@avi2dg/checks 0.8.0 → 0.9.0

package/README.md

@@ -63,6 +63,8 @@ below. Three of them:
 `lint-coverage.sh` fails when oxlint silently skips a tracked `.ts` or
 `.tsx` file, for example through a stray `.gitignore` entry. It compares
 `git ls-files` against oxlint's own file walk and names the missing files.
+It exits 2 when oxlint cannot walk the tree, as when it is not on `PATH`
+or its config does not parse.
 
 `test-layout.ts` decides the test layout described below.
 
@@ -87,7 +89,9 @@ The registry version is pinned by the consumer's lockfile; bump
 ## Lint entry point
 
 `checks-lint` runs each of the kit's lint gates in turn and names every
-one that fails, rather than stopping at the first:
+one that fails, rather than stopping at the first. A repository whose
+tracked files give a gate nothing to check can leave it out through
+`ciWiring.lintGates`; see "Gate selection" under "CI wiring".
 
 | Gate | Reads |
 | --- | --- |
@@ -122,13 +126,29 @@ tip: commits the base branch gained after the head branched off would
 otherwise count against the head. When the head is the merge base, as
 on a push to the default branch or a local run on it, the range would be
 empty, so each range gate is handed that tip commit alone and checks it
-against its parent:
+against its parent, or against the empty tree when it is a repository's
+first commit:
 
 ```
 checks-lint: tip 10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
 ```
 
-It prints the range, each gate's own report, then its verdict:
+A clone with no remote-tracking refs at all, such as a freshly
+initialised repository with no remote or one whose remote was never
+fetched, has no default branch to start from, so each range gate is
+handed `HEAD` alone the same way:
+
+```
+checks-lint: tip 10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD alone, as the clone has no remote-tracking refs
+```
+
+Once any ref sits under `refs/remotes/`, a missing
+`origin/<default branch>` exits 2 instead, since that is the shape of a
+shallow CI checkout, where `HEAD` alone would leave the commits before
+it unchecked.
+
+It prints the range, the declared selection if there is one, each
+gate's own report, then its verdict:
 
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
@@ -136,10 +156,11 @@ checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed7262
 checks-lint: 3 of 6 gate(s) failed: checks-commit-identity, checks-comment-gate, checks-suppressions-ratchet
 ```
 
-It exits 1 when any gate found a violation, and 2 when the range does
-not resolve or no failing gate could decide. Every gate runs, so a
-repository on `checks-lint` declares `ciWiring.gates` (see "CI wiring")
-and holds the test layout.
+It exits 1 when any gate found a violation, and 2 when the range or the
+selection does not resolve, or no failing gate could decide. ci-wiring
+always runs, so a repository on `checks-lint` declares `ciWiring.gates`
+(see "CI wiring"), and it holds the test layout unless its selection
+leaves out `checks-test-layout`.
 
 CI runs it through `lint`. The checkout fetches the whole history, which
 the merge base needs:
@@ -207,7 +228,9 @@ which need the `node`, `promise` and `unicorn` plugins in the override's
 `plugins`. `unicorn/no-process-exit` passes over any file that opens with
 a shebang, so a bin also needs `no-restricted-properties` on
 `process.exit`. Sites standing when the override lands go in oxlint's own
-baseline, `oxlint --suppress-all`, so their count can only fall.
+baseline, `oxlint --suppress-all`, so their count can only fall. A later
+override lifts `effect-channel/no-throw` from `scripts/comment-matchers.ts`,
+the one file there a host loads without `node_modules`.
 
 The language service holds the same paths to Effect-native IO through
 `overrides` in the plugin block of `tsconfig.json`. effect-tsgo keeps the
@@ -408,15 +431,23 @@ bun run checks-comment-gate <ref>
 ```
 
 With two arguments it diffs the base against the head. With one it diffs
-that commit against its parent, and exits 2 when that parent is not in
-the clone rather than widening to the whole tree, so a shallow checkout
-running the one-argument form needs `fetch-depth: 2`. Only added lines
+that commit against its parent, or against the empty tree for a
+repository's first commit, which has none. It exits 2 when the parent
+exists but is not in the clone rather than widening to the whole tree,
+so a shallow checkout running the one-argument form needs
+`fetch-depth: 2`. Only added lines
 are checked, so a violation in a file the diff never touches stays
 silent, and a refusal counts when any line of the comment carrying it was
 added. The check refuses a machine-read directive, a record or ticket
 pointer, a doc block, and a file opening with a rationale block over
-three lines, licence headers excepted; `scripts/comments.ts` holds the
-scanner the gate and the backtest share.
+three lines, licence headers excepted.
+
+`scripts/comment-matchers.ts` holds the scanner, the comment syntaxes
+and a synchronous `refused()`, and imports nothing, so a host such as a
+hook bundle can copy it alone into a directory with no `node_modules`
+and import it as `@avi2dg/checks/scripts/comment-matchers.ts`. The repo's
+cruise fails when it gains an import. `scripts/comments.ts` wraps the
+same matchers in Effect for the gate and the backtest.
 
 `checks-lint` runs it over each pull request's range; see "Lint entry point".
 
