serde_saphyr/de/

error.rs

use crate::Location;
use crate::budget::BudgetBreach;
use crate::de_snippet::{
    fmt_snippet_window_offset_or_fallback, snippet_window_frame_prefix_offset,
};
use crate::input_source::IncludeResolveError;
use crate::localizer::{DEFAULT_ENGLISH_LOCALIZER, ExternalMessageSource, Localizer};
use crate::location::Locations;
use crate::parse_scalars::{
    parse_int_signed, parse_yaml11_bool, parse_yaml12_float, scalar_is_nullish,
};
#[cfg(feature = "garde")]
use crate::path_map::path_key_from_garde;
use crate::properties_redaction::{
    redact_custom_message, redact_dynamic_identifier, redact_dynamic_value,
};
use crate::tags::SfTag;
#[cfg(any(feature = "garde", feature = "validator"))]
use crate::{
    localizer::ExternalMessage,
    path_map::{PathKey, PathMap, format_path_with_resolved_leaf},
};
use annotate_snippets::Level;
use granit_parser::{ErrorKind, ScalarStyle, ScanError};
use serde_core::de::{self};
use std::borrow::Cow;
use std::cell::Cell;
#[cfg(any(feature = "garde", feature = "validator"))]
use std::collections::HashSet;
use std::fmt;

#[cfg(all(feature = "properties", any(feature = "garde", feature = "validator")))]
use crate::properties_redaction::{redact_with_ctxs, with_interp_redaction};

#[cfg(feature = "validator")]
use validator::{ValidationErrors, ValidationErrorsKind};

/// Formats error *messages* (not including locations/snippets).
///
/// This is the core customization hook for deferred rendering. The error value remains
/// structured data; the formatter decides what message text to show (developer-oriented,
/// user-oriented, localized, etc.).
///
/// Important: implementations must NOT call `err.to_string()` / `Display` for `Error` to
/// avoid recursion once `Display` delegates to `Error::render()`.
///
/// # Example
///
/// Override a couple of messages, returning `Cow::Borrowed` for a fixed string and
/// `Cow::Owned` for a formatted message, while delegating all other cases to
/// `UserMessageFormatter`.
///
/// ```rust
/// use serde_saphyr::{Error, Location, MessageFormatter, UserMessageFormatter};
/// use std::borrow::Cow;
///
/// struct PoliteFormatter;
///
/// impl MessageFormatter for PoliteFormatter {
///     fn format_message<'a>(&self, err: &'a Error) -> Cow<'a, str> {
///         // `UserMessageFormatter` is a zero-sized type, so it is cheap to instantiate.
///         let fallback = UserMessageFormatter;
///
///         match err {
///             // Fixed string => `Cow::Borrowed`
///             Error::Eof { .. } => Cow::Borrowed("could you please provide a YAML document?"),
///
///             // Formatted string => `Cow::Owned`
///             Error::UnknownAnchor { .. } => {
///                 Cow::Borrowed("sorry but unknown reference")
///             }
///
///             // Everything else => delegate
///             _ => fallback.format_message(err),
///         }
///     }
/// }
///
/// let err = serde_saphyr::from_str::<String>("").unwrap_err();
/// assert!(err.render_with_formatter(&PoliteFormatter).contains("please provide"));
///
/// let err = Error::UnknownAnchor {
///     location: Location::UNKNOWN,
/// };
/// assert!(err
///     .render_with_formatter(&PoliteFormatter)
///     .contains("unknown reference"));
/// ```
pub trait MessageFormatter {
    /// Return the [`Localizer`] used by the renderer.
    ///
    /// This controls wording that is produced outside of [`MessageFormatter::format_message`],
    /// such as location suffixes and snippet/validation labels.
    fn localizer(&self) -> &dyn Localizer {
        &DEFAULT_ENGLISH_LOCALIZER
    }

    /// Return the message text for `err`.
    ///
    /// The returned string should NOT include location suffixes like
    /// `"at line X, column Y"`; those are added by the renderer.
    ///
    /// Rendering entrypoints unwrap [`Error::AliasError`] and [`Error::WithSnippet`] before
    /// calling this method, so the formatter receives the original error. Alias locations
    /// are composed separately by the renderer.
    ///
    /// Rendering entrypoints such as [`Error::render`] neutralize control characters in
    /// this text before composing their own layout. Implementations should therefore not
    /// use control characters, including line breaks, for message layout.
    ///
    /// Calling this low-level method directly bypasses that rendering boundary. Before
    /// writing its result to a terminal or log, sanitize it with
    /// [`str::escape_debug`] or an equivalent encoding.
    fn format_message<'a>(&self, err: &'a Error) -> Cow<'a, str>;

    /// Return the complete message for a standalone diagnostic, such as a Miette report,
    /// that does not retain the original error's source chain.
    ///
    /// The default preserves [`Self::format_message`] unchanged. Built-in formatters
    /// also include I/O causes here. Custom formatters control whether to include,
    /// translate, or omit those details; delegate this hook to a built-in formatter
    /// when its standalone behavior is desired for fallback cases.
    ///
    /// The same wrapper-unwrapping and sanitization rules as [`Self::format_message`]
    /// apply. Ordinary [`Error::render`] and `Display` still use `format_message`.
    fn format_standalone_message<'a>(&self, err: &'a Error) -> Cow<'a, str> {
        self.format_message(err)
    }

    /// Optionally format individual validation issues for plain rendering.
    ///
    /// For [`Error::ValidationError`], returning `Some(lines)` replaces the call to
    /// [`Self::format_message`]. The renderer escapes control characters in each line
    /// before calling [`Localizer::join_validation_issues`], preserving the joiner's
    /// newline separators. Lines may include their own per-issue locations.
    ///
    /// The default returns `None`, preserving custom whole-message formatting.
    /// The built-in formatters return individual issue lines. A custom formatter that
    /// delegates validation formatting can also delegate this method to a built-in
    /// formatter to retain that layout.
    #[cfg(any(feature = "garde", feature = "validator"))]
    fn format_validation_issue_lines(&self, _err: &Error) -> Option<Vec<String>> {
        None
    }
}

/// Convert control characters in semantic diagnostic text to inert debug escapes.
///
/// Renderer-owned layout is added after this boundary and is therefore unaffected.
/// Ordinary text stays borrowed and is not allocated.
pub(crate) fn sanitize_message_text(text: Cow<'_, str>) -> Cow<'_, str> {
    let Some(first_unsafe) = text
        .char_indices()
        .find_map(|(offset, ch)| message_char_needs_escape(ch).then_some(offset))
    else {
        return text;
    };

    let mut sanitized = String::with_capacity(text.len());
    sanitized.push_str(&text[..first_unsafe]);
    for ch in text[first_unsafe..].chars() {
        if message_char_needs_escape(ch) {
            sanitized.extend(ch.escape_debug());
        } else {
            sanitized.push(ch);
        }
    }
    Cow::Owned(sanitized)
}

#[inline]
fn message_char_needs_escape(ch: char) -> bool {
    ch.is_control() || matches!(ch, '\u{2028}' | '\u{2029}')
}

#[inline]
fn original_error(mut err: &Error) -> &Error {
    while let Error::AliasError { error, .. } | Error::WithSnippet { error, .. } = err {
        err = error;
    }
    err
}

#[inline]
pub(crate) fn render_message_text<'a>(
    formatter: &dyn MessageFormatter,
    err: &'a Error,
) -> Cow<'a, str> {
    sanitize_message_text(formatter.format_message(original_error(err)))
}

/// The failing value can be distinct from both the beginning of the anchor and its use.
/// Keep that location even when the original error is behind several alias wrappers.
pub(crate) fn distinct_alias_error_location(mut err: &Error) -> Option<Location> {
    while let Error::WithSnippet { error, .. } = err {
        err = error;
    }
    let Error::AliasError { locations, .. } = err else {
        return None;
    };
    original_error(err).location().filter(|location| {
        *location != Location::UNKNOWN
            && *location != locations.reference_location
            && *location != locations.defined_location
    })
}

/// User-facing message formatter.
///
/// This formatter simplifies technical errors and removes internal details.
/// ```
/// use serde_saphyr::UserMessageFormatter;
///
/// let err = serde_saphyr::from_str::<String>("").unwrap_err();
/// let msg = err.render_with_formatter(&UserMessageFormatter);
///
/// assert_eq!(msg, "unexpected end of file at line 1, column 1");
/// ```
#[derive(Debug, Default, Clone, Copy)]
pub struct UserMessageFormatter;

/// Controls whether snippet output is included when available.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SnippetMode {
    /// Render snippets when the error is wrapped in `Error::WithSnippet`.
    Auto,
    /// Never render snippets; render a plain (location-suffixed) message instead.
    Off,
}

/// Options for deferred error rendering.
/// Construct this via the [`render_options!`](crate::render_options!) macro:
///
/// ```rust
/// use serde_saphyr::{DefaultMessageFormatter, SnippetMode};
///
/// let dev = DefaultMessageFormatter;
/// // Customize how an error is rendered later (formatter + snippet mode).
/// let render_opts = serde_saphyr::render_options! {
///     formatter: &dev,
///     snippets: SnippetMode::Off,
/// };
///
/// let err = serde_saphyr::from_str::<String>("").unwrap_err();
/// let rendered = err.render_with_options(render_opts);
/// assert!(rendered.contains("unexpected"));
/// ```
#[non_exhaustive]
#[derive(Clone, Copy)]
pub struct RenderOptions<'a> {
    /// Message formatter used to produce the core error message text.
    pub formatter: &'a dyn MessageFormatter,
    /// Snippet rendering mode.
    pub snippets: SnippetMode,
    /// Number of lines preceding the root YAML input in its containing document.
    ///
    /// For YAML extracted from a larger document, set `line_offset` to the number of
    /// preceding lines. This example displays the first YAML line as line 10000:
    ///
    /// ```rust
    /// let yaml = "eighty\n";
    /// let err = serde_saphyr::from_str::<u16>(yaml).unwrap_err();
    /// let options = serde_saphyr::render_options! {
    ///     line_offset: 9_999,
    ///     source_name: Some("article.md"),
    /// };
    /// let rendered = err.render_with_options(options);
    /// assert!(rendered.contains("article.md:10000:1"));
    /// assert_eq!(err.location().unwrap().line(), 1);
    /// ```
    pub line_offset: u64,
    /// Display name for the root YAML source in snippet headers.
    ///
    /// Defaults to `None`, preserving the recorded source names. `Some(name)`
    /// overrides the root name, including miette's `file` argument, while included
    /// sources keep their own names. The name is borrowed and escaped for display;
    /// an empty name is used verbatim. Stored error data is unchanged.
    ///
    /// Plain messages have no source-name headers, so this option has no effect
    /// when snippets are disabled or unavailable.
    pub source_name: Option<&'a str>,
}

impl Default for RenderOptions<'_> {
    #[inline]
    fn default() -> Self {
        // Keep the default formatter reference valid even if `RenderOptions` is stored.
        static DEFAULT_FMT: crate::message_formatters::DefaultMessageFormatter =
            crate::message_formatters::DefaultMessageFormatter;

        Self::new(&DEFAULT_FMT)
    }
}

impl<'a> RenderOptions<'a> {
    /// Construct render options with the given message `formatter` and default values
    /// for all other fields.
    ///
    /// Defaults:
    /// - `snippets`: [`SnippetMode::Auto`]
    /// - `line_offset`: `0`
    /// - `source_name`: `None`
    #[inline]
    #[must_use]
    pub fn new(formatter: &'a dyn MessageFormatter) -> Self {
        Self {
            formatter,
            snippets: SnippetMode::Auto,
            line_offset: 0,
            source_name: None,
        }
    }
}

/// Choose the displayed name using the snippet's source identity, rather than its
/// filename: a root and an included source can legitimately have the same name.
fn display_source_name<'a>(
    location: Location,
    recorded_name: &'a str,
    root_name: Option<&'a str>,
) -> &'a str {
    if location.source_id() <= 1 {
        root_name.unwrap_or(recorded_name)
    } else {
        recorded_name
    }
}

/// Project a location for presentation without changing its source-relative span.
pub(crate) fn display_location(mut location: Location, line_offset: u64) -> Location {
    if location.line != 0 && location.source_id() <= 1 {
        location.line = location
            .line()
            .saturating_add(line_offset)
            .min(u32::MAX as u64) as u32;
    }
    location
}

/// Bound the offset once for the whole report so all displayed locations use the same
/// translation, even near the line-number limit. Leave room for snippet context.
pub(crate) fn render_line_offset(err: &Error, requested: u64) -> u64 {
    if requested == 0 {
        return 0;
    }
    fn root_line(location: Location) -> u64 {
        if location.source_id() <= 1 {
            location.line()
        } else {
            0
        }
    }
    fn max_line(err: &Error) -> u64 {
        let own = err.location().map_or(0, root_line);
        match err {
            Error::WithSnippet { error, regions, .. } => regions
                .iter()
                .filter(|region| region.location.source_id() <= 1)
                .map(|region| region.end_line as u64)
                .fold(max_line(error).max(own), u64::max),
            Error::AliasError {
                error, locations, ..
            } => max_line(error)
                .max(root_line(locations.reference_location))
                .max(root_line(locations.defined_location))
                .max(own),
            #[cfg(any(feature = "garde", feature = "validator"))]
            Error::ValidationError { locations, .. } => locations
                .map
                .values()
                .flat_map(|locs| {
                    [
                        root_line(locs.reference_location),
                        root_line(locs.defined_location),
                    ]
                })
                .fold(own, u64::max),
            #[cfg(any(feature = "garde", feature = "validator"))]
            Error::ValidationErrors { errors, .. } => {
                errors.iter().map(max_line).fold(own, u64::max)
            }
            _ => own,
        }
    }
    requested.min((u32::MAX as u64).saturating_sub(max_line(err).saturating_add(2)))
}

/// Cropped YAML source window stored inside [`Error::WithSnippet`].
///
/// The window is described in terms of the original (absolute) 1-based line numbers.
/// This allows selecting the best-matching region for a particular error location.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CroppedRegion {
    /// Cropped source text used for snippet rendering.
    pub text: String,
    /// Source name/path displayed in snippet headers.
    pub source_name: String,
    /// The 1-based line number in the *original* input where `text` starts.
    pub start_line: usize,
    /// The 1-based line number in the *original* input where `text` ends (inclusive).
    pub end_line: usize,
    /// The location to point to in this region.
    pub location: Location,
}

