npm - @variance-authority/core - Versions diffs - 0.2.0 → 0.4.0 - Mend

@variance-authority/core 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (37) hide show

package/CHANGELOG.md +85 -36
package/README.md +255 -128
package/dist/attribute/call-site.d.ts +20 -2
package/dist/attribute/call-site.js +17 -20
package/dist/attribute/call-site.js.map +1 -1
package/dist/attribute/composition.js +67 -11
package/dist/attribute/composition.js.map +1 -1
package/dist/attribute/index.d.ts +2 -0
package/dist/attribute/index.js +1 -0
package/dist/attribute/index.js.map +1 -1
package/dist/attribute/landmark.d.ts +97 -0
package/dist/attribute/landmark.js +144 -0
package/dist/attribute/landmark.js.map +1 -0
package/dist/attribute/lexicon.d.ts +25 -1
package/dist/attribute/lexicon.js +87 -27
package/dist/attribute/lexicon.js.map +1 -1
package/dist/attribute/stack.d.ts +62 -1
package/dist/attribute/stack.js +116 -5
package/dist/attribute/stack.js.map +1 -1
package/dist/judge/inspect.js +57 -4
package/dist/judge/inspect.js.map +1 -1
package/dist/relate/before.d.ts +137 -0
package/dist/relate/before.js +155 -0
package/dist/relate/before.js.map +1 -0
package/dist/relate/graph.d.ts +28 -11
package/dist/relate/graph.js +20 -9
package/dist/relate/graph.js.map +1 -1
package/dist/relate/index.d.ts +2 -1
package/dist/relate/index.js +1 -0
package/dist/relate/index.js.map +1 -1
package/dist/relate/merkle.d.ts +6 -0
package/dist/relate/merkle.js +6 -0
package/dist/relate/merkle.js.map +1 -1
package/dist/relate/records.d.ts +67 -1
package/dist/relate/records.js +34 -7
package/dist/relate/records.js.map +1 -1
package/package.json +1 -1

package/dist/judge/inspect.js CHANGED Viewed

