normalize-rules 0.3.1

//! Rules management service for server-less CLI.

use normalize_output::OutputFormatter;
use normalize_output::diagnostics::DiagnosticsReport;
use server_less::cli;
use std::cell::Cell;
use std::path::Path;

use normalize_syntax_rules::apply_fixes;

use crate::cmd_rules::run_syntax_rules;
use crate::runner::{
    ListFilters, RuleInfoReport, RuleKind, RulesListReport, RulesRunConfig, RulesTagsReport,
    add_rule, apply_native_rules_config, build_list_report, enable_disable, list_tags_structured,
    remove_rule, run_rules_report, show_rule_structured, update_rules,
};

/// Typed config for summary rules (stale-summary, missing-summary).
/// Deserialized from `extra` fields on the `RuleOverride` via `rule_config()`.
#[derive(serde::Deserialize, Default)]
struct SummaryRuleConfig {
    #[serde(
        default,
        deserialize_with = "normalize_rules_config::deserialize_one_or_many"
    )]
    filenames: Vec<String>,
    #[serde(
        default,
        deserialize_with = "normalize_rules_config::deserialize_one_or_many"
    )]
    paths: Vec<String>,
}

/// Typed config for threshold-based rules (long-file, high-complexity, long-function).
/// Deserialized from `extra` fields on the `RuleOverride` via `rule_config()`.
#[derive(serde::Deserialize, Default)]
struct ThresholdConfig {
    threshold: Option<usize>,
}

/// Resolve pretty mode: enabled on TTY (or forced via --pretty), disabled by --compact.
fn resolve_pretty(pretty: bool, compact: bool) -> bool {
    use std::io::IsTerminal;
    !compact && (pretty || std::io::stdout().is_terminal())
}

/// A single error found when compiling a `.dl` rules file.
#[derive(serde::Serialize, schemars::JsonSchema)]
pub struct CompileError {
    /// 1-based line number in the source file (0 = unknown / not line-specific).
    pub line: usize,
    /// 1-based column number in the source file (0 = unknown).
    pub col: usize,
    /// Human-readable description of the error.
    pub message: String,
}

/// A single warning found when compiling a `.dl` rules file.
#[derive(serde::Serialize, schemars::JsonSchema)]
pub struct CompileWarning {
    /// 1-based line number in the source file (0 = unknown / not line-specific).
    pub line: usize,
    /// 1-based column number in the source file (0 = unknown).
    pub col: usize,
    /// Human-readable description of the warning.
    pub message: String,
}

/// Report returned by `normalize rules compile`.
#[derive(serde::Serialize, schemars::JsonSchema)]
pub struct RulesCompileReport {
    /// Path to the `.dl` file that was checked.
    pub path: String,
    /// `true` if no errors were found; `false` otherwise.
    pub valid: bool,
    /// Hard errors — the program cannot run correctly.
    pub errors: Vec<CompileError>,
    /// Warnings — the program will run but may not behave as expected.
    pub warnings: Vec<CompileWarning>,
    /// All relation names referenced in rule heads or bodies (sorted).
    pub relations_used: Vec<String>,
}

impl OutputFormatter for RulesCompileReport {
    fn format_text(&self) -> String {
        let mut out = String::new();
        for e in &self.errors {
            if e.line > 0 {
                out.push_str(&format!(
                    "{}:{}:{}: error: {}\n",
                    self.path, e.line, e.col, e.message
                ));
            } else {
                out.push_str(&format!("{}: error: {}\n", self.path, e.message));
            }
        }
        for w in &self.warnings {
            if w.line > 0 {
                out.push_str(&format!(
                    "{}:{}:{}: warning: {}\n",
                    self.path, w.line, w.col, w.message
                ));
            } else {
                out.push_str(&format!("{}: warning: {}\n", self.path, w.message));
            }
        }
        if self.valid {
            out.push_str(&format!(
                "{}: ok — {} relation{} used\n",
                self.path,
                self.relations_used.len(),
                if self.relations_used.len() == 1 {
                    ""
                } else {
                    "s"
                },
            ));
        }
        out
    }
}

/// Report returned by `normalize rules validate`.
#[derive(serde::Serialize, schemars::JsonSchema)]
pub struct RulesValidateReport {
    /// Path to the config file that was checked.
    pub config_path: String,
    /// Overall validity — false if any errors were found.
    pub valid: bool,
    /// TOML parse errors or unknown rule IDs.
    pub errors: Vec<String>,
    /// Non-fatal warnings (e.g. disabled rules that have no effect).
    pub warnings: Vec<String>,
    /// Number of per-rule overrides found in the config.
    pub rule_count: usize,
    /// Number of global-allow patterns.
    pub global_allow_count: usize,
}

impl OutputFormatter for RulesValidateReport {
    fn format_text(&self) -> String {
        let mut out = String::new();
        if self.valid {
            out.push_str("Rules configuration is valid\n");
        } else {
            out.push_str("Rules configuration has errors\n");
        }
        out.push('\n');
        out.push_str(&format!("Config file: {}\n", self.config_path));

        if self.valid {
            out.push_str(&format!(
                "  {} rule override{}, {} global-allow pattern{}\n",
                self.rule_count,
                if self.rule_count == 1 { "" } else { "s" },
                self.global_allow_count,
                if self.global_allow_count == 1 {
                    ""
                } else {
                    "s"
                },
            ));
        } else {
            out.push_str(&format!(
                "  {} error{}:\n\n",
                self.errors.len(),
                if self.errors.len() == 1 { "" } else { "s" }
            ));
            for e in &self.errors {
                out.push_str(&format!("  error: {e}\n"));
            }
        }

        if !self.warnings.is_empty() {
            out.push('\n');
            for w in &self.warnings {
                out.push_str(&format!("  warning: {w}\n"));
            }
        }

        out
    }
}

/// One mismatch found during `normalize rules test`.
#[derive(serde::Serialize, schemars::JsonSchema)]
pub struct TestMismatch {
    /// 1-based line number.
    pub line: usize,
    /// Rule ID involved in the mismatch.
    pub rule_id: String,
    /// "expected finding missing" or "unexpected finding"
    pub kind: String,
}

/// Report returned by `normalize rules test`.
#[derive(serde::Serialize, schemars::JsonSchema)]
pub struct RulesTestReport {
    /// Path to the file that was tested.
    pub file: String,
    /// `true` if all assertions passed.
    pub passed: bool,
    /// Number of `// error[...]` annotations found in the file.
    pub annotations: usize,
    /// Number of findings from rule execution.
    pub findings: usize,
    /// List of mismatches (empty when passed = true).
    pub mismatches: Vec<TestMismatch>,
}

impl OutputFormatter for RulesTestReport {
    fn format_text(&self) -> String {
        if self.passed {
            format!(
                "PASS {} ({} annotation(s), {} finding(s))\n",
                self.file, self.annotations, self.findings
            )
        } else {
            let mut out = format!("FAIL {}:\n", self.file);
            for m in &self.mismatches {
                out.push_str(&format!("  line {}: {} — {}\n", m.line, m.rule_id, m.kind));
            }
            out
        }
    }

    fn format_pretty(&self) -> String {
        use nu_ansi_term::Color;
        if self.passed {
            format!(
                "{} {} ({} annotation(s), {} finding(s))\n",
                Color::Green.bold().paint("PASS"),
                self.file,
                self.annotations,
                self.findings
            )
        } else {
            let mut out = format!("{} {}:\n", Color::Red.bold().paint("FAIL"), self.file);
            for m in &self.mismatches {
                out.push_str(&format!(
                    "  line {}: {} — {}\n",
                    m.line,
                    Color::Yellow.paint(&m.rule_id),
                    m.kind
                ));
            }
            out
        }
    }
}

/// One expected finding in a fixture `expected.json` file.
#[derive(
    Debug,
    Clone,
    serde::Serialize,
    serde::Deserialize,
    schemars::JsonSchema,
    PartialEq,
    Eq,
    PartialOrd,
    Ord,
)]
pub struct FixtureExpectedFinding {
    /// Rule ID that should fire (e.g. `rust/unwrap-in-impl`).
    pub rule: String,
    /// Source file path, relative to the fixture's `input/` dir (or the input filename for single-file cases).
    pub file: String,
    /// 1-based line number.
    pub line: usize,
    /// Diagnostic message (substring match — actual message must contain this).
    pub message: String,
}

