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 _},
    rc::Rc,
    sync::Arc,
};

use tracing::{trace, Level};

use crate::{warning, Verdict};
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 = "$";

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

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

/// 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(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> {
        Rc::clone(&self.path_node)
    }

    /// 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 an 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(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(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 referf 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,
        }
    }

    /// 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,
}

type RawMap<'buf> = BTreeMap<RawStr<'buf>, Element<'buf>>;
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)
    }
}

/// Reference to a range of bytes encompassing a single valid JSON value in the
/// input data.
///
/// Use `RawValue` to store JSON for general transport around the code, as it does not
/// allocate recursively like `Value`.
///
/// A `RawValue` can be used to defer parsing parts of a payload until later,
/// or to avoid parsing it at all in the case that part of the payload just
/// needs to be transferred verbatim into a different output object.
///
/// When serializing, a value of this type will retain its original formatting
/// and will not be minified or pretty-printed.
pub(crate) type RawValue = serde_json::value::RawValue;

/// 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 an 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(Rc::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(Rc::clone(&self.0)))
    }
}

/// 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::rc::Rc;

    use crate::test;

    use super::PathNode;

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

        let root = Rc::new(PathNode::Root);
        let path_a = Rc::new(PathNode::Array {
            parent: Rc::clone(&root),
            index: 1,
        });
        let path_b = Rc::new(PathNode::Object {
            parent: Rc::clone(&path_a),
            key: r#""name""#.into(),
        });
        let path_c = PathNode::Object {
            parent: Rc::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> = Rc<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 light weight 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 an 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 fmt::Display for PathNode<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let paths: Vec<_> = PathIter::new(Rc::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,
        }
    }
}

