shape/

child_shape.rs

use std::fmt::{Display, Formatter};

use super::Shape;
use super::ShapeCase;
use crate::case_enum::Error;
use crate::helpers::quote_non_identifier;
use crate::location::{Located, Location};
use indexmap::IndexSet;

/// `NamedShapePathKey` represents a single step in a subpath associated with a
/// [`ShapeCase::Name`] shape reference. When pretty-printed, these subpaths are
/// delimited by `.` characters (with `"..."`-quoting as necessary for
/// non-identifier field names), and can be either `::Field` names or array
/// `::Index` values.
///
/// As a special form of catch-all `::Index` value, the step may also be the
/// wildcard `::AnyIndex`, which denotes a union of all the element shapes of an
/// array, or just the given shape if not an array, which is useful to support
/// GraphQL-like array mapping. When pretty-printed, these wildcard keys look
/// like `.*`, and if multiple wildcards are used in a row, they will be
/// coalesced/simplified down to just one logical `.*`.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum NamedShapePathKey {
    // The value shape of an object field with a specific name.
    Field(String),
    // The .** wildcard denoting a union of all object field value shapes,
    // automatically mapped over arrays, and returning the shape itself for
    // non-object, non-array shapes.
    AnyField,

    // The shape of an array element at a specific index.
    Index(usize),
    // The .* wildcard, which represents a union of all array element shapes
    // (ignoring None) or just the shape itself for non-array shapes.
    AnyIndex,

    // Represents the `?` optional chaining operator, which replaces any
    // possibility of `null` in the input shape with `None` (and silences some
    // errors at runtime), but otherwise leaves its input unmodified.
    Question,

    // Represents a hypothetical `!` non-`None` assertion operator, which
    // removes `None` from the input type. If you want to represent a shape that
    // is neither `null` nor `None`/missing, you can use `::Question` to map
    // `null` to `None` and then `::NotNone` to remove `None`, so both `null`
    // and `None` will be removed from the resulting shape. If you apply
    // `::NotNone` to a `None` shape, the result will be the empty union shape
    // `One<>`, which we pretty-print as `Never`, analogous to TypeScript's
    // `never` type. When included in a larger union, this `One<>`/`Never` shape
    // will be removed during union simplification.
    NotNone,
}

impl From<String> for NamedShapePathKey {
    fn from(value: String) -> Self {
        NamedShapePathKey::Field(value)
    }
}

impl From<&str> for NamedShapePathKey {
    fn from(value: &str) -> Self {
        NamedShapePathKey::Field(value.to_string())
    }
}

impl From<usize> for NamedShapePathKey {
    fn from(value: usize) -> Self {
        NamedShapePathKey::Index(value)
    }
}

impl NamedShapePathKey {
    #[must_use]
    pub fn path_to_string(path: &[Located<NamedShapePathKey>]) -> String {
        let mut dotted = String::new();

        for key in path {
            dotted.push_str(&key.value.to_string());
        }

        dotted
    }
}

impl Display for NamedShapePathKey {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            NamedShapePathKey::Field(name) => {
                write!(f, ".{}", quote_non_identifier(name.as_str()))
            }
            NamedShapePathKey::AnyField => {
                write!(f, ".**")
            }
            NamedShapePathKey::Index(index) => {
                write!(f, ".{index}")
            }
            NamedShapePathKey::AnyIndex => {
                write!(f, ".*")
            }
            NamedShapePathKey::Question => {
                write!(f, "?")
            }
            NamedShapePathKey::NotNone => {
                write!(f, "!")
            }
        }
    }
}

impl Shape {
    /// Returns a new [`Shape`] representing the shape of a given subproperty
    /// (field name) of the `self` shape.
    #[must_use]
    pub fn field(&self, field_name: &str, locations: impl IntoIterator<Item = Location>) -> Shape {
        self.child(Located::new(NamedShapePathKey::from(field_name), locations))
    }

    /// Returns a new [`Shape`] representing the union of all field shapes of
    /// object shapes, or just the shape itself for non-object shapes.
    #[must_use]
    pub fn any_field(&self, locations: impl IntoIterator<Item = Location>) -> Shape {
        self.child(Located::new(NamedShapePathKey::AnyField, locations))
    }

