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::{Deserialize, Serialize};
17
18use crate::semantic::{
19 ApiSurfaceResult, SemanticAnalysisIdentity, SemanticCandidateDecision, SemanticGapReason,
20 SemanticQuerySummary, SemanticSymbolImpact, SemanticSymbolTrace, TypeCouplingReport,
21};
22
23/// Schema version for this output format (independent of tool version). Bump
24/// policy: ADDITIVE changes (new optional top-level fields, new optional struct
25/// fields, new array entries, new MCP tools, new CLI flags that map to new
26/// optional fields) do NOT bump the version; consumers receive new fields
27/// without breaking. BREAKING changes (renamed fields, removed fields, type
28/// changes, enum-variant removals, semantic changes to existing fields) DO
29/// bump. Additions to existing enum-valued required fields bump the affected
30/// envelope version so strict JSON Schema consumers can migrate.
31/// `ComplexityContributionKind` is non-exhaustive so Rust consumers retain a
32/// wildcard. To
33/// detect newly-added fields without a bump, check field presence via
34/// JSON-key existence rather than gating on the version. v4 was introduced
35/// alongside fallow-cov-protocol 0.2 (per-finding verdict, stable IDs, evidence
36/// block, renamed summary fields); v5 introduced health_score formula_version 2
37/// with scale-invariant scoring semantics; v6 widened `AddToConfigAction.value`
38/// from a scalar string to `oneOf: [string, array]` so the new `ignoreExports`
39/// action can carry a paste-ready array of `{ file, exports }` rule objects
40/// (the legacy `ignoreDependencies` etc. variants still emit strings, so
41/// consumers that switch on `config_key` keep working unchanged). v8 added the
42/// required duplication `spread` field and changed `duplicated_tokens` to count
43/// redundant copies, excluding the retained copy in each group. Envelopes
44/// embedding health use their own version marker, so health-only contract
45/// changes do not advance dead-code or unrelated sibling envelopes. The
46/// runtime-coverage block is extended additively as the protocol evolves
47/// (currently 0.3, which adds an optional capture_quality summary field). Other
48/// additive examples: dupes --group-by adds optional grouped_by, total_issues,
49/// groups fields without bumping.
50#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
51#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
52#[serde(transparent)]
53pub struct SchemaVersion(pub u32);
54
55/// Fallow CLI version that produced this envelope. Renders to the JSON wire as
56/// a bare string (e.g. `"2.74.0"`).
57#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
58#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
59#[serde(transparent)]
60pub struct ToolVersion(pub String);
61
62/// Analysis duration in milliseconds. Renders to the JSON wire as a bare
63/// integer.
64#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
65#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
66#[serde(transparent)]
67pub struct ElapsedMs(pub u64);
68
69/// Audit-mode marker emitted on each finding when `fallow audit --format json`
70/// runs with a base ref. `true` means the finding's structural key was not
71/// present at the base ref (introduced by the current changeset); `false`
72/// means it was inherited. Duplication findings carry one carve-out: a clone
73/// group whose structural key is new but whose instances contain no added line
74/// from the diff (a group re-shaped by removing duplication elsewhere) is
75/// demoted to inherited and serializes `false` (issue #2164). Such demoted
76/// groups additionally carry a `demotion_reason` field naming the rule, and
77/// are counted in `attribution.duplication_demoted` (issue #2220).
78///
79/// Outside of audit sub-results the field is omitted, so call sites typically
80/// hold `Option<AuditIntroduced>`. Renders to the JSON wire as a bare boolean.
81#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
82#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
83#[serde(transparent)]
84pub struct AuditIntroduced(pub bool);
85
86/// Entry-point detection summary embedded in `CheckOutput` and the combined
87/// envelope.
88#[derive(Debug, Clone, Default, Serialize)]
89#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
90pub struct EntryPoints {
91 /// Total number of detected entry points.
92 pub total: usize,
93 /// Breakdown of entry points by detection source (e.g., `"package.json"`,
94 /// `"next.js"`, `"config entry"`). Underscored keys so dashboards can
95 /// drill into individual sources.
96 pub sources: BTreeMap<String, usize>,
97}
98
99#[expect(
100 clippy::trivially_copy_pass_by_ref,
101 reason = "serde skip_serializing_if requires a reference"
102)]
103const fn zero_count(count: &usize) -> bool {
104 *count == 0
105}
106
107/// Per-category issue counts for dead-code analysis. Always present in
108/// `CheckOutput`; when `--summary` is used the individual issue arrays are
109/// omitted but this object stays populated.
110#[derive(Debug, Clone, Default, Serialize)]
111#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
112pub struct CheckSummary {
113 /// Total number of issues across all categories.
114 pub total_issues: usize,
115 /// Prop chains whose saved effective severity explicitly enforces error policy.
116 #[serde(default, skip_serializing_if = "zero_count")]
117 pub prop_drilling_chains: usize,
118 /// Thin wrappers whose saved effective severity explicitly enforces error policy.
119 #[serde(default, skip_serializing_if = "zero_count")]
120 pub thin_wrappers: usize,
121 /// Duplicate prop shapes whose saved effective severity explicitly enforces error policy.
122 #[serde(default, skip_serializing_if = "zero_count")]
123 pub duplicate_prop_shapes: usize,
124 /// Unused source files.
125 pub unused_files: usize,
126 /// Unused value exports.
127 pub unused_exports: usize,
128 /// Unused type exports.
129 pub unused_types: usize,
130 /// Public exports whose signature references same-file private types.
131 pub private_type_leaks: usize,
132 /// Exports marked `@deprecated` that are still referenced.
133 pub deprecated_exports_in_use: usize,
134 /// Combined count of unused entries across `dependencies`,
135 /// `devDependencies`, and `optionalDependencies`. The per-section
136 /// breakdown lives in the individual issue arrays on `CheckOutput`.
137 pub unused_dependencies: usize,
138 /// Unused enum members.
139 pub unused_enum_members: usize,
140 /// Unused class members.
141 pub unused_class_members: usize,
142 /// Unused namespace members.
143 #[serde(default)]
144 pub unused_namespace_members: usize,
145 /// Unused store members.
146 #[serde(default)]
147 pub unused_store_members: usize,
148 /// Vue/Svelte injects whose key is provided nowhere in the project.
149 #[serde(default)]
150 pub unprovided_injects: usize,
151 /// Vue/Svelte components reachable but rendered nowhere in the project.
152 #[serde(default)]
153 pub unrendered_components: usize,
154 /// Vue, Svelte, or React props referenced nowhere inside their own component.
155 #[serde(default)]
156 pub unused_component_props: usize,
157 /// Optional consumed props omitted by known reachable callers, for manual review.
158 #[serde(default)]
159 pub absent_component_props: usize,
160 /// Parameters that each visible call passes in one way, for manual review.
161 /// Absent while zero, so a run with the opt-in rule off keeps its shape.
162 #[serde(default, skip_serializing_if = "zero_count")]
163 pub constant_parameters: usize,
164 /// Vue `<script setup>` emits emitted nowhere inside their own SFC.
165 #[serde(default)]
166 pub unused_component_emits: usize,
167 /// Angular `@Input()` bindings referenced nowhere inside their own component.
168 #[serde(default)]
169 pub unused_component_inputs: usize,
170 /// Angular `@Output()` bindings emitted nowhere inside their own component.
171 #[serde(default)]
172 pub unused_component_outputs: usize,
173 /// Svelte components dispatching a custom event via `createEventDispatcher`
174 /// whose name is listened to nowhere in the project.
175 #[serde(default)]
176 pub unused_svelte_events: usize,
177 /// Effect layers composed only into layers that nothing uses.
178 #[serde(default)]
179 pub unused_effect_layers: usize,
180 /// Effect tagged error classes that no code constructs or fails with.
181 #[serde(default)]
182 pub unused_tagged_errors: usize,
183 /// `catchTag` handlers for a project tag that no code produces.
184 #[serde(default)]
185 pub unproduced_catch_tags: usize,
186 /// Next.js Server Actions (exports of `"use server"` files) referenced by no
187 /// code in the project.
188 #[serde(default)]
189 pub unused_server_actions: usize,
190 /// SvelteKit `load()` return-object keys read by no consumer.
191 #[serde(default)]
192 pub unused_load_data_keys: usize,
193 /// Imports that could not be resolved against the project's module graph.
194 pub unresolved_imports: usize,
195 /// Dependencies imported but absent from `package.json`.
196 pub unlisted_dependencies: usize,
197 /// Binaries that scripts or process calls run, but that no installed or
198 /// listed package provides.
199 #[serde(default)]
200 pub unlisted_binaries: usize,
201 /// Same-named exports declared in more than one module.
202 pub duplicate_exports: usize,
203 /// Bindings that one module exports under two or more names.
204 #[serde(default)]
205 pub duplicate_export_aliases: usize,
206 /// Production dependencies only used via type-only imports (could be
207 /// devDependencies). Only populated in production mode.
208 pub type_only_dependencies: usize,
209 /// Production dependencies only imported by test files (could be
210 /// devDependencies).
211 pub test_only_dependencies: usize,
212 /// devDependencies imported by production source code with a runtime/value
213 /// import (should be promoted to dependencies).
214 pub dev_dependencies_in_production: usize,
215 /// Cycles detected in the import graph.
216 pub circular_dependencies: usize,
217 /// Cycles or self-loops in the re-export edge subgraph (barrel files
218 /// re-exporting from each other in a loop).
219 #[serde(default)]
220 pub re_export_cycles: usize,
221 /// Dependency cycles between workspace packages.
222 #[serde(default)]
223 pub package_cycles: usize,
224 /// Imports that cross architecture boundary rules.
225 pub boundary_violations: usize,
226 /// Files that match no architecture boundary zone.
227 #[serde(default)]
228 pub boundary_coverage_violations: usize,
229 /// Calls from zoned files to callees forbidden for that zone.
230 #[serde(default)]
231 pub boundary_call_violations: usize,
232 /// Banned calls, imports, and catalogue-derived effects matched by
233 /// declarative rule packs.
234 #[serde(default)]
235 pub policy_violations: usize,
236 /// Suppression comments that no longer match a finding.
237 pub stale_suppressions: usize,
238 /// Unused pnpm-workspace catalog entries.
239 pub unused_catalog_entries: usize,
240 /// Empty named catalog groups.
241 pub empty_catalog_groups: usize,
242 /// Workspace package.json catalog references the workspace catalogs
243 /// do not declare.
244 pub unresolved_catalog_references: usize,
245 /// Package-manager overrides whose target package is not declared by any
246 /// workspace package and not present in the active readable lockfile.
247 pub unused_dependency_overrides: usize,
248 /// Package-manager overrides whose key or value cannot be parsed.
249 pub misconfigured_dependency_overrides: usize,
250 /// `"use client"` files that export a Next.js server-only / route-config name.
251 #[serde(default)]
252 pub invalid_client_exports: usize,
253 /// Barrel files that re-export both a `"use client"` origin and a
254 /// server-only origin.
255 #[serde(default)]
256 pub mixed_client_server_barrels: usize,
257 /// Misplaced `"use client"` / `"use server"` directives written as
258 /// expression statements after a non-directive statement.
259 #[serde(default)]
260 pub misplaced_directives: usize,
261 /// Next.js App Router route files that resolve to the same URL within one
262 /// app-root.
263 #[serde(default)]
264 pub route_collisions: usize,
265 /// Sibling Next.js dynamic route segments at one position using different
266 /// param spellings.
267 #[serde(default)]
268 pub dynamic_segment_name_conflicts: usize,
269}
270
271/// Per-category delta comparison against a saved baseline. Only present in
272/// `CheckOutput` when `--baseline` is used.
273#[derive(Debug, Clone, Default, Serialize)]
274#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
275pub struct BaselineDeltas {
276 /// Net change in total issues vs baseline (positive = more issues).
277 pub total_delta: i64,
278 /// Per-category breakdown of current, baseline, and delta counts.
279 pub per_category: BTreeMap<String, BaselineCategoryDelta>,
280}
281
282/// Single-category baseline delta entry inside [`BaselineDeltas::per_category`].
283#[derive(Debug, Clone, Copy, Default, Serialize)]
284#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
285pub struct BaselineCategoryDelta {
286 /// Current issue count for this category.
287 pub current: usize,
288 /// Baseline issue count for this category.
289 pub baseline: usize,
290 /// Change from baseline (current - baseline).
291 pub delta: i64,
292}
293
294/// Baseline match statistics. Shows how many baseline entries existed and how
295/// many matched current issues. Useful for detecting stale baselines
296/// programmatically. Only present in `CheckOutput` when `--baseline` is used.
297#[derive(Debug, Clone, Copy, Default, Serialize)]
298#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
299pub struct BaselineMatch {
300 /// Total number of entries in the loaded baseline file.
301 pub entries: usize,
302 /// Number of baseline entries that matched current issues and were
303 /// filtered.
304 pub matched: usize,
305}
306
307/// Result of regression detection (`--fail-on-regression`). Compares current
308/// issue counts against a baseline from config or an explicit file.
309#[derive(Debug, Clone, Serialize)]
310#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
311pub struct RegressionResult {
312 /// Outcome of the regression check.
313 pub status: RegressionStatus,
314 /// Baseline total before the change. Absent when status is `skipped`.
315 #[serde(default, skip_serializing_if = "Option::is_none")]
316 pub baseline_total: Option<i64>,
317 /// Current total after the change. Absent when status is `skipped`.
318 #[serde(default, skip_serializing_if = "Option::is_none")]
319 pub current_total: Option<i64>,
320 /// Difference current - baseline. Absent when status is `skipped`.
321 #[serde(default, skip_serializing_if = "Option::is_none")]
322 pub delta: Option<i64>,
323 /// Configured tolerance, interpreted per [`RegressionToleranceKind`].
324 /// Absent when status is `skipped`.
325 #[serde(default, skip_serializing_if = "Option::is_none")]
326 pub tolerance: Option<f64>,
327 /// Interpretation of the tolerance value.
328 #[serde(default, skip_serializing_if = "Option::is_none")]
329 pub tolerance_kind: Option<RegressionToleranceKind>,
330 /// Whether the regression exceeded the tolerance.
331 pub exceeded: bool,
332 /// Only present when status is `skipped`.
333 #[serde(default, skip_serializing_if = "Option::is_none")]
334 pub reason: Option<String>,
335}
336
337/// Status of a regression-check pass.
338#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
339#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
340#[serde(rename_all = "lowercase")]
341pub enum RegressionStatus {
342 /// Issue count within tolerance.
343 Pass,
344 /// Issue count exceeded tolerance.
345 Exceeded,
346 /// Regression check did not run (missing baseline, etc.).
347 Skipped,
348}
349
350/// Interpretation of [`RegressionResult::tolerance`].
351#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
352#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
353#[serde(rename_all = "lowercase")]
354pub enum RegressionToleranceKind {
355 /// Tolerance is interpreted as an absolute issue-count delta.
356 Absolute,
357 /// Tolerance is interpreted as a percentage of the baseline total.
358 Percentage,
359}
360
361/// Metric and rule definitions emitted under `_meta` when `--explain` is
362/// passed (always present in MCP responses). Helps AI agents and CI systems
363/// interpret metric values without re-reading the docs site.
364#[derive(Debug, Clone, Default, Serialize)]
365#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
366pub struct Meta {
367 /// URL to the documentation page for this command.
368 #[serde(default, skip_serializing_if = "Option::is_none")]
369 pub docs: Option<String>,
370 /// Local telemetry correlation metadata for agent follow-up runs.
371 #[serde(default, skip_serializing_if = "Option::is_none")]
372 pub telemetry: Option<TelemetryMeta>,
373 /// Provenance for the opt-in TypeScript semantic analysis pass.
374 #[serde(default, skip_serializing_if = "Option::is_none")]
375 pub type_aware: Option<TypeAwareMeta>,
376 /// Per-field definitions for envelope fields and action payload fields.
377 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
378 pub field_definitions: BTreeMap<String, String>,
379 /// Per-metric definitions: name, description, range, interpretation.
380 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
381 pub metrics: BTreeMap<String, MetaMetric>,
382 /// Per-rule definitions for check command output.
383 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
384 pub rules: BTreeMap<String, MetaRule>,
385}
386
387/// Bounded provenance emitted when the opt-in type-aware pass runs.
388#[derive(Debug, Clone, Default, Deserialize, Serialize)]
389#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
390pub struct TypeAwareMeta {
391 /// Compatibility identity used by audit, baselines, snapshots, and stores.
392 #[serde(default, skip_serializing_if = "Option::is_none")]
393 pub identity: Option<SemanticAnalysisIdentity>,
394 /// Effective CLI or repository policy for incomplete semantic evidence.
395 #[serde(default, skip_serializing_if = "Option::is_none")]
396 pub required_completeness: Option<crate::semantic::SemanticCompletenessRequirement>,
397 /// Compact status for every requested semantic query.
398 #[serde(default, skip_serializing_if = "Vec::is_empty")]
399 pub queries: Vec<SemanticQuerySummary>,
400 /// Bounded decision and evidence for each semantic dead-code candidate.
401 #[serde(default, skip_serializing_if = "Vec::is_empty")]
402 pub candidate_decisions: Vec<SemanticCandidateDecision>,
403 /// Checker-backed trace evidence requested by focused symbol queries.
404 #[serde(default, skip_serializing_if = "Vec::is_empty")]
405 pub symbol_traces: Vec<SemanticSymbolTrace>,
406 /// Package-public surface and confirmed private type leaks.
407 #[serde(default, skip_serializing_if = "Option::is_none")]
408 pub api_surface: Option<ApiSurfaceResult>,
409 /// Exact-symbol blast radius and targeted-test recommendations.
410 #[serde(default, skip_serializing_if = "Vec::is_empty")]
411 pub symbol_impacts: Vec<SemanticSymbolImpact>,
412 /// Advisory project-local public-signature coupling.
413 #[serde(default, skip_serializing_if = "Option::is_none")]
414 pub type_coupling: Option<TypeCouplingReport>,
415 /// The call evidence of the `constant-parameter` rule. Present when the
416 /// rule sent candidates to the companion.
417 #[serde(default, skip_serializing_if = "Option::is_none")]
418 pub call_evidence: Option<TypeAwareCallEvidenceMeta>,
419 /// Whether the semantic companion executed at least one query.
420 pub executed: bool,
421 /// Version of Fallow's backend-neutral sidecar protocol.
422 pub protocol_version: u32,
423 /// Version of the sidecar package that executed the query.
424 #[serde(default, skip_serializing_if = "Option::is_none")]
425 pub sidecar_version: Option<String>,
426 /// Semantic backend capability identifier.
427 pub backend: String,
428 /// Backend compiler or engine version that executed the query.
429 #[serde(default, skip_serializing_if = "Option::is_none")]
430 pub backend_version: Option<String>,
431 /// TypeScript project configs selected for candidate files.
432 pub selected_tsconfigs: Vec<String>,
433 /// Number of candidate findings sent to the sidecar.
434 pub candidate_count: usize,
435 /// Number of candidates confirmed as used and removed.
436 pub confirmed_used_count: usize,
437 /// Number of candidates preserved because they implement or override a contract.
438 pub contract_preserved_count: usize,
439 /// Number of candidates with complete, closed-world no-static-reference evidence.
440 pub no_static_references_count: usize,
441 /// Number of retained class members eligible for a guarded type-aware fix.
442 pub fix_eligible_count: usize,
443 /// Number of candidates retained because semantic use was unresolved.
444 pub unresolved_count: usize,
445 /// Number of candidates retained because semantic analysis abstained.
446 pub abstained_count: usize,
447 /// Stable abstention reason counts for automation and diagnostics.
448 pub abstention_reasons: TypeAwareAbstentionCounts,
449 /// Per-project semantic refinement status and evidence.
450 pub projects: Vec<TypeAwareProjectMeta>,
451 /// Number of bounded warnings returned by the sidecar.
452 pub warning_count: usize,
453 /// Bounded semantic warnings. Findings mentioned here were retained.
454 pub warnings: Vec<String>,
455 /// Semantic pass duration as reported by the sidecar.
456 pub elapsed_ms: u64,
457 /// Bounded semantic phase timings reported by the sidecar.
458 pub phase_timings_ms: TypeAwarePhaseTimings,
459}
460
461/// The call evidence that the `constant-parameter` rule asked the companion
462/// for.
463#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, Serialize)]
464#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
465pub struct TypeAwareCallEvidenceMeta {
466 /// Parameters with a default whose arguments the companion typed.
467 pub default_candidates: usize,
468 /// Methods of exported classes whose calls the companion read.
469 pub method_candidates: usize,
470 /// Findings that the evidence proved.
471 pub findings: usize,
472 /// The count of each reason that a candidate got no evidence, such as
473 /// `outside-program` or `decorator`. An open set: a later version can
474 /// add a reason.
475 #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
476 pub abstention_reasons: std::collections::BTreeMap<String, usize>,
477 /// Duration of the request as reported by the companion.
478 pub elapsed_ms: u64,
479}
480
481/// Closed set of reasons for retaining a candidate without semantic scanning.
482#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, Serialize)]
483#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
484#[serde(rename_all = "kebab-case")]
485pub enum TypeAwareAbstentionReason {
486 /// No selected TypeScript project contains the candidate file.
487 #[default]
488 NoProject,
489 /// Multiple explicit TypeScript projects contain the candidate file.
490 AmbiguousProject,
491 /// Structural TypeScript diagnostics make exact matching unsafe.
492 BlockingDiagnostics,
493}
494
495/// Closed abstention reason counts for stable machine consumption.
496#[derive(Debug, Clone, Default, Deserialize, Serialize)]
497#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
498pub struct TypeAwareAbstentionCounts {
499 /// Candidates not contained by a selected TypeScript project.
500 pub no_project: usize,
501 /// Candidates contained by more than one explicit TypeScript project.
502 pub ambiguous_project: usize,
503 /// Candidates retained because structural diagnostics block scanning.
504 pub blocking_diagnostics: usize,
505 /// Candidates retained because the raw TypeScript-Go host cannot expose
506 /// named exports from Svelte virtual modules.
507 pub svelte_virtual_module_exports: usize,
508 /// Candidates whose exact declaration identity could not be resolved.
509 pub unknown_symbol: usize,
510 /// Candidates using declaration syntax unsupported by the semantic backend.
511 pub unsupported_syntax: usize,
512 /// Candidates retained because the bounded semantic request reached capacity.
513 pub capacity: usize,
514}
515
516/// How a TypeScript project was selected for semantic refinement.
517#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, Serialize)]
518#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
519#[serde(rename_all = "kebab-case")]
520pub enum TypeAwareProjectSource {
521 /// Fallow selected the nearest discovered project automatically.
522 #[default]
523 Auto,
524 /// The project was supplied with `--type-aware-project`.
525 Explicit,
526}
527
528/// Outcome of semantic refinement for one TypeScript project.
529#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, Serialize)]
530#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
531#[serde(rename_all = "kebab-case")]
532pub enum TypeAwareProjectStatus {
533 /// The project was structurally safe and its candidates were scanned.
534 #[default]
535 Refined,
536 /// Structural diagnostics prevented candidate scanning.
537 Abstained,
538 /// All semantic queries assigned to this Program completed.
539 Complete,
540 /// The Program could not answer its assigned semantic queries safely.
541 Unavailable,
542}
543
544/// How a persistent semantic snapshot was refreshed.
545#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
546#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
547#[serde(rename_all = "kebab-case")]
548pub enum TypeAwareInvalidationKind {
549 /// The backend rebuilt project state from a clean snapshot.
550 Full,
551 /// The backend applied an explicit source-file change set.
552 Incremental,
553 /// No filesystem change was reported between compatible requests.
554 None,
555}
556
557/// Semantic sidecar timings, separated from Fallow's syntactic pipeline.
558#[derive(Debug, Clone, Default, Deserialize, Serialize)]
559#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
560pub struct TypeAwarePhaseTimings {
561 /// TypeScript API construction and project snapshot selection.
562 pub project_setup: u64,
563 /// TypeScript diagnostics collected before any candidate refinement.
564 pub diagnostics: u64,
565 /// Batched symbol lookup and exact declaration matching.
566 pub symbol_scan: u64,
567}
568
569/// Bounded provenance for one TypeScript project handled by the sidecar.
570#[derive(Debug, Clone, Default, Deserialize, Serialize)]
571#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
572pub struct TypeAwareProjectMeta {
573 /// Project config relative to the analysis root, or `<inferred>`.
574 pub config: String,
575 /// How the project was selected: `auto` or `explicit`.
576 pub source: TypeAwareProjectSource,
577 /// Project result: `refined`, `abstained`, `complete`, or `unavailable`.
578 pub status: TypeAwareProjectStatus,
579 /// Candidates assigned to this project.
580 pub candidate_count: usize,
581 /// Candidates confirmed as used and removed.
582 pub confirmed_used_count: usize,
583 /// Candidates retained because they implement or override a contract.
584 pub contract_preserved_count: usize,
585 /// Candidates with complete no-static-reference evidence.
586 pub no_static_references_count: usize,
587 /// Candidates eligible for a guarded class-member fix.
588 pub fix_eligible_count: usize,
589 /// Candidates whose exact semantic outcome remained unresolved.
590 pub unresolved_count: usize,
591 /// Candidates retained without scanning because the project was unsafe.
592 pub abstained_count: usize,
593 /// Config, program, syntactic, and bind diagnostics that block scanning.
594 pub blocking_diagnostic_count: usize,
595 /// Source files loaded into this TypeScript program.
596 pub source_file_count: usize,
597 /// Whether this Program served more than one semantic query in the batch.
598 #[serde(default, skip_serializing_if = "Option::is_none")]
599 pub program_reused: Option<bool>,
600 /// Whether this Program served more than one query in the current batch.
601 #[serde(default, skip_serializing_if = "Option::is_none")]
602 pub program_shared_across_queries: Option<bool>,
603 /// Whether the root-bound semantic session reused the prior snapshot.
604 #[serde(default, skip_serializing_if = "Option::is_none")]
605 pub program_reused_from_previous_snapshot: Option<bool>,
606 /// Monotonic revision within the root-bound semantic session.
607 #[serde(default, skip_serializing_if = "Option::is_none")]
608 pub snapshot_revision: Option<u64>,
609 /// Full, incremental, or no invalidation before this query.
610 #[serde(default, skip_serializing_if = "Option::is_none")]
611 pub invalidation_kind: Option<TypeAwareInvalidationKind>,
612 /// Stable project-level gap reason.
613 #[serde(default, skip_serializing_if = "Option::is_none")]
614 pub reason_code: Option<SemanticGapReason>,
615 /// Stable reason code when `status` is `abstained`.
616 #[serde(default, skip_serializing_if = "Option::is_none")]
617 #[cfg_attr(feature = "schema", schemars(with = "TypeAwareAbstentionReason"))]
618 pub abstain_reason: Option<TypeAwareAbstentionReason>,
619}
620
621/// Privacy-safe local run metadata emitted for JSON consumers.
622#[derive(Debug, Clone, Default, Serialize)]
623#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
624pub struct TelemetryMeta {
625 /// Ephemeral local token that may be passed to the hidden `--parent-run`
626 /// flag on a later command. It is not derived from repository, path, user,
627 /// machine, project, or cloud data.
628 #[serde(default, skip_serializing_if = "Option::is_none")]
629 pub analysis_run_id: Option<String>,
630}
631
632/// Single-metric definition inside [`Meta::metrics`].
633#[derive(Debug, Clone, Default, Serialize)]
634#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
635pub struct MetaMetric {
636 /// Human-readable metric name.
637 #[serde(default, skip_serializing_if = "Option::is_none")]
638 pub name: Option<String>,
639 /// What this metric measures and how it is computed.
640 #[serde(default, skip_serializing_if = "Option::is_none")]
641 pub description: Option<String>,
642 /// Valid value range (e.g., `"[0, 100]"`).
643 #[serde(default, skip_serializing_if = "Option::is_none")]
644 pub range: Option<String>,
645 /// How to read the value (e.g., `"lower is better"`).
646 #[serde(default, skip_serializing_if = "Option::is_none")]
647 pub interpretation: Option<String>,
648}
649
650/// Single-rule definition inside [`Meta::rules`].
651#[derive(Debug, Clone, Default, Serialize)]
652#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
653pub struct MetaRule {
654 /// Human-readable rule name.
655 #[serde(default, skip_serializing_if = "Option::is_none")]
656 pub name: Option<String>,
657 /// What this rule detects.
658 #[serde(default, skip_serializing_if = "Option::is_none")]
659 pub description: Option<String>,
660 /// URL to the rule documentation.
661 #[serde(default, skip_serializing_if = "Option::is_none")]
662 pub docs: Option<String>,
663}