@variance-authority/tribunal 0.1.0

package/dist/ui/cause.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What each change hangs from — the file, or the property, that the commit changed.
+ *
+ * The docket grouped changes by *rung*: everything the diff declares under
+ * **Edited**, everything an edited parent hands its inputs to under **Owner
+ * edited**. That is the run's ladder printed as an index, and it is a category a
+ * reviewer never has. Nobody opens a build to work through the components whose
+ * cause is one hop away. They edited three files and they want to know what each
+ * of the three did.
+ *
+ * So the row is the cause. `Button` moved because `ui/button.tsx` changed;
+ * `CardFooter` moved because `ProductCard.tsx` changed and `ProductCard` draws it
+ * through `Card`. Two rungs, one root each, and the roots are the commit —
+ * three files in, three headings out, and a reviewer who reads them has read
+ * their own change rather than a taxonomy of it.
+ *
+ * ## Why the root is a file the commit changed, and never a declaring file
+ *
+ * An owner is a root because the commit **edited** it. The file that *declares*
+ * `MainNav` is the answer to a different question, and the two paths are the same
+ * only when the commit happened to edit that file directly. Rooting under a
+ * declaration the commit never touched would open a heading nobody wrote — the
+ * page inventing a cause out of the source index — so a name whose file is not in
+ * the change set gets a root under its own name and says so.
+ *
+ * ## An origin can hang from two roots, and it hangs from both
+ *
+ * The same `Button` is `edited` on the page whose file the diff names and
+ * `upstream` on the page where a changed parent hands it a different label. That
+ * is two causes for one component, and picking one would file a render under a
+ * commit that did not produce it. It is listed under each, carrying the count of
+ * renders that root explains — which is also the shape that keeps a partial
+ * answer from reading as a whole one.
+ */
+import type { BuildDetail } from '../review-types.js';
+import type { Origin } from './grouping.js';
+/** What kind of thing a root is, which decides how a heading draws it. */
+export type RootKind = 'file' | 'token' | 'component';
+/** One change under a root, and how much of it the root accounts for. */
+export interface Rooted {
+    readonly origin: Origin;
+    /**
+     * Renders this root explains, when it is not all of them.
+     *
+     * Absent is *all of them*, and it is absent rather than equal to the length so
+     * that a row printing it has nothing to print in the ordinary case. Present
+     * means the component moved for a second reason somewhere else, and the
+     * heading above it accounts for this many of its renders and no more.
+     */
+    readonly of?: number;
+}
+/** A cause in the commit, and everything that moved because of it. */
+export interface Root {
+    readonly kind: RootKind;
+    /** The path, the custom property, or the component name. */
+    readonly name: string;
+    readonly changes: readonly Rooted[];
+    /** Renders under it, summed over the changes. */
+    readonly renders: number;
+}
+/**
+ * The commit's causes, and the changes no cause in it accounts for.
+ *
+ * `loose` is not a failure and is not small. It holds every change on a rung with
+ * nothing in the commit at the top of it — nothing reaches it, nothing explains
+ * it, the run read no diff — and those are the findings the docket ranks above
+ * everything here. They keep their own bands.
+ */
+export declare function rootsOf(origins: readonly Origin[], build: BuildDetail): {
+    readonly roots: readonly Root[];
+    readonly loose: readonly Origin[];
+};
+//# sourceMappingURL=cause.d.ts.map

package/dist/ui/cause.js

