badness 0.28.0

//! Rendering the linter-rules reference from rule metadata.
//!
//! [`render_rule_doc`] and [`render_reference_page`] are the single source of
//! truth shared by the snapshot test (`tests/rule_docs.rs`) and the docs
//! generator (`examples/docgen.rs`), so the committed
//! `docs/src/reference/linter-rules.md` and the pinned snapshots can never
//! diverge from behavior. Every example is linted by the *real* driver
//! ([`demo_diagnostics`]), so the rendered diagnostics and the autofix
//! before/after always reflect the current rules.

use std::collections::HashMap;
use std::fmt::Write as _;
use std::path::{Path, PathBuf};

use smol_str::SmolStr;

use crate::file_discovery::file_kind_or_tex;
use crate::linter::check::lint_document;
use crate::linter::diagnostic::{Diagnostic, Fix};
use crate::linter::fix::apply_fixes;
use crate::linter::render::{OutputMode, render_findings};
use crate::linter::rules::{Example, Rule, all_rules};
use crate::parser::parse_with_flavor;
use crate::project::include::BibTarget;
use crate::project::labels::{document_label_names, document_ref_names};
use crate::project::{
    CiteFileFacts, FileFacts, IncludeGraph, PackageOptionFacts, ResolvedCitations, ResolvedLabels,
    ResolvedPackageOptions, collect_bib_resource_targets, collect_include_edge_keys,
    package_option_facts,
};
use crate::semantic::SemanticModel;
use crate::syntax::SyntaxNode;

/// The synthetic path used when linting an example snippet. The same value keys
/// both [`lint_document`] and the `render_findings` source lookup: the driver
/// stamps every diagnostic's `path` to it, and the pretty renderer degrades to a
/// location-only line if the source can't be found for that exact path.
fn example_path() -> PathBuf {
    PathBuf::from("example.tex")
}

/// Lint `source` as a self-contained document under a synthetic **closed,
/// rooted** single-file project view, so even the cross-file rules
/// (`undefined-ref`, `undefined-citation`) are demonstrable from one snippet.
///
/// Labels defined in the snippet are honored (a `\ref` to a *defined* label does
/// not flag), and every `\bibliography`/`\addbibresource` resource the snippet
/// names is registered as an analyzed, empty bibliography so the namespace is
/// closed and any cited key reads as undefined.
pub fn demo_diagnostics(source: &str) -> Vec<Diagnostic> {
    demo_diagnostics_at(&example_path(), source)
}

/// Like [`demo_diagnostics`] but lints the snippet under a given synthetic path.
/// Path-sensitive rules (gated on the file extension, like `missing-provides`)
/// pass their [`Rule::example_path`](crate::linter::rules::Rule::example_path) so
/// their examples fire.
pub fn demo_diagnostics_at(path: &Path, source: &str) -> Vec<Diagnostic> {
    demo_diagnostics_with(path, source, &[])
}

/// Like [`demo_diagnostics_at`] with synthetic sibling files linted alongside
/// the snippet — the two-file story a cross-file rule like `unknown-option`
/// needs (its example loads a `.sty` whose declared options live in a
/// companion). Each companion is parsed under its own file kind and its
/// package-option facts folded into the project view; companion paths are
/// relative, so a bare `mypkg.sty` is exactly what the snippet's
/// `\usepackage{mypkg}` resolves to next to `example.tex`.
pub fn demo_diagnostics_with(
    path: &Path,
    source: &str,
    companions: &[(&str, &str)],
) -> Vec<Diagnostic> {
    let path = path.to_path_buf();
    let root =
        SyntaxNode::new_root(parse_with_flavor(source, file_kind_or_tex(&path).lex_config()).green);
    let model = SemanticModel::build(&root);

    let mut option_facts: Vec<PackageOptionFacts> = package_option_facts(&path, &root, &model)
        .into_iter()
        .collect();
    for (companion_path, companion_source) in companions {
        let companion_path = Path::new(companion_path);
        let parsed = parse_with_flavor(
            companion_source,
            file_kind_or_tex(companion_path).lex_config(),
        );
        let companion_root = SyntaxNode::new_root(parsed.green);
        let companion_model = SemanticModel::build(&companion_root);
        option_facts.extend(package_option_facts(
            companion_path,
            &companion_root,
            &companion_model,
        ));
    }
    let resolved_packages = ResolvedPackageOptions::build(option_facts);

    let facts = [FileFacts {
        path: path.clone(),
        include_edges: collect_include_edge_keys(&root, None),
    }];
    let graph = IncludeGraph::build(&facts, None);

    // `true` treats the snippet as a document root, so the namespace is rooted
    // (and, with no unresolved includes, closed).
    let labels = [(
        path.clone(),
        document_label_names(&model),
        document_ref_names(&model),
        true,
    )];
    let resolved_labels = ResolvedLabels::build(&labels, &graph);

    let bib_targets = collect_bib_resource_targets(&root, None);
    let mut bib_keys: HashMap<PathBuf, Vec<SmolStr>> = HashMap::new();
    for target in &bib_targets {
        if let BibTarget::Path(p) = target {
            bib_keys.entry(p.clone()).or_default();
        }
    }
    let cite_facts = [CiteFileFacts {
        path: path.clone(),
        bib_targets,
        nocite_all: model.has_wildcard_nocite(),
        is_document_root: true,
    }];
    let resolved_citations = ResolvedCitations::build(&cite_facts, &graph, &bib_keys);

    lint_document(
        &path,
        &root,
        &model,
        Some(&resolved_labels),
        Some(&resolved_citations),
        Some(&resolved_packages),
    )
}

