amql_engine/

validator.rs

//! Validate annotation files against a schema manifest.

use crate::manifest::{AttrDefinition, AttrType, Manifest, BUILTIN_ATTRS};
use crate::sidecar::SidecarLocator;
use crate::store::{Annotation, AnnotationStore};
use crate::types::RelativePath;
#[cfg(feature = "fs")]
use rayon::prelude::*;
use serde::Serialize;
use serde_json::Value as JsonValue;

/// A validation result.
#[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)]
pub struct ValidationResult {
    pub level: ValidationLevel,
    pub file: RelativePath,
    pub message: String,
}

/// Severity level.
#[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, PartialEq, Eq, Serialize)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum ValidationLevel {
    Error,
    Warning,
}

/// Validate all loaded annotations against the manifest.
/// Parallelizes per-file validation via rayon when the `fs` feature is enabled.
#[must_use = "returns validation results that should be inspected"]
pub fn validate(store: &AnnotationStore, manifest: &Manifest) -> Vec<ValidationResult> {
    let files = store.annotated_files();
    let locator = store.locator();

    let validate_file = |file: &RelativePath| -> Vec<ValidationResult> {
        let annotations = store.get_file_annotations(file);
        let mut results = Vec::new();
        for ann in annotations {
            validate_annotation(ann, manifest, locator, &mut results);
        }
        results
    };

    #[cfg(feature = "fs")]
    {
        files.par_iter().flat_map(validate_file).collect()
    }
    #[cfg(not(feature = "fs"))]
    {
        files.iter().flat_map(validate_file).collect()
    }
}

fn validate_annotation(
    ann: &Annotation,
    manifest: &Manifest,
    locator: &dyn SidecarLocator,
    results: &mut Vec<ValidationResult>,
) {
    let file = locator.sidecar_for(&ann.file);

    // Check tag exists in manifest
    let tag_def = match manifest.tags.get(&*ann.tag) {
        Some(def) => def,
        None => {
            results.push(ValidationResult {
                level: ValidationLevel::Error,
                file: file.clone(),
                message: format!("Unknown tag '{}'", ann.tag),
            });
            // Can't validate attrs for unknown tag
            validate_children(ann, manifest, locator, results);
            return;
        }
    };

    // Check required bind
    if tag_def.require_bind && ann.binding.is_empty() {
        results.push(ValidationResult {
            level: ValidationLevel::Error,
            file: file.clone(),
            message: format!("Tag '{}' requires a 'bind' attribute", ann.tag),
        });
    }

    // Check for unknown attributes
    for attr_name in ann.attrs.keys() {
        if BUILTIN_ATTRS.contains(&attr_name.as_ref()) {
            continue;
        }
        if !tag_def.attrs.contains_key(&**attr_name) {
            results.push(ValidationResult {
                level: ValidationLevel::Warning,
                file: file.clone(),
                message: format!("Unknown attribute '{}' on tag '{}'", attr_name, ann.tag),
            });
        }
    }

    // Check required attributes
    for (attr_name, attr_def) in &tag_def.attrs {
        if attr_def.required && !ann.attrs.contains_key(&**attr_name) {
            results.push(ValidationResult {
                level: ValidationLevel::Error,
                file: file.clone(),
                message: format!(
                    "Missing required attribute '{}' on tag '{}'",
                    attr_name, ann.tag
                ),
            });
        }
    }

    // Type-check attribute values
    for (attr_name, value) in &ann.attrs {
        if BUILTIN_ATTRS.contains(&attr_name.as_ref()) {
            continue;
        }
        if let Some(attr_def) = tag_def.attrs.get(&**attr_name) {
            validate_attr_value(ann, attr_name, value, attr_def, &file, results);
        }
    }

    validate_children(ann, manifest, locator, results);
}

fn validate_attr_value(
    ann: &Annotation,
    attr_name: &str,
    value: &JsonValue,
    attr_def: &AttrDefinition,
    file: &RelativePath,
    results: &mut Vec<ValidationResult>,
) {
    if attr_def.attr_type == AttrType::Enum {
        if let Some(ref values) = attr_def.values {
            let str_val = crate::json_value_to_string(value);
            if !values.iter().any(|v| v == str_val.as_ref()) {
                results.push(ValidationResult {
                    level: ValidationLevel::Error,
                    file: file.clone(),
                    message: format!(
                        "Invalid value '{}' for enum attribute '{}' on tag '{}'. Expected one of: {}",
                        str_val,
                        attr_name,
                        ann.tag,
                        values.join(", ")
                    ),
                });
            }
        }
    }

    if attr_def.attr_type == AttrType::Boolean && !value.is_boolean() {
        results.push(ValidationResult {
            level: ValidationLevel::Warning,
            file: file.clone(),
            message: format!(
                "Attribute '{}' on tag '{}' should be a boolean",
                attr_name, ann.tag
            ),
        });
    }

    if attr_def.attr_type == AttrType::Number && !value.is_number() {
        results.push(ValidationResult {
            level: ValidationLevel::Warning,
            file: file.clone(),
            message: format!(
                "Attribute '{}' on tag '{}' should be a number",
                attr_name, ann.tag
            ),
        });
    }
}

