@wbern/obscene 2.0.0 → 2.1.0

package/README.md

@@ -73,7 +73,7 @@ Produces **four independent ranking tables**, each scoring files by a different
 |---------|---------------|----------------|
 | Complexity × Churn | `complexity × churn` | Cmplx, Dens |
 | Nesting × Churn | `maxNesting × churn` | Nest |
-| Defects × Churn | `defects × churn` | Dfcts, DfDns |
+| Fix Activity × Churn | `fixes × churn` | Fixes, FxDns |
 | Authors × Churn | `authors × churn` | Auth |
 
 Plus a **Combined** ranking using [Reciprocal Rank Fusion](https://doi.org/10.1145/1571941.1572114) (RRF) across all dimensions — files appearing near the top of multiple rankings score highest.
@@ -88,13 +88,13 @@ 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`
 
-Detects files that frequently change together in the same commit but live in different directories — Tornhill's "temporal coupling" analysis from *Your Code as a Crime Scene* (2015). Surfaces hidden structural dependencies that aren't visible in imports or the module graph.
+**Temporal coupling** (co-change history), not structural / type-level coupling. Detects files that frequently change together in the same commit but live in different directories — Tornhill's "temporal coupling" analysis from *Your Code as a Crime Scene* (2015). Surfaces hidden dependencies that aren't visible in imports or the module graph: pairs of files that *in practice* can't be changed independently, even when the type system says they can.
 
-Same-directory pairs are excluded (co-location is expected coupling). Mass commits touching >20 files are skipped (formatting changes, large refactors). See [Why temporal coupling?](#why-temporal-coupling) for the research backing this approach.
+Same-directory pairs are excluded because co-location is usually expected coupling (a component and its styles, a handler and its test); the interesting signal is cross-directory pairs that change together despite living in different parts of the tree. Mass commits touching >20 files are skipped (formatting changes, large refactors). See [Why temporal coupling?](#why-temporal-coupling) for the research backing this approach.
 
 ```bash
 obscene coupling                          # default: min 2 shared commits
@@ -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,23 +130,25 @@ 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.
 
-#### Defects (`Dfcts`)
+#### Fix activity (`Fixes`)
 
-Count of `fix:` conventional commits touching the file within the churn window. A proxy for historical defect rate — files that attract repeated fixes are more likely to contain latent bugs. Inspired by Moser, Pedrycz & Succi (2008), who showed that change-history metrics outperform static code metrics for defect prediction.
+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.
 
-#### Defect density (`DfDns`)
+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.
 
-`defects / lines of code`. Shown in the Defects × Churn table. Normalizes defect count by file size.
+#### Fix density (`FxDns`)
+
+`fixes / lines of code`. Shown in the Fix Activity × Churn table. Normalizes fix-commit count by file size so a 50-line file with 5 fixes (density 0.10) stands out against a 500-line file with 5 fixes (density 0.01).
 
 #### Nesting depth (`Nest`)
 
-Maximum indentation level (tab stops) in the file. Deep nesting correlates with high cognitive load and defect likelihood. Harrison & Magel (1981) identified nesting depth as a significant complexity contributor.
+Maximum indentation level (tab stops) in the file. Deep nesting correlates with high cognitive load and defect likelihood. Harrison & Magel (1981) identified nesting depth as a significant complexity contributor. The indent unit is detected from the most common positive delta between consecutive non-blank line indents, which keeps single-space outlier lines (multiline strings, continuation alignment) from inflating the score. The metric measures whitespace depth, not AST control-flow depth — they usually agree, but a file with deep alignment and shallow logic can read higher than its true nesting.
 
 #### Unique authors (`Auth`)
 
@@ -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)
 
@@ -320,6 +348,7 @@ Files that change together but live in different directories reveal implicit dep
 - **Must be run inside a git repo.** Churn data comes from `git log`.
 - **Only analyzes files that currently exist.** Deleted files don't appear, even if they churned heavily before removal.
 - **Tier thresholds are fixed** (50/80 cumulative %). Not configurable yet.
+- **Temporarily penalizes refactoring.** Moving code *out of* a hot file shows up as one more commit on that file, inflating its score before the new structure has time to pay off in stability. A file you just touched today will look hotter than it deserves; the signal stabilizes over the next few weeks.
 
 ### Coupling-specific
 
@@ -328,6 +357,40 @@ Files that change together but live in different directories reveal implicit dep
 - **Degree uses unfiltered churn.** The denominator (`min(churn)`) counts all commits to a file, including single-file commits. This means degree can understate coupling when a file has high solo churn.
 - **Squash merges collapse coupling signal.** If a branch with 10 separate commits is squash-merged into one, all co-changes within that branch become a single co-occurrence.
 
