@opensip-cli/graph 0.1.0

package/dist/cli/orchestrate/__tests__/sharded-graph.test.js

@@ -0,0 +1,257 @@
+/**
+ * Sharded build pipeline (`runShardedGraph`) — the unified top-level
+ * orchestration: plan → run shards in parallel → merge + recover
+ * cross-package edges → persist (optional) → derive indexes + run rules.
+ *
+ * Drives real shard-worker child processes via a fixture "CLI" script
+ * (same approach as shard-runner-spawn) so the whole pipeline runs
+ * without a TypeScript build. Two shards each contribute one occurrence;
+ * the assertions check the unified catalog, derived indexes, rule
+ * signals, cache-hit flag, and failed-shard attribution.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DataStoreFactory } from '@opensip-cli/datastore';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { stampEngineVersion } from '../../../cache/engine-version.js';
+import { CatalogRepo } from '../../../persistence/catalog-repo.js';
+import { runShardedGraph } from '../sharded-graph.js';
+// Fixture worker: emits one exported function occurrence per shard, named
+// after the shard id, so the merged catalog has a predictable shape. A
+// shard id starting with 'fail:' exits non-zero.
+// The real worker stamps the engine version + `mode=sharded` onto the fragment
+// cacheKey via assembleCatalog (ADR-0015 / ADR-0031); the fixture must emit the
+// same stamped key so a no-change rerun is a clean cache hit.
+const STAMPED_KEY = stampEngineVersion('key-none', 'sharded');
+const WORKER_SCRIPT = String.raw `
+const { readFileSync } = require('node:fs');
+const spec = JSON.parse(readFileSync(process.argv[3], 'utf8'));
+const id = spec.shard.id;
+if (id.startsWith('fail:')) { process.stderr.write('boom\n'); process.exit(2); }
+const name = id.replace(/[^a-zA-Z0-9]/g, '_');
+const occ = {
+  bodyHash: 'h-' + id, simpleName: name, qualifiedName: id + '.' + name,
+  filePath: id + '/index.ts', line: 1, column: 0, endLine: 1,
+  kind: 'function-declaration', params: [], returnType: null,
+  enclosingClass: null, decorators: [], visibility: 'exported',
+  inTestFile: false, definedInGenerated: false, calls: [],
+};
+// Echo back the validity keys the planner computes so a no-change rerun
+// is a clean cache hit: cacheKey mirrors adapter.cacheKey (configPathAbs
+// is undefined here → 'key-none'); the fingerprint is computed over the
+// shard's own file list exactly as planShardWork does.
+const { statSync } = require('node:fs');
+const files = spec.shard.files;
+const parts = [String(files.length)];
+for (const f of files) {
+  try { const st = statSync(f); parts.push(f + '|' + String(st.mtimeMs) + '|' + String(st.size)); }
+  catch { parts.push(f + '|missing'); }
+}
+// Shard ids starting with 'bc:' inject one unresolvable boundary call so the
+// shardStats.boundaryCallSites plumbing can be asserted (ADR-0045).
+const boundaryCalls = id.startsWith('bc:')
+  ? [{ ownerHash: 'h-' + id, ownerFile: id + '/index.ts', calleeName: 'nonexistent_callee', line: 1, column: 0, text: 'nonexistent_callee()' }]
+  : [];
+const result = {
+  shardId: id,
+  fragment: {
+    version: '3.0', tool: 'graph', language: 'typescript', builtAt: 'x',
+    cacheKey: ${JSON.stringify(STAMPED_KEY)}, resolutionMode: 'exact', functions: { [name]: [occ] },
+  },
+  fingerprint: parts.join('\n'), boundaryCalls, parseErrors: [],
+};
+process.stdout.write(JSON.stringify(result));
+process.exit(0);
+`;
+// Minimal adapter — only `cacheKey` (cache path) and `ruleHints` are read here.
+const adapter = {
+    id: 'typescript',
+    cacheKey: (i) => `key-${i.configPathAbs ?? 'none'}`,
+    ruleHints: undefined,
+};
+describe('runShardedGraph', () => {
+    let dir;
+    let cliScript;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'sharded-graph-'));
+        cliScript = join(dir, 'fake-cli.cjs');
+        writeFileSync(cliScript, WORKER_SCRIPT, 'utf8');
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    function shard(id) {
+        return { id, rootDir: dir, files: [join(dir, `${id}.ts`)] };
+    }
+    it('merges shard fragments into a unified catalog, derives indexes, and runs rules', async () => {
+        let evaluatedAgainst = null;
+        const rule = {
+            id: 'test.rule',
+            slug: 'test-rule',
+            description: 'counts functions',
+            evaluate: (catalog, _indexes) => {
+                evaluatedAgainst = catalog;
+                return [
+                    {
+                        ruleId: 'test.rule',
+                        message: `saw ${String(Object.keys(catalog.functions).length)} functions`,
+                        severity: 'warning',
+                    },
+                ];
+            },
+        };
+        const out = await runShardedGraph({
+            shards: [shard('pkg:a'), shard('pkg:b')],
+            projectRoot: dir,
+            cliScript,
+            adapter,
+            resolutionMode: 'exact',
+            useCache: false,
+            catalogRepo: null,
+            rules: [rule],
+        });
+        expect(Object.keys(out.catalog.functions).sort()).toEqual(['pkg_a', 'pkg_b']);
+        expect(out.indexes).not.toBeNull();
+        expect(out.cacheHit).toBe(false);
+        expect(out.failedShardIds).toEqual([]);
+        expect(out.signals).toHaveLength(1);
+        expect(out.signals[0]?.message).toBe('saw 2 functions');
+        expect(evaluatedAgainst).not.toBeNull();
+        expect(out.resolutionStats.totalCallSites).toBe(0);
+    });
+    it('reports per-run shard statistics (ADR-0045 measurement plane)', async () => {
+        // Uneven shard sizes (2 files vs 1) pin the descending sort; the 'bc:'
+        // shard injects exactly one boundary call through the worker fixture.
+        const big = {
+            id: 'bc:big',
+            rootDir: dir,
+            files: [join(dir, 'big-1.ts'), join(dir, 'big-2.ts')],
+        };
+        const out = await runShardedGraph({
+            shards: [shard('pkg:a'), big],
+            projectRoot: dir,
+            cliScript,
+            adapter,
+            resolutionMode: 'exact',
+            useCache: false,
+            catalogRepo: null,
+            rules: [],
+        });
+        expect(out.shardStats.shardCount).toBe(2);
+        expect(out.shardStats.shardsBuilt + out.shardStats.shardsCached).toBe(2);
+        expect(out.shardStats.shardSizes).toEqual([2, 1]);
+        expect(out.shardStats.boundaryCallSites).toBe(1);
+    });
+    it('emits the seven canonical stages onto onProgress (ADR-0032: engine-agnostic live view)', async () => {
+        // The sharded build maps its work onto the SAME stages the single-program
+        // (`runGraph`) path emits, so the live renderer shows one "Code Graph"
+        // checklist for both engines. This pins the order + the discover/parse/walk/
+        // resolve/rules sub-labels the runner surfaces.
+        const events = [];
+        await runShardedGraph({
+            shards: [shard('pkg:a'), shard('pkg:b')],
+            projectRoot: dir,
+            cliScript,
+            adapter,
+            resolutionMode: 'exact',
+            useCache: false,
+            catalogRepo: null,
+            rules: [],
+            onProgress: (e) => events.push({
+                type: e.type,
+                stage: e.stage,
+                ...(e.detail === undefined ? {} : { detail: e.detail }),
+            }),
+        });
+        // Each of the 7 stages fires exactly one start + one done, in canonical order.
+        const stageOrder = ['discover', 'parse', 'walk', 'resolve', 'index', 'features', 'rules'];
+        const dones = events.filter((e) => e.type === 'stage-done').map((e) => e.stage);
+        expect(dones).toEqual(stageOrder);
+        const starts = events.filter((e) => e.type === 'stage-start').map((e) => e.stage);
+        expect(starts).toEqual(stageOrder);
+        // The familiar sub-labels carry the sharded work onto the exact checklist.
+        const detailOf = (stage) => events.find((e) => e.type === 'stage-done' && e.stage === stage)?.detail;
+        expect(detailOf('discover')).toBe('2 files');
+        expect(detailOf('parse')).toBe('2 shards');
+        expect(detailOf('walk')).toBe('2 functions');
+        // Catalog-derived TOTAL call-site count — the SAME engine-agnostic metric
+        // the exact path reports, with no "cross-shard" implementation leakage.
+        expect(detailOf('resolve')).toMatch(/^\d+ call site\(s\)$/);
+        expect(detailOf('resolve')).not.toMatch(/cross-shard/);
+        expect(detailOf('rules')).toBe('0 rule(s), 0 signal(s)');
+    });
+    it('throws (fails loud) when two shards share an id', async () => {
+        // Duplicate ids collide on the fragment-cache primary key and silently
+        // corrupt the warm-build cache → non-determinism. The orchestrator must
+        // refuse to build rather than return a quietly-wrong graph.
+        await expect(runShardedGraph({
+            shards: [shard('engine'), shard('engine')],
+            projectRoot: dir,
+            cliScript,
+            adapter,
+            resolutionMode: 'exact',
+            useCache: false,
+            catalogRepo: null,
+            rules: [],
+        })).rejects.toThrow(/Duplicate shard id\(s\) \[engine\]/);
+    });
+    it('records a failed shard id while still building the rest of the catalog', async () => {
+        const out = await runShardedGraph({
+            shards: [shard('pkg:a'), shard('fail:b')],
+            projectRoot: dir,
+            cliScript,
+            adapter,
+            resolutionMode: 'exact',
+            useCache: false,
+            catalogRepo: null,
+            rules: [],
+        });
+        expect(out.failedShardIds).toEqual(['fail:b']);
+        expect(Object.keys(out.catalog.functions)).toEqual(['pkg_a']);
+        expect(out.signals).toEqual([]);
+    });
+    it('persists fragments and reports cacheHit when every shard is reused from cache', async () => {
+        const datastore = DataStoreFactory.open({ backend: 'memory' });
+        const repo = new CatalogRepo(datastore);
+        try {
+            const shards = [shard('pkg:a'), shard('pkg:b')];
+            // First run: cache cold, both shards built and their fragments persisted.
+            const first = await runShardedGraph({
+                shards,
+                projectRoot: dir,
+                cliScript,
+                adapter,
+                resolutionMode: 'exact',
+                useCache: true,
+                catalogRepo: repo,
+                rules: [],
+            });
+            expect(first.cacheHit).toBe(false);
+            // Second run: nothing changed → every shard reused, no worker runs.
+            const second = await runShardedGraph({
+                shards,
+                projectRoot: dir,
+                cliScript,
+                adapter,
+                resolutionMode: 'exact',
+                useCache: true,
+                catalogRepo: repo,
+                rules: [],
+            });
+            expect(second.cacheHit).toBe(true);
+            expect(Object.keys(second.catalog.functions).sort()).toEqual(['pkg_a', 'pkg_b']);
+            // F4 (Phase 7): the WARM build (fragments served from the REAL
+            // graph_shard_fragment cache, not a second in-memory rebuild) must be
+            // byte-identical to the COLD build, modulo the wall-clock `builtAt`. This
+            // exercises the actual datastore cache path the in-memory equivalence
+            // harness structurally cannot, locking determinism on the real cache.
+            const canon = (c) => JSON.stringify({ ...c, builtAt: 'EXCLUDED' });
+            expect(canon(second.catalog)).toBe(canon(first.catalog));
+        }
+        finally {
+            datastore.close?.();
+        }
+    });
+});
+//# sourceMappingURL=sharded-graph.test.js.map

package/dist/cli/orchestrate/__tests__/sharded-graph.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharded-graph.test.js","sourceRoot":"","sources":["../../../../src/cli/orchestrate/__tests__/sharded-graph.test.ts"],"names":[],"mappings":"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"}

package/dist/cli/orchestrate/__tests__/worker-pool.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The shared bounded worker pool — runs every item, never exceeds the
+ * concurrency cap, and tolerates a slot count larger than the item count.
+ */
+export {};
+//# sourceMappingURL=worker-pool.test.d.ts.map

