@xstate/codemod 0.1.0-beta.0 → 0.1.0-beta.1

package/README.md

@@ -5,5 +5,7 @@ Run `xstate-codemod migrate [globs...] --dry` to review a v5-to-v6 migration. Om
 
 The transforms rename imports, wrap string targets, convert inline `types` declarations to schemas, report APIs requiring manual migration, and report `#id.path` targets that v6 no longer resolves. `--transform name,name` selects transforms.
 
+`--json` prints a single JSON report to stdout, including a `manualSites` list with the file, line, column, API and hint for each manual migration step. The command exits with `0` when no manual migration is needed, `1` on a usage error or invalid migration output, and `2` when manual migration is needed.
+
 <!-- helper binding and output validation from src/util.ts, src/transforms/types-to-schemas.ts and src/runner.ts -->
 The codemod supports named, namespace and type-only imports. It checks transformed syntax before saving. Run your application's typecheck and tests after migration, and review any reported manual migration steps.

package/bin/alias-hook.mjs

@@ -0,0 +1,38 @@
+// Maps `xstate` and `xstate/*` to the major selected by XSTATE_VERIFY_MAJOR:
+// `xstate5` (npm:xstate@5, bundled with this package) or this package's own
+// `xstate` (6). Under 6, `xstate-v6` (the side-by-side install name from the
+// migration guide) maps to the same package. Synchronous hooks cover both
+// `import` and `require` (tsx transpiles CommonJS user files). Every specifier
+// resolves from this file, so the user's module and the verify runner share
+// one xstate instance.
+import { registerHooks } from 'node:module';
+
+const major = process.env.XSTATE_VERIFY_MAJOR;
+if (major !== '5' && major !== '6') {
+  throw new Error(`XSTATE_VERIFY_MAJOR must be 5 or 6, got ${major}`);
+}
+const target = major === '5' ? 'xstate5' : 'xstate';
+const aliases = major === '5' ? ['xstate'] : ['xstate', 'xstate-v6'];
+let resolvingTarget = false;
+
+function aliasFor(specifier) {
+  return aliases.find(
+    (alias) => specifier === alias || specifier.startsWith(`${alias}/`)
+  );
+}
+
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    const alias = resolvingTarget ? undefined : aliasFor(specifier);
+    if (alias) {
+      resolvingTarget = true;
+      try {
+        const url = import.meta.resolve(target + specifier.slice(alias.length));
+        return { url, shortCircuit: true };
+      } finally {
+        resolvingTarget = false;
+      }
+    }
+    return nextResolve(specifier, context);
+  }
+});

package/bin/codemod.js

@@ -1,4 +1,12 @@
 #!/usr/bin/env node
-import { main } from '../dist/xstate-codemod.js';
+import { main, verifyCli } from '../dist/xstate-codemod.js';
 
-process.exit(main(process.argv.slice(2)));
+const argv = process.argv.slice(2);
+const [command] = argv;
+
+// Set the exit code instead of calling process.exit() so a large JSON report
+// written to a pipe is flushed before the process ends.
+process.exitCode =
+  command === 'baseline' || command === 'verify'
+    ? await verifyCli(argv)
+    : main(argv);

package/bin/verify-child.mjs

@@ -0,0 +1,3 @@
+import { childMain } from '../dist/xstate-codemod.js';
+
+await childMain();

package/dist/declarations/src/cli.d.ts

