cel_parser/

error.rs

//! Parse error type with message and source span for CEL.
//!
//! Uses a [`SourceSpan`] (line/column only) so errors are `Send + Sync` and can
//! be used from async execution. Use [`SourceSpan::from_proc_macro2`] to extract
//! location from a `proc_macro2::Span` when building errors in the parser.

use annotate_snippets::{AnnotationKind, Group, Level, Renderer, Snippet};
use proc_macro2::LineColumn;
use std::str::FromStr;

/// Source region as start/end line and column.
///
/// Uses [`proc_macro2::LineColumn`] for positions (1-based line, 0-based column).
/// This type is `Send + Sync`. Build it from a `proc_macro2::Span` via
/// [`SourceSpan::from_proc_macro2`] when you have one (e.g. in the parser).
///
/// # Examples
/// See [`Self::new`] and [`Self::to_byte_range`].
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct SourceSpan {
    /// Start position (inclusive).
    pub start: LineColumn,
    /// End position (exclusive; one past the last character, matching `proc_macro2::Span::end()`).
    pub end: LineColumn,
}

impl Default for SourceSpan {
    /// Returns an empty region at line one, column zero.
    fn default() -> Self {
        SourceSpan {
            start: LineColumn { line: 1, column: 0 },
            end: LineColumn { line: 1, column: 0 },
        }
    }
}

impl SourceSpan {
    /// Builds a span from raw line/column values.
    ///
    /// Lines are 1-based, columns are 0-based (matching [`proc_macro2::LineColumn`]).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cel_parser::SourceSpan;
    ///
    /// let span = SourceSpan::new(1, 0, 1, 5);
    /// assert_eq!(span.start.line, 1);
    /// assert_eq!(span.end.column, 5);
    /// ```
    pub fn new(start_line: usize, start_column: usize, end_line: usize, end_column: usize) -> Self {
        SourceSpan {
            start: LineColumn {
                line: start_line,
                column: start_column,
            },
            end: LineColumn {
                line: end_line,
                column: end_column,
            },
        }
    }

    /// Extracts start/end line and column from a `proc_macro2::Span`.
    ///
    /// Use this when creating errors in the parser or other code that has a
    /// `proc_macro2::Span`; the result is `Send + Sync` and can be stored in
    /// [`CELError`] for use from async or other threads.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use proc_macro2::Span;
    /// use cel_parser::SourceSpan;
    ///
    /// let span = SourceSpan::from_proc_macro2(Span::call_site());
    /// assert_eq!(span.start.line, span.end.line);
    /// ```
    pub fn from_proc_macro2(span: proc_macro2::Span) -> Self {
        SourceSpan {
            start: span.start(),
            end: span.end(),
        }
    }

    /// Builds a span from two `proc_macro2::Span` values (start of `start`, end of `end`).
    ///
    /// Use this when an expression spans multiple tokens and you want a range span.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use proc_macro2::Span;
    /// use cel_parser::SourceSpan;
    ///
    /// let start = Span::call_site();
    /// let end = Span::call_site();
    /// let span = SourceSpan::from_proc_macro2_range(start, end);
    /// assert_eq!(span.start.line, span.end.line);
    /// ```
    pub fn from_proc_macro2_range(start: proc_macro2::Span, end: proc_macro2::Span) -> Self {
        SourceSpan {
            start: start.start(),
            end: end.end(),
        }
    }

    /// Converts this span (1-based lines, 0-based character columns) to a byte-offset range
    /// within `source`.
    ///
    /// - Precondition: `source` is the exact original text this span's line/column positions
    ///   were recorded against.
    /// - Precondition: `self.start.line >= 1` (spans use 1-based line numbers).
    /// - Precondition: `self.end` does not precede `self.start` (`self.end.line > self.start.line`,
    ///   or they're equal and `self.end.column >= self.start.column`).
    ///
    /// - Complexity: O(n) in the length of `source`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cel_parser::SourceSpan;
    ///
    /// let span = SourceSpan::new(1, 0, 1, 5);
    /// let range = span.to_byte_range("hello world");
    /// assert_eq!(&"hello world"[range], "hello");
    /// ```
    pub fn to_byte_range(&self, source: &str) -> std::ops::Range<usize> {
        span_to_byte_range(source, *self)
    }
}

/// A CEL parse error with a message and source location.
///
/// Uses a [`SourceSpan`] (line/column only) so the error is `Send + Sync` and
/// can be used from async execution or reported across thread boundaries.
///
/// # Examples
/// See [`Self::new`] and [`Self::format_rustc_style`].
#[derive(Clone, Debug)]
pub struct CELError {
    message: String,
    span: SourceSpan,
}

