@avi2dg/checks 0.35.0 → 0.35.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.35.1
+
+Released 2026-10-07.
+
+### Fixes
+
+- **delivery:** recognise mutation jobs that run stryker through repository shell scripts [#130](https://github.com/avi2d/checks/pull/130)
+
 ## 0.35.0
 
 Released 2026-10-07.

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

@@ -24,8 +24,16 @@ A path filter cannot cover every pull request and therefore cannot satisfy the c
 ### 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`.
+A mutation job is one with a run step that calls `stryker run`, `checks-mutation` or `checks-mutation-compare`, directly or through `bun`, `bun run` or `bunx`.
+The call counts too through a `package.json` script or a shell script in the repository.
+A command runs a shell script by a path inside the repository, such as `tools/mutate.sh` or `./mutate.sh`, or as a `bun` target that no `package.json` script names.
+The path resolves from the directory the command runs in: the step's `working-directory`, the job's or the workflow's `defaults.run.working-directory`, `bun --cwd` and a literal `cd`.
+A script file runs in its caller's directory, and a `package.json` script runs from the repository root.
+A path the check cannot know before the run, such as one built from an expression or a variable, reaches no file.
+A file counts as a shell script when its name ends in `.sh` or its first line names `sh`, `bash`, `dash`, `ksh` or `zsh`.
 The call counts as a command of its own or inside a command substitution, never as an argument to another command.
+A here-document that `sh`, `bash`, `dash`, `ksh` or `zsh` reads is a script, and its calls count.
+The text of any other here-document is data, so a call there counts only inside a command substitution when the delimiter is unquoted.
 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.
@@ -34,7 +42,7 @@ The check knows a repository is private only from GitHub's event, so a run outsi
 
 ## What it reads
 
-The bin reads `.github/workflows/*.yml`, `*.yaml` and the `scripts` in `package.json` from the working tree.
+The bin reads `.github/workflows/*.yml`, `*.yaml`, the `scripts` in `package.json` and the shell scripts those steps and scripts run 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.35.0",
+  "version": "0.35.1",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -47,6 +47,7 @@
     "src/testing/subsumed-tests.ts",
     "src/delivery/ci-wiring.ts",
     "src/delivery/shell-command.ts",
+    "src/delivery/mutation-job.ts",
     "src/delivery/secrets.ts",
     "src/delivery/gitleaks.ts",
     "src/delivery/gitleaks.toml",

package/src/delivery/ci-wiring.ts

@@ -3,7 +3,8 @@ 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 { fromProgram, invokes, mentions, plainCommand, shellCommands, withoutOptions, type Command } from "./shell-command.ts";
+import { readShellFiles, runsMutation, within, type Run } from "./mutation-job.ts";
+import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
 
 export type { Command };
 
@@ -39,6 +40,7 @@ export type Visibility = "private" | "public" | "unknown";
 export type RunnerPolicy = {
   readonly visibility: Visibility;
   readonly scripts: ReadonlyMap<string, string>;
+  readonly files?: ReadonlyMap<string, string>;
 };
 
 export type RunnerFault = {
@@ -76,10 +78,6 @@ 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> {
@@ -266,29 +264,6 @@ 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));
@@ -310,18 +285,37 @@ function runnerFault(runsOn: unknown, mutation: boolean, visibility: Visibility)
   return `the job is not on a hosted runner CI_RUNS_ON can override; set runs-on: ${HOSTED_DEFAULT}`;
 }
 
+function stepDirectory(value: unknown, inherited: string | undefined): string | undefined {
+  if (value === undefined) return inherited;
+  return typeof value === "string" ? within("", value) : undefined;
+}
+
+function defaultDirectory(node: unknown, inherited: string | undefined): string | undefined {
+  const defaults = isRecord(node) ? node["defaults"] : undefined;
+  const run = isRecord(defaults) ? defaults["run"] : undefined;
+  return stepDirectory(isRecord(run) ? run["working-directory"] : undefined, inherited);
+}
+
+function jobRuns(workflow: Workflow, job: Readonly<Record<string, unknown>>): readonly Run[] {
+  const dir = defaultDirectory(job, defaultDirectory(workflow.document, ""));
+  const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
+  return steps.flatMap((step: unknown) => (isRecord(step) && typeof step["run"] === "string" ? [{ script: step["run"], dir: stepDirectory(step["working-directory"], dir) }] : []));
+}
+
+function workflowJobs(workflow: Workflow): readonly (readonly [string, Readonly<Record<string, unknown>>])[] {
+  const jobs = isRecord(workflow.document) ? workflow.document["jobs"] : undefined;
+  return isRecord(jobs) ? Object.entries(jobs).flatMap(([id, job]) => (isRecord(job) ? [[id, job] as const] : [])) : [];
+}
+
 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));