@@ -434,8 +465,9 @@ bun run checks-suppressions-ratchet <base-ref> <head-ref>
 bun run checks-suppressions-ratchet <ref>
 ```
 
-With one argument it compares that commit with its parent, and exits 2
-when the parent is not in the clone. With two it reads the base where
+With one argument it compares that commit with its parent, or with the
+empty tree for a repository's first commit, and exits 2 when the parent
+exists but is not in the clone. With two it reads the base where
 the head branched off, at their merge-base, so a count the base branch
 lowered since does not read as a rise at the head. A count that fell and
 an entry that went both pass. A commit without the file counts as empty,
@@ -527,6 +559,55 @@ It exits 2 when `package.json` declares no gates, a gate is not one
 plain command, or a workflow does not parse. Whether a workflow is
 well formed is actionlint's question, not this one's.
 
+### Gate selection
+
+A repository with no TypeScript source gives `checks-lint-coverage` and
+`checks-test-layout` nothing to check, and test-layout still refuses its
+missing `bun test` script and `bunfig.toml`. It declares the gates
+`checks-lint` runs as `lintGates`, beside `gates`:
+
+```json
+"ciWiring": {
+  "gates": ["bun run lint"],
+  "lintGates": [
+    "checks-commit-identity",
+    "checks-comment-gate",
+    "checks-suppressions-ratchet",
+    "checks-ci-wiring"
+  ]
+}
+```
+
+`checks-lint` runs exactly those, in the "Lint entry point" table's
+order, and all six when `lintGates` is absent. A step running
+`checks-lint` then counts only for a declared gate that `lintGates`
+keeps.
+
+A selection may leave out only a gate that does not apply:
+
+| Gate | Applies when the repository |
+| --- | --- |
+| `checks-lint-coverage` | tracks a `.ts` or `.tsx` file |
+| `checks-test-layout` | tracks a `.ts` or `.tsx` file |
+| `checks-commit-identity` | always |
+| `checks-comment-gate` | always |
+| `checks-suppressions-ratchet` | always |
+| `checks-ci-wiring` | always |
+
+Both bins exit 2 on a `lintGates` that names an unknown gate or leaves
+out one that always applies. ci-wiring exits 1 when the
+selection leaves out a gate the repository's tracked files make
+applicable, and names the gate and the files:
+
+```
+ci-wiring: ciWiring.lintGates leaves out 2 gate(s) this repository's contents make applicable:
+  checks-lint-coverage: the repository tracks TypeScript source (src/widget.ts)
+  checks-test-layout: the repository tracks TypeScript source (src/widget.ts)
+```
+
+It reads the files tracked at the checkout, so the pull request that
+adds the first TypeScript file is the one refused.
+
 ### Limits
 
 The check reads workflow files and never runs them, so it deliberately
@@ -655,6 +736,11 @@ The shared Stryker preset's `json` reporter writes
   the entry point, and `lint-coverage.sh` stays a shell script. The
   gates run one at a time with their output passed straight through, so
   each report reads whole and in the table's order.
+- A gate selection is checked against the repository's contents rather
+  than trusted, so it cannot skip a gate that applies. ci-wiring does
+  that check, which is why a selection without it, or without another
+  gate that applies everywhere, is refused as `checks-lint` reads it:
+  nothing would check the selection otherwise.
 - `checks-ci-wiring` runs inside `lint`, not in a workflow of its own:
   deleting the step that runs a check is the violation it catches, so the
   local `lint` is where it has to fail.
@@ -695,7 +781,7 @@ a tag off `main` and reruns the build, `dist/` check, lint, typecheck
 and tests before it publishes:
 
 ```sh
