@rtorcato/repo-tooling 3.13.1 → 3.14.0

package/AGENTS.md

@@ -95,6 +95,8 @@ npx @rtorcato/repo-tooling fix claude-skills --yes --json
 
 Fixers marked `explicitOnly` are exempt from `fix` all *and* from `fix --yes` — they only run when named as the target. Today that is `claude-skills`, the one fixer whose blast radius is outside the repo.
 
+A fixer may also **refuse** — the target file holds something the generator cannot reproduce, so overwriting would destroy it. Today that is `dependabot` against a config with repo-local `ignore:` rules (#422). A targeted `fix dependabot` then exits 1 with `error: dependabot-ignore-rules`; a bulk `fix --yes` records it `skipped` and carries on with the rest. Neither `--yes` nor `--json` overrides it — resolve the named rules by hand and re-run.
+
 ## Source-of-truth files in the repo
 
 - `src/cli/commands/setup.ts` — `ProjectConfig` interface and the setup orchestrator

package/dist/base/checks.js

@@ -3,6 +3,7 @@ import fs from 'fs-extra';
 import { BLOCK_START, hasStaleAgentBlock } from '../cli/generators/agent-rules.js';
 import { BADGE_START, hasPublicOnlyBadges } from '../cli/generators/badges.js';
 import { claudeSkillStatus, SHIPPED_SKILL } from '../cli/generators/claude-skills.js';
+import { DEPENDABOT_CONFIG_PATHS, dependabotIgnoreRules } from '../cli/generators/security.js';
 import { detectNestedLanguages } from '../cli/utils/detect-language.js';
 /**
  * Root-only detection is the decision (#317), not an oversight — but it used to
@@ -235,7 +236,7 @@ export async function checkGitHubActions(dir, preset = null) {
     }
 }
 export async function checkDependabot(dir) {
-    for (const candidate of ['.github/dependabot.yml', '.github/dependabot.yaml']) {
+    for (const candidate of DEPENDABOT_CONFIG_PATHS) {
         const candidatePath = path.join(dir, candidate);
         if (await fs.pathExists(candidatePath)) {
             // The canonical standard (apps/docs/docs/guides/dependabot-strategy.md) is
@@ -250,21 +251,39 @@ export async function checkDependabot(dir) {
                 }
             }
             const automergePath = path.join(dir, '.github', 'workflows', 'dependabot-automerge.yml');
-            if (!(await fs.pathExists(automergePath))) {
+            if (await fs.pathExists(automergePath)) {
+                // Pre-#423 workflows gated on the semver type alone, so production
+                // bumps of a published package merged with nobody in the loop. The
+                // canonical gate also requires the dev-minor group.
+                const automerge = await fs.readFile(automergePath, 'utf8');
+                if (!automerge.includes("dependency-group == 'dev-minor'")) {
+                    deltas.push('auto-merge workflow merges production bumps (missing dev-minor group gate)');
+                }
+            }
+            else {
                 deltas.push('missing dependabot-automerge workflow');
             }
+            // Repo-local `ignore:` rules aren't drift — they're deliberate, and the
+            // canonical config has no way to express them. Report them anyway so the
+            // reason `fix dependabot` refuses is visible before anyone runs it (#422).
+            const ignored = dependabotIgnoreRules(content);
+            const ignoreNote = ignored.length === 0
+                ? ''
+                : ` — ${ignored.length} local \`ignore:\` rule(s) the canonical config cannot express (${ignored.join(', ')}); \`fix dependabot\` refuses rather than drop them`;
             if (deltas.length > 0) {
                 return {
                     check: 'Dependabot',
                     status: 'drift',
-                    detail: `${candidate} drifts from canonical (${deltas.join('; ')})`,
-                    hint: 'Run `npx @rtorcato/repo-tooling fix dependabot` to apply the canonical grouping + auto-merge workflow',
+                    detail: `${candidate} drifts from canonical (${deltas.join('; ')})${ignoreNote}`,
+                    hint: ignored.length > 0
+                        ? 'Run `npx @rtorcato/repo-tooling fix dependabot --diff` — it will refuse until the `ignore:` block is dealt with by hand'
+                        : 'Run `npx @rtorcato/repo-tooling fix dependabot` to apply the canonical grouping + auto-merge workflow',
                 };
             }
             return {
                 check: 'Dependabot',
                 status: 'ok',
-                detail: `${candidate} + auto-merge workflow`,
+                detail: `${candidate} + auto-merge workflow${ignoreNote}`,
             };
         }
     }

package/dist/base/fixers.js

@@ -21,7 +21,8 @@ import { generateBrand } from '../cli/generators/brand.js';
 import { generateCommunityHealth } from '../cli/generators/community-health.js';
 import { generateCommitlintConfig } from '../cli/generators/git.js';
 import { generateCodeowners, generateEditorConfig } from '../cli/generators/misc.js';
-import { generateCodeQLWorkflow, generateDependabotConfig, generateRenovateConfig, } from '../cli/generators/security.js';
+import { findDependabotIgnoreRules, generateCodeQLWorkflow, generateDependabotConfig, generateRenovateConfig, } from '../cli/generators/security.js';
+import { classifyCopiedAssets } from '../cli/utils/copied-assets.js';
 import { copyPreset } from '../cli/utils/copy-preset.js';
 import { detectLanguage } from '../cli/utils/detect-language.js';
 import { resolveLanguageModule } from '../languages/registry.js';
@@ -75,6 +76,24 @@ async function resolveInstallDir(explicit, assumeYes) {
     return trimmed ? path.resolve(trimmed) : null;
 }
 export const BASE_FIXERS = [
+    {
+        target: 'copied-assets',
+        description: 'Re-copy presets that are unchanged since they were copied but older than the version this package ships',
+        appliesTo: ['Copied assets'],
+        outputs: ['(the stale copied presets, re-copied in place)'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            // Only the `stale` ones: their content provably still matches what was
+            // copied, so overwriting loses nothing. `modified` assets are somebody's
+            // deliberate fork and stay a human decision (#428).
+            const stale = (await classifyCopiedAssets(targetDir)).filter((a) => a.state === 'stale');
+            const filesWritten = [];
+            for (const asset of stale) {
+                filesWritten.push((await copyPreset(asset.preset, targetDir)).target);
+            }
+            return { filesWritten };
+        },
+    },
     {
         target: 'editorconfig',
         description: 'Scaffold .editorconfig (UTF-8, LF, tab indent)',
@@ -112,6 +131,16 @@ export const BASE_FIXERS = [
         outputs: ['.github/dependabot.yml', '.github/workflows/dependabot-automerge.yml'],
         canFixDrift: true,
         async run({ targetDir }) {
+            // The template owns the whole file but emits no `ignore:` block, so
+            // regenerating deletes any repo-local ignore rule — silently, and with
+            // nothing in `doctor` to report the loss afterwards, because from the
+            // fixer's point of view the file then matches the standard exactly (#422).
+            // Refuse rather than warn: an unattended `fix --yes` would walk past a
+            // warning, and the rules are unrecoverable once written over.
+            const ignored = await findDependabotIgnoreRules(targetDir);
+            if (ignored) {
+                throw new FixerAbort('dependabot-ignore-rules', `refusing to overwrite ${ignored.file} — it has ${ignored.rules.length} \`ignore:\` rule(s) the canonical config does not reproduce: ${ignored.rules.join(', ')}`, `re-add the \`ignore:\` block after regenerating, or delete it from ${ignored.file} to accept the loss — then re-run \`fix dependabot\``);
+            }
             const { dependabotEcosystem } = await moduleFor(targetDir);
             return { filesWritten: await generateDependabotConfig(targetDir, dependabotEcosystem) };
         },

package/dist/base/github-settings.js

@@ -51,11 +51,15 @@ export const GITHUB_STANDARD = {
     requiredContexts: ['lint', 'typecheck', 'build', 'test'],
 };
 const CODE_SCANNING_CHECK = 'Code-scanning gate';
+const RELEASE_GATE_CHECK = 'Release gate';
+const RELEASE_ENV_CHECK = 'Release environment';
 const CHECK_NAMES = [
     'Branch protection',
     'Merge settings',
     'Workflow permissions',
     CODE_SCANNING_CHECK,
+    RELEASE_GATE_CHECK,
+    RELEASE_ENV_CHECK,
 ];
 // Recommended CodeQL alert thresholds — GitHub's UI defaults. This is the
 // override surface: bump them here for a stricter/looser fleet-wide baseline.
@@ -143,6 +147,7 @@ export async function checkGitHubSettings(dir, exec) {
         checkMergeSettings(info),
         await checkWorkflowPermissions(gh, info.nwo),
         await checkCodeScanningRuleset(gh, info.nwo, info.branch, dir),
+        ...(await checkReleaseGate(gh, info.nwo, dir)),
     ];
 }
 function probeFailureReason(probe) {
@@ -425,6 +430,270 @@ async function checkCodeScanningRuleset(gh, nwo, branch, dir) {
             : 'Run `npx @rtorcato/repo-tooling fix github-settings` to add a code_scanning branch ruleset that blocks merge on High+ CodeQL alerts',
     };
 }
+// --- Release environment gate (#429) --------------------------------------
+/** The environment name the standard reserves for the publish gate. */
+const RELEASE_ENVIRONMENT = 'release';
+/**
+ * What a job has to run for a merge to the default branch to reach a registry.
+ * `semantic-release` counts on its own — the shipped preset publishes with it.
+ */
+const PUBLISH_COMMAND = /semantic-release|changesets\/action|(?:npm|pnpm|yarn)\s+publish/;
+const GATE_HINT = 'Create a `release` environment with required reviewers (Settings → Environments) and add `environment: release` to the publishing job — a merge to the default branch then leaves the run `waiting` instead of publishing';
+const ENV_HINT = 'Add `environment: release` to the publishing job, or delete the environment — whichever was meant. An environment nothing references still lists under Settings → Environments as though it gates something';
+const unquote = (s) => s.replace(/^['"]|['"]$/g, '');
+/**
+ * A workflow's `jobs:` blocks, keyed by job id.
+ *
+ * Hand-split rather than parsed: this package ships no YAML dependency, and the
+ * only question asked of the result is whether *one particular job* carries an
+ * `environment:` key. A whole-file grep would answer that wrong on any repo with
+ * a `github-pages` deploy job — which is the exact false negative this check
+ * exists to avoid. Jobs sit one indent level under `jobs:` and their keys one
+ * level below that, which holds for every workflow Actions accepts.
+ */
+export function workflowJobs(yaml) {
+    const jobs = new Map();
+    const lines = yaml.split('\n');
+    const start = lines.findIndex((l) => /^jobs:\s*$/.test(l));
+    if (start === -1)
+        return jobs;
+    const indentOf = (l) => l.length - l.trimStart().length;
+    // The block runs until the next top-level key. A column-0 comment is not one —
+    // it ends nothing, so skipping it keeps a stray comment between `jobs:` and its
+    // first job from truncating the block and hiding every job below it.
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        const l = lines[i] ?? '';
+        if (l.trim() !== '' && !l.trimStart().startsWith('#') && indentOf(l) === 0) {
+            end = i;
+            break;
+        }
+    }
+    const body = lines.slice(start + 1, end);
+    const first = body.find((l) => l.trim() !== '' && !l.trimStart().startsWith('#'));
+    if (first === undefined)
+        return jobs;
+    const jobIndent = indentOf(first);
+    let id = null;
+    let buf = [];
+    for (const line of body) {
+        const header = line.trim() !== '' && indentOf(line) === jobIndent
+            ? /^([\w.-]+):/.exec(line.trim())?.[1]
+            : undefined;
+        if (header) {
+            if (id)
+                jobs.set(id, buf.join('\n'));
+            id = header;
+            buf = [];
+        }
+        else if (id) {
+            buf.push(line);
+        }
+    }
+    if (id)
+        jobs.set(id, buf.join('\n'));
+    return jobs;
+}
+/**
+ * The environment a job runs in, in either form Actions accepts: the scalar
+ * `environment: release`, or a block whose `name:` names it. Null when the job
+ * declares none.
+ */
+export function jobEnvironment(body) {
+    const inline = /^[ \t]*environment:[ \t]*(\S+)[ \t]*$/m.exec(body);
+    if (inline?.[1])
+        return unquote(inline[1]);
+    const at = body.search(/^[ \t]*environment:[ \t]*$/m);
+    if (at === -1)
+        return null;
+    // Step names are list items (`- name:`), so the first bare `name:` after the
+    // block opener is the environment's.
+    const name = /^[ \t]*name:[ \t]*(\S+)/m.exec(body.slice(at))?.[1];
+    return name ? unquote(name) : null;
+}
+/**
+ * A job body with whole-line comments dropped. Same reasoning as
+ * `hookHasUncommented` in base/checks.ts: a `#` line runs nothing, so matching
+ * it is a false positive. Observed on this repo's own ci.yml, where a `varcheck`
+ * job carrying `# npm publish uses OIDC trusted publishing` was reported as the
+ * publishing job. Comments are stripped rather than pattern-tested because
+ * `jobEnvironment` needs the same treatment — a commented-out `environment:`
+ * would otherwise read as a live gate, the exact inversion of this check.
+ */
+function withoutComments(body) {
+    return body
+        .split('\n')
+        .filter((line) => !line.trimStart().startsWith('#'))
+        .join('\n');
+}
+/** `private: true` — nothing reaches a registry, so no gate is owed. */
+async function isPrivatePackage(dir) {
+    try {
+        const pkg = await fs.readJson(path.join(dir, 'package.json'));
+        return pkg?.private === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The first workflow job that runs a publish command, or null if none does.
+ *
+ * `'skip'` when the directory exists but can't be read — a permission error or a
+ * broken symlink must not read as "nothing publishes", which would report the
+ * gate as `ok` on a repo whose workflows were never inspected. Same shape as
+ * `readEnvironments`: absent is an answer, unreadable is not.
+ */
+async function findPublishJob(dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (!(await fs.pathExists(workflowsDir)))
+        return null;
+    try {
+        for (const f of (await fs.readdir(workflowsDir)).sort()) {
+            if (!/\.ya?ml$/.test(f))
+                continue;
+            const content = await fs.readFile(path.join(workflowsDir, f), 'utf-8');
+            if (!PUBLISH_COMMAND.test(content))
+                continue;
+            for (const [job, raw] of workflowJobs(content)) {
+                const body = withoutComments(raw);
+                if (PUBLISH_COMMAND.test(body)) {
+                    return { file: f, job, environment: jobEnvironment(body) };
+                }
+            }
+        }
+    }
+    catch {
+        return 'skip';
+    }
+    return null;
+}
+async function readEnvironments(gh, nwo) {
+    const r = await gh(['api', `repos/${nwo}/environments`]);
+    // A repo with no environments can answer 404 — that's "none", not unreadable.
+    if (!r.ok)
+        return /404|not found/i.test(r.stderr) ? new Map() : 'skip';
+    try {
+        const parsed = JSON.parse(r.stdout);
+        const envs = new Map();
+        for (const e of parsed.environments ?? []) {
+            if (typeof e.name !== 'string')
+                continue;
+            envs.set(e.name, (e.protection_rules ?? []).some((p) => p.type === 'required_reviewers'));
+        }
+        return envs;
+    }
+    catch {
+        return 'skip';
+    }
+}
+/**
+ * The gap between merging the default branch and publishing to npm (#429). On
+ * the shipped semantic-release preset those are one event: nothing stands
+ * between a squash-merge and a new version on the registry.
+ *
+ * Two checks, because they fail differently and want different answers:
+ *
+ * - **Release gate** — the publishing job runs behind no environment at all, or
+ *   behind one that isn't really a gate (absent, or with no required reviewers).
+ * - **Release environment** — the repo *has* a `release` environment and no job
+ *   references it. That's the failure mode worth catching: an unreferenced
+ *   environment gates nothing while reading as a gate in the GitHub UI.
+ *
+ * The two never both fire on one repo. "No `environment:` and no `release`
+ * environment" is the gate check's; "no `environment:` but a `release`
+ * environment exists" is the environment check's, and the gate check defers.
+ *
+ * A repo that publishes nothing is `ok` — not applicable, not drift. There is
+ * no fixer: creating the environment needs a `required_reviewers` list only a
+ * human can supply, so both hints describe the manual step.
+ */
+async function checkReleaseGate(gh, nwo, dir) {
+    const publish = (await isPrivatePackage(dir)) ? null : await findPublishJob(dir);
+    if (publish === 'skip') {
+        const reason = 'could not read .github/workflows';
+        return [skip(RELEASE_GATE_CHECK, reason), skip(RELEASE_ENV_CHECK, reason)];
+    }
+    if (!publish) {
+        const detail = 'not applicable — no workflow job publishes to a registry';
+        return [
+            { check: RELEASE_GATE_CHECK, status: 'ok', detail },
+            { check: RELEASE_ENV_CHECK, status: 'ok', detail },
+        ];
+    }
+    const envs = await readEnvironments(gh, nwo);
+    if (envs === 'skip') {
+        const reason = 'could not read environments';
+        return [skip(RELEASE_GATE_CHECK, reason), skip(RELEASE_ENV_CHECK, reason)];
+    }
+    const named = publish.environment;
+    const where = `${publish.file} \`${publish.job}\``;
+    const hasRelease = envs.has(RELEASE_ENVIRONMENT);
+    let gate;
+    if (named === null) {
+        gate = hasRelease
+            ? {
+                check: RELEASE_GATE_CHECK,
+                status: 'ok',
+                detail: `${where} declares no environment — reported by the ${RELEASE_ENV_CHECK} check`,
+            }
+            : {
+                check: RELEASE_GATE_CHECK,
+                status: 'drift',
+                detail: `${where} publishes with no \`environment:\` and the repo has no \`${RELEASE_ENVIRONMENT}\` environment — anything that lands on the default branch publishes`,
+                hint: GATE_HINT,
+            };
+    }
+    else if (!envs.has(named)) {
+        gate = {
+            check: RELEASE_GATE_CHECK,
+            status: 'drift',
+            detail: `${where} names the \`${named}\` environment, which the repo does not have — Actions creates it unprotected on first run, so the publish is never held`,
+            hint: GATE_HINT,
+        };
+    }
+    else if (!envs.get(named)) {
+        gate = {
+            check: RELEASE_GATE_CHECK,
+            status: 'drift',
+            detail: `the \`${named}\` environment has no required_reviewers — ${where} passes straight through it`,
+            hint: GATE_HINT,
+        };
+    }
+    else {
+        gate = {
+            check: RELEASE_GATE_CHECK,
+            status: 'ok',
+            detail: `${where} runs behind the \`${named}\` environment (required reviewers)`,
+        };
+    }
+    let environment;
+    if (!hasRelease) {
+        environment = {
+            check: RELEASE_ENV_CHECK,
+            status: 'ok',
+            detail: `no \`${RELEASE_ENVIRONMENT}\` environment — nothing to reference`,
+        };
+    }
+    else if (named === RELEASE_ENVIRONMENT) {
+        environment = {
+            check: RELEASE_ENV_CHECK,
+            status: 'ok',
+            detail: `${where} references the \`${RELEASE_ENVIRONMENT}\` environment`,
+        };
+    }
+    else {
+        environment = {
+            check: RELEASE_ENV_CHECK,
+            status: 'drift',
+            detail: named
+                ? `the repo has a \`${RELEASE_ENVIRONMENT}\` environment but ${where} runs in \`${named}\` — \`${RELEASE_ENVIRONMENT}\` gates nothing while still reading as a gate in the GitHub UI`
+                : `the repo has a \`${RELEASE_ENVIRONMENT}\` environment but ${where} references no environment — it gates nothing while still reading as a gate in the GitHub UI`,
+            hint: ENV_HINT,
+        };
+    }
+    return [gate, environment];
+}
 /** The branch-protection body PUT to the API — mirrors the doctor standard. */
 const PROTECTION_BODY = JSON.stringify({
     required_status_checks: { strict: false, contexts: GITHUB_STANDARD.requiredContexts },

package/dist/cli/commands/doctor.js

@@ -15,6 +15,7 @@ import { detectLanguage } from '../utils/detect-language.js';
 import { checkGitHubSettings } from '../../base/github-settings.js';
 import { checkMilestones } from '../../base/milestones.js';
 import { checkGitIdentity } from '../../base/git-identity.js';
+import { checkCopiedAssets } from '../utils/copied-assets.js';
 import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
 import { declinedInLock, getFixTargetForCheck } from './fix-targets.js';
 import { checkAiSetup, checkBrand, checkCodeowners, checkClaudeSkills, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
@@ -150,6 +151,9 @@ function demoteDeclined(results, lock) {
 async function runBaseChecks(dir, lock, opts) {
     const results = [];
     results.push(checkLockfile(lock));
+    // Any language can have copied presets (swiftlint, ruff, perlcriticrc), so
+    // this rides with the base suite rather than a module's (#428).
+    results.push(await checkCopiedAssets(dir));
     results.push(await checkNestedLanguages(dir, opts.language));
     results.push(await checkGitIdentity(dir));
     results.push(await checkEditorConfig(dir));

package/dist/cli/commands/fix-targets.js

@@ -47,6 +47,7 @@ export const FIX_TARGETS = {
     'AI setup': 'ai',
     'Claude worktree settings': 'ai',
     'Claude skills': 'claude-skills',
+    'Copied assets': 'copied-assets',
 };
 /**
  * Where the Swift module's fixers shadow (or extend) the JS-named defaults

package/dist/cli/commands/fix.js

@@ -133,7 +133,17 @@ async function previewFixer(fixer, result, targetDir, pkg, lock) {
             },
         });
         // assumeYes: a preview must never prompt.
-        await fixer.run({ targetDir: tmpDir, pkg, result, lock, assumeYes: true });
+        try {
+            await fixer.run({ targetDir: tmpDir, pkg, result, lock, assumeYes: true });
+        }
+        catch (err) {
+            // A fixer that refuses has nothing to preview. Swallow it here rather than
+            // reporting it twice — the real run happens moments later and its abort is
+            // what the caller prints.
+            if (!(err instanceof FixerAbort))
+                throw err;
+            return [];
+        }
         const previews = [];
         const seen = new Set();
         for (const output of fixer.outputs) {
@@ -398,10 +408,9 @@ export async function fixCommand(target, options = {}) {
             console.log(chalk.gray('   skipped\n'));
             return;
         }
-        // ponytail: only the targeted path is guarded, because the only fixer that
-        // aborts is `claude-skills` and it is explicitOnly — the bulk loop below
-        // cannot reach it. A non-explicitOnly fixer that throws FixerAbort would
-        // surface as an unhandled rejection there; guard the loop when one exists.
+        // A targeted abort is fatal: the user named this fixer, so failing to run it
+        // is the whole outcome of the command. The bulk loop below takes the other
+        // branch and records a skip, since one refusal must not abandon the rest.
         const outcome = await applyFixer(fixer, effectiveResult, targetDir, pkg, lock, dryRun, silent, {
             skillsDir: options.skillsDir,
             assumeYes,
@@ -471,10 +480,27 @@ export async function fixCommand(target, options = {}) {
             skippedCount++;
             continue;
         }
-        const outcome = await applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent, {
-            skillsDir: options.skillsDir,
-            assumeYes,
-        });
+        // A fixer that refuses (e.g. dependabot, when the existing config carries
+        // repo-local `ignore:` rules the template can't reproduce) is a skip, not a
+        // crash — the remaining findings still deserve their fixers. The reason goes
+        // to stderr so it survives `--json`.
+        let outcome;
+        try {
+            outcome = await applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent, {
+                skillsDir: options.skillsDir,
+                assumeYes,
+            });
+        }
+        catch (err) {
+            if (!(err instanceof FixerAbort))
+                throw err;
+            actions.push(recordFor(fixer.target, result.check, result.status, 'skipped', [], conflict));
+            console.error(chalk.red(`    refused — ${err.message}`));
+            if (err.hint)
+                console.error(chalk.gray(`    ${err.hint}`));
+            skippedCount++;
+            continue;
+        }
         actions.push(recordFor(fixer.target, result.check, result.status, outcome.dryRun ? 'dry-run' : 'applied', outcome.filesWritten, conflict));
         appliedCount++;
     }

package/dist/cli/generators/security.js

@@ -29,13 +29,16 @@ export function dependabotConfig(ecosystem) {
       prefix: chore
       include: scope
     groups:
-      # Safe tier: runtime + dev minor/patch auto-merge on green (see the
-      # dependabot-automerge workflow). Grouped so react/react-dom move together.
+      # Runtime minor/patch. Grouped so react/react-dom move together, but NOT
+      # auto-merged — these ship to consumers of a published package, so they
+      # get a human (see the dependabot-automerge workflow).
       production-minor:
         dependency-type: production
         update-types:
           - minor
           - patch
+      # The only tier that auto-merges on green — dev tooling never reaches a
+      # consumer of the published package.
       dev-minor:
         dependency-type: development
         update-types:
@@ -62,11 +65,71 @@ ${manifest}  - package-ecosystem: github-actions
 /** The JS flavour — the historical default, kept for the generators that don't
  * resolve a language module. */
 export const DEPENDABOT_CONFIG = dependabotConfig('npm');
+/** Where `.github/dependabot.yml` can live, in the order Dependabot resolves it. */
+export const DEPENDABOT_CONFIG_PATHS = [
+    '.github/dependabot.yml',
+    '.github/dependabot.yaml',
+];
+/**
+ * The `ignore:` rules an existing dependabot.yml carries, named by
+ * `dependency-name` (#422).
+ *
+ * `dependabotConfig()` owns the whole file but emits no `ignore:` block, and
+ * `ignore` is precisely the key that is inherently repo-local — a pin held back
+ * by hand, with the reason usually in a comment above it. So every rule this
+ * finds is one a regeneration would delete silently.
+ *
+ * ponytail: a line scanner, not a YAML parse — the repo ships no YAML parser and
+ * this only needs to answer "is there something here to lose, and what is it
+ * called". A rule split across lines (`-` alone, `dependency-name` beneath)
+ * reports as `<unnamed rule>`, which still stops the overwrite. Reach for a
+ * parser if the message ever has to reproduce the rules rather than name them.
+ */
+export function dependabotIgnoreRules(content) {
+    const lines = content.split('\n');
+    const rules = [];
+    for (const [index, line] of lines.entries()) {
+        const header = /^(\s*)ignore:\s*(#.*)?$/.exec(line);
+        if (!header)
+            continue;
+        const blockIndent = (header[1] ?? '').length;
+        // Rules sit at the first list indent under `ignore:`; deeper `- ` lines are
+        // an entry's own values (`update-types:`) and must not count as rules.
+        let itemIndent = null;
+        const names = [];
+        let items = 0;
+        for (const next of lines.slice(index + 1)) {
+            if (next.trim() === '')
+                continue;
+            const indent = next.search(/\S/);
+            if (indent <= blockIndent)
+                break;
+            if (/^\s*-\s/.test(next)) {
+                itemIndent ??= indent;
+                if (indent === itemIndent)
+                    items++;
+            }
+            const named = /(?:^|\s)dependency-name:\s*["']?([^"'#\s]+)/.exec(next);
+            if (named?.[1] && (itemIndent === null || indent >= itemIndent))
+                names.push(named[1]);
+        }
+        while (names.length < items)
+            names.push('<unnamed rule>');
+        rules.push(...names);
+    }
+    return rules;
+}
 /**
- * Auto-merges patch + minor Dependabot PRs once CI is green. Requires branch
- * protection with required status checks on the target branch — without it,
- * \`gh pr merge --auto\` never fires. Majors are excluded (they land in the
- * major-updates group for manual triage).
+ * Auto-merges patch + minor Dependabot PRs **from the `dev-minor` group only**
+ * once CI is green. Requires branch protection with required status checks on
+ * the target branch — without it, \`gh pr merge --auto\` never fires.
+ *
+ * Everything else falls through to a human: production bumps ship to consumers
+ * of a published package (#423), majors are breaking by definition, and an
+ * ungrouped PR reports an empty \`dependency-group\`, so the gate fails closed.
+ *
+ * The group name is the one \`dependabotConfig()\` writes — the two files are a
+ * paired unit and have to move together.
  */
 export const DEPENDABOT_AUTOMERGE_WORKFLOW = `name: Dependabot auto-merge
 
@@ -87,10 +150,14 @@ jobs:
         with:
           github-token: \${{ secrets.GITHUB_TOKEN }}
 
-      - name: Auto-merge patch and minor updates
+      # Belt and braces: the dev-minor group is already declared minor+patch in
+      # dependabot.yml, but this workflow is the security gate and shouldn't
+      # trust a config file a consumer repo can edit independently.
+      - name: Auto-merge dev-dependency patch and minor updates
         if: |
-          steps.metadata.outputs.update-type == 'version-update:semver-patch' ||
-          steps.metadata.outputs.update-type == 'version-update:semver-minor'
+          steps.metadata.outputs.dependency-group == 'dev-minor' &&
+          (steps.metadata.outputs.update-type == 'version-update:semver-patch' ||
+          steps.metadata.outputs.update-type == 'version-update:semver-minor')
         run: gh pr merge --auto --squash "$PR_URL"
         env:
           PR_URL: \${{ github.event.pull_request.html_url }}
@@ -101,6 +168,20 @@ export const DEPENDABOT_FILES = [
     '.github/dependabot.yml',
     '.github/workflows/dependabot-automerge.yml',
 ];
+/**
+ * The repo-local `ignore:` rules a regeneration would delete, with the file
+ * they live in — or null when there is nothing to lose (#422).
+ */
+export async function findDependabotIgnoreRules(targetDir) {
+    for (const file of DEPENDABOT_CONFIG_PATHS) {
+        const candidate = path.join(targetDir, file);
+        if (!(await fs.pathExists(candidate)))
+            continue;
+        const rules = dependabotIgnoreRules(await fs.readFile(candidate, 'utf8'));
+        return rules.length > 0 ? { file, rules } : null;
+    }
+    return null;
+}
 /**
  * Scaffold the canonical Dependabot setup: the grouped \`dependabot.yml\` **and**
  * the auto-merge workflow. They're a paired unit — the config batches updates

package/dist/cli/utils/copied-assets.js

@@ -0,0 +1,79 @@
+/**
+ * Drift detection for copied presets (#428).
+ *
+ * `copy <preset>` used to be a one-shot: it wrote the file and nothing ever
+ * looked at it again, so eight copies of `sync-changelog.mjs` drifted into six
+ * versions with no signal. The fix is one recorded fact — the asset's pristine
+ * hash at copy time, in `.repo-tooling.json` — which is enough to separate the
+ * two cases that matter:
+ *
+ * - file ≠ recorded hash → `modified`. Someone edited it on purpose (js-common
+ *   forked this very script and documented why in its header). Reported, never
+ *   overwritten, never counted as drift.
+ * - file = recorded hash, but the shipped asset has moved on → `stale`. Nothing
+ *   local is in it, so re-copying is lossless.
+ * - no recorded hash → `unknown`. Copies predating this, and repos with no
+ *   lockfile at all. Absence of a record is not evidence of drift, so this
+ *   never fails a build.
+ */
+import path from 'node:path';
+import { getPackageRoot, hashFile, PRESETS } from './copy-preset.js';
+import { readLockfile } from './lockfile.js';
+/**
+ * Classify every preset whose target file exists in `dir`. Presets that were
+ * never copied here are absent from the result rather than reported missing —
+ * `copy` is opt-in, and doctor already has checks for the files that aren't.
+ */
+export async function classifyCopiedAssets(dir) {
+    const lock = await readLockfile(dir);
+    const packageRoot = getPackageRoot();
+    const statuses = [];
+    for (const name of Object.keys(PRESETS)) {
+        const preset = PRESETS[name];
+        const current = await hashFile(path.join(dir, preset.target));
+        if (current === null)
+            continue;
+        const recorded = lock?.assets?.[name];
+        // Unmodified since the copy, so whether it's stale is purely a question of
+        // what this package ships now. A source we can't read (shouldn't happen)
+        // falls back to the recorded hash — "no news", not drift.
+        const shipped = recorded
+            ? ((await hashFile(path.join(packageRoot, preset.source))) ?? recorded)
+            : null;
+        let state = 'ok';
+        if (!recorded)
+            state = 'unknown';
+        else if (recorded !== current)
+            state = 'modified';
+        else if (shipped !== recorded)
+            state = 'stale';
+        statuses.push({ preset: name, target: preset.target, state });
+    }
+    return statuses;
+}
+const listOf = (s) => s.map((a) => a.preset).join(', ');
+export async function checkCopiedAssets(dir) {
+    const check = 'Copied assets';
+    const all = await classifyCopiedAssets(dir);
+    if (all.length === 0) {
+        return { check, status: 'optional-missing', detail: 'no copied presets found' };
+    }
+    const by = (state) => all.filter((a) => a.state === state);
+    const stale = by('stale');
+    const modified = by('modified');
+    const unknown = by('unknown');
+    const parts = [`${by('ok').length} in sync`];
+    if (modified.length > 0)
+        parts.push(`${modified.length} locally modified: ${listOf(modified)}`);
+    if (unknown.length > 0)
+        parts.push(`${unknown.length} untracked: ${listOf(unknown)}`);
+    if (stale.length === 0) {
+        return { check, status: 'ok', detail: parts.join('; ') };
+    }
+    return {
+        check,
+        status: 'drift',
+        detail: `${stale.length} stale: ${listOf(stale)}; ${parts.join('; ')}`,
+        hint: 'Run `npx @rtorcato/repo-tooling fix copied-assets` to re-copy them. They still match what was copied, so nothing local is lost — locally modified assets are left alone.',
+    };
+}

package/dist/cli/utils/copy-preset.js

@@ -1,5 +1,7 @@
+import { createHash } from 'node:crypto';
 import path from 'node:path';
 import fs from 'fs-extra';
+import { recordAssetHash } from './lockfile.js';
 export const PRESETS = {
     biome: {
         source: 'tooling/biome/biome.json',
@@ -97,6 +99,11 @@ export const PRESETS = {
         target: 'scripts/sync-changelog.mjs',
         desc: 'Canonical CHANGELOG → docs sync script for Docusaurus sites',
     },
+    'docusaurus-docs-helpers': {
+        source: 'tooling/docusaurus/docs-helpers.mjs',
+        target: 'scripts/docs-helpers.mjs',
+        desc: 'Docs-generator helpers (markdown-table escaping, export parser, generated-block splice)',
+    },
     'docusaurus-theme-tokens': {
         source: 'tooling/docusaurus/theme-tokens.css',
         target: 'apps/docs/src/css/_jt-tokens.css',
@@ -112,6 +119,17 @@ export function getPackageRoot() {
     const cliFile = new URL(import.meta.url).pathname;
     return path.dirname(path.dirname(path.dirname(path.dirname(cliFile))));
 }
+/** sha256 of a file's bytes, or null when it doesn't exist / can't be read. */
+export async function hashFile(filepath) {
+    try {
+        return createHash('sha256')
+            .update(await fs.readFile(filepath))
+            .digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
 export async function copyPreset(name, targetDir = process.cwd()) {
     const preset = PRESETS[name];
     const packageRoot = getPackageRoot();
@@ -124,6 +142,11 @@ export async function copyPreset(name, targetDir = process.cwd()) {
         if (legacyPath !== targetPath)
             await fs.remove(legacyPath);
     }
+    // Stamp what was copied, so doctor can later tell a local edit from a copy
+    // the package has moved past (#428). No-ops when the repo has no lockfile.
+    const hash = await hashFile(sourcePath);
+    if (hash)
+        await recordAssetHash(targetDir, name, hash);
     return {
         source: preset.source,
         target: preset.target,

package/dist/cli/utils/lockfile.js

@@ -13,12 +13,14 @@ export const LEGACY_TOOL_NAME = 'js-tooling';
 export const LEGACY_LOCKFILE_NAME = `.${LEGACY_TOOL_NAME}.json`;
 // v2 added ProjectConfig.language (multi-language seam, #140). v1 files are
 // migrated to v2 on read, defaulting language to 'js'.
-export const LOCKFILE_VERSION = 2;
+// v3 added `assets` — the pristine hash of each copied preset (#428). Older
+// files carry no hashes, which reads as "not tracked", never as drift.
+export const LOCKFILE_VERSION = 3;
 const LOCKFILE_SCHEMA_URL = 'https://rtorcato.github.io/repo-tooling/schemas/lockfile.json';
 /**
  * Upgrade an older lockfile in-memory. Only touches files older than the
  * current version, so a newer-than-supported file is left as-is for
- * checkLockfile to flag. The file is rewritten to v2 next time it's saved.
+ * checkLockfile to flag. The file is rewritten to v3 next time it's saved.
  */
 function migrate(lock) {
     if (lock.version >= LOCKFILE_VERSION)
@@ -27,6 +29,7 @@ function migrate(lock) {
         ...lock,
         version: LOCKFILE_VERSION,
         config: { language: 'js', ...lock.config },
+        assets: lock.assets ?? {},
     };
 }
 export async function readLockfile(dir) {
@@ -53,16 +56,23 @@ export async function readLockfile(dir) {
         return null;
     }
 }
-export async function writeLockfile(dir, config) {
+/**
+ * @param assets Recorded asset hashes to write. Omit to carry the existing
+ *   file's hashes forward — every caller that only means to update `config`
+ *   would otherwise silently drop them.
+ */
+export async function writeLockfile(dir, config, assets) {
     const { valid, errors } = validateProjectConfig(config);
     if (!valid) {
         throw new Error(`Refusing to write invalid lockfile:\n  - ${errors.join('\n  - ')}`);
     }
+    const carried = assets ?? (await readLockfile(dir))?.assets;
     const filepath = path.join(dir, LOCKFILE_NAME);
     const lockfile = {
         $schema: LOCKFILE_SCHEMA_URL,
         version: LOCKFILE_VERSION,
         config,
+        ...(carried && Object.keys(carried).length > 0 ? { assets: carried } : {}),
         writtenBy: `@rtorcato/repo-tooling@${packageJson.version}`,
         writtenAt: new Date().toISOString(),
     };
@@ -86,3 +96,16 @@ export async function updateLockfileConfig(dir, patch) {
     await writeLockfile(dir, merged);
     return true;
 }
+/**
+ * Record the pristine hash of a just-copied preset (#428). Returns false when
+ * the repo has no lockfile — four family repos don't, and creating one as a
+ * side effect of `copy` would be a surprise. Those repos keep reporting the
+ * asset as untracked, which is the honest answer.
+ */
+export async function recordAssetHash(dir, preset, hash) {
+    const existing = await readLockfile(dir);
+    if (!existing)
+        return false;
+    await writeLockfile(dir, existing.config, { ...existing.assets, [preset]: hash });
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.13.1",
+	"version": "3.14.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [
@@ -87,6 +87,7 @@
 		"tooling/docusaurus/index.mjs",
 		"tooling/docusaurus/index.d.mts",
 		"tooling/docusaurus/sync-changelog.mjs",
+		"tooling/docusaurus/docs-helpers.mjs",
 		"tooling/docusaurus/theme-tokens.css",
 		"tooling/docusaurus/theme.css",
 		"tooling/biome/biome.json",

package/skills/ai-issue-loop/SKILL.md

@@ -60,6 +60,8 @@ header names the agent *and* says why it is wearing a human's face:
 | `ai-wip` | issue | Claimed; a worktree exists. |
 | `ai-blocked` | issue | Agent gave up; needs a human. |
 | `ai-review` | PR | Awaiting agent review. |
+| `ai-reviewing-code` | PR | `code-reviewer` claimed and running. Cleared with its verdict. |
+| `ai-reviewing-sec` | PR | `security-expert` claimed and running. Cleared with its verdict. |
 | `ai-ok-code` | PR | `code-reviewer` passed. |
 | `ai-ok-sec` | PR | `security-expert` passed. |
 | `ai-changes` | PR | A reviewer requested changes. |
@@ -86,6 +88,8 @@ gh label create ai-ready    -c '#0e8a16' -d 'Eligible for an AI agent to impleme
 gh label create ai-wip     -c '#fbca04' -d 'Claimed by an agent; worktree exists'
 gh label create ai-blocked -c '#b60205' -d 'Agent gave up; needs a human'
 gh label create ai-review  -c '#1d76db' -d 'PR awaiting agent review'
+gh label create ai-reviewing-code -c '#c5def5' -d 'code-reviewer claimed and running'
+gh label create ai-reviewing-sec  -c '#c5def5' -d 'security-expert claimed and running'
 gh label create ai-ok-code -c '#0e8a16' -d 'code-reviewer passed'
 gh label create ai-ok-sec  -c '#0e8a16' -d 'security-expert passed'
 gh label create ai-changes -c '#d93f0b' -d 'Reviewer requested changes'
@@ -100,14 +104,19 @@ grep -qxF '.claude/ai-loop-status' .gitignore || echo '.claude/ai-loop-status' >
 
 ```
 issue: ai-ready ─pickup─> ai-wip ─> PR opened, labelled ai-review
-PR: ai-review ─> reviewers ─┬─> ai-ok-code + ai-ok-sec ─┬─ issue PR  ─> assigned to you, ai-review dropped
-                            │        (± ai-notes)       │              ─> YOU merge ─> worktree removed
-                            │                           └─ dependabot ─┬─ no ai-notes ─> auto-merge ─> worktree removed
-                            │                                          └─ ai-notes ───> assigned to you
-                            └─> ai-changes ─> fix round (max 2) ─> ai-review
-                                                        └─ round 3 ─> ai-blocked
+PR: ai-review ─> ai-reviewing-* ─┬─> ai-ok-code + ai-ok-sec ─┬─ issue PR  ─> assigned to you, ai-review dropped
+                                 │        (± ai-notes)       │              ─> YOU merge ─> worktree removed
+                                 │                           └─ dependabot ─┬─ no ai-notes ─> auto-merge ─> worktree removed
+                                 │                                          └─ ai-notes ───> assigned to you
+                                 └─> ai-changes ─> fix round (max 2) ─> ai-review
+                                                             └─ round 3 ─> ai-blocked
 ```
 
+`ai-reviewing-code` / `ai-reviewing-sec` are the *claim* step: Pass 3 applies one
+immediately before spawning that reviewer, and the reviewer clears its own
+alongside its verdict label. They are transient — a claim outliving its reviewer
+means the agent died, which is Pass 2's stall reaping, not a state of the PR.
+
 Only the Dependabot arm merges itself, and only when no reviewer left `ai-notes`.
 An issue PR ends at *assigned to you* and waits there — `ai-ok-code, ai-ok-sec`
 with no `ai-review` is the loop's way of saying done. Add `ai-notes` and it means
@@ -374,7 +383,7 @@ work must never be reaped out from under itself.
 | Stalled | Condition | Do |
 |---|---|---|
 | Implementer died | issue `ai-wip` ≥45min, **and no PR exists** for `ai-<N>-<slug>` | `gh issue edit <N> --add-label ai-blocked --remove-label ai-wip --add-assignee @me`, comment, remove the worktree |
-| Reviewer died | PR `ai-review` ≥45min with no `ai-ok-*` and no `ai-changes` | re-spawn the missing reviewer — they're cheap and diff-scoped. If `ai-review` has been applied ≥3 times, `ai-blocked` instead |
+| Reviewer died | PR `ai-reviewing-code` (or `ai-reviewing-sec`) ≥45min with no matching `ai-ok-*` and no `ai-changes` | `gh pr edit <N> --remove-label <the claim that stalled>` — drop **that** label, not a fixed one; a stalled `ai-reviewing-sec` cleared as `ai-reviewing-code` leaves the dead claim in place and the reviewer never re-spawns. Dropping the claim is what lets Pass 3 re-spawn it, and they're cheap and diff-scoped. If that claim has been applied ≥3 times, `ai-blocked` instead |
 | Orphan worktree | `"$WT_ROOT"/ai-<N>-*` whose issue is not `ai-wip` and has no open PR | remove the worktree and branch |
 
 The **no PR exists** condition on the first row is what makes reaping safe. An
@@ -404,8 +413,34 @@ means *a human must look*; do not spend it on a claim you already understand.
 
 **PRs labelled `ai-review`.** For each, spawn *in background* only the reviewers
 whose pass-label is missing — `code-reviewer` if no `ai-ok-code`,
-`security-expert` if no `ai-ok-sec`. Both can run concurrently; launch them in a
-single message.
+`security-expert` if no `ai-ok-sec` — and **only those not already claimed**: skip
+`code-reviewer` if the PR carries `ai-reviewing-code`, `security-expert` if it
+carries `ai-reviewing-sec`. Both can run concurrently; launch them in a single
+message.
+
+**Claim first, then spawn** — the same shape Pass 4 uses before picking up an
+issue. Apply the label immediately before the spawn, not after:
+
+```bash
+gh pr edit <N> --add-label ai-reviewing-code   # then spawn code-reviewer
+gh pr edit <N> --add-label ai-reviewing-sec    # then spawn security-expert
+```
+
+Without the claim there is no window in which "a reviewer is running" is visible.
+A reviewer applies its verdict label only at the *end*, after reading the diff and
+posting its comment, so from spawn until then the labels are indistinguishable
+from "nobody has started" — and a 15-minute tick is comfortably shorter than a
+review. A tick landing in that gap spawns a duplicate of every reviewer in flight:
+two agents read the same diff and post two review comments under the owner's
+avatar, and the verdicts race, one applying `ai-ok-code` while the other applies
+`ai-changes` and leaves the PR contradictory for Pass 1 to interpret. On a 4-PR
+queue that is 8 duplicated reviewers against the monthly cap the limits section
+exists to protect.
+
+Two labels rather than one, because the reviewers are spawned independently and a
+single flag could not say *which* was already running. The reviewer clears its own
+claim alongside its verdict, so a claim never outlives its run; if one does, the
+agent died and Pass 2's stall reaping drops it.
 
 Reviewer prompt template:
 
@@ -452,9 +487,14 @@ Reviewer prompt template:
 > restating the diff. Writing `Nothing.` is a real verdict and the common one —
 > say it plainly rather than padding the section to look thorough.
 >
-> Then apply exactly one verdict label:
-> - Clean, or only nit-level suggestions → `gh pr edit <N> --add-label <ai-ok-code|ai-ok-sec>`
-> - A real defect a maintainer would block on → `gh pr edit <N> --add-label ai-changes --remove-label ai-review`
+> Then apply exactly one verdict label, **clearing your claim label in the same
+> command**:
+> - Clean, or only nit-level suggestions → `gh pr edit <N> --add-label <ai-ok-code|ai-ok-sec> --remove-label <ai-reviewing-code|ai-reviewing-sec>`
+> - A real defect a maintainer would block on → `gh pr edit <N> --add-label ai-changes --remove-label ai-review --remove-label <ai-reviewing-code|ai-reviewing-sec>`
+>
+> Pass 3 applied that claim label immediately before spawning you, and skips
+> spawning a second of you for as long as it is set. Leaving it behind wedges your
+> half of the review until Pass 2 reaps it as a dead reviewer.
 >
 > And **additionally**, if and only if your `### Before merging` section is not
 > `Nothing.`:
@@ -537,7 +577,10 @@ package/from/to table survives because it sits at the top; classify from that.
 > State in your comment which rule fired, name the packages that tripped it, and say
 > whether the body was truncated so the reader knows what you could and couldn't see.
 > Same `🤖 *Automated review — …*` header line, same closing `### Before merging`
-> section, and same one-verdict-label rule as above.
+> section, and same one-verdict-label rule as above — **including clearing your
+> `<ai-reviewing-code|ai-reviewing-sec>` claim label in the same `gh pr edit`**.
+> Pass 3 claimed you with it before spawning you, and a claim left behind wedges
+> your half of the review until Pass 2 reaps it.
 >
 > Be sparing with `ai-notes` here specifically: it suppresses auto-merge, so a
 > reflexive note on every dependency bump wedges the one path that runs

package/tooling/docusaurus/docs-helpers.mjs

@@ -0,0 +1,109 @@
+// Canonical docs-generator helpers for @rtorcato/* repos (shipped by
+// @rtorcato/repo-tooling — copy via `repo-tooling copy docusaurus-docs-helpers`).
+//
+// The pure pieces every subpath-exports package's doc generator needs, so the
+// generator script above them stays small and project-specific:
+//
+//   escapeForMarkdownTable(text)          — make a JSDoc summary safe for a table cell
+//   collectExportNames(file)              — recursive `export` parser over a module graph
+//   spliceGeneratedBlock(existing, block) — rewrite only the fenced generated region
+//
+// Zero-config and side-effect free: no paths, no package names, no I/O beyond
+// reading the files you hand it, so this file is copied unmodified.
+//
+//   import {
+//     collectExportNames,
+//     escapeForMarkdownTable,
+//     MARKER_END,
+//     MARKER_START,
+//     spliceGeneratedBlock,
+//   } from './docs-helpers.mjs'
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+const EXPORT_NAMED =
+	/export\s+(?:async\s+)?(?:function|const|let|class|type|interface|enum)\s+([A-Za-z_$][\w$]*)/g
+const EXPORT_BRACE = /export\s*\{\s*([^}]+)\}/g
+// Both re-export forms, any specifier — `export * from …` and
+// `export { … } from …`. Non-relative specifiers are filtered below rather than
+// in the pattern, so a bare-package re-export is recognised and then skipped
+// instead of silently parsed as nothing.
+const REEXPORT_FROM = /export\s+(?:\*|\{[^}]*\})\s+from\s+['"]([^'"]+)['"]/g
+
+/**
+ * Escape `text` so it survives a markdown table cell.
+ *
+ * Neutralises raw HTML-ish tags outside code spans, which would otherwise
+ * confuse Docusaurus's MDX parser — but keeps them inside backticks, where
+ * `Success<T>` and `<br>` are the point. Then escapes pipes everywhere, since
+ * one anywhere in the cell breaks the row.
+ *
+ * Escaping the `<` beats stripping `/<[^>]*>/`: a one-pass tag strip can leave
+ * a tag behind on nested input (`<<b>>` -> `<b>`) and silently eats text like
+ * `Success<T>` when the JSDoc forgot the backticks.
+ *
+ * Escape the backslash in the same pass as the pipe, not after it: escaping
+ * only `|` turns the input `a\|b` into `a\\|b`, which markdown reads as an
+ * escaped backslash followed by a live pipe, and the row breaks anyway.
+ */
+export function escapeForMarkdownTable(text) {
+	return text
+		.split(/(`[^`]*`)/)
+		.map((part, i) => (i % 2 === 1 ? part : part.replace(/</g, '&lt;')))
+		.join('')
+		.replace(/[\\|]/g, '\\$&')
+}
+
+/**
+ * Collect every name `file` exports, following relative re-exports into the
+ * files they name. Returns the accumulating `names` set; `seen` guards against
+ * an import cycle re-entering a file.
+ *
+ * For an aliased export the *alias* is the exported name — `export { foo as
+ * bar }` exports `bar`, which is what a consumer imports — so this takes the
+ * last segment, not the first.
+ */
+export function collectExportNames(file, names = new Set(), seen = new Set()) {
+	if (seen.has(file) || !existsSync(file)) return names
+	seen.add(file)
+	const src = readFileSync(file, 'utf8')
+
+	for (const m of src.matchAll(EXPORT_NAMED)) names.add(m[1])
+	for (const m of src.matchAll(EXPORT_BRACE)) {
+		for (const part of m[1].split(',')) {
+			const name = part
+				.trim()
+				.split(/\s+as\s+/)
+				.pop()
+				?.trim()
+			if (name) names.add(name)
+		}
+	}
+	for (const m of src.matchAll(REEXPORT_FROM)) {
+		if (!m[1].startsWith('.')) continue
+		const base = resolve(dirname(file), m[1].replace(/\.js$/, ''))
+		for (const candidate of [`${base}.ts`, `${base}.tsx`, join(base, 'index.ts')]) {
+			if (existsSync(candidate)) {
+				collectExportNames(candidate, names, seen)
+				break
+			}
+		}
+	}
+	return names
+}
+
+export const MARKER_START =
+	'<!-- generated:exports — do not edit; `pnpm docs:generate` rewrites this block -->'
+export const MARKER_END = '<!-- /generated:exports -->'
+
+/**
+ * Splice `block` into `existing` between the markers. Returns null when the
+ * page has no markers, which means "hand-written, leave it alone".
+ */
+export function spliceGeneratedBlock(existing, block) {
+	const start = existing.indexOf(MARKER_START)
+	const end = existing.indexOf(MARKER_END)
+	if (start === -1 || end === -1 || end < start) return null
+	return existing.slice(0, start) + block + existing.slice(end + MARKER_END.length)
+}