@lamentis/naome 1.2.0 → 1.3.0

package/crates/naome-core/src/quality/structure/config.rs

@@ -0,0 +1,89 @@
+use std::fs;
+use std::path::Path;
+
+use crate::models::NaomeError;
+
+use super::adapters::{
+    apply_structure_adapters, detected_structure_adapter_ids, validate_structure_adapter_ids,
+};
+use crate::quality::config_support::validate_ready_schema;
+
+use super::model::RepositoryStructureConfig;
+
+const CONFIG_RELATIVE_PATH: &str = ".naome/repository-structure.json";
+
+pub fn structure_config_relative_path() -> &'static str {
+    CONFIG_RELATIVE_PATH
+}
+
+pub fn read_structure_config(
+    root: &Path,
+    paths: &[String],
+) -> Result<RepositoryStructureConfig, NaomeError> {
+    let path = root.join(CONFIG_RELATIVE_PATH);
+    let config = if path.is_file() {
+        serde_json::from_str(&fs::read_to_string(path)?)?
+    } else {
+        generated_structure_config(paths)
+    };
+    validate_structure_config(&config)?;
+    apply_structure_adapters(config)
+}
+
+pub fn write_default_structure_config_if_missing(
+    root: &Path,
+    paths: &[String],
+) -> Result<bool, NaomeError> {
+    let path = root.join(CONFIG_RELATIVE_PATH);
+    if path.exists() {
+        return Ok(false);
+    }
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)?;
+    }
+    let content = serde_json::to_string_pretty(&generated_structure_config(paths))?;
+    fs::write(path, format!("{content}\n"))?;
+    Ok(true)
+}
+
+fn generated_structure_config(paths: &[String]) -> RepositoryStructureConfig {
+    let mut config = RepositoryStructureConfig::default();
+    config.enabled_adapters = detected_structure_adapter_ids(paths);
+    config
+}
+
+fn validate_structure_config(config: &RepositoryStructureConfig) -> Result<(), NaomeError> {
+    validate_ready_schema(
+        CONFIG_RELATIVE_PATH,
+        &config.schema,
+        "naome.repository-structure.v1",
+        config.version,
+        &config.status,
+    )?;
+    validate_structure_adapter_ids(&config.enabled_adapters)?;
+    if config.limits.max_directory_files == 0 {
+        return Err(NaomeError::new(
+            ".naome/repository-structure.json maxDirectoryFiles must be greater than 0.",
+        ));
+    }
+    if config.limits.max_path_depth == 0 {
+        return Err(NaomeError::new(
+            ".naome/repository-structure.json maxPathDepth must be greater than 0.",
+        ));
+    }
+    for rule in &config.directory_role_rules {
+        if rule.id.trim().is_empty() || rule.paths.is_empty() {
+            return Err(NaomeError::new(
+                ".naome/repository-structure.json directoryRoleRules require id and paths.",
+            ));
+        }
+    }
+    for rule in &config.layer_rules {
+        if rule.id.trim().is_empty() || rule.paths.is_empty() || rule.layer.trim().is_empty() {
+            return Err(NaomeError::new(
+                ".naome/repository-structure.json layerRules require id, paths, and layer.",
+            ));
+        }
+    }
+    Ok(())
+}

package/crates/naome-core/src/quality/structure/defaults.rs

