@wbern/obscene 1.4.0 → 2.0.0

package/README.md

@@ -252,9 +252,25 @@ Docs: https://github.com/wbern/obscene#metrics
 
 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
+## Exclusions
 
-Test files, lock files, and package manifests are excluded automatically: `*.test.*`, `*.spec.*`, `__tests__/`, `__mocks__/`, `*.stories.*`, `*.d.ts`, `package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, and similar patterns. scc also skips generated files by default (`--no-gen`).
+All exclusions are opt-in. Run `obscene init` to generate a `.obsignore` file with recommended patterns for your project:
+
+```bash
+obscene init
+```
+
+This creates a `.obsignore` containing:
+- **Universal exclusions** — test files (`*.test.*`, `*.spec.*`, `__tests__/`, etc.), lock files (`package-lock.json`, `pnpm-lock.yaml`, etc.), and package manifests (`package.json`)
+- **Detected project patterns** — CI directories (`.github/`), config files (`*.config.*`), vendored code, etc., based on your project structure
+
+If no `.obsignore` or `.obsceneignore` exists, obscene prints a hint to stderr:
+
+```
+hint: no .obsignore found — run `obscene init` to generate one with recommended exclusions
+```
+
+scc also skips generated files by default (`--no-gen`).
 
 ## Ignore files
 

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { existsSync, writeFileSync } from "fs";
 import { Command } from "commander";
 
 // src/analyze.ts
@@ -21,22 +22,32 @@ function readIgnoreFile() {
   }
   return [];
 }
-var DEFAULT_EXCLUDES = [
-  /\.test\./,
-  /\.spec\./,
-  /\.integration\.test\./,
-  /test-setup\./,
-  /test-utils\./,
-  /test-helpers\./,
-  /__tests__\//,
-  /__mocks__\//,
-  /\.stories\./,
-  /\.d\.ts$/,
-  /(?:^|\/)package\.json$/,
-  /(?:^|\/)package-lock\.json$/,
-  /(?:^|\/)pnpm-lock\.yaml$/,
-  /(?:^|\/)yarn\.lock$/,
-  /(?:^|\/)bun\.lock$/
+var UNIVERSAL_IGNORE_GROUPS = [
+  {
+    title: "Test files and test infrastructure",
+    patterns: [
+      { pattern: "*.test.*", comment: "Unit test files" },
+      { pattern: "*.spec.*", comment: "Spec test files" },
+      { pattern: "*.integration.test.*", comment: "Integration tests" },
+      { pattern: "test-setup.*", comment: "Test setup files" },
+      { pattern: "test-utils.*", comment: "Test utility files" },
+      { pattern: "test-helpers.*", comment: "Test helper files" },
+      { pattern: "__tests__/**", comment: "Test directories" },
+      { pattern: "__mocks__/**", comment: "Mock directories" },
+      { pattern: "*.stories.*", comment: "Storybook stories" },
+      { pattern: "*.d.ts", comment: "TypeScript declaration files" }
+    ]
+  },
+  {
+    title: "Lock files and package manifests",
+    patterns: [
+      { pattern: "package.json", comment: "npm package manifest" },
+      { pattern: "package-lock.json", comment: "npm lock file" },
+      { pattern: "pnpm-lock.yaml", comment: "pnpm lock file" },
+      { pattern: "yarn.lock", comment: "Yarn lock file" },
+      { pattern: "bun.lock", comment: "Bun lock file" }
+    ]
+  }
 ];
 var HOT_CUMULATIVE = 0.5;
 var WARM_CUMULATIVE = 0.8;
@@ -54,7 +65,7 @@ function normalizePath(p) {
   return forwardSlash.startsWith("./") ? forwardSlash.slice(2) : forwardSlash;
 }
 function runScc(excludes = []) {
-  const patterns = [...DEFAULT_EXCLUDES, ...excludes.map(globToRegex)];
+  const patterns = excludes.map(globToRegex);
   let raw;
   try {
     raw = execSync("scc --by-file --format json --no-cocomo --no-gen", {
@@ -153,7 +164,7 @@ function getAuthors(months) {
 }
 var MAX_FILES_PER_COMMIT = 20;
 function getCoChanges(months, excludes = []) {
-  const patterns = [...DEFAULT_EXCLUDES, ...excludes.map(globToRegex)];
+  const patterns = excludes.map(globToRegex);
   let raw;
   try {
     raw = execSync(
@@ -385,6 +396,110 @@ function getNestingDepths(filePaths) {
   }
   return depths;
 }
+var INIT_DIR_RULES = [
+  {
+    dir: ".github",
+    pattern: ".github/**",
+    comment: "GitHub Actions and workflows"
+  },
+  {
+    dir: ".circleci",
+    pattern: ".circleci/**",
+    comment: "CircleCI configuration"
+  },
+  { dir: ".husky", pattern: ".husky/**", comment: "Git hooks" },
+  { dir: ".vscode", pattern: ".vscode/**", comment: "VS Code settings" },
+  { dir: ".idea", pattern: ".idea/**", comment: "JetBrains settings" },
+  {
+    dir: "scripts",
+    pattern: "scripts/**",
+    comment: "Build and utility scripts"
+  },
+  { dir: "docs", pattern: "docs/**", comment: "Documentation" },
+  { dir: "docker", pattern: "docker/**", comment: "Docker configuration" },
+  {
+    dir: "fixtures",
+    pattern: "fixtures/**",
+    comment: "Test fixtures"
+  },
+  {
+    dir: "vendor",
+    pattern: "vendor/**",
+    comment: "Vendored dependencies"
+  }
+];
+var INIT_FILE_RULES = [
+  {
+    test: /\.generated\./,
+    pattern: "*.generated.*",
+    comment: "Generated code"
+  },
+  { test: /\.gen\.[^.]+$/, pattern: "*.gen.*", comment: "Generated code" },
+  {
+    test: /\.config\.\w/,
+    pattern: "*.config.*",
+    comment: "Configuration files"
+  },
+  {
+    test: /(?:^|\/)\.gitlab-ci/,
+    pattern: ".gitlab-ci*",
+    comment: "GitLab CI configuration"
+  }
+];
+function detectIgnorePatterns() {
+  let raw;
+  try {
+    raw = execSync("git ls-files", {
+      maxBuffer: 50 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch {
+    throw new Error("Not a git repository or git is not installed.");
+  }
+  const trackedFiles = raw.toString().split("\n").map((l) => normalizePath(l.trim())).filter(Boolean);
+  const patterns = [];
+  const topDirs = /* @__PURE__ */ new Set();
+  for (const f of trackedFiles) {
+    const slash = f.indexOf("/");
+    if (slash > 0) topDirs.add(f.slice(0, slash));
+  }
+  for (const rule of INIT_DIR_RULES) {
+    if (topDirs.has(rule.dir)) {
+      patterns.push({ pattern: rule.pattern, comment: rule.comment });
+    }
+  }
+  for (const rule of INIT_FILE_RULES) {
+    if (trackedFiles.some((f) => rule.test.test(f))) {
+      patterns.push({ pattern: rule.pattern, comment: rule.comment });
+    }
+  }
+  return patterns;
+}
+function formatIgnoreFile(detectedPatterns, universalGroups = UNIVERSAL_IGNORE_GROUPS) {
+  const lines = [
+    "# Generated by obscene init",
+    "# Edit this file to customize which files are excluded from analysis.",
+    "# Patterns use glob syntax (same as .gitignore).",
+    "# See: https://github.com/wbern/obscene#ignore-files",
+    ""
+  ];
+  for (const group of universalGroups) {
+    lines.push(`# ${group.title}`);
+    for (const p of group.patterns) {
+      lines.push(p.pattern);
+    }
+    lines.push("");
+  }
+  if (detectedPatterns.length > 0) {
+    lines.push("# Project-specific patterns");
+    for (const p of detectedPatterns) {
+      lines.push(`# ${p.comment}`);
+      lines.push(p.pattern);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
 var RRF_K = 10;
 function computeComposite(rankings, churn, top) {
   const totalDimensions = Object.keys(rankings).length;
@@ -756,7 +871,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.4.0");
+program.name("obscene").description("Identify hotspot files \u2014 complex code that changes frequently").version("2.0.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.",
@@ -812,10 +927,25 @@ addSharedOptions(
     exitWithError(err);
   }
 });
+program.command("init").description("generate a starter .obsignore based on project structure").action(() => {
+  try {
+    runInit();
+  } catch (err) {
+    exitWithError(err);
+  }
+});
 function resolveExcludes(cliExcludes) {
   return [...readIgnoreFile(), ...cliExcludes ?? []];
 }
+function warnIfNoIgnoreFile() {
+  if (!existsSync(".obsignore") && !existsSync(".obsceneignore")) {
+    process.stderr.write(
+      "hint: no .obsignore found \u2014 run `obscene init` to generate one with recommended exclusions\n"
+    );
+  }
+}
 function runReport(opts) {
+  warnIfNoIgnoreFile();
   const top = parseInt(opts.top, 10);
   const allExcludes = resolveExcludes(opts.exclude);
   const files = runScc(allExcludes);
@@ -848,6 +978,7 @@ function runReport(opts) {
   }
 }
 function runHotspots(opts) {
+  warnIfNoIgnoreFile();
   const top = parseInt(opts.top, 10);
   const months = parseInt(opts.months, 10);
   const allExcludes = resolveExcludes(opts.exclude);
@@ -887,6 +1018,7 @@ ${formatCompositeTable(composite)}
   }
 }
 function runCoupling(opts) {
+  warnIfNoIgnoreFile();
   const top = parseInt(opts.top, 10);
   const months = parseInt(opts.months, 10);
   const minCochanges = parseInt(opts.minCochanges, 10);
@@ -929,6 +1061,38 @@ function runCoupling(opts) {
 `);
   }
 }
+function runInit() {
+  if (existsSync(".obsignore")) {
+    throw new Error(
+      ".obsignore already exists. Remove it first to regenerate."
+    );
+  }
+  if (existsSync(".obsceneignore")) {
+    throw new Error(
+      ".obsceneignore already exists. Remove it first to regenerate."
+    );
+  }
+  const detected = detectIgnorePatterns();
+  const content = formatIgnoreFile(detected);
+  writeFileSync(".obsignore", content);
+  const universalCount = UNIVERSAL_IGNORE_GROUPS.reduce(
+    (sum, g) => sum + g.patterns.length,
+    0
+  );
+  process.stderr.write(
+    `Created .obsignore with ${universalCount} universal exclusions`
+  );
+  if (detected.length > 0) {
+    process.stderr.write(` + ${detected.length} detected patterns:
+`);
+    for (const p of detected) {
+      process.stderr.write(`  ${p.pattern.padEnd(20)} ${p.comment}
+`);
+    }
+  } else {
+    process.stderr.write(" (no project-specific patterns detected)\n");
+  }
+}
 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": "1.4.0",
+  "version": "2.0.0",
   "description": "Identify hotspot files — complex code that changes frequently. Churn × complexity analysis for any git repo.",
   "type": "module",
   "bin": {