sif_parser/

parse.rs

// SIF Core v1 — Document parser.
//
// Built from the Structured Interchange Format specification,
// following the collected ABNF in Appendix A.
//
// This module provides `parse()` for full-document parsing and
// individual parsing functions for types, schemas, and values.

use crate::error::{err, ErrorKind, Result};
use crate::types::*;
use std::collections::HashMap;

// ── Public API ──────────────────────────────────────────────────────

/// Parse a complete SIF document from a string.
pub fn parse(input: &str) -> Result<Document> {
    let mut parser = DocumentParser::new(input);
    parser.parse()
}

/// Parse a `#schema` field-definition list (without the `#schema` prefix).
pub fn parse_schema(input: &str) -> Result<Schema> {
    parse_schema_str(input, 0)
}

/// Parse a SIF type string (e.g., `"str[]?"`, `"enum(a,b,c)"`).
pub fn parse_type_str(input: &str) -> Result<Type> {
    let (ty, rest) = parse_type(input)?;
    if !rest.is_empty() {
        return Err(err(
            ErrorKind::InvalidType,
            0,
            format!("trailing characters after type: {:?}", rest),
        ));
    }
    Ok(ty)
}

/// Parse a single field value according to a declared type.
pub fn parse_typed_value(input: &str, ty: &Type) -> Result<Value> {
    parse_value_typed(input, ty, 0)
}

/// Parse a single field value using untyped disambiguation (§9.2).
pub fn parse_untyped_value(input: &str) -> Value {
    parse_value_untyped(input)
}

/// Parse inline semantic annotations in a string (§16.3).
pub fn parse_inline_annotations(input: &str) -> Vec<Span> {
    parse_spans(input)
}

/// Parse an inline SIF expression (§21): `sif::#schema ...::record::record`.
pub fn parse_inline_sif(input: &str) -> Result<Document> {
    if !input.starts_with("sif::") {
        return Err(err(ErrorKind::InvalidHeader, 0, "inline SIF must start with 'sif::'"));
    }
    let rest = &input[5..];
    let parts: Vec<&str> = rest.split("::").collect();
    // Reconstruct as a normal SIF document with newlines.
    let mut doc_str = String::from("#!sif v1\n");
    for part in parts {
        doc_str.push_str(part);
        doc_str.push('\n');
    }
    parse(&doc_str)
}

// ── Type Parsing (§7, Appendix A) ───────────────────────────────────

/// Parse a type from the start of `input`, returning (Type, remaining).
///
/// ABNF:
///   type       = base-type *type-suffix
///   base-type  = scalar-type / "map"
///   type-suffix = "[]" / "?"
fn parse_type(input: &str) -> Result<(Type, &str)> {
    let (base, mut rest) = parse_base_type(input)?;

    // Apply suffixes left-to-right: str[]? → Nullable(Array(Str))
    let mut ty = base;
    loop {
        if rest.starts_with("[]") {
            ty = Type::Array(Box::new(ty));
            rest = &rest[2..];
        } else if rest.starts_with('?') {
            ty = Type::Nullable(Box::new(ty));
            rest = &rest[1..];
        } else {
            break;
        }
    }
    Ok((ty, rest))
}

fn parse_base_type(input: &str) -> Result<(Type, &str)> {
    // Try each keyword, longest match first for datetime vs date.
    let keywords: &[(&str, Type)] = &[
        ("datetime", Type::DateTime),
        ("duration", Type::Duration),
        ("float", Type::Float),
        ("bool", Type::Bool),
        ("uint", Type::Uint),
        ("int", Type::Int),
        ("str", Type::Str),
        ("date", Type::Date),
        ("bytes", Type::Bytes),
        ("null", Type::Null),
        ("any", Type::Any),
        ("map", Type::Map),
    ];

    for (kw, ty) in keywords {
        if input.starts_with(kw) {
            let after = &input[kw.len()..];
            // Make sure it's a full token (not e.g. "integer")
            if after.is_empty()
                || after.starts_with("[]")
                || after.starts_with('?')
                || after.starts_with(':')
                || after.starts_with('|')
                || after.starts_with(' ')
                || after.starts_with(',')
                || after.starts_with(')')
            {
                return Ok((ty.clone(), after));
            }
        }
    }

    // Try enum(a,b,c)
    if input.starts_with("enum(") {
        let after_paren = &input[5..];
        let close = after_paren
            .find(')')
            .ok_or_else(|| err(ErrorKind::InvalidType, 0, "unterminated enum type"))?;
        let variants_str = &after_paren[..close];
        let variants: Vec<String> = variants_str.split(',').map(|s| s.trim().to_string()).collect();
        if variants.iter().any(|v| v.is_empty()) {
            return Err(err(ErrorKind::InvalidType, 0, "empty enum variant"));
        }
        // Validate variant characters: ALPHA / DIGIT / "_" / "-"
        for v in &variants {
            if !v.chars().all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-') {
                return Err(err(
                    ErrorKind::InvalidType,
                    0,
                    format!("invalid enum variant: {:?}", v),
                ));
            }
        }
        return Ok((Type::Enum(variants), &after_paren[close + 1..]));
    }

    Err(err(
        ErrorKind::InvalidType,
        0,
        format!("unrecognized type at: {:?}", &input[..input.len().min(20)]),
    ))
}

// ── Schema Parsing (§8) ─────────────────────────────────────────────

/// Parse the field definitions from a schema directive body.
///
/// `line_num` is used for error reporting.
pub(crate) fn parse_schema_str(input: &str, line_num: usize) -> Result<Schema> {
    let input = input.trim();
    if input.is_empty() {
        return Err(err(ErrorKind::InvalidSchema, line_num, "empty schema"));
    }

    let mut fields = Vec::new();
    let mut seen_names: HashMap<&str, usize> = HashMap::new();

    // Split on spaces, but we need to handle enum(...) which contains no spaces
    // so a simple split works here per the ABNF.
    let tokens = split_schema_fields(input);

    for token in &tokens {
        let field = parse_field_def(token, line_num)?;
        if let Some(prev) = seen_names.get(field.name.as_str()) {
            return Err(err(
                ErrorKind::DuplicateField,
                line_num,
                format!(
                    "duplicate field name {:?} (first at position {})",
                    field.name,
                    prev + 1
                ),
            ));
        }
        seen_names.insert(unsafe {
            // SAFETY: field.name is allocated and lives as long as `fields`
            // We only use this for duplicate detection within this function.
            std::mem::transmute::<&str, &str>(field.name.as_str())
        }, fields.len());
        fields.push(field);
    }

    Ok(Schema { fields })
}

/// Split schema field definitions on spaces, respecting enum(...) parentheses
/// and quoted modifier values.
fn split_schema_fields(input: &str) -> Vec<&str> {
    let mut fields = Vec::new();
    let mut start = 0;
    let mut paren_depth = 0;
    let mut in_quotes = false;

    for (i, c) in input.char_indices() {
        match c {
            '(' if !in_quotes => paren_depth += 1,
            ')' if !in_quotes => {
                if paren_depth > 0 {
                    paren_depth -= 1;
                }
            }
            '"' => in_quotes = !in_quotes,
            ' ' if paren_depth == 0 && !in_quotes => {
                let token = input[start..i].trim();
                if !token.is_empty() {
                    fields.push(token);
                }
                start = i + 1;
            }
            _ => {}
        }
    }
    let last = input[start..].trim();
    if !last.is_empty() {
        fields.push(last);
    }
    fields
}

