ocpi_tariffs/

json.rs

//! Types and functions for parsing JSON in a flexible and pedantic manner.
pub mod decode;
pub mod parser;
pub(crate) mod schema;
pub(crate) mod walk;
pub mod write;

#[cfg(test)]
mod test_parser;

use std::{
    collections::BTreeMap,
    fmt::{self, Write as _},
    sync::Arc,
};

use tracing::{trace, Level};

use crate::{
    warning::{self, IntoCaveat},
    SmartString, Verdict, WriteSmartString,
};
use parser::ErrorKind;
use parser::{Parser, Span};

#[doc(inline)]
pub use parser::{line_col, Error, ErrorReport, LineCol};
pub(crate) use parser::{parse, RawStr};

const PATH_SEPARATOR: char = '.';
const PATH_ROOT: &str = "$";

/// Return the `json::Element` If the given field exists(`Some`).
/// Otherwise, add a `Warning::FieldRequired` to the set of `Warning`s and return them as an `Err`.
#[doc(hidden)]
#[macro_export]
macro_rules! required_field_or_bail {
    ($elem:expr, $fields:expr, $field_name:literal, $warnings:expr) => {
        match $fields.get($field_name) {
            Some(field_elem) => field_elem,
            None => {
                return $warnings.bail(
                    Warning::FieldRequired {
                        field_name: $field_name.into(),
                    },
                    $elem,
                );
            }
        }
    };
}

/// Return the `json::Element` If the given field exists(`Some`).
/// Otherwise, add a `Warning::FieldRequired` to the set of `Warning`s and return them as an `Err`.
#[doc(hidden)]
#[macro_export]
macro_rules! required_field {
    ($elem:expr, $fields:expr, $field_name:literal, $warnings:expr) => {{
        let field = $fields.get($field_name);

        if field.is_none() {
            $warnings.with_elem(
                Warning::FieldRequired {
                    field_name: $field_name.into(),
                },
                $elem,
            );
        }

        field
    }};
}

/// Return the `Field`s of the given `json::Element` if it's a JSON object.
/// Otherwise, add a `Warning::FieldInvalidType` to the set of `Warning`s and return then as an `Err`.
#[doc(hidden)]
#[macro_export]
macro_rules! expect_object_or_bail {
    ($elem:expr, $warnings:expr) => {
        match $elem.as_object_fields() {
            Some(fields) => fields,
            None => {
                return $warnings.bail(
                    Warning::FieldInvalidType {
                        expected_type: json::ValueKind::Object,
                    },
                    $elem,
                );
            }
        }
    };
}

/// Return the `json::Element`s of the given `json::Element` if it's a JSON array.
/// Otherwise, add a `Warning::FieldInvalidType` to the set of `Warning`s and return then as an `Err`.
#[doc(hidden)]
#[macro_export]
macro_rules! expect_array_or_bail {
    ($elem:expr, $warnings:expr) => {
        match $elem.as_array() {
            Some(fields) => fields,
            None => {
                return $warnings.bail(
                    Warning::FieldInvalidType {
                        expected_type: json::ValueKind::Array,
                    },
                    $elem,
                );
            }
        }
    };
}

/// Return the contents of the given `json::Element` as a `Cow<str>` if it's a JSON string.
/// Otherwise, add a `Warning::FieldInvalidType` to the set of `Warning`s and return then as an `Err`.
///
/// Note: All escapes are decoded and this process may produce warnings.
#[doc(hidden)]
#[macro_export]
macro_rules! expect_string_or_bail {
    ($elem:expr, $warnings:expr) => {{
        use $crate::warning::GatherWarnings as _;

        match $elem.as_raw_str() {
            Some(s) => s.decode_escapes($elem).gather_warnings_into(&mut $warnings),
            None => {
                return $warnings.bail(
                    Warning::FieldInvalidType {
                        expected_type: json::ValueKind::String,
                    },
                    $elem,
                );
            }
        }
    }};
}

/// Get a field by name and fail if it doesn't exist.
///
/// Convert the value of the field to the `$target` type.
#[doc(hidden)]
#[macro_export]
macro_rules! parse_required_or_bail {
    ($elem:expr, $fields:expr, $elem_name:literal, $target:ty, $warnings:expr) => {{
        #[allow(
            unused,
            reason = "the macro uses the import but maybe the outside scope does too."
        )]
        use $crate::json::FromJson;
        use $crate::warning::GatherWarnings as _;

        let elem = $crate::required_field_or_bail!($elem, $fields, $elem_name, $warnings);
        <$target as FromJson>::from_json(elem)?.gather_warnings_into(&mut $warnings)
    }};
}

/// Get a field by name and return `None` if it doesn't exist.
///
/// Convert the value of the field to the `$target` type.
#[doc(hidden)]
#[macro_export]
macro_rules! parse_required {
    ($elem:expr, $fields:expr, $elem_name:literal, $target:ty, $warnings:expr) => {{
        #[allow(
            unused,
            reason = "the macro uses the import but maybe the outside scope does too."
        )]
        use $crate::json::FromJson;
        use $crate::warning::GatherWarnings as _;

        let elem = $crate::required_field!($elem, $fields, $elem_name, $warnings);

        if let Some(elem) = elem {
            let value =
                <$target as FromJson>::from_json(elem)?.gather_warnings_into(&mut $warnings);
            Some(value)
        } else {
            None
        }
    }};
}

/// Get an optional field by name and convert the field value to the `$target` type using the
/// blanket impl `Option<$target>` that can handle `null` JSON values.
#[doc(hidden)]
#[macro_export]
macro_rules! parse_nullable_or_bail {
    ($fields:expr, $elem_name:literal, $target:ty, $warnings:expr) => {{
        #[allow(
            unused,
            reason = "the macro uses the import but maybe the outside scope does too."
        )]
        use $crate::json::FromJson as _;
        use $crate::warning::GatherWarnings as _;

        match $fields.get($elem_name) {
            Some(elem) => Option::<$target>::from_json(elem)?.gather_warnings_into(&mut $warnings),
            None => None,
        }
    }};
}

/// A trait for converting `Element`s to Rust types.
pub(crate) trait FromJson<'elem, 'buf>: Sized {
    type Warning: crate::Warning;

    /// Convert the given `Element` to `Self`.
    fn from_json(elem: &'elem Element<'buf>) -> Verdict<Self, Self::Warning>;
}

/// Implement a `null` aware variant of all types that implement `FromJson`.
///
/// If the value of the `json::Element` is `null` then return a `None`.
impl<'a, 'b, T> FromJson<'a, 'b> for Option<T>
where
    T: FromJson<'a, 'b> + IntoCaveat,
{
    type Warning = T::Warning;

    fn from_json(elem: &'a Element<'b>) -> Verdict<Self, Self::Warning> {
        let value = elem.as_value();

        if value.is_null() {
            Ok(None.into_caveat(warning::Set::new()))
        } else {
            let v = T::from_json(elem)?;
            Ok(v.map(Some))
        }
    }
}

/// A JSON [`Element`] composed of a `Path` and it's [`Value`].
///
/// The `Span` is included so that the [`Element`]'s source `&str` can be acquired from the source JSON if needed.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Element<'buf> {
    /// Used to reference the Element from `Warning`s.
    id: ElemId,

    /// The `Path` to this [`Element`].
    path_node: PathNodeRef<'buf>,

    /// The `Span` of this [`Element`].
    ///
    /// The `Span` defines the range of bytes that delimits this JSON [`Element`].
    span: Span,

    /// The `Value` of this [`Element`].
    value: Value<'buf>,
}

/// A simple integer index used to ID the given [`Element`] within a JSON file.
///
/// The Id is unique until `usize::MAX` [`Element`]s are parsed.
#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq, Ord, PartialOrd)]
pub struct ElemId(usize);

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

