@avi2dg/checks 0.6.0 → 0.9.0

package/scripts/commit-identity.ts

@@ -1,7 +1,10 @@
 #!/usr/bin/env bun
-import { existsSync, readFileSync } from "node:fs";
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { git } from "./git.ts";
+import { runMain, Usage } from "./main.ts";
 
-type Identity = { readonly name: string; readonly email: string };
+const Identity = Schema.Struct({ name: Schema.String, email: Schema.String });
+type Identity = typeof Identity.Type;
 
 type Commit = {
   readonly sha: string;
@@ -29,80 +32,77 @@ const RECORD = "\u001e";
 
 const USAGE = "usage: commit-identity.ts <ref> | <base-ref> <head-ref>";
 
-function die(message: string): never {
-  console.error(message);
-  process.exit(2);
-}
+const Manifest = Schema.Struct({
+  commitIdentity: Schema.optional(Schema.Struct({ authors: Schema.NonEmptyArray(Identity) })),
+});
+const parseJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));
+const decodeManifest = Schema.decodeUnknownEffect(Manifest);
 
-function git(...args: readonly string[]): string {
-  const result = Bun.spawnSync(["git", ...args], { stdout: "pipe", stderr: "pipe" });
-  if (!result.success) {
-    die(`commit-identity: git ${args.join(" ")}: ${result.stderr.toString().trim()}`);
-  }
-  return result.stdout.toString();
-}
+class InvalidAllowlist extends Schema.TaggedError<InvalidAllowlist>()("InvalidAllowlist", {
+  message: Schema.String,
+}) {}
+
+class UnreadableLog extends Schema.TaggedError<UnreadableLog>()("UnreadableLog", {
+  message: Schema.String,
+}) {}
 
 function render(identity: Identity): string {
   return `${identity.name} <${identity.email}>`;
 }
 
-function isIdentity(value: unknown): value is Identity {
-  if (typeof value !== "object" || value === null) return false;
-  const candidate = value as { name?: unknown; email?: unknown };
-  return typeof candidate.name === "string" && typeof candidate.email === "string";
-}
+const allowedAuthors = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  const manifestPath = path.join(root, "package.json");
+  if (!(yield* fs.exists(manifestPath))) return DEFAULT_AUTHORS;
 
-function allowedAuthors(): readonly Identity[] {
-  const root = git("rev-parse", "--show-toplevel").trim();
-  const manifestPath = `${root}/package.json`;
-  if (!existsSync(manifestPath)) return DEFAULT_AUTHORS;
-
-  const parsed: unknown = JSON.parse(readFileSync(manifestPath, "utf8"));
-  const configured = (parsed as { commitIdentity?: unknown }).commitIdentity;
-  if (configured === undefined) return DEFAULT_AUTHORS;
-
-  const authors = (configured as { authors?: unknown }).authors;
-  if (!Array.isArray(authors) || authors.length === 0 || !authors.every(isIdentity)) {
-    die(
-      `commit-identity: ${manifestPath} sets commitIdentity without a non-empty authors array of {name, email}`,
-    );
-  }
-  return authors;
-}
+  const parsed = yield* fs.readFileString(manifestPath).pipe(
+    Effect.flatMap(parseJson),
+    Effect.mapError((cause) => new InvalidAllowlist({ message: `cannot read ${manifestPath} as JSON: ${cause.message}` })),
+  );
+  const manifest = yield* decodeManifest(parsed).pipe(
+    Effect.mapError(
+      () =>
+        new InvalidAllowlist({
+          message: `${manifestPath} sets commitIdentity without a non-empty authors array of {name, email}`,
+        }),
+    ),
+  );
+  return manifest.commitIdentity?.authors ?? DEFAULT_AUTHORS;
+});
 
