fallow_output/
health_report.rs

1//! Top-level health report contract.
2
3use crate::{
4    CoverageGaps, CoverageIntelligenceReport, CssAnalyticsReport, FileHealthScore,
5    FrameworkHealthDiagnostics, HealthActionsMeta, HealthFinding, HealthScore, HealthSummary,
6    HealthTrend, HotspotFinding, HotspotSummary, LargeFunctionEntry, RefactoringTargetFinding,
7    RuntimeCoverageReport, StylingHealth, TargetThresholds, ThresholdOverrideState, VitalSigns,
8};
9use fallow_types::output_dead_code::PropDrillingChainFinding;
10
11/// Result of complexity analysis for reporting.
12#[derive(Debug, Clone, Default, serde::Serialize)]
13#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
14pub struct HealthReport {
15    /// Functions and synthetic template entries exceeding complexity
16    /// thresholds, sorted by the --sort criteria. Each entry wraps its
17    /// inner `ComplexityViolation` payload (flattened on the wire) with
18    /// the typed `actions` list and an optional audit-mode `introduced`
19    /// flag.
20    pub findings: Vec<HealthFinding>,
21    /// Summary statistics.
22    pub summary: HealthSummary,
23    /// Configured threshold override states. Entries are emitted for active
24    /// exceptions, stale exceptions, and full-run no-match cleanup hints.
25    #[serde(default, skip_serializing_if = "Vec::is_empty")]
26    pub threshold_overrides: Vec<ThresholdOverrideState>,
27    /// Project-wide vital signs (always computed from available data).
28    #[serde(default, skip_serializing_if = "Option::is_none")]
29    pub vital_signs: Option<VitalSigns>,
30    /// Project-wide health score (only populated with `--score`).
31    #[serde(default, skip_serializing_if = "Option::is_none")]
32    pub health_score: Option<HealthScore>,
33    /// Per-file health scores. Only present when --file-scores is used. Sorted
34    /// by risk-aware triage concern, combining low maintainability and high
35    /// CRAP risk. Zero-function files (barrels) are excluded by default.
36    #[serde(default, skip_serializing_if = "Vec::is_empty")]
37    pub file_scores: Vec<FileHealthScore>,
38    /// Static coverage gaps.
39    ///
40    /// Populated when coverage gaps are explicitly requested, or when the
41    /// top-level `health` command allows config severity to surface them in the
42    /// default report.
43    #[serde(default, skip_serializing_if = "Option::is_none")]
44    pub coverage_gaps: Option<CoverageGaps>,
45    /// Located prop-drilling chains (React/Preact props forwarded unchanged
46    /// through 3+ pass-through components). Only present when the opt-in
47    /// `prop-drilling` rule is enabled (it defaults to off). Each entry carries
48    /// the source, every pass-through hop, and the consumer with file + line +
49    /// component, so CI / an agent can act. Surfaced alongside hotspots as a
50    /// graph-derived health signal.
51    #[serde(default, skip_serializing_if = "Vec::is_empty")]
52    pub prop_drilling_chains: Vec<PropDrillingChainFinding>,
53    /// Hotspot entries combining git churn with complexity. Only present when
54    /// --hotspots is used. Sorted by score descending (highest risk first).
55    /// Each entry wraps its inner `HotspotEntry` payload (flattened on the
56    /// wire) with a typed `actions` list.
57    #[serde(default, skip_serializing_if = "Vec::is_empty")]
58    pub hotspots: Vec<HotspotFinding>,
59    /// Hotspot analysis summary (only set with `--hotspots`).
60    #[serde(default, skip_serializing_if = "Option::is_none")]
61    pub hotspot_summary: Option<HotspotSummary>,
62    /// Runtime coverage findings from the paid sidecar (only populated with
63    /// `--runtime-coverage`).
64    #[serde(default, skip_serializing_if = "Option::is_none")]
65    pub runtime_coverage: Option<RuntimeCoverageReport>,
66    /// Combined coverage, runtime, complexity, and change-scope verdicts.
67    #[serde(default, skip_serializing_if = "Option::is_none")]
68    pub coverage_intelligence: Option<CoverageIntelligenceReport>,
69    /// Functions exceeding 60 LOC (very high risk). Only present when unit size
70    /// very-high-risk bin >= 3%. Sorted by line count descending.
71    #[serde(default, skip_serializing_if = "Vec::is_empty")]
72    pub large_functions: Vec<LargeFunctionEntry>,
73    /// Ranked refactoring recommendations. Only present when --targets is used.
74    /// Sorted by efficiency (priority/effort) descending. Each entry wraps
75    /// its inner `RefactoringTarget` payload (flattened on the wire) with
76    /// a typed `actions` list.
77    #[serde(default, skip_serializing_if = "Vec::is_empty")]
78    pub targets: Vec<RefactoringTargetFinding>,
79    /// Adaptive thresholds used for target scoring (only set with `--targets`).
80    #[serde(default, skip_serializing_if = "Option::is_none")]
81    pub target_thresholds: Option<TargetThresholds>,
82    /// Health trend comparison against a previous snapshot (only set with `--trend`).
83    #[serde(default, skip_serializing_if = "Option::is_none")]
84    pub health_trend: Option<HealthTrend>,
85    /// Audit breadcrumb explaining systemic action-array adjustments. Present
86    /// only when at least one adjustment was made (e.g., health finding
87    /// suppression hints omitted because a baseline is active). When --group-by
88    /// is active, each entry of `groups` may carry its own `actions_meta`
89    /// describing the same omission so per-group consumers do not need to walk
90    /// back to the report root.
91    #[serde(default, skip_serializing_if = "Option::is_none")]
92    pub actions_meta: Option<HealthActionsMeta>,
93    /// Optional framework-specific detector coverage. Present only when the
94    /// health run already needed the dead-code analysis output.
95    #[serde(default, skip_serializing_if = "Option::is_none")]
96    pub framework_health: Option<FrameworkHealthDiagnostics>,
97    /// Structural CSS analytics (specificity hotspots, `!important` density,
98    /// over-complex selectors, deep nesting). Present only with `--css`.
99    #[serde(default, skip_serializing_if = "Option::is_none")]
100    pub css_analytics: Option<CssAnalyticsReport>,
101    /// Styling-health score and letter grade: a SECOND health axis derived from
102    /// the CSS analytics (the design-system axis), orthogonal to the JS/TS code
103    /// `health_score`. Present only with `--css` (the same condition as
104    /// `css_analytics`), so a plain `fallow health` run is byte-unchanged. The
105    /// code score is never affected by this field.
106    #[serde(default, skip_serializing_if = "Option::is_none")]
107    pub styling_health: Option<StylingHealth>,
108    /// Per-file top render fan-in for the descriptive human drill-down only.
109    #[serde(skip)]
110    pub render_fan_in_top: rustc_hash::FxHashMap<std::path::PathBuf, (String, u32)>,
111}
112
113#[cfg(test)]
114mod tests {
115    use super::*;
116
117    #[test]
118    fn health_report_skips_empty_collections() {
119        let report = HealthReport::default();
120        let json = serde_json::to_string(&report).expect("health report should serialize");
121        assert!(!json.contains("file_scores"));
122        assert!(!json.contains("hotspots"));
123        assert!(!json.contains("hotspot_summary"));
124        assert!(!json.contains("runtime_coverage"));
125        assert!(!json.contains("coverage_intelligence"));
126        assert!(!json.contains("large_functions"));
127        assert!(!json.contains("targets"));
128        assert!(!json.contains("threshold_overrides"));
129        assert!(!json.contains("vital_signs"));
130        assert!(!json.contains("health_score"));
131        assert!(!json.contains("framework_health"));
132        assert!(!json.contains("css_analytics"));
133        assert!(!json.contains("styling_health"));
134    }
135
136    #[test]
137    fn health_score_none_skipped_in_report() {
138        let report = HealthReport::default();
139        let json = serde_json::to_string(&report).expect("health report should serialize");
140        assert!(!json.contains("health_score"));
141    }
142}
fallow_output/health_report.rs

fallow_output/
health_report.rs
