@avi2dg/checks 0.16.0 → 0.18.0

package/docs/gates/checks-comment-gate.md

@@ -18,6 +18,8 @@ It passes over a file with any other extension.
 `scripts/comment-matchers.ts` holds the scanner, the comment syntaxes and a synchronous `refused()`, and imports nothing.
 A host such as a hook bundle can therefore copy it alone into a directory with no `node_modules` and import it as `@avi2dg/checks/scripts/comment-matchers.ts`.
 The kit's own dependency cruise fails when that file gains an import.
+`REFUSED_DIRECTIVES` in that file owns the refused directive names, and the checker builds its directive pattern from that list, so the two cannot disagree.
+A consumer reads the same contract by importing `REFUSED_DIRECTIVES` from `@avi2dg/checks/scripts/comment-matchers.ts`.
 `scripts/comments.ts` wraps the same matchers in Effect for the gate and for [checks-backtest](checks-backtest.md).
 
 ## Arguments

package/docs/gates/checks-quality.md

@@ -1,6 +1,6 @@
 # checks-quality
 
-`checks-quality` is the bin that writes what `quality.json` declares for oxlint and tsc into generated fragments and checks them, and a reader looks it up when a fragment is stale.
+`checks-quality` is the bin that writes what `quality.json` declares into generated fragments and workflows and checks them, and a reader looks it up when generated text is stale.
 
 ## What it checks
 
@@ -29,11 +29,20 @@ A rule only this repository needs stays in its own `.oxlintrc.json`, whose overr
 }
 ```
 
+GitHub Actions reads its own YAML and nothing else, so `checks-quality generate` also writes the kit recipe workflows whole.
+`.github/workflows/ci.yml` runs every `gates.ci` command but the title lint as its own step after a frozen install.
+`.github/workflows/commitlint.yml` lints the pull request title with the installed kit config.
+A step one repository alone needs lives in another workflow file, never in the recipe.
+All generated workflows are committed.
+
 `checks-quality --check` fails when any of these holds:
 
 - A fragment is missing, or differs from what `generate` would write from `quality.json` and the installed kit's presets.
 - A fragment is left over once `quality.json` stops declaring `sources.effect`.
+- A generated workflow is missing, or differs from what `generate` would write from `quality.json` and the kit recipe.
 - `.oxlintrc.json` or `tsconfig.json` does not list its fragment in `extends`, so the tool never reads it.
+- `.oxlintrc.json` does not extend `./node_modules/@avi2dg/checks/oxlintrc.json`, so the kit's oxlint rules are not loaded.
+- `tsconfig.json` does not extend `@avi2dg/checks/tsconfig.effect.json`, the one accepted spelling of the kit's Effect config.
 - A `sources.effect.paths` or `sources.production` glob matches no tracked or untracked file, so it holds nothing.
 
 Two details of the fragments are easy to get wrong, so the kit's tests pin both:
@@ -47,7 +56,10 @@ Two details of the fragments are easy to get wrong, so the kit's tests pin both:
 
 ## What it reads
 
-It reads the working tree: `quality.json`, the presets of the installed kit, `.oxlintrc.json`, `tsconfig.json` and the two fragments.
+It reads the working tree: `quality.json`, the presets of the installed kit, `.oxlintrc.json`, `tsconfig.json`, the two fragments and the generated workflows.
+It reads the root `package.json` name, since only the kit's own tree lints titles with its root `commitlint.config.js`.
+The name also decides which kit configs `extends` must list, since the kit's own tree extends its root `oxlintrc.json` and `tsconfig.effect.json`.
+It looks for `.bun-version`, and the suite pins its bun to that file when the file exists.
 It lists the tracked and untracked files to see what each declared glob matches.
 
 ## Arguments
@@ -57,15 +69,15 @@ checks-quality generate
 checks-quality --check
 ```
 
-`generate` writes the fragments, removes a left-over one, then runs the same check as `--check`.
+`generate` writes the fragments and the workflows, removes a left-over one, then runs the same check as `--check`.
 `--check` writes nothing.
 
 ## Exit codes
 
 | Code | When |
 | --- | --- |
