@homeflare/config 0.9.0 → 0.11.0

package/src/hooks/activate.ts

@@ -0,0 +1,71 @@
+/**
+ * Turn the hooks on for a clone and EVERY worktree of it, from `prepare`.
+ *
+ * 🔴 THE GAP THIS CLOSES, measured 2026-09-23. husky sets `core.hooksPath=.husky/_`, and
+ *   `.husky/_` is generated and gitignored: it exists only in the worktree where `bun
+ *   install` ran husky. `core.hooksPath` lives in the clone's SHARED config, so every other
+ *   worktree — every `git worktree add` an agent makes — points at a directory it does not
+ *   have, and git runs no hooks there, silently. In homeflare-kit that was every worktree
+ *   until `bun install` had run husky inside it.
+ * ★ THE FIX IS A TRACKED PATH. `core.hooksPath=.husky` is relative, and git resolves a
+ *   relative hooks path against the worktree running the hook — so each worktree runs its
+ *   OWN checked-out `.husky/`, present from the moment the worktree exists. Measured on git
+ *   2.55: a fresh `git worktree add` ran the tracked hook with no install at all. (The
+ *   wrapper then needs that worktree's `node_modules` to do its work — install.ts says so
+ *   out loud rather than failing.)
+ * ⛔ IT NEVER FAILS. `prepare` runs inside `bun install`; a hook problem must not break an
+ *   install. Every outcome, including "did nothing", is a message and exit 0.
+ */
+import { probe } from './report.ts';
+
+export type Activation = {
+  /** The hooks path is set (now or already). */
+  readonly active: boolean;
+  readonly message: string;
+};
+
+/**
+ * ⚠️ CI IS SKIPPED ON PURPOSE. Hooks are a local convenience and CI runs the real gate; a
+ *   runner with hooks on would run them on the commits it makes itself (a release's
+ *   "Version Packages" commit) on a machine that may have no gitleaks.
+ */
+function inCi(env: Readonly<Record<string, string | undefined>>): boolean {
+  const ci = env['CI'];
+  return ci !== undefined && ci !== '' && ci !== '0' && ci.toLowerCase() !== 'false';
+}
+
+export async function activateHooks(
+  root: string,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): Promise<Activation> {
+  if (inCi(env)) return { active: false, message: 'CI is set — hooks stay off; CI runs the gate' };
+
+  // ★ `--show-prefix` answers two questions at once: whether this is a work tree at all
+  //   (it fails outside one — a tarball install), and where `root` sits inside it.
+  const where = await probe(['git', '-C', root, 'rev-parse', '--show-prefix']);
+  if (where.code !== 0) return { active: false, message: 'not a git work tree — nothing to do' };
+
+  const tracked = await Promise.all(
+    ['pre-commit', 'pre-push'].map((name) => Bun.file(`${root}/.husky/${name}`).exists()),
+  );
+  if (!tracked.some(Boolean)) {
+    return { active: false, message: 'no .husky/pre-commit or .husky/pre-push to point git at' };
+  }
+
+  // ⚠️ RELATIVE TO THE TOP OF THE WORK TREE, which is where git resolves it — a package
+  //   below the root (`<prefix>.husky`) still points at its own directory.
+  const want = `${where.stdout.trim()}.husky`;
+  const current = (
+    await probe(['git', '-C', root, 'config', '--get', 'core.hooksPath'])
+  ).stdout.trim();
+  if (current === want) return { active: true, message: `core.hooksPath is already ${want}` };
+
+  // ★ NO `--worktree`: the clone's shared config, so ONE install covers every worktree.
+  const set = await probe(['git', '-C', root, 'config', 'core.hooksPath', want]);
+  if (set.code !== 0) return { active: false, message: 'git config core.hooksPath failed' };
+  const was = current === '' ? 'unset' : current;
+  return {
+    active: true,
+    message: `core.hooksPath ${was} → ${want}, for every worktree of this clone`,
+  };
+}

