@stencil/cli 5.0.0-alpha.2 → 5.0.0-alpha.4

package/dist/index.d.mts

@@ -5,33 +5,33 @@ import { LogLevel } from "@stencil/core/compiler";
 /**
  * Supported CLI task commands
  */
-type TaskCommand = 'build' | 'docs' | 'generate' | 'g' | 'help' | 'info' | 'prerender' | 'serve' | 'telemetry' | 'test' | 'version';
+type TaskCommand = 'build' | 'docs' | 'generate' | 'g' | 'help' | 'info' | 'migrate' | 'prerender' | 'serve' | 'telemetry' | 'test' | 'version';
 //#endregion
 //#region src/config-flags.d.ts
 /**
  * All the Boolean options supported by the Stencil CLI
  */
-declare const BOOLEAN_CLI_FLAGS: readonly ["build", "cache", "checkVersion", "ci", "compare", "debug", "dev", "devtools", "docs", "e2e", "es5", "esm", "help", "log", "open", "prerender", "prerenderExternal", "prod", "profile", "serviceWorker", "screenshot", "serve", "skipNodeCheck", "spec", "ssr", "updateScreenshot", "verbose", "version", "watch", "all", "automock", "bail", "changedFilesWithAncestor", "clearCache", "clearMocks", "collectCoverage", "color", "colors", "coverage", "detectLeaks", "detectOpenHandles", "errorOnDeprecated", "expand", "findRelatedTests", "forceExit", "init", "injectGlobals", "json", "lastCommit", "listTests", "logHeapUsage", "noStackTrace", "notify", "onlyChanged", "onlyFailures", "passWithNoTests", "resetMocks", "resetModules", "restoreMocks", "runInBand", "runTestsByPath", "showConfig", "silent", "skipFilter", "testLocationInResults", "updateSnapshot", "useStderr", "watchAll", "watchman"];
+declare const BOOLEAN_CLI_FLAGS: readonly ["build", "cache", "checkVersion", "ci", "compare", "debug", "dev", "devtools", "docs", "dryRun", "esm", "help", "log", "open", "prerender", "prerenderExternal", "prod", "profile", "serviceWorker", "serve", "skipNodeCheck", "ssr", "verbose", "version", "watch"];
 /**
  * All the Number options supported by the Stencil CLI
  */
-declare const NUMBER_CLI_FLAGS: readonly ["port", "maxConcurrency", "testTimeout"];
+declare const NUMBER_CLI_FLAGS: readonly ["port"];
 /**
  * All the String options supported by the Stencil CLI
  */
-declare const STRING_CLI_FLAGS: readonly ["address", "config", "docsApi", "docsJson", "emulate", "root", "screenshotConnector", "cacheDirectory", "changedSince", "collectCoverageFrom", "coverageDirectory", "coverageThreshold", "env", "filter", "globalSetup", "globalTeardown", "globals", "haste", "moduleNameMapper", "notifyMode", "outputFile", "preset", "prettierPath", "resolver", "rootDir", "runner", "testEnvironment", "testEnvironmentOptions", "testFailureExitCode", "testNamePattern", "testResultsProcessor", "testRunner", "testSequencer", "testURL", "timers", "transform"];
-declare const STRING_ARRAY_CLI_FLAGS: readonly ["collectCoverageOnlyFrom", "coveragePathIgnorePatterns", "coverageReporters", "moduleDirectories", "moduleFileExtensions", "modulePathIgnorePatterns", "modulePaths", "projects", "reporters", "roots", "selectProjects", "setupFiles", "setupFilesAfterEnv", "snapshotSerializers", "testMatch", "testPathIgnorePatterns", "testPathPattern", "testRegex", "transformIgnorePatterns", "unmockedModulePathPatterns", "watchPathIgnorePatterns"];
+declare const STRING_CLI_FLAGS: readonly ["address", "config", "docsApi", "docsJson", "emulate", "root"];
+declare const STRING_ARRAY_CLI_FLAGS: readonly [];
 /**
  * All the CLI arguments which may have string or number values
  *
- * `maxWorkers` is an argument which is used both by Stencil _and_ by Jest,
- * which means that we need to support parsing both string and number values.
+ * `maxWorkers` controls the number of concurrent workers for Stencil builds.
+ * Supports both string (e.g., "50%") and number values.
  */
 declare const STRING_NUMBER_CLI_FLAGS: readonly ["maxWorkers"];
 /**
  * All the CLI arguments which may have boolean or string values.
  */
