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 `<script setup>` props referenced nowhere inside their own SFC.
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 /// Next.js Server Actions (exports of `"use server"` files) referenced by no
121 /// code in the project.
122 #[serde(default)]
123 pub unused_server_actions: usize,
124 /// SvelteKit `load()` return-object keys read by no consumer.
125 #[serde(default)]
126 pub unused_load_data_keys: usize,
127 /// Imports that could not be resolved against the project's module graph.
128 pub unresolved_imports: usize,
129 /// Dependencies imported but absent from `package.json`.
130 pub unlisted_dependencies: usize,
131 /// Same-named exports declared in more than one module.
132 pub duplicate_exports: usize,
133 /// Production dependencies only used via type-only imports (could be
134 /// devDependencies). Only populated in production mode.
135 pub type_only_dependencies: usize,
136 /// Production dependencies only imported by test files (could be
137 /// devDependencies).
138 pub test_only_dependencies: usize,
139 /// Cycles detected in the import graph.
140 pub circular_dependencies: usize,
141 /// Cycles or self-loops in the re-export edge subgraph (barrel files
142 /// re-exporting from each other in a loop).
143 #[serde(default)]
144 pub re_export_cycles: usize,
145 /// Imports that cross architecture boundary rules.
146 pub boundary_violations: usize,
147 /// Files that match no architecture boundary zone.
148 #[serde(default)]
149 pub boundary_coverage_violations: usize,
150 /// Calls from zoned files to callees forbidden for that zone.
151 #[serde(default)]
152 pub boundary_call_violations: usize,
153 /// Banned calls and banned imports matched by declarative rule packs.
154 #[serde(default)]
155 pub policy_violations: usize,
156 /// Suppression comments that no longer match a finding.
157 pub stale_suppressions: usize,
158 /// Unused pnpm-workspace catalog entries.
159 pub unused_catalog_entries: usize,
160 /// Empty named catalog groups.
161 pub empty_catalog_groups: usize,
162 /// Workspace package.json catalog references the workspace catalogs
163 /// do not declare.
164 pub unresolved_catalog_references: usize,
165 /// Pnpm `overrides:` entries whose target package is not declared by any
166 /// workspace package and not present in the lockfile.
167 pub unused_dependency_overrides: usize,
168 /// Pnpm `overrides:` entries whose key or value cannot be parsed.
169 pub misconfigured_dependency_overrides: usize,
170 /// `"use client"` files that export a Next.js server-only / route-config name.
171 #[serde(default)]
172 pub invalid_client_exports: usize,
173 /// Barrel files that re-export both a `"use client"` origin and a
174 /// server-only origin.
175 #[serde(default)]
176 pub mixed_client_server_barrels: usize,
177 /// Misplaced `"use client"` / `"use server"` directives written as
178 /// expression statements after a non-directive statement.
179 #[serde(default)]
180 pub misplaced_directives: usize,
181 /// Next.js App Router route files that resolve to the same URL within one
182 /// app-root.
183 #[serde(default)]
184 pub route_collisions: usize,
185 /// Sibling Next.js dynamic route segments at one position using different
186 /// param spellings.
187 #[serde(default)]
188 pub dynamic_segment_name_conflicts: usize,
189}
190
191/// Per-category delta comparison against a saved baseline. Only present in
192/// `CheckOutput` when `--baseline` is used.
193#[derive(Debug, Clone, Default, Serialize)]
194#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
195pub struct BaselineDeltas {
196 /// Net change in total issues vs baseline (positive = more issues).
197 pub total_delta: i64,
198 /// Per-category breakdown of current, baseline, and delta counts.
199 pub per_category: BTreeMap<String, BaselineCategoryDelta>,
200}
201
202/// Single-category baseline delta entry inside [`BaselineDeltas::per_category`].
203#[derive(Debug, Clone, Copy, Default, Serialize)]
204#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
205pub struct BaselineCategoryDelta {
206 /// Current issue count for this category.
207 pub current: usize,
208 /// Baseline issue count for this category.
209 pub baseline: usize,
210 /// Change from baseline (current - baseline).
211 pub delta: i64,
212}
213
214/// Baseline match statistics. Shows how many baseline entries existed and how
215/// many matched current issues. Useful for detecting stale baselines
216/// programmatically. Only present in `CheckOutput` when `--baseline` is used.
217#[derive(Debug, Clone, Copy, Default, Serialize)]
218#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
219pub struct BaselineMatch {
220 /// Total number of entries in the loaded baseline file.
221 pub entries: usize,
222 /// Number of baseline entries that matched current issues and were
223 /// filtered.
224 pub matched: usize,
225}
226
227/// Result of regression detection (`--fail-on-regression`). Compares current
228/// issue counts against a baseline from config or an explicit file.
229#[derive(Debug, Clone, Serialize)]
230#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
231pub struct RegressionResult {
232 /// Outcome of the regression check.
233 pub status: RegressionStatus,
234 /// Baseline total before the change. Absent when status is `skipped`.
235 #[serde(default, skip_serializing_if = "Option::is_none")]
236 pub baseline_total: Option<i64>,
237 /// Current total after the change. Absent when status is `skipped`.
238 #[serde(default, skip_serializing_if = "Option::is_none")]
239 pub current_total: Option<i64>,
240 /// Difference current - baseline. Absent when status is `skipped`.
241 #[serde(default, skip_serializing_if = "Option::is_none")]
242 pub delta: Option<i64>,
243 /// Configured tolerance, interpreted per [`RegressionToleranceKind`].
244 /// Absent when status is `skipped`.
245 #[serde(default, skip_serializing_if = "Option::is_none")]
246 pub tolerance: Option<f64>,
247 /// Interpretation of the tolerance value.
248 #[serde(default, skip_serializing_if = "Option::is_none")]
249 pub tolerance_kind: Option<RegressionToleranceKind>,
250 /// Whether the regression exceeded the tolerance.
251 pub exceeded: bool,
252 /// Only present when status is `skipped`.
253 #[serde(default, skip_serializing_if = "Option::is_none")]
254 pub reason: Option<String>,
255}
256
257/// Status of a regression-check pass.
258#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
259#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
260#[serde(rename_all = "lowercase")]
261pub enum RegressionStatus {
262 /// Issue count within tolerance.
263 Pass,
264 /// Issue count exceeded tolerance.
265 Exceeded,
266 /// Regression check did not run (missing baseline, etc.).
267 Skipped,
268}
269
270/// Interpretation of [`RegressionResult::tolerance`].
271#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
272#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
273#[serde(rename_all = "lowercase")]
274pub enum RegressionToleranceKind {
275 /// Tolerance is interpreted as an absolute issue-count delta.
276 Absolute,
277 /// Tolerance is interpreted as a percentage of the baseline total.
278 Percentage,
279}
280
281/// Metric and rule definitions emitted under `_meta` when `--explain` is
282/// passed (always present in MCP responses). Helps AI agents and CI systems
283/// interpret metric values without re-reading the docs site.
284#[derive(Debug, Clone, Default, Serialize)]
285#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
286pub struct Meta {
287 /// URL to the documentation page for this command.
288 #[serde(default, skip_serializing_if = "Option::is_none")]
289 pub docs: Option<String>,
290 /// Local telemetry correlation metadata for agent follow-up runs.
291 #[serde(default, skip_serializing_if = "Option::is_none")]
292 pub telemetry: Option<TelemetryMeta>,
293 /// Per-field definitions for envelope fields and action payload fields.
294 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
295 pub field_definitions: BTreeMap<String, String>,
296 /// Per-metric definitions: name, description, range, interpretation.
297 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
298 pub metrics: BTreeMap<String, MetaMetric>,
299 /// Per-rule definitions for check command output.
300 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
301 pub rules: BTreeMap<String, MetaRule>,
302}
303
304/// Privacy-safe local run metadata emitted for JSON consumers.
305#[derive(Debug, Clone, Default, Serialize)]
306#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
307pub struct TelemetryMeta {
308 /// Ephemeral local token that may be passed to the hidden `--parent-run`
309 /// flag on a later command. It is not derived from repository, path, user,
310 /// machine, project, or cloud data.
311 #[serde(default, skip_serializing_if = "Option::is_none")]
312 pub analysis_run_id: Option<String>,
313}
314
315/// Single-metric definition inside [`Meta::metrics`].
316#[derive(Debug, Clone, Default, Serialize)]
317#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
318pub struct MetaMetric {
319 /// Human-readable metric name.
320 #[serde(default, skip_serializing_if = "Option::is_none")]
321 pub name: Option<String>,
322 /// What this metric measures and how it is computed.
323 #[serde(default, skip_serializing_if = "Option::is_none")]
324 pub description: Option<String>,
325 /// Valid value range (e.g., `"[0, 100]"`).
326 #[serde(default, skip_serializing_if = "Option::is_none")]
327 pub range: Option<String>,
328 /// How to read the value (e.g., `"lower is better"`).
329 #[serde(default, skip_serializing_if = "Option::is_none")]
330 pub interpretation: Option<String>,
331}
332
333/// Single-rule definition inside [`Meta::rules`].
334#[derive(Debug, Clone, Default, Serialize)]
335#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
336pub struct MetaRule {
337 /// Human-readable rule name.
338 #[serde(default, skip_serializing_if = "Option::is_none")]
339 pub name: Option<String>,
340 /// What this rule detects.
341 #[serde(default, skip_serializing_if = "Option::is_none")]
342 pub description: Option<String>,
343 /// URL to the rule documentation.
344 #[serde(default, skip_serializing_if = "Option::is_none")]
345 pub docs: Option<String>,
346}