opencode-anti-slop 0.1.1 → 0.1.4

package/install.mjs

@@ -23,7 +23,7 @@
  *   node install.mjs [target-repo-dir] [--force] [--hooks]
  */
 
-import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -104,6 +104,22 @@ for (const entry of readdirSync(commandsSrc, { withFileTypes: true })) {
   }
 }
 
+// --- starter config -----------------------------------------------------------
+// Scaffold anti-slop.config.json when the target has none, so the tuning
+// surface exists from day one. JSON has no comments; the reasoning for the
+// starter rules is printed in the manual steps below.
+const configDest = path.join(target, 'anti-slop.config.json');
+if (!existsSync(configDest)) {
+  const starter = {
+    duplicates: { src: 'src', minTokens: 50, threshold: 3, ignore: [] },
+    modularity: { src: 'src', maxFileLines: 300, maxFunctionLines: 80, maxClassMethods: 10 },
+    docs: { src: 'src', ignorePaths: [], ignoreExports: [] },
+    imports: { deny: [] },
+  };
+  writeFileSync(configDest, `${JSON.stringify(starter, null, 2)}\n`);
+  console.log(`[ok] ${configDest} (starter — tune ignore lists to your framework's declarative files)`);
+}
+
 // --- manual steps -----------------------------------------------------------
 console.log(`
 Manual setup in ${target} (one-time):
@@ -133,13 +149,29 @@ Manual setup in ${target} (one-time):
 
 4. ESLint: enable eslint-plugin-react-hooks (and the React Compiler eslint
    plugin if the project uses the compiler) so hook misuse fails in the linter.
+   Consider ignoring the vendored gate scripts from your repo lint:
+   \`{ ignores: ['scripts/anti-slop/**'] }\` in eslint.config — they are
+   self-linted by this kit's own CI.
 
 5. Generate the first inventory:  node scripts/anti-slop/generate-component-index.mjs
 
 6. Git gates (recommended):  git init && node scripts/anti-slop/install-hooks.mjs
    - pre-commit: modularity + docs on staged files (blocking), duplicate/import reports
-   - pre-push: full duplicate + import gates + lint/typecheck/test via --if-present
+   - pre-push: full duplicate + import gates + lint/typecheck/test via run-project-checks
    - /audit-ui in OpenCode produces a prioritized refactor plan from the same checks
+
+7. Layer direction (imports.deny): the import gate detects cycles out of the box;
+   it enforces layer direction once you declare rules in anti-slop.config.json.
+   Starter rules to adapt (paths must match your layout):
+
+   "imports": { "deny": [
+     { "from": "src/components/**", "forbid": "src/collections/**" },
+     { "from": "src/app/**", "forbid": "src/collections/**" },
+     { "from": "src/access/**", "forbid": "src/app/**" }
+   ] }
+
+   With no rules the gate prints a cycles-only notice so a green result is never
+   mistaken for full architectural enforcement.
 `);
 
 // --- optional hooks ------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-anti-slop",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "OpenCode enforcement kit: agent skills plus deterministic gates that keep AI-generated React and Node code modular, DRY, and documented",
   "license": "MIT",
   "type": "module",

package/scripts/anti-slop/baseline.mjs