fn validate_children(
    ann: &Annotation,
    manifest: &Manifest,
    locator: &dyn SidecarLocator,
    results: &mut Vec<ValidationResult>,
) {
    for child in &ann.children {
        validate_annotation(child, manifest, locator, results);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::manifest::parse_manifest;
    use crate::store::AnnotationStore;
    use crate::types::{AttrName, Binding, TagName};
    use rustc_hash::FxHashMap;
    use std::path::Path;

    const MANIFEST_XML: &str = r#"
<schema version="1.0">
  <define tag="controller" description="HTTP handler">
    <attr name="method" type="enum" values="GET,POST,PUT,DELETE" required="true" />
    <attr name="path" type="string" required="true" />
  </define>
</schema>
"#;

    fn create_store_with_annotations(
        annotations: Vec<(String, FxHashMap<AttrName, JsonValue>, String)>,
    ) -> AnnotationStore {
        let mut store = AnnotationStore::new(Path::new("/project"));
        let mut by_file: FxHashMap<RelativePath, Vec<Annotation>> = FxHashMap::default();

        for (tag, attrs, file) in annotations {
            let rel = RelativePath::from(file);
            by_file.entry(rel.clone()).or_default().push(Annotation {
                tag: TagName::from(tag),
                attrs,
                binding: Binding::from(""),
                file: rel,
                children: vec![],
            });
        }

        for (file, anns) in by_file {
            store.inject_test_data(&file, anns);
        }

        store
    }

    fn attrs(pairs: &[(&str, JsonValue)]) -> FxHashMap<AttrName, JsonValue> {
        pairs
            .iter()
            .map(|(k, v)| (AttrName::from(*k), v.clone()))
            .collect()
    }

    #[test]
    fn reports_validation_errors() {
        // Arrange
        let manifest = parse_manifest(MANIFEST_XML).unwrap();
        let store = create_store_with_annotations(vec![
            // Unknown tag
            (
                "controllr".to_string(),
                FxHashMap::default(),
                "src/api.ts".to_string(),
            ),
            // Missing required attr (path)
            (
                "controller".to_string(),
                attrs(&[("method", JsonValue::String("POST".to_string()))]),
                "src/handlers.ts".to_string(),
            ),
            // Invalid enum value
            (
                "controller".to_string(),
                attrs(&[
                    ("method", JsonValue::String("PATCH".to_string())),
                    ("path", JsonValue::String("/api".to_string())),
                ]),
                "src/routes.ts".to_string(),
            ),
        ]);

        // Act
        let results = validate(&store, &manifest);

        // Assert
        let unknown_tag = results.iter().find(|r| r.message.contains("Unknown tag"));
        assert!(unknown_tag.is_some(), "should flag unknown tag");
        assert_eq!(
            unknown_tag.unwrap().level,
            ValidationLevel::Error,
            "unknown tag should be error level"
        );
        assert!(
            unknown_tag.unwrap().message.contains("controllr"),
            "should mention the unknown tag name"
        );

        let missing_attr = results
            .iter()
            .find(|r| r.message.contains("Missing required attribute"));
        assert!(missing_attr.is_some(), "should flag missing required attr");
        assert_eq!(
            missing_attr.unwrap().level,
            ValidationLevel::Error,
            "missing attr should be error level"
        );
        assert!(
            missing_attr.unwrap().message.contains("path"),
            "should mention the missing attr name"
        );

        let invalid_enum = results.iter().find(|r| r.message.contains("Invalid value"));
        assert!(invalid_enum.is_some(), "should flag invalid enum value");
        assert_eq!(
            invalid_enum.unwrap().level,
            ValidationLevel::Error,
            "invalid enum should be error level"
        );
        assert!(
            invalid_enum.unwrap().message.contains("PATCH"),
            "should mention the invalid value"
        );
    }

    #[test]
    fn passes_valid_annotations() {
        // Arrange
        let manifest = parse_manifest(MANIFEST_XML).unwrap();
        let store = create_store_with_annotations(vec![
            // Valid annotation with required attrs
            (
                "controller".to_string(),
                attrs(&[
                    ("method", JsonValue::String("POST".to_string())),
                    ("path", JsonValue::String("/api/users".to_string())),
                ]),
                "src/api.ts".to_string(),
            ),
            // Valid annotation with builtin attrs that need no manifest definition
            (
                "controller".to_string(),
                attrs(&[
                    ("method", JsonValue::String("POST".to_string())),
                    ("path", JsonValue::String("/api/teams".to_string())),
                    ("owner", JsonValue::String("@backend".to_string())),
                    ("visibility", JsonValue::String("public".to_string())),
                ]),
                "src/teams.ts".to_string(),
            ),
        ]);

        // Act
        let results = validate(&store, &manifest);

        // Assert
        assert!(
            results.is_empty(),
            "valid annotations should produce no issues"
        );
    }
}