@variance-authority/report 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# @variance-authority/report
+
+## 0.1.0
+
+### Minor Changes
+
+- 1d402d1: Carry the narrowing coordinate in the report, and print it in the summary header.
+  
+  A `RunReport` now holds `narrowing`: the ref the run was told to observe from,
+  and where the recorded execution index stands — the commit it was written at and
+  how many files the working tree differs from it by. A run that narrowed nothing
+  carries the second half alone, so the coordinate is present whether or not it was
+  spent.
+  
+  `variance_summary` prints it. Narrowing is an option and stays one; what this
+  refuses is the state where an agent works against a suite for weeks without ever
+  learning that an index is on disk and that the distance from it is a number. The
+  line names the commit and spells out the `variance run --since` that would use
+  it, and is omitted when there is no index, no position, or no distance.
+  
+  `run` takes the coordinate as `index` and acts on it for nothing else.
+  `narrowingFor` resolves `since`, `against` and `index` together, so a caller
+  assembling a run reaches one call rather than three.
+
+### Patch Changes
+
+- Updated dependencies [e8fee66]
+- Updated dependencies [5c34e6d]
+  - @variance-authority/core@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machine Garden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+<p align="center"><img src="./mark.svg" alt="Variance Authority mark" width="72"></p>
+
+# @variance-authority/report
+
+> The shape a Variance Authority run leaves behind, so a person, a pull request and an agent read one format.
+
+What a run leaves behind. A run compares one or more **subjects** — the pages,
+routes, or components under test — and produces its answers in memory before the
+process ends. A **`RunReport`** is the shape those answers take, so they can be
+read afterwards: from a different process, on a different machine, by whoever or
+whatever is asking. The format itself is plain data; only `report/file` touches a
+disk, and it needs a path this process can read and write.
+
+```bash
+npm install --save-dev @variance-authority/report
+```
+## Use this package when
+
+Install `@variance-authority/report` when a producer and its readers need a
+versioned run artifact without sharing a runner, browser, or transport. Use the
+root entrypoint for in-memory report types and derivations. Use
+`@variance-authority/report/file` only when this process should read or write a
+local path; an object store, PR comment, or socket should carry the same
+`RunReport` value without importing the file entrypoint.
+
+This package does not compare anything itself. It has no browser, no renderer,
+and no baseline store — pair it with whatever produces a `RunReport` (the
+`variance` CLI, or a custom runner) and, on the reading side, with something
+like `@variance-authority/mcp` or `@variance-authority/store`.
+
+## Package boundary
+
+It has several readers. The CLI writes it, a PR comment renders it, the MCP tools
+read it, and none of those is the format's home — a format owned by one reader
+bends towards that reader.
+
+The failure that shape produces is concrete: with these types living in
+`@variance-authority/mcp`, the CLI depends on an agent protocol to describe its
+own output.
+
+## Entrypoints
+
+| entrypoint | requires | holds |
+|---|---|---|
+| `.` | nothing | `RunReport`, `ObservationRecord`, `PresentationSignalRecord`, `RegionRecord`, `NotObserved`, `clusterChanges`, `adjudicateRun` |
+| `./file` | a filesystem | `readRunReport`, `writeRunReport` |
+
+The split exists because a run happening on a pinned machine in CI and the
+questions being asked on a laptop is exactly why this artifact exists — and a
+consumer who moves it some other way (an object store, a PR comment, a socket)
+wants the shapes and not the disk.
+
+## Smallest working path
+
+```ts
+import { readRunReport, writeRunReport } from '@variance-authority/report/file';
+
+// Throws on an unknown runVersion or malformed notObserved entry.
+const report = await readRunReport('.variance/run.json');
+console.log(report.runVersion, report.observations.length);
+
+// A producer can write the same validated shape to a new path.
+await writeRunReport('.variance/checked.json', report);
+```
+
+The read returns a validated `RunReport`; the file entrypoint does not rerun a
+browser or recompute observations. A report from a future format is refused,
+and an absent `notObserved` field remains absent rather than being treated as an
+empty coverage list.
+
+## The shape
+
+A `RunReport` is one JSON value: run metadata plus one **`ObservationRecord`**
+per subject. Trimmed to the fields most reports use:
+
+```json
+{
+  "runVersion": 1,
+  "at": "2026-08-27T10:00:00.000Z",
+  "identity": {
+    "renderer": "playwright-chromium@1.49.0",
+    "engine": "chromium@131",
+    "platform": "linux-x64",
+    "deviceScaleFactor": 1,
+    "fonts": ["Inter"]
+  },
+  "retention": "durable",
+  "observations": [
+    {
+      "subject": "component:Button",
+      "verdict": "changed",
+      "because": "12 pixels differ inside the label",
+      "changedPixels": 12,
+      "regions": [
+        { "x": 4, "y": 8, "width": 60, "height": 18, "pixels": 12, "component": "Button", "cause": true }
+      ]
+    }
+  ]
+}
+```
+
+Each `ObservationRecord` holds one subject's **verdict** — `unchanged`,
+`changed`, `new`, `incomparable`, or `ignored` — and, when it changed, the
+**region**s responsible: attributed rectangles of the diff, each with the
+component and pixel count that explain it.
+
+A report also carries **`narrowing`**: the ref a run was told to observe from,
+and where the recorded execution index stands — the commit it was written at,
+and how many files the working tree differs from it by. A run that observed
+everything carries the second half alone, which is what makes a narrowing option
+visible to a reader who never passed one. Absent `index` means there is nothing
+to diff from, either because no index was recorded or because the one on disk has
+no position; it never means the index is current, which is `changed: 0`.
+
+## Presentation consequence is a signal, not a verdict
+
+An `ObservationRecord` can carry one or more **signals** —
+`ObservationRecord.signals`, each an independently measured boundary
+(`document`, `pixels`, `accessibility`, `presentation`); a missing member means
+that boundary was never measured, not that it was clean.
+`ObservationRecord.signals.presentation` retains what changed in rendered
+relationships beside the document, pixel, and accessibility boundaries. It is
+orthogonal to the renderer's `layout`/`paint`/`composite` impact and does not
+change the observation verdict.
+
+A comparable signal carries the two presentation-report digests, information
+counts, and `introduced`, `resolved`, or `persisted` relationship effects. An
+empty `effects` list means both sides were measured and no relationship
+consequence changed. An `incomparable` signal carries a reason and no effects;
+an absent `presentation` member means nothing measured that boundary.
+
+Product-aware collectors return the signal with their collected subject. The
+CLI carries it through both a pixel-compared path and a **digest-settled**
+one — a subject whose document digest matched the baseline's, so it was
+declared unchanged without ever being repainted — and the JSON file,
+HTML report, text report, MCP description, and Tribunal record read the same
+stored value without re-running presentation analysis. The producing API and a complete
+example live with `@variance-authority/presentation`.
+
+## Format derivations
+
+None has a home in a reader. `clusterChanges` groups a run's changed subjects
+by fingerprint — the shape digest carried on each region — into a **cluster**:
+the set of subjects a single accept-or-reject decision covers. A token edit
+across forty stories becomes one cluster, so it is **one decision presented
+once** rather than forty. `adjudicateRun` reads those changes back against what
+the author said they were doing:
+
+```ts
+import { readRunReport } from '@variance-authority/report/file';
+import { adjudicateRun, describeAdjudication } from '@variance-authority/report';
+
+const report = await readRunReport('.variance/run.json');
+const answer = adjudicateRun(
+  report,
+  [{ root: 'component:Button', reason: 'new brand accent', maxSubjects: 3 }],
+  { unchecked: ['bands'] },
+);
+
+console.log(describeAdjudication(answer));
+```
+
+Each claim comes back `delivered`, `overreached`, `undelivered` or
+`unobservable`, alongside the changes no claim covered. `undelivered` is the one
+no diff can produce on its own — a component that **rendered and held still**,
+which means the edit did not take. Telling that apart from *never rendered, so
+nothing here is evidence* is what the composition census is for, and why the
+adjudication lives beside the format rather than inside a reader.
+
+`unchecked` is how a boundary keeps a claim it could not verify. A caller that
+parses agent-supplied claims — the MCP tool, the CLI — passes the field names
+this resolution does not read, and the answer ends `Not checked here: bands`
+instead of reporting `delivered` about something nothing looked at. Dropping
+them silently would be the more comfortable default and the worse one: the agent
+would be told its band claim held.
+
+## Changelog derivation
+
+A baseline update lands in a run of its own — `variance accept` promotes what a
+reviewer looked at — and the artifact that lands says *what* the new baseline is
+and nothing about **what the change was**. A month later, at the twelfth 2px
+approval, the report that could have said is gone with the CI job.
+
+`changelogOf` folds a report and the subjects that were actually accepted into
+one record, and `renderCommitMessage` puts it where the baseline is: in the
+commit message, as prose a reviewer reads and trailers a parser reads.
+
+```ts
+import { readRunReport } from '@variance-authority/report/file';
+import {
+  changelogOf,
+  isRecorded,
+  renderCommitMessage,
+  parseCommitMessage,
+} from '@variance-authority/report';
+
+const report = await readRunReport('.variance/run.json');
+const accepted = report.observations
+  .filter((observation) => observation.verdict === 'changed')
+  .slice(0, 2)
+  .map((observation) => observation.subject);
+if (accepted.length === 0) throw new Error('the report has no changed subject to promote');
+
+const record = changelogOf({
+  report,
+  accepted,
+  selection: 'shape',
+  at: new Date().toISOString(),
+  project: 'design-system',
+  by: 'marina',
+});
+
+if (isRecorded(record)) {
+  const text = renderCommitMessage({ message: 'chore(variance): regenerate baselines', record });
+  parseCommitMessage(text); // the same record, out of a commit somebody squash-merged
+}
+```
+
+`changelogOf` takes:
+
+| option | what it decides |
+|---|---|
+| `report` | the run the reviewer read. Nothing is re-derived from bytes; the entry is evidence about a decision rather than a second opinion about an image |
+| `accepted` | the subjects actually promoted. The entries are the **intersection** with each cluster, never the cluster's own list — `accept --shape` refuses by name any subject where something else also moved, and an entry that copied the cluster would claim those too |
+| `selection` | `named`, `shape` or `all`. Recorded rather than inferred: a regeneration under `--all` and a reviewed subject are different amounts of review, and a record that flattened them would let one read as the other |
+| `at` | ISO 8601, injected. Nothing written into a record may come from a hidden clock |
+| `project` | optional; the name the run is scoped by |
+| `by` | optional; who accepted |
+| `entries` | optional; entries a caller already formed, appended after the clustered ones. Region clustering is one producer of entries, not the definition of one — a change to an interface is the same kind of fact and has no rectangle, and the alternative was fabricating four numbers into a `RegionRecord` to get through the region path. `ungrouped` is untouched by them, and an entry with no fingerprint, no subjects, or fewer reached than promoted is refused rather than written |
+
+It refuses, with a message rather than an empty record, when nothing was
+accepted or when the report has no run id to attribute the baseline to.
+
+The record omits a changed-pixel count (the regions already say where the
+change was), rendered prose (drift is a token and two values instead), and any
+derived total. `changelogVersion` changes only when an existing field's meaning
+changes — a reader keeps keys it does not recognize, so adding a new field does
+not need one.
+
+`renderCommitMessage` takes `message` (the operator's subject line, emitted
+unchanged) and `record`, and emits one versioned, opaque trailer per change.
+`parseCommitMessage` scans the whole message for them rather than just the last
+paragraph, since a squash merge can move them out of it.
+
+Reading it back where baselines are commits is
+`@variance-authority/store`'s `readChangelog`; where they are rows it
+is `@variance-authority/tribunal`'s.
+
+## Validation boundaries
+
+`readRunReport` validates rather than casts. It refuses:
+
+- an unknown `runVersion`, including one from a future writer
+- a malformed `notObserved` entry
+- a presentation transition missing the before/after evidence it requires
+
+A caller gets a fully-typed `RunReport` back, or a thrown error — never a
+partially-parsed value with some fields silently absent.

