@opensip-cli/graph 0.1.0

package/dist/cli/graph-config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * graph-config — load the `graph:` block of `opensip-cli.config.yml`
+ * into a {@link GraphConfig}.
+ *
+ * The graph rule knobs (`minDuplicateBodyLines`, `minDuplicateBodySize`,
+ * `minCrossPackageDuplicatePackages`, `minCrossPackageDuplicateBodySize`,
+ * `entryPointHashes`, `severityOverrides`) are owned by the graph tool, so the graph engine
+ * reads its own config block — mirroring the way fitness owns its
+ * sections and the CLI seam owns the `cli:` block
+ * (`@opensip-cli/contracts` `loadCliDefaults`).
+ *
+ * Launch (ADR-0023, Phase 4): the block is now read through graph's
+ * own Zod {@link GraphConfigSchema} (the same schema graph contributes to the
+ * host's composed whole-document validation) instead of the old hand-rolled
+ * `projectGraphConfig`. The composed dispatch-level validation is the STRICT
+ * gate that rejects a typo inside `graph:` before any command runs; this
+ * loader stays permissive at its own call sites — a missing config, malformed
+ * YAML, an absent `graph:` key, or a block that fails the schema all collapse
+ * to `{}` so a rule falls back to its in-rule default and a mid-run read never
+ * throws.
+ */
+import { type ResolvedRecipe } from '@opensip-cli/contracts';
+import type { GraphConfig } from '../types.js';
+/**
+ * Best-effort load of the `graph:` block of `opensip-cli.config.yml`.
+ *
+ * ADR-0023, Phase 4: the resolved `graph:` block rides on the per-run scope
+ * (`scope.toolConfig.graph`) — the host already strict-validated + precedence-
+ * resolved (flag > env > file > defaults) the whole document before dispatch. So
+ * when a scope is present (every in-process AND forked-worker run goes through
+ * the pre-action hook) this returns the SCOPE value and does NOT re-read YAML.
+ * The YAML read below is the fallback for a caller with no scope (a unit test
+ * driving `loadGraphConfig` directly) — there it stays best-effort: a missing
+ * config, malformed YAML, an absent `graph:` key, or a block that fails the
+ * schema all collapse to `{}` so a rule falls back to its in-rule default.
+ *
+ * @param cwd Project root for config resolution.
+ * @param explicitPath Optional `--config <path>` override.
+ */
+export declare function loadGraphConfig(cwd: string, explicitPath?: string): GraphConfig;
+/**
+ * Resolve which recipe NAME a `graph` run should use (ADR-0022), applying the
+ * tool-scoped precedence: explicit `--recipe` > `graph.recipe` > built-in
+ * `default`. Delegates the precedence/tolerance decision to the shared
+ * `resolveToolRecipeName`. The caller turns the returned `name` into rules via
+ * `resolveRecipeToRules(name, { tolerant })`.
+ *
+ * @param cwd Project root for config resolution.
+ * @param explicit The `--recipe <name>` flag value (undefined when absent).
+ * @param explicitPath Optional `--config <path>` override.
+ */
+export declare function resolveGraphRecipeSelection(cwd: string, explicit: string | undefined, explicitPath?: string): ResolvedRecipe;
+//# sourceMappingURL=graph-config.d.ts.map

package/dist/cli/graph-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-config.d.ts","sourceRoot":"","sources":["../../src/cli/graph-config.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAKpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAO/C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CA4C/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,CAAC,EAAE,MAAM,GACpB,cAAc,CAMhB"}

package/dist/cli/graph-config.js

@@ -0,0 +1,111 @@
+// @fitness-ignore-file null-safety -- Zod schema builder chains (.strict()/.safeParse()) always return valid objects; `.safeParse` is called on a freshly-built strict schema, never a nullable reference.
+/**
+ * graph-config — load the `graph:` block of `opensip-cli.config.yml`
+ * into a {@link GraphConfig}.
+ *
+ * The graph rule knobs (`minDuplicateBodyLines`, `minDuplicateBodySize`,
+ * `minCrossPackageDuplicatePackages`, `minCrossPackageDuplicateBodySize`,
+ * `entryPointHashes`, `severityOverrides`) are owned by the graph tool, so the graph engine
+ * reads its own config block — mirroring the way fitness owns its
+ * sections and the CLI seam owns the `cli:` block
+ * (`@opensip-cli/contracts` `loadCliDefaults`).
+ *
+ * Launch (ADR-0023, Phase 4): the block is now read through graph's
+ * own Zod {@link GraphConfigSchema} (the same schema graph contributes to the
+ * host's composed whole-document validation) instead of the old hand-rolled
+ * `projectGraphConfig`. The composed dispatch-level validation is the STRICT
+ * gate that rejects a typo inside `graph:` before any command runs; this
+ * loader stays permissive at its own call sites — a missing config, malformed
+ * YAML, an absent `graph:` key, or a block that fails the schema all collapse
+ * to `{}` so a rule falls back to its in-rule default and a mid-run read never
+ * throws.
+ */
+import { resolveToolRecipeName } from '@opensip-cli/contracts';
+import { currentScope, logger, readYamlFile, resolveProjectConfigPath } from '@opensip-cli/core';
+import { GraphConfigSchema } from './graph-config-schema.js';
+/** Accept anything that looks like a plain object; everything else → `{}`. */
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Best-effort load of the `graph:` block of `opensip-cli.config.yml`.
+ *
+ * ADR-0023, Phase 4: the resolved `graph:` block rides on the per-run scope
+ * (`scope.toolConfig.graph`) — the host already strict-validated + precedence-
+ * resolved (flag > env > file > defaults) the whole document before dispatch. So
+ * when a scope is present (every in-process AND forked-worker run goes through
+ * the pre-action hook) this returns the SCOPE value and does NOT re-read YAML.
+ * The YAML read below is the fallback for a caller with no scope (a unit test
+ * driving `loadGraphConfig` directly) — there it stays best-effort: a missing
+ * config, malformed YAML, an absent `graph:` key, or a block that fails the
+ * schema all collapse to `{}` so a rule falls back to its in-rule default.
+ *
+ * @param cwd Project root for config resolution.
+ * @param explicitPath Optional `--config <path>` override.
+ */
+export function loadGraphConfig(cwd, explicitPath) {
+    // Scope-first: the resolved, strict-validated `graph:` block (with env/flag
+    // precedence already folded in). Present on every CLI dispatch path; absent
+    // only off-CLI (direct unit-test calls), where we fall back to the YAML read.
+    const scoped = currentScope()?.toolConfig?.graph;
+    if (isPlainObject(scoped)) {
+        // Already validated by the composer (graph's namespaced ToolConfigDeclaration
+        // is the same GraphConfigSchema), so this is a pure narrowing read.
+        return scoped;
+    }
+    let filePath;
+    try {
+        filePath = resolveProjectConfigPath(cwd, explicitPath);
+    }
+    catch (error) {
+        // No config file found — expected; the graph rules use their in-rule
+        // defaults. Debug-only so it never adds noise on config-less projects.
+        logger.debug({
+            evt: 'graph.config.not_found',
+            module: 'graph:config',
+            err: error instanceof Error ? error.message : String(error),
+        });
+        return {};
+    }
+    const doc = readYamlFile(filePath);
+    if (!isPlainObject(doc))
+        return {};
+    const graphBlock = doc.graph;
+    if (!isPlainObject(graphBlock))
+        return {};
+    // Parse the block through graph's own Zod schema, made `.strict()` to match
+    // the dispatch-level composed validation (an unknown key inside `graph:` is
+    // rejected, ADR-0023). A schema failure here is NOT fatal at the loader (the
+    // strict dispatch-level gate already surfaced it as a CONFIGURATION_ERROR
+    // before the command ran); fall back to `{}` so the call site keeps its
+    // historical "absent → in-rule default" semantics.
+    const parsed = GraphConfigSchema.strict().safeParse(graphBlock);
+    if (!parsed.success) {
+        logger.debug({
+            evt: 'graph.config.schema_rejected',
+            module: 'graph:config',
+            err: parsed.error.message,
+        });
+        return {};
+    }
+    return parsed.data;
+}
+/**
+ * Resolve which recipe NAME a `graph` run should use (ADR-0022), applying the
+ * tool-scoped precedence: explicit `--recipe` > `graph.recipe` > built-in
+ * `default`. Delegates the precedence/tolerance decision to the shared
+ * `resolveToolRecipeName`. The caller turns the returned `name` into rules via
+ * `resolveRecipeToRules(name, { tolerant })`.
+ *
+ * @param cwd Project root for config resolution.
+ * @param explicit The `--recipe <name>` flag value (undefined when absent).
+ * @param explicitPath Optional `--config <path>` override.
+ */
+export function resolveGraphRecipeSelection(cwd, explicit, explicitPath) {
+    const graphConfig = loadGraphConfig(cwd, explicitPath);
+    return resolveToolRecipeName({
+        explicit,
+        toolRecipe: graphConfig.recipe,
+    });
+}
+//# sourceMappingURL=graph-config.js.map

package/dist/cli/graph-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-config.js","sourceRoot":"","sources":["../../src/cli/graph-config.ts"],"names":[],"mappings":"AAAA,2MAA2M;AAC3M;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,qBAAqB,EAAuB,MAAM,wBAAwB,CAAC;AACpF,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAEjG,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAI7D,8EAA8E;AAC9E,SAAS,aAAa,CAAC,CAAU;IAC/B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,YAAqB;IAChE,4EAA4E;IAC5E,4EAA4E;IAC5E,8EAA8E;IAC9E,MAAM,MAAM,GAAG,YAAY,EAAE,EAAE,UAAU,EAAE,KAAK,CAAC;IACjD,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,8EAA8E;QAC9E,oEAAoE;QACpE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,wBAAwB,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IACzD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,qEAAqE;QACrE,uEAAuE;QACvE,MAAM,CAAC,KAAK,CAAC;YACX,GAAG,EAAE,wBAAwB;YAC7B,MAAM,EAAE,cAAc;YACtB,GAAG,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC5D,CAAC,CAAC;QACH,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC;IAC7B,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1C,4EAA4E;IAC5E,4EAA4E;IAC5E,6EAA6E;IAC7E,0EAA0E;IAC1E,wEAAwE;IACxE,mDAAmD;IACnD,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAChE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,CAAC,KAAK,CAAC;YACX,GAAG,EAAE,8BAA8B;YACnC,MAAM,EAAE,cAAc;YACtB,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;SAC1B,CAAC,CAAC;QACH,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,2BAA2B,CACzC,GAAW,EACX,QAA4B,EAC5B,YAAqB;IAErB,MAAM,WAAW,GAAG,eAAe,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IACvD,OAAO,qBAAqB,CAAC;QAC3B,QAAQ;QACR,UAAU,EAAE,WAAW,CAAC,MAAM;KAC/B,CAAC,CAAC;AACL,CAAC"}

package/dist/cli/graph-modes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Mode dispatch for `opensip graph`.
+ *
+ * Extracted from `cli/graph.ts` so the orchestrator there stays focused
+ * on flag validation, run-scope resolution, and result dispatch. Owns:
+ *
+ *  - `runGateMode` (--gate-save / --gate-compare)
+ *  - `runCatalogJsonMode` (--catalog-output)
+ *
+ * `--report-to` (the old `runReportMode`) moved to the composition root in
+ * ADR-0011 Phase 5: graph returns its `SignalEnvelope` and the root's
+ * `deliverSignals` owns cloud egress + the `--report-to` SARIF upload.
+ */
+import type { GraphCommandOptions } from './graph-options.js';
+import type { Catalog, Indexes } from '../types.js';
+import type { SignalEnvelope } from '@opensip-cli/contracts';
+import type { Signal, ToolCliContext } from '@opensip-cli/core';
+export declare function runGateMode(opts: GraphCommandOptions, envelope: SignalEnvelope, cli: ToolCliContext, resolutionMode?: 'exact' | 'fast'): Promise<void>;
+/**
+ * Catalog-JSON emission mode (Phase 3 Task 3.4 per opensip DEC-498).
+ * Walks the engine's `Catalog` + `Indexes`, derives opensip-compatible
+ * symbol/edge IDs, and writes a `CatalogExport` JSON document to the
+ * `--catalog-output <path>` file. Phase 6's `EngineSubprocessPort`
+ * invokes this mode per commit-sync run.
+ *
+ * Synchronous file write — catalog payloads are bounded (per-package
+ * fan-out limits per-run scope) and we want backpressure if disk is
+ * full rather than a deferred-write surprise.
+ */
+export declare function runCatalogJsonMode(opts: GraphCommandOptions, result: {
+    readonly catalog: Catalog | null;
+    readonly indexes: Indexes | null;
+    readonly signals: readonly Signal[];
+    readonly cacheHit: boolean;
+}, cli: ToolCliContext, startedAt: string): void;
+//# sourceMappingURL=graph-modes.d.ts.map

package/dist/cli/graph-modes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-modes.d.ts","sourceRoot":"","sources":["../../src/cli/graph-modes.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAmBH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKhE,wBAAsB,WAAW,CAC/B,IAAI,EAAE,mBAAmB,EACzB,QAAQ,EAAE,cAAc,EACxB,GAAG,EAAE,cAAc,EACnB,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,GAChC,OAAO,CAAC,IAAI,CAAC,CAiEf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE;IACN,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B,EACD,GAAG,EAAE,cAAc,EACnB,SAAS,EAAE,MAAM,GAChB,IAAI,CAgEN"}

package/dist/cli/graph-modes.js

@@ -0,0 +1,161 @@
+// @fitness-ignore-file detached-promises -- CLI dispatch: render helpers are synchronous; heuristic flags inside async handlers.
+// @fitness-ignore-file no-non-null-assertions -- narrowing helpers prove the discriminant before access; the assertions encode that proof for the type checker.
+// @fitness-ignore-file throws-documentation -- internal CLI mode helper rethrows for the top-level handleGraphError; not a documented contract surface.
+/**
+ * @fileoverview Mode dispatch for `opensip graph`.
+ *
+ * Extracted from `cli/graph.ts` so the orchestrator there stays focused
+ * on flag validation, run-scope resolution, and result dispatch. Owns:
+ *
+ *  - `runGateMode` (--gate-save / --gate-compare)
+ *  - `runCatalogJsonMode` (--catalog-output)
+ *
+ * `--report-to` (the old `runReportMode`) moved to the composition root in
+ * ADR-0011 Phase 5: graph returns its `SignalEnvelope` and the root's
+ * `deliverSignals` owns cloud egress + the `--report-to` SARIF upload.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { EXIT_CODES } from '@opensip-cli/contracts';
+import { ConfigurationError, isErrorSignal, logger, readPackageVersion, resolveFailOnDegraded, ToolError, } from '@opensip-cli/core';
+import { graphFingerprintStrategy } from '../baseline-strategy.js';
+import { renderCatalogJson } from '../render/catalog-json.js';
+const MODULE_GRAPH_RENDER = 'graph:render';
+const ENGINE_VERSION = readPackageVersion(import.meta.url);
+export async function runGateMode(opts, envelope, cli, resolutionMode) {
+    // A fast catalog's edges are approximate (syntactic). Seeding the
+    // security ratchet from them — or comparing against an exact baseline —
+    // would let false orphans/regressions flip the gate. The gate's value
+    // depends on edge fidelity, so fast mode is declined by default; the
+    // user must re-run with --resolution exact to gate.
+    if (resolutionMode === 'fast') {
+        throw new ConfigurationError('Graph gate refuses a fast (--resolution fast) catalog: its syntactic edges ' +
+            'are approximate and must not seed or compare against the security gate. ' +
+            'Re-run with --resolution exact to gate.');
+    }
+    // The host owns persistence (BaselineRepo), the diff, AND the exit (ADR-0036 /
+    // ADR-0035): graph hands the already-fingerprint-stamped envelope to the seams
+    // and feeds its gate verdict to the host's `deliverSignals` runFailed override.
+    // No tool `setExitCode` on the gate path — the host derives RUNTIME_ERROR.
+    const deliverOpts = { cwd: opts.cwd, reportTo: opts.reportTo, apiKey: opts.apiKey };
+    if (opts.gateSave === true) {
+        // ADR-0020: gate-save records the baseline AND hard-fails the step when the
+        // current (already suppression-filtered, ADR-0014) signal set contains any
+        // error-rung finding. The error rung is core's canonical `isErrorSignal`
+        // (`critical`/`high`) — the same predicate graph's envelope verdict
+        // (`build-envelope.ts`) uses — so `errorCount > 0` equals `!verdict.passed`.
+        // ADR-0035: that findings verdict is HOST-owned; graph passes it as the
+        // `deliverSignals` runFailed override (the host sets the exit), so the CI step
+        // is the honest pass/fail signal without a tool-side setExitCode. The `--sarif`
+        // export still runs in the command-spec under `if: always()` semantics.
+        await cli.saveBaseline('graph', envelope);
+        const errorCount = envelope.signals.filter(isErrorSignal).length;
+        const runFailed = errorCount > 0;
+        await cli.render({
+            type: 'gate-done',
+            lines: runFailed
+                ? [
+                    `Graph baseline saved (${String(envelope.signals.length)} signals)`,
+                    `Graph gate FAILED: ${String(errorCount)} error-level finding(s) present.`,
+                ]
+                : [`Graph baseline saved (${String(envelope.signals.length)} signals)`],
+        });
+        await cli.deliverSignals(envelope, { ...deliverOpts, runFailed });
+        return;
+    }
+    // gate-compare.
+    //
+    // ADR-0035 Phase 5 finding — RETAIN (not fold): `degraded` is "net-new findings
+    // since the saved baseline", a baseline-DIFF predicate NOT expressible over this
+    // run's own findings verdict (a run can have error-level findings yet be
+    // `degraded: false` if none are net-new, and vice versa). The ratchet is gated
+    // by the reserved `failOnDegraded` key (ADR-0036, default true); the resulting
+    // verdict rides the host's `deliverSignals` runFailed override — no tool exit.
+    const result = await cli.compareBaseline('graph', envelope);
+    const runFailed = result.degraded && resolveFailOnDegraded('graph');
+    await cli.render({
+        type: 'gate-done',
+        lines: result.degraded
+            ? [
+                `Graph gate FAILED: ${String(result.added.length)} new finding(s) since baseline.`,
+                ...result.added.map((s) => `  + ${graphFingerprintStrategy(s)}`),
+            ]
+            : [
+                `Graph gate PASS: no regressions (${String(result.resolved.length)} resolved since baseline).`,
+            ],
+    });
+    await cli.deliverSignals(envelope, { ...deliverOpts, runFailed });
+}
+/**
+ * Catalog-JSON emission mode (Phase 3 Task 3.4 per opensip DEC-498).
+ * Walks the engine's `Catalog` + `Indexes`, derives opensip-compatible
+ * symbol/edge IDs, and writes a `CatalogExport` JSON document to the
+ * `--catalog-output <path>` file. Phase 6's `EngineSubprocessPort`
+ * invokes this mode per commit-sync run.
+ *
+ * Synchronous file write — catalog payloads are bounded (per-package
+ * fan-out limits per-run scope) and we want backpressure if disk is
+ * full rather than a deferred-write surprise.
+ */
+export function runCatalogJsonMode(opts, result, cli, startedAt) {
+    if (typeof opts.tenantId !== 'string' || opts.tenantId.length === 0) {
+        throw new ConfigurationError('--catalog-output requires --tenant-id <id>.');
+    }
+    if (typeof opts.repoId !== 'string' || opts.repoId.length === 0) {
+        throw new ConfigurationError('--catalog-output requires --repo-id <id>.');
+    }
+    if (typeof opts.gitSha !== 'string' || opts.gitSha.length === 0) {
+        throw new ConfigurationError('--catalog-output requires --git-sha <sha>.');
+    }
+    if (result.catalog === null || result.indexes === null) {
+        throw new ToolError('Cannot emit catalog-json: engine returned null catalog / indexes (no parseable input).', 'GRAPH.CATALOG_JSON.NULL_CATALOG');
+    }
+    const runId = opts.runId ?? randomUUID();
+    const completedAt = new Date().toISOString();
+    // Caller (opensip-side EngineSubprocessPort, Phase 6) inspects the
+    // file's existence + completeness field; engine never emits 'partial'
+    // from this code path (the engine's pressure-monitor / abort-handling
+    // bypass this function entirely on failure). A future task may add
+    // partial-completion semantics by catching MemoryPressureError in
+    // executeGraph and writing a partial CatalogExport here.
+    const provenance = {
+        runId,
+        completeness: 'complete',
+        engineVersion: ENGINE_VERSION,
+        startedAt,
+        completedAt,
+        tenantId: opts.tenantId,
+    };
+    logger.info({
+        evt: 'graph.render.catalog_json.start',
+        module: MODULE_GRAPH_RENDER,
+        runId,
+        output: opts.catalogOutput,
+    });
+    const json = renderCatalogJson({
+        catalog: result.catalog,
+        indexes: result.indexes,
+        provenance,
+        repoId: opts.repoId,
+        gitSha: opts.gitSha,
+    });
+    // Defensively create the parent dir before writing — the sibling
+    // `runSarifExportMode` does the same. The
+    // opensip `EngineSubprocessPort.runCatalogExport` may point
+    // `--catalog-output` at a run-scoped temp dir that doesn't exist yet,
+    // so a bare writeFileSync would throw ENOENT.
+    mkdirSync(dirname(opts.catalogOutput), { recursive: true });
+    writeFileSync(opts.catalogOutput, json);
+    logger.info({
+        evt: 'graph.render.catalog_json.complete',
+        module: MODULE_GRAPH_RENDER,
+        runId,
+        output: opts.catalogOutput,
+        bytes: json.length,
+        cacheHit: result.cacheHit,
+        signalCount: result.signals.length,
+    });
+    cli.setExitCode(EXIT_CODES.SUCCESS);
+}
+//# sourceMappingURL=graph-modes.js.map

package/dist/cli/graph-modes.js.map

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

package/dist/cli/graph-options.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Public option shape for `executeGraph`.
+ *
+ * Extracted so the orchestrator (`graph.ts`) and the mode helpers
+ * (`graph-modes.ts`) can share the same interface without one
+ * importing from the other.
+ *
+ * Language-neutral surface per the graph-cli-language-neutral-scoping
+ * spec — positional `[paths...]`, `--workspace`, `--language <name>`
+ * replace the prior TypeScript-flavored `--package` / `--packages`
+ * flags (which were never publicly released — D11 hard-removes them).
+ */
+import type { ResolutionMode } from '../types.js';
+/**
+ * Public option shape for `executeGraph` — the language-neutral surface shared
+ * by the orchestrator (`graph.ts`) and the mode helpers (`graph-modes.ts`).
+ * Programmatic callers and tests construct this directly; the CLI builds it
+ * from parsed Commander flags.
+ */
+export interface GraphCommandOptions {
+    readonly cwd: string;
+    readonly json?: boolean;
+    readonly noCache?: boolean;
+    /**
+     * `--resolution <mode>`: edge resolution tier. `'exact'` (default) is
+     * the semantic, type-checker-backed path; `'fast'` is the syntactic
+     * (name + import-graph) path that skips the checker for a large
+     * cold-build speedup, at the cost of approximate edges. Optional here
+     * because programmatic callers and tests may omit it; the orchestrator
+     * normalizes a missing value to `'exact'`.
+     */
+    readonly resolution?: ResolutionMode;
+    /**
+     * `--recipe <name>`: select a named subset of graph rules to evaluate.
+     * Absent ⇒ the built-in `default` recipe (all rules, registration order
+     * — identical to the historical behavior). Resolved to a `readonly Rule[]`
+     * in the CLI layer and threaded into every run path as `RunGraphInput.rules`;
+     * an unknown name raises a `ConfigurationError`.
+     */
+    readonly recipe?: string;
+    readonly gateSave?: boolean;
+    readonly gateCompare?: boolean;
+    readonly reportTo?: string;
+    readonly apiKey?: string;
+    /**
+     * `--profile <path>`: write a stage-timing JSON artifact for this run.
+     * Intended for cold-start diagnostics; relative paths resolve against
+     * `cwd`.
+     */
+    readonly profileOutput?: string;
+    /**
+     * Positional `[paths...]`. Empty/undefined means whole-project scope.
+     * Each path must be an existing directory (absolute or relative to
+     * `cwd`). Multiple paths run sequentially in-process and aggregate
+     * into one session (D12).
+     */
+    readonly paths?: readonly string[];
+    /**
+     * `--workspace`: fan the run across every workspace unit returned by
+     * each detected adapter's `discoverWorkspaceUnits`. Polyglot per
+     * spec D8b: in a multi-language repo all adapters' units are
+     * aggregated into one combined fan-out.
+     */
+    readonly workspace?: boolean;
+    /**
+     * `--exact`: opt OUT of the default parallel SHARDED build engine and use
+     * the single-program EXACT engine instead. Determinism (ADR-0032, superseding
+     * ADR-0031): the build engine is chosen by THIS explicit flag (plus the
+     * project's shardability) — never by `process.stdout.isTTY` or on-disk
+     * discovery state. A bare `graph` uses the SHARDED engine (the default;
+     * both engines resolve through one shared model — exact = the 1-shard case —
+     * held equivalent by the directional soundness invariant + completeness floor,
+     * ADR-0033); `--exact` forces the single-program engine.
+     *
+     * The sharded engine is faster on large multi-package repos and — with
+     * equivalence held by the guardrails — is the authoritative default.
+     * `--exact` is the escape hatch for small/single-package repos (where exact
+     * is the natural path anyway) and the oracle used to verify equivalence.
+     * Sharding is always skipped for the whole-`--workspace` fan-out (which
+     * already runs one isolated child process per unit) and for positional-path /
+     * multi-path runs (those always use the exact engine).
+     */
+    readonly exact?: boolean;
+    /**
+     * `--language <name>`: force a single language adapter. Suppresses
+     * marker-based detection. Errors if the name is not registered.
+     * Also drives the D14 mixed mismatch policy at the end of the run.
+     */
+    readonly language?: string;
+    /**
+     * `-v, --verbose`: when true, the renderer includes the detailed
+     * catalog / findings-by-rule / entry-points sections in addition to
+     * the one-line summary. Default (false) shows the summary + footer
+     * hint only, matching fit's surface.
+     */
+    readonly verbose?: boolean;
+    /**
+     * Optional concurrency cap for `--workspace`. Defaults to
+     * `os.cpus().length - 1`. Exposed primarily for tests.
+     */
+    readonly concurrency?: number;
+    /**
+     * Path to the CLI entry script. `--workspace` children invoke
+     * `node <cliScript> graph <rootDir> --json`. Tools wiring
+     * `executeGraph` should pass `process.argv[1]`.
+     */
+    readonly cliScript?: string;
+    /**
+     * --catalog-output <path>. When set, runs in catalog-JSON emission
+     * mode: walks the engine's `Catalog` + edges, derives opensip-
+     * compatible symbol/edge IDs, and writes a `CatalogExport` JSON
+     * document to the path. File output (not stdout) because catalog
+     * JSON for 100k-file repos exceeds practical stdout buffer sizes.
+     *
+     * Required companion opts when set: `tenantId`, `repoId`, `gitSha`.
+     * `runId` is auto-generated if not provided.
+     *
+     * Phase 3 Task 3.4 per opensip DEC-498. Phase 6's
+     * EngineSubprocessPort invokes this mode per commit-sync run.
+     */
+    readonly catalogOutput?: string;
+    /** Tenant scope for catalog-output provenance. */
+    readonly tenantId?: string;
+    /** Repository scope — applied to every row in catalog-output. */
+    readonly repoId?: string;
+    /** Commit SHA the catalog was extracted at — provenance for every row. */
+    readonly gitSha?: string;
+    /** Optional UUID for the catalog-output run. Auto-generated if absent. */
+    readonly runId?: string;
+    /**
+     * `--list-files`: discovery-only mode. Resolve and print the source-file
+     * set the run would analyze for the given scope (whole project, positional
+     * subtrees, or `--workspace` fan-out) WITHOUT building the catalog, then
+     * exit. The list is faithful to a real run — it reuses the adapter's
+     * stage-0 `discoverFiles` (so `.d.ts` is excluded, TypeScript
+     * extension-priority collisions are collapsed, and per-tsconfig
+     * include/exclude is honored) — which makes it the canonical way to diff
+     * graph's view of a repo against e.g. `git ls-files`. Composes with
+     * `--json` for machine-readable output.
+     */
+    readonly listFiles?: boolean;
+}
+//# sourceMappingURL=graph-options.d.ts.map

package/dist/cli/graph-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-options.d.ts","sourceRoot":"","sources":["../../src/cli/graph-options.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B"}

package/dist/cli/graph-options.js

@@ -0,0 +1,15 @@
+// @fitness-ignore-file no-markdown-references -- docs/plans/* pointers in JSDoc are stable internal references.
+/**
+ * @fileoverview Public option shape for `executeGraph`.
+ *
+ * Extracted so the orchestrator (`graph.ts`) and the mode helpers
+ * (`graph-modes.ts`) can share the same interface without one
+ * importing from the other.
+ *
+ * Language-neutral surface per the graph-cli-language-neutral-scoping
+ * spec — positional `[paths...]`, `--workspace`, `--language <name>`
+ * replace the prior TypeScript-flavored `--package` / `--packages`
+ * flags (which were never publicly released — D11 hard-removes them).
+ */
+export {};
+//# sourceMappingURL=graph-options.js.map

package/dist/cli/graph-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-options.js","sourceRoot":"","sources":["../../src/cli/graph-options.ts"],"names":[],"mappings":"AAAA,gHAAgH;AAChH;;;;;;;;;;;GAWG"}

package/dist/cli/graph-progress.d.ts

@@ -0,0 +1,31 @@
+/**
+ * graph-progress — graph's pipeline-stage → universal progress-currency mapping
+ * (ADR-0016), extracted to a React-free module so both the live runner
+ * (`graph-runner.tsx`) and the off-process worker (`graph-worker.ts`) share one
+ * source of stage labels + the event translation.
+ */
+import type { GraphProgressEvent, GraphStage } from './orchestrate.js';
+import type { ProgressEvent } from '@opensip-cli/cli-ui';
+/**
+ * Human label per graph pipeline stage (the checklist row text) for the
+ * single-program (exact) engine.
+ */
+export declare const STAGE_LABELS: Readonly<Record<GraphStage, string>>;
+/**
+ * Sharded-engine checklist labels. The sharded pipeline runs per-shard
+ * parse/walk/resolve INSIDE parallel subprocesses — that is the `parse` stage
+ * (the shard build, where the bulk of resolution happens) — then the main thread
+ * merges fragments (`walk`) and links cross-package calls (`resolve`). These
+ * labels name what each stage actually does in sharded mode, so the checklist
+ * doesn't mislabel the shard build as "Parse project" or show a near-empty
+ * "Resolve call sites". discover/index/features/rules are identical to the exact
+ * engine (same main-thread work).
+ */
+export declare const SHARDED_STAGE_LABELS: Readonly<Record<GraphStage, string>>;
+/**
+ * Map graph's pipeline event onto the universal progress currency. `sharded`
+ * selects the engine-appropriate checklist labels (the two engines run genuinely
+ * different stages; `isTTY`/transport never affects this — only the engine does).
+ */
+export declare function toProgressEvent(event: GraphProgressEvent, sharded?: boolean): ProgressEvent;
+//# sourceMappingURL=graph-progress.d.ts.map

package/dist/cli/graph-progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-progress.d.ts","sourceRoot":"","sources":["../../src/cli/graph-progress.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAQ7D,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAKrE,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,kBAAkB,EAAE,OAAO,UAAQ,GAAG,aAAa,CAczF"}

package/dist/cli/graph-progress.js

@@ -0,0 +1,56 @@
+/**
+ * graph-progress — graph's pipeline-stage → universal progress-currency mapping
+ * (ADR-0016), extracted to a React-free module so both the live runner
+ * (`graph-runner.tsx`) and the off-process worker (`graph-worker.ts`) share one
+ * source of stage labels + the event translation.
+ */
+/**
+ * Human label per graph pipeline stage (the checklist row text) for the
+ * single-program (exact) engine.
+ */
+export const STAGE_LABELS = {
+    discover: 'Discover files',
+    parse: 'Parse project',
+    walk: 'Walk catalog',
+    resolve: 'Resolve call sites',
+    index: 'Build indexes',
+    features: 'Derive features',
+    rules: 'Evaluate rules',
+};
+/**
+ * Sharded-engine checklist labels. The sharded pipeline runs per-shard
+ * parse/walk/resolve INSIDE parallel subprocesses — that is the `parse` stage
+ * (the shard build, where the bulk of resolution happens) — then the main thread
+ * merges fragments (`walk`) and links cross-package calls (`resolve`). These
+ * labels name what each stage actually does in sharded mode, so the checklist
+ * doesn't mislabel the shard build as "Parse project" or show a near-empty
+ * "Resolve call sites". discover/index/features/rules are identical to the exact
+ * engine (same main-thread work).
+ */
+export const SHARDED_STAGE_LABELS = {
+    ...STAGE_LABELS,
+    parse: 'Build shards',
+    walk: 'Merge catalog',
+    resolve: 'Link cross-package',
+};
+/**
+ * Map graph's pipeline event onto the universal progress currency. `sharded`
+ * selects the engine-appropriate checklist labels (the two engines run genuinely
+ * different stages; `isTTY`/transport never affects this — only the engine does).
+ */
+export function toProgressEvent(event, sharded = false) {
+    const labels = sharded ? SHARDED_STAGE_LABELS : STAGE_LABELS;
+    if (event.type === 'stage-start') {
+        return { type: 'stage-start', stage: event.stage, label: labels[event.stage] };
+    }
+    if (event.type === 'stage-done') {
+        return {
+            type: 'stage-done',
+            stage: event.stage,
+            durationMs: event.durationMs ?? 0,
+            detail: event.detail,
+        };
+    }
+    return { type: 'stage-cached', stage: event.stage };
+}
+//# sourceMappingURL=graph-progress.js.map