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

package/README.md

@@ -3,7 +3,7 @@
 <!-- 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.
+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.
 
 <!-- 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.
+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/dist/declarations/src/index.d.ts

@@ -1,4 +1,4 @@
 export type { Transform, TransformResult } from "./types.js";
-export { transforms, transformsByName, renameImports, stringTargets, typesToSchemas, reportRemovedApis } from "./transforms/index.js";
+export { transforms, transformsByName, renameImports, stringTargets, typesToSchemas, reportRemovedApis, reportIdPathTargets } 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

@@ -13,7 +13,7 @@ export interface FileTransformReport {
 export interface RunReport {
     files: FileTransformReport[];
     filesChanged: number;
-    /** Notes emitted by `report-removed-apis` (manual-migration section). */
+    /** Notes emitted by the report-only transforms (manual-migration section). */
     manualMigrationNotes: string[];
 }
 /** Resolve a list of transform names to Transform objects. */

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

@@ -3,7 +3,8 @@ 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";
+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 };
+export { renameImports, stringTargets, typesToSchemas, reportRemovedApis, reportIdPathTargets };

package/dist/declarations/src/transforms/report-id-path-targets.d.ts

@@ -0,0 +1,8 @@
+import type { Transform } from "../types.js";
+/**
+ * Reports (does NOT transform) `#a.b` targets and `matches('#a.b')`/
+ * `stateIn('#a.b')` references that the codemod cannot verify as whole state
+ * ids. In v6, the text after `#` is an exact id and is never split into an
+ * id followed by a path.
+ */
+export declare const reportIdPathTargets: Transform;

package/dist/xstate-codemod.js

@@ -7,7 +7,13 @@ const RENAMES = {
   Interpreter: 'Actor',
   fromCallback: 'createCallbackLogic',
   fromObservable: 'createObservableLogic',
-  fromEventObservable: 'createEventObservableLogic'
+  fromEventObservable: 'createEventObservableLogic',
+  ExecutableActionObject: 'ExecutableEffect',
+  ExecutableActionsFrom: 'ExecutableEffectFrom',
+  ExecutableSpawnAction: 'SpawnExecutableEffect',
+  SpecialExecutableAction: 'SpecialExecutableEffect',
+  ToExecutableAction: 'ToExecutableEffect',
+  ActorRefFromLogic: 'ActorRefFrom'
 };
 
 /**
@@ -17,7 +23,7 @@ const RENAMES = {
  */
 const renameImports = {
   name: 'rename-imports',
-  description: "Rename renamed 'xstate' imports (interpret→createActor, Interpreter→Actor, fromCallback/fromObservable/fromEventObservable→create*Logic) and their usages.",
+  description: "Rename renamed 'xstate' imports (interpret→createActor, Interpreter→Actor, fromCallback/fromObservable/fromEventObservable→create*Logic, executable action types→executable effect types, ActorRefFromLogic→ActorRefFrom) and their usages.",
   apply(sourceFile) {
     const notes = [];
     let changed = false;
@@ -44,7 +50,12 @@ const renameImports = {
               ref.replaceWithText(replacement);
             }
           }
-          nameNode.replaceWithText(replacement);
+          const alreadyImported = imp.getNamedImports().some(other => other !== spec && !other.getAliasNode() && other.getNameNode().getText() === replacement);
+          if (alreadyImported) {
+            spec.remove();
+          } else {
+            nameNode.replaceWithText(replacement);
+          }
           notes.push(`renamed '${importedName}' → '${replacement}'${refs.length ? ` and ${refs.length} usage(s)` : ''}`);
         }
         changed = true;
@@ -446,9 +457,12 @@ const REMOVED_APIS = {
   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")`',
+  stateIn: 'use `self.getSnapshot().matches(...)`',
   fromPromise: 'use `createAsyncLogic(...)`',
-  fromTransition: 'use `createLogic({ context, run })`'
+  fromTransition: 'use `createStepLogic({ context, run })`',
+  toObserver: 'pass an observer object or callback directly',
+  pathToStateValue: 'build the state value object directly',
+  SpecialTargets: 'use `enq.sendTo(self, event)` for internal sends; parent sends use `enq.sendTo(...)` with the parent ref'
 };
 
 /**
@@ -458,7 +472,7 @@ const REMOVED_APIS = {
  */
 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.',
