@wbern/obscene 1.0.1 → 1.2.0

package/dist/cli.js

@@ -18,8 +18,10 @@ var DEFAULT_EXCLUDES = [
   /\.stories\./,
   /\.d\.ts$/
 ];
-var DANGER_CUMULATIVE = 0.5;
-var WATCH_CUMULATIVE = 0.8;
+var HOT_CUMULATIVE = 0.5;
+var WARM_CUMULATIVE = 0.8;
+var MIN_FIX_COMMITS = 5;
+var MIN_FILES_WITH_FIXES = 3;
 function isExcluded(location, patterns) {
   return patterns.some((p) => p.test(location));
 }
@@ -174,12 +176,12 @@ function assignTiers(items, totalScore) {
     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";
+    if (cumulativeShare <= HOT_CUMULATIVE) {
+      item.tier = "hot";
+    } else if (cumulativeShare <= WARM_CUMULATIVE) {
+      item.tier = "warm";
     } else {
-      item.tier = "stable";
+      item.tier = "cool";
     }
   }
 }
@@ -213,7 +215,7 @@ function computeRanking(files, churn, metricExtractor, densityExtractor) {
       file: f.file,
       score: metricValue * fileChurn,
       percentOfTotal: 0,
-      tier: "stable",
+      tier: "cool",
       churn: fileChurn,
       metricValue,
       metricDensity: densityExtractor ? densityExtractor(f) : void 0
@@ -244,16 +246,35 @@ function computeAllRankings(files, churn, defects, nestingDepths, authors, top)
       extract: (f) => authors.get(f.file) ?? 0
     }
   };
+  const skipped = {};
+  const totalFixCommits = [...defects.values()].reduce((s, v) => s + v, 0);
+  const filesWithFixes = defects.size;
+  if (totalFixCommits < MIN_FIX_COMMITS || filesWithFixes < MIN_FILES_WITH_FIXES) {
+    skipped.defects = {
+      reason: `insufficient data (${totalFixCommits} fix: commits across ${filesWithFixes} files, need ${MIN_FIX_COMMITS}+ commits across ${MIN_FILES_WITH_FIXES}+ files)`,
+      suggestion: "Adopt conventional commits with fix: prefix. See conventionalcommits.org"
+    };
+  }
+  let maxAuthors = 0;
+  for (const count of authors.values()) {
+    if (count > maxAuthors) maxAuthors = count;
+  }
+  if (maxAuthors <= 1) {
+    skipped.authors = {
+      reason: "all files have the same author count \u2014 no variance to rank"
+    };
+  }
   const rankings = {};
   for (const def of RANKING_DEFS) {
+    if (skipped[def.key]) continue;
     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
+      hot: 0,
+      warm: 0,
+      cool: 0
     };
     for (const e of allEntries) {
       tierCounts[e.tier]++;
@@ -268,7 +289,7 @@ function computeAllRankings(files, churn, defects, nestingDepths, authors, top)
       entries: limited
     };
   }
-  return rankings;
+  return { rankings, skipped };
 }
 function computeCoupling(cochanges, churn, complexityMap, minCochanges) {
   const entries = [];
@@ -286,7 +307,7 @@ function computeCoupling(cochanges, churn, complexityMap, minCochanges) {
       totalComplexity,
       couplingScore: count,
       percentOfTotal: 0,
-      tier: "stable"
+      tier: "cool"
     });
   }
   entries.sort((a, b) => b.couplingScore - a.couplingScore);
@@ -344,6 +365,65 @@ function getNestingDepths(filePaths) {
   }
   return depths;
 }
+var RRF_K = 10;
+function computeComposite(rankings, churn, top) {
+  const totalDimensions = Object.keys(rankings).length;
+  const fileScores = /* @__PURE__ */ new Map();
+  for (const ranking of Object.values(rankings)) {
+    for (let i = 0; i < ranking.entries.length; i++) {
+      const file = ranking.entries[i].file;
+      const rrf = 1 / (RRF_K + i + 1);
+      const existing = fileScores.get(file);
+      if (existing) {
+        existing.score += rrf;
+        existing.dims += 1;
+      } else {
+        fileScores.set(file, { score: rrf, dims: 1 });
+      }
+    }
+  }
+  const entries = [];
+  for (const [file, data] of fileScores) {
+    entries.push({
+      file,
+      score: Math.round(data.score * 1e4) / 1e4,
+      percentOfTotal: 0,
+      tier: "cool",
+      churn: churn.get(file) ?? 0,
+      dimensionCount: data.dims
+    });
+  }
+  entries.sort((a, b) => b.score - a.score);
+  const totalScore = entries.reduce((sum, e) => sum + e.score, 0);
+  if (totalScore === 0) {
+    return {
+      label: "Combined",
+      scoreFormula: "reciprocal rank fusion across all dimensions",
+      totalScore: 0,
+      tierCounts: { hot: 0, warm: 0, cool: 0 },
+      totalDimensions,
+      totalEntries: 0,
+      showing: 0,
+      entries: []
+    };
+  }
+  assignTiers(entries, totalScore);
+  const limited = top > 0 ? entries.slice(0, top) : entries;
+  const tierCounts = { hot: 0, warm: 0, cool: 0 };
+  for (const e of entries) {
+    tierCounts[e.tier]++;
+  }
+  return {
+    label: "Combined",
+    scoreFormula: "reciprocal rank fusion across all dimensions",
+    totalScore: Math.round(totalScore * 1e4) / 1e4,
+    tierCounts,
+    totalDimensions,
+    totalEntries: entries.length,
+    showing: limited.length,
+    entries: limited
+  };
+}
 
 // src/color.ts
 import pc from "picocolors";
