@opensip-cli/graph 0.1.0

package/dist/cli/graph.d.ts

@@ -0,0 +1,171 @@
+/**
+ * `opensip graph` — main subcommand handler.
+ *
+ * Runs the full pipeline and prints a comprehensive report covering
+ * rules, entry points, and catalog summary in one invocation. Per
+ * DEC-8, a switch in this handler dispatches to the right renderer.
+ *
+ * CLI shape (language-neutral):
+ *   - `graph` — whole project, auto-detected language(s)
+ *   - `graph <path> [<path>...]` — scope to one or more subtrees
+ *   - `graph --workspace` — fan out across detected workspace units
+ *     (polyglot: aggregates every adapter's units per spec D8b)
+ *   - `graph --language <name>` — force a single adapter
+ *
+ * History: v0.2 originally split this into three subcommands (`graph`,
+ * `graph-orphans`, `graph-entry-points`). The two filtered views are
+ * now sections in this unified report. The TS-flavored `--package` /
+ * `--packages` flags were retired in favor of the polyglot surface
+ * above; see docs/plans/graph-cli-language-neutral-scoping/.
+ */
+import { type LiveGraphOutput } from './graph-report.js';
+import { runGraph } from './orchestrate.js';
+import type { GraphCommandOptions } from './graph-options.js';
+import type { Shard } from './orchestrate/shard-model.js';
+import type { GraphProgressCallback } from './orchestrate.js';
+import type { GraphConfig, ResolutionMode, Rule } from '../types.js';
+import type { SignalEnvelope } from '@opensip-cli/contracts';
+import type { Signal, ToolCliContext, ToolSessionContribution } from '@opensip-cli/core';
+import type { DataStore } from '@opensip-cli/datastore';
+export type { GraphCommandOptions } from './graph-options.js';
+export type { UnifiedReportInput, LiveGraphOutput } from './graph-report.js';
+/**
+ * The result of a static graph run that the command handler returns to the
+ * host (host-owned-run-timing Phase 3). Carries the run's deliverable
+ * {@link SignalEnvelope} (for cloud + `--report-to` egress) plus the OPTIONAL
+ * generic-session contribution the host run plane persists after the handler
+ * resolves. `session` is present only on the human-facing render path (and the
+ * `--workspace` aggregate); the export/carrier modes (`--json`, `--report-to`,
+ * gate) return `{ envelope }` with no session — preserving "one human
+ * invocation = one session".
+ *
+ * Graph never writes the generic `StoredSession` row itself: it builds the
+ * contribution from BRANDED {@link FinalizedSignals} and hands it up; the host
+ * stamps `startedAt`/`completedAt`/`durationMs`/`id` and performs the save.
+ *
+ * `envelope` is optional because the `--workspace` aggregate carries a
+ * `session` (the one aggregate row the host persists) but NO deliverable
+ * envelope — the parent aggregates per-unit findings for the dashboard, not
+ * signals for the cloud (audit P1-2). The command handler's egress is guarded
+ * on `outcome?.envelope`, so a session-only outcome cloud-emits nothing.
+ */
+export interface GraphRunOutcome {
+    readonly envelope?: SignalEnvelope;
+    readonly session?: ToolSessionContribution;
+}
+/**
+ * Run graph and return the run's {@link GraphRunOutcome} — the deliverable
+ * {@link SignalEnvelope} (so the composition root can cloud + `--report-to`
+ * deliver it, ADR-0011) plus the optional generic-session contribution the
+ * host run plane persists (host-owned-run-timing Phase 3; graph never writes
+ * the row itself). Returns `undefined` for the paths that do NOT produce a
+ * deliverable envelope: plain `--json` (the `--workspace` child carrier —
+ * children must not each emit cloud signals) and `--workspace` itself (the
+ * parent aggregates per-unit findings for the dashboard, not signals for the
+ * cloud — audit P1-2), and any error path. The `--workspace` path returns its
+ * outcome through `executeWorkspaceGraph` so the host persists the single
+ * aggregate session. tool.ts calls `cli.deliverSignals` only when an envelope
+ * comes back.
+ */
+export declare function executeGraph(opts: GraphCommandOptions, cli: ToolCliContext): Promise<GraphRunOutcome | undefined>;
+/**
+ * Resolve a project's shard set the SAME way a production `graph` run does
+ * (workspace units → canonical-file partition, else synthetic flat shards),
+ * exposed for the real-repo equivalence guardrail (`graph-equivalence-check`).
+ * Returns `[]` when the project isn't shardable (≤1 shard / no worker script) —
+ * the guardrail rejects that, since the comparison is only meaningful on a
+ * shardable multi-package repo. Reuses the private {@link resolveShards} so
+ * there is ONE shard-resolution model, never a drifting copy.
+ */
+export declare function resolveShardsForCwd(cwd: string, cliScript: string, cli: ToolCliContext): Promise<readonly Shard[]>;
+/**
+ * The serializable live-build request the interactive runner (`graph-runner.tsx`)
+ * hands the engine. Mirrors the subset of {@link GraphCommandOptions} the
+ * whole-project live view exercises: cwd scope, cache/resolution tier, the
+ * resolved rule subset + config, and `exact` (which, with the project's
+ * shardability, selects the engine — ADR-0032). `cliScript` is needed to spawn
+ * the shard subprocesses for the in-process sharded path.
+ */
+export interface GraphLiveBuildArgs {
+    readonly cwd: string;
+    readonly noCache?: boolean;
+    readonly resolution?: ResolutionMode;
+    readonly exact?: boolean;
+    readonly config?: GraphConfig;
+    readonly rules?: readonly Rule[];
+    readonly cliScript?: string;
+}
+/**
+ * Resolve the build engine for the interactive live path — the SAME policy
+ * `executeGraph` uses (ADR-0032): the SHARDED engine when `--exact` is absent
+ * and the project yields >1 non-empty shard, the EXACT (single-program) engine
+ * otherwise. Returns the shard set (`length > 1` ⇒ sharded) so the live runner
+ * can decide its transport: sharded runs in-process (its shards are already
+ * subprocesses), exact runs off-process in the `graph-run-worker` (ADR-0028).
+ * `isTTY` is NEVER consulted — the engine is a pure function of the request +
+ * shardability, identical to the static path.
+ */
+export declare function resolveLiveEngineShards(args: GraphLiveBuildArgs, cli: ToolCliContext): Promise<Shard[]>;
+/**
+ * Run the SHARDED build in-process for the live view and reduce it to the slim,
+ * serializable {@link LiveGraphOutput} the interactive runner consumes —
+ * IDENTICAL in shape to what the off-process exact worker streams back, so both
+ * live transports converge on one payload. The heavy per-shard parse/walk/resolve
+ * runs in the shard SUBPROCESSES, so the main thread (which animates the Ink
+ * checklist) is only orchestrating + merging — no off-process worker is needed
+ * for the sharded path (ADR-0032). Progress events flow through `onProgress`,
+ * mapped onto the same seven canonical stages the exact engine emits.
+ *
+ * Crosses the single suppression chokepoint via {@link buildLiveGraphOutput}
+ * (against `args.cwd`, the build root) — so the live sharded path waives
+ * `@graph-ignore` directives IDENTICALLY to the static/exact paths (ADR-0014/0031).
+ */
+export declare function runShardedLiveBuild(args: GraphLiveBuildArgs, shards: readonly Shard[], datastore: DataStore | undefined, onProgress: GraphProgressCallback): Promise<LiveGraphOutput>;
+export declare function dispatchGraphResult(opts: GraphCommandOptions, rawResult: Awaited<ReturnType<typeof runGraph>>, cli: ToolCliContext, startedAt: string, suppressionRoot: string): Promise<GraphRunOutcome | undefined>;
+/**
+ * Shared contribution builder: derive graph's opaque session payload + the
+ * generic verdict (`score`/`passed`) from a run's engine-slug `Signal[]`. The
+ * payload is graph-owned detail (summary + rule-grouped per-signal findings);
+ * the generic session row holds zero graph vocabulary. `score`/`passed` mirror
+ * exactly what the former `saveGraphSession` computed (pass rate over
+ * passed/total rules; `passed` ⇔ no error-severity signals).
+ */
+/**
+ * Engine slugs of every rule a run evaluated — the session payload's full rule
+ * list, so a CLEAN run still records a PASS row per rule (the session detail
+ * then shows the complete rule list, exactly the way fitness shows every check,
+ * not just the failing ones).
+ *
+ * Prefer the EXPLICITLY-resolved rule set the run actually used (the `--recipe`
+ * subset, threaded from the dispatch seam as `args.rules`); otherwise read the
+ * current scope's full registry — this mirrors `runGraph`'s own
+ * `args.rules ?? currentRules()` resolution, so the recorded set is exactly what
+ * ran. Degrades to the empty set (fired-rules-only) when no graph scope is
+ * active — e.g. an isolated dispatch unit test; production always runs the
+ * handler inside the entered RunScope.
+ *
+ * Exported so BOTH contribution-building paths derive the evaluated set
+ * identically: the static `executeGraph` dispatch (below) AND the live Ink
+ * runner (`graph-runner.tsx`). Before it was shared, only the static path
+ * threaded it, so a clean run on the live (interactive) path persisted an empty
+ * `checks[]` and the report rendered "no results" instead of the rule list.
+ */
+export declare function evaluatedRuleSlugs(explicitRules?: readonly Rule[]): readonly string[];
+/**
+ * Build graph's generic-session contribution from a run's engine-slug
+ * `Signal[]` plus the engine slugs of the rules it evaluated. The SINGLE
+ * assembly point for both the static dispatch path and the live Ink runner, so
+ * the contribution shape (and the "every evaluated rule gets a row" behaviour)
+ * can never drift between them again. The payload is graph-owned detail
+ * (summary + rule-grouped per-signal findings); the generic session row holds
+ * zero graph vocabulary. `score`/`passed` follow fit's semantics (pass rate over
+ * passed/total rules; `passed` ⇔ no error-severity signal).
+ *
+ * `evaluatedSlugs` defaults to {@link evaluatedRuleSlugs}() (the scope's full
+ * registry) for the static callers, which build inside the entered RunScope; the
+ * live runner passes its `args.rules`-derived set explicitly.
+ */
+export declare function contributionFromSignals(opts: Pick<GraphCommandOptions, 'cwd' | 'recipe'>, signals: readonly Signal[], evaluatedSlugs?: readonly string[]): ToolSessionContribution;
+export declare function handleGraphError(label: string, error: unknown, cli: ToolCliContext): void;
+export { buildUnifiedReportLines, buildLiveGraphOutput } from './graph-report.js';
+//# sourceMappingURL=graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/cli/graph.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;GAmBG;AA6BH,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EAGL,QAAQ,EAET,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,8BAA8B,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAkB,MAAM,kBAAkB,CAAC;AAE9E,OAAO,KAAK,EAGV,WAAW,EAEX,cAAc,EACd,IAAI,EACL,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAmB,cAAc,EAAiB,MAAM,wBAAwB,CAAC;AAC7F,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAIxD,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAC;CAC5C;AAcD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,mBAAmB,EACzB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CA2KtC;AAqID;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,SAAS,KAAK,EAAE,CAAC,CAG3B;AAoID;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,kBAAkB,EACxB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,KAAK,EAAE,CAAC,CAYlB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,kBAAkB,EACxB,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,eAAe,CAAC,CA0B1B;AAgMD,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,mBAAmB,EACzB,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,EAC/C,GAAG,EAAE,cAAc,EACnB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CA6BtC;AA0RD;;;;;;;GAOG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,CAAC,EAAE,SAAS,IAAI,EAAE,GAAG,SAAS,MAAM,EAAE,CASrF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,KAAK,GAAG,QAAQ,CAAC,EACjD,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,cAAc,GAAE,SAAS,MAAM,EAAyB,GACvD,uBAAuB,CAUzB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,CAsBzF;AAED,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}