@@ -0,0 +1,147 @@
+/**
+ * baseline.mjs — the ratchet: gates fail only on violations NEWER than the
+ * committed `anti-slop.baseline.json` snapshot, so adopting a repo with legacy
+ * debt does not require a big-bang cleanup. Counts must only go down; growing
+ * a file's count beyond its baseline (or introducing a new file with debt) is
+ * a failure. Shrinking is always allowed, with a hint to re-snapshot.
+ *
+ * Zero dependencies (Node >= 18, ESM). Used by check-duplicates (per-file
+ * duplicated-line counts), check-modularity (per-file/per-kind violation
+ * counts), check-docs (per-file undocumented-export counts), and
+ * check-imports (cycle identity sets — deny-rule violations are never
+ * baselined, since rules are declared deliberately).
+ */
+
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+/** Default baseline path: gates auto-ratchet when this file exists at the repo root. */
+export const BASELINE_FILE = 'anti-slop.baseline.json';
+const BASELINE_COMMENT =
+  'Ratchet baseline: gates fail only on violations newer than this snapshot. ' +
+  'Shrink it after cleanup with <gate> --update-baseline; do not grow it to absorb new debt.';
+
+/** Load a baseline snapshot; null when the file is absent, warn+null when unparsable. */
+export function loadBaseline(file = BASELINE_FILE) {
+  const abs = path.resolve(file);
+  if (!existsSync(abs)) return null;
+  try {
+    return JSON.parse(readFileSync(abs, 'utf8'));
+  } catch (err) {
+    console.error(`[warn] Could not parse baseline ${file} (${err.message}); running without baseline.`);
+    return null;
+  }
+}
+
+/** Write a baseline snapshot with sorted keys so diffs stay stable. Merges with
+ * an existing file per top-level section, so each gate's --update-baseline
+ * only refreshes its own section instead of clobbering the others. */
+export function saveBaseline(file, snapshot) {
+  const abs = path.resolve(file);
+  let existing = {};
+  if (existsSync(abs)) {
+    try {
+      existing = JSON.parse(readFileSync(abs, 'utf8')) ?? {};
+    } catch {
+      existing = {}; // unparsable baseline gets replaced wholesale
+    }
+  }
+  const merged = sortDeep({ ...existing, ...sortDeep(snapshot), _comment: BASELINE_COMMENT });
+  const out = `${JSON.stringify(merged, null, 2)}\n`;
+  writeFileSync(abs, out);
+}
+
+function sortDeep(value) {
+  if (Array.isArray(value)) return value.map(sortDeep);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => [k, sortDeep(v)]),
+    );
+  }
+  return value;
+}
+
+/** Compare per-file counts against a baseline { rel: count }. New = file unseen or count grew. */
+export function compareCounts(current, baselineFiles) {
+  const base = baselineFiles ?? {};
+  const newDebt = [];
+  const improved = [];
+  for (const [rel, count] of Object.entries(current)) {
+    const accepted = base[rel];
+    if (accepted === undefined) {
+      if (count > 0) newDebt.push({ rel, count, accepted: 0 });
+      continue;
+    }
+    if (count > accepted) newDebt.push({ rel, count, accepted });
+    else if (count < accepted) improved.push({ rel, count, accepted });
+  }
+  return { newDebt, improved };
+}
+
+/** Compare per-file/per-kind counts against a baseline { rel: { kind: count } }. */
+export function compareKindCounts(current, baselineFiles) {
+  const base = baselineFiles ?? {};
+  const newDebt = [];
+  const improved = [];
+  for (const [rel, kinds] of Object.entries(current)) {
+    const accepted = base[rel] ?? {};
+    for (const [kind, count] of Object.entries(kinds)) {
+      if (count > (accepted[kind] ?? 0)) newDebt.push({ rel, kind, count, accepted: accepted[kind] ?? 0 });
+      else if (count < (accepted[kind] ?? 0)) improved.push({ rel, kind, count, accepted: accepted[kind] ?? 0 });
+    }
+  }
+  return { newDebt, improved };
+}
+
+/** Compare an identity set (e.g. cycle keys) against a baseline array. */
+export function compareSets(current, baselineItems) {
+  const base = new Set(baselineItems ?? []);
+  const added = current.filter((k) => !base.has(k));
+  const removed = (baselineItems ?? []).filter((k) => !current.includes(k));
+  return { added, removed };
+}
+
+/**
+ * Shared ratchet flow for count-based gates (duplicates/docs/modularity).
+ *
+ * - `--update-baseline`: writes `{ [section]: { files: current, ...extra } }`
+ *   and returns 'ok' (exit 0 in the gate).
+ * - baseline file exists: fails only on NEW debt (unseen file or grown count)
+ *   and returns 'fail'; otherwise 'ok' with an --update-baseline hint when
+ *   files improved.
+ * - no baseline: returns 'none' so the gate falls through to its own gate logic.
+ *
+ * `kindCounts` compares `{ rel: { kind: count } }` instead of `{ rel: count }`.
+ */
+export function baselineGate({ args, section, current, kindCounts = false, extra = {}, unit, showKind = false, fixLine }) {
+  if (args.updateBaseline) {
+    const file = args.baseline ?? BASELINE_FILE;
+    saveBaseline(file, { [section]: { files: current, ...extra } });
+    const total = Object.values(current).reduce((n, v) => n + (kindCounts ? Object.values(v).reduce((a, b) => a + b, 0) : v), 0);
+    console.log(`[ok] Baseline written to ${file} (${total} ${unit} across ${Object.keys(current).length} file(s)).`);
+    console.log('    Commit it. The gate now fails only on NEW debt; shrink the baseline as you clean up.');
+    return 'ok';
+  }
+  const baseline = loadBaseline(args.baseline);
+  if (!baseline?.[section]) return 'none';
+  const { newDebt, improved } = kindCounts
+    ? compareKindCounts(current, baseline[section].files)
+    : compareCounts(current, baseline[section].files);
+  if (newDebt.length === 0) {
+    console.log(`[ok] ${section} check passed within baseline (0 new${improved.length > 0 ? ' — consider --update-baseline to lock in the cleanup' : ''}).`);
+    return 'ok';
+  }
+  console.error(`[x] NEW ${unit} beyond baseline (${newDebt.length} file(s)):`);
+  for (const d of newDebt.slice(0, 20)) {
+    console.error(showKind
+      ? `    ${d.rel}: [${d.kind}] count ${d.count} (accepted: ${d.accepted})`
+      : `    ${d.rel}: ${d.count} ${unit} (accepted: ${d.accepted})`);
+  }
+  console.error(
+    `    ${fixLine}\n` +
+    '    The baseline records accepted debt — do NOT update it to absorb new debt.'
+  );
+  return 'fail';
+}