@@ -0,0 +1,133 @@
+/**
+ * What each change hangs from — the file, or the property, that the commit changed.
+ *
+ * The docket grouped changes by *rung*: everything the diff declares under
+ * **Edited**, everything an edited parent hands its inputs to under **Owner
+ * edited**. That is the run's ladder printed as an index, and it is a category a
+ * reviewer never has. Nobody opens a build to work through the components whose
+ * cause is one hop away. They edited three files and they want to know what each
+ * of the three did.
+ *
+ * So the row is the cause. `Button` moved because `ui/button.tsx` changed;
+ * `CardFooter` moved because `ProductCard.tsx` changed and `ProductCard` draws it
+ * through `Card`. Two rungs, one root each, and the roots are the commit —
+ * three files in, three headings out, and a reviewer who reads them has read
+ * their own change rather than a taxonomy of it.
+ *
+ * ## Why the root is a file the commit changed, and never a declaring file
+ *
+ * An owner is a root because the commit **edited** it. The file that *declares*
+ * `MainNav` is the answer to a different question, and the two paths are the same
+ * only when the commit happened to edit that file directly. Rooting under a
+ * declaration the commit never touched would open a heading nobody wrote — the
+ * page inventing a cause out of the source index — so a name whose file is not in
+ * the change set gets a root under its own name and says so.
+ *
+ * ## An origin can hang from two roots, and it hangs from both
+ *
+ * The same `Button` is `edited` on the page whose file the diff names and
+ * `upstream` on the page where a changed parent hands it a different label. That
+ * is two causes for one component, and picking one would file a render under a
+ * commit that did not produce it. It is listed under each, carrying the count of
+ * renders that root explains — which is also the shape that keeps a partial
+ * answer from reading as a whole one.
+ */
+/**
+ * The commit's causes, and the changes no cause in it accounts for.
+ *
+ * `loose` is not a failure and is not small. It holds every change on a rung with
+ * nothing in the commit at the top of it — nothing reaches it, nothing explains
+ * it, the run read no diff — and those are the findings the docket ranks above
+ * everything here. They keep their own bands.
+ */
+export function rootsOf(origins, build) {
+    const changedFiles = filesInCommit(build);
+    const found = new Map();
+    const loose = [];
+    for (const origin of origins) {
+        const mine = new Map();
+        for (const { movement } of origin.appearances) {
+            for (const at of rootsFor(movement, changedFiles)) {
+                mine.set(at, (mine.get(at) ?? 0) + 1);
+            }
+        }
+        if (mine.size === 0) {
+            loose.push(origin);
+            continue;
+        }
+        for (const [at, renders] of mine) {
+            const [kind, name] = split(at);
+            const root = found.get(at) ?? { kind, name, changes: [] };
+            root.changes.push({
+                origin,
+                ...(renders === origin.appearances.length ? {} : { of: renders }),
+            });
+            found.set(at, root);
+        }
+    }
+    const roots = [...found.values()]
+        .map((root) => ({
+        ...root,
+        changes: [...root.changes].sort((left, right) => left.origin.component.localeCompare(right.origin.component)),
+        renders: root.changes.reduce((total, { origin, of }) => total + (of ?? origin.appearances.length), 0),
+    }))
+        .sort((left, right) => RANK.indexOf(left.kind) - RANK.indexOf(right.kind) ||
+        left.name.localeCompare(right.name));
+    return { roots, loose };
+}
+/** Files first, then properties, then the owners whose file the commit misses. */
+const RANK = ['file', 'token', 'component'];
+function rootsFor(movement, changed) {
+    if (movement === undefined)
+        return [];
+    switch (movement.cause) {
+        case 'edited':
+            return movement.file === undefined ? [] : [at('file', movement.file)];
+        case 'token':
+            return (movement.tokens ?? []).map((token) => at('token', token));
+        case 'upstream': {
+            const owner = movement.upstream;
+            if (owner === undefined)
+                return [];
+            const file = changed.get(owner);
+            return [file === undefined ? at('component', owner) : at('file', file)];
+        }
+        default:
+            return [];
+    }
+}
+/**
+ * Each component the commit reaches, mapped to the changed file it is reached by.
+ *
+ * The reach trail's head is a path the commit changed, which is the one this
+ * needs. A component's own declaration wins when the commit changed that file
+ * too, because a heading a reviewer recognises as *the file I edited* beats the
+ * import at the top of the chain that led to it — and when the commit did not
+ * change the declaring file, that path is not a cause and is not offered as one.
+ */
+function filesInCommit(build) {
+    const changed = new Set(build.reach?.changed ?? []);
+    const found = new Map();
+    for (const entry of build.reach?.components ?? []) {
+        const head = entry.trail[0];
+        if (head !== undefined && changed.has(head))
+            found.set(entry.component, head);
+    }
+    for (const cause of build.causes) {
+        if (cause.file !== undefined && changed.has(cause.file))
+            found.set(cause.component, cause.file);
+    }
+    return found;
+}
+// The same separator, and for the same reason, as `attribution.ts`: a kind and a
+// name joined by anything either half can contain is two roots that can collide.
+// Written as the escape rather than as the byte, so the file stays greppable.
+const IN = '\u0000';
+function at(kind, name) {
+    return `${kind}${IN}${name}`;
+}
+function split(key) {
+    const cut = key.indexOf(IN);
+    return [key.slice(0, cut), key.slice(cut + 1)];
+}
+//# sourceMappingURL=cause.js.map