/// Result for a single fixture case.
#[derive(serde::Serialize, schemars::JsonSchema)]
pub struct FixtureCaseResult {
    /// Case name (directory or file stem).
    pub case: String,
    /// `true` if actual findings matched expected.
    pub passed: bool,
    /// Lines describing mismatches (empty when passed).
    pub diff: Vec<String>,
}

/// Report returned by `normalize rules test-fixtures`.
#[derive(serde::Serialize, schemars::JsonSchema)]
pub struct RulesFixtureTestReport {
    /// Root directory that was scanned for fixtures.
    pub fixture_dir: String,
    /// Results for each discovered case.
    pub cases: Vec<FixtureCaseResult>,
    /// Number of cases that passed.
    pub passed: usize,
    /// Number of cases that failed.
    pub failed: usize,
    /// `true` when run with --update (rewrites expected.json).
    pub updated: bool,
}

impl OutputFormatter for RulesFixtureTestReport {
    fn format_text(&self) -> String {
        let mut out = String::new();
        for c in &self.cases {
            if c.passed {
                out.push_str(&format!("PASS {}\n", c.case));
            } else {
                out.push_str(&format!("FAIL {}:\n", c.case));
                for line in &c.diff {
                    out.push_str(&format!("  {line}\n"));
                }
            }
        }
        if self.updated {
            out.push_str(&format!("\nUpdated {} case(s).\n", self.cases.len()));
        } else {
            out.push_str(&format!(
                "\n{} passed, {} failed\n",
                self.passed, self.failed
            ));
        }
        out
    }

    fn format_pretty(&self) -> String {
        use nu_ansi_term::Color;
        let mut out = String::new();
        for c in &self.cases {
            if c.passed {
                out.push_str(&format!(
                    "{} {}\n",
                    Color::Green.bold().paint("PASS"),
                    c.case
                ));
            } else {
                out.push_str(&format!(
                    "{} {}:\n",
                    Color::Red.bold().paint("FAIL"),
                    c.case
                ));
                for line in &c.diff {
                    out.push_str(&format!("  {}\n", Color::Yellow.paint(line.as_str())));
                }
            }
        }
        if self.updated {
            out.push_str(&format!("\n{} case(s) updated.\n", self.cases.len()));
        } else {
            out.push_str(&format!(
                "\n{} passed, {} failed\n",
                Color::Green.paint(self.passed.to_string()),
                if self.failed > 0 {
                    Color::Red.paint(self.failed.to_string()).to_string()
                } else {
                    "0".to_string()
                }
            ));
        }
        out
    }
}

/// Rules management sub-service.
pub struct RulesService {
    pretty: Cell<bool>,
    /// Set to true when --sarif is active; display_run emits SARIF instead of text.
    sarif: Cell<bool>,
    /// Issue display limit for text output (default 50).
    limit: Cell<usize>,
}

impl RulesService {
    pub fn new(pretty: &Cell<bool>) -> Self {
        Self {
            pretty: Cell::new(pretty.get()),
            sarif: Cell::new(false),
            limit: Cell::new(50),
        }
    }

    fn resolve_format(&self, pretty: bool, compact: bool) {
        self.pretty.set(resolve_pretty(pretty, compact));
    }
}

/// Generic result type for rule operations.
#[derive(serde::Serialize, schemars::JsonSchema)]
pub struct RuleShowReport {
    pub success: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub message: Option<String>,
}

impl OutputFormatter for RuleShowReport {
    fn format_text(&self) -> String {
        if let Some(ref msg) = self.message {
            msg.clone()
        } else if self.success {
            "Done".to_string()
        } else {
            "Failed".to_string()
        }
    }
}

impl RulesService {
    /// Generic display bridge that routes to `OutputFormatter::format_text()`.
    fn display_output<T: OutputFormatter>(&self, value: &T) -> String {
        if self.pretty.get() {
            value.format_pretty()
        } else {
            value.format_text()
        }
    }

    fn display_run(&self, r: &DiagnosticsReport) -> String {
        if self.sarif.get() {
            return r.format_sarif();
        }
        if self.pretty.get() {
            r.format_pretty()
        } else {
            r.format_text_limited(Some(self.limit.get()))
        }
    }
}

#[cli(
    name = "rules",
    description = "Manage and run analysis rules (syntax + fact + native)",
    global = [
        pretty = "Human-friendly output with colors and formatting",
        compact = "Compact output without colors (overrides TTY detection)",
    ]
)]
impl RulesService {
    /// List all rules (syntax + fact, builtin + user)
    ///
    /// Examples:
    ///   normalize rules list                   # all rules with status
    ///   normalize rules list --pretty          # with full descriptions
    ///   normalize rules list --json            # machine-readable output
    #[cli(display_with = "display_output")]
    #[allow(clippy::too_many_arguments)]
    pub fn list(
        &self,
        #[param(short = 't', help = "Filter by rule type (all, syntax, fact)")] r#type: Option<
            String,
        >,
        #[param(help = "Filter by tag")] tag: Option<String>,
        #[param(help = "Filter to enabled rules only")] enabled: bool,
        #[param(help = "Filter to disabled rules only")] disabled: bool,
        #[param(short = 'r', help = "Root directory (defaults to current directory)")] root: Option<
            String,
        >,
        pretty: bool,
        compact: bool,
    ) -> Result<RulesListReport, String> {
        let effective_root = root
            .as_deref()
            .map(std::path::PathBuf::from)
            .map(Ok)
            .unwrap_or_else(std::env::current_dir)
            .map_err(|e| format!("Failed to get current directory: {e}"))?;
        self.resolve_format(pretty, compact);
        let config = load_rules_config(&effective_root);
        let rule_type: RuleKind = r#type
            .as_deref()
            .unwrap_or("all")
            .parse()
            .unwrap_or_default();
        let report = build_list_report(
            &effective_root,
            &ListFilters {
                type_filter: &rule_type,
                tag: tag.as_deref(),
                enabled,
                disabled,
            },
            &config,
        );
        Ok(report)
    }

