@variance-authority/report 0.1.0

package/dist/promotion.d.ts

@@ -0,0 +1,86 @@
+import type { ObservationRecord } from './format.js';
+/**
+ * Whether a promotion would land, decided before anything is promoted.
+ *
+ * `accept` used to be the only thing that knew these rules, and it knew them by
+ * running: the answer to *what would this update record* was the update. That is
+ * fine for a person at a terminal and useless to anything asking beforehand — an
+ * agent proposing a command, a reader previewing a commit message — because the
+ * only way to find out was to do it.
+ *
+ * So the rules are a function over one observation and the command applies them
+ * rather than owning them. What that buys is the property the whole changelog
+ * argument rests on: a preview and the acceptance it previews cannot disagree,
+ * because there is one set of rules and both read it. A second copy that drifted
+ * would produce the worst available artifact here — a confident account of a
+ * baseline update that did not happen.
+ *
+ * Every refusal is the sentence `accept` prints, unchanged. The wording is part
+ * of the rule: it names what to do next, and an agent that gets a different
+ * sentence from the preview than from the command has to decide which one is the
+ * product.
+ */
+/**
+ * What would happen to this subject, and why.
+ *
+ * Three outcomes rather than a boolean, because *already the baseline* is not a
+ * refusal and printing it as one turns the ordinary case — the two hundred and
+ * ninety-eight subjects a run did not change — into a wall of failures. It is
+ * also not a promotion: nothing is written, and a record that counted it would
+ * describe a baseline update nobody made.
+ */
+export type Promotion = {
+    readonly kind: 'promotable';
+    /**
+     * The candidate image that would become the baseline, as the report named
+     * it.
+     *
+     * Carried on the answer rather than looked up again by the caller. A
+     * command that re-read `images.after` after being told a subject is
+     * promotable would be asking a second time whether the run left an image,
+     * and two readings of one fact are two answers waiting to differ.
+     */
+    readonly from: string;
+} | {
+    readonly kind: 'already-baseline';
+    readonly because: string;
+} | {
+    readonly kind: 'refused';
+    readonly because: string;
+};
+/**
+ * The rules, in the order they are asked.
+ *
+ * The order is load-bearing in one place: instability is asked *before* the
+ * verdict. A subject that read two ways and settled on `unchanged` is not a
+ * subject that did not change — `--flakes` reached the same baseline twice and
+ * got two answers — and answering "already the baseline" there hides the
+ * diagnostic that makes this refusable at all.
+ */
+export declare function promotionOf(observation: ObservationRecord): Promotion;
+/**
+ * Subjects a set of shapes can and cannot settle.
+ *
+ * `whole` is the safe bulk: every difference this subject has carries one of the
+ * named shapes, so promoting the shape here promotes nothing else. `partial` is
+ * the refusal that makes the bulk safe — the shape is present, something the
+ * shape does not name also moved, and accepting it there would baseline a
+ * difference nobody reviewed.
+ *
+ * A subject with no region at all is in neither list. It is not evidence about
+ * these shapes in either direction.
+ */
+export declare function selectByShape(observations: readonly ObservationRecord[], shapes: ReadonlySet<string>): {
+    whole: readonly ObservationRecord[];
+    partial: readonly ObservationRecord[];
+};
+/**
+ * Why a shape present in this subject cannot settle it.
+ *
+ * Two different facts wearing one outcome, and they send a reader to different
+ * places: the run recorded another difference, or the run stopped recording. The
+ * second is not evidence that something else moved — it is the absence of
+ * evidence that nothing did, which is why it refuses in exactly the same way.
+ */
+export declare function whyNotWhole(observation: ObservationRecord): string;
+//# sourceMappingURL=promotion.d.ts.map

package/dist/promotion.js