impl<'buf> Element<'buf> {
    /// Create a new `Element`.
    fn new(id: ElemId, path: PathNodeRef<'buf>, span: Span, value: Value<'buf>) -> Element<'buf> {
        Element {
            id,
            path_node: path,
            span,
            value,
        }
    }

    /// Return the unique Id for this `Element`.
    pub(crate) const fn id(&self) -> ElemId {
        self.id
    }

    /// Return the `Path` to this `Element`.
    pub fn path(&self) -> PathRef<'buf> {
        PathRef(self.path_node())
    }

    /// Return the `PathNode` to this `Element`.
    pub(crate) fn path_node(&self) -> PathNodeRef<'buf> {
        Arc::clone(&self.path_node)
    }

    /// Return the `Span` of the `Element`'s `&str` is the source JSON.
    pub fn span(&self) -> Span {
        self.span
    }

    /// Return the source JSON `&str` of the entire Object field if the `Element` is an Object.
    /// Otherwise, return the span of the [`Value`].
    ///
    /// In the case of an array like `["one", "two"]`, calling this method on the second `Element`
    /// will return `"two"`.
    ///
    /// In the case of an object like `{"one": 1, "two": 2}`, calling this method on the second
    /// `Element` will return `"\"two\": 2"`.
    ///
    /// # Panics
    ///
    /// If a source JSON is used that this `Element` didn't not originate from there is a chance
    /// that this function will panic.
    pub fn source_json(&self, source_json: &'buf str) -> SourceStr<'buf> {
        if let PathNode::Object { key, .. } = *self.path_node {
            // The span of an objects field starts from the start of the key...
            let span = Span {
                start: key.span().start,
                // ... and ends at the end of the value.
                end: self.span.end,
            };
            let field_str = &source_json
                .get(span.start..span.end)
                .expect("The disconnection between the source JSON and the `Element` will be fixed in a future PR");
            let field = RawStr::from_str(field_str, span);
            let (key, value) = field_str
                .split_once(':')
                .expect("An objects field always contains a delimiting `:`");

            SourceStr::Field { field, key, value }
        } else {
            let span = self.span;
            let s = source_json
                .get(span.start..span.end)
                .expect("The disconnection between the source JSON and the `Element` will be fixed in a future PR");
            SourceStr::Value(RawStr::from_str(s, span))
        }
    }

    /// Return the source JSON `&str` for the [`Value`].
    ///
    /// In the case of an array like `["one", "two"]`, calling this method on the second `Element`
    /// will return `"two"`.
    ///
    /// In the case of an object like `{"one": 1, "two": 2}`, calling this method on the second
    /// `Element` will return `"2"`.
    ///
    /// # Panics
    ///
    /// If a source JSON is used that this `Element` didn't not originate from there is a chance
    /// that this function will panic.
    pub fn source_json_value(&self, source_json: &'buf str) -> &'buf str {
        source_json
            .get(self.span.start..self.span.end)
            .expect("The disconnection between the source JSON and the `Element` will be fixed in a future PR")
    }

    /// Return the `Value` of the `Element`.
    pub(crate) fn value(&self) -> &Value<'buf> {
        &self.value
    }

    /// Return the `&Value`.
    pub(crate) fn as_value(&self) -> &Value<'buf> {
        &self.value
    }

    /// Return `Some(&str)` if the `Value` is a `String`.
    pub(crate) fn as_raw_str(&self) -> Option<&RawStr<'buf>> {
        self.value.as_raw_str()
    }

    /// Return `Some(&[Field])` if the `Value` is a `Object`.
    pub(crate) fn as_object_fields(&self) -> Option<&[Field<'buf>]> {
        self.value.as_object_fields()
    }

    pub(crate) fn as_array(&self) -> Option<&[Element<'buf>]> {
        self.value.as_array()
    }

    pub fn as_number_str(&self) -> Option<&str> {
        self.value.as_number()
    }
}

#[derive(Debug)]
pub enum SourceStr<'buf> {
    /// The source `&str` of the given [`Value`].
    Value(RawStr<'buf>),

    /// The key-value pair of the given [`Element`] where the [`PathNode`] is referring to an object.
    Field {
        /// The entire field as a `&str`. This is the `&str` from the beginning of the key to the end of the value.
        field: RawStr<'buf>,

        /// The key excluding the separating `:`.
        key: &'buf str,

        /// The [`Value`] as `&str`.
        value: &'buf str,
    },
}

impl fmt::Display for SourceStr<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            SourceStr::Value(s) => f.write_str(s.as_raw()),
            SourceStr::Field { field, .. } => f.write_str(field.as_raw()),
        }
    }
}

/// The `SourceStr` can be compared with other strings just like a `String`.
impl PartialEq<&str> for SourceStr<'_> {
    fn eq(&self, other: &&str) -> bool {
        match self {
            SourceStr::Value(s) => s.as_raw() == *other,
            SourceStr::Field { field, .. } => field.as_raw() == *other,
        }
    }
}

/// The `SourceStr` can be compared with other strings just like a `String`.
impl PartialEq<String> for SourceStr<'_> {
    fn eq(&self, other: &String) -> bool {
        self.eq(&&**other)
    }
}

impl PartialOrd for Element<'_> {
    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for Element<'_> {
    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
        self.path_node.cmp(&other.path_node)
    }
}

impl fmt::Display for Element<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{} = {}", self.path_node, self.value)
    }
}

/// A JSON `Object`'s field that upholds the invariant that the `Element`'s `Path` is as `Object`.
#[derive(Clone, Debug, Eq, PartialEq)]
pub(crate) struct Field<'buf>(Element<'buf>);

impl<'buf> Field<'buf> {
    #[expect(
        clippy::unreachable,
        reason = "A Field is created by the parser when the type is an Object."
    )]
    pub(crate) fn key(&self) -> RawStr<'buf> {
        let PathNode::Object { key, .. } = *self.0.path_node else {
            unreachable!();
        };

        key
    }

    /// Consume the `Field` and return the inner `Element`.
    #[expect(dead_code, reason = "pending use in `tariff::lint`")]
    pub(crate) fn into_element(self) -> Element<'buf> {
        self.0
    }

    /// Consume the `Field` and return the inner `Element`.
    pub(crate) fn element(&self) -> &Element<'buf> {
        &self.0
    }
}

/// A JSON `Value` that borrows it's content from the source JSON `&str`.
#[derive(Clone, Debug, Eq, PartialEq)]
pub(crate) enum Value<'buf> {
    /// A `"null"` value.
    Null,

    /// A `"true"` value.
    True,

    /// A `"false"` value.
    False,

    /// The value of the `String` has the quotes trimmed.
    String(RawStr<'buf>),

    /// A JSON `Number` in string format.
    ///
    /// The string is not guaranteed to be a valid number. Only that it's not a `null`, `bool` or `string` value.
    /// Convert the string into the number format you want.
    Number(&'buf str),

    /// A JSON `Array` parsed into a `Vec` of `Elements`.
    ///
    /// The inner `Element`'s path also encodes the index.
    /// E.g. `$.elements.2`: This path refers to third OCPI tariff element.
    Array(Vec<Element<'buf>>),

    /// A JSON `Object` where each of the fields are parsed into a `Vec` of `Elements`.
    ///
    /// The inner `Element`'s path encodes the fields key.
    /// E.g. `$.elements.2.restrictions` This path refers to the `restrictions` `Object`
    /// of the third OCPI tariff element.
    Object(Vec<Field<'buf>>),
}

impl<'buf> Value<'buf> {
    pub(crate) fn kind(&self) -> ValueKind {
        match self {
            Value::Null => ValueKind::Null,
            Value::True | Value::False => ValueKind::Bool,
            Value::String(_) => ValueKind::String,
            Value::Number(_) => ValueKind::Number,
            Value::Array(_) => ValueKind::Array,
            Value::Object(_) => ValueKind::Object,
        }
    }

    pub(crate) fn is_null(&self) -> bool {
        matches!(self, Value::Null)
    }

    /// Return true if the `Value` can't contain child elements.
    pub(crate) fn is_scalar(&self) -> bool {
        matches!(
            self,
            Value::Null | Value::True | Value::False | Value::String(_) | Value::Number(_)
        )
    }

    pub(crate) fn as_array(&self) -> Option<&[Element<'buf>]> {
        match self {
            Value::Array(elems) => Some(elems),
            _ => None,
        }
    }

    pub(crate) fn as_number(&self) -> Option<&str> {
        match self {
            Value::Number(s) => Some(s),
            _ => None,
        }
    }

    /// Return `Some(&str)` if the `Value` is a `String`.
    pub(crate) fn as_raw_str(&self) -> Option<&RawStr<'buf>> {
        match self {
            Value::String(s) => Some(s),
            _ => None,
        }
    }

    /// Return `Some(&[Field])` if the `Value` is a `Object`.
    pub(crate) fn as_object_fields(&self) -> Option<&[Field<'buf>]> {
        match self {
            Value::Object(fields) => Some(fields),
            _ => None,
        }
    }
}

impl fmt::Display for Value<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Null => write!(f, "null"),
            Self::True => write!(f, "true"),
            Self::False => write!(f, "false"),
            Self::String(s) => write!(f, "{s}"),
            Self::Number(s) => write!(f, "{s}"),
            Self::Array(..) => f.write_str("[...]"),
            Self::Object(..) => f.write_str("{...}"),
        }
    }
}