impl CroppedRegion {
    /// Construct a cropped source region for deferred snippet rendering.
    #[must_use]
    pub fn new(
        text: impl Into<String>,
        source_name: impl Into<String>,
        start_line: usize,
        end_line: usize,
        location: Location,
    ) -> Self {
        Self {
            text: text.into(),
            source_name: source_name.into(),
            start_line,
            end_line,
            location,
        }
    }

    fn snippet<'a>(
        &'a self,
        crop_radius: usize,
        options: RenderOptions<'a>,
    ) -> crate::de_snippet::Snippet<'a> {
        crate::de_snippet::Snippet::new(
            self.text.as_str(),
            display_source_name(
                self.location,
                self.source_name.as_str(),
                options.source_name,
            ),
            crop_radius,
        )
        .with_offset(self.start_line)
        .with_line_offset(options.line_offset)
    }

    fn covers_exact_source(&self, location: &Location) -> bool {
        if location == &Location::UNKNOWN {
            return false;
        }
        let source_id = location.source_id();
        source_id != 0 && self.location.source_id() == source_id && self.covers_line(location)
    }

    fn covers_line(&self, location: &Location) -> bool {
        let line = location.line as usize;
        self.start_line <= line && line <= self.end_line
    }

    fn covers(&self, location: &Location) -> bool {
        if location == &Location::UNKNOWN {
            return false;
        }
        if !self.covers_line(location) {
            return false;
        }
        let region_source_id = self.location.source_id();
        let location_source_id = location.source_id();
        region_source_id == 0 || location_source_id == 0 || region_source_id == location_source_id
    }
}

fn line_count_including_trailing_empty_line(text: &str) -> usize {
    let mut lines = text.split_terminator('\n').count().max(1);
    if text.ends_with('\n') {
        lines = lines.saturating_add(1);
    }
    lines
}

fn sanitize_snippet_source_name(name: &str) -> Cow<'_, str> {
    if !name.chars().any(char::is_control) {
        return Cow::Borrowed(name);
    }

    let sanitized: String = name
        .chars()
        .map(|ch| if ch.is_control() { ' ' } else { ch })
        .collect();
    Cow::Owned(sanitized)
}

fn cropped_region_for_location(
    text: &str,
    source_name: &str,
    location: &Location,
    mapping: crate::de_snippet::LineMapping,
    crop_radius: usize,
) -> Option<CroppedRegion> {
    if crop_radius == 0 || *location == Location::UNKNOWN {
        return None;
    }

    let (cropped, start_line) =
        crate::de_snippet::crop_source_window(text, location, mapping, crop_radius);
    if cropped.is_empty() {
        return None;
    }

    let lines = line_count_including_trailing_empty_line(cropped.as_str());
    let end_line = start_line.saturating_add(lines.saturating_sub(1));
    Some(CroppedRegion {
        text: cropped,
        source_name: source_name.to_string(),
        start_line,
        end_line,
        location: *location,
    })
}

fn push_region_for_location(
    regions: &mut Vec<CroppedRegion>,
    text: &str,
    source_name: &str,
    location: &Location,
    mapping: crate::de_snippet::LineMapping,
    crop_radius: usize,
) {
    if let Some(region) =
        cropped_region_for_location(text, source_name, location, mapping, crop_radius)
    {
        regions.push(region);
    }
}

fn push_regions_for_locations(
    regions: &mut Vec<CroppedRegion>,
    text: &str,
    source_name: &str,
    locations: Locations,
    mapping: crate::de_snippet::LineMapping,
    crop_radius: usize,
) {
    push_region_for_location(
        regions,
        text,
        source_name,
        &locations.reference_location,
        mapping,
        crop_radius,
    );
    if locations.defined_location != locations.reference_location {
        push_region_for_location(
            regions,
            text,
            source_name,
            &locations.defined_location,
            mapping,
            crop_radius,
        );
    }
}

#[cfg(any(feature = "garde", feature = "validator"))]
fn push_validation_issue_regions(
    regions: &mut Vec<CroppedRegion>,
    issues: &[ValidationIssue],
    locations: &PathMap,
    text: &str,
    source_name: &str,
    mapping: crate::de_snippet::LineMapping,
    crop_radius: usize,
) {
    for issue in issues {
        let (locs, _) = locations
            .search_with_ancestor_fallback(&issue.path)
            .unwrap_or((Locations::UNKNOWN, String::new()));
        push_regions_for_locations(regions, text, source_name, locs, mapping, crop_radius);
    }
}

fn collect_snippet_regions(
    inner: &Error,
    text: &str,
    source_name: &str,
    mapping: crate::de_snippet::LineMapping,
    crop_radius: usize,
) -> Vec<CroppedRegion> {
    let mut regions = Vec::new();

    // Validation errors may contain multiple independent issue locations; pre-crop
    // one region per issue so we can later pick the region that covers the issue.
    #[cfg(any(feature = "garde", feature = "validator"))]
    if let Error::ValidationError {
        issues, locations, ..
    } = inner
    {
        push_validation_issue_regions(
            &mut regions,
            issues,
            locations,
            text,
            source_name,
            mapping,
            crop_radius,
        );
    }

    // Fallback: crop around the top-level error locations (including dual-location
    // errors such as AliasError).
    if regions.is_empty() {
        if let Some(locs) = inner.locations() {
            push_regions_for_locations(&mut regions, text, source_name, locs, mapping, crop_radius);
        } else if let Some(loc) = inner.location() {
            push_region_for_location(&mut regions, text, source_name, &loc, mapping, crop_radius);
        }
    }

    if let Some(location) = distinct_alias_error_location(inner) {
        push_region_for_location(
            &mut regions,
            text,
            source_name,
            &location,
            mapping,
            crop_radius,
        );
    }

    regions
}

#[cfg(any(feature = "garde", feature = "validator"))]
/// A structured issue reported by a validation library.
///
/// Use [`ValidationIssue::new`] to construct synthetic issues when testing custom
/// formatters or localizers.
#[non_exhaustive]
#[derive(Debug, Clone)]
pub struct ValidationIssue {
    /// Path to the value that failed validation.
    pub path: PathKey,
    /// Validation-library error code.
    pub code: String,
    /// Human-readable validation message, when provided.
    pub message: Option<String>,
    /// Structured parameters supplied by the validation library.
    pub params: Vec<(String, String)>,
}

#[cfg(any(feature = "garde", feature = "validator"))]
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ValidationSource {
    Garde,
    Validator,
}

#[cfg(any(feature = "garde", feature = "validator"))]
impl ValidationSource {
    pub(crate) fn external_message_source(self) -> ExternalMessageSource {
        match self {
            ValidationSource::Garde => ExternalMessageSource::Garde,
            ValidationSource::Validator => ExternalMessageSource::Validator,
        }
    }
}

#[cfg(any(feature = "garde", feature = "validator"))]
impl ValidationIssue {
    /// Construct a validation issue without a message or structured parameters.
    #[must_use]
    pub fn new(path: PathKey, code: impl Into<String>) -> Self {
        Self {
            path,
            code: code.into(),
            message: None,
            params: Vec::new(),
        }
    }

    /// Attach a human-readable validation message.
    #[must_use]
    pub fn with_message(mut self, message: impl Into<String>) -> Self {
        self.message = Some(message.into());
        self
    }

    /// Attach structured validation parameters.
    #[must_use]
    pub fn with_params(mut self, params: Vec<(String, String)>) -> Self {
        self.params = params;
        self
    }

    pub(crate) fn display_entry(&self) -> String {
        if let Some(msg) = &self.message {
            return msg.clone();
        }

        if self.params.is_empty() {
            return self.code.clone();
        }

        let mut params = String::new();
        for (i, (k, v)) in self.params.iter().enumerate() {
            if i > 0 {
                params.push_str(", ");
            }
            params.push_str(k);
            params.push('=');
            params.push_str(v);
        }
        format!("{} ({params})", self.code)
    }

    pub(crate) fn display_entry_overridden(
        &self,
        l10n: &dyn Localizer,
        source: ExternalMessageSource,
    ) -> String {
        let raw = self.display_entry();
        let overridden = l10n
            .override_external_message(ExternalMessage {
                source,
                original: raw.as_str(),
                code: Some(self.code.as_str()),
                params: &self.params,
            })
            .unwrap_or(Cow::Borrowed(raw.as_str()));
        overridden.into_owned()
    }
}

#[cfg(all(feature = "properties", any(feature = "garde", feature = "validator")))]
fn replace_known_effectives(
    mut text: String,
    ctxs: &[crate::properties_redaction::ScalarRedactionCtx],
) -> String {
    let mut pairs: Vec<&crate::properties_redaction::ScalarRedactionCtx> = ctxs
        .iter()
        .filter(|ctx| !ctx.effective.is_empty())
        .collect();

    pairs.sort_by_key(|ctx| std::cmp::Reverse(ctx.effective.len()));

    for ctx in pairs {
        if text.contains(&ctx.effective) {
            text = text.replace(&ctx.effective, &ctx.raw);
        }
    }

    text
}

#[cfg(all(feature = "properties", any(feature = "garde", feature = "validator")))]
pub(crate) fn redact_issue(mut issue: ValidationIssue) -> ValidationIssue {
    with_interp_redaction(|pairs| {
        if pairs.is_empty() {
            return issue;
        }

        if let Some(msg) = issue.message.take() {
            issue.message = Some(redact_with_ctxs(msg, pairs, "invalid interpolated value"));
        }

        issue.code = replace_known_effectives(std::mem::take(&mut issue.code), pairs);

        for (key, value) in &mut issue.params {
            *key = replace_known_effectives(std::mem::take(key), pairs);
            *value = redact_with_ctxs(std::mem::take(value), pairs, "<redacted>");
        }

        issue
    })
}

#[cfg(all(
    not(feature = "properties"),
    any(feature = "garde", feature = "validator")
))]
pub(crate) fn redact_issue(issue: ValidationIssue) -> ValidationIssue {
    issue
}

// Fallback location for Serde's static error constructors (`unknown_field`, `missing_field`,
// etc.) which have no `&self` and cannot access deserializer state. Thread-local because
// that is the only side-channel available. `Cell` suffices since `Location` is `Copy`.
//
// Set to the current key's location before each key deserialization via
// [`MissingFieldLocationGuard`]; read by [`maybe_attach_fallback_location`].
// The guard saves/restores the previous value on drop for correct nesting.
thread_local! {
    static MISSING_FIELD_FALLBACK: Cell<Option<Location>> = const { Cell::new(None) };
}

/// RAII guard for [`MISSING_FIELD_FALLBACK`]. Saves the previous value on creation,
/// restores it on drop.
pub(crate) struct MissingFieldLocationGuard {
    prev: Option<Location>,
}

impl MissingFieldLocationGuard {
    pub(crate) fn new(location: Location) -> Self {
        let prev = MISSING_FIELD_FALLBACK.with(|c| c.replace(Some(location)));
        Self { prev }
    }

    /// Update the fallback location in place, reusing the existing guard's restore point.
    #[allow(clippy::unused_self)] // The receiver ties this update to the lifetime of a live guard.
    pub(crate) fn replace_location(&mut self, location: Location) {
        MISSING_FIELD_FALLBACK.with(|c| c.set(Some(location)));
    }
}

impl Drop for MissingFieldLocationGuard {
    fn drop(&mut self) {
        MISSING_FIELD_FALLBACK.with(|c| c.set(self.prev));
    }
}

/// The reason why a string value was transformed during parsing and cannot be borrowed.
///
/// When deserializing to `&str`, the value must exist verbatim in the input. However,
/// certain YAML constructs require string transformation, making borrowing impossible.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransformReason {
    /// Escape sequences were processed (e.g., `\n`, `\t`, `\uXXXX` in double-quoted strings).
    EscapeSequence,
    /// Line folding was applied (folded block scalar `>`).
    LineFolding,
    /// Multi-line plain or quoted scalar with whitespace normalization.
    MultiLineNormalization,
    /// Block scalar processing (literal `|` or folded `>` with chomping/indentation).
    BlockScalarProcessing,
    /// Single-quoted string with `''` escape processing.
    SingleQuoteEscape,
    /// Borrowing is not supported because the deserializer does not have access to the full input
    /// buffer (for example, when deserializing from a `Read`er), or because the parser did not
    /// provide a slice that is a subslice of the original input.
    InputNotBorrowable,

    /// The parser returned an owned string for this scalar.
    ///
    /// In newer `granit-parser` versions, zero-copy is represented directly as `Cow::Borrowed`.
    /// If a scalar comes through as `Cow::Owned`, the deserializer cannot safely fabricate a
    /// borrow, because it would not refer to the original input buffer.
    ParserReturnedOwned,

    /// Property interpolation transformed the scalar.
    VariableInterpolation,
}

impl fmt::Display for TransformReason {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            TransformReason::EscapeSequence => write!(f, "escape sequence processing"),
            TransformReason::LineFolding => write!(f, "line folding"),
            TransformReason::MultiLineNormalization => {
                write!(f, "multi-line whitespace normalization")
            }
            TransformReason::BlockScalarProcessing => write!(f, "block scalar processing"),
            TransformReason::SingleQuoteEscape => write!(f, "single-quote escape processing"),
            TransformReason::InputNotBorrowable => {
                write!(f, "input is not available for borrowing")
            }
            TransformReason::ParserReturnedOwned => write!(f, "parser returned an owned string"),
            TransformReason::VariableInterpolation => write!(f, "variable interpolation"),
        }
    }
}

/// Error type compatible with `serde::de::Error`.
#[non_exhaustive]
pub enum Error {
    /// Free-form error with optional source location.
    Message {
        msg: String,
        location: Location,
    },

    /// Invalid deserializer options were provided.
    InvalidOptions {
        msg: String,
        location: Location,
    },

