use serde_json::{Value, json};
const DOCS_BASE: &str = "https://docs.fallow.tools";
pub const CHECK_DOCS: &str = "https://docs.fallow.tools/cli/dead-code";
pub const HEALTH_DOCS: &str = "https://docs.fallow.tools/cli/health";
pub const DUPES_DOCS: &str = "https://docs.fallow.tools/cli/dupes";
pub struct RuleDef {
pub id: &'static str,
pub name: &'static str,
pub short: &'static str,
pub full: &'static str,
pub docs_path: &'static str,
}
pub const CHECK_RULES: &[RuleDef] = &[
RuleDef {
id: "fallow/unused-file",
name: "Unused Files",
short: "File is not reachable from any entry point",
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.",
docs_path: "explanations/dead-code#unused-files",
},
RuleDef {
id: "fallow/unused-export",
name: "Unused Exports",
short: "Export is never imported",
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.",
docs_path: "explanations/dead-code#unused-exports",
},
RuleDef {
id: "fallow/unused-type",
name: "Unused Type Exports",
short: "Type export is never imported",
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.",
docs_path: "explanations/dead-code#unused-types",
},
RuleDef {
id: "fallow/unused-dependency",
name: "Unused Dependencies",
short: "Dependency listed but never imported",
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.",
docs_path: "explanations/dead-code#unused-dependencies",
},
RuleDef {
id: "fallow/unused-dev-dependency",
name: "Unused Dev Dependencies",
short: "Dev dependency listed but never imported",
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.",
docs_path: "explanations/dead-code#unused-devdependencies",
},
RuleDef {
id: "fallow/unused-optional-dependency",
name: "Unused Optional Dependencies",
short: "Optional dependency listed but never imported",
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.",
docs_path: "explanations/dead-code#unused-optionaldependencies",
},
RuleDef {
id: "fallow/type-only-dependency",
name: "Type-only Dependencies",
short: "Production dependency only used via type-only imports",
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.",
docs_path: "explanations/dead-code#type-only-dependencies",
},
RuleDef {
id: "fallow/unused-enum-member",
name: "Unused Enum Members",
short: "Enum member is never referenced",
full: "Enum members that are never referenced in the codebase. Uses scope-aware binding analysis to track all references including computed access patterns.",
docs_path: "explanations/dead-code#unused-enum-members",
},
RuleDef {
id: "fallow/unused-class-member",
name: "Unused Class Members",
short: "Class member is never referenced",
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.",
docs_path: "explanations/dead-code#unused-class-members",
},
RuleDef {
id: "fallow/unresolved-import",
name: "Unresolved Imports",
short: "Import could not be resolved",
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.",
docs_path: "explanations/dead-code#unresolved-imports",
},
RuleDef {
id: "fallow/unlisted-dependency",
name: "Unlisted Dependencies",
short: "Dependency used but not in package.json",
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.",
docs_path: "explanations/dead-code#unlisted-dependencies",
},
RuleDef {
id: "fallow/duplicate-export",
name: "Duplicate Exports",
short: "Export name appears in multiple modules",
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.",
docs_path: "explanations/dead-code#duplicate-exports",
},
RuleDef {
id: "fallow/circular-dependency",
name: "Circular Dependencies",
short: "Circular dependency chain detected",
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.",
docs_path: "explanations/dead-code#circular-dependencies",
},
];
#[must_use]
pub fn rule_by_id(id: &str) -> Option<&'static RuleDef> {
CHECK_RULES
.iter()
.chain(HEALTH_RULES.iter())
.chain(DUPES_RULES.iter())
.find(|r| r.id == id)
}
#[must_use]
pub fn rule_docs_url(rule: &RuleDef) -> String {
format!("{DOCS_BASE}/{}", rule.docs_path)
}
pub const HEALTH_RULES: &[RuleDef] = &[
RuleDef {
id: "fallow/high-cyclomatic-complexity",
name: "High Cyclomatic Complexity",
short: "Function has high cyclomatic complexity",
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.",
docs_path: "explanations/health#cyclomatic-complexity",
},
RuleDef {
id: "fallow/high-cognitive-complexity",
name: "High Cognitive Complexity",
short: "Function has high cognitive complexity",
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.",
docs_path: "explanations/health#cognitive-complexity",
},
RuleDef {
id: "fallow/high-complexity",
name: "High Complexity (Both)",
short: "Function exceeds both complexity thresholds",
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.",
docs_path: "explanations/health#complexity-metrics",
},
RuleDef {
id: "fallow/refactoring-target",
name: "Refactoring Target",
short: "File identified as a high-priority refactoring candidate",
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.",
docs_path: "explanations/health#refactoring-targets",
},
];
pub const DUPES_RULES: &[RuleDef] = &[RuleDef {
id: "fallow/code-duplication",
name: "Code Duplication",
short: "Duplicated code block",
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.",
docs_path: "explanations/duplication#clone-groups",
}];
#[must_use]
pub fn check_meta() -> Value {
let rules: Value = CHECK_RULES
.iter()
.map(|r| {
(
r.id.replace("fallow/", ""),
json!({
"name": r.name,
"description": r.full,
"docs": rule_docs_url(r)
}),
)
})
.collect::<serde_json::Map<String, Value>>()
.into();
json!({
"docs": CHECK_DOCS,
"rules": rules
})
}
#[must_use]
pub fn health_meta() -> Value {
json!({
"docs": HEALTH_DOCS,
"metrics": {
"cyclomatic": {
"name": "Cyclomatic Complexity",
"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.",
"range": "[1, \u{221e})",
"interpretation": "lower is better; default threshold: 20"
},
"cognitive": {
"name": "Cognitive Complexity",
"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.",
"range": "[0, \u{221e})",
"interpretation": "lower is better; default threshold: 15"
},
"line_count": {
"name": "Line Count",
"description": "Number of lines in the function body.",
"range": "[1, \u{221e})",
"interpretation": "context-dependent; long functions may need splitting"
},
"maintainability_index": {
"name": "Maintainability Index",
"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.",
"range": "[0, 100]",
"interpretation": "higher is better; <40 poor, 40\u{2013}70 moderate, >70 good"
},
"complexity_density": {
"name": "Complexity Density",
"description": "Total cyclomatic complexity divided by lines of code. Measures how densely complex the code is per line.",
"range": "[0, \u{221e})",
"interpretation": "lower is better; >1.0 indicates very dense complexity"
},
"dead_code_ratio": {
"name": "Dead Code Ratio",
"description": "Fraction of value exports (excluding type-only exports like interfaces and type aliases) with zero references across the project.",
"range": "[0, 1]",
"interpretation": "lower is better; 0 = all exports are used"
},
"fan_in": {
"name": "Fan-in (Importers)",
"description": "Number of files that import this file. High fan-in means high blast radius \u{2014} changes to this file affect many dependents.",
"range": "[0, \u{221e})",
"interpretation": "context-dependent; high fan-in files need careful review before changes"
},
"fan_out": {
"name": "Fan-out (Imports)",
"description": "Number of files this file directly imports. High fan-out indicates high coupling and change propagation risk.",
"range": "[0, \u{221e})",
"interpretation": "lower is better; MI penalty caps at ~40 imports"
},
"score": {
"name": "Hotspot Score",
"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.",
"range": "[0, 100]",
"interpretation": "higher = riskier; prioritize refactoring high-score files"
},
"weighted_commits": {
"name": "Weighted Commits",
"description": "Recency-weighted commit count using exponential decay with 90-day half-life. Recent commits contribute more than older ones.",
"range": "[0, \u{221e})",
"interpretation": "higher = more recent churn activity"
},
"trend": {
"name": "Churn Trend",
"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.",
"values": ["accelerating", "stable", "cooling"],
"interpretation": "accelerating files need attention; cooling files are stabilizing"
},
"priority": {
"name": "Refactoring Priority",
"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.",
"range": "[0, 100]",
"interpretation": "higher = more urgent to refactor"
},
"efficiency": {
"name": "Efficiency Score",
"description": "priority / effort_numeric (Low=1, Medium=2, High=3). Surfaces quick wins: high-priority, low-effort targets rank first. Default sort order.",
"range": "[0, 100] \u{2014} effective max depends on effort: Low=100, Medium=50, High\u{2248}33",
"interpretation": "higher = better quick-win value; targets are sorted by efficiency descending"
},
"effort": {
"name": "Effort Estimate",
"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.",
"values": ["low", "medium", "high"],
"interpretation": "low = quick win, high = needs planning and coordination"
},
"confidence": {
"name": "Confidence Level",
"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).",
"values": ["high", "medium", "low"],
"interpretation": "high = act on it, medium = verify context, low = treat as a signal, not a directive"
},
"health_score": {
"name": "Health Score",
"description": "Project-level aggregate score computed from vital signs: dead code, complexity, maintainability, hotspots, unused deps, and circular deps. Penalties subtracted from 100. Missing metrics (from pipelines that didn't run) don't penalize. Use --score to force full pipeline for maximum accuracy.",
"range": "[0, 100]",
"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)"
}
}
})
}
#[must_use]
pub fn dupes_meta() -> Value {
json!({
"docs": DUPES_DOCS,
"metrics": {
"duplication_percentage": {
"name": "Duplication Percentage",
"description": "Fraction of total source tokens that appear in at least one clone group. Computed over the full analyzed file set.",
"range": "[0, 100]",
"interpretation": "lower is better"
},
"token_count": {
"name": "Token Count",
"description": "Number of normalized source tokens in the clone group. Tokens are language-aware (keywords, identifiers, operators, punctuation). Higher token count = larger duplicate.",
"range": "[1, \u{221e})",
"interpretation": "larger clones have higher refactoring value"
},
"line_count": {
"name": "Line Count",
"description": "Number of source lines spanned by the clone instance. Approximation of clone size for human readability.",
"range": "[1, \u{221e})",
"interpretation": "larger clones are more impactful to deduplicate"
},
"clone_groups": {
"name": "Clone Groups",
"description": "A set of code fragments with identical or near-identical normalized token sequences. Each group has 2+ instances across different locations.",
"interpretation": "each group is a single refactoring opportunity"
},
"clone_families": {
"name": "Clone Families",
"description": "Groups of clone groups that share the same set of files. Indicates systematic duplication patterns (e.g., mirrored directory structures).",
"interpretation": "families suggest extract-module refactoring opportunities"
}
}
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn rule_by_id_finds_check_rule() {
let rule = rule_by_id("fallow/unused-file").unwrap();
assert_eq!(rule.name, "Unused Files");
}
#[test]
fn rule_by_id_finds_health_rule() {
let rule = rule_by_id("fallow/high-cyclomatic-complexity").unwrap();
assert_eq!(rule.name, "High Cyclomatic Complexity");
}
#[test]
fn rule_by_id_finds_dupes_rule() {
let rule = rule_by_id("fallow/code-duplication").unwrap();
assert_eq!(rule.name, "Code Duplication");
}
#[test]
fn rule_by_id_returns_none_for_unknown() {
assert!(rule_by_id("fallow/nonexistent").is_none());
assert!(rule_by_id("").is_none());
}
#[test]
fn rule_docs_url_format() {
let rule = rule_by_id("fallow/unused-export").unwrap();
let url = rule_docs_url(rule);
assert!(url.starts_with("https://docs.fallow.tools/"));
assert!(url.contains("unused-exports"));
}
#[test]
fn check_rules_all_have_fallow_prefix() {
for rule in CHECK_RULES {
assert!(
rule.id.starts_with("fallow/"),
"rule {} should start with fallow/",
rule.id
);
}
}
#[test]
fn check_rules_all_have_docs_path() {
for rule in CHECK_RULES {
assert!(
!rule.docs_path.is_empty(),
"rule {} should have a docs_path",
rule.id
);
}
}
#[test]
fn check_rules_no_duplicate_ids() {
let mut seen = rustc_hash::FxHashSet::default();
for rule in CHECK_RULES.iter().chain(HEALTH_RULES).chain(DUPES_RULES) {
assert!(seen.insert(rule.id), "duplicate rule id: {}", rule.id);
}
}
#[test]
fn check_meta_has_docs_and_rules() {
let meta = check_meta();
assert!(meta.get("docs").is_some());
assert!(meta.get("rules").is_some());
let rules = meta["rules"].as_object().unwrap();
assert_eq!(rules.len(), CHECK_RULES.len());
assert!(rules.contains_key("unused-file"));
assert!(rules.contains_key("unused-export"));
assert!(rules.contains_key("unused-type"));
assert!(rules.contains_key("unused-dependency"));
assert!(rules.contains_key("unused-dev-dependency"));
assert!(rules.contains_key("unused-optional-dependency"));
assert!(rules.contains_key("unused-enum-member"));
assert!(rules.contains_key("unused-class-member"));
assert!(rules.contains_key("unresolved-import"));
assert!(rules.contains_key("unlisted-dependency"));
assert!(rules.contains_key("duplicate-export"));
assert!(rules.contains_key("type-only-dependency"));
assert!(rules.contains_key("circular-dependency"));
}
#[test]
fn check_meta_rule_has_required_fields() {
let meta = check_meta();
let rules = meta["rules"].as_object().unwrap();
for (key, value) in rules {
assert!(value.get("name").is_some(), "rule {key} missing 'name'");
assert!(
value.get("description").is_some(),
"rule {key} missing 'description'"
);
assert!(value.get("docs").is_some(), "rule {key} missing 'docs'");
}
}
#[test]
fn health_meta_has_metrics() {
let meta = health_meta();
assert!(meta.get("docs").is_some());
let metrics = meta["metrics"].as_object().unwrap();
assert!(metrics.contains_key("cyclomatic"));
assert!(metrics.contains_key("cognitive"));
assert!(metrics.contains_key("maintainability_index"));
assert!(metrics.contains_key("complexity_density"));
assert!(metrics.contains_key("fan_in"));
assert!(metrics.contains_key("fan_out"));
}
#[test]
fn dupes_meta_has_metrics() {
let meta = dupes_meta();
assert!(meta.get("docs").is_some());
let metrics = meta["metrics"].as_object().unwrap();
assert!(metrics.contains_key("duplication_percentage"));
assert!(metrics.contains_key("token_count"));
assert!(metrics.contains_key("clone_groups"));
assert!(metrics.contains_key("clone_families"));
}
#[test]
fn health_rules_all_have_fallow_prefix() {
for rule in HEALTH_RULES {
assert!(
rule.id.starts_with("fallow/"),
"health rule {} should start with fallow/",
rule.id
);
}
}
#[test]
fn health_rules_all_have_docs_path() {
for rule in HEALTH_RULES {
assert!(
!rule.docs_path.is_empty(),
"health rule {} should have a docs_path",
rule.id
);
}
}
#[test]
fn health_rules_all_have_non_empty_fields() {
for rule in HEALTH_RULES {
assert!(
!rule.name.is_empty(),
"health rule {} missing name",
rule.id
);
assert!(
!rule.short.is_empty(),
"health rule {} missing short description",
rule.id
);
assert!(
!rule.full.is_empty(),
"health rule {} missing full description",
rule.id
);
}
}
#[test]
fn dupes_rules_all_have_fallow_prefix() {
for rule in DUPES_RULES {
assert!(
rule.id.starts_with("fallow/"),
"dupes rule {} should start with fallow/",
rule.id
);
}
}
#[test]
fn dupes_rules_all_have_docs_path() {
for rule in DUPES_RULES {
assert!(
!rule.docs_path.is_empty(),
"dupes rule {} should have a docs_path",
rule.id
);
}
}
#[test]
fn dupes_rules_all_have_non_empty_fields() {
for rule in DUPES_RULES {
assert!(!rule.name.is_empty(), "dupes rule {} missing name", rule.id);
assert!(
!rule.short.is_empty(),
"dupes rule {} missing short description",
rule.id
);
assert!(
!rule.full.is_empty(),
"dupes rule {} missing full description",
rule.id
);
}
}
#[test]
fn check_rules_all_have_non_empty_fields() {
for rule in CHECK_RULES {
assert!(!rule.name.is_empty(), "check rule {} missing name", rule.id);
assert!(
!rule.short.is_empty(),
"check rule {} missing short description",
rule.id
);
assert!(
!rule.full.is_empty(),
"check rule {} missing full description",
rule.id
);
}
}
#[test]
fn rule_docs_url_health_rule() {
let rule = rule_by_id("fallow/high-cyclomatic-complexity").unwrap();
let url = rule_docs_url(rule);
assert!(url.starts_with("https://docs.fallow.tools/"));
assert!(url.contains("health"));
}
#[test]
fn rule_docs_url_dupes_rule() {
let rule = rule_by_id("fallow/code-duplication").unwrap();
let url = rule_docs_url(rule);
assert!(url.starts_with("https://docs.fallow.tools/"));
assert!(url.contains("duplication"));
}
#[test]
fn health_meta_all_metrics_have_name_and_description() {
let meta = health_meta();
let metrics = meta["metrics"].as_object().unwrap();
for (key, value) in metrics {
assert!(
value.get("name").is_some(),
"health metric {key} missing 'name'"
);
assert!(
value.get("description").is_some(),
"health metric {key} missing 'description'"
);
assert!(
value.get("interpretation").is_some(),
"health metric {key} missing 'interpretation'"
);
}
}
#[test]
fn health_meta_has_all_expected_metrics() {
let meta = health_meta();
let metrics = meta["metrics"].as_object().unwrap();
let expected = [
"cyclomatic",
"cognitive",
"line_count",
"maintainability_index",
"complexity_density",
"dead_code_ratio",
"fan_in",
"fan_out",
"score",
"weighted_commits",
"trend",
"priority",
"efficiency",
"effort",
"confidence",
];
for key in &expected {
assert!(
metrics.contains_key(*key),
"health_meta missing expected metric: {key}"
);
}
}
#[test]
fn dupes_meta_all_metrics_have_name_and_description() {
let meta = dupes_meta();
let metrics = meta["metrics"].as_object().unwrap();
for (key, value) in metrics {
assert!(
value.get("name").is_some(),
"dupes metric {key} missing 'name'"
);
assert!(
value.get("description").is_some(),
"dupes metric {key} missing 'description'"
);
}
}
#[test]
fn dupes_meta_has_line_count() {
let meta = dupes_meta();
let metrics = meta["metrics"].as_object().unwrap();
assert!(metrics.contains_key("line_count"));
}
#[test]
fn check_docs_url_valid() {
assert!(CHECK_DOCS.starts_with("https://"));
assert!(CHECK_DOCS.contains("dead-code"));
}
#[test]
fn health_docs_url_valid() {
assert!(HEALTH_DOCS.starts_with("https://"));
assert!(HEALTH_DOCS.contains("health"));
}
#[test]
fn dupes_docs_url_valid() {
assert!(DUPES_DOCS.starts_with("https://"));
assert!(DUPES_DOCS.contains("dupes"));
}
#[test]
fn check_meta_docs_url_matches_constant() {
let meta = check_meta();
assert_eq!(meta["docs"].as_str().unwrap(), CHECK_DOCS);
}
#[test]
fn health_meta_docs_url_matches_constant() {
let meta = health_meta();
assert_eq!(meta["docs"].as_str().unwrap(), HEALTH_DOCS);
}
#[test]
fn dupes_meta_docs_url_matches_constant() {
let meta = dupes_meta();
assert_eq!(meta["docs"].as_str().unwrap(), DUPES_DOCS);
}
#[test]
fn rule_by_id_finds_all_check_rules() {
for rule in CHECK_RULES {
assert!(
rule_by_id(rule.id).is_some(),
"rule_by_id should find check rule {}",
rule.id
);
}
}
#[test]
fn rule_by_id_finds_all_health_rules() {
for rule in HEALTH_RULES {
assert!(
rule_by_id(rule.id).is_some(),
"rule_by_id should find health rule {}",
rule.id
);
}
}
#[test]
fn rule_by_id_finds_all_dupes_rules() {
for rule in DUPES_RULES {
assert!(
rule_by_id(rule.id).is_some(),
"rule_by_id should find dupes rule {}",
rule.id
);
}
}
#[test]
fn check_rules_count() {
assert_eq!(CHECK_RULES.len(), 13);
}
#[test]
fn health_rules_count() {
assert_eq!(HEALTH_RULES.len(), 4);
}
#[test]
fn dupes_rules_count() {
assert_eq!(DUPES_RULES.len(), 1);
}
}