@@ -0,0 +1,104 @@
+/**
+ * The rules, in the order they are asked.
+ *
+ * The order is load-bearing in one place: instability is asked *before* the
+ * verdict. A subject that read two ways and settled on `unchanged` is not a
+ * subject that did not change — `--flakes` reached the same baseline twice and
+ * got two answers — and answering "already the baseline" there hides the
+ * diagnostic that makes this refusable at all.
+ */
+export function promotionOf(observation) {
+    if (observation.unstable !== undefined && observation.unstable.absorbed === undefined) {
+        return {
+            kind: 'refused',
+            because: `${observation.unstable.because}. Accepting it would promote one of two readings ` +
+                'as the baseline; fix what moves between them, or re-run once it is fixed',
+        };
+    }
+    if (observation.verdict === 'unchanged') {
+        return {
+            kind: 'already-baseline',
+            because: 'it did not change, so it already is the baseline; nothing to accept',
+        };
+    }
+    if (observation.alone?.reproduced === false) {
+        return {
+            kind: 'refused',
+            because: `${observation.alone.because}. Accepting it would make the leak the baseline; ` +
+                'fix the subject that writes the shared state, or re-run once it is fixed',
+        };
+    }
+    const after = observation.images?.after;
+    if (after === undefined) {
+        return { kind: 'refused', because: noImage(observation) };
+    }
+    return { kind: 'promotable', from: after };
+}
+/**
+ * Subjects a set of shapes can and cannot settle.
+ *
+ * `whole` is the safe bulk: every difference this subject has carries one of the
+ * named shapes, so promoting the shape here promotes nothing else. `partial` is
+ * the refusal that makes the bulk safe — the shape is present, something the
+ * shape does not name also moved, and accepting it there would baseline a
+ * difference nobody reviewed.
+ *
+ * A subject with no region at all is in neither list. It is not evidence about
+ * these shapes in either direction.
+ */
+export function selectByShape(observations, shapes) {
+    const whole = [];
+    const partial = [];
+    for (const observation of observations) {
+        if (observation.regions.length === 0)
+            continue;
+        const hits = observation.regions.filter((region) => region.fingerprint !== undefined && shapes.has(region.fingerprint));
+        if (hits.length === 0)
+            continue;
+        // A capped list is not a complete one. Regions the run found and chose not
+        // to record could be anything, so a subject whose evidence was truncated
+        // cannot support "this shape is the entire change" however its recorded
+        // regions look.
+        const capped = observation.truncated !== undefined && observation.truncated.regions > 0;
+        if (!capped && hits.length === observation.regions.length)
+            whole.push(observation);
+        else
+            partial.push(observation);
+    }
+    return { whole, partial };
+}
+/**
+ * Why a shape present in this subject cannot settle it.
+ *
+ * Two different facts wearing one outcome, and they send a reader to different
+ * places: the run recorded another difference, or the run stopped recording. The
+ * second is not evidence that something else moved — it is the absence of
+ * evidence that nothing did, which is why it refuses in exactly the same way.
+ */
+export function whyNotWhole(observation) {
+    return observation.truncated !== undefined && observation.truncated.regions > 0
+        ? `this shape is present, but the run capped its region list ` +
+            `(${String(observation.truncated.regions)} more, ${String(observation.truncated.pixels)}px), so ` +
+            'there is no evidence it is the whole change; accept this subject by name'
+        : 'this shape is present and something else changed too, so accepting it here ' +
+            'would baseline that as well; accept this subject by name once you have read it';
+}
+/**
+ * Why a subject has no image, phrased around what to do next.
+ *
+ * The two causes are opposite and a single message would serve neither. A
+ * settlement means nothing was rendered *because nothing needed to be*; an
+ * incomparable baseline means the comparison was refused, and the fix is a
+ * decision about machines rather than about this subject.
+ */
+function noImage(observation) {
+    if (observation.verdict === 'incomparable') {
+        return ('its baseline belongs to another machine, so the run refused to compare and produced ' +
+            'no image. Delete that baseline and re-run here to record one for this machine, or ' +
+            'run where the baseline was written — accepting across identities is the failure the ' +
+            'partition exists to prevent');
+    }
+    return ('the run recorded no image for it. Re-run on this machine so the candidate exists; ' +
+        'this command promotes an image that was already reviewed and never renders one');
+}
+//# sourceMappingURL=promotion.js.map

