specfold_core/check/
baseline.rs

1//! A committed baseline of known findings, so a project can adopt specfold on an existing pile:
2//! what is already there is accepted, anything new fails, and the counts may only go down.
3//! Used by `spec check` ([check] baseline) and by each guard (its `baseline`); strict paths never
4//! get one.
5
6use super::finding::{Finding, Severity};
7use crate::corpus::Corpus;
8use crate::workspace::owners::{PathMatch, matcher};
9use crate::workspace::vcs;
10use anyhow::{Context, Result, anyhow, bail};
11use serde::{Deserialize, Serialize};
12use std::collections::BTreeMap;
13use std::path::Path;
14
15pub const SCHEMA: &str = "spec.baseline.v1";
16
17#[derive(Debug, Clone, Serialize, Deserialize)]
18pub struct Baseline {
19    pub schema: String,
20    /// The commit whose files were measured; it must stay in HEAD's history.
21    pub measured_on: String,
22    /// Error counts keyed `RULE<TAB>path`.
23    pub counts: BTreeMap<String, usize>,
24}
25
26/// The outcome of holding findings against a baseline.
27#[derive(Debug, Default)]
28pub struct Held {
29    /// Findings the baseline does not cover; these decide the exit code.
30    pub findings: Vec<Finding>,
31    /// Errors accepted because the baseline lists them.
32    pub known: usize,
33    /// Keys whose count fell below the baseline: (key, baseline, now).
34    pub lowerable: Vec<(String, usize, usize)>,
35}
36
37fn key(f: &Finding) -> String {
38    format!("{}\t{}", f.rule, f.path)
39}
40
41fn counted(f: &Finding, strict: &[PathMatch]) -> bool {
42    f.severity == Severity::Error && !strict.iter().any(|m| m.is_match(&f.path))
43}
44
45pub fn matchers(patterns: &[String]) -> Vec<PathMatch> {
46    patterns.iter().filter_map(|p| matcher(p)).collect()
47}
48
49/// Reads `rel` under `root`; None when it does not exist yet.
50pub fn load_file(root: &Path, rel: &str) -> Result<Option<Baseline>> {
51    let path = root.join(rel);
52    if !path.exists() {
53        return Ok(None);
54    }
55    let text = std::fs::read_to_string(&path).with_context(|| format!("cannot read {rel}"))?;
56    let b: Baseline = serde_json::from_str(&text).with_context(|| format!("{rel} is not a {SCHEMA} file"))?;
57    if b.schema != SCHEMA {
58        bail!("{rel} has schema {}, expected {SCHEMA}", b.schema);
59    }
60    match vcs::is_ancestor_of_head(root, &b.measured_on) {
61        Some(true) => Ok(Some(b)),
62        Some(false) => {
63            bail!("{rel} was measured on {}, which is not in HEAD's history; measure it again", b.measured_on)
64        }
65        None => bail!("{rel} names {}, which git does not know", b.measured_on),
66    }
67}
68
69pub fn hold_with(b: &Baseline, findings: Vec<Finding>, strict: &[PathMatch]) -> Held {
70    let mut seen: BTreeMap<String, usize> = BTreeMap::new();
71    let mut held = Held::default();
72    for f in findings {
73        if !counted(&f, strict) {
74            held.findings.push(f);
75            continue;
76        }
77        let k = key(&f);
78        let n = seen.entry(k.clone()).or_default();
79        *n += 1;
80        if *n <= b.counts.get(&k).copied().unwrap_or(0) {
81            held.known += 1;
82        } else {
83            held.findings.push(f);
84        }
85    }
86    for (k, &allowed) in &b.counts {
87        let now = seen.get(k).copied().unwrap_or(0);
88        if now < allowed {
89            held.lowerable.push((k.clone(), allowed, now));
90        }
91    }
92    held
93}
94
95/// Measures errors into a baseline. Refuses when a measured file differs from HEAD, because the
96/// baseline names a commit and must describe that commit's bytes.
97pub fn measure_with(
98    root: &Path,
99    findings: &[Finding],
100    strict: &[PathMatch],
101    measured: impl Fn(&str) -> bool,
102) -> Result<Baseline> {
103    let head = vcs::head(root).ok_or_else(|| anyhow!("a baseline needs a git repository with a commit"))?;
104    let changed = vcs::changed_since(root, "HEAD").unwrap_or_default();
105    let dirty: Vec<&str> = changed.iter().map(String::as_str).filter(|p| measured(p)).take(10).collect();
106    if !dirty.is_empty() {
107        bail!("commit these files first, the baseline names HEAD: {}", dirty.join(", "));
108    }
109    let mut counts = BTreeMap::new();
110    for f in findings.iter().filter(|f| counted(f, strict)) {
111        *counts.entry(key(f)).or_default() += 1;
112    }
113    Ok(Baseline { schema: SCHEMA.into(), measured_on: head, counts })
114}
115
116pub fn write_file(root: &Path, rel: &str, b: &Baseline) -> Result<()> {
117    let path = root.join(rel);
118    if let Some(dir) = path.parent() {
119        std::fs::create_dir_all(dir)?;
120    }
121    std::fs::write(&path, serde_json::to_string_pretty(b)? + "\n")?;
122    Ok(())
123}
124
125pub fn load(c: &Corpus) -> Result<Option<Baseline>> {
126    match &c.cfg.raw.check.baseline {
127        Some(rel) => load_file(&c.cfg.root, rel),
128        None => Ok(None),
129    }
130}
131
132pub fn hold(c: &Corpus, b: &Baseline, findings: Vec<Finding>) -> Held {
133    hold_with(b, findings, &matchers(&c.cfg.raw.check.strict))
134}
135
136pub fn measure(c: &Corpus, findings: &[Finding]) -> Result<Baseline> {
137    let strict = matchers(&c.cfg.raw.check.strict);
138    measure_with(&c.cfg.root, findings, &strict, |p| c.docs.iter().any(|d| d.path == p))
139}
140
141pub fn write(c: &Corpus, b: &Baseline) -> Result<String> {
142    let rel = c.cfg.raw.check.baseline.clone().ok_or_else(|| anyhow!("set [check] baseline in spec.toml first"))?;
143    write_file(&c.cfg.root, &rel, b)?;
144    Ok(rel)
145}
specfold_core/check/baseline.rs

specfold_core/check/
baseline.rs