package/dist/ui/cause.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cause.js","sourceRoot":"","sources":["../../src/ui/cause.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What each change hangs from — the file, or the property, that the commit changed.\n *\n * The docket grouped changes by *rung*: everything the diff declares under\n * **Edited**, everything an edited parent hands its inputs to under **Owner\n * edited**. That is the run's ladder printed as an index, and it is a category a\n * reviewer never has. Nobody opens a build to work through the components whose\n * cause is one hop away. They edited three files and they want to know what each\n * of the three did.\n *\n * So the row is the cause. `Button` moved because `ui/button.tsx` changed;\n * `CardFooter` moved because `ProductCard.tsx` changed and `ProductCard` draws it\n * through `Card`. Two rungs, one root each, and the roots are the commit —\n * three files in, three headings out, and a reviewer who reads them has read\n * their own change rather than a taxonomy of it.\n *\n * ## Why the root is a file the commit changed, and never a declaring file\n *\n * An owner is a root because the commit **edited** it. The file that *declares*\n * `MainNav` is the answer to a different question, and the two paths are the same\n * only when the commit happened to edit that file directly. Rooting under a\n * declaration the commit never touched would open a heading nobody wrote — the\n * page inventing a cause out of the source index — so a name whose file is not in\n * the change set gets a root under its own name and says so.\n *\n * ## An origin can hang from two roots, and it hangs from both\n *\n * The same `Button` is `edited` on the page whose file the diff names and\n * `upstream` on the page where a changed parent hands it a different label. That\n * is two causes for one component, and picking one would file a render under a\n * commit that did not produce it. It is listed under each, carrying the count of\n * renders that root explains — which is also the shape that keeps a partial\n * answer from reading as a whole one.\n */\n\nimport type { BuildDetail, MovementView } from '../review-types.js';\nimport type { Origin } from './grouping.js';\n\n/** What kind of thing a root is, which decides how a heading draws it. */\nexport type RootKind = 'file' | 'token' | 'component';\n\n/** One change under a root, and how much of it the root accounts for. */\nexport interface Rooted {\n  readonly origin: Origin;\n  /**\n   * Renders this root explains, when it is not all of them.\n   *\n   * Absent is *all of them*, and it is absent rather than equal to the length so\n   * that a row printing it has nothing to print in the ordinary case. Present\n   * means the component moved for a second reason somewhere else, and the\n   * heading above it accounts for this many of its renders and no more.\n   */\n  readonly of?: number;\n}\n\n/** A cause in the commit, and everything that moved because of it. */\nexport interface Root {\n  readonly kind: RootKind;\n  /** The path, the custom property, or the component name. */\n  readonly name: string;\n  readonly changes: readonly Rooted[];\n  /** Renders under it, summed over the changes. */\n  readonly renders: number;\n}\n\n/**\n * The commit's causes, and the changes no cause in it accounts for.\n *\n * `loose` is not a failure and is not small. It holds every change on a rung with\n * nothing in the commit at the top of it — nothing reaches it, nothing explains\n * it, the run read no diff — and those are the findings the docket ranks above\n * everything here. They keep their own bands.\n */\nexport function rootsOf(\n  origins: readonly Origin[],\n  build: BuildDetail,\n): { readonly roots: readonly Root[]; readonly loose: readonly Origin[] } {\n  const changedFiles = filesInCommit(build);\n  const found = new Map<string, { kind: RootKind; name: string; changes: Rooted[] }>();\n  const loose: Origin[] = [];\n\n  for (const origin of origins) {\n    const mine = new Map<string, number>();\n    for (const { movement } of origin.appearances) {\n      for (const at of rootsFor(movement, changedFiles)) {\n        mine.set(at, (mine.get(at) ?? 0) + 1);\n      }\n    }\n\n    if (mine.size === 0) {\n      loose.push(origin);\n      continue;\n    }\n\n    for (const [at, renders] of mine) {\n      const [kind, name] = split(at);\n      const root = found.get(at) ?? { kind, name, changes: [] };\n      root.changes.push({\n        origin,\n        ...(renders === origin.appearances.length ? {} : { of: renders }),\n      });\n      found.set(at, root);\n    }\n  }\n\n  const roots = [...found.values()]\n    .map((root) => ({\n      ...root,\n      changes: [...root.changes].sort((left, right) =>\n        left.origin.component.localeCompare(right.origin.component),\n      ),\n      renders: root.changes.reduce(\n        (total, { origin, of }) => total + (of ?? origin.appearances.length),\n        0,\n      ),\n    }))\n    .sort(\n      (left, right) => RANK.indexOf(left.kind) - RANK.indexOf(right.kind) ||\n        left.name.localeCompare(right.name),\n    );\n\n  return { roots, loose };\n}\n\n/** Files first, then properties, then the owners whose file the commit misses. */\nconst RANK: readonly RootKind[] = ['file', 'token', 'component'];\n\nfunction rootsFor(\n  movement: MovementView | undefined,\n  changed: ReadonlyMap<string, string>,\n): readonly string[] {\n  if (movement === undefined) return [];\n\n  switch (movement.cause) {\n    case 'edited':\n      return movement.file === undefined ? [] : [at('file', movement.file)];\n    case 'token':\n      return (movement.tokens ?? []).map((token) => at('token', token));\n    case 'upstream': {\n      const owner = movement.upstream;\n      if (owner === undefined) return [];\n      const file = changed.get(owner);\n      return [file === undefined ? at('component', owner) : at('file', file)];\n    }\n    default:\n      return [];\n  }\n}\n\n/**\n * Each component the commit reaches, mapped to the changed file it is reached by.\n *\n * The reach trail's head is a path the commit changed, which is the one this\n * needs. A component's own declaration wins when the commit changed that file\n * too, because a heading a reviewer recognises as *the file I edited* beats the\n * import at the top of the chain that led to it — and when the commit did not\n * change the declaring file, that path is not a cause and is not offered as one.\n */\nfunction filesInCommit(build: BuildDetail): ReadonlyMap<string, string> {\n  const changed = new Set(build.reach?.changed ?? []);\n  const found = new Map<string, string>();\n\n  for (const entry of build.reach?.components ?? []) {\n    const head = entry.trail[0];\n    if (head !== undefined && changed.has(head)) found.set(entry.component, head);\n  }\n  for (const cause of build.causes) {\n    if (cause.file !== undefined && changed.has(cause.file)) found.set(cause.component, cause.file);\n  }\n\n  return found;\n}\n\n// The same separator, and for the same reason, as `attribution.ts`: a kind and a\n// name joined by anything either half can contain is two roots that can collide.\n// Written as the escape rather than as the byte, so the file stays greppable.\nconst IN = '\\u0000';\n\nfunction at(kind: RootKind, name: string): string {\n  return `${kind}${IN}${name}`;\n}\n\nfunction split(key: string): [RootKind, string] {\n  const cut = key.indexOf(IN);\n  return [key.slice(0, cut) as RootKind, key.slice(cut + 1)];\n}\n"]}