package/src/hooks/gates.ts

@@ -1,16 +1,19 @@
 /**
  * The two gates every HomeFlare repo gets, from one place.
  *
- * ★ THE SPLIT IS BY COST. `pre-commit` touches only the staged files and is measured in
- *   hundreds of milliseconds, so it can run on every commit without anyone resenting
- *   it. `pre-push` runs the repo's own `bun run check` — seconds, once, before the
- *   change costs a slot on the shared self-hosted runner.
- *
- * ⚠️ NEITHER IS A GATE. Both are skippable with `--no-verify` and neither exists in a
- *   fresh clone until `bun install` runs `prepare`. The required checks on `main` stay
- *   the gate; these only make the cheap mistakes cheap to find.
+ * ★ THE SPLIT IS BY COST. `pre-commit` touches only the staged files — a secret scan, then
+ *   format and lint — and is measured in hundreds of milliseconds, so it can run on every
+ *   commit without anyone resenting it. `pre-push` runs the repository's own `check`
+ *   narrowed to what the push can affect (push-plan.ts): seconds, once per push.
+ * ⚠️ NEITHER IS A GATE. Both are skippable with `--no-verify`, and a worktree has them only
+ *   once `bun install` has run there. The required checks on `main` stay the gate — CI
+ *   runs the whole `check`, every test, the build and the smoke test on every pull request.
  */
-import { fail, note, ok, run, tool } from './report.ts';
+import { existsSync } from 'node:fs';
+import { type Lane, planLanes } from './push-plan.ts';
+import { changesEverything, parsePushRefs, pushScope } from './push-range.ts';
+import { fail, note, ok, run, runLane, tool } from './report.ts';
+import { scanStagedSecrets } from './secrets.ts';
 import { fingerprints, staged } from './staged.ts';
 
 /**
@@ -20,7 +23,26 @@ import { fingerprints, staged } from './staged.ts';
  *   happens. Without the restage, oxfmt would fix the worktree while the commit kept
  *   the unformatted bytes — CI then fails on a file that reads as correct locally.
  */
