@opensip-cli/contracts 0.1.0

package/dist/exit-codes.js

@@ -0,0 +1,186 @@
+import { ConfigurationError, NetworkError, NotFoundError, PluginIncompatibleError, TimeoutError, ValidationError, } from '@opensip-cli/core';
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    RUNTIME_ERROR: 1,
+    CONFIGURATION_ERROR: 2,
+    CHECK_NOT_FOUND: 3,
+    REPORT_FAILED: 4,
+    /**
+     * A plugin was rejected by the compatibility gate (launch) — its
+     * declared `apiVersion` is out of range and it was explicitly requested
+     * (fail-closed; the skip path is silent). Dedicated rather than reusing
+     * `CONFIGURATION_ERROR` so an incompatible plugin is diagnosable from the
+     * exit code alone. Read by the CLI fail-closed admission path (Phase 3).
+     */
+    PLUGIN_INCOMPATIBLE: 5,
+};
+/**
+ * Canonical mapping from typed `ToolError` subclasses to CLI exit
+ * codes. This is the single source of truth for how typed errors flow
+ * into the process exit code — both the CLI's top-level
+ * `handleParseError` and any tool that chooses to handle its own
+ * `ToolError` locally route through this function.
+ *
+ * The mapping policy (see `Tool` interface JSDoc in
+ * `@opensip-cli/core` for the full contract):
+ *
+ *   - `NotFoundError`       → `CHECK_NOT_FOUND` (exit 3)
+ *   - `ConfigurationError`  → `CONFIGURATION_ERROR` (exit 2)
+ *   - `ValidationError`     → `CONFIGURATION_ERROR` (exit 2)
+ *   - `NetworkError`           → `REPORT_FAILED` (exit 4)
+ *   - `PluginIncompatibleError`→ `PLUGIN_INCOMPATIBLE` (exit 5)
+ *   - `TimeoutError`           → `RUNTIME_ERROR` (exit 1)
+ *   - any other `ToolError`    → `RUNTIME_ERROR` (exit 1)
+ */
+export function mapToolErrorToExitCode(error) {
+    if (error instanceof NotFoundError)
+        return EXIT_CODES.CHECK_NOT_FOUND;
+    if (error instanceof ConfigurationError)
+        return EXIT_CODES.CONFIGURATION_ERROR;
+    if (error instanceof ValidationError)
+        return EXIT_CODES.CONFIGURATION_ERROR;
+    if (error instanceof NetworkError)
+        return EXIT_CODES.REPORT_FAILED;
+    if (error instanceof PluginIncompatibleError)
+        return EXIT_CODES.PLUGIN_INCOMPATIBLE;
+    if (error instanceof TimeoutError)
+        return EXIT_CODES.RUNTIME_ERROR;
+    return EXIT_CODES.RUNTIME_ERROR;
+}
+/**
+ * True when any of the supplied substrings appear in `message`.
+ *
+ * Wraps the substring checks the rule table needs without spreading
+ * `String#includes` ladders back through `getErrorSuggestion`. Each
+ * rule keeps its own readable list of substrings and the function
+ * body stays a pure data walk.
+ */
+function containsAny(haystack, needles) {
+    return needles.some((needle) => haystack.includes(needle));
+}
+/**
+ * Ordered list of suggestion rules. Walked top-down by
+ * `getErrorSuggestion`; first hit wins, so order is load-bearing.
+ *
+ * Adding a new error category is one tuple. Do NOT replace this with
+ * a Chain-of-Responsibility class — a flat array is the contract here.
+ *
+ * The over-broad bare `'config'` substring from the previous
+ * implementation has been narrowed into two explicit rules — one for
+ * `opensip-cli.config.yml` (file shape) and one for `YAML` (parse
+ * shape). The bare substring matched common English words like
+ * `'configurable'` and `'reconfigure'` and produced false positives.
+ */
+const SUGGESTION_RULES = [
+    // Recipe not found — must come BEFORE the check-not-found rule because
+    // the fitness engine throws `Recipe not found: <id>` and the broad
+    // `/not found: (.+)/` regex would otherwise mis-classify it as
+    // CHECK_NOT_FOUND (exit 3) instead of CONFIGURATION_ERROR (exit 2).
+    {
+        match: (message) => {
+            const recipeRegex = /Recipe not found: (.+)/;
+            const m = recipeRegex.exec(message);
+            if (m)
+                return { capture: m[1] ?? null };
+            if (containsAny(message, ['Recipe not found:']))
+                return { capture: null };
+            return null;
+        },
+        suggest: (capture) => ({
+            message: `Recipe '${capture ?? 'unknown'}' not found.`,
+            action: 'Run opensip fit --recipes to see available recipes.',
+            exitCode: EXIT_CODES.CONFIGURATION_ERROR,
+        }),
+    },
+    // Check not found — only the explicit "Check not found: <slug>" form (plus
+    // the substring for no-capture cases). We deliberately dropped the previous
+    // broad `/not found: (.+)/` and bare "not found" contains check to avoid
+    // mis-classifying other "not found" errors (recipes, files, symbols, etc.)
+    // as CHECK_NOT_FOUND via the string suggestion path. The *typed* mapper
+    // (mapToolErrorToExitCode) already routes real NotFoundError correctly; this
+    // table is only for unstructured Error messages.
+    {
+        match: (message) => {
+            const slugMatch = /Check not found: (.+)/.exec(message);
+            if (slugMatch) {
+                return { capture: slugMatch[1] };
+            }
+            if (containsAny(message, ['Check not found:'])) {
+                return { capture: null };
+            }
+            return null;
+        },
+        suggest: (capture) => ({
+            message: `Check '${capture ?? 'unknown'}' not found.`,
+            action: 'Run opensip fit --list to see available checks.',
+            exitCode: EXIT_CODES.CHECK_NOT_FOUND,
+        }),
+    },
+    // Recipe not found — captures the verbatim error message so the
+    // surfaced suggestion preserves the recipe name.
+    {
+        match: (message) => (containsAny(message, ['Unknown recipe']) ? { capture: message } : null),
+        suggest: (capture) => ({
+            message: capture ?? 'Unknown recipe.',
+            action: 'Run opensip fit --recipes to see available recipes.',
+            exitCode: EXIT_CODES.CONFIGURATION_ERROR,
+        }),
+    },
+    // Config file error — opensip-cli.config.yml shape.
+    {
+        match: (message) => containsAny(message, ['opensip-cli.config.yml']) ? { capture: null } : null,
+        suggest: () => ({
+            message: 'Configuration error.',
+            action: 'Check opensip-cli.config.yml for syntax errors.',
+            exitCode: EXIT_CODES.CONFIGURATION_ERROR,
+        }),
+    },
+    // Config file error — YAML parse shape (paired with the file rule above).
+    {
+        match: (message) => (containsAny(message, ['YAML']) ? { capture: null } : null),
+        suggest: () => ({
+            message: 'Configuration error.',
+            action: 'Check opensip-cli.config.yml for syntax errors.',
+            exitCode: EXIT_CODES.CONFIGURATION_ERROR,
+        }),
+    },
+    // Permission denied
+    {
+        match: (message) => containsAny(message, ['EACCES', 'permission denied']) ? { capture: null } : null,
+        suggest: () => ({
+            message: 'Permission denied reading files.',
+            action: 'Check file permissions in the target directory.',
+            exitCode: EXIT_CODES.RUNTIME_ERROR,
+        }),
+    },
+    // No checks available
+    {
+        match: (message) => containsAny(message, ['No checks registered', 'No checks to run']) ? { capture: null } : null,
+        suggest: () => ({
+            message: 'No checks available to run.',
+            action: 'Install at least one @opensip-cli/checks-* package, or declare plugins.checkPackages in opensip-cli.config.yml.',
+            exitCode: EXIT_CODES.RUNTIME_ERROR,
+        }),
+    },
+    // Network error (report-to)
+    {
+        match: (message) => containsAny(message, ['fetch', 'ECONNREFUSED', 'network']) ? { capture: null } : null,
+        suggest: () => ({
+            message: 'Network error sending report.',
+            action: 'Check the --report-to URL and your network connection.',
+            exitCode: EXIT_CODES.REPORT_FAILED,
+        }),
+    },
+];
+/** Matches an arbitrary error against the suggestion-rule table; returns null if no rule fires. */
+export function getErrorSuggestion(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    for (const rule of SUGGESTION_RULES) {
+        const result = rule.match(message);
+        if (result !== null) {
+            return rule.suggest(result.capture);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=exit-codes.js.map

package/dist/exit-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,uBAAuB,EACvB,YAAY,EACZ,eAAe,GAEhB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,OAAO,EAAE,CAAC;IACV,aAAa,EAAE,CAAC;IAChB,mBAAmB,EAAE,CAAC;IACtB,eAAe,EAAE,CAAC;IAClB,aAAa,EAAE,CAAC;IAChB;;;;;;OAMG;IACH,mBAAmB,EAAE,CAAC;CACd,CAAC;AAEX;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAgB;IACrD,IAAI,KAAK,YAAY,aAAa;QAAE,OAAO,UAAU,CAAC,eAAe,CAAC;IACtE,IAAI,KAAK,YAAY,kBAAkB;QAAE,OAAO,UAAU,CAAC,mBAAmB,CAAC;IAC/E,IAAI,KAAK,YAAY,eAAe;QAAE,OAAO,UAAU,CAAC,mBAAmB,CAAC;IAC5E,IAAI,KAAK,YAAY,YAAY;QAAE,OAAO,UAAU,CAAC,aAAa,CAAC;IACnE,IAAI,KAAK,YAAY,uBAAuB;QAAE,OAAO,UAAU,CAAC,mBAAmB,CAAC;IACpF,IAAI,KAAK,YAAY,YAAY;QAAE,OAAO,UAAU,CAAC,aAAa,CAAC;IACnE,OAAO,UAAU,CAAC,aAAa,CAAC;AAClC,CAAC;AA0BD;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,QAAgB,EAAE,OAA0B;IAC/D,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,gBAAgB,GAA8B;IAClD,uEAAuE;IACvE,mEAAmE;IACnE,+DAA+D;IAC/D,oEAAoE;IACpE;QACE,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE;YACjB,MAAM,WAAW,GAAG,wBAAwB,CAAC;YAC7C,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACpC,IAAI,CAAC;gBAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;YACxC,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC,mBAAmB,CAAC,CAAC;gBAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAC1E,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACrB,OAAO,EAAE,WAAW,OAAO,IAAI,SAAS,cAAc;YACtD,MAAM,EAAE,qDAAqD;YAC7D,QAAQ,EAAE,UAAU,CAAC,mBAAmB;SACzC,CAAC;KACH;IAED,2EAA2E;IAC3E,4EAA4E;IAC5E,yEAAyE;IACzE,2EAA2E;IAC3E,wEAAwE;IACxE,6EAA6E;IAC7E,iDAAiD;IACjD;QACE,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE;YACjB,MAAM,SAAS,GAAG,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACxD,IAAI,SAAS,EAAE,CAAC;gBACd,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;YACnC,CAAC;YACD,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC,kBAAkB,CAAC,CAAC,EAAE,CAAC;gBAC/C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAC3B,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACrB,OAAO,EAAE,UAAU,OAAO,IAAI,SAAS,cAAc;YACrD,MAAM,EAAE,iDAAiD;YACzD,QAAQ,EAAE,UAAU,CAAC,eAAe;SACrC,CAAC;KACH;IAED,gEAAgE;IAChE,iDAAiD;IACjD;QACE,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5F,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACrB,OAAO,EAAE,OAAO,IAAI,iBAAiB;YACrC,MAAM,EAAE,qDAAqD;YAC7D,QAAQ,EAAE,UAAU,CAAC,mBAAmB;SACzC,CAAC;KACH;IAED,oDAAoD;IACpD;QACE,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CACjB,WAAW,CAAC,OAAO,EAAE,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI;QAC7E,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;YACd,OAAO,EAAE,sBAAsB;YAC/B,MAAM,EAAE,iDAAiD;YACzD,QAAQ,EAAE,UAAU,CAAC,mBAAmB;SACzC,CAAC;KACH;IAED,0EAA0E;IAC1E;QACE,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC/E,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;YACd,OAAO,EAAE,sBAAsB;YAC/B,MAAM,EAAE,iDAAiD;YACzD,QAAQ,EAAE,UAAU,CAAC,mBAAmB;SACzC,CAAC;KACH;IAED,oBAAoB;IACpB;QACE,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CACjB,WAAW,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI;QAClF,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;YACd,OAAO,EAAE,kCAAkC;YAC3C,MAAM,EAAE,iDAAiD;YACzD,QAAQ,EAAE,UAAU,CAAC,aAAa;SACnC,CAAC;KACH;IAED,sBAAsB;IACtB;QACE,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CACjB,WAAW,CAAC,OAAO,EAAE,CAAC,sBAAsB,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI;QAC/F,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;YACd,OAAO,EAAE,6BAA6B;YACtC,MAAM,EACJ,iHAAiH;YACnH,QAAQ,EAAE,UAAU,CAAC,aAAa;SACnC,CAAC;KACH;IAED,4BAA4B;IAC5B;QACE,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CACjB,WAAW,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI;QACvF,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;YACd,OAAO,EAAE,+BAA+B;YACxC,MAAM,EAAE,wDAAwD;YAChE,QAAQ,EAAE,UAAU,CAAC,aAAa;SACnC,CAAC;KACH;CACF,CAAC;AAEF,mGAAmG;AACnG,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAEjE,KAAK,MAAM,IAAI,IAAI,gBAAgB,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/graph-catalog.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Type-only structural shapes for the v0.3 Code Paths panel.
+ *
+ * The graph engine's catalog.json is consumed here purely by JSON shape;
+ * this file MUST NOT import from `@opensip-cli/graph`. The shape is
+ * intentionally duplicated as readonly structural types — this decouples
+ * the dashboard panel from the graph engine's runtime types so
+ * @opensip-cli/contracts stays a pure type-only kernel boundary.
+ *
+ * Runtime exports are forbidden. Only `export type` and `export interface`.
+ */
+export type GraphFunctionKind = 'function-declaration' | 'function-expression' | 'arrow' | 'method' | 'constructor' | 'getter' | 'setter' | 'module-init';
+export type GraphCallResolution = 'static' | 'method-dispatch' | 'jsx' | 'constructor' | 'unknown' | 'dynamic-string'
+/** Fast-mode (syntactic) edge: resolved from name + import graph, no
+ *  type checker. Always approximate — carries capped confidence. */
+ | 'syntactic'
+/** Cross-shard boundary edge recovered by the semantic linker: the import
+ *  specifier + callee name resolved to a UNIQUE exported occurrence in the
+ *  imported package (the type checker's conclusion). High-confidence; the
+ *  linker declines on ambiguity rather than guessing. */
+ | 'semantic';
+export type GraphCallConfidence = 'high' | 'medium' | 'low';
+/** Mirror of the engine's `ResolutionMode`. `exact` = semantic;
+ *  `fast` = syntactic (approximate). Kept structurally in sync. */
+export type GraphResolutionMode = 'exact' | 'fast';
+export type GraphVisibility = 'exported' | 'module-local' | 'private';
+export interface GraphParam {
+    readonly name: string;
+    readonly optional: boolean;
+    readonly rest: boolean;
+}
+export interface GraphCallEdge {
+    readonly to: readonly string[];
+    readonly line: number;
+    readonly column: number;
+    readonly resolution: GraphCallResolution;
+    readonly confidence: GraphCallConfidence;
+    readonly text: string;
+    /** True for an edge recovered by the cross-shard boundary pass (always
+     *  syntactic). Mirrors the engine `CallEdge.crossShard`. */
+    readonly crossShard?: boolean;
+}
+export interface GraphFunctionOccurrence {
+    readonly bodyHash: string;
+    readonly simpleName: string;
+    readonly qualifiedName: string;
+    readonly filePath: string;
+    /**
+     * The package this occurrence belongs to — the `name` of its nearest
+     * enclosing `package.json` (e.g. `@opensip-cli/fitness`), or the
+     * top-level path segment when there is no manifest. Computed at build
+     * time (the dashboard has no filesystem access). Absent on legacy
+     * catalogs; consumers fall back to deriving it from `filePath`.
+     */
+    readonly package?: string;
+    readonly line: number;
+    readonly column: number;
+    readonly endLine: number;
+    readonly kind: GraphFunctionKind;
+    readonly params: readonly GraphParam[];
+    readonly returnType: string | null;
+    readonly enclosingClass: string | null;
+    readonly decorators: readonly string[];
+    readonly visibility: GraphVisibility;
+    readonly inTestFile: boolean;
+    readonly definedInGenerated: boolean;
+    readonly calls: readonly GraphCallEdge[];
+}
+/** Mirror of the engine `BlastScore`. */
+export interface GraphBlastScore {
+    readonly direct: number;
+    readonly transitive: number;
+    readonly score: number;
+}
+/** Mirror of the engine `FunctionFeatures` (per-function columns). */
+export interface GraphFunctionFeatures {
+    readonly bodyLines: number;
+    readonly blast?: GraphBlastScore;
+    readonly reachableFromEntry?: boolean;
+    readonly testReachable?: boolean;
+    readonly reachableOnlyFromTests?: boolean;
+}
+/** Mirror of the engine `PackageFeatures` (per-package coupling degrees). */
+export interface GraphPackageFeatures {
+    readonly couplingOut: number;
+    readonly couplingIn: number;
+}
+/** Mirror of the engine `SccFeatures` (one strongly-connected component). */
+export interface GraphSccFeatures {
+    readonly id: string;
+    readonly members: readonly string[];
+    readonly sccSize: number;
+    readonly crossesPackages: boolean;
+}
+/** Mirror of the engine `PackageEdgeFeature` (one directed coupling edge). */
+export interface GraphPackageEdgeFeature {
+    readonly callerPackage: string;
+    readonly calleePackage: string;
+    readonly count: number;
+}
+/**
+ * Structural mirror of the engine `PersistedFeatures`. Every entity is
+ * optional — only the columns a dashboard-bound run materialized are present.
+ * The dashboard reads these instead of recomputing blast / SCC / coupling
+ * client-side.
+ */
+export interface GraphFeatures {
+    readonly function?: Readonly<Record<string, GraphFunctionFeatures>>;
+    readonly package?: Readonly<Record<string, GraphPackageFeatures>>;
+    readonly scc?: readonly GraphSccFeatures[];
+    readonly edge?: readonly GraphPackageEdgeFeature[];
+}
+/**
+ * Public catalog shape consumed by the dashboard.
+ *
+ * The `language` field carries the adapter id (e.g. 'typescript', 'python',
+ * 'rust') and `cacheKey` is an opaque per-adapter invalidation string. Legacy
+ * catalog payloads classify as `invalid` at load time.
+ *
+ * `cacheKey` is optional here because external callers parsing
+ * an older catalog they have on disk would otherwise fail to load the file with
+ * this type. Engine-internal code requires it.
+ */
+export interface GraphCatalog {
+    readonly version: string;
+    readonly tool: string;
+    readonly language: string;
+    readonly builtAt: string;
+    readonly cacheKey?: string;
+    readonly filesFingerprint?: string;
+    /** The resolution tier that produced this catalog. Absent ⇒ `'exact'`
+     *  (historical behavior). Mirrors the engine `Catalog.resolutionMode`. */
+    readonly resolutionMode?: GraphResolutionMode;
+    readonly functions: Readonly<Record<string, readonly GraphFunctionOccurrence[]>>;
+    /**
+     * Derived feature columns (blast / SCC / package coupling). Present only on
+     * catalogs produced by a dashboard-bound run (ADR-0006); the dashboard falls
+     * back to a no-data state when absent. Mirrors the engine
+     * `Catalog.features` so `loadCatalogContract` stays a cast-free widening.
+     */
+    readonly features?: GraphFeatures;
+}
+//# sourceMappingURL=graph-catalog.d.ts.map

package/dist/graph-catalog.d.ts.map

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

package/dist/graph-catalog.js

@@ -0,0 +1,13 @@
+/**
+ * Type-only structural shapes for the v0.3 Code Paths panel.
+ *
+ * The graph engine's catalog.json is consumed here purely by JSON shape;
+ * this file MUST NOT import from `@opensip-cli/graph`. The shape is
+ * intentionally duplicated as readonly structural types — this decouples
+ * the dashboard panel from the graph engine's runtime types so
+ * @opensip-cli/contracts stays a pure type-only kernel boundary.
+ *
+ * Runtime exports are forbidden. Only `export type` and `export interface`.
+ */
+export {};
+//# sourceMappingURL=graph-catalog.js.map

package/dist/graph-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-catalog.js","sourceRoot":"","sources":["../src/graph-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @opensip-cli/contracts — shared contract types.
+ *
+ * Tool packages (fitness, simulation) and the CLI entry-point both
+ * depend on this package for:
+ *   - CLI option / output / result types
+ *   - Exit code constants and error suggestions
+ *   - The cross-tool StoredSession type (the SessionRepo runtime + the
+ *     sessions schema live in @opensip-cli/session-store)
+ *
+ * The GraphCatalog shape is DEFINED here (./graph-catalog.ts), not
+ * re-exported from elsewhere. It is the contract surface between the
+ * graph tool (which writes catalog.json) and @opensip-cli/dashboard
+ * (which renders it): both producer and consumer depend on contracts
+ * from below, so the shape lives in the layer beneath both. contracts
+ * holds zero runtime dependency on dashboard or graph — these are
+ * type-only declarations.
+ *
+ * contracts depends only on @opensip-cli/core. Tools depend on
+ * contracts. The CLI entry-point depends on contracts and on every
+ * tool package — the dependency graph stays acyclic.
+ */
+export type { FitOptions, InitOptions, ToolOptions } from './types.js';
+export type { SignalEnvelope, RunVerdict, UnitResult, BuildEnvelopeInput, } from './signal-envelope.js';
+export { buildSignalEnvelope } from './signal-envelope.js';
+export type { CommandResult, ClearDoneResult, ConfigureDoneResult, UninstallDoneResult, FitDoneResult, SimDoneResult, GraphDoneResult, GateDoneResult, GraphStatusResult, TextLinesResult, ToolsListResult, ToolsListRow, ToolsValidateResult, ToolsValidateSection, ToolsInstallResult, ToolsUninstallResult, ToolsDataPurgeResult, ListChecksResult, ListRecipesResult, HistorySession, HistoryResult, ReportResult, InitResult, PreExistingFile, SimNoticeResult, PluginResult, PluginInfo, SyncEntry, SessionReplayResult, HelpResult, ErrorResult, VerboseDetail, FindingGroup, FindingLine, } from './command-results.js';
+export type { CommandOutcome, CommandOutcomeStatus, ErrorDetail, WarningDetail, RenderHints, } from './command-outcome.js';
+export type { RunDiagnostics, DiagnosticEvent, DiagnosticPhase, DiagnosticLevel, } from '@opensip-cli/core';
+export { passRate } from './score.js';
+export { EXIT_CODES, getErrorSuggestion, mapToolErrorToExitCode } from './exit-codes.js';
+export type { ErrorSuggestion } from './exit-codes.js';
+export { PLUGIN_API_VERSION, checkCompatibility } from '@opensip-cli/core';
+export type { RawToolPluginManifest, ToolPluginManifest, ToolCommandManifest, ToolProvenance, ToolSource, CompatibilityVerdict, CapabilityDomainSpec, ToolCapabilityDeclaration, CapabilityContributionKind, } from '@opensip-cli/core';
+export { defineCommand, COMMON_FLAG_KEYS, RAW_STREAM_REASONS } from '@opensip-cli/core';
+export type { CommandSpec, OptionSpec, ArgSpec, CommandHandler, CommandContext, CommandOutputMode, CommandScopeRequirement, RawStreamReason, } from '@opensip-cli/core';
+export { resolveToolRecipeName, BUILTIN_DEFAULT_RECIPE } from './recipe-default.js';
+export type { ResolvedRecipe, RecipeSource } from './recipe-default.js';
+export { commonFlags, applyCommonFlags, MANDATORY_COMMON_FLAGS } from './cli-flags.js';
+export type { CommonFlagKey, CommonFlagSpec } from './cli-flags.js';
+export { buildFindingGroups } from './verbose-detail.js';
+export type { FindingGroupUnit } from './verbose-detail.js';
+export type { StoredSession, StoredSessionHostMetrics, ToolSessionReplay, } from './session-types.js';
+export type { GraphCatalog, GraphFunctionOccurrence, GraphCallEdge, GraphParam, GraphFunctionKind, GraphCallResolution, GraphCallConfidence, GraphResolutionMode, GraphVisibility, GraphFeatures, GraphFunctionFeatures, GraphPackageFeatures, GraphSccFeatures, GraphPackageEdgeFeature, GraphBlastScore, } from './graph-catalog.js';
+import type { Command } from 'commander';
+/**
+ * Type alias for Commander's `Command` class — re-exported here so the
+ * host's command-spec mounting (`mountCommandSpec`) and the tool lifecycle
+ * can type the root `program` handle without a direct `commander` import or
+ * an `as Command` cast. (Tools themselves no longer touch Commander — they
+ * declare `commandSpecs`; the host owns `program`.)
+ *
+ * `commander` is an OPTIONAL peer dependency of
+ * `@opensip-cli/contracts`. `CliProgram` is now primarily a host-side
+ * type (the `Tool` contract no longer surfaces it — tools declare
+ * `commandSpecs`), so any code referencing it needs `commander` resolvable
+ * in its own `node_modules`; pnpm/npm will surface the peer requirement in
+ * install output. Code that never touches `CliProgram` can skip commander
+ * entirely. The alias erases at compile time — no runtime commander require
+ * lands in `dist/index.js`.
+ */
+export type CliProgram = Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,56 @@
+/**
+ * @opensip-cli/contracts — shared contract types.
+ *
+ * Tool packages (fitness, simulation) and the CLI entry-point both
+ * depend on this package for:
+ *   - CLI option / output / result types
+ *   - Exit code constants and error suggestions
+ *   - The cross-tool StoredSession type (the SessionRepo runtime + the
+ *     sessions schema live in @opensip-cli/session-store)
+ *
+ * The GraphCatalog shape is DEFINED here (./graph-catalog.ts), not
+ * re-exported from elsewhere. It is the contract surface between the
+ * graph tool (which writes catalog.json) and @opensip-cli/dashboard
+ * (which renders it): both producer and consumer depend on contracts
+ * from below, so the shape lives in the layer beneath both. contracts
+ * holds zero runtime dependency on dashboard or graph — these are
+ * type-only declarations.
+ *
+ * contracts depends only on @opensip-cli/core. Tools depend on
+ * contracts. The CLI entry-point depends on contracts and on every
+ * tool package — the dependency graph stays acyclic.
+ */
+export { buildSignalEnvelope } from './signal-envelope.js';
+// Canonical pass-rate (`score`) computation — shared by every tool that
+// builds a signal envelope so the dashboard "PASS RATE" stays consistent
+// across fit/graph and cannot drift back into per-tool formulas.
+export { passRate } from './score.js';
+// Exit codes + error suggestion helper + typed-error → exit-code mapping
+export { EXIT_CODES, getErrorSuggestion, mapToolErrorToExitCode } from './exit-codes.js';
+// Static tool-plugin manifest + the plugin-API epoch + provenance types +
+// the pure compatibility gate (launch raw-vs-admitted contract).
+// DEFINED in @opensip-cli/core (next to the Tool contract; core cannot
+// import contracts); re-exported here for the public Tool↔runner surface.
+export { PLUGIN_API_VERSION, checkCompatibility } from '@opensip-cli/core';
+// The `cli:` block loader (`loadCliDefaults` / `CliDefaults`) moved to
+// `@opensip-cli/config` in ADR-0023 — its runtime YAML projection
+// was the standing "contracts is types-only" charter violation. Importers now
+// take it from the config layer.
+// Command-plane types (launch, §5.4) — the declarative CommandSpec a
+// tool exports for the host to mount, replacing raw-Commander access. DEFINED in
+// @opensip-cli/core (beside the Tool contract; core cannot import contracts);
+// re-exported here for the public Tool↔runner surface. `CommonFlagKey` is also
+// re-exported from ./cli-flags (which now sources it from core) — both paths
+// resolve to the same kernel type.
+export { defineCommand, COMMON_FLAG_KEYS, RAW_STREAM_REASONS } from '@opensip-cli/core';
+// Tool-scoped recipe-default resolution (ADR-0022). The pure resolver every
+// tool uses to pick its recipe name from --recipe / <tool>.recipe / default.
+export { resolveToolRecipeName, BUILTIN_DEFAULT_RECIPE } from './recipe-default.js';
+// Cross-tool common-flag registry (ADR-0021). One source of truth for the flags
+// every tool's run command shares; tools apply them via applyCommonFlags rather
+// than re-declaring `--json`/`--cwd`/`--report-to`/… per tool.
+export { commonFlags, applyCommonFlags, MANDATORY_COMMON_FLAGS } from './cli-flags.js';
+// Verbose-detail builder (ADR-0021) — shared Signal[] → FindingGroup[] mapping
+// for the tools' `verboseDetail` carrier (fit + sim; one source, not per-tool).
+export { buildFindingGroups } from './verbose-detail.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAcH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAiE3D,wEAAwE;AACxE,yEAAyE;AACzE,iEAAiE;AACjE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,yEAAyE;AACzE,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGzF,0EAA0E;AAC1E,iEAAiE;AACjE,uEAAuE;AACvE,0EAA0E;AAC1E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAe3E,uEAAuE;AACvE,kEAAkE;AAClE,8EAA8E;AAC9E,iCAAiC;AAEjC,qEAAqE;AACrE,iFAAiF;AACjF,8EAA8E;AAC9E,+EAA+E;AAC/E,6EAA6E;AAC7E,mCAAmC;AACnC,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAYxF,4EAA4E;AAC5E,6EAA6E;AAC7E,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAGpF,gFAAgF;AAChF,gFAAgF;AAChF,+DAA+D;AAC/D,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAGvF,+EAA+E;AAC/E,gFAAgF;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/recipe-default.d.ts

@@ -0,0 +1,53 @@
+/**
+ * recipe-default — resolve which recipe NAME a tool should use (ADR-0022).
+ *
+ * Recipes are tool-scoped: `fit`, `graph`, and `sim` each own a separate recipe
+ * registry with a disjoint namespace, so a default recipe is a per-tool setting.
+ * Each tool reads its own `<tool>.recipe` config block.
+ *
+ * This helper is pure — the caller supplies the two already-read inputs and
+ * gets back the chosen name plus a `tolerant` flag. Tolerance is the ADR-0022
+ * guardrail split: a name that came from CONFIG (`<tool>.recipe`) but is absent
+ * from the active tool's registry should
+ * fall back to the tool's built-in `default` rather than abort the run — the
+ * default may legitimately belong to a different tool. An EXPLICIT `--recipe`
+ * flag stays strict (`tolerant: false`) so a typo still hard-fails.
+ *
+ * Lives in contracts (not core, not a single tool) because all three tools
+ * consume it and it is part of the CLI↔tool config seam. Resolution precedence:
+ *
+ *   explicit `--recipe` > `<tool>.recipe` > `default`
+ */
+/** Where the resolved recipe name came from, in precedence order. */
+export type RecipeSource = 'flag' | 'tool-config' | 'builtin';
+/** Built-in recipe name every tool registers (all rules / all checks). */
+export declare const BUILTIN_DEFAULT_RECIPE = "default";
+/**
+ * The outcome of {@link resolveToolRecipeName}: the chosen recipe `name`, which
+ * input it came from (`source`), and whether an unknown `name` should be
+ * tolerated (fall back to the built-in default) or hard-fail.
+ */
+export interface ResolvedRecipe {
+    /** The recipe name the tool should look up in its registry. */
+    readonly name: string;
+    /** Which input supplied {@link name}. */
+    readonly source: RecipeSource;
+    /**
+     * `false` only when `source === 'flag'`. When `true`, an unknown `name`
+     * should fall back to {@link BUILTIN_DEFAULT_RECIPE} with a warning instead
+     * of aborting — the name came from config and may target another tool.
+     */
+    readonly tolerant: boolean;
+}
+/**
+ * Resolve the recipe name for a tool from its three possible sources. See the
+ * module docstring for precedence and the tolerance contract (ADR-0022).
+ *
+ * @param input.explicit   The `--recipe <name>` flag value (strict if present).
+ * @param input.toolRecipe The tool's own `<tool>.recipe` config default.
+ */
+export declare function resolveToolRecipeName(input: {
+    readonly explicit?: string;
+    readonly toolRecipe?: string;
+}): ResolvedRecipe;
+//# sourceMappingURL=recipe-default.d.ts.map

package/dist/recipe-default.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe-default.d.ts","sourceRoot":"","sources":["../src/recipe-default.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qEAAqE;AACrE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;AAE9D,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,YAAY,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAOD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,GAAG,cAAc,CAoBjB"}

package/dist/recipe-default.js

@@ -0,0 +1,55 @@
+/**
+ * recipe-default — resolve which recipe NAME a tool should use (ADR-0022).
+ *
+ * Recipes are tool-scoped: `fit`, `graph`, and `sim` each own a separate recipe
+ * registry with a disjoint namespace, so a default recipe is a per-tool setting.
+ * Each tool reads its own `<tool>.recipe` config block.
+ *
+ * This helper is pure — the caller supplies the two already-read inputs and
+ * gets back the chosen name plus a `tolerant` flag. Tolerance is the ADR-0022
+ * guardrail split: a name that came from CONFIG (`<tool>.recipe`) but is absent
+ * from the active tool's registry should
+ * fall back to the tool's built-in `default` rather than abort the run — the
+ * default may legitimately belong to a different tool. An EXPLICIT `--recipe`
+ * flag stays strict (`tolerant: false`) so a typo still hard-fails.
+ *
+ * Lives in contracts (not core, not a single tool) because all three tools
+ * consume it and it is part of the CLI↔tool config seam. Resolution precedence:
+ *
+ *   explicit `--recipe` > `<tool>.recipe` > `default`
+ */
+/** Built-in recipe name every tool registers (all rules / all checks). */
+export const BUILTIN_DEFAULT_RECIPE = 'default';
+/** A config value counts as "set" only when it is a non-empty string. */
+function isSet(value) {
+    return value !== undefined && value !== '';
+}
+/**
+ * Resolve the recipe name for a tool from its three possible sources. See the
+ * module docstring for precedence and the tolerance contract (ADR-0022).
+ *
+ * @param input.explicit   The `--recipe <name>` flag value (strict if present).
+ * @param input.toolRecipe The tool's own `<tool>.recipe` config default.
+ */
+export function resolveToolRecipeName(input) {
+    if (isSet(input.explicit)) {
+        return {
+            name: input.explicit,
+            source: 'flag',
+            tolerant: false,
+        };
+    }
+    if (isSet(input.toolRecipe)) {
+        return {
+            name: input.toolRecipe,
+            source: 'tool-config',
+            tolerant: true,
+        };
+    }
+    return {
+        name: BUILTIN_DEFAULT_RECIPE,
+        source: 'builtin',
+        tolerant: true,
+    };
+}
+//# sourceMappingURL=recipe-default.js.map

package/dist/recipe-default.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe-default.js","sourceRoot":"","sources":["../src/recipe-default.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC;AAoBhD,yEAAyE;AACzE,SAAS,KAAK,CAAC,KAAyB;IACtC,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAGrC;IACC,IAAI,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,QAAQ;YACpB,MAAM,EAAE,MAAM;YACd,QAAQ,EAAE,KAAK;SAChB,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,UAAU;YACtB,MAAM,EAAE,aAAa;YACrB,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE,SAAS;QACjB,QAAQ,EAAE,IAAI;KACf,CAAC;AACJ,CAAC"}

package/dist/recipe-default.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=recipe-default.test.d.ts.map

package/dist/recipe-default.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe-default.test.d.ts","sourceRoot":"","sources":["../src/recipe-default.test.ts"],"names":[],"mappings":""}