@lamentis/naome 1.2.0 → 1.2.1

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

@@ -0,0 +1,144 @@
+use std::collections::BTreeMap;
+
+use crate::quality::structure::model::{RepositoryStructureModel, StructurePath};
+use crate::quality::types::{QualityMode, QualityViolation};
+
+use super::{applies, push, push_with_limit};
+
+const DUMPING_GROUND_NAMES: &[&str] = &["utils", "helpers", "common", "shared", "misc", "lib"];
+
+pub(super) fn dumping_ground_directories(
+    model: &RepositoryStructureModel,
+    mode: QualityMode,
+    violations: &mut Vec<QualityViolation>,
+) {
+    for path in model.paths.iter().filter(|path| applies(path, mode)) {
+        if path.explanation.role != "source" || !is_dumping_ground_path(path) {
+            continue;
+        }
+        push(
+            "dumping-ground-directory",
+            &path.explanation.path,
+            format!(
+                "{} adds source logic under a generic dumping-ground directory; prefer a named module directory.",
+                path.explanation.path
+            ),
+            related_module_paths(model, path),
+            violations,
+        );
+    }
+}
+
+pub(super) fn directory_size(
+    model: &RepositoryStructureModel,
+    mode: QualityMode,
+    violations: &mut Vec<QualityViolation>,
+) {
+    for directory in &model.directories {
+        if directory.file_count <= model.config.limits.max_directory_files {
+            continue;
+        }
+        if mode == QualityMode::Changed && directory.direct_changed_paths.is_empty() {
+            continue;
+        }
+        push_with_limit(
+            "directory-size",
+            &directory.path,
+            format!(
+                "{} contains {} direct files, exceeding the configured limit of {}.",
+                directory.path, directory.file_count, model.config.limits.max_directory_files
+            ),
+            directory.file_count as f64,
+            model.config.limits.max_directory_files as f64,
+            directory.direct_changed_paths.clone(),
+            violations,
+        );
+    }
+}
+
+pub(super) fn path_depth(
+    model: &RepositoryStructureModel,
+    mode: QualityMode,
+    violations: &mut Vec<QualityViolation>,
+) {
+    for path in model.paths.iter().filter(|path| applies(path, mode)) {
+        let depth = path.segments.len();
+        if depth > model.config.limits.max_path_depth {
+            push_with_limit(
+                "path-depth",
+                &path.explanation.path,
+                format!(
+                    "{} has path depth {}, exceeding the configured limit of {}.",
+                    path.explanation.path, depth, model.config.limits.max_path_depth
+                ),
+                depth as f64,
+                model.config.limits.max_path_depth as f64,
+                vec![],
+                violations,
+            );
+        }
+    }
+}
+
+pub(super) fn case_collisions(
+    model: &RepositoryStructureModel,
+    mode: QualityMode,
+    violations: &mut Vec<QualityViolation>,
+) {
+    let mut groups: BTreeMap<String, Vec<String>> = BTreeMap::new();
+    for path in &model.paths {
+        groups
+            .entry(path.explanation.path.to_ascii_lowercase())
+            .or_default()
+            .push(path.explanation.path.clone());
+    }
+    for group in groups.values().filter(|group| group.len() > 1) {
+        let changed_group = group.iter().any(|path| {
+            model.paths.iter().any(|candidate| {
+                candidate.explanation.path == *path && candidate.explanation.changed
+            })
+        });
+        if mode == QualityMode::Changed && !changed_group {
+            continue;
+        }
+        for path in group {
+            push(
+                "case-collision",
+                path,
+                format!(
+                    "{} collides with another path on case-insensitive filesystems.",
+                    path
+                ),
+                group
+                    .iter()
+                    .filter(|other| *other != path)
+                    .cloned()
+                    .collect(),
+                violations,
+            );
+        }
+    }
+}
+
+fn is_dumping_ground_path(path: &StructurePath) -> bool {
+    path.segments.iter().enumerate().any(|(index, segment)| {
+        index > 0
+            && DUMPING_GROUND_NAMES
+                .iter()
+                .any(|name| segment.eq_ignore_ascii_case(name))
+    })
+}
+
+fn related_module_paths(model: &RepositoryStructureModel, path: &StructurePath) -> Vec<String> {
+    let Some(module) = &path.explanation.module else {
+        return Vec::new();
+    };
+    model
+        .paths
+        .iter()
+        .filter(|candidate| candidate.explanation.module.as_ref() == Some(module))
+        .map(|candidate| candidate.explanation.path.clone())
+        .filter(|candidate| candidate != &path.explanation.path)
+        .take(10)
+        .collect()
+}

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