/// A light-weight type identity for a JSON `Value`'s content.
#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
pub enum ValueKind {
    Null,
    Bool,
    Number,
    String,
    Array,
    Object,
}

impl fmt::Display for ValueKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ValueKind::Null => write!(f, "null"),
            ValueKind::Bool => write!(f, "bool"),
            ValueKind::Number => write!(f, "number"),
            ValueKind::String => write!(f, "string"),
            ValueKind::Array => write!(f, "array"),
            ValueKind::Object => write!(f, "object"),
        }
    }
}

/// Used to distinguish the type of compound object.
///
/// This is used to track which type of object an `Element` is in when parsing.
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
pub(crate) enum ObjectKind {
    Object,
    Array,
}

pub type RawMap<'buf> = BTreeMap<RawStr<'buf>, Element<'buf>>;
pub type RawRefMap<'a, 'buf> = BTreeMap<RawStr<'buf>, &'a Element<'buf>>;

#[expect(dead_code, reason = "pending use in `tariff::lint`")]
pub(crate) trait FieldsIntoExt<'buf> {
    fn into_map(self) -> RawMap<'buf>;
}

pub(crate) trait FieldsAsExt<'buf> {
    fn as_raw_map(&self) -> RawRefMap<'_, 'buf>;
    fn find_field(&self, key: &str) -> Option<&Field<'buf>>;
}

impl<'buf> FieldsIntoExt<'buf> for Vec<Field<'buf>> {
    fn into_map(self) -> RawMap<'buf> {
        self.into_iter()
            .map(|field| (field.key(), field.into_element()))
            .collect()
    }
}

impl<'buf> FieldsAsExt<'buf> for Vec<Field<'buf>> {
    fn as_raw_map(&self) -> RawRefMap<'_, 'buf> {
        self.iter()
            .map(|field| (field.key(), field.element()))
            .collect()
    }

    fn find_field(&self, key: &str) -> Option<&Field<'buf>> {
        self.iter().find(|field| field.key().as_raw() == key)
    }
}

impl<'buf> FieldsAsExt<'buf> for [Field<'buf>] {
    fn as_raw_map(&self) -> RawRefMap<'_, 'buf> {
        self.iter()
            .map(|field| (field.key(), field.element()))
            .collect()
    }

    fn find_field(&self, key: &str) -> Option<&Field<'buf>> {
        self.iter().find(|field| field.key().as_raw() == key)
    }
}

/// A collection of paths that were unexpected according to the schema used while parsing the JSON
/// for an OCPI object.
#[derive(Clone, Debug)]
pub struct UnexpectedFields<'buf>(Vec<PathNodeRef<'buf>>);

impl fmt::Display for UnexpectedFields<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if f.alternate() {
            // Print each path on a newline.
            f.write_str("[\n")?;
            for entry in &self.0 {
                writeln!(f, "\t\"{entry}\",")?;
            }
            f.write_str("]\n")?;
        } else {
            // Print all paths on a single line.
            f.write_char('[')?;
            for entry in &self.0 {
                write!(f, "{entry},")?;
            }
            f.write_char(']')?;
        }

        Ok(())
    }
}

impl<'buf> UnexpectedFields<'buf> {
    /// Create an empty `UnexpectedFields` collection.
    pub(crate) fn empty() -> Self {
        Self(vec![])
    }

    /// Create a collection of `UnexpectedFields` from a `Vec`
    pub(crate) fn from_vec(v: Vec<PathNodeRef<'buf>>) -> Self {
        Self(v)
    }

    /// Return the field paths as a `Vec` of `String`s.
    pub fn to_strings(&self) -> Vec<String> {
        self.0.iter().map(ToString::to_string).collect()
    }

    /// Return the field paths as a `Vec` of `String`s.
    pub fn into_strings(self) -> Vec<String> {
        self.0.into_iter().map(|path| path.to_string()).collect()
    }

    /// Return true if the list of unexpected fields is empty.
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// Return the number of unexpected fields.
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// Return an Iterator over the unexpected fields.
    pub fn iter<'a>(&'a self) -> UnexpectedFieldsIter<'a, 'buf> {
        UnexpectedFieldsIter(self.0.iter())
    }
}

impl<'buf> IntoIterator for UnexpectedFields<'buf> {
    type Item = PathRef<'buf>;

    type IntoIter = UnexpectedFieldsIntoIter<'buf>;

    fn into_iter(self) -> Self::IntoIter {
        UnexpectedFieldsIntoIter(self.0.into_iter())
    }
}

pub struct UnexpectedFieldsIntoIter<'buf>(std::vec::IntoIter<PathNodeRef<'buf>>);

impl<'buf> Iterator for UnexpectedFieldsIntoIter<'buf> {
    type Item = PathRef<'buf>;

    fn next(&mut self) -> Option<Self::Item> {
        let path_node = self.0.next()?;

        Some(PathRef(path_node))
    }
}

impl<'a, 'buf> IntoIterator for &'a UnexpectedFields<'buf> {
    type Item = PathRef<'buf>;

    type IntoIter = UnexpectedFieldsIter<'a, 'buf>;

    fn into_iter(self) -> Self::IntoIter {
        self.iter()
    }
}

/// An `Iterator` over each unexpected field as a `PathRef`.
pub struct UnexpectedFieldsIter<'a, 'buf>(std::slice::Iter<'a, PathNodeRef<'buf>>);

impl<'buf> Iterator for UnexpectedFieldsIter<'_, 'buf> {
    type Item = PathRef<'buf>;

    fn next(&mut self) -> Option<Self::Item> {
        let path_node = self.0.next()?;

        Some(PathRef(Arc::clone(path_node)))
    }
}

/// A path to a JSON `Element` where the path components are borrowed from the source JSON `&str`.
///
/// The Display impl outputs strings like:
///
/// - `$` The root is represented by a dollar.
/// - `$.object_key` Dots separate the path elements.
/// - `$.object_key.2` Arrays are represented as integers.
pub struct PathRef<'buf>(PathNodeRef<'buf>);

impl fmt::Debug for PathRef<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{self}")
    }
}

impl<'buf> PathRef<'buf> {
    /// Return an [`Iterator`] over the components of this path.
    pub fn components(&self) -> PathComponents<'buf> {
        PathComponents(PathIter::new(Arc::clone(&self.0)))
    }

    pub fn to_smart_string(&self) -> SmartString {
        self.0.to_smart_string()
    }
}

/// An [`Iterator`] over the components of a path.
pub struct PathComponents<'buf>(PathIter<'buf>);

impl<'buf> Iterator for PathComponents<'buf> {
    type Item = PathComponent<'buf>;

    fn next(&mut self) -> Option<Self::Item> {
        let path_node = self.0.next()?;
        Some(PathComponent(path_node))
    }
}

