@avi2dg/checks 0.50.1 → 0.52.0

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.50.1",
+  "version": "0.52.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
+  "author": {
+    "name": "avi2d",
+    "email": "avi2dg@gmail.com"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,10 +17,14 @@
   "type": "module",
   "files": [
     "CHANGELOG.md",
+    "docs/bins.md",
     "docs/configs/",
     "docs/design.md",
     "docs/gates/",
+    "docs/how-to/",
+    "docs/shipped-files.md",
     "bunfig.toml",
+    ".bun-version",
     "commitlint.config.ts",
     "dependency-cruiser.config.js",
     "knip-base.json",
@@ -48,7 +56,9 @@
     "src/testing/mutation-refusal.ts",
     "src/testing/mutation-compare.ts",
     "src/testing/mutation-scope.ts",
+    "src/testing/mutation-scope-graph.ts",
     "src/testing/mutation-baseline.ts",
+    "src/testing/mutation-baseline-full.ts",
     "src/testing/mutation-baseline-saved.ts",
     "src/testing/subsumed-tests.ts",
     "src/testing/night-run.ts",
@@ -58,6 +68,7 @@
     "src/delivery/workflow-references.ts",
     "src/delivery/bun-pin.ts",
     "src/delivery/mutation-job.ts",
+    "src/delivery/runner-policy.ts",
     "src/delivery/secrets.ts",
     "src/delivery/gitleaks.ts",
     "src/delivery/gitleaks.toml",
@@ -93,6 +104,7 @@
     "src/docs/doc-snapshot.ts",
     "src/docs/doc-templates.ts",
     "src/docs/doc-names.ts",
+    "src/docs/doc-versions.ts",
     "dist/templates/",
     "src/quality/presets/effect.language-service.json",
     "src/quality/presets/oxlint.ts",

package/src/delivery/bun-pin.ts

@@ -2,12 +2,12 @@ import { Effect, FileSystem, Path, Schema } from "effect";
 import { within } from "./mutation-job.ts";
 import { isRecord, locate, workflowJobs, type Workflow } from "./workflow-references.ts";
 
-export const FLEET_BUN_VERSION = "1.4.3";
 const ROOT_MANIFEST = "package.json";
 
 export type BunPinPolicy = {
   readonly files: ReadonlyMap<string, string>;
   readonly manifests: ReadonlyMap<string, unknown>;
+  readonly fleet: string;
 };
 
 export type BunPinFault = {
@@ -94,12 +94,12 @@ function bunPinRequest(policy: BunPinPolicy, step: Readonly<Record<string, unkno
 function bunPinFault(policy: BunPinPolicy, step: Readonly<Record<string, unknown>>): string | undefined {
   const request = bunPinRequest(policy, step);
   if (request.expression !== undefined) {
-    return `requests bun ${request.expression} from ${request.source}, which cannot be shown equal to ${FLEET_BUN_VERSION} before the run`;
+    return `requests bun ${request.expression} from ${request.source}, which cannot be shown equal to ${policy.fleet} before the run`;
   }
   if (request.version === undefined) {
-    return `pins no bun version from ${request.source}, so setup-bun installs latest, want ${FLEET_BUN_VERSION}`;
+    return `pins no bun version from ${request.source}, so setup-bun installs latest, want ${policy.fleet}`;
   }
-  return request.version === FLEET_BUN_VERSION ? undefined : `requests bun ${request.version} from ${request.source}, want ${FLEET_BUN_VERSION}`;
+  return request.version === policy.fleet ? undefined : `requests bun ${request.version} from ${request.source}, want ${policy.fleet}`;
 }
 
 function unknownRefFault(ref: string): string {
@@ -156,6 +156,20 @@ const readJsonFile = Effect.fn("readJsonFile")(function* (file: string) {
   );
 });
 
+export class BunPinError extends Schema.TaggedError<BunPinError>()("BunPinError", {
+  message: Schema.String,
+}) {}
+
+// The kit ships its own .bun-version, so the check reads the fleet pin from that file rather than a constant.
+const kitBunVersion = Effect.gen(function* () {
+  const file = (yield* Path.Path).join(import.meta.dir, "..", "..", ".bun-version");
+  const version = (yield* (yield* FileSystem.FileSystem).readFileString(file).pipe(
+    Effect.mapError((cause) => new BunPinError({ message: `cannot read the kit .bun-version at ${file}: ${cause.message}` })),
+  )).trim();
+  if (version === "") return yield* new BunPinError({ message: `the kit .bun-version at ${file} pins no version` });
+  return version;
+});
+
 export const readBunPinPolicy = Effect.fn("readBunPinPolicy")(function* (root: string, workflows: readonly Workflow[]) {
   const path = yield* Path.Path;
   const fs = yield* FileSystem.FileSystem;
@@ -170,5 +184,5 @@ export const readBunPinPolicy = Effect.fn("readBunPinPolicy")(function* (root: s
       if (text !== undefined) files.set(name, text);
     }
   }
-  return { files, manifests };
+  return { files, manifests, fleet: yield* kitBunVersion };
 });

package/src/delivery/ci-wiring.ts

@@ -4,11 +4,13 @@ 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 { findBunPinFaults, formatBunPinReport, readBunPinPolicy } from "./bun-pin.ts";
-import { readShellFiles, runsMutation, within, type Run } from "./mutation-job.ts";
+import { readShellFiles } from "./mutation-job.ts";
+import { findRunnerFaults, formatRunnerReport, jobRuns, readRunnerConfig } from "./runner-policy.ts";
 import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
 import { findMissingWorkflows, formatMissingReport, isRecord, names, workflowJobs, type Workflow } from "./workflow-references.ts";
 
-export { FLEET_BUN_VERSION, findBunPinFaults, formatBunPinReport } from "./bun-pin.ts";
+export { BunPinError, findBunPinFaults, formatBunPinReport } from "./bun-pin.ts";
+export { RunnerPolicyError } from "./runner-policy.ts";
 export type { BunPinFault, BunPinPolicy } from "./bun-pin.ts";
 
 export type { Command };
@@ -39,17 +41,6 @@ export type Gap = {
 
 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 = {
-  readonly location: string;
-  readonly fault: string;
-};
-
 type RunStep = {
   readonly location: string;
   readonly blocker: string | undefined;
@@ -71,7 +62,9 @@ const TITLE_LINT = "bunx checks-commit-title";
 // The gate holds until every consumer migrates, so the direct commitlint call still counts.
 // The kit calls its own file through bun, since bunx never resolves the working tree.
 const TITLE_CALLS = ["bun src/delivery/commit-title.ts", "./node_modules/.bin/commitlint"];
-const Manifest = Schema.Struct({ scripts: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)) });
+const ScriptsManifest = Schema.Struct({
+  scripts: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+});
 // Without these a pull_request workflow never sees the commits a pull request pushes.
 const GATING_TYPES = ["opened", "synchronize"];
 const CONSTANTS = new Map([
@@ -79,13 +72,6 @@ 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 DEVICE_RUNNER = ["self-hosted", "macOS", "iphone"];
-const HOSTED_DEFAULT = "${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}";
 const EventRepository = Schema.fromJsonString(Schema.Struct({ repository: Schema.Struct({ private: Schema.Boolean }) }));
 
 function constant(value: unknown): boolean | undefined {
@@ -278,59 +264,6 @@ export function declarationFor(scripts: readonly string[], branch: string): Decl
   };
 }
 
-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 mutation runs 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 || sameLabels(runsOn, DEVICE_RUNNER) || (visibility !== "private" && !overridden)) return undefined;
-  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) }] : []));
-}
-
-export function findRunnerFaults(policy: RunnerPolicy, workflows: readonly Workflow[]): readonly RunnerFault[] {
-  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 {
-  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), text }),
@@ -342,10 +275,10 @@ const readScripts = Effect.fn("readScripts")(function* (root: string) {
   const file = (yield* Path.Path).join(root, "package.json");
   const { scripts = {} } = (yield* fs.exists(file))
     ? yield* fs.readFileString(file).pipe(
-        Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(Manifest))),
+        Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(ScriptsManifest))),
         Effect.mapError((cause) => new WiringError({ message: `cannot read ${file}: ${cause.message}` })),
       )
