frontmatter_gen/

parser.rs

//! # Front Matter Parser and Serialiser Module
//!
//! This module provides robust functionality for parsing and serialising front matter
//! in various formats (YAML, TOML, and JSON). It focuses on:
//!
//! - Memory efficiency through pre-allocation and string optimisation
//! - Type safety with comprehensive error handling
//! - Performance optimisation with minimal allocations
//! - Validation of input data
//! - Consistent cross-format handling
//!
//! ## Features
//!
//! - Multi-format support (YAML, TOML, JSON)
//! - Zero-copy parsing where possible
//! - Efficient memory management
//! - Comprehensive validation
//! - Rich error context
//!
//! ## Usage Example
//!
//! ```rust
//! use frontmatter_gen::{Format, parser};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let yaml = "title: My Post\ndate: 2025-09-09\n";
//! let front_matter = parser::parse_with_options(
//!     yaml,
//!     Format::Yaml,
//!     None
//! )?;
//! # Ok(())
//! # }
//! ```

use noyalib::Value as YamlValue;
use serde::Serialize;
use serde_json::Value as JsonValue;
use std::{collections::HashMap, sync::Arc};
use toml::Value as TomlValue;

use crate::{error::Error, types::Frontmatter, Format, Value};

// Constants for optimisation and validation
const SMALL_STRING_SIZE: usize = 24;
const MAX_NESTING_DEPTH: usize = 32;
const MAX_KEYS: usize = 1000;

/// Options for controlling parsing behaviour.
///
/// Provides configuration for maximum allowed nesting depth, maximum number of keys,
/// and whether to perform validation.
#[derive(Debug, Clone, Copy)]
pub struct ParseOptions {
    /// Maximum allowed nesting depth.
    pub max_depth: usize,
    /// Maximum allowed number of keys.
    pub max_keys: usize,
    /// Whether to validate the structure.
    pub validate: bool,
}

impl Default for ParseOptions {
    fn default() -> Self {
        Self {
            max_depth: MAX_NESTING_DEPTH,
            max_keys: MAX_KEYS,
            validate: true,
        }
    }
}

/// Optimises string storage based on length.
///
/// For strings shorter than `SMALL_STRING_SIZE`, uses standard allocation.
/// For longer strings, pre-allocates exact capacity to avoid reallocations.
///
/// # Arguments
///
/// * `s` - The input string slice to optimise.
///
/// # Returns
///
/// An optimised owned `String`.
#[inline]
fn optimise_string(s: &str) -> String {
    if s.len() <= SMALL_STRING_SIZE {
        s.to_string()
    } else {
        let mut string = String::with_capacity(s.len());
        string.push_str(s);
        string
    }
}

/// Parses raw front matter string into a `Frontmatter` object based on the specified format.
///
/// This function attempts to parse the provided string into a structured `Frontmatter`
/// object according to the specified format. It performs validation by default
/// and optimises memory allocation where possible.
///
/// # Arguments
///
/// * `raw_front_matter` - A string slice containing the raw front matter content.
/// * `format` - The `Format` enum specifying the desired format.
/// * `options` - Optional parsing options for controlling validation and limits.
///
/// # Returns
///
/// A `Result` containing either the parsed `Frontmatter` object or a `Error`.
///
/// # Errors
///
/// Returns `Error` if:
/// - The input is not valid in the specified format
/// - The structure exceeds configured limits
/// - The format is unsupported
pub fn parse_with_options(
    raw_front_matter: &str,
    format: Format,
    options: Option<ParseOptions>,
) -> Result<Frontmatter, Error> {
    let options = options.unwrap_or_default();

    // Trim the input and validate format assumptions
    let trimmed = raw_front_matter.trim();

    let front_matter = match format {
        Format::Yaml => parse_yaml_checked(trimmed)?,
        Format::Toml => parse_toml_checked(trimmed)?,
        Format::Json => parse_json_checked(trimmed)?,
        Format::Unsupported => parse_unsupported(format)?,
    };

    // Perform validation if specified in options
    if options.validate {
        let max_depth = options.max_depth;
        let max_keys = options.max_keys;
        log::debug!("Validating front matter: maximum allowed nesting depth is {max_depth}, maximum allowed number of keys is {max_keys}");

        validate_frontmatter(&front_matter, max_depth, max_keys)
            .map_err(|e| {
                log::error!("Front matter validation failed: {}", e);
                e
            })?;
    }

    Ok(front_matter)
}

/// Validates and parses YAML front matter content.
fn parse_yaml_checked(trimmed: &str) -> Result<Frontmatter, Error> {
    if !trimmed.starts_with("---") {
        log::debug!("YAML front matter validation: Content structure appears non-standard");
    }
    parse_yaml(trimmed).map_err(|e| {
        log::error!("YAML parsing failed: {}", e);
        e
    })
}

const ERR_TOML_MISSING_EQ: &str =
    "Format set to TOML but input does not contain '=' signs.";
const ERR_JSON_MISSING_BRACE: &str =
    "Format set to JSON but input does not start with '{'.";