/// The `PathRef` can be compared with other strings just like a `String`.
impl PartialEq<&str> for PathRef<'_> {
    fn eq(&self, other: &&str) -> bool {
        match_path_node(&self.0, other, |_| false)
    }
}

/// The `PathRef` can be compared with other strings just like a `String`.
impl PartialEq<String> for PathRef<'_> {
    fn eq(&self, other: &String) -> bool {
        match_path_node(&self.0, other, |_| false)
    }
}

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

#[cfg(test)]
mod test_path_node_matches_str {
    use std::sync::Arc;

    use crate::test;

    use super::PathNode;

    #[test]
    fn should_match_path() {
        test::setup();

        let root = Arc::new(PathNode::Root);
        let path_a = Arc::new(PathNode::Array {
            parent: Arc::clone(&root),
            index: 1,
        });
        let path_b = Arc::new(PathNode::Object {
            parent: Arc::clone(&path_a),
            key: r#""name""#.into(),
        });
        let path_c = PathNode::Object {
            parent: Arc::clone(&path_b),
            key: r#""gene""#.into(),
        };

        assert_eq!(*root, "$");
        assert_eq!(*path_a, "$.1");
        assert_eq!(*path_b, "$.1.name");
        assert_eq!(path_c, "$.1.name.gene");
    }
}

/// The path to a JSON `Element`.
pub(crate) type PathNodeRef<'buf> = Arc<PathNode<'buf>>;

/// A single node of a complete path.
///
/// Path's are structured as a linked list from the leaf of the path back to the root through the parents.
///
/// The Display impl of the `Path` outputs strings like:
///
/// - `$` The root is represented by a dollar.
/// - `$.object_key` Dots separate the path elements.
/// - `$.object_key.2` Arrays are represented as integers.
#[derive(Clone, Debug, Default, Eq, PartialEq, Ord, PartialOrd)]
pub(crate) enum PathNode<'buf> {
    /// The root of the JSON `Element` tree.
    #[default]
    Root,
    /// An `Array` element referenced by index.
    Array {
        parent: PathNodeRef<'buf>,
        index: usize,
    },
    /// An `Object` field referenced be key value.
    Object {
        parent: PathNodeRef<'buf>,
        key: RawStr<'buf>,
    },
}

/// A lightweight enum used to indicate the kind of component being visited when using the
/// [`PathComponents`] [`Iterator`].
pub enum PathNodeKind {
    /// The root of the JSON `Element` tree.
    Root,
    /// An `Array` element referenced by index.
    Array,
    /// An `Object` field referenced be key value.
    Object,
}

/// A path to a JSON `Element` where the path components are heap allocated and so do not require
/// a lifetime back to the source JSON `&str`.
///
/// The Display impl outputs strings like:
///
/// - `$` The root is represented by a dollar.
/// - `$.object_key` Dots separate the path elements.
/// - `$.object_key.2` Arrays are represented as integers.
#[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
pub struct Path(Vec<PathPiece>);

impl Path {
    /// Create a root `Path`.
    const fn root() -> Self {
        Self(vec![])
    }

    /// Create an `Path` by iterating over a [`PathNode`].
    fn from_node(path: PathNodeRef<'_>) -> Self {
        let paths: Vec<_> = PathIter::new(path).collect();

        let pieces = paths
            .into_iter()
            .rev()
            .filter_map(|path_node| match *path_node {
                PathNode::Root => None,
                PathNode::Array { index, .. } => Some(PathPiece::Array(index)),
                PathNode::Object { key, .. } => Some(PathPiece::Object(key.to_string())),
            })
            .collect();

        Self(pieces)
    }
}

/// The `Path` can be compared with other strings just like a `String`.
impl PartialEq<&str> for Path {
    fn eq(&self, other: &&str) -> bool {
        match_path(self, other)
    }
}

/// The `Path` can be compared with other strings just like a `String`.
impl PartialEq<String> for Path {
    fn eq(&self, other: &String) -> bool {
        match_path(self, other)
    }
}

impl fmt::Display for Path {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let iter = self.0.iter();

        write!(f, "$")?;

        for path in iter {
            write!(f, ".{path}")?;
        }

        Ok(())
    }
}

/// A piece/component of a [`Path`].
///
/// The `PathComponent` name is already taken and this type is private.
#[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
enum PathPiece {
    /// An `Array` element referenced by index.
    Array(usize),
    /// An `Object` field referenced be key value.
    Object(String),
}

impl fmt::Display for PathPiece {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            PathPiece::Array(index) => write!(f, "{index}"),
            PathPiece::Object(key) => write!(f, "{key}"),
        }
    }
}

/// A single component of a [`PathRef`].
pub struct PathComponent<'buf>(PathNodeRef<'buf>);

impl PathComponent<'_> {
    /// Return the kind of component this is.
    pub fn kind(&self) -> PathNodeKind {
        match *self.0 {
            PathNode::Root => PathNodeKind::Root,
            PathNode::Array { .. } => PathNodeKind::Array,
            PathNode::Object { .. } => PathNodeKind::Object,
        }
    }
}

impl fmt::Display for PathComponent<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self.0 {
            PathNode::Root => f.write_str(PATH_ROOT),
            PathNode::Array { index, .. } => write!(f, "{index}"),
            PathNode::Object { key, .. } => write!(f, "{key}"),
        }
    }
}

impl WriteSmartString for PathComponent<'_> {
    fn write_smart(&self, s: &mut SmartString) -> fmt::Result {
        match *self.0 {
            PathNode::Root => {
                s.push_str(PATH_ROOT);
                Ok(())
            }
            PathNode::Array { index, .. } => write!(s, "{index}"),
            PathNode::Object { key, .. } => write!(s, "{key}"),
        }
    }
}

impl fmt::Display for PathNode<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let paths: Vec<_> = PathIter::new(Arc::new(self.clone())).collect();
        let mut iter = paths.into_iter().rev();

        if f.alternate() {
            // Print out each path element as a debugging tab-stop.
            for path in iter {
                match *path {
                    PathNode::Root => f.write_str("")?,
                    PathNode::Array { .. } | PathNode::Object { .. } => f.write_str("...|")?,
                }
            }
        } else {
            if let Some(path) = iter.next() {
                write!(f, "{}", PathComponent(path))?;
            }

            for path in iter {
                write!(f, ".{}", PathComponent(path))?;
            }
        }
        Ok(())
    }
}

impl<'buf> PathNode<'buf> {
    /// Returns true if the `Path` refers to the root.
    pub(crate) fn is_root(&self) -> bool {
        matches!(self, PathNode::Root)
    }

    /// Returns true if the `Path` refers to an `Array`.
    pub(crate) fn is_array(&self) -> bool {
        matches!(self, PathNode::Array { .. })
    }

    /// Return a key as `Some(&str)` if the `Path` refers to an `Object`.
    pub(crate) fn as_object_key(&self) -> Option<&RawStr<'buf>> {
        match self {
            PathNode::Object { key, .. } => Some(key),
            PathNode::Root | PathNode::Array { .. } => None,
        }
    }

    pub(crate) fn to_smart_string(&self) -> SmartString {
        let mut s = SmartString::new();
        self.write_smart(&mut s)
            .expect("Unable to write string: out of memory");
        s
    }
}

impl WriteSmartString for PathNode<'_> {
    fn write_smart(&self, s: &mut SmartString) -> fmt::Result {
        let paths: Vec<_> = PathIter::new(Arc::new(self.clone())).collect();
        let mut iter = paths.into_iter().rev();

        if let Some(path) = iter.next() {
            write!(s, "{}", PathComponent(path))?;
        }

        for path in iter {
            write!(s, ".{}", PathComponent(path))?;
        }

        Ok(())
    }
}

