@variance-authority/report 0.1.0

package/dist/changelog.d.ts

@@ -0,0 +1,231 @@
+import type { RunReport } from './format.js';
+/**
+ * Why a baseline is what it is — written where the baseline is written.
+ *
+ * A baseline update happens in a run of its own: `variance accept` promotes the
+ * candidates a reviewer looked at, and the artifact that lands is a directory of
+ * PNGs, or a row in a review database. Both record *what* the new baseline is.
+ * Neither records **what the change was**, and by the time anybody asks — a month
+ * later, at the twelfth 2px approval — the report that could have said is gone
+ * with the CI job that wrote it.
+ *
+ * So the explanation is written at the only moment it exists, into the same
+ * artifact as the bytes it explains: a commit message where baselines are commits,
+ * a row where they are rows. This module is the part neither of those owns — the
+ * derivation from a report, and the encoding that survives the trip back.
+ *
+ * ## The unit is a change, not a screenshot
+ *
+ * One entry per **cluster** ([`cluster.ts`](./cluster.ts)), because that is
+ * already this project's answer to the same question one level up: a token edit
+ * across forty stories is one decision, and forty entries would reproduce exactly
+ * the review problem clustering exists to solve. A changelog that logged
+ * screenshots would be forty lines nobody reads, ending in the same place as a
+ * commit message that says `regenerate baselines`.
+ *
+ * ## Only what was accepted, and only what the report already said
+ *
+ * The subjects on an entry are the intersection of the cluster with the subjects
+ * this command actually promoted — 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. What the shape *reached* is carried
+ * as a count beside it, so the shortfall is visible rather than absent.
+ *
+ * Nothing here re-derives anything from bytes. The entry is built from the report
+ * the reviewer read, which is what makes it evidence about a decision rather than
+ * a second opinion about an image.
+ *
+ * ## What a record carries, and what it deliberately does not
+ *
+ * This outlives everything around it. The report is gone with the CI job, the
+ * reviewer has left the project, the file has been renamed twice — and the record
+ * is still in the log, being read by somebody who cannot check any of it. So a
+ * field belongs here only if it will still mean the same thing then.
+ *
+ * Three that would not, and are absent:
+ *
+ * **A pixel count.** It measures *displacement* rather than magnitude — a 1px
+ * token edit high on a page moves everything below it — and it is machine-bound
+ * on top of that. Two commits carrying `1,180px` and `2,180px` invite a
+ * comparison that is not valid between them, which is the same argument that
+ * keeps pixels out of the history store.
+ *
+ * **A rendered sentence.** Drift is carried as `token`, `from`, `to` and a step
+ * count, never as the phrasing today's reporter happened to use. Prose in a
+ * durable record freezes one wording forever and goes stale against the tool that
+ * writes the new one.
+ *
+ * **Anything derivable.** The accepted total is the entries' subjects plus the
+ * ungrouped count. Recording it as well would create two numbers that can
+ * disagree after a partial read, and no way to decide which is the record.
+ *
+ * What stays is what a later reader can still verify or act on: a
+ * content-addressed fingerprint they can pass straight back to `accept --shape`,
+ * the subject ids it landed in, what the shape reached, and the run and commit it
+ * all came from. `component` and `file` stay as *where it was then* — a rename
+ * makes them stale, and the fingerprint beside them does not.
+ *
+ * ## Version 1, and what may be added without a version 2
+ *
+ * A reader ignores keys it does not know, so a field added later is readable by
+ * readers that predate it. The version bumps only when the *meaning* of an
+ * existing field changes — that is the case where partly understanding a record
+ * is worse than refusing it, and refusing is what a version is for.
+ */
+/** One change, as it was accepted. */
+export interface ChangelogEntry {
+    /** The shape digest, as `accept --shape` and an ignore both take it. */
+    readonly fingerprint: string;
+    /**
+     * The component the semantic tier attributed this shape to.
+     *
+     * Absent means the shape was grouped by silhouette alone — the ephemeral and
+     * raster-only paths, where no document survived to name a cause. Surfaced
+     * rather than smoothed over, because a later reader asking *what changed in
+     * `Card`* must not be answered from a group that never named one.
+     */
+    readonly component?: string;
+    /** A source location for the component, when one was resolved. */
+    readonly file?: string;
+    /** Accepted subjects this shape landed in, in report order. */
+    readonly subjects: readonly string[];
+    /**
+     * Subjects the shape reached in the run, accepted or not.
+     *
+     * Equal to `subjects.length` in the ordinary case and larger whenever the
+     * command refused part of the cluster. The difference is the part of the change
+     * this baseline update did **not** take, and a record that dropped it would read
+     * as though the whole shape had been promoted.
+     */
+    readonly reached: number;
+    /**
+     * `true` when the semantic tier called this shape a cause somewhere.
+     *
+     * A claim the run made, recorded as the run's, because it is what the reviewer
+     * was shown when they approved. A later tier that would group the same pixels
+     * differently does not make this entry wrong; it makes it historical, which is
+     * what a changelog is.
+     */
+    readonly cause: boolean;
+}
+/** How the subjects to accept were chosen. */
+export type ChangelogSelection = 'named' | 'all' | 'shape';
+/**
+ * A token whose value moved, and how far it has drifted getting there.
+ *
+ * Four fields and no sentence. The report phrases this finding for a reviewer and
+ * phrases it well; storing that phrasing would preserve one release's wording in
+ * every commit written under it, and a reader in two years would be reading the
+ * output of a reporter nobody runs any more. The facts are what is durable, and
+ * whoever prints them can say it however they say it then.
+ */
+export interface ChangelogDrift {
+    readonly token: string;
+    readonly from: string;
+    readonly to: string;
+    /** Value changes behind it. One is not drift; this is never below two. */
+    readonly steps: number;
+}
+/**
+ * What one baseline update was.
+ *
+ * Drift sits on the record rather than on an entry, and that is a join that does
+ * not exist rather than a placement preference: drift is keyed by token and a
+ * cluster is keyed by fingerprint, and nothing in this project maps one to the
+ * other. It is a fact about the run, recorded at the level it is true at.
+ */
+export interface ChangelogRecord {
+    /** Bumped when the stored shape changes in a way an older reader would misread. */
+    readonly changelogVersion: 1;
+    /** The run whose candidates were promoted. */
+    readonly run: string;
+    /** The commit that run observed — not the commit this record lands in. */
+    readonly commit: string;
+    readonly at: string;
+    readonly project?: string;
+    /** What the run was comparing, in the author's words. */
+    readonly intent?: string;
+    /**
+     * Who accepted, when the surface that recorded it knows.
+     *
+     * Absent is not "nobody", for the same reason `Approval.by` is optional: the
+     * CLI runs on a machine and in CI, and has no identity to offer that would mean
+     * anything. A review service that does know one records it.
+     */
+    readonly by?: string;
+    /**
+     * How the subjects were chosen.
+     *
+     * Recorded because `--all` and a named subject are different events wearing one
+     * outcome. `--all` accepts changed subjects as well as new ones — unattended,
+     * that is baseline regeneration rather than review, and a reader who cannot
+     * tell the two apart is reading a record that launders one into the other.
+     */
+    readonly selection: ChangelogSelection;
+    /**
+     * Accepted subjects that carried no fingerprint anywhere.
+     *
+     * Counted, never folded into an entry. A run with no document behind its
+     * baseline produces regions with no shape, and inventing a group for them would
+     * report a change this record cannot describe as one it can.
+     */
+    readonly ungrouped: number;
+    readonly entries: readonly ChangelogEntry[];
+    readonly drift?: readonly ChangelogDrift[];
+}
+/** Why no record could be made. Never an empty record, which reads as "nothing changed". */
+export interface Unrecordable {
+    readonly because: string;
+}
+export interface ChangelogOptions {
+    /** The report the reviewer read, and the only source of what changed. */
+    readonly report: RunReport;
+    /** Subject ids this command actually promoted. */
+    readonly accepted: readonly string[];
+    /** How those subjects were chosen. See {@link ChangelogRecord.selection}. */
+    readonly selection: ChangelogSelection;
+    /** ISO 8601. Injected, because nothing in a record may come from a hidden clock. */
+    readonly at: string;
+    /** The project the record is scoped by, when the operator keeps one. */
+    readonly project?: string;
+    /** Who accepted. See {@link ChangelogRecord.by}. */
+    readonly by?: string;
+    /**
+     * Entries a caller formed itself, appended after the clustered ones in the
+     * order given.
+     *
+     * Region clustering is one producer of entries, not the definition of one. A
+     * change to an interface — an operation whose response lost a field, a named
+     * type reached from nine operations — is the same kind of fact this record
+     * exists to carry, and it has no rectangle. The alternative was for such a
+     * producer to hand `report.observations` a `RegionRecord` with four invented
+     * numbers in it, which would give `x`, `y`, `width` and `height` a second
+     * meaning and put a fabricated measurement into the one artifact nobody can
+     * go back and correct.
+     *
+     * Appended rather than merged, because merging would need a rule for two
+     * producers claiming one fingerprint, and there is no such rule: a fingerprint
+     * carries a domain tag inside its digest input (`shape/v1`, `mask/v1`, and
+     * whatever a third producer chooses), so two producers cannot collide unless
+     * one of them built its digest wrong — and quietly merging is how that stays
+     * hidden.
+     *
+     * `ungrouped` is untouched by these. It counts accepted subjects *this report's
+     * regions* could not group, and a producer that never looked at a region has
+     * nothing to say about it.
+     */
+    readonly entries?: readonly ChangelogEntry[];
+}
+/** `true` when a record was made, rather than a sentence saying why none was. */
+export declare function isRecorded(value: ChangelogRecord | Unrecordable): value is ChangelogRecord;
+/**
+ * Derive the record of one baseline update.
+ *
+ * Refuses in two cases, and both refusals are the same rule: an entry that cannot
+ * be joined to what produced it explains nothing. A report with no `run` names no
+ * build, and an acceptance with no subjects promoted nothing — writing either
+ * would leave a message in the log that a later reader has to decide how to
+ * discount.
+ */
+export declare function changelogOf(options: ChangelogOptions): ChangelogRecord | Unrecordable;
+//# sourceMappingURL=changelog.d.ts.map

