@opensip-cli/graph 0.1.0

package/dist/cache/engine-version.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Engine-version cache invalidation (ADR-0015).
+ *
+ * The persisted catalog and per-shard fragment caches let a re-run skip
+ * parse/walk/resolve when nothing relevant changed. Their validity is
+ * keyed on the adapter `cacheKey` (config + tool-version hash) and a
+ * per-file fingerprint — but NOT on the version of the graph engine that
+ * produced them. So upgrading opensip-cli to a build with changed
+ * catalog-construction logic (edge resolution, body hashing, a new
+ * rule-relevant field) would replay a stale catalog when the source was
+ * unchanged: the customer analog of running a stale compiled binary.
+ *
+ * Fix: fold the running engine's package version into the `cacheKey` at
+ * the (language-agnostic) engine boundary, so ANY tool upgrade
+ * invalidates the cache for EVERY adapter — TypeScript and the
+ * tree-sitter languages alike — and the next run rebuilds with the
+ * engine the user actually installed. Over-invalidation (a no-op release
+ * triggers one cold rebuild) is the deliberately safe default.
+ *
+ * Stamping lives in the existing `cacheKey` channel (not a parallel
+ * field) precisely because both cache paths — `classifyCatalog` for the
+ * full catalog and `planShardWork`/`loadValidShardFragment` for shard
+ * fragments — already invalidate on `cacheKey` mismatch. One stamp,
+ * both caches, all languages, and no datastore migration: a pre-stamp
+ * catalog simply mismatches the new prefix and rebuilds once.
+ */
+/**
+ * The running `@opensip-cli/graph` package version, resolved once from
+ * the nearest `package.json`. In a published install this is the version
+ * npm placed on disk; in the monorepo it is `graph/engine`'s version.
+ */
+export declare const ENGINE_VERSION: string;
+/**
+ * The two build engines whose catalogs share the single `graph_catalog`
+ * row (id=1). The exact engine (single-program `runGraph`) and the sharded
+ * engine resolve cross-package edges through ONE shared hop (exact = the
+ * 1-shard case), held equivalent by the directional soundness invariant +
+ * completeness floor (ADR-0033, supersedes ADR-0032), but
+ * the mode is still folded into the `cacheKey` (below) so a mode switch is a
+ * clean, attributable cache miss rather than a silent cross-engine read of a
+ * row built under different orchestration — keeping the two cache lineages
+ * independent and the invalidate logs diagnosable.
+ *
+ * Determinism (ADR-0032, superseding ADR-0031): the default `graph` uses
+ * `'sharded'` when the project is shardable; `'exact'` is reached via the
+ * explicit `--exact` opt-out or when the project isn't shardable.
+ */
+export type EngineMode = 'exact' | 'sharded';
+/**
+ * Prefix an adapter's `cacheKey` with the running engine version AND the
+ * build engine mode so (a) a tool upgrade invalidates persisted
+ * catalogs/fragments, and (b) the exact and sharded engines — which write
+ * the same `graph_catalog` row — keep independent cache lineages and never
+ * read each other's row. Applied at every engine-side cacheKey computation
+ * (build-time stamp + both reuse-decision comparisons), so the stamped and
+ * compared keys always agree.
+ *
+ * `mode` defaults to `'exact'` because the single-program `runGraph` path IS
+ * the exact engine and stamps the default; the (now-default) sharded path
+ * passes `'sharded'` explicitly, including when it derives the merged
+ * build-level key from the per-shard keys.
+ *
+ * The result stays an opaque string per the `Catalog.cacheKey` contract;
+ * the `eng=<version>|mode=<mode>|` prefix is human-legible in the
+ * invalidate logs (`cached:`/`current:`) so a version- or mode-driven
+ * rebuild is diagnosable.
+ */
+export declare function stampEngineVersion(adapterCacheKey: string, mode?: EngineMode): string;
+//# sourceMappingURL=engine-version.d.ts.map

