badness 0.28.0

A language server, formatter, and linter for LaTeX
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! Rendering the bib linter-rules reference from rule metadata.
//!
//! The bib analog of [`crate::linter::docs`], sharing its section renderer
//! ([`render_rule_section`]) so the two references cannot drift in shape.
//! [`render_rule_doc`] and [`render_reference_page`] are the single source of
//! truth shared by the snapshot test (`tests/bib_rule_docs.rs`) and the docs
//! generator (`examples/docgen.rs`), so the committed
//! `docs/src/reference/bib-linter-rules.md` and the pinned snapshots can never
//! diverge from behavior. Every example is linted by the *real* bib driver
//! ([`demo_diagnostics`]), so the rendered diagnostics and the autofix
//! before/after always reflect the current rules.

use std::path::PathBuf;

use crate::bib::linter::check::lint_document;
use crate::bib::linter::rules::{BibRule, all_rules};
use crate::bib::parse;
use crate::bib::semantic::Model;
use crate::linter::diagnostic::Diagnostic;
use crate::linter::docs::{RuleDocSection, render_rule_section};

/// The synthetic path an example snippet is linted under. Every bib rule is
/// single-file-sound, so one fixed name serves all of them (no per-rule
/// `example_path` the way path-gated LaTeX rules need).
fn example_path() -> PathBuf {
    PathBuf::from("references.bib")
}

/// Lint `source` as a self-contained `.bib` file: parse, build the semantic
/// [`Model`], and run every built-in bib rule.
pub fn demo_diagnostics(source: &str) -> Vec<Diagnostic> {
    let path = example_path();
    let root = parse(source).syntax();
    let model = Model::build(&root);
    lint_document(&path, &root, &model)
}

/// Render the reference *section* for a single bib 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 BibRule) -> String {
    let path = example_path();
    render_rule_section(
        &RuleDocSection {
            id: rule.id(),
            description: rule.description(),
            default_enabled: rule.default_enabled(),
            examples: rule.examples(),
            companions: &[],
            example_path: &path,
            lang: "bib",
        },
        &demo_diagnostics,
    )
}

/// Render the reference section for the bib rule with `id`, or `None` if no
/// built-in bib rule has that id. Backs `badness lint --explain <rule>` (after
/// the LaTeX registry misses), reusing the same live-linted rendering as the
/// docs page.
pub fn explain_rule(id: &str) -> Option<String> {
    all_rules()
        .iter()
        .find(|rule| rule.id() == id)
        .map(|rule| render_rule_doc(rule.as_ref()))
}

/// The full `bib-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
}

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

# BibTeX Linter Rules

`badness lint` runs a parallel set of built-in rules over each `.bib` file's
parse tree and reports a diagnostic for every finding. Each section describes
one rule, identified by its stable **rule id**. BibTeX rules share an id
namespace with the [LaTeX rules](linter-rules.md), so the same `[lint]` settings
and `--select` and `--ignore` flags select both sets.

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\".

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

const FOOTER: &str = "\
## Suppression

BibTeX has no line-comment token, so write suppression directives inside
structured `@comment` entries. A `skip` directive suppresses one rule on the
**next entry**:

```bib
@comment{badness-lint skip missing-required-field: publisher long gone}
@book{oldbook, title = {An Orphaned Book}}
```

The directive grammar is the same as in LaTeX. `off` and `on` delimit a
region of entries, and `skip-file` covers the whole file wherever the directive
appears:

```bib
@comment{badness-lint off missing-required-field: imported, incomplete by design}
@book{oldbook, title = {An Orphaned Book}}
@comment{badness-lint on missing-required-field}
```

The `<id>` is optional. Omitting it suppresses every rule over the same span.
Parse diagnostics (rule id `parse`) are never suppressed.
";