package/dist/ui/change-story.d.ts

@@ -0,0 +1,153 @@
+/**
+ * What the record says about one change, before anybody decides it.
+ *
+ * Seven readings, and not one of them is an act. [`change.tsx`](./change.tsx)
+ * holds the page and the two buttons; this holds every sentence printed above
+ * them, which is the half that has to be argued rather than wired — what counts
+ * as *reached*, what a silence is allowed to imply, and which of two absences a
+ * reviewer is looking at. Splitting them keeps the argument readable and stops
+ * the page that carries the decision from being mostly prose about it.
+ *
+ * The rule they share: absent is not empty. A run that read no diff, a component
+ * the source index does not declare, a render nobody wrote a reach row for and a
+ * build that counted no collateral each get their own sentence or no sentence at
+ * all, because the alternative is spending this product’s loudest line on its
+ * most ordinary fact and training the reader out of it.
+ */
+import { type ReactElement } from 'react';
+import type { BuildDetail } from '../review-types.js';
+import type { ReviewClient } from './client.js';
+import type { Crossing } from './crossing.js';
+import { type Origin } from './grouping.js';
+/**
+ * Three counts, because the reviewer asks three questions and they differ.
+ *
+ * *2 distinct differences, in 7 renders* is two of them run together, and the
+ * third — how many of those a press of the button actually settles — was in the
+ * button's own label, at the other end of the header. The three come apart on
+ * every change of any size: a component moves in twelve renders, five of which
+ * the docket filed under somebody else; the twelve carry two distinct shapes, so
+ * there are two pictures to look at rather than twelve; and seven are open here,
+ * because the rest are decided or belong to the other change.
+ *
+ * Kept as three cells with the reviewer's own words on them rather than folded
+ * into a sentence. A sentence has to pick an order and an emphasis, and these
+ * are three answers of equal standing.
+ *
+ * The pixel total rides along, muted. It is the least useful figure available —
+ * one number for every size of change — and it is the one somebody eventually
+ * asks for.
+ */
+export declare function Tally({ origin, elsewhere, open, }: {
+    readonly origin: Origin;
+    /** Renders it moved in that another change owns, and is decided under. */
+    readonly elsewhere: number;
+    /** Renders here a press settles: undecided, and approvable. */
+    readonly open: number;
+}): ReactElement;
+/**
+ * Where this component is declared, and what it means when nothing says.
+ *
+ * A blank is the one answer this cell must not give. The reviewer's next move on
+ * a change they do not recognise is to open the file, and *nothing here* reads as
+ * a defect in the tool — when the ordinary cause is that the name belongs to a
+ * dependency, which the source index scans no part of and never claimed to. So
+ * the two silences are separated: a run that resolved files for other components
+ * has said something about this one, and a run that resolved none has not.
+ */
+export declare function Declared({ file, sourced, }: {
+    readonly file?: string | undefined;
+    readonly sourced: boolean;
+}): ReactElement;
+/**
+ * Whether the commit arrives here, said in five states rather than two.
+ *
+ * A run with no diff read cannot say, and saying nothing is the only honest
+ * version of that. Silence would be indistinguishable from *reached*, which is
+ * the assumption a reviewer makes by default and the one that costs them.
+ *
+ * The last of the five is now conditional: it is a reconstruction, and it stands
+ * down where the run recorded a conclusion of its own. See the branch below.
+ *
+ * The rest is the split this card got wrong twice. `reached` is computed against
+ * the components the diff can arrive at, so a component the graph carries nowhere
+ * — anything out of `node_modules`, which is most of the host nodes on a real
+ * page — can never be in that set whatever the commit did. And a render the reach
+ * record has no row for is not a render the commit fails to reach; it is a render
+ * nobody wrote down. Printing *nothing reaches it and it moved anyway* over
+ * either of those spends the loudest sentence on the page on the most ordinary
+ * fact about it, and by the time a real orphan appears the sentence has been
+ * trained out of the reader.
+ */
+export declare function Arrival({ origin }: {
+    readonly origin: Origin;
+}): ReactElement | null;
+/**
+ * What the run before this one had to say about these renders.
+ *
+ * The sentence a reviewer skips work on, and the reason it is here rather than in
+ * the crossing panel: *build 5 already showed you this, and nobody decided it* is
+ * worth reading beside the change it is about and worth nothing at the bottom of
+ * a page about twenty other subjects. The undecided count is the part that is
+ * never printed anywhere else — it is the docket being delivered twice.
+ */
+export declare function SinceLast({ crossing, origin, }: {
+    readonly crossing: Crossing;
+    readonly origin: Origin;
+}): ReactElement | null;
+/**
+ * Where this change's renders stopped agreeing with each other.
+ *
+ * A change is approved once and lands many times, and the count above reads as
+ * one thing having happened seven times. On a component with two shapes it is
+ * two things: two renders moved by 6,418 pixels and five by about 3,500, and a
+ * reviewer pressing approve is signing off on both under one name.
+ *
+ * So the groups are drawn, largest first, with what each one is worth in pixels
+ * and the name its renders share when that name is theirs alone. The digest goes
+ * beside each group rather than in the prose, because `variance accept --shape`
+ * takes exactly that set in the next run and a reviewer who has decided one of
+ * the two groups is holding the argument for it.
+ */
+export declare function Shapes({ origin }: {
+    readonly origin: Origin;
+}): ReactElement | null;
+/**
+ * How often this component moves, asked on mount: there is one change on this page.
+ *
+ * Named for the question rather than the call, and not `Record`, which is a
+ * global type every other file in this package is entitled to use.
+ */
+export declare function Recurrence({ client, component, }: {
+    readonly client: ReviewClient;
+    readonly component: string;
+}): ReactElement | null;
+/**
+ * Collateral, and nothing at all when the build did not count it.
+ *
+ * One number for the whole build, repeated onto every cause row by the store —
+ * which is exactly why it is printed once, here, and never attributed to a
+ * change. Deciding which edit pushed which box around is the attribution the
+ * semantic tier declined to make. The guard is the rule: a build with no causes
+ * has not counted zero collateral pixels, it has counted none, and `0 collateral
+ * pixels` reads as a measurement.
+ */
+export declare function Collateral({ build }: {
+    readonly build: BuildDetail;
+}): ReactElement | null;
+/**
+ * What a band claim is made of, said once on the page that makes them.
+ *
+ * Asked directly, about `what it announces`: *how do you know?* The page had no
+ * answer on it. It knows because two digests disagree, and the digest is over the
+ * role, name and state of every node inside the boundary — which is enough to
+ * assert the band and not enough to say what the name became, because the
+ * baseline sidecar stores the hash and not the value.
+ *
+ * At the foot rather than beside every band, because it is the same sentence for
+ * all of them and a reviewer needs it once. Not behind a disclosure: the whole
+ * complaint that produced it was a page processing its results and hiding what
+ * they were made from.
+ */
+export declare function Evidence(): ReactElement;
+//# sourceMappingURL=change-story.d.ts.map

