@variance-authority/core 0.1.0

package/dist/judge/verdict.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The verdict model (spec §7).
+ *
+ * A verdict is the system's only output that anyone acts on. Everything upstream
+ * — snapshots, diffs, bands, attribution — exists to produce one of these six
+ * words with a defensible reason attached.
+ */
+export type Verdict = 
+/** Hash hit, or never reachable from the change. */
+'unchanged'
+/** Fully explained by an adjudication that already happened upstream. */
+ | 'inherited'
+/** Matches declared intent, or policy auto-approves this band. */
+ | 'authorized'
+/** Band and policy require a human to sign off. One action per root. */
+ | 'needs-review'
+/** Policy forbids it. An agent must fix this before opening a PR. */
+ | 'violation'
+/**
+ * Raster residue with no semantic cause. The highest severity in the system.
+ *
+ * Inverted relative to pixel-diff tools, and deliberately so (spec §1): a
+ * change the pipeline cannot explain means provenance failed, so the tool has
+ * lost the thread rather than found a small problem.
+ */
+ | 'unexplained';
+/**
+ * A band the acting profile could not observe.
+ *
+ * Not a verdict, and never collapsed into one. A tier that cannot see a band must
+ * say so rather than pass it (ADR-0002); folding this into `unchanged` is exactly
+ * the false-negative the profile system exists to prevent.
+ */
+export declare const UNOBSERVED: 'unobserved';
+export type BandOutcome = Verdict | typeof UNOBSERVED;
+export declare function severityOf(verdict: Verdict): number;
+/** Whether a verdict should fail CI. Policy may promote, never demote. */
+export declare function blocks(verdict: Verdict): boolean;
+//# sourceMappingURL=verdict.d.ts.map

package/dist/judge/verdict.js

@@ -0,0 +1,32 @@
+/**
+ * The verdict model (spec §7).
+ *
+ * A verdict is the system's only output that anyone acts on. Everything upstream
+ * — snapshots, diffs, bands, attribution — exists to produce one of these six
+ * words with a defensible reason attached.
+ */
+/**
+ * A band the acting profile could not observe.
+ *
+ * Not a verdict, and never collapsed into one. A tier that cannot see a band must
+ * say so rather than pass it (ADR-0002); folding this into `unchanged` is exactly
+ * the false-negative the profile system exists to prevent.
+ */
+export const UNOBSERVED = 'unobserved';
+/** Ordered by severity. Later entries win when a subject carries several. */
+const SEVERITY = [
+    'unchanged',
+    'inherited',
+    'authorized',
+    'needs-review',
+    'violation',
+    'unexplained',
+];
+export function severityOf(verdict) {
+    return SEVERITY.indexOf(verdict);
+}
+/** Whether a verdict should fail CI. Policy may promote, never demote. */
+export function blocks(verdict) {
+    return verdict === 'violation' || verdict === 'unexplained' || verdict === 'needs-review';
+}
+//# sourceMappingURL=verdict.js.map

