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

package/README.md

@@ -0,0 +1,9 @@
+# @xstate/codemod
+
+<!-- CLI commands and transforms from src/cli.ts and src/transforms/index.ts -->
+Run `xstate-codemod migrate [globs...] --dry` to review a v5-to-v6 migration. Omit `--dry` to save changes. The default scan includes TypeScript and JavaScript files, excluding `node_modules` and `dist`.
+
+The transforms rename imports, wrap string targets, convert inline `types` declarations to schemas, and report APIs requiring manual migration. `--transform name,name` selects transforms.
+
+<!-- helper binding and output validation from src/util.ts, src/transforms/types-to-schemas.ts and src/runner.ts -->
+Schema helpers use value imports, preserve usable aliases, and avoid conflicting local names. Namespace and type-only imports are supported. Event payload separators and escaped event names retain their meaning. The runner checks transformed syntax before saving; generated code still needs your application's typecheck and tests, and reported manual migrations still need review.

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

@@ -0,0 +1,16 @@
+export interface ParsedArgs {
+    command: string | undefined;
+    globs: string[];
+    dry: boolean;
+    transformNames: string[] | undefined;
+    help: boolean;
+}
+/** Hand-written arg parser (no yargs). */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/**
+ * Resolves glob patterns into a de-duplicated list of file paths using
+ * ts-morph's built-in glob support (no extra glob dependency).
+ */
+export declare function resolveFiles(globs: string[]): string[];
+/** CLI entry point. Returns a process exit code. */
+export declare function main(argv: string[]): number;

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

@@ -0,0 +1,4 @@
+export type { Transform, TransformResult } from "./types.js";
+export { transforms, transformsByName, renameImports, stringTargets, typesToSchemas, reportRemovedApis } from "./transforms/index.js";
+export { run, applyToSourceFile, selectTransforms, type RunReport, type FileTransformReport } from "./runner.js";
+export { main, parseArgs, resolveFiles } from "./cli.js";

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

@@ -0,0 +1,32 @@
+import { SourceFile } from 'ts-morph';
+import type { Transform } from "./types.js";
+export interface FileTransformReport {
+    filePath: string;
+    perTransform: Array<{
+        transform: string;
+        changed: boolean;
+        notes: string[];
+    }>;
+    changed: boolean;
+    newText?: string;
+}
+export interface RunReport {
+    files: FileTransformReport[];
+    filesChanged: number;
+    /** Notes emitted by `report-removed-apis` (manual-migration section). */
+    manualMigrationNotes: string[];
+}
+/** Resolve a list of transform names to Transform objects. */
+export declare function selectTransforms(names?: string[]): Transform[];
+/** Applies the given transforms to a single source file (in-memory). */
+export declare function applyToSourceFile(sourceFile: SourceFile, transforms: Transform[]): FileTransformReport;
+/**
+ * Runs the selected transforms over the given files.
+ *
+ * @param filePaths absolute or cwd-relative file paths to process
+ * @param transforms the transforms to apply
+ * @param options.write when true, saves modified files to disk
+ */
+export declare function run(filePaths: string[], transforms: Transform[], options?: {
+    write: boolean;
+}): RunReport;

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

@@ -0,0 +1,9 @@
+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 { reportRemovedApis } from "./report-removed-apis.js";
+/** All transforms, in recommended application order. */
+export declare const transforms: Transform[];
+export declare const transformsByName: Record<string, Transform>;
+export { renameImports, stringTargets, typesToSchemas, reportRemovedApis };

package/dist/declarations/src/transforms/rename-imports.d.ts

@@ -0,0 +1,7 @@
+import type { Transform } from "../types.js";
+/**
+ * Renames imports (and their usages) from `'xstate'` to their v6 equivalents.
+ * Preserves aliases: `import { interpret as x }` keeps `x` but renames the
+ * imported binding to `createActor`.
+ */
+export declare const renameImports: Transform;

package/dist/declarations/src/transforms/report-removed-apis.d.ts

@@ -0,0 +1,7 @@
+import type { Transform } from "../types.js";
+/**
+ * Detects (does NOT transform) usages of v5 `'xstate'` APIs that were removed
+ * or restructured in v6. Reports file:line + API + a replacement hint via the
+ * returned notes.
+ */
+export declare const reportRemovedApis: Transform;

