opencode-anti-slop 0.0.0-stage → 0.1.1

package/scripts/anti-slop/check-duplicates.mjs

@@ -0,0 +1,182 @@
+#!/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 { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import {
+  walk, stripNoise, tokenize, lineOf,
+} from './lib.mjs';
+import { loadConfig, matchesAnyGlob, bootstrapGate, resolveScanTarget } from './cli.mjs';
+
+// --- args -------------------------------------------------------------------
+// Defaults < anti-slop.config.json < CLI flags.
+const cfgDups = (loadConfig().duplicates ?? {});
+const { args, positionals } = bootstrapGate(process.argv.slice(2), {
+  usage: 'Usage: node check-duplicates.mjs [--src src] [--min-tokens 50] [--threshold 3]\n' +
+         'Config: anti-slop.config.json "duplicates" section (src, minTokens, threshold, ignore globs).',
+  spec: { '--src': 'string', '--min-tokens': 'number', '--threshold': 'number' },
+  defaults: {
+    src: cfgDups.src ?? 'src',
+    minTokens: cfgDups.minTokens ?? 50,
+    threshold: cfgDups.threshold ?? 3,
+  },
+});
+if (positionals.length > 0) {
+  console.error(`Unexpected arguments: ${positionals.join(' ')} (this script takes flags only)`);
+  process.exit(1);
+}
+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,
+  });
+}
+
+for (const r of cloneRegions) {
+  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 (cloneRegions.length === 0) {
+  console.log('[ok] No duplicates found.');
+  process.exit(0);
+}
+
+const MAX_REPORT = 40;
+console.log(`Found ${cloneRegions.length} clone region(s). Showing up to ${MAX_REPORT}:\n`);
+for (const r of cloneRegions.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, 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)}%)`);
+
+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.'
+  );
+  process.exit(1);
+}
+console.log('[ok] Duplicate-code check passed.');

package/scripts/anti-slop/check-imports.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * check-imports.mjs
+ *
+ * Import-boundary gate: detects circular dependencies (default, blocking)
+ * and configurable layer violations (`imports.deny` in anti-slop.config.json).
+ * Catches the architecture drift that size budgets cannot: a cycle between
+ * modules is two responsibilities fused, and a `from`/`forbid` rule encodes
+ * the ports-and-adapters direction the modular-architecture skill teaches.
+ *
+ * Zero dependencies. Resolution is relative-import only (package specifiers
+ * are ignored); candidates probe extensions and /index files.
+ *
+ * Usage:
+ *   node scripts/anti-slop/check-imports.mjs [--src src] [--report-only]
+ *
+ * Config:
+ *   "imports": { "src": "src", "deny": [{ "from": "src/app/**", "forbid": "src/collections/**" }] }
+ *   `from`/`forbid` are globs matched against repo-relative paths ('/' separators).
+ */
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { walk, stripComments } from './lib.mjs';
+import { loadConfig, bootstrapGate, resolveScanTarget, matchesAnyGlob } from './cli.mjs';
+
+// --- parsing ------------------------------------------------------------------
+
+const IMPORT_RE =
+  /(?:import|export)\s+(?:[\w*{}\s,]*?\sfrom\s+)?['"]([^'"]+)['"]|(?:require|import)\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+const PROBE_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.mts'];
+
+/** Resolve a relative specifier to a file inside `root`; null for packages/misses.
+ * Probes extensions and /index files; a specifier written with one extension
+ * (e.g. './c.js' for a c.ts file, the TS convention) is re-probed with all of them.
+ */
+export function resolveSpecifier(fromFull, spec, root) {
+  if (!spec.startsWith('.')) return null;
+  let base = path.resolve(path.dirname(fromFull), spec);
+  const hasExt = PROBE_EXTS.includes(path.extname(base).toLowerCase());
+  const stem = hasExt ? base.slice(0, base.length - path.extname(base).length) : base;
+  const candidates = [
+    ...(hasExt ? [base] : []),
+    ...PROBE_EXTS.map((e) => stem + e),
+    ...PROBE_EXTS.map((e) => path.join(stem, 'index' + e)),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c) && statSync(c).isFile()) {
+      return path.relative(root, c).split(path.sep).join('/');
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract import specifiers, skipping statements that begin inside string
+ * literals — a code example embedded in a string is not an import edge.
+ */
+function parseImports(source) {
+  const ranges = stringRanges(source);
+  const specs = [];
+  for (const m of source.matchAll(IMPORT_RE)) {
+    const idx = m.index ?? 0;
+    if (ranges.some(([s, e]) => idx >= s && idx <= e)) continue;
+    const spec = m[1] ?? m[2];
+    if (spec) specs.push(spec);
+  }
+  return specs;
+}
+
+/** [start, end] index ranges of string literals (end = closing quote index). */
+function stringRanges(src) {
+  const ranges = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === '"' || c === "'" || c === '`') {
+      const start = i;
+      const q = c;
+      i++;
+      while (i < src.length && src[i] !== q) {
+        if (src[i] === '\\') i++;
+        i++;
+      }
+      ranges.push([start, i]);
+      i++; // closing quote
+    } else {
+      i++;
+    }
+  }
+  return ranges;
+}
+
+/** Build the internal import graph: relFile -> Set<relFile> (relative imports only). */
+export function buildImportGraph(files, root) {
+  const graph = new Map();
+  for (const file of files) {
+    const source = stripComments(readFileSync(file.full, 'utf8'));
+    const edges = graph.get(file.rel) ?? new Set();
+    for (const spec of parseImports(source)) {
+      const resolved = resolveSpecifier(file.full, spec, root);
+      if (resolved && resolved !== file.rel) edges.add(resolved);
+    }
+    graph.set(file.rel, edges);
+  }
+  return graph;
+}
+
+/**
+ * Find circular dependencies. Returns each cycle once, as a chain
+ * [a, b, ..., a] rotated so the lexicographically smallest node is first.
+ */
+export function findCycles(graph) {
+  const cycles = new Map(); // key -> chain
+  const state = new Map(); // rel -> 'visiting' | 'done'
+  const stack = [];
+
+  function dfs(node) {
+    state.set(node, 'visiting');
+    stack.push(node);
+    for (const next of graph.get(node) ?? []) {
+      const s = state.get(next);
+      if (s === 'visiting') {
+        const at = stack.indexOf(next);
+        const chain = stack.slice(at).concat(next);
+        const key = [...chain.slice(0, -1)].sort().join('~');
+        if (!cycles.has(key)) cycles.set(key, chain);
+      } else if (!s) {
+        dfs(next);
+      }
+    }
+    stack.pop();
+    state.set(node, 'done');
+  }
+
+  for (const node of graph.keys()) {
+    if (!state.get(node)) dfs(node);
+  }
+  return [...cycles.values()];
+}
+
+// --- CLI (only when run directly; exported functions are unit-testable) --------
+
+const isMain =
+  process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (isMain) {
+  const cfgImports = loadConfig().imports ?? {};
+  const { args, positionals } = bootstrapGate(process.argv.slice(2), {
+    usage: 'Usage: node check-imports.mjs [--src src] [--report-only]\n' +
+      'Config: anti-slop.config.json "imports" section (src, deny: [{from, forbid}]).',
+    spec: { '--src': 'string', '--report-only': 'flag' },
+    defaults: { src: cfgImports.src ?? 'src' },
+  });
+  if (positionals.length > 0) {
+    console.error(`Unexpected arguments: ${positionals.join(' ')} (this script takes flags only)`);
+    process.exit(1);
+  }
+
+  const src = path.resolve(args.src);
+  if (!existsSync(src) || !statSync(src).isDirectory()) {
+    console.error(`Source directory not found: ${src}`);
+    process.exit(1);
+  }
+  const files = resolveScanTarget(args.src);
+  const graph = buildImportGraph(files, src);
+  const deny = Array.isArray(cfgImports.deny) ? cfgImports.deny : [];
+
+  let violations = 0;
+
+  const cycles = findCycles(graph);
+  if (cycles.length > 0) {
+    console.log(`Circular dependencies (${cycles.length}):`);
+    for (const chain of cycles.slice(0, 20)) {
+      console.log(`  ${chain.join(' -> ')}`);
+      violations++;
+    }
+  }
+
+  for (const rule of deny) {
+    if (!rule?.from || !rule?.forbid) {
+      console.error(`[warn] ignoring malformed imports.deny rule: ${JSON.stringify(rule)}`);
+      continue;
+    }
+    for (const [from, edges] of graph) {
+      if (!matchesAnyGlob(from, [rule.from])) continue;
+      for (const to of edges) {
+        if (matchesAnyGlob(to, [rule.forbid])) {
+          console.log(`Layer violation: ${from} imports ${to} (deny: from '${rule.from}' forbid '${rule.forbid}')`);
+          violations++;
+        }
+      }
+    }
+  }
+
+  if (violations === 0) {
+    console.log(`[ok] Import-boundary check passed (${graph.size} files, no cycles, ${deny.length} layer rule(s)).`);
+    process.exit(0);
+  }
+
+  console.error(
+    `\n[x] Import-boundary check FAILED (${violations} violation(s)).\n` +
+    '    Fix: break the cycle by extracting the shared part into a module both can import\n' +
+    '    (see the modular-architecture skill). Do NOT create a re-export shim that keeps the cycle.'
+  );
+  process.exit(args.reportOnly ? 0 : 1);
+}

