amql_engine/

declare.rs

//! Type-safe programmatic config declaration, inspired by Babel's `declare()`.
//!
//! Provides a structured alternative to XML `.config/aql.schema` manifests.
//! `declare_config` validates a `DeclareConfig` and produces a `Manifest`.

use crate::error::AqlError;
use crate::manifest::{
    check_schema_version, AttrDefinition, AttrType, ExtractorConfig, Manifest, TagDefinition,
    BUILTIN_ATTRS,
};
use crate::types::{AttrName, TagName};
use rustc_hash::FxHashMap;
use serde::{Deserialize, Serialize};

/// User-facing config for `declare()`. All fields have sensible defaults.
///
/// This is the programmatic equivalent of `.config/aql.schema`:
/// ```ignore
/// declare({
///   version: "1.0",
///   tags: {
///     route: {
///       description: "HTTP route handler",
///       attrs: {
///         method: { type: "enum", values: ["GET", "POST"], required: true },
///         path:   { type: "string", required: true },
///       },
///     },
///   },
///   extractors: [
///     { name: "express", globs: ["src/**/*.ts"] },
///   ],
/// })
/// ```
#[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))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DeclareConfig {
    /// Schema version. Defaults to `"1.0"`.
    #[serde(default = "default_version")]
    pub version: String,

    /// Tag definitions keyed by tag name.
    #[serde(default)]
    #[cfg_attr(
        feature = "ts",
        ts(as = "std::collections::HashMap<String, DeclareTag>")
    )]
    #[cfg_attr(
        feature = "flow",
        flow(as = "std::collections::HashMap<String, DeclareTag>")
    )]
    pub tags: FxHashMap<String, DeclareTag>,

    /// Audience labels (e.g. `{ "product": "Product engineers" }`).
    #[serde(default)]
    #[cfg_attr(feature = "ts", ts(as = "std::collections::HashMap<String, String>"))]
    #[cfg_attr(
        feature = "flow",
        flow(as = "std::collections::HashMap<String, String>")
    )]
    pub audiences: FxHashMap<String, String>,

    /// Visibility labels (e.g. `{ "public": "Stable API" }`).
    #[serde(default)]
    #[cfg_attr(feature = "ts", ts(as = "std::collections::HashMap<String, String>"))]
    #[cfg_attr(
        feature = "flow",
        flow(as = "std::collections::HashMap<String, String>")
    )]
    pub visibilities: FxHashMap<String, String>,

    /// Extractors to enable.
    #[serde(default)]
    pub extractors: Vec<DeclareExtractor>,
}

/// Tag definition within a `DeclareConfig`.
#[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))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DeclareTag {
    /// Human-readable description.
    #[serde(default)]
    pub description: String,

    /// Attribute definitions keyed by attribute name.
    #[serde(default)]
    #[cfg_attr(
        feature = "ts",
        ts(as = "std::collections::HashMap<String, DeclareAttr>")
    )]
    #[cfg_attr(
        feature = "flow",
        flow(as = "std::collections::HashMap<String, DeclareAttr>")
    )]
    pub attrs: FxHashMap<String, DeclareAttr>,

    /// When true, annotations of this tag must have a `bind` attribute.
    #[serde(default, rename = "requireBind")]
    pub require_bind: bool,
}

/// Attribute definition within a `DeclareTag`.
#[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))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DeclareAttr {
    /// Attribute type.
    #[serde(rename = "type")]
    pub attr_type: AttrType,

    /// Whether this attribute is required on every annotation of the parent tag.
    #[serde(default)]
    pub required: bool,

    /// Default value when omitted.
    #[serde(default)]
    pub default: Option<String>,

    /// Allowed values (for `enum` type).
    #[serde(default)]
    pub values: Option<Vec<String>>,

    /// Human-readable description.
    #[serde(default)]
    pub description: Option<String>,

    /// Whether this attribute is deterministically generated from source code.
    #[serde(default = "default_true")]
    pub generated: bool,
}

/// Extractor definition within a `DeclareConfig`.
#[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))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DeclareExtractor {
    /// Extractor name. Built-in names: `express`, `test`, `react`,
    /// `go-http`, `go-structure`, `go_test`, `rust-structure`, `ts-structure`.
    pub name: String,

    /// Shell command for subprocess extractors. Omit for built-in extractors.
    #[serde(default)]
    pub run: Option<String>,

    /// Glob patterns for files this extractor covers.
    #[serde(default)]
    pub globs: Vec<String>,
}

fn default_version() -> String {
    "1.0".to_string()
}

fn default_true() -> bool {
    true
}

