@avi2dg/checks 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.34.0
+
+Released 2026-10-03.
+
+### Features
+
+- **delivery:** pin mutation jobs to winbox and default other jobs to hosted runners [#123](https://github.com/avi2d/checks/pull/123)
+
 ## 0.33.0
 
 Released 2026-10-03.

package/README.md

@@ -104,6 +104,7 @@ To consume the kit from a repository:
    ```
 
 Add a pull request title lint step in another workflow using `./node_modules/.bin/commitlint`.
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on each job, as [checks-ci-wiring](docs/gates/checks-ci-wiring.md#runners) requires.
 `bun run lint` then ends with `checks-lint: <count> gate(s) pass`.
 
 ## What runs

package/docs/gates/checks-advisories.md

@@ -110,7 +110,7 @@ on:
   workflow_dispatch:
 jobs:
   advisories:
-    runs-on: self-hosted
+    runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v5
@@ -119,8 +119,9 @@ jobs:
       - run: ./node_modules/.bin/checks-advisories --all
 ```
 
+The job runs on a hosted runner unless `CI_RUNS_ON` names another, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires.
+A hosted runner starts each run with an empty cache, so each run downloads both the scanner and the database.
 A self-hosted runner keeps `~/.cache/avi2dg-checks/` between runs, so it downloads the scanner once per pinned version and the database about once a day.
-A hosted runner starts each run with an empty cache, so each run downloads both.
 
 ## Related topics
 

package/docs/gates/checks-ci-wiring.md

@@ -21,10 +21,22 @@ It refuses a step or job with `if: false` or `continue-on-error: true`.
 It also refuses a workflow that does not trigger on both `opened` and `synchronize` pull requests to the target branch.
 A path filter cannot cover every pull request and therefore cannot satisfy the check.
 
+### Runners
+
+It also judges the runner of every job in every workflow.
+A mutation job is one with a run step that calls `stryker run`, `checks-mutation`, `checks-mutation-compare` or a `package.json` script that does, directly or through `bun`, `bun run` or `bunx`.
+The call counts as a command of its own or inside a command substitution, never as an argument to another command.
+A mutation job never names `CI_RUNS_ON` directly in `runs-on`, as `vars.CI_RUNS_ON` or `vars['CI_RUNS_ON']`, so an override for an outage cannot send its full sweeps to hosted runners.
+Any other job that names `CI_RUNS_ON` in `runs-on` carries exactly the hosted-default expression `${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}`.
+In a private repository each mutation job carries exactly the labels `[self-hosted, Linux, X64, winbox]` and every other job exactly the hosted-default expression.
+A public repository may keep `runs-on: ubuntu-latest` on every job, because a pull request from a fork runs its own code on the runner.
+The check knows a repository is private only from GitHub's event, so a run outside CI judges only the rules that hold in either.
+
 ## What it reads
 
 The bin reads `.github/workflows/*.yml`, `*.yaml` and the `scripts` in `package.json` from the working tree.
 It reads the target branch from `GITHUB_BASE_REF`, then from `refs/remotes/origin/HEAD` and then from the event file `GITHUB_EVENT_PATH` names.
+It reads whether the repository is private from `repository.private` in that event file.
 It parses the workflows with `Bun.YAML` without executing them.
 
 ## Arguments
@@ -36,7 +48,7 @@ It takes no arguments.
 | Code | Result |
 | --- | --- |
 | 0 | Every required command has a reachable step. |
-| 1 | A required command is missing or blocked. |
+| 1 | A required command is missing or blocked, or a job runs on the wrong runner. |
 | 2 | A workflow or `package.json` cannot be decoded. |
 
 ## Sample output
@@ -49,6 +61,13 @@ ci-wiring: 1 of 6 gate(s) do not run on pull requests to main:
     no run step invokes it
 ```
 
+A mutation job that names `CI_RUNS_ON` in `runs-on` produces a report like this:
+
+```
+ci-wiring: 1 job(s) run on the wrong runner:
+  .github/workflows/mutation-compare.yml job mutation-compare: a mutation job reads CI_RUNS_ON, so an override moves its full sweeps off winbox; set runs-on: [self-hosted, Linux, X64, winbox]
+```
+
 ## When it runs
 
 `checks-lint` runs it in every repository.

package/docs/gates/checks-flake.md

@@ -76,6 +76,8 @@ jobs:
           path: flake-report.json
 ```
 
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on the job, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires.
+
 ## Related topics
 
 - [checks-test](checks-test.md)

package/docs/gates/checks-mutation-compare.md

@@ -107,8 +107,9 @@ jobs:
 Both Stryker runs are full sweeps, and GitHub sets `CI=true` on every runner, so the preset lets them through.
 The base worktree's path carries the run's id and attempt, and the last step removes it even when a run fails, so a runner kept between jobs starts each job clean.
 A public repository keeps `runs-on: ubuntu-latest`, because a pull request from a fork runs its own code on the runner.
-A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}` instead.
-With `CI_RUNS_ON` unset, the job then runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a private repository sends its full sweeps.
+A private repository sets `runs-on: [self-hosted, Linux, X64, winbox]` instead, which is the fleet's self-hosted Linux runner where it sends its full sweeps.
+The job never reads `CI_RUNS_ON`, so an override that moves a repository's other jobs during a runner outage leaves the comparison waiting for `winbox`.
+[checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names it in `runs-on`.
 
 ## Related topics
 

package/docs/gates/checks-mutation.md

@@ -73,7 +73,7 @@ on:
   workflow_dispatch:
 jobs:
   mutation:
-    runs-on: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}
+    runs-on: [self-hosted, Linux, X64, winbox]
     steps:
       - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2
@@ -88,8 +88,9 @@ jobs:
           path: reports/mutation/mutation.json
 ```
 