@@ -384,19 +464,19 @@ 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");
+  if (tier === "hot") return pc.red("\u{1F525} HOT");
+  if (tier === "warm") return pc.yellow("\u2600\uFE0F WARM");
+  return pc.green("\u{1F9CA} cool");
 }
 function colorRow(tier, text) {
-  if (tier === "danger") return pc.red(text);
-  if (tier === "watch") return pc.yellow(text);
+  if (tier === "hot") return pc.red(text);
+  if (tier === "warm") 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`)}`
+    `Tiers: ${pc.red(`${tierCounts.hot} hot`)}, ${pc.yellow(`${tierCounts.warm} warm`)}, ${pc.green(`${tierCounts.cool} cool`)}`
   );
   lines.push(`Showing: ${showing} of ${total}`);
   return lines;
@@ -552,6 +632,16 @@ function formatHotspotsTable(output) {
       lines.push("");
     }
   }
+  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})`);
+      if (info.suggestion) {
+        lines.push(`  ${info.suggestion}`);
+      }
+    }
+  }
   lines.push("");
   lines.push(
     "Score=metric\xD7churn | Tiers are relative to THIS codebase, not absolute quality grades."
@@ -590,10 +680,29 @@ function formatCouplingTable(output) {
   lines.push("Docs: https://github.com/wbern/obscene#metrics");
   return lines.join("\n");
 }
+function formatCompositeTable(output) {
+  const lines = [];
+  lines.push(
+    `${output.label} \u2014 Total score: ${output.totalScore.toLocaleString()}`
+  );
+  lines.push(
+    ...tierSummary(output.tierCounts, output.showing, output.totalEntries)
+  );
+  lines.push("");
+  lines.push(
+    padRight("File", 50) + padLeft("Score", 9) + padLeft("Churn", 7) + padLeft("Dims", 6) + padLeft("Tier", 12)
+  );
+  lines.push("\u2500".repeat(84));
+  for (const entry of output.entries) {
+    const rawRow = padRight(truncate(entry.file, 48), 50) + padLeft(entry.score.toFixed(4), 9) + padLeft(String(entry.churn), 7) + padLeft(`${entry.dimensionCount}/${output.totalDimensions}`, 6) + padLeft(tierLabel(entry.tier), 12);
+    lines.push(colorRow(entry.tier, rawRow));
+  }
+  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("1.0.1");
+program.name("obscene").description("Identify hotspot files \u2014 complex code that changes frequently").version("1.2.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.",
@@ -605,13 +714,14 @@ var HOTSPOTS_GUIDE = {
   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."
+  composite: "Combined ranking using Reciprocal Rank Fusion (RRF) across all dimensions. Files appearing near the top of multiple rankings score highest.",
+  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."
 };
 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."
+  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."
 };
 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(
@@ -687,7 +797,7 @@ function runHotspots(opts) {
   const defects = getDefects(months);
   const authors = getAuthors(months);
   const nestingDepths = getNestingDepths(files.map((f) => f.file));
-  const rankings = computeAllRankings(
+  const { rankings, skipped } = computeAllRankings(
     files,
     churn,
     defects,
@@ -695,15 +805,23 @@ function runHotspots(opts) {
     authors,
     top
   );
+  const composite = computeComposite(rankings, churn, top);
   const output = {
     generated: (/* @__PURE__ */ new Date()).toISOString(),
     guide: HOTSPOTS_GUIDE,
     churnWindow: `${months} months`,
-    rankings
+    rankings,
+    skipped: Object.keys(skipped).length > 0 ? skipped : void 0,
+    composite
   };
   if (opts.format === "table") {
     process.stdout.write(`${formatHotspotsTable(output)}
 `);
+    if (composite.entries.length > 0) {
+      process.stdout.write(`
+${formatCompositeTable(composite)}
+`);
+    }
   } else {
     process.stdout.write(`${JSON.stringify(output, null, 2)}
 `);
@@ -727,7 +845,7 @@ function runCoupling(opts) {
     minCochanges
   );
   const limited = top > 0 ? couplings.slice(0, top) : couplings;
-  const tierCounts = { danger: 0, watch: 0, stable: 0 };
+  const tierCounts = { hot: 0, warm: 0, cool: 0 };
   for (const c of couplings) {
     tierCounts[c.tier]++;
   }

package/package.json

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