@lamentis/naome 1.2.0 → 1.3.0

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

@@ -0,0 +1,89 @@
+use std::collections::HashSet;
+
+use crate::models::NaomeError;
+
+pub(crate) struct RepoSignals<'a> {
+    paths: &'a [String],
+}
+
+impl<'a> RepoSignals<'a> {
+    pub(crate) fn new(paths: &'a [String]) -> Self {
+        Self { paths }
+    }
+
+    pub(crate) fn has_manifest(&self, expected: &str) -> bool {
+        let nested_suffix = format!("/{expected}");
+        self.paths
+            .iter()
+            .any(|path| path == expected || path.ends_with(&nested_suffix))
+    }
+
+    pub(crate) fn has_extension(&self, extensions: &[&str]) -> bool {
+        self.paths
+            .iter()
+            .any(|path| extensions.iter().any(|extension| path.ends_with(extension)))
+    }
+}
+
+pub(crate) trait AdapterDescriptor {
+    fn id(&self) -> &'static str;
+    fn detects(&self, signals: &RepoSignals<'_>) -> bool;
+}
+
+pub(crate) fn detected_ids<T: AdapterDescriptor>(paths: &[String], registry: &[T]) -> Vec<String> {
+    let signals = RepoSignals::new(paths);
+    registry
+        .iter()
+        .filter(|adapter| adapter.detects(&signals))
+        .map(|adapter| adapter.id().to_string())
+        .collect()
+}
+
+pub(crate) fn find_adapter_by_id<'a, T: AdapterDescriptor>(
+    registry: &'a [T],
+    id: &str,
+    config_path: &str,
+) -> Result<&'a T, NaomeError> {
+    registry
+        .iter()
+        .find(|adapter| adapter.id() == id)
+        .ok_or_else(|| {
+            NaomeError::new(format!(
+                "{config_path} enabledAdapters contains unknown adapter '{id}'."
+            ))
+        })
+}
+
+pub(crate) fn validate_ids<T: AdapterDescriptor>(
+    ids: &[String],
+    registry: &[T],
+    config_path: &str,
+) -> Result<(), NaomeError> {
+    let mut seen = HashSet::new();
+    for adapter_id in ids {
+        if !seen.insert(adapter_id) {
+            return Err(NaomeError::new(format!(
+                "{config_path} enabledAdapters contains duplicate adapter '{adapter_id}'."
+            )));
+        }
+        find_adapter_by_id(registry, adapter_id, config_path)?;
+    }
+    Ok(())
+}
+
+pub(crate) fn extend_unique(target: &mut Vec<String>, values: &[&str]) {
+    for value in values {
+        if !target.iter().any(|existing| existing == value) {
+            target.push((*value).to_string());
+        }
+    }
+}
+
+pub(crate) fn detects_rust_project(signals: &RepoSignals<'_>) -> bool {
+    signals.has_manifest("Cargo.toml") || signals.has_extension(&[".rs"])
+}
+
+pub(crate) fn detects_javascript_typescript_project(signals: &RepoSignals<'_>) -> bool {
+    signals.has_manifest("package.json")
+        || signals.has_extension(&[".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"])
+}

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

@@ -1,9 +1,13 @@
-use std::collections::HashSet;
-
 use crate::models::NaomeError;
 
+use super::adapter_support::{
+    detected_ids, detects_javascript_typescript_project, detects_rust_project, extend_unique,
+    find_adapter_by_id, validate_ids, AdapterDescriptor, RepoSignals,
+};
 use super::types::{QualityLimitOverrides, QualityPathRule, RepositoryQualityConfig};
 
+const CONFIG_PATH: &str = ".naome/repository-quality.json";
+
 pub(crate) struct QualityAdapter {
     pub id: &'static str,
     pub generated_paths: &'static [&'static str],
@@ -11,44 +15,28 @@ pub(crate) struct QualityAdapter {
     path_rules: fn() -> Vec<QualityPathRule>,
 }
 