/// Converts a [`SourceSpan`] (1-based lines, 0-based character columns) to a byte-offset
/// range within `source`.
///
/// - Complexity: O(n) time and O(1) auxiliary space for n source bytes.
pub(crate) fn span_to_byte_range(source: &str, span: SourceSpan) -> std::ops::Range<usize> {
    debug_assert!(
        span.start.line >= 1,
        "`span.start.line` must be 1-based (≥ 1)"
    );
    debug_assert!(
        span.end.line > span.start.line
            || (span.end.line == span.start.line && span.end.column >= span.start.column),
        "`span.end` must not precede `span.start`"
    );
    let start_line_byte: usize = source
        .split_inclusive('\n')
        .take(span.start.line - 1)
        .map(str::len)
        .sum();
    let start_byte = start_line_byte
        + source[start_line_byte..]
            .chars()
            .take(span.start.column)
            .map(char::len_utf8)
            .sum::<usize>();
    let end_byte = if span.end.line == span.start.line {
        start_byte
            + source[start_byte..]
                .chars()
                .take(span.end.column - span.start.column)
                .map(char::len_utf8)
                .sum::<usize>()
    } else {
        let end_line_byte = start_byte
            + source[start_byte..]
                .split_inclusive('\n')
                .take(span.end.line - span.start.line)
                .map(str::len)
                .sum::<usize>();
        end_line_byte
            + source[end_line_byte..]
                .chars()
                .take(span.end.column)
                .map(char::len_utf8)
                .sum::<usize>()
    };
    debug_assert!(
        end_byte <= source.len(),
        "computed end_byte exceeds source.len()"
    );
    start_byte..end_byte
}

/// One labelled span in a multi-span diagnostic.
///
/// # Examples
/// See [`format_multi_span`].
#[derive(Clone, Debug)]
pub struct SpanLabel {
    /// The source region to underline.
    pub span: SourceSpan,
    /// The label printed beside the caret.
    pub label: String,
}

/// Renders `title` with several labelled annotations over `source_code`, the first as the
/// primary caret and the rest as secondary context, in rustc style.
///
/// - Precondition: `labels` is non-empty.
/// - Complexity: O(k * s + l) annotation work for k labels, s source bytes and l label bytes,
///   plus renderer layout; O(k + s + b) auxiliary/output space for b output bytes.
///
/// # Examples
///
/// ```rust
/// use annotate_snippets::Renderer;
/// use cel_parser::{SourceSpan, SpanLabel, format_multi_span};
///
/// let labels = vec![SpanLabel { span: SourceSpan::new(1, 0, 1, 1), label: "here".into() }];
/// let out = format_multi_span("oops", &labels, "x", "f.adm2", 1, &Renderer::plain());
/// assert!(out.contains("oops"));
/// ```
pub fn format_multi_span(
    title: &str,
    labels: &[SpanLabel],
    source_code: &str,
    filename: &str,
    start_line: u32,
    renderer: &Renderer,
) -> String {
    debug_assert!(!labels.is_empty(), "`labels` must be non-empty");
    let mut snippet = Snippet::source(source_code)
        .path(filename)
        .line_start(start_line as usize);
    for (i, l) in labels.iter().enumerate() {
        let range = span_to_byte_range(source_code, l.span);
        let kind = if i == 0 {
            AnnotationKind::Primary
        } else {
            AnnotationKind::Context
        };
        snippet = snippet.annotation(kind.span(range).label(l.label.as_str()));
    }
    let report = [Group::with_title(Level::ERROR.primary_title(title)).element(snippet)];
    renderer.render(&report)
}

/// Returns the closing delimiter character that pairs with opening bracket `open`.
///
/// - Precondition: `open` is one of `(`, `[`, `{`.
fn matching_close(open: char) -> char {
    match open {
        '(' => ')',
        '[' => ']',
        '{' => '}',
        _ => {
            debug_assert!(false, "`open` must be one of `(`, `[`, `{{`");
            open
        }
    }
}

/// Finds the innermost bracket delimiter still open at the point where an unmatched or
/// mismatched closing delimiter appears at `close_span` in `source`.
///
/// `close_span` is the first lex failure in `source`, so everything before it lexed as a
/// self-contained run of valid tokens: literals and comments already closed, and nested
/// bracket groups already balanced. The only way that prefix can itself fail to lex on its
/// own is an unclosed group, and `proc_macro2` reports the position of its innermost
/// still-open delimiter — exactly the opener `close_span`'s delimiter failed to match.
///
/// Returns `None` when the prefix lexes cleanly (no opener at all to match).
///
/// - Complexity: O(n) in `source`'s length (re-lexes the prefix before `close_span`).
///   Prefix lexing uses O(n) auxiliary space.
fn innermost_open_delimiter(
    source: &str,
    close_span: proc_macro2::Span,
) -> Option<(char, proc_macro2::Span)> {
    let close_start = span_to_byte_range(source, SourceSpan::from_proc_macro2(close_span)).start;
    let prefix_err = proc_macro2::TokenStream::from_str(&source[..close_start]).err()?;
    let open_span = prefix_err.span();
    let open_start = span_to_byte_range(source, SourceSpan::from_proc_macro2(open_span)).start;
    match source[open_start..].chars().next()? {
        ch @ ('(' | '[' | '{') => Some((ch, open_span)),
        _ => None,
    }
}