package/dist/judge/verdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.js","sourceRoot":"","sources":["../../src/judge/verdict.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsBH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,YAAqB,CAAC;AAIhD,6EAA6E;AAC7E,MAAM,QAAQ,GAAuB;IACnC,WAAW;IACX,WAAW;IACX,YAAY;IACZ,cAAc;IACd,WAAW;IACX,aAAa;CACd,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,OAAO,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,MAAM,CAAC,OAAgB;IACrC,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,KAAK,aAAa,IAAI,OAAO,KAAK,cAAc,CAAC;AAC5F,CAAC","sourcesContent":["/**\n * The verdict model (spec §7).\n *\n * A verdict is the system's only output that anyone acts on. Everything upstream\n * — snapshots, diffs, bands, attribution — exists to produce one of these six\n * words with a defensible reason attached.\n */\n\nexport type Verdict =\n  /** Hash hit, or never reachable from the change. */\n  | 'unchanged'\n  /** Fully explained by an adjudication that already happened upstream. */\n  | 'inherited'\n  /** Matches declared intent, or policy auto-approves this band. */\n  | 'authorized'\n  /** Band and policy require a human to sign off. One action per root. */\n  | 'needs-review'\n  /** Policy forbids it. An agent must fix this before opening a PR. */\n  | 'violation'\n  /**\n   * Raster residue with no semantic cause. The highest severity in the system.\n   *\n   * Inverted relative to pixel-diff tools, and deliberately so (spec §1): a\n   * change the pipeline cannot explain means provenance failed, so the tool has\n   * lost the thread rather than found a small problem.\n   */\n  | 'unexplained';\n\n/**\n * A band the acting profile could not observe.\n *\n * Not a verdict, and never collapsed into one. A tier that cannot see a band must\n * say so rather than pass it (ADR-0002); folding this into `unchanged` is exactly\n * the false-negative the profile system exists to prevent.\n */\nexport const UNOBSERVED = 'unobserved' as const;\n\nexport type BandOutcome = Verdict | typeof UNOBSERVED;\n\n/** Ordered by severity. Later entries win when a subject carries several. */\nconst SEVERITY: readonly Verdict[] = [\n  'unchanged',\n  'inherited',\n  'authorized',\n  'needs-review',\n  'violation',\n  'unexplained',\n];\n\nexport function severityOf(verdict: Verdict): number {\n  return SEVERITY.indexOf(verdict);\n}\n\n/** Whether a verdict should fail CI. Policy may promote, never demote. */\nexport function blocks(verdict: Verdict): boolean {\n  return verdict === 'violation' || verdict === 'unexplained' || verdict === 'needs-review';\n}\n"]}

package/dist/plan/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@variance-authority/core/plan` — a composition as a value.
+ *
+ * The declaration every tool carries, the list a caller assembles from them, and
+ * the identity derived from that list. Its own entrypoint because assembling a
+ * pipeline is a thing somebody does *before* they have any of the values the
+ * other groups describe — and because the identity is the mechanism that makes
+ * "declare what you did" enforceable rather than promised.
+ */
+export { planIdentity, validatePlan, planForTier, describePlan } from './tool.js';
+export type { ToolKind, Tier, IdentityContribution, ToolDeclaration, Plan, PlanProblem, } from './tool.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/plan/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@variance-authority/core/plan` — a composition as a value.
+ *
+ * The declaration every tool carries, the list a caller assembles from them, and
+ * the identity derived from that list. Its own entrypoint because assembling a
+ * pipeline is a thing somebody does *before* they have any of the values the
+ * other groups describe — and because the identity is the mechanism that makes
+ * "declare what you did" enforceable rather than promised.
+ */
+export { planIdentity, validatePlan, planForTier, describePlan } from './tool.js';
+//# sourceMappingURL=index.js.map

package/dist/plan/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/plan/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC","sourcesContent":["/**\n * `@variance-authority/core/plan` — a composition as a value.\n *\n * The declaration every tool carries, the list a caller assembles from them, and\n * the identity derived from that list. Its own entrypoint because assembling a\n * pipeline is a thing somebody does *before* they have any of the values the\n * other groups describe — and because the identity is the mechanism that makes\n * \"declare what you did\" enforceable rather than promised.\n */\n\nexport { planIdentity, validatePlan, planForTier, describePlan } from './tool.js';\nexport type {\n  ToolKind,\n  Tier,\n  IdentityContribution,\n  ToolDeclaration,\n  Plan,\n  PlanProblem,\n} from './tool.js';\n"]}

package/dist/plan/tool.d.ts