    /// Text primarily produced by a dependency (parser / validators).
    ///
    /// Renderers should call [`Localizer::override_external_message`] to allow callers
    /// to replace or translate this text.
    ExternalMessage {
        /// Dependency that produced the message and any structured source error.
        ///
        /// This is boxed to keep [`Error`] below Clippy's large-error threshold.
        source: Box<ExternalMessageSource>,
        msg: String,
        /// Stable-ish identifier when available (e.g. validator error code).
        code: Option<String>,
        /// Optional structured parameters when available.
        params: Vec<(String, String)>,
        location: Location,
    },
    /// Unexpected end of input.
    Eof {
        location: Location,
    },
    /// More than one YAML document was found when a single document was expected.
    ///
    /// This is typically returned by single-document entrypoints like `from_str*` / `from_slice*`
    /// / `read_to_end*` when the input stream contains multiple `---`-delimited documents.
    MultipleDocuments {
        /// Developer-facing hint (may mention specific APIs).
        hint: &'static str,
        location: Location,
    },
    /// Structural/type mismatch — something else than the expected token/value was seen.
    Unexpected {
        expected: &'static str,
        location: Location,
    },

    /// YAML merge (`<<`) value was not a mapping or a sequence of mappings.
    MergeValueNotMapOrSeqOfMaps {
        location: Location,
    },

    /// YAML merge keys (`<<`) are disabled by policy.
    MergeKeyNotAllowed {
        location: Location,
    },

    /// `!!binary` scalar could not be decoded as base64.
    InvalidBinaryBase64 {
        location: Location,
    },

    /// `!!binary` scalar decoded successfully but was not valid UTF-8 when a string was expected.
    BinaryNotUtf8 {
        location: Location,
    },

    /// A scalar was explicitly tagged but could not be deserialized into a string.
    TaggedScalarCannotDeserializeIntoString {
        location: Location,
    },

    /// Encountered a sequence end where it was not expected.
    UnexpectedSequenceEnd {
        location: Location,
    },

    /// Encountered a mapping end where it was not expected.
    UnexpectedMappingEnd {
        location: Location,
    },

    /// Invalid boolean literal in strict mode.
    InvalidBooleanStrict {
        location: Location,
    },

    /// Invalid char: null cannot be deserialized into `char`.
    InvalidCharNull {
        location: Location,
    },

    /// Invalid char: expected a single Unicode scalar value.
    InvalidCharNotSingleScalar {
        location: Location,
    },

    /// Cannot deserialize null into string.
    NullIntoString {
        location: Location,
    },

    /// Bytes (`&[u8]` / `Vec<u8>`) are not supported unless the scalar is tagged as `!!binary`.
    BytesNotSupportedMissingBinaryTag {
        location: Location,
    },

    /// Unexpected value for unit (`()`).
    UnexpectedValueForUnit {
        location: Location,
    },

    /// Unit struct expected an empty mapping.
    ExpectedEmptyMappingForUnitStruct {
        location: Location,
    },

    /// While skipping a node, a container end event was encountered unexpectedly.
    UnexpectedContainerEndWhileSkippingNode {
        location: Location,
    },

    /// Internal error: a seed was reused for a map key.
    InternalSeedReusedForMapKey {
        location: Location,
    },

    /// Internal error: value requested before key.
    ValueRequestedBeforeKey {
        location: Location,
    },

    /// Externally tagged enum: expected a string key.
    ExpectedStringKeyForExternallyTaggedEnum {
        location: Location,
    },

    /// Externally tagged enum: expected either a scalar or a mapping.
    ExternallyTaggedEnumExpectedScalarOrMapping {
        location: Location,
    },

    /// Unexpected value for unit enum variant.
    UnexpectedValueForUnitEnumVariant {
        location: Location,
    },

    /// Input was not valid UTF-8.
    InvalidUtf8Input,

    /// Alias replay counter overflow.
    AliasReplayCounterOverflow {
        location: Location,
    },

    /// Alias replay total event limit exceeded.
    AliasReplayLimitExceeded {
        total_replayed_events: usize,
        max_total_replayed_events: usize,
        location: Location,
    },

    /// Alias expansion limit exceeded for a single anchor.
    AliasExpansionLimitExceeded {
        anchor_id: usize,
        expansions: usize,
        max_expansions_per_anchor: usize,
        location: Location,
    },

    /// Alias replay stack depth limit exceeded.
    AliasReplayStackDepthExceeded {
        depth: usize,
        max_depth: usize,
        location: Location,
    },

    /// Folded block scalars must indent their content.
    FoldedBlockScalarMustIndentContent {
        location: Location,
    },

    /// Internal: depth counter underflow.
    InternalDepthUnderflow {
        location: Location,
    },

    /// Internal: recursion stack empty.
    InternalRecursionStackEmpty {
        location: Location,
    },

    /// recursive references require weak recursion types.
    RecursiveReferencesRequireWeakTypes {
        location: Location,
    },

    /// Scalar parsing failed for the requested target type.
    InvalidScalar {
        ty: &'static str,
        location: Location,
    },

    /// In a typeless position (e.g. `deserialize_any` targeting `serde_json::Value`), a
    /// scalar resolved to a non-finite float — NaN, ±Inf, or a decimal literal that
    /// overflows `f64` to infinity (e.g. `1e999`) — and
    /// the effective [`NonFiniteFloatPolicy`](crate::NonFiniteFloatPolicy) is `Reject`,
    /// rejecting it before passing it to the visitor.
    NonFiniteFloat {
        /// The offending scalar text as it appeared in the source (e.g. `.nan`, `1e999`).
        value: String,
        location: Location,
    },

    /// Serde-generated: invalid type.
    SerdeInvalidType {
        unexpected: String,
        expected: String,
        location: Location,
    },

    /// Serde-generated: invalid value.
    SerdeInvalidValue {
        unexpected: String,
        expected: String,
        location: Location,
    },

    /// Serde-generated: invalid sequence or container length.
    SerdeInvalidLength {
        /// Invalid length reported by the deserializer or visitor.
        len: usize,
        /// Description of the expected value supplied by Serde's visitor.
        expected: String,
        location: Location,
    },

    /// Serde-generated: unknown enum variant.
    SerdeUnknownVariant {
        variant: String,
        expected: Vec<&'static str>,
        location: Location,
    },

    /// Serde-generated: unknown field.
    SerdeUnknownField {
        field: String,
        expected: Vec<&'static str>,
        location: Location,
    },

    /// Serde-generated: missing required field.
    SerdeMissingField {
        field: &'static str,
        location: Location,
    },

    /// Encountered the end of a sequence or mapping while reading a key node.
    ///
    /// This indicates a structural mismatch in the input.
    UnexpectedContainerEndWhileReadingKeyNode {
        location: Location,
    },

    /// Duplicate key in a mapping.
    ///
    /// When the duplicate key can be rendered as a string-like scalar, `key` is provided.
    DuplicateMappingKey {
        key: Option<String>,
        location: Location,
    },

    /// Tagged enum name does not match the target enum.
    TaggedEnumMismatch {
        tagged: String,
        target: &'static str,
        location: Location,
    },

    /// Serde-generated error while deserializing an enum variant identifier.
    SerdeVariantId {
        msg: String,
        location: Location,
    },

    /// Expected the end of a mapping after an externally tagged enum variant value.
    ExpectedMappingEndAfterEnumVariantValue {
        location: Location,
    },
    ContainerEndMismatch {
        location: Location,
    },
    /// Alias references a non-existent anchor.
    UnknownAnchor {
        location: Location,
    },
    /// Cyclic include detected.
    CyclicInclude {
        id: String,
        stack: Vec<String>,
        location: Location,
    },
    /// `!include` currently only supports the scalar form: `!include <path>`
    UnsupportedIncludeForm {
        location: Location,
    },
    /// Failed to resolve include
    ResolverError {
        target: String,
        error: IncludeResolveError,
        stack: Vec<String>,
        location: Location,
    },
    /// Error related to an alias, with both reference (use-site) and defined (anchor) locations.
    ///
    /// `error` keeps the original error, so it renders with the active [`MessageFormatter`] and
    /// [`Localizer`], and [`std::error::Error::source`] returns it.
    AliasError {
        /// Default-rendered inner error retained for existing message-based handlers.
        ///
        /// The deserializer still populates this field, but renderers use `error` instead.
        #[deprecated(since = "2.0.0", note = "use error to access the original error")]
        msg: String,
        /// Original error, including its type and source location.
        error: Box<Error>,
        locations: Locations,
    },
    /// Error when parsing robotic and other extensions beyond standard YAML.
    /// (error in extension hook).
    HookError {
        msg: String,
        location: Location,
    },
    /// A `${NAME}` property reference could not be resolved from the configured property map.
    UnresolvedProperty {
        /// Property name that was requested.
        name: String,
        location: Location,
    },
    /// A `${...}` property candidate used an invalid property name.
    InvalidPropertyName {
        /// The invalid `${...}` candidate as it appeared in the YAML source.
        name: String,
        location: Location,
    },
    /// A `${NAME?text}` or `${NAME:?text}` reference required a value but the property was unset.
    /// `message` may be empty. Hints containing non-empty property-map values preserve their
    /// original source text instead of exposing the resolved values.
    PropertyRequiredButUnset {
        name: String,
        message: String,
        location: Location,
    },
    /// A `${NAME:?text}` reference required a non-empty value but the property was present and empty.
    /// `message` may be empty. Hints containing non-empty property-map values preserve their
    /// original source text instead of exposing the resolved values.
    PropertyRequiredButEmpty {
        name: String,
        message: String,
        location: Location,
    },
    /// A YAML budget limit was exceeded.
    Budget {
        breach: BudgetBreach,
        location: Location,
    },
    /// Unexpected I/O error. This may happen only when deserializing from a reader.
    ///
    /// The default display is `IO error`; [`std::error::Error::source`] provides
    /// the underlying cause so error chains do not repeat its message.
    IOError {
        cause: std::io::Error,
    },
    /// The value is targeted to the string field but can be interpreted as a number or boolean.
    /// This error can only happen if `no_schema` set true.
    QuotingRequired {
        value: String, // sanitized (checked) value that must be quoted
        location: Location,
    },

    /// The target type requires a borrowed string (`&str`), but the value was transformed
    /// during parsing (e.g., through escape processing, line folding, or multi-line normalization)
    /// and cannot be borrowed from the input.
    ///
    /// Use `String` or `Cow<str>` instead of `&str` to handle transformed values.
    CannotBorrowTransformedString {
        /// The reason why the string had to be transformed and cannot be borrowed.
        reason: TransformReason,
        location: Location,
    },

    /// Indentation does not meet the configured [`RequireIndent`](crate::RequireIndent) requirement.
    IndentationError {
        /// The indentation requirement that was violated.
        required: crate::indentation::RequireIndent,
        /// The actual indentation (in spaces) that was found.
        actual: usize,
        location: Location,
    },

    /// Wrap an error with the full input text, enabling rustc-like snippet rendering.
    WithSnippet {
        /// Cropped source windows used for snippet rendering.
        ///
        /// This intentionally does NOT store the full input text, to avoid retaining
        /// large YAML inputs inside errors.
        regions: Vec<CroppedRegion>,
        crop_radius: usize,
        error: Box<Error>,
    },

    /// Validation failure.
    #[cfg(any(feature = "garde", feature = "validator"))]
    ValidationError {
        source: ValidationSource,
        issues: Vec<ValidationIssue>,
        locations: PathMap,
    },

    /// Validation failures (multiple, if multiple validations fail)
    #[cfg(any(feature = "garde", feature = "validator"))]
    ValidationErrors {
        source: ValidationSource,
        errors: Vec<Error>,
    },

    /// An explicitly specified YAML tag is not supported by this crate.
    UnsupportedTag {
        tag: String,
        location: Location,
    },

    /// A struct field name's explicit tag violates the enabled
    /// [`crate::Options::reject_tagged_field_names`] policy.
    TaggedStructFieldName {
        tag: String,
        location: Location,
    },
}

impl Error {
    /// Wrap in an empty snippet wrapper, so include-site regions can be added for an error whose
    /// own source text is not available.
    #[cfg(feature = "include")]
    #[cold]
    #[inline(never)]
    pub(crate) fn with_no_snippet_regions(self, crop_radius: usize) -> Self {
        let inner = match self {
            Error::WithSnippet { error, .. } => *error,
            other => other,
        };
        Error::WithSnippet {
            regions: Vec::new(),
            crop_radius,
            error: Box::new(inner),
        }
    }

    #[cold]
    #[inline(never)]
    pub(crate) fn with_snippet(self, text: &str, crop_radius: usize) -> Self {
        self.with_snippet_named(text, "<input>", crop_radius)
    }

    #[cold]
    #[inline(never)]
    pub(crate) fn with_snippet_named(
        self,
        text: &str,
        source_name: &str,
        crop_radius: usize,
    ) -> Self {
        let source_name = sanitize_snippet_source_name(source_name);

        // Avoid nesting snippet wrappers: keep the innermost error and rebuild the
        // wrapper with freshly cropped source window.
        let inner = match self {
            Error::WithSnippet { error, .. } => *error,
            other => other,
        };

        // Keep snippet coordinates aligned with parsers that ignore a leading UTF-8 BOM.
        let text = text.strip_prefix('\u{FEFF}').unwrap_or(text);

        let regions = collect_snippet_regions(
            &inner,
            text,
            source_name.as_ref(),
            crate::de_snippet::LineMapping::Identity,
            crop_radius,
        );

        Error::WithSnippet {
            regions,
            crop_radius,
            error: Box::new(inner),
        }
    }

    #[cfg(feature = "include")]
    #[cold]
    #[inline(never)]
    pub(crate) fn with_additional_snippet_named(
        mut self,
        text: &str,
        source_name: &str,
        location: &Location,
        crop_radius: usize,
    ) -> Self {
        let source_name = sanitize_snippet_source_name(source_name);

        if crop_radius == 0 || *location == Location::UNKNOWN {
            return self;
        }

        let text = text.strip_prefix('\u{FEFF}').unwrap_or(text);
        let mapping = crate::de_snippet::LineMapping::Identity;

        let Some(region) =
            cropped_region_for_location(text, source_name.as_ref(), location, mapping, crop_radius)
        else {
            return self;
        };

        if let Error::WithSnippet {
            ref mut regions, ..
        } = self
        {
            regions.push(region);
        }
        self
    }

