@cosyte/script-utils 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.9
+
+### Patch Changes
+
+- 65208bf: The docs-content check (`cosyte-docs-content`, `@cosyte/script-utils/docs-content`) now resolves every link a page makes into the generated reference, `./api/<page>.md#<anchor>`: the page must exist under `docs-content/api/`, and the anchor must be one a heading on it gets on docs.cosyte.com (lower case, every character but a letter, a mark, a digit, an underscore, a space or a hyphen dropped, each space a hyphen, a repeat numbered `-1`, `-2`). A link that does not resolve is a finding under the new rule `reference-link`, with its page and line. It also requires the "Current numbers" section of both quality pages to hold only the placeholder, `NUMBERS_PLACEHOLDER`, until the release fills in the numbers: a table, a sub-heading or a sentence added beside it is a finding. `readDocsContent` now returns the generated pages as `reference`, and `headingAnchors(text)` is exported.
+- 57847cb: A new subpath, `@cosyte/script-utils/docs-content`, and its bin, `cosyte-docs-content` (also `script-utils docs-content`): the structure check for a library's `docs-content/` folder, against the docs-content standard (decision record 0006 in cosyte/config). It checks the sidebar's shape (`intro`, then Installation, Quickstart, Tutorials, How-to guides, Explanation, Reference and Troubleshooting in that order, then the pages `testing-and-quality` and `performance`), that every page is listed once and every listed id is a page, the required pages, each page's front matter (`id` equal to the file name, `title`, `sidebar_label`, a `description` of at most 160 characters, no `sidebar_position`), page names, and the "Current numbers" section on both quality pages. Exit 0 clean, 1 a finding, 2 the check could not read its input. Nothing else in the package changes.
+- cc43161: The PHI scan's command-line form (`cosyte-phi-scan`, `script-utils phi-scan` and `node phi-scan.js`) takes `--allow-list <path>`, the allow list to use instead of `scripts/phi-allow-list.txt`. It goes with `--staged`, with paths, or alone; a relative path is read from the working directory, and the repository's own list is not read. A tool scanning a repository that keeps no allow list can pass an empty file and get a scan with no exceptions, where the scan used to refuse at exit 2 for the missing list. A path the option names that does not exist, or that cannot be read (a directory, no read permission), is refused at exit 2 before anything is scanned, with a line saying which. So are the option with no path, an empty path, and the option given twice. Without the option nothing changes: a repository with no `scripts/phi-allow-list.txt` still refuses at exit 2. `runPhiScan` is unchanged; its `allowListPath` setting already did this for a caller script.
+- 5a0470a: Adds the coverage and mutation ratchet: the `cosyte-ratchet` bin (also `script-utils ratchet`) and the `./ratchet` entry point. `cosyte-ratchet check` reads a floor file, `quality-floor.json`, holding each package's coverage (lines, branches, functions, statements) and mutation score, compares what was measured, prints each metric with its floor and its gap to 100, and exits 1 on any drop. With `--base <ref>` it also requires every changed line coverage counts to have run and every mutant in changed code to be killed, unless an inline comment names a reason (`/* v8 ignore next -- reason */`, `// Stryker disable next-line all: reason`), and lists each such exception in changed code; an exception with no reason fails. With `--base` it also reads the floor file as it was at the merge base and exits 1 when the change lowered or removed any floor in it; raising or adding a floor passes. `cosyte-ratchet raise` moves floors up to what was measured and never lowers one. Exit 2 means an input could not be read. Also adds `./changes`, `readChanges({ base })`: the lines a change touched against a base ref, read from git, which the ratchet and `@cosyte/vitest-config/mutate` share, and `readFileAtCommit({ commit, path, cwd })`, a file as it was at a commit. The base ref and the path reach git on standard input, never as arguments.
+
+## 0.1.8
+
+### Patch Changes
+
+- 7dee328: The catalog carries `@cosyte/cli`'s description from its latest npm release, which no longer ends
+  with the sentence on value-free diagnostics and the exit-code contract.
+
 ## 0.1.7
 
 ### Patch Changes