/// Return true if the given `PathNode` matches the given `&str`.
///
/// If the `skip` function returns true, that path component is skipped.
/// The `skip` function allows this single function to implement comparisons between `PathNode` and `&str`;
/// and comparisons between `PathNode` and `PathGlob`.
fn match_path_node<F>(path: &PathNode<'_>, s: &str, mut skip: F) -> bool
where
    F: FnMut(&str) -> bool,
{
    let mut parts = s.rsplit(PATH_SEPARATOR);
    let mut paths_iter = PathIter::new(Arc::new(path.clone()));

    loop {
        let node_segment = paths_iter.next();
        let str_segment = parts.next();

        let (node_segment, str_segment) = match (node_segment, str_segment) {
            // If we have exhausted both iterators then the `&str` is equal to the path.
            (None, None) => return true,
            // If either of the iters are a different size, then they don't match.
            (None, Some(_)) | (Some(_), None) => return false,
            // If both iters have another item, continue on to try match them.
            (Some(a), Some(b)) => (a, b),
        };

        // If the skip function says to skip a path segment, then continue to the next segment.
        if skip(str_segment) {
            continue;
        }

        let yip = match *node_segment {
            PathNode::Root => str_segment == PATH_ROOT,
            PathNode::Array { index, .. } => {
                let Ok(b) = str_segment.parse::<usize>() else {
                    return false;
                };

                index == b
            }
            PathNode::Object { key, .. } => key.as_raw() == str_segment,
        };

        // Return false on the first mismatch.
        if !yip {
            return false;
        }
    }
}

/// Return true if the given `Path` matches the given `&str`.
fn match_path(path: &Path, s: &str) -> bool {
    let mut parts = s.split(PATH_SEPARATOR);
    let mut paths_iter = path.0.iter();

    let Some(str_segment) = parts.next() else {
        return false;
    };

    // The root path segment is not explicitly stored in a `Path` so we just match the first
    // `str` segment to the expected `$` nomenclature.
    if str_segment != PATH_ROOT {
        return false;
    }

    loop {
        let node_segment = paths_iter.next();
        let str_segment = parts.next();

        let (node_segment, str_segment) = match (node_segment, str_segment) {
            // If we have exhausted both iterators then the `&str` is equal to the path.
            (None, None) => return true,
            // If either of the iters are a different size, then they don't match.
            (None, Some(_)) | (Some(_), None) => return false,
            // If both iters have another item, continue on to try match them.
            (Some(a), Some(b)) => (a, b),
        };

        let yip = match node_segment {
            PathPiece::Array(index) => {
                let Ok(b) = str_segment.parse::<usize>() else {
                    return false;
                };

                *index == b
            }
            PathPiece::Object(key) => key == str_segment,
        };

        // Return false on the first mismatch.
        if !yip {
            return false;
        }
    }
}

impl PartialEq<&str> for PathNode<'_> {
    fn eq(&self, other: &&str) -> bool {
        match_path_node(self, other, |_| false)
    }
}

impl PartialEq<String> for PathNode<'_> {
    fn eq(&self, other: &String) -> bool {
        match_path_node(self, other, |_| false)
    }
}

/// Traverse a `Path` from the leaf to the root.
struct PathIter<'buf> {
    /// The root has been reached.
    complete: bool,
    /// The current path node to introspect when `Iterator::next` is called.
    path: PathNodeRef<'buf>,
}

impl<'buf> PathIter<'buf> {
    /// Create a new `PathIter` from a leaf node.
    fn new(path: PathNodeRef<'buf>) -> Self {
        Self {
            complete: false,
            path,
        }
    }
}

impl<'buf> Iterator for PathIter<'buf> {
    type Item = PathNodeRef<'buf>;

    fn next(&mut self) -> Option<Self::Item> {
        if self.complete {
            return None;
        }

        match &*self.path {
            PathNode::Root => {
                // The iteration is complete once we've arrived at the root node.
                self.complete = true;
                Some(Arc::clone(&self.path))
            }
            PathNode::Array { parent, .. } | PathNode::Object { parent, .. } => {
                let next = Arc::clone(&self.path);
                self.path = Arc::clone(parent);
                Some(next)
            }
        }
    }
}

/// Display the expectation stack for debugging
struct DisplayExpectStack<'a>(&'a [schema::Expect]);

impl fmt::Display for DisplayExpectStack<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut iter = self.0.iter().rev();
        let last = iter.next();

        // Use the `~` to represent a schema stack.
        f.write_str("~")?;

        for _ in iter {
            f.write_str("...~")?;
        }

        if let Some(exp) = last {
            match exp {
                schema::Expect::Scalar => f.write_str("~")?,
                schema::Expect::Array(element) => match &**element {
                    schema::Element::Scalar => f.write_str("~")?,
                    schema::Element::Array(element) => write!(f, "[{element:?}]")?,
                    schema::Element::Object(fields) => {
                        write!(f, "[{{{:}}}])", DisplayExpectFields(&**fields))?;
                    }
                },
                schema::Expect::Object(fields) => {
                    write!(f, "{{{:}}}", DisplayExpectFields(&**fields))?;
                }
                schema::Expect::UnmatchedScalar => write!(f, "unmatched(scalar)")?,
                schema::Expect::UnmatchedArray => write!(f, "unmatched(array)")?,
                schema::Expect::UnmatchedObject => write!(f, "unmatched(object)")?,
                schema::Expect::OutOfSchema => write!(f, "no_schema")?,
            }
        }

        Ok(())
    }
}

/// Display the fields of a schema expect stack level.
struct DisplayExpectFields<'a, V>(&'a BTreeMap<&'a str, V>);

impl<V> fmt::Display for DisplayExpectFields<'_, V> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        const MAX_FIELDS: usize = 8;

        let mut count = 0;
        let mut iter = self.0.keys().peekable();

        loop {
            if count >= MAX_FIELDS {
                f.write_str("...")?;
                break;
            }

            let Some(field) = iter.next() else {
                break;
            };

            count += 1;
            write!(f, "{field}")?;

            let Some(_) = iter.peek() else {
                break;
            };

            f.write_str(", ")?;
        }

        Ok(())
    }
}

#[derive(Debug)]
struct UnbalancedExpectStack;

impl fmt::Display for UnbalancedExpectStack {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("unbalanced expectation stack")
    }
}

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