/// Parse a single field definition per §8 / §8.5 / §8.6:
///
///   field-def = [ "∅" ] field-name ":" type [ ":" semantic ]
///               [ "|" modifier *( "," modifier ) ]
fn parse_field_def(input: &str, line_num: usize) -> Result<FieldDef> {
    let mut s = input;

    // §8.5: Check for deprecated prefix ∅ (U+2205)
    let deprecated = if s.starts_with('∅') {
        s = &s['∅'.len_utf8()..];
        true
    } else {
        false
    };

    // §8.6: Split on | for modifiers (at most one split, outside parens)
    let (left, modifiers_str) = split_on_pipe(s);

    // Parse modifiers
    let modifiers = if let Some(mods) = modifiers_str {
        parse_modifiers(mods, line_num)?
    } else {
        Vec::new()
    };

    // Split left side on : for name:type[:semantic]
    // But we must be careful with enum(a,b,c) which doesn't contain ':'
    // at the outer level, and with type suffixes like str[]?
    let parts = split_field_parts(left);

    if parts.len() < 2 {
        return Err(err(
            ErrorKind::InvalidSchema,
            line_num,
            format!("field definition must have at least name:type, got {:?}", input),
        ));
    }

    let name = parts[0].to_string();
    // Validate field name: 1-63 chars of ALPHA / DIGIT / "_" / "."
    if name.is_empty() || name.len() > 63 {
        return Err(err(
            ErrorKind::InvalidSchema,
            line_num,
            format!("field name must be 1-63 characters, got {:?}", name),
        ));
    }
    if !name
        .chars()
        .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '.')
    {
        return Err(err(
            ErrorKind::InvalidSchema,
            line_num,
            format!("invalid field name characters: {:?}", name),
        ));
    }

    let (field_type, _) = parse_type(parts[1])
        .map_err(|e| err(ErrorKind::InvalidType, line_num, e.message))?;

    let semantic = if parts.len() >= 3 && !parts[2].is_empty() {
        Some(parts[2].to_string())
    } else {
        None
    };

    Ok(FieldDef {
        name,
        field_type,
        semantic,
        deprecated,
        modifiers,
    })
}

/// Split on `|` at the top level (not inside parens or quotes).
fn split_on_pipe(input: &str) -> (&str, Option<&str>) {
    let mut paren_depth = 0;
    let mut in_quotes = false;
    for (i, c) in input.char_indices() {
        match c {
            '(' if !in_quotes => paren_depth += 1,
            ')' if !in_quotes => {
                if paren_depth > 0 {
                    paren_depth -= 1;
                }
            }
            '"' => in_quotes = !in_quotes,
            '|' if paren_depth == 0 && !in_quotes => {
                return (&input[..i], Some(&input[i + 1..]));
            }
            _ => {}
        }
    }
    (input, None)
}

/// Split a field's name:type[:semantic] on `:`, but skip `:` inside
/// `enum(...)` and after the type portion.
///
/// Strategy: split on `:` up to 3 parts, where the second part (type)
/// may contain colons if it's an enum (but enum uses commas, not colons,
/// so this is safe). The only colon in a type is if someone writes
/// something unexpected — we handle it by greedily consuming the type.
fn split_field_parts(input: &str) -> Vec<&str> {
    let mut parts = Vec::new();
    let mut paren_depth = 0;

    // Find first colon outside parens = name boundary
    let mut first_colon = None;
    for (i, c) in input.char_indices() {
        match c {
            '(' => paren_depth += 1,
            ')' => {
                if paren_depth > 0 {
                    paren_depth -= 1;
                }
            }
            ':' if paren_depth == 0 => {
                first_colon = Some(i);
                break;
            }
            _ => {}
        }
    }

    let Some(fc) = first_colon else {
        return vec![input];
    };

    parts.push(&input[..fc]);
    let after_name = &input[fc + 1..];

    // Now parse the type, which may contain parens (enum).
    // Find the next colon outside parens = semantic boundary.
    paren_depth = 0;
    let mut second_colon = None;
    for (i, c) in after_name.char_indices() {
        match c {
            '(' => paren_depth += 1,
            ')' => {
                if paren_depth > 0 {
                    paren_depth -= 1;
                }
            }
            ':' if paren_depth == 0 => {
                second_colon = Some(i);
                break;
            }
            _ => {}
        }
    }

    if let Some(sc) = second_colon {
        parts.push(&after_name[..sc]);
        parts.push(&after_name[sc + 1..]);
    } else {
        parts.push(after_name);
    }

    parts
}

/// Parse comma-separated modifiers: `mod1,mod2=val,mod3="quoted"`.
fn parse_modifiers(input: &str, line_num: usize) -> Result<Vec<Modifier>> {
    let mut modifiers = Vec::new();
    if input.is_empty() {
        return Ok(modifiers);
    }

    // Split on commas, respecting quotes
    let tokens = split_on_comma_unquoted(input);

    for token in tokens {
        let token = token.trim();
        if token.is_empty() {
            continue;
        }
        if let Some(eq_pos) = token.find('=') {
            let name = token[..eq_pos].to_string();
            let raw_value = &token[eq_pos + 1..];
            let value = if raw_value.starts_with('"') {
                // Unquote
                parse_quoted_string_value(raw_value)
                    .map_err(|e| err(ErrorKind::InvalidSchema, line_num, e.message))?
            } else {
                raw_value.to_string()
            };
            modifiers.push(Modifier {
                name,
                value: Some(value),
            });
        } else {
            modifiers.push(Modifier {
                name: token.to_string(),
                value: None,
            });
        }
    }
    Ok(modifiers)
}

fn split_on_comma_unquoted(input: &str) -> Vec<&str> {
    let mut parts = Vec::new();
    let mut start = 0;
    let mut in_quotes = false;

    for (i, c) in input.char_indices() {
        match c {
            '"' => in_quotes = !in_quotes,
            ',' if !in_quotes => {
                parts.push(&input[start..i]);
                start = i + 1;
            }
            _ => {}
        }
    }
    parts.push(&input[start..]);
    parts
}

// ── Value Parsing (§9–§15) ──────────────────────────────────────────

/// Parse a value according to a known type (§9.1).
fn parse_value_typed(input: &str, ty: &Type, line_num: usize) -> Result<Value> {
    // §10: Null literal.
    // Spec says `_` is only valid for nullable types, but real-world SIF
    // files commonly use `_` in non-nullable fields to mean "no value."
    // We accept it leniently for all types.
    if input == "_" {
        return Ok(Value::Null);
    }

    // §9.3: Empty field
    if input.is_empty() {
        return match ty {
            Type::Str | Type::Any => Ok(Value::Str(String::new())),
            Type::Nullable(_) => Ok(Value::Null),
            _ => Err(err(
                ErrorKind::TypeMismatch,
                line_num,
                format!("empty field for non-nullable type {}", ty),
            )),
        };
    }

    match ty {
        Type::Bool => parse_bool(input, line_num),
        Type::Int => parse_int(input, line_num),
        Type::Uint => parse_uint(input, line_num),
        Type::Float => parse_float(input, line_num),
        Type::Str => Ok(Value::Str(parse_string_value(input)?)),
        Type::Date => {
            let s = parse_string_value(input)?;
            validate_date(&s, line_num)?;
            Ok(Value::Date(s))
        }
        Type::DateTime => {
            let s = parse_string_value(input)?;
            validate_datetime(&s, line_num)?;
            Ok(Value::DateTime(s))
        }
        Type::Duration => {
            let s = parse_string_value(input)?;
            validate_duration(&s, line_num)?;
            Ok(Value::Duration(s))
        }
        Type::Bytes => {
            let s = parse_string_value(input)?;
            let bytes = base64_decode(&s)
                .map_err(|e| err(ErrorKind::TypeMismatch, line_num, e))?;
            Ok(Value::Bytes(bytes))
        }
        Type::Enum(variants) => {
            let s = parse_string_value(input)?;
            if !variants.contains(&s) {
                return Err(err(
                    ErrorKind::TypeMismatch,
                    line_num,
                    format!("value {:?} not in enum({})", s, variants.join(",")),
                ));
            }
            Ok(Value::Enum(s))
        }
        Type::Null => {
            // Only `_` is valid for the null type, handled above.
            Err(err(
                ErrorKind::TypeMismatch,
                line_num,
                format!("expected null ('_'), got {:?}", input),
            ))
        }
        Type::Any => Ok(parse_value_untyped(input)),
        Type::Map => parse_map_value(input, line_num),
        Type::Array(elem_ty) => parse_array_value(input, elem_ty, line_num),
        Type::Nullable(inner) => parse_value_typed(input, inner, line_num),
    }
}

