fallow_cli/
explain.rs

1//! Metric and rule definitions for explainable CLI output.
2//!
3//! Provides structured metadata that describes what each metric, threshold,
4//! and rule means — consumed by the `_meta` object in JSON output and by
5//! SARIF `fullDescription` / `helpUri` fields.
6
7use serde_json::{Value, json};
8
9// ── Docs base URL ────────────────────────────────────────────────
10
11const DOCS_BASE: &str = "https://docs.fallow.tools";
12
13/// Docs URL for the check command.
14pub const CHECK_DOCS: &str = "https://docs.fallow.tools/cli/check";
15
16/// Docs URL for the health command.
17pub const HEALTH_DOCS: &str = "https://docs.fallow.tools/cli/health";
18
19/// Docs URL for the dupes command.
20pub const DUPES_DOCS: &str = "https://docs.fallow.tools/cli/dupes";
21
22// ── Check rules ─────────────────────────────────────────────────
23
24/// Rule definition for SARIF `fullDescription` and JSON `_meta`.
25pub struct RuleDef {
26    pub id: &'static str,
27    pub name: &'static str,
28    pub short: &'static str,
29    pub full: &'static str,
30    pub docs_path: &'static str,
31}
32
33pub const CHECK_RULES: &[RuleDef] = &[
34    RuleDef {
35        id: "fallow/unused-file",
36        name: "Unused Files",
37        short: "File is not reachable from any entry point",
38        full: "Source files that are not imported by any other module and are not entry points (scripts, tests, configs). These files can safely be deleted. Detection uses graph reachability from configured entry points.",
39        docs_path: "explanations/dead-code#unused-files",
40    },
41    RuleDef {
42        id: "fallow/unused-export",
43        name: "Unused Exports",
44        short: "Export is never imported",
45        full: "Named exports that are never imported by any other module in the project. Includes both direct exports and re-exports through barrel files. The export may still be used locally within the same file.",
46        docs_path: "explanations/dead-code#unused-exports",
47    },
48    RuleDef {
49        id: "fallow/unused-type",
50        name: "Unused Type Exports",
51        short: "Type export is never imported",
52        full: "Type-only exports (interfaces, type aliases, enums used only as types) that are never imported. These do not generate runtime code but add maintenance burden.",
53        docs_path: "explanations/dead-code#unused-types",
54    },
55    RuleDef {
56        id: "fallow/unused-dependency",
57        name: "Unused Dependencies",
58        short: "Dependency listed but never imported",
59        full: "Packages listed in dependencies that are never imported or required by any source file. Framework plugins and CLI tools may be false positives — use the ignore_dependencies config to suppress.",
60        docs_path: "explanations/dead-code#unused-dependencies",
61    },
62    RuleDef {
63        id: "fallow/unused-dev-dependency",
64        name: "Unused Dev Dependencies",
65        short: "Dev dependency listed but never imported",
66        full: "Packages listed in devDependencies that are never imported by test files, config files, or scripts. Build tools and jest presets that are referenced only in config may appear as false positives.",
67        docs_path: "explanations/dead-code#unused-devdependencies",
68    },
69    RuleDef {
70        id: "fallow/unused-optional-dependency",
71        name: "Unused Optional Dependencies",
72        short: "Optional dependency listed but never imported",
73        full: "Packages listed in optionalDependencies that are never imported. Optional dependencies are typically platform-specific — verify they are not needed on any supported platform before removing.",
74        docs_path: "explanations/dead-code#unused-optionaldependencies",
75    },
76    RuleDef {
77        id: "fallow/type-only-dependency",
78        name: "Type-only Dependencies",
79        short: "Production dependency only used via type-only imports",
80        full: "Production dependencies that are only imported via `import type` statements. These can be moved to devDependencies since they generate no runtime code and are stripped during compilation.",
81        docs_path: "explanations/dead-code#type-only-dependencies",
82    },
83    RuleDef {
84        id: "fallow/unused-enum-member",
85        name: "Unused Enum Members",
86        short: "Enum member is never referenced",
87        full: "Enum members that are never referenced in the codebase. Uses scope-aware binding analysis to track all references including computed access patterns.",
88        docs_path: "explanations/dead-code#unused-enum-members",
89    },
90    RuleDef {
91        id: "fallow/unused-class-member",
92        name: "Unused Class Members",
93        short: "Class member is never referenced",
94        full: "Class methods and properties that are never referenced outside the class. Private members are checked within the class scope; public members are checked project-wide.",
95        docs_path: "explanations/dead-code#unused-class-members",
96    },
97    RuleDef {
98        id: "fallow/unresolved-import",
99        name: "Unresolved Imports",
100        short: "Import could not be resolved",
101        full: "Import specifiers that could not be resolved to a file on disk. Common causes: deleted files, typos in paths, missing path aliases in tsconfig, or uninstalled packages.",
102        docs_path: "explanations/dead-code#unresolved-imports",
103    },
104    RuleDef {
105        id: "fallow/unlisted-dependency",
106        name: "Unlisted Dependencies",
107        short: "Dependency used but not in package.json",
108        full: "Packages that are imported in source code but not listed in package.json. These work by accident (hoisted from another workspace package or transitive dep) and will break in strict package managers.",
109        docs_path: "explanations/dead-code#unlisted-dependencies",
110    },
111    RuleDef {
112        id: "fallow/duplicate-export",
113        name: "Duplicate Exports",
114        short: "Export name appears in multiple modules",
115        full: "The same export name is defined in multiple modules. Consumers may import from the wrong module, leading to subtle bugs. Consider renaming or consolidating.",
116        docs_path: "explanations/dead-code#duplicate-exports",
117    },
118    RuleDef {
119        id: "fallow/circular-dependency",
120        name: "Circular Dependencies",
121        short: "Circular dependency chain detected",
122        full: "A cycle in the module import graph. Circular dependencies cause undefined behavior with CommonJS (partial modules) and initialization ordering issues with ESM. Break cycles by extracting shared code.",
123        docs_path: "explanations/dead-code#circular-dependencies",
124    },
125];
126
127/// Look up a rule definition by its SARIF rule ID across all rule sets.
128pub fn rule_by_id(id: &str) -> Option<&'static RuleDef> {
129    CHECK_RULES
130        .iter()
131        .chain(HEALTH_RULES.iter())
132        .chain(DUPES_RULES.iter())
133        .find(|r| r.id == id)
134}
135
136/// Build the docs URL for a rule.
137pub fn rule_docs_url(rule: &RuleDef) -> String {
138    format!("{DOCS_BASE}/{}", rule.docs_path)
139}
140
141// ── Health SARIF rules ──────────────────────────────────────────
142
143pub const HEALTH_RULES: &[RuleDef] = &[
144    RuleDef {
145        id: "fallow/high-cyclomatic-complexity",
146        name: "High Cyclomatic Complexity",
147        short: "Function has high cyclomatic complexity",
148        full: "McCabe cyclomatic complexity exceeds the configured threshold. Cyclomatic complexity counts the number of independent paths through a function (1 + decision points: if/else, switch cases, loops, ternary, logical operators). High values indicate functions that are hard to test exhaustively.",
149        docs_path: "explanations/health#cyclomatic-complexity",
150    },
151    RuleDef {
152        id: "fallow/high-cognitive-complexity",
153        name: "High Cognitive Complexity",
154        short: "Function has high cognitive complexity",
155        full: "SonarSource cognitive complexity exceeds the configured threshold. Unlike cyclomatic complexity, cognitive complexity penalizes nesting depth and non-linear control flow (breaks, continues, early returns). It measures how hard a function is to understand when reading sequentially.",
156        docs_path: "explanations/health#cognitive-complexity",
157    },
158    RuleDef {
159        id: "fallow/high-complexity",
160        name: "High Complexity (Both)",
161        short: "Function exceeds both complexity thresholds",
162        full: "Function exceeds both cyclomatic and cognitive complexity thresholds. This is the strongest signal that a function needs refactoring — it has many paths AND is hard to understand.",
163        docs_path: "explanations/health#complexity-metrics",
164    },
165    RuleDef {
166        id: "fallow/refactoring-target",
167        name: "Refactoring Target",
168        short: "File identified as a high-priority refactoring candidate",
169        full: "File identified as a refactoring candidate based on a weighted combination of complexity density, churn velocity, dead code ratio, fan-in (blast radius), and fan-out (coupling). Categories: urgent churn+complexity, break circular dependency, split high-impact file, remove dead code, extract complex functions, reduce coupling.",
170        docs_path: "explanations/health#refactoring-targets",
171    },
172];
173
174pub const DUPES_RULES: &[RuleDef] = &[RuleDef {
175    id: "fallow/code-duplication",
176    name: "Code Duplication",
177    short: "Duplicated code block",
178    full: "A block of code that appears in multiple locations with identical or near-identical token sequences. Clone detection uses normalized token comparison — identifier names and literals are abstracted away in non-strict modes.",
179    docs_path: "explanations/duplication#clone-groups",
180}];
181
182// ── JSON _meta builders ─────────────────────────────────────────
183
184/// Build the `_meta` object for `fallow check --format json --explain`.
185pub fn check_meta() -> Value {
186    let rules: Value = CHECK_RULES
187        .iter()
188        .map(|r| {
189            (
190                r.id.replace("fallow/", ""),
191                json!({
192                    "name": r.name,
193                    "description": r.full,
194                    "docs": rule_docs_url(r)
195                }),
196            )
197        })
198        .collect::<serde_json::Map<String, Value>>()
199        .into();
200
201    json!({
202        "docs": CHECK_DOCS,
203        "rules": rules
204    })
205}
206
207/// Build the `_meta` object for `fallow health --format json --explain`.
208pub fn health_meta() -> Value {
209    json!({
210        "docs": HEALTH_DOCS,
211        "metrics": {
212            "cyclomatic": {
213                "name": "Cyclomatic Complexity",
214                "description": "McCabe cyclomatic complexity: 1 + number of decision points (if/else, switch cases, loops, ternary, logical operators). Measures the number of independent paths through a function.",
215                "range": "[1, \u{221e})",
216                "interpretation": "lower is better; default threshold: 20"
217            },
218            "cognitive": {
219                "name": "Cognitive Complexity",
220                "description": "SonarSource cognitive complexity: penalizes nesting depth and non-linear control flow (breaks, continues, early returns). Measures how hard a function is to understand when reading top-to-bottom.",
221                "range": "[0, \u{221e})",
222                "interpretation": "lower is better; default threshold: 15"
223            },
224            "line_count": {
225                "name": "Line Count",
226                "description": "Number of lines in the function body.",
227                "range": "[1, \u{221e})",
228                "interpretation": "context-dependent; long functions may need splitting"
229            },
230            "maintainability_index": {
231                "name": "Maintainability Index",
232                "description": "Composite score: 100 - (complexity_density \u{00d7} 30) - (dead_code_ratio \u{00d7} 20) - min(ln(fan_out+1) \u{00d7} 4, 15). Clamped to [0, 100]. Higher is better.",
233                "range": "[0, 100]",
234                "interpretation": "higher is better; <40 poor, 40\u{2013}70 moderate, >70 good"
235            },
236            "complexity_density": {
237                "name": "Complexity Density",
238                "description": "Total cyclomatic complexity divided by lines of code. Measures how densely complex the code is per line.",
239                "range": "[0, \u{221e})",
240                "interpretation": "lower is better; >1.0 indicates very dense complexity"
241            },
242            "dead_code_ratio": {
243                "name": "Dead Code Ratio",
244                "description": "Fraction of value exports (excluding type-only exports like interfaces and type aliases) with zero references across the project.",
245                "range": "[0, 1]",
246                "interpretation": "lower is better; 0 = all exports are used"
247            },
248            "fan_in": {
249                "name": "Fan-in (Importers)",
250                "description": "Number of files that import this file. High fan-in means high blast radius \u{2014} changes to this file affect many dependents.",
251                "range": "[0, \u{221e})",
252                "interpretation": "context-dependent; high fan-in files need careful review before changes"
253            },
254            "fan_out": {
255                "name": "Fan-out (Imports)",
256                "description": "Number of files this file directly imports. High fan-out indicates high coupling and change propagation risk.",
257                "range": "[0, \u{221e})",
258                "interpretation": "lower is better; MI penalty caps at ~40 imports"
259            },
260            "score": {
261                "name": "Hotspot Score",
262                "description": "normalized_churn \u{00d7} normalized_complexity \u{00d7} 100, where normalization is against the project maximum. Identifies files that are both complex AND frequently changing.",
263                "range": "[0, 100]",
264                "interpretation": "higher = riskier; prioritize refactoring high-score files"
265            },
266            "weighted_commits": {
267                "name": "Weighted Commits",
268                "description": "Recency-weighted commit count using exponential decay with 90-day half-life. Recent commits contribute more than older ones.",
269                "range": "[0, \u{221e})",
270                "interpretation": "higher = more recent churn activity"
271            },
272            "trend": {
273                "name": "Churn Trend",
274                "description": "Compares recent vs older commit frequency within the analysis window. accelerating = recent > 1.5\u{00d7} older, cooling = recent < 0.67\u{00d7} older, stable = in between.",
275                "values": ["accelerating", "stable", "cooling"],
276                "interpretation": "accelerating files need attention; cooling files are stabilizing"
277            },
278            "priority": {
279                "name": "Refactoring Priority",
280                "description": "Weighted score: complexity density (30%), hotspot boost (25%), dead code ratio (20%), fan-in (15%), fan-out (10%). Does not use the maintainability index to avoid double-counting.",
281                "range": "[0, 100]",
282                "interpretation": "higher = more urgent to refactor"
283            },
284            "effort": {
285                "name": "Effort Estimate",
286                "description": "Heuristic effort estimate based on file size, function count, and fan-in. Low: <100 lines, \u{2264}3 functions, <5 importers. High: \u{2265}500 lines, \u{2265}20 importers, or \u{2265}15 functions with high density. Medium: everything else.",
287                "values": ["low", "medium", "high"],
288                "interpretation": "low = quick win, high = needs planning and coordination"
289            }
290        }
291    })
292}
293
294#[cfg(test)]
295mod tests {
296    use super::*;
297
298    // ── rule_by_id ───────────────────────────────────────────────────
299
300    #[test]
301    fn rule_by_id_finds_check_rule() {
302        let rule = rule_by_id("fallow/unused-file").unwrap();
303        assert_eq!(rule.name, "Unused Files");
304    }
305
306    #[test]
307    fn rule_by_id_finds_health_rule() {
308        let rule = rule_by_id("fallow/high-cyclomatic-complexity").unwrap();
309        assert_eq!(rule.name, "High Cyclomatic Complexity");
310    }
311
312    #[test]
313    fn rule_by_id_finds_dupes_rule() {
314        let rule = rule_by_id("fallow/code-duplication").unwrap();
315        assert_eq!(rule.name, "Code Duplication");
316    }
317
318    #[test]
319    fn rule_by_id_returns_none_for_unknown() {
320        assert!(rule_by_id("fallow/nonexistent").is_none());
321        assert!(rule_by_id("").is_none());
322    }
323
324    // ── rule_docs_url ────────────────────────────────────────────────
325
326    #[test]
327    fn rule_docs_url_format() {
328        let rule = rule_by_id("fallow/unused-export").unwrap();
329        let url = rule_docs_url(rule);
330        assert!(url.starts_with("https://docs.fallow.tools/"));
331        assert!(url.contains("unused-exports"));
332    }
333
334    // ── CHECK_RULES completeness ─────────────────────────────────────
335
336    #[test]
337    fn check_rules_all_have_fallow_prefix() {
338        for rule in CHECK_RULES {
339            assert!(
340                rule.id.starts_with("fallow/"),
341                "rule {} should start with fallow/",
342                rule.id
343            );
344        }
345    }
346
347    #[test]
348    fn check_rules_all_have_docs_path() {
349        for rule in CHECK_RULES {
350            assert!(
351                !rule.docs_path.is_empty(),
352                "rule {} should have a docs_path",
353                rule.id
354            );
355        }
356    }
357
358    #[test]
359    fn check_rules_no_duplicate_ids() {
360        let mut seen = std::collections::HashSet::new();
361        for rule in CHECK_RULES.iter().chain(HEALTH_RULES).chain(DUPES_RULES) {
362            assert!(seen.insert(rule.id), "duplicate rule id: {}", rule.id);
363        }
364    }
365
366    // ── check_meta ───────────────────────────────────────────────────
367
368    #[test]
369    fn check_meta_has_docs_and_rules() {
370        let meta = check_meta();
371        assert!(meta.get("docs").is_some());
372        assert!(meta.get("rules").is_some());
373        let rules = meta["rules"].as_object().unwrap();
374        // Verify all 13 rule categories are present (stripped fallow/ prefix)
375        assert_eq!(rules.len(), CHECK_RULES.len());
376        assert!(rules.contains_key("unused-file"));
377        assert!(rules.contains_key("unused-export"));
378        assert!(rules.contains_key("unused-type"));
379        assert!(rules.contains_key("unused-dependency"));
380        assert!(rules.contains_key("unused-dev-dependency"));
381        assert!(rules.contains_key("unused-optional-dependency"));
382        assert!(rules.contains_key("unused-enum-member"));
383        assert!(rules.contains_key("unused-class-member"));
384        assert!(rules.contains_key("unresolved-import"));
385        assert!(rules.contains_key("unlisted-dependency"));
386        assert!(rules.contains_key("duplicate-export"));
387        assert!(rules.contains_key("type-only-dependency"));
388        assert!(rules.contains_key("circular-dependency"));
389    }
390
391    #[test]
392    fn check_meta_rule_has_required_fields() {
393        let meta = check_meta();
394        let rules = meta["rules"].as_object().unwrap();
395        for (key, value) in rules {
396            assert!(value.get("name").is_some(), "rule {key} missing 'name'");
397            assert!(
398                value.get("description").is_some(),
399                "rule {key} missing 'description'"
400            );
401            assert!(value.get("docs").is_some(), "rule {key} missing 'docs'");
402        }
403    }
404
405    // ── health_meta ──────────────────────────────────────────────────
406
407    #[test]
408    fn health_meta_has_metrics() {
409        let meta = health_meta();
410        assert!(meta.get("docs").is_some());
411        let metrics = meta["metrics"].as_object().unwrap();
412        assert!(metrics.contains_key("cyclomatic"));
413        assert!(metrics.contains_key("cognitive"));
414        assert!(metrics.contains_key("maintainability_index"));
415        assert!(metrics.contains_key("complexity_density"));
416        assert!(metrics.contains_key("fan_in"));
417        assert!(metrics.contains_key("fan_out"));
418    }
419
420    // ── dupes_meta ───────────────────────────────────────────────────
421
422    #[test]
423    fn dupes_meta_has_metrics() {
424        let meta = dupes_meta();
425        assert!(meta.get("docs").is_some());
426        let metrics = meta["metrics"].as_object().unwrap();
427        assert!(metrics.contains_key("duplication_percentage"));
428        assert!(metrics.contains_key("token_count"));
429        assert!(metrics.contains_key("clone_groups"));
430        assert!(metrics.contains_key("clone_families"));
431    }
432}
433
434/// Build the `_meta` object for `fallow dupes --format json --explain`.
435pub fn dupes_meta() -> Value {
436    json!({
437        "docs": DUPES_DOCS,
438        "metrics": {
439            "duplication_percentage": {
440                "name": "Duplication Percentage",
441                "description": "Fraction of total source tokens that appear in at least one clone group. Computed over the full analyzed file set.",
442                "range": "[0, 100]",
443                "interpretation": "lower is better"
444            },
445            "token_count": {
446                "name": "Token Count",
447                "description": "Number of normalized source tokens in the clone group. Tokens are language-aware (keywords, identifiers, operators, punctuation). Higher token count = larger duplicate.",
448                "range": "[1, \u{221e})",
449                "interpretation": "larger clones have higher refactoring value"
450            },
451            "line_count": {
452                "name": "Line Count",
453                "description": "Number of source lines spanned by the clone instance. Approximation of clone size for human readability.",
454                "range": "[1, \u{221e})",
455                "interpretation": "larger clones are more impactful to deduplicate"
456            },
457            "clone_groups": {
458                "name": "Clone Groups",
459                "description": "A set of code fragments with identical or near-identical normalized token sequences. Each group has 2+ instances across different locations.",
460                "interpretation": "each group is a single refactoring opportunity"
461            },
462            "clone_families": {
463                "name": "Clone Families",
464                "description": "Groups of clone groups that share the same set of files. Indicates systematic duplication patterns (e.g., mirrored directory structures).",
465                "interpretation": "families suggest extract-module refactoring opportunities"
466            }
467        }
468    })
469}
fallow_cli/explain.rs

fallow_cli/
explain.rs
