fallow_cli/health_types/
mod.rs

1//! Health / complexity analysis report types.
2//!
3//! Separated from the `health` command module so that report formatters
4//! (which are compiled as part of both the lib and bin targets) can
5//! reference these types without pulling in binary-only dependencies.
6
7mod coverage;
8mod finding;
9mod grouped;
10mod runtime_coverage;
11mod scores;
12mod targets;
13mod trends;
14mod vital_signs;
15
16pub use coverage::*;
17pub use finding::*;
18pub use grouped::*;
19pub use runtime_coverage::*;
20pub use scores::*;
21pub use targets::*;
22pub use trends::*;
23pub use vital_signs::*;
24
25/// Detailed timing breakdown for the health pipeline.
26///
27/// Only populated when `--performance` is passed.
28#[derive(Debug, Clone, serde::Serialize)]
29pub struct HealthTimings {
30    pub config_ms: f64,
31    pub discover_ms: f64,
32    pub parse_ms: f64,
33    /// Summed wall-clock time of the actual AST parses across all rayon
34    /// workers (the parse stage's CPU cost). `parse_ms` is the stage's
35    /// wall-clock time. Observational and non-deterministic; do not assert
36    /// against it. `0.0` when `shared_parse` is true (parse was reused).
37    pub parse_cpu_ms: f64,
38    pub complexity_ms: f64,
39    pub file_scores_ms: f64,
40    pub git_churn_ms: f64,
41    pub git_churn_cache_hit: bool,
42    pub hotspots_ms: f64,
43    pub duplication_ms: f64,
44    pub targets_ms: f64,
45    pub total_ms: f64,
46    /// True when discover + parse were reused from the upstream dead-code
47    /// (check) pass in combined mode, so their timings are `0.0` here and
48    /// the cost is attributed to the `Pipeline Performance` table instead.
49    /// The renderer shows those two stages as `(measured above)`.
50    pub shared_parse: bool,
51}
52
53/// Auditable breadcrumb recording when health-finding `suppress-line`
54/// action hints were omitted from the report.
55///
56/// Set at construction time on [`HealthReport::actions_meta`] (and on
57/// each [`HealthGroup::actions_meta`](crate::health_types::HealthGroup)
58/// when grouped) by the report builder, derived from the active
59/// [`HealthActionContext`]. Lets consumers see "where did the
60/// suppress-line hints go?" without having to grep the config or CLI
61/// history.
62///
63/// Stable `reason` codes:
64/// - `baseline-active`: a baseline is active and inline ignores would
65///   become dead annotations once the baseline regenerates.
66/// - `config-disabled`: `health.suggestInlineSuppression` is `false`.
67/// - `unspecified`: the caller did not record a reason.
68#[derive(Debug, Clone, serde::Serialize)]
69#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
70pub struct HealthActionsMeta {
71    /// Always `true` when the breadcrumb is emitted. Absent from the wire
72    /// when no suppression occurred.
73    pub suppression_hints_omitted: bool,
74    /// Stable code describing why the suppression occurred.
75    pub reason: String,
76    /// Scope of the omission. Always `"health-findings"` today.
77    pub scope: String,
78}
79
80/// Result of complexity analysis for reporting.
81#[derive(Debug, Clone, serde::Serialize)]
82#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
83pub struct HealthReport {
84    /// Functions and synthetic template entries exceeding complexity
85    /// thresholds, sorted by the --sort criteria. Each entry wraps its
86    /// inner [`ComplexityViolation`] payload (flattened on the wire) with
87    /// the typed `actions` list and an optional audit-mode `introduced`
88    /// flag.
89    pub findings: Vec<HealthFinding>,
90    /// Summary statistics.
91    pub summary: HealthSummary,
92    /// Project-wide vital signs (always computed from available data).
93    #[serde(default, skip_serializing_if = "Option::is_none")]
94    pub vital_signs: Option<VitalSigns>,
95    /// Project-wide health score (only populated with `--score`).
96    #[serde(default, skip_serializing_if = "Option::is_none")]
97    pub health_score: Option<HealthScore>,
98    /// Per-file health scores. Only present when --file-scores is used. Sorted
99    /// by maintainability_index ascending (worst first). Zero-function files
100    /// (barrels) are excluded by default.
101    #[serde(default, skip_serializing_if = "Vec::is_empty")]
102    pub file_scores: Vec<FileHealthScore>,
103    /// Static coverage gaps.
104    ///
105    /// Populated when coverage gaps are explicitly requested, or when the
106    /// top-level `health` command allows config severity to surface them in the
107    /// default report.
108    #[serde(default, skip_serializing_if = "Option::is_none")]
109    pub coverage_gaps: Option<CoverageGaps>,
110    /// Hotspot entries combining git churn with complexity. Only present when
111    /// --hotspots is used. Sorted by score descending (highest risk first).
112    /// Each entry wraps its inner [`HotspotEntry`] payload (flattened on the
113    /// wire) with a typed `actions` list.
114    #[serde(default, skip_serializing_if = "Vec::is_empty")]
115    pub hotspots: Vec<HotspotFinding>,
116    /// Hotspot analysis summary (only set with `--hotspots`).
117    #[serde(default, skip_serializing_if = "Option::is_none")]
118    pub hotspot_summary: Option<HotspotSummary>,
119    /// Runtime coverage findings from the paid sidecar (only populated with
120    /// `--runtime-coverage`).
121    #[serde(default, skip_serializing_if = "Option::is_none")]
122    pub runtime_coverage: Option<RuntimeCoverageReport>,
123    /// Functions exceeding 60 LOC (very high risk). Only present when unit size
124    /// very-high-risk bin >= 3%. Sorted by line count descending.
125    #[serde(default, skip_serializing_if = "Vec::is_empty")]
126    pub large_functions: Vec<LargeFunctionEntry>,
127    /// Ranked refactoring recommendations. Only present when --targets is used.
128    /// Sorted by efficiency (priority/effort) descending. Each entry wraps
129    /// its inner [`RefactoringTarget`] payload (flattened on the wire) with
130    /// a typed `actions` list.
131    #[serde(default, skip_serializing_if = "Vec::is_empty")]
132    pub targets: Vec<RefactoringTargetFinding>,
133    /// Adaptive thresholds used for target scoring (only set with `--targets`).
134    #[serde(default, skip_serializing_if = "Option::is_none")]
135    pub target_thresholds: Option<TargetThresholds>,
136    /// Health trend comparison against a previous snapshot (only set with `--trend`).
137    #[serde(default, skip_serializing_if = "Option::is_none")]
138    pub health_trend: Option<HealthTrend>,
139    /// Audit breadcrumb explaining systemic action-array adjustments. Present
140    /// only when at least one adjustment was made (e.g., health finding
141    /// suppression hints omitted because a baseline is active). When --group-by
142    /// is active, each entry of `groups` may carry its own `actions_meta`
143    /// describing the same omission so per-group consumers do not need to walk
144    /// back to the report root.
145    #[serde(default, skip_serializing_if = "Option::is_none")]
146    pub actions_meta: Option<HealthActionsMeta>,
147}
148
149#[cfg(test)]
150#[expect(
151    clippy::derivable_impls,
152    reason = "test-only Default with custom HealthSummary thresholds (20/15)"
153)]
154impl Default for HealthReport {
155    fn default() -> Self {
156        Self {
157            findings: vec![],
158            summary: HealthSummary::default(),
159            vital_signs: None,
160            health_score: None,
161            file_scores: vec![],
162            coverage_gaps: None,
163            hotspots: vec![],
164            hotspot_summary: None,
165            runtime_coverage: None,
166            large_functions: vec![],
167            targets: vec![],
168            target_thresholds: None,
169            health_trend: None,
170            actions_meta: None,
171        }
172    }
173}
174
175#[cfg(test)]
176mod tests {
177    use super::*;
178
179    #[test]
180    fn health_report_skips_empty_collections() {
181        let report = HealthReport::default();
182        let json = serde_json::to_string(&report).unwrap();
183        // Empty vecs should be omitted due to skip_serializing_if
184        assert!(!json.contains("file_scores"));
185        assert!(!json.contains("hotspots"));
186        assert!(!json.contains("hotspot_summary"));
187        assert!(!json.contains("runtime_coverage"));
188        assert!(!json.contains("large_functions"));
189        assert!(!json.contains("targets"));
190        assert!(!json.contains("vital_signs"));
191        assert!(!json.contains("health_score"));
192    }
193
194    #[test]
195    fn health_score_none_skipped_in_report() {
196        let report = HealthReport::default();
197        let json = serde_json::to_string(&report).unwrap();
198        assert!(!json.contains("health_score"));
199    }
200}
fallow_cli/health_types/mod.rs

fallow_cli/health_types/
mod.rs