/// Parse the JSON into a [`ParseReport`] checking the parsed [`Element`]s names against the given
/// [`schema`] and reporting fields that are unexpected in the [`ParseReport::unexpected_fields`].
pub(crate) fn parse_with_schema<'buf>(
    json: &'buf str,
    schema: &schema::Element,
) -> Result<ParseReport<'buf>, Error> {
    let parser = Parser::new(json);
    let mut unexpected_fields = vec![];
    // The current node of the schema is the last element of this `Vec`.
    let mut expectation_stack = vec![schema.to_expectation()];

    for event in parser {
        match event? {
            parser::Event::Open { kind, parent_path } => {
                // Take the schema expectation off the stack.
                // This is simpler than taking a `&mut` to the last element.
                let Some(expectation) = expectation_stack.pop() else {
                    return Err(ErrorKind::Internal(Box::new(UnbalancedExpectStack))
                        .into_partial_error_without_token()
                        .with_root_path());
                };

                if tracing::enabled!(Level::DEBUG) {
                    match kind {
                        ObjectKind::Array => {
                            trace!("{parent_path} [ {}", DisplayExpectStack(&expectation_stack));
                        }
                        ObjectKind::Object => trace!(
                            "{parent_path} {{ {}",
                            DisplayExpectStack(&expectation_stack)
                        ),
                    }
                }

                match expectation {
                    schema::Expect::Array(elem) => {
                        // If the opening element is at the root we only care if the element
                        // is an array or not.
                        if parent_path.is_root() {
                            let next = match kind {
                                ObjectKind::Array => schema::Expect::Array(elem),
                                ObjectKind::Object => schema::Expect::UnmatchedArray,
                            };

                            expectation_stack.push(next);
                            trace!("{}", DisplayExpectStack(&expectation_stack));
                            continue;
                        }

                        if !parent_path.is_array() {
                            expectation_stack.push(schema::Expect::UnmatchedArray);
                            trace!("{}", DisplayExpectStack(&expectation_stack));
                            continue;
                        }

                        expectation_stack.push(schema::Expect::Array(Arc::clone(&elem)));
                        // Each array element should match this expectation
                        expectation_stack.push(elem.to_expectation());
                    }
                    schema::Expect::Object(fields) => {
                        // If the opening element is at the root there is no path to inspect.
                        // We only care if the element is an object or not.
                        if parent_path.is_root() {
                            let next = match kind {
                                ObjectKind::Array => schema::Expect::UnmatchedObject,
                                ObjectKind::Object => schema::Expect::Object(fields),
                            };

                            expectation_stack.push(next);
                            trace!("{}", DisplayExpectStack(&expectation_stack));
                            continue;
                        }
                        let Some(key) = parent_path.as_object_key() else {
                            expectation_stack.push(schema::Expect::UnmatchedObject);
                            trace!("{}", DisplayExpectStack(&expectation_stack));
                            continue;
                        };

                        let next = if let Some(elem) = fields.get(key.as_raw()) {
                            open_object(kind, elem.as_ref())
                        } else {
                            unexpected_fields.push(parent_path);
                            schema::Expect::OutOfSchema
                        };

                        expectation_stack.push(schema::Expect::Object(fields));
                        expectation_stack.push(next);
                    }
                    schema::Expect::OutOfSchema => {
                        // If we're already outside of the schema we put that back on the stack
                        // and add a new one for the object that just opened.
                        //
                        // We need to track the object level even though the schema expectations
                        // have been exhausted, as we'll pop these placeholder `OutOfSchema`s
                        // off the stack when the object has closed so we land on the correct
                        // schema again.
                        expectation_stack.push(expectation);
                        expectation_stack.push(schema::Expect::OutOfSchema);
                    }
                    schema::Expect::UnmatchedArray | schema::Expect::UnmatchedObject => {
                        expectation_stack.push(expectation);
                        expectation_stack.push(schema::Expect::OutOfSchema);
                    }
                    _ => {
                        expectation_stack.push(expectation);
                    }
                }

                trace!("{}", DisplayExpectStack(&expectation_stack));
            }
            parser::Event::Element { kind, parent_path } => {
                // Take the schema expectation off the stack.
                // This is simpler than taking a `&mut` to the last element.
                let Some(expectation) = expectation_stack.pop() else {
                    return Err(ErrorKind::Internal(Box::new(UnbalancedExpectStack))
                        .into_partial_error_without_token()
                        .with_root_path());
                };

                // An `Element` of kind `Array` or `Object` means the `Element` is closed
                // and has completed construction. The expectation can remain off the stack.
                if let ValueKind::Array | ValueKind::Object = kind {
                    if tracing::enabled!(Level::DEBUG) {
                        match kind {
                            ValueKind::Array => {
                                trace!(
                                    "{parent_path} ] {}",
                                    DisplayExpectStack(&expectation_stack)
                                );
                            }
                            ValueKind::Object => trace!(
                                "{parent_path} }} {}",
                                DisplayExpectStack(&expectation_stack)
                            ),
                            _ => (),
                        }
                    }
                    continue;
                }

                match expectation {
                    #[expect(
                        clippy::unreachable,
                        reason = "The parser only emits an `Event::Complete` for a scalar object at the root"
                    )]
                    schema::Expect::Object(fields) => match &*parent_path {
                        PathNode::Root => unreachable!(),
                        PathNode::Array { .. } => {
                            expectation_stack.push(schema::Expect::UnmatchedObject);
                        }
                        PathNode::Object { parent, key } => {
                            trace!("{parent:#}.{key}");

                            if !fields.contains_key(key.as_raw()) {
                                unexpected_fields.push(parent_path);
                            }

                            expectation_stack.push(schema::Expect::Object(fields));
                        }
                    },
                    schema::Expect::OutOfSchema => {
                        unexpected_fields.push(parent_path);
                        expectation_stack.push(expectation);
                    }
                    _ => {
                        expectation_stack.push(expectation);
                    }
                }
            }
            parser::Event::Complete(element) => {
                if element.value().is_scalar() {
                    unexpected_fields.push(element.path_node());
                }

                // Parsing the JSON is complete.
                // Return the `Element` and the unexpected fields collected during parsing
                return Ok(ParseReport {
                    element,
                    unexpected_fields: UnexpectedFields::from_vec(unexpected_fields),
                });
            }
        }
    }

    Err(ErrorKind::UnexpectedEOF
        .into_partial_error_without_token()
        .with_root_path())
}

fn open_object(kind: ObjectKind, elem: Option<&Arc<schema::Element>>) -> schema::Expect {
    let Some(schema) = elem else {
        return schema::Expect::OutOfSchema;
    };

    match (kind, &**schema) {
        (ObjectKind::Object | ObjectKind::Array, schema::Element::Scalar) => {
            schema::Expect::UnmatchedScalar
        }
        (ObjectKind::Object, schema::Element::Array(_)) => schema::Expect::UnmatchedArray,
        (ObjectKind::Object, schema::Element::Object(fields)) => {
            schema::Expect::Object(Arc::clone(fields))
        }
        (ObjectKind::Array, schema::Element::Array(element)) => {
            schema::Expect::Array(Arc::clone(element))
        }
        (ObjectKind::Array, schema::Element::Object(_)) => schema::Expect::UnmatchedObject,
    }
}

/// The output of the `parse_with_schema` function where the parsed JSON `Element` is returned
/// along with a list of fields that the schema did not define.
#[derive(Debug)]
pub(crate) struct ParseReport<'buf> {
    /// The root JSON [`Element`].
    pub element: Element<'buf>,

    /// A list of fields that were not expected: The schema did not define them.
    pub unexpected_fields: UnexpectedFields<'buf>,
}

#[cfg(test)]
pub mod test {
    #![allow(clippy::missing_panics_doc, reason = "tests are allowed to panic")]
    #![allow(clippy::panic, reason = "tests are allowed panic")]

    use crate::{json::match_path_node, test::Expectation};

    use super::{
        parser::Span, walk::DepthFirst, ElemId, Element, Field, FieldsAsExt as _, PathNode,
        PathNodeRef, PathRef, RawStr, UnexpectedFields, Value,
    };

    impl<'buf> Element<'buf> {
        /// Consume the `Element` and return only the `Value`.
        pub(crate) fn into_value(self) -> Value<'buf> {
            self.value
        }

        /// Consume the `Element` and return the `Path`, `Span` and `Value` as a tuple.
        pub(crate) fn into_parts(self) -> (ElemId, PathNodeRef<'buf>, Span, Value<'buf>) {
            let Self {
                id,
                path_node: path,
                span,
                value,
            } = self;
            (id, path, span, value)
        }