@@ -0,0 +1,85 @@
+import { type Digest } from '../format/hash.js';
+import { type Tier } from '../format/tier.js';
+/**
+ * The declaration every tool carries, and the plan a caller assembles from them.
+ *
+ * The architecture says a pipeline is something a user composes rather than
+ * something this project ships. That is only true if a composition is a *value*:
+ * something that can be listed, checked, printed, and — the part that matters —
+ * whose identity is derived from its parts instead of hand-written somewhere
+ * else.
+ *
+ * The hand-written version is the bug this file exists to remove. When the
+ * identity of a result enumerates the machine, the scale, the fonts and the
+ * tricks, swapping a *tool* — a different pruner, a different comparator, a
+ * different clustering — leaves that identity untouched. Two results produced by
+ * different code then compare as though they were produced by the same code, and
+ * the difference is attributed to whichever component happens to sit under it.
+ * Contract 2 says declare what you did; a list somebody maintains by hand is a
+ * promise, and this is the mechanism.
+ */
+export type ToolKind = 'acquire' | 'prepare' | 'render' | 'hash' | 'compare' | 'isolate' | 'map' | 'judge' | 'record';
+export type { Tier };
+/**
+ * What a tool contributes to the identity of what it produces.
+ *
+ * `'nothing'` is a decision, not a default. A tool that genuinely cannot change
+ * an answer says so out loud, and the difference between "contributes nothing"
+ * and "nobody thought about it" stays visible — the same distinction contract 3
+ * makes everywhere else, applied to provenance.
+ */
+export type IdentityContribution = Digest | 'nothing';
+export interface ToolDeclaration {
+    /**
+     * Stable identifier, and part of the plan's identity.
+     *
+     * Renaming a tool is therefore a new identity. That is correct: nothing
+     * downstream can know that two names referred to one implementation.
+     */
+    readonly id: string;
+    readonly kind: ToolKind;
+    readonly needs: Tier;
+    /** One sentence: what it does, and what it costs. */
+    readonly because: string;
+    /**
+     * Everything about this tool's configuration that could change its answer.
+     *
+     * A version, a policy, a threshold, a ruleset. Not its inputs — those are
+     * addressed separately — only what the tool *is*.
+     */
+    readonly identity: IdentityContribution;
+}
+export type Plan = readonly ToolDeclaration[];
+/**
+ * The identity of a composition.
+ *
+ * Order-sensitive, unlike an intervention recipe. Two plans containing the same
+ * tools in a different order do not produce the same answer — isolating before
+ * mapping and mapping before isolating are different systems — so the sequence
+ * is part of what is addressed.
+ */
+export declare function planIdentity(plan: Plan): Digest;
+export interface PlanProblem {
+    readonly severity: 'error' | 'warning';
+    readonly tool: string;
+    readonly because: string;
+}
+/**
+ * What is wrong with a composition, before it runs.
+ *
+ * Returned rather than thrown. A caller assembling a bespoke plan is entitled to
+ * a list, and some of what is reported here is a legitimate choice — running a
+ * raster tool at a semantic tier is a mistake, but a plan that produces no
+ * verdict is a perfectly good extraction pipeline.
+ */
+export declare function validatePlan(plan: Plan, tier: Tier): readonly PlanProblem[];
+/** The tools a plan will actually run at a given tier. */
+export declare function planForTier(plan: Plan, tier: Tier): Plan;
+/**
+ * The plan as something a person reads before trusting a number that came out of it.
+ *
+ * Printed beside a verdict, this is what lets a reader tell "the button changed"
+ * from "the button changed, according to a composition that skipped attribution".
+ */
+export declare function describePlan(plan: Plan, tier: Tier): string;
+//# sourceMappingURL=tool.d.ts.map

package/dist/plan/tool.js

