easement 0.3.0

Architecture quality gate for polyglot codebases
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

use std::collections::BTreeSet;
use std::path::Path;

use anyhow::{Context, Result};
use serde::{Deserialize, Serialize};

use crate::check::{Key, Violation};

const HEADER: &str = "# Legalized architecture violations. Generated by `easement baseline`.\n\
# Fix them and regenerate: the gate fails on new violations and on stale entries.\n";

#[derive(Debug, Default, Serialize, Deserialize)]
pub struct Baseline {
    pub violations: BTreeSet<Key>,
}

impl Baseline {
    pub fn load(path: &Path) -> Result<Option<Self>> {
        if !path.exists() {
            return Ok(None);
        }
        let text = std::fs::read_to_string(path)
            .with_context(|| format!("cannot read baseline {}", path.display()))?;
        let baseline = serde_norway::from_str(&text)
            .with_context(|| format!("invalid baseline {}", path.display()))?;
        Ok(Some(baseline))
    }

    pub fn from_violations(violations: &[Violation]) -> Self {
        Self {
            violations: violations.iter().map(Violation::key).collect(),
        }
    }

    pub fn save(&self, path: &Path) -> Result<()> {
        let body = serde_norway::to_string(self)?;
        std::fs::write(path, format!("{HEADER}{body}"))
            .with_context(|| format!("cannot write baseline {}", path.display()))
    }
}

/// Result of judging the current violations against a baseline.
pub struct Verdict {
    /// Violations not covered by the baseline.
    pub new: Vec<Violation>,
    /// Baseline entries that no longer occur: the debt was paid, the baseline must shrink.
    pub stale: Vec<Key>,
    pub legalized: usize,
}

impl Verdict {
    /// `violations` are the ones being judged (all of them, or only those in a
    /// diff); `current` are the keys of every violation in the project, which
    /// decide whether a baseline entry is stale.
    pub fn judge(
        violations: Vec<Violation>,
        current: &BTreeSet<Key>,
        baseline: Option<&Baseline>,
    ) -> Self {
        let Some(baseline) = baseline else {
            return Self {
                new: violations,
                stale: Vec::new(),
                legalized: 0,
            };
        };
        let stale = baseline.violations.difference(current).cloned().collect();
        let (legal, new): (Vec<_>, Vec<_>) = violations
            .into_iter()
            .partition(|v| baseline.violations.contains(&v.key()));
        Self {
            new,
            stale,
            legalized: legal.len(),
        }
    }

    pub fn passed(&self) -> bool {
        self.new.is_empty() && self.stale.is_empty()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn v(file: &str, to: &str) -> Violation {
        Violation {
            rule: crate::check::RuleId::Dependency,
            file: file.into(),
            line: 1,
            message: String::new(),
            because: None,
            from: "a".into(),
            to: to.into(),
            target: format!("{to}/x"),
            specifier: String::new(),
            evidence: Vec::new(),
        }
    }

    #[test]
    fn one_baseline_entry_legalizes_every_use_of_its_key() {
        let mut second = v("f1", "b");
        second.line = 9;
        let baseline = Baseline::from_violations(&[v("f1", "b")]);
        let found = vec![v("f1", "b"), second];
        let current = found.iter().map(Violation::key).collect();
        let verdict = Verdict::judge(found, &current, Some(&baseline));
        assert_eq!(verdict.legalized, 2);
        assert!(verdict.passed());
    }

    #[test]
    fn ratchet_fails_on_new_and_stale() {
        let baseline = Baseline::from_violations(&[v("f1", "b"), v("f2", "b")]);
        let found = vec![v("f1", "b"), v("f3", "c")];
        let current = found.iter().map(Violation::key).collect();
        let verdict = Verdict::judge(found, &current, Some(&baseline));
        assert_eq!(verdict.legalized, 1);
        assert_eq!(verdict.new.len(), 1);
        assert_eq!(verdict.new[0].file, "f3");
        assert_eq!(verdict.stale.len(), 1);
        assert_eq!(verdict.stale[0].file, "f2");
        assert!(!verdict.passed());
    }
}