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 dead-code (check) command.
14pub const CHECK_DOCS: &str = "https://docs.fallow.tools/cli/dead-code";
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.
128#[must_use]
129pub fn rule_by_id(id: &str) -> Option<&'static RuleDef> {
130    CHECK_RULES
131        .iter()
132        .chain(HEALTH_RULES.iter())
133        .chain(DUPES_RULES.iter())
134        .find(|r| r.id == id)
135}
136
137/// Build the docs URL for a rule.
138#[must_use]
139pub fn rule_docs_url(rule: &RuleDef) -> String {
140    format!("{DOCS_BASE}/{}", rule.docs_path)
141}
142
143// ── Health SARIF rules ──────────────────────────────────────────
144
145pub const HEALTH_RULES: &[RuleDef] = &[
146    RuleDef {
147        id: "fallow/high-cyclomatic-complexity",
148        name: "High Cyclomatic Complexity",
149        short: "Function has high cyclomatic complexity",
150        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.",
151        docs_path: "explanations/health#cyclomatic-complexity",
152    },
153    RuleDef {
154        id: "fallow/high-cognitive-complexity",
155        name: "High Cognitive Complexity",
156        short: "Function has high cognitive complexity",
157        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.",
158        docs_path: "explanations/health#cognitive-complexity",
159    },
160    RuleDef {
161        id: "fallow/high-complexity",
162        name: "High Complexity (Both)",
163        short: "Function exceeds both complexity thresholds",
164        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.",
165        docs_path: "explanations/health#complexity-metrics",
166    },
167    RuleDef {
168        id: "fallow/refactoring-target",
169        name: "Refactoring Target",
170        short: "File identified as a high-priority refactoring candidate",
171        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.",
172        docs_path: "explanations/health#refactoring-targets",
173    },
174    RuleDef {
175        id: "fallow/untested-file",
176        name: "Untested File",
177        short: "Runtime-reachable file has no test dependency path",
178        full: "A file is reachable from runtime entry points but not from any discovered test entry point. This indicates production code that no test imports, directly or transitively, according to the static module graph.",
179        docs_path: "explanations/health#coverage-gaps",
180    },
181    RuleDef {
182        id: "fallow/untested-export",
183        name: "Untested Export",
184        short: "Runtime-reachable export has no test dependency path",
185        full: "A value export is reachable from runtime entry points but no test-reachable module references it. This is a static test dependency gap rather than line coverage, and highlights exports exercised only through production entry paths.",
186        docs_path: "explanations/health#coverage-gaps",
187    },
188];
189
190pub const DUPES_RULES: &[RuleDef] = &[RuleDef {
191    id: "fallow/code-duplication",
192    name: "Code Duplication",
193    short: "Duplicated code block",
194    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.",
195    docs_path: "explanations/duplication#clone-groups",
196}];
197
198// ── JSON _meta builders ─────────────────────────────────────────
199
200/// Build the `_meta` object for `fallow dead-code --format json --explain`.
201#[must_use]
202pub fn check_meta() -> Value {
203    let rules: Value = CHECK_RULES
204        .iter()
205        .map(|r| {
206            (
207                r.id.replace("fallow/", ""),
208                json!({
209                    "name": r.name,
210                    "description": r.full,
211                    "docs": rule_docs_url(r)
212                }),
213            )
214        })
215        .collect::<serde_json::Map<String, Value>>()
216        .into();
217
218    json!({
219        "docs": CHECK_DOCS,
220        "rules": rules
221    })
222}
223
224/// Build the `_meta` object for `fallow health --format json --explain`.
225#[must_use]
226pub fn health_meta() -> Value {
227    json!({
228        "docs": HEALTH_DOCS,
229        "metrics": {
230            "cyclomatic": {
231                "name": "Cyclomatic Complexity",
232                "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.",
233                "range": "[1, \u{221e})",
234                "interpretation": "lower is better; default threshold: 20"
235            },
236            "cognitive": {
237                "name": "Cognitive Complexity",
238                "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.",
239                "range": "[0, \u{221e})",
240                "interpretation": "lower is better; default threshold: 15"
241            },
242            "line_count": {
243                "name": "Line Count",
244                "description": "Number of lines in the function body.",
245                "range": "[1, \u{221e})",
246                "interpretation": "context-dependent; long functions may need splitting"
247            },
248            "maintainability_index": {
249                "name": "Maintainability Index",
250                "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.",
251                "range": "[0, 100]",
252                "interpretation": "higher is better; <40 poor, 40\u{2013}70 moderate, >70 good"
253            },
254            "complexity_density": {
255                "name": "Complexity Density",
256                "description": "Total cyclomatic complexity divided by lines of code. Measures how densely complex the code is per line.",
257                "range": "[0, \u{221e})",
258                "interpretation": "lower is better; >1.0 indicates very dense complexity"
259            },
260            "dead_code_ratio": {
261                "name": "Dead Code Ratio",
262                "description": "Fraction of value exports (excluding type-only exports like interfaces and type aliases) with zero references across the project.",
263                "range": "[0, 1]",
264                "interpretation": "lower is better; 0 = all exports are used"
265            },
266            "fan_in": {
267                "name": "Fan-in (Importers)",
268                "description": "Number of files that import this file. High fan-in means high blast radius \u{2014} changes to this file affect many dependents.",
269                "range": "[0, \u{221e})",
270                "interpretation": "context-dependent; high fan-in files need careful review before changes"
271            },
272            "fan_out": {
273                "name": "Fan-out (Imports)",
274                "description": "Number of files this file directly imports. High fan-out indicates high coupling and change propagation risk.",
275                "range": "[0, \u{221e})",
276                "interpretation": "lower is better; MI penalty caps at ~40 imports"
277            },
278            "score": {
279                "name": "Hotspot Score",
280                "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.",
281                "range": "[0, 100]",
282                "interpretation": "higher = riskier; prioritize refactoring high-score files"
283            },
284            "weighted_commits": {
285                "name": "Weighted Commits",
286                "description": "Recency-weighted commit count using exponential decay with 90-day half-life. Recent commits contribute more than older ones.",
287                "range": "[0, \u{221e})",
288                "interpretation": "higher = more recent churn activity"
289            },
290            "trend": {
291                "name": "Churn Trend",
292                "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.",
293                "values": ["accelerating", "stable", "cooling"],
294                "interpretation": "accelerating files need attention; cooling files are stabilizing"
295            },
296            "priority": {
297                "name": "Refactoring Priority",
298                "description": "Weighted score: complexity density (30%), hotspot boost (25%), dead code ratio (20%), fan-in (15%), fan-out (10%). Fan-in and fan-out normalization uses adaptive percentile-based thresholds (p95 of the project distribution). Does not use the maintainability index to avoid double-counting.",
299                "range": "[0, 100]",
300                "interpretation": "higher = more urgent to refactor"
301            },
302            "efficiency": {
303                "name": "Efficiency Score",
304                "description": "priority / effort_numeric (Low=1, Medium=2, High=3). Surfaces quick wins: high-priority, low-effort targets rank first. Default sort order.",
305                "range": "[0, 100] \u{2014} effective max depends on effort: Low=100, Medium=50, High\u{2248}33",
306                "interpretation": "higher = better quick-win value; targets are sorted by efficiency descending"
307            },
308            "effort": {
309                "name": "Effort Estimate",
310                "description": "Heuristic effort estimate based on file size, function count, and fan-in. Thresholds adapt to the project\u{2019}s distribution (percentile-based). Low: small file, few functions, low fan-in. High: large file, high fan-in, or many functions with high density. Medium: everything else.",
311                "values": ["low", "medium", "high"],
312                "interpretation": "low = quick win, high = needs planning and coordination"
313            },
314            "confidence": {
315                "name": "Confidence Level",
316                "description": "Reliability of the recommendation based on data source. High: deterministic graph/AST analysis (dead code, circular deps, complexity). Medium: heuristic thresholds (fan-in/fan-out coupling). Low: depends on git history quality (churn-based recommendations).",
317                "values": ["high", "medium", "low"],
318                "interpretation": "high = act on it, medium = verify context, low = treat as a signal, not a directive"
319            },
320            "health_score": {
321                "name": "Health Score",
322                "description": "Project-level aggregate score computed from vital signs: dead code, complexity, maintainability, hotspots, unused dependencies, and circular dependencies. Penalties subtracted from 100. Missing metrics (from pipelines that didn't run) don't penalize. Use --score to force full pipeline for maximum accuracy.",
323                "range": "[0, 100]",
324                "interpretation": "higher is better; A (85\u{2013}100), B (70\u{2013}84), C (55\u{2013}69), D (40\u{2013}54), F (0\u{2013}39)"
325            }
326        }
327    })
328}
329
330/// Build the `_meta` object for `fallow dupes --format json --explain`.
331#[must_use]
332pub fn dupes_meta() -> Value {
333    json!({
334        "docs": DUPES_DOCS,
335        "metrics": {
336            "duplication_percentage": {
337                "name": "Duplication Percentage",
338                "description": "Fraction of total source tokens that appear in at least one clone group. Computed over the full analyzed file set.",
339                "range": "[0, 100]",
340                "interpretation": "lower is better"
341            },
342            "token_count": {
343                "name": "Token Count",
344                "description": "Number of normalized source tokens in the clone group. Tokens are language-aware (keywords, identifiers, operators, punctuation). Higher token count = larger duplicate.",
345                "range": "[1, \u{221e})",
346                "interpretation": "larger clones have higher refactoring value"
347            },
348            "line_count": {
349                "name": "Line Count",
350                "description": "Number of source lines spanned by the clone instance. Approximation of clone size for human readability.",
351                "range": "[1, \u{221e})",
352                "interpretation": "larger clones are more impactful to deduplicate"
353            },
354            "clone_groups": {
355                "name": "Clone Groups",
356                "description": "A set of code fragments with identical or near-identical normalized token sequences. Each group has 2+ instances across different locations.",
357                "interpretation": "each group is a single refactoring opportunity"
358            },
359            "clone_families": {
360                "name": "Clone Families",
361                "description": "Groups of clone groups that share the same set of files. Indicates systematic duplication patterns (e.g., mirrored directory structures).",
362                "interpretation": "families suggest extract-module refactoring opportunities"
363            }
364        }
365    })
366}
367
368#[cfg(test)]
369mod tests {
370    use super::*;
371
372    // ── rule_by_id ───────────────────────────────────────────────────
373
374    #[test]
375    fn rule_by_id_finds_check_rule() {
376        let rule = rule_by_id("fallow/unused-file").unwrap();
377        assert_eq!(rule.name, "Unused Files");
378    }
379
380    #[test]
381    fn rule_by_id_finds_health_rule() {
382        let rule = rule_by_id("fallow/high-cyclomatic-complexity").unwrap();
383        assert_eq!(rule.name, "High Cyclomatic Complexity");
384    }
385
386    #[test]
387    fn rule_by_id_finds_dupes_rule() {
388        let rule = rule_by_id("fallow/code-duplication").unwrap();
389        assert_eq!(rule.name, "Code Duplication");
390    }
391
392    #[test]
393    fn rule_by_id_returns_none_for_unknown() {
394        assert!(rule_by_id("fallow/nonexistent").is_none());
395        assert!(rule_by_id("").is_none());
396    }
397
398    // ── rule_docs_url ────────────────────────────────────────────────
399
400    #[test]
401    fn rule_docs_url_format() {
402        let rule = rule_by_id("fallow/unused-export").unwrap();
403        let url = rule_docs_url(rule);
404        assert!(url.starts_with("https://docs.fallow.tools/"));
405        assert!(url.contains("unused-exports"));
406    }
407
408    // ── CHECK_RULES completeness ─────────────────────────────────────
409
410    #[test]
411    fn check_rules_all_have_fallow_prefix() {
412        for rule in CHECK_RULES {
413            assert!(
414                rule.id.starts_with("fallow/"),
415                "rule {} should start with fallow/",
416                rule.id
417            );
418        }
419    }
420
421    #[test]
422    fn check_rules_all_have_docs_path() {
423        for rule in CHECK_RULES {
424            assert!(
425                !rule.docs_path.is_empty(),
426                "rule {} should have a docs_path",
427                rule.id
428            );
429        }
430    }
431
432    #[test]
433    fn check_rules_no_duplicate_ids() {
434        let mut seen = rustc_hash::FxHashSet::default();
435        for rule in CHECK_RULES.iter().chain(HEALTH_RULES).chain(DUPES_RULES) {
436            assert!(seen.insert(rule.id), "duplicate rule id: {}", rule.id);
437        }
438    }
439
440    // ── check_meta ───────────────────────────────────────────────────
441
442    #[test]
443    fn check_meta_has_docs_and_rules() {
444        let meta = check_meta();
445        assert!(meta.get("docs").is_some());
446        assert!(meta.get("rules").is_some());
447        let rules = meta["rules"].as_object().unwrap();
448        // Verify all 13 rule categories are present (stripped fallow/ prefix)
449        assert_eq!(rules.len(), CHECK_RULES.len());
450        assert!(rules.contains_key("unused-file"));
451        assert!(rules.contains_key("unused-export"));
452        assert!(rules.contains_key("unused-type"));
453        assert!(rules.contains_key("unused-dependency"));
454        assert!(rules.contains_key("unused-dev-dependency"));
455        assert!(rules.contains_key("unused-optional-dependency"));
456        assert!(rules.contains_key("unused-enum-member"));
457        assert!(rules.contains_key("unused-class-member"));
458        assert!(rules.contains_key("unresolved-import"));
459        assert!(rules.contains_key("unlisted-dependency"));
460        assert!(rules.contains_key("duplicate-export"));
461        assert!(rules.contains_key("type-only-dependency"));
462        assert!(rules.contains_key("circular-dependency"));
463    }
464
465    #[test]
466    fn check_meta_rule_has_required_fields() {
467        let meta = check_meta();
468        let rules = meta["rules"].as_object().unwrap();
469        for (key, value) in rules {
470            assert!(value.get("name").is_some(), "rule {key} missing 'name'");
471            assert!(
472                value.get("description").is_some(),
473                "rule {key} missing 'description'"
474            );
475            assert!(value.get("docs").is_some(), "rule {key} missing 'docs'");
476        }
477    }
478
479    // ── health_meta ──────────────────────────────────────────────────
480
481    #[test]
482    fn health_meta_has_metrics() {
483        let meta = health_meta();
484        assert!(meta.get("docs").is_some());
485        let metrics = meta["metrics"].as_object().unwrap();
486        assert!(metrics.contains_key("cyclomatic"));
487        assert!(metrics.contains_key("cognitive"));
488        assert!(metrics.contains_key("maintainability_index"));
489        assert!(metrics.contains_key("complexity_density"));
490        assert!(metrics.contains_key("fan_in"));
491        assert!(metrics.contains_key("fan_out"));
492    }
493
494    // ── dupes_meta ───────────────────────────────────────────────────
495
496    #[test]
497    fn dupes_meta_has_metrics() {
498        let meta = dupes_meta();
499        assert!(meta.get("docs").is_some());
500        let metrics = meta["metrics"].as_object().unwrap();
501        assert!(metrics.contains_key("duplication_percentage"));
502        assert!(metrics.contains_key("token_count"));
503        assert!(metrics.contains_key("clone_groups"));
504        assert!(metrics.contains_key("clone_families"));
505    }
506
507    // ── HEALTH_RULES completeness ──────────────────────────────────
508
509    #[test]
510    fn health_rules_all_have_fallow_prefix() {
511        for rule in HEALTH_RULES {
512            assert!(
513                rule.id.starts_with("fallow/"),
514                "health rule {} should start with fallow/",
515                rule.id
516            );
517        }
518    }
519
520    #[test]
521    fn health_rules_all_have_docs_path() {
522        for rule in HEALTH_RULES {
523            assert!(
524                !rule.docs_path.is_empty(),
525                "health rule {} should have a docs_path",
526                rule.id
527            );
528        }
529    }
530
531    #[test]
532    fn health_rules_all_have_non_empty_fields() {
533        for rule in HEALTH_RULES {
534            assert!(
535                !rule.name.is_empty(),
536                "health rule {} missing name",
537                rule.id
538            );
539            assert!(
540                !rule.short.is_empty(),
541                "health rule {} missing short description",
542                rule.id
543            );
544            assert!(
545                !rule.full.is_empty(),
546                "health rule {} missing full description",
547                rule.id
548            );
549        }
550    }
551
552    // ── DUPES_RULES completeness ───────────────────────────────────
553
554    #[test]
555    fn dupes_rules_all_have_fallow_prefix() {
556        for rule in DUPES_RULES {
557            assert!(
558                rule.id.starts_with("fallow/"),
559                "dupes rule {} should start with fallow/",
560                rule.id
561            );
562        }
563    }
564
565    #[test]
566    fn dupes_rules_all_have_docs_path() {
567        for rule in DUPES_RULES {
568            assert!(
569                !rule.docs_path.is_empty(),
570                "dupes rule {} should have a docs_path",
571                rule.id
572            );
573        }
574    }
575
576    #[test]
577    fn dupes_rules_all_have_non_empty_fields() {
578        for rule in DUPES_RULES {
579            assert!(!rule.name.is_empty(), "dupes rule {} missing name", rule.id);
580            assert!(
581                !rule.short.is_empty(),
582                "dupes rule {} missing short description",
583                rule.id
584            );
585            assert!(
586                !rule.full.is_empty(),
587                "dupes rule {} missing full description",
588                rule.id
589            );
590        }
591    }
592
593    // ── CHECK_RULES field completeness ─────────────────────────────
594
595    #[test]
596    fn check_rules_all_have_non_empty_fields() {
597        for rule in CHECK_RULES {
598            assert!(!rule.name.is_empty(), "check rule {} missing name", rule.id);
599            assert!(
600                !rule.short.is_empty(),
601                "check rule {} missing short description",
602                rule.id
603            );
604            assert!(
605                !rule.full.is_empty(),
606                "check rule {} missing full description",
607                rule.id
608            );
609        }
610    }
611
612    // ── rule_docs_url with health/dupes rules ──────────────────────
613
614    #[test]
615    fn rule_docs_url_health_rule() {
616        let rule = rule_by_id("fallow/high-cyclomatic-complexity").unwrap();
617        let url = rule_docs_url(rule);
618        assert!(url.starts_with("https://docs.fallow.tools/"));
619        assert!(url.contains("health"));
620    }
621
622    #[test]
623    fn rule_docs_url_dupes_rule() {
624        let rule = rule_by_id("fallow/code-duplication").unwrap();
625        let url = rule_docs_url(rule);
626        assert!(url.starts_with("https://docs.fallow.tools/"));
627        assert!(url.contains("duplication"));
628    }
629
630    // ── health_meta metric structure ───────────────────────────────
631
632    #[test]
633    fn health_meta_all_metrics_have_name_and_description() {
634        let meta = health_meta();
635        let metrics = meta["metrics"].as_object().unwrap();
636        for (key, value) in metrics {
637            assert!(
638                value.get("name").is_some(),
639                "health metric {key} missing 'name'"
640            );
641            assert!(
642                value.get("description").is_some(),
643                "health metric {key} missing 'description'"
644            );
645            assert!(
646                value.get("interpretation").is_some(),
647                "health metric {key} missing 'interpretation'"
648            );
649        }
650    }
651
652    #[test]
653    fn health_meta_has_all_expected_metrics() {
654        let meta = health_meta();
655        let metrics = meta["metrics"].as_object().unwrap();
656        let expected = [
657            "cyclomatic",
658            "cognitive",
659            "line_count",
660            "maintainability_index",
661            "complexity_density",
662            "dead_code_ratio",
663            "fan_in",
664            "fan_out",
665            "score",
666            "weighted_commits",
667            "trend",
668            "priority",
669            "efficiency",
670            "effort",
671            "confidence",
672        ];
673        for key in &expected {
674            assert!(
675                metrics.contains_key(*key),
676                "health_meta missing expected metric: {key}"
677            );
678        }
679    }
680
681    // ── dupes_meta metric structure ────────────────────────────────
682
683    #[test]
684    fn dupes_meta_all_metrics_have_name_and_description() {
685        let meta = dupes_meta();
686        let metrics = meta["metrics"].as_object().unwrap();
687        for (key, value) in metrics {
688            assert!(
689                value.get("name").is_some(),
690                "dupes metric {key} missing 'name'"
691            );
692            assert!(
693                value.get("description").is_some(),
694                "dupes metric {key} missing 'description'"
695            );
696        }
697    }
698
699    #[test]
700    fn dupes_meta_has_line_count() {
701        let meta = dupes_meta();
702        let metrics = meta["metrics"].as_object().unwrap();
703        assert!(metrics.contains_key("line_count"));
704    }
705
706    // ── docs URLs ─────────────────────────────────────────────────
707
708    #[test]
709    fn check_docs_url_valid() {
710        assert!(CHECK_DOCS.starts_with("https://"));
711        assert!(CHECK_DOCS.contains("dead-code"));
712    }
713
714    #[test]
715    fn health_docs_url_valid() {
716        assert!(HEALTH_DOCS.starts_with("https://"));
717        assert!(HEALTH_DOCS.contains("health"));
718    }
719
720    #[test]
721    fn dupes_docs_url_valid() {
722        assert!(DUPES_DOCS.starts_with("https://"));
723        assert!(DUPES_DOCS.contains("dupes"));
724    }
725
726    // ── check_meta docs URL matches constant ──────────────────────
727
728    #[test]
729    fn check_meta_docs_url_matches_constant() {
730        let meta = check_meta();
731        assert_eq!(meta["docs"].as_str().unwrap(), CHECK_DOCS);
732    }
733
734    #[test]
735    fn health_meta_docs_url_matches_constant() {
736        let meta = health_meta();
737        assert_eq!(meta["docs"].as_str().unwrap(), HEALTH_DOCS);
738    }
739
740    #[test]
741    fn dupes_meta_docs_url_matches_constant() {
742        let meta = dupes_meta();
743        assert_eq!(meta["docs"].as_str().unwrap(), DUPES_DOCS);
744    }
745
746    // ── rule_by_id finds all check rules ──────────────────────────
747
748    #[test]
749    fn rule_by_id_finds_all_check_rules() {
750        for rule in CHECK_RULES {
751            assert!(
752                rule_by_id(rule.id).is_some(),
753                "rule_by_id should find check rule {}",
754                rule.id
755            );
756        }
757    }
758
759    #[test]
760    fn rule_by_id_finds_all_health_rules() {
761        for rule in HEALTH_RULES {
762            assert!(
763                rule_by_id(rule.id).is_some(),
764                "rule_by_id should find health rule {}",
765                rule.id
766            );
767        }
768    }
769
770    #[test]
771    fn rule_by_id_finds_all_dupes_rules() {
772        for rule in DUPES_RULES {
773            assert!(
774                rule_by_id(rule.id).is_some(),
775                "rule_by_id should find dupes rule {}",
776                rule.id
777            );
778        }
779    }
780
781    // ── Rule count verification ───────────────────────────────────
782
783    #[test]
784    fn check_rules_count() {
785        assert_eq!(CHECK_RULES.len(), 13);
786    }
787
788    #[test]
789    fn health_rules_count() {
790        assert_eq!(HEALTH_RULES.len(), 6);
791    }
792
793    #[test]
794    fn dupes_rules_count() {
795        assert_eq!(DUPES_RULES.len(), 1);
796    }
797}
fallow_cli/explain.rs

fallow_cli/
explain.rs
