@variance-authority/core 0.1.0

package/dist/relate/graph.js

@@ -0,0 +1,234 @@
+/**
+ * What reaches what, stored so that asking is cheap.
+ *
+ * Every question this project asks about a change is a reachability question. A
+ * diff names files; a subject is made of components; a component is declared in a
+ * file that imports other files. *Which subjects could this diff have changed* is
+ * one traversal of one graph, and the only reason it is not asked that way today
+ * is that there has never been a graph to traverse.
+ *
+ * ## Why a structure rather than a `Map`
+ *
+ * The obvious shape is `Map<string, string[]>`, and it is wrong at the size this
+ * runs at. A monorepo scan produces tens of thousands of files and several times
+ * as many edges; the map holds one array object and one string copy per edge, and
+ * a traversal chases a pointer for every step. What replaces it here is the
+ * standard answer, and it is standard because nothing has beaten it:
+ *
+ * - **strings are interned once.** A node is an integer. Comparison is an integer
+ *   compare, membership is an index into a byte array, and a visited set is a
+ *   `Uint8Array` rather than a `Set<string>`.
+ * - **edges are two typed arrays** in compressed-sparse-row form: `offset` says
+ *   where a node's row starts, `target` holds the rows end to end. One node's
+ *   edges are contiguous, so a traversal walks memory forwards instead of
+ *   following pointers into the heap.
+ * - **both directions are materialized.** *What does this depend on* and *what
+ *   depends on this* are different questions, and a graph answering only the
+ *   first makes the second a whole-graph scan. The transpose is a counting sort —
+ *   one pass to count, one to place — so holding it costs `O(n + m)` once instead
+ *   of `O(n + m)` per query.
+ *
+ * ## Edges point at what a thing depends on
+ *
+ * One convention, held everywhere: **`A → B` means A depends on B**, so a change
+ * in B may move A. Every affected-set question is therefore a walk against the
+ * arrows, which is what `dependentsOf` does, and every *what would I have to read
+ * to understand this* question is a walk along them.
+ *
+ * It decides the direction of the less obvious edges too. A component is
+ * `declared-in` the file that declares it — the component depends on the file and
+ * not the other way round — so editing that file reaches the component in the
+ * same traversal that reaches every importer.
+ *
+ * ## Nodes are typed, because files are not the last kind
+ *
+ * This ships with two kinds and the join between them: a `file` graph built from
+ * imports, and the `component` nodes the source index already knows how to find.
+ * That is deliberate rather than incidental. A component relation — *`TodoFooter`
+ * renders `Chip`* — is another edge kind between nodes of another kind in this
+ * same structure, and
+ * [`composition.md`](../../../../docs/composition.md) already computes exactly
+ * that relation from what a run rendered. One graph means the static answer and
+ * the rendered answer are joinable rather than adjacent.
+ *
+ * ## What it is not
+ *
+ * **Not a build graph.** It has no notion of a task, an output or a cache key,
+ * and it does not know what an install produced. `nx` and `turbo` own that layer,
+ * and what reads them reads their answer rather than competing with it.
+ *
+ * **Not a resolver.** Nothing here opens a file or knows what a specifier means.
+ * `core` performs no I/O (ADR-0006); the records this folds are somebody else's
+ * disk.
+ */
+/** Node kinds, in id order. An id is an index into this, never the word. */
+export const NODE_KINDS = ['file', 'component'];
+/**
+ * Edge kinds, in id order.
+ *
+ * The distinctions are kept because they explain a finding, not because the
+ * default traversal narrows on them. `type` is erased by every compiler and can
+ * change no rendering, and it is still walked unless a caller says otherwise —
+ * for the reason every rule in selection resolves the same way: a subject skipped
+ * in error is a green run over an unwatched surface, and a subject observed in
+ * error costs a collection.
+ */
+export const EDGE_KINDS = [
+    /** `import x from './y'` — a value import. */
+    'imports',
+    /** `export … from './y'` — an import that also republishes. */
+    'reexports',
+    /** `import('./y')`, with a specifier that was a literal. */
+    'dynamic',
+    /** `import type { T } from './y'` — erased before anything renders. */
+    'type',
+    /** A stylesheet's `@import`, or a `url()` reaching a font or an image. */
+    'asset',
+    /** A component to the file that declares it. */
+    'declared-in',
+];
+/**
+ * The lookup key for a node.
+ *
+ * Runtime only; nothing serializes this, and no code parses it back — the
+ * separator only has to be injective, and it is, because a kind is one of two
+ * fixed words and neither contains a `:`. A name that contains one is therefore
+ * fine.
+ *
+ * The obvious separator is a NUL, and it is the wrong one: a source file
+ * carrying that byte stops being text to `grep`, `file` and `git diff`, which is
+ * a search finding nothing looking exactly like a search that returned nothing.
+ * `tools/boundaries.check.ts` fails a build over it.
+ */
+export function keyOf(kind, name) {
+    return `${kind}:${name}`;
+}
+export function idOf(relations, kind, name) {
+    return relations.index.get(keyOf(kind, name));
+}
+export function nodeAt(relations, id) {
+    const name = relations.names[id];
+    if (name === undefined)
+        return undefined;
+    return { kind: NODE_KINDS[relations.kinds[id]], name };
+}
+/** Every node of one kind, as ids. Contiguous, because the order is kind-major. */
+export function nodesOfKind(relations, kind) {
+    const wanted = NODE_KINDS.indexOf(kind);
+    const found = [];
+    for (let id = 0; id < relations.kinds.length; id += 1) {
+        if (relations.kinds[id] === wanted)
+            found.push(id);
+    }
+    return found;
+}
+/**
+ * Fold relations into the queryable form.
+ *
+ * Deterministic to the byte: nodes are ordered by kind and then by **code unit** —
+ * never `localeCompare`, which would make an id a promise about `LANG` — and edges
+ * are sorted and deduplicated, so two runs over the same records produce identical
+ * arrays and a serialized graph is stable.
+ *
+ * `O(n log n + m log m)` for the two sorts and `O(n + m)` for everything else. The
+ * transpose is a counting sort rather than a second pass over a map, which is why
+ * both directions cost one build instead of one per query.
+ */
+export function relationsOf(input) {
+    const relations = [...input.relations];
+    const unknownNodes = [...(input.unknown ?? [])].map((entry) => Array.isArray(entry) ? entry : [entry, undefined]);
+    const seen = new Map();
+    const see = (node) => {
+        const key = keyOf(node.kind, node.name);
+        if (!seen.has(key))
+            seen.set(key, node);
+    };
+    for (const relation of relations) {
+        see(relation.from);
+        see(relation.to);
+    }
+    for (const [node] of unknownNodes)
+        see(node);
+    for (const node of input.isolated ?? [])
+        see(node);
+    // Kind-major, then code unit. Kind-major keeps one kind's nodes contiguous,
+    // which is what lets a caller filter to files without touching a string.
+    const ordered = [...seen.values()].sort((a, b) => NODE_KINDS.indexOf(a.kind) - NODE_KINDS.indexOf(b.kind) ||
+        (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const index = new Map();
+    const names = Array.from({ length: ordered.length });
+    const kinds = new Uint8Array(ordered.length);
+    for (const [id, node] of ordered.entries()) {
+        index.set(keyOf(node.kind, node.name), id);
+        names[id] = node.name;
+        kinds[id] = NODE_KINDS.indexOf(node.kind);
+    }
+    const edges = sortedEdges(relations, index);
+    const depends = adjacencyOf(edges, ordered.length, 'from');
+    const dependents = adjacencyOf(edges, ordered.length, 'to');
+    const unknown = new Uint8Array(ordered.length);
+    const reasons = new Map();
+    for (const [node, because] of unknownNodes) {
+        const id = index.get(keyOf(node.kind, node.name));
+        if (id === undefined)
+            continue;
+        unknown[id] = 1;
+        if (because !== undefined)
+            reasons.set(id, because);
+    }
+    return { names, kinds, depends, dependents, unknown, reasons, index };
+}
+/**
+ * Edges as ids, sorted and deduplicated.
+ *
+ * Sorting the whole list once is what makes every row of *both* adjacencies
+ * sorted without sorting any row: each fill walks the list in order, so a row
+ * receives its targets in order. Two files related twice — a value import and a
+ * type import — stay two edges, because the kinds differ and one of them explains
+ * a finding the other does not.
+ */
+function sortedEdges(relations, index) {
+    const edges = [];
+    for (const relation of relations) {
+        const from = index.get(keyOf(relation.from.kind, relation.from.name));
+        const to = index.get(keyOf(relation.to.kind, relation.to.name));
+        if (from === undefined || to === undefined)
+            continue;
+        edges.push({ from, to, kind: EDGE_KINDS.indexOf(relation.kind) });
+    }
+    edges.sort((a, b) => a.from - b.from || a.to - b.to || a.kind - b.kind);
+    const unique = [];
+    for (const edge of edges) {
+        const last = unique[unique.length - 1];
+        const same = last !== undefined && last.from === edge.from && last.to === edge.to && last.kind === edge.kind;
+        if (!same)
+            unique.push(edge);
+    }
+    return unique;
+}
+/**
+ * One direction, by counting sort.
+ *
+ * `by` names the endpoint a row is keyed on: `from` produces *what this depends
+ * on*, `to` produces the transpose. Two passes — count the degrees, then place —
+ * and no per-node array is ever allocated.
+ */
+function adjacencyOf(edges, nodes, by) {
+    const offset = new Uint32Array(nodes + 1);
+    for (const edge of edges)
+        offset[edge[by] + 1] = offset[edge[by] + 1] + 1;
+    for (let id = 0; id < nodes; id += 1)
+        offset[id + 1] = offset[id + 1] + offset[id];
+    const target = new Uint32Array(edges.length);
+    const kind = new Uint8Array(edges.length);
+    const cursor = Uint32Array.from(offset.subarray(0, nodes));
+    for (const edge of edges) {
+        const row = edge[by];
+        const at = cursor[row];
+        target[at] = by === 'from' ? edge.to : edge.from;
+        kind[at] = edge.kind;
+        cursor[row] = at + 1;
+    }
+    return { offset, target, kind };
+}
+//# sourceMappingURL=graph.js.map

package/dist/relate/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../src/relate/graph.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What reaches what, stored so that asking is cheap.\n *\n * Every question this project asks about a change is a reachability question. A\n * diff names files; a subject is made of components; a component is declared in a\n * file that imports other files. *Which subjects could this diff have changed* is\n * one traversal of one graph, and the only reason it is not asked that way today\n * is that there has never been a graph to traverse.\n *\n * ## Why a structure rather than a `Map`\n *\n * The obvious shape is `Map<string, string[]>`, and it is wrong at the size this\n * runs at. A monorepo scan produces tens of thousands of files and several times\n * as many edges; the map holds one array object and one string copy per edge, and\n * a traversal chases a pointer for every step. What replaces it here is the\n * standard answer, and it is standard because nothing has beaten it:\n *\n * - **strings are interned once.** A node is an integer. Comparison is an integer\n *   compare, membership is an index into a byte array, and a visited set is a\n *   `Uint8Array` rather than a `Set<string>`.\n * - **edges are two typed arrays** in compressed-sparse-row form: `offset` says\n *   where a node's row starts, `target` holds the rows end to end. One node's\n *   edges are contiguous, so a traversal walks memory forwards instead of\n *   following pointers into the heap.\n * - **both directions are materialized.** *What does this depend on* and *what\n *   depends on this* are different questions, and a graph answering only the\n *   first makes the second a whole-graph scan. The transpose is a counting sort —\n *   one pass to count, one to place — so holding it costs `O(n + m)` once instead\n *   of `O(n + m)` per query.\n *\n * ## Edges point at what a thing depends on\n *\n * One convention, held everywhere: **`A → B` means A depends on B**, so a change\n * in B may move A. Every affected-set question is therefore a walk against the\n * arrows, which is what `dependentsOf` does, and every *what would I have to read\n * to understand this* question is a walk along them.\n *\n * It decides the direction of the less obvious edges too. A component is\n * `declared-in` the file that declares it — the component depends on the file and\n * not the other way round — so editing that file reaches the component in the\n * same traversal that reaches every importer.\n *\n * ## Nodes are typed, because files are not the last kind\n *\n * This ships with two kinds and the join between them: a `file` graph built from\n * imports, and the `component` nodes the source index already knows how to find.\n * That is deliberate rather than incidental. A component relation — *`TodoFooter`\n * renders `Chip`* — is another edge kind between nodes of another kind in this\n * same structure, and\n * [`composition.md`](../../../../docs/composition.md) already computes exactly\n * that relation from what a run rendered. One graph means the static answer and\n * the rendered answer are joinable rather than adjacent.\n *\n * ## What it is not\n *\n * **Not a build graph.** It has no notion of a task, an output or a cache key,\n * and it does not know what an install produced. `nx` and `turbo` own that layer,\n * and what reads them reads their answer rather than competing with it.\n *\n * **Not a resolver.** Nothing here opens a file or knows what a specifier means.\n * `core` performs no I/O (ADR-0006); the records this folds are somebody else's\n * disk.\n */\n\n/** Node kinds, in id order. An id is an index into this, never the word. */\nexport const NODE_KINDS = ['file', 'component'] as const;\nexport type NodeKind = (typeof NODE_KINDS)[number];\n\n/**\n * Edge kinds, in id order.\n *\n * The distinctions are kept because they explain a finding, not because the\n * default traversal narrows on them. `type` is erased by every compiler and can\n * change no rendering, and it is still walked unless a caller says otherwise —\n * for the reason every rule in selection resolves the same way: a subject skipped\n * in error is a green run over an unwatched surface, and a subject observed in\n * error costs a collection.\n */\nexport const EDGE_KINDS = [\n  /** `import x from './y'` — a value import. */\n  'imports',\n  /** `export … from './y'` — an import that also republishes. */\n  'reexports',\n  /** `import('./y')`, with a specifier that was a literal. */\n  'dynamic',\n  /** `import type { T } from './y'` — erased before anything renders. */\n  'type',\n  /** A stylesheet's `@import`, or a `url()` reaching a font or an image. */\n  'asset',\n  /** A component to the file that declares it. */\n  'declared-in',\n] as const;\nexport type EdgeKind = (typeof EDGE_KINDS)[number];\n\nexport interface Node {\n  readonly kind: NodeKind;\n  /** Repository-relative for a file; the identifier for a component. */\n  readonly name: string;\n}\n\nexport interface Relation {\n  readonly from: Node;\n  readonly to: Node;\n  readonly kind: EdgeKind;\n}\n\n/** An index into `Relations.names`. Valid only against the graph it came from. */\nexport type NodeId = number;\n\n/**\n * One direction of the edge set, compressed-sparse-row.\n *\n * Node `i`'s edges are `target[offset[i] … offset[i + 1])`, and `kind[j]`\n * describes `target[j]`. `offset` holds one more entry than there are nodes, so\n * the last row needs no special case.\n */\nexport interface Adjacency {\n  readonly offset: Uint32Array;\n  readonly target: Uint32Array;\n  readonly kind: Uint8Array;\n}\n\nexport interface Relations {\n  /** Node names by id, ordered by kind and then by code unit. */\n  readonly names: readonly string[];\n  /** The `NODE_KINDS` index of each node. */\n  readonly kinds: Uint8Array;\n\n  /** What each node depends on. */\n  readonly depends: Adjacency;\n  /** What depends on each node — the transpose, materialized. */\n  readonly dependents: Adjacency;\n\n  /**\n   * `1` where this node's outgoing edges could not be enumerated.\n   *\n   * A parse failure, a specifier that was not a literal, a file in a language\n   * nothing here reads. It is *not* \"this file has no dependencies\", and the\n   * difference is the whole safety argument: a file whose edges are unknown may\n   * depend on anything that changed, so selection seeds the traversal with every\n   * one of them (ADR-0002 — absent is not empty).\n   */\n  readonly unknown: Uint8Array;\n\n  /**\n   * Why, for each of those nodes, in the words whoever read the file used.\n   *\n   * Sparse — a repository the scan understands carries none of these — and kept\n   * apart from the mask because the mask is what the inner loop tests and this is\n   * what an operator reads. Without it, a run that observed forty subjects instead\n   * of twelve can say *because eight files could not be read* and can never say\n   * **which**, which is the difference between a fact and a work item.\n   */\n  readonly reasons: ReadonlyMap<NodeId, string>;\n\n  /** `keyOf` to id — the interning table, kept for lookup. */\n  readonly index: ReadonlyMap<string, NodeId>;\n}\n\n/**\n * The lookup key for a node.\n *\n * Runtime only; nothing serializes this, and no code parses it back — the\n * separator only has to be injective, and it is, because a kind is one of two\n * fixed words and neither contains a `:`. A name that contains one is therefore\n * fine.\n *\n * The obvious separator is a NUL, and it is the wrong one: a source file\n * carrying that byte stops being text to `grep`, `file` and `git diff`, which is\n * a search finding nothing looking exactly like a search that returned nothing.\n * `tools/boundaries.check.ts` fails a build over it.\n */\nexport function keyOf(kind: NodeKind, name: string): string {\n  return `${kind}:${name}`;\n}\n\nexport function idOf(relations: Relations, kind: NodeKind, name: string): NodeId | undefined {\n  return relations.index.get(keyOf(kind, name));\n}\n\nexport function nodeAt(relations: Relations, id: NodeId): Node | undefined {\n  const name = relations.names[id];\n  if (name === undefined) return undefined;\n  return { kind: NODE_KINDS[relations.kinds[id]!]!, name };\n}\n\n/** Every node of one kind, as ids. Contiguous, because the order is kind-major. */\nexport function nodesOfKind(relations: Relations, kind: NodeKind): readonly NodeId[] {\n  const wanted = NODE_KINDS.indexOf(kind);\n  const found: NodeId[] = [];\n  for (let id = 0; id < relations.kinds.length; id += 1) {\n    if (relations.kinds[id] === wanted) found.push(id);\n  }\n  return found;\n}\n\n/**\n * Fold relations into the queryable form.\n *\n * Deterministic to the byte: nodes are ordered by kind and then by **code unit** —\n * never `localeCompare`, which would make an id a promise about `LANG` — and edges\n * are sorted and deduplicated, so two runs over the same records produce identical\n * arrays and a serialized graph is stable.\n *\n * `O(n log n + m log m)` for the two sorts and `O(n + m)` for everything else. The\n * transpose is a counting sort rather than a second pass over a map, which is why\n * both directions cost one build instead of one per query.\n */\nexport function relationsOf(input: {\n  readonly relations: Iterable<Relation>;\n  /**\n   * Nodes whose outgoing edges are not fully known, and must be treated as such.\n   *\n   * A bare node says *this one is blind*. A pair says why, in whatever words the\n   * reader of the file used — and the sentence is the half an operator can act on,\n   * so it travels with the fact rather than being reconstructed from it.\n   */\n  readonly unknown?: Iterable<Node | readonly [Node, string]>;\n  /** Nodes with no edges at all, which would otherwise be absent from the graph. */\n  readonly isolated?: Iterable<Node>;\n}): Relations {\n  const relations = [...input.relations];\n  const unknownNodes = [...(input.unknown ?? [])].map((entry) =>\n    Array.isArray(entry) ? entry : ([entry, undefined] as const),\n  ) as readonly (readonly [Node, string | undefined])[];\n\n  const seen = new Map<string, Node>();\n  const see = (node: Node): void => {\n    const key = keyOf(node.kind, node.name);\n    if (!seen.has(key)) seen.set(key, node);\n  };\n\n  for (const relation of relations) {\n    see(relation.from);\n    see(relation.to);\n  }\n  for (const [node] of unknownNodes) see(node);\n  for (const node of input.isolated ?? []) see(node);\n\n  // Kind-major, then code unit. Kind-major keeps one kind's nodes contiguous,\n  // which is what lets a caller filter to files without touching a string.\n  const ordered = [...seen.values()].sort(\n    (a, b) =>\n      NODE_KINDS.indexOf(a.kind) - NODE_KINDS.indexOf(b.kind) ||\n      (a.name < b.name ? -1 : a.name > b.name ? 1 : 0),\n  );\n\n  const index = new Map<string, NodeId>();\n  const names: string[] = Array.from<string>({ length: ordered.length });\n  const kinds = new Uint8Array(ordered.length);\n\n  for (const [id, node] of ordered.entries()) {\n    index.set(keyOf(node.kind, node.name), id);\n    names[id] = node.name;\n    kinds[id] = NODE_KINDS.indexOf(node.kind);\n  }\n\n  const edges = sortedEdges(relations, index);\n  const depends = adjacencyOf(edges, ordered.length, 'from');\n  const dependents = adjacencyOf(edges, ordered.length, 'to');\n\n  const unknown = new Uint8Array(ordered.length);\n  const reasons = new Map<NodeId, string>();\n  for (const [node, because] of unknownNodes) {\n    const id = index.get(keyOf(node.kind, node.name));\n    if (id === undefined) continue;\n\n    unknown[id] = 1;\n    if (because !== undefined) reasons.set(id, because);\n  }\n\n  return { names, kinds, depends, dependents, unknown, reasons, index };\n}\n\ninterface Edge {\n  readonly from: NodeId;\n  readonly to: NodeId;\n  readonly kind: number;\n}\n\n/**\n * Edges as ids, sorted and deduplicated.\n *\n * Sorting the whole list once is what makes every row of *both* adjacencies\n * sorted without sorting any row: each fill walks the list in order, so a row\n * receives its targets in order. Two files related twice — a value import and a\n * type import — stay two edges, because the kinds differ and one of them explains\n * a finding the other does not.\n */\nfunction sortedEdges(\n  relations: readonly Relation[],\n  index: ReadonlyMap<string, NodeId>,\n): readonly Edge[] {\n  const edges: Edge[] = [];\n\n  for (const relation of relations) {\n    const from = index.get(keyOf(relation.from.kind, relation.from.name));\n    const to = index.get(keyOf(relation.to.kind, relation.to.name));\n    if (from === undefined || to === undefined) continue;\n    edges.push({ from, to, kind: EDGE_KINDS.indexOf(relation.kind) });\n  }\n\n  edges.sort((a, b) => a.from - b.from || a.to - b.to || a.kind - b.kind);\n\n  const unique: Edge[] = [];\n  for (const edge of edges) {\n    const last = unique[unique.length - 1];\n    const same =\n      last !== undefined && last.from === edge.from && last.to === edge.to && last.kind === edge.kind;\n    if (!same) unique.push(edge);\n  }\n\n  return unique;\n}\n\n/**\n * One direction, by counting sort.\n *\n * `by` names the endpoint a row is keyed on: `from` produces *what this depends\n * on*, `to` produces the transpose. Two passes — count the degrees, then place —\n * and no per-node array is ever allocated.\n */\nfunction adjacencyOf(edges: readonly Edge[], nodes: number, by: 'from' | 'to'): Adjacency {\n  const offset = new Uint32Array(nodes + 1);\n  for (const edge of edges) offset[edge[by] + 1] = offset[edge[by] + 1]! + 1;\n  for (let id = 0; id < nodes; id += 1) offset[id + 1] = offset[id + 1]! + offset[id]!;\n\n  const target = new Uint32Array(edges.length);\n  const kind = new Uint8Array(edges.length);\n  const cursor = Uint32Array.from(offset.subarray(0, nodes));\n\n  for (const edge of edges) {\n    const row = edge[by];\n    const at = cursor[row]!;\n    target[at] = by === 'from' ? edge.to : edge.from;\n    kind[at] = edge.kind;\n    cursor[row] = at + 1;\n  }\n\n  return { offset, target, kind };\n}\n"]}

package/dist/relate/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `core/relate` — what reaches what.
+ *
+ * A typed, interned, bidirectional graph and the two traversals over it, plus the
+ * file-shaped record the scanner produces and the fold that turns a pile of them
+ * into the structure. No I/O, no parser, no resolver: the expensive half belongs
+ * to whoever owns the disk, and this is the half that has to be fast and has to
+ * be provable without one.
+ *
+ * See [`docs/selecting.md`](../../../../docs/selecting.md) for what it is for.
+ */
+export { EDGE_KINDS, NODE_KINDS, idOf, keyOf, nodeAt, nodesOfKind, relationsOf, type Adjacency, type EdgeKind, type Node, type NodeId, type NodeKind, type Relation, type Relations, } from './graph.js';
+export { dependenciesOf, dependentsOf, trailOf, type Reach, type ReachOptions, } from './reach.js';
+export { CLOSURE_EDGES, closureOf, driftedBetween, type Closure, type ClosureInput, type Drift, } from './merkle.js';
+export { explain, movedBy, relationsOfFiles, type FileEdge, type FileRecord, type Hole, type Reached, } from './records.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/relate/index.js

@@ -0,0 +1,16 @@
+/**
+ * `core/relate` — what reaches what.
+ *
+ * A typed, interned, bidirectional graph and the two traversals over it, plus the
+ * file-shaped record the scanner produces and the fold that turns a pile of them
+ * into the structure. No I/O, no parser, no resolver: the expensive half belongs
+ * to whoever owns the disk, and this is the half that has to be fast and has to
+ * be provable without one.
+ *
+ * See [`docs/selecting.md`](../../../../docs/selecting.md) for what it is for.
+ */
+export { EDGE_KINDS, NODE_KINDS, idOf, keyOf, nodeAt, nodesOfKind, relationsOf, } from './graph.js';
+export { dependenciesOf, dependentsOf, trailOf, } from './reach.js';
+export { CLOSURE_EDGES, closureOf, driftedBetween, } from './merkle.js';
+export { explain, movedBy, relationsOfFiles, } from './records.js';
+//# sourceMappingURL=index.js.map

package/dist/relate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/relate/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,UAAU,EACV,UAAU,EACV,IAAI,EACJ,KAAK,EACL,MAAM,EACN,WAAW,EACX,WAAW,GAQZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,OAAO,GAGR,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,SAAS,EACT,cAAc,GAIf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,OAAO,EACP,OAAO,EACP,gBAAgB,GAKjB,MAAM,cAAc,CAAC","sourcesContent":["/**\n * `core/relate` — what reaches what.\n *\n * A typed, interned, bidirectional graph and the two traversals over it, plus the\n * file-shaped record the scanner produces and the fold that turns a pile of them\n * into the structure. No I/O, no parser, no resolver: the expensive half belongs\n * to whoever owns the disk, and this is the half that has to be fast and has to\n * be provable without one.\n *\n * See [`docs/selecting.md`](../../../../docs/selecting.md) for what it is for.\n */\n\nexport {\n  EDGE_KINDS,\n  NODE_KINDS,\n  idOf,\n  keyOf,\n  nodeAt,\n  nodesOfKind,\n  relationsOf,\n  type Adjacency,\n  type EdgeKind,\n  type Node,\n  type NodeId,\n  type NodeKind,\n  type Relation,\n  type Relations,\n} from './graph.js';\n\nexport {\n  dependenciesOf,\n  dependentsOf,\n  trailOf,\n  type Reach,\n  type ReachOptions,\n} from './reach.js';\n\nexport {\n  CLOSURE_EDGES,\n  closureOf,\n  driftedBetween,\n  type Closure,\n  type ClosureInput,\n  type Drift,\n} from './merkle.js';\n\nexport {\n  explain,\n  movedBy,\n  relationsOfFiles,\n  type FileEdge,\n  type FileRecord,\n  type Hole,\n  type Reached,\n} from './records.js';\n"]}

package/dist/relate/merkle.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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 { type Digest } from '../format/hash.js';
+import { type EdgeKind, type Relations } from './graph.js';
+export interface ClosureInput {
+    readonly relations: Relations;
+    /**
+     * Content digest per file, keyed by the file's path.
+     *
+     * A file with no entry is volatile: nothing here can tell whether it moved.
+     * Component nodes take no entry — a component has no bytes of its own, and its
+     * content is the file that declares it, which it already depends on.
+     */
+    readonly content: ReadonlyMap<string, Digest>;
+    /** Restrict the closure to these edge kinds. Every kind by default. */
+    readonly through?: Iterable<EdgeKind>;
+}
+export interface Closure {
+    /** `keyOf(kind, name)` → the digest of everything that node rests on. */
+    readonly digests: ReadonlyMap<string, Digest>;
+    /**
+     * Nodes whose digest cannot prove sameness, and everything resting on them.
+     *
+     * Not an error. It is the honest half of the answer, and a caller that ignores
+     * it converts a missing input into a subject nobody observed.
+     */
+    readonly volatile: ReadonlySet<string>;
+}
+/**
+ * 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 declare function closureOf(input: ClosureInput): Closure;
+export interface Drift {
+    /** Node keys whose closure is not provably the one it was. */
+    readonly changed: readonly string[];
+    /** The file paths among them. */
+    readonly files: readonly string[];
+    /** The component names among them. */
+    readonly components: readonly string[];
+    /** Node keys the earlier closure held and this one does not. */
+    readonly gone: readonly string[];
+}
+/**
+ * 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 declare function driftedBetween(before: Closure, after: Closure): Drift;
+/**
+ * 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 declare const CLOSURE_EDGES: readonly EdgeKind[];
+//# sourceMappingURL=merkle.d.ts.map