Skip to main content

fallow_types/
command_surfaces.rs

1//! One row per analysis subcommand: the JSON kinds it writes and the surfaces
2//! that must know about it.
3//!
4//! A new analysis command must reach the root `FallowOutput` schema, `fallow
5//! report --from`, the MCP server, the GitHub Action, the GitLab CI template
6//! and the drift harness. Each of those
7//! surfaces has a test that reads
8//! [`COMMAND_ENVELOPES`](crate::command_surfaces::COMMAND_ENVELOPES), so a
9//! command that is added to the CLI without a row, or a row without a
10//! surface, fails a test instead of shipping a silent gap. Every other
11//! visible subcommand is listed in
12//! [`COMMANDS_WITHOUT_ANALYSIS_ENVELOPE`](crate::command_surfaces::COMMANDS_WITHOUT_ANALYSIS_ENVELOPE)
13//! with the reason it has no row.
14
15/// How `fallow report --from` treats a saved envelope of a command.
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub enum ReportFrom {
18    /// `fallow report --from` renders the saved envelope, flat and grouped.
19    Renders,
20    /// `fallow report --from` refuses the saved envelope, for this reason.
21    Refused(&'static str),
22}
23
24/// How the GitHub Action and the GitLab CI template treat a command.
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum CiIntegration {
27    /// The `command` input of the Action and `FALLOW_COMMAND` of the GitLab
28    /// template accept the command, and the job summary routes its envelope.
29    Routed,
30    /// The CI integrations do not run the command, for this reason.
31    Omitted(&'static str),
32}
33
34/// The machine contract of one analysis subcommand.
35#[derive(Debug, Clone, Copy)]
36pub struct CommandEnvelope {
37    /// The subcommand, as `fallow <command>` spells it.
38    pub command: &'static str,
39    /// The root `kind` of `fallow <command> --format json`.
40    pub kind: &'static str,
41    /// The root `kind` with `--group-by`, when grouping writes another kind.
42    pub grouped_kind: Option<&'static str>,
43    /// How `fallow report --from` treats a saved envelope.
44    pub report_from: ReportFrom,
45    /// The MCP tool whose CLI analogue is this command.
46    pub mcp_tool: Option<&'static str>,
47    /// Why no MCP tool exists. `Some` exactly when `mcp_tool` is `None`.
48    pub mcp_omission: Option<&'static str>,
49    /// Whether the drift harness compares the verdict of the JSON and human
50    /// runs (invariant I7).
51    pub verdict: bool,
52    /// How the GitHub Action and the GitLab CI template treat the command.
53    pub ci: CiIntegration,
54}
55
56/// Every analysis subcommand with its JSON kinds and surfaces.
57pub const COMMAND_ENVELOPES: &[CommandEnvelope] = &[
58    CommandEnvelope {
59        command: "dead-code",
60        kind: "dead-code",
61        grouped_kind: Some("dead-code-grouped"),
62        report_from: ReportFrom::Renders,
63        mcp_tool: Some("analyze"),
64        mcp_omission: None,
65        verdict: true,
66        ci: CiIntegration::Routed,
67    },
68    CommandEnvelope {
69        command: "architecture",
70        kind: "architecture",
71        grouped_kind: Some("architecture-grouped"),
72        report_from: ReportFrom::Renders,
73        mcp_tool: Some("check_architecture"),
74        mcp_omission: None,
75        verdict: true,
76        ci: CiIntegration::Routed,
77    },
78    CommandEnvelope {
79        command: "dupes",
80        kind: "dupes",
81        grouped_kind: None,
82        report_from: ReportFrom::Renders,
83        mcp_tool: Some("find_dupes"),
84        mcp_omission: None,
85        verdict: true,
86        ci: CiIntegration::Routed,
87    },
88    CommandEnvelope {
89        command: "health",
90        kind: "health",
91        grouped_kind: None,
92        report_from: ReportFrom::Renders,
93        mcp_tool: Some("check_health"),
94        mcp_omission: None,
95        verdict: true,
96        ci: CiIntegration::Routed,
97    },
98    CommandEnvelope {
99        command: "security",
100        kind: "security",
101        grouped_kind: None,
102        report_from: ReportFrom::Renders,
103        mcp_tool: Some("security_candidates"),
104        mcp_omission: None,
105        verdict: true,
106        ci: CiIntegration::Routed,
107    },
108    CommandEnvelope {
109        command: "audit",
110        kind: "audit",
111        grouped_kind: None,
112        report_from: ReportFrom::Renders,
113        mcp_tool: Some("audit"),
114        mcp_omission: None,
115        verdict: true,
116        ci: CiIntegration::Routed,
117    },
118    CommandEnvelope {
119        command: "flags",
120        kind: "feature-flags",
121        grouped_kind: None,
122        report_from: ReportFrom::Refused(
123            "feature flags are an inventory with no CI annotation or review surface",
124        ),
125        mcp_tool: Some("feature_flags"),
126        mcp_omission: None,
127        verdict: false,
128        ci: CiIntegration::Omitted("feature flags are an inventory with no CI gate or annotation"),
129    },
130    CommandEnvelope {
131        command: "similar-code",
132        kind: "similar-code",
133        grouped_kind: None,
134        report_from: ReportFrom::Refused(
135            "similar-code candidates are unverified and never feed a CI surface",
136        ),
137        mcp_tool: Some("find_similar_code"),
138        mcp_omission: None,
139        verdict: false,
140        ci: CiIntegration::Omitted(
141            "similar-code candidates are unverified and never feed a CI surface",
142        ),
143    },
144    CommandEnvelope {
145        command: "mutation",
146        kind: "mutation",
147        grouped_kind: None,
148        report_from: ReportFrom::Refused(
149            "mutation results come from one opt-in test run and feed no CI surface in version 1",
150        ),
151        mcp_tool: Some("mutation_plan"),
152        mcp_omission: None,
153        verdict: false,
154        ci: CiIntegration::Omitted(
155            "mutation testing runs the project tests; only an explicit local command starts a run",
156        ),
157    },
158];
159
160/// Visible subcommands that write no analysis report, with the reason.
161pub const COMMANDS_WITHOUT_ANALYSIS_ENVELOPE: &[(&str, &str)] = &[
162    (
163        "guard",
164        "per-file rule lookup before an edit; it reports rules, not findings",
165    ),
166    ("watch", "interactive loop that prints human output only"),
167    (
168        "fix",
169        "applies fixes; `report --from` detects its kind-less envelope by its fields",
170    ),
171    (
172        "list",
173        "project inspection; writes `list-boundaries` or `list-workspaces`",
174    ),
175    ("inspect", "evidence bundle for one target"),
176    ("trace", "call-chain and import-path trace for one symbol"),
177    ("trace-error", "stack-trace frame resolution"),
178    (
179        "decision-surface",
180        "advisory review signals of a change, not findings",
181    ),
182    ("workspaces", "workspace discovery diagnostics"),
183    ("explain", "static issue-type documentation"),
184    ("suppressions", "inventory of suppression markers"),
185    ("impact", "local impact digest of fallow itself"),
186    ("viz", "writes an HTML map"),
187    ("doctor", "project readiness checks"),
188    ("init", "writes a config file"),
189    ("agent", "wires fallow into agent tools"),
190    ("audit-cache", "maintains audit base-snapshot caches"),
191    (
192        "baselines",
193        "maintains committed baseline files; writes a `baselines-prune` envelope",
194    ),
195    ("recommend", "config recommendation for an agent"),
196    ("migrate", "config migration"),
197    ("config", "resolved config"),
198    ("config-schema", "JSON Schema of the config"),
199    ("plugin-schema", "JSON Schema of external plugins"),
200    ("plugin-check", "external plugin dry run"),
201    ("rule-pack", "rule-pack management"),
202    ("rule-pack-schema", "JSON Schema of rule packs"),
203    ("type-aware", "semantic companion status"),
204    ("ci", "builds PR and MR feedback from a saved envelope"),
205    ("ci-template", "CI template output"),
206    ("report", "renders a saved envelope"),
207    ("hooks", "Git and agent hook management"),
208    ("setup-hooks", "deprecated alias of hook installation"),
209    ("coverage", "runtime coverage setup and analysis"),
210    ("license", "license management"),
211    ("cloud", "Fallow Cloud login and logout"),
212    ("telemetry", "telemetry settings"),
213    ("schema", "capability manifest"),
214];
215
216/// The row of `command`, when it is an analysis subcommand.
217#[must_use]
218pub fn command_envelope(command: &str) -> Option<&'static CommandEnvelope> {
219    COMMAND_ENVELOPES.iter().find(|row| row.command == command)
220}
221
222#[cfg(test)]
223mod tests {
224    use std::collections::BTreeSet;
225
226    use super::*;
227
228    #[test]
229    fn rows_name_each_command_and_kind_once() {
230        let commands: BTreeSet<&str> = COMMAND_ENVELOPES.iter().map(|row| row.command).collect();
231        assert_eq!(commands.len(), COMMAND_ENVELOPES.len());
232        let kinds: Vec<&str> = COMMAND_ENVELOPES
233            .iter()
234            .flat_map(|row| std::iter::once(row.kind).chain(row.grouped_kind))
235            .collect();
236        let unique: BTreeSet<&str> = kinds.iter().copied().collect();
237        assert_eq!(unique.len(), kinds.len(), "a kind is in two rows");
238        for (command, _) in COMMANDS_WITHOUT_ANALYSIS_ENVELOPE {
239            assert!(
240                command_envelope(command).is_none(),
241                "{command} is in both lists"
242            );
243        }
244    }
245
246    #[test]
247    fn every_row_has_an_mcp_tool_or_a_reason() {
248        for row in COMMAND_ENVELOPES {
249            assert_eq!(
250                row.mcp_tool.is_some(),
251                row.mcp_omission.is_none(),
252                "{}: set exactly one of mcp_tool and mcp_omission",
253                row.command
254            );
255            if let Some(tool) = row.mcp_tool {
256                let info = crate::mcp_manifest::MCP_TOOLS
257                    .iter()
258                    .find(|info| info.name == tool)
259                    .unwrap_or_else(|| panic!("{}: no MCP tool `{tool}`", row.command));
260                let expected = format!("fallow {} ", row.command);
261                assert!(
262                    info.cli_command
263                        .is_some_and(|cli| cli.starts_with(expected.as_str())),
264                    "{}: MCP tool `{tool}` names another CLI analogue: {:?}",
265                    row.command,
266                    info.cli_command
267                );
268            }
269        }
270    }
271}