@variance-authority/report 0.1.0

package/dist/format.d.ts

@@ -0,0 +1,444 @@
+import type { AccessibilitySnapshot, ComponentBands, RenderIdentity } from '@variance-authority/core';
+import type { FindingRecord } from './finding-record.js';
+import type { CompositionReport } from './composition.js';
+import type { IgnoreLedger, SensitivityLedger } from './declarations.js';
+import type { ReachReport } from './reach.js';
+import type { PresentationSignalRecord } from './presentation-record.js';
+import type { ChurnRecord, DriftRecord, FlakinessRecord } from './history-records.js';
+import type { VariationRecord } from './variation.js';
+/**
+ * The run report — the artifact an agent actually reads.
+ *
+ * The observation pipeline produces values in memory and then the process ends.
+ * That is fine for a test and useless for the thing this is for: an agent asked
+ * to *fix* something arrives afterwards, in a different process, with no access
+ * to whatever was in scope when the change was sensed.
+ *
+ * So the run writes one of these, and the MCP tools query it. Keeping the file
+ * the contract — rather than having the tools re-run the pipeline — is what makes
+ * the two halves independent: a run can be produced by CI on a pinned machine
+ * and queried on a laptop, and the tools can be tested against a report nobody
+ * rendered.
+ *
+ * Deliberately not the raw `Observation`. That carries a `ChangeMask` and base64
+ * PNGs, which would make a 300-subject report hundreds of megabytes of data no
+ * reader ever looks at. What is kept is what a sentence needs.
+ */
+export interface RunReport {
+    readonly runVersion: 1;
+    /** ISO 8601. Supplied by the caller — nothing in this package reads a clock. */
+    readonly at: string;
+    readonly identity: RenderIdentity;
+    readonly retention: 'durable' | 'ephemeral';
+    /** What the run was comparing, in the author's words. Carried into every answer. */
+    readonly intent?: string;
+    readonly observations: readonly ObservationRecord[];
+    /**
+     * Subjects the run planned and has no observation for. **Absent is not empty.**
+     *
+     * Lives here rather than only on the CLI's own superset because the answers an
+     * agent gets are computed from *this* type, and a field the tools cannot see is
+     * a field the tools cannot be contradicted by. A run that planned 300 subjects,
+     * failed on 50 and found the other 250 unchanged produces a report in which
+     * every observation is clean and the conclusion "nothing to review" is false;
+     * the only thing that can refuse that sentence is this list.
+     *
+     * Optional because a report written by something other than `variance run` will
+     * not carry it, and the difference has to survive: `undefined` means the writer
+     * never said what it skipped, which is not the same claim as "it skipped
+     * nothing" and must never be printed as one. Costs every reader an extra state
+     * to handle, which is cheaper than the state it prevents collapsing.
+     */
+    readonly notObserved?: readonly NotObserved[];
+    /**
+     * Which run this was, and at which commit.
+     *
+     * Present when the run could name itself — `--run` and `--commit`, or the pair
+     * the surrounding CI exports. Absent on a laptop, and absent is not a default
+     * anybody may fill in: an invented id cannot be joined back to anything that
+     * shipped, and it would silently become a denominator.
+     *
+     * Carried in the artifact because acceptance happens *later*, in a different
+     * command reading this file. A reviewer approves a subject **in a build**, and
+     * without the build's id there is nothing for that approval to point at — which
+     * is why every observation a run records is unapproved and why drift summed
+     * nothing until this field existed.
+     */
+    readonly run?: {
+        readonly id: string;
+        readonly commit: string;
+    };
+    /**
+     * What a history record already knew about the subjects this run found
+     * unstable, keyed by subject.
+     *
+     * Two readings put a *floor* under flakiness and can never put a ceiling on it
+     * (`ObservationRecord.unstable`). This is the other instrument: how often the
+     * subject has read differently before, and — the part that decides what anybody
+     * does next — whether it has happened since the last few sweeps. "Unstable in 6
+     * of 20" and "6 times, none in the last 9 sweeps" are opposite instructions.
+     *
+     * It lives on this type rather than only on the CLI's superset for the reason
+     * `notObserved` does: the answers an agent gets are computed from *this* type,
+     * and a field the tools cannot see is a field they cannot be contradicted by.
+     *
+     * **Absent is not "this has never happened."** It means no store answered —
+     * because none is configured, or because one could not be reached — and the
+     * reason is in `warnings` where it can be printed. A surface that renders a
+     * missing entry as "first occurrence" has invented the one fact this record
+     * exists to supply.
+     */
+    readonly flakiness?: Readonly<Record<string, FlakinessRecord>>;
+    /**
+     * How often each component this run named as a cause has changed before,
+     * keyed by component.
+     *
+     * The instrument a comparison structurally cannot be. A diff answers *what
+     * moved*; this answers *how often this moves*, which is the difference between
+     * "review this" and "this component has been rewritten eleven times this
+     * quarter and nobody has asked why". No threshold reaches it, because the
+     * quantity is a count across runs and a one-run-at-a-time tool keeps none.
+     *
+     * **Absent is not "it has never changed."** It means no store answered, and the
+     * reason is in `warnings`.
+     */
+    readonly churn?: Readonly<Record<string, ChurnRecord>>;
+    /**
+     * Design tokens whose value moved in this run, and what they have drifted to
+     * across every approved change in the window.
+     *
+     * The finding no comparison reaches. A button gains 2px, eleven times, each
+     * approved correctly by somebody looking at one diff — and the 22px is a number
+     * no review ever saw, because the quantity that would catch it is a sum and a
+     * single run holds none. Present only for tokens that moved *here*, so it is
+     * empty on almost every run and is the whole story on the one where it is not.
+     */
+    readonly drift?: Readonly<Record<string, DriftRecord>>;
+    /**
+     * The suite compared to *itself*, at this one commit — see
+     * [`composition.ts`](./composition.ts).
+     *
+     * The only section of this report with no baseline in it. Absent when the
+     * collection produced no semantic snapshots to join, which is a real state and
+     * not an empty graph: a suite that shares nothing and a suite nobody could ask
+     * are different claims.
+     */
+    readonly composition?: CompositionReport;
+    /**
+     * Subjects that declared themselves variations of another subject, and what
+     * the variation *is*.
+     *
+     * The other section with no baseline in it, and the answer to a question the
+     * category has never had one for: a story added behind a feature flag is a new
+     * subject, so its first run is `new`, its diff is empty, and what the flag
+     * actually does to the page is visible only by opening two pictures side by
+     * side. A subject that names a parent is compared against that parent *in the
+     * same run*, so the difference is a value with an identity — and the identity
+     * is what lets a reviewer be told that the difference is the one they already
+     * approved, on a run where both subjects changed.
+     *
+     * Every declared variation appears, including the ones that could not be
+     * computed: a parent nobody observed is a variation that was not measured, and
+     * dropping it would make a broken link look like a subject with nothing to say.
+     *
+     * Absent when no subject in the run declared a parent. Never present and empty.
+     */
+    readonly variations?: readonly VariationRecord[];
+    /**
+     * What this commit reaches, from the diff and the file graph — see
+     * [`reach.ts`](./reach.ts).
+     *
+     * The third axis. `observations` is a subject against its past, `composition`
+     * is the suite against itself, and this is the suite against the *edit* — which
+     * components the changed files can possibly have moved, and by which chain.
+     * Crossed against the verdicts, it is what lets a report say that an edit
+     * reached a subject and changed nothing, or that a subject moved with nothing
+     * in the commit reaching it.
+     *
+     * Absent when the run was given no ref to diff against, or when no file graph
+     * was scanned. Present with `subjects` absent is the run saying it *has* a diff
+     * and could not attribute it, which is a different fact and a louder one.
+     */
+    readonly reach?: ReachReport;
+    /**
+     * What this run narrowed by, and what it could have narrowed by.
+     *
+     * A run that observed everything is the default and is not a failure, so this
+     * is not a scolding — it is the coordinate. The execution index records the
+     * commit it was written at, which is its position in time and space; the
+     * distance from there to the tree on disk is what `--since` would have spent,
+     * and a reader that cannot see the coordinate cannot decide whether spending
+     * it is worth anything.
+     *
+     * Both halves are optional and mean different things absent. No `since` is a
+     * run that observed everything it planned. No `index` is either no recorded
+     * execution index or one with no position — nothing to diff from, so nothing
+     * to offer — and never *the index is current*, which is `changed: 0`.
+     */
+    readonly narrowing?: {
+        /** The ref `--since` named. */
+        readonly since?: string;
+        /** Where the recorded execution index stands, and how far the tree is from it. */
+        readonly index?: {
+            readonly commit: string;
+            /** Files differing between that commit and the working tree. */
+            readonly changed: number;
+        };
+    };
+    /**
+     * What each declaration did, and the audit an ignore is only safe to have
+     * because of — see [`declarations.ts`](./declarations.ts). Kept in the record
+     * because *has this mask grown over a regression?* is asked months later, by
+     * somebody else. Never empty: absent is *the config named no such rule*.
+     */
+    readonly ignores?: IgnoreLedger;
+    /** The same, for rules that relax an assertion rather than remove a region. */
+    readonly sensitivities?: SensitivityLedger;
+}
+/**
+ * Why a subject is in the report without an observation.
+ *
+ * Three kinds, because they mean different things about whether anyone should
+ * act. `excluded` is a decision the operator made and wrote down; `failed` is a
+ * hole in coverage, and collapsing the two makes every exclusion permanently red
+ * or a crash on subject 41 look chosen. `unreached` is neither: the run read the
+ * diff against what each baseline records having rendered and concluded this
+ * change cannot arrive. Calling that a decision reports one nobody made.
+ */
+export type NotObservedKind = 'excluded' | 'failed' | 'unreached';
+export interface NotObserved {
+    readonly subject: string;
+    readonly kind: NotObservedKind;
+    /** One sentence, ready to print, naming what was not looked at and why. */
+    readonly because: string;
+}
+export interface ObservationRecord {
+    readonly subject: string;
+    /**
+     * `ignored` is green and is not `unchanged`.
+     *
+     * Pixels differed and every one of them landed inside a subtree the operator
+     * excluded (spec 0024). Kept as its own word so a report can be asked how much
+     * of its green was earned and how much was declared — a question `unchanged`
+     * absorbs and can never answer again.
+     */
+    readonly verdict: 'unchanged' | 'changed' | 'new' | 'incomparable' | 'ignored';
+    readonly because: string;
+    /**
+     * Differing pixels at the policy the run isolated on, **after** exclusions.
+     *
+     * What was ignored is in {@link ObservationRecord.ignored} rather than folded
+     * in here, so the two numbers cannot be added by accident and a subject with a
+     * mask over half of it does not read as a subject that barely moved.
+     */
+    readonly changedPixels: number;
+    /** Independently observed boundaries. A missing member was not measured. */
+    readonly signals?: {
+        readonly document?: 'unchanged' | 'changed';
+        readonly pixels?: 'unchanged' | 'changed';
+        readonly accessibility?: {
+            readonly verdict: 'unchanged' | 'changed' | 'incomparable';
+            readonly before?: AccessibilitySnapshot;
+            readonly after?: AccessibilitySnapshot;
+        };
+        /** Rendered relationship consequences, independent of render impact and verdict. */
+        readonly presentation?: PresentationSignalRecord;
+    };
+    /**
+     * What the operator's ignores took out of this comparison.
+     *
+     * Present whenever the subject had an excluded subtree at all, including when
+     * nothing was absorbed — `pixels: 0` with `boxes: 2` is a rule that caught
+     * nothing this run, which is the state that turns an ignore into a blind spot
+     * and therefore the one a report must be able to state.
+     */
+    readonly ignored?: {
+        readonly pixels: number;
+        readonly boxes: number;
+        /** Boxes covering no changed pixel: the raster half of a dead ignore. */
+        readonly inert: number;
+        /** Pixels each rule absorbed here. A rule present with `0` caught nothing. */
+        readonly byRule: Readonly<Record<string, number>>;
+    };
+    /**
+     * The sensitivity that absorbed this subject, when one did.
+     *
+     * A subject reported `ignored` has two possible reasons and they are not
+     * interchangeable: every differing pixel fell inside an excluded subtree, or
+     * every band that moved was one this subject is not asserted on. The first is
+     * in {@link ObservationRecord.ignored}; this is the second, and keeping them
+     * apart is what lets a run be asked how much of its green came from a mask and
+     * how much from a declared level.
+     */
+    readonly relaxed?: {
+        readonly rule: string;
+        readonly level: string;
+        readonly bands: readonly string[];
+    };
+    /**
+     * Every component whose hashes moved here, and the bands it moved in.
+     *
+     * A region is a box the pixels drew, named from where that box landed, so it
+     * fails where a change is most worth explaining: an edit that reflows its
+     * neighbours merges into one blob, the blob fits no component, and the name
+     * that comes back is the document root. These entries never looked at a pixel,
+     * so they still say `Button — geometry, token` where the only region is called
+     * `Anonymous`, and a component here that no region names is a difference lost.
+     *
+     * **Absent is not empty.** Omitted means no baseline hashes were there to
+     * compare; `[]` means both sides were read and every digest matched.
+     */
+    readonly moved?: readonly ComponentBands[];
+    readonly regions: readonly RegionRecord[];
+    /** Regions found but not recorded, with their pixels. Never silently dropped. */
+    readonly truncated?: {
+        readonly regions: number;
+        readonly pixels: number;
+    };
+    readonly missingFonts?: readonly string[];
+    /**
+     * Defects found in *this* render, with no baseline consulted.
+     *
+     * The other half of what a run knows, and the half a comparison structurally
+     * cannot produce: a control that never had an accessible name compares equal
+     * to itself forever, so approving the first baseline approves the defect.
+     * Recorded per subject rather than per run because they are attributed the
+     * same way a region is — a component, a place, a file — and because the same
+     * component appearing in six subjects is six chances to notice it.
+     *
+     * They do not affect the verdict. A tool that blocks a merge on day one over
+     * findings nobody asked for gets switched off in week one; a project that
+     * wants them enforced writes `blocking: ['a11y']` in its policy, which covers
+     * both these and the regressions found by comparison.
+     *
+     * **Empty is not absent.** `[]` means this render was inspected and was clean;
+     * omitted means nothing inspected it, because the collector supplied no
+     * snapshot. Printing the second as the first tells a reader the component is
+     * fine on the authority of something that never looked at it — the same
+     * collapse `notObserved` exists to prevent.
+     */
+    readonly findings?: readonly FindingRecord[];
+    /**
+     * What a second collection, in a world nothing else had touched, said.
+     *
+     * Present only on a subject the run called `changed`, and only when the
+     * collector can build such a world — `collectAlone` in `commands/run.ts` is
+     * optional, because a collector holding one page open across every subject
+     * cannot, and saying so is better than being assumed to have one.
+     *
+     * `reproduced: false` is the finding this whole path exists for: the change is
+     * gone when nothing else has run, so the baseline was right and the *session*
+     * moved this subject. That is a defect in the suite rather than in the
+     * component, and it must never be promoted — see `accept`, which refuses it.
+     *
+     * **Absent is not `reproduced: true`.** Omitted means nothing re-collected
+     * this subject, and reading that as "it reproduces" is how a false regression
+     * gets promoted with a confirmation attached to it.
+     */
+    readonly alone?: {
+        /** `true` when the difference survived a world nothing else had touched. */
+        readonly reproduced: boolean;
+        readonly because: string;
+    };
+    /**
+     * The subject was read twice in one world and the two readings disagreed.
+     *
+     * The other second pass, and it answers the opposite question to
+     * {@link ObservationRecord.alone}: that one rebuilds the world and holds time,
+     * this one holds the world and lets time pass. A subject that fails this one is
+     * not a change and not a leak — it is a reading that cannot be taken twice, and
+     * everything the comparison said about it was said about one of the two.
+     *
+     * `accept` refuses it, for the reason it refuses order dependence: promoting a
+     * reading that will not reproduce makes the instability the baseline, and the
+     * next run compares against a coin flip somebody approved.
+     *
+     * **Absent means this run's two readings agreed — it does not mean stable.** A
+     * subject that reads differently one time in fifty passes twice-in-a-row forty
+     * nine runs out of fifty. Two readings put a floor under flakiness; nothing here
+     * puts a ceiling on it, and a reader who treats the absent field as a
+     * certificate has been told something this field never said. It is also absent
+     * on every subject the run did not call `changed`, which is almost all of them.
+     */
+    readonly unstable?: {
+        /**
+         * Components whose own content differed between the two readings, with the
+         * file that declares each one where the source index could name it.
+         *
+         * Empty when the collector supplied no snapshot, which is a different state
+         * from *no component was responsible* — see the `because`, which says which
+         * of the two it is rather than leaving an empty list to be read as an answer.
+         */
+        readonly components: readonly {
+            readonly name: string;
+            /** `file:line`. Absent when no source index resolved the name. */
+            readonly file?: string;
+        }[];
+        /** Frequency bands the disagreement fell in, e.g. `content`, `geometry`. */
+        readonly bands: readonly string[];
+        /**
+         * The declaration that put every band of this movement outside what the
+         * subject is asserted on.
+         *
+         * **Present means this is not a finding.** It does not gate, `accept` does
+         * not refuse it, and the summary files it under a different heading — because
+         * a route declared `layout` has said, in the config, that it does not assert
+         * on what the page is painted with, and a clock inside it is then a fact
+         * about the page rather than a defect in it. Stability is required inside the
+         * boundary the subject declares, and demanding it outside would make the
+         * declaration worthless: every route-level test would go red over the exact
+         * movement it was written to ignore.
+         *
+         * Recorded rather than dropped, for the reason `ignored` is a word of its own
+         * and never `unchanged` (ADR-0026): a suite has to be answerable about how
+         * much of its green came from a declaration. `bands` above still lists
+         * everything that moved, so the register can say what was absorbed and by
+         * which rule.
+         */
+        readonly absorbed?: {
+            readonly rule: string;
+            readonly level: string;
+        };
+        readonly because: string;
+    };
+    /** Where the images went, when the run kept them. Relative to the report. */
+    readonly images?: {
+        readonly before?: string;
+        readonly after?: string;
+        readonly diff?: string;
+    };
+}
+export interface RegionRecord {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly pixels: number;
+    readonly component?: string;
+    readonly path?: string;
+    /** Landmark phrase, e.g. `main → list item 2 of 3`. */
+    readonly where?: string;
+    readonly file?: string;
+    /**
+     * `true` when the semantic tier named this component a root of the change.
+     *
+     * The field that decides whether a report leads with the edit or with what the
+     * edit pushed around. See `rankRegions` — area alone gets this backwards.
+     */
+    readonly cause: boolean;
+    /** `true` when no box contained the region; a wrong scale or origin. */
+    readonly unattributed?: boolean;
+    /**
+     * The shape of this difference, with position and values removed.
+     *
+     * Printed so that writing a shape-scoped ignore is copying a digest out of the
+     * report rather than deriving one. Two regions with the same fingerprint are
+     * the same kind of thing happening, wherever on the canvas they landed.
+     */
+    readonly fingerprint?: string;
+}
+export type { FindingRecord } from './finding-record.js';
+export type { PresentationEffectEvidence, PresentationEffectRecord, PresentationEffectTransition, PresentationInformationRecord, PresentationSignalRecord, } from './presentation-record.js';
+export type { ChurnRecord, DriftRecord, FlakinessRecord } from './history-records.js';
+export type { VariationRecord } from './variation.js';
+//# sourceMappingURL=format.d.ts.map

