@wbern/obscene 0.3.1 → 1.0.1

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,6 +84,8 @@ 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 from *Your Code as a Crime Scene* (2015). Surfaces hidden structural dependencies that aren't visible in imports or the module graph.
@@ -105,9 +116,9 @@ Per-file complexity without churn. Useful for raw complexity distribution.
 
 ### 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`)
 
@@ -125,9 +136,9 @@ Total cyclomatic complexity as reported by [scc](https://github.com/boyter/scc).
 
 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`)
 
@@ -164,19 +175,34 @@ 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
+
+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=complexity×churn | Dens=complexity/code | Dfcts=fix commits | Nest=max indent depth | Auth=unique authors
+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
 ```
 

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,62 @@ 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";
+
+// src/color.ts
+import pc from "picocolors";
+var ANSI_RE = /\x1b\[[0-9;]*m/g;
+function isWide(cp) {
+  return (
+    // CJK Radicals through Katakana (U+2E80–U+30FF) + CJK Symbols (U+3000–U+303F)
+    cp >= 11904 && cp <= 12543 || // Enclosed CJK Letters + CJK Compatibility (U+3200–U+33FF)
+    cp >= 12800 && cp <= 13311 || // CJK Extension A (U+3400–U+4DBF) + CJK Unified Ideographs (U+4E00–U+9FFF)
+    cp >= 13312 && cp <= 40959 || // Hangul Syllables (U+AC00–U+D7AF)
+    cp >= 44032 && cp <= 55215 || // CJK Compatibility Ideographs (U+F900–U+FAFF)
+    cp >= 63744 && cp <= 64255 || // Fullwidth Forms (U+FF01–U+FF60, U+FFE0–U+FFE6)
+    cp >= 65281 && cp <= 65376 || cp >= 65504 && cp <= 65510 || // Emoji and symbol blocks in supplementary planes (U+1F300–U+1FAFF)
+    cp >= 127744 && cp <= 129791 || // CJK Extension B+ and supplementary ideographs (U+20000–U+2FA1F)
+    cp >= 131072 && cp <= 195103
+  );
+}
+function visualWidth(s) {
+  const stripped = s.replace(ANSI_RE, "");
+  let width = 0;
+  for (const ch of stripped) {
+    const cp = ch.codePointAt(0);
+    if (cp !== void 0) {
+      width += isWide(cp) ? 2 : 1;
     }
-    return { ...h, percentOfTotal, tier };
-  });
+  }
+  return width;
+}
+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
@@ -309,28 +432,129 @@ function formatReportTable(output) {
   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=complexity\xD7churn | Dens=complexity/code | Dfcts=fix commits | Nest=max indent depth | Auth=unique authors"
-  );
-  lines.push(
-    "Tiers are relative to THIS codebase, not absolute quality grades. A 'danger' file in a clean codebase may be fine."
+    "Score=metric\xD7churn | Tiers are relative to THIS codebase, not absolute quality grades."
   );
   lines.push(
     "High scores flag review candidates, not bad code \u2014 stable complex files (parsers, engines) score high naturally."
@@ -344,15 +568,14 @@ 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(
@@ -367,44 +590,22 @@ function formatCouplingTable(output) {
   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`
-  );
-  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)}`;
-}
 
 // src/cli.ts
 var program = new Command();
-program.name("obscene").description("Identify hotspot files \u2014 complex code that changes frequently").version("0.3.1");
+program.name("obscene").description("Identify hotspot files \u2014 complex code that changes frequently").version("1.0.1");
 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 = {
-  hotspotScore: "complexity \xD7 churn. Ranks files by combined risk: complex code that changes often. High score does NOT mean bad code \u2014 stable high-complexity files (parsers, engines) are fine. Focus on files where score is rising over time.",
-  churn: "Commit count in the time window. High churn alone is neutral \u2014 active development is normal. It becomes a signal when combined with high complexity.",
-  tier: "Relative ranking within THIS codebase (top 50% = danger, next 30% = watch, bottom 20% = stable). NOT an absolute quality grade. A 'danger' file in a clean codebase may be perfectly fine. Compare across runs to spot trends.",
-  defects: "Count of fix: conventional commits. A proxy for bug frequency \u2014 0 does not mean bug-free, and >0 does not mean bad code. Useful for spotting files that attract repeated fixes.",
-  defectDensity: "Fix commits per line of code. Normalizes defect count by file size. Only meaningful with conventional commits (fix: prefix).",
-  maxNesting: "Deepest indentation level. >6 suggests complex control flow worth simplifying. Language-dependent \u2014 Python files naturally nest less than C++.",
-  authors: "Unique committers in the time window. High author count may indicate unclear ownership. Low count is normal for specialized code. Neither value is inherently good or bad."
+  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.",
@@ -486,28 +687,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)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wbern/obscene",
-  "version": "0.3.1",
+  "version": "1.0.1",
   "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",