-declare const BOOLEAN_STRING_CLI_FLAGS: readonly ["headless", "stats"];
+declare const BOOLEAN_STRING_CLI_FLAGS: readonly ["stats"];
 /**
  * All the LogLevel-type options supported by the Stencil CLI
  *

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { LOG_LEVELS } from "@stencil/core/compiler";
 import { buildError, catchError, hasError, isFunction, isOutputTargetDocs, isOutputTargetHydrate, isOutputTargetWww, isString, normalizePath, readOnlyArrayHasStringMember, result, shouldIgnoreError, toCamelCase, validateComponentTag } from "@stencil/core/compiler/utils";
-import { join, parse, relative } from "path";
+import { isAbsolute, join, parse, relative } from "path";
+import ts from "typescript";
 import { start } from "@stencil/dev-server";
 //#region src/config-flags.ts
 /**
@@ -16,8 +17,7 @@ const BOOLEAN_CLI_FLAGS = [
 	"dev",
 	"devtools",
 	"docs",
-	"e2e",
-	"es5",
+	"dryRun",
 	"esm",
 	"help",
 	"log",
@@ -27,64 +27,17 @@ const BOOLEAN_CLI_FLAGS = [
 	"prod",
 	"profile",
 	"serviceWorker",
-	"screenshot",
 	"serve",
 	"skipNodeCheck",
-	"spec",
 	"ssr",
-	"updateScreenshot",
 	"verbose",
 	"version",
-	"watch",
-	"all",
-	"automock",
-	"bail",
-	"changedFilesWithAncestor",
-	"clearCache",
-	"clearMocks",
-	"collectCoverage",
-	"color",
-	"colors",
-	"coverage",
-	"detectLeaks",
-	"detectOpenHandles",
-	"errorOnDeprecated",
-	"expand",
-	"findRelatedTests",
-	"forceExit",
-	"init",
-	"injectGlobals",
-	"json",
-	"lastCommit",
-	"listTests",
-	"logHeapUsage",
-	"noStackTrace",
-	"notify",
-	"onlyChanged",
-	"onlyFailures",
-	"passWithNoTests",
-	"resetMocks",
-	"resetModules",
-	"restoreMocks",
-	"runInBand",
-	"runTestsByPath",
-	"showConfig",
-	"silent",
-	"skipFilter",
-	"testLocationInResults",
-	"updateSnapshot",
-	"useStderr",
-	"watchAll",
-	"watchman"
+	"watch"
 ];
 /**
 * All the Number options supported by the Stencil CLI
 */
-const NUMBER_CLI_FLAGS = [
-	"port",
-	"maxConcurrency",
-	"testTimeout"
-];
+const NUMBER_CLI_FLAGS = ["port"];
 /**
 * All the String options supported by the Stencil CLI
 */
@@ -94,72 +47,20 @@ const STRING_CLI_FLAGS = [
 	"docsApi",
 	"docsJson",
 	"emulate",
-	"root",
-	"screenshotConnector",
-	"cacheDirectory",
-	"changedSince",
-	"collectCoverageFrom",
-	"coverageDirectory",
-	"coverageThreshold",
-	"env",
-	"filter",
-	"globalSetup",
-	"globalTeardown",
-	"globals",
-	"haste",
-	"moduleNameMapper",
-	"notifyMode",
-	"outputFile",
-	"preset",
-	"prettierPath",
-	"resolver",
-	"rootDir",
-	"runner",
-	"testEnvironment",
-	"testEnvironmentOptions",
-	"testFailureExitCode",
-	"testNamePattern",
-	"testResultsProcessor",
-	"testRunner",
-	"testSequencer",
-	"testURL",
-	"timers",
-	"transform"
-];
-const STRING_ARRAY_CLI_FLAGS = [
-	"collectCoverageOnlyFrom",
-	"coveragePathIgnorePatterns",
-	"coverageReporters",
-	"moduleDirectories",
-	"moduleFileExtensions",
-	"modulePathIgnorePatterns",
-	"modulePaths",
-	"projects",
-	"reporters",
-	"roots",
-	"selectProjects",
-	"setupFiles",
-	"setupFilesAfterEnv",
-	"snapshotSerializers",
-	"testMatch",
-	"testPathIgnorePatterns",
-	"testPathPattern",
-	"testRegex",
-	"transformIgnorePatterns",
-	"unmockedModulePathPatterns",
-	"watchPathIgnorePatterns"
+	"root"
 ];
+const STRING_ARRAY_CLI_FLAGS = [];
 /**
 * All the CLI arguments which may have string or number values
 *
-* `maxWorkers` is an argument which is used both by Stencil _and_ by Jest,
-* which means that we need to support parsing both string and number values.
+* `maxWorkers` controls the number of concurrent workers for Stencil builds.
+* Supports both string (e.g., "50%") and number values.
 */
 const STRING_NUMBER_CLI_FLAGS = ["maxWorkers"];
 /**
 * All the CLI arguments which may have boolean or string values.
 */