    #[cfg(feature = "include")]
    #[cold]
    #[inline(never)]
    pub(crate) fn with_additional_snippet_offset_named(
        mut self,
        text: &str,
        start_line: usize,
        source_name: &str,
        location: &Location,
        crop_radius: usize,
    ) -> Self {
        let source_name = sanitize_snippet_source_name(source_name);

        if crop_radius == 0 || *location == Location::UNKNOWN {
            return self;
        }

        let text = text.strip_prefix('\u{FEFF}').unwrap_or(text);
        let mapping = crate::de_snippet::LineMapping::Offset { start_line };

        let Some(region) =
            cropped_region_for_location(text, source_name.as_ref(), location, mapping, crop_radius)
        else {
            return self;
        };

        if let Error::WithSnippet {
            ref mut regions, ..
        } = self
        {
            regions.push(region);
        }
        self
    }

    #[cold]
    #[inline(never)]
    pub(crate) fn with_snippet_offset_named(
        self,
        text: &str,
        start_line: usize,
        source_name: &str,
        crop_radius: usize,
    ) -> Self {
        let source_name = sanitize_snippet_source_name(source_name);

        let inner = match self {
            Error::WithSnippet { error, .. } => *error,
            other => other,
        };

        // Keep snippet coordinates aligned with parsers that ignore a leading UTF-8 BOM.
        let text = text.strip_prefix('\u{FEFF}').unwrap_or(text);

        let regions = collect_snippet_regions(
            &inner,
            text,
            source_name.as_ref(),
            crate::de_snippet::LineMapping::Offset { start_line },
            crop_radius,
        );

        Error::WithSnippet {
            regions,
            crop_radius,
            error: Box::new(inner),
        }
    }

    /// Provide "no snippet" version for cases when snippet rendering is not desired.
    #[must_use]
    pub fn without_snippet(&self) -> &Self {
        match self {
            Error::WithSnippet { error, .. } => error,
            other => other,
        }
    }

    /// Whether a persistent interpolation-budget breach ended this operation,
    /// including errors wrapped with alias locations or source snippets.
    pub(crate) fn is_property_interpolation_budget_breach(&self) -> bool {
        matches!(
            original_error(self),
            Error::Budget {
                breach: BudgetBreach::PropertyExpansionDepth { .. }
                    | BudgetBreach::PropertyInterpolationWork { .. },
                ..
            }
        )
    }

    /// Render this error using the built-in developer formatter.
    ///
    /// This is the deferred-rendering entrypoint. It is equivalent to `Display`/`to_string()`
    /// output, but also allows callers to choose a custom [`MessageFormatter`] via
    /// [`Error::render_with_options`].
    #[must_use]
    pub fn render(&self) -> String {
        self.render_with_options(RenderOptions::default())
    }

    /// Render this error using a custom message formatter.
    #[must_use]
    pub fn render_with_formatter(&self, formatter: &dyn MessageFormatter) -> String {
        self.render_with_options(RenderOptions {
            formatter,
            ..RenderOptions::default()
        })
    }

    /// Render this error using the provided options.
    ///
    /// To append to an existing writer, use [`Error::render_to`].
    #[must_use]
    pub fn render_with_options(&self, options: RenderOptions<'_>) -> String {
        RenderDisplay { err: self, options }.to_string()
    }

    /// Append this error to `writer` using the provided rendering `options`.
    ///
    /// Produces the same text as [`Error::render_with_options`] without first
    /// collecting the complete output in an intermediate `String`. Message
    /// formatters and snippet rendering still perform their own allocations.
    ///
    /// Returns [`fmt::Result`], propagating any error from `writer`. On failure,
    /// the writer may already contain part of the rendered error.
    ///
    /// ```rust
    /// let err = serde_saphyr::from_str::<u16>("eighty").unwrap_err();
    /// let mut output = String::from("invalid configuration: ");
    /// err.render_to(&mut output, serde_saphyr::render_options! {
    ///     source_name: Some("config.yaml"),
    /// })?;
    /// assert!(output.starts_with("invalid configuration: "));
    /// assert!(output.contains("config.yaml:1:1"));
    /// # Ok::<(), std::fmt::Error>(())
    /// ```
    pub fn render_to<W: fmt::Write + ?Sized>(
        &self,
        writer: &mut W,
        options: RenderOptions<'_>,
    ) -> fmt::Result {
        writer.write_fmt(format_args!("{}", RenderDisplay { err: self, options }))
    }

    /// Construct a `Message` error with no known location.
    ///
    /// Arguments:
    /// - `s`: human-readable message.
    ///
    /// Returns:
    /// - `Error::Message` pointing at [`Location::UNKNOWN`].
    ///
    /// Called by:
    /// - Scalar parsers and helpers throughout this module.
    #[cold]
    #[inline(never)]
    pub(crate) fn msg<S: Into<String>>(s: S) -> Self {
        Error::Message {
            msg: s.into(),
            location: Location::UNKNOWN,
        }
    }

    /// Construct an `InvalidOptions` error with no known source location.
    #[cold]
    #[inline(never)]
    pub(crate) fn invalid_options<S: Into<String>>(s: S) -> Self {
        Error::InvalidOptions {
            msg: s.into(),
            location: Location::UNKNOWN,
        }
    }

    /// Construct a `QuotingRequired` error with no known location.
    /// Called by:
    /// - Deserializer, when deserializing into string if `no_schema` set to true.
    #[cold]
    #[inline(never)]
    pub(crate) fn quoting_required(value: &str, interpolated: bool) -> Self {
        // Ensure the value really is like number or boolean (do not reflect back content
        // that may be used for attack)
        let location = Location::UNKNOWN;
        let value = if !interpolated
            && (parse_yaml12_float::<f64>(value, location, SfTag::None, false).is_ok()
                || parse_int_signed::<i128>(value, "i128", location, false).is_ok()
                || parse_yaml11_bool(value).is_some()
                || scalar_is_nullish(value, &ScalarStyle::Plain))
        {
            value.to_string()
        } else {
            String::new()
        };
        Error::QuotingRequired { value, location }
    }

    /// Convenience for an `Unexpected` error pre-filled with a human phrase.
    ///
    /// Arguments:
    /// - `what`: short description like "sequence start".
    ///
    /// Returns:
    /// - `Error::Unexpected` at unknown location.
    ///
    /// Called by:
    /// - Deserializer methods that validate the next event kind.
    #[cold]
    #[inline(never)]
    pub(crate) fn unexpected(what: &'static str) -> Self {
        Error::Unexpected {
            expected: what,
            location: Location::UNKNOWN,
        }
    }

    /// Construct an unexpected end-of-input error with unknown location.
    ///
    /// Used by:
    /// - Lookahead and pull methods when `None` appears prematurely.
    #[cold]
    #[inline(never)]
    pub(crate) fn eof() -> Self {
        Error::Eof {
            location: Location::UNKNOWN,
        }
    }

    #[cold]
    #[inline(never)]
    pub(crate) fn multiple_documents(hint: &'static str) -> Self {
        Error::MultipleDocuments {
            hint,
            location: Location::UNKNOWN,
        }
    }

    #[cfg(any(feature = "garde", feature = "validator"))]
    pub(crate) fn validation_error(
        source: ValidationSource,
        issues: Vec<ValidationIssue>,
        locations: PathMap,
    ) -> Self {
        Error::ValidationError {
            source,
            issues,
            locations,
        }
    }

    #[cfg(any(feature = "garde", feature = "validator"))]
    pub(crate) fn validation_errors(source: ValidationSource, errors: Vec<Error>) -> Self {
        Error::ValidationErrors { source, errors }
    }

    #[cfg(any(feature = "garde", feature = "validator"))]
    pub(crate) fn is_validation_error(&self) -> bool {
        matches!(self, Error::ValidationError { .. })
    }

    /// Construct an `UnknownAnchor` error (unknown location).
    ///
    /// Called by:
    /// - Alias replay logic in the live event source.
    #[cold]
    #[inline(never)]
    pub(crate) fn unknown_anchor() -> Self {
        Error::UnknownAnchor {
            location: Location::UNKNOWN,
        }
    }

    /// Construct a `CannotBorrowTransformedString` error for the given reason.
    ///
    /// This error is returned when deserializing to `&str` but the string value
    /// was transformed during parsing and cannot be borrowed from the input.
    #[cold]
    #[inline(never)]
    #[must_use]
    pub fn cannot_borrow_transformed(reason: TransformReason) -> Self {
        Error::CannotBorrowTransformedString {
            reason,
            location: Location::UNKNOWN,
        }
    }

    /// Attach/override a concrete location to this error and return it.
    ///
    /// Arguments:
    /// - `set_location`: location to store in the error.
    ///
    /// Returns:
    /// - The same `Error` with location updated.
    ///
    /// Called by:
    /// - Most error paths once the event position becomes known.
    #[cold]
    #[inline(never)]
    pub(crate) fn with_location(mut self, set_location: Location) -> Self {
        match &mut self {
            Error::Message { location, .. }
            | Error::InvalidOptions { location, .. }
            | Error::ExternalMessage { location, .. }
            | Error::Eof { location }
            | Error::MultipleDocuments { location, .. }
            | Error::Unexpected { location, .. }
            | Error::MergeValueNotMapOrSeqOfMaps { location }
            | Error::MergeKeyNotAllowed { location }
            | Error::UnsupportedTag { location, .. }
            | Error::TaggedStructFieldName { location, .. }
            | Error::InvalidBinaryBase64 { location }
            | Error::BinaryNotUtf8 { location }
            | Error::TaggedScalarCannotDeserializeIntoString { location }
            | Error::UnexpectedSequenceEnd { location }
            | Error::UnexpectedMappingEnd { location }
            | Error::InvalidBooleanStrict { location }
            | Error::InvalidCharNull { location }
            | Error::InvalidCharNotSingleScalar { location }
            | Error::NullIntoString { location }
            | Error::BytesNotSupportedMissingBinaryTag { location }
            | Error::UnexpectedValueForUnit { location }
            | Error::ExpectedEmptyMappingForUnitStruct { location }
            | Error::UnexpectedContainerEndWhileSkippingNode { location }
            | Error::InternalSeedReusedForMapKey { location }
            | Error::ValueRequestedBeforeKey { location }
            | Error::ExpectedStringKeyForExternallyTaggedEnum { location }
            | Error::ExternallyTaggedEnumExpectedScalarOrMapping { location }
            | Error::UnexpectedValueForUnitEnumVariant { location }
            | Error::AliasReplayCounterOverflow { location }
            | Error::AliasReplayLimitExceeded { location, .. }
            | Error::AliasExpansionLimitExceeded { location, .. }
            | Error::AliasReplayStackDepthExceeded { location, .. }
            | Error::FoldedBlockScalarMustIndentContent { location }
            | Error::InternalDepthUnderflow { location }
            | Error::InternalRecursionStackEmpty { location }
            | Error::RecursiveReferencesRequireWeakTypes { location }
            | Error::InvalidScalar { location, .. }
            | Error::NonFiniteFloat { location, .. }
            | Error::SerdeInvalidType { location, .. }
            | Error::SerdeInvalidValue { location, .. }
            | Error::SerdeInvalidLength { location, .. }
            | Error::SerdeUnknownVariant { location, .. }
            | Error::SerdeUnknownField { location, .. }
            | Error::SerdeMissingField { location, .. }
            | Error::UnexpectedContainerEndWhileReadingKeyNode { location }
            | Error::DuplicateMappingKey { location, .. }
            | Error::TaggedEnumMismatch { location, .. }
            | Error::SerdeVariantId { location, .. }
            | Error::ExpectedMappingEndAfterEnumVariantValue { location }
            | Error::HookError { location, .. }
            | Error::UnresolvedProperty { location, .. }
            | Error::InvalidPropertyName { location, .. }
            | Error::PropertyRequiredButUnset { location, .. }
            | Error::PropertyRequiredButEmpty { location, .. }
            | Error::ContainerEndMismatch { location, .. }
            | Error::UnknownAnchor { location, .. }
            | Error::CyclicInclude { location, .. }
            | Error::UnsupportedIncludeForm { location, .. }
            | Error::ResolverError { location, .. }
            | Error::QuotingRequired { location, .. }
            | Error::Budget { location, .. }
            | Error::CannotBorrowTransformedString { location, .. }
            | Error::IndentationError { location, .. } => {
                *location = set_location;
            }
            Error::InvalidUtf8Input => {}
            Error::IOError { .. } => {} // this error does not support location
            Error::AliasError { .. } => {
                // AliasError carries its own Locations; don't override with a single location.
            }
            Error::WithSnippet { error, .. } => {
                let inner = *std::mem::replace(error, Box::new(Error::eof()));
                **error = inner.with_location(set_location);
            }
            #[cfg(any(feature = "garde", feature = "validator"))]
            Error::ValidationError { .. } => {
                // Validation errors carry their own per-path locations.
            }
            #[cfg(any(feature = "garde", feature = "validator"))]
            Error::ValidationErrors { .. } => {
                // Aggregate validation errors carry their own per-entry locations.
            }
        }
        self
    }