package/dist/changelog-message.d.ts

@@ -0,0 +1,51 @@
+import type { ChangelogRecord } from './changelog.js';
+export interface CommitMessageOptions {
+    /** The subject line, in the operator's words. The record never invents one. */
+    readonly message: string;
+    readonly record: ChangelogRecord;
+}
+/**
+ * Render the commit that carries a baseline update.
+ *
+ * The subject line is the operator's, unchanged. A command that rewrote it would
+ * be overruling the one part of the message a project's own conventions govern —
+ * and every repository with a commit-message convention has one.
+ */
+export declare function renderCommitMessage(options: CommitMessageOptions): string;
+/**
+ * The body, as lines somebody scans rather than sentences they read.
+ *
+ * Exported because a commit message is not the only place these lines belong.
+ * An agent asking *what would this update record* before running `accept` has to
+ * be answered in the same words the commit will carry, or the preview becomes a
+ * second description of a baseline update — and the two would then be edited
+ * separately until one of them was wrong.
+ *
+ * This lands in **every** baseline commit. That is the constraint the shape is
+ * chosen for: a paragraph explaining what `--all` means is true, and by the
+ * fourth commit nobody reads it, and by the tenth it is what `git log` looks
+ * like. So the body is a table — one line per change, fixed columns, fingerprint
+ * first, because that is the token a reader recognises when the same shape comes
+ * back three months later.
+ *
+ * Nothing here argues. Everything that used to be argued in prose is in the
+ * trailers, where the reader that needs it decodes it and the person scrolling
+ * past does not pay for it.
+ */
+export declare function changelogBody(record: ChangelogRecord): readonly string[];
+/**
+ * Read the record out of a commit message, or `undefined` when it carries none.
+ *
+ * `undefined` is *this commit is not a baseline update*, which is the answer for
+ * almost every commit in a repository and is not a failure. A malformed one is,
+ * and it throws: a record that half-parsed would answer "what changed here" with
+ * the part that happened to survive.
+ *
+ * Keys this reader does not know are **kept, not refused**. A field added by a
+ * later writer is not a corrupt record, it is a newer one, and a reader that
+ * threw on it would make every additive change a breaking change — which is the
+ * pressure that turns a version number into a wall nobody may cross. The version
+ * is checked instead, and it moves only when an existing field changes meaning.
+ */
+export declare function parseCommitMessage(text: string): ChangelogRecord | undefined;
+//# sourceMappingURL=changelog-message.d.ts.map

