@variance-authority/core 0.14.0 → 0.17.1

package/dist/nearest.js

@@ -0,0 +1,102 @@
+/**
+ * The name somebody meant, when exactly one name is close enough.
+ *
+ * A refusal names what was typed and then the command's synopsis, which lists
+ * what it accepts. The reader is usually an agent, and an agent that mistyped
+ * `--quer` should correct it from the same message instead of spending a second
+ * turn on it. So one sentence goes in front of the synopsis. Naming a candidate
+ * is cheap and reversible: nothing is run on the guess, and a wrong guess costs
+ * one line.
+ *
+ * ## Why one, and why not always
+ *
+ * Two names equally close is not a suggestion, it is a second decision handed
+ * back — so a tie suggests nothing and the set alone answers. And the distance
+ * is bounded by the length of what was typed: without that, `--x` is one edit
+ * from nothing and three from half the table, and a suggestion that fires on
+ * anything is one nobody can read as a signal.
+ *
+ * Damerau-Levenshtein, iterative, over three rows. Transposed neighbours count
+ * as one edit rather than two, which is not a refinement: `aks` for `ask` and
+ * `--fromat` for `--format` are the typo, and under plain Levenshtein both sit
+ * at distance two and are missed by the bound below. No dependency, for the
+ * reason `parse.ts` gives — a tool whose claim is that its output can be trusted
+ * does not acquire a transitive graph to spell-check a flag.
+ */
+/** How far a name may be from what was typed, as a share of the typed length. */
+function within(typed) {
+    // A third of it, at least one and at most three. One edit on a short name and
+    // three on `--exit-zero-on-changes`, which is the range real typos fall in:
+    // a transposition, a dropped character, a repeated one.
+    return Math.min(3, Math.max(1, Math.floor(typed.length / 3)));
+}
+/**
+ * The single closest candidate, or nothing.
+ *
+ * Case-insensitive, because a name typed in the wrong case is the same mistake
+ * and the answer is the same name. Comparison only — what comes back is the
+ * candidate as it is actually spelled, since that is what has to be typed next.
+ */
+export function nearest(typed, candidates) {
+    const limit = within(typed);
+    let best;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    let tied = false;
+    for (const candidate of candidates) {
+        const distance = editDistance(typed.toLowerCase(), candidate.toLowerCase());
+        if (distance > limit)
+            continue;
+        if (distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+            tied = false;
+        }
+        else if (distance === bestDistance) {
+            tied = true;
+        }
+    }
+    return tied ? undefined : best;
+}
+/**
+ * The line a refusal adds beside its list, or nothing.
+ *
+ * Its own function so every refusal says it the same way. An agent reading three
+ * different phrasings for one idea has three things to recognise.
+ *
+ * A line of its own, and it carries the newline itself so a refusal with nothing
+ * to suggest does not print a blank one. Beside the accepted set rather than
+ * inside that sentence: the set is the part a reader parses — a name split out
+ * of a list should not have half a second sentence attached to it.
+ */
+export function didYouMean(typed, candidates) {
+    const found = nearest(typed, candidates);
+    return found === undefined ? '' : `\nDid you mean \`${found}\`?`;
+}
+/**
+ * Edits between two strings, counting a swap of neighbours as one.
+ *
+ * Three rows rather than a matrix: a transposition needs the row before last,
+ * and nothing needs the one before that.
+ */
+function editDistance(from, to) {
+    let twoBack = [];
+    let previous = Array.from({ length: to.length + 1 }, (_, index) => index);
+    for (let row = 1; row <= from.length; row += 1) {
+        const current = [row];
+        for (let column = 1; column <= to.length; column += 1) {
+            const same = from[row - 1] === to[column - 1];
+            let best = Math.min(previous[column - 1] + (same ? 0 : 1), previous[column] + 1, current[column - 1] + 1);
+            if (row > 1 &&
+                column > 1 &&
+                from[row - 1] === to[column - 2] &&
+                from[row - 2] === to[column - 1]) {
+                best = Math.min(best, twoBack[column - 2] + 1);
+            }
+            current[column] = best;
+        }
+        twoBack = previous;
+        previous = current;
+    }
+    return previous[to.length];
+}
+//# sourceMappingURL=nearest.js.map