package/README.md

@@ -200,6 +200,9 @@ CATALOG.engine.displayName; // => "Pathways"
 | `@cosyte/script-utils/claude-card`   | `runClaudeCardGate(options)` and `checkClaudeCard(text)`, the CLAUDE.md card checker         |
 | `@cosyte/script-utils/catalog`       | `CATALOG`, `catalogEntry(name)` and `runCatalogCheck(options)`, the catalog of our libraries |
 | `@cosyte/script-utils/agent-notes`   | deprecated (D62): `runAgentNotesCheck(options)` and `checkAgentNotes(input)`                 |
+| `@cosyte/script-utils/ratchet`       | `runRatchet(options)` and its parts, the coverage and mutation ratchet                       |
+| `@cosyte/script-utils/changes`       | `readChanges({ base })`, the lines a change touched against a base ref, read from git        |
+| `@cosyte/script-utils/docs-content`  | `runDocsContentCheck(options)` and `checkDocsContent(input)`, the docs-content check         |
 
 They are separate subpaths because they are separately adoptable: a repo can take the entry-point
 guard without taking a position on PHI scanning, a repo can take the internal-reference gate without
@@ -226,9 +229,14 @@ Each shared gate runs from a repository's package script with no file of its own
   whole repository as the scan root; `--staged` reading everything but Markdown; the allow-list at
   `scripts/phi-allow-list.txt` and the override log at `phi-scan-overrides.md`. Each line of
   `scripts/phi-scan.exclude` is one literal tracked path (`#` lines are comments); a directory, a