+  description: 'Detect (report only) usages of removed/restructured v5 xstate APIs (assign, raise, sendTo, emit, fromPromise, and/or/not, toObserver, SpecialTargets, etc.) that need manual migration.',
   apply(sourceFile) {
     const notes = [];
     const xstateImports = sourceFile.getImportDeclarations().filter(imp => imp.getModuleSpecifierValue() === 'xstate');
@@ -507,10 +521,153 @@ const reportRemovedApis = {
   }
 };
 
+/** Keys whose string values (or string array elements) are state targets. */
+const TARGET_KEYS = new Set(['target', 'initial', 'on', 'after', 'always', 'onDone', 'onError']);
+
+/** Calls whose first argument is a state value or `#id` reference. */
+const MATCH_CALLS = new Set(['matches', 'stateIn']);
+function getPropertyName(node) {
+  if (Node.isPropertyAssignment(node)) {
+    const name = node.getNameNode();
+    if (Node.isIdentifier(name) || Node.isStringLiteral(name)) {
+      return Node.isStringLiteral(name) ? name.getLiteralText() : name.getText();
+    }
+  }
+  return undefined;
+}
+function getStringProperty(object, name) {
+  const property = object.getProperty(name);
+  if (!property || !Node.isPropertyAssignment(property)) return undefined;
+  const initializer = property.getInitializer();
+  return initializer && (Node.isStringLiteral(initializer) || Node.isNoSubstitutionTemplateLiteral(initializer)) ? initializer.getLiteralText() : undefined;
+}
+/**
+ * Collects the state ids that one machine config literal declares: explicit
+ * state `id`s and, for `createMachine` configs, implicit ids (the path from
+ * the root, prefixed by the machine id when one is set). Invoke and actor ids
+ * are not state ids and are not collected.
+ */
+function collectStateIds(config, withImplicitIds) {
+  const ids = new Set();
+  function walk(stateConfig, implicitId) {
+    const explicitId = getStringProperty(stateConfig, 'id');
+    if (explicitId !== undefined) ids.add(explicitId);else if (withImplicitIds) ids.add(implicitId);
+    const states = stateConfig.getProperty('states');
+    if (!states || !Node.isPropertyAssignment(states)) return;
+    const statesObject = states.getInitializer();
+    if (!statesObject || !Node.isObjectLiteralExpression(statesObject)) return;
+    for (const state of statesObject.getProperties()) {
+      const key = getPropertyName(state);
+      if (key === undefined || !Node.isPropertyAssignment(state)) continue;
+      const child = state.getInitializer();
+      if (!child || !Node.isObjectLiteralExpression(child)) continue;
+      walk(child, implicitId ? `${implicitId}.${key}` : key);
+    }
+  }
+  walk(config, getStringProperty(config, 'id') ?? '');
+  return ids;
+}
+
+/**
+ * Finds the `createMachine(...)` or `createStateConfig(...)` config literal
+ * that contains `node`, if any.
+ */
+function findEnclosingConfig(node, machineConfigs, stateConfigs) {
+  for (const ancestor of node.getAncestors()) {
+    if (!Node.isObjectLiteralExpression(ancestor)) continue;
+    if (machineConfigs.has(ancestor)) {
+      return {
+        config: ancestor,
+        withImplicitIds: true
+      };
+    }
+    if (stateConfigs.has(ancestor)) {
+      return {
+        config: ancestor,
+        withImplicitIds: false
+      };
+    }
+  }
+  return undefined;
+}
+function isMatchArgument(literal) {
+  const call = literal.getParent();
+  if (!call || !Node.isCallExpression(call)) return false;
+  if (call.getArguments()[0] !== literal) return false;
+  const expression = call.getExpression();
+  const name = Node.isIdentifier(expression) ? expression.getText() : Node.isPropertyAccessExpression(expression) ? expression.getName() : undefined;
+  return !!name && MATCH_CALLS.has(name);
+}
+function isTargetValue(literal) {
+  let node = literal;
+  let parent = node.getParent();
+  if (parent && Node.isArrayLiteralExpression(parent)) {
+    node = parent;
+    parent = node.getParent();
+  }
+  if (!parent || !Node.isPropertyAssignment(parent)) return false;
+  const name = getPropertyName(parent);
+  if (name && TARGET_KEYS.has(name)) return true;
+  // A bare string transition inside `on: { EVENT: '#a.b' }` or
+  // `after: { 1000: '#a.b' }`.
+  const container = parent.getParent();
+  const owner = container?.getParent();
+  const ownerName = owner ? getPropertyName(owner) : undefined;
+  return ownerName === 'on' || ownerName === 'after';
+}
+
+/**
+ * Reports (does NOT transform) `#a.b` targets and `matches('#a.b')`/
+ * `stateIn('#a.b')` references that the codemod cannot verify as whole state
+ * ids. In v6, the text after `#` is an exact id and is never split into an
+ * id followed by a path.
+ */
+const reportIdPathTargets = {
+  name: 'report-id-path-targets',
+  description: "Detect (report only) '#id.path' targets and matches('#id.path') references that may combine an id with a relative path, which v6 no longer resolves.",
+  apply(sourceFile) {
+    const notes = [];
+    const filePath = sourceFile.getFilePath();
+    const machineConfigs = new Set(findMachineConfigObjects(sourceFile, ['createMachine']));
+    const stateConfigs = new Set(findMachineConfigObjects(sourceFile, ['createStateConfig']));
+    const idsByConfig = new Map();
+    const literals = [...sourceFile.getDescendantsOfKind(SyntaxKind.StringLiteral), ...sourceFile.getDescendantsOfKind(SyntaxKind.NoSubstitutionTemplateLiteral)].sort((a, b) => a.getStart() - b.getStart());
+    for (const literal of literals) {
+      const text = literal.getLiteralText();
+      if (!text.startsWith('#') || !text.includes('.')) continue;
+      if (!isTargetValue(literal) && !isMatchArgument(literal)) continue;
+      // Only ids from the config that contains the reference count; a
+      // reference outside an analyzable config is always reported.
+      const enclosing = findEnclosingConfig(literal, machineConfigs, stateConfigs);
+      if (enclosing) {
+        let ids = idsByConfig.get(enclosing.config);
+        if (!ids) {
+          ids = collectStateIds(enclosing.config, enclosing.withImplicitIds);
+          idsByConfig.set(enclosing.config, ids);
+        }
+        if (ids.has(text.slice(1))) continue;
+      }
+      const {
+        line,
+        column
+      } = sourceFile.getLineAndColumnAtPos(literal.getStart());
+      notes.push(`${filePath}:${line}:${column} — '${text}' → '#…' is an exact state id in v6 and is never split into an id and a path; use the target state's own id (its explicit \`id\` or its full implicit id)`);
+    }
+
+    // Never mutates the file.
+    return {
+      changed: false,
+      notes
+    };
+  }
+};
+
 /** All transforms, in recommended application order. */