/// Parse a value using untyped disambiguation rules (§9.2).
fn parse_value_untyped(input: &str) -> Value {
    // 1. null
    if input == "_" {
        return Value::Null;
    }
    // 2. bool (only T/F in untyped context)
    if input == "T" {
        return Value::Bool(true);
    }
    if input == "F" {
        return Value::Bool(false);
    }
    // 3. array
    if input.starts_with('[') && input.ends_with(']') {
        if let Ok(v) = parse_array_value(input, &Type::Any, 0) {
            return v;
        }
    }
    // 4. map
    if input.starts_with('{') && input.ends_with('}') {
        if let Ok(v) = parse_map_value(input, 0) {
            return v;
        }
    }
    // 5. signed integer
    if is_int_literal(input) {
        if let Ok(n) = input.parse::<i64>() {
            return Value::Int(n);
        }
    }
    // 6. float (contains '.')
    if input.contains('.') {
        if let Ok(n) = input.parse::<f64>() {
            if n.is_finite() {
                return Value::Float(n);
            }
        }
    }
    // 7. string
    if input.starts_with('"') {
        if let Ok(s) = parse_quoted_string_value(input) {
            return Value::Str(s);
        }
    }
    Value::Str(input.to_string())
}

fn is_int_literal(s: &str) -> bool {
    let s = s.strip_prefix('-').unwrap_or(s);
    !s.is_empty() && s.chars().all(|c| c.is_ascii_digit())
}

fn parse_bool(input: &str, line_num: usize) -> Result<Value> {
    match input {
        "T" | "true" | "TRUE" | "True" | "1" => Ok(Value::Bool(true)),
        "F" | "false" | "FALSE" | "False" | "0" => Ok(Value::Bool(false)),
        _ => Err(err(
            ErrorKind::TypeMismatch,
            line_num,
            format!("invalid bool: {:?}", input),
        )),
    }
}

fn parse_int(input: &str, line_num: usize) -> Result<Value> {
    input
        .parse::<i64>()
        .map(Value::Int)
        .map_err(|_| err(ErrorKind::TypeMismatch, line_num, format!("invalid int: {:?}", input)))
}

fn parse_uint(input: &str, line_num: usize) -> Result<Value> {
    if input.starts_with('-') {
        return Err(err(
            ErrorKind::TypeMismatch,
            line_num,
            format!("negative value for uint: {:?}", input),
        ));
    }
    input
        .parse::<u64>()
        .map(Value::Uint)
        .map_err(|_| err(ErrorKind::TypeMismatch, line_num, format!("invalid uint: {:?}", input)))
}

fn parse_float(input: &str, line_num: usize) -> Result<Value> {
    let n: f64 = input
        .parse()
        .map_err(|_| err(ErrorKind::TypeMismatch, line_num, format!("invalid float: {:?}", input)))?;
    if !n.is_finite() {
        return Err(err(
            ErrorKind::TypeMismatch,
            line_num,
            "NaN/Inf not allowed in SIF floats",
        ));
    }
    Ok(Value::Float(n))
}

// ── String Parsing (§11) ────────────────────────────────────────────

/// Parse a string value — unquoted passthrough or quoted with escaping.
fn parse_string_value(input: &str) -> Result<String> {
    if input.starts_with('"') {
        parse_quoted_string_value(input)
    } else {
        Ok(input.to_string())
    }
}

/// Parse a quoted string: `"content with \"escapes\""`.
fn parse_quoted_string_value(input: &str) -> Result<String> {
    if !input.starts_with('"') {
        return Err(err(ErrorKind::InvalidString, 0, "expected opening quote"));
    }

    let inner = &input[1..];
    let mut result = String::new();
    let mut chars = inner.chars();
    loop {
        match chars.next() {
            None => {
                return Err(err(ErrorKind::InvalidString, 0, "unterminated quoted string"));
            }
            Some('"') => {
                // End of string — verify nothing follows except whitespace
                // (in record context, the rest of the field ends at the tab)
                break;
            }
            Some('\\') => {
                match chars.next() {
                    Some('n') => result.push('\n'),
                    Some('t') => result.push('\t'),
                    Some('\\') => result.push('\\'),
                    Some('"') => result.push('"'),
                    Some(c) => {
                        return Err(err(
                            ErrorKind::InvalidString,
                            0,
                            format!("invalid escape sequence: \\{}", c),
                        ));
                    }
                    None => {
                        return Err(err(
                            ErrorKind::InvalidString,
                            0,
                            "unterminated escape sequence",
                        ));
                    }
                }
            }
            Some(c) => result.push(c),
        }
    }
    Ok(result)
}

// ── Array Parsing (§14) ─────────────────────────────────────────────

fn parse_array_value(input: &str, elem_ty: &Type, line_num: usize) -> Result<Value> {
    if !input.starts_with('[') || !input.ends_with(']') {
        return Err(err(
            ErrorKind::InvalidArray,
            line_num,
            format!("expected array literal, got {:?}", input),
        ));
    }
    let inner = &input[1..input.len() - 1];
    if inner.is_empty() {
        return Ok(Value::Array(Vec::new()));
    }

    let elements = split_array_elements(inner);
    let mut values = Vec::with_capacity(elements.len());
    for elem in &elements {
        let v = parse_value_typed(elem, elem_ty, line_num)?;
        values.push(v);
    }
    Ok(Value::Array(values))
}

/// Split array elements on commas, respecting nested brackets and quotes.
fn split_array_elements(input: &str) -> Vec<&str> {
    let mut elements = Vec::new();
    let mut start = 0;
    let mut bracket_depth = 0;
    let mut brace_depth = 0;
    let mut in_quotes = false;

    for (i, c) in input.char_indices() {
        match c {
            '"' => in_quotes = !in_quotes,
            '[' if !in_quotes => bracket_depth += 1,
            ']' if !in_quotes => bracket_depth -= 1,
            '{' if !in_quotes => brace_depth += 1,
            '}' if !in_quotes => brace_depth -= 1,
            ',' if !in_quotes && bracket_depth == 0 && brace_depth == 0 => {
                elements.push(&input[start..i]);
                start = i + 1;
            }
            _ => {}
        }
    }
    elements.push(&input[start..]);
    elements
}

// ── Map Parsing (§15) ───────────────────────────────────────────────

fn parse_map_value(input: &str, line_num: usize) -> Result<Value> {
    if !input.starts_with('{') || !input.ends_with('}') {
        return Err(err(
            ErrorKind::InvalidMap,
            line_num,
            format!("expected map literal, got {:?}", input),
        ));
    }
    let inner = &input[1..input.len() - 1];
    if inner.is_empty() {
        return Ok(Value::Map(Vec::new()));
    }

    let entries_str = split_array_elements(inner); // reuse comma splitter
    let mut entries = Vec::with_capacity(entries_str.len());
    for entry in &entries_str {
        let colon_pos = entry.find(':').ok_or_else(|| {
            err(
                ErrorKind::InvalidMap,
                line_num,
                format!("map entry missing ':' separator: {:?}", entry),
            )
        })?;
        let key = &entry[..colon_pos];
        // Validate key: 1*(ALPHA / DIGIT / "_")
        if key.is_empty() || !key.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') {
            return Err(err(
                ErrorKind::InvalidMap,
                line_num,
                format!("invalid map key: {:?}", key),
            ));
        }
        let val_str = &entry[colon_pos + 1..];
        let val = parse_value_untyped(val_str);
        entries.push((key.to_string(), val));
    }
    Ok(Value::Map(entries))
}

