opencode-anti-slop 0.0.0-stage → 0.1.1

package/scripts/anti-slop/lib.mjs

@@ -0,0 +1,204 @@
+/**
+ * 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;
+}
+
+/**
+ * Remove comments and string contents so brace/regex analysis is reliable.
+ * Newlines (including those inside strings) are preserved, so line numbers
+ * computed on the output match the original source.
+ */
+export function stripNoise(src) {
+  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++;
+      while (i < n && src[i] !== quote) {
+        if (src[i] === '\\') i++;
+        if (src[i] === '\n') out += '\n';
+        i++;
+      }
+      i++; // closing quote
+      out += '""';
+    } else {
+      out += c;
+      i++;
+    }
+  }
+  return out;
+}
+
+/**
+ * Remove comments while KEEPING string contents, preserving newlines. Used
+ * where the text inside strings matters (import specifier parsing) but
+ * comment noise must not create false edges.
+ */
+export function stripComments(src) {
+  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 {
+      out += c;
+      i++;
+    }
+  }
+  return out;
+}
+
+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) => {
+    if (name && !found.some((e) => e.name === name)) found.push({ name, kind, index });
+  };
+
+  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);
+  }
+  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);
+  }
+  for (const m of source.matchAll(/export\s+(?:abstract\s+)?class\s+([A-Za-z0-9_$]+)/g)) {
+    add(m[1], 'class', m.index);
+  }
+  for (const m of source.matchAll(/export\s+(?:type|interface)\s+([A-Za-z0-9_$]+)/g)) {
+    add(m[1], 'type', m.index);
+  }
+  if (/export\s+default\s+(?!function|class|const)/.test(source)) {
+    add('default', 'default', source.length);
+  }
+  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/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