        pub(crate) fn find_field(&self, key: &str) -> Option<&Field<'buf>> {
            self.as_object_fields()
                .and_then(|fields| fields.find_field(key))
        }
    }

    impl<'buf> Value<'buf> {
        /// Return true if the `Value` is an `Array`.
        pub(crate) fn is_array(&self) -> bool {
            matches!(self, Value::Array(_))
        }

        /// Return true if the `Value` is an `Object`.
        pub(crate) fn is_object(&self) -> bool {
            matches!(self, Value::Object(_))
        }

        pub(crate) fn as_string(&self) -> Option<&RawStr<'buf>> {
            match self {
                Value::String(s) => Some(s),
                _ => None,
            }
        }
    }

    impl<'buf> Field<'buf> {
        pub fn id(&self) -> ElemId {
            self.0.id()
        }

        pub fn into_parts(self) -> (ElemId, PathNodeRef<'buf>, Span, Value<'buf>) {
            self.0.into_parts()
        }
    }

    impl<'buf> UnexpectedFields<'buf> {
        /// The tests need to assert against the contents.
        pub(super) fn into_inner(self) -> Vec<PathNodeRef<'buf>> {
            self.0
        }

        /// Filter off the fields that match the glob.
        fn filter_matches(&mut self, glob: &PathGlob) {
            self.0.retain(|path| !glob.matches(path));
        }
    }

    /// A string based `Path` that can contain glob `*` patterns in place of a literal path element.
    /// The glob means that the path section can be any valid section.
    #[derive(Debug)]
    pub(crate) struct PathGlob(String);

    impl PathGlob {
        /// Return true if this `PathGlob` matches the given `PathNode`.
        pub(crate) fn matches(&self, path: &PathNode<'_>) -> bool {
            const WILDCARD: &str = "*";

            match_path_node(path, &self.0, |s| {
                // If the `PathGlob` segment is a glob, then continue to the next segment.
                s == WILDCARD
            })
        }
    }

    /// The tests need to assert against literal `ElemId`s.
    impl From<usize> for ElemId {
        fn from(value: usize) -> Self {
            Self(value)
        }
    }

    impl<'a> From<&'a str> for PathGlob {
        fn from(s: &'a str) -> Self {
            Self(s.into())
        }
    }

    impl From<String> for PathGlob {
        fn from(s: String) -> Self {
            Self(s)
        }
    }

    impl<'de> serde::Deserialize<'de> for PathGlob {
        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where
            D: ::serde::Deserializer<'de>,
        {
            let s = <String as ::serde::Deserialize>::deserialize(deserializer)?;
            Ok(Self(s))
        }
    }

    /// A map of `Element`s referenced by their unique Id.
    pub struct ElementMap<'a, 'buf>(Vec<&'a Element<'buf>>);

    impl<'a, 'buf> ElementMap<'a, 'buf> {
        /// Create a new `ElementMap` by traversing the `Element` tree from the given node.
        pub fn for_elem(root: &'a Element<'buf>) -> Self {
            // The walker will emit `Element`s ordered by their Id.
            let walker = DepthFirst::new(root);
            Self(walker.collect())
        }

        /// Return the `Element` with the given id.
        pub fn get(&self, id: ElemId) -> &Element<'buf> {
            self.0.get(id.0).map(|e| &**e).unwrap()
        }

        /// Return the `Path` of the `Element` with the given id.
        pub fn path(&self, id: ElemId) -> PathRef<'buf> {
            self.0.get(id.0).map(|elem| elem.path()).unwrap()
        }
    }

    /// The `unexpected_fields` should be empty. If not then panic with a truncated list of the fields.
    #[track_caller]
    pub(crate) fn expect_no_unexpected_fields(
        expect_file_name: &str,
        unexpected_fields: &UnexpectedFields<'_>,
    ) {
        if !unexpected_fields.is_empty() {
            const MAX_FIELD_DISPLAY: usize = 20;

            if unexpected_fields.len() > MAX_FIELD_DISPLAY {
                let truncated_fields = unexpected_fields
                    .iter()
                    .take(MAX_FIELD_DISPLAY)
                    .map(|path| path.to_string())
                    .collect::<Vec<_>>();

                panic!(
                    "The expect file `{expect_file_name}` didn't expect `{}` unexpected fields;\n\
                    displaying the first ({}):\n{}\n... and {} more",
                    unexpected_fields.len(),
                    truncated_fields.len(),
                    truncated_fields.join(",\n"),
                    unexpected_fields.len() - truncated_fields.len(),
                )
            } else {
                panic!(
                    "The expect file `{expect_file_name}` didn't expect `{}` unexpected fields:\n{}",
                    unexpected_fields.len(),
                    unexpected_fields.to_strings().join(",\n")
                )
            };
        }
    }

    /// Compare the `unexpected_fields` to the expected fields globs.
    ///
    /// Panic if there are any fields not expected.
    #[track_caller]
    pub(crate) fn expect_unexpected_fields(
        expect_file_name: &str,
        unexpected_fields: &mut UnexpectedFields<'_>,
        expected: Expectation<Vec<PathGlob>>,
    ) {
        if let Expectation::Present(expectation) = expected {
            let unexpected_fields_expect = expectation.expect_value();

            // Remove any fields that match the expected glob.
            // The remaining fields are truly unexpected.
            for expect_glob in unexpected_fields_expect {
                unexpected_fields.filter_matches(&expect_glob);
            }

            expect_no_unexpected_fields(expect_file_name, unexpected_fields);
        } else {
            expect_no_unexpected_fields(expect_file_name, unexpected_fields);
        }
    }

    #[cfg(test)]
    mod test_path_matches_glob {
        use std::sync::Arc;

        use crate::test;

        use super::{PathGlob, PathNode};

        #[test]
        fn should_match_path() {
            test::setup();

            let root = Arc::new(PathNode::Root);
            let path_a = Arc::new(PathNode::Array {
                parent: Arc::clone(&root),
                index: 1,
            });
            let path_b = Arc::new(PathNode::Object {
                parent: Arc::clone(&path_a),
                key: r#""name""#.into(),
            });
            let path_c = PathNode::Object {
                parent: Arc::clone(&path_b),
                key: r#""gene""#.into(),
            };

            assert!(PathGlob::from("$").matches(&root));
            assert!(PathGlob::from("*").matches(&root));

            assert!(!PathGlob::from("*").matches(&path_a));
            assert!(PathGlob::from("*.*").matches(&path_a));
            assert!(PathGlob::from("$.*").matches(&path_a));
            assert!(PathGlob::from("$.1").matches(&path_a));

            assert!(!PathGlob::from("*").matches(&path_b));
            assert!(!PathGlob::from("*.*").matches(&path_b));
            assert!(PathGlob::from("*.*.*").matches(&path_b));
            assert!(PathGlob::from("$.*.*").matches(&path_b));
            assert!(PathGlob::from("$.1.*").matches(&path_b));
            assert!(PathGlob::from("$.*.name").matches(&path_b));
            assert!(PathGlob::from("$.1.name").matches(&path_b));

            assert!(PathGlob::from("$.1.name.gene").matches(&path_c));
        }
    }
}

#[cfg(test)]
mod test_path {
    use super::{Path, PathPiece};

    #[test]
    fn path_should_cmp_with_str() {
        assert_ne!(Path::root(), "");
        assert_eq!(Path::root(), "$");
        assert_eq!(Path(vec![PathPiece::Object("field_a".into())]), "$.field_a");
        assert_eq!(Path(vec![PathPiece::Array(1)]), "$.1");
        assert_eq!(
            Path(vec![
                PathPiece::Object("field_a".into()),
                PathPiece::Array(1)
            ]),
            "$.field_a.1"
        );
    }

    #[test]
    fn path_should_display() {
        assert_eq!(Path::root().to_string(), "$");
        assert_eq!(
            Path(vec![PathPiece::Object("field_a".into())]).to_string(),
            "$.field_a"
        );
        assert_eq!(Path(vec![PathPiece::Array(1)]).to_string(), "$.1");
        assert_eq!(
            Path(vec![
                PathPiece::Object("field_a".into()),
                PathPiece::Array(1)
            ])
            .to_string(),
            "$.field_a.1"
        );
    }
}

#[cfg(test)]
mod test_parse_with_schema {
    use crate::{json_schema, test};

    use super::{parse_with_schema, ParseReport};

    #[test]
    fn should_report_unexpected_fields_for_root_element() {
        const JSON: &str = "null";

        test::setup();

        let schema = json_schema!({
            "id",
            "currency",
        });

        let report = parse_with_schema(JSON, &schema).unwrap();
        let ParseReport {
            element: _,
            unexpected_fields,
        } = report;

        {
            let [field_a] = unexpected_fields.into_inner().try_into().unwrap();
            assert_eq!(*field_a, "$");
        }
    }

    #[test]
    fn should_report_unexpected_fields_in_flat_object() {
        const JSON: &str = r#"{
    "id": "tariff_id",
    "currency": "EUR",
    "name": "Barry",
    "address": "Barrystown"
}"#;

        test::setup();

        let schema = json_schema!({
            "id",
            "currency",
        });

        let report = parse_with_schema(JSON, &schema).unwrap();
        let ParseReport {
            element: _,
            unexpected_fields,
        } = report;

