omnist/formats/

yaml.rs

//! YAML codec. Ported from `~/dev/omnist/omnist/formats.py`'s
//! `read_yaml`/`write_yaml`/`check_yaml`.
//!
//! ## Crate choice
//!
//! YAML's grammar (block/flow collections, indentation-sensitivity, scalar
//! styles, anchors/aliases, tags) is significantly more complex than JSON's.
//! This module uses [`yaml_rust2`]'s low-level [`Parser`]/[`MarkedEventReceiver`]
//! event stream for raw tokenization/structure (indentation handling, flow vs.
//! block collections, quoting, anchors/aliases) -- the "reasonable,
//! spec-compliant" choice issue #18 calls out, since re-deriving YAML's
//! indentation/quoting grammar by hand would duplicate a large, well-tested
//! surface for little benefit. Everything omnist-specific is still hand-written
//! Rust code in this module, not delegated to the crate:
//!
//! * **Scalar-tag resolution** (`resolve_plain_scalar`) -- `yaml_rust2`'s own
//!   built-in resolver (`Yaml::from_str`) only recognizes `true`/`false`
//!   (YAML 1.2 core schema) for booleans. Live-checked against Python's
//!   `yaml.safe_load` (PyYAML, which this project's Python reference wraps):
//!   PyYAML additionally treats `yes`/`no`/`on`/`off` (and case variants) as
//!   booleans (YAML 1.1 `Resolver.yaml_implicit_resolvers`, confirmed via the
//!   `tag:yaml.org,2002:bool` regex) -- `y`/`n` alone are **not** included and
//!   stay strings. Because `yaml_rust2`'s own resolution would silently
//!   produce the wrong Rust value for `yes`/`no`/`on`/`off`, this module
//!   ignores the crate's built-in scalar typing entirely and re-implements
//!   PyYAML's exact implicit-resolver regexes for null/bool/int/float/
//!   timestamp against the raw scalar text + style (quoted scalars are never
//!   auto-typed, matching PyYAML, which only applies implicit resolution to
//!   plain-style scalars).
//! * **Merge-key (`<<`) handling** (`expand_merge_keys`) -- `yaml_rust2` has
//!   no built-in merge-key support at all (confirmed by reading its source);
//!   this module implements the YAML merge-key spec directly: an unquoted
//!   `<<` key's value must be a mapping or a sequence of mappings, merged in
//!   order with explicit keys in the mapping taking precedence, else a clean
//!   [`ParseError`] (never a panic) -- the omnist-ts#46 regression this
//!   module's test suite pins.
//! * **Depth guard, temporal shape-check, integer digit cap** -- reused from
//!   [`crate::document`]/[`crate::schema`]/this crate's established
//!   4300-digit-cap pattern (see `MAX_INT_DIGITS`), not reimplemented.
//!
//! ## Depth guard reuse
//!
//! Same reasoning as `json.rs`: [`read_yaml`] builds a [`Doc`] via [`Doc::of`],
//! which calls `crate::document::check_write_depth` internally. The merge-
//! key/alias-resolution pass that runs *before* `Doc::of` also depth-guards
//! itself (an alias can reference an already-deep subtree, and merging can
//! grow a mapping before the Document-model depth check ever sees it), reusing
//! the same `crate::document::check_write_depth` guard rather than adding a
//! second copy. [`write_yaml`]/[`check_yaml`] walk an already-built `Doc` (via
//! `to_grouped`), whose nodes are already depth-checked, so there is nothing
//! left to re-guard on the way out.
//!
//! ## No native temporal type; but YAML dates/datetimes still need normalizing
//!
//! Like `json.rs`, this port's [`crate::document::Scalar`] has no temporal
//! variant -- a YAML timestamp becomes a `Scalar::Str` holding its ISO
//! spelling. Unlike JSON, YAML's timestamp grammar is looser than the ISO
//! shapes `schema.rs`'s temporal shape-check accepts (space-separated date/
//! time, single-digit month/day, a bare `Z` suffix, no zero-padding) --
//! Python's PyYAML normalizes any such spelling to a `datetime.date`/
//! `datetime.datetime` object and then (elsewhere in the pipeline) back to a
//! canonical ISO string. `normalize_timestamp` reproduces that
//! normalization for the timestamp grammar PyYAML's own
//! `tag:yaml.org,2002:timestamp` resolver accepts, so a YAML value like
//! `2001-12-14 21:59:43.10 -5` round-trips to the same canonical
//! `2001-12-14T21:59:43.100000-05:00` shape Python's `datetime.isoformat()`
//! would produce, not the original loose spelling. A timestamp-shaped string
//! naming a calendar/clock value that doesn't exist (`2024-13-01`,
//! `2024-02-30`) is a [`ParseError`], not a silent string fallback --
//! live-confirmed: PyYAML's construction step raises `ValueError` there,
//! which fails the whole document. Calendar/clock validity itself reuses
//! `crate::schema::valid_ymd`/`crate::schema::valid_hms` rather than a
//! second copy of that logic, even though the *shape* regex is necessarily
//! separate (looser than `schema.rs`'s).
//!
//! ## Native NaN/Infinity support (no lossy adjustment, unlike JSON)
//!
//! YAML's float grammar has native tokens for `.nan`/`.inf`/`-.inf`
//! (`tag:yaml.org,2002:float`), so -- unlike `json.rs`'s `write_json`, which
//! must substitute `null` for a special float -- [`write_yaml`] never needs to
//! adjust a `NaN`/`Infinity` leaf. The only adjustment [`check_yaml`] ever
//! records is forcing double-quoted style for a string containing U+0085
//! (NEL), which PyYAML's default (unquoted/single-quoted) scalar styles
//! normalize away as a line break -- mirrors Python's `_scan_yaml_labels`/
//! `_yaml_str_representer` exactly.
//!
//! ## Integer digit cap (omnist-ts#54 / oml.rs / json.rs precedent)
//!
//! Same 4300-digit cap, applied to a plain decimal integer scalar's digit run
//! before attempting to parse it, mirroring `json.rs`'s identical guard.

mod alias;
#[cfg(test)]
mod alias_tests;

use std::collections::HashMap;

use yaml_rust2::parser::{Event, MarkedEventReceiver, Parser, Tag};
use yaml_rust2::scanner::{Marker, ScanError, TScalarStyle};

use crate::WriteError;
use crate::document::{Doc, Value};
use crate::error::{DocumentError, OmnistError, ParseError};
use crate::formats::float_fmt;
use crate::formats::string_escape::{YAML_ESCAPES, write_quoted};
use crate::limits::{IntGuard, Limits, Resolved, int_exceeds};
use crate::report::{Severity, WriteReport};
use indexmap::IndexMap;
use num_bigint::BigInt;

// Same guard, same constant as `json.rs`'s/`oml.rs`'s -- see this
// module's doc comment. Constant and message constructors now live in
// [`crate::formats::int_cap`] (issue #49).

/// The default bound on the total number of nodes materialized while
/// rebuilding the event stream (issue #42, "YAML alias/anchor expansion
/// amplification"); the bound in force is [`Limits::max_nodes`].
/// A node is what the spec's D-9 counts: a **container**, a mapping or a
/// sequence (an edge list). Keys and scalar values are not nodes, so a flat
/// mapping of any number of scalar entries is one node (omnist-rs#189).
/// The number is the spec's reference default, 1 000 000
/// (docs/02-document-model.md §2.4); it is [`Limits::max_nodes`].
///
/// An `*alias` reference counts every container of the subtree it clones,
/// so a chain of anchors each referencing the previous generation's alias
/// multiple times ("billion laughs") is still charged its real, amplified
/// size. The value-slot amplification of aliases and merges is bounded
/// separately and first, by D-18 and D-22, before any tree is built.
#[cfg(test)]
const MAX_MATERIALIZED_NODES: usize = crate::limits::DEFAULT_MAX_NODES as usize;

/// Counts the containers (mappings and sequences) in `node`'s subtree,
/// including `node` itself when it is one. Used to charge an alias reference
/// for the containers it clones, not just "one node". Scalars are not nodes.
fn count_nodes(node: &Raw) -> usize {
    match node {
        Raw::Scalar(..) => 0,
        Raw::Sequence(items) => 1 + items.iter().map(count_nodes).sum::<usize>(),
        Raw::Mapping(entries) => {
            1 + entries
                .iter()
                .map(|(k, v)| count_nodes(k) + count_nodes(v))
                .sum::<usize>()
        }
    }
}

// ============================================================== Reader

/// The raw shape `yaml_rust2`'s event stream is rebuilt into: a scalar with
/// its original text and style (style is what `resolve_plain_scalar` and
/// merge-key detection both need, and what `yaml_rust2`'s own `Yaml` enum
/// throws away by pre-resolving plain scalars with its own, PyYAML-incompatible
/// rules -- see this module's doc comment), or an ordered sequence/mapping.
#[derive(Debug, Clone)]
enum Raw {
    Scalar(String, TScalarStyle, Option<Tag>),
    Sequence(Vec<Raw>),
    Mapping(Vec<(Raw, Raw)>),
}

/// Rebuilds a [`Raw`] tree from `yaml_rust2`'s parser event stream, resolving
/// aliases against anchors seen so far (anchors always precede their aliases
/// in a valid YAML document). Structurally mirrors `yaml_rust2::yaml::YamlLoader`
/// (the crate's own reference event-to-tree builder), adapted to keep scalar
/// style/tag information `YamlLoader`'s `Yaml` throws away.
struct Builder {
    doc_stack: Vec<(Raw, usize)>,
    key_stack: Vec<Option<Raw>>,
    anchor_map: HashMap<usize, Raw>,
    docs: Vec<Raw>,
    /// Running total of [`Raw`] nodes materialized so far -- see
    /// [`MAX_MATERIALIZED_NODES`].
    node_count: usize,
    /// Set once the node cap ([`Limits::max_nodes`]) is exceeded; further
    /// events are ignored (no more work is done building an already-rejected
    /// tree) and this is surfaced as `document.limit.nodes` at `$` once
    /// parsing finishes.
    error: Option<DocumentError>,
    /// The limits in force.
    limits: Resolved,
    /// Set when an alias refers to an anchor that is not complete yet (a
    /// self-referential definition, D-20): `document.limit.alias-expansion`
    /// at `$`; or when block/flow nesting runs far past
    /// [`crate::document::MAX_DEPTH`]: `document.limit.depth` at `$`. Like
    /// `error`, once set the receiver stops building.
    self_reference: Option<DocumentError>,
    /// Set when a node is tagged `!!pairs`, `!!omap` or `!!set` (C-13):
    /// `format.tag-forbidden` at `$`. Like `error`, once set the receiver
    /// stops building.
    tag_forbidden: Option<DocumentError>,
}

impl Builder {
    fn new(limits: &Resolved) -> Self {
        Builder {
            limits: *limits,
            doc_stack: Vec::new(),
            key_stack: Vec::new(),
            anchor_map: HashMap::new(),
            docs: Vec::new(),
            node_count: 0,
            error: None,
            self_reference: None,
            tag_forbidden: None,
        }
    }

    /// Whether opening one more collection would nest far beyond
    /// [`crate::document::MAX_DEPTH`]. The margin keeps every boundary case
    /// the later `check_write_depth` stages decide exactly as before; only
    /// nesting they would reject anyway is caught here.
    fn too_deep(&self) -> bool {
        self.doc_stack.len() > self.limits.max_depth + 8
    }

    /// Charges `n` newly-materialized nodes against the running total,
    /// setting `self.error` (if not already set) the first time the total
    /// exceeds [`MAX_MATERIALIZED_NODES`]. Returns `true` if the caller
    /// should proceed (still under the limit), `false` if it tripped (or
    /// had already tripped) and should skip the work it was about to do.
    fn charge(&mut self, n: usize, _mark: Marker) -> bool {
        if self.error.is_some() {
            return false;
        }
        self.node_count = self.node_count.saturating_add(n);
        if self.node_count > self.limits.max_nodes {
            self.error = Some(DocumentError::with_code(
                "$",
                "document.limit.nodes",
                format!(
                    "invalid YAML: document materializes more than \
                     {} nodes (security: unbounded anchor/alias \
                     expansion can amplify a small document into an enormous tree, \
                     independent of nesting depth)",
                    self.limits.max_nodes
                ),
            ));
            return false;
        }
        true
    }

    fn insert(&mut self, node: Raw, aid: usize, _mark: Marker) {
        if aid > 0 {
            self.anchor_map.insert(aid, node.clone());
        }
        match self.doc_stack.last_mut() {
            None => self.doc_stack.push((node, aid)),
            Some((Raw::Sequence(items), _)) => items.push(node),
            Some((Raw::Mapping(_), _)) => {
                let cur_key = self
                    .key_stack
                    .last_mut()
                    .expect("a Mapping is only ever pushed alongside a matching key_stack entry");
                match cur_key.take() {
                    None => *cur_key = Some(node),
                    Some(k) => {
                        if let Some((Raw::Mapping(entries), _)) = self.doc_stack.last_mut() {
                            entries.push((k, node));
                        }
                    }
                }
            }
            Some((Raw::Scalar(..), _)) => {
                // A scalar is never pushed onto doc_stack as a container
                // (only Sequence/Mapping are, in on_event's SequenceStart/
                // MappingStart arms) -- this arm is structurally unreachable.
                unreachable!("a Scalar is never a container on doc_stack")
            }
        }
    }

    /// Handles one parser event. The crate's own scanner rejects an alias
    /// whose anchor was never defined (`ScanError: found unknown anchor`,
    /// surfaced through [`scan_error_to_parse_error`]), but it DOES emit the
    /// `Event::Alias` for a reference made inside its own still-open anchor
    /// (`a: &A\n  b: *A`): the anchor map has no entry yet. That is a
    /// self-referential definition, recorded in `self_reference` (D-20) and
    /// never materialized.
    fn on_event_impl(&mut self, ev: Event, mark: Marker) {
        // Once tripped, stop doing any further tree-building work -- the
        // document is already rejected, and continuing to clone/insert
        // subsequent alias references would just keep paying the same
        // amplified cost this guard exists to avoid.
        if self.error.is_some() || self.self_reference.is_some() || self.tag_forbidden.is_some() {
            return;
        }
        match ev {
            Event::Nothing | Event::StreamStart | Event::StreamEnd | Event::DocumentStart => {}
            Event::DocumentEnd => match self.doc_stack.len() {
                0 => self
                    .docs
                    .push(Raw::Scalar(String::new(), TScalarStyle::Plain, None)),
                1 => self.docs.push(self.doc_stack.pop().unwrap().0),
                _ => unreachable!("a single document's stack never nests more than one root"),
            },
            Event::SequenceStart(_, Some(ref tag))
            | Event::MappingStart(_, Some(ref tag))
            | Event::Scalar(_, _, _, Some(ref tag))
                if is_forbidden_tag(Some(tag)) =>
            {
                self.tag_forbidden = Some(tag_forbidden_error(tag));
            }
            Event::SequenceStart(..) | Event::MappingStart(..) if self.too_deep() => {
                // Nesting this far past the depth cap is rejected here,
                // while the tree is still shallow enough to drop: yaml-rust2
                // has no recursion limit for BLOCK collections (`- - - ...`
                // or one more indent per line), so a small input could
                // otherwise build a tree deep enough to overflow the stack
                // when it is dropped or walked.
                self.self_reference = Some(self.limits.depth_error());
            }
            Event::SequenceStart(aid, _) => {
                if !self.charge(1, mark) {
                    return;
                }
                self.doc_stack.push((Raw::Sequence(Vec::new()), aid));
            }
            Event::SequenceEnd => {
                let (node, aid) = self.doc_stack.pop().expect("matched by SequenceStart");
                self.insert(node, aid, mark);
            }
            Event::MappingStart(aid, _) => {
                if !self.charge(1, mark) {
                    return;
                }
                self.doc_stack.push((Raw::Mapping(Vec::new()), aid));
                self.key_stack.push(None);
            }
            Event::MappingEnd => {
                let (node, aid) = self.doc_stack.pop().expect("matched by MappingStart");
                self.key_stack.pop();
                self.insert(node, aid, mark);
            }
            Event::Scalar(v, style, aid, tag) => {
                // A scalar is not a node (D-9): it is not charged.
                self.insert(Raw::Scalar(v, style, tag), aid, mark);
            }
            Event::Alias(id) => {
                // Count the *whole subtree's* size before cloning it -- an
                // alias amplifies by the size of what it references, not
                // by one node, so charging anything less would let the
                // exponential "billion laughs" pattern through uncounted.
                // The borrow of `anchor_map` ends with this block, so
                // `self.charge` below can take `&mut self` freely.
                // An alias to an anchor with no entry yet: yaml_rust2 rejects an
                // alias to a NEVER-defined anchor itself, but it emits the
                // Alias event for a reference made while its own anchor is
                // still being built (`a: &A\n  b: *A`, `a: &A\n  <<: *A`).
                // That is a self-referential definition, which D-20 says MUST
                // be rejected with `document.limit.alias-expansion` (path `$`,
                // E-4a) and never materialized.
                let Some(referenced) = self.anchor_map.get(&id) else {
                    self.self_reference = Some(DocumentError::with_code(
                        "$",
                        "document.limit.alias-expansion",
                        "an alias refers to an anchor that is not yet complete: a \
                         self-referential definition has unbounded expansion (D-20)",
                    ));
                    return;
                };
                let n = count_nodes(referenced);
                if !self.charge(n, mark) {
                    return;
                }
                let node = self
                    .anchor_map
                    .get(&id)
                    .cloned()
                    .expect("checked above: the anchor_map entry exists for this id");
                self.insert(node, 0, mark);
            }
        }
    }
}

impl MarkedEventReceiver for Builder {
    fn on_event(&mut self, ev: Event, mark: Marker) {
        self.on_event_impl(ev, mark);
    }
}

/// The reference default for the maximum alias expansion factor (spec
/// §2.4, D-18): the reader rejects any mapping or sequence whose
/// materialized-to-written value-slot ratio exceeds it. Documented per D-11.
pub const DEFAULT_MAX_ALIAS_EXPANSION: u32 = 50;

/// The largest maximum alias expansion factor [`read_yaml_with`] accepts.
/// A larger value is refused rather than clamped (D-10: the limit must be
/// finite and meaningful; it is a denial-of-service bound, not a tuning knob
/// without an upper end).
pub const MAX_ALIAS_EXPANSION_CEILING: u32 = 10_000;

/// The reference default for the maximum expanded size (spec §2.4.1, D-22):
/// the reader rejects an input that contains an alias or a merge key and
/// whose document root materializes more value slots (`W(root)`) than this,
/// with `document.limit.expanded-size`. Documented per D-11.
pub const DEFAULT_MAX_EXPANDED_SLOTS: u32 = 1_000_000;

/// The largest maximum expanded size [`read_yaml_with`] accepts: the spec's
/// recommended ceiling (D-22, "SHOULD NOT configure one above 10 000 000
/// without measuring"). A larger value is refused rather than clamped, as for
/// [`MAX_ALIAS_EXPANSION_CEILING`].
pub const MAX_EXPANDED_SLOTS_CEILING: u32 = 10_000_000;

