@variance-authority/core 0.1.0

package/dist/relate/merkle.js

@@ -0,0 +1,246 @@
+/**
+ * The graph, hashed the way a build system hashes an action's inputs.
+ *
+ * Reachability answers *what could this diff have moved*. It needs a diff, which
+ * means it needs `git`, a ref that exists, a checkout deep enough to contain it,
+ * and the assumption that the ref is where this branch actually diverged. Every
+ * one of those is a thing CI gets wrong, and each failure narrows a run.
+ *
+ * A Merkle digest asks a different question and needs none of them: **is this
+ * subject's entire input closure byte-identical to the one that produced the
+ * baseline?** One digest per node, over the node's own content and the digests of
+ * everything it rests on — the same construction `bazel` uses to key an action,
+ * and the same idea as this project's own content addressing, applied one level
+ * out from the document to the source that produced it.
+ *
+ * What the difference buys:
+ *
+ * | situation | reachability | closure digest |
+ * |---|---|---|
+ * | a change, then a revert | both commits are in the diff, so it widens | identical digest, nothing runs |
+ * | rebase, squash, branch switch | the merge base moves and the diff with it | unaffected — no ref is consulted |
+ * | a shallow clone with no merge base | cannot answer; runs everything | unaffected |
+ * | a dependency changed two hops away | reached, and observed | different digest, and observed |
+ * | *why* a subject is being observed | a chain of files | a digest that differs |
+ *
+ * Neither replaces the other. The trail is the explanation, and the digest is the
+ * proof; a run wants the digest to decide and the trail to justify.
+ *
+ * ## Cycles
+ *
+ * A dependency graph has them and a Merkle tree cannot. Strongly connected
+ * components are condensed and hashed as a unit, so every file in a cycle carries
+ * the same digest — which is exactly the truth about a cycle: no member of one can
+ * be called unchanged while another moved.
+ *
+ * ## The digest that must never lie
+ *
+ * A digest says *these inputs are the same*. A file whose content was not supplied,
+ * or whose own imports could not be read, breaks that claim — its closure may have
+ * moved with no digest in this structure changing. Those nodes are marked
+ * **volatile**, the mark propagates to everything that rests on them, and a
+ * volatile node is treated as changed however its digest compares. A cache that
+ * cannot be trusted must not be silently trusted.
+ */
+import { digestCombine, digestString } from '../format/hash.js';
+import { EDGE_KINDS, NODE_KINDS, keyOf, } from './graph.js';
+/**
+ * Hash every node over its own content and its whole dependency closure.
+ *
+ * One pass of Tarjan's algorithm and one pass over the components it emits, which
+ * is `O(n + m)` — the same cost as the traversal next door, for an answer that
+ * survives a rebase.
+ */
+export function closureOf(input) {
+    const { relations, content } = input;
+    const allowed = allowedKinds(input.through);
+    const count = relations.names.length;
+    const { component, order } = condense(relations, allowed);
+    const digests = new Map();
+    const unstable = new Set();
+    // One digest per component, so every member of a cycle carries the same one.
+    const byComponent = [];
+    const shakyComponent = [];
+    // Tarjan emits a component only after everything it can reach, so a dependency
+    // digest is always already computed by the time it is read here.
+    for (const [id, members] of order.entries()) {
+        const terms = [];
+        const outward = new Set();
+        let shaky = false;
+        for (const node of members) {
+            const kind = NODE_KINDS[relations.kinds[node]];
+            const name = relations.names[node];
+            const own = kind === 'file' ? content.get(name) : SETTLED;
+            if (own === undefined || relations.unknown[node] === 1)
+                shaky = true;
+            terms.push(`${kind}\u0000${name}\u0000${own ?? UNREAD}`);
+            const { offset, target, kind: edgeKind } = relations.depends;
+            for (let at = offset[node]; at < offset[node + 1]; at += 1) {
+                if (allowed[edgeKind[at]] !== 1)
+                    continue;
+                const other = target[at];
+                if (component[other] === id)
+                    continue;
+                outward.add(`${EDGE_KINDS[edgeKind[at]]}\u0000${byComponent[component[other]]}`);
+                if (shakyComponent[component[other]] === true)
+                    shaky = true;
+            }
+        }
+        byComponent.push(digestCombine('relate.closure', [
+            digestString([...terms].sort(byCodeUnit).join('
')),
+            digestString([...outward].sort(byCodeUnit).join('
')),
+        ]));
+        shakyComponent.push(shaky);
+    }
+    for (let node = 0; node < count; node += 1) {
+        const key = keyOf(NODE_KINDS[relations.kinds[node]], relations.names[node]);
+        digests.set(key, byComponent[component[node]]);
+        if (shakyComponent[component[node]] === true)
+            unstable.add(key);
+    }
+    return { digests, volatile: unstable };
+}
+/** The term a node with content contributes when the content is not known. */
+const UNREAD = '(unread)';
+/** The term a node that has no content of its own contributes. */
+const SETTLED = '(declared)';
+/**
+ * What moved between two closures, without consulting a repository.
+ *
+ * Three ways a node lands in `changed`, and only the first is a difference: its
+ * digest differs, it is **new**, or it is **volatile** — the last because a node
+ * whose inputs were not fully read has a digest that can match by accident, and a
+ * selector that believed it would skip a subject on the strength of a hash over
+ * bytes nobody hashed.
+ */
+export function driftedBetween(before, after) {
+    const changed = [];
+    for (const [key, digest] of after.digests) {
+        const was = before.digests.get(key);
+        if (was === digest && !after.volatile.has(key) && !before.volatile.has(key))
+            continue;
+        changed.push(key);
+    }
+    const gone = [...before.digests.keys()].filter((key) => !after.digests.has(key));
+    return {
+        changed: changed.sort(byCodeUnit),
+        files: named(changed, 'file'),
+        components: named(changed, 'component'),
+        gone: gone.sort(byCodeUnit),
+    };
+}
+function named(keys, kind) {
+    const prefix = `${kind}:`;
+    return keys
+        .filter((key) => key.startsWith(prefix))
+        .map((key) => key.slice(prefix.length))
+        .sort(byCodeUnit);
+}
+/**
+ * Tarjan's strongly connected components, iteratively.
+ *
+ * Iterative because the recursion depth is the longest dependency chain in the
+ * repository, and a deep monorepo would overflow a call stack on a structure whose
+ * whole point is to be cheap. The emission order is the useful half: a component
+ * appears only once everything it can reach has, which is the order a Merkle fold
+ * needs and costs nothing extra to get.
+ */
+function condense(relations, allowed) {
+    const count = relations.names.length;
+    const { offset, target, kind } = relations.depends;
+    const index = new Int32Array(count).fill(-1);
+    const low = new Int32Array(count);
+    const onStack = new Uint8Array(count);
+    const component = new Int32Array(count).fill(-1);
+    const pending = [];
+    const order = [];
+    // Frames as two parallel arrays: the node, and how far through its edges it is.
+    const frameNode = [];
+    const frameEdge = [];
+    let counter = 0;
+    for (let root = 0; root < count; root += 1) {
+        if (index[root] !== -1)
+            continue;
+        index[root] = counter;
+        low[root] = counter;
+        counter += 1;
+        pending.push(root);
+        onStack[root] = 1;
+        frameNode.push(root);
+        frameEdge.push(offset[root]);
+        while (frameNode.length > 0) {
+            const node = frameNode[frameNode.length - 1];
+            const at = frameEdge[frameEdge.length - 1];
+            if (at < offset[node + 1]) {
+                frameEdge[frameEdge.length - 1] = at + 1;
+                if (allowed[kind[at]] !== 1)
+                    continue;
+                const next = target[at];
+                if (index[next] === -1) {
+                    index[next] = counter;
+                    low[next] = counter;
+                    counter += 1;
+                    pending.push(next);
+                    onStack[next] = 1;
+                    frameNode.push(next);
+                    frameEdge.push(offset[next]);
+                }
+                else if (onStack[next] === 1) {
+                    if (index[next] < low[node])
+                        low[node] = index[next];
+                }
+                continue;
+            }
+            frameNode.pop();
+            frameEdge.pop();
+            const parent = frameNode[frameNode.length - 1];
+            if (parent !== undefined && low[node] < low[parent])
+                low[parent] = low[node];
+            if (low[node] !== index[node])
+                continue;
+            const members = [];
+            for (;;) {
+                const member = pending.pop();
+                onStack[member] = 0;
+                component[member] = order.length;
+                members.push(member);
+                if (member === node)
+                    break;
+            }
+            order.push(members.sort((a, b) => a - b));
+        }
+    }
+    return { component, order };
+}
+/**
+ * The edge kinds a closure walks when the caller does not say.
+ *
+ * Listed rather than derived from `EDGE_KINDS`, and the difference is the whole
+ * point. A digest is a claim about *which inputs* were folded, so widening the
+ * fold silently changes every digest that exists — one added edge kind, and the
+ * next run finds nothing it can prove unchanged and re-observes the entire suite
+ * while reporting a successful narrowing. Adding a kind here is a decision with a
+ * cost, and it should read like one.
+ */
+export const CLOSURE_EDGES = [
+    'imports',
+    'reexports',
+    'dynamic',
+    'type',
+    'asset',
+    'declared-in',
+];
+/** Edge kinds as a lookup, so the inner loop tests a byte. */
+function allowedKinds(through) {
+    const allowed = new Uint8Array(EDGE_KINDS.length);
+    for (const kind of through ?? CLOSURE_EDGES) {
+        const at = EDGE_KINDS.indexOf(kind);
+        if (at !== -1)
+            allowed[at] = 1;
+    }
+    return allowed;
+}
+function byCodeUnit(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+//# sourceMappingURL=merkle.js.map

package/dist/relate/merkle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle.js","sourceRoot":"","sources":["../../src/relate/merkle.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The graph, hashed the way a build system hashes an action's inputs.\n *\n * Reachability answers *what could this diff have moved*. It needs a diff, which\n * means it needs `git`, a ref that exists, a checkout deep enough to contain it,\n * and the assumption that the ref is where this branch actually diverged. Every\n * one of those is a thing CI gets wrong, and each failure narrows a run.\n *\n * A Merkle digest asks a different question and needs none of them: **is this\n * subject's entire input closure byte-identical to the one that produced the\n * baseline?** One digest per node, over the node's own content and the digests of\n * everything it rests on — the same construction `bazel` uses to key an action,\n * and the same idea as this project's own content addressing, applied one level\n * out from the document to the source that produced it.\n *\n * What the difference buys:\n *\n * | situation | reachability | closure digest |\n * |---|---|---|\n * | a change, then a revert | both commits are in the diff, so it widens | identical digest, nothing runs |\n * | rebase, squash, branch switch | the merge base moves and the diff with it | unaffected — no ref is consulted |\n * | a shallow clone with no merge base | cannot answer; runs everything | unaffected |\n * | a dependency changed two hops away | reached, and observed | different digest, and observed |\n * | *why* a subject is being observed | a chain of files | a digest that differs |\n *\n * Neither replaces the other. The trail is the explanation, and the digest is the\n * proof; a run wants the digest to decide and the trail to justify.\n *\n * ## Cycles\n *\n * A dependency graph has them and a Merkle tree cannot. Strongly connected\n * components are condensed and hashed as a unit, so every file in a cycle carries\n * the same digest — which is exactly the truth about a cycle: no member of one can\n * be called unchanged while another moved.\n *\n * ## The digest that must never lie\n *\n * A digest says *these inputs are the same*. A file whose content was not supplied,\n * or whose own imports could not be read, breaks that claim — its closure may have\n * moved with no digest in this structure changing. Those nodes are marked\n * **volatile**, the mark propagates to everything that rests on them, and a\n * volatile node is treated as changed however its digest compares. A cache that\n * cannot be trusted must not be silently trusted.\n */\n\nimport { digestCombine, digestString, type Digest } from '../format/hash.js';\nimport {\n  EDGE_KINDS,\n  NODE_KINDS,\n  keyOf,\n  type EdgeKind,\n  type NodeId,\n  type Relations,\n} from './graph.js';\n\nexport interface ClosureInput {\n  readonly relations: Relations;\n\n  /**\n   * Content digest per file, keyed by the file's path.\n   *\n   * A file with no entry is volatile: nothing here can tell whether it moved.\n   * Component nodes take no entry — a component has no bytes of its own, and its\n   * content is the file that declares it, which it already depends on.\n   */\n  readonly content: ReadonlyMap<string, Digest>;\n\n  /** Restrict the closure to these edge kinds. Every kind by default. */\n  readonly through?: Iterable<EdgeKind>;\n}\n\nexport interface Closure {\n  /** `keyOf(kind, name)` → the digest of everything that node rests on. */\n  readonly digests: ReadonlyMap<string, Digest>;\n\n  /**\n   * Nodes whose digest cannot prove sameness, and everything resting on them.\n   *\n   * Not an error. It is the honest half of the answer, and a caller that ignores\n   * it converts a missing input into a subject nobody observed.\n   */\n  readonly volatile: ReadonlySet<string>;\n}\n\n/**\n * Hash every node over its own content and its whole dependency closure.\n *\n * One pass of Tarjan's algorithm and one pass over the components it emits, which\n * is `O(n + m)` — the same cost as the traversal next door, for an answer that\n * survives a rebase.\n */\nexport function closureOf(input: ClosureInput): Closure {\n  const { relations, content } = input;\n  const allowed = allowedKinds(input.through);\n  const count = relations.names.length;\n\n  const { component, order } = condense(relations, allowed);\n  const digests = new Map<string, Digest>();\n  const unstable = new Set<string>();\n\n  // One digest per component, so every member of a cycle carries the same one.\n  const byComponent: Digest[] = [];\n  const shakyComponent: boolean[] = [];\n\n  // Tarjan emits a component only after everything it can reach, so a dependency\n  // digest is always already computed by the time it is read here.\n  for (const [id, members] of order.entries()) {\n    const terms: string[] = [];\n    const outward = new Set<string>();\n    let shaky = false;\n\n    for (const node of members) {\n      const kind = NODE_KINDS[relations.kinds[node]!]!;\n      const name = relations.names[node]!;\n      const own = kind === 'file' ? content.get(name) : SETTLED;\n\n      if (own === undefined || relations.unknown[node] === 1) shaky = true;\n      terms.push(`${kind}\\u0000${name}\\u0000${own ?? UNREAD}`);\n\n      const { offset, target, kind: edgeKind } = relations.depends;\n      for (let at = offset[node]!; at < offset[node + 1]!; at += 1) {\n        if (allowed[edgeKind[at]!] !== 1) continue;\n\n        const other = target[at]!;\n        if (component[other] === id) continue;\n\n        outward.add(`${EDGE_KINDS[edgeKind[at]!]!}\\u0000${byComponent[component[other]!]!}`);\n        if (shakyComponent[component[other]!] === true) shaky = true;\n      }\n    }\n\n    byComponent.push(\n      digestCombine('relate.closure', [\n        digestString([...terms].sort(byCodeUnit).join('\u0001')),\n        digestString([...outward].sort(byCodeUnit).join('\u0001')),\n      ]),\n    );\n    shakyComponent.push(shaky);\n  }\n\n  for (let node = 0; node < count; node += 1) {\n    const key = keyOf(NODE_KINDS[relations.kinds[node]!]!, relations.names[node]!);\n    digests.set(key, byComponent[component[node]!]!);\n    if (shakyComponent[component[node]!] === true) unstable.add(key);\n  }\n\n  return { digests, volatile: unstable };\n}\n\n/** The term a node with content contributes when the content is not known. */\nconst UNREAD = '(unread)';\n\n/** The term a node that has no content of its own contributes. */\nconst SETTLED = '(declared)';\n\nexport interface Drift {\n  /** Node keys whose closure is not provably the one it was. */\n  readonly changed: readonly string[];\n  /** The file paths among them. */\n  readonly files: readonly string[];\n  /** The component names among them. */\n  readonly components: readonly string[];\n  /** Node keys the earlier closure held and this one does not. */\n  readonly gone: readonly string[];\n}\n\n/**\n * What moved between two closures, without consulting a repository.\n *\n * Three ways a node lands in `changed`, and only the first is a difference: its\n * digest differs, it is **new**, or it is **volatile** — the last because a node\n * whose inputs were not fully read has a digest that can match by accident, and a\n * selector that believed it would skip a subject on the strength of a hash over\n * bytes nobody hashed.\n */\nexport function driftedBetween(before: Closure, after: Closure): Drift {\n  const changed: string[] = [];\n\n  for (const [key, digest] of after.digests) {\n    const was = before.digests.get(key);\n    if (was === digest && !after.volatile.has(key) && !before.volatile.has(key)) continue;\n    changed.push(key);\n  }\n\n  const gone = [...before.digests.keys()].filter((key) => !after.digests.has(key));\n\n  return {\n    changed: changed.sort(byCodeUnit),\n    files: named(changed, 'file'),\n    components: named(changed, 'component'),\n    gone: gone.sort(byCodeUnit),\n  };\n}\n\nfunction named(keys: readonly string[], kind: 'file' | 'component'): readonly string[] {\n  const prefix = `${kind}:`;\n\n  return keys\n    .filter((key) => key.startsWith(prefix))\n    .map((key) => key.slice(prefix.length))\n    .sort(byCodeUnit);\n}\n\ninterface Condensation {\n  /** Component index per node. */\n  readonly component: Int32Array;\n  /** Components in emission order — every one after everything it reaches. */\n  readonly order: readonly (readonly NodeId[])[];\n}\n\n/**\n * Tarjan's strongly connected components, iteratively.\n *\n * Iterative because the recursion depth is the longest dependency chain in the\n * repository, and a deep monorepo would overflow a call stack on a structure whose\n * whole point is to be cheap. The emission order is the useful half: a component\n * appears only once everything it can reach has, which is the order a Merkle fold\n * needs and costs nothing extra to get.\n */\nfunction condense(relations: Relations, allowed: Uint8Array): Condensation {\n  const count = relations.names.length;\n  const { offset, target, kind } = relations.depends;\n\n  const index = new Int32Array(count).fill(-1);\n  const low = new Int32Array(count);\n  const onStack = new Uint8Array(count);\n  const component = new Int32Array(count).fill(-1);\n\n  const pending: NodeId[] = [];\n  const order: NodeId[][] = [];\n\n  // Frames as two parallel arrays: the node, and how far through its edges it is.\n  const frameNode: number[] = [];\n  const frameEdge: number[] = [];\n  let counter = 0;\n\n  for (let root = 0; root < count; root += 1) {\n    if (index[root] !== -1) continue;\n\n    index[root] = counter;\n    low[root] = counter;\n    counter += 1;\n    pending.push(root);\n    onStack[root] = 1;\n    frameNode.push(root);\n    frameEdge.push(offset[root]!);\n\n    while (frameNode.length > 0) {\n      const node = frameNode[frameNode.length - 1]!;\n      const at = frameEdge[frameEdge.length - 1]!;\n\n      if (at < offset[node + 1]!) {\n        frameEdge[frameEdge.length - 1] = at + 1;\n        if (allowed[kind[at]!] !== 1) continue;\n\n        const next = target[at]!;\n        if (index[next] === -1) {\n          index[next] = counter;\n          low[next] = counter;\n          counter += 1;\n          pending.push(next);\n          onStack[next] = 1;\n          frameNode.push(next);\n          frameEdge.push(offset[next]!);\n        } else if (onStack[next] === 1) {\n          if (index[next]! < low[node]!) low[node] = index[next]!;\n        }\n        continue;\n      }\n\n      frameNode.pop();\n      frameEdge.pop();\n\n      const parent = frameNode[frameNode.length - 1];\n      if (parent !== undefined && low[node]! < low[parent]!) low[parent] = low[node]!;\n\n      if (low[node] !== index[node]) continue;\n\n      const members: NodeId[] = [];\n      for (;;) {\n        const member = pending.pop()!;\n        onStack[member] = 0;\n        component[member] = order.length;\n        members.push(member);\n        if (member === node) break;\n      }\n      order.push(members.sort((a, b) => a - b));\n    }\n  }\n\n  return { component, order };\n}\n\n/**\n * The edge kinds a closure walks when the caller does not say.\n *\n * Listed rather than derived from `EDGE_KINDS`, and the difference is the whole\n * point. A digest is a claim about *which inputs* were folded, so widening the\n * fold silently changes every digest that exists — one added edge kind, and the\n * next run finds nothing it can prove unchanged and re-observes the entire suite\n * while reporting a successful narrowing. Adding a kind here is a decision with a\n * cost, and it should read like one.\n */\nexport const CLOSURE_EDGES: readonly EdgeKind[] = [\n  'imports',\n  'reexports',\n  'dynamic',\n  'type',\n  'asset',\n  'declared-in',\n];\n\n/** Edge kinds as a lookup, so the inner loop tests a byte. */\nfunction allowedKinds(through: Iterable<EdgeKind> | undefined): Uint8Array {\n  const allowed = new Uint8Array(EDGE_KINDS.length);\n\n  for (const kind of through ?? CLOSURE_EDGES) {\n    const at = EDGE_KINDS.indexOf(kind);\n    if (at !== -1) allowed[at] = 1;\n  }\n\n  return allowed;\n}\n\nfunction byCodeUnit(a: string, b: string): number {\n  return a < b ? -1 : a > b ? 1 : 0;\n}\n"]}

package/dist/relate/reach.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Walking the graph, and being able to say why the walk arrived.
+ *
+ * Two questions, one traversal each way:
+ *
+ * - **`dependentsOf`** — against the arrows. *What could this change have moved?*
+ *   This is the one selection asks, and it is asked once per run over the whole
+ *   seed set rather than once per seed, because a breadth-first search from many
+ *   sources costs the same as one from a single source.
+ * - **`dependenciesOf`** — along them. *What does this rest on?* The cache-key
+ *   question, and the one a reviewer asks about a file they have not read.
+ *
+ * ## The trail is not an extra
+ *
+ * Both return the path each node was reached by, and that is load-bearing rather
+ * than a convenience. A selector that says *observe 41 of 300* is asking to be
+ * trusted; a selector that says *`Button` is affected because
+ * `src/tokens.css` → `src/button.css` → `src/Button.tsx`* has shown its work, and
+ * the operator can see the edge that is wrong when one is.
+ *
+ * Recording it costs one `Int32Array` and nothing in the inner loop — the parent
+ * is written exactly where the visited mark already is.
+ *
+ * ## Cycles
+ *
+ * Import graphs have them, routinely and legitimately. Nothing here treats a
+ * cycle as an error: the visited mask means every node is expanded once, so a
+ * cycle terminates the same way any revisit does.
+ */
+import { type EdgeKind, type NodeId, type Relations } from './graph.js';
+export interface Reach {
+    /** `1` where the node was reached, including the seeds themselves. */
+    readonly mask: Uint8Array;
+    /**
+     * The node that reached each one, or `-1` for a seed and for anything
+     * unreached. Following it lands on a seed, which is what `trailOf` walks.
+     */
+    readonly via: Int32Array;
+    /** Reached nodes in id order, which is kind-major and then code unit. */
+    readonly reached: readonly NodeId[];
+}
+export interface ReachOptions {
+    /**
+     * Edge kinds to walk. Every kind, when absent.
+     *
+     * The default is deliberately the widest one. Narrowing here is how a caller
+     * says *a type-only import cannot have moved a pixel*, which is true and is
+     * still not the default, because the cost of being wrong about it is a green
+     * run over a surface nobody looked at.
+     */
+    readonly through?: Iterable<EdgeKind>;
+}
+/** What depends on these nodes, transitively. Against the arrows. */
+export declare function dependentsOf(relations: Relations, seeds: Iterable<NodeId>, options?: ReachOptions): Reach;
+/** What these nodes depend on, transitively. Along the arrows. */
+export declare function dependenciesOf(relations: Relations, seeds: Iterable<NodeId>, options?: ReachOptions): Reach;
+/**
+ * The chain from a reached node back to the seed that reached it.
+ *
+ * In arrival order — seed first, `id` last — because that is the direction the
+ * sentence reads: *the token file, then the stylesheet, then the component*.
+ * Empty when the node was never reached.
+ */
+export declare function trailOf(reach: Reach, id: NodeId): readonly NodeId[];
+//# sourceMappingURL=reach.d.ts.map

package/dist/relate/reach.js

@@ -0,0 +1,111 @@
+/**
+ * Walking the graph, and being able to say why the walk arrived.
+ *
+ * Two questions, one traversal each way:
+ *
+ * - **`dependentsOf`** — against the arrows. *What could this change have moved?*
+ *   This is the one selection asks, and it is asked once per run over the whole
+ *   seed set rather than once per seed, because a breadth-first search from many
+ *   sources costs the same as one from a single source.
+ * - **`dependenciesOf`** — along them. *What does this rest on?* The cache-key
+ *   question, and the one a reviewer asks about a file they have not read.
+ *
+ * ## The trail is not an extra
+ *
+ * Both return the path each node was reached by, and that is load-bearing rather
+ * than a convenience. A selector that says *observe 41 of 300* is asking to be
+ * trusted; a selector that says *`Button` is affected because
+ * `src/tokens.css` → `src/button.css` → `src/Button.tsx`* has shown its work, and
+ * the operator can see the edge that is wrong when one is.
+ *
+ * Recording it costs one `Int32Array` and nothing in the inner loop — the parent
+ * is written exactly where the visited mark already is.
+ *
+ * ## Cycles
+ *
+ * Import graphs have them, routinely and legitimately. Nothing here treats a
+ * cycle as an error: the visited mask means every node is expanded once, so a
+ * cycle terminates the same way any revisit does.
+ */
+import { EDGE_KINDS } from './graph.js';
+/** What depends on these nodes, transitively. Against the arrows. */
+export function dependentsOf(relations, seeds, options = {}) {
+    return search(relations.dependents, relations.names.length, seeds, options);
+}
+/** What these nodes depend on, transitively. Along the arrows. */
+export function dependenciesOf(relations, seeds, options = {}) {
+    return search(relations.depends, relations.names.length, seeds, options);
+}
+/**
+ * The chain from a reached node back to the seed that reached it.
+ *
+ * In arrival order — seed first, `id` last — because that is the direction the
+ * sentence reads: *the token file, then the stylesheet, then the component*.
+ * Empty when the node was never reached.
+ */
+export function trailOf(reach, id) {
+    if (reach.mask[id] !== 1)
+        return [];
+    const trail = [];
+    for (let at = id; at !== -1; at = reach.via[at])
+        trail.push(at);
+    return trail.reverse();
+}
+/**
+ * Breadth-first over one direction, from every seed at once.
+ *
+ * A plain array as the queue with a moving head rather than `shift()`, which is
+ * `O(n)` per call in every engine that does not special-case it and turns a
+ * linear traversal quadratic on the graphs this exists for.
+ *
+ * Breadth-first rather than depth-first for the trail's sake: the parent
+ * recorded is then the one on a *shortest* path, so the explanation a run prints
+ * is the shortest true one rather than whichever the stack happened to unwind.
+ */
+function search(adjacency, nodes, seeds, options) {
+    const mask = new Uint8Array(nodes);
+    const via = new Int32Array(nodes).fill(-1);
+    const queue = [];
+    for (const seed of seeds) {
+        if (seed < 0 || seed >= nodes || mask[seed] === 1)
+            continue;
+        mask[seed] = 1;
+        queue.push(seed);
+    }
+    const allowed = allowedKinds(options.through);
+    for (let head = 0; head < queue.length; head += 1) {
+        const node = queue[head];
+        const end = adjacency.offset[node + 1];
+        for (let at = adjacency.offset[node]; at < end; at += 1) {
+            if (allowed !== undefined && allowed[adjacency.kind[at]] !== 1)
+                continue;
+            const next = adjacency.target[at];
+            if (mask[next] === 1)
+                continue;
+            mask[next] = 1;
+            via[next] = node;
+            queue.push(next);
+        }
+    }
+    // `queue` is in visit order, which depends on seed order. The result is in id
+    // order instead, so a report built from it is byte-stable whatever order the
+    // caller listed its changed files in.
+    const reached = [];
+    for (let id = 0; id < nodes; id += 1)
+        if (mask[id] === 1)
+            reached.push(id);
+    return { mask, via, reached };
+}
+/** A kind filter as a byte lookup, or `undefined` when every kind is walked. */
+function allowedKinds(through) {
+    if (through === undefined)
+        return undefined;
+    const allowed = new Uint8Array(EDGE_KINDS.length);
+    for (const kind of through) {
+        const at = EDGE_KINDS.indexOf(kind);
+        if (at !== -1)
+            allowed[at] = 1;
+    }
+    return allowed;
+}
+//# sourceMappingURL=reach.js.map

package/dist/relate/reach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reach.js","sourceRoot":"","sources":["../../src/relate/reach.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Walking the graph, and being able to say why the walk arrived.\n *\n * Two questions, one traversal each way:\n *\n * - **`dependentsOf`** — against the arrows. *What could this change have moved?*\n *   This is the one selection asks, and it is asked once per run over the whole\n *   seed set rather than once per seed, because a breadth-first search from many\n *   sources costs the same as one from a single source.\n * - **`dependenciesOf`** — along them. *What does this rest on?* The cache-key\n *   question, and the one a reviewer asks about a file they have not read.\n *\n * ## The trail is not an extra\n *\n * Both return the path each node was reached by, and that is load-bearing rather\n * than a convenience. A selector that says *observe 41 of 300* is asking to be\n * trusted; a selector that says *`Button` is affected because\n * `src/tokens.css` → `src/button.css` → `src/Button.tsx`* has shown its work, and\n * the operator can see the edge that is wrong when one is.\n *\n * Recording it costs one `Int32Array` and nothing in the inner loop — the parent\n * is written exactly where the visited mark already is.\n *\n * ## Cycles\n *\n * Import graphs have them, routinely and legitimately. Nothing here treats a\n * cycle as an error: the visited mask means every node is expanded once, so a\n * cycle terminates the same way any revisit does.\n */\n\nimport { EDGE_KINDS, type Adjacency, type EdgeKind, type NodeId, type Relations } from './graph.js';\n\nexport interface Reach {\n  /** `1` where the node was reached, including the seeds themselves. */\n  readonly mask: Uint8Array;\n  /**\n   * The node that reached each one, or `-1` for a seed and for anything\n   * unreached. Following it lands on a seed, which is what `trailOf` walks.\n   */\n  readonly via: Int32Array;\n  /** Reached nodes in id order, which is kind-major and then code unit. */\n  readonly reached: readonly NodeId[];\n}\n\nexport interface ReachOptions {\n  /**\n   * Edge kinds to walk. Every kind, when absent.\n   *\n   * The default is deliberately the widest one. Narrowing here is how a caller\n   * says *a type-only import cannot have moved a pixel*, which is true and is\n   * still not the default, because the cost of being wrong about it is a green\n   * run over a surface nobody looked at.\n   */\n  readonly through?: Iterable<EdgeKind>;\n}\n\n/** What depends on these nodes, transitively. Against the arrows. */\nexport function dependentsOf(\n  relations: Relations,\n  seeds: Iterable<NodeId>,\n  options: ReachOptions = {},\n): Reach {\n  return search(relations.dependents, relations.names.length, seeds, options);\n}\n\n/** What these nodes depend on, transitively. Along the arrows. */\nexport function dependenciesOf(\n  relations: Relations,\n  seeds: Iterable<NodeId>,\n  options: ReachOptions = {},\n): Reach {\n  return search(relations.depends, relations.names.length, seeds, options);\n}\n\n/**\n * The chain from a reached node back to the seed that reached it.\n *\n * In arrival order — seed first, `id` last — because that is the direction the\n * sentence reads: *the token file, then the stylesheet, then the component*.\n * Empty when the node was never reached.\n */\nexport function trailOf(reach: Reach, id: NodeId): readonly NodeId[] {\n  if (reach.mask[id] !== 1) return [];\n\n  const trail: NodeId[] = [];\n  for (let at: number = id; at !== -1; at = reach.via[at]!) trail.push(at);\n  return trail.reverse();\n}\n\n/**\n * Breadth-first over one direction, from every seed at once.\n *\n * A plain array as the queue with a moving head rather than `shift()`, which is\n * `O(n)` per call in every engine that does not special-case it and turns a\n * linear traversal quadratic on the graphs this exists for.\n *\n * Breadth-first rather than depth-first for the trail's sake: the parent\n * recorded is then the one on a *shortest* path, so the explanation a run prints\n * is the shortest true one rather than whichever the stack happened to unwind.\n */\nfunction search(\n  adjacency: Adjacency,\n  nodes: number,\n  seeds: Iterable<NodeId>,\n  options: ReachOptions,\n): Reach {\n  const mask = new Uint8Array(nodes);\n  const via = new Int32Array(nodes).fill(-1);\n  const queue: NodeId[] = [];\n\n  for (const seed of seeds) {\n    if (seed < 0 || seed >= nodes || mask[seed] === 1) continue;\n    mask[seed] = 1;\n    queue.push(seed);\n  }\n\n  const allowed = allowedKinds(options.through);\n\n  for (let head = 0; head < queue.length; head += 1) {\n    const node = queue[head]!;\n    const end = adjacency.offset[node + 1]!;\n\n    for (let at = adjacency.offset[node]!; at < end; at += 1) {\n      if (allowed !== undefined && allowed[adjacency.kind[at]!] !== 1) continue;\n\n      const next = adjacency.target[at]!;\n      if (mask[next] === 1) continue;\n\n      mask[next] = 1;\n      via[next] = node;\n      queue.push(next);\n    }\n  }\n\n  // `queue` is in visit order, which depends on seed order. The result is in id\n  // order instead, so a report built from it is byte-stable whatever order the\n  // caller listed its changed files in.\n  const reached: NodeId[] = [];\n  for (let id = 0; id < nodes; id += 1) if (mask[id] === 1) reached.push(id);\n\n  return { mask, via, reached };\n}\n\n/** A kind filter as a byte lookup, or `undefined` when every kind is walked. */\nfunction allowedKinds(through: Iterable<EdgeKind> | undefined): Uint8Array | undefined {\n  if (through === undefined) return undefined;\n\n  const allowed = new Uint8Array(EDGE_KINDS.length);\n  for (const kind of through) {\n    const at = EDGE_KINDS.indexOf(kind);\n    if (at !== -1) allowed[at] = 1;\n  }\n  return allowed;\n}\n"]}

package/dist/relate/records.d.ts

@@ -0,0 +1,129 @@
+/**
+ * One file's outgoing edges, and the fold that turns a pile of them into a graph.
+ *
+ * A record is what reading **one** file produced, and that is the unit on
+ * purpose. It makes the expensive half — open, parse, resolve — cacheable by
+ * content digest and parallelizable per file, and it leaves the graph a pure
+ * function of the records, so the structure can be rebuilt, sharded or merged
+ * without touching a disk. `core` performs no I/O (ADR-0006); whoever owns the
+ * disk produces these and hands them over.
+ *
+ * ## An empty record and an unreadable one are different facts
+ *
+ * A file with no imports and a file nothing could parse both produce a record
+ * with no edges, and treating them alike is the one mistake that turns this from
+ * a saving into a silent hole: the second one may import anything, including
+ * whatever just changed. So `unknown` carries the *reason* the edges are not
+ * known, and every consumer seeds its traversal with those files (ADR-0002 —
+ * absent is not empty, and here absent is not even absent, it is *unread*).
+ */
+import type { Digest } from '../format/hash.js';
+import { type EdgeKind, type Node, type Relations } from './graph.js';
+import { type Reach } from './reach.js';
+export interface FileEdge {
+    /** Repository-relative, already resolved. A specifier is not an edge. */
+    readonly to: string;
+    readonly kind: EdgeKind;
+}
+export interface FileRecord {
+    /** Repository-relative, so a graph is portable between machines and CI. */
+    readonly file: string;
+    /**
+     * The content digest this record was read from.
+     *
+     * Two jobs. It lets a second scan skip the parse for a file that has not moved,
+     * which is the difference between a scan that costs a second and one nobody
+     * leaves enabled. And it is the leaf of the Merkle fold in
+     * [`merkle.ts`](./merkle.ts) — a file with no digest is one nothing can prove
+     * unchanged, and is marked as such rather than assumed still.
+     */
+    readonly digest?: Digest;
+    /** Resolved outgoing edges. Absent and empty mean the same thing here. */
+    readonly edges?: readonly FileEdge[];
+    /** Component names this file declares, from `indexSource` or better. */
+    readonly declares?: readonly string[];
+    /**
+     * Specifiers that were read but did not resolve.
+     *
+     * Kept for the report rather than for the graph. A bare specifier that failed
+     * to resolve is usually a package that is not installed; a **relative** one
+     * that failed is a hole, and whoever produced the record says so by also
+     * setting `unknown`.
+     */
+    readonly unresolved?: readonly string[];
+    /**
+     * Why this file's outgoing edges could not be enumerated, when they could not.
+     *
+     * Present means *this file may depend on anything*. The sentence is carried
+     * rather than a flag, because it ends up in the paragraph explaining why a run
+     * observed more than the operator expected.
+     */
+    readonly unknown?: string;
+}
+/**
+ * Fold file records into the graph.
+ *
+ * Every record contributes its own node even when it has no edges, so a changed
+ * file that imports nothing is still findable — otherwise the one file in the
+ * diff would be missing from the structure that exists to answer questions about
+ * it.
+ *
+ * A declaration becomes an edge from the **component to the file**, which is the
+ * direction the convention requires: the component depends on the file that
+ * declares it, so one walk against the arrows from a changed file reaches every
+ * importer and every component in the same pass.
+ */
+export declare function relationsOfFiles(records: Iterable<FileRecord>): Relations;
+export interface Hole {
+    /** The file whose outgoing edges could not be enumerated. */
+    readonly file: string;
+    /** Why, in the words of whoever read it. Absent when nobody said. */
+    readonly because?: string;
+}
+export interface Reached {
+    /** Files the change could have moved, including the changed files themselves. */
+    readonly files: readonly string[];
+    /** Components declared in any of them. */
+    readonly components: readonly string[];
+    /**
+     * Changed paths the graph does not hold.
+     *
+     * Never silently ignored. A `README.md` belongs here and means nothing; a
+     * source file belongs here only because the scan never reached it, and the
+     * caller — which knows where it told the scan to look — is the one that can
+     * tell those apart.
+     */
+    readonly missing: readonly string[];
+    /**
+     * Files seeded because their own edges are unknown, rather than because
+     * anything reached them, each with the reason it could not be read.
+     *
+     * Counted separately so that "we widened" never hides inside "we found", and
+     * carrying its sentence so the widening is a work item rather than a tax: *four
+     * files could not be read* is something to live with, and ``src/legacy.js — a
+     * computed require()`` is something to fix.
+     */
+    readonly opaque: readonly Hole[];
+    /** The traversal, kept so a caller can ask how any one file was reached. */
+    readonly reach: Reach;
+}
+/**
+ * What a set of changed files could have moved.
+ *
+ * The seed set is the changed files **and every file whose edges are unknown**,
+ * which is the rule the whole structure rests on. An unreadable file might import
+ * the one that changed; seeding it means everything depending on *it* is observed
+ * too, and the cost is a collection rather than a green run over an unwatched
+ * surface.
+ *
+ * One breadth-first search, whatever the number of changed files.
+ */
+export declare function movedBy(relations: Relations, changed: Iterable<string>): Reached;
+/**
+ * How one file or component was reached, as the chain that reached it.
+ *
+ * The sentence a run prints when somebody asks why a subject was observed. Empty
+ * when the node was not reached at all.
+ */
+export declare function explain(relations: Relations, moved: Reached, node: Node): readonly string[];
+//# sourceMappingURL=records.d.ts.map