Struct Span 

pub struct Span {
    pub span_id: String,
    pub file_path: String,
    pub byte_start: usize,
    pub byte_end: usize,
    pub start_line: usize,
    pub start_col: usize,
    pub end_line: usize,
    pub end_col: usize,
    pub context: Option<SpanContext>,
    pub semantics: Option<SpanSemantics>,
    pub relationships: Option<SpanRelationships>,
    pub checksums: Option<SpanChecksums>,
}

Span in source code (byte + line/column)

Represents a half-open range [start, end) where:

• byte_start is inclusive (first byte INCLUDED)
• byte_end is exclusive (first byte NOT included)

All offsets are UTF-8 byte positions. Lines are 1-indexed for user-friendliness. Columns are 0-indexed byte offsets within each line.

Examples

Creating a span and extracting text:

use magellan::output::command::Span;

let source = "fn main() { println!(\"Hello\"); }";
let span = Span::new(
    "main.rs".into(),  // file_path
    3,   // byte_start (points to 'm')
    7,   // byte_end (points to '(')
    1,   // start_line (1-indexed)
    3,   // start_col (byte offset in line)
    1,   // end_line
    7,   // end_col
);

// Extract text using the span
let text = source.get(span.byte_start..span.byte_end).unwrap();
assert_eq!(text, "main");

Safety

Always use .get() for UTF-8 safe slicing:

// SAFE: Returns Option<&str>, None if out of bounds
let text = source.get(span.byte_start..span.byte_end);

// UNSAFE: Can panic on invalid UTF-8 boundaries
// let text = &source[span.byte_start..span.byte_end];

Serialization

Span implements Serialize and Deserialize for JSON output. All fields are public and included in serialization.

Fields

span_id: String

Stable span ID (SHA-256 hash of file_path:byte_start:byte_end)

This ID is deterministic and platform-independent. See Span::generate_id for the algorithm details.

file_path: String

File path (absolute or root-relative)

Use consistent paths for stable IDs. The path is included in the span ID hash, so different representations of the same file (e.g., ./main.rs vs main.rs) produce different IDs.

byte_start: usize

Byte range start (inclusive, first byte INCLUDED)

UTF-8 byte offset from the start of the file.

byte_end: usize

Byte range end (exclusive, first byte NOT included)

UTF-8 byte offset. The span covers [byte_start, byte_end). Length is byte_end - byte_start.

start_line: usize

Start line (1-indexed)

Line number where the span starts, counting from 1. Matches editor line numbers.

start_col: usize

Start column (0-indexed, byte-based)

Byte offset within start_line where the span begins. This is a byte offset, not a character offset.

end_line: usize

End line (1-indexed)

Line number where the span ends.

end_col: usize

End column (0-indexed, byte-based)

Byte offset within end_line where the span ends (exclusive).

context: Option<SpanContext>

Context lines around the span

semantics: Option<SpanSemantics>

Semantic information (kind, language) - grouped in a single struct

relationships: Option<SpanRelationships>

Relationship information (callers, callees, imports, exports)

checksums: Option<SpanChecksums>

Checksums for content verification

Implementations

impl Span

pub fn generate_id( file_path: &str, byte_start: usize, byte_end: usize, ) -> String

Generate a stable span ID from (file_path, byte_start, byte_end)

Uses SHA-256 for platform-independent, deterministic span IDs.

Algorithm

The hash is computed from: file_path + ":" + byte_start + ":" + byte_end The first 8 bytes (64 bits) of the hash are formatted as 16 hex characters.

Properties

This ensures span IDs are:

• Deterministic: same inputs always produce the same ID
• Platform-independent: SHA-256 produces consistent results across architectures
• Collision-resistant: 64-bit space with good distribution

Stability

The span ID format is part of Magellan’s stable API contract. IDs generated by this function will remain consistent across versions.

Examples

use magellan::output::command::Span;

let id1 = Span::generate_id("main.rs", 10, 20);
let id2 = Span::generate_id("main.rs", 10, 20);
let id3 = Span::generate_id("main.rs", 10, 21);

assert_eq!(id1, id2);  // Same inputs = same ID
assert_ne!(id1, id3);  // Different inputs = different ID
assert_eq!(id1.len(), 16);  // Always 16 hex characters

pub fn new( file_path: String, byte_start: usize, byte_end: usize, start_line: usize, start_col: usize, end_line: usize, end_col: usize, ) -> Self

Create a new Span from component parts

Constructs a Span with a stable span_id automatically generated using Span::generate_id.

Parameters

• file_path: Path to the source file (absolute or root-relative)
• byte_start: UTF-8 byte offset where the span starts (inclusive)
• byte_end: UTF-8 byte offset where the span ends (exclusive)
• start_line: Line number where the span starts (1-indexed)
• start_col: Byte offset within start_line where the span starts (0-indexed)
• end_line: Line number where the span ends (1-indexed)
• end_col: Byte offset within end_line where the span ends (0-indexed, exclusive)

Half-Open Convention

The span uses half-open range semantics [byte_start, byte_end):

• byte_start is inclusive (first byte included)
• byte_end is exclusive (first byte NOT included)

Examples

use magellan::output::command::Span;

let span = Span::new(
    "main.rs".into(),  // file_path
    3,   // byte_start (inclusive)
    7,   // byte_end (exclusive)
    1,   // start_line (1-indexed)
    3,   // start_col (byte offset, 0-indexed)
    1,   // end_line
    7,   // end_col (byte offset, 0-indexed)
);

assert_eq!(span.byte_end - span.byte_start, 4);  // Length
assert_eq!(span.span_id.len(), 16);  // Stable ID

pub fn with_context(self, context: SpanContext) -> Self

Set context on the span

pub fn with_semantics(self, semantics: SpanSemantics) -> Self

Set semantic information on the span

pub fn with_semantics_from(self, kind: String, language: String) -> Self

Set semantic information from kind and language strings

pub fn with_relationships(self, relationships: SpanRelationships) -> Self

Set relationships on the span

pub fn with_checksums(self, checksums: SpanChecksums) -> Self

Set checksums on the span

Trait Implementations

impl Clone for Span

fn clone(&self) -> Span

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Span

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Span

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for Span

impl PartialEq for Span

fn eq(&self, other: &Span) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Span

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Span