    /// If the error has a known location, return it.
    ///
    /// Returns:
    /// - `Some(Location)` when coordinates are known; `None` otherwise.
    ///
    /// Used by:
    /// - Callers that want to surface precise positions to users.
    #[must_use]
    pub fn location(&self) -> Option<Location> {
        #[cfg(any(feature = "garde", feature = "validator"))]
        if let Error::ValidationErrors { errors, .. } = self {
            // Preserve aggregate behavior: use the first child that has a location,
            // rather than requiring the first child itself to have one.
            return errors.iter().find_map(Error::location);
        }

        self.locations().and_then(Locations::primary_location)
    }
    /// Return a pair of locations associated with this error.
    ///
    /// - For syntax and other errors that carry a single [`Location`], this returns two
    ///   identical locations.
    /// - For validation errors (when the `garde` / `validator` feature is enabled), this returns
    ///   the `(reference_location, defined_location)` pair for the *first* validation entry.
    ///
    ///   These two locations may differ when YAML anchors/aliases are involved.
    /// - Returns `None` when no meaningful location information is available.
    #[must_use]
    pub fn locations(&self) -> Option<Locations> {
        match self {
            Error::Message { location, .. }
            | Error::InvalidOptions { location, .. }
            | Error::ExternalMessage { location, .. }
            | Error::Eof { location }
            | Error::MultipleDocuments { location, .. }
            | Error::Unexpected { location, .. }
            | Error::MergeValueNotMapOrSeqOfMaps { location }
            | Error::MergeKeyNotAllowed { location }
            | Error::UnsupportedTag { location, .. }
            | Error::TaggedStructFieldName { location, .. }
            | Error::InvalidBinaryBase64 { location }
            | Error::BinaryNotUtf8 { location }
            | Error::TaggedScalarCannotDeserializeIntoString { location }
            | Error::UnexpectedSequenceEnd { location }
            | Error::UnexpectedMappingEnd { location }
            | Error::InvalidBooleanStrict { location }
            | Error::InvalidCharNull { location }
            | Error::InvalidCharNotSingleScalar { location }
            | Error::NullIntoString { location }
            | Error::BytesNotSupportedMissingBinaryTag { location }
            | Error::UnexpectedValueForUnit { location }
            | Error::ExpectedEmptyMappingForUnitStruct { location }
            | Error::UnexpectedContainerEndWhileSkippingNode { location }
            | Error::InternalSeedReusedForMapKey { location }
            | Error::ValueRequestedBeforeKey { location }
            | Error::ExpectedStringKeyForExternallyTaggedEnum { location }
            | Error::ExternallyTaggedEnumExpectedScalarOrMapping { location }
            | Error::UnexpectedValueForUnitEnumVariant { location }
            | Error::AliasReplayCounterOverflow { location }
            | Error::AliasReplayLimitExceeded { location, .. }
            | Error::AliasExpansionLimitExceeded { location, .. }
            | Error::AliasReplayStackDepthExceeded { location, .. }
            | Error::FoldedBlockScalarMustIndentContent { location }
            | Error::InternalDepthUnderflow { location }
            | Error::InternalRecursionStackEmpty { location }
            | Error::RecursiveReferencesRequireWeakTypes { location }
            | Error::InvalidScalar { location, .. }
            | Error::NonFiniteFloat { location, .. }
            | Error::SerdeInvalidType { location, .. }
            | Error::SerdeInvalidValue { location, .. }
            | Error::SerdeInvalidLength { location, .. }
            | Error::SerdeUnknownVariant { location, .. }
            | Error::SerdeUnknownField { location, .. }
            | Error::SerdeMissingField { location, .. }
            | Error::UnexpectedContainerEndWhileReadingKeyNode { location }
            | Error::DuplicateMappingKey { location, .. }
            | Error::TaggedEnumMismatch { location, .. }
            | Error::SerdeVariantId { location, .. }
            | Error::ExpectedMappingEndAfterEnumVariantValue { location }
            | Error::HookError { location, .. }
            | Error::UnresolvedProperty { location, .. }
            | Error::InvalidPropertyName { location, .. }
            | Error::PropertyRequiredButUnset { location, .. }
            | Error::PropertyRequiredButEmpty { location, .. }
            | Error::ContainerEndMismatch { location, .. }
            | Error::UnknownAnchor { location, .. }
            | Error::CyclicInclude { location, .. }
            | Error::UnsupportedIncludeForm { location, .. }
            | Error::ResolverError { location, .. }
            | Error::QuotingRequired { location, .. }
            | Error::Budget { location, .. }
            | Error::CannotBorrowTransformedString { location, .. }
            | Error::IndentationError { location, .. } => Locations::same(location),
            Error::InvalidUtf8Input => None,
            Error::IOError { .. } => None,
            Error::AliasError { locations, .. } => Some(*locations),
            Error::WithSnippet { error, .. } => error.locations(),
            #[cfg(any(feature = "garde", feature = "validator"))]
            Error::ValidationError {
                issues, locations, ..
            } => issues
                .first()
                .and_then(|issue| locations.search_with_ancestor_fallback(&issue.path))
                .map(|(locs, _)| locs),
            #[cfg(any(feature = "garde", feature = "validator"))]
            Error::ValidationErrors { errors, .. } => errors.first().and_then(Error::locations),
        }
    }

    /// Map a `granit_parser::ScanError` into our error type with location.
    ///
    /// Called by:
    /// - The live events adapter when the underlying parser fails.
    #[cold]
    #[inline(never)]
    pub(crate) fn from_scan_error(err: ScanError) -> Self {
        let err = match err.try_into_input_io_error() {
            Ok(error) => {
                let cause = match error.try_into_io_error() {
                    Ok(error) => error,
                    Err(error) => {
                        let kind = error
                            .io_error()
                            .map_or(std::io::ErrorKind::Other, std::io::Error::kind);
                        std::io::Error::new(kind, error)
                    }
                };
                return Error::IOError { cause };
            }
            Err(err) => err,
        };

        let mark = err.marker();
        let location = Location::new(mark.line(), mark.col() + 1)
            .with_span(crate::Span::new(mark.index() as u64, 1));

        match err.kind() {
            ErrorKind::InputDecoding { message } => {
                return Error::IOError {
                    cause: std::io::Error::new(std::io::ErrorKind::InvalidData, message.clone()),
                };
            }
            ErrorKind::InputByteLimitExceeded { limit } => {
                return Error::IOError {
                    cause: std::io::Error::new(
                        std::io::ErrorKind::FileTooLarge,
                        format!("input size limit of {limit} bytes exceeded"),
                    ),
                };
            }
            ErrorKind::MultipleDocumentsUnsupported => {
                return Error::MultipleDocuments {
                    hint: "only one document is supported in this context",
                    location,
                };
            }
            ErrorKind::UnknownAnchor => return Error::UnknownAnchor { location },
            _ => {}
        }

        let message = err.info();
        Error::ExternalMessage {
            source: Box::new(ExternalMessageSource::Parser(err)),
            msg: message,
            code: None,
            params: Vec::new(),
            location,
        }
    }
}

fn fmt_error_plain_with_formatter(
    f: &mut fmt::Formatter<'_>,
    err: &Error,
    formatter: &dyn MessageFormatter,
    line_offset: u64,
) -> fmt::Result {
    let mut err = err;
    while let Error::WithSnippet { error, .. } = err {
        err = error;
    }

    // Validation formatters compose their own per-issue locations. Give both built-in
    // and custom hooks a temporary display view, leaving the stored error untouched.
    // The default (zero-offset) path does not copy any validation data.
    #[cfg(any(feature = "garde", feature = "validator"))]
    let display_error = if line_offset != 0
        && let Error::ValidationError {
            source,
            issues,
            locations,
        } = err
    {
        let mut locations = locations.clone();
        for locs in locations.map.values_mut() {
            locs.reference_location = display_location(locs.reference_location, line_offset);
            locs.defined_location = display_location(locs.defined_location, line_offset);
        }
        Some(Error::ValidationError {
            source: *source,
            issues: issues.clone(),
            locations,
        })
    } else {
        None
    };
    #[cfg(any(feature = "garde", feature = "validator"))]
    let err = display_error.as_ref().unwrap_or(err);

    #[cfg(any(feature = "garde", feature = "validator"))]
    if matches!(err, Error::ValidationError { .. })
        && let Some(lines) = formatter.format_validation_issue_lines(err)
    {
        let lines: Vec<_> = lines
            .into_iter()
            .map(|line| sanitize_message_text(Cow::Owned(line)).into_owned())
            .collect();
        let joined = formatter.localizer().join_validation_issues(&lines);
        // Only the join hook introduces layout. Escape its other control characters
        // without turning the separators between already-sanitized issues into text.
        for (index, line) in joined.split('\n').enumerate() {
            if index > 0 {
                writeln!(f)?;
            }
            write!(f, "{}", sanitize_message_text(Cow::Borrowed(line)))?;
        }
        return Ok(());
    }

    let msg = render_message_text(formatter, err);

    let msg = if let Some(location) = distinct_alias_error_location(err) {
        sanitize_message_text(
            formatter
                .localizer()
                .attach_location(msg, display_location(location, line_offset)),
        )
    } else {
        msg
    };

    // Preserve the outer use and definition as context for the original failing value.
    let msg = if let Error::AliasError { locations, .. } = err
        && locations.reference_location != Location::UNKNOWN
        && locations.defined_location != Location::UNKNOWN
        && locations.defined_location != locations.reference_location
    {
        let suffix = sanitize_message_text(Cow::Owned(
            formatter
                .localizer()
                .alias_defined_at(display_location(locations.defined_location, line_offset)),
        ));
        Cow::Owned(format!("{msg}{suffix}"))
    } else {
        msg
    };

    // Validation errors embed per-issue locations in their formatted message (potentially
    // multiple distinct locations). Do not attach a single top-level location suffix here,
    // or we'd duplicate location wording.
    #[cfg(any(feature = "garde", feature = "validator"))]
    if matches!(err, Error::ValidationError { .. }) {
        return write!(f, "{msg}");
    }

    if let Error::AliasError { locations, .. } = err
        && locations.reference_location != Location::UNKNOWN
    {
        let suffix = sanitize_message_text(Cow::Owned(
            formatter
                .localizer()
                .alias_used_at(display_location(locations.reference_location, line_offset)),
        ));
        write!(f, "{msg}{suffix}")?;
    } else if let Some(loc) = err.location() {
        fmt_with_location(
            f,
            formatter.localizer(),
            msg.as_ref(),
            &display_location(loc, line_offset),
        )?;
    } else {
        write!(f, "{msg}")?;
    }

    #[cfg(any(feature = "garde", feature = "validator"))]
    if let Error::ValidationErrors { errors, .. } = err {
        for err in errors {
            writeln!(f)?;
            writeln!(f)?;
            fmt_error_plain_with_formatter(f, err, formatter, line_offset)?;
        }
    }

    Ok(())
}

fn pick_cropped_region<'a>(
    regions: &'a [CroppedRegion],
    location: &Location,
) -> Option<&'a CroppedRegion> {
    // Different locations may share a vertical window but have different horizontal crops.
    if let Some(region) = regions.iter().find(|region| region.location == *location) {
        return Some(region);
    }
    let source_id = location.source_id();

    if source_id != 0 {
        if let Some(region) = regions.iter().find(|r| r.covers_exact_source(location)) {
            return Some(region);
        }
        if let Some(region) = regions.iter().find(|r| r.location.source_id() == source_id) {
            return Some(region);
        }
        if let Some(region) = regions
            .iter()
            .find(|r| r.location.source_id() == 0 && r.covers(location))
        {
            return Some(region);
        }
        return None;
    }

    regions
        .iter()
        .find(|r| r.covers(location))
        .or_else(|| regions.first())
}

fn writeln_anchor_intro(
    f: &mut fmt::Formatter<'_>,
    l10n: &dyn Localizer,
    def_loc: Location,
    def_region: &CroppedRegion,
    line_offset: u64,
) -> fmt::Result {
    let line = sanitize_message_text(Cow::Owned(
        l10n.value_comes_from_the_anchor(display_location(def_loc, line_offset)),
    ));
    let Some(prefix) = snippet_window_frame_prefix_offset(
        def_region.text.as_str(),
        def_region.start_line,
        &def_loc,
        line_offset,
    ) else {
        return writeln!(f, "{line}");
    };

    match line.strip_prefix("  |") {
        Some(rest) => writeln!(f, "{prefix}{rest}"),
        None => writeln!(f, "{line}"),
    }
}

struct RenderDisplay<'a> {
    err: &'a Error,
    options: RenderOptions<'a>,
}

impl fmt::Display for RenderDisplay<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut options = self.options;
        options.line_offset = render_line_offset(self.err, options.line_offset);
        fmt_error_rendered(f, self.err, options)
    }
}

fn fmt_error_rendered(
    f: &mut fmt::Formatter<'_>,
    err: &Error,
    options: RenderOptions<'_>,
) -> fmt::Result {
    if options.snippets == SnippetMode::Off {
        return fmt_error_plain_with_formatter(f, err, options.formatter, options.line_offset);
    }

    match err {
        #[cfg(any(feature = "garde", feature = "validator"))]
        Error::ValidationErrors { errors, .. } => {
            let msg = render_message_text(options.formatter, err);
            if !msg.is_empty() {
                writeln!(f, "{msg}")?;
            }
            let mut first = true;
            for err in errors {
                if !first {
                    writeln!(f)?;
                    writeln!(f)?;
                }
                first = false;
                fmt_error_rendered(f, err, options)?;
            }
            Ok(())
        }

        Error::WithSnippet {
            regions,
            crop_radius,
            error,
        } => {
            if *crop_radius == 0 {
                // Treat as "snippet disabled".
                return fmt_error_plain_with_formatter(
                    f,
                    error,
                    options.formatter,
                    options.line_offset,
                );
            }

            if regions.is_empty() {
                return fmt_error_plain_with_formatter(
                    f,
                    error,
                    options.formatter,
                    options.line_offset,
                );
            }

            // Validation errors have custom snippet formatting (paths, alias context, and
            // messages without location duplication).
            #[cfg(any(feature = "garde", feature = "validator"))]
            if let Error::ValidationError {
                source,
                issues,
                locations,
            } = error.as_ref()
            {
                return fmt_validation_error_with_snippets_offset(
                    f,
                    options,
                    &source.external_message_source(),
                    issues,
                    locations,
                    regions,
                    *crop_radius,
                );
            }
            #[cfg(any(feature = "garde", feature = "validator"))]
            if let Error::ValidationErrors { errors, .. } = error.as_ref() {
                let msg = render_message_text(options.formatter, error);
                if !msg.is_empty() {
                    writeln!(f, "{msg}")?;
                }
                let mut first = true;
                for err in errors {
                    if !first {
                        writeln!(f)?;
                        writeln!(f)?;
                    }
                    first = false;
                    fmt_error_with_snippets_offset(f, err, regions, *crop_radius, options)?;
                }
                return Ok(());
            }

            // Render a snippet from the cropped source window. If anything is missing,
            // fall back to the plain nested error.
            let Some(location) = error.location() else {
                return fmt_error_plain_with_formatter(
                    f,
                    error,
                    options.formatter,
                    options.line_offset,
                );
            };
            if location == Location::UNKNOWN {
                return fmt_error_plain_with_formatter(
                    f,
                    error,
                    options.formatter,
                    options.line_offset,
                );
            }

            let l10n = options.formatter.localizer();

            let Some(region) = pick_cropped_region(regions, &location) else {
                // No window for the error's own source (an included source whose text was not
                // retained): print the plain error, then the include sites as context.
                fmt_error_plain_with_formatter(f, error, options.formatter, options.line_offset)?;
                if location.source_id() != 0 {
                    for extra_region in regions {
                        writeln!(f)?;
                        writeln!(f, "{}:", sanitize_message_text(l10n.included_from_here()))?;
                        extra_region
                            .snippet(*crop_radius, options)
                            .fmt_or_fallback(f, Level::NOTE, l10n, "", &extra_region.location)?;
                    }
                }
                return Ok(());
            };

            // Dual-location rendering: show both the reference and the definition window.
            let dual_locations = error.locations().filter(|locs| {
                locs.reference_location != Location::UNKNOWN
                    && locs.defined_location != Location::UNKNOWN
                    && locs.reference_location != locs.defined_location
            });

            let msg = render_message_text(options.formatter, error);
            let failing_location = distinct_alias_error_location(error);

            if let Some(locs) = dual_locations {
                let ref_loc = locs.reference_location;
                let def_loc = locs.defined_location;

                let used_region = pick_cropped_region(regions, &ref_loc).unwrap_or(region);
                let label = l10n.value_used_here();
                let ctx = used_region.snippet(*crop_radius, options);
                ctx.fmt_or_fallback_with_label(
                    f,
                    Level::ERROR,
                    l10n,
                    msg.as_ref(),
                    label.as_ref(),
                    &ref_loc,
                )?;

                let def_region = pick_cropped_region(regions, &def_loc).unwrap_or(region);
                writeln!(f)?;
                writeln_anchor_intro(f, l10n, def_loc, def_region, options.line_offset)?;
                fmt_snippet_window_offset_or_fallback(
                    f,
                    &def_loc,
                    def_region.text.as_str(),
                    def_region.start_line,
                    l10n.defined_window().as_ref(),
                    *crop_radius,
                    options.line_offset,
                )?;
            } else {
                // Single location rendering.
                let ctx = region.snippet(*crop_radius, options);
                ctx.fmt_or_fallback(f, Level::ERROR, l10n, msg.as_ref(), &location)?;

                for extra_region in regions {
                    if std::ptr::eq(extra_region, region)
                        || failing_location == Some(extra_region.location)
                    {
                        continue;
                    }
                    writeln!(f)?;
                    writeln!(f, "{}:", sanitize_message_text(l10n.included_from_here()))?;
                    let extra_ctx = extra_region.snippet(*crop_radius, options);
                    extra_ctx.fmt_or_fallback(f, Level::NOTE, l10n, "", &extra_region.location)?;
                }
            }

            if let Some(location) = failing_location {
                writeln!(f)?;
                let label = l10n.error_here();
                if let Some(region) = pick_cropped_region(regions, &location) {
                    let ctx = region.snippet(*crop_radius, options);
                    ctx.fmt_or_fallback(f, Level::NOTE, l10n, label.as_ref(), &location)?;
                } else {
                    fmt_with_location(
                        f,
                        l10n,
                        label.as_ref(),
                        &display_location(location, options.line_offset),
                    )?;
                }
            }
            Ok(())
        }
        _ => fmt_error_plain_with_formatter(f, err, options.formatter, options.line_offset),
    }
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt_error_rendered(f, self, RenderOptions::default())
    }
}