package/dist/nearest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nearest.js","sourceRoot":"","sources":["../src/nearest.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The name somebody meant, when exactly one name is close enough.\n *\n * A refusal names what was typed and then the command's synopsis, which lists\n * what it accepts. The reader is usually an agent, and an agent that mistyped\n * `--quer` should correct it from the same message instead of spending a second\n * turn on it. So one sentence goes in front of the synopsis. Naming a candidate\n * is cheap and reversible: nothing is run on the guess, and a wrong guess costs\n * one line.\n *\n * ## Why one, and why not always\n *\n * Two names equally close is not a suggestion, it is a second decision handed\n * back — so a tie suggests nothing and the set alone answers. And the distance\n * is bounded by the length of what was typed: without that, `--x` is one edit\n * from nothing and three from half the table, and a suggestion that fires on\n * anything is one nobody can read as a signal.\n *\n * Damerau-Levenshtein, iterative, over three rows. Transposed neighbours count\n * as one edit rather than two, which is not a refinement: `aks` for `ask` and\n * `--fromat` for `--format` are the typo, and under plain Levenshtein both sit\n * at distance two and are missed by the bound below. No dependency, for the\n * reason `parse.ts` gives — a tool whose claim is that its output can be trusted\n * does not acquire a transitive graph to spell-check a flag.\n */\n\n/** How far a name may be from what was typed, as a share of the typed length. */\nfunction within(typed: string): number {\n  // A third of it, at least one and at most three. One edit on a short name and\n  // three on `--exit-zero-on-changes`, which is the range real typos fall in:\n  // a transposition, a dropped character, a repeated one.\n  return Math.min(3, Math.max(1, Math.floor(typed.length / 3)));\n}\n\n/**\n * The single closest candidate, or nothing.\n *\n * Case-insensitive, because a name typed in the wrong case is the same mistake\n * and the answer is the same name. Comparison only — what comes back is the\n * candidate as it is actually spelled, since that is what has to be typed next.\n */\nexport function nearest(typed: string, candidates: readonly string[]): string | undefined {\n  const limit = within(typed);\n  let best: string | undefined;\n  let bestDistance = Number.POSITIVE_INFINITY;\n  let tied = false;\n\n  for (const candidate of candidates) {\n    const distance = editDistance(typed.toLowerCase(), candidate.toLowerCase());\n    if (distance > limit) continue;\n    if (distance < bestDistance) {\n      best = candidate;\n      bestDistance = distance;\n      tied = false;\n    } else if (distance === bestDistance) {\n      tied = true;\n    }\n  }\n\n  return tied ? undefined : best;\n}\n\n/**\n * The line a refusal adds beside its list, or nothing.\n *\n * Its own function so every refusal says it the same way. An agent reading three\n * different phrasings for one idea has three things to recognise.\n *\n * A line of its own, and it carries the newline itself so a refusal with nothing\n * to suggest does not print a blank one. Beside the accepted set rather than\n * inside that sentence: the set is the part a reader parses — a name split out\n * of a list should not have half a second sentence attached to it.\n */\nexport function didYouMean(typed: string, candidates: readonly string[]): string {\n  const found = nearest(typed, candidates);\n  return found === undefined ? '' : `\\nDid you mean \\`${found}\\`?`;\n}\n\n/**\n * Edits between two strings, counting a swap of neighbours as one.\n *\n * Three rows rather than a matrix: a transposition needs the row before last,\n * and nothing needs the one before that.\n */\nfunction editDistance(from: string, to: string): number {\n  let twoBack: number[] = [];\n  let previous = Array.from({ length: to.length + 1 }, (_, index) => index);\n\n  for (let row = 1; row <= from.length; row += 1) {\n    const current = [row];\n    for (let column = 1; column <= to.length; column += 1) {\n      const same = from[row - 1] === to[column - 1];\n      let best = Math.min(\n        previous[column - 1]! + (same ? 0 : 1),\n        previous[column]! + 1,\n        current[column - 1]! + 1,\n      );\n      if (\n        row > 1 &&\n        column > 1 &&\n        from[row - 1] === to[column - 2] &&\n        from[row - 2] === to[column - 1]\n      ) {\n        best = Math.min(best, twoBack[column - 2]! + 1);\n      }\n      current[column] = best;\n    }\n    twoBack = previous;\n    previous = current;\n  }\n\n  return previous[to.length]!;\n}\n"]}