package/dist/promotion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promotion.js","sourceRoot":"","sources":["../src/promotion.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ObservationRecord } from './format.js';\n\n/**\n * Whether a promotion would land, decided before anything is promoted.\n *\n * `accept` used to be the only thing that knew these rules, and it knew them by\n * running: the answer to *what would this update record* was the update. That is\n * fine for a person at a terminal and useless to anything asking beforehand — an\n * agent proposing a command, a reader previewing a commit message — because the\n * only way to find out was to do it.\n *\n * So the rules are a function over one observation and the command applies them\n * rather than owning them. What that buys is the property the whole changelog\n * argument rests on: a preview and the acceptance it previews cannot disagree,\n * because there is one set of rules and both read it. A second copy that drifted\n * would produce the worst available artifact here — a confident account of a\n * baseline update that did not happen.\n *\n * Every refusal is the sentence `accept` prints, unchanged. The wording is part\n * of the rule: it names what to do next, and an agent that gets a different\n * sentence from the preview than from the command has to decide which one is the\n * product.\n */\n\n/**\n * What would happen to this subject, and why.\n *\n * Three outcomes rather than a boolean, because *already the baseline* is not a\n * refusal and printing it as one turns the ordinary case — the two hundred and\n * ninety-eight subjects a run did not change — into a wall of failures. It is\n * also not a promotion: nothing is written, and a record that counted it would\n * describe a baseline update nobody made.\n */\nexport type Promotion =\n  | {\n      readonly kind: 'promotable';\n      /**\n       * The candidate image that would become the baseline, as the report named\n       * it.\n       *\n       * Carried on the answer rather than looked up again by the caller. A\n       * command that re-read `images.after` after being told a subject is\n       * promotable would be asking a second time whether the run left an image,\n       * and two readings of one fact are two answers waiting to differ.\n       */\n      readonly from: string;\n    }\n  | { readonly kind: 'already-baseline'; readonly because: string }\n  | { readonly kind: 'refused'; readonly because: string };\n\n/**\n * The rules, in the order they are asked.\n *\n * The order is load-bearing in one place: instability is asked *before* the\n * verdict. A subject that read two ways and settled on `unchanged` is not a\n * subject that did not change — `--flakes` reached the same baseline twice and\n * got two answers — and answering \"already the baseline\" there hides the\n * diagnostic that makes this refusable at all.\n */\nexport function promotionOf(observation: ObservationRecord): Promotion {\n  if (observation.unstable !== undefined && observation.unstable.absorbed === undefined) {\n    return {\n      kind: 'refused',\n      because:\n        `${observation.unstable.because}. Accepting it would promote one of two readings ` +\n        'as the baseline; fix what moves between them, or re-run once it is fixed',\n    };\n  }\n\n  if (observation.verdict === 'unchanged') {\n    return {\n      kind: 'already-baseline',\n      because: 'it did not change, so it already is the baseline; nothing to accept',\n    };\n  }\n\n  if (observation.alone?.reproduced === false) {\n    return {\n      kind: 'refused',\n      because:\n        `${observation.alone.because}. Accepting it would make the leak the baseline; ` +\n        'fix the subject that writes the shared state, or re-run once it is fixed',\n    };\n  }\n\n  const after = observation.images?.after;\n  if (after === undefined) {\n    return { kind: 'refused', because: noImage(observation) };\n  }\n\n  return { kind: 'promotable', from: after };\n}\n\n/**\n * Subjects a set of shapes can and cannot settle.\n *\n * `whole` is the safe bulk: every difference this subject has carries one of the\n * named shapes, so promoting the shape here promotes nothing else. `partial` is\n * the refusal that makes the bulk safe — the shape is present, something the\n * shape does not name also moved, and accepting it there would baseline a\n * difference nobody reviewed.\n *\n * A subject with no region at all is in neither list. It is not evidence about\n * these shapes in either direction.\n */\nexport function selectByShape(\n  observations: readonly ObservationRecord[],\n  shapes: ReadonlySet<string>,\n): { whole: readonly ObservationRecord[]; partial: readonly ObservationRecord[] } {\n  const whole: ObservationRecord[] = [];\n  const partial: ObservationRecord[] = [];\n\n  for (const observation of observations) {\n    if (observation.regions.length === 0) continue;\n\n    const hits = observation.regions.filter(\n      (region) => region.fingerprint !== undefined && shapes.has(region.fingerprint),\n    );\n    if (hits.length === 0) continue;\n\n    // A capped list is not a complete one. Regions the run found and chose not\n    // to record could be anything, so a subject whose evidence was truncated\n    // cannot support \"this shape is the entire change\" however its recorded\n    // regions look.\n    const capped = observation.truncated !== undefined && observation.truncated.regions > 0;\n\n    if (!capped && hits.length === observation.regions.length) whole.push(observation);\n    else partial.push(observation);\n  }\n\n  return { whole, partial };\n}\n\n/**\n * Why a shape present in this subject cannot settle it.\n *\n * Two different facts wearing one outcome, and they send a reader to different\n * places: the run recorded another difference, or the run stopped recording. The\n * second is not evidence that something else moved — it is the absence of\n * evidence that nothing did, which is why it refuses in exactly the same way.\n */\nexport function whyNotWhole(observation: ObservationRecord): string {\n  return observation.truncated !== undefined && observation.truncated.regions > 0\n    ? `this shape is present, but the run capped its region list ` +\n        `(${String(observation.truncated.regions)} more, ${String(observation.truncated.pixels)}px), so ` +\n        'there is no evidence it is the whole change; accept this subject by name'\n    : 'this shape is present and something else changed too, so accepting it here ' +\n      'would baseline that as well; accept this subject by name once you have read it';\n}\n\n/**\n * Why a subject has no image, phrased around what to do next.\n *\n * The two causes are opposite and a single message would serve neither. A\n * settlement means nothing was rendered *because nothing needed to be*; an\n * incomparable baseline means the comparison was refused, and the fix is a\n * decision about machines rather than about this subject.\n */\nfunction noImage(observation: ObservationRecord): string {\n  if (observation.verdict === 'incomparable') {\n    return (\n      'its baseline belongs to another machine, so the run refused to compare and produced ' +\n      'no image. Delete that baseline and re-run here to record one for this machine, or ' +\n      'run where the baseline was written — accepting across identities is the failure the ' +\n      'partition exists to prevent'\n    );\n  }\n  return (\n    'the run recorded no image for it. Re-run on this machine so the candidate exists; ' +\n    'this command promotes an image that was already reviewed and never renders one'\n  );\n}\n"]}

package/dist/reach.d.ts

@@ -0,0 +1,154 @@
+/**
+ * What the commit reaches, joined to what the run saw.
+ *
+ * Every other section of a report is an answer about *pixels*: this subject
+ * against its baseline, this suite against itself. This one is the answer about
+ * *cause*, and it is built from three things no diff tool holds at once — the
+ * paths git named, the file graph a scanner read off disk, and the component
+ * list each baseline recorded when it was painted.
+ *
+ * Walking the graph backwards from every changed file gives the set of
+ * components an edit can possibly have moved, and the trail that carried it:
+ * `app/src/tokens.css → app/src/components/ui/button.css → Button`. A subject
+ * renders components, so the same walk says, per subject, whether this commit
+ * could have touched it.
+ *
+ * ## The reason this is worth an artifact rather than a log line
+ *
+ * The same computation already exists one directory over as `--since`, where it
+ * is used to *skip* subjects and then discarded. Skipping is a saving; this is
+ * the finding. Crossed against the verdicts the run produced, reach sorts every
+ * subject into four states, and two of them are questions nobody else in this
+ * category can even ask:
+ *
+ * - **reached and changed** — the expected case, and the trail names the file.
+ * - **reached and unchanged** — the edit is inert here. No diff tool asserts
+ *   anything about a green subject, so the surface an author *believed* they were
+ *   changing and did not is invisible everywhere else.
+ * - **unreached and changed** — nothing in this commit reaches this subject, and
+ *   it moved anyway. That is a flake, an input from outside the repository, or a
+ *   hole in the graph, and it is a different bug in each case.
+ * - **unreached and unchanged** — counted, never listed.
+ *
+ * The states are not stored. They are `reached × verdict`, and the verdicts are
+ * already in the report; writing them down as a fifth field would be a second
+ * copy of a fact that can disagree with the first.
+ *
+ * ## Every refusal here is louder than an answer
+ *
+ * A graph that cannot place a changed file cannot say what that file reaches,
+ * and the difference between *this edit reaches nothing* and *this edit was not
+ * understood* is the difference between a finding and a lie. So `subjects` is
+ * absent rather than empty when the attribution could not be made, and `whole`
+ * carries the reason in the same words the selector would have used to refuse to
+ * narrow.
+ */
+/** A component the diff reaches, and the chain that carried it there. */
+export interface ReachedComponent {
+    readonly component: string;
+    /**
+     * The shortest chain from a seed to this component: seed first, component
+     * last, every step a repository-relative path but the last.
+     *
+     * Shortest because the traversal is breadth-first, so the explanation printed
+     * is the shortest true one rather than whichever a stack happened to unwind.
+     */
+    readonly trail: readonly string[];
+    /**
+     * Present when the chain does not begin at a file this diff named.
+     *
+     * The traversal seeds every file whose own imports could not be read, because
+     * an unreadable file may import the one that changed. A component reached only
+     * through such a file is reached by the *scan's blind spot*, not by the edit,
+     * and a trail that opened with a path nobody touched would read as an
+     * attribution.
+     */
+    readonly throughUnread?: string;
+}
+/** Whether this commit could have moved this subject, and through what. */
+export interface SubjectReach {
+    readonly reached: boolean;
+    /**
+     * Components this subject's baseline records that the diff reaches, sorted.
+     *
+     * Empty exactly when `reached` is `false`.
+     */
+    readonly through: readonly string[];
+    /** The trail to the first of them. Absent when nothing was reached. */
+    readonly trail?: readonly string[];
+    /** One sentence, ready to print, either way it went. */
+    readonly because: string;
+}
+/** A file the graph holds but could not read the edges of. */
+export interface ReachHole {
+    readonly file: string;
+    readonly because?: string;
+}
+/**
+ * What the commit reaches, as the run recorded it.
+ *
+ * The half of a comparison no comparison can produce. A diff says which files an
+ * author touched; the import graph says which components those files reach; the
+ * suite says which subjects render those components. Put together they answer the
+ * question a reviewer actually has in front of a changed screenshot — *did I do
+ * this?* — and the answer is occasionally **no**, which is the strongest signal on
+ * the page and one nothing that only compares pixels can ever emit.
+ *
+ * Every field is written so the report can say *unknown* as loudly as it says
+ * *yes* and *no*. `whole` is the walk's refusal to attribute, `unscanned` the
+ * files it could not parse, `opaque` the edges it could not follow, and
+ * `subjects` is absent rather than empty when none of it could be attributed —
+ * because a commit that was understood and reaches nothing supports the opposite
+ * decision to a commit nothing could be read from.
+ */
+export interface ReachReport {
+    /** The ref the diff was taken against, in the operator's own words. */
+    readonly against: string;
+    /** Repository-relative paths the diff named. */
+    readonly changed: readonly string[];
+    /**
+     * Components the diff reaches, sorted by name.
+     *
+     * The whole answer, independent of any subject — a component here that appears
+     * in no subject's `through` is a component this suite does not watch, which is
+     * a coverage question rather than a review one.
+     */
+    readonly components: readonly ReachedComponent[];
+    /**
+     * Per planned subject, keyed by id. **Absent is not empty.**
+     *
+     * Absent means nothing here could be attributed and `whole` says why; every
+     * subject must then be read as possibly reached. Empty would mean the opposite
+     * — that the commit was understood and reaches none of them — and those two
+     * support opposite decisions.
+     *
+     * A subject whose baseline recorded no component list is simply not a key: the
+     * run does not know what it is made of, so it cannot say what reaches it.
+     */
+    readonly subjects?: Readonly<Record<string, SubjectReach>>;
+    /**
+     * Why nothing could be attributed, when nothing could.
+     *
+     * Present exactly when `subjects` is absent. A changed file under the scanned
+     * roots that the graph never saw, a diff entirely outside the graph, a diff
+     * that reaches no component at all: each of those looks identical to an edit
+     * that genuinely affects nothing, and only one of them is safe to act on.
+     */
+    readonly whole?: string;
+    /**
+     * Changed files under the scanned roots the graph does not hold.
+     *
+     * A gap in the scan rather than a file that affects nothing — the roots are the
+     * operator's own statement of where renders come from.
+     */
+    readonly unscanned?: readonly string[];
+    /**
+     * Files in the graph whose own edges could not be read, with the reason.
+     *
+     * Every one of them is traversed as though it changed. Reported because a
+     * reader who can see them can go and fix the scan; a reader who cannot sees an
+     * attribution that quietly covers more than the diff.
+     */
+    readonly opaque?: readonly ReachHole[];
+}
+//# sourceMappingURL=reach.d.ts.map

package/dist/reach.js

@@ -0,0 +1,47 @@
+/**
+ * What the commit reaches, joined to what the run saw.
+ *
+ * Every other section of a report is an answer about *pixels*: this subject
+ * against its baseline, this suite against itself. This one is the answer about
+ * *cause*, and it is built from three things no diff tool holds at once — the
+ * paths git named, the file graph a scanner read off disk, and the component
+ * list each baseline recorded when it was painted.
+ *
+ * Walking the graph backwards from every changed file gives the set of
+ * components an edit can possibly have moved, and the trail that carried it:
+ * `app/src/tokens.css → app/src/components/ui/button.css → Button`. A subject
+ * renders components, so the same walk says, per subject, whether this commit
+ * could have touched it.
+ *
+ * ## The reason this is worth an artifact rather than a log line
+ *
+ * The same computation already exists one directory over as `--since`, where it
+ * is used to *skip* subjects and then discarded. Skipping is a saving; this is
+ * the finding. Crossed against the verdicts the run produced, reach sorts every
+ * subject into four states, and two of them are questions nobody else in this
+ * category can even ask:
+ *
+ * - **reached and changed** — the expected case, and the trail names the file.
+ * - **reached and unchanged** — the edit is inert here. No diff tool asserts
+ *   anything about a green subject, so the surface an author *believed* they were
+ *   changing and did not is invisible everywhere else.
+ * - **unreached and changed** — nothing in this commit reaches this subject, and
+ *   it moved anyway. That is a flake, an input from outside the repository, or a
+ *   hole in the graph, and it is a different bug in each case.
+ * - **unreached and unchanged** — counted, never listed.
+ *
+ * The states are not stored. They are `reached × verdict`, and the verdicts are
+ * already in the report; writing them down as a fifth field would be a second
+ * copy of a fact that can disagree with the first.
+ *
+ * ## Every refusal here is louder than an answer
+ *
+ * A graph that cannot place a changed file cannot say what that file reaches,
+ * and the difference between *this edit reaches nothing* and *this edit was not
+ * understood* is the difference between a finding and a lie. So `subjects` is
+ * absent rather than empty when the attribution could not be made, and `whole`
+ * carries the reason in the same words the selector would have used to refuse to
+ * narrow.
+ */
+export {};
+//# sourceMappingURL=reach.js.map

package/dist/reach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reach.js","sourceRoot":"","sources":["../src/reach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG","sourcesContent":["/**\n * What the commit reaches, joined to what the run saw.\n *\n * Every other section of a report is an answer about *pixels*: this subject\n * against its baseline, this suite against itself. This one is the answer about\n * *cause*, and it is built from three things no diff tool holds at once — the\n * paths git named, the file graph a scanner read off disk, and the component\n * list each baseline recorded when it was painted.\n *\n * Walking the graph backwards from every changed file gives the set of\n * components an edit can possibly have moved, and the trail that carried it:\n * `app/src/tokens.css → app/src/components/ui/button.css → Button`. A subject\n * renders components, so the same walk says, per subject, whether this commit\n * could have touched it.\n *\n * ## The reason this is worth an artifact rather than a log line\n *\n * The same computation already exists one directory over as `--since`, where it\n * is used to *skip* subjects and then discarded. Skipping is a saving; this is\n * the finding. Crossed against the verdicts the run produced, reach sorts every\n * subject into four states, and two of them are questions nobody else in this\n * category can even ask:\n *\n * - **reached and changed** — the expected case, and the trail names the file.\n * - **reached and unchanged** — the edit is inert here. No diff tool asserts\n *   anything about a green subject, so the surface an author *believed* they were\n *   changing and did not is invisible everywhere else.\n * - **unreached and changed** — nothing in this commit reaches this subject, and\n *   it moved anyway. That is a flake, an input from outside the repository, or a\n *   hole in the graph, and it is a different bug in each case.\n * - **unreached and unchanged** — counted, never listed.\n *\n * The states are not stored. They are `reached × verdict`, and the verdicts are\n * already in the report; writing them down as a fifth field would be a second\n * copy of a fact that can disagree with the first.\n *\n * ## Every refusal here is louder than an answer\n *\n * A graph that cannot place a changed file cannot say what that file reaches,\n * and the difference between *this edit reaches nothing* and *this edit was not\n * understood* is the difference between a finding and a lie. So `subjects` is\n * absent rather than empty when the attribution could not be made, and `whole`\n * carries the reason in the same words the selector would have used to refuse to\n * narrow.\n */\n\n/** A component the diff reaches, and the chain that carried it there. */\nexport interface ReachedComponent {\n  readonly component: string;\n\n  /**\n   * The shortest chain from a seed to this component: seed first, component\n   * last, every step a repository-relative path but the last.\n   *\n   * Shortest because the traversal is breadth-first, so the explanation printed\n   * is the shortest true one rather than whichever a stack happened to unwind.\n   */\n  readonly trail: readonly string[];\n\n  /**\n   * Present when the chain does not begin at a file this diff named.\n   *\n   * The traversal seeds every file whose own imports could not be read, because\n   * an unreadable file may import the one that changed. A component reached only\n   * through such a file is reached by the *scan's blind spot*, not by the edit,\n   * and a trail that opened with a path nobody touched would read as an\n   * attribution.\n   */\n  readonly throughUnread?: string;\n}\n\n/** Whether this commit could have moved this subject, and through what. */\nexport interface SubjectReach {\n  readonly reached: boolean;\n\n  /**\n   * Components this subject's baseline records that the diff reaches, sorted.\n   *\n   * Empty exactly when `reached` is `false`.\n   */\n  readonly through: readonly string[];\n\n  /** The trail to the first of them. Absent when nothing was reached. */\n  readonly trail?: readonly string[];\n\n  /** One sentence, ready to print, either way it went. */\n  readonly because: string;\n}\n\n/** A file the graph holds but could not read the edges of. */\nexport interface ReachHole {\n  readonly file: string;\n  readonly because?: string;\n}\n\n/**\n * What the commit reaches, as the run recorded it.\n *\n * The half of a comparison no comparison can produce. A diff says which files an\n * author touched; the import graph says which components those files reach; the\n * suite says which subjects render those components. Put together they answer the\n * question a reviewer actually has in front of a changed screenshot — *did I do\n * this?* — and the answer is occasionally **no**, which is the strongest signal on\n * the page and one nothing that only compares pixels can ever emit.\n *\n * Every field is written so the report can say *unknown* as loudly as it says\n * *yes* and *no*. `whole` is the walk's refusal to attribute, `unscanned` the\n * files it could not parse, `opaque` the edges it could not follow, and\n * `subjects` is absent rather than empty when none of it could be attributed —\n * because a commit that was understood and reaches nothing supports the opposite\n * decision to a commit nothing could be read from.\n */\nexport interface ReachReport {\n  /** The ref the diff was taken against, in the operator's own words. */\n  readonly against: string;\n\n  /** Repository-relative paths the diff named. */\n  readonly changed: readonly string[];\n\n  /**\n   * Components the diff reaches, sorted by name.\n   *\n   * The whole answer, independent of any subject — a component here that appears\n   * in no subject's `through` is a component this suite does not watch, which is\n   * a coverage question rather than a review one.\n   */\n  readonly components: readonly ReachedComponent[];\n\n  /**\n   * Per planned subject, keyed by id. **Absent is not empty.**\n   *\n   * Absent means nothing here could be attributed and `whole` says why; every\n   * subject must then be read as possibly reached. Empty would mean the opposite\n   * — that the commit was understood and reaches none of them — and those two\n   * support opposite decisions.\n   *\n   * A subject whose baseline recorded no component list is simply not a key: the\n   * run does not know what it is made of, so it cannot say what reaches it.\n   */\n  readonly subjects?: Readonly<Record<string, SubjectReach>>;\n\n  /**\n   * Why nothing could be attributed, when nothing could.\n   *\n   * Present exactly when `subjects` is absent. A changed file under the scanned\n   * roots that the graph never saw, a diff entirely outside the graph, a diff\n   * that reaches no component at all: each of those looks identical to an edit\n   * that genuinely affects nothing, and only one of them is safe to act on.\n   */\n  readonly whole?: string;\n\n  /**\n   * Changed files under the scanned roots the graph does not hold.\n   *\n   * A gap in the scan rather than a file that affects nothing — the roots are the\n   * operator's own statement of where renders come from.\n   */\n  readonly unscanned?: readonly string[];\n\n  /**\n   * Files in the graph whose own edges could not be read, with the reason.\n   *\n   * Every one of them is traversed as though it changed. Reported because a\n   * reader who can see them can go and fix the scan; a reader who cannot sees an\n   * attribution that quietly covers more than the diff.\n   */\n  readonly opaque?: readonly ReachHole[];\n}\n"]}

package/dist/variation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * One subject read against the subject it declares itself a variation of.
+ *
+ * A flattened `Variation` from `@variance-authority/core`, for the reason
+ * {@link ChurnRecord} is a copy rather than an import: a report reader must not
+ * have to install the comparison engine to open a file. The deltas themselves
+ * are not here — a report is read by something that wants a sentence, and the
+ * bands, the components and the digest are what a sentence is made of.
+ *
+ * **This is never a verdict.** A variation is a difference somebody declared on
+ * purpose; reporting it as a regression would be reporting a subject for
+ * existing. Nothing here reaches `exitFor`, `accept` or the baseline store.
+ */
+export interface VariationRecord {
+    readonly subject: string;
+    /**
+     * The parent's subject id, once it resolved to a subject in this run.
+     *
+     * Absent when the declaration named something the run does not have — which is
+     * a state with its own sentence in `because`, and not the same claim as a
+     * variation that was compared and found identical.
+     */
+    readonly parent?: string;
+    /** `true` when both sides render to one hash: the variation changes nothing. */
+    readonly identical?: boolean;
+    /** Bands the difference falls in, in band order. Present with the comparison. */
+    readonly bands?: readonly string[];
+    /** Bands neither side's profile could decide. Absent is not "none". */
+    readonly unobserved?: readonly string[];
+    /** Components the difference was attributed to, causes first. */
+    readonly components?: readonly string[];
+    /**
+     * The identity of the difference itself, `variation/v1` over its deltas.
+     *
+     * Stable across a change that moved both subjects the same way, which is the
+     * whole reason a linked pair is worth more than two independent baselines: it
+     * distinguishes *this flag now does something else* from *everything moved*.
+     */
+    readonly digest?: string;
+    /**
+     * How the pair came to be a pair.
+     *
+     * `declared` is a tag somebody wrote. `named` is an inference from the ids: a
+     * subject whose name extends another subject's name is that subject plus an
+     * axis, which is how a suite that already encodes its variants in its names
+     * gets this for free — and is correct exactly as often as the naming
+     * convention is kept.
+     *
+     * On the record rather than derived from the presence of a tag, because the
+     * report is read by things that never saw the plan, and *a person said so* and
+     * *a name implied it* carry different weight in every sentence built from
+     * this.
+     */
+    readonly how?: 'declared' | 'named';
+    /** One sentence, ready to print, saying what this variation is or why it is not. */
+    readonly because: string;
+}
+//# sourceMappingURL=variation.d.ts.map

package/dist/variation.js

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

package/dist/variation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variation.js","sourceRoot":"","sources":["../src/variation.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * One subject read against the subject it declares itself a variation of.\n *\n * A flattened `Variation` from `@variance-authority/core`, for the reason\n * {@link ChurnRecord} is a copy rather than an import: a report reader must not\n * have to install the comparison engine to open a file. The deltas themselves\n * are not here — a report is read by something that wants a sentence, and the\n * bands, the components and the digest are what a sentence is made of.\n *\n * **This is never a verdict.** A variation is a difference somebody declared on\n * purpose; reporting it as a regression would be reporting a subject for\n * existing. Nothing here reaches `exitFor`, `accept` or the baseline store.\n */\nexport interface VariationRecord {\n  readonly subject: string;\n\n  /**\n   * The parent's subject id, once it resolved to a subject in this run.\n   *\n   * Absent when the declaration named something the run does not have — which is\n   * a state with its own sentence in `because`, and not the same claim as a\n   * variation that was compared and found identical.\n   */\n  readonly parent?: string;\n\n  /** `true` when both sides render to one hash: the variation changes nothing. */\n  readonly identical?: boolean;\n\n  /** Bands the difference falls in, in band order. Present with the comparison. */\n  readonly bands?: readonly string[];\n\n  /** Bands neither side's profile could decide. Absent is not \"none\". */\n  readonly unobserved?: readonly string[];\n\n  /** Components the difference was attributed to, causes first. */\n  readonly components?: readonly string[];\n\n  /**\n   * The identity of the difference itself, `variation/v1` over its deltas.\n   *\n   * Stable across a change that moved both subjects the same way, which is the\n   * whole reason a linked pair is worth more than two independent baselines: it\n   * distinguishes *this flag now does something else* from *everything moved*.\n   */\n  readonly digest?: string;\n\n  /**\n   * How the pair came to be a pair.\n   *\n   * `declared` is a tag somebody wrote. `named` is an inference from the ids: a\n   * subject whose name extends another subject's name is that subject plus an\n   * axis, which is how a suite that already encodes its variants in its names\n   * gets this for free — and is correct exactly as often as the naming\n   * convention is kept.\n   *\n   * On the record rather than derived from the presence of a tag, because the\n   * report is read by things that never saw the plan, and *a person said so* and\n   * *a name implied it* carry different weight in every sentence built from\n   * this.\n   */\n  readonly how?: 'declared' | 'named';\n\n  /** One sentence, ready to print, saying what this variation is or why it is not. */\n  readonly because: string;\n}\n"]}

package/mark.svg

@@ -0,0 +1,30 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 320" role="img" aria-labelledby="title desc">
+  <title id="title">Variance Authority mark</title>
+  <desc id="desc">Folded ribbon VA mark in charcoal and orange.</desc>
+
+  <defs>
+    <style>
+      .ribbon-dark {
+        fill: #24282A;
+      }
+
+      @media (prefers-color-scheme: dark) {
+        .ribbon-dark {
+          fill: #F3F4F6;
+        }
+      }
+    </style>
+  </defs>
+
+  <!-- Left descending ribbon -->
+  <path class="ribbon-dark" d="M64 54H159L256 266H160Z"/>
+
+  <!-- Right descending ribbon -->
+  <path class="ribbon-dark" d="M331 28H419L494 266H397Z"/>
+
+  <!-- Chosen / variant ribbon -->
+  <path d="M256 266L202 152L283 28H376L301 165Z" fill="#FF4A19"/>
+
+  <!-- Fold shadow -->
+  <path d="M202 152L256 266L301 165L264 103Z" fill="#D83A13" opacity="0.72"/>
+</svg>

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@variance-authority/report",
+  "version": "0.1.0",
+  "description": "The shape a Variance Authority run leaves behind, so a person, a pull request and an agent read one format.",
+  "keywords": [
+    "variance-authority",
+    "report",
+    "json",
+    "html-report",
+    "ci"
+  ],
+  "license": "MIT",
+  "author": "Machine Garden",
+  "homepage": "https://variance-authority.dev#packages",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Variance-Authority/variance-authority.git",
+    "directory": "packages/report"
+  },
+  "bugs": "https://github.com/Variance-Authority/variance-authority/issues",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./file": {
+      "types": "./dist/file.d.ts",
+      "default": "./dist/file.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/**/*.d.ts.map",
+    "mark.svg"
+  ],
+  "scripts": {
+    "build": "tsc --build"
+  },
+  "dependencies": {
+    "@variance-authority/core": "^0.1.0"
+  }
+}