/// Validates and parses TOML front matter content.
fn parse_toml_checked(trimmed: &str) -> Result<Frontmatter, Error> {
    if !trimmed.contains('=') {
        let msg = ERR_TOML_MISSING_EQ.to_string();
        return Err(Error::ConversionError(msg));
    }
    parse_toml(trimmed).map_err(|e| {
        log::error!("TOML parsing failed: {}", e);
        e
    })
}

/// Validates and parses JSON front matter content.
fn parse_json_checked(trimmed: &str) -> Result<Frontmatter, Error> {
    if !trimmed.starts_with('{') {
        let msg = ERR_JSON_MISSING_BRACE.to_string();
        return Err(Error::ConversionError(msg));
    }
    parse_json(trimmed).map_err(|e| {
        log::error!("JSON parsing failed: {}", e);
        e
    })
}

/// Constructs and logs an unsupported format error.
fn parse_unsupported(format: Format) -> Result<Frontmatter, Error> {
    let err_msg = format!("Unsupported format: {format:?}. Supported formats are YAML, TOML, and JSON.");
    log::error!("{err_msg}");
    Err(Error::ConversionError(err_msg))
}

/// Convenience wrapper around `parse_with_options` using default options.
///
/// # Arguments
///
/// * `raw_front_matter` - A string slice containing the raw front matter content.
/// * `format` - The `Format` enum specifying the desired format.
///
/// # Returns
///
/// A `Result` containing either the parsed `Frontmatter` object or a `Error`.
///
/// # Errors
///
/// Returns an `Error` if:
/// - The format is invalid or unsupported.
/// - Parsing fails due to invalid syntax.
/// - Validation fails if enabled.
pub fn parse(
    raw_front_matter: &str,
    format: Format,
) -> Result<Frontmatter, Error> {
    parse_with_options(raw_front_matter, format, None)
}

/// Converts a `Frontmatter` object to a string representation in the specified format.
///
/// # Arguments
///
/// * `front_matter` - Reference to the `Frontmatter` object to serialise.
/// * `format` - The target format for serialisation.
///
/// # Returns
///
/// A `Result` containing the serialised string or a `Error`.
///
/// # Errors
///
/// Returns `Error` if:
/// - Serialisation fails.
/// - The specified format is unsupported.
pub fn to_string(
    front_matter: &Frontmatter,
    format: Format,
) -> Result<String, Error> {
    match format {
        Format::Yaml => to_yaml(front_matter),
        Format::Toml => to_toml(front_matter),
        Format::Json => to_json_optimised(front_matter),
        Format::Unsupported => Err(Error::ConversionError(
            "Unsupported format".to_string(),
        )),
    }
}

// YAML Implementation
// -------------------

/// Parses a YAML string into a `Frontmatter` object.
///
/// # Arguments
///
/// * `raw` - The raw YAML string.
///
/// # Returns
///
/// A `Result` containing the parsed `Frontmatter` or a `Error`.
fn parse_yaml(raw: &str) -> Result<Frontmatter, Error> {
    // Parse the YAML content into a noyalib::Value
    let yaml_value: YamlValue = noyalib::from_str(raw)
        .map_err(|e| Error::YamlParseError { source: e.into() })?;

    // Prepare the front matter container
    let capacity =
        yaml_value.as_mapping().map_or(0, noyalib::Mapping::len);
    let mut front_matter =
        Frontmatter(HashMap::with_capacity(capacity));

    // Convert the YAML mapping into the front matter structure.
    //
    // `noyalib::Mapping` keys are guaranteed `String` (unlike serde_yml's
    // `Value`-keyed mapping), so we can iterate directly without an extra
    // type check.
    if let YamlValue::Mapping(mapping) = yaml_value {
        for (key, value) in mapping {
            // `mapping` is consumed by value, so each `value` is owned
            // here. Passing `&value` forced `yaml_to_value` to allocate a
            // fresh `String` for every scalar it had just been handed.
            let _ = front_matter.insert(key, yaml_into_value(value));
        }
    } else {
        return Err(Error::ParseError(
            "YAML front matter is not a valid mapping".to_string(),
        ));
    }

    Ok(front_matter)
}

/// Converts an **owned** `noyalib::Value` into a `Value`, moving strings
/// rather than copying them.
///
/// The borrowed [`yaml_to_value`] is kept for callers that genuinely only
/// have a reference (nested sequences reached through a borrow). Where the
/// caller owns the value — which the mapping loop in [`parse_yaml`] does,
/// because it consumes the mapping — this avoids one heap allocation and
/// one copy per scalar.
///
/// Measured on a 2,000-document corpus of typical frontmatter: the parse
/// phase allocated 22.4 MB across 202k allocations to read 0.9 MB of
/// input, roughly eight allocations per value. Every string was allocated
/// once by the YAML parser and again here.
fn yaml_into_value(yaml: YamlValue) -> Value {
    match yaml {
        YamlValue::String(s) => Value::String(s),
        YamlValue::Sequence(seq) => {
            Value::Array(seq.into_iter().map(yaml_into_value).collect())
        }
        YamlValue::Mapping(map) => {
            let mut inner = HashMap::with_capacity(map.len());
            for (k, v) in map {
                let _ = inner.insert(k, yaml_into_value(v));
            }
            Value::Object(Box::new(Frontmatter(inner)))
        }
        // Scalars that own nothing: reuse the borrowed conversion so the
        // number-precision handling lives in exactly one place.
        other => yaml_to_value(&other),
    }
}