package/dist/cli/orchestrate/__tests__/worker-pool.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-pool.test.d.ts","sourceRoot":"","sources":["../../../../src/cli/orchestrate/__tests__/worker-pool.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/cli/orchestrate/__tests__/worker-pool.test.js

@@ -0,0 +1,38 @@
+/**
+ * The shared bounded worker pool — runs every item, never exceeds the
+ * concurrency cap, and tolerates a slot count larger than the item count.
+ */
+import { describe, expect, it } from 'vitest';
+import { runWorkerPool } from '../worker-pool.js';
+describe('runWorkerPool', () => {
+    it('runs every item exactly once', async () => {
+        const items = [1, 2, 3, 4, 5];
+        const results = await runWorkerPool(items, 2, (n) => Promise.resolve(n * 10));
+        expect([...results].sort((a, b) => a - b)).toEqual([10, 20, 30, 40, 50]);
+    });
+    it('never exceeds the concurrency cap', async () => {
+        let active = 0;
+        let peak = 0;
+        const run = async (n) => {
+            active++;
+            peak = Math.max(peak, active);
+            await new Promise((r) => setTimeout(r, 5));
+            active--;
+            return n;
+        };
+        await runWorkerPool([1, 2, 3, 4, 5, 6, 7, 8], 3, run);
+        expect(peak).toBeLessThanOrEqual(3);
+    });
+    it('clamps a zero/negative cap to at least one slot and still completes', async () => {
+        const results = await runWorkerPool([1, 2, 3], 0, (n) => Promise.resolve(n));
+        expect([...results].sort((a, b) => a - b)).toEqual([1, 2, 3]);
+    });
+    it('handles an empty item list', async () => {
+        expect(await runWorkerPool([], 4, () => Promise.resolve(1))).toEqual([]);
+    });
+    it('throws on non-finite concurrency (NaN, Infinity) rather than producing zero workers', async () => {
+        await expect(runWorkerPool([1], Number.NaN, (n) => Promise.resolve(n))).rejects.toThrow(/concurrency must be a finite number/);
+        await expect(runWorkerPool([1], Infinity, (n) => Promise.resolve(n))).rejects.toThrow(/concurrency must be a finite number/);
+    });
+});
+//# sourceMappingURL=worker-pool.test.js.map