/// Options for [`read_yaml_with`].
///
/// ```
/// use omnist::formats::yaml::{read_yaml_with, YamlReadOptions};
///
/// let opts = YamlReadOptions::default().with_max_alias_expansion(200);
/// let doc = read_yaml_with("a: 1\n", &opts).unwrap();
/// assert_eq!(doc.to_raw(), omnist::formats::yaml::read_yaml("a: 1\n").unwrap().to_raw());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct YamlReadOptions {
    /// The maximum alias expansion factor `E = W / S` any one mapping or
    /// sequence (anchored or not, the document root included) may reach
    /// before the reader rejects the input with
    /// `document.limit.alias-expansion` (spec §2.4.1, D-18).
    ///
    /// `0` selects [`DEFAULT_MAX_ALIAS_EXPANSION`] (50): a zero or unset value
    /// never widens the limit. Values above [`MAX_ALIAS_EXPANSION_CEILING`]
    /// (10 000) are rejected by [`read_yaml_with`]. Note the
    /// `(keys + 2) / 3` behaviour of merges: a mapping that merges an
    /// `n`-key anchor and writes one key of its own has `E ~ (n + 2) / 3`, so
    /// the default of 50 rejects merging a 150-key anchor into such a
    /// mapping; raise this option for configurations that large.
    pub max_alias_expansion: u32,
    /// The maximum expanded size `W(root)`, in value slots, an input that
    /// contains at least one alias or merge key may reach before the reader
    /// rejects it with `document.limit.expanded-size` (spec §2.4.1, D-22).
    /// `W(root)` equal to the maximum is accepted; one past is rejected.
    ///
    /// This is independent of [`YamlReadOptions::max_alias_expansion`]: the
    /// ratio limit bounds amplification, this one bounds absolute size, and
    /// an input can pass one and fail the other (when both fail the ratio
    /// code is reported). An input with neither an alias nor a merge key is
    /// exempt however large: a plain file of two million slots passes, and
    /// adding one alias subjects it to this cap. `0` selects
    /// [`DEFAULT_MAX_EXPANDED_SLOTS`] (1 000 000); values above
    /// [`MAX_EXPANDED_SLOTS_CEILING`] (10 000 000) are rejected by
    /// [`read_yaml_with`].
    pub max_expanded_slots: u32,
    /// The safety limits every format shares (nesting depth, node count,
    /// integer digits; spec section 2.4): see [`Limits`].
    pub limits: Limits,
}

impl Default for YamlReadOptions {
    fn default() -> Self {
        YamlReadOptions {
            max_alias_expansion: DEFAULT_MAX_ALIAS_EXPANSION,
            max_expanded_slots: DEFAULT_MAX_EXPANDED_SLOTS,
            limits: Limits::default(),
        }
    }
}

impl YamlReadOptions {
    /// These options with [`YamlReadOptions::max_alias_expansion`] set to `n`
    /// (the struct is `#[non_exhaustive]`, so a downstream crate builds it
    /// from [`Default`] with this).
    #[must_use]
    pub fn with_max_alias_expansion(mut self, n: u32) -> Self {
        self.max_alias_expansion = n;
        self
    }

    /// These options with [`YamlReadOptions::max_expanded_slots`] set to `n`.
    #[must_use]
    pub fn with_max_expanded_slots(mut self, n: u32) -> Self {
        self.max_expanded_slots = n;
        self
    }

    /// These options with [`YamlReadOptions::limits`] set to `limits`.
    #[must_use]
    pub fn with_limits(mut self, limits: Limits) -> Self {
        self.limits = limits;
        self
    }

    /// The maximum expanded size these options select: the configured value,
    /// or [`DEFAULT_MAX_EXPANDED_SLOTS`] when it is `0`.
    pub fn effective_max_expanded_slots(&self) -> u32 {
        if self.max_expanded_slots == 0 {
            DEFAULT_MAX_EXPANDED_SLOTS
        } else {
            self.max_expanded_slots
        }
    }

    /// The maximum expansion factor these options select: the configured
    /// value, or [`DEFAULT_MAX_ALIAS_EXPANSION`] when it is `0`.
    pub fn effective_max_alias_expansion(&self) -> u32 {
        if self.max_alias_expansion == 0 {
            DEFAULT_MAX_ALIAS_EXPANSION
        } else {
            self.max_alias_expansion
        }
    }

    /// Checks the options: [`YamlReadOptions::max_alias_expansion`] must not
    /// exceed [`MAX_ALIAS_EXPANSION_CEILING`], nor
    /// [`YamlReadOptions::max_expanded_slots`] [`MAX_EXPANDED_SLOTS_CEILING`],
    /// and [`YamlReadOptions::limits`] must pass [`Limits::validate`].
    /// [`read_yaml_with`] calls this
    /// first and returns its error unchanged.
    pub fn validate(&self) -> Result<(), DocumentError> {
        if self.max_alias_expansion > MAX_ALIAS_EXPANSION_CEILING {
            return Err(DocumentError::new(
                "$",
                format!(
                    "max_alias_expansion {} exceeds the ceiling {MAX_ALIAS_EXPANSION_CEILING} \
                     (0 selects the default {DEFAULT_MAX_ALIAS_EXPANSION})",
                    self.max_alias_expansion
                ),
            ));
        }
        if self.max_expanded_slots > MAX_EXPANDED_SLOTS_CEILING {
            return Err(DocumentError::new(
                "$",
                format!(
                    "max_expanded_slots {} exceeds the ceiling {MAX_EXPANDED_SLOTS_CEILING} \
                     (0 selects the default {DEFAULT_MAX_EXPANDED_SLOTS})",
                    self.max_expanded_slots
                ),
            ));
        }
        self.limits.validate()?;
        Ok(())
    }
}

/// Drives `parser` to the end of the stream, running the alias expansion
/// and merge-shape check (D-18/D-18a/D-19/D-20/D-22) on every event and
/// buffering the events, which are replayed into [`Builder`] only once the
/// whole stream has passed -- so no alias is ever expanded before the check
/// has accepted the input.
///
/// This is what `Parser::load(builder, true)` does, minus its recursion.
/// `load` walks nested collections with mutually recursive `load_node` /
/// `load_sequence` / `load_mapping` calls and no depth limit for BLOCK
/// collections (its scanner only limits flow nesting): about 15 KB of `- - -
/// ...` or one more indent per line overflowed the stack and aborted the
/// process, before any of this crate's depth guards could run. The event
/// stream itself ([`Parser::next_token`]) is a flat state machine, so pulling
/// events directly is safe at any depth; the checker keeps its frames on the
/// heap, and once nesting runs far past the depth cap buffering stops (the
/// replay reports the depth error from the events already kept), so a hostile
/// nesting costs a scan, not a stack.
///
/// The checker keeps reading after a limit violation, because a malformed
/// merge later in the stream is a syntax error that wins over every
/// `document.limit.*` code (D-18a); it stops buffering, as nothing will be
/// replayed. A scan error wins over both, as every earlier self-reference
/// error did: the scan always runs to the end.
///
/// One difference from `load`, which cleared the parser's anchor table
/// between documents: this does not (that table is private), so a later
/// document's alias to an earlier document's anchor now resolves instead of
/// being an unknown-anchor scan error. A multi-document stream is rejected
/// afterwards either way, as `parse.codec-syntax`.
fn feed_events(
    parser: &mut Parser<std::str::Chars<'_>>,
    check: &mut alias::AliasCheck,
    max_depth: usize,
) -> Result<Vec<(Event, Marker)>, ScanError> {
    let mut events = Vec::new();
    let mut halted = false;
    loop {
        let (ev, mark) = parser.next_token()?;
        let done = ev == Event::StreamEnd;
        check.event(&ev, (mark.line(), mark.col() + 1));
        if !check.failed() && !halted {
            halted = check.depth() > max_depth + 10;
            events.push((ev, mark));
        }
        if done {
            return Ok(events);
        }
    }
}

fn scan_error_to_parse_error(e: &ScanError) -> ParseError {
    let mark = e.marker();
    ParseError::codec_syntax(mark.line(), mark.col() + 1, format!("invalid YAML: {e}"))
}

/// Parse YAML text into a [`Doc`], with the default [`YamlReadOptions`].
///
/// Exactly one YAML document is accepted (matching Python's `yaml.safe_load`,
/// which raises on a stream containing more than one `---`-separated
/// document); an empty/blank input parses as a `Null` document, also matching
/// `yaml.safe_load("")` returning `None`. A bare top-level sequence, a
/// sequence nested directly inside another sequence, or nesting past
/// [`crate::document::MAX_DEPTH`] all surface as
/// [`crate::error::DocumentError`] (via [`Doc::of`]), matching `json.rs`'s
/// identical `read_json` behavior.
///
/// Input whose alias expansion factor exceeds
/// [`DEFAULT_MAX_ALIAS_EXPANSION`] (spec D-18), or that holds a
/// self-referential anchor (D-20), is rejected with
/// `document.limit.alias-expansion` at `$` before anything is materialized;
/// see [`read_yaml_with`] to change the maximum.
pub fn read_yaml(text: &str) -> Result<Doc, OmnistError> {
    read_yaml_with(text, &YamlReadOptions::default())
}

/// Parse YAML text into a [`Doc`] with explicit [`YamlReadOptions`]; see
/// [`read_yaml`] for everything else.
///
/// Returns the [`YamlReadOptions::validate`] error unchanged when the options
/// are out of range.
pub fn read_yaml_with(text: &str, options: &YamlReadOptions) -> Result<Doc, OmnistError> {
    options.validate()?;
    // D-23: the size is checked first, on the input as received (BOM
    // counted), for every YAML input, an alias-free one included.
    options
        .limits
        .resolve_validated()
        .check_input_size(text.len())?;
    // D-15/D-21: one leading BOM is stripped, a second is rejected at 1:1.
    // Without this pre-check yaml-rust2 would swallow (or keep) the second
    // mark silently; YAML 1.2 itself admits a leading BOM, so the library
    // cannot be relied on to fail (D-21).
    let text = crate::bom::strip_leading_bom(text)
        .map_err(|_| ParseError::codec_syntax(1, 1, crate::bom::DOUBLED_BOM_MESSAGE))?;
    let mut parser = Parser::new(text.chars());
    let mut check = alias::AliasCheck::new(
        u64::from(options.effective_max_alias_expansion()),
        u64::from(options.effective_max_expanded_slots()),
    );
    let limits = options.limits.resolve_validated();
    let events = feed_events(&mut parser, &mut check, limits.max_depth)
        .map_err(|e| scan_error_to_parse_error(&e))?;
    if let Some(e) = check.into_error() {
        return Err(e);
    }
    let mut builder = Builder::new(&limits);
    for (ev, mark) in events {
        builder.on_event(ev, mark);
    }
    if let Some(e) = builder.tag_forbidden {
        return Err(e.into());
    }
    if let Some(e) = builder.self_reference {
        return Err(e.into());
    }
    if let Some(e) = builder.error {
        return Err(e.into());
    }
    if builder.docs.len() > 1 {
        return Err(ParseError::codec_syntax(
            1,
            1,
            "invalid YAML: expected a single document in the stream, found more than one",
        )
        .into());
    }
    let raw = builder.docs.into_iter().next().unwrap_or(Raw::Scalar(
        String::new(),
        TScalarStyle::Plain,
        None,
    ));
    let mut dropped: Vec<Raw> = Vec::new();
    let resolved = resolve_merges(&raw, 0, limits.max_depth, &mut dropped)?;
    let mut guard = IntGuard::new(limits.max_int_digits);
    let value = raw_to_value(&resolved, &Trail::Root, &mut guard)?;
    // A merged value a mapping's own key overrode is never part of the
    // Document, but an integer in it past the digit limit is still refused
    // (D-13): convert what was dropped so the guard sees it. The work is
    // bounded by the size of the (already expansion-limited) tree.
    for node in &dropped {
        note_dropped_integers(node, &mut guard);
    }
    let doc = Doc::of_resolved(&value, limits).map_err(|e| limits.whole_document(e))?;
    // A placeholder for an over-cap literal that never reached the Document
    // is still a limit error (D-13).
    guard.finish(&limits)?;
    Ok(doc)
}

/// Recursively expands every `<<` merge key, depth-guarded the same way
/// `document.rs`'s own construction path is (an alias can smuggle in an
/// already-deep subtree before `Doc::of` ever sees it).
fn resolve_merges(
    node: &Raw,
    depth: usize,
    max_depth: usize,
    dropped: &mut Vec<Raw>,
) -> Result<Raw, OmnistError> {
    crate::document::check_write_depth(depth, "$", max_depth)?;
    match node {
        Raw::Scalar(..) => Ok(node.clone()),
        Raw::Sequence(items) => {
            let mut out = Vec::with_capacity(items.len());
            for item in items {
                out.push(resolve_merges(item, depth + 1, max_depth, dropped)?);
            }
            Ok(Raw::Sequence(out))
        }
        Raw::Mapping(entries) => Ok(Raw::Mapping(resolve_mapping(
            entries, depth, max_depth, dropped,
        )?)),
    }
}

/// Resolves one mapping's entries, flattening every `<<` merge key in.
///
/// The order is normative (`docs/formats/yaml.md`, "Merged entries come
/// first, in source order"): the merged entries come first, in the order the
/// aliases are written (`<<: [*a, *b]` is `a`'s entries, then `b`'s -- never
/// reversed, whatever a YAML library's own constructor does), then the
/// referring mapping's own entries. Key collisions resolve to ONE edge at the
/// position of the key's first occurrence in that order: it carries the
/// referring mapping's own value when the mapping writes one (whether the
/// local key is written before or after the `<<`), otherwise the value from
/// the EARLIEST alias that supplies it.
fn resolve_mapping(
    entries: &[(Raw, Raw)],
    depth: usize,
    max_depth: usize,
    dropped: &mut Vec<Raw>,
) -> Result<Vec<(Raw, Raw)>, OmnistError> {
    let mut merged_from: Vec<(Raw, Raw)> = Vec::new();
    let mut own: Vec<(Raw, Raw)> = Vec::new();
    let mut written: std::collections::HashSet<&str> = std::collections::HashSet::new();
    for (k, v) in entries {
        if is_merge_key(k) {
            merged_from.extend(merge_source_entries(v, depth, max_depth, dropped)?);
        } else {
            // C-12: a key written twice in one mapping is malformed YAML
            // (`a` and `"a"` are one key). A key a merge supplies is not a
            // repeat of one written here: the written one overrides it.
            if let Some(label) = scalar_key_text(k)
                && !written.insert(label)
            {
                return Err(ParseError::codec_syntax(
                    1,
                    1,
                    format!("invalid YAML: duplicate mapping key {label:?}"),
                )
                .into());
            }
            own.push((
                resolve_merges(k, depth + 1, max_depth, dropped)?,
                resolve_merges(v, depth + 1, max_depth, dropped)?,
            ));
        }
    }
    // Merged entries, first supplier of a key wins (this also makes a
    // repeated alias in one sequence contribute once).
    let mut result: Vec<(Raw, Raw)> = Vec::with_capacity(merged_from.len() + own.len());
    let mut position: std::collections::HashMap<String, usize> =
        std::collections::HashMap::with_capacity(merged_from.len());
    for (k, v) in merged_from {
        match scalar_key_text(&k) {
            Some(label) if position.contains_key(label) => dropped.push(v),
            Some(label) => {
                position.insert(label.to_string(), result.len());
                result.push((k, v));
            }
            None => result.push((k, v)),
        }
    }
    // The mapping's own entries: a key a merge already supplied keeps the
    // merged key's position but takes the local value; any other key is
    // appended. A key written twice among the own keys was refused above.
    for (k, v) in own {
        match scalar_key_text(&k).and_then(|label| position.get(label).copied()) {
            Some(at) => dropped.push(std::mem::replace(&mut result[at].1, v)),
            None => result.push((k, v)),
        }
    }
    Ok(result)
}

/// Resolves every scalar of a dropped subtree so an integer past the digit
/// limit leaves its mark on `guard` (which [`IntGuard::finish`] then refuses).
/// Any other outcome of the resolution is irrelevant for a value the Document
/// does not hold.
fn note_dropped_integers(node: &Raw, guard: &mut IntGuard) {
    match node {
        Raw::Scalar(text, style, tag) => {
            let _ = scalar_to_value(text, *style, tag.as_ref(), guard);
        }
        Raw::Sequence(items) => {
            for item in items {
                note_dropped_integers(item, guard);
            }
        }
        Raw::Mapping(entries) => {
            for (_, v) in entries {
                note_dropped_integers(v, guard);
            }
        }
    }
}

/// A merge key's own key text, for de-duplication purposes -- non-scalar
/// (or non-string-scalar) keys never collide with anything by this scheme,
/// matching the fact that only string-labeled fields exist in this model.
fn scalar_key_text(k: &Raw) -> Option<&str> {
    match k {
        Raw::Scalar(s, _, _) => Some(s.as_str()),
        _ => None,
    }
}

/// Whether a scalar is a merge key (D-27): a plain `<<`, or a `<<` tagged
/// `!!merge` (`tag:yaml.org,2002:merge`) in any style. A quoted `<<` and a
/// `!!str <<` are the string `<<`, an ordinary key: an explicit tag decides
/// what a `<<` is, as YAML 1.1 resolves the merge key by its tag.
fn is_merge_scalar(text: &str, style: TScalarStyle, tag: Option<&Tag>) -> bool {
    text == "<<"
        && match tag {
            None => style == TScalarStyle::Plain,
            Some(t) => is_yaml_tag(t, "merge"),
        }
}

/// Whether `tag` is the standard YAML tag `!!suffix` (`tag:yaml.org,2002:suffix`).
fn is_yaml_tag(tag: &Tag, suffix: &str) -> bool {
    tag.handle == "tag:yaml.org,2002:" && tag.suffix == suffix
}

/// Whether `tag` is one of the three collection tags C-13 refuses: `!!pairs`,
/// `!!omap` and `!!set`, on a node of any kind.
fn is_forbidden_tag(tag: Option<&Tag>) -> bool {
    tag.is_some_and(|t| {
        t.handle == "tag:yaml.org,2002:" && matches!(t.suffix.as_str(), "pairs" | "omap" | "set")
    })
}

/// The `format.tag-forbidden` refusal (C-13): well-formed YAML outside the
/// supported profile, so not a syntax error. Its path is `$`.
fn tag_forbidden_error(tag: &Tag) -> DocumentError {
    DocumentError::with_code(
        "$",
        "format.tag-forbidden",
        format!(
            "the YAML tag '!!{}' is outside the supported profile (use a plain sequence or \
             mapping instead)",
            tag.suffix
        ),
    )
}

/// Is `k` a `<<` merge-key marker? See [`is_merge_scalar`].
fn is_merge_key(k: &Raw) -> bool {
    matches!(k, Raw::Scalar(s, style, tag) if is_merge_scalar(s, *style, tag.as_ref()))
}

