@xihan-ui/cli 5.1.0 → 5.3.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import process from "node:process";
 import { parseArgs } from "node:util";
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline";
 //#region src/knowledge.ts
@@ -1042,6 +1042,1275 @@ function serveStdio(options, input = process.stdin, output = process.stdout) {
 	return new Promise((resolve) => reader.once("close", () => resolve()));
 }
 //#endregion
+//#region src/migrate.ts
+const DIALECTS = {
+	".vue": "vue",
+	".tsx": "jsx",
+	".jsx": "jsx",
+	".html": "html",
+	".htm": "html",
+	".css": "css",
+	".scss": "css",
+	".sass": "css",
+	".less": "css",
+	".ts": "script",
+	".mts": "script",
+	".cts": "script",
+	".js": "script",
+	".mjs": "script",
+	".cjs": "script"
+};
+/** 按扩展名认写法；不认识的扩展名返回 undefined，迁移时跳过。 */
+function dialectOf(file) {
+	const dot = file.lastIndexOf(".");
+	return dot < 0 ? void 0 : DIALECTS[file.slice(dot).toLowerCase()];
+}
+const LIBRARY = /@xihan-ui\/|\bXh[A-Z]|<xh-|['"`]xh-|--xh-|data-scope|data-xh-|xh-scope-/;
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const kebab = (name) => name.replace(/[A-Z]/g, (char, index) => `${index > 0 ? "-" : ""}${char.toLowerCase()}`);
+const camel = (name) => name.replace(/-([a-z0-9])/g, (_, char) => char.toUpperCase());
+const pascal = (name) => camel(name).replace(/^[a-z]/, (char) => char.toUpperCase());
+/** 改写过程的状态：当前文本、改了几处、报了哪些。 */
+var Draft = class {
+	text;
+	edits = 0;
+	found = /* @__PURE__ */ new Map();
+	constructor(text) {
+		this.text = text;
+	}
+	/** 全文按正则替换，计数。 */
+	replace(pattern, replacer) {
+		let out = "";
+		let last = 0;
+		for (const match of this.text.matchAll(pattern)) {
+			const next = replacer(match);
+			if (next === void 0 || next === match[0]) continue;
+			out += this.text.slice(last, match.index) + next;
+			last = match.index + match[0].length;
+			this.edits++;
+		}
+		if (last > 0) this.text = out + this.text.slice(last);
+	}
+	/** 按区间改：区间互不重叠，从后往前套用。 */
+	splice(edits) {
+		for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+			this.text = this.text.slice(0, edit.start) + edit.text + this.text.slice(edit.end);
+			this.edits++;
+		}
+	}
+	report(index, message) {
+		const line = this.text.slice(0, index).split("\n").length;
+		this.found.set(`${line}\u0000${message}`, {
+			line,
+			message
+		});
+	}
+	get findings() {
+		return [...this.found.values()].sort((a, b) => a.line - b.line);
+	}
+};
+/** 从 open 处的开括号走到配对的闭括号，跳过字符串。 */
+function skipBalanced(text, open, close, start) {
+	let depth = 0;
+	for (let i = open; i < text.length; i++) {
+		const char = text[i];
+		if (char === "\"" || char === "'" || char === "`") {
+			i = text.indexOf(char, i + 1);
+			if (i < 0) return text.length;
+			continue;
+		}
+		if (char === start) depth++;
+		else if (char === close && --depth === 0) return i;
+	}
+	return text.length;
+}
+function parseAttributes(text, from, to) {
+	const out = [];
+	let i = from;
+	while (i < to) {
+		const char = text[i];
+		if (/\s|\//.test(char)) {
+			i++;
+			continue;
+		}
+		if (char === "{") {
+			i = skipBalanced(text, i, "}", "{") + 1;
+			continue;
+		}
+		const name = /^[^\s=>/'"{}]+/.exec(text.slice(i, to));
+		if (!name) {
+			i++;
+			continue;
+		}
+		const start = i;
+		i += name[0].length;
+		let j = i;
+		while (j < to && /\s/.test(text[j])) j++;
+		if (text[j] !== "=") {
+			out.push({
+				start,
+				end: i,
+				name: name[0],
+				quoted: false,
+				braced: false
+			});
+			continue;
+		}
+		j++;
+		while (j < to && /\s/.test(text[j])) j++;
+		const quote = text[j];
+		if (quote === "\"" || quote === "'") {
+			const close = text.indexOf(quote, j + 1);
+			const end = close < 0 ? to : close + 1;
+			out.push({
+				start,
+				end,
+				name: name[0],
+				value: text.slice(j + 1, end - 1),
+				quoted: true,
+				braced: false
+			});
+			i = end;
+		} else if (quote === "{") {
+			const close = skipBalanced(text, j, "}", "{");
+			out.push({
+				start,
+				end: close + 1,
+				name: name[0],
+				value: text.slice(j + 1, close).trim(),
+				quoted: false,
+				braced: true
+			});
+			i = close + 1;
+		} else {
+			const bare = /^[^\s>]*/.exec(text.slice(j, to))[0];
+			out.push({
+				start,
+				end: j + bare.length,
+				name: name[0],
+				value: bare,
+				quoted: false,
+				braced: false
+			});
+			i = j + bare.length;
+		}
+	}
+	return out;
+}
+/** 文本里的 Xh 组件标签与 xh- 元素标签（开标签）。 */
+function scanTags(text) {
+	const out = [];
+	for (const match of text.matchAll(/<(Xh[A-Z][\w.]*|xh-[a-z][\w-]*)/g)) {
+		const start = match.index;
+		const nameEnd = start + match[0].length;
+		if (!/[\s/>]/.test(text[nameEnd] ?? "")) continue;
+		let end = nameEnd;
+		for (; end < text.length; end++) {
+			const char = text[end];
+			if (char === "\"" || char === "'") {
+				const close = text.indexOf(char, end + 1);
+				end = close < 0 ? text.length : close;
+			} else if (char === "{") end = skipBalanced(text, end, "}", "{");
+			else if (char === ">" || char === "<") break;
+		}
+		out.push({
+			start,
+			end,
+			name: match[1],
+			attributes: parseAttributes(text, nameEnd, end)
+		});
+	}
+	return out;
+}
+/** 标签归到组件：Xh 组件按短横线写法、xh- 元素去掉前缀，取最长的组件标识前缀。 */
+function scopeOf(tag, scopes) {
+	const words = (tag.startsWith("Xh") ? kebab(tag.slice(2)) : tag.slice(3)).split("-");
+	for (let size = words.length; size > 0; size--) {
+		const candidate = words.slice(0, size).join("-");
+		if (scopes.has(candidate)) return candidate;
+	}
+}
+/** 属性名拆成前缀（: v-bind: @ v-on:）、本名与修饰符。 */
+function splitName(name) {
+	const match = /^(:|v-bind:|@|v-on:)?([^.]+)(\..*)?$/.exec(name);
+	return {
+		prefix: match?.[1] ?? "",
+		base: match?.[2] ?? name,
+		modifiers: match?.[3] ?? ""
+	};
+}
+const isEventPrefix = (prefix) => prefix === "@" || prefix === "v-on:";
+/** 新属性名按原写法的风格出：原来是短横线或在模板与 HTML 里就写短横线，JSX 里写驼峰。 */
+function styled(base, to, dialect) {
+	if (base.includes("-")) return kebab(to);
+	if (/[A-Z]/.test(base)) return to;
+	return dialect === "jsx" ? to : kebab(to);
+}
+/** 属性改名；名字对上了就返回 true（改了或报了），后面不再按删除清单报它。 */
+function rewriteProp(rule, attribute, dialect, draft, edits) {
+	const { prefix, base } = splitName(attribute.name);
+	if (isEventPrefix(prefix) || camel(base) !== rule.from) return false;
+	const name = styled(base, rule.to, dialect);
+	if (rule.booleanTo === void 0) {
+		edits.push({
+			start: attribute.start,
+			end: attribute.start + prefix.length + base.length,
+			text: prefix + name
+		});
+		return true;
+	}
+	const raw = attribute.value?.trim();
+	const truthy = raw === void 0 || attribute.braced && raw === "true" || (prefix === ":" || prefix === "v-bind:" ? raw === "true" : !attribute.braced);
+	if ((attribute.braced || prefix !== "") && raw === "false") {
+		const start = /\s/.test(draft.text[attribute.start - 1] ?? "") ? attribute.start - 1 : attribute.start;
+		edits.push({
+			start,
+			end: attribute.end,
+			text: ""
+		});
+		return true;
+	}
+	if (!truthy) {
+		draft.report(attribute.start, `${rule.from} 写了表达式：改成 ${rule.to}，开着时取 ${JSON.stringify(rule.booleanTo)}，关着时不写`);
+		return true;
+	}
+	const value = rule.booleanTo;
+	const text = typeof value === "string" ? `${name}="${value}"` : dialect === "jsx" ? `${name}={${value}}` : dialect === "vue" ? `:${name}="${value}"` : `${name}="${value}"`;
+	edits.push({
+		start: attribute.start,
+		end: attribute.end,
+		text
+	});
+	return true;
+}
+/** 事件改名；名字对上了就返回 true。 */
+function rewriteEvent(rule, attribute, edits) {
+	const { prefix, base, modifiers } = splitName(attribute.name);
+	if (isEventPrefix(prefix) && kebab(camel(base)) === rule.from) {
+		edits.push({
+			start: attribute.start,
+			end: attribute.start + attribute.name.length,
+			text: `${prefix}${base.includes("-") || base === base.toLowerCase() ? rule.to : camel(rule.to)}${modifiers}`
+		});
+		return true;
+	}
+	if (prefix === "" && base === `on${pascal(rule.from)}`) {
+		edits.push({
+			start: attribute.start,
+			end: attribute.start + base.length,
+			text: `on${pascal(rule.to)}`
+		});
+		return true;
+	}
+	return false;
+}
+/** 标签里的属性与事件改名，顺带报出本 major 删掉的属性。 */
+function rewriteTags(draft, dialect, rules, surface) {
+	const scopes = new Set(surface.scopes);
+	const elementTags = new Set(surface.tags);
+	const edits = [];
+	for (const tag of scanTags(draft.text)) {
+		const scope = scopeOf(tag.name, scopes);
+		if (!scope) continue;
+		const isElement = elementTags.has(tag.name);
+		const tagDialect = tag.name.startsWith("xh-") && dialect !== "vue" ? "html" : dialect;
+		const removedProps = new Set(surface.removed.props[scope] ?? []);
+		const removedAttributes = new Set(isElement ? surface.removed.elementAttributes[tag.name] ?? [] : []);
+		for (const attribute of tag.attributes) {
+			let handled = false;
+			for (const rule of rules.props ?? []) {
+				if (!rule.components.includes(scope)) continue;
+				if (rule.only === "web-components" && !(isElement && dialect !== "vue")) continue;
+				handled = rewriteProp(rule, attribute, tagDialect, draft, edits) || handled;
+			}
+			for (const rule of rules.events ?? []) if (rule.components.includes(scope)) handled = rewriteEvent(rule, attribute, edits) || handled;
+			if (handled) continue;
+			const { prefix, base } = splitName(attribute.name);
+			const asProp = isEventPrefix(prefix) ? `on${pascal(base)}` : camel(base);
+			if (removedProps.has(asProp) || removedAttributes.has(base)) draft.report(attribute.start, `${scope} 的 ${attribute.name} 在 ${rules.major}.0 删除了，按更新日志改写`);
+		}
+	}
+	draft.splice(edits);
+}
+function parseSpecifiers(list) {
+	return list.split(",").map((part) => part.trim()).filter(Boolean).map((part) => {
+		const match = /^(type\s+)?([\w$]+)(?:\s+as\s+([\w$]+))?$/.exec(part);
+		return match ? {
+			type: Boolean(match[1]),
+			name: match[2],
+			alias: match[3]
+		} : {
+			type: false,
+			name: part
+		};
+	});
+}
+const printSpecifier = (spec) => `${spec.type ? "type " : ""}${spec.name}${spec.alias ? ` as ${spec.alias}` : ""}`;
+/** 一组名字从一个模块搬到另一个模块：改导入语句，没起别名的顺带改文件里的用处。 */
+function moveImports(draft, from, to, names) {
+	const locals = /* @__PURE__ */ new Map();
+	draft.replace(/import\s+(type\s+)?\{([^}]*)\}\s*from\s*(['"])([^'"]+)\3(\s*;)?/g, (match) => {
+		if (match[4] !== from) return void 0;
+		const specifiers = parseSpecifiers(match[2]);
+		const moving = specifiers.filter((spec) => Object.hasOwn(names, spec.name));
+		if (moving.length === 0) return void 0;
+		const staying = specifiers.filter((spec) => !moving.includes(spec));
+		const moved = moving.map((spec) => {
+			const renamed = names[spec.name] === true ? spec.name : names[spec.name];
+			if (!spec.alias && renamed !== spec.name) locals.set(spec.name, renamed);
+			return {
+				...spec,
+				name: renamed
+			};
+		});
+		const keyword = match[1] ?? "";
+		const quote = match[3];
+		const semi = match[5] ?? "";
+		const statement = (specs, module) => `import ${keyword}{ ${specs.map(printSpecifier).join(", ")} } from ${quote}${module}${quote}${semi}`;
+		return staying.length > 0 ? `${statement(staying, from)}\n${statement(moved, to)}` : statement(moved, to);
+	});
+	for (const [name, renamed] of locals) draft.replace(new RegExp(`(?<![\\w$.])${escape(name)}(?![\\w$])`, "g"), () => renamed);
+}
+/** 从 @xihan-ui 各包导入的名字（导入时的原名）。 */
+function libraryImports(text) {
+	const out = /* @__PURE__ */ new Set();
+	for (const match of text.matchAll(/import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]@xihan-ui\/[^'"]+['"]/g)) for (const spec of parseSpecifiers(match[1])) out.add(spec.name);
+	return out;
+}
+function migrateMajor(draft, dialect, { rules, surface }) {
+	for (const check of rules.manual ?? []) for (const match of draft.text.matchAll(new RegExp(check.pattern.source, `${check.pattern.flags.replace("g", "")}g`))) draft.report(match.index, check.message);
+	const modules = Object.entries(rules.modules ?? {}).sort(([a], [b]) => b.length - a.length);
+	for (const [from, to] of modules) draft.replace(new RegExp(`(['"\`])${escape(from)}(?=(?:/[^'"\`]*)?\\1)`, "g"), (match) => `${match[1]}${to}`);
+	for (const moved of rules.imports ?? []) moveImports(draft, moved.from, moved.to, moved.names);
+	if (dialect !== "css") rewriteTags(draft, dialect, rules, surface);
+	const identifiers = {
+		...surface.renamed.identifiers,
+		...rules.identifiers
+	};
+	const imported = libraryImports(draft.text);
+	for (const [from, rename] of Object.entries(identifiers)) {
+		const to = typeof rename === "string" ? rename : rename.to;
+		const attrs = typeof rename === "string" ? void 0 : rename.attrs;
+		if (!from.startsWith("Xh") && !imported.has(from)) continue;
+		if (from.startsWith("Xh")) for (const [old, next] of [[from, to], [`xh-${kebab(from.slice(2))}`, `xh-${kebab(to.slice(2))}`]]) {
+			draft.replace(new RegExp(`<${escape(old)}(?=[\\s/>])`, "g"), () => `<${next}${attrs ? ` ${attrs}` : ""}`);
+			draft.replace(new RegExp(`</${escape(old)}(?=\\s*>)`, "g"), () => `</${next}`);
+		}
+		draft.replace(new RegExp(`(?<![\\w$])${escape(from)}(?![\\w$])`, "g"), () => to);
+	}
+	const elements = [...Object.entries(surface.renamed.elements).map(([from, to]) => ({
+		from,
+		to
+	})), ...rules.elements ?? []];
+	for (const element of elements) renameElement(draft, dialect, element);
+	for (const rename of rules.parts ?? []) renamePart(draft, rename);
+	for (const rule of rules.events ?? []) rewriteListeners(draft, rule);
+	const cssVariables = {
+		...surface.renamed.cssVariables,
+		...rules.cssVariables
+	};
+	for (const [from, to] of Object.entries(cssVariables)) draft.replace(new RegExp(`${escape(from)}(?![\\w-])`, "g"), () => to);
+	for (const [from, to] of [...Object.entries(rules.keyframes ?? {}), ...Object.entries(rules.dataAttributes ?? {})]) draft.replace(new RegExp(`(?<![\\w-])${escape(from)}(?![\\w-])`, "g"), () => to);
+	reportRemoved(draft, rules.major, surface);
+}
+/** 元素改名：先改元素里的部件，再改开闭标签、字符串里的元素名与样式表里的元素选择器。 */
+function renameElement(draft, dialect, { from, to, attrs, parts }) {
+	if (parts) renamePartsInside(draft, from, parts);
+	draft.replace(new RegExp(`<${escape(from)}(?=[\\s/>])`, "g"), () => `<${to}${attrs ? ` ${attrs}` : ""}`);
+	draft.replace(new RegExp(`</${escape(from)}(?=\\s*>)`, "g"), () => `</${to}`);
+	draft.replace(new RegExp(`(['"\`])${escape(from)}\\1`, "g"), (match) => `${match[1]}${to}${match[1]}`);
+	if (dialect === "css" || dialect === "vue" || dialect === "html") draft.replace(new RegExp(`(?<![\\w-])${escape(from)}(?=[\\s.:#\\[{,>+~)])`, "g"), () => to);
+}
+/** 元素块（开标签到同名闭标签）里的 data-xh-part 改名。 */
+function renamePartsInside(draft, tag, parts) {
+	const block = new RegExp(`<${escape(tag)}(?=[\\s/>])[\\s\\S]*?</${escape(tag)}\\s*>`, "g");
+	draft.replace(block, (match) => match[0].replace(/data-xh-part=(["'])([\w-]+)\1/g, (whole, quote, part) => {
+		const next = parts[part];
+		return next ? `data-xh-part=${quote}${next}${quote}` : whole;
+	}));
+}
+/** 部件改名：自写皮肤里 [data-scope][data-part] 与挂载类的写法，Web Components 元素里的 data-xh-part。 */
+function renamePart(draft, { components, from, to }) {
+	for (const scope of components) {
+		const part = `(\\[data-part=(['"]?))${escape(from)}(\\2\\])`;
+		draft.replace(new RegExp(`(\\[data-scope=(['"]?)${escape(scope)}\\2\\]|\\.xh-scope-${escape(scope)}(?![\\w-]))${part}`, "g"), (match) => `${match[1]}${match[3]}${to}${match[5]}`);
+		renamePartsInside(draft, `xh-${scope}`, { [from]: to });
+	}
+}
+/** Web Components 的事件监听：够独特的事件直接改名，与原生事件同名的只报出来。 */
+function rewriteListeners(draft, rule) {
+	const pattern = new RegExp(`((?:add|remove)EventListener\\(\\s*)(['"\`])${escape(rule.from)}\\2`, "g");
+	if (rule.distinctive) {
+		draft.replace(pattern, (match) => `${match[1]}${match[2]}${rule.to}${match[2]}`);
+		return;
+	}
+	if (!new RegExp(rule.components.map((scope) => `<xh-${escape(scope)}(?=[\\s/>])|['"\`]xh-${escape(scope)}['"\`]|Xh${pascal(scope)}Element`).join("|")).test(draft.text)) return;
+	for (const match of draft.text.matchAll(pattern)) draft.report(match.index, `${rule.components.join("、")} 的 ${rule.from} 事件改名 ${rule.to}；这里监听的若是这些元素，改成 '${rule.to}'`);
+}
+/** 本 major 删掉、迁移后仍出现的名字逐个报出来。 */
+function reportRemoved(draft, major, surface) {
+	const { removed } = surface;
+	const text = draft.text;
+	const words = /* @__PURE__ */ new Map();
+	for (const match of text.matchAll(/[A-Z_$][\w$]*/gi)) if (!words.has(match[0])) words.set(match[0], match.index);
+	const importedFrom = /* @__PURE__ */ new Map();
+	for (const match of text.matchAll(/import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g)) for (const spec of parseSpecifiers(match[1])) importedFrom.set(spec.name, [...importedFrom.get(spec.name) ?? [], match[2]]);
+	for (const [pkg, names] of Object.entries(removed.exports)) for (const name of names) {
+		const at = words.get(name);
+		const modules = importedFrom.get(name);
+		const fromPackage = modules?.some((module) => module === pkg || module.startsWith(`${pkg}/`));
+		if (at !== void 0 && (fromPackage || !modules && name.startsWith("Xh"))) draft.report(at, `${name}（${pkg}）在 ${major}.0 删除了，按更新日志改写`);
+	}
+	for (const subpath of removed.subpaths) {
+		const at = text.search(new RegExp(`['"]${escape(subpath)}['"]`));
+		if (at >= 0) draft.report(at, `子入口 ${subpath} 在 ${major}.0 删除了`);
+	}
+	const tokens = (pattern) => {
+		const out = /* @__PURE__ */ new Map();
+		for (const match of text.matchAll(pattern)) if (!out.has(match[1])) out.set(match[1], match.index);
+		return out;
+	};
+	const variables = tokens(/(--xh-[\w-]+)/g);
+	for (const name of removed.cssVariables) {
+		const at = variables.get(name);
+		if (at !== void 0) draft.report(at, `${name} 在 ${major}.0 删除了，按更新日志改写`);
+	}
+	const kebabWords = tokens(/(?<![\w-])((?:xh|data)-[\w-]+)/g);
+	for (const name of [...removed.keyframes, ...removed.dataAttributes]) {
+		const at = kebabWords.get(name);
+		if (at !== void 0) draft.report(at, `${name} 在 ${major}.0 删除了，按更新日志改写`);
+	}
+	for (const element of removed.elements) {
+		const at = text.search(new RegExp(`<${escape(element)}(?=[\\s/>])|['"\`]${escape(element)}['"\`]`));
+		if (at >= 0) draft.report(at, `<${element}> 在 ${major}.0 删除了，按更新日志改写`);
+	}
+	for (const [scope, parts] of Object.entries(removed.parts)) for (const part of parts) {
+		const at = text.search(new RegExp(`(?:\\[data-scope=(['"]?)${escape(scope)}\\1\\]|\\.xh-scope-${escape(scope)}(?![\\w-]))\\[data-part=(['"]?)${escape(part)}\\2\\]`));
+		if (at >= 0) draft.report(at, `${scope} 的部件 ${part} 在 ${major}.0 删除了，按更新日志改写选择器`);
+	}
+}
+/** 按从低到高的几套规则改一份源码。 */
+function migrateSource(text, dialect, migrations) {
+	if (!LIBRARY.test(text)) return {
+		text,
+		edits: 0,
+		findings: []
+	};
+	const draft = new Draft(text);
+	for (const migration of migrations) migrateMajor(draft, dialect, migration);
+	return {
+		text: draft.text,
+		edits: draft.edits,
+		findings: draft.findings
+	};
+}
+/** 不进去的目录：依赖、产物与点开头的目录（.git、.nuxt 一类）。 */
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	"dist",
+	"build",
+	"coverage",
+	"out"
+]);
+function* sourceFiles(entry) {
+	let stat;
+	try {
+		stat = statSync(entry);
+	} catch {
+		return;
+	}
+	if (stat.isFile()) {
+		if (dialectOf(entry)) yield entry;
+		return;
+	}
+	for (const dirent of readdirSync(entry, { withFileTypes: true })) {
+		if (dirent.name.startsWith(".") || SKIP_DIRS.has(dirent.name)) continue;
+		yield* sourceFiles(join(entry, dirent.name));
+	}
+}
+/** 迁移一组文件或目录；write 为假时只算不写。 */
+function migrateProject(options) {
+	const files = [];
+	for (const path of options.paths) for (const file of sourceFiles(resolve(options.cwd, path))) {
+		const text = readFileSync(file, "utf8");
+		const result = migrateSource(text, dialectOf(file), options.migrations);
+		if (result.edits === 0 && result.findings.length === 0) continue;
+		if (options.write && result.text !== text) writeFileSync(file, result.text);
+		files.push({
+			file: relative(options.cwd, file).split(sep).join("/"),
+			edits: result.edits,
+			findings: result.findings
+		});
+	}
+	return {
+		from: options.from,
+		to: options.to,
+		majors: options.migrations.map(({ rules }) => rules.major),
+		files: files.sort((a, b) => a.file.localeCompare(b.file)),
+		notes: options.migrations.map(({ rules }) => ({
+			major: rules.major,
+			notes: rules.notes
+		})),
+		written: options.write
+	};
+}
+/** 迁移结果写成给人看的 markdown。 */
+function renderMigration(report) {
+	const changed = report.files.filter((file) => file.edits > 0);
+	const edits = changed.reduce((sum, file) => sum + file.edits, 0);
+	const lines = [
+		`# 迁移 ${report.from}.x → ${report.to}.0`,
+		"",
+		`依次套用 ${report.majors.map((major) => `${major}.0`).join("、")} 的规则：${changed.length > 0 ? `改写 ${changed.length} 个文件，共 ${edits} 处` : "没有要改的地方"}${report.written || changed.length === 0 ? "" : "（未写回）"}。`
+	];
+	if (changed.length > 0) lines.push("", ...changed.map((file) => `- ${file.file}：${file.edits} 处`));
+	const findings = report.files.flatMap((file) => file.findings.map((finding) => `- ${file.file}:${finding.line}  ${finding.message}`));
+	if (findings.length > 0) lines.push("", `## 要人工处理（${findings.length} 处）`, "", ...findings);
+	for (const { major, notes } of report.notes) if (notes.length > 0) lines.push("", `## ${major}.0 升级须知里改不了代码的`, "", ...notes.map((note) => `- ${note}`));
+	return lines.join("\n");
+}
+//#endregion
+//#region src/migrations/index.ts
+const RULES = [
+	{
+		major: 2,
+		modules: {
+			"@xihan-ui/kernel/metadata": "@xihan-ui/core/metadata",
+			"@xihan-ui/kernel/skin-check": "@xihan-ui/core/skin-check",
+			"@xihan-ui/kernel/vite": "@xihan-ui/core/vite",
+			"@xihan-ui/machine/vanilla": "@xihan-ui/core/vanilla",
+			"@xihan-ui/behavior/presence": "@xihan-ui/core/presence",
+			"@xihan-ui/kernel": "@xihan-ui/core",
+			"@xihan-ui/machine": "@xihan-ui/core",
+			"@xihan-ui/behavior": "@xihan-ui/core"
+		},
+		components: {
+			Ellipsis: "Truncate",
+			DynamicInput: "FieldArray",
+			Time: "Timestamp",
+			QrCode: "MatrixCode",
+			Calendar: "CalendarPicker",
+			Result: "EmptyState",
+			Space: "Flex",
+			Countdown: "Timer"
+		},
+		props: [
+			{
+				components: ["password-input"],
+				from: "visible",
+				to: "revealed"
+			},
+			{
+				components: ["password-input"],
+				from: "defaultVisible",
+				to: "defaultRevealed"
+			},
+			{
+				components: ["resizable", "floating-panel"],
+				from: "size",
+				to: "dimensions"
+			},
+			{
+				components: ["resizable", "floating-panel"],
+				from: "defaultSize",
+				to: "defaultDimensions"
+			},
+			{
+				components: ["floating-panel"],
+				from: "stage",
+				to: "windowState"
+			},
+			{
+				components: ["floating-panel"],
+				from: "defaultStage",
+				to: "defaultWindowState"
+			},
+			{
+				components: ["table"],
+				from: "expanded",
+				to: "expandedValue"
+			},
+			{
+				components: ["table"],
+				from: "defaultExpanded",
+				to: "defaultExpandedValue"
+			},
+			{
+				components: ["steps", "tour"],
+				from: "step",
+				to: "value"
+			},
+			{
+				components: ["steps", "tour"],
+				from: "defaultStep",
+				to: "defaultValue"
+			},
+			{
+				components: ["mention"],
+				from: "prefix",
+				to: "triggerPrefix"
+			},
+			{
+				components: ["image-viewer"],
+				from: "items",
+				to: "collection"
+			},
+			{
+				components: ["toast"],
+				from: "type",
+				to: "tone"
+			},
+			{
+				components: ["listbox"],
+				from: "multiple",
+				to: "selectionMode",
+				booleanTo: "multiple"
+			}
+		],
+		events: [
+			{
+				components: ["password-input"],
+				from: "visibility-change",
+				to: "revealed-change",
+				distinctive: true
+			},
+			{
+				components: ["back-top"],
+				from: "visible-change",
+				to: "visibility-change",
+				distinctive: true
+			},
+			{
+				components: ["resizable", "floating-panel"],
+				from: "size-change",
+				to: "dimensions-change",
+				distinctive: true
+			},
+			{
+				components: ["resizable"],
+				from: "size-change-end",
+				to: "dimensions-change-end",
+				distinctive: true
+			},
+			{
+				components: ["floating-panel"],
+				from: "stage-change",
+				to: "window-state-change",
+				distinctive: true
+			},
+			{
+				components: [
+					"json-viewer",
+					"side-nav",
+					"table",
+					"tree",
+					"tree-select"
+				],
+				from: "expanded-change",
+				to: "expanded-value-change",
+				distinctive: true
+			},
+			{
+				components: ["steps", "tour"],
+				from: "step-change",
+				to: "value-change"
+			},
+			{
+				components: ["number-animation"],
+				from: "finish",
+				to: "complete"
+			},
+			{
+				components: ["virtualizer"],
+				from: "change",
+				to: "range-change"
+			}
+		],
+		parts: [
+			{
+				components: ["alert", "empty-state"],
+				from: "icon",
+				to: "indicator"
+			},
+			{
+				components: ["avatar-group"],
+				from: "overflow",
+				to: "overflow-item"
+			},
+			{
+				components: ["checkbox-group"],
+				from: "trigger",
+				to: "select-all-trigger"
+			},
+			{
+				components: ["clipboard"],
+				from: "trigger",
+				to: "copy-trigger"
+			},
+			{
+				components: ["combobox", "listbox"],
+				from: "item-group",
+				to: "group"
+			},
+			{
+				components: ["combobox", "listbox"],
+				from: "item-group-label",
+				to: "group-label"
+			},
+			{
+				components: ["date-picker", "time-picker"],
+				from: "presets",
+				to: "preset-group"
+			},
+			{
+				components: ["fieldset"],
+				from: "helper-text",
+				to: "description"
+			},
+			{
+				components: ["file-upload"],
+				from: "item-group",
+				to: "list"
+			},
+			{
+				components: ["floating-panel"],
+				from: "stage-trigger",
+				to: "window-state-trigger"
+			},
+			{
+				components: ["heatmap"],
+				from: "week-day-label",
+				to: "week-day"
+			},
+			{
+				components: ["page-header"],
+				from: "subtitle",
+				to: "description"
+			},
+			{
+				components: ["pagination"],
+				from: "ellipsis",
+				to: "ellipsis-trigger"
+			},
+			{
+				components: ["signature-pad"],
+				from: "segment",
+				to: "path"
+			},
+			{
+				components: ["skeleton"],
+				from: "bone",
+				to: "item"
+			},
+			{
+				components: ["slider"],
+				from: "mark",
+				to: "tick"
+			},
+			{
+				components: ["slider"],
+				from: "mark-label",
+				to: "tick-label"
+			},
+			{
+				components: ["slider"],
+				from: "marks",
+				to: "tick-group"
+			},
+			{
+				components: ["sortable"],
+				from: "item-handle",
+				to: "item-drag-trigger"
+			},
+			{
+				components: ["table"],
+				from: "loading-state",
+				to: "loading"
+			},
+			{
+				components: ["timer"],
+				from: "area",
+				to: "display"
+			},
+			{
+				components: ["card"],
+				from: "body",
+				to: "content"
+			}
+		],
+		dataAttributes: {
+			"data-affixed": "data-fixed",
+			"data-stage": "data-window-state",
+			"data-target-stage": "data-target-window-state"
+		},
+		manual: [
+			{
+				pattern: /\bdata-borderless\b/,
+				message: "data-borderless 删除，改认 data-bordered，取值反转"
+			},
+			{
+				pattern: /\bdata-type\b/,
+				message: "data-type 拆分为 data-value-type、data-severity、data-select-mode、data-reveal-mode、data-format，按组件改认"
+			},
+			{
+				pattern: /\bdata-(?:phase|status)\b/,
+				message: "data-phase 与六个组件的生命周期 data-status 并入 data-state"
+			},
+			{
+				pattern: /\b(?:XhThread|XhComposer|XhCodeBlock)\w*|<xh-(?:thread|composer|code-block)\b/,
+				message: "thread、composer、code-block 删除，分别改用 message-feed（配合 log）、prompt-input、code-view"
+			},
+			{
+				pattern: /\bXhPopselect\w*|<xh-popselect\b/,
+				message: "popselect 退役：随表单提交的场景改用 select，仅切换视图参数的场景改用 popover 组合 listbox"
+			},
+			{
+				pattern: /\bXhSpace\b|<xh-space\b/,
+				message: "space 并入 flex：XhSpace 未写 gap 时缺省有间距，XhFlex 缺省为 0，迁移后显式写 gap=\"md\""
+			},
+			{
+				pattern: /\bXhResult\w*|<xh-result\b/,
+				message: "result 并入 empty-state：live 缺省为 polite、缺省尺寸小一号，保持原样写 live=\"off\" 与 size=\"lg\""
+			},
+			{
+				pattern: /(?:\bXhFlex|<xh-flex\b)[^>]*\s:?direction=/,
+				message: "flex 的 direction 别名删除，只保留 orientation"
+			},
+			{
+				pattern: /(?:\bXh(?:Descriptions|List|Layout|PageHeader)|<xh-(?:descriptions|list|layout|page-header)\b)[^>]*\s:?bordered\b|(?:\bXhTable|<xh-table\b)[^>]*\s:?borderless\b/,
+				message: "descriptions、list、layout、page-header 的 bordered 与 table 的 borderless 改为 variant 形态轴"
+			},
+			{
+				pattern: /\b(?:XhConfig|xhConfig)\b[\s\S]{1,80}\bmotion\b/,
+				message: "XhConfig.motion 的隐式全局覆盖移除，视觉环境统一由 createVisualEnvironmentController 管理"
+			},
+			{
+				pattern: /\bXhFormFieldGroup\b[^>]*\b:?value=/,
+				message: "XhFormFieldGroup 的 value 改名为 name（表单字段标识统一为 FormPath）"
+			}
+		],
+		notes: [
+			"@xihan-ui/kernel、machine、behavior 合并为 @xihan-ui/core，旧包不再发布：导入路径已改，package.json 里的依赖换成 @xihan-ui/core",
+			"@xihan-ui/code-highlight 改为可选 peer 依赖，用代码着色的项目自行安装",
+			"select、tags-input、tag-group 的标签统一改用 tag 组件渲染：item-delete-trigger、item-preview、item-text 对应 tag 的 root / label / close-trigger",
+			"部件上同名事件处理器统一为使用者的先执行；pin-input 按顺序录入；combobox 等的原生表单提交改为每个值一个同名隐藏字段",
+			"读屏文案只接受函数；kbd 的单键与组合键统一为 keys 数组；grid 的 cols / span / offset 增加取值范围校验"
+		]
+	},
+	{
+		major: 3,
+		identifiers: {
+			XhToastRoot: {
+				to: "XhNotificationItem",
+				attrs: "preset=\"toast\""
+			},
+			XhToastRootProps: "XhNotificationItemProps",
+			XhToastIndicator: "XhNotificationItemIndicator",
+			XhToastIndicatorProps: "XhNotificationItemIndicatorProps",
+			XhToastContent: "XhNotificationItemContent",
+			XhToastContentProps: "XhNotificationItemContentProps",
+			XhToastTitle: "XhNotificationItemTitle",
+			XhToastTitleProps: "XhNotificationItemTitleProps",
+			XhToastDescription: "XhNotificationItemDescription",
+			XhToastDescriptionProps: "XhNotificationItemDescriptionProps",
+			XhToastActionTrigger: "XhNotificationItemActionTrigger",
+			XhToastActionTriggerProps: "XhNotificationItemActionTriggerProps",
+			XhToastProgress: "XhNotificationItemProgress",
+			XhToastProgressProps: "XhNotificationItemProgressProps",
+			XhToastCloseTrigger: "XhNotificationItemCloseTrigger",
+			XhToastCloseTriggerProps: "XhNotificationItemCloseTriggerProps",
+			useToast: "useNotificationItem",
+			ToastContext: "NotificationItemContext",
+			useToastContext: "useNotificationItemContext",
+			ToastRootSlotProps: "NotificationItemSlotProps",
+			createToastService: "createNotificationService",
+			ToastService: "NotificationService",
+			ToastServiceOptions: "NotificationServiceOptions",
+			ToastCreateOptions: "NotificationCreateOptions",
+			ToastMessageOptions: "NotificationMessageOptions",
+			ToastPromiseOptions: "NotificationPromiseOptions",
+			withToastSound: "withNotificationSound",
+			ToastSoundOptions: "NotificationSoundOptions",
+			withToastSoundService: "withNotificationSoundService",
+			ToastSoundServicePort: "NotificationSoundServicePort",
+			ToastSoundServiceOptions: "NotificationSoundServiceOptions",
+			ToastSoundKey: "NotificationSoundKey",
+			toastMachine: "notificationItemMachine",
+			ToastSchema: "NotificationItemSchema",
+			ToastApi: "NotificationItemApi",
+			connectToast: "connectNotificationItem",
+			toastAnatomy: "notificationAnatomy",
+			toastKeyboard: "notificationKeyboard",
+			toastMeta: "notificationMeta",
+			resolveToastId: "resolveNotificationItemId",
+			ToastTone: "NotificationTone",
+			ToastRecord: "NotificationRecord",
+			ToastTranslations: "NotificationTranslations",
+			ToastActionDetails: "NotificationActionDetails",
+			ToastPauseSource: "NotificationPauseSource",
+			ToastPressedPart: "NotificationPressedPart",
+			ToastStatusChangeDetails: "NotificationStatusChangeDetails",
+			XhSegmentedRoot: {
+				to: "XhRadioGroupRoot",
+				attrs: "variant=\"segmented\""
+			},
+			XhSegmentedRootProps: "XhRadioGroupRootProps",
+			XhSegmentedIndicator: "XhRadioGroupThumb",
+			XhSegmentedIndicatorProps: "XhRadioGroupThumbProps",
+			XhSegmentedItem: "XhRadioGroupItem",
+			XhSegmentedItemProps: "XhRadioGroupItemProps",
+			XhSegmentedItemText: "XhRadioGroupItemText",
+			XhSegmentedItemTextProps: "XhRadioGroupItemTextProps",
+			useSegmented: "useRadioGroup",
+			useSegmentedContext: "useRadioGroupContext",
+			useSegmentedItemContext: "useRadioGroupItemContext",
+			SegmentedContext: "RadioGroupContext",
+			timePickerColumns: "timeColumns",
+			timePickerColumnsFor: "timeColumnsFor",
+			timePickerItemValue: "timeItemValue",
+			TimePickerColumnsOptions: "TimeColumnsOptions"
+		},
+		elements: [{
+			from: "xh-toast",
+			to: "xh-notification-item",
+			attrs: "preset=\"toast\"",
+			parts: {
+				"root": "item",
+				"indicator": "item-indicator",
+				"content": "item-content",
+				"title": "item-title",
+				"description": "item-description",
+				"action-trigger": "item-action-trigger",
+				"progress": "item-progress",
+				"close-trigger": "item-close-trigger"
+			}
+		}, {
+			from: "xh-segmented",
+			to: "xh-radio-group",
+			attrs: "variant=\"segmented\"",
+			parts: { indicator: "thumb" }
+		}],
+		cssVariables: {
+			"--xh-spin-duration": "--xh-motion-loop-spin",
+			"--xh-caret-duration": "--xh-motion-loop-caret",
+			"--xh-shimmer-duration": "--xh-motion-loop-shimmer",
+			"--xh-toast-icon-fg": "--xh-notification-indicator-fg",
+			"--xh-toast-scale-collapsed": "--xh-notification-stack-scale",
+			"--xh-segmented-bg": "--xh-radio-group-track-bg",
+			"--xh-segmented-bg-disabled": "--xh-radio-group-track-bg-disabled",
+			"--xh-segmented-border": "--xh-radio-group-track-border",
+			"--xh-segmented-border-invalid": "--xh-radio-group-track-border-invalid",
+			"--xh-segmented-radius": "--xh-radio-group-track-radius",
+			"--xh-segmented-track-padding": "--xh-radio-group-track-padding",
+			"--xh-segmented-item-bg-hover": "--xh-radio-group-segment-bg-hover",
+			"--xh-segmented-item-bg-pressed": "--xh-radio-group-segment-bg-pressed",
+			"--xh-segmented-item-fg": "--xh-radio-group-segment-fg",
+			"--xh-segmented-item-fg-checked": "--xh-radio-group-segment-fg-checked",
+			"--xh-segmented-item-fg-checked-disabled": "--xh-radio-group-segment-fg-checked-disabled",
+			"--xh-segmented-item-fg-hover": "--xh-radio-group-segment-fg-hover",
+			"--xh-segmented-item-font-weight": "--xh-radio-group-segment-font-weight",
+			"--xh-segmented-item-h": "--xh-radio-group-segment-h",
+			"--xh-segmented-item-px": "--xh-radio-group-segment-px",
+			"--xh-segmented-item-radius": "--xh-radio-group-segment-radius",
+			"--xh-segmented-indicator-bg": "--xh-radio-group-thumb-bg",
+			"--xh-segmented-indicator-border": "--xh-radio-group-thumb-border",
+			"--xh-segmented-indicator-radius": "--xh-radio-group-thumb-radius",
+			"--xh-segmented-indicator-shadow": "--xh-radio-group-thumb-shadow",
+			"--xh-segmented-indicator-shadow-disabled": "--xh-radio-group-thumb-shadow-disabled",
+			"--xh-icon-wrapper-size": "--xh-icon-frame-size",
+			"--xh-icon-wrapper-glyph-size": "--xh-icon-frame-glyph-size",
+			"--xh-icon-wrapper-radius": "--xh-icon-frame-radius",
+			"--xh-icon-wrapper-bg": "--xh-icon-frame-bg",
+			"--xh-icon-wrapper-shadow": "--xh-icon-frame-shadow",
+			"--xh-gradient-text-from": "--xh-typography-gradient-from",
+			"--xh-gradient-text-to": "--xh-typography-gradient-to"
+		},
+		keyframes: {
+			"xh-toast-in": "xh-notification-stack-in",
+			"xh-toast-out": "xh-notification-stack-out",
+			"xh-spinner-rotate": "xh-spin",
+			"xh-popconfirm-rotate": "xh-spin",
+			"xh-switch-rotate": "xh-spin",
+			"xh-toast-spin": "xh-spin",
+			"xh-approval-rotate": "xh-spin",
+			"xh-clipboard-rotate": "xh-spin",
+			"xh-download-trigger-rotate": "xh-spin",
+			"xh-notification-spin": "xh-spin",
+			"xh-reasoning-shimmer": "xh-shimmer",
+			"xh-tool-call-shimmer": "xh-shimmer",
+			"xh-skeleton-shimmer": "xh-shimmer",
+			"xh-approval-in": "xh-item-in",
+			"xh-message-feed-item-in": "xh-item-in",
+			"xh-question-flow-in": "xh-item-in",
+			"xh-tool-call-enter": "xh-item-in",
+			"xh-approval-result-in": "xh-pop-in",
+			"xh-message-feed-button-in": "xh-pop-in",
+			"xh-question-flow-result-in": "xh-pop-in",
+			"xh-log-button-in": "xh-pop-in",
+			"xh-reasoning-fade-in": "xh-fade-in",
+			"xh-clipboard-loading-reveal": "xh-fade-in",
+			"xh-download-trigger-loading-reveal": "xh-fade-in",
+			"xh-clipboard-loading-hide": "xh-fade-out",
+			"xh-diff-view-reveal": "xh-drop-in",
+			"xh-form-summary-enter": "xh-drop-in",
+			"xh-dialog-in": "xh-sheet-in",
+			"xh-dialog-out": "xh-sheet-out",
+			"xh-notification-in": "xh-sheet-in",
+			"xh-notification-out": "xh-sheet-out",
+			"xh-drawer-in-top": "xh-slide-in",
+			"xh-drawer-in-right": "xh-slide-in",
+			"xh-drawer-in-bottom": "xh-slide-in",
+			"xh-drawer-in-left": "xh-slide-in",
+			"xh-drawer-out-top": "xh-slide-out",
+			"xh-drawer-out-right": "xh-slide-out",
+			"xh-drawer-out-bottom": "xh-slide-out",
+			"xh-drawer-out-left": "xh-slide-out"
+		},
+		manual: [
+			{
+				pattern: /\bcreateToastService\s*\(/,
+				message: "createToastService(options) 改为 createNotificationService({ preset: 'toast', ...options })：名字已改，补上 preset: 'toast'，否则是两层卡片"
+			},
+			{
+				pattern: /\btoastTranslations\b/,
+				message: "通知服务的选项 toastTranslations 改为 translations；全局配置的文案桶 translations.toast 改为 translations.notification"
+			},
+			{
+				pattern: /\bresolveToastDuration\b/,
+				message: "resolveToastDuration(loading, duration) 改为 resolveNotificationDuration(loading, duration, preset)"
+			},
+			{
+				pattern: /\b(?:removeDelay|remove-delay|TOAST_REMOVE_DELAY)\b/,
+				message: "Toast 与 Notification 删除了固定退场窗口 removeDelay，改为等退场动画播完再卸载；要调时长覆盖 --xh-motion-duration-exit"
+			},
+			{
+				pattern: /\bXhIconWrapper\b|<xh-icon-wrapper\b/,
+				message: "IconWrapper 并入 Icon：底框写在图标自己身上，variant 改名 frame，如 <XhIcon :icon=\"FolderIcon\" frame=\"subtle\" tone=\"brand\" size=\"lg\" />"
+			},
+			{
+				pattern: /\bXhGradientText\b|<xh-gradient-text\b/,
+				message: "GradientText 并入 Typography：写成 XhTypographyRoot 里的 XhTypographyText variant=\"gradient\"，from / to / direction 改为 --xh-typography-gradient-* 覆盖槽"
+			},
+			{
+				pattern: /\bXhSegmentedHiddenInput\b/,
+				message: "分段控件并入单选组后每个条目一份原生 radio，不再有整组的 hidden-input，删掉这个部件"
+			},
+			{
+				pattern: /\bscrollElement\b|\bscroll-element\b|\bgetScrollEl\b/,
+				message: "Anchor 的滚动容器 scrollElement 改名 target（与 Affix、BackTop 一致），Headless refs getScrollEl 改为 getTargetEl"
+			},
+			{
+				pattern: /(?:\bXhTime(?:Range)?Picker|<xh-time(?:-range)?-picker\b)[^>]*\s:?step=/,
+				message: "TimePicker / TimeRangePicker 删除 step，改为按单位的 timeStep：step={15} 改为 timeStep={{ minute: 15 }}（Web Components time-step='{\"minute\":15}'）"
+			},
+			{
+				pattern: /\bisTimeUnavailable\b/,
+				message: "isTimeUnavailable 改为 (value, unit, context)：时列的 value 恒按 24 小时制，TimeRangePicker 原第三个参数 index 挪进 context.index"
+			},
+			{
+				pattern: /\b(?:TOAST|NOTIFICATION)_(?:DURATION|GAP|MAX|PLACEMENT)\b/,
+				message: "轻提示与通知的缺省常量改读 NOTIFICATION_PRESETS.<preset> 或 notificationPresetOf(preset)"
+			},
+			{
+				pattern: /\[data-scope=['"]?toast['"]?\]/,
+				message: "[data-scope='toast'][data-part='root'] 改认 [data-scope='notification'][data-part='item'][data-preset='toast']，其余部件改认 item-<部件>"
+			},
+			{
+				pattern: /\[data-scope=['"]?segmented['"]?\]/,
+				message: "分段控件的选择器改认 [data-scope='radio-group'][data-variant='segmented']，指示块改认 thumb 部件"
+			}
+		],
+		notes: [
+			"Notification、Toast 的叠放测量槽（--xh-toast-offset-collapsed、--xh-toast-height 等）不再公开，叠放收拢比例改由 --xh-motion-scale-stack 逐层计算",
+			"键盘统一为 APG 单选组：segmented 形态按 Enter 不再选中，Home / End 不再跳到首末段",
+			"缺省值与外观：减弱动效改为去掉位移、保留淡变；Select、Combobox、TreeSelect 的候选面板与字段盒等宽；Tooltip 新增接替窗口 skipDelayDuration",
+			"Headless 的 Badge、EmptyState、Marquee、Skeleton、Spinner、Timestamp、Watermark 改由状态机驱动：connectX(props, normalize) 改为 connectX(service, normalize)",
+			"@xihan-ui/motion 的缓动表删除 decelerate 与 accelerate，resolveEasing 认不出写法时抛 TypeError"
+		]
+	},
+	{
+		major: 4,
+		notes: [
+			"缺省值：Accordion variant 改为 outline、Tree variant 改为 ghost、Badge tone 改为 danger，日历的 weekdayFormat 改为 narrow；要保持原样请显式传值",
+			"Fieldset 的禁用会压到整棵子树；Web Components 的字段族宿主缺省 display: contents，写在宿主上的宽度与外边距改写到 root 或用 --xh-control-w",
+			"令牌：控件高 sm / md / lg 为 28 / 32 / 36px，圆角 2 / 4 / 8px，--xh-motion-scale-press 为 1（主题写回 0.97 可恢复按下回弹）",
+			"删掉的组件覆盖槽集中在字段聚焦环、Dialog、Slider 与日期时间面板，下面逐个报出写到它们的地方"
+		]
+	},
+	{
+		major: 5,
+		imports: [
+			{
+				from: "@xihan-ui/headless",
+				to: "@xihan-ui/core/color",
+				names: {
+					colorCss: true,
+					colorHexToRgba: true,
+					colorHslaToRgba: true,
+					colorHsvaToRgba: true,
+					colorNormalizeHsva: true,
+					colorNormalizeRgba: true,
+					colorOklchToRgba: true,
+					colorParse: true,
+					colorRgbaToHex: true,
+					colorRgbaToHsla: true,
+					colorRgbaToHsva: true,
+					colorRgbaToOklch: true,
+					colorSameColor: true,
+					colorSameRgba: true,
+					colorToString: true,
+					ColorFormat: true,
+					ColorHsla: true,
+					ColorHsva: true,
+					ColorOklch: true,
+					ColorRgba: true
+				}
+			},
+			{
+				from: "@xihan-ui/headless",
+				to: "@xihan-ui/core/hotkey",
+				names: {
+					detectKbdPlatform: true,
+					formatHotkey: true,
+					matchesHotkey: true,
+					resolveKbdPlatform: true,
+					HotkeySegment: true,
+					KbdPlatform: true,
+					KbdResolvedPlatform: true
+				}
+			},
+			{
+				from: "@xihan-ui/tokens",
+				to: "@xihan-ui/core/color",
+				names: {
+					srgbToLinear: "colorSrgbToLinear",
+					linearToSrgb: "colorLinearToSrgb",
+					linearRgbToOklch: "colorLinearRgbToOklch",
+					oklchToLinearRgb: "colorOklchToLinearRgb",
+					parseColorToOklch: "colorParseOklch",
+					inSrgbGamut: "colorInSrgbGamut",
+					clampChroma: "colorClampChroma",
+					formatOklch: "colorFormatOklch",
+					Oklch: "ColorOklch"
+				}
+			}
+		],
+		identifiers: {
+			HeatmapCellDetails: "HeatmapDatumDetails",
+			MenuSelectDetails: "MenuItemSelectDetails",
+			ContextMenuSelectDetails: "ContextMenuItemSelectDetails",
+			MenubarSelectDetails: "MenubarItemSelectDetails",
+			CommandSelectDetails: "CommandItemSelectDetails",
+			MentionSelectDetails: "MentionItemSelectDetails"
+		},
+		props: [
+			{
+				components: ["tree"],
+				from: "multiple",
+				to: "selectionMode",
+				booleanTo: "multiple"
+			},
+			{
+				components: ["table"],
+				from: "footer",
+				to: "footerRows",
+				booleanTo: 1
+			},
+			{
+				components: ["dialog", "drawer"],
+				from: "role",
+				to: "dialogRole",
+				only: "web-components"
+			},
+			{
+				components: ["notification"],
+				from: "title",
+				to: "titleText",
+				only: "web-components"
+			}
+		],
+		events: [
+			{
+				components: ["heatmap"],
+				from: "cell-press",
+				to: "datum-press",
+				distinctive: true
+			},
+			{
+				components: ["heatmap"],
+				from: "cell-active",
+				to: "datum-active",
+				distinctive: true
+			},
+			{
+				components: [
+					"menu",
+					"context-menu",
+					"menubar",
+					"command",
+					"mention"
+				],
+				from: "select",
+				to: "item-select"
+			},
+			{
+				components: ["popconfirm"],
+				from: "cancel",
+				to: "cancel-press"
+			}
+		],
+		manual: [
+			{
+				pattern: /\bbuildPeriodGrid\b[\s\S]{0,200}?\.cells\b/,
+				message: "日历族的周、月、季度、年视图改为按行渲染：buildPeriodGrid 的 cells 改为 rows，自备格子列表用 calendarPeriodRows(periods, view) 切行"
+			},
+			{
+				pattern: /\bgetFooterRowProps\(\s*\)/,
+				message: "表格的 getFooterRowProps() 改为 getFooterRowProps({ level })，多行表尾每行写 level"
+			},
+			{
+				pattern: /\b(?:getTitleEl|getDescriptionEl|setTitleEl|setDescriptionEl)\b/,
+				message: "HoverCard 删去了标题、说明的 refs：自写的标题、说明部件改为经 parts 报告在场"
+			},
+			{
+				pattern: /\bopenSource\b/,
+				message: "Citation 的语言包删除了 openSource、source，覆盖过的直接去掉"
+			}
+		],
+		notes: [
+			"菜单族的 item-indicator 只当对号、只在勾选与单选条目上出现；当图标用的改写 item-icon（ItemIcon）",
+			"Web Components FileUpload 的条目改按 allFiles 对应（远程附件在前、本地文件在后），用了 remoteFiles 的改按 allFiles 铺行",
+			"表单校验：只含空白的字符串与元素全为空的数组算空，min / max 对字符串改按字素计数",
+			"React Card：XhCardRoot 的 title、content 改为卡片的标题与正文，不再作为原生属性写到根上",
+			"Web Components 布尔属性改为三态：显式写 =\"false\" 为假，不写交给组件缺省",
+			"缺省结构：根组件不写子内容时铺出整套部件；渲染成 <button> 的部件清掉了浏览器缺省样式",
+			"ColorPicker 单选给空数组改为未选，要黑色的改写 ['#000000']",
+			"headless 直接用状态机的：菜单族的 onSelect 改为 onItemSelect，Popconfirm 的 onCancel 改为 onCancelPress"
+		]
+	}
+];
+/** 有迁移规则的最新 major。 */
+const LATEST_MAJOR = RULES.at(-1).major;
+/**
+* 公开面差异有一百多 kB，不打进包：源码里它与本文件同目录，构建时 tsdown 把它拷到 dist/，
+* 与打包后的本模块同目录。只在跑 migrate 时读一次。
+*/
+const SURFACE_FILE = "surface.generated.json";
+let diffs;
+function surfaceOf(major) {
+	diffs ??= JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), SURFACE_FILE), "utf8"));
+	const surface = diffs.find((diff) => diff.major === major);
+	if (!surface) throw new Error(`${SURFACE_FILE} 里没有 ${major} 的差异，先跑 node build/gen-migrations.mjs`);
+	return surface;
+}
+/** 从 from 迁到 to 要依次套用的几套规则：from 之后、to 及之前的每个 major。 */
+function migrationsBetween(from, to) {
+	return RULES.filter((rules) => rules.major > from && rules.major <= to).map((rules) => ({
+		rules,
+		surface: surfaceOf(rules.major)
+	}));
+}
+//#endregion
 //#region src/project.ts
 const ADAPTER_PACKAGES = [
 	["vue", "@xihan-ui/vue"],
@@ -1284,6 +2553,11 @@ const HELP = `xihan-ui —— XiHan.UI 的离线知识库与 MCP 服务端
   design.md                                      设计语言文档
   changelog [<版本> [<版本>]] [--keyword <词>]   更新日志，两个版本时取区间
 
+迁移
+  migrate <从版本> <到版本> [<路径>...]          按每个 major 的规则改写源码：导入、组件、属性、事件、部件、元素、
+        [--dry-run] [--check]                    CSS 变量与关键帧的改名；改不了的报出位置。路径缺省为当前目录，
+                                                 --dry-run 只列出不写回，--check 有要改的就以 1 退出
+
 集成
   mcp                                            以 stdio 启动 MCP 服务端
   setup --client <${CLIENTS.join("|")}>   写入 MCP 配置与技能
@@ -1413,6 +2687,30 @@ function query(command, positionals, values, knowledge, framework) {
 		default: throw new UsageError(`未知命令：${command}。xihan-ui --help 查看全部命令`);
 	}
 }
+/** 版本写法（4、4.2.0、v4、^4.2.0）取 major。 */
+function majorOf(version, usage) {
+	const match = /^\D*(\d+)/.exec(requireArg(version, usage));
+	if (!match) throw new UsageError(`版本写法认不出：${version}。用法：xihan-ui ${usage}`);
+	return Number(match[1]);
+}
+function runMigrate(positionals, values, out) {
+	const usage = "migrate <从版本> <到版本> [<路径>...]";
+	const from = majorOf(positionals[0], usage);
+	const to = majorOf(positionals[1], usage);
+	const latest = LATEST_MAJOR;
+	if (to <= from) throw new UsageError(`到版本（${to}）要比从版本（${from}）新`);
+	if (to > latest) throw new UsageError(`最新的一套迁移规则是 ${latest}.0，没有到 ${to}.0 的规则`);
+	const report = migrateProject({
+		migrations: migrationsBetween(from, to),
+		from,
+		to,
+		paths: positionals.length > 2 ? positionals.slice(2) : ["."],
+		cwd: out.cwd ?? process.cwd(),
+		write: !values["dry-run"] && !values.check
+	});
+	out.stdout(values.format === "json" ? JSON.stringify(report, null, 2) : renderMigration(report));
+	return values.check && report.files.some((file) => file.edits > 0) ? 1 : 0;
+}
 function runSetup(values, knowledge, out) {
 	const client = values.client;
 	if (typeof client !== "string" || !CLIENTS.includes(client)) throw new UsageError(`--client 只能是 ${CLIENTS.join(" / ")}`);
@@ -1488,6 +2786,10 @@ async function runCli(argv, environment = {}) {
 		return 0;
 	}
 	try {
+		if (command === "migrate") {
+			if (values.format !== void 0 && values.format !== "markdown" && values.format !== "json") throw new UsageError(`--format 只能是 markdown / json，收到 ${values.format}`);
+			return runMigrate(rest, values, out);
+		}
 		const knowledge = loadKnowledge(out.dataDir);
 		if (values.version) {
 			out.stdout(knowledge.meta.version);