@lamentis/naome 1.3.11 → 1.3.13

package/Cargo.lock

@@ -76,7 +76,7 @@ checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
 [[package]]
 name = "naome-cli"
-version = "1.3.11"
+version = "1.3.13"
 dependencies = [
  "naome-core",
  "serde_json",
@@ -84,7 +84,7 @@ dependencies = [
 
 [[package]]
 name = "naome-core"
-version = "1.3.11"
+version = "1.3.13"
 dependencies = [
  "serde",
  "serde_json",

package/crates/naome-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "naome-cli"
-version = "1.3.11"
+version = "1.3.13"
 edition.workspace = true
 license.workspace = true
 repository.workspace = true

package/crates/naome-cli/src/architecture_commands.rs

@@ -4,7 +4,7 @@ use std::path::{Path, PathBuf};
 use naome_core::{
     default_architecture_config_text, format_architecture_explain, format_architecture_scan,
     format_architecture_validation, scan_architecture, validate_architecture,
-    ArchitectureScanOptions,
+    ArchitectureScanOptions, ARCHITECTURE_RULE_IDS,
 };
 
 use crate::cli_args::{has_flag, option_value};
@@ -52,11 +52,7 @@ fn run_arch_explain(root: &Path, args: &[String]) -> Result<(), Box<dyn std::err
                 "schema": "naome.arch.explain.v1",
                 "layers": scan.config.layers.keys().collect::<Vec<_>>(),
                 "contexts": scan.config.contexts.keys().collect::<Vec<_>>(),
-                "rules": [
-                    "arch.max_file_lines",
-                    "arch.generated_manual_boundary",
-                    "arch.no_forbidden_layer_dependencies"
-                ],
+                "rules": ARCHITECTURE_RULE_IDS,
                 "extractors": ["path", "typescript", "javascript", "rust", "python", "go"]
             }))?
         );

package/crates/naome-cli/tests/architecture_cli.rs

