@variance-authority/core 0.1.0

package/dist/judge/ignore.js

@@ -0,0 +1,237 @@
+import { aggregateImpact } from '../compare/impact.js';
+import { componentsOf } from '../compare/diff/components.js';
+import { impactTag } from '../compare/diff/delta.js';
+import { fingerprintOfRoot } from './fingerprint.js';
+import { appliesToSubject, isExpired, isUnder } from './scope.js';
+/**
+ * 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 function validateIgnoreRule(rule, options = {}) {
+    const problems = [];
+    if (rule.id.trim() === '')
+        problems.push('needs an id');
+    if (rule.reason.trim() === '') {
+        problems.push('needs a reason: an ignore nobody can evaluate later is one nobody will ever remove');
+    }
+    // `hasPlace` is the caller's business because a place is resolved outside this
+    // package: a selector needs a DOM. The rule this enforces is the same either
+    // way — a rule that names no place and no shape absorbs everything its bands
+    // cover in every subject it lists, which is a tolerance.
+    const concrete = (options.hasPlace ?? false) ||
+        rule.whole === true ||
+        (rule.fingerprints !== undefined && rule.fingerprints.length > 0);
+    if (!concrete) {
+        problems.push(`"${rule.id}" names neither a place nor a shape, so there is nothing for it to be scoped ` +
+            'to; an ignore that is only a band is a tolerance');
+    }
+    if (rule.whole === true && rule.bands === undefined) {
+        // `whole` with no band is every difference in the subject, which is not an
+        // ignore — it is switching the subject off, and `subjects.exclude` says that
+        // in a word a reader cannot mistake.
+        problems.push(`"${rule.id}" covers the whole subject and narrows nothing, which silences it entirely; ` +
+            'exclude the subject if that is the intent');
+    }
+    if (rule.until !== undefined && Number.isNaN(Date.parse(rule.until))) {
+        problems.push(`until must be an ISO date, not "${rule.until}"`);
+    }
+    return problems;
+}
+/**
+ * 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 function applyIgnores(diffs, rules, options = {}) {
+    if (rules.length === 0) {
+        return { diffs, register: emptyRegister() };
+    }
+    const now = options.now;
+    const expired = rules.filter((rule) => isExpired(rule, now)).map((rule) => rule.id);
+    const live = rules.filter((rule) => !isExpired(rule, now));
+    const tallies = new Map();
+    const fullyAbsorbed = [];
+    const filtered = [];
+    for (const diff of diffs) {
+        if (diff.identical || diff.deltas.length === 0) {
+            filtered.push(diff);
+            continue;
+        }
+        const sites = options.sites?.[diff.subjectId] ?? [];
+        const applicable = live.filter((rule) => appliesToSubject(rule, diff.subjectId));
+        if (applicable.length === 0) {
+            filtered.push(diff);
+            continue;
+        }
+        // Fingerprints are per root, so they are resolved once per root rather than
+        // once per delta: a root's shape is a property of the whole group, and asking
+        // it repeatedly would make the digest cost quadratic in a wide change set.
+        const fingerprints = new Map();
+        for (const root of diff.roots) {
+            const digest = fingerprintOfRoot(root);
+            for (const delta of root.deltas)
+                fingerprints.set(delta, digest);
+        }
+        const absorbedBy = new Map();
+        for (const delta of diff.deltas) {
+            const rule = applicable.find((candidate) => absorbs(candidate, delta, sites, fingerprints.get(delta)));
+            if (rule !== undefined)
+                absorbedBy.set(delta, rule);
+        }
+        if (absorbedBy.size === 0) {
+            filtered.push(diff);
+            continue;
+        }
+        for (const [delta, rule] of absorbedBy) {
+            const tally = tallies.get(rule.id) ?? newTally(rule);
+            tallies.set(rule.id, tally);
+            tally.deltas += 1;
+            tally.subjects.add(diff.subjectId);
+            tally.bands.add(delta.band);
+            const digest = fingerprints.get(delta);
+            if (digest !== undefined)
+                tally.fingerprints.add(digest);
+        }
+        const kept = diff.deltas.filter((delta) => !absorbedBy.has(delta));
+        if (kept.length === 0)
+            fullyAbsorbed.push(diff.subjectId);
+        filtered.push(rebuild(diff, kept, absorbedBy));
+    }
+    const absorbed = [...tallies.values()]
+        .map(finalizeTally)
+        .sort((a, b) => b.deltas - a.deltas || (a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0));
+    const dead = rules
+        .filter((rule) => !tallies.has(rule.id) && !expired.includes(rule.id))
+        .map((rule) => rule.id);
+    return {
+        diffs: filtered,
+        register: {
+            absorbed,
+            dead,
+            expired,
+            fullyAbsorbed,
+            totalAbsorbed: absorbed.reduce((sum, entry) => sum + entry.deltas, 0),
+        },
+    };
+}
+/**
+ * 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 function summarizeIgnores(register) {
+    const lines = [];
+    if (register.totalAbsorbed > 0) {
+        lines.push(`${register.totalAbsorbed} difference(s) absorbed by ${register.absorbed.length} ignore(s).`);
+        for (const entry of register.absorbed) {
+            lines.push(`  ${entry.rule}: ${entry.deltas} in ${entry.subjects.length} subject(s), ` +
+                `${entry.bands.join('/')} — ${entry.reason}`);
+        }
+    }
+    if (register.fullyAbsorbed.length > 0) {
+        lines.push(`  ${register.fullyAbsorbed.length} subject(s) differed and were entirely ignored: ` +
+            `${register.fullyAbsorbed.slice(0, 3).join(', ')}` +
+            (register.fullyAbsorbed.length > 3 ? ` (+${register.fullyAbsorbed.length - 3} more)` : ''));
+    }
+    for (const rule of register.expired) {
+        lines.push(`  [expired] ${rule} — past its date; it absorbed nothing and is now reporting`);
+    }
+    for (const rule of register.dead) {
+        lines.push(`  [dead] ${rule} — absorbed nothing this run; either it is no longer needed, or it ` +
+            'stopped matching and something is being reported that you believe is silenced');
+    }
+    return lines.join('\n');
+}
+function newTally(rule) {
+    return {
+        rule,
+        deltas: 0,
+        subjects: new Set(),
+        bands: new Set(),
+        fingerprints: new Set(),
+    };
+}
+function finalizeTally(tally) {
+    return {
+        rule: tally.rule.id,
+        reason: tally.rule.reason,
+        deltas: tally.deltas,
+        subjects: [...tally.subjects],
+        bands: [...tally.bands],
+        fingerprints: [...tally.fingerprints],
+    };
+}
+function emptyRegister() {
+    return { absorbed: [], dead: [], expired: [], fullyAbsorbed: [], totalAbsorbed: 0 };
+}
+/**
+ * Whether a rule absorbs one delta.
+ *
+ * Order matters only for cost. A rule absorbs when it names *this* place or
+ * *this* shape and the band, if it named any, is one of them — so a rule that
+ * names nothing absorbs nothing, which is the property that keeps a config typo
+ * from silencing a suite.
+ */
+function absorbs(rule, delta, sites, fingerprint) {
+    if (rule.bands !== undefined && !rule.bands.includes(delta.band))
+        return false;
+    // Checked after the band and before any place, which is the order that makes
+    // it safe: `whole` is only ever reached by a rule that has already narrowed to
+    // the bands it absorbs, so "the whole subject" never means "everything in it".
+    if (rule.whole === true)
+        return true;
+    if (fingerprint !== undefined && rule.fingerprints?.includes(fingerprint))
+        return true;
+    return sites.some((site) => site.rule === rule.id && isUnder(delta.path, site.path));
+}
+/**
+ * Rebuild a diff around the deltas that survived.
+ *
+ * Roots keep their own band and cause — filtering deltas out of a root does not
+ * change what caused the rest of them — but a root left with nothing is dropped,
+ * because a cause with no observed effect is not a review item. Components and
+ * aggregate impact are recomputed from the survivors by the same functions that
+ * built them, so a filtered diff cannot disagree with an unfiltered one about
+ * what a given set of deltas implies.
+ */
+function rebuild(diff, kept, absorbedBy) {
+    const roots = [];
+    for (const root of diff.roots) {
+        const deltas = root.deltas.filter((delta) => !absorbedBy.has(delta));
+        if (deltas.length === 0)
+            continue;
+        roots.push(deltas.length === root.deltas.length ? root : { ...root, deltas });
+    }
+    return {
+        ...diff,
+        deltas: kept,
+        roots,
+        components: componentsOf(kept, roots),
+        impact: aggregateImpact(kept.map(impactTag)),
+    };
+}
+//# sourceMappingURL=ignore.js.map