-| 0 | the fragments hold what `quality.json` declares |
-| 1 | a fragment is stale, missing, left over or not extended, or a declared glob matches no file |
+| 0 | the generated files hold what `quality.json` declares |
+| 1 | a generated file is stale, missing or left over, a fragment is not extended, the kit's config is not extended, or a declared glob matches no file |
 | 2 | `quality.json` does not decode, or the arguments are neither `generate` nor `--check` |
 
 ## Sample output
@@ -76,16 +88,19 @@ checks-quality: 2 problem(s) with what quality.json declares:
   tsconfig.json does not extend ./tsconfig.quality.json, so the language service never reads it
 ```
 
-A passing run says what the fragments hold:
+A passing run says what the generated files hold:
 
 ```
-checks-quality: oxlintrc.quality.json and tsconfig.quality.json hold what quality.json declares
+checks-quality: oxlintrc.quality.json and tsconfig.quality.json and .github/workflows/ci.yml and .github/workflows/commitlint.yml hold what quality.json declares
 ```
 
+A stale workflow is reported the same way as a stale fragment.
+
 ## Opting out
 
 It runs only in a repository that tracks `quality.json`, and a selection in `quality.json` always keeps it, since the file it sits in is what makes it apply.
-A repository that declares no `sources.effect` gets no fragment, and the check then only refuses a left-over one.
+A repository that declares no `sources.effect` gets no fragment, and the check then refuses a left-over one.
+Every repository gets the title lint workflow, and one with `gates.ci` gets the suite with it.
 
 ## Related topics
 

package/docs/gates/checks-size-budget.md

@@ -13,7 +13,7 @@ It holds production and test files to the size budget, and lists every other fil
 
 A production file is one under `sources.production`, and a test file is a tracked `.ts` or `.tsx` file under `tests/`.
 A test file keeps to the tests budget, and every other file keeps to the production budget.
-It runs oxlint with a configuration of five rules and nothing else, one for each limit.
+It runs oxlint with a configuration of five rules, one for each limit, and the kit's own plugin bundle, which holds the complexity rule.
 The kit sets each limit:
 
 <!-- generated size-limits: bun run build writes it from SIZE_RULES and SIZE_DEFAULTS in scripts/size-rules.ts and scripts/doc-blocks.ts -->
@@ -23,7 +23,7 @@ The kit sets each limit:
 | `fileLines` | The most lines a file may hold, blank and comment lines counted | `max-lines` | 400 | 600 |
 | `functionLines` | The most lines a function may span, blank and comment lines counted | `max-lines-per-function` | 100 | none |
 | `statements` | The most statements a function may hold | `max-statements` | 30 | 50 |
-| `complexity` | The highest cyclomatic complexity a function may reach, a switch counted once | `complexity` | 15 | 15 |
+| `complexity` | The highest cognitive complexity a function may reach, a switch counted once | `effect-channel/cognitive-complexity` | 15 | 15 |
 | `depth` | The deepest a block may nest inside a function | `max-depth` | 4 | 4 |
 
 <!-- end generated size-limits -->
@@ -88,8 +88,8 @@ With one it is that commit against its parent, or against the empty tree for a r
 size-budget: 2 overrun(s) grew past the base in the production and test files the range adds or changes:
   src/billing/invoice.ts: max-lines over by 31 in total, up from 19
     src/billing/invoice.ts: File has too many lines (431). Maximum allowed is 400.
-  src/billing/ledger.ts: complexity over by 3 in total, up from 0
-    src/billing/ledger.ts:12: function `settle` has a complexity of 18. Maximum allowed is 15.
+  src/billing/ledger.ts: cognitive-complexity over by 3 in total, up from 0
+    src/billing/ledger.ts:12: function `settle` has a cognitive complexity of 18. Maximum allowed is 15.
 size-budget: advisory, 1 overrun(s) where the budget does not hold yet:
   tests/e2e/billing.test.ts: File has too many lines (612). Maximum allowed is 600.
 ```

package/oxlintrc.json

@@ -16,6 +16,7 @@
     "eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_", "ignoreRestSiblings": true }],
     "typescript/no-unsafe-type-assertion": "error",
     "typescript/no-non-null-assertion": "error",
