opencode-anti-slop 0.0.0-stage → 0.1.4

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

@@ -0,0 +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 { 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

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * check-duplicates.mjs
+ *
+ * Built-in copy/paste detector for JS/TS/React code. Fails (exit 1) when the
+ * percentage of duplicated lines across the source tree exceeds `threshold`.
+ * Used as a pre-completion / pre-commit gate by the `verify-clean-code` skill.
+ *
+ * Zero dependencies. Why not jscpd: verified in testing that jscpd (v3 and v4
+ * via npx) can analyze 0 files on some Windows setups; a built-in token-stream
+ * detector is deterministic and needs no downloads.
+ *
+ * Method: strip comments, tokenize, compare sliding windows of `min-tokens`
+ * consecutive tokens between files (and within a file). Windows are
+ * normalized: string/number literals are abstracted so clones with changed
+ * text/numbers are still caught.
+ *
+ * Usage:
+ *   node scripts/anti-slop/check-duplicates.mjs [--src src] [--min-tokens 50] [--threshold 3]
+ *   threshold = max allowed duplicated-lines percent; 0 disables failing.
+ */
+
+import { readFileSync } from 'node:fs';
+import {
+  stripNoise, tokenize,
+} from './lib.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 } = 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 (args.minTokens < 10) {
+  console.error('min-tokens must be a number >= 10');
+  process.exit(1);
+}
+const IGNORE_GLOBS = Array.isArray(cfgDups.ignore) ? cfgDups.ignore : [];
+
+// --- detect -------------------------------------------------------------------
+const allFiles = resolveScanTarget(args.src);
+const files = allFiles.filter((f) => !matchesAnyGlob(f.rel, IGNORE_GLOBS));
+const excludedCount = allFiles.length - files.length;
+if (IGNORE_GLOBS.length > 0) {
+  console.log(`Ignoring paths relative to '${args.src}/': ${IGNORE_GLOBS.join(', ')} (${excludedCount} file(s) excluded).`);
+}
+const K = args.minTokens;
+
+// Map: window key -> [{ file, idx }]
+const windows = new Map();
+
+for (const file of files) {
+  const stripped = stripNoise(readFileSync(file.full, 'utf8'));
+  file.tokens = tokenize(stripped);
+  file.totalLines = stripped.split('\n').length;
+  if (file.tokens.length < K) continue;
+  for (let i = 0; i + K <= file.tokens.length; i++) {
+    const key = file.tokens.slice(i, i + K).map((x) => x.t).join('\u0000');
+    let list = windows.get(key);
+    if (!list) { list = []; windows.set(key, list); }
+    list.push({ file, idx: i });
+  }
+}
+
+// Merge overlapping window hits into clone regions (per file pair).
+const clones = []; // { aFile, bFile, aStart, aEnd, bStart, bEnd, tokens }
+const seenPairs = new Set();
+
+for (const list of windows.values()) {
+  if (list.length < 2) continue;
+  for (let x = 0; x < list.length; x++) {
+    for (let y = x + 1; y < list.length; y++) {
+      const A = list[x];
+      const B = list[y];
+      if (A.file === B.file && Math.abs(A.idx - B.idx) < K) continue; // overlapping self-match
+      const pairKey = `${A.file.rel}|${A.idx}|${B.file.rel}|${B.idx}`;
+      // skip if this (A,B) pair region is already covered by a longer clone
+      const idPair = `${A.file.rel}~${B.file.rel}`;
+      let covered = false;
+      for (const c of clones) {
+        if (c.aFile !== A.file.rel || c.bFile !== B.file.rel) continue;
+        if (A.idx >= c.aStart - K && A.idx <= c.aEnd + K && B.idx >= c.bStart - K && B.idx <= c.bEnd + K) {
+          // extend if adjacent
+          if (A.idx <= c.aEnd + 1 || B.idx <= c.bEnd + 1) {
+            c.aEnd = Math.max(c.aEnd, A.idx + K - 1);
+            c.bEnd = Math.max(c.bEnd, B.idx + K - 1);
+            c.tokens = Math.max(c.tokens, c.aEnd - c.aStart + 1);
+            covered = true;
+            break;
+          }
+        }
+      }
+      if (covered) continue;
+      if (seenPairs.has(idPair) && clones.length > 200) continue; // hard cap on pathological input
+      clones.push({
+        aFile: A.file.rel, bFile: B.file.rel,
+        aStart: A.idx, aEnd: A.idx + K - 1,
+        bStart: B.idx, bEnd: B.idx + K - 1,
+        tokens: K,
+      });
+      seenPairs.add(idPair);
+    }
+  }
+}
+
+// --- compute duplicated lines per file ---------------------------------------
+const dupLines = new Map(); // rel -> Set<line>
+const totalLines = new Map();
+for (const f of files) totalLines.set(f.rel, f.totalLines);
+
+const cloneRegions = [];
+for (const c of clones) {
+  const aTok = files.find((f) => f.rel === c.aFile).tokens;
+  const bTok = files.find((f) => f.rel === c.bFile).tokens;
+  cloneRegions.push({
+    aFile: c.aFile, aLine: aTok[c.aStart]?.line ?? 1, aEndLine: aTok[Math.min(c.aEnd, aTok.length - 1)]?.line ?? aTok.length,
+    bFile: c.bFile, bLine: bTok[c.bStart]?.line ?? 1, bEndLine: bTok[Math.min(c.bEnd, bTok.length - 1)]?.line ?? bTok.length,
+    tokens: c.tokens,
+  });
+}
+
+// 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); }
+    for (let l = s; l <= e; l++) set.add(l);
+  }
+}
+
+let totalDup = 0;
+let totalAll = 0;
+for (const f of files) {
+  totalAll += f.totalLines;
+  totalDup += dupLines.get(f.rel)?.size ?? 0;
+}
+const pct = totalAll > 0 ? (totalDup / totalAll) * 100 : 0;
+
+// --- report -------------------------------------------------------------------
+console.log(`Checked ${files.length} files (${totalAll} lines), min-tokens=${K}, threshold=${args.threshold}%`);
+
+if (regions.length === 0) {
+  console.log('[ok] No duplicates found.');
+  process.exit(0);
+}
+
+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)`);
+}
+
+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, 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.\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);
+}
+console.log('[ok] Duplicate-code check passed.');