package/dist/changelog.js

@@ -0,0 +1,96 @@
+import { clusterChanges } from './cluster.js';
+/** `true` when a record was made, rather than a sentence saying why none was. */
+export function isRecorded(value) {
+    return 'changelogVersion' in value;
+}
+/**
+ * Derive the record of one baseline update.
+ *
+ * Refuses in two cases, and both refusals are the same rule: an entry that cannot
+ * be joined to what produced it explains nothing. A report with no `run` names no
+ * build, and an acceptance with no subjects promoted nothing — writing either
+ * would leave a message in the log that a later reader has to decide how to
+ * discount.
+ */
+export function changelogOf(options) {
+    const { report, at, selection } = options;
+    const accepted = new Set(options.accepted);
+    if (accepted.size === 0) {
+        return {
+            because: 'nothing was accepted, so there is no baseline update to explain. A record written here ' +
+                'would say a change landed that did not',
+        };
+    }
+    if (report.run === undefined) {
+        return {
+            because: 'this report does not say which run produced it, so the record has nothing to point at. ' +
+                'Runs name themselves from `--run` and `--commit` or from the CI environment; an id ' +
+                'invented here would attribute a baseline to a build that never happened',
+        };
+    }
+    const clustering = clusterChanges(report.observations.filter((observation) => accepted.has(observation.subject)));
+    const reach = new Map(clusterChanges(report.observations).changes.map((change) => [
+        change.fingerprint,
+        change.subjects.length,
+    ]));
+    const entries = clustering.changes.map((change) => ({
+        fingerprint: change.fingerprint,
+        ...(change.component !== undefined ? { component: change.component } : {}),
+        ...(change.file !== undefined ? { file: change.file } : {}),
+        subjects: change.subjects,
+        reached: reach.get(change.fingerprint) ?? change.subjects.length,
+        cause: change.cause,
+    }));
+    // Checked here rather than trusted, because these did not come from clustering
+    // and nothing upstream of this function guarantees their shape.
+    //
+    // `reached < subjects.length` is the clause worth defending: it cannot happen,
+    // and it is the one that fails quietly if it does. Containment runs one way —
+    // a change reaches some set of subjects and `subjects` is that set intersected
+    // with what was accepted, and an intersection cannot exceed what it intersects.
+    // The case that looks like an exception is a shape spanning two documents where
+    // the operator accepts one of them, and that is `reached: 2, subjects: 1`,
+    // which is this check passing. Were it ever to happen, `describe` would print a
+    // bare count instead of `n/m` and a partial promotion would read as a whole one.
+    const given = options.entries ?? [];
+    const wrong = given.find((entry) => entry.fingerprint === '' || entry.subjects.length === 0 || entry.reached < entry.subjects.length);
+    if (wrong !== undefined) {
+        return {
+            because: 'an entry handed to `changelogOf` is not one: it has no fingerprint, no subjects, or ' +
+                `reached fewer subjects than it was promoted in (\`${wrong.fingerprint}\`). Refused here ` +
+                'rather than written, because a commit message is the one artifact nobody can go back and ' +
+                'correct, and `accept --shape` takes that fingerprint as an argument',
+        };
+    }
+    const drift = driftOf(report);
+    return {
+        changelogVersion: 1,
+        run: report.run.id,
+        commit: report.run.commit,
+        at,
+        ...(options.project !== undefined ? { project: options.project } : {}),
+        ...(report.intent !== undefined ? { intent: report.intent } : {}),
+        ...(options.by !== undefined ? { by: options.by } : {}),
+        selection,
+        ungrouped: clustering.ungrouped.length,
+        entries: [...entries, ...given],
+        ...(drift.length > 0 ? { drift } : {}),
+    };
+}
+function driftOf(report) {
+    return Object.entries(report.drift ?? {})
+        .map(([token, record]) => ({
+        token,
+        from: record.from,
+        to: record.to,
+        steps: record.steps,
+    }))
+        // Byte order rather than `localeCompare`, which is the right sort for a list
+        // being shown to a person and the wrong one for a list being serialised. This
+        // one goes verbatim into a commit message, and `localeCompare` orders by the
+        // machine's `LANG` — two runners accepting the same run would write different
+        // bytes for the same facts, which is exactly the machine-boundness this
+        // record refuses everywhere else.
+        .sort((a, b) => (a.token < b.token ? -1 : a.token > b.token ? 1 : 0));
+}
+//# sourceMappingURL=changelog.js.map