impl fmt::Debug for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(self, f)
    }
}

#[cfg(any(feature = "garde", feature = "validator"))]
fn fmt_validation_error_with_snippets_offset(
    f: &mut fmt::Formatter<'_>,
    options: RenderOptions<'_>,
    source: &ExternalMessageSource,
    issues: &[ValidationIssue],
    locations: &PathMap,
    regions: &[CroppedRegion],
    crop_radius: usize,
) -> fmt::Result {
    let l10n = options.formatter.localizer();
    let line_offset = options.line_offset;
    // Regions cropped for the issues' own locations. Only the remaining regions are include
    // sites ("included from here"); the issue regions must not be repeated as such.
    let issue_locations: HashSet<Location> = issues
        .iter()
        .filter_map(|issue| locations.search_with_ancestor_fallback(&issue.path))
        .flat_map(|(locs, _)| [locs.reference_location, locs.defined_location])
        .filter(|loc| *loc != Location::UNKNOWN)
        .collect();
    // Classify once so rendering each issue does not rescan all issue locations/regions.
    let include_regions: Vec<&CroppedRegion> = regions
        .iter()
        .filter(|region| !issue_locations.contains(&region.location))
        .collect();

    let mut first = true;
    for issue in issues {
        if !first {
            writeln!(f)?;
        }
        first = false;

        let original_leaf = issue
            .path
            .leaf_string()
            .unwrap_or_else(|| l10n.root_path_label().into_owned());

        let (locs, resolved_leaf) = locations
            .search_with_ancestor_fallback(&issue.path)
            .unwrap_or((Locations::UNKNOWN, original_leaf));

        let ref_loc = locs.reference_location;
        let def_loc = locs.defined_location;

        let resolved_path = format_path_with_resolved_leaf(&issue.path, &resolved_leaf);
        let entry = issue.display_entry_overridden(l10n, (*source).clone());
        let base_msg = sanitize_message_text(Cow::Owned(
            l10n.validation_base_message(&entry, &resolved_path),
        ));

        let mut rendered_regions = Vec::new();

        match (ref_loc, def_loc) {
            (Location::UNKNOWN, Location::UNKNOWN) => {
                write!(f, "{base_msg}")?;
            }
            (r, d) if r != Location::UNKNOWN && (d == Location::UNKNOWN || d == r) => {
                if let Some(region) = pick_cropped_region(regions, &r) {
                    rendered_regions.push(std::ptr::from_ref(region));
                    let ctx = region.snippet(crop_radius, options);
                    ctx.fmt_or_fallback(f, Level::ERROR, l10n, &base_msg, &r)?;
                } else {
                    fmt_with_location(f, l10n, &base_msg, &display_location(r, line_offset))?;
                }
            }
            (r, d) if r == Location::UNKNOWN && d != Location::UNKNOWN => {
                if let Some(region) = pick_cropped_region(regions, &d) {
                    rendered_regions.push(std::ptr::from_ref(region));
                    let ctx = region.snippet(crop_radius, options);
                    ctx.fmt_or_fallback(f, Level::ERROR, l10n, &base_msg, &d)?;
                } else {
                    fmt_with_location(f, l10n, &base_msg, &display_location(d, line_offset))?;
                }
            }
            (r, d) => {
                let label = l10n.value_used_here();
                let invalid_here = l10n.invalid_here(&base_msg);
                if let Some(region) = pick_cropped_region(regions, &r) {
                    rendered_regions.push(std::ptr::from_ref(region));
                    let ctx = region.snippet(crop_radius, options);
                    ctx.fmt_or_fallback_with_label(
                        f,
                        Level::ERROR,
                        l10n,
                        &invalid_here,
                        label.as_ref(),
                        &r,
                    )?;
                } else {
                    fmt_with_location(f, l10n, &invalid_here, &display_location(r, line_offset))?;
                }
                writeln!(f)?;
                if let Some(region) = pick_cropped_region(regions, &d) {
                    writeln_anchor_intro(f, l10n, d, region, line_offset)?;
                    rendered_regions.push(std::ptr::from_ref(region));
                    crate::de_snippet::fmt_snippet_window_offset_or_fallback(
                        f,
                        &d,
                        region.text.as_str(),
                        region.start_line,
                        l10n.defined_window().as_ref(),
                        crop_radius,
                        line_offset,
                    )?;
                } else {
                    let anchor_intro = sanitize_message_text(Cow::Owned(
                        l10n.value_comes_from_the_anchor(display_location(d, line_offset)),
                    ));
                    writeln!(f, "{anchor_intro}")?;
                    fmt_with_location(
                        f,
                        l10n,
                        l10n.defined_window().as_ref(),
                        &display_location(d, line_offset),
                    )?;
                }
            }
        }

        for &extra_region in &include_regions {
            if rendered_regions.contains(&std::ptr::from_ref(extra_region)) {
                continue;
            }
            writeln!(f)?;
            writeln!(f, "{}:", sanitize_message_text(l10n.included_from_here()))?;
            let extra_ctx = extra_region.snippet(crop_radius, options);
            extra_ctx.fmt_or_fallback(f, Level::NOTE, l10n, "", &extra_region.location)?;
        }
    }
    Ok(())
}

#[cfg(any(feature = "garde", feature = "validator"))]
fn fmt_error_with_snippets_offset(
    f: &mut fmt::Formatter<'_>,
    err: &Error,
    regions: &[CroppedRegion],
    crop_radius: usize,
    options: RenderOptions<'_>,
) -> fmt::Result {
    let formatter = options.formatter;
    let line_offset = options.line_offset;
    if crop_radius == 0 {
        return fmt_error_plain_with_formatter(f, err, formatter, line_offset);
    }

    // Keep existing snippet output if the nested error is already wrapped.
    if let Error::WithSnippet { .. } = err {
        return fmt_error_rendered(f, err, options);
    }

    #[cfg(any(feature = "garde", feature = "validator"))]
    if let Error::ValidationError {
        source,
        issues,
        locations,
    } = err
    {
        return fmt_validation_error_with_snippets_offset(
            f,
            options,
            &source.external_message_source(),
            issues,
            locations,
            regions,
            crop_radius,
        );
    }

    let msg = render_message_text(formatter, err);
    let Some(location) = err.location() else {
        return write!(f, "{msg}");
    };
    if location == Location::UNKNOWN {
        return write!(f, "{msg}");
    }

    let Some(region) = pick_cropped_region(regions, &location) else {
        return fmt_with_location(
            f,
            formatter.localizer(),
            msg.as_ref(),
            &display_location(location, line_offset),
        );
    };
    let ctx = region.snippet(crop_radius, options);
    ctx.fmt_or_fallback(
        f,
        Level::ERROR,
        formatter.localizer(),
        msg.as_ref(),
        &location,
    )
}

#[cfg(feature = "validator")]
pub(crate) fn collect_validator_issues(errors: &ValidationErrors) -> Vec<ValidationIssue> {
    let mut out = Vec::new();
    let root = PathKey::empty();
    collect_validator_issues_inner(errors, &root, &mut out);
    out
}

#[cfg(feature = "validator")]
fn collect_validator_issues_inner(
    errors: &ValidationErrors,
    path: &PathKey,
    out: &mut Vec<ValidationIssue>,
) {
    for (field, kind) in errors.errors() {
        let field_path = path.clone().join(field.as_ref());
        match kind {
            ValidationErrorsKind::Field(entries) => {
                for entry in entries {
                    let mut params = Vec::new();
                    for (k, v) in &entry.params {
                        params.push((k.to_string(), v.to_string()));
                    }

                    out.push(ValidationIssue {
                        path: field_path.clone(),
                        code: entry.code.to_string(),
                        message: entry.message.as_ref().map(std::string::ToString::to_string),
                        params,
                    });
                }
            }
            ValidationErrorsKind::Struct(inner) => {
                collect_validator_issues_inner(inner, &field_path, out);
            }
            ValidationErrorsKind::List(list) => {
                for (idx, inner) in list {
                    let index_path = field_path.clone().join(*idx);
                    collect_validator_issues_inner(inner, &index_path, out);
                }
            }
        }
    }
}

#[cfg(feature = "garde")]
pub(crate) fn collect_garde_issues(report: &garde::Report) -> Vec<ValidationIssue> {
    let mut out = Vec::new();
    for (path, entry) in report.iter() {
        out.push(ValidationIssue {
            path: path_key_from_garde(path),
            code: "garde".to_string(),
            message: Some(entry.message().to_string()),
            params: Vec::new(),
        });
    }
    out
}
impl std::error::Error for Error {
    /// Snippet wrappers forward the wrapped error's cause to avoid duplicate messages.
    /// Use [`Error::without_snippet`] to inspect the wrapped error itself.
    /// As an exception, [`Error::AliasError`] and its snippet wrappers return the
    /// wrapped error directly to preserve the existing source chain.
    /// I/O errors return their underlying [`std::io::Error`].
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Error::WithSnippet { error, .. } => {
                let mut inner = error.as_ref();
                while let Error::WithSnippet { error, .. } = inner {
                    inner = error;
                }
                if matches!(inner, Error::AliasError { .. }) {
                    Some(error.as_ref())
                } else {
                    inner.source()
                }
            }
            Error::AliasError { error, .. } => Some(error.as_ref()),
            Error::IOError { cause } => Some(cause),
            _ => None,
        }
    }
}

/// Attach the current [`MISSING_FIELD_FALLBACK`] location to `err`, if available.
#[cold]
#[inline(never)]
fn maybe_attach_fallback_location(mut err: Error) -> Error {
    let loc = MISSING_FIELD_FALLBACK.with(std::cell::Cell::get);
    if let Some(loc) = loc
        && loc != Location::UNKNOWN
    {
        err = err.with_location(loc);
    }
    err
}

/// Renders a Serde `Unexpected` into a string sized up front: its `Display` writes in several
/// pieces, which would otherwise regrow the string a few times for every type mismatch, and
/// untagged enums produce one such mismatch per variant they try.
fn unexpected_text(unexp: &de::Unexpected<'_>) -> String {
    use std::fmt::Write as _;

    let mut text = String::with_capacity(64);
    let _ = write!(text, "{unexp}");
    text
}

impl de::Error for Error {
    #[cold]
    #[inline(never)]
    fn custom<T: fmt::Display>(msg: T) -> Self {
        // Keep custom errors locationless by default; the deserializer should attach an explicit
        // location when it can. For Serde-generated errors, we override the relevant hooks below
        // and attach a best-effort fallback location.
        Error::msg(redact_custom_message(msg.to_string()))
    }

    #[cold]
    #[inline(never)]
    fn invalid_type(unexp: de::Unexpected, exp: &dyn de::Expected) -> Self {
        // Mirror serde’s default formatting, but add a best-effort location.
        maybe_attach_fallback_location(Error::SerdeInvalidType {
            unexpected: redact_dynamic_value(unexpected_text(&unexp), "an interpolated value"),
            expected: exp.to_string(),
            location: Location::UNKNOWN,
        })
    }

    #[cold]
    #[inline(never)]
    fn invalid_value(unexp: de::Unexpected, exp: &dyn de::Expected) -> Self {
        maybe_attach_fallback_location(Error::SerdeInvalidValue {
            unexpected: redact_dynamic_value(unexpected_text(&unexp), "an interpolated value"),
            expected: exp.to_string(),
            location: Location::UNKNOWN,
        })
    }

    #[cold]
    #[inline(never)]
    fn invalid_length(len: usize, exp: &dyn de::Expected) -> Self {
        maybe_attach_fallback_location(Error::SerdeInvalidLength {
            len,
            expected: exp.to_string(),
            location: Location::UNKNOWN,
        })
    }