/// Classifies a lex failure by inspecting the character at `span`'s start in `source`.
///
/// Returns the message plus an optional secondary label: for a closing delimiter that
/// doesn't match (or has no) currently-open opener, the secondary points back at the
/// unmatched opener when one exists.
///
/// Returns `None` when the span doesn't resolve to a character (e.g. it points past the end of
/// `source`), so the caller can fall back to a generic message.
///
/// - Complexity: O(s) time and auxiliary space for s source bytes, including prefix re-lexing.
fn lex_failure_message(
    source: &str,
    span: proc_macro2::Span,
) -> Option<(String, Option<SpanLabel>)> {
    let byte_range = span_to_byte_range(source, SourceSpan::from_proc_macro2(span));
    let rest = &source[byte_range.start..];
    Some(match rest.chars().next()? {
        '(' => (
            "unclosed delimiter `(`: expected a matching `)`".to_string(),
            None,
        ),
        '[' => (
            "unclosed delimiter `[`: expected a matching `]`".to_string(),
            None,
        ),
        '{' => (
            "unclosed delimiter `{`: expected a matching `}`".to_string(),
            None,
        ),
        ch @ (')' | ']' | '}') => match innermost_open_delimiter(source, span) {
            Some((open_ch, open_span)) => (
                format!(
                    "mismatched closing delimiter: found `{ch}`, expected `{}`",
                    matching_close(open_ch)
                ),
                Some(SpanLabel {
                    span: SourceSpan::from_proc_macro2(open_span),
                    label: format!("unclosed delimiter `{open_ch}`"),
                }),
            ),
            None => (format!("unexpected closing delimiter `{ch}`"), None),
        },
        '"' => ("unterminated string literal".to_string(), None),
        '\'' => (
            "invalid or unterminated character literal".to_string(),
            None,
        ),
        '`' => ("invalid character `` ` ``".to_string(), None),
        '/' if rest.starts_with("/*") => ("unterminated block comment".to_string(), None),
        ch => (format!("invalid character `{ch}`"), None),
    })
}

impl CELError {
    /// Creates a new error with the given message and source span.
    ///
    /// - Complexity: O(m) time and space for m borrowed message bytes; transferring a `String`
    ///   is O(1). Other message types contribute their `Into<String>` conversion cost.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cel_parser::CELError;
    /// use cel_parser::SourceSpan;
    ///
    /// let span = SourceSpan::default();
    /// let e = CELError::new("unexpected token", span);
    /// assert_eq!(e.message(), "unexpected token");
    /// ```
    pub fn new(message: impl Into<String>, span: SourceSpan) -> Self {
        CELError {
            message: message.into(),
            span,
        }
    }

    /// Returns the error message.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cel_parser::CELError;
    /// use cel_parser::SourceSpan;
    ///
    /// let e = CELError::new("bad input", SourceSpan::default());
    /// assert_eq!(e.message(), "bad input");
    /// ```
    pub fn message(&self) -> &str {
        &self.message
    }

    /// Returns the source span for this error.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cel_parser::CELError;
    /// use cel_parser::SourceSpan;
    ///
    /// let span = SourceSpan::default();
    /// let e = CELError::new("bad input", span);
    /// assert_eq!(e.span(), span);
    /// ```
    pub fn span(&self) -> SourceSpan {
        self.span
    }

    /// Formats this error in rustc diagnostic style with source context.
    ///
    /// Produces a multi-line string matching Rust compiler diagnostic output,
    /// including the source file location, error message, and a caret indicating
    /// the error position. Uses [annotate-snippets](https://docs.rs/annotate-snippets)
    /// for rendering.
    ///
    /// Pass [`Renderer::plain`] for tests and non-ANSI contexts; pass
    /// [`Renderer::styled`] for terminal output.
    ///
    /// - Complexity: O(s) source traversal for s source bytes, plus renderer layout;
    ///   rendering uses O(s + b) auxiliary/output space for b output bytes.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use annotate_snippets::Renderer;
    /// use cel_parser::CELParser;
    /// use cel_parser::op_table::OpLookup;
    /// use cel_parser::CELError;
    ///
    /// let line = line!() + 1;
    /// let source = r#"
    ///     10 + 20 30
    /// "#;
    /// let mut parser = CELParser::new(OpLookup::new());
    /// if let Err(e) = parser.parse_str(source) {
    ///     let e: CELError = e.into();
    ///     println!("{}", e.format_rustc_style(source, file!(), line, &Renderer::styled()));
    /// }
    /// ```
    pub fn format_rustc_style(
        &self,
        source_code: &str,
        filename: &str,
        start_line: u32,
        renderer: &Renderer,
    ) -> String {
        let byte_range = span_to_byte_range(source_code, self.span);
        let report = [
            Group::with_title(Level::ERROR.primary_title(self.message.as_str())).element(
                Snippet::source(source_code)
                    .path(filename)
                    .line_start(start_line as usize)
                    .annotation(AnnotationKind::Primary.span(byte_range)),
            ),
        ];
        renderer.render(&report)
    }
}

impl std::fmt::Display for CELError {
    /// Writes m message bytes in O(m) time without allocating an intermediate string.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.message)
    }
}

impl std::error::Error for CELError {}

/// A parse error carrying the original `proc_macro2::Span` of the offending token or
/// expression start, plus an optional end span for range errors.
///
/// Used as the return type of all parser methods. Not `Send + Sync` because
/// `proc_macro2::Span` wraps a compiler-internal handle that is only valid on
/// the proc-macro thread. Convert to [`CELError`] via `From` when the error
/// must cross thread boundaries or be stored for async reporting.
///
/// # Examples
/// See [`Self::new`], [`Self::new_range`] and [`Self::with_cause`].
#[derive(Clone, Debug)]
pub struct ParseError {
    message: String,
    span: proc_macro2::Span,
    end_span: Option<proc_macro2::Span>,
    secondary: Vec<SpanLabel>,
    cause: Option<std::rc::Rc<dyn std::error::Error>>,
}

impl ParseError {
    /// Retains an immutable frontend cause without replacing its concrete error type.
    ///
    /// Cloning the parse error shares this cause. Conversion to [`CELError`] retains
    /// only the message and primary span for thread-safe reporting.
    ///
    /// # Examples
    /// ```
    /// use std::error::Error;
    /// let error = cel_parser::ParseError::new("frontend", proc_macro2::Span::call_site())
    ///     .with_cause(std::io::Error::other("original"));
    /// assert!(error.source().unwrap().is::<std::io::Error>());
    /// ```
    pub fn with_cause(mut self, cause: impl std::error::Error + 'static) -> Self {
        self.cause = Some(std::rc::Rc::new(cause));
        self
    }