    /// Run rules against the codebase
    ///
    /// Examples:
    ///   normalize rules run                    # run all enabled rules
    ///   normalize rules run src/               # run on specific directory
    ///   normalize rules run --rule rust/unwrap-in-impl   # single rule
    ///   normalize rules run --pretty           # colored output with details
    ///   normalize rules run --type syntax      # only syntax rules
    ///   normalize rules run --only "*.rs"      # only Rust files
    ///   normalize rules run --exclude "tests/" # skip test directories
    ///   normalize rules run --files src/main.rs src/lib.rs  # explicit file list
    #[cli(display_with = "display_run")]
    #[allow(clippy::too_many_arguments)]
    pub async fn run(
        &self,
        #[param(help = "Specific rule ID to run")] rule: Option<String>,
        #[param(help = "Filter by tag")] tag: Option<String>,
        #[param(help = "Apply auto-fixes (syntax rules only)")] fix: bool,
        #[param(help = "Output in SARIF format")] sarif: bool,
        #[param(positional, help = "Target directory or file")] target: Option<String>,
        #[param(
            short = 't',
            help = "Filter by rule type (all, syntax, fact, native, sarif)"
        )]
        r#type: Option<String>,
        #[param(help = "Debug flags (comma-separated)")] debug: Vec<String>,
        #[param(short = 'r', help = "Root directory (defaults to current directory)")] root: Option<
            String,
        >,
        #[param(help = "Exit 0 even when error-severity issues are found")] no_fail: bool,
        #[param(help = "Maximum number of issues to show in detail (default: 50)")] limit: Option<
            usize,
        >,
        #[param(help = "Only include files matching glob patterns")] only: Vec<String>,
        #[param(help = "Exclude files matching glob patterns")] exclude: Vec<String>,
        #[param(help = "Explicit file paths to check (bypasses file walker)")] files: Vec<String>,
        pretty: bool,
        compact: bool,
    ) -> Result<DiagnosticsReport, String> {
        let effective_root = root
            .as_deref()
            .map(std::path::PathBuf::from)
            .map(Ok)
            .unwrap_or_else(std::env::current_dir)
            .map_err(|e| format!("Failed to get current directory: {e}"))?;
        self.resolve_format(pretty, compact);
        self.sarif.set(sarif);
        // Cap limit to prevent accidental OOM from huge values (e.g. usize::MAX).
        let limit = limit.unwrap_or(50).min(10_000);
        self.limit.set(limit);
        let config = load_rules_config(&effective_root);
        let rule_type: RuleKind = r#type
            .as_deref()
            .unwrap_or("all")
            .parse()
            .unwrap_or_default();
        let target_root = target
            .as_deref()
            .map(std::path::PathBuf::from)
            .unwrap_or_else(|| effective_root.clone());
        let project_root = effective_root.clone();

        // Resolve --files to absolute paths (relative to effective_root).
        // When `target` is a single file, treat it as an explicit file too so the
        // daemon can hit the per-file fast path instead of walking from `target_root`.
        let explicit_files: Option<Vec<std::path::PathBuf>> = if files.is_empty() {
            if target_root.is_file() {
                Some(vec![target_root.clone()])
            } else {
                None
            }
        } else {
            Some(
                files
                    .iter()
                    .map(|f| {
                        let p = std::path::PathBuf::from(f);
                        if p.is_absolute() {
                            p
                        } else {
                            effective_root.join(p)
                        }
                    })
                    .collect(),
            )
        };

        // Parse --only / --exclude into a PathFilter early so every engine can
        // skip non-matching files *before* doing expensive work (parsing, walking).
        let path_filter = normalize_rules_config::PathFilter::new(&only, &exclude);

        // --fix path: syntax-only, loop until no fixable issues remain
        if fix {
            let debug_flags = normalize_syntax_rules::DebugFlags::from_args(&debug);
            let fix_filter = path_filter.clone();
            tokio::task::spawn_blocking(move || {
                const MAX_FIX_ITERATIONS: usize = 100;
                let mut total_fixed = 0usize;
                let mut total_files = 0usize;
                let mut iterations = 0usize;
                loop {
                    if iterations >= MAX_FIX_ITERATIONS {
                        eprintln!(
                            "Warning: --fix stopped after {MAX_FIX_ITERATIONS} iterations; \
                             a rule fix may be generating output that still matches the same rule."
                        );
                        break;
                    }
                    iterations += 1;
                    let findings = run_syntax_rules(
                        &target_root,
                        &project_root,
                        rule.as_deref(),
                        tag.as_deref(),
                        None,
                        &config.rules,
                        &debug_flags,
                        explicit_files.as_deref(),
                        &fix_filter,
                        &config.walk,
                    );
                    let fixable_count = findings.iter().filter(|f| f.fix.is_some()).count();
                    if fixable_count == 0 {
                        break;
                    }
                    match apply_fixes(&findings) {
                        Ok(0) => break,
                        Ok(files_modified) => {
                            total_fixed += fixable_count;
                            total_files = files_modified;
                        }
                        Err(e) => return Err(format!("Error applying fixes: {e}")),
                    }
                }
                if total_fixed == 0 {
                    eprintln!("No auto-fixable issues found.");
                } else {
                    println!("Fixed {} issue(s) in {} file(s).", total_fixed, total_files);
                }
                Ok(())
            })
            .await
            .map_err(|e| format!("Task error: {e}"))??;
            return Ok(DiagnosticsReport::new());
        }

        let run_native = matches!(rule_type, RuleKind::All | RuleKind::Native);
        let rule_filter = rule.clone();

        // Syntax + fact + SARIF engines via run_rules_report() (blocking)
        let explicit_files_clone = explicit_files.clone();
        let syntax_filter = path_filter.clone();
        let mut report = tokio::task::spawn_blocking(move || {
            run_rules_report(
                &target_root,
                &project_root,
                rule.as_deref(),
                tag.as_deref(),
                &rule_type,
                &debug,
                &config,
                explicit_files_clone.as_deref(),
                &syntax_filter,
            )
        })
        .await
        .map_err(|e| format!("Task error: {e}"))?;

        // Native engine (missing-summary, stale-summary, check-refs, stale-docs, check-examples,
        // ratchet, budget, long-file, high-complexity, long-function)
        // runs in async context; included in All and Native engine types.
        // All checks are independent — run them in parallel.
        // Skip when daemon already served cached native results.
        if run_native && !report.daemon_cached {
            let native_timings_start = std::time::Instant::now();
            let native_root = effective_root.clone();
            let native_config = load_rules_config(&native_root);
            let threshold = 10;
            let missing_summary_cfg: SummaryRuleConfig = native_config
                .rules
                .rules
                .get("missing-summary")
                .map(|r| r.rule_config())
                .unwrap_or_default();
            let missing_summary_filenames = missing_summary_cfg.filenames;
            let missing_summary_paths = missing_summary_cfg.paths;
            let stale_summary_cfg: SummaryRuleConfig = native_config
                .rules
                .rules
                .get("stale-summary")
                .map(|r| r.rule_config())
                .unwrap_or_default();
            let stale_summary_filenames = stale_summary_cfg.filenames;
            let stale_summary_paths = stale_summary_cfg.paths;

            // Helper: check if a native rule is enabled given config overrides and
            // the descriptor's default_enabled. A `--rule <id>` filter implicitly
            // enables the targeted rule so users can test disabled rules on demand.
            let is_native_enabled = |rule_id: &str| -> bool {
                if rule_filter.as_deref() == Some(rule_id) {
                    return true;
                }
                let desc = normalize_native_rules::NATIVE_RULES
                    .iter()
                    .find(|d| d.id == rule_id);
                let default = desc.map(|d| d.default_enabled).unwrap_or(true);
                native_config
                    .rules
                    .rules
                    .get(rule_id)
                    .and_then(|o| o.enabled)
                    .unwrap_or(default)
            };

            let run_long_file = is_native_enabled("long-file");
            let run_high_complexity = is_native_enabled("high-complexity");
            let run_long_function = is_native_enabled("long-function");
            let run_stale_doc = is_native_enabled("stale-doc");
            let run_boundary_violations = is_native_enabled("boundary-violations");
            let run_high_fan_out = is_native_enabled("high-fan-out");
            let run_high_fan_in = is_native_enabled("high-fan-in");
            let run_dead_parameter = is_native_enabled("dead-parameter");

            let boundary_cfg: normalize_native_rules::BoundaryViolationsConfig = native_config
                .rules
                .rules
                .get("boundary-violations")
                .map(|r| r.rule_config())
                .unwrap_or_default();
            let boundaries: Vec<normalize_native_rules::Boundary> = boundary_cfg
                .boundaries
                .iter()
                .filter_map(|s| normalize_native_rules::parse_boundary(s))
                .collect();

            let long_file_threshold: usize = native_config
                .rules
                .rules
                .get("long-file")
                .map(|r| r.rule_config::<ThresholdConfig>())
                .and_then(|c| c.threshold)
                .unwrap_or(500);
            let long_file_allow: Vec<String> = native_config
                .rules
                .rules
                .get("long-file")
                .map(|r| r.allow.clone())
                .unwrap_or_default();
            let high_complexity_threshold: usize = native_config
                .rules
                .rules
                .get("high-complexity")
                .map(|r| r.rule_config::<ThresholdConfig>())
                .and_then(|c| c.threshold)
                .unwrap_or(20);
            let long_function_threshold: usize = native_config
                .rules
                .rules
                .get("long-function")
                .map(|r| r.rule_config::<ThresholdConfig>())
                .and_then(|c| c.threshold)
                .unwrap_or(100);
            let high_fan_out_threshold: usize = native_config
                .rules
                .rules
                .get("high-fan-out")
                .map(|r| r.rule_config::<ThresholdConfig>())
                .and_then(|c| c.threshold)
                .unwrap_or(20);
            let high_fan_in_threshold: usize = native_config
                .rules
                .rules
                .get("high-fan-in")
                .map(|r| r.rule_config::<ThresholdConfig>())
                .and_then(|c| c.threshold)
                .unwrap_or(20);

            let stale_doc_cfg: normalize_native_rules::StaleDocConfig = native_config
                .rules
                .rules
                .get("stale-doc")
                .map(|r| r.rule_config())
                .unwrap_or_default();

            // Compute effective_files concurrently with group-1 rules so advisory
            // rules (group 2) can start immediately after group 1 finishes rather
            // than waiting for a sequential file walk.
            let effective_files_future = {
                let root = native_root.clone();
                let pf = path_filter.clone();
                let ef = explicit_files.clone();
                let wc = native_config.walk.clone();
                tokio::task::spawn_blocking(move || -> Option<Vec<std::path::PathBuf>> {
                    if !pf.is_empty() {
                        if let Some(ef) = ef {
                            Some(
                                ef.into_iter()
                                    .filter(|p| {
                                        let rel = p.strip_prefix(&root).unwrap_or(p);
                                        pf.matches_path(rel)
                                    })
                                    .collect(),
                            )
                        } else {
                            // Walk once, filtering by PathFilter, and share the list
                            // across all advisory rules.
                            Some(
                                normalize_native_rules::walk::filtered_gitignore_walk(
                                    &root, &pf, &wc,
                                )
                                .filter(|e| e.path().is_file())
                                .map(|e| e.path().to_path_buf())
                                .collect(),
                            )
                        }
                    } else {
                        None
                    }
                })
            };

            let (
                missing_res,
                summary_res,
                stale_res,
                examples_res,
                refs_res,
                ratchet_res,
                budget_res,
                effective_files_res,
            ) = tokio::join!(
                tokio::task::spawn_blocking({
                    let root = native_root.clone();
                    let wc = native_config.walk.clone();
                    move || {
                        let t = std::time::Instant::now();
                        let r = normalize_native_rules::build_missing_summary_report(
                            &root,
                            threshold,
                            &missing_summary_filenames,
                            &missing_summary_paths,
                            &wc,
                        );
                        eprintln!("[timings] missing-summary: {:.1?}", t.elapsed());
                        r
                    }
                }),
                tokio::task::spawn_blocking({
                    let root = native_root.clone();
                    let wc = native_config.walk.clone();
                    move || {
                        let t = std::time::Instant::now();
                        let r = normalize_native_rules::build_stale_summary_report(
                            &root,
                            threshold,
                            &stale_summary_filenames,
                            &stale_summary_paths,
                            &wc,
                        );
                        eprintln!("[timings] stale-summary: {:.1?}", t.elapsed());
                        r
                    }
                }),
                tokio::task::spawn_blocking({
                    let root = native_root.clone();
                    let wc = native_config.walk.clone();
                    move || {
                        let t = std::time::Instant::now();
                        let r = normalize_native_rules::build_stale_docs_report(&root, &wc);
                        eprintln!("[timings] stale-docs: {:.1?}", t.elapsed());
                        r
                    }
                }),
                tokio::task::spawn_blocking({
                    let root = native_root.clone();
                    let wc = native_config.walk.clone();
                    move || {
                        let t = std::time::Instant::now();
                        let r = normalize_native_rules::build_check_examples_report(&root, &wc);
                        eprintln!("[timings] check-examples: {:.1?}", t.elapsed());
                        r
                    }
                }),
                async {
                    let t = std::time::Instant::now();
                    let r = normalize_native_rules::build_check_refs_report(
                        &native_root,
                        &native_config.walk,
                    )
                    .await;
                    eprintln!("[timings] check-refs: {:.1?}", t.elapsed());
                    r
                },
                tokio::task::spawn_blocking({
                    let root = native_root.clone();
                    move || {
                        let t = std::time::Instant::now();
                        let r = normalize_native_rules::build_ratchet_report(&root);
                        eprintln!("[timings] ratchet: {:.1?}", t.elapsed());
                        r
                    }
                }),
                tokio::task::spawn_blocking({
                    let root = native_root.clone();
                    move || {
                        let t = std::time::Instant::now();
                        let r = normalize_native_rules::build_budget_report(&root);
                        eprintln!("[timings] budget: {:.1?}", t.elapsed());
                        r
                    }
                }),
                effective_files_future,
            );

            // Unwrap effective_files; fall back to explicit_files if the walk task failed.
            let effective_files: Option<Vec<std::path::PathBuf>> = effective_files_res
                .ok()
                .flatten()
                .or_else(|| explicit_files.clone());

            // Track how many issues existed before adding native results so
            // global_allow filtering only touches the newly added native issues.
            let native_start = report.issues.len();

            if let Ok(r) = missing_res {
                report.merge(r.into());
            }
            if let Ok(r) = summary_res {
                report.merge(r.into());
            }
            if let Ok(r) = stale_res {
                report.merge(r.into());
            }
            if let Ok(r) = examples_res {
                report.merge(r.into());
            }
            if let Ok(r) = refs_res {
                report.merge(r.into());
            }
            if let Ok(r) = ratchet_res {
                report.merge(r.into());
            }
            if let Ok(r) = budget_res {
                report.merge(r.into());
            }

            // Advisory rules (default disabled — only run when explicitly enabled).
            // long-file / high-complexity / long-function are tree-sitter-heavy.
            // dead-parameter uses the scope engine (locals.scm queries).
            // stale-doc, boundary-violations, high-fan-out, and high-fan-in require the index.
            let (
                long_file_res,
                high_complexity_res,
                long_function_res,
                stale_doc_res,
                boundary_violations_res,
                high_fan_out_res,
                high_fan_in_res,
                dead_parameter_res,
            ) = tokio::join!(
                async {
                    if !run_long_file {
                        return None;
                    }
                    let root = native_root.clone();
                    let threshold = long_file_threshold;
                    let allow = long_file_allow.clone();
                    let ef = effective_files.clone();
                    let wc = native_config.walk.clone();
                    let t = std::time::Instant::now();
                    let r = tokio::task::spawn_blocking(move || {
                        normalize_native_rules::build_long_file_report(
                            &root,
                            threshold,
                            ef.as_deref(),
                            &wc,
                            &allow,
                        )
                    })
                    .await
                    .ok();
                    eprintln!("[timings] long-file: {:.1?}", t.elapsed());
                    r
                },
                async {
                    if !run_high_complexity {
                        return None;
                    }
                    let root = native_root.clone();
                    let threshold = high_complexity_threshold;
                    let ef = effective_files.clone();
                    let wc = native_config.walk.clone();
                    let t = std::time::Instant::now();
                    let r = tokio::task::spawn_blocking(move || {
                        normalize_native_rules::build_high_complexity_report(
                            &root,
                            threshold,
                            ef.as_deref(),
                            &wc,
                        )
                    })
                    .await
                    .ok();
                    eprintln!("[timings] high-complexity: {:.1?}", t.elapsed());
                    r
                },
                async {
                    if !run_long_function {
                        return None;
                    }
                    let root = native_root.clone();
                    let threshold = long_function_threshold;
                    let ef = effective_files.clone();
                    let wc = native_config.walk.clone();
                    let t = std::time::Instant::now();
                    let r = tokio::task::spawn_blocking(move || {
                        normalize_native_rules::build_long_function_report(
                            &root,
                            threshold,
                            ef.as_deref(),
                            &wc,
                        )
                    })
                    .await
                    .ok();
                    eprintln!("[timings] long-function: {:.1?}", t.elapsed());
                    r
                },
                async {
                    if !run_stale_doc {
                        return None;
                    }
                    let root = native_root.clone();
                    let cfg = stale_doc_cfg;
                    let ef = effective_files.clone();
                    let t = std::time::Instant::now();
                    let r = tokio::task::spawn_blocking(move || {
                        normalize_native_rules::build_stale_doc_report(&root, cfg, ef.as_deref())
                    })
                    .await
                    .ok();
                    eprintln!("[timings] stale-doc: {:.1?}", t.elapsed());
                    r
                },
                async {
                    if !run_boundary_violations {
                        return None;
                    }
                    let root = native_root.clone();
                    let t = std::time::Instant::now();
                    let r = normalize_native_rules::build_boundary_violations_report(
                        &root,
                        &boundaries,
                    )
                    .await;
                    eprintln!("[timings] boundary-violations: {:.1?}", t.elapsed());
                    Some(r)
                },
                async {
                    if !run_high_fan_out {
                        return None;
                    }
                    let root = native_root.clone();
                    let threshold = high_fan_out_threshold;
                    let t = std::time::Instant::now();
                    let r =
                        normalize_native_rules::build_high_fan_out_report(&root, threshold).await;
                    eprintln!("[timings] high-fan-out: {:.1?}", t.elapsed());
                    Some(r)
                },
                async {
                    if !run_high_fan_in {
                        return None;
                    }
                    let root = native_root.clone();
                    let threshold = high_fan_in_threshold;
                    let t = std::time::Instant::now();
                    let r =
                        normalize_native_rules::build_high_fan_in_report(&root, threshold).await;
                    eprintln!("[timings] high-fan-in: {:.1?}", t.elapsed());
                    Some(r)
                },
                async {
                    if !run_dead_parameter {
                        return None;
                    }
                    let root = native_root.clone();
                    let ef = effective_files.clone();
                    let wc = native_config.walk.clone();
                    let t = std::time::Instant::now();
                    let r = tokio::task::spawn_blocking(move || {
                        normalize_native_rules::build_dead_parameter_report(
                            &root,
                            ef.as_deref(),
                            &wc,
                        )
                    })
                    .await
                    .ok();
                    eprintln!("[timings] dead-parameter: {:.1?}", t.elapsed());
                    r
                },
            );

            if let Some(r) = long_file_res {
                report.merge(r);
            }
            if let Some(r) = high_complexity_res {
                report.merge(r);
            }
            if let Some(r) = long_function_res {
                report.merge(r);
            }
            if let Some(r) = stale_doc_res {
                report.merge(r);
            }
            if let Some(r) = boundary_violations_res {
                report.merge(r);
            }
            if let Some(r) = high_fan_out_res {
                report.merge(r);
            }
            if let Some(r) = high_fan_in_res {
                report.merge(r);
            }
            if let Some(r) = dead_parameter_res {
                report.merge(r);
            }

            // Apply global_allow patterns to native-rule issues (syntax/fact rules
            // apply global_allow during their own execution; native rules need it here).
            let global_allow: Vec<glob::Pattern> = native_config
                .rules
                .global_allow
                .iter()
                .filter_map(|s| glob::Pattern::new(s).ok())
                .collect();
            if !global_allow.is_empty() {
                let mut keep_idx = 0usize;
                report.issues.retain(|issue| {
                    let idx = keep_idx;
                    keep_idx += 1;
                    if idx < native_start {
                        // pre-existing syntax/fact issue — already filtered, keep it
                        return true;
                    }
                    !global_allow.iter().any(|p| p.matches(&issue.file))
                });
            }
            apply_native_rules_config(&mut report, &native_config.rules);
            tracing::debug!(
                "[timings] total native: {:.1?}",
                native_timings_start.elapsed()
            );
            report.sources_run.push("native".into());
        }

        // Apply --rule filter across all engines (syntax/fact already filter internally,
        // but native engine produces all its issues unconditionally).
        if let Some(ref filter) = rule_filter {
            report
                .issues
                .retain(|issue| issue.rule_id == filter.as_str());
        }

        // Safety-net: apply --only / --exclude path filters to all issues post-walk.
        // The pre-walk filter handles syntax and advisory native rules; this catches
        // engines that don't support pre-walk filtering (fact rules, non-advisory native).
        if !path_filter.is_empty() {
            report
                .issues
                .retain(|issue| path_filter.matches(issue.file.as_str()));
            let unique_files: std::collections::HashSet<&str> =
                report.issues.iter().map(|i| i.file.as_str()).collect();
            report.files_checked = unique_files.len();
        }

        report.sort();

        let error_count = report.count_by_severity(normalize_output::diagnostics::Severity::Error);
        if !no_fail && error_count > 0 {
            let detail = self.display_run(&report);
            return Err(format!("{detail}\n{error_count} error(s) found"));
        }

        Ok(report)
    }

    /// Enable a rule or all rules matching a tag
    ///
    /// Examples:
    ///   normalize rules enable python/bare-except   # enable a specific rule
    ///   normalize rules enable --tag correctness    # enable all correctness rules
    #[cli(display_with = "display_output")]
    pub fn enable(
        &self,
        #[param(positional, help = "Rule ID or tag name")] id_or_tag: String,
        #[param(help = "Preview changes without writing")] dry_run: bool,
        #[param(short = 'r', help = "Root directory (defaults to current directory)")] root: Option<
            String,
        >,
    ) -> Result<RuleShowReport, String> {
        let effective_root = root
            .as_deref()
            .map(std::path::PathBuf::from)
            .map(Ok)
            .unwrap_or_else(std::env::current_dir)
            .map_err(|e| format!("Failed to get current directory: {e}"))?;
        let config = load_rules_config(&effective_root);
        enable_disable(&effective_root, &id_or_tag, true, dry_run, &config).map(|msg| {
            RuleShowReport {
                success: true,
                message: Some(msg),
            }
        })
    }

    /// Disable a rule or all rules matching a tag
    ///
    /// Examples:
    ///   normalize rules disable no-todo-comment     # disable a specific rule
    #[cli(display_with = "display_output")]
    pub fn disable(
        &self,
        #[param(positional, help = "Rule ID or tag name")] id_or_tag: String,
        #[param(help = "Preview changes without writing")] dry_run: bool,
        #[param(short = 'r', help = "Root directory (defaults to current directory)")] root: Option<
            String,
        >,
    ) -> Result<RuleShowReport, String> {
        let effective_root = root
            .as_deref()
            .map(std::path::PathBuf::from)
            .map(Ok)
            .unwrap_or_else(std::env::current_dir)
            .map_err(|e| format!("Failed to get current directory: {e}"))?;
        let config = load_rules_config(&effective_root);
        enable_disable(&effective_root, &id_or_tag, false, dry_run, &config).map(|msg| {
            RuleShowReport {
                success: true,
                message: Some(msg),
            }
        })
    }

    /// Show full documentation for a rule
    ///
    /// Examples:
    ///   normalize rules show rust/unwrap-in-impl    # full docs for a rule
    #[cli(display_with = "display_output")]
    pub fn show(
        &self,
        #[param(positional, help = "Rule ID to show")] id: String,
        #[param(short = 'r', help = "Root directory (defaults to current directory)")] root: Option<
            String,
        >,
        pretty: bool,
        compact: bool,
    ) -> Result<RuleInfoReport, String> {
        let effective_root = root
            .as_deref()
            .map(std::path::PathBuf::from)
            .map(Ok)
            .unwrap_or_else(std::env::current_dir)
            .map_err(|e| format!("Failed to get current directory: {e}"))?;
        self.resolve_format(pretty, compact);
        let config = load_rules_config(&effective_root);
        show_rule_structured(&effective_root, &id, &config)
    }

    /// List all tags and the rules they group
    ///
    /// Examples:
    ///   normalize rules tags                   # list all tags with rule counts
    #[cli(display_with = "display_output")]
    pub fn tags(
        &self,
        #[param(help = "Show only this specific tag")] tag: Option<String>,
        #[param(short = 'r', help = "Root directory (defaults to current directory)")] root: Option<
            String,
        >,
        pretty: bool,
        compact: bool,
    ) -> Result<RulesTagsReport, String> {
        let effective_root = root
            .as_deref()
            .map(std::path::PathBuf::from)
            .map(Ok)
            .unwrap_or_else(std::env::current_dir)
            .map_err(|e| format!("Failed to get current directory: {e}"))?;
        self.resolve_format(pretty, compact);
        let config = load_rules_config(&effective_root);
        list_tags_structured(&effective_root, tag.as_deref(), &config)
    }

    /// Add a rule from a URL
    ///
    /// Examples:
    ///   normalize rules add https://example.com/rule.scm   # import a rule from URL
    #[cli(display_with = "display_output")]
    pub fn add(
        &self,
        #[param(positional, help = "URL to download the rule from")] url: String,
        #[param(help = "Install to global rules instead of project")] global: bool,
    ) -> Result<RuleShowReport, String> {
        add_rule(&url, global).map(|_| RuleShowReport {
            success: true,
            message: None,
        })
    }

    /// Update imported rules from their sources
    #[cli(display_with = "display_output")]
    pub fn update(
        &self,
        #[param(
            positional,
            help = "Specific rule ID to update (updates all if omitted)"
        )]
        rule_id: Option<String>,
    ) -> Result<RuleShowReport, String> {
        update_rules(rule_id.as_deref()).map(|_| RuleShowReport {
            success: true,
            message: None,
        })
    }

    /// Remove an imported rule
    #[cli(display_with = "display_output")]
    pub fn remove(
        &self,
        #[param(positional, help = "Rule ID to remove")] rule_id: String,
    ) -> Result<RuleShowReport, String> {
        remove_rule(&rule_id).map(|_| RuleShowReport {
            success: true,
            message: None,
        })
    }

    /// Interactive setup wizard — run all rules and walk through enable/disable decisions
    ///
    /// Examples:
    ///   normalize rules setup                    # interactive rule configuration
    #[cli(display_with = "display_output")]
    pub fn setup(
        &self,
        #[param(short = 'r', help = "Root directory (defaults to current directory)")] root: Option<
            String,
        >,
    ) -> Result<RuleShowReport, String> {
        let effective_root = root
            .as_deref()
            .map(std::path::PathBuf::from)
            .map(Ok)
            .unwrap_or_else(std::env::current_dir)
            .map_err(|e| format!("Failed to get current directory: {e}"))?;
        let exit_code = crate::setup::run_setup_wizard(&effective_root);
        if exit_code == 0 {
            Ok(RuleShowReport {
                success: true,
                message: None,
            })
        } else {
            Err("Setup wizard failed".to_string())
        }
    }

    /// Validate the rules configuration — check rule IDs, TOML syntax, and report issues
    ///
    /// Examples:
    ///   normalize rules validate               # check rule config for errors
    #[cli(display_with = "display_output")]
    pub fn validate(
        &self,
        #[param(short = 'r', help = "Root directory (defaults to current directory)")] root: Option<
            String,
        >,
        pretty: bool,
        compact: bool,
    ) -> Result<RulesValidateReport, String> {
        let effective_root = root
            .as_deref()
            .map(std::path::PathBuf::from)
            .map(Ok)
            .unwrap_or_else(std::env::current_dir)
            .map_err(|e| format!("Failed to get current directory: {e}"))?;
        self.pretty.set(resolve_pretty(pretty, compact));

        let config_file = effective_root.join(".normalize").join("config.toml");
        let config_path = if config_file.exists() {
            ".normalize/config.toml".to_string()
        } else {
            "(not found — using defaults)".to_string()
        };

        let mut errors: Vec<String> = Vec::new();

        // Check for TOML parse errors directly (load_rules_config silently swallows them)
        if config_file.exists() {
            let raw = std::fs::read_to_string(&config_file)
                .map_err(|e| format!("Failed to read config: {e}"))?;
            if let Err(e) = toml::from_str::<toml::Value>(&raw) {
                errors.push(format!("TOML parse error: {e}"));
                return Ok(RulesValidateReport {
                    config_path,
                    valid: false,
                    errors,
                    warnings: Vec::new(),
                    rule_count: 0,
                    global_allow_count: 0,
                });
            }
        }

        // Load effective config
        let config = load_rules_config(&effective_root);
        let rules_cfg = &config.rules;

        let rule_count = rules_cfg.rules.len();
        let global_allow_count = rules_cfg.global_allow.len();

        // Build list of known rule IDs by querying all rule engines
        let list_report = build_list_report(
            &effective_root,
            &ListFilters {
                type_filter: &RuleKind::All,
                tag: None,
                enabled: false,
                disabled: false,
            },
            &config,
        );
        let known_ids: std::collections::HashSet<String> =
            list_report.rules.iter().map(|r| r.id.clone()).collect();

        // Check each configured rule ID against known rules
        for rule_id in rules_cfg.rules.keys() {
            if !known_ids.contains(rule_id) {
                errors.push(format!(
                    "unknown rule ID \"{rule_id}\" — run 'normalize rules list' to see available rules"
                ));
            }
        }

        let valid = errors.is_empty();

        let report = RulesValidateReport {
            config_path,
            valid,
            errors,
            warnings: Vec::new(),
            rule_count,
            global_allow_count,
        };

        Ok(report)
    }

    /// Validate and "compile" a Datalog rules file — check syntax and relation names
    ///
    /// Parses the `.dl` file, validates that all referenced relations are declared (or
    /// are built-in), and reports errors with file/line context.  Exits with status 1
    /// when errors are found so it can be used in CI pipelines.
    ///
    /// Examples:
    ///   normalize rules compile my-rule.dl       # check a single rule file
    ///   normalize rules compile .normalize/rules/arch.dl --json  # machine-readable output
    #[cli(display_with = "display_output")]
    pub fn compile(
        &self,
        #[param(positional, help = "Path to the .dl file to validate")] path: String,
        #[param(short = 'r', help = "Root directory (defaults to current directory)")] root: Option<
            String,
        >,
        pretty: bool,
        compact: bool,
    ) -> Result<RulesCompileReport, String> {
        use normalize_facts_rules_interpret::{compile_rules_source, parse_rule_content};

        self.resolve_format(pretty, compact);

        let effective_root = root
            .as_deref()
            .map(std::path::PathBuf::from)
            .map(Ok)
            .unwrap_or_else(std::env::current_dir)
            .map_err(|e| format!("Failed to get current directory: {e}"))?;

        let dl_path = if std::path::Path::new(&path).is_absolute() {
            std::path::PathBuf::from(&path)
        } else {
            effective_root.join(&path)
        };

        let content = std::fs::read_to_string(&dl_path)
            .map_err(|e| format!("Failed to read '{}': {e}", dl_path.display()))?;

        // Strip frontmatter to get the Datalog source body
        let default_id = dl_path
            .file_stem()
            .and_then(|s| s.to_str())
            .unwrap_or("rule");
        let rule = parse_rule_content(&content, default_id, false);
        let source = rule.as_ref().map(|r| r.source.as_str()).unwrap_or(&content);

        let compile_result = compile_rules_source(source);

        let errors: Vec<CompileError> = compile_result
            .errors
            .into_iter()
            .map(|e| CompileError {
                line: e.line,
                col: e.col,
                message: e.message,
            })
            .collect();

        let warnings: Vec<CompileWarning> = compile_result
            .warnings
            .into_iter()
            .map(|w| CompileWarning {
                line: w.line,
                col: w.col,
                message: w.message,
            })
            .collect();

        let valid = errors.is_empty();

        let report = RulesCompileReport {
            path,
            valid,
            errors,
            warnings,
            relations_used: compile_result.relations_used,
        };

        if report.valid {
            Ok(report)
        } else {
            // Signal failure to the CLI via Err so the process exits with status 1.
            // The formatted output is passed as the error string so it appears on stderr.
            Err(self.display_output(&report))
        }
    }

    /// Test a source file against inline `// error[rule-id]` annotations.
    ///
    /// Runs all enabled syntax rules against the file and checks that:
    ///   - Every `// error[rule-id]` annotation has a matching finding on that line
    ///   - Every finding has a corresponding annotation
    ///
    /// Exits with code 1 if any assertion fails.
    ///
    /// Examples:
    ///   normalize rules test src/lib.rs          # test a file
    ///   normalize rules test tests/fixture.rs    # test a fixture file
    #[cli(display_with = "display_output")]
    pub fn test(
        &self,
        #[param(positional, help = "Path to the source file to test")] file: String,
        #[param(short = 'r', help = "Root directory (defaults to current directory)")] root: Option<
            String,
        >,
        pretty: bool,
        compact: bool,
    ) -> Result<RulesTestReport, String> {
        self.resolve_format(pretty, compact);

        let effective_root = root
            .as_deref()
            .map(std::path::PathBuf::from)
            .map(Ok)
            .unwrap_or_else(std::env::current_dir)
            .map_err(|e| format!("Failed to get current directory: {e}"))?;

        let file_path = if std::path::Path::new(&file).is_absolute() {
            std::path::PathBuf::from(&file)
        } else {
            effective_root.join(&file)
        };

        let content = std::fs::read_to_string(&file_path)
            .map_err(|e| format!("Failed to read '{}': {e}", file_path.display()))?;

        // Parse inline annotations: scan for `error[rule-id]` patterns (language-agnostic).
        // Collect (line_number, rule_id) pairs; line numbers are 1-based.
        let mut annotations: Vec<(usize, String)> = Vec::new();
        for (idx, line) in content.lines().enumerate() {
            let line_no = idx + 1;
            let mut search = line;
            loop {
                let Some(pos) = search.find("error[") else {
                    break;
                };
                let after = &search[pos + "error[".len()..];
                let Some(end) = after.find(']') else {
                    break;
                };
                let rule_id = &after[..end];
                if !rule_id.is_empty() {
                    annotations.push((line_no, rule_id.to_string()));
                }
                // Advance past this match to find further annotations on the same line.
                search = &search[pos + "error[".len() + end + 1..];
            }
        }

        let config = load_rules_config(&effective_root);
        let debug_flags = normalize_syntax_rules::DebugFlags::default();
        let path_filter = normalize_rules_config::PathFilter::new(&[], &[]);
        let findings = run_syntax_rules(
            &effective_root,
            &effective_root,
            None,
            None,
            None,
            &config.rules,
            &debug_flags,
            Some(std::slice::from_ref(&file_path)),
            &path_filter,
            &config.walk,
        );

        let annotation_count = annotations.len();
        let finding_count = findings.len();

        // Build sets for bidirectional comparison.
        // Key: (line, rule_id)
        let annotation_set: std::collections::HashSet<(usize, String)> =
            annotations.into_iter().collect();
        let finding_set: std::collections::HashSet<(usize, String)> = findings
            .iter()
            .map(|f| (f.start_line, f.rule_id.clone()))
            .collect();

        let mut mismatches: Vec<TestMismatch> = Vec::new();

        // Findings without a matching annotation → "unexpected finding"
        let mut unexpected: Vec<(usize, String)> = finding_set
            .iter()
            .filter(|k| !annotation_set.contains(*k))
            .cloned()
            .collect();
        unexpected.sort();
        for (line, rule_id) in unexpected {
            mismatches.push(TestMismatch {
                line,
                rule_id,
                kind: "unexpected finding".to_string(),
            });
        }

        // Annotations without a matching finding → "expected finding missing"
        let mut missing: Vec<(usize, String)> = annotation_set
            .iter()
            .filter(|k| !finding_set.contains(*k))
            .cloned()
            .collect();
        missing.sort();
        for (line, rule_id) in missing {
            mismatches.push(TestMismatch {
                line,
                rule_id,
                kind: "expected finding missing".to_string(),
            });
        }

        mismatches.sort_by_key(|m| (m.line, m.rule_id.clone()));

        let passed = mismatches.is_empty();
        let report = RulesTestReport {
            file,
            passed,
            annotations: annotation_count,
            findings: finding_count,
            mismatches,
        };

        if passed {
            Ok(report)
        } else {
            let n = report.mismatches.len();
            let detail = self.display_output(&report);
            Err(format!("{detail}\n{n} test failure(s)"))
        }
    }

    /// Run fixture-based tests for rules.
    ///
    /// Discovers fixture cases under `fixture_dir` (defaults to `.normalize/rule-tests/`).
    ///
    /// **Single-file format** (flat, one file per case):
    /// ```text
    /// <fixture-dir>/
    ///   case-name.input.rs          # input source file
    ///   case-name.expected.json     # expected findings array
    /// ```
    ///
    /// **Multi-file format** (one subdirectory per case):
    /// ```text
    /// <fixture-dir>/
    ///   case-name/
    ///     input/
    ///       main.rs                 # one or more input files
    ///       helper.rs
    ///     expected.json             # expected findings array
    /// ```
    ///
    /// The `expected.json` file is an array of objects:
    /// ```json
    /// [{"rule": "rust/no-todo-comment", "file": "main.rs", "line": 3, "message": "TODO"}]
    /// ```
    ///
    /// `message` is a **substring match** — the actual diagnostic message only needs to
    /// contain the expected string.
    ///
    /// With `--update` the actual findings are written back to `expected.json`, making it
    /// easy to bootstrap a new fixture case.
    ///
    /// Examples:
    ///   normalize rules test-fixtures                           # scan .normalize/rule-tests/
    ///   normalize rules test-fixtures --fixture-dir tests/rules # custom dir
    ///   normalize rules test-fixtures --update                  # overwrite expected.json
    #[cli(display_with = "display_output")]
    pub fn test_fixtures(
        &self,
        #[param(
            short = 'd',
            help = "Directory containing fixture cases (default: .normalize/rule-tests/)"
        )]
        fixture_dir: Option<String>,
        #[param(help = "Overwrite expected.json with actual findings (bootstrap mode)")]
        update: bool,
        #[param(short = 'r', help = "Root directory (defaults to current directory)")] root: Option<
            String,
        >,
        pretty: bool,
        compact: bool,
    ) -> Result<RulesFixtureTestReport, String> {
        self.resolve_format(pretty, compact);

        let effective_root = root
            .as_deref()
            .map(std::path::PathBuf::from)
            .map(Ok)
            .unwrap_or_else(std::env::current_dir)
            .map_err(|e| format!("Failed to get current directory: {e}"))?;

        let fixture_root = match fixture_dir {
            Some(ref d) => {
                let p = std::path::Path::new(d);
                if p.is_absolute() {
                    p.to_path_buf()
                } else {
                    effective_root.join(p)
                }
            }
            None => effective_root.join(".normalize").join("rule-tests"),
        };

        if !fixture_root.exists() {
            return Err(format!(
                "Fixture directory '{}' does not exist. \
                 Create it and add .input.<ext> + .expected.json pairs.",
                fixture_root.display()
            ));
        }

        let config = load_rules_config(&effective_root);
        let cases = discover_fixture_cases(&fixture_root)
            .map_err(|e| format!("Failed to discover fixtures: {e}"))?;

        if cases.is_empty() {
            return Err(format!(
                "No fixture cases found under '{}'. \
                 Add .input.<ext> + .expected.json pairs (single-file format) \
                 or case-name/input/ + case-name/expected.json (multi-file format).",
                fixture_root.display()
            ));
        }

        let mut case_results: Vec<FixtureCaseResult> = Vec::new();

        for case in &cases {
            let result = run_fixture_case(case, &effective_root, &config, update);
            case_results.push(result);
        }

        let passed = case_results.iter().filter(|c| c.passed).count();
        let failed = case_results.iter().filter(|c| !c.passed).count();

        let report = RulesFixtureTestReport {
            fixture_dir: fixture_root.display().to_string(),
            cases: case_results,
            passed,
            failed,
            updated: update,
        };

        if failed > 0 && !update {
            let detail = self.display_output(&report);
            Err(format!("{detail}\n{failed} fixture case(s) failed"))
        } else {
            Ok(report)
        }
    }
}

