opencode-anti-slop 0.0.0-stage → 0.1.4

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

@@ -0,0 +1,97 @@
+#!/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, 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; sensitivity from anti-slop.config.json):"
+node scripts/anti-slop/check-duplicates.mjs --threshold 0 --summary || 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 (lint/typecheck/test; skips are printed, not hidden)..."
+node scripts/anti-slop/run-project-checks.mjs || 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).
+`);

package/scripts/anti-slop/lib.mjs

@@ -0,0 +1,210 @@
+/**
+ * lib.mjs — shared source-scanning helpers for the anti-slop gate scripts.
+ *
+ * Zero dependencies (Node >= 18, ESM). CLI/config plumbing lives in cli.mjs;
+ * this module is pure scanning: file discovery, noise stripping, tokenizing,
+ * export extraction. Keep it free of I/O decisions and argument parsing.
+ */
+
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+
+/** Directories never scanned by the gates (deps, build output, tests, tooling). */
+export const EXCLUDE_DIRS = new Set([
+  'node_modules', 'dist', 'build', 'out', '.next', '.turbo',
+  'coverage', 'storybook-static', '__tests__', '__mocks__',
+]);
+/** Filename patterns never gated: test/spec/story files (any JS/TS extension incl. mjs/mts) and type declaration shims. */
+export const IGNORE_FILE = /(\.test|\.spec|\.stories|\.d)\.[mc]?[tj]sx?$/;
+
+/** Generated files that must never be gated (sizes/counts are machine-owned). */
+export const GENERATED_FILE = /(^|\/)(payload-types|next-env)(\.d)?\.ts$/;
+
+/** True when relPath is a generated artifact (see GENERATED_FILE). */
+export function isGenerated(relPath) {
+  return GENERATED_FILE.test(relPath);
+}
+
+/** Source file extensions the gates scan. */
+export const SOURCE_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.mts']);
+
+/** Recursively list source files under `dir`, as { full, rel } with '/'-separated rel paths. */
+export function walk(dir, base) {
+  const files = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') || EXCLUDE_DIRS.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    const rel = path.relative(base, full).split(path.sep).join('/');
+    if (entry.isDirectory()) files.push(...walk(full, base));
+    else if (SOURCE_EXT.has(path.extname(entry.name)) && !IGNORE_FILE.test(entry.name) && !isGenerated(rel)) {
+      files.push({ full, rel });
+    }
+  }
+  return files;
+}
+
+/**
+ * Comment/string handling shared by both strippers below. Newlines (including
+ * those inside strings) are preserved, so line numbers computed on the output
+ * match the original source.
+ */
+function stripSource(src, blankStrings) {
+  let out = '';
+  let i = 0;
+  const n = src.length;
+  while (i < n) {
+    const c = src[i];
+    const next = src[i + 1];
+    if (c === '/' && next === '/') {
+      while (i < n && src[i] !== '\n') i++;
+    } else if (c === '/' && next === '*') {
+      i += 2;
+      while (i < n && !(src[i] === '*' && src[i + 1] === '/')) {
+        if (src[i] === '\n') out += '\n';
+        i++;
+      }
+      i += 2;
+    } else if (c === '"' || c === "'" || c === '`') {
+      const quote = c;
+      i++;
+      if (blankStrings) {
+        while (i < n && src[i] !== quote) {
+          if (src[i] === '\\') i++;
+          if (src[i] === '\n') out += '\n';
+          i++;
+        }
+        i++; // closing quote
+        out += '""';
+      } else {
+        out += quote;
+        while (i < n && src[i] !== quote) {
+          if (src[i] === '\\' && i + 1 < n) {
+            out += src[i] + src[i + 1];
+            i += 2;
+            continue;
+          }
+          out += src[i];
+          i++;
+        }
+        out += quote;
+        i++; // closing quote
+      }
+    } else {
+      out += c;
+      i++;
+    }
+  }
+  return out;
+}
+
+/**
+ * Remove comments and blank string contents so brace/regex analysis is
+ * reliable. Newlines are preserved, so line numbers computed on the output
+ * match the original source.
+ */
+export function stripNoise(src) {
+  return stripSource(src, true);
+}
+
+/**
+ * Remove comments while KEEPING string contents verbatim — used where the
+ * text inside strings matters (import specifier parsing) but comment noise
+ * must not create false edges.
+ */
+export function stripComments(src) {
+  return stripSource(src, false);
+}
+
+const TOKEN_RE =
+  /"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|`(?:[^`\\]|\\.)*`|[A-Za-z_$][\w$]*|\d+(?:\.\d+)?|\S/g;
+
+/** Tokenize stripped source into normalized tokens [{ t, line }] (1-based lines): strings -> `<str>`, numbers -> `<num>`, identifiers/symbols stay literal. */
+export function tokenize(stripped) {
+  const tokens = [];
+  for (const m of stripped.matchAll(TOKEN_RE)) {
+    let nl = 0;
+    for (let k = 0; k < m.index; k++) if (m.input[k] === '\n') nl++;
+    const raw = m[0];
+    const t = raw[0] === '"' || raw[0] === "'" || raw[0] === '`' ? '<str>'
+      : /^\d/.test(raw) ? '<num>'
+      : raw;
+    tokens.push({ t, line: 1 + nl });
+  }
+  return tokens;
+}
+
+/** 1-based line number of char index `idx` within comment/string-stripped source. */
+export function lineOf(stripped, idx) {
+  let line = 1;
+  for (let i = 0; i < idx && i < stripped.length; i++) {
+    if (stripped[i] === '\n') line++;
+  }
+  return line;
+}
+
+/**
+ * Returns the first line of the JSDoc/TSDoc block immediately preceding
+ * source index `idx`, or null if there is none.
+ *
+ * Why this is not a one-line regex: the previous implementation scanned with
+ * `/\/\*\*([\s\S]*?)\*\/\s*$/`. The `$` anchor plus a lazy capture makes that
+ * match start at the FIRST docblock in the file and end at the LAST closing
+ * terminator before the declaration, so every export reported the module
+ * header — in a real repo, four server actions all described as "Carer-facing
+ * mutations." and a type's doc attached to the function above it. A one-line
+ * block also leaked its closing terminator into docs/COMPONENT_INDEX.md.
+ * check-docs only requires a non-null first line, so the gate passed while the
+ * inventory that `reuse-before-create` is grounded in was wrong.
+ *
+ * Keep both properties: the NEAREST block, and only when nothing but whitespace
+ * sits between its close and the declaration. Anything else must return null —
+ * that is the "undocumented" verdict the gate exists to report, and it is safer
+ * than borrowing a neighbouring comment.
+ */
+export function jsdocBefore(source, idx) {
+  const slice = source.slice(0, idx);
+  const start = slice.lastIndexOf('/**');
+  if (start === -1) return null;
+  const end = slice.indexOf('*/', start);
+  if (end === -1) return null;
+  if (slice.slice(end + 2).trim() !== '') return null;
+
+  const lines = slice
+    .slice(start + 3, end)
+    .split('\n')
+    .map((l) => l.replace(/^\s*\*+\s?/, '').trim())
+    .filter(Boolean);
+  if (lines.length === 0) return null;
+  const desc = lines[0];
+  return desc.startsWith('@') ? null : desc; // tag-only blocks are not usage docs
+}
+
+/**
+ * Extract exported declarations from source: [{ name, kind, index, desc }].
+ * `desc` is the JSDoc first line (null when undocumented).
+ */
+export function extractExports(source) {
+  const found = [];
+  const add = (name, kind, index, isDefault) => {
+    if (name && !found.some((e) => e.name === name)) {
+      found.push({ name, kind, index, isDefault: Boolean(isDefault) });
+    }
+  };
+
+  for (const m of source.matchAll(/export\s+(?:default\s+)?(?:async\s+)?function\s*\*?\s*([A-Za-z0-9_$]+)/g)) {
+    add(m[1], 'function', m.index, m[0].startsWith('export default'));
+  }
+  for (const m of source.matchAll(/export\s+(?:default\s+)?const\s+([A-Za-z0-9_$]+)/g)) {
+    add(m[1], /=>/.test(source.slice(m.index, m.index + 200)) ? 'function' : 'value', m.index, m[0].startsWith('export default'));
+  }
+  for (const m of source.matchAll(/export\s+(?:abstract\s+)?class\s+([A-Za-z0-9_$]+)/g)) {
+    add(m[1], 'class', m.index, m[0].startsWith('export default'));
+  }
+  for (const m of source.matchAll(/export\s+(?:type|interface)\s+([A-Za-z0-9_$]+)/g)) {
+    add(m[1], 'type', m.index, false);
+  }
+  if (/export\s+default\s+(?!function|class|const)/.test(source)) {
+    add('default', 'default', source.length, true);
+  }
+  return found.map((e) => ({ ...e, desc: jsdocBefore(source, e.index) }));
+}

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