package/dist/cache/engine-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-version.d.ts","sourceRoot":"","sources":["../../src/cache/engine-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAsC,CAAC;AAKlE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAK7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,IAAI,GAAE,UAAoB,GAAG,MAAM,CAE9F"}

package/dist/cache/engine-version.js

@@ -0,0 +1,60 @@
+/**
+ * Engine-version cache invalidation (ADR-0015).
+ *
+ * The persisted catalog and per-shard fragment caches let a re-run skip
+ * parse/walk/resolve when nothing relevant changed. Their validity is
+ * keyed on the adapter `cacheKey` (config + tool-version hash) and a
+ * per-file fingerprint — but NOT on the version of the graph engine that
+ * produced them. So upgrading opensip-cli to a build with changed
+ * catalog-construction logic (edge resolution, body hashing, a new
+ * rule-relevant field) would replay a stale catalog when the source was
+ * unchanged: the customer analog of running a stale compiled binary.
+ *
+ * Fix: fold the running engine's package version into the `cacheKey` at
+ * the (language-agnostic) engine boundary, so ANY tool upgrade
+ * invalidates the cache for EVERY adapter — TypeScript and the
+ * tree-sitter languages alike — and the next run rebuilds with the
+ * engine the user actually installed. Over-invalidation (a no-op release
+ * triggers one cold rebuild) is the deliberately safe default.
+ *
+ * Stamping lives in the existing `cacheKey` channel (not a parallel
+ * field) precisely because both cache paths — `classifyCatalog` for the
+ * full catalog and `planShardWork`/`loadValidShardFragment` for shard
+ * fragments — already invalidate on `cacheKey` mismatch. One stamp,
+ * both caches, all languages, and no datastore migration: a pre-stamp
+ * catalog simply mismatches the new prefix and rebuilds once.
+ */
+import { readPackageVersion } from '@opensip-cli/core';
+/**
+ * The running `@opensip-cli/graph` package version, resolved once from
+ * the nearest `package.json`. In a published install this is the version
+ * npm placed on disk; in the monorepo it is `graph/engine`'s version.
+ */
+export const ENGINE_VERSION = readPackageVersion(import.meta.url);
+/** Cache-key prefix carrying the engine version. */
+const ENGINE_VERSION_PREFIX = 'eng=';
+/** Cache-key segment carrying the build engine mode. */
+const ENGINE_MODE_PREFIX = 'mode=';
+/**
+ * Prefix an adapter's `cacheKey` with the running engine version AND the
+ * build engine mode so (a) a tool upgrade invalidates persisted
+ * catalogs/fragments, and (b) the exact and sharded engines — which write
+ * the same `graph_catalog` row — keep independent cache lineages and never
+ * read each other's row. Applied at every engine-side cacheKey computation
+ * (build-time stamp + both reuse-decision comparisons), so the stamped and
+ * compared keys always agree.
+ *
+ * `mode` defaults to `'exact'` because the single-program `runGraph` path IS
+ * the exact engine and stamps the default; the (now-default) sharded path
+ * passes `'sharded'` explicitly, including when it derives the merged
+ * build-level key from the per-shard keys.
+ *
+ * The result stays an opaque string per the `Catalog.cacheKey` contract;
+ * the `eng=<version>|mode=<mode>|` prefix is human-legible in the
+ * invalidate logs (`cached:`/`current:`) so a version- or mode-driven
+ * rebuild is diagnosable.
+ */
+export function stampEngineVersion(adapterCacheKey, mode = 'exact') {
+    return `${ENGINE_VERSION_PREFIX}${ENGINE_VERSION}|${ENGINE_MODE_PREFIX}${mode}|${adapterCacheKey}`;
+}
+//# sourceMappingURL=engine-version.js.map