    /// Creates a new parse error with the given message and token span.
    ///
    /// - Complexity: O(m) time and space for m borrowed message bytes; transferring a `String`
    ///   is O(1). Other message types contribute their `Into<String>` conversion cost.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use proc_macro2::Span;
    /// use cel_parser::ParseError;
    ///
    /// let e = ParseError::new("unexpected token", Span::call_site());
    /// assert_eq!(e.message(), "unexpected token");
    /// ```
    pub fn new(message: impl Into<String>, span: proc_macro2::Span) -> Self {
        ParseError {
            message: message.into(),
            span,
            end_span: None,
            secondary: Vec::new(),
            cause: None,
        }
    }

    /// Creates a parse error spanning a sub-expression from `start` to `end`.
    ///
    /// Use this for op-lookup failures where the error implicates a full
    /// sub-expression rather than a single token. At runtime the two spans
    /// are merged into a contiguous underline; at compile time two separate
    /// `compile_error!()` diagnostics are emitted.
    ///
    /// - Complexity: Matches the message conversion in [`Self::new`].
    ///
    /// # Examples
    ///
    /// ```rust
    /// use proc_macro2::Span;
    /// use cel_parser::ParseError;
    ///
    /// let start = Span::call_site();
    /// let end = Span::call_site();
    /// let e = ParseError::new_range("type mismatch", start, end);
    /// assert_eq!(e.message(), "type mismatch");
    /// assert!(e.end_span().is_some());
    /// ```
    pub fn new_range(
        message: impl Into<String>,
        start: proc_macro2::Span,
        end: proc_macro2::Span,
    ) -> Self {
        ParseError {
            message: message.into(),
            span: start,
            end_span: Some(end),
            secondary: Vec::new(),
            cause: None,
        }
    }

    /// Returns the error message.
    ///
    /// # Examples
    /// See [`Self::new`].
    pub fn message(&self) -> &str {
        &self.message
    }

    /// Returns the `proc_macro2::Span` of the offending token.
    ///
    /// Use this span with `quote_spanned!` in proc-macro code to attach the
    /// `compile_error!` to the exact source location.
    ///
    /// # Examples
    /// ```
    /// use cel_parser::ParseError;
    /// let error = ParseError::new("bad name", proc_macro2::Span::call_site());
    /// assert_eq!(error.span().start().column, 0);
    /// ```
    pub fn span(&self) -> proc_macro2::Span {
        self.span
    }

    /// Returns the end span of this error, or `None` for single-point errors.
    ///
    /// `Some` for errors created with [`new_range`](Self::new_range);
    /// `None` for errors created with [`new`](Self::new).
    ///
    /// # Examples
    /// See [`Self::new_range`].
    pub fn end_span(&self) -> Option<proc_macro2::Span> {
        self.end_span
    }

    /// Attaches secondary labelled spans, rendered as extra carets alongside the primary.
    ///
    /// - Complexity: O(k) to release k previously attached labels; transfers the new vector.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use proc_macro2::Span;
    /// use cel_parser::{ParseError, SourceSpan, SpanLabel};
    ///
    /// let e = ParseError::new("bad", Span::call_site()).with_secondary(vec![SpanLabel {
    ///     span: SourceSpan::new(1, 4, 1, 7),
    ///     label: "also here".into(),
    /// }]);
    /// assert_eq!(e.message(), "bad");
    /// ```
    pub fn with_secondary(mut self, secondary: Vec<SpanLabel>) -> Self {
        self.secondary = secondary;
        self
    }

    /// Returns the secondary labelled spans attached to this error.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cel_parser::{ParseError, SourceSpan, SpanLabel};
    /// use proc_macro2::Span;
    ///
    /// let e = ParseError::new("bad", Span::call_site()).with_secondary(vec![SpanLabel {
    ///     span: SourceSpan::new(1, 0, 1, 3),
    ///     label: "related".into(),
    /// }]);
    /// assert_eq!(e.secondary().len(), 1);
    /// ```
    pub fn secondary(&self) -> &[SpanLabel] {
        &self.secondary
    }

    /// Converts a lex failure (e.g. from `proc_macro2::TokenStream::from_str`) into a
    /// `ParseError` with a message describing the likely cause.
    ///
    /// `proc_macro2::LexError`'s `Display` is the same generic string ("cannot parse string
    /// into token stream") regardless of cause, but its span reliably points at the offending
    /// character. This inspects that character in `source` to report *why* lexing failed —
    /// unclosed/unexpected delimiter, unterminated string or character literal, unterminated
    /// block comment, or another invalid character — falling back to `err`'s own message only
    /// when the span doesn't resolve to a character in `source` (e.g. it points past the end).
    ///
    /// - Complexity: O(s) inspection for s source bytes, plus lexer error display when needed;
    ///   O(s) auxiliary/output space in delimiter classification.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cel_parser::ParseError;
    /// use proc_macro2::TokenStream;
    /// use std::str::FromStr;
    ///
    /// let source = "(1 + 2";
    /// let lex_err = TokenStream::from_str(source).unwrap_err();
    /// let err = ParseError::from_lex_error(source, lex_err);
    /// assert_eq!(err.message(), "unclosed delimiter `(`: expected a matching `)`");
    /// ```
    pub fn from_lex_error(source: &str, err: proc_macro2::LexError) -> Self {
        let span = err.span();
        match lex_failure_message(source, span) {
            Some((message, Some(secondary))) => {
                ParseError::new(message, span).with_secondary(vec![secondary])
            }
            Some((message, None)) => ParseError::new(message, span),
            None => ParseError::new(err.to_string(), span),
        }
    }