    /// Returns a new [`Shape`] representing the shape of a given element of an
    /// array shape.
    #[must_use]
    pub fn item(&self, index: usize, locations: impl IntoIterator<Item = Location>) -> Shape {
        self.child(Located::new(NamedShapePathKey::from(index), locations))
    }

    /// Returns a new [`Shape`] representing the union of all element shapes of
    /// array shapes, or just the shape itself for non-array shapes.
    #[must_use]
    pub fn any_item(&self, locations: impl IntoIterator<Item = Location>) -> Shape {
        self.child(Located::new(NamedShapePathKey::AnyIndex, locations))
    }

    /// Returns a new [`Shape`] representing the input shape with any
    /// possibility of `null` replaced by `None`, but otherwise unchanged. This
    /// models the behavior of a `?` optional chainining operator, which
    /// additionally silences some errors related to missing fields at runtime.
    /// When a [`ShapeCase::Name`] shape reference has a `?` step in its
    /// subpath, that `?` step can be applied to the shape when/if the named
    /// shape is declared/resolved, so the effect of the `?` is not lost.
    #[must_use]
    pub fn question(&self, locations: impl IntoIterator<Item = Location>) -> Shape {
        self.child(Located::new(NamedShapePathKey::Question, locations))
    }

    /// Returns a new [`Shape`] representing the input shape with any
    /// possibility of `None` removed, but otherwise unchanged. This models the
    /// behavior of a hypothetical `!` non-`None` assertion operator. When a
    /// [`ShapeCase::Name`] shape reference has a `!` step in its subpath, that
    /// `!` step can be applied to the shape when/if the named shape is later
    /// declared/resolved, so the effect of the `!` is not lost.
    #[must_use]
    pub fn not_none(&self, locations: impl IntoIterator<Item = Location>) -> Shape {
        self.child(Located::new(NamedShapePathKey::NotNone, locations))
    }

