@wbern/obscene 0.2.1 → 0.3.0

package/README.md

@@ -57,6 +57,8 @@ 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 coupling                 # temporal coupling analysis
+obscene coupling --min-cochanges 1 --format table
 obscene --exclude "*.generated.*"
 obscene | jq '.hotspots[0]'     # pipe-friendly
 ```
@@ -73,6 +75,18 @@ 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 |
 
+### `obscene coupling`
+
+Detects files that frequently change together in the same commit but live in different directories — Tornhill's "temporal coupling" analysis. Surfaces hidden structural dependencies that aren't visible in the code itself.
+
+Same-directory pairs are excluded (co-location is expected coupling). Mass commits touching >20 files are skipped (formatting changes, large refactors).
+
+```bash
+obscene coupling                          # default: min 2 shared commits
+obscene coupling --min-cochanges 1        # include single co-occurrences
+obscene coupling --format table --top 10  # human-readable, top 10
+```
+
 ### `obscene report`
 
 Per-file complexity without churn. Useful for raw complexity distribution.
@@ -84,6 +98,7 @@ Per-file complexity without churn. Useful for raw complexity distribution.
 | `--top <n>` | `20` | Limit results (0 = all) |
 | `--months <n>` | `3` | Churn window in months |
 | `--format <type>` | `json` | `json` or `table` |
+| `--min-cochanges <n>` | `2` | Minimum shared commits (coupling only) |
 | `--exclude <patterns...>` | — | Additional exclusion patterns |
 
 ## Metrics
@@ -122,6 +137,14 @@ Maximum indentation level (tab stops) in the file. Deep nesting correlates with
 
 Number of distinct git authors who committed to the file within the churn window. Files touched by many authors may lack clear ownership and accumulate inconsistent patterns. Kamei et al. (2013) found developer count to be a significant predictor of defect-introducing changes.
 
+### Shared commits (`Shared`, coupling only)
+
+Number of commits where both files in a pair were modified together. The core ranking metric for temporal coupling — higher values indicate stronger hidden dependencies between files in different directories.
+
+### Coupling degree (`Degree`, coupling only)
+
+`shared commits / min(churn of file1, churn of file2) × 100`. What percentage of the less-active file's changes also involved the other file. A degree of 100% means every change to the less-active file also touched the other file.
+
 ### Tier
 
 Cumulative score distribution bucket:

package/dist/cli.js

@@ -129,6 +129,82 @@ function getAuthors(months) {
   }
   return counts;
 }
+var MAX_FILES_PER_COMMIT = 20;
+function getCoChanges(months, excludes = []) {
+  const patterns = [...DEFAULT_EXCLUDES, ...excludes.map(globToRegex)];
+  let raw;
+  try {
+    raw = execSync(
+      `git log --since="${months} months ago" --format="COMMIT_SEP%n" --name-only`,
+      { maxBuffer: 50 * 1024 * 1024, stdio: ["pipe", "pipe", "pipe"] }
+    );
+  } catch {
+    throw new Error("Not a git repository or git is not installed.");
+  }
+  const cochanges = /* @__PURE__ */ new Map();
+  const commits = raw.toString().split("COMMIT_SEP\n");
+  for (const commit of commits) {
+    if (!commit.trim()) continue;
+    const seen = /* @__PURE__ */ new Set();
+    for (const line of commit.split("\n")) {
+      const trimmed = normalizePath(line.trim());
+      if (!trimmed) continue;
+      if (!isExcluded(trimmed, patterns)) {
+        seen.add(trimmed);
+      }
+    }
+    const files = [...seen];
+    if (files.length < 2 || files.length > MAX_FILES_PER_COMMIT) continue;
+    for (let i = 0; i < files.length; i++) {
+      for (let j = i + 1; j < files.length; j++) {
+        const [a, b] = files[i] < files[j] ? [files[i], files[j]] : [files[j], files[i]];
+        const dirA = a.includes("/") ? a.slice(0, a.lastIndexOf("/")) : "";
+        const dirB = b.includes("/") ? b.slice(0, b.lastIndexOf("/")) : "";
+        if (dirA === dirB) continue;
+        const key = `${a}\0${b}`;
+        cochanges.set(key, (cochanges.get(key) ?? 0) + 1);
+      }
+    }
+  }
+  return cochanges;
+}
+function computeCoupling(cochanges, churn, complexityMap, minCochanges) {
+  const entries = [];
+  for (const [key, count] of cochanges) {
+    if (count < minCochanges) continue;
+    const [file1, file2] = key.split("\0");
+    const minChurn = Math.min(churn.get(file1) ?? 0, churn.get(file2) ?? 0);
+    const degree = minChurn > 0 ? Math.round(count / minChurn * 1e3) / 10 : 0;
+    const totalComplexity = (complexityMap.get(file1) ?? 0) + (complexityMap.get(file2) ?? 0);
+    entries.push({
+      file1,
+      file2,
+      cochanges: count,
+      degree,
+      totalComplexity,
+      couplingScore: count,
+      percentOfTotal: 0,
+      tier: "stable"
+    });
+  }
+  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";
+    }
+  }
+  return entries;
+}
 function getNestingDepths(filePaths) {
   const depths = /* @__PURE__ */ new Map();
   for (const filePath of filePaths) {
@@ -231,19 +307,14 @@ function formatHotspotsTable(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("");
+  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)
   );
   lines.push("\u2500".repeat(112));
   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), 7) + padLeft(String(h.defects), 6) + padLeft(String(h.maxNesting), 6) + padLeft(String(h.authors), 6) + padLeft(tierLabel, 8)
+      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("");
@@ -253,6 +324,41 @@ function formatHotspotsTable(output) {
   lines.push("Docs: https://github.com/wbern/obscene#metrics");
   return lines.join("\n");
 }
+function formatCouplingTable(output) {
+  const lines = [];
+  const { tierCounts, totalScore, churnWindow, couplings } = 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(
+    padRight("File 1", 35) + padRight("File 2", 35) + padLeft("Shared", 7) + padLeft("Degree", 8) + padLeft("Cmplx", 7) + padLeft("Tier", 8)
+  );
+  lines.push("\u2500".repeat(100));
+  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)
+    );
+  }
+  lines.push("");
+  lines.push(
+    "Shared=co-changed commits | Degree=shared/min(churn)\xD7100 | Cmplx=sum of both files"
+  );
+  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);
 }
@@ -265,7 +371,7 @@ function truncate(s, max) {
 
 // src/cli.ts
 var program = new Command();
-program.name("obscene").description("Identify hotspot files \u2014 complex code that changes frequently").version("0.2.1");
+program.name("obscene").description("Identify hotspot files \u2014 complex code that changes frequently").version("0.3.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...>",
@@ -290,6 +396,17 @@ addSharedOptions(
     exitWithError(err);
   }
 });
+addSharedOptions(
+  program.command("coupling").description(
+    "temporal coupling \u2014 files that change together across directories"
+  )
+).option("--months <n>", "churn window in months", "3").option("--min-cochanges <n>", "minimum shared commits to include", "2").action((opts) => {
+  try {
+    runCoupling(opts);
+  } catch (err) {
+    exitWithError(err);
+  }
+});
 function runReport(opts) {
   const top = parseInt(opts.top, 10);
   const files = runScc(opts.exclude);
@@ -358,6 +475,47 @@ function runHotspots(opts) {
 `);
   }
 }
+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 churn = getChurn(months);
+  const cochanges = getCoChanges(months, opts.exclude);
+  const complexityMap = /* @__PURE__ */ new Map();
+  for (const f of files) {
+    complexityMap.set(f.file, f.complexity);
+  }
+  const couplings = computeCoupling(
+    cochanges,
+    churn,
+    complexityMap,
+    minCochanges
+  );
+  const limited = top > 0 ? couplings.slice(0, top) : couplings;
+  const tierCounts = { danger: 0, watch: 0, stable: 0 };
+  for (const c of couplings) {
+    tierCounts[c.tier]++;
+  }
+  const totalScore = couplings.reduce((sum, c) => sum + c.couplingScore, 0);
+  const output = {
+    generated: (/* @__PURE__ */ new Date()).toISOString(),
+    churnWindow: `${months} months`,
+    minCochanges,
+    totalScore,
+    tierCounts,
+    totalCouplings: couplings.length,
+    showing: limited.length,
+    couplings: limited
+  };
+  if (opts.format === "table") {
+    process.stdout.write(`${formatCouplingTable(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}

package/package.json

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