-const transforms = [renameImports, stringTargets, typesToSchemas, reportRemovedApis];
+const transforms = [renameImports, stringTargets, typesToSchemas, reportRemovedApis, reportIdPathTargets];
 const transformsByName = Object.fromEntries(transforms.map(t => [t.name, t]));
 
+/** Report-only transforms whose notes list manual migration steps. */
+const REPORT_TRANSFORMS = new Set(['report-removed-apis', 'report-id-path-targets']);
 /** Resolve a list of transform names to Transform objects. */
 function selectTransforms(names) {
   if (!names || names.length === 0) {
@@ -580,7 +737,7 @@ function run(filePaths, transforms, options = {
     const sourceFile = project.addSourceFileAtPath(filePath);
     const report = applyToSourceFile(sourceFile, transforms);
     for (const pt of report.perTransform) {
-      if (pt.transform === 'report-removed-apis') {
+      if (REPORT_TRANSFORMS.has(pt.transform)) {
         manualMigrationNotes.push(...pt.notes);
       }
     }
@@ -709,4 +866,4 @@ function main(argv) {
   return 0;
 }
 
-export { applyToSourceFile, main, parseArgs, renameImports, reportRemovedApis, resolveFiles, run, selectTransforms, stringTargets, transforms, transformsByName, typesToSchemas };
+export { applyToSourceFile, main, parseArgs, renameImports, reportIdPathTargets, reportRemovedApis, resolveFiles, run, selectTransforms, stringTargets, transforms, transformsByName, typesToSchemas };

package/package.json

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