@@ -0,0 +1,107 @@
+use super::model::{RepositoryStructureConfig, StructureLimits};
+
+pub fn default_structure_config() -> RepositoryStructureConfig {
+    RepositoryStructureConfig {
+        schema: "naome.repository-structure.v1".to_string(),
+        version: 1,
+        status: "ready".to_string(),
+        enabled_adapters: Vec::new(),
+        source_roots: string_list(DEFAULT_SOURCE_ROOTS),
+        test_roots: string_list(DEFAULT_TEST_ROOTS),
+        docs_roots: string_list(DEFAULT_DOCS_ROOTS),
+        generated_roots: string_list(DEFAULT_GENERATED_ROOTS),
+        artifact_roots: string_list(DEFAULT_ARTIFACT_ROOTS),
+        module_roots: string_list(DEFAULT_MODULE_ROOTS),
+        allowed_root_files: string_list(DEFAULT_ALLOWED_ROOT_FILES),
+        directory_role_rules: Vec::new(),
+        layer_rules: Vec::new(),
+        ignored_paths: string_list(DEFAULT_IGNORED_PATHS),
+        disabled_checks: Vec::new(),
+        changed_code_policy: default_changed_policy(),
+        debt_policy: default_debt_policy(),
+        limits: StructureLimits::default(),
+    }
+}
+
+pub fn default_changed_policy() -> String {
+    "block".to_string()
+}
+
+pub fn default_debt_policy() -> String {
+    "report".to_string()
+}
+
+const DEFAULT_SOURCE_ROOTS: &[&str] = &[
+    "src/**",
+    "app/**",
+    "apps/*/src/**",
+    "packages/*/src/**",
+    "crates/*/src/**",
+    "**/src/**",
+    "lib/**",
+];
+const DEFAULT_TEST_ROOTS: &[&str] = &[
+    "test/**",
+    "tests/**",
+    "__tests__/**",
+    "packages/*/test/**",
+    "packages/*/tests/**",
+    "crates/*/tests/**",
+    "**/tests/**",
+    "scripts/*.test.js",
+];
+const DEFAULT_DOCS_ROOTS: &[&str] = &["docs/**", "doc/**"];
+const DEFAULT_GENERATED_ROOTS: &[&str] = &[
+    "**/generated/**",
+    "**/__generated__/**",
+    "**/codegen/**",
+    "**/*.generated.*",
+];
+const DEFAULT_ARTIFACT_ROOTS: &[&str] = &[
+    "dist/**",
+    "build/**",
+    "coverage/**",
+    ".next/**",
+    "target/**",
+    "**/dist/**",
+    "**/build/**",
+];
+const DEFAULT_MODULE_ROOTS: &[&str] = &[
+    "src/**",
+    "app/**",
+    "packages/*/src/**",
+    "crates/*/src/**",
+    "**/src/**",
+];
+const DEFAULT_ALLOWED_ROOT_FILES: &[&str] = &[
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "AGENTS.md",
+    "package.json",
+    "Cargo.toml",
+    "pyproject.toml",
+    "go.mod",
+    "go.sum",
+    "Makefile",
+    ".gitignore",
+    ".naomeignore",
+];
+const DEFAULT_IGNORED_PATHS: &[&str] = &[
+    ".git/**",
+    "node_modules/**",
+    "vendor/**",
+    "target/**",
+    "**/target/**",
+    "dist/**",
+    "build/**",
+    "coverage/**",
+    ".next/**",
+];
+
+fn string_list(values: &[&str]) -> Vec<String> {
+    values.iter().map(|value| (*value).to_string()).collect()
+}

package/crates/naome-core/src/quality/structure/mod.rs

@@ -0,0 +1,77 @@
+mod adapters;
+mod checks;
+mod classify;
+mod config;
+mod defaults;
+mod model;
+
+use std::collections::HashSet;
+use std::path::Path;
+
+use crate::models::NaomeError;
+
+use super::scanner::QualityContext;
+use super::types::QualityViolation;
+use checks::run_structure_checks;
+use classify::build_structure_model;
+use config::read_structure_config;
+pub use config::{structure_config_relative_path, write_default_structure_config_if_missing};
+pub use model::{RepositoryStructureConfig, StructurePathExplanation};
+
+pub fn run_repository_structure_checks(
+    root: &Path,
+    context: &QualityContext,
+    baseline_fingerprints: &HashSet<String>,
+) -> Result<Vec<QualityViolation>, NaomeError> {
+    let model = structure_model(root, context, baseline_fingerprints)?;
+    let mut violations = run_structure_checks(&model, context.mode);
+    violations.retain(|violation| {
+        violation.check_id != "test-source-pairing"
+            || context
+                .files
+                .iter()
+                .find(|file| file.path == violation.path)
+                .is_some_and(|file| !file.symbols.is_empty())
+    });
+    if !context.mode.is_changed() {
+        for violation in &mut violations {
+            violation.baseline = baseline_fingerprints.contains(&violation.fingerprint);
+        }
+    }
+    Ok(violations)
+}
+
+pub fn explain_repository_structure(
+    root: &Path,
+    path: impl AsRef<str>,
+) -> Result<StructurePathExplanation, NaomeError> {
+    let repo_paths = super::scanner::collect_repo_paths(root)?;
+    let changed_paths = crate::git::changed_paths(root)?;
+    let config = read_structure_config(root, &repo_paths)?;
+    let model = build_structure_model(config, &repo_paths, &changed_paths, &HashSet::new());
+    let normalized = path.as_ref().replace('\\', "/");
+    model
+        .paths
+        .into_iter()
+        .find(|entry| entry.explanation.path == normalized)
+        .map(|entry| entry.explanation)
+        .ok_or_else(|| {
+            NaomeError::new(format!(
+                "{normalized} is not visible to structure analysis."
+            ))
+        })
+}
+
+fn structure_model(
+    root: &Path,
+    context: &QualityContext,
+    baseline_fingerprints: &HashSet<String>,
+) -> Result<model::RepositoryStructureModel, NaomeError> {
+    let config = read_structure_config(root, &context.repo_paths)?;
+    Ok(build_structure_model(
+        config,
+        &context.repo_paths,
+        &context.changed_paths,
+        baseline_fingerprints,
+    ))
+}