package/scripts/anti-slop/check-docs.mjs

@@ -1,70 +1,109 @@
-#!/usr/bin/env node
-/**
- * check-docs.mjs
- *
- * Documentation gate for shared exports. Fails (exit 1) when exported
- * declarations in the checked files lack a one-line `/** When to use ... *\/`
- * JSDoc above them. Keeps docs/COMPONENT_INDEX.md (generated from the same
- * JSDoc) a maintained, trustworthy inventory instead of a stale artifact.
- *
- * Zero dependencies.
- *
- * Usage:
- *   node scripts/anti-slop/check-docs.mjs [paths...] [--src src] [--report-only]
- *
- * With no path arguments it scans --src (default `src`). With path arguments
- * it checks exactly those files — used by git hooks to check only staged
- * files, so legacy undocumented code never blocks commits.
- */
-
-import { readFileSync, existsSync } from 'node:fs';
-import path from 'node:path';
-import { walk, extractExports } from './lib.mjs';
-import { loadConfig, bootstrapGate, collectPathFiles, resolveScanTarget } from './cli.mjs';
-
-// Defaults < anti-slop.config.json < CLI flags.
-const cfgDocs = loadConfig().docs ?? {};
-const { args, positionals } = bootstrapGate(process.argv.slice(2), {
-  usage: 'Usage: node check-docs.mjs [paths...] [--src src] [--report-only]\n' +
-         'Config: anti-slop.config.json "docs" section (src).\n' +
-         'With path arguments, checks exactly those files (git-hook staged mode).',
-  spec: { '--src': 'string', '--report-only': 'flag' },
-  defaults: { src: cfgDocs.src ?? 'src' },
-});
-
-const files = positionals.length > 0 ? collectPathFiles(positionals) : resolveScanTarget(args.src);
-
-let missing = 0;
-const detail = [];
-for (const file of files) {
-  let exports;
-  try {
-    exports = extractExports(readFileSync(file.full, 'utf8'));
-  } catch {
-    continue;
-  }
-  const undocumented = exports.filter((e) => !e.desc && e.name !== 'default');
-  if (undocumented.length === 0) continue;
-  missing += undocumented.length;
-  detail.push({ rel: file.rel, names: undocumented.map((e) => e.name) });
-}
-
-if (missing === 0) {
-  console.log(`[ok] Docs check passed (${files.length} file(s), every export documented).`);
-  process.exit(0);
-}
-
-console.log(`${missing} undocumented export(s) in ${detail.length} file(s):`);
-for (const d of detail.slice(0, 20)) {
-  console.log(`  ${d.rel}: ${d.names.join(', ')}`);
-}
-if (detail.length > 20) console.log(`  ... and ${detail.length - 20} more file(s)`);
-
-console.error(
-  '\n[x] Docs check FAILED.\n' +
-  '    Fix: add a one-line "/** When to use ... */" JSDoc above each export —\n' +
-  '    this is what feeds docs/COMPONENT_INDEX.md, the inventory the\n' +
-  '    reuse-before-create pre-flight depends on. Do NOT delete the check or\n' +
-  '    leave the doc as a bare restatement of the name.'
-);
-process.exit(args.reportOnly ? 0 : 1);
+#!/usr/bin/env node
+/**
+ * check-docs.mjs
+ *
+ * Documentation gate for shared exports. Fails (exit 1) when exported
+ * declarations in the checked files lack a one-line `/** When to use ... *\/`
+ * JSDoc above them. Keeps docs/COMPONENT_INDEX.md (generated from the same
+ * JSDoc) a maintained, trustworthy inventory instead of a stale artifact.
+ *
+ * Zero dependencies.
+ *
+ * Usage:
+ *   node scripts/anti-slop/check-docs.mjs [paths...] [--src src] [--report-only]
+ *
+ * With no path arguments it scans --src (default `src`). With path arguments
+ * it checks exactly those files — used by git hooks to check only staged
+ * files, so legacy undocumented code never blocks commits.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { extractExports } from './lib.mjs';
+import { loadConfig, gateArgs, collectPathFiles, resolveScanTarget, applyIgnorePaths } from './cli.mjs';
+import { baselineGate } from './baseline.mjs';
+
+// Defaults < anti-slop.config.json < CLI flags.
+const cfgDocs = loadConfig().docs ?? {};
+const { args, positionals } = gateArgs({
+  argv: process.argv.slice(2),
+  usage: 'Usage: node check-docs.mjs [paths...] [--src src] [--report-only] [--baseline file] [--update-baseline]\n' +
+         'Config: anti-slop.config.json "docs" section (src, ignorePaths, ignoreExports).\n' +
+         'With path arguments, checks exactly those files (git-hook staged mode).\n' +
+         'With a baseline file (default anti-slop.baseline.json) the gate fails only on NEW undocumented exports.',
+  spec: { '--src': 'string', '--report-only': 'flag', '--baseline': 'string', '--update-baseline': 'flag' },
+  defaults: { src: cfgDocs.src ?? 'src' },
+  allowPositionals: true,
+});
+
+// Framework-owned exports that are configuration, not shared surface.
+// Defaulted on when a Next.js config is present (segment config exports).
+const NEXTJS_EXPORTS = [
+  'metadata', 'generateMetadata', 'viewport', 'generateViewport', 'dynamic',
+  'revalidate', 'runtime', 'dynamicParams', 'fetchCache', 'maxDuration',
+  'preferredRegion', 'generateStaticParams', 'generateImageMetadata',
+];
+const hasNextConfig = existsSync(path.join(process.cwd(), 'next.config.js')) ||
+  existsSync(path.join(process.cwd(), 'next.config.mjs')) ||
+  existsSync(path.join(process.cwd(), 'next.config.ts'));
+const ignoreExports = Array.isArray(cfgDocs.ignoreExports)
+  ? cfgDocs.ignoreExports
+  : (hasNextConfig ? NEXTJS_EXPORTS : []);
+const ignorePaths = Array.isArray(cfgDocs.ignorePaths) ? cfgDocs.ignorePaths : [];
+
+const allFiles = positionals.length > 0 ? collectPathFiles(positionals) : resolveScanTarget(args.src);
+// ignorePaths applies in both modes (per-file/staged and whole-tree), so the
+// hook never rejects files the config says to ignore.
+const files = applyIgnorePaths(allFiles, ignorePaths, { label: 'docs.ignorePaths', src: args.src });
+
+let missing = 0;
+const detail = [];
+const perFileDocs = {};
+for (const file of files) {
+  let exports;
+  try {
+    exports = extractExports(readFileSync(file.full, 'utf8'));
+  } catch {
+    continue;
+  }
+  // Default exports are entry points (route files, pages) consumed by the
+  // framework, not shared surface; exempt them the way the index count does.
+  const undocumented = exports.filter(
+    (e) => !e.desc && !e.isDefault && !ignoreExports.includes(e.name),
+  );
+  if (undocumented.length === 0) continue;
+  perFileDocs[file.rel] = undocumented.length;
+  missing += undocumented.length;
+  detail.push({ rel: file.rel, names: undocumented.map((e) => e.name) });
+}
+
+// --- baseline (ratchet) mode ---------------------------------------------------
+const decision = baselineGate({
+  args,
+  section: 'docs',
+  current: perFileDocs,
+  unit: 'undocumented export(s)',
+  fixLine: 'Fix: add the one-line "/** When to use ... */" JSDoc — it feeds the component index.',
+});
+if (decision === 'ok') process.exit(0);
+if (decision === 'fail') process.exit(args.reportOnly ? 0 : 1);
+
+if (missing === 0) {
+  console.log(`[ok] Docs check passed (${files.length} file(s), every export documented).`);
+  process.exit(0);
+}
+
+console.log(`${missing} undocumented export(s) in ${detail.length} file(s):`);
+for (const d of detail.slice(0, 20)) {
+  console.log(`  ${d.rel}: ${d.names.join(', ')}`);
+}
+if (detail.length > 20) console.log(`  ... and ${detail.length - 20} more file(s)`);
+
+console.error(
+  '\n[x] Docs check FAILED.\n' +
+  '    Fix: add a one-line "/** When to use ... */" JSDoc above each export —\n' +
+  '    this is what feeds docs/COMPONENT_INDEX.md, the inventory the\n' +
+  '    reuse-before-create pre-flight depends on. Do NOT delete the check or\n' +
+  '    leave the doc as a bare restatement of the name.'
+);
+process.exit(args.reportOnly ? 0 : 1);

