fallow_cli/health_types/
targets.rs

1//! Refactoring target types, recommendations, effort estimates, and evidence.
2
3/// Adaptive thresholds used for refactoring target scoring.
4///
5/// Derived from the project's metric distribution (percentile-based with floors).
6/// Exposed in JSON output so consumers can interpret scores in context.
7#[derive(Debug, Clone, serde::Serialize)]
8#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
9#[allow(
10    clippy::struct_field_names,
11    reason = "triggered in bin but not lib — #[expect] would be unfulfilled in lib"
12)]
13pub struct TargetThresholds {
14    /// Fan-in saturation point for priority formula (p95, floor 5).
15    pub fan_in_p95: f64,
16    /// Fan-in moderate threshold for contributing factors (p75, floor 3).
17    pub fan_in_p75: f64,
18    /// Fan-out saturation point for priority formula (p95, floor 8).
19    pub fan_out_p95: f64,
20    /// Fan-out high threshold for rules and contributing factors (p90, floor 5).
21    pub fan_out_p90: usize,
22}
23
24/// Category of refactoring recommendation.
25#[derive(Debug, Clone, serde::Serialize)]
26#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
27#[serde(rename_all = "snake_case")]
28pub enum RecommendationCategory {
29    /// Actively-changing file with growing complexity — highest urgency.
30    UrgentChurnComplexity,
31    /// File participates in an import cycle with significant blast radius.
32    BreakCircularDependency,
33    /// High fan-in + high complexity — changes here ripple widely.
34    SplitHighImpact,
35    /// Majority of exports are unused — reduce surface area.
36    RemoveDeadCode,
37    /// Contains functions with very high cognitive complexity.
38    ExtractComplexFunctions,
39    /// Excessive imports reduce testability and increase coupling.
40    ExtractDependencies,
41    /// Multiple complex functions lack test dependency path.
42    AddTestCoverage,
43}
44
45impl RecommendationCategory {
46    /// Human-readable label for terminal output.
47    #[must_use]
48    pub const fn label(&self) -> &'static str {
49        match self {
50            Self::UrgentChurnComplexity => "churn+complexity",
51            Self::BreakCircularDependency => "circular dependency",
52            Self::SplitHighImpact => "high impact",
53            Self::RemoveDeadCode => "dead code",
54            Self::ExtractComplexFunctions => "complexity",
55            Self::ExtractDependencies => "coupling",
56            Self::AddTestCoverage => "untested risk",
57        }
58    }
59
60    /// Machine-parseable label for compact output (no spaces).
61    #[must_use]
62    pub const fn compact_label(&self) -> &'static str {
63        match self {
64            Self::UrgentChurnComplexity => "churn_complexity",
65            Self::BreakCircularDependency => "circular_dep",
66            Self::SplitHighImpact => "high_impact",
67            Self::RemoveDeadCode => "dead_code",
68            Self::ExtractComplexFunctions => "complexity",
69            Self::ExtractDependencies => "coupling",
70            Self::AddTestCoverage => "untested_risk",
71        }
72    }
73}
74
75/// A contributing factor that triggered or strengthened a recommendation.
76#[derive(Debug, Clone, serde::Serialize)]
77#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
78pub struct ContributingFactor {
79    /// Metric name (matches JSON field names: `"fan_in"`, `"dead_code_ratio"`, etc.).
80    pub metric: &'static str,
81    /// Raw metric value for programmatic use.
82    pub value: f64,
83    /// Threshold that was exceeded.
84    pub threshold: f64,
85    /// Human-readable explanation.
86    pub detail: String,
87}
88
89/// A ranked refactoring recommendation for a file.
90///
91/// ## Priority Formula
92///
93/// ```text
94/// priority = min(density, 1) × 30 + hotspot_boost × 25 + dead_code × 20 + fan_in_norm × 15 + fan_out_norm × 10
95/// ```
96///
97/// Fan-in and fan-out normalization uses adaptive percentile-based thresholds
98/// (p95 of the project distribution, with floors) instead of fixed constants.
99///
100/// ## Efficiency (default sort)
101///
102/// ```text
103/// efficiency = priority / effort_numeric   (Low=1, Medium=2, High=3)
104/// ```
105///
106/// Surfaces quick wins: high-priority, low-effort targets rank first.
107/// Effort estimate for a refactoring target.
108#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
109#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
110#[serde(rename_all = "snake_case")]
111pub enum EffortEstimate {
112    /// Small file, few functions, low fan-in — quick to address.
113    Low,
114    /// Moderate size or coupling — needs planning.
115    Medium,
116    /// Large file, many functions, or high fan-in — significant effort.
117    High,
118}
119
120impl EffortEstimate {
121    /// Human-readable label for terminal output.
122    #[must_use]
123    pub const fn label(&self) -> &'static str {
124        match self {
125            Self::Low => "low",
126            Self::Medium => "medium",
127            Self::High => "high",
128        }
129    }
130
131    /// Numeric value for arithmetic (efficiency = priority / effort).
132    #[must_use]
133    pub const fn numeric(&self) -> f64 {
134        match self {
135            Self::Low => 1.0,
136            Self::Medium => 2.0,
137            Self::High => 3.0,
138        }
139    }
140}
141
142/// Confidence level for a refactoring recommendation.
143///
144/// Based on the data source reliability:
145/// - **High**: deterministic graph/AST analysis (dead code, circular deps, complexity)
146/// - **Medium**: heuristic thresholds (fan-in/fan-out coupling)
147/// - **Low**: depends on git history quality (churn-based recommendations)
148#[derive(Debug, Clone, serde::Serialize)]
149#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
150#[serde(rename_all = "snake_case")]
151pub enum Confidence {
152    /// Recommendation based on deterministic analysis (graph, AST).
153    High,
154    /// Recommendation based on heuristic thresholds.
155    Medium,
156    /// Recommendation depends on external data quality (git history).
157    Low,
158}
159
160impl Confidence {
161    /// Human-readable label for terminal output.
162    #[must_use]
163    pub const fn label(&self) -> &'static str {
164        match self {
165            Self::High => "high",
166            Self::Medium => "medium",
167            Self::Low => "low",
168        }
169    }
170}
171
172/// Evidence linking a target back to specific analysis data.
173///
174/// Provides enough detail for an AI agent to act on a recommendation
175/// without a second tool call.
176#[derive(Debug, Clone, Default, serde::Serialize)]
177#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
178pub struct TargetEvidence {
179    /// Names of unused exports (populated for `RemoveDeadCode` targets).
180    #[serde(default, skip_serializing_if = "Vec::is_empty")]
181    pub unused_exports: Vec<String>,
182    /// Complex functions with line numbers and cognitive scores (populated for `ExtractComplexFunctions`).
183    #[serde(default, skip_serializing_if = "Vec::is_empty")]
184    pub complex_functions: Vec<EvidenceFunction>,
185    /// Files forming the import cycle (populated for `BreakCircularDependency` targets).
186    #[serde(default, skip_serializing_if = "Vec::is_empty")]
187    pub cycle_path: Vec<String>,
188    /// Files that directly import this target, with imported and local symbols.
189    #[serde(default, skip_serializing_if = "Vec::is_empty")]
190    pub direct_callers: Vec<DirectCallerEvidence>,
191    /// Other duplicate-code instances that share a clone group with this target.
192    #[serde(default, skip_serializing_if = "Vec::is_empty")]
193    pub clone_siblings: Vec<CloneSiblingEvidence>,
194}
195
196/// A direct importer referenced in target evidence.
197#[derive(Debug, Clone, serde::Serialize)]
198#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
199pub struct DirectCallerEvidence {
200    /// File that directly imports the target.
201    #[serde(serialize_with = "fallow_types::serde_path::serialize")]
202    pub path: std::path::PathBuf,
203    /// Symbols imported from the target by this file.
204    #[serde(default, skip_serializing_if = "Vec::is_empty")]
205    pub symbols: Vec<DirectCallerSymbolEvidence>,
206}
207
208/// Symbol details for a direct importer.
209#[derive(Debug, Clone, serde::Serialize)]
210#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
211pub struct DirectCallerSymbolEvidence {
212    /// Imported binding name.
213    pub imported: String,
214    /// Local binding name in the importing file.
215    pub local: String,
216    /// Whether the import is type-only.
217    pub type_only: bool,
218}
219
220/// A duplicate-code sibling referenced in target evidence.
221#[derive(Debug, Clone, serde::Serialize)]
222#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
223pub struct CloneSiblingEvidence {
224    /// File containing the sibling clone instance.
225    #[serde(serialize_with = "fallow_types::serde_path::serialize")]
226    pub path: std::path::PathBuf,
227    /// 1-based start line of the sibling clone.
228    pub start_line: usize,
229    /// 1-based end line of the sibling clone.
230    pub end_line: usize,
231    /// Stable duplicate-group handle, matching `dupes --trace dup:<id>`.
232    pub fingerprint: String,
233}
234
235/// A function referenced in target evidence.
236#[derive(Debug, Clone, serde::Serialize)]
237#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
238pub struct EvidenceFunction {
239    /// Function name.
240    pub name: String,
241    /// 1-based line number.
242    pub line: u32,
243    /// Cognitive complexity score.
244    pub cognitive: u16,
245}
246
247#[derive(Debug, Clone, serde::Serialize)]
248#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
249pub struct RefactoringTarget {
250    /// Absolute file path (stripped to relative in output).
251    #[serde(serialize_with = "fallow_types::serde_path::serialize")]
252    pub path: std::path::PathBuf,
253    /// Priority score (0–100, higher = more urgent).
254    pub priority: f64,
255    /// Efficiency score (priority / effort). Higher = better quick-win value.
256    /// Surfaces low-effort, high-priority targets first.
257    pub efficiency: f64,
258    /// One-line actionable recommendation.
259    pub recommendation: String,
260    /// Recommendation category for tooling/filtering.
261    pub category: RecommendationCategory,
262    /// Estimated effort to address this target.
263    pub effort: EffortEstimate,
264    /// Confidence in this recommendation based on data source reliability.
265    pub confidence: Confidence,
266    /// Contributing factors that triggered this recommendation. Empty array
267    /// omitted from JSON.
268    #[serde(default, skip_serializing_if = "Vec::is_empty")]
269    #[cfg_attr(feature = "schema", schemars(default))]
270    pub factors: Vec<ContributingFactor>,
271    /// Structured evidence linking to specific analysis data.
272    #[serde(default, skip_serializing_if = "Option::is_none")]
273    pub evidence: Option<TargetEvidence>,
274}
275
276#[cfg(test)]
277mod tests {
278    use super::*;
279
280    #[test]
281    fn category_labels_are_non_empty() {
282        let categories = [
283            RecommendationCategory::UrgentChurnComplexity,
284            RecommendationCategory::BreakCircularDependency,
285            RecommendationCategory::SplitHighImpact,
286            RecommendationCategory::RemoveDeadCode,
287            RecommendationCategory::ExtractComplexFunctions,
288            RecommendationCategory::ExtractDependencies,
289            RecommendationCategory::AddTestCoverage,
290        ];
291        for cat in &categories {
292            assert!(!cat.label().is_empty(), "{cat:?} should have a label");
293        }
294    }
295
296    #[test]
297    fn category_labels_are_unique() {
298        let categories = [
299            RecommendationCategory::UrgentChurnComplexity,
300            RecommendationCategory::BreakCircularDependency,
301            RecommendationCategory::SplitHighImpact,
302            RecommendationCategory::RemoveDeadCode,
303            RecommendationCategory::ExtractComplexFunctions,
304            RecommendationCategory::ExtractDependencies,
305            RecommendationCategory::AddTestCoverage,
306        ];
307        let labels: Vec<&str> = categories
308            .iter()
309            .map(RecommendationCategory::label)
310            .collect();
311        let unique: rustc_hash::FxHashSet<&&str> = labels.iter().collect();
312        assert_eq!(labels.len(), unique.len(), "category labels must be unique");
313    }
314
315    #[test]
316    fn category_serializes_as_snake_case() {
317        let json = serde_json::to_string(&RecommendationCategory::UrgentChurnComplexity).unwrap();
318        assert_eq!(json, r#""urgent_churn_complexity""#);
319
320        let json = serde_json::to_string(&RecommendationCategory::BreakCircularDependency).unwrap();
321        assert_eq!(json, r#""break_circular_dependency""#);
322    }
323
324    #[test]
325    fn refactoring_target_skips_empty_factors() {
326        let target = RefactoringTarget {
327            path: std::path::PathBuf::from("/src/foo.ts"),
328            priority: 75.0,
329            efficiency: 75.0,
330            recommendation: "Test recommendation".into(),
331            category: RecommendationCategory::RemoveDeadCode,
332            effort: EffortEstimate::Low,
333            confidence: Confidence::High,
334            factors: vec![],
335            evidence: None,
336        };
337        let json = serde_json::to_string(&target).unwrap();
338        assert!(!json.contains("factors"));
339        assert!(!json.contains("evidence"));
340    }
341
342    #[test]
343    fn effort_numeric_values() {
344        assert!((EffortEstimate::Low.numeric() - 1.0).abs() < f64::EPSILON);
345        assert!((EffortEstimate::Medium.numeric() - 2.0).abs() < f64::EPSILON);
346        assert!((EffortEstimate::High.numeric() - 3.0).abs() < f64::EPSILON);
347    }
348
349    #[test]
350    fn confidence_labels_are_non_empty() {
351        let levels = [Confidence::High, Confidence::Medium, Confidence::Low];
352        for level in &levels {
353            assert!(!level.label().is_empty(), "{level:?} should have a label");
354        }
355    }
356
357    #[test]
358    fn confidence_serializes_as_snake_case() {
359        let json = serde_json::to_string(&Confidence::High).unwrap();
360        assert_eq!(json, r#""high""#);
361        let json = serde_json::to_string(&Confidence::Medium).unwrap();
362        assert_eq!(json, r#""medium""#);
363        let json = serde_json::to_string(&Confidence::Low).unwrap();
364        assert_eq!(json, r#""low""#);
365    }
366
367    #[test]
368    fn contributing_factor_serializes_correctly() {
369        let factor = ContributingFactor {
370            metric: "fan_in",
371            value: 15.0,
372            threshold: 10.0,
373            detail: "15 files depend on this".into(),
374        };
375        let json = serde_json::to_string(&factor).unwrap();
376        let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
377        assert_eq!(parsed["metric"], "fan_in");
378        assert_eq!(parsed["value"], 15.0);
379        assert_eq!(parsed["threshold"], 10.0);
380    }
381
382    #[test]
383    fn category_compact_labels_are_non_empty() {
384        let categories = [
385            RecommendationCategory::UrgentChurnComplexity,
386            RecommendationCategory::BreakCircularDependency,
387            RecommendationCategory::SplitHighImpact,
388            RecommendationCategory::RemoveDeadCode,
389            RecommendationCategory::ExtractComplexFunctions,
390            RecommendationCategory::ExtractDependencies,
391            RecommendationCategory::AddTestCoverage,
392        ];
393        for cat in &categories {
394            assert!(
395                !cat.compact_label().is_empty(),
396                "{cat:?} should have a compact_label"
397            );
398        }
399    }
400
401    #[test]
402    fn category_compact_labels_are_unique() {
403        let categories = [
404            RecommendationCategory::UrgentChurnComplexity,
405            RecommendationCategory::BreakCircularDependency,
406            RecommendationCategory::SplitHighImpact,
407            RecommendationCategory::RemoveDeadCode,
408            RecommendationCategory::ExtractComplexFunctions,
409            RecommendationCategory::ExtractDependencies,
410            RecommendationCategory::AddTestCoverage,
411        ];
412        let labels: Vec<&str> = categories
413            .iter()
414            .map(RecommendationCategory::compact_label)
415            .collect();
416        let unique: rustc_hash::FxHashSet<&&str> = labels.iter().collect();
417        assert_eq!(labels.len(), unique.len(), "compact labels must be unique");
418    }
419
420    #[test]
421    fn category_compact_labels_have_no_spaces() {
422        let categories = [
423            RecommendationCategory::UrgentChurnComplexity,
424            RecommendationCategory::BreakCircularDependency,
425            RecommendationCategory::SplitHighImpact,
426            RecommendationCategory::RemoveDeadCode,
427            RecommendationCategory::ExtractComplexFunctions,
428            RecommendationCategory::ExtractDependencies,
429            RecommendationCategory::AddTestCoverage,
430        ];
431        for cat in &categories {
432            assert!(
433                !cat.compact_label().contains(' '),
434                "compact_label for {:?} should not contain spaces: '{}'",
435                cat,
436                cat.compact_label()
437            );
438        }
439    }
440
441    #[test]
442    fn effort_labels_are_non_empty() {
443        let efforts = [
444            EffortEstimate::Low,
445            EffortEstimate::Medium,
446            EffortEstimate::High,
447        ];
448        for effort in &efforts {
449            assert!(!effort.label().is_empty(), "{effort:?} should have a label");
450        }
451    }
452
453    #[test]
454    fn effort_serializes_as_snake_case() {
455        assert_eq!(
456            serde_json::to_string(&EffortEstimate::Low).unwrap(),
457            r#""low""#
458        );
459        assert_eq!(
460            serde_json::to_string(&EffortEstimate::Medium).unwrap(),
461            r#""medium""#
462        );
463        assert_eq!(
464            serde_json::to_string(&EffortEstimate::High).unwrap(),
465            r#""high""#
466        );
467    }
468
469    #[test]
470    fn target_evidence_skips_empty_fields() {
471        let evidence = TargetEvidence {
472            unused_exports: vec![],
473            complex_functions: vec![],
474            cycle_path: vec![],
475            direct_callers: vec![],
476            clone_siblings: vec![],
477        };
478        let json = serde_json::to_string(&evidence).unwrap();
479        assert!(!json.contains("unused_exports"));
480        assert!(!json.contains("complex_functions"));
481        assert!(!json.contains("cycle_path"));
482        assert!(!json.contains("direct_callers"));
483        assert!(!json.contains("clone_siblings"));
484    }
485
486    #[test]
487    fn target_evidence_with_data() {
488        let evidence = TargetEvidence {
489            unused_exports: vec!["foo".to_string(), "bar".to_string()],
490            complex_functions: vec![EvidenceFunction {
491                name: "processData".into(),
492                line: 42,
493                cognitive: 30,
494            }],
495            cycle_path: vec![],
496            direct_callers: vec![DirectCallerEvidence {
497                path: "src/consumer.ts".into(),
498                symbols: vec![DirectCallerSymbolEvidence {
499                    imported: "processData".into(),
500                    local: "processData".into(),
501                    type_only: false,
502                }],
503            }],
504            clone_siblings: vec![CloneSiblingEvidence {
505                path: "src/peer.ts".into(),
506                start_line: 12,
507                end_line: 20,
508                fingerprint: "dup:12345678".into(),
509            }],
510        };
511        let json = serde_json::to_string(&evidence).unwrap();
512        assert!(json.contains("unused_exports"));
513        assert!(json.contains("complex_functions"));
514        assert!(json.contains("processData"));
515        assert!(json.contains("direct_callers"));
516        assert!(json.contains("clone_siblings"));
517        assert!(!json.contains("cycle_path"));
518    }
519}
fallow_cli/health_types/targets.rs

fallow_cli/health_types/
targets.rs
