opencode-anti-slop 0.0.0-stage → 0.1.4

package/scripts/anti-slop/cli.mjs

@@ -0,0 +1,259 @@
+/**
+ * cli.mjs — shared CLI/config plumbing for the anti-slop gate scripts.
+ *
+ * Zero dependencies (Node >= 18, ESM). Source-scanning helpers live in lib.mjs;
+ * this module handles flag parsing, per-repo config loading, and path-to-file
+ * resolution. Keep it free of scanning logic.
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { walk, SOURCE_EXT, IGNORE_FILE } from './lib.mjs';
+
+// --- CLI parsing ---------------------------------------------------------------
+
+/**
+ * Parse CLI flags uniformly across gate scripts.
+ *
+ * spec maps flag -> type: 'string' | 'number' | 'flag' (boolean, no value).
+ * argv starts after the script path. Unknown flags and bare positional words
+ * land in `positionals`; each script decides whether positionals are an error
+ * or file paths.
+ *
+ * Returns { values: Record<flag, string|number|true>, positionals: string[] }.
+ */
+export function parseFlags(argv, spec) {
+  const values = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const s = argv[i];
+    const type = spec[s];
+    if (!type) {
+      positionals.push(s);
+      continue;
+    }
+    if (type === 'flag') {
+      values[s] = true;
+      continue;
+    }
+    const raw = argv[++i];
+    if (raw === undefined) {
+      throw new Error(`Missing value for ${s}`);
+    }
+    const v = type === 'number' ? Number(raw) : raw;
+    if (type === 'number' && Number.isNaN(v)) {
+      throw new Error(`${s} expects a number, got: ${raw}`);
+    }
+    values[s] = v;
+  }
+  return { values, positionals };
+}
+
+/**
+ * Common gate bootstrap: handle -h/--help with `usage`, parse flags per `spec`,
+ * and merge flag values over `defaults` (config-supplied). Flag names are
+ * camelCased into arg keys: --min-tokens -> args.minTokens, --report-only ->
+ * args.reportOnly (flags become true/false).
+ *
+ * Returns { args, positionals }. Never returns on -h (exits 0) or a parse
+ * error (exits 1).
+ */
+export function bootstrapGate(argv, { usage, spec, defaults }) {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    console.log(usage);
+    process.exit(0);
+  }
+  let parsed;
+  try {
+    parsed = parseFlags(argv, spec);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+  const args = { ...defaults };
+  for (const [flag, type] of Object.entries(spec)) {
+    const key = flag.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    args[key] = type === 'flag'
+      ? parsed.values[flag] === true
+      : (parsed.values[flag] ?? defaults[key]);
+  }
+  return { args, positionals: parsed.positionals };
+}
+
+/**
+ * Resolve explicit path arguments (files or directories) into { full, rel }
+ * source entries, applying the same filters as walk(). Exits 1 on a missing
+ * path. Used by gate scripts in git-hook staged-file mode.
+ */
+export function collectPathFiles(paths) {
+  const files = [];
+  for (const p of paths) {
+    const abs = path.resolve(p);
+    if (!existsSync(abs)) {
+      console.error(`Path not found: ${p}`);
+      process.exit(1);
+    }
+    if (statSync(abs).isDirectory()) {
+      files.push(...walk(abs, abs));
+    } else if (SOURCE_EXT.has(path.extname(abs)) && !IGNORE_FILE.test(abs)) {
+      files.push({ full: abs, rel: path.relative(process.cwd(), abs).split(path.sep).join('/') });
+    }
+  }
+  return files;
+}
+
+/**
+ * Resolve the scan root given to a gate (--src): accepts a directory (walked)
+ * or a single file. Exits 1 when the path does not exist.
+ */
+export function resolveScanTarget(src) {
+  const abs = path.resolve(src);
+  if (!existsSync(abs)) {
+    console.error(`Source directory not found: ${abs}`);
+    process.exit(1);
+  }
+  if (statSync(abs).isFile()) {
+    return collectPathFiles([src]);
+  }
+  return walk(abs, abs);
+}
+
+/**
+ * bootstrapGate plus the standard positional validation most gates share.
+ * Pass allowPositionals: true for gates that accept file-path arguments
+ * (git-hook staged mode).
+ */
+export function gateArgs({ argv, usage, spec, defaults, allowPositionals = false }) {
+  const { args, positionals } = bootstrapGate(argv, { usage, spec, defaults });
+  if (!allowPositionals && positionals.length > 0) {
+    console.error(`Unexpected arguments: ${positionals.join(' ')} (this script takes flags only)`);
+    process.exit(1);
+  }
+  return { args, positionals };
+}
+
+// --- per-repo config ----------------------------------------------------------
+
+/**
+ * Filter resolved files by a docs/duplicates-style ignore-path config:
+ * globs are matched against THREE path candidates so every mode and both
+ * glob conventions work — the provided rel, repo-relative, and (when `src`
+ * is given) scan-root-relative. Tree-wide walks produce scan-root-relative
+ * rels; git-hook staged mode produces repo-relative ones; configs may use
+ * either convention. Returns the kept files and prints an exclusion notice
+ * when any glob is configured and something matched.
+ */
+export function applyIgnorePaths(files, globs, { label = 'ignorePaths', src } = {}) {
+  if (!Array.isArray(globs) || globs.length === 0) return files;
+  const srcDir = src ? path.resolve(src) : null;
+  const kept = files.filter((f) => {
+    const repoRel = path.relative(process.cwd(), f.full).split(path.sep).join('/');
+    const scanRel = srcDir ? path.relative(srcDir, f.full).split(path.sep).join('/') : null;
+    const candidates = scanRel ? [f.rel, repoRel, scanRel] : [f.rel, repoRel];
+    return !candidates.some((p) => matchesAnyGlob(p, globs));
+  });
+  const excluded = files.length - kept.length;
+  if (excluded > 0) {
+    console.log(`Ignoring ${excluded} file(s) matching ${label} (${globs.join(', ')}).`);
+  }
+  return kept;
+}
+
+const KNOWN_SECTIONS = new Set(['duplicates', 'modularity', 'docs', 'imports', '$schema', '_comment']);
+
+/** Light validation: unknown keys and wrong types warn instead of silently
+ * disabling the tuning (a typo like "duplicate" would otherwise run the gates
+ * on defaults with no signal why). */
+function validateConfig(parsed) {
+  const warns = [];
+  for (const key of Object.keys(parsed)) {
+    if (!KNOWN_SECTIONS.has(key)) warns.push(`unknown key "${key}" (ignored)`);
+  }
+  const num = (section, key) => {
+    const v = parsed[section]?.[key];
+    if (v !== undefined && (typeof v !== 'number' || Number.isNaN(v))) warns.push(`${section}.${key} must be a number`);
+  };
+  const arr = (section, key) => {
+    const v = parsed[section]?.[key];
+    if (v !== undefined && !Array.isArray(v)) warns.push(`${section}.${key} must be an array of globs/names`);
+  };
+  num('duplicates', 'minTokens');
+  num('duplicates', 'threshold');
+  arr('duplicates', 'ignore');
+  num('modularity', 'maxFileLines');
+  num('modularity', 'maxFunctionLines');
+  num('modularity', 'maxClassMethods');
+  arr('modularity', 'ignorePaths');
+  arr('docs', 'ignorePaths');
+  arr('docs', 'ignoreExports');
+  if (parsed.imports?.deny !== undefined && !Array.isArray(parsed.imports.deny)) {
+    warns.push('imports.deny must be an array of { from, forbid } rules');
+  }
+  if (warns.length > 0) {
+    console.error(`[warn] anti-slop.config.json: ${warns.join('; ')}.`);
+  }
+}
+
+/**
+ * Reads `anti-slop.config.json` from process.cwd() (repo root), returning the
+ * parsed object or {} when absent (warn+{} when unparsable).
+ * Scripts merge: defaults < config file < CLI flags.
+ *
+ * Shape:
+ * {
+ *   "duplicates": { "src": "src", "minTokens": 50, "threshold": 3,
+ *                   "ignore": ["collections/**"] },
+ *   "modularity": { "src": "src", "maxFileLines": 300, "maxFunctionLines": 80,
+ *                   "maxClassMethods": 10 },
+ *   "docs":       { "src": "src", "ignorePaths": ["app/(payload)/**"],
+ *                   "ignoreExports": ["metadata", "dynamic"] },
+ *   "imports":    { "src": "src", "deny": [{ "from": "src/domain/**",
+ *                   "forbid": "src/infra/**" }] }
+ * }
+ *
+ * `ignore` (duplicates) and `ignorePaths` (docs) exclude framework-idiomatic
+ * declarative files whose repetition is shape, not logic.
+ */
+export function loadConfig() {
+  const file = path.join(process.cwd(), 'anti-slop.config.json');
+  if (!existsSync(file)) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (err) {
+    console.error(`[warn] Could not parse anti-slop.config.json (${err.message}); using defaults.`);
+    return {};
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    console.error('[warn] anti-slop.config.json is not an object; using defaults.');
+    return {};
+  }
+  validateConfig(parsed);
+  return parsed;
+}
+
+/** Convert a glob (`**`, `*`, `?`) into a RegExp tested against '/'-separated rel paths. */
+export function globToRegex(glob) {
+  let pattern = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        pattern += '[\\s\\S]*';
+        i++;
+      } else {
+        pattern += '[^/]*';
+      }
+    } else if (c === '?') {
+      pattern += '[^/]';
+    } else {
+      pattern += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`^${pattern}$`);
+}
+
+/** True when relPath matches any ignore glob. */
+export function matchesAnyGlob(relPath, globs) {
+  return globs.length > 0 && globs.some((g) => globToRegex(g).test(relPath));
+}

