///|
/// 1-based source location span used in TOON diagnostics.
#derive(Eq, @debug.Debug)
pub(all) struct Span {
  line : Int32
  column : Int32
  length : Int32
}

///|
/// Constructs a `Span` (clamping `line`, `column`, and `length` to `>= 1`
/// unless `line == 0` indicates an unattached line).
pub fn Span::at(line : Int32, column : Int32, length~ : Int32 = 1) -> Span {
  let safe_line = if line < 0 { 0 } else { line }
  let safe_col = if column < 1 { 1 } else { column }
  let safe_len = if length < 1 { 1 } else { length }
  { line: safe_line, column: safe_col, length: safe_len, }
}

///|
/// Machine-matchable error classification for TOON decoding failures.
#derive(Eq, @debug.Debug)
pub(all) enum ErrorKind {
  InvalidUtf8
  InvalidIndentation
  BlankLineInScope
  MalformedHeader
  HeaderDelimiterMismatch
  UnexpectedContent
  NumberOutOfRange
  MissingColon
  UnterminatedString
  InvalidEscape
  InvalidSurrogate
  TrailingCharacters
  CountMismatch
  WidthMismatch
  DuplicateKey
  DuplicateField
  DepthJump
  OverIndentation
  KeylessHeaderMisuse
  InvalidOption
}

///|
/// Returns a stable diagnostic error code string (e.g. `E_HEADER`).
pub fn ErrorKind::code(self : ErrorKind) -> String {
  match self {
    InvalidUtf8 => "E_UTF8"
    InvalidIndentation => "E_INDENT"
    BlankLineInScope => "E_BLANK"
    MalformedHeader => "E_HEADER"
    HeaderDelimiterMismatch => "E_HEADER_DELIM"
    UnexpectedContent => "E_UNEXPECTED"
    NumberOutOfRange => "E_NUMBER"
    MissingColon => "E_COLON"
    UnterminatedString => "E_STRING"
    InvalidEscape => "E_ESCAPE"
    InvalidSurrogate => "E_SURROGATE"
    TrailingCharacters => "E_TRAILING"
    CountMismatch => "E_COUNT"
    WidthMismatch => "E_WIDTH"
    DuplicateKey => "E_DUP_KEY"
    DuplicateField => "E_DUP_FIELD"
    DepthJump => "E_DEPTH"
    OverIndentation => "E_OVER_INDENT"
    KeylessHeaderMisuse => "E_KEYLESS"
    InvalidOption => "E_OPTION"
  }
}

///|
/// Structured TOON decode error carrying diagnostic kind, human message,
/// 1-based line/column span, and optional offending source line.
#derive(Eq, @debug.Debug)
pub(all) suberror DecodeError {
  DecodeError(
    kind~ : ErrorKind,
    message~ : String,
    span~ : Span,
    source_line~ : String?,
  )
}

///|
/// Constructs a `DecodeError` with optional span and source line context.
pub fn DecodeError::new(
  kind~ : ErrorKind,
  message~ : String,
  span~ : Span = Span::at(0, 1, length=1),
  source_line~ : String? = None,
) -> DecodeError {
  DecodeError(kind~, message~, span~, source_line~)
}

///|
/// Returns a copy of this `DecodeError` bound to a specific 1-based line and
/// optional source line, adjusting column by `col_offset` if desired.
pub fn DecodeError::at_line(
  self : DecodeError,
  line : Int32,
  source_line~ : String? = None,
  col_offset~ : Int32 = 0,
) -> DecodeError {
  match self {
    DecodeError(kind~, message~, span~, source_line=existing_src) => {
      let next_col = if span.column + col_offset < 1 {
        1
      } else {
        span.column + col_offset
      }
      let next_src = match source_line {
        Some(_) => source_line
        None => existing_src
      }
      DecodeError(
        kind~,
        message~,
        span=Span::at(line, next_col, length=span.length),
        source_line=next_src,
      )
    }
  }
}

///|
/// Renders the error as a multi-line human-readable diagnostic with source line
/// and `^` caret underline (visualizing `\t` as `→`).
pub fn DecodeError::format(self : DecodeError) -> String {
  match self {
    DecodeError(kind~, message~, span~, source_line~) => {
      let code = kind.code()
      let sb = StringBuilder()
      if span.line > 0 {
        sb.write_string(
          "DecodeError[\{code}] at line \{span.line}, column \{span.column}: \{message}",
        )
      } else {
        sb.write_string("DecodeError[\{code}]: \{message}")
      }
      match source_line {
        None => ()
        Some(raw) => {
          let line_str = if span.line > 0 { span.line.to_string() } else { "?" }
          let prefix = "  \{line_str} | "
          let blank_gutter = String::make(prefix.length() - 2, ' ') + "| "
          let visible = StringBuilder()
          for ch in raw {
            if ch == '\t' {
              visible.write_char('→')
            } else if ch == '\r' {
              ()
            } else {
              visible.write_char(ch)
            }
          }
          let visible_str = visible.to_string()
          let vis_len = visible_str.char_length()
          let col0 = if span.column <= 1 {
            0
          } else if span.column - 1 > vis_len {
            vis_len
          } else {
            span.column - 1
          }
          let caret_len = if span.length < 1 { 1 } else { span.length }
          sb.write_char('\n')
          sb.write_string(prefix)
          sb.write_string(visible_str)
          sb.write_char('\n')
          sb.write_string(blank_gutter)
          sb.write_string(String::make(col0, ' '))
          sb.write_string(String::make(caret_len, '^'))
        }
      }
      sb.to_string()
    }
  }
}

///|
/// Structured TOON encode error (e.g. invalid options or unpaired UTF-16 surrogates).
#derive(Eq, @debug.Debug)
pub(all) suberror EncodeError {
  EncodeError(message~ : String, path~ : String?)
}

///|
/// Formats an `EncodeError` for display.
pub fn EncodeError::format(self : EncodeError) -> String {
  match self {
    EncodeError(message~, path=None) => "EncodeError: \{message}"
    EncodeError(message~, path=Some(p)) => "EncodeError at \{p}: \{message}"
  }
}