@avi2dg/checks 0.14.0 → 0.16.0

package/docs/gates/checks-repetition.md

@@ -0,0 +1,72 @@
+# checks-repetition
+
+`checks-repetition` is the gate that fails a change adding repeated lines to production code, and a reader looks it up when a production file repeats more lines than it did where the range starts.
+
+## What it checks
+
+It runs jscpd over the files `quality.json` declares as production:
+
+```json
+"sources": { "production": ["src/**/*.ts"] }
+```
+
+jscpd finds each block of at least 50 tokens and 5 lines that appears twice, within one file or across two.
+A repeated line is a line of a file inside such a block.
+The gate counts the repeated lines of each production file at the head and where the range starts, and fails when a file counts more at the head.
+A renamed file is compared with its count under the old path.
+A block counts only when both copies are in production files, so a test that copies production code changes no count.
+Each file whose count rose is listed with the blocks it repeats and where the other copy is.
+
+Every other file that repeats lines is listed as advisory and never fails the gate.
+The advisory list names the production files whose count did not rise, and every other tracked `.ts` or `.tsx` file that repeats a block within itself or from another such file.
+`.d.ts` files are not measured.
+Nothing is committed as a baseline, because each run measures where the range starts as well as the head.
+
+## What it reads
+
+It reads each file from the commits at the two ends of the range rather than the working tree, so an uncommitted edit neither fails nor passes a range, and a pull request's merge checkout measures what the pull request holds.
+It reads `sources.production` from `quality.json`.
+jscpd must be on `PATH`, as it is under a package script.
+
+## Arguments
+
+```sh
+checks-repetition <base-ref> <head-ref>
+checks-repetition <ref>
+```
+
+With two arguments the range starts where the head branched from the base, at their merge-base.
+With one it is that commit against its parent, or against the empty tree for a repository's first commit.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | no production file repeats more lines than where the range starts |
+| 1 | a production file repeats more lines than where the range starts |
+| 2 | `quality.json` does not decode, a ref does not resolve, or jscpd cannot run |
+
+## Sample output
+
+```
+repetition: 1 production file(s) repeat more lines than where the range starts, at 50 tokens and 5 lines:
+  src/billing/refund.ts: 11 repeated line(s), up from 0
+    src/billing/refund.ts:1-11 repeats src/billing/legacy.ts:1-11
+repetition: advisory, 4 file(s) repeat lines the hold does not fail:
+  src/billing/ledger.ts: 11 repeated line(s)
+  src/billing/legacy.ts: 21 repeated line(s)
+  tests/one.test.ts: 11 repeated line(s)
+  tests/two.test.ts: 11 repeated line(s)
+```
+
+## Opting out
+
+A repository that declares no `sources.production` passes.
+`checks-quality` refuses a `sources.production` glob that matches no file.
+A repository that tracks no `.ts` or `.tsx` file leaves it out of `gates.lint`, as [Gate selection](checks-lint.md#gate-selection) says.
+
+## Related topics
+
+- [The quality file](../configs/quality-file.md)
+- [checks-size-budget](checks-size-budget.md)
+- [checks-lint](checks-lint.md)

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

@@ -1,26 +1,66 @@
 # checks-size-budget
 
-`checks-size-budget` is the gate that holds production files to the line budget `quality.json` declares, and a reader looks it up when a file or a function runs over it.
+`checks-size-budget` is the gate that holds production and test files to the size budget `quality.json` declares, and a reader looks it up when a file or a function runs over it.
 
 ## What it checks
 
-It holds production files to the line budget `quality.json` declares, and lists every other file over it without failing:
+It holds production and test files to the size budget, and lists every other file over it without failing:
 
 ```json
 "sources": { "production": ["src/**/*.ts"] },
-"size": { "fileLines": 400, "functionLines": 100, "applies": "changed" }
+"size": { "applies": "ratchet" }
 ```
 
-It runs oxlint with a configuration of two rules and nothing else, `max-lines` at `fileLines` and `max-lines-per-function` at `functionLines`, both counting blank and comment lines.
-With `applies` set to `changed` it holds the files under `sources.production` that the range adds or changes, a rename that edits the file included.
-With `all` it holds every file under `sources.production`.
+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.
+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 -->
+
+| Key | Limits | oxlint rule | Production | Tests |
+| --- | --- | --- | --- | --- |
+| `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 |
+| `depth` | The deepest a block may nest inside a function | `max-depth` | 4 | 4 |
+
+<!-- end generated size-limits -->
+
+`size.production` and `size.tests` state only a limit that differs from the kit's:
+
+```json
+"size": {
+  "applies": "ratchet",
+  "production": { "complexity": 12 },
+  "tests": { "fileLines": 800 }
+}
+```
+
+`applies` decides which files the gate holds and what fails them:
+
+- `ratchet` holds each production and test file the range adds or changes, a rename that edits the file included.
+  For each file and each rule, it sums how far every site runs over its limit, and fails when that sum is higher at the head than at the base of the range.
+  A file the range adds starts from zero, so it has to keep within the budget.
+  A file already over the budget passes while its overrun does not grow, and an edit that shrinks the overrun passes.
+  An edited rename is compared with the file it was renamed from.
+  Nothing is committed as a baseline, because the base of the range holds it.
+- `all` holds every production and test file, and fails on any overrun in them.
+
+`applies` is `ratchet` when `size` leaves it out.
 A file the range deletes or only renames is not held.
-Every other tracked `.ts` or `.tsx` file over the budget, tests and unchanged production files alike, is listed as advisory and never fails the gate.
+Every other tracked `.ts` or `.tsx` file over the budget, tooling and unchanged files alike, is listed as advisory and never fails the gate.
+Under `ratchet` the advisory list also names each site in a held file whose overrun did not grow.
 `.d.ts` files are not measured.
 
+`quality.json` refuses `applies: "changed"`, which `ratchet` replaces.
+It refuses a limit set directly under `size`, since each limit goes in `size.production` or `size.tests`.
+
 ## What it reads
 
 It reads each file from the head commit rather than the working tree, so an uncommitted edit neither fails nor passes a range, and a pull request's merge checkout measures what the pull request holds.
+Under `ratchet` it also reads each held file from the base of the range, under the path the file has at the head, so a file keeps the same budget at both ends.
 It reads `sources.production` and `size` from `quality.json`.
 oxlint must be on `PATH`, as it is under a package script.
 
@@ -38,25 +78,28 @@ With one it is that commit against its parent, or against the empty tree for a r
 
 | Code | When |
 | --- | --- |
-| 0 | every file it holds keeps within the budget |
-| 1 | a file it holds runs over the budget |
+| 0 | every file it holds keeps within the budget, or under `ratchet` no file's overrun grows |
+| 1 | a file it holds runs over the budget, or under `ratchet` a file's overrun grows |
 | 2 | `quality.json` does not decode, a ref does not resolve, or oxlint cannot run |
 
 ## Sample output
 
 ```
-size-budget: 1 overrun(s) of 400 lines per file and 100 per function in the production files the range adds or changes:
-  src/billing/ledger.ts:12: The function `settle` has too many lines (131). Maximum allowed is 100.
+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.
 size-budget: advisory, 1 overrun(s) where the budget does not hold yet:
-  tests/e2e/billing.test.ts: File has too many lines (512).
+  tests/e2e/billing.test.ts: File has too many lines (612). Maximum allowed is 600.
 ```
 
 ## Opting out
 
 A repository that declares no `size` passes.
-`quality.json` refuses a `size` without `sources.production`, which would hold nothing, and with `size` declared `checks-quality` refuses a `sources.production` glob that matches no file.
+`quality.json` refuses a `size` without `sources.production`, and `checks-quality` refuses a `sources.production` glob that matches no file.
 A repository that tracks no `.ts` or `.tsx` file leaves it out of `gates.lint`, as [Gate selection](checks-lint.md#gate-selection) says.
-Moving `applies` from `changed` to `all` tightens the budget to every production file, once the advisory list names none.
+Moving `applies` from `ratchet` to `all` tightens the budget to every production and test file, once the advisory list names none.
 
 ## Related topics
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -33,6 +33,7 @@
     "scripts/mutation-compare.ts",
     "scripts/ci-wiring.ts",
     "scripts/comment-matchers.ts",
+    "scripts/prose-matchers.ts",
     "scripts/comments.ts",
     "scripts/comment-gate.ts",
     "scripts/suppressions-ratchet.ts",
@@ -40,10 +41,14 @@
     "scripts/quality-file.ts",
     "scripts/quality.ts",
     "scripts/size-budget.ts",
+    "scripts/size-rules.ts",
+    "scripts/repetition.ts",
     "scripts/feature-owners.ts",
     "scripts/docs.ts",
     "scripts/doc-outline.ts",
     "scripts/doc-rules.ts",
+    "scripts/doc-references.ts",
+    "scripts/doc-snapshot.ts",
     "scripts/doc-templates.ts",
     "templates/",
     "presets/effect.oxlint.json",
@@ -68,6 +73,7 @@
     "./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/prose-matchers.ts": "./scripts/prose-matchers.ts",
     "./scripts/comments.ts": "./scripts/comments.ts",
     "./scripts/comment-gate.ts": "./scripts/comment-gate.ts",
     "./scripts/suppressions-ratchet.ts": "./scripts/suppressions-ratchet.ts",
@@ -75,6 +81,7 @@
     "./scripts/quality-file.ts": "./scripts/quality-file.ts",
     "./scripts/quality.ts": "./scripts/quality.ts",
     "./scripts/size-budget.ts": "./scripts/size-budget.ts",
+    "./scripts/repetition.ts": "./scripts/repetition.ts",
     "./scripts/feature-owners.ts": "./scripts/feature-owners.ts",
     "./scripts/docs.ts": "./scripts/docs.ts",
     "./templates/readme.md": "./templates/readme.md",
@@ -109,6 +116,7 @@
     "checks-backtest": "scripts/backtest.ts",
     "checks-quality": "scripts/quality.ts",
     "checks-size-budget": "scripts/size-budget.ts",
+    "checks-repetition": "scripts/repetition.ts",
     "checks-feature-owners": "scripts/feature-owners.ts",
     "checks-docs": "scripts/docs.ts"
   },
@@ -123,6 +131,7 @@
     "dependency-cruiser": "18.4.0",
     "@effect/tsgo": "0.45.0",
     "effect": "4.0.0-rc.115",
+    "jscpd": "5.3.2",
     "oxlint": "1.83.0",
     "oxlint-tsgolint": "7.0.2002"
   },
@@ -134,6 +143,7 @@
     "ajv": "8.20.0",
     "dependency-cruiser": "18.4.0",
     "effect": "4.0.0-rc.115",
+    "jscpd": "5.3.2",
     "oxlint": "1.83.0",
     "oxlint-tsgolint": "7.0.2002",
     "typescript": "7.0.2"

package/quality.schema.json

@@ -47,6 +47,7 @@
               "checks-docs",
               "checks-quality",
               "checks-size-budget",
+              "checks-repetition",
               "checks-feature-owners"
             ]
           },
@@ -148,32 +149,76 @@
     "size": {
       "type": "object",
       "properties": {
-        "fileLines": {
-          "type": "integer",
-          "exclusiveMinimum": 0,
-          "description": "The most lines a file may hold, blank and comment lines counted"
-        },
-        "functionLines": {
-          "type": "integer",
-          "exclusiveMinimum": 0,
-          "description": "The most lines a function may span, blank and comment lines counted"
-        },
         "applies": {
           "type": "string",
           "enum": [
-            "changed",
+            "ratchet",
             "all"
           ],
-          "description": "Which production files the budget holds: changed, the ones a range adds or changes; all, every one. The rest are reported as advisory"
+          "description": "Which production and test files the budget holds: ratchet, the ones a range adds or changes, to no more overrun per rule than at the range's base; all, every one. ratchet when absent. The rest are listed as advisory"
+        },
+        "production": {
+          "type": "object",
+          "properties": {
+            "fileLines": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "description": "The most lines a file may hold, blank and comment lines counted; 400 when absent"
+            },
+            "functionLines": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "description": "The most lines a function may span, blank and comment lines counted; 100 when absent"
+            },
+            "statements": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "description": "The most statements a function may hold; 30 when absent"
+            },
+            "complexity": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "description": "The highest cyclomatic complexity a function may reach, a switch counted once; 15 when absent"
+            },
+            "depth": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "description": "The deepest a block may nest inside a function; 4 when absent"
+            }
+          },
+          "additionalProperties": false,
+          "description": "The budget of the files under sources.production, and of the files listed as advisory outside tests/"
+        },
+        "tests": {
+          "type": "object",
+          "properties": {
+            "fileLines": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "description": "The most lines a file may hold, blank and comment lines counted; 600 when absent"
+            },
+            "statements": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "description": "The most statements a function may hold; 50 when absent"
+            },
+            "complexity": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "description": "The highest cyclomatic complexity a function may reach, a switch counted once; 15 when absent"
+            },
+            "depth": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "description": "The deepest a block may nest inside a function; 4 when absent"
+            }
+          },
+          "additionalProperties": false,
+          "description": "The budget of the files under tests/, which sets no limit on a function's lines"
         }
       },
-      "required": [
-        "fileLines",
-        "functionLines",
-        "applies"
-      ],
       "additionalProperties": false,
-      "description": "The line budget oxlint holds production files to, read by checks-size-budget"
+      "description": "The size budget oxlint holds production and test files to, read by checks-size-budget"
     },
     "features": {
       "type": "array",
@@ -285,6 +330,13 @@
           },
           "additionalProperties": false,
           "description": "The Diátaxis mode of each page, whose template checks-docs holds the page to; a page under docs/ needs one"
+        },
+        "forConsumers": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/DocGlob"
+          },
+          "description": "The living docs that speak to a repository installing this one, whose bun run commands checks-docs does not hold to this package.json"
         }
       },
       "additionalProperties": false,
@@ -382,6 +434,11 @@
     "RuleName": {
       "type": "string",
       "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "DocGlob": {
+      "type": "string",
+      "pattern": "^(?:(?!\\.\\.?(?:\\/|$))(?:\\*\\*|(?:[\\w.@+-]|\\*(?!\\*))+)\\/)*(?:[\\w.@+-]|\\*(?!\\*))*\\.\\w+$",
+      "description": "A glob from the repository root that checks-docs reads: * within a segment, ** as a whole one, a file name with an extension last"
     }
   }
 }

package/scripts/comment-gate.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, Option } from "effect";
 import { refused, syntaxOf } from "./comments.ts";
-import { git, parentOrEmptyTree } from "./git.ts";
+import { changedLines, git, parentOrEmptyTree } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
 
 export type GateResult = {
@@ -16,64 +16,21 @@ function readable(path: string): boolean {
   return syntaxOf(path) !== undefined;
 }
 
-function newPathOf(line: string): string | undefined {
-  const path = line.startsWith("+++ b/") ? line.slice("+++ b/".length) : line.slice("+++ ".length);
-  return path === "/dev/null" ? undefined : path;
-}
-
-const HUNK = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
-
-export function parseAddedLines(diff: string): Map<string, Set<number>> {
-  const added = new Map<string, Set<number>>();
-  let path: string | undefined;
-  let line = 0;
-  let inHunk = false;
-  for (const row of diff.split("\n")) {
-    if (row.startsWith("+++ ")) {
-      path = newPathOf(row);
-      inHunk = false;
-      continue;
-    }
-    const hunk = HUNK.exec(row);
-    if (hunk !== null) {
-      line = Number(hunk[1]);
-      inHunk = true;
-      continue;
-    }
-    if (!inHunk || path === undefined) continue;
-    if (row.startsWith("+")) {
-      let lines = added.get(path);
-      if (lines === undefined) {
-        lines = new Set<number>();
-        added.set(path, lines);
-      }
-      lines.add(line);
-      line += 1;
-    } else if (row.startsWith("-")) {
-      continue;
-    } else {
-      line += 1;
-    }
-  }
-  return added;
-}
-
 const show = (rev: string, path: string, root: string) =>
   git(["show", `${rev}:${path}`], root).pipe(Effect.option);
 
 export const runRange = Effect.fn("runRange")(function* (root: string, base: string, head: string) {
-  const diff = yield* git(["-c", "core.quotePath=false", "diff", "-U0", "--no-color", "--no-prefix", base, head], root);
-  const added = parseAddedLines(diff);
+  const added = yield* changedLines(base, head, [], root);
   const violations: string[] = [];
-  let addedLines = 0;
+  let lineCount = 0;
   for (const [path, lines] of added) {
-    addedLines += lines.size;
+    lineCount += lines.size;
     if (!readable(path)) continue;
     const source = yield* show(head, path, root);
     if (Option.isNone(source)) continue;
     violations.push(...(yield* refused(path, source.value, lines)));
   }
-  return { files: added.size, addedLines, violations };
+  return { files: added.size, addedLines: lineCount, violations };
 });
 
 export function report({ files, addedLines, violations }: GateResult): string {

package/scripts/doc-references.ts

@@ -0,0 +1,190 @@
+import { scanMarkdown, type MarkdownLine } from "./prose-matchers.ts";
+
+export type ReferenceKind = "path" | "link" | "command";
+
+export type Unresolved = {
+  readonly kind: ReferenceKind;
+  readonly line: number;
+  readonly named: string;
+  readonly message: string;
+  readonly missing:
+    | { readonly type: "file"; readonly path: string }
+    | { readonly type: "script"; readonly name: string; readonly packageDirectory: string }
+    | { readonly type: "anchor" };
+};
+
+export type Snapshot = {
+  readonly files: ReadonlySet<string>;
+  readonly directories: ReadonlySet<string>;
+  readonly roots: ReadonlySet<string>;
+  readonly anchors: ReadonlyMap<string, ReadonlySet<string>>;
+  readonly scripts: ReadonlyMap<string, ReadonlySet<string>>;
+};
+
+export const PACKAGE_MANIFEST = "package.json";
+
+export function rootsOf(files: readonly string[]): readonly string[] {
+  return files.flatMap((file) => (file.includes("/") ? [file.slice(0, file.indexOf("/"))] : []));
+}
+
+export function snapshotOf(
+  files: readonly string[],
+  anchors: ReadonlyMap<string, ReadonlySet<string>>,
+  scripts: ReadonlyMap<string, ReadonlySet<string>>,
+  alsoRoots: readonly string[] = [],
+): Snapshot {
+  const directories = new Set<string>([""]);
+  for (const file of files) for (let at = file.indexOf("/"); at >= 0; at = file.indexOf("/", at + 1)) directories.add(file.slice(0, at));
+  return { files: new Set(files), directories, roots: new Set([...rootsOf(files), ...alsoRoots]), anchors, scripts };
+}
+
+function directoryOf(path: string): string {
+  return path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+}
+
+function normalize(path: string): string | undefined {
+  const parts: string[] = [];
+  for (const part of path.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part !== "..") parts.push(part);
+    else if (parts.pop() === undefined) return undefined;
+  }
+  return parts.join("/");
+}
+
+function within(directory: string, path: string): string | undefined {
+  return normalize(directory === "" ? path : `${directory}/${path}`);
+}
+
+function exists(snapshot: Snapshot, path: string): boolean {
+  return snapshot.files.has(path) || snapshot.directories.has(path);
+}
+
+const PARENT = /^\.\.\//;
+const PATH = /^((?:\.{1,2}\/)*(?:[\w.@-]+\/)+[\w.@-]+\.(?:ts|tsx|mts|cts|js|jsx|cjs|mjs|md|mdx|json|jsonc|sh|bash|zsh|toml|nix|lua|ya?ml|txt|py|rs|go|css|html))(?::\d+(?::\d+)?)?$/;
+
+function unresolvedPath(doc: string, line: number, span: string, snapshot: Snapshot): Unresolved | undefined {
+  const named = PATH.exec(span)?.[1];
+  if (named === undefined) return undefined;
+  const fromDoc = within(directoryOf(doc), named);
+  const fromRoot = PARENT.test(named) ? undefined : normalize(named);
+  if ([fromRoot, fromDoc].some((path) => path !== undefined && exists(snapshot, path))) return undefined;
+  const checked = fromRoot ?? fromDoc;
+  // A path whose top directory this repository lacks names a file in another one, such as a consumer's.
+  if (checked === undefined || (fromRoot !== undefined && !snapshot.roots.has(fromRoot.split("/")[0] ?? ""))) return undefined;
+  return { kind: "path", line, named, message: `names \`${named}\`, which is not in the repository`, missing: { type: "file", path: checked } };
+}
+
+const SCHEME = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+const ASCII_ESCAPE = /%([0-7][0-9a-f])/gi;
+
+function unresolvedLink(doc: string, line: number, target: string, snapshot: Snapshot): Unresolved | undefined {
+  if (target === "" || SCHEME.test(target)) return undefined;
+  const hash = target.indexOf("#");
+  const written = (hash < 0 ? target : target.slice(0, hash)).split("?", 1)[0] ?? "";
+  const decoded = written.replace(ASCII_ESCAPE, (_, code: string) => String.fromCharCode(Number.parseInt(code, 16)));
+  const path = decoded === "" ? doc : decoded.startsWith("/") ? normalize(decoded) : within(directoryOf(doc), decoded);
+  if (path === undefined) return undefined;
+  const named = target;
+  if (!exists(snapshot, path)) {
+    return { kind: "link", line, named, message: `links to \`${named}\`, which is not in the repository`, missing: { type: "file", path } };
+  }
+  const anchor = hash < 0 ? "" : target.slice(hash + 1);
+  const anchors = snapshot.anchors.get(path);
+  if (anchor === "" || anchors === undefined || anchors.has(anchor) || anchors.has(anchor.toLowerCase())) return undefined;
+  return { kind: "link", line, named, message: `links to \`${named}\`, and \`${path}\` has no heading with that anchor`, missing: { type: "anchor" } };
+}
+
+const RUN = /\bbun run\s+([^\s`'"]+)/g;
+const RUNS_A_FILE = /\/|\.[cm]?[jt]sx?$/;
+const NOT_A_NAME = /^[-$<{]/;
+
+function packageOf(doc: string, snapshot: Snapshot): string | undefined {
+  for (let directory: string | undefined = directoryOf(doc); directory !== undefined; directory = directory === "" ? undefined : directoryOf(directory)) {
+    if (snapshot.files.has(directory === "" ? PACKAGE_MANIFEST : `${directory}/${PACKAGE_MANIFEST}`)) return directory;
+  }
+  return undefined;
+}
+
+function unresolvedCommand(doc: string, line: number, name: string, snapshot: Snapshot): Unresolved | undefined {
+  const packageDirectory = packageOf(doc, snapshot);
+  if (packageDirectory === undefined || NOT_A_NAME.test(name)) return undefined;
+  const named = `bun run ${name}`;
+  if (RUNS_A_FILE.test(name)) {
+    const path = within(packageDirectory, name);
+    if (path === undefined || exists(snapshot, path)) return undefined;
+    return { kind: "command", line, named, message: `runs \`${named}\`, and \`${path}\` is not in the repository`, missing: { type: "file", path } };
+  }
+  if (snapshot.scripts.get(packageDirectory)?.has(name) === true) return undefined;
+  const manifest = packageDirectory === "" ? PACKAGE_MANIFEST : `${packageDirectory}/${PACKAGE_MANIFEST}`;
+  return {
+    kind: "command",
+    line,
+    named,
+    message: `runs \`${named}\`, and \`${name}\` is not a script in \`${manifest}\``,
+    missing: { type: "script", name, packageDirectory },
+  };
+}
+
+function commandsOn({ kind, raw, code }: MarkdownLine): readonly string[] {
+  const texts = kind === "code" ? [raw] : code;
+  return texts.flatMap((text) => [...text.matchAll(RUN)].map(([, name = ""]) => name.replace(/[),.;:]+$/, "")));
+}
+
+export type Judging = { readonly commands: boolean };
+
+export function unresolvedIn(doc: string, text: string, snapshot: Snapshot, { commands }: Judging): readonly Unresolved[] {
+  return scanMarkdown(text).flatMap((markdown) => {
+    const { line } = markdown;
+    const prose = markdown.kind === "code" || markdown.kind === "front-matter" ? [] : markdown.code.map((span) => unresolvedPath(doc, line, span, snapshot));
+    const links = markdown.links.map((target) => unresolvedLink(doc, line, target, snapshot));
+    const runs = commands && markdown.kind !== "front-matter" ? commandsOn(markdown).map((name) => unresolvedCommand(doc, line, name, snapshot)) : [];
+    return [...prose, ...links, ...runs].filter((found) => found !== undefined);
+  });
+}
+
+export function anchoredTargets(doc: string, text: string): readonly string[] {
+  return scanMarkdown(text).flatMap(({ links }) =>
+    links.flatMap((target) => {
+      const hash = target.indexOf("#");
+      if (hash < 0 || SCHEME.test(target)) return [];
+      const written = target.slice(0, hash);
+      const path = written === "" ? doc : written.startsWith("/") ? normalize(written) : within(directoryOf(doc), written);
+      return path?.endsWith(".md") === true ? [path] : [];
+    }),
+  );
+}
+
+export function packagesOf(docs: readonly string[], snapshot: Snapshot): readonly string[] {
+  return [...new Set(docs.flatMap((doc) => packageOf(doc, snapshot) ?? []))];
+}
+
+const EXPLICIT_ANCHOR = /<a\s[^>]*\b(?:id|name)="([^"]+)"/g;
+const HEADING_MARKERS = /^\s{0,3}#{1,6}\s*|\s+#+\s*$/g;
+
+function headingText(raw: string): string {
+  return raw
+    .replace(HEADING_MARKERS, "")
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/<[^>]+>/g, "")
+    .replace(/[`*]/g, "")
+    .trim();
+}
+
+export function anchorsOf(text: string): ReadonlySet<string> {
+  const anchors = new Set<string>();
+  const seen = new Map<string, number>();
+  for (const { kind, raw } of scanMarkdown(text)) {
+    if (kind === "code" || kind === "front-matter") continue;
+    for (const [, id = ""] of raw.matchAll(EXPLICIT_ANCHOR)) anchors.add(id);
+    if (kind !== "heading") continue;
+    const slug = headingText(raw)
+      .toLowerCase()
+      .replace(/[^\p{L}\p{M}\p{N}\p{Pc} -]/gu, "")
+      .replaceAll(" ", "-");
+    const count = seen.get(slug) ?? 0;
+    anchors.add(count === 0 ? slug : `${slug}-${count}`);
+    seen.set(slug, count + 1);
+  }
+  return anchors;
+}

package/scripts/doc-rules.ts

@@ -11,6 +11,7 @@ import {
   VERSION,
 } from "./doc-outline.ts";
 import { ADR_STATUSES, TEMPLATES, templateFile, type Kind, type Title } from "./doc-templates.ts";
+import { ADR_DIRECTORY, DOCS_DIRECTORY } from "./prose-matchers.ts";
 import { MODES, type Docs, type Mode } from "./quality-file.ts";
 
 export type Placement =
@@ -24,10 +25,9 @@ export type Doc = {
   readonly text: string;
 };
 
-export const ADR_DIRECTORY = "docs/adr/";
+export { ADR_DIRECTORY };
 // A generated index takes its shape from its generator.
 export const ADR_INDEX = `${ADR_DIRECTORY}README.md`;
-const DOCS_DIRECTORY = "docs/";
 
 export const ROOT_FILES: ReadonlyMap<string, Kind> = new Map<string, Kind>([
   ["README.md", "readme"],