package/scripts/anti-slop/cli.test.mjs

@@ -0,0 +1,202 @@
+/**
+ * Unit tests for CLI/config plumbing (cli.mjs). Zero dependencies — runs with
+ * `node --test`. bootstrapGate's flag-to-key camelCasing and the
+ * defaults < config < flags merge are contract tests: the gates' hooks call
+ * the scripts bare, so the config file must govern them without flags.
+ */
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import {
+  bootstrapGate, globToRegex, matchesAnyGlob, parseFlags, gateArgs, applyIgnorePaths,
+} from './cli.mjs';
+import {
+  compareCounts, compareKindCounts, compareSets, loadBaseline, saveBaseline,
+} from './baseline.mjs';
+
+// --- parseFlags ----------------------------------------------------------------
+
+test('parseFlags: string, number, and flag types', () => {
+  const { values, positionals } = parseFlags(
+    ['--src', 'lib', '--min-tokens', '30', '--report-only'],
+    { '--src': 'string', '--min-tokens': 'number', '--report-only': 'flag' },
+  );
+  assert.equal(values['--src'], 'lib');
+  assert.equal(values['--min-tokens'], 30);
+  assert.equal(values['--report-only'], true);
+  assert.deepEqual(positionals, []);
+});
+
+test('parseFlags: bare words land in positionals', () => {
+  const { values, positionals } = parseFlags(['src/a.ts', 'src/b.ts'], {});
+  assert.deepEqual(values, {});
+  assert.deepEqual(positionals, ['src/a.ts', 'src/b.ts']);
+});
+
+test('parseFlags: missing value throws', () => {
+  assert.throws(() => parseFlags(['--src'], { '--src': 'string' }), /Missing value/);
+});
+
+test('parseFlags: non-numeric number throws', () => {
+  assert.throws(
+    () => parseFlags(['--max-file-lines', 'abc'], { '--max-file-lines': 'number' }),
+    /expects a number/,
+  );
+});
+
+// --- bootstrapGate ----------------------------------------------------------------
+
+const SPEC = {
+  '--src': 'string', '--min-tokens': 'number', '--threshold': 'number',
+  '--report-only': 'flag',
+};
+
+test('bootstrapGate: flags override defaults, keys camelCased', () => {
+  const { args, positionals } = bootstrapGate(
+    ['--min-tokens', '20'],
+    {
+      usage: 'usage',
+      spec: SPEC,
+      defaults: { src: 'src', minTokens: 50, threshold: 3, reportOnly: false },
+    },
+  );
+  assert.equal(args.src, 'src');
+  assert.equal(args.minTokens, 20);
+  assert.equal(args.threshold, 3);
+  assert.equal(args.reportOnly, false);
+  assert.deepEqual(positionals, []);
+});
+
+test('bootstrapGate: config defaults flow through unchanged', () => {
+  const { args } = bootstrapGate([], {
+    usage: 'usage',
+    spec: SPEC,
+    defaults: { src: 'app', minTokens: 80, threshold: 5 },
+  });
+  assert.deepEqual(args, { src: 'app', minTokens: 80, threshold: 5, reportOnly: false });
+});
+
+test('bootstrapGate: --report-only becomes boolean true', () => {
+  const { args } = bootstrapGate(['--report-only'], {
+    usage: 'usage', spec: SPEC, defaults: { src: 'src', reportOnly: false },
+  });
+  assert.equal(args.reportOnly, true);
+});
+
+// --- glob matching -----------------------------------------------------------------
+
+test('globToRegex: ** crosses directories, * stays within one', () => {
+  assert.ok(globToRegex('collections/**').test('collections/AccessGrants.ts'));
+  assert.ok(globToRegex('collections/**').test('collections/nested/Clients.ts'));
+  assert.ok(!globToRegex('collections/**').test('src/collections/Clients.ts'));
+  assert.ok(globToRegex('app/(payload)/**').test('app/(payload)/admin/page.tsx'));
+  assert.ok(globToRegex('lib/*.ts').test('lib/date.ts'));
+  assert.ok(!globToRegex('lib/*.ts').test('lib/deep/date.ts'));
+  assert.ok(globToRegex('use?.ts').test('useA.ts'));
+  assert.ok(!globToRegex('use?.ts').test('useAB.ts'));
+  assert.ok(globToRegex('a.b.ts').test('a.b.ts'));
+  assert.ok(!globToRegex('a.b.ts').test('axbts'));
+});
+
+test('matchesAnyGlob: empty list never matches', () => {
+  assert.equal(matchesAnyGlob('anything.ts', []), false);
+});
+
+test('matchesAnyGlob: any of several globs', () => {
+  assert.ok(matchesAnyGlob('x/y.ts', ['nothing/**', 'x/**']));
+});
+
+// --- applyIgnorePaths -----------------------------------------------------------
+
+test('applyIgnorePaths: scan-root-relative globs match repo-relative staged files', async () => {
+  // Regression for #18: git-hook staged mode passes repo-relative paths
+  // (src/app/...); a config glob written scan-root-relative (app/...) must
+  // still match, because tree-wide mode matches it that way.
+  const dir = mkdtempSync(path.join(tmpdir(), 'antislop-ignore-'));
+  try {
+    const repo = path.join(dir, 'repo');
+    const nested = path.join(repo, 'src', 'app', '(payload)');
+    mkdirSync(nested, { recursive: true });
+    const full = path.join(nested, 'importMap.js');
+    writeFileSync(full, 'export default 1;');
+    const files = [{ full, rel: 'src/app/payload/importMap.js' }];
+    const kept = applyIgnorePaths(files, ['app/(payload)/**'], { src: path.join(repo, 'src') });
+    assert.equal(kept.length, 0);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('applyIgnorePaths: repo-relative globs match scan-root-relative rels', () => {
+  // full path under the repo's src/, rel produced by a tree-wide walk
+  const files = [{ full: 'src/collections/Users.ts', rel: 'collections/Users.ts' }];
+  const kept = applyIgnorePaths(files, ['src/collections/**'], { src: 'src' });
+  assert.equal(kept.length, 0);
+});
+
+test('applyIgnorePaths: no globs keeps everything silently', () => {
+  const files = [{ full: 'a.ts', rel: 'a.ts' }];
+  assert.equal(applyIgnorePaths(files, []).length, 1);
+});
+
+// --- baseline ratchet ------------------------------------------------------------
+
+test('compareCounts: unseen file with duplication is new debt', () => {
+  const { newDebt, improved } = compareCounts({ 'a.ts': 5 }, { 'b.ts': 3 });
+  assert.deepEqual(newDebt, [{ rel: 'a.ts', count: 5, accepted: 0 }]);
+  assert.deepEqual(improved, []);
+});
+
+test('compareCounts: growth beyond accepted is new; shrink is improvement', () => {
+  const { newDebt, improved } = compareCounts(
+    { 'a.ts': 8, 'b.ts': 1 },
+    { 'a.ts': 5, 'b.ts': 3 },
+  );
+  assert.deepEqual(newDebt, [{ rel: 'a.ts', count: 8, accepted: 5 }]);
+  assert.deepEqual(improved, [{ rel: 'b.ts', count: 1, accepted: 3 }]);
+});
+
+test('compareCounts: equal counts are neither', () => {
+  const { newDebt, improved } = compareCounts({ 'a.ts': 5 }, { 'a.ts': 5 });
+  assert.deepEqual(newDebt, []);
+  assert.deepEqual(improved, []);
+});
+
+test('compareKindCounts: new kind on a baselined file is new debt', () => {
+  const { newDebt } = compareKindCounts(
+    { 'big.ts': { file: 1, function: 2 } },
+    { 'big.ts': { file: 1, function: 0 } },
+  );
+  assert.deepEqual(newDebt, [{ rel: 'big.ts', kind: 'function', count: 2, accepted: 0 }]);
+});
+
+test('compareKindCounts: unseen file with any violation is new debt', () => {
+  const { newDebt } = compareKindCounts({ 'new.ts': { file: 1 } }, {});
+  assert.deepEqual(newDebt, [{ rel: 'new.ts', kind: 'file', count: 1, accepted: 0 }]);
+});
+
+test('compareSets: added and removed', () => {
+  const { added, removed } = compareSets(['a~b', 'c~d'], ['a~b', 'e~f']);
+  assert.deepEqual(added, ['c~d']);
+  assert.deepEqual(removed, ['e~f']);
+});
+
+test('saveBaseline/loadBaseline: roundtrip with sorted keys', () => {
+  const dir = mkdtempSync(path.join(tmpdir(), 'antislop-baseline-'));
+  try {
+    const file = path.join(dir, 'baseline.json');
+    saveBaseline(file, { duplicates: { files: { 'b.ts': 2, 'a.ts': 1 }, totalDuplicatedLines: 3 } });
+    const loaded = loadBaseline(file);
+    assert.equal(loaded.duplicates.totalDuplicatedLines, 3);
+    assert.deepEqual(Object.keys(loaded.duplicates.files), ['a.ts', 'b.ts']);
+    const raw = readFileSync(file, 'utf8');
+    assert.ok(raw.includes('_comment'));
+    assert.ok(raw.includes('Ratchet baseline'));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/scripts/anti-slop/generate-component-index.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * generate-component-index.mjs
+ *
+ * Scans a source tree and (re)generates docs/COMPONENT_INDEX.md — the
+ * inventory that the `reuse-before-create` skill treats as the source of
+ * truth for existing layouts, components, hooks, and utilities.
+ *
+ * Zero dependencies (plain Node >= 18, ESM). Classification is heuristic
+ * (paths + export names + file extension); it is a discovery aid, not a parser.
+ *
+ * Usage:
+ *   node scripts/anti-slop/generate-component-index.mjs [--src src] [--out docs/COMPONENT_INDEX.md] [--root .]
+ *
+ * A "## Manual Notes" section at the end of an existing index is preserved.
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+} from 'node:fs';
+import path from 'node:path';
+import { walk, extractExports } from './lib.mjs';
+import { loadConfig, applyIgnorePaths } from './cli.mjs';
+
+// --- args -------------------------------------------------------------------
+function parseArgs(argv) {
+  const args = { src: 'src', out: 'docs/COMPONENT_INDEX.md', root: '.', check: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--src') args.src = argv[++i];
+    else if (a === '--out') args.out = argv[++i];
+    else if (a === '--root') args.root = argv[++i];
+    else if (a === '--check') args.check = true;
+    else if (a === '-h' || a === '--help') {
+      console.log('Usage: node generate-component-index.mjs [--src src] [--out docs/COMPONENT_INDEX.md] [--root .] [--check]');
+      console.log('  --check  compare against the file on disk; exit 1 when stale (CI mode, writes nothing)');
+      process.exit(0);
+    } else {
+      console.error(`Unknown argument: ${a}`);
+      process.exit(1);
+    }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv);
+
+const SRC_DIR = path.resolve(args.root, args.src);
+const OUT_FILE = path.resolve(args.root, args.out);
+
+if (!existsSync(SRC_DIR)) {
+  console.error(`Source directory not found: ${SRC_DIR}`);
+  process.exit(1);
+}
+
+// --- classification ---------------------------------------------------------
+function classify(relPath, exports) {
+  const base = path.basename(relPath);
+  const dir = path.dirname(relPath).toLowerCase();
+  const baseName = path.basename(base, path.extname(base));
+  const isTsx = /\.(tsx|jsx)$/.test(base);
+
+  const hasJsxLike = exports.length > 0 && isTsx;
+
+  if (/^use[A-Z0-9]/.test(baseName) || /(^|\/)hooks?\//.test(dir)) return 'Hook';
+  if (/(^|\/)layouts?(\/|$)/.test(dir) || /layout/i.test(baseName)) return 'Layout';
+  if (hasJsxLike && exports.some((e) => /^[A-Z]/.test(e.name))) return 'Component';
+  if (/(^|\/)(services?|adapters?)(\/|$)/.test(dir)) return 'Service';
+  if (/(^|\/)(utils?|lib|helpers?)(\/|$)/.test(dir)) return 'Util';
+  if (exports.some((e) => e.kind === 'type')) return 'Types';
+  return 'Module';
+}
+
+// --- build ------------------------------------------------------------------
+const files = walk(SRC_DIR, SRC_DIR);
+// The generator and the docs gate must agree on what exists: docs.ignorePaths
+// excludes framework-owned or declarative files from both the listing and the
+// undocumented count, so the two never report different totals.
+const ignorePaths = Array.isArray(loadConfig().docs?.ignorePaths)
+  ? loadConfig().docs.ignorePaths
+  : [];
+const filtered = applyIgnorePaths(files, ignorePaths, { label: 'docs.ignorePaths', src: args.src });
+const index = new Map(); // kind -> [{rel, name, kind, desc, lines}]
+let missingDocs = 0;
+
+for (const file of filtered) {
+  const source = readFileSync(file.full, 'utf8');
+  const exports = extractExports(source);
+  if (exports.length === 0) continue;
+  const kind = classify(file.rel, exports);
+  const lines = source.split('\n').length;
+  const list = index.get(kind) ?? [];
+  for (const exp of exports) {
+    // The docs gate exempts default exports (route entry points etc.); the
+    // generator's count must agree, or the two report different totals.
+    if (!exp.desc && exp.kind !== 'default') missingDocs++;
+    list.push({ rel: file.rel, name: exp.name, kind: exp.kind, desc: exp.desc, lines });
+  }
+  index.set(kind, list);
+}
+
+// --- preserve manual notes --------------------------------------------------
+let manualNotes = '';
+if (existsSync(OUT_FILE)) {
+  const existing = readFileSync(OUT_FILE, 'utf8');
+  const marker = existing.indexOf('## Manual Notes');
+  if (marker !== -1) manualNotes = existing.slice(marker);
+}
+
+// --- render -----------------------------------------------------------------
+const KIND_ORDER = ['Layout', 'Component', 'Hook', 'Service', 'Util', 'Types', 'Module'];
+// Categories already plural keep their name; everything else takes a plain 's'.
+const PLURAL = { Types: 'Types' };
+const heading = (kind) => PLURAL[kind] ?? `${kind}s`;
+const totalExports = KIND_ORDER.reduce((n, k) => n + (index.get(k)?.length ?? 0), 0);
+
+let md = `# Component Index\n\n`;
+md += `<!-- generated: run \`node scripts/anti-slop/generate-component-index.mjs\` to regenerate -->\n\n`;
+md += `Inventory of shared layouts, components, hooks, services, and utilities under \`${args.src}/\`. `;
+md += `${filtered.length} files, ${totalExports} exports.\n\n`;
+md += `> Rule of use: before creating any new component, hook, or utility, check this file first (see the \`reuse-before-create\` skill). When you add a shared abstraction, rerun the generator and fill in the "When to use" column.\n\n`;
+
+for (const kind of KIND_ORDER) {
+  const list = index.get(kind);
+  if (!list || list.length === 0) continue;
+  md += `## ${heading(kind)} (${list.length})\n\n`;
+  md += `| File | Export | When to use |\n|---|---|---|\n`;
+  for (const e of list) {
+    const doc = e.desc ? e.desc.replace(/\|/g, '\\|') : '';
+    md += `| \`${e.rel}\` | \`${e.name}\`${e.kind === 'type' ? ' *(type)*' : ''} | ${doc || '-'} |\n`;
+  }
+  md += `\n`;
+}
+
+md += manualNotes ? `${manualNotes.trimEnd()}\n` : `## Manual Notes\n\n(Add notes here; they are preserved when the index is regenerated.)\n`;
+md = md.replace(/\n+$/, '\n');
+
+if (args.check) {
+  if (!existsSync(OUT_FILE)) {
+    console.error(`[x] Index check FAILED: ${OUT_FILE} does not exist. Run the generator without --check and commit the result.`);
+    process.exit(1);
+  }
+  const onDisk = readFileSync(OUT_FILE, 'utf8').replace(/\n+$/, '\n');
+  if (onDisk === md) {
+    console.log(`[ok] Component index is up to date (${OUT_FILE}).`);
+    process.exit(0);
+  }
+  console.error(`[x] Index check FAILED: ${OUT_FILE} is stale. Run \`node scripts/anti-slop/generate-component-index.mjs\` and commit the result.`);
+  process.exit(1);
+}
+
+mkdirSync(path.dirname(OUT_FILE), { recursive: true });
+writeFileSync(OUT_FILE, md);
+
+console.log(`Wrote ${OUT_FILE}`);
+console.log(`  ${filtered.length} source files, ${totalExports} exports across ${KIND_ORDER.filter((k) => index.has(k)).length} categories.`);
+if (missingDocs > 0) {
+  console.log(`  [doc] ${missingDocs} export(s) have no JSDoc description. Shared components/hooks/utils must carry a one-line "/** When to use ... */" above the export.`);
+}