Skip to main content

spec_driven_docs/services/
lint.rs

1//! What the Markdown linter will read here, reported, and one proof that its
2//! link rule runs.
3//!
4//! The report reads the discovery locations the status report names for the
5//! active profile, or for the candidate profile before a landing, and turns
6//! each configuration that breaks the delivered shapes, each link rule that
7//! is not loaded or not enabled, and each reserved Markdown path the linter
8//! still reads into one finding with the rule it breaks and the kind of edit
9//! that resolves it. A configuration whose grammar this binary does not read,
10//! a JavaScript module, is reported as `unknown` rather than guessed at.
11//!
12//! The proof runs the delivered Markdown hook over a scratch file at the
13//! repository root, first with a broken relative link and then a valid one,
14//! and removes the file. A broken link that lints clean is a failed proof,
15//! because it means the rule silently does not run.
16
17use camino::{Utf8Path, Utf8PathBuf};
18use serde::Serialize;
19
20use crate::domain::markdownlint::{CLI2_NAMES, LIBRARY_NAMES, RELATIVE_LINKS_PACKAGE};
21use crate::domain::profile::ProfileId;
22use crate::domain::rule_id::RuleId;
23use crate::error::AppError;
24
25/// The machine schema `sdd lint --json` declares.
26pub const SCHEMA: &str = "sdd.lint/1";
27
28/// The machine schema `sdd lint prove --json` declares.
29pub const PROVE_SCHEMA: &str = "sdd.lint-prove/1";
30
31/// The rule the link findings and the proof cite.
32const LINKS: RuleId = RuleId::RootLintConfigurationLoadsRelativeLinks;
33
34/// The rule the placement findings cite.
35const COMPOSES: RuleId = RuleId::LintConfigurationComposes;
36
37/// The rule the reserved-path findings cite.
38const DECLARES: RuleId = RuleId::ProjectDeclaresWhatItsGatesJudge;
39
40/// The rule name markdownlint reports a broken relative link under.
41const LINK_RULE: &str = "relative-links";
42
43/// The edit one finding needs.
44#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
45#[serde(rename_all = "kebab-case")]
46pub enum Edit {
47    /// Fold the configuration into the repository root's CLI2 file.
48    FoldIntoRoot,
49    /// Replace a linked directory with the directory itself.
50    ReplaceLink,
51    /// Add the link rule's package to `customRules`.
52    LoadRelativeLinks,
53    /// Set `"relative-links": true` in the effective rules.
54    EnableRelativeLinks,
55    /// Add a CLI2 file at the root beside a library-family file, to load the
56    /// rule.
57    AddCompanionCli2,
58    /// Add a reserved Markdown path to the root CLI2 file's `ignores`.
59    AddIgnore,
60    /// The binary cannot read this configuration; the agent inspects it.
61    Unknown,
62}
63
64/// One finding.
65#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
66pub struct Finding {
67    /// The path the edit lands on, relative to the target, or the reserved
68    /// pattern.
69    pub path: String,
70    /// The rule the finding breaks.
71    pub rule: &'static str,
72    /// The edit that resolves it.
73    pub edit: Edit,
74}
75
76/// Which profile the report read, and what decided it.
77#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
78#[serde(rename_all = "kebab-case")]
79pub enum ProfileSource {
80    /// The instance record.
81    Recorded,
82    /// The `--profile` flag, before a landing.
83    Flag,
84    /// The codebase default, before a landing.
85    Default,
86}
87
88/// The whole report.
89#[derive(Debug, Clone, Serialize)]
90pub struct Report {
91    /// The machine schema of this object.
92    pub schema: &'static str,
93    /// The repository read.
94    pub target: Utf8PathBuf,
95    /// The profile whose discovery locations were read.
96    pub profile: ProfileId,
97    /// What decided the profile.
98    pub profile_source: ProfileSource,
99    /// Every finding, in the order the report reads the locations.
100    pub findings: Vec<Finding>,
101}
102
103fn finding(path: impl Into<String>, rule: RuleId, edit: Edit) -> Finding {
104    Finding {
105        path: path.into(),
106        rule: rule.as_str(),
107        edit,
108    }
109}
110
111/// The profile a report reads: the recorded one wherever an instance is.
112fn profile(
113    target: &Utf8Path,
114    flag: Option<ProfileId>,
115) -> Result<(ProfileId, ProfileSource), AppError> {
116    let recorded =
117        crate::services::installer::recorded_field(target, "profile").and_then(|value| {
118            ProfileId::every().find(|profile| Some(profile.as_str()) == value.as_str())
119        });
120    match (recorded, flag) {
121        (Some(recorded), Some(asked)) if recorded != asked => Err(AppError::Refused(format!(
122            "{target} records the {recorded} profile and this report asks for {asked}"
123        ))),
124        (Some(recorded), _) => Ok((recorded, ProfileSource::Recorded)),
125        (None, Some(asked)) => Ok((asked, ProfileSource::Flag)),
126        (None, None) => Ok((ProfileId::Codebase, ProfileSource::Default)),
127    }
128}
129
130/// JSON with comments and trailing commas, as markdownlint-cli2 reads it.
131fn jsonc(text: &str) -> Option<serde_json::Value> {
132    let mut out = String::with_capacity(text.len());
133    let mut chars = text.chars().peekable();
134    let mut in_string = false;
135    while let Some(c) = chars.next() {
136        if in_string {
137            out.push(c);
138            if c == '\\' {
139                if let Some(next) = chars.next() {
140                    out.push(next);
141                }
142            } else if c == '"' {
143                in_string = false;
144            }
145            continue;
146        }
147        match (c, chars.peek()) {
148            ('"', _) => {
149                in_string = true;
150                out.push(c);
151            }
152            ('/', Some('/')) => {
153                for skipped in chars.by_ref() {
154                    if skipped == '\n' {
155                        out.push('\n');
156                        break;
157                    }
158                }
159            }
160            ('/', Some('*')) => {
161                chars.next();
162                let mut last = ' ';
163                for skipped in chars.by_ref() {
164                    if last == '*' && skipped == '/' {
165                        break;
166                    }
167                    last = skipped;
168                }
169            }
170            _ => out.push(c),
171        }
172    }
173    let trailing = regex::Regex::new(r",(\s*[}\]])").ok()?;
174    serde_json::from_str(&trailing.replace_all(&out, "$1")).ok()
175}
176
177/// One configuration file's contents, where this binary reads its grammar.
178fn read_configuration(path: &Utf8Path) -> Option<serde_json::Value> {
179    let text = std::fs::read_to_string(path).ok()?;
180    match path.extension() {
181        Some("jsonc" | "json") => jsonc(&text),
182        Some("yaml" | "yml") => yaml_serde::from_str(&text).ok(),
183        _ => None,
184    }
185}
186
187/// Whether a rules object turns the link rule on.
188fn enables(rules: Option<&serde_json::Value>) -> bool {
189    match rules.and_then(|rules| rules.get(LINK_RULE)) {
190        Some(serde_json::Value::Bool(on)) => *on,
191        Some(serde_json::Value::Object(_)) => true,
192        _ => false,
193    }
194}
195
196/// The findings the repository root's configuration raises.
197///
198/// SATISFIES instance:the-root-lint-configuration-loads-relative-links
199fn root_findings(target: &Utf8Path, landed: bool, findings: &mut Vec<Finding>) {
200    let present = |name: &str| std::fs::symlink_metadata(target.join(name)).is_ok();
201    let cli2: Vec<&str> = CLI2_NAMES
202        .into_iter()
203        .filter(|name| present(name))
204        .collect();
205    let library: Vec<&str> = LIBRARY_NAMES
206        .into_iter()
207        .filter(|name| present(name))
208        .collect();
209    if cli2.is_empty() && library.is_empty() {
210        // Before a landing the root seed lands here and loads the rule.
211        if landed {
212            findings.push(finding(CLI2_NAMES[0], LINKS, Edit::LoadRelativeLinks));
213        }
214        return;
215    }
216    // The linter reads the first CLI2 file by precedence and ignores the
217    // rest, so a setting in a later one loads nothing.
218    let Some(effective) = cli2.first() else {
219        findings.push(finding(CLI2_NAMES[0], LINKS, Edit::AddCompanionCli2));
220        return library_findings(target, &library, None, findings);
221    };
222    let Some(value) = read_configuration(&target.join(effective)) else {
223        findings.push(finding(*effective, LINKS, Edit::Unknown));
224        return library_findings(target, &library, None, findings);
225    };
226    let loaded = value
227        .get("customRules")
228        .and_then(serde_json::Value::as_array)
229        .is_some_and(|rules| {
230            rules.iter().any(|rule| {
231                rule.as_str()
232                    .is_some_and(|rule| rule.contains(RELATIVE_LINKS_PACKAGE))
233            })
234        });
235    if !loaded {
236        findings.push(finding(*effective, LINKS, Edit::LoadRelativeLinks));
237    }
238    library_findings(target, &library, Some((effective, &value)), findings);
239}
240
241/// The findings on which file's rules turn the link rule on.
242fn library_findings(
243    target: &Utf8Path,
244    library: &[&str],
245    cli2: Option<(&str, &serde_json::Value)>,
246    findings: &mut Vec<Finding>,
247) {
248    // A library-family file at the root replaces the CLI2 file's `config`,
249    // so it is the one whose rules decide.
250    if let Some(name) = library.first() {
251        match read_configuration(&target.join(name)) {
252            Some(rules) if enables(Some(&rules)) => {}
253            Some(_) => findings.push(finding(*name, LINKS, Edit::EnableRelativeLinks)),
254            None => findings.push(finding(*name, LINKS, Edit::Unknown)),
255        }
256    } else if let Some((name, value)) = cli2
257        && !enables(value.get("config"))
258    {
259        findings.push(finding(name, LINKS, Edit::EnableRelativeLinks));
260    }
261}
262
263/// The `ignores` the root CLI2 file the linter reads carries, where it is
264/// readable.
265fn root_ignores(target: &Utf8Path) -> Vec<String> {
266    CLI2_NAMES
267        .iter()
268        .find(|name| std::fs::symlink_metadata(target.join(name)).is_ok())
269        .and_then(|name| read_configuration(&target.join(name)))
270        .and_then(|value| {
271            value
272                .get("ignores")
273                .and_then(serde_json::Value::as_array)
274                .cloned()
275        })
276        .into_iter()
277        .flatten()
278        .filter_map(|entry| entry.as_str().map(String::from))
279        .collect()
280}
281
282/// Every reserved pattern that matches Markdown the linter still reads.
283fn reserved_findings(target: &Utf8Path, findings: &mut Vec<Finding>) {
284    use crate::domain::path_filter::{Layer, PathFilter, Pattern};
285
286    let Ok(declaration) = crate::domain::instance_config::InstanceConfig::read(target) else {
287        return;
288    };
289    if declaration.reserved.is_empty() {
290        return;
291    }
292    let markdown: Vec<Utf8PathBuf> = walkdir::WalkDir::new(target)
293        .into_iter()
294        .filter_entry(|entry| {
295            let name = entry.file_name().to_string_lossy();
296            !(entry.depth() > 0
297                && entry.file_type().is_dir()
298                && crate::gates::PRUNED_DIRS.contains(&name.as_ref()))
299        })
300        .filter_map(Result::ok)
301        .filter(|entry| entry.file_type().is_file())
302        .filter_map(|entry| {
303            let path = Utf8Path::from_path(entry.path())?;
304            let relative = path.strip_prefix(target).ok()?;
305            (relative.extension() == Some("md")).then(|| relative.to_owned())
306        })
307        .collect();
308    let ignores = root_ignores(target);
309    for glob in &declaration.reserved {
310        let Ok(filter) = PathFilter::build(
311            Vec::new(),
312            vec![Pattern::new(glob.clone(), Layer::Reserved)],
313        ) else {
314            continue;
315        };
316        let holds_markdown = markdown.iter().any(|path| !filter.judges(path));
317        if holds_markdown && !ignores.iter().any(|ignored| ignored == glob) {
318            findings.push(finding(glob.clone(), DECLARES, Edit::AddIgnore));
319        }
320    }
321}
322
323/// Report what the Markdown linter will read at `target`.
324///
325/// SATISFIES setup:lint-reports-each-finding-with-its-rule
326///
327/// # Errors
328///
329/// [`AppError::Refused`] where the flag names another profile than the
330/// record.
331pub fn report(target: &Utf8Path, flag: Option<ProfileId>) -> Result<Report, AppError> {
332    let (profile, profile_source) = profile(target, flag)?;
333    let docs_root = crate::candidate::docs_root_of(profile)?;
334    let landed = profile_source == ProfileSource::Recorded;
335    let mut findings = Vec::new();
336    for path in crate::services::verifier::linked_lint_scan_roots(target, docs_root) {
337        findings.push(finding(path.to_string(), COMPOSES, Edit::ReplaceLink));
338    }
339    for path in
340        crate::services::verifier::lint_configurations_that_break_composition(target, docs_root)
341    {
342        findings.push(finding(path.to_string(), COMPOSES, Edit::FoldIntoRoot));
343    }
344    root_findings(target, landed, &mut findings);
345    if landed {
346        reserved_findings(target, &mut findings);
347    }
348    Ok(Report {
349        schema: SCHEMA,
350        target: target.to_owned(),
351        profile,
352        profile_source,
353        findings,
354    })
355}
356
357/// One run of the hook over the scratch file.
358#[derive(Debug, Clone, Serialize)]
359pub struct Run {
360    /// The process exit code, where it exited with one.
361    pub exit: Option<i32>,
362    /// Whether the output names the link rule.
363    pub cites_rule: bool,
364}
365
366/// The whole proof.
367#[derive(Debug, Clone, Serialize)]
368pub struct Proof {
369    /// The machine schema of this object.
370    pub schema: &'static str,
371    /// The command the proof ran, before the scratch file's name.
372    pub command: Vec<String>,
373    /// The run over a broken relative link, which must fail on the rule.
374    pub broken: Run,
375    /// The run over a valid relative link, which must pass.
376    pub valid: Run,
377    /// Whether the rule fired on the broken link and stayed quiet on the
378    /// valid one.
379    pub ok: bool,
380    /// The rule the proof holds.
381    pub rule: &'static str,
382}
383
384/// The command a proof runs: the delivered hook through pre-commit, unless
385/// the operator's environment names another runner.
386fn command() -> Vec<String> {
387    crate::domain::paths::variable(crate::domain::paths::LINT_PROVE_RUNNER_VAR).map_or_else(
388        || {
389            ["pre-commit", "run", "markdownlint-cli2", "--files"]
390                .map(String::from)
391                .to_vec()
392        },
393        |runner| runner.split_whitespace().map(String::from).collect(),
394    )
395}
396
397/// Run the command over one file and read what it said.
398fn run(target: &Utf8Path, command: &[String], file: &str) -> Result<Run, AppError> {
399    let (program, args) = command
400        .split_first()
401        .ok_or_else(|| AppError::Usage("the lint proof runner names no program".to_string()))?;
402    let output = std::process::Command::new(program)
403        .args(args)
404        .arg(file)
405        .current_dir(target)
406        .stdin(std::process::Stdio::null())
407        .output()
408        .map_err(|source| {
409            AppError::Unavailable(format!(
410                "{program} could not run, so the proof cannot hold the rule: {source}"
411            ))
412        })?;
413    let said = format!(
414        "{}{}",
415        String::from_utf8_lossy(&output.stdout),
416        String::from_utf8_lossy(&output.stderr)
417    );
418    Ok(Run {
419        exit: output.status.code(),
420        cites_rule: said.contains(LINK_RULE),
421    })
422}
423
424/// Prove the link rule runs at `target`, and remove the scratch file.
425///
426/// SATISFIES instance:the-root-lint-configuration-loads-relative-links
427///
428/// # Errors
429///
430/// [`AppError::Unavailable`] where the runner cannot start, and I/O errors
431/// writing or removing the scratch file.
432pub fn prove(target: &Utf8Path) -> Result<Proof, AppError> {
433    let name = format!("sdd-lint-proof-{}.md", std::process::id());
434    let path = target.join(&name);
435    if std::fs::symlink_metadata(&path).is_ok() {
436        return Err(AppError::Refused(format!(
437            "{path} already exists, and the proof writes only a file of its own"
438        )));
439    }
440    let command = command();
441    let broken = format!("# Proof\n\nA [broken link](./{name}.missing.md).\n");
442    let valid = format!("# Proof\n\nA [valid link](./{name}).\n");
443    let result = (|| {
444        crate::adapters::fs::write_file(&path, broken.as_bytes())?;
445        let broken = run(target, &command, &name)?;
446        crate::adapters::fs::write_file(&path, valid.as_bytes())?;
447        let valid = run(target, &command, &name)?;
448        Ok::<_, AppError>((broken, valid))
449    })();
450    let removed = std::fs::remove_file(&path);
451    let (broken, valid) = result?;
452    removed?;
453    let ok = broken.exit != Some(0) && broken.cites_rule && valid.exit == Some(0);
454    Ok(Proof {
455        schema: PROVE_SCHEMA,
456        command,
457        broken,
458        valid,
459        ok,
460        rule: LINKS.as_str(),
461    })
462}
463
464#[cfg(test)]
465mod tests {
466    use super::*;
467
468    #[test]
469    fn jsonc_reads_comments_and_trailing_commas() {
470        let value = jsonc(
471            "// head\n{\n  \"customRules\": [\"a//b\", /* x */ \"c\",],\n  \"config\": {\"relative-links\": true,},\n}\n",
472        )
473        .expect("the JSONC parses");
474        assert_eq!(value["customRules"][0], "a//b");
475        assert!(enables(value.get("config")));
476    }
477
478    #[test]
479    fn the_rule_is_enabled_by_true_or_by_options() {
480        assert!(enables(Some(
481            &serde_json::json!({"relative-links": {"root_path": "."}})
482        )));
483        assert!(!enables(Some(
484            &serde_json::json!({"relative-links": false})
485        )));
486        assert!(!enables(Some(&serde_json::json!({}))));
487        assert!(!enables(None));
488    }
489}