-const BOOLEAN_STRING_CLI_FLAGS = ["headless", "stats"];
+const BOOLEAN_STRING_CLI_FLAGS = ["stats"];
 /**
 * All the LogLevel-type options supported by the Stencil CLI
 *
@@ -175,21 +76,13 @@ const CLI_FLAG_ALIASES = {
 	c: "config",
 	h: "help",
 	p: "port",
-	v: "version",
-	b: "bail",
-	e: "expand",
-	f: "onlyFailures",
-	i: "runInBand",
-	o: "onlyChanged",
-	t: "testNamePattern",
-	u: "updateSnapshot",
-	w: "maxWorkers"
+	v: "version"
 };
 /**
 * A regular expression which can be used to match a CLI flag for one of our
 * short aliases.
 */
-const CLI_FLAG_REGEX = new RegExp(`^-[chpvbewofitu]{1}$`);
+const CLI_FLAG_REGEX = new RegExp(`^-[chpv]{1}$`);
 /**
 * Helper function for initializing a `ConfigFlags` object. Provide any overrides
 * for default values and off you go!
@@ -354,9 +247,10 @@ const setCLIArg = (flags, rawArg, normalizedArg, value) => {
 		flags.knownArgs.push(rawArg);
 		flags.knownArgs.push(value);
 	} else throwCLIParsingError(rawArg, "expected a string argument but received nothing");
-	else if (readOnlyArrayHasStringMember(STRING_ARRAY_CLI_FLAGS, normalizedArg)) if (typeof value === "string") {
-		if (!Array.isArray(flags[normalizedArg])) flags[normalizedArg] = [];
-		const targetArray = flags[normalizedArg];
+	else if (STRING_ARRAY_CLI_FLAGS.length > 0 && readOnlyArrayHasStringMember(STRING_ARRAY_CLI_FLAGS, normalizedArg)) if (typeof value === "string") {
+		const flagsRecord = flags;
+		if (!Array.isArray(flagsRecord[normalizedArg])) flagsRecord[normalizedArg] = [];
+		const targetArray = flagsRecord[normalizedArg];
 		if (Array.isArray(targetArray)) {
 			targetArray.push(value);
 			flags.knownArgs.push(rawArg);
@@ -657,7 +551,6 @@ const startupCompilerLog = (coreCompiler, config) => {
 	const isDevBuild = coreCompiler.version.includes("-dev.");
 	if (isPrerelease && !isDevBuild) logger.warn(logger.yellow(`This is a prerelease build, undocumented changes might happen at any time. Technical support is not available for prereleases, but any assistance testing is appreciated.`));
 	if (config.devMode && !isDebug) {
-		if (config.buildEs5) logger.warn(`Generating ES5 during development is a very task expensive, initial and incremental builds will be much slower. Drop the '--es5' flag and use a modern browser for development.`);
 		if (!config.enableCache) logger.warn(`Disabling cache during development will slow down incremental builds.`);
 	}
 };
@@ -692,7 +585,6 @@ const mergeFlags = (config, flags) => {
 	if (typeof flags.docsJson === "string") merged.docsJsonPath = flags.docsJson;
 	if (flags.stats) merged.statsJsonPath = flags.stats;
 	if (typeof flags.serviceWorker === "boolean") merged.generateServiceWorker = flags.serviceWorker;
-	if (typeof flags.e2e === "boolean") merged.e2eTests = flags.e2e;
 	if (typeof flags.maxWorkers === "number") merged.maxConcurrentWorkers = flags.maxWorkers;
 	if (typeof flags.address === "string") merged.devServerAddress = flags.address;
 	if (typeof flags.port === "number") merged.devServerPort = flags.port;
@@ -726,6 +618,432 @@ const printCheckVersionResults = async (versionChecker) => {
 	}
 };
 //#endregion
+//#region src/migrations/rules/encapsulation-api.ts
+/**
+* Migration rule for the @Component encapsulation API change.
+*
+* Migrates:
+* - `shadow: true` → `encapsulation: { type: 'shadow' }`
+* - `shadow: { delegatesFocus: true }` → `encapsulation: { type: 'shadow', delegatesFocus: true }`
+* - `scoped: true` → `encapsulation: { type: 'scoped' }`
+*/
+const encapsulationApiRule = {
+	id: "encapsulation-api",
+	name: "Encapsulation API",
+	description: "Migrate shadow/scoped properties to new encapsulation API",
+	fromVersion: "4.x",
+	toVersion: "5.x",
+	detect(sourceFile) {
+		const matches = [];
+		const importMap = getStencilCoreImportMap(sourceFile);
+		const visit = (node) => {
+			if (ts.isDecorator(node) && ts.isCallExpression(node.expression)) {
+				const decoratorName = node.expression.expression;
+				if (ts.isIdentifier(decoratorName) && isStencilDecorator(decoratorName.text, "Component", importMap)) {
+					const [arg] = node.expression.arguments;
+					if (arg && ts.isObjectLiteralExpression(arg)) {
+						for (const prop of arg.properties) if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+							const propName = prop.name.text;
+							if (propName === "shadow" || propName === "scoped") {
+								const { line, character } = sourceFile.getLineAndCharacterOfPosition(prop.getStart());
+								matches.push({
+									node: prop,
+									message: `Deprecated '${propName}' property found - migrate to 'encapsulation' API`,
+									line: line + 1,
+									column: character + 1
+								});
+							}
+						}
+					}
+				}
+			}
+			ts.forEachChild(node, visit);
+		};
+		visit(sourceFile);
+		return matches;
+	},
+	transform(sourceFile, matches) {
+		if (matches.length === 0) return sourceFile.getFullText();
+		let text = sourceFile.getFullText();
+		const sortedMatches = [...matches].sort((a, b) => {
+			const posA = a.node.getStart();
+			return b.node.getStart() - posA;
+		});
+		for (const match of sortedMatches) {
+			const prop = match.node;
+			const propName = prop.name.text;
+			const start = prop.getStart();
+			const end = prop.getEnd();
+			let replacement;
+			if (propName === "shadow") if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) replacement = "encapsulation: { type: 'shadow' }";
+			else if (ts.isObjectLiteralExpression(prop.initializer)) {
+				const options = [];
+				for (const innerProp of prop.initializer.properties) if (ts.isPropertyAssignment(innerProp) && ts.isIdentifier(innerProp.name)) {
+					const optName = innerProp.name.text;
+					const optValue = innerProp.initializer.getText();
+					options.push(`${optName}: ${optValue}`);
+				}
+				if (options.length > 0) replacement = `encapsulation: { type: 'shadow', ${options.join(", ")} }`;
+				else replacement = "encapsulation: { type: 'shadow' }";
+			} else replacement = "";
+			else if (propName === "scoped") if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) replacement = "encapsulation: { type: 'scoped' }";
+			else replacement = "";
+			else continue;
+			let endPos = end;
+			const afterProp = text.slice(end).match(/^\s*,/);
+			if (afterProp && replacement === "") endPos = end + afterProp[0].length;
+			else if (afterProp && replacement !== "") {} else if (!afterProp && replacement !== "") {}
+			text = text.slice(0, start) + replacement + text.slice(endPos);
+		}
+		return text;
+	}
+};
+//#endregion
+//#region src/migrations/rules/form-associated.ts
+/**
+* Migration rule for formAssociated → @AttachInternals.
+*
+* Migrates:
+* - `formAssociated: true` in @Component → Adds `@AttachInternals() internals: ElementInternals;`
+*/
+const formAssociatedRule = {
+	id: "form-associated",
+	name: "Form Associated",
+	description: "Migrate formAssociated to @AttachInternals decorator",
+	fromVersion: "4.x",
+	toVersion: "5.x",
+	detect(sourceFile) {
+		const matches = [];
+		const importMap = getStencilCoreImportMap(sourceFile);
+		let hasAttachInternalsImport = false;
+		let stencilImportEnd = 0;
+		for (const statement of sourceFile.statements) if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "@stencil/core") {
+			stencilImportEnd = statement.getEnd();
+			for (const [, originalName] of importMap) if (originalName === "AttachInternals") {
+				hasAttachInternalsImport = true;
+				break;
+			}
+			break;
+		}
+		const visit = (node) => {
+			if (ts.isClassDeclaration(node)) {
+				const decorators = ts.getDecorators(node);
+				if (!decorators) {
+					ts.forEachChild(node, visit);
+					return;
+				}
+				let componentDecorator;
+				let formAssociatedProp;
+				for (const decorator of decorators) if (ts.isCallExpression(decorator.expression) && ts.isIdentifier(decorator.expression.expression) && isStencilDecorator(decorator.expression.expression.text, "Component", importMap)) {
+					componentDecorator = decorator;
+					const [arg] = decorator.expression.arguments;
+					if (arg && ts.isObjectLiteralExpression(arg)) {
+						for (const prop of arg.properties) if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name) && prop.name.text === "formAssociated") {
+							formAssociatedProp = prop;
+							break;
+						}
+					}
+					break;
+				}
+				if (componentDecorator && formAssociatedProp) {
+					let hasAttachInternals = false;
+					for (const member of node.members) if (ts.isPropertyDeclaration(member) || ts.isMethodDeclaration(member)) {
+						const memberDecorators = ts.getDecorators(member);
+						if (memberDecorators) {
+							for (const d of memberDecorators) if (ts.isCallExpression(d.expression) && ts.isIdentifier(d.expression.expression) && isStencilDecorator(d.expression.expression.text, "AttachInternals", importMap)) {
+								hasAttachInternals = true;
+								break;
+							}
+						}
+					}
+					let searchStart = node.name ? node.name.getEnd() : node.getStart(sourceFile);
+					if (node.heritageClauses) for (const clause of node.heritageClauses) searchStart = Math.max(searchStart, clause.getEnd());
+					const braceMatch = sourceFile.getFullText().slice(searchStart).match(/\s*\{/);
+					if (!braceMatch) {
+						ts.forEachChild(node, visit);
+						return;
+					}
+					const classBodyStart = searchStart + braceMatch[0].length;
+					let indent = "  ";
+					if (node.members.length > 0) {
+						const memberStart = node.members[0].getStart(sourceFile);
+						const indentMatch = sourceFile.getFullText().slice(classBodyStart, memberStart).match(/\n(\s+)/);
+						if (indentMatch) indent = indentMatch[1];
+					}
+					const { line, character } = sourceFile.getLineAndCharacterOfPosition(formAssociatedProp.getStart());
+					matches.push({
+						node: formAssociatedProp,
+						message: hasAttachInternals ? "Remove 'formAssociated' (already has @AttachInternals)" : "Migrate 'formAssociated' to @AttachInternals decorator",
+						line: line + 1,
+						column: character + 1,
+						classBodyStart,
+						hasAttachInternals,
+						indent,
+						needsImport: !hasAttachInternalsImport && !hasAttachInternals,
+						stencilImportEnd
+					});
+				}
+			}
+			ts.forEachChild(node, visit);
+		};
+		visit(sourceFile);
+		return matches;
+	},
+	transform(sourceFile, matches) {
+		if (matches.length === 0) return sourceFile.getFullText();
+		let text = sourceFile.getFullText();
+		const typedMatches = matches;
+		const sortedMatches = [...typedMatches].sort((a, b) => {
+			return b.classBodyStart - a.classBodyStart;
+		});
+		for (const match of sortedMatches) {
+			if (!match.hasAttachInternals) {
+				const newMember = `\n${match.indent}@AttachInternals() internals: ElementInternals;\n`;
+				text = text.slice(0, match.classBodyStart) + newMember + text.slice(match.classBodyStart);
+			}
+			const prop = match.node;
+			const start = prop.getStart();
+			let end = prop.getEnd();
+			const afterProp = text.slice(end).match(/^\s*,/);
+			if (afterProp) end = end + afterProp[0].length;
+			text = text.slice(0, start) + text.slice(end);
+		}
+		const firstMatch = typedMatches[0];
+		if (firstMatch?.needsImport && firstMatch.stencilImportEnd > 0) {
+			const importMatch = text.match(/import\s*\{([^}]*)\}\s*from\s*['"]@stencil\/core['"]/);
+			if (importMatch) {
+				const newImports = importMatch[1].trimEnd() + ", AttachInternals";
+				text = text.replace(importMatch[0], `import {${newImports}} from '@stencil/core'`);
+			}
+		}
+		return text;
+	}
+};
+//#endregion
+//#region src/migrations/index.ts
+/**
+* Build a map of local import names to their original names from @stencil/core.
+* Handles aliased imports like `import { Component as Cmp } from '@stencil/core'`.
+* Also handles multiple imports from @stencil/core (e.g., separate type and value imports).
+*
+* @param sourceFile The TypeScript source file to analyze
+* @returns Map where keys are local names and values are original imported names
+*/
+const getStencilCoreImportMap = (sourceFile) => {
+	const importMap = /* @__PURE__ */ new Map();
+	for (const statement of sourceFile.statements) if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "@stencil/core") {
+		const namedBindings = statement.importClause?.namedBindings;
+		if (namedBindings && ts.isNamedImports(namedBindings)) for (const element of namedBindings.elements) {
+			const localName = element.name.text;
+			const originalName = element.propertyName?.text ?? element.name.text;
+			importMap.set(localName, originalName);
+		}
+	}
+	return importMap;
+};
+/**
+* Check if a decorator identifier refers to a specific @stencil/core export.
+* Handles aliased imports like `import { Component as Cmp } from '@stencil/core'`.
+*
+* @param decoratorName The identifier used in the decorator
+* @param expectedOriginalName The original export name (e.g., 'Component')
+* @param importMap The import map from getStencilCoreImportMap
+* @returns True if the decorator refers to the expected export
+*/
+const isStencilDecorator = (decoratorName, expectedOriginalName, importMap) => {
+	return importMap.get(decoratorName) === expectedOriginalName;
+};
+/**
+* Registry of all available migration rules.
+* Rules are applied in order, so add new rules at the end.
+*/
+const migrationRules = [encapsulationApiRule, formAssociatedRule];
+/**
+* Get all migration rules for a specific version upgrade.
+* @param fromVersion Source version (e.g., '4')
+* @param toVersion Target version (e.g., '5')
+* @returns Filtered list of applicable rules
+*/
+const getRulesForVersionUpgrade = (fromVersion, toVersion) => {
+	return migrationRules.filter((rule) => rule.fromVersion.startsWith(fromVersion) && rule.toVersion.startsWith(toVersion));
+};
+//#endregion
+//#region src/task-migrate.ts
+/**
+* Run the migration task to update Stencil components from v4 to v5 API.
+*
+* @param coreCompiler the Stencil compiler instance
+* @param config the validated Stencil config
+* @param flags CLI flags (includes dryRun option)
+*/
+const taskMigrate = async (coreCompiler, config, flags) => {
+	const logger = config.logger;
+	const sys = config.sys;
+	const dryRun = flags.dryRun ?? false;
+	const currentMajor = coreCompiler.version.split(".")[0];
+	const fromVersion = String(Number(currentMajor) - 1);
+	const toVersion = currentMajor;
+	const rules = getRulesForVersionUpgrade(fromVersion, toVersion);
+	if (rules.length === 0) {
+		logger.info(`No migration rules found for ${fromVersion}.x → ${toVersion}.x upgrade.`);
+		return;
+	}
+	logger.info(`${logger.emoji("🔄 ")}Stencil Migration Tool (v${fromVersion} → v${toVersion})`);
+	logger.info(`Scanning for components that need migration...`);
+	if (dryRun) logger.info(logger.cyan("Dry run mode - no files will be modified"));
+	const tsFiles = await getTypeScriptFiles(config, sys, logger);
+	if (tsFiles.length === 0) {
+		logger.info(`No TypeScript files found. Check your tsconfig.json configuration.`);
+		return;
+	}
+	logger.info(`Found ${tsFiles.length} TypeScript files to scan`);
+	const results = [];
+	for (const filePath of tsFiles) {
+		let content = await sys.readFile(filePath);
+		if (!content) continue;
+		for (const rule of rules) {
+			const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+			const matches = rule.detect(sourceFile);
+			if (matches.length > 0) {
+				const relPath = relative(config.rootDir, filePath);
+				logger.info(`\n${logger.cyan(relPath)}`);
+				logger.info(`  ${logger.yellow(`[${rule.id}]`)} ${rule.name}`);
+				for (const match of matches) logger.info(`    Line ${match.line}: ${match.message}`);
+				if (!dryRun) {
+					const transformed = rule.transform(sourceFile, matches);
+					await sys.writeFile(filePath, transformed);
+					content = transformed;
+					results.push({
+						filePath,
+						rule,
+						matches,
+						transformed: true
+					});
+					logger.info(`  ${logger.green("✓")} Migrated`);
+				} else results.push({
+					filePath,
+					rule,
+					matches,
+					transformed: false
+				});
+			}
+		}
+	}
+	logger.info("\n" + logger.bold("Migration Summary"));
+	logger.info("─".repeat(40));
+	const totalMatches = results.reduce((sum, r) => sum + r.matches.length, 0);
+	const filesAffected = new Set(results.map((r) => r.filePath)).size;
+	if (totalMatches === 0) logger.info(logger.green("No migrations needed - your code is up to date!"));
+	else {
+		logger.info(`Found ${totalMatches} item(s) to migrate in ${filesAffected} file(s)`);
+		if (dryRun) logger.info(logger.yellow("\nRun without --dry-run to apply the migrations"));
+		else logger.info(logger.green(`\n✓ Successfully migrated ${totalMatches} item(s)`));
+	}
+	const byRule = /* @__PURE__ */ new Map();
+	for (const result of results) {
+		const existing = byRule.get(result.rule.id) || [];
+		existing.push(result);
+		byRule.set(result.rule.id, existing);
+	}
+	if (byRule.size > 0) {
+		logger.info("\nBy migration rule:");
+		for (const [ruleId, ruleResults] of byRule) {
+			const rule = rules.find((r) => r.id === ruleId);
+			const count = ruleResults.reduce((sum, r) => sum + r.matches.length, 0);
+			logger.info(`  ${rule?.name || ruleId}: ${count} item(s)`);
+		}
+	}
+};
+/**
+* Detect available migrations without applying them.
+* Used by the build task to check if migrations might help fix build errors.
+*
+* @param coreCompiler the Stencil compiler instance
+* @param config the validated Stencil config
+* @returns detection result with migration information
+*/
+const detectMigrations = async (coreCompiler, config) => {
+	const sys = config.sys;
+	const logger = config.logger;
+	const currentMajor = coreCompiler.version.split(".")[0];
+	const rules = getRulesForVersionUpgrade(String(Number(currentMajor) - 1), currentMajor);
+	if (rules.length === 0) return {
+		hasMigrations: false,
+		totalMatches: 0,
+		filesAffected: 0,
+		migrations: [],
+		rules: []
+	};
+	const tsFiles = await getTypeScriptFiles(config, sys, logger);
+	if (tsFiles.length === 0) return {
+		hasMigrations: false,
+		totalMatches: 0,
+		filesAffected: 0,
+		migrations: [],
+		rules
+	};
+	const migrations = [];
+	for (const filePath of tsFiles) {
+		const content = await sys.readFile(filePath);
+		if (!content) continue;
+		for (const rule of rules) {
+			const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+			const matches = rule.detect(sourceFile);
+			if (matches.length > 0) migrations.push({
+				filePath,
+				rule,
+				matches
+			});
+		}
+	}
+	const totalMatches = migrations.reduce((sum, m) => sum + m.matches.length, 0);
+	const filesAffected = new Set(migrations.map((m) => m.filePath)).size;
+	return {
+		hasMigrations: migrations.length > 0,
+		totalMatches,
+		filesAffected,
+		migrations,
+		rules
+	};
+};
+/**
+* Get TypeScript files using the project's tsconfig.json.
+* Uses the same approach as the Stencil compiler.
+*
+* @param config the validated Stencil config
+* @param sys the compiler system for file operations
+* @param logger the logger for output
+* @returns array of absolute paths to TypeScript files
+*/
+async function getTypeScriptFiles(config, sys, logger) {
+	let tsconfigPath;
+	if (config.tsconfig) tsconfigPath = isAbsolute(config.tsconfig) ? config.tsconfig : join(config.rootDir, config.tsconfig);
+	else tsconfigPath = join(config.rootDir, "tsconfig.json");
+	logger.debug(`Using tsconfig: ${tsconfigPath}`);
+	const tsconfigContent = await sys.readFile(tsconfigPath);
+	if (!tsconfigContent) {
+		logger.error(`tsconfig not found: ${tsconfigPath}`);
+		return [];
+	}
+	const host = {
+		...ts.sys,
+		readFile: (p) => {
+			if (p === tsconfigPath) return tsconfigContent;
+			return ts.sys.readFile(p);
+		},
+		onUnRecoverableConfigFileDiagnostic: (diagnostic) => {
+			logger.error(ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"));
+		}
+	};
+	const results = ts.getParsedCommandLineOfConfigFile(tsconfigPath, {}, host);
+	if (!results) {
+		logger.error(`Failed to parse tsconfig: ${tsconfigPath}`);
+		return [];
+	}
+	if (results.errors && results.errors.length > 0) for (const err of results.errors) logger.warn(ts.flattenDiagnosticMessageText(err.messageText, "\n"));
+	return results.fileNames.filter((f) => (f.endsWith(".ts") || f.endsWith(".tsx")) && !f.endsWith(".d.ts"));
+}
+//#endregion
 //#region src/task-prerender.ts
 const taskPrerender = async (coreCompiler, config, flags) => {
 	startupCompilerLog(coreCompiler, config);
@@ -1000,9 +1318,9 @@ function getActiveTargets(config) {
 * @returns a Promise wrapping data for the telemetry endpoint
 */
 const prepareData = async (coreCompiler, config, sys, flags, duration_ms, component_count = void 0) => {
-	const { typescript, rollup } = coreCompiler.versions || {
+	const { typescript, rolldown } = coreCompiler.versions || {
 		typescript: "unknown",
-		rollup: "unknown"
+		rolldown: "unknown"
 	};
 	const { packages, packagesNoVersions } = await getInstalledPackages(sys, flags);
 	const targets = getActiveTargets(config);
@@ -1027,7 +1345,7 @@ const prepareData = async (coreCompiler, config, sys, flags, duration_ms, compon
 		os_version,
 		packages,
 		packages_no_versions: packagesNoVersions,
-		rollup,
+		rolldown,
 		stencil,
 		system,
 		system_major: getMajorVersion(system),
@@ -1051,13 +1369,11 @@ const CONFIG_PROPS_TO_ANONYMIZE = [
 	"tsconfig"
 ];
 const CONFIG_PROPS_TO_DELETE = [
-	"commonjs",
 	"devServer",
 	"env",
 	"logger",
-	"rollupConfig",
+	"rolldownConfig",
 	"sys",
-	"testing",
 	"tsCompilerOptions"
 ];
 /**
@@ -1276,8 +1592,36 @@ const taskBuild = async (coreCompiler, config, flags) => {
 		const results = await compiler.build();
 		await telemetryBuildFinishedAction(config.sys, config, coreCompiler, results, flags);
 		await compiler.destroy();
-		if (results.hasError) exitCode = 1;
-		else if (flags.prerender) {
+		if (results.hasError) {
+			const migrationResult = await detectMigrations(coreCompiler, config);
+			if (migrationResult.hasMigrations) {
+				const action = await promptForMigrationOnBuildError(config, migrationResult);
+				if (action === "run") {
+					await taskMigrate(coreCompiler, config, {
+						...flags,
+						dryRun: false
+					});
+					config.logger.info("\nRe-running build after migrations...\n");
+					const newCompiler = await coreCompiler.createCompiler(config);
+					const newResults = await newCompiler.build();
+					await newCompiler.destroy();
+					if (!newResults.hasError) {
+						exitCode = 0;
+						if (flags.prerender) {
+							const prerenderDiagnostics = await runPrerenderTask(coreCompiler, config, newResults.hydrateAppFilePath, newResults.componentGraph, void 0);
+							config.logger.printDiagnostics(prerenderDiagnostics);
+							if (prerenderDiagnostics.some((d) => d.level === "error")) exitCode = 1;
+						}
+					} else exitCode = 1;
+				} else if (action === "dry-run") {
+					await taskMigrate(coreCompiler, config, {
+						...flags,
+						dryRun: true
+					});
+					exitCode = 1;
+				} else exitCode = 1;
+			} else exitCode = 1;
+		} else if (flags.prerender) {
 			const prerenderDiagnostics = await runPrerenderTask(coreCompiler, config, results.hydrateAppFilePath, results.componentGraph, void 0);
 			config.logger.printDiagnostics(prerenderDiagnostics);
 			if (prerenderDiagnostics.some((d) => d.level === "error")) exitCode = 1;
@@ -1289,6 +1633,51 @@ const taskBuild = async (coreCompiler, config, flags) => {
 	}
 	if (exitCode > 0) return config.sys.exit(exitCode);
 };
+/**
+* Prompt the user about available migrations when a build fails.
+* Shows what migrations are available and lets them choose to run them.
+* @param config the Stencil config
+* @param migrationResult the result of migration detection with available migrations
+* @returns the user's chosen action for handling migrations
+*/
+async function promptForMigrationOnBuildError(config, migrationResult) {
+	const logger = config.logger;
+	logger.info("");
+	logger.info(logger.bold(logger.yellow("Migrations Available")));
+	logger.info("─".repeat(40));
+	logger.info(`Found ${migrationResult.totalMatches} item(s) in ${migrationResult.filesAffected} file(s) that can be automatically migrated.`);
+	for (const migration of migrationResult.migrations) {
+		const relPath = relative(config.rootDir, migration.filePath);
+		logger.info(`  ${logger.cyan(relPath)}: ${migration.matches.length} item(s)`);
+	}
+	logger.info("");
+	logger.info("These migrations may help resolve the build errors above.");
+	const prompt = (await import("prompts")).default;
+	const response = await prompt({
+		name: "action",
+		type: "select",
+		message: "What would you like to do?",
+		choices: [
+			{
+				title: "Run migration",
+				value: "run",
+				description: "Apply migrations and re-run build"
+			},
+			{
+				title: "Dry run",
+				value: "dry-run",
+				description: "Preview changes without modifying files"
+			},
+			{
+				title: "Exit",
+				value: "exit",
+				description: "Exit without making changes"
+			}
+		]
+	});
+	if (response.action === void 0) return "exit";
+	return response.action;
+}
 //#endregion
 //#region src/task-docs.ts
 const taskDocs = async (coreCompiler, config) => {
@@ -1680,7 +2069,7 @@ const taskInfo = (coreCompiler, sys, logger) => {
 	console.log(`${logger.cyan("       Build:")} ${coreCompiler.buildId}`);
 	console.log(`${logger.cyan("     Stencil:")} ${coreCompiler.version}${logger.emoji(" " + coreCompiler.vermoji)}`);
 	console.log(`${logger.cyan("  TypeScript:")} ${versions.typescript}`);
-	console.log(`${logger.cyan("      Rollup:")} ${versions.rollup}`);
+	console.log(`${logger.cyan("      Rolldown:")} ${versions.rolldown}`);
 	console.log(`${logger.cyan("      Terser:")} ${versions.terser}`);
 	console.log(``);
 };
@@ -1810,6 +2199,9 @@ const runTask = async (coreCompiler, config, task, sys, flags) => {
 		case "help":
 			await taskHelp(resolvedFlags, strictConfig.logger, sys);
 			break;
+		case "migrate":
+			await taskMigrate(coreCompiler, strictConfig, resolvedFlags);
+			break;
 		case "prerender":
 			await taskPrerender(coreCompiler, strictConfig, resolvedFlags);
 			break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stencil/cli",
-  "version": "5.0.0-alpha.2",
+  "version": "5.0.0-alpha.4",
   "description": "CLI for Stencil - Web component compiler",
   "keywords": [
     "components",
@@ -38,13 +38,14 @@
   },
   "dependencies": {
     "prompts": "^2.4.2",
-    "@stencil/dev-server": "5.0.0-alpha.2"
+    "@stencil/dev-server": "5.0.0-alpha.4"
   },
   "devDependencies": {
+    "@types/prompts": "^2.4.9",
     "tsdown": "^0.21.6",
     "typescript": "~6.0.2",
     "vitest": "^4.1.1",
-    "@stencil/core": "5.0.0-alpha.2"
+    "@stencil/core": "5.0.0-alpha.4"
   },
   "peerDependencies": {
     "@stencil/core": "^5.0.0-0"