+    "typescript/no-deprecated": "error",
     "typescript/consistent-return": "off"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -32,6 +32,7 @@
     "scripts/commit-identity.ts",
     "scripts/mutation-compare.ts",
     "scripts/ci-wiring.ts",
+    "scripts/shell-command.ts",
     "scripts/comment-matchers.ts",
     "scripts/prose-matchers.ts",
     "scripts/comments.ts",
@@ -41,6 +42,7 @@
     "scripts/quality-file.ts",
     "scripts/quality.ts",
     "scripts/size-budget.ts",
+    "scripts/range-gate.ts",
     "scripts/size-rules.ts",
     "scripts/repetition.ts",
     "scripts/feature-owners.ts",

package/quality.schema.json

@@ -178,7 +178,7 @@
             "complexity": {
               "type": "integer",
               "exclusiveMinimum": 0,
-              "description": "The highest cyclomatic complexity a function may reach, a switch counted once; 15 when absent"
+              "description": "The highest cognitive complexity a function may reach, a switch counted once; 15 when absent"
             },
             "depth": {
               "type": "integer",
@@ -205,7 +205,7 @@
             "complexity": {
               "type": "integer",
               "exclusiveMinimum": 0,
-              "description": "The highest cyclomatic complexity a function may reach, a switch counted once; 15 when absent"
+              "description": "The highest cognitive complexity a function may reach, a switch counted once; 15 when absent"
             },
             "depth": {
               "type": "integer",

package/scripts/backtest.ts

@@ -27,65 +27,72 @@ function withoutLine(refusal: string): string {
   return refusal.replace(/^(\S+?):\d+ /, "$1 ");
 }
 
-export const backtest = Effect.fn("backtest")(function* (count: string) {
-  const lines: string[] = [];
-  const commits = (yield* git(["log", "--first-parent", "--format=%H%x09%P%x09%s", "-n", count]))
+type Commit = {
+  readonly sha: string;
+  readonly parent: string;
+  readonly subject: string;
+};
+
+const firstParentCommits = Effect.fn("firstParentCommits")(function* (count: string) {
+  return (yield* git(["log", "--first-parent", "--format=%H%x09%P%x09%s", "-n", count]))
     .trim()
     .split("\n")
-    .map((row) => {
+    .map((row): Commit => {
       const [sha = "", parents = "", subject = ""] = row.split("\t");
       return { sha, parent: parents.split(" ")[0] ?? "", subject };
     })
     .filter((commit) => commit.sha !== "" && commit.parent !== "");
+});
 
-  const landed: Landed[] = [];
+const addedLines = Effect.fn("addedLines")(function* ({ sha, parent }: Commit, changed: readonly string[]) {
+  const numstat = (yield* git(["diff", "--numstat", parent, sha, "--", ...changed])).trim();
+  return numstat === "" ? 0 : numstat.split("\n").reduce((sum, row) => sum + Number(row.split("\t")[0] ?? 0), 0);
+});
+
+const pathLanded = Effect.fn("pathLanded")(function* ({ sha, parent }: Commit, path: string) {
+  const after = yield* at(sha, path);
+  if (Option.isNone(after)) return { comments: 0, refusals: [] };
+  const before = Option.getOrElse(yield* at(parent, path), () => "");
+
+  const wasRefused = new Set((yield* refused(path, before)).map(withoutLine));
+  const refusals = (yield* refused(path, after.value)).filter((refusal) => !wasRefused.has(withoutLine(refusal)));
 
-  for (const { sha, parent, subject } of commits) {
-    const changed = (yield* git(["diff", "--name-only", "--diff-filter=d", parent, sha]))
-      .trim()
-      .split("\n")
-      .filter((path) => path !== "" && readable(path));
-    if (changed.length === 0) continue;
-
-    const numstat = (yield* git(["diff", "--numstat", parent, sha, "--", ...changed])).trim();
-    const added =
-      numstat === ""
-        ? 0
-        : numstat.split("\n").reduce((sum, row) => sum + Number(row.split("\t")[0] ?? 0), 0);
-
-    let commentLines = 0;
-    const refusals: string[] = [];
-
-    for (const path of changed) {
-      const after = yield* at(sha, path);
-      if (Option.isNone(after)) continue;
-      const before = Option.getOrElse(yield* at(parent, path), () => "");
-
-      const wasRefused = new Set((yield* refused(path, before)).map(withoutLine));
-      for (const refusal of yield* refused(path, after.value)) {
-        if (!wasRefused.has(withoutLine(refusal))) refusals.push(refusal);
-      }
-
-      const wasComment = new Set((yield* comments(path, before)).map((one) => one.text));
-      for (const one of yield* comments(path, after.value)) {
-        if (!wasComment.has(one.text)) commentLines += one.text.split("\n").length;
-      }
-    }
-
-    landed.push({ sha: sha.slice(0, 7), subject, added, comments: commentLines, refusals });
+  const wasComment = new Set((yield* comments(path, before)).map((one) => one.text));
+  const added = (yield* comments(path, after.value)).filter((one) => !wasComment.has(one.text));
+  return { comments: added.reduce((sum, one) => sum + one.text.split("\n").length, 0), refusals };
+});
+
+const commitLanded = Effect.fn("commitLanded")(function* (commit: Commit) {
+  const changed = (yield* git(["diff", "--name-only", "--diff-filter=d", commit.parent, commit.sha]))
+    .trim()
+    .split("\n")
+    .filter((path) => path !== "" && readable(path));
+  if (changed.length === 0) return Option.none<Landed>();
+
+  const added = yield* addedLines(commit, changed);
+  let commentLines = 0;
+  const refusals: string[] = [];
+  for (const path of changed) {
+    const one = yield* pathLanded(commit, path);
+    commentLines += one.comments;
+    refusals.push(...one.refusals);
   }
+  return Option.some<Landed>({ sha: commit.sha.slice(0, 7), subject: commit.subject, added, comments: commentLines, refusals });
+});
 
+function summary(landed: readonly Landed[]): string {
+  const lines: string[] = [];
   const total = (pick: (one: Landed) => number): number => landed.reduce((sum, one) => sum + pick(one), 0);
-  const addedLines = total((one) => one.added);
+  const added = total((one) => one.added);
   const commentLines = total((one) => one.comments);
   const refusalCount = total((one) => one.refusals.length);
 
   for (const one of landed) {
     lines.push(`${one.sha}\t${one.added}\t${one.comments}\t${one.refusals.length}\t${one.subject.slice(0, 58)}`);
   }
-  lines.push(`${landed.length} commits touching code, ${addedLines} added lines`);
+  lines.push(`${landed.length} commits touching code, ${added} added lines`);
   lines.push(
-    `comment lines added: ${commentLines} (${((commentLines / Math.max(addedLines, 1)) * 100).toFixed(1)}% of added lines)`,
+    `comment lines added: ${commentLines} (${((commentLines / Math.max(added, 1)) * 100).toFixed(1)}% of added lines)`,
   );
   lines.push(`refusals introduced: ${refusalCount}`);
   for (const one of landed) {
@@ -94,6 +101,15 @@ export const backtest = Effect.fn("backtest")(function* (count: string) {
     for (const refusal of one.refusals) lines.push(`    ${refusal}`);
   }
   return lines.join("\n");
+}
+
+export const backtest = Effect.fn("backtest")(function* (count: string) {
+  const landed: Landed[] = [];
+  for (const commit of yield* firstParentCommits(count)) {
+    const one = yield* commitLanded(commit);
+    if (Option.isSome(one)) landed.push(one.value);
+  }
+  return summary(landed);
 });
 
 const main = Effect.gen(function* () {

package/scripts/ci-wiring.ts

@@ -4,8 +4,9 @@ import { git } from "./git.ts";
 import { runMain } from "./main.ts";
 import { DEFAULT_BRANCH, ENTRY_POINT, EVERY_REPOSITORY, KIT_GATES, QUALITY_FILE, selectedGates, type KitGate } from "./gates.ts";
 import { readQuality, type Quality } from "./quality-file.ts";
+import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
 
-export type Command = readonly string[];
+export type { Command };
 
 export type Gate = {
   readonly command: string;
@@ -61,8 +62,6 @@ const CONSTANTS = new Map([
   ["false", false],
 ]);
 const STATUS_OVERRIDE = /\b(?:always|failure|cancelled)\s*\(/;
-const VARIABLE = /^\$(?:[A-Za-z_][A-Za-z0-9_]*|\{[A-Za-z_][A-Za-z0-9_]*\})/;
-const UNPLAIN = new Set(["|", "&", ";", "<", ">", "(", ")", "`", "\\", "#", "\n"]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -74,66 +73,6 @@ function names(value: unknown): readonly string[] | undefined {
   return value.filter((entry): entry is string => typeof entry === "string");
 }
 
-function expansion(text: string, from: number): number | undefined {
-  const match = VARIABLE.exec(text.slice(from));
-  return match === null ? undefined : from + match[0].length;
-}
-
-// A script counts only when it is one line of plain words: any shell control, redirection or
-// substitution can run the gate without its failure failing the step.
-function plainCommand(script: string): Command | undefined {
-  const line = script.trim();
-  const words: string[] = [];
-  let word: string | undefined;
-  for (let index = 0; index < line.length; index += 1) {
-    const char = line.charAt(index);
-    if (char === " " || char === "\t") {
-      if (word !== undefined) words.push(word);
-      word = undefined;
-    } else if (char === "'") {
-      const close = line.indexOf("'", index + 1);
-      if (close === -1) return undefined;
-      word = (word ?? "") + line.slice(index + 1, close);
-      index = close;
-    } else if (char === '"') {
-      let quoted = "";
-      for (index += 1; line.charAt(index) !== '"'; index += 1) {
-        const inner = line.charAt(index);
-        if (inner === "" || inner === "\\" || inner === "`") return undefined;
-        if (inner === "$") {
-          const end = expansion(line, index);
-          if (end === undefined) return undefined;
-          quoted += line.slice(index, end);
-          index = end - 1;
-        } else {
-          quoted += inner;
-        }
-      }
-      word = (word ?? "") + quoted;
-    } else if (char === "$") {
-      const end = expansion(line, index);
-      if (end === undefined) return undefined;
-      word = (word ?? "") + line.slice(index, end);
-      index = end - 1;
-    } else if (UNPLAIN.has(char)) {
-      return undefined;
-    } else {
-      word = (word ?? "") + char;
-    }
-  }
-  if (word !== undefined) words.push(word);
-  return words.length === 0 ? undefined : words;
-}
-
-function invokes(command: Command | undefined, gate: Command): boolean {
-  return command !== undefined && gate.length <= command.length && gate.every((word, index) => command[index] === word);
-}
-
-function mentions(script: string, gate: Command): boolean {
-  const tokens = script.split(/[\s|&;<>()`]+/);
-  return tokens.some((_, start) => invokes(tokens.slice(start), gate));
-}
-
 function constant(value: unknown): boolean | undefined {
   if (typeof value === "boolean") return value;
   if (typeof value !== "string") return undefined;

package/scripts/comment-gate.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { Console, Effect, Option } from "effect";
 import { refused, syntaxOf } from "./comments.ts";
-import { changedLines, git, parentOrEmptyTree } from "./git.ts";
-import { runMain, Usage } from "./main.ts";
+import { changedLines, git, parentOrEmptyTree, refArgs } from "./git.ts";
+import { runMain } from "./main.ts";
 
 export type GateResult = {
   readonly files: number;
@@ -41,8 +41,7 @@ export function report({ files, addedLines, violations }: GateResult): string {
 }
 
 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 { first, second } = yield* refArgs(process.argv.slice(2), USAGE);
 
   const root = (yield* git(["rev-parse", "--show-toplevel"], process.cwd())).trim();
   const base = second === undefined ? yield* parentOrEmptyTree(first, root) : first;

package/scripts/comment-matchers.ts

@@ -147,70 +147,67 @@ function endOfRegex(source: string, start: number): number {
   return source.length;
 }
 
+type Token = { readonly stop: number; readonly previous: string };
+
+function endOfBlockComment(source: string, i: number, syntax: Syntax): number | undefined {
+  const block = syntax.block.find(([open]) => source.startsWith(open, i));
+  if (block === undefined) return undefined;
+  const [open, close] = block;
+  const closed = source.indexOf(close, i + open.length);
+  return closed < 0 ? source.length : closed + close.length;
+}
+
+function endOfLineComment(source: string, i: number, syntax: Syntax): number | undefined {
+  const marker = syntax.line.find(
+    ({ token, afterAWordBreak }) =>
+      source.startsWith(token, i) && (!afterAWordBreak || i === 0 || WORD_BREAK.test(source.charAt(i - 1))),
+  );
+  if (marker === undefined) return undefined;
+  const newline = source.indexOf("\n", i);
+  return newline < 0 ? source.length : newline;
+}
+
+function endOfWord(source: string, i: number): number {
+  let end = i;
+  while (end < source.length && WORD.test(source.charAt(end))) end += 1;
+  return end;
+}
+
+function codeToken(source: string, i: number, syntax: Syntax, previous: string): Token {
+  const quote = syntax.quotes.find(
+    ({ token, opensMidWord }) =>
+      source.startsWith(token, i) && (opensMidWord || i === 0 || !WORD.test(source.charAt(i - 1))),
+  );
+  if (quote) return { stop: endOfQuoted(source, i, quote), previous: quote.token };
+
+  const char = source.charAt(i);
+  if (syntax.regexLiterals && char === "/" && opensRegex(previous)) return { stop: endOfRegex(source, i), previous: "/" };
+  if (WORD.test(char)) {
+    const end = endOfWord(source, i);
+    return { stop: end, previous: source.slice(i, end) };
+  }
+  return { stop: i + 1, previous: /\s/.test(char) ? previous : char };
+}
+
+function newlinesIn(source: string, from: number, to: number): number {
+  let count = 0;
+  for (let k = from; k < to; k++) if (source[k] === "\n") count += 1;
+  return count;
+}
+
 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);
+    const commentStop = endOfBlockComment(source, i, syntax) ?? endOfLineComment(source, i, syntax);
+    if (commentStop !== undefined) found.push({ line, text: source.slice(i, commentStop) });
+    const token = commentStop === undefined ? codeToken(source, i, syntax, previous) : { stop: commentStop, previous: "" };
+    line += newlinesIn(source, i, token.stop);
+    i = token.stop;
+    previous = token.previous;
   }
 
   return found;
@@ -244,6 +241,24 @@ function openingBlock(found: readonly Comment[], source: string): Comment[] {
   return block;
 }
 
+export const REFUSED_DIRECTIVES = [
+  "@ts-expect-error",
+  "@ts-ignore",
+  "biome-ignore",
+  "eslint-disable",
+  "prettier-ignore",
+] as const satisfies readonly string[];
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+const directiveSource = (name: string): string => {
+  const escaped = escapeRegExp(name);
+  if (name === "eslint-disable") return `\\b${escaped}[\\w-]*`;
+  return /^[\w]/.test(name) ? `\\b${escaped}\\b` : escaped;
+};
+
+const DIRECTIVE = new RegExp(REFUSED_DIRECTIVES.map(directiveSource).join("|"));
+
 type Check = {
   readonly find: RegExp;
   readonly refusal: (match: string) => string;
@@ -251,7 +266,7 @@ type Check = {
 
 const CHECKS: readonly Check[] = [
   {
-    find: /@ts-expect-error|@ts-ignore|\bprettier-ignore\b|\beslint-disable[\w-]*|\bbiome-ignore\b/,
+    find: DIRECTIVE,
     refusal: (match) =>
       `carries the machine-read directive \`${match}\`. Fix what the tool is reporting, or stop running the tool on this file`,
   },

package/scripts/commit-identity.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
-import { git } from "./git.ts";
-import { runMain, Usage } from "./main.ts";
+import { git, refArgs } from "./git.ts";
+import { runMain } from "./main.ts";
 import { readQuality, type Identity } from "./quality-file.ts";
 
 type Commit = {
@@ -98,8 +98,7 @@ function inspect(commit: Commit, allowed: readonly Identity[]): Offence | undefi
 }
 
 const check = Effect.gen(function* () {
-  const [first, second, ...extra] = process.argv.slice(2);
-  if (first === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
+  const { first, second } = yield* refArgs(process.argv.slice(2), USAGE);
   const range = second === undefined ? first : `${first}..${second}`;
   const revisions = second === undefined ? ["-1", range] : [range];
 

package/scripts/doc-outline.ts

@@ -156,32 +156,50 @@ function missing(slot: Slot, level: number): string {
   return slot.type === "fixed" ? `lacks ${marked(level, slot.text)}` : `lacks a ${marked(level, slot.placeholder)} section`;
 }
 
+type Placement =
+  | { readonly kind: "behind"; readonly index: number }
+  | { readonly kind: "unplaced" }
+  | { readonly kind: "placed"; readonly index: number; readonly slot: Slot; readonly at: number };
+
+function placementOf(slots: readonly Slot[], title: string, at: number): Placement {
+  const fixed = fixedIndexOf(slots, title);
+  if (fixed !== -1 && fixed <= at) return { kind: "behind", index: fixed };
+  const open = openIndexFrom(slots, at);
+  const index = fixed !== -1 ? fixed : open.index;
+  const slot = slots[index];
+  if (slot === undefined) return { kind: "unplaced" };
+  return { kind: "placed", index, slot, at: fixed !== -1 || open.advances ? index : at };
+}
+
+function placedProblems(slot: Slot, { heading, subsections }: Section, level: number): Violation[] {
+  const problem = slot.type === "open" ? ruleProblem(slot.rule, heading.title) : undefined;
+  return [
+    ...(problem === undefined ? [] : [{ line: heading.line, message: `${marked(level, heading.title)} ${problem}` }]),
+    ...(slot.subsections === undefined ? [] : matchSections(subsections, slot.subsections, level + 1, heading.line)),
+  ];
+}
+
 export function matchSections(sections: readonly Section[], slots: readonly Slot[], level: number, parentLine: number): Violation[] {
   const order = `the template's order is ${slots.map(slotLabel).join(", ")}`;
   const violations: Violation[] = [];
   const found = slots.map(() => false);
   let at = -1;
-  for (const { heading, subsections } of sections) {
+  for (const section of sections) {
+    const { heading } = section;
     const named = marked(level, heading.title);
-    const fixed = fixedIndexOf(slots, heading.title);
-    if (fixed !== -1 && fixed <= at) {
-      found[fixed] = true;
-      const problem = fixed === at ? "appears twice" : `is out of order, as ${order}`;
-      violations.push({ line: heading.line, message: `${named} ${problem}` });
+    const placement = placementOf(slots, heading.title, at);
+    if (placement.kind === "unplaced") {
+      violations.push({ line: heading.line, message: `${named} is not a section the template has there, as ${order}` });
       continue;
     }
-    const open = openIndexFrom(slots, at);
-    const index = fixed !== -1 ? fixed : open.index;
-    const slot = slots[index];
-    if (slot === undefined) {
-      violations.push({ line: heading.line, message: `${named} is not a section the template has there, as ${order}` });
+    found[placement.index] = true;
+    if (placement.kind === "behind") {
+      const problem = placement.index === at ? "appears twice" : `is out of order, as ${order}`;
+      violations.push({ line: heading.line, message: `${named} ${problem}` });
       continue;
     }
-    if (fixed !== -1 || open.advances) at = index;
-    found[index] = true;
-    const problem = slot.type === "open" ? ruleProblem(slot.rule, heading.title) : undefined;
-    if (problem !== undefined) violations.push({ line: heading.line, message: `${named} ${problem}` });
-    if (slot.subsections !== undefined) violations.push(...matchSections(subsections, slot.subsections, level + 1, heading.line));
+    at = placement.at;
+    violations.push(...placedProblems(placement.slot, section, level));
   }
   slots.forEach((slot, index) => {
     if (slot.presence.required && found[index] !== true) violations.push({ line: parentLine, message: missing(slot, level) });