wowlab_tidy/languages/rust/rules/hygiene/

spec_module_layout.rs

#[cfg(test)]
use googletest::prelude::*;
use wowlab_fs::{
    directory::{self, EntryKind},
    path::Path,
};

use crate::{Example, FileCtx, Violation, violation};

const HOOKS_MOD: &str = "crates/engine-content/src/hooks/mod.rs";
const HOOKS_TREE: &str = "crates/engine-content/src/hooks/";
const BUG_MACRO: &str = "define_game_bug!";

#[rustfmt::skip]
const EXAMPLES: &[Example] = &[
    Example {
        label: "canonical spec directory",
        code: "mod.rs\nitems/\nshared/\narms_warrior/mod.rs\narms_warrior/hooks.rs\narms_warrior/config.rs\narcane_mage/mod.rs\narcane_mage/hooks.rs",
        pass: true,
    },
    Example {
        label: "top-level spec file",
        code: "mod.rs\narms_warrior.rs",
        pass: false,
    },
    Example {
        label: "spec directory missing mod.rs",
        code: "mod.rs\narms_warrior/hooks.rs",
        pass: false,
    },
    Example {
        label: "spec directory missing hook implementation",
        code: "mod.rs\narms_warrior/mod.rs",
        pass: false,
    },
];

crate::line_rule!(
    spec_module_layout,
    "Enforce the minimum directory layout for engine-content spec hook modules, including `define_game_bug!` placement in `bugs.rs`.",
    "A uniform spec layout keeps hook implementations discoverable, prevents new single-file specs from bypassing the module structure, and keeps every modeled live-game bug findable in one file per spec.",
    Medium,
);

fn check_spec_module_layout(ctx: &FileCtx<'_>) -> Vec<Violation> {
    if ctx.rel == HOOKS_MOD {
        return check_hooks_directory(ctx.path.parent().unwrap_or(ctx.path), ctx.rel);
    }

    check_bug_declaration_placement(ctx)
}

fn check_bug_declaration_placement(ctx: &FileCtx<'_>) -> Vec<Violation> {
    if !ctx.rel.starts_with(HOOKS_TREE) || ctx.rel.ends_with("/bugs.rs") {
        return Vec::new();
    }

    ctx.lines
        .iter()
        .enumerate()
        .filter(|(_, line)| line.contains(BUG_MACRO))
        .map(|(index, _)| {
            violation(
                ctx.rel,
                index + 1,
                "`define_game_bug!` declarations belong in the spec's `bugs.rs`",
            )
        })
        .collect()
}

fn check_hooks_directory(hooks: &Path, anchor_rel: &str) -> Vec<Violation> {
    let Ok(entries) = directory::entries(hooks) else {
        return vec![violation(
            anchor_rel,
            1,
            "unable to inspect the engine-content hooks directory",
        )];
    };

    let mut violations = Vec::new();

    for entry in entries {
        let Some(name) = entry.path().file_name() else {
            continue;
        };
        let name = name.to_string_lossy();

        if name == "mod.rs" || name == "items" || name == "shared" {
            continue;
        }

        let path = entry.path();

        if entry.kind() != EntryKind::Directory {
            violations.push(violation(
                anchor_rel,
                1,
                format!("top-level hooks child `{name}` must be a spec directory"),
            ));
            continue;
        }

        if !directory::inspect(&path.join("mod.rs"))
            .ok()
            .flatten()
            .is_some_and(|entry| entry.kind() == EntryKind::File)
        {
            violations.push(violation(
                anchor_rel,
                1,
                format!("spec directory `{name}` is missing required `mod.rs`"),
            ));
        }

        if !directory::inspect(&path.join("hooks.rs"))
            .ok()
            .flatten()
            .is_some_and(|entry| entry.kind() == EntryKind::File)
        {
            violations.push(violation(
                anchor_rel,
                1,
                format!("spec directory `{name}` is missing required `hooks.rs`"),
            ));
        }
    }

    violations
}

#[cfg(test)]
mod tests {
    use super::*;

    #[gtest]
    fn examples() -> Result<()> {
        for (index, example) in EXAMPLES.iter().enumerate() {
            let temporary =
                wowlab_fs::temporary::Directory::with_prefix(&format!("tidy-layout-{index}-"))
                    .or_fail()?;
            let root = temporary.path();
            let hooks = root.join("hooks");

            directory::ensure(&hooks).or_fail()?;

            for fixture_path in example.code.lines() {
                let path = hooks.join(fixture_path.trim_end_matches('/'));

                if fixture_path.ends_with('/') {
                    directory::ensure(&path).or_fail()?;
                } else {
                    if let Some(parent) = path.parent() {
                        directory::ensure(parent).or_fail()?;
                    }

                    wowlab_fs::file::write_text(&path, "").or_fail()?;
                }
            }

            let violations = check_hooks_directory(&hooks, HOOKS_MOD);

            verify_eq!(violations.is_empty(), example.pass)?;
        }

        Ok(())
    }

    #[gtest]
    fn bug_declarations_must_live_in_bugs_rs() -> Result<()> {
        let cfg = crate::infra::config::Config::generate_default(&[]);
        let source =
            "wowlab_engine_ports::define_game_bug! {\n    static BUG_X = (\"x\", \"y\");\n}\n";
        let lines: Vec<&str> = source.lines().collect();
        let check = |rel: &str| {
            check_bug_declaration_placement(&FileCtx {
                rel,
                path: Path::new(rel),
                lines: &lines,
                contents: source,
                config: &cfg,
            })
        };

        verify_false!(
            check("crates/engine-content/src/hooks/elemental_shaman/hooks.rs").is_empty()
        )?;
        verify_true!(check("crates/engine-content/src/hooks/elemental_shaman/bugs.rs").is_empty())?;
        verify_true!(check("crates/engine-ports/src/game_bugs.rs").is_empty())?;

        Ok(())
    }
}