opencode-anti-slop 0.0.0-stage → 0.1.1

package/scripts/anti-slop/cli.mjs

@@ -0,0 +1,175 @@
+/**
+ * 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 { readFileSync, existsSync, 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);
+}
+
+// --- per-repo config ----------------------------------------------------------
+
+/**
+ * Reads `anti-slop.config.json` from process.cwd() (repo root), returning the
+ * parsed object or {} when absent/invalid (with a warning on invalid).
+ * 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" }
+ * }
+ *
+ * `ignore` (duplicates only) excludes framework-idiomatic declarative files
+ * (collection configs, generated tables) whose repetition is shape, not logic.
+ */
+export function loadConfig() {
+  const file = path.join(process.cwd(), 'anti-slop.config.json');
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch (err) {
+    console.error(`[warn] Could not parse anti-slop.config.json (${err.message}); using defaults.`);
+    return {};
+  }
+}
+
+/** 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,106 @@
+/**
+ * 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 { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { bootstrapGate, globToRegex, matchesAnyGlob, parseFlags } from './cli.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/**']));
+});

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

@@ -0,0 +1,133 @@
+#!/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 {
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+} from 'node:fs';
+import path from 'node:path';
+import { walk, extractExports } from './lib.mjs';
+
+// --- args -------------------------------------------------------------------
+function parseArgs(argv) {
+  const args = { src: 'src', out: 'docs/COMPONENT_INDEX.md', root: '.' };
+  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 === '-h' || a === '--help') {
+      console.log('Usage: node generate-component-index.mjs [--src src] [--out docs/COMPONENT_INDEX.md] [--root .]');
+      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);
+const index = new Map(); // kind -> [{rel, name, kind, desc, lines}]
+let missingDocs = 0;
+
+for (const file of files) {
+  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) {
+    if (!exp.desc) 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'];
+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 += `Generated ${new Date().toISOString().slice(0, 10)}, ${files.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 += `## ${kind}s (${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}\n` : `## Manual Notes\n\n(Add notes here; they are preserved when the index is regenerated.)\n`;
+
+mkdirSync(path.dirname(OUT_FILE), { recursive: true });
+writeFileSync(OUT_FILE, md);
+
+console.log(`Wrote ${OUT_FILE}`);
+console.log(`  ${files.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.`);
+}

package/scripts/anti-slop/install-hooks.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * install-hooks.mjs — wire the anti-slop gates into git hooks of a repo.
+ *
+ *   pre-commit : checks ONLY staged JS/TS files with check-modularity
+ *                (blocking) + reports duplicates (non-blocking). Fast, and
+ *                never blocked by legacy code.
+ *   pre-push   : full duplicates gate (blocking) + lint/typecheck/test via
+ *                `npm run <script> --if-present`.
+ *
+ * Run from the target repo root:  node scripts/anti-slop/install-hooks.mjs [--force]
+ * Existing hooks are never overwritten without --force.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+
+const force = process.argv.includes('--force');
+const preCommitOnly = process.argv.includes('--pre-commit-only');
+if (process.argv.includes('-h') || process.argv.includes('--help')) {
+  console.log('Usage: node scripts/anti-slop/install-hooks.mjs [--force] [--pre-commit-only]');
+  console.log('  --pre-commit-only: skip the pre-push gate. Use when legacy duplication or');
+  console.log('  size violations exist repo-wide — pre-push would block every push until');
+  console.log('  the cleanup lands. Install the full pair once the gates pass.');
+  process.exit(0);
+}
+
+const cwd = process.cwd();
+const gitDir = existsSync(path.join(cwd, '.git')) ? path.join(cwd, '.git') : null;
+
+if (!gitDir) {
+  console.error('No .git directory here. Run from the root of a git repository.');
+  process.exit(1);
+}
+
+const hooksDir = path.join(gitDir, 'hooks');
+mkdirSync(hooksDir, { recursive: true });
+
+const PRE_COMMIT = `#!/bin/sh
+# anti-slop pre-commit gate (installed by scripts/anti-slop/install-hooks.mjs)
+staged=$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\\.(ts|tsx|js|jsx|mjs|mts)$')
+[ -z "$staged" ] && exit 0
+
+echo "[anti-slop] modularity check on staged files..."
+# shellcheck disable=SC2086
+node scripts/anti-slop/check-modularity.mjs $staged || exit 1
+
+echo "[anti-slop] docs check on staged files..."
+# shellcheck disable=SC2086
+node scripts/anti-slop/check-docs.mjs $staged || exit 1
+
+echo "[anti-slop] import-boundary report (non-blocking; cycles are tree-wide)..."
+node scripts/anti-slop/check-imports.mjs --report-only || true
+
+echo "[anti-slop] duplicate-code report (non-blocking):"
+node scripts/anti-slop/check-duplicates.mjs --min-tokens 20 --threshold 0 || true
+
+exit 0
+`;
+
+const PRE_PUSH = `#!/bin/sh
+# anti-slop pre-push gate (installed by scripts/anti-slop/install-hooks.mjs)
+echo "[anti-slop] duplicate-code gate..."
+node scripts/anti-slop/check-duplicates.mjs || exit 1
+
+echo "[anti-slop] import-boundary gate..."
+node scripts/anti-slop/check-imports.mjs || exit 1
+
+echo "[anti-slop] project checks (--if-present)..."
+npm run lint --if-present || exit 1
+npm run typecheck --if-present || exit 1
+npm test --if-present || exit 1
+
+exit 0
+`;
+
+const writeHook = (name, body) => {
+  const dest = path.join(hooksDir, name);
+  if (existsSync(dest) && !force) {
+    console.error(`[skip] ${name} already exists (use --force to overwrite)`);
+    return;
+  }
+  writeFileSync(dest, body, { mode: 0o755 });
+  console.log(`[ok] wrote ${path.relative(cwd, dest)}`);
+};
+
+writeHook('pre-commit', PRE_COMMIT);
+if (preCommitOnly) {
+  console.log('[skip] pre-push (--pre-commit-only)');
+} else {
+  writeHook('pre-push', PRE_PUSH);
+}
+
+console.log(`
+Notes:
+- Hooks require core.hooksPath to be unset (default). Verify: git config core.hooksPath
+- Pre-commit only checks staged files, so pre-existing violations elsewhere do not block.
+- To bypass once in an emergency: git commit --no-verify (use sparingly; it defeats the gate).
+`);