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("gates", READS_DATA),
205        no_verdict("export", READS_DATA),
206        no_verdict("changes", READS_DATA),
207        no_verdict("anchors", READS_DATA),
208        no_verdict("conflicts list", READS_DATA),
209        no_verdict("review-mark list", READS_DATA),
210        no_verdict("review-mark diff", READS_DATA),
211        no_verdict("projection brief", READS_DATA),
212        no_verdict("projection check-path", READS_DATA),
213        // The check ledger: the one surface deliberately outside the
214        // rule, because its verdict is the caller's claim about the
215        // caller's own work, never the engine's claim about state the
216        // engine examined.
217        no_verdict(
218            "check",
219            "records the caller's verdict about the caller's own work into the \
220             append-only ledger; the engine derives no verdict of its own",
221        ),
222        // Schema tooling verdicts are total over the caller-named
223        // input, so no workspace axis is claimed.
224        no_verdict(
225            "schema validate",
226            "validates the caller-named schema package; the verdict is total over \
227             exactly that input and claims no workspace axis",
228        ),
229        no_verdict("schema new", MUTATION),
230        no_verdict("schema install", MUTATION),
231        // Mutations and setup.
232        no_verdict("create", MUTATION),
233        no_verdict("update", MUTATION),
234        no_verdict("relate", MUTATION),
235        no_verdict("delete", MUTATION),
236        no_verdict("rename", MUTATION),
237        no_verdict("conflicts resolve", MUTATION),
238        no_verdict("review-mark set", MUTATION),
239        no_verdict("review-mark clear", MUTATION),
240        no_verdict("reload", MUTATION),
241        no_verdict("init", MUTATION),
242        no_verdict("quickstart", MUTATION),
243        no_verdict("projection init", MUTATION),
244        no_verdict("projection migrate", MUTATION),
245        no_verdict("projection enable", MUTATION),
246        no_verdict("projection edit", MUTATION),
247        no_verdict("projection advance", MUTATION),
248        no_verdict("projection exclude", MUTATION),
249        // Registry and account operations.
250        no_verdict("publish", ACCOUNT_OP),
251        no_verdict("unpublish", ACCOUNT_OP),
252        no_verdict("login", ACCOUNT_OP),
253        no_verdict("logout", ACCOUNT_OP),
254        no_verdict("domain keygen", ACCOUNT_OP),
255        no_verdict("domain manifest", ACCOUNT_OP),
256        no_verdict("admin takedown", ACCOUNT_OP),
257        no_verdict("admin denylist", ACCOUNT_OP),
258    ];
259    #[cfg(feature = "mem-repo")]
260    rows.extend([
261        WORKSPACE_DUMP,
262        no_verdict("install", MUTATION),
263        no_verdict("uninstall", MUTATION),
264        no_verdict("batch-update", MUTATION),
265        no_verdict("batch-create", MUTATION),
266        no_verdict("batch-relate", MUTATION),
267        no_verdict("recover", MUTATION),
268        no_verdict("fetch", TRANSPORT),
269        no_verdict("pull", TRANSPORT),
270        no_verdict("push", TRANSPORT),
271        no_verdict("branch-reset", TRANSPORT),
272        no_verdict("mem init", MUTATION),
273        no_verdict("mem unregister", MUTATION),
274        no_verdict("mem delete", MUTATION),
275        no_verdict("mem rename", MUTATION),
276        no_verdict("mem set-version", MUTATION),
277        no_verdict("mem set-schema", MUTATION),
278        no_verdict("mem set-description", MUTATION),
279        no_verdict("mem set-title", MUTATION),
280        no_verdict("mem set-subject", MUTATION),
281        no_verdict("mem set-sync-state", MUTATION),
282        no_verdict("mem set-internal", MUTATION),
283        no_verdict("mem list", READS_DATA),
284        no_verdict("mem-repo init", MUTATION),
285        no_verdict("mem-repo remote-add", MUTATION),
286        no_verdict("workspace show", READS_DATA),
287        no_verdict("workspace allow-create", MUTATION),
288        no_verdict("workspace revoke-create", MUTATION),
289        no_verdict("workspace allow-delete", MUTATION),
290        no_verdict("workspace revoke-delete", MUTATION),
291        no_verdict("workspace grant-cross-link", MUTATION),
292        no_verdict("workspace revoke-cross-link", MUTATION),
293        no_verdict("workspace set-mutations", MUTATION),
294    ]);
295    rows
296}
297
298#[cfg(test)]
299mod tests {
300    use super::*;
301    use clap::CommandFactory;
302    use memstead_base::ops::coverage::{validate_coverage, verdict_axes};
303
304    /// Walk the live clap tree to its leaves. This is the discovery
305    /// half of the gate: the roster comes from the binary's own
306    /// command definition, never from a hand-kept list, so a
307    /// subcommand cannot land outside the registry's sight.
308    fn discovered_surfaces() -> Vec<String> {
309        fn walk(cmd: &clap::Command, prefix: &str, out: &mut Vec<String>) {
310            let mut leaves = 0;
311            for sub in cmd.get_subcommands() {
312                if sub.get_name() == "help" {
313                    continue;
314                }
315                leaves += 1;
316                let path = if prefix.is_empty() {
317                    sub.get_name().to_string()
318                } else {
319                    format!("{prefix} {}", sub.get_name())
320                };
321                walk(sub, &path, out);
322            }
323            if leaves == 0 && !prefix.is_empty() {
324                out.push(prefix.to_string());
325            }
326        }
327        let mut out = Vec::new();
328        let cmd = crate::cli::Cli::command();
329        walk(&cmd, "", &mut out);
330        out
331    }
332
333    /// The gate. A clean run means: every discoverable subcommand
334    /// has a row, every verdict row speaks to every axis in the
335    /// vocabulary, and no row is stale.
336    #[test]
337    fn every_cli_surface_declares_its_coverage() {
338        let discovered = discovered_surfaces();
339        let discovered_refs: Vec<&str> = discovered.iter().map(|s| s.as_str()).collect();
340        let vocab = verdict_axes();
341        let registry = surface_registry();
342        let findings = validate_coverage(&vocab, &registry, &discovered_refs);
343        assert!(
344            findings.is_empty(),
345            "{} coverage finding(s):\n{}",
346            findings.len(),
347            findings.join("\n")
348        );
349    }
350}
memstead_cli/coverage.rs

memstead_cli/
coverage.rs