    #[cold]
    #[inline(never)]
    fn unknown_variant(variant: &str, expected: &'static [&'static str]) -> Self {
        maybe_attach_fallback_location(Error::SerdeUnknownVariant {
            variant: redact_dynamic_identifier(variant, "an interpolated variant"),
            expected: expected.to_vec(),
            location: Location::UNKNOWN,
        })
    }

    #[cold]
    #[inline(never)]
    fn unknown_field(field: &str, expected: &'static [&'static str]) -> Self {
        maybe_attach_fallback_location(Error::SerdeUnknownField {
            field: redact_dynamic_identifier(field, "an interpolated field"),
            expected: expected.to_vec(),
            location: Location::UNKNOWN,
        })
    }

    #[cold]
    #[inline(never)]
    fn missing_field(field: &'static str) -> Self {
        maybe_attach_fallback_location(Error::SerdeMissingField {
            field,
            location: Location::UNKNOWN,
        })
    }
}

/// Print a message optionally suffixed with "at line X, column Y".
///
/// Arguments:
/// - `f`: destination formatter.
/// - `msg`: main text.
/// - `location`: position to attach if known.
///
/// Returns:
/// - `fmt::Result` as required by `Display`.
#[cold]
#[inline(never)]
fn fmt_with_location(
    f: &mut fmt::Formatter<'_>,
    l10n: &dyn Localizer,
    msg: &str,
    location: &Location,
) -> fmt::Result {
    let out = sanitize_message_text(l10n.attach_location(Cow::Borrowed(msg), *location));
    write!(f, "{out}")
}

