@variance-authority/core 0.1.0

package/dist/judge/locale.d.ts

@@ -0,0 +1,111 @@
+import type { NodePath, SemanticSnapshot } from '../format/snapshot.js';
+import type { Finding } from './inspect.js';
+/**
+ * One subject, two locales.
+ *
+ * The join a pixel differ cannot make. A baseline image and a message catalogue
+ * have nothing in common — there is no key that relates the string `checkout.cta`
+ * to a region of a PNG — so every product in the category answers a locale
+ * question by taking N times as many screenshots and asking a human to look at
+ * all of them. The document has the strings *and* the boxes, addressed to the
+ * same nodes, so the two questions a localized UI actually raises are arithmetic:
+ *
+ * 1. **Did this string get translated?** Identical text in two locales, in a
+ *    subject where other text did change.
+ * 2. **Did the translation break the layout?** A box that fits its container in
+ *    one locale and overflows it in another.
+ *
+ * **This is not a regression comparison and must not be read as one.** Both
+ * renders are correct. `diffSnapshots` answers "did this change since the
+ * baseline"; this answers "do these two agree about everything except their
+ * language", which is a different question with a different failure mode. So it
+ * produces `Finding`s — the same type inspection produces, for the same reason:
+ * a defect in a render, not a change to one.
+ *
+ * **What is deliberately not here.** No expansion threshold. "German is 35%
+ * longer" is a rule of thumb, and a tool that fails a build on a ratio is a tool
+ * whose ratio gets raised until it stops failing. The growth is *measured* and
+ * returned; only overflow — a box outside the box that contains it, which is a
+ * fact about two rectangles — is a finding.
+ */
+export interface LocaleComparison {
+    readonly subject: string;
+    /** Whatever the caller calls the two renders. This module reads no locale tags. */
+    readonly base: string;
+    readonly other: string;
+    /** Text nodes that differ. Evidence that translation happened at all. */
+    readonly translated: number;
+    /** Text nodes carrying letters that are byte-identical in both. */
+    readonly identical: number;
+    readonly findings: readonly Finding[];
+    /**
+     * The largest width growth observed, when both sides carried layout.
+     *
+     * Reported, never judged. A reviewer deciding whether a locale is safe wants
+     * the number and the component; a build deciding it from a threshold wants an
+     * argument nobody has made.
+     */
+    readonly expansion?: {
+        readonly ratio: number;
+        readonly path: NodePath;
+        readonly component?: string;
+    };
+    /**
+     * `false` when either side lacked rects, so overflow could not be decided.
+     *
+     * The same rule as `unobserved`: a question that was not asked has no answer,
+     * and "no overflow findings" must not be readable as "nothing overflows" when
+     * the profile had no layout engine.
+     */
+    readonly layoutObserved: boolean;
+    /**
+     * What the two trees did not have in common, and therefore what was not asked.
+     *
+     * {@link pairByPosition} refuses to guess across a structural difference: a
+     * node whose tag moved takes its whole subtree out of the comparison, and
+     * children past the shorter of the two lists are never reached. Both are the
+     * right call — a plural form with an extra element is not evidence about
+     * translation — and both make this function return **fewer findings**, which
+     * is the one direction a partial answer must never be reported in silently.
+     *
+     * A German plural that adds a `<span>`, or a locale whose date renders as
+     * `<time>` where English renders `<span>`, drops real strings out of the
+     * comparison. Without this field the run looks *cleaner* for it: zero
+     * untranslated strings, because zero strings were examined.
+     *
+     * Always present, never absent when the trees agree. `{ base: 0, other: 0 }`
+     * says the trees were walked and matched; a missing field would say nobody
+     * counted, and those are the two things this project exists to keep apart.
+     */
+    readonly uncompared: Uncompared;
+}
+export interface Uncompared {
+    /** Nodes in the base render that nothing in the other render was paired with. */
+    readonly base: number;
+    /** Nodes in the other render that nothing in the base render was paired with. */
+    readonly other: number;
+    /**
+     * Where pairing stopped, as paths in the *base* render, in document order.
+     *
+     * A count says the answer is partial; a path says where to look. Reported in
+     * the base render's addresses because that is the side a reader has a
+     * baseline for — the other locale's paths past a divergence are addresses in
+     * a tree nothing here compared.
+     */
+    readonly divergedAt: readonly NodePath[];
+}
+export interface LocaleOptions {
+    /**
+     * Slack in pixels before a box counts as outside its container.
+     *
+     * Not a tolerance on the finding — a tolerance on *rounding*. Sub-pixel layout
+     * routinely puts a child a fraction outside its parent's rounded rect, and
+     * reporting that as overflow would bury the real ones.
+     */
+    readonly slack?: number;
+}
+export declare function compareLocales(base: SemanticSnapshot, other: SemanticSnapshot, labels: {
+    readonly base: string;
+    readonly other: string;
+}, options?: LocaleOptions): LocaleComparison;
+//# sourceMappingURL=locale.d.ts.map