/// Converts a `noyalib::Value` into a `Value`.
fn yaml_to_value(yaml: &YamlValue) -> Value {
    match yaml {
        YamlValue::Null => Value::Null,
        YamlValue::Bool(b) => Value::Boolean(*b),
        YamlValue::Number(n) => {
            // `noyalib::Number::as_f64` returns `f64` directly (not
            // `Option<f64>` — integers are losslessly widened when
            // possible). We still prefer the integer path when the value
            // fits in f64's 52-bit mantissa, falling back to the float
            // representation otherwise.
            n.as_i64().map_or_else(
                || Value::Number(n.as_f64()),
                |i| {
                    if i.abs() < (1_i64 << 52) {
                        Value::Number(i as f64)
                    } else {
                        log::warn!(
                            "Integer {} exceeds precision of f64. Defaulting to 0.0",
                            i
                        );
                        Value::Number(0.0) // Fallback for large values outside f64 precision
                    }
                },
            )
        }
        YamlValue::String(s) => Value::String(optimise_string(s)),
        YamlValue::Sequence(seq) => {
            let mut vec = Vec::with_capacity(seq.len());
            vec.extend(seq.iter().map(yaml_to_value));
            Value::Array(vec)
        }
        YamlValue::Mapping(map) => {
            // `noyalib::Mapping` is keyed by `String` directly — no need
            // to filter out non-string keys the way we did with the old
            // `serde_yml::Value`-keyed mapping.
            let mut result =
                Frontmatter(HashMap::with_capacity(map.len()));
            for (k, v) in map {
                let key = optimise_string(k);
                let _ = result.insert(key, yaml_to_value(v));
            }
            Value::Object(Box::new(result))
        }
        YamlValue::Tagged(tagged) => Value::Tagged(
            optimise_string(tagged.tag().as_ref()),
            Box::new(yaml_to_value(tagged.value())),
        ),
    }
}

/// Serialises a `Frontmatter` object into a YAML string.
///
/// # Arguments
///
/// * `front_matter` - The `Frontmatter` object to serialise.
///
/// # Returns
///
/// A `Result` containing the serialised YAML string or a `Error`.
fn to_yaml(front_matter: &Frontmatter) -> Result<String, Error> {
    noyalib::to_string(&front_matter.0)
        .map_err(|e| Error::ConversionError(e.to_string()))
}

// TOML Implementation
// -------------------

/// Parses a TOML string into a `Frontmatter` object.
///
/// # Arguments
///
/// * `raw` - The raw TOML string.
///
/// # Returns
///
/// A `Result` containing the parsed `Frontmatter` or a `Error`.
fn parse_toml(raw: &str) -> Result<Frontmatter, Error> {
    // toml 1.x: `Value::from_str` parses a single TOML *value*, not a
    // document. Parse into `toml::Table` (i.e. a document) and wrap it.
    let table: toml::Table =
        raw.parse().map_err(Error::TomlParseError)?;

    let mut front_matter =
        Frontmatter(HashMap::with_capacity(table.len()));

    for (key, value) in table {
        let _ = front_matter.0.insert(key, toml_to_value(&value));
    }

    Ok(front_matter)
}

/// Converts a `toml::Value` into a `Value`.
fn toml_to_value(toml: &TomlValue) -> Value {
    match toml {
        TomlValue::String(s) => Value::String(optimise_string(s)),
        TomlValue::Integer(i) => Value::Number(*i as f64),
        TomlValue::Float(f) => Value::Number(*f),
        TomlValue::Boolean(b) => Value::Boolean(*b),
        TomlValue::Array(arr) => {
            let mut vec = Vec::with_capacity(arr.len());
            vec.extend(arr.iter().map(toml_to_value));
            Value::Array(vec)
        }
        TomlValue::Table(table) => {
            let mut result =
                Frontmatter(HashMap::with_capacity(table.len()));
            for (k, v) in table {
                let key = optimise_string(k);
                let _ = result.insert(key, toml_to_value(v));
            }
            Value::Object(Box::new(result))
        }
        TomlValue::Datetime(dt) => Value::String(dt.to_string()),
    }
}

/// Serialises a `Frontmatter` object into a TOML string.
///
/// # Arguments
///
/// * `front_matter` - The `Frontmatter` object to serialise.
///
/// # Returns
///
/// A `Result` containing the serialised TOML string or a `Error`.
fn to_toml(front_matter: &Frontmatter) -> Result<String, Error> {
    toml::to_string(&front_matter.0)
        .map_err(|e| Error::ConversionError(e.to_string()))
}

// JSON Implementation
// -------------------