package/dist/format.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  AccessibilitySnapshot,\n  ComponentBands,\n  RenderIdentity,\n} from '@variance-authority/core';\nimport type { FindingRecord } from './finding-record.js';\nimport type { CompositionReport } from './composition.js';\nimport type { IgnoreLedger, SensitivityLedger } from './declarations.js';\nimport type { ReachReport } from './reach.js';\nimport type { PresentationSignalRecord } from './presentation-record.js';\nimport type { ChurnRecord, DriftRecord, FlakinessRecord } from './history-records.js';\nimport type { VariationRecord } from './variation.js';\n\n/**\n * The run report — the artifact an agent actually reads.\n *\n * The observation pipeline produces values in memory and then the process ends.\n * That is fine for a test and useless for the thing this is for: an agent asked\n * to *fix* something arrives afterwards, in a different process, with no access\n * to whatever was in scope when the change was sensed.\n *\n * So the run writes one of these, and the MCP tools query it. Keeping the file\n * the contract — rather than having the tools re-run the pipeline — is what makes\n * the two halves independent: a run can be produced by CI on a pinned machine\n * and queried on a laptop, and the tools can be tested against a report nobody\n * rendered.\n *\n * Deliberately not the raw `Observation`. That carries a `ChangeMask` and base64\n * PNGs, which would make a 300-subject report hundreds of megabytes of data no\n * reader ever looks at. What is kept is what a sentence needs.\n */\n\nexport interface RunReport {\n  readonly runVersion: 1;\n  /** ISO 8601. Supplied by the caller — nothing in this package reads a clock. */\n  readonly at: string;\n  readonly identity: RenderIdentity;\n  readonly retention: 'durable' | 'ephemeral';\n  /** What the run was comparing, in the author's words. Carried into every answer. */\n  readonly intent?: string;\n  readonly observations: readonly ObservationRecord[];\n  /**\n   * Subjects the run planned and has no observation for. **Absent is not empty.**\n   *\n   * Lives here rather than only on the CLI's own superset because the answers an\n   * agent gets are computed from *this* type, and a field the tools cannot see is\n   * a field the tools cannot be contradicted by. A run that planned 300 subjects,\n   * failed on 50 and found the other 250 unchanged produces a report in which\n   * every observation is clean and the conclusion \"nothing to review\" is false;\n   * the only thing that can refuse that sentence is this list.\n   *\n   * Optional because a report written by something other than `variance run` will\n   * not carry it, and the difference has to survive: `undefined` means the writer\n   * never said what it skipped, which is not the same claim as \"it skipped\n   * nothing\" and must never be printed as one. Costs every reader an extra state\n   * to handle, which is cheaper than the state it prevents collapsing.\n   */\n  readonly notObserved?: readonly NotObserved[];\n\n  /**\n   * Which run this was, and at which commit.\n   *\n   * Present when the run could name itself — `--run` and `--commit`, or the pair\n   * the surrounding CI exports. Absent on a laptop, and absent is not a default\n   * anybody may fill in: an invented id cannot be joined back to anything that\n   * shipped, and it would silently become a denominator.\n   *\n   * Carried in the artifact because acceptance happens *later*, in a different\n   * command reading this file. A reviewer approves a subject **in a build**, and\n   * without the build's id there is nothing for that approval to point at — which\n   * is why every observation a run records is unapproved and why drift summed\n   * nothing until this field existed.\n   */\n  readonly run?: {\n    readonly id: string;\n    readonly commit: string;\n  };\n\n  /**\n   * What a history record already knew about the subjects this run found\n   * unstable, keyed by subject.\n   *\n   * Two readings put a *floor* under flakiness and can never put a ceiling on it\n   * (`ObservationRecord.unstable`). This is the other instrument: how often the\n   * subject has read differently before, and — the part that decides what anybody\n   * does next — whether it has happened since the last few sweeps. \"Unstable in 6\n   * of 20\" and \"6 times, none in the last 9 sweeps\" are opposite instructions.\n   *\n   * It lives on this type rather than only on the CLI's superset for the reason\n   * `notObserved` does: the answers an agent gets are computed from *this* type,\n   * and a field the tools cannot see is a field they cannot be contradicted by.\n   *\n   * **Absent is not \"this has never happened.\"** It means no store answered —\n   * because none is configured, or because one could not be reached — and the\n   * reason is in `warnings` where it can be printed. A surface that renders a\n   * missing entry as \"first occurrence\" has invented the one fact this record\n   * exists to supply.\n   */\n  readonly flakiness?: Readonly<Record<string, FlakinessRecord>>;\n\n  /**\n   * How often each component this run named as a cause has changed before,\n   * keyed by component.\n   *\n   * The instrument a comparison structurally cannot be. A diff answers *what\n   * moved*; this answers *how often this moves*, which is the difference between\n   * \"review this\" and \"this component has been rewritten eleven times this\n   * quarter and nobody has asked why\". No threshold reaches it, because the\n   * quantity is a count across runs and a one-run-at-a-time tool keeps none.\n   *\n   * **Absent is not \"it has never changed.\"** It means no store answered, and the\n   * reason is in `warnings`.\n   */\n  readonly churn?: Readonly<Record<string, ChurnRecord>>;\n\n  /**\n   * Design tokens whose value moved in this run, and what they have drifted to\n   * across every approved change in the window.\n   *\n   * The finding no comparison reaches. A button gains 2px, eleven times, each\n   * approved correctly by somebody looking at one diff — and the 22px is a number\n   * no review ever saw, because the quantity that would catch it is a sum and a\n   * single run holds none. Present only for tokens that moved *here*, so it is\n   * empty on almost every run and is the whole story on the one where it is not.\n   */\n  readonly drift?: Readonly<Record<string, DriftRecord>>;\n\n  /**\n   * The suite compared to *itself*, at this one commit — see\n   * [`composition.ts`](./composition.ts).\n   *\n   * The only section of this report with no baseline in it. Absent when the\n   * collection produced no semantic snapshots to join, which is a real state and\n   * not an empty graph: a suite that shares nothing and a suite nobody could ask\n   * are different claims.\n   */\n  readonly composition?: CompositionReport;\n\n  /**\n   * Subjects that declared themselves variations of another subject, and what\n   * the variation *is*.\n   *\n   * The other section with no baseline in it, and the answer to a question the\n   * category has never had one for: a story added behind a feature flag is a new\n   * subject, so its first run is `new`, its diff is empty, and what the flag\n   * actually does to the page is visible only by opening two pictures side by\n   * side. A subject that names a parent is compared against that parent *in the\n   * same run*, so the difference is a value with an identity — and the identity\n   * is what lets a reviewer be told that the difference is the one they already\n   * approved, on a run where both subjects changed.\n   *\n   * Every declared variation appears, including the ones that could not be\n   * computed: a parent nobody observed is a variation that was not measured, and\n   * dropping it would make a broken link look like a subject with nothing to say.\n   *\n   * Absent when no subject in the run declared a parent. Never present and empty.\n   */\n  readonly variations?: readonly VariationRecord[];\n\n  /**\n   * What this commit reaches, from the diff and the file graph — see\n   * [`reach.ts`](./reach.ts).\n   *\n   * The third axis. `observations` is a subject against its past, `composition`\n   * is the suite against itself, and this is the suite against the *edit* — which\n   * components the changed files can possibly have moved, and by which chain.\n   * Crossed against the verdicts, it is what lets a report say that an edit\n   * reached a subject and changed nothing, or that a subject moved with nothing\n   * in the commit reaching it.\n   *\n   * Absent when the run was given no ref to diff against, or when no file graph\n   * was scanned. Present with `subjects` absent is the run saying it *has* a diff\n   * and could not attribute it, which is a different fact and a louder one.\n   */\n  readonly reach?: ReachReport;\n\n  /**\n   * What this run narrowed by, and what it could have narrowed by.\n   *\n   * A run that observed everything is the default and is not a failure, so this\n   * is not a scolding — it is the coordinate. The execution index records the\n   * commit it was written at, which is its position in time and space; the\n   * distance from there to the tree on disk is what `--since` would have spent,\n   * and a reader that cannot see the coordinate cannot decide whether spending\n   * it is worth anything.\n   *\n   * Both halves are optional and mean different things absent. No `since` is a\n   * run that observed everything it planned. No `index` is either no recorded\n   * execution index or one with no position — nothing to diff from, so nothing\n   * to offer — and never *the index is current*, which is `changed: 0`.\n   */\n  readonly narrowing?: {\n    /** The ref `--since` named. */\n    readonly since?: string;\n    /** Where the recorded execution index stands, and how far the tree is from it. */\n    readonly index?: {\n      readonly commit: string;\n      /** Files differing between that commit and the working tree. */\n      readonly changed: number;\n    };\n  };\n\n  /**\n   * What each declaration did, and the audit an ignore is only safe to have\n   * because of — see [`declarations.ts`](./declarations.ts). Kept in the record\n   * because *has this mask grown over a regression?* is asked months later, by\n   * somebody else. Never empty: absent is *the config named no such rule*.\n   */\n  readonly ignores?: IgnoreLedger;\n  /** The same, for rules that relax an assertion rather than remove a region. */\n  readonly sensitivities?: SensitivityLedger;\n}\n\n/**\n * Why a subject is in the report without an observation.\n *\n * Three kinds, because they mean different things about whether anyone should\n * act. `excluded` is a decision the operator made and wrote down; `failed` is a\n * hole in coverage, and collapsing the two makes every exclusion permanently red\n * or a crash on subject 41 look chosen. `unreached` is neither: the run read the\n * diff against what each baseline records having rendered and concluded this\n * change cannot arrive. Calling that a decision reports one nobody made.\n */\nexport type NotObservedKind = 'excluded' | 'failed' | 'unreached';\n\nexport interface NotObserved {\n  readonly subject: string;\n  readonly kind: NotObservedKind;\n  /** One sentence, ready to print, naming what was not looked at and why. */\n  readonly because: string;\n}\n\nexport interface ObservationRecord {\n  readonly subject: string;\n\n  /**\n   * `ignored` is green and is not `unchanged`.\n   *\n   * Pixels differed and every one of them landed inside a subtree the operator\n   * excluded (spec 0024). Kept as its own word so a report can be asked how much\n   * of its green was earned and how much was declared — a question `unchanged`\n   * absorbs and can never answer again.\n   */\n  readonly verdict: 'unchanged' | 'changed' | 'new' | 'incomparable' | 'ignored';\n  readonly because: string;\n\n  /**\n   * Differing pixels at the policy the run isolated on, **after** exclusions.\n   *\n   * What was ignored is in {@link ObservationRecord.ignored} rather than folded\n   * in here, so the two numbers cannot be added by accident and a subject with a\n   * mask over half of it does not read as a subject that barely moved.\n   */\n  readonly changedPixels: number;\n\n  /** Independently observed boundaries. A missing member was not measured. */\n  readonly signals?: {\n    readonly document?: 'unchanged' | 'changed';\n    readonly pixels?: 'unchanged' | 'changed';\n    readonly accessibility?: {\n      readonly verdict: 'unchanged' | 'changed' | 'incomparable';\n      readonly before?: AccessibilitySnapshot;\n      readonly after?: AccessibilitySnapshot;\n    };\n    /** Rendered relationship consequences, independent of render impact and verdict. */\n    readonly presentation?: PresentationSignalRecord;\n  };\n\n  /**\n   * What the operator's ignores took out of this comparison.\n   *\n   * Present whenever the subject had an excluded subtree at all, including when\n   * nothing was absorbed — `pixels: 0` with `boxes: 2` is a rule that caught\n   * nothing this run, which is the state that turns an ignore into a blind spot\n   * and therefore the one a report must be able to state.\n   */\n  readonly ignored?: {\n    readonly pixels: number;\n    readonly boxes: number;\n    /** Boxes covering no changed pixel: the raster half of a dead ignore. */\n    readonly inert: number;\n    /** Pixels each rule absorbed here. A rule present with `0` caught nothing. */\n    readonly byRule: Readonly<Record<string, number>>;\n  };\n  /**\n   * The sensitivity that absorbed this subject, when one did.\n   *\n   * A subject reported `ignored` has two possible reasons and they are not\n   * interchangeable: every differing pixel fell inside an excluded subtree, or\n   * every band that moved was one this subject is not asserted on. The first is\n   * in {@link ObservationRecord.ignored}; this is the second, and keeping them\n   * apart is what lets a run be asked how much of its green came from a mask and\n   * how much from a declared level.\n   */\n  readonly relaxed?: {\n    readonly rule: string;\n    readonly level: string;\n    readonly bands: readonly string[];\n  };\n\n  /**\n   * Every component whose hashes moved here, and the bands it moved in.\n   *\n   * A region is a box the pixels drew, named from where that box landed, so it\n   * fails where a change is most worth explaining: an edit that reflows its\n   * neighbours merges into one blob, the blob fits no component, and the name\n   * that comes back is the document root. These entries never looked at a pixel,\n   * so they still say `Button — geometry, token` where the only region is called\n   * `Anonymous`, and a component here that no region names is a difference lost.\n   *\n   * **Absent is not empty.** Omitted means no baseline hashes were there to\n   * compare; `[]` means both sides were read and every digest matched.\n   */\n  readonly moved?: readonly ComponentBands[];\n  readonly regions: readonly RegionRecord[];\n  /** Regions found but not recorded, with their pixels. Never silently dropped. */\n  readonly truncated?: { readonly regions: number; readonly pixels: number };\n  readonly missingFonts?: readonly string[];\n\n  /**\n   * Defects found in *this* render, with no baseline consulted.\n   *\n   * The other half of what a run knows, and the half a comparison structurally\n   * cannot produce: a control that never had an accessible name compares equal\n   * to itself forever, so approving the first baseline approves the defect.\n   * Recorded per subject rather than per run because they are attributed the\n   * same way a region is — a component, a place, a file — and because the same\n   * component appearing in six subjects is six chances to notice it.\n   *\n   * They do not affect the verdict. A tool that blocks a merge on day one over\n   * findings nobody asked for gets switched off in week one; a project that\n   * wants them enforced writes `blocking: ['a11y']` in its policy, which covers\n   * both these and the regressions found by comparison.\n   *\n   * **Empty is not absent.** `[]` means this render was inspected and was clean;\n   * omitted means nothing inspected it, because the collector supplied no\n   * snapshot. Printing the second as the first tells a reader the component is\n   * fine on the authority of something that never looked at it — the same\n   * collapse `notObserved` exists to prevent.\n   */\n  readonly findings?: readonly FindingRecord[];\n\n  /**\n   * What a second collection, in a world nothing else had touched, said.\n   *\n   * Present only on a subject the run called `changed`, and only when the\n   * collector can build such a world — `collectAlone` in `commands/run.ts` is\n   * optional, because a collector holding one page open across every subject\n   * cannot, and saying so is better than being assumed to have one.\n   *\n   * `reproduced: false` is the finding this whole path exists for: the change is\n   * gone when nothing else has run, so the baseline was right and the *session*\n   * moved this subject. That is a defect in the suite rather than in the\n   * component, and it must never be promoted — see `accept`, which refuses it.\n   *\n   * **Absent is not `reproduced: true`.** Omitted means nothing re-collected\n   * this subject, and reading that as \"it reproduces\" is how a false regression\n   * gets promoted with a confirmation attached to it.\n   */\n  readonly alone?: {\n    /** `true` when the difference survived a world nothing else had touched. */\n    readonly reproduced: boolean;\n    readonly because: string;\n  };\n\n  /**\n   * The subject was read twice in one world and the two readings disagreed.\n   *\n   * The other second pass, and it answers the opposite question to\n   * {@link ObservationRecord.alone}: that one rebuilds the world and holds time,\n   * this one holds the world and lets time pass. A subject that fails this one is\n   * not a change and not a leak — it is a reading that cannot be taken twice, and\n   * everything the comparison said about it was said about one of the two.\n   *\n   * `accept` refuses it, for the reason it refuses order dependence: promoting a\n   * reading that will not reproduce makes the instability the baseline, and the\n   * next run compares against a coin flip somebody approved.\n   *\n   * **Absent means this run's two readings agreed — it does not mean stable.** A\n   * subject that reads differently one time in fifty passes twice-in-a-row forty\n   * nine runs out of fifty. Two readings put a floor under flakiness; nothing here\n   * puts a ceiling on it, and a reader who treats the absent field as a\n   * certificate has been told something this field never said. It is also absent\n   * on every subject the run did not call `changed`, which is almost all of them.\n   */\n  readonly unstable?: {\n    /**\n     * Components whose own content differed between the two readings, with the\n     * file that declares each one where the source index could name it.\n     *\n     * Empty when the collector supplied no snapshot, which is a different state\n     * from *no component was responsible* — see the `because`, which says which\n     * of the two it is rather than leaving an empty list to be read as an answer.\n     */\n    readonly components: readonly {\n      readonly name: string;\n      /** `file:line`. Absent when no source index resolved the name. */\n      readonly file?: string;\n    }[];\n    /** Frequency bands the disagreement fell in, e.g. `content`, `geometry`. */\n    readonly bands: readonly string[];\n\n    /**\n     * The declaration that put every band of this movement outside what the\n     * subject is asserted on.\n     *\n     * **Present means this is not a finding.** It does not gate, `accept` does\n     * not refuse it, and the summary files it under a different heading — because\n     * a route declared `layout` has said, in the config, that it does not assert\n     * on what the page is painted with, and a clock inside it is then a fact\n     * about the page rather than a defect in it. Stability is required inside the\n     * boundary the subject declares, and demanding it outside would make the\n     * declaration worthless: every route-level test would go red over the exact\n     * movement it was written to ignore.\n     *\n     * Recorded rather than dropped, for the reason `ignored` is a word of its own\n     * and never `unchanged` (ADR-0026): a suite has to be answerable about how\n     * much of its green came from a declaration. `bands` above still lists\n     * everything that moved, so the register can say what was absorbed and by\n     * which rule.\n     */\n    readonly absorbed?: {\n      readonly rule: string;\n      readonly level: string;\n    };\n\n    readonly because: string;\n  };\n\n  /** Where the images went, when the run kept them. Relative to the report. */\n  readonly images?: {\n    readonly before?: string;\n    readonly after?: string;\n    readonly diff?: string;\n  };\n}\n\nexport interface RegionRecord {\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n  readonly pixels: number;\n  readonly component?: string;\n  readonly path?: string;\n  /** Landmark phrase, e.g. `main → list item 2 of 3`. */\n  readonly where?: string;\n  readonly file?: string;\n  /**\n   * `true` when the semantic tier named this component a root of the change.\n   *\n   * The field that decides whether a report leads with the edit or with what the\n   * edit pushed around. See `rankRegions` — area alone gets this backwards.\n   */\n  readonly cause: boolean;\n  /** `true` when no box contained the region; a wrong scale or origin. */\n  readonly unattributed?: boolean;\n\n  /**\n   * The shape of this difference, with position and values removed.\n   *\n   * Printed so that writing a shape-scoped ignore is copying a digest out of the\n   * report rather than deriving one. Two regions with the same fingerprint are\n   * the same kind of thing happening, wherever on the canvas they landed.\n   */\n  readonly fingerprint?: string;\n}\n\n// Re-exported so a reader importing the report's shape gets the shapes its\n// fields are made of, without having to know which file each one was argued in.\nexport type { FindingRecord } from './finding-record.js';\nexport type {\n  PresentationEffectEvidence,\n  PresentationEffectRecord,\n  PresentationEffectTransition,\n  PresentationInformationRecord,\n  PresentationSignalRecord,\n} from './presentation-record.js';\nexport type { ChurnRecord, DriftRecord, FlakinessRecord } from './history-records.js';\nexport type { VariationRecord } from './variation.js';\n"]}