/// The `(key, value)` pairs a merge key's value contributes: a mapping
/// contributes its own entries directly; a sequence contributes every
/// member's entries in order. The alias check has already refused every other
/// shape (a scalar, a scalar or sequence member, `parse.codec-syntax`, spec
/// D-18a) before this runs, so only mappings reach here.
fn merge_source_entries(
    v: &Raw,
    depth: usize,
    max_depth: usize,
    dropped: &mut Vec<Raw>,
) -> Result<Vec<(Raw, Raw)>, OmnistError> {
    match v {
        // A merged mapping is itself resolved first, so a nested `<<` inside
        // it flattens recursively and the grandparent's entries arrive first.
        Raw::Mapping(entries) => resolve_mapping(entries, depth + 1, max_depth, dropped),
        Raw::Sequence(items) => {
            let mut out = Vec::new();
            for item in items {
                let Raw::Mapping(entries) = item else {
                    unreachable!("the alias check refused a non-mapping merge member")
                };
                out.extend(resolve_mapping(entries, depth + 2, max_depth, dropped)?);
            }
            Ok(out)
        }
        Raw::Scalar(..) => unreachable!("the alias check refused a scalar merge value"),
    }
}

/// Where [`raw_to_value`] is in the tree, as a Document path, kept as a
/// linked chain and rendered only when a diagnostic needs it (a path string
/// per node would cost an allocation per scalar of a large document that
/// never errs).
enum Trail<'a> {
    /// The document root, `$`.
    Root,
    /// A mapping entry's label under the parent position.
    Key(&'a Trail<'a>, &'a str),
    /// The `i`-th of a label's repeated edges under the parent position
    /// (E-10: only when the label occurs more than once, i.e. the sequence
    /// has more than one item).
    Index(&'a Trail<'a>, usize),
}

impl Trail<'_> {
    /// The Document path of this position (`$`, `$.a`, `$.a[1].b`).
    fn render(&self) -> String {
        match self {
            Trail::Root => "$".to_string(),
            Trail::Key(parent, key) => crate::document::join(&parent.render(), key),
            Trail::Index(parent, i) => format!("{}[{i}]", parent.render()),
        }
    }
}

/// Turn a (merge-resolved) [`Raw`] tree into a [`Value`], applying scalar-tag
/// resolution to every leaf along the way. `trail` is where `node` sits, so a
/// diagnostic about it (a non-string mapping key) carries its Document path.
fn raw_to_value(node: &Raw, trail: &Trail<'_>, guard: &mut IntGuard) -> Result<Value, OmnistError> {
    match node {
        Raw::Scalar(text, style, tag) => Ok(scalar_to_value(text, *style, tag.as_ref(), guard)?),
        Raw::Sequence(items) => {
            let mut out = Vec::with_capacity(items.len());
            for (i, item) in items.iter().enumerate() {
                // E-10: no index when the label occurs once.
                let value = if items.len() == 1 {
                    raw_to_value(item, trail, guard)?
                } else {
                    raw_to_value(item, &Trail::Index(trail, i), guard)?
                };
                out.push(value);
            }
            Ok(Value::Array(out))
        }
        Raw::Mapping(entries) => {
            let mut map: IndexMap<String, Value> = IndexMap::new();
            for (k, v) in entries {
                let key = match k {
                    // Route the key through the same implicit-type
                    // resolver mapping *values* already go through
                    // (`scalar_to_value`) -- issue #88, the "Norway
                    // problem": YAML 1.1's core schema resolves a bare
                    // `on`/`off`/`yes`/`no`/`true`/`false`/`~`/etc. key the
                    // same way it would as a value. A label MUST be a
                    // string, so a key that resolves to anything else
                    // (bool, null, int, float) is rejected here, matching
                    // Python's `DocumentError: object key <value> is not a
                    // string` (live-confirmed).
                    Raw::Scalar(s, style, tag) => {
                        match scalar_to_value(s, *style, tag.as_ref(), guard)? {
                            Value::Str(s) => s,
                            // An over-long integer used as a key: the digit
                            // limit is what refuses it, not the missing label.
                            Value::Int(i) if int_exceeds(&i, guard.max()) => {
                                return Err(DocumentError::with_code(
                                    trail.render(),
                                    "document.limit.int-digits",
                                    crate::formats::int_cap::over_cap_message(
                                        "invalid YAML: ",
                                        guard.max(),
                                    ),
                                )
                                .into());
                            }
                            other => {
                                // `document.unlabeled-element`: the key has no
                                // string label to become an edge. Its path is
                                // that of the mapping the key is in (`$` for
                                // the top-level mapping).
                                return Err(DocumentError::with_code(
                                    trail.render(),
                                    "document.unlabeled-element",
                                    format!(
                                        "object key {} is not a string",
                                        describe_non_string_key(&other)
                                    ),
                                )
                                .into());
                            }
                        }
                    }
                    _ => {
                        return Err(ParseError::codec_syntax(
                            1,
                            1,
                            "invalid YAML: a mapping key must be a scalar",
                        )
                        .into());
                    }
                };
                // No key repeats here: `resolve_mapping` refused a repeated
                // key (C-12) before this tree was built.
                let value = raw_to_value(v, &Trail::Key(trail, &key), guard)?;
                map.insert(key, value);
            }
            Ok(Value::Object(map))
        }
    }
}

/// Renders a non-string [`Value`] the way Python's reference implementation
/// spells it in its `DocumentError` message (`True`/`False`/`None`/a plain
/// number), for parity with the diagnostic text PyYAML/`omnist`'s own
/// `object key <value> is not a string` error uses -- live-confirmed:
/// `omnist.read_yaml("on:\n  push: true\n")` raises `object key True is not
/// a string`. Only `Bool`/`Null`/`Int`/`Float` are structurally reachable
/// here -- `scalar_to_value` (this function's only caller's source) never
/// produces `Str` (excluded by the caller's own match arm before this runs)
/// or `Array`/`Object` (it operates on a single `Raw::Scalar` leaf) -- the
/// wildcard arm is an unreachable-but-harmless fallback, not a real case.
fn describe_non_string_key(v: &Value) -> String {
    match v {
        Value::Bool(true) => "True".to_string(),
        Value::Bool(false) => "False".to_string(),
        Value::Null => "None".to_string(),
        Value::Int(i) => i.to_string(),
        Value::Float(f) => {
            // Rust's `f64::to_string()` renders whole numbers like `1.0`
            // as `"1"`, but Python's `repr(float)` always keeps the `.0`
            // -- confirmed live: `repr(1.0)` is `'1.0'`, not `'1'`.
            let s = f.to_string();
            if f.is_finite() && !s.contains('.') && !s.contains('e') && !s.contains('E') {
                format!("{s}.0")
            } else {
                s
            }
        }
        other => format!("{other:?}"),
    }
}

fn scalar_to_value(
    text: &str,
    style: TScalarStyle,
    tag: Option<&Tag>,
    guard: &mut IntGuard,
) -> Result<Value, ParseError> {
    if let Some(t) = tag
        && t.handle == "tag:yaml.org,2002:"
    {
        return explicit_tag_to_value(text, &t.suffix, guard);
    }
    if style != TScalarStyle::Plain {
        return Ok(Value::Str(text.to_string()));
    }
    resolve_plain_scalar(text, guard)
}

/// Constructs a [`Value`] from an explicit standard YAML tag
/// (`!!str`/`!!int`/`!!float`/`!!bool`/`!!null`), matching what PyYAML's
/// `SafeConstructor` supports for these five. Any other explicit tag (a
/// custom `!!` type, `!!seq`/`!!map` forced onto a scalar, an unknown handle)
/// is rejected with a [`ParseError`] -- PyYAML's `SafeConstructor` itself
/// raises `ConstructorError: could not determine a constructor for the tag`
/// for anything it doesn't recognize, so this is matching behavior, not an
/// arbitrarily narrower one.
fn explicit_tag_to_value(
    text: &str,
    suffix: &str,
    guard: &mut IntGuard,
) -> Result<Value, ParseError> {
    match suffix {
        "str" => Ok(Value::Str(text.to_string())),
        "null" => Ok(Value::Null),
        // PyYAML's `SafeConstructor.construct_yaml_bool` looks up
        // `node.value.lower()` in `bool_values = {"yes": True, "no": False,
        // "true": True, "false": False, "on": True, "off": False}`
        // regardless of how the `!!bool` tag got attached (explicit or
        // implicit) -- live-confirmed (see module doc comment): `!!bool
        // "YES"`/`"On"`/`"OFF"` all construct successfully, not just
        // true/false spellings; bare `y`/`n`/`1`/`0` do not (`KeyError`).
        "bool" => match text.to_ascii_lowercase().as_str() {
            "true" | "yes" | "on" => Ok(Value::Bool(true)),
            "false" | "no" | "off" => Ok(Value::Bool(false)),
            _ => Err(ParseError::codec_syntax(
                1,
                1,
                format!("invalid YAML: {text:?} is not a valid !!bool value"),
            )),
        },
        "int" => parse_int_literal(text, guard),
        "float" => parse_float_literal(text),
        other => Err(ParseError::codec_syntax(
            1,
            1,
            format!("invalid YAML: unsupported explicit tag '!!{other}'"),
        )),
    }
}

/// PyYAML's `tag:yaml.org,2002:bool` implicit-resolver spelling set --
/// live-confirmed (see module doc comment): `yes`/`no`/`on`/`off` (and case
/// variants) count as booleans; bare `y`/`n` do not.
fn resolve_plain_scalar(text: &str, guard: &mut IntGuard) -> Result<Value, ParseError> {
    match text {
        "" | "~" | "null" | "Null" | "NULL" => return Ok(Value::Null),
        "true" | "True" | "TRUE" | "yes" | "Yes" | "YES" | "on" | "On" | "ON" => {
            return Ok(Value::Bool(true));
        }
        "false" | "False" | "FALSE" | "no" | "No" | "NO" | "off" | "Off" | "OFF" => {
            return Ok(Value::Bool(false));
        }
        _ => {}
    }
    if is_int_literal_shape(text) {
        return parse_int_literal(text, guard);
    }
    if is_sexagesimal_int_shape(text) {
        return parse_sexagesimal_int(text, guard);
    }
    if is_float_literal_shape(text) {
        return parse_float_literal(text);
    }
    if SEXAGESIMAL_FLOAT_RE.is_match(text) {
        return Ok(parse_sexagesimal_float(text));
    }
    if let Some(iso) = normalize_timestamp(text)? {
        // YAML's own implicit-resolver timestamp grammar (unlike OML's or
        // TOML's) has no standalone bare-time form -- `normalize_timestamp`
        // only ever produces a date-only or a full datetime spelling, never
        // a time-only one (issue #105: real provenance instead of staying
        // `Str`, the same fix issue #99 already applied to OML). A
        // datetime spelling always contains the date/time `T` separator;
        // a date-only one never does.
        return Ok(if iso.contains('T') {
            Value::Datetime(iso)
        } else {
            Value::Date(iso)
        });
    }
    Ok(Value::Str(text.to_string()))
}

/// Live-confirmed against `yaml.safe_load` (see module doc comment): PyYAML's
/// `tag:yaml.org,2002:int` implicit resolver recognizes `0x`/`0b` prefixes and
/// a bare leading zero as octal (`"017" -> 15`), but **not** a YAML-1.2-style
/// `0o` prefix (`"0o17"` stays a plain string). The legacy sexagesimal
/// `1:20` form is handled separately by [`SEXAGESIMAL_INT_RE`]/
/// [`is_sexagesimal_int_shape`] below (issue #87 -- this comment previously
/// called it "out of scope", but the spec (`docs/formats/yaml.md`) and both
/// sibling ports require it; that framing was simply wrong).
static INT_RE: std::sync::LazyLock<regex::Regex> = std::sync::LazyLock::new(|| {
    regex::Regex::new(
        r"^(?:[-+]?0b[0-1_]+|[-+]?0[0-7_]+|[-+]?(?:0|[1-9][0-9_]*)|[-+]?0x[0-9a-fA-F_]+)$",
    )
    .unwrap()
});

fn is_int_literal_shape(text: &str) -> bool {
    INT_RE.is_match(text)
}

/// PyYAML's legacy sexagesimal integer form: a colon-separated run of
/// base-60 digit groups, e.g. `12:00:00` -> `12*3600 + 0*60 + 0 = 43200`.
/// Live-confirmed against `yaml.safe_load`/`omnist.read_yaml` (issue #87):
/// the first group must NOT have a leading zero (`"0:0:1"`/`"01:20"` stay
/// plain strings) and every subsequent group is constrained to `0-59`
/// (`"1:60"`/`"1:600"` stay plain strings) -- exactly mirroring PyYAML's own
/// `tag:yaml.org,2002:int` resolver regex
/// (`^[-+]?[1-9][0-9_]*(:[0-5]?[0-9])+$`, see
/// <https://yaml.org/type/int.html>).
static SEXAGESIMAL_INT_RE: std::sync::LazyLock<regex::Regex> = std::sync::LazyLock::new(|| {
    regex::Regex::new(r"^[-+]?[1-9][0-9_]*(?::[0-5]?[0-9])+$").unwrap()
});

fn is_sexagesimal_int_shape(text: &str) -> bool {
    SEXAGESIMAL_INT_RE.is_match(text)
}

/// Parses a sexagesimal-shaped string (already confirmed via
/// [`is_sexagesimal_int_shape`]) into its base-60 integer value: fold each
/// `:`-separated group left to right as `acc = acc*60 + group`, matching
/// PyYAML's `construct_yaml_int`'s own sexagesimal branch.
///
/// Arbitrary-precision (issue #104): the fold itself can no longer
/// overflow -- `BigInt` has no width limit -- so `MAX_INT_DIGITS` (the
/// same cap `parse_int_literal` enforces) is checked explicitly on the
/// fold's *result* instead. This replaces a real guard, not just
/// tidies one: the old `i64` accumulator's `checked_mul`/`checked_add`
/// overflow was incidentally bounding a many-group literal like
/// `1:0:0:...:0` (thousands of groups); a naive swap to unchecked
/// `BigInt` arithmetic here would silently remove that bound entirely,
/// letting such a literal build an arbitrarily large integer.
fn parse_sexagesimal_int(text: &str, guard: &mut IntGuard) -> Result<Value, ParseError> {
    let neg = text.starts_with('-');
    let t = text.strip_prefix(['+', '-']).unwrap_or(text);
    let mut acc = BigInt::from(0);
    let sixty = BigInt::from(60);
    for group in t.split(':') {
        let cleaned: String = group.chars().filter(|&c| c != '_').collect();
        // Every group is guaranteed decimal digits by `SEXAGESIMAL_INT_RE`
        // (the caller's shape check) -- this can't fail.
        let digit = BigInt::parse_bytes(cleaned.as_bytes(), 10)
            .expect("SEXAGESIMAL_INT_RE guarantees decimal digit groups");
        acc = acc * &sixty + digit;
    }
    let value = if neg { -acc } else { acc };
    if int_exceeds(&value, guard.max()) {
        return Ok(Value::Int(guard.placeholder()));
    }
    Ok(Value::Int(value))
}

/// Arbitrary-precision (issue #104): a magnitude that fits the shape
/// `is_int_literal_shape` already confirmed always parses -- no more
/// `i64`-overflow special-casing (the old version's own comment about
/// `i64::MIN`'s asymmetric magnitude is now moot, since `BigInt` negation
/// never overflows).
fn parse_int_literal(text: &str, guard: &mut IntGuard) -> Result<Value, ParseError> {
    let neg = text.starts_with('-');
    let t = text.strip_prefix(['+', '-']).unwrap_or(text);
    let cleaned: String = t.chars().filter(|&c| c != '_').collect();
    let (radix, digits) = if let Some(rest) = cleaned.strip_prefix("0x") {
        (16, rest)
    } else if let Some(rest) = cleaned.strip_prefix("0b") {
        (2, rest)
    } else if cleaned.starts_with('0') && cleaned.len() > 1 {
        (8, &cleaned[1..])
    } else {
        (10, cleaned.as_str())
    };
    if radix == 10 && digits.len() > guard.max() {
        return Ok(Value::Int(guard.placeholder()));
    }
    // Implicit resolution only calls this after `is_int_literal_shape` has
    // confirmed the shape, but an EXPLICIT `!!int` tag reaches it with any
    // text at all (`a: !!int x`), so the digits are not guaranteed valid.
    let Some(magnitude) = BigInt::parse_bytes(digits.as_bytes(), radix) else {
        return Err(ParseError::codec_syntax(
            1,
            1,
            format!("invalid YAML: {text:?} is not a valid !!int value"),
        ));
    };
    let value = if neg { -magnitude } else { magnitude };
    Ok(Value::Int(value))
}

/// Live-confirmed against `yaml.safe_load`: PyYAML's `tag:yaml.org,2002:float`
/// implicit resolver requires a literal `.` -- `"1e3"` (no decimal point)
/// stays a plain string, and the exponent sign is **mandatory** when present
/// (`"1.0e3"` stays a string; `"1.0e+3"`/`"1.0e-3"` are floats). The legacy
/// sexagesimal float form is out of scope, same rationale as
/// `is_int_literal_shape`.
static FLOAT_RE: std::sync::LazyLock<regex::Regex> = std::sync::LazyLock::new(|| {
    regex::Regex::new(
        r"^(?:[-+]?(?:[0-9][0-9_]*)\.[0-9_]*(?:[eE][-+][0-9]+)?|\.[0-9][0-9_]*(?:[eE][-+][0-9]+)?|[-+]?\.(?:inf|Inf|INF)|\.(?:nan|NaN|NAN))$",
    )
    .unwrap()
});

/// PyYAML's legacy sexagesimal float form (C-17): colon-separated base-60
/// groups ending in a fractional group, `1:30.5` -> `90.5`. Mirrors PyYAML's
/// `tag:yaml.org,2002:float` resolver regex
/// (`^[-+]?[0-9][0-9_]*(:[0-5]?[0-9])+\.[0-9_]*$`).
static SEXAGESIMAL_FLOAT_RE: std::sync::LazyLock<regex::Regex> = std::sync::LazyLock::new(|| {
    regex::Regex::new(r"^[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+\.[0-9_]*$").unwrap()
});

/// Folds a sexagesimal-float-shaped string (confirmed by
/// [`SEXAGESIMAL_FLOAT_RE`]) left to right as `acc = acc*60 + group`, the last
/// group carrying the fraction, as PyYAML's `construct_yaml_float` does.
fn parse_sexagesimal_float(text: &str) -> Value {
    let neg = text.starts_with('-');
    let t = text.strip_prefix(['+', '-']).unwrap_or(text);
    let cleaned: String = t.chars().filter(|&c| c != '_').collect();
    let mut acc = 0.0_f64;
    for group in cleaned.split(':') {
        let group: f64 = group
            .parse()
            .expect("SEXAGESIMAL_FLOAT_RE guarantees numeric groups");
        acc = acc * 60.0 + group;
    }
    Value::Float(if neg { -acc } else { acc })
}

fn is_float_literal_shape(text: &str) -> bool {
    FLOAT_RE.is_match(text)
}

fn parse_float_literal(text: &str) -> Result<Value, ParseError> {
    match text {
        ".inf" | ".Inf" | ".INF" | "+.inf" | "+.Inf" | "+.INF" => {
            return Ok(Value::Float(f64::INFINITY));
        }
        "-.inf" | "-.Inf" | "-.INF" => return Ok(Value::Float(f64::NEG_INFINITY)),
        ".nan" | ".NaN" | ".NAN" => return Ok(Value::Float(f64::NAN)),
        _ => {}
    }
    let cleaned: String = text.chars().filter(|&c| c != '_').collect();
    cleaned.parse::<f64>().map(Value::Float).map_err(|_| {
        ParseError::codec_syntax(
            1,
            1,
            format!("invalid YAML: invalid float literal {text:?}"),
        )
    })
}

