fallow_types/
output_health.rs

1//! Per-action types attached to each health finding by the JSON output
2//! layer.
3//!
4//! These types are the typed wire shape for health output data shared outside
5//! the CLI crate, including `actions[]` arrays and refactoring target
6//! evidence. The JSON emission path constructs action entries through typed
7//! wrappers (for example `UntestedFileFinding` in
8//! `crates/cli/src/health_types/coverage.rs`) and serializes them via serde;
9//! the schemars derive renders matching shapes in `docs/output-schema.json`.
10//!
11//! Whenever a new action variant or optional field is added, update the
12//! matching type here so the drift gate flags the divergence before review.
13
14use std::path::PathBuf;
15
16use serde::Serialize;
17
18/// Evidence linking a refactoring target back to specific analysis data.
19#[derive(Debug, Clone, Default, Serialize)]
20#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
21pub struct TargetEvidence {
22    /// Names of unused exports.
23    #[serde(default, skip_serializing_if = "Vec::is_empty")]
24    pub unused_exports: Vec<String>,
25    /// Complex functions with line numbers and cognitive scores.
26    #[serde(default, skip_serializing_if = "Vec::is_empty")]
27    pub complex_functions: Vec<EvidenceFunction>,
28    /// Files forming the import cycle.
29    #[serde(default, skip_serializing_if = "Vec::is_empty")]
30    pub cycle_path: Vec<String>,
31    /// Files that directly import this target, with imported and local symbols.
32    #[serde(default, skip_serializing_if = "Vec::is_empty")]
33    pub direct_callers: Vec<DirectCallerEvidence>,
34    /// Other duplicate-code instances that share a clone group with this target.
35    #[serde(default, skip_serializing_if = "Vec::is_empty")]
36    pub clone_siblings: Vec<CloneSiblingEvidence>,
37}
38
39/// A function referenced in target evidence.
40#[derive(Debug, Clone, Serialize)]
41#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
42pub struct EvidenceFunction {
43    /// Function name.
44    pub name: String,
45    /// 1-based line number.
46    pub line: u32,
47    /// Cognitive complexity score.
48    pub cognitive: u16,
49}
50
51/// A direct importer referenced in target evidence.
52#[derive(Debug, Clone, Serialize)]
53#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
54pub struct DirectCallerEvidence {
55    /// File that directly imports the target.
56    #[serde(serialize_with = "crate::serde_path::serialize")]
57    pub path: PathBuf,
58    /// Symbols imported from the target by this file.
59    #[serde(default, skip_serializing_if = "Vec::is_empty")]
60    pub symbols: Vec<DirectCallerSymbolEvidence>,
61}
62
63/// Symbol details for a direct importer.
64#[derive(Debug, Clone, Serialize)]
65#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
66pub struct DirectCallerSymbolEvidence {
67    /// Imported binding name.
68    pub imported: String,
69    /// Local binding name in the importing file.
70    pub local: String,
71    /// Whether the import is type-only.
72    pub type_only: bool,
73}
74
75/// A duplicate-code sibling referenced in target evidence.
76#[derive(Debug, Clone, Serialize)]
77#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
78pub struct CloneSiblingEvidence {
79    /// File containing the sibling clone instance.
80    #[serde(serialize_with = "crate::serde_path::serialize")]
81    pub path: PathBuf,
82    /// 1-based start line of the sibling clone.
83    pub start_line: usize,
84    /// 1-based end line of the sibling clone.
85    pub end_line: usize,
86    /// Stable duplicate-group handle, matching `dupes --trace dup:<id>`.
87    pub fingerprint: String,
88}
89
90/// Suggested action attached to a [`ComplexityViolation`].
91///
92/// Each complexity finding carries an array of these on the JSON wire
93/// (`findings[].actions[]`). The action selector in
94/// `crates/cli/src/report/json.rs::build_health_finding_actions` picks the
95/// primary action based on which thresholds triggered the finding and the
96/// bucketed coverage tier. See [`HealthFindingActionType`] for the full
97/// discriminant list.
98///
99/// `note`, `comment`, and `placement` are populated per-variant: refactor
100/// actions carry a `note`, suppress-line / suppress-file actions carry
101/// `comment` plus `placement`, and the coverage-leaning actions
102/// (`add-tests`, `increase-coverage`) carry only `note`.
103///
104/// [`ComplexityViolation`]: ../../fallow-cli/src/health_types/scores.rs
105#[derive(Debug, Clone, Serialize)]
106#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
107pub struct HealthFindingAction {
108    /// Action type identifier. A single finding's `actions` array can carry
109    /// MULTIPLE entries of different types: e.g., a finding that exceeded
110    /// both cyclomatic and CRAP at `coverage_tier`: partial will get BOTH
111    /// `increase-coverage` AND `refactor-function`, plus `suppress-line`.
112    /// Consumers that select a single action should treat the FIRST
113    /// non-`suppress-{line,file}` action as primary. `add-tests` is emitted
114    /// when CRAP triggered the finding, the function has no test coverage
115    /// (`coverage_tier`: none), and full coverage can bring CRAP below
116    /// `max_crap_threshold` (cyclomatic < threshold, since CRAP bottoms out
117    /// at CC at 100% coverage). `increase-coverage` is emitted when CRAP
118    /// triggered the finding, some coverage exists (`coverage_tier`: partial
119    /// or high), and full coverage can bring CRAP below `max_crap_threshold`;
120    /// the description steers toward targeted branch coverage rather than
121    /// scaffolding new tests. `refactor-function` is emitted when
122    /// cyclomatic/cognitive triggered the finding, when full coverage still
123    /// cannot bring CRAP below `max_crap_threshold` (cyclomatic >=
124    /// threshold), or as a secondary action when cyclomatic is within the
125    /// configured `health.crapRefactorBand` of the cyclomatic threshold AND
126    /// cognitive is at or above `max_cognitive_threshold / 2` (the cognitive
127    /// floor suppresses false positives on flat type-tag dispatchers and JSX
128    /// render maps where high cyclomatic comes from a single switch with
129    /// near-zero cognitive load). `suppress-file` is emitted instead of
130    /// `suppress-line` for
131    /// synthetic Angular `<template>` findings on `.html` files, because
132    /// line-suppression comments cannot be expressed in HTML; the `comment`
133    /// field carries `<!-- fallow-ignore-file complexity -->` and
134    /// `placement` is `top-of-template`.
135    #[serde(rename = "type")]
136    pub kind: HealthFindingActionType,
137    /// Whether `fallow fix` can auto-apply this action. Today every health
138    /// finding action is manual, but the field is non-singleton so a future
139    /// auto-applier (e.g., an LLM-driven `refactor-function` worker) does
140    /// not need a schema change.
141    pub auto_fixable: bool,
142    /// Human-readable description of the action.
143    pub description: String,
144    /// Additional context (e.g., the canonical CRAP formula, or a hint
145    /// about which branch type to extract). Present on most action types;
146    /// dropped only when the description carries the full ask.
147    #[serde(default, skip_serializing_if = "Option::is_none")]
148    pub note: Option<String>,
149    /// The inline comment to insert (e.g.,
150    /// `// fallow-ignore-next-line complexity` or
151    /// `<!-- fallow-ignore-file complexity -->`). Present on
152    /// `suppress-line` and `suppress-file` action variants.
153    #[serde(default, skip_serializing_if = "Option::is_none")]
154    pub comment: Option<String>,
155    /// Where to insert the suppress comment
156    /// (e.g., `above-function-declaration`, `above-angular-decorator`,
157    /// `above-component-worst-method`, or `top-of-template`). Present on
158    /// `suppress-line` and `suppress-file` action variants.
159    #[serde(default, skip_serializing_if = "Option::is_none")]
160    pub placement: Option<String>,
161    /// Project-relative path the action should target when the finding's
162    /// remediation lives in a different file from where the finding is
163    /// anchored. Currently populated on the `increase-coverage` action for
164    /// synthetic Angular `<template>` findings whose CRAP is inherited from
165    /// the owning `.component.ts`: the action points at the component file
166    /// (where the user actually adds tests) rather than the `.html` template
167    /// (where the finding is anchored but which is not directly testable).
168    /// Absent when the action's target is the finding's own file.
169    #[serde(default, skip_serializing_if = "Option::is_none")]
170    pub target_path: Option<String>,
171}
172
173/// Discriminant for [`HealthFindingAction::kind`]. Mirrors the action types
174/// emitted by `build_health_finding_actions`. A single finding's `actions`
175/// array may carry multiple entries of different types: a finding that
176/// exceeded both cyclomatic and CRAP at `coverage_tier: partial` will get
177/// BOTH `increase-coverage` AND `refactor-function`, plus the trailing
178/// `suppress-line`.
179#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
180#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
181#[serde(rename_all = "kebab-case")]
182pub enum HealthFindingActionType {
183    /// Refactor the function to reduce complexity. Emitted when
184    /// cyclomatic/cognitive triggered the finding, when full coverage
185    /// still cannot bring CRAP below `max_crap_threshold`, or as a
186    /// secondary action when cyclomatic is within the configured
187    /// `health.crapRefactorBand` of the cyclomatic threshold AND cognitive
188    /// is at or above the cognitive floor.
189    RefactorFunction,
190    /// Add tests for a CRAP-triggered finding whose coverage tier is
191    /// `none` (no test path reaches the function).
192    AddTests,
193    /// Increase test coverage for a CRAP-triggered finding whose coverage
194    /// tier is `partial` or `high` (some test path exists; add targeted
195    /// assertions for uncovered branches).
196    IncreaseCoverage,
197    /// Suppress with an HTML comment at the top of the template. Used for
198    /// synthetic Angular `<template>` findings on `.html` files where a
199    /// line suppression cannot be expressed.
200    SuppressFile,
201    /// Suppress with an inline `// fallow-ignore-next-line complexity`
202    /// comment above the function or Angular decorator.
203    SuppressLine,
204}
205
206/// Suggested action attached to a [`HotspotEntry`].
207///
208/// The action list always begins with `refactor-file` plus `add-tests`.
209/// Ownership-derived variants (`low-bus-factor`, `unowned-hotspot`,
210/// `ownership-drift`) are appended only when `--ownership` is active AND
211/// the corresponding signal fires for the hotspot.
212///
213/// [`HotspotEntry`]: ../../fallow-cli/src/health_types/scores.rs
214#[derive(Debug, Clone, Serialize)]
215#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
216pub struct HotspotAction {
217    /// Action type identifier.
218    #[serde(rename = "type")]
219    pub kind: HotspotActionType,
220    /// Whether `fallow fix` can auto-apply this action. Today every
221    /// hotspot action is manual.
222    pub auto_fixable: bool,
223    /// Human-readable description of the action.
224    pub description: String,
225    /// Additional context for the action. Absent on `low-bus-factor` when
226    /// the finding's description already carries the full ask (no
227    /// suggested reviewers and not a low-commit file).
228    #[serde(default, skip_serializing_if = "Option::is_none")]
229    pub note: Option<String>,
230    /// Suggested CODEOWNERS pattern. Present only on `unowned-hotspot`
231    /// actions. Derived per the [`heuristic`](Self::heuristic) field;
232    /// consumers should branch on [`heuristic`](Self::heuristic) rather
233    /// than assume a stable algorithm.
234    #[serde(default, skip_serializing_if = "Option::is_none")]
235    pub suggested_pattern: Option<String>,
236    /// Strategy used to derive [`suggested_pattern`](Self::suggested_pattern).
237    /// Reserved for future evolution (`codeowners-cluster`, etc.).
238    #[serde(default, skip_serializing_if = "Option::is_none")]
239    pub heuristic: Option<HotspotActionHeuristic>,
240}
241
242/// Discriminant for [`HotspotAction::kind`].
243#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
244#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
245#[serde(rename_all = "kebab-case")]
246pub enum HotspotActionType {
247    /// Refactor the hotspot file (high complexity plus frequent change).
248    RefactorFile,
249    /// Add test coverage to reduce change risk on the hotspot file.
250    AddTests,
251    /// Bus factor of 1: a single recent contributor owns the file.
252    /// Emitted only with `--ownership`.
253    LowBusFactor,
254    /// Hotspot matches no CODEOWNERS rule (a rules file exists but no
255    /// pattern matches). Emitted only with `--ownership`.
256    UnownedHotspot,
257    /// Ownership has drifted from the original author to a new top
258    /// contributor. Emitted only with `--ownership`.
259    OwnershipDrift,
260}
261
262/// Strategy discriminant for the suggested CODEOWNERS pattern attached to
263/// an `unowned-hotspot` action.
264#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
265#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
266#[serde(rename_all = "kebab-case")]
267pub enum HotspotActionHeuristic {
268    /// Suggest the deepest directory containing the file (e.g.,
269    /// `/src/api/users/`). Keeps the suggestion reviewable while staying
270    /// a directory pattern rather than a per-file rule.
271    DirectoryDeepest,
272}
273
274/// Suggested action attached to a [`RefactoringTarget`].
275///
276/// The list always begins with `apply-refactoring`. A trailing
277/// `suppress-line` is appended only when the target carries `evidence`
278/// linking to specific functions (e.g., `extract_complex_functions`,
279/// `add_test_coverage`).
280///
281/// Unlike [`HealthFindingAction`], the `suppress-line` variant emitted
282/// here does NOT carry a `placement` field: the parent
283/// [`RefactoringTarget`] points at a file (not a specific function
284/// declaration site), so a per-line placement hint would have no
285/// referent. Consumers that want the placement metadata should follow
286/// the target's `evidence.complex_functions` back to the matching
287/// `ComplexityViolation` and read placement from THAT action instead.
288///
289/// [`RefactoringTarget`]: ../../fallow-cli/src/health_types/targets.rs
290#[derive(Debug, Clone, Serialize)]
291#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
292pub struct RefactoringTargetAction {
293    /// Action type identifier.
294    #[serde(rename = "type")]
295    pub kind: RefactoringTargetActionType,
296    /// Whether `fallow fix` can auto-apply this action. Today both
297    /// variants are manual.
298    pub auto_fixable: bool,
299    /// Human-readable description of the action. For `apply-refactoring`
300    /// this is the target's own `recommendation` string; for
301    /// `suppress-line` it is the suppression prompt.
302    pub description: String,
303    /// Recommendation category for `apply-refactoring` actions. Mirrors
304    /// the parent target's
305    /// [`category`](../../fallow-cli/src/health_types/targets.rs.html)
306    /// field so consumers can route on the action alone.
307    #[serde(default, skip_serializing_if = "Option::is_none")]
308    pub category: Option<String>,
309    /// The inline comment to insert. Present on `suppress-line` actions
310    /// when evidence exists.
311    #[serde(default, skip_serializing_if = "Option::is_none")]
312    pub comment: Option<String>,
313}
314
315/// Discriminant for [`RefactoringTargetAction::kind`].
316#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
317#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
318#[serde(rename_all = "kebab-case")]
319pub enum RefactoringTargetActionType {
320    /// Apply the recommended refactoring (extract, split, decouple, etc.).
321    ApplyRefactoring,
322    /// Suppress the underlying complexity finding with an inline comment.
323    SuppressLine,
324}
325
326/// Suggested action attached to an [`UntestedFile`] coverage-gap finding.
327///
328/// `build_untested_file_actions` emits a two-entry array on every
329/// untested-file item: an `add-tests` primary action (scaffold tests for
330/// the runtime file) and a `suppress-file` action
331/// (`// fallow-ignore-file coverage-gaps`). Both variants share the same
332/// struct shape; the field that is populated (`note` for `add-tests`,
333/// `comment` for `suppress-file`) depends on the `kind`.
334///
335/// [`UntestedFile`]: ../../fallow-cli/src/health_types/coverage.rs
336#[derive(Debug, Clone, Serialize)]
337#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
338pub struct UntestedFileAction {
339    /// Action type identifier.
340    #[serde(rename = "type")]
341    pub kind: UntestedFileActionType,
342    /// Whether `fallow fix` can auto-apply this action. Today both
343    /// variants are manual.
344    pub auto_fixable: bool,
345    /// Human-readable description of the action.
346    pub description: String,
347    /// Additional context for the `add-tests` variant (explains why no
348    /// test path reaches this file). Absent on `suppress-file`.
349    #[serde(default, skip_serializing_if = "Option::is_none")]
350    pub note: Option<String>,
351    /// The file-level comment to insert. Present on `suppress-file`
352    /// (`// fallow-ignore-file coverage-gaps`). Absent on `add-tests`.
353    #[serde(default, skip_serializing_if = "Option::is_none")]
354    pub comment: Option<String>,
355}
356
357/// Discriminant for [`UntestedFileAction::kind`]. Mirrors the action types
358/// emitted by `build_untested_file_actions`.
359#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
360#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
361#[serde(rename_all = "kebab-case")]
362pub enum UntestedFileActionType {
363    /// Scaffold tests that exercise the runtime file.
364    AddTests,
365    /// Suppress coverage-gap reporting for this file with a file-level
366    /// comment.
367    SuppressFile,
368}
369
370/// Suggested action attached to an [`UntestedExport`] coverage-gap
371/// finding.
372///
373/// `build_untested_export_actions` emits a two-entry array on every
374/// untested-export item: an `add-test-import` primary action (import the
375/// export from a test-reachable module) and a `suppress-file` action
376/// (`// fallow-ignore-file coverage-gaps`). The export-specific variant
377/// `add-test-import` reflects that a test-reachable reference chain, not
378/// just any test coverage, is what closes the gap.
379///
380/// [`UntestedExport`]: ../../fallow-cli/src/health_types/coverage.rs
381#[derive(Debug, Clone, Serialize)]
382#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
383pub struct UntestedExportAction {
384    /// Action type identifier.
385    #[serde(rename = "type")]
386    pub kind: UntestedExportActionType,
387    /// Whether `fallow fix` can auto-apply this action. Today both
388    /// variants are manual.
389    pub auto_fixable: bool,
390    /// Human-readable description of the action.
391    pub description: String,
392    /// Additional context for the `add-test-import` variant (explains the
393    /// runtime-reachable / test-unreachable asymmetry). Absent on
394    /// `suppress-file`.
395    #[serde(default, skip_serializing_if = "Option::is_none")]
396    pub note: Option<String>,
397    /// The file-level comment to insert. Present on `suppress-file`
398    /// (`// fallow-ignore-file coverage-gaps`). Absent on
399    /// `add-test-import`.
400    #[serde(default, skip_serializing_if = "Option::is_none")]
401    pub comment: Option<String>,
402}
403
404/// Discriminant for [`UntestedExportAction::kind`]. Mirrors the action
405/// types emitted by `build_untested_export_actions`.
406#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
407#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
408#[serde(rename_all = "kebab-case")]
409pub enum UntestedExportActionType {
410    /// Import and exercise the export from a test-reachable module.
411    AddTestImport,
412    /// Suppress coverage-gap reporting for the export's file with a
413    /// file-level comment.
414    SuppressFile,
415}
fallow_types/output_health.rs

fallow_types/
output_health.rs