package/dist/cli/orchestrate/__tests__/worker-pool.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-pool.test.js","sourceRoot":"","sources":["../../../../src/cli/orchestrate/__tests__/worker-pool.test.ts"],"names":[],"mappings":"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"}

package/dist/cli/orchestrate/cache-orchestrator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Cache hit/miss/incremental routing.
+ *
+ * Consults the on-disk catalog cache and dispatches to the right
+ * rebuild path per `classifyCatalog`'s verdict:
+ *   - 'valid'        → reuse the cached catalog wholesale
+ *   - 'incremental'  → re-walk only changed files + their dependents
+ *   - 'invalid'      → full rebuild
+ */
+import { type RunStage } from './catalog-builder.js';
+import type { GraphProgressCallback } from './types.js';
+import type { DiscoverOutput, GraphLanguageAdapter } from '../../lang-adapter/types.js';
+import type { CatalogRepo } from '../../persistence/catalog-repo.js';
+import type { Catalog, ResolutionMode, ResolutionStats } from '../../types.js';
+import type { PressureMonitor } from '../pressure-monitor.js';
+export interface ObtainCatalogInput {
+    readonly runStage: RunStage;
+    readonly adapter: GraphLanguageAdapter;
+    readonly discovery: DiscoverOutput;
+    readonly catalogRepo: CatalogRepo | null;
+    readonly useCache: boolean;
+    /** Active resolution tier. Folded into the cacheKey so fast/exact
+     *  catalogs never collide, and forwarded into the build path. */
+    readonly resolutionMode: ResolutionMode;
+    /** Absolute project root — used to stamp each occurrence's package via its
+     *  nearest `package.json` (see `assignPackages`). */
+    readonly projectRoot: string;
+    readonly onProgress?: GraphProgressCallback;
+    readonly monitor?: PressureMonitor;
+}
+export interface ObtainCatalogOutput {
+    readonly catalog: Catalog;
+    readonly cacheHit: boolean;
+    readonly resolutionStats: ResolutionStats | null;
+}
+/**
+ * Resolve the catalog for this run by consulting the on-disk cache,
+ * dispatching to the right rebuild path (full vs Wave 4 incremental
+ * vs cache hit) per `classifyCatalog`'s verdict.
+ */
+export declare function obtainCatalog(input: ObtainCatalogInput): Promise<ObtainCatalogOutput>;
+//# sourceMappingURL=cache-orchestrator.d.ts.map