/// Parses a JSON string into a `Frontmatter` object.
///
/// # Arguments
///
/// * `raw` - The raw JSON string.
///
/// # Returns
///
/// A `Result` containing the parsed `Frontmatter` or a `Error`.
fn parse_json(raw: &str) -> Result<Frontmatter, Error> {
    let json_value: JsonValue = serde_json::from_str(raw)
        .map_err(|e| Error::JsonParseError(Arc::new(e)))?;

    let capacity = match &json_value {
        JsonValue::Object(obj) => obj.len(),
        _ => 0,
    };

    let mut front_matter =
        Frontmatter(HashMap::with_capacity(capacity));

    if let JsonValue::Object(obj) = json_value {
        for (key, value) in obj {
            let _ = front_matter.0.insert(key, json_to_value(&value));
        }
    }

    Ok(front_matter)
}

/// Converts a `serde_json::Value` into a `Value`.
fn json_to_value(json: &JsonValue) -> Value {
    match json {
        JsonValue::Null => Value::Null,
        JsonValue::Bool(b) => Value::Boolean(*b),
        JsonValue::Number(n) => n.as_i64().map_or_else(
            || Value::Number(n.as_f64().unwrap_or(0.0)),
            |i| Value::Number(i as f64),
        ),
        JsonValue::String(s) => Value::String(optimise_string(s)),
        JsonValue::Array(arr) => {
            let mut vec = Vec::with_capacity(arr.len());
            vec.extend(arr.iter().map(json_to_value));
            Value::Array(vec)
        }
        JsonValue::Object(obj) => {
            let mut result =
                Frontmatter(HashMap::with_capacity(obj.len()));
            for (k, v) in obj {
                let key = optimise_string(k);
                let _ = result.insert(key, json_to_value(v));
            }
            Value::Object(Box::new(result))
        }
    }
}

/// Optimised JSON serialisation with pre-allocated buffer.
///
/// # Arguments
///
/// * `front_matter` - The `Frontmatter` object to serialise.
///
/// # Returns
///
/// A `Result` containing the serialised JSON string or a `Error`.
fn to_json_optimised(
    front_matter: &Frontmatter,
) -> Result<String, Error> {
    let estimated_size = estimate_json_size(front_matter);
    let buf = Vec::with_capacity(estimated_size);
    let mut ser = serde_json::Serializer::new(buf);

    let _ = front_matter.0.serialize(&mut ser);

    Ok(String::from_utf8(ser.into_inner()).unwrap_or_default())
}

// Validation and Utilities
// ------------------------

/// Validates a front matter structure against configured limits.
///
/// Checks:
/// - Maximum nesting depth.
/// - Maximum number of keys.
/// - Structure validity.
///
/// # Arguments
///
/// * `fm` - Reference to the front matter to validate.
/// * `max_depth` - Maximum allowed nesting depth.
/// * `max` - Maximum allowed number of keys.
///
/// # Returns
///
/// `Ok(())` if validation passes, `Error` otherwise.
///
/// # Errors
///
/// Returns `Error` if:
/// - The number of keys exceeds `max`.
/// - The nesting depth exceeds `max_depth`.
pub fn validate_frontmatter(
    fm: &Frontmatter,
    max_depth: usize,
    max: usize,
) -> Result<(), Error> {
    let size = fm.0.len();
    if size > max {
        return Err(Error::ContentTooLarge { size, max });
    }

    // Validate nesting depth
    for value in fm.0.values() {
        check_depth(value, 1, max_depth)?;
    }

    Ok(())
}

/// Recursively checks the nesting depth of a value.
///
/// # Arguments
///
/// * `value` - The `Value` to check.
/// * `depth` - The current depth of recursion.
/// * `max` - The maximum allowed depth.
///
/// # Returns
///
/// `Ok(())` if the depth is within limits, `Error` otherwise.
fn check_depth(
    value: &Value,
    depth: usize,
    max: usize,
) -> Result<(), Error> {
    if depth > max {
        return Err(Error::NestingTooDeep { depth, max });
    }

    if let Value::Array(arr) = value {
        for item in arr {
            check_depth(item, depth + 1, max)?;
        }
    } else if let Value::Object(obj) = value {
        for v in obj.0.values() {
            check_depth(v, depth + 1, max)?;
        }
    }

    Ok(())
}

/// Estimates the JSON string size for a front matter object.
///
/// Used for pre-allocating buffers in serialisation.
///
/// # Arguments
///
/// * `fm` - The `Frontmatter` object.
///
/// # Returns
///
/// An estimated size in bytes.
fn estimate_json_size(fm: &Frontmatter) -> usize {
    let mut size = 2; // {}
    for (k, v) in &fm.0 {
        size += k.len() + 3; // "key":
        size += estimate_value_size(v);
        size += 1; // ,
    }
    size
}

/// Estimates the serialised size of a value.
///
/// # Arguments
///
/// * `value` - The `Value` to estimate.
///
/// # Returns
///
/// An estimated size in bytes.
fn estimate_value_size(value: &Value) -> usize {
    match value {
        Value::Null => 4,                // null
        Value::String(s) => s.len() + 2, // "string"
        Value::Number(_) => 8,           // average number length
        Value::Boolean(_) => 5,          // false/true
        Value::Array(arr) => {
            2 + arr.iter().map(estimate_value_size).sum::<usize>() // []
        }
        Value::Object(obj) => estimate_json_size(obj),
        Value::Tagged(tag, val) => {
            tag.len() + 2 + estimate_value_size(val)
        }
    }
}