-With `CI_RUNS_ON` unset, the job runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a private repository sends its full sweeps.
-A repository sets `CI_RUNS_ON` only to name a different runner.
+The job runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a repository sends its full sweeps.
+It never reads `CI_RUNS_ON`, so an override that moves a repository's other jobs during a runner outage leaves the sweep waiting for `winbox`.
+[checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names it in `runs-on`.
 The `name: mutation` line is what `gh workflow run mutation` looks up.
 GitHub sets `CI=true` on every runner, so the preset lets the full run through there.
 

package/docs/gates/checks-release-notes.md

@@ -133,6 +133,7 @@ jobs:
         run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/release-notes.md"
 ```
 
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on each job in either workflow, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires.
 A release is a pull request that holds only the version bump and the built changelog, which [checks-release-pr](checks-release-pr.md) opens once a day.
 When it lands, [checks-release-tag](checks-release-tag.md) tags the merge commit and dispatches this workflow on the tag.
 A tag the workflow token pushes starts no `push` run, so the workflow triggers on `workflow_dispatch` as well, and refuses a dispatch on a ref that is not a tag.

package/docs/gates/checks-release-pr.md

@@ -138,11 +138,11 @@ jobs:
 ```
 
 A public repository keeps `runs-on: ubuntu-latest`.
-A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}` on both jobs, as its other workflows do.
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on both jobs, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires of every job but a mutation job.
 A repository whose build needs more than Bun adds the steps its `.github/workflows/ci.yml` runs before `bun run build` to both jobs, and nothing after it.
 Neither job runs a test suite or a mutation run.
 On a hosted runner the `pull-request` job takes about 25 seconds, which GitHub bills as one minute, whether it opens, refreshes or leaves the pull request alone.
-A private repository runs it on its self-hosted runner, which bills no minutes.
+A private repository runs it there too unless `CI_RUNS_ON` names its self-hosted runner, which bills no minutes.
 The `tag` job runs only when a release lands, and a job its `if` skips bills nothing.
 The checks it dispatches are the release pull request's own required checks, and they run again only when `main` moves under it.
 The pull request also lists its own `pull_request` runs as waiting for approval.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {

package/src/delivery/ci-wiring.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env bun
-import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { Config, Console, Effect, FileSystem, Path, Schema } from "effect";
 import { defaultBranch, git } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { ENTRY_POINT, KIT_GATES, type KitGate } from "../core/gates.ts";
-import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
+import { fromProgram, invokes, mentions, plainCommand, shellCommands, withoutOptions, type Command } from "./shell-command.ts";
 
 export type { Command };
 
@@ -34,6 +34,18 @@ export type Gap = {
   readonly blocked: readonly BlockedInvocation[];
 };
 
+export type Visibility = "private" | "public" | "unknown";
+
+export type RunnerPolicy = {
+  readonly visibility: Visibility;
+  readonly scripts: ReadonlyMap<string, string>;
+};
+
+export type RunnerFault = {
+  readonly location: string;
+  readonly fault: string;
+};
+
 type RunStep = {
   readonly location: string;
   readonly blocker: string | undefined;
@@ -58,6 +70,17 @@ const CONSTANTS = new Map([
   ["false", false],
 ]);
 const STATUS_OVERRIDE = /\b(?:always|failure|cancelled)\s*\(/;
+// GitHub expressions match context and property names without regard to case.
+const OVERRIDE_ACCESS = String.raw`vars\s*(?:\.\s*CI_RUNS_ON\b|\[\s*'CI_RUNS_ON'\s*\])`;
+const RUNNER_OVERRIDE = new RegExp(String.raw`\b${OVERRIDE_ACCESS}`, "i");
+const HOSTED_OVERRIDE = new RegExp(String.raw`^\$\{\{\s*${OVERRIDE_ACCESS}\s*\|\|\s*'ubuntu-latest'\s*\}\}$`, "i");
+const MUTATION_RUNNER = ["self-hosted", "Linux", "X64", "winbox"];
+const HOSTED_DEFAULT = "${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}";
+const MUTATION_BINS = ["checks-mutation", "checks-mutation-compare"];
+const BUN_OPERANDS = new Set(["--cwd", "-c", "--config", "--env-file", "-F", "--filter", "-r", "--preload", "--require", "--import", "-e", "--eval", "-p", "--print", "--elide-lines", "--tsconfig-override"]);
+// bun's own commands take precedence over a package.json script of the same name unless bun run names it.
+const BUN_COMMANDS = new Set(["test", "repl", "exec", "install", "i", "add", "a", "remove", "rm", "update", "outdated", "link", "unlink", "pm", "build", "init", "create", "c", "upgrade", "publish", "patch", "patch-commit", "audit", "info", "why"]);
+const EventRepository = Schema.fromJsonString(Schema.Struct({ repository: Schema.Struct({ private: Schema.Boolean }) }));
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -243,13 +266,75 @@ export function declarationFor(scripts: readonly string[], branch: string): Decl
   };
 }
 
+function runsMutation(script: string, scripts: ReadonlyMap<string, string>, walked: readonly string[] = []): boolean {
+  return shellCommands(script).some((command) => mutationCommand(command, scripts, walked));
+}
+
+function mutationCommand(command: Command, scripts: ReadonlyMap<string, string>, walked: readonly string[]): boolean {
+  const [first = "", ...rest] = fromProgram(command);
+  return first === "bun" ? bunRunsMutation(rest, scripts, walked) : mutationBin([first, ...rest]);
+}
+
+function bunRunsMutation(args: Command, scripts: ReadonlyMap<string, string>, walked: readonly string[]): boolean {
+  const [command = "", ...rest] = withoutOptions(args, BUN_OPERANDS);
+  if (command === "x") return mutationCommand(["bunx", ...rest], scripts, walked);
+  if (BUN_COMMANDS.has(command)) return false;
+  const [target = "", ...targetArgs] = command === "run" ? withoutOptions(rest, BUN_OPERANDS) : [command, ...rest];
+  const body = walked.includes(target) ? undefined : scripts.get(target);
+  return body === undefined ? mutationBin([target, ...targetArgs]) : runsMutation(body, scripts, [...walked, target]);
+}
+
+function mutationBin([program = "", subcommand]: Command): boolean {
+  const bin = program.slice(program.lastIndexOf("/") + 1);
+  return MUTATION_BINS.includes(bin) || (bin === "stryker" && subcommand === "run");
+}
+
+function sameLabels(runsOn: unknown, labels: readonly string[]): boolean {
+  const named = Array.isArray(runsOn) ? names(runsOn) : undefined;
+  return named?.length === labels.length && labels.every((label) => named.includes(label));
+}
+
+function readsOverride(runsOn: unknown): boolean {
+  if (typeof runsOn === "string") return RUNNER_OVERRIDE.test(runsOn);
+  const values = isRecord(runsOn) ? Object.values(runsOn) : Array.isArray(runsOn) ? runsOn : [];
+  return values.some(readsOverride);
+}
+
+function runnerFault(runsOn: unknown, mutation: boolean, visibility: Visibility): string | undefined {
+  const overridden = readsOverride(runsOn);
+  const pin = `set runs-on: [${MUTATION_RUNNER.join(", ")}]`;
+  if (mutation && overridden) return `a mutation job reads CI_RUNS_ON, so an override moves its full sweeps off winbox; ${pin}`;
+  if (mutation) return visibility === "private" && !sameLabels(runsOn, MUTATION_RUNNER) ? `a mutation job in a private repository runs off winbox; ${pin}` : undefined;
+  const hosted = typeof runsOn === "string" && HOSTED_OVERRIDE.test(runsOn.trim());
+  if (hosted || (visibility !== "private" && !overridden)) return undefined;
+  return `the job is not on a hosted runner CI_RUNS_ON can override; set runs-on: ${HOSTED_DEFAULT}`;
+}
+
+export function findRunnerFaults(policy: RunnerPolicy, workflows: readonly Workflow[]): readonly RunnerFault[] {
+  return workflows.flatMap((workflow) => {
+    const jobs = isRecord(workflow.document) ? workflow.document["jobs"] : undefined;
+    if (!isRecord(jobs)) return [];
+    return Object.entries(jobs).flatMap(([id, job]) => {
+      if (!isRecord(job) || job["runs-on"] === undefined) return [];
+      const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
+      const mutation = steps.some((step: unknown) => isRecord(step) && typeof step["run"] === "string" && runsMutation(step["run"], policy.scripts));
+      const fault = runnerFault(job["runs-on"], mutation, policy.visibility);
+      return fault === undefined ? [] : [{ location: `${workflow.path} job ${id}`, fault }];
+    });
+  });
+}
+
+export function formatRunnerReport(faults: readonly RunnerFault[]): string {
+  return [`ci-wiring: ${faults.length} job(s) run on the wrong runner:`, ...faults.map(({ location, fault }) => `  ${location}: ${fault}`)].join("\n");
+}
+
 export const parseWorkflow = (path: string, text: string): Effect.Effect<Workflow, WiringError> =>
   Effect.try({
     try: () => ({ path, document: Bun.YAML.parse(text) }),
     catch: (error) => new WiringError({ message: `cannot parse ${path}: ${String(error)}` }),
   });
 
-export const readDeclaration = Effect.fn("readDeclaration")(function* (root: string) {
+const readScripts = Effect.fn("readScripts")(function* (root: string) {
   const fs = yield* FileSystem.FileSystem;
   const file = (yield* Path.Path).join(root, "package.json");
   const { scripts = {} } = (yield* fs.exists(file))
@@ -258,7 +343,22 @@ export const readDeclaration = Effect.fn("readDeclaration")(function* (root: str
         Effect.mapError((cause) => new WiringError({ message: `cannot read ${file}: ${cause.message}` })),
       )
     : Manifest.make({});
-  return declarationFor(Object.keys(scripts), yield* defaultBranch(root));
+  return new Map(Object.entries(scripts));
+});
+
+export const readDeclaration = Effect.fn("readDeclaration")(function* (root: string) {
+  return declarationFor([...(yield* readScripts(root)).keys()], yield* defaultBranch(root));
+});
+
+// Only GitHub's event says whether the repository is private, so a run outside CI judges what holds in either.
+const readVisibility = Effect.gen(function* () {
+  const eventPath = yield* Config.String("GITHUB_EVENT_PATH").pipe(Config.withDefault(""));
+  if (eventPath === "") return "unknown" satisfies Visibility;
+  return yield* (yield* FileSystem.FileSystem).readFileString(eventPath).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(EventRepository)),
+    Effect.map(({ repository }): Visibility => (repository.private ? "private" : "public")),
+    Effect.orElseSucceed((): Visibility => "unknown"),
+  );
 });
 
 export const readWorkflows = Effect.fn("readWorkflows")(function* (root: string) {
@@ -283,7 +383,9 @@ const wiring = Effect.gen(function* () {
   const gaps = findGaps(declaration, workflows);
   const gapReport = formatReport(declaration, gaps);
   yield* gaps.length > 0 ? Console.error(gapReport) : Console.log(gapReport);
-  return gaps.length === 0;
+  const faults = findRunnerFaults({ visibility: yield* readVisibility, scripts: yield* readScripts(root) }, workflows);
+  if (faults.length > 0) yield* Console.error(formatRunnerReport(faults));
+  return gaps.length === 0 && faults.length === 0;
 });
 
 if (import.meta.main) runMain("ci-wiring", wiring);

package/src/delivery/shell-command.ts

@@ -64,6 +64,149 @@ export function plainCommand(script: string): Command | undefined {
   return words.length === 0 ? undefined : words;
 }
 
+type ShellPart = Span & { readonly substitutions: readonly string[] };
+
+const COMMAND_BREAKS = new Set(["\n", ";", "&", "|", "(", ")", "`"]);
+const WORD_BREAKS = new Set([" ", "\t"]);
+const REDIRECTS = new Set(["<", ">"]);
+const REDIRECT_OPERATOR = /^[<>][<>&|]*/;
+const FILE_DESCRIPTOR = /^\d+$/;
+const DOUBLE_QUOTE_ESCAPES = new Set(["$", "`", '"', "\\"]);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const RESERVED_WORDS = new Set(["!", "{", "if", "then", "elif", "else", "while", "until", "do"]);
+const LAUNCHER_OPERANDS = new Map<string, ReadonlySet<string>>([
+  ["time", new Set(["-o", "-f"])],
+  ["env", new Set(["-u", "-C", "--unset", "--chdir"])],
+  ["exec", new Set(["-a"])],
+  ["nohup", new Set()],
+  ["sudo", new Set(["-u", "-g", "-C", "-D", "-h", "-p", "-r", "-t", "-U", "--user", "--group", "--chdir", "--host", "--prompt"])],
+  ["bunx", new Set(["-p", "--package"])],
+  ["npx", new Set(["-p", "--package", "-c", "--call", "-w", "--workspace"])],
+]);
+
+function substitutionEnd(script: string, start: number): number {
+  if (script.charAt(start) === "`") {
+    const close = script.indexOf("`", start + 1);
+    return close === -1 ? script.length : close;
+  }
+  let depth = 0;
+  for (let index = start + 1; index < script.length; index += 1) {
+    if (script.charAt(index) === "(") depth += 1;
+    if (script.charAt(index) === ")") depth -= 1;
+    if (depth === 0) return index;
+  }
+  return script.length;
+}
+
+function doubleQuotedPart(script: string, index: number): ShellPart {
+  const char = script.charAt(index);
+  const next = script.charAt(index + 1);
+  if (char === "\\" && next === "\n") return { text: "", end: index + 2, substitutions: [] };
+  if (char === "\\" && DOUBLE_QUOTE_ESCAPES.has(next)) return { text: next, end: index + 2, substitutions: [] };
+  if (char !== "`" && !(char === "$" && next === "(")) return { text: char, end: index + 1, substitutions: [] };
+  const end = substitutionEnd(script, index);
+  return { text: "", end: end + 1, substitutions: [script.slice(index + (char === "`" ? 1 : 2), end)] };
+}
+
+function shellDoubleQuoted(script: string, open: number): ShellPart {
+  let text = "";
+  const substitutions: string[] = [];
+  let index = open + 1;
+  while (index < script.length && script.charAt(index) !== '"') {
+    const part = doubleQuotedPart(script, index);
+    text += part.text;
+    substitutions.push(...part.substitutions);
+    index = part.end;
+  }
+  return { text, end: index + 1, substitutions };
+}
+
+function shellPart(script: string, index: number): ShellPart {
+  const char = script.charAt(index);
+  if (char === "'") {
+    const close = script.indexOf("'", index + 1);
+    const end = close === -1 ? script.length : close;
+    return { text: script.slice(index + 1, end), end: end + 1, substitutions: [] };
+  }
+  if (char === '"') return shellDoubleQuoted(script, index);
+  if (char === "\\") return { text: script.charAt(index + 1), end: index + 2, substitutions: [] };
+  return { text: char, end: index + 1, substitutions: [] };
+}
+
+function commentEnd(script: string, from: number): number {
+  const newline = script.indexOf("\n", from);
+  return newline === -1 ? script.length : newline;
+}
+
+type ShellParse = {
+  readonly commands: string[][];
+  readonly substitutions: string[];
+  words: string[];
+  word: string | undefined;
+  redirecting: boolean;
+};
+
+function endWord(parse: ShellParse): void {
+  if (parse.word === undefined) return;
+  if (!parse.redirecting) parse.words.push(parse.word);
+  parse.redirecting = false;
+  parse.word = undefined;
+}
+
+function endCommand(parse: ShellParse): void {
+  endWord(parse);
+  parse.commands.push(parse.words);
+  parse.words = [];
+  parse.redirecting = false;
+}
+
+function startRedirect(parse: ShellParse, script: string, index: number): number {
+  if (parse.word !== undefined && FILE_DESCRIPTOR.test(parse.word)) parse.word = undefined;
+  endWord(parse);
+  parse.redirecting = true;
+  return index + (REDIRECT_OPERATOR.exec(script.slice(index))?.[0].length ?? 1);
+}
+
+export function shellCommands(script: string): readonly Command[] {
+  const parse: ShellParse = { commands: [], substitutions: [], words: [], word: undefined, redirecting: false };
+  let index = 0;
+  while (index < script.length) {
+    const char = script.charAt(index);
+    if (char === "\\" && script.charAt(index + 1) === "\n") {
+      index += 2;
+    } else if (char === "#" && parse.word === undefined) {
+      index = commentEnd(script, index);
+    } else if (REDIRECTS.has(char)) {
+      index = startRedirect(parse, script, index);
+    } else if (COMMAND_BREAKS.has(char) || WORD_BREAKS.has(char)) {
+      if (COMMAND_BREAKS.has(char)) endCommand(parse);
+      else endWord(parse);
+      index += 1;
+    } else {
+      const part = shellPart(script, index);
+      parse.word = (parse.word ?? "") + part.text;
+      parse.substitutions.push(...part.substitutions);
+      index = part.end;
+    }
+  }
+  endCommand(parse);
+  return [...parse.commands, ...parse.substitutions.flatMap(shellCommands)].filter((command) => command.length > 0);
+}
+
+export function withoutOptions(words: Command, operands: ReadonlySet<string>): Command {
+  const [first = "", ...rest] = words;
+  if (first === "--") return rest;
+  if (!first.startsWith("-")) return words;
+  return withoutOptions(operands.has(first) ? rest.slice(1) : rest, operands);
+}
+
+export function fromProgram(words: Command): Command {
+  const [first = "", ...rest] = words;
+  if (ASSIGNMENT.test(first) || RESERVED_WORDS.has(first)) return fromProgram(rest);
+  const operands = LAUNCHER_OPERANDS.get(first);
+  return operands === undefined ? words : fromProgram(withoutOptions(rest, operands));
+}
+
 // bun run resolves any other word, even one holding a slash, to a package.json script of that name first.
 const FILE_PATH = /^\.{0,2}\//;