package/dist/cli/orchestrate/cache-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-orchestrator.d.ts","sourceRoot":"","sources":["../../../src/cli/orchestrate/cache-orchestrator.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAKH,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,sBAAsB,CAAC;AAI9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;qEACiE;IACjE,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;yDACqD;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,eAAe,GAAG,IAAI,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA+E3F"}

package/dist/cli/orchestrate/cache-orchestrator.js

@@ -0,0 +1,92 @@
+// @fitness-ignore-file error-handling-quality -- catalogRepo.replaceAll write failure is non-fatal and already logged inside the repo (see inline comment at the catch); the orchestrator returns the freshly-built catalog regardless so the run never hangs on cache persistence.
+/**
+ * Cache hit/miss/incremental routing.
+ *
+ * Consults the on-disk catalog cache and dispatches to the right
+ * rebuild path per `classifyCatalog`'s verdict:
+ *   - 'valid'        → reuse the cached catalog wholesale
+ *   - 'incremental'  → re-walk only changed files + their dependents
+ *   - 'invalid'      → full rebuild
+ */
+import { stampEngineVersion } from '../../cache/engine-version.js';
+import { classifyCatalog, computeFilesFingerprint } from '../../cache/invalidate.js';
+import { buildAndResolveCatalog, buildAndResolveCatalogIncremental, } from './catalog-builder.js';
+import { stampAndConstrainPackages } from './cross-shard-resolve.js';
+import { recoverExactBoundaryEdges } from './exact-boundary-recovery.js';
+/**
+ * Resolve the catalog for this run by consulting the on-disk cache,
+ * dispatching to the right rebuild path (full vs Wave 4 incremental
+ * vs cache hit) per `classifyCatalog`'s verdict.
+ */
+export async function obtainCatalog(input) {
+    const cachedCatalog = input.useCache && input.catalogRepo ? input.catalogRepo.loadFullCatalog() : null;
+    const currentCacheKey = stampEngineVersion(input.adapter.cacheKey({
+        projectDirAbs: input.discovery.projectDirAbs,
+        configPathAbs: input.discovery.configPathAbs,
+        compilerOptions: input.discovery.compilerOptions,
+        resolutionMode: input.resolutionMode,
+    }));
+    const verdict = cachedCatalog
+        ? classifyCatalog(cachedCatalog, {
+            currentLanguage: input.adapter.id,
+            currentCacheKey,
+            currentFiles: input.discovery.files,
+        })
+        : { kind: 'invalid', reason: 'no-cache' };
+    if (verdict.kind === 'valid' && cachedCatalog) {
+        // Parse/walk/resolve are skipped wholesale. Tell the view so it can
+        // render those stages as "(cached)" rather than leaving them pending.
+        for (const stage of ['parse', 'walk', 'resolve']) {
+            input.onProgress?.({ type: 'stage-cached', stage });
+        }
+        return { catalog: cachedCatalog, cacheHit: true, resolutionStats: null };
+    }
+    const built = verdict.kind === 'incremental' && cachedCatalog
+        ? await buildAndResolveCatalogIncremental({
+            runStage: input.runStage,
+            adapter: input.adapter,
+            discovery: input.discovery,
+            cachedCatalog,
+            changedFilesAbs: verdict.changedFiles,
+            resolutionMode: input.resolutionMode,
+            onProgress: input.onProgress,
+            monitor: input.monitor,
+            emitBoundaryCalls: true,
+        })
+        : await buildAndResolveCatalog({
+            runStage: input.runStage,
+            adapter: input.adapter,
+            discovery: input.discovery,
+            resolutionMode: input.resolutionMode,
+            onProgress: input.onProgress,
+            monitor: input.monitor,
+            emitBoundaryCalls: true,
+        });
+    // ONE resolution model (Phase 3, Option A): the single-program (exact) catalog
+    // IS the whole/merged catalog, so run the SAME cross-shard linker the sharded
+    // engine runs post-merge over its syntactic boundary calls. This converges the
+    // two engines — exact is the 1-shard case — resolving the cross-package call
+    // sites exact's type-checker-driven inline pass captures inconsistently (it
+    // only fires where `getSymbolAtLocation` succeeds and the reference kind
+    // dispatches; the syntactic boundary extractor captures every imported call
+    // site). The extractor already skips sites resolved inline, so no double edge.
+    const recovered = recoverExactBoundaryEdges(built, input.discovery.files, input.projectRoot);
+    // Stamp packages (nearest package.json), then drop name-guessed edges that
+    // contradict the import graph. Order matters: the constraint reads the
+    // stamped `occurrence.package`.
+    const catalog = stampAndConstrainPackages({
+        ...recovered,
+        filesFingerprint: computeFilesFingerprint(input.discovery.files),
+    }, input.projectRoot);
+    if (input.useCache && input.catalogRepo) {
+        try {
+            input.catalogRepo.replaceAll(catalog);
+        }
+        catch {
+            /* v8 ignore next */
+            // Cache write failure is non-fatal — already logged.
+        }
+    }
+    return { catalog, cacheHit: false, resolutionStats: built.resolutionStats };
+}
+//# sourceMappingURL=cache-orchestrator.js.map