+## Field reports
+
+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). Honest take:
+>
+> What surfaced new information from the hotspots view:
+>
+> - 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.
+>
+> What `obscene coupling` added on a second run:
+>
+> - 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?"
+>
+> Worth setting expectations on the hotspots view:
+>
+> - 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.
+>
+> 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.
+> - `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: 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
+
 ## License
 
 MIT

package/dist/cli.js

@@ -229,8 +229,8 @@ var RANKING_DEFS = [
   },
   {
     key: "defects",
-    label: "Defects \xD7 Churn",
-    scoreFormula: "defects \xD7 churn"
+    label: "Fix Activity \xD7 Churn",
+    scoreFormula: "fixes \xD7 churn"
   },
   {
     key: "authors",
@@ -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);
@@ -365,20 +392,36 @@ function getNestingDepths(filePaths) {
       depths.set(filePath, 0);
       continue;
     }
-    let minSpaces = Number.POSITIVE_INFINITY;
     const leadings = [];
+    const deltaCounts = /* @__PURE__ */ new Map();
+    let prevSpaceWidth = 0;
     for (const line of content.split("\n")) {
       if (!line.trim()) continue;
       const match = line.match(/^(\s+)/);
-      if (!match) continue;
+      if (!match) {
+        prevSpaceWidth = 0;
+        continue;
+      }
       const leading = match[1];
       leadings.push(leading);
-      const spaceCount = (leading.match(/ /g) ?? []).length;
-      if (spaceCount > 0 && !leading.includes("	") && spaceCount < minSpaces) {
-        minSpaces = spaceCount;
+      if (leading.includes("	")) {
+        continue;
+      }
+      const width = leading.length;
+      const delta = width - prevSpaceWidth;
+      if (delta > 0) {
+        deltaCounts.set(delta, (deltaCounts.get(delta) ?? 0) + 1);
+      }
+      prevSpaceWidth = width;
+    }
+    let indentUnit = 4;
+    let bestCount = 0;
+    for (const [delta, count] of deltaCounts) {
+      if (count > bestCount || count === bestCount && delta < indentUnit) {
+        bestCount = count;
+        indentUnit = delta;
       }
     }
-    const indentUnit = minSpaces === Number.POSITIVE_INFINITY ? 4 : minSpaces;
     let maxDepth = 0;
     for (const leading of leadings) {
       let depth = 0;
@@ -444,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) {
@@ -469,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;
@@ -599,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 ");
@@ -621,6 +679,9 @@ function tierSummary(tierCounts, showing, total) {
 }
 
 // src/format.ts
+var RANKING_LABELS_BY_KEY = Object.fromEntries(
+  RANKING_DEFS.map((d) => [d.key, d.label])
+);
 function formatReportTable(output) {
   const lines = [];
   const { summary, files } = output;
@@ -706,13 +767,13 @@ function getRankingColumns(key) {
     ],
     defects: [
       {
-        header: "Dfcts",
+        header: "Fixes",
         width: 6,
         align: "right",
         value: (e) => String(e.metricValue)
       },
       {
-        header: "DfDns",
+        header: "FxDns",
         width: 7,
         align: "right",
         value: (e) => (e.metricDensity ?? 0).toFixed(4)
@@ -738,7 +799,7 @@ function getRankingColumns(key) {
 var METRIC_EMOJI = {
   complexity: "\u{1F9EC}",
   nesting: "\u{1F4CF}",
-  defects: "\u{1F41B}",
+  defects: "\u{1F527}",
   authors: "\u{1F465}"
 };
 function formatRankingTable(key, ranking, description) {
@@ -777,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++) {
@@ -793,8 +867,8 @@ function formatHotspotsTable(output) {
   if (output.skipped) {
     for (const [key, info] of Object.entries(output.skipped)) {
       lines.push("");
-      const label = key.charAt(0).toUpperCase() + key.slice(1);
-      lines.push(`${label} \xD7 Churn \u2014 skipped (${info.reason})`);
+      const label = RANKING_LABELS_BY_KEY[key] ?? `${key.charAt(0).toUpperCase() + key.slice(1)} \xD7 Churn`;
+      lines.push(`${label} \u2014 skipped (${info.reason})`);
       if (info.suggestion) {
         lines.push(`  ${info.suggestion}`);
       }
@@ -825,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("");
@@ -835,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."
@@ -871,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.0");
+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.",
@@ -881,16 +974,19 @@ var HOTSPOTS_GUIDE = {
   rankings: "Four independent ranking tables, each scoring files by a different metric \xD7 churn. A file may rank high in one dimension but not others.",
   complexity: "complexity \xD7 churn. Complex code that changes often poses maintenance risk.\nSource: McCabe cyclomatic complexity (1976) via scc \xB7 Strength: objective, language-agnostic \xB7 Limit: parsers and state machines score high naturally",
   nesting: "maxNesting \xD7 churn. Deeply nested code that changes often is harder to reason about.\nSource: cognitive complexity research (SonarSource, G. Ann Campbell 2018) \xB7 Strength: catches hard-to-follow control flow \xB7 Limit: some patterns (error chains, config) legitimately nest deep",
-  defects: "defects \xD7 churn. Files with fix: commits that also churn heavily may harbor latent bugs.\nSource: defect prediction via conventional commits (fix: prefix) \xB7 Strength: direct bug-history signal \xB7 Limit: requires consistent fix: convention to be accurate",
+  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(
@@ -996,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)}
@@ -1030,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.0",
+  "version": "2.1.0",
   "description": "Identify hotspot files — complex code that changes frequently. Churn × complexity analysis for any git repo.",
   "type": "module",
   "bin": {