+/**
+ * Has `bun install` run in this worktree?
+ *
+ * ⚠️ WITHOUT IT, SKIP — LOUDLY — RATHER THAN IMPROVISE. A fresh worktree now runs its hooks
+ *   (activate.ts), and in the repo that HOSTS this package they are reached by workspace
+ *   path, not through node_modules. There `tool()` would fall back to `bunx`, fetching an
+ *   unpinned oxfmt mid-commit, and a pre-push lane would die on "command not found". The
+ *   wrapper every other repo commits makes the same call one step earlier (install.ts).
+ */
+function installed(root: string, hook: 'pre-commit' | 'pre-push'): boolean {
+  if (existsSync(`${root}/node_modules`)) return true;
+  note(`${hook}: no node_modules in this worktree — run 'bun install'; skipping the rest`);
+  return false;
+}
+
 export async function preCommit(root: string): Promise<void> {
+  // ⛔ SECRETS FIRST, before anything can rewrite or pass — see secrets.ts. It needs only the
+  //   gitleaks binary, so it runs even in a worktree nobody has installed yet.
+  await scanStagedSecrets();
+  if (!installed(root, 'pre-commit')) return;
   const oxfmt = tool(root, 'oxfmt');
   const { formattable, code, partial } = await staged();
 
@@ -68,37 +90,74 @@ export async function preCommit(root: string): Promise<void> {
   ok(`pre-commit: ${formattable.length} staged file(s) formatted and linted`);
 }
 
+/** The one-line reason a lane is in the run, printed before it starts. */
+function describe(lane: Lane): string {
+  if (lane.kind === 'skip') return `skip ${lane.label} — ${lane.why}`;
+  if (lane.kind === 'test' && lane.scoped)
+    return `run  ${lane.command}  (only the tests the push can reach)`;
+  if (lane.kind === 'test') return `run  ${lane.command}  (IN FULL)`;
+  return `run  ${lane.command}`;
+}
+
 /**
- * Run the repo's own declared gate before the push reaches the runner.
+ * Run the repository's own `check`, narrowed to what the push can affect.
  *
- * ★ IT CALLS `bun run check` RATHER THAN NAMING TOOLS. Every repo's `check` is the
- *   command CI runs; hard-coding `tsc` and `bun test` here would drift from whichever
- *   repo added a step, and the hook would certify a push CI rejects.
- * ⛔ It does not widen a narrow `check`. If a repo's gate only looks at part of the
- *   tree, this hook inherits exactly that blind spot — fix the script, not the hook.
+ * ★ `args` ARE GIT'S: the remote name and URL. `stdin` is git's ref list — see
+ *   push-range.ts for how the base is chosen and why it never narrows to nothing.
+ * ⛔ IT DOES NOT CERTIFY WHAT CI WILL SAY. It certifies that `check`'s own lint and type
+ *   lanes pass and that every test the pushed files can reach passes. The build, the smoke
+ *   test and the unreachable tests are CI's, and the success line says so.
  */
-export async function prePush(root: string): Promise<void> {
+export async function prePush(root: string, args: readonly string[], stdin: string): Promise<void> {
   const manifest = Bun.file(`${root}/package.json`);
   const pkg = (await manifest.exists())
     ? ((await manifest.json()) as { scripts?: Record<string, string> })
     : {};
-
-  if (pkg.scripts?.['check'] === undefined) {
+  const scripts = pkg.scripts ?? {};
+  if (scripts['check'] === undefined) {
     note('pre-push: no `check` script declared in package.json; nothing to run');
     return;
   }
+  if (!installed(root, 'pre-push')) return;
 
-  note('pre-push: running `bun run check` — the same gate CI runs');
-  const started = Bun.nanoseconds();
-  // 🔴 `isolated`: strip the GIT_* this hook inherited before running the test suite.
-  //   See report.ts — without it a test's throwaway git repository commits into this one.
-  if ((await run(['bun', 'run', 'check'], true)) !== 0) {
-    fail(
-      'pre-push',
-      'bun run check failed — CI would fail the same way, on a shared runner',
-      'bun run lint:fix, then bun run check until it is green',
+  const scope = await pushScope(root, args[0] ?? 'origin', parsePushRefs(stdin));
+  if (scope.kind === 'empty') {
+    ok(`pre-push: ${scope.why} — nothing to check`);
+    return;
+  }
+  if (scope.kind === 'elsewhere') {
+    // ⛔ NOT A PASS, AND IT DOES NOT SAY ONE. The working tree is another commit; running the
+    //   lanes would certify content nobody checked. Failing would teach `--no-verify` for an
+    //   ordinary push, so it says what it did not do, and CI checks the ref.
+    note(`pre-push: ${scope.why} — the working tree is not what is being pushed`);
+    note(
+      '  NOT CHECKED here; CI checks it. To check it locally, check it out and push from there.',
     );
+    return;
+  }
+  let base: string | undefined;
+  if (scope.kind === 'unscoped') {
+    note(`pre-push: ${scope.why} — every lane runs, tests in full`);
+  } else {
+    const global = scope.changed.filter(changesEverything);
+    note(`pre-push: ${String(scope.changed.length)} file(s) changed ${scope.why}`);
+    if (global.length > 0)
+      note(`  ${global.join(', ')} changes what every test runs on — tests in full`);
+    else base = scope.base;
   }
 
-  ok(`pre-push: bun run check passed in ${((Bun.nanoseconds() - started) / 1e9).toFixed(1)}s`);
+  const lanes = planLanes(scripts, base);
+  const started = Bun.nanoseconds();
+  let ran = 0;
+  for (const lane of lanes) {
+    note(describe(lane));
+    if (lane.kind === 'skip') continue;
+    // 🔴 `runLane` strips the GIT_* this hook inherited — see report.ts.
+    if ((await runLane(lane.command, root)) !== 0) {
+      fail('pre-push', `\`${lane.label}\` failed`, `${lane.command} — until it is green`);
+    }
+    ran += 1;
+  }
+  const seconds = ((Bun.nanoseconds() - started) / 1e9).toFixed(1);
+  ok(`pre-push: ${String(ran)} lane(s) of \`check\` passed in ${seconds}s — CI runs the full gate`);
 }

package/src/hooks/install.ts

@@ -1,14 +1,18 @@
 /**
  * Adoption: the one wrapper every repo commits, and the check that it has not drifted.
  *
- * ★ WHY A WRAPPER AT ALL. husky can only run a file that is tracked in the repo, so
+ * ★ WHY A WRAPPER AT ALL. git can only run a file that is present in the worktree, so
  *   something must be committed per repo. This keeps that something to a delegation
  *   whose text is owned HERE — the behaviour lives in one package, and a repo that
  *   edits its copy is reported as drift rather than quietly diverging.
  * ★ ONE FILE, TWO NAMES. The wrapper reads the hook name from `$0`, so `pre-commit`
  *   and `pre-push` are byte-identical and there is a single text to keep in step.
+ * ★ THE DIRECTORY KEEPS HUSKY'S NAME, NOT HUSKY. `.husky/` is where the estate's hook files
+ *   already live (homeflare-kit, homeflare-alerts, the house monorepo); since 2026-09-23 git
+ *   runs them directly through `core.hooksPath` — see activate.ts for why husky's own
+ *   `.husky/_` left every fresh worktree without hooks.
  */
-import { chmod, mkdir } from 'node:fs/promises';
+import { chmod, mkdir, stat } from 'node:fs/promises';
 
 /** The hook files this package installs, in the order a contributor meets them. */
 export const HOOK_NAMES = ['pre-commit', 'pre-push'] as const;
@@ -16,27 +20,34 @@ export const HOOK_NAMES = ['pre-commit', 'pre-push'] as const;
 /** Where the runner lives once `bun install` has run. Relative: git runs hooks at the root. */
 const RUNNER = 'node_modules/@homeflare/config/bin/hooks.ts';
 
+/** What a consumer's `prepare` script runs, so every `bun install` activates the hooks. */
+export const PREPARE: string = `bun ${RUNNER} activate`;
+
 /**
- * ⚠️ IT EXITS 0 WHEN THE RUNNER IS ABSENT. A checkout with no `node_modules` would
+ * ⚠️ IT EXITS 0 WHEN THE RUNNER IS ABSENT. A worktree with no `node_modules` would
  *   otherwise fail every commit with a module-resolution error, and the first thing
  *   anyone would do is delete the hook. Failing open is the right trade for a
  *   convenience; the required checks on `main` are what must fail closed.
+ * ★ `"$@"` AND STDIN PASS THROUGH. `pre-push` reads the remote name from its first argument
+ *   and the pushed refs from stdin (push-range.ts); `exec` keeps both.
+ * ⚠️ NO SHEBANG, AND THAT IS MEASURED, NOT FORGOTTEN: git 2.55 runs an executable hook that
+ *   has none through `sh` (2026-09-23), and the husky-era files in the estate have none.
  */
 export const HUSKY_HOOK: string = `# HomeFlare shared git hook. The behaviour lives in @homeflare/config, not in this file,
 # and the same bytes are installed as .husky/pre-commit and .husky/pre-push — the hook
-# name comes from $0.
+# name comes from $0, and git's arguments and stdin pass straight through.
 #
-# ⚠️ A hook is a local convenience, not a gate: it is skippable with --no-verify and does
-#   not exist in a fresh clone until \`bun install\` runs the \`prepare\` script. The
-#   required checks on main stay the gate.
+# ⚠️ A hook is a local convenience, not a gate: it is skippable with --no-verify, and a
+#   worktree runs it only once \`bun install\` has run there. The required checks on main
+#   stay the gate.
 #
 # Regenerate this file with: bun ${RUNNER} install
 hook="${RUNNER}"
 if [ ! -f "$hook" ]; then
-  echo "husky: $hook is missing — run 'bun install' to enable the HomeFlare hooks; skipping"
+  echo "homeflare hooks: $hook is missing — run 'bun install' in this worktree; skipping" >&2
   exit 0
 fi
-exec bun "$hook" "$(basename "$0")"
+exec bun "$hook" "$(basename "$0")" "$@"
 `;
 
 /** Write the wrapper into `.husky/`. Returns the paths written, relative to the project. */
@@ -46,8 +57,8 @@ export async function installHooks(projectDir: string): Promise<readonly string[
   for (const name of HOOK_NAMES) {
     const path = `${projectDir}/.husky/${name}`;
     await Bun.write(path, HUSKY_HOOK);
-    // ⚠️ husky's own runner does `sh -e "$s"`, which does not need the execute bit, but
-    //   `core.hooksPath=.husky` without husky does. Set it so both mechanisms work.
+    // ⛔ THE EXECUTE BIT IS REQUIRED. git runs a `core.hooksPath` file directly and IGNORES
+    //   a non-executable hook, with nothing but an advice line to say so.
     await chmod(path, 0o755);
     written.push(`.husky/${name}`);
   }
@@ -66,20 +77,25 @@ export async function problemsInHooks(projectDir: string): Promise<readonly stri
   const manifest = Bun.file(`${projectDir}/package.json`);
 
   if (!(await manifest.exists())) return ['package.json: missing'];
-  const pkg = (await manifest.json()) as {
-    scripts?: Record<string, string>;
-    devDependencies?: Record<string, string>;
-  };
+  const pkg = (await manifest.json()) as { scripts?: Record<string, string> };
 
-  if (!(pkg.scripts?.['prepare'] ?? '').includes('husky')) {
-    problems.push('package.json: no "prepare": "husky" script — a fresh clone installs no hooks');
+  const prepare = pkg.scripts?.['prepare'] ?? '';
+  if (!/bin\/hooks\.ts activate/.test(prepare)) {
+    problems.push(
+      `package.json: "prepare" does not run \`${PREPARE}\` — no clone or worktree gets hooks`,
+    );
   }
-  if (pkg.devDependencies?.['husky'] === undefined) {
-    problems.push('package.json: husky is not a devDependency');
+  // ⚠️ husky POINTS core.hooksPath AT AN UNTRACKED `.husky/_` that exists only where it ran —
+  //   the gap activate.ts closes. Left in `prepare`, it undoes the activation.
+  if (/\bhusky\b/.test(prepare)) {
+    problems.push(
+      'package.json: "prepare" still runs husky, which re-points core.hooksPath at .husky/_',
+    );
   }
 
   for (const name of HOOK_NAMES) {
-    const file = Bun.file(`${projectDir}/.husky/${name}`);
+    const path = `${projectDir}/.husky/${name}`;
+    const file = Bun.file(path);
     if (!(await file.exists())) {
       problems.push(`.husky/${name}: missing — run \`bun ${RUNNER} install\``);
       continue;
@@ -89,6 +105,9 @@ export async function problemsInHooks(projectDir: string): Promise<readonly stri
         `.husky/${name}: differs from the @homeflare/config wrapper — run \`bun ${RUNNER} install\`, or change it in the package`,
       );
     }
+    if (((await stat(path)).mode & 0o111) === 0) {
+      problems.push(`.husky/${name}: not executable, so git ignores it — chmod +x it and commit`);
+    }
   }
 
   return problems;

package/src/hooks/push-plan.ts

@@ -0,0 +1,167 @@
+/**
+ * What `pre-push` runs: the repository's own `check`, with the expensive lanes narrowed to
+ * the push or left to CI.
+ *
+ * ★ IT READS `check` RATHER THAN NAMING TOOLS. `check` is the command CI runs, so the lanes
+ *   here are that command's lanes — a repository that adds a step to `check` gets it in the
+ *   hook with no change to this package. Hard-coding `tsc` and `bun test` would drift from
+ *   whichever repository added a step first, and certify a push CI rejects.
+ * ★ THREE THINGS CHANGE, AND ONLY THREE:
+ *   1. every `bun test …` becomes `bun test … --changed=<base>` — Bun's own import-graph
+ *      answer to "which test files can these changed files reach" (bun 1.4, measured
+ *      2026-09-23: 11 changed files ran 2 of 246 test files in homeflare-kit);
+ *   2. `build` and `smoke` scripts are skipped — minutes in a big workspace, and CI runs
+ *      both on every pull request;
+ *   3. everything else (lint, types, a `--check` script) runs exactly as `check` spells it.
+ *      They are seconds, whole-program by nature, and deterministic.
+ * ⛔ PURE. No git, no filesystem, no process: the whole contract is a function of the
+ *   scripts table and the base, so the estate's real `check` shapes are pinned by a table
+ *   test (tests/hooks-push-plan.test.ts) instead of by a live push.
+ */
+
+/** One step of the pre-push run. */
+export type Lane =
+  /** Run `command` through `sh -c` at the repository root. */
+  | { readonly kind: 'run'; readonly label: string; readonly command: string }
+  /** A test runner; `scoped` says whether it was narrowed to the push. */
+  | {
+      readonly kind: 'test';
+      readonly label: string;
+      readonly command: string;
+      readonly scoped: boolean;
+    }
+  /** Not run here, and why. */
+  | { readonly kind: 'skip'; readonly label: string; readonly why: string };
+
+/**
+ * ⚠️ BY NAME, AND ONLY THESE. A build in homeflare-kit is every package; a smoke test packs
+ *   and installs tarballs. Both are CI jobs on every pull request, and neither says anything
+ *   a type check and the reachable tests did not already say about a typical push.
+ */
+const LEFT_TO_CI = /^(build|smoke)(:|$)/;
+
+/** Recursion guard: a script that names itself, directly or through another, stops here. */
+const MAX_DEPTH = 8;
+
+/**
+ * Split a script on top-level `&&`, or return undefined when it is anything else.
+ *
+ * ⛔ UNDEFINED MEANS "RUN IT WHOLE". `||`, `;`, a pipe, a redirect, a background `&` or a
+ *   substitution each change what the pieces mean together, and a hook that re-plumbed them
+ *   would run something the repository never wrote. Quoted text is left alone, so
+ *   `--path-ignore-patterns="homeflare-*\/**"` survives intact.
+ */
+export function andChain(script: string): readonly string[] | undefined {
+  const parts: string[] = [];
+  let quote: string | undefined;
+  let current = '';
+  for (let i = 0; i < script.length; i++) {
+    const char = script[i] ?? '';
+    if (quote !== undefined) {
+      if (char === quote) quote = undefined;
+      current += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      current += char;
+      continue;
+    }
+    if (char === '&' && script[i + 1] === '&') {
+      parts.push(current.trim());
+      current = '';
+      i += 1;
+      continue;
+    }
+    if ('|;&<>`'.includes(char) || (char === '$' && script[i + 1] === '(')) return undefined;
+    current += char;
+  }
+  if (quote !== undefined) return undefined;
+  parts.push(current.trim());
+  return parts.some((part) => part === '') ? undefined : parts;
+}
+
+/** The script a segment names: `bun run x`, `npm run x`, or `npm test`. Else undefined. */
+function scriptRef(segment: string, scripts: Readonly<Record<string, string>>): string | undefined {
+  const words = segment.split(/\s+/);
+  if (words.length === 2 && words[0] === 'npm' && words[1] === 'test') return 'test';
+  const [runner, verb, name] = words;
+  if (words.length !== 3 || verb !== 'run' || name === undefined) return undefined;
+  if (runner !== 'bun' && runner !== 'npm') return undefined;
+  return Object.hasOwn(scripts, name) ? name : undefined;
+}
+
+/** `bun test …` — the runner, not a script called `test`. */
+const isBunTest = (segment: string): boolean => /^bun\s+test(\s|$)/.test(segment);
+
+function testLane(segment: string, base: string | undefined): Lane {
+  return base === undefined
+    ? { kind: 'test', label: segment, command: segment, scoped: false }
+    : { kind: 'test', label: segment, command: `${segment} --changed=${base}`, scoped: true };
+}
+
+function expand(
+  script: string,
+  scripts: Readonly<Record<string, string>>,
+  base: string | undefined,
+  depth: number,
+): readonly Lane[] | undefined {
+  const segments = andChain(script);
+  if (segments === undefined || depth > MAX_DEPTH) return undefined;
+  const lanes: Lane[] = [];
+  for (const segment of segments) {
+    if (isBunTest(segment)) {
+      lanes.push(testLane(segment, base));
+      continue;
+    }
+    const name = scriptRef(segment, scripts);
+    if (name === undefined) {
+      lanes.push({ kind: 'run', label: segment, command: segment });
+      continue;
+    }
+    if (LEFT_TO_CI.test(name)) {
+      lanes.push({ kind: 'skip', label: segment, why: 'CI runs it on every pull request' });
+      continue;
+    }
+    const inner = expand(scripts[name] ?? '', scripts, base, depth + 1);
+    if (inner !== undefined && inner.some((lane) => lane.kind !== 'run')) {
+      // Something inside needs narrowing or skipping: open the script up.
+      lanes.push(...inner);
+    } else if (/^test(:|$)/.test(name)) {
+      // ⚠️ A TEST SCRIPT WITH NO `bun test` IN IT RUNS IN FULL, AND SAYS SO — vitest with
+      //   coverage thresholds (a narrowed run would fail them), `node --test`, anything piped.
+      //   Narrowing it would mean rewriting a command this package does not understand.
+      lanes.push({ kind: 'test', label: segment, command: segment, scoped: false });
+    } else {
+      // ★ A SCRIPT WITH NOTHING TO NARROW RUNS UNDER ITS OWN NAME. `bun run lint` keeps
+      //   Bun's PATH handling and reads the way the repository wrote it.
+      lanes.push({ kind: 'run', label: segment, command: segment });
+    }
+  }
+  return lanes;
+}
+
+/**
+ * The lanes `pre-push` runs for this `scripts` table.
+ *
+ * `base` is the commit the push is measured from; `undefined` runs every test lane in full
+ * (an unknown base, or a push that changes what every test runs on).
+ * ⚠️ AN EMPTY LIST MEANS NO `check` SCRIPT — the caller reports that; it is not a pass.
+ */
+export function planLanes(
+  scripts: Readonly<Record<string, string>>,
+  base: string | undefined,
+): readonly Lane[] {
+  const check = scripts['check'];
+  if (check === undefined) return [];
+  // ⚠️ A `check` THAT IS NOT A PLAIN `&&` CHAIN IS RUN WHOLE, tests and all, and reported
+  //   as unscoped. No estate repository has one (surveyed 2026-09-23); the fallback exists so
+  //   an unusual one is checked rather than skipped.
+  const whole: Lane = {
+    kind: 'test',
+    label: 'bun run check',
+    command: 'bun run check',
+    scoped: false,
+  };
+  return expand(check, scripts, base, 0) ?? [whole];
+}