@@ -1,7 +1,8 @@
-export interface ParsedArgs {
+interface ParsedArgs {
     command: string | undefined;
     globs: string[];
     dry: boolean;
+    json: boolean;
     transformNames: string[] | undefined;
     help: boolean;
 }
@@ -14,3 +15,4 @@ export declare function parseArgs(argv: string[]): ParsedArgs;
 export declare function resolveFiles(globs: string[]): string[];
 /** CLI entry point. Returns a process exit code. */
 export declare function main(argv: string[]): number;
+export {};

package/dist/declarations/src/index.d.ts

@@ -1,4 +1,5 @@
 export type { Transform, TransformResult } from "./types.js";
-export { transforms, transformsByName, renameImports, stringTargets, typesToSchemas, reportRemovedApis, reportIdPathTargets } from "./transforms/index.js";
+export { transforms, transformsByName, renameImports, stringTargets, typesToSchemas, lowerActions, reportRemovedApis, reportIdPathTargets } from "./transforms/index.js";
 export { run, applyToSourceFile, selectTransforms, type RunReport, type FileTransformReport } from "./runner.js";
 export { main, parseArgs, resolveFiles } from "./cli.js";
+export { verifyCli, childMain, runBaseline, runVerify, VerifyError, type BaselineOptions, type VerifyOptions, type Baseline, type VerifyReport } from "./verify/index.js";

package/dist/declarations/src/runner.d.ts

@@ -1,11 +1,12 @@
 import { SourceFile } from 'ts-morph';
-import type { Transform } from "./types.js";
+import type { ManualSite, Transform } from "./types.js";
 export interface FileTransformReport {
     filePath: string;
     perTransform: Array<{
         transform: string;
         changed: boolean;
         notes: string[];
+        sites: ManualSite[];
     }>;
     changed: boolean;
     newText?: string;
@@ -15,6 +16,10 @@ export interface RunReport {
     filesChanged: number;
     /** Notes emitted by the report-only transforms (manual-migration section). */
     manualMigrationNotes: string[];
+    /** Structured locations that need manual migration, from every transform. */
+    manualSites: Array<ManualSite & {
+        transform: string;
+    }>;
 }
 /** Resolve a list of transform names to Transform objects. */
 export declare function selectTransforms(names?: string[]): Transform[];

package/dist/declarations/src/transforms/index.d.ts

@@ -2,9 +2,10 @@ import type { Transform } from "../types.js";
 import { renameImports } from "./rename-imports.js";
 import { stringTargets } from "./string-targets.js";
 import { typesToSchemas } from "./types-to-schemas.js";
+import { lowerActions } from "./lower-actions.js";
 import { reportRemovedApis } from "./report-removed-apis.js";
 import { reportIdPathTargets } from "./report-id-path-targets.js";
 /** All transforms, in recommended application order. */
 export declare const transforms: Transform[];
 export declare const transformsByName: Record<string, Transform>;
-export { renameImports, stringTargets, typesToSchemas, reportRemovedApis, reportIdPathTargets };
+export { renameImports, stringTargets, typesToSchemas, lowerActions, reportRemovedApis, reportIdPathTargets };

package/dist/declarations/src/transforms/lower-actions.d.ts

@@ -0,0 +1,7 @@
+import type { Transform } from "../types.js";
+/**
+ * Lowers v5 action creators, guards and transition objects to v6 transition
+ * and entry/exit functions. Anything it cannot lower is left untouched for the
+ * report transforms.
+ */
+export declare const lowerActions: Transform;

package/dist/declarations/src/transforms/types-to-schemas.d.ts

@@ -1,6 +1,7 @@
 import type { Transform } from "../types.js";
 /**
- * Converts `types: {} as { context; events; input; ... }` inside machine config
- * objects into `schemas: { context: types<...>(), ... }`.
+ * Converts `types: {} as { context; events; input; ... }` (or the per-key
+ * `types: { context: {} as C, ... }` form) inside machine config objects into
+ * `schemas: { context: types<...>(), ... }`.
  */
 export declare const typesToSchemas: Transform;

package/dist/declarations/src/types.d.ts

@@ -1,7 +1,16 @@
 import type { SourceFile } from 'ts-morph';
+/** A source location that needs manual migration. */
+export interface ManualSite {
+    file: string;
+    line: number;
+    column: number;
+    api: string;
+    hint: string;
+}
 export interface TransformResult {
     changed: boolean;
     notes: string[];
+    sites?: ManualSite[];
 }
 export interface Transform {
     name: string;

package/dist/declarations/src/verify/child.d.ts

@@ -0,0 +1,3 @@
+/** Marks the start of the JSON result on stdout; user code may print before it. */
+export declare const RESULT_MARKER = "\n@@xstate-verify-result@@\n";
+export declare function childMain(): Promise<void>;

package/dist/declarations/src/verify/cli.d.ts

@@ -0,0 +1,2 @@
+/** `baseline` and `verify` commands; `argv[0]` is the command name. */
+export declare function verifyCli(argv: string[]): Promise<number>;

package/dist/declarations/src/verify/index.d.ts

@@ -0,0 +1,4 @@
+export { verifyCli } from "./cli.js";
+export { childMain } from "./child.js";
+export { runBaseline, runVerify, startError, VerifyError, type BaselineOptions, type VerifyOptions } from "./run.js";
+export type * from "./types.js";

package/dist/declarations/src/verify/run.d.ts

@@ -0,0 +1,37 @@
+import type { Baseline, EventCases, GenerateOptions, Stubs, VerifyReport } from "./types.js";
+export declare class VerifyError extends Error {
+    phase: 'baseline' | 'replay';
+    code: string;
+    stderr: string;
+    childStack: string | undefined;
+    constructor(phase: 'baseline' | 'replay', code: string, message: string, stderr: string, childStack?: string);
+}
+export interface BaselineOptions extends Partial<GenerateOptions> {
+    file: string;
+    export?: string;
+    events?: EventCases;
+    stubs?: Stubs;
+    input?: unknown;
+    timeout?: number;
+}
+/** The error of the first trace's start step, when the machine errored there. */
+export declare function startError(baseline: Baseline): string | undefined;
+/** Records a golden trace of a v5 module. Throws {@link VerifyError}. */
+export declare function runBaseline(options: BaselineOptions): Promise<Baseline>;
+export interface VerifyOptions extends Partial<GenerateOptions> {
+    /** The v6 module to replay. */
+    file: string;
+    /** A v5 module to baseline first; ignored when `baseline` is given. */
+    v5?: string;
+    baseline?: Baseline;
+    export?: string;
+    /** Override the baseline's recorded cases/stubs/input. */
+    events?: EventCases;
+    stubs?: Stubs;
+    input?: unknown;
+    /** Trace fields to compare; defaults to all but `actions`. */
+    compare?: string[];
+    timeout?: number;
+}
+/** Replays the baseline's sequences on a v6 module and diffs the traces. */
+export declare function runVerify(options: VerifyOptions): Promise<VerifyReport>;

package/dist/declarations/src/verify/types.d.ts

@@ -0,0 +1,177 @@
+export type EventObject = {
+    type: string;
+    [key: string]: unknown;
+};
+export type NormalizedEvent = EventObject;
+export type SequenceStep = {
+    event: EventObject;
+} | {
+    advance: number;
+};
+export type Origin = 'shortest' | 'simple' | 'random';
+export interface Sequence {
+    id: string;
+    origin: Origin;
+    steps: SequenceStep[];
+}
+export interface TraceStep {
+    input: SequenceStep | {
+        start: true;
+    };
+    value: unknown;
+    context: unknown;
+    status: 'active' | 'done' | 'error' | 'stopped';
+    output?: unknown;
+    error?: string;
+    processed: NormalizedEvent[];
+    children: Array<{
+        id: string;
+        src: string;
+    }>;
+    sent: Array<{
+        to: string;
+        event: NormalizedEvent;
+        delay?: number;
+    }>;
+    emitted: NormalizedEvent[];
+    actions: Array<{
+        type: string;
+        params: unknown;
+    }>;
+}
+export interface Trace {
+    sequenceId: string;
+    steps: TraceStep[];
+}
+export type StubSpec = 'pending' | {
+    done: unknown;
+} | {
+    error: string;
+};
+export interface Stubs {
+    actors?: Record<string, StubSpec>;
+    delays?: Record<string, number>;
+}
+/** `{ TYPE: [payload, …] }`; each payload is merged into `{ type: TYPE }`. */
+export type EventCases = Record<string, Array<Record<string, unknown>>>;
+export interface GenerateOptions {
+    seed: number;
+    walks: number;
+    steps: number;
+    maxSequences: number;
+    /** `false` skips the v5 graph's simple paths (`--no-simple-paths`). */
+    simplePaths?: boolean;
+}
+export interface Baseline {
+    version: 1;
+    file: string;
+    export: string;
+    xstateVersion: string;
+    options: GenerateOptions;
+    events: EventCases;
+    stubs: Stubs;
+    /** Passed as `createActor(logic, { input })`. */
+    input?: unknown;
+    sequences: Sequence[];
+    traces: Trace[];
+    unstubbed: string[];
+    eventsWithoutCases: string[];
+    /** Graph origins or events dropped because a guard threw while generating. */
+    generationErrors: string[];
+    nonSerializable: number;
+    /** Loader notes, such as which of several machine exports was used. */
+    notes?: string[];
+}
+export interface ChildJob {
+    mode: 'baseline' | 'replay';
+    file: string;
+    export?: string;
+    events: EventCases;
+    stubs: Stubs;
+    input?: unknown;
+    options: GenerateOptions;
+    /** Replay only. */
+    sequences?: Sequence[];
+}
+export type ChildResult = {
+    ok: true;
+    export: string;
+    xstateVersion: string;
+    sequences: Sequence[];
+    traces: Trace[];
+    unstubbed: string[];
+    eventsWithoutCases: string[];
+    generationErrors?: string[];
+    nonSerializable: number;
+    notes?: string[];
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    stack?: string;
+};
+export type Classification = 'unclassified' | {
+    rule: string;
+    section: string;
+    note: string;
+};
+export interface Diff {
+    sequenceId: string;
+    origin: Origin;
+    step: number;
+    witness: SequenceStep[];
+    field: string;
+    expected: unknown;
+    actual: unknown;
+    /** Error message(s) behind a `status` diff where either side errored. */
+    detail?: string;
+    classification: Classification;
+}
+export interface VerifyReport {
+    status: 'equivalent' | 'diverged' | 'error';
+    v5: {
+        file: string;
+        export: string;
+        xstateVersion: string;
+    };
+    v6: {
+        file: string;
+        export: string;
+        xstateVersion: string;
+    };
+    sequences: number;
+    stepsCompared: number;
+    diffs: Diff[];
+    intentional: number;
+    unstubbed: string[];
+    eventsWithoutCases: string[];
+    generationErrors: string[];
+    nonSerializable: number;
+    /** The baseline's error at start, if the v5 machine errored there. */
+    startError?: string;
+    notes: string[];
+    error?: {
+        phase: 'baseline' | 'replay';
+        code: string;
+        message: string;
+        stack?: string;
+        stderr: string;
+    };
+}
+/** Per-step buckets a recorder fills from inspection events. */
+export interface StepRecord {
+    processed: NormalizedEvent[];
+    sent: TraceStep['sent'];
+    emitted: NormalizedEvent[];
+    actions: TraceStep['actions'];
+}
+export interface Recorder {
+    setRoot(root: unknown): void;
+    inspect(event: any): void;
+    emit(event: any): void;
+    srcOf(ref: unknown): string;
+    take(): StepRecord;
+}
+export interface Stats {
+    nonSerializable: number;
+}