package/dist/judge/locale.js

@@ -0,0 +1,247 @@
+import { locate } from '../attribute/locate.js';
+/** Has at least one letter. `€ 2,400.00` and `—` are not strings anyone translates. */
+const TRANSLATABLE = /\p{L}/u;
+/**
+ * Attributes that carry prose, and are therefore translated.
+ *
+ * The list matters more than it looks. The first run of this against a real
+ * panel found **nothing**, because the only untranslated string in the fixture
+ * was a `title` — and the rule was reading text nodes only. In a real product
+ * the strings most often left behind are exactly these: an `aria-label` on an
+ * icon button, a `placeholder`, an `alt`. They render no pixel of their own,
+ * which is why they are forgotten, and why no image comparison at any tolerance
+ * has ever reported one.
+ */
+const TRANSLATABLE_ATTRIBUTES = ['title', 'alt', 'placeholder'];
+export function compareLocales(base, other, labels, options = {}) {
+    if (base.subject.id !== other.subject.id) {
+        throw new Error(`refusing to compare locales of different subjects: ${base.subject.id} vs ${other.subject.id}`);
+    }
+    const slack = options.slack ?? 1;
+    const { pairs, uncompared } = pairByPosition(base.root, other.root);
+    const findings = [];
+    const identical = [];
+    let translated = 0;
+    let layoutObserved = false;
+    let expansion;
+    for (const { before, after, container } of pairs) {
+        // Text, then the accessible name and description, then the prose-bearing
+        // attributes. All four are strings a translator is handed and all four are
+        // invisible to a camera in different ways: a name is announced and never
+        // painted, a `title` appears only on hover, an `alt` only when the image
+        // does not load.
+        for (const [what, was, is] of stringsOf(before, after)) {
+            if (was !== is) {
+                translated += 1;
+            }
+            else if (TRANSLATABLE.test(is)) {
+                identical.push({ node: after, text: is, what });
+            }
+        }
+        if (before.rect === undefined || after.rect === undefined)
+            continue;
+        layoutObserved = true;
+        if (before.rect.width > 0) {
+            const ratio = after.rect.width / before.rect.width;
+            if (expansion === undefined || ratio > expansion.ratio) {
+                expansion = { ratio, path: after.path, ...component(after) };
+            }
+        }
+        // Overflow is judged in the *other* locale against this node's container
+        // there, and only where the base render fitted. A layout that was already
+        // broken is a real problem and is not this one: reporting it would put a
+        // pre-existing bug in front of whoever is reviewing a translation, in every
+        // locale, every time.
+        if (container === undefined)
+            continue;
+        const outsideNow = after.rect.x + after.rect.width;
+        const insideNow = container.after.rect.x + container.after.rect.width;
+        const outsideBefore = before.rect.x + before.rect.width;
+        const insideBefore = container.before.rect.x + container.before.rect.width;
+        if (outsideNow > insideNow + slack && outsideBefore <= insideBefore + slack) {
+            findings.push(finding('overflows-container', 'geometry', after, other, `${describe(after)} is ${Math.round(outsideNow - insideNow)}px wider than what ` +
+                `contains it in ${labels.other}, and fitted in ${labels.base}`));
+        }
+    }
+    // Only when something *was* translated. A subject rendered twice in one
+    // language has every string identical, and reporting all of them as
+    // untranslated would be a tool telling the truth about nothing.
+    if (translated > 0) {
+        // One node, one string, one finding. An icon button's `title` and its
+        // accessible name are routinely the same string, and reporting both is
+        // reporting one missing translation twice — the same collapse the
+        // name-from-content check makes above, at the other end.
+        for (const { node, text, what } of collapse(identical)) {
+            findings.push(finding('untranslated', 'content', node, other, `${what} "${clip(text)}" is identical in ${labels.base} and ${labels.other} — ` +
+                'either it was not translated, or it is a name that does not change'));
+        }
+    }
+    return {
+        subject: other.subject.id,
+        base: labels.base,
+        other: labels.other,
+        translated,
+        identical: identical.length,
+        findings,
+        ...(expansion !== undefined ? { expansion } : {}),
+        layoutObserved,
+        uncompared,
+    };
+}
+/**
+ * Every string on a node, paired across the two renders, labelled by where it
+ * came from so the finding can say *which* string rather than only its value.
+ *
+ * A string present on one side and absent on the other is skipped rather than
+ * counted as translated. That is a structural difference between the renders,
+ * which is what `pairByPosition` refuses to guess about, and counting it here
+ * would smuggle the guess back in through a different door.
+ */
+/**
+ * One entry per (node, value). Where several fields carry the same string, they
+ * are named together: `accessible name / title=` says more than either alone and
+ * is still one thing to fix.
+ */
+function collapse(candidates) {
+    const byValue = new Map();
+    for (const candidate of candidates) {
+        const key = `${candidate.node.path}\u0000${candidate.text}`;
+        const seen = byValue.get(key);
+        if (seen)
+            seen.whats.push(candidate.what);
+        else
+            byValue.set(key, { node: candidate.node, text: candidate.text, whats: [candidate.what] });
+    }
+    return [...byValue.values()].map(({ node, text, whats }) => ({
+        node,
+        text,
+        what: whats.join(' / '),
+    }));
+}
+function stringsOf(before, after) {
+    const strings = [];
+    const pair = (what, was, is) => {
+        if (was !== undefined && is !== undefined)
+            strings.push([what, was, is]);
+    };
+    pair('text', before.text, after.text);
+    // A name computed from content *is* the text, observed a second way. Counting
+    // both makes one translated string read as two, and one missing translation
+    // read as two findings on one node. Same rule as `derivedFrom` on a delta.
+    if (before.name !== before.text || after.name !== after.text) {
+        pair('accessible name', before.name, after.name);
+    }
+    pair('accessible description', before.description, after.description);
+    for (const attribute of TRANSLATABLE_ATTRIBUTES) {
+        pair(`${attribute}=`, before.attributes[attribute], after.attributes[attribute]);
+    }
+    return strings;
+}
+function finding(rule, band, node, snapshot, what) {
+    const where = locate(snapshot.root, node.path).where;
+    return {
+        rule,
+        band,
+        path: node.path,
+        what,
+        ...(where !== '' ? { where } : {}),
+        ...component(node),
+        ...(node.provenance ? { owners: node.provenance.owners } : {}),
+    };
+}
+/**
+ * A text node has no provenance of its own — React does not own text — so the
+ * name comes from the nearest owner recorded on it, and the caller's tree walk
+ * has already put the enclosing component there.
+ */
+function component(node) {
+    const name = node.provenance?.createdBy ?? node.provenance?.owners[0]?.name;
+    return name === undefined ? {} : { component: name };
+}
+function describe(node) {
+    if (node.name !== undefined)
+        return `${node.role ?? node.tag} "${clip(node.name)}"`;
+    if (node.text !== undefined)
+        return `"${clip(node.text)}"`;
+    return `<${node.tag}>`;
+}
+function clip(text) {
+    return text.length <= 40 ? text : `${text.slice(0, 39)}…`;
+}
+/**
+ * Pair the two trees by position, not by identity — and this is the whole reason
+ * `matchTrees` is not reused here.
+ *
+ * `matchKey` keys a node on its role and accessible name, because that is the
+ * strongest signal that two renders of one revision are showing the same thing.
+ * A translation changes exactly that: `button "Continue"` and
+ * `button "Fortfahren"` get different keys, so the differ reports the button as
+ * removed and a different one added, and every comparison this module wants to
+ * make evaporates. It is the right key for "same language, later revision" and
+ * the wrong one for "same revision, another language".
+ *
+ * Position is the right key here because a translation is not supposed to change
+ * the tree. Where the shapes diverge — a locale that wraps to two lines with an
+ * extra element, a plural form with a different structure — pairing stops at
+ * that branch rather than guessing, and the strings underneath it are simply not
+ * compared. Under-reporting, which is the direction to fail in for a report that
+ * does not block anything.
+ *
+ * **Under-reporting is only the safe direction while it is counted.** Silent, it
+ * is the failure this whole project refuses, wearing the most convincing
+ * disguise available: a subject whose tree diverged reports *fewer* untranslated
+ * strings than one that matched, so the locale nobody translated reads as the
+ * clean one. So every node the walk did not reach is counted, and every branch
+ * it stopped at is named.
+ */
+function pairByPosition(base, other) {
+    const pairs = [];
+    const divergedAt = [];
+    const walk = (before, after, container) => {
+        if (before.tag !== after.tag) {
+            // This node and everything under it, on both sides. Recorded at the node
+            // that stopped the walk rather than at each of its descendants: one
+            // address a reader can open beats a list of addresses in a subtree that
+            // was never examined.
+            divergedAt.push(before.path);
+            return;
+        }
+        const pair = {
+            before,
+            after,
+            ...(container !== undefined && container.before.rect !== undefined &&
+                container.after.rect !== undefined
+                ? { container }
+                : {}),
+        };
+        pairs.push(pair);
+        const count = Math.min(before.children.length, after.children.length);
+        // The parent, because the unreached children are the ones the *shorter*
+        // list does not have — on whichever side that is, they have no counterpart
+        // to be addressed by.
+        if (before.children.length !== after.children.length)
+            divergedAt.push(before.path);
+        for (let index = 0; index < count; index += 1) {
+            walk(before.children[index], after.children[index], pair);
+        }
+    };
+    walk(base, other);
+    // Total minus paired, per side. A pair consumes exactly one node from each, so
+    // the two subtractions are independent and a lopsided divergence says which
+    // render carried the extra material.
+    return {
+        pairs,
+        uncompared: {
+            base: countNodes(base) - pairs.length,
+            other: countNodes(other) - pairs.length,
+            divergedAt,
+        },
+    };
+}
+function countNodes(node) {
+    let total = 1;
+    for (const child of node.children)
+        total += countNodes(child);
+    return total;
+}
+//# sourceMappingURL=locale.js.map