    /// Formats this error in rustc diagnostic style with source context.
    ///
    /// Identical contract to [`CELError::format_rustc_style`] when no secondary spans are
    /// attached; prefer calling this directly on a `ParseError` rather than converting to
    /// `CELError` first when you have the source text at hand. When secondaries have been
    /// added via [`with_secondary`](Self::with_secondary), renders a multi-span diagnostic
    /// (the primary span plus one context caret per secondary) via [`format_multi_span`].
    ///
    /// - Complexity: O(k * s + l) annotation work for k total labels, s source bytes and
    ///   l secondary-label bytes, plus renderer layout; O(k + l + s + b) auxiliary/output
    ///   space for b output bytes.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use annotate_snippets::Renderer;
    /// use cel_parser::CELParser;
    /// use cel_parser::OpLookup;
    ///
    /// let line = line!() + 1;
    /// let source = "10 + 20 30";
    /// let mut parser = CELParser::new(OpLookup::new());
    /// if let Err(e) = parser.parse_str(source) {
    ///     println!("{}", e.format_rustc_style(source, file!(), line, &Renderer::plain()));
    /// }
    /// ```
    pub fn format_rustc_style(
        &self,
        source_code: &str,
        filename: &str,
        start_line: u32,
        renderer: &Renderer,
    ) -> String {
        let source_span = SourceSpan {
            start: self.span.start(),
            end: self.end_span.unwrap_or(self.span).end(),
        };
        if !self.secondary.is_empty() {
            let mut labels = vec![SpanLabel {
                span: source_span,
                label: String::new(),
            }];
            labels.extend(self.secondary.iter().cloned());
            return format_multi_span(
                &self.message,
                &labels,
                source_code,
                filename,
                start_line,
                renderer,
            );
        }
        let byte_range = span_to_byte_range(source_code, source_span);
        let report = [
            Group::with_title(Level::ERROR.primary_title(self.message.as_str())).element(
                Snippet::source(source_code)
                    .path(filename)
                    .line_start(start_line as usize)
                    .annotation(AnnotationKind::Primary.span(byte_range)),
            ),
        ];
        renderer.render(&report)
    }
}

/// Converts a [`ParseError`] to a [`CELError`] by extracting the
/// [`SourceSpan`] from the token span.
///
/// Use this at async/runtime boundaries where `Send + Sync` is required.
impl From<ParseError> for CELError {
    /// Transfers the message and complete primary range into a thread-safe error.
    ///
    /// - Complexity: O(k) to release k secondary labels, plus releasing the retained cause.
    fn from(e: ParseError) -> Self {
        let source_span = SourceSpan {
            start: e.span.start(),
            end: e.end_span.unwrap_or(e.span).end(),
        };
        CELError::new(e.message, source_span)
    }
}

impl std::fmt::Display for ParseError {
    /// Writes m message bytes in O(m) time without allocating an intermediate string.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.message)
    }
}

impl std::error::Error for ParseError {
    /// Borrows the retained original frontend cause, if present.
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        self.cause.as_deref()
    }
}

/// A runtime error context carrying the source span of the failing operation.
///
/// Add this as anyhow context with `.context(SpanContext::new(span))` when wrapping
/// an op closure. Retrieve it from an `anyhow::Error` with `e.downcast_ref::<SpanContext>()`.
///
/// # Examples
/// See [`Self::new`] and [`FormatRustcStyle::format_rustc_style`].
pub struct SpanContext {
    span: SourceSpan,
}

impl SpanContext {
    /// Creates a new span context for the given source region.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cel_parser::{SourceSpan, SpanContext};
    ///
    /// let span = SourceSpan::new(1, 0, 1, 5);
    /// let ctx = SpanContext::new(span);
    /// assert_eq!(ctx.span(), span);
    /// ```
    pub fn new(span: SourceSpan) -> Self {
        SpanContext { span }
    }

    /// Returns the source span.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cel_parser::{SourceSpan, SpanContext};
    ///
    /// let span = SourceSpan::new(2, 3, 2, 7);
    /// let ctx = SpanContext::new(span);
    /// assert_eq!(ctx.span(), span);
    /// ```
    pub fn span(&self) -> SourceSpan {
        self.span
    }

    /// Formats a runtime error message with rustc-style source annotation.
    ///
    /// Delegates to `CELError::format_rustc_style` using `self.span` and `message`.
    ///
    /// - Complexity: O(s + m) source/message work for s source bytes and m message bytes,
    ///   plus renderer layout; O(s + m + b) auxiliary/output space for b output bytes.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use annotate_snippets::Renderer;
    /// use cel_parser::{SourceSpan, SpanContext};
    ///
    /// let source = "1i32 + 2i32";
    /// let span = SourceSpan::new(1, 5, 1, 6);
    /// let ctx = SpanContext::new(span);
    /// let output = ctx.format_rustc_style("arithmetic overflow", source, "test.cel", 1, &Renderer::plain());
    /// assert!(output.contains("arithmetic overflow"));
    /// ```
    pub fn format_rustc_style(
        &self,
        message: &str,
        source_code: &str,
        filename: &str,
        start_line: u32,
        renderer: &Renderer,
    ) -> String {
        CELError::new(message, self.span).format_rustc_style(
            source_code,
            filename,
            start_line,
            renderer,
        )
    }
}