        {
            let [field_a, field_b] = unexpected_fields.into_inner().try_into().unwrap();
            assert_eq!(*field_a, "$.name");
            assert_eq!(*field_b, "$.address");
        }
    }

    #[test]
    fn should_report_unexpected_fields_in_nested_object() {
        const JSON: &str = r#"{
    "id": "tariff_id",
    "currency": "EUR",
    "owner": {
        "id": "456856",
        "subscription_id": "tedi4568",
        "name": "Barry",
        "address": "Barrystown"
    }
}"#;

        test::setup();

        let schema = json_schema!({
            "id",
            "currency",
            "owner": {
                "id",
                "subscription_id"
            }
        });

        let report = parse_with_schema(JSON, &schema).unwrap();
        let ParseReport {
            element: _,
            unexpected_fields,
        } = report;

        {
            let [field_a, field_b] = unexpected_fields.into_inner().try_into().unwrap();
            assert_eq!(*field_a, "$.owner.name");
            assert_eq!(*field_b, "$.owner.address");
        }
    }

    #[test]
    fn should_parse_nested_object_out_of_schema() {
        const JSON: &str = r#"{
    "id": "tariff_id",
    "owner": {
        "id": "456856",
        "subscription_id": "tedi4568",
        "name": "Barry",
        "address": {
            "city": "Barrystown",
            "street": "Barrysstreet"
        }
    },
    "currency": "EUR",
    "country": "NL"
}"#;

        test::setup();

        let schema = json_schema!({
            "id",
            "currency",
            "owner"
        });

        let report = parse_with_schema(JSON, &schema).unwrap();
        let ParseReport {
            element: _,
            unexpected_fields,
        } = report;

        {
            let [field_a, field_b, field_c, field_d, field_e, field_f] =
                unexpected_fields.into_inner().try_into().unwrap();
            assert_eq!(*field_a, "$.owner.id");
            assert_eq!(*field_b, "$.owner.subscription_id");
            assert_eq!(*field_c, "$.owner.name");
            assert_eq!(*field_d, "$.owner.address.city");
            assert_eq!(*field_e, "$.owner.address.street");
            assert_eq!(*field_f, "$.country");
        }
    }

    #[test]
    fn should_report_unexpected_fields_in_array_with_nested_object() {
        const JSON: &str = r#"{
    "id": "tariff_id",
    "currency": "EUR",
    "elements": [{
        "id": "456856",
        "subscription_id": "tedi4568",
        "name": "Barry",
        "address": "Barrystown"
    }]
}"#;

        test::setup();

        let schema = json_schema!({
            "id",
            "currency",
            "elements": [{
                "id",
                "subscription_id"
            }]
        });

        let report = parse_with_schema(JSON, &schema).unwrap();
        let ParseReport {
            element: _,
            unexpected_fields,
        } = report;

        {
            let [field_a, field_b] = unexpected_fields.into_inner().try_into().unwrap();
            assert_eq!(*field_a, "$.elements.0.name");
            assert_eq!(*field_b, "$.elements.0.address");
        }
    }

    #[test]
    fn should_report_unexpected_fields_in_array_of_nested_objects() {
        const JSON: &str = r#"{
    "id": "tariff_id",
    "currency": "EUR",
    "elements": [
        {
            "id": "456856",
            "subscription_id": "tedi4568",
            "name": "Barry",
            "address": "Barrystown"
        },
        {
            "id": "8746we",
            "subscription_id": "dfr345",
            "name": "Gerry",
            "address": "Gerrystown"
        }
    ]
}"#;

        test::setup();

        let schema = json_schema!({
            "id",
            "currency",
            "elements": [{
                "id",
                "subscription_id"
            }]
        });

        let report = parse_with_schema(JSON, &schema).unwrap();
        let ParseReport {
            element: _,
            unexpected_fields,
        } = report;

        {
            let [field_a, field_b, field_c, field_d] =
                unexpected_fields.into_inner().try_into().unwrap();
            assert_eq!(*field_a, "$.elements.0.name");
            assert_eq!(*field_b, "$.elements.0.address");
            assert_eq!(*field_c, "$.elements.1.name");
            assert_eq!(*field_d, "$.elements.1.address");
        }
    }

    #[test]
    fn should_report_unexpected_fields_in_array_of_objects() {
        const JSON: &str = r#"[
    {
        "id": "456856",
        "subscription_id": "tedi4568",
        "name": "Barry",
        "address": "Barrystown"
    },
    {
        "id": "8746we",
        "subscription_id": "dfr345",
        "name": "Gerry",
        "address": "Gerrystown"
    }
]"#;

        test::setup();

        let schema = json_schema!([
            {
                "id",
                "subscription_id"
            }
        ]);

        let report = parse_with_schema(JSON, &schema).unwrap();
        let ParseReport {
            element: _,
            unexpected_fields,
        } = report;

        {
            let [field_a, field_b, field_c, field_d] =
                unexpected_fields.into_inner().try_into().unwrap();
            assert_eq!(*field_a, "$.0.name");
            assert_eq!(*field_b, "$.0.address");
            assert_eq!(*field_c, "$.1.name");
            assert_eq!(*field_d, "$.1.address");
        }
    }
}

#[cfg(test)]
mod test_source_json {
    use super::{parse, walk};

    #[test]
    fn should_resolve_to_source_json() {
        const JSON: &str = r#"{
    "name": "David Byrne",
    "hobbies": ["song writing", "thinking about society"]
}"#;

        let element = parse(JSON).unwrap();

        let mut walk = walk::DepthFirst::new(&element);

        let root = walk.next().unwrap();
        assert_eq!(root.source_json(JSON), JSON);

        let field_name = walk.next().unwrap();
        assert_eq!(field_name.source_json(JSON), r#""name": "David Byrne""#);
        assert_eq!(field_name.source_json_value(JSON), r#""David Byrne""#);

        let field_hobbies = walk.next().unwrap();
        assert_eq!(
            field_hobbies.source_json(JSON),
            r#""hobbies": ["song writing", "thinking about society"]"#
        );
        assert_eq!(
            field_hobbies.source_json_value(JSON),
            r#"["song writing", "thinking about society"]"#
        );

        let hobbies_one = walk.next().unwrap();
        assert_eq!(hobbies_one.source_json(JSON), r#""song writing""#);
        assert_eq!(hobbies_one.source_json_value(JSON), r#""song writing""#);

        let hobbies_two = walk.next().unwrap();
        assert_eq!(hobbies_two.source_json(JSON), r#""thinking about society""#);
        assert_eq!(
            hobbies_two.source_json_value(JSON),
            r#""thinking about society""#
        );
    }
}

#[cfg(test)]
mod test_path_node {
    use std::sync::Arc;

    use super::{
        parser::{RawStr, Token, TokenType},
        PathNode, PathNodeRef, Span,
    };

    #[test]
    const fn should_be_send_and_sync() {
        const fn f<T: Send + Sync>() {}

        f::<PathNode<'_>>();
        f::<PathNodeRef<'_>>();
    }

    #[test]
    fn should_display_path() {
        let root = Arc::new(PathNode::Root);
        let path_a = Arc::new(PathNode::Array {
            parent: Arc::clone(&root),
            index: 1,
        });
        let path_b = Arc::new(PathNode::Object {
            parent: Arc::clone(&path_a),
            key: r#""name""#.into(),
        });
        let path_c = Arc::new(PathNode::Object {
            parent: Arc::clone(&path_b),
            key: r#""gene""#.into(),
        });

        assert_eq!(*root, "$");
        assert_eq!(*path_a, "$.1");
        assert_eq!(*path_b, "$.1.name");
        assert_eq!(*path_c, "$.1.name.gene");
    }

    impl<'buf> From<&'buf str> for RawStr<'buf> {
        #[track_caller]
        fn from(s: &'buf str) -> Self {
            RawStr::from_quoted_str(
                s,
                Token {
                    kind: TokenType::String,
                    span: Span::default(),
                },
            )
            .unwrap()
        }
    }
}