// ---------------------------------------------------------------------------
// Fixture discovery and execution helpers (not part of the CLI surface)
// ---------------------------------------------------------------------------

/// A discovered fixture case — either single-file or multi-file.
struct FixtureCase {
    /// Human-readable case name (used in output).
    name: String,
    /// Input files: Vec<(filename, absolute_path)>.
    inputs: Vec<(String, std::path::PathBuf)>,
    /// Absolute path to `expected.json`.
    expected_json: std::path::PathBuf,
}

/// Discover all fixture cases under `root`.
///
/// Scans for:
/// 1. `*.input.<ext>` files paired with `*.expected.json` (single-file).
/// 2. Subdirectories containing `input/` + `expected.json` (multi-file).
fn discover_fixture_cases(root: &std::path::Path) -> std::io::Result<Vec<FixtureCase>> {
    let mut cases: Vec<FixtureCase> = Vec::new();
    let mut single_file_stems: std::collections::HashSet<String> = std::collections::HashSet::new();

    let mut entries: Vec<_> = std::fs::read_dir(root)?
        .filter_map(|e| e.ok())
        .map(|e| e.path())
        .collect();
    entries.sort();

    // First pass: collect single-file cases (*.input.*)
    for path in &entries {
        let file_name = match path.file_name().and_then(|n| n.to_str()) {
            Some(n) => n.to_string(),
            None => continue,
        };
        // Match pattern: <stem>.input.<ext>
        if let Some(stem) = extract_input_stem(&file_name) {
            let expected = root.join(format!("{stem}.expected.json"));
            // Always discover: expected.json may not exist yet (--update creates it).
            single_file_stems.insert(stem.clone());
            cases.push(FixtureCase {
                name: stem,
                inputs: vec![(file_name.clone(), path.clone())],
                expected_json: expected,
            });
        }
    }

    // Second pass: multi-file cases (subdirectories with input/ + expected.json)
    for path in &entries {
        if !path.is_dir() {
            continue;
        }
        let dir_name = match path.file_name().and_then(|n| n.to_str()) {
            Some(n) => n.to_string(),
            None => continue,
        };
        // Skip if we already handled this as a single-file case
        if single_file_stems.contains(&dir_name) {
            continue;
        }
        let input_dir = path.join("input");
        let expected = path.join("expected.json");
        if input_dir.is_dir() && (expected.exists() || !expected.exists()) {
            // Collect all files under input/
            let mut inputs: Vec<(String, std::path::PathBuf)> = Vec::new();
            collect_input_files(&input_dir, &input_dir, &mut inputs)?;
            inputs.sort_by(|a, b| a.0.cmp(&b.0));
            if !inputs.is_empty() {
                cases.push(FixtureCase {
                    name: dir_name,
                    inputs,
                    expected_json: expected,
                });
            }
        }
    }

    cases.sort_by(|a, b| a.name.cmp(&b.name));
    Ok(cases)
}