package/scripts/anti-slop/check-imports.test.mjs

@@ -0,0 +1,128 @@
+/**
+ * Unit tests for the import-boundary gate's graph logic (check-imports.mjs).
+ * The script guards its CLI behind an isMain check so these can import 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 { buildImportGraph, findCycles, resolveSpecifier } from './check-imports.mjs';
+
+function fixture(files) {
+  const root = mkdtempSync(path.join(tmpdir(), 'antislop-imports-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const full = path.join(root, rel);
+    mkdirSync(path.dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return root;
+}
+
+test('resolveSpecifier: probes extensions and index files', () => {
+  const root = fixture({
+    'lib/date.ts': 'export const d = 1;',
+    'lib/util.ts': 'export const u = 1;',
+    'lib/legacy.mjs': 'export const l = 1;',
+    'lib/store/index.ts': 'export const s = 1;',
+  });
+  const from = path.join(root, 'lib', 'date.ts');
+  assert.equal(resolveSpecifier(from, './util', root), 'lib/util.ts');
+  // TS convention: a .js specifier may point at a .ts file
+  assert.equal(resolveSpecifier(from, './util.js', root), 'lib/util.ts');
+  assert.equal(resolveSpecifier(from, './legacy.mjs', root), 'lib/legacy.mjs');
+  assert.equal(resolveSpecifier(from, './store', root), 'lib/store/index.ts');
+  assert.equal(resolveSpecifier(from, 'react', root), null);
+  assert.equal(resolveSpecifier(from, './missing', root), null);
+  assert.equal(resolveSpecifier(from, './missing.js', root), null);
+  rmSync(root, { recursive: true, force: true });
+});
+
+test('buildImportGraph: edges from import/export-from/require/dynamic', () => {
+  const root = fixture({
+    'src/a.ts': [
+      "import { b } from './b';",
+      "export * from './c.js';",
+      "const d = require('./d');",
+      "async () => { const e = await import('./e'); };",
+    ].join('\n'),
+    'src/b.ts': "import { c } from './c';",
+    'src/c.ts': 'export const c = 1;',
+    'src/d.ts': 'export const d = 1;',
+    'src/e.ts': 'export const e = 1;',
+  });
+  const files = [
+    'src/a.ts', 'src/b.ts', 'src/c.ts', 'src/d.ts', 'src/e.ts',
+  ].map((rel) => ({ full: path.join(root, rel), rel }));
+  const graph = buildImportGraph(files, root);
+  assert.deepEqual([...graph.get('src/a.ts')].sort(), ['src/b.ts', 'src/c.ts', 'src/d.ts', 'src/e.ts']);
+  assert.deepEqual([...graph.get('src/b.ts')], ['src/c.ts']);
+  rmSync(root, { recursive: true, force: true });
+});
+
+test('buildImportGraph: imports inside comments and strings are ignored', () => {
+  const root = fixture({
+    'src/a.ts': [
+      "// import { ghost } from './ghost';",
+      '/* import { ghost2 } from "./ghost2"; */',
+      "const tip = \"import x from './ghost3';\";",
+      "import { b } from './b';",
+    ].join('\n'),
+    'src/b.ts': 'export const b = 1;',
+    'src/ghost.ts': 'export const g = 1;',
+    'src/ghost2.ts': 'export const g2 = 1;',
+    'src/ghost3.ts': 'export const g3 = 1;',
+  });
+  const files = ['src/a.ts', 'src/b.ts', 'src/ghost.ts', 'src/ghost2.ts', 'src/ghost3.ts']
+    .map((rel) => ({ full: path.join(root, rel), rel }));
+  const graph = buildImportGraph(files, root);
+  assert.deepEqual([...graph.get('src/a.ts')], ['src/b.ts']);
+  rmSync(root, { recursive: true, force: true });
+});
+
+test('findCycles: two-node cycle found once', () => {
+  const graph = new Map([
+    ['a.ts', new Set(['b.ts'])],
+    ['b.ts', new Set(['a.ts'])],
+    ['c.ts', new Set(['a.ts'])],
+  ]);
+  const cycles = findCycles(graph);
+  assert.equal(cycles.length, 1);
+  const chain = cycles[0];
+  assert.equal(chain[0], chain[chain.length - 1]);
+  assert.deepEqual([...chain.slice(0, -1)].sort(), ['a.ts', 'b.ts']);
+});
+
+test('findCycles: three-node cycle and self-import', () => {
+  const graph = new Map([
+    ['a.ts', new Set(['b.ts'])],
+    ['b.ts', new Set(['c.ts'])],
+    ['c.ts', new Set(['a.ts'])],
+    ['d.ts', new Set(['d.ts'])],
+  ]);
+  const cycles = findCycles(graph);
+  assert.equal(cycles.length, 2);
+  const three = cycles.find((c) => c.length === 4);
+  assert.deepEqual(three, ['a.ts', 'b.ts', 'c.ts', 'a.ts']);
+  const self = cycles.find((c) => c.length === 2);
+  assert.deepEqual(self, ['d.ts', 'd.ts']);
+});
+
+test('findCycles: acyclic graph -> no cycles', () => {
+  const graph = new Map([
+    ['a.ts', new Set(['b.ts', 'c.ts'])],
+    ['b.ts', new Set(['c.ts'])],
+    ['c.ts', new Set([])],
+  ]);
+  assert.deepEqual(findCycles(graph), []);
+});
+
+test('findCycles: deep cycle through many nodes does not blow the stack guard', () => {
+  const graph = new Map();
+  for (let i = 0; i < 200; i++) graph.set(`f${i}.ts`, new Set([`f${(i + 1) % 200}.ts`]));
+  const cycles = findCycles(graph);
+  assert.equal(cycles.length, 1);
+  assert.equal(cycles[0].length, 201);
+});