@@ -0,0 +1,63 @@
+use std::collections::BTreeSet;
+
+use crate::quality::structure::model::{RepositoryStructureModel, StructurePath};
+use crate::quality::types::{QualityMode, QualityViolation};
+
+use super::{applies, push};
+
+pub(super) fn test_source_pairing(
+    model: &RepositoryStructureModel,
+    mode: QualityMode,
+    violations: &mut Vec<QualityViolation>,
+) {
+    for source in model.paths.iter().filter(|path| {
+        path.explanation.role == "source" && applies(path, mode) && !is_entrypoint(path)
+    }) {
+        if has_related_test(model, source) {
+            continue;
+        }
+        push(
+            "test-source-pairing",
+            &source.explanation.path,
+            format!(
+                "{} changed without a nearby or module-matched test file.",
+                source.explanation.path
+            ),
+            vec![],
+            violations,
+        );
+    }
+}
+
+fn has_related_test(model: &RepositoryStructureModel, source: &StructurePath) -> bool {
+    let tokens = source_tokens(source);
+    model.paths.iter().any(|candidate| {
+        candidate.explanation.role == "test"
+            && tokens.iter().any(|token| {
+                candidate
+                    .explanation
+                    .path
+                    .to_ascii_lowercase()
+                    .contains(token)
+            })
+    })
+}
+
+fn source_tokens(source: &StructurePath) -> BTreeSet<String> {
+    source
+        .segments
+        .iter()
+        .flat_map(|segment| segment.split(['.', '-', '_']))
+        .map(str::to_ascii_lowercase)
+        .filter(|token| token.len() > 2 && token != "src" && token != "mod")
+        .collect()
+}
+
+fn is_entrypoint(path: &StructurePath) -> bool {
+    path.segments.last().is_some_and(|file| {
+        matches!(
+            file.as_str(),
+            "main.rs" | "main.go" | "index.js" | "index.ts"
+        )
+    })
+}

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