package/dist/ui/change-story.js

@@ -0,0 +1,253 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * What the record says about one change, before anybody decides it.
+ *
+ * Seven readings, and not one of them is an act. [`change.tsx`](./change.tsx)
+ * holds the page and the two buttons; this holds every sentence printed above
+ * them, which is the half that has to be argued rather than wired — what counts
+ * as *reached*, what a silence is allowed to imply, and which of two absences a
+ * reviewer is looking at. Splitting them keeps the argument readable and stops
+ * the page that carries the decision from being mostly prose about it.
+ *
+ * The rule they share: absent is not empty. A run that read no diff, a component
+ * the source index does not declare, a render nobody wrote a reach row for and a
+ * build that counted no collateral each get their own sentence or no sentence at
+ * all, because the alternative is spending this product’s loudest line on its
+ * most ordinary fact and training the reader out of it.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { shapesOf } from './grouping.js';
+import { partedBy } from './parted.js';
+import { ChurnLine } from './history.js';
+import { ORDER, READS, senseOf } from './sense.js';
+import { count, number } from './text.js';
+/**
+ * Three counts, because the reviewer asks three questions and they differ.
+ *
+ * *2 distinct differences, in 7 renders* is two of them run together, and the
+ * third — how many of those a press of the button actually settles — was in the
+ * button's own label, at the other end of the header. The three come apart on
+ * every change of any size: a component moves in twelve renders, five of which
+ * the docket filed under somebody else; the twelve carry two distinct shapes, so
+ * there are two pictures to look at rather than twelve; and seven are open here,
+ * because the rest are decided or belong to the other change.
+ *
+ * Kept as three cells with the reviewer's own words on them rather than folded
+ * into a sentence. A sentence has to pick an order and an emphasis, and these
+ * are three answers of equal standing.
+ *
+ * The pixel total rides along, muted. It is the least useful figure available —
+ * one number for every size of change — and it is the one somebody eventually
+ * asks for.
+ */
+export function Tally({ origin, elsewhere, open, }) {
+    const shapes = shapesOf(origin.appearances).size;
+    const know = origin.appearances.length + elsewhere;
+    return (_jsxs("p", { className: "va-tally", children: [_jsxs("span", { title: "Every render this component moved in, wherever the docket filed it.", children: [_jsx("strong", { children: count(know, 'render') }), " to know about"] }), _jsx("span", { title: "Distinct shapes among the renders on this page \u2014 how many pictures there are to look at, rather than how many renders carry them.", children: shapes === 0 ? (_jsxs(_Fragment, { children: [_jsx("strong", { children: "no shape" }), " was recorded, so nothing says whether these moved the same way"] })) : (_jsxs(_Fragment, { children: [_jsx("strong", { children: count(shapes, 'difference') }), " to review"] })) }), _jsx("span", { title: "Renders on this page that are open and approvable \u2014 what pressing approve settles.", children: open === 0 ? (_jsxs(_Fragment, { children: [_jsx("strong", { children: "nothing" }), " left to accept"] })) : (_jsxs(_Fragment, { children: [_jsx("strong", { children: count(open, 'render') }), " to accept"] })) }), _jsxs("span", { className: "va-note", children: [number(origin.pixels), " px"] })] }));
+}
+/**
+ * Where this component is declared, and what it means when nothing says.
+ *
+ * A blank is the one answer this cell must not give. The reviewer's next move on
+ * a change they do not recognise is to open the file, and *nothing here* reads as
+ * a defect in the tool — when the ordinary cause is that the name belongs to a
+ * dependency, which the source index scans no part of and never claimed to. So
+ * the two silences are separated: a run that resolved files for other components
+ * has said something about this one, and a run that resolved none has not.
+ */
+export function Declared({ file, sourced, }) {
+    if (file !== undefined)
+        return _jsx("code", { className: "va-file", children: file });
+    return (_jsx("span", { className: "va-note", title: sourced
+            ? 'This run resolved files for other components in this build, so this is a name its source index does not declare — a component out of a dependency, or one produced at build time.'
+            : 'This run resolved no source files at all, so nothing here says where any of these components are declared.', children: sourced ? 'not in the scanned source' : 'no source index' }));
+}
+/**
+ * Whether the commit arrives here, said in five states rather than two.
+ *
+ * A run with no diff read cannot say, and saying nothing is the only honest
+ * version of that. Silence would be indistinguishable from *reached*, which is
+ * the assumption a reviewer makes by default and the one that costs them.
+ *
+ * The last of the five is now conditional: it is a reconstruction, and it stands
+ * down where the run recorded a conclusion of its own. See the branch below.
+ *
+ * The rest is the split this card got wrong twice. `reached` is computed against
+ * the components the diff can arrive at, so a component the graph carries nowhere
+ * — anything out of `node_modules`, which is most of the host nodes on a real
+ * page — can never be in that set whatever the commit did. And a render the reach
+ * record has no row for is not a render the commit fails to reach; it is a render
+ * nobody wrote down. Printing *nothing reaches it and it moved anyway* over
+ * either of those spends the loudest sentence on the page on the most ordinary
+ * fact about it, and by the time a real orphan appears the sentence has been
+ * trained out of the reader.
+ */
+export function Arrival({ origin }) {
+    if (origin.reached === undefined)
+        return null;
+    if (origin.reached) {
+        const trail = origin.trail;
+        return (_jsx("p", { className: "va-reaches va-reached", children: trail === undefined ? ('This commit reaches it.') : (_jsxs(_Fragment, { children: ["This commit reaches it:", ' ', trail.map((step, index) => (_jsxs("span", { children: [index === 0 ? null : _jsx("span", { className: "va-arrow", children: "\u2192" }), index === trail.length - 1 ? _jsx("strong", { children: step }) : _jsx("code", { children: step })] }, step)))] })) }));
+    }
+    const stranded = origin.stranded ?? [];
+    const unlisted = origin.unlisted ?? [];
+    const through = origin.through ?? [];
+    if (stranded.length > 0) {
+        return (_jsxs("p", { className: "va-reaches va-alarm", children: ["This commit reaches nothing at all in ", count(stranded.length, 'render'), " it moved in \u2014", ' ', stranded.slice(0, 3).join(', '), stranded.length > 3 ? `, and ${count(stranded.length - 3, 'other')}` : '', ". Something changed there that the diff cannot account for."] }));
+    }
+    // The run's own conclusion supersedes the rest of this, and `Because` has
+    // already printed it directly above. What follows is a reconstruction from the
+    // reach record alone — and on a component the import walk merely climbed past,
+    // it reads *this comes from a dependency* about a file named at the top of this
+    // same page. The one thing it says that the conclusion does not is the gap in
+    // the record, so that is what survives.
+    if (origin.cause !== undefined) {
+        return unlisted.length === 0 ? null : (_jsx("p", { className: "va-reaches va-unnamed", children: _jsx(Unlisted, { renders: unlisted.length }) }));
+    }
+    return (_jsxs("p", { className: "va-reaches va-unnamed", children: ["The commit reaches nothing called ", _jsx("strong", { children: origin.component }), " \u2014 the file graph carries no such name, which is what a component out of a dependency looks like from here.", ' ', through.length === 0
+                ? 'It does reach every render this moved in, without naming a component in any of them.'
+                : `It does reach every render this moved in, through ${through.slice(0, 4).join(', ')}${through.length > 4 ? ` and ${count(through.length - 4, 'other')}` : ''} — so either one of those drew this node, or something reaches it that the graph does not model.`, unlisted.length === 0 ? null : (_jsxs(_Fragment, { children: [' ', _jsx(Unlisted, { renders: unlisted.length })] }))] }));
+}
+/**
+ * The renders the reach record has no row for.
+ *
+ * Not *the commit does not reach these*. Nobody wrote them down, and a page that
+ * folded the two together would report a gap in its own record as a finding about
+ * the commit.
+ */
+function Unlisted({ renders }) {
+    return (_jsxs(_Fragment, { children: [count(renders, 'render'), " it moved in ", renders === 1 ? 'has' : 'have', " no reach recorded at all, so nothing the commit reaches was ever weighed against", ' ', renders === 1 ? 'it' : 'them', "."] }));
+}
+/**
+ * What the run before this one had to say about these renders.
+ *
+ * The sentence a reviewer skips work on, and the reason it is here rather than in
+ * the crossing panel: *build 5 already showed you this, and nobody decided it* is
+ * worth reading beside the change it is about and worth nothing at the bottom of
+ * a page about twenty other subjects. The undecided count is the part that is
+ * never printed anywhere else — it is the docket being delivered twice.
+ */
+export function SinceLast({ crossing, origin, }) {
+    if (crossing.state !== 'ready')
+        return null;
+    const rows = origin.appearances
+        .map(({ subject }) => crossing.of(subject.subject))
+        .filter((row) => row !== undefined);
+    if (rows.length === 0)
+        return null;
+    const against = `build ${crossing.earlier.build}`;
+    const seen = rows.filter((row) => row.shift === 'again');
+    const undecided = seen.filter((row) => row.earlier?.decision == null).length;
+    const moved = rows.filter((row) => row.shift === 'differently').length;
+    const first = rows.filter((row) => row.shift === 'first').length;
+    const fresh = rows.filter((row) => row.shift === 'new').length;
+    if (seen.length === 0 && moved === 0 && first === 0 && fresh === 0)
+        return null;
+    return (_jsxs("p", { className: seen.length > 0 ? 'va-since va-known' : 'va-since', children: [seen.length === 0 ? null : (_jsxs(_Fragment, { children: [seen.length === rows.length ? 'Every one of these' : count(seen.length, 'of these'), ' ', "carried the same difference in ", against, undecided === 0
+                        ? ', and every one was decided there.'
+                        : undecided === seen.length
+                            ? ', and none of them was decided there.'
+                            : `, and ${number(undecided)} of them went undecided there.`, ' '] })), moved === 0 ? null : (_jsxs(_Fragment, { children: [count(moved, 'render'), " differed in ", against, " too, but not in the same way: the difference itself changed between the two builds.", ' '] })), first === 0 ? null : (_jsxs(_Fragment, { children: [count(first, 'render'), " moved for the first time; ", against, " compared", ' ', first === 1 ? 'it' : 'them', " and found nothing.", ' '] })), fresh === 0 ? null : _jsxs(_Fragment, { children: [count(fresh, 'render'), " did not exist in ", against, "."] })] }));
+}
+/**
+ * A shape at reading length, with the whole of it a hover away.
+ *
+ * The digest is thirty-two hexadecimal characters and a reviewer needs none of
+ * them: it is an identity, and an identity is only ever typed by copying it. A
+ * prefix says *this one and not that one* on a page that never shows two, which
+ * is the whole of the job the full string was doing on the surface.
+ */
+function brief(shape) {
+    return shape.length <= 14 ? shape : `${shape.slice(0, 14)}…`;
+}
+/**
+ * Where this change's renders stopped agreeing with each other.
+ *
+ * A change is approved once and lands many times, and the count above reads as
+ * one thing having happened seven times. On a component with two shapes it is
+ * two things: two renders moved by 6,418 pixels and five by about 3,500, and a
+ * reviewer pressing approve is signing off on both under one name.
+ *
+ * So the groups are drawn, largest first, with what each one is worth in pixels
+ * and the name its renders share when that name is theirs alone. The digest goes
+ * beside each group rather than in the prose, because `variance accept --shape`
+ * takes exactly that set in the next run and a reviewer who has decided one of
+ * the two groups is holding the argument for it.
+ */
+export function Shapes({ origin }) {
+    const { shapes, unshaped } = partedBy(origin);
+    if (shapes.length === 0)
+        return null;
+    const only = shapes.length === 1 && unshaped.length === 0 ? shapes[0] : undefined;
+    if (only !== undefined) {
+        return (_jsxs("p", { className: "va-note", children: ["The same difference in every one of the ", count(origin.appearances.length, 'render'), ".", ' ', _jsxs("code", { title: only.shape, children: ["variance accept --shape ", brief(only.shape)] }), " takes exactly this set."] }));
+    }
+    return (_jsxs("section", { className: "va-parted", children: [_jsxs("h2", { children: [count(shapes.length, 'shape'), " over ", count(origin.appearances.length, 'render')] }), _jsx("ul", { children: shapes.map((each) => (_jsxs("li", { children: [_jsxs("p", { className: "va-parted-head", children: [_jsxs("span", { className: "va-num", children: [span(each.least, each.most), " px"] }), each.only === undefined ? null : _jsx("span", { className: "va-parted-only", children: each.only }), _jsxs("code", { className: "va-parted-take", title: each.shape, children: ["--shape ", brief(each.shape)] })] }), _jsx("p", { className: "va-parted-in va-note", children: each.renders.join(', ') })] }, each.shape))) }), unshaped.length === 0 ? null : (_jsxs("p", { className: "va-note", children: [count(unshaped.length, 'render'), " recorded no shape, so they are not known to match anything here: ", unshaped.join(', '), "."] }))] }));
+}
+/** One figure when the group is flat, two when the renders differ in size. */
+function span(least, most) {
+    return least === most ? number(least) : `${number(least)}–${number(most)}`;
+}
+/**
+ * How often this component moves, asked on mount: there is one change on this page.
+ *
+ * Named for the question rather than the call, and not `Record`, which is a
+ * global type every other file in this package is entitled to use.
+ */
+export function Recurrence({ client, component, }) {
+    const [churn, setChurn] = useState(null);
+    const load = useCallback(async () => {
+        try {
+            setChurn(await client.churn(component));
+        }
+        catch {
+            // A missing record is a silence this page can afford. Everything above it
+            // is a reading of this build, and none of it becomes less true because the
+            // history service did not answer.
+            setChurn(null);
+        }
+    }, [client, component]);
+    useEffect(() => {
+        void load();
+    }, [load]);
+    // `0 of 0 runs` on every change is the shape of an answer with none of the
+    // substance, and this is a reading of *this* build — history is an addition
+    // where there is history, not a line that has to be filled.
+    if (churn === null || churn.runs === 0)
+        return null;
+    return _jsx(ChurnLine, { component: component, churn: churn });
+}
+/**
+ * Collateral, and nothing at all when the build did not count it.
+ *
+ * One number for the whole build, repeated onto every cause row by the store —
+ * which is exactly why it is printed once, here, and never attributed to a
+ * change. Deciding which edit pushed which box around is the attribution the
+ * semantic tier declined to make. The guard is the rule: a build with no causes
+ * has not counted zero collateral pixels, it has counted none, and `0 collateral
+ * pixels` reads as a measurement.
+ */
+export function Collateral({ build }) {
+    const pixels = build.causes[0]?.collateralPixels;
+    if (pixels === undefined || pixels === 0)
+        return null;
+    return (_jsxs("p", { className: "va-note va-collateral-note", children: [count(pixels, 'collateral pixel'), " moved in this build alongside the changes \u2014 regions that shifted because something else did. Counted for the build, never split between the changes."] }));
+}
+/**
+ * What a band claim is made of, said once on the page that makes them.
+ *
+ * Asked directly, about `what it announces`: *how do you know?* The page had no
+ * answer on it. It knows because two digests disagree, and the digest is over the
+ * role, name and state of every node inside the boundary — which is enough to
+ * assert the band and not enough to say what the name became, because the
+ * baseline sidecar stores the hash and not the value.
+ *
+ * At the foot rather than beside every band, because it is the same sentence for
+ * all of them and a reviewer needs it once. Not behind a disclosure: the whole
+ * complaint that produced it was a page processing its results and hiding what
+ * they were made from.
+ */
+export function Evidence() {
+    return (_jsxs("p", { className: "va-evidence", children: ["Each band is a digest comparison \u2014", ' ', ORDER.filter((band) => band !== 'texture').map((band, index) => (_jsxs("span", { children: [index === 0 ? '' : '; ', _jsx("em", { children: senseOf(band) }), " over ", READS[band]] }, band))), ". The baseline keeps the digests and not the values, so a band names which of them differ and not what they became."] }));
+}
+//# sourceMappingURL=change-story.js.map