/// Extract the stem from a filename matching `<stem>.input.<ext>`.
/// Returns `None` if the pattern doesn't match.
fn extract_input_stem(file_name: &str) -> Option<String> {
    // We need at least two dots: <stem>.input.<ext>
    let parts: Vec<&str> = file_name.splitn(3, '.').collect();
    if parts.len() >= 3 && parts[1] == "input" {
        Some(parts[0].to_string())
    } else {
        None
    }
}

/// Recursively collect files under `dir`, recording paths relative to `base`.
fn collect_input_files(
    dir: &std::path::Path,
    base: &std::path::Path,
    out: &mut Vec<(String, std::path::PathBuf)>,
) -> std::io::Result<()> {
    for entry in std::fs::read_dir(dir)?.filter_map(|e| e.ok()) {
        let path = entry.path();
        if path.is_dir() {
            collect_input_files(&path, base, out)?;
        } else {
            let rel = path.strip_prefix(base).unwrap_or(&path);
            out.push((rel.to_string_lossy().to_string(), path));
        }
    }
    Ok(())
}

/// Run a single fixture case and return the result.
fn run_fixture_case(
    case: &FixtureCase,
    project_root: &std::path::Path,
    config: &crate::runner::RulesRunConfig,
    update: bool,
) -> FixtureCaseResult {
    // Collect the input file paths for the rule runner
    let input_paths: Vec<std::path::PathBuf> = case.inputs.iter().map(|(_, p)| p.clone()).collect();

    // Use a temp directory as the root so relative file paths in findings are clean
    let input_root: std::path::PathBuf = if case.inputs.len() == 1 {
        // Single-file: use the file's parent dir
        case.inputs[0]
            .1
            .parent()
            .unwrap_or(project_root)
            .to_path_buf()
    } else {
        // Multi-file: use the input/ directory (first input's parent)
        case.inputs[0]
            .1
            .parent()
            .unwrap_or(project_root)
            .to_path_buf()
    };

    // Run syntax rules on the input files
    let debug_flags = normalize_syntax_rules::DebugFlags::default();
    let path_filter = normalize_rules_config::PathFilter::new(&[], &[]);
    let findings = run_syntax_rules(
        &input_root,
        project_root,
        None,
        None,
        None,
        &config.rules,
        &debug_flags,
        Some(&input_paths),
        &path_filter,
        &config.walk,
    );

    // Convert findings to FixtureExpectedFinding (sorted for stable comparison)
    let mut actual: Vec<FixtureExpectedFinding> = findings
        .iter()
        .map(|f| {
            let file_rel = f
                .file
                .strip_prefix(&input_root)
                .unwrap_or(&f.file)
                .to_string_lossy()
                .to_string();
            FixtureExpectedFinding {
                rule: f.rule_id.clone(),
                file: file_rel,
                line: f.start_line,
                message: f.message.clone(),
            }
        })
        .collect();
    actual.sort();
    actual.dedup();

    if update {
        // Write actual findings back to expected.json
        let json = serde_json::to_string_pretty(&actual).unwrap_or_else(|_| "[]".to_string());
        if let Err(e) = std::fs::write(&case.expected_json, json) {
            return FixtureCaseResult {
                case: case.name.clone(),
                passed: false,
                diff: vec![format!("Failed to write expected.json: {e}")],
            };
        }
        return FixtureCaseResult {
            case: case.name.clone(),
            passed: true,
            diff: Vec::new(),
        };
    }

    // Load expected findings
    let expected: Vec<FixtureExpectedFinding> = if case.expected_json.exists() {
        match std::fs::read_to_string(&case.expected_json)
            .map_err(|e| e.to_string())
            .and_then(|s| serde_json::from_str(&s).map_err(|e| e.to_string()))
        {
            Ok(v) => v,
            Err(e) => {
                return FixtureCaseResult {
                    case: case.name.clone(),
                    passed: false,
                    diff: vec![format!("Failed to read expected.json: {e}")],
                };
            }
        }
    } else {
        // No expected.json → treat as expecting zero findings
        Vec::new()
    };

    // Compare: expected uses substring match on message
    let mut diff: Vec<String> = Vec::new();

    // Findings in actual but not matched by any expected entry → unexpected
    let mut matched_actuals: Vec<bool> = vec![false; actual.len()];
    let mut matched_expected: Vec<bool> = vec![false; expected.len()];

    for (ei, exp) in expected.iter().enumerate() {
        let found = actual.iter().enumerate().find(|(ai, act)| {
            !matched_actuals[*ai]
                && act.rule == exp.rule
                && act.file == exp.file
                && act.line == exp.line
                && act.message.contains(&exp.message)
        });
        if let Some((ai, _)) = found {
            matched_actuals[ai] = true;
            matched_expected[ei] = true;
        }
    }

    for (ei, exp) in expected.iter().enumerate() {
        if !matched_expected[ei] {
            diff.push(format!(
                "missing: {}:{} [{}] {:?}",
                exp.file, exp.line, exp.rule, exp.message
            ));
        }
    }

    for (ai, act) in actual.iter().enumerate() {
        if !matched_actuals[ai] {
            diff.push(format!(
                "unexpected: {}:{} [{}] {:?}",
                act.file, act.line, act.rule, act.message
            ));
        }
    }

    diff.sort();

    FixtureCaseResult {
        case: case.name.clone(),
        passed: diff.is_empty(),
        diff,
    }
}