package/dist/cache/engine-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-version.js","sourceRoot":"","sources":["../../src/cache/engine-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAElE,oDAAoD;AACpD,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAmBrC,wDAAwD;AACxD,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAEnC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,kBAAkB,CAAC,eAAuB,EAAE,OAAmB,OAAO;IACpF,OAAO,GAAG,qBAAqB,GAAG,cAAc,IAAI,kBAAkB,GAAG,IAAI,IAAI,eAAe,EAAE,CAAC;AACrG,CAAC"}

package/dist/cache/invalidate.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Cache invalidation per §6.2.
+ *
+ * v3: the catalog is content-keyed via three signals:
+ *  1. language       — adapter id; mismatch invalidates immediately.
+ *  2. cacheKey       — opaque per-adapter invalidation key; mismatch
+ *                      invalidates (e.g. TS upgrade or tsconfig change).
+ *  3. filesFingerprint — per-file mtime + size agreement; any source
+ *                      file change re-runs stages 1+2.
+ *
+ * Per-file fingerprinting uses mtime + size to keep the cost low.
+ *
+ * Wave 4 layered an "incremental" verdict on top: when language +
+ * cacheKey agree but some files have changed mtimes, the orchestrator
+ * can re-walk only the changed files (plus their transitive edge-
+ * dependents) instead of rebuilding everything. See `classifyCatalog`
+ * and the orchestrator's incremental path.
+ */
+import type { Catalog } from '../types.js';
+export interface ValidationContext {
+    readonly currentLanguage: string;
+    readonly currentCacheKey: string;
+    readonly currentFiles: readonly string[];
+}
+/**
+ * Wave 4 verdict — three states:
+ *   - 'valid': cached catalog matches current file set on every axis;
+ *     orchestrator returns it untouched.
+ *   - 'incremental': language + cacheKey agree, but some files changed.
+ *     `changedFiles` lists the absolute paths whose cached entries
+ *     must be re-walked. Orchestrator builds the program over all
+ *     current files and only walks/resolves the changed set.
+ *   - 'invalid': structural mismatch (language, cacheKey, missing
+ *     fingerprint). Orchestrator does a full rebuild.
+ */
+export type CatalogVerdict = {
+    readonly kind: 'valid';
+} | {
+    readonly kind: 'incremental';
+    readonly changedFiles: readonly string[];
+} | {
+    readonly kind: 'invalid';
+    readonly reason: string;
+};
+export declare function classifyCatalog(cached: Catalog, ctx: ValidationContext): CatalogVerdict;
+/**
+ * Compute a fingerprint over the project's source files. Uses mtime
+ * (nanosecond resolution) per file plus the file count; cheap to
+ * compute and stable for unchanged trees.
+ */
+export declare function computeFilesFingerprint(files: readonly string[]): string;
+/**
+ * Diff two fingerprints (computed by `computeFilesFingerprint`) and
+ * return the absolute file paths that differ. A file appears in the
+ * result if it was added, removed, or had its mtime/size change. The
+ * leading file-count line is ignored. Used by the incremental
+ * rebuild path.
+ */
+export declare function diffFingerprints(cachedFingerprint: string, currentFingerprint: string): readonly string[];
+//# sourceMappingURL=invalidate.d.ts.map

package/dist/cache/invalidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidate.d.ts","sourceRoot":"","sources":["../../src/cache/invalidate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,GAAG,cAAc,CAyCvF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAWxE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,iBAAiB,EAAE,MAAM,EACzB,kBAAkB,EAAE,MAAM,GACzB,SAAS,MAAM,EAAE,CAYnB"}

package/dist/cache/invalidate.js

