@variance-authority/core 0.1.0

package/dist/judge/docket.js

@@ -0,0 +1,162 @@
+import { loudestBand } from '../compare/band.js';
+import { aggregateImpact } from '../compare/impact.js';
+export function buildDocket(diffs, options = {}) {
+    const sampleSize = options.sampleSize ?? 3;
+    const groups = new Map();
+    for (const diff of diffs) {
+        if (diff.identical)
+            continue;
+        for (const root of diff.roots) {
+            const entry = groups.get(root.id) ?? newAccumulator(root);
+            groups.set(root.id, entry);
+            entry.subjects.add(diff.subjectId);
+            entry.deltas.push(...root.deltas);
+            for (const component of componentsUnder(root, diff.components)) {
+                mergeComponent(entry.components, component);
+            }
+        }
+    }
+    const entries = [...groups.values()]
+        .map((entry) => finalize(entry, sampleSize))
+        // Widest blast radius first: a root touching forty subjects is the review,
+        // and one touching a single subject is a detail underneath it.
+        .sort((a, b) => b.subjectCount - a.subjectCount || b.deltaCount - a.deltaCount);
+    const changed = diffs.filter((diff) => !diff.identical).length;
+    return {
+        entries,
+        subjectsCompared: diffs.length,
+        subjectsUnchanged: diffs.length - changed,
+        subjectsChanged: changed,
+        singleRoot: entries.length === 1,
+    };
+}
+/**
+ * The docket as one sentence per entry.
+ *
+ * Deliberately terse. The audience is a reviewer deciding whether to look
+ * further and an agent deciding whether to act, and both are worse served by a
+ * paragraph than by a line they can scan.
+ */
+export function summarize(docket) {
+    if (docket.entries.length === 0) {
+        return `${docket.subjectsCompared} subjects compared, nothing changed.`;
+    }
+    const header = `${docket.subjectsChanged} of ${docket.subjectsCompared} subjects changed, ` +
+        `explained by ${docket.entries.length} root${docket.entries.length === 1 ? '' : 's'}.`;
+    const lines = docket.entries.map((entry) => {
+        const reach = entry.subjectCount === 1
+            ? `${entry.deltaCount} change${entry.deltaCount === 1 ? '' : 's'}`
+            : `${entry.subjectCount} subjects, ${entry.deltaCount} collateral`;
+        const structure = entry.structureIntact ? 'structure intact' : 'structure changed';
+        const components = entry.components.length > 0
+            ? ` — ${entry.components
+                .slice(0, 4)
+                .map((component) => component.name)
+                .join(', ')}`
+            : '';
+        return (`  ${entry.kind}: ${entry.label} — ${reach}, ${entry.band}/${entry.impact}, ` +
+            `${structure}${components}`);
+    });
+    return [header, ...lines].join('\n');
+}
+function newAccumulator(root) {
+    return { root, subjects: new Set(), deltas: [], components: new Map() };
+}
+function finalize(entry, sampleSize) {
+    const subjects = [...entry.subjects];
+    return {
+        rootId: entry.root.id,
+        kind: entry.root.kind,
+        label: entry.root.label,
+        // The root's own band is a floor, not the answer. A token edit whose
+        // collateral includes a dropped accessible name is reported at `a11y`: the
+        // entry is one review action, so it must be labelled by the loudest thing a
+        // reviewer would be signing off on, not by the thing that caused it.
+        band: loudestBand([entry.root.band, ...entry.deltas.map((delta) => delta.band)]) ?? entry.root.band,
+        impact: aggregateImpact(entry.deltas.map((delta) => delta.impact ?? 'structural')),
+        subjects,
+        subjectCount: subjects.length,
+        deltaCount: entry.deltas.length,
+        components: [...entry.components.values()]
+            .map((component) => ({
+            name: component.name,
+            role: component.role,
+            deltaCount: component.deltaCount,
+            bands: [...component.bands],
+            impact: aggregateImpact(component.impacts),
+            renderedIn: [...component.renderedIn],
+        }))
+            .sort((a, b) => b.deltaCount - a.deltaCount || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+        sample: subjects.slice(0, sampleSize),
+        places: rankedPlaces(entry.deltas),
+        structureIntact: !entry.deltas.some(isStructural),
+    };
+}
+/** Distinct `where` phrases, most frequent first, capped. */
+function rankedPlaces(deltas) {
+    const counts = new Map();
+    for (const delta of deltas) {
+        if (delta.where === undefined || delta.where === '')
+            continue;
+        counts.set(delta.where, (counts.get(delta.where) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .map(([where]) => where);
+}
+/**
+ * Whether a delta changed the shape of the tree rather than a value.
+ *
+ * A `rect-changed` that was *derived* from a style change does not count: the
+ * box moved because a value moved, and calling that a structural change would
+ * make every spacing token look like it rearranged the page.
+ */
+function isStructural(delta) {
+    switch (delta.kind) {
+        case 'node-added':
+        case 'node-removed':
+        case 'node-moved':
+        case 'role-changed':
+        case 'name-changed':
+        case 'text-changed':
+            return true;
+        case 'rect-changed':
+            return delta.derivedFrom === undefined;
+        default:
+            return false;
+    }
+}
+/** Components that appear in this root's deltas, from the subject's own view. */
+function componentsUnder(root, components) {
+    const names = new Set();
+    for (const delta of root.deltas) {
+        for (const owner of delta.owners ?? [])
+            names.add(owner.name);
+    }
+    return components.filter((component) => names.has(component.name));
+}
+function mergeComponent(into, component) {
+    const existing = into.get(component.name);
+    if (!existing) {
+        into.set(component.name, {
+            name: component.name,
+            role: component.role,
+            deltaCount: component.deltaCount,
+            bands: new Set(component.bands),
+            impacts: [],
+            renderedIn: new Set(component.renderedIn),
+        });
+        return;
+    }
+    existing.deltaCount += component.deltaCount;
+    for (const band of component.bands)
+        existing.bands.add(band);
+    for (const parent of component.renderedIn)
+        existing.renderedIn.add(parent);
+    // Root in any subject means root: a component that changed internally
+    // somewhere is a cause, even if elsewhere it was only along for the ride.
+    if (component.role === 'root')
+        existing.role = 'root';
+}
+//# sourceMappingURL=docket.js.map

package/dist/judge/docket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docket.js","sourceRoot":"","sources":["../../src/judge/docket.ts"],"names":[],"mappings":"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","sourcesContent":["import { loudestBand, type Band } from '../compare/band.js';\nimport type { ChangedComponent, Delta, Root, RootKind, SemanticDiff } from '../compare/diff/index.js';\nimport { aggregateImpact, type AggregateImpact, type PropertyImpact } from '../compare/impact.js';\n\n/**\n * The docket: one entry per root cause, across every subject in a change set.\n *\n * A `SemanticDiff` answers \"what changed in this subject\". That is the wrong unit\n * for review, and reviewing at that unit is what makes visual regression\n * unbearable — one design-token edit arrives as three hundred separate subjects\n * to click through, and the three-hundred-and-first gets approved without being\n * read.\n *\n * The docket inverts it. One token edit is **one entry**, carrying the count of\n * what it reached. Spec §6.2 requires that approving it be a single action, which\n * is only possible if the thing being approved is the cause rather than each of\n * its effects.\n *\n * Aggregation is by root **id**, which is why root ids are constructed to be\n * stable across subjects: `token:--color-primary` is the same root wherever it\n * lands, so the grouping needs no similarity heuristic.\n */\n\nexport interface DocketEntry {\n  readonly rootId: string;\n  readonly kind: RootKind;\n  readonly label: string;\n  readonly band: Band;\n  readonly impact: AggregateImpact;\n\n  /** Subjects this root reached, in first-seen order. */\n  readonly subjects: readonly string[];\n  readonly subjectCount: number;\n  /** Individual deltas across all subjects — the collateral count. */\n  readonly deltaCount: number;\n\n  readonly components: readonly ChangedComponent[];\n\n  /**\n   * A few subjects to actually look at.\n   *\n   * Mass re-baselining is only survivable if approval is *informed*, and nobody\n   * informs themselves by reviewing three hundred identical diffs. Spec §7.3 asks\n   * for a sampled spot-check list, and this is it.\n   */\n  readonly sample: readonly string[];\n\n  /**\n   * Distinct places this root's changes were observed, most common first.\n   *\n   * Carried on the entry rather than derived from deltas at report time, because\n   * an entry spans subjects and the deltas behind it are not kept. Three is\n   * enough to orient without turning a collapsed root back into a list — the\n   * thing collapsing it was for.\n   */\n  readonly places: readonly string[];\n\n  /**\n   * `true` when nothing under this root added, removed, moved, or renamed a node.\n   *\n   * The other half of the sentence the product promises. \"One token change, 300\n   * collateral\" is only reassuring alongside \"structure intact\" — that is what\n   * makes it a one-action approval rather than three hundred things to check.\n   */\n  readonly structureIntact: boolean;\n}\n\nexport interface Docket {\n  readonly entries: readonly DocketEntry[];\n  readonly subjectsCompared: number;\n  readonly subjectsUnchanged: number;\n  readonly subjectsChanged: number;\n\n  /**\n   * `true` when every change in the set has one explanation.\n   *\n   * The condition under which the whole review collapses to a single action.\n   */\n  readonly singleRoot: boolean;\n}\n\nexport interface DocketOptions {\n  /** Subjects listed per entry for spot-checking. Policy, not a constant. */\n  readonly sampleSize?: number;\n}\n\nexport function buildDocket(\n  diffs: readonly SemanticDiff[],\n  options: DocketOptions = {},\n): Docket {\n  const sampleSize = options.sampleSize ?? 3;\n  const groups = new Map<string, Accumulator>();\n\n  for (const diff of diffs) {\n    if (diff.identical) continue;\n\n    for (const root of diff.roots) {\n      const entry = groups.get(root.id) ?? newAccumulator(root);\n      groups.set(root.id, entry);\n\n      entry.subjects.add(diff.subjectId);\n      entry.deltas.push(...root.deltas);\n      for (const component of componentsUnder(root, diff.components)) {\n        mergeComponent(entry.components, component);\n      }\n    }\n  }\n\n  const entries = [...groups.values()]\n    .map((entry) => finalize(entry, sampleSize))\n    // Widest blast radius first: a root touching forty subjects is the review,\n    // and one touching a single subject is a detail underneath it.\n    .sort((a, b) => b.subjectCount - a.subjectCount || b.deltaCount - a.deltaCount);\n\n  const changed = diffs.filter((diff) => !diff.identical).length;\n\n  return {\n    entries,\n    subjectsCompared: diffs.length,\n    subjectsUnchanged: diffs.length - changed,\n    subjectsChanged: changed,\n    singleRoot: entries.length === 1,\n  };\n}\n\n/**\n * The docket as one sentence per entry.\n *\n * Deliberately terse. The audience is a reviewer deciding whether to look\n * further and an agent deciding whether to act, and both are worse served by a\n * paragraph than by a line they can scan.\n */\nexport function summarize(docket: Docket): string {\n  if (docket.entries.length === 0) {\n    return `${docket.subjectsCompared} subjects compared, nothing changed.`;\n  }\n\n  const header =\n    `${docket.subjectsChanged} of ${docket.subjectsCompared} subjects changed, ` +\n    `explained by ${docket.entries.length} root${docket.entries.length === 1 ? '' : 's'}.`;\n\n  const lines = docket.entries.map((entry) => {\n    const reach =\n      entry.subjectCount === 1\n        ? `${entry.deltaCount} change${entry.deltaCount === 1 ? '' : 's'}`\n        : `${entry.subjectCount} subjects, ${entry.deltaCount} collateral`;\n\n    const structure = entry.structureIntact ? 'structure intact' : 'structure changed';\n    const components =\n      entry.components.length > 0\n        ? ` — ${entry.components\n            .slice(0, 4)\n            .map((component) => component.name)\n            .join(', ')}`\n        : '';\n\n    return (\n      `  ${entry.kind}: ${entry.label} — ${reach}, ${entry.band}/${entry.impact}, ` +\n      `${structure}${components}`\n    );\n  });\n\n  return [header, ...lines].join('\\n');\n}\n\ninterface Accumulator {\n  readonly root: Root;\n  readonly subjects: Set<string>;\n  readonly deltas: Delta[];\n  readonly components: Map<string, MutableComponent>;\n}\n\ninterface MutableComponent {\n  name: string;\n  role: 'root' | 'collateral';\n  deltaCount: number;\n  bands: Set<Band>;\n  impacts: (PropertyImpact | 'structural')[];\n  renderedIn: Set<string>;\n}\n\nfunction newAccumulator(root: Root): Accumulator {\n  return { root, subjects: new Set(), deltas: [], components: new Map() };\n}\n\nfunction finalize(entry: Accumulator, sampleSize: number): DocketEntry {\n  const subjects = [...entry.subjects];\n\n  return {\n    rootId: entry.root.id,\n    kind: entry.root.kind,\n    label: entry.root.label,\n    // The root's own band is a floor, not the answer. A token edit whose\n    // collateral includes a dropped accessible name is reported at `a11y`: the\n    // entry is one review action, so it must be labelled by the loudest thing a\n    // reviewer would be signing off on, not by the thing that caused it.\n    band: loudestBand([entry.root.band, ...entry.deltas.map((delta) => delta.band)]) ?? entry.root.band,\n    impact: aggregateImpact(entry.deltas.map((delta) => delta.impact ?? 'structural')),\n    subjects,\n    subjectCount: subjects.length,\n    deltaCount: entry.deltas.length,\n    components: [...entry.components.values()]\n      .map((component) => ({\n        name: component.name,\n        role: component.role,\n        deltaCount: component.deltaCount,\n        bands: [...component.bands],\n        impact: aggregateImpact(component.impacts),\n        renderedIn: [...component.renderedIn],\n      }))\n      .sort(\n        (a, b) =>\n          b.deltaCount - a.deltaCount || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0),\n      ),\n    sample: subjects.slice(0, sampleSize),\n    places: rankedPlaces(entry.deltas),\n    structureIntact: !entry.deltas.some(isStructural),\n  };\n}\n\n/** Distinct `where` phrases, most frequent first, capped. */\nfunction rankedPlaces(deltas: readonly Delta[]): readonly string[] {\n  const counts = new Map<string, number>();\n\n  for (const delta of deltas) {\n    if (delta.where === undefined || delta.where === '') continue;\n    counts.set(delta.where, (counts.get(delta.where) ?? 0) + 1);\n  }\n\n  return [...counts.entries()]\n    .sort((a, b) => b[1] - a[1])\n    .slice(0, 3)\n    .map(([where]) => where);\n}\n\n/**\n * Whether a delta changed the shape of the tree rather than a value.\n *\n * A `rect-changed` that was *derived* from a style change does not count: the\n * box moved because a value moved, and calling that a structural change would\n * make every spacing token look like it rearranged the page.\n */\nfunction isStructural(delta: Delta): boolean {\n  switch (delta.kind) {\n    case 'node-added':\n    case 'node-removed':\n    case 'node-moved':\n    case 'role-changed':\n    case 'name-changed':\n    case 'text-changed':\n      return true;\n    case 'rect-changed':\n      return delta.derivedFrom === undefined;\n    default:\n      return false;\n  }\n}\n\n/** Components that appear in this root's deltas, from the subject's own view. */\nfunction componentsUnder(\n  root: Root,\n  components: readonly ChangedComponent[],\n): readonly ChangedComponent[] {\n  const names = new Set<string>();\n  for (const delta of root.deltas) {\n    for (const owner of delta.owners ?? []) names.add(owner.name);\n  }\n  return components.filter((component) => names.has(component.name));\n}\n\nfunction mergeComponent(\n  into: Map<string, MutableComponent>,\n  component: ChangedComponent,\n): void {\n  const existing = into.get(component.name);\n\n  if (!existing) {\n    into.set(component.name, {\n      name: component.name,\n      role: component.role,\n      deltaCount: component.deltaCount,\n      bands: new Set(component.bands),\n      impacts: [],\n      renderedIn: new Set(component.renderedIn),\n    });\n    return;\n  }\n\n  existing.deltaCount += component.deltaCount;\n  for (const band of component.bands) existing.bands.add(band);\n  for (const parent of component.renderedIn) existing.renderedIn.add(parent);\n  // Root in any subject means root: a component that changed internally\n  // somewhere is a cause, even if elsewhere it was only along for the ride.\n  if (component.role === 'root') existing.role = 'root';\n}\n"]}

package/dist/judge/fingerprint.d.ts

@@ -0,0 +1,53 @@
+import type { Delta, Root } from '../compare/diff/delta.js';
+import type { ChangeMask, DiffRegion } from '../attribute/mask.js';
+import { type Digest } from '../format/hash.js';
+/**
+ * The shape of one difference: its kind, its band, and which property moved.
+ *
+ * Everything positional and everything valued is deliberately absent. Two deltas
+ * with the same shape are the same *kind of thing happening*, which is the
+ * equivalence a flake needs and the one a coordinate cannot express.
+ */
+export declare function shapeOfDelta(delta: Delta): string;
+/**
+ * A digest of a difference with its position and its values removed.
+ *
+ * Built from the root's kind, the multiset of its deltas' shapes, and the
+ * component responsible — and from nothing else. The label is excluded on
+ * purpose: `token:--brand-a` and `token:--brand-b` moving the same properties in
+ * the same component are the same shape, and an operator silencing a themable
+ * surface wants both. Where the *label* is the identity worth matching on, the
+ * root id already exists and `Policy.alwaysAuthorized` already takes it.
+ *
+ * The `cause` is included, which is what keeps this from being too coarse: the
+ * same shape in a different component is a different fingerprint, so silencing a
+ * flake in `Avatar` does not silence the identical-looking regression in `Badge`.
+ */
+export declare function fingerprintOfRoot(root: Root): Digest;
+export interface MaskFingerprintOptions {
+    /** Grid the cropped region is resampled onto. Larger is stricter. */
+    readonly grid?: number;
+    /** Fraction of a cell that must have changed for the cell to count as set. */
+    readonly coverage?: number;
+}
+/**
+ * A digest of what a change *looks like*, for the tier that has no document.
+ *
+ * The region is cropped to its own bounding box and resampled onto a fixed grid,
+ * so the same artifact three hundred pixels lower — a card that moved, a toast
+ * that reappeared — produces the same digest. The aspect ratio is bucketed in
+ * alongside it, coarsely, so a wide banner and a tall column cannot collide
+ * merely by having similar interiors.
+ *
+ * This is [mask-fingerprint](https://github.com/argos-ci/mask-fingerprint)'s
+ * move, and it is the right one: it is the only way an ignore can be scoped to a
+ * *flake* rather than to a rectangle, which is the difference between silencing
+ * one artifact and blinding a region.
+ *
+ * It is deliberately the weaker of the two fingerprints on this page. A pixel
+ * shape knows nothing about who caused it, so two unrelated components producing
+ * similar-looking residue collide — which is exactly why the semantic
+ * fingerprint exists and is preferred wherever a document is available.
+ */
+export declare function fingerprintOfMask(mask: ChangeMask, region: DiffRegion, options?: MaskFingerprintOptions): Digest;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/judge/fingerprint.js

@@ -0,0 +1,144 @@
+import { digestString } from '../format/hash.js';
+/**
+ * The shape of a difference, with its position and its values removed.
+ *
+ * Two digests, and the interesting thing about them is that they answer the same
+ * question at different strengths. A **semantic** fingerprint knows which
+ * component produced the difference and can therefore tell an identical-looking
+ * change in `Avatar` from one in `Badge`. A **pixel** fingerprint knows only what
+ * the residue looks like, so it collides where two unrelated components produce
+ * similar shapes — and it is the only one available where no document survives.
+ *
+ * Both exist so that an ignore, or an acceptance, can be scoped to *what
+ * happened* rather than to *where it landed* (spec 0024, ADR-0025). A coordinate
+ * stops covering the thing it was drawn around the first time the layout moves; a
+ * shape follows it. That is [`mask-fingerprint`](https://github.com/argos-ci/mask-fingerprint)'s
+ * idea, and it is the right one.
+ *
+ * Separated from `ignore.ts` because ignoring is one of three things these are
+ * for. `variance accept --shape` promotes a change everywhere it reached, a
+ * report prints one beside every region so an operator can copy it, and an ignore
+ * absorbs one — and a file named for the third would misdescribe the other two.
+ */
+/**
+ * Field separator inside a digest input.
+ *
+ * A byte that cannot occur in a component name, a property or a band, so no two
+ * different shapes can concatenate into the same string. A space would collide
+ * the moment a value contained one, which is the collision `digestCombine` uses
+ * the same character to avoid.
+ */
+const SEPARATOR = '\u0000';
+/**
+ * The shape of one difference: its kind, its band, and which property moved.
+ *
+ * Everything positional and everything valued is deliberately absent. Two deltas
+ * with the same shape are the same *kind of thing happening*, which is the
+ * equivalence a flake needs and the one a coordinate cannot express.
+ */
+export function shapeOfDelta(delta) {
+    return `${delta.kind}/${delta.band}/${delta.property ?? ''}`;
+}
+/**
+ * A digest of a difference with its position and its values removed.
+ *
+ * Built from the root's kind, the multiset of its deltas' shapes, and the
+ * component responsible — and from nothing else. The label is excluded on
+ * purpose: `token:--brand-a` and `token:--brand-b` moving the same properties in
+ * the same component are the same shape, and an operator silencing a themable
+ * surface wants both. Where the *label* is the identity worth matching on, the
+ * root id already exists and `Policy.alwaysAuthorized` already takes it.
+ *
+ * The `cause` is included, which is what keeps this from being too coarse: the
+ * same shape in a different component is a different fingerprint, so silencing a
+ * flake in `Avatar` does not silence the identical-looking regression in `Badge`.
+ */
+export function fingerprintOfRoot(root) {
+    const shapes = root.deltas.map(shapeOfDelta).sort();
+    return digestString(['shape/v1', root.kind, root.cause ?? '', ...shapes].join(SEPARATOR));
+}
+const DEFAULT_GRID = 12;
+const DEFAULT_COVERAGE = 0.25;
+/**
+ * A digest of what a change *looks like*, for the tier that has no document.
+ *
+ * The region is cropped to its own bounding box and resampled onto a fixed grid,
+ * so the same artifact three hundred pixels lower — a card that moved, a toast
+ * that reappeared — produces the same digest. The aspect ratio is bucketed in
+ * alongside it, coarsely, so a wide banner and a tall column cannot collide
+ * merely by having similar interiors.
+ *
+ * This is [mask-fingerprint](https://github.com/argos-ci/mask-fingerprint)'s
+ * move, and it is the right one: it is the only way an ignore can be scoped to a
+ * *flake* rather than to a rectangle, which is the difference between silencing
+ * one artifact and blinding a region.
+ *
+ * It is deliberately the weaker of the two fingerprints on this page. A pixel
+ * shape knows nothing about who caused it, so two unrelated components producing
+ * similar-looking residue collide — which is exactly why the semantic
+ * fingerprint exists and is preferred wherever a document is available.
+ */
+export function fingerprintOfMask(mask, region, options = {}) {
+    const grid = Math.max(1, Math.floor(options.grid ?? DEFAULT_GRID));
+    const coverage = options.coverage ?? DEFAULT_COVERAGE;
+    const width = Math.max(1, region.width);
+    const height = Math.max(1, region.height);
+    // Typed rather than plain arrays: the resample is the one hot loop on this
+    // page, running once per region on every red raster comparison.
+    const cells = new Uint32Array(grid * grid);
+    const totals = new Uint32Array(grid * grid);
+    for (let y = 0; y < height; y += 1) {
+        const sourceY = region.y + y;
+        if (sourceY < 0 || sourceY >= mask.height)
+            continue;
+        const row = ((y * grid) / height) | 0;
+        const rowOffset = sourceY * mask.width;
+        const cellRow = Math.min(row, grid - 1) * grid;
+        for (let x = 0; x < width; x += 1) {
+            const sourceX = region.x + x;
+            if (sourceX < 0 || sourceX >= mask.width)
+                continue;
+            const cell = cellRow + Math.min(((x * grid) / width) | 0, grid - 1);
+            totals[cell] = (totals[cell] ?? 0) + 1;
+            if (mask.data[rowOffset + sourceX] !== 0)
+                cells[cell] = (cells[cell] ?? 0) + 1;
+        }
+    }
+    let bits = '';
+    for (let index = 0; index < cells.length; index += 1) {
+        const total = totals[index] ?? 0;
+        const set = cells[index] ?? 0;
+        bits += total > 0 && set / total >= coverage ? '1' : '0';
+    }
+    return digestString(['mask/v1', aspectBucket(width, height), sizeBucket(width, height), bits].join(SEPARATOR));
+}
+/**
+ * Aspect ratio in coarse steps, so a shape is not required to keep its exact box.
+ *
+ * Halving steps rather than a continuous ratio: a region that grows by a pixel
+ * must stay the same fingerprint, or the whole mechanism degrades into the
+ * coordinate matching it exists to replace.
+ */
+function aspectBucket(width, height) {
+    const ratio = width / height;
+    return String(Math.round(Math.log2(ratio) * 2));
+}
+/**
+ * Extent in coarse doubling steps, so a shape ignore is scoped to a magnitude.
+ *
+ * Without it the digest is **scale-free**, and that is not a subtlety: solid
+ * squares of 12, 16, 24, 36, 48, 96 and 120 device pixels all resample to twelve
+ * rows of ones and all carry aspect `0`, so they produce one digest. A rule
+ * written for a 12×12 flaky badge would absorb a 120×120 card that had gone
+ * solid — an image that failed to load, a component that rendered as a filled
+ * block — at a hundred times the area, and the subject would come back green.
+ *
+ * The geometric mean rather than the area, so this term and the aspect are in the
+ * same units and one bucket step means one doubling of *linear* size. That bounds
+ * over-absorption to under 2× in each dimension instead of leaving it unbounded,
+ * which is the most a position-invariant digest can promise.
+ */
+function sizeBucket(width, height) {
+    return String(Math.round(Math.log2(Math.sqrt(width * height))));
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/judge/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../src/judge/fingerprint.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Delta, Root } from '../compare/diff/delta.js';\nimport type { ChangeMask, DiffRegion } from '../attribute/mask.js';\nimport { digestString, type Digest } from '../format/hash.js';\n\n/**\n * The shape of a difference, with its position and its values removed.\n *\n * Two digests, and the interesting thing about them is that they answer the same\n * question at different strengths. A **semantic** fingerprint knows which\n * component produced the difference and can therefore tell an identical-looking\n * change in `Avatar` from one in `Badge`. A **pixel** fingerprint knows only what\n * the residue looks like, so it collides where two unrelated components produce\n * similar shapes — and it is the only one available where no document survives.\n *\n * Both exist so that an ignore, or an acceptance, can be scoped to *what\n * happened* rather than to *where it landed* (spec 0024, ADR-0025). A coordinate\n * stops covering the thing it was drawn around the first time the layout moves; a\n * shape follows it. That is [`mask-fingerprint`](https://github.com/argos-ci/mask-fingerprint)'s\n * idea, and it is the right one.\n *\n * Separated from `ignore.ts` because ignoring is one of three things these are\n * for. `variance accept --shape` promotes a change everywhere it reached, a\n * report prints one beside every region so an operator can copy it, and an ignore\n * absorbs one — and a file named for the third would misdescribe the other two.\n */\n\n/**\n * Field separator inside a digest input.\n *\n * A byte that cannot occur in a component name, a property or a band, so no two\n * different shapes can concatenate into the same string. A space would collide\n * the moment a value contained one, which is the collision `digestCombine` uses\n * the same character to avoid.\n */\nconst SEPARATOR = '\\u0000';\n\n/**\n * The shape of one difference: its kind, its band, and which property moved.\n *\n * Everything positional and everything valued is deliberately absent. Two deltas\n * with the same shape are the same *kind of thing happening*, which is the\n * equivalence a flake needs and the one a coordinate cannot express.\n */\nexport function shapeOfDelta(delta: Delta): string {\n  return `${delta.kind}/${delta.band}/${delta.property ?? ''}`;\n}\n\n/**\n * A digest of a difference with its position and its values removed.\n *\n * Built from the root's kind, the multiset of its deltas' shapes, and the\n * component responsible — and from nothing else. The label is excluded on\n * purpose: `token:--brand-a` and `token:--brand-b` moving the same properties in\n * the same component are the same shape, and an operator silencing a themable\n * surface wants both. Where the *label* is the identity worth matching on, the\n * root id already exists and `Policy.alwaysAuthorized` already takes it.\n *\n * The `cause` is included, which is what keeps this from being too coarse: the\n * same shape in a different component is a different fingerprint, so silencing a\n * flake in `Avatar` does not silence the identical-looking regression in `Badge`.\n */\nexport function fingerprintOfRoot(root: Root): Digest {\n  const shapes = root.deltas.map(shapeOfDelta).sort();\n  return digestString(\n    ['shape/v1', root.kind, root.cause ?? '', ...shapes].join(SEPARATOR),\n  );\n}\n\nexport interface MaskFingerprintOptions {\n  /** Grid the cropped region is resampled onto. Larger is stricter. */\n  readonly grid?: number;\n\n  /** Fraction of a cell that must have changed for the cell to count as set. */\n  readonly coverage?: number;\n}\n\nconst DEFAULT_GRID = 12;\nconst DEFAULT_COVERAGE = 0.25;\n\n/**\n * A digest of what a change *looks like*, for the tier that has no document.\n *\n * The region is cropped to its own bounding box and resampled onto a fixed grid,\n * so the same artifact three hundred pixels lower — a card that moved, a toast\n * that reappeared — produces the same digest. The aspect ratio is bucketed in\n * alongside it, coarsely, so a wide banner and a tall column cannot collide\n * merely by having similar interiors.\n *\n * This is [mask-fingerprint](https://github.com/argos-ci/mask-fingerprint)'s\n * move, and it is the right one: it is the only way an ignore can be scoped to a\n * *flake* rather than to a rectangle, which is the difference between silencing\n * one artifact and blinding a region.\n *\n * It is deliberately the weaker of the two fingerprints on this page. A pixel\n * shape knows nothing about who caused it, so two unrelated components producing\n * similar-looking residue collide — which is exactly why the semantic\n * fingerprint exists and is preferred wherever a document is available.\n */\nexport function fingerprintOfMask(\n  mask: ChangeMask,\n  region: DiffRegion,\n  options: MaskFingerprintOptions = {},\n): Digest {\n  const grid = Math.max(1, Math.floor(options.grid ?? DEFAULT_GRID));\n  const coverage = options.coverage ?? DEFAULT_COVERAGE;\n\n  const width = Math.max(1, region.width);\n  const height = Math.max(1, region.height);\n  // Typed rather than plain arrays: the resample is the one hot loop on this\n  // page, running once per region on every red raster comparison.\n  const cells = new Uint32Array(grid * grid);\n  const totals = new Uint32Array(grid * grid);\n\n  for (let y = 0; y < height; y += 1) {\n    const sourceY = region.y + y;\n    if (sourceY < 0 || sourceY >= mask.height) continue;\n\n    const row = ((y * grid) / height) | 0;\n    const rowOffset = sourceY * mask.width;\n    const cellRow = Math.min(row, grid - 1) * grid;\n\n    for (let x = 0; x < width; x += 1) {\n      const sourceX = region.x + x;\n      if (sourceX < 0 || sourceX >= mask.width) continue;\n\n      const cell = cellRow + Math.min(((x * grid) / width) | 0, grid - 1);\n      totals[cell] = (totals[cell] ?? 0) + 1;\n      if (mask.data[rowOffset + sourceX] !== 0) cells[cell] = (cells[cell] ?? 0) + 1;\n    }\n  }\n\n  let bits = '';\n  for (let index = 0; index < cells.length; index += 1) {\n    const total = totals[index] ?? 0;\n    const set = cells[index] ?? 0;\n    bits += total > 0 && set / total >= coverage ? '1' : '0';\n  }\n\n  return digestString(\n    ['mask/v1', aspectBucket(width, height), sizeBucket(width, height), bits].join(SEPARATOR),\n  );\n}\n\n/**\n * Aspect ratio in coarse steps, so a shape is not required to keep its exact box.\n *\n * Halving steps rather than a continuous ratio: a region that grows by a pixel\n * must stay the same fingerprint, or the whole mechanism degrades into the\n * coordinate matching it exists to replace.\n */\nfunction aspectBucket(width: number, height: number): string {\n  const ratio = width / height;\n  return String(Math.round(Math.log2(ratio) * 2));\n}\n\n/**\n * Extent in coarse doubling steps, so a shape ignore is scoped to a magnitude.\n *\n * Without it the digest is **scale-free**, and that is not a subtlety: solid\n * squares of 12, 16, 24, 36, 48, 96 and 120 device pixels all resample to twelve\n * rows of ones and all carry aspect `0`, so they produce one digest. A rule\n * written for a 12×12 flaky badge would absorb a 120×120 card that had gone\n * solid — an image that failed to load, a component that rendered as a filled\n * block — at a hundred times the area, and the subject would come back green.\n *\n * The geometric mean rather than the area, so this term and the aspect are in the\n * same units and one bucket step means one doubling of *linear* size. That bounds\n * over-absorption to under 2× in each dimension instead of leaving it unbounded,\n * which is the most a position-invariant digest can promise.\n */\nfunction sizeBucket(width: number, height: number): string {\n  return String(Math.round(Math.log2(Math.sqrt(width * height))));\n}\n"]}

package/dist/judge/ignore.d.ts

@@ -0,0 +1,206 @@
+import type { Band } from '../compare/band.js';
+import type { SemanticDiff } from '../compare/diff/index.js';
+import type { Digest } from '../format/hash.js';
+import type { IgnoreSite } from '../format/snapshot.js';
+export type { IgnoreSite } from '../format/snapshot.js';
+/**
+ * Ignores, and the accounting that stops one becoming a blind spot (spec 0024).
+ *
+ * The README refuses tolerances, and it is right to: a tolerance is an anonymous
+ * number that hides whatever fits underneath it, chosen by whoever wrote the
+ * default. An ignore is the opposite of that in every respect that matters, and
+ * the difference is enforced here rather than asserted in a document:
+ *
+ * - it names a **place** or a **shape**, never a magnitude;
+ * - it carries a **reason**, and a rule without one is refused;
+ * - it says how much it absorbed, in how many subjects, every run;
+ * - it is **reported when it absorbs nothing**, because an ignore that outlived
+ *   its flake is a hole in the suite nobody can see;
+ * - it never produces `unchanged`. A subject whose every difference was absorbed
+ *   is a subject that was *ignored*, and the two words are not interchangeable.
+ *
+ * That last rule is ADR-0002's, applied to a second reason for not having looked.
+ * A profile that cannot observe a band reports `unobserved` rather than passing
+ * it; an operator who declined to look at a region gets the same treatment, for
+ * the same reason — a green subject that is indistinguishable from a genuinely
+ * unchanged one makes every count on this page decorative.
+ *
+ * ## Two ways to name what is not the subject
+ *
+ * **By place.** A subtree, resolved once by whatever held the document, arrives
+ * here as an {@link IgnoreSite}: a path, and the box it occupied. One declaration
+ * serves both tiers — the semantic tier drops deltas under the path, the raster
+ * tier subtracts the box from the change mask — because two declarations would
+ * let the tiers disagree about what the subject is, and a region that is ignored
+ * semantically and compared on pixels reports `unexplained`, the highest severity
+ * in the system, for something the operator already excluded.
+ *
+ * **By shape.** A {@link fingerprintOfRoot} is a digest of a difference with its
+ * position and its values removed, so the same artifact anywhere in any subject
+ * digests the same. An ignore keyed on one silences a known flake *without*
+ * blinding the image it appears in: a different regression in the same place has
+ * a different shape and is still reported. A coordinate mask cannot make that
+ * distinction and never will, which is why no rule here accepts one: a rectangle
+ * is a place that stops covering the thing it was drawn around the first time the
+ * layout moves, and a selector is a place that does not.
+ *
+ * ## What is not here
+ *
+ * A band on its own. `bands` narrows a rule that already names a place or a
+ * shape; a rule carrying only a band would be a tolerance wearing an ignore's
+ * clothes, and {@link validateIgnoreRule} refuses it. Which bands *block* is a
+ * different question with a different answer — `Policy.blocking` in `intent.ts`.
+ */
+export interface IgnoreRule {
+    /** Stable name, used in the config, in the report, and by `IgnoreSite.rule`. */
+    readonly id: string;
+    /**
+     * Why this is not the subject. Required.
+     *
+     * Not documentation. Six months on, the only question anyone asks about an
+     * ignore is whether it is still true, and a rule that cannot answer it gets
+     * kept out of superstition. Carried into the report so the answer is in front
+     * of whoever is reading the failure it did not absorb.
+     */
+    readonly reason: string;
+    /**
+     * Subjects this applies to. `*` matches any run of characters. Absent means all.
+     *
+     * Narrow by default is the wrong default here and the right one to offer: a
+     * flake that appears in one story should be silenced in one story, and an
+     * operator who genuinely means "everywhere" can say so by omission — visibly,
+     * in the same file.
+     */
+    readonly subjects?: readonly string[];
+    /**
+     * Difference shapes this absorbs. See {@link fingerprintOfRoot}.
+     *
+     * The form to prefer. It survives layout changes, applies across subjects
+     * without listing them, and leaves the rest of the image being tested.
+     */
+    readonly fingerprints?: readonly Digest[];
+    /** Narrows what the rule absorbs where it already applies. Never on its own. */
+    readonly bands?: readonly Band[];
+    /**
+     * The place is the whole subject.
+     *
+     * The one way a rule may carry `bands` and no selector, and it has to be said
+     * rather than inferred from their absence — because "no place" and "every
+     * place" are the two readings of the same missing field, and one of them is the
+     * tolerance this mechanism exists to refuse.
+     *
+     * Set by {@link import('./sensitivity.js').asIgnore} and by nothing else. A
+     * sensitivity declares what a subject *is asserted on*, so its place genuinely
+     * is the subject: "this route asserts on layout" absorbs every token-band
+     * difference in it, wherever in it they land. The config parser does not accept
+     * this key, so a hand-written ignore still cannot reach it.
+     */
+    readonly whole?: boolean;
+    /**
+     * ISO date after which this stops absorbing and starts being reported.
+     *
+     * Declared rather than inferred, so the default lifetime of a blind spot is
+     * "until somebody decides again" instead of "forever". An expired rule is not
+     * an error — the run proceeds and the differences it used to absorb come back,
+     * which is the point.
+     */
+    readonly until?: string;
+}
+/** What one rule absorbed in one run. */
+export interface AbsorbedByRule {
+    readonly rule: string;
+    readonly reason: string;
+    readonly deltas: number;
+    readonly subjects: readonly string[];
+    readonly bands: readonly Band[];
+    /**
+     * The shapes this rule actually absorbed.
+     *
+     * The most useful field for an operator holding a place-scoped rule: it names
+     * what that place was covering, so a whole excluded subtree can be narrowed to
+     * the one shape that is actually noisy without anyone guessing a digest.
+     */
+    readonly fingerprints: readonly Digest[];
+}
+export interface IgnoreRegister {
+    readonly absorbed: readonly AbsorbedByRule[];
+    /**
+     * Rules that absorbed nothing this run.
+     *
+     * Not a warning about the config file — a report about the suite. Either the
+     * flake is fixed and the rule is a hole that should close, or the rule stopped
+     * matching and something is being silently reported that the operator believes
+     * is silenced. Both are worth a line.
+     */
+    readonly dead: readonly string[];
+    /** Rules past their `until` date. They absorbed nothing, by construction. */
+    readonly expired: readonly string[];
+    /**
+     * Subjects whose every difference was absorbed.
+     *
+     * The list that must never be folded into "unchanged". These are subjects that
+     * differed and were not looked at.
+     */
+    readonly fullyAbsorbed: readonly string[];
+    readonly totalAbsorbed: number;
+}
+export interface IgnoreOutcome {
+    /** The diffs with absorbed deltas removed, in the order they were given. */
+    readonly diffs: readonly SemanticDiff[];
+    readonly register: IgnoreRegister;
+}
+export interface IgnoreOptions {
+    /** Sites per subject id, as resolved against each candidate document. */
+    readonly sites?: Readonly<Record<string, readonly IgnoreSite[]>>;
+    /**
+     * Today, as an ISO date, for `until`. Supplied rather than read.
+     *
+     * `core` has no clock — a package that reads one cannot be tested for what it
+     * does on the day a rule expires, which is the only day the field matters.
+     */
+    readonly now?: string;
+}
+/**
+ * Check a rule before it can absorb anything.
+ *
+ * Returns the problems rather than throwing, because a config carrying three bad
+ * rules should report three, and because the CLI's config parser wants to attach
+ * its own file and key to each one.
+ */
+export declare function validateIgnoreRule(rule: IgnoreRule, options?: {
+    readonly hasPlace?: boolean;
+}): readonly string[];
+/**
+ * The shape of one difference: its kind, its band, and which property moved.
+ *
+ * Everything positional and everything valued is deliberately absent. Two deltas
+ * with the same shape are the same *kind of thing happening*, which is the
+ * equivalence a flake needs and the one a coordinate cannot express.
+ */
+/**
+ * Field separator inside a digest input.
+ *
+ * A byte that cannot occur in a component name, a property or a band, so no two
+ * different shapes can concatenate into the same string. A space would collide
+ * the moment a value contained one, which is the collision `digestCombine` uses
+ * the same character to avoid.
+ */
+/**
+ * Apply ignores to a run's diffs, and account for every difference absorbed.
+ *
+ * Runs after `diffSnapshots` and before `buildDocket`: the docket's arithmetic is
+ * about which causes a reviewer signs off on, and a cause nobody is going to look
+ * at should not be in it. Everything removed here is counted, attributed to the
+ * rule that removed it, and reported.
+ */
+export declare function applyIgnores(diffs: readonly SemanticDiff[], rules: readonly IgnoreRule[], options?: IgnoreOptions): IgnoreOutcome;
+/**
+ * The register as the paragraph a reader is owed.
+ *
+ * Absorption first, because that is what changed the verdict; dead and expired
+ * rules after it, because those are what the operator has to do something about.
+ * A register with nothing in it returns the empty string rather than a cheerful
+ * line — a run with no ignores should read exactly as it did before this existed.
+ */
+export declare function summarizeIgnores(register: IgnoreRegister): string;
+//# sourceMappingURL=ignore.d.ts.map