paralleldrive/aidd/aidd-churn

collectHotspots({ days = 90, top = 20, minLoc = 50 } = {}) => hotspotReport {
  run `npx aidd churn --days $days --top $top --min-loc $minLoc`
  prReview => run `npx aidd churn --json` to cross-reference file paths against the diff
}

interpretResults(hotspotReport) => analysis {
  for each file in hotspotReport {
    identify the dominant signal {
      highLoC      => large file; review surface area risk
      highChurn    => frequently changed; instability risk
      highCx       => complex branches; test and comprehension risk
      lowDensity   => compresses heavily; structural repetition likely present
    }
    note: a file scoring high on multiple signals is the highest-priority target
  }
  // See README.md for interpretation ranges and score formula
}

recommend(analysis, { context = "standalone" } = {}) => recommendations {
  for each top hotspot {
    state: file path and score
    explain: WHY it ranks high — cite the specific metric(s) driving the score
    propose a strategy {
      highLoC      => extract cohesive sub-modules or pure utility functions into separate files
      highChurn    => split responsibilities so stable interfaces churn less
      highCx       => flatten conditionals, extract named predicates, replace switch trees with lookup maps
      lowDensity   => eliminate copy-paste by extracting shared helpers
    }
    estimate: which metric drops the most after the refactor
  }
  
  if context === "prReview" {
    cross-reference: identify files in both the diff AND the top hotspot results
    for each match {
      flag: "⚠️ This file is a hotspot"
      explain: which signal (LoC, churn, complexity, or density) is driving the risk
      reviewGuidance: prioritize this file for extra scrutiny — changes here have higher blast radius
      recommend: consider splitting this file or extracting stable interfaces before merging
    }
    if no matches found => note that the diff avoids known hotspots (lower risk)
  }
}

# Default: top 20 files, 90-day git window, minimum 50 LoC
npx aidd churn
 
# Adjust window and thresholds
npx aidd churn --days 30 --top 10 --min-loc 100
 
# Machine-readable output (useful for cross-referencing with a PR diff)
npx aidd churn --json