@avi2dg/checks 0.16.0 → 0.18.0

package/scripts/doc-rules.ts

@@ -89,29 +89,42 @@ function statusProblem(outline: Outline): Violation | undefined {
   return { line: opening?.line ?? status.heading.line, message: `\`## Status\` opens with ${found} where one of ${ADR_STATUSES.join(", ")} goes` };
 }
 
-function adrProblems(path: string, outline: Outline, records: readonly string[]): readonly Violation[] {
-  const violations: Violation[] = [];
-  const filed = recordNumber(path);
-  if (filed === undefined) {
-    violations.push({ line: 1, message: `is not named as a record, a four-digit number and a kebab-case name directly in ${ADR_DIRECTORY}` });
-  }
+function recordTitleProblem(outline: Outline, filed: number | undefined): Violation | undefined {
   const title = titleOf(outline);
-  const titled = title === undefined ? undefined : RECORD_TITLE.exec(title.title)?.[1];
-  if (title !== undefined && titled === undefined) {
-    violations.push({ line: title.line, message: `${marked(1, title.title)} does not open with the record's number, as in \`# 7. The decision\`` });
-  }
-  if (title !== undefined && titled !== undefined && filed !== undefined && Number(titled) !== filed) {
-    violations.push({ line: title.line, message: `${marked(1, title.title)} carries number ${titled}, and the file name ${filed}` });
+  if (title === undefined) return undefined;
+  const titled = RECORD_TITLE.exec(title.title)?.[1];
+  if (titled === undefined) {
+    return { line: title.line, message: `${marked(1, title.title)} does not open with the record's number, as in \`# 7. The decision\`` };
   }
-  const dated = firstText(outline.lead);
-  if (!isDate(DATE_LINE.exec(dated?.text.trim() ?? "")?.[1])) {
-    violations.push({ line: dated?.line ?? 1, message: "does not follow its title with a `Date: YYYY-MM-DD` line" });
-  }
-  const status = statusProblem(outline);
-  if (status !== undefined) violations.push(status);
-  const sharing = records.filter((other) => other !== path && filed !== undefined && recordNumber(other) === filed);
-  if (sharing.length > 0) violations.push({ line: 1, message: `shares number ${filed} with ${sharing.join(", ")}` });
-  return violations;
+  if (filed === undefined || Number(titled) === filed) return undefined;
+  return { line: title.line, message: `${marked(1, title.title)} carries number ${titled}, and the file name ${filed}` };
+}
+
+function recordDateProblem({ lead }: Outline): Violation | undefined {
+  const dated = firstText(lead);
+  if (isDate(DATE_LINE.exec(dated?.text.trim() ?? "")?.[1])) return undefined;
+  return { line: dated?.line ?? 1, message: "does not follow its title with a `Date: YYYY-MM-DD` line" };
+}
+
+function sharedNumberProblem(path: string, filed: number | undefined, records: readonly string[]): Violation | undefined {
+  if (filed === undefined) return undefined;
+  const sharing = records.filter((other) => other !== path && recordNumber(other) === filed);
+  return sharing.length === 0 ? undefined : { line: 1, message: `shares number ${filed} with ${sharing.join(", ")}` };
+}
+
+function adrProblems(path: string, outline: Outline, records: readonly string[]): readonly Violation[] {
+  const filed = recordNumber(path);
+  const misnamed: Violation | undefined =
+    filed === undefined
+      ? { line: 1, message: `is not named as a record, a four-digit number and a kebab-case name directly in ${ADR_DIRECTORY}` }
+      : undefined;
+  return [
+    misnamed,
+    recordTitleProblem(outline, filed),
+    recordDateProblem(outline),
+    statusProblem(outline),
+    sharedNumberProblem(path, filed, records),
+  ].filter((violation) => violation !== undefined);
 }
 
 export const RELEASED = /^Released (\S+)\.$/;

package/scripts/docs.ts

@@ -3,8 +3,8 @@ import { Console, Effect } from "effect";
 import { rootsOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
 import { ADR_DIRECTORY, judge, placementOf, placementProblem, type Placement } from "./doc-rules.ts";
 import { readTexts, snapshotAt, stillMissing } from "./doc-snapshot.ts";
-import { changedLines, changedPaths, git, pathsAt, rangeEnds } from "./git.ts";
-import { runMain, Usage } from "./main.ts";
+import { changedLines, changedPaths, git, pathsAt, rangeEnds, refArgs } from "./git.ts";
+import { runMain } from "./main.ts";
 import { isLivingDoc, proseFindings, readerOf } from "./prose-matchers.ts";
 import { readQuality } from "./quality-file.ts";
 
@@ -152,8 +152,7 @@ export function report({ held, edited, living, findings, advisory, brokenBefore
 }
 
 const docs = Effect.gen(function* () {
-  const [first, second, ...extra] = process.argv.slice(2);
-  if (first === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
+  const { first, second } = yield* refArgs(process.argv.slice(2), USAGE);
 
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
   const { base, head } = yield* rangeEnds(first, second, root);

package/scripts/feature-owners.ts

@@ -2,8 +2,9 @@
 import { parse } from "@swc/core";
 import { Console, Effect, Path, Schema } from "effect";
 import { changedPaths, git, pathsAt, rangeEnds, type Change } from "./git.ts";
-import { runMain, Usage } from "./main.ts";
-import { PROOF_DIRECTORY, readQuality, type Feature } from "./quality-file.ts";
+import { runMain } from "./main.ts";
+import { PROOF_DIRECTORY, type Feature } from "./quality-file.ts";
+import { rangeGateInputs } from "./range-gate.ts";
 
 type Unproven = {
   readonly feature: string;
@@ -120,17 +121,13 @@ function signalReport(touched: readonly Touch[]): string {
 }
 
 const owners = Effect.gen(function* () {
-  const [first, second, ...extra] = process.argv.slice(2);
-  if (first === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
-
-  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const { source, quality } = yield* readQuality(root);
+  const { refs, root, source, quality } = yield* rangeGateInputs(USAGE);
   const features = quality.features ?? [];
   if (features.length === 0) {
     yield* Console.log(`${NAME}: ${source} declares no feature`);
     return true;
   }
-  const { base, head } = yield* rangeEnds(first, second, root);
+  const { base, head } = yield* rangeEnds(refs.first, refs.second, root);
   const found = yield* unproven(root, head, features);
   yield* Console.log(proofReport(features, found));
   if (quality.changeSignal === "advisory") {

package/scripts/git.ts

@@ -87,37 +87,37 @@ function newPathOf(line: string): string | undefined {
 
 const HUNK = /^@@ -\d+(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
 
+type HunkPosition = {
+  readonly line: number;
+  readonly oldLeft: number;
+  readonly newLeft: number;
+};
+
+function hunkStart(row: string): HunkPosition | undefined {
+  const hunk = HUNK.exec(row);
+  return hunk === null ? undefined : { oldLeft: Number(hunk[1] ?? 1), line: Number(hunk[2]), newLeft: Number(hunk[3] ?? 1) };
+}
+
+function pastHunkRow(row: string, { line, oldLeft, newLeft }: HunkPosition): HunkPosition {
+  if (row.startsWith("+")) return { line: line + 1, oldLeft, newLeft: newLeft - 1 };
+  if (row.startsWith("-")) return { line, oldLeft: oldLeft - 1, newLeft };
+  if (row.startsWith(" ")) return { line: line + 1, oldLeft: oldLeft - 1, newLeft: newLeft - 1 };
+  return { line, oldLeft, newLeft };
+}
+
 // A hunk's header counts its lines, so an added line reading `++ x` is not taken for the next file's `+++` header.
 export function parseAddedLines(diff: string): Map<string, Set<number>> {
   const added = new Map<string, Set<number>>();
   let path: string | undefined;
-  let line = 0;
-  let oldLeft = 0;
-  let newLeft = 0;
+  let at: HunkPosition = { line: 0, oldLeft: 0, newLeft: 0 };
   for (const row of diff.split("\n")) {
-    if (oldLeft > 0 || newLeft > 0) {
-      if (row.startsWith("+")) {
-        if (path !== undefined) added.set(path, (added.get(path) ?? new Set<number>()).add(line));
-        line += 1;
-        newLeft -= 1;
-      } else if (row.startsWith("-")) {
-        oldLeft -= 1;
-      } else if (row.startsWith(" ")) {
-        line += 1;
-        oldLeft -= 1;
-        newLeft -= 1;
-      }
-      continue;
-    }
-    if (row.startsWith("+++ ")) {
+    if (at.oldLeft > 0 || at.newLeft > 0) {
+      if (row.startsWith("+") && path !== undefined) added.set(path, (added.get(path) ?? new Set<number>()).add(at.line));
+      at = pastHunkRow(row, at);
+    } else if (row.startsWith("+++ ")) {
       path = newPathOf(row);
-      continue;
-    }
-    const hunk = HUNK.exec(row);
-    if (hunk !== null) {
-      oldLeft = Number(hunk[1] ?? 1);
-      line = Number(hunk[2]);
-      newLeft = Number(hunk[3] ?? 1);
+    } else {
+      at = hunkStart(row) ?? at;
     }
   }
   return added;
@@ -161,9 +161,14 @@ export const rangeEnds = Effect.fn("rangeEnds")(function* (first: string, second
   return { base: (yield* git(["merge-base", first, second], cwd)).trim(), head: second };
 });
 
-export const rangeFromArgs = Effect.fn("rangeFromArgs")(function* (args: readonly string[], usage: string, cwd?: string) {
+export const refArgs = Effect.fn("refArgs")(function* (args: readonly string[], usage: string) {
   const [first, second, ...extra] = args;
   if (first === undefined || extra.length > 0) return yield* new Usage({ message: usage });
+  return { first, second };
+});
+
+export const rangeFromArgs = Effect.fn("rangeFromArgs")(function* (args: readonly string[], usage: string, cwd?: string) {
+  const { first, second } = yield* refArgs(args, usage);
   return yield* rangeEnds(first, second, cwd);
 });
 

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.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/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)) };
+});