/// Load `RulesRunConfig` from the project config files.
///
/// This mirrors the structure of `NormalizeConfig` but only pulls out the
/// fields needed by the rules machinery, avoiding a circular dependency on the
/// main `normalize` crate.
pub fn load_rules_config(root: &Path) -> RulesRunConfig {
    // We parse a minimal subset of normalize.toml — just the rules-related sections.
    let project_path = root.join(".normalize").join("config.toml");
    let content = match std::fs::read_to_string(&project_path) {
        Ok(s) => s,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => String::new(),
        Err(e) => {
            tracing::warn!("failed to read config at {:?}: {}", project_path, e);
            String::new()
        }
    };

    #[derive(serde::Deserialize, Default)]
    #[serde(default)]
    struct RulesOnlyConfig {
        rules: crate::runner::RulesConfig,
        #[serde(rename = "rule-tags")]
        rule_tags: std::collections::HashMap<String, Vec<String>>,
        walk: Option<normalize_rules_config::WalkConfig>,
    }

    // Load global config first
    let global_content = dirs::config_dir()
        .map(|d| d.join("normalize").join("config.toml"))
        .map(|p| match std::fs::read_to_string(&p) {
            Ok(s) => s,
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => String::new(),
            Err(e) => {
                tracing::warn!("failed to read config at {:?}: {}", p, e);
                String::new()
            }
        })
        .unwrap_or_default();

    let global: RulesOnlyConfig = toml::from_str(&global_content).unwrap_or_else(|e| {
        eprintln!("warning: failed to parse global rules config: {e}");
        eprintln!("  Rule overrides, severity settings, and allow patterns will not apply.");
        RulesOnlyConfig::default()
    });
    let project: RulesOnlyConfig = toml::from_str(&content).unwrap_or_else(|e| {
        eprintln!(
            "warning: failed to parse rules config at {}: {e}",
            project_path.display()
        );
        eprintln!("  Rule overrides, severity settings, and allow patterns will not apply.");
        RulesOnlyConfig::default()
    });

    let rule_tags = {
        let mut merged = global.rule_tags;
        merged.extend(project.rule_tags);
        merged
    };

    // Merge: start with global, overlay project on top.  Using normalize_core::Merge
    // ensures per-rule overrides from global config are preserved when the project
    // config only overrides a subset of rules.
    use normalize_core::Merge as _;
    let rules = global.rules.merge(project.rules);
    // Walk config: project overrides global if specified.
    let walk = match (global.walk, project.walk) {
        (_, Some(p)) => p,
        (Some(g), None) => g,
        (None, None) => normalize_rules_config::WalkConfig::default(),
    };
    RulesRunConfig {
        rule_tags,
        rules,
        walk,
    }
}