package/dist/cli/orchestrate/cache-orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-orchestrator.js","sourceRoot":"","sources":["../../../src/cli/orchestrate/cache-orchestrator.ts"],"names":[],"mappings":"AAAA,oRAAoR;AACpR;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAErF,OAAO,EACL,sBAAsB,EACtB,iCAAiC,GAElC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AA8BzE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAyB;IAC3D,MAAM,aAAa,GACjB,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACnF,MAAM,eAAe,GAAG,kBAAkB,CACxC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QACrB,aAAa,EAAE,KAAK,CAAC,SAAS,CAAC,aAAa;QAC5C,aAAa,EAAE,KAAK,CAAC,SAAS,CAAC,aAAa;QAC5C,eAAe,EAAE,KAAK,CAAC,SAAS,CAAC,eAAe;QAChD,cAAc,EAAE,KAAK,CAAC,cAAc;KACrC,CAAC,CACH,CAAC;IACF,MAAM,OAAO,GAAG,aAAa;QAC3B,CAAC,CAAC,eAAe,CAAC,aAAa,EAAE;YAC7B,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE;YACjC,eAAe;YACf,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK;SACpC,CAAC;QACJ,CAAC,CAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAY,CAAC;IAEvD,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,IAAI,aAAa,EAAE,CAAC;QAC9C,oEAAoE;QACpE,sEAAsE;QACtE,KAAK,MAAM,KAAK,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAU,EAAE,CAAC;YAC1D,KAAK,CAAC,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;QACtD,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;IAC3E,CAAC;IACD,MAAM,KAAK,GACT,OAAO,CAAC,IAAI,KAAK,aAAa,IAAI,aAAa;QAC7C,CAAC,CAAC,MAAM,iCAAiC,CAAC;YACtC,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,aAAa;YACb,eAAe,EAAE,OAAO,CAAC,YAAY;YACrC,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,iBAAiB,EAAE,IAAI;SACxB,CAAC;QACJ,CAAC,CAAC,MAAM,sBAAsB,CAAC;YAC3B,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,iBAAiB,EAAE,IAAI;SACxB,CAAC,CAAC;IAET,+EAA+E;IAC/E,8EAA8E;IAC9E,+EAA+E;IAC/E,6EAA6E;IAC7E,4EAA4E;IAC5E,yEAAyE;IACzE,4EAA4E;IAC5E,+EAA+E;IAC/E,MAAM,SAAS,GAAG,yBAAyB,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAE7F,2EAA2E;IAC3E,uEAAuE;IACvE,gCAAgC;IAChC,MAAM,OAAO,GAAY,yBAAyB,CAChD;QACE,GAAG,SAAS;QACZ,gBAAgB,EAAE,uBAAuB,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC;KACjE,EACD,KAAK,CAAC,WAAW,CAClB,CAAC;IACF,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QACxC,IAAI,CAAC;YACH,KAAK,CAAC,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,oBAAoB;YACpB,qDAAqD;QACvD,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,CAAC,eAAe,EAAE,CAAC;AAC9E,CAAC"}