+  return workflows.flatMap((workflow) =>
+    workflowJobs(workflow).flatMap(([id, job]) => {
+      if (job["runs-on"] === undefined) return [];
+      const mutation = jobRuns(workflow, job).some((run) => runsMutation(run, policy.scripts, (file) => policy.files?.get(file)));
       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 {
@@ -383,7 +377,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);
-  const faults = findRunnerFaults({ visibility: yield* readVisibility, scripts: yield* readScripts(root) }, workflows);
+  const scripts = yield* readScripts(root);
+  const runs = workflows.flatMap((workflow) => workflowJobs(workflow).flatMap(([, job]) => jobRuns(workflow, job)));
+  const faults = findRunnerFaults({ visibility: yield* readVisibility, scripts, files: yield* readShellFiles(root, scripts, runs) }, workflows);
   if (faults.length > 0) yield* Console.error(formatRunnerReport(faults));
   return gaps.length === 0 && faults.length === 0;
 });

package/src/delivery/mutation-job.ts

@@ -0,0 +1,131 @@
+import { Effect, FileSystem, Path } from "effect";
+import { fromProgram, SHELLS, shellCommands, withoutOptions, type Command } from "./shell-command.ts";
+
+// An undefined directory is one known only at run time.
+export type Run = {
+  readonly script: string;
+  readonly dir: string | undefined;
+};
+
+type Invocation =
+  | { readonly script: string; readonly body: string }
+  | { readonly program: Command; readonly file: string | undefined; readonly dir: string | undefined };
+
+type Walked = {
+  readonly scripts: readonly string[];
+  readonly files: readonly string[];
+};
+
+type Context = {
+  readonly scripts: ReadonlyMap<string, string>;
+  readonly files: (file: string) => string | undefined;
+};
+
+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 SHELL_SHEBANG = new RegExp(String.raw`^#!\s*(?:\S*\/)?(?:env\s+(?:-\S+\s+)*)?(?:${SHELLS.join("|")})(?:\s|$)`);
+const UNRESOLVED = /^[/~]|[$`]/;
+const ROOT = "";
+
+export function within(dir: string | undefined, path: string): string | undefined {
+  if (dir === undefined || UNRESOLVED.test(path)) return undefined;
+  const resolved = dir === ROOT ? [] : dir.split("/");
+  for (const part of path.split("/")) {
+    if (part === ".." && resolved.length === 0) return undefined;
+    if (part === "..") resolved.pop();
+    else if (part !== "" && part !== ".") resolved.push(part);
+  }
+  return resolved.join("/");
+}
+
+export function runsMutation(run: Run, scripts: ReadonlyMap<string, string>, files: (file: string) => string | undefined): boolean {
+  return scriptRunsMutation(run.script, run.dir, { scripts, files }, { scripts: [], files: [] });
+}
+
+function scriptRunsMutation(script: string, dir: string | undefined, context: Context, walked: Walked): boolean {
+  let cwd = dir;
+  for (const command of shellCommands(script)) {
+    const [program = "", ...args] = fromProgram(command);
+    if (program === "cd") cwd = changedDirectory(cwd, withoutOptions(args, new Set()));
+    else if (mutationCommand(command, cwd, context, walked)) return true;
+  }
+  return false;
+}
+
+function changedDirectory(cwd: string | undefined, [target]: Command): string | undefined {
+  return target === undefined || target === "-" ? undefined : within(cwd, target);
+}
+
+function bunOptions(words: Command): Command {
+  return words.slice(0, words.length - withoutOptions(words, BUN_OPERANDS).length);
+}
+
+function bunDirectory(options: Command, dir: string | undefined): string | undefined {
+  return options.reduce<string | undefined>((current, word, index) => {
+    const value = word === "--cwd" ? options[index + 1] : word.startsWith("--cwd=") ? word.slice("--cwd=".length) : undefined;
+    return value === undefined ? current : within(dir, value);
+  }, dir);
+}
+
+function fileAt(dir: string | undefined, path: string): string | undefined {
+  return within(dir, path) || undefined;
+}
+
+function invocation(command: Command, dir: string | undefined, context: Context, walked: Walked): Invocation | undefined {
+  const [first = "", ...rest] = fromProgram(command);
+  if (first !== "bun") return { program: [first, ...rest], file: first.includes("/") ? fileAt(dir, first) : undefined, dir };
+  const [subcommand = "", ...operands] = withoutOptions(rest, BUN_OPERANDS);
+  if (subcommand === "x") return invocation(["bunx", ...operands], dir, context, walked);
+  if (BUN_COMMANDS.has(subcommand)) return undefined;
+  const [target = "", ...targetArgs] = subcommand === "run" ? withoutOptions(operands, BUN_OPERANDS) : [subcommand, ...operands];
+  const cwd = bunDirectory([...bunOptions(rest), ...(subcommand === "run" ? bunOptions(operands) : [])], dir);
+  const body = walked.scripts.includes(target) ? undefined : context.scripts.get(target);
+  return body === undefined ? { program: [target, ...targetArgs], file: fileAt(cwd, target), dir: cwd } : { script: target, body };
+}
+
+function mutationCommand(command: Command, dir: string | undefined, context: Context, walked: Walked): boolean {
+  const call = invocation(command, dir, context, walked);
+  if (call === undefined) return false;
+  // bun runs a script from the directory of the package.json that names it.
+  if ("body" in call) return scriptRunsMutation(call.body, ROOT, context, { ...walked, scripts: [...walked.scripts, call.script] });
+  return mutationBin(call.program) || fileRunsMutation(call.file, call.dir, context, walked);
+}
+
+// A script file runs in its caller's directory, not its own.
+function fileRunsMutation(file: string | undefined, dir: string | undefined, context: Context, walked: Walked): boolean {
+  if (file === undefined || walked.files.includes(file)) return false;
+  const body = context.files(file);
+  return body !== undefined && scriptRunsMutation(body, dir, context, { ...walked, files: [...walked.files, file] });
+}
+
+function mutationBin([program = "", subcommand]: Command): boolean {
+  const bin = program.slice(program.lastIndexOf("/") + 1);
+  return MUTATION_BINS.includes(bin) || (bin === "stryker" && subcommand === "run");
+}
+
+function filesWanted(runs: readonly Run[], scripts: ReadonlyMap<string, string>, files: ReadonlyMap<string, string>, read: ReadonlySet<string>): readonly string[] {
+  const wanted = new Set<string>();
+  const lookup = (file: string) => {
+    if (!read.has(file)) wanted.add(file);
+    return files.get(file);
+  };
+  for (const run of runs) runsMutation(run, scripts, lookup);
+  return [...wanted];
+}
+
+export const readShellFiles = Effect.fn("readShellFiles")(function* (root: string, scripts: ReadonlyMap<string, string>, runs: readonly Run[]) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const contents = new Map<string, string>();
+  const read = new Set<string>();
+  for (let wanted = filesWanted(runs, scripts, contents, read); wanted.length > 0; wanted = filesWanted(runs, scripts, contents, read)) {
+    for (const file of wanted) {
+      read.add(file);
+      const text = yield* fs.readFileString(path.join(root, file)).pipe(Effect.orElseSucceed(() => undefined));
+      if (text !== undefined && (file.endsWith(".sh") || SHELL_SHEBANG.test(text))) contents.set(file, text);
+    }
+  }
+  return contents;
+});

package/src/delivery/shell-command.ts

@@ -70,6 +70,7 @@ const COMMAND_BREAKS = new Set(["\n", ";", "&", "|", "(", ")", "`"]);
 const WORD_BREAKS = new Set([" ", "\t"]);
 const REDIRECTS = new Set(["<", ">"]);
 const REDIRECT_OPERATOR = /^[<>][<>&|]*/;
+const DELIMITER_BREAKS = new Set([...WORD_BREAKS, ...COMMAND_BREAKS, ...REDIRECTS]);
 const FILE_DESCRIPTOR = /^\d+$/;
 const DOUBLE_QUOTE_ESCAPES = new Set(["$", "`", '"', "\\"]);
 const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
@@ -138,9 +139,19 @@ function commentEnd(script: string, from: number): number {
   return newline === -1 ? script.length : newline;
 }
 
+export const SHELLS = ["sh", "bash", "dash", "ksh", "zsh"];
+
+type Heredoc = {
+  readonly consumer: Command;
+  readonly delimiter: string;
+  readonly tabs: boolean;
+  readonly literal: boolean;
+};
+
 type ShellParse = {
   readonly commands: string[][];
   readonly substitutions: string[];
+  readonly heredocs: Heredoc[];
   words: string[];
   word: string | undefined;
   redirecting: boolean;
@@ -163,12 +174,63 @@ function endCommand(parse: ShellParse): void {
 function startRedirect(parse: ShellParse, script: string, index: number): number {
   if (parse.word !== undefined && FILE_DESCRIPTOR.test(parse.word)) parse.word = undefined;
   endWord(parse);
+  const operator = REDIRECT_OPERATOR.exec(script.slice(index))?.[0] ?? script.charAt(index);
+  if (operator === "<<") return startHeredoc(parse, script, index + operator.length);
   parse.redirecting = true;
-  return index + (REDIRECT_OPERATOR.exec(script.slice(index))?.[0].length ?? 1);
+  return index + operator.length;
+}
+
+function startHeredoc(parse: ShellParse, script: string, from: number): number {
+  const tabs = script.charAt(from) === "-";
+  let start = tabs ? from + 1 : from;
+  while (WORD_BREAKS.has(script.charAt(start))) start += 1;
+  let delimiter = "";
+  let end = start;
+  while (end < script.length && !DELIMITER_BREAKS.has(script.charAt(end))) {
+    const part = shellPart(script, end);
+    delimiter += part.text;
+    end = part.end;
+  }
+  parse.heredocs.push({ consumer: parse.words, delimiter, tabs, literal: /['"\\]/.test(script.slice(start, end)) });
+  return end;
+}
+
+function heredocBody(script: string, from: number, { delimiter, tabs }: Heredoc): Span {
+  let line = from;
+  while (line < script.length) {
+    const lineEnd = commentEnd(script, line);
+    const text = script.slice(line, lineEnd);
+    if ((tabs ? text.replace(/^\t+/, "") : text) === delimiter) return { text: script.slice(from, line), end: lineEnd + 1 };
+    line = lineEnd + 1;
+  }
+  return { text: script.slice(from), end: script.length };
+}
+
+function bodySubstitutions(body: string): readonly string[] {
+  const substitutions: string[] = [];
+  let index = 0;
+  while (index < body.length) {
+    const part = doubleQuotedPart(body, index);
+    substitutions.push(...part.substitutions);
+    index = part.end;
+  }
+  return substitutions;
+}
+
+function skipHeredocs(parse: ShellParse, script: string, from: number): number {
+  let index = from;
+  for (const heredoc of parse.heredocs.splice(0)) {
+    const body = heredocBody(script, index, heredoc);
+    const [program = ""] = fromProgram(heredoc.consumer);
+    if (SHELLS.includes(program.slice(program.lastIndexOf("/") + 1))) parse.substitutions.push(body.text);
+    else if (!heredoc.literal) parse.substitutions.push(...bodySubstitutions(body.text));
+    index = body.end;
+  }
+  return index;
 }
 
 export function shellCommands(script: string): readonly Command[] {
-  const parse: ShellParse = { commands: [], substitutions: [], words: [], word: undefined, redirecting: false };
+  const parse: ShellParse = { commands: [], substitutions: [], heredocs: [], words: [], word: undefined, redirecting: false };
   let index = 0;
   while (index < script.length) {
     const char = script.charAt(index);
@@ -178,9 +240,11 @@ export function shellCommands(script: string): readonly Command[] {
       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);
+    } else if (COMMAND_BREAKS.has(char)) {
+      endCommand(parse);
+      index = char === "\n" ? skipHeredocs(parse, script, index + 1) : index + 1;
+    } else if (WORD_BREAKS.has(char)) {
+      endWord(parse);
       index += 1;
     } else {
       const part = shellPart(script, index);