package/scripts/anti-slop/check-modularity.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * check-modularity.mjs
+ *
+ * Deterministic monolith gate. Flags structural size violations:
+ *   - files exceeding --max-file-lines (default 300)
+ *   - functions/methods exceeding --max-function-lines (default 80)
+ *   - classes exceeding --max-class-methods (default 10 public methods)
+ *
+ * Zero dependencies. Parsing is heuristic (brace matching on comment/string-
+ * stripped source); thresholds are budgets, not exact science — treat hits as
+ * "split by responsibility" signals.
+ *
+ * Usage:
+ *   node scripts/anti-slop/check-modularity.mjs [paths...] [--src src] [--max-file-lines 300]
+ *        [--max-function-lines 80] [--max-class-methods 10] [--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 violations don't block commits).
+ * --report-only prints findings but always exits 0.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import {
+  walk, stripNoise, lineOf,
+} from './lib.mjs';
+import { loadConfig, bootstrapGate, collectPathFiles, resolveScanTarget } from './cli.mjs';
+
+// Defaults < anti-slop.config.json < CLI flags.
+const cfgMod = ((loadConfig().modularity) ?? {});
+const { args, positionals } = bootstrapGate(process.argv.slice(2), {
+  usage: 'Usage: node check-modularity.mjs [paths...] [--src src] [--max-file-lines 300] [--max-function-lines 80] [--max-class-methods 10] [--report-only]\n' +
+         'Config: anti-slop.config.json "modularity" section (src, maxFileLines, maxFunctionLines, maxClassMethods).\n' +
+         'With path arguments, checks exactly those files (git-hook staged mode).',
+  spec: {
+    '--src': 'string', '--max-file-lines': 'number', '--max-function-lines': 'number',
+    '--max-class-methods': 'number', '--report-only': 'flag',
+  },
+  defaults: {
+    src: cfgMod.src ?? 'src',
+    maxFileLines: cfgMod.maxFileLines ?? 300,
+    maxFunctionLines: cfgMod.maxFunctionLines ?? 80,
+    maxClassMethods: cfgMod.maxClassMethods ?? 10,
+  },
+});
+const paths = positionals;
+
+function analyze(source, limits) {
+  const findings = [];
+  const stripped = stripNoise(source);
+  const totalLines = source.split('\n').length;
+
+  if (totalLines > limits.maxFileLines) {
+    findings.push({ kind: 'file', line: 1, detail: `${totalLines} lines (> ${limits.maxFileLines})` });
+  }
+
+  // Brace matching; record regions opened by a function-like `{`.
+  // A `{` is function-like when the preceding non-space char is `)` (params)
+  // or `>` of an arrow `=>`.
+  const stack = []; // { depth, start, isFn }
+  let depth = 0;
+  const regions = []; // { startIdx, endIdx, isFn }
+  const classes = []; // { startIdx, endIdx, name, depth }
+  let classStart = null; // { name, depth, braceDepth|null, methods }
+
+  for (let i = 0; i < stripped.length; i++) {
+    const c = stripped[i];
+    if (c === '{') {
+      let j = i - 1;
+      while (j >= 0 && /\s/.test(stripped[j])) j--;
+      const prev = j >= 0 ? stripped[j] : '';
+      // detect `class X ... {`
+      const head = stripped.slice(Math.max(0, i - 200), i);
+      const cm = /(?:^|[\s;}])class\s+([A-Za-z0-9_$]+)[^{}]*$/.exec(head);
+      const isFn = prev === ')' || head.trimEnd().endsWith('=>');
+      if (cm && classStart === null) {
+        classStart = { name: cm[1], declIdx: i, braceDepth: depth, methods: 0 };
+      } else if (classStart && classStart.braceDepth !== null && depth === classStart.braceDepth + 1 && prev === ')') {
+        classStart.methods++;
+      }
+      stack.push({ depth, start: i, isFn, classStart });
+      depth++;
+    } else if (c === '}') {
+      depth--;
+      const open = stack.pop();
+      if (open) {
+        if (open.isFn) regions.push({ startIdx: open.start, endIdx: i });
+        if (classStart && open.depth === classStart.braceDepth) {
+          classes.push({ ...classStart, endIdx: i });
+          classStart = null;
+        }
+      }
+    }
+  }
+
+  for (const r of regions) {
+    const startLine = lineOf(stripped, r.startIdx);
+    const endLine = lineOf(stripped, r.endIdx);
+    const len = endLine - startLine + 1;
+    if (len > limits.maxFunctionLines) {
+      findings.push({ kind: 'function', line: startLine, detail: `${len} lines (> ${limits.maxFunctionLines})` });
+    }
+  }
+  for (const c of classes) {
+    if (c.methods > limits.maxClassMethods) {
+      findings.push({
+        kind: 'class',
+        line: lineOf(stripped, c.declIdx),
+        detail: `class ${c.name}: ${c.methods} methods (> ${limits.maxClassMethods})`,
+      });
+    }
+  }
+
+  return { findings, totalLines };
+}
+
+// --- run ---------------------------------------------------------------------
+const files = positionals.length > 0 ? collectPathFiles(positionals) : resolveScanTarget(args.src);
+
+const limits = {
+  maxFileLines: args.maxFileLines,
+  maxFunctionLines: args.maxFunctionLines,
+  maxClassMethods: args.maxClassMethods,
+};
+
+let violations = 0;
+for (const file of files) {
+  const { findings, totalLines } = analyze(readFileSync(file.full, 'utf8'), limits);
+  if (findings.length === 0) continue;
+  console.log(`${file.rel} (${totalLines} lines):`);
+  for (const f of findings) {
+    console.log(`  [${f.kind}] line ${f.line}: ${f.detail}`);
+    violations++;
+  }
+}
+
+if (violations === 0) {
+  console.log(`[ok] Modularity check passed (${files.length} files within budgets).`);
+  process.exit(0);
+}
+
+console.log(`\n${violations} size-budget violation(s) in ${files.length} file(s).`);
+console.error(
+  '[x] Modularity check FAILED.\n' +
+  '    Fix: split by responsibility (see the modular-architecture skill) — transport/service/domain/data,\n' +
+  '    smaller functions, smaller public surfaces. Do NOT compress code, raise budgets, or disable the check.'
+);
+process.exit(args.reportOnly ? 0 : 1);