-struct RepoSignals<'a> {
-    paths: &'a [String],
-}
-impl RepoSignals<'_> {
-    fn has_manifest(&self, expected: &str) -> bool {
-        let nested_suffix = format!("/{expected}");
-        self.paths
-            .iter()
-            .any(|path| path == expected || path.ends_with(&nested_suffix))
+impl AdapterDescriptor for QualityAdapter {
+    fn id(&self) -> &'static str {
+        self.id
     }
 
-    fn has_extension(&self, extensions: &[&str]) -> bool {
-        self.paths
-            .iter()
-            .any(|path| extensions.iter().any(|extension| path.ends_with(extension)))
+    fn detects(&self, signals: &RepoSignals<'_>) -> bool {
+        (self.detect)(signals)
     }
 }
+
 pub(crate) fn detected_adapter_ids(paths: &[String]) -> Vec<String> {
-    let signals = RepoSignals { paths };
-    registry()
-        .iter()
-        .filter(|adapter| (adapter.detect)(&signals))
-        .map(|adapter| adapter.id.to_string())
-        .collect()
+    detected_ids(paths, registry())
 }
+
 pub(crate) fn apply_enabled_adapters(
     mut config: RepositoryQualityConfig,
 ) -> Result<RepositoryQualityConfig, NaomeError> {
-    let mut seen = HashSet::new();
+    validate_adapter_ids(&config.enabled_adapters)?;
     let local_path_rules = std::mem::take(&mut config.path_rules);
 
     for adapter_id in config.enabled_adapters.clone() {
-        if !seen.insert(adapter_id.clone()) {
-            return Err(NaomeError::new(format!(
-                ".naome/repository-quality.json enabledAdapters contains duplicate adapter '{adapter_id}'."
-            )));
-        }
-        let adapter = adapter_by_id(&adapter_id)?;
+        let adapter = find_adapter_by_id(registry(), &adapter_id, CONFIG_PATH)?;
         extend_unique(&mut config.generated_paths, adapter.generated_paths);
         config.path_rules.extend((adapter.path_rules)());
     }
@@ -56,27 +44,9 @@ pub(crate) fn apply_enabled_adapters(
     config.path_rules.extend(local_path_rules);
     Ok(config)
 }
+
 pub(crate) fn validate_adapter_ids(ids: &[String]) -> Result<(), NaomeError> {
-    let mut seen = HashSet::new();
-    for adapter_id in ids {
-        if !seen.insert(adapter_id) {
-            return Err(NaomeError::new(format!(
-                ".naome/repository-quality.json enabledAdapters contains duplicate adapter '{adapter_id}'."
-            )));
-        }
-        adapter_by_id(adapter_id)?;
-    }
-    Ok(())
-}
-fn adapter_by_id(id: &str) -> Result<&'static QualityAdapter, NaomeError> {
-    registry()
-        .iter()
-        .find(|adapter| adapter.id == id)
-        .ok_or_else(|| {
-            NaomeError::new(format!(
-                ".naome/repository-quality.json enabledAdapters contains unknown adapter '{id}'."
-            ))
-        })
+    validate_ids(ids, registry(), CONFIG_PATH)
 }
 
 fn registry() -> &'static [QualityAdapter] {
@@ -84,27 +54,18 @@ fn registry() -> &'static [QualityAdapter] {
         QualityAdapter {
             id: "rust",
             generated_paths: &[],
-            detect: detects_rust,
+            detect: detects_rust_project,
             path_rules: rust_path_rules,
         },
         QualityAdapter {
             id: "javascript-typescript",
             generated_paths: &["coverage/**", "**/coverage/**", ".next/**", "**/.next/**"],
-            detect: detects_javascript_typescript,
+            detect: detects_javascript_typescript_project,
             path_rules: javascript_typescript_path_rules,
         },
     ]
 }
 