// ── Date/Time Validation (§7.3) ─────────────────────────────────────

fn validate_date(s: &str, line_num: usize) -> Result<()> {
    // YYYY-MM-DD
    if s.len() < 10 {
        return Err(err(ErrorKind::TypeMismatch, line_num, format!("invalid date: {:?}", s)));
    }
    let bytes = s.as_bytes();
    if bytes[4] != b'-' || bytes[7] != b'-' {
        return Err(err(ErrorKind::TypeMismatch, line_num, format!("invalid date format: {:?}", s)));
    }
    // Basic digit check
    for &i in &[0, 1, 2, 3, 5, 6, 8, 9] {
        if !bytes[i].is_ascii_digit() {
            return Err(err(ErrorKind::TypeMismatch, line_num, format!("invalid date: {:?}", s)));
        }
    }
    Ok(())
}

fn validate_datetime(s: &str, line_num: usize) -> Result<()> {
    // Must start with a valid date
    if s.len() < 10 {
        return Err(err(ErrorKind::TypeMismatch, line_num, format!("invalid datetime: {:?}", s)));
    }
    validate_date(&s[..10], line_num)?;
    // After the date there should be 'T' followed by time
    if s.len() > 10 && s.as_bytes()[10] != b'T' {
        return Err(err(
            ErrorKind::TypeMismatch,
            line_num,
            format!("invalid datetime separator (expected 'T'): {:?}", s),
        ));
    }
    Ok(())
}

fn validate_duration(s: &str, line_num: usize) -> Result<()> {
    if !s.starts_with('P') {
        return Err(err(
            ErrorKind::TypeMismatch,
            line_num,
            format!("duration must start with 'P': {:?}", s),
        ));
    }
    Ok(())
}

// ── Base64 Decoding ─────────────────────────────────────────────────

fn base64_decode(input: &str) -> std::result::Result<Vec<u8>, String> {
    fn char_val(c: u8) -> std::result::Result<u8, String> {
        match c {
            b'A'..=b'Z' => Ok(c - b'A'),
            b'a'..=b'z' => Ok(c - b'a' + 26),
            b'0'..=b'9' => Ok(c - b'0' + 52),
            b'+' => Ok(62),
            b'/' => Ok(63),
            _ => Err(format!("invalid base64 character: {:?}", c as char)),
        }
    }

    let input = input.trim_end_matches('=');
    let bytes = input.as_bytes();
    let mut out = Vec::with_capacity(bytes.len() * 3 / 4);

    for chunk in bytes.chunks(4) {
        let a = char_val(chunk[0])?;
        let b = if chunk.len() > 1 { char_val(chunk[1])? } else { 0 };
        let c = if chunk.len() > 2 { char_val(chunk[2])? } else { 0 };
        let d = if chunk.len() > 3 { char_val(chunk[3])? } else { 0 };

        let n = (a as u32) << 18 | (b as u32) << 12 | (c as u32) << 6 | d as u32;

        out.push((n >> 16) as u8);
        if chunk.len() > 2 {
            out.push((n >> 8) as u8);
        }
        if chunk.len() > 3 {
            out.push(n as u8);
        }
    }
    Ok(out)
}

// ── Header Parsing (§6) ─────────────────────────────────────────────

fn parse_header(line: &str, line_num: usize) -> Result<Header> {
    let s = line.trim_end();
    if !s.starts_with("#!sif ") {
        return Err(err(ErrorKind::InvalidHeader, line_num, "header must start with '#!sif '"));
    }
    let rest = &s[6..]; // after "#!sif "

    // Tokenize respecting quoted attribute values
    let tokens = tokenize_header(rest);
    if tokens.is_empty() {
        return Err(err(ErrorKind::InvalidHeader, line_num, "missing version"));
    }

    // First token must be vN
    let version_str = &tokens[0];
    if !version_str.starts_with('v') {
        return Err(err(
            ErrorKind::InvalidHeader,
            line_num,
            format!("expected version like 'v1', got {:?}", version_str),
        ));
    }
    let version: u32 = version_str[1..]
        .parse()
        .map_err(|_| err(ErrorKind::InvalidHeader, line_num, "invalid version number"))?;

    if version != 1 {
        return Err(err(
            ErrorKind::UnsupportedVersion,
            line_num,
            format!("unsupported SIF version {}, only v1 is supported", version),
        ));
    }

    // Remaining tokens are key=value attributes
    let mut attributes = HashMap::new();
    for token in &tokens[1..] {
        if let Some(eq_pos) = token.find('=') {
            let key = &token[..eq_pos];
            let raw_val = &token[eq_pos + 1..];
            let val = if raw_val.starts_with('"') {
                parse_quoted_string_value(raw_val)
                    .map_err(|e| err(ErrorKind::InvalidHeader, line_num, e.message))?
            } else {
                raw_val.to_string()
            };
            attributes.insert(key.to_string(), val);
        } else {
            return Err(err(
                ErrorKind::InvalidHeader,
                line_num,
                format!("invalid header attribute (missing '='): {:?}", token),
            ));
        }
    }

    Ok(Header { version, attributes })
}

/// Tokenize header content on spaces, respecting quoted values.
fn tokenize_header(input: &str) -> Vec<&str> {
    let mut tokens = Vec::new();
    let mut start = 0;
    let mut in_quotes = false;
    let bytes = input.as_bytes();

    let mut i = 0;
    while i < bytes.len() {
        match bytes[i] {
            b'"' => in_quotes = !in_quotes,
            b' ' if !in_quotes => {
                let tok = &input[start..i];
                if !tok.is_empty() {
                    tokens.push(tok);
                }
                start = i + 1;
            }
            _ => {}
        }
        i += 1;
    }
    let last = &input[start..];
    if !last.is_empty() {
        tokens.push(last);
    }
    tokens
}

// ── Directive Parsing (§18) ─────────────────────────────────────────

fn parse_directive(line: &str, line_num: usize) -> Result<Option<Directive>> {
    let s = line.trim_end();

    if s == "#recall schema" {
        return Ok(Some(Directive::Recall));
    }

    if let Some(rest) = s.strip_prefix("#context ") {
        return Ok(Some(Directive::Context(rest.to_string())));
    }
    if let Some(rest) = s.strip_prefix("#source ") {
        return Ok(Some(Directive::Source(rest.to_string())));
    }
    if let Some(rest) = s.strip_prefix("#license ") {
        return Ok(Some(Directive::License(rest.to_string())));
    }
    if let Some(rest) = s.strip_prefix("#error ") {
        return Ok(Some(Directive::Error(rest.to_string())));
    }
    if let Some(rest) = s.strip_prefix("#filter ") {
        return Ok(Some(Directive::Filter(rest.to_string())));
    }
    if let Some(rest) = s.strip_prefix("#sort ") {
        let parts: Vec<&str> = rest.splitn(2, ' ').collect();
        let field = parts[0].to_string();
        let direction = if parts.len() > 1 {
            match parts[1] {
                "asc" => SortDirection::Asc,
                "desc" => SortDirection::Desc,
                _ => {
                    return Err(err(
                        ErrorKind::InvalidDirective,
                        line_num,
                        format!("invalid sort direction: {:?}", parts[1]),
                    ));
                }
            }
        } else {
            SortDirection::Asc
        };
        return Ok(Some(Directive::Sort { field, direction }));
    }
    if let Some(rest) = s.strip_prefix("#limit ") {
        let n: u64 = rest
            .trim()
            .parse()
            .map_err(|_| err(ErrorKind::InvalidDirective, line_num, "invalid limit value"))?;
        return Ok(Some(Directive::Limit(n)));
    }
    if let Some(rest) = s.strip_prefix("#truncated") {
        let attrs_str = rest.trim();
        let attrs = parse_header_attrs(attrs_str, line_num)?;
        return Ok(Some(Directive::Truncated(attrs)));
    }
    if let Some(rest) = s.strip_prefix("#relation ") {
        return parse_relation(rest, line_num).map(Some);
    }

    // §18.8: Unknown directives — skip without error.
    if s.starts_with('#') {
        let name_end = s[1..]
            .find(' ')
            .map(|i| i + 1)
            .unwrap_or(s.len());
        let name = &s[1..name_end];
        let content = if name_end < s.len() {
            s[name_end + 1..].to_string()
        } else {
            String::new()
        };
        return Ok(Some(Directive::Unknown {
            name: name.to_string(),
            content,
        }));
    }

    Ok(None)
}

