fallow_types/
envelope.rs

1//! Typed envelope and utility-shape structs for the JSON output contract.
2//!
3//! Today the JSON serialization layer (`crates/cli/src/report/json.rs`) builds
4//! its envelopes (`CheckOutput`, `HealthOutput`, ...) via `serde_json::json!`
5//! macros and ad-hoc map merging. The types in this module are the schema-side
6//! counterpart of those envelopes plus a small set of utility shapes
7//! (`SchemaVersion`, `Meta`, `BaselineDeltas`, ...) that the envelopes
8//! reference.
9//!
10//! Gated on the `schema` cargo feature so consumers that do not need the
11//! `schemars::JsonSchema` derive (every crate except `fallow-cli` with
12//! `--features schema-emit`) skip the schemars compile cost.
13
14use std::collections::BTreeMap;
15
16use serde::Serialize;
17
18/// Schema version for this output format (independent of tool version). Bump
19/// policy: ADDITIVE changes (new optional top-level fields, new optional struct
20/// fields, new array entries, new MCP tools, new CLI flags that map to new
21/// optional fields) do NOT bump the version; consumers receive new fields
22/// without breaking. BREAKING changes (renamed fields, removed fields, type
23/// changes, enum-variant removals, semantic changes to existing fields) DO
24/// bump. To detect newly-added fields without a bump, check field presence via
25/// JSON-key existence rather than gating on the version. v4 was introduced
26/// alongside fallow-cov-protocol 0.2 (per-finding verdict, stable IDs, evidence
27/// block, renamed summary fields); v5 introduced health_score formula_version 2
28/// with scale-invariant scoring semantics; v6 widened `AddToConfigAction.value`
29/// from a scalar string to `oneOf: [string, array]` so the new `ignoreExports`
30/// action can carry a paste-ready array of `{ file, exports }` rule objects
31/// (the legacy `ignoreDependencies` etc. variants still emit strings, so
32/// consumers that switch on `config_key` keep working unchanged). The
33/// runtime-coverage block is extended additively as the protocol evolves
34/// (currently 0.3, which adds an optional capture_quality summary field). Other
35/// additive examples: dupes --group-by adds optional grouped_by, total_issues,
36/// groups fields without bumping.
37#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
38#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
39#[serde(transparent)]
40pub struct SchemaVersion(pub u32);
41
42/// Fallow CLI version that produced this envelope. Renders to the JSON wire as
43/// a bare string (e.g. `"2.74.0"`).
44#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
45#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
46#[serde(transparent)]
47pub struct ToolVersion(pub String);
48
49/// Analysis duration in milliseconds. Renders to the JSON wire as a bare
50/// integer.
51#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
52#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
53#[serde(transparent)]
54pub struct ElapsedMs(pub u64);
55
56/// Audit-mode marker emitted on each finding when `fallow audit --format json`
57/// runs with a base ref. `true` means the finding's structural key was not
58/// present at the base ref (introduced by the current changeset); `false`
59/// means it was inherited.
60///
61/// Outside of audit sub-results the field is omitted, so call sites typically
62/// hold `Option<AuditIntroduced>`. Renders to the JSON wire as a bare boolean.
63#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
64#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
65#[serde(transparent)]
66pub struct AuditIntroduced(pub bool);
67
68/// Entry-point detection summary embedded in `CheckOutput` and the combined
69/// envelope.
70#[derive(Debug, Clone, Default, Serialize)]
71#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
72pub struct EntryPoints {
73    /// Total number of detected entry points.
74    pub total: usize,
75    /// Breakdown of entry points by detection source (e.g., `"package.json"`,
76    /// `"next.js"`, `"config entry"`). Underscored keys so dashboards can
77    /// drill into individual sources.
78    pub sources: BTreeMap<String, usize>,
79}
80
81/// Per-category issue counts for dead-code analysis. Always present in
82/// `CheckOutput`; when `--summary` is used the individual issue arrays are
83/// omitted but this object stays populated.
84#[derive(Debug, Clone, Default, Serialize)]
85#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
86pub struct CheckSummary {
87    /// Total number of issues across all categories.
88    pub total_issues: usize,
89    /// Unused source files.
90    pub unused_files: usize,
91    /// Unused value exports.
92    pub unused_exports: usize,
93    /// Unused type exports.
94    pub unused_types: usize,
95    /// Public exports whose signature references same-file private types.
96    pub private_type_leaks: usize,
97    /// Combined count of unused entries across `dependencies`,
98    /// `devDependencies`, and `optionalDependencies`. The per-section
99    /// breakdown lives in the individual issue arrays on `CheckOutput`.
100    pub unused_dependencies: usize,
101    /// Unused enum members.
102    pub unused_enum_members: usize,
103    /// Unused class members.
104    pub unused_class_members: usize,
105    /// Unused store members.
106    #[serde(default)]
107    pub unused_store_members: usize,
108    /// Vue/Svelte injects whose key is provided nowhere in the project.
109    #[serde(default)]
110    pub unprovided_injects: usize,
111    /// Vue/Svelte components reachable but rendered nowhere in the project.
112    #[serde(default)]
113    pub unrendered_components: usize,
114    /// Vue, Svelte, or React props referenced nowhere inside their own component.
115    #[serde(default)]
116    pub unused_component_props: usize,
117    /// Vue `<script setup>` emits emitted nowhere inside their own SFC.
118    #[serde(default)]
119    pub unused_component_emits: usize,
120    /// Angular `@Input()` bindings referenced nowhere inside their own component.
121    #[serde(default)]
122    pub unused_component_inputs: usize,
123    /// Angular `@Output()` bindings emitted nowhere inside their own component.
124    #[serde(default)]
125    pub unused_component_outputs: usize,
126    /// Svelte components dispatching a custom event via `createEventDispatcher`
127    /// whose name is listened to nowhere in the project.
128    #[serde(default)]
129    pub unused_svelte_events: usize,
130    /// Next.js Server Actions (exports of `"use server"` files) referenced by no
131    /// code in the project.
132    #[serde(default)]
133    pub unused_server_actions: usize,
134    /// SvelteKit `load()` return-object keys read by no consumer.
135    #[serde(default)]
136    pub unused_load_data_keys: usize,
137    /// Imports that could not be resolved against the project's module graph.
138    pub unresolved_imports: usize,
139    /// Dependencies imported but absent from `package.json`.
140    pub unlisted_dependencies: usize,
141    /// Same-named exports declared in more than one module.
142    pub duplicate_exports: usize,
143    /// Production dependencies only used via type-only imports (could be
144    /// devDependencies). Only populated in production mode.
145    pub type_only_dependencies: usize,
146    /// Production dependencies only imported by test files (could be
147    /// devDependencies).
148    pub test_only_dependencies: usize,
149    /// Cycles detected in the import graph.
150    pub circular_dependencies: usize,
151    /// Cycles or self-loops in the re-export edge subgraph (barrel files
152    /// re-exporting from each other in a loop).
153    #[serde(default)]
154    pub re_export_cycles: usize,
155    /// Imports that cross architecture boundary rules.
156    pub boundary_violations: usize,
157    /// Files that match no architecture boundary zone.
158    #[serde(default)]
159    pub boundary_coverage_violations: usize,
160    /// Calls from zoned files to callees forbidden for that zone.
161    #[serde(default)]
162    pub boundary_call_violations: usize,
163    /// Banned calls, imports, and catalogue-derived effects matched by
164    /// declarative rule packs.
165    #[serde(default)]
166    pub policy_violations: usize,
167    /// Suppression comments that no longer match a finding.
168    pub stale_suppressions: usize,
169    /// Unused pnpm-workspace catalog entries.
170    pub unused_catalog_entries: usize,
171    /// Empty named catalog groups.
172    pub empty_catalog_groups: usize,
173    /// Workspace package.json catalog references the workspace catalogs
174    /// do not declare.
175    pub unresolved_catalog_references: usize,
176    /// Pnpm `overrides:` entries whose target package is not declared by any
177    /// workspace package and not present in the lockfile.
178    pub unused_dependency_overrides: usize,
179    /// Pnpm `overrides:` entries whose key or value cannot be parsed.
180    pub misconfigured_dependency_overrides: usize,
181    /// `"use client"` files that export a Next.js server-only / route-config name.
182    #[serde(default)]
183    pub invalid_client_exports: usize,
184    /// Barrel files that re-export both a `"use client"` origin and a
185    /// server-only origin.
186    #[serde(default)]
187    pub mixed_client_server_barrels: usize,
188    /// Misplaced `"use client"` / `"use server"` directives written as
189    /// expression statements after a non-directive statement.
190    #[serde(default)]
191    pub misplaced_directives: usize,
192    /// Next.js App Router route files that resolve to the same URL within one
193    /// app-root.
194    #[serde(default)]
195    pub route_collisions: usize,
196    /// Sibling Next.js dynamic route segments at one position using different
197    /// param spellings.
198    #[serde(default)]
199    pub dynamic_segment_name_conflicts: usize,
200}
201
202/// Per-category delta comparison against a saved baseline. Only present in
203/// `CheckOutput` when `--baseline` is used.
204#[derive(Debug, Clone, Default, Serialize)]
205#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
206pub struct BaselineDeltas {
207    /// Net change in total issues vs baseline (positive = more issues).
208    pub total_delta: i64,
209    /// Per-category breakdown of current, baseline, and delta counts.
210    pub per_category: BTreeMap<String, BaselineCategoryDelta>,
211}
212
213/// Single-category baseline delta entry inside [`BaselineDeltas::per_category`].
214#[derive(Debug, Clone, Copy, Default, Serialize)]
215#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
216pub struct BaselineCategoryDelta {
217    /// Current issue count for this category.
218    pub current: usize,
219    /// Baseline issue count for this category.
220    pub baseline: usize,
221    /// Change from baseline (current - baseline).
222    pub delta: i64,
223}
224
225/// Baseline match statistics. Shows how many baseline entries existed and how
226/// many matched current issues. Useful for detecting stale baselines
227/// programmatically. Only present in `CheckOutput` when `--baseline` is used.
228#[derive(Debug, Clone, Copy, Default, Serialize)]
229#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
230pub struct BaselineMatch {
231    /// Total number of entries in the loaded baseline file.
232    pub entries: usize,
233    /// Number of baseline entries that matched current issues and were
234    /// filtered.
235    pub matched: usize,
236}
237
238/// Result of regression detection (`--fail-on-regression`). Compares current
239/// issue counts against a baseline from config or an explicit file.
240#[derive(Debug, Clone, Serialize)]
241#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
242pub struct RegressionResult {
243    /// Outcome of the regression check.
244    pub status: RegressionStatus,
245    /// Baseline total before the change. Absent when status is `skipped`.
246    #[serde(default, skip_serializing_if = "Option::is_none")]
247    pub baseline_total: Option<i64>,
248    /// Current total after the change. Absent when status is `skipped`.
249    #[serde(default, skip_serializing_if = "Option::is_none")]
250    pub current_total: Option<i64>,
251    /// Difference current - baseline. Absent when status is `skipped`.
252    #[serde(default, skip_serializing_if = "Option::is_none")]
253    pub delta: Option<i64>,
254    /// Configured tolerance, interpreted per [`RegressionToleranceKind`].
255    /// Absent when status is `skipped`.
256    #[serde(default, skip_serializing_if = "Option::is_none")]
257    pub tolerance: Option<f64>,
258    /// Interpretation of the tolerance value.
259    #[serde(default, skip_serializing_if = "Option::is_none")]
260    pub tolerance_kind: Option<RegressionToleranceKind>,
261    /// Whether the regression exceeded the tolerance.
262    pub exceeded: bool,
263    /// Only present when status is `skipped`.
264    #[serde(default, skip_serializing_if = "Option::is_none")]
265    pub reason: Option<String>,
266}
267
268/// Status of a regression-check pass.
269#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
270#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
271#[serde(rename_all = "lowercase")]
272pub enum RegressionStatus {
273    /// Issue count within tolerance.
274    Pass,
275    /// Issue count exceeded tolerance.
276    Exceeded,
277    /// Regression check did not run (missing baseline, etc.).
278    Skipped,
279}
280
281/// Interpretation of [`RegressionResult::tolerance`].
282#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
283#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
284#[serde(rename_all = "lowercase")]
285pub enum RegressionToleranceKind {
286    /// Tolerance is interpreted as an absolute issue-count delta.
287    Absolute,
288    /// Tolerance is interpreted as a percentage of the baseline total.
289    Percentage,
290}
291
292/// Metric and rule definitions emitted under `_meta` when `--explain` is
293/// passed (always present in MCP responses). Helps AI agents and CI systems
294/// interpret metric values without re-reading the docs site.
295#[derive(Debug, Clone, Default, Serialize)]
296#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
297pub struct Meta {
298    /// URL to the documentation page for this command.
299    #[serde(default, skip_serializing_if = "Option::is_none")]
300    pub docs: Option<String>,
301    /// Local telemetry correlation metadata for agent follow-up runs.
302    #[serde(default, skip_serializing_if = "Option::is_none")]
303    pub telemetry: Option<TelemetryMeta>,
304    /// Per-field definitions for envelope fields and action payload fields.
305    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
306    pub field_definitions: BTreeMap<String, String>,
307    /// Per-metric definitions: name, description, range, interpretation.
308    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
309    pub metrics: BTreeMap<String, MetaMetric>,
310    /// Per-rule definitions for check command output.
311    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
312    pub rules: BTreeMap<String, MetaRule>,
313}
314
315/// Privacy-safe local run metadata emitted for JSON consumers.
316#[derive(Debug, Clone, Default, Serialize)]
317#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
318pub struct TelemetryMeta {
319    /// Ephemeral local token that may be passed to the hidden `--parent-run`
320    /// flag on a later command. It is not derived from repository, path, user,
321    /// machine, project, or cloud data.
322    #[serde(default, skip_serializing_if = "Option::is_none")]
323    pub analysis_run_id: Option<String>,
324}
325
326/// Single-metric definition inside [`Meta::metrics`].
327#[derive(Debug, Clone, Default, Serialize)]
328#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
329pub struct MetaMetric {
330    /// Human-readable metric name.
331    #[serde(default, skip_serializing_if = "Option::is_none")]
332    pub name: Option<String>,
333    /// What this metric measures and how it is computed.
334    #[serde(default, skip_serializing_if = "Option::is_none")]
335    pub description: Option<String>,
336    /// Valid value range (e.g., `"[0, 100]"`).
337    #[serde(default, skip_serializing_if = "Option::is_none")]
338    pub range: Option<String>,
339    /// How to read the value (e.g., `"lower is better"`).
340    #[serde(default, skip_serializing_if = "Option::is_none")]
341    pub interpretation: Option<String>,
342}
343
344/// Single-rule definition inside [`Meta::rules`].
345#[derive(Debug, Clone, Default, Serialize)]
346#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
347pub struct MetaRule {
348    /// Human-readable rule name.
349    #[serde(default, skip_serializing_if = "Option::is_none")]
350    pub name: Option<String>,
351    /// What this rule detects.
352    #[serde(default, skip_serializing_if = "Option::is_none")]
353    pub description: Option<String>,
354    /// URL to the rule documentation.
355    #[serde(default, skip_serializing_if = "Option::is_none")]
356    pub docs: Option<String>,
357}
fallow_types/envelope.rs

fallow_types/
envelope.rs