@@ -0,0 +1,60 @@
+use std::fs;
+use std::process::Command;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde_json::Value;
+
+static FIXTURE_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+#[test]
+fn architecture_explain_json_lists_all_validation_rules() {
+    let root = fixture_root();
+    let output = Command::new(env!("CARGO_BIN_EXE_naome"))
+        .args(["arch", "explain", "--json"])
+        .current_dir(&root)
+        .output()
+        .unwrap();
+
+    assert!(
+        output.status.success(),
+        "{}{}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let payload: Value = serde_json::from_slice(&output.stdout).unwrap();
+    let rules = payload["rules"].as_array().unwrap();
+
+    for rule in [
+        "arch.no_cross_context_internal_imports",
+        "arch.public_api_boundary",
+        "arch.no_cycles",
+        "arch.no_transitive_forbidden_layer_dependencies",
+        "arch.max_imports_per_file",
+        "arch.max_fan_out",
+        "arch.external_dependency_policy",
+    ] {
+        assert!(rules.iter().any(|value| value == rule), "{rule}");
+    }
+}
+
+fn fixture_root() -> std::path::PathBuf {
+    let nonce = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_nanos();
+    let counter = FIXTURE_COUNTER.fetch_add(1, Ordering::Relaxed);
+    let root = std::env::temp_dir().join(format!(
+        "naome-arch-cli-fixture-{}-{nonce}-{counter}",
+        std::process::id()
+    ));
+    fs::create_dir_all(&root).unwrap();
+    fs::create_dir_all(root.join(".naome")).unwrap();
+    fs::write(
+        root.join(".naomeignore"),
+        ".naome/archive/\n.naome/tasks/\n",
+    )
+    .unwrap();
+    fs::write(root.join(".naome/task-state.json"), "{}\n").unwrap();
+    root
+}

package/crates/naome-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "naome-core"
-version = "1.3.11"
+version = "1.3.13"
 edition.workspace = true
 license.workspace = true
 repository.workspace = true

package/crates/naome-core/src/architecture/config/parser/sections.rs

@@ -2,7 +2,9 @@ use crate::models::NaomeError;
 
 use super::scalar::{clean, indent, parse_bool, section_name};
 use super::ConfigParser;
-use crate::architecture::config::{ContextConfig, IgnoreRule, LayerConfig, RuleConfig};
+use crate::architecture::config::{
+    ContextConfig, ExternalDependencyPolicy, IgnoreRule, LayerConfig, RuleConfig,
+};
 use crate::architecture::output::Severity;
 
 pub(super) fn parse_layers(parser: &mut ConfigParser<'_>) -> Result<(), NaomeError> {
@@ -53,6 +55,47 @@ pub(super) fn parse_allowed_dependencies(parser: &mut ConfigParser<'_>) -> Resul
     Ok(())
 }
 
+pub(super) fn parse_external_dependencies(parser: &mut ConfigParser<'_>) -> Result<(), NaomeError> {
+    while let Some((_, line)) = parser.peek_line() {
+        if indent(line) == 0 {
+            break;
+        }
+        let (line_number, line) = parser.next_line().unwrap();
+        let name = section_name(line, 2).ok_or_else(|| {
+            parser.error(line_number, "expected dependency policy owner".to_string())
+        })?;
+        let policy = parse_external_dependency_policy(parser)?;
+        parser
+            .config
+            .external_dependencies
+            .insert(name.to_string(), policy);
+    }
+    Ok(())
+}
+
+fn parse_external_dependency_policy(
+    parser: &mut ConfigParser<'_>,
+) -> Result<ExternalDependencyPolicy, NaomeError> {
+    let mut policy = ExternalDependencyPolicy::default();
+    while let Some((_, child)) = parser.peek_line() {
+        if indent(child) <= 2 {
+            break;
+        }
+        let (child_line, child) = parser.next_line().unwrap();
+        match child.trim() {
+            "allow:" => policy.allow = parser.parse_list(6)?,
+            "allow: []" => policy.allow = Vec::new(),
+            other => {
+                return Err(parser.error(
+                    child_line,
+                    format!("unsupported external dependency policy key: {other}"),
+                ))
+            }
+        }
+    }
+    Ok(policy)
+}
+
 fn parse_context(parser: &mut ConfigParser<'_>) -> Result<ContextConfig, NaomeError> {
     let mut context = ContextConfig::default();
     while let Some((_, child)) = parser.peek_line() {

package/crates/naome-core/src/architecture/config/parser.rs

@@ -41,6 +41,7 @@ impl<'a> ConfigParser<'a> {
                 "layers:" => sections::parse_layers(self)?,
                 "contexts:" => sections::parse_contexts(self)?,
                 "allowed_dependencies:" => sections::parse_allowed_dependencies(self)?,
+                "external_dependencies:" => sections::parse_external_dependencies(self)?,
                 "rules:" => sections::parse_rules(self)?,
                 "ignore:" => sections::parse_ignore(self)?,
                 other => {

package/crates/naome-core/src/architecture/config.rs

@@ -13,6 +13,7 @@ pub struct ArchitectureConfig {
     pub layers: BTreeMap<String, LayerConfig>,
     pub contexts: BTreeMap<String, ContextConfig>,
     pub allowed_dependencies: BTreeMap<String, Vec<String>>,
+    pub external_dependencies: BTreeMap<String, ExternalDependencyPolicy>,
     pub rules: BTreeMap<String, RuleConfig>,
     pub ignore: Vec<IgnoreRule>,
 }
@@ -28,6 +29,11 @@ pub struct ContextConfig {
     pub public_api: Vec<String>,
 }
 
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ExternalDependencyPolicy {
+    pub allow: Vec<String>,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct RuleConfig {
     pub enabled: bool,
@@ -104,6 +110,35 @@ rules:
   no_forbidden_layer_dependencies:
     enabled: true
     severity: error
+  no_cross_context_internal_imports:
+    enabled: true
+    severity: error
+  public_api_boundary:
+    enabled: true
+    severity: error
+  no_cycles:
+    enabled: true
+    severity: error
+  no_transitive_forbidden_layer_dependencies:
+    enabled: true
+    severity: error
+  max_imports_per_file:
+    enabled: true
+    value: 20
+    severity: warning
+  max_fan_out:
+    enabled: true
+    value: 20
+    severity: warning
+  external_dependency_policy:
+    enabled: true
+    severity: error
+
+external_dependencies:
+  domain:
+    allow: []
+  infrastructure:
+    allow: []
 
 ignore:
   - path: "generated/**"

package/crates/naome-core/src/architecture/output.rs

@@ -59,6 +59,19 @@ pub struct ArchitectureValidation {
     pub agent_feedback: Vec<ArchitectureAgentFeedback>,
 }
 
+pub const ARCHITECTURE_RULE_IDS: &[&str] = &[
+    "arch.max_file_lines",
+    "arch.generated_manual_boundary",
+    "arch.no_forbidden_layer_dependencies",
+    "arch.no_cross_context_internal_imports",
+    "arch.public_api_boundary",
+    "arch.no_cycles",
+    "arch.no_transitive_forbidden_layer_dependencies",
+    "arch.max_imports_per_file",
+    "arch.max_fan_out",
+    "arch.external_dependency_policy",
+];
+
 impl Severity {
     pub fn parse(value: &str) -> Option<Self> {
         match value {
@@ -163,7 +176,8 @@ pub fn format_architecture_explain(scan: &ArchitectureScanReport) -> String {
         .collect::<Vec<_>>()
         .join(", ");
     format!(
-        "NAOME Architecture Fitness\nrules: max_file_lines, generated_manual_boundary, no_forbidden_layer_dependencies\nlayers: {}\ncontexts: {}\npath extractor: enabled for every repository\nimport extractors: typescript, javascript, rust, python, go\n",
+        "NAOME Architecture Fitness\nrules: {}\nlayers: {}\ncontexts: {}\npath extractor: enabled for every repository\nimport extractors: typescript, javascript, rust, python, go\n",
+        ARCHITECTURE_RULE_IDS.join(", "),
         empty_label(&layers),
         empty_label(&contexts)
     )

package/crates/naome-core/src/architecture/rules/budgets.rs

@@ -0,0 +1,179 @@
+use crate::architecture::output::{ArchitectureViolation, Severity};
+use crate::architecture::scan::{ArchitectureScanReport, FileFact, ImportTarget};
+
+pub(super) fn validate_file_size_budget(
+    scan: &ArchitectureScanReport,
+    violations: &mut Vec<ArchitectureViolation>,
+    rules_executed: &mut Vec<String>,
+) {
+    let Some((severity, limit)) = configured_budget(
+        scan,
+        "max_file_lines",
+        "arch.max_file_lines",
+        rules_executed,
+    ) else {
+        return;
+    };
+    for fact in scan.file_facts.values() {
+        push_budget_violation(
+            violations,
+            BudgetFinding {
+                id: "arch.max_file_lines",
+                violation_type: "file_size_budget",
+                severity,
+                path: &fact.path,
+                actual: fact.line_count,
+                limit,
+                unit: "lines",
+                suggestion: "Split the file into cohesive modules or move generated content behind an explicit ignore rule.",
+                instruction: format!(
+                    "Reduce {} below {} lines or add a justified generated-code ignore rule if it is not manually owned.",
+                    fact.path, limit
+                ),
+            },
+        );
+    }
+}
+
+pub(super) fn validate_dependency_budgets(
+    scan: &ArchitectureScanReport,
+    violations: &mut Vec<ArchitectureViolation>,
+    rules_executed: &mut Vec<String>,
+) {
+    for budget in [
+        BudgetRule {
+            config_key: "max_imports_per_file",
+            id: "arch.max_imports_per_file",
+            violation_type: "import_count_budget",
+            metric: BudgetMetric::ImportCount,
+            unit: "imports",
+            suggestion: "Split responsibilities or introduce a smaller facade to reduce imports.",
+            instruction:
+                "Reduce imports in this file before continuing architecture-sensitive work.",
+        },
+        BudgetRule {
+            config_key: "max_fan_out",
+            id: "arch.max_fan_out",
+            violation_type: "fan_out_budget",
+            metric: BudgetMetric::FanOut,
+            unit: "unique targets",
+            suggestion: "Reduce direct dependencies or move orchestration into a narrower module.",
+            instruction: "Lower this file's fan-out before adding more direct dependencies.",
+        },
+    ] {
+        validate_measured_budget(scan, violations, rules_executed, budget);
+    }
+}
+
+#[derive(Clone, Copy)]
+struct BudgetRule {
+    config_key: &'static str,
+    id: &'static str,
+    violation_type: &'static str,
+    metric: BudgetMetric,
+    unit: &'static str,
+    suggestion: &'static str,
+    instruction: &'static str,
+}
+
+#[derive(Clone, Copy)]
+enum BudgetMetric {
+    FanOut,
+    ImportCount,
+}
+
+struct BudgetFinding<'a> {
+    id: &'static str,
+    violation_type: &'static str,
+    severity: Severity,
+    path: &'a str,
+    actual: usize,
+    limit: usize,
+    unit: &'static str,
+    suggestion: &'static str,
+    instruction: String,
+}
+
+fn validate_measured_budget(
+    scan: &ArchitectureScanReport,
+    violations: &mut Vec<ArchitectureViolation>,
+    rules_executed: &mut Vec<String>,
+    budget: BudgetRule,
+) {
+    let Some((severity, limit)) =
+        configured_budget(scan, budget.config_key, budget.id, rules_executed)
+    else {
+        return;
+    };
+    for fact in scan.file_facts.values() {
+        push_budget_violation(
+            violations,
+            BudgetFinding {
+                id: budget.id,
+                violation_type: budget.violation_type,
+                severity,
+                path: &fact.path,
+                actual: measure_budget(fact, budget.metric),
+                limit,
+                unit: budget.unit,
+                suggestion: budget.suggestion,
+                instruction: budget.instruction.to_string(),
+            },
+        );
+    }
+}
+
+fn measure_budget(fact: &FileFact, metric: BudgetMetric) -> usize {
+    match metric {
+        BudgetMetric::FanOut => fact
+            .imports
+            .iter()
+            .map(|import| stable_target_id(&import.target))
+            .collect::<std::collections::BTreeSet<_>>()
+            .len(),
+        BudgetMetric::ImportCount => fact.imports.len(),
+    }
+}
+
+fn configured_budget(
+    scan: &ArchitectureScanReport,
+    config_key: &str,
+    rule_id: &str,
+    rules_executed: &mut Vec<String>,
+) -> Option<(Severity, usize)> {
+    let rule = scan.config.rule(config_key);
+    if !rule.enabled {
+        return None;
+    }
+    rules_executed.push(rule_id.to_string());
+    rule.value.map(|limit| (rule.severity, limit))
+}
+
+fn push_budget_violation(violations: &mut Vec<ArchitectureViolation>, finding: BudgetFinding<'_>) {
+    if finding.actual <= finding.limit {
+        return;
+    }
+    violations.push(ArchitectureViolation {
+        id: finding.id.to_string(),
+        severity: finding.severity,
+        violation_type: finding.violation_type.to_string(),
+        message: format!(
+            "{} has {} {}, exceeding the configured budget of {}.",
+            finding.path, finding.actual, finding.unit, finding.limit
+        ),
+        from: Some(format!("file:{}", finding.path)),
+        to: None,
+        path: Some(finding.path.to_string()),
+        source_range: None,
+        suggestion: finding.suggestion.to_string(),
+        agent_instruction: finding.instruction,
+    });
+}
+
+fn stable_target_id(target: &ImportTarget) -> String {
+    match target {
+        ImportTarget::File(path) => format!("file:{path}"),
+        ImportTarget::ExternalDependency(package) => format!("external:{package}"),
+        ImportTarget::Unknown(specifier) => format!("unknown:{specifier}"),
+    }
+}

package/crates/naome-core/src/architecture/rules/context.rs

@@ -0,0 +1,138 @@
+use crate::architecture::output::ArchitectureViolation;
+use crate::architecture::scan::{ArchitectureScanReport, FileFact};
+use crate::paths;
+
+use super::graph;
+
+pub(super) fn validate_context_rules(
+    scan: &ArchitectureScanReport,
+    violations: &mut Vec<ArchitectureViolation>,
+    rules_executed: &mut Vec<String>,
+) {
+    for boundary in [
+        BoundaryRule {
+            config_key: "no_cross_context_internal_imports",
+            rule_id: "arch.no_cross_context_internal_imports",
+            violation_type: "forbidden_context_dependency",
+            message: |from, to| format!("{from} imports internal context file {to}."),
+            suggestion: "Import a declared public API entrypoint for the target context instead.",
+            instruction:
+                "Do not import another bounded context's internal files; route through its public API.",
+            internal_targets_only: true,
+        },
+        BoundaryRule {
+            config_key: "public_api_boundary",
+            rule_id: "arch.public_api_boundary",
+            violation_type: "public_api_boundary",
+            message: |from, to| format!("{from} crosses into {to} without using its public API."),
+            suggestion: "Change the import to a path listed in the target context public_api.",
+            instruction:
+                "Use the target bounded context public API; do not import its internal files.",
+            internal_targets_only: false,
+        },
+    ] {
+        validate_boundary(scan, violations, rules_executed, boundary);
+    }
+}
+
+struct BoundaryRule {
+    config_key: &'static str,
+    rule_id: &'static str,
+    violation_type: &'static str,
+    message: fn(&str, &str) -> String,
+    suggestion: &'static str,
+    instruction: &'static str,
+    internal_targets_only: bool,
+}
+
+fn validate_boundary(
+    scan: &ArchitectureScanReport,
+    violations: &mut Vec<ArchitectureViolation>,
+    rules_executed: &mut Vec<String>,
+    boundary: BoundaryRule,
+) {
+    let rule = scan.config.rule(boundary.config_key);
+    if !rule.enabled {
+        return;
+    }
+    rules_executed.push(boundary.rule_id.to_string());
+    for import in graph::file_import_edges(scan) {
+        let Some(from_fact) = scan.file_facts.get(import.from_path) else {
+            continue;
+        };
+        let Some(to_fact) = scan.file_facts.get(import.to_path) else {
+            continue;
+        };
+        if compatible(scan, &from_fact.contexts, to_fact, import.to_path) {
+            continue;
+        }
+        if boundary.internal_targets_only && !is_internal_path(import.to_path) {
+            continue;
+        }
+        violations.push(ArchitectureViolation {
+            id: boundary.rule_id.to_string(),
+            severity: rule.severity,
+            violation_type: boundary.violation_type.to_string(),
+            message: (boundary.message)(import.from_path, import.to_path),
+            from: Some(format!("file:{}", import.from_path)),
+            to: Some(format!("file:{}", import.to_path)),
+            path: Some(import.from_path.to_string()),
+            source_range: scan.graph.edges[import.edge_index]
+                .metadata
+                .source_range
+                .clone(),
+            suggestion: boundary.suggestion.to_string(),
+            agent_instruction: boundary.instruction.to_string(),
+        });
+    }
+}
+
+fn compatible(
+    scan: &ArchitectureScanReport,
+    from_contexts: &[String],
+    to_fact: &FileFact,
+    to_path: &str,
+) -> bool {
+    let from_effective = effective_contexts(scan, from_contexts);
+    let to_effective = effective_contexts(scan, &to_fact.contexts);
+    if to_effective.is_empty() {
+        return true;
+    }
+    if from_effective.is_empty() {
+        return is_public_api(scan, to_path, &to_effective);
+    }
+    from_effective
+        .iter()
+        .any(|context| to_effective.contains(context))
+        || is_public_api(scan, to_path, &to_effective)
+}
+
+fn is_public_api(scan: &ArchitectureScanReport, path: &str, contexts: &[String]) -> bool {
+    contexts.iter().any(|context| {
+        scan.config
+            .contexts
+            .get(context)
+            .is_some_and(|config| paths::matches_any(path, &config.public_api))
+    })
+}
+
+fn is_internal_path(path: &str) -> bool {
+    path.split('/').any(|segment| segment == "internal")
+}
+
+fn effective_contexts(scan: &ArchitectureScanReport, contexts: &[String]) -> Vec<String> {
+    contexts
+        .iter()
+        .filter(|context| !is_catch_all_context(scan, context))
+        .cloned()
+        .collect()
+}
+
+fn is_catch_all_context(scan: &ArchitectureScanReport, context: &str) -> bool {
+    scan.config.contexts.get(context).is_some_and(|config| {
+        config
+            .paths
+            .iter()
+            .any(|path| matches!(path.as_str(), "**" | "src/**"))
+    })
+}

package/crates/naome-core/src/architecture/rules/cycles.rs

@@ -0,0 +1,39 @@
+use crate::architecture::output::ArchitectureViolation;
+use crate::architecture::scan::ArchitectureScanReport;
+
+use super::graph;
+
+pub(super) fn validate_cycles(
+    scan: &ArchitectureScanReport,
+    violations: &mut Vec<ArchitectureViolation>,
+    rules_executed: &mut Vec<String>,
+) {
+    let rule = scan.config.rule("no_cycles");
+    if !rule.enabled {
+        return;
+    }
+    rules_executed.push("arch.no_cycles".to_string());
+    let adjacency = graph::file_cycle_adjacency(scan);
+    for component in graph::strongly_connected_components(&adjacency) {
+        let path = component.first().cloned();
+        violations.push(ArchitectureViolation {
+            id: "arch.no_cycles".to_string(),
+            severity: rule.severity,
+            violation_type: "cycle".to_string(),
+            message: format!(
+                "Architecture import cycle detected: {}.",
+                component.join(" -> ")
+            ),
+            from: path.as_ref().map(|path| format!("file:{path}")),
+            to: None,
+            path,
+            source_range: None,
+            suggestion:
+                "Break the cycle by extracting a lower-level dependency or inverting one edge."
+                    .to_string(),
+            agent_instruction:
+                "Break this import cycle before adding more behavior; do not suppress the rule."
+                    .to_string(),
+        });
+    }
+}