@@ -0,0 +1,120 @@
+/**
+ * Cache invalidation per §6.2.
+ *
+ * v3: the catalog is content-keyed via three signals:
+ *  1. language       — adapter id; mismatch invalidates immediately.
+ *  2. cacheKey       — opaque per-adapter invalidation key; mismatch
+ *                      invalidates (e.g. TS upgrade or tsconfig change).
+ *  3. filesFingerprint — per-file mtime + size agreement; any source
+ *                      file change re-runs stages 1+2.
+ *
+ * Per-file fingerprinting uses mtime + size to keep the cost low.
+ *
+ * Wave 4 layered an "incremental" verdict on top: when language +
+ * cacheKey agree but some files have changed mtimes, the orchestrator
+ * can re-walk only the changed files (plus their transitive edge-
+ * dependents) instead of rebuilding everything. See `classifyCatalog`
+ * and the orchestrator's incremental path.
+ */
+import { statSync } from 'node:fs';
+import { logger } from '@opensip-cli/core';
+export function classifyCatalog(cached, ctx) {
+    if (cached.language !== ctx.currentLanguage) {
+        logger.info({
+            evt: 'graph.cache.invalidate.miss',
+            module: 'graph:cache',
+            reason: 'language-changed',
+            cached: cached.language,
+            current: ctx.currentLanguage,
+        });
+        return { kind: 'invalid', reason: 'language-changed' };
+    }
+    if (cached.cacheKey !== ctx.currentCacheKey) {
+        logger.info({
+            evt: 'graph.cache.invalidate.miss',
+            module: 'graph:cache',
+            reason: 'cache-key-changed',
+            cached: cached.cacheKey,
+            current: ctx.currentCacheKey,
+        });
+        return { kind: 'invalid', reason: 'cache-key-changed' };
+    }
+    const cachedFingerprint = cached.filesFingerprint;
+    if (typeof cachedFingerprint !== 'string') {
+        logger.info({
+            evt: 'graph.cache.invalidate.miss',
+            module: 'graph:cache',
+            reason: 'no-fingerprint',
+        });
+        return { kind: 'invalid', reason: 'no-fingerprint' };
+    }
+    const currentFingerprint = computeFilesFingerprint(ctx.currentFiles);
+    if (cachedFingerprint === currentFingerprint) {
+        return { kind: 'valid' };
+    }
+    const changedFiles = diffFingerprints(cachedFingerprint, currentFingerprint);
+    logger.info({
+        evt: 'graph.cache.invalidate.incremental',
+        module: 'graph:cache',
+        changedFiles: changedFiles.length,
+    });
+    return { kind: 'incremental', changedFiles };
+}
+/**
+ * Compute a fingerprint over the project's source files. Uses mtime
+ * (nanosecond resolution) per file plus the file count; cheap to
+ * compute and stable for unchanged trees.
+ */
+export function computeFilesFingerprint(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`);
+        }
+    }
+    return parts.join('\n');
+}
+/**
+ * Diff two fingerprints (computed by `computeFilesFingerprint`) and
+ * return the absolute file paths that differ. A file appears in the
+ * result if it was added, removed, or had its mtime/size change. The
+ * leading file-count line is ignored. Used by the incremental
+ * rebuild path.
+ */
+export function diffFingerprints(cachedFingerprint, currentFingerprint) {
+    const cachedMap = parseFingerprint(cachedFingerprint);
+    const currentMap = parseFingerprint(currentFingerprint);
+    const changed = new Set();
+    for (const [path, mark] of cachedMap) {
+        const cur = currentMap.get(path);
+        if (cur === undefined || cur !== mark)
+            changed.add(path);
+    }
+    for (const [path] of currentMap) {
+        if (!cachedMap.has(path))
+            changed.add(path);
+    }
+    return [...changed].sort();
+}
+function parseFingerprint(fingerprint) {
+    const out = new Map();
+    const lines = fingerprint.split('\n');
+    // Skip the leading file-count line.
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (typeof line !== 'string' || line.length === 0)
+            continue;
+        const firstPipe = line.indexOf('|');
+        if (firstPipe === -1)
+            continue;
+        const path = line.slice(0, firstPipe);
+        const mark = line.slice(firstPipe + 1);
+        out.set(path, mark);
+    }
+    return out;
+}
+//# sourceMappingURL=invalidate.js.map

package/dist/cache/invalidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidate.js","sourceRoot":"","sources":["../../src/cache/invalidate.ts"],"names":[],"mappings":"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"}

package/dist/cli/__tests__/build-envelope.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for `buildGraphEnvelope` (ADR-0011 Phase 5) — the graph run's signal
+ * envelope assembly. Covers the Option-A rule-ID mapping (engine slug →
+ * OpenSIP rule ID on both `ruleId` and `source`), per-rule unit derivation,
+ * the verdict counts, and `resolutionMode` passthrough.
+ */
+export {};
+//# sourceMappingURL=build-envelope.test.d.ts.map

package/dist/cli/__tests__/build-envelope.test.d.ts.map

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

package/dist/cli/__tests__/build-envelope.test.js

@@ -0,0 +1,70 @@
+/**
+ * Tests for `buildGraphEnvelope` (ADR-0011 Phase 5) — the graph run's signal
+ * envelope assembly. Covers the Option-A rule-ID mapping (engine slug →
+ * OpenSIP rule ID on both `ruleId` and `source`), per-rule unit derivation,
+ * the verdict counts, and `resolutionMode` passthrough.
+ */
+import { describe, expect, it } from 'vitest';
+import { buildGraphEnvelope } from '../build-envelope.js';
+function signal(over = {}) {
+    return {
+        id: 'sig_1',
+        source: 'graph',
+        provider: 'opensip-cli',
+        severity: 'medium',
+        category: 'quality',
+        ruleId: 'graph:orphan-subtree',
+        message: 'msg',
+        filePath: 'src/a.ts',
+        line: 1,
+        metadata: {},
+        createdAt: '2026-06-04T00:00:00.000Z',
+        ...over,
+    };
+}
+const BASE = { runId: 'run-1', createdAt: '2026-06-04T00:00:00.000Z' };
+describe('buildGraphEnvelope', () => {
+    it('maps engine slug → OpenSIP rule ID on both ruleId and source', () => {
+        const env = buildGraphEnvelope({ ...BASE, signals: [signal()] });
+        expect(env.signals[0]?.ruleId).toBe('graph.dead-code.orphan-subtree');
+        expect(env.signals[0]?.source).toBe('graph.dead-code.orphan-subtree');
+    });
+    it('derives one unit per rule that fired, keyed on the mapped slug', () => {
+        const env = buildGraphEnvelope({
+            ...BASE,
+            signals: [
+                signal({ ruleId: 'graph:orphan-subtree' }),
+                signal({ ruleId: 'graph:orphan-subtree' }),
+                signal({ ruleId: 'graph:cycle', severity: 'high' }),
+            ],
+        });
+        const slugs = env.units.map((u) => u.slug).sort();
+        expect(slugs).toEqual(['graph.architecture.cycle', 'graph.dead-code.orphan-subtree']);
+        const orphan = env.units.find((u) => u.slug === 'graph.dead-code.orphan-subtree');
+        expect(orphan?.violationCount).toBe(2);
+        expect(orphan?.passed).toBe(true); // medium severity ⇒ no error
+        const cycle = env.units.find((u) => u.slug === 'graph.architecture.cycle');
+        expect(cycle?.passed).toBe(false); // high severity ⇒ error ⇒ fail
+    });
+    it('computes the verdict (errors = critical|high; passed ⇔ errors === 0)', () => {
+        const clean = buildGraphEnvelope({ ...BASE, signals: [signal({ severity: 'low' })] });
+        expect(clean.verdict.passed).toBe(true);
+        expect(clean.verdict.summary.errors).toBe(0);
+        expect(clean.verdict.summary.warnings).toBe(1);
+        const failing = buildGraphEnvelope({ ...BASE, signals: [signal({ severity: 'critical' })] });
+        expect(failing.verdict.passed).toBe(false);
+        expect(failing.verdict.summary.errors).toBe(1);
+    });
+    it('is schemaVersion 2 and tool graph, with an empty units list for no signals', () => {
+        const env = buildGraphEnvelope({ ...BASE, signals: [] });
+        expect(env.schemaVersion).toBe(2);
+        expect(env.tool).toBe('graph');
+        expect(env.units).toEqual([]);
+        expect(env.verdict.passed).toBe(true);
+    });
+    it('passes resolutionMode through only when set', () => {
+        expect(buildGraphEnvelope({ ...BASE, signals: [] }).resolutionMode).toBeUndefined();
+        expect(buildGraphEnvelope({ ...BASE, signals: [], resolutionMode: 'fast' }).resolutionMode).toBe('fast');
+    });
+});
+//# sourceMappingURL=build-envelope.test.js.map

package/dist/cli/__tests__/build-envelope.test.js.map

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

package/dist/cli/__tests__/dispatch-envelope.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ADR-0011 Phase 5 (supersedes the audit-P1-2 `graph-signal-emit` test):
+ * `dispatchGraphResult` no longer emits cloud signals itself — the root owns
+ * egress (`cli.deliverSignals`). Instead it RETURNS the run's
+ * {@link GraphRunOutcome} (envelope + optional session) for every mode that
+ * should deliver (gate / catalog / default render) and `undefined` for plain
+ * `--json` (the `--workspace` child carrier, which must not trigger per-child
+ * cloud emits). These tests pin that return contract.
+ *
+ * host-owned-run-timing Phase 3: the human-render path's outcome also carries a
+ * `session` contribution (the host persists it); the export modes (gate /
+ * catalog / `--json` / `--report-to`) carry no `session`.
+ */
+export {};
+//# sourceMappingURL=dispatch-envelope.test.d.ts.map

package/dist/cli/__tests__/dispatch-envelope.test.d.ts.map

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

package/dist/cli/__tests__/dispatch-envelope.test.js

@@ -0,0 +1,73 @@
+/**
+ * ADR-0011 Phase 5 (supersedes the audit-P1-2 `graph-signal-emit` test):
+ * `dispatchGraphResult` no longer emits cloud signals itself — the root owns
+ * egress (`cli.deliverSignals`). Instead it RETURNS the run's
+ * {@link GraphRunOutcome} (envelope + optional session) for every mode that
+ * should deliver (gate / catalog / default render) and `undefined` for plain
+ * `--json` (the `--workspace` child carrier, which must not trigger per-child
+ * cloud emits). These tests pin that return contract.
+ *
+ * host-owned-run-timing Phase 3: the human-render path's outcome also carries a
+ * `session` contribution (the host persists it); the export modes (gate /
+ * catalog / `--json` / `--report-to`) carry no `session`.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { dispatchGraphResult } from '../graph.js';
+vi.mock('../graph-modes.js', () => ({
+    runGateMode: vi.fn().mockResolvedValue(undefined),
+    runCatalogJsonMode: vi.fn(),
+}));
+const result = { signals: [], catalog: undefined };
+function mockCli() {
+    return {
+        setExitCode: vi.fn(),
+        emitRaw: vi.fn(),
+        emitEnvelope: vi.fn(),
+        emitError: vi.fn(),
+        render: vi.fn(() => Promise.resolve()),
+        logger: console,
+        scope: { signalSink: { emit: vi.fn() }, datastore: () => undefined },
+    };
+}
+const STARTED = '2026-06-03T00:00:00.000Z';
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+afterEach(() => vi.restoreAllMocks());
+describe('dispatchGraphResult — outcome return contract (ADR-0011)', () => {
+    it('returns the envelope (no session) in --gate-save mode (root delivers it)', async () => {
+        const opts = { gateSave: true, cwd: '/x' };
+        const outcome = await dispatchGraphResult(opts, result, mockCli(), STARTED, '/x');
+        expect(outcome?.envelope?.tool).toBe('graph');
+        expect(outcome?.envelope?.schemaVersion).toBe(2);
+        // Export mode: the host must NOT persist a session for the gate path.
+        expect(outcome?.session).toBeUndefined();
+    });
+    it('returns the envelope (no session) in --catalog-output mode', async () => {
+        // runCatalogJsonMode is mocked, so the path is never written — any
+        // non-empty string exercises the branch.
+        const opts = { catalogOutput: 'out/c.json', cwd: '/x' };
+        const outcome = await dispatchGraphResult(opts, result, mockCli(), STARTED, '/x');
+        expect(outcome?.envelope?.tool).toBe('graph');
+        expect(outcome?.session).toBeUndefined();
+    });
+    it('returns the envelope AND a session in the default render mode', async () => {
+        const opts = { cwd: '/x' };
+        const outcome = await dispatchGraphResult(opts, result, mockCli(), STARTED, '/x');
+        expect(outcome?.envelope?.tool).toBe('graph');
+        // host-owned-run-timing Phase 3: the human-render path contributes the
+        // session the host persists; timing/id are host-stamped (absent here).
+        expect(outcome?.session?.tool).toBe('graph');
+        expect(outcome?.session?.cwd).toBe('/x');
+        expect(outcome?.session?.payload).toBeDefined();
+    });
+    it('returns undefined under plain --json (the --workspace child carrier)', async () => {
+        const opts = { json: true, cwd: '/x' };
+        const cli = mockCli();
+        const outcome = await dispatchGraphResult(opts, result, cli, STARTED, '/x');
+        expect(outcome).toBeUndefined();
+        // --json still emits the envelope to stdout via the seam.
+        expect(cli.emitEnvelope).toHaveBeenCalledTimes(1);
+    });
+});
+//# sourceMappingURL=dispatch-envelope.test.js.map

package/dist/cli/__tests__/dispatch-envelope.test.js.map

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

package/dist/cli/__tests__/dispatch-suppression-root.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Regression: `dispatchGraphResult` must waive `@graph-ignore` directives
+ * against the BUILD ROOT the signals are relative to (`suppressionRoot`), NOT
+ * `opts.cwd`.
+ *
+ * The two coincide for a bare `graph` run, but diverge for `graph <subdir>` and
+ * for every `--workspace` child (which runs `graph <unitRoot> --json` with cwd
+ * inherited from the parent = repo root). The old code resolved directive files
+ * against `opts.cwd`, so a child's package-relative `code.file` never found its
+ * directive on disk (ENOENT) and the waiver silently leaked — reproducing the
+ * cycle/large-function warnings that the single-program run correctly suppresses.
+ *
+ * These tests drive the public `dispatchGraphResult` seam with `opts.cwd` set to
+ * a directory that does NOT contain the directive, and `suppressionRoot` set to
+ * the temp dir that does. The signal must be suppressed via `suppressionRoot`.
+ */
+export {};
+//# sourceMappingURL=dispatch-suppression-root.test.d.ts.map

package/dist/cli/__tests__/dispatch-suppression-root.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-suppression-root.test.d.ts","sourceRoot":"","sources":["../../../src/cli/__tests__/dispatch-suppression-root.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/cli/__tests__/dispatch-suppression-root.test.js

@@ -0,0 +1,91 @@
+/**
+ * Regression: `dispatchGraphResult` must waive `@graph-ignore` directives
+ * against the BUILD ROOT the signals are relative to (`suppressionRoot`), NOT
+ * `opts.cwd`.
+ *
+ * The two coincide for a bare `graph` run, but diverge for `graph <subdir>` and
+ * for every `--workspace` child (which runs `graph <unitRoot> --json` with cwd
+ * inherited from the parent = repo root). The old code resolved directive files
+ * against `opts.cwd`, so a child's package-relative `code.file` never found its
+ * directive on disk (ENOENT) and the waiver silently leaked — reproducing the
+ * cycle/large-function warnings that the single-program run correctly suppresses.
+ *
+ * These tests drive the public `dispatchGraphResult` seam with `opts.cwd` set to
+ * a directory that does NOT contain the directive, and `suppressionRoot` set to
+ * the temp dir that does. The signal must be suppressed via `suppressionRoot`.
+ */
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createSignal } from '@opensip-cli/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { dispatchGraphResult } from '../graph.js';
+// Capture the signals each output mode receives. runGateMode is the simplest
+// sink to assert against (it takes the post-waiver signals as arg[1]).
+const runGateMode = vi.fn().mockResolvedValue(undefined);
+vi.mock('../graph-modes.js', () => ({
+    runGateMode: (...args) => runGateMode(...args),
+    runCatalogJsonMode: vi.fn(),
+}));
+let buildRoot;
+let otherCwd;
+beforeEach(async () => {
+    vi.clearAllMocks();
+    buildRoot = await mkdtemp(join(tmpdir(), 'graph-disp-root-'));
+    otherCwd = await mkdtemp(join(tmpdir(), 'graph-disp-cwd-'));
+});
+afterEach(async () => {
+    await rm(buildRoot, { recursive: true, force: true });
+    await rm(otherCwd, { recursive: true, force: true });
+    vi.restoreAllMocks();
+});
+function mockCli() {
+    return {
+        setExitCode: vi.fn(),
+        emitRaw: vi.fn(),
+        emitEnvelope: vi.fn(),
+        emitError: vi.fn(),
+        render: vi.fn(() => Promise.resolve()),
+        logger: console,
+        scope: { signalSink: { emit: vi.fn() }, datastore: () => undefined },
+    };
+}
+/** A graph:large-function signal anchored at `file:line` (project-relative). */
+function sig(file, line) {
+    return createSignal({
+        source: 'graph',
+        severity: 'medium',
+        category: 'quality',
+        ruleId: 'graph:large-function',
+        message: `big at ${file}:${String(line)}`,
+        code: { file, line },
+    });
+}
+function gateOpts(cwd) {
+    return { gateSave: true, cwd };
+}
+const result = (signals) => ({ signals, catalog: undefined });
+const STARTED = '2026-06-07T00:00:00.000Z';
+describe('dispatchGraphResult — waives against suppressionRoot, not opts.cwd', () => {
+    it('suppresses a signal whose directive lives under suppressionRoot (≠ opts.cwd)', async () => {
+        // The directive file exists ONLY under buildRoot. opts.cwd points elsewhere
+        // (the repo-root stand-in a --workspace child inherits). The waiver must
+        // still apply — it is resolved against suppressionRoot.
+        await writeFile(join(buildRoot, 'walk.ts'), ['// @graph-ignore-next-line graph:large-function -- intentional', 'function big() {}'].join('\n'), 'utf8');
+        await dispatchGraphResult(gateOpts(otherCwd), result([sig('walk.ts', 2)]), mockCli(), STARTED, buildRoot);
+        expect(runGateMode).toHaveBeenCalledTimes(1);
+        // arg[1] is the post-waiver envelope runGateMode receives (ADR-0036).
+        expect(runGateMode.mock.calls[0]?.[1]?.signals).toHaveLength(0);
+    });
+    it('does NOT suppress when only opts.cwd (the wrong base) holds the directive', async () => {
+        // The directive sits under opts.cwd, NOT the build root. Resolving against
+        // opts.cwd (the old behavior) would suppress; resolving against
+        // suppressionRoot (correct) must KEEP the signal — pinning the base used.
+        await writeFile(join(otherCwd, 'walk.ts'), ['// @graph-ignore-next-line graph:large-function -- wrong base', 'function big() {}'].join('\n'), 'utf8');
+        await dispatchGraphResult(gateOpts(otherCwd), result([sig('walk.ts', 2)]), mockCli(), STARTED, buildRoot);
+        expect(runGateMode).toHaveBeenCalledTimes(1);
+        // The waiver under opts.cwd must NOT apply — the signal survives.
+        expect(runGateMode.mock.calls[0]?.[1]?.signals).toHaveLength(1);
+    });
+});
+//# sourceMappingURL=dispatch-suppression-root.test.js.map