@@ -0,0 +1,87 @@
+import { digestCombine, digestValue } from '../format/hash.js';
+import { tierReaches } from '../format/tier.js';
+/**
+ * The identity of a composition.
+ *
+ * Order-sensitive, unlike an intervention recipe. Two plans containing the same
+ * tools in a different order do not produce the same answer — isolating before
+ * mapping and mapping before isolating are different systems — so the sequence
+ * is part of what is addressed.
+ */
+export function planIdentity(plan) {
+    return digestCombine('plan', plan.map((tool) => digestValue({
+        id: tool.id,
+        kind: tool.kind,
+        needs: tool.needs,
+        identity: tool.identity,
+    })));
+}
+/**
+ * What is wrong with a composition, before it runs.
+ *
+ * Returned rather than thrown. A caller assembling a bespoke plan is entitled to
+ * a list, and some of what is reported here is a legitimate choice — running a
+ * raster tool at a semantic tier is a mistake, but a plan that produces no
+ * verdict is a perfectly good extraction pipeline.
+ */
+export function validatePlan(plan, tier) {
+    const problems = [];
+    const seen = new Set();
+    for (const tool of plan) {
+        if (seen.has(tool.id)) {
+            // Two tools under one name make the plan's identity ambiguous: the digest
+            // cannot distinguish the composition from one containing either alone.
+            problems.push({
+                severity: 'error',
+                tool: tool.id,
+                because: 'appears more than once, so the plan identity cannot address it',
+            });
+        }
+        seen.add(tool.id);
+        if (!tierReaches(tier, tool.needs)) {
+            problems.push({
+                severity: 'error',
+                tool: tool.id,
+                because: `needs the ${tool.needs} tier and this plan runs at ${tier}, so it cannot answer ` +
+                    'its question — and a tool that runs anyway reports whatever it managed to see',
+            });
+        }
+    }
+    if (!plan.some((tool) => tool.kind === 'judge')) {
+        problems.push({
+            severity: 'warning',
+            tool: '(plan)',
+            because: 'contains no judge, so it produces observations and no verdict. Legitimate for an ' +
+                'extraction pipeline; a mistake if anything downstream expects a pass or a fail',
+        });
+    }
+    return problems;
+}
+/** The tools a plan will actually run at a given tier. */
+export function planForTier(plan, tier) {
+    return plan.filter((tool) => tierReaches(tier, tool.needs));
+}
+/**
+ * The plan as something a person reads before trusting a number that came out of it.
+ *
+ * Printed beside a verdict, this is what lets a reader tell "the button changed"
+ * from "the button changed, according to a composition that skipped attribution".
+ */
+export function describePlan(plan, tier) {
+    if (plan.length === 0)
+        return 'an empty plan, which observes nothing';
+    const running = planForTier(plan, tier);
+    const skipped = plan.filter((tool) => !running.includes(tool));
+    return [
+        `${running.length} tool(s) at the ${tier} tier — ${planIdentity(plan)}`,
+        ...running.map((tool) => `  ${tool.kind.padEnd(8)} ${tool.id} — ${tool.because}`),
+        ...(skipped.length > 0
+            ? [
+                '',
+                `${skipped.length} tool(s) need a more expensive tier and will not run:`,
+                ...skipped.map((tool) => `  ${tool.id} needs ${tool.needs}`),
+            ]
+            : []),
+    ].join('\n');
+}
+//# sourceMappingURL=tool.js.map

