@avi2dg/checks 0.17.0 → 0.19.0

package/scripts/prose-matchers.ts

@@ -97,59 +97,70 @@ function targetOf(destination: string): string {
   return trimmed.split(/\s/, 1)[0] ?? "";
 }
 
+type Masking = { readonly raw: string; readonly out: string[]; readonly code: string[]; readonly links: string[]; inComment: boolean };
+
+function hide(masking: Masking, from: number, to: number, fill: string): void {
+  for (let at = from; at < to; at += 1) masking.out[at] = fill;
+}
+
+// A step returns an index past `at`, or undefined when its token does not start there.
+function commentStep(masking: Masking, at: number): number | undefined {
+  const { raw } = masking;
+  if (!masking.inComment) {
+    if (!raw.startsWith("<!--", at)) return undefined;
+    hide(masking, at, at + 4, BLANK);
+    masking.inComment = true;
+    return at + 4;
+  }
+  const close = raw.indexOf("-->", at);
+  const end = close < 0 ? raw.length : close + 3;
+  hide(masking, at, end, BLANK);
+  masking.inComment = close < 0;
+  return end;
+}
+
+function codeSpanStep(masking: Masking, at: number): number | undefined {
+  const { raw } = masking;
+  if (raw.charAt(at) !== "`") return undefined;
+  const run = runOf(raw, at, "`");
+  const close = closingRun(raw, at + run, run);
+  if (close < 0) return at + run;
+  masking.code.push(raw.slice(at + run, close).trim());
+  hide(masking, at, close + run, HIDDEN);
+  return close + run;
+}
+
+function linkStep(masking: Masking, at: number): number | undefined {
+  const { raw } = masking;
+  const end = raw.startsWith("](", at) ? destinationEnd(raw, at + 1) : -1;
+  if (end < 0) return undefined;
+  masking.links.push(targetOf(raw.slice(at + 2, end)));
+  hide(masking, at + 1, end + 1, HIDDEN);
+  return end + 1;
+}
+
+function hiddenStep(masking: Masking, at: number): number | undefined {
+  const hidden = hiddenAt(masking.raw, at, masking.raw.slice(at));
+  if (hidden === undefined) return undefined;
+  hide(masking, at, at + hidden.length, hidden.fill);
+  return at + hidden.length;
+}
+
+const MASK_STEPS = [commentStep, codeSpanStep, linkStep, hiddenStep];
+
+function maskStep(masking: Masking, at: number): number {
+  for (const step of MASK_STEPS) {
+    const next = step(masking, at);
+    if (next !== undefined) return next;
+  }
+  return at + 1;
+}
+
 function mask(raw: string, startsInComment: boolean): Masked {
-  const out = raw.split("");
-  const code: string[] = [];
-  const links: string[] = [];
-  const hide = (from: number, to: number, fill: string): void => {
-    for (let at = from; at < to; at += 1) out[at] = fill;
-  };
-  let inComment = startsInComment;
+  const masking: Masking = { raw, out: raw.split(""), code: [], links: [], inComment: startsInComment };
   let at = 0;
-  while (at < raw.length) {
-    if (inComment) {
-      const close = raw.indexOf("-->", at);
-      const end = close < 0 ? raw.length : close + 3;
-      hide(at, end, BLANK);
-      inComment = close < 0;
-      at = end;
-      continue;
-    }
-    const rest = raw.slice(at);
-    if (rest.startsWith("<!--")) {
-      hide(at, at + 4, BLANK);
-      inComment = true;
-      at += 4;
-      continue;
-    }
-    if (rest.startsWith("`")) {
-      const run = runOf(raw, at, "`");
-      const close = closingRun(raw, at + run, run);
-      if (close >= 0) {
-        code.push(raw.slice(at + run, close).trim());
-        hide(at, close + run, HIDDEN);
-        at = close + run;
-      } else at += run;
-      continue;
-    }
-    if (rest.startsWith("](")) {
-      const end = destinationEnd(raw, at + 1);
-      if (end >= 0) {
-        links.push(targetOf(raw.slice(at + 2, end)));
-        hide(at + 1, end + 1, HIDDEN);
-        at = end + 1;
-        continue;
-      }
-    }
-    const hidden = hiddenAt(raw, at, rest);
-    if (hidden !== undefined) {
-      hide(at, at + hidden.length, hidden.fill);
-      at += hidden.length;
-      continue;
-    }
-    at += 1;
-  }
-  return { prose: out.join(""), code, links, inComment };
+  while (at < raw.length) at = maskStep(masking, at);
+  return { prose: masking.out.join(""), code: masking.code, links: masking.links, inComment: masking.inComment };
 }
 
 const FENCE = /^\s*(`{3,}|~{3,})(.*)$/;
@@ -191,42 +202,41 @@ function settext(lines: MarkdownLine[]): MarkdownLine[] {
   });
 }
 
+function frontMatterLength(raws: readonly string[]): number {
+  if (raws[0] !== "---") return 0;
+  const close = raws.findIndex((raw, index) => index > 0 && (raw === "---" || raw === "..."));
+  return close < 0 ? raws.length : close + 1;
+}
+
+type Scanning = { fence: string | undefined; inComment: boolean; inHtmlBlock: boolean };
+
+function scanLine(line: number, raw: string, scanning: Scanning): MarkdownLine {
+  if (scanning.fence !== undefined) {
+    if (fenceCloses(raw, scanning.fence)) scanning.fence = undefined;
+    return unread(line, raw, "code");
+  }
+  const opener = scanning.inComment ? undefined : fenceOpener(raw);
+  if (opener !== undefined) {
+    scanning.fence = opener;
+    return unread(line, raw, "code");
+  }
+  const definition = scanning.inComment ? null : DEFINITION.exec(raw);
+  if (definition !== null) return { ...unread(line, raw, "definition"), links: [targetOf(definition[1] ?? "")] };
+  const masked = mask(raw, scanning.inComment);
+  scanning.inComment = masked.inComment;
+  const kind = kindOf(raw, masked.prose);
+  // An HTML block runs to the next blank line, whatever its later lines open with.
+  scanning.inHtmlBlock = kind === "html" || (scanning.inHtmlBlock && kind !== "blank");
+  return { line, kind: scanning.inHtmlBlock ? "html" : kind, raw, prose: masked.prose, code: masked.code, links: masked.links };
+}
+
 export function scanMarkdown(text: string): readonly MarkdownLine[] {
   const raws = text.split("\n").map((raw) => raw.replace(/\r$/, ""));
+  const frontMatter = frontMatterLength(raws);
+  const scanning: Scanning = { fence: undefined, inComment: false, inHtmlBlock: false };
   const lines: MarkdownLine[] = [];
-  let fence: string | undefined;
-  let inComment = false;
-  let inHtmlBlock = false;
-  let frontMatter = raws[0] === "---";
   for (const [index, raw] of raws.entries()) {
-    const line = index + 1;
-    if (frontMatter) {
-      frontMatter = index === 0 || (raw !== "---" && raw !== "...");
-      lines.push(unread(line, raw, "front-matter"));
-      continue;
-    }
-    if (fence !== undefined) {
-      if (fenceCloses(raw, fence)) fence = undefined;
-      lines.push(unread(line, raw, "code"));
-      continue;
-    }
-    const opener = inComment ? undefined : fenceOpener(raw);
-    if (opener !== undefined) {
-      fence = opener;
-      lines.push(unread(line, raw, "code"));
-      continue;
-    }
-    const definition = inComment ? null : DEFINITION.exec(raw);
-    if (definition !== null) {
-      lines.push({ ...unread(line, raw, "definition"), links: [targetOf(definition[1] ?? "")] });
-      continue;
-    }
-    const masked = mask(raw, inComment);
-    inComment = masked.inComment;
-    const kind = kindOf(raw, masked.prose);
-    // An HTML block runs to the next blank line, whatever its later lines open with.
-    inHtmlBlock = kind === "html" || (inHtmlBlock && kind !== "blank");
-    lines.push({ line, kind: inHtmlBlock ? "html" : kind, raw, prose: masked.prose, code: masked.code, links: masked.links });
+    lines.push(index < frontMatter ? unread(index + 1, raw, "front-matter") : scanLine(index + 1, raw, scanning));
   }
   return settext(lines);
 }

package/scripts/quality-file.ts

@@ -91,10 +91,33 @@ const EffectSources = Schema.Struct({
   ),
 });
 
+const Library = Schema.Struct({
+  name: Schema.String.check(
+    Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { expected: "a library name in kebab case" }),
+  ).annotate({ description: "The link checks-vendor manages under repos/" }),
+  package: Schema.NonEmptyString.annotate({ description: "The npm package whose installed version picks the tag" }),
+  repository: Schema.NonEmptyString.annotate({ description: "The git remote checks-vendor clones the tag from" }),
+  tag: Schema.String.check(Schema.isPattern(/\{version\}/, { expected: "a tag template holding {version}" })).annotate({
+    description: "The tag template, with {version} for the installed version",
+  }),
+  path: Schema.optionalKey(
+    FilePath.annotate({ description: "The manifest inside the clone holding the version; package.json when absent" }),
+  ),
+}).annotate({ identifier: "Library" });
+export type Library = typeof Library.Type;
+
 const Sources = Schema.Struct({
   production: Schema.optionalKey(
     Schema.Array(PathGlob).annotate({ description: "The source the repository ships, as against tests and tooling" }),
   ),
+  libraries: Schema.optionalKey(
+    Schema.Array(Library).check(
+      Schema.makeFilter((libraries) => {
+        const repeated = duplicates(libraries.map((library) => library.name));
+        return repeated === undefined || `names ${repeated} more than once`;
+      }),
+    ).annotate({ description: "The libraries checks-vendor pins to a shared read-only clone" }),
+  ),
   effect: Schema.optionalKey(EffectSources),
 });
 
@@ -124,11 +147,15 @@ function nests(outer: string, inner: string): boolean {
   return outer === inner || inner.startsWith(`${outer}/`);
 }
 
+function duplicates(names: readonly string[]): string | undefined {
+  const repeated = names.filter((name, index) => names.indexOf(name) !== index);
+  return repeated.length === 0 ? undefined : [...new Set(repeated)].join(", ");
+}
+
 const Features = Schema.Array(Feature).check(
   Schema.makeFilter((features) => {
-    const names = features.map((feature) => feature.name);
-    const repeated = names.filter((name, index) => names.indexOf(name) !== index);
-    if (repeated.length > 0) return `names ${[...new Set(repeated)].join(", ")} more than once`;
+    const repeated = duplicates(features.map((feature) => feature.name));
+    if (repeated !== undefined) return `names ${repeated} more than once`;
     for (const outer of features) {
       const inner = features.find((other) => other !== outer && nests(outer.root, other.root));
       if (inner !== undefined) return `gives ${inner.root} to both ${outer.name} and ${inner.name}`;

package/scripts/quality.ts

@@ -1,16 +1,21 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import kitOxlint from "../oxlintrc.json" with { type: "json" };
+import kitManifest from "../package.json" with { type: "json" };
 import effectLanguageService from "../presets/effect.language-service.json" with { type: "json" };
 import effectOxlint from "../presets/effect.oxlint.json" with { type: "json" };
 import { git } from "./git.ts";
+import { DEFAULT_BRANCH } from "./gates.ts";
 import { runMain, Usage } from "./main.ts";
-import { readQuality, renderJson, type Quality } from "./quality-file.ts";
+import { QualityUnreadable, readQuality, renderJson, type Quality } from "./quality-file.ts";
+import { invokes, plainCommand } from "./shell-command.ts";
 
 // oxlint resolves an override's files, and the language service an override's include, against the
 // directory of the config that holds it, so a fragment anywhere but the root matches nothing there.
 export const OXLINT_FRAGMENT = "oxlintrc.quality.json";
 export const TSCONFIG_FRAGMENT = "tsconfig.quality.json";
+export const SUITE_WORKFLOW = ".github/workflows/ci.yml";
+export const COMMITLINT_WORKFLOW = ".github/workflows/commitlint.yml";
 
 const NAME = "checks-quality";
 const USAGE = `usage: ${NAME} --check | generate`;
@@ -25,6 +30,16 @@ export type Fragment = {
   readonly content: unknown;
 };
 
+export type GeneratedWorkflow = {
+  readonly file: typeof SUITE_WORKFLOW | typeof COMMITLINT_WORKFLOW;
+  readonly content: string;
+};
+
+export type WorkflowRecipe = {
+  readonly commitlintConfig: string;
+  readonly bunVersionFile: boolean;
+};
+
 class NativeConfigUnreadable extends Schema.TaggedError<NativeConfigUnreadable>()("NativeConfigUnreadable", {
   message: Schema.String,
 }) {}
@@ -51,14 +66,86 @@ function tsconfigFragment({ paths, exempt = [] }: EffectSources): unknown {
 }
 
 const FRAGMENTS = [
-  { file: OXLINT_FRAGMENT, extendedBy: ".oxlintrc.json", reader: "oxlint", build: oxlintFragment },
-  { file: TSCONFIG_FRAGMENT, extendedBy: "tsconfig.json", reader: "the language service", build: tsconfigFragment },
+  {
+    file: OXLINT_FRAGMENT,
+    extendedBy: ".oxlintrc.json",
+    reader: "oxlint",
+    kitConfig: "./node_modules/@avi2dg/checks/oxlintrc.json",
+    kitRepositoryConfig: "./oxlintrc.json",
+    kitConfigReason: "so the kit's oxlint rules are not loaded",
+    build: oxlintFragment,
+  },
+  {
+    file: TSCONFIG_FRAGMENT,
+    extendedBy: "tsconfig.json",
+    reader: "the language service",
+    kitConfig: "@avi2dg/checks/tsconfig.effect.json",
+    kitRepositoryConfig: "./tsconfig.effect.json",
+    kitConfigReason: "the one accepted spelling of the kit's Effect config",
+    build: tsconfigFragment,
+  },
 ] as const;
 
 export function fragmentsFor(quality: Quality): readonly Fragment[] {
   const effect = quality.sources?.effect;
   if (effect === undefined) return [];
-  return FRAGMENTS.map(({ build, ...fragment }) => ({ ...fragment, content: build(effect) }));
+  return FRAGMENTS.map(({ file, extendedBy, reader, build }) => ({ file, extendedBy, reader, content: build(effect) }));
+}
+
+const OWN_COMMITLINT_CONFIG = "./commitlint.config.js";
+const KIT_COMMITLINT_CONFIG = "./node_modules/@avi2dg/checks/commitlint.config.js";
+
+function titleLint(commitlintConfig: string): string {
+  return `./node_modules/.bin/commitlint --config ${commitlintConfig} --edit "$RUNNER_TEMP/pr-title"`;
+}
+
+function runsInTitleLint(gate: string, commitlintConfig: string): boolean {
+  const words = plainCommand(gate);
+  return words !== undefined && invokes(plainCommand(titleLint(commitlintConfig)), words);
+}
+
+function runScalar(command: string): string {
+  return /(^[\s#&*!|>@`'"%{[-])|:\s|\s#|:$|[\n\\]/.test(command) ? JSON.stringify(command) : command;
+}
+
+export function commitlintWorkflow(commitlintConfig: string): string {
+  return `on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+jobs:
+  commitlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      # Only the title is linted: it is what a squash merge lands, with GitHub appending " (#N)" to it.
+      - run: printf '%s' "$PR_TITLE (#0000)" > "$RUNNER_TEMP/pr-title"
+        env:
+          PR_TITLE: \${{ github.event.pull_request.title }}
+      - run: ${titleLint(commitlintConfig)}
+`;
+}
+
+export function suiteWorkflow(defaultBranch: string, gates: readonly string[], bunVersionFile: boolean): string {
+  const setup = bunVersionFile
+    ? "      - uses: oven-sh/setup-bun@v2\n        with:\n          bun-version-file: .bun-version\n"
+    : "      - uses: oven-sh/setup-bun@v2\n";
+  const steps = gates.map((gate) => `      - run: ${runScalar(gate)}\n`).join("");
+  return `name: ci\non:\n  push:\n    branches: [${defaultBranch}]\n  pull_request:\n    types: [opened, edited, synchronize, reopened]\njobs:\n  checks:\n    runs-on: ubuntu-latest\n    steps:\n      # The head, not GitHub's merge ref, so the tree the gates read is the commit the range ends at.\n      # The whole history, since the range starts where the head branched from the base branch.\n      - uses: actions/checkout@v5\n        with:\n          ref: \${{ github.event.pull_request.head.sha || github.sha }}\n          fetch-depth: 0\n${setup}      - run: bun install --frozen-lockfile\n${steps}`;
+}
+
+export function workflowsFor(quality: Quality, recipe: WorkflowRecipe): readonly GeneratedWorkflow[] {
+  const commitlint: GeneratedWorkflow = {
+    file: COMMITLINT_WORKFLOW,
+    content: commitlintWorkflow(recipe.commitlintConfig),
+  };
+  if (quality.gates?.ci === undefined) return [commitlint];
+  const suite = quality.gates.ci.filter((gate) => !runsInTitleLint(gate, recipe.commitlintConfig));
+  return [
+    { file: SUITE_WORKFLOW, content: suiteWorkflow(quality.defaultBranch ?? DEFAULT_BRANCH, suite, recipe.bunVersionFile) },
+    commitlint,
+  ];
 }
 
 const NativeConfig = Schema.Struct({
@@ -94,11 +181,24 @@ const sameJson = (text: string, content: unknown): Effect.Effect<boolean> =>
     Effect.orElseSucceed(() => false),
   );
 
+const decodePackageName = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ name: Schema.optionalKey(Schema.String) })));
+
+const isKit = Effect.fn("isKit")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const manifest = (yield* Path.Path).join(root, "package.json");
+  if (!(yield* fs.exists(manifest))) return false;
+  const { name } = yield* decodePackageName(yield* fs.readFileString(manifest)).pipe(
+    Effect.mapError((cause) => new QualityUnreadable({ message: `package.json: ${cause.message}` })),
+  );
+  return name === kitManifest.name;
+});
+
 const fragmentProblems = Effect.fn("fragmentProblems")(function* (root: string, source: string, expected: readonly Fragment[]) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const problems: string[] = [];
-  for (const { file } of FRAGMENTS) {
+  const kitRepository = yield* isKit(root);
+  for (const { file, extendedBy, reader, kitConfig, kitRepositoryConfig, kitConfigReason } of FRAGMENTS) {
     const target = path.join(root, file);
     const fragment = expected.find((candidate) => candidate.file === file);
     const present = yield* fs.exists(target);
@@ -111,8 +211,13 @@ const fragmentProblems = Effect.fn("fragmentProblems")(function* (root: string,
     } else if (!(yield* sameJson(yield* fs.readFileString(target), fragment.content))) {
       problems.push(`${file} is stale against ${source} and the kit's presets; run ${GENERATE}`);
     }
-    if (!(yield* extendsOf(root, fragment.extendedBy)).includes(file)) {
-      problems.push(`${fragment.extendedBy} does not extend ./${file}, so ${fragment.reader} never reads it`);
+    const configured = yield* extendsOf(root, extendedBy);
+    if (!configured.includes(file)) {
+      problems.push(`${extendedBy} does not extend ./${file}, so ${reader} never reads it`);
+    }
+    const requiredKitConfig = kitRepository ? kitRepositoryConfig : kitConfig;
+    if (!configured.includes(path.normalize(requiredKitConfig))) {
+      problems.push(`${extendedBy} does not extend ${requiredKitConfig}, ${kitConfigReason}`);
     }
   }
   return problems;
@@ -135,18 +240,54 @@ const unmatchedPaths = Effect.fn("unmatchedPaths")(function* (root: string, qual
   return problems;
 });
 
+const recipeOf = Effect.fn("recipeOf")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  return {
+    // The kit never installs itself, so its own tree lints with its root config.
+    commitlintConfig: (yield* isKit(root)) ? OWN_COMMITLINT_CONFIG : KIT_COMMITLINT_CONFIG,
+    bunVersionFile: yield* fs.exists(path.join(root, ".bun-version")),
+  } satisfies WorkflowRecipe;
+});
+
+const workflowProblems = Effect.fn("workflowProblems")(function* (
+  root: string,
+  source: string,
+  expected: readonly GeneratedWorkflow[],
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const problems: string[] = [];
+  for (const { file, content } of expected) {
+    const target = path.join(root, file);
+    if (!(yield* fs.exists(target))) {
+      problems.push(`${file} is missing; run ${GENERATE}`);
+    } else if ((yield* fs.readFileString(target)) !== content) {
+      problems.push(`${file} is stale against ${source} and the kit recipe; run ${GENERATE}`);
+    }
+  }
+  return problems;
+});
+
 const check = Effect.fn("check")(function* (root: string) {
   const { source, quality } = yield* readQuality(root);
   const expected = fragmentsFor(quality);
-  const problems = [...(yield* fragmentProblems(root, source, expected)), ...(yield* unmatchedPaths(root, quality))];
+  const workflows = workflowsFor(quality, yield* recipeOf(root));
+  const problems = [
+    ...(yield* fragmentProblems(root, source, expected)),
+    ...(yield* workflowProblems(root, source, workflows)),
+    ...(yield* unmatchedPaths(root, quality)),
+  ];
   if (problems.length > 0) {
     yield* Console.error([`${NAME}: ${problems.length} problem(s) with what ${source} declares:`, ...problems.map((line) => `  ${line}`)].join("\n"));
     return false;
   }
+  const held = [...expected.map((fragment) => fragment.file), ...workflows.map((workflow) => workflow.file)];
+  const verb = held.length === 1 ? "holds" : "hold";
   yield* Console.log(
     expected.length === 0
-      ? `${NAME}: no sources.effect is declared, so nothing is generated`
-      : `${NAME}: ${expected.map((fragment) => fragment.file).join(" and ")} hold what ${source} declares`,
+      ? `${NAME}: no sources.effect is declared, so no fragment is generated; ${held.join(" and ")} ${verb} the kit recipe`
+      : `${NAME}: ${held.join(" and ")} ${verb} what ${source} declares`,
   );
   return true;
 });
@@ -167,6 +308,12 @@ const generate = Effect.fn("generate")(function* (root: string) {
       yield* Console.log(`${NAME}: removed ${file}`);
     }
   }
+  const workflows = workflowsFor(quality, yield* recipeOf(root));
+  yield* fs.makeDirectory(path.join(root, ".github", "workflows"), { recursive: true });
+  for (const { file, content } of workflows) {
+    yield* fs.writeFileString(path.join(root, file), content);
+    yield* Console.log(`${NAME}: wrote ${file}`);
+  }
   return yield* check(root);
 });
 