impl std::fmt::Display for SpanContext {
    /// Writes the start and end line/column coordinates.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "at {}:{}-{}:{}",
            self.span.start.line, self.span.start.column, self.span.end.line, self.span.end.column
        )
    }
}

impl std::fmt::Debug for SpanContext {
    /// Writes the context's source region as a named debug field.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SpanContext")
            .field("span", &self.span)
            .finish()
    }
}

impl std::error::Error for SpanContext {}

/// Extension trait that adds rustc-style formatting to `anyhow::Error`.
///
/// Import this trait to call `.format_rustc_style(...)` directly on an `anyhow::Error`.
/// If the error carries a [`SpanContext`] (added during op execution with the
/// `span-diagnostics` feature), the output includes a source-location annotation.
/// Otherwise it falls back to `self.to_string()`.
///
/// # Examples
///
/// ```rust
/// use annotate_snippets::Renderer;
/// use cel_parser::FormatRustcStyle;
///
/// let err = anyhow::anyhow!("something went wrong");
/// let output = err.format_rustc_style("1 + 2", "example.cel", 1, &Renderer::plain());
/// assert_eq!(output, "something went wrong");
/// ```
pub trait FormatRustcStyle {
    /// Formats in rustc diagnostic style.
    ///
    /// If the error carries a [`SpanContext`], produces a multi-line caret diagnostic.
    /// Uses the root failure as the diagnostic title, regardless of textual context wrappers.
    /// Otherwise returns `self.to_string()`.
    ///
    /// - Complexity: O(c + s) traversal work for c error-chain links and s source bytes,
    ///   plus error-display and renderer-layout costs; O(c + s + b) auxiliary/output
    ///   space for b output bytes. Unlocated errors do not inspect the source.
    ///
    /// # Examples
    /// ```
    /// use annotate_snippets::Renderer;
    /// use cel_parser::{FormatRustcStyle, SourceSpan, SpanContext};
    /// let error = anyhow::anyhow!("division by zero")
    ///     .context(SpanContext::new(SourceSpan::new(1, 0, 1, 1)));
    /// let text = error.format_rustc_style("1", "input.cel", 1, &Renderer::plain());
    /// assert!(text.contains("error: division by zero"));
    /// assert!(text.contains("input.cel:1:1"));
    /// ```
    /// See the [`FormatRustcStyle`] example for the unlocated fallback.
    fn format_rustc_style(
        &self,
        source_code: &str,
        filename: &str,
        start_line: u32,
        renderer: &Renderer,
    ) -> String;
}

impl FormatRustcStyle for anyhow::Error {
    /// Renders the located root failure, or the outer display text when no location exists.
    ///
    /// - Complexity: Matches [`FormatRustcStyle::format_rustc_style`].
    fn format_rustc_style(
        &self,
        source_code: &str,
        filename: &str,
        start_line: u32,
        renderer: &Renderer,
    ) -> String {
        if let Some(ctx) = self.downcast_ref::<SpanContext>() {
            let message = self.root_cause().to_string();
            ctx.format_rustc_style(&message, source_code, filename, start_line, renderer)
        } else {
            self.to_string()
        }
    }
}

#[cfg(test)]
mod tests {
    /// Retains an immutable concrete cause through cloning and error-source traversal.
    #[test]
    fn parse_error_retains_owning_cause() {
        use std::error::Error;
        let error = ParseError::new("construction failed", proc_macro2::Span::call_site())
            .with_cause(std::io::Error::other("original"));
        let copy = error.clone();
        assert_eq!(
            copy.source()
                .unwrap()
                .downcast_ref::<std::io::Error>()
                .unwrap()
                .to_string(),
            "original"
        );
        assert!(
            ParseError::new("syntax", proc_macro2::Span::call_site())
                .source()
                .is_none()
        );
    }

    use super::*;
    use annotate_snippets::Renderer;
    use proc_macro2::Span;

    #[test]
    fn parse_error_message() {
        let e = ParseError::new("bad token", Span::call_site());
        assert_eq!(e.message(), "bad token");
    }

    #[test]
    fn parse_error_display() {
        let e = ParseError::new("bad token", Span::call_site());
        assert_eq!(e.to_string(), "bad token");
    }

    #[test]
    fn parse_error_into_cel_error() {
        let e = ParseError::new("bad token", Span::call_site());
        let cel: CELError = e.into();
        assert_eq!(cel.message(), "bad token");
        assert_eq!(cel.span(), SourceSpan::from_proc_macro2(Span::call_site()));
    }

    #[test]
    fn parse_error_format_rustc_style() {
        let source = "10 + 20 30";
        let e = ParseError::new("unexpected token", Span::call_site());
        let formatted = e.format_rustc_style(source, "test.cel", 1, &Renderer::plain());
        assert!(formatted.contains("error: unexpected token"));
        assert!(formatted.contains("test.cel"));
    }

    #[test]
    fn parse_error_new_range_has_end_span() {
        let start = Span::call_site();
        let end = Span::call_site();
        let e = ParseError::new_range("type mismatch", start, end);
        assert_eq!(e.message(), "type mismatch");
        assert!(e.end_span().is_some());
    }