fn parse_header_attrs(input: &str, line_num: usize) -> Result<Vec<(String, String)>> {
    let mut attrs = Vec::new();
    if input.is_empty() {
        return Ok(attrs);
    }
    let tokens = tokenize_header(input);
    for token in tokens {
        if let Some(eq_pos) = token.find('=') {
            let key = token[..eq_pos].to_string();
            let raw_val = &token[eq_pos + 1..];
            let val = if raw_val.starts_with('"') {
                parse_quoted_string_value(raw_val)
                    .map_err(|e| err(ErrorKind::InvalidDirective, line_num, e.message))?
            } else {
                raw_val.to_string()
            };
            attrs.push((key, val));
        }
    }
    Ok(attrs)
}

fn parse_relation(input: &str, line_num: usize) -> Result<Directive> {
    // field_ref SP "->" SP field_ref
    let parts: Vec<&str> = input.splitn(3, " -> ").collect();
    if parts.len() != 2 {
        // Try splitting on " -> " with different whitespace
        let arrow = input.find("->").ok_or_else(|| {
            err(
                ErrorKind::InvalidDirective,
                line_num,
                "relation directive missing '->'",
            )
        })?;
        let from_str = input[..arrow].trim();
        let to_str = input[arrow + 2..].trim();
        return Ok(Directive::Relation {
            from: parse_field_ref(from_str),
            to: parse_field_ref(to_str),
        });
    }
    Ok(Directive::Relation {
        from: parse_field_ref(parts[0].trim()),
        to: parse_field_ref(parts[1].trim()),
    })
}

fn parse_field_ref(input: &str) -> FieldRef {
    if input.starts_with('§') {
        let rest = &input['§'.len_utf8()..];
        if let Some(dot_pos) = rest.find('.') {
            return FieldRef {
                section: Some(rest[..dot_pos].to_string()),
                field: rest[dot_pos + 1..].to_string(),
            };
        }
    }
    FieldRef {
        section: None,
        field: input.to_string(),
    }
}

// ── Block Parsing (§19) ─────────────────────────────────────────────

fn parse_block_start(line: &str, line_num: usize) -> Result<(BlockType, Vec<(String, String)>)> {
    let s = line.trim_end();
    let rest = s
        .strip_prefix("#block ")
        .ok_or_else(|| err(ErrorKind::InvalidBlock, line_num, "expected '#block <type>'"))?;

    let tokens = tokenize_header(rest);
    if tokens.is_empty() {
        return Err(err(ErrorKind::InvalidBlock, line_num, "missing block type"));
    }

    let block_type = match tokens[0] {
        "code" => BlockType::Code,
        "text" => BlockType::Text,
        "diff" => BlockType::Diff,
        "raw" => BlockType::Raw,
        "template" => BlockType::Template,
        other => {
            return Err(err(
                ErrorKind::InvalidBlock,
                line_num,
                format!("unknown block type: {:?}", other),
            ));
        }
    };

    let mut attrs = Vec::new();
    for token in &tokens[1..] {
        if let Some(eq_pos) = token.find('=') {
            let key = token[..eq_pos].to_string();
            let raw_val = &token[eq_pos + 1..];
            let val = if raw_val.starts_with('"') {
                parse_quoted_string_value(raw_val)
                    .map_err(|e| err(ErrorKind::InvalidBlock, line_num, e.message))?
            } else {
                raw_val.to_string()
            };
            attrs.push((key, val));
        }
    }

    Ok((block_type, attrs))
}

// ── Inline Annotations (§16.3) ──────────────────────────────────────

fn parse_spans(input: &str) -> Vec<Span> {
    let mut spans = Vec::new();
    let mut pos = 0;
    let bytes = input.as_bytes();
    let len = bytes.len();

    while pos < len {
        // Look for @semantic{ pattern
        if bytes[pos] == b'@' && pos + 1 < len {
            // Find the semantic name (up to '{')
            let sem_start = pos + 1;
            let mut brace_pos = None;
            let mut j = sem_start;
            while j < len {
                if bytes[j] == b'{' {
                    brace_pos = Some(j);
                    break;
                }
                if !bytes[j].is_ascii_alphanumeric() && bytes[j] != b'_' {
                    break;
                }
                j += 1;
            }

            if let Some(bp) = brace_pos {
                if bp > sem_start {
                    // Flush preceding text
                    if pos > spans_text_end(&spans, input) {
                        let text_start = spans_text_end(&spans, input);
                        if text_start < pos {
                            // Already handled
                        }
                    }
                    // Parse the annotation
                    let semantic = &input[sem_start..bp];
                    let content_start = bp + 1;
                    // Find matching closing brace, respecting nesting
                    if let Some(content_end) = find_matching_brace(input, content_start) {
                        let content = &input[content_start..content_end];
                        let children = parse_spans(content);
                        spans.push(Span::Annotated {
                            semantic: semantic.to_string(),
                            children,
                        });
                        pos = content_end + 1;
                        continue;
                    }
                }
            }
        }

        // Accumulate plain text
        let text_start = pos;
        while pos < len {
            if bytes[pos] == b'@' && pos + 1 < len && bytes[pos + 1].is_ascii_alphabetic() {
                // Check if this is actually an annotation
                let mut k = pos + 1;
                while k < len && (bytes[k].is_ascii_alphanumeric() || bytes[k] == b'_') {
                    k += 1;
                }
                if k < len && bytes[k] == b'{' {
                    break;
                }
            }
            pos += 1;
        }
        if pos > text_start {
            spans.push(Span::Text(input[text_start..pos].to_string()));
        }
    }

    spans
}

fn spans_text_end(_spans: &[Span], _input: &str) -> usize {
    0
}

fn find_matching_brace(input: &str, start: usize) -> Option<usize> {
    let bytes = input.as_bytes();
    let mut depth = 1;
    let mut i = start;
    while i < bytes.len() {
        match bytes[i] {
            b'{' => depth += 1,
            b'}' => {
                depth -= 1;
                if depth == 0 {
                    return Some(i);
                }
            }
            _ => {}
        }
        i += 1;
    }
    None
}

// ── Record Parsing ──────────────────────────────────────────────────

