memhooks 0.4.1

Reference parser, resolver, validator, and CLI for filesystem-scoped AI agent memory routing
Documentation
use crate::model::{Entity, RecallQuery};
use crate::parser::{parse_hook, ParseError, ParsedHook};
use ignore::WalkBuilder;
use serde::{Deserialize, Serialize};
use std::collections::HashSet;
use std::path::{Path, PathBuf};

const MEMORY_TYPES: &[&str] = &["world", "experience", "observation"];
const CONNECTION_TYPES: &[&str] = &["semantic", "temporal", "entity", "causal"];

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum Severity {
    Error,
    Warning,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct Diagnostic {
    pub code: String,
    pub severity: Severity,
    pub message: String,
    pub path: PathBuf,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub line: Option<usize>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub column: Option<usize>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub help: Option<String>,
}

impl Diagnostic {
    pub fn error(
        code: &str,
        parsed: &ParsedHook,
        message: impl Into<String>,
        key: Option<&str>,
    ) -> Self {
        Self {
            code: code.into(),
            severity: Severity::Error,
            message: message.into(),
            path: parsed.path.clone(),
            line: key.and_then(|key| parsed.line_for_key(key)),
            column: None,
            help: None,
        }
    }

    pub fn warning(
        code: &str,
        parsed: &ParsedHook,
        message: impl Into<String>,
        key: Option<&str>,
    ) -> Self {
        Self {
            code: code.into(),
            severity: Severity::Warning,
            message: message.into(),
            path: parsed.path.clone(),
            line: key.and_then(|key| parsed.line_for_key(key)),
            column: None,
            help: None,
        }
    }

    pub fn from_parse(error: ParseError) -> Self {
        Self {
            code: "MH000".into(),
            severity: Severity::Error,
            message: error.message,
            path: error.path,
            line: error.line,
            column: error.column,
            help: None,
        }
    }
}

pub fn validate_file(path: &Path) -> Vec<Diagnostic> {
    match parse_hook(path) {
        Ok(parsed) => validate_parsed(&parsed),
        Err(error) => vec![Diagnostic::from_parse(error)],
    }
}

pub fn validate_parsed(parsed: &ParsedHook) -> Vec<Diagnostic> {
    let mut diagnostics = Vec::new();
    let fm = &parsed.frontmatter;

    match fm.schema.as_deref() {
        Some("memhooks/v1") => {}
        Some(other) => diagnostics.push(Diagnostic::error(
            "MH001",
            parsed,
            format!("unsupported schema `{other}`; expected `memhooks/v1`"),
            Some("schema"),
        )),
        None => diagnostics.push(Diagnostic::error(
            "MH001",
            parsed,
            "missing required `schema: memhooks/v1`",
            Some("schema"),
        )),
    }

    for key in fm.extra.keys() {
        diagnostics.push(Diagnostic::warning(
            "MH002",
            parsed,
            format!("unknown top-level field `{key}`"),
            Some(key),
        ));
    }

    validate_enum_list(
        parsed,
        "memory_types",
        &fm.memory_types,
        MEMORY_TYPES,
        &mut diagnostics,
    );
    validate_enum_list(
        parsed,
        "connection_types",
        &fm.connection_types,
        CONNECTION_TYPES,
        &mut diagnostics,
    );

    let mut query_keys = HashSet::new();
    for query in &fm.recall_queries {
        validate_query(parsed, query, &mut diagnostics);
        let key = query.text().trim().to_string();
        if !key.is_empty() && !query_keys.insert(key.clone()) {
            diagnostics.push(Diagnostic::warning(
                "MH010",
                parsed,
                format!("duplicate recall query `{key}`"),
                Some("recall_queries"),
            ));
        }
    }

    let mut entity_keys = HashSet::new();
    for entity in &fm.entities {
        validate_entity(parsed, entity, &mut diagnostics);
        let key = entity.name().trim().to_string();
        if !key.is_empty() && !entity_keys.insert(key.clone()) {
            diagnostics.push(Diagnostic::warning(
                "MH011",
                parsed,
                format!("duplicate top-level entity `{key}`"),
                Some("entities"),
            ));
        }
    }

    let excludes = fm
        .exclude
        .iter()
        .map(|value| value.trim())
        .collect::<HashSet<_>>();
    for query in &fm.recall_queries {
        if excludes.contains(query.text().trim()) {
            diagnostics.push(Diagnostic::warning(
                "MH012",
                parsed,
                format!("recall query is also excluded: `{}`", query.text().trim()),
                Some("exclude"),
            ));
        }
    }

    diagnostics
}

pub fn discover_hooks(path: &Path, all: bool) -> Vec<PathBuf> {
    if path.is_file() {
        return vec![path.to_path_buf()];
    }

    let scan_root = if all {
        crate::resolver::find_root(path)
    } else {
        path.to_path_buf()
    };
    let mut hooks = WalkBuilder::new(&scan_root)
        .hidden(false)
        .git_ignore(true)
        .git_exclude(true)
        .git_global(true)
        .build()
        .filter_map(Result::ok)
        .filter(|entry| entry.file_type().is_some_and(|kind| kind.is_file()))
        .filter(|entry| entry.file_name() == crate::resolver::HOOK_FILENAME)
        .map(|entry| entry.into_path())
        .collect::<Vec<_>>();
    hooks.sort();
    hooks
}

pub fn validate_path(path: &Path, all: bool) -> Vec<Diagnostic> {
    let hooks = discover_hooks(path, all);
    if hooks.is_empty() {
        return vec![Diagnostic {
            code: "MH013".into(),
            severity: Severity::Warning,
            message: "no MEMHOOKS.md files found".into(),
            path: path.to_path_buf(),
            line: None,
            column: None,
            help: Some(
                "run `memhooks validate --all` from a repository containing MemHooks files".into(),
            ),
        }];
    }
    hooks.iter().flat_map(|hook| validate_file(hook)).collect()
}

fn validate_query(parsed: &ParsedHook, query: &RecallQuery, diagnostics: &mut Vec<Diagnostic>) {
    if query.text().trim().is_empty() {
        diagnostics.push(Diagnostic::error(
            "MH003",
            parsed,
            "recall query must not be empty",
            Some("recall_queries"),
        ));
    }

    if let Some(priority) = query.priority() {
        if !(0.0..=1.0).contains(&priority) || !priority.is_finite() {
            diagnostics.push(Diagnostic::error(
                "MH004",
                parsed,
                format!("query priority must be between 0.0 and 1.0; got {priority}"),
                Some("priority"),
            ));
        }
    }

    if let RecallQuery::Structured(value) = query {
        for key in value.extra.keys() {
            diagnostics.push(Diagnostic::warning(
                "MH005",
                parsed,
                format!("unknown recall-query field `{key}`"),
                Some(key),
            ));
        }
        if let Some(when) = &value.when {
            for role in &when.roles {
                if role.trim().is_empty() {
                    diagnostics.push(Diagnostic::error(
                        "MH006",
                        parsed,
                        "role names must not be empty",
                        Some("roles"),
                    ));
                }
            }
            for key in when.extra.keys() {
                diagnostics.push(Diagnostic::warning(
                    "MH007",
                    parsed,
                    format!("unknown routing condition `{key}`"),
                    Some(key),
                ));
            }
        }
        validate_enum_list(
            parsed,
            "memory_types",
            &value.memory_types,
            MEMORY_TYPES,
            diagnostics,
        );
        validate_enum_list(
            parsed,
            "connection_types",
            &value.connection_types,
            CONNECTION_TYPES,
            diagnostics,
        );
        for entity in &value.entities {
            validate_entity(parsed, entity, diagnostics);
        }
    }
}

fn validate_entity(parsed: &ParsedHook, entity: &Entity, diagnostics: &mut Vec<Diagnostic>) {
    if entity.name().trim().is_empty() {
        diagnostics.push(Diagnostic::error(
            "MH008",
            parsed,
            "entity name must not be empty",
            Some("entities"),
        ));
    }
    if let Some(salience) = entity.salience() {
        if !(0.0..=1.0).contains(&salience) || !salience.is_finite() {
            diagnostics.push(Diagnostic::error(
                "MH009",
                parsed,
                format!("entity salience must be between 0.0 and 1.0; got {salience}"),
                Some("salience"),
            ));
        }
    }
    if let Entity::Structured(value) = entity {
        for key in value.extra.keys() {
            diagnostics.push(Diagnostic::warning(
                "MH014",
                parsed,
                format!("unknown entity field `{key}`"),
                Some(key),
            ));
        }
    }
}

fn validate_enum_list(
    parsed: &ParsedHook,
    field: &str,
    values: &[String],
    allowed: &[&str],
    diagnostics: &mut Vec<Diagnostic>,
) {
    for value in values {
        if !allowed.contains(&value.as_str()) {
            diagnostics.push(Diagnostic::error(
                "MH015",
                parsed,
                format!(
                    "invalid {field} value `{value}`; expected one of {}",
                    allowed.join(", ")
                ),
                Some(field),
            ));
        }
    }
}