-  pattern, a repeat or a path git does not track is refused at exit 2. It carries the
-  cross-cutting floor only, so a repository whose standard needs field-level detectors keeps a
-  caller passing `detect` until the per-standard detectors ship here.
+  pattern, a repeat or a path git does not track is refused at exit 2. `--allow-list <path>`,
+  with `--staged`, with paths or alone, uses that allow list instead of
+  `scripts/phi-allow-list.txt` (a relative path is read from the working directory, and the
+  repository's own list is not read). A tool scanning a repository that keeps no allow list passes
+  an empty file, and the floor then has no exceptions; without the option that repository refuses
+  at exit 2. A path the option names that does not exist or cannot be read is refused at exit 2. It
+  carries the cross-cutting floor only, so a repository whose standard needs field-level detectors
+  keeps a caller passing `detect` until the per-standard detectors ship here.
 - **Internal refs** reads its axes from `scripts/internal-refs.json` (keys starting with `$` are
   notes), with exit codes 0 clean, 1 hits, 2 the gate could not run. The file may not set
   `exitCodes`, `repoRoot` or `write`, which the command-line form owns.
@@ -254,6 +262,8 @@ npx -y -p @cosyte/script-utils@0.1 cosyte-readme   # or one gate's own bin
 | `cosyte-claude-card`   | `claude-card`          | the CLAUDE.md card checker                        |
 | `cosyte-agent-notes`   | `agent-notes`          | deprecated (D62): the retired agent-notes checker |
 | `cosyte-catalog`       | `catalog`              | the catalog check                                 |
+| `cosyte-ratchet`       | `ratchet`              | the coverage and mutation ratchet                 |
+| `cosyte-docs-content`  | `docs-content`         | the docs-content structure check                  |
 
 Each runs over the working directory, takes the arguments its gate takes, exits with the gate's own
 code, and prints what it does with `--help`. `script-utils` with no command prints the list and exits 2.
@@ -384,6 +394,87 @@ release, because config's check against npm picks the change up once the library
 2 means the check could not run (no package.json, or an argument it does not accept). `--strict`
 restores the gate: 1 for a disagreement, 2 for an unlisted package.
 
+### The coverage and mutation ratchet
+
+`cosyte-ratchet` holds a repository to a floor file at its root, `quality-floor.json`: each package
+directory, relative to the file, with its coverage (lines, branches, functions, statements) and its
+mutation score. A floor only rises: `raise` never lowers one, and `check --base` fails a change
+that lowers or removes one.
+
+```sh
+cosyte-ratchet check --skip mutation                     # coverage against its floor, every run
+cosyte-ratchet check --skip mutation --base origin/main  # and a pull request's changed lines
+cosyte-ratchet check --skip coverage --base origin/main  # the mutants in a pull request's changed code
+cosyte-ratchet raise                                     # move floors up to what was measured
+```
+
+`check` prints each metric, its floor and its gap to 100, and exits 1 on any drop. With `--base` it
+also holds the change's own code to 100: every changed line coverage counts must have run, and
+every mutant in changed code must be killed, unless an inline comment names its reason
+(`/* v8 ignore next -- reason */` for coverage, `// Stryker disable next-line all: reason` for a
+mutant). It lists every exception it finds in changed code, so the pull request can carry the list,
+and an exception with no reason fails. With `--base` it also reads the floor file as it was at the
+merge base and exits 1 when the change lowered any floor in it or removed one; raising a floor or
+adding one passes. `raise` never lowers a floor. Exit 2 means an input could not be read: the floor
+file now or at the merge base, a report a floor needs, or git.
+
+It reads Istanbul's `coverage/coverage-summary.json` and `coverage/lcov.info` (which
+`@cosyte/vitest-config` writes), and StrykerJS's `reports/mutation/mutation.json` and `changed.json`
+(which `@cosyte/vitest-config/stryker` writes), from each package directory. A changed line any package's
+suite ran counts as run.
+
+`@cosyte/script-utils/changes` is how both the ratchet and `@cosyte/vitest-config/mutate` read what a
+change touched: the diff from the merge base of the base ref and HEAD to the working tree, plus
+untracked files, as each file's changed lines. `readFileAtCommit({ commit, path, cwd })` reads a
+file as it was at a commit, which is how the ratchet reads the floor file at the merge base. A base
+ref or a path reaches git on standard input, never as an argument, so no value can become a git
+option.
+
+```ts runnable
+import { parseUnifiedDiff } from "@cosyte/script-utils/changes";
+
+const diff = ["+++ b/src/a.ts", "@@ -3 +3,2 @@"].join("\n");
+[...(parseUnifiedDiff(diff).get("src/a.ts") ?? [])]; // => [3, 4]
+```
+
+```ts runnable
+import { parseFloor, toFloor } from "@cosyte/script-utils/ratchet";
+
+toFloor(98.056); // => 98.05
+const floor = parseFloor({ packages: { ".": { coverage: { lines: 98.05 }, mutation: 81.2 } } });
+floor.packages["."].mutation; // => 81.2
+```
+
+### The docs-content check
+
+`@cosyte/script-utils/docs-content` checks a library's `docs-content/` folder, the pages
+docs.cosyte.com renders, against the docs-content standard (decision record 0006 in this
+repository). Run it from a package script:
+
+```sh
+cosyte-docs-content                # docs-content/ in the working directory
+cosyte-docs-content --dir <path>   # another repository
+```
+
+It checks the sidebar's shape (`intro`, then Installation, Quickstart, Tutorials, How-to guides,
+Explanation, Reference and Troubleshooting in that order, then `testing-and-quality` and
+`performance`), that every page is listed once and every listed id is a page, the required pages,
+each page's front matter, page names, and the "Current numbers" section on both quality pages,
+which holds only the placeholder sentence until the release fills in the numbers. It also resolves
+every link into the generated reference, `./api/<page>.md#<anchor>`: the page must exist under
+`api/`, and the anchor must be one of its headings, slugged the way docs.cosyte.com slugs them. It
+does not read any other link, check the generated pages themselves, or run a sample: the shared
+CI's link check, `cosyte-docs-reference` in `@cosyte/process` and the sample runner in
+`@cosyte/vitest-config` do those. Exit 0 clean, 1 a finding, 2 the check could not run.
+
+```ts runnable
+import { checkDocsContent } from "@cosyte/script-utils/docs-content";
+
+const found = checkDocsContent({ pages: [{ name: "intro", text: "# Intro\n" }], sidebars: null });
+found.map((f) => f.rule).includes("front-matter"); // => true
+found.map((f) => f.rule).includes("required-page"); // => true
+```
+
 ### The agent-notes checker, deprecated
 
 `@cosyte/script-utils/agent-notes` and its bin, `cosyte-agent-notes`, are deprecated. They check a