package/dist/plan/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/plan/tool.ts"],"names":[],"mappings":"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","sourcesContent":["import { digestCombine, digestValue, type Digest } from '../format/hash.js';\nimport { tierReaches, type Tier } from '../format/tier.js';\n\n/**\n * The declaration every tool carries, and the plan a caller assembles from them.\n *\n * The architecture says a pipeline is something a user composes rather than\n * something this project ships. That is only true if a composition is a *value*:\n * something that can be listed, checked, printed, and — the part that matters —\n * whose identity is derived from its parts instead of hand-written somewhere\n * else.\n *\n * The hand-written version is the bug this file exists to remove. When the\n * identity of a result enumerates the machine, the scale, the fonts and the\n * tricks, swapping a *tool* — a different pruner, a different comparator, a\n * different clustering — leaves that identity untouched. Two results produced by\n * different code then compare as though they were produced by the same code, and\n * the difference is attributed to whichever component happens to sit under it.\n * Contract 2 says declare what you did; a list somebody maintains by hand is a\n * promise, and this is the mechanism.\n */\n\nexport type ToolKind =\n  | 'acquire'\n  | 'prepare'\n  | 'render'\n  | 'hash'\n  | 'compare'\n  | 'isolate'\n  | 'map'\n  | 'judge'\n  | 'record';\n\nexport type { Tier };\n\n/**\n * What a tool contributes to the identity of what it produces.\n *\n * `'nothing'` is a decision, not a default. A tool that genuinely cannot change\n * an answer says so out loud, and the difference between \"contributes nothing\"\n * and \"nobody thought about it\" stays visible — the same distinction contract 3\n * makes everywhere else, applied to provenance.\n */\nexport type IdentityContribution = Digest | 'nothing';\n\nexport interface ToolDeclaration {\n  /**\n   * Stable identifier, and part of the plan's identity.\n   *\n   * Renaming a tool is therefore a new identity. That is correct: nothing\n   * downstream can know that two names referred to one implementation.\n   */\n  readonly id: string;\n  readonly kind: ToolKind;\n  readonly needs: Tier;\n  /** One sentence: what it does, and what it costs. */\n  readonly because: string;\n  /**\n   * Everything about this tool's configuration that could change its answer.\n   *\n   * A version, a policy, a threshold, a ruleset. Not its inputs — those are\n   * addressed separately — only what the tool *is*.\n   */\n  readonly identity: IdentityContribution;\n}\n\nexport type Plan = readonly ToolDeclaration[];\n\n/**\n * The identity of a composition.\n *\n * Order-sensitive, unlike an intervention recipe. Two plans containing the same\n * tools in a different order do not produce the same answer — isolating before\n * mapping and mapping before isolating are different systems — so the sequence\n * is part of what is addressed.\n */\nexport function planIdentity(plan: Plan): Digest {\n  return digestCombine(\n    'plan',\n    plan.map((tool) =>\n      digestValue({\n        id: tool.id,\n        kind: tool.kind,\n        needs: tool.needs,\n        identity: tool.identity,\n      }),\n    ),\n  );\n}\n\nexport interface PlanProblem {\n  readonly severity: 'error' | 'warning';\n  readonly tool: string;\n  readonly because: string;\n}\n\n/**\n * What is wrong with a composition, before it runs.\n *\n * Returned rather than thrown. A caller assembling a bespoke plan is entitled to\n * a list, and some of what is reported here is a legitimate choice — running a\n * raster tool at a semantic tier is a mistake, but a plan that produces no\n * verdict is a perfectly good extraction pipeline.\n */\nexport function validatePlan(plan: Plan, tier: Tier): readonly PlanProblem[] {\n  const problems: PlanProblem[] = [];\n  const seen = new Set<string>();\n\n  for (const tool of plan) {\n    if (seen.has(tool.id)) {\n      // Two tools under one name make the plan's identity ambiguous: the digest\n      // cannot distinguish the composition from one containing either alone.\n      problems.push({\n        severity: 'error',\n        tool: tool.id,\n        because: 'appears more than once, so the plan identity cannot address it',\n      });\n    }\n    seen.add(tool.id);\n\n    if (!tierReaches(tier, tool.needs)) {\n      problems.push({\n        severity: 'error',\n        tool: tool.id,\n        because:\n          `needs the ${tool.needs} tier and this plan runs at ${tier}, so it cannot answer ` +\n          'its question — and a tool that runs anyway reports whatever it managed to see',\n      });\n    }\n  }\n\n  if (!plan.some((tool) => tool.kind === 'judge')) {\n    problems.push({\n      severity: 'warning',\n      tool: '(plan)',\n      because:\n        'contains no judge, so it produces observations and no verdict. Legitimate for an ' +\n        'extraction pipeline; a mistake if anything downstream expects a pass or a fail',\n    });\n  }\n\n  return problems;\n}\n\n/** The tools a plan will actually run at a given tier. */\nexport function planForTier(plan: Plan, tier: Tier): Plan {\n  return plan.filter((tool) => tierReaches(tier, tool.needs));\n}\n\n/**\n * The plan as something a person reads before trusting a number that came out of it.\n *\n * Printed beside a verdict, this is what lets a reader tell \"the button changed\"\n * from \"the button changed, according to a composition that skipped attribution\".\n */\nexport function describePlan(plan: Plan, tier: Tier): string {\n  if (plan.length === 0) return 'an empty plan, which observes nothing';\n\n  const running = planForTier(plan, tier);\n  const skipped = plan.filter((tool) => !running.includes(tool));\n\n  return [\n    `${running.length} tool(s) at the ${tier} tier — ${planIdentity(plan)}`,\n    ...running.map((tool) => `  ${tool.kind.padEnd(8)} ${tool.id} — ${tool.because}`),\n    ...(skipped.length > 0\n      ? [\n          '',\n          `${skipped.length} tool(s) need a more expensive tier and will not run:`,\n          ...skipped.map((tool) => `  ${tool.id} needs ${tool.needs}`),\n        ]\n      : []),\n  ].join('\\n');\n}\n"]}

package/dist/relate/graph.d.ts

@@ -0,0 +1,190 @@
+/**
+ * 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 declare const NODE_KINDS: readonly ['file', 'component'];
+export type NodeKind = (typeof NODE_KINDS)[number];
+/**
+ * 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 declare const EDGE_KINDS: readonly [
+/** `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'];
+export type EdgeKind = (typeof EDGE_KINDS)[number];
+export interface Node {
+    readonly kind: NodeKind;
+    /** Repository-relative for a file; the identifier for a component. */
+    readonly name: string;
+}
+export interface Relation {
+    readonly from: Node;
+    readonly to: Node;
+    readonly kind: EdgeKind;
+}
+/** An index into `Relations.names`. Valid only against the graph it came from. */
+export type NodeId = number;
+/**
+ * One direction of the edge set, compressed-sparse-row.
+ *
+ * Node `i`'s edges are `target[offset[i] … offset[i + 1])`, and `kind[j]`
+ * describes `target[j]`. `offset` holds one more entry than there are nodes, so
+ * the last row needs no special case.
+ */
+export interface Adjacency {
+    readonly offset: Uint32Array;
+    readonly target: Uint32Array;
+    readonly kind: Uint8Array;
+}
+export interface Relations {
+    /** Node names by id, ordered by kind and then by code unit. */
+    readonly names: readonly string[];
+    /** The `NODE_KINDS` index of each node. */
+    readonly kinds: Uint8Array;
+    /** What each node depends on. */
+    readonly depends: Adjacency;
+    /** What depends on each node — the transpose, materialized. */
+    readonly dependents: Adjacency;
+    /**
+     * `1` where this node's outgoing edges could not be enumerated.
+     *
+     * A parse failure, a specifier that was not a literal, a file in a language
+     * nothing here reads. It is *not* "this file has no dependencies", and the
+     * difference is the whole safety argument: a file whose edges are unknown may
+     * depend on anything that changed, so selection seeds the traversal with every
+     * one of them (ADR-0002 — absent is not empty).
+     */
+    readonly unknown: Uint8Array;
+    /**
+     * Why, for each of those nodes, in the words whoever read the file used.
+     *
+     * Sparse — a repository the scan understands carries none of these — and kept
+     * apart from the mask because the mask is what the inner loop tests and this is
+     * what an operator reads. Without it, a run that observed forty subjects instead
+     * of twelve can say *because eight files could not be read* and can never say
+     * **which**, which is the difference between a fact and a work item.
+     */
+    readonly reasons: ReadonlyMap<NodeId, string>;
+    /** `keyOf` to id — the interning table, kept for lookup. */
+    readonly index: ReadonlyMap<string, NodeId>;
+}
+/**
+ * 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 declare function keyOf(kind: NodeKind, name: string): string;
+export declare function idOf(relations: Relations, kind: NodeKind, name: string): NodeId | undefined;
+export declare function nodeAt(relations: Relations, id: NodeId): Node | undefined;
+/** Every node of one kind, as ids. Contiguous, because the order is kind-major. */
+export declare function nodesOfKind(relations: Relations, kind: NodeKind): readonly NodeId[];
+/**
+ * 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 declare function relationsOf(input: {
+    readonly relations: Iterable<Relation>;
+    /**
+     * Nodes whose outgoing edges are not fully known, and must be treated as such.
+     *
+     * A bare node says *this one is blind*. A pair says why, in whatever words the
+     * reader of the file used — and the sentence is the half an operator can act on,
+     * so it travels with the fact rather than being reconstructed from it.
+     */
+    readonly unknown?: Iterable<Node | readonly [Node, string]>;
+    /** Nodes with no edges at all, which would otherwise be absent from the graph. */
+    readonly isolated?: Iterable<Node>;
+}): Relations;
+//# sourceMappingURL=graph.d.ts.map