-fn detects_rust(signals: &RepoSignals<'_>) -> bool {
-    signals.has_manifest("Cargo.toml") || signals.has_extension(&[".rs"])
-}
-
-fn detects_javascript_typescript(signals: &RepoSignals<'_>) -> bool {
-    signals.has_manifest("package.json")
-        || signals.has_extension(&[".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"])
-}
-
 fn rust_path_rules() -> Vec<QualityPathRule> {
     vec![path_rule(
         "rust-tests",
@@ -168,11 +129,3 @@ fn path_rule(
 fn string_list(values: &[&str]) -> Vec<String> {
     values.iter().map(|value| (*value).to_string()).collect()
 }
-
-fn extend_unique(target: &mut Vec<String>, values: &[&str]) {
-    for value in values {
-        if !target.iter().any(|existing| existing == value) {
-            target.push((*value).to_string());
-        }
-    }
-}

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

@@ -73,3 +73,11 @@ pub fn write_baseline(root: &Path, violations: &[QualityViolation]) -> Result<bo
     }
     Ok(changed)
 }
+
+pub fn write_empty_baseline_if_missing(root: &Path) -> Result<bool, NaomeError> {
+    let path = root.join(BASELINE_RELATIVE_PATH);
+    if path.is_file() {
+        return Ok(false);
+    }
+    write_baseline(root, &[])
+}

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

@@ -0,0 +1,153 @@
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use crate::models::NaomeError;
+
+use super::scanner::FileAnalysis;
+use super::types::RepositoryQualityConfig;
+
+const CACHE_RELATIVE_PATH: &str = ".naome/cache/quality";
+const CACHE_SCHEMA: &str = "naome.quality-cache-entry.v1";
+const ADAPTER_VERSION: &str = "quality-core-v1";
+
+#[derive(Debug, Clone)]
+pub(crate) struct QualityCache {
+    root: PathBuf,
+    config_hash: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct CacheEntry {
+    schema: String,
+    naome_version: String,
+    config_hash: String,
+    adapter_version: String,
+    path: String,
+    content_hash: String,
+    analysis: FileAnalysis,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct QualityCacheStatus {
+    pub schema: String,
+    pub path: String,
+    pub entry_count: usize,
+    pub bytes: u64,
+}
+
+impl QualityCache {
+    pub(crate) fn new(root: &Path, config: &RepositoryQualityConfig) -> Self {
+        Self {
+            root: root.to_path_buf(),
+            config_hash: config_hash(config),
+        }
+    }
+
+    pub(crate) fn read(&self, path: &str, content_hash: &str) -> Option<FileAnalysis> {
+        let entry = fs::read_to_string(self.entry_path(path, content_hash)).ok()?;
+        let entry: CacheEntry = serde_json::from_str(&entry).ok()?;
+        if entry.schema == CACHE_SCHEMA
+            && entry.naome_version == env!("CARGO_PKG_VERSION")
+            && entry.config_hash == self.config_hash
+            && entry.adapter_version == ADAPTER_VERSION
+            && entry.path == path
+            && entry.content_hash == content_hash
+        {
+            Some(entry.analysis)
+        } else {
+            None
+        }
+    }
+
+    pub(crate) fn write(
+        &self,
+        path: &str,
+        content_hash: &str,
+        analysis: &FileAnalysis,
+    ) -> Result<(), NaomeError> {
+        let cache_path = self.entry_path(path, content_hash);
+        if let Some(parent) = cache_path.parent() {
+            fs::create_dir_all(parent)?;
+        }
+        let entry = CacheEntry {
+            schema: CACHE_SCHEMA.to_string(),
+            naome_version: env!("CARGO_PKG_VERSION").to_string(),
+            config_hash: self.config_hash.clone(),
+            adapter_version: ADAPTER_VERSION.to_string(),
+            path: path.to_string(),
+            content_hash: content_hash.to_string(),
+            analysis: analysis.clone(),
+        };
+        let content = format!("{}\n", serde_json::to_string(&entry)?);
+        if fs::read_to_string(&cache_path).map_or(true, |current| current != content) {
+            fs::write(cache_path, content)?;
+        }
+        Ok(())
+    }
+
+    fn entry_path(&self, path: &str, content_hash: &str) -> PathBuf {
+        self.root
+            .join(CACHE_RELATIVE_PATH)
+            .join(stable_key(&[
+                env!("CARGO_PKG_VERSION"),
+                &self.config_hash,
+                ADAPTER_VERSION,
+                path,
+                content_hash,
+            ]))
+    }
+}
+
+pub fn quality_cache_status(root: &Path) -> Result<QualityCacheStatus, NaomeError> {
+    let path = root.join(CACHE_RELATIVE_PATH);
+    let mut entry_count = 0;
+    let mut bytes = 0;
+    if path.is_dir() {
+        for entry in fs::read_dir(&path)? {
+            let entry = entry?;
+            let metadata = entry.metadata()?;
+            if metadata.is_file() {
+                entry_count += 1;
+                bytes += metadata.len();
+            }
+        }
+    }
+    Ok(QualityCacheStatus {
+        schema: "naome.quality-cache-status.v1".to_string(),
+        path: CACHE_RELATIVE_PATH.to_string(),
+        entry_count,
+        bytes,
+    })
+}
+
+pub fn clear_quality_cache(root: &Path) -> Result<QualityCacheStatus, NaomeError> {
+    let path = root.join(CACHE_RELATIVE_PATH);
+    if path.exists() {
+        fs::remove_dir_all(&path)?;
+    }
+    quality_cache_status(root)
+}
+
+pub(crate) fn content_hash(content: &str) -> String {
+    stable_key(&[content])
+}
+
+fn config_hash(config: &RepositoryQualityConfig) -> String {
+    serde_json::to_string(config)
+        .map(|content| stable_key(&[&content]))
+        .unwrap_or_else(|_| stable_key(&["invalid-config"]))
+}
+
+fn stable_key(parts: &[&str]) -> String {
+    let mut hasher = Sha256::new();
+    for part in parts {
+        hasher.update(part.as_bytes());
+        hasher.update(b"\0");
+    }
+    format!("{:x}.json", hasher.finalize())
+}

package/crates/naome-core/src/quality/checks/duplicate_blocks.rs

@@ -1,6 +1,8 @@
 use std::collections::{HashMap, HashSet};
 
-use super::super::scanner::{stable_fingerprint, QualityContext};
+use sha2::{Digest, Sha256};
+
+use super::super::scanner::{stable_fingerprint, NormalizedLine, QualityContext};
 use super::super::types::QualityViolation;
 use super::{is_code_like_path, QualityCheck};
 
@@ -12,22 +14,23 @@ impl QualityCheck for DuplicateBlockCheck {
     }
 
     fn evaluate(&self, context: &QualityContext, violations: &mut Vec<QualityViolation>) {
+        if context.mode == super::super::types::QualityMode::Report {
+            return;
+        }
         let mut occurrences: HashMap<String, Vec<DuplicateOccurrence>> = HashMap::new();
-        for file in context.files.iter().filter(|file| {
-            is_code_like_path(&file.path)
-                && context.config.check_enabled_for_path(self.id(), &file.path)
-        }) {
+        for file in context
+            .comparison_candidate_files()
+            .filter(|file| {
+                is_code_like_path(&file.path)
+                    && context.config.check_enabled_for_path(self.id(), &file.path)
+            })
+        {
             let window = context.limits_for(&file.path).duplicate_block_lines;
             if file.normalized_lines.len() < window {
                 continue;
             }
             for lines in file.normalized_lines.windows(window) {
-                let joined = lines
-                    .iter()
-                    .map(|line| line.value.as_str())
-                    .collect::<Vec<_>>()
-                    .join("\n");
-                let fingerprint = stable_fingerprint(&[self.id(), &joined]);
+                let fingerprint = window_fingerprint(self.id(), lines);
                 occurrences
                     .entry(fingerprint.clone())
                     .or_default()
@@ -72,6 +75,17 @@ impl QualityCheck for DuplicateBlockCheck {
     }
 }
 
+fn window_fingerprint(check_id: &str, lines: &[NormalizedLine]) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(check_id.as_bytes());
+    hasher.update(b"\0");
+    for line in lines {
+        hasher.update(line.value.as_bytes());
+        hasher.update(b"\n");
+    }
+    format!("sha256:{:x}", hasher.finalize())
+}
+
 #[derive(Debug, Clone)]
 struct DuplicateOccurrence {
     path: String,

package/crates/naome-core/src/quality/checks/near_duplicates.rs

@@ -12,6 +12,9 @@ impl QualityCheck for NearDuplicateFunctionCheck {
     }
 
     fn evaluate(&self, context: &QualityContext, violations: &mut Vec<QualityViolation>) {
+        if context.mode == super::super::types::QualityMode::Report {
+            return;
+        }
         let symbols = collect_function_occurrences(context, self.id());
         let mut emitted = HashSet::new();
 
@@ -59,8 +62,7 @@ fn collect_function_occurrences<'a>(
     check_id: &str,
 ) -> Vec<FunctionOccurrence<'a>> {
     context
-        .files
-        .iter()
+        .comparison_candidate_files()
         .filter(|file| {
             is_code_like_path(&file.path)
                 && context.config.check_enabled_for_path(check_id, &file.path)

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

@@ -4,7 +4,7 @@ mod near_duplicates;
 use std::collections::HashSet;
 
 use super::scanner::{stable_fingerprint, QualityContext};
-use super::types::{QualityMode, QualityViolation};
+use super::types::QualityViolation;
 use duplicate_blocks::DuplicateBlockCheck;
 use near_duplicates::NearDuplicateFunctionCheck;
 
@@ -64,12 +64,11 @@ impl QualityCheck for FileLengthCheck {
             .filter(|file| context.check_applies_to(self.id(), &file.path))
         {
             let limits = context.limits_for(&file.path);
-            let limit =
-                if context.mode == QualityMode::Changed && file.added_lines == file.line_count {
-                    limits.max_new_file_lines
-                } else {
-                    limits.max_file_lines
-                };
+            let limit = if context.mode.is_changed() && file.added_lines == file.line_count {
+                limits.max_new_file_lines
+            } else {
+                limits.max_file_lines
+            };
             if file.line_count > limit {
                 violations.push(violation(
                     self.id(),
@@ -96,7 +95,7 @@ impl QualityCheck for DiffGrowthCheck {
     }
 
     fn evaluate(&self, context: &QualityContext, violations: &mut Vec<QualityViolation>) {
-        if context.mode != QualityMode::Changed {
+        if !context.mode.is_changed() {
             return;
         }
         for file in context

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

@@ -56,17 +56,62 @@ pub fn cleanup_route_for_path(
         .into_iter()
         .collect::<Vec<_>>();
     related_paths.retain(|related| related != path);
+    let topic = if violations.iter().any(|violation| {
+        violation.check_id.starts_with("directory-")
+            || violation.check_id == "root-file-sprawl"
+            || violation.check_id == "dumping-ground-directory"
+            || violation.check_id == "path-depth"
+            || violation.check_id == "case-collision"
+            || violation.check_id == "test-source-pairing"
+    }) {
+        "repository structure"
+    } else {
+        "repository quality"
+    };
+    let agent_instructions = cleanup_instructions(path, topic, &violations);
     QualityCleanupRoute {
         schema: "naome.quality-cleanup-route.v1".to_string(),
         path: path.to_string(),
         violations,
         related_paths,
-        agent_instructions: format!(
-            "Reduce or split {path} until every repository-quality violation is gone. Prefer extracting reusable helpers/components over copying code. Keep behavior unchanged, add or preserve focused tests, then run naome quality check --changed before task completion."
-        ),
+        agent_instructions,
         required_checks: vec![
             "naome quality check --changed".to_string(),
             "git diff --check".to_string(),
         ],
     }
 }
+
+fn cleanup_instructions(path: &str, topic: &str, violations: &[QualityViolation]) -> String {
+    let mut instructions = Vec::new();
+    instructions.push(format!(
+        "Clean up {path} until every {topic} violation is gone while preserving behavior."
+    ));
+    for check_id in violations
+        .iter()
+        .map(|violation| violation.check_id.as_str())
+        .collect::<BTreeSet<_>>()
+    {
+        instructions.push(match check_id {
+            "test-source-pairing" => "Create or update a nearby or module-matched test that exercises the changed source behavior.".to_string(),
+            "dumping-ground-directory" => "Move feature logic out of generic utils/helpers/common/shared directories into a named module, or extract a reusable helper with a clear owner.".to_string(),
+            "directory-role-mixing" => "Separate source, generated, artifact, and dependency/vendor roles into directories that match repository policy.".to_string(),
+            "misplaced-file-role" => "Move the file to a configured root for its role, such as source, test, docs, config, or script.".to_string(),
+            "root-file-sprawl" => "Move new root-level work into an existing module, docs, config, or script directory unless it is a recognized root manifest.".to_string(),
+            "directory-size" => "Split the directory by module or responsibility until direct file count is below the configured limit.".to_string(),
+            "path-depth" => "Shorten the path by moving the file closer to its owning module boundary.".to_string(),
+            "case-collision" => "Rename colliding paths so they are distinct on case-insensitive filesystems.".to_string(),
+            "file-length" => "Reduce or split the file into focused modules with stable public behavior.".to_string(),
+            "function-length" => "Extract cohesive helper functions or components until each function fits the configured limit.".to_string(),
+            "top-level-symbols" => "Group related symbols into smaller modules and export only the intended public surface.".to_string(),
+            "duplicate-block" | "near-duplicate-function" => "Extract shared behavior into a reusable helper, fixture, builder, or component used by all duplicate call sites.".to_string(),
+            "diff-growth" => "Reduce the diff by narrowing scope, splitting generated changes, or moving unrelated cleanup to a separate task.".to_string(),
+            _ => format!("Resolve the {check_id} finding without weakening generic policy."),
+        });
+    }
+    instructions.push(
+        "Run naome quality check --changed and git diff --check before task completion."
+            .to_string(),
+    );
+    instructions.join(" ")
+}

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

@@ -4,6 +4,7 @@ use std::path::Path;
 use crate::models::NaomeError;
 
 use super::adapters::{apply_enabled_adapters, detected_adapter_ids, validate_adapter_ids};
+use super::config_support::validate_ready_schema;
 use super::scanner::collect_repo_paths;
 use super::types::RepositoryQualityConfig;
 
@@ -46,21 +47,13 @@ fn generated_config(root: &Path) -> Result<RepositoryQualityConfig, NaomeError>
 }
 
 fn validate_config(config: &RepositoryQualityConfig) -> Result<(), NaomeError> {
-    if config.schema != "naome.repository-quality.v1" {
-        return Err(NaomeError::new(
-            ".naome/repository-quality.json schema must be naome.repository-quality.v1.",
-        ));
-    }
-    if config.version != 1 {
-        return Err(NaomeError::new(
-            ".naome/repository-quality.json version must be 1.",
-        ));
-    }
-    if config.status != "ready" {
-        return Err(NaomeError::new(
-            ".naome/repository-quality.json status must be ready.",
-        ));
-    }
+    validate_ready_schema(
+        CONFIG_RELATIVE_PATH,
+        &config.schema,
+        "naome.repository-quality.v1",
+        config.version,
+        &config.status,
+    )?;
     if config.limits.duplicate_block_lines < 3 {
         return Err(NaomeError::new(
             ".naome/repository-quality.json duplicateBlockLines must be at least 3.",

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

@@ -0,0 +1,24 @@
+use crate::models::NaomeError;
+
+pub(crate) fn validate_ready_schema(
+    config_path: &str,
+    actual_schema: &str,
+    expected_schema: &str,
+    version: u32,
+    status: &str,
+) -> Result<(), NaomeError> {
+    if actual_schema != expected_schema {
+        return Err(NaomeError::new(format!(
+            "{config_path} schema must be {expected_schema}."
+        )));
+    }
+    if version != 1 {
+        return Err(NaomeError::new(format!("{config_path} version must be 1.")));
+    }
+    if status != "ready" {
+        return Err(NaomeError::new(format!(
+            "{config_path} status must be ready."
+        )));
+    }
+    Ok(())
+}