@opensip-cli/graph 0.1.0

package/dist/cli/orchestrate/cross-shard-resolve.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Cross-shard merge & semantic boundary linking (plan #2, Phase 2).
+ *
+ * After the shard workers return per-shard fragments + cross-boundary
+ * call descriptors, this module:
+ *   1. merges the fragments into one unified catalog (union of occurrences,
+ *      each keeping its already-resolved intra-shard edges);
+ *   2. LINKS the boundary calls semantically against the export symbol table
+ *      ({@link ExportIndex}) + package manifest index ({@link PackageManifestIndex})
+ *      built from the merged catalog and the resolved shard set, then stitches
+ *      the recovered edges onto their owner occurrences as
+ *      `resolution: 'semantic'`, `crossShard: true`, `confidence: 'high'`.
+ *
+ * The linker emits a cross-package edge ONLY when the import specifier + callee
+ * name resolve to a UNIQUE exported occurrence in the imported package — exactly
+ * what the TypeScript type checker would conclude. On ANY ambiguity (a name with
+ * multiple matching exports the subpath can't disambiguate, a name the package
+ * does not export, a specifier pointing at an external npm package) it DECLINES
+ * and emits an unresolved (`to: []`) edge. A missing edge is safe; a phantom
+ * cross-package edge would fail the gate. This replaces the old name-only
+ * syntactic fallback, which fabricated impossible coupling edges by matching a
+ * globally-unique simple name into a package the caller never imported.
+ *
+ * Intra-shard edges retain their original (semantic, in exact mode) fidelity;
+ * relative imports are still path-pinned (already exact for same-package
+ * imports). Engine-layer and language-agnostic: it operates on plain catalog
+ * data + the descriptors' callee names / import specifiers + each package's
+ * `package.json` — no parser, no TypeScript assumptions.
+ */
+import type { ShardBuildResult } from './shard-model.js';
+import type { PackageManifestIndex } from '../../cross-package/export-index.js';
+import type { Catalog, CrossBoundaryCall, ResolutionStats } from '../../types.js';
+/** Output of the cross-shard pass: the unified catalog + boundary-resolution stats. */
+export interface CrossShardOutput {
+    readonly catalog: Catalog;
+    readonly boundaryStats: ResolutionStats;
+}
+/**
+ * Merge per-shard fragments and recover cross-package edges. The single
+ * Phase-2 entry the orchestrator calls.
+ */
+export declare function mergeAndResolveShards(fragments: readonly ShardBuildResult[], allFiles: readonly string[], manifestIndex: PackageManifestIndex): CrossShardOutput;
+/**
+ * Finalize cross-package edges on a merged catalog: stamp each occurrence's
+ * owning package (`assignPackages`) then drop name-guessed cross-package edges
+ * that contradict the import graph (`constrainCrossPackageEdges`). These two
+ * pipeline steps are always applied as a pair on the post-resolve catalog — by
+ * both the sharded build (`runShardedGraph`) and the cached single-program
+ * recovery path (`cache-orchestrator`) — so they live here, the cross-package
+ * resolution module, as one helper rather than duplicated import pairs.
+ */
+export declare function stampAndConstrainPackages(catalog: Catalog, projectRoot: string): Catalog;
+/**
+ * Union every fragment's `functions` map into one catalog. Each
+ * occurrence keeps its already-resolved intra-shard `calls`. Shards are
+ * disjoint by construction (distinct files), so occurrences don't
+ * conflict; a defensive dedup by occurrence IDENTITY — (bodyHash,
+ * filePath, line, column) — drops any accidental duplicate rather than
+ * double-counting.
+ *
+ * The dedup key MUST include `column`: two distinct callables can share a
+ * `(bodyHash, filePath, line)` triple when they sit on the SAME source line
+ * with BYTE-IDENTICAL bodies — e.g. `a.some((p) => p.test(x)) || b.some((p) =>
+ * p.test(x))` (two body-twin arrows on one line). `bodyHash` is a CONTENT hash,
+ * so both twins hash equally; a column-less key collapsed them into one,
+ * dropping the second occurrence the single-program engine keeps. Keying on the
+ * full occurrence identity (filePath:line:column — the same tuple the SCC graph
+ * uses as its node id) makes the merged function set byte-identical to exact
+ * (Phase 3 closed the residual 2-occurrence delta this way).
+ */
+export declare function mergeShardFragments(fragments: readonly Catalog[], allFiles: readonly string[]): Catalog;
+/**
+ * Resolve each cross-boundary call against the merged global catalog and
+ * stitch the recovered edge onto its owner. A recovered edge is `'semantic'`,
+ * `crossShard: true`, `confidence: 'high'` — the import specifier + callee name
+ * linked to a UNIQUE target occurrence (relative imports pin by path; bare /
+ * workspace imports pin by the imported package's export symbol table). On any
+ * ambiguity the resolver DECLINES (`to: []`) — a missing edge is safe, a phantom
+ * cross-package edge is not. Declined / external boundary calls stay unresolved
+ * but are counted (attributable).
+ */
+export declare function resolveCrossBoundaryCalls(merged: Catalog, boundaryCalls: readonly CrossBoundaryCall[], manifestIndex: PackageManifestIndex): CrossShardOutput;
+/**
+ * The full sharded≡exact equivalence verdict — the Phase-4 gate's currency.
+ * Five partitions, ALL of which MUST be empty for the sharded build to be
+ * byte-equivalent to the single-program build:
+ *
+ *  - `functionsOnlyInA` / `functionsOnlyInB` — symmetric difference of the
+ *    occurrence IDENTITY sets (the function set itself). A non-empty side means
+ *    one engine discovered a function the other did not — a discovery/merge
+ *    divergence, NOT an edge difference. (This is the partition that caught the
+ *    two body-twin arrows the column-less merge dedup dropped; see
+ *    `mergeShardFragments`.)
+ *  - `intraMismatches` / `crossDifferences` — edges whose target set differs,
+ *    partitioned by whether either side is a cross-shard (boundary-linked) edge
+ *    (see {@link CatalogEdgeDiff}).
+ *  - `sccDifferences` — strongly-connected components present in one catalog's
+ *    occId-keyed SCC graph but not the other (by sorted-member signature). SCCs
+ *    drive the `cycle` rule's findings, so an SCC divergence is a gate-visible
+ *    divergence even when every individual edge matches (e.g. a dropped function
+ *    that was a cycle member changes the component).
+ *
+ * `equivalence` ⇔ every partition empty.
+ */
+export interface CatalogEquivalence {
+    readonly functionsOnlyInA: readonly string[];
+    readonly functionsOnlyInB: readonly string[];
+    readonly intraMismatches: readonly string[];
+    readonly crossDifferences: readonly string[];
+    readonly sccDifferences: readonly string[];
+    /**
+     * Owner-attributed detail for every differing edge (the union of
+     * `intraMismatches` + `crossDifferences`). Additive: it carries the owner file
+     * path + position the real-repo equivalence guardrail classifies on (and
+     * prints on a budget breach). The five partition arrays above are the
+     * authoritative equivalence verdict (`isEquivalent` ignores this field).
+     */
+    readonly edgeDifferences: readonly EdgeDifference[];
+}
+/**
+ * Full structural diff of two catalogs: function set + edges + SCCs. The
+ * Phase-4 equivalence gate runs this over (sharded, exact) and asserts every
+ * partition empty. Composes the three orthogonal diffs:
+ *   - `diffFunctionSets` — occurrence-identity symmetric difference;
+ *   - `diffCatalogsByEdge` — the per-edge target diff (intra / cross);
+ *   - `diffSccs` — occId-keyed SCC membership diff (reusing the engine's own
+ *     `computeSccs` over `buildIndexes`, so the gate measures the SAME SCCs the
+ *     `cycle` rule consumes).
+ */
+export declare function diffCatalogs(a: Catalog, b: Catalog): CatalogEquivalence;
+/** True when every partition of a {@link CatalogEquivalence} is empty. */
+export declare function isEquivalent(eq: CatalogEquivalence): boolean;
+export interface CatalogEdgeDiff {
+    /** Intra-shard edges whose target differs between the two catalogs. MUST be
+     *  empty for a correct sharded build vs single-program build. */
+    readonly intraMismatches: readonly string[];
+    /**
+     * Cross-package (boundary-linked) edges whose target differs between the two
+     * catalogs. MUST ALSO be empty.
+     *
+     * With semantic linking (Phase 2), the sharded build's cross-package edges
+     * are no longer an approximation of the single-program build's — they are the
+     * SAME edges, recovered by linking each import specifier + callee name to the
+     * UNIQUE exported occurrence the type checker would pick. A non-empty
+     * `crossDifferences` is therefore a correctness REGRESSION (e.g. a name-only
+     * fallback fabricating a phantom edge into a package the caller never
+     * imported, or the linker declining an edge the single program resolves), NOT
+     * an accepted fidelity gap. The Phase 4 equivalence guardrail asserts this
+     * partition empty.
+     */
+    readonly crossDifferences: readonly string[];
+    readonly differences: readonly EdgeDifference[];
+}
+/**
+ * One owner-attributed edge difference. `key` is the same `ownerHash@line:col`
+ * the partition arrays use. `ownerFilePath` is the project-relative path of the
+ * owner occurrence (resolved from whichever catalog holds it — the two catalogs
+ * share occurrence identities, so the owner file is the same on both sides).
+ * `toA` / `toB` are the sorted-joined target sets on each side (one is `''` when
+ * the edge is present only on one side). `cross` mirrors the partition split.
+ */
+export interface EdgeDifference {
+    readonly key: string;
+    readonly ownerFilePath: string;
+    readonly line: number;
+    readonly column: number;
+    readonly toA: string;
+    readonly toB: string;
+    readonly cross: boolean;
+}
+/**
+ * Diff two catalogs by edge, partitioned into intra-shard mismatches and
+ * cross-package (boundary-linked) differences. An edge is keyed by
+ * `ownerHash@line:col → sorted(to)`; a key is a difference when the two
+ * catalogs disagree on its target set. Both partitions MUST be empty for a
+ * correct sharded build vs single-program build: intra-package edges are exact
+ * in both, and semantic boundary linking reproduces the single-program build's
+ * cross-package edges verbatim (Phase 2). The partition only records WHICH side
+ * a difference falls on (cross when either edge is `crossShard`), so a
+ * regression is attributable to the linker vs a local resolver. The Phase 4
+ * equivalence guardrail (`__tests__/equivalence.test.ts`) is the live gate.
+ *
+ * `differences` additionally carries the OWNER FILE PATH + call-site line/column
+ * of every differing edge, so the real-repo equivalence guardrail can classify a
+ * divergence by owner file (test/fixture-owned ⇒ gate-invisible; production ⇒
+ * meaningful) and print the offending `file:line → target` on a budget breach.
+ * The legacy key arrays are unchanged.
+ */
+export declare function diffCatalogsByEdge(a: Catalog, b: Catalog): CatalogEdgeDiff;
+//# sourceMappingURL=cross-shard-resolve.d.ts.map

package/dist/cli/orchestrate/cross-shard-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-shard-resolve.d.ts","sourceRoot":"","sources":["../../../src/cli/orchestrate/cross-shard-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAiBH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAe,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAC7F,OAAO,KAAK,EAEV,OAAO,EACP,iBAAiB,EAGjB,eAAe,EAChB,MAAM,gBAAgB,CAAC;AAExB,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,gBAAgB,EAAE,EACtC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,aAAa,EAAE,oBAAoB,GAClC,gBAAgB,CAOlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAExF;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,OAAO,EAAE,EAC7B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CA2CT;AAkGD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,aAAa,EAAE,oBAAoB,GAClC,gBAAgB,CA2ClB;AA2JD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;CACrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAYvE;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,EAAE,EAAE,kBAAkB,GAAG,OAAO,CAQ5D;AA+DD,MAAM,WAAW,eAAe;IAC9B;qEACiE;IACjE,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;CACjD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,eAAe,CA4B1E"}