/// The language-agnostic inputs for one rule's reference section: the rule's
/// metadata, the synthetic path its snippets are linted under, and the fence
/// language. Linting itself is supplied by the caller, so the same renderer
/// serves both the LaTeX rules and the bib rules
/// ([`crate::bib::linter::docs`]).
pub(crate) struct RuleDocSection<'a> {
    pub id: &'a str,
    pub description: &'a str,
    pub default_enabled: bool,
    pub examples: &'a [Example],
    pub companions: &'a [(&'static str, &'static str)],
    pub example_path: &'a Path,
    pub lang: &'a str,
}

/// Render one rule's reference section from its inputs: an `## \`id\`` heading,
/// the description, and each example rendered with its live diagnostics (via
/// `lint`) and (for a safe autofix) the after state.
pub(crate) fn render_rule_section(
    section: &RuleDocSection<'_>,
    lint: &dyn Fn(&str) -> Vec<Diagnostic>,
) -> String {
    let mut out = String::new();
    let id = section.id;
    let _ = writeln!(out, "## `{id}`");

    let description = section.description.trim();
    if !description.is_empty() {
        let _ = writeln!(out);
        let _ = writeln!(out, "{description}");
    }

    let _ = writeln!(out);
    if section.default_enabled {
        let _ = writeln!(out, "This rule is **enabled by default**.");
    } else {
        let _ = writeln!(
            out,
            "This rule is **disabled by default**; enable it with `select`."
        );
    }

    // Synthetic sibling files linted alongside every example (the two-file
    // story of a cross-file rule); rendered once, before the examples.
    for (companion_path, companion_source) in section.companions {
        let _ = writeln!(out);
        let _ = writeln!(out, "With a sibling `{companion_path}`:");
        let _ = writeln!(out);
        fenced(&mut out, section.lang, companion_source);
    }

    for example in section.examples {
        let _ = writeln!(out);
        if !example.caption.is_empty() {
            let _ = writeln!(out, "{}", example.caption);
            let _ = writeln!(out);
        }
        fenced(&mut out, section.lang, example.source);

        // Restrict to this rule so an example can't advertise another's finding.
        let diagnostics: Vec<Diagnostic> = lint(example.source)
            .into_iter()
            .filter(|d| d.rule == id)
            .collect();
        let source = example.source.to_string();
        // Plain: the rendered snippet is fenced into a Markdown page, where an
        // ANSI escape would be literal text.
        let rendered = render_findings(&diagnostics, OutputMode::Pretty, false, &|path| {
            (path == section.example_path).then(|| source.clone())
        });
        let _ = writeln!(out);
        fenced(&mut out, "text", &rendered);

        // Safe fixes only, matching what `badness lint --fix` applies.
        let fixes: Vec<Fix> = diagnostics.iter().filter_map(|d| d.fix.clone()).collect();
        let after = apply_fixes(&source, &fixes, false);
        if after.applied > 0 {
            let _ = writeln!(out);
            let _ = writeln!(out, "After applying the fix:");
            let _ = writeln!(out);
            fenced(&mut out, section.lang, &after.output);
        }
    }

    out
}

/// Render the reference *section* for a single LaTeX rule: an `## \`id\``
/// heading, the rule's `description()`, and each example rendered with its live
/// diagnostics and (for a safe autofix) the after state.
pub fn render_rule_doc(rule: &dyn Rule) -> String {
    let example_path = PathBuf::from(rule.example_path());
    let companions = rule.example_companions();
    render_rule_section(
        &RuleDocSection {
            id: rule.id(),
            description: rule.description(),
            default_enabled: rule.default_enabled(),
            examples: rule.examples(),
            companions,
            example_path: &example_path,
            lang: "tex",
        },
        &|source| demo_diagnostics_with(&example_path, source, companions),
    )
}