@@ -442,6 +533,11 @@ evasion per round: each of `--quiet`, `-q`, `--format json`, `-fjson`, `-qP`, `-
 Widening that set is a deliberate one-line edit in this package, reviewed here, and not something a
 caller can do. No net can be switched off.
 
+`cosyte-ratchet` takes the floor file's path, the base ref, and `--skip coverage` or
+`--skip mutation` for a run that does not make that report; a skipped metric is printed as skipped,
+never as passed. It has no way to lower a floor, and a floor file with a key it does not know is
+refused rather than read around: a misspelled metric would be a floor nobody checks.
+
 ## PHI and safety
 
 This package ships the machinery of the PHI commit-gate, so it is the one package here that reads

package/bin/cosyte-docs-content.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// cosyte-docs-content: the docs-content structure check for the repository in the working directory.
+// It forwards every argument to the check and exits with the check's own code; `--help` prints what
+// it does and exits 0, or 2 under CI.
+
+import { runDocsContentCheck } from "../docs-content.js";
+import { answerHelp } from "./help.js";
+
+const HELP = `cosyte-docs-content: check docs-content/ against the docs-content standard.
+
+  cosyte-docs-content [--dir <repository root>]
+
+It reads docs-content/ and checks the shape the standard gives it: one "docs" sidebar that opens
+with "intro", then the categories Installation, Quickstart, Tutorials, How-to guides, Explanation,
+Reference and Troubleshooting in that order (Tutorials and Reference only when a library has them),
+then the pages "testing-and-quality" and "performance". Every page is listed once, every listed id
+is a page, the required pages exist, every page opens with front matter carrying id (the file
+name), title, sidebar_label and description (at most 160 characters), page names are lower-case
+and hyphenated, and both quality pages carry a "## Current numbers" section.
+
+It does not read links (the shared CI's docs-content link check does), the generated pages under
+api/ (cosyte-docs-reference checks those), or whether a sample runs (the sample runner in
+@cosyte/vitest-config does). Exit 0 clean, 1 a finding, 2 the check could not run.
+`;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  process.exitCode = answerHelp("cosyte-docs-content", HELP);
+} else {
+  process.exitCode = runDocsContentCheck({ argv: args });
+}

package/bin/cosyte-phi-scan.js

@@ -13,10 +13,15 @@ const HELP = `cosyte-phi-scan: run the PHI commit-gate over the repository in th
   cosyte-phi-scan --staged        scan what is staged, Markdown excepted (the pre-commit route)
   cosyte-phi-scan <path>...       scan these paths
 
+  --allow-list <path>             use this allow list instead of scripts/phi-allow-list.txt;
+                                  it goes with any of the three forms above
+
 It carries the cross-cutting floor (a dashed SSN shape, an email at an undeclared domain) and
 reports a place and a rule, never the matched value. scripts/phi-allow-list.txt declares synthetic
-values, and scripts/phi-scan.exclude names literal tracked paths to leave out. Exit 0 clean, 1 hits,
-2 the scan could not account for something.
+values, and scripts/phi-scan.exclude names literal tracked paths to leave out. Without that allow
+list the scan refuses, unless --allow-list names another: an empty file there scans a repository
+that keeps no list with no exceptions. A path --allow-list names that does not exist or cannot be
+read refuses. Exit 0 clean, 1 hits, 2 the scan could not account for something.
 `;
 
 const args = process.argv.slice(2);

package/bin/cosyte-ratchet.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// cosyte-ratchet: the coverage and mutation ratchet over the repository's floor file.
+// A bin of @cosyte/script-utils, so a repository with no package.json can run it with
+// `npx -y -p @cosyte/script-utils cosyte-ratchet check`. It forwards every argument to the ratchet
+// and exits with its code; `--help` prints what it does and exits 0, or 2 under CI.
+
+import { runRatchet } from "../ratchet.js";
+import { answerHelp } from "./help.js";
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  let help = "";
+  runRatchet({
+    argv: ["--help"],
+    cwd: process.cwd(),
+    out: (text) => (help += text),
+    err: () => {},
+  });
+  process.exitCode = answerHelp("cosyte-ratchet", help);
+} else {
+  process.exitCode = runRatchet({
+    argv: args,
+    cwd: process.cwd(),
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+  });
+}

package/bin/script-utils.js

@@ -21,6 +21,8 @@ const COMMANDS = {
   "claude-card": ["cosyte-claude-card", "the CLAUDE.md card checker"],
   "agent-notes": ["cosyte-agent-notes", "the agent-notes checker, deprecated by D62"],
   catalog: ["cosyte-catalog", "the catalog check, for the library here"],
+  ratchet: ["cosyte-ratchet", "the coverage and mutation ratchet, over the floor file here"],
+  "docs-content": ["cosyte-docs-content", "the docs-content structure check, for the library here"],
 };
 
 const HELP = `script-utils: run one of the @cosyte/script-utils gates over the working directory.

package/catalog.json

@@ -181,7 +181,7 @@
     {
       "name": "@cosyte/cli",
       "slug": "cli",
-      "description": "The Cosyte command line for Node.js and TypeScript: one command over HL7 v2, FHIR R4, X12, ASTM, NCPDP, C-CDA, DICOM, and MLLP, with HL7 v2 to FHIR conversion from transform, code mapping from terminology, and the cosyte-mcp MCP server for agents. Value-free diagnostics and a documented exit-code contract.",
+      "description": "The Cosyte command line for Node.js and TypeScript: one command over HL7 v2, FHIR R4, X12, ASTM, NCPDP, C-CDA, DICOM, and MLLP, with HL7 v2 to FHIR conversion from transform, code mapping from terminology, and the cosyte-mcp MCP server for agents.",
       "line": "0.1",
       "engines": {
         "node": ">=22.0.0"

package/changes.d.ts

@@ -0,0 +1,78 @@
+/** The result of running git: its exit status (`null` when it could not start) and its output. */
+export interface GitResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/** Runs git with array arguments in a directory, writing `input`, when given, to its standard input. */
+export type GitRunner = (args: string[], cwd: string, input?: string) => GitResult;
+
+/** What a change touched against a base ref. */
+export interface Changes {
+  /** The repository root. */
+  root: string;
+  /** The base ref, as given. */
+  base: string;
+  /** The merge base of the base ref and HEAD. */
+  mergeBase: string;
+  /** Each changed file, relative to the root, with the 1-based lines its new version added or changed. */
+  files: Map<string, Set<number>>;
+}
+
+/** Thrown when git cannot answer: no repository, an unknown base, a failed diff. */
+export declare class ChangesUnreadable extends Error {
+  constructor(message: string);
+}
+
+/**
+ * Undo git's C-style quoting of a path. A path git did not quote is returned as it is.
+ *
+ * @param path A path as git printed it.
+ * @returns The path.
+ */
+export declare function unquoteGitPath(path: string): string;
+
+/**
+ * Read the changed lines out of a zero-context unified diff.
+ *
+ * @param text The diff.
+ * @returns Each changed file with its changed lines.
+ */
+export declare function parseUnifiedDiff(text: string): Map<string, Set<number>>;
+
+/**
+ * The lines a change touched against a base ref: the diff from the merge base to the working tree,
+ * plus every untracked file git does not ignore.
+ *
+ * @param opts The base ref, a directory inside the repository, and the git runner.
+ * @returns What changed.
+ * @throws {ChangesUnreadable} When git cannot answer.
+ * @example
+ * ```js
+ * import { readChanges } from "@cosyte/script-utils/changes";
+ * const { files } = readChanges({ base: "origin/main" });
+ * ```
+ */
+export declare function readChanges(opts: { base: string; cwd?: string; git?: GitRunner }): Changes;
+
+/**
+ * A file as it was at a commit. The path reaches git on standard input, never as an argument.
+ *
+ * @param opts The commit id as git printed it, the path relative to the repository root, a
+ *   directory inside the repository, and the git runner.
+ * @returns The file's text, or `null` when the commit has no such path.
+ * @throws {ChangesUnreadable} When git cannot answer, or the path names no file.
+ * @example
+ * ```js
+ * import { readChanges, readFileAtCommit } from "@cosyte/script-utils/changes";
+ * const { mergeBase, root } = readChanges({ base: "origin/main" });
+ * const before = readFileAtCommit({ commit: mergeBase, path: "quality-floor.json", cwd: root });
+ * ```
+ */
+export declare function readFileAtCommit(opts: {
+  commit: string;
+  path: string;
+  cwd: string;
+  git?: GitRunner;
+}): string | null;

package/changes.js

@@ -0,0 +1,269 @@
+// @cosyte/script-utils/changes
+//
+// WHAT A PULL REQUEST CHANGED, BY LINE, READ FROM GIT. The ratchet's rule for a pull request (its
+// changed lines covered, every mutant in them killed) and the changed-files mutation run both need
+// the same answer to "what did this change touch", so it is computed here, once.
+//
+// The answer is the diff from the merge base of the base ref and HEAD to the working tree, plus
+// every untracked file that git does not ignore. In CI the working tree is HEAD, so this is exactly
+// what the pull request changed. Locally it also counts edits not yet committed, which is what a
+// person running the gate before pushing wants judged.
+//
+// A deleted file changes no lines that still exist, so it is left out. A file moved without edits
+// changes none either (rename detection is switched on explicitly, so a user's `diff.renames`
+// setting cannot change the answer). Zero dependencies, like the rest of this package.
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Thrown when git cannot answer: no repository, an unknown base, a failed diff. Exit 2. */
+export class ChangesUnreadable extends Error {
+  /**
+   * @param {string} message What could not be read.
+   */
+  constructor(message) {
+    super(message);
+    this.name = "ChangesUnreadable";
+  }
+}
+
+/**
+ * Run git with array arguments, never through a shell. Not exported: every argument a caller
+ * could reach is a literal or an id git itself printed, and a value a caller passes in (a base
+ * ref, a path) reaches git on standard input, so no value can become an option such as
+ * `--upload-pack`, which runs a command.
+ *
+ * @param {string[]} args The arguments.
+ * @param {string} cwd The directory to run in.
+ * @param {string} [input] What to write to git's standard input.
+ * @returns {{ status: number | null, stdout: string, stderr: string }} The result.
+ */
+function runGit(args, cwd, input) {
+  const r = spawnSync("git", args, {
+    cwd,
+    input,
+    encoding: "utf8",
+    maxBuffer: 256 * 1024 * 1024,
+  });
+  // When git could not start, the status is null and nothing reads the output.
+  return {
+    status: r.error ? null : r.status,
+    stdout: r.stdout,
+    stderr: r.error ? r.error.message : r.stderr,
+  };
+}
+
+/** A commit id as git prints one: 40 hex digits, or 64 in a SHA-256 repository. */
+const COMMIT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+/** A control character: it would end or break the line git reads a name from. */
+const CONTROL = /[\u0000-\u001f\u007f]/;
+
+/**
+ * Run git, throwing {@link ChangesUnreadable} with git's own complaint when it fails.
+ *
+ * @param {typeof runGit} git Runs git.
+ * @param {string[]} args The arguments.
+ * @param {string} cwd The directory to run in.
+ * @param {string} what What could not be read, for the message.
+ * @param {string} [input] What to write to git's standard input.
+ * @returns {string} Git's standard output.
+ */
+function mustRun(git, args, cwd, what, input) {
+  const r = git(args, cwd, input);
+  if (r.status !== 0) {
+    throw new ChangesUnreadable(`${what}: git ${args.join(" ")} failed: ${r.stderr.trim()}`);
+  }
+  return r.stdout;
+}
+
+/** The escapes git writes in a quoted path besides octal bytes, as the byte each stands for. */
+const GIT_ESCAPES = Object.freeze({ n: 10, t: 9, r: 13 });
+
+/**
+ * Undo git's C-style quoting of a path (`"a\"b"`, octal escapes for bytes). A path git did not
+ * quote is returned as it is.
+ *
+ * @param {string} path A path as git printed it.
+ * @returns {string} The path.
+ */
+export function unquoteGitPath(path) {
+  if (!path.startsWith('"') || !path.endsWith('"') || path.length < 2) return path;
+  const body = path.slice(1, -1);
+  /** @type {number[]} */
+  const bytes = [];
+  for (let i = 0; i < body.length; i += 1) {
+    const ch = body[i];
+    if (ch !== "\\") {
+      bytes.push(...Buffer.from(ch));
+      continue;
+    }
+    const next = body[i + 1];
+    const octal = /^[0-7]{3}/.exec(body.slice(i + 1));
+    if (octal !== null) {
+      bytes.push(Number.parseInt(octal[0], 8));
+      i += 3;
+      continue;
+    }
+    bytes.push(GIT_ESCAPES[next] ?? next.charCodeAt(0));
+    i += 1;
+  }
+  return Buffer.from(bytes).toString("utf8");
+}
+
+/**
+ * Read the changed lines out of a zero-context unified diff (`git diff --unified=0`).
+ *
+ * @param {string} text The diff.
+ * @returns {Map<string, Set<number>>} Each changed file, relative to the repository root, with the
+ *   1-based line numbers its new version added or changed.
+ */
+export function parseUnifiedDiff(text) {
+  /** @type {Map<string, Set<number>>} */
+  const files = new Map();
+  /** @type {Set<number> | null} */
+  let current = null;
+  for (const line of text.split("\n")) {
+    if (line.startsWith("+++ ")) {
+      // git ends a name that has a space in it with a tab, for patch(1); the tab is not the name's.
+      const target = line.endsWith("\t") ? line.slice(4, -1) : line.slice(4);
+      if (target === "/dev/null") {
+        current = null;
+        continue;
+      }
+      // The destination prefix is pinned to b/ by the diff's own arguments, whatever the config says.
+      const path = unquoteGitPath(target).slice(2);
+      current = files.get(path) ?? new Set();
+      files.set(path, current);
+      continue;
+    }
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+    if (hunk !== null && current !== null) {
+      const start = Number(hunk[1]);
+      const count = hunk[2] === undefined ? 1 : Number(hunk[2]);
+      for (let n = start; n < start + count; n += 1) current.add(n);
+    }
+  }
+  return files;
+}
+
+/**
+ * The lines a change touched against a base ref.
+ *
+ * @param {object} opts Options.
+ * @param {string} opts.base The base ref, for example `origin/main`.
+ * @param {string} [opts.cwd] Any directory inside the repository.
+ * @param {typeof runGit} [opts.git] Runs git; replaced in tests.
+ * @returns {{ root: string, base: string, mergeBase: string, files: Map<string, Set<number>> }}
+ *   The repository root, the base as given, the merge base it resolved to, and each changed file
+ *   (relative to the root) with its changed lines.
+ * @throws {ChangesUnreadable} When git cannot answer.
+ */
+export function readChanges({ base, cwd = process.cwd(), git = runGit }) {
+  if (typeof base !== "string" || base === "") {
+    throw new ChangesUnreadable("no base ref was given to compare against");
+  }
+  // The ref reaches git on standard input, never as an argument. A dash at its start still names
+  // no ref git would take, so it is refused as a mistake, and a control character would end the
+  // line git reads it from.
+  if (base.startsWith("-")) {
+    throw new ChangesUnreadable(`the base ref ${JSON.stringify(base)} starts with a dash`);
+  }
+  if (CONTROL.test(base)) {
+    throw new ChangesUnreadable(`the base ref ${JSON.stringify(base)} has a control character`);
+  }
+  const root = mustRun(
+    git,
+    ["rev-parse", "--show-toplevel"],
+    cwd,
+    "not inside a git repository",
+  ).trim();
+  // Everything after this runs at the root, so a run from a package directory sees the whole change.
+  const must = (args, what, input) => mustRun(git, args, root, what, input);
+  const resolved = must(
+    ["cat-file", "--batch-check=%(objectname)"],
+    "could not resolve the base ref",
+    `${base}^{commit}\n`,
+  ).trim();
+  if (!COMMIT_ID.test(resolved)) {
+    throw new ChangesUnreadable(
+      `the base ref ${JSON.stringify(base)} names no commit git can find`,
+    );
+  }
+  const mergeBase = must(["merge-base", resolved, "HEAD"], `no merge base with ${base}`).trim();
+  const diff = must(
+    [
+      "-c",
+      "core.quotepath=off",
+      "diff",
+      "--unified=0",
+      "--no-color",
+      "--no-ext-diff",
+      "--find-renames",
+      "--src-prefix=a/",
+      "--dst-prefix=b/",
+      "--diff-filter=d",
+      mergeBase,
+      "--",
+    ],
+    "could not diff against the merge base",
+  );
+  const files = parseUnifiedDiff(diff);
+  const untracked = must(
+    ["-c", "core.quotepath=off", "ls-files", "--others", "--exclude-standard", "--full-name"],
+    "could not list untracked files",
+  );
+  // The listing ends with a newline, so its last entry is empty: that names the root itself, which
+  // reads as no file and is skipped like any path that cannot be read (a dangling link, a socket).
+  for (const raw of untracked.split("\n")) {
+    const path = unquoteGitPath(raw);
+    let text;
+    try {
+      text = String(readFileSync(join(root, path)));
+    } catch {
+      continue;
+    }
+    const count = text === "" ? 0 : text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+    files.set(path, new Set(Array.from({ length: count }, (_, i) => i + 1)));
+  }
+  return { root, base, mergeBase, files };
+}
+
+/**
+ * A file as it was at a commit: what the ratchet reads the floor file at the merge base with.
+ *
+ * @param {object} opts Options.
+ * @param {string} opts.commit The commit id, as git printed it.
+ * @param {string} opts.path The file, relative to the repository root, with `/` separators.
+ * @param {string} opts.cwd Any directory inside the repository.
+ * @param {typeof runGit} [opts.git] Runs git; replaced in tests.
+ * @returns {string | null} The file's text, or `null` when the commit has no such path.
+ * @throws {ChangesUnreadable} When git cannot answer, or the path names no file.
+ */
+export function readFileAtCommit({ commit, path, cwd, git = runGit }) {
+  if (!COMMIT_ID.test(commit)) {
+    throw new ChangesUnreadable(`the commit ${JSON.stringify(commit)} is not a commit id`);
+  }
+  if (CONTROL.test(path)) {
+    throw new ChangesUnreadable(`the path ${JSON.stringify(path)} has a control character`);
+  }
+  // `cat-file --batch` reads the name from standard input and prints a header line, the content,
+  // and a newline; a name it cannot find prints only `<name> missing`.
+  const out = mustRun(
+    git,
+    ["cat-file", "--batch"],
+    cwd,
+    `could not read ${path} at ${commit}`,
+    `${commit}:${path}\n`,
+  );
+  const end = out.indexOf("\n");
+  const header = end === -1 ? out : out.slice(0, end);
+  if (header === `${commit}:${path} missing`) return null;
+  const parts = header.split(" ");
+  if (parts.length !== 3 || !COMMIT_ID.test(parts[0])) {
+    throw new ChangesUnreadable(`${path} at ${commit} could not be read: ${header}`);
+  }
+  if (parts[1] !== "blob") throw new ChangesUnreadable(`${path} at ${commit} is not a file`);
+  return out.slice(end + 1, -1);
+}