-git tag v0.8.0 && git push origin v0.8.0
+git tag v0.9.0 && git push origin v0.9.0
 ```
 
 The `release` workflow publishes the tagged version through npm

package/oxlintrc.json

@@ -14,8 +14,8 @@
     "typescript/no-unnecessary-type-parameters": "error",
     "typescript/use-unknown-in-catch-callback-variable": "error",
     "eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_", "ignoreRestSiblings": true }],
-    "typescript/no-unsafe-type-assertion": "off",
-    "typescript/no-non-null-assertion": "off",
+    "typescript/no-unsafe-type-assertion": "error",
+    "typescript/no-non-null-assertion": "error",
     "typescript/consistent-return": "off"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -24,6 +24,7 @@
     "scripts/commit-identity.ts",
     "scripts/mutation-compare.ts",
     "scripts/ci-wiring.ts",
+    "scripts/comment-matchers.ts",
     "scripts/comments.ts",
     "scripts/comment-gate.ts",
     "scripts/suppressions-ratchet.ts",
@@ -43,6 +44,7 @@
     "./scripts/commit-identity.ts": "./scripts/commit-identity.ts",
     "./scripts/mutation-compare.ts": "./scripts/mutation-compare.ts",
     "./scripts/ci-wiring.ts": "./scripts/ci-wiring.ts",
+    "./scripts/comment-matchers.ts": "./scripts/comment-matchers.ts",
     "./scripts/comments.ts": "./scripts/comments.ts",
     "./scripts/comment-gate.ts": "./scripts/comment-gate.ts",
     "./scripts/suppressions-ratchet.ts": "./scripts/suppressions-ratchet.ts",
@@ -65,7 +67,7 @@
   },
   "scripts": {
     "build": "bun build effect-channel/index.ts --outdir dist --target node --format esm",
-    "lint": "oxlint --type-aware && bun scripts/lint.ts && depcruise --config .dependency-cruiser.cjs effect-channel scripts tests commitlint.config.js dependency-cruiser.config.js stryker.preset.js .dependency-cruiser.cjs",
+    "lint": "oxlint --type-aware && bun scripts/lint.ts && depcruise --config .dependency-cruiser.cjs .",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
     "test": "bun test --randomize"
   },

package/scripts/backtest.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect, Option } from "effect";
-import { comments, refused, SYNTAXES } from "./comments.ts";
+import { comments, refused, syntaxOf } from "./comments.ts";
 import { git } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
 
@@ -18,8 +18,7 @@ const EXCLUDED = ["generated/", "vendor/", "repos/", "node_modules/", "dist/"];
 
 function readable(path: string): boolean {
   if (EXCLUDED.some((prefix) => path.startsWith(prefix))) return false;
-  const extension = path.slice(path.lastIndexOf(".") + 1);
-  return extension in SYNTAXES;
+  return syntaxOf(path) !== undefined;
 }
 
 const at = (sha: string, path: string) => git(["show", `${sha}:${path}`]).pipe(Effect.option);

package/scripts/ci-wiring.ts

@@ -2,7 +2,15 @@
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { git } from "./git.ts";
 import { runMain } from "./main.ts";
-import { DEFAULT_BRANCH, ENTRY_POINT, KIT_GATES } from "./gates.ts";
+import {
+  DEFAULT_BRANCH,
+  ENTRY_POINT,
+  EVERY_REPOSITORY,
+  KIT_GATES,
+  LintWiring,
+  selectedGates,
+  type KitGate,
+} from "./gates.ts";
 
 export type Command = readonly string[];
 
@@ -14,6 +22,7 @@ export type Gate = {
 export type Declaration = {
   readonly gates: readonly Gate[];
   readonly defaultBranch: string;
+  readonly lintGates: readonly KitGate[];
 };
 
 export type Workflow = {
@@ -26,6 +35,12 @@ export type BlockedInvocation = {
   readonly blocker: string;
 };
 
+export type Omission = {
+  readonly gate: string;
+  readonly content: string;
+  readonly files: readonly [string, ...string[]];
+};
+
 export type Gap = {
   readonly gate: string;
   readonly entryPoint?: string;
@@ -230,15 +245,15 @@ function runSteps(workflows: readonly Workflow[], branch: string): readonly RunS
   return steps;
 }
 
-function entryPointCommand(gate: Command): Command | undefined {
-  const index = gate.findIndex((word) => KIT_GATES.some((kitGate) => kitGate.bin === word));
+function entryPointCommand(gate: Command, lintGates: readonly KitGate[]): Command | undefined {
+  const index = gate.findIndex((word) => lintGates.some((kitGate) => kitGate.bin === word));
   return index === -1 ? undefined : [...gate.slice(0, index), ENTRY_POINT.bin];
 }
 
 export function findGaps(declaration: Declaration, workflows: readonly Workflow[]): readonly Gap[] {
   const steps = runSteps(workflows, declaration.defaultBranch);
   return declaration.gates.flatMap((gate) => {
-    const entryPoint = entryPointCommand(gate.words);
+    const entryPoint = entryPointCommand(gate.words, declaration.lintGates);
     const commands = [
       { command: gate.command, words: gate.words },
       ...(entryPoint === undefined ? [] : [{ command: entryPoint.join(" "), words: entryPoint }]),
@@ -273,6 +288,8 @@ export function formatReport(declaration: Declaration, gaps: readonly Gap[]): st
   return lines.join("\n");
 }
 
+const decodeWiring = Schema.decodeUnknownEffect(LintWiring);
+
 export const parseDeclaration = Effect.fnUntraced(function* (
   manifest: unknown,
   source: string,
@@ -293,13 +310,49 @@ export const parseDeclaration = Effect.fnUntraced(function* (
     }
     gates.push({ command, words });
   }
-  const defaultBranch = configured["defaultBranch"] ?? DEFAULT_BRANCH;
-  if (typeof defaultBranch !== "string" || defaultBranch === "") {
-    return yield* new WiringError({ message: `${source} ciWiring.defaultBranch is not a branch name` });
+  const { ciWiring } = yield* decodeWiring(manifest).pipe(
+    Effect.mapError((cause) => new WiringError({ message: `${source}: ${cause.message}` })),
+  );
+  return {
+    gates,
+    defaultBranch: ciWiring?.defaultBranch ?? DEFAULT_BRANCH,
+    lintGates: selectedGates(ciWiring?.lintGates),
+  };
+});
+
+function omittedFrom(lintGates: readonly KitGate[]): readonly KitGate[] {
+  return KIT_GATES.filter((gate) => !lintGates.includes(gate));
+}
+
+export const findOmissions = Effect.fn("findOmissions")(function* (root: string, lintGates: readonly KitGate[]) {
+  const omissions: Omission[] = [];
+  for (const gate of omittedFrom(lintGates)) {
+    // LintGates refuses a selection that leaves out a gate every repository runs.
+    if (gate.appliesTo === EVERY_REPOSITORY) continue;
+    const { pathspecs, content } = gate.appliesTo;
+    const [first, ...rest] = (yield* git(["ls-files", "-z", "--", ...pathspecs], root)).split("\0").filter(Boolean);
+    if (first !== undefined) omissions.push({ gate: gate.bin, content, files: [first, ...rest] });
   }
-  return { gates, defaultBranch };
+  return omissions;
 });
 
+function sample([first, ...rest]: Omission["files"]): string {
+  return rest.length === 0 ? first : `${first} and ${rest.length} more`;
+}
+
+export function formatOmissions(lintGates: readonly KitGate[], omissions: readonly Omission[]): string | undefined {
+  const omitted = omittedFrom(lintGates);
+  if (omitted.length === 0) return undefined;
+  if (omissions.length === 0) {
+    const bins = omitted.map((gate) => gate.bin).join(", ");
+    return `ci-wiring: ciWiring.lintGates leaves out ${bins}, none of which this repository's contents make applicable`;
+  }
+  return [
+    `ci-wiring: ciWiring.lintGates leaves out ${omissions.length} gate(s) this repository's contents make applicable:`,
+    ...omissions.map(({ gate, content, files }) => `  ${gate}: the repository tracks ${content} (${sample(files)})`),
+  ].join("\n");
+}
+
 export const parseWorkflow = (path: string, text: string): Effect.Effect<Workflow, WiringError> =>
   Effect.try({
     try: () => ({ path, document: Bun.YAML.parse(text) }),
@@ -337,12 +390,14 @@ const wiring = Effect.gen(function* () {
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
   const declaration = yield* readDeclaration(root);
   const gaps = findGaps(declaration, yield* readWorkflows(root));
-  if (gaps.length > 0) {
-    yield* Console.error(formatReport(declaration, gaps));
-    return false;
+  const omissions = yield* findOmissions(root, declaration.lintGates);
+  const gapReport = formatReport(declaration, gaps);
+  yield* gaps.length > 0 ? Console.error(gapReport) : Console.log(gapReport);
+  const omissionReport = formatOmissions(declaration.lintGates, omissions);
+  if (omissionReport !== undefined) {
+    yield* omissions.length > 0 ? Console.error(omissionReport) : Console.log(omissionReport);
   }
-  yield* Console.log(formatReport(declaration, gaps));
-  return true;
+  return gaps.length === 0 && omissions.length === 0;
 });
 
 if (import.meta.main) runMain("ci-wiring", wiring);

package/scripts/comment-gate.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, Option } from "effect";
-import { refused, SYNTAXES } from "./comments.ts";
-import { git } from "./git.ts";
+import { refused, syntaxOf } from "./comments.ts";
+import { git, parentOrEmptyTree } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
 
 export type GateResult = {
@@ -13,7 +13,7 @@ export type GateResult = {
 const USAGE = "usage: comment-gate.ts <ref> | <base-ref> <head-ref>";
 
 function readable(path: string): boolean {
-  return path.slice(path.lastIndexOf(".") + 1) in SYNTAXES;
+  return syntaxOf(path) !== undefined;
 }
 
 function newPathOf(line: string): string | undefined {
@@ -83,15 +83,12 @@ export function report({ files, addedLines, violations }: GateResult): string {
   return [`comment-gate: ${violations.length} violation(s):`, ...violations.map((one) => `  ${one}`)].join("\n");
 }
 
-const parentOf = (root: string, rev: string) =>
-  git(["rev-parse", "--verify", `${rev}^`], root).pipe(Effect.map((parent) => parent.trim()));
-
 const gate = 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"], process.cwd())).trim();
-  const base = second === undefined ? yield* parentOf(root, first) : first;
+  const base = second === undefined ? yield* parentOrEmptyTree(first, root) : first;
   const result = yield* runRange(root, base, second ?? first);
 
   yield* Console.log(report(result));

package/scripts/comment-matchers.ts

@@ -0,0 +1,309 @@
+export type Comment = { line: number; text: string };
+
+type Marker = { readonly token: string; readonly afterAWordBreak: boolean };
+type Quote = { readonly token: string; readonly backslashEscapes: boolean; readonly opensMidWord: boolean };
+
+export type Syntax = {
+  readonly line: readonly Marker[];
+  readonly block: readonly (readonly [open: string, close: string])[];
+  readonly quotes: readonly Quote[];
+  readonly regexLiterals: boolean;
+};
+
+const anywhere = (token: string): Marker => ({ token, afterAWordBreak: false });
+const startingAWord = (token: string): Marker => ({ token, afterAWordBreak: true });
+const escaping = (token: string): Quote => ({ token, backslashEscapes: true, opensMidWord: true });
+const literal = (token: string): Quote => ({ token, backslashEscapes: false, opensMidWord: true });
+const outsideAWord = (quote: Quote): Quote => ({ ...quote, opensMidWord: false });
+
+const SLASHES: readonly (readonly [string, string])[] = [["/*", "*/"]];
+const SLASH_SLASH = [startingAWord("//")];
+const DASHES = [anywhere("--")];
+const STRINGS = [escaping('"'), escaping("'")];
+
+const JS: Syntax = {
+  line: SLASH_SLASH,
+  block: SLASHES,
+  quotes: [escaping('"'), outsideAWord(escaping("'")), escaping("`")],
+  regexLiterals: true,
+};
+const CURLY: Syntax = { ...JS, quotes: [...STRINGS, escaping("`")], regexLiterals: false };
+const PHP: Syntax = { line: [...SLASH_SLASH, anywhere("#")], block: SLASHES, quotes: STRINGS, regexLiterals: false };
+const HASH: Syntax = {
+  line: [startingAWord("#")],
+  block: [],
+  quotes: [escaping('"'), literal("'")],
+  regexLiterals: false,
+};
+const YAML: Syntax = { ...HASH, quotes: [escaping('"'), outsideAWord(literal("'"))] };
+const SQL: Syntax = { line: DASHES, block: SLASHES, quotes: STRINGS, regexLiterals: false };
+const LUA: Syntax = { line: DASHES, block: [["--[[", "]]"]], quotes: STRINGS, regexLiterals: false };
+const HASKELL: Syntax = { line: DASHES, block: [["{-", "-}"]], quotes: [escaping('"')], regexLiterals: false };
+const ML: Syntax = { line: [], block: [["(*", "*)"]], quotes: [escaping('"')], regexLiterals: false };
+
+export const SYNTAXES: Readonly<Record<string, Syntax>> = {
+  ts: JS,
+  tsx: JS,
+  mts: JS,
+  cts: JS,
+  js: JS,
+  jsx: JS,
+  mjs: JS,
+  cjs: JS,
+  go: CURLY,
+  rs: CURLY,
+  java: CURLY,
+  kt: CURLY,
+  swift: CURLY,
+  scala: CURLY,
+  c: CURLY,
+  h: CURLY,
+  cc: CURLY,
+  cpp: CURLY,
+  hpp: CURLY,
+  cs: CURLY,
+  php: PHP,
+  py: HASH,
+  rb: HASH,
+  ex: HASH,
+  exs: HASH,
+  sh: HASH,
+  bash: HASH,
+  zsh: HASH,
+  nix: HASH,
+  sql: SQL,
+  lua: LUA,
+  hs: HASKELL,
+  yaml: YAML,
+  yml: YAML,
+  toml: HASH,
+  ml: ML,
+};
+
+const extensionOf = (path: string): string => path.slice(path.lastIndexOf(".") + 1);
+
+export function syntaxOf(path: string): Syntax | undefined {
+  const extension = extensionOf(path);
+  return Object.hasOwn(SYNTAXES, extension) ? SYNTAXES[extension] : undefined;
+}
+
+export function unreadable(path: string): string {
+  return `${path} is code the comment checks cannot read: add a comment syntax for .${extensionOf(path)} to scripts/comment-matchers.ts`;
+}
+
+const WORD = /[\w$]/;
+
+const KEYWORDS = new Set([
+  "return",
+  "typeof",
+  "instanceof",
+  "in",
+  "of",
+  "new",
+  "delete",
+  "void",
+  "throw",
+  "case",
+  "do",
+  "else",
+  "yield",
+  "await",
+]);
+
+const AFTER_A_VALUE = /[)\]}"'`]/;
+
+function opensRegex(previous: string): boolean {
+  if (previous === "") return true;
+  if (WORD.test(previous.charAt(0))) return KEYWORDS.has(previous);
+  return !AFTER_A_VALUE.test(previous);
+}
+
+const WORD_BREAK = /[\s;|&(]/;
+
+function endOfQuoted(source: string, start: number, quote: Quote): number {
+  let i = start + quote.token.length;
+  while (i < source.length) {
+    if (quote.backslashEscapes && source[i] === "\\") i += 2;
+    else if (source.startsWith(quote.token, i)) return i + quote.token.length;
+    else i += 1;
+  }
+  return start + quote.token.length;
+}
+
+function endOfRegex(source: string, start: number): number {
+  let i = start + 1;
+  let inClass = false;
+  while (i < source.length) {
+    const char = source.charAt(i);
+    if (char === "\\") i += 2;
+    else if (char === "\n") return i;
+    else {
+      if (char === "[") inClass = true;
+      else if (char === "]") inClass = false;
+      else if (char === "/" && !inClass) return i + 1;
+      i += 1;
+    }
+  }
+  return source.length;
+}
+
+export function commentsIn(source: string, syntax: Syntax): Comment[] {
+  const found: Comment[] = [];
+  let i = 0;
+  let line = 1;
+  let previous = "";
+
+  const advance = (to: number): void => {
+    for (let k = i; k < to; k++) if (source[k] === "\n") line += 1;
+    i = to;
+  };
+
+  while (i < source.length) {
+    const char = source.charAt(i);
+
+    const block = syntax.block.find(([open]) => source.startsWith(open, i));
+    if (block) {
+      const [open, close] = block;
+      const closed = source.indexOf(close, i + open.length);
+      const stop = closed < 0 ? source.length : closed + close.length;
+      found.push({ line, text: source.slice(i, stop) });
+      advance(stop);
+      previous = "";
+      continue;
+    }
+
+    const marker = syntax.line.find(
+      ({ token, afterAWordBreak }) =>
+        source.startsWith(token, i) && (!afterAWordBreak || i === 0 || WORD_BREAK.test(source.charAt(i - 1))),
+    );
+    if (marker) {
+      const newline = source.indexOf("\n", i);
+      const stop = newline < 0 ? source.length : newline;
+      found.push({ line, text: source.slice(i, stop) });
+      advance(stop);
+      previous = "";
+      continue;
+    }
+
+    const quote = syntax.quotes.find(
+      ({ token, opensMidWord }) =>
+        source.startsWith(token, i) && (opensMidWord || i === 0 || !WORD.test(source.charAt(i - 1))),
+    );
+    if (quote) {
+      advance(endOfQuoted(source, i, quote));
+      previous = quote.token;
+      continue;
+    }
+
+    if (syntax.regexLiterals && char === "/" && opensRegex(previous)) {
+      advance(endOfRegex(source, i));
+      previous = "/";
+      continue;
+    }
+
+    if (WORD.test(char)) {
+      let end = i;
+      while (end < source.length && WORD.test(source.charAt(end))) end += 1;
+      previous = source.slice(i, end);
+      advance(end);
+      continue;
+    }
+
+    if (!/\s/.test(char)) previous = char;
+    advance(i + 1);
+  }
+
+  return found;
+}
+
+const LICENCE = /copyright|spdx-license-identifier|all rights reserved|licen[cs]ed under|permission is hereby granted/i;
+
+// A single sentence wraps to at most a few lines at a normal width, so a longer run at the
+// file's own opening is the shape of a paragraph rather than of one fact.
+const A_WRAPPED_SENTENCE_FITS_WITHIN = 3;
+
+function firstLine(text: string): string {
+  const newline = text.indexOf("\n");
+  return newline < 0 ? text : text.slice(0, newline);
+}
+
+function beginsItsLine(comment: Comment, lines: readonly string[]): boolean {
+  const line = lines[comment.line - 1];
+  return line !== undefined && line.trimStart().startsWith(firstLine(comment.text));
+}
+
+function openingBlock(found: readonly Comment[], source: string): Comment[] {
+  const lines = source.split("\n");
+  const block: Comment[] = [];
+  let next = 1;
+  for (const comment of found) {
+    if (comment.line !== next || !beginsItsLine(comment, lines)) break;
+    block.push(comment);
+    next = comment.line + comment.text.split("\n").length;
+  }
+  return block;
+}
+
+type Check = {
+  readonly find: RegExp;
+  readonly refusal: (match: string) => string;
+};
+
+const CHECKS: readonly Check[] = [
+  {
+    find: /@ts-expect-error|@ts-ignore|\bprettier-ignore\b|\beslint-disable[\w-]*|\bbiome-ignore\b/,
+    refusal: (match) =>
+      `carries the machine-read directive \`${match}\`. Fix what the tool is reporting, or stop running the tool on this file`,
+  },
+  {
+    find: /\bADR[\s-]?\d+|\bdocs\/adr\b|\bRFC[\s-]?\d+|(?:^|[\s(["'`])#\d+\b|[\w.-]+\/[\w.-]+#\d+|\/(?:issues|pull)\/\d+/i,
+    refusal: (match) =>
+      `points at a record or a ticket (${JSON.stringify(match.trim())}). Drop the pointer: a record is reached by searching docs/adr, and the story of the change goes in the commit message`,
+  },
+  {
+    find: /^\/\*\*/,
+    refusal: () =>
+      "opens a doc block. Make the code say it, or put what the types cannot hold on a line comment in the fewest words that carry it",
+  },
+];
+
+function spans(from: number, lineCount: number, within: ReadonlySet<number> | undefined): boolean {
+  if (within === undefined) return true;
+  for (let line = from; line < from + lineCount; line += 1) if (within.has(line)) return true;
+  return false;
+}
+
+export function refusalsIn(path: string, source: string, syntax: Syntax, within?: ReadonlySet<number>): string[] {
+  const out: string[] = [];
+  const found = commentsIn(source, syntax);
+
+  const opening = openingBlock(found, source);
+  const openingText = opening.map((comment) => comment.text).join("\n");
+  const openingLines = opening.reduce((sum, comment) => sum + comment.text.split("\n").length, 0);
+  if (
+    opening.length > 0 &&
+    openingLines > A_WRAPPED_SENTENCE_FITS_WITHIN &&
+    !LICENCE.test(openingText) &&
+    spans(1, openingLines, within)
+  ) {
+    out.push(
+      `${path}:1 opens with a ${openingLines}-line rationale block. A record this long belongs in docs/adr or the repo's decision log, and the code does not point at it`,
+    );
+  }
+
+  for (const comment of found) {
+    if (LICENCE.test(comment.text)) continue;
+    if (!spans(comment.line, comment.text.split("\n").length, within)) continue;
+    for (const check of CHECKS) {
+      const [match] = check.find.exec(comment.text) ?? [];
+      if (match !== undefined) out.push(`${path}:${comment.line} ${check.refusal(match)}`);
+    }
+  }
+  return out;
+}
+
+export function refused(path: string, source: string, within?: ReadonlySet<number>): string[] {
+  const syntax = syntaxOf(path);
+  if (syntax === undefined) throw new Error(unreadable(path));
+  return refusalsIn(path, source, syntax, within);
+}

package/scripts/comments.ts

@@ -1,309 +1,21 @@
 import { Effect, Schema } from "effect";
+import { commentsIn, refusalsIn, syntaxOf, unreadable, type Syntax } from "./comment-matchers.ts";
 
-export type Comment = { line: number; text: string };
-
-type Marker = { readonly token: string; readonly afterAWordBreak: boolean };
-type Quote = { readonly token: string; readonly backslashEscapes: boolean; readonly opensMidWord: boolean };
-
-type Syntax = {
-  readonly line: readonly Marker[];
-  readonly block: readonly (readonly [open: string, close: string])[];
-  readonly quotes: readonly Quote[];
-  readonly regexLiterals: boolean;
-};
-
-const anywhere = (token: string): Marker => ({ token, afterAWordBreak: false });
-const startingAWord = (token: string): Marker => ({ token, afterAWordBreak: true });
-const escaping = (token: string): Quote => ({ token, backslashEscapes: true, opensMidWord: true });
-const literal = (token: string): Quote => ({ token, backslashEscapes: false, opensMidWord: true });
-const outsideAWord = (quote: Quote): Quote => ({ ...quote, opensMidWord: false });
-
-const SLASHES: readonly (readonly [string, string])[] = [["/*", "*/"]];
-const SLASH_SLASH = [startingAWord("//")];
-const DASHES = [anywhere("--")];
-const STRINGS = [escaping('"'), escaping("'")];
-
-const JS: Syntax = {
-  line: SLASH_SLASH,
-  block: SLASHES,
-  quotes: [escaping('"'), outsideAWord(escaping("'")), escaping("`")],
-  regexLiterals: true,
-};
-const CURLY: Syntax = { ...JS, quotes: [...STRINGS, escaping("`")], regexLiterals: false };
-const PHP: Syntax = { line: [...SLASH_SLASH, anywhere("#")], block: SLASHES, quotes: STRINGS, regexLiterals: false };
-const HASH: Syntax = {
-  line: [startingAWord("#")],
-  block: [],
-  quotes: [escaping('"'), literal("'")],
-  regexLiterals: false,
-};
-const YAML: Syntax = { ...HASH, quotes: [escaping('"'), outsideAWord(literal("'"))] };
-const SQL: Syntax = { line: DASHES, block: SLASHES, quotes: STRINGS, regexLiterals: false };
-const LUA: Syntax = { line: DASHES, block: [["--[[", "]]"]], quotes: STRINGS, regexLiterals: false };
-const HASKELL: Syntax = { line: DASHES, block: [["{-", "-}"]], quotes: [escaping('"')], regexLiterals: false };
-const ML: Syntax = { line: [], block: [["(*", "*)"]], quotes: [escaping('"')], regexLiterals: false };
-
-export const SYNTAXES: Readonly<Record<string, Syntax>> = {
-  ts: JS,
-  tsx: JS,
-  mts: JS,
-  cts: JS,
-  js: JS,
-  jsx: JS,
-  mjs: JS,
-  cjs: JS,
-  go: CURLY,
-  rs: CURLY,
-  java: CURLY,
-  kt: CURLY,
-  swift: CURLY,
-  scala: CURLY,
-  c: CURLY,
-  h: CURLY,
-  cc: CURLY,
-  cpp: CURLY,
-  hpp: CURLY,
-  cs: CURLY,
-  php: PHP,
-  py: HASH,
-  rb: HASH,
-  ex: HASH,
-  exs: HASH,
-  sh: HASH,
-  bash: HASH,
-  zsh: HASH,
-  nix: HASH,
-  sql: SQL,
-  lua: LUA,
-  hs: HASKELL,
-  yaml: YAML,
-  yml: YAML,
-  toml: HASH,
-  ml: ML,
-};
+export { SYNTAXES, syntaxOf, type Comment } from "./comment-matchers.ts";
 
 export class UnreadableCode extends Schema.TaggedError<UnreadableCode>()("UnreadableCode", {
   message: Schema.String,
 }) {}
 
 export function syntaxFor(path: string): Effect.Effect<Syntax, UnreadableCode> {
-  const extension = path.slice(path.lastIndexOf(".") + 1);
-  const syntax = SYNTAXES[extension];
-  return syntax
-    ? Effect.succeed(syntax)
-    : Effect.fail(
-        new UnreadableCode({
-          message: `${path} is code the comment checks cannot read: add a comment syntax for .${extension} to scripts/comments.ts`,
-        }),
-      );
-}
-
-const WORD = /[\w$]/;
-
-const KEYWORDS = new Set([
-  "return",
-  "typeof",
-  "instanceof",
-  "in",
-  "of",
-  "new",
-  "delete",
-  "void",
-  "throw",
-  "case",
-  "do",
-  "else",
-  "yield",
-  "await",
-]);
-
-const AFTER_A_VALUE = /[)\]}"'`]/;
-
-function opensRegex(previous: string): boolean {
-  if (previous === "") return true;
-  if (WORD.test(previous[0]!)) return KEYWORDS.has(previous);
-  return !AFTER_A_VALUE.test(previous);
-}
-
-const WORD_BREAK = /[\s;|&(]/;
-
-function endOfQuoted(source: string, start: number, quote: Quote): number {
-  let i = start + quote.token.length;
-  while (i < source.length) {
-    if (quote.backslashEscapes && source[i] === "\\") i += 2;
-    else if (source.startsWith(quote.token, i)) return i + quote.token.length;
-    else i += 1;
-  }
-  return start + quote.token.length;
-}
-
-function endOfRegex(source: string, start: number): number {
-  let i = start + 1;
-  let inClass = false;
-  while (i < source.length) {
-    const char = source[i]!;
-    if (char === "\\") i += 2;
-    else if (char === "\n") return i;
-    else {
-      if (char === "[") inClass = true;
-      else if (char === "]") inClass = false;
-      else if (char === "/" && !inClass) return i + 1;
-      i += 1;
-    }
-  }
-  return source.length;
+  const syntax = syntaxOf(path);
+  return syntax ? Effect.succeed(syntax) : Effect.fail(new UnreadableCode({ message: unreadable(path) }));
 }
 
 export const comments = Effect.fn("comments")(function* (path: string, source: string) {
-  const syntax = yield* syntaxFor(path);
-  const found: Comment[] = [];
-  let i = 0;
-  let line = 1;
-  let previous = "";
-
-  const advance = (to: number): void => {
-    for (let k = i; k < to; k++) if (source[k] === "\n") line += 1;
-    i = to;
-  };
-
-  while (i < source.length) {
-    const char = source[i]!;
-
-    const block = syntax.block.find(([open]) => source.startsWith(open, i));
-    if (block) {
-      const [open, close] = block;
-      const closed = source.indexOf(close, i + open.length);
-      const stop = closed < 0 ? source.length : closed + close.length;
-      found.push({ line, text: source.slice(i, stop) });
-      advance(stop);
-      previous = "";
-      continue;
-    }
-
-    const marker = syntax.line.find(
-      ({ token, afterAWordBreak }) =>
-        source.startsWith(token, i) && (!afterAWordBreak || i === 0 || WORD_BREAK.test(source[i - 1]!)),
-    );
-    if (marker) {
-      const newline = source.indexOf("\n", i);
-      const stop = newline < 0 ? source.length : newline;
-      found.push({ line, text: source.slice(i, stop) });
-      advance(stop);
-      previous = "";
-      continue;
-    }
-
-    const quote = syntax.quotes.find(
-      ({ token, opensMidWord }) =>
-        source.startsWith(token, i) && (opensMidWord || i === 0 || !WORD.test(source[i - 1]!)),
-    );
-    if (quote) {
-      advance(endOfQuoted(source, i, quote));
-      previous = quote.token;
-      continue;
-    }
-
-    if (syntax.regexLiterals && char === "/" && opensRegex(previous)) {
-      advance(endOfRegex(source, i));
-      previous = "/";
-      continue;
-    }
-
-    if (WORD.test(char)) {
-      let end = i;
-      while (end < source.length && WORD.test(source[end]!)) end += 1;
-      previous = source.slice(i, end);
-      advance(end);
-      continue;
-    }
-
-    if (!/\s/.test(char)) previous = char;
-    advance(i + 1);
-  }
-
-  return found;
+  return commentsIn(source, yield* syntaxFor(path));
 });
 
-const LICENCE = /copyright|spdx-license-identifier|all rights reserved|licen[cs]ed under|permission is hereby granted/i;
-
-// A single sentence wraps to at most a few lines at a normal width, so a longer run at the
-// file's own opening is the shape of a paragraph rather than of one fact.
-const A_WRAPPED_SENTENCE_FITS_WITHIN = 3;
-
-function beginsItsLine(comment: Comment, lines: readonly string[]): boolean {
-  return lines[comment.line - 1]!.trimStart().startsWith(comment.text.split("\n")[0]!);
-}
-
-function openingBlock(found: readonly Comment[], source: string): Comment[] {
-  const lines = source.split("\n");
-  if (found.length === 0 || found[0]!.line !== 1 || !beginsItsLine(found[0]!, lines)) return [];
-  const block = [found[0]!];
-  let next = found[0]!.line + found[0]!.text.split("\n").length;
-  for (let i = 1; i < found.length && found[i]!.line === next && beginsItsLine(found[i]!, lines); i++) {
-    block.push(found[i]!);
-    next = found[i]!.line + found[i]!.text.split("\n").length;
-  }
-  return block;
-}
-
-type Check = {
-  readonly find: RegExp;
-  readonly refusal: (match: string) => string;
-};
-
-const CHECKS: readonly Check[] = [
-  {
-    find: /@ts-expect-error|@ts-ignore|\bprettier-ignore\b|\beslint-disable[\w-]*|\bbiome-ignore\b/,
-    refusal: (match) =>
-      `carries the machine-read directive \`${match}\`. Fix what the tool is reporting, or stop running the tool on this file`,
-  },
-  {
-    find: /\bADR[\s-]?\d+|\bdocs\/adr\b|\bRFC[\s-]?\d+|(?:^|[\s(["'`])#\d+\b|[\w.-]+\/[\w.-]+#\d+|\/(?:issues|pull)\/\d+/i,
-    refusal: (match) =>
-      `points at a record or a ticket (${JSON.stringify(match.trim())}). Drop the pointer: a record is reached by searching docs/adr, and the story of the change goes in the commit message`,
-  },
-  {
-    find: /^\/\*\*/,
-    refusal: () =>
-      "opens a doc block. Make the code say it, or put what the types cannot hold on a line comment in the fewest words that carry it",
-  },
-];
-
-function spans(from: number, lineCount: number, within: ReadonlySet<number> | undefined): boolean {
-  if (within === undefined) return true;
-  for (let line = from; line < from + lineCount; line += 1) if (within.has(line)) return true;
-  return false;
-}
-
-export const refused = Effect.fn("refused")(function* (
-  path: string,
-  source: string,
-  within?: ReadonlySet<number>,
-) {
-  const out: string[] = [];
-  const found = yield* comments(path, source);
-
-  const opening = openingBlock(found, source);
-  const openingText = opening.map((comment) => comment.text).join("\n");
-  const openingLines = opening.reduce((sum, comment) => sum + comment.text.split("\n").length, 0);
-  if (
-    opening.length > 0 &&
-    openingLines > A_WRAPPED_SENTENCE_FITS_WITHIN &&
-    !LICENCE.test(openingText) &&
-    spans(1, openingLines, within)
-  ) {
-    out.push(
-      `${path}:1 opens with a ${openingLines}-line rationale block. A record this long belongs in docs/adr or the repo's decision log, and the code does not point at it`,
-    );
-  }
-
-  for (const comment of found) {
-    if (LICENCE.test(comment.text)) continue;
-    if (!spans(comment.line, comment.text.split("\n").length, within)) continue;
-    for (const check of CHECKS) {
-      const [match] = check.find.exec(comment.text) ?? [];
-      if (match !== undefined) out.push(`${path}:${comment.line} ${check.refusal(match)}`);
-    }
-  }
-  return out;
+export const refused = Effect.fn("refused")(function* (path: string, source: string, within?: ReadonlySet<number>) {
+  return refusalsIn(path, source, yield* syntaxFor(path), within);
 });

package/scripts/gates.ts

@@ -1,21 +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";
 
-export const KIT_GATES: readonly KitGate[] = [
-  { bin: "checks-lint-coverage", script: "lint-coverage.sh", reads: "tree" },
-  { bin: "checks-test-layout", script: "test-layout.ts", reads: "tree" },
-  { bin: "checks-commit-identity", script: "commit-identity.ts", reads: "range" },
-  { bin: "checks-comment-gate", script: "comment-gate.ts", reads: "range" },
-  { bin: "checks-suppressions-ratchet", script: "suppressions-ratchet.ts", reads: "range" },
-  { bin: "checks-ci-wiring", script: "ci-wiring.ts", reads: "tree" },
-];
+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

@@ -25,3 +25,17 @@ export const git = Effect.fn("git")(
   },
   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

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { DEFAULT_BRANCH, KIT_GATES, type KitGate } from "./gates.ts";
+import { DEFAULT_BRANCH, LintWiring, selectedGates, type KitGate } from "./gates.ts";
 import { git } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
 
@@ -20,6 +20,10 @@ class GatesUndecided extends Schema.TaggedError<GatesUndecided>()("GatesUndecide
   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";
@@ -52,30 +56,38 @@ const pullRequestEnds = Effect.fn("pullRequestEnds")(function* (eventPath: strin
   };
 });
 
-const decodeManifest = Schema.decodeUnknownEffect(
-  Schema.fromJsonString(
-    Schema.Struct({
-      ciWiring: Schema.optionalKey(Schema.Struct({ defaultBranch: Schema.optionalKey(Schema.NonEmptyString) })),
-    }),
-  ),
-);
+const decodeWiring = Schema.decodeUnknownEffect(Schema.fromJsonString(LintWiring));
 
-const declaredDefaultBranch = Effect.gen(function* () {
+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(decodeManifest));
-  return ciWiring?.defaultBranch ?? DEFAULT_BRANCH;
-}).pipe(
-  Effect.mapError((cause) => new RangeUnresolved({ message: `cannot read ciWiring.defaultBranch: ${cause.message}` })),
-);
+  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 localEnds = git(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]).pipe(
-  Effect.map((ref) => ref.trim()),
-  Effect.catchTag("GitFailure", () => declaredDefaultBranch.pipe(Effect.map((branch) => `origin/${branch}`))),
-  Effect.map((base) => ({ base, head: "HEAD", source: `HEAD against ${base}` })),
-);
+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}` })),
+  );
 
-const endsOf = Effect.fn("endsOf")(function* (args: readonly string[]) {
+// 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}` };
@@ -92,7 +104,7 @@ const endsOf = Effect.fn("endsOf")(function* (args: readonly string[]) {
     }
     return yield* pullRequestEnds(event.path.value);
   }
-  return yield* localEnds;
+  return yield* localEnds(defaultBranch);
 });
 
 const commitOf = (ref: string) =>
@@ -105,8 +117,8 @@ const commitOf = (ref: string) =>
 
 // 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[]) {
-  const ends = yield* endsOf(args);
+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()),
@@ -142,16 +154,21 @@ const runGate = Effect.fn("runGate")(function* (gate: KitGate, range: Range) {
 });
 
 const lint = Effect.gen(function* () {
-  const range = yield* resolveRange(process.argv.slice(2));
+  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(KIT_GATES, (gate) => runGate(gate, range));
+  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}: ${KIT_GATES.length} gate(s) pass`);
+    yield* Console.log(`${NAME}: ${gates.length} gate(s) pass`);
     return true;
   }
-  const summary = `${failed.length} of ${KIT_GATES.length} gate(s) failed: ${failed.map((verdict) => verdict.gate.bin).join(", ")}`;
+  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 });
   }

package/scripts/suppressions-ratchet.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
-import { git } from "./git.ts";
+import { git, parentOrEmptyTree } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
 
 export const SUPPRESSIONS = "oxlint-suppressions.json";
@@ -99,10 +99,10 @@ const mergeBase = Effect.fn("mergeBase")(function* (base: string, head: string)
   return commit.trim();
 });
 
-const suppressionsAt = Effect.fn("suppressionsAt")(function* (commit: string) {
-  const blob = (yield* git(["ls-tree", "--object-only", commit, "--", SUPPRESSIONS])).trim();
+const suppressionsAt = Effect.fn("suppressionsAt")(function* (treeish: string) {
+  const blob = (yield* git(["ls-tree", "--object-only", treeish, "--", SUPPRESSIONS])).trim();
   if (blob === "") return new Map() satisfies Suppressions;
-  return yield* parseSuppressions(yield* git(["cat-file", "blob", blob]), `${SUPPRESSIONS} at ${commit}`);
+  return yield* parseSuppressions(yield* git(["cat-file", "blob", blob]), `${SUPPRESSIONS} at ${treeish}`);
 });
 
 export const runRange = Effect.fn("runRange")(function* (base: string, head: string) {
@@ -112,11 +112,16 @@ export const runRange = Effect.fn("runRange")(function* (base: string, head: str
   return compareSuppressions(yield* suppressionsAt(branchPoint), yield* suppressionsAt(headCommit));
 });
 
+export const runTip = Effect.fn("runTip")(function* (tip: string) {
+  const tipCommit = yield* commitOf(tip);
+  return compareSuppressions(yield* suppressionsAt(yield* parentOrEmptyTree(tipCommit)), yield* suppressionsAt(tipCommit));
+});
+
 const ratchet = Effect.gen(function* () {
   const [first, second, ...extra] = process.argv.slice(2);
   if (first === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
 
-  const result = second !== undefined ? yield* runRange(first, second) : yield* runRange(`${first}^`, first);
+  const result = second !== undefined ? yield* runRange(first, second) : yield* runTip(first);
 
   yield* Console.log(report(result));
   return result.rises.length === 0;