statelyai 0.16.0 → 0.17.0

package/dist/coverageWorker.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/coverageWorker.mjs

@@ -0,0 +1,178 @@
+import { createRequire, registerHooks } from "node:module";
+import { readFile, realpath } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parentPort, workerData } from "node:worker_threads";
+import ts from "typescript";
+import { register } from "tsx/esm/api";
+import { createXStateSourceCoverageGraph, extractXStateSourceCoverage, getXStateSourceCoverageEventCases, instrumentXStateSourceCoverage } from "@statelyai/sdk/source-coverage";
+
+//#region src/sourceCoverageRunner.ts
+/** Executes trusted source with ordinary local permissions; called in a worker. */
+async function runSourceCoverageFile(options) {
+	const fileName = await realpath(resolve(options.sourceFile));
+	const source = await readFile(fileName, "utf8");
+	const manifest = await extractXStateSourceCoverage(source, { fileName });
+	if (!options.execute) return {
+		schemaVersion: 1,
+		mode: "extract",
+		status: manifest.complete ? "complete" : "incomplete",
+		manifest,
+		exitCode: manifest.complete ? 0 : 2
+	};
+	if (!manifest.complete) throw Object.assign(/* @__PURE__ */ new Error("Source extraction is incomplete."), { diagnostics: manifest.diagnostics });
+	const projectRequire = createRequire(fileName);
+	const load = async (name) => import(pathToFileURL(projectRequire.resolve(name)).href);
+	const graph = await load("@statelyai/graph");
+	const testing = await load("@xstate/test");
+	if (typeof graph.getSourceCoverageWitnesses !== "function" || typeof testing.createSourceCoverageSession !== "function") throw new Error("Source coverage requires @statelyai/graph with source-coverage planning and @xstate/test with createSourceCoverageSession. Upgrade these project dependencies.");
+	const runtimeName = options.runtime ?? "xstate";
+	const runtime = await load(runtimeName);
+	const runtimePackage = projectRequire(`${runtimeName}/package.json`);
+	const runtimeId = `${runtimePackage.name}@${runtimePackage.version}`;
+	if (typeof runtime.getMicrosteps !== "function") throw new Error("The selected runtime does not expose microstep execution.");
+	const instrumented = await instrumentXStateSourceCoverage(source, { fileName });
+	const transpiled = ts.transpileModule(instrumented.source, {
+		fileName,
+		compilerOptions: {
+			target: ts.ScriptTarget.ES2022,
+			module: ts.ModuleKind.ESNext
+		},
+		reportDiagnostics: true
+	});
+	if (transpiled.diagnostics?.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)) throw new Error("The instrumented module could not be compiled.");
+	const sourceUrl = pathToFileURL(fileName).href;
+	const unregister = register({ tsconfig: ts.findConfigFile(dirname(fileName), ts.sys.fileExists) ?? false });
+	const hooks = registerHooks({ load(url, context, nextLoad) {
+		if (url === sourceUrl) return {
+			format: "module",
+			source: transpiled.outputText,
+			shortCircuit: true
+		};
+		return nextLoad(url, context);
+	} });
+	try {
+		const module = await import(sourceUrl);
+		const selected = module[options.exportName ?? "machine"];
+		const control = module[instrumented.controlExport];
+		if (!selected || !control) throw new Error("Expected the selected machine export and source coverage control.");
+		const input = options.inputFile ? JSON.parse(await readFile(options.inputFile, "utf8")) : void 0;
+		const machineIndex = options.machineIndex ?? 0;
+		if (!Number.isSafeInteger(machineIndex) || machineIndex < 0 || machineIndex >= manifest.machineCount) throw new Error("machineIndex is outside the extracted machine range.");
+		const selectedManifest = {
+			...manifest,
+			obligations: manifest.obligations.filter((obligation) => obligation.machineIndex === machineIndex)
+		};
+		const createSession = (input) => {
+			const machine = typeof selected === "function" ? selected(input) : selected;
+			if (!machine.eventSchema || !machine.sources) throw new Error("Source coverage execution currently requires an XState v6 machine.");
+			return testing.createSourceCoverageSession(machine, control, {
+				input,
+				runtimeId,
+				validateEvent: async (event, snapshot) => {
+					const candidate = event;
+					if (typeof candidate.type === "string" && candidate.type.startsWith("xstate.") && typeof runtime.getNextTransitions === "function" && runtime.getNextTransitions(snapshot).some((transition) => transition.eventType === candidate.type && Object.entries(transition.matches ?? {}).every(([key, value]) => Object.is(candidate[key], value)))) return;
+					const validation = await machine.eventSchema["~standard"].validate(event);
+					if (validation.issues) throw new Error(`Event validation failed: ${JSON.stringify(validation.issues)}`);
+				}
+			});
+		};
+		let result;
+		if (options.replayFile) {
+			const saved = JSON.parse(await readFile(options.replayFile, "utf8"));
+			const witnesses = Array.isArray(saved) ? saved : saved.witnesses;
+			if (!Array.isArray(witnesses)) throw new Error("Replay file must contain a witness array or a report with witnesses.");
+			const actual = [];
+			for (const witness of witnesses) actual.push((await graph.getSourceCoverageReplay(manifest, witness, createSession)).witness);
+			result = {
+				report: graph.getSourceCoverageReport(selectedManifest, actual),
+				witnesses: actual,
+				exploration: { replayed: actual.length }
+			};
+		} else {
+			if (!options.casesFile) throw new Error("Execution requires --cases or --replay.");
+			const cases = JSON.parse(await readFile(options.casesFile, "utf8"));
+			if (!Array.isArray(cases) || cases.some((event) => !event || typeof event.type !== "string")) throw new Error("Cases must be an array of event objects with string types.");
+			const suggest = options.suggestFile ? (await import(pathToFileURL(resolve(options.suggestFile)).href)).default : void 0;
+			if (options.suggestFile && typeof suggest !== "function") throw new Error("Suggestion module must default-export a function.");
+			result = await graph.getSourceCoverageWitnesses({
+				manifest,
+				machineIndex,
+				input,
+				createSession,
+				events: cases,
+				maxStates: options.maxStates,
+				maxDepth: options.maxDepth,
+				maxExecutions: options.maxExecutions,
+				suggestEvents: async (args) => {
+					const boundaries = getXStateSourceCoverageEventCases({
+						...selectedManifest,
+						obligations: args.uncovered
+					}, args.state.snapshot, cases);
+					const suggestions = await suggest?.({
+						...args,
+						sourceHash: manifest.source.hash
+					}) ?? [];
+					if (!Array.isArray(suggestions) || suggestions.some((event) => !event || typeof event.type !== "string")) throw new Error("Suggested cases must be event objects.");
+					return [...boundaries, ...suggestions];
+				}
+			});
+			if (options.shrink !== false) {
+				const minimized = [];
+				for (const witness of result.witnesses) minimized.push((await graph.getMinimizedSourceCoverageWitness(manifest, witness, createSession, { maxExecutions: 100 })).witness);
+				result.witnesses = graph.getReducedSourceCoverageWitnesses(selectedManifest, minimized);
+			}
+			const verified = [];
+			for (const witness of result.witnesses) verified.push((await graph.getSourceCoverageReplay(manifest, witness, createSession)).witness);
+			result.witnesses = verified;
+			result.report = graph.getSourceCoverageReport(selectedManifest, verified);
+		}
+		const projection = await createXStateSourceCoverageGraph(source, result.report, {
+			fileName,
+			machineIndex,
+			profile: "xstate-v6-alpha"
+		});
+		const machine = typeof selected === "function" ? selected(input) : selected;
+		const schemas = Object.entries(machine.schemas?.events ?? {});
+		const typeOnlyEvents = schemas.filter(([, schema]) => schema?.["~standard"]?.vendor === "xstate.types").map(([type]) => type);
+		const runtimeSchemaEvents = schemas.filter(([, schema]) => schema?.["~standard"]?.vendor && schema["~standard"].vendor !== "xstate.types").map(([type]) => type);
+		const unconstrainedEvents = [...new Set(result.witnesses.flatMap((witness) => witness.events.map((event) => event.type)))].filter((type) => !schemas.some(([key]) => key === type));
+		return {
+			schemaVersion: 1,
+			mode: options.replayFile ? "replay" : "execute",
+			status: result.report.complete ? "complete" : "incomplete",
+			machineIndex,
+			runtimeId,
+			effectsExecuted: false,
+			payloadValidation: {
+				typeOnlyEvents,
+				runtimeSchemaEvents,
+				unconstrainedEvents,
+				modeledRuntimeEvents: result.witnesses.flatMap((witness) => witness.events.filter((event) => event.type.startsWith("xstate.")))
+			},
+			manifest: selectedManifest,
+			...result,
+			graph: projection.graph,
+			exitCode: result.report.complete ? 0 : 1
+		};
+	} finally {
+		hooks.deregister();
+		await unregister();
+	}
+}
+
+//#endregion
+//#region src/coverageWorker.ts
+if (parentPort) runSourceCoverageFile(workerData).then((result) => parentPort.postMessage({
+	ok: true,
+	result
+}), (error) => parentPort.postMessage({
+	ok: false,
+	error: {
+		message: error instanceof Error ? error.message : String(error),
+		diagnostics: error?.diagnostics
+	}
+}));
+
+//#endregion
+export {  };