    #[test]
    fn from_lex_error_unclosed_paren_names_expected_close() {
        let source = "(1 + 2";
        let lex_err = source.parse::<proc_macro2::TokenStream>().unwrap_err();
        let e = ParseError::from_lex_error(source, lex_err);
        assert_eq!(
            e.message(),
            "unclosed delimiter `(`: expected a matching `)`"
        );
    }

    #[test]
    fn from_lex_error_unclosed_bracket_names_expected_close() {
        let source = "[1, 2";
        let lex_err = source.parse::<proc_macro2::TokenStream>().unwrap_err();
        let e = ParseError::from_lex_error(source, lex_err);
        assert_eq!(
            e.message(),
            "unclosed delimiter `[`: expected a matching `]`"
        );
    }

    #[test]
    fn from_lex_error_unclosed_brace_names_expected_close() {
        let source = "{1: 2";
        let lex_err = source.parse::<proc_macro2::TokenStream>().unwrap_err();
        let e = ParseError::from_lex_error(source, lex_err);
        assert_eq!(
            e.message(),
            "unclosed delimiter `{`: expected a matching `}`"
        );
    }

    #[test]
    fn from_lex_error_unexpected_closing_delimiter() {
        let source = "1 + 2)";
        let lex_err = source.parse::<proc_macro2::TokenStream>().unwrap_err();
        let e = ParseError::from_lex_error(source, lex_err);
        assert_eq!(e.message(), "unexpected closing delimiter `)`");
    }

    #[test]
    fn from_lex_error_mismatched_delimiter_names_found_and_expected() {
        let source = "(1 + 2]";
        let lex_err = source.parse::<proc_macro2::TokenStream>().unwrap_err();
        let e = ParseError::from_lex_error(source, lex_err);
        assert_eq!(
            e.message(),
            "mismatched closing delimiter: found `]`, expected `)`"
        );
        let out = e.format_rustc_style(source, "t.cel", 1, &Renderer::plain());
        assert!(
            out.contains("unclosed delimiter `(`"),
            "expected a secondary annotation on the unclosed `(`:\n{out}"
        );
    }

    #[test]
    fn from_lex_error_mismatched_delimiter_issue_77_example() {
        // From issue #77: the real problem is the unclosed `(`, not the `}` the lex error
        // itself points at.
        let source = "{a: (1 + 2}";
        let lex_err = source.parse::<proc_macro2::TokenStream>().unwrap_err();
        let e = ParseError::from_lex_error(source, lex_err);
        assert_eq!(
            e.message(),
            "mismatched closing delimiter: found `}`, expected `)`"
        );
        let out = e.format_rustc_style(source, "t.cel", 1, &Renderer::plain());
        assert!(
            out.contains("unclosed delimiter `(`"),
            "expected a secondary annotation on the unclosed `(`:\n{out}"
        );
    }

    #[test]
    fn from_lex_error_mismatched_delimiter_reports_innermost_opener() {
        // Innermost open delimiter is `{`, not the outer `[` or `(`.
        let source = "([{1)]}";
        let lex_err = source.parse::<proc_macro2::TokenStream>().unwrap_err();
        let e = ParseError::from_lex_error(source, lex_err);
        assert_eq!(
            e.message(),
            "mismatched closing delimiter: found `)`, expected `}`"
        );
        let out = e.format_rustc_style(source, "t.cel", 1, &Renderer::plain());
        assert!(
            out.contains("unclosed delimiter `{`"),
            "expected a secondary annotation on the unclosed `{{`:\n{out}"
        );
    }

    #[test]
    fn from_lex_error_unterminated_string_literal() {
        let source = "1 + \"abc";
        let lex_err = source.parse::<proc_macro2::TokenStream>().unwrap_err();
        let e = ParseError::from_lex_error(source, lex_err);
        assert_eq!(e.message(), "unterminated string literal");
    }

    #[test]
    fn from_lex_error_unterminated_block_comment() {
        let source = "/* unterminated";
        let lex_err = source.parse::<proc_macro2::TokenStream>().unwrap_err();
        let e = ParseError::from_lex_error(source, lex_err);
        assert_eq!(e.message(), "unterminated block comment");
    }

    #[test]
    fn from_lex_error_invalid_character_names_the_character() {
        let source = "1 + `";
        let lex_err = source.parse::<proc_macro2::TokenStream>().unwrap_err();
        let e = ParseError::from_lex_error(source, lex_err);
        assert_eq!(e.message(), "invalid character `` ` ``");
    }

    #[test]
    fn from_lex_error_preserves_lex_error_span() {
        let source = "(1 + 2";
        let lex_err = source.parse::<proc_macro2::TokenStream>().unwrap_err();
        let expected_span = SourceSpan::from_proc_macro2(lex_err.span());
        let e = ParseError::from_lex_error(source, lex_err);
        assert_eq!(SourceSpan::from_proc_macro2(e.span()), expected_span);
    }

    #[test]
    fn parse_error_new_range_cel_error_merges_spans() {
        let ts: proc_macro2::TokenStream = r#""Hello" 32.0"#.parse().unwrap();
        let mut iter = ts.into_iter();
        let start_tok = iter.next().unwrap();
        let end_tok = iter.next().unwrap();
        let start = start_tok.span();
        let end = end_tok.span();

        let e = ParseError::new_range("type mismatch", start, end);
        let cel: CELError = e.into();

        assert_eq!(cel.message(), "type mismatch");
        assert_eq!(
            cel.span().start,
            start.start(),
            "CELError span should start at expression start"
        );
        assert_eq!(
            cel.span().end,
            end.end(),
            "CELError span should end at expression end"
        );
    }

