fallow_cli/health_types/
grouped.rs

1//! Per-group health output for `--group-by`.
2//!
3//! When health is invoked with `--group-by package` (or any other grouping
4//! mode), the orchestrator partitions the project's files by the resolver and
5//! emits one [`HealthGroup`] per bucket. Each group carries its own
6//! [`VitalSigns`] and [`HealthScore`] computed from the files in that group
7//! alone, plus the per-file output (findings, file scores, hotspots, large
8//! functions, refactoring targets) restricted to the same subset.
9
10use serde::Serialize;
11
12use crate::health_types::{
13    FileHealthScore, HealthActionsMeta, HealthFinding, HealthScore, HotspotFinding,
14    LargeFunctionEntry, RefactoringTargetFinding, VitalSigns,
15};
16
17/// A health report scoped to a single group.
18///
19/// `key` is the group label produced by the resolver (workspace package name,
20/// CODEOWNERS owner, directory, or section). `owners` is populated only for
21/// `--group-by section` (mirrors dead-code grouped output).
22///
23/// Per-group `vital_signs` and `health_score` are recomputed from the
24/// files in the group, so they answer "what is the health of workspace X" in
25/// a single invocation. `files_analyzed` and `functions_above_threshold`
26/// summarise the subset for parity with the project-level
27/// [`crate::health_types::HealthSummary`].
28#[derive(Debug, Clone, Serialize)]
29#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
30pub struct HealthGroup {
31    /// Group identifier produced by the resolver. For 'package' grouping:
32    /// workspace package name (e.g. '@scope/app-a') or '(root)' for files
33    /// outside any workspace. For 'owner' grouping: the CODEOWNERS team. For
34    /// 'directory' grouping: the top-level directory prefix. For 'section'
35    /// grouping: the GitLab CODEOWNERS section name, or '(no section)' /
36    /// '(unowned)' for unmatched files.
37    pub key: String,
38    /// Section default owners (GitLab CODEOWNERS `[Section] @owner1 @owner2`).
39    /// Present only when grouped_by is 'section'.
40    #[serde(skip_serializing_if = "Option::is_none")]
41    pub owners: Option<Vec<String>>,
42    /// Files participating in this group after workspace and ignore filters.
43    pub files_analyzed: usize,
44    /// Number of findings in this group, mirroring the project-level
45    /// `summary.functions_above_threshold` semantics post-baseline /
46    /// post-`--top` truncation. When `--top` was supplied this reflects the
47    /// rendered finding count, not the un-truncated total.
48    pub functions_above_threshold: usize,
49    /// Per-group vital signs recomputed from the files in this group. Absent
50    /// when --score-only suppressed top-level vital signs.
51    #[serde(skip_serializing_if = "Option::is_none")]
52    pub vital_signs: Option<VitalSigns>,
53    /// Per-group health score recomputed from the per-group vital signs. Absent
54    /// when --score was not requested.
55    #[serde(skip_serializing_if = "Option::is_none")]
56    pub health_score: Option<HealthScore>,
57    /// Findings restricted to files in this group. Each entry is the typed
58    /// [`HealthFinding`] wrapper around a
59    /// [`ComplexityViolation`](crate::health_types::ComplexityViolation)
60    /// payload.
61    #[serde(default, skip_serializing_if = "Vec::is_empty")]
62    pub findings: Vec<HealthFinding>,
63    /// File scores restricted to files in this group.
64    #[serde(default, skip_serializing_if = "Vec::is_empty")]
65    pub file_scores: Vec<FileHealthScore>,
66    /// Hotspots restricted to files in this group. Each entry is the typed
67    /// [`HotspotFinding`] wrapper around a
68    /// [`HotspotEntry`](crate::health_types::HotspotEntry) payload.
69    #[serde(default, skip_serializing_if = "Vec::is_empty")]
70    pub hotspots: Vec<HotspotFinding>,
71    /// Large functions in files belonging to this group.
72    #[serde(default, skip_serializing_if = "Vec::is_empty")]
73    pub large_functions: Vec<LargeFunctionEntry>,
74    /// Refactoring targets in files belonging to this group. Each entry is
75    /// the typed [`RefactoringTargetFinding`] wrapper around a
76    /// [`RefactoringTarget`](crate::health_types::RefactoringTarget)
77    /// payload.
78    #[serde(default, skip_serializing_if = "Vec::is_empty")]
79    pub targets: Vec<RefactoringTargetFinding>,
80    /// Auditable breadcrumb recording why `suppress-line` action hints
81    /// were omitted from this group's findings. Mirrors the project-level
82    /// `HealthReport.actions_meta`; populated at construction time when the
83    /// per-group [`HealthActionContext`](crate::health_types::HealthActionContext)
84    /// suppresses inline hints.
85    #[serde(default, skip_serializing_if = "Option::is_none")]
86    pub actions_meta: Option<HealthActionsMeta>,
87}
88
89/// Wrapper carrying the resolver mode label alongside the partitioned groups.
90///
91/// Stored on `crate::health::HealthResult` when `--group-by` is active and
92/// consumed by formatters that either render grouped data directly or annotate
93/// per-finding machine output with the group key.
94#[derive(Debug, Clone)]
95pub struct HealthGrouping {
96    /// Resolver mode label (`"package"`, `"owner"`, `"directory"`, `"section"`).
97    pub mode: &'static str,
98    /// Groups in the same order the resolver produced them.
99    pub groups: Vec<HealthGroup>,
100}
fallow_cli/health_types/grouped.rs

fallow_cli/health_types/
grouped.rs
