amql_engine/

types.rs

//! Domain newtypes for the AQL engine.
//!
//! Types shared with subcrates (`amql-selector`, `amql-mutate`) are re-exported
//! from those crates to ensure type identity across the dependency graph.
//! Engine-only types are defined here with the `define_newtype_string!` macro.

use serde::{Deserialize, Serialize};
use std::borrow::Borrow;
use std::fmt;
use std::ops::Deref;
use std::path::{Path, PathBuf};

// Re-export shared types from subcrates so the engine and its dependencies
// agree on a single concrete type.
pub use amql_mutate::{NodeKind, RelativePath};
pub use amql_selector::{AttrName, TagName};

macro_rules! define_newtype_string {
    ($name:ident, $doc:expr) => {
        #[doc = $doc]
        #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
        #[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
        #[cfg_attr(feature = "ts", derive(ts_rs::TS))]
        #[cfg_attr(feature = "flow", derive(flowjs_rs::Flow))]
        #[cfg_attr(feature = "ts", ts(export))]
        #[cfg_attr(feature = "flow", flow(export))]
        #[serde(transparent)]
        pub struct $name(String);

        impl Deref for $name {
            type Target = str;
            #[inline]
            fn deref(&self) -> &str {
                &self.0
            }
        }

        impl AsRef<str> for $name {
            #[inline]
            fn as_ref(&self) -> &str {
                &self.0
            }
        }

        impl Borrow<str> for $name {
            #[inline]
            fn borrow(&self) -> &str {
                &self.0
            }
        }

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

        impl From<String> for $name {
            #[inline]
            fn from(s: String) -> Self {
                Self(s)
            }
        }

        impl From<&str> for $name {
            #[inline]
            fn from(s: &str) -> Self {
                Self(s.to_owned())
            }
        }

        impl PartialEq<str> for $name {
            #[inline]
            fn eq(&self, other: &str) -> bool {
                self.0 == other
            }
        }

        impl PartialEq<&str> for $name {
            #[inline]
            fn eq(&self, other: &&str) -> bool {
                self.0 == *other
            }
        }

        impl PartialEq<String> for $name {
            #[inline]
            fn eq(&self, other: &String) -> bool {
                self.0 == *other
            }
        }
    };
}

define_newtype_string!(Binding, "Annotation-to-code join key.");
define_newtype_string!(Scope, "Query scope prefix (directory, file, or empty).");
define_newtype_string!(CodeElementName, "Name of a code construct.");
define_newtype_string!(SelectorStr, "Raw selector string before parsing.");

// ---------------------------------------------------------------------------
// ProjectRoot — hand-written because it wraps PathBuf, not String.
// ---------------------------------------------------------------------------

/// Absolute path to the project root directory.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "flow", derive(flowjs_rs::Flow))]
#[cfg_attr(feature = "ts", ts(export))]
#[cfg_attr(feature = "flow", flow(export))]
#[serde(transparent)]
pub struct ProjectRoot(PathBuf);

impl Deref for ProjectRoot {
    type Target = Path;
    #[inline]
    fn deref(&self) -> &Path {
        &self.0
    }
}

impl AsRef<Path> for ProjectRoot {
    #[inline]
    fn as_ref(&self) -> &Path {
        &self.0
    }
}

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

impl From<PathBuf> for ProjectRoot {
    #[inline]
    fn from(p: PathBuf) -> Self {
        Self(p)
    }
}

impl From<&Path> for ProjectRoot {
    #[inline]
    fn from(p: &Path) -> Self {
        Self(p.to_path_buf())
    }
}

impl ProjectRoot {
    /// Join a relative path onto the project root.
    #[inline]
    pub fn join<P: AsRef<Path>>(&self, path: P) -> PathBuf {
        self.0.join(path)
    }

    /// Convert to the inner `PathBuf`.
    #[inline]
    pub fn to_path_buf(&self) -> PathBuf {
        self.0.clone()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use rustc_hash::FxHashMap;

    #[test]
    fn string_newtype_behavior() {
        // Arrange
        let tag = TagName::from("function");
        let opt_tag: Option<TagName> = Some(TagName::from("function"));
        let mut map = FxHashMap::default();
        map.insert(TagName::from("function"), 42);

        // Act
        let deref_val: &str = &tag;
        let display_val = format!("{tag}");
        let lookup_val = map.get("function");
        let as_deref_val = opt_tag.as_deref();

        // Assert
        assert_eq!(deref_val, "function", "Deref should yield inner str");
        assert_eq!(display_val, "function", "Display should show inner value");
        assert_eq!(tag, "function", "PartialEq<&str> should work");
        assert_eq!(tag, *"function", "PartialEq<str> should work");
        assert_eq!(tag, "function".to_string(), "PartialEq<String> should work");
        assert_eq!(lookup_val, Some(&42), "Borrow<str> should allow map lookup");
        assert_eq!(
            as_deref_val,
            Some("function"),
            "Option::as_deref should work"
        );
    }

    #[test]
    fn project_root_behavior() {
        // Arrange
        let root = ProjectRoot::from(PathBuf::from("/project"));

        // Act
        let joined = root.join("src/main.rs");
        let display_val = format!("{root}");

        // Assert
        assert_eq!(
            joined,
            PathBuf::from("/project/src/main.rs"),
            "join should produce correct path"
        );
        assert_eq!(display_val, "/project", "Display should show path");
    }
}