/// Validate a `DeclareConfig` and produce a `Manifest`.
///
/// This is the programmatic equivalent of `parse_manifest()` for XML configs.
/// Returns an error if the config contains invalid attribute types or
/// enum attributes without values.
#[must_use = "declaring a config is useless without using the result"]
pub fn declare_config(config: DeclareConfig) -> Result<Manifest, AqlError> {
    check_schema_version(&config.version)?;

    let mut tags = FxHashMap::default();

    for (tag_name, tag_def) in config.tags {
        if tag_name.is_empty() {
            return Err("Tag name cannot be empty".into());
        }
        if BUILTIN_ATTRS.contains(&tag_name.as_str()) {
            return Err(format!("'{tag_name}' is a reserved built-in attribute name").into());
        }

        let mut attrs = FxHashMap::default();
        for (attr_name, attr_def) in tag_def.attrs {
            if attr_name.is_empty() {
                return Err(format!("Attribute name cannot be empty in tag '{tag_name}'").into());
            }

            // Enum type must have values
            if attr_def.attr_type == AttrType::Enum && attr_def.values.is_none() {
                return Err(format!(
                    "Attribute '{attr_name}' on tag '{tag_name}' has type 'enum' but no values"
                )
                .into());
            }

            attrs.insert(
                AttrName::from(attr_name),
                AttrDefinition {
                    attr_type: attr_def.attr_type,
                    required: attr_def.required,
                    default: attr_def.default,
                    values: attr_def.values,
                    description: attr_def.description,
                    generated: attr_def.generated,
                },
            );
        }

        tags.insert(
            TagName::from(tag_name),
            TagDefinition {
                description: tag_def.description,
                attrs,
                require_bind: tag_def.require_bind,
            },
        );
    }

    let extractors = config
        .extractors
        .into_iter()
        .map(|e| ExtractorConfig {
            name: e.name,
            run: e.run.unwrap_or_default(),
            globs: e.globs,
        })
        .collect();

    Ok(Manifest {
        version: config.version,
        tags,
        audiences: config.audiences,
        visibilities: config.visibilities,
        extractors,
    })
}

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

    #[test]
    fn declares_simple_config() {
        // Arrange
        let json = r#"{
            "tags": {
                "route": {
                    "description": "HTTP route",
                    "attrs": {
                        "method": { "type": "enum", "values": ["GET", "POST"], "required": true },
                        "path": { "type": "string", "required": true }
                    },
                    "requireBind": true
                }
            },
            "extractors": [
                { "name": "express", "globs": ["src/**/*.ts"] }
            ]
        }"#;

        // Act
        let config: DeclareConfig = serde_json::from_str(json).unwrap();
        let manifest = declare_config(config).unwrap();

        // Assert
        assert_eq!(manifest.version, "1.0", "should default version to 1.0");
        assert!(manifest.tags.contains_key("route"), "should have route tag");
        let route = manifest.tags.get("route").unwrap();
        assert!(route.require_bind, "route should require bind");
        assert_eq!(
            route.attrs.get("method").unwrap().attr_type,
            AttrType::Enum,
            "method should be enum"
        );
        assert!(
            route.attrs.get("method").unwrap().required,
            "method should be required"
        );
        assert_eq!(manifest.extractors.len(), 1, "should have 1 extractor");
        assert_eq!(
            manifest.extractors[0].name, "express",
            "extractor should be express"
        );
    }

    #[test]
    fn declares_with_defaults() {
        // Arrange
        let config = DeclareConfig {
            version: default_version(),
            tags: FxHashMap::default(),
            audiences: FxHashMap::default(),
            visibilities: FxHashMap::default(),
            extractors: Vec::new(),
        };

        // Act
        let manifest = declare_config(config).unwrap();

        // Assert
        assert_eq!(manifest.version, "1.0", "should use default version");
        assert!(manifest.tags.is_empty(), "should have no tags");
    }

    #[test]
    fn rejects_enum_without_values() {
        // Arrange
        let json = r#"{
            "tags": {
                "route": {
                    "attrs": {
                        "method": { "type": "enum" }
                    }
                }
            }
        }"#;

        // Act
        let config: DeclareConfig = serde_json::from_str(json).unwrap();
        let result = declare_config(config);

        // Assert
        assert!(result.is_err(), "should reject enum without values");
        assert!(
            result.unwrap_err().to_string().contains("no values"),
            "error should mention missing values"
        );
    }

    #[test]
    fn rejects_empty_tag_name() {
        // Arrange
        let mut tags = FxHashMap::default();
        tags.insert(
            String::new(),
            DeclareTag {
                description: String::new(),
                attrs: FxHashMap::default(),
                require_bind: false,
            },
        );

        // Act
        let result = declare_config(DeclareConfig {
            version: default_version(),
            tags,
            audiences: FxHashMap::default(),
            visibilities: FxHashMap::default(),
            extractors: Vec::new(),
        });

        // Assert
        assert!(result.is_err(), "should reject empty tag name");
    }

    #[test]
    fn subprocess_extractor_with_run() {
        // Arrange
        let json = r#"{
            "extractors": [
                { "name": "flask", "run": "python3 extract_flask.py", "globs": ["**/*.py"] }
            ]
        }"#;

        // Act
        let config: DeclareConfig = serde_json::from_str(json).unwrap();
        let manifest = declare_config(config).unwrap();

        // Assert
        assert_eq!(manifest.extractors[0].name, "flask", "extractor name");
        assert_eq!(
            manifest.extractors[0].run, "python3 extract_flask.py",
            "extractor run command"
        );
    }

    #[test]
    fn roundtrip_json() {
        // Arrange — config as JSON
        let json = r#"{
            "version": "2.0",
            "tags": {
                "component": {
                    "description": "React component",
                    "attrs": {
                        "memo": { "type": "boolean" },
                        "displayName": { "type": "string", "description": "Component display name" }
                    }
                }
            },
            "audiences": { "frontend": "Frontend engineers" },
            "visibilities": { "stable": "Stable API" }
        }"#;

        // Act
        let config: DeclareConfig = serde_json::from_str(json).unwrap();
        let manifest = declare_config(config).unwrap();

        // Assert
        assert_eq!(manifest.version, "2.0", "should preserve version");
        assert_eq!(
            manifest.audiences.get("frontend").unwrap(),
            "Frontend engineers",
            "should preserve audiences"
        );
        let component = manifest.tags.get("component").unwrap();
        assert_eq!(
            component.attrs.get("memo").unwrap().attr_type,
            AttrType::Boolean,
            "memo should be boolean"
        );
    }
}