package/dist/history-records.d.ts

@@ -0,0 +1,112 @@
+/**
+ * What the store answered, flattened into the report.
+ *
+ * Three shapes, and each is a copy of something `@variance-authority/history`
+ * already has. Deliberately: a report is opened by a reader that has a JSON file
+ * and nothing else, and importing the history package to name the type of a
+ * field would make reading a run report require installing a database client.
+ *
+ * They are together because they answer one question between them — *what does
+ * this suite's past say about what it just did* — and apart from `format.ts`
+ * because that question is the only one in the report a run cannot answer on its
+ * own. A run with no history configured has none of these, and its report is not
+ * missing anything it could have produced.
+ */
+/** What one token has drifted to, and how far it travelled getting there. */
+export interface DriftRecord {
+    readonly from: string;
+    readonly to: string;
+    /** Value changes behind it. One is not drift; this is never below two. */
+    readonly steps: number;
+    readonly firstAt: string;
+    readonly lastAt: string;
+    /**
+     * The arithmetic, when every value was the same kind of quantity.
+     *
+     * Absent for a colour, a font stack, or a mixed set of units — and absent means
+     * *not measurable*, never zero. `because` says which.
+     */
+    readonly quantity?: {
+        readonly unit: string;
+        readonly net: number;
+        /** The largest single step: the most any one review could have seen. */
+        readonly largestStep: number;
+        /** Sum of the absolute steps, which exceeds `|net|` whenever it changed direction. */
+        readonly travel: number;
+    };
+    /** One sentence, ready to print, from the package that owns the arithmetic. */
+    readonly because: string;
+}
+/**
+ * How often one component's own code has changed, over a window.
+ *
+ * A structural copy of `@variance-authority/history`'s `Churn`, for the reason
+ * {@link FlakinessRecord} is one: this package requires nothing, and a report
+ * reader must not have to install a history client to open a file.
+ */
+export interface ChurnRecord {
+    /** Runs in the window, quiet ones included. The denominator. */
+    readonly runs: number;
+    /** Runs in which this component caused an **approved** change in any band. */
+    readonly changedRuns: number;
+    /**
+     * Runs in which only this component's geometry moved — it was *displaced* by an
+     * edit somewhere else. Reported, never summed: accumulating displacement makes
+     * the widest container in the application the thing that keeps changing, in
+     * every run, forever.
+     */
+    readonly collateralRuns: number;
+    /** Runs carrying a change to this component that nobody approved. */
+    readonly rejectedRuns: number;
+    readonly firstAt?: string;
+    readonly lastAt?: string;
+    /** One sentence, ready to print, from the package that owns the arithmetic. */
+    readonly because: string;
+}
+/**
+ * How often one subject has failed to read the same way twice.
+ *
+ * A structural copy of `@variance-authority/history`'s `Flakiness` rather than an
+ * import of it: this package requires nothing, and a report reader must not have
+ * to install a history client to open a file. The two are kept in step by the
+ * writer — `cli`, which imports both — and the fields that could drift are the
+ * ones with a rule attached, restated here so a reader of the artifact meets it.
+ */
+export interface FlakinessRecord {
+    /** Distinct runs recorded in the window, whatever they examined. */
+    readonly runs: number;
+    /**
+     * Distinct runs that read **every** subject twice, and the only honest
+     * denominator: an ordinary run asks a subject whether it agrees with itself
+     * only after calling it `changed`, so a green subject's silence in one is not
+     * evidence of anything.
+     */
+    readonly sweeps: number;
+    /** Distinct runs in which this subject read differently and was not absorbed. */
+    readonly occurrences: number;
+    /**
+     * Runs whose instability fell entirely in bands this subject does not assert
+     * on — working as declared, never a finding, counted so a rule that absorbs
+     * something forever can still be asked about.
+     */
+    readonly absorbedRuns: number;
+    /** Occurrences per sweep. **Absent when no sweep has run**, and never zero. */
+    readonly rate?: number;
+    /**
+     * Sweeps recorded since the most recent occurrence. Counted in sweeps rather
+     * than in days, so a suite that stopped running does not look increasingly
+     * fixed the longer nobody looks at it.
+     */
+    readonly sweepsSince: number;
+    /** What read differently, loudest first. Empty when nothing could be named. */
+    readonly causes: readonly {
+        readonly component?: string;
+        readonly band?: string;
+        readonly runs: number;
+    }[];
+    readonly firstAt?: string;
+    readonly lastAt?: string;
+    /** One sentence, ready to print, from the package that owns the arithmetic. */
+    readonly because: string;
+}
+//# sourceMappingURL=history-records.d.ts.map