package/dist/cli/orchestrate/canonical-file-set.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Canonical graph file set — the SINGLE definition of "which files the graph
+ * tool analyzes," shared by BOTH build engines (exact single-program and
+ * sharded parallel).
+ *
+ * Phase 1 of graph-sharded-exact-parity (ADR-0031 lineage). Before this, the
+ * two engines discovered DIFFERENT file sets:
+ *   - exact   walked the ROOT tsconfig (no include/exclude) → EVERY `.ts(x)`,
+ *             fixtures AND tests included;
+ *   - sharded enumerated each PACKAGE tsconfig, which excludes that package's
+ *             `__fixtures__` tree and (for some packages) its test files.
+ * The result was a ~2,500-occurrence catalog gap (measured via
+ * `scripts/graph-catalog-diff.mjs`) and two engines that could never agree.
+ *
+ * The maintainer's Phase-0 ruling (LOCKED): the canonical graph is
+ * **production code + real test files, with `__fixtures__/` EXCLUDED**, applied
+ * identically to both engines. Real test files are KEPT — they're needed for
+ * `test-only-reachable` and for test → production blast/coverage edges.
+ * `__fixtures__/` is synthetic test-INPUT code (fitness-check sample sources,
+ * graph fixtures) that is noise in a real call graph.
+ *
+ * This module owns that decision as ONE pure predicate ({@link isFixturePath})
+ * and ONE pure filter ({@link resolveCanonicalFileSet}) over file paths. Both
+ * engines feed their project-wide root discovery through `resolveCanonicalFileSet`
+ * so they see the identical set; the sharded engine then PARTITIONS that set
+ * across shards rather than re-deriving each shard's files from a package
+ * tsconfig (see `partition-files.ts`).
+ */
+/**
+ * The canonical fixture predicate: a path is a fixture iff it contains a
+ * `/__fixtures__/` segment anywhere in its (forward-slash-normalized) path.
+ *
+ * Pure and string-only — it makes no filesystem call and is agnostic to whether
+ * the input is absolute or project-relative. Normalizes Windows `\` to `/`
+ * first so the segment match is OS-independent. This is the ONLY place the
+ * fixture convention is encoded; both engines and the parity test reference it.
+ */
+export declare function isFixturePath(filePath: string): boolean;
+/**
+ * Reduce a raw discovered file set to the canonical graph set: drop every
+ * fixture path, keep everything else (production AND real test files).
+ *
+ * Pure over the input array — returns a NEW array, preserves input order, and
+ * never touches the filesystem. Both engines call this on the SAME project-wide
+ * root discovery so their inputs to parse/walk are byte-identical.
+ *
+ * @param files - raw discovered absolute file paths (e.g. `DiscoverOutput.files`).
+ * @returns the subset with `__fixtures__/` paths removed.
+ */
+export declare function resolveCanonicalFileSet(files: readonly string[]): readonly string[];
+//# sourceMappingURL=canonical-file-set.d.ts.map