package/dist/declarations/src/transforms/string-targets.d.ts

@@ -0,0 +1,9 @@
+import type { Transform } from "../types.js";
+/**
+ * Converts bare string transition values inside `createMachine`/`setup().
+ * createMachine`/`createStateConfig` config objects into `{ target: '...' }`.
+ *
+ * Does NOT touch `initial:` (still a string in v6) or existing `target:`
+ * values.
+ */
+export declare const stringTargets: Transform;

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

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

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

@@ -0,0 +1,10 @@
+import type { SourceFile } from 'ts-morph';
+export interface TransformResult {
+    changed: boolean;
+    notes: string[];
+}
+export interface Transform {
+    name: string;
+    description: string;
+    apply(sourceFile: SourceFile): TransformResult;
+}

package/dist/xstate-codemod.d.ts

@@ -1,2 +1,2 @@
-export * from "../src/index.js";
-//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoieHN0YXRlLWNvZGVtb2QuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoieHN0YXRlLWNvZGVtb2QuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4vZGVjbGFyYXRpb25zL3NyYy9pbmRleC5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBIn0=

package/dist/xstate-codemod.js

@@ -0,0 +1,712 @@
+import { Node, SyntaxKind, SymbolFlags, ts, Project } from 'ts-morph';
+import process from 'node:process';
+
+/** Map of v5 xstate exports → v6 replacement names. */
+const RENAMES = {
+  interpret: 'createActor',
+  Interpreter: 'Actor',
+  fromCallback: 'createCallbackLogic',
+  fromObservable: 'createObservableLogic',
+  fromEventObservable: 'createEventObservableLogic'
+};
+
+/**
+ * Renames imports (and their usages) from `'xstate'` to their v6 equivalents.
+ * Preserves aliases: `import { interpret as x }` keeps `x` but renames the
+ * imported binding to `createActor`.
+ */
+const renameImports = {
+  name: 'rename-imports',
+  description: "Rename renamed 'xstate' imports (interpret→createActor, Interpreter→Actor, fromCallback/fromObservable/fromEventObservable→create*Logic) and their usages.",
+  apply(sourceFile) {
+    const notes = [];
+    let changed = false;
+    const xstateImports = sourceFile.getImportDeclarations().filter(imp => imp.getModuleSpecifierValue() === 'xstate');
+    for (const imp of xstateImports) {
+      for (const spec of imp.getNamedImports()) {
+        const importedName = spec.getNameNode().getText();
+        const replacement = RENAMES[importedName];
+        if (!replacement) {
+          continue;
+        }
+        const aliasNode = spec.getAliasNode();
+        if (aliasNode) {
+          // Aliased: rename only the imported binding, keep the alias.
+          // `interpret as x` → `createActor as x`
+          spec.getNameNode().replaceWithText(replacement);
+          notes.push(`renamed import '${importedName}' → '${replacement}' (alias '${aliasNode.getText()}' preserved)`);
+        } else {
+          // Not aliased: rename the binding and every reference to it.
+          const nameNode = spec.getNameNode();
+          const refs = Node.isIdentifier(nameNode) ? nameNode.findReferencesAsNodes().filter(n => n !== nameNode) : [];
+          for (const ref of refs) {
+            if (ref.getKind() === SyntaxKind.Identifier) {
+              ref.replaceWithText(replacement);
+            }
+          }
+          nameNode.replaceWithText(replacement);
+          notes.push(`renamed '${importedName}' → '${replacement}'${refs.length ? ` and ${refs.length} usage(s)` : ''}`);
+        }
+        changed = true;
+      }
+    }
+    return {
+      changed,
+      notes
+    };
+  }
+};
+
+/**
+ * Returns the simple identifier name of the function being called, if any.
+ * Handles both `createMachine(...)` and `setup(...).createMachine(...)` by
+ * returning the trailing property/identifier name (e.g. `createMachine`).
+ */
+function getCallName(call) {
+  const expr = call.getExpression();
+  if (Node.isIdentifier(expr)) {
+    return expr.getText();
+  }
+  if (Node.isPropertyAccessExpression(expr)) {
+    return expr.getNameNode().getText();
+  }
+  return undefined;
+}
+
+/**
+ * Finds the config object literals passed as the first argument to
+ * `createMachine(...)` or `createStateConfig(...)` (including the
+ * `setup(...).createMachine(...)` form).
+ *
+ * This is a best-effort match by call-expression name, not by resolving the
+ * actual import — that is sufficient for a migration codemod and avoids fragile
+ * type resolution.
+ */
+function findMachineConfigObjects(sourceFile, callNames = ['createMachine', 'createStateConfig']) {
+  const result = [];
+  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const name = getCallName(call);
+    if (!name || !callNames.includes(name)) {
+      continue;
+    }
+    const firstArg = call.getArguments()[0];
+    if (firstArg && Node.isObjectLiteralExpression(firstArg)) {
+      result.push(firstArg);
+    }
+  }
+  return result;
+}
+
+/** Finds or adds a runtime helper import and returns its binding at the use site. */
+function ensureNamedImport(sourceFile, name, location = sourceFile) {
+  const imports = sourceFile.getImportDeclarations().filter(imp => imp.getModuleSpecifierValue() === 'xstate');
+  if (!imports.length) return undefined;
+  const visible = location.getSymbolsInScope(SymbolFlags.Value);
+  for (const imp of imports) {
+    if (imp.isTypeOnly()) continue;
+    for (const spec of imp.getNamedImports()) {
+      if (spec.isTypeOnly() || spec.getName() !== name) continue;
+      const local = (spec.getAliasNode() ?? spec.getNameNode()).getText();
+      if (visible.find(symbol => symbol.getName() === local)?.getDeclarations().includes(spec)) {
+        return local;
+      }
+    }
+  }
+
+  // Reserve every identifier, including nested bindings, so the new import is
+  // usable throughout the file without shadowing an existing local value.
+  const identifiers = new Set(sourceFile.getDescendantsOfKind(SyntaxKind.Identifier).filter(node => {
+    const parent = node.getParent();
+    return !((Node.isPropertyAssignment(parent) || Node.isPropertySignature(parent)) && parent.getNameNode() === node);
+  }).map(node => node.getText()));
+  let local = name;
+  let suffix = 1;
+  while (identifiers.has(local)) local = `${name}${suffix++}`;
+  const specifier = {
+    name,
+    ...(local === name ? {} : {
+      alias: local
+    })
+  };
+  const target = imports.find(imp => !imp.isTypeOnly() && !imp.getNamespaceImport());
+  if (target) target.addNamedImport(specifier);else sourceFile.addImportDeclaration({
+    moduleSpecifier: 'xstate',
+    namedImports: [specifier]
+  });
+  return local;
+}
+
+/**
+ * Property keys whose value is a transition (or map/array of transitions) that,
+ * in v6, must be an object `{ target: '...' }` rather than a bare string.
+ */
+const EVENT_LIKE_KEYS = new Set(['on', 'after']);
+const DIRECT_TRANSITION_KEYS = new Set(['onDone', 'onError', 'always']);
+
+/**
+ * Wraps a bare string transition value into `{ target: '<str>' }`.
+ * Returns true if a change was made.
+ */
+function wrapValue(node) {
+  if (Node.isStringLiteral(node)) {
+    const raw = node.getText(); // includes quotes
+    node.replaceWithText(`{ target: ${raw} }`);
+    return true;
+  }
+  if (Node.isArrayLiteralExpression(node)) {
+    let changed = false;
+    // Iterate over a snapshot; replacing elements is index-stable here since
+    // we replace text in place without adding/removing elements.
+    for (const el of node.getElements()) {
+      if (Node.isStringLiteral(el)) {
+        el.replaceWithText(`{ target: ${el.getText()} }`);
+        changed = true;
+      }
+    }
+    return changed;
+  }
+  return false;
+}
+
+/**
+ * Given the value of an `on:` or `after:` property (an object literal mapping
+ * event/delay → transition), wrap each string transition target.
+ */
+function wrapTransitionMap(value) {
+  if (!Node.isObjectLiteralExpression(value)) {
+    return 0;
+  }
+  let count = 0;
+  for (const prop of value.getProperties()) {
+    if (Node.isPropertyAssignment(prop)) {
+      const init = prop.getInitializerOrThrow();
+      if (wrapValue(init)) {
+        count++;
+      }
+    }
+  }
+  return count;
+}
+
+/**
+ * Recursively walk a state config object literal wrapping string transitions.
+ * We recurse into `states`, `on`/`after`/`onDone`/`onError`/`always`, and
+ * nested state nodes.
+ */
+function walkStateNode(obj, notes) {
+  let count = 0;
+  for (const prop of obj.getProperties()) {
+    if (!Node.isPropertyAssignment(prop)) {
+      continue;
+    }
+    const key = getKey$1(prop);
+    if (key === undefined) {
+      continue;
+    }
+    const init = prop.getInitializer();
+    if (!init) {
+      continue;
+    }
+    if (EVENT_LIKE_KEYS.has(key)) {
+      const n = wrapTransitionMap(init);
+      count += n;
+      if (n) {
+        notes.push(`wrapped ${n} string transition(s) under '${key}'`);
+      }
+    } else if (DIRECT_TRANSITION_KEYS.has(key)) {
+      if (wrapValue(init)) {
+        count++;
+        notes.push(`wrapped string transition under '${key}'`);
+      }
+    } else if (key === 'states' && Node.isObjectLiteralExpression(init)) {
+      for (const stateProp of init.getProperties()) {
+        if (Node.isPropertyAssignment(stateProp) && Node.isObjectLiteralExpression(stateProp.getInitializerOrThrow())) {
+          count += walkStateNode(stateProp.getInitializerOrThrow(), notes);
+        }
+      }
+    } else if (key === 'invoke') {
+      // invoke configs carry their own onDone/onError transitions
+      const invokeObjects = Node.isArrayLiteralExpression(init) ? init.getElements().filter(Node.isObjectLiteralExpression) : Node.isObjectLiteralExpression(init) ? [init] : [];
+      for (const invokeObj of invokeObjects) {
+        count += walkStateNode(invokeObj, notes);
+      }
+    }
+  }
+  return count;
+}
+function getKey$1(prop) {
+  const nameNode = prop.getNameNode();
+  if (Node.isIdentifier(nameNode)) {
+    return nameNode.getText();
+  }
+  if (Node.isStringLiteral(nameNode)) {
+    return nameNode.getLiteralText();
+  }
+  if (nameNode.getKind() === SyntaxKind.NumericLiteral) {
+    return nameNode.getText();
+  }
+  return undefined;
+}
+
+/**
+ * Converts bare string transition values inside `createMachine`/`setup().
+ * createMachine`/`createStateConfig` config objects into `{ target: '...' }`.
+ *
+ * Does NOT touch `initial:` (still a string in v6) or existing `target:`
+ * values.
+ */
+const stringTargets = {
+  name: 'string-targets',
+  description: "Wrap bare string transition values (on/after/onDone/onError/always) into { target: '...' } inside machine config objects. Best-effort: matches createMachine/createStateConfig by call name.",
+  apply(sourceFile) {
+    const notes = [];
+    let total = 0;
+    for (const configObj of findMachineConfigObjects(sourceFile)) {
+      total += walkStateNode(configObj, notes);
+    }
+    return {
+      changed: total > 0,
+      notes
+    };
+  }
+};
+
+/**
+ * Extracts the `T` type node from a `{} as T` (AsExpression) initializer of a
+ * `types:` property. Returns undefined if the shape isn't recognized.
+ */
+function getTypesAsTypeNode(init) {
+  if (!Node.isAsExpression(init)) {
+    return undefined;
+  }
+  return init.getTypeNode();
+}
+
+/**
+ * Given a union type node written as an inline literal union of object types,
+ * each with a `type: '...'` discriminant, returns a map entry list of
+ * `[eventType, remainingObjectTypeText]`. Returns undefined when the union is
+ * not a literal inline union of object types with string-literal `type` props.
+ */
+function unionToEventMap(typeNode) {
+  const members = Node.isUnionTypeNode(typeNode) ? typeNode.getTypeNodes() : [typeNode];
+  const entries = [];
+  for (const member of members) {
+    if (!Node.isTypeLiteral(member)) {
+      return undefined; // e.g. a type reference — bail out entirely
+    }
+    const lit = member;
+    const props = lit.getProperties();
+    const typeProp = props.find(p => p.getName() === 'type');
+    if (!typeProp) {
+      return undefined;
+    }
+    const typePropTypeNode = typeProp.getTypeNode();
+    if (!typePropTypeNode || typePropTypeNode.getKind() !== SyntaxKind.LiteralType) {
+      return undefined;
+    }
+    const literal = typePropTypeNode.getFirstChild();
+    if (!literal || !Node.isStringLiteral(literal)) return undefined;
+    const eventType = literal.getLiteralValue();
+
+    // Build payload object type text from the remaining props.
+    const payloadProps = props.filter(p => p.getName() !== 'type').map(p => p.getText().replace(/[;,]\s*$/, ''));
+    const payload = payloadProps.length ? `{ ${payloadProps.join('; ')} }` : `{}`;
+    entries.push({
+      eventType,
+      payload
+    });
+  }
+  return entries;
+}
+function getKey(prop) {
+  const nameNode = prop.getNameNode();
+  if (Node.isIdentifier(nameNode)) {
+    return nameNode.getText();
+  }
+  if (Node.isStringLiteral(nameNode)) {
+    return nameNode.getLiteralText();
+  }
+  return undefined;
+}
+
+/**
+ * Converts a single `types: {} as { ... }` property into a `schemas: { ... }`
+ * property. Mutates the containing config object literal.
+ */
+function convertTypesProperty(configObj, typesProp, notes) {
+  const init = typesProp.getInitializerOrThrow();
+  const typeNode = getTypesAsTypeNode(init);
+  if (!typeNode) {
+    return false;
+  }
+
+  // `types: {} as any` (or non-object) — cannot infer a shape; leave a note.
+  if (!Node.isTypeLiteral(typeNode)) {
+    notes.push(`left 'types' unchanged: initializer is not an inline object type ({} as ${typeNode.getText()})`);
+    typesProp.replaceWithText(`${typesProp.getText()} /* TODO(xstate-codemod): could not migrate 'types' to 'schemas' automatically */`);
+    return false;
+  }
+  const lit = typeNode;
+  const schemaEntries = [];
+  let usedTypes = false;
+  let eventsLeftBehind = false;
+  for (const member of lit.getProperties()) {
+    const key = member.getName();
+    const valueTypeNode = member.getTypeNode();
+    if (!valueTypeNode) {
+      continue;
+    }
+    if (key === 'events') {
+      const map = unionToEventMap(valueTypeNode);
+      if (!map) {
+        // Not a literal inline union — leave events in `types`, add a TODO.
+        eventsLeftBehind = true;
+        notes.push(`could not migrate 'events' to schemas.events map (not a literal inline union); left in place`);
+        continue;
+      }
+      schemaEntries.push(helper => {
+        const mapEntries = map.map(e => `${JSON.stringify(e.eventType)}: ${helper}<${e.payload}>()`);
+        return `events: {\n    ${mapEntries.join(',\n    ')}\n  }`;
+      });
+      usedTypes = true;
+    } else {
+      // context, input, output, emitted, tags, meta, ... → types<T>()
+      const valueType = valueTypeNode.getText();
+      schemaEntries.push(helper => `${key}: ${helper}<${valueType}>()`);
+      usedTypes = true;
+    }
+  }
+  if (schemaEntries.length === 0) {
+    return false;
+  }
+  const helper = usedTypes ? ensureNamedImport(configObj.getSourceFile(), 'types', configObj) : undefined;
+  if (!helper) {
+    notes.push("left 'types' unchanged: no xstate runtime import available");
+    return false;
+  }
+  const schemasText = `schemas: {\n  ${schemaEntries.map(entry => entry(helper)).join(',\n  ')}\n}`;
+  if (eventsLeftBehind) {
+    // Keep the original `types` property (holding only the un-migratable
+    // events) alongside the new `schemas` property.
+    // Rebuild `types` with only the `events` member preserved.
+    const eventsMember = lit.getProperties().find(p => p.getName() === 'events');
+    const preservedTypes = eventsMember ? `types: {} as { ${eventsMember.getText()} } /* TODO(xstate-codemod): migrate events to schemas.events map */` : typesProp.getText();
+    typesProp.replaceWithText(`${schemasText},\n  ${preservedTypes}`);
+  } else {
+    typesProp.replaceWithText(schemasText);
+  }
+  notes.push(`converted 'types' → 'schemas' (${schemaEntries.length} key(s))${eventsLeftBehind ? "; 'events' left as types (manual)" : ''}`);
+  return true;
+}
+
+/**
+ * Converts `types: {} as { context; events; input; ... }` inside machine config
+ * objects into `schemas: { context: types<...>(), ... }`.
+ */
+const typesToSchemas = {
+  name: 'types-to-schemas',
+  description: 'Convert `types: {} as {...}` into `schemas: { context: types<C>(), events: { ... }, input: types<I>() }`. Events are converted to a map only when written as a literal inline union.',
+  apply(sourceFile) {
+    const notes = [];
+    let changed = false;
+    for (const configObj of findMachineConfigObjects(sourceFile, ['createMachine', 'createStateConfig', 'setup'])) {
+      for (const prop of configObj.getProperties()) {
+        if (Node.isPropertyAssignment(prop) && getKey(prop) === 'types') {
+          if (convertTypesProperty(configObj, prop, notes)) {
+            changed = true;
+          }
+        }
+      }
+    }
+    return {
+      changed,
+      notes
+    };
+  }
+};
+
+/**
+ * v5 `'xstate'` exports that require structural rewrites in v6 and are too
+ * risky to automate. Value is a one-line hint for the v6 replacement.
+ */
+const REMOVED_APIS = {
+  assign: 'return a `{ context }` patch from the transition/action function',
+  raise: 'use `enq.raise(...)` inside an action',
+  sendTo: 'use `enq.sendTo(...)` inside an action',
+  sendParent: 'use `enq.sendTo(...)` with the parent ref inside an action',
+  forwardTo: 'use `enq.sendTo(target, event)` inside an action',
+  emit: 'use `enq.emit(...)` inside an action',
+  log: 'use `enq.log(...)` inside an action',
+  cancel: 'use `enq.cancel(...)` inside an action',
+  spawnChild: 'use `enq.spawn(...)` inside an action',
+  stop: 'use `enq.stop(...)` inside an action',
+  stopChild: 'use `enq.stop(...)` inside an action',
+  enqueueActions: 'action functions now receive an `enq` enqueue object directly',
+  and: 'inline the guard as `(...) => a(...) && b(...)`',
+  or: 'inline the guard as `(...) => a(...) || b(...)`',
+  not: 'inline the guard as `(...) => !a(...)`',
+  stateIn: 'use `self.getSnapshot().matches(...)` or `checkStateIn(snapshot, "#id")`',
+  fromPromise: 'use `createAsyncLogic(...)`',
+  fromTransition: 'use `createLogic({ context, run })`'
+};
+
+/**
+ * Detects (does NOT transform) usages of v5 `'xstate'` APIs that were removed
+ * or restructured in v6. Reports file:line + API + a replacement hint via the
+ * returned notes.
+ */
+const reportRemovedApis = {
+  name: 'report-removed-apis',
+  description: 'Detect (report only) usages of removed/restructured v5 xstate APIs (assign, raise, sendTo, emit, fromPromise, and/or/not, etc.) that need manual migration.',
+  apply(sourceFile) {
+    const notes = [];
+    const xstateImports = sourceFile.getImportDeclarations().filter(imp => imp.getModuleSpecifierValue() === 'xstate');
+
+    // Map local binding name → canonical API name (respecting aliases).
+    const tracked = new Map();
+    for (const imp of xstateImports) {
+      for (const spec of imp.getNamedImports()) {
+        const original = spec.getNameNode().getText();
+        if (REMOVED_APIS[original]) {
+          const local = (spec.getAliasNode() ?? spec.getNameNode()).getText();
+          tracked.set(local, original);
+        }
+      }
+    }
+    if (tracked.size === 0) {
+      return {
+        changed: false,
+        notes
+      };
+    }
+    const filePath = sourceFile.getFilePath();
+    for (const ident of sourceFile.getDescendantsOfKind(SyntaxKind.Identifier)) {
+      const local = ident.getText();
+      const api = tracked.get(local);
+      if (!api) {
+        continue;
+      }
+      // Skip the import specifier declarations themselves.
+      const parentKind = ident.getParent()?.getKind();
+      if (parentKind === SyntaxKind.ImportSpecifier || parentKind === SyntaxKind.ImportClause) {
+        continue;
+      }
+      const {
+        line,
+        column
+      } = sourceFile.getLineAndColumnAtPos(ident.getPos());
+      notes.push(`${filePath}:${line}:${column} — '${api}' → ${REMOVED_APIS[api]}`);
+    }
+
+    // Never mutates the file.
+    return {
+      changed: false,
+      notes
+    };
+  }
+};
+
+/** All transforms, in recommended application order. */
+const transforms = [renameImports, stringTargets, typesToSchemas, reportRemovedApis];
+const transformsByName = Object.fromEntries(transforms.map(t => [t.name, t]));
+
+/** Resolve a list of transform names to Transform objects. */
+function selectTransforms(names) {
+  if (!names || names.length === 0) {
+    return transforms;
+  }
+  const selected = [];
+  for (const name of names) {
+    const t = transformsByName[name];
+    if (!t) {
+      throw new Error(`Unknown transform '${name}'. Available: ${Object.keys(transformsByName).join(', ')}`);
+    }
+    selected.push(t);
+  }
+  return selected;
+}
+
+/** Applies the given transforms to a single source file (in-memory). */
+function applyToSourceFile(sourceFile, transforms) {
+  const perTransform = [];
+  let changed = false;
+  for (const transform of transforms) {
+    const result = transform.apply(sourceFile);
+    perTransform.push({
+      transform: transform.name,
+      changed: result.changed,
+      notes: result.notes
+    });
+    if (result.changed) {
+      changed = true;
+    }
+  }
+  if (changed) {
+    const diagnostics = sourceFile.getProject().getProgram().compilerObject.getSyntacticDiagnostics(sourceFile.compilerNode);
+    if (diagnostics.length) {
+      throw new Error(`Refusing to write invalid migration output for ${sourceFile.getFilePath()}: ${diagnostics.map(diagnostic => ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ')).join('; ')}`);
+    }
+  }
+  return {
+    filePath: sourceFile.getFilePath(),
+    perTransform,
+    changed,
+    newText: changed ? sourceFile.getFullText() : undefined
+  };
+}
+
+/**
+ * Runs the selected transforms over the given files.
+ *
+ * @param filePaths absolute or cwd-relative file paths to process
+ * @param transforms the transforms to apply
+ * @param options.write when true, saves modified files to disk
+ */
+function run(filePaths, transforms, options = {
+  write: false
+}) {
+  const project = new Project({
+    useInMemoryFileSystem: false,
+    skipAddingFilesFromTsConfig: true,
+    compilerOptions: {
+      allowJs: true
+    }
+  });
+  const files = [];
+  const manualMigrationNotes = [];
+  let filesChanged = 0;
+  for (const filePath of filePaths) {
+    const sourceFile = project.addSourceFileAtPath(filePath);
+    const report = applyToSourceFile(sourceFile, transforms);
+    for (const pt of report.perTransform) {
+      if (pt.transform === 'report-removed-apis') {
+        manualMigrationNotes.push(...pt.notes);
+      }
+    }
+    if (report.changed) {
+      filesChanged++;
+      if (options.write) {
+        sourceFile.saveSync();
+      }
+    }
+    files.push(report);
+  }
+  return {
+    files,
+    filesChanged,
+    manualMigrationNotes
+  };
+}
+
+const DEFAULT_GLOB = '**/*.{ts,tsx,js,jsx}';
+const IGNORE = ['**/node_modules/**', '**/dist/**'];
+
+/** Hand-written arg parser (no yargs). */
+function parseArgs(argv) {
+  const parsed = {
+    command: undefined,
+    globs: [],
+    dry: false,
+    transformNames: undefined,
+    help: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+    } else if (arg === '--dry') {
+      parsed.dry = true;
+    } else if (arg === '--transform') {
+      const value = argv[++i];
+      if (value) {
+        parsed.transformNames = value.split(',').map(s => s.trim()).filter(Boolean);
+      }
+    } else if (arg.startsWith('--transform=')) {
+      parsed.transformNames = arg.slice('--transform='.length).split(',').map(s => s.trim()).filter(Boolean);
+    } else if (!parsed.command) {
+      parsed.command = arg;
+    } else {
+      parsed.globs.push(arg);
+    }
+  }
+  return parsed;
+}
+function printHelp() {
+  const names = transforms.map(t => `    ${t.name} — ${t.description}`);
+  process.stdout.write(['xstate-codemod — migrate XState source (v5 → v6)', '', 'Usage:', '  xstate-codemod migrate [globs...] [--dry] [--transform <name,name>]', '', 'Options:', '  --dry                  Print a summary of changes without writing files', '  --transform <names>    Comma-separated transform names (default: all)', '  -h, --help             Show this help', '', `Default glob: ${DEFAULT_GLOB} (excludes node_modules and dist)`, '', 'Transforms:', ...names, ''].join('\n'));
+}
+
+/**
+ * Resolves glob patterns into a de-duplicated list of file paths using
+ * ts-morph's built-in glob support (no extra glob dependency).
+ */
+function resolveFiles(globs) {
+  const patterns = (globs.length ? globs : [DEFAULT_GLOB]).concat(IGNORE.map(p => `!${p}`));
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true
+  });
+  const set = new Set();
+  for (const sf of project.addSourceFilesAtPaths(patterns)) {
+    set.add(sf.getFilePath());
+  }
+  return [...set].sort();
+}
+
+/** CLI entry point. Returns a process exit code. */
+function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help || !args.command) {
+    printHelp();
+    return args.command ? 0 : args.help ? 0 : 1;
+  }
+  if (args.command !== 'migrate') {
+    process.stderr.write(`Unknown command '${args.command}'. Did you mean 'migrate'?\n`);
+    return 1;
+  }
+  let transforms;
+  try {
+    transforms = selectTransforms(args.transformNames);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    return 1;
+  }
+  const files = resolveFiles(args.globs);
+  if (files.length === 0) {
+    process.stdout.write('No files matched.\n');
+    return 0;
+  }
+  const report = run(files, transforms, {
+    write: !args.dry
+  });
+
+  // Per-file, per-transform summary.
+  for (const file of report.files) {
+    const touched = file.perTransform.filter(pt => pt.changed || pt.notes.length);
+    if (touched.length === 0) {
+      continue;
+    }
+    process.stdout.write(`\n${file.filePath}${file.changed ? '' : ' (no writes)'}\n`);
+    for (const pt of touched) {
+      const mark = pt.changed ? '✔' : '·';
+      process.stdout.write(`  ${mark} ${pt.transform}\n`);
+      for (const note of pt.notes) {
+        process.stdout.write(`      - ${note}\n`);
+      }
+    }
+  }
+
+  // Manual-migration section.
+  if (report.manualMigrationNotes.length) {
+    process.stdout.write('\n=== Manual migration needed ===\n');
+    for (const note of report.manualMigrationNotes) {
+      process.stdout.write(`  ${note}\n`);
+    }
+  }
+
+  // Final report.
+  process.stdout.write(`\n${args.dry ? '[dry run] ' : ''}${report.filesChanged} of ${files.length} file(s) ${args.dry ? 'would change' : 'changed'}.\n`);
+  return 0;
+}
+
+export { applyToSourceFile, main, parseArgs, renameImports, reportRemovedApis, resolveFiles, run, selectTransforms, stringTargets, transforms, transformsByName, typesToSchemas };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xstate/codemod",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "Codemods for migrating XState source between versions (v5 → v6)",
   "keywords": [
     "xstate",
@@ -42,4 +42,4 @@
       "./index.ts"
     ]
   }
-}
+}