#[cfg(test)]
mod tests {
    /// The scalar arms of the borrowed converter: null, a non-integral
    /// float, an integer beyond f64's exact range, and a tagged value.
    ///
    /// These were reached on every parse when the mapping loop went
    /// through `yaml_to_value`; now that it moves through
    /// `yaml_into_value`, only `Tagged` and nested borrows arrive here, and
    /// Codecov reported them as newly uncovered. Each is asserted on its
    /// documented behaviour, not merely executed.
    #[test]
    fn yaml_to_value_borrowed_handles_every_scalar_arm() {
        let doc = "nothing: ~\nratio: 2.5\nhuge: 9007199254740993\ntagged: !custom text\n";
        let root: YamlValue = noyalib::from_str(doc).expect("yaml");

        assert_eq!(
            yaml_to_value(root.get("nothing").expect("nothing")),
            Value::Null
        );
        assert_eq!(
            yaml_to_value(root.get("ratio").expect("ratio")),
            Value::Number(2.5)
        );
        // 2^53 + 1 is not exactly representable; the converter documents a
        // 0.0 fallback rather than a silently rounded value.
        assert_eq!(
            yaml_to_value(root.get("huge").expect("huge")),
            Value::Number(0.0)
        );
        let tagged_val =
            yaml_to_value(root.get("tagged").expect("tagged"));
        let (tag, inner) =
            tagged_val.as_tagged().expect("expected tagged");
        assert!(tag.contains("custom"), "tag was {tag:?}");
        assert_eq!(*inner, Value::String("text".into()));
    }

    /// The borrowed converter still handles every variant.
    ///
    /// The mapping loop now moves values through `yaml_into_value`, so
    /// these arms of `yaml_to_value` are only reached through a `Tagged`
    /// wrapper or a nested borrow. They must keep working, and without a
    /// direct test they had silently gone uncovered.
    #[test]
    fn yaml_to_value_borrowed_handles_compound_values() {
        let doc = "list:\n  - one\n  - two\nmap:\n  k: v\n";
        let root: YamlValue = noyalib::from_str(doc).expect("yaml");
        let list = root.get("list").expect("list");
        let map = root.get("map").expect("map");

        let list_val = yaml_to_value(list);
        let items = list_val.as_array().expect("expected array");
        assert_eq!(items.len(), 2);
        assert_eq!(items[0], Value::String("one".into()));

        let map_val = yaml_to_value(map);
        let obj = map_val.as_object().expect("expected object");
        assert_eq!(obj.get("k"), Some(&Value::String("v".into())));
    }

    /// Moving and borrowing produce identical results.
    #[test]
    fn yaml_into_value_matches_yaml_to_value() {
        let doc =
            "s: text\nn: 3\nb: true\nlist:\n  - a\nmap:\n  x: y\n";
        let root: YamlValue = noyalib::from_str(doc).expect("yaml");
        let m = root.as_mapping().cloned().unwrap();
        for (k, v) in m {
            let borrowed = yaml_to_value(&v);
            let moved = yaml_into_value(v);
            assert_eq!(borrowed, moved, "key {k}");
        }
    }

    /// The README install snippet must name the crate's own version.
    ///
    /// REPO-STANDARD §1 asks for docs verified against the manifest. This
    /// README said `0.0.6` through two releases; nothing checked it.
    #[test]
    fn readme_install_snippet_matches_cargo_version() {
        let readme = include_str!("../README.md");
        let version = env!("CARGO_PKG_VERSION");
        let expected = format!("frontmatter-gen = \"{version}\"");
        assert!(
            readme.contains(&expected),
            "README does not contain `{expected}`; update the install \
             snippet when bumping Cargo.toml"
        );
    }

    use super::*;
    use std::f64::consts::PI;

    // Helper for creating a test `Frontmatter`
    fn create_test_frontmatter() -> Frontmatter {
        let mut fm = Frontmatter::new();
        let _ = fm.insert(
            "title".to_string(),
            Value::String("Test".to_string()),
        );
        let _ = fm.insert("number".to_string(), Value::Number(PI));
        let _ = fm.insert("boolean".to_string(), Value::Boolean(true));
        let _ = fm.insert(
            "array".to_string(),
            Value::Array(vec![
                Value::Number(1.0),
                Value::Number(2.0),
                Value::Number(3.0),
            ]),
        );
        fm
    }

    /// Tests for `ParseOptions::default`.
    mod parse_options_tests {
        use super::*;

        #[test]
        fn test_parse_options_default() {
            let default_options = ParseOptions::default();
            assert_eq!(default_options.max_depth, MAX_NESTING_DEPTH);
            assert_eq!(default_options.max_keys, MAX_KEYS);
            assert!(default_options.validate);
        }
    }

    /// Tests for `optimise_string`.
    mod optimise_string_tests {
        use super::*;

        #[test]
        fn test_optimise_string_short() {
            let short_string = "short";
            let optimised = optimise_string(short_string);
            assert_eq!(optimised, short_string);
            assert_eq!(optimised.capacity(), short_string.len());
        }

