@avi2dg/checks 0.17.0 → 0.19.0

package/quality.schema.json

@@ -48,7 +48,8 @@
               "checks-quality",
               "checks-size-budget",
               "checks-repetition",
-              "checks-feature-owners"
+              "checks-feature-owners",
+              "checks-quarantine-clock"
             ]
           },
           "allOf": [
@@ -76,6 +77,11 @@
               "contains": {
                 "const": "checks-docs"
               }
+            },
+            {
+              "contains": {
+                "const": "checks-quarantine-clock"
+              }
             }
           ]
         }
@@ -114,6 +120,12 @@
           },
           "description": "The source the repository ships, as against tests and tooling"
         },
+        "libraries": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Library"
+          }
+        },
         "effect": {
           "type": "object",
           "properties": {
@@ -237,12 +249,12 @@
             "type": "array",
             "prefixItems": [
               {
-                "$ref": "#/$defs/FilePath"
+                "$ref": "#/$defs/FilePath_1"
               }
             ],
             "minItems": 1,
             "items": {
-              "$ref": "#/$defs/FilePath"
+              "$ref": "#/$defs/FilePath_1"
             },
             "description": "The files under root that code outside it imports the feature through"
           },
@@ -417,12 +429,52 @@
       "pattern": "^(?!\\.\\.?(?:\\/|$))(?:\\*\\*|(?:[\\w.@+-]|\\*(?!\\*))+)(?:\\/(?!\\.\\.?(?:\\/|$))(?:\\*\\*|(?:[\\w.@+-]|\\*(?!\\*))+))*\\/(?:[\\w.@+-]|\\*(?!\\*))*\\.\\w+$",
       "description": "A glob from the repository root that oxlint, the Effect language service and git read alike: a directory first, * within a segment, ** as a whole one, a file name with an extension last, and no braces, ?, [ or leading ./"
     },
+    "FilePath": {
+      "type": "string",
+      "pattern": "^(?:(?!\\.\\.?(?:\\/|$))[\\w.@+-]+\\/)*[\\w.@+-]*\\.\\w+$",
+      "description": "The manifest inside the clone holding the version; package.json when absent"
+    },
+    "Library": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+          "description": "The link checks-vendor manages under repos/"
+        },
+        "package": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The npm package whose installed version picks the tag"
+        },
+        "repository": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The git remote checks-vendor clones the tag from"
+        },
+        "tag": {
+          "type": "string",
+          "pattern": "\\{version\\}",
+          "description": "The tag template, with {version} for the installed version"
+        },
+        "path": {
+          "$ref": "#/$defs/FilePath"
+        }
+      },
+      "required": [
+        "name",
+        "package",
+        "repository",
+        "tag"
+      ],
+      "additionalProperties": false
+    },
     "DirectoryPath": {
       "type": "string",
       "pattern": "^(?!\\.\\.?(?:\\/|$))[\\w.@+-]+(?:\\/(?!\\.\\.?(?:\\/|$))[\\w.@+-]+)*$",
       "description": "The directory the feature owns"
     },
-    "FilePath": {
+    "FilePath_1": {
       "type": "string",
       "pattern": "^(?:(?!\\.\\.?(?:\\/|$))[\\w.@+-]+\\/)*[\\w.@+-]*\\.\\w+$"
     },

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;

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) });

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);