package/dist/judge/locale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.js","sourceRoot":"","sources":["../../src/judge/locale.ts"],"names":[],"mappings":"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","sourcesContent":["import type { NodePath, SemanticNode, SemanticSnapshot } from '../format/snapshot.js';\nimport { locate } from '../attribute/locate.js';\nimport type { Finding } from './inspect.js';\n\n/**\n * One subject, two locales.\n *\n * The join a pixel differ cannot make. A baseline image and a message catalogue\n * have nothing in common — there is no key that relates the string `checkout.cta`\n * to a region of a PNG — so every product in the category answers a locale\n * question by taking N times as many screenshots and asking a human to look at\n * all of them. The document has the strings *and* the boxes, addressed to the\n * same nodes, so the two questions a localized UI actually raises are arithmetic:\n *\n * 1. **Did this string get translated?** Identical text in two locales, in a\n *    subject where other text did change.\n * 2. **Did the translation break the layout?** A box that fits its container in\n *    one locale and overflows it in another.\n *\n * **This is not a regression comparison and must not be read as one.** Both\n * renders are correct. `diffSnapshots` answers \"did this change since the\n * baseline\"; this answers \"do these two agree about everything except their\n * language\", which is a different question with a different failure mode. So it\n * produces `Finding`s — the same type inspection produces, for the same reason:\n * a defect in a render, not a change to one.\n *\n * **What is deliberately not here.** No expansion threshold. \"German is 35%\n * longer\" is a rule of thumb, and a tool that fails a build on a ratio is a tool\n * whose ratio gets raised until it stops failing. The growth is *measured* and\n * returned; only overflow — a box outside the box that contains it, which is a\n * fact about two rectangles — is a finding.\n */\n\nexport interface LocaleComparison {\n  readonly subject: string;\n  /** Whatever the caller calls the two renders. This module reads no locale tags. */\n  readonly base: string;\n  readonly other: string;\n\n  /** Text nodes that differ. Evidence that translation happened at all. */\n  readonly translated: number;\n  /** Text nodes carrying letters that are byte-identical in both. */\n  readonly identical: number;\n\n  readonly findings: readonly Finding[];\n\n  /**\n   * The largest width growth observed, when both sides carried layout.\n   *\n   * Reported, never judged. A reviewer deciding whether a locale is safe wants\n   * the number and the component; a build deciding it from a threshold wants an\n   * argument nobody has made.\n   */\n  readonly expansion?: {\n    readonly ratio: number;\n    readonly path: NodePath;\n    readonly component?: string;\n  };\n\n  /**\n   * `false` when either side lacked rects, so overflow could not be decided.\n   *\n   * The same rule as `unobserved`: a question that was not asked has no answer,\n   * and \"no overflow findings\" must not be readable as \"nothing overflows\" when\n   * the profile had no layout engine.\n   */\n  readonly layoutObserved: boolean;\n\n  /**\n   * What the two trees did not have in common, and therefore what was not asked.\n   *\n   * {@link pairByPosition} refuses to guess across a structural difference: a\n   * node whose tag moved takes its whole subtree out of the comparison, and\n   * children past the shorter of the two lists are never reached. Both are the\n   * right call — a plural form with an extra element is not evidence about\n   * translation — and both make this function return **fewer findings**, which\n   * is the one direction a partial answer must never be reported in silently.\n   *\n   * A German plural that adds a `<span>`, or a locale whose date renders as\n   * `<time>` where English renders `<span>`, drops real strings out of the\n   * comparison. Without this field the run looks *cleaner* for it: zero\n   * untranslated strings, because zero strings were examined.\n   *\n   * Always present, never absent when the trees agree. `{ base: 0, other: 0 }`\n   * says the trees were walked and matched; a missing field would say nobody\n   * counted, and those are the two things this project exists to keep apart.\n   */\n  readonly uncompared: Uncompared;\n}\n\nexport interface Uncompared {\n  /** Nodes in the base render that nothing in the other render was paired with. */\n  readonly base: number;\n  /** Nodes in the other render that nothing in the base render was paired with. */\n  readonly other: number;\n\n  /**\n   * Where pairing stopped, as paths in the *base* render, in document order.\n   *\n   * A count says the answer is partial; a path says where to look. Reported in\n   * the base render's addresses because that is the side a reader has a\n   * baseline for — the other locale's paths past a divergence are addresses in\n   * a tree nothing here compared.\n   */\n  readonly divergedAt: readonly NodePath[];\n}\n\nexport interface LocaleOptions {\n  /**\n   * Slack in pixels before a box counts as outside its container.\n   *\n   * Not a tolerance on the finding — a tolerance on *rounding*. Sub-pixel layout\n   * routinely puts a child a fraction outside its parent's rounded rect, and\n   * reporting that as overflow would bury the real ones.\n   */\n  readonly slack?: number;\n}\n\n/** Has at least one letter. `€ 2,400.00` and `—` are not strings anyone translates. */\nconst TRANSLATABLE = /\\p{L}/u;\n\n/**\n * Attributes that carry prose, and are therefore translated.\n *\n * The list matters more than it looks. The first run of this against a real\n * panel found **nothing**, because the only untranslated string in the fixture\n * was a `title` — and the rule was reading text nodes only. In a real product\n * the strings most often left behind are exactly these: an `aria-label` on an\n * icon button, a `placeholder`, an `alt`. They render no pixel of their own,\n * which is why they are forgotten, and why no image comparison at any tolerance\n * has ever reported one.\n */\nconst TRANSLATABLE_ATTRIBUTES = ['title', 'alt', 'placeholder'] as const;\n\nexport function compareLocales(\n  base: SemanticSnapshot,\n  other: SemanticSnapshot,\n  labels: { readonly base: string; readonly other: string },\n  options: LocaleOptions = {},\n): LocaleComparison {\n  if (base.subject.id !== other.subject.id) {\n    throw new Error(\n      `refusing to compare locales of different subjects: ${base.subject.id} vs ${other.subject.id}`,\n    );\n  }\n\n  const slack = options.slack ?? 1;\n  const { pairs, uncompared } = pairByPosition(base.root, other.root);\n\n  const findings: Finding[] = [];\n  const identical: { node: SemanticNode; text: string; what: string }[] = [];\n  let translated = 0;\n  let layoutObserved = false;\n  let expansion: LocaleComparison['expansion'];\n\n  for (const { before, after, container } of pairs) {\n    // Text, then the accessible name and description, then the prose-bearing\n    // attributes. All four are strings a translator is handed and all four are\n    // invisible to a camera in different ways: a name is announced and never\n    // painted, a `title` appears only on hover, an `alt` only when the image\n    // does not load.\n    for (const [what, was, is] of stringsOf(before, after)) {\n      if (was !== is) {\n        translated += 1;\n      } else if (TRANSLATABLE.test(is)) {\n        identical.push({ node: after, text: is, what });\n      }\n    }\n\n    if (before.rect === undefined || after.rect === undefined) continue;\n    layoutObserved = true;\n\n    if (before.rect.width > 0) {\n      const ratio = after.rect.width / before.rect.width;\n      if (expansion === undefined || ratio > expansion.ratio) {\n        expansion = { ratio, path: after.path, ...component(after) };\n      }\n    }\n\n    // Overflow is judged in the *other* locale against this node's container\n    // there, and only where the base render fitted. A layout that was already\n    // broken is a real problem and is not this one: reporting it would put a\n    // pre-existing bug in front of whoever is reviewing a translation, in every\n    // locale, every time.\n    if (container === undefined) continue;\n\n    const outsideNow = after.rect.x + after.rect.width;\n    const insideNow = container.after.rect!.x + container.after.rect!.width;\n    const outsideBefore = before.rect.x + before.rect.width;\n    const insideBefore = container.before.rect!.x + container.before.rect!.width;\n\n    if (outsideNow > insideNow + slack && outsideBefore <= insideBefore + slack) {\n      findings.push(\n        finding(\n          'overflows-container',\n          'geometry',\n          after,\n          other,\n          `${describe(after)} is ${Math.round(outsideNow - insideNow)}px wider than what ` +\n            `contains it in ${labels.other}, and fitted in ${labels.base}`,\n        ),\n      );\n    }\n  }\n\n  // Only when something *was* translated. A subject rendered twice in one\n  // language has every string identical, and reporting all of them as\n  // untranslated would be a tool telling the truth about nothing.\n  if (translated > 0) {\n    // One node, one string, one finding. An icon button's `title` and its\n    // accessible name are routinely the same string, and reporting both is\n    // reporting one missing translation twice — the same collapse the\n    // name-from-content check makes above, at the other end.\n    for (const { node, text, what } of collapse(identical)) {\n      findings.push(\n        finding(\n          'untranslated',\n          'content',\n          node,\n          other,\n          `${what} \"${clip(text)}\" is identical in ${labels.base} and ${labels.other} — ` +\n            'either it was not translated, or it is a name that does not change',\n        ),\n      );\n    }\n  }\n\n  return {\n    subject: other.subject.id,\n    base: labels.base,\n    other: labels.other,\n    translated,\n    identical: identical.length,\n    findings,\n    ...(expansion !== undefined ? { expansion } : {}),\n    layoutObserved,\n    uncompared,\n  };\n}\n\n/**\n * Every string on a node, paired across the two renders, labelled by where it\n * came from so the finding can say *which* string rather than only its value.\n *\n * A string present on one side and absent on the other is skipped rather than\n * counted as translated. That is a structural difference between the renders,\n * which is what `pairByPosition` refuses to guess about, and counting it here\n * would smuggle the guess back in through a different door.\n */\n/**\n * One entry per (node, value). Where several fields carry the same string, they\n * are named together: `accessible name / title=` says more than either alone and\n * is still one thing to fix.\n */\nfunction collapse(\n  candidates: readonly { node: SemanticNode; text: string; what: string }[],\n): readonly { node: SemanticNode; text: string; what: string }[] {\n  const byValue = new Map<string, { node: SemanticNode; text: string; whats: string[] }>();\n\n  for (const candidate of candidates) {\n    const key = `${candidate.node.path}\\u0000${candidate.text}`;\n    const seen = byValue.get(key);\n    if (seen) seen.whats.push(candidate.what);\n    else byValue.set(key, { node: candidate.node, text: candidate.text, whats: [candidate.what] });\n  }\n\n  return [...byValue.values()].map(({ node, text, whats }) => ({\n    node,\n    text,\n    what: whats.join(' / '),\n  }));\n}\n\nfunction stringsOf(\n  before: SemanticNode,\n  after: SemanticNode,\n): readonly (readonly [what: string, was: string, is: string])[] {\n  const strings: (readonly [string, string, string])[] = [];\n\n  const pair = (what: string, was: string | undefined, is: string | undefined): void => {\n    if (was !== undefined && is !== undefined) strings.push([what, was, is]);\n  };\n\n  pair('text', before.text, after.text);\n\n  // A name computed from content *is* the text, observed a second way. Counting\n  // both makes one translated string read as two, and one missing translation\n  // read as two findings on one node. Same rule as `derivedFrom` on a delta.\n  if (before.name !== before.text || after.name !== after.text) {\n    pair('accessible name', before.name, after.name);\n  }\n  pair('accessible description', before.description, after.description);\n  for (const attribute of TRANSLATABLE_ATTRIBUTES) {\n    pair(`${attribute}=`, before.attributes[attribute], after.attributes[attribute]);\n  }\n\n  return strings;\n}\n\nfunction finding(\n  rule: 'untranslated' | 'overflows-container',\n  band: Finding['band'],\n  node: SemanticNode,\n  snapshot: SemanticSnapshot,\n  what: string,\n): Finding {\n  const where = locate(snapshot.root, node.path).where;\n\n  return {\n    rule,\n    band,\n    path: node.path,\n    what,\n    ...(where !== '' ? { where } : {}),\n    ...component(node),\n    ...(node.provenance ? { owners: node.provenance.owners } : {}),\n  };\n}\n\n/**\n * A text node has no provenance of its own — React does not own text — so the\n * name comes from the nearest owner recorded on it, and the caller's tree walk\n * has already put the enclosing component there.\n */\nfunction component(node: SemanticNode): { component?: string } {\n  const name = node.provenance?.createdBy ?? node.provenance?.owners[0]?.name;\n  return name === undefined ? {} : { component: name };\n}\n\nfunction describe(node: SemanticNode): string {\n  if (node.name !== undefined) return `${node.role ?? node.tag} \"${clip(node.name)}\"`;\n  if (node.text !== undefined) return `\"${clip(node.text)}\"`;\n  return `<${node.tag}>`;\n}\n\nfunction clip(text: string): string {\n  return text.length <= 40 ? text : `${text.slice(0, 39)}…`;\n}\n\ninterface Pair {\n  readonly before: SemanticNode;\n  readonly after: SemanticNode;\n  /** The enclosing pair, when both sides have one *and* both carry rects. */\n  readonly container?: Pair;\n}\n\n/**\n * Pair the two trees by position, not by identity — and this is the whole reason\n * `matchTrees` is not reused here.\n *\n * `matchKey` keys a node on its role and accessible name, because that is the\n * strongest signal that two renders of one revision are showing the same thing.\n * A translation changes exactly that: `button \"Continue\"` and\n * `button \"Fortfahren\"` get different keys, so the differ reports the button as\n * removed and a different one added, and every comparison this module wants to\n * make evaporates. It is the right key for \"same language, later revision\" and\n * the wrong one for \"same revision, another language\".\n *\n * Position is the right key here because a translation is not supposed to change\n * the tree. Where the shapes diverge — a locale that wraps to two lines with an\n * extra element, a plural form with a different structure — pairing stops at\n * that branch rather than guessing, and the strings underneath it are simply not\n * compared. Under-reporting, which is the direction to fail in for a report that\n * does not block anything.\n *\n * **Under-reporting is only the safe direction while it is counted.** Silent, it\n * is the failure this whole project refuses, wearing the most convincing\n * disguise available: a subject whose tree diverged reports *fewer* untranslated\n * strings than one that matched, so the locale nobody translated reads as the\n * clean one. So every node the walk did not reach is counted, and every branch\n * it stopped at is named.\n */\nfunction pairByPosition(\n  base: SemanticNode,\n  other: SemanticNode,\n): { readonly pairs: readonly Pair[]; readonly uncompared: Uncompared } {\n  const pairs: Pair[] = [];\n  const divergedAt: NodePath[] = [];\n\n  const walk = (before: SemanticNode, after: SemanticNode, container?: Pair): void => {\n    if (before.tag !== after.tag) {\n      // This node and everything under it, on both sides. Recorded at the node\n      // that stopped the walk rather than at each of its descendants: one\n      // address a reader can open beats a list of addresses in a subtree that\n      // was never examined.\n      divergedAt.push(before.path);\n      return;\n    }\n\n    const pair: Pair = {\n      before,\n      after,\n      ...(container !== undefined && container.before.rect !== undefined &&\n      container.after.rect !== undefined\n        ? { container }\n        : {}),\n    };\n    pairs.push(pair);\n\n    const count = Math.min(before.children.length, after.children.length);\n    // The parent, because the unreached children are the ones the *shorter*\n    // list does not have — on whichever side that is, they have no counterpart\n    // to be addressed by.\n    if (before.children.length !== after.children.length) divergedAt.push(before.path);\n\n    for (let index = 0; index < count; index += 1) {\n      walk(before.children[index]!, after.children[index]!, pair);\n    }\n  };\n\n  walk(base, other);\n\n  // Total minus paired, per side. A pair consumes exactly one node from each, so\n  // the two subtractions are independent and a lopsided divergence says which\n  // render carried the extra material.\n  return {\n    pairs,\n    uncompared: {\n      base: countNodes(base) - pairs.length,\n      other: countNodes(other) - pairs.length,\n      divergedAt,\n    },\n  };\n}\n\nfunction countNodes(node: SemanticNode): number {\n  let total = 1;\n  for (const child of node.children) total += countNodes(child);\n  return total;\n}\n"]}

package/dist/judge/scope.d.ts

@@ -0,0 +1,41 @@
+import type { NodePath } from '../format/snapshot.js';
+/**
+ * Who a declaration applies to, and when it has stopped.
+ *
+ * Four predicates and no policy. They are together because they are the whole of
+ * *scope* — a rule reaches a subject, a subtree, and a date — and apart from
+ * `ignore.ts` because more than one thing asks: an ignore, a sensitivity, and
+ * whatever declares itself next. A second implementation of "does this glob
+ * match" is how two config keys come to mean subtly different things while
+ * looking identical in the documentation.
+ */
+/** The scope fields every declaration shares. */
+export interface Scoped {
+    readonly subjects?: readonly string[];
+    readonly until?: string;
+}
+/**
+ * Whether a rule is past its date, comparing *days* rather than instants.
+ *
+ * `until` names a day and a caller's clock is usually a timestamp, so comparing
+ * them directly expires a rule at one millisecond past midnight **on** the day it
+ * names — a full day early. The date a run happened is its own first ten
+ * characters, which is UTC: the same calendar `until` is written in when nobody
+ * says otherwise, and a choice worth stating, since a team near a boundary sees a
+ * rule expire on the UTC day rather than on theirs.
+ *
+ * `until` is the last day it holds, not the first day it does not.
+ */
+export declare function isExpired(rule: Scoped, now: string | undefined): boolean;
+/**
+ * Path containment on the child-index address, boundary-aware.
+ *
+ * `0/1` contains `0/1/2` and does not contain `0/10`, which a bare `startsWith`
+ * gets wrong — and gets wrong silently, in the direction of ignoring more than
+ * was asked for.
+ */
+export declare function isUnder(path: NodePath, ancestor: NodePath): boolean;
+export declare function appliesToSubject(rule: Scoped, subjectId: string): boolean;
+/** `*` matches any run of characters, including none. Nothing else is special. */
+export declare function matchesGlob(value: string, pattern: string): boolean;
+//# sourceMappingURL=scope.d.ts.map

package/dist/judge/scope.js

@@ -0,0 +1,47 @@
+/**
+ * Whether a rule is past its date, comparing *days* rather than instants.
+ *
+ * `until` names a day and a caller's clock is usually a timestamp, so comparing
+ * them directly expires a rule at one millisecond past midnight **on** the day it
+ * names — a full day early. The date a run happened is its own first ten
+ * characters, which is UTC: the same calendar `until` is written in when nobody
+ * says otherwise, and a choice worth stating, since a team near a boundary sees a
+ * rule expire on the UTC day rather than on theirs.
+ *
+ * `until` is the last day it holds, not the first day it does not.
+ */
+export function isExpired(rule, now) {
+    if (rule.until === undefined || now === undefined)
+        return false;
+    if (Number.isNaN(Date.parse(rule.until)) || Number.isNaN(Date.parse(now)))
+        return false;
+    return now.slice(0, 10) > rule.until.slice(0, 10);
+}
+/**
+ * Path containment on the child-index address, boundary-aware.
+ *
+ * `0/1` contains `0/1/2` and does not contain `0/10`, which a bare `startsWith`
+ * gets wrong — and gets wrong silently, in the direction of ignoring more than
+ * was asked for.
+ */
+export function isUnder(path, ancestor) {
+    if (path === ancestor)
+        return true;
+    return path.startsWith(`${ancestor}/`);
+}
+export function appliesToSubject(rule, subjectId) {
+    if (rule.subjects === undefined)
+        return true;
+    return rule.subjects.some((pattern) => matchesGlob(subjectId, pattern));
+}
+/** `*` matches any run of characters, including none. Nothing else is special. */
+export function matchesGlob(value, pattern) {
+    if (!pattern.includes('*'))
+        return value === pattern;
+    const escaped = pattern
+        .split('*')
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        .join('.*');
+    return new RegExp(`^${escaped}$`).test(value);
+}
+//# sourceMappingURL=scope.js.map

package/dist/judge/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/judge/scope.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,GAAuB;IAC7D,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAChE,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACxF,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,IAAc,EAAE,QAAkB;IACxD,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,SAAiB;IAC9D,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,OAAe;IACxD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,KAAK,OAAO,CAAC;IAErD,MAAM,OAAO,GAAG,OAAO;SACpB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;SAC1D,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,OAAO,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC","sourcesContent":["import type { NodePath } from '../format/snapshot.js';\n\n/**\n * Who a declaration applies to, and when it has stopped.\n *\n * Four predicates and no policy. They are together because they are the whole of\n * *scope* — a rule reaches a subject, a subtree, and a date — and apart from\n * `ignore.ts` because more than one thing asks: an ignore, a sensitivity, and\n * whatever declares itself next. A second implementation of \"does this glob\n * match\" is how two config keys come to mean subtly different things while\n * looking identical in the documentation.\n */\n\n/** The scope fields every declaration shares. */\nexport interface Scoped {\n  readonly subjects?: readonly string[];\n  readonly until?: string;\n}\n\n/**\n * Whether a rule is past its date, comparing *days* rather than instants.\n *\n * `until` names a day and a caller's clock is usually a timestamp, so comparing\n * them directly expires a rule at one millisecond past midnight **on** the day it\n * names — a full day early. The date a run happened is its own first ten\n * characters, which is UTC: the same calendar `until` is written in when nobody\n * says otherwise, and a choice worth stating, since a team near a boundary sees a\n * rule expire on the UTC day rather than on theirs.\n *\n * `until` is the last day it holds, not the first day it does not.\n */\nexport function isExpired(rule: Scoped, now: string | undefined): boolean {\n  if (rule.until === undefined || now === undefined) return false;\n  if (Number.isNaN(Date.parse(rule.until)) || Number.isNaN(Date.parse(now))) return false;\n  return now.slice(0, 10) > rule.until.slice(0, 10);\n}\n\n/**\n * Path containment on the child-index address, boundary-aware.\n *\n * `0/1` contains `0/1/2` and does not contain `0/10`, which a bare `startsWith`\n * gets wrong — and gets wrong silently, in the direction of ignoring more than\n * was asked for.\n */\nexport function isUnder(path: NodePath, ancestor: NodePath): boolean {\n  if (path === ancestor) return true;\n  return path.startsWith(`${ancestor}/`);\n}\n\nexport function appliesToSubject(rule: Scoped, subjectId: string): boolean {\n  if (rule.subjects === undefined) return true;\n  return rule.subjects.some((pattern) => matchesGlob(subjectId, pattern));\n}\n\n/** `*` matches any run of characters, including none. Nothing else is special. */\nexport function matchesGlob(value: string, pattern: string): boolean {\n  if (!pattern.includes('*')) return value === pattern;\n\n  const escaped = pattern\n    .split('*')\n    .map((part) => part.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&'))\n    .join('.*');\n\n  return new RegExp(`^${escaped}$`).test(value);\n}\n"]}