/// Reproduces PyYAML's `tag:yaml.org,2002:timestamp` resolver + construction
/// (`construct_yaml_timestamp`): accepts a bare ISO date, or a date/time
/// joined by `T`/`t`/one-or-more spaces, with an optional fractional-second
/// part and an optional `Z`/`±HH[:MM]` offset -- and returns the value
/// re-spelled the way `datetime.date.isoformat()`/`datetime.datetime.isoformat()`
/// would: zero-padded, `T`-joined, offset as `+HH:MM`/`-HH:MM` (a bare `Z`
/// becomes `+00:00`, matching `datetime.timezone.utc`'s own `isoformat()`).
/// Returns `Ok(None)` for anything not shaped like a timestamp at all (the
/// overwhelmingly common case -- most plain scalars are plain strings).
///
/// A string that *is* timestamp-shaped but names a calendar/clock value that
/// doesn't exist (`2024-13-01`, `2024-02-30`, `2024-01-01T25:00:00`, an
/// out-of-range timezone offset) is a [`ParseError`], **not** a silent
/// fallback to a plain string -- live-confirmed against PyYAML (see this
/// module's doc comment): `yaml.safe_load` calls `datetime.date`/
/// `datetime.datetime`'s constructor on the captured fields, which raises a
/// `ValueError` PyYAML doesn't catch, so the *whole document* fails to parse
/// rather than quietly typing the value as a string. Calendar-date validity
/// (leap years, per-month day counts) reuses `crate::schema::valid_ymd`/
/// `crate::schema::valid_hms` rather than a second copy of that logic.
fn normalize_timestamp(text: &str) -> Result<Option<String>, ParseError> {
    static RE: std::sync::LazyLock<regex::Regex> = std::sync::LazyLock::new(|| {
        regex::Regex::new(
            r"^(?P<year>[0-9]{4})-(?P<month>[0-9][0-9]?)-(?P<day>[0-9][0-9]?)(?:(?:[Tt]|[ \t]+)(?P<hour>[0-9][0-9]?):(?P<minute>[0-9][0-9]):(?P<second>[0-9][0-9])(?:\.(?P<fraction>[0-9]*))?(?:[ \t]*(?:Z|(?P<tz_sign>[-+])(?P<tz_hour>[0-9][0-9]?)(?::(?P<tz_minute>[0-9][0-9]))?))?)?$",
        )
        .unwrap()
    });
    let Some(caps) = RE.captures(text) else {
        return Ok(None);
    };
    let bad = |what: &str| {
        Err(ParseError::codec_syntax(
            1,
            1,
            format!("invalid YAML: {text:?} is timestamp-shaped but names an invalid {what}"),
        ))
    };
    let year: u32 = caps["year"].parse().unwrap_or(u32::MAX);
    let month: u32 = caps["month"].parse().unwrap_or(u32::MAX);
    let day: u32 = caps["day"].parse().unwrap_or(u32::MAX);
    if !crate::schema::valid_ymd(year, month, day) {
        return bad("calendar date");
    }
    let Some(hour_m) = caps.name("hour") else {
        return Ok(Some(format!("{year:04}-{month:02}-{day:02}")));
    };
    let hour: u32 = hour_m.as_str().parse().unwrap_or(u32::MAX);
    let minute: u32 = caps["minute"].parse().unwrap_or(u32::MAX);
    let second: u32 = caps["second"].parse().unwrap_or(u32::MAX);
    if !crate::schema::valid_hms(hour, minute, second) {
        return bad("time of day");
    }
    let mut out = format!("{year:04}-{month:02}-{day:02}T{hour:02}:{minute:02}:{second:02}");
    if let Some(frac) = caps.name("fraction") {
        let mut digits = frac.as_str().to_string();
        // The Document model holds at most six fractional digits; a
        // non-zero digit beyond them cannot be kept, so it fails rather
        // than being truncated (fail, don't invent). Trailing zeros are
        // insignificant.
        if digits.len() > 6 && digits[6..].bytes().any(|b| b != b'0') {
            return bad("fractional second (more than six digits)");
        }
        while digits.len() < 6 {
            digits.push('0');
        }
        digits.truncate(6);
        out.push('.');
        out.push_str(&digits);
    }
    match caps.name("tz_sign") {
        Some(sign) => {
            let tz_hour: u32 = caps["tz_hour"].parse().unwrap_or(u32::MAX);
            let tz_minute: u32 = caps
                .name("tz_minute")
                .map(|m| m.as_str().parse().unwrap_or(u32::MAX))
                .unwrap_or(0);
            if tz_hour > 23 || tz_minute > 59 {
                return bad("timezone offset");
            }
            out.push_str(sign.as_str());
            out.push_str(&format!("{tz_hour:02}:{tz_minute:02}"));
        }
        None if text.trim_end().ends_with('Z') => out.push_str("+00:00"),
        None => {}
    }
    Ok(Some(out))
}

// ============================================================== Writer

/// Project a [`Doc`] to YAML text (block style, 2-space indent, insertion
/// order preserved -- matching Python's `yaml.dump(..., sort_keys=False,
/// default_flow_style=False)`).
pub fn write_yaml(
    doc: &Doc,
    strict: bool,
    report: Option<&mut WriteReport>,
) -> Result<String, WriteError> {
    let grouped = doc.to_grouped();
    let mut rep = check_yaml_grouped(&grouped);
    add_interleaving_diagnostic(doc, &mut rep);
    let mut out = String::new();
    write_node(&grouped, 0, &mut out, true);
    if out.ends_with('\n') {
        out.pop();
    }
    crate::report::finish_write(out, rep, strict, report)
}

/// `format.interleaving-lost` (spec Sec8.3.8, D-3) is a whole-document
/// diagnostic that depends on the original `Doc`'s edge order, lost by the
/// time `to_grouped` runs -- so it is detected separately via
/// `Doc::has_interleaving_loss` rather than folded into `check_yaml_grouped`'s
/// grouped-`Value` walk.
fn add_interleaving_diagnostic(doc: &Doc, rep: &mut WriteReport) {
    if doc.has_interleaving_loss() {
        rep.add(
            "$",
            "format.interleaving-lost",
            "cross-label interleaving could not be written; same-label edges were grouped",
            Severity::Warning,
        );
    }
}

/// Report what writing YAML would adjust, without producing output. The only
/// adjustment YAML ever needs is forcing double-quoted style for a U+0085
/// (NEL) string/label -- see this module's doc comment.
pub fn check_yaml(doc: &Doc) -> WriteReport {
    let grouped = doc.to_grouped();
    let mut rep = check_yaml_grouped(&grouped);
    add_interleaving_diagnostic(doc, &mut rep);
    rep
}

fn check_yaml_grouped(grouped: &Value) -> WriteReport {
    let mut rep = WriteReport::new();
    let mut path = String::from("$");
    crate::formats::visit_grouped(grouped, &mut path, &mut |visited, path| match visited {
        crate::formats::Visited::Edge { label } if label.contains('\u{0085}') => {
            rep.add(
                path,
                "format.string-line-break-char",
                "label contains U+0085 (NEL); written double-quoted to round-trip correctly",
                Severity::Warning,
            );
        }
        crate::formats::Visited::Node {
            value: Value::Str(s),
        } if s.contains('\u{0085}') => {
            rep.add(
                path,
                "format.string-line-break-char",
                "value contains U+0085 (NEL); written double-quoted to round-trip correctly",
                Severity::Warning,
            );
        }
        // E-37 rule 4: YAML 1.1 has no time-of-day type, so every `time` is
        // written as a double-quoted string.
        crate::formats::Visited::Node {
            value: Value::Datetime(s),
        } if crate::formats::fraction_inexact(s) => {
            rep.add(
                path,
                "format.temporal-stringified",
                "fractional second has more than six digits; wrote as a quoted ISO-8601 string",
                Severity::Warning,
            );
        }
        crate::formats::Visited::Node {
            value: Value::Time(_),
        } => {
            rep.add(
                path,
                "format.temporal-stringified",
                "time has no native YAML literal; wrote as a quoted ISO-8601 string",
                Severity::Warning,
            );
        }
        _ => {}
    });
    rep
}

/// Marker type implementing [`crate::formats::Codec`] for YAML -- adapts
/// [`read_yaml`]/[`write_yaml`]/[`check_yaml`] to the registry's uniform
/// shape with the documented defaults (`strict: false`, no report).
pub(crate) struct Yaml;

impl crate::formats::Codec for Yaml {
    const NAME: &'static str = "yaml";

    fn read(text: &str) -> Result<Doc, OmnistError> {
        read_yaml(text)
    }

    fn write(doc: &Doc) -> Result<String, OmnistError> {
        write_yaml(doc, false, None).map_err(Into::into)
    }

    fn check(doc: &Doc) -> WriteReport {
        check_yaml(doc)
    }
}

fn indent(out: &mut String, level: usize) {
    for _ in 0..level {
        out.push_str("  ");
    }
}

/// Writes `node` at `level`, matching PyYAML's block style: a scalar directly
/// after `key:`/`- ` on the same line; a nested mapping/sequence starts on
/// the next line, indented. `top` is `true` only for the document root, which
/// (for an empty root object) still needs `{}` -- an empty nested object
/// is written the same way PyYAML does, inline `{}`/`[]`.
fn write_node(node: &Value, level: usize, out: &mut String, top: bool) {
    match node {
        Value::Object(map) if map.is_empty() => {
            out.push_str("{}\n");
        }
        Value::Array(items) if items.is_empty() => {
            out.push_str("[]\n");
        }
        Value::Object(map) => {
            for (label, child) in map {
                indent(out, level);
                write_scalar(label, out);
                out.push(':');
                write_child(child, level, out);
            }
            let _ = top;
        }
        Value::Array(items) => {
            for item in items {
                indent(out, level);
                out.push('-');
                write_seq_child(item, level, out);
            }
        }
        other => {
            write_scalar_value(other, out);
            out.push('\n');
        }
    }
}

fn write_child(child: &Value, level: usize, out: &mut String) {
    match child {
        Value::Object(m) if !m.is_empty() => {
            out.push('\n');
            write_node(child, level + 1, out, false);
        }
        Value::Array(a) if !a.is_empty() => {
            out.push('\n');
            write_node(child, level, out, false);
        }
        _ => {
            out.push(' ');
            write_node(child, level + 1, out, false);
        }
    }
}

fn write_seq_child(item: &Value, level: usize, out: &mut String) {
    match item {
        Value::Object(m) if !m.is_empty() => {
            out.push(' ');
            // The first field of a mapping under a `- ` sequence marker is
            // written on the same line as the dash; PyYAML indents the
            // remaining fields to align under it (one level deeper than the
            // dash itself, i.e. `level + 1`).
            let mut first = true;
            for (label, child) in m {
                if !first {
                    indent(out, level + 1);
                }
                first = false;
                write_scalar(label, out);
                out.push(':');
                write_child(child, level + 1, out);
            }
        }
        Value::Array(a) if !a.is_empty() => {
            out.push('\n');
            write_node(item, level + 1, out, false);
        }
        _ => {
            out.push(' ');
            write_node(item, level + 1, out, false);
        }
    }
}

fn write_scalar(s: &str, out: &mut String) {
    write_scalar_value(&Value::Str(s.to_string()), out);
}

fn write_scalar_value(v: &Value, out: &mut String) {
    match v {
        Value::Null => out.push_str("null"),
        Value::Bool(b) => out.push_str(if *b { "true" } else { "false" }),
        Value::Int(i) => out.push_str(&i.to_string()),
        Value::Float(x) => write_float(*x, out),
        // Always quoted -- no shape-guessing (issue #105, the same fix
        // issue #99 already applied to OML). A genuinely temporal-kinded
        // value is a `Date`/`Time`/`Datetime` variant, not a
        // shape-matched `Str`.
        Value::Str(s) => write_yaml_string(s, out),
        // Written bare unconditionally -- by construction (see
        // `Scalar::Date`'s own doc comment) always already a validated,
        // canonical spelling that YAML's own implicit resolver reads back
        // as the identical kind (`normalize_timestamp` produces exactly
        // this date-or-datetime shape, see `resolve_plain_scalar`).
        Value::Date(s) => out.push_str(s),
        Value::Datetime(s) => {
            let text = super::temporal_text(s, true);
            if super::fraction_inexact(&text) {
                write_quoted(&text, &YAML_ESCAPES, out);
            } else {
                out.push_str(&text);
            }
        }
        // Unlike `Date`/`Datetime`, YAML's implicit resolver has no bare
        // standalone-time form at all (`normalize_timestamp`'s grammar
        // always requires a date) -- a genuine `Time` value (e.g. from a
        // schema-directed upgrade of a JSON-sourced sample, or read from
        // OML's own bare time grammar) has no native YAML spelling, so it
        // must stay a quoted string, the same fallback TOML's writer uses
        // for a `Time` value that carries a UTC offset.
        Value::Time(s) => write_quoted(&super::temporal_text(s, false), &YAML_ESCAPES, out),
        Value::Object(_) | Value::Array(_) => {
            unreachable!("write_scalar_value is only ever called on a leaf")
        }
    }
}

/// See `formats::float_fmt` (issue #47) for the shared render-then-inspect
/// core (issue #46's fix); this is just YAML's spelling table.
fn write_float(x: f64, out: &mut String) {
    float_fmt::write_float(x, ".nan", ".inf", "-.inf", out);
}

/// Writes `s` as a YAML scalar: double-quoted (with the U+0085 escape
/// `check_yaml` warns about) if it contains a NEL, or if writing it bare
/// would round-trip back as a *different* value (it would be re-resolved as
/// null/bool/int/float/timestamp, it's empty, or it has YAML-significant
/// leading/embedded punctuation) -- otherwise written plain.
fn write_yaml_string(s: &str, out: &mut String) {
    if needs_quoting(s) {
        write_quoted(s, &YAML_ESCAPES, out);
    } else {
        out.push_str(s);
    }
}