/// Render the reference section for a current or retired LaTeX rule with `id`,
/// or `None` if the id is unknown. Backs `badness lint --explain <rule>`, reusing
/// the same live-linted rendering as the docs page for current rules.
pub fn explain_rule(id: &str) -> Option<String> {
    all_rules()
        .iter()
        .find(|rule| rule.id() == id)
        .map(|rule| render_rule_doc(rule.as_ref()))
        .or_else(|| retired_rule_doc(id))
}

fn retired_rule_doc(id: &str) -> Option<String> {
    match id {
        "mismatched-delimiter" => Some(String::from(
            "## `mismatched-delimiter`\n\n\
             Retired. TeX permits any valid delimiter glyph after either `\\left` \
             or `\\right`, including reversed and same-facing pairs such as \
             `\\left] ... \\right[` and `\\left] ... \\right]`. Delimiter \
             orientation therefore cannot prove an error, and the rule produced \
             false positives. The id remains accepted in `select` and `ignore` \
             for configuration compatibility, but it emits no diagnostics.\n",
        )),
        _ => None,
    }
}

/// The full `linter-rules.md` reference page: a static preamble, one generated
/// section per rule (registry order), and a static configuration footer.
pub fn render_reference_page() -> String {
    let mut out = String::from(PREAMBLE);
    for rule in all_rules() {
        out.push('\n');
        out.push_str(&render_rule_doc(rule.as_ref()));
    }
    out.push('\n');
    out.push_str(FOOTER);
    out
}

/// Write a fenced code block, normalizing the body to end with exactly one
/// newline so the closing fence always sits on its own line (idempotence).
fn fenced(out: &mut String, lang: &str, body: &str) {
    let _ = writeln!(out, "```{lang}");
    let _ = out.write_str(body);
    if !body.ends_with('\n') {
        let _ = out.write_str("\n");
    }
    let _ = writeln!(out, "```");
}

const PREAMBLE: &str = "\
<!-- Generated by `cargo run --example docgen`. Do not edit by hand: edit each \
rule's `description()`/`examples()` in `src/linter/rules/` and regenerate. -->

# Linter Rules

`badness lint` runs a set of built-in rules over each file's parse tree and
reports a diagnostic for every finding. Each section describes one rule,
identified by its stable **rule id**. The id appears in diagnostics and selects
the rule in `[lint]` settings, `--select` and `--ignore` flags, and
`% badness-lint skip <id>` comments.

Most rules are **on by default**. Each rule's section states whether it is
enabled by default. Use `select` to enable an opt-in rule, or use `select` and
`ignore` in the `[lint]` table to narrow the default set. See the
[Configuration reference](configuration.md#lint).

Some rules offer an **autofix** when a rewrite is unambiguous.
`badness lint --fix` applies *safe* fixes, shown below under \"After applying the
fix\". An *unsafe* fix may change output, such as by inserting a tie that
prevents a line break. It applies only with `--unsafe-fixes` or an editor code
action, so it has no \"after\" block here.

Each example below is linted live to produce its diagnostic and fixed output, so
this page never drifts from the rules' actual behavior.

This page covers the **LaTeX** linter. BibTeX files have a parallel set of rules
(a separate `BibRule` registry under `src/bib/linter/`), selectable through the
same `[lint]` config and cataloged in
[BibTeX Linter Rules](bib-linter-rules.md).
";

const FOOTER: &str = "\
## Suppression

To suppress a rule at a single site, use a comment directive:

```tex
% badness-lint skip deprecated-command: legacy code, leave as-is
{\\bf here}
```

The verb determines the scope. `skip` covers the next construct, `off` and `on`
delimit a region, and `skip-file` covers the whole file wherever the directive
appears:

```tex
% badness-lint off deprecated-command: legacy chapter
{\\bf here}
{\\it and here}
% badness-lint on deprecated-command
```

The `<id>` is optional. Omitting it suppresses every rule over the same span.
The `: <reason>` is optional everywhere.

`% badness skip` / `off` / `on` / `skip-file` do the same and turn off the
**formatter** at the same time; see [Formatting](../guide/formatting.md#turning-the-formatter-off)
for the layout-only `% badness-format` spellings.

Parse diagnostics (rule id `parse`) are never suppressed by `select`/`ignore`.
";