        #[test]
        fn test_optimise_string_long() {
            let long_string = "a".repeat(SMALL_STRING_SIZE + 1);
            let optimised = optimise_string(&long_string);
            assert_eq!(optimised, long_string);
            assert!(optimised.capacity() >= long_string.len());
        }
    }

    /// Tests for parsing functions.
    mod parsing_tests {
        use super::*;

        #[test]
        fn test_parse_yaml() {
            let yaml = "key: value";
            let result = parse_yaml(yaml);
            assert!(result.is_ok());
            let fm = result.unwrap();
            assert_eq!(
                fm.0.get("key"),
                Some(&Value::String("value".to_string()))
            );
        }

        #[test]
        fn test_parse_toml() {
            let toml = "key = \"value\"";
            let result = parse_toml(toml);
            assert!(result.is_ok());
            let fm = result.unwrap();
            assert_eq!(
                fm.0.get("key"),
                Some(&Value::String("value".to_string()))
            );
        }

        #[test]
        fn test_parse_json() {
            let json = r#"{"key": "value"}"#;
            let result = parse_json(json);
            assert!(result.is_ok());
            let fm = result.unwrap();
            assert_eq!(
                fm.0.get("key"),
                Some(&Value::String("value".to_string()))
            );
        }

        #[test]
        fn test_parse_with_options() {
            let yaml = "key: value";
            let result = parse_with_options(yaml, Format::Yaml, None);
            assert!(result.is_ok());
            let fm = result.unwrap();
            assert_eq!(
                fm.0.get("key"),
                Some(&Value::String("value".to_string()))
            );
        }

        #[test]
        fn test_parse_with_invalid_format() {
            let yaml = "key: value";
            let result =
                parse_with_options(yaml, Format::Unsupported, None);
            assert!(matches!(result, Err(Error::ConversionError(_))));
        }
    }

    /// Tests for serialization functions.
    mod serialization_tests {
        use super::*;

        #[test]
        fn test_to_yaml() {
            let fm = create_test_frontmatter();
            let yaml = to_yaml(&fm).unwrap();
            assert!(yaml.contains("title:"));
            assert!(yaml.contains("Test"));
        }

        #[test]
        fn test_to_toml() {
            let fm = create_test_frontmatter();
            let toml = to_toml(&fm).unwrap();
            assert!(toml.contains("title = \"Test\""));
        }

        #[test]
        fn test_to_json_optimised() {
            let fm = create_test_frontmatter();
            let json = to_json_optimised(&fm).unwrap();
            assert!(json.contains("\"title\":\"Test\""));
        }

        #[test]
        fn test_to_string() {
            let fm = create_test_frontmatter();

            // Test YAML format
            let yaml = to_string(&fm, Format::Yaml).unwrap();
            assert!(yaml.contains("title: Test"));

            // Test TOML format
            let toml = to_string(&fm, Format::Toml).unwrap();
            assert!(toml.contains("title = \"Test\""));

            // Test JSON format
            let json = to_string(&fm, Format::Json).unwrap();
            assert!(json.contains("\"title\":\"Test\""));
        }
    }

    /// Tests for validation functions.
    mod validation_tests {
        use super::*;

        #[test]
        fn test_validate_frontmatter_valid() {
            let fm = create_test_frontmatter();
            assert!(validate_frontmatter(
                &fm,
                MAX_NESTING_DEPTH,
                MAX_KEYS
            )
            .is_ok());
        }

        #[test]
        fn test_validate_frontmatter_exceeds_keys() {
            let mut fm = Frontmatter::new();
            for i in 0..MAX_KEYS + 1 {
                let _ = fm.insert(
                    i.to_string(),
                    Value::String("value".to_string()),
                );
            }
            let result =
                validate_frontmatter(&fm, MAX_NESTING_DEPTH, MAX_KEYS);
            assert!(matches!(
                result,
                Err(Error::ContentTooLarge { .. })
            ));
        }

        #[test]
        fn test_validate_frontmatter_exceeds_depth() {
            let mut current = Value::Null;
            for _ in 0..MAX_NESTING_DEPTH + 1 {
                current = Value::Object(Box::new(Frontmatter(
                    [("nested".to_string(), current)]
                        .into_iter()
                        .collect(),
                )));
            }
            let mut fm = Frontmatter::new();
            let _ = fm.insert("deep".to_string(), current);
            let result =
                validate_frontmatter(&fm, MAX_NESTING_DEPTH, MAX_KEYS);
            assert!(matches!(
                result,
                Err(Error::NestingTooDeep { .. })
            ));
        }
    }

    /// Tests for utility functions.
    mod utility_tests {
        use super::*;

        #[test]
        fn test_estimate_json_size() {
            let fm = create_test_frontmatter();
            let estimated_size = estimate_json_size(&fm);
            let actual_json = to_string(&fm, Format::Json).unwrap();
            assert!(estimated_size >= actual_json.len());
        }

        #[test]
        fn test_check_depth_valid() {
            let value =
                Value::Object(Box::new(create_test_frontmatter()));
            assert!(check_depth(&value, 1, MAX_NESTING_DEPTH).is_ok());
        }