-function readCommits(revisions: readonly string[]): readonly Commit[] {
+const readCommits = Effect.fn("readCommits")(function* (revisions: readonly string[]) {
   const format =
     ["%H", "%an", "%ae", "%cn", "%ce", "%s", CO_AUTHORED_BY_FORMAT].join(FIELD_FORMAT) +
     RECORD_FORMAT;
-  const log = git("log", `--format=${format}`, ...revisions);
-
-  return log
-    .split(RECORD)
-    .map((record) => record.replace(/^\n/, ""))
-    .filter((record) => record !== "")
-    .map((record) => {
-      const [sha, authorName, authorEmail, committerName, committerEmail, subject, trailers] =
-        record.split(FIELD);
-      if (
-        sha === undefined ||
-        authorName === undefined ||
-        authorEmail === undefined ||
-        committerName === undefined ||
-        committerEmail === undefined ||
-        subject === undefined ||
-        trailers === undefined
-      ) {
-        return die(`commit-identity: cannot parse git log record: ${JSON.stringify(record)}`);
-      }
-      return {
-        sha,
-        subject,
-        author: { name: authorName, email: authorEmail },
-        committer: { name: committerName, email: committerEmail },
-        coAuthoredBy: trailers.split("\n").filter((line) => line !== ""),
-      };
+  const log = yield* git(["log", `--format=${format}`, ...revisions]);
+
+  const commits: Commit[] = [];
+  for (const record of log.split(RECORD).map((one) => one.replace(/^\n/, ""))) {
+    if (record === "") continue;
+    const [sha, authorName, authorEmail, committerName, committerEmail, subject, trailers] = record.split(FIELD);
+    if (
+      sha === undefined ||
+      authorName === undefined ||
+      authorEmail === undefined ||
+      committerName === undefined ||
+      committerEmail === undefined ||
+      subject === undefined ||
+      trailers === undefined
+    ) {
+      return yield* new UnreadableLog({ message: `cannot parse git log record: ${JSON.stringify(record)}` });
+    }
+    commits.push({
+      sha,
+      subject,
+      author: { name: authorName, email: authorEmail },
+      committer: { name: committerName, email: committerEmail },
+      coAuthoredBy: trailers.split("\n").filter((line) => line !== ""),
     });
-}
+  }
+  return commits;
+});
 
 function allows(allowed: readonly Identity[], identity: Identity): boolean {
   return allowed.some(
@@ -126,28 +126,32 @@ function inspect(commit: Commit, allowed: readonly Identity[]): Offence | undefi
   return reasons.length === 0 ? undefined : { commit, reasons };
 }
 
-const [first, second, ...extra] = process.argv.slice(2);
-if (first === undefined || extra.length > 0) die(USAGE);
-const range = second === undefined ? first : `${first}..${second}`;
-const revisions = second === undefined ? ["-1", range] : [range];
-
-const allowed = allowedAuthors();
-const commits = readCommits(revisions);
-const offences = commits
-  .map((commit) => inspect(commit, allowed))
-  .filter((offence) => offence !== undefined);
-
-if (offences.length > 0) {
-  console.error(
-    `commit-identity: ${offences.length} of ${commits.length} commit(s) in ${range} carry a foreign identity:`,
-  );
-  for (const { commit, reasons } of offences) {
-    console.error(`  ${commit.sha.slice(0, 12)} ${commit.subject}`);
-    for (const reason of reasons) console.error(`    ${reason}`);
+const check = Effect.gen(function* () {
+  const [first, second, ...extra] = process.argv.slice(2);
+  if (first === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
+  const range = second === undefined ? first : `${first}..${second}`;
+  const revisions = second === undefined ? ["-1", range] : [range];
+
+  const allowed = yield* allowedAuthors;
+  const commits = yield* readCommits(revisions);
+  const offences = commits
+    .map((commit) => inspect(commit, allowed))
+    .filter((offence) => offence !== undefined);
+
+  if (offences.length > 0) {
+    const lines = [`commit-identity: ${offences.length} of ${commits.length} commit(s) in ${range} carry a foreign identity:`];
+    for (const { commit, reasons } of offences) {
+      lines.push(`  ${commit.sha.slice(0, 12)} ${commit.subject}`);
+      for (const reason of reasons) lines.push(`    ${reason}`);
+    }
+    lines.push(`  allowed: ${allowed.map(render).join(", ")}`);
+    lines.push(`  allowed as committer only: ${render(SQUASH_COMMITTER)}`);
+    yield* Console.error(lines.join("\n"));
+    return false;
   }
-  console.error(`  allowed: ${allowed.map(render).join(", ")}`);
-  console.error(`  allowed as committer only: ${render(SQUASH_COMMITTER)}`);
-  process.exit(1);
-}
 
-console.log(`commit-identity: ${commits.length} commit(s) in ${range} carry only allowed identities`);
+  yield* Console.log(`commit-identity: ${commits.length} commit(s) in ${range} carry only allowed identities`);
+  return true;
+});
+
+runMain("commit-identity", check);

package/scripts/gates.ts

@@ -0,0 +1,59 @@
+import { Schema } from "effect";
+
+export type Program = {
+  readonly bin: string;
+  readonly script: string;
+};
+
+type TrackedContent = {
+  readonly pathspecs: readonly string[];
+  readonly content: string;
+};
+
+export const EVERY_REPOSITORY = "every repository";
+
+export type KitGate = Program & {
+  readonly reads: "tree" | "range";
+  readonly appliesTo: typeof EVERY_REPOSITORY | TrackedContent;
+};
+
+export const ENTRY_POINT: Program = { bin: "checks-lint", script: "lint.ts" };
+
+export const DEFAULT_BRANCH = "main";
+
+const TYPESCRIPT_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx"], content: "TypeScript source" };
+
+export const KIT_GATES = [
+  { bin: "checks-lint-coverage", script: "lint-coverage.sh", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-test-layout", script: "test-layout.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-commit-identity", script: "commit-identity.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-comment-gate", script: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-suppressions-ratchet", script: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-ci-wiring", script: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
+] as const satisfies readonly KitGate[];
+
+const UNCONDITIONAL = KIT_GATES.filter((gate) => gate.appliesTo === EVERY_REPOSITORY).map((gate) => gate.bin);
+
+// A selection without ci-wiring would go unchecked under checks-lint, so a gate every repository runs
+// is refused where checks-lint decodes the selection, not by ci-wiring.
+export const LintGates = Schema.Array(Schema.Literals(KIT_GATES.map((gate) => gate.bin))).check(
+  Schema.makeFilter((selected) => {
+    const missing = UNCONDITIONAL.filter((bin) => !selected.includes(bin));
+    if (missing.length === 0) return true;
+    const verb = missing.length === 1 ? "applies" : "apply";
+    return `checks-lint must run ${missing.join(", ")}, which ${verb} to ${EVERY_REPOSITORY}`;
+  }),
+);
+
+export const LintWiring = Schema.Struct({
+  ciWiring: Schema.optionalKey(
+    Schema.Struct({
+      defaultBranch: Schema.optionalKey(Schema.NonEmptyString),
+      lintGates: Schema.optionalKey(LintGates),
+    }),
+  ),
+});
+
+export function selectedGates(lintGates: typeof LintGates.Type | undefined): readonly KitGate[] {
+  return lintGates === undefined ? KIT_GATES : KIT_GATES.filter((gate) => lintGates.includes(gate.bin));
+}

package/scripts/git.ts

@@ -0,0 +1,41 @@
+import { Effect, Schema, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+export class GitFailure extends Schema.TaggedError<GitFailure>()("GitFailure", {
+  message: Schema.String,
+}) {}
+
+const text = <E>(bytes: Stream.Stream<Uint8Array, E>): Effect.Effect<string, E> =>
+  bytes.pipe(Stream.decodeText(), Stream.mkString);
+
+// Both pipes drain while git runs: one left unread fills its buffer and stalls git.
+export const git = Effect.fn("git")(
+  function* (args: readonly string[], cwd?: string) {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const command = `git ${args.join(" ")}`;
+    const failed = (stderr: string): GitFailure => new GitFailure({ message: `${command}: ${stderr.trim()}` });
+    const handle = yield* spawner
+      .spawn(ChildProcess.make("git", args, { cwd }))
+      .pipe(Effect.mapError((cause) => failed(cause.message)));
+    const [stdout, stderr, exitCode] = yield* Effect.all([text(handle.stdout), text(handle.stderr), handle.exitCode], {
+      concurrency: "unbounded",
+    }).pipe(Effect.mapError((cause) => failed(cause.message)));
+    if (exitCode !== ChildProcessSpawner.ExitCode(0)) return yield* failed(stderr);
+    return stdout;
+  },
+  Effect.scoped,
+);
+
+function namesAParent(commitObject: string): boolean {
+  const [headers = ""] = commitObject.split("\n\n", 1);
+  return headers.split("\n").some((header) => header.startsWith("parent "));
+}
+
+// A shallow clone's boundary commit reads as parentless to rev-parse and log, and judged against
+// the empty tree it would carry the whole repository; only the commit object still names its parents.
+export const parentOrEmptyTree = Effect.fn("parentOrEmptyTree")(function* (rev: string, cwd?: string) {
+  if (!namesAParent(yield* git(["cat-file", "commit", rev], cwd))) {
+    return (yield* git(["hash-object", "-t", "tree", "/dev/null"], cwd)).trim();
+  }
+  return (yield* git(["rev-parse", "--verify", `${rev}^`], cwd)).trim();
+});

package/scripts/lint-coverage.sh

@@ -12,15 +12,21 @@ if ! [ -s "$tmp/expected" ]; then
 fi
 
 # Explicit paths bypass ignore files, so only an unscoped walk proves coverage.
-oxlint --debug=files 2>/dev/null | grep -E '\.tsx?$' | LC_ALL=C sort > "$tmp/walked" || true
+if ! oxlint --debug=files > "$tmp/walk" 2> "$tmp/walk-error"; then
+  echo "lint-coverage: oxlint could not walk the tree:"
+  cat "$tmp/walk" "$tmp/walk-error"
+  exit 2
+fi
+grep -E '\.tsx?$' "$tmp/walk" | LC_ALL=C sort > "$tmp/walked" || true
 
 expected_count="$(wc -l < "$tmp/expected" | tr -d ' ')"
 walked_count="$(grep -c . "$tmp/walked" || true)"
 
-missing="$(comm -23 "$tmp/expected" "$tmp/walked")"
-if [ -n "$missing" ]; then
-  echo "lint-coverage: oxlint skips ${walked_count}/${expected_count} tracked .ts/.tsx files; missing:"
-  printf '%s\n' "$missing"
+comm -23 "$tmp/expected" "$tmp/walked" > "$tmp/missing"
+if [ -s "$tmp/missing" ]; then
+  missing_count="$(wc -l < "$tmp/missing" | tr -d ' ')"
+  echo "lint-coverage: oxlint skips ${missing_count}/${expected_count} tracked .ts/.tsx files; missing:"
+  cat "$tmp/missing"
   exit 1
 fi
 

package/scripts/lint.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env bun
+import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { DEFAULT_BRANCH, LintWiring, selectedGates, type KitGate } from "./gates.ts";
+import { git } from "./git.ts";
+import { runMain, Usage } from "./main.ts";
+
+type Range = {
+  readonly refs: readonly [tip: string] | readonly [base: string, head: string];
+  readonly source: string;
+};
+
+type Outcome = "passed" | "violated" | "undecided";
+
+class RangeUnresolved extends Schema.TaggedError<RangeUnresolved>()("RangeUnresolved", {
+  message: Schema.String,
+}) {}
+
+class GatesUndecided extends Schema.TaggedError<GatesUndecided>()("GatesUndecided", {
+  message: Schema.String,
+}) {}
+
+class WiringUnreadable extends Schema.TaggedError<WiringUnreadable>()("WiringUnreadable", {
+  message: Schema.String,
+}) {}
+
+const NAME = "checks-lint";
+const USAGE = "usage: lint.ts [<base-ref> <head-ref>]";
+const PULL_REQUEST_EVENT = "pull_request";
+const SHALLOW_HINT = "a CI checkout needs actions/checkout fetch-depth: 0";
+
+const decodePullRequestEvent = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(
+    Schema.Struct({
+      pull_request: Schema.Struct({
+        number: Schema.Int,
+        base: Schema.Struct({ ref: Schema.String }),
+        head: Schema.Struct({ sha: Schema.String }),
+      }),
+    }),
+  ),
+);
+
+const pullRequestEnds = Effect.fn("pullRequestEnds")(function* (eventPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const { pull_request: pullRequest } = yield* fs.readFileString(eventPath).pipe(
+    Effect.flatMap(decodePullRequestEvent),
+    Effect.mapError(
+      (cause) => new RangeUnresolved({ message: `cannot read the pull request from ${eventPath}: ${cause.message}` }),
+    ),
+  );
+  return {
+    base: `origin/${pullRequest.base.ref}`,
+    head: pullRequest.head.sha,
+    source: `pull request #${pullRequest.number} into ${pullRequest.base.ref}`,
+  };
+});
+
+const decodeWiring = Schema.decodeUnknownEffect(Schema.fromJsonString(LintWiring));
+
+const readWiring = Effect.gen(function* () {
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  const manifest = (yield* Path.Path).join(root, "package.json");
+  const { ciWiring } = yield* (yield* FileSystem.FileSystem).readFileString(manifest).pipe(
+    Effect.flatMap(decodeWiring),
+    Effect.mapError((cause) => new WiringUnreadable({ message: `cannot read ciWiring from ${manifest}: ${cause.message}` })),
+  );
+  return { defaultBranch: ciWiring?.defaultBranch ?? DEFAULT_BRANCH, lintGates: ciWiring?.lintGates };
+});
+
+const originEnds = (defaultBranch: string) =>
+  git(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]).pipe(
+    Effect.map((ref) => ref.trim()),
+    Effect.catchTag("GitFailure", () => Effect.succeed(`origin/${defaultBranch}`)),
+    Effect.map((base) => ({ base, head: "HEAD", source: `HEAD against ${base}` })),
+  );
+
+// A clone holding any remote-tracking ref but not the default branch is a shallow CI checkout,
+// where judging HEAD alone would pass every commit before it unchecked.
+const localEnds = Effect.fn("localEnds")(function* (defaultBranch: string) {
+  const remoteTracking = yield* git(["for-each-ref", "--count=1", "refs/remotes/"]).pipe(
+    Effect.mapError((cause) => new RangeUnresolved({ message: cause.message })),
+  );
+  if (remoteTracking.trim() === "") {
+    return { base: "HEAD", head: "HEAD", source: "HEAD alone, as the clone has no remote-tracking refs" };
+  }
+  return yield* originEnds(defaultBranch);
+});
+
+const endsOf = Effect.fn("endsOf")(function* (args: readonly string[], defaultBranch: string) {
+  const [base, head, ...extra] = args;
+  if (base !== undefined && head !== undefined && extra.length === 0) {
+    return { base, head, source: `${head} against ${base}` };
+  }
+  if (base !== undefined) return yield* new Usage({ message: USAGE });
+
+  const event = yield* Config.all({
+    name: Config.option(Config.String("GITHUB_EVENT_NAME")),
+    path: Config.option(Config.String("GITHUB_EVENT_PATH")),
+  }).pipe(Effect.mapError((cause) => new RangeUnresolved({ message: cause.message })));
+  if (Option.isSome(event.name) && event.name.value === PULL_REQUEST_EVENT) {
+    if (Option.isNone(event.path)) {
+      return yield* new RangeUnresolved({ message: `${PULL_REQUEST_EVENT} sets no GITHUB_EVENT_PATH` });
+    }
+    return yield* pullRequestEnds(event.path.value);
+  }
+  return yield* localEnds(defaultBranch);
+});
+
+const commitOf = (ref: string) =>
+  git(["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`]).pipe(
+    Effect.map((sha) => sha.trim()),
+    Effect.mapError(
+      (cause) => new RangeUnresolved({ message: `${ref} is not a commit in this clone; ${SHALLOW_HINT}: ${cause.message}` }),
+    ),
+  );
+
+// From the base branch's tip, every range gate would charge the head with the commits the base
+// branch gained after the head branched off.
+const resolveRange = Effect.fn("resolveRange")(function* (args: readonly string[], defaultBranch: string) {
+  const ends = yield* endsOf(args, defaultBranch);
+  const head = yield* commitOf(ends.head);
+  const base = yield* git(["merge-base", yield* commitOf(ends.base), head]).pipe(
+    Effect.map((sha) => sha.trim()),
+    Effect.mapError(
+      () => new RangeUnresolved({ message: `${ends.base} and ${ends.head} share no commit in this clone; ${SHALLOW_HINT}` }),
+    ),
+  );
+  return { refs: base === head ? [head] : [base, head], source: ends.source } satisfies Range;
+});
+
+function describe({ refs }: Range): string {
+  return refs.length === 1 ? `tip ${refs[0]}` : `range ${refs[0]}..${refs[1]}`;
+}
+
+function outcomeOf(exitCode: number): Outcome {
+  if (exitCode === 0) return "passed";
+  return exitCode === 1 ? "violated" : "undecided";
+}
+
+const runGate = Effect.fn("runGate")(function* (gate: KitGate, range: Range) {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const script = (yield* Path.Path).join(import.meta.dir, gate.script);
+  const program = gate.script.endsWith(".sh") ? "sh" : process.execPath;
+  const args = gate.reads === "range" ? [script, ...range.refs] : [script];
+  const exitCode = yield* spawner
+    .exitCode(ChildProcess.make(program, args, { stdin: "ignore", stdout: "inherit", stderr: "inherit" }))
+    .pipe(
+      Effect.catch((cause) =>
+        Console.error(`${NAME}: cannot run ${gate.bin}: ${cause.message}`).pipe(Effect.as(ChildProcessSpawner.ExitCode(2))),
+      ),
+    );
+  return { gate, outcome: outcomeOf(exitCode) };
+});
+
+const lint = Effect.gen(function* () {
+  const { defaultBranch, lintGates } = yield* readWiring;
+  const range = yield* resolveRange(process.argv.slice(2), defaultBranch);
+  yield* Console.log(`${NAME}: ${describe(range)} from ${range.source}`);
+  const gates = selectedGates(lintGates);
+  if (lintGates !== undefined) {
+    yield* Console.log(`${NAME}: ciWiring.lintGates selects ${gates.map((gate) => gate.bin).join(", ")}`);
+  }
+
+  const verdicts = yield* Effect.forEach(gates, (gate) => runGate(gate, range));
+  const failed = verdicts.filter((verdict) => verdict.outcome !== "passed");
+  if (failed.length === 0) {
+    yield* Console.log(`${NAME}: ${gates.length} gate(s) pass`);
+    return true;
+  }
+  const summary = `${failed.length} of ${gates.length} gate(s) failed: ${failed.map((verdict) => verdict.gate.bin).join(", ")}`;
+  if (failed.every((verdict) => verdict.outcome === "undecided")) {
+    return yield* new GatesUndecided({ message: summary });
+  }
+  yield* Console.error(`${NAME}: ${summary}`);
+  return false;
+});
+
+if (import.meta.main) runMain(NAME, lint);

package/scripts/main.ts

@@ -0,0 +1,28 @@
+import { BunRuntime, BunServices } from "@effect/platform-bun";
+import { Cause, Console, Effect, Exit, Schema } from "effect";
+
+const PASSED = 0;
+const VIOLATED = 1;
+const UNDECIDED = 2;
+const INTERRUPTED = 130;
+
+export class Usage extends Schema.TaggedError<Usage>()("Usage", {
+  message: Schema.String,
+}) {}
+
+function statusOf<A, E>(exit: Exit.Exit<A, E>): number {
+  if (Exit.isSuccess(exit)) return typeof exit.value === "number" ? exit.value : UNDECIDED;
+  return Cause.hasInterruptsOnly(exit.cause) ? INTERRUPTED : UNDECIDED;
+}
+
+export function runMain<E extends { readonly message: string }>(
+  name: string,
+  passes: Effect.Effect<boolean, E, BunServices.BunServices>,
+): void {
+  const program = passes.pipe(
+    Effect.map((passed) => (passed ? PASSED : VIOLATED)),
+    Effect.catch((failure) => Console.error(`${name}: ${failure.message}`).pipe(Effect.as(UNDECIDED))),
+    Effect.provide(BunServices.layer),
+  );
+  BunRuntime.runMain(program, { teardown: (exit, onExit) => onExit(statusOf(exit)) });
+}