package/scripts/anti-slop/check-duplicates.mjs

@@ -20,30 +20,30 @@
  *   threshold = max allowed duplicated-lines percent; 0 disables failing.
  */
 
-import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
-import path from 'node:path';
+import { readFileSync } from 'node:fs';
 import {
-  walk, stripNoise, tokenize, lineOf,
+  stripNoise, tokenize,
 } from './lib.mjs';
-import { loadConfig, matchesAnyGlob, bootstrapGate, resolveScanTarget } from './cli.mjs';
+import {
+  loadConfig, matchesAnyGlob, gateArgs, resolveScanTarget,
+} from './cli.mjs';
+import { baselineGate } from './baseline.mjs';
 
 // --- args -------------------------------------------------------------------
 // Defaults < anti-slop.config.json < CLI flags.
 const cfgDups = (loadConfig().duplicates ?? {});
-const { args, positionals } = bootstrapGate(process.argv.slice(2), {
-  usage: 'Usage: node check-duplicates.mjs [--src src] [--min-tokens 50] [--threshold 3]\n' +
-         'Config: anti-slop.config.json "duplicates" section (src, minTokens, threshold, ignore globs).',
-  spec: { '--src': 'string', '--min-tokens': 'number', '--threshold': 'number' },
+const { args } = gateArgs({
+  argv: process.argv.slice(2),
+  usage: 'Usage: node check-duplicates.mjs [--src src] [--min-tokens 50] [--threshold 3] [--baseline file] [--update-baseline] [--summary]\n' +
+         'Config: anti-slop.config.json "duplicates" section (src, minTokens, threshold, ignore globs).\n' +
+         'With a baseline file (default anti-slop.baseline.json) the gate fails only on NEW clones.',
+  spec: { '--src': 'string', '--min-tokens': 'number', '--threshold': 'number', '--baseline': 'string', '--update-baseline': 'flag', '--summary': 'flag' },
   defaults: {
     src: cfgDups.src ?? 'src',
     minTokens: cfgDups.minTokens ?? 50,
     threshold: cfgDups.threshold ?? 3,
   },
 });
-if (positionals.length > 0) {
-  console.error(`Unexpected arguments: ${positionals.join(' ')} (this script takes flags only)`);
-  process.exit(1);
-}
 if (args.minTokens < 10) {
   console.error('min-tokens must be a number >= 10');
   process.exit(1);
@@ -132,7 +132,16 @@ for (const c of clones) {
   });
 }
 
-for (const r of cloneRegions) {
+// Same-file pairs whose line ranges overlap are the sliding window matching
+// itself shifted within one line — not clones, and they inflate both the
+// region list and the per-file ranking. Keep disjoint same-file pairs and all
+// cross-file pairs.
+const regions = cloneRegions.filter((r) => {
+  if (r.aFile !== r.bFile) return true;
+  return r.aLine > r.bEndLine || r.bLine > r.aEndLine;
+});
+
+for (const r of regions) {
   for (const [rel, s, e] of [[r.aFile, r.aLine, r.aEndLine], [r.bFile, r.bLine, r.bEndLine]]) {
     let set = dupLines.get(rel);
     if (!set) { set = new Set(); dupLines.set(rel, set); }
@@ -151,14 +160,14 @@ const pct = totalAll > 0 ? (totalDup / totalAll) * 100 : 0;
 // --- report -------------------------------------------------------------------
 console.log(`Checked ${files.length} files (${totalAll} lines), min-tokens=${K}, threshold=${args.threshold}%`);
 
-if (cloneRegions.length === 0) {
+if (regions.length === 0) {
   console.log('[ok] No duplicates found.');
   process.exit(0);
 }
 
-const MAX_REPORT = 40;
-console.log(`Found ${cloneRegions.length} clone region(s). Showing up to ${MAX_REPORT}:\n`);
-for (const r of cloneRegions.slice(0, MAX_REPORT)) {
+const MAX_REPORT = args.summary ? 3 : 40;
+console.log(`Found ${regions.length} clone region(s). Showing up to ${MAX_REPORT}:\n`);
+for (const r of regions.slice(0, MAX_REPORT)) {
   console.log(`  ${r.aFile}:${r.aLine}-${r.aEndLine}  <->  ${r.bFile}:${r.bLine}-${r.bEndLine}  (~${r.tokens} tokens)`);
 }
 
@@ -166,16 +175,32 @@ const worst = [...dupLines.entries()]
   .map(([rel, set]) => ({ rel, dup: set.size, total: totalLines.get(rel) }))
   .filter((f) => f.dup > 0)
   .sort((a, b) => b.dup / b.total - a.dup / a.total)
-  .slice(0, 5);
+  .slice(0, args.summary ? 3 : 5);
 console.log('\nMost duplicated files:');
 for (const w of worst) console.log(`  ${w.rel}: ${w.dup}/${w.total} lines (${((w.dup / w.total) * 100).toFixed(1)}%)`);
 console.log(`\nTotal duplicated lines: ${totalDup}/${totalAll} (${pct.toFixed(1)}%)`);
 
+// --- baseline (ratchet) mode ---------------------------------------------------
+const perFileDup = {};
+for (const [rel, set] of dupLines) if (set.size > 0) perFileDup[rel] = set.size;
+const decision = baselineGate({
+  args,
+  section: 'duplicates',
+  current: perFileDup,
+  extra: { totalDuplicatedLines: totalDup },
+  unit: 'duplicated line(s)',
+  fixLine: 'Fix: extract into existing shared modules (see the reuse-before-create skill).',
+});
+if (decision === 'ok') process.exit(0);
+if (decision === 'fail') process.exit(1);
+
 if (args.threshold > 0 && pct > args.threshold) {
   console.error(
     `\n[x] Duplicate-code check FAILED (${pct.toFixed(1)}% > ${args.threshold}%).\n` +
     '    Fix: extract duplicates into existing shared modules (see the reuse-before-create skill).\n' +
-    '    Do NOT weaken the threshold or add ignore comments to pass.'
+    '    Do NOT weaken the threshold or add ignore comments to pass.\n' +
+    '    Adopting a repo with legacy duplication? Snapshot it once:\n' +
+    `    node scripts/anti-slop/check-duplicates.mjs --update-baseline — the gate then fails only on NEW clones.`
   );
   process.exit(1);
 }

package/scripts/anti-slop/check-imports.mjs

@@ -22,8 +22,11 @@
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { walk, stripComments } from './lib.mjs';
-import { loadConfig, bootstrapGate, resolveScanTarget, matchesAnyGlob } from './cli.mjs';
+import { stripComments } from './lib.mjs';
+import {
+  loadConfig, gateArgs, resolveScanTarget, matchesAnyGlob,
+} from './cli.mjs';
+import { loadBaseline, saveBaseline, compareSets, BASELINE_FILE } from './baseline.mjs';
 
 // --- parsing ------------------------------------------------------------------
 
@@ -146,36 +149,33 @@ export function findCycles(graph) {
 const isMain =
   process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
 
-if (isMain) {
-  const cfgImports = loadConfig().imports ?? {};
-  const { args, positionals } = bootstrapGate(process.argv.slice(2), {
-    usage: 'Usage: node check-imports.mjs [--src src] [--report-only]\n' +
-      'Config: anti-slop.config.json "imports" section (src, deny: [{from, forbid}]).',
-    spec: { '--src': 'string', '--report-only': 'flag' },
-    defaults: { src: cfgImports.src ?? 'src' },
-  });
-  if (positionals.length > 0) {
-    console.error(`Unexpected arguments: ${positionals.join(' ')} (this script takes flags only)`);
-    process.exit(1);
-  }
-
-  const src = path.resolve(args.src);
-  if (!existsSync(src) || !statSync(src).isDirectory()) {
-    console.error(`Source directory not found: ${src}`);
-    process.exit(1);
-  }
-  const files = resolveScanTarget(args.src);
-  const graph = buildImportGraph(files, src);
-  const deny = Array.isArray(cfgImports.deny) ? cfgImports.deny : [];
-
+/** Evaluate cycles + deny rules against the graph, printing findings.
+ * Returns the violation count. Deny-rule violations are never baselined:
+ * rules are declared deliberately, so violating one is new debt by definition.
+ */
+function evaluateBoundaries(graph, cycles, deny, baseline) {
   let violations = 0;
+  const cycleKeys = cycles.map((chain) => [...chain.slice(0, -1)].sort().join('~'));
 
-  const cycles = findCycles(graph);
   if (cycles.length > 0) {
-    console.log(`Circular dependencies (${cycles.length}):`);
-    for (const chain of cycles.slice(0, 20)) {
-      console.log(`  ${chain.join(' -> ')}`);
-      violations++;
+    if (baseline?.imports) {
+      const { added } = compareSets(cycleKeys, baseline.imports.cycles);
+      if (added.length === 0) {
+        console.log(`[ok] No NEW cycles (${cycles.length} baselined cycle(s) remain; ${graph.size} files).`);
+      } else {
+        console.log(`NEW circular dependencies (${added.length}):`);
+        for (const key of added.slice(0, 20)) {
+          const chain = cycles.find((c) => [...c.slice(0, -1)].sort().join('~') === key);
+          console.log(`  ${chain ? chain.join(' -> ') : key}`);
+        }
+        violations += added.length;
+      }
+    } else {
+      console.log(`Circular dependencies (${cycles.length}):`);
+      for (const chain of cycles.slice(0, 20)) {
+        console.log(`  ${chain.join(' -> ')}`);
+        violations++;
+      }
     }
   }
 
@@ -194,9 +194,49 @@ if (isMain) {
       }
     }
   }
+  return violations;
+}
+
+function main() {
+  const cfgImports = loadConfig().imports ?? {};
+  const { args } = gateArgs({
+    argv: process.argv.slice(2),
+    usage: 'Usage: node check-imports.mjs [--src src] [--report-only] [--baseline file] [--update-baseline]\n' +
+      'Config: anti-slop.config.json "imports" section (src, deny: [{from, forbid}]).\n' +
+      'With a baseline file (default anti-slop.baseline.json) the gate fails only on NEW cycles.',
+    spec: { '--src': 'string', '--report-only': 'flag', '--baseline': 'string', '--update-baseline': 'flag' },
+    defaults: { src: cfgImports.src ?? 'src' },
+  });
+
+  const src = path.resolve(args.src);
+  if (!existsSync(src) || !statSync(src).isDirectory()) {
+    console.error(`Source directory not found: ${src}`);
+    process.exit(1);
+  }
+  const files = resolveScanTarget(args.src);
+  const graph = buildImportGraph(files, src);
+  const deny = Array.isArray(cfgImports.deny) ? cfgImports.deny : [];
+
+  const cycles = findCycles(graph);
+  const cycleKeys = cycles.map((chain) => [...chain.slice(0, -1)].sort().join('~'));
+
+  if (args.updateBaseline) {
+    const file = args.baseline ?? BASELINE_FILE;
+    saveBaseline(file, { imports: { cycles: [...cycleKeys].sort() } });
+    console.log(`[ok] Baseline written to ${file} (${cycleKeys.length} cycle(s)).`);
+    console.log('    Commit it. The gate now fails only on NEW cycles; shrink the baseline as you break them.');
+    process.exit(0);
+  }
+
+  const baseline = loadBaseline(args.baseline);
+  const violations = evaluateBoundaries(graph, cycles, deny, baseline);
 
   if (violations === 0) {
-    console.log(`[ok] Import-boundary check passed (${graph.size} files, no cycles, ${deny.length} layer rule(s)).`);
+    if (deny.length === 0) {
+      console.log(`[ok] No cycles (${graph.size} files). Cycles-only gate: no imports.deny rules configured — declare some (see README "Tuning per repo") to enforce layer direction.`);
+    } else {
+      console.log(`[ok] Import-boundary check passed (${graph.size} files, no cycles, ${deny.length} layer rule(s)).`);
+    }
     process.exit(0);
   }
 
@@ -207,3 +247,5 @@ if (isMain) {
   );
   process.exit(args.reportOnly ? 0 : 1);
 }
+
+if (isMain) main();