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            ("vital_signs", STATUS_SCOPE),
70            ("stale_derivations", STATUS_SCOPE),
71            ("checks", STATUS_SCOPE),
72            ("ledger", STATUS_SCOPE),
73            ("mounts", STATUS_SCOPE),
74        ],
75    }),
76};
77
78const OVERVIEW: SurfaceCoverage = SurfaceCoverage {
79    surface: "overview",
80    // The content is the shared constant the composer itself stamps
81    // into the overview frontmatter, so registry and output cannot
82    // diverge.
83    disposition: CoverageDisposition::Verdict(memstead_base::ops::coverage::OVERVIEW_COVERAGE),
84};
85
86pub const VERIFY_ANCHORS: SurfaceCoverage = SurfaceCoverage {
87    surface: "verify-anchors",
88    disposition: CoverageDisposition::Verdict(AxisCoverage {
89        examined: &["anchors"],
90        excluded: &[
91            ("orphans", ANCHORS_ONLY),
92            ("stubs", ANCHORS_ONLY),
93            ("most_connected", ANCHORS_ONLY),
94            ("missing_fields", ANCHORS_ONLY),
95            ("stale", ANCHORS_ONLY),
96            ("dangling_links", ANCHORS_ONLY),
97            ("tags", ANCHORS_ONLY),
98            ("missing_required_outgoing", ANCHORS_ONLY),
99            ("constraints", ANCHORS_ONLY),
100            ("signals", ANCHORS_ONLY),
101            ("labelling", ANCHORS_ONLY),
102            ("conformance", ANCHORS_ONLY),
103            ("integrity", ANCHORS_ONLY),
104            ("config", ANCHORS_ONLY),
105            ("friction", ANCHORS_ONLY),
106            ("open_questions", ANCHORS_ONLY),
107            ("vital_signs", ANCHORS_ONLY),
108            ("stale_derivations", ANCHORS_ONLY),
109            ("checks", ANCHORS_ONLY),
110            ("ledger", ANCHORS_ONLY),
111            ("projection", ANCHORS_ONLY),
112            ("mounts", ANCHORS_ONLY),
113        ],
114    }),
115};
116
117pub const PROJECTION_VERIFY: SurfaceCoverage = SurfaceCoverage {
118    surface: "projection verify",
119    disposition: CoverageDisposition::Verdict(AxisCoverage {
120        examined: &["projection", "anchors"],
121        excluded: &[
122            ("orphans", VERIFY_SCOPE),
123            ("stubs", VERIFY_SCOPE),
124            ("most_connected", VERIFY_SCOPE),
125            ("missing_fields", VERIFY_SCOPE),
126            ("stale", VERIFY_SCOPE),
127            ("dangling_links", VERIFY_SCOPE),
128            ("tags", VERIFY_SCOPE),
129            ("missing_required_outgoing", VERIFY_SCOPE),
130            ("constraints", VERIFY_SCOPE),
131            ("signals", VERIFY_SCOPE),
132            ("labelling", VERIFY_SCOPE),
133            ("conformance", VERIFY_SCOPE),
134            ("integrity", VERIFY_SCOPE),
135            ("config", VERIFY_SCOPE),
136            ("friction", VERIFY_SCOPE),
137            ("open_questions", VERIFY_SCOPE),
138            ("vital_signs", VERIFY_SCOPE),
139            ("stale_derivations", VERIFY_SCOPE),
140            ("checks", VERIFY_SCOPE),
141            ("ledger", VERIFY_SCOPE),
142            ("mounts", VERIFY_SCOPE),
143        ],
144    }),
145};
146
147#[cfg(feature = "mem-repo")]
148pub const WORKSPACE_DUMP: SurfaceCoverage = SurfaceCoverage {
149    surface: "workspace dump",
150    disposition: CoverageDisposition::Verdict(AxisCoverage {
151        examined: &["mounts", "config"],
152        excluded: &[
153            ("orphans", DUMP_SCOPE),
154            ("stubs", DUMP_SCOPE),
155            ("most_connected", DUMP_SCOPE),
156            ("missing_fields", DUMP_SCOPE),
157            ("stale", DUMP_SCOPE),
158            ("dangling_links", DUMP_SCOPE),
159            ("tags", DUMP_SCOPE),
160            ("missing_required_outgoing", DUMP_SCOPE),
161            ("constraints", DUMP_SCOPE),
162            ("signals", DUMP_SCOPE),
163            ("labelling", DUMP_SCOPE),
164            ("conformance", DUMP_SCOPE),
165            ("integrity", DUMP_SCOPE),
166            ("anchors", DUMP_SCOPE),
167            ("friction", DUMP_SCOPE),
168            ("open_questions", DUMP_SCOPE),
169            ("vital_signs", DUMP_SCOPE),
170            ("stale_derivations", DUMP_SCOPE),
171            ("checks", DUMP_SCOPE),
172            ("ledger", DUMP_SCOPE),
173            (
174                "projection",
175                "binding fidelity is answered by status and projection verify",
176            ),
177        ],
178    }),
179};
180
181fn no_verdict(surface: &'static str, reason: &'static str) -> SurfaceCoverage {
182    SurfaceCoverage {
183        surface,
184        disposition: CoverageDisposition::NoVerdict(reason),
185    }
186}
187
188/// Every CLI surface's coverage row. Names are the clap path exactly
189/// as the walk below produces it ("workspace dump", not "dump").
190/// Feature-gated commands carry the same gate as their clap variant,
191/// so the lean build's registry matches the lean build's walk.
192pub fn surface_registry() -> Vec<SurfaceCoverage> {
193    #[cfg_attr(not(feature = "mem-repo"), allow(unused_mut))]
194    let mut rows = vec![
195        STATUS,
196        HEALTH,
197        OVERVIEW,
198        VERIFY_ANCHORS,
199        PROJECTION_VERIFY,
200        // Read surfaces that return data rather than a verdict.
201        no_verdict("entity", READS_DATA),
202        no_verdict("relations", READS_DATA),
203        no_verdict("search", READS_DATA),
204        no_verdict("list", READS_DATA),
205        no_verdict("context", READS_DATA),
206        no_verdict("type", READS_DATA),
207        no_verdict("due", READS_DATA),
208        no_verdict("gates", READS_DATA),
209        no_verdict("export", READS_DATA),
210        no_verdict("changes", READS_DATA),
211        no_verdict("anchors", READS_DATA),
212        no_verdict("conflicts list", READS_DATA),
213        no_verdict("review-mark list", READS_DATA),
214        no_verdict("review-mark diff", READS_DATA),
215        no_verdict("projection brief", READS_DATA),
216        no_verdict("projection check-path", READS_DATA),
217        // The check ledger: the one surface deliberately outside the
218        // rule, because its verdict is the caller's claim about the
219        // caller's own work, never the engine's claim about state the
220        // engine examined.
221        no_verdict(
222            "check",
223            "records the caller's verdict about the caller's own work into the \
224             append-only ledger; the engine derives no verdict of its own",
225        ),
226        // Schema tooling verdicts are total over the caller-named
227        // input, so no workspace axis is claimed.
228        no_verdict(
229            "schema validate",
230            "validates the caller-named schema package; the verdict is total over \
231             exactly that input and claims no workspace axis",
232        ),
233        no_verdict("schema new", MUTATION),
234        no_verdict("schema install", MUTATION),
235        no_verdict(
236            "schema migrate",
237            "previews or applies rewrites of the caller-named schema package; reports \
238             the rewrites, never an all-clear over any workspace axis",
239        ),
240        // Mutations and setup.
241        no_verdict("create", MUTATION),
242        no_verdict("update", MUTATION),
243        no_verdict("relate", MUTATION),
244        no_verdict("delete", MUTATION),
245        no_verdict("rename", MUTATION),
246        no_verdict("retype", MUTATION),
247        no_verdict("conflicts resolve", MUTATION),
248        no_verdict("review-mark set", MUTATION),
249        no_verdict("review-mark clear", MUTATION),
250        no_verdict("reload", MUTATION),
251        no_verdict("init", MUTATION),
252        no_verdict("quickstart", MUTATION),
253        no_verdict("projection init", MUTATION),
254        no_verdict("projection migrate", MUTATION),
255        no_verdict("projection enable", MUTATION),
256        no_verdict("projection edit", MUTATION),
257        no_verdict("projection advance", MUTATION),
258        no_verdict("projection exclude", MUTATION),
259        // Registry and account operations.
260        no_verdict("publish", ACCOUNT_OP),
261        no_verdict("unpublish", ACCOUNT_OP),
262        no_verdict("login", ACCOUNT_OP),
263        no_verdict("logout", ACCOUNT_OP),
264        no_verdict("domain keygen", ACCOUNT_OP),
265        no_verdict("domain manifest", ACCOUNT_OP),
266        no_verdict("admin takedown", ACCOUNT_OP),
267        no_verdict("admin denylist", ACCOUNT_OP),
268    ];
269    #[cfg(feature = "mem-repo")]
270    rows.extend([
271        WORKSPACE_DUMP,
272        no_verdict("install", MUTATION),
273        no_verdict("uninstall", MUTATION),
274        no_verdict("batch-update", MUTATION),
275        no_verdict("batch-create", MUTATION),
276        no_verdict("batch-relate", MUTATION),
277        no_verdict("recover", MUTATION),
278        no_verdict("fetch", TRANSPORT),
279        no_verdict("pull", TRANSPORT),
280        no_verdict("push", TRANSPORT),
281        no_verdict("branch-reset", TRANSPORT),
282        no_verdict("mem init", MUTATION),
283        no_verdict("mem unregister", MUTATION),
284        no_verdict("mem delete", MUTATION),
285        no_verdict("mem rename", MUTATION),
286        no_verdict("mem set-version", MUTATION),
287        no_verdict("mem set-schema", MUTATION),
288        no_verdict("mem set-description", MUTATION),
289        no_verdict("mem set-title", MUTATION),
290        no_verdict("mem set-subject", MUTATION),
291        no_verdict("mem set-sync-state", MUTATION),
292        no_verdict("mem set-internal", MUTATION),
293        no_verdict("mem list", READS_DATA),
294        no_verdict("mem-repo init", MUTATION),
295        no_verdict("mem-repo remote-add", MUTATION),
296        no_verdict("workspace show", READS_DATA),
297        no_verdict("workspace allow-create", MUTATION),
298        no_verdict("workspace revoke-create", MUTATION),
299        no_verdict("workspace allow-delete", MUTATION),
300        no_verdict("workspace revoke-delete", MUTATION),
301        no_verdict("workspace grant-cross-link", MUTATION),
302        no_verdict("workspace revoke-cross-link", MUTATION),
303        no_verdict("workspace set-mutations", MUTATION),
304    ]);
305    rows
306}
307
308#[cfg(test)]
309mod tests {
310    use super::*;
311    use clap::CommandFactory;
312    use memstead_base::ops::coverage::{validate_coverage, verdict_axes};
313
314    /// Walk the live clap tree to its leaves. This is the discovery
315    /// half of the gate: the roster comes from the binary's own
316    /// command definition, never from a hand-kept list, so a
317    /// subcommand cannot land outside the registry's sight.
318    fn discovered_surfaces() -> Vec<String> {
319        fn walk(cmd: &clap::Command, prefix: &str, out: &mut Vec<String>) {
320            let mut leaves = 0;
321            for sub in cmd.get_subcommands() {
322                if sub.get_name() == "help" {
323                    continue;
324                }
325                leaves += 1;
326                let path = if prefix.is_empty() {
327                    sub.get_name().to_string()
328                } else {
329                    format!("{prefix} {}", sub.get_name())
330                };
331                walk(sub, &path, out);
332            }
333            if leaves == 0 && !prefix.is_empty() {
334                out.push(prefix.to_string());
335            }
336        }
337        let mut out = Vec::new();
338        let cmd = crate::cli::Cli::command();
339        walk(&cmd, "", &mut out);
340        out
341    }
342
343    /// The gate. A clean run means: every discoverable subcommand
344    /// has a row, every verdict row speaks to every axis in the
345    /// vocabulary, and no row is stale.
346    #[test]
347    fn every_cli_surface_declares_its_coverage() {
348        let discovered = discovered_surfaces();
349        let discovered_refs: Vec<&str> = discovered.iter().map(|s| s.as_str()).collect();
350        let vocab = verdict_axes();
351        let registry = surface_registry();
352        let findings = validate_coverage(&vocab, &registry, &discovered_refs);
353        assert!(
354            findings.is_empty(),
355            "{} coverage finding(s):\n{}",
356            findings.len(),
357            findings.join("\n")
358        );
359    }
360}
memstead_cli/coverage.rs

memstead_cli/
coverage.rs
