simt-dev 0.6.2 → 0.7.0

package/src/hooks/dispatcher.mjs

@@ -19,30 +19,200 @@
 //   its reason, so "passed" can never be mistaken for "only some of it passed".
 
 import { execFile } from 'node:child_process';
-import { readFile, stat } from 'node:fs/promises';
-import { basename, join, resolve, sep } from 'node:path';
+import { mkdtemp, readFile, rm, stat, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join, matchesGlob, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
 
 import { GATES } from './gates.mjs';
 import { resolveGate } from './resolve.mjs';
+import { resolveNodeRunner } from '../ecosystem/node-runner.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import { assertVersionPin } from '../package-version.mjs';
 import { recordRun } from '../ledger/index.mjs';
+import { renderFindings, scanStaged } from '../secrets.mjs';
 
 const exec = promisify(execFile);
 
 /** Gates that are known but not required for the event to pass. */
 const DEFAULT_EVENTS = { 'pre-commit': 'preCommit', 'pre-push': 'prePush' };
 
+/** The sha git writes for a ref that does not exist on the remote yet. */
+const ZERO_SHA = '0'.repeat(40);
+
+/**
+ * The lines git feeds a pre-push hook on stdin, one per ref being pushed:
+ * `<local ref> <local sha> <remote ref> <remote sha>`.
+ *
+ * Returns `{ refs, error }`. A line this parser cannot read is an ERROR, not a
+ * dropped line: a push that cannot be read is a push that cannot be classified,
+ * and the classifier's contract is to fail closed to the full suite.
+ *
+ * @param {string} text the raw stdin
+ * @returns {{refs: {ref: string, localSha: string, remoteSha: string}[] | null, error: string | null}}
+ */
+export function parsePushedRefs(text) {
+  const refs = [];
+  for (const line of String(text ?? '').split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    const parts = trimmed.split(' ');
+    if (parts.length !== 4) return { refs: null, error: `unrecognized pre-push line: ${trimmed}` };
+    const [ref, localSha, , remoteSha] = parts;
+    if (!/^[0-9a-f]{40}$/.test(localSha) || !/^[0-9a-f]{40}$/.test(remoteSha)) {
+      return { refs: null, error: `unrecognized sha in pre-push line: ${trimmed}` };
+    }
+    refs.push({ ref, localSha, remoteSha });
+  }
+  return { refs, error: null };
+}
+
+/**
+ * Confirm a tag's commit is already accounted for, so the tag may ride along in a
+ * docs-only push (ADR-113). A tag carries no commits of its own in the release flow:
+ * it points at commits delivered (and tested) by a branch push. It is acceptable only
+ * when the commit it names is reachable from a remote-tracking ref (already pushed) or
+ * from a branch tip this same push is delivering. Any uncertainty - the tag does not
+ * resolve to a commit, the remote refs cannot be listed, no candidate is known, or the
+ * commit is unreachable from all of them - fails closed to the full suite.
+ *
+ * @param {string} root the repository to ask git
+ * @param {string} tagSha the tag's local sha from the pre-push line
+ * @param {string[]} pushingTips branch tips this same push is delivering
+ * @returns {Promise<{ok: boolean, reason: string | null}>}
+ */
+async function tagCommitAccountedFor(root, tagSha, pushingTips) {
+  let commit;
+  try {
+    ({ stdout: commit } = await exec('git', ['rev-parse', `${tagSha}^{commit}`], { cwd: root }));
+  } catch (error) {
+    return { ok: false, reason: `the tag could not be resolved to a commit: ${String(error.stderr ?? error.message).trim()}` };
+  }
+  commit = commit.trim();
+
+  let remoteRefs;
+  try {
+    ({ stdout: remoteRefs } = await exec('git', ['for-each-ref', 'refs/remotes/', '--format=%(refname)'], { cwd: root }));
+  } catch (error) {
+    return { ok: false, reason: `the remote refs could not be listed: ${String(error.stderr ?? error.message).trim()}` };
+  }
+  const candidates = [
+    ...remoteRefs.split('\n').map((s) => s.trim()).filter((s) => s !== ''),
+    ...pushingTips,
+  ];
+  if (candidates.length === 0) {
+    return { ok: false, reason: 'no remote refs are known and no branch is being pushed, so the tag’s commit cannot be confirmed as already delivered' };
+  }
+  for (const candidate of candidates) {
+    try {
+      await exec('git', ['merge-base', '--is-ancestor', commit, candidate], { cwd: root });
+      return { ok: true, reason: null };
+    } catch {
+      // not reachable from this ref; try the next candidate
+    }
+  }
+  return { ok: false, reason: `the tag’s commit (${commit.slice(0, 7)}) is not reachable from any pushed ref; it may not have been tested` };
+}
+
+/**
+ * Decide whether a push carries only documentation, so the `test` gate may be
+ * skipped for it (ADR-113). Every uncertainty fails closed to `{ docsOnly: false }`
+ * with the reason the full suite runs: an empty ref list, a new branch (no remote
+ * sha to diff against), a tag whose commit is not confirmed already delivered, a
+ * commit count above the ceiling, a file outside the declared paths, or a git error.
+ *
+ * Branch refs are judged on a TREE diff (`remote..local`), so a force push that
+ * drops commits is judged on the trees it replaces, not on the commit count alone.
+ * Tag refs carry no commits of their own; each is accepted only when its commit is
+ * already accounted for (see `tagCommitAccountedFor`). Deletions push nothing.
+ *
+ * @param {string} root the repository to ask git
+ * @param {{ref: string, localSha: string, remoteSha: string}[]} refs
+ * @param {{maxCommits: number, paths: string[]}} config the manifest's `gates.prePushSkipTest`
+ * @returns {Promise<{docsOnly: boolean, reason: string}>}
+ */
+export async function classifyPush(root, refs, { maxCommits, paths }) {
+  if (refs.length === 0) {
+    return { docsOnly: false, reason: 'the push carries no readable ref list; running the full suite' };
+  }
+  const deletions = refs.filter((r) => r.localSha === ZERO_SHA).length;
+  const branches = refs.filter((r) => r.localSha !== ZERO_SHA && !r.ref.startsWith('refs/tags/'));
+  const tags = refs.filter((r) => r.localSha !== ZERO_SHA && r.ref.startsWith('refs/tags/'));
+
+  let commits = 0;
+  const files = new Set();
+  for (const { ref, localSha, remoteSha } of branches) {
+    if (remoteSha === ZERO_SHA) {
+      return { docsOnly: false, reason: `a new branch is being pushed (${ref}); its history cannot be diffed against the remote` };
+    }
+    let count, names;
+    try {
+      ({ stdout: count } = await exec('git', ['rev-list', '--count', `${remoteSha}..${localSha}`], { cwd: root }));
+      ({ stdout: names } = await exec('git', ['diff', '--name-only', `${remoteSha}..${localSha}`], { cwd: root }));
+    } catch (error) {
+      return { docsOnly: false, reason: `the push could not be diffed: ${String(error.stderr ?? error.message).trim()}` };
+    }
+    commits += Number(count.trim());
+    for (const f of names.split('\n')) {
+      const name = f.trim();
+      if (name !== '') files.add(name);
+    }
+  }
+
+  const pushingTips = branches.map((b) => b.localSha);
+  for (const { localSha } of tags) {
+    const verdict = await tagCommitAccountedFor(root, localSha, pushingTips);
+    if (!verdict.ok) return { docsOnly: false, reason: verdict.reason };
+  }
+
+  if (commits > maxCommits) {
+    return { docsOnly: false, reason: `${commits} commits exceed the ${maxCommits}-commit ceiling for a docs-only push` };
+  }
+  const outside = [...files].filter((f) => !paths.some((p) => matchesGlob(f, p)));
+  if (outside.length > 0) {
+    return { docsOnly: false, reason: `${outside.length} file(s) are outside the docs-only paths: ${outside.slice(0, 5).join(', ')}` };
+  }
+
+  const parts = [];
+  if (commits > 0) parts.push(`${commits} commit(s) touching ${files.size} file(s), all inside the docs-only paths`);
+  if (tags.length > 0) parts.push(`${tags.length} tag(s) already delivered`);
+  if (deletions > 0) parts.push(`${deletions} ref deletion(s)`);
+  return { docsOnly: true, reason: parts.length > 0 ? parts.join('; ') : 'no commits carried' };
+}
+
+/**
+ * The pre-push skip decision, from the manifest and the ref list git fed on stdin.
+ *
+ * The skip is OPT-IN: a repository without `gates.prePushSkipTest` runs the full
+ * suite on every push, because a control a repo did not declare is one it did not
+ * review. A misdeclaration (missing fields) also runs the suite - a skip the
+ * manifest cannot state precisely is a skip a reviewer cannot see.
+ *
+ * @returns {Promise<{reason: string} | null>} null runs the suite; a reason skips the `test` gate
+ */
+async function resolveDocsOnlySkip(root, manifest, pushed) {
+  if (pushed === undefined) return null;
+  const config = manifest?.gates?.prePushSkipTest;
+  if (typeof config?.maxCommits !== 'number' || !Array.isArray(config?.paths)) return null;
+  const { refs, error } = parsePushedRefs(pushed);
+  if (error !== null) {
+    return null; // the caller cannot be sure what is being pushed; the suite runs
+  }
+  const verdict = await classifyPush(root, refs, { maxCommits: config.maxCommits, paths: config.paths });
+  return verdict.docsOnly ? { reason: verdict.reason } : null;
+}
+
 /**
  * @param {string} event 'pre-commit' | 'pre-push'
  * @param {object} ctx
  * @param {string} ctx.root
  * @param {object} ctx.manifest parsed simt-dev.json, or null
+ * @param {string} [ctx.pushed] the ref list git feeds pre-push on stdin; undefined when no
+ *   push is being classified (every other event, a manual run with no stdin)
  * @returns {Promise<{event: string, gates: object[], failed: boolean}>}
  */
-export async function runGates(event, { root, manifest }) {
+export async function runGates(event, { root, manifest, pushed }) {
   const key = DEFAULT_EVENTS[event];
   if (key === undefined) {
     return { event, gates: [], failed: true, error: `unknown hook event ${event}` };
@@ -83,7 +253,89 @@ export async function runGates(event, { root, manifest }) {
     };
   }
 
+  // A pre-push gate runs against the COMMITTED tree, not the working one. Uncommitted
+  // work must not block the push of previous commits: a gate that fails on WIP the
+  // author has not committed is blocking a push it does not own. The worktree is
+  // disposable and shares the repository's object store, so `git worktree add` is cheap
+  // and needs no clone. The ledger and the version pin stay at the real root - the
+  // evidence is about this repository, not the throwaway checkout.
+  let runRoot = root;
+  let headWorktree = null;
+  let skipTest = null;
+  if (event === 'pre-push') {
+    // Decided before the worktree exists: a push that carries only documentation
+    // skips the `test` gate (ADR-113), and a push that earns the skip needs no
+    // tree for a gate that will not run.
+    skipTest = await resolveDocsOnlySkip(root, manifest, pushed);
+    if (skipTest === null) {
+      const materialized = await materializeHeadWorktree(root);
+      if (materialized.path === null) {
+        return {
+          event,
+          gates: [
+            {
+              name: 'head',
+              status: 'failed',
+              detail: materialized.error,
+              remedy: 'commit the work, or resolve the git state so HEAD is a valid reference, then push again',
+              adr: null,
+            },
+          ],
+          failed: true,
+        };
+      }
+      runRoot = materialized.path;
+      headWorktree = materialized.path;
+    }
+  }
+
+  try {
+    return await runGatesAt(event, { root: runRoot, ledgerRoot: root, manifest, declared, key, skipTest });
+  } finally {
+    if (headWorktree !== null) await removeHeadWorktree(root, headWorktree);
+  }
+}
+
+/**
+ * Run the declared gates at `root`, recording evidence at `ledgerRoot`.
+ *
+ * For a pre-push run the two differ: the gates execute in a throwaway worktree at
+ * HEAD so uncommitted work cannot block the push, while the ledger line belongs to
+ * the repository the author is standing in. For every other event they are the same
+ * path, which is why this is one function with two names for the root rather than
+ * two functions.
+ *
+ * @param {string} event
+ * @param {object} ctx
+ * @param {string} ctx.root the tree the gates execute in
+ * @param {string} ctx.ledgerRoot the repository the evidence is recorded in
+ * @param {object} ctx.manifest
+ * @param {string[]} ctx.declared the gate names for this event
+ * @param {string} ctx.key the manifest key for this event
+ * @param {{reason: string} | null} [ctx.skipTest] set when a docs-only push skips the
+ *   `test` gate (ADR-113); the reason is what the report prints in its place
+ * @returns {Promise<{event: string, gates: object[], failed: boolean}>}
+ */
+async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, skipTest = null }) {
   const pkg = await readPkg(root);
+  // Q31: the runner is committed evidence (lockfile, then `packageManager`),
+  // resolved once per hook run so every script gate spawns the same manager.
+  let runner = null;
+  if (pkg) {
+    const lockfiles = [];
+    for (const file of ['pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb', 'package-lock.json']) {
+      try {
+        await stat(join(root, file));
+        lockfiles.push(file);
+      } catch {
+        // Absent is the normal case.
+      }
+    }
+    runner = resolveNodeRunner({
+      lockfiles,
+      packageManager: typeof pkg.packageManager === 'string' ? pkg.packageManager : null,
+    }).id;
+  }
   const staged = event === 'pre-commit' ? await stagedFiles(root) : [];
   const unstaged = event === 'pre-commit' ? await unstagedFiles(root) : new Set();
   const commands = manifest?.gates?.commands;
@@ -110,7 +362,15 @@ export async function runGates(event, { root, manifest }) {
       continue;
     }
 
-    const resolution = await resolveGate(gate, { root, pkg, staged, commands });
+    // The one gate a docs-only push does not run (ADR-113). It is reported, not
+    // dropped: a skip without a printed reason would let "passed" mean "the suite
+    // never ran", which is the exact confusion the report exists to prevent.
+    if (skipTest !== null && name === 'test') {
+      results.push({ name, status: 'skipped', detail: `docs-only push: ${skipTest.reason}`, adr: 'ADR-113', exitCode: null });
+      continue;
+    }
+
+    const resolution = await resolveGate(gate, { root, pkg, staged, commands, runner });
     if (!resolution.ok) {
       results.push({
         name,
@@ -121,6 +381,41 @@ export async function runGates(event, { root, manifest }) {
       });
       continue;
     }
+
+    // A built-in gate runs here, in this process: no script, no command, no
+    // tool on disk (ADR-100). It gets the same ledger line and the same
+    // fail-closed reporting as every other gate; only the source of the bytes
+    // it runs over differs. Keyed on the RESOLUTION rather than the gate, so a
+    // declared command for this name takes the shell path below instead.
+    if (resolution.builtin !== undefined) {
+      const startedBuiltin = Date.now();
+      // The manifest's per-builtin options, where a builtin has any: the secret
+      // scan takes its ignore globs from gates.secretScan (review 0003 Q24).
+      const outcome = await runBuiltinGate(resolution.builtin, { root, staged, options: manifest?.gates?.secretScan });
+      try {
+        await recordRun(ledgerRoot, {
+          cmd: `builtin:${resolution.builtin}`,
+          exit: outcome.ok ? 0 : 1,
+          ms: Date.now() - startedBuiltin,
+          output: outcome.output,
+          gate: name,
+          kind: 'builtin',
+        });
+      } catch {
+        // Recorded by absence: the next evidence read for this tree has no line.
+      }
+      results.push({
+        name,
+        status: outcome.ok ? 'passed' : 'failed',
+        detail: outcome.detail,
+        output: outcome.ok ? '' : outcome.output,
+        ...(outcome.remedy !== undefined ? { remedy: outcome.remedy } : {}),
+        adr: gate.adr,
+        exitCode: outcome.ok ? 0 : 1,
+      });
+      continue;
+    }
+
     if (resolution.argv === null) {
       results.push({ name, status: 'skipped', detail: resolution.detail, adr: gate.adr, exitCode: null });
       continue;
@@ -187,11 +482,18 @@ export async function runGates(event, { root, manifest }) {
     // claim check then finds nothing, which is the direction that cannot invent a run.
     try {
       const cmd = typeof resolution.command === 'string' ? resolution.command : resolution.argv.join(' ');
-      await recordRun(root, {
+      // The evidence claim needs the gate and its kind: a passing secret-scan is
+      // not a passing test run (review 0003 Q18). Coverage proves tests; anything
+      // else keeps its own kind or the gate name.
+      const kind =
+        name === 'test' || name === 'coverage' ? 'test' : name === 'lint' ? 'lint' : name === 'format' ? 'format' : (gate.kind ?? name);
+      await recordRun(ledgerRoot, {
         cmd,
         exit: outcome.code,
         ms: Date.now() - started,
         output: `${outcome.stdout ?? ''}\n${outcome.stderr ?? ''}`,
+        gate: name,
+        kind,
       });
     } catch {
       // Recorded by absence: the next evidence read for this tree has no line.
@@ -241,15 +543,141 @@ export async function runGates(event, { root, manifest }) {
   return { event, gates: results, failed: results.some((r) => r.status === 'failed') };
 }
 
-async function run(argv, cwd) {
+/**
+ * Materialize a detached worktree at HEAD so the pre-push gates run against the
+ * committed tree, not the working one. The worktree shares the repository's object
+ * store, so `git worktree add` is cheap and needs no clone. `node_modules` is
+ * symlinked in when the real root has one, because a script gate resolves its runner
+ * and binaries from there and a fresh worktree does not carry it.
+ *
+ * Fails closed: an unborn HEAD (no commits) or a git error returns `{ path: null }`
+ * with the reason, and the caller turns that into a gate failure rather than running
+ * against a tree it cannot name.
+ *
+ * @param {string} root the real repository root
+ * @returns {Promise<{path: string, error?: never}|{path: null, error: string}>}
+ */
+async function materializeHeadWorktree(root) {
+  const path = await mkdtemp(join(tmpdir(), 'head-gate-'));
+  try {
+    await exec('git', ['worktree', 'add', '--detach', path, 'HEAD'], { cwd: root });
+  } catch (error) {
+    await rm(path, { recursive: true, force: true }).catch(() => {});
+    return { path: null, error: `git worktree add failed: ${String(error.stderr ?? error.message).trim()}` };
+  }
+  const nodeModules = join(root, 'node_modules');
+  try {
+    await symlink(nodeModules, join(path, 'node_modules'));
+  } catch {
+    // Absent node_modules is the normal case for a repo with no install step; a
+    // dangling link is harmless, and `npm run` does not need it to exist.
+  }
+  return { path };
+}
+
+/**
+ * Remove a pre-push worktree. `--force` because a gate may have left it dirty (a
+ * formatter, a test that writes fixtures); the worktree is disposable, the real tree
+ * is not. Falls back to `rm -rf` plus a prune when git cannot remove it (a lock, a
+ * path in a state git does not expect), so a cleanup failure never leaks the tree.
+ *
+ * @param {string} root the real repository root
+ * @param {string} path the worktree to remove
+ */
+async function removeHeadWorktree(root, path) {
+  await exec('git', ['worktree', 'remove', '--force', path], { cwd: root }).catch(async () => {
+    await rm(path, { recursive: true, force: true }).catch(() => {});
+    await exec('git', ['worktree', 'prune'], { cwd: root }).catch(() => {});
+  });
+}
+
+/**
+ * The lines that report one event's gate run: the event, what was declared, every
+ * gate with its disposition, its reason and its remedy, and the verdict.
+ *
+ * Shared by `hooks run` and `slice finish` rather than written twice (ADR-002: the
+ * second real use is what the extraction exists for). Both run this dispatcher over
+ * the same event, and two renderings of one run are two ways for one of them to
+ * quietly stop printing a gate that failed.
+ *
+ * @param {string} event the hook event as git spells it
+ * @param {string[]} declared the gate names the manifest declares for it
+ * @param {object} result the value `runGates` returned
+ * @returns {string[]} the report lines, newline-free, in print order
+ */
+export function renderGateReport(event, declared, result) {
+  const lines = [`hooks    ${event}`, `gates    ${(declared ?? []).join(', ') || '(none declared)'}`];
+  for (const g of result.gates) {
+    lines.push(`${g.status.toUpperCase().padEnd(8)} ${g.name.padEnd(20)} ${g.detail}${g.adr ? `  [${g.adr}]` : ''}`);
+    if (g.remedy) lines.push(`        remedy: ${g.remedy}`);
+    if (g.output) lines.push(...g.output.split('\n').map((l) => `        ${l}`));
+  }
+  lines.push(result.failed ? 'BLOCKED  at least one gate failed' : 'PASSED');
+  return lines;
+}
+
+async function run(argv, cwd, env) {
   try {
-    const { stdout, stderr } = await exec(argv[0], argv.slice(1), { cwd, maxBuffer: 8 * 1024 * 1024 });
+    const { stdout, stderr } = await exec(argv[0], argv.slice(1), { cwd, env, maxBuffer: 8 * 1024 * 1024 });
     return { code: 0, stdout, stderr };
   } catch (error) {
     return { code: typeof error.code === 'number' ? error.code : 1, stdout: error.stdout ?? '', stderr: error.stderr ?? String(error.message ?? error) };
   }
 }
 
+/** The built-in gates this dispatcher can run, by name. */
+const BUILTIN_GATES = new Map([['secret-scan', scanStaged]]);
+
+/** How many findings the report prints; the detail carries the true count. */
+const BUILTIN_REPORT_MAX = 12;
+
+/**
+ * Run a `builtin` gate in this process (ADR-100).
+ * Every outcome is a verdict with a reason: a built-in that does not exist, a
+ * diff git cannot read, or a secret found each fail with their own detail —
+ * none of them can degrade into a pass, which is the same fail-closed contract
+ * an unresolvable script gate has.
+ */
+async function runBuiltinGate(name, { root, staged, options }) {
+  const scan = BUILTIN_GATES.get(name);
+  if (scan === undefined) {
+    return {
+      ok: false,
+      detail: `no built-in implementation for gate "${name}"; this is a bug in ${CLI}`,
+      remedy: `remove "${name}" from ${MANIFEST_FILE} gates`,
+      output: '',
+    };
+  }
+  if (staged.length === 0) {
+    return { ok: true, detail: 'nothing staged; no added line to scan', output: '' };
+  }
+  const result = await scan(root, options ?? {});
+  if (result.error !== null) {
+    return {
+      ok: false,
+      detail: `the staged diff could not be read: ${result.error}`,
+      remedy: 'the gate fails closed; inspect the repository state and commit again',
+      output: '',
+    };
+  }
+  if (result.findings.length === 0) {
+    return { ok: true, detail: `${result.lines} added line(s) scanned, no secret found`, output: '' };
+  }
+  const files = new Set(result.findings.map((f) => f.file));
+  const shown = result.findings.slice(0, BUILTIN_REPORT_MAX);
+  const more = result.findings.length - shown.length;
+  return {
+    ok: false,
+    detail: `${result.findings.length} probable secret(s) in ${files.size} staged file(s)`,
+    remedy:
+      'remove the value from the staged file (or unstage it with git restore --staged <path>) ' +
+      'and commit again; the report never prints the matched bytes',
+    output:
+      renderFindings(shown) +
+      (more > 0 ? `\n  … ${more} more finding(s) not shown` : ''),
+  };
+}
+
 /**
  * Run a gate's resolution, as a shell line or as an argv.
  *
@@ -266,9 +694,13 @@ async function run(argv, cwd) {
  * rather than a flag on `run`.
  */
 async function runGate(resolution, cwd) {
+  // The push override is for the push itself, not for the gates the hook runs.
+  // A test that asserts a push is denied sees the override and fails.
+  const env = { ...process.env };
+  delete env.SIMT_ALLOW;
   if (resolution.shell === true && typeof resolution.command === 'string') {
     try {
-      const { stdout, stderr } = await exec('sh', ['-c', resolution.command], { cwd, maxBuffer: 8 * 1024 * 1024 });
+      const { stdout, stderr } = await exec('sh', ['-c', resolution.command], { cwd, env, maxBuffer: 8 * 1024 * 1024 });
       return { code: 0, stdout, stderr };
     } catch (error) {
       return {
@@ -278,7 +710,7 @@ async function runGate(resolution, cwd) {
       };
     }
   }
-  return run(resolution.argv, cwd);
+  return run(resolution.argv, cwd, env);
 }
 
 async function readPkg(root) {

package/src/hooks/gates.mjs

@@ -1,7 +1,7 @@
 import { MANIFEST_FILE } from '../name.mjs';
 // Gate definitions for the shared hook dispatcher.
 //
-// A gate has one of three kinds, and the choice is not cosmetic:
+// A gate has one of four kinds, and the choice is not cosmetic:
 //
 //   staged   run a formatter over the STAGED FILES ONLY, then re-stage them.
 //            Whole-repo formatting from a pre-commit hook would rewrite
@@ -14,13 +14,18 @@ import { MANIFEST_FILE } from '../name.mjs';
 //            know what monkeyc or a Kotlin script path looks like in one repo
 //            and something else in another. Plan 0001 section 3.2 keeps repo
 //            commands and paths local; this is that ruling in code.
+//   builtin  run inside this binary, with nothing to resolve on disk. For a
+//            check whose whole value is that a fresh clone has it: the staged-
+//            diff secret scan needs no script, no command and no tool in
+//            node_modules, and a gate that needed an install step would be a
+//            gate the repository that most needs it does not have (ADR-100).
 //
 // ADR-010 note: no gate invokes `npx` or `npm exec`. Script gates go through
 // `npm run`, and staged gates resolve the formatter from the project's own
 // `node_modules/.bin`, which is the declared dependency's binary rather than
 // one fetched at hook time.
 
-export const GATE_KINDS = new Set(['staged', 'script', 'command']);
+export const GATE_KINDS = new Set(['staged', 'script', 'command', 'builtin']);
 
 /** Extensions a `staged` formatter gate will hand to the tool. */
 export const FORMATTABLE = new Set([
@@ -29,7 +34,7 @@ export const FORMATTABLE = new Set([
 ]);
 
 /**
- * @typedef {{name: string, kind: 'staged'|'script'|'command', adr: string,
+ * @typedef {{name: string, kind: 'staged'|'script'|'command'|'builtin', adr: string,
  *            script?: string, tools?: string[], why: string}} Gate
  */
 
@@ -88,6 +93,12 @@ export const GATES = {
     adr: 'ADR-002',
     why: 'a protocol change is a two-repo change; the drift check is what makes half of it fail loudly',
   },
+  'secret-scan': {
+    name: 'secret-scan',
+    kind: 'builtin',
+    adr: 'ADR-100',
+    why: 'a staged diff is the last moment a secret can still be kept out of history, and the scan must be runnable by a clone with nothing installed',
+  },
 };
 
 export function getGate(name) {

package/src/hooks/resolve.mjs

@@ -68,7 +68,7 @@ export function hasScript(pkg, script) {
  * @returns {Promise<{ok: true, argv: string[], kind: string, detail: string}
  *                  | {ok: false, gate: string, kind: string, reason: string, remedy: string}>}
  */
-export async function resolveGate(gate, { root, pkg, staged, commands }) {
+export async function resolveGate(gate, { root, pkg, staged, commands, runner = null }) {
   const name = gate.name;
   const declared = commands?.[name];
 
@@ -119,6 +119,20 @@ export async function resolveGate(gate, { root, pkg, staged, commands }) {
     };
   }
 
+  if (gate.kind === 'builtin') {
+    // Nothing on disk to resolve: the implementation IS this binary, which is
+    // the whole point of the kind (ADR-100). A declared command was handled
+    // above and still wins, so a repository can swap the built-in for its own
+    // program exactly the way it can for any other gate.
+    return {
+      ok: true,
+      kind: gate.kind,
+      argv: null,
+      builtin: gate.name,
+      detail: `built-in: ${gate.name}`,
+    };
+  }
+
   if (gate.kind === 'staged') {
     const tool = await resolveStagedTool(root, gate);
     if (tool.path === null) {
@@ -158,11 +172,17 @@ export async function resolveGate(gate, { root, pkg, staged, commands }) {
         remedy: `add "${script}" to scripts, or remove "${name}" from ${MANIFEST_FILE} gates`,
       };
     }
+    // Q31: script gates run through the repo's own manager — `pnpm run`, not
+    // `npm run`, in a pnpm checkout. The default stays npm for callers that do
+    // not report one (older capabilities, hand-built contexts).
+    const { runScriptArgv, runScript } = await import('../ecosystem/node-runner.mjs');
+    const manager = runner ?? pkg?.packageManager?.split('@')?.[0] ?? 'npm';
+    const known = ['npm', 'pnpm', 'yarn', 'bun'].includes(manager) ? manager : 'npm';
     return {
       ok: true,
       kind: gate.kind,
-      argv: ['npm', 'run', '--silent', script],
-      detail: `npm run ${script}`,
+      argv: runScriptArgv(known, script),
+      detail: runScript(known, script),
     };
   }