@avi2dg/checks 0.64.0 → 0.65.0

package/src/delivery/release-schedule.ts

@@ -5,6 +5,7 @@ import { isRecord, locate, names, workflowJobs, type Workflow } from "./workflow
 
 export type ScheduledRelease = {
   readonly location: string;
+  readonly fault: string;
 };
 
 export type ScheduleContext = {
@@ -12,18 +13,26 @@ export type ScheduleContext = {
   readonly files: ReadonlyMap<string, string>;
 };
 
-const EMPTY: ScheduleContext = { scripts: new Map(), files: new Map() };
+export type ScheduleOwner = {
+  readonly visibility: "private" | "public" | "unknown";
+  readonly publishes: boolean;
+};
 
 const RELEASE_BINS = ["pr", "push", "tag", "publish"].flatMap((bin) => [`checks-release-${bin}`, `release-${bin}.ts`]);
+const PUBLISH_BINS = ["checks-release-publish", "release-publish.ts"];
+const NUMBER = /^\d+$/;
+const BY_HAND = "drop the schedule, so a release runs only when someone starts it";
+
+function isBinIn(bins: readonly string[], word: string): boolean {
+  return bins.some((name) => word === name || word.endsWith(`/${name}`));
+}
 
-function isReleaseBin(word: string): boolean {
-  return RELEASE_BINS.some((name) => word === name || word.endsWith(`/${name}`));
+function isPublishCommand([head = "", ...rest]: Command): boolean {
+  return (head === "npm" && rest[0] === "publish") || isBinIn(PUBLISH_BINS, head);
 }
 
 function isReleaseCommand(program: Command): boolean {
-  const [head = "", ...rest] = program;
-  if (head === "npm" && rest[0] === "publish") return true;
-  return isReleaseBin(head);
+  return isPublishCommand(program) || isBinIn(RELEASE_BINS, program[0] ?? "");
 }
 
 function localUses(job: Readonly<Record<string, unknown>>): string | undefined {
@@ -31,9 +40,10 @@ function localUses(job: Readonly<Record<string, unknown>>): string | undefined {
   return typeof uses === "string" && uses.startsWith("./") ? uses.slice(2) : undefined;
 }
 
-function workflowReleases(
+function workflowRuns(
   workflow: Workflow,
   context: ScheduleContext,
+  isBin: (program: Command) => boolean,
   byPath: ReadonlyMap<string, Workflow>,
   walkedWorkflows: readonly string[],
 ): boolean {
@@ -41,32 +51,57 @@ function workflowReleases(
   if (
     workflowJobs(workflow)
       .flatMap(([, job]) => jobRuns(workflow, job))
-      .some((run) => runsBin(run, context.scripts, files, isReleaseCommand, true))
+      .some((run) => runsBin(run, context.scripts, files, isBin, true))
   )
     return true;
   return workflowJobs(workflow).some(([, job]) => {
     const called = localUses(job);
     if (called === undefined || walkedWorkflows.includes(called)) return false;
     const next = byPath.get(called);
-    return next !== undefined && workflowReleases(next, context, byPath, [...walkedWorkflows, called]);
+    return next !== undefined && workflowRuns(next, context, isBin, byPath, [...walkedWorkflows, called]);
   });
 }
 
-function schedules(document: unknown): boolean {
+function crons(document: unknown): readonly unknown[] {
+  const on = isRecord(document) ? document["on"] : undefined;
+  const schedule = isRecord(on) ? on["schedule"] : undefined;
+  return Array.isArray(schedule) ? schedule.map((entry) => (isRecord(entry) ? entry["cron"] : undefined)) : [];
+}
+
+// At most once a day is one minute and one hour, whatever the day, month and weekday fields allow.
+export function atMostDaily(cron: unknown): boolean {
+  if (typeof cron !== "string") return false;
+  const fields = cron.trim().split(/\s+/);
+  return fields.length === 5 && NUMBER.test(fields[0] ?? "") && NUMBER.test(fields[1] ?? "");
+}
+
+// A run outside CI cannot read whether the repository is private, so only a package.json that sets private refuses there.
+function releaseFault(workflow: Workflow, owner: ScheduleOwner, publishesToNpm: boolean): string | undefined {
+  if (owner.visibility === "private" || !owner.publishes || !publishesToNpm) return "only a public package that publishes to npm releases on a schedule; " + BY_HAND;
+  const entries = crons(workflow.document);
+  if (entries.length === 1 && entries.every(atMostDaily)) return undefined;
+  return 'the release runs more than once a day; keep one cron at a minute and an hour, such as "7 3 * * *"';
+}
+
+export function schedules(document: unknown): boolean {
   const on = isRecord(document) ? document["on"] : undefined;
   return isRecord(on) ? "schedule" in on : (names(on) ?? []).includes("schedule");
 }
 
-export function findScheduledReleases(workflows: readonly Workflow[], context: ScheduleContext = EMPTY): readonly ScheduledRelease[] {
+export function releasesOnSchedule(workflows: readonly Workflow[], context: ScheduleContext): readonly Workflow[] {
   const byPath = new Map(workflows.map((workflow) => [workflow.path, workflow] as const));
-  return workflows
-    .filter((workflow) => schedules(workflow.document) && workflowReleases(workflow, context, byPath, [workflow.path]))
-    .map((workflow) => ({ location: locate(workflow.path, workflow.text.split("\n"))(["on"], "schedule", "on schedule") }));
+  return workflows.filter((workflow) => schedules(workflow.document) && workflowRuns(workflow, context, isReleaseCommand, byPath, [workflow.path]));
+}
+
+export function findScheduledReleases(workflows: readonly Workflow[], context: ScheduleContext, owner: ScheduleOwner): readonly ScheduledRelease[] {
+  const byPath = new Map(workflows.map((workflow) => [workflow.path, workflow] as const));
+  const publishesToNpm = workflows.some((workflow) => workflowRuns(workflow, context, isPublishCommand, byPath, [workflow.path]));
+  return releasesOnSchedule(workflows, context).flatMap((workflow) => {
+    const fault = releaseFault(workflow, owner, publishesToNpm);
+    return fault === undefined ? [] : [{ location: locate(workflow.path, workflow.text.split("\n"))(["on"], "schedule", "on schedule"), fault }];
+  });
 }
 
 export function formatScheduleReport(scheduled: readonly ScheduledRelease[]): string {
-  return [
-    `ci-wiring: ${scheduled.length} workflow(s) release on a schedule:`,
-    ...scheduled.map(({ location }) => `  ${location}: drop the schedule, so a release runs only when someone starts it`),
-  ].join("\n");
+  return [`ci-wiring: ${scheduled.length} workflow(s) release on a schedule:`, ...scheduled.map(({ location, fault }) => `  ${location}: ${fault}`)].join("\n");
 }

package/src/delivery/schedule-policy.ts

@@ -0,0 +1,64 @@
+import { runsBin } from "./mutation-job.ts";
+import { releasesOnSchedule, schedules } from "./release-schedule.ts";
+import { jobRuns } from "./runner-policy.ts";
+import { invokes, plainCommand, type Command } from "./shell-command.ts";
+import { isRecord, locate, workflowJobs, type Workflow } from "./workflow-references.ts";
+import type { ScheduleContext, ScheduleOwner } from "./release-schedule.ts";
+
+export type ScheduledRun = {
+  readonly location: string;
+  readonly fault: string;
+};
+
+const ADVISORY_BINS = ["checks-advisories", "advisories.ts"];
+const INSTALL = ["bun", "install"];
+const NUMBER = /^\d+$/;
+const WEEKDAY = /^(?:[0-7]|sun|mon|tue|wed|thu|fri|sat)$/i;
+const BY_HAND = "drop the schedule, so it runs only when someone starts it with gh workflow run";
+
+function isAdvisoryBin([head = ""]: Command): boolean {
+  return ADVISORY_BINS.some((name) => head === name || head.endsWith(`/${name}`));
+}
+
+function crons(document: unknown): readonly unknown[] {
+  const on = isRecord(document) ? document["on"] : undefined;
+  const schedule = isRecord(on) ? on["schedule"] : undefined;
+  return Array.isArray(schedule) ? schedule.map((entry) => (isRecord(entry) ? entry["cron"] : undefined)) : [];
+}
+
+// Once a week is one minute, one hour and one weekday, on any day of any month.
+export function weekly(cron: unknown): boolean {
+  if (typeof cron !== "string") return false;
+  const [minute = "", hour = "", day = "", month = "", weekday = "", ...rest] = cron.trim().split(/\s+/);
+  return rest.length === 0 && NUMBER.test(minute) && NUMBER.test(hour) && day === "*" && month === "*" && WEEKDAY.test(weekday);
+}
+
+function scansAdvisoriesOnly(workflow: Workflow, context: ScheduleContext): boolean {
+  const files = (file: string) => context.files.get(file);
+  const runs = workflowJobs(workflow).flatMap(([, job]) => jobRuns(workflow, job));
+  const scans = runs.filter((run) => runsBin(run, context.scripts, files, isAdvisoryBin, true));
+  return scans.length > 0 && runs.every((run) => scans.includes(run) || invokes(plainCommand(run.script), INSTALL));
+}
+
+function advisoryFault(workflow: Workflow, owner: ScheduleOwner): string | undefined {
+  if (owner.visibility === "private") return "a private repository scans advisories by hand; " + BY_HAND;
+  if (!owner.publishes) return "a package.json that sets private publishes nothing to npm, so it scans advisories by hand; " + BY_HAND;
+  const entries = crons(workflow.document);
+  if (entries.length === 1 && entries.every(weekly)) return undefined;
+  return 'the advisory scan runs more than once a week; keep one cron at a minute, an hour and a weekday, such as "15 5 * * 1"';
+}
+
+// A workflow that releases on a schedule is the release rule's to judge, so this rule passes over it.
+export function findScheduledRuns(workflows: readonly Workflow[], context: ScheduleContext, owner: ScheduleOwner): readonly ScheduledRun[] {
+  const releasing = new Set(releasesOnSchedule(workflows, context));
+  return workflows.flatMap((workflow) => {
+    if (!schedules(workflow.document) || releasing.has(workflow)) return [];
+    const fault = scansAdvisoriesOnly(workflow, context) ? advisoryFault(workflow, owner) : BY_HAND;
+    if (fault === undefined) return [];
+    return [{ location: locate(workflow.path, workflow.text.split("\n"))(["on"], "schedule", "on schedule"), fault }];
+  });
+}
+
+export function formatScheduledRunReport(scheduled: readonly ScheduledRun[]): string {
+  return [`ci-wiring: ${scheduled.length} workflow(s) run on a schedule:`, ...scheduled.map(({ location, fault }) => `  ${location}: ${fault}`)].join("\n");
+}

package/src/delivery/setup-workflow.ts

@@ -0,0 +1,43 @@
+const HOSTED_FALLBACK = "ubuntu-latest";
+const HOSTED_DEFAULT = "${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}";
+
+export function ciWorkflow(isPrivate: boolean, hasBuild: boolean): string {
+  const lines = [
+    "name: ci",
+    "",
+    "on:",
+    "  pull_request:",
+    "    types: [opened, synchronize]",
+    "",
+    "concurrency:",
+    "  group: ci-${{ github.event.pull_request.number }}",
+    "  cancel-in-progress: true",
+    "",
+    "jobs:",
+    "  checks:",
+    "    runs-on: " + (isPrivate ? HOSTED_DEFAULT : HOSTED_FALLBACK),
+    "    timeout-minutes: 30",
+    "    steps:",
+    "      - uses: actions/checkout@v5",
+    "        with:",
+    "          fetch-depth: 0",
+    "      - uses: oven-sh/setup-bun@v2",
+    "        with:",
+    "          bun-version-file: .bun-version",
+    "      - run: bun install --frozen-lockfile",
+  ];
+  if (hasBuild) {
+    lines.push("      - run: bun run build", "      - run: git diff --exit-code");
+  }
+  lines.push("      - run: bun run lint", "      - run: bun run typecheck", "      - run: bun run test");
+  lines.push(
+    "      - id: title",
+    "        name: lint the title",
+    "        env:",
+    "          PR_TITLE: ${{ github.event.pull_request.title }}",
+    "          GH_TOKEN: ${{ github.token }}",
+    "        run: bunx checks-commit-title",
+    "",
+  );
+  return lines.join("\n");
+}

package/src/delivery/setup.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { runMain, Usage } from "../core/main.ts";
+import { ciWorkflow } from "./setup-workflow.ts";
 import { TEMPLATES } from "../docs/doc-templates.ts";
 import { scriptOptions } from "../testing/test.ts";
 import { withServiceOverrides, type ServiceOverride } from "../quality/effect-scope.ts";
@@ -10,8 +11,6 @@ import severities from "../quality/presets/effect.language-service.json" with {
 const NAME = "checks-setup";
 const USAGE = "usage: " + NAME + " [--private]";
 const PRIVATE = "--private";
-const HOSTED_FALLBACK = "ubuntu-latest";
-const HOSTED_DEFAULT = "${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}";
 const IGNORE_ENTRY = "node_modules/";
 const KIT_ID = "@avi2dg/checks";
 
@@ -116,42 +115,6 @@ const KNIP_CONFIG = [
   "",
 ].join("\n");
 
-function workflow(isPrivate: boolean, hasBuild: boolean): string {
-  const lines = [
-    "name: ci",
-    "",
-    "on:",
-    "  pull_request:",
-    "    types: [opened, synchronize]",
-    "",
-    "jobs:",
-    "  checks:",
-    "    runs-on: " + (isPrivate ? HOSTED_DEFAULT : HOSTED_FALLBACK),
-    "    steps:",
-    "      - uses: actions/checkout@v5",
-    "        with:",
-    "          fetch-depth: 0",
-    "      - uses: oven-sh/setup-bun@v2",
-    "        with:",
-    "          bun-version-file: .bun-version",
-    "      - run: bun install --frozen-lockfile",
-  ];
-  if (hasBuild) {
-    lines.push("      - run: bun run build", "      - run: git diff --exit-code");
-  }
-  lines.push("      - run: bun run lint", "      - run: bun run typecheck", "      - run: bun run test");
-  lines.push(
-    "      - id: title",
-    "        name: lint the title",
-    "        env:",
-    "          PR_TITLE: ${{ github.event.pull_request.title }}",
-    "          GH_TOKEN: ${{ github.token }}",
-    "        run: bunx checks-commit-title",
-    "",
-  );
-  return lines.join("\n");
-}
-
 const kitText = Effect.fn("kitText")(function* (file: string) {
   const system = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
@@ -385,7 +348,7 @@ const check = Effect.gen(function* () {
     : OXLINT_CONFIG;
   yield* setupTsconfig(root, oxlintText);
   yield* setupFile(root, "knip.config.ts", KNIP_CONFIG);
-  yield* setupFile(root, ".github/workflows/ci.yml", workflow(isPrivate, outcome.hasBuild));
+  yield* setupFile(root, ".github/workflows/ci.yml", ciWorkflow(isPrivate, outcome.hasBuild));
   for (const kind of Object.keys(TEMPLATES)) {
     yield* setupFile(root, "templates/" + kind + ".md", yield* kitText("dist/templates/" + kind + ".md"));
   }

package/src/testing/affected-tests.ts

@@ -0,0 +1,261 @@
+import { Config, Effect, FileSystem, Option, Path, Schema } from "effect";
+import { pathsSinceMergeBase, workingTreeFiles } from "../core/git.ts";
+import { decodePullRequestEvent, pullRequestEndsOf } from "../core/lint.ts";
+import { classifyPath } from "../core/scope.ts";
+import { decodeBunfig, importedFile, importsOf, preloadPaths, resolved, TEST_TREE } from "./mutation-scope-graph.ts";
+
+export type Narrowing =
+  | { readonly kind: "full"; readonly because: string }
+  | { readonly kind: "files"; readonly files: readonly string[] };
+
+type SelfReference = {
+  readonly name: string;
+  readonly exports: ReadonlyMap<string, string>;
+};
+
+export type Repository = {
+  readonly files: readonly string[];
+  readonly sources: ReadonlyMap<string, string>;
+  readonly bins: ReadonlyMap<string, string>;
+  readonly self: SelfReference | undefined;
+  readonly preloads: readonly string[];
+};
+
+const FIXTURES = "tests/fixtures/";
+// A workflow runs the suite rather than being read by it, so a test that reads one names its path.
+const WORKFLOWS = ".github/";
+const TEST_FILE = /\.test\.tsx?$/;
+const SOURCE_FILE = /\.(?:[cm]?[jt]sx?|astro|svelte|vue|sh)$/;
+const LOCKFILES = new Set(["bun.lock", "bun.lockb", "package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml"]);
+const TOOL_PINS = new Set([".bun-version", ".npmrc", ".nvmrc", ".node-version", ".tool-versions"]);
+const CONFIG = /(?:^|\.)config\.(?:[cm]?[jt]s|json)$/;
+const STYLESHEET = /\.(?:css|scss|sass|less|pcss|styl)$/;
+const FONT = /\.(?:woff2?|ttf|otf|eot)$/;
+const LAYOUT = /^layout\./i;
+const LISTED_SEGMENTS = /["'`][ \t]*,[ \t]*["'`]/g;
+const TOKEN = /[\w.@/-]+/g;
+const LEADING_HOPS = /^(?:\.{1,2}\/|\/)+/;
+const BARE_IMPORT = /(?:from|import)\s*\(?\s*["']([^"'.][^"']*)["']|require\s*\(\s*["']([^"'.][^"']*)["']\s*\)/g;
+// Bun picks the first condition it knows, and types names no file it runs.
+const CONDITIONS = ["bun", "import", "default", "node", "require"];
+const BUILT = "the build";
+
+const basenameOf = (path: string): string => path.slice(path.lastIndexOf("/") + 1);
+const directoryNode = (directory: string): string => directory + "/";
+
+export function sharedReason(path: string, preloads: ReadonlySet<string>): string | undefined {
+  if (path.startsWith(FIXTURES)) return undefined;
+  const name = basenameOf(path);
+  const directories = path.split("/").slice(0, -1);
+  if (LOCKFILES.has(name)) return "a lockfile";
+  if ((classifyPath(path) === "workflow" && !path.startsWith(WORKFLOWS)) || CONFIG.test(name) || TOOL_PINS.has(name)) {
+    return "a config every test runs under";
+  }
+  if (preloads.has(path)) return "a file Bun preloads into every test";
+  if (path.startsWith(TEST_TREE) && !TEST_FILE.test(path)) return "a test helper";
+  if (STYLESHEET.test(name)) return "a stylesheet";
+  if (FONT.test(name) || directories.includes("fonts")) return "a font";
+  if (directories.includes("layouts") || LAYOUT.test(name)) return "a layout";
+  return undefined;
+}
+
+// A path mentioned by any trailing run of two or more of its segments, or in full, names it.
+function mentionKeys(path: string): readonly string[] {
+  const segments = path.split("/");
+  const keys = [path];
+  for (let start = 1; start <= segments.length - 2; start += 1) keys.push(segments.slice(start).join("/"));
+  return keys;
+}
+
+// Only a fixture is read by its directory; a source directory a file names is one it lists, as a runner does.
+function directoriesOf(path: string): readonly string[] {
+  if (!path.startsWith(FIXTURES)) return [];
+  const segments = path.split("/");
+  return segments.slice(1).map((_, end) => segments.slice(0, end + 1).join("/"));
+}
+
+function exportTarget(target: unknown): string | undefined {
+  if (typeof target === "string") return target;
+  if (typeof target !== "object" || target === null) return undefined;
+  const conditions: Readonly<Record<string, unknown>> = { ...target };
+  for (const condition of CONDITIONS) {
+    const found = exportTarget(conditions[condition]);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+function exportsMap(exports: unknown): ReadonlyMap<string, string> {
+  if (typeof exports === "string") return new Map([[".", resolved("", exports)]]);
+  if (typeof exports !== "object" || exports === null) return new Map();
+  const entries: Readonly<Record<string, unknown>> = { ...exports };
+  return new Map(Object.entries(entries).flatMap(([key, target]) => {
+    const file = exportTarget(target);
+    return file === undefined ? [] : [[key, resolved("", file)] as const];
+  }));
+}
+
+function selfTarget(spec: string, self: SelfReference): string | undefined {
+  if (spec !== self.name && !spec.startsWith(self.name + "/")) return undefined;
+  const subpath = spec === self.name ? "." : "./" + spec.slice(self.name.length + 1);
+  if (self.exports.size === 0) return resolved("", subpath === "." ? "index" : subpath);
+  const exact = self.exports.get(subpath);
+  if (exact !== undefined) return exact;
+  for (const [key, target] of self.exports) {
+    const star = key.indexOf("*");
+    if (star === -1) continue;
+    const [before, after] = [key.slice(0, star), key.slice(star + 1)];
+    if (subpath.startsWith(before) && subpath.endsWith(after) && subpath.length >= key.length - 1) {
+      return target.replace("*", subpath.slice(before.length, subpath.length - after.length));
+    }
+  }
+  return BUILT;
+}
+
+type Graph = { readonly readers: ReadonlyMap<string, ReadonlySet<string>>; readonly builtReaders: ReadonlySet<string> };
+
+function linkTo(readers: Map<string, Set<string>>, read: string, reader: string): void {
+  if (read === reader) return;
+  readers.set(read, (readers.get(read) ?? new Set()).add(reader));
+}
+
+function selfImports(text: string, self: SelfReference, known: ReadonlySet<string>): readonly string[] {
+  return [...text.matchAll(BARE_IMPORT)].flatMap(([, viaImport = "", viaRequire = ""]) => {
+    const target = selfTarget(viaImport || viaRequire, self);
+    if (target === undefined || target === BUILT) return target === undefined ? [] : [BUILT];
+    const found = importedFile(target, known);
+    return found.length === 0 ? [BUILT] : found;
+  });
+}
+
+function mentioned(text: string, index: ReadonlyMap<string, readonly string[]>): readonly string[] {
+  const joined = text.replaceAll(LISTED_SEGMENTS, "/");
+  return [...joined.matchAll(TOKEN)].flatMap(([token]) => index.get(token.replace(LEADING_HOPS, "").replace(/\/$/, "")) ?? []);
+}
+
+function mentionIndex(repository: Repository, known: ReadonlySet<string>): ReadonlyMap<string, readonly string[]> {
+  const index = new Map<string, string[]>();
+  const add = (key: string, node: string) => index.set(key, [...(index.get(key) ?? []), node]);
+  const directories = new Set([...known].flatMap(directoriesOf));
+  for (const file of known) for (const key of mentionKeys(file)) add(key, file);
+  for (const directory of directories) for (const key of mentionKeys(directory)) if (key.includes("/")) add(key, directoryNode(directory));
+  for (const [bin, file] of repository.bins) add(bin, file);
+  return index;
+}
+
+function graphOf(repository: Repository, changed: readonly string[]): Graph {
+  const known = new Set([...repository.files, ...changed]);
+  const index = mentionIndex(repository, known);
+  const readers = new Map<string, Set<string>>();
+  const builtReaders = new Set<string>();
+  for (const [file, text] of repository.sources) {
+    const self = repository.self === undefined ? [] : selfImports(text, repository.self, known);
+    if (self.includes(BUILT)) builtReaders.add(file);
+    const named = file.startsWith(TEST_TREE) ? mentioned(text, index) : [];
+    for (const read of [...importsOf(file, text, known), ...self.filter((target) => target !== BUILT), ...named]) {
+      linkTo(readers, read, file);
+    }
+  }
+  return { readers, builtReaders };
+}
+
+function reach(graph: Graph, changed: readonly string[], sources: ReadonlyMap<string, string>): ReadonlySet<string> {
+  const reached = new Set<string>();
+  const pending = [...changed];
+  const builds = changed.some((path) => sources.has(path) && !path.startsWith(TEST_TREE));
+  if (builds) pending.push(...graph.builtReaders);
+  for (let node = pending.pop(); node !== undefined; node = pending.pop()) {
+    if (reached.has(node)) continue;
+    reached.add(node);
+    pending.push(...(graph.readers.get(node) ?? []));
+    if (!node.endsWith("/")) pending.push(...directoriesOf(node).map(directoryNode));
+  }
+  return reached;
+}
+
+function preloadClosure(repository: Repository): ReadonlySet<string> {
+  const known = new Set(repository.files);
+  const loaded = new Set<string>();
+  for (let pending = [...repository.preloads]; pending.length > 0; ) {
+    const file = pending.pop() ?? "";
+    if (loaded.has(file)) continue;
+    loaded.add(file);
+    pending.push(...importsOf(file, repository.sources.get(file) ?? "", known));
+  }
+  return loaded;
+}
+
+// A test or its helper reads a file it imports or names by path or bin, and a source reads only what it imports, at any depth.
+// A source that names a path, as a registry does, would make every importer read every file it lists.
+export function narrowTests(changed: readonly string[], repository: Repository, tests: readonly string[]): Narrowing {
+  if (changed.length === 0) return { kind: "full", because: "the pull request changes no file" };
+  const preloads = preloadClosure(repository);
+  for (const path of changed) {
+    const reason = sharedReason(path, preloads);
+    if (reason !== undefined) return { kind: "full", because: `the pull request changes ${path}, ${reason}` };
+  }
+  const reached = reach(graphOf(repository, changed), changed, repository.sources);
+  return { kind: "files", files: tests.filter((test) => reached.has(test)) };
+}
+
+const Manifest = Schema.Struct({
+  name: Schema.optionalKey(Schema.String),
+  exports: Schema.optionalKey(Schema.Unknown),
+  bin: Schema.optionalKey(Schema.Union([Schema.String, Schema.Record(Schema.String, Schema.String)])),
+});
+const decodeManifest = Schema.decodeUnknownEffect(Schema.fromJsonString(Manifest));
+
+class NarrowingError extends Schema.TaggedError<NarrowingError>()("NarrowingError", {
+  message: Schema.String,
+}) {}
+
+function binsOf(manifest: typeof Manifest.Type): ReadonlyMap<string, string> {
+  const { bin, name } = manifest;
+  if (bin === undefined) return new Map();
+  if (typeof bin === "string") return name === undefined ? new Map() : new Map([[basenameOf(name), resolved("", bin)]]);
+  return new Map(Object.entries(bin).map(([command, file]) => [command, resolved("", file)]));
+}
+
+const readRepository = Effect.fn("readRepository")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const files = yield* workingTreeFiles(root);
+  const read = (file: string) => fs.readFileString(path.join(root, file)).pipe(Effect.orElseSucceed(() => ""));
+  const sources = new Map(yield* Effect.forEach(files.filter((file) => SOURCE_FILE.test(file)), (file) =>
+    read(file).pipe(Effect.map((text) => [file, text] as const)), { concurrency: 16 }));
+  const manifest = files.includes("package.json") ? yield* read("package.json").pipe(Effect.flatMap(decodeManifest)) : {};
+  const bunfig = files.includes("bunfig.toml")
+    ? yield* read("bunfig.toml").pipe(
+        Effect.flatMap((text) => Effect.try({ try: (): unknown => Bun.TOML.parse(text), catch: (cause) => new NarrowingError({ message: "cannot parse bunfig.toml: " + String(cause) }) })),
+        Effect.flatMap(decodeBunfig),
+      )
+    : {};
+  return {
+    files,
+    sources,
+    bins: binsOf(manifest),
+    self: manifest.name === undefined ? undefined : { name: manifest.name, exports: exportsMap(manifest.exports) },
+    preloads: preloadPaths(bunfig),
+  } satisfies Repository;
+});
+
+const pullRequestEvent = Config.all({
+  name: Config.String("GITHUB_EVENT_NAME").pipe(Config.withDefault("")),
+  path: Config.String("GITHUB_EVENT_PATH").pipe(Config.withDefault("")),
+});
+
+// Only a pull_request run has a base to diff against; every other run keeps the suite whole.
+export const readPullRequestNarrowing = Effect.fn("readPullRequestNarrowing")(function* (root: string, tests: readonly string[]) {
+  const event = yield* pullRequestEvent.pipe(Effect.orElseSucceed(() => ({ name: "", path: "" })));
+  if (event.name !== "pull_request" || event.path === "") return Option.none<Narrowing>();
+  const narrowing = Effect.gen(function* () {
+    const text = yield* (yield* FileSystem.FileSystem).readFileString(event.path);
+    const { pull_request: pullRequest } = yield* decodePullRequestEvent(text);
+    const { base, head } = pullRequestEndsOf(pullRequest);
+    const changed = yield* pathsSinceMergeBase(base, head, root);
+    return narrowTests(changed, yield* readRepository(root), tests);
+  });
+  return Option.some(yield* narrowing.pipe(
+    Effect.catch((cause) => Effect.succeed<Narrowing>({ kind: "full", because: "the pull request's changes cannot be read: " + cause.message })),
+  ));
+});

package/src/testing/mutation-scope-graph.ts

@@ -1,3 +1,5 @@
+import { Schema } from "effect";
+
 export const TEST_TREE = "tests/";
 const FIXTURES = "tests/fixtures/";
 const CANDIDATE_EXTENSIONS = [".tsx", ".ts", ".mts", ".cts", ".jsx", ".js", ".mjs", ".cjs", ".json", ".node"];
@@ -6,6 +8,17 @@ const IMPORT = /(?:from|import)\s*\(?\s*["'](\.[^"']*)["']|require\s*\(\s*["'](\
 const LISTED_SEGMENTS = /["'`][ \t]*,[ \t]*["'`]/g;
 const DIRECTORY_ENDS = ['"', "'", "`", '/"', "/'", "/`", "/${"];
 
+const Bunfig = Schema.Struct({
+  test: Schema.optionalKey(Schema.Struct({ preload: Schema.optionalKey(Schema.Union([Schema.String, Schema.Array(Schema.String)])) })),
+});
+
+export const decodeBunfig = Schema.decodeUnknownEffect(Bunfig);
+
+export function preloadPaths(bunfig: typeof Bunfig.Type): readonly string[] {
+  const preload = bunfig.test?.preload ?? [];
+  return (typeof preload === "string" ? [preload] : preload).map((entry) => resolved("", entry));
+}
+
 type Needle = { readonly text: string; readonly kind: "file" | "directory"; readonly fixture: string };
 
 export function resolved(directory: string, spec: string): string {

package/src/testing/mutation-scope.ts

@@ -3,7 +3,7 @@ import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { escape, minimatch } from "minimatch";
 import { changedPaths, git, pathsAt, pathsOf, rangeEnds, type Change } from "../core/git.ts";
 import { runMain, Usage } from "../core/main.ts";
-import { importedFile, importsOf, readersOf, resolved, TEST_TREE } from "./mutation-scope-graph.ts";
+import { decodeBunfig, importedFile, importsOf, preloadPaths, readersOf, resolved, TEST_TREE } from "./mutation-scope-graph.ts";
 
 const NAME = "mutation-scope";
 const USAGE = "usage: mutation-scope.ts <base> [full-baseline-report]";
@@ -53,12 +53,6 @@ export type Baseline = typeof BaselineSchema.Type;
 
 const decodeBaseline = Schema.decodeUnknownEffect(Schema.fromJsonString(BaselineSchema));
 
-const decodeBunfig = Schema.decodeUnknownEffect(
-  Schema.Struct({
-    test: Schema.optionalKey(Schema.Struct({ preload: Schema.optionalKey(Schema.Union([Schema.String, Schema.Array(Schema.String)])) })),
-  }),
-);
-
 export type MutationScope = { readonly scope: readonly string[]; readonly staleTests: readonly string[] };
 
 export type Picked = {
@@ -173,8 +167,7 @@ const preloadsAt = Effect.fn("preloadsAt")(function* (rev: string, paths: Readon
   const text = yield* git(["show", `${rev}:${BUNFIG}`]);
   const unparsed = () => new ScopeError({ message: `${BUNFIG} at ${rev} does not parse as TOML whose [test] preload is a path or a list of paths` });
   const bunfig = yield* Effect.try({ try: (): unknown => Bun.TOML.parse(text), catch: unparsed }).pipe(Effect.flatMap(decodeBunfig), Effect.mapError(unparsed));
-  const preload = bunfig.test?.preload ?? [];
-  return (typeof preload === "string" ? [preload] : preload).map((entry) => resolved("", entry));
+  return preloadPaths(bunfig);
 });
 
 const transitivelyImported = Effect.fn("transitivelyImported")(function* (rev: string, roots: readonly string[], paths: ReadonlySet<string>) {

package/src/testing/test-skips.ts

@@ -138,13 +138,13 @@ function declarationsIn(source: string, file: string, module: unknown): Declarat
   return { kind: "valid", declarations };
 }
 
-function selectedTierFile(file: string, tier: TestTier | undefined): boolean {
+export function selectedTierFile(file: string, tier: TestTier | undefined): boolean {
   if (file.startsWith("tests/quarantine/")) return false;
   if (tier === undefined) return !file.startsWith("tests/live/") && !file.startsWith("tests/pixel/");
   return file.startsWith(`tests/${tier}/`);
 }
 
-const scanTestFiles = Effect.fn("scanTestFiles")(function* (root: string) {
+export const scanTestFiles = Effect.fn("scanTestFiles")(function* (root: string) {
   return yield* Effect.tryPromise({
     try: () =>
       Promise.all(
@@ -156,7 +156,7 @@ const scanTestFiles = Effect.fn("scanTestFiles")(function* (root: string) {
   });
 });
 
-const readDeclarationsIn = Effect.fn("readDeclarationsIn")(function* (root: string, files: readonly string[]) {
+export const readDeclarationsIn = Effect.fn("readDeclarationsIn")(function* (root: string, files: readonly string[]) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const declarations: SkipDeclaration[] = [];