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

package/dist/index.mjs

@@ -1,13 +1,173 @@
-import { $ as describeValue, Q as assertValidAdapterInput, Y as defineAdapter, q as mergeMarkerDeclarations, t as transformedComponentAcceptsSx, x as identifierName } from "./sx-surface-Cth8EesU.mjs";
-import { c as resolveBarrelReExport, d as Logger, n as createPrepassParser, t as walkAst } from "./ast-walk-C226poBl.mjs";
-import { r as extractStyledDefBasesFromSource } from "./compute-leaf-set-Cu4lMMQ9.mjs";
+import { t as createModuleResolver } from "./resolve-imports-DgSAddIF.mjs";
+import { $ as assertValidAdapterInput, J as mergeMarkerDeclarations, X as defineAdapter, et as describeValue, t as transformedComponentAcceptsSx, x as identifierName } from "./sx-surface-Kv8zK8L4.mjs";
+import { S as Logger, T as getCascadeDependedFilePath, a as buildImportMapFromNodes, b as resolveBarrelReExportBinding, f as walkForImportsAndTemplates, m as createPrepassParser, s as collectStyledLocalBindingNames, t as walkAst, y as resolveBarrelReExport } from "./ast-walk-DVmYZ2mK.mjs";
 import { r as toRealPath } from "./path-utils-BC4U8X_q.mjs";
 import jscodeshift from "jscodeshift";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { glob, readFile, writeFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
+//#region src/internal/prepass/styled-def-bases.ts
+/**
+* Extracts styled-component definition bases for prepass consumers that need
+* component names and their root shape.
+*/
+const RX_EXPORT_DECL = String.raw`(?:export\s+)?(?:const|let|var)\s+`;
+/** `const Name = styled.tag` — intrinsic HTML/SVG tag member. */
+const STYLED_INTRINSIC_MEMBER_RE = new RegExp(String.raw`\b${RX_EXPORT_DECL}([A-Z][A-Za-z0-9]*)\b[^=]*=\s*styled\.([a-z][a-zA-Z0-9]*)\b`, "g");
+/** `const Name = styled("tag")` — intrinsic string tag. */
+const STYLED_INTRINSIC_STRING_RE = new RegExp(String.raw`\b${RX_EXPORT_DECL}([A-Z][A-Za-z0-9]*)\b[^=]*=\s*styled\s*\(\s*["']([^"']+)["']`, "g");
+/** `const Name = styled(Component)` — wraps another component identifier. */
+const STYLED_COMPONENT_RE = new RegExp(String.raw`\b${RX_EXPORT_DECL}([A-Z][A-Za-z0-9]*)\b[^=]*=\s*styled\s*\(\s*([A-Z][A-Za-z0-9]*)\s*\)`, "g");
+/**
+* Regex-derived styled definition bases for files in the transform set.
+* Later entries for the same component name overwrite earlier ones (rare).
+*/
+function extractStyledDefBasesFromSource(filePath, source, into) {
+	let map = into.get(filePath);
+	if (!map) {
+		map = /* @__PURE__ */ new Map();
+		into.set(filePath, map);
+	}
+	STYLED_INTRINSIC_MEMBER_RE.lastIndex = 0;
+	for (const m of source.matchAll(STYLED_INTRINSIC_MEMBER_RE)) {
+		const name = m[1];
+		if (name) map.set(name, { kind: "intrinsic" });
+	}
+	STYLED_INTRINSIC_STRING_RE.lastIndex = 0;
+	for (const m of source.matchAll(STYLED_INTRINSIC_STRING_RE)) {
+		const name = m[1];
+		if (name) map.set(name, { kind: "intrinsic" });
+	}
+	STYLED_COMPONENT_RE.lastIndex = 0;
+	for (const m of source.matchAll(STYLED_COMPONENT_RE)) {
+		const name = m[1];
+		const ident = m[2];
+		if (name && ident) map.set(name, {
+			kind: "component",
+			ident
+		});
+	}
+}
+/**
+* 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.
+*/
+function extractStyledDefBasesFromAstProgram(filePath, program, styledLocalNames, into) {
+	if (styledLocalNames.size === 0) return;
+	let map = into.get(filePath);
+	if (!map) {
+		map = /* @__PURE__ */ new Map();
+		into.set(filePath, map);
+	}
+	const body = program.body;
+	if (!body) return;
+	for (const stmt of body) walkStatement(stmt);
+	function walkStatement(stmt) {
+		if (stmt.type === "VariableDeclaration") {
+			for (const d of stmt.declarations ?? []) processDeclarator(d);
+			return;
+		}
+		if (stmt.type === "ExportNamedDeclaration" && stmt.declaration) walkStatement(stmt.declaration);
+	}
+	function processDeclarator(decl) {
+		if (decl.type !== "VariableDeclarator") return;
+		const id = decl.id;
+		if (id.type !== "Identifier" || typeof id.name !== "string") return;
+		const tpl = findTaggedTemplate(unwrapInitializer(decl.init));
+		if (!tpl || tpl.type !== "TaggedTemplateExpression") return;
+		const base = classifyStyledTemplateTag(tpl.tag, styledLocalNames);
+		if (base) map.set(id.name, base);
+	}
+}
+function unwrapInitializer(node) {
+	let cur = node ?? void 0;
+	while (cur) {
+		if (cur.type === "TSAsExpression" || cur.type === "AsExpression") {
+			cur = cur.expression;
+			continue;
+		}
+		if (cur.type === "ParenthesizedExpression") {
+			cur = cur.expression;
+			continue;
+		}
+		return cur;
+	}
+}
+function findTaggedTemplate(node) {
+	const n = unwrapInitializer(node);
+	if (!n) return;
+	if (n.type === "TaggedTemplateExpression") return n;
+}
+/** Peel `.attrs` / `.withConfig` / nested calls down to `styled.div` or `styled(X)`. */
+function peelStyledApplication(tag, styledNames) {
+	let cur = tag;
+	while (cur) {
+		if (cur.type === "CallExpression") {
+			const callee = cur.callee;
+			if (callee?.type === "MemberExpression") {
+				cur = callee;
+				continue;
+			}
+			if (callee?.type === "Identifier" && typeof callee.name === "string" && styledNames.has(callee.name)) return cur;
+			return null;
+		}
+		if (cur.type === "MemberExpression") {
+			const obj = cur.object;
+			if (obj?.type === "Identifier" && typeof obj.name === "string" && styledNames.has(obj.name)) return cur;
+			cur = obj;
+			continue;
+		}
+		break;
+	}
+	return null;
+}
+function classifyStyledTemplateTag(tag, styledNames) {
+	const root = peelStyledApplication(tag, styledNames);
+	if (!root) return null;
+	if (root.type === "MemberExpression") {
+		const obj = root.object;
+		const prop = root.property;
+		const objName = obj?.type === "Identifier" ? obj.name : void 0;
+		if (obj?.type !== "Identifier" || typeof objName !== "string" || !styledNames.has(objName)) return null;
+		const isComputed = Boolean(root.computed);
+		if (isComputed && prop?.type === "StringLiteral" && typeof prop.value === "string") return { kind: "intrinsic" };
+		if (!isComputed && prop?.type === "Identifier" && typeof prop.name === "string") return { kind: "intrinsic" };
+		return null;
+	}
+	if (root.type === "CallExpression") {
+		const callee = root.callee;
+		const arg0 = root.arguments?.[0];
+		const calleeName = callee?.type === "Identifier" ? callee.name : void 0;
+		if (callee?.type !== "Identifier" || typeof calleeName !== "string" || !styledNames.has(calleeName) || !arg0) return null;
+		if (arg0.type === "Identifier" && typeof arg0.name === "string") return {
+			kind: "component",
+			ident: arg0.name
+		};
+		if (arg0.type === "StringLiteral" && typeof arg0.value === "string") return { kind: "intrinsic" };
+		return null;
+	}
+	return null;
+}
+//#endregion
 //#region src/internal/prepass/resolve-static-members.ts
 /**
 * Resolves the underlying component name(s) a static member access like `Select.Option` refers to,
@@ -24,7 +184,7 @@ import { spawn } from "node:child_process";
 * behavior so downstream metadata lookups still have something to try).
 */
 function resolveStaticMemberComponentNames(source, rootNames, memberPath, parserName = "tsx") {
-	const program = parseProgram(source, parserName);
+	const program = parseProgram$1(source, parserName);
 	const fallbackMember = memberPath[memberPath.length - 1];
 	const fallback = fallbackMember ? [fallbackMember] : [];
 	if (!program) return [...new Set([...rootNames, ...fallback])];
@@ -39,7 +199,7 @@ function resolveStaticMemberComponentNames(source, rootNames, memberPath, parser
 	return [...new Set([...owners, ...fallback])];
 }
 const programCache = /* @__PURE__ */ new Map();
-function parseProgram(source, parserName) {
+function parseProgram$1(source, parserName) {
 	const cached = programCache.get(source);
 	if (cached !== void 0) return cached;
 	const parsed = tryParse(source, parserName);
@@ -167,6 +327,12 @@ function capitalizedIdentifierName(node) {
 * Core concepts: jscodeshift execution, globs, and adapter hooks.
 */
 const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Expand glob pattern(s) into file paths relative to `cwd`. */
+async function expandGlobFiles(patterns, cwd) {
+	const filePaths = [];
+	for (const pattern of patterns) for await (const file of glob(pattern, { cwd })) filePaths.push(file);
+	return filePaths;
+}
 /**
 * Run the styled-components to StyleX transform on files matching the glob pattern.
 *
@@ -241,13 +407,11 @@ async function runTransform(options) {
 		"Example: consumerPaths: \"src/**/*.tsx\"  // scan for cross-file usage",
 		"Example: consumerPaths: null             // opt out"
 	].join("\n"));
-	const transformModeRaw = options.transformMode;
-	if (transformModeRaw !== void 0 && transformModeRaw !== "all" && transformModeRaw !== "leavesOnly") throw new Error(["runTransform(options): `transformMode` must be one of: \"all\", \"leavesOnly\".", `Received: transformMode=${describeValue(transformModeRaw)}`].join("\n"));
-	const leavesOnly = options.transformMode === "leavesOnly";
 	const { files, consumerPaths: consumerPathsOption, dryRun = false, print = false, parser = "tsx", formatterCommands, maxExamples } = options;
 	if (maxExamples !== void 0) Logger.setMaxExamples(maxExamples);
 	const adapterInput = options.adapter;
 	assertValidAdapterInput(adapterInput, "runTransform(options)");
+	if ((options.assumeConvertedFiles?.length ?? 0) > 0 && !dryRun) throw new Error("runTransform(options): `assumeConvertedFiles` is only supported with `dryRun: true` (it is used by the migration planner's analysis passes). Seeding assumed conversions on a writing run would bypass the cascade-conflict safety bail.");
 	if (adapterInput.externalInterface === "auto" && consumerPathsOption === null) throw new Error([
 		"runTransform(options): externalInterface is \"auto\" but consumerPaths is null.",
 		"Auto-detection needs consumer file globs to scan for styled(Component) and as-prop usage.",
@@ -296,9 +460,8 @@ async function runTransform(options) {
 		}
 	};
 	const patterns = Array.isArray(files) ? files : [files];
-	let filePaths = [];
 	const cwd = process.cwd();
-	for (const pattern of patterns) for await (const file of glob(pattern, { cwd })) filePaths.push(file);
+	let filePaths = await expandGlobFiles(patterns, cwd);
 	if (filePaths.length === 0) {
 		Logger.warn("No files matched the provided glob pattern(s)");
 		return {
@@ -307,13 +470,13 @@ async function runTransform(options) {
 			skipped: 0,
 			transformed: 0,
 			timeElapsed: 0,
-			warnings: []
+			warnings: [],
+			fileResults: []
 		};
 	}
 	Logger.setFileCount(filePaths.length);
 	const consumerPatterns = consumerPathsOption ? Array.isArray(consumerPathsOption) ? consumerPathsOption : [consumerPathsOption] : [];
-	const consumerFilePaths = [];
-	for (const pattern of consumerPatterns) for await (const file of glob(pattern, { cwd })) consumerFilePaths.push(file);
+	const consumerFilePaths = await expandGlobFiles(consumerPatterns, cwd);
 	if (consumerPatterns.length > 0 && consumerFilePaths.length === 0) throw new Error([
 		"runTransform(options): consumerPaths matched no files.",
 		`Pattern(s): ${consumerPatterns.join(", ")}`,
@@ -322,7 +485,7 @@ async function runTransform(options) {
 	const { createModuleResolver } = await import("./resolve-imports-DgSAddIF.mjs").then((n) => n.n);
 	const sharedResolver = createModuleResolver();
 	filePaths = orderFilesByLocalImportDependencies(filePaths, sharedResolver, toRealPath);
-	const { runPrepass } = await import("./run-prepass-D3Ti1ryc.mjs");
+	const { runPrepass } = await import("./run-prepass-CGL_ugPB.mjs");
 	const absoluteFiles = filePaths.map((f) => resolve(f));
 	const absoluteConsumers = consumerFilePaths.map((f) => resolve(f));
 	let prepassResult;
@@ -335,9 +498,7 @@ async function runTransform(options) {
 			resolver: sharedResolver,
 			parserName: parser,
 			createExternalInterface: adapterInput.externalInterface === "auto",
-			enableAstCache: true,
-			leavesOnly,
-			resolveBaseComponent: adapterInput.resolveBaseComponent
+			enableAstCache: true
 		});
 		Logger.info(`Prepass: completed in ${formatElapsedSeconds(prepassStartedAt)}s\n`);
 	} catch (err) {
@@ -349,8 +510,7 @@ async function runTransform(options) {
 				componentsNeedingMarkerSidecar: /* @__PURE__ */ new Map(),
 				componentsNeedingGlobalSelectorBridge: /* @__PURE__ */ new Map(),
 				propUsageByFile: /* @__PURE__ */ new Map(),
-				stylexComponentFiles: /* @__PURE__ */ new Map(),
-				globalLeafKeys: leavesOnly ? /* @__PURE__ */ new Set() : void 0
+				stylexComponentFiles: /* @__PURE__ */ new Map()
 			},
 			consumerAnalysis: void 0,
 			forwardedAsConsumers: /* @__PURE__ */ new Map(),
@@ -360,6 +520,21 @@ async function runTransform(options) {
 	const transformedFiles = /* @__PURE__ */ new Set();
 	const transformedComponents = /* @__PURE__ */ new Map();
 	const transformedFileSources = /* @__PURE__ */ new Map();
+	const seedParser = createPrepassParser(parser);
+	for (const assumedFile of options.assumeConvertedFiles ?? []) {
+		const realPath = toRealPath(resolve(assumedFile));
+		transformedFiles.add(realPath);
+		if (!transformedComponents.has(realPath)) {
+			const extracted = /* @__PURE__ */ new Map();
+			let source = "";
+			try {
+				source = readFileSync(realPath, "utf-8");
+				extractStyledDefBases(realPath, source, seedParser, extracted);
+			} catch {}
+			transformedComponents.set(realPath, new Set(extracted.get(realPath)?.keys() ?? []));
+			transformedFileSources.set(realPath, source);
+		}
+	}
 	const crossFilePrepassResult = {
 		...prepassResult.crossFileInfo,
 		transformedFiles,
@@ -400,7 +575,7 @@ async function runTransform(options) {
 				const cached = styledDefinitionNamesByFile.get(realPath);
 				if (cached) return cached;
 				const extracted = /* @__PURE__ */ new Map();
-				extractStyledDefBasesFromSource(realPath, cachedRead(realPath), extracted);
+				extractStyledDefBases(realPath, cachedRead(realPath), seedParser, extracted);
 				const names = new Set(extracted.get(realPath)?.keys() ?? []);
 				styledDefinitionNamesByFile.set(realPath, names);
 				return names;
@@ -495,9 +670,7 @@ async function runTransform(options) {
 		transformedComponents,
 		transformedFileSources,
 		transientPropRenames,
-		allowPartialMigration: options.allowPartialMigration ?? (leavesOnly ? true : false),
-		transformMode: leavesOnly ? "leavesOnly" : options.transformMode ?? "all",
-		globalLeafKeys: crossFilePrepassResult.globalLeafKeys,
+		allowPartialMigration: options.allowPartialMigration ?? false,
 		resolveModule: (fromFile, specifier) => sharedResolver.resolve(resolve(fromFile), specifier),
 		runInBand: true,
 		silent: options.silent ?? false
@@ -548,7 +721,7 @@ async function runTransform(options) {
 	const result = await runTransformSequentially(transformModule, filePaths, runnerOptions);
 	if (sidecarFiles.size > 0 && !dryRun) for (const [sidecarPath, content] of sidecarFiles) await writeFile(sidecarPath, mergeSidecarContent(sidecarPath, content), "utf-8");
 	if (bridgeResults.size > 0 && !dryRun) {
-		const { buildConsumerReplacements, patchConsumerFile } = await import("./bridge-consumer-patcher-DDcYZM_G.mjs");
+		const { buildConsumerReplacements, patchConsumerFile } = await import("./bridge-consumer-patcher-jeeDUlId.mjs");
 		const consumerReplacements = buildConsumerReplacements(crossFilePrepassResult.selectorUsages, bridgeResults, transformedFiles);
 		const patchedFiles = [];
 		for (const [consumerPath, replacements] of consumerReplacements) {
@@ -561,7 +734,7 @@ async function runTransform(options) {
 		if (formatterCommands && patchedFiles.length > 0) await runFormatters(formatterCommands, patchedFiles);
 	}
 	if (prepassResult.forwardedAsConsumers.size > 0 && !dryRun) {
-		const { buildForwardedAsReplacements, patchConsumerForwardedAs } = await import("./forwarded-as-consumer-patcher-Bva_36Gy.mjs");
+		const { buildForwardedAsReplacements, patchConsumerForwardedAs } = await import("./forwarded-as-consumer-patcher-Do4PI4Qs.mjs");
 		const forwardedAsReplacements = buildForwardedAsReplacements(prepassResult.forwardedAsConsumers, transformedFiles);
 		const patchedFiles = [];
 		for (const [consumerPath, entries] of forwardedAsReplacements) {
@@ -574,7 +747,7 @@ async function runTransform(options) {
 		if (formatterCommands && patchedFiles.length > 0) await runFormatters(formatterCommands, patchedFiles);
 	}
 	if (transientPropRenames.size > 0 && !dryRun) {
-		const { collectTransientPropPatches } = await import("./transient-prop-consumer-patcher-DSd7uVA6.mjs");
+		const { collectTransientPropPatches } = await import("./transient-prop-consumer-patcher-D-iqO8-T.mjs");
 		const patches = collectTransientPropPatches({
 			transientPropRenames,
 			consumerFilePaths: consumerFilePaths.map((p) => resolve(p)),
@@ -589,7 +762,7 @@ async function runTransform(options) {
 	}
 	if (formatterCommands && formatterCommands.length > 0 && result.ok > 0 && !dryRun) await runFormatters(formatterCommands, filePaths);
 	const report = Logger.createReport();
-	report.print();
+	if (!(options.silent ?? false)) report.print();
 	return {
 		errors: result.error,
 		unchanged: result.nochange,
@@ -597,6 +770,7 @@ async function runTransform(options) {
 		transformed: result.ok,
 		timeElapsed: parseFloat(result.timeElapsed) || 0,
 		warnings: report.getWarnings(),
+		fileResults: result.files,
 		standaloneFileResults: standaloneResult?.files,
 		standaloneWarnings
 	};
@@ -703,16 +877,10 @@ function createStandalonePrepassResult(prepass, filePath, transformedFiles, tran
 		selectorUsages,
 		componentsNeedingMarkerSidecar,
 		componentsNeedingGlobalSelectorBridge,
-		globalLeafKeys: getStandaloneGlobalLeafKeys(prepass.globalLeafKeys, standaloneFile),
 		transformedFiles,
 		transformedComponents
 	};
 }
-function getStandaloneGlobalLeafKeys(globalLeafKeys, standaloneFile) {
-	if (!globalLeafKeys) return;
-	const filePrefix = `${standaloneFile}:`;
-	return new Set([...globalLeafKeys].filter((key) => key.startsWith(filePrefix)));
-}
 function addSetMapEntry(map, key, value) {
 	const values = map.get(key);
 	if (values) {
@@ -837,4 +1005,423 @@ async function runFormatters(commands, files) {
 	}
 }
 //#endregion
-export { defineAdapter, runTransform };
+//#region src/migration-plan.ts
+/**
+* Analysis-only mode: produce an ordered plan of the files that must be
+* converted by hand before the codemod can finish the rest of the migration.
+*
+* Core concepts: genuine blocker detection (files the codemod truly cannot
+* convert, as opposed to files that only bail because a dependency is still
+* styled-components), bottom-up dependency ordering, and consumer/imported-export
+* accounting so each blocker is presented with the impact of converting it.
+*/
+/**
+* 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.
+*/
+async function analyzeMigrationPlan(options) {
+	const cwd = process.cwd();
+	const filePatterns = Array.isArray(options.files) ? options.files : [options.files];
+	const consumerPatterns = options.consumerPaths === null ? [] : Array.isArray(options.consumerPaths) ? options.consumerPaths : [options.consumerPaths];
+	const runFiles = await expandGlobFiles(filePatterns, cwd);
+	const scanFiles = unique([...runFiles, ...await expandGlobFiles(consumerPatterns, cwd)]);
+	const parser = options.parser ?? "tsx";
+	const runFilesNorm = new Set(runFiles.map((file) => norm(file, cwd)));
+	const cascadeUnblocks = collectCascadeUnblocks((await runAnalysisPass(options, parser, [])).warnings, cwd);
+	const externalBlockerSet = new Set([...cascadeUnblocks.keys()].filter((target) => !runFilesNorm.has(target)));
+	const maxPasses = options.maxAnalysisPasses ?? MAX_ANALYSIS_PASSES;
+	const assumedConverted = new Set(externalBlockerSet);
+	let blockerReasons = /* @__PURE__ */ new Map();
+	let stabilized = false;
+	for (let pass = 0; pass < maxPasses; pass++) {
+		const passResult = await runAnalysisPass(options, parser, [...assumedConverted]);
+		blockerReasons = collectGenuineBlockers(passResult.warnings, passResult.fileResults, cwd);
+		const newlyFound = [...blockerReasons.keys()].filter((file) => !assumedConverted.has(file));
+		if (newlyFound.length === 0) {
+			stabilized = true;
+			break;
+		}
+		for (const file of newlyFound) assumedConverted.add(file);
+	}
+	if (!stabilized) throw new Error(`Migration plan analysis did not stabilize within ${maxPasses} passes — the cascade blocker chain is deeper than the analysis cap, so the plan would be incomplete. Raise \`maxAnalysisPasses\` if this is a legitimately deep chain.`);
+	const reachableExternalBlockers = new Set([...externalBlockerSet].filter((target) => (cascadeUnblocks.get(target)?.size ?? 0) > 0));
+	if (blockerReasons.size === 0 && reachableExternalBlockers.size === 0) return {
+		manualConversionFiles: [],
+		totalFiles: runFiles.length,
+		unlocksFileCount: 0
+	};
+	const graph = buildImportGraph(scanFiles, cwd, parser);
+	const displayByNorm = buildDisplayMap(scanFiles, cwd);
+	const blockerSet = new Set([...blockerReasons.keys(), ...reachableExternalBlockers]);
+	const reasonsByBlocker = new Map(blockerReasons);
+	for (const target of reachableExternalBlockers) reasonsByBlocker.set(target, [{
+		message: EXTERNAL_BLOCKER_REASON,
+		locations: []
+	}]);
+	const { consumersByBlocker, depsByBlocker, consumerCountByBlocker, blockedCountByBlocker, soleBlockerCountByBlocker, weightByBlocker } = buildBlockerGraph(blockerSet, graph, cascadeUnblocks);
+	const manualConversionFiles = orderBottomUp([...blockerSet], depsByBlocker, (blocker) => weightByBlocker.get(blocker) ?? 0).map((blocker, index) => {
+		const importedExports = [...(consumersByBlocker.get(blocker) ?? /* @__PURE__ */ new Map()).entries()].map(([exportName, consumers]) => ({
+			exportName,
+			consumerCount: consumers.size
+		})).sort((a, b) => b.consumerCount - a.consumerCount || a.exportName.localeCompare(b.exportName));
+		const dependsOn = [...depsByBlocker.get(blocker) ?? []].map((dep) => displayByNorm.get(dep) ?? relative(cwd, dep)).sort();
+		return {
+			filePath: displayByNorm.get(blocker) ?? relative(cwd, blocker),
+			order: index + 1,
+			consumerCount: consumerCountByBlocker.get(blocker) ?? 0,
+			soleBlockerFileCount: soleBlockerCountByBlocker.get(blocker) ?? 0,
+			blockedFileCount: blockedCountByBlocker.get(blocker) ?? 0,
+			importedExports,
+			reasons: reasonsByBlocker.get(blocker) ?? [],
+			dependsOn
+		};
+	});
+	const unlockedFiles = /* @__PURE__ */ new Set();
+	for (const consumers of cascadeUnblocks.values()) for (const consumer of consumers) if (!blockerSet.has(consumer)) unlockedFiles.add(consumer);
+	return {
+		manualConversionFiles,
+		totalFiles: runFiles.length,
+		unlocksFileCount: unlockedFiles.size
+	};
+}
+/** Render a {@link MigrationPlan} as a human-readable, actionable report. */
+function formatMigrationPlan(plan) {
+	const { manualConversionFiles, totalFiles, unlocksFileCount } = plan;
+	if (manualConversionFiles.length === 0) return `No manual conversion needed — the codemod can convert all ${totalFiles} file(s) in dependency order.`;
+	const focusPaths = collectFocusPaths(manualConversionFiles);
+	const priority = manualConversionFiles.filter((file) => focusPaths.has(file.filePath));
+	const standalone = manualConversionFiles.filter((file) => !focusPaths.has(file.filePath));
+	const lines = [];
+	lines.push("Manual conversion plan");
+	lines.push("======================");
+	lines.push(`${manualConversionFiles.length} of ${totalFiles} file(s) need manual conversion.`);
+	if (unlocksFileCount > 0) {
+		lines.push(`Focus on the ${priority.length} file(s) below. Direct payoff: converting all listed blockers lets ${unlocksFileCount} file(s) auto-migrate.`);
+		lines.push(`Per-file "directly unlocks" counts are sole-blocker payoffs; chain context is secondary and may need other blockers or manual fixes too.`);
+	}
+	lines.push("");
+	if (priority.length > 0) {
+		const positionByPath = new Map(priority.map((file, index) => [file.filePath, index + 1]));
+		lines.push("Convert in this order (dependencies first):");
+		lines.push("");
+		priority.forEach((file, index) => appendFileEntry(lines, file, index + 1, positionByPath));
+	}
+	if (standalone.length > 0) {
+		lines.push(`Standalone file(s) — nothing else in the plan depends on these; convert as you reach them (${standalone.length}):`);
+		lines.push("");
+		appendStandaloneSummary(lines, standalone);
+	}
+	return lines.join("\n").trimEnd();
+}
+/**
+* Run one dry analysis pass and return only the warnings it produced. `Logger`
+* is process-global, so snapshot the pre-existing warnings, keep only this run's,
+* and restore the snapshot afterward so analysis never leaks blocker warnings
+* into a later transform in the same process.
+*/
+async function runAnalysisPass(options, parser, assumeConvertedFiles) {
+	const snapshot = Logger.createReport().getWarnings();
+	const priorWarnings = new Set(snapshot);
+	let result;
+	try {
+		result = await runTransform({
+			files: options.files,
+			consumerPaths: options.consumerPaths,
+			adapter: options.adapter,
+			parser,
+			dryRun: true,
+			silent: true,
+			assumeConvertedFiles
+		});
+	} finally {
+		Logger.restoreWarnings(snapshot);
+	}
+	return {
+		warnings: result.warnings.filter((warning) => !priorWarnings.has(warning)),
+		fileResults: result.fileResults
+	};
+}
+/** Attribute consumers, in-plan dependencies, and impact weights to each blocker. */
+function buildBlockerGraph(blockerSet, graph, cascadeUnblocks) {
+	const consumersByBlocker = /* @__PURE__ */ new Map();
+	const depsByBlocker = /* @__PURE__ */ new Map();
+	for (const blocker of blockerSet) {
+		consumersByBlocker.set(blocker, /* @__PURE__ */ new Map());
+		depsByBlocker.set(blocker, /* @__PURE__ */ new Set());
+	}
+	for (const [consumer, edges] of graph) for (const edge of edges) {
+		if (!blockerSet.has(edge.dep) || edge.dep === consumer) continue;
+		addConsumer(consumersByBlocker.get(edge.dep), edge.exportName, consumer);
+		if (blockerSet.has(consumer)) depsByBlocker.get(consumer).add(edge.dep);
+	}
+	const blockersByConsumer = /* @__PURE__ */ new Map();
+	for (const [blocker, consumers] of cascadeUnblocks) for (const consumer of consumers) {
+		const set = blockersByConsumer.get(consumer) ?? /* @__PURE__ */ new Set();
+		set.add(blocker);
+		blockersByConsumer.set(consumer, set);
+	}
+	const consumerCountByBlocker = /* @__PURE__ */ new Map();
+	const blockedCountByBlocker = /* @__PURE__ */ new Map();
+	const soleBlockerCountByBlocker = /* @__PURE__ */ new Map();
+	const weightByBlocker = /* @__PURE__ */ new Map();
+	for (const blocker of blockerSet) {
+		const importers = /* @__PURE__ */ new Set();
+		for (const set of consumersByBlocker.get(blocker).values()) for (const consumer of set) importers.add(consumer);
+		const blocked = [...cascadeUnblocks.get(blocker) ?? []];
+		const soleBlocked = blocked.filter((consumer) => !blockerSet.has(consumer) && (blockersByConsumer.get(consumer)?.size ?? 0) === 1);
+		consumerCountByBlocker.set(blocker, importers.size);
+		blockedCountByBlocker.set(blocker, blocked.length);
+		soleBlockerCountByBlocker.set(blocker, soleBlocked.length);
+		weightByBlocker.set(blocker, soleBlocked.length * 1e6 + blocked.length);
+	}
+	return {
+		consumersByBlocker,
+		depsByBlocker,
+		consumerCountByBlocker,
+		blockedCountByBlocker,
+		soleBlockerCountByBlocker,
+		weightByBlocker
+	};
+}
+/**
+* Files to surface in the ordered focus list: any file that unblocks automatic
+* migration, plus any file involved in an in-plan dependency relationship (it
+* depends on another listed file, or another listed file depends on it). Only
+* fully isolated blockers fall through to the standalone summary, so the ordered
+* list never loses a real dependency chain — even when nothing unlocks a wrapper.
+*/
+function collectFocusPaths(files) {
+	const dependedUpon = /* @__PURE__ */ new Set();
+	for (const file of files) for (const dependency of file.dependsOn) dependedUpon.add(dependency);
+	const focus = /* @__PURE__ */ new Set();
+	for (const file of files) if (file.blockedFileCount > 0 || file.dependsOn.length > 0 || dependedUpon.has(file.filePath)) focus.add(file.filePath);
+	return focus;
+}
+function appendFileEntry(lines, file, position, positionByPath) {
+	lines.push(`${position}. ${file.filePath}`);
+	const impact = [];
+	if (file.blockedFileCount > 0) impact.push(`directly unlocks ${file.soleBlockerFileCount} file(s)`);
+	const chainOnlyFileCount = file.blockedFileCount - file.soleBlockerFileCount;
+	if (chainOnlyFileCount > 0) {
+		const prefix = file.soleBlockerFileCount > 0 ? "also " : "";
+		impact.push(`chain context: ${chainOnlyFileCount} file(s) ${prefix}bail through this file but are not unlocked by it alone`);
+	}
+	if (file.consumerCount > 0) impact.push(`imported by ${file.consumerCount} file(s)`);
+	if (impact.length > 0) lines.push(`   → ${impact.join(" · ")}`);
+	if (file.dependsOn.length > 0) {
+		const deps = file.dependsOn.map((dep) => {
+			const depPosition = positionByPath.get(dep);
+			return depPosition === void 0 ? dep : `#${depPosition} ${dep}`;
+		}).sort();
+		lines.push(`   Requires first: ${deps.join(", ")}`);
+	}
+	if (file.importedExports.length > 0) {
+		const exportList = file.importedExports.map((usage) => `${formatExportName(usage.exportName)} (used by ${usage.consumerCount})`).join(", ");
+		lines.push(`   Convert these exports: ${exportList}`);
+	}
+	lines.push("   Blocked by:");
+	for (const reason of file.reasons) {
+		lines.push(`     • ${reason.message}`);
+		for (const loc of reason.locations.slice(0, MAX_REASON_LOCATIONS)) lines.push(`         ${loc.filePath}:${loc.line}:${loc.column}`);
+		const remaining = reason.locations.length - MAX_REASON_LOCATIONS;
+		if (remaining > 0) lines.push(`         ... and ${remaining} more location(s)`);
+	}
+	lines.push("");
+}
+/** Group standalone blockers by reason so the long tail stays scannable. */
+function appendStandaloneSummary(lines, standalone) {
+	const filesByReason = /* @__PURE__ */ new Map();
+	for (const file of standalone) {
+		const reasonMessage = file.reasons[0]?.message ?? "Unsupported pattern";
+		const files = filesByReason.get(reasonMessage) ?? [];
+		files.push(file.filePath);
+		filesByReason.set(reasonMessage, files);
+	}
+	const grouped = [...filesByReason.entries()].sort((a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0]));
+	for (const [reasonMessage, files] of grouped) {
+		lines.push(`  • ${reasonMessage} (${files.length} file(s))`);
+		for (const filePath of files.slice(0, MAX_STANDALONE_FILES_PER_REASON)) lines.push(`      ${filePath}`);
+		const remaining = files.length - MAX_STANDALONE_FILES_PER_REASON;
+		if (remaining > 0) lines.push(`      ... and ${remaining} more file(s)`);
+	}
+	lines.push("");
+}
+function formatExportName(exportName) {
+	if (exportName === "default") return "default export";
+	if (exportName === "*") return "* (namespace import)";
+	return exportName;
+}
+const MAX_REASON_LOCATIONS = 3;
+const MAX_STANDALONE_FILES_PER_REASON = 5;
+const EXTERNAL_BLOCKER_REASON = "Outside the analyzed files — still uses styled-components and is wrapped by in-scope component(s); convert it or add it to the migration scope first";
+/** Safety cap on fixpoint passes; each pass reveals at least one new blocker until stable. */
+const MAX_ANALYSIS_PASSES = 50;
+/**
+* A file is a genuine blocker when the codemod did not convert it and the reason
+* is something other than a dependency-order cascade conflict (which resolves on
+* its own once the depended-on file is converted), or when it threw outright.
+*/
+function collectGenuineBlockers(warnings, fileResults, cwd) {
+	const reasonsByFile = /* @__PURE__ */ new Map();
+	const ensureReason = (fileNorm, message) => {
+		let reasons = reasonsByFile.get(fileNorm);
+		if (!reasons) {
+			reasons = /* @__PURE__ */ new Map();
+			reasonsByFile.set(fileNorm, reasons);
+		}
+		let reason = reasons.get(message);
+		if (!reason) {
+			reason = {
+				message,
+				locations: []
+			};
+			reasons.set(message, reason);
+		}
+		return reason;
+	};
+	const unconverted = /* @__PURE__ */ new Set();
+	const erroredFiles = /* @__PURE__ */ new Set();
+	for (const fileResult of fileResults) {
+		if (fileResult.status === "skipped" || fileResult.status === "error") unconverted.add(norm(fileResult.filePath, cwd));
+		if (fileResult.status === "error") erroredFiles.add(norm(fileResult.filePath, cwd));
+	}
+	for (const warning of warnings) {
+		if (warning.type === "styled(ImportedComponent) wraps a component whose file uses styled-components — convert the base component's file first to avoid CSS cascade conflicts") continue;
+		const fileNorm = norm(warning.filePath, cwd);
+		if (!unconverted.has(fileNorm)) continue;
+		const reason = ensureReason(fileNorm, warning.type);
+		if (warning.loc) reason.locations.push({
+			filePath: warning.filePath,
+			line: warning.loc.line,
+			column: warning.loc.column
+		});
+	}
+	for (const fileNorm of erroredFiles) ensureReason(fileNorm, "The codemod threw an error while transforming this file");
+	const result = /* @__PURE__ */ new Map();
+	for (const [fileNorm, reasons] of reasonsByFile) result.set(fileNorm, [...reasons.values()]);
+	return result;
+}
+/** Map each blocker file to the set of files that cascade-bail because of it. */
+function collectCascadeUnblocks(warnings, cwd) {
+	const unblocks = /* @__PURE__ */ new Map();
+	for (const warning of warnings) {
+		if (warning.type !== "styled(ImportedComponent) wraps a component whose file uses styled-components — convert the base component's file first to avoid CSS cascade conflicts") continue;
+		const target = getCascadeDependedFilePath(warning);
+		if (!target) continue;
+		const targetNorm = norm(target, cwd);
+		let consumers = unblocks.get(targetNorm);
+		if (!consumers) {
+			consumers = /* @__PURE__ */ new Set();
+			unblocks.set(targetNorm, consumers);
+		}
+		consumers.add(norm(warning.filePath, cwd));
+	}
+	return unblocks;
+}
+/** Build a `consumer -> [{ dep, exportName }]` import graph over all scanned files. */
+function buildImportGraph(scanFiles, cwd, parserName) {
+	const graph = /* @__PURE__ */ new Map();
+	const resolver = createModuleResolver();
+	const parser = createPrepassParser(parserName);
+	const read = (filePath) => {
+		try {
+			return readFileSync(filePath, "utf-8");
+		} catch {
+			return "";
+		}
+	};
+	const resolveForBarrel = (specifier, fromFile) => resolver.resolve(fromFile, specifier) ?? null;
+	for (const relPath of scanFiles) {
+		const absFrom = resolve(cwd, relPath);
+		const source = read(absFrom);
+		if (!source) continue;
+		const program = parseProgram(parser, source);
+		if (!program) continue;
+		const importNodes = [];
+		walkForImportsAndTemplates(program, importNodes, []);
+		const importMap = buildImportMapFromNodes(importNodes.map(stripTypeOnlyImports));
+		const edges = [];
+		for (const entry of importMap.values()) {
+			const resolved = resolver.resolve(absFrom, entry.source);
+			if (!resolved) continue;
+			const resolvedReal = toRealPath(resolved);
+			const binding = resolveBarrelReExportBinding(resolvedReal, entry.importedName, resolveForBarrel, read);
+			const definitionPath = binding?.filePath ?? resolvedReal;
+			const exportName = binding?.exportedName ?? entry.importedName;
+			edges.push({
+				dep: toRealPath(definitionPath),
+				exportName
+			});
+		}
+		graph.set(toRealPath(absFrom), edges);
+	}
+	return graph;
+}
+/** Remove type-only specifiers (or the whole declaration) so only runtime imports remain. */
+function stripTypeOnlyImports(node) {
+	if (isTypeOnlyImportKind(node.importKind)) return {
+		...node,
+		specifiers: []
+	};
+	const specifiers = node.specifiers;
+	if (!specifiers) return node;
+	const valueSpecifiers = specifiers.filter((spec) => !isTypeOnlyImportKind(spec.importKind));
+	return valueSpecifiers.length === specifiers.length ? node : {
+		...node,
+		specifiers: valueSpecifiers
+	};
+}
+function isTypeOnlyImportKind(importKind) {
+	return importKind === "type" || importKind === "typeof";
+}
+function parseProgram(parser, source) {
+	try {
+		const ast = parser.parse(source);
+		return ast.program ?? ast;
+	} catch {
+		return null;
+	}
+}
+/**
+* Topologically order blockers so that dependencies come before the blockers
+* that depend on them (bottom-up). Ties are broken by impact (consumer count)
+* then path for stable output.
+*/
+function orderBottomUp(blockers, depsByBlocker, weight) {
+	const byImpact = (a, b) => weight(b) - weight(a) || a.localeCompare(b);
+	const seeds = [...blockers].sort(byImpact);
+	const ordered = [];
+	const visited = /* @__PURE__ */ new Set();
+	const visiting = /* @__PURE__ */ new Set();
+	const visit = (blocker) => {
+		if (visited.has(blocker) || visiting.has(blocker)) return;
+		visiting.add(blocker);
+		for (const dep of [...depsByBlocker.get(blocker) ?? []].sort(byImpact)) visit(dep);
+		visiting.delete(blocker);
+		visited.add(blocker);
+		ordered.push(blocker);
+	};
+	for (const seed of seeds) visit(seed);
+	return ordered;
+}
+function buildDisplayMap(scanFiles, cwd) {
+	const displayByNorm = /* @__PURE__ */ new Map();
+	for (const relPath of scanFiles) displayByNorm.set(norm(relPath, cwd), relPath);
+	return displayByNorm;
+}
+function addConsumer(exportUsage, exportName, consumer) {
+	let consumers = exportUsage.get(exportName);
+	if (!consumers) {
+		consumers = /* @__PURE__ */ new Set();
+		exportUsage.set(exportName, consumers);
+	}
+	consumers.add(consumer);
+}
+function norm(filePath, cwd) {
+	return toRealPath(resolve(cwd, filePath));
+}
+function unique(values) {
+	return [...new Set(values)];
+}
+//#endregion
+export { analyzeMigrationPlan, defineAdapter, formatMigrationPlan, runTransform };