@wbern/obscene 0.3.0 → 1.0.0

package/README.md

@@ -60,14 +60,23 @@ obscene report                   # raw complexity (no churn)
 obscene coupling                 # temporal coupling analysis
 obscene coupling --min-cochanges 1 --format table
 obscene --exclude "*.generated.*"
-obscene | jq '.hotspots[0]'     # pipe-friendly
+obscene | jq '.rankings.complexity.entries[0]'  # pipe-friendly
 ```
 
 ## Commands
 
 ### `obscene hotspots` (default)
 
-Scores each file by `complexity × commits` over a time window, then assigns tiers by cumulative score distribution:
+Produces **four independent ranking tables**, each scoring files by a different metric multiplied by churn:
+
+| Ranking | Score formula | Metric columns |
+|---------|---------------|----------------|
+| Complexity × Churn | `complexity × churn` | Cmplx, Dens |
+| Nesting × Churn | `maxNesting × churn` | Nest |
+| Defects × Churn | `defects × churn` | Dfcts, DfDns |
+| Authors × Churn | `authors × churn` | Auth |
+
+Each table has its own tier assignment by cumulative score distribution:
 
 | Tier | Range | Meaning |
 |------|-------|---------|
@@ -75,11 +84,13 @@ Scores each file by `complexity × commits` over a time window, then assigns tie
 | **watch** | next 30% (50–80%) | Keep an eye on these |
 | **stable** | bottom 20% | Low risk |
 
+A file may rank high in one dimension (e.g. complexity) but low in another (e.g. authors). Tables with no scored entries are omitted.
+
 ### `obscene coupling`
 
-Detects files that frequently change together in the same commit but live in different directories — Tornhill's "temporal coupling" analysis. Surfaces hidden structural dependencies that aren't visible in the code itself.
+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.
 
-Same-directory pairs are excluded (co-location is expected coupling). Mass commits touching >20 files are skipped (formatting changes, large refactors).
+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.
 
 ```bash
 obscene coupling                          # default: min 2 shared commits
@@ -103,49 +114,55 @@ Per-file complexity without churn. Useful for raw complexity distribution.
 
 ## Metrics
 
-Each hotspot row includes the following metrics:
+### Hotspot metrics
 
-### Hotspot score (`Score`)
+#### Score
 