fn parse_record_line(
    line: &str,
    schema: &Schema,
    line_num: usize,
) -> Result<Record> {
    let s = line.trim_end_matches('\n').trim_end_matches('\r');

    // Check for CDC prefix (§ from SIF Streaming spec)
    let (cdc_op, data) = if s.starts_with('Δ') {
        (CdcOp::Update, &s['Δ'.len_utf8()..])
    } else if s.starts_with('∅') {
        (CdcOp::Delete, &s['∅'.len_utf8()..])
    } else {
        (CdcOp::Insert, s)
    };

    // Split on tabs
    let raw_fields: Vec<&str> = data.split('\t').collect();
    let field_count = schema.field_count();

    let mut values = Vec::with_capacity(field_count);

    // CDC delete tombstones contain only :id field values.
    // Non-id fields are implicitly null.
    if cdc_op == CdcOp::Delete {
        let id_fields: Vec<usize> = schema
            .fields
            .iter()
            .enumerate()
            .filter(|(_, f)| f.semantic.as_deref() == Some("id"))
            .map(|(i, _)| i)
            .collect();

        let mut id_idx = 0;
        for (i, field_def) in schema.fields.iter().enumerate() {
            if id_fields.contains(&i) {
                let raw = if id_idx < raw_fields.len() {
                    raw_fields[id_idx]
                } else {
                    ""
                };
                id_idx += 1;
                let value = parse_value_typed(raw, &field_def.field_type, line_num)?;
                values.push(value);
            } else {
                values.push(Value::Null);
            }
        }
    } else {
        for (i, field_def) in schema.fields.iter().enumerate() {
            let raw = if i < raw_fields.len() {
                raw_fields[i]
            } else {
                // §9: Too few fields — treat missing trailing fields as null
                ""
            };

            let value = parse_value_typed(raw, &field_def.field_type, line_num)?;
            values.push(value);
        }
    }

    // §9: Too many fields — we parse them but could warn.
    // For now, silently accept extra fields (lenient mode).

    Ok(Record { values, cdc_op })
}

// ── Document Parser ─────────────────────────────────────────────────

struct DocumentParser<'a> {
    lines: Vec<&'a str>,
    pos: usize,
}

impl<'a> DocumentParser<'a> {
    fn new(input: &'a str) -> Self {
        let lines: Vec<&str> = input.lines().collect();
        Self { lines, pos: 0 }
    }

    fn line_num(&self) -> usize {
        self.pos + 1
    }

    fn peek(&self) -> Option<&'a str> {
        self.lines.get(self.pos).copied()
    }

    fn advance(&mut self) -> Option<&'a str> {
        let line = self.lines.get(self.pos).copied();
        if line.is_some() {
            self.pos += 1;
        }
        line
    }

    fn parse(&mut self) -> Result<Document> {
        // §4: Handle BOM
        if let Some(first) = self.peek() {
            if first.starts_with('\u{FEFF}') {
                // Strip BOM, continue with warning (non-fatal).
                // We modify the line in place conceptually.
                let stripped = &first[3..]; // UTF-8 BOM is 3 bytes
                self.lines[0] = stripped;
            }
        }

        // §6: Parse header
        let header_line = self
            .advance()
            .ok_or_else(|| err(ErrorKind::UnexpectedEof, 1, "empty document"))?;
        let header = parse_header(header_line, 1)?;

        // Parse sections
        let mut sections = Vec::new();
        let mut current = self.new_section();

        while let Some(line) = self.peek() {
            let trimmed = line.trim_end();

            // Skip empty lines (§5.1)
            if trimmed.is_empty() {
                self.advance();
                continue;
            }

            // §5.3: Lines beginning with #! after header — silently ignore
            if trimmed.starts_with("#!") {
                self.advance();
                continue;
            }

            // Section break (§17)
            if trimmed == "---" {
                self.advance();
                sections.push(current);
                current = self.new_section();
                continue;
            }

            // Section identifier (§17.3)
            if trimmed.starts_with('§') {
                self.advance();
                let id = &trimmed['§'.len_utf8()..];
                current.id = Some(id.to_string());
                continue;
            }

            // Block (§19)
            if trimmed.starts_with("#block ") {
                let block = self.parse_block()?;
                current.blocks.push(block);
                continue;
            }

            // Template (§22)
            if trimmed.starts_with("#template ") {
                let template = self.parse_template()?;
                current.templates.push(template);
                continue;
            }

            // Block end outside block — error
            if trimmed == "#/block" {
                return Err(err(
                    ErrorKind::InvalidBlock,
                    self.line_num(),
                    "unexpected #/block outside block",
                ));
            }

            // Schema (§8)
            if trimmed.starts_with("#schema ") {
                self.advance();
                let schema_body = &trimmed[8..];
                let schema = parse_schema_str(schema_body, self.line_num() - 1)?;
                current.schema = Some(schema);
                continue;
            }

            // Recall (§18.10) — no-op
            if trimmed == "#recall schema" {
                self.advance();
                current.directives.push(Directive::Recall);
                continue;
            }

            // Other directives (§18)
            if trimmed.starts_with('#') {
                self.advance();
                if let Some(directive) = parse_directive(trimmed, self.line_num() - 1)? {
                    current.directives.push(directive);
                }
                continue;
            }

            // Record (§9)
            if let Some(ref schema) = current.schema {
                self.advance();
                let schema_clone = schema.clone();
                let record = parse_record_line(trimmed, &schema_clone, self.line_num() - 1)?;
                current.records.push(record);
            } else {
                // §3: A section without a schema MUST NOT contain records.
                return Err(err(
                    ErrorKind::RecordWithoutSchema,
                    self.line_num(),
                    "record found before any #schema directive in this section",
                ));
            }
        }

        sections.push(current);
        Ok(Document { header, sections })
    }

    fn new_section(&self) -> Section {
        Section {
            id: None,
            directives: Vec::new(),
            schema: None,
            records: Vec::new(),
            blocks: Vec::new(),
            templates: Vec::new(),
        }
    }

    fn parse_block(&mut self) -> Result<Block> {
        let start_line = self.line_num();
        let start = self
            .advance()
            .ok_or_else(|| err(ErrorKind::UnexpectedEof, start_line, "expected block start"))?;
        let (block_type, attributes) = parse_block_start(start, start_line)?;

        let mut content = String::new();
        loop {
            let line = self
                .advance()
                .ok_or_else(|| err(ErrorKind::InvalidBlock, start_line, "unterminated block"))?;
            if line.trim_end() == "#/block" {
                break;
            }
            if !content.is_empty() {
                content.push('\n');
            }
            content.push_str(line);
        }

        Ok(Block {
            block_type,
            attributes,
            content,
        })
    }

    fn parse_template(&mut self) -> Result<Template> {
        let start_line = self.line_num();
        let start = self
            .advance()
            .ok_or_else(|| err(ErrorKind::UnexpectedEof, start_line, "expected template start"))?;

        let name = start
            .trim_end()
            .strip_prefix("#template ")
            .ok_or_else(|| err(ErrorKind::InvalidTemplate, start_line, "expected '#template <name>'"))?
            .trim()
            .to_string();

        if name.is_empty() {
            return Err(err(
                ErrorKind::InvalidTemplate,
                start_line,
                "template name cannot be empty",
            ));
        }

        let mut body = String::new();
        loop {
            let line = self.advance().ok_or_else(|| {
                err(
                    ErrorKind::InvalidTemplate,
                    start_line,
                    "unterminated template",
                )
            })?;
            if line.trim_end() == "#/template" {
                break;
            }
            if !body.is_empty() {
                body.push('\n');
            }
            body.push_str(line);
        }

        Ok(Template { name, body })
    }
}

// ── Functions exposed to sibling modules (reader.rs) ────────────────

pub(crate) fn parse_header_public(line: &str, line_num: usize) -> Result<Header> {
    parse_header(line, line_num)
}

pub(crate) fn parse_directive_public(
    line: &str,
    line_num: usize,
) -> Result<Option<Directive>> {
    parse_directive(line, line_num)
}

pub(crate) fn parse_record_public(
    line: &str,
    schema: &Schema,
    line_num: usize,
) -> Result<Record> {
    parse_record_line(line, schema, line_num)
}