package/dist/judge/ignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ignore.js","sourceRoot":"","sources":["../../src/judge/ignore.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Band } from '../compare/band.js';\nimport { aggregateImpact } from '../compare/impact.js';\nimport { componentsOf } from '../compare/diff/components.js';\nimport { impactTag, type Delta, type Root } from '../compare/diff/delta.js';\nimport type { SemanticDiff } from '../compare/diff/index.js';\nimport type { Digest } from '../format/hash.js';\nimport { fingerprintOfRoot } from './fingerprint.js';\nimport type { IgnoreSite } from '../format/snapshot.js';\nimport { appliesToSubject, isExpired, isUnder } from './scope.js';\n\nexport type { IgnoreSite } from '../format/snapshot.js';\n\n/**\n * Ignores, and the accounting that stops one becoming a blind spot (spec 0024).\n *\n * The README refuses tolerances, and it is right to: a tolerance is an anonymous\n * number that hides whatever fits underneath it, chosen by whoever wrote the\n * default. An ignore is the opposite of that in every respect that matters, and\n * the difference is enforced here rather than asserted in a document:\n *\n * - it names a **place** or a **shape**, never a magnitude;\n * - it carries a **reason**, and a rule without one is refused;\n * - it says how much it absorbed, in how many subjects, every run;\n * - it is **reported when it absorbs nothing**, because an ignore that outlived\n *   its flake is a hole in the suite nobody can see;\n * - it never produces `unchanged`. A subject whose every difference was absorbed\n *   is a subject that was *ignored*, and the two words are not interchangeable.\n *\n * That last rule is ADR-0002's, applied to a second reason for not having looked.\n * A profile that cannot observe a band reports `unobserved` rather than passing\n * it; an operator who declined to look at a region gets the same treatment, for\n * the same reason — a green subject that is indistinguishable from a genuinely\n * unchanged one makes every count on this page decorative.\n *\n * ## Two ways to name what is not the subject\n *\n * **By place.** A subtree, resolved once by whatever held the document, arrives\n * here as an {@link IgnoreSite}: a path, and the box it occupied. One declaration\n * serves both tiers — the semantic tier drops deltas under the path, the raster\n * tier subtracts the box from the change mask — because two declarations would\n * let the tiers disagree about what the subject is, and a region that is ignored\n * semantically and compared on pixels reports `unexplained`, the highest severity\n * in the system, for something the operator already excluded.\n *\n * **By shape.** A {@link fingerprintOfRoot} is a digest of a difference with its\n * position and its values removed, so the same artifact anywhere in any subject\n * digests the same. An ignore keyed on one silences a known flake *without*\n * blinding the image it appears in: a different regression in the same place has\n * a different shape and is still reported. A coordinate mask cannot make that\n * distinction and never will, which is why no rule here accepts one: a rectangle\n * is a place that stops covering the thing it was drawn around the first time the\n * layout moves, and a selector is a place that does not.\n *\n * ## What is not here\n *\n * A band on its own. `bands` narrows a rule that already names a place or a\n * shape; a rule carrying only a band would be a tolerance wearing an ignore's\n * clothes, and {@link validateIgnoreRule} refuses it. Which bands *block* is a\n * different question with a different answer — `Policy.blocking` in `intent.ts`.\n */\n\nexport interface IgnoreRule {\n  /** Stable name, used in the config, in the report, and by `IgnoreSite.rule`. */\n  readonly id: string;\n\n  /**\n   * Why this is not the subject. Required.\n   *\n   * Not documentation. Six months on, the only question anyone asks about an\n   * ignore is whether it is still true, and a rule that cannot answer it gets\n   * kept out of superstition. Carried into the report so the answer is in front\n   * of whoever is reading the failure it did not absorb.\n   */\n  readonly reason: string;\n\n  /**\n   * Subjects this applies to. `*` matches any run of characters. Absent means all.\n   *\n   * Narrow by default is the wrong default here and the right one to offer: a\n   * flake that appears in one story should be silenced in one story, and an\n   * operator who genuinely means \"everywhere\" can say so by omission — visibly,\n   * in the same file.\n   */\n  readonly subjects?: readonly string[];\n\n  /**\n   * Difference shapes this absorbs. See {@link fingerprintOfRoot}.\n   *\n   * The form to prefer. It survives layout changes, applies across subjects\n   * without listing them, and leaves the rest of the image being tested.\n   */\n  readonly fingerprints?: readonly Digest[];\n\n  /** Narrows what the rule absorbs where it already applies. Never on its own. */\n  readonly bands?: readonly Band[];\n\n  /**\n   * The place is the whole subject.\n   *\n   * The one way a rule may carry `bands` and no selector, and it has to be said\n   * rather than inferred from their absence — because \"no place\" and \"every\n   * place\" are the two readings of the same missing field, and one of them is the\n   * tolerance this mechanism exists to refuse.\n   *\n   * Set by {@link import('./sensitivity.js').asIgnore} and by nothing else. A\n   * sensitivity declares what a subject *is asserted on*, so its place genuinely\n   * is the subject: \"this route asserts on layout\" absorbs every token-band\n   * difference in it, wherever in it they land. The config parser does not accept\n   * this key, so a hand-written ignore still cannot reach it.\n   */\n  readonly whole?: boolean;\n\n  /**\n   * ISO date after which this stops absorbing and starts being reported.\n   *\n   * Declared rather than inferred, so the default lifetime of a blind spot is\n   * \"until somebody decides again\" instead of \"forever\". An expired rule is not\n   * an error — the run proceeds and the differences it used to absorb come back,\n   * which is the point.\n   */\n  readonly until?: string;\n}\n\n/** What one rule absorbed in one run. */\nexport interface AbsorbedByRule {\n  readonly rule: string;\n  readonly reason: string;\n  readonly deltas: number;\n  readonly subjects: readonly string[];\n  readonly bands: readonly Band[];\n\n  /**\n   * The shapes this rule actually absorbed.\n   *\n   * The most useful field for an operator holding a place-scoped rule: it names\n   * what that place was covering, so a whole excluded subtree can be narrowed to\n   * the one shape that is actually noisy without anyone guessing a digest.\n   */\n  readonly fingerprints: readonly Digest[];\n}\n\nexport interface IgnoreRegister {\n  readonly absorbed: readonly AbsorbedByRule[];\n\n  /**\n   * Rules that absorbed nothing this run.\n   *\n   * Not a warning about the config file — a report about the suite. Either the\n   * flake is fixed and the rule is a hole that should close, or the rule stopped\n   * matching and something is being silently reported that the operator believes\n   * is silenced. Both are worth a line.\n   */\n  readonly dead: readonly string[];\n\n  /** Rules past their `until` date. They absorbed nothing, by construction. */\n  readonly expired: readonly string[];\n\n  /**\n   * Subjects whose every difference was absorbed.\n   *\n   * The list that must never be folded into \"unchanged\". These are subjects that\n   * differed and were not looked at.\n   */\n  readonly fullyAbsorbed: readonly string[];\n\n  readonly totalAbsorbed: number;\n}\n\nexport interface IgnoreOutcome {\n  /** The diffs with absorbed deltas removed, in the order they were given. */\n  readonly diffs: readonly SemanticDiff[];\n  readonly register: IgnoreRegister;\n}\n\nexport interface IgnoreOptions {\n  /** Sites per subject id, as resolved against each candidate document. */\n  readonly sites?: Readonly<Record<string, readonly IgnoreSite[]>>;\n\n  /**\n   * Today, as an ISO date, for `until`. Supplied rather than read.\n   *\n   * `core` has no clock — a package that reads one cannot be tested for what it\n   * does on the day a rule expires, which is the only day the field matters.\n   */\n  readonly now?: string;\n}\n\n/**\n * Check a rule before it can absorb anything.\n *\n * Returns the problems rather than throwing, because a config carrying three bad\n * rules should report three, and because the CLI's config parser wants to attach\n * its own file and key to each one.\n */\nexport function validateIgnoreRule(\n  rule: IgnoreRule,\n  options: { readonly hasPlace?: boolean } = {},\n): readonly string[] {\n  const problems: string[] = [];\n\n  if (rule.id.trim() === '') problems.push('needs an id');\n  if (rule.reason.trim() === '') {\n    problems.push(\n      'needs a reason: an ignore nobody can evaluate later is one nobody will ever remove',\n    );\n  }\n\n  // `hasPlace` is the caller's business because a place is resolved outside this\n  // package: a selector needs a DOM. The rule this enforces is the same either\n  // way — a rule that names no place and no shape absorbs everything its bands\n  // cover in every subject it lists, which is a tolerance.\n  const concrete =\n    (options.hasPlace ?? false) ||\n    rule.whole === true ||\n    (rule.fingerprints !== undefined && rule.fingerprints.length > 0);\n\n  if (!concrete) {\n    problems.push(\n      `\"${rule.id}\" names neither a place nor a shape, so there is nothing for it to be scoped ` +\n        'to; an ignore that is only a band is a tolerance',\n    );\n  }\n\n  if (rule.whole === true && rule.bands === undefined) {\n    // `whole` with no band is every difference in the subject, which is not an\n    // ignore — it is switching the subject off, and `subjects.exclude` says that\n    // in a word a reader cannot mistake.\n    problems.push(\n      `\"${rule.id}\" covers the whole subject and narrows nothing, which silences it entirely; ` +\n        'exclude the subject if that is the intent',\n    );\n  }\n\n  if (rule.until !== undefined && Number.isNaN(Date.parse(rule.until))) {\n    problems.push(`until must be an ISO date, not \"${rule.until}\"`);\n  }\n\n  return problems;\n}\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 */\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 */\n/**\n * Apply ignores to a run's diffs, and account for every difference absorbed.\n *\n * Runs after `diffSnapshots` and before `buildDocket`: the docket's arithmetic is\n * about which causes a reviewer signs off on, and a cause nobody is going to look\n * at should not be in it. Everything removed here is counted, attributed to the\n * rule that removed it, and reported.\n */\nexport function applyIgnores(\n  diffs: readonly SemanticDiff[],\n  rules: readonly IgnoreRule[],\n  options: IgnoreOptions = {},\n): IgnoreOutcome {\n  if (rules.length === 0) {\n    return { diffs, register: emptyRegister() };\n  }\n\n  const now = options.now;\n  const expired = rules.filter((rule) => isExpired(rule, now)).map((rule) => rule.id);\n  const live = rules.filter((rule) => !isExpired(rule, now));\n\n  const tallies = new Map<string, Tally>();\n  const fullyAbsorbed: string[] = [];\n  const filtered: SemanticDiff[] = [];\n\n  for (const diff of diffs) {\n    if (diff.identical || diff.deltas.length === 0) {\n      filtered.push(diff);\n      continue;\n    }\n\n    const sites = options.sites?.[diff.subjectId] ?? [];\n    const applicable = live.filter((rule) => appliesToSubject(rule, diff.subjectId));\n\n    if (applicable.length === 0) {\n      filtered.push(diff);\n      continue;\n    }\n\n    // Fingerprints are per root, so they are resolved once per root rather than\n    // once per delta: a root's shape is a property of the whole group, and asking\n    // it repeatedly would make the digest cost quadratic in a wide change set.\n    const fingerprints = new Map<Delta, Digest>();\n    for (const root of diff.roots) {\n      const digest = fingerprintOfRoot(root);\n      for (const delta of root.deltas) fingerprints.set(delta, digest);\n    }\n\n    const absorbedBy = new Map<Delta, IgnoreRule>();\n\n    for (const delta of diff.deltas) {\n      const rule = applicable.find((candidate) =>\n        absorbs(candidate, delta, sites, fingerprints.get(delta)),\n      );\n      if (rule !== undefined) absorbedBy.set(delta, rule);\n    }\n\n    if (absorbedBy.size === 0) {\n      filtered.push(diff);\n      continue;\n    }\n\n    for (const [delta, rule] of absorbedBy) {\n      const tally = tallies.get(rule.id) ?? newTally(rule);\n      tallies.set(rule.id, tally);\n      tally.deltas += 1;\n      tally.subjects.add(diff.subjectId);\n      tally.bands.add(delta.band);\n      const digest = fingerprints.get(delta);\n      if (digest !== undefined) tally.fingerprints.add(digest);\n    }\n\n    const kept = diff.deltas.filter((delta) => !absorbedBy.has(delta));\n    if (kept.length === 0) fullyAbsorbed.push(diff.subjectId);\n\n    filtered.push(rebuild(diff, kept, absorbedBy));\n  }\n\n  const absorbed = [...tallies.values()]\n    .map(finalizeTally)\n    .sort(\n      (a, b) => b.deltas - a.deltas || (a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0),\n    );\n\n  const dead = rules\n    .filter((rule) => !tallies.has(rule.id) && !expired.includes(rule.id))\n    .map((rule) => rule.id);\n\n  return {\n    diffs: filtered,\n    register: {\n      absorbed,\n      dead,\n      expired,\n      fullyAbsorbed,\n      totalAbsorbed: absorbed.reduce((sum, entry) => sum + entry.deltas, 0),\n    },\n  };\n}\n\n/**\n * The register as the paragraph a reader is owed.\n *\n * Absorption first, because that is what changed the verdict; dead and expired\n * rules after it, because those are what the operator has to do something about.\n * A register with nothing in it returns the empty string rather than a cheerful\n * line — a run with no ignores should read exactly as it did before this existed.\n */\nexport function summarizeIgnores(register: IgnoreRegister): string {\n  const lines: string[] = [];\n\n  if (register.totalAbsorbed > 0) {\n    lines.push(\n      `${register.totalAbsorbed} difference(s) absorbed by ${register.absorbed.length} ignore(s).`,\n    );\n    for (const entry of register.absorbed) {\n      lines.push(\n        `  ${entry.rule}: ${entry.deltas} in ${entry.subjects.length} subject(s), ` +\n          `${entry.bands.join('/')} — ${entry.reason}`,\n      );\n    }\n  }\n\n  if (register.fullyAbsorbed.length > 0) {\n    lines.push(\n      `  ${register.fullyAbsorbed.length} subject(s) differed and were entirely ignored: ` +\n        `${register.fullyAbsorbed.slice(0, 3).join(', ')}` +\n        (register.fullyAbsorbed.length > 3 ? ` (+${register.fullyAbsorbed.length - 3} more)` : ''),\n    );\n  }\n\n  for (const rule of register.expired) {\n    lines.push(`  [expired] ${rule} — past its date; it absorbed nothing and is now reporting`);\n  }\n\n  for (const rule of register.dead) {\n    lines.push(\n      `  [dead] ${rule} — absorbed nothing this run; either it is no longer needed, or it ` +\n        'stopped matching and something is being reported that you believe is silenced',\n    );\n  }\n\n  return lines.join('\\n');\n}\n\ninterface Tally {\n  readonly rule: IgnoreRule;\n  deltas: number;\n  readonly subjects: Set<string>;\n  readonly bands: Set<Band>;\n  readonly fingerprints: Set<Digest>;\n}\n\nfunction newTally(rule: IgnoreRule): Tally {\n  return {\n    rule,\n    deltas: 0,\n    subjects: new Set(),\n    bands: new Set(),\n    fingerprints: new Set(),\n  };\n}\n\nfunction finalizeTally(tally: Tally): AbsorbedByRule {\n  return {\n    rule: tally.rule.id,\n    reason: tally.rule.reason,\n    deltas: tally.deltas,\n    subjects: [...tally.subjects],\n    bands: [...tally.bands],\n    fingerprints: [...tally.fingerprints],\n  };\n}\n\nfunction emptyRegister(): IgnoreRegister {\n  return { absorbed: [], dead: [], expired: [], fullyAbsorbed: [], totalAbsorbed: 0 };\n}\n\n/**\n * Whether a rule absorbs one delta.\n *\n * Order matters only for cost. A rule absorbs when it names *this* place or\n * *this* shape and the band, if it named any, is one of them — so a rule that\n * names nothing absorbs nothing, which is the property that keeps a config typo\n * from silencing a suite.\n */\nfunction absorbs(\n  rule: IgnoreRule,\n  delta: Delta,\n  sites: readonly IgnoreSite[],\n  fingerprint: Digest | undefined,\n): boolean {\n  if (rule.bands !== undefined && !rule.bands.includes(delta.band)) return false;\n\n  // Checked after the band and before any place, which is the order that makes\n  // it safe: `whole` is only ever reached by a rule that has already narrowed to\n  // the bands it absorbs, so \"the whole subject\" never means \"everything in it\".\n  if (rule.whole === true) return true;\n\n  if (fingerprint !== undefined && rule.fingerprints?.includes(fingerprint)) return true;\n\n  return sites.some((site) => site.rule === rule.id && isUnder(delta.path, site.path));\n}\n\n/**\n * Rebuild a diff around the deltas that survived.\n *\n * Roots keep their own band and cause — filtering deltas out of a root does not\n * change what caused the rest of them — but a root left with nothing is dropped,\n * because a cause with no observed effect is not a review item. Components and\n * aggregate impact are recomputed from the survivors by the same functions that\n * built them, so a filtered diff cannot disagree with an unfiltered one about\n * what a given set of deltas implies.\n */\nfunction rebuild(\n  diff: SemanticDiff,\n  kept: readonly Delta[],\n  absorbedBy: ReadonlyMap<Delta, IgnoreRule>,\n): SemanticDiff {\n  const roots: Root[] = [];\n\n  for (const root of diff.roots) {\n    const deltas = root.deltas.filter((delta) => !absorbedBy.has(delta));\n    if (deltas.length === 0) continue;\n    roots.push(deltas.length === root.deltas.length ? root : { ...root, deltas });\n  }\n\n  return {\n    ...diff,\n    deltas: kept,\n    roots,\n    components: componentsOf(kept, roots),\n    impact: aggregateImpact(kept.map(impactTag)),\n  };\n}\n"]}

package/dist/judge/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `@variance-authority/core/judge` — from what moved to whether anyone should mind.
+ *
+ * Verdicts and their ordering, intent claims and their adjudication, and the
+ * docket a reader is handed. This is where policy lives, and it is deliberately
+ * the last group and the smallest: everything above it produces facts, and a
+ * team that disagrees with the policy replaces this and keeps the rest.
+ *
+ * `UNOBSERVED` is the group's whole argument in one export. A band a profile
+ * cannot see is not a band that passed, and the type system will not let the two
+ * be spelled the same way.
+ *
+ * `inspect` is the one member that needs no baseline. Everything else here
+ * decides between two snapshots; it decides about one, which is the only way a
+ * defect present on the *first* run is ever reported rather than approved into
+ * the baseline.
+ *
+ * `ignore` is the group's second refusal to conflate two things. A difference the
+ * operator declined to look at is not a difference that did not happen, so an
+ * absorbed delta is counted, attributed to the rule that absorbed it, and the
+ * rule is reported when it absorbs nothing — the same treatment `UNOBSERVED`
+ * gives a band nobody could see.
+ */
+export type { Verdict, BandOutcome } from './verdict.js';
+export { UNOBSERVED, severityOf, blocks } from './verdict.js';
+export { adjudicate, summarizeAdjudication } from './intent.js';
+export type { Intent, IntentClaim, Policy, Adjudication, Adjudicated } from './intent.js';
+export { buildDocket, summarize } from './docket.js';
+export type { Docket, DocketEntry, DocketOptions } from './docket.js';
+export { findingMark, inspect, summarizeFindings } from './inspect.js';
+export type { Finding, FindingRule, InspectionReportOptions } from './inspect.js';
+export { applyIgnores, summarizeIgnores, validateIgnoreRule } from './ignore.js';
+export { isUnder, matchesGlob, appliesToSubject, isExpired } from './scope.js';
+export type { Scoped } from './scope.js';
+export { fingerprintOfRoot, fingerprintOfMask, shapeOfDelta } from './fingerprint.js';
+export type { MaskFingerprintOptions } from './fingerprint.js';
+export type { IgnoreRule, IgnoreOptions, IgnoreOutcome, IgnoreRegister, AbsorbedByRule, } from './ignore.js';
+export { applySensitivity, absorbsEntirely, asIgnore, bandsOf, relaxes, summarizeSensitivity, } from './sensitivity.js';
+export type { Level, SensitivityRule, SensitivityOutcome, SensitivityRegister, Relaxation, } from './sensitivity.js';
+export { startTrail, record, progress, summarizeTrail } from './trail.js';
+export type { Trail, TrailStep, Progress } from './trail.js';
+export { compareLocales } from './locale.js';
+export type { LocaleComparison, LocaleOptions, Uncompared } from './locale.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/judge/index.js

@@ -0,0 +1,34 @@
+/**
+ * `@variance-authority/core/judge` — from what moved to whether anyone should mind.
+ *
+ * Verdicts and their ordering, intent claims and their adjudication, and the
+ * docket a reader is handed. This is where policy lives, and it is deliberately
+ * the last group and the smallest: everything above it produces facts, and a
+ * team that disagrees with the policy replaces this and keeps the rest.
+ *
+ * `UNOBSERVED` is the group's whole argument in one export. A band a profile
+ * cannot see is not a band that passed, and the type system will not let the two
+ * be spelled the same way.
+ *
+ * `inspect` is the one member that needs no baseline. Everything else here
+ * decides between two snapshots; it decides about one, which is the only way a
+ * defect present on the *first* run is ever reported rather than approved into
+ * the baseline.
+ *
+ * `ignore` is the group's second refusal to conflate two things. A difference the
+ * operator declined to look at is not a difference that did not happen, so an
+ * absorbed delta is counted, attributed to the rule that absorbed it, and the
+ * rule is reported when it absorbs nothing — the same treatment `UNOBSERVED`
+ * gives a band nobody could see.
+ */
+export { UNOBSERVED, severityOf, blocks } from './verdict.js';
+export { adjudicate, summarizeAdjudication } from './intent.js';
+export { buildDocket, summarize } from './docket.js';
+export { findingMark, inspect, summarizeFindings } from './inspect.js';
+export { applyIgnores, summarizeIgnores, validateIgnoreRule } from './ignore.js';
+export { isUnder, matchesGlob, appliesToSubject, isExpired } from './scope.js';
+export { fingerprintOfRoot, fingerprintOfMask, shapeOfDelta } from './fingerprint.js';
+export { applySensitivity, absorbsEntirely, asIgnore, bandsOf, relaxes, summarizeSensitivity, } from './sensitivity.js';
+export { startTrail, record, progress, summarizeTrail } from './trail.js';
+export { compareLocales } from './locale.js';
+//# sourceMappingURL=index.js.map

package/dist/judge/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/judge/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGhE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGvE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE/E,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAUtF,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACR,OAAO,EACP,OAAO,EACP,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAS1B,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG1E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC","sourcesContent":["/**\n * `@variance-authority/core/judge` — from what moved to whether anyone should mind.\n *\n * Verdicts and their ordering, intent claims and their adjudication, and the\n * docket a reader is handed. This is where policy lives, and it is deliberately\n * the last group and the smallest: everything above it produces facts, and a\n * team that disagrees with the policy replaces this and keeps the rest.\n *\n * `UNOBSERVED` is the group's whole argument in one export. A band a profile\n * cannot see is not a band that passed, and the type system will not let the two\n * be spelled the same way.\n *\n * `inspect` is the one member that needs no baseline. Everything else here\n * decides between two snapshots; it decides about one, which is the only way a\n * defect present on the *first* run is ever reported rather than approved into\n * the baseline.\n *\n * `ignore` is the group's second refusal to conflate two things. A difference the\n * operator declined to look at is not a difference that did not happen, so an\n * absorbed delta is counted, attributed to the rule that absorbed it, and the\n * rule is reported when it absorbs nothing — the same treatment `UNOBSERVED`\n * gives a band nobody could see.\n */\n\nexport type { Verdict, BandOutcome } from './verdict.js';\nexport { UNOBSERVED, severityOf, blocks } from './verdict.js';\n\nexport { adjudicate, summarizeAdjudication } from './intent.js';\nexport type { Intent, IntentClaim, Policy, Adjudication, Adjudicated } from './intent.js';\n\nexport { buildDocket, summarize } from './docket.js';\nexport type { Docket, DocketEntry, DocketOptions } from './docket.js';\n\nexport { findingMark, inspect, summarizeFindings } from './inspect.js';\nexport type { Finding, FindingRule, InspectionReportOptions } from './inspect.js';\n\nexport { applyIgnores, summarizeIgnores, validateIgnoreRule } from './ignore.js';\nexport { isUnder, matchesGlob, appliesToSubject, isExpired } from './scope.js';\nexport type { Scoped } from './scope.js';\nexport { fingerprintOfRoot, fingerprintOfMask, shapeOfDelta } from './fingerprint.js';\nexport type { MaskFingerprintOptions } from './fingerprint.js';\nexport type {\n  IgnoreRule,\n  IgnoreOptions,\n  IgnoreOutcome,\n  IgnoreRegister,\n  AbsorbedByRule,\n} from './ignore.js';\n\nexport {\n  applySensitivity,\n  absorbsEntirely,\n  asIgnore,\n  bandsOf,\n  relaxes,\n  summarizeSensitivity,\n} from './sensitivity.js';\nexport type {\n  Level,\n  SensitivityRule,\n  SensitivityOutcome,\n  SensitivityRegister,\n  Relaxation,\n} from './sensitivity.js';\n\nexport { startTrail, record, progress, summarizeTrail } from './trail.js';\nexport type { Trail, TrailStep, Progress } from './trail.js';\n\nexport { compareLocales } from './locale.js';\nexport type { LocaleComparison, LocaleOptions, Uncompared } from './locale.js';\n"]}

package/dist/judge/inspect.d.ts

@@ -0,0 +1,148 @@
+import type { Band } from '../compare/band.js';
+import type { OwnerFrame, SourceLocation } from '../format/provenance.js';
+import type { NodePath, SemanticSnapshot } from '../format/snapshot.js';
+import { type SourceIndex } from '../attribute/source.js';
+/**
+ * What a render says without a baseline.
+ *
+ * Two producers, one `Finding` type. `inspect` reads a single snapshot;
+ * `compareLocales` reads two renders of one subject in different languages,
+ * which is also not a regression comparison — both renders are correct. Sharing
+ * the type is what lets the report, the CLI and the MCP tools carry both without
+ * knowing which produced what.
+ *
+ * The rest of this comment is about `inspect`, which reads one snapshot with no
+ * baseline and no second run.
+ *
+ * Everything else in this package answers *what changed*, which requires two of
+ * something. That framing has a blind spot the whole category shares: **a defect
+ * that was present on the first run is invisible to a comparison forever.** A
+ * button that never had an accessible name compares equal to itself on every run
+ * until someone happens to edit it, and a picture of it is a perfectly good
+ * picture. Approving the first baseline approves the defect.
+ *
+ * These rules read the normalized snapshot and report defects in it. Consequences
+ * worth stating, because they are the practical argument for having the document
+ * rather than an image of it:
+ *
+ * - **A fresh checkout with zero baselines is already useful.** The expensive
+ *   part of adopting a visual-regression tool is that it says nothing until it
+ *   has a history; this half says something on the first run.
+ * - **Every finding names a component and a file**, through the same provenance
+ *   chain a delta uses. A rule engine that reports a DOM path reports where the
+ *   symptom is; this reports whose JSX wrote it.
+ * - **They band as `a11y`**, so a project that writes `blocking: ['a11y']` gets
+ *   both halves under one policy: regressions found by comparison, and defects
+ *   found by inspection.
+ *
+ * Deliberately *not* an axe-core reimplementation. Axe runs against a live DOM
+ * with computed visibility, contrast and focus order, and does dozens of things
+ * this cannot. What is here is the subset a normalized snapshot can decide
+ * without guessing — and the subset it can decide **offline, from a stored
+ * artifact, months later**, which is a thing axe cannot do at all.
+ *
+ * There is no severity field. A rule that needs one to be tolerable is a rule
+ * whose condition is too broad, and the fix is a better condition or no rule.
+ *
+ * **Why there is no contrast rule, stated here so nobody adds one badly later.**
+ * The snapshot carries a resolved `color` and `background-color` per node, so a
+ * check looks like four lines and would be wrong: the background a glyph is
+ * actually painted on is whatever is behind it, which is a stacking question a
+ * layout engine answers and a document does not. A node with a transparent
+ * background over a dark ancestor, an image, a gradient, or a positioned sibling
+ * all read as "background-color: rgba(0,0,0,0)" here. A rule that is right most
+ * of the time about accessibility is worse than no rule: it gets disabled after
+ * the second false alarm, and takes the four that work with it. Spec 0009
+ * records the same for focus order and anything about motion.
+ */
+export type FindingRule = 
+/** An interactive control with no accessible name. Nothing announces it. */
+'control-without-name'
+/** A meaningful image with neither a name nor an explicit `alt=""`. */
+ | 'image-without-alt'
+/** Heading levels jump forward by more than one. */
+ | 'heading-level-skipped'
+/** A control inside another control. Only one of them is reachable. */
+ | 'nested-interactive'
+/** An id reference that resolves to nothing inside this subject. */
+ | 'dangling-reference'
+/** A control whose accessible name does not contain its visible label. */
+ | 'label-mismatch'
+/** Two landmarks of one role that nothing tells apart. */
+ | 'duplicate-landmark'
+/** A table with no header cells. */
+ | 'table-without-headers'
+/** `tabindex` above zero, which reorders focus for the whole page. */
+ | 'positive-tabindex'
+/**
+ * The same string in two locales. From `compareLocales`, not from `inspect` —
+ * one render cannot know whether its text was translated.
+ */
+ | 'untranslated'
+/** A box outside the box that contains it, in one locale and not the other. */
+ | 'overflows-container';
+/**
+ * The identity of a finding, as a string two runs can be compared on.
+ *
+ * A finding is *the same finding* when the same rule fires on the same node. Not
+ * the same sentence: `what` quotes the text it found, so a copy edit beside a
+ * control with no accessible name would read as the old defect going away and a
+ * new one arriving in the same place. And not the same component either — a
+ * component renders in many places, and every one of them would collapse to one.
+ *
+ * Small on purpose. This is what a baseline carries so that the next run can say
+ * whether a defect it found was already there, and a baseline sidecar rides
+ * beside a PNG in a tracked directory: a mark is a few dozen bytes and a stored
+ * `Finding` is a paragraph. It can only answer membership, which is the only
+ * question the next run is allowed to ask of it — the same restraint
+ * `Described.components` is written under.
+ */
+export declare function findingMark(finding: {
+    readonly rule: string;
+    readonly path: string;
+}): string;
+export interface Finding {
+    readonly rule: FindingRule;
+    /**
+     * The band this finding would block under.
+     *
+     * Carried so that inspection and comparison answer to one policy. A team that
+     * blocks `a11y` should not have to discover that it blocks regressions and not
+     * defects.
+     */
+    readonly band: Band;
+    readonly path: NodePath;
+    /** One sentence, naming the thing rather than the rule. */
+    readonly what: string;
+    /** Spoken outside-in, from `locate` — `main → region "Todos" → item 2 of 3`. */
+    readonly where?: string;
+    /** The component whose JSX created the node, when provenance reached it. */
+    readonly component?: string;
+    readonly owners?: readonly OwnerFrame[];
+    /**
+     * The line that wrote *this element*, when a JSX runtime recorded one.
+     *
+     * Different from — and better than — resolving `component` through the source
+     * index, which answers with where the component is *declared*. A defect is
+     * rarely at a declaration: a button with no accessible name is a specific
+     * element on a specific line inside that component, and that line is the edit.
+     * The index stays as the fallback, because it needs no build change.
+     *
+     * Requires `@variance-authority/jsx-source` in the transform. Absent otherwise,
+     * and absence is normal.
+     */
+    readonly source?: SourceLocation;
+}
+export declare function inspect(snapshot: SemanticSnapshot): readonly Finding[];
+export interface InspectionReportOptions {
+    /** Component → file, so a finding names an edit rather than an identifier. */
+    readonly source?: SourceIndex;
+}
+/**
+ * Findings as the thing a reviewer or an agent reads.
+ *
+ * Same shape as `summarizeAdjudication`: what, where, which file. A finding a
+ * reader has to go and locate is a finding that gets skipped.
+ */
+export declare function summarizeFindings(findings: readonly Finding[], options?: InspectionReportOptions): string;
+//# sourceMappingURL=inspect.d.ts.map