@rtorcato/repo-tooling 3.33.0 → 3.35.0

package/dist/cli/commands/doctor.js

@@ -22,7 +22,7 @@ import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
 import { compareRulesWithReference } from '../utils/reference-rules.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, checkRecommendedMcp, checkRequiredSkills, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
-import { allDeps, checkAreTheTypesWrong, checkBiome, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
+import { allDeps, checkAreTheTypesWrong, checkBiome, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkExportsBuildable, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
 export { evaluateNodeVersion };
 const PACKAGE = '@rtorcato/repo-tooling';
 // Detects the broken-release-on-protected-main footgun: a workflow that runs
@@ -385,6 +385,8 @@ export async function runDoctor(dir, skillsDir) {
     results.push(await checkTypedoc(targetDir, pkg));
     results.push(await checkAreTheTypesWrong(targetDir, pkg));
     results.push(await checkPublint(targetDir, pkg));
+    // The setup/doctor-time half of what publint catches at release time (#578).
+    results.push(await checkExportsBuildable(targetDir, pkg));
     results.push(await checkTreeshakeSetup(targetDir, pkg));
     results.push(await checkPnpmWorkspace(targetDir, pkg));
     results.push(await checkBuildApprovals(targetDir, pkg));

package/dist/cli/generators/claude-skills.js

@@ -14,9 +14,17 @@ import { shellQuote } from '../utils/shell.js';
 import { isNewerVersion, resolveShippedVersion } from '../utils/version.js';
 /**
  * Skills this package owns the content of and keeps up to date. The loop first —
- * it is the pipeline; the other three are its drivers (burst, on-ramp, status).
+ * it is the pipeline; the next three are its drivers (burst, on-ramp, status).
+ * `dogfood` stands apart: it tests the consuming repo's own tooling rather than
+ * driving the loop, and it is the only one that writes nothing outside a temp dir.
  */
-export const SHIPPED_SKILLS = ['ai-issue-loop', 'ai-workflow', 'ai-issue', 'ai-loop-status'];
+export const SHIPPED_SKILLS = [
+    'ai-issue-loop',
+    'ai-workflow',
+    'ai-issue',
+    'ai-loop-status',
+    'dogfood',
+];
 /** The primary skill — the default everywhere a single name is accepted. */
 export const SHIPPED_SKILL = 'ai-issue-loop';
 /**

package/dist/languages/js/checks.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'fs-extra';
 import { checkFile, hookHasUncommented } from '../../base/checks.js';
+import { realGitExec } from '../../base/git-identity.js';
 import { CLAUDE_SETTINGS_FILE, readClaudeSettings, workspaceSymlinkDirs, worktreeSymlinkDirs, } from '../../cli/generators/agent-rules.js';
 import { WORKSPACE_FILE, dependsOnEsbuild, familyGlob, missingPnpmSettings, } from '../../cli/generators/pnpm-workspace.js';
 const PACKAGE = '@rtorcato/repo-tooling';
@@ -964,6 +965,202 @@ export async function checkPublint(_dir, pkg) {
         hint: 'Run `npx @rtorcato/repo-tooling fix publint` to lint your package before publishing',
     };
 }
+/**
+ * The file extensions each recognised build command drops in the output
+ * directory. Inferring this from an arbitrary shell command is inherently
+ * partial, so the table is deliberately small and anything missing from it
+ * makes the whole check stand down (see `emittedExtensions`) — a doctor check
+ * that cries wolf on a valid config is worse than one with a stated blind spot.
+ */
+const BUILD_EMITS = {
+    // tsc mirrors its input extension: .ts → .js + .d.ts. It reaches .cjs/.d.cts
+    // only from .cts sources, which is why a repo that has any stands the check
+    // down below.
+    tsc: ['.js', '.d.ts'],
+    // tsup's real set is whatever `format`/`dts` say in a config file this does
+    // not parse, so it claims the broadest set tsup could emit. A tsup build is
+    // therefore passed rather than guessed at, while `rimraf dist && tsup` still
+    // resolves instead of standing the check down.
+    tsup: ['.js', '.cjs', '.mjs', '.d.ts', '.d.cts', '.d.mts'],
+    // Cleaners emit nothing. Recognised only so the very common
+    // `rimraf dist && tsc` is still judged on its tsc half.
+    rimraf: [],
+    rm: [],
+    del: [],
+};
+/** Package-manager noise to strip before the command name: `pnpm exec tsup`. */
+const RUNNER_TOKENS = new Set([
+    'npx',
+    'npm',
+    'pnpm',
+    'yarn',
+    'bun',
+    'exec',
+    'dlx',
+    'run',
+    'x',
+    '-s',
+    '--silent',
+]);
+/**
+ * Extensions this check will judge, longest suffix first. Anything else — a
+ * package publishing `./src/index.ts` directly, a `./dist/style.css` from a
+ * non-JS step — is left alone rather than measured against a JS emit table.
+ */
+const ARTEFACT_EXTENSIONS = ['.d.cts', '.d.mts', '.d.ts', '.cjs', '.mjs', '.js'];
+function artefactExtension(p) {
+    return ARTEFACT_EXTENSIONS.find((ext) => p.endsWith(ext)) ?? null;
+}
+/**
+ * Every file path the publish contract names. Shared with the #570 regression
+ * test so doctor and that test agree on what the contract is.
+ */
+export function declaredEntryPoints(pkg) {
+    const found = [];
+    const walk = (node) => {
+        if (typeof node === 'string')
+            found.push(node);
+        else if (node && typeof node === 'object')
+            Object.values(node).forEach(walk);
+    };
+    walk(pkg.exports);
+    for (const field of ['main', 'module', 'types']) {
+        const value = pkg[field];
+        if (typeof value === 'string')
+            found.push(value);
+    }
+    return [...new Set(found)];
+}
+/**
+ * What `command` puts in the output directory, or null when any part of it is
+ * absent from BUILD_EMITS. Null means "don't know", and every caller stands
+ * down on it rather than guessing.
+ */
+function emittedExtensions(scripts, command, seen = new Set()) {
+    // Only a plain `a && b` chain is read. Pipes, `||`, subshells and redirects
+    // are not something to infer an output set from.
+    if (/[|;`<>]|\$\(/.test(command))
+        return null;
+    const emitted = new Set();
+    for (const segment of command.split('&&')) {
+        const tokens = segment.trim().split(/\s+/).filter(Boolean);
+        const before = tokens.length;
+        while (tokens.length > 0 && RUNNER_TOKENS.has(tokens[0]))
+            tokens.shift();
+        const name = tokens[0];
+        if (!name)
+            return null;
+        // `"build": "pnpm build-cli"` — one script delegating to another. Followed
+        // only when a runner was actually stripped, because a bare `tsc` runs the
+        // binary even in a repo that also happens to have a script by that name.
+        const nested = tokens.length < before ? scripts[name] : undefined;
+        if (nested !== undefined) {
+            if (seen.has(name))
+                return null;
+            seen.add(name);
+            const inner = emittedExtensions(scripts, nested, seen);
+            if (!inner)
+                return null;
+            for (const ext of inner)
+                emitted.add(ext);
+            continue;
+        }
+        const known = BUILD_EMITS[name];
+        if (!known)
+            return null;
+        for (const ext of known)
+            emitted.add(ext);
+    }
+    return [...emitted];
+}
+/**
+ * Catches a publish contract naming files the repo's own `build` cannot produce
+ * (#578) — the class of bug that shipped `main: ./dist/index.cjs` alongside
+ * `build: tsc`, which emits only .js and .d.ts, so every CJS consumer of the
+ * published package got a 404 (#570). #577 fixed the preset that wrote that
+ * pair; this catches it however else it arises, e.g. a repo editing `build` or
+ * the contract by hand afterwards.
+ *
+ * Judged from the build *script*, never from `dist/` on disk: a clean checkout
+ * has no dist/ and a stale one has whatever the last build left, so neither
+ * answers the question. Git is what separates the two kinds of path a contract
+ * may name — a tracked `./tooling/preset.mjs` ships as committed source and
+ * needs no build, while an untracked `./dist/index.cjs` has to come out of
+ * `build` or it will not exist at publish time.
+ *
+ * This overlaps publint, which the generated `verify` already runs — but not in
+ * time. publint fires at release, against a dist/ just built on a machine where
+ * it happens to work; this fires at setup/doctor time, on a checkout, before
+ * anything is built.
+ */
+export async function checkExportsBuildable(dir, pkg, exec) {
+    const check = 'Exports buildable';
+    if (!pkg || !isPublishableLibrary(pkg)) {
+        return { check, status: 'ok', detail: 'not applicable (private or no published exports)' };
+    }
+    const scripts = pkg.scripts ?? {};
+    const build = scripts.build;
+    if (!build) {
+        return { check, status: 'ok', detail: 'no build script — nothing is expected to be generated' };
+    }
+    const emitted = emittedExtensions(scripts, build);
+    if (!emitted) {
+        return {
+            check,
+            status: 'ok',
+            detail: `not checked — cannot infer what \`${build}\` emits (recognised: ${Object.keys(BUILD_EMITS).join(', ')})`,
+        };
+    }
+    const declared = declaredEntryPoints(pkg).filter((p) => artefactExtension(p));
+    if (declared.length === 0) {
+        return { check, status: 'ok', detail: 'no JS entry points named in main/module/types/exports' };
+    }
+    if (!(await fs.pathExists(path.join(dir, '.git')))) {
+        return {
+            check,
+            status: 'ok',
+            detail: 'not checked — not a git repository, so committed assets and build output are indistinguishable',
+        };
+    }
+    // Declared paths are `./dist/index.js`; git speaks `dist/index.js`.
+    const declaredByPath = new Map(declared.map((p) => [p.replace(/^\.\//, ''), p]));
+    const git = exec ?? ((args) => realGitExec(args, dir));
+    // One call answers both questions: which declared paths are committed, and
+    // whether the repo has .cts/.mts sources. Every argument is a pathspec behind
+    // `--`, so a package.json path beginning with `-` cannot become a flag.
+    const listed = await git(['ls-files', '-z', '--', ...declaredByPath.keys(), '*.cts', '*.mts']);
+    if (listed === null) {
+        return { check, status: 'ok', detail: 'not checked — `git ls-files` is unavailable here' };
+    }
+    const tracked = new Set(listed.split('\0').filter(Boolean));
+    const unbuildable = [...declaredByPath]
+        .filter(([bare]) => !tracked.has(bare))
+        .map(([, declaredPath]) => declaredPath)
+        .filter((p) => !emitted.includes(artefactExtension(p)));
+    if (unbuildable.length === 0) {
+        return {
+            check,
+            status: 'ok',
+            detail: `every declared entry point is committed or emitted by \`${build}\``,
+        };
+    }
+    // tsc emits .cjs/.d.cts from a .cts input, so its narrow BUILD_EMITS entry is
+    // wrong for a repo that has any. Checked last, and only when there is
+    // something to report, so the common repo pays nothing for it.
+    if ([...tracked].some((p) => !declaredByPath.has(p) && /\.[cm]ts$/.test(p))) {
+        return {
+            check,
+            status: 'ok',
+            detail: 'not checked — repo has .cts/.mts sources, whose emitted extensions this cannot infer',
+        };
+    }
+    return {
+        check,
+        status: 'drift',
+        detail: `\`${build}\` emits ${emitted.join(', ')}; package.json names ${unbuildable.length} entry point(s) nothing produces: ${unbuildable.join(', ')}`,
+        hint: 'The published package will 404 on those paths. Either point `build` at a bundler that emits those formats (tsup with `format: ["cjs", "esm"]`), or narrow main/module/exports to the formats the current build produces. No autofix — both directions are valid and only the package author knows which one it promises.',
+    };
+}
 /** Who this package's README badges are for — feeds the base badge check (#309). */
 export function jsBadgeAudience(pkg) {
     if (!pkg || pkg.private === true)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.33.0",
+	"version": "3.35.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [

package/skills/dogfood/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: dogfood
+description: |
+  Run this repo's own tooling against throwaway greenfield fixtures in a temp
+  directory and report what breaks. Use when the user asks to "dogfood",
+  "test the tool on a fresh repo", "see what happens on a new project", or
+  invokes `/dogfood`. Asks what to exercise before it starts. Writes only
+  under a temp directory, never touches the repo's working tree, and never
+  deletes anything — it hands the path back for the user to remove.
+---
+
+# dogfood
+
+Point the repo's own tooling at repos it has never seen and find out what it
+does wrong. Arguments: $ARGUMENTS
+
+**The bugs live where the tool meets content it did not write.** An empty
+directory finds nothing — every finding from the run this skill is based on came
+from a fixture that already had a `package.json`, a manifest, or a source file
+with an opinion in it. Scaffolding onto nothing is the one case the authors
+already tested.
+
+## What this never does
+
+- **Never writes outside its temp directory.** Not the repo's working tree, not
+  `~/.claude`, not a global git config (`git config --global` writes a stowed
+  dotfile on this machine).
+- **Never deletes.** `rm` is often permission-blocked for an agent, and a
+  half-deleted fixture is worse than a kept one. Report the path and size at the
+  end; the user removes it when they are done reading it.
+- **Never files an issue without asking**, and never labels one `ai-ready` —
+  that label is the human's gate into `ai-issue-loop`.
+
+## Step 1 — ask what to exercise
+
+Use `AskUserQuestion`. Look at the repo first so the options are real — read its
+`package.json` `bin`, its CLI's `--help`, or its presets/templates directory —
+then ask:
+
+1. **What to exercise.** Offer the actual entry points found (multiSelect).
+   For a scaffolding tool that is its presets; for a linter its rule sets; for a
+   codemod its transforms.
+2. **Fixture shape.** *Realistic pre-existing repos* (recommended — this is what
+   finds bugs) vs *empty directories* (only worth it to check the happy path
+   still works).
+3. **What to do with findings.** *Report in the transcript only* (recommended
+   for a first run) vs *also file GitHub issues*. If they choose issues, every
+   one opens with `🤖 *Filed by an agent via dogfood.*` and carries no
+   `ai-ready` label.
+
+Skip a question the arguments already answer.
+
+## Step 2 — pin the build and the version
+
+**A finding with no version stamp is unreproducible and will be argued with.**
+Build from source, and record the commit — not the version in `package.json`,
+which under semantic-release without `@semantic-release/git` never moves:
+
+```bash
+ROOT=$(git rev-parse --show-toplevel)
+cd "$ROOT" && pnpm build-cli          # or whatever CLAUDE.md says the build is
+REF=$(git -C "$ROOT" rev-parse --short HEAD)
+DIRTY=$(git -C "$ROOT" status --porcelain | head -1)
+```
+
+Say in every finding: *Reproduced with `dist/` built from `<REF>`*, and mention
+it if the tree was dirty. Invoke the built artefact directly
+(`node "$ROOT/dist/cli/index.js" …`) — never `npx <package>`, which silently
+tests the *published* version instead of the working tree.
+
+## Step 3 — make the temp root, once
+
+```bash
+BASE="${TMPDIR:-/tmp}/dogfood-$REF-$$"
+mkdir -p "$BASE"
+echo "$BASE"
+```
+
+**Pin `$BASE` as an absolute path and reuse that literal for the rest of the
+run.** `$TMPDIR` resolves differently inside and outside the command sandbox, so
+re-expanding it in a later command lands in a different directory and the run
+silently splits in two. A unique suffix means a re-run never collides, which is
+what makes never-deleting safe.
+
+## Step 4 — build each fixture, and commit it
+
+A fixture is a *plausible* repo, not a stub. Give it the things the tool will
+read and be tempted to rewrite: a real name (scoped and unscoped both matter —
+a scope is a code path), a source file, a manifest that already declares
+something, an existing script.
+
+Then **`git init` and commit it**. That baseline commit is the whole trick:
+
+```bash
+git -C "$BASE/$NAME" init -q
+git -C "$BASE/$NAME" add -A
+git -C "$BASE/$NAME" -c user.email=dogfood@local -c user.name=dogfood commit -qm baseline
+```
+
+`-c` on the command, never `git config --global`. Without the commit, "what did
+the tool overwrite" is a question nobody can answer afterwards.
+
+## Step 5 — before, run, after
+
+```bash
+node "$ROOT/dist/cli/index.js" doctor --json > "$BASE/$NAME.before.json" 2>&1 || true
+node "$ROOT/dist/cli/index.js" setup --preset <p> --yes > "$BASE/$NAME.setup.log" 2>&1; echo "exit=$?"
+node "$ROOT/dist/cli/index.js" doctor --json > "$BASE/$NAME.after.json" 2>&1 || true
+```
+
+`> file 2>&1`, in that order — `2>&1 > file` leaves stderr on the terminal, which
+is where the interesting output usually is. `|| true` because a diagnostic
+command exiting non-zero *is* data, not a reason to abort the run.
+
+## Step 6 — the three checks that actually find things
+
+Run all three on every fixture. Each one found a distinct real bug.
+
+### a. What did it overwrite?
+
+```bash
+git -C "$BASE/$NAME" diff --stat
+git -C "$BASE/$NAME" diff -- <every file the tool claims to merge rather than replace>
+```
+
+A tool that says it preserves your `name`, `version`, and scripts is making a
+promise; the diff is where you check it. This is how a preset was caught
+renaming a package after its directory and orphaning the sources — **and the
+build still exited 0**, because the build system ignored the now-undeclared
+directory. A green build is not evidence.
+
+### b. Does it pass its own check?
+
+```bash
+node "$ROOT/dist/cli/index.js" doctor; echo "exit=$?"
+```
+
+Non-zero on a repo the tool itself just created is a bug every time, however
+small the detail. "Run setup, you're aligned" either holds or the promise is
+worthless — and a user's CI or pre-commit hook keys on exactly that exit code.
+Diff `before.json` against `after.json` too: a check that *stopped* running is
+invisible in the exit code.
+
+### c. Does the contract it wrote actually hold?
+
+The subtlest class, and the most damaging. The tool writes a *declaration* —
+`exports`, `main`, entry points, a target list — and separately preserves a
+*producer* — the build script. Nothing checks that the producer emits what the
+declaration promises. So:
+
+```bash
+cd "$BASE/$NAME" && <the repo's own build> && ls -R dist 2>/dev/null
+```
+
+then read the manifest and confirm every path it names exists on disk. A package
+whose `main` points at a file its own `build` cannot emit publishes green and
+breaks every consumer.
+
+## Step 7 — report
+
+Per fixture, one short block: preset, exit codes, and each finding as
+*what happened → why it matters → the evidence*. Paste the diff hunk or the JSON
+line; a paraphrase is not a reproduction.
+
+Rank by **silence, not severity**. A loud failure gets noticed by whoever hits
+it. A wrong result that exits 0 does not, and that is the finding worth the
+user's attention — lead with it.
+
+If the user chose to file issues, one issue per finding, ≤30 lines each: what,
+the minimal reproduction, the version stamp, and a `## What to change` section
+that names the options rather than picking one. Attach no `ai-ready`.
+
+**Say what you could not test.** A preset you skipped, a build you could not
+run, an area still in flight — an unexamined corner reported as unexamined is
+useful; one left silent reads as covered.
+
+## Step 8 — hand back the temp directory
+
+Last line of the run, always:
+
+```bash
+du -sh "$BASE"
+```
+
+Tell the user the path and the size, and give them the exact command:
+
+```
+! rm -rf <BASE>
+```
+
+The `!` prefix runs it in their session. Do not run it yourself, do not offer to
+run it later, and do not delete it on a subsequent invocation — the fixtures are
+the evidence behind every finding, and they are worth more than the disk.
+
+## Gotchas that cost real time
+
+- **Shell aliases corrupt captured output.** `ls` aliased to a colouriser emits
+  escape codes into anything you parse. `unalias ls` / `unalias g` first, or use
+  `command ls`.
+- **Ambient `GIT_DIR` / `GIT_WORK_TREE` / `GIT_CONFIG*` outrank `-C`.** If any is
+  exported, every fixture git command silently operates on the wrong repo.
+  `env -u GIT_DIR -u GIT_WORK_TREE git …` when in doubt.
+- **A function, not a variable, for a wrapped command.** `G="env -u X git"` does
+  not word-split under zsh; define `g() { env -u X git "$@"; }`.
+- **`pnpm install` may need the sandbox disabled** — it writes to a store outside
+  the working directory. That is a legitimate escalation for this one command.
+- **Never reuse a fixture between runs.** A second `setup` over an
+  already-set-up repo tests idempotency, which is a different question; mixing
+  the two makes both answers unreliable.