package/dist/index.d.mts

@@ -69,10 +69,10 @@ declare const behaviorCiResultsSchema: z.ZodArray<z.ZodObject<{
   file: z.ZodString;
   fullName: z.ZodString;
   outcome: z.ZodEnum<{
-    error: "error";
     passed: "passed";
     failed: "failed";
     skipped: "skipped";
+    error: "error";
   }>;
   detail: z.ZodString;
 }, z.core.$strict>>;
@@ -129,6 +129,53 @@ declare class BehaviorCalibrateCommand extends Command {
   run(): Promise<void>;
 }
 //#endregion
+//#region src/sourceCoverageRunner.d.ts
+interface SourceCoverageRunOptions {
+  sourceFile: string;
+  execute?: boolean;
+  casesFile?: string;
+  inputFile?: string;
+  replayFile?: string;
+  runtime?: string;
+  exportName?: string;
+  machineIndex?: number;
+  maxStates?: number;
+  maxDepth?: number;
+  maxExecutions?: number;
+  shrink?: boolean;
+  /** Trusted callback module supplying additional event cases from coverage gaps. */
+  suggestFile?: string;
+}
+//#endregion
+//#region src/sourceCoverageCommand.d.ts
+declare function runSourceCoverageWorker(options: SourceCoverageRunOptions, timeoutMs?: number, workerUrl?: URL): Promise<any>;
+declare class SourceCoverageCommand extends Command {
+  static enableJsonFlag: boolean;
+  static summary: string;
+  static description: string;
+  static args: {
+    source: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+  };
+  static flags: {
+    execute: _oclif_core_interfaces0.BooleanFlag<boolean>;
+    cases: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    input: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    replay: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    runtime: _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
+    export: _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
+    "machine-index": _oclif_core_interfaces0.OptionFlag<number, _oclif_core_interfaces0.CustomOptions>;
+    "max-states": _oclif_core_interfaces0.OptionFlag<number, _oclif_core_interfaces0.CustomOptions>;
+    "max-depth": _oclif_core_interfaces0.OptionFlag<number, _oclif_core_interfaces0.CustomOptions>;
+    "max-executions": _oclif_core_interfaces0.OptionFlag<number, _oclif_core_interfaces0.CustomOptions>;
+    timeout: _oclif_core_interfaces0.OptionFlag<number, _oclif_core_interfaces0.CustomOptions>;
+    shrink: _oclif_core_interfaces0.BooleanFlag<boolean>;
+    suggest: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    report: _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
+    graph: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+  };
+  run(): Promise<void>;
+}
+//#endregion
 //#region src/testCommand.d.ts
 declare class TestCommand extends Command {
   static enableJsonFlag: boolean;
@@ -885,6 +932,7 @@ declare const COMMANDS: {
   'behavior:check': typeof BehaviorCheckCommand;
   'behavior:adopt': typeof BehaviorAdoptCommand;
   test: typeof TestCommand;
+  coverage: typeof SourceCoverageCommand;
   verify: typeof VerifyCommand;
   plan: typeof PlanCommand;
   diff: typeof DiffCommand;
@@ -1822,4 +1870,4 @@ declare function verifyProject(options?: VerifyProjectOptions): Promise<{
 /** One case per recorded path/probe. Unattributed divergences remain separate cases. */
 declare function formatVerificationJUnit(report: VerificationRunReport): string;
 //#endregion
-export { ApiKeyResolution, type BehaviorCiAdapter, type BehaviorCiConfig, type BehaviorCiResult, COMMANDS, CredentialStatus, DiscoveredMachine, InitProjectOptions, InitProjectResult, type LinkProjectOptions, LinkedPullTarget, OAuthLoginDiscovery, ProjectMachineStatus, ProjectStatusMachine, ProjectStatusResult, PushCandidateClassification, RemoteProjectMachineTarget, ResolveApiKeyOptions, ResolvedConfiguredPullTargets, ScanProjectSourcesOptions, type VerificationExecutor, type VerificationRequest, type VerificationRunReport, type VerifyProjectOptions, adoptBehavior, behaviorCiConfigSchema, behaviorCiResultsSchema, briefReport, buildOAuthLoginStart, calibrateBehavior, changesReport, checkBehavior, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverMachinesInSource, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatDiscoveredMachines, formatMissingNewMachineDirMessage, formatPlanSummary, formatProjectStatus, formatStoredCredentialSource, formatVerificationJUnit, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, linkProject, pendingReport, readGraphFile, resolveApiKey, resolveConfiguredPullTargets, resolveCredentialStatus, resolveOpenRootDir, resolveProjectStatus, resolveVerificationRequest, resourceId, run, scanProjectMachines, scanProjectSources, verifyProject, verifyReport };
+export { ApiKeyResolution, type BehaviorCiAdapter, type BehaviorCiConfig, type BehaviorCiResult, COMMANDS, CredentialStatus, DiscoveredMachine, InitProjectOptions, InitProjectResult, type LinkProjectOptions, LinkedPullTarget, OAuthLoginDiscovery, ProjectMachineStatus, ProjectStatusMachine, ProjectStatusResult, PushCandidateClassification, RemoteProjectMachineTarget, ResolveApiKeyOptions, ResolvedConfiguredPullTargets, ScanProjectSourcesOptions, SourceCoverageCommand, type SourceCoverageRunOptions, type VerificationExecutor, type VerificationRequest, type VerificationRunReport, type VerifyProjectOptions, adoptBehavior, behaviorCiConfigSchema, behaviorCiResultsSchema, briefReport, buildOAuthLoginStart, calibrateBehavior, changesReport, checkBehavior, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverMachinesInSource, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatDiscoveredMachines, formatMissingNewMachineDirMessage, formatPlanSummary, formatProjectStatus, formatStoredCredentialSource, formatVerificationJUnit, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, linkProject, pendingReport, readGraphFile, resolveApiKey, resolveConfiguredPullTargets, resolveCredentialStatus, resolveOpenRootDir, resolveProjectStatus, resolveVerificationRequest, resourceId, run, runSourceCoverageWorker, scanProjectMachines, scanProjectSources, verifyProject, verifyReport };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { A as formatVerificationJUnit, B as calibrateBehavior, C as run, D as resourceId, E as linkProject, F as readGraphFile, I as verifyReport, L as adoptBehavior, M as briefReport, N as changesReport, O as resolveVerificationRequest, P as pendingReport, R as behaviorCiConfigSchema, S as resolveProjectStatus, T as scanProjectSources, V as checkBehavior, _ as isFileGitDirty, a as discoverMachinesInSource, b as resolveCredentialStatus, c as formatDiscoveredMachines, d as formatProjectStatus, f as formatStoredCredentialSource, g as initProject, h as inferInitProjectName, i as discoverLinkedPullTargets, j as createStatelyProjectConfig, k as verifyProject, l as formatMissingNewMachineDirMessage, m as getEnvCredential, n as buildOAuthLoginStart, o as discoverOAuthLogin, p as getEnvApiKey, r as classifyPushCandidates, s as discoverRemoteProjectMachineTargets, t as COMMANDS, u as formatPlanSummary, v as resolveApiKey, w as scanProjectMachines, x as resolveOpenRootDir, y as resolveConfiguredPullTargets, z as behaviorCiResultsSchema } from "./cli-CqVcBAPG.mjs";
+import { A as formatVerificationJUnit, B as behaviorCiConfigSchema, C as run, D as resourceId, E as linkProject, F as readGraphFile, H as calibrateBehavior, I as verifyReport, L as SourceCoverageCommand, M as briefReport, N as changesReport, O as resolveVerificationRequest, P as pendingReport, R as runSourceCoverageWorker, S as resolveProjectStatus, T as scanProjectSources, U as checkBehavior, V as behaviorCiResultsSchema, _ as isFileGitDirty, a as discoverMachinesInSource, b as resolveCredentialStatus, c as formatDiscoveredMachines, d as formatProjectStatus, f as formatStoredCredentialSource, g as initProject, h as inferInitProjectName, i as discoverLinkedPullTargets, j as createStatelyProjectConfig, k as verifyProject, l as formatMissingNewMachineDirMessage, m as getEnvCredential, n as buildOAuthLoginStart, o as discoverOAuthLogin, p as getEnvApiKey, r as classifyPushCandidates, s as discoverRemoteProjectMachineTargets, t as COMMANDS, u as formatPlanSummary, v as resolveApiKey, w as scanProjectMachines, x as resolveOpenRootDir, y as resolveConfiguredPullTargets, z as adoptBehavior } from "./cli-BBG--n3O.mjs";
 
-export { COMMANDS, adoptBehavior, behaviorCiConfigSchema, behaviorCiResultsSchema, briefReport, buildOAuthLoginStart, calibrateBehavior, changesReport, checkBehavior, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverMachinesInSource, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatDiscoveredMachines, formatMissingNewMachineDirMessage, formatPlanSummary, formatProjectStatus, formatStoredCredentialSource, formatVerificationJUnit, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, linkProject, pendingReport, readGraphFile, resolveApiKey, resolveConfiguredPullTargets, resolveCredentialStatus, resolveOpenRootDir, resolveProjectStatus, resolveVerificationRequest, resourceId, run, scanProjectMachines, scanProjectSources, verifyProject, verifyReport };
+export { COMMANDS, SourceCoverageCommand, adoptBehavior, behaviorCiConfigSchema, behaviorCiResultsSchema, briefReport, buildOAuthLoginStart, calibrateBehavior, changesReport, checkBehavior, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverMachinesInSource, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatDiscoveredMachines, formatMissingNewMachineDirMessage, formatPlanSummary, formatProjectStatus, formatStoredCredentialSource, formatVerificationJUnit, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, linkProject, pendingReport, readGraphFile, resolveApiKey, resolveConfiguredPullTargets, resolveCredentialStatus, resolveOpenRootDir, resolveProjectStatus, resolveVerificationRequest, resourceId, run, runSourceCoverageWorker, scanProjectMachines, scanProjectSources, verifyProject, verifyReport };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "statelyai",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Command-line tools for Stately",
   "license": "MIT",
   "bin": {
@@ -26,18 +26,19 @@
   },
   "dependencies": {
     "@oclif/core": "^4.10.3",
+    "tsx": "^4.23.13",
     "typescript": "^5.9.3",
     "ws": "^8.21.0",
     "zod": "^4.4.1",
     "@statelyai/mcp": "0.21.0",
-    "@statelyai/sdk": "0.40.0"
+    "@statelyai/sdk": "0.41.0"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",
     "tsdown": "0.21.0-beta.2",
     "vitest": "^3.2.4",
-    "@statelyai/editor-sync": "0.2.7",
-    "@statelyai/api-contract": "0.10.0"
+    "@statelyai/api-contract": "0.10.1",
+    "@statelyai/editor-sync": "0.2.8"
   },
   "oclif": {
     "bin": "statelyai",