package/scripts/quarantine-clock.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env bun
+import { Console, Effect, Schema } from "effect";
+import { commitOf, git, isShallowBoundary, refArgs } from "./git.ts";
+import { runMain } from "./main.ts";
+import { TEST_FILE } from "./test-layout.ts";
+
+export const QUARANTINE = "tests/quarantine/";
+export const QUARANTINE_DAYS = 30;
+const DAY_SECONDS = 86400;
+
+export class QuarantineError extends Schema.TaggedError<QuarantineError>()("QuarantineError", {
+  message: Schema.String,
+}) {}
+
+const USAGE = "usage: quarantine-clock.ts <ref> | <base-ref> <head-ref>";
+
+export type Entry =
+  | { readonly kind: "entered"; readonly sha: string; readonly at: number; readonly day: string }
+  | { readonly kind: "truncated" };
+
+export type Overdue = {
+  readonly file: string;
+  readonly day: string;
+  readonly days: number;
+};
+
+export type ClockResult = {
+  readonly checked: number;
+  readonly overdue: readonly Overdue[];
+};
+
+const HEADER = /^commit ([0-9a-f]{40}|[0-9a-f]{64}) (\d+) (\S+)$/;
+const TWO_PATHS = /^[RC]/;
+
+type Status = readonly [status: string, from: string, to: string];
+
+type CommitBlock = {
+  readonly sha: string;
+  readonly at: number;
+  readonly day: string;
+  readonly statuses: readonly Status[];
+};
+
+function parseBlocks(output: string): readonly CommitBlock[] {
+  const blocks: { readonly sha: string; readonly at: number; readonly day: string; readonly statuses: Status[] }[] = [];
+  const fields = output.split("\0");
+  let index = 0;
+  while (index < fields.length) {
+    const field = (fields[index] ?? "").replace(/^\n/, "");
+    index += 1;
+    const header = HEADER.exec(field);
+    if (header !== null) {
+      blocks.push({ sha: header[1] ?? "", at: Number(header[2] ?? "0"), day: (header[3] ?? "").slice(0, "YYYY-MM-DD".length), statuses: [] });
+      continue;
+    }
+    if (field === "") continue;
+    const paths = TWO_PATHS.test(field) ? 2 : 1;
+    blocks.at(-1)?.statuses.push([field, fields[index] ?? "", fields[index + paths - 1] ?? ""]);
+    index += paths;
+  }
+  return blocks;
+}
+
+function entryIn({ sha, at, day, statuses }: CommitBlock, path: string): Entry | undefined {
+  const entered = statuses.some(
+    ([status, from, to]) =>
+      to === path && (status === "A" || status.startsWith("C") || (status.startsWith("R") && !from.startsWith(QUARANTINE))),
+  );
+  return entered ? { kind: "entered", sha, at, day } : undefined;
+}
+
+function followedPath({ statuses }: CommitBlock, path: string): string {
+  const rename = statuses.find(([status, , to]) => status.startsWith("R") && to === path);
+  return rename?.[1] ?? path;
+}
+
+export function findEntry(output: string, file: string): Entry {
+  let current = file;
+  for (const block of parseBlocks(output)) {
+    const entry = entryIn(block, current);
+    if (entry !== undefined) return entry;
+    current = followedPath(block, current);
+  }
+  return { kind: "truncated" };
+}
+
+export function overdueOf(
+  entries: readonly { readonly file: string; readonly at: number; readonly day: string }[],
+  headAt: number,
+): readonly Overdue[] {
+  const limit = QUARANTINE_DAYS * DAY_SECONDS;
+  return entries
+    .flatMap((entry) =>
+      headAt - entry.at > limit
+        ? [{ file: entry.file, day: entry.day, days: Math.floor((headAt - entry.at) / DAY_SECONDS) }]
+        : [],
+    )
+    .toSorted((a, b) => (a.file < b.file ? -1 : 1));
+}
+
+export function report({ checked, overdue }: ClockResult): string {
+  if (overdue.length === 0) {
+    return `quarantine-clock: no test in ${QUARANTINE} is past ${QUARANTINE_DAYS} days (${checked} checked)`;
+  }
+  const verb = overdue.length === 1 ? "is" : "are";
+  return [
+    `quarantine-clock: ${overdue.length} test(s) in ${QUARANTINE} ${verb} past ${QUARANTINE_DAYS} days; fix each and move it back, or delete it:`,
+    ...overdue.map((file) => `  ${file.file} entered quarantine on ${file.day} (${file.days} days ago)`),
+  ].join("\n");
+}
+
+const filesAt = Effect.fn("filesAt")(function* (root: string, head: string) {
+  const listed = yield* git(["ls-tree", "-r", "-z", "--name-only", head, "--", QUARANTINE], root);
+  return listed.split("\0").filter((file) => TEST_FILE.test(file));
+});
+
+const entryAt = Effect.fn("entryAt")(function* (root: string, head: string, file: string) {
+  const output = yield* git(["log", "--follow", "--root", "--name-status", "-z", "--format=commit %H %at %aI", head, "--", file], root);
+  const entry = findEntry(output, file);
+  if (entry.kind === "truncated" || (yield* isShallowBoundary(entry.sha, root))) {
+    return yield* new QuarantineError({
+      message: `cannot see ${file} entering ${QUARANTINE}; fetch the whole history, since a shallow clone ends before it`,
+    });
+  }
+  return { file, at: entry.at, day: entry.day };
+});
+
+const headAt = Effect.fn("headAt")(function* (root: string, head: string) {
+  const shown = yield* git(["show", "-s", "--format=%at %ct", head], root);
+  const dates = shown.trim().split(" ").map(Number);
+  if (dates.length !== 2 || !dates.every(Number.isInteger)) {
+    return yield* new QuarantineError({ message: `cannot read when ${head} was written` });
+  }
+  return Math.max(...dates);
+});
+
+export const runHead = Effect.fn("runHead")(function* (root: string, head: string) {
+  const files = yield* filesAt(root, head);
+  const entries = yield* Effect.forEach(files, (file) => entryAt(root, head, file));
+  return { checked: files.length, overdue: overdueOf(entries, yield* headAt(root, head)) } satisfies ClockResult;
+});
+
+const clock = Effect.gen(function* () {
+  const { first, second } = yield* refArgs(process.argv.slice(2), USAGE);
+  if (second !== undefined) yield* commitOf(first);
+  const head = yield* commitOf(second ?? first);
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  const result = yield* runHead(root, head);
+  yield* Console.log(report(result));
+  return result.overdue.length === 0;
+});
+
+if (import.meta.main) runMain("quarantine-clock", clock);

package/scripts/range-gate.ts

@@ -0,0 +1,9 @@
+import { Effect } from "effect";
+import { git, refArgs } from "./git.ts";
+import { readQuality } from "./quality-file.ts";
+
+export const rangeGateInputs = Effect.fn("rangeGateInputs")(function* (usage: string) {
+  const refs = yield* refArgs(process.argv.slice(2), usage);
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  return { refs, root, ...(yield* readQuality(root)) };
+});