package/dist/relate/before.d.ts

@@ -34,11 +34,16 @@
  *
  * ## 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.
+ * Everything below it. A fixture module only the setup imports, a polyfill,
+ * the environment package it registers: each is an ordinary file the scan
+ * already holds, that nothing in a test 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.
+ *
+ * Only along imports. A runner config names its setup files as strings, and a
+ * string is no edge, so the setup is declared beside the config rather than
+ * found below it. Reading what a runner would make of its own config is the
+ * runner's answer, and guessing at it here would be wrong the day it changed.
  *
  * ## Where the descent stops
  *
@@ -52,17 +57,12 @@
  *
  * ## 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 change — and a repository
- * that finds it too wide narrows what it declares rather than what this
- * concludes.
+ * Not here. A setup imports `jest-environment-jsdom`, which rests on `jsdom`;
+ * `jsdom` is bumped. [`beyond.ts`](./beyond.ts) reads that bump back into the
+ * file whose import rests on it, the setup, before this stage is asked, so the
+ * closure holds files alone and a bump the harness rests on arrives as the
+ * harness file it changed. No file in the repository ever wrote the word, and
+ * the run still does not narrow.
  */
 import { type Relations } from './graph.js';
 /** The part of a run that sits before the tests, as names. */
@@ -77,8 +77,6 @@ export interface BeforeReach {
     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.
      *
@@ -111,11 +109,8 @@ export interface BeforeReachOptions {
  */
 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 changed nothing the run rests on.
+ * Which of a diff's changed files the harness rests on, as they were named.
+ * Empty is a real answer: the diff changed 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
@@ -123,7 +118,7 @@ export declare function beforeReach(relations: Relations, entries: readonly stri
  * widening it to its directory would put its neighbours before reach without
  * anybody saying they were.
  */
-export declare function changedBefore(before: BeforeReach, changed: readonly string[], packages?: readonly string[]): readonly string[];
+export declare function changedBefore(before: BeforeReach, changed: readonly string[]): readonly string[];
 /**
  * Whether a path lies under one of these directories.
  *

package/dist/relate/before.js

@@ -34,11 +34,16 @@
  *
  * ## 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.
+ * Everything below it. A fixture module only the setup imports, a polyfill,
+ * the environment package it registers: each is an ordinary file the scan
+ * already holds, that nothing in a test 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.
+ *
+ * Only along imports. A runner config names its setup files as strings, and a
+ * string is no edge, so the setup is declared beside the config rather than
+ * found below it. Reading what a runner would make of its own config is the
+ * runner's answer, and guessing at it here would be wrong the day it changed.
  *
  * ## Where the descent stops
  *
@@ -52,19 +57,14 @@
  *
  * ## 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 change — and a repository
- * that finds it too wide narrows what it declares rather than what this
- * concludes.
+ * Not here. A setup imports `jest-environment-jsdom`, which rests on `jsdom`;
+ * `jsdom` is bumped. [`beyond.ts`](./beyond.ts) reads that bump back into the
+ * file whose import rests on it, the setup, before this stage is asked, so the
+ * closure holds files alone and a bump the harness rests on arrives as the
+ * harness file it changed. No file in the repository ever wrote the word, and
+ * the run still does not narrow.
  */
-import { nodeAt } from './graph.js';
+import { RUNTIME_EDGES, nodeAt } from './graph.js';
 import { dependenciesOf } from './reach.js';
 /**
  * Walk down from each declared entry point, stopping where the scan takes over.
@@ -76,10 +76,9 @@ import { dependenciesOf } from './reach.js';
  */
 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 };
+        return { entries, files, unread };
     const sensed = options.sensed ?? [];
     const held = new Map();
     for (let id = 0; id < relations.names.length; id += 1) {
@@ -87,16 +86,25 @@ export function beforeReach(relations, entries, options = {}) {
         if (node?.kind === 'file')
             held.set(node.name, id);
     }
+    // A declared directory is every file the graph holds under it, each walked
+    // as an entry point: a setup under `test/` loads what it loads whether the
+    // operator named the file or the directory it sits in.
     const seeds = [];
     for (const entry of entries) {
         const id = held.get(entry);
-        if (id === undefined)
+        if (id !== undefined) {
+            seeds.push(id);
+            continue;
+        }
+        const under = [...held].filter(([name]) => within(name, [entry]));
+        if (under.length === 0)
             unread.push(entry);
         else
-            seeds.push(id);
+            for (const [, below] of under)
+                seeds.push(below);
     }
     if (seeds.length === 0)
-        return { entries, files, packages, unread };
+        return { entries, files, 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
@@ -107,23 +115,16 @@ export function beforeReach(relations, entries, options = {}) {
         if (!entered.has(id) && within(name, sensed))
             avoid.push(id);
     }
-    for (const id of dependenciesOf(relations, seeds, { avoid }).nodes) {
+    for (const id of dependenciesOf(relations, seeds, { through: RUNTIME_EDGES, avoid }).nodes) {
         const node = nodeAt(relations, id);
-        if (node === undefined)
-            continue;
-        if (node.kind === 'file')
+        if (node?.kind === 'file')
             files.add(node.name);
-        else if (node.kind === 'package')
-            packages.add(node.name);
     }
-    return { entries, files, packages, unread };
+    return { entries, files, 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 changed nothing the run rests on.
+ * Which of a diff's changed files the harness rests on, as they were named.
+ * Empty is a real answer: the diff changed 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
@@ -131,11 +132,8 @@ export function beforeReach(relations, entries, options = {}) {
  * widening it to its directory would put its neighbours before reach without
  * anybody saying they were.
  */
-export function changedBefore(before, changed, packages = []) {
-    return [
-        ...changed.filter((file) => before.files.has(file) || within(file, before.entries)),
-        ...packages.filter((name) => before.packages.has(name)),
-    ];
+export function changedBefore(before, changed) {
+    return changed.filter((file) => before.files.has(file) || within(file, before.entries));
 }
 /**
  * Whether a path lies under one of these directories.

package/dist/relate/before.js.map

@@ -1 +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 changed.\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 imported *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 change — 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 walked — 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 }).nodes) {\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 changed 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: the walk visited it, 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 changedBefore(\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"]}
+{"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 changed.\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 fixture module only the setup imports, a polyfill,\n * the environment package it registers: each is an ordinary file the scan\n * already holds, that nothing in a test imports, whose change reaches no\n * component and narrows the run to nothing. Declared, the entry point is walked\n * *along* the arrows once and that whole set comes with it.\n *\n * Only along imports. A runner config names its setup files as strings, and a\n * string is no edge, so the setup is declared beside the config rather than\n * found below it. Reading what a runner would make of its own config is the\n * runner's answer, and guessing at it here would be wrong the day it changed.\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 imported *through* it, and it already answers.\n *\n * ## Where the two ends meet\n *\n * Not here. A setup imports `jest-environment-jsdom`, which rests on `jsdom`;\n * `jsdom` is bumped. [`beyond.ts`](./beyond.ts) reads that bump back into the\n * file whose import rests on it, the setup, before this stage is asked, so the\n * closure holds files alone and a bump the harness rests on arrives as the\n * harness file it changed. No file in the repository ever wrote the word, and\n * the run still does not narrow.\n */\n\nimport { RUNTIME_EDGES, 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  /**\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 walked — 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 unread: string[] = [];\n  if (entries.length === 0) return { entries, files, 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  // A declared directory is every file the graph holds under it, each walked\n  // as an entry point: a setup under `test/` loads what it loads whether the\n  // operator named the file or the directory it sits in.\n  const seeds: NodeId[] = [];\n  for (const entry of entries) {\n    const id = held.get(entry);\n    if (id !== undefined) {\n      seeds.push(id);\n      continue;\n    }\n    const under = [...held].filter(([name]) => within(name, [entry]));\n    if (under.length === 0) unread.push(entry);\n    else for (const [, below] of under) seeds.push(below);\n  }\n  if (seeds.length === 0) return { entries, files, 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, { through: RUNTIME_EDGES, avoid }).nodes) {\n    const node = nodeAt(relations, id);\n    if (node?.kind === 'file') files.add(node.name);\n  }\n\n  return { entries, files, unread };\n}\n\n/**\n * Which of a diff's changed files the harness rests on, as they were named.\n * Empty is a real answer: the diff changed 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: the walk visited it, 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 changedBefore(before: BeforeReach, changed: readonly string[]): readonly string[] {\n  return changed.filter((file) => before.files.has(file) || within(file, before.entries));\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/beyond.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What a change to the install did to the repository's own files.
+ *
+ * The far-right end of the line selection walks. A bumped package and a moved
+ * manifest change how files load without changing a line of any of them, and
+ * every later stage of a selection asks about files: whether one sits before
+ * reach, whether the record measured it, which tests entered it. So the install
+ * is read back into files once, here, and nothing after this stage hears of a
+ * package.
+ *
+ * ## Where a bump stops
+ *
+ * Against the arrows through the install, then one step into the repository. A
+ * bump of `jsdom` reaches `jest-environment-jsdom`, which rests on it, and from
+ * there the setup file that imports that: the first file whose import loads the
+ * changed code. It stops there because everything further along loads the
+ * package through that file, so a test that entered anything further along
+ * evaluated it on the way, and the stages after this one answer for its
+ * importers as they do for any changed file's.
+ *
+ * Runtime edges only. `import type { Theme } from '@mui/material'` is erased
+ * before anything runs, so a bump of `@mui/material` reaches nothing through it.
+ *
+ * ## Absence
+ *
+ * A package the graph holds no node for is imported by nothing here, and it
+ * reaches nothing. That is an answer rather than a gap: every file that names a
+ * package has an edge to it.
+ */
+import { type Relations } from './graph.js';
+/** What the install comparison says moved, by name. */
+export interface InstallMoved {
+    /** Packages whose installed version moved. */
+    readonly packages: readonly string[];
+    /** Manifests whose `exports`, `main` or `type` moved, as repository paths. */
+    readonly moved: readonly string[];
+}
+/** The install, read as files. */
+export interface BeyondReach {
+    /** Every repository file a bump or a moved manifest changed, whole, sorted. */
+    readonly files: readonly string[];
+    /**
+     * Moved manifests the graph holds no file beside: a gap under the scanned
+     * roots, or a package outside them. Each is read as the ordinary changed path
+     * it would have been, rather than as a package that reached nothing.
+     */
+    readonly unplaced: readonly string[];
+    /** The bumped packages that changed a file, for the sentence that says what the answer was built from. */
+    readonly traced: readonly string[];
+    /**
+     * For each file a bump reached, the packages it was reached through, from the
+     * bumped one to the one the file imports: `['jsdom', 'jest-environment-jsdom']`.
+     * The first bump to reach a file names it.
+     */
+    readonly chains: ReadonlyMap<string, readonly string[]>;
+}
+/** Trace the install's moves to the repository files they change. */
+export declare function beyondReach(relations: Relations, install: InstallMoved): BeyondReach;
+//# sourceMappingURL=beyond.d.ts.map

package/dist/relate/beyond.js

@@ -0,0 +1,98 @@
+// compass: variance-authority.reach
+/**
+ * What a change to the install did to the repository's own files.
+ *
+ * The far-right end of the line selection walks. A bumped package and a moved
+ * manifest change how files load without changing a line of any of them, and
+ * every later stage of a selection asks about files: whether one sits before
+ * reach, whether the record measured it, which tests entered it. So the install
+ * is read back into files once, here, and nothing after this stage hears of a
+ * package.
+ *
+ * ## Where a bump stops
+ *
+ * Against the arrows through the install, then one step into the repository. A
+ * bump of `jsdom` reaches `jest-environment-jsdom`, which rests on it, and from
+ * there the setup file that imports that: the first file whose import loads the
+ * changed code. It stops there because everything further along loads the
+ * package through that file, so a test that entered anything further along
+ * evaluated it on the way, and the stages after this one answer for its
+ * importers as they do for any changed file's.
+ *
+ * Runtime edges only. `import type { Theme } from '@mui/material'` is erased
+ * before anything runs, so a bump of `@mui/material` reaches nothing through it.
+ *
+ * ## Absence
+ *
+ * A package the graph holds no node for is imported by nothing here, and it
+ * reaches nothing. That is an answer rather than a gap: every file that names a
+ * package has an edge to it.
+ */
+import { EDGE_KINDS, RUNTIME_EDGES, idOf, nodeAt, nodesOfKind } from './graph.js';
+import { within } from './before.js';
+import { dependentsOf, trailOf } from './reach.js';
+/** The edge kinds a file loads a package through, as a byte lookup over `EDGE_KINDS`. */
+const IMPORTS = new Uint8Array(EDGE_KINDS.length);
+for (const kind of RUNTIME_EDGES)
+    if (kind !== 'depends-on')
+        IMPORTS[EDGE_KINDS.indexOf(kind)] = 1;
+/** Trace the install's moves to the repository files they change. */
+export function beyondReach(relations, install) {
+    const files = new Set();
+    const traced = [];
+    const chains = new Map();
+    for (const name of install.packages) {
+        const id = idOf(relations, 'package', name);
+        if (id === undefined)
+            continue;
+        // Every package whose install rests on this one, itself included.
+        const traversal = dependentsOf(relations, [id], { through: ['depends-on'] });
+        let reached = false;
+        for (const at of traversal.nodes) {
+            for (const importer of importersOf(relations, at)) {
+                const file = relations.names[importer];
+                files.add(file);
+                if (!chains.has(file))
+                    chains.set(file, trailOf(traversal, at).map((step) => relations.names[step]));
+                reached = true;
+            }
+        }
+        if (reached)
+            traced.push(name);
+    }
+    // A moved manifest's directory is expanded the way a monorepo tool's changed
+    // directory is: every file the graph holds under it.
+    const unplaced = [];
+    if (install.moved.length > 0) {
+        const names = nodesOfKind(relations, 'file').map((id) => relations.names[id]);
+        for (const manifest of install.moved) {
+            const beside = names.filter((file) => within(file, [directoryOf(manifest)]));
+            if (beside.length === 0)
+                unplaced.push(manifest);
+            for (const file of beside)
+                files.add(file);
+        }
+    }
+    return { files: [...files].sort(byCodeUnit), unplaced, traced, chains };
+}
+/** The files with a runtime import of `id`, one step against the arrows. */
+function importersOf(relations, id) {
+    const { offset, kind, target } = relations.dependents;
+    const importers = [];
+    for (let at = offset[id]; at < offset[id + 1]; at += 1) {
+        if (IMPORTS[kind[at]] !== 1)
+            continue;
+        const other = target[at];
+        if (nodeAt(relations, other)?.kind === 'file')
+            importers.push(other);
+    }
+    return importers;
+}
+function directoryOf(file) {
+    const at = file.lastIndexOf('/');
+    return at === -1 ? '.' : file.slice(0, at);
+}
+function byCodeUnit(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+//# sourceMappingURL=beyond.js.map

package/dist/relate/beyond.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beyond.js","sourceRoot":"","sources":["../../src/relate/beyond.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAA+B,MAAM,YAAY,CAAC;AAC/G,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AA8BnD,yFAAyF;AACzF,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAClD,KAAK,MAAM,IAAI,IAAI,aAAa;IAAE,IAAI,IAAI,KAAK,YAAY;QAAE,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;AAEnG,qEAAqE;AACrE,MAAM,UAAU,WAAW,CAAC,SAAoB,EAAE,OAAqB;IACrE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAEhC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,IAAI,GAAG,EAA6B,CAAC;IACpD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACpC,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;QAC5C,IAAI,EAAE,KAAK,SAAS;YAAE,SAAS;QAC/B,kEAAkE;QAClE,MAAM,SAAS,GAAG,YAAY,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;QAC7E,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,KAAK,MAAM,EAAE,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC;YACjC,KAAK,MAAM,QAAQ,IAAI,WAAW,CAAC,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC;gBAClD,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAE,CAAC;gBACxC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAChB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;oBAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAE,CAAC,CAAC,CAAC;gBACtG,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC;QACH,CAAC;QACD,IAAI,OAAO;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,6EAA6E;IAC7E,qDAAqD;IACrD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAE,CAAC,CAAC;QAC/E,KAAK,MAAM,QAAQ,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YACrC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YAC7E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACjD,KAAK,MAAM,IAAI,IAAI,MAAM;gBAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC1E,CAAC;AAED,4EAA4E;AAC5E,SAAS,WAAW,CAAC,SAAoB,EAAE,EAAU;IACnD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,UAAU,CAAC;IACtD,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,IAAI,EAAE,GAAG,MAAM,CAAC,EAAE,CAAE,EAAE,EAAE,GAAG,MAAM,CAAC,EAAE,GAAG,CAAC,CAAE,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC;QACzD,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAE,CAAC,KAAK,CAAC;YAAE,SAAS;QACvC,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAE,CAAC;QAC1B,IAAI,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,IAAI,KAAK,MAAM;YAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACjC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,UAAU,CAAC,CAAS,EAAE,CAAS;IACtC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC","sourcesContent":["// compass: variance-authority.reach\n/**\n * What a change to the install did to the repository's own files.\n *\n * The far-right end of the line selection walks. A bumped package and a moved\n * manifest change how files load without changing a line of any of them, and\n * every later stage of a selection asks about files: whether one sits before\n * reach, whether the record measured it, which tests entered it. So the install\n * is read back into files once, here, and nothing after this stage hears of a\n * package.\n *\n * ## Where a bump stops\n *\n * Against the arrows through the install, then one step into the repository. A\n * bump of `jsdom` reaches `jest-environment-jsdom`, which rests on it, and from\n * there the setup file that imports that: the first file whose import loads the\n * changed code. It stops there because everything further along loads the\n * package through that file, so a test that entered anything further along\n * evaluated it on the way, and the stages after this one answer for its\n * importers as they do for any changed file's.\n *\n * Runtime edges only. `import type { Theme } from '@mui/material'` is erased\n * before anything runs, so a bump of `@mui/material` reaches nothing through it.\n *\n * ## Absence\n *\n * A package the graph holds no node for is imported by nothing here, and it\n * reaches nothing. That is an answer rather than a gap: every file that names a\n * package has an edge to it.\n */\n\nimport { EDGE_KINDS, RUNTIME_EDGES, idOf, nodeAt, nodesOfKind, type NodeId, type Relations } from './graph.js';\nimport { within } from './before.js';\nimport { dependentsOf, trailOf } from './reach.js';\n\n/** What the install comparison says moved, by name. */\nexport interface InstallMoved {\n  /** Packages whose installed version moved. */\n  readonly packages: readonly string[];\n  /** Manifests whose `exports`, `main` or `type` moved, as repository paths. */\n  readonly moved: readonly string[];\n}\n\n/** The install, read as files. */\nexport interface BeyondReach {\n  /** Every repository file a bump or a moved manifest changed, whole, sorted. */\n  readonly files: readonly string[];\n  /**\n   * Moved manifests the graph holds no file beside: a gap under the scanned\n   * roots, or a package outside them. Each is read as the ordinary changed path\n   * it would have been, rather than as a package that reached nothing.\n   */\n  readonly unplaced: readonly string[];\n  /** The bumped packages that changed a file, for the sentence that says what the answer was built from. */\n  readonly traced: readonly string[];\n  /**\n   * For each file a bump reached, the packages it was reached through, from the\n   * bumped one to the one the file imports: `['jsdom', 'jest-environment-jsdom']`.\n   * The first bump to reach a file names it.\n   */\n  readonly chains: ReadonlyMap<string, readonly string[]>;\n}\n\n/** The edge kinds a file loads a package through, as a byte lookup over `EDGE_KINDS`. */\nconst IMPORTS = new Uint8Array(EDGE_KINDS.length);\nfor (const kind of RUNTIME_EDGES) if (kind !== 'depends-on') IMPORTS[EDGE_KINDS.indexOf(kind)] = 1;\n\n/** Trace the install's moves to the repository files they change. */\nexport function beyondReach(relations: Relations, install: InstallMoved): BeyondReach {\n  const files = new Set<string>();\n\n  const traced: string[] = [];\n  const chains = new Map<string, readonly string[]>();\n  for (const name of install.packages) {\n    const id = idOf(relations, 'package', name);\n    if (id === undefined) continue;\n    // Every package whose install rests on this one, itself included.\n    const traversal = dependentsOf(relations, [id], { through: ['depends-on'] });\n    let reached = false;\n    for (const at of traversal.nodes) {\n      for (const importer of importersOf(relations, at)) {\n        const file = relations.names[importer]!;\n        files.add(file);\n        if (!chains.has(file)) chains.set(file, trailOf(traversal, at).map((step) => relations.names[step]!));\n        reached = true;\n      }\n    }\n    if (reached) traced.push(name);\n  }\n\n  // A moved manifest's directory is expanded the way a monorepo tool's changed\n  // directory is: every file the graph holds under it.\n  const unplaced: string[] = [];\n  if (install.moved.length > 0) {\n    const names = nodesOfKind(relations, 'file').map((id) => relations.names[id]!);\n    for (const manifest of install.moved) {\n      const beside = names.filter((file) => within(file, [directoryOf(manifest)]));\n      if (beside.length === 0) unplaced.push(manifest);\n      for (const file of beside) files.add(file);\n    }\n  }\n\n  return { files: [...files].sort(byCodeUnit), unplaced, traced, chains };\n}\n\n/** The files with a runtime import of `id`, one step against the arrows. */\nfunction importersOf(relations: Relations, id: NodeId): readonly NodeId[] {\n  const { offset, kind, target } = relations.dependents;\n  const importers: NodeId[] = [];\n  for (let at = offset[id]!; at < offset[id + 1]!; at += 1) {\n    if (IMPORTS[kind[at]!] !== 1) continue;\n    const other = target[at]!;\n    if (nodeAt(relations, other)?.kind === 'file') importers.push(other);\n  }\n  return importers;\n}\n\nfunction directoryOf(file: string): string {\n  const at = file.lastIndexOf('/');\n  return at === -1 ? '.' : file.slice(0, at);\n}\n\nfunction byCodeUnit(a: string, b: string): number {\n  return a < b ? -1 : a > b ? 1 : 0;\n}\n"]}