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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
//! What a passing `alef verify` actually proves -- stated in the report, every run.
//!
//! `alef verify`'s findings are all *negative* claims (nothing stale, nothing missing,
//! nothing orphaned), and a report made only of negative claims is indistinguishable from a
//! report that examined nothing. Consumer CI runs this command under job names like
//! "Alef-generated bindings freshness" and reads a green result as a whole-tree guarantee,
//! while the actual claim is much narrower: only files carrying an alef marker on disk are
//! held to a hash. Everything else is proven by PATH PRESENCE at best -- a present-but-wrong
//! file passes -- and files outside the ownership walk's scan set are never opened at all.
//!
//! This module states the gap in numbers alongside the verdict. It is the same fix
//! `alef snippets audit` needed when a snippets-only invocation printed a bare
//! "Audit clean: no issues found." for a run in which the documentation-page checks had
//! never executed: the floor is not "check more", it is "never let the report read as a
//! bigger claim than the check made". ~keep
/// The measured scope of one `alef verify` run.
///
/// Built by [`Self::measure`] from facts the run already has in hand, never from a second
/// walk of its own: a coverage report derived independently of the checks it describes can
/// disagree with them, which would make it worse than no report at all. ~keep
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
pub(crate) struct VerifyCoverage {
/// Paths this run's configuration would produce, across every selected crate.
pub(crate) managed_total: usize,
/// Managed paths that exist on disk carrying an alef marker: the only ones whose CONTENTS
/// were checked, by comparing the embedded `alef:hash:` against the current generation
/// inputs.
pub(crate) managed_content_verified: usize,
/// Managed paths that exist but carry no marker the walk could read -- create-once seeds,
/// formats with no comment syntax (`.json`, `.jar`, lockfiles) whose ownership lives in
/// `.alef-ownership.toml`, and anything the walk did not open. Their presence was checked;
/// nothing else about them was. ~keep
pub(crate) managed_present_only: usize,
/// Managed paths absent from disk. Already reported under the missing-file headings; kept
/// here so the three managed numbers add up to [`Self::managed_total`] and a reader can
/// see that they do.
pub(crate) managed_absent: usize,
/// Alef-marked files found on disk that this run's managed surface does not claim. The
/// orphan check reports these; counted here so a reader can tell "verify found nothing"
/// from "verify's surface and the disk disagree about this many files".
pub(crate) marked_outside_surface: usize,
/// Files the ownership walk opened and read anywhere under the tree.
pub(crate) files_opened: usize,
/// Files the walk reached and did not examine at all -- see
/// [`super::verify_scan::ScanCoverage::unexamined`].
pub(crate) files_unexamined: usize,
/// The subset of [`Self::managed_present_only`] that are create-once seeds carrying no
/// provenance marker.
///
/// Reported here rather than under a frozen-file heading, and that placement IS the fix:
/// alef writes a create-once seed only when its path is absent, so an existing one is a
/// user-owned file alef will never rewrite -- not drift, and not something any command can
/// or should change. See [`super::helpers::frozen::report_lines`] for the measured incident.
/// Stating the number as coverage keeps it visible on a clean run, which the old heading
/// (printed only when some other check had already failed) did not. ~keep
pub(crate) create_once_unmarked: usize,
/// The subset of [`Self::managed_absent`] that `[crates.verify].ignore_ephemeral`
/// (`crate::core::config::VerifyConfig`) matched and dropped from the "missing generated
/// files" / "missing generated files that are also gitignored" headings -- output the
/// consumer declared intentionally ephemeral (e.g. registry-mode `test_apps/`) and
/// deliberately never commits.
///
/// Reported here, unconditionally, for the same reason [`Self::create_once_unmarked`] is:
/// an opt-out that narrows what one check may report must never be free to shrink silently.
/// A run that excluded 316 paths must say so on every run, including a clean one -- not
/// only when a reader happens to look at the missing-file headings that no longer name
/// them. See `crate::core::config::verify`'s module doc for the incident this closes. ~keep
pub(crate) ephemeral_excluded: usize,
}
impl VerifyCoverage {
/// Measure one run from the managed surface it built and the walk it already performed.
///
/// `marked_paths` must be the paths of the SAME walk `scan` describes. Passing a set from
/// a different walk would make `managed_content_verified` describe files this run never
/// looked at. ~keep
pub(crate) fn measure(
managed_paths: &std::collections::HashSet<std::path::PathBuf>,
marked_paths: &std::collections::HashSet<std::path::PathBuf>,
scan: super::verify_scan::ScanCoverage,
create_once_unmarked: usize,
ephemeral_excluded: usize,
) -> Self {
let mut coverage = Self {
managed_total: managed_paths.len(),
marked_outside_surface: marked_paths.difference(managed_paths).count(),
files_opened: scan.opened,
files_unexamined: scan.unexamined,
create_once_unmarked,
ephemeral_excluded,
..Self::default()
};
for path in managed_paths {
if marked_paths.contains(path) {
coverage.managed_content_verified += 1;
} else if path.exists() {
coverage.managed_present_only += 1;
} else {
coverage.managed_absent += 1;
}
}
coverage
}
/// The report, one line per element, ready for [`super::output::line`].
///
/// A pure function returning lines rather than printing them, so the numbers and the
/// wording are unit-testable. `alef verify` writes through `output::line` straight to
/// stdout, which an in-process test cannot intercept -- an assertion on the printed text
/// would have to be a timing argument instead of a check. ~keep
pub(crate) fn report_lines(&self) -> Vec<String> {
let mut lines = vec![
"Verify coverage (what this run examined, so a green result is not read as more \
than it is):"
.to_owned(),
format!(
" managed surface: {} path(s) this configuration would produce",
self.managed_total
),
format!(
" {} content-verified (alef marker on disk, hashed against current generation inputs)",
self.managed_content_verified
),
format!(
" {} present but NOT content-verified (no readable marker: create-once seeds, formats \
that cannot carry one, paths proven by .alef-ownership.toml -- presence is the whole check, \
so a present-but-wrong file passes)",
self.managed_present_only
),
];
if self.create_once_unmarked > 0 {
lines.push(format!(
" of which {} are create-once seeds with no marker: alef writes each of these \
paths only when absent and never revisits it, so the missing marker is the \
documented user-owned steady state, not drift -- nothing needs adopting and no \
rerun changes this line (-vv lists them)",
self.create_once_unmarked
));
}
lines.push(format!(
" {} absent (reported under the missing-file headings)",
self.managed_absent
));
if self.ephemeral_excluded > 0 {
lines.push(format!(
" of which {} are excluded from those headings by `[crates.verify].ignore_ephemeral` \
(declared intentionally ephemeral and deliberately never committed -- their absence is \
never a failure, but they ARE still counted in the {} above)",
self.ephemeral_excluded, self.managed_absent
));
}
lines.push(format!(
" tree walk: {} file(s) opened, {} never examined (name and extension outside the \
ownership walk's scan set, or not readable as text -- nothing about their contents \
entered this result)",
self.files_opened, self.files_unexamined
));
if self.marked_outside_surface > 0 {
// Deliberately not "see the orphan heading": the orphan check excludes known
// create-once seed paths on top of this diff, so the two counts legitimately differ
// and pointing at a heading that may not be printed would be the same over-claim
// this module exists to stop. ~keep
lines.push(format!(
" {} alef-marked file(s) on disk are not claimed by this run's managed surface \
(the orphan check reports whichever of them it can attribute to a dropped emit)",
self.marked_outside_surface
));
}
lines
}
}
#[cfg(test)]
mod tests;