package/dist/changelog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../src/changelog.ts"],"names":[],"mappings":"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","sourcesContent":["import { clusterChanges } from './cluster.js';\nimport type { RunReport } from './format.js';\n\n/**\n * Why a baseline is what it is — written where the baseline is written.\n *\n * A baseline update happens in a run of its own: `variance accept` promotes the\n * candidates a reviewer looked at, and the artifact that lands is a directory of\n * PNGs, or a row in a review database. Both record *what* the new baseline is.\n * Neither records **what the change was**, and by the time anybody asks — a month\n * later, at the twelfth 2px approval — the report that could have said is gone\n * with the CI job that wrote it.\n *\n * So the explanation is written at the only moment it exists, into the same\n * artifact as the bytes it explains: a commit message where baselines are commits,\n * a row where they are rows. This module is the part neither of those owns — the\n * derivation from a report, and the encoding that survives the trip back.\n *\n * ## The unit is a change, not a screenshot\n *\n * One entry per **cluster** ([`cluster.ts`](./cluster.ts)), because that is\n * already this project's answer to the same question one level up: a token edit\n * across forty stories is one decision, and forty entries would reproduce exactly\n * the review problem clustering exists to solve. A changelog that logged\n * screenshots would be forty lines nobody reads, ending in the same place as a\n * commit message that says `regenerate baselines`.\n *\n * ## Only what was accepted, and only what the report already said\n *\n * The subjects on an entry are the intersection of the cluster with the subjects\n * this command actually promoted — never the cluster's own list. `accept --shape`\n * refuses by name any subject where something else also moved, and an entry that\n * copied the cluster would claim those too. What the shape *reached* is carried\n * as a count beside it, so the shortfall is visible rather than absent.\n *\n * Nothing here re-derives anything from bytes. The entry is built from the report\n * the reviewer read, which is what makes it evidence about a decision rather than\n * a second opinion about an image.\n *\n * ## What a record carries, and what it deliberately does not\n *\n * This outlives everything around it. The report is gone with the CI job, the\n * reviewer has left the project, the file has been renamed twice — and the record\n * is still in the log, being read by somebody who cannot check any of it. So a\n * field belongs here only if it will still mean the same thing then.\n *\n * Three that would not, and are absent:\n *\n * **A pixel count.** It measures *displacement* rather than magnitude — a 1px\n * token edit high on a page moves everything below it — and it is machine-bound\n * on top of that. Two commits carrying `1,180px` and `2,180px` invite a\n * comparison that is not valid between them, which is the same argument that\n * keeps pixels out of the history store.\n *\n * **A rendered sentence.** Drift is carried as `token`, `from`, `to` and a step\n * count, never as the phrasing today's reporter happened to use. Prose in a\n * durable record freezes one wording forever and goes stale against the tool that\n * writes the new one.\n *\n * **Anything derivable.** The accepted total is the entries' subjects plus the\n * ungrouped count. Recording it as well would create two numbers that can\n * disagree after a partial read, and no way to decide which is the record.\n *\n * What stays is what a later reader can still verify or act on: a\n * content-addressed fingerprint they can pass straight back to `accept --shape`,\n * the subject ids it landed in, what the shape reached, and the run and commit it\n * all came from. `component` and `file` stay as *where it was then* — a rename\n * makes them stale, and the fingerprint beside them does not.\n *\n * ## Version 1, and what may be added without a version 2\n *\n * A reader ignores keys it does not know, so a field added later is readable by\n * readers that predate it. The version bumps only when the *meaning* of an\n * existing field changes — that is the case where partly understanding a record\n * is worse than refusing it, and refusing is what a version is for.\n */\n\n/** One change, as it was accepted. */\nexport interface ChangelogEntry {\n  /** The shape digest, as `accept --shape` and an ignore both take it. */\n  readonly fingerprint: string;\n\n  /**\n   * The component the semantic tier attributed this shape to.\n   *\n   * Absent means the shape was grouped by silhouette alone — the ephemeral and\n   * raster-only paths, where no document survived to name a cause. Surfaced\n   * rather than smoothed over, because a later reader asking *what changed in\n   * `Card`* must not be answered from a group that never named one.\n   */\n  readonly component?: string;\n\n  /** A source location for the component, when one was resolved. */\n  readonly file?: string;\n\n  /** Accepted subjects this shape landed in, in report order. */\n  readonly subjects: readonly string[];\n\n  /**\n   * Subjects the shape reached in the run, accepted or not.\n   *\n   * Equal to `subjects.length` in the ordinary case and larger whenever the\n   * command refused part of the cluster. The difference is the part of the change\n   * this baseline update did **not** take, and a record that dropped it would read\n   * as though the whole shape had been promoted.\n   */\n  readonly reached: number;\n\n  /**\n   * `true` when the semantic tier called this shape a cause somewhere.\n   *\n   * A claim the run made, recorded as the run's, because it is what the reviewer\n   * was shown when they approved. A later tier that would group the same pixels\n   * differently does not make this entry wrong; it makes it historical, which is\n   * what a changelog is.\n   */\n  readonly cause: boolean;\n}\n\n/** How the subjects to accept were chosen. */\nexport type ChangelogSelection = 'named' | 'all' | 'shape';\n\n/**\n * A token whose value moved, and how far it has drifted getting there.\n *\n * Four fields and no sentence. The report phrases this finding for a reviewer and\n * phrases it well; storing that phrasing would preserve one release's wording in\n * every commit written under it, and a reader in two years would be reading the\n * output of a reporter nobody runs any more. The facts are what is durable, and\n * whoever prints them can say it however they say it then.\n */\nexport interface ChangelogDrift {\n  readonly token: string;\n  readonly from: string;\n  readonly to: string;\n  /** Value changes behind it. One is not drift; this is never below two. */\n  readonly steps: number;\n}\n\n/**\n * What one baseline update was.\n *\n * Drift sits on the record rather than on an entry, and that is a join that does\n * not exist rather than a placement preference: drift is keyed by token and a\n * cluster is keyed by fingerprint, and nothing in this project maps one to the\n * other. It is a fact about the run, recorded at the level it is true at.\n */\nexport interface ChangelogRecord {\n  /** Bumped when the stored shape changes in a way an older reader would misread. */\n  readonly changelogVersion: 1;\n  /** The run whose candidates were promoted. */\n  readonly run: string;\n  /** The commit that run observed — not the commit this record lands in. */\n  readonly commit: string;\n  readonly at: string;\n  readonly project?: string;\n  /** What the run was comparing, in the author's words. */\n  readonly intent?: string;\n\n  /**\n   * Who accepted, when the surface that recorded it knows.\n   *\n   * Absent is not \"nobody\", for the same reason `Approval.by` is optional: the\n   * CLI runs on a machine and in CI, and has no identity to offer that would mean\n   * anything. A review service that does know one records it.\n   */\n  readonly by?: string;\n\n  /**\n   * How the subjects were chosen.\n   *\n   * Recorded because `--all` and a named subject are different events wearing one\n   * outcome. `--all` accepts changed subjects as well as new ones — unattended,\n   * that is baseline regeneration rather than review, and a reader who cannot\n   * tell the two apart is reading a record that launders one into the other.\n   */\n  readonly selection: ChangelogSelection;\n\n  /**\n   * Accepted subjects that carried no fingerprint anywhere.\n   *\n   * Counted, never folded into an entry. A run with no document behind its\n   * baseline produces regions with no shape, and inventing a group for them would\n   * report a change this record cannot describe as one it can.\n   */\n  readonly ungrouped: number;\n\n  readonly entries: readonly ChangelogEntry[];\n  readonly drift?: readonly ChangelogDrift[];\n}\n\n/** Why no record could be made. Never an empty record, which reads as \"nothing changed\". */\nexport interface Unrecordable {\n  readonly because: string;\n}\n\nexport interface ChangelogOptions {\n  /** The report the reviewer read, and the only source of what changed. */\n  readonly report: RunReport;\n  /** Subject ids this command actually promoted. */\n  readonly accepted: readonly string[];\n  /** How those subjects were chosen. See {@link ChangelogRecord.selection}. */\n  readonly selection: ChangelogSelection;\n  /** ISO 8601. Injected, because nothing in a record may come from a hidden clock. */\n  readonly at: string;\n  /** The project the record is scoped by, when the operator keeps one. */\n  readonly project?: string;\n  /** Who accepted. See {@link ChangelogRecord.by}. */\n  readonly by?: string;\n  /**\n   * Entries a caller formed itself, appended after the clustered ones in the\n   * order given.\n   *\n   * Region clustering is one producer of entries, not the definition of one. A\n   * change to an interface — an operation whose response lost a field, a named\n   * type reached from nine operations — is the same kind of fact this record\n   * exists to carry, and it has no rectangle. The alternative was for such a\n   * producer to hand `report.observations` a `RegionRecord` with four invented\n   * numbers in it, which would give `x`, `y`, `width` and `height` a second\n   * meaning and put a fabricated measurement into the one artifact nobody can\n   * go back and correct.\n   *\n   * Appended rather than merged, because merging would need a rule for two\n   * producers claiming one fingerprint, and there is no such rule: a fingerprint\n   * carries a domain tag inside its digest input (`shape/v1`, `mask/v1`, and\n   * whatever a third producer chooses), so two producers cannot collide unless\n   * one of them built its digest wrong — and quietly merging is how that stays\n   * hidden.\n   *\n   * `ungrouped` is untouched by these. It counts accepted subjects *this report's\n   * regions* could not group, and a producer that never looked at a region has\n   * nothing to say about it.\n   */\n  readonly entries?: readonly ChangelogEntry[];\n}\n\n/** `true` when a record was made, rather than a sentence saying why none was. */\nexport function isRecorded(value: ChangelogRecord | Unrecordable): value is ChangelogRecord {\n  return 'changelogVersion' in value;\n}\n\n/**\n * Derive the record of one baseline update.\n *\n * Refuses in two cases, and both refusals are the same rule: an entry that cannot\n * be joined to what produced it explains nothing. A report with no `run` names no\n * build, and an acceptance with no subjects promoted nothing — writing either\n * would leave a message in the log that a later reader has to decide how to\n * discount.\n */\nexport function changelogOf(options: ChangelogOptions): ChangelogRecord | Unrecordable {\n  const { report, at, selection } = options;\n  const accepted = new Set(options.accepted);\n\n  if (accepted.size === 0) {\n    return {\n      because:\n        'nothing was accepted, so there is no baseline update to explain. A record written here ' +\n        'would say a change landed that did not',\n    };\n  }\n  if (report.run === undefined) {\n    return {\n      because:\n        'this report does not say which run produced it, so the record has nothing to point at. ' +\n        'Runs name themselves from `--run` and `--commit` or from the CI environment; an id ' +\n        'invented here would attribute a baseline to a build that never happened',\n    };\n  }\n\n  const clustering = clusterChanges(\n    report.observations.filter((observation) => accepted.has(observation.subject)),\n  );\n  const reach = new Map(\n    clusterChanges(report.observations).changes.map((change) => [\n      change.fingerprint,\n      change.subjects.length,\n    ]),\n  );\n\n  const entries = clustering.changes.map(\n    (change): ChangelogEntry => ({\n      fingerprint: change.fingerprint,\n      ...(change.component !== undefined ? { component: change.component } : {}),\n      ...(change.file !== undefined ? { file: change.file } : {}),\n      subjects: change.subjects,\n      reached: reach.get(change.fingerprint) ?? change.subjects.length,\n      cause: change.cause,\n    }),\n  );\n\n  // Checked here rather than trusted, because these did not come from clustering\n  // and nothing upstream of this function guarantees their shape.\n  //\n  // `reached < subjects.length` is the clause worth defending: it cannot happen,\n  // and it is the one that fails quietly if it does. Containment runs one way —\n  // a change reaches some set of subjects and `subjects` is that set intersected\n  // with what was accepted, and an intersection cannot exceed what it intersects.\n  // The case that looks like an exception is a shape spanning two documents where\n  // the operator accepts one of them, and that is `reached: 2, subjects: 1`,\n  // which is this check passing. Were it ever to happen, `describe` would print a\n  // bare count instead of `n/m` and a partial promotion would read as a whole one.\n  const given = options.entries ?? [];\n  const wrong = given.find(\n    (entry) =>\n      entry.fingerprint === '' || entry.subjects.length === 0 || entry.reached < entry.subjects.length,\n  );\n  if (wrong !== undefined) {\n    return {\n      because:\n        'an entry handed to `changelogOf` is not one: it has no fingerprint, no subjects, or ' +\n        `reached fewer subjects than it was promoted in (\\`${wrong.fingerprint}\\`). Refused here ` +\n        'rather than written, because a commit message is the one artifact nobody can go back and ' +\n        'correct, and `accept --shape` takes that fingerprint as an argument',\n    };\n  }\n\n  const drift = driftOf(report);\n\n  return {\n    changelogVersion: 1,\n    run: report.run.id,\n    commit: report.run.commit,\n    at,\n    ...(options.project !== undefined ? { project: options.project } : {}),\n    ...(report.intent !== undefined ? { intent: report.intent } : {}),\n    ...(options.by !== undefined ? { by: options.by } : {}),\n    selection,\n    ungrouped: clustering.ungrouped.length,\n    entries: [...entries, ...given],\n    ...(drift.length > 0 ? { drift } : {}),\n  };\n}\n\nfunction driftOf(report: RunReport): readonly ChangelogDrift[] {\n  return Object.entries(report.drift ?? {})\n    .map(([token, record]) => ({\n      token,\n      from: record.from,\n      to: record.to,\n      steps: record.steps,\n    }))\n    // Byte order rather than `localeCompare`, which is the right sort for a list\n    // being shown to a person and the wrong one for a list being serialised. This\n    // one goes verbatim into a commit message, and `localeCompare` orders by the\n    // machine's `LANG` — two runners accepting the same run would write different\n    // bytes for the same facts, which is exactly the machine-boundness this\n    // record refuses everywhere else.\n    .sort((a, b) => (a.token < b.token ? -1 : a.token > b.token ? 1 : 0));\n}\n"]}

package/dist/cluster.d.ts

@@ -0,0 +1,112 @@
+import type { ObservationRecord } from './format.js';
+/**
+ * A run's changes, grouped into the *distinct things that happened*.
+ *
+ * ## The unit of review is wrong by default
+ *
+ * Every tool in this category hands a reviewer a list of screenshots, and a
+ * reviewer's actual question is not "is this screenshot acceptable". It is *what
+ * changed, and how many places did it land*. A design-token edit that touches 40
+ * stories is one decision presented as forty, and the fortieth is approved
+ * without being looked at — which is the mechanism by which large suites stop
+ * being reviewed at all.
+ *
+ * Argos groups by the shape of the pixel diff and calls the group a **change**,
+ * ranked by recurrence
+ * ([test page](https://argos-ci.com/docs/learn/reliability-and-flakiness/test-page.md)).
+ * Applitools clusters by diff-region shape so one accept propagates across the
+ * batch. This project has had the *fingerprints* since 2026-08-05 and printed
+ * them one region at a time — [`comparison.md`](../../../docs/comparison.md)
+ * states the gap in as many words: they group the batch for you, and here the
+ * operator copies one digest out of a report.
+ *
+ * This is the grouping. It needs nothing new: a fingerprint is already on every
+ * region, and it already carries the component responsible, so a cluster is a
+ * `groupBy` and an ordering.
+ *
+ * ## Why the fingerprint is better than the one it is modelled on
+ *
+ * `mask-fingerprint` hashes the *silhouette* of a red diff mask — bounding box,
+ * dilated, resampled onto a 16×16 grid, density quantized to four buckets. That
+ * is translation- and scale-invariant, which is the point, and it is also blind
+ * to what changed: two different edits occupying the same box collide, and an
+ * ignore scoped to one of them silences the other. Their own docs concede a
+ * version of this while a neighbouring page claims it cannot happen.
+ *
+ * The semantic fingerprint here is built from the kind of root, the multiset of
+ * delta shapes, **and the component responsible**. So the same-looking change in
+ * `Avatar` and in `Badge` are different clusters, and accepting one does not
+ * reach the other. Where no document survived, the pixel fingerprint is the
+ * fallback and inherits the weaker guarantee — which is a reason to keep the
+ * document, not a reason to pretend the two are equal.
+ */
+export interface Change {
+    /** The shape digest. What `variance accept --shape` and an ignore both take. */
+    readonly fingerprint: string;
+    /**
+     * The component this shape was attributed to, when the semantic tier named one.
+     *
+     * The field that makes a cluster safe to act on in bulk. Absent means the
+     * change is grouped by silhouette alone, and a bulk decision on it is the
+     * weaker claim — surfaced rather than smoothed over.
+     */
+    readonly component?: string;
+    /** A source location for the component, when one was resolved. */
+    readonly file?: string;
+    /** Subject ids where this shape appears at all, in report order. */
+    readonly subjects: readonly string[];
+    /**
+     * Subjects where this shape is the **whole** change.
+     *
+     * The set a single decision can settle. Everywhere else, something the shape
+     * does not name also moved, so accepting the shape there would promote an
+     * unreviewed difference alongside a reviewed one — which is the exact way a
+     * bulk-accept feature turns a gate into a recorder. `accept --shape` already
+     * refuses those by name; this is the same distinction, computed before the
+     * operator commits to anything.
+     */
+    readonly settles: readonly string[];
+    /** Regions this shape accounts for, summed. */
+    readonly pixels: number;
+    /** `true` when the semantic tier called this shape a cause somewhere. */
+    readonly cause: boolean;
+}
+export interface Clustering {
+    /** Distinct changes, most widespread first. */
+    readonly changes: readonly Change[];
+    /**
+     * Subjects that changed and produced no fingerprint anywhere.
+     *
+     * Never folded into a catch-all cluster. A run with no document to compare
+     * against — the ephemeral mode, or a raster-only path — produces regions with
+     * no shape, and grouping those together would invent a "change" that is
+     * really the absence of one. Counting them separately is what keeps the
+     * headline honest: *N subjects, M changes, and K we could not group*.
+     */
+    readonly ungrouped: readonly string[];
+}
+/**
+ * Group a run's changed subjects by what happened to them.
+ *
+ * Ordered by how many subjects a change *settles*, then by how many it touches,
+ * then by pixels, then by fingerprint. The first key is the useful one: it ranks
+ * by how much of the review one decision would finish, which is the question the
+ * reviewer is actually asking. Ties break deterministically so two runs over the
+ * same report print the same order — a docket whose ordering wobbles is one
+ * nobody can diff.
+ *
+ * `ignored` observations are excluded along with the green ones. An absorbed
+ * difference is not a change awaiting a decision; it is a decision already made,
+ * and it is accounted for in the ignore register where the question *what did
+ * this rule absorb* can still be asked.
+ */
+export declare function clusterChanges(observations: readonly ObservationRecord[]): Clustering;
+/**
+ * The clustering as the two sentences a reviewer needs before anything else.
+ *
+ * "40 subjects changed" is a workload. "40 subjects changed, and they are 3
+ * changes" is a plan — and the difference between those two sentences is most of
+ * what this module is for.
+ */
+export declare function describeClustering(clustering: Clustering, changed: number): string;
+//# sourceMappingURL=cluster.d.ts.map

package/dist/cluster.js

@@ -0,0 +1,109 @@
+/**
+ * Group a run's changed subjects by what happened to them.
+ *
+ * Ordered by how many subjects a change *settles*, then by how many it touches,
+ * then by pixels, then by fingerprint. The first key is the useful one: it ranks
+ * by how much of the review one decision would finish, which is the question the
+ * reviewer is actually asking. Ties break deterministically so two runs over the
+ * same report print the same order — a docket whose ordering wobbles is one
+ * nobody can diff.
+ *
+ * `ignored` observations are excluded along with the green ones. An absorbed
+ * difference is not a change awaiting a decision; it is a decision already made,
+ * and it is accounted for in the ignore register where the question *what did
+ * this rule absorb* can still be asked.
+ */
+export function clusterChanges(observations) {
+    const byFingerprint = new Map();
+    const ungrouped = [];
+    for (const observation of observations) {
+        if (observation.verdict !== 'changed')
+            continue;
+        const fingerprints = new Set(observation.regions
+            .map((region) => region.fingerprint)
+            .filter((fingerprint) => fingerprint !== undefined));
+        if (fingerprints.size === 0) {
+            ungrouped.push(observation.subject);
+            continue;
+        }
+        for (const fingerprint of fingerprints) {
+            const regions = observation.regions.filter((region) => region.fingerprint === fingerprint);
+            const entry = byFingerprint.get(fingerprint) ?? blank(fingerprint);
+            name(entry, regions);
+            entry.subjects.push(observation.subject);
+            // The whole change exactly when no region of this subject carries a
+            // *different* shape. A region with no fingerprint counts against it: we
+            // cannot say a shape explains a difference we could not name.
+            if (observation.regions.every((region) => region.fingerprint === fingerprint)) {
+                entry.settles.push(observation.subject);
+            }
+            entry.pixels += regions.reduce((total, region) => total + region.pixels, 0);
+            entry.cause ||= regions.some((region) => region.cause);
+            byFingerprint.set(fingerprint, entry);
+        }
+    }
+    const changes = [...byFingerprint.values()]
+        .map((entry) => ({
+        fingerprint: entry.fingerprint,
+        ...(entry.component !== undefined ? { component: entry.component } : {}),
+        ...(entry.file !== undefined ? { file: entry.file } : {}),
+        subjects: entry.subjects,
+        settles: entry.settles,
+        pixels: entry.pixels,
+        cause: entry.cause,
+    }))
+        .sort((a, b) => b.settles.length - a.settles.length ||
+        b.subjects.length - a.subjects.length ||
+        b.pixels - a.pixels ||
+        (a.fingerprint < b.fingerprint ? -1 : a.fingerprint > b.fingerprint ? 1 : 0));
+    return { changes, ungrouped };
+}
+function blank(fingerprint) {
+    return { fingerprint, subjects: [], settles: [], pixels: 0, cause: false };
+}
+/**
+ * Adopt a component and a file from the first region in the cluster that has
+ * them, wherever in the run that turns out to be.
+ *
+ * Filling a gap, not resolving a disagreement. A semantic fingerprint already
+ * *contains* the cause, so two regions sharing one agree about the component by
+ * construction — which means an absent component is a component that was not
+ * resolved *there*, and taking it from a sibling adds information rather than
+ * choosing between claims. Doing it only on the first subject seen was the first
+ * draft, and it made the answer depend on report order.
+ *
+ * A pixel fingerprint contains no cause, so no region in that cluster names one
+ * and the field stays absent — the honest report of a group formed by silhouette
+ * alone, which must not borrow a component from a neighbour and start looking
+ * like the stronger kind of claim.
+ */
+function name(entry, regions) {
+    if (entry.component !== undefined)
+        return;
+    const named = regions.find((region) => region.component !== undefined);
+    if (named === undefined)
+        return;
+    entry.component = named.component;
+    if (named.file !== undefined)
+        entry.file = named.file;
+}
+/**
+ * The clustering as the two sentences a reviewer needs before anything else.
+ *
+ * "40 subjects changed" is a workload. "40 subjects changed, and they are 3
+ * changes" is a plan — and the difference between those two sentences is most of
+ * what this module is for.
+ */
+export function describeClustering(clustering, changed) {
+    const { changes, ungrouped } = clustering;
+    if (changed === 0)
+        return 'nothing changed';
+    if (changes.length === 0) {
+        return `${changed} subject(s) changed, and none of them could be grouped`;
+    }
+    const settled = changes.filter((change) => change.settles.length > 0).length;
+    return (`${changed} subject(s) changed, and they are ${changes.length} distinct change(s) — ` +
+        `${settled} of which can be decided in one action` +
+        (ungrouped.length > 0 ? `; ${ungrouped.length} could not be grouped` : ''));
+}
+//# sourceMappingURL=cluster.js.map

package/dist/cluster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.js","sourceRoot":"","sources":["../src/cluster.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ObservationRecord, RegionRecord } from './format.js';\n\n/**\n * A run's changes, grouped into the *distinct things that happened*.\n *\n * ## The unit of review is wrong by default\n *\n * Every tool in this category hands a reviewer a list of screenshots, and a\n * reviewer's actual question is not \"is this screenshot acceptable\". It is *what\n * changed, and how many places did it land*. A design-token edit that touches 40\n * stories is one decision presented as forty, and the fortieth is approved\n * without being looked at — which is the mechanism by which large suites stop\n * being reviewed at all.\n *\n * Argos groups by the shape of the pixel diff and calls the group a **change**,\n * ranked by recurrence\n * ([test page](https://argos-ci.com/docs/learn/reliability-and-flakiness/test-page.md)).\n * Applitools clusters by diff-region shape so one accept propagates across the\n * batch. This project has had the *fingerprints* since 2026-08-05 and printed\n * them one region at a time — [`comparison.md`](../../../docs/comparison.md)\n * states the gap in as many words: they group the batch for you, and here the\n * operator copies one digest out of a report.\n *\n * This is the grouping. It needs nothing new: a fingerprint is already on every\n * region, and it already carries the component responsible, so a cluster is a\n * `groupBy` and an ordering.\n *\n * ## Why the fingerprint is better than the one it is modelled on\n *\n * `mask-fingerprint` hashes the *silhouette* of a red diff mask — bounding box,\n * dilated, resampled onto a 16×16 grid, density quantized to four buckets. That\n * is translation- and scale-invariant, which is the point, and it is also blind\n * to what changed: two different edits occupying the same box collide, and an\n * ignore scoped to one of them silences the other. Their own docs concede a\n * version of this while a neighbouring page claims it cannot happen.\n *\n * The semantic fingerprint here is built from the kind of root, the multiset of\n * delta shapes, **and the component responsible**. So the same-looking change in\n * `Avatar` and in `Badge` are different clusters, and accepting one does not\n * reach the other. Where no document survived, the pixel fingerprint is the\n * fallback and inherits the weaker guarantee — which is a reason to keep the\n * document, not a reason to pretend the two are equal.\n */\n\nexport interface Change {\n  /** The shape digest. What `variance accept --shape` and an ignore both take. */\n  readonly fingerprint: string;\n\n  /**\n   * The component this shape was attributed to, when the semantic tier named one.\n   *\n   * The field that makes a cluster safe to act on in bulk. Absent means the\n   * change is grouped by silhouette alone, and a bulk decision on it is the\n   * weaker claim — surfaced rather than smoothed over.\n   */\n  readonly component?: string;\n\n  /** A source location for the component, when one was resolved. */\n  readonly file?: string;\n\n  /** Subject ids where this shape appears at all, in report order. */\n  readonly subjects: readonly string[];\n\n  /**\n   * Subjects where this shape is the **whole** change.\n   *\n   * The set a single decision can settle. Everywhere else, something the shape\n   * does not name also moved, so accepting the shape there would promote an\n   * unreviewed difference alongside a reviewed one — which is the exact way a\n   * bulk-accept feature turns a gate into a recorder. `accept --shape` already\n   * refuses those by name; this is the same distinction, computed before the\n   * operator commits to anything.\n   */\n  readonly settles: readonly string[];\n\n  /** Regions this shape accounts for, summed. */\n  readonly pixels: number;\n\n  /** `true` when the semantic tier called this shape a cause somewhere. */\n  readonly cause: boolean;\n}\n\nexport interface Clustering {\n  /** Distinct changes, most widespread first. */\n  readonly changes: readonly Change[];\n\n  /**\n   * Subjects that changed and produced no fingerprint anywhere.\n   *\n   * Never folded into a catch-all cluster. A run with no document to compare\n   * against — the ephemeral mode, or a raster-only path — produces regions with\n   * no shape, and grouping those together would invent a \"change\" that is\n   * really the absence of one. Counting them separately is what keeps the\n   * headline honest: *N subjects, M changes, and K we could not group*.\n   */\n  readonly ungrouped: readonly string[];\n}\n\n/**\n * Group a run's changed subjects by what happened to them.\n *\n * Ordered by how many subjects a change *settles*, then by how many it touches,\n * then by pixels, then by fingerprint. The first key is the useful one: it ranks\n * by how much of the review one decision would finish, which is the question the\n * reviewer is actually asking. Ties break deterministically so two runs over the\n * same report print the same order — a docket whose ordering wobbles is one\n * nobody can diff.\n *\n * `ignored` observations are excluded along with the green ones. An absorbed\n * difference is not a change awaiting a decision; it is a decision already made,\n * and it is accounted for in the ignore register where the question *what did\n * this rule absorb* can still be asked.\n */\nexport function clusterChanges(observations: readonly ObservationRecord[]): Clustering {\n  const byFingerprint = new Map<string, Mutable>();\n  const ungrouped: string[] = [];\n\n  for (const observation of observations) {\n    if (observation.verdict !== 'changed') continue;\n\n    const fingerprints = new Set(\n      observation.regions\n        .map((region) => region.fingerprint)\n        .filter((fingerprint): fingerprint is string => fingerprint !== undefined),\n    );\n\n    if (fingerprints.size === 0) {\n      ungrouped.push(observation.subject);\n      continue;\n    }\n\n    for (const fingerprint of fingerprints) {\n      const regions = observation.regions.filter((region) => region.fingerprint === fingerprint);\n      const entry = byFingerprint.get(fingerprint) ?? blank(fingerprint);\n      name(entry, regions);\n\n      entry.subjects.push(observation.subject);\n      // The whole change exactly when no region of this subject carries a\n      // *different* shape. A region with no fingerprint counts against it: we\n      // cannot say a shape explains a difference we could not name.\n      if (observation.regions.every((region) => region.fingerprint === fingerprint)) {\n        entry.settles.push(observation.subject);\n      }\n      entry.pixels += regions.reduce((total, region) => total + region.pixels, 0);\n      entry.cause ||= regions.some((region) => region.cause);\n\n      byFingerprint.set(fingerprint, entry);\n    }\n  }\n\n  const changes = [...byFingerprint.values()]\n    .map(\n      (entry): Change => ({\n        fingerprint: entry.fingerprint,\n        ...(entry.component !== undefined ? { component: entry.component } : {}),\n        ...(entry.file !== undefined ? { file: entry.file } : {}),\n        subjects: entry.subjects,\n        settles: entry.settles,\n        pixels: entry.pixels,\n        cause: entry.cause,\n      }),\n    )\n    .sort(\n      (a, b) =>\n        b.settles.length - a.settles.length ||\n        b.subjects.length - a.subjects.length ||\n        b.pixels - a.pixels ||\n        (a.fingerprint < b.fingerprint ? -1 : a.fingerprint > b.fingerprint ? 1 : 0),\n    );\n\n  return { changes, ungrouped };\n}\n\ninterface Mutable {\n  readonly fingerprint: string;\n  component?: string;\n  file?: string;\n  readonly subjects: string[];\n  readonly settles: string[];\n  pixels: number;\n  cause: boolean;\n}\n\nfunction blank(fingerprint: string): Mutable {\n  return { fingerprint, subjects: [], settles: [], pixels: 0, cause: false };\n}\n\n/**\n * Adopt a component and a file from the first region in the cluster that has\n * them, wherever in the run that turns out to be.\n *\n * Filling a gap, not resolving a disagreement. A semantic fingerprint already\n * *contains* the cause, so two regions sharing one agree about the component by\n * construction — which means an absent component is a component that was not\n * resolved *there*, and taking it from a sibling adds information rather than\n * choosing between claims. Doing it only on the first subject seen was the first\n * draft, and it made the answer depend on report order.\n *\n * A pixel fingerprint contains no cause, so no region in that cluster names one\n * and the field stays absent — the honest report of a group formed by silhouette\n * alone, which must not borrow a component from a neighbour and start looking\n * like the stronger kind of claim.\n */\nfunction name(entry: Mutable, regions: readonly RegionRecord[]): void {\n  if (entry.component !== undefined) return;\n\n  const named = regions.find(\n    (region): region is RegionRecord & { component: string } => region.component !== undefined,\n  );\n  if (named === undefined) return;\n\n  entry.component = named.component;\n  if (named.file !== undefined) entry.file = named.file;\n}\n\n/**\n * The clustering as the two sentences a reviewer needs before anything else.\n *\n * \"40 subjects changed\" is a workload. \"40 subjects changed, and they are 3\n * changes\" is a plan — and the difference between those two sentences is most of\n * what this module is for.\n */\nexport function describeClustering(clustering: Clustering, changed: number): string {\n  const { changes, ungrouped } = clustering;\n\n  if (changed === 0) return 'nothing changed';\n  if (changes.length === 0) {\n    return `${changed} subject(s) changed, and none of them could be grouped`;\n  }\n\n  const settled = changes.filter((change) => change.settles.length > 0).length;\n\n  return (\n    `${changed} subject(s) changed, and they are ${changes.length} distinct change(s) — ` +\n    `${settled} of which can be decided in one action` +\n    (ungrouped.length > 0 ? `; ${ungrouped.length} could not be grouped` : '')\n  );\n}\n"]}