memstead_cli/
coverage.rs

1//! The CLI's axis-coverage registry: every subcommand a caller can
2//! reach declares either which axes its clean verdict examined or why
3//! it emits no verdict at all. The rule, its vocabulary, and the
4//! validator live in `memstead_base::ops::coverage`; this module is
5//! the CLI consumer's declaration, and the test at the bottom is the
6//! gate: it walks the live clap tree, so a new subcommand fails here
7//! until it declares, and a new axis fails every verdict row that
8//! has not met it.
9
10use memstead_base::ops::coverage::{AxisCoverage, CoverageDisposition, SurfaceCoverage};
11
12// Shared no-verdict reasons. One string per surface family, because
13// the reason is the same fact each time; the rows stay one per
14// surface so a departed subcommand fails as its own stale entry.
15const READS_DATA: &str = "returns data, not a verdict; an empty result is an empty \
16     result, never an all-clear";
17const MUTATION: &str = "mutation surface: reports what it did, never an all-clear \
18     over unexamined state";
19#[cfg(feature = "mem-repo")]
20const TRANSPORT: &str = "transport operation: reports the transfer's own outcome";
21const ACCOUNT_OP: &str = "registry or account operation: reports the operation's own \
22     outcome";
23
24// Shared exclusion reasons for the verdict rows.
25const STATUS_SCOPE: &str = "outside the status rollup, whose verdict answers for \
26     declared projection bindings only";
27const ANCHORS_ONLY: &str = "the standalone anchor statement answers for anchors \
28     alone; it examines no other axis and says so";
29const VERIFY_SCOPE: &str = "the binding-scoped fidelity report answers for one \
30     binding's projection and its anchors; other axes belong to health";
31#[cfg(feature = "mem-repo")]
32const DUMP_SCOPE: &str = "the dump is a configuration and roster snapshot; graph \
33     axes belong to health";
34
35/// `memstead health` under `--strict`: exit 0 is the clean verdict,
36/// and it answers exactly for the promoted set, always-on
37/// configuration and mount axes plus the include-gated promotions.
38/// Everything advisory by the strict contract is excluded by name.
39pub const HEALTH: SurfaceCoverage = SurfaceCoverage {
40    surface: "health",
41    // Shared content (memstead_base::ops::coverage::HEALTH_COVERAGE):
42    // the same declaration the MCP composer stamps, so the CLI's
43    // strict verdict and the composed report cannot diverge.
44    disposition: CoverageDisposition::Verdict(memstead_base::ops::coverage::HEALTH_COVERAGE),
45};
46
47pub const STATUS: SurfaceCoverage = SurfaceCoverage {
48    surface: "status",
49    disposition: CoverageDisposition::Verdict(AxisCoverage {
50        examined: &["projection"],
51        excluded: &[
52            ("orphans", STATUS_SCOPE),
53            ("stubs", STATUS_SCOPE),
54            ("most_connected", STATUS_SCOPE),
55            ("missing_fields", STATUS_SCOPE),
56            ("stale", STATUS_SCOPE),
57            ("dangling_links", STATUS_SCOPE),
58            ("tags", STATUS_SCOPE),
59            ("missing_required_outgoing", STATUS_SCOPE),
60            ("constraints", STATUS_SCOPE),
61            ("signals", STATUS_SCOPE),
62            ("labelling", STATUS_SCOPE),
63            ("conformance", STATUS_SCOPE),
64            ("integrity", STATUS_SCOPE),
65            ("config", STATUS_SCOPE),
66            ("anchors", STATUS_SCOPE),
67            ("friction", STATUS_SCOPE),
68            ("open_questions", STATUS_SCOPE),
69            ("stale_derivations", STATUS_SCOPE),
70            ("checks", STATUS_SCOPE),
71            ("ledger", STATUS_SCOPE),
72            ("mounts", STATUS_SCOPE),
73        ],
74    }),
75};
76
77const OVERVIEW: SurfaceCoverage = SurfaceCoverage {
78    surface: "overview",
79    // The content is the shared constant the composer itself stamps
80    // into the overview frontmatter, so registry and output cannot
81    // diverge.
82    disposition: CoverageDisposition::Verdict(memstead_base::ops::coverage::OVERVIEW_COVERAGE),
83};
84
85pub const VERIFY_ANCHORS: SurfaceCoverage = SurfaceCoverage {
86    surface: "verify-anchors",
87    disposition: CoverageDisposition::Verdict(AxisCoverage {
88        examined: &["anchors"],
89        excluded: &[
90            ("orphans", ANCHORS_ONLY),
91            ("stubs", ANCHORS_ONLY),
92            ("most_connected", ANCHORS_ONLY),
93            ("missing_fields", ANCHORS_ONLY),
94            ("stale", ANCHORS_ONLY),
95            ("dangling_links", ANCHORS_ONLY),
96            ("tags", ANCHORS_ONLY),
97            ("missing_required_outgoing", ANCHORS_ONLY),
98            ("constraints", ANCHORS_ONLY),
99            ("signals", ANCHORS_ONLY),
100            ("labelling", ANCHORS_ONLY),
101            ("conformance", ANCHORS_ONLY),
102            ("integrity", ANCHORS_ONLY),
103            ("config", ANCHORS_ONLY),
104            ("friction", ANCHORS_ONLY),
105            ("open_questions", ANCHORS_ONLY),
106            ("stale_derivations", ANCHORS_ONLY),
107            ("checks", ANCHORS_ONLY),
108            ("ledger", ANCHORS_ONLY),
109            ("projection", ANCHORS_ONLY),
110            ("mounts", ANCHORS_ONLY),
111        ],
112    }),
113};
114
115pub const PROJECTION_VERIFY: SurfaceCoverage = SurfaceCoverage {
116    surface: "projection verify",
117    disposition: CoverageDisposition::Verdict(AxisCoverage {
118        examined: &["projection", "anchors"],
119        excluded: &[
120            ("orphans", VERIFY_SCOPE),
121            ("stubs", VERIFY_SCOPE),
122            ("most_connected", VERIFY_SCOPE),
123            ("missing_fields", VERIFY_SCOPE),
124            ("stale", VERIFY_SCOPE),
125            ("dangling_links", VERIFY_SCOPE),
126            ("tags", VERIFY_SCOPE),
127            ("missing_required_outgoing", VERIFY_SCOPE),
128            ("constraints", VERIFY_SCOPE),
129            ("signals", VERIFY_SCOPE),
130            ("labelling", VERIFY_SCOPE),
131            ("conformance", VERIFY_SCOPE),
132            ("integrity", VERIFY_SCOPE),
133            ("config", VERIFY_SCOPE),
134            ("friction", VERIFY_SCOPE),
135            ("open_questions", VERIFY_SCOPE),
136            ("stale_derivations", VERIFY_SCOPE),
137            ("checks", VERIFY_SCOPE),
138            ("ledger", VERIFY_SCOPE),
139            ("mounts", VERIFY_SCOPE),
140        ],
141    }),
142};
143
144#[cfg(feature = "mem-repo")]
145pub const WORKSPACE_DUMP: SurfaceCoverage = SurfaceCoverage {
146    surface: "workspace dump",
147    disposition: CoverageDisposition::Verdict(AxisCoverage {
148        examined: &["mounts", "config"],
149        excluded: &[
150            ("orphans", DUMP_SCOPE),
151            ("stubs", DUMP_SCOPE),
152            ("most_connected", DUMP_SCOPE),
153            ("missing_fields", DUMP_SCOPE),
154            ("stale", DUMP_SCOPE),
155            ("dangling_links", DUMP_SCOPE),
156            ("tags", DUMP_SCOPE),
157            ("missing_required_outgoing", DUMP_SCOPE),
158            ("constraints", DUMP_SCOPE),
159            ("signals", DUMP_SCOPE),
160            ("labelling", DUMP_SCOPE),
161            ("conformance", DUMP_SCOPE),
162            ("integrity", DUMP_SCOPE),
163            ("anchors", DUMP_SCOPE),
164            ("friction", DUMP_SCOPE),
165            ("open_questions", DUMP_SCOPE),
166            ("stale_derivations", DUMP_SCOPE),
167            ("checks", DUMP_SCOPE),
168            ("ledger", DUMP_SCOPE),
169            (
170                "projection",
171                "binding fidelity is answered by status and projection verify",
172            ),
173        ],
174    }),
175};
176
177fn no_verdict(surface: &'static str, reason: &'static str) -> SurfaceCoverage {
178    SurfaceCoverage {
179        surface,
180        disposition: CoverageDisposition::NoVerdict(reason),
181    }
182}
183
184/// Every CLI surface's coverage row. Names are the clap path exactly
185/// as the walk below produces it ("workspace dump", not "dump").
186/// Feature-gated commands carry the same gate as their clap variant,
187/// so the lean build's registry matches the lean build's walk.
188pub fn surface_registry() -> Vec<SurfaceCoverage> {
189    #[cfg_attr(not(feature = "mem-repo"), allow(unused_mut))]
190    let mut rows = vec![
191        STATUS,
192        HEALTH,
193        OVERVIEW,
194        VERIFY_ANCHORS,
195        PROJECTION_VERIFY,
196        // Read surfaces that return data rather than a verdict.
197        no_verdict("entity", READS_DATA),
198        no_verdict("relations", READS_DATA),
199        no_verdict("search", READS_DATA),
200        no_verdict("list", READS_DATA),
201        no_verdict("context", READS_DATA),
202        no_verdict("type", READS_DATA),
203        no_verdict("due", READS_DATA),
204        no_verdict("export", READS_DATA),
205        no_verdict("changes", READS_DATA),
206        no_verdict("anchors", READS_DATA),
207        no_verdict("conflicts list", READS_DATA),
208        no_verdict("review-mark list", READS_DATA),
209        no_verdict("review-mark diff", READS_DATA),
210        no_verdict("projection brief", READS_DATA),
211        no_verdict("projection check-path", READS_DATA),
212        // The check ledger: the one surface deliberately outside the
213        // rule, because its verdict is the caller's claim about the
214        // caller's own work, never the engine's claim about state the
215        // engine examined.
216        no_verdict(
217            "check",
218            "records the caller's verdict about the caller's own work into the \
219             append-only ledger; the engine derives no verdict of its own",
220        ),
221        // Schema tooling verdicts are total over the caller-named
222        // input, so no workspace axis is claimed.
223        no_verdict(
224            "schema validate",
225            "validates the caller-named schema package; the verdict is total over \
226             exactly that input and claims no workspace axis",
227        ),
228        no_verdict("schema new", MUTATION),
229        no_verdict("schema install", MUTATION),
230        // Mutations and setup.
231        no_verdict("create", MUTATION),
232        no_verdict("update", MUTATION),
233        no_verdict("relate", MUTATION),
234        no_verdict("delete", MUTATION),
235        no_verdict("rename", MUTATION),
236        no_verdict("conflicts resolve", MUTATION),
237        no_verdict("review-mark set", MUTATION),
238        no_verdict("review-mark clear", MUTATION),
239        no_verdict("reload", MUTATION),
240        no_verdict("init", MUTATION),
241        no_verdict("quickstart", MUTATION),
242        no_verdict("projection init", MUTATION),
243        no_verdict("projection migrate", MUTATION),
244        no_verdict("projection enable", MUTATION),
245        no_verdict("projection advance", MUTATION),
246        no_verdict("projection exclude", MUTATION),
247        // Registry and account operations.
248        no_verdict("publish", ACCOUNT_OP),
249        no_verdict("unpublish", ACCOUNT_OP),
250        no_verdict("login", ACCOUNT_OP),
251        no_verdict("logout", ACCOUNT_OP),
252        no_verdict("domain keygen", ACCOUNT_OP),
253        no_verdict("domain manifest", ACCOUNT_OP),
254        no_verdict("admin takedown", ACCOUNT_OP),
255        no_verdict("admin denylist", ACCOUNT_OP),
256    ];
257    #[cfg(feature = "mem-repo")]
258    rows.extend([
259        WORKSPACE_DUMP,
260        no_verdict("install", MUTATION),
261        no_verdict("uninstall", MUTATION),
262        no_verdict("batch-update", MUTATION),
263        no_verdict("batch-create", MUTATION),
264        no_verdict("batch-relate", MUTATION),
265        no_verdict("recover", MUTATION),
266        no_verdict("fetch", TRANSPORT),
267        no_verdict("pull", TRANSPORT),
268        no_verdict("push", TRANSPORT),
269        no_verdict("branch-reset", TRANSPORT),
270        no_verdict("mem init", MUTATION),
271        no_verdict("mem unregister", MUTATION),
272        no_verdict("mem delete", MUTATION),
273        no_verdict("mem rename", MUTATION),
274        no_verdict("mem set-version", MUTATION),
275        no_verdict("mem set-schema", MUTATION),
276        no_verdict("mem set-description", MUTATION),
277        no_verdict("mem set-title", MUTATION),
278        no_verdict("mem set-subject", MUTATION),
279        no_verdict("mem set-sync-state", MUTATION),
280        no_verdict("mem set-internal", MUTATION),
281        no_verdict("mem list", READS_DATA),
282        no_verdict("mem-repo init", MUTATION),
283        no_verdict("mem-repo remote-add", MUTATION),
284        no_verdict("workspace show", READS_DATA),
285        no_verdict("workspace allow-create", MUTATION),
286        no_verdict("workspace revoke-create", MUTATION),
287        no_verdict("workspace allow-delete", MUTATION),
288        no_verdict("workspace revoke-delete", MUTATION),
289        no_verdict("workspace grant-cross-link", MUTATION),
290        no_verdict("workspace revoke-cross-link", MUTATION),
291        no_verdict("workspace set-mutations", MUTATION),
292    ]);
293    rows
294}
295
296#[cfg(test)]
297mod tests {
298    use super::*;
299    use clap::CommandFactory;
300    use memstead_base::ops::coverage::{validate_coverage, verdict_axes};
301
302    /// Walk the live clap tree to its leaves. This is the discovery
303    /// half of the gate: the roster comes from the binary's own
304    /// command definition, never from a hand-kept list, so a
305    /// subcommand cannot land outside the registry's sight.
306    fn discovered_surfaces() -> Vec<String> {
307        fn walk(cmd: &clap::Command, prefix: &str, out: &mut Vec<String>) {
308            let mut leaves = 0;
309            for sub in cmd.get_subcommands() {
310                if sub.get_name() == "help" {
311                    continue;
312                }
313                leaves += 1;
314                let path = if prefix.is_empty() {
315                    sub.get_name().to_string()
316                } else {
317                    format!("{prefix} {}", sub.get_name())
318                };
319                walk(sub, &path, out);
320            }
321            if leaves == 0 && !prefix.is_empty() {
322                out.push(prefix.to_string());
323            }
324        }
325        let mut out = Vec::new();
326        let cmd = crate::cli::Cli::command();
327        walk(&cmd, "", &mut out);
328        out
329    }
330
331    /// The gate. A clean run means: every discoverable subcommand
332    /// has a row, every verdict row speaks to every axis in the
333    /// vocabulary, and no row is stale.
334    #[test]
335    fn every_cli_surface_declares_its_coverage() {
336        let discovered = discovered_surfaces();
337        let discovered_refs: Vec<&str> = discovered.iter().map(|s| s.as_str()).collect();
338        let vocab = verdict_axes();
339        let registry = surface_registry();
340        let findings = validate_coverage(&vocab, &registry, &discovered_refs);
341        assert!(
342            findings.is_empty(),
343            "{} coverage finding(s):\n{}",
344            findings.len(),
345            findings.join("\n")
346        );
347    }
348}
memstead_cli/coverage.rs

memstead_cli/
coverage.rs