fn needs_quoting(s: &str) -> bool {
    if s.is_empty() || s.contains('\u{0085}') || s.contains('\n') {
        return true;
    }
    // C-14: a character YAML 1.1 does not print is escaped, so the scalar is
    // double-quoted (tab and CR keep their existing plain handling).
    if s.chars()
        .any(|c| (c < ' ' && c != '\t' && c != '\r') || YAML_ESCAPES.also_escape.contains(&c))
    {
        return true;
    }
    // A string that starts with a byte-order mark is always quoted (D-15,
    // D-21): written bare as the very first key or the whole document it
    // would put a leading BOM at offset zero of the output, which a writer
    // MUST NOT emit and which a reader strips (changing the label) or, doubled,
    // rejects.
    if s.starts_with(crate::bom::BOM) {
        return true;
    }
    if matches!(resolve_plain_scalar(s, &mut IntGuard::new(crate::formats::int_cap::MAX_INT_DIGITS)), Ok(Value::Str(ref t)) if t == s)
    {
        // Round-trips as the identical plain string -- but a leading char /
        // embedded token that's YAML-significant still needs quoting even
        // though resolve_plain_scalar wouldn't itself retype it.
    } else {
        return true; // would be re-read as null/bool/int/float/timestamp
    }
    // `s` is guaranteed non-empty here: the early return at line 1021-1023
    // already handles `s.is_empty()`, so `.chars().next()` always yields a
    // char.
    let first = s.chars().next().unwrap();
    if matches!(
        first,
        '-' | '?'
            | ':'
            | ','
            | '['
            | ']'
            | '{'
            | '}'
            | '#'
            | '&'
            | '*'
            | '!'
            | '|'
            | '>'
            | '\''
            | '"'
            | '%'
            | '@'
            | '`'
            | ' '
    ) {
        return true;
    }
    if s.ends_with(' ') || s.contains(": ") || s.ends_with(':') || s.contains(" #") {
        return true;
    }
    false
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::document::{Doc, Scalar, Value};
    use crate::formats::int_cap::MAX_INT_DIGITS;

    fn obj(pairs: Vec<(&str, Value)>) -> Value {
        Value::Object(pairs.into_iter().map(|(k, v)| (k.to_string(), v)).collect())
    }

    fn doc_of(v: Value) -> Doc {
        Doc::of(&v).unwrap()
    }

    // ---------------------------------------------------------- reader: scalars

    #[test]
    fn reads_every_scalar_kind() {
        let doc = read_yaml("a: 1\nb: \"s\"\nc: true\nd: null\ne: 1.5\n").unwrap();
        let root = doc.root();
        assert_eq!(
            *root.get_one("a").unwrap().value().unwrap(),
            Scalar::Int((1).into())
        );
        assert_eq!(
            *root.get_one("b").unwrap().value().unwrap(),
            Scalar::Str("s".to_string())
        );
        assert_eq!(
            *root.get_one("c").unwrap().value().unwrap(),
            Scalar::Bool(true)
        );
        assert_eq!(*root.get_one("d").unwrap().value().unwrap(), Scalar::Null);
        assert_eq!(
            *root.get_one("e").unwrap().value().unwrap(),
            Scalar::Float(1.5)
        );
    }

    #[test]
    fn reads_yaml_1_1_bool_spellings_but_not_bare_y_or_n() {
        let doc = read_yaml("a: yes\nb: no\nc: on\nd: off\ne: Yes\nf: y\ng: n\n").unwrap();
        let root = doc.root();
        assert_eq!(
            *root.get_one("a").unwrap().value().unwrap(),
            Scalar::Bool(true)
        );
        assert_eq!(
            *root.get_one("b").unwrap().value().unwrap(),
            Scalar::Bool(false)
        );
        assert_eq!(
            *root.get_one("c").unwrap().value().unwrap(),
            Scalar::Bool(true)
        );
        assert_eq!(
            *root.get_one("d").unwrap().value().unwrap(),
            Scalar::Bool(false)
        );
        assert_eq!(
            *root.get_one("e").unwrap().value().unwrap(),
            Scalar::Bool(true)
        );
        // 'y'/'n' alone stay strings -- live-confirmed against PyYAML (see
        // module doc comment).
        assert_eq!(
            *root.get_one("f").unwrap().value().unwrap(),
            Scalar::Str("y".to_string())
        );
        assert_eq!(
            *root.get_one("g").unwrap().value().unwrap(),
            Scalar::Str("n".to_string())
        );
    }

    #[test]
    fn a_string_starting_with_a_bom_is_quoted_so_the_output_never_leads_with_one() {
        let doc = doc_of(obj(vec![(
            "\u{FEFF}k",
            Value::Str("\u{FEFF}v".to_string()),
        )]));
        let text = write_yaml(&doc, false, None).unwrap();
        assert!(text.starts_with('"'), "{text:?}");
        assert!(!text.starts_with('\u{FEFF}'));
        // It reads back to the same Document (the mark survives inside quotes).
        assert_eq!(read_yaml(&text).unwrap().to_raw(), doc.to_raw());
        // A mark that is not first is not quoted for its sake.
        let doc = doc_of(obj(vec![("a\u{FEFF}b", Value::Str("x".to_string()))]));
        assert_eq!(write_yaml(&doc, false, None).unwrap(), "a\u{FEFF}b: x");
    }

    #[test]
    fn quoted_yes_stays_a_string_not_a_bool() {
        let doc = read_yaml("a: \"yes\"\n").unwrap();
        assert_eq!(
            *doc.root().get_one("a").unwrap().value().unwrap(),
            Scalar::Str("yes".to_string())
        );
    }

    #[test]
    fn reads_null_spellings() {
        let doc = read_yaml("a: ~\nb: null\nc: Null\nd: NULL\ne:\n").unwrap();
        let root = doc.root();
        for label in ["a", "b", "c", "d", "e"] {
            assert_eq!(*root.get_one(label).unwrap().value().unwrap(), Scalar::Null);
        }
    }

    #[test]
    fn reads_negative_and_hex_and_octal_and_binary_ints() {
        // Note: PyYAML's legacy (YAML-1.1-derived) int resolver recognizes a
        // *bare leading zero* as octal ("017" -> 15), not a `0o` prefix --
        // live-confirmed (see module doc comment on `INT_RE`); a separate
        // test below pins `"0o17"` staying a string for that exact reason.
        let doc = read_yaml("a: -5\nb: 0x1A\nc: 017\nd: 0b101\ne: 1_000\n").unwrap();
        let root = doc.root();
        assert_eq!(
            *root.get_one("a").unwrap().value().unwrap(),
            Scalar::Int((-5).into())
        );
        assert_eq!(
            *root.get_one("b").unwrap().value().unwrap(),
            Scalar::Int((26).into())
        );
        assert_eq!(
            *root.get_one("c").unwrap().value().unwrap(),
            Scalar::Int((15).into())
        );
        assert_eq!(
            *root.get_one("d").unwrap().value().unwrap(),
            Scalar::Int((5).into())
        );
        assert_eq!(
            *root.get_one("e").unwrap().value().unwrap(),
            Scalar::Int((1000).into())
        );
    }

    #[test]
    fn a_yaml_1_2_style_0o_octal_prefix_is_not_recognized_and_stays_a_string() {
        let doc = read_yaml("a: 0o17\n").unwrap();
        assert_eq!(
            *doc.root().get_one("a").unwrap().value().unwrap(),
            Scalar::Str("0o17".to_string())
        );
    }

    #[test]
    fn reads_legacy_sexagesimal_int_forms() {
        // issue #87: live-confirmed against PyYAML/omnist -- `12:00:00`
        // resolves via the legacy YAML-1.1 sexagesimal integer form
        // (base-60 digit groups) to the plain integer 43200, not a string.
        let doc =
            read_yaml("a: 12:00:00\nb: 1:20\nc: 1:2:3\nd: -1:20\ne: +1:20\nf: 123:45\ng: 1_2:30\n")
                .unwrap();
        let root = doc.root();
        assert_eq!(
            *root.get_one("a").unwrap().value().unwrap(),
            Scalar::Int((43200).into())
        );
        assert_eq!(
            *root.get_one("b").unwrap().value().unwrap(),
            Scalar::Int((80).into())
        );
        assert_eq!(
            *root.get_one("c").unwrap().value().unwrap(),
            Scalar::Int((3723).into())
        );
        assert_eq!(
            *root.get_one("d").unwrap().value().unwrap(),
            Scalar::Int((-80).into())
        );
        assert_eq!(
            *root.get_one("e").unwrap().value().unwrap(),
            Scalar::Int((80).into())
        );
        assert_eq!(
            *root.get_one("f").unwrap().value().unwrap(),
            Scalar::Int((7425).into())
        );
        assert_eq!(
            *root.get_one("g").unwrap().value().unwrap(),
            Scalar::Int((750).into())
        );
    }

    #[test]
    fn sexagesimal_first_group_over_i64_range_parses() {
        // Issue #104: `Scalar::Int` is arbitrary-precision (`BigInt`), so
        // a first digit group beyond `i64`'s ~19-digit range is no longer
        // a parse error -- `parse_sexagesimal_int`'s fold just produces a
        // real, correctly-computed `BigInt` value.
        let text = format!("a: {}:0\n", "9".repeat(20));
        let doc = read_yaml(&text).unwrap();
        let value = doc.root().child("a").unwrap().value().unwrap();
        assert_eq!(
            value,
            &Scalar::Int(num_bigint::BigInt::parse_bytes(b"5999999999999999999940", 10).unwrap())
        );
    }

    #[test]
    fn sexagesimal_fold_overflow_across_many_in_range_groups_parses() {
        // Every individual group here is a legal 0-59 sexagesimal digit;
        // this exercises the *fold* itself accumulating well past `i64`
        // range across many groups -- issue #104 means the fold no longer
        // overflows, it just keeps growing the `BigInt`.
        let text = format!("a: 1{}\n", ":59".repeat(15));
        let doc = read_yaml(&text).unwrap();
        let value = doc.root().child("a").unwrap().value().unwrap();
        assert_eq!(
            value,
            &Scalar::Int(
                num_bigint::BigInt::parse_bytes(b"940369969151999999999999999", 10).unwrap()
            )
        );
    }

    #[test]
    fn sexagesimal_fold_still_rejects_past_the_digit_cap() {
        // The digit-cap check this migration *added* to the fold (issue
        // #104 -- replacing the `i64` overflow that used to bound this
        // incidentally) -- enough groups to push the folded result's
        // decimal digit count past MAX_INT_DIGITS must still be rejected,
        // not silently accepted now that raw fold overflow no longer does
        // that job.
        let text = format!("a: 1{}\n", ":59".repeat(2500));
        let err = read_yaml(&text).unwrap_err();
        assert!(
            matches!(&err, OmnistError::Document(e)
                if e.code.as_deref() == Some("document.limit.int-digits")
                    && e.path == "$.a"
                    && e.message.contains("4300-digit")),
            "got {err:?}"
        );
    }

    #[test]
    fn sexagesimal_shape_with_leading_zero_or_out_of_range_group_stays_a_string() {
        // Live-confirmed against PyYAML: the first digit group must NOT
        // have a leading zero, and every subsequent `:NN` group must be
        // 0-59 -- otherwise the whole thing stays a plain string, it does
        // not partially resolve.
        let doc = read_yaml("a: 0:0:1\nb: 1:60\nc: 1:600\nd: 01:20\n").unwrap();
        let root = doc.root();
        assert_eq!(
            *root.get_one("a").unwrap().value().unwrap(),
            Scalar::Str("0:0:1".to_string())
        );
        assert_eq!(
            *root.get_one("b").unwrap().value().unwrap(),
            Scalar::Str("1:60".to_string())
        );
        assert_eq!(
            *root.get_one("c").unwrap().value().unwrap(),
            Scalar::Str("1:600".to_string())
        );
        assert_eq!(
            *root.get_one("d").unwrap().value().unwrap(),
            Scalar::Str("01:20".to_string())
        );
    }

    #[test]
    fn reads_float_and_inf_and_nan_tokens() {
        let doc = read_yaml("a: 1.5\nb: .inf\nc: -.inf\nd: .nan\ne: 1.0e+3\n").unwrap();
        let root = doc.root();
        assert_eq!(
            *root.get_one("a").unwrap().value().unwrap(),
            Scalar::Float(1.5)
        );
        assert_eq!(
            *root.get_one("b").unwrap().value().unwrap(),
            Scalar::Float(f64::INFINITY)
        );
        assert_eq!(
            *root.get_one("c").unwrap().value().unwrap(),
            Scalar::Float(f64::NEG_INFINITY)
        );
        assert!(
            matches!(root.get_one("d").unwrap().value().unwrap(), Scalar::Float(x) if x.is_nan())
        );
        assert_eq!(
            *root.get_one("e").unwrap().value().unwrap(),
            Scalar::Float(1000.0)
        );
    }

    #[test]
    fn a_bare_exponent_without_a_decimal_point_is_not_float_shaped_and_stays_a_string() {
        // Live-confirmed against PyYAML: its float resolver requires a
        // literal `.`, and a mandatory sign on the exponent when present --
        // "1e3" and "1.0e3" both stay plain strings.
        let doc = read_yaml("a: 1e3\nb: 1.0e3\n").unwrap();
        let root = doc.root();
        assert_eq!(
            *root.get_one("a").unwrap().value().unwrap(),
            Scalar::Str("1e3".to_string())
        );
        assert_eq!(
            *root.get_one("b").unwrap().value().unwrap(),
            Scalar::Str("1.0e3".to_string())
        );
    }

    #[test]
    fn reads_bare_date_as_iso_string() {
        let doc = read_yaml("a: 2024-01-15\n").unwrap();
        assert_eq!(
            *doc.root().get_one("a").unwrap().value().unwrap(),
            Scalar::Date("2024-01-15".to_string())
        );
    }

    #[test]
    fn genuine_date_and_datetime_values_write_bare_and_a_time_value_writes_quoted() {
        // `Date`/`Datetime` (issue #105) write as YAML's own bare
        // timestamp literal, since `write_scalar_value` trusts them as
        // already-canonical (see that function's doc comment); `Time` has
        // no native YAML spelling at all, so it always stays quoted.
        let v = obj(vec![
            ("d", Value::Date("2024-01-15".to_string())),
            ("dt", Value::Datetime("2024-01-15T12:00:00".to_string())),
            ("t", Value::Time("12:00:00".to_string())),
        ]);
        let doc = doc_of(v);
        let text = write_yaml(&doc, false, None).unwrap();
        assert!(text.contains("d: 2024-01-15\n"));
        assert!(text.contains("dt: 2024-01-15T12:00:00\n"));
        assert!(text.contains("t: \"12:00:00\""));
    }

    #[test]
    fn reads_loose_timestamp_and_normalizes_to_canonical_iso() {
        // Space-separated, single-digit month/day/hour, short fraction,
        // bare `Z` -- all normalized the way `datetime.isoformat()` would.
        // (Minute/second must still be exactly two digits -- that's PyYAML's
        // own `tag:yaml.org,2002:timestamp` regex, not a relaxation this port
        // invented; live-confirmed via the module doc comment's approach.)
        let doc = read_yaml("a: 2001-2-3 4:05:06.7 Z\n").unwrap();
        assert_eq!(
            *doc.root().get_one("a").unwrap().value().unwrap(),
            Scalar::Datetime("2001-02-03T04:05:06.700000+00:00".to_string())
        );
    }

    #[test]
    fn a_single_digit_minute_or_second_is_not_timestamp_shaped_and_stays_a_string() {
        // PyYAML's own timestamp resolver requires an exactly-2-digit
        // minute/second even though hour/month/day may be 1 or 2 digits --
        // confirmed by this port's `normalize_timestamp` regex (mirroring
        // PyYAML's), not a looser rule this port invented.
        let doc = read_yaml("a: 2001-2-3 4:5:6\n").unwrap();
        assert_eq!(
            *doc.root().get_one("a").unwrap().value().unwrap(),
            Scalar::Str("2001-2-3 4:5:6".to_string())
        );
    }

    #[test]
    fn reads_datetime_with_no_timezone_at_all() {
        // A full date+time with no `Z` and no explicit offset -- exercises
        // `normalize_timestamp`'s "no timezone information at all" arm,
        // distinct from both the explicit-offset and bare-`Z` cases.
        let doc = read_yaml("a: 2024-01-15T12:30:00\n").unwrap();
        assert_eq!(
            *doc.root().get_one("a").unwrap().value().unwrap(),
            Scalar::Datetime("2024-01-15T12:30:00".to_string())
        );
    }

    #[test]
    fn reads_timestamp_with_explicit_offset() {
        let doc = read_yaml("a: 2001-12-14T21:59:43.10-05:00\n").unwrap();
        assert_eq!(
            *doc.root().get_one("a").unwrap().value().unwrap(),
            Scalar::Datetime("2001-12-14T21:59:43.100000-05:00".to_string())
        );
    }

    #[test]
    fn a_string_that_merely_looks_like_a_short_date_but_isnt_shaped_right_stays_a_string() {
        let doc = read_yaml("a: 2024-1\n").unwrap();
        assert_eq!(
            *doc.root().get_one("a").unwrap().value().unwrap(),
            Scalar::Str("2024-1".to_string())
        );
    }

    // ---------------------------------------------------------- reader: structure

    #[test]
    fn reads_nested_mapping_and_sequence() {
        let doc = read_yaml("a:\n  b:\n    c: 1\nm:\n  - 1\n  - 2\n  - 3\n").unwrap();
        let root = doc.root();
        let a = root.get_one("a").unwrap();
        let b = a.get_one("b").unwrap();
        assert_eq!(
            *b.get_one("c").unwrap().value().unwrap(),
            Scalar::Int((1).into())
        );
        let ms = root.get("m");
        assert_eq!(ms.len(), 3);
        assert_eq!(*ms[2].value().unwrap(), Scalar::Int((3).into()));
    }

    #[test]
    fn reads_flow_style_mapping_and_sequence() {
        let doc = read_yaml("a: {b: 1, c: 2}\nm: [1, 2, 3]\n").unwrap();
        let root = doc.root();
        let a = root.get_one("a").unwrap();
        assert_eq!(
            *a.get_one("b").unwrap().value().unwrap(),
            Scalar::Int((1).into())
        );
        assert_eq!(root.get("m").len(), 3);
    }

    #[test]
    fn bare_top_level_sequence_is_a_document_error_not_a_parse_error() {
        let err = read_yaml("- 1\n- 2\n").unwrap_err();
        assert!(matches!(err, OmnistError::Document(_)), "got {err:?}");
    }

    #[test]
    fn sequence_of_sequences_is_a_document_error() {
        let err = read_yaml("m:\n  - [1, 2]\n").unwrap_err();
        assert!(matches!(err, OmnistError::Document(_)), "got {err:?}");
    }

    #[test]
    fn empty_input_reads_as_a_null_document() {
        let doc = read_yaml("").unwrap();
        assert_eq!(*doc.root().value().unwrap(), Scalar::Null);
    }

    #[test]
    fn explicit_empty_document_marker_reads_as_a_null_document() {
        // An explicit `---` document-start marker with no content produces a
        // `DocumentEnd` event with nothing ever pushed onto the doc stack --
        // a different code path than a wholly empty input (which never
        // produces a `DocumentStart`/`DocumentEnd` pair at all).
        let doc = read_yaml("---\n").unwrap();
        assert_eq!(*doc.root().value().unwrap(), Scalar::Null);
    }

    #[test]
    fn a_repeated_mapping_key_is_a_syntax_error() {
        // C-12: block, flow, nested, in a sequence element, and quoted.
        for text in [
            "a: 1\nb: 2\na: 3\n",
            "{a: 1, a: 2}\n",
            "o:\n  k: 1\n  k: 2\n",
            "m:\n  - {a: 1, a: 2}\n",
            "a: 1\n\"a\": 2\n",
            "a: 1\na: [2, 3]\n",
            "p: &p {x: 1}\nq: {a: 1, <<: *p, a: 2}\n",
        ] {
            let e = read_yaml(text).unwrap_err();
            assert!(
                matches!(&e, OmnistError::Parse(p)
                    if p.code == "parse.codec-syntax" && p.message.contains("duplicate mapping key")),
                "{text:?}: {e:?}"
            );
        }
    }

    #[test]
    fn the_same_key_in_two_mappings_or_differing_in_case_is_not_a_repeat() {
        assert!(read_yaml("x: {a: 1}\ny: {a: 2}\n").is_ok());
        assert!(read_yaml("a: 1\nA: 2\n").is_ok());
        // A key a merge supplies is overridden by the one written, not a repeat.
        let doc = read_yaml("p: &p {a: 1, b: 2}\nq: {<<: *p, a: 9}\n").unwrap();
        let q = doc.root().get_one("q").unwrap();
        assert_eq!(
            *q.get_one("a").unwrap().value().unwrap(),
            Scalar::Int(9.into())
        );
        assert_eq!(
            *q.get_one("b").unwrap().value().unwrap(),
            Scalar::Int(2.into())
        );
    }

    #[test]
    fn omap_pairs_and_set_are_refused_with_tag_forbidden_at_the_root() {
        // C-13: whatever the node kind or position, path `$`, not a syntax error.
        for text in [
            "t: !!omap [{k: 1}, {j: 2}]\n",
            "t: !!pairs [{k: 1}, {k: 2}]\n",
            "t: !!set {x, y}\n",
            "t: !!set\n  ? x\n  ? y\n",
            "t: !!omap []\n",
            "!!omap [{k: 1}]\n",
            "a:\n  b: !!set {x}\n",
            "t: !!set x\n",
        ] {
            let e = read_yaml(text).unwrap_err();
            assert!(
                matches!(&e, OmnistError::Document(d)
                    if d.code.as_deref() == Some("format.tag-forbidden")
                        && d.path == "$"
                        && d.message.contains("!!")),
                "{text:?}: {e:?}"
            );
        }
        // A plain sequence of single-entry mappings is just a sequence.
        assert!(read_yaml("t:\n  - {k: 1}\n  - {j: 2}\n").is_ok());
    }

    #[test]
    fn a_merge_tagged_merge_key_merges_and_a_str_tagged_one_does_not() {
        // D-27.
        let doc = read_yaml("p: &p {x: 1}\nq: {!!merge <<: *p, y: 2}\n").unwrap();
        let q = doc.root().get_one("q").unwrap();
        assert_eq!(q.labels(), vec!["x".to_string(), "y".to_string()]);
        let doc = read_yaml("p: &p {x: 1}\nr: &r {y: 2}\nq: {!!merge <<: [*p, *r]}\n").unwrap();
        let q = doc.root().get_one("q").unwrap();
        assert_eq!(q.labels(), vec!["x".to_string(), "y".to_string()]);
        let doc = read_yaml("q: {!!str <<: 2}\n").unwrap();
        let q = doc.root().get_one("q").unwrap();
        assert_eq!(q.labels(), vec!["<<".to_string()]);
        // A merge-tagged merge key is held to the same shape rule, and
        // `!!merge` on anything but `<<` is still not a supported tag.
        for text in ["q: {!!merge <<: 1}\n", "q: !!merge x\n"] {
            let e = read_yaml(text).unwrap_err();
            assert!(
                matches!(&e, OmnistError::Parse(p) if p.code == "parse.codec-syntax"),
                "{text:?}: {e:?}"
            );
        }
    }

    #[test]
    fn invalid_yaml_syntax_is_a_parse_error() {
        let err = read_yaml("a: [1, 2\n").unwrap_err();
        assert!(matches!(err, OmnistError::Parse(_)), "got {err:?}");
    }

    #[test]
    fn multiple_documents_is_a_parse_error() {
        let err = read_yaml("a: 1\n---\nb: 2\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("single document")),
            "got {err:?}"
        );
    }

    #[test]
    fn nesting_far_past_max_depth_trips_the_event_stream_guard_not_the_stack() {
        // Deep enough that `Builder::too_deep` -- checked in the event
        // stream, before yaml-rust2's own recursive `load` would overflow
        // the stack -- fires well before any Document is even built: both
        // block sequences and block mappings, since each has its own
        // `SequenceStart`/`MappingStart` arm.
        let mut seq = String::new();
        for _ in 0..5000 {
            seq.push_str("- ");
        }
        let err = read_yaml(&seq).unwrap_err();
        assert!(matches!(err, OmnistError::Document(_)), "got {err:?}");

        let mut map = String::new();
        for i in 0..5000 {
            map.push_str(&"  ".repeat(i));
            map.push_str("a:\n");
        }
        let err = read_yaml(&map).unwrap_err();
        assert!(matches!(err, OmnistError::Document(_)), "got {err:?}");
    }

    #[test]
    fn nesting_past_max_depth_is_a_document_error() {
        // Genuine indentation-nested mappings, not a flat run of overwritten
        // "a:" keys -- each level indented two spaces deeper than the last.
        let mut text = String::new();
        for i in 0..=crate::document::MAX_DEPTH {
            text.push_str(&"  ".repeat(i));
            text.push_str("a:\n");
        }
        let err = read_yaml(&text).unwrap_err();
        assert!(matches!(err, OmnistError::Document(_)), "got {err:?}");
    }

    #[test]
    fn integer_literal_over_digit_cap_is_rejected() {
        let text = format!("a: {}\n", "9".repeat(MAX_INT_DIGITS + 1));
        let err = read_yaml(&text).unwrap_err();
        assert!(
            matches!(&err, OmnistError::Document(e)
                if e.code.as_deref() == Some("document.limit.int-digits")
                    && e.path == "$.a"
                    && e.message.contains("4300-digit")),
            "got {err:?}"
        );
    }

    /// `(code, path)` of the Document error `read_yaml` raises for `text`.
    fn doc_diag(text: &str) -> (String, String) {
        use OmnistError as E;
        let err = read_yaml(text).unwrap_err();
        let E::Document(e) = err else { panic!() };
        (e.code.unwrap_or_default(), e.path)
    }

    fn unlabeled(path: &str) -> (String, String) {
        ("document.unlabeled-element".to_string(), path.to_string())
    }

    #[test]
    fn a_non_string_key_in_the_top_level_mapping_is_at_the_root() {
        // Pinned by `formats-yaml/sharp-edges/norway-problem-...`.
        assert_eq!(doc_diag("on: 1\n"), unlabeled("$"));
        assert_eq!(doc_diag("a: 1\n1: x\n"), unlabeled("$"));
        assert_eq!(doc_diag("~: x\n"), unlabeled("$"));
    }

    #[test]
    fn a_non_string_key_in_a_nested_mapping_carries_that_mapping_s_path() {
        assert_eq!(doc_diag("a: {on: 1}\n"), unlabeled("$.a"));
        assert_eq!(doc_diag("a:\n  on: 1\n"), unlabeled("$.a"));
        assert_eq!(
            doc_diag("a:\n  b:\n    c:\n      1: x\n"),
            unlabeled("$.a.b.c")
        );
        assert_eq!(doc_diag("x: 1\na:\n  y: 2\n  no: 3\n"), unlabeled("$.a"));
        // A label that needs quoting in a Document path (E-36), and one that
        // does not.
        assert_eq!(doc_diag("\"a.b\": {on: 1}\n"), unlabeled("$[\"a.b\"]"));
        assert_eq!(doc_diag("\"a b\": {on: 1}\n"), unlabeled("$.a b"));
    }

    #[test]
    fn a_non_string_key_in_a_mapping_inside_a_sequence_follows_e10() {
        // E-10: the index is present when the label occurs more than once in
        // its node, absent when it occurs exactly once.
        assert_eq!(doc_diag("a: [{on: 1}]\n"), unlabeled("$.a"));
        assert_eq!(doc_diag("a: [{x: 1}, {on: 1}]\n"), unlabeled("$.a[1]"));
        assert_eq!(doc_diag("a: [{on: 1}, {x: 1}]\n"), unlabeled("$.a[0]"));
        assert_eq!(
            doc_diag("a: [{x: 1}, {y: 2}, {z: 3}, {on: 1}]\n"),
            unlabeled("$.a[3]")
        );
        // Deeper: a sequence under a nested key, then a mapping inside it.
        assert_eq!(
            doc_diag("a:\n  b:\n    - {x: 1}\n    - {c: {on: 1}}\n"),
            unlabeled("$.a.b[1].c")
        );
    }

    #[test]
    fn a_non_string_key_reached_again_through_a_merge_is_reported_where_first_written() {
        // The anchored mapping is itself a node of the document, so it is the
        // first place the key is met; the merge into `m` does not move it.
        assert_eq!(
            doc_diag("base: &b {on: 1}\nm:\n  <<: *b\n"),
            unlabeled("$.base")
        );
    }

    #[test]
    fn an_over_long_integer_key_in_a_nested_mapping_carries_the_mapping_s_path() {
        let options =
            YamlReadOptions::default().with_limits(Limits::default().with_max_int_digits(3));
        let err = read_yaml_with("a: {b: {1000: x}}\n", &options).unwrap_err();
        assert!(
            matches!(&err, OmnistError::Document(e)
                if e.code.as_deref() == Some("document.limit.int-digits") && e.path == "$.a.b"),
            "got {err:?}"
        );
    }

    #[test]
    fn an_over_limit_integer_in_a_dropped_merge_entry_is_still_refused() {
        // D-13: a merged value the mapping's own key overrides (or an earlier
        // merge source shadows) never reaches the Document, but the integer
        // limit applies to the input, so the document is refused all the same.
        let options =
            YamlReadOptions::default().with_limits(Limits::default().with_max_int_digits(3));
        for text in [
            "m: {<<: {a: 1000}, a: 1}
",
            "m: {a: 1, <<: {a: 1000}}
",
            "m: {<<: [{a: 1}, {a: 1000}]}
",
            "m: {<<: {a: [1, {z: 1000}]}, a: 1}
",
            "m: {<<: {<<: {a: 1000}, a: 1}}
",
            "m: {<<: {<<: {a: 1000}}, a: 1}
",
        ] {
            let err = read_yaml_with(text, &options).unwrap_err();
            assert!(
                matches!(&err, OmnistError::Document(e)
                    if e.code.as_deref() == Some("document.limit.int-digits")),
                "{text:?} gave {err:?}"
            );
        }
        // At the limit, and when nothing is dropped, nothing changes.
        assert!(
            read_yaml_with(
                "m: {<<: {a: 999}, a: 1}
",
                &options
            )
            .is_ok()
        );
    }

    #[test]
    fn an_over_long_integer_used_as_a_key_is_refused_by_the_digit_limit() {
        // Not as a missing label: the digit limit is what refuses it.
        let options =
            YamlReadOptions::default().with_limits(Limits::default().with_max_int_digits(3));
        let err = read_yaml_with("1000: x\n", &options).unwrap_err();
        assert!(
            matches!(&err, OmnistError::Document(e)
                if e.code.as_deref() == Some("document.limit.int-digits") && e.path == "$"),
            "got {err:?}"
        );
        // At the limit it is an ordinary non-string key.
        let err = read_yaml_with("999: x\n", &options).unwrap_err();
        assert!(
            matches!(&err, OmnistError::Document(e)
                if e.code.as_deref() == Some("document.unlabeled-element")),
            "got {err:?}"
        );
    }

    #[test]
    fn i64_min_round_trips_through_yaml() {
        // Regression test for issue #26's fuzz harness finding: the
        // previous `parse_int_literal` stripped the sign, then parsed the
        // *positive* magnitude as `i64`, which overflows for `i64::MIN`
        // (whose magnitude, 9223372036854775808, is one past `i64::MAX`)
        // even though the signed value itself is representable.
        let doc = read_yaml("a: -9223372036854775808\n").unwrap();
        assert_eq!(
            *doc.root().get_one("a").unwrap().value().unwrap(),
            Scalar::Int((i64::MIN).into())
        );
    }

    #[test]
    fn positive_integer_one_past_i64_max_parses() {
        // Issue #104: no more `i64` ceiling -- one past `i64::MAX` is now
        // just a real, correctly-parsed value.
        let doc = read_yaml("a: 9223372036854775808\n").unwrap();
        let value = doc.root().child("a").unwrap().value().unwrap();
        assert_eq!(value, &Scalar::Int(num_bigint::BigInt::from(i64::MAX) + 1));
    }

    #[test]
    fn negative_integer_one_past_i64_min_parses() {
        // Issue #104: same, on the negative side -- was the `checked_neg`
        // overflow arm, now just a real value one past `i64::MIN`.
        let doc = read_yaml("a: -9223372036854775809\n").unwrap();
        let value = doc.root().child("a").unwrap().value().unwrap();
        assert_eq!(value, &Scalar::Int(num_bigint::BigInt::from(i64::MIN) - 1));
    }

    #[test]
    fn integer_literal_over_i64_range_parses() {
        let text = format!("a: {}\n", "9".repeat(20));
        let doc = read_yaml(&text).unwrap();
        let value = doc.root().child("a").unwrap().value().unwrap();
        assert_eq!(
            value,
            &Scalar::Int(num_bigint::BigInt::parse_bytes(b"99999999999999999999", 10).unwrap())
        );
    }

    // ---------------------------------------------------------- reader: anchors/aliases

    #[test]
    fn reads_anchor_and_alias_as_a_deep_copy() {
        let doc = read_yaml("a: &x [1, 2, 3]\nb: *x\n").unwrap();
        let root = doc.root();
        assert_eq!(root.get("a").len(), 3);
        assert_eq!(root.get("b").len(), 3);
        assert_eq!(*root.get("b")[1].value().unwrap(), Scalar::Int((2).into()));
    }

    #[test]
    fn unknown_alias_is_a_parse_error() {
        let err = read_yaml("a: *nope\n").unwrap_err();
        assert!(matches!(err, OmnistError::Parse(_)), "got {err:?}");
    }

    /// Issue #42: builds the classic "billion laughs" pattern -- each
    /// generation's anchor references the previous generation's alias
    /// twice, so after `n` generations there are `2^n` leaf scalars
    /// materialized from a source document only `n` lines long and only
    /// `n` levels deep (well under `crate::document::MAX_DEPTH == 200`).
    /// 24 generations reaches `2^24` (16,777,216) nodes -- comfortably over
    /// `MAX_MATERIALIZED_NODES` (1,000,000 containers) so the guard trips partway
    /// through, and small enough that even the *unguarded* clone-everything
    /// behavior finishes (rather than hanging or exhausting memory) within
    /// this test's patience, which is what let this be captured red before
    /// the fix: before the fix this took over 4 seconds and allocated a
    /// many-million-node tree; after the fix it is rejected as a clean
    /// `ParseError` in well under a second (a debug build still has to
    /// walk/clone the last, still-under-the-ceiling generation, so this
    /// is not sub-millisecond, but it is bounded by the ceiling rather
    /// than by the attack's exponent), well before the full tree is
    /// ever materialized.
    fn billion_laughs_yaml(generations: usize) -> String {
        let mut out = String::new();
        out.push_str("a0: &a0 [x, x]\n");
        for i in 1..generations {
            out.push_str(&format!("a{i}: &a{i} [*a{prev}, *a{prev}]\n", prev = i - 1));
        }
        out
    }

    #[test]
    fn billion_laughs_alias_amplification_is_rejected_fast_issue_42() {
        let text = billion_laughs_yaml(24);
        // A source document of only 24 short lines.
        assert!(text.len() < 1000, "source text should be tiny: {text:?}");

        let start = std::time::Instant::now();
        let err = read_yaml(&text).unwrap_err();
        let elapsed = start.elapsed();

        // Since D-18/D-19 the bomb is refused by the alias expansion check
        // before any expansion is built, with the expansion code (the node cap
        // is the backstop for what passes that check; see `alias_tests`).
        assert!(
            matches!(&err, OmnistError::Document(e)
                if e.code.as_deref() == Some("document.limit.alias-expansion")
                    && e.path == "$"),
            "expected the alias expansion rejection, got {err:?}"
        );
        assert!(
            elapsed < std::time::Duration::from_secs(5),
            "fix should reject the bomb almost immediately, took {elapsed:?}"
        );
    }

    #[test]
    fn moderate_legitimate_nested_alias_reuse_still_works() {
        // A handful of anchors reused a few times each -- ordinary,
        // legitimate YAML anchor/alias usage (e.g. shared defaults), well
        // within any reasonable node-count limit. Must not be affected by
        // the issue #42 fix.
        let doc = read_yaml(
            "base: &base\n  x: 1\n  y: 2\na: *base\nb: *base\nc: *base\nlist: &list [1, 2, 3]\nd: *list\ne: *list\n",
        )
        .unwrap();
        let root = doc.root();
        for label in ["a", "b", "c"] {
            let node = root.get_one(label).unwrap();
            assert_eq!(
                *node.get_one("x").unwrap().value().unwrap(),
                Scalar::Int((1).into())
            );
            assert_eq!(
                *node.get_one("y").unwrap().value().unwrap(),
                Scalar::Int((2).into())
            );
        }
        for label in ["d", "e"] {
            assert_eq!(root.get(label).len(), 3);
        }
    }

    // ---------------------------------------------------------- reader: merge keys

    #[test]
    fn merge_key_from_a_mapping_merges_with_local_keys_winning() {
        let doc =
            read_yaml("base: &b\n  x: 1\n  y: 2\nchild:\n  <<: *b\n  y: 20\n  z: 3\n").unwrap();
        let child = doc.root().get_one("child").unwrap();
        assert_eq!(
            *child.get_one("x").unwrap().value().unwrap(),
            Scalar::Int((1).into())
        );
        assert_eq!(
            *child.get_one("y").unwrap().value().unwrap(),
            Scalar::Int((20).into()),
            "an explicit local key beats the merged-in value"
        );
        assert_eq!(
            *child.get_one("z").unwrap().value().unwrap(),
            Scalar::Int((3).into())
        );
    }

    #[test]
    fn merge_key_from_a_sequence_of_mappings_merges_each_in_order() {
        // First-listed source wins a collision between the sources
        // themselves (YAML merge spec), matching PyYAML's own behavior.
        let doc =
            read_yaml("a: &a\n  x: 1\nb: &b\n  x: 2\n  y: 3\nchild:\n  <<: [*a, *b]\n").unwrap();
        let child = doc.root().get_one("child").unwrap();
        assert_eq!(
            *child.get_one("x").unwrap().value().unwrap(),
            Scalar::Int((1).into())
        );
        assert_eq!(
            *child.get_one("y").unwrap().value().unwrap(),
            Scalar::Int((3).into())
        );
    }

    #[test]
    fn quoted_double_angle_bracket_key_is_a_literal_string_not_a_merge() {
        let doc = read_yaml("a:\n  \"<<\": 1\n").unwrap();
        let a = doc.root().get_one("a").unwrap();
        assert_eq!(
            *a.get_one("<<").unwrap().value().unwrap(),
            Scalar::Int((1).into())
        );
    }

    // omnist-ts#46: a fuzz suite intermittently found a ParseError with a
    // non-map merge source -- pinned here as an explicit regression: merging
    // from a scalar must fail predictably (a clean ParseError), never panic
    // or behave inconsistently.
    #[test]
    fn merge_key_from_a_non_map_scalar_source_is_a_clean_parse_error_omnist_ts_46() {
        let err = read_yaml("child:\n  <<: 5\n  y: 2\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("merge key")),
            "got {err:?}"
        );
    }

    #[test]
    fn merge_key_from_a_sequence_containing_a_scalar_is_a_clean_parse_error() {
        let err = read_yaml("child:\n  <<: [1, 2]\n").unwrap_err();
        assert!(matches!(err, OmnistError::Parse(_)), "got {err:?}");
    }

    #[test]
    fn merge_source_with_a_non_scalar_key_is_a_clean_parse_error() {
        // Exercises the (structurally rare) branch where a merge source's
        // own key isn't a plain scalar (YAML's complex-mapping-key syntax) --
        // `scalar_key_text` returns `None` for it during merge de-duplication,
        // and the final scalar-key check in `raw_to_value` still catches it.
        let err = read_yaml("base: &b\n  ? [1, 2]\n  : 3\nchild:\n  <<: *b\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("mapping key must be a scalar")),
            "got {err:?}"
        );
    }

    #[test]
    fn merge_key_from_an_alias_to_a_scalar_is_a_clean_parse_error() {
        let err = read_yaml("base: &b 5\nchild:\n  <<: *b\n").unwrap_err();
        assert!(matches!(err, OmnistError::Parse(_)), "got {err:?}");
    }

    // ---------------------------------------------------------- reader: explicit tags

    #[test]
    fn explicit_tags_construct_the_named_type_regardless_of_spelling() {
        let doc = read_yaml("a: !!str yes\nb: !!int \"5\"\nc: !!bool \"true\"\n").unwrap();
        let root = doc.root();
        assert_eq!(
            *root.get_one("a").unwrap().value().unwrap(),
            Scalar::Str("yes".to_string())
        );
        assert_eq!(
            *root.get_one("b").unwrap().value().unwrap(),
            Scalar::Int((5).into())
        );
        assert_eq!(
            *root.get_one("c").unwrap().value().unwrap(),
            Scalar::Bool(true)
        );
    }

    #[test]
    fn unsupported_explicit_tag_is_a_parse_error() {
        let err = read_yaml("a: !!binary \"x\"\n").unwrap_err();
        assert!(matches!(err, OmnistError::Parse(_)), "got {err:?}");
    }

    #[test]
    fn explicit_bool_tag_accepts_the_full_yaml_1_1_spelling_set_not_just_true_false() {
        // Live-confirmed against PyYAML (see module doc comment on
        // `explicit_tag_to_value`'s "bool" arm): `!!bool` uses the exact same
        // `bool_values` lookup regardless of implicit vs. explicit tagging,
        // so "yes"/"On"/"OFF" all construct via the explicit tag too.
        let doc = read_yaml("a: !!bool \"yes\"\nb: !!bool \"On\"\nc: !!bool \"OFF\"\n").unwrap();
        let root = doc.root();
        assert_eq!(
            *root.get_one("a").unwrap().value().unwrap(),
            Scalar::Bool(true)
        );
        assert_eq!(
            *root.get_one("b").unwrap().value().unwrap(),
            Scalar::Bool(true)
        );
        assert_eq!(
            *root.get_one("c").unwrap().value().unwrap(),
            Scalar::Bool(false)
        );
    }

    #[test]
    fn invalid_explicit_bool_spelling_is_a_parse_error() {
        let err = read_yaml("a: !!bool \"nonsense\"\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("!!bool")),
            "got {err:?}"
        );
    }

    #[test]
    fn bare_y_or_n_is_not_a_valid_explicit_bool_spelling() {
        // Live-confirmed: PyYAML's `bool_values` dict has no "y"/"n" keys
        // even though the plain-scalar implicit resolver never even tags
        // these as bool in the first place -- a bare "y"/"n" reaches this
        // arm only via an explicit `!!bool` tag, and PyYAML raises
        // (`KeyError` -> `ConstructorError`) rather than accepting it.
        let err = read_yaml("a: !!bool \"y\"\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("!!bool")),
            "got {err:?}"
        );
    }

    #[test]
    fn bare_on_key_resolves_to_boolean_and_is_rejected_norway_problem() {
        // issue #88: YAML 1.1's core schema resolves a bare `on:` key to
        // the boolean `true`, same as it would as a value -- since a label
        // MUST be a string, this must be rejected as a DocumentError, not
        // silently kept as the literal string "on".
        let err = read_yaml("on:\n  push: true\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Document(e) if e.path == "$"),
            "got {err:?}"
        );
    }

    #[test]
    fn other_implicit_bool_and_null_key_spellings_are_also_rejected() {
        for key in ["off", "yes", "no", "Off", "YES", "~", "null", "true"] {
            let text = format!("{key}:\n  push: true\n");
            let err = read_yaml(&text).unwrap_err();
            assert!(
                matches!(&err, OmnistError::Document(_)),
                "key {key:?} got {err:?}"
            );
        }
    }

    #[test]
    fn bare_y_or_n_key_is_not_a_bool_and_stays_a_string_label() {
        // Live-confirmed against PyYAML/omnist: unlike "yes"/"no", bare
        // "y"/"n" are NOT booleans under the implicit resolver, so these
        // stay ordinary string keys and parse successfully.
        let doc = read_yaml("y:\n  push: true\n").unwrap();
        assert!(doc.root().get_one("y").is_ok());
        let doc = read_yaml("n:\n  push: true\n").unwrap();
        assert!(doc.root().get_one("n").is_ok());
    }

    #[test]
    fn sexagesimal_looking_key_also_resolves_and_is_rejected() {
        // Interaction check between #87 and #88: a key shaped like a
        // sexagesimal int must go through the same resolver and be
        // rejected as a non-string label, consistent with the bool case.
        let err = read_yaml("12:00:00:\n  push: true\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Document(e) if e.path == "$"),
            "got {err:?}"
        );
    }

    #[test]
    fn describe_non_string_key_renders_pythonic_spellings() {
        assert_eq!(describe_non_string_key(&Value::Bool(true)), "True");
        assert_eq!(describe_non_string_key(&Value::Bool(false)), "False");
        assert_eq!(describe_non_string_key(&Value::Null), "None");
        assert_eq!(
            describe_non_string_key(&Value::Int((43200).into())),
            "43200"
        );
        assert_eq!(describe_non_string_key(&Value::Float(1.5)), "1.5");
        // Whole-number floats must keep the `.0` (Python's `repr(1.0)` is
        // `'1.0'`, not `'1'` -- `f64::to_string()` alone drops it).
        assert_eq!(describe_non_string_key(&Value::Float(1.0)), "1.0");
        assert_eq!(describe_non_string_key(&Value::Float(-2.0)), "-2.0");
        // Structurally unreachable via the real call site (see the
        // function's doc comment), exercised directly here so the wildcard
        // fallback arm is real, tested code, not a dead branch.
        assert_eq!(
            describe_non_string_key(&Value::Str("x".to_string())),
            "Str(\"x\")"
        );
    }

    #[test]
    fn int_and_float_shaped_mapping_keys_are_rejected_with_python_parity_messages() {
        // Direct coverage for the reviewer-flagged gap: int/float-shaped
        // (non-bool/null) keys are also generically rejected, and the
        // whole-number float case must render as Python's `1.0`, not `1`.
        let err = read_yaml("123:\n  a: 1\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Document(e) if e.path == "$" && e.message.contains("123")),
            "got {err:?}"
        );
        let err = read_yaml("1.0:\n  a: 1\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Document(e) if e.path == "$" && e.message.contains("1.0")),
            "got {err:?}"
        );
    }

    #[test]
    fn a_non_scalar_mapping_key_is_a_clean_parse_error() {
        // YAML's complex-mapping-key syntax (`? ... : ...`) allows a
        // sequence/mapping as a key -- this model's edges are always
        // string-labeled, so this is rejected with a clean ParseError.
        let err = read_yaml("? [1, 2]\n: 3\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("mapping key must be a scalar")),
            "got {err:?}"
        );
    }

    // ---------------------------------------------------------- writer

    #[test]
    fn round_trips_every_scalar_kind() {
        let v = obj(vec![
            ("null", Value::Null),
            ("bool", Value::Bool(true)),
            ("int", Value::Int((42).into())),
            ("float", Value::Float(1.5)),
            ("str", Value::Str("hi".to_string())),
        ]);
        let doc = doc_of(v);
        let text = write_yaml(&doc, false, None).unwrap();
        let back = read_yaml(&text).unwrap();
        assert!(doc.eq_doc(&back));
    }

    #[test]
    fn round_trips_integral_float_at_and_above_1e17_boundary_issue_46() {
        // Regression test for issue #46 (see json.rs's twin test for the
        // full explanation): an integral-valued float >= 1e17 used to
        // render as a bare digit run and re-read as `Scalar::Int`.
        for x in [1.0e17, 1.0e18, -1.23e17, 9.9e16_f64] {
            let doc = doc_of(obj(vec![("a", Value::Float(x))]));
            let text = write_yaml(&doc, false, None).unwrap();
            let back = read_yaml(&text).unwrap();
            assert_eq!(
                *back.root().get_one("a").unwrap().value().unwrap(),
                Scalar::Float(x),
                "x={x} text={text}"
            );
        }
    }

    #[test]
    fn round_trips_nan_and_infinity_natively_no_adjustment_needed() {
        let v = obj(vec![
            ("a", Value::Float(f64::NAN)),
            ("b", Value::Float(f64::INFINITY)),
            ("c", Value::Float(f64::NEG_INFINITY)),
        ]);
        let doc = doc_of(v);
        let mut rep = WriteReport::new();
        let text = write_yaml(&doc, false, Some(&mut rep)).unwrap();
        assert!(rep.is_empty());
        let back = read_yaml(&text).unwrap();
        assert!(
            matches!(back.root().get_one("a").unwrap().value().unwrap(), Scalar::Float(x) if x.is_nan())
        );
        assert_eq!(
            *back.root().get_one("b").unwrap().value().unwrap(),
            Scalar::Float(f64::INFINITY)
        );
        assert_eq!(
            *back.root().get_one("c").unwrap().value().unwrap(),
            Scalar::Float(f64::NEG_INFINITY)
        );
    }

    #[test]
    fn round_trips_strings_that_look_like_other_scalar_kinds() {
        let v = obj(vec![
            ("a", Value::Str("yes".to_string())),
            ("b", Value::Str("null".to_string())),
            ("c", Value::Str("123".to_string())),
            ("d", Value::Str("1.5".to_string())),
            ("e", Value::Str("".to_string())),
            ("f", Value::Str("2024-01-15".to_string())),
        ]);
        let doc = doc_of(v);
        let text = write_yaml(&doc, false, None).unwrap();
        let back = read_yaml(&text).unwrap();
        assert!(doc.eq_doc(&back), "text was:\n{text}");
    }

    #[test]
    fn round_trips_repeated_labels_as_a_yaml_sequence() {
        let doc = doc_of(obj(vec![(
            "m",
            Value::Array(vec![
                Value::Int((1).into()),
                Value::Int((2).into()),
                Value::Int((3).into()),
            ]),
        )]));
        let text = write_yaml(&doc, false, None).unwrap();
        let back = read_yaml(&text).unwrap();
        assert!(doc.eq_doc(&back));
    }

    #[test]
    fn round_trips_nested_mappings_and_sequences_of_mappings() {
        let v = obj(vec![
            (
                "a",
                obj(vec![
                    ("b", Value::Int((1).into())),
                    ("c", Value::Int((2).into())),
                ]),
            ),
            (
                "items",
                Value::Array(vec![
                    obj(vec![
                        ("x", Value::Int((1).into())),
                        ("y", Value::Int((2).into())),
                    ]),
                    obj(vec![
                        ("x", Value::Int((3).into())),
                        ("y", Value::Int((4).into())),
                    ]),
                ]),
            ),
        ]);
        let doc = doc_of(v);
        let text = write_yaml(&doc, false, None).unwrap();
        let back = read_yaml(&text).unwrap();
        assert!(doc.eq_doc(&back), "text was:\n{text}");
    }

    #[test]
    fn writes_empty_object_and_array_compactly() {
        let doc = doc_of(obj(vec![("o", Value::Object(IndexMap::new()))]));
        let text = write_yaml(&doc, false, None).unwrap();
        assert!(text.contains("o: {}"));
    }

    #[test]
    fn nel_string_triggers_a_warning_and_still_round_trips() {
        let s = format!("a{}b", '\u{0085}');
        let doc = doc_of(obj(vec![("s", Value::Str(s.clone()))]));
        let mut rep = WriteReport::new();
        let text = write_yaml(&doc, false, Some(&mut rep)).unwrap();
        assert_eq!(rep.len(), 1);
        assert_eq!(rep.adjustments()[0].code, "format.string-line-break-char");
        let back = read_yaml(&text).unwrap();
        assert_eq!(
            *back.root().get_one("s").unwrap().value().unwrap(),
            Scalar::Str(s)
        );
    }

    #[test]
    fn strict_write_with_nel_raises_and_carries_the_report() {
        let s = format!("x{}y", '\u{0085}');
        let doc = doc_of(obj(vec![("s", Value::Str(s))]));
        let err = write_yaml(&doc, true, None).unwrap_err();
        let rep = err.report().expect("strict WriteError carries a report");
        assert_eq!(rep.len(), 1);
    }

    #[test]
    fn strict_write_with_no_adjustments_succeeds() {
        let doc = doc_of(obj(vec![("a", Value::Int((1).into()))]));
        let text = write_yaml(&doc, true, None).unwrap();
        assert!(text.contains("a: 1"));
    }

    #[test]
    fn check_yaml_reports_without_producing_output() {
        let s = format!("a{}b", '\u{0085}');
        let doc = doc_of(obj(vec![("s", Value::Str(s))]));
        let rep = check_yaml(&doc);
        assert_eq!(rep.len(), 1);
        assert_eq!(rep.adjustments()[0].path, "$.s");
    }

    #[test]
    fn deeply_nested_document_write_reuses_doc_construction_depth_guard() {
        let mut v = Value::Int((0).into());
        for _ in 0..=crate::document::MAX_DEPTH {
            v = obj(vec![("a", v)]);
        }
        assert!(Doc::of(&v).is_err());
    }

    // ---------------------------------------------------------- omnist-ts#43: wide document

    // omnist-ts#43: YAML read was a ~3x-25x performance outlier vs OML/JSON on
    // wide documents. Not a hard timing assertion here (Rust is a different
    // performance regime) -- this is the *correctness*-under-scale angle:
    // a wide document reads and round-trips correctly, so a similarly bad
    // implementation (e.g. quadratic re-scanning per field) doesn't silently
    // produce wrong output even if it's slow.
    #[test]
    fn wide_document_smoke_test_reads_and_round_trips_every_field() {
        let n = 5_000;
        let mut text = String::new();
        for i in 0..n {
            text.push_str(&format!("field{i}: {i}\n"));
        }
        let doc = read_yaml(&text).unwrap();
        let root = doc.root();
        assert_eq!(root.labels().len(), n);
        for i in [0, n / 2, n - 1] {
            assert_eq!(
                *root.get_one(&format!("field{i}")).unwrap().value().unwrap(),
                Scalar::Int((i as i64).into())
            );
        }
        let out = write_yaml(&doc, false, None).unwrap();
        let back = read_yaml(&out).unwrap();
        assert!(doc.eq_doc(&back));
    }

    #[test]
    fn wide_flat_sequence_smoke_test() {
        let n = 5_000;
        let mut text = String::from("m:\n");
        for i in 0..n {
            text.push_str(&format!("  - {i}\n"));
        }
        let doc = read_yaml(&text).unwrap();
        assert_eq!(doc.root().get("m").len(), n);
    }

    // ---------------------------------------------------------- coverage: explicit tags/errors

    #[test]
    fn invalid_explicit_float_literal_is_a_parse_error() {
        let err = read_yaml("a: !!float \"not-a-float\"\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("invalid float literal")),
            "got {err:?}"
        );
    }

    #[test]
    fn explicit_float_tag_accepts_inf_and_nan_and_negative() {
        let doc = read_yaml("a: !!float \"-1.5\"\n").unwrap();
        assert_eq!(
            *doc.root().get_one("a").unwrap().value().unwrap(),
            Scalar::Float(-1.5)
        );
    }

    // ---------------------------------------------------------- coverage: timestamp edge cases

    // Live-confirmed against PyYAML (see `normalize_timestamp`'s doc
    // comment): a timestamp-*shaped* string naming a calendar/clock value
    // that doesn't exist is a clean ParseError, not a silent string
    // fallback -- `yaml.safe_load` calls `datetime.date`/`datetime.datetime`
    // construction on the captured fields, and that raises `ValueError`
    // for an out-of-range month/day/hour/minute/timezone, failing the
    // *entire document*, not just retyping this one scalar as a string.

    #[test]
    fn timestamp_with_invalid_month_is_a_parse_error() {
        let err = read_yaml("a: 2024-13-01\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("calendar date")),
            "got {err:?}"
        );
    }

    #[test]
    fn timestamp_with_year_zero_is_a_parse_error() {
        let err = read_yaml("a: 0000-01-01\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("calendar date")),
            "got {err:?}"
        );
    }

    #[test]
    fn timestamp_with_a_day_that_doesnt_exist_in_the_month_is_a_parse_error() {
        // February 30th never exists, regardless of leap year -- exercises
        // the day-count upper bound (`schema::valid_ymd`'s `days_in_month`),
        // not just the "day < 1" lower bound.
        let err = read_yaml("a: 2024-02-30\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("calendar date")),
            "got {err:?}"
        );
    }

    #[test]
    fn timestamp_february_29_on_a_non_leap_year_is_a_parse_error() {
        let err = read_yaml("a: 2023-02-29\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("calendar date")),
            "got {err:?}"
        );
    }

    #[test]
    fn timestamp_february_29_on_a_leap_year_normalizes_fine() {
        let doc = read_yaml("a: 2024-02-29\n").unwrap();
        assert_eq!(
            *doc.root().get_one("a").unwrap().value().unwrap(),
            Scalar::Date("2024-02-29".to_string())
        );
    }

    #[test]
    fn timestamp_with_out_of_range_hour_is_a_parse_error() {
        let err = read_yaml("a: 2024-01-01T25:00:00\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("time of day")),
            "got {err:?}"
        );
    }

    #[test]
    fn timestamp_with_out_of_range_minute_is_a_parse_error() {
        let err = read_yaml("a: 2024-01-01T00:61:00\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("time of day")),
            "got {err:?}"
        );
    }

    #[test]
    fn timestamp_with_out_of_range_timezone_offset_is_a_parse_error() {
        let err = read_yaml("a: 2024-01-01T00:00:00+25:00\n").unwrap_err();
        assert!(
            matches!(&err, OmnistError::Parse(e) if e.message.contains("timezone offset")),
            "got {err:?}"
        );
    }

    #[test]
    fn timestamp_with_hour_only_timezone_offset_normalizes_with_zero_minutes() {
        let doc = read_yaml("a: 2024-01-01T00:00:00+05\n").unwrap();
        assert_eq!(
            *doc.root().get_one("a").unwrap().value().unwrap(),
            Scalar::Datetime("2024-01-01T00:00:00+05:00".to_string())
        );
    }

    // ---------------------------------------------------------- coverage: writer

    #[test]
    fn nel_in_a_label_triggers_a_warning_and_still_round_trips() {
        let label = format!("a{}b", '\u{0085}');
        let doc = doc_of(obj(vec![(label.as_str(), Value::Int((1).into()))]));
        let mut rep = WriteReport::new();
        let text = write_yaml(&doc, false, Some(&mut rep)).unwrap();
        assert_eq!(rep.len(), 1);
        assert_eq!(rep.adjustments()[0].code, "format.string-line-break-char");
        let back = read_yaml(&text).unwrap();
        assert_eq!(
            *back.root().get_one(&label).unwrap().value().unwrap(),
            Scalar::Int((1).into())
        );
    }

    #[test]
    fn write_node_on_a_bare_empty_array_writes_the_flow_empty_token() {
        // `Doc`'s own model never produces a *standalone* empty-array node
        // (an empty `Value::Array` under a key expands into zero edges at
        // construction time -- see `document.rs`'s own note on this) --
        // white-box exercising `write_node`'s empty-array arm directly here,
        // the same "test the arm directly since the public API can't reach
        // it" pattern `document.rs`'s `internal_edges_mut_rejects_a_leaf_directly`
        // and `json.rs`'s handling of the analogous case establish.
        let mut out = String::new();
        write_node(&Value::Array(vec![]), 0, &mut out, true);
        assert_eq!(out, "[]\n");
    }

    #[test]
    fn round_trips_strings_needing_every_quoting_trigger() {
        let cases = [
            "-leading-dash",
            "?leading-question",
            ":leading-colon",
            ",leading-comma",
            "[leading-bracket",
            "]leading-bracket",
            "{leading-brace",
            "}leading-brace",
            "#leading-hash",
            "&leading-amp",
            "*leading-star",
            "!leading-bang",
            "|leading-pipe",
            ">leading-gt",
            "'leading-quote",
            "\"leading-dquote",
            "%leading-percent",
            "@leading-at",
            "`leading-backtick",
            " leading-space",
            "trailing-space ",
            "embedded: colon-space",
            "trailing-colon:",
            "embedded #hash-space",
            "line\nbreak",
            "tab\ttab",
            "quote\"quote",
            "back\\slash",
            "control\u{01}char",
        ];
        for s in cases {
            let doc = doc_of(obj(vec![("s", Value::Str(s.to_string()))]));
            let text = write_yaml(&doc, false, None).unwrap();
            let back = read_yaml(&text).unwrap();
            assert!(
                doc.eq_doc(&back),
                "round trip failed for {s:?}, text was:\n{text}"
            );
        }
    }

    #[test]
    fn write_scalar_value_panics_on_a_non_leaf_value() {
        // `write_scalar_value` is only ever called on a leaf via the public
        // `write_yaml` path (every call site passes a scalar) -- white-box
        // confirming the documented invariant directly, same rationale as
        // the empty-array test above.
        let result = std::panic::catch_unwind(|| {
            let mut out = String::new();
            write_scalar_value(&Value::Object(IndexMap::new()), &mut out);
        });
        assert!(result.is_err());
    }

    // ---------------------------------------------------------- coverage: Builder white-box

    // The following four tests drive `Builder`'s private event-handling
    // methods directly rather than through `read_yaml`/`Parser`. Each covers
    // a branch that is structurally unreachable via any real YAML text --
    // confirmed empirically (see `on_event_impl`'s doc comment and this
    // module's doc comment on the crate-choice rationale): `yaml_rust2`'s own
    // scanner already rejects an alias to an undefined anchor, and every
    // document's event stream always nests its root exactly once before a
    // `DocumentEnd`/pushes only `Sequence`/`Mapping` as containers. Testing
    // the arm directly (rather than leaving it an untested dead branch)
    // matches `document.rs`'s `internal_edges_mut_rejects_a_leaf_directly`
    // precedent.
    use yaml_rust2::parser::Event;
    use yaml_rust2::scanner::Marker;

    /// `Marker` has no public constructor, so a real one is captured from an
    /// actual (trivial) parse -- the tests below only care about the event
    /// stream reaching `Builder`'s methods, not about which `Marker` value
    /// they carry.
    fn test_marker() -> Marker {
        struct Capture(Option<Marker>);
        impl MarkedEventReceiver for Capture {
            fn on_event(&mut self, _ev: Event, mark: Marker) {
                self.0.get_or_insert(mark);
            }
        }
        let mut cap = Capture(None);
        Parser::new("x".chars()).load(&mut cap, false).unwrap();
        cap.0
            .expect("a trivial scalar document always emits at least one event")
    }

    /// The alias check refuses every non-mapping merge shape before the
    /// merge resolver runs (D-18a); these two arms are its backstop, proven
    /// by calling the resolver directly, as for the other `unreachable!`s.
    #[test]
    #[should_panic(expected = "the alias check refused a scalar merge value")]
    fn merge_source_entries_panics_on_a_scalar_the_check_refused() {
        let scalar = Raw::Scalar("1".to_string(), TScalarStyle::Plain, None);
        let _ = merge_source_entries(&scalar, 0, 200, &mut Vec::new());
    }

    #[test]
    #[should_panic(expected = "the alias check refused a non-mapping merge member")]
    fn merge_source_entries_panics_on_a_member_the_check_refused() {
        let member = Raw::Scalar("1".to_string(), TScalarStyle::Plain, None);
        let _ = merge_source_entries(&Raw::Sequence(vec![member]), 0, 200, &mut Vec::new());
    }

    #[test]
    fn builder_document_end_with_an_empty_stack_pushes_a_null_scalar() {
        let mut b = Builder::new(&Resolved::DEFAULT);
        b.on_event_impl(Event::DocumentEnd, test_marker());
        assert_eq!(b.docs.len(), 1);
        assert!(matches!(&b.docs[0], Raw::Scalar(s, TScalarStyle::Plain, None) if s.is_empty()));
    }

    #[test]
    #[should_panic(expected = "a single document's stack never nests more than one root")]
    fn builder_document_end_with_more_than_one_stack_entry_panics() {
        let mut b = Builder::new(&Resolved::DEFAULT);
        b.doc_stack
            .push((Raw::Scalar(String::new(), TScalarStyle::Plain, None), 0));
        b.doc_stack
            .push((Raw::Scalar(String::new(), TScalarStyle::Plain, None), 0));
        b.on_event_impl(Event::DocumentEnd, test_marker());
    }

    #[test]
    #[should_panic(expected = "a Scalar is never a container on doc_stack")]
    fn builder_insert_onto_a_scalar_container_panics() {
        let mut b = Builder::new(&Resolved::DEFAULT);
        b.doc_stack
            .push((Raw::Scalar("x".to_string(), TScalarStyle::Plain, None), 0));
        b.insert(
            Raw::Scalar("y".to_string(), TScalarStyle::Plain, None),
            0,
            test_marker(),
        );
    }

    #[test]
    fn builder_alias_to_an_anchor_with_no_entry_is_a_document_error_not_a_panic() {
        // Calling `on_event_impl` directly with an id that has no entry: the
        // same state a self-referential definition reaches through real
        // input (see `self_referential_anchors_are_rejected_not_panicked`).
        let mut b = Builder::new(&Resolved::DEFAULT);
        b.on_event_impl(Event::Alias(999), test_marker());
        let e = b.self_reference.as_ref().expect("recorded");
        assert_eq!(e.code.as_deref(), Some("document.limit.alias-expansion"));
        assert_eq!(e.path, "$");
        // Once set, further events are ignored.
        b.on_event_impl(Event::Alias(999), test_marker());
    }

    #[test]
    fn an_explicit_int_tag_on_non_integer_text_is_a_syntax_error_not_a_panic() {
        for src in [
            "a: !!int x\n",
            "a: !!int -\n",
            "a: !!int 0xZZ\n",
            "a: !!int ''\n",
        ] {
            let e = read_yaml(src).unwrap_err();
            assert!(
                matches!(&e, OmnistError::Parse(p) if p.code == "parse.codec-syntax"),
                "{src:?}: {e:?}"
            );
        }
        assert_eq!(
            read_yaml("a: !!int 0x1f\n").unwrap().to_raw(),
            crate::document::RawNode::Edges(vec![(
                "a".to_string(),
                crate::document::RawNode::Leaf(Scalar::Int(31.into()))
            )])
        );
    }

    #[test]
    fn self_referential_anchors_are_rejected_not_panicked() {
        // Both inputs used to panic the library on an `.expect()`.
        for src in [
            "a: &A\n  b: *A\n",
            "a: &A\n  <<: *A\n  x: 1\n",
            "a: &A [*A]\n",
            "a: &A\n  b: &B\n    c: *A\n",
        ] {
            let e = read_yaml(src).unwrap_err();
            assert!(
                matches!(&e, OmnistError::Document(d)
                    if d.code.as_deref() == Some("document.limit.alias-expansion") && d.path == "$"),
                "{src:?}: {e:?}"
            );
        }
        // A completed anchor reused afterwards is still fine.
        assert!(read_yaml("a: &A\n  b: 1\nc: *A\n").is_ok());
    }

    // -------------------------------------------------- coverage: issue #42 node-count guard

    /// Calling `charge` directly once `self.error` is already `Some(..)`
    /// exercises the short-circuit at the very top of `charge` (returns
    /// `false` without touching `node_count` or overwriting `error`) --
    /// unreachable through `on_event_impl` alone, since its own top-of-
    /// function `self.error.is_some()` check means `charge` is never
    /// invoked a second time once tripped in the normal event-driven path.
    #[test]
    fn charge_after_already_tripped_is_a_pure_no_op() {
        let mut b = Builder::new(&Resolved::DEFAULT);
        assert!(!b.charge(MAX_MATERIALIZED_NODES + 1, test_marker()));
        let first_error = format!("{:?}", b.error);
        let count_after_first_trip = b.node_count;
        assert!(!b.charge(1, test_marker()));
        assert_eq!(
            format!("{:?}", b.error),
            first_error,
            "error must not change"
        );
        assert_eq!(
            b.node_count, count_after_first_trip,
            "node_count must not change once already tripped"
        );
    }

    /// Drives the guard to trip from `Event::SequenceStart`'s `charge` call
    /// specifically (as opposed to the size-charging `Event::Alias` path
    /// the top-level `billion_laughs_...` integration test exercises),
    /// confirming every one of the three plain-node `charge` call sites is
    /// independently reachable.
    #[test]
    fn sequence_start_can_itself_trip_the_node_count_guard() {
        let mut b = Builder::new(&Resolved::DEFAULT);
        b.node_count = MAX_MATERIALIZED_NODES;
        b.on_event_impl(Event::SequenceStart(0, None), test_marker());
        assert!(
            matches!(&b.error, Some(e) if e.message.contains("materializes more than")),
            "got {:?}",
            b.error
        );
        // The doc_stack push it guards must not have happened.
        assert!(b.doc_stack.is_empty());
    }

    /// Same as above, for `Event::MappingStart`.
    #[test]
    fn mapping_start_can_itself_trip_the_node_count_guard() {
        let mut b = Builder::new(&Resolved::DEFAULT);
        b.node_count = MAX_MATERIALIZED_NODES;
        b.on_event_impl(Event::MappingStart(0, None), test_marker());
        assert!(
            matches!(&b.error, Some(e) if e.message.contains("materializes more than")),
            "got {:?}",
            b.error
        );
        assert!(b.doc_stack.is_empty());
        assert!(b.key_stack.is_empty());
    }

    #[test]
    fn n189_the_cap_counts_containers_not_keys_or_scalar_values() {
        let mut b = Builder::new(&Resolved::DEFAULT);
        let mark = test_marker();
        b.on_event_impl(Event::MappingStart(0, None), mark);
        for i in 0..10 {
            b.on_event_impl(
                Event::Scalar(format!("k{i}"), TScalarStyle::Plain, 0, None),
                mark,
            );
            b.on_event_impl(
                Event::Scalar(format!("v{i}"), TScalarStyle::Plain, 0, None),
                mark,
            );
        }
        assert_eq!(b.node_count, 1, "one mapping, twenty scalars: one node");
    }

    #[test]
    fn n189_the_node_cap_boundary_is_exact() {
        let mark = test_marker();
        let mut b = Builder::new(&Resolved::DEFAULT);
        b.node_count = MAX_MATERIALIZED_NODES - 1;
        b.on_event_impl(Event::MappingStart(0, None), mark);
        assert!(b.error.is_none(), "exactly the cap is accepted");
        assert_eq!(b.node_count, MAX_MATERIALIZED_NODES);
        b.on_event_impl(Event::SequenceStart(0, None), mark);
        assert!(
            matches!(&b.error, Some(e) if e.code.as_deref() == Some("document.limit.nodes")),
            "one past the cap is refused: {:?}",
            b.error
        );
    }

    #[test]
    fn n189_the_default_node_cap_is_the_spec_reference_default() {
        assert_eq!(MAX_MATERIALIZED_NODES, 1_000_000);
    }

    #[test]
    fn n189_an_alias_is_charged_for_the_containers_it_clones() {
        let mut b = Builder::new(&Resolved::DEFAULT);
        let mark = test_marker();
        // &1 [x, {a: b}] holds a sequence and a mapping: two containers.
        b.on_event_impl(Event::SequenceStart(1, None), mark);
        b.on_event_impl(
            Event::Scalar("x".into(), TScalarStyle::Plain, 0, None),
            mark,
        );
        b.on_event_impl(Event::MappingStart(0, None), mark);
        b.on_event_impl(
            Event::Scalar("a".into(), TScalarStyle::Plain, 0, None),
            mark,
        );
        b.on_event_impl(
            Event::Scalar("b".into(), TScalarStyle::Plain, 0, None),
            mark,
        );
        b.on_event_impl(Event::MappingEnd, mark);
        b.on_event_impl(Event::SequenceEnd, mark);
        assert_eq!(b.node_count, 2);
    }

    // ---------------------------------------------------------- coverage: writer edge cases

    #[test]
    fn round_trips_an_integral_float_with_trailing_dot_zero() {
        let doc = doc_of(obj(vec![("f", Value::Float(2.0))]));
        let text = write_yaml(&doc, false, None).unwrap();
        assert!(text.contains("f: 2.0"), "text was:\n{text}");
        let back = read_yaml(&text).unwrap();
        assert!(doc.eq_doc(&back));
    }

    #[test]
    fn quoted_string_escapes_every_special_character_in_one_pass() {
        // A leading `-` forces quoting; once quoted, this exercises every
        // remaining escape arm in `write_yaml_string`'s per-char loop in a
        // single string: backslash, tab, double-quote, and a low control
        // character (NEL and newline are already covered by dedicated tests).
        let s = "-a\tb\\c\"d\u{01}e";
        let doc = doc_of(obj(vec![("s", Value::Str(s.to_string()))]));
        let text = write_yaml(&doc, false, None).unwrap();
        let back = read_yaml(&text).unwrap();
        assert!(doc.eq_doc(&back), "text was:\n{text}");
    }

    #[test]
    fn write_seq_child_on_a_bare_non_empty_array_item_writes_it_on_the_next_line() {
        // The Document model never produces a sequence item that is itself a
        // *standalone* non-empty array (sequence-of-sequences has no
        // labeled-edge form -- see `sequence_of_sequences_is_a_document_error`
        // above), so this arm of `write_seq_child` is unreachable via any
        // real `Doc` -- white-box exercising it directly, same rationale as
        // `write_node_on_a_bare_empty_array_writes_the_flow_empty_token`.
        let mut out = String::new();
        write_seq_child(
            &Value::Array(vec![Value::Int((1).into()), Value::Int((2).into())]),
            0,
            &mut out,
        );
        assert_eq!(out, "\n  - 1\n  - 2\n");
    }

    #[test]
    fn test_yaml_merge_key_deduplication_order() {
        let src = r#"
base1: &b1
  a: 1
  b: 2
  dup: "from_b1"
base2: &b2
  b: 20
  c: 3
  dup: "from_b2"
child:
  <<: [*b1, *b2]
  own: 0
  a: 100
"#;
        let doc = read_yaml(src).unwrap();
        let root = doc.root();
        let child = root.get_one("child").unwrap();
        let labels = child.labels();
        // Merged entries come first, in source order (b1's a, b, dup, then
        // b2's c -- its b and dup are collisions the earlier alias wins); the
        // local `a` keeps the merged `a`'s position with the local value; the
        // non-colliding own key `own` follows.
        assert_eq!(labels, vec!["a", "b", "dup", "c", "own"]);
        assert_eq!(
            *child.get_one("a").unwrap().value().unwrap(),
            Scalar::Int((100).into())
        );
        assert_eq!(
            *child.get_one("b").unwrap().value().unwrap(),
            Scalar::Int((2).into())
        );
        assert_eq!(
            *child.get_one("dup").unwrap().value().unwrap(),
            Scalar::Str("from_b1".into())
        );
        assert_eq!(
            *child.get_one("c").unwrap().value().unwrap(),
            Scalar::Int((3).into())
        );
    }

    // ---------------------------------------------- D-3: format.interleaving-lost
    // (issue #156, spec Sec8.3.8. Same MUST as formats-json/basic/
    // cross-label-interleaving-lost-and-reported -- YAML shares JSON's
    // `to_grouped` grouping, so the loss and the report are identical
    // in shape; see json.rs's mirrored tests.)

    fn interleaved_doc() -> Doc {
        Doc::from_raw(crate::document::RawNode::Edges(vec![
            (
                "m".to_string(),
                crate::document::RawNode::Leaf(Scalar::Str("A".to_string())),
            ),
            (
                "x".to_string(),
                crate::document::RawNode::Leaf(Scalar::Str("X".to_string())),
            ),
            (
                "m".to_string(),
                crate::document::RawNode::Leaf(Scalar::Str("B".to_string())),
            ),
        ]))
        .unwrap()
    }

    fn contiguous_repeat_doc() -> Doc {
        Doc::from_raw(crate::document::RawNode::Edges(vec![
            (
                "m".to_string(),
                crate::document::RawNode::Leaf(Scalar::Str("A".to_string())),
            ),
            (
                "m".to_string(),
                crate::document::RawNode::Leaf(Scalar::Str("B".to_string())),
            ),
            (
                "x".to_string(),
                crate::document::RawNode::Leaf(Scalar::Str("X".to_string())),
            ),
        ]))
        .unwrap()
    }

    #[test]
    fn reports_interleaving_lost_on_write() {
        let doc = interleaved_doc();
        let mut report = crate::report::WriteReport::new();
        write_yaml(&doc, false, Some(&mut report)).unwrap();
        let adjustments = report.adjustments();
        assert_eq!(adjustments.len(), 1);
        assert_eq!(adjustments[0].path, "$");
        assert_eq!(adjustments[0].code, "format.interleaving-lost");
        assert_eq!(adjustments[0].severity, crate::report::Severity::Warning);
    }

    #[test]
    fn check_yaml_reports_interleaving_lost() {
        let rep = check_yaml(&interleaved_doc());
        assert_eq!(rep.adjustments().len(), 1);
        assert_eq!(rep.adjustments()[0].code, "format.interleaving-lost");
    }

    #[test]
    fn contiguous_repeated_label_does_not_report_interleaving_lost() {
        let doc = contiguous_repeat_doc();
        let mut report = crate::report::WriteReport::new();
        write_yaml(&doc, false, Some(&mut report)).unwrap();
        assert!(report.is_empty());
        assert!(check_yaml(&doc).is_empty());
    }
}

