@wbern/obscene 2.0.1 → 2.1.0

package/README.md

@@ -88,7 +88,7 @@ Each table has its own tier assignment by cumulative score distribution:
 
 Tiers are relative to THIS codebase, not absolute quality grades. A "hot" file is under heavy load, not necessarily broken.
 
-A file may rank high in one dimension (e.g. complexity) but low in another (e.g. authors). Rankings with insufficient data are skipped with an explanation (e.g. defects ranking requires 5+ `fix:` commits across 3+ files). Bot authors (`[bot]` suffix) are filtered automatically.
+A file may rank high in one dimension (e.g. complexity) but low in another (e.g. authors). Rankings with insufficient data are skipped with an explanation (e.g. the Fix Activity ranking requires 5+ `fix:` commits across 3+ files). Bot authors (`[bot]` suffix) are filtered automatically.
 
 ### `obscene coupling`
 
@@ -122,7 +122,7 @@ Per-file complexity without churn. Useful for raw complexity distribution.
 
 #### Score
 
-`metric × churn`. Each ranking table uses a different metric (complexity, nesting, defects, or authors) multiplied by churn. See [Why churn × complexity?](#why-churn-x-complexity) for the research backing this approach.
+`metric × churn`. Each ranking table uses a different metric (complexity, nesting, fix activity, or authors) multiplied by churn. See [Why churn × complexity?](#why-churn-x-complexity) for the research backing this approach.
 
 #### Churn (`Churn`)
 
@@ -130,15 +130,17 @@ Number of commits touching the file within the configured time window (default:
 
 #### Cyclomatic complexity (`Cmplx`)
 
-Total cyclomatic complexity as reported by [scc](https://github.com/boyter/scc). Counts independent execution paths (branches, loops, conditions). Higher values mean more paths to test and more places for bugs to hide.
+Total cyclomatic complexity as reported by [scc](https://github.com/boyter/scc). Counts independent execution paths (branches, loops, conditions). Higher values mean more paths to test and more places for bugs to hide. The measure was introduced by McCabe (1976) in *A Complexity Measure* and has been the standard structural-complexity metric since. — [IEEE TSE](https://doi.org/10.1109/TSE.1976.233837)
 
 #### Complexity density (`Dens`)
 
 `complexity / lines of code`. Normalizes complexity by file size so a 50-line file with complexity 25 (density 0.50) stands out against a 500-line file with complexity 25 (density 0.05). Based on Harrison & Magel (1981), who found that complexity relative to code size is a stronger fault predictor than raw complexity alone.
 
-#### Fixes (`Fixes`)
+#### Fix activity (`Fixes`)
 
-Count of `fix:` conventional commits touching the file within the churn window. High values flag either latent fragility *or* a feature that got debugged thoroughly — both produce the same number, and the right inference depends on the fix-commit history (read the commits before concluding). The metric is inspired by Moser, Pedrycz & Succi (2008), who showed that change-history metrics outperform static code metrics for defect prediction; obscene reports the raw fix-activity signal and leaves the interpretation to you.
+Count of `fix:` conventional commits touching the file within the churn window. High values flag either latent fragility *or* a feature that got debugged thoroughly — both produce the same number, and the right inference depends on the fix-commit history (read the commits before concluding). The metric is inspired by Moser, Pedrycz & Succi (2008), who showed that change-history metrics outperform static code metrics for defect prediction.
+
+The literature in [Why churn × complexity?](#why-churn-x-complexity) talks about *defects* — bugs confirmed against a bug-tracker or post-release issue database. obscene doesn't have access to that ground truth, so it uses `fix:` commits as a proxy and reports the raw signal as Fix Activity. The two are related but not identical: a `fix:` commit is direct evidence that someone considered something broken enough to label the change as a fix, but it doesn't distinguish trivial fixes from severe ones, and it relies on the team using conventional commits consistently. Treat Fix Activity as a prompt to read the commits, not as a defect count.
 
 #### Fix density (`FxDns`)
 
@@ -176,6 +178,30 @@ Cumulative score distribution bucket:
 | ☀️ **warm** | next 30% (50–80%) | Moderate coupling |
 | 🧊 **cool** | bottom 20% | Low coupling |
 
+#### Pair markers
+
+The coupling table annotates entries that need framing:
+
+| Marker | JSON field | Meaning |
+|--------|------------|---------|
+| `†` next to a path | `file1Deleted` / `file2Deleted` | File is no longer present at HEAD (deleted or renamed away). The coupling signal is historical; the pair is not actionable in the current tree. |
+| `⇄` next to the Degree value | `lockstep` | Both files' total churn equals their co-change count over the window — they only ever changed together. The 100% degree is real but uninformative; treat the pair as a single unit from git's perspective. |
+
+### Corpus framing
+
+When the analyzed file set has no measurable cyclomatic complexity (every scanned file is non-code or trivial), the `hotspots` table prepends a banner noting that rankings reflect size and churn only. The `corpus` field in JSON output exposes the same signal:
+
+```json
+{
+  "corpus": {
+    "fileCount": 42,
+    "totalComplexity": 0
+  }
+}
+```
+
+`fileCount` counts files *after* exclusion (`.obsignore` and `--exclude` patterns are already applied). Treat HOT/WARM/COOL as relative groupings rather than risk labels when `totalComplexity` is 0.
+
 ## Example output
 
 ```
@@ -262,7 +288,7 @@ obscene init
 
 This creates a `.obsignore` containing:
 - **Universal exclusions** — test files (`*.test.*`, `*.spec.*`, `__tests__/`, etc.), lock files (`package-lock.json`, `pnpm-lock.yaml`, etc.), and package manifests (`package.json`)
-- **Detected project patterns** — CI directories (`.github/`), config files (`*.config.*`), vendored code, etc., based on your project structure
+- **Detected project patterns** — CI directories (`.github/`), config files (`*.config.*`), vendored code, generated agent-command directories (`.claude/commands/**`, `.opencode/commands/**`, `.cursor/rules/**`), etc., based on your project structure
 
 If no `.obsignore` or `.obsceneignore` exists, obscene prints a hint to stderr:
 
@@ -297,6 +323,8 @@ Files that are both complex and frequently modified are disproportionately likel
 
 - **Nagappan & Ball (2005)** studied Windows Server 2003 and found that relative code churn measures predict system defect density with 89% accuracy. — [ICSE 2005](https://doi.org/10.1109/ICSE.2005.1553571)
 - **Moser, Pedrycz & Succi (2008)** compared change metrics against static code attributes on Eclipse and found that process metrics (churn, change frequency) outperform static code metrics for defect prediction. — [ICSE 2008](https://doi.org/10.1145/1368088.1368114)
+- **Hassan (2009)** introduced an entropy-based measure of code-change complexity and showed it predicts faults better than prior change and prior fault counts on six large open-source systems. — [ICSE 2009](https://doi.org/10.1109/ICSE.2009.5070510)
+- **D'Ambros, Lanza & Robbes (2010)** systematically compared bug-prediction approaches (process, churn, source-code, entropy, and combined metrics) on five open-source systems and found that change-history metrics consistently rank among the strongest predictors. — [MSR 2010](https://doi.org/10.1109/MSR.2010.5463279)
 - **Shin, Meneely, Williams & Osborne (2011)** combined complexity, churn, and developer activity metrics to predict vulnerabilities in Mozilla Firefox and the Linux kernel. By flagging only 10.9% of files, the model identified 70.8% of known vulnerabilities. — [IEEE TSE](https://doi.org/10.1109/TSE.2010.55)
 - **Tornhill & Borg (2022)** analyzed 39 proprietary codebases and found that low-quality code (by their Code Health metric) contains 15x more defects and takes 124% longer to resolve. In their case studies, 4% of the codebase was responsible for 72% of all defects. — [ACM/IEEE TechDebt 2022](https://arxiv.org/abs/2203.04374)
 
@@ -331,43 +359,35 @@ Files that change together but live in different directories reveal implicit dep
 
 ## Field reports
 
-Reviews from agents that ran obscene against real codebases. Unedited.
+Reviews from agents that ran obscene against real codebases.
 
-> I ran obscene against a mid-sized polyglot codebase (web frontend + Python service + IaC, ~150 files, ~4 months of active history) right after a session of structural refactors. Honest take:
+> I ran obscene against a mid-sized polyglot codebase (web frontend + Python service + IaC, ~150 files, ~4 months of active history). Honest take:
 >
-> What actually surfaced new information:
+> What surfaced new information from the hotspots view:
 >
-> - The defect-density column (fix-commits per change) flagged a fragile component I would not have prioritized from reading the code alone — ~10 fix-commits over ~14 changes is a "this feature keeps breaking" signal you don't get from raw line counts or complexity.
-> - A nesting outlier (one handler scoring ~30-deep in a repo whose median was 4–7). Extreme enough that no amount of churn-weighting could hide it.
+> - The Fix Activity column (fix-commits × churn) flagged a component I would not have prioritized from reading the code alone — ~10 fix-commits over ~14 changes. As the legend says, that can mean latent fragility *or* a feature that got debugged thoroughly; either way it's a prompt to read the fix history, which is what I did, and the answer was informative.
+> - A nesting outlier (one handler scoring ~15-deep in a repo whose median was 4–7). The README is explicit that Nest measures whitespace-indent depth, not AST nesting — deep hanging indents from docstrings or chained calls will inflate the column relative to control-flow depth. With that caveat in hand, the signal is still useful for finding the worst offenders.
 >
-> Worth setting expectations on:
+> What `obscene coupling` added on a second run:
 >
-> - It's a churn × complexity instrument, so it *temporarily penalizes* refactoring — moving code out of a hot file shows up as more commits on that file, inflating the score before the new structure pays off in stability. The hottest file in our run was hottest partly because we'd touched it that day.
-> - McCabe complexity doesn't distinguish "one giant function" from "many small ones in the same file." A score tells you the size of the badness, not the shape.
-> - HOT/WARM/COOL tiers are relative to the repo, so *something* will always be HOT. Useful for "what's worst here," not a portable quality grade.
-> - It can't see the failure modes that actually bite at runtime: coupling, type confusion, missing tests, brittle integration seams, hidden globals.
+> - The headline finding: the top co-change pair (~21 shared commits, ~70% degree) was a service module and its corresponding configuration-management playbook. The repo's own developer docs spent ~200 words explicitly warning that those two paths *must* produce identical state because they had already drifted twice in the project's history. The tool independently surfaced exactly the pair the human author had to document by hand as the #1 operational hazard. Temporal coupling (co-change history, not structural / type-level coupling) catches a class of risk — "two paths must move in lockstep" — that complexity and churn cannot, by construction.
+> - Second-tier signal: cross-stack pairs (frontend SPA + backend API, ~8 co-changes) flagged which abstraction boundaries actually leak in practice. Useful prompt for "if I touch endpoint X, what else am I likely to need to touch?"
 >
-> Verdict: a 60-second sanity check that mostly ranks what reading the codebase already tells you, plus one or two findings you'd otherwise miss. Treat the defect-density column as the most signal-dense, run it quarterly, and don't optimize against the leaderboard — it's a magnifying glass, not a scoreboard.
->
-> — Claude (Opus 4.7), via Claude Code
-
-**Coupling addendum** — a separate run of `obscene coupling` against the same codebase a few weeks later, at the maintainer's request.
-
-> What landed:
+> Worth setting expectations on the hotspots view:
 >
-> - The headline finding: the top co-change pair (~21 shared commits, ~70% degree) was a service module and its corresponding configuration-management playbook. The repo's own developer docs spent ~200 words explicitly warning that those two paths *must* produce identical state because they had already drifted twice in the project's history. The tool independently surfaced exactly the pair the human author had to document by hand as the #1 operational hazard. That's a real find — temporal coupling catches a class of risk ("two paths must move in lockstep") that complexity and churn cannot, by construction.
-> - Second-tier signal that earned its keep: cross-stack pairs (frontend SPA + backend API, ~8 co-changes) flagged which abstraction boundaries actually leak in practice. Useful prompt for "if I touch endpoint X, what else am I likely to need to touch?"
-> - Worth saying explicitly: the original testament's line "can't see coupling" was unfair as written. I meant *structural* coupling — the static-analysis question of "if I rename this field, what breaks?". `obscene coupling` measures *temporal* coupling (co-change history). Different sense of the word, and for the failure mode I was implicitly thinking of ("two things must stay in sync") the temporal lens is arguably more diagnostic than the structural one would have been.
+> - It's a churn × complexity instrument, so it *temporarily penalizes* refactoring — moving code out of a hot file shows up as more commits on that file, inflating the score before the new structure pays off in stability.
+> - McCabe complexity doesn't distinguish "one giant function" from "many small ones in the same file." A score tells you the size of the badness, not the shape.
+> - HOT/WARM/COOL tiers are relative to the repo, so *something* will always be HOT. Useful for "what's worst here," not a portable quality grade.
+> - Failure modes that aren't visible to git or scc — type confusion, missing tests, brittle integration seams, hidden globals — won't appear in the rankings at all. The tool can't tell you about risks it has no signal for.
 >
-> Where the friction was:
+> And on the coupling view:
 >
-> - Documentation files (CLAUDE.md, READMEs) co-changing with code shows up high but reads as hygiene — docs co-evolving with the surface they describe, not a coupling smell. Worth either a default exclusion for markdown or an explicit callout in the legend.
-> - The `Degree` metric is asymmetric (`shared / min(churn)`, so it measures how entangled the *less-churned* file is with the other), but the file-pair display is symmetric. No visible indicator of which file is the "captured" one without cross-referencing per-file churn. Adding directionality to the printout would read more clearly.
-> - Small-absolute / high-degree pairs (e.g. 5 co-changes at 83%) appeared near the top at defaults. `--min-cochanges 5` filtered these out cleanly, but the defaults need either a sane minimum or a confidence-shaped column.
-> - The combined-complexity column on each row didn't add much — a sum of two unrelated complexities has no clean interpretation, and the hotspots report already covers per-file complexity well.
-> - Tier inflation again: ~68 HOT pairs out of ~231 at defaults. Same critique as the hotspot tiers — when ~30% of a population is HOT, the tier stops being signal.
+> - Documentation files (CLAUDE.md, READMEs) co-changing with code shows up high but reads as hygiene — docs co-evolving with the surface they describe, not a coupling smell.
+> - `Degree` is asymmetric (`shared / min(churn)`, so it measures how entangled the *less-churned* file is with the other), but the file-pair display is symmetric. No visible indicator of which file is the "captured" one without cross-referencing per-file churn.
+> - Small-absolute / high-degree pairs (e.g. 5 co-changes at 83%) appear near the top at defaults. `--min-cochanges 5` filters these out cleanly.
+> - Tier inflation: a sizable fraction of pairs end up HOT at defaults. Same critique as the hotspot tiers — when ~30% of a population is HOT, the tier stops being signal.
 >
-> Verdict: `obscene coupling` complements the hotspot view rather than overlapping with it. Hotspots ask "what file is the worst?"; coupling asks "what files must I keep in sync?" — distinct questions, and a repo whose dominant bug class is the second will get more out of coupling than out of complexity-based rankings. For this codebase, coupling rediscovered an institutional hazard the human author had felt compelled to document in prose. Worth running alongside hotspots, not in place of either lens. Same quarterly cadence applies; treat the cross-stack and cross-path pairs as the most action-shaped output.
+> Verdict: hotspots and coupling are complementary, not redundant. Hotspots ask "what file is the worst?"; coupling asks "what files must I keep in sync?" — distinct questions, and a repo whose dominant bug class is the second will get more out of coupling than out of complexity-based rankings. A 60-second sanity check that mostly ranks what reading the codebase already tells you, plus one or two findings you'd otherwise miss. Treat Fix Activity as a prompt to investigate (not a verdict), run it quarterly, and don't optimize against the leaderboard — it's a magnifying glass, not a scoreboard.
 >
 > — Claude (Opus 4.7), via Claude Code
 

package/dist/cli.js

@@ -322,15 +322,34 @@ function computeAllRankings(files, churn, defects, nestingDepths, authors, top)
   }
   return { rankings, skipped };
 }
-function computeCoupling(cochanges, churn, complexityMap, minCochanges) {
+function getTrackedFiles() {
+  let raw;
+  try {
+    raw = execSync("git ls-files", {
+      maxBuffer: 50 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch {
+    throw new Error("Not a git repository or git is not installed.");
+  }
+  const set = /* @__PURE__ */ new Set();
+  for (const line of raw.toString().split("\n")) {
+    const trimmed = normalizePath(line.trim());
+    if (trimmed) set.add(trimmed);
+  }
+  return set;
+}
+function computeCoupling(cochanges, churn, complexityMap, minCochanges, trackedFiles) {
   const entries = [];
   for (const [key, count] of cochanges) {
     if (count < minCochanges) continue;
     const [file1, file2] = key.split("\0");
-    const minChurn = Math.min(churn.get(file1) ?? 0, churn.get(file2) ?? 0);
+    const churn1 = churn.get(file1) ?? 0;
+    const churn2 = churn.get(file2) ?? 0;
+    const minChurn = Math.min(churn1, churn2);
     const degree = minChurn > 0 ? Math.round(count / minChurn * 1e3) / 10 : 0;
     const totalComplexity = (complexityMap.get(file1) ?? 0) + (complexityMap.get(file2) ?? 0);
-    entries.push({
+    const entry = {
       file1,
       file2,
       cochanges: count,
@@ -339,7 +358,15 @@ function computeCoupling(cochanges, churn, complexityMap, minCochanges) {
       couplingScore: count,
       percentOfTotal: 0,
       tier: "cool"
-    });
+    };
+    if (count > 0 && churn1 === count && churn2 === count) {
+      entry.lockstep = true;
+    }
+    if (trackedFiles) {
+      if (!trackedFiles.has(file1)) entry.file1Deleted = true;
+      if (!trackedFiles.has(file2)) entry.file2Deleted = true;
+    }
+    entries.push(entry);
   }
   entries.sort((a, b) => b.couplingScore - a.couplingScore);
   const totalScore = entries.reduce((sum, e) => sum + e.couplingScore, 0);
@@ -460,19 +487,25 @@ var INIT_FILE_RULES = [
     test: /(?:^|\/)\.gitlab-ci/,
     pattern: ".gitlab-ci*",
     comment: "GitLab CI configuration"
+  },
+  {
+    test: /^\.claude\/commands\//,
+    pattern: ".claude/commands/**",
+    comment: "Claude Code slash commands (often generated from sources)"
+  },
+  {
+    test: /^\.opencode\/commands\//,
+    pattern: ".opencode/commands/**",
+    comment: "OpenCode slash commands (often generated from sources)"
+  },
+  {
+    test: /^\.cursor\/rules\//,
+    pattern: ".cursor/rules/**",
+    comment: "Cursor rules (often generated from sources)"
   }
 ];
 function detectIgnorePatterns() {
-  let raw;
-  try {
-    raw = execSync("git ls-files", {
-      maxBuffer: 50 * 1024 * 1024,
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-  } catch {
-    throw new Error("Not a git repository or git is not installed.");
-  }
-  const trackedFiles = raw.toString().split("\n").map((l) => normalizePath(l.trim())).filter(Boolean);
+  const trackedFiles = getTrackedFiles();
   const patterns = [];
   const topDirs = /* @__PURE__ */ new Set();
   for (const f of trackedFiles) {
@@ -485,8 +518,11 @@ function detectIgnorePatterns() {
     }
   }
   for (const rule of INIT_FILE_RULES) {
-    if (trackedFiles.some((f) => rule.test.test(f))) {
-      patterns.push({ pattern: rule.pattern, comment: rule.comment });
+    for (const f of trackedFiles) {
+      if (rule.test.test(f)) {
+        patterns.push({ pattern: rule.pattern, comment: rule.comment });
+        break;
+      }
     }
   }
   return patterns;
@@ -615,7 +651,13 @@ function padLeft(s, n) {
   return w >= n ? s : " ".repeat(n - w) + s;
 }
 function truncate(s, max) {
-  return s.length <= max ? s : `\u2026${s.slice(s.length - max + 1)}`;
+  if (max <= 0) return "";
+  if (s.length <= max) return s;
+  if (max === 1) return "\u2026";
+  const remaining = max - 1;
+  const tail = Math.ceil(remaining * 0.6);
+  const head = remaining - tail;
+  return `${s.slice(0, head)}\u2026${s.slice(s.length - tail)}`;
 }
 function tierLabel(tier) {
   if (tier === "hot") return pc.red("\u{1F525} HOT ");
@@ -796,8 +838,21 @@ function formatRankingTable(key, ranking, description) {
 }
 function formatHotspotsTable(output) {
   const lines = [];
-  const { churnWindow, rankings } = output;
+  const { churnWindow, rankings, corpus } = output;
   lines.push(`Hotspots \u2014 ${churnWindow} churn window`);
+  if (corpus && corpus.fileCount > 0 && corpus.totalComplexity === 0) {
+    lines.push("");
+    lines.push(
+      pc2.yellow(
+        "Note: no measurable code complexity detected across this corpus (cyclomatic = 0)."
+      )
+    );
+    lines.push(
+      pc2.yellow(
+        "Rankings reflect size and churn only \u2014 HOT/WARM/COOL are relative groupings, not risk labels."
+      )
+    );
+  }
   lines.push("");
   const keys = Object.keys(rankings);
   for (let i = 0; i < keys.length; i++) {
@@ -844,8 +899,15 @@ function formatCouplingTable(output) {
     padRight("File 1", 35) + padRight("File 2", 35) + padLeft("Shared", 7) + padLeft("Degree", 8) + padLeft("Cmplx", 7) + padLeft("Tier", 12)
   );
   lines.push("\u2500".repeat(104));
+  let anyDeleted = false;
+  let anyLockstep = false;
   for (const c of couplings) {
-    const rawRow = padRight(truncate(c.file1, 33), 35) + padRight(truncate(c.file2, 33), 35) + padLeft(String(c.cochanges), 7) + padLeft(`${c.degree.toFixed(1)}%`, 8) + padLeft(String(c.totalComplexity), 7) + padLeft(tierLabel(c.tier), 12);
+    if (c.file1Deleted || c.file2Deleted) anyDeleted = true;
+    if (c.lockstep) anyLockstep = true;
+    const file1Cell = c.file1Deleted ? `\u2020 ${truncate(c.file1, 31)}` : truncate(c.file1, 33);
+    const file2Cell = c.file2Deleted ? `\u2020 ${truncate(c.file2, 31)}` : truncate(c.file2, 33);
+    const degreeText = c.lockstep ? `${c.degree.toFixed(1)}\u21C4` : `${c.degree.toFixed(1)}%`;
+    const rawRow = padRight(file1Cell, 35) + padRight(file2Cell, 35) + padLeft(String(c.cochanges), 7) + padLeft(degreeText, 8) + padLeft(String(c.totalComplexity), 7) + padLeft(tierLabel(c.tier), 12);
     lines.push(colorRow(c.tier, rawRow));
   }
   lines.push("");
@@ -854,6 +916,18 @@ function formatCouplingTable(output) {
       "Shared=co-changed commits | Degree=shared/min(churn)\xD7100 | Cmplx=sum of both files"
     )
   );
+  if (anyDeleted) {
+    lines.push(
+      pc2.dim("\u2020 = file no longer present at HEAD (deleted or renamed)")
+    );
+  }
+  if (anyLockstep) {
+    lines.push(
+      pc2.dim(
+        "\u21C4 = lockstep pair (both files only ever changed together \u2014 signal is real but uninformative)"
+      )
+    );
+  }
   lines.push(
     pc2.dim(
       "Tiers are relative to THIS codebase, not absolute quality grades. High coupling may be intentional and fine."
@@ -890,7 +964,7 @@ function formatCompositeTable(output) {
 
 // src/cli.ts
 var program = new Command();
-program.name("obscene").description("Identify hotspot files \u2014 complex code that changes frequently").version("2.0.1");
+program.name("obscene").description("Identify hotspot files \u2014 complex code that changes frequently").version("2.1.0");
 var REPORT_GUIDE = {
   complexity: "Cyclomatic complexity (branch/loop count). NOT a quality judgment \u2014 a 500-line parser will naturally score high. Compare density, not raw values.",
   complexityDensity: "Complexity per line of code. Normalizes for file size. >0.25 suggests dense logic worth reviewing; <0.10 is typical for straightforward code.",
@@ -903,13 +977,16 @@ var HOTSPOTS_GUIDE = {
   defects: "fixes \xD7 churn. Count of fix: commits touching the file \xD7 churn. High values can mean latent fragility, but they also flag features that got debugged thoroughly \u2014 read the fix-commit history before concluding which.\nSource: change-history metrics (Moser, Pedrycz & Succi 2008) via conventional commits (fix: prefix) \xB7 Strength: direct fix-history signal \xB7 Limit: counts fix activity, not defects per se; requires consistent fix: convention",
   authors: "authors \xD7 churn. Files touched by many authors and changing often may lack clear ownership.\nSource: code ownership research (Bird et al. 2011, Microsoft) \xB7 Strength: flags diffuse ownership risk \xB7 Limit: doesn't measure expertise depth, bot authors filtered automatically",
   composite: "Combined ranking using Reciprocal Rank Fusion (RRF) across all dimensions. Files appearing near the top of multiple rankings score highest.\nSource: RRF (Cormack et al. 2009) \xB7 Strength: robust to outliers, no normalization needed \xB7 Limit: equal weight across all dimensions",
-  tier: "Relative ranking within THIS codebase (top 50% = hot, next 30% = warm, bottom 20% = cool). NOT an absolute quality grade \u2014 a hot file is under heavy load, not necessarily broken."
+  tier: "Relative ranking within THIS codebase (top 50% = hot, next 30% = warm, bottom 20% = cool). NOT an absolute quality grade \u2014 a hot file is under heavy load, not necessarily broken.",
+  corpus: "Aggregate stats for the analyzed file set (post-exclude \u2014 files filtered by .obsignore or --exclude are not counted). When totalComplexity is 0, the rankings reflect size and churn only; HOT/WARM/COOL become relative groupings rather than risk labels."
 };
 var COUPLING_GUIDE = {
   cochanges: "Times both files appeared in the same commit. Higher values suggest a dependency between the files. Same-directory pairs are excluded \u2014 only cross-directory pairs are shown.",
   degree: "Percentage: shared commits / min(churn of file1, file2) \xD7 100. Shows how tightly coupled the pair is relative to their individual change rates. 100% means every change to the less-active file also touched the other.",
   totalComplexity: "Sum of both files' cyclomatic complexity. Highlights coupled pairs where the involved code is also complex \u2014 hidden dependency + high complexity compounds maintenance risk.",
-  tier: "Relative ranking within THIS codebase's coupling pairs (top 50% = hot, next 30% = warm, bottom 20% = cool). NOT an absolute quality grade. 'hot' means this pair co-changes more than most \u2014 it may be intentional and fine."
+  tier: "Relative ranking within THIS codebase's coupling pairs (top 50% = hot, next 30% = warm, bottom 20% = cool). NOT an absolute quality grade. 'hot' means this pair co-changes more than most \u2014 it may be intentional and fine.",
+  deleted: "file1Deleted / file2Deleted are set when the file is no longer present at HEAD (deleted or renamed away). The coupling signal is historical \u2014 the pair is not actionable in the current tree.",
+  lockstep: "Set when both files' total churn equals their co-change count over the window \u2014 i.e. they only ever changed together. The 100% degree is real but uninformative; treat the pair as a single unit from git's perspective."
 };
 function addSharedOptions(cmd) {
   return cmd.option("--top <n>", "limit to top N entries (0 = all)", "20").option("--format <type>", "output format: json | table", "json").option(
@@ -1015,13 +1092,19 @@ function runHotspots(opts) {
     top
   );
   const composite = computeComposite(rankings, churn, top);
+  let corpusTotalComplexity = 0;
+  for (const f of files) corpusTotalComplexity += f.complexity;
   const output = {
     generated: (/* @__PURE__ */ new Date()).toISOString(),
     guide: HOTSPOTS_GUIDE,
     churnWindow: `${months} months`,
     rankings,
     skipped: Object.keys(skipped).length > 0 ? skipped : void 0,
-    composite
+    composite,
+    corpus: {
+      fileCount: files.length,
+      totalComplexity: corpusTotalComplexity
+    }
   };
   if (opts.format === "table") {
     process.stdout.write(`${formatHotspotsTable(output)}
@@ -1049,11 +1132,13 @@ function runCoupling(opts) {
   for (const f of files) {
     complexityMap.set(f.file, f.complexity);
   }
+  const trackedFiles = getTrackedFiles();
   const couplings = computeCoupling(
     cochanges,
     churn,
     complexityMap,
-    minCochanges
+    minCochanges,
+    trackedFiles
   );
   const limited = top > 0 ? couplings.slice(0, top) : couplings;
   const tierCounts = { hot: 0, warm: 0, cool: 0 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wbern/obscene",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Identify hotspot files — complex code that changes frequently. Churn × complexity analysis for any git repo.",
   "type": "module",
   "bin": {