// ── Tests ───────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    // -- Header tests --

    #[test]
    fn test_minimal_header() {
        let doc = parse("#!sif v1\n").unwrap();
        assert_eq!(doc.header.version, 1);
        assert!(doc.header.attributes.is_empty());
    }

    #[test]
    fn test_header_with_attrs() {
        let doc = parse("#!sif v1 origin=sif-cli/1.0.0 created=2026-03-08T06:50:51Z\n").unwrap();
        assert_eq!(doc.header.attributes["origin"], "sif-cli/1.0.0");
        assert_eq!(doc.header.attributes["created"], "2026-03-08T06:50:51Z");
    }

    #[test]
    fn test_header_quoted_attr() {
        let doc = parse("#!sif v1 context=\"GitHub issue export for serde-rs/serde\"\n").unwrap();
        assert_eq!(
            doc.header.attributes["context"],
            "GitHub issue export for serde-rs/serde"
        );
    }

    #[test]
    fn test_unsupported_version() {
        assert!(parse("#!sif v2\n").is_err());
    }

    // -- Type tests --

    #[test]
    fn test_scalar_types() {
        assert_eq!(parse_type_str("bool").unwrap(), Type::Bool);
        assert_eq!(parse_type_str("int").unwrap(), Type::Int);
        assert_eq!(parse_type_str("uint").unwrap(), Type::Uint);
        assert_eq!(parse_type_str("float").unwrap(), Type::Float);
        assert_eq!(parse_type_str("str").unwrap(), Type::Str);
        assert_eq!(parse_type_str("date").unwrap(), Type::Date);
        assert_eq!(parse_type_str("datetime").unwrap(), Type::DateTime);
        assert_eq!(parse_type_str("duration").unwrap(), Type::Duration);
        assert_eq!(parse_type_str("bytes").unwrap(), Type::Bytes);
        assert_eq!(parse_type_str("null").unwrap(), Type::Null);
        assert_eq!(parse_type_str("any").unwrap(), Type::Any);
        assert_eq!(parse_type_str("map").unwrap(), Type::Map);
    }

    #[test]
    fn test_compound_types() {
        assert_eq!(
            parse_type_str("str[]").unwrap(),
            Type::Array(Box::new(Type::Str))
        );
        assert_eq!(
            parse_type_str("int?").unwrap(),
            Type::Nullable(Box::new(Type::Int))
        );
        // str[]? → Nullable(Array(Str))
        assert_eq!(
            parse_type_str("str[]?").unwrap(),
            Type::Nullable(Box::new(Type::Array(Box::new(Type::Str))))
        );
        // int?[] → Array(Nullable(Int))
        assert_eq!(
            parse_type_str("int?[]").unwrap(),
            Type::Array(Box::new(Type::Nullable(Box::new(Type::Int))))
        );
    }

    #[test]
    fn test_enum_type() {
        assert_eq!(
            parse_type_str("enum(open,closed,merged)").unwrap(),
            Type::Enum(vec![
                "open".to_string(),
                "closed".to_string(),
                "merged".to_string()
            ])
        );
    }

    // -- Schema tests --

    #[test]
    fn test_basic_schema() {
        let s = parse_schema("id:uint:id title:str status:enum(open,closed)").unwrap();
        assert_eq!(s.fields.len(), 3);
        assert_eq!(s.fields[0].name, "id");
        assert_eq!(s.fields[0].field_type, Type::Uint);
        assert_eq!(s.fields[0].semantic.as_deref(), Some("id"));
        assert_eq!(s.fields[1].name, "title");
        assert_eq!(s.fields[1].field_type, Type::Str);
        assert!(s.fields[1].semantic.is_none());
        assert_eq!(s.fields[2].name, "status");
        assert_eq!(
            s.fields[2].field_type,
            Type::Enum(vec!["open".to_string(), "closed".to_string()])
        );
    }

    #[test]
    fn test_deprecated_field() {
        let s = parse_schema("id:uint:id ∅old_email:str email:str:email").unwrap();
        assert!(!s.fields[0].deprecated);
        assert!(s.fields[1].deprecated);
        assert_eq!(s.fields[1].name, "old_email");
        assert!(!s.fields[2].deprecated);
    }

    #[test]
    fn test_field_modifiers() {
        let s =
            parse_schema("stock:uint:metric|agg=sum,align=right price:float|unit=usd,fmt=currency")
                .unwrap();
        assert_eq!(s.fields[0].modifiers.len(), 2);
        assert_eq!(s.fields[0].modifiers[0].name, "agg");
        assert_eq!(s.fields[0].modifiers[0].value.as_deref(), Some("sum"));
        assert_eq!(s.fields[0].modifiers[1].name, "align");
        assert_eq!(s.fields[0].modifiers[1].value.as_deref(), Some("right"));
    }

    // -- Value tests --

    #[test]
    fn test_untyped_disambiguation() {
        assert_eq!(parse_untyped_value("_"), Value::Null);
        assert_eq!(parse_untyped_value("T"), Value::Bool(true));
        assert_eq!(parse_untyped_value("F"), Value::Bool(false));
        assert_eq!(parse_untyped_value("42"), Value::Int(42));
        assert_eq!(parse_untyped_value("-7"), Value::Int(-7));
        assert_eq!(parse_untyped_value("3.14"), Value::Float(3.14));
        assert_eq!(
            parse_untyped_value("hello"),
            Value::Str("hello".to_string())
        );
        // "true" is NOT bool in untyped context — only T/F
        assert_eq!(
            parse_untyped_value("true"),
            Value::Str("true".to_string())
        );
    }

    #[test]
    fn test_typed_values() {
        assert_eq!(
            parse_typed_value("T", &Type::Bool).unwrap(),
            Value::Bool(true)
        );
        assert_eq!(
            parse_typed_value("true", &Type::Bool).unwrap(),
            Value::Bool(true)
        );
        assert_eq!(
            parse_typed_value("42", &Type::Int).unwrap(),
            Value::Int(42)
        );
        assert_eq!(
            parse_typed_value("42", &Type::Uint).unwrap(),
            Value::Uint(42)
        );
        assert!(parse_typed_value("-1", &Type::Uint).is_err());
        assert_eq!(
            parse_typed_value("3.14", &Type::Float).unwrap(),
            Value::Float(3.14)
        );
    }

    #[test]
    fn test_nullable() {
        assert_eq!(
            parse_typed_value("_", &Type::Nullable(Box::new(Type::Int))).unwrap(),
            Value::Null
        );
        assert_eq!(
            parse_typed_value("42", &Type::Nullable(Box::new(Type::Int))).unwrap(),
            Value::Int(42)
        );
        // Lenient: _ accepted for non-nullable types too (real-world compat)
        assert_eq!(parse_typed_value("_", &Type::Int).unwrap(), Value::Null);
    }

    #[test]
    fn test_enum_validation() {
        let ty = Type::Enum(vec!["open".to_string(), "closed".to_string()]);
        assert_eq!(
            parse_typed_value("open", &ty).unwrap(),
            Value::Enum("open".to_string())
        );
        assert!(parse_typed_value("invalid", &ty).is_err());
    }

    #[test]
    fn test_array_value() {
        assert_eq!(
            parse_typed_value("[1,2,3]", &Type::Array(Box::new(Type::Int))).unwrap(),
            Value::Array(vec![Value::Int(1), Value::Int(2), Value::Int(3)])
        );
        assert_eq!(
            parse_typed_value("[]", &Type::Array(Box::new(Type::Str))).unwrap(),
            Value::Array(Vec::new())
        );
    }

    #[test]
    fn test_map_value() {
        assert_eq!(
            parse_typed_value("{name:alice,age:30}", &Type::Map).unwrap(),
            Value::Map(vec![
                ("name".to_string(), Value::Str("alice".to_string())),
                ("age".to_string(), Value::Int(30)),
            ])
        );
    }

    #[test]
    fn test_string_escaping() {
        assert_eq!(
            parse_typed_value(r#""has a \t tab""#, &Type::Str).unwrap(),
            Value::Str("has a \t tab".to_string())
        );
        assert_eq!(
            parse_typed_value(r#""line\nbreak""#, &Type::Str).unwrap(),
            Value::Str("line\nbreak".to_string())
        );
        assert_eq!(
            parse_typed_value(r#""she said \"hello\"""#, &Type::Str).unwrap(),
            Value::Str("she said \"hello\"".to_string())
        );
    }

    // -- Full document tests --

    #[test]
    fn test_typical_document() {
        let input = "\
#!sif v1
#context Repository issues
#schema id:uint:id title:str status:enum(open,closed) created:datetime
1\tFix flatten in tagged enums\topen\t2026-01-15T10:30:00Z
2\tCow borrows owned\tclosed\t2026-01-16T08:00:00Z
";
        let doc = parse(input).unwrap();
        assert_eq!(doc.sections.len(), 1);
        let sec = &doc.sections[0];
        assert_eq!(sec.records.len(), 2);
        assert_eq!(sec.records[0].values[0], Value::Uint(1));
        assert_eq!(
            sec.records[0].values[1],
            Value::Str("Fix flatten in tagged enums".to_string())
        );
        assert_eq!(
            sec.records[0].values[2],
            Value::Enum("open".to_string())
        );
    }

    #[test]
    fn test_multi_section() {
        let input = "\
#!sif v1
#context Repos
#schema name:str stars:uint
serde\t8947
---
#context Issues
#schema id:uint:id title:str
1\tFlatten bug
";
        let doc = parse(input).unwrap();
        assert_eq!(doc.sections.len(), 2);
        assert_eq!(doc.sections[0].records.len(), 1);
        assert_eq!(doc.sections[1].records.len(), 1);
    }

    #[test]
    fn test_section_identifiers() {
        let input = "\
#!sif v1
§repos
#schema name:str stars:uint
serde\t8947
---
§issues
#schema id:uint:id title:str
1\tFlatten bug
";
        let doc = parse(input).unwrap();
        assert_eq!(doc.sections[0].id.as_deref(), Some("repos"));
        assert_eq!(doc.sections[1].id.as_deref(), Some("issues"));
        assert!(doc.section_by_id("repos").is_some());
    }

    #[test]
    fn test_blocks() {
        let input = "\
#!sif v1
#block code language=rust
fn main() {
    println!(\"hello\");
}
#/block
";
        let doc = parse(input).unwrap();
        assert_eq!(doc.sections[0].blocks.len(), 1);
        let block = &doc.sections[0].blocks[0];
        assert_eq!(block.block_type, BlockType::Code);
        assert_eq!(block.attributes, vec![("language".to_string(), "rust".to_string())]);
        assert!(block.content.contains("fn main()"));
    }

    #[test]
    fn test_templates() {
        let input = "\
#!sif v1
#schema id:uint name:str
#template greeting
Hello, @{name}! Your ID is @{id}.
#/template
1\talice
";
        let doc = parse(input).unwrap();
        assert_eq!(doc.sections[0].templates.len(), 1);
        let tmpl = &doc.sections[0].templates[0];
        assert_eq!(tmpl.name, "greeting");

        let schema = doc.sections[0].schema.as_ref().unwrap();
        let record = &doc.sections[0].records[0];
        let rendered = tmpl.render(record, schema);
        assert_eq!(rendered, "Hello, alice! Your ID is 1.");
    }

    #[test]
    fn test_recall_is_noop() {
        let input = "\
#!sif v1
#schema id:uint name:str
1\talice
#recall schema
2\tbob
";
        let doc = parse(input).unwrap();
        assert_eq!(doc.sections[0].records.len(), 2);
    }

    #[test]
    fn test_inline_annotations() {
        let spans = parse_inline_annotations(
            "Error in @path{src/main.rs} at @line_number{42}: @error{expected usize}",
        );
        // Should produce: Text, Annotated(path), Text, Annotated(line_number), Text, Annotated(error)
        assert_eq!(spans.len(), 6);
        match &spans[1] {
            Span::Annotated { semantic, children } => {
                assert_eq!(semantic, "path");
                assert_eq!(children.len(), 1);
            }
            _ => panic!("expected annotated span"),
        }
    }

    #[test]
    fn test_inline_sif() {
        let doc =
            parse_inline_sif("sif::#schema id:uint name:str::1\talice::2\tbob").unwrap();
        assert_eq!(doc.sections[0].records.len(), 2);
    }

    #[test]
    fn test_cdc_prefixes() {
        let schema = parse_schema("id:uint:id name:str").unwrap();
        let rec = parse_record_line("Δ1\tupdated", &schema, 1).unwrap();
        assert_eq!(rec.cdc_op, CdcOp::Update);
        assert_eq!(rec.values[0], Value::Uint(1));

        let rec = parse_record_line("∅2\tdeleted", &schema, 1).unwrap();
        assert_eq!(rec.cdc_op, CdcOp::Delete);
    }

    #[test]
    fn test_relation_directive() {
        let input = "\
#!sif v1
#schema id:uint:id parent_id:uint?:ref name:str
#relation parent_id -> id
1\t_\tRoot
2\t1\tChild
";
        let doc = parse(input).unwrap();
        let directives = &doc.sections[0].directives;
        assert!(directives.iter().any(|d| matches!(d, Directive::Relation { .. })));
    }

    #[test]
    fn test_cross_section_reference() {
        let input = "\
#!sif v1
§auth
#schema name:str:id type:str
jwt\tbearer
---
§endpoints
#schema path:str:path auth:str?
/users\t§auth.jwt
";
        let doc = parse(input).unwrap();
        let rec = &doc.sections[1].records[0];
        // The reference is parsed as a plain string value
        assert_eq!(rec.values[1], Value::Str("§auth.jwt".to_string()));
    }

    #[test]
    fn test_date_types() {
        let schema = parse_schema("d:date dt:datetime dur:duration").unwrap();
        let rec = parse_record_line("2026-03-14\t2026-03-14T10:30:00Z\tPT2H30M", &schema, 1).unwrap();
        assert_eq!(rec.values[0], Value::Date("2026-03-14".to_string()));
        assert_eq!(rec.values[1], Value::DateTime("2026-03-14T10:30:00Z".to_string()));
        assert_eq!(rec.values[2], Value::Duration("PT2H30M".to_string()));
    }

    #[test]
    fn test_empty_document() {
        let doc = parse("#!sif v1\n").unwrap();
        assert_eq!(doc.sections.len(), 1);
        assert!(doc.sections[0].records.is_empty());
    }

    #[test]
    fn test_nullable_array() {
        let schema = parse_schema("tags:str[]?").unwrap();
        assert_eq!(
            schema.fields[0].field_type,
            Type::Nullable(Box::new(Type::Array(Box::new(Type::Str))))
        );
        let rec = parse_record_line("_", &schema, 1).unwrap();
        assert_eq!(rec.values[0], Value::Null);
        let rec = parse_record_line("[a,b]", &schema, 1).unwrap();
        assert_eq!(
            rec.values[0],
            Value::Array(vec![
                Value::Str("a".to_string()),
                Value::Str("b".to_string()),
            ])
        );
    }

    #[test]
    fn test_missing_trailing_fields() {
        let schema = parse_schema("a:str b:str? c:str?").unwrap();
        let rec = parse_record_line("hello", &schema, 1).unwrap();
        assert_eq!(rec.values.len(), 3);
        assert_eq!(rec.values[0], Value::Str("hello".to_string()));
        assert_eq!(rec.values[1], Value::Null);
        assert_eq!(rec.values[2], Value::Null);
    }

    #[test]
    fn test_unknown_directive_ignored() {
        let input = "\
#!sif v1
#custom_directive some value here
#schema id:uint
1
";
        let doc = parse(input).unwrap();
        assert!(doc.sections[0]
            .directives
            .iter()
            .any(|d| matches!(d, Directive::Unknown { name, .. } if name == "custom_directive")));
        assert_eq!(doc.sections[0].records.len(), 1);
    }
}