@@ -0,0 +1,124 @@
+mod basic;
+mod directory;
+mod pairing;
+
+use super::model::{RepositoryStructureModel, StructurePath};
+use crate::quality::scanner::stable_fingerprint;
+use crate::quality::types::{QualityMode, QualityViolation};
+
+pub fn run_structure_checks(
+    model: &RepositoryStructureModel,
+    mode: QualityMode,
+) -> Vec<QualityViolation> {
+    let mut violations = Vec::new();
+    if check_enabled(model, "root-file-sprawl") {
+        basic::root_file_sprawl(model, mode, &mut violations);
+    }
+    if check_enabled(model, "misplaced-file-role") {
+        basic::misplaced_files(model, mode, &mut violations);
+    }
+    if check_enabled(model, "directory-role-mixing") {
+        basic::directory_role_mixing(model, mode, &mut violations);
+    }
+    if check_enabled(model, "dumping-ground-directory") {
+        directory::dumping_ground_directories(model, mode, &mut violations);
+    }
+    if check_enabled(model, "directory-size") {
+        directory::directory_size(model, mode, &mut violations);
+    }
+    if check_enabled(model, "path-depth") {
+        directory::path_depth(model, mode, &mut violations);
+    }
+    if check_enabled(model, "case-collision") {
+        directory::case_collisions(model, mode, &mut violations);
+    }
+    if check_enabled(model, "test-source-pairing") {
+        pairing::test_source_pairing(model, mode, &mut violations);
+    }
+    violations.sort_by(|left, right| {
+        left.path
+            .cmp(&right.path)
+            .then(left.check_id.cmp(&right.check_id))
+            .then(left.fingerprint.cmp(&right.fingerprint))
+    });
+    violations
+}
+
+fn check_enabled(model: &RepositoryStructureModel, check_id: &str) -> bool {
+    !model
+        .config
+        .disabled_checks
+        .iter()
+        .any(|disabled| disabled == check_id)
+}
+
+fn applies(path: &StructurePath, mode: QualityMode) -> bool {
+    mode == QualityMode::Report || path.explanation.changed
+}
+
+fn push(
+    check_id: &str,
+    path: &str,
+    message: String,
+    related_paths: Vec<String>,
+    violations: &mut Vec<QualityViolation>,
+) {
+    push_with_optional_limit(
+        check_id,
+        path,
+        message,
+        None,
+        None,
+        related_paths,
+        violations,
+    );
+}
+
+fn push_with_limit(
+    check_id: &str,
+    path: &str,
+    message: String,
+    value: f64,
+    limit: f64,
+    related_paths: Vec<String>,
+    violations: &mut Vec<QualityViolation>,
+) {
+    push_with_optional_limit(
+        check_id,
+        path,
+        message,
+        Some(value),
+        Some(limit),
+        related_paths,
+        violations,
+    );
+}
+
+fn push_with_optional_limit(
+    check_id: &str,
+    path: &str,
+    message: String,
+    value: Option<f64>,
+    limit: Option<f64>,
+    related_paths: Vec<String>,
+    violations: &mut Vec<QualityViolation>,
+) {
+    if violations
+        .iter()
+        .any(|existing| existing.check_id == check_id && existing.path == path)
+    {
+        return;
+    }
+    violations.push(QualityViolation {
+        check_id: check_id.to_string(),
+        severity: "blocking".to_string(),
+        path: path.to_string(),
+        line: None,
+        message: message.clone(),
+        value,
+        limit,
+        fingerprint: stable_fingerprint(&[check_id, path, &message]),
+        related_paths,
+        baseline: false,
+    });
+}

package/crates/naome-core/src/quality/structure/classify/roles.rs