-`complexity × churn`. The core ranking metric — files that are both complex and frequently modified bubble to the top. 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, defects, or authors) multiplied by churn. See [Why churn × complexity?](#why-churn-x-complexity) for the research backing this approach.
 
-### Churn (`Churn`)
+#### Churn (`Churn`)
 
 Number of commits touching the file within the configured time window (default: 3 months). Measures how actively the file is being modified.
 
-### Cyclomatic complexity (`Cmplx`)
+#### 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.
 
-### Complexity density (`Dens`)
+#### 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`)
+#### Defects (`Dfcts`)
 
 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.
 
-### Defect density (`defectDensity`, JSON only)
+#### Defect density (`DfDns`)
 
-`defects / lines of code`. Not shown in table output due to column width, but available in JSON. Normalizes defect count by file size.
+`defects / lines of code`. Shown in the Defects × Churn table. Normalizes defect count by file size.
 
-### Nesting depth (`Nest`)
+#### 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.
 
-### Unique authors (`Auth`)
+#### Unique authors (`Auth`)
 
 Number of distinct git authors who committed to the file within the churn window. Files touched by many authors may lack clear ownership and accumulate inconsistent patterns. Kamei et al. (2013) found developer count to be a significant predictor of defect-introducing changes.
 
-### Shared commits (`Shared`, coupling only)
+### Coupling metrics
+
+#### Shared commits (`Shared`)
+
+Number of commits where both files in a pair were modified together. The core ranking metric for temporal coupling — higher values indicate stronger hidden dependencies between files in different directories. Ball, Kim, Porter & Siy (1997) demonstrated that co-change relationships reveal design dependencies that static analysis misses.
+
+#### Coupling degree (`Degree`)
 
-Number of commits where both files in a pair were modified together. The core ranking metric for temporal coupling — higher values indicate stronger hidden dependencies between files in different directories.
+`shared commits / min(churn of file1, churn of file2) × 100`. What percentage of the less-active file's changes also involved the other file. A degree of 100% means every change to the less-active file also touched the other file. This normalization follows D'Ambros, Lanza & Lungu (2009), who showed that relative coupling measures provide more stable results than raw co-change counts across projects of different sizes.
 
-### Coupling degree (`Degree`, coupling only)
+#### Combined complexity (`Cmplx`)
 
-`shared commits / min(churn of file1, churn of file2) × 100`. What percentage of the less-active file's changes also involved the other file. A degree of 100% means every change to the less-active file also touched the other file.
+Sum of cyclomatic complexity of both files in the pair. Highlights coupled pairs where the involved code is also complex — the combination of hidden dependency and high complexity compounds maintenance risk.
 
-### Tier
+#### Tier
 
 Cumulative score distribution bucket:
 
@@ -158,19 +175,53 @@ Cumulative score distribution bucket:
 ## Example output
 
 ```
-Hotspots — 3 months churn window | Total score: 35,452
+Hotspots — 3 months churn window
+
+Complexity × Churn — Total score: 35,452
 Tiers: 3 danger, 13 watch, 194 stable
 Showing: 5 of 210
 
-File                                                 Score      %  Churn  Cmplx   Dens Dfcts  Nest  Auth    Tier
-────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-src/utils/effect-generator.ts                        8,296   23.4     68    122   0.12     5     6     4  DANGER
-src/services/game-engine.ts                          4,284   12.1     51     84   0.09     3     4     3  DANGER
-src/components/board-renderer.tsx                    2,940    8.3     42     70   0.11     2     5     3  DANGER
-src/hooks/use-game-state.ts                          1,320    3.7     33     40   0.08     1     3     2   WATCH
-src/utils/move-validator.ts                            945    2.7     27     35   0.06     0     2     1   WATCH
+File                                                Score       %  Churn  Cmplx   Dens        Tier
+──────────────────────────────────────────────────────────────────────────────────────────────────
+src/utils/effect-generator.ts                       8,296    23.4     68    122   0.12  🔴 DANGER
+src/services/game-engine.ts                         4,284    12.1     51     84   0.09  🔴 DANGER
+src/components/board-renderer.tsx                   2,940     8.3     42     70   0.11  🔴 DANGER
+src/hooks/use-game-state.ts                         1,320     3.7     33     40   0.08   🟡 WATCH
+src/utils/move-validator.ts                           945     2.7     27     35   0.06   🟡 WATCH
+
+Nesting × Churn — Total score: 1,284
+Tiers: 2 danger, 5 watch, 203 stable
+Showing: 5 of 210
 
-Score=complexity×churn | Dens=complexity/code | Dfcts=fix commits | Nest=max indent depth | Auth=unique authors
+File                                                Score       %  Churn  Nest        Tier
+────────────────────────────────────────────────────────────────────────────────────────
+src/utils/effect-generator.ts                         408    31.8     68     6  🔴 DANGER
+src/services/game-engine.ts                           255    19.8     51     5  🔴 DANGER
+src/components/board-renderer.tsx                     210    16.4     42     5   🟡 WATCH
+src/hooks/use-game-state.ts                            99     7.7     33     3   🟡 WATCH
+src/utils/move-validator.ts                            54     4.2     27     2   🟡 WATCH
+
+Score=metric×churn | Tiers are relative to THIS codebase, not absolute quality grades.
+High scores flag review candidates, not bad code — stable complex files (parsers, engines) score high naturally.
+Docs: https://github.com/wbern/obscene#metrics
+```
+
+### Coupling example
+
+```
+Coupling — 6 months churn window | Min shared: 3 | Total score: 91
+Tiers: 10 danger, 7 watch, 7 stable
+Showing: 5 of 24
+
+File 1                             File 2                              Shared  Degree  Cmplx    Tier
+────────────────────────────────────────────────────────────────────────────────────────────────────
+…ePlayer/hooks/useChessEffects.ts  src/utils/effect-generator.ts            6   46.2%    261  DANGER
+…ePlayer/hooks/useChessEffects.ts  src/utils/pgn-types.ts                   6   50.0%    121  DANGER
+src/test/pgn-fixtures.ts           src/utils/pgn-parser.server.ts           5   71.4%      3  DANGER
+src/test/pgn-fixtures.ts           src/utils/effect-generator.ts            4   57.1%    145  DANGER
+src/test/pgn-fixtures.ts           src/utils/pgn-types.ts                   4   57.1%      5  DANGER
+
+Shared=co-changed commits | Degree=shared/min(churn)×100 | Cmplx=sum of both files
 Docs: https://github.com/wbern/obscene#metrics
 ```
 
@@ -193,14 +244,32 @@ Files that are both complex and frequently modified are disproportionately likel
 
 The general approach was popularized by Adam Tornhill's *Your Code as a Crime Scene* (2015), which applies forensic analysis techniques to version control history.
 
+## Why temporal coupling?
+
+Files that change together but live in different directories reveal implicit dependencies that the module graph doesn't capture. These hidden couplings are a maintenance hazard: a developer modifying one file doesn't know they also need to update the other, leading to bugs that only surface later.
+
+- **Ball, Kim, Porter & Siy (1997)** pioneered co-change analysis and showed that version control history surfaces design relationships invisible to static analysis. — [ICSE 1997 Workshop](https://www.researchgate.net/publication/2791666_If_Your_Version_Control_System_Could_Talk)
+- **D'Ambros, Lanza & Lungu (2009)** developed the Evolution Radar for visualizing logical coupling at both file and module level, showing how evolutionary coupling reveals architectural decay. The normalized approach (coupling relative to total changes) provides more stable measures across projects of different sizes. — [IEEE TSE](https://doi.org/10.1109/TSE.2009.17)
+- **Tornhill (2015)** popularized temporal coupling analysis in *Your Code as a Crime Scene*, demonstrating how co-change patterns reveal "surprise dependencies" — files that should logically be independent but can't be changed separately in practice. His tooling (Code Maat) uses the same commit co-occurrence approach.
+- **Cataldo, Mockus, Roberts & Herbsleb (2009)** analyzed both syntactic and logical dependencies across two large systems and found that logical (co-change) dependencies have a significant independent effect on failure proneness. When developers are unaware of these hidden couplings, defects increase. — [IEEE TSE](https://doi.org/10.1109/TSE.2009.42)
+
 ## Limitations
 
+### General
+
 - **Churn = commit count**, not lines changed. A one-line typo fix counts the same as a 500-line rewrite.
 - **Per-file granularity only.** A 1000-line file with many small functions scores higher than it probably should. No function-level breakdown.
 - **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.
 
+### Coupling-specific
+
+- **Same-directory exclusion is a heuristic.** Files in the same directory that are unexpectedly coupled won't be surfaced. The assumption is that co-located files are *expected* to change together.
+- **Mass commit threshold (>20 files) is hardcoded.** Commits touching many files are skipped to avoid noise from formatting changes and large refactors, but legitimate large features that touch many files across directories are also excluded.
+- **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.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -168,6 +168,108 @@ function getCoChanges(months, excludes = []) {
   }
   return cochanges;
 }
+function assignTiers(items, totalScore) {
+  let cumulative = 0;
+  for (const item of items) {
+    item.percentOfTotal = Math.round(item.score / totalScore * 1e3) / 10;
+    cumulative += item.score;
+    const cumulativeShare = cumulative / totalScore;
+    if (cumulativeShare <= DANGER_CUMULATIVE) {
+      item.tier = "danger";
+    } else if (cumulativeShare <= WATCH_CUMULATIVE) {
+      item.tier = "watch";
+    } else {
+      item.tier = "stable";
+    }
+  }
+}
+var RANKING_DEFS = [
+  {
+    key: "complexity",
+    label: "Complexity \xD7 Churn",
+    scoreFormula: "complexity \xD7 churn"
+  },
+  {
+    key: "nesting",
+    label: "Nesting \xD7 Churn",
+    scoreFormula: "maxNesting \xD7 churn"
+  },
+  {
+    key: "defects",
+    label: "Defects \xD7 Churn",
+    scoreFormula: "defects \xD7 churn"
+  },
+  {
+    key: "authors",
+    label: "Authors \xD7 Churn",
+    scoreFormula: "authors \xD7 churn"
+  }
+];
+function computeRanking(files, churn, metricExtractor, densityExtractor) {
+  const scored = files.map((f) => {
+    const fileChurn = churn.get(f.file) ?? 0;
+    const metricValue = metricExtractor(f);
+    return {
+      file: f.file,
+      score: metricValue * fileChurn,
+      percentOfTotal: 0,
+      tier: "stable",
+      churn: fileChurn,
+      metricValue,
+      metricDensity: densityExtractor ? densityExtractor(f) : void 0
+    };
+  }).filter((e) => e.score > 0).sort((a, b) => b.score - a.score);
+  const totalScore = scored.reduce((sum, e) => sum + e.score, 0);
+  if (totalScore === 0) return [];
+  assignTiers(scored, totalScore);
+  return scored;
+}
+function computeAllRankings(files, churn, defects, nestingDepths, authors, top) {
+  const extractors = {
+    complexity: {
+      extract: (f) => f.complexity,
+      density: (f) => f.complexityDensity
+    },
+    nesting: {
+      extract: (f) => nestingDepths.get(f.file) ?? 0
+    },
+    defects: {
+      extract: (f) => defects.get(f.file) ?? 0,
+      density: (f) => {
+        const d = defects.get(f.file) ?? 0;
+        return f.code > 0 ? Math.round(d / f.code * 1e4) / 1e4 : 0;
+      }
+    },
+    authors: {
+      extract: (f) => authors.get(f.file) ?? 0
+    }
+  };
+  const rankings = {};
+  for (const def of RANKING_DEFS) {
+    const ext = extractors[def.key];
+    const allEntries = computeRanking(files, churn, ext.extract, ext.density);
+    if (allEntries.length === 0) continue;
+    const limited = top > 0 ? allEntries.slice(0, top) : allEntries;
+    const tierCounts = {
+      danger: 0,
+      watch: 0,
+      stable: 0
+    };
+    for (const e of allEntries) {
+      tierCounts[e.tier]++;
+    }
+    rankings[def.key] = {
+      label: def.label,
+      scoreFormula: def.scoreFormula,
+      totalScore: allEntries.reduce((sum, e) => sum + e.score, 0),
+      tierCounts,
+      totalEntries: allEntries.length,
+      showing: limited.length,
+      entries: limited
+    };
+  }
+  return rankings;
+}
 function computeCoupling(cochanges, churn, complexityMap, minCochanges) {
   const entries = [];
   for (const [key, count] of cochanges) {
@@ -190,18 +292,14 @@ function computeCoupling(cochanges, churn, complexityMap, minCochanges) {
   entries.sort((a, b) => b.couplingScore - a.couplingScore);
   const totalScore = entries.reduce((sum, e) => sum + e.couplingScore, 0);
   if (totalScore === 0) return [];
-  let cumulative = 0;
-  for (const entry of entries) {
-    entry.percentOfTotal = Math.round(entry.couplingScore / totalScore * 1e3) / 10;
-    cumulative += entry.couplingScore;
-    const cumulativeShare = cumulative / totalScore;
-    if (cumulativeShare <= DANGER_CUMULATIVE) {
-      entry.tier = "danger";
-    } else if (cumulativeShare <= WATCH_CUMULATIVE) {
-      entry.tier = "watch";
-    } else {
-      entry.tier = "stable";
-    }
+  const adapted = entries.map((e) => ({
+    ...e,
+    score: e.couplingScore
+  }));
+  assignTiers(adapted, totalScore);
+  for (let i = 0; i < entries.length; i++) {
+    entries[i].percentOfTotal = adapted[i].percentOfTotal;
+    entries[i].tier = adapted[i].tier;
   }
   return entries;
 }
@@ -246,37 +344,41 @@ function getNestingDepths(filePaths) {
   }
   return depths;
 }
-function computeHotspots(files, churn, defects = /* @__PURE__ */ new Map(), nestingDepths = /* @__PURE__ */ new Map(), authors = /* @__PURE__ */ new Map()) {
-  const scored = files.map((f) => {
-    const fileChurn = churn.get(f.file) ?? 0;
-    const fileDefects = defects.get(f.file) ?? 0;
-    return {
-      ...f,
-      churn: fileChurn,
-      hotspotScore: f.complexity * fileChurn,
-      defects: fileDefects,
-      defectDensity: f.code > 0 ? Math.round(fileDefects / f.code * 1e4) / 1e4 : 0,
-      maxNesting: nestingDepths.get(f.file) ?? 0,
-      authors: authors.get(f.file) ?? 0
-    };
-  }).filter((h) => h.hotspotScore > 0).sort((a, b) => b.hotspotScore - a.hotspotScore);
-  const totalScore = scored.reduce((sum, h) => sum + h.hotspotScore, 0);
-  if (totalScore === 0) return [];
-  let cumulative = 0;
-  return scored.map((h) => {
-    const percentOfTotal = Math.round(h.hotspotScore / totalScore * 1e3) / 10;
-    cumulative += h.hotspotScore;
-    const cumulativeShare = cumulative / totalScore;
-    let tier;
-    if (cumulativeShare <= DANGER_CUMULATIVE) {
-      tier = "danger";
-    } else if (cumulativeShare <= WATCH_CUMULATIVE) {
-      tier = "watch";
-    } else {
-      tier = "stable";
-    }
-    return { ...h, percentOfTotal, tier };
-  });
+
+// src/color.ts
+import pc from "picocolors";
+var ANSI_RE = /\x1b\[[0-9;]*m/g;
+function visualWidth(s) {
+  return s.replace(ANSI_RE, "").length;
+}
+function padRight(s, n) {
+  const w = visualWidth(s);
+  return w >= n ? s : s + " ".repeat(n - w);
+}
+function padLeft(s, n) {
+  const w = visualWidth(s);
+  return w >= n ? s : " ".repeat(n - w) + s;
+}
+function truncate(s, max) {
+  return s.length <= max ? s : `\u2026${s.slice(s.length - max + 1)}`;
+}
+function tierLabel(tier) {
+  if (tier === "danger") return pc.red("\u{1F534} DANGER");
+  if (tier === "watch") return pc.yellow("\u{1F7E1} WATCH");
+  return pc.green("\u{1F7E2} stable");
+}
+function colorRow(tier, text) {
+  if (tier === "danger") return pc.red(text);
+  if (tier === "watch") return pc.yellow(text);
+  return pc.green(text);
+}
+function tierSummary(tierCounts, showing, total) {
+  const lines = [];
+  lines.push(
+    `Tiers: ${pc.red(`${tierCounts.danger} danger`)}, ${pc.yellow(`${tierCounts.watch} watch`)}, ${pc.green(`${tierCounts.stable} stable`)}`
+  );
+  lines.push(`Showing: ${showing} of ${total}`);
+  return lines;
 }
 
 // src/format.ts
@@ -299,27 +401,142 @@ function formatReportTable(output) {
       padRight(truncate(f.file, 58), 60) + padLeft(String(f.code), 8) + padLeft(String(f.complexity), 12) + padLeft(f.complexityDensity.toFixed(2), 9) + padLeft(String(f.comments), 10)
     );
   }
+  lines.push("");
+  lines.push(
+    "Complexity=cyclomatic branch/loop count | Density=complexity/code | Comments=comment lines"
+  );
+  lines.push(
+    "High complexity is expected for parsers, state machines, and business logic. Compare density across files, not raw values."
+  );
+  lines.push("Docs: https://github.com/wbern/obscene#metrics");
   return lines.join("\n");
 }
-function formatHotspotsTable(output) {
+function getRankingColumns(key) {
+  const base = [
+    {
+      header: "File",
+      width: 50,
+      align: "left",
+      value: (e) => truncate(e.file, 48)
+    },
+    {
+      header: "Score",
+      width: 8,
+      align: "right",
+      value: (e) => e.score.toLocaleString()
+    },
+    {
+      header: "%",
+      width: 7,
+      align: "right",
+      value: (e) => e.percentOfTotal.toFixed(1)
+    },
+    {
+      header: "Churn",
+      width: 7,
+      align: "right",
+      value: (e) => String(e.churn)
+    }
+  ];
+  const metricCols = {
+    complexity: [
+      {
+        header: "Cmplx",
+        width: 7,
+        align: "right",
+        value: (e) => String(e.metricValue)
+      },
+      {
+        header: "Dens",
+        width: 7,
+        align: "right",
+        value: (e) => (e.metricDensity ?? 0).toFixed(2)
+      }
+    ],
+    nesting: [
+      {
+        header: "Nest",
+        width: 6,
+        align: "right",
+        value: (e) => String(e.metricValue)
+      }
+    ],
+    defects: [
+      {
+        header: "Dfcts",
+        width: 6,
+        align: "right",
+        value: (e) => String(e.metricValue)
+      },
+      {
+        header: "DfDns",
+        width: 7,
+        align: "right",
+        value: (e) => (e.metricDensity ?? 0).toFixed(4)
+      }
+    ],
+    authors: [
+      {
+        header: "Auth",
+        width: 6,
+        align: "right",
+        value: (e) => String(e.metricValue)
+      }
+    ]
+  };
+  const tierCol = {
+    header: "Tier",
+    width: 12,
+    align: "right",
+    value: (e) => tierLabel(e.tier)
+  };
+  return [...base, ...metricCols[key] ?? [], tierCol];
+}
+function formatRankingTable(key, ranking) {
   const lines = [];
-  const { tierCounts, totalScore, churnWindow, hotspots } = output;
+  const cols = getRankingColumns(key);
   lines.push(
-    `Hotspots \u2014 ${churnWindow} churn window | Total score: ${totalScore.toLocaleString()}`
+    `${ranking.label} \u2014 Total score: ${ranking.totalScore.toLocaleString()}`
   );
-  pushTierSummary(lines, tierCounts, output.showing, output.totalHotspots);
   lines.push(
-    padRight("File", 50) + padLeft("Score", 8) + padLeft("%", 7) + padLeft("Churn", 7) + padLeft("Cmplx", 7) + padLeft("Dens", 7) + padLeft("Dfcts", 6) + padLeft("Nest", 6) + padLeft("Auth", 6) + padLeft("Tier", 8)
+    ...tierSummary(ranking.tierCounts, ranking.showing, ranking.totalEntries)
   );
-  lines.push("\u2500".repeat(112));
-  for (const h of hotspots) {
-    lines.push(
-      padRight(truncate(h.file, 48), 50) + padLeft(h.hotspotScore.toLocaleString(), 8) + padLeft(h.percentOfTotal.toFixed(1), 7) + padLeft(String(h.churn), 7) + padLeft(String(h.complexity), 7) + padLeft(h.complexityDensity.toFixed(2), 7) + padLeft(String(h.defects), 6) + padLeft(String(h.maxNesting), 6) + padLeft(String(h.authors), 6) + padLeft(tierLabel(h.tier), 8)
-    );
+  lines.push("");
+  const headerLine = cols.map(
+    (c) => c.align === "left" ? padRight(c.header, c.width) : padLeft(c.header, c.width)
+  ).join("");
+  lines.push(headerLine);
+  const totalWidth = cols.reduce((sum, c) => sum + c.width, 0);
+  lines.push("\u2500".repeat(totalWidth));
+  for (const entry of ranking.entries) {
+    const rowParts = cols.map((c) => {
+      const val = c.value(entry);
+      return c.align === "left" ? padRight(val, c.width) : padLeft(val, c.width);
+    });
+    const rawRow = rowParts.join("");
+    lines.push(colorRow(entry.tier, rawRow));
   }
+  return lines;
+}
+function formatHotspotsTable(output) {
+  const lines = [];
+  const { churnWindow, rankings } = output;
+  lines.push(`Hotspots \u2014 ${churnWindow} churn window`);
   lines.push("");
+  const keys = Object.keys(rankings);
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    lines.push(...formatRankingTable(key, rankings[key]));
+    if (i < keys.length - 1) {
+      lines.push("");
+    }
+  }
+  lines.push("");
+  lines.push(
+    "Score=metric\xD7churn | Tiers are relative to THIS codebase, not absolute quality grades."
+  );
   lines.push(
-    "Score=complexity\xD7churn | Dens=complexity/code | Dfcts=fix commits | Nest=max indent depth | Auth=unique authors"
+    "High scores flag review candidates, not bad code \u2014 stable complex files (parsers, engines) score high naturally."
   );
   lines.push("Docs: https://github.com/wbern/obscene#metrics");
   return lines.join("\n");
@@ -330,48 +547,51 @@ function formatCouplingTable(output) {
   lines.push(
     `Coupling \u2014 ${churnWindow} churn window | Min shared: ${output.minCochanges} | Total score: ${totalScore.toLocaleString()}`
   );
-  pushTierSummary(lines, tierCounts, output.showing, output.totalCouplings);
+  lines.push(...tierSummary(tierCounts, output.showing, output.totalCouplings));
   lines.push(
-    padRight("File 1", 35) + padRight("File 2", 35) + padLeft("Shared", 7) + padLeft("Degree", 8) + padLeft("Cmplx", 7) + padLeft("Tier", 8)
+    padRight("File 1", 35) + padRight("File 2", 35) + padLeft("Shared", 7) + padLeft("Degree", 8) + padLeft("Cmplx", 7) + padLeft("Tier", 12)
   );
-  lines.push("\u2500".repeat(100));
+  lines.push("\u2500".repeat(104));
   for (const c of couplings) {
-    lines.push(
-      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), 8)
-    );
+    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);
+    lines.push(colorRow(c.tier, rawRow));
   }
   lines.push("");
   lines.push(
     "Shared=co-changed commits | Degree=shared/min(churn)\xD7100 | Cmplx=sum of both files"
   );
-  lines.push("Docs: https://github.com/wbern/obscene#metrics");
-  return lines.join("\n");
-}
-function pushTierSummary(lines, tierCounts, showing, total) {
   lines.push(
-    `Tiers: ${tierCounts.danger} danger, ${tierCounts.watch} watch, ${tierCounts.stable} stable`
+    "Tiers are relative to THIS codebase, not absolute quality grades. High coupling may be intentional and fine."
   );
-  lines.push(`Showing: ${showing} of ${total}`);
-  lines.push("");
-}
-function tierLabel(tier) {
-  if (tier === "danger") return "DANGER";
-  if (tier === "watch") return "WATCH";
-  return "stable";
-}
-function padRight(s, n) {
-  return s.length >= n ? s : s + " ".repeat(n - s.length);
-}
-function padLeft(s, n) {
-  return s.length >= n ? s : " ".repeat(n - s.length) + s;
-}
-function truncate(s, max) {
-  return s.length <= max ? s : `\u2026${s.slice(s.length - max + 1)}`;
+  lines.push(
+    "Same-directory pairs excluded. Commits touching >20 files skipped. Only cross-directory dependencies shown."
+  );
+  lines.push("Docs: https://github.com/wbern/obscene#metrics");
+  return lines.join("\n");
 }
 
 // src/cli.ts
 var program = new Command();
-program.name("obscene").description("Identify hotspot files \u2014 complex code that changes frequently").version("0.3.0");
+program.name("obscene").description("Identify hotspot files \u2014 complex code that changes frequently").version("1.0.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.",
+  comments: "Comment line count. Low comments in high-density files may indicate under-documented logic. High comments alone is not a problem."
+};
+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. Ranks files by combined risk: complex code that changes often.",
+  nesting: "maxNesting \xD7 churn. Deeply nested code that changes often is harder to reason about.",
+  defects: "defects \xD7 churn. Files with fix: commits that also churn heavily may contain latent bugs.",
+  authors: "authors \xD7 churn. Files touched by many authors and changing often may lack clear ownership.",
+  tier: "Relative ranking within THIS codebase (top 50% = danger, next 30% = watch, bottom 20% = stable). NOT an absolute quality grade."
+};
+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% = danger, next 30% = watch, bottom 20% = stable). NOT an absolute quality grade. 'danger' means this pair co-changes more than most \u2014 it may be intentional and fine."
+};
 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(
     "--exclude <patterns...>",
@@ -421,6 +641,7 @@ function runReport(opts) {
   const limited = top > 0 ? files.slice(0, top) : files;
   const output = {
     generated: (/* @__PURE__ */ new Date()).toISOString(),
+    guide: REPORT_GUIDE,
     summary: {
       ...totals,
       fileCount: files.length,
@@ -445,27 +666,19 @@ function runHotspots(opts) {
   const defects = getDefects(months);
   const authors = getAuthors(months);
   const nestingDepths = getNestingDepths(files.map((f) => f.file));
-  const hotspots = computeHotspots(
+  const rankings = computeAllRankings(
     files,
     churn,
     defects,
     nestingDepths,
-    authors
+    authors,
+    top
   );
-  const limited = top > 0 ? hotspots.slice(0, top) : hotspots;
-  const tierCounts = { danger: 0, watch: 0, stable: 0 };
-  for (const h of hotspots) {
-    tierCounts[h.tier]++;
-  }
-  const totalScore = hotspots.reduce((sum, h) => sum + h.hotspotScore, 0);
   const output = {
     generated: (/* @__PURE__ */ new Date()).toISOString(),
+    guide: HOTSPOTS_GUIDE,
     churnWindow: `${months} months`,
-    totalScore,
-    tierCounts,
-    totalHotspots: hotspots.length,
-    showing: limited.length,
-    hotspots: limited
+    rankings
   };
   if (opts.format === "table") {
     process.stdout.write(`${formatHotspotsTable(output)}
@@ -500,6 +713,7 @@ function runCoupling(opts) {
   const totalScore = couplings.reduce((sum, c) => sum + c.couplingScore, 0);
   const output = {
     generated: (/* @__PURE__ */ new Date()).toISOString(),
+    guide: COUPLING_GUIDE,
     churnWindow: `${months} months`,
     minCochanges,
     totalScore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wbern/obscene",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Identify hotspot files — complex code that changes frequently. Churn × complexity analysis for any git repo.",
   "type": "module",
   "bin": {
@@ -48,7 +48,8 @@
     "node": ">=18"
   },
   "dependencies": {
-    "commander": "^13.1.0"
+    "commander": "^13.1.0",
+    "picocolors": "^1.1.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.0.0",