@wbern/obscene 1.1.0 → 1.3.0

package/dist/cli.js

@@ -6,6 +6,17 @@ import { Command } from "commander";
 // src/analyze.ts
 import { execSync } from "child_process";
 import { readFileSync } from "fs";
+var IGNORE_FILES = [".obsignore", ".obsceneignore"];
+function readIgnoreFile() {
+  for (const name of IGNORE_FILES) {
+    try {
+      const content = readFileSync(name, "utf-8");
+      return content.split("\n").map((line) => line.trim()).filter((line) => line !== "" && !line.startsWith("#"));
+    } catch {
+    }
+  }
+  return [];
+}
 var DEFAULT_EXCLUDES = [
   /\.test\./,
   /\.spec\./,
@@ -18,8 +29,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));
 }
@@ -111,7 +124,7 @@ function getAuthors(months) {
     if (!block.trim()) continue;
     const lines = block.split("\n");
     const author = lines[0].trim();
-    if (!author) continue;
+    if (!author || author.endsWith("[bot]")) continue;
     for (let i = 1; i < lines.length; i++) {
       const file = normalizePath(lines[i].trim());
       if (!file) continue;
@@ -174,12 +187,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 +226,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 +257,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 +300,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 +318,7 @@ function computeCoupling(cochanges, churn, complexityMap, minCochanges) {
       totalComplexity,
       couplingScore: count,
       percentOfTotal: 0,
-      tier: "stable"
+      tier: "cool"
     });
   }
   entries.sort((a, b) => b.couplingScore - a.couplingScore);
@@ -346,6 +378,7 @@ function getNestingDepths(filePaths) {
 }
 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++) {
@@ -366,7 +399,7 @@ function computeComposite(rankings, churn, top) {
       file,
       score: Math.round(data.score * 1e4) / 1e4,
       percentOfTotal: 0,
-      tier: "stable",
+      tier: "cool",
       churn: churn.get(file) ?? 0,
       dimensionCount: data.dims
     });
@@ -378,7 +411,8 @@ function computeComposite(rankings, churn, top) {
       label: "Combined",
       scoreFormula: "reciprocal rank fusion across all dimensions",
       totalScore: 0,
-      tierCounts: { danger: 0, watch: 0, stable: 0 },
+      tierCounts: { hot: 0, warm: 0, cool: 0 },
+      totalDimensions,
       totalEntries: 0,
       showing: 0,
       entries: []
@@ -386,7 +420,7 @@ function computeComposite(rankings, churn, top) {
   }
   assignTiers(entries, totalScore);
   const limited = top > 0 ? entries.slice(0, top) : entries;
-  const tierCounts = { danger: 0, watch: 0, stable: 0 };
+  const tierCounts = { hot: 0, warm: 0, cool: 0 };
   for (const e of entries) {
     tierCounts[e.tier]++;
   }
@@ -395,12 +429,16 @@ function computeComposite(rankings, churn, top) {
     scoreFormula: "reciprocal rank fusion across all dimensions",
     totalScore: Math.round(totalScore * 1e4) / 1e4,
     tierCounts,
+    totalDimensions,
     totalEntries: entries.length,
     showing: limited.length,
     entries: limited
   };
 }
 
