1use serde_json::{Value, json};
8
9const DOCS_BASE: &str = "https://docs.fallow.tools";
12
13pub const CHECK_DOCS: &str = "https://docs.fallow.tools/cli/dead-code";
15
16pub const HEALTH_DOCS: &str = "https://docs.fallow.tools/cli/health";
18
19pub const DUPES_DOCS: &str = "https://docs.fallow.tools/cli/dupes";
21
22pub 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/private-type-leak",
57 name: "Private Type Leaks",
58 short: "Exported signature references a private type",
59 full: "Exported values or types whose public TypeScript signature references a same-file type declaration that is not exported. Consumers cannot name that private type directly, so the backing type should be exported or removed from the public signature.",
60 docs_path: "explanations/dead-code#private-type-leaks",
61 },
62 RuleDef {
63 id: "fallow/unused-dependency",
64 name: "Unused Dependencies",
65 short: "Dependency listed but never imported",
66 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.",
67 docs_path: "explanations/dead-code#unused-dependencies",
68 },
69 RuleDef {
70 id: "fallow/unused-dev-dependency",
71 name: "Unused Dev Dependencies",
72 short: "Dev dependency listed but never imported",
73 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.",
74 docs_path: "explanations/dead-code#unused-devdependencies",
75 },
76 RuleDef {
77 id: "fallow/unused-optional-dependency",
78 name: "Unused Optional Dependencies",
79 short: "Optional dependency listed but never imported",
80 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.",
81 docs_path: "explanations/dead-code#unused-optionaldependencies",
82 },
83 RuleDef {
84 id: "fallow/type-only-dependency",
85 name: "Type-only Dependencies",
86 short: "Production dependency only used via type-only imports",
87 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.",
88 docs_path: "explanations/dead-code#type-only-dependencies",
89 },
90 RuleDef {
91 id: "fallow/unused-enum-member",
92 name: "Unused Enum Members",
93 short: "Enum member is never referenced",
94 full: "Enum members that are never referenced in the codebase. Uses scope-aware binding analysis to track all references including computed access patterns.",
95 docs_path: "explanations/dead-code#unused-enum-members",
96 },
97 RuleDef {
98 id: "fallow/unused-class-member",
99 name: "Unused Class Members",
100 short: "Class member is never referenced",
101 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.",
102 docs_path: "explanations/dead-code#unused-class-members",
103 },
104 RuleDef {
105 id: "fallow/unresolved-import",
106 name: "Unresolved Imports",
107 short: "Import could not be resolved",
108 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.",
109 docs_path: "explanations/dead-code#unresolved-imports",
110 },
111 RuleDef {
112 id: "fallow/unlisted-dependency",
113 name: "Unlisted Dependencies",
114 short: "Dependency used but not in package.json",
115 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.",
116 docs_path: "explanations/dead-code#unlisted-dependencies",
117 },
118 RuleDef {
119 id: "fallow/duplicate-export",
120 name: "Duplicate Exports",
121 short: "Export name appears in multiple modules",
122 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.",
123 docs_path: "explanations/dead-code#duplicate-exports",
124 },
125 RuleDef {
126 id: "fallow/circular-dependency",
127 name: "Circular Dependencies",
128 short: "Circular dependency chain detected",
129 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.",
130 docs_path: "explanations/dead-code#circular-dependencies",
131 },
132 RuleDef {
133 id: "fallow/stale-suppression",
134 name: "Stale Suppressions",
135 short: "Suppression comment or tag no longer matches any issue",
136 full: "A fallow-ignore-next-line, fallow-ignore-file, or @expected-unused suppression that no longer matches any active issue. The underlying problem was fixed but the suppression was left behind. Remove it to keep the codebase clean.",
137 docs_path: "explanations/dead-code#stale-suppressions",
138 },
139];
140
141#[must_use]
143pub fn rule_by_id(id: &str) -> Option<&'static RuleDef> {
144 CHECK_RULES
145 .iter()
146 .chain(HEALTH_RULES.iter())
147 .chain(DUPES_RULES.iter())
148 .find(|r| r.id == id)
149}
150
151#[must_use]
153pub fn rule_docs_url(rule: &RuleDef) -> String {
154 format!("{DOCS_BASE}/{}", rule.docs_path)
155}
156
157pub const HEALTH_RULES: &[RuleDef] = &[
160 RuleDef {
161 id: "fallow/high-cyclomatic-complexity",
162 name: "High Cyclomatic Complexity",
163 short: "Function has high cyclomatic complexity",
164 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.",
165 docs_path: "explanations/health#cyclomatic-complexity",
166 },
167 RuleDef {
168 id: "fallow/high-cognitive-complexity",
169 name: "High Cognitive Complexity",
170 short: "Function has high cognitive complexity",
171 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.",
172 docs_path: "explanations/health#cognitive-complexity",
173 },
174 RuleDef {
175 id: "fallow/high-complexity",
176 name: "High Complexity (Both)",
177 short: "Function exceeds both complexity thresholds",
178 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.",
179 docs_path: "explanations/health#complexity-metrics",
180 },
181 RuleDef {
182 id: "fallow/high-crap-score",
183 name: "High CRAP Score",
184 short: "Function has a high CRAP score (complexity combined with low coverage)",
185 full: "The function's CRAP (Change Risk Anti-Patterns) score meets or exceeds the configured threshold. CRAP combines cyclomatic complexity with test coverage using the Savoia and Evans (2007) formula: `CC^2 * (1 - coverage/100)^3 + CC`. High CRAP indicates changes to this function carry high risk because it is complex AND poorly tested. Pair with `--coverage` for accurate per-function scoring; without it fallow estimates coverage from the module graph.",
186 docs_path: "explanations/health#crap-score",
187 },
188 RuleDef {
189 id: "fallow/refactoring-target",
190 name: "Refactoring Target",
191 short: "File identified as a high-priority refactoring candidate",
192 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.",
193 docs_path: "explanations/health#refactoring-targets",
194 },
195 RuleDef {
196 id: "fallow/untested-file",
197 name: "Untested File",
198 short: "Runtime-reachable file has no test dependency path",
199 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.",
200 docs_path: "explanations/health#coverage-gaps",
201 },
202 RuleDef {
203 id: "fallow/untested-export",
204 name: "Untested Export",
205 short: "Runtime-reachable export has no test dependency path",
206 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.",
207 docs_path: "explanations/health#coverage-gaps",
208 },
209 RuleDef {
210 id: "fallow/runtime-safe-to-delete",
211 name: "Production Safe To Delete",
212 short: "Statically unused AND never invoked in production with V8 tracking",
213 full: "The function is both statically unreachable in the module graph and was never invoked during the observed runtime coverage window. This is the highest-confidence delete signal fallow emits.",
214 docs_path: "explanations/health#runtime-coverage",
215 },
216 RuleDef {
217 id: "fallow/runtime-review-required",
218 name: "Production Review Required",
219 short: "Statically used but never invoked in production",
220 full: "The function is reachable in the module graph (or exercised by tests / untracked call sites) but was not invoked during the observed runtime coverage window. Needs a human look — may be seasonal, error-path only, or legitimately unused.",
221 docs_path: "explanations/health#runtime-coverage",
222 },
223 RuleDef {
224 id: "fallow/runtime-low-traffic",
225 name: "Production Low Traffic",
226 short: "Function was invoked below the low-traffic threshold",
227 full: "The function was invoked in production but below the configured `--low-traffic-threshold` fraction of total trace count (spec default 0.1%). Effectively dead for the current period.",
228 docs_path: "explanations/health#runtime-coverage",
229 },
230 RuleDef {
231 id: "fallow/runtime-coverage-unavailable",
232 name: "Runtime Coverage Unavailable",
233 short: "Runtime coverage could not be resolved for this function",
234 full: "The function could not be matched to a V8-tracked coverage entry. Common causes: the function lives in a worker thread (separate V8 isolate), it is lazy-parsed and never reached the JIT tier, or its source map did not resolve to the expected source path. This is advisory, not a dead-code signal.",
235 docs_path: "explanations/health#runtime-coverage",
236 },
237 RuleDef {
238 id: "fallow/runtime-coverage",
239 name: "Runtime Coverage",
240 short: "Runtime coverage finding",
241 full: "Generic runtime-coverage finding for verdicts not covered by a more specific rule. Covers the forward-compat `unknown` sentinel; the CLI filters `active` entries out of `runtime_coverage.findings` so the surfaced list stays actionable.",
242 docs_path: "explanations/health#runtime-coverage",
243 },
244];
245
246pub const DUPES_RULES: &[RuleDef] = &[RuleDef {
247 id: "fallow/code-duplication",
248 name: "Code Duplication",
249 short: "Duplicated code block",
250 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.",
251 docs_path: "explanations/duplication#clone-groups",
252}];
253
254#[must_use]
258pub fn check_meta() -> Value {
259 let rules: Value = CHECK_RULES
260 .iter()
261 .map(|r| {
262 (
263 r.id.replace("fallow/", ""),
264 json!({
265 "name": r.name,
266 "description": r.full,
267 "docs": rule_docs_url(r)
268 }),
269 )
270 })
271 .collect::<serde_json::Map<String, Value>>()
272 .into();
273
274 json!({
275 "docs": CHECK_DOCS,
276 "rules": rules
277 })
278}
279
280#[must_use]
282#[expect(
283 clippy::too_many_lines,
284 reason = "flat metric table: every entry is 3-4 short lines of metadata and keeping them in one map is clearer than splitting into per-metric helpers"
285)]
286pub fn health_meta() -> Value {
287 json!({
288 "docs": HEALTH_DOCS,
289 "metrics": {
290 "cyclomatic": {
291 "name": "Cyclomatic Complexity",
292 "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.",
293 "range": "[1, \u{221e})",
294 "interpretation": "lower is better; default threshold: 20"
295 },
296 "cognitive": {
297 "name": "Cognitive Complexity",
298 "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.",
299 "range": "[0, \u{221e})",
300 "interpretation": "lower is better; default threshold: 15"
301 },
302 "line_count": {
303 "name": "Function Line Count",
304 "description": "Number of lines in the function body.",
305 "range": "[1, \u{221e})",
306 "interpretation": "context-dependent; long functions may need splitting"
307 },
308 "lines": {
309 "name": "File Line Count",
310 "description": "Total lines of code in the file (from line offsets). Provides scale context for other metrics: a file with 0.4 complexity density at 80 LOC is different from 0.4 density at 800 LOC.",
311 "range": "[1, \u{221e})",
312 "interpretation": "context-dependent; large files may benefit from splitting even if individual functions are small"
313 },
314 "maintainability_index": {
315 "name": "Maintainability Index",
316 "description": "Composite score: 100 - (complexity_density \u{00d7} 30 \u{00d7} dampening) - (dead_code_ratio \u{00d7} 20) - min(ln(fan_out+1) \u{00d7} 4, 15), where dampening = min(lines/50, 1.0). Clamped to [0, 100]. Higher is better.",
317 "range": "[0, 100]",
318 "interpretation": "higher is better; <40 poor, 40\u{2013}70 moderate, >70 good"
319 },
320 "complexity_density": {
321 "name": "Complexity Density",
322 "description": "Total cyclomatic complexity divided by lines of code. Measures how densely complex the code is per line.",
323 "range": "[0, \u{221e})",
324 "interpretation": "lower is better; >1.0 indicates very dense complexity"
325 },
326 "dead_code_ratio": {
327 "name": "Dead Code Ratio",
328 "description": "Fraction of value exports (excluding type-only exports like interfaces and type aliases) with zero references across the project.",
329 "range": "[0, 1]",
330 "interpretation": "lower is better; 0 = all exports are used"
331 },
332 "fan_in": {
333 "name": "Fan-in (Importers)",
334 "description": "Number of files that import this file. High fan-in means high blast radius \u{2014} changes to this file affect many dependents.",
335 "range": "[0, \u{221e})",
336 "interpretation": "context-dependent; high fan-in files need careful review before changes"
337 },
338 "fan_out": {
339 "name": "Fan-out (Imports)",
340 "description": "Number of files this file directly imports. High fan-out indicates high coupling and change propagation risk.",
341 "range": "[0, \u{221e})",
342 "interpretation": "lower is better; MI penalty caps at ~40 imports"
343 },
344 "score": {
345 "name": "Hotspot Score",
346 "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.",
347 "range": "[0, 100]",
348 "interpretation": "higher = riskier; prioritize refactoring high-score files"
349 },
350 "weighted_commits": {
351 "name": "Weighted Commits",
352 "description": "Recency-weighted commit count using exponential decay with 90-day half-life. Recent commits contribute more than older ones.",
353 "range": "[0, \u{221e})",
354 "interpretation": "higher = more recent churn activity"
355 },
356 "trend": {
357 "name": "Churn Trend",
358 "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.",
359 "values": ["accelerating", "stable", "cooling"],
360 "interpretation": "accelerating files need attention; cooling files are stabilizing"
361 },
362 "priority": {
363 "name": "Refactoring Priority",
364 "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.",
365 "range": "[0, 100]",
366 "interpretation": "higher = more urgent to refactor"
367 },
368 "efficiency": {
369 "name": "Efficiency Score",
370 "description": "priority / effort_numeric (Low=1, Medium=2, High=3). Surfaces quick wins: high-priority, low-effort targets rank first. Default sort order.",
371 "range": "[0, 100] \u{2014} effective max depends on effort: Low=100, Medium=50, High\u{2248}33",
372 "interpretation": "higher = better quick-win value; targets are sorted by efficiency descending"
373 },
374 "effort": {
375 "name": "Effort Estimate",
376 "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.",
377 "values": ["low", "medium", "high"],
378 "interpretation": "low = quick win, high = needs planning and coordination"
379 },
380 "confidence": {
381 "name": "Confidence Level",
382 "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).",
383 "values": ["high", "medium", "low"],
384 "interpretation": "high = act on it, medium = verify context, low = treat as a signal, not a directive"
385 },
386 "health_score": {
387 "name": "Health Score",
388 "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 compute the score; add --hotspots, or --targets with --score, when the score should include the churn-backed hotspot penalty.",
389 "range": "[0, 100]",
390 "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)"
391 },
392 "crap_max": {
393 "name": "Untested Complexity Risk (CRAP)",
394 "description": "Change Risk Anti-Patterns score (Savoia & Evans, 2007). Formula: CC\u{00b2} \u{00d7} (1 - cov/100)\u{00b3} + CC. Default model (static_estimated): estimates per-function coverage from export references \u{2014} directly test-referenced exports get 85%, indirectly test-reachable functions get 40%, untested files get 0%. Provide --coverage <path> with Istanbul-format coverage-final.json (from Jest, Vitest, c8, nyc) for exact per-function CRAP scores.",
395 "range": "[1, \u{221e})",
396 "interpretation": "lower is better; >=30 is high-risk (CC >= 5 without test path)"
397 },
398 "bus_factor": {
399 "name": "Bus Factor",
400 "description": "Avelino truck factor: the minimum number of distinct contributors who together account for at least 50% of recency-weighted commits to this file in the analysis window. Bot authors are excluded.",
401 "range": "[1, \u{221e})",
402 "interpretation": "lower is higher knowledge-loss risk; 1 means a single contributor covers most of the recent history"
403 },
404 "contributor_count": {
405 "name": "Contributor Count",
406 "description": "Number of distinct authors who touched this file in the analysis window after bot-pattern filtering.",
407 "range": "[0, \u{221e})",
408 "interpretation": "higher generally indicates broader knowledge spread; pair with bus_factor for context"
409 },
410 "share": {
411 "name": "Contributor Share",
412 "description": "Recency-weighted share of total weighted commits attributed to a single contributor. Rounded to three decimals.",
413 "range": "[0, 1]",
414 "interpretation": "share close to 1.0 indicates dominance and pairs with low bus_factor"
415 },
416 "stale_days": {
417 "name": "Stale Days",
418 "description": "Days since this contributor last touched the file. Computed at analysis time.",
419 "range": "[0, \u{221e})",
420 "interpretation": "high stale_days on the top contributor often correlates with ownership drift"
421 },
422 "drift": {
423 "name": "Ownership Drift",
424 "description": "True when the file's original author (earliest first commit in the window) differs from the current top contributor, the file is at least 30 days old, and the original author's recency-weighted share is below 10%.",
425 "values": [true, false],
426 "interpretation": "true means the original author is no longer maintaining; route reviews to the current top contributor"
427 },
428 "unowned": {
429 "name": "Unowned (Tristate)",
430 "description": "true = a CODEOWNERS file exists but no rule matches this file; false = a rule matches; null = no CODEOWNERS file was discovered for the repository (cannot determine).",
431 "values": [true, false, null],
432 "interpretation": "true on a hotspot is a review-bottleneck risk; null means the signal is unavailable, not absent"
433 },
434 "runtime_coverage_verdict": {
435 "name": "Runtime Coverage Verdict",
436 "description": "Overall verdict across all runtime-coverage findings. `clean` = nothing cold; `cold-code-detected` = one or more tracked functions had zero invocations; `hot-path-changes-needed` = a function modified in the current change set is on the hot path; `license-expired-grace` = analysis ran but the license is in its post-expiry grace window; `unknown` = verdict could not be computed (degenerate input).",
437 "values": ["clean", "hot-path-changes-needed", "cold-code-detected", "license-expired-grace", "unknown"],
438 "interpretation": "`cold-code-detected` is the primary actionable signal; `hot-path-changes-needed` elevates code-review attention for touched hot paths"
439 },
440 "runtime_coverage_state": {
441 "name": "Runtime Coverage State",
442 "description": "Per-function observation: `called` = V8 saw at least one invocation; `never-called` = V8 tracked the function but it never ran; `coverage-unavailable` = the function was not in the V8 tracking set (e.g., lazy-parsed, worker thread, dynamic code); `unknown` = forward-compat sentinel for newer sidecar states.",
443 "values": ["called", "never-called", "coverage-unavailable", "unknown"],
444 "interpretation": "`never-called` in combination with static `unused` is the highest-confidence delete signal"
445 },
446 "runtime_coverage_confidence": {
447 "name": "Runtime Coverage Confidence",
448 "description": "Confidence in a runtime-coverage finding. `high` = tracked by V8 with a statistically meaningful observation volume; `medium` = either low observation volume or indirect evidence; `low` = minimal data; `unknown` = insufficient information to classify.",
449 "values": ["high", "medium", "low", "unknown"],
450 "interpretation": "high = act on it; medium = verify context; low = treat as a signal only"
451 },
452 "production_invocations": {
453 "name": "Production Invocations",
454 "description": "Observed invocation count for the function over the collected coverage window. For `coverage-unavailable` findings this is `0` and semantically means `null` (not tracked). Absolute counts are not directly comparable across services without normalizing by trace_count.",
455 "range": "[0, \u{221e})",
456 "interpretation": "0 + tracked = cold path; 0 + untracked = unknown; high + never-called cannot occur by definition"
457 },
458 "percent_dead_in_production": {
459 "name": "Percent Dead in Production",
460 "description": "Fraction of tracked functions with zero observed invocations, multiplied by 100. Computed before any `--top` truncation so the summary total is stable regardless of display limits.",
461 "range": "[0, 100]",
462 "interpretation": "lower is better; values above ~10% on a long-running service indicate a large cleanup opportunity"
463 }
464 }
465 })
466}
467
468#[must_use]
470pub fn dupes_meta() -> Value {
471 json!({
472 "docs": DUPES_DOCS,
473 "metrics": {
474 "duplication_percentage": {
475 "name": "Duplication Percentage",
476 "description": "Fraction of total source tokens that appear in at least one clone group. Computed over the full analyzed file set.",
477 "range": "[0, 100]",
478 "interpretation": "lower is better"
479 },
480 "token_count": {
481 "name": "Token Count",
482 "description": "Number of normalized source tokens in the clone group. Tokens are language-aware (keywords, identifiers, operators, punctuation). Higher token count = larger duplicate.",
483 "range": "[1, \u{221e})",
484 "interpretation": "larger clones have higher refactoring value"
485 },
486 "line_count": {
487 "name": "Line Count",
488 "description": "Number of source lines spanned by the clone instance. Approximation of clone size for human readability.",
489 "range": "[1, \u{221e})",
490 "interpretation": "larger clones are more impactful to deduplicate"
491 },
492 "clone_groups": {
493 "name": "Clone Groups",
494 "description": "A set of code fragments with identical or near-identical normalized token sequences. Each group has 2+ instances across different locations.",
495 "interpretation": "each group is a single refactoring opportunity"
496 },
497 "clone_families": {
498 "name": "Clone Families",
499 "description": "Groups of clone groups that share the same set of files. Indicates systematic duplication patterns (e.g., mirrored directory structures).",
500 "interpretation": "families suggest extract-module refactoring opportunities"
501 }
502 }
503 })
504}
505
506#[cfg(test)]
507mod tests {
508 use super::*;
509
510 #[test]
513 fn rule_by_id_finds_check_rule() {
514 let rule = rule_by_id("fallow/unused-file").unwrap();
515 assert_eq!(rule.name, "Unused Files");
516 }
517
518 #[test]
519 fn rule_by_id_finds_health_rule() {
520 let rule = rule_by_id("fallow/high-cyclomatic-complexity").unwrap();
521 assert_eq!(rule.name, "High Cyclomatic Complexity");
522 }
523
524 #[test]
525 fn rule_by_id_finds_dupes_rule() {
526 let rule = rule_by_id("fallow/code-duplication").unwrap();
527 assert_eq!(rule.name, "Code Duplication");
528 }
529
530 #[test]
531 fn rule_by_id_returns_none_for_unknown() {
532 assert!(rule_by_id("fallow/nonexistent").is_none());
533 assert!(rule_by_id("").is_none());
534 }
535
536 #[test]
539 fn rule_docs_url_format() {
540 let rule = rule_by_id("fallow/unused-export").unwrap();
541 let url = rule_docs_url(rule);
542 assert!(url.starts_with("https://docs.fallow.tools/"));
543 assert!(url.contains("unused-exports"));
544 }
545
546 #[test]
549 fn check_rules_all_have_fallow_prefix() {
550 for rule in CHECK_RULES {
551 assert!(
552 rule.id.starts_with("fallow/"),
553 "rule {} should start with fallow/",
554 rule.id
555 );
556 }
557 }
558
559 #[test]
560 fn check_rules_all_have_docs_path() {
561 for rule in CHECK_RULES {
562 assert!(
563 !rule.docs_path.is_empty(),
564 "rule {} should have a docs_path",
565 rule.id
566 );
567 }
568 }
569
570 #[test]
571 fn check_rules_no_duplicate_ids() {
572 let mut seen = rustc_hash::FxHashSet::default();
573 for rule in CHECK_RULES.iter().chain(HEALTH_RULES).chain(DUPES_RULES) {
574 assert!(seen.insert(rule.id), "duplicate rule id: {}", rule.id);
575 }
576 }
577
578 #[test]
581 fn check_meta_has_docs_and_rules() {
582 let meta = check_meta();
583 assert!(meta.get("docs").is_some());
584 assert!(meta.get("rules").is_some());
585 let rules = meta["rules"].as_object().unwrap();
586 assert_eq!(rules.len(), CHECK_RULES.len());
588 assert!(rules.contains_key("unused-file"));
589 assert!(rules.contains_key("unused-export"));
590 assert!(rules.contains_key("unused-type"));
591 assert!(rules.contains_key("unused-dependency"));
592 assert!(rules.contains_key("unused-dev-dependency"));
593 assert!(rules.contains_key("unused-optional-dependency"));
594 assert!(rules.contains_key("unused-enum-member"));
595 assert!(rules.contains_key("unused-class-member"));
596 assert!(rules.contains_key("unresolved-import"));
597 assert!(rules.contains_key("unlisted-dependency"));
598 assert!(rules.contains_key("duplicate-export"));
599 assert!(rules.contains_key("type-only-dependency"));
600 assert!(rules.contains_key("circular-dependency"));
601 }
602
603 #[test]
604 fn check_meta_rule_has_required_fields() {
605 let meta = check_meta();
606 let rules = meta["rules"].as_object().unwrap();
607 for (key, value) in rules {
608 assert!(value.get("name").is_some(), "rule {key} missing 'name'");
609 assert!(
610 value.get("description").is_some(),
611 "rule {key} missing 'description'"
612 );
613 assert!(value.get("docs").is_some(), "rule {key} missing 'docs'");
614 }
615 }
616
617 #[test]
620 fn health_meta_has_metrics() {
621 let meta = health_meta();
622 assert!(meta.get("docs").is_some());
623 let metrics = meta["metrics"].as_object().unwrap();
624 assert!(metrics.contains_key("cyclomatic"));
625 assert!(metrics.contains_key("cognitive"));
626 assert!(metrics.contains_key("maintainability_index"));
627 assert!(metrics.contains_key("complexity_density"));
628 assert!(metrics.contains_key("fan_in"));
629 assert!(metrics.contains_key("fan_out"));
630 }
631
632 #[test]
635 fn dupes_meta_has_metrics() {
636 let meta = dupes_meta();
637 assert!(meta.get("docs").is_some());
638 let metrics = meta["metrics"].as_object().unwrap();
639 assert!(metrics.contains_key("duplication_percentage"));
640 assert!(metrics.contains_key("token_count"));
641 assert!(metrics.contains_key("clone_groups"));
642 assert!(metrics.contains_key("clone_families"));
643 }
644
645 #[test]
648 fn health_rules_all_have_fallow_prefix() {
649 for rule in HEALTH_RULES {
650 assert!(
651 rule.id.starts_with("fallow/"),
652 "health rule {} should start with fallow/",
653 rule.id
654 );
655 }
656 }
657
658 #[test]
659 fn health_rules_all_have_docs_path() {
660 for rule in HEALTH_RULES {
661 assert!(
662 !rule.docs_path.is_empty(),
663 "health rule {} should have a docs_path",
664 rule.id
665 );
666 }
667 }
668
669 #[test]
670 fn health_rules_all_have_non_empty_fields() {
671 for rule in HEALTH_RULES {
672 assert!(
673 !rule.name.is_empty(),
674 "health rule {} missing name",
675 rule.id
676 );
677 assert!(
678 !rule.short.is_empty(),
679 "health rule {} missing short description",
680 rule.id
681 );
682 assert!(
683 !rule.full.is_empty(),
684 "health rule {} missing full description",
685 rule.id
686 );
687 }
688 }
689
690 #[test]
693 fn dupes_rules_all_have_fallow_prefix() {
694 for rule in DUPES_RULES {
695 assert!(
696 rule.id.starts_with("fallow/"),
697 "dupes rule {} should start with fallow/",
698 rule.id
699 );
700 }
701 }
702
703 #[test]
704 fn dupes_rules_all_have_docs_path() {
705 for rule in DUPES_RULES {
706 assert!(
707 !rule.docs_path.is_empty(),
708 "dupes rule {} should have a docs_path",
709 rule.id
710 );
711 }
712 }
713
714 #[test]
715 fn dupes_rules_all_have_non_empty_fields() {
716 for rule in DUPES_RULES {
717 assert!(!rule.name.is_empty(), "dupes rule {} missing name", rule.id);
718 assert!(
719 !rule.short.is_empty(),
720 "dupes rule {} missing short description",
721 rule.id
722 );
723 assert!(
724 !rule.full.is_empty(),
725 "dupes rule {} missing full description",
726 rule.id
727 );
728 }
729 }
730
731 #[test]
734 fn check_rules_all_have_non_empty_fields() {
735 for rule in CHECK_RULES {
736 assert!(!rule.name.is_empty(), "check rule {} missing name", rule.id);
737 assert!(
738 !rule.short.is_empty(),
739 "check rule {} missing short description",
740 rule.id
741 );
742 assert!(
743 !rule.full.is_empty(),
744 "check rule {} missing full description",
745 rule.id
746 );
747 }
748 }
749
750 #[test]
753 fn rule_docs_url_health_rule() {
754 let rule = rule_by_id("fallow/high-cyclomatic-complexity").unwrap();
755 let url = rule_docs_url(rule);
756 assert!(url.starts_with("https://docs.fallow.tools/"));
757 assert!(url.contains("health"));
758 }
759
760 #[test]
761 fn rule_docs_url_dupes_rule() {
762 let rule = rule_by_id("fallow/code-duplication").unwrap();
763 let url = rule_docs_url(rule);
764 assert!(url.starts_with("https://docs.fallow.tools/"));
765 assert!(url.contains("duplication"));
766 }
767
768 #[test]
771 fn health_meta_all_metrics_have_name_and_description() {
772 let meta = health_meta();
773 let metrics = meta["metrics"].as_object().unwrap();
774 for (key, value) in metrics {
775 assert!(
776 value.get("name").is_some(),
777 "health metric {key} missing 'name'"
778 );
779 assert!(
780 value.get("description").is_some(),
781 "health metric {key} missing 'description'"
782 );
783 assert!(
784 value.get("interpretation").is_some(),
785 "health metric {key} missing 'interpretation'"
786 );
787 }
788 }
789
790 #[test]
791 fn health_meta_has_all_expected_metrics() {
792 let meta = health_meta();
793 let metrics = meta["metrics"].as_object().unwrap();
794 let expected = [
795 "cyclomatic",
796 "cognitive",
797 "line_count",
798 "lines",
799 "maintainability_index",
800 "complexity_density",
801 "dead_code_ratio",
802 "fan_in",
803 "fan_out",
804 "score",
805 "weighted_commits",
806 "trend",
807 "priority",
808 "efficiency",
809 "effort",
810 "confidence",
811 "bus_factor",
812 "contributor_count",
813 "share",
814 "stale_days",
815 "drift",
816 "unowned",
817 "runtime_coverage_verdict",
818 "runtime_coverage_state",
819 "runtime_coverage_confidence",
820 "production_invocations",
821 "percent_dead_in_production",
822 ];
823 for key in &expected {
824 assert!(
825 metrics.contains_key(*key),
826 "health_meta missing expected metric: {key}"
827 );
828 }
829 }
830
831 #[test]
834 fn dupes_meta_all_metrics_have_name_and_description() {
835 let meta = dupes_meta();
836 let metrics = meta["metrics"].as_object().unwrap();
837 for (key, value) in metrics {
838 assert!(
839 value.get("name").is_some(),
840 "dupes metric {key} missing 'name'"
841 );
842 assert!(
843 value.get("description").is_some(),
844 "dupes metric {key} missing 'description'"
845 );
846 }
847 }
848
849 #[test]
850 fn dupes_meta_has_line_count() {
851 let meta = dupes_meta();
852 let metrics = meta["metrics"].as_object().unwrap();
853 assert!(metrics.contains_key("line_count"));
854 }
855
856 #[test]
859 fn check_docs_url_valid() {
860 assert!(CHECK_DOCS.starts_with("https://"));
861 assert!(CHECK_DOCS.contains("dead-code"));
862 }
863
864 #[test]
865 fn health_docs_url_valid() {
866 assert!(HEALTH_DOCS.starts_with("https://"));
867 assert!(HEALTH_DOCS.contains("health"));
868 }
869
870 #[test]
871 fn dupes_docs_url_valid() {
872 assert!(DUPES_DOCS.starts_with("https://"));
873 assert!(DUPES_DOCS.contains("dupes"));
874 }
875
876 #[test]
879 fn check_meta_docs_url_matches_constant() {
880 let meta = check_meta();
881 assert_eq!(meta["docs"].as_str().unwrap(), CHECK_DOCS);
882 }
883
884 #[test]
885 fn health_meta_docs_url_matches_constant() {
886 let meta = health_meta();
887 assert_eq!(meta["docs"].as_str().unwrap(), HEALTH_DOCS);
888 }
889
890 #[test]
891 fn dupes_meta_docs_url_matches_constant() {
892 let meta = dupes_meta();
893 assert_eq!(meta["docs"].as_str().unwrap(), DUPES_DOCS);
894 }
895
896 #[test]
899 fn rule_by_id_finds_all_check_rules() {
900 for rule in CHECK_RULES {
901 assert!(
902 rule_by_id(rule.id).is_some(),
903 "rule_by_id should find check rule {}",
904 rule.id
905 );
906 }
907 }
908
909 #[test]
910 fn rule_by_id_finds_all_health_rules() {
911 for rule in HEALTH_RULES {
912 assert!(
913 rule_by_id(rule.id).is_some(),
914 "rule_by_id should find health rule {}",
915 rule.id
916 );
917 }
918 }
919
920 #[test]
921 fn rule_by_id_finds_all_dupes_rules() {
922 for rule in DUPES_RULES {
923 assert!(
924 rule_by_id(rule.id).is_some(),
925 "rule_by_id should find dupes rule {}",
926 rule.id
927 );
928 }
929 }
930
931 #[test]
934 fn check_rules_count() {
935 assert_eq!(CHECK_RULES.len(), 15);
936 }
937
938 #[test]
939 fn health_rules_count() {
940 assert_eq!(HEALTH_RULES.len(), 12);
941 }
942
943 #[test]
944 fn dupes_rules_count() {
945 assert_eq!(DUPES_RULES.len(), 1);
946 }
947}