/// 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(Rc::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(Rc::clone(&self.path))
            }
            PathNode::Array { parent, .. } | PathNode::Object { parent, .. } => {
                let next = Rc::clone(&self.path);
                self.path = Rc::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 keep track of 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 std::borrow::Cow;

    use crate::json::match_path_node;

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

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

        /// 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(crate) fn into_inner(self) -> Vec<PathNodeRef<'buf>> {
            self.0
        }

        /// Filter off the fields that match the glob.
        pub(crate) 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<'a>(Cow<'a, str>);

    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<'a> {
        fn from(s: &'a str) -> Self {
            Self(s.into())
        }
    }

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

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

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

    impl<'a, 'bin> ElementMap<'a, 'bin> {
        /// Create a new `ElementMap` by traversing the `Element` tree from the given node.
        pub fn for_elem(root: &'a Element<'bin>) -> 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<'bin> {
            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<'bin> {
            self.0.get(id.0).map(|elem| elem.path()).unwrap()
        }
    }

    #[cfg(test)]
    mod test_path_matches_glob {
        use std::rc::Rc;

        use crate::test;

        use super::{PathGlob, PathNode};

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

            let root = Rc::new(PathNode::Root);
            let path_a = Rc::new(PathNode::Array {
                parent: Rc::clone(&root),
                index: 1,
            });
            let path_b = Rc::new(PathNode::Object {
                parent: Rc::clone(&path_a),
                key: r#""name""#.into(),
            });
            let path_c = PathNode::Object {
                parent: Rc::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::rc::Rc;

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

    #[test]
    fn should_display_path() {
        let root = Rc::new(PathNode::Root);
        let path_a = Rc::new(PathNode::Array {
            parent: Rc::clone(&root),
            index: 1,
        });
        let path_b = Rc::new(PathNode::Object {
            parent: Rc::clone(&path_a),
            key: r#""name""#.into(),
        });
        let path_c = Rc::new(PathNode::Object {
            parent: Rc::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()
        }
    }
}

#[cfg(test)]
mod test_raw_json {
    use std::{borrow::Cow, rc::Rc};

    use serde::{de::IntoDeserializer, Deserialize};

    use super::{ElemId, Element, PathNode, RawValue, Span, Value, ValueKind};
    use crate::json::decode::unescape_str;

    const TITLE: &str = "همّا مين واحنا مين (Who Are They and Who Are We?)";

    /// Extends a `RawValue` with methods that:
    ///
    /// - Convert a `RawValue` into a `Value`.
    /// - Convert a `RawValue` into a `RawObject`.
    /// - Identifies the type of the JSON value in the `RawValue`.
    pub(crate) trait RawValueExt {
        fn kind(&self) -> ValueKind;

        fn is_string(&self) -> bool;

        /// Return Some(&str) if the value is a JSON string.
        ///
        /// The surrounding quotes will be trimmed from the JSON string.
        fn as_str(&self) -> Option<Cow<'_, str>>;
    }

    impl RawValueExt for RawValue {
        fn kind(&self) -> ValueKind {
            let s = self.get();
            let first = s
                .as_bytes()
                .first()
                .expect("A RawValue can`t be an empty string, it has to contain a JSON value");

            // If whitespace has been removed from a JSON value and we know `serde` has already
            // validated the value. Then the only possible set of chars that can come next `[0-9]` or `[-nt"[{]`.
            //
            // * See: <https://www.json.org/json-en.html>
            //
            // `RawValue` has whitespace stripped so we know the first char is non-whitespace.
            // See: `test_raw_json::should_fail_to_parse_whitespace_only_string_as_json` and
            // `test_raw_json::should_identify_whitespace_surrounded_value_as_array`.
            match *first {
                b'n' => ValueKind::Null,
                b't' | b'f' => ValueKind::Bool,
                b'"' => ValueKind::String,
                b'[' => ValueKind::Array,
                b'{' => ValueKind::Object,
                // A `RawValue` is already known to be valid, the only other possibility for valid JSON
                // is that this is a number
                _ => ValueKind::Number,
            }
        }

        fn is_string(&self) -> bool {
            matches!(self.kind(), ValueKind::String)
        }

        fn as_str(&self) -> Option<Cow<'_, str>> {
            if !self.is_string() {
                return None;
            }

            let s = self.get().trim_matches('"');
            // This is a dummy element used to satisfy the `Warning` system used by the `decode` mod.
            // This hack will not be needed when the pricer uses the new parser.
            let elem = Element {
                id: ElemId(0),
                path_node: Rc::new(PathNode::Root),
                span: Span::default(),
                value: Value::Null,
            };
            let (s, _warnings) = unescape_str(s, &elem).into_parts();
            Some(s)
        }
    }

    #[test]
    fn should_fail_to_parse_whitespace_only_string_as_json() {
        const JSON: &str = "  ";
        let err = serde_json::from_str::<&RawValue>(JSON).unwrap_err();

        assert_eq!(
            err.classify(),
            serde_json::error::Category::Eof,
            "A JSON string can't be empty"
        );

        let err = RawValue::from_string(JSON.to_string()).unwrap_err();

        assert_eq!(
            err.classify(),
            serde_json::error::Category::Eof,
            "A JSON string can't be empty"
        );
    }

    #[test]
    fn should_validate_json_without_allocating_for_each_token() {
        #[derive(Deserialize)]
        struct Song {
            title: String,
        }

        let json = format!(r#"{{ "title": "{TITLE}" }}"#);

        // If you need to simply validate json then you can deserialize to `&RawValue` or
        // `Box<RawValue>`. The given `String` will be parsed as JSON and the bytes returned
        // wrapped in a `RawValue`.
        //
        // `RawValue` asserts that the bytes are valid JSON encoded as UTF8. It is a wrapper
        // around `str` and is therefore unsized.
        //
        // Use a `Box<RawValue>` to store an owned `RawValue`.
        // This will copy/allocate the source bytes to the heap.
        let json: Box<RawValue> = serde_json::from_str(&json).unwrap();

        // If you want to parse the `RawValue` into a Rust data type the `str` must be extracted
        // and the bytes parsed anew. This is the cost of not annotating the source `String`
        // with any structural markers. But parsing JSON is a quick operation compared to
        // recursive allocation.
        let song = Song::deserialize(json.into_deserializer()).unwrap();

        assert_eq!(song.title, TITLE);
    }

    #[test]
    fn should_compare_raw_title_correctly() {
        #[derive(Deserialize)]
        struct Song<'a> {
            #[serde(borrow)]
            title: &'a RawValue,
        }

        let json = format!(r#"{{ "title": "{TITLE}" }}"#);
        let song: Song<'_> = serde_json::from_str(&json).unwrap();

        assert_ne!(
            song.title.get(),
            TITLE,
            "The raw `title` field contains the delimiting '\"' and so is technically not directly equal to the `TITLE` const"
        );

        let title = song.title.as_str().unwrap();

        assert_eq!(
            title, TITLE,
            "When the quotes are removed the `title` field is the same as the `TITLE` const"
        );
    }

    #[test]
    fn should_fail_to_parse_invalid_json() {
        const JSON: &str = r#"{ "title": }"#;

        let err = serde_json::from_str::<Box<RawValue>>(JSON).unwrap_err();

        assert_eq!(
            err.classify(),
            serde_json::error::Category::Syntax,
            "The bytes contained within `RawValue` are valid JSON"
        );
    }

    #[test]
    fn should_parse_raw_json_to_rust_struct() {
        /// A Song where the `title` field is copied onto the heap.
        #[derive(Deserialize)]
        struct Song {
            title: String,
        }

        /// A Song with the original JSON stored alongside on the heap.
        struct SongMessage {
            song: Song,
            original: Box<RawValue>,
        }

        // This is the first heap allocation in this test.
        let json = format!(r#"{{ "title": "{TITLE}" }}"#);

        // This is the second heap allocation in this test.
        let raw_json: Box<RawValue> = serde_json::from_str(&json)
            .expect("Typically we want to parse some JSON from an endpoint first");
        // This (`title: String`) is the third heap allocation in this test.
        let song = Song::deserialize(raw_json.into_deserializer()).expect("And then introspect it");

        let message = SongMessage {
            song,
            original: raw_json,
        };

        assert_eq!(
            message.song.title, TITLE,
            "The title is a normal `String` and so can be directly compared"
        );
        assert_eq!(
            message.original.get(),
            &json,
            "The original has not been modified in any way"
        );
    }

    #[test]
    fn should_parse_borrowed_raw_json_to_rust_struct() {
        /// A Song where the `title` field is borrowed from the original JSON String.
        #[derive(Deserialize)]
        struct Song<'a> {
            title: &'a str,
        }

        /// A Song with the original JSON stored alongside.
        ///
        /// Where all fields are borrowed.
        struct SongMessage<'a> {
            song: Song<'a>,
            original: &'a RawValue,
        }

        // This is the only heap allocation in this test.
        let json = format!(r#"{{ "title": "{TITLE}" }}"#);

        // The JSON bytes contained in the original String are borrowed to the `RawValue(str)`.
        let raw_json: &RawValue = serde_json::from_str(&json)
            .expect("Typically we want to parse some JSON from an endpoint first");
        // The bytes borrowed to the `RawValue` are in turn, borrowed to `Song::title`.
        let song =
            Song::<'_>::deserialize(raw_json.into_deserializer()).expect("And then introspect it");
        // The original JSON bytes are borrowed to the `SongMessage::original` field.
        let message = SongMessage {
            song,
            original: raw_json,
        };

        assert_eq!(
            message.song.title, TITLE,
            "The title is a normal `&str` and so can be directly compared"
        );
        assert_eq!(
            message.original.get(),
            &json,
            "The original has not been modified in any way"
        );
    }

    #[test]
    fn should_deser_number_as_i64() {
        const JSON: &str = "123";
        let json: &RawValue = serde_json::from_str(JSON).unwrap();

        let n = i64::deserialize(json.into_deserializer()).unwrap();

        assert_eq!(n, 123);
    }

    #[test]
    fn should_convert_json_string_to_str() {
        /// A Song where the `title` field is borrowed from the original JSON String.
        #[derive(Deserialize)]
        struct Song<'a> {
            title: &'a str,
        }

        /// A Song with the original JSON stored alongside.
        ///
        /// Where all fields are borrowed.
        struct SongMessage<'a> {
            song: Song<'a>,
            original: &'a RawValue,
        }

        // This is the only heap allocation in this test.
        let json = format!(r#"{{ "title": "{TITLE}" }}"#);

        // The JSON bytes contained in the original String are borrowed to the `RawValue(str)`.
        let raw_json: &RawValue = serde_json::from_str(&json)
            .expect("Typically we want to parse some JSON from an endpoint first");
        // The bytes borrowed to the `RawValue` are in turn, borrowed to `Song::title`.
        let song =
            Song::<'_>::deserialize(raw_json.into_deserializer()).expect("And then introspect it");
        // The original JSON bytes are borrowed to the `SongMessage::original` field.
        let message = SongMessage {
            song,
            original: raw_json,
        };

        assert_eq!(
            message.song.title, TITLE,
            "The title is a normal `&str` and so can be directly compared"
        );
        assert_eq!(
            message.original.get(),
            &json,
            "The original has not been modified in any way"
        );
    }
}