#[cfg(test)]
mod v035_tests {
    use super::*;
    use crate::document::{Doc, Scalar, Value};

    fn one(label: &str, v: Value) -> Doc {
        let mut m = IndexMap::new();
        m.insert(label.to_string(), v);
        Doc::of(&Value::Object(m)).unwrap()
    }

    fn written(v: Value) -> String {
        write_yaml(&one("a", v), false, None).unwrap()
    }

    #[test]
    fn characters_yaml_does_not_print_are_escaped_in_lowercase() {
        for (c, want) in [
            ('\u{0}', "\"x\\x00y\""),
            ('\u{1}', "\"x\\x01y\""),
            ('\u{8}', "\"x\\x08y\""),
            ('\u{b}', "\"x\\x0by\""),
            ('\u{1f}', "\"x\\x1fy\""),
            ('\u{7f}', "\"x\\x7fy\""),
            ('\u{80}', "\"x\\x80y\""),
            ('\u{9f}', "\"x\\x9fy\""),
            ('\u{85}', "\"x\\Ny\""),
            ('\u{fffe}', "\"x\\ufffey\""),
            ('\u{ffff}', "\"x\\uffffy\""),
        ] {
            assert_eq!(
                written(Value::Str(format!("x{c}y"))),
                format!("a: {want}"),
                "{c:?}"
            );
        }
        // Printable neighbours stay plain.
        for c in ['\u{a0}', '\u{fffd}', 'é'] {
            assert_eq!(written(Value::Str(format!("x{c}y"))), format!("a: x{c}y"));
        }
    }