package/crates/naome-core/src/quality/structure/model.rs

@@ -0,0 +1,131 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use serde::{Deserialize, Serialize};
+
+use super::defaults::{default_changed_policy, default_debt_policy, default_structure_config};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct StructureLimits {
+    pub max_directory_files: usize,
+    pub max_path_depth: usize,
+    pub max_directory_roles: usize,
+    pub max_dumping_ground_files: usize,
+}
+
+impl Default for StructureLimits {
+    fn default() -> Self {
+        Self {
+            max_directory_files: 40,
+            max_path_depth: 10,
+            max_directory_roles: 2,
+            max_dumping_ground_files: 12,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DirectoryRoleRule {
+    pub id: String,
+    pub paths: Vec<String>,
+    #[serde(default)]
+    pub allowed_roles: Vec<String>,
+    #[serde(default)]
+    pub max_roles: Option<usize>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LayerRule {
+    pub id: String,
+    pub paths: Vec<String>,
+    pub layer: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RepositoryStructureConfig {
+    pub schema: String,
+    pub version: u32,
+    pub status: String,
+    #[serde(default)]
+    pub enabled_adapters: Vec<String>,
+    #[serde(default)]
+    pub source_roots: Vec<String>,
+    #[serde(default)]
+    pub test_roots: Vec<String>,
+    #[serde(default)]
+    pub docs_roots: Vec<String>,
+    #[serde(default)]
+    pub generated_roots: Vec<String>,
+    #[serde(default)]
+    pub artifact_roots: Vec<String>,
+    #[serde(default)]
+    pub module_roots: Vec<String>,
+    #[serde(default)]
+    pub allowed_root_files: Vec<String>,
+    #[serde(default)]
+    pub directory_role_rules: Vec<DirectoryRoleRule>,
+    #[serde(default)]
+    pub layer_rules: Vec<LayerRule>,
+    #[serde(default)]
+    pub ignored_paths: Vec<String>,
+    #[serde(default)]
+    pub disabled_checks: Vec<String>,
+    #[serde(default = "default_changed_policy")]
+    pub changed_code_policy: String,
+    #[serde(default = "default_debt_policy")]
+    pub debt_policy: String,
+    #[serde(default)]
+    pub limits: StructureLimits,
+}
+
+impl Default for RepositoryStructureConfig {
+    fn default() -> Self {
+        default_structure_config()
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct StructurePathExplanation {
+    pub path: String,
+    pub role: String,
+    pub module: Option<String>,
+    pub layer: String,
+    pub language: Option<String>,
+    pub generated: bool,
+    pub debt: bool,
+    pub changed: bool,
+    pub directory: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct StructurePath {
+    pub explanation: StructurePathExplanation,
+    pub segments: Vec<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct StructureDirectory {
+    pub path: String,
+    pub roles: BTreeSet<String>,
+    pub modules: BTreeSet<String>,
+    pub file_count: usize,
+    pub direct_changed_paths: Vec<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct RepositoryStructureModel {
+    pub config: RepositoryStructureConfig,
+    pub paths: Vec<StructurePath>,
+    pub directories: Vec<StructureDirectory>,
+    pub module_paths: BTreeMap<String, Vec<String>>,
+    #[allow(dead_code)]
+    pub directory_paths: BTreeMap<String, Vec<String>>,
+    #[allow(dead_code)]
+    pub role_paths: BTreeMap<String, Vec<String>>,
+    pub lowercase_paths: BTreeMap<String, Vec<String>>,
+    pub changed_paths: BTreeSet<String>,
+}

package/crates/naome-core/src/quality/types.rs

@@ -4,15 +4,45 @@ use crate::paths;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum QualityMode {
-    Changed,
+    ChangedFast,
     Report,
+    DeepReport,
 }
 
 impl QualityMode {
+    #[allow(non_upper_case_globals)]
+    pub const Changed: Self = Self::ChangedFast;
+
     pub fn as_str(self) -> &'static str {
         match self {
-            Self::Changed => "changed",
+            Self::ChangedFast => "changed",
             Self::Report => "report",
+            Self::DeepReport => "deep-report",
+        }
+    }
+
+    pub fn is_changed(self) -> bool {
+        self == Self::ChangedFast
+    }
+
+    pub fn is_deep(self) -> bool {
+        self == Self::DeepReport
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum QualityInitMode {
+    SeedOnly,
+    Baseline,
+    DeepBaseline,
+}
+
+impl QualityInitMode {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::SeedOnly => "init",
+            Self::Baseline => "baseline",
+            Self::DeepBaseline => "deep-baseline",
         }
     }
 }
@@ -187,9 +217,14 @@ pub struct QualityReport {
 #[serde(rename_all = "camelCase")]
 pub struct QualitySummary {
     pub scanned_files: usize,
+    pub scanned_path_count: usize,
     pub violation_count: usize,
     pub baseline_violation_count: usize,
     pub blocking_violation_count: usize,
+    pub truncated: bool,
+    pub reason_codes: Vec<String>,
+    pub cache_hits: usize,
+    pub cache_misses: usize,
 }
 
 #[derive(Debug, Clone, Serialize)]
@@ -211,10 +246,14 @@ pub struct QualityViolation {
 #[serde(rename_all = "camelCase")]
 pub struct QualityInitResult {
     pub schema: String,
+    pub mode: String,
     pub config_written: bool,
+    pub structure_config_written: bool,
     pub baseline_written: bool,
+    pub baseline_pending: bool,
     pub baseline_violations: usize,
     pub config_path: String,
+    pub structure_config_path: String,
     pub baseline_path: String,
 }
 
@@ -256,9 +295,11 @@ pub fn default_generated_paths() -> Vec<String> {
 const DEFAULT_IGNORED_PATHS: &str = r#"
 .git/**
 .naome/archive/**
+.naome/cache/**
 .naome/task-state.json
 .naome/task-journal.jsonl
 .naome/repository-quality.json
+.naome/repository-structure.json
 .naome/repository-quality-baseline.json
 node_modules/**
 .npm/**

package/crates/naome-core/src/route/builtin_checks.rs

@@ -0,0 +1,141 @@
+use std::path::Path;
+
+use crate::harness_health::{validate_harness_health, HarnessHealthOptions};
+use crate::models::NaomeError;
+use crate::quality::{check_repository_quality, QualityMode};
+use crate::route::git_ops::{command_output, git_output};
+use crate::route::quality_gate::QualityCheck;
+use crate::task_state::{validate_task_state, TaskStateMode, TaskStateOptions};
+use crate::verification_contract::validate_verification_contract;
+
+use super::builtin_context::{run_context_budget_check, template_root};
+use super::builtin_integrity::packaged_harness_integrity;
+use super::builtin_require::{require_builtin_quality_check, require_builtin_quality_check_any};
+
+pub(super) fn run_quality_check(
+    root: &Path,
+    check_id: &str,
+    check: &QualityCheck,
+) -> Result<(), NaomeError> {
+    match check_id {
+        "diff-check" => {
+            require_builtin_quality_check(check_id, check, "git diff --check")?;
+            let output = git_output(root, &["diff", "--check"])?;
+
+            if output.status.success() {
+                Ok(())
+            } else {
+                Err(NaomeError::new(command_output(&output)))
+            }
+        }
+        "naome-harness-health" => {
+            require_builtin_quality_check(
+                check_id,
+                check,
+                "node .naome/bin/check-harness-health.js",
+            )?;
+            run_harness_health_check(root)
+        }
+        "task-state-check" => {
+            require_builtin_quality_check(check_id, check, "npm run check:task-state")?;
+            run_template_task_state_check(root)
+        }
+        "verification-contract-check" => {
+            require_builtin_quality_check(
+                check_id,
+                check,
+                "npm run check:verification-contract",
+            )?;
+            run_template_verification_contract_check(root)
+        }
+        "context-budget-check" => {
+            require_builtin_quality_check(check_id, check, "npm run check:context-budget")?;
+            run_context_budget_check(root)
+        }
+        "repository-quality-check" => {
+            require_builtin_quality_check_any(
+                check_id,
+                check,
+                &[
+                    "naome quality check --changed",
+                    "node .naome/bin/naome.js quality check --changed",
+                    "npm run check:repository-quality",
+                ],
+            )?;
+            run_repository_quality_check(root)
+        }
+        _ => Err(NaomeError::new(format!(
+            "Quality check {check_id} is not a built-in safe check; NAOME will not execute repository-controlled verification commands."
+        ))),
+    }
+}
+
+fn run_repository_quality_check(root: &Path) -> Result<(), NaomeError> {
+    let report = check_repository_quality(root, QualityMode::ChangedFast)?;
+    if report.ok {
+        return Ok(());
+    }
+
+    let details = report
+        .violations
+        .iter()
+        .take(20)
+        .map(|violation| {
+            let location = violation
+                .line
+                .map(|line| format!("{}:{line}", violation.path))
+                .unwrap_or_else(|| violation.path.clone());
+            format!("{location} {}: {}", violation.check_id, violation.message)
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+    Err(NaomeError::new(format!(
+        "repository-quality-check failed with {} violation(s).\n{}",
+        report.violations.len(),
+        details
+    )))
+}
+
+fn run_harness_health_check(root: &Path) -> Result<(), NaomeError> {
+    let errors = validate_harness_health(
+        root,
+        HarnessHealthOptions {
+            expected_integrity: packaged_harness_integrity()?,
+            ..HarnessHealthOptions::default()
+        },
+    )?;
+    if errors.is_empty() {
+        Ok(())
+    } else {
+        Err(NaomeError::new(errors.join("\n")))
+    }
+}
+
+fn run_template_task_state_check(root: &Path) -> Result<(), NaomeError> {
+    let template_root = template_root(root);
+    let report = validate_task_state(
+        &template_root,
+        TaskStateOptions {
+            mode: TaskStateMode::State,
+            harness_health: Some(HarnessHealthOptions {
+                expected_integrity: packaged_harness_integrity()?,
+                allow_missing_archive: true,
+                ..HarnessHealthOptions::default()
+            }),
+        },
+    )?;
+    if report.errors.is_empty() {
+        Ok(())
+    } else {
+        Err(NaomeError::new(report.errors.join("\n")))
+    }
+}
+
+fn run_template_verification_contract_check(root: &Path) -> Result<(), NaomeError> {
+    let errors = validate_verification_contract(&template_root(root))?;
+    if errors.is_empty() {
+        Ok(())
+    } else {
+        Err(NaomeError::new(errors.join("\n")))
+    }
+}

package/crates/naome-core/src/route/builtin_context.rs

@@ -0,0 +1,73 @@
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use crate::models::NaomeError;
+
+pub(super) fn run_context_budget_check(root: &Path) -> Result<(), NaomeError> {
+    let template_root = template_root(root);
+    let mut context_files = vec![
+        template_root.join("AGENTS.md"),
+        template_root.join(".naomeignore"),
+    ];
+    context_files.extend(markdown_files(&template_root.join("docs").join("naome"))?);
+    context_files.sort();
+
+    let mut errors = Vec::new();
+    for path in context_files {
+        let content = fs::read_to_string(&path)?;
+        let line_count = count_lines(&content);
+        if line_count > 200 {
+            errors.push(format!(
+                "{}: {line_count} lines",
+                display_repo_path(root, &path)
+            ));
+        }
+    }
+
+    if errors.is_empty() {
+        Ok(())
+    } else {
+        Err(NaomeError::new(format!(
+            "NAOME context budget exceeded. Limit: 200 lines per file.\n{}",
+            errors.join("\n")
+        )))
+    }
+}
+
+pub(super) fn template_root(root: &Path) -> PathBuf {
+    root.join("packages")
+        .join("naome")
+        .join("templates")
+        .join("naome-root")
+}
+
+fn markdown_files(dir: &Path) -> Result<Vec<PathBuf>, NaomeError> {
+    let mut files = Vec::new();
+    for entry in fs::read_dir(dir)? {
+        let entry = entry?;
+        let path = entry.path();
+        if path.is_dir() {
+            files.extend(markdown_files(&path)?);
+        } else if path.is_file() && path.extension().is_some_and(|extension| extension == "md") {
+            files.push(path);
+        }
+    }
+    Ok(files)
+}
+
+fn count_lines(content: &str) -> usize {
+    if content.is_empty() {
+        0
+    } else if content.ends_with('\n') {
+        content.split('\n').count() - 1
+    } else {
+        content.split('\n').count()
+    }
+}
+
+fn display_repo_path(root: &Path, path: &Path) -> String {
+    path.strip_prefix(root)
+        .unwrap_or(path)
+        .to_string_lossy()
+        .to_string()
+}