@wbern/obscene 1.2.0 → 1.3.1

package/dist/cli.js

@@ -6,6 +6,21 @@ 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 (err) {
+      if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+        continue;
+      }
+      throw err;
+    }
+  }
+  return [];
+}
 var DEFAULT_EXCLUDES = [
   /\.test\./,
   /\.spec\./,
@@ -113,7 +128,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;
@@ -425,6 +440,9 @@ function computeComposite(rankings, churn, top) {
   };
 }
 
+// src/format.ts
+import pc2 from "picocolors";
+
 // src/color.ts
 import pc from "picocolors";
 var ANSI_RE = /\x1b\[[0-9;]*m/g;
@@ -436,7 +454,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
   );
@@ -446,9 +465,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;
 }
@@ -464,19 +482,19 @@ function truncate(s, max) {
   return s.length <= max ? s : `\u2026${s.slice(s.length - max + 1)}`;
 }
 function tierLabel(tier) {
-  if (tier === "hot") return pc.red("\u{1F525} HOT");
+  if (tier === "hot") return pc.red("\u{1F525} HOT ");
   if (tier === "warm") return pc.yellow("\u2600\uFE0F WARM");
-  return pc.green("\u{1F9CA} cool");
+  return pc.blue("\u{1F9CA} COOL");
 }
 function colorRow(tier, text) {
   if (tier === "hot") return pc.red(text);
   if (tier === "warm") return pc.yellow(text);
-  return pc.green(text);
+  return pc.blue(text);
 }
 function tierSummary(tierCounts, showing, total) {
   const lines = [];
   lines.push(
-    `Tiers: ${pc.red(`${tierCounts.hot} hot`)}, ${pc.yellow(`${tierCounts.warm} warm`)}, ${pc.green(`${tierCounts.cool} cool`)}`
+    `Tiers: ${pc.red(`${tierCounts.hot} HOT`)}, ${pc.yellow(`${tierCounts.warm} WARM`)}, ${pc.blue(`${tierCounts.cool} COOL`)}`
   );
   lines.push(`Showing: ${showing} of ${total}`);
   return lines;
@@ -504,12 +522,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) {
@@ -593,12 +615,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)
   );
@@ -627,9 +663,11 @@ 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) {
@@ -644,12 +682,16 @@ function formatHotspotsTable(output) {
   }
   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) {
@@ -669,21 +711,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)
@@ -702,7 +751,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.2.0");
+program.name("obscene").description("Identify hotspot files \u2014 complex code that changes frequently").version("1.3.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.",
@@ -710,11 +759,11 @@ 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.",
+  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 = {
@@ -726,7 +775,7 @@ var COUPLING_GUIDE = {
 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...>",
-    "additional file patterns to exclude (e.g. *.generated.*)"
+    "additional file patterns to exclude (also reads .obsignore / .obsceneignore)"
   );
 }
 addSharedOptions(
@@ -758,9 +807,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,
@@ -792,7 +845,8 @@ 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);
@@ -831,9 +885,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);

package/package.json

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