wowlab_tidy/

llm.rs

// #t(file: rust_alloc_in_loop) markdown document builder uses format! throughout loops by design
// #t(file: rust_println) --llm CLI output writes the document to stdout by design
// #t(file: rust_vec_string_field) rule-info structs are built then immediately rendered; boxing buys nothing

use std::{collections::BTreeMap, process::ExitCode};

use wowlab_common::markdown::{self, Doc, Table};
use wowlab_fs::path::Path;

use crate::{Config, Example, ParamDefault, RuleKind, RuleParam, Severity, Violation, runner};

struct LlmRuleInfo {
    name: &'static str,
    kind: RuleKind,
    description: &'static str,
    justification: &'static str,
    severity: Severity,
    examples: &'static [Example],
    params: &'static [RuleParam],
    enabled: bool,
    fixable: bool,
    ignore_patterns: Vec<String>,
}

fn gather_rules(config: &Config, rule_filter: &[String]) -> Vec<LlmRuleInfo> {
    crate::all_rules()
        .into_iter()
        .filter(|r| rule_filter.is_empty() || rule_filter.iter().any(|f| f == r.name))
        .map(|r| LlmRuleInfo {
            name: r.name,
            kind: r.kind,
            description: r.description,
            justification: r.justification,
            severity: r.severity,
            examples: r.examples,
            params: r.params,
            enabled: config.is_enabled(r.name),
            fixable: r.fixable,
            ignore_patterns: config.ignore_patterns(r.name).to_vec(),
        })
        .collect()
}

fn render_summary_table(doc: Doc, rules: &[LlmRuleInfo]) -> Doc {
    let mut table = Table::new().headers([
        "Rule",
        "Severity",
        "Type",
        "Enabled",
        "Fixable",
        "Description",
    ]);

    for r in rules {
        let enabled = if r.enabled { "yes" } else { "no" };
        let fixable = if r.fixable { "yes" } else { "no" };

        table = table.row([
            r.name,
            r.severity.as_str(),
            r.kind.as_str(),
            enabled,
            fixable,
            r.description,
        ]);
    }

    doc.raw(table.build_markdown()).blank()
}

fn render_rule_details(mut doc: Doc, rules: &[LlmRuleInfo]) -> Doc {
    for r in rules {
        doc = doc.h3(r.name).blank().line(r.description).blank();

        if !r.justification.is_empty() {
            doc = doc.quote(r.justification).blank();
        }

        let enabled = if r.enabled { "yes" } else { "no" };
        let fixable = if r.fixable { "yes" } else { "no" };
        let mut meta = Table::new()
            .headers(["", ""])
            .row(["Severity", r.severity.as_str()])
            .row(["Type", r.kind.as_str()])
            .row(["Enabled", enabled])
            .row(["Fixable", fixable]);

        for p in r.params {
            let type_str = match p.param_type {
                crate::ParamType::Int => "i64",
                crate::ParamType::StringArray => "[String]",
            };
            let default_str = match &p.default {
                ParamDefault::Int(d) => d.to_string(),
                ParamDefault::StringArray(d) => format!("{d:?}"),
            };
            let label = format!("Param: {}", p.name);
            let value = format!("{type_str}, default = {default_str}");

            meta = meta.row([&label, &value]);
        }

        doc = doc.raw(meta.build_markdown());

        if !r.ignore_patterns.is_empty() {
            let patterns = r
                .ignore_patterns
                .iter()
                .map(markdown::code)
                .collect::<Vec<_>>()
                .join(", ");

            doc = doc.kv_bullet("Ignored paths", &patterns);
        }

        doc = doc.blank();

        let bad: Vec<_> = r.examples.iter().filter(|e| !e.pass).collect();
        let good: Vec<_> = r.examples.iter().filter(|e| e.pass).collect();

        if !bad.is_empty() {
            doc = doc
                .line(&markdown::bold("Bad (triggers violation):"))
                .blank();

            for ex in &bad {
                if !ex.label.is_empty() {
                    doc = doc.line(&markdown::italic(ex.label));
                }

                doc = doc.code_block("rust", ex.code).blank();
            }
        }

        if !good.is_empty() {
            doc = doc.line(&markdown::bold("Good (passes):")).blank();

            for ex in &good {
                if !ex.label.is_empty() {
                    doc = doc.line(&markdown::italic(ex.label));
                }

                doc = doc.code_block("rust", ex.code).blank();
            }
        }
    }

    doc
}

