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