/// Convert a budget breach report into a user-facing error.
///
/// Arguments:
/// - `breach`: which limit was exceeded (from the streaming budget checker).
///
/// Returns:
/// - `Error::Message` with a formatted description.
///
/// Called by:
/// - The live events layer when enforcing budgets during/after parsing.
#[cold]
#[inline(never)]
pub(crate) fn budget_error(breach: BudgetBreach) -> Error {
    Error::Budget {
        breach,
        location: Location::UNKNOWN,
    }
}

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

    #[test]
    fn message_sanitizer_is_selective_and_idempotent() {
        let clean = Cow::Borrowed("quotes: '\"', slash: \\, Unicode: ☃");
        let sanitized = sanitize_message_text(clean.clone());
        assert!(matches!(sanitized, Cow::Borrowed(_)));
        assert_eq!(sanitized, clean);

        let unsafe_text = Cow::Borrowed(
            "nul:\0 tab:\t line:\n esc:\u{1b} del:\u{7f} c1:\u{9b} ls:\u{2028} ps:\u{2029}",
        );
        let sanitized = sanitize_message_text(unsafe_text);
        assert_eq!(
            sanitized,
            r"nul:\0 tab:\t line:\n esc:\u{1b} del:\u{7f} c1:\u{9b} ls:\u{2028} ps:\u{2029}"
        );
        assert_eq!(
            sanitize_message_text(Cow::Owned(sanitized.clone().into_owned())),
            sanitized
        );
    }

    #[test]
    fn formatter_newlines_are_semantic_text_not_renderer_layout() {
        let error = Error::CyclicInclude {
            id: "child.yaml".to_owned(),
            stack: vec!["root.yaml".to_owned(), "parent.yaml".to_owned()],
            location: Location::UNKNOWN,
        };
        let formatter = crate::message_formatters::DefaultMessageFormatter;

        assert!(formatter.format_message(&error).contains('\n'));
        let rendered = error.render_with_formatter(&formatter);
        assert_eq!(
            rendered,
            r"cyclic include detected: child.yaml\nwhile processing include from root.yaml -> parent.yaml"
        );
        assert!(!rendered.contains('\n'));
    }

    #[cfg(any(feature = "garde", feature = "validator"))]
    #[rstest::rstest]
    #[case::reference_only(Location::new(10, 8), Location::UNKNOWN)]
    #[case::definition_only(Location::UNKNOWN, Location::new(10, 8))]
    #[case::same_location(Location::new(10, 8), Location::new(10, 8))]
    fn validation_snippet_headers_use_region_source_names(
        #[case] reference_location: Location,
        #[case] defined_location: Location,
    ) {
        struct DefinitionLabels;
        impl Localizer for DefinitionLabels {
            fn defined(&self) -> Cow<'static, str> {
                Cow::Borrowed("LOCALIZED DEFINITION")
            }

            fn defined_here(&self) -> Cow<'static, str> {
                Cow::Borrowed("LOCALIZED DEFINITION HERE")
            }
        }

        let path = PathKey::new().join_key("value");
        let mut locations = PathMap::new();
        locations.insert(
            path.clone(),
            Locations {
                reference_location,
                defined_location,
            },
        );
        let default = crate::DefaultMessageFormatter;
        let localized = default.with_localizer(&DefinitionLabels);
        for (source_name, displayed_name) in [
            ("config.yaml", "config.yaml"),
            ("config.yaml\n\u{1b}[31m", r"config.yaml\n\u{1b}[31m"),
        ] {
            let error = Error::WithSnippet {
                error: Box::new(Error::ValidationError {
                    source: ValidationSource::Validator,
                    issues: vec![
                        ValidationIssue::new(path.clone(), "bad").with_message("invalid value"),
                    ],
                    locations: locations.clone(),
                }),
                regions: vec![CroppedRegion::new(
                    "value: bad\n",
                    source_name,
                    10,
                    11,
                    Location::new(10, 8),
                )],
                crop_radius: 64,
            };
            for formatter in [&default as &dyn MessageFormatter, &localized] {
                let rendered = error.render_with_formatter(formatter);
                assert!(
                    rendered.contains(&format!(" --> {displayed_name}:10:8")),
                    "expected the source name and absolute coordinates: {rendered}"
                );
                assert!(
                    rendered.contains("^ validation error: invalid value for `value`"),
                    "expected the validation annotation to be preserved: {rendered}"
                );
                assert!(!rendered.contains("LOCALIZED DEFINITION"), "{rendered}");
                assert!(!rendered.contains("included from here"), "{rendered}");
                assert!(!rendered.contains('\u{1b}'), "{rendered:?}");
            }
        }
    }

    #[cfg(any(feature = "garde", feature = "validator"))]
    #[test]
    fn validation_issue_separators_preserve_only_layout_newlines() {
        let error = Error::ValidationError {
            source: ValidationSource::Validator,
            issues: vec![
                ValidationIssue::new(PathKey::new().join_key("first\nkey"), "bad")
                    .with_message("invalid\nvalue\r\t\u{1b}\u{9b}\u{2028}\u{2029}"),
                ValidationIssue::new(PathKey::new().join_key("second"), "bad")
                    .with_message("literal \\n stays literal"),
            ],
            locations: PathMap::new(),
        };
        let expected = concat!(
            "validation error at first\\nkey: invalid\\nvalue\\r\\t\\u{1b}\\u{9b}\\u{2028}\\u{2029}\n",
            "validation error at second: literal \\n stays literal",
        );
        let default = crate::DefaultMessageFormatter;
        let localized_default = default.with_localizer(&DEFAULT_ENGLISH_LOCALIZER);
        let localized_user = UserMessageFormatter.with_localizer(&DEFAULT_ENGLISH_LOCALIZER);
        for formatter in [
            &default as &dyn MessageFormatter,
            &UserMessageFormatter,
            &localized_default,
            &localized_user,
        ] {
            assert_eq!(error.render_with_formatter(formatter), expected);
        }
    }

    #[cfg(any(feature = "garde", feature = "validator"))]
    #[test]
    fn validation_layout_honors_localizer_hooks_and_escapes_their_text() {
        struct Localized;
        impl Localizer for Localized {
            fn override_external_message<'a>(
                &self,
                _msg: ExternalMessage<'a>,
            ) -> Option<Cow<'a, str>> {
                Some(Cow::Borrowed("localized\nmessage\u{1b}"))
            }

            fn validation_issue_line(
                &self,
                path: &str,
                entry: &str,
                _loc: Option<Location>,
            ) -> String {
                format!("{path}: {entry}\t")
            }

            fn join_validation_issues(&self, lines: &[String]) -> String {
                format!("{}\u{1b}", lines.join("\n---\n"))
            }
        }

        let error = Error::ValidationError {
            source: ValidationSource::Validator,
            issues: ["first", "second"]
                .into_iter()
                .map(|key| ValidationIssue::new(PathKey::new().join_key(key), "bad"))
                .collect(),
            locations: PathMap::new(),
        };
        let formatter = crate::DefaultMessageFormatter.with_localizer(&Localized);
        assert_eq!(
            error.render_with_formatter(&formatter),
            concat!(
                "first: localized\\nmessage\\u{1b}\\t\n---\n",
                "second: localized\\nmessage\\u{1b}\\t\\u{1b}",
            )
        );
    }

    #[cfg(any(feature = "garde", feature = "validator"))]
    #[test]
    fn validation_plain_rendering_keeps_custom_whole_message_overrides() {
        struct Custom(std::cell::Cell<usize>);
        impl MessageFormatter for Custom {
            fn format_message<'a>(&self, error: &'a Error) -> Cow<'a, str> {
                self.0.set(self.0.get() + 1);
                let Error::ValidationError { issues, .. } = error else {
                    panic!("expected the whole validation error");
                };
                Cow::Owned(format!("{} problems\ncustom\u{1b}", issues.len()))
            }
        }

        let error = Error::ValidationError {
            source: ValidationSource::Validator,
            issues: ["first", "second"]
                .into_iter()
                .map(|key| ValidationIssue::new(PathKey::new().join_key(key), "bad"))
                .collect(),
            locations: PathMap::new(),
        };
        let formatter = Custom(std::cell::Cell::new(0));
        assert_eq!(
            error.render_with_formatter(&formatter),
            r"2 problems\ncustom\u{1b}"
        );
        assert_eq!(formatter.0.get(), 1);
    }

    #[cfg(any(feature = "garde", feature = "validator"))]
    #[test]
    fn validation_messages_cross_the_same_sanitization_boundary() {
        let path = PathKey::empty().join("field\n\u{1b}");
        let mut locations = PathMap::new();
        locations.insert(
            path.clone(),
            Locations {
                reference_location: Location::new(1, 1),
                defined_location: Location::new(1, 1),
            },
        );
        let error = Error::ValidationError {
            source: ValidationSource::Validator,
            issues: vec![
                ValidationIssue::new(path, "bad\u{9b}")
                    .with_message("invalid\nvalue\u{1b}]0;owned\u{7}"),
            ],
            locations,
        };

        let plain = error.render();
        assert!(
            plain.contains(r"invalid\nvalue\u{1b}]0;owned\u{7}"),
            "{plain:?}"
        );
        assert!(plain.contains(r"field\n\u{1b}"), "{plain:?}");
        assert!(!plain.contains("invalid\nvalue\u{1b}"), "{plain:?}");

        let snippet = error.with_snippet("field: bad\n", 20).render();
        assert!(
            snippet.contains(r"invalid\nvalue\u{1b}]0;owned\u{7}"),
            "{snippet:?}"
        );
        assert!(snippet.contains(r"field\n\u{1b}"), "{snippet:?}");
        assert!(
            snippet.contains('\n'),
            "renderer-owned snippet layout should retain newlines: {snippet:?}"
        );
        assert!(!snippet.contains("invalid\nvalue\u{1b}"), "{snippet:?}");
    }

    #[test]
    fn message_only_input_io_scan_error_uses_portable_fallback() {
        let input = core::iter::once(Err::<char, _>(ErrorKind::InputIo {
            error: granit_parser::InputIoError::from_message("portable reader failure"),
        }));
        let scan_error = granit_parser::Parser::new_from_fallible_iter(input)
            .find_map(Result::err)
            .expect("the source error should be reported");
        let error = Error::from_scan_error(scan_error);

        match error {
            Error::IOError { cause } => {
                assert_eq!(cause.kind(), std::io::ErrorKind::Other);
                assert_eq!(cause.to_string(), "portable reader failure");
            }
            other => panic!("expected reader I/O error, got {other:?}"),
        }
    }

    #[rstest::rstest]
    #[case::unknown_anchor("while parsing node, found unknown anchor")]
    #[case::multiple_documents("multiple documents not supported here")]
    fn custom_scan_error_messages_are_not_reclassified_as_builtin_kinds(#[case] message: &str) {
        let scan_error = ScanError::new(granit_parser::Marker::new(0, 1, 0), message);
        let mapped = Error::from_scan_error(scan_error);

        assert!(matches!(
            mapped,
            Error::ExternalMessage {
                ref source,
                ref msg,
                ..
            } if msg == message
                && matches!(source.as_ref(), ExternalMessageSource::Parser(error)
                    if matches!(error.kind(), ErrorKind::Custom(_)))
        ));
    }

    #[test]
    fn sanitize_snippet_source_name_replaces_control_chars() {
        let sanitized = sanitize_snippet_source_name("evil.yaml\nINJECTED:\u{001b}[31m");
        assert_eq!(sanitized, "evil.yaml INJECTED: [31m");
    }

    #[test]
    fn with_snippet_named_sanitizes_source_name() {
        let err = Error::Message {
            msg: "oops".to_owned(),
            location: Location::new(1, 1),
        }
        .with_snippet_named("x: y\n", "evil.yaml\nINJECTED", 2);

        let Error::WithSnippet { regions, .. } = err else {
            panic!("expected Error::WithSnippet");
        };

        assert_eq!(regions.len(), 1);
        assert_eq!(regions[0].source_name, "evil.yaml INJECTED");
    }

    #[test]
    fn locations_for_basic_error_duplicates_location() {
        let l = Location::new(3, 7);
        let err = Error::Message {
            msg: "x".to_owned(),
            location: l,
        };
        assert_eq!(
            err.locations(),
            Some(Locations {
                reference_location: l,
                defined_location: l,
            })
        );
    }

    #[test]
    fn merge_key_not_allowed_location_helpers() {
        let l = Location::new(4, 2);
        let err = Error::MergeKeyNotAllowed { location: l };
        assert_eq!(err.location(), Some(l));
        assert_eq!(
            err.locations(),
            Some(Locations {
                reference_location: l,
                defined_location: l,
            })
        );

        let updated = err.with_location(Location::new(5, 9));
        assert_eq!(updated.location(), Some(Location::new(5, 9)));
    }

    #[test]
    fn serde_invalid_type_location_helpers() {
        let l = Location::new(4, 2);
        let err = Error::SerdeInvalidType {
            unexpected: "string".to_owned(),
            expected: "an integer".to_owned(),
            location: l,
        };
        assert_eq!(err.location(), Some(l));
        assert_eq!(
            err.locations(),
            Some(Locations {
                reference_location: l,
                defined_location: l,
            })
        );

        let updated = err.with_location(Location::new(5, 9));
        assert_eq!(updated.location(), Some(Location::new(5, 9)));
    }

    #[test]
    fn locations_for_io_error_is_unknown() {
        let err = Error::IOError {
            cause: std::io::Error::other("x"),
        };
        assert_eq!(err.locations(), None);
    }

    #[test]
    #[allow(deprecated)] // Populates the legacy msg field when constructing an alias error.
    fn alias_error_returns_both_locations() {
        let ref_loc = Location::new(5, 10);
        let def_loc = Location::new(2, 3);
        let err = Error::AliasError {
            msg: "test error".to_owned(),
            error: Box::new(Error::msg("test error")),
            locations: Locations {
                reference_location: ref_loc,
                defined_location: def_loc,
            },
        };

        // location() should return the primary (reference) location
        assert_eq!(err.location(), Some(ref_loc));

        // locations() should return both
        assert_eq!(
            err.locations(),
            Some(Locations {
                reference_location: ref_loc,
                defined_location: def_loc,
            })
        );
    }

    #[test]
    #[allow(deprecated)] // Populates the legacy msg field when constructing an alias error.
    fn alias_error_keeps_its_locations_and_returns_the_inner_error_as_source() {
        let locations = Locations {
            reference_location: Location::new(5, 10),
            defined_location: Location::new(2, 3),
        };
        let err = Error::AliasError {
            msg: "inner".to_owned(),
            error: Box::new(Error::msg("inner")),
            locations,
        }
        .with_location(Location::new(9, 9));

        // with_location() must not replace the dual locations.
        assert_eq!(err.locations(), Some(locations));

        let source = std::error::Error::source(&err).expect("AliasError has a source");
        assert_eq!(source.to_string(), "inner");
        assert!(std::error::Error::source(&Error::msg("plain")).is_none());
    }

    #[test]
    #[allow(deprecated)] // Populates the legacy msg field when constructing an alias error.
    fn alias_error_display_shows_both_locations() {
        let ref_loc = Location::new(5, 10);
        let def_loc = Location::new(2, 3);
        let err = Error::AliasError {
            msg: "invalid value".to_owned(),
            error: Box::new(Error::msg("invalid value")),
            locations: Locations {
                reference_location: ref_loc,
                defined_location: def_loc,
            },
        };

        let display = err.to_string();
        assert!(display.contains("invalid value"));
        assert!(display.contains("line 5"));
        assert!(display.contains("column 10"));
        assert!(display.contains("line 2"));
        assert!(display.contains("column 3"));
    }

    #[test]
    #[allow(deprecated)] // Populates the legacy msg field when constructing an alias error.
    fn alias_error_display_with_same_locations() {
        let loc = Location::new(3, 7);
        let err = Error::AliasError {
            msg: "test".to_owned(),
            error: Box::new(Error::msg("test")),
            locations: Locations {
                reference_location: loc,
                defined_location: loc,
            },
        };

        let display = err.to_string();
        // When both locations are the same, show the labelled use only once.
        assert_eq!(display, "test (used at line 3, column 7)");
    }

    #[test]
    #[allow(deprecated)] // Populates the legacy msg field when constructing an alias error.
    fn alias_error_with_unknown_definition_reports_use_once() {
        let err = Error::AliasError {
            msg: "test error".to_owned(),
            error: Box::new(Error::msg("test error")),
            locations: Locations {
                reference_location: Location::new(3, 7),
                defined_location: Location::UNKNOWN,
            },
        };

        assert_eq!(err.to_string(), "test error (used at line 3, column 7)");
    }

    #[test]
    #[allow(deprecated)] // Populates the legacy msg field when constructing an alias error.
    fn alias_error_with_unknown_reference_reports_definition_once() {
        let err = Error::AliasError {
            msg: "test error".to_owned(),
            error: Box::new(Error::msg("test error")),
            locations: Locations {
                reference_location: Location::UNKNOWN,
                defined_location: Location::new(2, 3),
            },
        };

        assert_eq!(err.to_string(), "test error at line 2, column 3");
    }

    #[test]
    #[allow(deprecated)] // Populates the legacy msg field when constructing an alias error.
    fn alias_error_deduplicates_a_failure_at_either_alias_location() {
        let reference_location = Location::new(3, 7);
        let defined_location = Location::new(1, 10);
        for location in [reference_location, defined_location, Location::UNKNOWN] {
            let err = Error::AliasError {
                msg: "invalid u16".to_owned(),
                error: Box::new(Error::InvalidScalar {
                    ty: "u16",
                    location,
                }),
                locations: Locations {
                    reference_location,
                    defined_location,
                },
            };
            assert_eq!(
                err.render(),
                "invalid u16 (defined at line 1, column 10) (used at line 3, column 7)"
            );
            let rendered = err
                .with_snippet("base: &b\n  port: eighty\ncopy: *b\n", 64)
                .render();
            assert!(!rendered.contains("the error occurred here"), "{rendered}");
        }
    }

    #[test]
    #[allow(deprecated)] // Populates the legacy msg field when constructing an alias error.
    fn alias_error_preserves_a_known_failure_when_alias_locations_are_unknown() {
        let failure = Location::new(2, 9);
        for defined_location in [Location::new(2, 3), Location::UNKNOWN] {
            let err = Error::AliasError {
                msg: "invalid u16".to_owned(),
                error: Box::new(Error::InvalidScalar {
                    ty: "u16",
                    location: failure,
                }),
                locations: Locations {
                    reference_location: Location::UNKNOWN,
                    defined_location,
                },
            };
            let expected = if defined_location == Location::UNKNOWN {
                "invalid u16 at line 2, column 9"
            } else {
                "invalid u16 at line 2, column 9 at line 2, column 3"
            };
            assert_eq!(err.render(), expected);
            let wrapped = err.with_snippet("base: &b\n  port: eighty\ncopy: *b\n", 64);
            let rendered = wrapped.render();
            if defined_location == Location::UNKNOWN {
                assert_eq!(rendered, expected);
            } else {
                assert!(rendered.contains("<input>:2:9"), "{rendered}");
                assert!(rendered.contains("the error occurred here"), "{rendered}");
                assert!(!rendered.contains("included from here"), "{rendered}");
            }
        }
    }

    #[test]
    fn with_snippet_counts_trailing_empty_line_for_end_line() {
        // `"a\n"` has two logical lines: "a" and a trailing empty line.
        let text = "a\n";
        let err = Error::Message {
            msg: "x".to_owned(),
            location: Location::new(2, 1),
        };

        let wrapped = err.with_snippet(text, 50);
        let Error::WithSnippet { regions, .. } = wrapped else {
            panic!("expected WithSnippet wrapper");
        };
        assert_eq!(regions.len(), 1);
        assert_eq!(regions[0].start_line, 1);
        assert_eq!(regions[0].end_line, 2);
    }

    #[test]
    fn with_snippet_offset_counts_trailing_empty_line_for_end_line() {
        // Fragment starts at line 10, and ends with a newline -> includes empty line 11.
        let text = "a\n";
        let err = Error::Message {
            msg: "x".to_owned(),
            location: Location::new(11, 1),
        };

        let wrapped = err.with_snippet_offset_named(text, 10, "<input>", 50);
        let Error::WithSnippet { regions, .. } = wrapped else {
            panic!("expected WithSnippet wrapper");
        };
        assert_eq!(regions.len(), 1);
        assert_eq!(regions[0].start_line, 10);
        assert_eq!(regions[0].end_line, 11);
    }

    #[cfg(feature = "validator")]
    #[test]
    fn locations_for_validator_error_uses_first_entry() {
        use validator::Validate;

        #[derive(Debug, Validate)]
        struct Cfg {
            #[validate(length(min = 2))]
            second_string: String,
        }

        let cfg = Cfg {
            second_string: "x".to_owned(),
        };
        let errors = cfg.validate().expect_err("validation error expected");

        let referenced_loc = Location::new(3, 15);
        let defined_loc = Location::new(2, 18);

        let mut locations = PathMap::new();
        locations.insert(
            PathKey::empty().join("secondString"),
            Locations {
                reference_location: referenced_loc,
                defined_location: defined_loc,
            },
        );

        let err = Error::ValidationError {
            source: ValidationSource::Validator,
            issues: crate::de_error::collect_validator_issues(&errors),
            locations,
        };
        assert_eq!(
            err.locations(),
            Some(Locations {
                reference_location: referenced_loc,
                defined_location: defined_loc,
            })
        );
    }

    #[cfg(feature = "validator")]
    #[test]
    fn validator_error_uses_ancestor_path_location_fallback() {
        let yaml = "parent:\n  child: bad\n";
        let referenced_loc = Location::new(1, 1);
        let defined_loc = Location::new(1, 1);

        let mut locations = PathMap::new();
        locations.insert(
            PathKey::empty().join("parent"),
            Locations {
                reference_location: referenced_loc,
                defined_location: defined_loc,
            },
        );

        let err = Error::ValidationError {
            source: ValidationSource::Validator,
            issues: vec![ValidationIssue {
                path: PathKey::empty().join("parent").join("child").join("value"),
                code: "custom".to_owned(),
                message: Some("custom validation failed".to_owned()),
                params: Vec::new(),
            }],
            locations,
        };

        assert_eq!(err.location(), Some(referenced_loc));
        assert_eq!(
            err.locations(),
            Some(Locations {
                reference_location: referenced_loc,
                defined_location: defined_loc,
            })
        );

        let rendered = err.with_snippet(yaml, 20).render();
        assert!(
            rendered.contains("custom validation failed"),
            "expected validation message, got: {rendered}"
        );
        assert!(
            rendered.contains("for `parent.child.value`"),
            "expected original validation path, got: {rendered}"
        );
        assert!(
            rendered.contains("line 1 column 1"),
            "expected ancestor location, got: {rendered}"
        );
        assert!(
            rendered.contains("1 | parent:"),
            "expected snippet around ancestor path, got: {rendered}"
        );
    }

    #[test]
    fn nested_snippet_preserves_custom_formatter() {
        struct Custom;
        impl MessageFormatter for Custom {
            fn localizer(&self) -> &dyn Localizer {
                &DEFAULT_ENGLISH_LOCALIZER
            }
            fn format_message<'a>(&self, err: &'a Error) -> Cow<'a, str> {
                match err {
                    Error::Message { msg, .. } => Cow::Owned(format!("CUSTOM: {}", msg.as_str())),
                    _ => Cow::Borrowed(""),
                }
            }
        }
        let loc = Location::new(1, 1);
        let base = Error::Message {
            msg: "original".to_string(),
            location: loc,
        };
        let text = "input";
        let start_line = 1;
        let radius = 1;
        let inner = base.with_snippet_offset_named(text, start_line, "<input>", radius);
        let outer = inner.with_snippet_offset_named(text, start_line, "<input>", radius);
        let rendered = outer.render_with_options(RenderOptions::new(&Custom));
        assert!(rendered.contains("CUSTOM: original"));
    }

    #[test]
    #[allow(deprecated)] // Populates the legacy msg field when constructing an alias error.
    fn alias_error_dual_snippet_rendering() {
        // YAML with anchor on line 2 and alias usage on line 5
        let yaml = r#"config:
  anchor: &myval 42
  other: stuff
  more: data
  use_it: *myval
"#;
        // Reference location: line 5, column 11 (where *myval is used)
        let ref_loc = Location::new(5, 11);
        // Defined location: line 2, column 11 (where &myval is defined)
        let def_loc = Location::new(2, 11);

        let err = Error::AliasError {
            msg: "invalid value type".to_owned(),
            error: Box::new(Error::msg("invalid value type")),
            locations: Locations {
                reference_location: ref_loc,
                defined_location: def_loc,
            },
        };

        // Wrap with snippet
        let wrapped = err.with_snippet(yaml, 5);
        let rendered = wrapped.render();

        // Should contain the error message
        assert!(
            rendered.contains("invalid value type"),
            "rendered: {}",
            rendered
        );

        // When a secondary snippet window is shown, avoid duplicating the alias
        // "defined at …" suffix in the main message.
        assert!(
            !rendered.contains("(defined at line"),
            "did not expect alias defined-at suffix when secondary window is present: {}",
            rendered
        );
        // Should show "the value is used here" for the reference location
        assert!(
            rendered.contains("the value is used here") || rendered.contains("use_it"),
            "rendered should show reference location context: {}",
            rendered
        );
        // Should show "defined here" for the anchor location
        assert!(
            rendered.contains("defined here") || rendered.contains("anchor"),
            "rendered should show defined location context: {}",
            rendered
        );
        // Should mention both line numbers in some form
        assert!(
            rendered.contains('5') || rendered.contains("use_it"),
            "rendered should reference line 5: {}",
            rendered
        );
        assert!(
            rendered.contains('2') || rendered.contains("anchor"),
            "rendered should reference line 2: {}",
            rendered
        );
    }

    #[test]
    #[allow(deprecated)] // Populates the legacy msg field when constructing an alias error.
    fn alias_error_same_location_single_snippet() {
        let yaml = "value: &anchor 42\n";
        let loc = Location::new(1, 8);

        let err = Error::AliasError {
            msg: "test error".to_owned(),
            error: Box::new(Error::msg("test error")),
            locations: Locations {
                reference_location: loc,
                defined_location: loc,
            },
        };

        let wrapped = err.with_snippet(yaml, 5);
        let rendered = wrapped.render();

        // Should contain the error message
        assert!(rendered.contains("test error"), "rendered: {}", rendered);
        // Should NOT show dual-snippet labels when locations are the same
        assert!(
            !rendered.contains("defined here"),
            "should not show 'defined here' when locations are same: {}",
            rendered
        );
        assert!(
            !rendered.contains("the value is used here"),
            "should not show 'value used here' when locations are same: {}",
            rendered
        );
    }
}