@@ -55,6 +55,14 @@ export function inspect(snapshot) {
     });
     return findings;
     function visit(node, insideControl) {
+        // Nothing below a node the browser never built. A responsive site renders
+        // the mobile navigation into the desktop document and hides it with a
+        // class, and a reader that counts it sees two `navigation` landmarks where
+        // Chrome's tree holds one — a duplicate nobody can reach, reported against
+        // markup that is correct. Every rule here is about what a screen reader
+        // encounters, so the gate belongs at the walk rather than in each rule.
+        if (!exposed(node))
+            return;
         const interactive = node.role !== undefined && INTERACTIVE.has(node.role);
         if (interactive && node.name === undefined) {
             findings.push(finding('control-without-name', node, `<${node.tag}> is a ${node.role} with no accessible name`, snapshot));
@@ -124,6 +132,27 @@ export function inspect(snapshot) {
             visit(child, insideControl || interactive);
     }
 }
+/**
+ * Whether a screen reader reaches this node at all.
+ *
+ * Three ways out of the accessibility tree, and only one of them is declared.
+ * `aria-hidden="true"` and the `hidden` attribute are the author saying so, and
+ * arrive as state. `display: none` is the one nobody says: it is a utility
+ * class, a media query, a `<details>` that is closed at this width. All three
+ * take the subtree with them — `aria-hidden` is not reversible by a descendant,
+ * and neither is a box that was never generated.
+ *
+ * `display` is read from the node's own computed style, which the capture
+ * already carries: it is in the style allowlist, so this costs no new field and
+ * moves no hash. Absent — a structural-only profile, where no style was
+ * computed — the answer is "exposed", because refusing to report on a document
+ * whose visibility could not be observed would silently empty the inspection.
+ */
+function exposed(node) {
+    if (node.state?.['hidden'] === true)
+        return false;
+    return node.style['display'] !== 'none';
+}
 function hasHeaders(node) {
     if (node.role === 'columnheader' || node.role === 'rowheader')
         return true;
@@ -137,11 +166,35 @@ function hasHeaders(node) {
  * has nothing to compare.
  */
 function visibleTextOf(node) {
-    if (node.state?.['hidden'] === true)
+    return runsOf(node).replace(/\s+/g, ' ').trim();
+}
+/**
+ * The same separator rule accname uses, so the two readings can be compared.
+ *
+ * `label-mismatch` asks whether the accessible name contains the visible words,
+ * and that question is only meaningful if both sides were assembled the same
+ * way. Joining every child with a space while `accessibleName` concatenated
+ * them produced the failure this rule exists to prevent, in the rule itself: a
+ * flex button reading "Search ⌘K" and named "Search⌘K" was reported as
+ * unreachable by voice, against markup a browser names correctly.
+ *
+ * So a child contributes separated only when its computed `display` is not
+ * inline — which is what a browser does, and which makes `<b>` inside a
+ * sentence contribute as part of the word it is inside.
+ */
+function runsOf(node) {
+    if (!exposed(node))
         return '';
-    const own = node.text ?? '';
-    const children = node.children.map(visibleTextOf).join(' ');
-    return `${own} ${children}`.replace(/\s+/g, ' ').trim();
+    let text = node.text ?? '';
+    for (const child of node.children) {
+        const contribution = runsOf(child);
+        if (contribution.length === 0)
+            continue;
+        const display = child.style['display'];
+        const separated = display !== undefined && display !== 'inline' && display !== 'contents';
+        text += separated ? ` ${contribution} ` : contribution;
+    }
+    return text;
 }
 function levelOf(node) {
     // `aria-level` wins, because it is what an assistive technology reads. The tag

package/dist/judge/inspect.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../src/judge/inspect.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Band } from '../compare/band.js';\nimport type { OwnerFrame, SourceLocation } from '../format/provenance.js';\nimport type { NodePath, SemanticNode, SemanticSnapshot } from '../format/snapshot.js';\nimport { locate } from '../attribute/locate.js';\nimport { formatSource, resolveSource, type SourceIndex } from '../attribute/source.js';\n\n/*\n What a render says without a baseline.\n \n Two producers, one `Finding` type. `inspect` reads a single snapshot;\n * `compareLocales` reads two renders of one subject in different languages,\n * which is also not a regression comparison — both renders are correct. Sharing\n * the type is what lets the report, the CLI and the MCP tools carry both without\n * knowing which produced what.\n \n The rest of this comment is about `inspect`, which reads one snapshot with no\n * baseline and no second run.\n \n Everything else in this package answers what changed, which requires two of\n * something. That framing has a blind spot the whole category shares: *a defect\n that was present on the first run is invisible to a comparison forever.** A\n * button that never had an accessible name compares equal to itself on every run\n * until someone happens to edit it, and a picture of it is a perfectly good\n * picture. Approving the first baseline approves the defect.\n \n These rules read the normalized snapshot and report defects in it. Consequences\n * worth stating, because they are the practical argument for having the document\n * rather than an image of it:\n \n - A fresh checkout with zero baselines is already useful. The expensive\n * part of adopting a visual-regression tool is that it says nothing until it\n * has a history; this half says something on the first run.\n * - Every finding names a component and a file, through the same provenance\n * chain a delta uses. A rule engine that reports a DOM path reports where the\n * symptom is; this reports whose JSX wrote it.\n * - They band as `a11y`, so a project that writes `blocking: ['a11y']` gets\n * both halves under one policy: regressions found by comparison, and defects\n * found by inspection.\n \n Deliberately not an axe-core reimplementation. Axe runs against a live DOM\n * with computed visibility, contrast and focus order, and does dozens of things\n * this cannot. What is here is the subset a normalized snapshot can decide\n * without guessing — and the subset it can decide *offline, from a stored\n artifact, months later*, which is a thing axe cannot do at all.\n \n * There is no severity field. A rule that needs one to be tolerable is a rule\n * whose condition is too broad, and the fix is a better condition or no rule.\n \n Why there is no contrast rule, stated here so nobody adds one badly later.\n * The snapshot carries a resolved `color` and `background-color` per node, so a\n * check looks like four lines and would be wrong: the background a glyph is\n * actually painted on is whatever is behind it, which is a stacking question a\n * layout engine answers and a document does not. A node with a transparent\n * background over a dark ancestor, an image, a gradient, or a positioned sibling\n * all read as \"background-color: rgba(0,0,0,0)\" here. A rule that is right most\n * of the time about accessibility is worse than no rule: it gets disabled after\n * the second false alarm, and takes the four that work with it. Spec 0009\n * records the same for focus order and anything about motion.\n /\n\nexport type FindingRule =\n /* An interactive control with no accessible name. Nothing announces it. /\n \| 'control-without-name'\n /* A meaningful image with neither a name nor an explicit `alt=\"\"`. /\n \| 'image-without-alt'\n /* Heading levels jump forward by more than one. /\n \| 'heading-level-skipped'\n /* A control inside another control. Only one of them is reachable. /\n \| 'nested-interactive'\n /* An id reference that resolves to nothing inside this subject. /\n \| 'dangling-reference'\n /* A control whose accessible name does not contain its visible label. /\n \| 'label-mismatch'\n /* Two landmarks of one role that nothing tells apart. /\n \| 'duplicate-landmark'\n /* A table with no header cells. /\n \| 'table-without-headers'\n /* `tabindex` above zero, which reorders focus for the whole page. /\n \| 'positive-tabindex'\n /\n The same string in two locales. From `compareLocales`, not from `inspect` —\n * one render cannot know whether its text was translated.\n /\n \| 'untranslated'\n /* A box outside the box that contains it, in one locale and not the other. /\n \| 'overflows-container';\n\n/\n The identity of a finding, as a string two runs can be compared on.\n \n A finding is the same finding when the same rule fires on the same node. Not\n * the same sentence: `what` quotes the text it found, so a copy edit beside a\n * control with no accessible name would read as the old defect going away and a\n * new one arriving in the same place. And not the same component either — a\n * component renders in many places, and every one of them would collapse to one.\n \n Small on purpose. This is what a baseline carries so that the next run can say\n * whether a defect it found was already there, and a baseline sidecar rides\n * beside a PNG in a tracked directory: a mark is a few dozen bytes and a stored\n * `Finding` is a paragraph. It can only answer membership, which is the only\n * question the next run is allowed to ask of it — the same restraint\n * `Described.components` is written under.\n /\nexport function findingMark(finding: { readonly rule: string; readonly path: string }): string {\n return `${finding.rule}@${finding.path}`;\n}\n\nexport interface Finding {\n readonly rule: FindingRule;\n\n /\n The band this finding would block under.\n \n Carried so that inspection and comparison answer to one policy. A team that\n * blocks `a11y` should not have to discover that it blocks regressions and not\n * defects.\n /\n readonly band: Band;\n\n readonly path: NodePath;\n\n /* One sentence, naming the thing rather than the rule. /\n readonly what: string;\n\n /* Spoken outside-in, from `locate` — `main → region \"Todos\" → item 2 of 3`. /\n readonly where?: string;\n\n /* The component whose JSX created the node, when provenance reached it. /\n readonly component?: string;\n readonly owners?: readonly OwnerFrame[];\n\n /\n The line that wrote this element, when a JSX runtime recorded one.\n \n Different from — and better than — resolving `component` through the source\n * index, which answers with where the component is declared. A defect is\n * rarely at a declaration: a button with no accessible name is a specific\n * element on a specific line inside that component, and that line is the edit.\n * The index stays as the fallback, because it needs no build change.\n \n Requires `@variance-authority/jsx-source` in the transform. Absent otherwise,\n * and absence is normal.\n /\n readonly source?: SourceLocation;\n}\n\n/* Roles that are operated. A control nobody can name is a control nobody can use. /\nconst INTERACTIVE = new Set([\n 'button', 'link', 'checkbox', 'radio', 'switch', 'textbox', 'searchbox',\n 'combobox', 'slider', 'spinbutton', 'menuitem', 'menuitemcheckbox',\n 'menuitemradio', 'tab', 'treeitem',\n]);\n\n/* Attributes whose value the aliaser rewrote, so `#extern:` means unresolved. /\nconst REFERENCE_ATTRIBUTES = new Set(['for', 'form', 'list', 'headers']);\n\nconst HEADING_TAGS: Readonly<Record<string, number>> = {\n h1: 1, h2: 2, h3: 3, h4: 4, h5: 5, h6: 6,\n};\n\n/* Regions of a page a screen reader user navigates between. /\nconst LANDMARKS = new Set([\n 'banner', 'navigation', 'main', 'complementary', 'contentinfo',\n 'region', 'form', 'search',\n]);\n\n/* Has at least one letter. A glyph is not a visible label. /\nconst HAS_LETTER = /\\p{L}/u;\n\nexport function inspect(snapshot: SemanticSnapshot): readonly Finding[] {\n const findings: Finding[] = [];\n const headings: { node: SemanticNode; level: number }[] = [];\n const landmarks = new Map<string, SemanticNode>();\n\n visit(snapshot.root, false);\n\n // Heading order is a property of the sequence, not of any one node, so it is\n // decided after the walk. Only forward* jumps are reported: a component that\n // starts at `h3` is a component rendered inside something, not a defect, and a\n // subject is not a page.\n headings.forEach((heading, index) => {\n const previous = headings[index - 1];\n if (previous === undefined \|\| heading.level <= previous.level + 1) return;\n\n findings.push(\n finding(\n 'heading-level-skipped',\n heading.node,\n `heading level jumps from ${previous.level} to ${heading.level}` +\n (heading.node.name !== undefined ? ` at \"${heading.node.name}\"` : ''),\n snapshot,\n ),\n );\n });\n\n return findings;\n\n function visit(node: SemanticNode, insideControl: boolean): void {\n const interactive = node.role !== undefined && INTERACTIVE.has(node.role);\n\n if (interactive && node.name === undefined) {\n findings.push(\n finding(\n 'control-without-name',\n node,\n `<${node.tag}> is a ${node.role} with no accessible name`,\n snapshot,\n ),\n );\n }\n\n if (interactive && insideControl) {\n findings.push(\n finding(\n 'nested-interactive',\n node,\n `a ${node.role} is nested inside another control; only one of the two is reachable`,\n snapshot,\n ),\n );\n }\n\n // `alt=\"\"` is the author saying \"decorative\", which is a correct answer and\n // must not be reported. A missing `alt` is the author saying nothing.\n if (node.role === 'img' && node.name === undefined && node.attributes['alt'] === undefined) {\n findings.push(\n finding(\n 'image-without-alt',\n node,\n `<${node.tag}> has an image role, no accessible name, and no alt=\"\" to say it is decorative`,\n snapshot,\n ),\n );\n }\n\n for (const [attribute, value] of Object.entries(node.attributes)) {\n if (!REFERENCE_ATTRIBUTES.has(attribute) \|\| !value.includes('#extern:')) continue;\n\n findings.push(\n finding(\n 'dangling-reference',\n node,\n // Honest about the ambiguity the aliaser records: from inside the\n // subject, escaping the subtree and pointing at nothing look the same.\n `<${node.tag} ${attribute}> references an element that is not in this subject`,\n snapshot,\n ),\n );\n }\n\n if (node.role === 'heading') {\n const level = levelOf(node);\n if (level !== undefined) headings.push({ node, level });\n }\n\n if (node.role !== undefined && LANDMARKS.has(node.role)) {\n // Keyed by role and name: two `navigation` landmarks called \"Primary\"\n // and \"Footer\" are how a page is meant to be built. Two called nothing are\n // two identical entries in the landmark list.\n const key = `${node.role}\\u0000${node.name ?? ''}`;\n const first = landmarks.get(key);\n\n if (first === undefined) {\n landmarks.set(key, node);\n } else {\n findings.push(\n finding(\n 'duplicate-landmark',\n node,\n `a second ${node.role} landmark` +\n (node.name !== undefined ? ` also named \"${node.name}\"` : ' with no name') +\n ', so nothing tells the two apart in a landmark list',\n snapshot,\n ),\n );\n }\n }\n\n if (node.role === 'table' && !hasHeaders(node)) {\n findings.push(\n finding(\n 'table-without-headers',\n node,\n `<${node.tag}> is a table with no header cells, so every cell is announced without ` +\n 'the column it belongs to',\n snapshot,\n ),\n );\n }\n\n const tabindex = Number(node.attributes['tabindex']);\n if (Number.isInteger(tabindex) && tabindex > 0) {\n findings.push(\n finding(\n 'positive-tabindex',\n node,\n `<${node.tag}> has tabindex=${tabindex}, which pulls it ahead of every element in ` +\n 'the document that relies on source order',\n snapshot,\n ),\n );\n }\n\n // WCAG 2.5.3. A control whose accessible name does not contain its visible\n // label cannot be operated by voice: \"click Save\" does nothing when the\n // button reads Save and is named \"Submit form\".\n //\n // Only when the visible text carries a letter. An icon button labelled\n // `aria-label=\"Refresh\"` around a glyph is correct, and a rule that reported\n // it would fire on every icon in every design system.\n if (interactive && node.name !== undefined) {\n const visible = visibleTextOf(node);\n if (\n visible.length > 0 &&\n HAS_LETTER.test(visible) &&\n !node.name.toLowerCase().includes(visible.toLowerCase())\n ) {\n findings.push(\n finding(\n 'label-mismatch',\n node,\n `reads \"${visible}\" and is named \"${node.name}\", so a voice command using the ` +\n 'visible words does not reach it',\n snapshot,\n ),\n );\n }\n }\n\n for (const child of node.children) visit(child, insideControl \|\| interactive);\n }\n}\n\nfunction hasHeaders(node: SemanticNode): boolean {\n if (node.role === 'columnheader' \|\| node.role === 'rowheader') return true;\n return node.children.some(hasHeaders);\n}\n\n/*\n Text a sighted user reads, normalized to single spaces.\n \n `aria-hidden` subtrees are excluded, which is what makes the icon-button case\n * work: the glyph is hidden, so the visible text is empty and `label-mismatch`\n * has nothing to compare.\n /\nfunction visibleTextOf(node: SemanticNode): string {\n if (node.state?.['hidden'] === true) return '';\n\n const own = node.text ?? '';\n const children = node.children.map(visibleTextOf).join(' ');\n\n return `${own} ${children}`.replace(/\\s+/g, ' ').trim();\n}\n\nfunction levelOf(node: SemanticNode): number \| undefined {\n // `aria-level` wins, because it is what an assistive technology reads. The tag\n // is the fallback, and a `role=\"heading\"` with neither is not a level at all.\n const declared = node.state?.['level'];\n if (typeof declared === 'number') return declared;\n if (typeof declared === 'string' && /^\\d+$/.test(declared)) return Number(declared);\n\n return HEADING_TAGS[node.tag];\n}\n\nfunction finding(\n rule: FindingRule,\n node: SemanticNode,\n what: string,\n snapshot: SemanticSnapshot,\n): Finding {\n const where = locate(snapshot.root, node.path).where;\n const component = node.provenance?.createdBy ?? node.provenance?.owners[0]?.name;\n\n return {\n rule,\n band: 'a11y',\n path: node.path,\n what,\n ...(where !== '' ? { where } : {}),\n ...(component !== undefined ? { component } : {}),\n ...(node.provenance ? { owners: node.provenance.owners } : {}),\n ...(node.provenance?.source ? { source: node.provenance.source } : {}),\n };\n}\n\nexport interface InspectionReportOptions {\n /* Component → file, so a finding names an edit rather than an identifier. /\n readonly source?: SourceIndex;\n}\n\n/\n Findings as the thing a reviewer or an agent reads.\n \n Same shape as `summarizeAdjudication`: what, where, which file. A finding a\n * reader has to go and locate is a finding that gets skipped.\n */\nexport function summarizeFindings(\n findings: readonly Finding[],\n options: InspectionReportOptions = {},\n): string {\n if (findings.length === 0) return 'no findings.';\n\n const byRule = new Map<FindingRule, number>();\n for (const found of findings) byRule.set(found.rule, (byRule.get(found.rule) ?? 0) + 1);\n\n const header =\n `${findings.length} finding${findings.length === 1 ? '' : 's'}: ` +\n [...byRule].map(([rule, count]) => `${count} ${rule}`).join(', ');\n\n const lines = findings.flatMap((found) => {\n // The element's own line wins over the component's declaration. Both are\n // `file:line`, so the reader cannot tell them apart and does not need to —\n // either one opens at something worth editing, and the recorded one opens at\n // the element the finding is actually about.\n const declared =\n found.component !== undefined && options.source\n ? resolveSource(found.component, options.source)\n : null;\n const where =\n found.source !== undefined\n ? `${found.source.file}:${String(found.source.line)}`\n : declared\n ? formatSource(declared)\n : '';\n\n const attribution = [found.component, where === '' ? undefined : where]\n .filter((part): part is string => part !== undefined)\n .join(' ');\n\n return [\n ` [${found.rule}] ${found.what}`,\n found.where !== undefined ? ` in ${found.where}` : null,\n attribution === '' ? null : ` ${attribution}`,\n ].filter((line): line is string => line !== null);\n });\n\n return [header, ...lines].join('\\n');\n}\n"]}
1	+ {"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../src/judge/inspect.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Band } from '../compare/band.js';\nimport type { OwnerFrame, SourceLocation } from '../format/provenance.js';\nimport type { NodePath, SemanticNode, SemanticSnapshot } from '../format/snapshot.js';\nimport { locate } from '../attribute/locate.js';\nimport { formatSource, resolveSource, type SourceIndex } from '../attribute/source.js';\n\n/*\n What a render says without a baseline.\n \n Two producers, one `Finding` type. `inspect` reads a single snapshot;\n * `compareLocales` reads two renders of one subject in different languages,\n * which is also not a regression comparison — both renders are correct. Sharing\n * the type is what lets the report, the CLI and the MCP tools carry both without\n * knowing which produced what.\n \n The rest of this comment is about `inspect`, which reads one snapshot with no\n * baseline and no second run.\n \n Everything else in this package answers what changed, which requires two of\n * something. That framing has a blind spot the whole category shares: *a defect\n that was present on the first run is invisible to a comparison forever.** A\n * button that never had an accessible name compares equal to itself on every run\n * until someone happens to edit it, and a picture of it is a perfectly good\n * picture. Approving the first baseline approves the defect.\n \n These rules read the normalized snapshot and report defects in it. Consequences\n * worth stating, because they are the practical argument for having the document\n * rather than an image of it:\n \n - A fresh checkout with zero baselines is already useful. The expensive\n * part of adopting a visual-regression tool is that it says nothing until it\n * has a history; this half says something on the first run.\n * - Every finding names a component and a file, through the same provenance\n * chain a delta uses. A rule engine that reports a DOM path reports where the\n * symptom is; this reports whose JSX wrote it.\n * - They band as `a11y`, so a project that writes `blocking: ['a11y']` gets\n * both halves under one policy: regressions found by comparison, and defects\n * found by inspection.\n \n Deliberately not an axe-core reimplementation. Axe runs against a live DOM\n * with computed visibility, contrast and focus order, and does dozens of things\n * this cannot. What is here is the subset a normalized snapshot can decide\n * without guessing — and the subset it can decide *offline, from a stored\n artifact, months later*, which is a thing axe cannot do at all.\n \n * There is no severity field. A rule that needs one to be tolerable is a rule\n * whose condition is too broad, and the fix is a better condition or no rule.\n \n Why there is no contrast rule, stated here so nobody adds one badly later.\n * The snapshot carries a resolved `color` and `background-color` per node, so a\n * check looks like four lines and would be wrong: the background a glyph is\n * actually painted on is whatever is behind it, which is a stacking question a\n * layout engine answers and a document does not. A node with a transparent\n * background over a dark ancestor, an image, a gradient, or a positioned sibling\n * all read as \"background-color: rgba(0,0,0,0)\" here. A rule that is right most\n * of the time about accessibility is worse than no rule: it gets disabled after\n * the second false alarm, and takes the four that work with it. Spec 0009\n * records the same for focus order and anything about motion.\n /\n\nexport type FindingRule =\n /* An interactive control with no accessible name. Nothing announces it. /\n \| 'control-without-name'\n /* A meaningful image with neither a name nor an explicit `alt=\"\"`. /\n \| 'image-without-alt'\n /* Heading levels jump forward by more than one. /\n \| 'heading-level-skipped'\n /* A control inside another control. Only one of them is reachable. /\n \| 'nested-interactive'\n /* An id reference that resolves to nothing inside this subject. /\n \| 'dangling-reference'\n /* A control whose accessible name does not contain its visible label. /\n \| 'label-mismatch'\n /* Two landmarks of one role that nothing tells apart. /\n \| 'duplicate-landmark'\n /* A table with no header cells. /\n \| 'table-without-headers'\n /* `tabindex` above zero, which reorders focus for the whole page. /\n \| 'positive-tabindex'\n /\n The same string in two locales. From `compareLocales`, not from `inspect` —\n * one render cannot know whether its text was translated.\n /\n \| 'untranslated'\n /* A box outside the box that contains it, in one locale and not the other. /\n \| 'overflows-container';\n\n/\n The identity of a finding, as a string two runs can be compared on.\n \n A finding is the same finding when the same rule fires on the same node. Not\n * the same sentence: `what` quotes the text it found, so a copy edit beside a\n * control with no accessible name would read as the old defect going away and a\n * new one arriving in the same place. And not the same component either — a\n * component renders in many places, and every one of them would collapse to one.\n \n Small on purpose. This is what a baseline carries so that the next run can say\n * whether a defect it found was already there, and a baseline sidecar rides\n * beside a PNG in a tracked directory: a mark is a few dozen bytes and a stored\n * `Finding` is a paragraph. It can only answer membership, which is the only\n * question the next run is allowed to ask of it — the same restraint\n * `Described.components` is written under.\n /\nexport function findingMark(finding: { readonly rule: string; readonly path: string }): string {\n return `${finding.rule}@${finding.path}`;\n}\n\nexport interface Finding {\n readonly rule: FindingRule;\n\n /\n The band this finding would block under.\n \n Carried so that inspection and comparison answer to one policy. A team that\n * blocks `a11y` should not have to discover that it blocks regressions and not\n * defects.\n /\n readonly band: Band;\n\n readonly path: NodePath;\n\n /* One sentence, naming the thing rather than the rule. /\n readonly what: string;\n\n /* Spoken outside-in, from `locate` — `main → region \"Todos\" → item 2 of 3`. /\n readonly where?: string;\n\n /* The component whose JSX created the node, when provenance reached it. /\n readonly component?: string;\n readonly owners?: readonly OwnerFrame[];\n\n /\n The line that wrote this element, when a JSX runtime recorded one.\n \n Different from — and better than — resolving `component` through the source\n * index, which answers with where the component is declared. A defect is\n * rarely at a declaration: a button with no accessible name is a specific\n * element on a specific line inside that component, and that line is the edit.\n * The index stays as the fallback, because it needs no build change.\n \n Requires `@variance-authority/jsx-source` in the transform. Absent otherwise,\n * and absence is normal.\n /\n readonly source?: SourceLocation;\n}\n\n/* Roles that are operated. A control nobody can name is a control nobody can use. /\nconst INTERACTIVE = new Set([\n 'button', 'link', 'checkbox', 'radio', 'switch', 'textbox', 'searchbox',\n 'combobox', 'slider', 'spinbutton', 'menuitem', 'menuitemcheckbox',\n 'menuitemradio', 'tab', 'treeitem',\n]);\n\n/* Attributes whose value the aliaser rewrote, so `#extern:` means unresolved. /\nconst REFERENCE_ATTRIBUTES = new Set(['for', 'form', 'list', 'headers']);\n\nconst HEADING_TAGS: Readonly<Record<string, number>> = {\n h1: 1, h2: 2, h3: 3, h4: 4, h5: 5, h6: 6,\n};\n\n/* Regions of a page a screen reader user navigates between. /\nconst LANDMARKS = new Set([\n 'banner', 'navigation', 'main', 'complementary', 'contentinfo',\n 'region', 'form', 'search',\n]);\n\n/* Has at least one letter. A glyph is not a visible label. /\nconst HAS_LETTER = /\\p{L}/u;\n\nexport function inspect(snapshot: SemanticSnapshot): readonly Finding[] {\n const findings: Finding[] = [];\n const headings: { node: SemanticNode; level: number }[] = [];\n const landmarks = new Map<string, SemanticNode>();\n\n visit(snapshot.root, false);\n\n // Heading order is a property of the sequence, not of any one node, so it is\n // decided after the walk. Only forward* jumps are reported: a component that\n // starts at `h3` is a component rendered inside something, not a defect, and a\n // subject is not a page.\n headings.forEach((heading, index) => {\n const previous = headings[index - 1];\n if (previous === undefined \|\| heading.level <= previous.level + 1) return;\n\n findings.push(\n finding(\n 'heading-level-skipped',\n heading.node,\n `heading level jumps from ${previous.level} to ${heading.level}` +\n (heading.node.name !== undefined ? ` at \"${heading.node.name}\"` : ''),\n snapshot,\n ),\n );\n });\n\n return findings;\n\n function visit(node: SemanticNode, insideControl: boolean): void {\n // Nothing below a node the browser never built. A responsive site renders\n // the mobile navigation into the desktop document and hides it with a\n // class, and a reader that counts it sees two `navigation` landmarks where\n // Chrome's tree holds one — a duplicate nobody can reach, reported against\n // markup that is correct. Every rule here is about what a screen reader\n // encounters, so the gate belongs at the walk rather than in each rule.\n if (!exposed(node)) return;\n\n const interactive = node.role !== undefined && INTERACTIVE.has(node.role);\n\n if (interactive && node.name === undefined) {\n findings.push(\n finding(\n 'control-without-name',\n node,\n `<${node.tag}> is a ${node.role} with no accessible name`,\n snapshot,\n ),\n );\n }\n\n if (interactive && insideControl) {\n findings.push(\n finding(\n 'nested-interactive',\n node,\n `a ${node.role} is nested inside another control; only one of the two is reachable`,\n snapshot,\n ),\n );\n }\n\n // `alt=\"\"` is the author saying \"decorative\", which is a correct answer and\n // must not be reported. A missing `alt` is the author saying nothing.\n if (node.role === 'img' && node.name === undefined && node.attributes['alt'] === undefined) {\n findings.push(\n finding(\n 'image-without-alt',\n node,\n `<${node.tag}> has an image role, no accessible name, and no alt=\"\" to say it is decorative`,\n snapshot,\n ),\n );\n }\n\n for (const [attribute, value] of Object.entries(node.attributes)) {\n if (!REFERENCE_ATTRIBUTES.has(attribute) \|\| !value.includes('#extern:')) continue;\n\n findings.push(\n finding(\n 'dangling-reference',\n node,\n // Honest about the ambiguity the aliaser records: from inside the\n // subject, escaping the subtree and pointing at nothing look the same.\n `<${node.tag} ${attribute}> references an element that is not in this subject`,\n snapshot,\n ),\n );\n }\n\n if (node.role === 'heading') {\n const level = levelOf(node);\n if (level !== undefined) headings.push({ node, level });\n }\n\n if (node.role !== undefined && LANDMARKS.has(node.role)) {\n // Keyed by role and name: two `navigation` landmarks called \"Primary\"\n // and \"Footer\" are how a page is meant to be built. Two called nothing are\n // two identical entries in the landmark list.\n const key = `${node.role}\\u0000${node.name ?? ''}`;\n const first = landmarks.get(key);\n\n if (first === undefined) {\n landmarks.set(key, node);\n } else {\n findings.push(\n finding(\n 'duplicate-landmark',\n node,\n `a second ${node.role} landmark` +\n (node.name !== undefined ? ` also named \"${node.name}\"` : ' with no name') +\n ', so nothing tells the two apart in a landmark list',\n snapshot,\n ),\n );\n }\n }\n\n if (node.role === 'table' && !hasHeaders(node)) {\n findings.push(\n finding(\n 'table-without-headers',\n node,\n `<${node.tag}> is a table with no header cells, so every cell is announced without ` +\n 'the column it belongs to',\n snapshot,\n ),\n );\n }\n\n const tabindex = Number(node.attributes['tabindex']);\n if (Number.isInteger(tabindex) && tabindex > 0) {\n findings.push(\n finding(\n 'positive-tabindex',\n node,\n `<${node.tag}> has tabindex=${tabindex}, which pulls it ahead of every element in ` +\n 'the document that relies on source order',\n snapshot,\n ),\n );\n }\n\n // WCAG 2.5.3. A control whose accessible name does not contain its visible\n // label cannot be operated by voice: \"click Save\" does nothing when the\n // button reads Save and is named \"Submit form\".\n //\n // Only when the visible text carries a letter. An icon button labelled\n // `aria-label=\"Refresh\"` around a glyph is correct, and a rule that reported\n // it would fire on every icon in every design system.\n if (interactive && node.name !== undefined) {\n const visible = visibleTextOf(node);\n if (\n visible.length > 0 &&\n HAS_LETTER.test(visible) &&\n !node.name.toLowerCase().includes(visible.toLowerCase())\n ) {\n findings.push(\n finding(\n 'label-mismatch',\n node,\n `reads \"${visible}\" and is named \"${node.name}\", so a voice command using the ` +\n 'visible words does not reach it',\n snapshot,\n ),\n );\n }\n }\n\n for (const child of node.children) visit(child, insideControl \|\| interactive);\n }\n}\n\n/*\n Whether a screen reader reaches this node at all.\n \n Three ways out of the accessibility tree, and only one of them is declared.\n * `aria-hidden=\"true\"` and the `hidden` attribute are the author saying so, and\n * arrive as state. `display: none` is the one nobody says: it is a utility\n * class, a media query, a `<details>` that is closed at this width. All three\n * take the subtree with them — `aria-hidden` is not reversible by a descendant,\n * and neither is a box that was never generated.\n \n `display` is read from the node's own computed style, which the capture\n * already carries: it is in the style allowlist, so this costs no new field and\n * moves no hash. Absent — a structural-only profile, where no style was\n * computed — the answer is \"exposed\", because refusing to report on a document\n * whose visibility could not be observed would silently empty the inspection.\n /\nfunction exposed(node: SemanticNode): boolean {\n if (node.state?.['hidden'] === true) return false;\n return node.style['display'] !== 'none';\n}\n\nfunction hasHeaders(node: SemanticNode): boolean {\n if (node.role === 'columnheader' \|\| node.role === 'rowheader') return true;\n return node.children.some(hasHeaders);\n}\n\n/\n Text a sighted user reads, normalized to single spaces.\n \n `aria-hidden` subtrees are excluded, which is what makes the icon-button case\n * work: the glyph is hidden, so the visible text is empty and `label-mismatch`\n * has nothing to compare.\n /\nfunction visibleTextOf(node: SemanticNode): string {\n return runsOf(node).replace(/\\s+/g, ' ').trim();\n}\n\n/\n The same separator rule accname uses, so the two readings can be compared.\n \n `label-mismatch` asks whether the accessible name contains the visible words,\n * and that question is only meaningful if both sides were assembled the same\n * way. Joining every child with a space while `accessibleName` concatenated\n * them produced the failure this rule exists to prevent, in the rule itself: a\n * flex button reading \"Search ⌘K\" and named \"Search⌘K\" was reported as\n * unreachable by voice, against markup a browser names correctly.\n \n So a child contributes separated only when its computed `display` is not\n * inline — which is what a browser does, and which makes `<b>` inside a\n * sentence contribute as part of the word it is inside.\n /\nfunction runsOf(node: SemanticNode): string {\n if (!exposed(node)) return '';\n\n let text = node.text ?? '';\n\n for (const child of node.children) {\n const contribution = runsOf(child);\n if (contribution.length === 0) continue;\n\n const display = child.style['display'];\n const separated = display !== undefined && display !== 'inline' && display !== 'contents';\n text += separated ? ` ${contribution} ` : contribution;\n }\n\n return text;\n}\n\nfunction levelOf(node: SemanticNode): number \| undefined {\n // `aria-level` wins, because it is what an assistive technology reads. The tag\n // is the fallback, and a `role=\"heading\"` with neither is not a level at all.\n const declared = node.state?.['level'];\n if (typeof declared === 'number') return declared;\n if (typeof declared === 'string' && /^\\d+$/.test(declared)) return Number(declared);\n\n return HEADING_TAGS[node.tag];\n}\n\nfunction finding(\n rule: FindingRule,\n node: SemanticNode,\n what: string,\n snapshot: SemanticSnapshot,\n): Finding {\n const where = locate(snapshot.root, node.path).where;\n const component = node.provenance?.createdBy ?? node.provenance?.owners[0]?.name;\n\n return {\n rule,\n band: 'a11y',\n path: node.path,\n what,\n ...(where !== '' ? { where } : {}),\n ...(component !== undefined ? { component } : {}),\n ...(node.provenance ? { owners: node.provenance.owners } : {}),\n ...(node.provenance?.source ? { source: node.provenance.source } : {}),\n };\n}\n\nexport interface InspectionReportOptions {\n /* Component → file, so a finding names an edit rather than an identifier. /\n readonly source?: SourceIndex;\n}\n\n/\n Findings as the thing a reviewer or an agent reads.\n \n Same shape as `summarizeAdjudication`: what, where, which file. A finding a\n * reader has to go and locate is a finding that gets skipped.\n */\nexport function summarizeFindings(\n findings: readonly Finding[],\n options: InspectionReportOptions = {},\n): string {\n if (findings.length === 0) return 'no findings.';\n\n const byRule = new Map<FindingRule, number>();\n for (const found of findings) byRule.set(found.rule, (byRule.get(found.rule) ?? 0) + 1);\n\n const header =\n `${findings.length} finding${findings.length === 1 ? '' : 's'}: ` +\n [...byRule].map(([rule, count]) => `${count} ${rule}`).join(', ');\n\n const lines = findings.flatMap((found) => {\n // The element's own line wins over the component's declaration. Both are\n // `file:line`, so the reader cannot tell them apart and does not need to —\n // either one opens at something worth editing, and the recorded one opens at\n // the element the finding is actually about.\n const declared =\n found.component !== undefined && options.source\n ? resolveSource(found.component, options.source)\n : null;\n const where =\n found.source !== undefined\n ? `${found.source.file}:${String(found.source.line)}`\n : declared\n ? formatSource(declared)\n : '';\n\n const attribution = [found.component, where === '' ? undefined : where]\n .filter((part): part is string => part !== undefined)\n .join(' ');\n\n return [\n ` [${found.rule}] ${found.what}`,\n found.where !== undefined ? ` in ${found.where}` : null,\n attribution === '' ? null : ` ${attribution}`,\n ].filter((line): line is string => line !== null);\n });\n\n return [header, ...lines].join('\\n');\n}\n"]}

package/dist/relate/before.d.ts ADDED Viewed

@@ -0,0 +1,137 @@
+/**
+ * What a run rests on that nothing in it imports.
+ *
+ * Selection walks one line. It starts at the test harness, moves right through
+ * the tests into the repository's own files, and goes out past them into the
+ * dependencies ([`records.ts`](./records.ts) holds all three as nodes). Every
+ * question it asks is asked *against* the arrows: what depends on the thing
+ * that moved.
+ *
+ * The far-left end of that line answers no such question. A `vitest.config.ts`,
+ * a `jest.config.js`, a Next.js setup, a CI workflow, the Node version in a
+ * `.nvmrc`: nothing imports them, so nothing has an edge to them, so a walk
+ * from one reaches nothing and a walk to one arrives never. They are *before
+ * reach* — able to repaint the whole suite and invisible to the only mechanism
+ * that could say so.
+ *
+ * ## Why the accident is not enough
+ *
+ * A diff that names only such a file already runs everything, because a diff no
+ * part of which is in the graph is refused. That holds only while it is the
+ * *whole* diff. A CI workflow edited beside one component file is a diff with a
+ * seed in it, and the walk from that seed answers confidently for a change it
+ * never looked at. The widening was a side effect of having nothing to say, and
+ * a side effect stops the moment somebody else has something to say.
+ *
+ * ## Why the operator names them
+ *
+ * Because no rule can. *Every changed path the graph does not hold* is the
+ * README, the changelog, the fixture JSON, the editor settings: a whole run
+ * each, forever, and an operator who turns that off has turned off the config
+ * files too. Which paths govern a run is a fact about the repository that only
+ * the repository knows, so it is declared — and once declared it is exact,
+ * where a heuristic would be both too wide and too narrow on the same diff.
+ *
+ * ## What declaring one buys beyond its own name
+ *
+ * Everything below it. A `setup.ts` the config loads, a fixture module only
+ * that setup imports, a polyfill, the environment package it names: each is an
+ * ordinary file the scan already holds, that nothing imports, whose change
+ * reaches no component and narrows the run to nothing. Declared, the entry
+ * point is walked *along* the arrows once and that whole set comes with it.
+ *
+ * ## Where the descent stops
+ *
+ * At the first file the scan can already reason about. A setup file that
+ * imports `src/theme.ts` does not drag `src/theme.ts` in with it: that file has
+ * dependents, a change to it is answered exactly by walking them, and pulling
+ * it into the harness would trade an exact answer for a whole run — the one
+ * direction this is not allowed to be wrong in. The walk avoids sensed files,
+ * and avoiding a node stops the walk there rather than stepping over it: what
+ * lies below a sensed file is reached *through* it, and it already answers.
+ *
+ * ## Where the two ends meet
+ *
+ * The same walk carries into the package layer, and that is the whole of the
+ * mixed case. A config imports `jest-environment-jsdom`, which rests on
+ * `jsdom`; `jsdom` is bumped; the install comparison names it. It is a package
+ * the harness reaches, so the run does not narrow — and no file in the
+ * repository ever wrote the word. A change beyond reach, arriving before it.
+ *
+ * That cost is real and is the operator's to spend: a config that imports a
+ * bundler reaches everything the bundler rests on, so a bump inside that set
+ * widens. It is the correct answer — the harness did move — and a repository
+ * that finds it too wide narrows what it declares rather than what this
+ * concludes.
+ */
+import { type Relations } from './graph.js';
+/** The part of a run that sits before the tests, as names. */
+export interface BeforeReach {
+    /**
+     * The entry points as they were declared, matched against a diff by path.
+     *
+     * Kept apart from what they reach because they are matched differently: a
+     * declared path claims everything under it, so a directory of workflows is
+     * one entry, while a file the walk found is one file.
+     */
+    readonly entries: readonly string[];
+    /** Files below the entry points that the scan does not otherwise sense. */
+    readonly files: ReadonlySet<string>;
+    /** Packages they rest on, direct and transitive. */
+    readonly packages: ReadonlySet<string>;
+    /**
+     * Declared entry points the graph does not hold, and so has no closure for.
+     *
+     * Ordinary for most of them: a `.nvmrc`, a CI workflow and a `tsconfig` have
+     * nothing below them a scan could read, and they contribute their own name,
+     * which is all they have. Not ordinary for a config the scan should have
+     * read, where it means the closure that would have come with it — the setup
+     * module, the environment — is missing and those files still narrow to
+     * nothing. The two are indistinguishable from here, so both are reported and
+     * neither is guessed at.
+     */
+    readonly unread: readonly string[];
+}
+export interface BeforeReachOptions {
+    /**
+     * Files the scan already answers for, as the directories they live under.
+     *
+     * The descent stops at these. Absent, nothing stops it, and one setup import
+     * into `src/` would put the repository's own source before reach.
+     */
+    readonly sensed?: readonly string[];
+}
+/**
+ * Walk down from each declared entry point, stopping where the scan takes over.
+ *
+ * Along the arrows, unlike every other walk here, because this is the one
+ * question whose subject has no dependents: *what does the harness rest on*.
+ * Type-only edges are not followed — a config's `import type` is erased before
+ * the suite runs, exactly as a component's is.
+ */
+export declare function beforeReach(relations: Relations, entries: readonly string[], options?: BeforeReachOptions): BeforeReach;
+/**
+ * Which of a diff's own inputs the harness rests on, as they were named.
+ *
+ * Files and packages together and in that order, because the caller's next act
+ * is to print them in one sentence and a reader does not care which list a name
+ * came out of. Empty is a real answer: the diff moved nothing the run rests on.
+ *
+ * A declared entry claims every path under it, so naming a directory of
+ * workflows is one line of configuration rather than one per file. A file the
+ * walk found claims only itself: it was reached, so it is known exactly, and
+ * widening it to its directory would put its neighbours before reach without
+ * anybody saying they were.
+ */
+export declare function movedBefore(before: BeforeReach, changed: readonly string[], packages?: readonly string[]): readonly string[];
+/**
+ * Whether a path lies under one of these directories.
+ *
+ * On directory boundaries rather than characters: `src` must not claim
+ * `srcery/`, or a repository would put half of itself before reach and find out
+ * from the runs that never narrowed. Exported because every caller that draws
+ * this boundary over paths draws the same one, and two spellings of it would
+ * disagree on the day one of them was fixed.
+ */
+export declare function within(file: string, dirs: readonly string[]): boolean;
+//# sourceMappingURL=before.d.ts.map

package/dist/relate/before.js ADDED Viewed

@@ -0,0 +1,155 @@
+/**
+ * What a run rests on that nothing in it imports.
+ *
+ * Selection walks one line. It starts at the test harness, moves right through
+ * the tests into the repository's own files, and goes out past them into the
+ * dependencies ([`records.ts`](./records.ts) holds all three as nodes). Every
+ * question it asks is asked *against* the arrows: what depends on the thing
+ * that moved.
+ *
+ * The far-left end of that line answers no such question. A `vitest.config.ts`,
+ * a `jest.config.js`, a Next.js setup, a CI workflow, the Node version in a
+ * `.nvmrc`: nothing imports them, so nothing has an edge to them, so a walk
+ * from one reaches nothing and a walk to one arrives never. They are *before
+ * reach* — able to repaint the whole suite and invisible to the only mechanism
+ * that could say so.
+ *
+ * ## Why the accident is not enough
+ *
+ * A diff that names only such a file already runs everything, because a diff no
+ * part of which is in the graph is refused. That holds only while it is the
+ * *whole* diff. A CI workflow edited beside one component file is a diff with a
+ * seed in it, and the walk from that seed answers confidently for a change it
+ * never looked at. The widening was a side effect of having nothing to say, and
+ * a side effect stops the moment somebody else has something to say.
+ *
+ * ## Why the operator names them
+ *
+ * Because no rule can. *Every changed path the graph does not hold* is the
+ * README, the changelog, the fixture JSON, the editor settings: a whole run
+ * each, forever, and an operator who turns that off has turned off the config
+ * files too. Which paths govern a run is a fact about the repository that only
+ * the repository knows, so it is declared — and once declared it is exact,
+ * where a heuristic would be both too wide and too narrow on the same diff.
+ *
+ * ## What declaring one buys beyond its own name
+ *
+ * Everything below it. A `setup.ts` the config loads, a fixture module only
+ * that setup imports, a polyfill, the environment package it names: each is an
+ * ordinary file the scan already holds, that nothing imports, whose change
+ * reaches no component and narrows the run to nothing. Declared, the entry
+ * point is walked *along* the arrows once and that whole set comes with it.
+ *
+ * ## Where the descent stops
+ *
+ * At the first file the scan can already reason about. A setup file that
+ * imports `src/theme.ts` does not drag `src/theme.ts` in with it: that file has
+ * dependents, a change to it is answered exactly by walking them, and pulling
+ * it into the harness would trade an exact answer for a whole run — the one
+ * direction this is not allowed to be wrong in. The walk avoids sensed files,
+ * and avoiding a node stops the walk there rather than stepping over it: what
+ * lies below a sensed file is reached *through* it, and it already answers.
+ *
+ * ## Where the two ends meet
+ *
+ * The same walk carries into the package layer, and that is the whole of the
+ * mixed case. A config imports `jest-environment-jsdom`, which rests on
+ * `jsdom`; `jsdom` is bumped; the install comparison names it. It is a package
+ * the harness reaches, so the run does not narrow — and no file in the
+ * repository ever wrote the word. A change beyond reach, arriving before it.
+ *
+ * That cost is real and is the operator's to spend: a config that imports a
+ * bundler reaches everything the bundler rests on, so a bump inside that set
+ * widens. It is the correct answer — the harness did move — and a repository
+ * that finds it too wide narrows what it declares rather than what this
+ * concludes.
+ */
+import { nodeAt } from './graph.js';
+import { dependenciesOf } from './reach.js';
+/**
+ * Walk down from each declared entry point, stopping where the scan takes over.
+ *
+ * Along the arrows, unlike every other walk here, because this is the one
+ * question whose subject has no dependents: *what does the harness rest on*.
+ * Type-only edges are not followed — a config's `import type` is erased before
+ * the suite runs, exactly as a component's is.
+ */
+export function beforeReach(relations, entries, options = {}) {
+    const files = new Set();
+    const packages = new Set();
+    const unread = [];
+    if (entries.length === 0)
+        return { entries, files, packages, unread };
+    const sensed = options.sensed ?? [];
+    const held = new Map();
+    for (let id = 0; id < relations.names.length; id += 1) {
+        const node = nodeAt(relations, id);
+        if (node?.kind === 'file')
+            held.set(node.name, id);
+    }
+    const seeds = [];
+    for (const entry of entries) {
+        const id = held.get(entry);
+        if (id === undefined)
+            unread.push(entry);
+        else
+            seeds.push(id);
+    }
+    if (seeds.length === 0)
+        return { entries, files, packages, unread };
+    // Avoided before the walk rather than filtered after it. A sensed file is not
+    // a step on the way to something else here: whatever it imports, it imports
+    // as a file the scan holds, and the dependents of *that* file are the exact
+    // answer the harness would have replaced with a whole run.
+    const entered = new Set(seeds);
+    const avoid = [];
+    for (const [name, id] of held) {
+        if (!entered.has(id) && within(name, sensed))
+            avoid.push(id);
+    }
+    for (const id of dependenciesOf(relations, seeds, { avoid }).reached) {
+        const node = nodeAt(relations, id);
+        if (node === undefined)
+            continue;
+        if (node.kind === 'file')
+            files.add(node.name);
+        else if (node.kind === 'package')
+            packages.add(node.name);
+    }
+    return { entries, files, packages, unread };
+}
+/**
+ * Which of a diff's own inputs the harness rests on, as they were named.
+ *
+ * Files and packages together and in that order, because the caller's next act
+ * is to print them in one sentence and a reader does not care which list a name
+ * came out of. Empty is a real answer: the diff moved nothing the run rests on.
+ *
+ * A declared entry claims every path under it, so naming a directory of
+ * workflows is one line of configuration rather than one per file. A file the
+ * walk found claims only itself: it was reached, so it is known exactly, and
+ * widening it to its directory would put its neighbours before reach without
+ * anybody saying they were.
+ */
+export function movedBefore(before, changed, packages = []) {
+    return [
+        ...changed.filter((file) => before.files.has(file) || within(file, before.entries)),
+        ...packages.filter((name) => before.packages.has(name)),
+    ];
+}
+/**
+ * Whether a path lies under one of these directories.
+ *
+ * On directory boundaries rather than characters: `src` must not claim
+ * `srcery/`, or a repository would put half of itself before reach and find out
+ * from the runs that never narrowed. Exported because every caller that draws
+ * this boundary over paths draws the same one, and two spellings of it would
+ * disagree on the day one of them was fixed.
+ */
+export function within(file, dirs) {
+    return dirs.some((dir) => {
+        const normalized = dir.replace(/\/+$/, '');
+        return normalized === '.' || file === normalized || file.startsWith(`${normalized}/`);
+    });
+}
+//# sourceMappingURL=before.js.map

package/dist/relate/before.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"before.js","sourceRoot":"","sources":["../../src/relate/before.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a run rests on that nothing in it imports.\n *\n * Selection walks one line. It starts at the test harness, moves right through\n * the tests into the repository's own files, and goes out past them into the\n * dependencies ([`records.ts`](./records.ts) holds all three as nodes). Every\n * question it asks is asked *against* the arrows: what depends on the thing\n * that moved.\n *\n * The far-left end of that line answers no such question. A `vitest.config.ts`,\n * a `jest.config.js`, a Next.js setup, a CI workflow, the Node version in a\n * `.nvmrc`: nothing imports them, so nothing has an edge to them, so a walk\n * from one reaches nothing and a walk to one arrives never. They are *before\n * reach* — able to repaint the whole suite and invisible to the only mechanism\n * that could say so.\n *\n * ## Why the accident is not enough\n *\n * A diff that names only such a file already runs everything, because a diff no\n * part of which is in the graph is refused. That holds only while it is the\n * *whole* diff. A CI workflow edited beside one component file is a diff with a\n * seed in it, and the walk from that seed answers confidently for a change it\n * never looked at. The widening was a side effect of having nothing to say, and\n * a side effect stops the moment somebody else has something to say.\n *\n * ## Why the operator names them\n *\n * Because no rule can. *Every changed path the graph does not hold* is the\n * README, the changelog, the fixture JSON, the editor settings: a whole run\n * each, forever, and an operator who turns that off has turned off the config\n * files too. Which paths govern a run is a fact about the repository that only\n * the repository knows, so it is declared — and once declared it is exact,\n * where a heuristic would be both too wide and too narrow on the same diff.\n *\n * ## What declaring one buys beyond its own name\n *\n * Everything below it. A `setup.ts` the config loads, a fixture module only\n * that setup imports, a polyfill, the environment package it names: each is an\n * ordinary file the scan already holds, that nothing imports, whose change\n * reaches no component and narrows the run to nothing. Declared, the entry\n * point is walked *along* the arrows once and that whole set comes with it.\n *\n * ## Where the descent stops\n *\n * At the first file the scan can already reason about. A setup file that\n * imports `src/theme.ts` does not drag `src/theme.ts` in with it: that file has\n * dependents, a change to it is answered exactly by walking them, and pulling\n * it into the harness would trade an exact answer for a whole run — the one\n * direction this is not allowed to be wrong in. The walk avoids sensed files,\n * and avoiding a node stops the walk there rather than stepping over it: what\n * lies below a sensed file is reached *through* it, and it already answers.\n *\n * ## Where the two ends meet\n *\n * The same walk carries into the package layer, and that is the whole of the\n * mixed case. A config imports `jest-environment-jsdom`, which rests on\n * `jsdom`; `jsdom` is bumped; the install comparison names it. It is a package\n * the harness reaches, so the run does not narrow — and no file in the\n * repository ever wrote the word. A change beyond reach, arriving before it.\n *\n * That cost is real and is the operator's to spend: a config that imports a\n * bundler reaches everything the bundler rests on, so a bump inside that set\n * widens. It is the correct answer — the harness did move — and a repository\n * that finds it too wide narrows what it declares rather than what this\n * concludes.\n */\n\nimport { nodeAt, type NodeId, type Relations } from './graph.js';\nimport { dependenciesOf } from './reach.js';\n\n/** The part of a run that sits before the tests, as names. */\nexport interface BeforeReach {\n /**\n * The entry points as they were declared, matched against a diff by path.\n *\n * Kept apart from what they reach because they are matched differently: a\n * declared path claims everything under it, so a directory of workflows is\n * one entry, while a file the walk found is one file.\n */\n readonly entries: readonly string[];\n /** Files below the entry points that the scan does not otherwise sense. */\n readonly files: ReadonlySet<string>;\n /** Packages they rest on, direct and transitive. */\n readonly packages: ReadonlySet<string>;\n /**\n * Declared entry points the graph does not hold, and so has no closure for.\n *\n * Ordinary for most of them: a `.nvmrc`, a CI workflow and a `tsconfig` have\n * nothing below them a scan could read, and they contribute their own name,\n * which is all they have. Not ordinary for a config the scan should have\n * read, where it means the closure that would have come with it — the setup\n * module, the environment — is missing and those files still narrow to\n * nothing. The two are indistinguishable from here, so both are reported and\n * neither is guessed at.\n */\n readonly unread: readonly string[];\n}\n\nexport interface BeforeReachOptions {\n /**\n * Files the scan already answers for, as the directories they live under.\n *\n * The descent stops at these. Absent, nothing stops it, and one setup import\n * into `src/` would put the repository's own source before reach.\n */\n readonly sensed?: readonly string[];\n}\n\n/**\n * Walk down from each declared entry point, stopping where the scan takes over.\n *\n * Along the arrows, unlike every other walk here, because this is the one\n * question whose subject has no dependents: *what does the harness rest on*.\n * Type-only edges are not followed — a config's `import type` is erased before\n * the suite runs, exactly as a component's is.\n */\nexport function beforeReach(\n relations: Relations,\n entries: readonly string[],\n options: BeforeReachOptions = {},\n): BeforeReach {\n const files = new Set<string>();\n const packages = new Set<string>();\n const unread: string[] = [];\n if (entries.length === 0) return { entries, files, packages, unread };\n\n const sensed = options.sensed ?? [];\n const held = new Map<string, NodeId>();\n for (let id = 0; id < relations.names.length; id += 1) {\n const node = nodeAt(relations, id);\n if (node?.kind === 'file') held.set(node.name, id);\n }\n\n const seeds: NodeId[] = [];\n for (const entry of entries) {\n const id = held.get(entry);\n if (id === undefined) unread.push(entry);\n else seeds.push(id);\n }\n if (seeds.length === 0) return { entries, files, packages, unread };\n\n // Avoided before the walk rather than filtered after it. A sensed file is not\n // a step on the way to something else here: whatever it imports, it imports\n // as a file the scan holds, and the dependents of *that* file are the exact\n // answer the harness would have replaced with a whole run.\n const entered = new Set(seeds);\n const avoid: NodeId[] = [];\n for (const [name, id] of held) {\n if (!entered.has(id) && within(name, sensed)) avoid.push(id);\n }\n\n for (const id of dependenciesOf(relations, seeds, { avoid }).reached) {\n const node = nodeAt(relations, id);\n if (node === undefined) continue;\n if (node.kind === 'file') files.add(node.name);\n else if (node.kind === 'package') packages.add(node.name);\n }\n\n return { entries, files, packages, unread };\n}\n\n/**\n * Which of a diff's own inputs the harness rests on, as they were named.\n *\n * Files and packages together and in that order, because the caller's next act\n * is to print them in one sentence and a reader does not care which list a name\n * came out of. Empty is a real answer: the diff moved nothing the run rests on.\n *\n * A declared entry claims every path under it, so naming a directory of\n * workflows is one line of configuration rather than one per file. A file the\n * walk found claims only itself: it was reached, so it is known exactly, and\n * widening it to its directory would put its neighbours before reach without\n * anybody saying they were.\n */\nexport function movedBefore(\n before: BeforeReach,\n changed: readonly string[],\n packages: readonly string[] = [],\n): readonly string[] {\n return [\n ...changed.filter((file) => before.files.has(file) || within(file, before.entries)),\n ...packages.filter((name) => before.packages.has(name)),\n ];\n}\n\n/**\n * Whether a path lies under one of these directories.\n *\n * On directory boundaries rather than characters: `src` must not claim\n * `srcery/`, or a repository would put half of itself before reach and find out\n * from the runs that never narrowed. Exported because every caller that draws\n * this boundary over paths draws the same one, and two spellings of it would\n * disagree on the day one of them was fixed.\n */\nexport function within(file: string, dirs: readonly string[]): boolean {\n return dirs.some((dir) => {\n const normalized = dir.replace(/\\/+$/, '');\n return normalized === '.' || file === normalized || file.startsWith(`${normalized}/`);\n });\n}\n"]}

package/dist/relate/graph.d.ts CHANGED Viewed

@@ -42,15 +42,22 @@
  *
  * ## Nodes are typed, because files are not the last kind
  *
- * This ships with two kinds and the join between them: a `file` graph built from
- * imports, and the `component` nodes the source index already knows how to find.
- * That is deliberate rather than incidental. A component relation — *`TodoFooter`
- * renders `Chip`* — is another edge kind between nodes of another kind in this
- * same structure, and
+ * Three kinds and the joins between them: a `file` graph built from imports, the
+ * `component` nodes the source index already knows how to find, and a `package`
+ * for each name an install resolved. That is deliberate rather than incidental. A
+ * component relation — *`TodoFooter` renders `Chip`* — is another edge kind
+ * between nodes of another kind in this same structure, and
  * [`composition.md`](../../../../docs/composition.md) already computes exactly
  * that relation from what a run rendered. One graph means the static answer and
  * the rendered answer are joinable rather than adjacent.
  *
+ * A `package` earns its kind for the same reason and one more: it is the far end
+ * of the same line. A run starts at the harness, arrives at our code through the
+ * tests, and leaves it again at the packages — so a bumped dependency is a node
+ * like any other, and *which of our files a new `jsdom` can have moved* is the
+ * one traversal this file already performs, seeded on the other side
+ * ([`docs/selecting.md`](../../../../docs/selecting.md)).
+ *
  * ## What it is not
  *
  * **Not a build graph.** It has no notion of a task, an output or a cache key,
@@ -62,7 +69,7 @@
  * disk.
  */
 /** Node kinds, in id order. An id is an index into this, never the word. */
-export declare const NODE_KINDS: readonly ['file', 'component'];
+export declare const NODE_KINDS: readonly ['file', 'component', 'package'];
 export type NodeKind = (typeof NODE_KINDS)[number];
 /**
  * Edge kinds, in id order.
@@ -86,16 +93,26 @@ export declare const EDGE_KINDS: readonly [
 /** A stylesheet's `@import`, or a `url()` reaching a font or an image. */
 'asset',
 /** A component to the file that declares it. */
-'declared-in'];
+'declared-in',
+/** A package to a package its install resolved beneath it. */
+'depends-on'];
 export type EdgeKind = (typeof EDGE_KINDS)[number];
 /**
  * The edge kinds something at runtime can follow: every kind but `type`. The
- * default for a reach and for a closure, and the list a caller widens from.
+ * default for a reach, and the list a caller widens from. A closure folds a
+ * shorter list (`CLOSURE_EDGES`), because a digest is a claim about bytes and
+ * one of these kinds leads nowhere any bytes are.
  */
 export declare const RUNTIME_EDGES: readonly EdgeKind[];
 export interface Node {
     readonly kind: NodeKind;
-    /** Repository-relative for a file; the identifier for a component. */
+    /**
+     * Repository-relative for a file, the identifier for a component, and for a
+     * package the name source code imports it by — `@mui/material`, never a
+     * version and never a resolution. Which copy a resolver handed any one
+     * importer is unanswerable without running that resolver, and the question
+     * this graph is asked never needs it ([`sense/lock`](../../../sense/src/lock/index.ts)).
+     */
     readonly name: string;
 }
 export interface Relation {
@@ -164,8 +181,8 @@ export interface Relations {
  * The lookup key for a node.
  *
  * Runtime only; nothing serializes this, and no code parses it back — the
- * separator only has to be injective, and it is, because a kind is one of two
- * fixed words and neither contains a `:`. A name that contains one is therefore
+ * separator only has to be injective, and it is, because a kind is one of a few
+ * fixed words and none contains a `:`. A name that contains one is therefore
  * fine.
  *
  * The obvious separator is a NUL, and it is the wrong one: a source file