@archwall/core 0.1.0

package/dist/transform-CnUPOO0E.d.mts

@@ -0,0 +1,638 @@
+//#region src/graph/ir.d.ts
+/** Semver of the Project Graph IR schema itself, independent of package versions. */
+declare const IR_VERSION = "1.0.0";
+/**
+ * A module's identity, in the IR's own vocabulary rather than the host's.
+ *
+ * ```
+ * file:<repo-relative-posix-path>   source | workspace | excluded
+ * pkg:<name>                        package    — the package, not one of its files
+ * builtin:<specifier>               builtin    — always prefixed (builtin:node:fs)
+ * virtual:<host>:<opaque>           virtual    — host-synthesized, host-specific by nature
+ * unresolved:<raw-specifier>        unresolved
+ * ```
+ *
+ * Producers report host facts; `GraphBuilder` decides identity — the same division
+ * {@link ModuleKind} already uses. That is what makes a violation's fingerprint the same under
+ * every bundler, which is what makes a baseline file possible at all.
+ */
+type ModuleId = string;
+/** The schemes {@link ModuleId} recognises. */
+declare const MODULE_ID_SCHEMES: readonly ["file", "pkg", "builtin", "virtual", "unresolved"];
+type ModuleIdScheme = (typeof MODULE_ID_SCHEMES)[number];
+/**
+ * Splits a canonical id into its scheme and body, or null when it carries no known scheme.
+ *
+ * Null is a legitimate answer, not an error: in-memory graphs (`@archwall/test-utils`, a
+ * playground) use bare ids, and every consumer here degrades to treating the id as opaque.
+ */
+declare function parseModuleId(id: ModuleId): {
+  scheme: ModuleIdScheme;
+  body: string;
+} | null;
+/**
+ * The id as a human should read it: the path, the package name, the builtin specifier.
+ *
+ * Used by every reporter and offered to rules as `RuleContext.display`, so that a message names
+ * `src/domain/rules.ts` and `react` rather than a scheme-prefixed id — or, as before canonical
+ * ids existed, an absolute path from whichever machine produced the graph.
+ *
+ * `virtual:` keeps its prefix: it is not a path, and the prefix is the only thing that says so.
+ */
+declare function displayModuleId(id: ModuleId): string;
+type WellKnownCapability =
+/** `Edge.loc` is populated. */
+"import-locations" |
+/** Dynamic `import()` edges are present and marked `kind: "dynamic"`. */
+"dynamic-imports" |
+/** Every module in the project is present; absence of a module IS evidence. */
+"complete-graph" |
+/** Re-export edges are distinguished from plain imports. */
+"reexport-edges" |
+/**
+ * `Edge.rawSpecifier` is what the author wrote, not a copy of the resolved id. A rule
+ * that matches on specifiers must require this, or it silently matches nothing on hosts
+ * that cannot supply them and reports a clean run rather than an unavailable one.
+ */
+"raw-specifiers";
+/**
+ * Open union: adapters may declare capabilities core does not know about, and rules may
+ * require them, without an IR major. `WellKnownCapability` keeps autocomplete useful for
+ * the ones core ships.
+ */
+type Capability = WellKnownCapability | (string & {});
+interface HostInfo {
+  name: string;
+  version: string;
+  capabilities: ReadonlySet<Capability>;
+}
+interface SourceLocation {
+  file: string;
+  /** 1-based */
+  line: number;
+  /** 0-based */
+  column: number;
+}
+type WellKnownEdgeKind = "static" | "dynamic" | "reexport";
+/**
+ * Open union so future graph facts (CSS imports, worker edges, type-only edges) arrive
+ * additively. Consumers must treat an unrecognised kind as "some dependency exists" —
+ * never assume exhaustiveness.
+ */
+type EdgeKind = WellKnownEdgeKind | (string & {});
+/**
+ * What a module *is*, relative to the project being analysed.
+ *
+ * - `source`     — a first-party file inside the analysed project
+ * - `workspace`  — a file owned by a *different* package in the same monorepo
+ * - `package`    — a third-party dependency (node_modules)
+ * - `builtin`    — a runtime builtin (`node:fs`, `bun:sqlite`, …)
+ * - `virtual`    — generated by the toolchain; no file on disk
+ * - `unresolved` — the specifier could not be resolved to anything
+ * - `excluded`   — a real project file the config's `exclude` removed from analysis
+ *
+ * The seven-way split is load-bearing: a purity rule that cannot tell `node:crypto` from
+ * `lodash` from `@myorg/shared-kernel` gives the wrong answer for two of the three.
+ */
+type ModuleKind = "source" | "workspace" | "package" | "builtin" | "virtual" | "unresolved" | "excluded";
+interface ModuleNode {
+  /** Canonical; see {@link ModuleId}. */
+  id: ModuleId;
+  /**
+   * Absolute path, for the kinds that denote a file: `source`, `workspace`, `excluded`.
+   *
+   * Null for everything else — including `package`, because a dependency is one node
+   * (`pkg:react`) rather than one node per file, so there is no single file to name.
+   */
+  file: string | null;
+  kind: ModuleKind;
+  /** npm package name, for `kind: "package"`. */
+  packageName?: string;
+  /** Owning workspace package name, for `kind: "workspace"`. */
+  workspace?: string;
+  /** Filled by classification, e.g. layer → "features". */
+  tags: ReadonlyMap<string, string>;
+}
+/** Code the project owns and can change — including sibling packages in the monorepo. */
+declare const FIRST_PARTY_KINDS: readonly ["source", "workspace"];
+/** A dependency the project does not own: third-party code or a runtime builtin. */
+declare const THIRD_PARTY_KINDS: readonly ["package", "builtin"];
+declare function isFirstParty(kind: ModuleKind): boolean;
+declare function isThirdParty(kind: ModuleKind): boolean;
+interface Edge {
+  from: ModuleId;
+  to: ModuleId;
+  /** What the source wrote: "@/features/auth". */
+  rawSpecifier: string;
+  /** What it actually is after resolution. */
+  resolvedPath: string;
+  kind: EdgeKind;
+  /** Present only if host capability allows. */
+  loc?: SourceLocation;
+}
+type GraphDelivery = "complete" | "progressive";
+interface ProjectGraphInit {
+  host: HostInfo;
+  /** Default "complete". */
+  delivery?: GraphDelivery;
+  modules: Iterable<readonly [ModuleId, ModuleNode]> | ReadonlyMap<ModuleId, ModuleNode>;
+  edges: readonly Edge[];
+  /** Default {@link IR_VERSION}. Adapters should leave this alone. */
+  irVersion?: string;
+}
+/**
+ * The module graph, as an OPAQUE handle.
+ *
+ * The backing stores are private and no accessor hands them out. Everything a consumer
+ * legitimately needs is a method here or on `GraphQuery`; if something is missing, the fix
+ * is to add a method, never to expose the store.
+ *
+ * That is what keeps the *representation* out of the IR contract: a `ReadonlyMap` plus an
+ * `Edge[]` is the current implementation, not the promise.
+ */
+declare class ProjectGraph {
+  #private;
+  readonly irVersion: string;
+  readonly host: HostInfo;
+  readonly delivery: GraphDelivery;
+  private constructor();
+  static create(init: ProjectGraphInit): ProjectGraph;
+  get moduleCount(): number;
+  get edgeCount(): number;
+  module(id: ModuleId): ModuleNode | undefined;
+  hasModule(id: ModuleId): boolean;
+  /** Every module, in graph order. */
+  modules(): Iterable<ModuleNode>;
+  /** Every module id, in graph order. */
+  moduleIds(): Iterable<ModuleId>;
+  /** Every edge, in graph order. Never copy this — it is already immutable. */
+  edges(): readonly Edge[];
+  /**
+   * A new graph with replaced stores, same identity fields.
+   *
+   * @internal Engine and {@link GraphDraft} only. Not part of the IR contract.
+   */
+  replaceStores(modules: ReadonlyMap<ModuleId, ModuleNode>, edges?: readonly Edge[]): ProjectGraph;
+}
+/**
+ * The write surface a {@link GraphTransform} gets.
+ *
+ * A transform adds, patches, and removes; it never constructs a graph. That is what keeps
+ * {@link ProjectGraph} opaque in practice rather than only in principle, and it means a
+ * transform cannot drop an IR field it does not know about.
+ */
+interface GraphMutation {
+  /** Read side, mirroring {@link ProjectGraph}. */
+  module(id: ModuleId): ModuleNode | undefined;
+  hasModule(id: ModuleId): boolean;
+  modules(): Iterable<ModuleNode>;
+  edges(): readonly Edge[];
+  /** Adds a module, or replaces one with the same id. */
+  addModule(node: ModuleNode): void;
+  /** Merges fields into an existing module; `tags` merge key-by-key. No-op if absent. */
+  patchModule(id: ModuleId, patch: Partial<Omit<ModuleNode, "id" | "tags">> & {
+    tags?: Record<string, string>;
+  }): void;
+  addEdge(edge: Edge): void;
+  /** Removes every edge the predicate accepts. */
+  removeEdges(predicate: (edge: Edge) => boolean): void;
+}
+/**
+ * Copy-on-write {@link GraphMutation} over a {@link ProjectGraph}.
+ *
+ * A transform that touches nothing costs nothing: the stores are only cloned on the first
+ * write, and `commit()` returns the original graph when there were none.
+ *
+ * @internal
+ */
+declare class GraphDraft implements GraphMutation {
+  #private;
+  constructor(base: ProjectGraph);
+  module(id: ModuleId): ModuleNode | undefined;
+  hasModule(id: ModuleId): boolean;
+  modules(): Iterable<ModuleNode>;
+  edges(): readonly Edge[];
+  addModule(node: ModuleNode): void;
+  patchModule(id: ModuleId, patch: Partial<Omit<ModuleNode, "id" | "tags">> & {
+    tags?: Record<string, string>;
+  }): void;
+  addEdge(edge: Edge): void;
+  removeEdges(predicate: (edge: Edge) => boolean): void;
+  /** The resulting graph, or the untouched original when nothing was written. */
+  commit(): ProjectGraph;
+}
+declare function irMajor(version: string): number;
+declare function assertIrCompatible(graphVersion: string): void;
+//#endregion
+//#region src/contracts/classifier.d.ts
+interface ClassifierContext {
+  /**
+   * Absolute source root from resolved config. Classifier patterns describe the shape of
+   * the source tree, so they are relative to this and never to the repository root.
+   */
+  sourceRoot: string;
+  /**
+   * A file's path relative to {@link sourceRoot}, forward-slashed, or null when it lies
+   * outside. Every path-based classifier needs exactly this, and none of them should be
+   * re-deriving it — guards, slash normalisation and all — in user code.
+   */
+  relative(file: string): string | null;
+}
+type TagPatch = Record<string, string> | null | undefined | void;
+interface Classifier {
+  name: string;
+  classify(module: ModuleNode, ctx: ClassifierContext): TagPatch;
+}
+declare function defineClassifier(classifier: Classifier): Classifier;
+//#endregion
+//#region src/violations.d.ts
+/**
+ * The ONE severity vocabulary, shared by violations and diagnostics.
+ *
+ * `info` is available to violations too: a rule may report something worth surfacing that
+ * should never gate a build.
+ */
+type Severity = "error" | "warn" | "info";
+/**
+ * Where a violation is.
+ *
+ * A tagged union rather than a pair of optional fields, and an ARRAY on the violation
+ * rather than one value, because findings are not all edge-shaped. A cycle has no single
+ * offending location — it has N of them, and the old model could only name one and had to
+ * serialise the rest into the message string. A finding about a package, a directory, or
+ * the configuration has no module at all.
+ *
+ * See docs/adr/0004-violation-locations.md.
+ */
+type ViolationLocation = {
+  type: "edge";
+  edge: Edge;
+} | {
+  type: "module";
+  module: ModuleId;
+} | {
+  type: "path";
+  path: string;
+  loc?: SourceLocation;
+};
+interface Violation {
+  ruleName: string;
+  /**
+   * Rule *instance* id — what you put in `overrides`, and what every reporter prints.
+   * Differs from `ruleName` when the rule came from a preset (`fsd/public-api`) or was
+   * given an explicit id; equal to it otherwise.
+   */
+  ruleId: string;
+  severity: Severity;
+  /** Rendered human summary. Derived from `messageId` + `data` unless set literally. */
+  message: string;
+  /**
+   * Stable identifier for WHICH of the rule's messages this is, independent of wording.
+   * Machine consumers group on this; translators key on it; `ConfiguredRule.message`
+   * retargets it.
+   */
+  messageId?: string;
+  /**
+   * The values interpolated into the message — and the structured payload a reporter needs
+   * in order to do anything other than print English. Without it a consumer wanting the
+   * layer names out of a `layer-dependencies` finding has to parse the sentence.
+   */
+  data?: Readonly<Record<string, string | number>>;
+  /**
+   * Every place this finding is about, most significant first. Always at least one entry
+   * for a rule that reported a location; may be empty for a finding about the run itself.
+   */
+  locations: readonly ViolationLocation[];
+  /** "Why": resolution chain, which constraint, how to fix. */
+  explanation?: string;
+  /**
+   * Stable, machine-independent identity. The same architecture problem on two developers'
+   * machines, or under two bundlers, yields the same fingerprint.
+   *
+   * This is what makes a baseline file possible, and a graph-based linter has no other
+   * suppression mechanism available: with no source text there can be no `// archwall-ignore`.
+   */
+  fingerprint: string;
+}
+interface ViolationInput {
+  /** Literal message. Mutually exclusive with `messageId`; one of the two is required. */
+  message?: string;
+  /** Key into the rule's `meta.messages`. Preferred — it is what `data` interpolates into. */
+  messageId?: string;
+  data?: Record<string, string | number>;
+  /** Convenience for the overwhelmingly common single-edge finding. */
+  edge?: Edge;
+  /** Convenience for the single-module finding. */
+  module?: ModuleId;
+  /** Full control, for findings with several locations or a non-module subject. */
+  locations?: readonly ViolationLocation[];
+  explanation?: string;
+  /**
+   * Overrides the rule instance's configured severity for this one finding — e.g. a
+   * two-module cycle as a warning and a forty-module cycle as an error.
+   */
+  severity?: Severity;
+  /**
+   * Explicit identity, for findings whose sameness is not captured by their locations.
+   * Order-insensitive: parts are sorted before hashing.
+   */
+  identity?: readonly string[];
+}
+/** Normalizes the three input spellings into the canonical location list. */
+declare function locationsOf(input: ViolationInput): readonly ViolationLocation[];
+/** The edge a finding is primarily about, when it is about one. */
+declare function primaryEdge(v: Pick<Violation, "locations">): Edge | undefined;
+/** The module a finding is primarily about: an explicit module, else an edge's source. */
+declare function primaryModule(v: Pick<Violation, "locations">): ModuleId | undefined;
+/** Where a finding should be anchored in an editor or in SARIF, when that is knowable. */
+declare function primarySourceLocation(v: Pick<Violation, "locations">): SourceLocation | undefined;
+/**
+ * Renders `{placeholder}` templates. Unknown placeholders are left verbatim, so a
+ * mis-keyed template is visible in the output rather than silently blank.
+ */
+declare function renderMessage(template: string, data: Readonly<Record<string, string | number>> | undefined): string;
+/**
+ * Fingerprint scheme version. Bump when the algorithm changes so that a stale baseline
+ * ERRORS instead of silently mismatching every entry.
+ *
+ * `aw3` is the first scheme over canonical module ids
+ * (docs/adr/0012-canonical-module-identity.md). Before it, a violation about `react` hashed the
+ * host's own id — a resolved `node_modules` path under the CLI, the bare specifier under esbuild
+ * — so the same finding fingerprinted differently under two bundlers.
+ */
+declare const FINGERPRINT_SCHEME = "aw3";
+/**
+ * Identity is (rule instance, offending locations) — deliberately NOT the message, so
+ * improving the wording of a rule's output does not invalidate every baseline entry that
+ * rule ever produced. `identity` overrides the locations when a rule knows better.
+ */
+declare function fingerprintOf(repoRoot: string, ruleId: string, input: Pick<ViolationInput, "edge" | "module" | "locations" | "identity">): string;
+type SeverityCounts = Record<Severity, number>;
+/** One definition of "how many of each", shared by every consumer that needs counts. */
+declare function countBySeverity(violations: readonly {
+  severity: Severity;
+}[]): SeverityCounts;
+/**
+ * Total order over violations, so two runs of the same analysis produce byte-identical
+ * output. Required by baselines, CI diffing, and snapshot tests; without it, ordering
+ * follows rule registration order and each rule's internal scan order, which differs
+ * between hosts because module insertion order does.
+ */
+declare function compareViolations(a: Violation, b: Violation): number;
+//#endregion
+//#region src/contracts/diagnostic.d.ts
+/** Alias, for readability at use sites — it IS {@link Severity}. */
+type DiagnosticSeverity = Severity;
+/**
+ * Stable, machine-matchable identifiers. Open union — adapters and third-party rules may
+ * emit their own codes; the ones core emits are enumerated by {@link WellKnownDiagnosticCode}.
+ */
+type WellKnownDiagnosticCode =
+/** A rule required host capabilities this run cannot provide, and was skipped. */
+"rule-skipped" |
+/** A rule threw. The run continued; that rule produced no results. */
+"rule-failed" |
+/** Classification tagged nothing — almost always a misconfigured `sourceRoot`. */
+"no-modules-classified" |
+/** The project boundary (`include`/`exclude`) matched no source modules. */
+"empty-project" |
+/** A rule's `scope` narrowed the graph to nothing, so the rule could not report anything. */
+"empty-scope" |
+/** A rule's options failed its `optionsSchema` at config time; the rule did not run. */
+"invalid-rule-options" |
+/** The configuration itself is wrong; see the message. The rule or preset was dropped. */
+"invalid-config" |
+/** A configured rule, or one of its options, is deprecated. */
+"rule-deprecated" |
+/** A graph transform threw. The pipeline continued without its contribution. */
+"transform-failed";
+type DiagnosticCode = WellKnownDiagnosticCode | (string & {});
+/**
+ * Everything the run wants to say that is *not* a violation of the user's architecture: a
+ * rule that could not run, a rule that crashed, a configuration that looks wrong.
+ *
+ * A first-class channel because the alternative — an exception — is the wrong shape for
+ * "one of your forty rules is broken": it destroys the other thirty-nine results.
+ */
+interface Diagnostic {
+  code: DiagnosticCode;
+  severity: DiagnosticSeverity;
+  message: string;
+  /** The rule instance this concerns, when it concerns one. */
+  ruleId?: string;
+  /** Structured payload for machine consumers; shape depends on `code`. */
+  details?: Readonly<Record<string, unknown>>;
+}
+/** Payload shape for `code: "rule-skipped"`. */
+interface RuleSkippedDetails {
+  missingCapabilities: readonly Capability[];
+  host: string;
+}
+/** Payload shape for `code: "empty-scope"`. */
+interface EmptyScopeDetails {
+  /** The scope as configured, so the message can be acted on without reopening the config. */
+  scope: {
+    include?: readonly string[];
+    exclude?: readonly string[];
+    tag?: Record<string, string>;
+  };
+  /** Modules in the graph before scoping — the denominator that makes "0" meaningful. */
+  totalModules: number;
+}
+//#endregion
+//#region src/graph/query.d.ts
+interface ModuleFilter {
+  /** ALL entries must match module tags. */
+  tag?: Record<string, string>;
+  /**
+   * Any listed kind matches. `FIRST_PARTY_KINDS` / `THIRD_PARTY_KINDS` cover the two
+   * groupings that are actually meaningful.
+   */
+  moduleKind?: ModuleKind | readonly ModuleKind[];
+  packageName?: string;
+}
+interface EdgeFilter {
+  kind?: EdgeKind;
+  /** Any listed kind matches, applied to the edge's target. */
+  toModuleKind?: ModuleKind | readonly ModuleKind[];
+  fromTag?: Record<string, string>;
+  toTag?: Record<string, string>;
+  /** Tag key; keep edge iff BOTH endpoints have the tag and values differ. */
+  crossing?: string;
+}
+/**
+ * Stable key for a filter, so the engine can bucket rules that want the same slice of the
+ * graph and evaluate that slice once for all of them.
+ */
+declare function filterKey(filter: EdgeFilter | ModuleFilter | undefined): string;
+/**
+ * The adjacency and attribute indexes over one graph, built LAZILY per axis.
+ *
+ * One index serves every query over a graph, scoped or not: a scope narrows *which results
+ * are returned*, and does not change what the graph contains, so it must never rebuild the
+ * index of it.
+ *
+ * Each axis is built on first use. A run whose rules only walk edges never pays for the
+ * tag, kind, and package indexes.
+ */
+declare class GraphIndex {
+  #private;
+  constructor(graph: ProjectGraph);
+  outOf(id: ModuleId): readonly Edge[];
+  into(id: ModuleId): readonly Edge[];
+  byTag(key: string, value: string): readonly ModuleId[];
+  byKind(kind: ModuleKind): readonly ModuleNode[];
+  byPackage(name: string): readonly ModuleNode[];
+}
+/**
+ * A set of modules, with the operations a rule actually performs on one.
+ *
+ * An interface rather than a class: a selection carries the query it came from, and one
+ * built by hand against a different graph would answer edge questions about the wrong one.
+ * Only {@link GraphQuery} can produce one.
+ */
+interface ModuleSelection extends Iterable<ModuleNode> {
+  readonly size: number;
+  isEmpty(): boolean;
+  toArray(): readonly ModuleNode[];
+  ids(): ModuleId[];
+  forEach(fn: (m: ModuleNode) => void): void;
+  /** Chainable: narrows this selection without going back to the graph. */
+  filter(predicate: (m: ModuleNode) => boolean): ModuleSelection;
+  edgesOut(filter?: EdgeFilter): readonly Edge[];
+  /** The mirror of {@link edgesOut}: edges arriving at any module in this selection. */
+  edgesIn(filter?: EdgeFilter): readonly Edge[];
+}
+/**
+ * The only sanctioned way to read a graph.
+ *
+ * A scoped query is a VIEW: it shares the underlying {@link GraphIndex} with the query it
+ * came from and differs only in which modules it is *about*.
+ *
+ * ## What scope does, exactly
+ *
+ * One rule: **an operation is scoped if and only if it ENUMERATES. An operation that answers a
+ * question about a module you named is never scoped.**
+ *
+ * | Operation | Scoped |
+ * |---|---|
+ * | `modules`, `moduleIds`, `moduleCount`, `edges` | yes — they enumerate |
+ * | `module`, `has`, `tagOf` | no — you named the module |
+ * | `edgesOutOf`, `edgesInto` | no — you named the module |
+ * | `reachableFrom`, `reaching`, `pathBetween` | no — traversal from a named module |
+ * | `ModuleSelection.edgesOut` / `edgesIn` | anchored: endpoints in-selection, edges unfiltered |
+ * | `RuleContext.compute` | yes — a computation enumerates |
+ *
+ * The asymmetry is deliberate rather than incidental. A scoped rule must be able to ask what an
+ * out-of-scope import target *is*, because an edge leaving the scope is the most interesting
+ * thing it can find; hiding the target would turn `layer-dependencies` under a scope from a
+ * finding into silence.
+ */
+declare class GraphQuery {
+  #private;
+  constructor(graph: ProjectGraph, index?: GraphIndex, scope?: ReadonlySet<ModuleId>);
+  /** A view of the same graph restricted to `scope`, sharing this query's index. */
+  scoped(scope: ReadonlySet<ModuleId>): GraphQuery;
+  module(id: ModuleId): ModuleNode | undefined;
+  /** Modules in scope, or all of them when unscoped. */
+  moduleCount(): number;
+  /** Every in-scope module id, in graph order. The traversal primitive. */
+  moduleIds(): Iterable<ModuleId>;
+  /** Whether the graph contains this module at all — distinct from "is it a source file". */
+  has(id: ModuleId): boolean;
+  tagOf(id: ModuleId, key: string): string | undefined;
+  modules(filter?: ModuleFilter): ModuleSelection;
+  /**
+   * In-scope edges matching `filter`.
+   *
+   * Returns the graph's own array when nothing narrows it — it is already immutable, so a
+   * defensive copy per call would protect nobody and cost a full edge list per rule.
+   */
+  edges(filter?: EdgeFilter): readonly Edge[];
+  edgesOutOf(id: ModuleId): readonly Edge[];
+  edgesInto(id: ModuleId): readonly Edge[];
+  /**
+   * Every module reachable from `id` by following edges, excluding `id` itself unless a
+   * cycle leads back to it. Iterative: a 10k-module chain would overflow the stack.
+   */
+  reachableFrom(id: ModuleId, filter?: EdgeFilter): ReadonlySet<ModuleId>;
+  /** The mirror of {@link reachableFrom}: everything that can reach `id`. */
+  reaching(id: ModuleId, filter?: EdgeFilter): ReadonlySet<ModuleId>;
+  /**
+   * Shortest dependency path from `from` to `to`, inclusive of both, or null. BFS, because
+   * the useful evidence for "domain reaches infrastructure" is the shortest chain, not
+   * whichever one a traversal happened to find first.
+   */
+  pathBetween(from: ModuleId, to: ModuleId, filter?: EdgeFilter): readonly ModuleId[] | null;
+  /** Applies an {@link EdgeFilter} to an edge list. Returns the input when there is none. */
+  filterEdges(edges: readonly Edge[], filter?: EdgeFilter): readonly Edge[];
+  /** Whether one edge satisfies a filter. The unit the engine's visitor dispatch uses. */
+  matchesEdge(e: Edge, filter: EdgeFilter): boolean;
+  /** Whether one module satisfies a filter. Paired with {@link matchesEdge}. */
+  matchesModule(m: ModuleNode, filter: ModuleFilter): boolean;
+}
+//#endregion
+//#region src/contracts/analysis.d.ts
+/**
+ * A memoized derived value over the graph — an SCC decomposition, a reachability table —
+ * computed at most once per run and shared by every rule that asks for it.
+ *
+ * Named `GraphComputation` rather than `Analysis` because "analysis" already meant four
+ * other things: `AnalysisResult` (the run's output), `AnalysisStats`, `AnalysisCache`, and
+ * `analyze()`, plus a directory called `analysis/`. Four meanings for one word in one
+ * codebase is a thing contributors conflate weekly; the run-output family keeps the name
+ * and this — the odd one out — gives it up.
+ */
+interface GraphComputation<T> {
+  name: string;
+  compute(graph: GraphQuery): T;
+}
+declare function defineGraphComputation<T>(computation: GraphComputation<T>): GraphComputation<T>;
+//#endregion
+//#region src/contracts/transform.d.ts
+interface TransformContext {
+  /** Absolute source root from resolved config. */
+  sourceRoot: string;
+  /** Absolute repository root from resolved config. */
+  repoRoot: string;
+  /** A file's path relative to {@link sourceRoot}, or null when it lies outside. */
+  relative(file: string): string | null;
+}
+/**
+ * A pass that enriches the graph, between the project boundary and classification.
+ *
+ * The slot a TypeScript type-edge enricher — or any other "add facts the bundler did not
+ * give us" pass — lives in. Ordered after the boundary so a transform sees which modules
+ * are actually in the project, and before classification so anything it adds gets tagged
+ * like everything else. Modules a transform adds are boundary-checked too: the pipeline
+ * runs the boundary again over its contributions rather than trusting them.
+ *
+ * A transform may also declare capabilities it CONTRIBUTES. A rule requiring `type-edges`
+ * should run when a transform supplies them, even though no host does — which is the whole
+ * reason capabilities are a set rather than a property of the adapter.
+ */
+interface GraphTransform {
+  name: string;
+  /**
+   * Capabilities this transform adds to the graph. Declaring one is a promise that the
+   * transform actually produced it; rules requiring it will now run.
+   */
+  provides?: Capability[];
+  /**
+   * Writes through {@link GraphMutation} rather than returning a new graph.
+   *
+   * Graph-in/graph-out meant every third-party transform in existence saw and
+   * reconstructed the concrete representation, which froze it — and invited the whole
+   * class of bug where a transform rebuilds a graph and silently drops a field it did not
+   * know about.
+   *
+   * A transform that throws is isolated the same way a rule is: reported as a diagnostic,
+   * its partial writes discarded, and the pipeline continues — one broken enricher must
+   * not destroy the whole run.
+   */
+  transform(graph: GraphMutation, ctx: TransformContext): void;
+}
+declare function defineTransform(transform: GraphTransform): GraphTransform;
+//#endregion
+export { THIRD_PARTY_KINDS as $, primarySourceLocation as A, GraphDelivery as B, ViolationLocation as C, locationsOf as D, fingerprintOf as E, defineClassifier as F, MODULE_ID_SCHEMES as G, GraphMutation as H, Capability as I, ModuleKind as J, ModuleId as K, Edge as L, Classifier as M, ClassifierContext as N, primaryEdge as O, TagPatch as P, SourceLocation as Q, EdgeKind as R, ViolationInput as S, countBySeverity as T, HostInfo as U, GraphDraft as V, IR_VERSION as W, ProjectGraph as X, ModuleNode as Y, ProjectGraphInit as Z, WellKnownDiagnosticCode as _, defineGraphComputation as a, isFirstParty as at, SeverityCounts as b, GraphQuery as c, filterKey as d, WellKnownCapability as et, Diagnostic as f, RuleSkippedDetails as g, EmptyScopeDetails as h, GraphComputation as i, irMajor as it, renderMessage as j, primaryModule as k, ModuleFilter as l, DiagnosticSeverity as m, TransformContext as n, assertIrCompatible as nt, EdgeFilter as o, isThirdParty as ot, DiagnosticCode as p, ModuleIdScheme as q, defineTransform as r, displayModuleId as rt, GraphIndex as s, parseModuleId as st, GraphTransform as t, WellKnownEdgeKind as tt, ModuleSelection as u, FINGERPRINT_SCHEME as v, compareViolations as w, Violation as x, Severity as y, FIRST_PARTY_KINDS as z };
+//# sourceMappingURL=transform-CnUPOO0E.d.mts.map