package/dist/history-records.js

@@ -0,0 +1,16 @@
+/**
+ * What the store answered, flattened into the report.
+ *
+ * Three shapes, and each is a copy of something `@variance-authority/history`
+ * already has. Deliberately: a report is opened by a reader that has a JSON file
+ * and nothing else, and importing the history package to name the type of a
+ * field would make reading a run report require installing a database client.
+ *
+ * They are together because they answer one question between them — *what does
+ * this suite's past say about what it just did* — and apart from `format.ts`
+ * because that question is the only one in the report a run cannot answer on its
+ * own. A run with no history configured has none of these, and its report is not
+ * missing anything it could have produced.
+ */
+export {};
+//# sourceMappingURL=history-records.js.map

package/dist/history-records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-records.js","sourceRoot":"","sources":["../src/history-records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG","sourcesContent":["/**\n * What the store answered, flattened into the report.\n *\n * Three shapes, and each is a copy of something `@variance-authority/history`\n * already has. Deliberately: a report is opened by a reader that has a JSON file\n * and nothing else, and importing the history package to name the type of a\n * field would make reading a run report require installing a database client.\n *\n * They are together because they answer one question between them — *what does\n * this suite's past say about what it just did* — and apart from `format.ts`\n * because that question is the only one in the report a run cannot answer on its\n * own. A run with no history configured has none of these, and its report is not\n * missing anything it could have produced.\n */\n\n/** What one token has drifted to, and how far it travelled getting there. */\nexport interface DriftRecord {\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  readonly firstAt: string;\n  readonly lastAt: string;\n\n  /**\n   * The arithmetic, when every value was the same kind of quantity.\n   *\n   * Absent for a colour, a font stack, or a mixed set of units — and absent means\n   * *not measurable*, never zero. `because` says which.\n   */\n  readonly quantity?: {\n    readonly unit: string;\n    readonly net: number;\n    /** The largest single step: the most any one review could have seen. */\n    readonly largestStep: number;\n    /** Sum of the absolute steps, which exceeds `|net|` whenever it changed direction. */\n    readonly travel: number;\n  };\n\n  /** One sentence, ready to print, from the package that owns the arithmetic. */\n  readonly because: string;\n}\n\n/**\n * How often one component's own code has changed, over a window.\n *\n * A structural copy of `@variance-authority/history`'s `Churn`, for the reason\n * {@link FlakinessRecord} is one: this package requires nothing, and a report\n * reader must not have to install a history client to open a file.\n */\nexport interface ChurnRecord {\n  /** Runs in the window, quiet ones included. The denominator. */\n  readonly runs: number;\n\n  /** Runs in which this component caused an **approved** change in any band. */\n  readonly changedRuns: number;\n\n  /**\n   * Runs in which only this component's geometry moved — it was *displaced* by an\n   * edit somewhere else. Reported, never summed: accumulating displacement makes\n   * the widest container in the application the thing that keeps changing, in\n   * every run, forever.\n   */\n  readonly collateralRuns: number;\n\n  /** Runs carrying a change to this component that nobody approved. */\n  readonly rejectedRuns: number;\n\n  readonly firstAt?: string;\n  readonly lastAt?: string;\n\n  /** One sentence, ready to print, from the package that owns the arithmetic. */\n  readonly because: string;\n}\n\n/**\n * How often one subject has failed to read the same way twice.\n *\n * A structural copy of `@variance-authority/history`'s `Flakiness` rather than an\n * import of it: this package requires nothing, and a report reader must not have\n * to install a history client to open a file. The two are kept in step by the\n * writer — `cli`, which imports both — and the fields that could drift are the\n * ones with a rule attached, restated here so a reader of the artifact meets it.\n */\nexport interface FlakinessRecord {\n  /** Distinct runs recorded in the window, whatever they examined. */\n  readonly runs: number;\n\n  /**\n   * Distinct runs that read **every** subject twice, and the only honest\n   * denominator: an ordinary run asks a subject whether it agrees with itself\n   * only after calling it `changed`, so a green subject's silence in one is not\n   * evidence of anything.\n   */\n  readonly sweeps: number;\n\n  /** Distinct runs in which this subject read differently and was not absorbed. */\n  readonly occurrences: number;\n\n  /**\n   * Runs whose instability fell entirely in bands this subject does not assert\n   * on — working as declared, never a finding, counted so a rule that absorbs\n   * something forever can still be asked about.\n   */\n  readonly absorbedRuns: number;\n\n  /** Occurrences per sweep. **Absent when no sweep has run**, and never zero. */\n  readonly rate?: number;\n\n  /**\n   * Sweeps recorded since the most recent occurrence. Counted in sweeps rather\n   * than in days, so a suite that stopped running does not look increasingly\n   * fixed the longer nobody looks at it.\n   */\n  readonly sweepsSince: number;\n\n  /** What read differently, loudest first. Empty when nothing could be named. */\n  readonly causes: readonly {\n    readonly component?: string;\n    readonly band?: string;\n    readonly runs: number;\n  }[];\n\n  readonly firstAt?: string;\n  readonly lastAt?: string;\n\n  /** One sentence, ready to print, from the package that owns the arithmetic. */\n  readonly because: string;\n}\n"]}