-    : Manifest.make({});
+    : ScriptsManifest.make({});
   return new Map(Object.entries(scripts));
 });
 
@@ -390,7 +323,8 @@ const wiring = Effect.gen(function* () {
   if (missing.length > 0) yield* Console.error(formatMissingReport(missing));
   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);
+  const runners = yield* readRunnerConfig(root);
+  const faults = findRunnerFaults({ visibility: yield* readVisibility, scripts, files: yield* readShellFiles(root, scripts, runs), runners }, workflows);
   if (faults.length > 0) yield* Console.error(formatRunnerReport(faults));
   const bunFaults = findBunPinFaults(yield* readBunPinPolicy(root, workflows), workflows);
   if (bunFaults.length > 0) yield* Console.error(formatBunPinReport(bunFaults));

package/src/delivery/commit-identity.ts

@@ -16,8 +16,6 @@ type Commit = {
 
 type Offence = { readonly commit: Commit; readonly reasons: readonly string[] };
 
-const DEFAULT_AUTHORS: readonly Identity[] = [{ name: "avi2d", email: "avi2dg@gmail.com" }];
-
 // GitHub writes the squash commit, so it commits what the owner authored and never authors.
 const SQUASH_COMMITTER: Identity = { name: "GitHub", email: "noreply@github.com" };
 
@@ -74,13 +72,12 @@ const allowedAuthors = Effect.gen(function* () {
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
   const fs = yield* FileSystem.FileSystem;
   const file = (yield* Path.Path).join(root, "package.json");
-  if (!(yield* fs.exists(file))) return DEFAULT_AUTHORS;
+  if (!(yield* fs.exists(file))) return [];
   const manifest = yield* fs.readFileString(file).pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(Authors))));
-  const listed = [manifest.author, ...(manifest.contributors ?? [])]
+  return [manifest.author, ...(manifest.contributors ?? [])]
     .filter((entry) => entry !== undefined)
     .map(identityOf)
     .filter((entry) => entry !== undefined);
-  return listed.length === 0 ? DEFAULT_AUTHORS : listed;
 });
 
 const readCommits = Effect.fn("readCommits")(function* (revisions: readonly string[]) {
@@ -123,11 +120,17 @@ function allows(allowed: readonly Identity[], identity: Identity): boolean {
   );
 }
 
+// GitHub authors a web merge under the account's display name, which the owner's git name need not match.
+function allowsEmail(allowed: readonly Identity[], identity: Identity): boolean {
+  return allowed.some((entry) => entry.email.toLowerCase() === identity.email.toLowerCase());
+}
+
 function inspect(commit: Commit, allowed: readonly Identity[]): Offence | undefined {
   const reasons: string[] = [];
   const release = releasedVersionOf(commit.subject) !== undefined;
   const authors = release ? [...allowed, RELEASE_AUTHOR] : allowed;
-  if (!allows(authors, commit.author)) {
+  const madeByGitHub = allows([SQUASH_COMMITTER], commit.committer);
+  if (!(madeByGitHub ? allowsEmail(authors, commit.author) : allows(authors, commit.author))) {
     reasons.push(`author ${render(commit.author)}`);
   }
   if (!allows([...allowed, SQUASH_COMMITTER], commit.committer)) {
@@ -146,6 +149,10 @@ const check = Effect.gen(function* () {
   const revisions = second === undefined ? ["-1", range] : [range];
 
   const allowed = yield* allowedAuthors;
+  if (allowed.length === 0) {
+    yield* Console.error("commit-identity: package.json declares no author or contributors, so no identity is allowed; declare the owners there");
+    return false;
+  }
   const commits = yield* readCommits(revisions);
   const offences = commits
     .map((commit) => inspect(commit, allowed))
@@ -158,7 +165,7 @@ const check = Effect.gen(function* () {
       for (const reason of reasons) lines.push(`    ${reason}`);
     }
     lines.push(`  allowed: ${allowed.map(render).join(", ")}`);
-    lines.push(`  allowed as committer only: ${render(SQUASH_COMMITTER)}`);
+    lines.push(`  allowed as committer only: ${render(SQUASH_COMMITTER)}, which also lets an allowed email author under any name`);
     lines.push(`  allowed as release author only: ${render(RELEASE_AUTHOR)}`);
     yield* Console.error(lines.join("\n"));
     return false;