    #[test]
    fn parse_error_new_has_no_end_span() {
        let e = ParseError::new("bad token", Span::call_site());
        assert!(e.end_span().is_none());
    }

    #[test]
    fn span_to_byte_range_basic() {
        let source = "hello world";
        assert_eq!(
            span_to_byte_range(source, SourceSpan::new(1, 6, 1, 11)),
            6..11
        );
    }

    #[test]
    fn span_to_byte_range_empty_span() {
        let source = "hello";
        assert_eq!(
            span_to_byte_range(source, SourceSpan::new(1, 2, 1, 2)),
            2..2
        );
    }

    #[test]
    fn span_to_byte_range_start_past_end_of_source() {
        let source = "hi";
        let r = span_to_byte_range(source, SourceSpan::new(5, 0, 5, 3));
        assert_eq!(r, source.len()..source.len());
    }

    #[test]
    fn span_to_byte_range_end_past_end_of_source() {
        let source = "hi";
        let r = span_to_byte_range(source, SourceSpan::new(1, 0, 1, 100));
        assert!(r.start <= r.end && r.end <= source.len());
    }

    #[test]
    fn span_context_display_shows_span_location() {
        let span = SourceSpan::new(1, 0, 1, 5);
        let ctx = SpanContext::new(span);
        let s = ctx.to_string();
        assert_eq!(s, "at 1:0-1:5");
    }

    #[test]
    fn span_context_span_roundtrip() {
        let span = SourceSpan::new(2, 3, 2, 7);
        let ctx = SpanContext::new(span);
        assert_eq!(ctx.span(), span);
    }

    #[test]
    fn span_context_format_rustc_style_contains_message_and_location() {
        let source = "1i32 + 2i32";
        let span = SourceSpan::new(1, 5, 1, 6);
        let ctx = SpanContext::new(span);
        let output = ctx.format_rustc_style(
            "arithmetic overflow",
            source,
            "test.cel",
            1,
            &Renderer::plain(),
        );
        assert!(
            output.contains("arithmetic overflow"),
            "expected message in output:\n{output}"
        );
        assert!(
            output.contains("test.cel"),
            "expected filename in output:\n{output}"
        );
    }

    #[test]
    fn format_rustc_style_with_span_context_uses_span() {
        let source = "1i32 + 2i32";
        let span = SourceSpan::new(1, 5, 1, 6);
        let inner = anyhow::anyhow!("arithmetic overflow");
        let wrapped = inner.context(SpanContext::new(span));
        let output = FormatRustcStyle::format_rustc_style(
            &wrapped,
            source,
            "test.cel",
            1,
            &Renderer::plain(),
        );
        assert!(
            output.contains("arithmetic overflow"),
            "expected message:\n{output}"
        );
        assert!(output.contains("test.cel"), "expected filename:\n{output}");
    }

    #[test]
    fn format_rustc_style_without_span_context_falls_back_to_to_string() {
        let err = anyhow::anyhow!("something went wrong");
        let output = FormatRustcStyle::format_rustc_style(
            &err,
            "unused source",
            "unused.cel",
            1,
            &Renderer::plain(),
        );
        assert_eq!(output, "something went wrong");
    }

    #[test]
    fn parse_error_with_secondary_renders_all_spans() {
        let source = "aaa bbb";
        let e = ParseError::new_range("bad", Span::call_site(), Span::call_site()).with_secondary(
            vec![SpanLabel {
                span: SourceSpan::new(1, 4, 1, 7),
                label: "also here".into(),
            }],
        );
        // primary span is call_site (line 1 col 0..0); secondary underlines "bbb".
        let out = e.format_rustc_style(source, "t.cel", 1, &Renderer::plain());
        assert!(out.contains("bad"), "{out}");
        assert!(out.contains("also here"), "{out}");
    }

    #[test]
    fn parse_error_without_secondary_renders_single_span_as_before() {
        let e = ParseError::new("bad", Span::call_site());
        let out = e.format_rustc_style("10 + 20 30", "t.cel", 1, &Renderer::plain());
        assert!(out.contains("error: bad"), "{out}");
    }

    #[test]
    fn format_multi_span_underlines_every_span_and_prints_labels() {
        let source = "aaa bbb ccc";
        let labels = vec![
            SpanLabel {
                span: SourceSpan::new(1, 0, 1, 3),
                label: "first".into(),
            },
            SpanLabel {
                span: SourceSpan::new(1, 8, 1, 11),
                label: "third".into(),
            },
        ];
        let out = format_multi_span("mismatch", &labels, source, "t.adm2", 1, &Renderer::plain());
        assert!(out.contains("mismatch"), "{out}");
        assert!(out.contains("first"), "{out}");
        assert!(out.contains("third"), "{out}");
        assert!(out.contains("| ^^^     --- third"), "{out}");
        assert!(out.contains("| first"), "{out}");
        assert!(!out.contains('\u{1b}'), "plain renderer has no ANSI: {out}");
    }

    #[test]
    fn to_byte_range_matches_manual_slice() {
        let source = "line one\nline two\nline three";
        let span = SourceSpan::new(2, 5, 3, 4);
        let range = span.to_byte_range(source);
        assert_eq!(&source[range], "two\nline");
    }
}