@@ -0,0 +1,178 @@
+/**
+ * Unit tests for the shared scanning helpers (lib.mjs). Zero dependencies —
+ * runs with `node --test`. The jsdocBefore cases are regression tests for a
+ * real failure: a `$`-anchored lazy regex attached the file's FIRST docblock
+ * to every export, and the gate could not notice (it only required a non-null
+ * first line). If you "simplify" jsdocBackfore back into a one-line regex,
+ * these tests are the ones that will catch it.
+ */
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import {
+  extractExports,
+  isGenerated,
+  jsdocBefore,
+  lineOf,
+  stripNoise,
+  tokenize,
+  walk,
+} from './lib.mjs';
+
+// --- jsdocBefore -------------------------------------------------------------
+
+test('jsdocBefore: attached block supplies its first line', () => {
+  const src = '/** Formats dates for tables. */\nexport function f() {}';
+  const idx = src.indexOf('export');
+  assert.equal(jsdocBefore(src, idx), 'Formats dates for tables.');
+});
+
+test('jsdocBefore: multi-line block, first meaningful line wins', () => {
+  const src = [
+    '/**',
+    ' * Renders the standard page shell.',
+    ' * @param props - ignored',
+    ' */',
+    'export function f() {}',
+  ].join('\n');
+  const idx = src.indexOf('export');
+  assert.equal(jsdocBefore(src, idx), 'Renders the standard page shell.');
+});
+
+test('jsdocBefore: one-line block must not leak its terminator', () => {
+  const src = '/** doc */ export const x = 1';
+  const idx = src.indexOf('export');
+  const desc = jsdocBefore(src, idx);
+  assert.ok(!desc.includes('*/'), `terminator leaked: ${desc}`);
+});
+
+test('jsdocBefore: nearest of several blocks wins (regression: first-block bug)', () => {
+  const src = [
+    '/** Module header. */',
+    'export const a = 1;',
+    '/** Second helper. */',
+    'export const b = 2;',
+  ].join('\n');
+  const idxA = src.indexOf('export const a');
+  const idxB = src.indexOf('export const b');
+  assert.equal(jsdocBefore(src, idxA), 'Module header.');
+  assert.equal(jsdocBefore(src, idxB), 'Second helper.');
+});
+
+test('jsdocBefore: code between block and export means undocumented', () => {
+  const src = '/** Module header. */\nconst internal = 1;\nexport function f() {}';
+  const idx = src.indexOf('export');
+  assert.equal(jsdocBefore(src, idx), null);
+});
+
+test('jsdocBefore: blank lines between block and export are allowed', () => {
+  const src = '/** Doc. */\n\n\nexport const x = 1';
+  const idx = src.indexOf('export');
+  assert.equal(jsdocBefore(src, idx), 'Doc.');
+});
+
+test('jsdocBefore: tag-only block is not a usage doc', () => {
+  const src = '/** @internal */\nexport const x = 1';
+  const idx = src.indexOf('export');
+  assert.equal(jsdocBefore(src, idx), null);
+});
+
+test('jsdocBefore: no block at all -> null', () => {
+  assert.equal(jsdocBefore('export const x = 1', 0), null);
+});
+
+// --- extractExports -----------------------------------------------------------
+
+test('extractExports: classifies functions, consts, classes, types, default', () => {
+  const src = [
+    'export async function doThing() {}',
+    'export const handler = () => 1;',
+    'export const LIMIT = 3;',
+    'export class Repo {}',
+    'export type Shape = { a: number };',
+    'export interface Person { id: number }',
+    'export default config;',
+  ].join('\n');
+  const byName = new Map(extractExports(src).map((e) => [e.name, e]));
+  assert.equal(byName.get('doThing').kind, 'function');
+  assert.equal(byName.get('handler').kind, 'function');
+  assert.equal(byName.get('LIMIT').kind, 'value');
+  assert.equal(byName.get('Repo').kind, 'class');
+  assert.equal(byName.get('Shape').kind, 'type');
+  assert.equal(byName.get('Person').kind, 'type');
+  assert.equal(byName.get('default').kind, 'default');
+});
+
+test('extractExports: attached docs flow through', () => {
+  const src = '/** Doubles a value. */\nexport function double(x: number) { return x * 2; }';
+  const [e] = extractExports(src);
+  assert.equal(e.desc, 'Doubles a value.');
+});
+
+// --- stripNoise / tokenize / lineOf -------------------------------------------
+
+test('stripNoise: removes comments, blanks strings, preserves newlines', () => {
+  const src = [
+    '// line comment',
+    'const a = "two', // inside string newline
+    'words";',
+    '/* block',
+    'comment */',
+    'const b = 1;',
+  ].join('\n');
+  const out = stripNoise(src);
+  assert.ok(!out.includes('line comment'));
+  assert.ok(!out.includes('block'));
+  assert.equal(out.split('\n').length, src.split('\n').length);
+  assert.ok(out.includes('const b = 1;'));
+});
+
+test('tokenize: strings and numbers normalized, lines tracked', () => {
+  const stripped = 'const msg = "hello";\nconst n = 42;';
+  const tokens = tokenize(stripped);
+  const values = tokens.map((t) => t.t);
+  assert.deepEqual(values, ['const', 'msg', '=', '<str>', ';', 'const', 'n', '=', '<num>', ';']);
+  const numLine = tokens.find((t) => t.t === '<num>').line;
+  assert.equal(numLine, 2);
+});
+
+test('lineOf: char index to 1-based line', () => {
+  const s = 'one\ntwo\nthree';
+  assert.equal(lineOf(s, 0), 1);
+  assert.equal(lineOf(s, 5), 2);
+  assert.equal(lineOf(s, 9), 3);
+});
+
+// --- walk / isGenerated ---------------------------------------------------------
+
+test('walk: skips excluded dirs, tests, generated files', () => {
+  const root = mkdtempSync(path.join(tmpdir(), 'antislop-walk-'));
+  try {
+    mkdirSync(path.join(root, 'components'), { recursive: true });
+    mkdirSync(path.join(root, 'node_modules', 'pkg'), { recursive: true });
+    mkdirSync(path.join(root, 'dist'), { recursive: true });
+    writeFileSync(path.join(root, 'components', 'Card.tsx'), 'export const Card = 1;');
+    writeFileSync(path.join(root, 'components', 'Card.test.tsx'), 'export const t = 1;');
+    writeFileSync(path.join(root, 'components', 'util.test.mjs'), 'export const u = 1;');
+    writeFileSync(path.join(root, 'payload-types.ts'), 'export type X = 1;');
+    writeFileSync(path.join(root, 'node_modules', 'pkg', 'index.js'), 'module.exports = 1;');
+    writeFileSync(path.join(root, 'dist', 'out.js'), 'export const o = 1;');
+
+    const rels = walk(root, root).map((f) => f.rel);
+    assert.deepEqual(rels, ['components/Card.tsx']);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('isGenerated: payload-types and next-env, nothing else', () => {
+  assert.ok(isGenerated('payload-types.ts'));
+  assert.ok(isGenerated('src/app/payload-types.ts'));
+  assert.ok(isGenerated('next-env.d.ts'));
+  assert.ok(!isGenerated('src/lib/dbs.ts'));
+  assert.ok(!isGenerated('types.ts'));
+});

package/scripts/anti-slop/run-project-checks.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * run-project-checks.mjs — pre-push project checks, without silent skips.
+ *
+ * Runs the repo's own lint/typecheck/test scripts with the package manager
+ * detected from the lockfile, and:
+ *   - prints every check as present or skipped, so "nothing ran" is visible;
+ *   - falls back to `tsc --noEmit` when there is no typecheck script but a
+ *     tsconfig.json exists (a TypeScript repo must not pass untypechecked);
+ *   - works with npm, pnpm, yarn and bun.
+ *
+ * Zero dependencies. Exits non-zero on the first failing check.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const cwd = process.cwd();
+const pkg = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+const scripts = pkg.scripts ?? {};
+
+function detectPackageManager() {
+  if (existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsSync(path.join(cwd, 'yarn.lock'))) return 'yarn';
+  if (existsSync(path.join(cwd, 'bun.lockb')) || existsSync(path.join(cwd, 'bun.lock'))) return 'bun';
+  return 'npm';
+}
+
+const pm = detectPackageManager();
+const run = (cmd, args) => spawnSync(cmd, args, { stdio: 'inherit', shell: process.platform === 'win32' });
+
+/** Run `<pm> run <script>` when it exists. Returns 'ran' | 'skipped'. */
+function runScript(name) {
+  if (!scripts[name]) {
+    console.log(`[skip] ${name}: no "${name}" script in package.json`);
+    return 'skipped';
+  }
+  console.log(`[run] ${name} (${pm} run ${name})`);
+  const res = run(pm, ['run', name]);
+  if (res.status !== 0) {
+    console.error(`\n[x] "${name}" failed (exit ${res.status ?? 'signal'}).`);
+    process.exit(res.status ?? 1);
+  }
+  return 'ran';
+}
+
+/** tsc --noEmit fallback for TypeScript repos without a typecheck script. */
+function runTypecheck() {
+  if (scripts.typecheck) return runScript('typecheck');
+
+  const hasTs = existsSync(path.join(cwd, 'tsconfig.json')) ||
+    scripts.typescript !== undefined ||
+    (pkg.devDependencies && pkg.devDependencies.typescript);
+  if (!hasTs) {
+    console.log('[skip] typecheck: no typecheck script and no TypeScript setup detected');
+    return 'skipped';
+  }
+  console.log('[run] typecheck (fallback: tsc --noEmit — no "typecheck" script was found)');
+  const exec = pm === 'bun' ? 'bunx' : pm === 'npm' ? 'npx' : pm;
+  const res = run(exec, ['--no-install', 'tsc', '--noEmit']);
+  if (res.status !== 0) {
+    console.error(`\n[x] typecheck failed (exit ${res.status ?? 'signal'}).`);
+    process.exit(res.status ?? 1);
+  }
+  return 'ran';
+}
+
+console.log(`[anti-slop] project checks via ${pm}`);
+runScript('lint');
+runTypecheck();
+runScript('test');
+console.log('[ok] project checks done.');

package/templates/anti-slop-ci.yml

@@ -0,0 +1,22 @@
+# Anti-slop gates for this repository (installed by opencode-anti-slop).
+# Runs the deterministic checks on every push and pull request. Tune the
+# checks via anti-slop.config.json at the repo root.
+name: anti-slop
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: node scripts/anti-slop/check-modularity.mjs
+      - run: node scripts/anti-slop/check-imports.mjs
+      - run: node scripts/anti-slop/check-docs.mjs
+      - run: node scripts/anti-slop/check-duplicates.mjs
+      - run: node scripts/anti-slop/generate-component-index.mjs --check