styled-components-to-stylex-codemod 0.0.54 → 0.0.56

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, how many files it unblocks, and the bail reasons. `formatMigrationPlan` renders it as a report (high-impact files first).
+
+```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-CCXrDCKY.mjs → ast-walk-CLvMH7Lm.mjs}

@@ -1,4 +1,5 @@
-import path from "node:path";
+import { n as isTemplatePlaceholderInSelectorContext, r as PLACEHOLDER_RE } from "./selector-context-heuristic-Dptd93Xe.mjs";
+import path, { resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { parse } from "@babel/parser";
 //#region src/internal/logger.ts
@@ -89,6 +90,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 = [];
@@ -273,14 +282,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));
@@ -522,6 +533,300 @@ 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);
+}
+/** 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/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/utilities/ast-walk.ts
 const SKIPPED_KEYS = new Set([
 	"loc",
@@ -547,4 +852,4 @@ function walkAst(root, visitor) {
 	visit(root);
 }
 //#endregion
-export { findImportSource as a, resolveBarrelReExportBinding as c, PARTIAL_MIGRATION_INCOMPLETE_WARNING as d, UNSUPPORTED_SHOULD_FORWARD_PROP_WARNING as f, fileImportsFrom as i, CASCADE_CONFLICT_WARNING as l, createPrepassParser as n, getReExportedSourceName as o, fileExports as r, resolveBarrelReExport as s, walkAst as t, Logger as u };
+export { PARTIAL_MIGRATION_INCOMPLETE_WARNING as C, 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, applyBridgeFields as i, findComponentSelectorLocalsFromNodes as l, createPrepassParser as m, findDefaultExportedLocalName as n, categorizeSelectorUsages as o, addToSetMap as p, BARE_TEMPLATE_IDENTIFIER_RE 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-B__X3jOg.mjs}

@@ -1,6 +1,6 @@
-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 { t as isSelectorContext } from "./selector-context-heuristic-Dptd93Xe.mjs";
+import { r as toRealPath } from "./path-utils-ByFNVtHo.mjs";
+import { r as escapeRegex } from "./string-utils-4eeXGa48.mjs";
 import { readFileSync } from "node:fs";
 //#region src/internal/bridge-consumer-patcher.ts
 /**

package/dist/{compute-leaf-set-u51kTofH.mjs → compute-leaf-set-D5GvkV-H.mjs}

@@ -1,4 +1,4 @@
-import { a as findImportSource, c as resolveBarrelReExportBinding } from "./ast-walk-CCXrDCKY.mjs";
+import { _ as findImportSource, b as resolveBarrelReExportBinding, f as walkForImportsAndTemplates, n as findDefaultExportedLocalName, s as collectStyledLocalBindingNames } from "./ast-walk-CLvMH7Lm.mjs";
 //#region src/internal/prepass/compute-leaf-set.ts
 /**
 * Computes which styled-component bindings are "leaves" for leaves-only mode:
@@ -44,6 +44,22 @@ function extractStyledDefBasesFromSource(filePath, source, into) {
 	}
 }
 /**
+* Regex baseline for styled defs, then an AST pass overrides/adds rows when the
+* source parses. The AST pass understands aliased/named `styled` imports
+* (`import { styled as sc }`) that the regexes (which assume the literal `styled`)
+* miss, so callers that only ran the regex extractor under-report components.
+*/
+function extractStyledDefBases(filePath, source, parser, into) {
+	extractStyledDefBasesFromSource(filePath, source, into);
+	try {
+		const ast = parser.parse(source);
+		const program = ast.program ?? ast;
+		const importNodes = [];
+		walkForImportsAndTemplates(program, importNodes, []);
+		extractStyledDefBasesFromAstProgram(filePath, program, collectStyledLocalBindingNames(importNodes), into);
+	} catch {}
+}
+/**
 * AST-based extraction: understands `let`/`var`, export blocks, named `styled` imports,
 * and `.attrs` / `.withConfig` chains before the tagged template.
 * Results merge into `into`; bindings found here override regex entries for the same name.
@@ -235,8 +251,5 @@ function leafKeyExists(defFile, exportedName, allowDefaultFallback, cachedRead,
 	const defaultLocalName = findDefaultExportedLocalName(cachedRead(defFile));
 	return defaultLocalName ? globalLeaves.get(defFile)?.has(defaultLocalName) ?? false : false;
 }
-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
-export { extractStyledDefBasesFromAstProgram as n, extractStyledDefBasesFromSource as r, computeGlobalLeafKeys as t };
+export { extractStyledDefBases as n, computeGlobalLeafKeys as t };

package/dist/{forwarded-as-consumer-patcher-Bva_36Gy.mjs → forwarded-as-consumer-patcher-Bs9ymhBa.mjs}

@@ -1,5 +1,5 @@
-import { r as toRealPath } from "./path-utils-BC4U8X_q.mjs";
-import { r as escapeRegex } from "./string-utils-Bo3cWgss.mjs";
+import { r as toRealPath } from "./path-utils-ByFNVtHo.mjs";
+import { r as escapeRegex } from "./string-utils-4eeXGa48.mjs";
 import { readFileSync } from "node:fs";
 //#region src/internal/forwarded-as-consumer-patcher.ts
 /**

package/dist/index.d.mts

@@ -64,7 +64,8 @@ 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;
@@ -99,6 +100,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 +121,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 +172,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 };