opencode-anti-slop 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,275 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```text
+ █████╗   ███╗   ██╗████████╗ ██╗                 ███████╗  ██╗        ██████╗  ██████╗
+██╔══██╗  ████╗  ██║╚══██╔══╝ ██║                 ██╔════╝  ██║       ██╔═══██╗ ██╔══██╗
+███████║  ██╔══██║     ██║    ██║        ═════    ███████╗  ██║       ██║   ██║ ██████╔╝
+██╔══██║  ██║ ╚███║    ██║    ██║                 ╚════██║  ██║       ██║   ██║ ██╔═══╝
+██║  ██║  ██║ ╚████    ██║    ██║                 ███████║  ███████╗  ╚██████╔╝ ██║
+╚═╝  ╚═╝  ╚═╝  ╚═══    ╚═╝    ╚═╝                 ╚══════╝  ╚══════╝   ╚═════╝  ╚═╝
+```
+
+**Stop your AI coding agent from producing slop.**
+
+Agent skills + deterministic checks that force [OpenCode](https://opencode.ai)
+(and other AI coding agents) to reuse what exists, compose instead of rewrite,
+use React primitives correctly, and keep files modular — enforced at write
+time, commit time, and push time.
+
+[![ci](https://github.com/hyperbolictonic/opencode-anti-slop/actions/workflows/ci.yml/badge.svg)](https://github.com/hyperbolictonic/opencode-anti-slop/actions/workflows/ci.yml)
+![npm](https://img.shields.io/badge/install-npx--from--git-blue)
+![zero dependencies](https://img.shields.io/badge/dependencies-zero-success)
+
+</div>
+
+Built for **React and Node** projects. The gates run on **any JS/TS codebase**;
+the skills use the standard Agent Skills format, so they also work with Claude
+Code by copying them into `.claude/skills/`. The scripts and git hooks are
+agent-agnostic.
+
+## Quick start
+
+One command — installs skills, the `/audit-ui` command, gate scripts, the CI
+workflow, and (with `--hooks`) the git gates into the current directory:
+
+```sh
+npx opencode-anti-slop --hooks
+```
+
+> **npm >= 11 and the kit is git-hosted?** Use
+> `npx --allow-git=all github:hyperbolictonic/opencode-anti-slop --hooks`.
+> The `--allow-git=all` flag is npm's gate for git-hosted packages; older npm
+> runs without it. `--force` overwrites previously installed kit files; an
+> explicit target dir can be passed as the first argument.
+
+Manual equivalent (clone first, no npm involvement):
+
+```sh
+git clone https://github.com/hyperbolictonic/opencode-anti-slop.git
+node opencode-anti-slop/install.mjs path/to/your-project
+node scripts/anti-slop/generate-component-index.mjs   # in your project
+```
+
+Requires Node >= 18 and git. No npm dependencies — the kit installs clean into
+any project. The installer prints the manual steps that cannot be safely
+automated: an `AGENTS.md` snippet, optional `opencode.json` instructions,
+`package.json` scripts, and the ESLint hooks plugin.
+
+Skills are auto-discovered by OpenCode from `.opencode/skills/` in the target
+repo — no registration needed. They are advertised to the model by their
+`description` and load on demand via the `skill` tool. The `/audit-ui` command
+arrives with the kit and produces a prioritized refactor plan from the same
+deterministic checks.
+
+## The problem
+
+AI agents write code that works and rots: the same layout rebuilt per page, the
+same helper rewritten in three files, `useEffect` doing derived-state work,
+one 400-line file doing six jobs. Prompts like "keep it DRY" drift within a
+session and vanish between sessions. What does not drift is a script that exits
+non-zero — so this kit pairs model-level skills with deterministic gates:
+
+- the **agent** is instructed (skills) to check before building;
+- the **inventory** (`docs/COMPONENT_INDEX.md`, generated) tells it what exists;
+- the **gates** (scripts) catch whatever slips through;
+- the **hooks** (git) make violations fail loudly at commit and push.
+
+## What it catches
+
+| Slop pattern | Caught by |
+|---|---|
+| Rewritten layouts instead of reused components | `reuse-before-create` + `layout-composition` skills |
+| Duplicated components, hooks, utils, server actions | duplicate gate (token-based clone detection) |
+| Misused `useEffect`, premature `useMemo`/`useCallback`, Context abuse | `react-state-and-effects` skill |
+| Monolithic files, god classes, oversized functions | modularity gate (size budgets) |
+| Undocumented shared exports, stale component inventory | docs gate + index generator |
+| Load-bearing domain rules buried in UI components | `abstraction-review` skill (post-refactor) |
+
+A blocked commit looks like this:
+
+```text
+[anti-slop] modularity check on staged files...
+src/lib/monolith.ts (321 lines):
+  [file] line 1: 321 lines (> 300)
+  [function] line 16: 93 lines (> 80)
+  [class] line 1: class ReportOrchestrator: 12 methods (> 10)
+
+[x] Modularity check FAILED.
+    Fix: split by responsibility (see the modular-architecture skill) — transport/service/domain/data,
+    smaller functions, smaller public surfaces. Do NOT compress code, raise budgets, or disable the check.
+```
+
+Every failure message names the fix and the skill that owns it. Gate thresholds
+are per-repo tunable; weakening the check to pass it is the one forbidden fix.
+
+## What's inside
+
+```
+.opencode/skills/
+  reuse-before-create/          Mandatory pre-flight: search inventory + package.json
+                                before creating ANY new file. Rule of Two, extend
+                                don't clone, adapter pattern for external services.
+  layout-composition/           Pages with the same structure share ONE skeleton
+                                (2-column, dashboard, settings) filled via slots;
+                                page-specific widgets are sub-components.
+  react-composition-patterns/   Data/UI separation, slots & children over prop
+                                drilling, compound components, colocation.
+  react-state-and-effects/      useEffect/useMemo/useCallback/Context decision
+                                rules with explicit bans and gotchas.
+  modular-architecture/         UI and non-UI: single-responsibility modules,
+                                ports & adapters with injected dependencies, OO
+                                composition, no god files/classes/functions.
+  abstraction-review/           Post-refactor review for duplication that has
+                                not happened yet: load-bearing rules left in UI
+                                components, structural twins, near-clone triage.
+                                Reports with a cost-ranked contract; never
+                                auto-extracts.
+  verify-clean-code/            End-of-task gate: typecheck -> lint -> tests ->
+                                duplicate + modularity + docs checks -> index
+                                freshness -> abstraction review for refactors.
+
+.opencode/commands/
+  audit-ui.md                   /audit-ui — prioritized refactor plan built from
+                                the deterministic checks (duplication, monoliths,
+                                layout reuse, missing docs, misplaced logic).
+
+scripts/anti-slop/
+  lib.mjs                       Shared scanning helpers (walk, stripNoise,
+                                tokenize, lineOf, export extraction).
+  cli.mjs                       Shared CLI/config plumbing (flag parsing,
+                                per-repo config, path resolution).
+  generate-component-index.mjs  Scans src/ and (re)generates docs/COMPONENT_INDEX.md;
+                                pulls each export's "When to use" from its JSDoc.
+  check-duplicates.mjs          Copy/paste detector (token-based, zero deps);
+                                exits non-zero when duplication exceeds the
+                                per-repo threshold.
+  check-modularity.mjs          Monolith gate: file >300 / function >80 lines,
+                                class >10 methods. Per-file mode for git hooks.
+  check-imports.mjs             Import-boundary gate: circular dependencies
+                                (default) plus configurable layer rules
+                                (imports.deny). Per-file cycles are tree-wide.
+  check-docs.mjs                Docs gate: fails when exports lack a one-line
+                                "When to use" JSDoc. Per-file mode for hooks.
+  install-hooks.mjs             Installs pre-commit (staged files: modularity +
+                                docs, blocking) and pre-push (duplicate +
+                                import gates + lint/typecheck/test) git hooks.
+
+templates/anti-slop-ci.yml      GitHub Actions workflow the installer drops
+                                into target repos (.github/workflows/).
+install.mjs                     Installs skills + commands + scripts + CI
+                                template into a target repo.
+```
+
+## How enforcement works
+
+| Layer | Mechanism | Catches |
+|---|---|---|
+| Skills (model) | Loaded by trigger description before relevant work | Rewritten layouts, cloned components, wrong hook usage, monolith growth — at write time |
+| Component index (data) | Regenerated by script; JSDoc feeds the "When to use" column | Duplicating things that already exist because "nothing existed" |
+| Duplicates gate (script) | Built-in clone detector fails on duplication above threshold | Duplicates that slip past the model |
+| Modularity gate (script) | Size budgets: file >300 lines, function >80, class >10 methods | Monolithic files, god classes/functions |
+| Import gate (script) | Cycle detection + configurable `imports.deny` layer rules | Circular dependencies, domain logic importing transport |
+| Git hooks (target repo) | pre-commit checks staged files only (modularity + docs); pre-push runs full gates | New violations and undocumented exports at commit time without blocking on legacy code |
+| ESLint (config, target repo) | `eslint-plugin-react-hooks`, React Compiler rules | Hook dependency errors, redundant memoization |
+
+Rules of thumb baked into the skills:
+
+- **Rule of Two** — extract a shared abstraction only on the second use (or a
+  file over ~150 lines); never clone on the first variation.
+- **One skeleton, many fillers** — pages with the same structure share one
+  layout template via slots; they differ in sub-components, not markup.
+- **Monoliths are defects** — one responsibility per module; ports & adapters
+  with injected dependencies; size budgets enforced by the gate.
+- **Composition before Context** — slots/`children` before creating a Context.
+- **Effects only for external sync** — derived state during render, events in
+  handlers, data via the project's fetching library.
+- **No threshold weakening** — fix the duplication/monolith, don't tune the check.
+
+## Tuning per repo: `anti-slop.config.json`
+
+Each gate reads `anti-slop.config.json` from the repo root (defaults shown):
+
+```json
+{
+  "duplicates": {
+    "src": "src",
+    "minTokens": 50,
+    "threshold": 3,
+    "ignore": ["src/collections/**"]
+  },
+  "modularity": {
+    "src": "src",
+    "maxFileLines": 300,
+    "maxFunctionLines": 80,
+    "maxClassMethods": 10
+  },
+  "imports": {
+    "deny": [{ "from": "src/access/**", "forbid": "src/app/**" }]
+  }
+}
+```
+
+- `ignore` (duplicates only): globs relative to `src` for **framework-idiomatic
+  declarative files** — collection/field configs, generated route scaffolding.
+  Their repetition is shape a framework requires, not logic that can drift;
+  excluding them keeps the gate focused on logic clones. Exclusions are printed
+  on every run, so nothing is silently ignored.
+- `imports.deny`: rules encoding dependency direction — any file matching
+  `from` importing a file matching `forbid` is a violation. With no rules, the
+  import gate still detects circular dependencies.
+- CLI flags override the config; the config overrides defaults. Hooks call the
+  scripts bare, so the config governs them automatically.
+
+## What counts as duplication — and what doesn't
+
+- **Counts:** logic whose copies can drift — repeated guards, repeated
+  fetch/map flows, hand-rolled helpers for what a library or the framework
+  already provides.
+- **Doesn't count:** declarative scaffolding a framework requires you to write.
+  The dividing line is *drift*: extract a repeated block only when its copies
+  could behave differently. If a declarative block embeds a real rule (e.g.
+  who may read a record), extract that rule to one place and reference it —
+  the config stays, the behavior is single-source.
+- **Prefer the framework's own primitives** (auth, field-level access,
+  validation, versions) over hand-rolled equivalents — a second source of
+  truth is worse than repetition.
+
+## Tests and self-enforcement
+
+The gates are regression-tested with `node --test` (zero dependencies — same
+constraint as the scripts). The `jsdocBefore` cases exist because a one-line
+regex version of that function shipped a real bug: every export in an index
+reported the file's first docblock. If you touch the scanners, `npm test` is
+not optional.
+
+```sh
+npm test        # unit tests for lib.mjs and cli.mjs
+npm run gates   # the kit runs its own gates on its own source
+npm run index   # regenerate the kit's own component index
+```
+
+CI runs the tests and the self-gates on Node 20/22/24.
+
+## Scope, requirements and limitations
+
+- **Stacks:** React/Node rules in the skills; gates scan `.ts` `.tsx` `.js`
+  `.jsx` `.mjs` `.mts`. Other languages need their own gates — the system
+  design (inventory + drift principle + gates + hooks) still applies.
+- **Heuristics, not compilers:** the clone detector tokenizes rather than
+  parses; the modularity gate brace-matches rather than builds an AST. Treat
+  findings as strong signals, and `anti-slop.config.json` as the way to live
+  with rare false positives.
+- **Agent support:** skills follow the Agent Skills format — native for
+  OpenCode, copyable to `.claude/skills/` for Claude Code. The scripts and
+  hooks work with any agent plus git. `/audit-ui` is OpenCode-specific.
+
+## Reusable vs. project-specific
+
+The skills are project-agnostic: they direct the agent to discover each repo's
+own structure (`package.json`, source tree, `docs/COMPONENT_INDEX.md`) at
+runtime. Tuning per project happens in the target repo's `anti-slop.config.json`
+and its own `AGENTS.md` — not by editing these skills.
+
+## License
+
+[MIT](LICENSE)

package/install.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * install.mjs — install the anti-slop kit into a target repository.
+ *
+ * Also the npx entrypoint (`bin` in package.json):
+ *   npx github:hyperbolictonic/opencode-anti-slop          # install into cwd
+ *   npx github:hyperbolictonic/opencode-anti-slop ./app    # explicit target
+ *   npx github:hyperbolictonic/opencode-anti-slop --hooks  # + git hooks
+ *
+ * Copies:
+ *   .opencode/skills/<skills>            -> <target>/.opencode/skills/
+ *   .opencode/commands/audit-ui.md       -> <target>/.opencode/commands/
+ *   scripts/anti-slop/*.mjs              -> <target>/scripts/anti-slop/
+ *   templates/anti-slop-ci.yml           -> <target>/.github/workflows/
+ *
+ * Then prints the manual setup steps that cannot be safely automated
+ * (AGENTS.md snippet, opencode.json instructions, package.json scripts,
+ * ESLint setup). --hooks also installs the git pre-commit gate when the
+ * target is a git repo.
+ *
+ * Usage:
+ *   npx opencode-anti-slop [target-dir] [--force] [--hooks]
+ *   node install.mjs [target-repo-dir] [--force] [--hooks]
+ */
+
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const kitRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
+const argv = process.argv.slice(2);
+const flags = new Set(argv.filter((a) => a.startsWith('--')));
+const force = flags.has('--force');
+const wantHooks = flags.has('--hooks');
+const targetArg = argv.find((a) => !a.startsWith('--'));
+const helpRequested = flags.has('-h') || flags.has('--help');
+
+if (helpRequested) {
+  const help = [
+    'Usage: npx github:hyperbolictonic/opencode-anti-slop [target-dir] [--force] [--hooks]',
+    '',
+    '  target-dir  defaults to the current directory',
+    '  --force     overwrite kit files that already exist in the target',
+    '  --hooks     also install the git pre-commit gate (requires .git)',
+  ].join('\n');
+  console.log(help);
+  process.exit(0);
+}
+
+const target = path.resolve(targetArg ?? process.cwd());
+if (!existsSync(target) || !statSync(target).isDirectory()) {
+  console.error(`Target directory not found: ${target}`);
+  process.exit(1);
+}
+if (path.resolve(kitRoot) === target) {
+  console.error('Refusing to install the kit into itself.');
+  process.exit(1);
+}
+
+const copyOverwrite = (src, dest) => {
+  if (existsSync(dest) && !force) {
+    console.error(`[skip] ${dest} already exists (use --force to overwrite)`);
+    return false;
+  }
+  cpSync(src, dest, { recursive: true });
+  console.log(`[ok] ${dest}`);
+  return true;
+};
+
+// --- skills -----------------------------------------------------------------
+const skillsSrc = path.join(kitRoot, '.opencode', 'skills');
+const skillsDest = path.join(target, '.opencode', 'skills');
+mkdirSync(skillsDest, { recursive: true });
+
+for (const entry of readdirSync(skillsSrc, { withFileTypes: true })) {
+  if (entry.isDirectory() && existsSync(path.join(skillsSrc, entry.name, 'SKILL.md'))) {
+    copyOverwrite(path.join(skillsSrc, entry.name), path.join(skillsDest, entry.name));
+  }
+}
+
+// --- scripts ----------------------------------------------------------------
+const scriptsSrc = path.join(kitRoot, 'scripts', 'anti-slop');
+const scriptsDest = path.join(target, 'scripts', 'anti-slop');
+mkdirSync(path.dirname(scriptsDest), { recursive: true });
+copyOverwrite(scriptsSrc, scriptsDest);
+
+// --- CI workflow template -----------------------------------------------------
+const templateSrc = path.join(kitRoot, 'templates', 'anti-slop-ci.yml');
+const templateDest = path.join(target, '.github', 'workflows', 'anti-slop.yml');
+if (existsSync(templateSrc)) {
+  mkdirSync(path.dirname(templateDest), { recursive: true });
+  copyOverwrite(templateSrc, templateDest);
+}
+
+// --- commands ----------------------------------------------------------------
+// Copy command FILES individually so a pre-existing commands dir doesn't nest
+// (dir-into-dir copy would produce commands/commands/x.md → /commands/x).
+const commandsSrc = path.join(kitRoot, '.opencode', 'commands');
+const commandsDest = path.join(target, '.opencode', 'commands');
+mkdirSync(commandsDest, { recursive: true });
+for (const entry of readdirSync(commandsSrc, { withFileTypes: true })) {
+  if (entry.isFile() && entry.name.endsWith('.md')) {
+    copyOverwrite(path.join(commandsSrc, entry.name), path.join(commandsDest, entry.name));
+  }
+}
+
+// --- manual steps -----------------------------------------------------------
+console.log(`
+Manual setup in ${target} (one-time):
+
+1. AGENTS.md — add:
+   ${'```markdown'}
+   ## Anti-slop skills
+   - Before creating any new component, hook, or utility: load the \`reuse-before-create\` skill.
+   - When building/refactoring React UI: load \`react-composition-patterns\`.
+   - When touching state/effects/memo/context: load \`react-state-and-effects\`.
+   - Before marking any coding task complete: run the \`verify-clean-code\` checklist.
+   ${'```'}
+
+2. opencode.json (optional, makes the inventory always loaded):
+   ${'```json'}
+   { "$schema": "https://opencode.ai/config.json", "instructions": ["docs/COMPONENT_INDEX.md"] }
+   ${'```'}
+
+3. package.json scripts:
+   ${'```json'}
+   "scripts:anti-slop": {
+     "index": "node scripts/anti-slop/generate-component-index.mjs",
+     "dupes": "node scripts/anti-slop/check-duplicates.mjs"
+   }
+   ${'```'}
+   (flatten to plain keys if you prefer: "index:components", "check:dupes")
+
+4. ESLint: enable eslint-plugin-react-hooks (and the React Compiler eslint
+   plugin if the project uses the compiler) so hook misuse fails in the linter.
+
+5. Generate the first inventory:  node scripts/anti-slop/generate-component-index.mjs
+
+6. Git gates (recommended):  git init && node scripts/anti-slop/install-hooks.mjs
+   - pre-commit: modularity + docs on staged files (blocking), duplicate/import reports
+   - pre-push: full duplicate + import gates + lint/typecheck/test via --if-present
+   - /audit-ui in OpenCode produces a prioritized refactor plan from the same checks
+`);
+
+// --- optional hooks ------------------------------------------------------------
+if (wantHooks) {
+  if (!existsSync(path.join(target, '.git'))) {
+    console.error('[skip] --hooks requested but no .git directory in target; run git init first.');
+  } else {
+    const { spawnSync } = await import('node:child_process');
+    const hookScript = path.join(scriptsDest, 'install-hooks.mjs');
+    if (existsSync(hookScript)) {
+      const res = spawnSync(process.execPath, [hookScript], { stdio: 'inherit', cwd: target });
+      if (res.error) console.error(`[warn] hook installer failed: ${res.error.message}`);
+    }
+  }
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "opencode-anti-slop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "OpenCode enforcement kit: agent skills plus deterministic gates that keep AI-generated React and Node code modular, DRY, and documented",
+  "license": "MIT",
+  "type": "module",
+  "bin": "install.mjs",
+  "files": [
+    "install.mjs",
+    "templates",
+    "scripts/anti-slop",
+    ".opencode"
+  ],
+  "keywords": [
+    "opencode",
+    "ai-agents",
+    "agent-skills",
+    "claude-code",
+    "react",
+    "nodejs",
+    "typescript",
+    "code-quality",
+    "dry",
+    "technical-debt",
+    "lint",
+    "git-hooks",
+    "ci"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyperbolictonic/opencode-anti-slop.git"
+  },
+  "homepage": "https://github.com/hyperbolictonic/opencode-anti-slop#readme",
+  "bugs": "https://github.com/hyperbolictonic/opencode-anti-slop/issues",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test scripts/anti-slop/lib.test.mjs scripts/anti-slop/cli.test.mjs scripts/anti-slop/check-imports.test.mjs",
+    "gates": "node scripts/anti-slop/check-modularity.mjs --src scripts/anti-slop && node scripts/anti-slop/check-imports.mjs --src scripts && node scripts/anti-slop/check-docs.mjs --src scripts/anti-slop && node scripts/anti-slop/check-duplicates.mjs --src scripts",
+    "index": "node scripts/anti-slop/generate-component-index.mjs --src scripts"
+  }
+}

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

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * check-docs.mjs
+ *
+ * Documentation gate for shared exports. Fails (exit 1) when exported
+ * declarations in the checked files lack a one-line `/** When to use ... *\/`
+ * JSDoc above them. Keeps docs/COMPONENT_INDEX.md (generated from the same
+ * JSDoc) a maintained, trustworthy inventory instead of a stale artifact.
+ *
+ * Zero dependencies.
+ *
+ * Usage:
+ *   node scripts/anti-slop/check-docs.mjs [paths...] [--src src] [--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 undocumented code never blocks commits.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { walk, extractExports } from './lib.mjs';
+import { loadConfig, bootstrapGate, collectPathFiles, resolveScanTarget } from './cli.mjs';
+
+// Defaults < anti-slop.config.json < CLI flags.
+const cfgDocs = loadConfig().docs ?? {};
+const { args, positionals } = bootstrapGate(process.argv.slice(2), {
+  usage: 'Usage: node check-docs.mjs [paths...] [--src src] [--report-only]\n' +
+         'Config: anti-slop.config.json "docs" section (src).\n' +
+         'With path arguments, checks exactly those files (git-hook staged mode).',
+  spec: { '--src': 'string', '--report-only': 'flag' },
+  defaults: { src: cfgDocs.src ?? 'src' },
+});
+
+const files = positionals.length > 0 ? collectPathFiles(positionals) : resolveScanTarget(args.src);
+
+let missing = 0;
+const detail = [];
+for (const file of files) {
+  let exports;
+  try {
+    exports = extractExports(readFileSync(file.full, 'utf8'));
+  } catch {
+    continue;
+  }
+  const undocumented = exports.filter((e) => !e.desc && e.name !== 'default');
+  if (undocumented.length === 0) continue;
+  missing += undocumented.length;
+  detail.push({ rel: file.rel, names: undocumented.map((e) => e.name) });
+}
+
+if (missing === 0) {
+  console.log(`[ok] Docs check passed (${files.length} file(s), every export documented).`);
+  process.exit(0);
+}
+
+console.log(`${missing} undocumented export(s) in ${detail.length} file(s):`);
+for (const d of detail.slice(0, 20)) {
+  console.log(`  ${d.rel}: ${d.names.join(', ')}`);
+}
+if (detail.length > 20) console.log(`  ... and ${detail.length - 20} more file(s)`);
+
+console.error(
+  '\n[x] Docs check FAILED.\n' +
+  '    Fix: add a one-line "/** When to use ... */" JSDoc above each export —\n' +
+  '    this is what feeds docs/COMPONENT_INDEX.md, the inventory the\n' +
+  '    reuse-before-create pre-flight depends on. Do NOT delete the check or\n' +
+  '    leave the doc as a bare restatement of the name.'
+);
+process.exit(args.reportOnly ? 0 : 1);