fn render_violations(mut doc: Doc, violations: &[Violation]) -> Doc {
    if violations.is_empty() {
        return doc.line("No violations found.").blank();
    }

    doc = doc
        .line(&markdown::bold(format!(
            "{} violation(s) found. Fix these:",
            violations.len()
        )))
        .blank();

    let mut by_rule: BTreeMap<&str, Vec<&Violation>> = BTreeMap::new();

    for v in violations {
        by_rule.entry(v.rule_name()).or_default().push(v);
    }

    for (rule, vs) in &by_rule {
        doc = doc.h3(&format!("{rule} ({} issues)", vs.len())).blank();

        for v in vs {
            let loc = format!("{}:{}", v.rel, v.line);

            doc = doc.def(&loc, &v.message);
        }

        doc = doc.blank();
    }

    doc
}

#[rustfmt::skip]
const DIRECTIVES: &[(&str, &str)] = &[
    // #t:aligned
    ("// #t(rule) reason"        ,          "suppress the next line for this rule"),
    ("// #t(rule1, rule2) reason",  "suppress the next line for multiple rules")   ,
    ("// #t(file: rule) reason"  ,    "skip the entire file for this rule")        ,
    ("// #t(block: rule) reason" ,   "suppress until blank line or closing brace") ,
    ("// #t(fn: rule) reason"    ,      "suppress until end of next function")     ,
    ("// #t(*) reason"           ,             "suppress all rules (next line)")   ,
];

/// Render the rule catalog and current violations as a markdown document for LLM consumption.
// #t(rust_param_order_consistency) CLI entry mirrors clap argument order; reordering is out of scope here
pub fn print(
    rule_filter: &[String],
    crate_filter: &[String],
    config: &Config,
    root: &Path,
    crates_dir: &Path,
) -> ExitCode {
    let rules = gather_rules(config, rule_filter);

    let mut doc = Doc::new()
        .h1("tidy — Rust source code linter")
        .blank()
        .line("Custom lint rules for the WoW Lab Rust workspace. Runs beyond what clippy and rustfmt cover.")
        .blank();

    let severity_table = Table::new()
        .headers(["Severity", "Meaning"])
        .row([
            "high",
            "Likely bug, security issue, or correctness problem. Fix these first.",
        ])
        .row([
            "medium",
            "Potential bug, performance issue, or maintainability concern.",
        ])
        .row([
            "low",
            "Style nit or minor improvement. Safe to suppress with good reason.",
        ]);

    doc = doc
        .h2("Severity levels")
        .blank()
        .raw(severity_table.build_markdown())
        .blank();

    doc = doc
        .h2("Suppression directives")
        .blank()
        .line("When a rule fires on code that is intentionally written that way, suppress it with a directive comment:")
        .blank();

    for (syntax, desc) in DIRECTIVES {
        doc = doc.def(syntax, desc);
    }

    doc = doc
        .blank()
        .line("Rule names and a reason after `)` are required. Missing either is a violation.")
        .blank();

    doc = doc.h2("Rules").blank();
    doc = render_summary_table(doc, &rules);

    doc = doc.h2("Rule details").blank();
    doc = render_rule_details(doc, &rules);

    doc = doc.h2("Current violations").blank();
    let run_ctx = runner::RunCtx {
        rule_filter,
        crate_filter,
        config,
        root,
        crates_dir,
        quiet: true,
        dirty: false,
    };
    let violations = match runner::collect_violations(&run_ctx, false, None) {
        Ok((violations, _, _)) => violations,
        Err(error) => {
            eprintln!("tidy: analysis aborted: {error}");

            return ExitCode::FAILURE;
        }
    };

    doc = render_violations(doc, &violations);

    print!("{}", doc.build());

    ExitCode::SUCCESS
}