package/dist/changelog-message.js

@@ -0,0 +1,244 @@
+/**
+ * The record as a commit message, and back.
+ *
+ * Where baselines are files in the repository, the commit that updates them is
+ * the only artifact guaranteed to still exist when somebody asks why. It already
+ * has a place for an explanation, and every tool a reader has — `git log`,
+ * `git blame`, a pull request page — already shows it. So the message *is* the
+ * store, and this is its codec.
+ *
+ * ## Two audiences, two halves, one message
+ *
+ * The subject line and the table under it are for whoever scrolls `git log`. The
+ * **trailers** are for the reader that comes back with a question. Asking one
+ * string to be both readable and parseable is how a format acquires escaping
+ * rules that a component named `Card: small` then breaks, so the halves are
+ * separate and only one of them is parsed.
+ *
+ * That split is also what keeps the readable half short. It carries no field it
+ * has to carry — the record is complete in the trailers either way — so it
+ * carries the four things a person scanning a log is actually looking for, and a
+ * change to what is *displayed* is never a change to what was *recorded*.
+ *
+ * ## Why the payload is opaque
+ *
+ * A trailer value is a single line of arbitrary text, and every field here is a
+ * string somebody else chose: subject ids, component names, an intent sentence,
+ * a file path. Base64url removes the entire question — no delimiter to collide
+ * with, no colon to split on twice, nothing that can become shell or markdown
+ * syntax on the way through a pull-request body.
+ *
+ * The `v1` prefix in front of it is what lets a later reader **refuse** rather
+ * than half-understand. A commit written by a newer writer is named as such;
+ * partly parsing it would answer a question about a change with a subset of what
+ * that change was.
+ *
+ * ## What git does to this, and what it does not
+ *
+ * Trailers are repeated keys, one per entry, which git treats as ordered and
+ * preserves. Values never contain a newline, so nothing ever needs unfolding.
+ *
+ * The parser scans the **whole message**, not the last paragraph. That deviates
+ * from git's own trailer rules deliberately: a squash merge concatenates commit
+ * bodies, so a baseline commit's trailers land mid-message and `%(trailers)`
+ * finds nothing. A false positive is not reachable — a line that matches must
+ * also decode as base64 and parse as a versioned record.
+ *
+ * What this cannot promise is append-only. `--amend` and `reword` rewrite a
+ * message in place and nothing here observes it. That is a property of the
+ * medium, stated rather than papered over: the trigger-backed guarantee belongs
+ * to the review database, and a repository is a place where history is editable
+ * by whoever can push.
+ */
+/** Head fields: which run, at which commit, and how it was accepted. */
+const HEAD = 'Variance-Run';
+/** One per change, repeated. */
+const CHANGE = 'Variance-Change';
+const VERSION = 'v1';
+/** How many changes the prose names before it starts counting instead. */
+const NAMED_IN_PROSE = 20;
+/**
+ * Render the commit that carries a baseline update.
+ *
+ * The subject line is the operator's, unchanged. A command that rewrote it would
+ * be overruling the one part of the message a project's own conventions govern —
+ * and every repository with a commit-message convention has one.
+ */
+export function renderCommitMessage(options) {
+    const { record } = options;
+    const head = { ...record, entries: undefined };
+    return [
+        options.message,
+        '',
+        ...changelogBody(record),
+        '',
+        `${HEAD}: ${VERSION} ${encode(head)}`,
+        ...record.entries.map((entry) => `${CHANGE}: ${VERSION} ${encode(entry)}`),
+        '',
+    ].join('\n');
+}
+/**
+ * The body, as lines somebody scans rather than sentences they read.
+ *
+ * Exported because a commit message is not the only place these lines belong.
+ * An agent asking *what would this update record* before running `accept` has to
+ * be answered in the same words the commit will carry, or the preview becomes a
+ * second description of a baseline update — and the two would then be edited
+ * separately until one of them was wrong.
+ *
+ * This lands in **every** baseline commit. That is the constraint the shape is
+ * chosen for: a paragraph explaining what `--all` means is true, and by the
+ * fourth commit nobody reads it, and by the tenth it is what `git log` looks
+ * like. So the body is a table — one line per change, fixed columns, fingerprint
+ * first, because that is the token a reader recognises when the same shape comes
+ * back three months later.
+ *
+ * Nothing here argues. Everything that used to be argued in prose is in the
+ * trailers, where the reader that needs it decodes it and the person scrolling
+ * past does not pay for it.
+ */
+export function changelogBody(record) {
+    const lines = [];
+    // The operator's own sentence, unlabelled. It is the one line here a person
+    // wrote, and an `Intent:` prefix would be this format taking credit for it.
+    if (record.intent !== undefined)
+        lines.push(record.intent, '');
+    for (const entry of record.entries.slice(0, NAMED_IN_PROSE))
+        lines.push(describe(entry));
+    if (record.entries.length > NAMED_IN_PROSE) {
+        lines.push(`+${String(record.entries.length - NAMED_IN_PROSE)} more in trailers`);
+    }
+    // On its own line rather than folded into a change: nothing in the run said
+    // what changed in these subjects, and a count that cannot become a row must
+    // not be printed as one.
+    if (record.ungrouped > 0)
+        lines.push(`+${String(record.ungrouped)} unshaped`);
+    // The one finding that earns a full line of its own, because it is about what
+    // no single review could see — including the one that produced this commit.
+    for (const drift of record.drift ?? []) {
+        lines.push(`drift ${drift.token} ${drift.from} -> ${drift.to} over ${String(drift.steps)} approvals`);
+    }
+    lines.push('', `run ${record.run} @ ${record.commit} ${selection(record.selection)}` +
+        `${record.by === undefined ? '' : ` ${record.by}`}`);
+    return lines;
+}
+/**
+ * One change, as columns: what it is, where it was, how much of it landed.
+ *
+ * The fingerprint leads because it is the only field on the line that is stable
+ * *across* commits — the same shape returning is the finding, and a reader who
+ * has seen `v1:9a3f1c2e04` before recognises it without reading the rest. It is
+ * also the exact string `accept --shape` and an ignore take, so the line is
+ * something to copy rather than something to interpret.
+ *
+ * A shape with no component keeps its digest rather than borrowing a name, and
+ * says which it is. "An unnamed shape" is a weaker claim than a component, and a
+ * line that hid the difference would let a bulk decision be read back as an
+ * attributed one.
+ *
+ * `3/4` wherever the promotion was partial: the subjects this shape reached and
+ * did not take are the part of the change still sitting in the suite, and a bare
+ * count reads as though the whole shape landed.
+ */
+function describe(entry) {
+    const what = entry.component === undefined
+        ? `unnamed ${entry.fingerprint.slice(0, 12)}`
+        : `${entry.component}${entry.file === undefined ? '' : ` ${entry.file}`}`;
+    const subjects = entry.reached > entry.subjects.length
+        ? `${String(entry.subjects.length)}/${String(entry.reached)}`
+        : String(entry.subjects.length);
+    return `${entry.fingerprint} ${what} ${subjects}${entry.cause ? '' : ' collateral'}`;
+}
+/**
+ * The flag that chose the subjects, as the flag.
+ *
+ * `--all` accepts changed subjects as well as new ones — unattended, that is
+ * regeneration rather than review, and it is the distinction this whole record
+ * exists to keep. Carried as the flag rather than as the clause explaining it:
+ * the clause is identical in every commit ever written, and the flag is the part
+ * that differs between them.
+ */
+function selection(kind) {
+    if (kind === 'all')
+        return '--all';
+    if (kind === 'shape')
+        return '--shape';
+    return '--subject';
+}
+/**
+ * Read the record out of a commit message, or `undefined` when it carries none.
+ *
+ * `undefined` is *this commit is not a baseline update*, which is the answer for
+ * almost every commit in a repository and is not a failure. A malformed one is,
+ * and it throws: a record that half-parsed would answer "what changed here" with
+ * the part that happened to survive.
+ *
+ * Keys this reader does not know are **kept, not refused**. A field added by a
+ * later writer is not a corrupt record, it is a newer one, and a reader that
+ * threw on it would make every additive change a breaking change — which is the
+ * pressure that turns a version number into a wall nobody may cross. The version
+ * is checked instead, and it moves only when an existing field changes meaning.
+ */
+export function parseCommitMessage(text) {
+    const head = payload(text, HEAD);
+    if (head === undefined)
+        return undefined;
+    const record = decode(head, HEAD);
+    if (record.changelogVersion !== 1) {
+        throw new Error(`a commit carries a variance changelog with changelogVersion=${String(record.changelogVersion)}, ` +
+            'which this reader does not know. Partly reading it would describe a baseline update by ' +
+            'whichever fields happened to be recognised');
+    }
+    const entries = payloads(text, CHANGE).map((value) => decode(value, CHANGE));
+    for (const entry of entries) {
+        if (typeof entry.fingerprint !== 'string' || !Array.isArray(entry.subjects)) {
+            throw new Error(`a commit carries a \`${CHANGE}\` trailer that is not a change: it has no fingerprint or ` +
+                'no subject list');
+        }
+    }
+    return { ...record, entries };
+}
+/**
+ * Every value for a key, in message order.
+ *
+ * Anchored on the key and the version together, so a line mentioning the trailer
+ * name in prose — a commit that *discusses* this format, of which this repository
+ * has several — is not mistaken for one.
+ */
+function payloads(text, key) {
+    const pattern = new RegExp(`^[ \\t]*${key}:[ \\t]+(\\S+)[ \\t]+(\\S+)[ \\t]*$`, 'gm');
+    return [...text.matchAll(pattern)].map(([, version, value]) => {
+        if (version !== VERSION) {
+            throw new Error(`a commit carries a \`${key}\` trailer encoded as ${String(version)}, and this reader ` +
+                `understands ${VERSION}`);
+        }
+        return value ?? '';
+    });
+}
+function payload(text, key) {
+    const found = payloads(text, key);
+    if (found.length > 1) {
+        throw new Error(`a commit carries ${String(found.length)} \`${key}\` trailers, and a commit updates ` +
+            'baselines for one run. Two heads in one message is a rewritten history, not a record');
+    }
+    return found[0];
+}
+function encode(value) {
+    const bytes = new TextEncoder().encode(JSON.stringify(value));
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function decode(value, key) {
+    try {
+        const binary = atob(value.replace(/-/g, '+').replace(/_/g, '/'));
+        const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch (error) {
+        throw new Error(`a commit carries a \`${key}\` trailer this reader cannot decode ` +
+            `(${error instanceof Error ? error.message : String(error)})`);
+    }
+}
+//# sourceMappingURL=changelog-message.js.map

package/dist/changelog-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog-message.js","sourceRoot":"","sources":["../src/changelog-message.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ChangelogEntry, ChangelogRecord } from './changelog.js';\n\n/**\n * The record as a commit message, and back.\n *\n * Where baselines are files in the repository, the commit that updates them is\n * the only artifact guaranteed to still exist when somebody asks why. It already\n * has a place for an explanation, and every tool a reader has — `git log`,\n * `git blame`, a pull request page — already shows it. So the message *is* the\n * store, and this is its codec.\n *\n * ## Two audiences, two halves, one message\n *\n * The subject line and the table under it are for whoever scrolls `git log`. The\n * **trailers** are for the reader that comes back with a question. Asking one\n * string to be both readable and parseable is how a format acquires escaping\n * rules that a component named `Card: small` then breaks, so the halves are\n * separate and only one of them is parsed.\n *\n * That split is also what keeps the readable half short. It carries no field it\n * has to carry — the record is complete in the trailers either way — so it\n * carries the four things a person scanning a log is actually looking for, and a\n * change to what is *displayed* is never a change to what was *recorded*.\n *\n * ## Why the payload is opaque\n *\n * A trailer value is a single line of arbitrary text, and every field here is a\n * string somebody else chose: subject ids, component names, an intent sentence,\n * a file path. Base64url removes the entire question — no delimiter to collide\n * with, no colon to split on twice, nothing that can become shell or markdown\n * syntax on the way through a pull-request body.\n *\n * The `v1` prefix in front of it is what lets a later reader **refuse** rather\n * than half-understand. A commit written by a newer writer is named as such;\n * partly parsing it would answer a question about a change with a subset of what\n * that change was.\n *\n * ## What git does to this, and what it does not\n *\n * Trailers are repeated keys, one per entry, which git treats as ordered and\n * preserves. Values never contain a newline, so nothing ever needs unfolding.\n *\n * The parser scans the **whole message**, not the last paragraph. That deviates\n * from git's own trailer rules deliberately: a squash merge concatenates commit\n * bodies, so a baseline commit's trailers land mid-message and `%(trailers)`\n * finds nothing. A false positive is not reachable — a line that matches must\n * also decode as base64 and parse as a versioned record.\n *\n * What this cannot promise is append-only. `--amend` and `reword` rewrite a\n * message in place and nothing here observes it. That is a property of the\n * medium, stated rather than papered over: the trigger-backed guarantee belongs\n * to the review database, and a repository is a place where history is editable\n * by whoever can push.\n */\n\n/** Head fields: which run, at which commit, and how it was accepted. */\nconst HEAD = 'Variance-Run';\n\n/** One per change, repeated. */\nconst CHANGE = 'Variance-Change';\n\nconst VERSION = 'v1';\n\n/** How many changes the prose names before it starts counting instead. */\nconst NAMED_IN_PROSE = 20;\n\nexport interface CommitMessageOptions {\n  /** The subject line, in the operator's words. The record never invents one. */\n  readonly message: string;\n  readonly record: ChangelogRecord;\n}\n\n/**\n * Render the commit that carries a baseline update.\n *\n * The subject line is the operator's, unchanged. A command that rewrote it would\n * be overruling the one part of the message a project's own conventions govern —\n * and every repository with a commit-message convention has one.\n */\nexport function renderCommitMessage(options: CommitMessageOptions): string {\n  const { record } = options;\n  const head: Record<string, unknown> = { ...record, entries: undefined };\n\n  return [\n    options.message,\n    '',\n    ...changelogBody(record),\n    '',\n    `${HEAD}: ${VERSION} ${encode(head)}`,\n    ...record.entries.map((entry) => `${CHANGE}: ${VERSION} ${encode(entry)}`),\n    '',\n  ].join('\\n');\n}\n\n/**\n * The body, as lines somebody scans rather than sentences they read.\n *\n * Exported because a commit message is not the only place these lines belong.\n * An agent asking *what would this update record* before running `accept` has to\n * be answered in the same words the commit will carry, or the preview becomes a\n * second description of a baseline update — and the two would then be edited\n * separately until one of them was wrong.\n *\n * This lands in **every** baseline commit. That is the constraint the shape is\n * chosen for: a paragraph explaining what `--all` means is true, and by the\n * fourth commit nobody reads it, and by the tenth it is what `git log` looks\n * like. So the body is a table — one line per change, fixed columns, fingerprint\n * first, because that is the token a reader recognises when the same shape comes\n * back three months later.\n *\n * Nothing here argues. Everything that used to be argued in prose is in the\n * trailers, where the reader that needs it decodes it and the person scrolling\n * past does not pay for it.\n */\nexport function changelogBody(record: ChangelogRecord): readonly string[] {\n  const lines: string[] = [];\n\n  // The operator's own sentence, unlabelled. It is the one line here a person\n  // wrote, and an `Intent:` prefix would be this format taking credit for it.\n  if (record.intent !== undefined) lines.push(record.intent, '');\n\n  for (const entry of record.entries.slice(0, NAMED_IN_PROSE)) lines.push(describe(entry));\n  if (record.entries.length > NAMED_IN_PROSE) {\n    lines.push(`+${String(record.entries.length - NAMED_IN_PROSE)} more in trailers`);\n  }\n\n  // On its own line rather than folded into a change: nothing in the run said\n  // what changed in these subjects, and a count that cannot become a row must\n  // not be printed as one.\n  if (record.ungrouped > 0) lines.push(`+${String(record.ungrouped)} unshaped`);\n\n  // The one finding that earns a full line of its own, because it is about what\n  // no single review could see — including the one that produced this commit.\n  for (const drift of record.drift ?? []) {\n    lines.push(\n      `drift ${drift.token} ${drift.from} -> ${drift.to} over ${String(drift.steps)} approvals`,\n    );\n  }\n\n  lines.push(\n    '',\n    `run ${record.run} @ ${record.commit} ${selection(record.selection)}` +\n      `${record.by === undefined ? '' : ` ${record.by}`}`,\n  );\n\n  return lines;\n}\n\n/**\n * One change, as columns: what it is, where it was, how much of it landed.\n *\n * The fingerprint leads because it is the only field on the line that is stable\n * *across* commits — the same shape returning is the finding, and a reader who\n * has seen `v1:9a3f1c2e04` before recognises it without reading the rest. It is\n * also the exact string `accept --shape` and an ignore take, so the line is\n * something to copy rather than something to interpret.\n *\n * A shape with no component keeps its digest rather than borrowing a name, and\n * says which it is. \"An unnamed shape\" is a weaker claim than a component, and a\n * line that hid the difference would let a bulk decision be read back as an\n * attributed one.\n *\n * `3/4` wherever the promotion was partial: the subjects this shape reached and\n * did not take are the part of the change still sitting in the suite, and a bare\n * count reads as though the whole shape landed.\n */\nfunction describe(entry: ChangelogEntry): string {\n  const what =\n    entry.component === undefined\n      ? `unnamed ${entry.fingerprint.slice(0, 12)}`\n      : `${entry.component}${entry.file === undefined ? '' : ` ${entry.file}`}`;\n\n  const subjects =\n    entry.reached > entry.subjects.length\n      ? `${String(entry.subjects.length)}/${String(entry.reached)}`\n      : String(entry.subjects.length);\n\n  return `${entry.fingerprint} ${what} ${subjects}${entry.cause ? '' : ' collateral'}`;\n}\n\n/**\n * The flag that chose the subjects, as the flag.\n *\n * `--all` accepts changed subjects as well as new ones — unattended, that is\n * regeneration rather than review, and it is the distinction this whole record\n * exists to keep. Carried as the flag rather than as the clause explaining it:\n * the clause is identical in every commit ever written, and the flag is the part\n * that differs between them.\n */\nfunction selection(kind: ChangelogRecord['selection']): string {\n  if (kind === 'all') return '--all';\n  if (kind === 'shape') return '--shape';\n  return '--subject';\n}\n\n/**\n * Read the record out of a commit message, or `undefined` when it carries none.\n *\n * `undefined` is *this commit is not a baseline update*, which is the answer for\n * almost every commit in a repository and is not a failure. A malformed one is,\n * and it throws: a record that half-parsed would answer \"what changed here\" with\n * the part that happened to survive.\n *\n * Keys this reader does not know are **kept, not refused**. A field added by a\n * later writer is not a corrupt record, it is a newer one, and a reader that\n * threw on it would make every additive change a breaking change — which is the\n * pressure that turns a version number into a wall nobody may cross. The version\n * is checked instead, and it moves only when an existing field changes meaning.\n */\nexport function parseCommitMessage(text: string): ChangelogRecord | undefined {\n  const head = payload(text, HEAD);\n  if (head === undefined) return undefined;\n\n  const record = decode(head, HEAD) as Omit<ChangelogRecord, 'entries'>;\n  if (record.changelogVersion !== 1) {\n    throw new Error(\n      `a commit carries a variance changelog with changelogVersion=${String(record.changelogVersion)}, ` +\n        'which this reader does not know. Partly reading it would describe a baseline update by ' +\n        'whichever fields happened to be recognised',\n    );\n  }\n\n  const entries = payloads(text, CHANGE).map((value) => decode(value, CHANGE) as ChangelogEntry);\n  for (const entry of entries) {\n    if (typeof entry.fingerprint !== 'string' || !Array.isArray(entry.subjects)) {\n      throw new Error(\n        `a commit carries a \\`${CHANGE}\\` trailer that is not a change: it has no fingerprint or ` +\n          'no subject list',\n      );\n    }\n  }\n\n  return { ...record, entries };\n}\n\n/**\n * Every value for a key, in message order.\n *\n * Anchored on the key and the version together, so a line mentioning the trailer\n * name in prose — a commit that *discusses* this format, of which this repository\n * has several — is not mistaken for one.\n */\nfunction payloads(text: string, key: string): readonly string[] {\n  const pattern = new RegExp(`^[ \\\\t]*${key}:[ \\\\t]+(\\\\S+)[ \\\\t]+(\\\\S+)[ \\\\t]*$`, 'gm');\n\n  return [...text.matchAll(pattern)].map(([, version, value]) => {\n    if (version !== VERSION) {\n      throw new Error(\n        `a commit carries a \\`${key}\\` trailer encoded as ${String(version)}, and this reader ` +\n          `understands ${VERSION}`,\n      );\n    }\n    return value ?? '';\n  });\n}\n\nfunction payload(text: string, key: string): string | undefined {\n  const found = payloads(text, key);\n  if (found.length > 1) {\n    throw new Error(\n      `a commit carries ${String(found.length)} \\`${key}\\` trailers, and a commit updates ` +\n        'baselines for one run. Two heads in one message is a rewritten history, not a record',\n    );\n  }\n  return found[0];\n}\n\nfunction encode(value: unknown): string {\n  const bytes = new TextEncoder().encode(JSON.stringify(value));\n  let binary = '';\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n\n  return btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n}\n\nfunction decode(value: string, key: string): unknown {\n  try {\n    const binary = atob(value.replace(/-/g, '+').replace(/_/g, '/'));\n    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));\n    return JSON.parse(new TextDecoder().decode(bytes));\n  } catch (error) {\n    throw new Error(\n      `a commit carries a \\`${key}\\` trailer this reader cannot decode ` +\n        `(${error instanceof Error ? error.message : String(error)})`,\n    );\n  }\n}\n"]}