package/dist/cli/orchestrate/canonical-file-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-file-set.d.ts","sourceRoot":"","sources":["../../../src/cli/orchestrate/canonical-file-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAEnF"}

package/dist/cli/orchestrate/canonical-file-set.js

@@ -0,0 +1,58 @@
+/**
+ * Canonical graph file set — the SINGLE definition of "which files the graph
+ * tool analyzes," shared by BOTH build engines (exact single-program and
+ * sharded parallel).
+ *
+ * Phase 1 of graph-sharded-exact-parity (ADR-0031 lineage). Before this, the
+ * two engines discovered DIFFERENT file sets:
+ *   - exact   walked the ROOT tsconfig (no include/exclude) → EVERY `.ts(x)`,
+ *             fixtures AND tests included;
+ *   - sharded enumerated each PACKAGE tsconfig, which excludes that package's
+ *             `__fixtures__` tree and (for some packages) its test files.
+ * The result was a ~2,500-occurrence catalog gap (measured via
+ * `scripts/graph-catalog-diff.mjs`) and two engines that could never agree.
+ *
+ * The maintainer's Phase-0 ruling (LOCKED): the canonical graph is
+ * **production code + real test files, with `__fixtures__/` EXCLUDED**, applied
+ * identically to both engines. Real test files are KEPT — they're needed for
+ * `test-only-reachable` and for test → production blast/coverage edges.
+ * `__fixtures__/` is synthetic test-INPUT code (fitness-check sample sources,
+ * graph fixtures) that is noise in a real call graph.
+ *
+ * This module owns that decision as ONE pure predicate ({@link isFixturePath})
+ * and ONE pure filter ({@link resolveCanonicalFileSet}) over file paths. Both
+ * engines feed their project-wide root discovery through `resolveCanonicalFileSet`
+ * so they see the identical set; the sharded engine then PARTITIONS that set
+ * across shards rather than re-deriving each shard's files from a package
+ * tsconfig (see `partition-files.ts`).
+ */
+/** The path segment that marks synthetic test-input code excluded from the canonical set. */
+const FIXTURES_SEGMENT = '/__fixtures__/';
+/**
+ * The canonical fixture predicate: a path is a fixture iff it contains a
+ * `/__fixtures__/` segment anywhere in its (forward-slash-normalized) path.
+ *
+ * Pure and string-only — it makes no filesystem call and is agnostic to whether
+ * the input is absolute or project-relative. Normalizes Windows `\` to `/`
+ * first so the segment match is OS-independent. This is the ONLY place the
+ * fixture convention is encoded; both engines and the parity test reference it.
+ */
+export function isFixturePath(filePath) {
+    const normalized = filePath.replaceAll('\\', '/');
+    return normalized.includes(FIXTURES_SEGMENT);
+}
+/**
+ * Reduce a raw discovered file set to the canonical graph set: drop every
+ * fixture path, keep everything else (production AND real test files).
+ *
+ * Pure over the input array — returns a NEW array, preserves input order, and
+ * never touches the filesystem. Both engines call this on the SAME project-wide
+ * root discovery so their inputs to parse/walk are byte-identical.
+ *
+ * @param files - raw discovered absolute file paths (e.g. `DiscoverOutput.files`).
+ * @returns the subset with `__fixtures__/` paths removed.
+ */
+export function resolveCanonicalFileSet(files) {
+    return files.filter((f) => !isFixturePath(f));
+}
+//# sourceMappingURL=canonical-file-set.js.map

package/dist/cli/orchestrate/canonical-file-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-file-set.js","sourceRoot":"","sources":["../../../src/cli/orchestrate/canonical-file-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,6FAA6F;AAC7F,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAClD,OAAO,UAAU,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAwB;IAC9D,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC"}