@@ -0,0 +1,188 @@
+use crate::paths;
+
+use crate::quality::structure::model::RepositoryStructureConfig;
+
+pub fn role_for(path: &str, segments: &[String], config: &RepositoryStructureConfig) -> String {
+    let lower = path.to_ascii_lowercase();
+    if has_segment(segments, &["node_modules", "vendor", "third_party"]) {
+        return "dependency/vendor".to_string();
+    }
+    if paths::matches_any(path, &config.generated_roots)
+        || has_segment(segments, &["generated", "__generated__", "codegen"])
+    {
+        return "generated".to_string();
+    }
+    if paths::matches_any(path, &config.artifact_roots) || is_artifact_path(&lower) {
+        return "artifact".to_string();
+    }
+    if paths::matches_any(path, &config.test_roots) || is_test_path(&lower, segments) {
+        return "test".to_string();
+    }
+    if paths::matches_any(path, &config.docs_roots) || is_docs_path(&lower, segments) {
+        return "docs".to_string();
+    }
+    if is_config_path(path, &lower, segments, config) {
+        return "config".to_string();
+    }
+    if is_script_path(&lower, segments) {
+        return "script".to_string();
+    }
+    if paths::matches_any(path, &config.source_roots) || language_for(path).is_some() {
+        return "source".to_string();
+    }
+    "unknown".to_string()
+}
+
+pub fn module_for(
+    path: &str,
+    segments: &[String],
+    config: &RepositoryStructureConfig,
+) -> Option<String> {
+    for root in &config.module_roots {
+        if !paths::matches_any(path, &[root.clone()]) {
+            continue;
+        }
+        if let Some(module) = module_from_wildcard_root(segments, root) {
+            return Some(module);
+        }
+        let root_prefix = root.trim_end_matches("/**");
+        let after_root = path.strip_prefix(root_prefix).unwrap_or(path);
+        let candidate = after_root.trim_start_matches('/').split('/').next()?;
+        if !candidate.is_empty() && candidate.contains('.') {
+            return stem(candidate);
+        }
+        if !candidate.is_empty() {
+            return Some(candidate.to_string());
+        }
+    }
+    if segments.len() >= 3 && (segments[0] == "packages" || segments[0] == "crates") {
+        return Some(segments[1].clone());
+    }
+    segments
+        .iter()
+        .rev()
+        .nth(1)
+        .filter(|segment| !is_role_segment(segment))
+        .cloned()
+}
+
+fn module_from_wildcard_root(segments: &[String], root: &str) -> Option<String> {
+    let root_segments = root.trim_end_matches("/**").split('/').collect::<Vec<_>>();
+    for (index, segment) in root_segments.iter().enumerate() {
+        if *segment == "*" {
+            return segments
+                .get(index)
+                .filter(|segment| !segment.is_empty())
+                .cloned();
+        }
+    }
+
+    if root_segments.first() == Some(&"**") {
+        let anchor = root_segments
+            .iter()
+            .skip(1)
+            .find(|segment| !segment.contains('*'))?;
+        if let Some(src_index) = segments.iter().position(|segment| segment == anchor) {
+            return src_index
+                .checked_sub(1)
+                .and_then(|module_index| segments.get(module_index))
+                .filter(|segment| !segment.is_empty())
+                .cloned();
+        }
+    }
+
+    None
+}
+
+pub fn layer_for(path: &str, role: &str, config: &RepositoryStructureConfig) -> String {
+    config
+        .layer_rules
+        .iter()
+        .find(|rule| paths::matches_any(path, &rule.paths))
+        .map(|rule| rule.layer.clone())
+        .unwrap_or_else(|| role.to_string())
+}
+
+pub fn language_for(path: &str) -> Option<String> {
+    let lower = path.to_ascii_lowercase();
+    let language = if lower.ends_with(".rs") {
+        "rust"
+    } else if lower.ends_with(".ts") || lower.ends_with(".tsx") {
+        "typescript"
+    } else if lower.ends_with(".js")
+        || lower.ends_with(".jsx")
+        || lower.ends_with(".mjs")
+        || lower.ends_with(".cjs")
+    {
+        "javascript"
+    } else if lower.ends_with(".py") {
+        "python"
+    } else if lower.ends_with(".go") {
+        "go"
+    } else if lower.ends_with(".swift") {
+        "swift"
+    } else {
+        return None;
+    };
+    Some(language.to_string())
+}
+
+fn is_test_path(lower: &str, segments: &[String]) -> bool {
+    lower.contains(".test.")
+        || lower.contains(".spec.")
+        || lower.ends_with("_test.rs")
+        || has_segment(segments, &["test", "tests", "__tests__"])
+}
+
+fn is_docs_path(lower: &str, segments: &[String]) -> bool {
+    lower.ends_with(".md")
+        || lower.ends_with(".mdx")
+        || lower.ends_with(".rst")
+        || has_segment(segments, &["docs", "doc"])
+}
+
+fn is_config_path(
+    path: &str,
+    lower: &str,
+    segments: &[String],
+    config: &RepositoryStructureConfig,
+) -> bool {
+    paths::matches_any(path, &config.allowed_root_files)
+        || segments.len() == 1 && (lower.starts_with('.') || lower.ends_with(".toml"))
+        || lower.ends_with(".json")
+        || lower.ends_with(".yaml")
+        || lower.ends_with(".yml")
+}
+
+fn is_script_path(lower: &str, segments: &[String]) -> bool {
+    has_segment(segments, &["scripts", "bin"]) || lower.ends_with(".sh") || lower.ends_with(".zsh")
+}
+
+fn is_artifact_path(lower: &str) -> bool {
+    lower.ends_with(".tmp")
+        || lower.ends_with(".log")
+        || lower.ends_with(".map")
+        || lower.ends_with(".min.js")
+}
+
+fn has_segment(segments: &[String], expected: &[&str]) -> bool {
+    segments.iter().any(|segment| {
+        let lower = segment.to_ascii_lowercase();
+        expected.iter().any(|value| *value == lower)
+    })
+}
+
+fn is_role_segment(segment: &str) -> bool {
+    matches!(
+        segment,
+        "src" | "test" | "tests" | "docs" | "doc" | "scripts" | "generated"
+    )
+}
+
+fn stem(file_name: &str) -> Option<String> {
+    file_name
+        .split('.')
+        .next()
+        .filter(|value| !value.is_empty())
+        .map(ToString::to_string)
+}

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