    #[allow(clippy::too_many_lines)]
    #[must_use]
    /// Get a child shape, and add the provided `locations` to it.
    pub fn child(&self, key: Located<NamedShapePathKey>) -> Shape {
        match self.case() {
            ShapeCase::Object { fields, rest, .. } => match &key.value {
                NamedShapePathKey::Field(field_name) => {
                    if let Some(shape) = fields.get(field_name) {
                        shape.with_locations(key.locations)
                    } else {
                        // The rest shape might be ShapeCase::None, so the
                        // ShapeCase::One will simplify to just ShapeCase::None.
                        Shape::one(
                            [
                                rest.with_locations(key.locations.clone()),
                                Shape::none().with_locations(key.locations.clone()),
                            ],
                            key.locations.clone(),
                        )
                    }
                }

                NamedShapePathKey::AnyField => {
                    let mut subshapes = IndexSet::new();
                    for shape in fields.values() {
                        subshapes.insert(shape.clone());
                    }
                    if !rest.is_none() {
                        subshapes.insert(rest.clone());
                    }
                    Shape::one(subshapes, key.locations)
                }

                // Object shapes have no specific indexes.
                NamedShapePathKey::Index(_) => Shape::none().with_locations(key.locations),

                // The .* AnyIndex wildcard is defined to return the input shape if it
                // is not an array that can have indexes.
                NamedShapePathKey::AnyIndex
                // Object shapes are neither null nor None, so ? and ! have no
                // effect.
                | NamedShapePathKey::Question
                | NamedShapePathKey::NotNone => self.clone(),
            },

            ShapeCase::Array { prefix, tail } => match &key.value {
                NamedShapePathKey::Index(index) => {
                    if let Some(shape) = prefix.get(*index) {
                        shape.with_locations(key.locations)
                    } else {
                        // The rest shape might be ShapeCase::None, so the
                        // ShapeCase::One will simplify to just ShapeCase::None.
                        Shape::one(
                            [
                                tail.clone(),
                                Shape::none().with_locations(key.locations.clone()),
                            ],
                            key.locations.clone(),
                        )
                    }
                }

                NamedShapePathKey::AnyIndex => {
                    let mut subshapes = IndexSet::new();
                    for shape in prefix {
                        subshapes.insert(shape.clone());
                    }
                    if !tail.is_none() {
                        subshapes.insert(tail.clone());
                    }
                    Shape::one(subshapes, key.locations)
                }

                NamedShapePathKey::AnyField | NamedShapePathKey::Field(_) => {
                    // Following GraphQL logic, map key over the array and make
                    // a new ShapeCase::Array with the resulting shapes.
                    let new_items = prefix
                        .iter()
                        .map(|shape| shape.child(key.clone()))
                        .collect::<Vec<_>>();

                    let new_rest = tail.child(key.clone());

                    // If we tried mapping a field name over an array, and all
                    // we got back was an empty array, then we can simplify to
                    // ShapeCase::None.
                    if new_rest.is_none() && new_items.iter().all(Shape::is_none) {
                        Shape::none().with_locations(self.locations.clone())
                    } else {
                        Shape::array(new_items, new_rest, self.locations.clone())
                    }
                }

                // Array shapes are neither null nor None, so ? and ! have no effect.
                NamedShapePathKey::Question | NamedShapePathKey::NotNone => self.clone(),
            },

            ShapeCase::String(value) => match &key.value {
                NamedShapePathKey::Index(index) => {
                    if let Some(singleton) = value {
                        if let Some(ch) = singleton.chars().nth(*index) {
                            Shape::string_value(ch.to_string().as_str(), key.locations)
                        } else {
                            Shape::none().with_locations(key.locations)
                        }
                    } else {
                        Shape::one(
                            [
                                Shape::string(self.locations.clone()),
                                Shape::none().with_locations(key.locations.clone()),
                            ],
                            key.locations.clone(),
                        )
                    }
                }

                NamedShapePathKey::AnyIndex => {
                    if let Some(singleton) = value {
                        let mut subshapes = IndexSet::new();
                        for ch in singleton.chars() {
                            subshapes.insert(Shape::string_value(ch.to_string().as_str(), []));
                        }
                        Shape::one(subshapes, key.locations)
                    } else {
                        Shape::string(key.locations)
                    }
                }

                // String shapes have no named fields.
                NamedShapePathKey::Field(_) => Shape::none(),

                // The .** wildcard is defined to return the input shape if it
                // is not an object that can have fields.
                NamedShapePathKey::AnyField
                // String shapes are neither null nor None, so ? and ! have no
                // effect.
                | NamedShapePathKey::Question
                | NamedShapePathKey::NotNone => self.clone(),
            },

            ShapeCase::One(shapes) => {
                let mut subshapes = IndexSet::new();
                for shape in shapes {
                    subshapes.insert(shape.child(key.clone()));
                }
                // Note that if/when subshapes.is_empty(), Shape::one will
                // return an empty One<> union, which is analogous to
                // TypeScript's `never` type, so we pretty-print One<> as
                // "Never" for clarity.
                Shape::one(subshapes, self.locations.clone())
            }

            ShapeCase::All(shapes) => {
                let mut subshapes = IndexSet::new();
                for shape in shapes {
                    // When shape.is_none() and key is ::NotNone,
                    // shape.child(key.clone()) will return the One<>/Never
                    // shape, which will be removed from the intersection during
                    // simplification, as desired, per the rules of intersection
                    // simplification.
                    let subshape = shape.child(key.clone());
                    if matches!(subshape.case.as_ref(), ShapeCase::None) {
                        continue;
                    }
                    subshapes.insert(subshape);
                }
                if subshapes.is_empty() {
                    Shape::none().with_locations(key.locations)
                } else {
                    Shape::all(subshapes, key.locations)
                }
            }

            // For ShapeCase::Name, the subproperties accumulate in the subpath
            // vector, to be evaluated once the named shape has been declared.
            // For all other ShapeCase variants, the child shape can be
            // evaluated immediately.
            ShapeCase::Name(name, subpath) => match &key.value {
                NamedShapePathKey::Field(_) | NamedShapePathKey::Index(_) => {
                    let mut new_subpath = subpath.clone();
                    new_subpath.push(key.clone());
                    Shape::new(
                        ShapeCase::Name(name.clone(), new_subpath),
                        self.locations.clone(),
                    )
                }
                NamedShapePathKey::AnyIndex => {
                    // Disallow multiple consecutive .*.*... wildcards.
                    if subpath
                        .last()
                        .is_some_and(|last| last.value == NamedShapePathKey::AnyIndex)
                    {
                        Shape::new(
                            ShapeCase::Name(name.clone(), subpath.clone()),
                            key.locations,
                        )
                    } else {
                        let mut new_subpath = subpath.clone();
                        new_subpath.push(key.clone());
                        Shape::new(ShapeCase::Name(name.clone(), new_subpath), key.locations)
                    }
                }
                NamedShapePathKey::AnyField => {
                    // Unlike with .*, multiple consecutive .** wildcards do not
                    // collapse to one.
                    let mut new_subpath = subpath.clone();
                    new_subpath.push(key.clone());
                    Shape::new(ShapeCase::Name(name.clone(), new_subpath), key.locations)
                }
                NamedShapePathKey::Question => {
                    // Disallow multiple consecutive field??? operators, as
                    // their effect should be idempotent, and ?? is ambiguous
                    // with the nullish coalescing operator.
                    if subpath
                        .last()
                        .is_some_and(|last| last.value == NamedShapePathKey::Question)
                    {
                        Shape::new(
                            ShapeCase::Name(name.clone(), subpath.clone()),
                            key.locations,
                        )
                    } else {
                        let mut new_subpath = subpath.clone();
                        new_subpath.push(key.clone());
                        Shape::new(ShapeCase::Name(name.clone(), new_subpath), key.locations)
                    }
                }
                NamedShapePathKey::NotNone => {
                    // Disallow multiple consecutive field!!! operators, as
                    // their effect should be idempotent.
                    if subpath
                        .last()
                        .is_some_and(|last| last.value == NamedShapePathKey::NotNone)
                    {
                        Shape::new(
                            ShapeCase::Name(name.clone(), subpath.clone()),
                            key.locations,
                        )
                    } else {
                        let mut new_subpath = subpath.clone();
                        new_subpath.push(key.clone());
                        Shape::new(ShapeCase::Name(name.clone(), new_subpath), key.locations)
                    }
                }
            },

            // ShapeCase::Error allows access to subproperty shapes of its
            // partial field.
            ShapeCase::Error(Error { partial, .. }) => partial
                .as_ref()
                .map_or(Shape::none(), |shape| shape.child(key.clone())),

            ShapeCase::Null => match &key.value {
                // Null shapes have no specific named fields or numeric indexes.
                NamedShapePathKey::Field(_) | NamedShapePathKey::Index(_) => Shape::none(),
                // The .* and .** wildcards are defined to return the input
                // shape if it is not an array or object that can have
                // indexes or fields.
                NamedShapePathKey::AnyIndex
                | NamedShapePathKey::AnyField
                // Null shapes are not None, so ! has no effect.
                | NamedShapePathKey::NotNone => self.clone(),
                // Null shapes are null, so ? replaces them with None.
                NamedShapePathKey::Question => Shape::none().with_locations(key.locations),
            },

            // ShapeCase::None has no subproperties, as it represents the
            // absence of a value, or (to put it another way) the shape of any
            // subproperty of ShapeCase::None is also ShapeCase::None.
            ShapeCase::None => match &key.value {
                NamedShapePathKey::NotNone => Shape::never(key.locations),
                // Any other NamedShapePathKey applied to ShapeCase::None just
                // returns ShapeCase::None.
                _ => self.clone(),
            },

            // ShapeCase::Unknown has no known subproperties, which means any
            // child access also results in ShapeCase::Unknown.
            ShapeCase::Unknown => Shape::unknown(key.locations),

            // Non-String primitive shapes like ::Bool and ::Int and ::Float do
            // not have subproperties, but a wildcard .* subproperty produces
            // the same shape (as if it was the only element of an array).
            _ => match &key.value {
                NamedShapePathKey::AnyIndex
                | NamedShapePathKey::AnyField
                // Primitive shapes are neither null nor None, so ? and ! have
                // no effect.
                | NamedShapePathKey::Question
                | NamedShapePathKey::NotNone => self.clone(),
                _ => Shape::none().with_locations(key.locations),
            },
        }
    }
}