    #[test]
    fn a_time_is_written_double_quoted_with_its_seconds_and_reported() {
        for (t, want) in [
            ("12:00:00", "a: \"12:00:00\""),
            ("12:00", "a: \"12:00:00\""),
            ("12:00:00.5", "a: \"12:00:00.5\""),
            ("12:00:00.123456+01:00", "a: \"12:00:00.123456+01:00\""),
        ] {
            let doc = one("a", Value::Time(t.to_string()));
            let mut rep = WriteReport::new();
            assert_eq!(write_yaml(&doc, false, Some(&mut rep)).unwrap(), want);
            assert_eq!(rep.adjustments().len(), 1);
            assert_eq!(rep.adjustments()[0].path, "$.a");
            assert_eq!(rep.adjustments()[0].code, "format.temporal-stringified");
            assert_eq!(check_yaml(&doc).adjustments().len(), 1);
        }
        assert_eq!(
            written(Value::Datetime("2024-01-15 12:00".to_string())),
            "a: 2024-01-15T12:00:00"
        );
    }

    #[test]
    fn a_sexagesimal_float_reads_as_a_number_and_the_look_alikes_stay_strings() {
        for (text, want) in [
            ("1:30.5", 90.5),
            ("-1:30.5", -90.5),
            ("+1:30.5", 90.5),
            ("1:30:15.25", 5415.25),
            ("1_0:30.5", 630.5),
            ("190:20:30.15", 685230.15),
            ("1:30.", 90.0),
        ] {
            let doc = read_yaml(&format!("a: {text}\n")).unwrap();
            assert_eq!(
                *doc.root().get_one("a").unwrap().value().unwrap(),
                Scalar::Float(want),
                "{text}"
            );
        }
        for text in [
            "0o17", "08", "09", "0:5", "1e3", "1.0e3", "1:60.5", "1:30.5x",
        ] {
            let doc = read_yaml(&format!("a: {text}\n")).unwrap();
            assert_eq!(
                *doc.root().get_one("a").unwrap().value().unwrap(),
                Scalar::Str(text.to_string()),
            );
        }
    }

    #[test]
    fn a_string_that_reads_as_a_sexagesimal_float_is_written_quoted() {
        assert_eq!(written(Value::Str("1:30.5".to_string())), "a: \"1:30.5\"");
    }

    #[test]
    fn a_fraction_past_six_digits_fails_the_read_and_is_quoted_on_write() {
        let err = read_yaml("t: 2024-01-15T12:00:00.1234567+01:00\n")
            .unwrap_err()
            .to_string();
        assert!(err.contains("fractional second"), "{err}");
        // Zeros past the sixth digit are insignificant.
        assert!(read_yaml("t: 2024-01-15T12:00:00.1234560\n").is_ok());
        let doc = one(
            "t",
            Value::Datetime("2024-01-15T12:00:00.1234567+01:00".to_string()),
        );
        let mut report = WriteReport::new();
        let text = write_yaml(&doc, false, Some(&mut report)).unwrap();
        assert_eq!(text, "t: \"2024-01-15T12:00:00.1234567+01:00\"");
        assert_eq!(report.adjustments()[0].code, "format.temporal-stringified");
        assert_eq!(check_yaml(&doc).adjustments().len(), 1);
    }
}