@@ -0,0 +1,94 @@
+mod roles;
+
+use std::collections::{BTreeMap, BTreeSet, HashSet};
+
+use crate::paths;
+
+use super::model::{
+    RepositoryStructureConfig, RepositoryStructureModel, StructureDirectory, StructurePath,
+    StructurePathExplanation,
+};
+use roles::{language_for, layer_for, module_for, role_for};
+
+pub fn build_structure_model(
+    config: RepositoryStructureConfig,
+    repo_paths: &[String],
+    changed_paths: &[String],
+    baseline_fingerprints: &HashSet<String>,
+) -> RepositoryStructureModel {
+    let changed = changed_paths.iter().cloned().collect::<HashSet<_>>();
+    let mut paths = repo_paths
+        .iter()
+        .filter(|path| !paths::matches_any(path, &config.ignored_paths))
+        .map(|path| classify_path(path, &config, changed.contains(path), baseline_fingerprints))
+        .collect::<Vec<_>>();
+    paths.sort_by(|left, right| left.explanation.path.cmp(&right.explanation.path));
+    let directories = directories_for(&paths);
+    RepositoryStructureModel {
+        config,
+        paths,
+        directories,
+    }
+}
+
+fn classify_path(
+    path: &str,
+    config: &RepositoryStructureConfig,
+    changed: bool,
+    _baseline_fingerprints: &HashSet<String>,
+) -> StructurePath {
+    let segments = path.split('/').map(ToString::to_string).collect::<Vec<_>>();
+    let directory = directory_of(path);
+    let role = role_for(path, &segments, config);
+    let module = module_for(path, &segments, config);
+    let language = language_for(path);
+    let layer = layer_for(path, &role, config);
+    let generated = role == "generated";
+    StructurePath {
+        explanation: StructurePathExplanation {
+            path: path.to_string(),
+            role,
+            module,
+            layer,
+            language,
+            generated,
+            debt: false,
+            changed,
+            directory,
+        },
+        segments,
+    }
+}
+
+fn directories_for(paths: &[StructurePath]) -> Vec<StructureDirectory> {
+    let mut dirs: BTreeMap<String, StructureDirectory> = BTreeMap::new();
+    for path in paths {
+        let dir = path.explanation.directory.clone();
+        let entry = dirs
+            .entry(dir.clone())
+            .or_insert_with(|| StructureDirectory {
+                path: dir,
+                roles: BTreeSet::new(),
+                modules: BTreeSet::new(),
+                file_count: 0,
+                direct_changed_paths: Vec::new(),
+            });
+        entry.file_count += 1;
+        entry.roles.insert(path.explanation.role.clone());
+        if let Some(module) = &path.explanation.module {
+            entry.modules.insert(module.clone());
+        }
+        if path.explanation.changed {
+            entry
+                .direct_changed_paths
+                .push(path.explanation.path.clone());
+        }
+    }
+    dirs.into_values().collect()
+}
+
+fn directory_of(path: &str) -> String {
+    path.rsplit_once('/')
+        .map(|(directory, _)| directory.to_string())
+        .unwrap_or_else(|| ".".to_string())
+}

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