+// src/format.ts
+import pc2 from "picocolors";
+
 // src/color.ts
 import pc from "picocolors";
 var ANSI_RE = /\x1b\[[0-9;]*m/g;
@@ -412,7 +450,8 @@ function isWide(cp) {
     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 >= 65281 && cp <= 65376 || cp >= 65504 && cp <= 65510 || // Miscellaneous Symbols (U+2600–U+26FF) — includes ☀, ⚡, etc.
+    cp >= 9728 && cp <= 9983 || // 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
   );
@@ -422,9 +461,8 @@ function visualWidth(s) {
   let width = 0;
   for (const ch of stripped) {
     const cp = ch.codePointAt(0);
-    if (cp !== void 0) {
-      width += isWide(cp) ? 2 : 1;
-    }
+    if (cp === 65038 || cp === 65039) continue;
+    width += isWide(cp) ? 2 : 1;
   }
   return width;
 }
@@ -440,19 +478,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.blue("\u{1F9CA} COOL");
 }
 function colorRow(tier, text) {
-  if (tier === "danger") return pc.red(text);
-  if (tier === "watch") return pc.yellow(text);
-  return pc.green(text);
+  if (tier === "hot") return pc.red(text);
+  if (tier === "warm") return pc.yellow(text);
+  return pc.blue(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.blue(`${tierCounts.cool} COOL`)}`
   );
   lines.push(`Showing: ${showing} of ${total}`);
   return lines;
@@ -480,12 +518,16 @@ function formatReportTable(output) {
   }
   lines.push("");
   lines.push(
-    "Complexity=cyclomatic branch/loop count | Density=complexity/code | Comments=comment lines"
+    pc2.dim(
+      "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."
+    pc2.dim(
+      "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");
+  lines.push(pc2.dim("Docs: https://github.com/wbern/obscene#metrics"));
   return lines.join("\n");
 }
 function getRankingColumns(key) {
@@ -569,12 +611,26 @@ function getRankingColumns(key) {
   };
   return [...base, ...metricCols[key] ?? [], tierCol];
 }
-function formatRankingTable(key, ranking) {
+var METRIC_EMOJI = {
+  complexity: "\u{1F9EC}",
+  nesting: "\u{1F4CF}",
+  defects: "\u{1F41B}",
+  authors: "\u{1F465}"
+};
+function formatRankingTable(key, ranking, description) {
   const lines = [];
   const cols = getRankingColumns(key);
+  const emoji = METRIC_EMOJI[key];
+  const prefix = emoji ? `${emoji} ` : "";
+  const title = ranking.label.toUpperCase().replace("CHURN", "\u{1F504} CHURN");
   lines.push(
-    `${ranking.label} \u2014 Total score: ${ranking.totalScore.toLocaleString()}`
+    `${prefix}${title} \u2014 Total score: ${ranking.totalScore.toLocaleString()}`
   );
+  if (description) {
+    for (const line of description.split("\n")) {
+      lines.push(pc2.dim(line));
+    }
+  }
   lines.push(
     ...tierSummary(ranking.tierCounts, ranking.showing, ranking.totalEntries)
   );
@@ -603,19 +659,35 @@ function formatHotspotsTable(output) {
   const keys = Object.keys(rankings);
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i];
-    lines.push(...formatRankingTable(key, rankings[key]));
+    lines.push(...formatRankingTable(key, rankings[key], output.guide[key]));
     if (i < keys.length - 1) {
       lines.push("");
+      lines.push("\xB7 \xB7 \xB7");
+      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."
+    pc2.dim(
+      "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."
+    pc2.dim(
+      "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");
+  lines.push(pc2.dim("Docs: https://github.com/wbern/obscene#metrics"));
   return lines.join("\n");
 }
 function formatCouplingTable(output) {
@@ -635,21 +707,28 @@ function formatCouplingTable(output) {
   }
   lines.push("");
   lines.push(
-    "Shared=co-changed commits | Degree=shared/min(churn)\xD7100 | Cmplx=sum of both files"
+    pc2.dim(
+      "Shared=co-changed commits | Degree=shared/min(churn)\xD7100 | Cmplx=sum of both files"
+    )
   );
   lines.push(
-    "Tiers are relative to THIS codebase, not absolute quality grades. High coupling may be intentional and fine."
+    pc2.dim(
+      "Tiers are relative to THIS codebase, not absolute quality grades. High coupling may be intentional and fine."
+    )
   );
   lines.push(
-    "Same-directory pairs excluded. Commits touching >20 files skipped. Only cross-directory dependencies shown."
+    pc2.dim(
+      "Same-directory pairs excluded. Commits touching >20 files skipped. Only cross-directory dependencies shown."
+    )
   );
-  lines.push("Docs: https://github.com/wbern/obscene#metrics");
+  lines.push(pc2.dim("Docs: https://github.com/wbern/obscene#metrics"));
   return lines.join("\n");
 }
 function formatCompositeTable(output) {
   const lines = [];
+  lines.push("\u2550".repeat(84));
   lines.push(
-    `${output.label} \u2014 Total score: ${output.totalScore.toLocaleString()}`
+    `\u2605 ${output.label.toUpperCase()} \u2014 Total score: ${output.totalScore.toLocaleString()}`
   );
   lines.push(
     ...tierSummary(output.tierCounts, output.showing, output.totalEntries)
@@ -660,7 +739,7 @@ function formatCompositeTable(output) {
   );
   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}/4`, 6) + padLeft(tierLabel(entry.tier), 12);
+    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");
@@ -668,7 +747,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("1.1.0");
+program.name("obscene").description("Identify hotspot files \u2014 complex code that changes frequently").version("1.3.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.",
@@ -676,18 +755,18 @@ var REPORT_GUIDE = {
 };
 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.",
-  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% = danger, next 30% = watch, bottom 20% = stable). NOT an absolute quality grade."
+  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",
+  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."
 };
 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(
@@ -724,9 +803,13 @@ addSharedOptions(
     exitWithError(err);
   }
 });
+function resolveExcludes(cliExcludes) {
+  return [...readIgnoreFile(), ...cliExcludes ?? []];
+}
 function runReport(opts) {
   const top = parseInt(opts.top, 10);
-  const files = runScc(opts.exclude);
+  const allExcludes = resolveExcludes(opts.exclude);
+  const files = runScc(allExcludes);
   const totals = files.reduce(
     (acc, f) => ({
       totalComplexity: acc.totalComplexity + f.complexity,
@@ -758,12 +841,13 @@ function runReport(opts) {
 function runHotspots(opts) {
   const top = parseInt(opts.top, 10);
   const months = parseInt(opts.months, 10);
-  const files = runScc(opts.exclude);
+  const allExcludes = resolveExcludes(opts.exclude);
+  const files = runScc(allExcludes);
   const churn = getChurn(months);
   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,
@@ -777,6 +861,7 @@ function runHotspots(opts) {
     guide: HOTSPOTS_GUIDE,
     churnWindow: `${months} months`,
     rankings,
+    skipped: Object.keys(skipped).length > 0 ? skipped : void 0,
     composite
   };
   if (opts.format === "table") {
@@ -796,9 +881,10 @@ function runCoupling(opts) {
   const top = parseInt(opts.top, 10);
   const months = parseInt(opts.months, 10);
   const minCochanges = parseInt(opts.minCochanges, 10);
-  const files = runScc(opts.exclude);
+  const allExcludes = resolveExcludes(opts.exclude);
+  const files = runScc(allExcludes);
   const churn = getChurn(months);
-  const cochanges = getCoChanges(months, opts.exclude);
+  const cochanges = getCoChanges(months, allExcludes);
   const complexityMap = /* @__PURE__ */ new Map();
   for (const f of files) {
     complexityMap.set(f.file, f.complexity);
@@ -810,7 +896,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.1.0",
+  "version": "1.3.0",
   "description": "Identify hotspot files — complex code that changes frequently. Churn × complexity analysis for any git repo.",
   "type": "module",
   "bin": {