@lamentis/naome 1.2.0 → 1.2.1

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/cleanup.rs

@@ -56,13 +56,25 @@ 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"
+    };
     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."
+            "Reduce or split {path} until every {topic} violation is gone. Prefer named modules and reusable helpers/components over dumping logic into generic directories. Keep behavior unchanged, add or preserve focused tests, then run naome quality check --changed before task completion."
         ),
         required_checks: vec![
             "naome quality check --changed".to_string(),

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(())
+}

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

@@ -1,9 +1,12 @@
+mod adapter_support;
 mod adapters;
 mod baseline;
 mod checks;
 mod cleanup;
 mod config;
+mod config_support;
 mod scanner;
+mod structure;
 mod types;
 
 use std::path::Path;
@@ -11,6 +14,9 @@ use std::path::Path;
 use crate::models::NaomeError;
 
 pub use cleanup::{cleanup_plan_from_violations, cleanup_route_for_path};
+pub use structure::{
+    explain_repository_structure, RepositoryStructureConfig, StructurePathExplanation,
+};
 pub use types::{
     QualityCleanupPlan, QualityCleanupRoute, QualityCleanupTask, QualityInitResult, QualityMode,
     QualityReport, QualitySummary, QualityViolation, RepositoryQualityConfig,
@@ -20,6 +26,10 @@ use self::baseline::{baseline_relative_path, read_baseline_fingerprints, write_b
 use self::checks::run_quality_checks;
 use self::config::{config_relative_path, read_config, write_default_config_if_missing};
 use self::scanner::scan_repository;
+use self::structure::{
+    run_repository_structure_checks, structure_config_relative_path,
+    write_default_structure_config_if_missing,
+};
 
 pub fn check_repository_quality(
     root: &Path,
@@ -29,6 +39,7 @@ pub fn check_repository_quality(
     let context = scan_repository(root, mode, config)?;
     let baseline = read_baseline_fingerprints(root)?;
     let mut violations = run_quality_checks(&context);
+    violations.extend(run_repository_structure_checks(root, &context, &baseline)?);
     for violation in &mut violations {
         violation.baseline = baseline.contains(&violation.fingerprint);
     }
@@ -57,15 +68,22 @@ pub fn check_repository_quality(
 
 pub fn init_repository_quality(root: &Path) -> Result<QualityInitResult, NaomeError> {
     let config_written = write_default_config_if_missing(root)?;
+    let structure_config_written = {
+        let config = read_config(root)?;
+        let context = scan_repository(root, QualityMode::Report, config)?;
+        write_default_structure_config_if_missing(root, &context.repo_paths)?
+    };
     let report = check_repository_quality(root, QualityMode::Report)?;
     let baseline_written = write_baseline(root, &report.violations)?;
 
     Ok(QualityInitResult {
         schema: "naome.repository-quality-init.v1".to_string(),
         config_written,
+        structure_config_written,
         baseline_written,
         baseline_violations: report.violations.len(),
         config_path: config_relative_path().to_string(),
+        structure_config_path: structure_config_relative_path().to_string(),
         baseline_path: baseline_relative_path().to_string(),
     })
 }

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

@@ -20,6 +20,7 @@ pub struct QualityContext {
     pub mode: QualityMode,
     pub config: RepositoryQualityConfig,
     pub changed_paths: Vec<String>,
+    pub repo_paths: Vec<String>,
     pub target_paths: HashSet<String>,
     pub files: Vec<FileAnalysis>,
 }
@@ -80,9 +81,12 @@ pub fn scan_repository(
 ) -> Result<QualityContext, NaomeError> {
     let changed_paths = git::changed_paths(root)?;
     let target_paths = changed_paths.iter().cloned().collect::<HashSet<_>>();
+    let mut whole_repo_paths = collect_repo_paths(root)?;
+    whole_repo_paths.sort();
+    whole_repo_paths.dedup();
     let scan_paths = match mode {
         QualityMode::Changed => changed_paths.clone(),
-        QualityMode::Report => collect_repo_paths(root)?,
+        QualityMode::Report => whole_repo_paths.clone(),
     };
     let added_lines = added_lines_by_path(root)?;
     let ignore_patterns = ignore_patterns(root, &config);
@@ -98,18 +102,15 @@ pub fn scan_repository(
     }
 
     if mode == QualityMode::Changed {
-        let mut whole_repo_paths = collect_repo_paths(root)?;
-        whole_repo_paths.sort();
-        whole_repo_paths.dedup();
         let scanned = files
             .iter()
             .map(|file| file.path.clone())
             .collect::<HashSet<_>>();
-        for path in whole_repo_paths {
-            if scanned.contains(&path) || should_skip_path(&path, &ignore_patterns) {
+        for path in &whole_repo_paths {
+            if scanned.contains(path) || should_skip_path(path, &ignore_patterns) {
                 continue;
             }
-            if let Some(file) = analyze_repo_file(root, &path, &added_lines) {
+            if let Some(file) = analyze_repo_file(root, path, &added_lines) {
                 files.push(file);
             }
         }
@@ -120,6 +121,7 @@ pub fn scan_repository(
         mode,
         config,
         changed_paths,
+        repo_paths: whole_repo_paths,
         target_paths,
         files,
     })
@@ -249,7 +251,11 @@ fn symbol_name(rest: &str) -> String {
 
 fn normalize_line(line: &str) -> Option<String> {
     let trimmed = line.trim();
-    if trimmed.is_empty() || is_comment_only(trimmed) || is_generated_hash_mapping(trimmed) {
+    if trimmed.is_empty()
+        || is_comment_only(trimmed)
+        || is_string_list_item(trimmed)
+        || is_generated_hash_mapping(trimmed)
+    {
         return None;
     }
 
@@ -309,6 +315,12 @@ fn is_generated_hash_mapping(trimmed: &str) -> bool {
         && value.chars().filter(|character| *character == '"').count() >= 2
 }
 
+fn is_string_list_item(trimmed: &str) -> bool {
+    let value = trimmed.trim_end_matches(',');
+    (value.starts_with('"') && value.ends_with('"'))
+        || (value.starts_with('\'') && value.ends_with('\''))
+}
+
 fn token_set(line: &str) -> Vec<String> {
     line.split(|character: char| !character.is_ascii_alphanumeric() && character != '_')
         .filter(|token| token.len() > 1)

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

@@ -0,0 +1,84 @@
+use crate::models::NaomeError;
+
+use crate::quality::adapter_support::{
+    detected_ids, detects_javascript_typescript_project, detects_rust_project, extend_unique,
+    find_adapter_by_id, validate_ids, AdapterDescriptor, RepoSignals,
+};
+
+use super::model::RepositoryStructureConfig;
+
+const CONFIG_PATH: &str = ".naome/repository-structure.json";
+
+struct StructureAdapter {
+    id: &'static str,
+    detect: fn(&RepoSignals<'_>) -> bool,
+    source_roots: &'static [&'static str],
+    test_roots: &'static [&'static str],
+    module_roots: &'static [&'static str],
+    allowed_root_files: &'static [&'static str],
+}
+
+impl AdapterDescriptor for StructureAdapter {
+    fn id(&self) -> &'static str {
+        self.id
+    }
+
+    fn detects(&self, signals: &RepoSignals<'_>) -> bool {
+        (self.detect)(signals)
+    }
+}
+
+pub fn detected_structure_adapter_ids(paths: &[String]) -> Vec<String> {
+    detected_ids(paths, registry())
+}
+
+pub fn apply_structure_adapters(
+    mut config: RepositoryStructureConfig,
+) -> Result<RepositoryStructureConfig, NaomeError> {
+    validate_structure_adapter_ids(&config.enabled_adapters)?;
+    for adapter_id in config.enabled_adapters.clone() {
+        let adapter = find_adapter_by_id(registry(), &adapter_id, CONFIG_PATH)?;
+        extend_unique(&mut config.source_roots, adapter.source_roots);
+        extend_unique(&mut config.test_roots, adapter.test_roots);
+        extend_unique(&mut config.module_roots, adapter.module_roots);
+        extend_unique(&mut config.allowed_root_files, adapter.allowed_root_files);
+    }
+    Ok(config)
+}
+
+pub fn validate_structure_adapter_ids(ids: &[String]) -> Result<(), NaomeError> {
+    validate_ids(ids, registry(), CONFIG_PATH)
+}
+
+fn registry() -> &'static [StructureAdapter] {
+    &[
+        StructureAdapter {
+            id: "rust",
+            detect: detects_rust_project,
+            source_roots: &["src/**", "crates/*/src/**", "**/crates/*/src/**"],
+            test_roots: &["tests/**", "crates/*/tests/**", "**/crates/*/tests/**"],
+            module_roots: &["src/**", "crates/*/src/**", "**/crates/*/src/**"],
+            allowed_root_files: &["Cargo.toml", "Cargo.lock"],
+        },
+        StructureAdapter {
+            id: "javascript-typescript",
+            detect: detects_javascript_typescript_project,
+            source_roots: &[
+                "src/**",
+                "app/**",
+                "pages/**",
+                "components/**",
+                "packages/*/src/**",
+                "**/packages/*/src/**",
+            ],
+            test_roots: &["test/**", "tests/**", "__tests__/**", "packages/*/tests/**"],
+            module_roots: &["src/**", "app/**", "packages/*/src/**"],
+            allowed_root_files: &[
+                "package.json",
+                "tsconfig.json",
+                "vite.config.ts",
+                "next.config.js",
+            ],
+        },
+    ]
+}

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

@@ -0,0 +1,153 @@
+use crate::paths;
+use crate::quality::types::{QualityMode, QualityViolation};
+
+use super::{applies, push};
+use crate::quality::structure::model::{DirectoryRoleRule, RepositoryStructureModel};
+
+pub(super) fn root_file_sprawl(
+    model: &RepositoryStructureModel,
+    mode: QualityMode,
+    violations: &mut Vec<QualityViolation>,
+) {
+    for path in model
+        .paths
+        .iter()
+        .filter(|path| applies(path, mode) && path.segments.len() == 1)
+    {
+        if paths::matches_any(&path.explanation.path, &model.config.allowed_root_files) {
+            continue;
+        }
+        push_single_path(
+            "root-file-sprawl",
+            &path.explanation.path,
+            format!(
+                "{} is a root-level file without a recognized root role; place new work inside a module, docs, config, or script directory.",
+                path.explanation.path
+            ),
+            violations,
+        );
+    }
+}
+
+pub(super) fn misplaced_files(
+    model: &RepositoryStructureModel,
+    mode: QualityMode,
+    violations: &mut Vec<QualityViolation>,
+) {
+    for path in model.paths.iter().filter(|path| applies(path, mode)) {
+        let role = path.explanation.role.as_str();
+        let misplaced_test =
+            role == "test" && !paths::matches_any(&path.explanation.path, &model.config.test_roots);
+        if misplaced_test {
+            push_single_path(
+                "misplaced-file-role",
+                &path.explanation.path,
+                format!(
+                    "{} is test code outside a configured test root.",
+                    path.explanation.path
+                ),
+                violations,
+            );
+        }
+    }
+}
+
+pub(super) fn directory_role_mixing(
+    model: &RepositoryStructureModel,
+    mode: QualityMode,
+    violations: &mut Vec<QualityViolation>,
+) {
+    for path in model.paths.iter().filter(|path| {
+        applies(path, mode)
+            && matches!(path.explanation.role.as_str(), "generated" | "artifact")
+            && paths::matches_any(&path.explanation.path, &model.config.source_roots)
+    }) {
+        if role_rule_allows_path(model, &path.explanation.path, &path.explanation.role) {
+            continue;
+        }
+        push_single_path(
+            "directory-role-mixing",
+            &path.explanation.path,
+            format!(
+                "{} is {} content under a source root.",
+                path.explanation.path, path.explanation.role
+            ),
+            violations,
+        );
+    }
+
+    for directory in &model.directories {
+        let rule = directory_role_rule_for(model, &directory.path);
+        let allowed_by_rule = rule
+            .filter(|rule| !rule.allowed_roles.is_empty())
+            .is_some_and(|rule| {
+                directory
+                    .roles
+                    .iter()
+                    .all(|role| rule.allowed_roles.iter().any(|allowed| allowed == role))
+            });
+        let max_roles = rule
+            .and_then(|rule| rule.max_roles)
+            .unwrap_or(model.config.limits.max_directory_roles);
+        let incompatible = directory.roles.contains("source")
+            && (directory.roles.contains("generated")
+                || directory.roles.contains("artifact")
+                || directory.roles.contains("dependency/vendor"));
+        let too_many_roles = directory.roles.len() > max_roles
+            && (directory.roles.contains("source")
+                || directory.roles.contains("generated")
+                || directory.roles.contains("artifact"));
+        if (!incompatible || allowed_by_rule) && !too_many_roles {
+            continue;
+        }
+        for path in model.paths.iter().filter(|path| {
+            path.explanation.directory == directory.path
+                && applies(path, mode)
+                && path.explanation.role != "source"
+        }) {
+            push(
+                "directory-role-mixing",
+                &path.explanation.path,
+                format!(
+                    "{} mixes incompatible directory roles: {}.",
+                    directory.path,
+                    directory
+                        .roles
+                        .iter()
+                        .cloned()
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                ),
+                vec![],
+                violations,
+            );
+        }
+    }
+}
+
+fn role_rule_allows_path(model: &RepositoryStructureModel, path: &str, role: &str) -> bool {
+    model.config.directory_role_rules.iter().any(|rule| {
+        !rule.allowed_roles.is_empty()
+            && paths::matches_any(path, &rule.paths)
+            && rule.allowed_roles.iter().any(|allowed| allowed == role)
+    })
+}
+
+fn directory_role_rule_for<'a>(
+    model: &'a RepositoryStructureModel,
+    directory: &str,
+) -> Option<&'a DirectoryRoleRule> {
+    model.config.directory_role_rules.iter().find(|rule| {
+        paths::matches_any(directory, &rule.paths)
+            || paths::matches_any(&format!("{directory}/_"), &rule.paths)
+    })
+}
+
+fn push_single_path(
+    check_id: &str,
+    path: &str,
+    message: String,
+    violations: &mut Vec<QualityViolation>,
+) {
+    push(check_id, path, message, vec![], violations);
+}