        #[test]
        fn test_check_depth_exceeds() {
            let mut current = Value::Null;
            for _ in 0..MAX_NESTING_DEPTH + 1 {
                current = Value::Object(Box::new(Frontmatter(
                    [("nested".to_string(), current)]
                        .into_iter()
                        .collect(),
                )));
            }
            let result = check_depth(&current, 1, MAX_NESTING_DEPTH);
            assert!(matches!(
                result,
                Err(Error::NestingTooDeep { .. })
            ));
        }
    }
}

#[cfg(test)]
mod exhaustive_parser_tests {
    //! One case per branch of the three value converters and per
    //! failure mode of the entry points.
    //!
    //! `yaml_to_value`, `toml_to_value` and `json_to_value` are three
    //! parallel matches over three foreign enums. They are exactly the
    //! shape where one arm drifts from the others and nothing notices:
    //! the output is still a `Value`, just the wrong one.

    use super::*;

    fn get<'a>(fm: &'a Frontmatter, key: &str) -> &'a Value {
        fm.get(key).unwrap()
    }

    #[test]
    fn toml_converts_every_scalar_and_container_kind() {
        let raw = "\
s = \"text\"
i = 7
f = 2.5
b = true
when = 2024-01-02
arr = [1, 2]
nested = [[1], [2]]

[table]
inner = \"x\"
";
        let fm = parse_toml(raw).expect("valid TOML");
        assert_eq!(get(&fm, "s"), &Value::String("text".into()));
        assert_eq!(get(&fm, "i"), &Value::Number(7.0));
        assert_eq!(get(&fm, "f"), &Value::Number(2.5));
        assert_eq!(get(&fm, "b"), &Value::Boolean(true));
        // Datetimes render as strings; TOML's type is not in `Value`.
        assert!(
            matches!(get(&fm, "when"), Value::String(s) if s.contains("2024"))
        );
        assert_eq!(get(&fm, "arr").array_len(), Some(2));
        assert_eq!(get(&fm, "nested").array_len(), Some(2));
        let table = get(&fm, "table")
            .as_object()
            .expect("table should convert to an object");
        assert_eq!(
            table.get("inner"),
            Some(&Value::String("x".into()))
        );
    }

    #[test]
    fn json_converts_every_scalar_and_container_kind() {
        let raw = r#"{
            "null": null,
            "bool": false,
            "int": 7,
            "float": 2.5,
            "big": 12345678901234567890,
            "str": "text",
            "arr": [1, "a", null],
            "obj": {"inner": {"deep": 1}}
        }"#;
        let fm = parse_json(raw).expect("valid JSON");
        assert_eq!(get(&fm, "null"), &Value::Null);
        assert_eq!(get(&fm, "bool"), &Value::Boolean(false));
        assert_eq!(get(&fm, "int"), &Value::Number(7.0));
        assert_eq!(get(&fm, "float"), &Value::Number(2.5));
        // Beyond i64: the f64 fallback, not the integer path.
        assert!(
            matches!(get(&fm, "big"), Value::Number(n) if *n > 1e19)
        );
        assert_eq!(get(&fm, "str"), &Value::String("text".into()));
        assert_eq!(get(&fm, "arr").array_len(), Some(3));
        let obj = get(&fm, "obj").as_object().expect("nested object");
        assert!(matches!(obj.get("inner"), Some(Value::Object(_))));
    }

    #[test]
    fn yaml_converts_every_scalar_and_container_kind() {
        let raw = "\
s: text
i: 7
f: 2.5
b: true
n: null
arr:
  - 1
  - a
obj:
  inner: x
";
        let fm = parse_yaml(raw).expect("valid YAML");
        assert_eq!(get(&fm, "s"), &Value::String("text".into()));
        assert_eq!(get(&fm, "i"), &Value::Number(7.0));
        assert_eq!(get(&fm, "b"), &Value::Boolean(true));
        assert_eq!(get(&fm, "n"), &Value::Null);
        assert_eq!(get(&fm, "arr").array_len(), Some(2));
        assert!(matches!(get(&fm, "obj"), Value::Object(_)));
    }

    #[test]
    fn the_three_converters_agree_on_the_same_document() {
        let yaml =
            parse_yaml("a: 1\nb: text\nc: true\n").expect("yaml");
        let toml = parse_toml("a = 1\nb = \"text\"\nc = true\n")
            .expect("toml");
        let json = parse_json(r#"{"a": 1, "b": "text", "c": true}"#)
            .expect("json");
        for key in ["a", "b", "c"] {
            assert_eq!(
                get(&yaml, key),
                get(&toml, key),
                "yaml vs toml on {key}"
            );
            assert_eq!(
                get(&yaml, key),
                get(&json, key),
                "yaml vs json on {key}"
            );
        }
    }

    #[test]
    fn format_mismatch_is_rejected_before_parsing() {
        let err =
            parse_with_options("no equals here", Format::Toml, None)
                .expect_err("TOML without '=' is rejected");
        assert!(
            matches!(err, Error::ConversionError(ref m) if m.contains("TOML"))
        );

        let err =
            parse_with_options("not an object", Format::Json, None)
                .expect_err("JSON not starting with '{' is rejected");
        assert!(
            matches!(err, Error::ConversionError(ref m) if m.contains("JSON"))
        );
    }

    #[test]
    fn validation_limits_are_enforced_only_when_asked() {
        let deep = r#"{"a": {"b": {"c": {"d": 1}}}}"#;

        // Off by default for this entry point: the document parses.
        let options = ParseOptions {
            max_depth: 2,
            max_keys: 100,
            validate: false,
        };
        assert!(parse_with_options(deep, Format::Json, Some(options))
            .is_ok());

        let options = ParseOptions {
            max_depth: 2,
            max_keys: 100,
            validate: true,
        };
        let err = parse_with_options(deep, Format::Json, Some(options))
            .expect_err("nesting beyond max_depth is rejected");
        assert!(matches!(err, Error::NestingTooDeep { .. }), "{err:?}");

        let wide = r#"{"a": 1, "b": 2, "c": 3}"#;
        let options = ParseOptions {
            max_depth: 10,
            max_keys: 2,
            validate: true,
        };
        assert!(parse_with_options(wide, Format::Json, Some(options))
            .is_err());
    }

    #[test]
    fn round_trips_through_every_format() {
        let fm = parse_json(r#"{"title": "T", "n": 2, "flag": true}"#)
            .expect("json");
        for format in [Format::Yaml, Format::Toml, Format::Json] {
            let text = to_string(&fm, format).expect("serialise");
            let back = parse(&text, format).expect("re-parse");
            assert_eq!(
                back.get("title"),
                Some(&Value::String("T".into())),
                "{format} lost the title"
            );
            assert_eq!(back.get("flag"), Some(&Value::Boolean(true)));
        }
    }

    #[test]
    fn non_mapping_yaml_and_non_object_json_and_deep_yaml_serialisation(
    ) {
        log::set_max_level(log::LevelFilter::Trace);

        // YAML document starting with `---` in parse_with_options
        let with_delim = parse_with_options(
            "---\ntitle: test\n",
            Format::Yaml,
            None,
        )
        .expect("yaml with ---");
        assert_eq!(
            with_delim.get("title"),
            Some(&Value::String("test".into()))
        );

        // YAML scalar/sequence is rejected as non-mapping
        assert!(matches!(
            parse_yaml("- item1\n- item2\n"),
            Err(Error::ParseError(_))
        ));

        // JSON non-object at parse_json level returns empty Frontmatter
        let empty = parse_json("[1, 2, 3]").expect("json array");
        assert!(empty.is_empty());

        // TOML serialisation error on root Null
        let mut null_fm = Frontmatter::new();
        let _ = null_fm.insert("k".into(), Value::Null);
        assert!(matches!(
            to_toml(&null_fm),
            Err(Error::ConversionError(_))
        ));

        // YAML serialisation error when nesting exceeds noyalib's max_depth
        let mut deep_val = Value::Null;
        for _ in 0..150 {
            deep_val = Value::Array(vec![deep_val]);
        }
        let mut deep_fm = Frontmatter::new();
        let _ = deep_fm.insert("deep".into(), deep_val);
        assert!(matches!(
            to_yaml(&deep_fm),
            Err(Error::ConversionError(_))
        ));
    }

    #[test]
    fn unsupported_format_is_rejected_rather_than_reaching_unreachable()
    {
        // The `unreachable!()` arms downstream are guarded by this
        // check; if it ever stops rejecting, they start panicking.
        let err =
            parse_with_options("anything", Format::Unsupported, None)
                .expect_err("Unsupported must be refused up front");
        assert!(!err.to_string().is_empty());
    }

    #[test]
    fn size_estimates_grow_with_the_document() {
        // The estimate feeds `to_json_optimised`'s buffer reservation.
        // It does not have to be exact, but it must account for every
        // variant: a variant returning 0 would make the reservation
        // useless for documents made of it.
        let empty = Frontmatter::new();
        assert!(estimate_json_size(&empty) >= 2, "at least the braces");

        let mut fm = Frontmatter::new();
        let _ = fm.insert("k".into(), Value::String("value".into()));
        let one = estimate_json_size(&fm);
        let _ = fm.insert("k2".into(), Value::Number(1.0));
        assert!(
            estimate_json_size(&fm) > one,
            "adding a key must grow the estimate"
        );

        for value in [
            Value::Null,
            Value::String("s".into()),
            Value::Number(1.0),
            Value::Boolean(true),
            Value::Array(vec![Value::Null, Value::Number(1.0)]),
            Value::Object(Box::new(Frontmatter::new())),
            Value::Tagged("t".into(), Box::new(Value::Null)),
        ] {
            assert!(
                estimate_value_size(&value) > 0,
                "{value:?} estimated as zero bytes"
            );
        }

        // Nesting is counted through, not truncated at the first level.
        let nested =
            Value::Array(vec![Value::Array(vec![Value::String(
                "deep".into(),
            )])]);
        assert!(
            estimate_value_size(&nested)
                > estimate_value_size(&Value::Array(vec![]))
        );
    }

    #[test]
    fn malformed_input_reports_the_formats_own_error() {
        assert!(parse_yaml("a: [").is_err());
        assert!(parse_toml("a = ").is_err());
        assert!(parse_json("{").is_err());
    }
}