@wbern/obscene 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Bernting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @wbern/obscene
+
+```
+       _==/          i     i          \==_
+     /XX/            |\___/|            \XX\
+   /XXXX\            |XXXXX|            /XXXX\
+  |XXXXXX\_         _XXXXXXX_         _/XXXXXX|
+ XXXXXXXXXXXxxxxxxxXXXXXXXXXXXxxxxxxxXXXXXXXXXXX
+|XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX|
+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+|XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX|
+ XXXXXX/^^^^"\XXXXXXXXXXXXXXXXXXXXX/^^^^^\XXXXXX
+  |XXX|       \XXX/^^\XXXXX/^^\XXX/       |XXX|
+    \XX\       \X/    \XXX/    \X/       /XX/
+       "\       "      \X/      "       /"
+```
+
+**Find hotspot files — complex code that changes frequently.**
+
+Combines [scc](https://github.com/boyter/scc) cyclomatic complexity with git churn to surface files that are both complex AND actively modified. Based on Adam Tornhill's *Your Code as a Crime Scene*.
+
+Works on any language scc supports. No configuration needed.
+
+## Prerequisites
+
+[scc](https://github.com/boyter/scc#install) must be installed and on your PATH.
+
+## Install
+
+```bash
+pnpm add -g @wbern/obscene
+```
+
+```bash
+npm install -g @wbern/obscene   # also works
+```
+
+## Usage
+
+```bash
+obscene                          # top 20 hotspots as JSON
+obscene --format table           # human-readable table
+obscene --top 50 --months 6     # more results, longer window
+obscene --top 0                  # all files
+obscene report                   # raw complexity (no churn)
+obscene --exclude "*.generated.*"
+obscene | jq '.hotspots[0]'     # pipe-friendly
+```
+
+## Commands
+
+### `obscene hotspots` (default)
+
+Scores each file by `complexity × commits` over a time window, then assigns tiers by cumulative score distribution:
+
+| Tier | Range | Meaning |
+|------|-------|---------|
+| **danger** | top 50% of total score | Refactor candidates |
+| **watch** | next 30% (50–80%) | Keep an eye on these |
+| **stable** | bottom 20% | Low risk |
+
+### `obscene report`
+
+Per-file complexity without churn. Useful for raw complexity distribution.
+
+## Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--top <n>` | `20` | Limit results (0 = all) |
+| `--months <n>` | `3` | Churn window in months |
+| `--format <type>` | `json` | `json` or `table` |
+| `--exclude <patterns...>` | — | Additional exclusion patterns |
+
+## Example output
+
+```
+Hotspots — 3 months churn window | Total score: 35452
+Tiers: 3 danger, 13 watch, 194 stable
+Showing: 5 of 210
+
+File                                       Score      %  Churn  Cmplx  Density    Tier
+──────────────────────────────────────────────────────────────────────────────────────
+src/utils/effect-generator.ts               8296   23.4     68    122     0.12  DANGER
+src/services/game-engine.ts                 4284   12.1     51     84     0.09  DANGER
+src/components/board-renderer.tsx           2940    8.3     42     70     0.11  DANGER
+src/hooks/use-game-state.ts                 1320    3.7     33     40     0.08   WATCH
+src/utils/move-validator.ts                  945    2.7     27     35     0.06   WATCH
+```
+
+## Supported languages
+
+Any language [scc supports](https://github.com/boyter/scc#features) — 200+ languages including C, C++, Go, Java, JavaScript, TypeScript, Python, Rust, Ruby, PHP, Swift, Kotlin, and many more. No configuration needed; scc auto-detects languages from file extensions.
+
+## Default exclusions
+
+Test and generated files are excluded automatically: `*.test.*`, `*.spec.*`, `__tests__/`, `__mocks__/`, `*.stories.*`, `*.d.ts`, and similar patterns. scc also skips generated files by default (`--no-gen`).
+
+## Limitations
+
+- **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.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/analyze.ts
+import { execSync } from "child_process";
+var DEFAULT_EXCLUDES = [
+  /\.test\./,
+  /\.spec\./,
+  /\.integration\.test\./,
+  /test-setup\./,
+  /test-utils\./,
+  /test-helpers\./,
+  /__tests__\//,
+  /__mocks__\//,
+  /\.stories\./,
+  /\.d\.ts$/
+];
+var DANGER_CUMULATIVE = 0.5;
+var WATCH_CUMULATIVE = 0.8;
+function isExcluded(location, patterns) {
+  return patterns.some((p) => p.test(location));
+}
+function globToRegex(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\u27E8GLOBSTAR\u27E9").replace(/\*/g, "[^/]*").replace(/⟨GLOBSTAR⟩/g, ".*").replace(/\?/g, ".");
+  return new RegExp(escaped);
+}
+function normalizePath(p) {
+  return p.startsWith("./") ? p.slice(2) : p;
+}
+function runScc(excludes = []) {
+  const patterns = [...DEFAULT_EXCLUDES, ...excludes.map(globToRegex)];
+  let raw;
+  try {
+    raw = execSync("scc --by-file --format json --no-cocomo --no-gen", {
+      maxBuffer: 50 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+      throw new Error(
+        "scc not found. Install it: https://github.com/boyter/scc#install"
+      );
+    }
+    throw err;
+  }
+  const languages = JSON.parse(raw.toString());
+  const files = [];
+  for (const lang of languages) {
+    for (const f of lang.Files) {
+      const normalized = normalizePath(f.Location);
+      if (isExcluded(normalized, patterns)) continue;
+      files.push({
+        file: normalized,
+        code: f.Code,
+        lines: f.Lines,
+        complexity: f.Complexity,
+        comments: f.Comment,
+        complexityDensity: f.Code > 0 ? Math.round(f.Complexity / f.Code * 100) / 100 : 0
+      });
+    }
+  }
+  return files.sort((a, b) => b.complexity - a.complexity);
+}
+function getChurn(months) {
+  let raw;
+  try {
+    raw = execSync(
+      `git log --since="${months} months ago" --format="" --name-only`,
+      { maxBuffer: 50 * 1024 * 1024, stdio: ["pipe", "pipe", "pipe"] }
+    );
+  } catch {
+    throw new Error("Not a git repository or git is not installed.");
+  }
+  const counts = /* @__PURE__ */ new Map();
+  for (const line of raw.toString().split("\n")) {
+    const trimmed = normalizePath(line.trim());
+    if (!trimmed) continue;
+    counts.set(trimmed, (counts.get(trimmed) ?? 0) + 1);
+  }
+  return counts;
+}
+function computeHotspots(files, churn) {
+  const scored = files.map((f) => {
+    const fileChurn = churn.get(f.file) ?? 0;
+    return {
+      ...f,
+      churn: fileChurn,
+      hotspotScore: f.complexity * fileChurn
+    };
+  }).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/format.ts
+function formatReportTable(output) {
+  const lines = [];
+  const { summary, files } = output;
+  lines.push(
+    `Complexity Report \u2014 ${summary.fileCount} files, ${summary.totalComplexity} total complexity`
+  );
+  lines.push(
+    `Showing: ${summary.showing} | Avg complexity/file: ${summary.avgComplexityPerFile}`
+  );
+  lines.push("");
+  lines.push(
+    padRight("File", 60) + padLeft("Code", 8) + padLeft("Complexity", 12) + padLeft("Density", 9) + padLeft("Comments", 10)
+  );
+  lines.push("\u2500".repeat(99));
+  for (const f of files) {
+    lines.push(
+      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)
+    );
+  }
+  return lines.join("\n");
+}
+function formatHotspotsTable(output) {
+  const lines = [];
+  const { tierCounts, totalScore, churnWindow, hotspots } = output;
+  lines.push(
+    `Hotspots \u2014 ${churnWindow} churn window | Total score: ${totalScore.toLocaleString()}`
+  );
+  lines.push(
+    `Tiers: ${tierCounts.danger} danger, ${tierCounts.watch} watch, ${tierCounts.stable} stable`
+  );
+  lines.push(`Showing: ${output.showing} of ${output.totalHotspots}`);
+  lines.push("");
+  lines.push(
+    padRight("File", 50) + padLeft("Score", 8) + padLeft("%", 7) + padLeft("Churn", 7) + padLeft("Cmplx", 7) + padLeft("Density", 9) + padLeft("Tier", 8)
+  );
+  lines.push("\u2500".repeat(96));
+  for (const h of hotspots) {
+    const tierLabel = h.tier === "danger" ? "DANGER" : h.tier === "watch" ? "WATCH" : "stable";
+    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), 9) + padLeft(tierLabel, 8)
+    );
+  }
+  return lines.join("\n");
+}
+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.1.0");
+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.*)"
+  );
+}
+addSharedOptions(
+  program.command("report").description("per-file complexity data")
+).action((opts) => {
+  try {
+    runReport(opts);
+  } catch (err) {
+    exitWithError(err);
+  }
+});
+addSharedOptions(
+  program.command("hotspots", { isDefault: true }).description("churn \xD7 complexity hotspot analysis (default)")
+).option("--months <n>", "churn window in months", "3").action((opts) => {
+  try {
+    runHotspots(opts);
+  } catch (err) {
+    exitWithError(err);
+  }
+});
+function runReport(opts) {
+  const top = parseInt(opts.top, 10);
+  const files = runScc(opts.exclude);
+  const totals = files.reduce(
+    (acc, f) => ({
+      totalComplexity: acc.totalComplexity + f.complexity,
+      totalCode: acc.totalCode + f.code,
+      totalLines: acc.totalLines + f.lines
+    }),
+    { totalComplexity: 0, totalCode: 0, totalLines: 0 }
+  );
+  const limited = top > 0 ? files.slice(0, top) : files;
+  const output = {
+    generated: (/* @__PURE__ */ new Date()).toISOString(),
+    summary: {
+      ...totals,
+      fileCount: files.length,
+      avgComplexityPerFile: files.length > 0 ? Math.round(totals.totalComplexity / files.length * 10) / 10 : 0,
+      showing: limited.length
+    },
+    files: limited
+  };
+  if (opts.format === "table") {
+    process.stdout.write(`${formatReportTable(output)}
+`);
+  } else {
+    process.stdout.write(`${JSON.stringify(output, null, 2)}
+`);
+  }
+}
+function runHotspots(opts) {
+  const top = parseInt(opts.top, 10);
+  const months = parseInt(opts.months, 10);
+  const files = runScc(opts.exclude);
+  const churn = getChurn(months);
+  const hotspots = computeHotspots(files, churn);
+  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(),
+    churnWindow: `${months} months`,
+    totalScore,
+    tierCounts,
+    totalHotspots: hotspots.length,
+    showing: limited.length,
+    hotspots: limited
+  };
+  if (opts.format === "table") {
+    process.stdout.write(`${formatHotspotsTable(output)}
+`);
+  } else {
+    process.stdout.write(`${JSON.stringify(output, null, 2)}
+`);
+  }
+}
+function exitWithError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`Error: ${message}
+`);
+  process.exit(1);
+}
+program.parse();

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@wbern/obscene",
+  "version": "0.1.0",
+  "description": "Identify hotspot files — complex code that changes frequently. Churn × complexity analysis for any git repo.",
+  "type": "module",
+  "bin": {
+    "obscene": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "git",
+    "complexity",
+    "churn",
+    "hotspot",
+    "code-quality",
+    "scc",
+    "static-analysis",
+    "code-review",
+    "technical-debt"
+  ],
+  "license": "MIT",
+  "author": "William Bernting",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wbern/obscene.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/wbern/obscene#readme",
+  "bugs": "https://github.com/wbern/obscene/issues",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@commitlint/cli": "^20.4.2",
+    "@commitlint/config-conventional": "^20.4.2",
+    "@secretlint/secretlint-rule-preset-recommend": "^11.3.1",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/node": "^22.15.2",
+    "@vitest/coverage-v8": "^3.1.0",
+    "@wbern/claude-instructions": "^2.11.0",
+    "husky": "^9.1.7",
+    "jscpd": "^4.0.8",
+    "knip": "^5.84.1",
+    "lint-staged": "^16.2.0",
+    "markdownlint-cli": "^0.44.0",
+    "secretlint": "^11.3.1",
+    "semantic-release": "^25.0.3",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.0"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "package.json"
+          ],
+          "message": "chore(release): ${nextRelease.version}"
+        }
+      ]
+    ]
+  },
+  "scripts": {
+    "postinstall": "claude-instructions --scope=project --prefix= --overwrite || true",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "knip": "knip --no-config-hints",
+    "duplication-check": "jscpd",
+    "markdownlint": "markdownlint --fix '**/*.md' --ignore node_modules"
+  }
+}