Skip to main content

drep/docs/
mod.rs

1//! Rule-based markdown checks. No LLM, no network, no configuration.
2//!
3//! Ten checks over the text of a markdown file, run by `drep lint-docs`. This
4//! module deliberately imports nothing from `llm`, `config` or `analysis`
5//! beyond the [`Finding`] vocabulary: `lint-docs` runs on every commit, and
6//! must not construct a provider chain or open a response cache.
7//!
8//! Structure:
9//!
10//! - `fence` answers "is this line inside a code fence", once per file, for
11//!   every check that asks. See its module doc for why that is not a per-check
12//!   concern.
13//! - `lines` holds the checks that look at one line in isolation.
14//! - `html` finds the raw HTML tags and comments, which may run over several
15//!   lines, for `links` to skip.
16//! - `links` holds the two that need markdown's link grammar.
17//! - `blocks` holds the three that span more than one line.
18//!
19//! The split is by what a check needs to see, not by file size, so a new check
20//! has an obvious home.
21
22mod blocks;
23mod fence;
24mod html;
25mod lines;
26mod links;
27
28use std::path::Path;
29
30use crate::analysis::findings::{Finding, Severity};
31
32/// Longest line drep will accept outside a code fence.
33///
34/// A fixed number, not a setting. `lint-docs` is report-only unless `--strict`
35/// is passed, so a project that disagrees (this repository does - its
36/// `.markdownlint.json` sets `MD013: false`) runs it report-only and ignores
37/// the line rather than tuning a threshold drep would then have to reconcile
38/// with the project's own linter.
39pub const LONG_LINE_MAX: usize = 120;
40
41/// Consecutive blank lines tolerated outside a code fence.
42///
43/// The check fires on the run that exceeds this, i.e. at three blanks.
44pub const BLANK_RUN_MAX: usize = 2;
45
46/// The ten checks.
47///
48/// The wire names are a stable output contract. [`Check::as_str`] is the only
49/// place a name is written.
50///
51/// [`Check::ALL`] is what the tests iterate, and it is a hand-maintained list:
52/// Rust cannot enumerate an enum without a derive macro, so nothing makes a
53/// new variant appear in it. What does force the author's hand is that the
54/// three `match self` methods below are exhaustive - a new variant fails to
55/// compile until all three are extended, and `ALL` sits immediately above
56/// them. Treat adding to `ALL` as part of adding a variant; a check missing
57/// from it silently drops out of every test in this module.
58#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
59pub enum Check {
60    BareUrl,
61    EmptyHeading,
62    LinkSyntaxInvalid,
63    LongLine,
64    MissingSpaceAfterHeading,
65    MultipleBlankLines,
66    TabCharacter,
67    TrailingBlankLines,
68    TrailingWhitespace,
69    UnclosedCodeFence,
70}
71
72impl Check {
73    /// Every check. The one place the vocabulary is listed.
74    pub const ALL: [Check; 10] = [
75        Check::BareUrl,
76        Check::EmptyHeading,
77        Check::LinkSyntaxInvalid,
78        Check::LongLine,
79        Check::MissingSpaceAfterHeading,
80        Check::MultipleBlankLines,
81        Check::TabCharacter,
82        Check::TrailingBlankLines,
83        Check::TrailingWhitespace,
84        Check::UnclosedCodeFence,
85    ];
86
87    /// The wire name, as it appears in a finding's `kind`.
88    pub const fn as_str(self) -> &'static str {
89        match self {
90            Check::BareUrl => "bare_url",
91            Check::EmptyHeading => "empty_heading",
92            Check::LinkSyntaxInvalid => "link_syntax_invalid",
93            Check::LongLine => "long_line",
94            Check::MissingSpaceAfterHeading => "missing_space_after_heading",
95            Check::MultipleBlankLines => "multiple_blank_lines",
96            Check::TabCharacter => "tab_character",
97            Check::TrailingBlankLines => "trailing_blank_lines",
98            Check::TrailingWhitespace => "trailing_whitespace",
99            Check::UnclosedCodeFence => "unclosed_code_fence",
100        }
101    }
102
103    /// How badly this check's subject breaks the document.
104    ///
105    /// One rule decides all ten: **does it change how the document renders?**
106    ///
107    /// - [`Severity::Error`] - the rest of the file renders as something else.
108    ///   Only an unclosed fence does that, and it does it to every line below
109    ///   itself.
110    /// - [`Severity::Warning`] - that line renders wrong. A heading that is not
111    ///   a heading, a link that is not a link.
112    /// - [`Severity::Info`] - renders identically; this is hygiene.
113    ///
114    /// The rule matters because `drep lint-docs --strict` and `--fail-on`
115    /// downstream both gate on it, and "whitespace blocks a commit" is the
116    /// calibration failure that makes a gate get switched off.
117    pub const fn severity(self) -> Severity {
118        match self {
119            Check::UnclosedCodeFence => Severity::Error,
120            Check::EmptyHeading | Check::MissingSpaceAfterHeading | Check::LinkSyntaxInvalid => {
121                Severity::Warning
122            }
123            Check::BareUrl
124            | Check::LongLine
125            | Check::MultipleBlankLines
126            | Check::TabCharacter
127            | Check::TrailingBlankLines
128            | Check::TrailingWhitespace => Severity::Info,
129        }
130    }
131
132    /// What to do about it. Advice, never a literal replacement.
133    ///
134    /// A literal replacement would be misleading for checks whose fix requires
135    /// judgment, so this field consistently describes the intended result.
136    pub const fn suggestion(self) -> &'static str {
137        match self {
138            Check::BareUrl => "wrap it as [text](url)",
139            Check::EmptyHeading => "give the heading text, or delete the line",
140            Check::LinkSyntaxInvalid => "balance the brackets: [text](url)",
141            Check::LongLine => "wrap or rephrase",
142            Check::MissingSpaceAfterHeading => "put a space after the `#`s",
143            Check::MultipleBlankLines => "reduce to one blank line",
144            Check::TabCharacter => "replace tabs with spaces",
145            Check::TrailingBlankLines => "remove the blank line(s) at end of file",
146            Check::TrailingWhitespace => "remove the trailing whitespace",
147            Check::UnclosedCodeFence => {
148                "close it with a fence of the same character, at least as long"
149            }
150        }
151    }
152}
153
154/// One line, and where it sits.
155///
156/// Deliberately does **not** carry the line's characters. Every column drep
157/// reports is a character offset rather than a byte offset - a heading under a
158/// line containing an em dash must not have its column shifted by two - so the
159/// checks do need a `[char]`, but only for the line being examined. Holding one
160/// `Vec<char>` per line meant an allocation per line of every file and 43% of
161/// the analysis pass; [`analyze`] now fills a single reused buffer instead.
162/// [`blocks`] needs no characters at all.
163pub(crate) struct Line<'a> {
164    /// 1-based line number, as reported.
165    pub number: u32,
166    /// The line as written, without its terminator.
167    pub text: &'a str,
168    /// True iff a fence delimiter or a line between two of them.
169    pub in_fence: bool,
170}
171
172/// Build a [`Finding`] for `check` at a position.
173///
174/// Central so that the kind/severity/suggestion triple is never assembled by
175/// hand at a check site, where one of the three can quietly disagree with
176/// [`Check`].
177pub(crate) fn finding(
178    check: Check,
179    file_path: &str,
180    line: u32,
181    column: u32,
182    message: String,
183) -> Finding {
184    Finding::deterministic(
185        check.as_str().to_owned(),
186        check.severity(),
187        file_path.to_owned(),
188        line,
189        Some(column),
190        message,
191        Some(check.suggestion().to_owned()),
192    )
193}
194
195/// Run every check over `content`, reporting against `path`.
196///
197/// Findings come back sorted by position, then by check name, so the output of
198/// two runs over the same file is byte-identical and a reader follows the file
199/// top to bottom. The checks themselves run in whatever order is convenient;
200/// grouping output by check would make a reader jump around the file.
201pub fn analyze(path: &Path, content: &str) -> Vec<Finding> {
202    let file_path = path.to_string_lossy().into_owned();
203    let raw: Vec<&str> = content.lines().collect();
204    let fences = fence::Fences::scan(&raw);
205
206    let lines: Vec<Line<'_>> = raw
207        .iter()
208        .zip(fences.mask())
209        .enumerate()
210        .map(|(index, (text, in_fence))| Line {
211            number: index as u32 + 1,
212            text,
213            in_fence: *in_fence,
214        })
215        .collect();
216
217    // Two buffers for the whole file rather than one allocation per line:
218    // `chars` holds the line under examination, `scratch` the blanked copy the
219    // link checks work on. Both are cleared and refilled, so peak memory is the
220    // longest line rather than the file.
221    let html = html::spans(&lines);
222    let mut findings = Vec::new();
223    let mut chars: Vec<char> = Vec::new();
224    let mut scratch: Vec<char> = Vec::new();
225    for (line, html) in lines.iter().zip(&html) {
226        chars.clear();
227        chars.extend(line.text.chars());
228        lines::check(line, &chars, &file_path, &mut findings);
229        links::check(line, &chars, html, &mut scratch, &file_path, &mut findings);
230    }
231    blocks::check(&lines, &fences, &file_path, &mut findings);
232
233    findings.sort_by(|a, b| (a.line, a.column, &a.kind).cmp(&(b.line, b.column, &b.kind)));
234    findings
235}
236
237#[cfg(test)]
238mod tests;