styled-components-to-stylex-codemod 0.0.55 → 0.0.57

package/README.md

@@ -37,6 +37,8 @@ The adapter maps your project's `props.theme.*` access, CSS variables, and helpe
 
 When a component wraps another component that internally uses styled-components (e.g. `styled(GroupHeader)` where `GroupHeader` renders a `StyledHeader`), CSS cascade conflicts can arise after migration. Convert leaf files — the ones that don't wrap other styled-components — first, then work your way up. The codemod will bail with a warning if it detects this pattern.
 
+Run [`analyzeMigrationPlan`](#planning-manual-conversions) to get the ordered, bottom-up list of files to convert by hand first.
+
 ### 4. Verify, iterate, clean up
 
 Build and test your project. Review warnings — they tell you which files were skipped and why. Fix adapter gaps, re-run on remaining files, and repeat until done. [Report issues](https://github.com/skovhus/styled-components-to-stylex-codemod/issues) with input/output examples if the codemod produces incorrect results.
@@ -380,6 +382,24 @@ await runTransform({
 
 </details>
 
+### Planning manual conversions
+
+`analyzeMigrationPlan` runs the codemod in analysis-only mode (it never writes files) and returns the bottom-up ordered list of files you must convert by hand — the genuine blockers the codemod can't convert — each with its consumer count, the exports to convert, direct auto-migration payoff, secondary blocker-chain context, and the bail reasons. `formatMigrationPlan` renders it as a report with direct unlocks emphasized first so raw chain involvement is not mistaken for files unlocked by one blocker alone.
+
+```ts
+import { analyzeMigrationPlan, formatMigrationPlan } from "styled-components-to-stylex-codemod";
+
+const plan = await analyzeMigrationPlan({
+  files: "src/**/*.tsx",
+  consumerPaths: "src/**/*.tsx",
+  adapter, // the same adapter you pass to runTransform
+});
+
+console.log(formatMigrationPlan(plan));
+```
+
+Try it against this repo's own fixtures with `node scripts/migration-plan.mts`.
+
 ### Adapter
 
 Adapters are the main extension point, see full example above. They let you control:

package/dist/{ast-walk-C226poBl.mjs → ast-walk-DVmYZ2mK.mjs}

@@ -1,6 +1,60 @@
-import path from "node:path";
+import { n as isTemplatePlaceholderInSelectorContext, r as PLACEHOLDER_RE } from "./selector-context-heuristic-Dptd93Xe.mjs";
+import path, { relative, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { parse } from "@babel/parser";
+//#region src/internal/utilities/ast-safety.ts
+/**
+* AST safety checks for null nodes and structural issues.
+* Core concepts: recursive validation and error reporting.
+*/
+/**
+* `JSON.stringify` replacer that drops noisy AST positional metadata
+* (`loc`/`tokens`/`comments`/`start`/`end`) and replaces circular references
+* with `"[Circular]"`, so AST nodes can be serialized for logging or as a
+* stable structural key. Create a fresh replacer per `stringify` call — it
+* keeps per-serialization state.
+*/
+function createAstSafeJsonReplacer() {
+	const seen = /* @__PURE__ */ new WeakSet();
+	return (key, value) => {
+		if (key === "loc" || key === "tokens" || key === "comments" || key === "start" || key === "end") return;
+		if (value && typeof value === "object") {
+			if (seen.has(value)) return "[Circular]";
+			seen.add(value);
+		}
+		return value;
+	};
+}
+/** AST node types whose `elements` array legitimately contains `null` (holes/elisions). */
+const ARRAY_ELEMENT_HOLE_TYPES = new Set(["ArrayPattern", "ArrayExpression"]);
+function assertNoNullNodesInArrays(node) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const visit = (cur, path, allowNulls) => {
+		if (cur === null || cur === void 0) return;
+		if (Array.isArray(cur)) {
+			for (let i = 0; i < cur.length; i++) {
+				if (cur[i] === null) {
+					if (!allowNulls) throw new Error(`Null AST node in array at ${path}[${i}]`);
+					continue;
+				}
+				visit(cur[i], `${path}[${i}]`, false);
+			}
+			return;
+		}
+		if (typeof cur !== "object") return;
+		const curObj = cur;
+		if (seen.has(curObj)) return;
+		seen.add(curObj);
+		const nodeType = cur.type;
+		const hasValidElementHoles = typeof nodeType === "string" && ARRAY_ELEMENT_HOLE_TYPES.has(nodeType);
+		for (const [k, v] of Object.entries(cur)) {
+			if (v === null) continue;
+			if (typeof v === "object") visit(v, `${path}.${k}`, hasValidElementHoles && k === "elements");
+		}
+	};
+	visit(node, "root", false);
+}
+//#endregion
 //#region src/internal/logger.ts
 /**
 * Logger and warning types for transform diagnostics.
@@ -89,6 +143,14 @@ var Logger = class Logger {
 	static createReport() {
 		return new LoggerReport([...Logger.collected], Logger.fileCount, Logger.maxExamples);
 	}
+	/**
+	* Restore the collected warnings to a previous snapshot (from
+	* `createReport().getWarnings()`). Used to undo the side effects of an
+	* analysis-only dry run on the process-global logger.
+	*/
+	static restoreWarnings(warnings) {
+		Logger.collected = [...warnings];
+	}
 	/** @internal - for testing only */
 	static _clearCollected() {
 		Logger.collected = [];
@@ -123,20 +185,9 @@ var Logger = class Logger {
 	}
 	static formatContext(context) {
 		if (typeof context === "undefined") return null;
-		return JSON.stringify(context, createContextReplacer(), 2);
+		return JSON.stringify(context, createAstSafeJsonReplacer(), 2);
 	}
 };
-function createContextReplacer() {
-	const seen = /* @__PURE__ */ new WeakSet();
-	return (key, value) => {
-		if (key === "loc" || key === "tokens" || key === "comments" || key === "start" || key === "end") return;
-		if (value && typeof value === "object") {
-			if (seen.has(value)) return "[Circular]";
-			seen.add(value);
-		}
-		return value;
-	};
-}
 const MAX_DEPENDED_FILE_GROUPS = 15;
 var LoggerReport = class {
 	warnings;
@@ -273,14 +324,16 @@ var LoggerReport = class {
 		}
 	}
 };
+/**
+* Extract the depended-on file path from a cascade-conflict warning's context
+* (the base component's defining file that must be converted first). Owned here
+* alongside the warning-type definition so consumers share one invariant.
+*/
 function getCascadeDependedFilePath(warning) {
 	const context = warning.context;
-	if (!context || typeof context !== "object") return;
-	const record = context;
-	const definitionPath = record.definitionPath;
-	if (typeof definitionPath === "string") return definitionPath;
-	const importedPath = record.importedPath;
-	return typeof importedPath === "string" ? importedPath : void 0;
+	if (!context) return;
+	if (typeof context.definitionPath === "string") return context.definitionPath;
+	return typeof context.importedPath === "string" ? context.importedPath : void 0;
 }
 function uniqueSorted(values) {
 	return Array.from(new Set(values)).sort((a, b) => a.localeCompare(b));
@@ -425,22 +478,6 @@ function getFileImportsFromRes(name) {
 	return cached;
 }
 //#endregion
-//#region src/internal/utilities/default-export-name.ts
-/**
-* Regex helpers for inspecting a module's default export by source text.
-*
-* These operate on raw source strings (not the AST) so they can be shared by
-* both prepass and transform-step layers without import-graph coupling.
-*/
-/**
-* Returns the local name of a PascalCase default export, supporting both
-* `export default Name` and `export { Name as default }` forms. Returns
-* `undefined` when no PascalCase default export is found.
-*/
-function findDefaultExportedLocalName(source) {
-	return source.match(/\bexport\s+default\s+([A-Z][A-Za-z0-9]*)\b/)?.[1] ?? source.match(/\bexport\s*\{[^}]*\b([A-Z][A-Za-z0-9]*)\s+as\s+default\b[^}]*\}/)?.[1];
-}
-//#endregion
 //#region src/internal/prepass/prepass-parser.ts
 /**
 * Shared babel parser for prepass modules.
@@ -538,6 +575,309 @@ const FLOW_PLUGINS = [
 	"throwExpressions"
 ];
 //#endregion
+//#region src/internal/utilities/collection-utils.ts
+/** Add a value to a Set stored in a Map, creating the Set if it doesn't exist. */
+function addToSetMap(map, key, value) {
+	let set = map.get(key);
+	if (!set) {
+		set = /* @__PURE__ */ new Set();
+		map.set(key, set);
+	}
+	set.add(value);
+}
+//#endregion
+//#region src/internal/prepass/scan-cross-file-selectors.ts
+/**
+* Pre-filter: matches any bare `${Identifier}` template expression.
+* Used to skip files that only contain arrow functions or member expressions
+* in template literals (e.g. `${props => ...}`, `${theme.color}`).
+*/
+const BARE_TEMPLATE_IDENTIFIER_RE = /\$\{\s*[a-zA-Z_$][\w$]*\s*\}/;
+/**
+* Categorize cross-file selector usages into marker sidecar and global selector bridge maps.
+*
+* Bridge usages (from already-converted files) are skipped — the consumer handles marker
+* generation via the forward selector handler, so no sidecar/bridge is needed on the target.
+*/
+function categorizeSelectorUsages(usages, componentsNeedingMarkerSidecar, componentsNeedingGlobalSelectorBridge) {
+	for (const usage of usages) {
+		if (usage.bridgeComponentName) continue;
+		if (usage.consumerIsTransformed) addToSetMap(componentsNeedingMarkerSidecar, usage.resolvedPath, usage.importedName);
+		addToSetMap(componentsNeedingGlobalSelectorBridge, usage.resolvedPath, usage.importedName);
+	}
+}
+/**
+* Regex matching bridge GlobalSelector export patterns (global for matchAll).
+* Matches both:
+*   - Old format: `export const XGlobalSelector = ".sc2sx-..."`
+*   - New format: `` export const XGlobalSelector = `.${xBridgeClass}` ``
+*/
+const BRIDGE_EXPORT_RE = /export\s+const\s+(\w+GlobalSelector)\s*=\s*(?:["']\.sc2sx-|`\.\$\{)/g;
+/**
+* Detect whether an imported name is a bridge GlobalSelector from an
+* already-converted StyleX file.
+*
+* Detection criteria (hybrid fast + safe):
+* 1. Variable name ends with "GlobalSelector" AND the stripped name starts uppercase
+* 2. Target file contains "@stylexjs/stylex" (string check, no parse)
+* 3. Target file has a matching `export const XGlobalSelector = ".sc2sx-"` pattern
+*
+* @returns The stripped component name (e.g., "CollapseArrowIcon" for
+*   "CollapseArrowIconGlobalSelector"), or null if not a bridge.
+*/
+function detectBridgeGlobalSelector(importedName, resolvedPath, readFile) {
+	if (!importedName.endsWith("GlobalSelector")) return null;
+	const stripped = importedName.slice(0, -14);
+	if (!stripped || !/^[A-Z]/.test(stripped)) return null;
+	const content = readFile(resolvedPath);
+	if (!content || !content.includes("@stylexjs/stylex")) return null;
+	let found = false;
+	for (const m of content.matchAll(BRIDGE_EXPORT_RE)) if (m[1] === importedName) {
+		found = true;
+		break;
+	}
+	if (!found) return null;
+	return stripped;
+}
+/**
+* If `importedName` is a bridge GlobalSelector, populate bridge fields on `usage`
+* and find the corresponding component import from the same source.
+*/
+function applyBridgeFields(usage, importedName, localName, resolvedPath, importMap, readFile) {
+	const bridgeName = detectBridgeGlobalSelector(importedName, resolvedPath, readFile);
+	if (!bridgeName) return;
+	usage.bridgeComponentName = bridgeName;
+	const imp = importMap.get(localName);
+	if (!imp) return;
+	let defaultImportLocal;
+	for (const [otherLocal, otherImp] of importMap) {
+		if (otherImp.source !== imp.source || otherLocal === localName) continue;
+		if (otherImp.importedName === bridgeName) {
+			usage.bridgeComponentLocalName = otherLocal;
+			defaultImportLocal = void 0;
+			break;
+		}
+		if (otherImp.importedName === "default" && defaultImportLocal === void 0) defaultImportLocal = otherLocal;
+	}
+	if (defaultImportLocal !== void 0) usage.bridgeComponentLocalName = defaultImportLocal;
+}
+/** Global version for matchAll/replace operations */
+const PLACEHOLDER_RE_G = new RegExp(PLACEHOLDER_RE.source, "g");
+/**
+* Walk the AST collecting ImportDeclaration and TaggedTemplateExpression nodes.
+*
+* Uses a targeted recursive walk — only descends into node types that can
+* contain these targets (skips type annotations, comments, etc.).
+*/
+function walkForImportsAndTemplates(node, imports, templates) {
+	if (!node || typeof node !== "object") return;
+	const n = node;
+	if (n.type === "ImportDeclaration") {
+		imports.push(n);
+		return;
+	}
+	if (n.type === "TaggedTemplateExpression") templates.push(n);
+	for (const key of Object.keys(n)) {
+		if (key === "type" || key === "start" || key === "end" || key === "loc") continue;
+		const val = n[key];
+		if (Array.isArray(val)) for (const child of val) walkForImportsAndTemplates(child, imports, templates);
+		else if (val && typeof val === "object" && val.type) walkForImportsAndTemplates(val, imports, templates);
+	}
+}
+/** Build a map of localName → import info from raw ImportDeclaration nodes. */
+function buildImportMapFromNodes(importNodes) {
+	const map = /* @__PURE__ */ new Map();
+	for (const node of importNodes) {
+		const sourceValue = node.source?.value;
+		if (typeof sourceValue !== "string") continue;
+		const specifiers = node.specifiers;
+		if (!specifiers) continue;
+		for (const spec of specifiers) {
+			const localName = getNodeName(spec.local);
+			if (!localName) continue;
+			if (spec.type === "ImportDefaultSpecifier") map.set(localName, {
+				source: sourceValue,
+				importedName: "default"
+			});
+			else if (spec.type === "ImportNamespaceSpecifier") map.set(localName, {
+				source: sourceValue,
+				importedName: "*"
+			});
+			else if (spec.type === "ImportSpecifier") {
+				const importedName = getNodeName(spec.imported) ?? localName;
+				map.set(localName, {
+					source: sourceValue,
+					importedName
+				});
+			}
+		}
+	}
+	return map;
+}
+/**
+* Local identifiers that refer to `styled` from `"styled-components"` (default and/or
+* `import { styled }` / `import { styled as sc }`).
+*/
+function collectStyledLocalBindingNames(importNodes) {
+	const names = /* @__PURE__ */ new Set();
+	for (const node of importNodes) {
+		if (node.source?.value !== "styled-components") continue;
+		const specifiers = node.specifiers;
+		if (!specifiers) continue;
+		for (const spec of specifiers) if (spec.type === "ImportDefaultSpecifier") {
+			const name = getNodeName(spec.local);
+			if (name) names.add(name);
+		} else if (spec.type === "ImportSpecifier") {
+			if (getNodeName(spec.imported) === "styled") {
+				const localName = getNodeName(spec.local);
+				if (localName) names.add(localName);
+			}
+		}
+	}
+	return names;
+}
+/** Find the local name for the styled-components default import. */
+function findStyledImportNameFromNodes(importNodes) {
+	let namedStyledLocal;
+	for (const node of importNodes) {
+		if (node.source?.value !== "styled-components") continue;
+		const specifiers = node.specifiers;
+		if (!specifiers) continue;
+		for (const spec of specifiers) if (spec.type === "ImportDefaultSpecifier") {
+			const name = getNodeName(spec.local);
+			if (name) return name;
+		} else if (spec.type === "ImportSpecifier") {
+			if (getNodeName(spec.imported) === "styled") {
+				const localName = getNodeName(spec.local);
+				if (localName) namedStyledLocal = localName;
+			}
+		}
+	}
+	return namedStyledLocal;
+}
+/**
+* Find local names of `css` imported from styled-components.
+* Handles aliased imports like `import { css as sc } from "styled-components"`.
+*/
+function findCssImportNamesFromNodes(importNodes) {
+	const names = /* @__PURE__ */ new Set();
+	for (const node of importNodes) {
+		if (node.source?.value !== "styled-components") continue;
+		const specifiers = node.specifiers;
+		if (!specifiers) continue;
+		for (const spec of specifiers) if (spec.type === "ImportSpecifier") {
+			if (getNodeName(spec.imported) === "css") {
+				const localName = getNodeName(spec.local);
+				if (localName) names.add(localName);
+			}
+		}
+	}
+	return names;
+}
+/**
+* Find local names of imported components used as selectors inside
+* styled-components template literals (both `styled` and `css` tagged templates).
+*/
+function findComponentSelectorLocalsFromNodes(templateNodes, styledImportName, cssImportNames) {
+	const selectorLocals = /* @__PURE__ */ new Set();
+	for (const node of templateNodes) {
+		if (!isStyledTag(node.tag, styledImportName) && !isCssTag(node.tag, cssImportNames)) continue;
+		const quasi = node.quasi;
+		if (!quasi) continue;
+		const quasis = quasi.quasis;
+		const expressions = quasi.expressions;
+		if (!quasis || !expressions) continue;
+		const rawParts = [];
+		for (let i = 0; i < quasis.length; i++) {
+			const value = quasis[i]?.value;
+			rawParts.push(value?.raw ?? "");
+			if (i < expressions.length) rawParts.push(`__SC_EXPR_${i}__`);
+		}
+		const rawCss = rawParts.join("");
+		for (const match of rawCss.matchAll(PLACEHOLDER_RE_G)) {
+			const exprIndex = Number(match[1]);
+			const pos = match.index;
+			if (isTemplatePlaceholderInSelectorContext(rawCss, pos, match[0].length)) {
+				const expr = expressions[exprIndex];
+				if (expr?.type === "Identifier" && typeof expr.name === "string") selectorLocals.add(expr.name);
+			}
+		}
+	}
+	return selectorLocals;
+}
+/**
+* Check whether a styled-components tag expression is a styled call.
+* Matches: styled.div, styled(X), styled.div.attrs(...), styled(X).withConfig(...), etc.
+*/
+function isStyledTag(tag, styledName) {
+	if (!tag || typeof tag !== "object") return false;
+	if (tag.type === "MemberExpression") {
+		const obj = tag.object;
+		if (obj?.type === "Identifier" && obj.name === styledName) return true;
+	}
+	if (tag.type === "CallExpression") {
+		const callee = tag.callee;
+		if (callee?.type === "Identifier" && callee.name === styledName) return true;
+		if (callee?.type === "MemberExpression" && callee.object) return isStyledTag(callee.object, styledName);
+	}
+	return false;
+}
+/** Check if a template tag is the `css` helper from styled-components. */
+function isCssTag(tag, cssImportNames) {
+	if (!tag || !cssImportNames || cssImportNames.size === 0) return false;
+	return tag.type === "Identifier" && typeof tag.name === "string" && cssImportNames.has(tag.name);
+}
+/**
+* Build the shared `DEBUG_CODEMOD` report lines for cross-file prepass info.
+* `header` distinguishes the standalone scan from the unified prepass; callers
+* may append their own sections before writing.
+*/
+function buildCrossFileDebugLines(header, scannedFiles, info) {
+	const cwd = process.cwd();
+	const rel = (p) => relative(cwd, p);
+	const lines = [header];
+	lines.push(`  Scanned ${scannedFiles.length} file(s)`);
+	if (info.selectorUsages.size === 0) lines.push("  No cross-file selector usages found.");
+	else {
+		lines.push(`  Found cross-file selector usages in ${info.selectorUsages.size} file(s):`);
+		for (const [consumer, usages] of info.selectorUsages) for (const u of usages) lines.push(`    ${rel(consumer)} → ${u.importedName} (from ${rel(u.resolvedPath)}, transformed=${u.consumerIsTransformed})`);
+	}
+	if (info.componentsNeedingMarkerSidecar.size > 0) {
+		lines.push("  Components needing marker sidecar (both consumer and target transformed):");
+		for (const [file, names] of info.componentsNeedingMarkerSidecar) lines.push(`    ${rel(file)}: ${[...names].join(", ")}`);
+	}
+	if (info.componentsNeedingGlobalSelectorBridge.size > 0) {
+		lines.push("  Components needing global selector bridge className (consumer not transformed):");
+		for (const [file, names] of info.componentsNeedingGlobalSelectorBridge) lines.push(`    ${rel(file)}: ${[...names].join(", ")}`);
+	}
+	return lines;
+}
+/** Safely extract the name string from an AST identifier-like node. */
+function getNodeName(node) {
+	if (!node || typeof node !== "object") return;
+	if (node.type === "Identifier" && typeof node.name === "string") return node.name;
+}
+/** Deduplicate and resolve two file lists into a single array of absolute paths. */
+function deduplicateAndResolve(filesToTransform, consumerPaths) {
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const f of filesToTransform) {
+		const abs = resolve(f);
+		if (!seen.has(abs)) {
+			seen.add(abs);
+			result.push(abs);
+		}
+	}
+	for (const f of consumerPaths) {
+		const abs = resolve(f);
+		if (!seen.has(abs)) {
+			seen.add(abs);
+			result.push(abs);
+		}
+	}
+	return result;
+}
+//#endregion
 //#region src/internal/utilities/ast-walk.ts
 const SKIPPED_KEYS = new Set([
 	"loc",
@@ -563,4 +903,4 @@ function walkAst(root, visitor) {
 	visit(root);
 }
 //#endregion
-export { fileImportsFrom as a, resolveBarrelReExport as c, Logger as d, PARTIAL_MIGRATION_INCOMPLETE_WARNING as f, fileExports as i, resolveBarrelReExportBinding as l, createPrepassParser as n, findImportSource as o, UNSUPPORTED_SHOULD_FORWARD_PROP_WARNING as p, findDefaultExportedLocalName as r, getReExportedSourceName as s, walkAst as t, CASCADE_CONFLICT_WARNING as u };
+export { PARTIAL_MIGRATION_INCOMPLETE_WARNING as C, createAstSafeJsonReplacer as D, assertNoNullNodesInArrays as E, Logger as S, getCascadeDependedFilePath as T, findImportSource as _, buildImportMapFromNodes as a, resolveBarrelReExportBinding as b, deduplicateAndResolve as c, findStyledImportNameFromNodes as d, walkForImportsAndTemplates as f, fileImportsFrom as g, fileExports as h, buildCrossFileDebugLines as i, findComponentSelectorLocalsFromNodes as l, createPrepassParser as m, BARE_TEMPLATE_IDENTIFIER_RE as n, categorizeSelectorUsages as o, addToSetMap as p, applyBridgeFields as r, collectStyledLocalBindingNames as s, walkAst as t, findCssImportNamesFromNodes as u, getReExportedSourceName as v, UNSUPPORTED_SHOULD_FORWARD_PROP_WARNING as w, CASCADE_CONFLICT_WARNING as x, resolveBarrelReExport as y };

package/dist/{bridge-consumer-patcher-DDcYZM_G.mjs → bridge-consumer-patcher-jeeDUlId.mjs}

@@ -1,6 +1,6 @@
+import { t as isSelectorContext } from "./selector-context-heuristic-Dptd93Xe.mjs";
 import { r as toRealPath } from "./path-utils-BC4U8X_q.mjs";
 import { r as escapeRegex } from "./string-utils-Bo3cWgss.mjs";
-import { t as isSelectorContext } from "./selector-context-heuristic-LVizWWOR.mjs";
 import { readFileSync } from "node:fs";
 //#region src/internal/bridge-consumer-patcher.ts
 /**

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as CollectedWarning, c as MarkerFileContext, l as defineAdapter, n as TransformMode, o as AdapterInput, s as ImportSource } from "./transform-types-BGGNjb8R.mjs";
+import { a as ImportSource, i as AdapterInput, o as MarkerFileContext, s as defineAdapter, t as CollectedWarning } from "./logger-ByYsVkrB.mjs";
 
 //#region src/run.d.ts
 interface RunTransformOptions {
@@ -64,21 +64,11 @@ interface RunTransformOptions {
    */
   maxExamples?: number;
   /**
-   * Suppress jscodeshift runner output.
+   * Suppress console output: both the per-file runner messages and the final
+   * warning summary report. Warnings are still collected and returned.
    * @default false
    */
   silent?: boolean;
-  /**
-   * Controls which styled declarations are eligible for conversion.
-   *
-   * - `"all"` converts every supported styled declaration.
-   * - `"leavesOnly"` only converts declarations whose render base is intrinsic
-   *   after adapter resolution, or that wrap another leaf styled declaration in
-   *   the transform run (including cross-file imports).
-   *
-   * @default "all"
-   */
-  transformMode?: TransformMode;
   /**
    * When true, allow the codemod to leave individual styled declarations as-is when
    * they hit an unsupported pattern while transforming the rest of the file. This
@@ -99,6 +89,13 @@ interface RunTransformOptions {
    * @default false
    */
   collectStandaloneFileResults?: boolean;
+  /**
+   * Absolute paths of files to treat as already converted to StyleX, even though
+   * they are not. Cascade-conflict checks then "see past" these files so a
+   * consumer's own unsupported patterns surface instead of being masked by the
+   * cascade bail. Intended for analysis-only/dry runs (e.g. the migration plan).
+   */
+  assumeConvertedFiles?: string[];
 }
 interface RunTransformResult {
   /** Number of files that had errors */
@@ -113,6 +110,8 @@ interface RunTransformResult {
   timeElapsed: number;
   /** Warnings emitted during transformation */
   warnings: CollectedWarning[];
+  /** Per-file outcomes from the dependency-ordered run. */
+  fileResults: TransformFileResult[];
   /** Per-file outcomes from isolated transforms, populated when requested. */
   standaloneFileResults?: TransformFileResult[];
   /** Warnings from isolated transforms, populated when requested. */
@@ -162,4 +161,83 @@ type TransformFileResult = {
   status: "error" | "skipped" | "unchanged" | "transformed";
 };
 //#endregion
-export { type AdapterInput, type ImportSource, type MarkerFileContext, defineAdapter, runTransform };
+//#region src/migration-plan.d.ts
+interface MigrationPlanOptions {
+  /** Glob pattern(s) for the files the codemod would transform. */
+  files: string | string[];
+  /** Glob pattern(s) of additional files to scan for consumers, or `null`. */
+  consumerPaths: string | string[] | null;
+  /** Adapter for the transform (same adapter you would pass to `runTransform`). */
+  adapter: AdapterInput;
+  /** jscodeshift parser to use. @default "tsx" */
+  parser?: "babel" | "babylon" | "flow" | "ts" | "tsx";
+  /**
+   * Safety cap on fixpoint analysis passes used to reveal cascade-masked
+   * blockers. Analysis throws if it doesn't stabilize within this many passes
+   * (rather than returning a partial plan). @default 50
+   */
+  maxAnalysisPasses?: number;
+}
+interface ImportedExportUsage {
+  /** Exported name consumers import (`"default"` for a default import, `"*"` for a namespace). */
+  exportName: string;
+  /** Number of distinct files importing this export. */
+  consumerCount: number;
+}
+interface ManualConversionReason {
+  /** The bail message explaining why the codemod cannot convert the file. */
+  message: string;
+  /** Source locations where the unsupported pattern occurs. */
+  locations: Array<{
+    filePath: string;
+    line: number;
+    column: number;
+  }>;
+}
+interface ManualConversionFile {
+  /** Path of the file that must be converted by hand. */
+  filePath: string;
+  /** 1-based position in the recommended bottom-up conversion order. */
+  order: number;
+  /** Number of distinct files that import from this file. */
+  consumerCount: number;
+  /**
+   * Number of files that auto-convert once this file is converted, because this
+   * file is their ONLY remaining blocker (single cascade blocker, no unsupported
+   * patterns of their own). Converting this file is sufficient for these.
+   */
+  soleBlockerFileCount: number;
+  /**
+   * Number of files that cascade-bail on this file (raw chain involvement).
+   * Includes files that also have other blockers, so converting this file alone
+   * does not necessarily unblock all of them. Always ≥ `soleBlockerFileCount`.
+   */
+  blockedFileCount: number;
+  /** Which exports consumers import, so you know what to convert first. */
+  importedExports: ImportedExportUsage[];
+  /** Why the codemod cannot convert this file automatically. */
+  reasons: ManualConversionReason[];
+  /** Other files in this plan that this file imports (must be converted first). */
+  dependsOn: string[];
+}
+interface MigrationPlan {
+  /** Files to convert by hand, ordered by unblock impact (dependencies first). */
+  manualConversionFiles: ManualConversionFile[];
+  /** Total number of files matched by the `files` glob. */
+  totalFiles: number;
+  /**
+   * Number of distinct files that auto-convert once ALL listed files are
+   * converted (cascade-blocked files that have no unsupported patterns of their
+   * own). This is the whole-plan payoff, not attributable to any single file.
+   */
+  unlocksFileCount: number;
+}
+/**
+ * Run the codemod in analysis-only (dry) mode and compute the ordered list of
+ * files that block the rest of the migration and must be converted manually.
+ */
+declare function analyzeMigrationPlan(options: MigrationPlanOptions): Promise<MigrationPlan>;
+/** Render a {@link MigrationPlan} as a human-readable, actionable report. */
+declare function formatMigrationPlan(plan: MigrationPlan): string;
+//#endregion
+export { type AdapterInput, type ImportSource, type ImportedExportUsage, type ManualConversionFile, type ManualConversionReason, type MarkerFileContext, type MigrationPlan, type MigrationPlanOptions, analyzeMigrationPlan, defineAdapter, formatMigrationPlan, runTransform };