pnpm-settings-migrator 0.7.0 → 0.8.1

package/dist/cli.mjs

@@ -1,86 +1,133 @@
 import process from "node:process";
-import { cac } from "cac";
 import consola$1, { consola } from "consola";
-import { resolve } from "pathe";
-import { Document, parse } from "yaml";
-import { access, readFile, rm, writeFile } from "node:fs/promises";
+import { cac } from "cac";
+import { basename, dirname, join, resolve } from "pathe";
+import { randomUUID } from "node:crypto";
+import { access, chmod, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
 import { getColor } from "consola/utils";
-import { isPlainObject, isUndefined, pick } from "@ntnyq/utils";
+import { isPlainObject, isUndefined } from "@ntnyq/utils";
 import { defu } from "defu";
 import camelcaseKeys from "camelcase-keys";
 import { readIniFile } from "read-ini-file";
 import { kebabCase } from "uncase";
+import { isDeepStrictEqual } from "node:util";
+import { Document, isMap, isNode, isScalar, isSeq, parseDocument, stringify } from "yaml";
 import detectIndent from "detect-indent";
 //#region package.json
 var name = "pnpm-settings-migrator";
-var version = "0.7.0";
+var version = "0.8.1";
+//#endregion
+//#region src/cli-options.ts
+/**
+* Create the command-line parser shared by the executable and parser tests.
+*/
+function createCli() {
+	const cli = cac(name).version(version).option("--cwd <cwd>", "Current working directory").option("--sort-keys", "Sort keys when write pnpm-workspace.yaml").option("--compatibility <compatibility>", "Compatibility target (auto, v10, v11, v12)").option("--replace-deprecated", "Replace deprecated pnpm settings with new ones and remove old keys").option("--strategy <strategy>", "Strategy to handle conflicts (discard, merge, overwrite)").option("--no-yarn-resolutions", "Disable migrating resolutions field in package.json").option("--no-newline-between", "Disable adding newlines between each root keys").option("--no-show-changes", "Disable showing settings changes").option("--no-clean-npmrc", "Disable removing pnpm settings in .npmrc file").option("--no-clean-package-json", "Disable removing pnpm fields in package.json");
+	cli.help((sections) => {
+		if (!(cli.commands.length > 0 && cli.commands.every((command) => command.isDefaultCommand))) return sections;
+		return sections.filter((section) => section.title !== "Commands" && !section.title?.startsWith("For more info"));
+	});
+	return cli;
+}
 //#endregion
 //#region src/constants.ts
 const NPMRC = ".npmrc";
 const PACKAGE_JSON = "package.json";
 const PNPM_WORKSPACE_YAML = "pnpm-workspace.yaml";
 /**
-* @see {@link https://github.com/pnpm/pnpm/blob/main/packages/types/src/package.ts}
-* Schema-aligned pnpm config fields that can be migrated from `.npmrc`.
+* @see {@link https://pnpm.io/10.x/settings}
+* Documented pnpm v10 config fields that can be migrated from `.npmrc`.
 *
 * Intentionally excluded workspace manifest-only fields:
 * - `catalog`
-* - `catalogMode`
 * - `catalogs`
-* - `cleanupUnusedCatalogs`
 * - `packages`
 */
-const PNPM_SETTINGS_FIELDS = [
+const PNPM_V10_NPMRC_SETTINGS_FIELDS = [
 	"allowBuilds",
 	"allowedDeprecatedVersions",
 	"allowNonAppliedPatches",
 	"allowUnusedPatches",
 	"auditConfig",
+	"auditLevel",
+	"autoInstallPeers",
+	"blockExoticSubdeps",
+	"cacheDir",
+	"catalogMode",
+	"childConcurrency",
+	"ci",
+	"cleanupUnusedCatalogs",
+	"color",
 	"configDependencies",
+	"dangerouslyAllowAllBuilds",
 	"dedupeDirectDeps",
 	"dedupeInjectedDeps",
 	"dedupePeerDependents",
 	"deployAllFiles",
+	"disallowWorkspaceCycles",
+	"dlxCacheMaxAge",
+	"enableGlobalVirtualStore",
+	"enableModulesDir",
+	"enablePrePostScripts",
 	"engineStrict",
 	"executionEnv",
+	"extendNodePath",
+	"failIfNoMatch",
 	"fetchMinSpeedKiBps",
+	"fetchRetries",
 	"fetchRetryFactor",
 	"fetchRetryMaxtimeout",
 	"fetchRetryMintimeout",
-	"fetchRetryTimeout",
+	"fetchTimeout",
 	"fetchWarnTimeoutMs",
 	"forceLegacyDeploy",
+	"frozenLockfile",
+	"gitBranchLockfile",
 	"gitChecks",
 	"gitShallowHosts",
-	"globalVirtualStore",
+	"globalBinDir",
+	"globalDir",
+	"globalPnpmfile",
 	"globalVirtualStoreDir",
 	"hoist",
 	"hoistPattern",
 	"hoistWorkspacePackages",
 	"httpProxy",
 	"httpsProxy",
+	"ignoreCompatibilityDb",
 	"ignoredBuiltDependencies",
 	"ignoreDepScripts",
-	"ignoreDeps",
 	"ignoredOptionalDependencies",
 	"ignorePatchFailures",
+	"ignorePnpmfile",
+	"ignoreScripts",
 	"ignoreWorkspaceCycles",
+	"ignoreWorkspaceRootCheck",
+	"includeWorkspaceRoot",
 	"injectWorkspacePackages",
 	"linkWorkspacePackages",
+	"localAddress",
 	"lockfile",
 	"lockfileDir",
+	"lockfileIncludeTarballUrl",
+	"loglevel",
 	"managePackageManagerVersions",
+	"maxsockets",
 	"mergeGitBranchLockfiles",
 	"mergeGitBranchLockfilesBranchPattern",
+	"minimumReleaseAge",
+	"minimumReleaseAgeExclude",
 	"modulesCacheMaxAge",
+	"modulesDir",
 	"networkConcurrency",
 	"neverBuiltDependencies",
-	"nodeDownloadMirrors",
 	"nodeLinker",
-	"noproxy",
+	"nodeOptions",
+	"nodeVersion",
 	"noProxy",
+	"noproxy",
 	"npmPath",
-	"npmrcAuthFile",
 	"onlyBuiltDependencies",
 	"onlyBuiltDependenciesFile",
 	"optimisticRepeatInstall",
@@ -94,38 +141,46 @@ const PNPM_SETTINGS_FIELDS = [
 	"peerDependencyRules",
 	"peersSuffixMaxLength",
 	"pnpmfile",
-	"pnpmfileIgnorePkgManifest",
-	"pmOnFail",
 	"preferFrozenLockfile",
+	"preferSymlinkedExecutables",
 	"preferWorkspacePackages",
 	"production",
 	"proxy",
 	"publicHoistPattern",
 	"recursiveInstall",
-	"registries",
+	"registrySupportsTimeField",
 	"requiredScripts",
 	"resolutionMode",
 	"resolvePeersFromWorkspaceRoot",
 	"saveExact",
 	"savePrefix",
+	"saveWorkspaceProtocol",
 	"scriptShell",
 	"shamefullyHoist",
 	"sharedWorkspaceLockfile",
 	"shellEmulator",
 	"sideEffectsCache",
 	"sideEffectsCacheReadonly",
+	"stateDir",
 	"storeDir",
 	"strictDepBuilds",
 	"strictPeerDependencies",
 	"strictSsl",
+	"strictStorePkgContentCheck",
 	"supportedArchitectures",
+	"symlink",
 	"syncInjectedDepsAfterScripts",
 	"tag",
-	"targetDependenciesField",
-	"timeout",
+	"trustPolicy",
+	"trustPolicyExclude",
+	"trustPolicyIgnoreAfter",
+	"unsafePerm",
 	"updateConfig",
+	"updateNotifier",
 	"useBetaCli",
 	"useNodeVersion",
+	"useRunningStoreServer",
+	"useStderr",
 	"verifyDepsBeforeRun",
 	"verifyStoreIntegrity",
 	"virtualStoreDir",
@@ -155,9 +210,9 @@ const DEFAULT_OPTIONS = {
 	cleanNpmrc: true,
 	cleanPackageJson: true,
 	compatibility: "auto",
-	cwd: process.cwd(),
 	newlineBetween: true,
 	replaceDeprecated: false,
+	showChanges: true,
 	sortKeys: false,
 	strategy: "merge",
 	yarnResolutions: true
@@ -208,8 +263,9 @@ function resolveOptions(options = {}) {
 	return {
 		cleanNpmrc: options.cleanNpmrc ?? DEFAULT_OPTIONS.cleanNpmrc,
 		compatibility: resolveCompatibility(options.compatibility),
-		cwd: options.cwd ?? DEFAULT_OPTIONS.cwd,
+		cwd: options.cwd ?? process.cwd(),
 		newlineBetween: options.newlineBetween ?? DEFAULT_OPTIONS.newlineBetween,
+		showChanges: options.showChanges ?? DEFAULT_OPTIONS.showChanges,
 		sortKeys: options.sortKeys ?? DEFAULT_OPTIONS.sortKeys,
 		strategy: resolveStrategy(options.strategy),
 		yarnResolutions: options.yarnResolutions ?? DEFAULT_OPTIONS.yarnResolutions,
@@ -220,52 +276,104 @@ function resolveOptions(options = {}) {
 //#endregion
 //#region src/utils/fs.ts
 /**
-* Check if a path exists
-* @param path - given path
-* @returns `true` if exists, false otherwise
+* Modulus that isolates Unix permission bits from a stat mode.
+*/
+const FILE_PERMISSION_MODULUS = 512;
+/**
+* Resolve a filesystem path to a string suitable for a sibling temp file.
+*/
+function resolvePathString(path) {
+	if (path instanceof URL) return fileURLToPath(path);
+	return typeof path === "string" ? path : path.toString();
+}
+/**
+* Read an existing file's permission bits, if the file exists.
+*/
+async function resolveExistingMode(path) {
+	try {
+		return (await stat(path)).mode % FILE_PERMISSION_MODULUS;
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+}
+/**
+* Check whether a filesystem path exists.
+*
+* @param path - Filesystem path to check
+*
+* @returns `true` when the path is accessible, otherwise `false`
 */
 async function fsExists(path) {
 	return access(path).then(() => true).catch(() => false);
 }
 /**
-* Read file content
-* @param path - file path
-* @returns content of given file
+* Read a UTF-8 text file.
+*
+* @param path - Filesystem path to read
+*
+* @returns Text content of the file
 */
 async function fsReadFile(path) {
 	return await readFile(path, "utf-8");
 }
 /**
 * Remove a file if it exists.
-* @param path - file path
+*
+* @param path - Filesystem path to remove
+*
+* @returns A promise that resolves after the file is removed
 */
 async function fsRemoveFile(path) {
 	await rm(path, { force: true });
 }
 /**
-* Write file
-* @param path - file path
-* @param content - file content
+* Write a normalized UTF-8 text file with one trailing newline.
+*
+* @param path - Filesystem path to write
+* @param content - Text content to write
+*
+* @returns A promise that resolves after the file is written
 */
 async function fsWriteFile(path, content) {
-	await writeFile(path, `${content.trimEnd()}\n`, "utf-8");
+	const pathString = resolvePathString(path);
+	const temporaryPath = join(dirname(pathString), `.${basename(pathString)}.${process.pid}.${randomUUID()}.tmp`);
+	const mode = await resolveExistingMode(path);
+	try {
+		await writeFile(temporaryPath, `${content.trimEnd()}\n`, {
+			encoding: "utf-8",
+			mode
+		});
+		if (mode !== void 0) await chmod(temporaryPath, mode);
+		await rename(temporaryPath, pathString);
+	} finally {
+		await rm(temporaryPath, { force: true });
+	}
 }
-getColor("cyan");
-getColor("yellow");
+//#endregion
+//#region src/utils/color.ts
+/**
+* Apply dim terminal styling to a value.
+*/
 const dim = getColor("dim");
+/**
+* Apply green terminal styling to a value.
+*/
 const green = getColor("green");
+/**
+* Apply red terminal styling to a value.
+*/
 const red = getColor("red");
+/**
+* Apply bold terminal styling to a value.
+*/
 const bold = getColor("bold");
+/**
+* Apply magenta terminal styling to a value.
+*/
 const magenta = getColor("magenta");
 //#endregion
-//#region src/utils/compatibility.ts
-const PNPM_REPLACEABLE_IN_V10_SETTINGS = [
-	"allowNonAppliedPatches",
-	"ignoredBuiltDependencies",
-	"neverBuiltDependencies",
-	"onlyBuiltDependencies",
-	"onlyBuiltDependenciesFile"
-];
+//#region src/utils/legacy-build-settings.ts
 /**
 * Read packages listed by the legacy `onlyBuiltDependenciesFile` setting.
 */
@@ -277,18 +385,50 @@ async function readOnlyBuiltDependenciesFile(cwd, file) {
 	return value;
 }
 /**
+* Read and validate one legacy build dependency list. Configuration files are
+* external input, so their runtime shape can differ from its declared type.
+*/
+function readLegacyBuildDependencyList(settings, key) {
+	const value = settings[key];
+	if (value === void 0) return [];
+	if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+		const npmrcKey = key.replace(/[A-Z]/gu, (character) => `-${character.toLowerCase()}`);
+		throw new TypeError(`Invalid ${key}: expected an array of package names. In .npmrc, use ${npmrcKey}[]=<package>.`);
+	}
+	return value;
+}
+/**
 * Build an `allowBuilds` map from legacy build-script settings.
 */
 async function collectAllowBuildsFromLegacy(incomingSettings, cwd) {
 	const allowBuilds = {};
+	const allowed = readLegacyBuildDependencyList(incomingSettings, "onlyBuiltDependencies");
+	const ignored = readLegacyBuildDependencyList(incomingSettings, "ignoredBuiltDependencies");
+	const neverBuilt = readLegacyBuildDependencyList(incomingSettings, "neverBuiltDependencies");
 	const allowedFromFile = await readOnlyBuiltDependenciesFile(cwd, incomingSettings.onlyBuiltDependenciesFile);
-	for (const name of [...incomingSettings.onlyBuiltDependencies || [], ...allowedFromFile]) allowBuilds[name] = true;
-	for (const name of incomingSettings.ignoredBuiltDependencies || []) allowBuilds[name] = false;
-	for (const name of incomingSettings.neverBuiltDependencies || []) allowBuilds[name] = false;
+	for (const name of [...allowed, ...allowedFromFile]) allowBuilds[name] = true;
+	for (const name of ignored) allowBuilds[name] = false;
+	for (const name of neverBuilt) allowBuilds[name] = false;
 	return Object.keys(allowBuilds).length ? allowBuilds : void 0;
 }
+//#endregion
+//#region src/utils/compatibility.ts
+/**
+* Legacy build settings that can be replaced for pnpm v10.
+*/
+const PNPM_REPLACEABLE_IN_V10_SETTINGS = [
+	"allowNonAppliedPatches",
+	"ignoredBuiltDependencies",
+	"neverBuiltDependencies",
+	"onlyBuiltDependencies",
+	"onlyBuiltDependenciesFile"
+];
 /**
 * Resolve the pnpm v11 replacement for legacy package-manager settings.
+*
+* @param settings - Settings containing legacy package-manager declarations
+*
+* @returns Resolved `pmOnFail` behavior, or `undefined` when not configured
 */
 function resolvePmOnFail(settings) {
 	if (settings.pmOnFail) return settings.pmOnFail;
@@ -299,6 +439,11 @@ function resolvePmOnFail(settings) {
 }
 /**
 * Rename legacy audit settings while preserving values for manual ID updates.
+*
+* @param settings - Settings whose audit configuration may be normalized
+* @param warnings - Warning collection updated with manual follow-up guidance
+*
+* @returns Nothing; the settings and warning collection are mutated in place
 */
 function normalizeAuditConfig(settings, warnings) {
 	const { auditConfig } = settings;
@@ -310,6 +455,11 @@ function normalizeAuditConfig(settings, warnings) {
 }
 /**
 * Resolve a removed Node.js runtime setting for migration to `package.json`.
+*
+* @param settings - Settings containing legacy runtime declarations
+* @param warnings - Warning collection updated when declarations conflict
+*
+* @returns Runtime version to migrate, or `undefined` when not configured
 */
 function resolveRuntimeVersion(settings, warnings) {
 	const { useNodeVersion } = settings;
@@ -319,6 +469,11 @@ function resolveRuntimeVersion(settings, warnings) {
 }
 /**
 * Normalize settings according to the selected compatibility target.
+*
+* @param incomingSettings - Settings to normalize in place
+* @param options - Compatibility target and normalization context
+*
+* @returns Normalization result, extracted runtime version, and warnings
 */
 async function normalizeIncomingSettings(incomingSettings, options) {
 	const { compatibility, cwd, replaceDeprecated } = options;
@@ -354,8 +509,15 @@ async function normalizeIncomingSettings(incomingSettings, options) {
 		warnings
 	};
 }
+//#endregion
+//#region src/utils/compatibility-runtime.ts
 /**
 * Move a removed Node.js runtime setting to `package.json#devEngines.runtime`.
+*
+* @param packageJson - Package manifest to update in place
+* @param runtimeVersion - Node.js runtime version extracted from pnpm settings
+*
+* @returns Migration result indicating whether the manifest changed
 */
 function migrateRuntimeToPackageJson(packageJson, runtimeVersion) {
 	if (!runtimeVersion) return { changed: false };
@@ -374,6 +536,12 @@ function migrateRuntimeToPackageJson(packageJson, runtimeVersion) {
 }
 /**
 * Select the runtime setting that wins under the configured merge strategy.
+*
+* @param existingVersion - Runtime version from existing workspace settings
+* @param incomingVersion - Runtime version from incoming settings
+* @param strategy - Merge strategy controlling value precedence
+*
+* @returns Selected runtime version, or `undefined` when neither source has one
 */
 function resolveRuntimeVersionByStrategy(existingVersion, incomingVersion, strategy) {
 	if (strategy === "overwrite") return incomingVersion ?? existingVersion;
@@ -381,17 +549,44 @@ function resolveRuntimeVersionByStrategy(existingVersion, incomingVersion, strat
 }
 //#endregion
 //#region src/utils/compatibility-target.ts
+/**
+* pnpm major version that introduced the v11 settings schema.
+*/
 const PNPM_V11_MAJOR = 11;
+/**
+* pnpm major version that introduced the v12 compatibility target.
+*/
 const PNPM_V12_MAJOR = 12;
 /**
+* Resolve a pnpm major from a package manager declaration.
+*/
+function resolvePnpmMajor(hint) {
+	const match = hint?.match(/^pnpm@[\s<=>^~]*(?<major>\d+)(?:\.|\s|$)/u);
+	return match?.groups?.major ? Number(match.groups.major) : void 0;
+}
+/**
+* Normalize the single-or-array devEngines declaration.
+*/
+function normalizePackageManagers(value) {
+	if (Array.isArray(value)) return value;
+	return value ? [value] : [];
+}
+/**
 * Resolve final compatibility target from user option and package manager hint.
+*
+* @param compatibility - Explicit or automatically detected compatibility target
+* @param packageManager - `packageManager` declaration from `package.json`
+* @param devPackageManager - Package manager declaration from `devEngines`
+*
+* @returns Resolved concrete compatibility target
 */
 function resolveCompatibilityTarget(compatibility, packageManager, devPackageManager) {
 	if (compatibility !== "auto") return compatibility;
-	const match = (packageManager || (devPackageManager?.name === "pnpm" ? `pnpm@${devPackageManager.version}` : void 0))?.match(/^pnpm@[\s<=>^~]*(?<major>\d+)(?:\.|\s|$)/u);
-	const major = Number(match?.groups?.major);
-	if (major >= PNPM_V12_MAJOR) return "v12";
-	return major >= PNPM_V11_MAJOR ? "v11" : "v10";
+	const packageManagerMajor = resolvePnpmMajor(packageManager);
+	const devPackageManagerMajors = normalizePackageManagers(devPackageManager).filter((item) => item.name === "pnpm").map((item) => resolvePnpmMajor(`pnpm@${item.version ?? ""}`)).filter((major) => major !== void 0);
+	const major = packageManagerMajor ?? (devPackageManagerMajors.length ? Math.max(...devPackageManagerMajors) : void 0);
+	if (major !== void 0 && major >= PNPM_V12_MAJOR) return "v12";
+	return major !== void 0 && major >= PNPM_V11_MAJOR ? "v11" : "v10";
 }
 //#endregion
 //#region src/utils/merge.ts
@@ -470,6 +665,9 @@ function mergeByStrategy(existing, incoming, strategy) {
 }
 //#endregion
 //#region src/utils/npmrc.ts
+/**
+* Authentication and registry keys that must remain in `.npmrc`.
+*/
 const NPMRC_AUTH_OR_REGISTRY_KEYS = [
 	"_auth",
 	"_authtoken",
@@ -486,15 +684,26 @@ const NPMRC_AUTH_OR_REGISTRY_KEYS = [
 	"tokenhelper",
 	"username"
 ];
+/**
+* Pattern for pnpm's channel-specific Node.js mirror keys.
+*/
 const NODE_MIRROR_KEY_PATTERN = /^node-mirror:(?<channel>.+)$/iu;
 /**
 * Normalize `.npmrc` key for case-insensitive matching.
+*
+* @param key - Raw `.npmrc` key
+*
+* @returns Trimmed lower-case key without an array suffix
 */
 function normalizeNpmrcKey(key) {
 	return key.trim().replace(/\[\]$/u, "").toLowerCase();
 }
 /**
 * Extract key name from a raw `.npmrc` line.
+*
+* @param line - Raw line from an `.npmrc` file
+*
+* @returns Normalized key, or `undefined` for comments and invalid lines
 */
 function getNpmrcLineKey(line) {
 	const trimmed = line.trim();
@@ -506,6 +715,10 @@ function getNpmrcLineKey(line) {
 /**
 * Check whether a `.npmrc` key is auth/registry-related and should stay in
 * pnpm v11 and newer.
+*
+* @param key - Raw or normalized `.npmrc` key
+*
+* @returns `true` when the key must remain in `.npmrc`
 */
 function isNpmrcAuthOrRegistryKey(key) {
 	const normalized = normalizeNpmrcKey(key);
@@ -516,11 +729,12 @@ function isNpmrcAuthOrRegistryKey(key) {
 /**
 * Remove pnpm-related settings from `.npmrc` file.
 *
-* This function reads the `.npmrc` file, filters out all lines that start with
-* pnpm-specific configuration keys (as defined in PNPM_SETTINGS_FIELDS), and
-* writes the cleaned content back to the file.
+* This function reads the `.npmrc` file, removes lines whose exact normalized
+* keys were migrated, and writes the cleaned content back to the file.
 *
 * @param path - Absolute path to the `.npmrc` file
+* @param compatibility - Concrete pnpm compatibility target
+* @param migratedKeys - Original `.npmrc` keys that were migrated
 *
 * @returns A promise that resolves when the file has been pruned
 *
@@ -528,17 +742,15 @@ function isNpmrcAuthOrRegistryKey(key) {
 *
 * @example
 * ```ts
-* await pruneNpmrc('/path/to/.npmrc')
+* await pruneNpmrc('/path/to/.npmrc', 'v10', ['node-linker'])
 * ```
 */
-async function pruneNpmrc(path, compatibility = "v10", migratedKeys = []) {
-	const pnpmSettingsFields = PNPM_SETTINGS_FIELDS.map((field) => kebabCase(field));
+async function pruneNpmrc(path, compatibility, migratedKeys) {
 	const migratedKeySet = new Set(migratedKeys.map(normalizeNpmrcKey));
 	const updatedContent = (await fsReadFile(path)).split(/\r?\n/u).filter((line) => {
 		const key = getNpmrcLineKey(line);
 		if (!key) return true;
-		if (compatibility !== "v10") return !migratedKeySet.has(normalizeNpmrcKey(key));
-		return !pnpmSettingsFields.some((field) => key.startsWith(field));
+		return !migratedKeySet.has(key);
 	}).join("\n").trimEnd();
 	if (compatibility !== "v10" && !updatedContent.trim()) {
 		await fsRemoveFile(path);
@@ -547,38 +759,28 @@ async function pruneNpmrc(path, compatibility = "v10", migratedKeys = []) {
 	await fsWriteFile(path, updatedContent);
 }
 /**
-* Read and parse `.npmrc` file with camelCase key conversion.
+* Read `.npmrc` and return settings that should be migrated into workspace config.
 *
-* This function reads an `.npmrc` INI-format file and parses it into an object.
-* All keys are automatically converted from kebab-case to camelCase for easier
-* JavaScript consumption (e.g., `allow-builds` → `allowBuilds`).
+* - `v10`: returns settings from the legacy whitelist.
+* - `v11+`: excludes auth/registry keys because pnpm still reads them from
+*   `.npmrc`.
 *
 * @param path - Absolute path to the `.npmrc` file
+* @param compatibility - Concrete pnpm compatibility target
 *
-* @returns A promise that resolves to the parsed `.npmrc` configuration object with camelCase keys
+* @returns Migratable settings and their original `.npmrc` keys
 *
 * @throws {Error} When file reading or INI parsing fails
-*
-* @example
-* ```ts
-* const config = await readNpmrc('/path/to/.npmrc')
-* // config.allowBuilds, config.packageExtensions, etc.
-* ```
-*/
-/**
-* Read `.npmrc` and return settings that should be migrated into workspace config.
-*
-* - `v10`: returns settings from the legacy whitelist.
-* - `v11+`: excludes auth/registry keys because pnpm still reads them from
-*   `.npmrc`.
 */
 async function readMigratableNpmrc(path, compatibility) {
 	const raw = await readIniFile(path);
 	if (compatibility === "v10") {
-		const settings = camelcaseKeys(raw);
+		const pnpmSettingsFields = new Set(PNPM_V10_NPMRC_SETTINGS_FIELDS.map((field) => normalizeNpmrcKey(kebabCase(field))));
+		const keys = Object.keys(raw).filter((key) => pnpmSettingsFields.has(normalizeNpmrcKey(key)));
+		const migratable = Object.fromEntries(keys.map((key) => [key, raw[key]]));
 		return {
-			keys: PNPM_SETTINGS_FIELDS,
-			settings: pick(settings, PNPM_SETTINGS_FIELDS)
+			keys,
+			settings: camelcaseKeys(migratable)
 		};
 	}
 	const migratable = {};
@@ -598,11 +800,225 @@ async function readMigratableNpmrc(path, compatibility) {
 	};
 }
 //#endregion
+//#region src/utils/settings-change.ts
+/**
+* Maximum dynamic-programming cells used for an exact line diff.
+*/
+const MAX_LCS_CELLS = 1e6;
+/**
+* URL userinfo can contain proxy usernames and passwords. It must never be
+* printed in a migration report.
+*/
+const URL_USERINFO_PATTERN = /(?<scheme>[a-z][a-z\d+.-]*:\/\/)[^/\s@]+@/giu;
+/**
+* Collect changed root settings between two workspace configurations.
+*
+* @param before - Workspace settings before migration
+* @param after - Workspace settings after migration
+*
+* @returns Changed root settings with their before and after values
+*/
+function collectSettingsChanges(before, after) {
+	const beforeSettings = { ...before };
+	const afterSettings = { ...after };
+	const keys = /* @__PURE__ */ new Set([...Object.keys(beforeSettings), ...Object.keys(afterSettings)]);
+	return Array.from(keys).filter((key) => !isDeepStrictEqual(beforeSettings[key], afterSettings[key])).map((key) => ({
+		after: afterSettings[key],
+		before: beforeSettings[key],
+		key
+	}));
+}
+/**
+* Create a bounded-memory diff that retains shared prefixes and suffixes.
+*
+* This fallback deliberately gives up the exact LCS for unusually large
+* settings to keep reporting from exhausting memory after migration writes.
+*/
+function createLinearLineDiff(beforeLines, afterLines) {
+	let prefixLength = 0;
+	const maximumPrefixLength = Math.min(beforeLines.length, afterLines.length);
+	while (prefixLength < maximumPrefixLength && beforeLines[prefixLength] === afterLines[prefixLength]) prefixLength++;
+	let suffixLength = 0;
+	const maximumSuffixLength = maximumPrefixLength - prefixLength;
+	while (suffixLength < maximumSuffixLength && beforeLines[beforeLines.length - suffixLength - 1] === afterLines[afterLines.length - suffixLength - 1]) suffixLength++;
+	return [
+		...beforeLines.slice(0, prefixLength).map((value) => ({
+			kind: "unchanged",
+			value
+		})),
+		...beforeLines.slice(prefixLength, beforeLines.length - suffixLength).map((value) => ({
+			kind: "removed",
+			value
+		})),
+		...afterLines.slice(prefixLength, afterLines.length - suffixLength).map((value) => ({
+			kind: "added",
+			value
+		})),
+		...beforeLines.slice(beforeLines.length - suffixLength).map((value) => ({
+			kind: "unchanged",
+			value
+		}))
+	];
+}
+/**
+* Create a line-based diff using the longest common subsequence.
+*
+* @param beforeLines - YAML lines before migration
+* @param afterLines - YAML lines after migration
+*
+* @returns Classified diff lines in display order
+*/
+function createLineDiff(beforeLines, afterLines) {
+	if (beforeLines.length * afterLines.length > MAX_LCS_CELLS) return createLinearLineDiff(beforeLines, afterLines);
+	const lengths = Array.from({ length: beforeLines.length + 1 }, () => Array(afterLines.length + 1).fill(0));
+	for (let beforeIndex = beforeLines.length - 1; beforeIndex >= 0; beforeIndex--) for (let afterIndex = afterLines.length - 1; afterIndex >= 0; afterIndex--) lengths[beforeIndex][afterIndex] = beforeLines[beforeIndex] === afterLines[afterIndex] ? lengths[beforeIndex + 1][afterIndex + 1] + 1 : Math.max(lengths[beforeIndex + 1][afterIndex], lengths[beforeIndex][afterIndex + 1]);
+	const diff = [];
+	let beforeIndex = 0;
+	let afterIndex = 0;
+	while (beforeIndex < beforeLines.length && afterIndex < afterLines.length) if (beforeLines[beforeIndex] === afterLines[afterIndex]) {
+		diff.push({
+			kind: "unchanged",
+			value: beforeLines[beforeIndex]
+		});
+		beforeIndex++;
+		afterIndex++;
+	} else if (lengths[beforeIndex + 1][afterIndex] >= lengths[beforeIndex][afterIndex + 1]) {
+		diff.push({
+			kind: "removed",
+			value: beforeLines[beforeIndex]
+		});
+		beforeIndex++;
+	} else {
+		diff.push({
+			kind: "added",
+			value: afterLines[afterIndex]
+		});
+		afterIndex++;
+	}
+	while (beforeIndex < beforeLines.length) {
+		diff.push({
+			kind: "removed",
+			value: beforeLines[beforeIndex]
+		});
+		beforeIndex++;
+	}
+	while (afterIndex < afterLines.length) {
+		diff.push({
+			kind: "added",
+			value: afterLines[afterIndex]
+		});
+		afterIndex++;
+	}
+	return diff;
+}
+/**
+* Format one root setting as YAML lines.
+*
+* @param key - Root setting key
+* @param value - Setting value, or `undefined` when the key is absent
+*
+* @returns YAML lines for the setting, or an empty array when absent
+*/
+function formatSettingLines(key, value) {
+	if (value === void 0) return [];
+	return stringify({ [key]: value }).trimEnd().split("\n");
+}
+/**
+* Remove credentials embedded in URLs while preserving enough context to
+* identify the changed setting.
+*
+* @param value - Rendered YAML diff line
+*
+* @returns Diff line safe to print to a terminal or CI log
+*/
+function redactUrlCredentials(value) {
+	return value.replace(URL_USERINFO_PATTERN, "$<scheme>***@");
+}
+/**
+* Format a setting change as a GitHub-style YAML diff.
+*
+* @param change - Root setting change to format
+*
+* @returns Classified YAML diff lines
+*/
+function createSettingsDiffLines(change) {
+	return createLineDiff(formatSettingLines(change.key, change.before), formatSettingLines(change.key, change.after)).map((line) => ({
+		kind: line.kind,
+		value: redactUrlCredentials(line.value)
+	}));
+}
+/**
+* Print a summary and GitHub-style YAML diff for every changed setting.
+*
+* @param changes - Root setting changes to report
+*
+* @returns Nothing; output is written through consola
+*/
+function reportSettingsChanges(changes) {
+	consola$1.info(`${changes.length} ${changes.length === 1 ? "setting" : "settings"} changed`);
+	for (const [index, change] of changes.entries()) {
+		if (index > 0) consola$1.log("");
+		for (const line of createSettingsDiffLines(change)) if (line.kind === "added") consola$1.log(green(`+ ${line.value}`));
+		else if (line.kind === "removed") consola$1.log(red(`- ${line.value}`));
+		else consola$1.log(dim(`  ${line.value}`));
+	}
+}
+//#endregion
+//#region src/utils/yaml-document.ts
+/**
+* Sort every mapping in a YAML node without replacing its comments or anchors.
+*/
+function sortYamlMappings(node) {
+	if (isMap(node)) {
+		node.items.sort((left, right) => {
+			const leftKey = isScalar(left.key) ? String(left.key.value) : "";
+			const rightKey = isScalar(right.key) ? String(right.key.value) : "";
+			return leftKey.localeCompare(rightKey);
+		});
+		for (const pair of node.items) if (isNode(pair.value)) sortYamlMappings(pair.value);
+	} else if (isSeq(node)) {
+		for (const item of node.items) if (isNode(item)) sortYamlMappings(item);
+	}
+}
+/**
+* Apply semantic root changes to the parsed document while retaining untouched
+* YAML nodes and their source metadata.
+*/
+function updateYamlDocument(document, options) {
+	const { after, before, sortKeys } = options;
+	for (const key of Object.keys(before)) if (!Object.hasOwn(after, key)) document.delete(key);
+	for (const [key, value] of Object.entries(after)) if (!Object.hasOwn(before, key) || !isDeepStrictEqual(Reflect.get(before, key), value)) document.set(key, value);
+	if (sortKeys) sortYamlMappings(document.contents);
+}
+/**
+* Normalize blank lines immediately before root mapping keys.
+*/
+function formatRootSpacing(content, newlineBetween) {
+	return content.replace(/\n+(?=[^\s#][^:\n]*:)/gu, newlineBetween ? "\n\n" : "\n");
+}
+//#endregion
 //#region src/utils/config.ts
+/**
+* Resolve the indentation width for a YAML document.
+*
+* @param content - Raw YAML content
+*
+* @returns Detected indentation width or the project default
+*/
 function resolveYamlIndent(content) {
 	const detectedIndent = detectIndent(content).amount;
 	return detectedIndent > 0 ? detectedIndent : 2;
 }
+/**
+* Read and parse a package manifest when it exists.
+*
+* @param path - Absolute path to `package.json`
+* @param exists - Whether the package manifest exists
+*
+* @returns Parsed package manifest and detected indentation
+*
+* @throws {SyntaxError} When the package manifest contains invalid JSON
+*/
 async function readPackageJson(path, exists) {
 	if (!exists) return {
 		indent: 2,
@@ -614,17 +1030,46 @@ async function readPackageJson(path, exists) {
 		value: JSON.parse(content)
 	};
 }
+/**
+* Read and parse a pnpm workspace manifest when it exists.
+*
+* @param path - Absolute path to `pnpm-workspace.yaml`
+* @param exists - Whether the workspace manifest exists
+*
+* @returns Parsed workspace settings and detected indentation
+*
+* @throws {Error} When the workspace manifest contains invalid YAML
+*/
 async function readPnpmWorkspace(path, exists) {
 	if (!exists) return {
+		document: new Document({}),
 		indent: 2,
 		value: {}
 	};
 	const content = await fsReadFile(path);
+	const document = parseDocument(content);
+	const [parseError] = document.errors;
+	if (parseError) throw parseError;
+	const parsedValue = document.toJS();
+	if (parsedValue !== null && !isMap(document.contents)) throw new TypeError("pnpm-workspace.yaml must contain a root mapping.");
+	if (parsedValue === null) document.contents = document.createNode({});
 	return {
+		document,
 		indent: resolveYamlIndent(content),
-		value: parse(content) ?? {}
+		value: parsedValue ?? {}
 	};
 }
+/**
+* Resolve migratable pnpm settings from a package manifest.
+*
+* Yarn resolutions are merged into pnpm overrides when enabled. Empty
+* overrides are removed from the result.
+*
+* @param packageJson - Parsed package manifest
+* @param yarnResolutions - Whether to convert Yarn resolutions to pnpm overrides
+*
+* @returns Pnpm workspace settings resolved from the package manifest
+*/
 function resolvePackageJsonSettings(packageJson, yarnResolutions) {
 	const pnpmSettings = yarnResolutions && packageJson.resolutions ? {
 		...packageJson.pnpm,
@@ -649,6 +1094,10 @@ function hasMigratableSettings(sources) {
 function assertCanMigrateRuntime(runtimeVersion, packageJsonExists) {
 	if (runtimeVersion && !packageJsonExists) throw new Error("Cannot migrate the removed Node.js runtime setting without a package.json file.");
 }
+function reportMigrationChanges(showChanges, before = {}, after = {}) {
+	if (!showChanges) return;
+	reportSettingsChanges(collectSettingsChanges(before, after));
+}
 /**
 * Migrate pnpm settings from legacy locations to `pnpm-workspace.yaml`.
 *
@@ -666,6 +1115,7 @@ function assertCanMigrateRuntime(runtimeVersion, packageJsonExists) {
 * @param rawOptions.yarnResolutions - Whether to migrate resolutions field (default: true)
 * @param rawOptions.sortKeys - Whether to sort keys in output YAML (default: false)
 * @param rawOptions.newlineBetween - Add newlines between root keys (default: true)
+* @param rawOptions.showChanges - Show settings changes after migration (default: true)
 *
 * @returns A promise that resolves when migration is complete
 *
@@ -695,19 +1145,19 @@ async function migratePnpmSettings(rawOptions = {}) {
 			fsExists(packageJsonPath),
 			fsExists(pnpmWorkspaceYamlPath)
 		]);
-		if (!hasSettingsSources(npmrcExists, packageJsonExists, pnpmWorkspaceExists)) return;
+		if (!hasSettingsSources(npmrcExists, packageJsonExists, pnpmWorkspaceExists)) {
+			reportMigrationChanges(options.showChanges);
+			return;
+		}
 		const [packageJson, pnpmWorkspace] = await Promise.all([readPackageJson(packageJsonPath, packageJsonExists), readPnpmWorkspace(pnpmWorkspaceYamlPath, pnpmWorkspaceExists)]);
+		const pnpmWorkspaceBefore = structuredClone(pnpmWorkspace.value);
 		const compatibility = resolveCompatibilityTarget(options.compatibility, packageJson.value.packageManager, packageJson.value.devEngines?.packageManager);
 		const npmrcMigratable = npmrcExists ? await readMigratableNpmrc(npmrcPath, compatibility) : {
 			keys: [],
 			settings: {}
 		};
 		const pnpmSettingsInNpmrc = npmrcMigratable.settings;
-		const pnpmSettingsInPackageJson = resolvePackageJsonSettings(packageJson.value, options.yarnResolutions);
-		const incomingSettings = {
-			...pnpmSettingsInNpmrc,
-			...pnpmSettingsInPackageJson
-		};
+		const incomingSettings = mergeByStrategy(resolvePackageJsonSettings(packageJson.value, options.yarnResolutions), pnpmSettingsInNpmrc, "merge");
 		const [existingNormalization, incomingNormalization] = await Promise.all([normalizeIncomingSettings(pnpmWorkspace.value, {
 			compatibility,
 			cwd: options.cwd,
@@ -729,19 +1179,16 @@ async function migratePnpmSettings(rawOptions = {}) {
 			yarnResolutions: options.yarnResolutions
 		})) {
 			consola$1.warn("No pnpm settings fields to migrate");
+			reportMigrationChanges(options.showChanges);
 			return;
 		}
 		const pnpmWorkspaceResult = mergeByStrategy(pnpmWorkspace.value, incomingSettings, options.strategy);
-		const yamlDocument = new Document({}, { sortMapEntries: options.sortKeys });
-		Object.entries(pnpmWorkspaceResult).forEach(([key, value]) => {
-			yamlDocument.add({
-				key,
-				value
-			});
+		updateYamlDocument(pnpmWorkspace.document, {
+			after: pnpmWorkspaceResult,
+			before: pnpmWorkspaceBefore,
+			sortKeys: options.sortKeys
 		});
-		const yamlContent = yamlDocument.toString({ indent: pnpmWorkspace.indent });
-		await fsWriteFile(pnpmWorkspaceYamlPath, options.newlineBetween ? yamlContent.replace(/\n(?=[^\s#][^:\n]*:)/gu, "\n\n") : yamlContent);
-		if (npmrcExists && options.cleanNpmrc) await pruneNpmrc(npmrcPath, compatibility, npmrcMigratable.keys);
+		const finalYamlContent = formatRootSpacing(pnpmWorkspace.document.toString({ indent: pnpmWorkspace.indent }), options.newlineBetween);
 		let packageJsonChanged = runtimeMigration.changed;
 		if (packageJsonExists && options.cleanPackageJson) {
 			if (packageJson.value.pnpm) packageJsonChanged = true;
@@ -751,7 +1198,10 @@ async function migratePnpmSettings(rawOptions = {}) {
 				delete packageJson.value.resolutions;
 			}
 		}
+		await fsWriteFile(pnpmWorkspaceYamlPath, finalYamlContent);
 		if (packageJsonExists && packageJsonChanged) await fsWriteFile(packageJsonPath, JSON.stringify(packageJson.value, null, packageJson.indent));
+		if (npmrcExists && options.cleanNpmrc) await pruneNpmrc(npmrcPath, compatibility, npmrcMigratable.keys);
+		reportMigrationChanges(options.showChanges, pnpmWorkspaceBefore, pnpmWorkspaceResult);
 	} catch (err) {
 		consola$1.error("Failed to migrate pnpm settings:", err);
 		throw err;
@@ -759,9 +1209,8 @@ async function migratePnpmSettings(rawOptions = {}) {
 }
 //#endregion
 //#region src/cli.ts
-const cli = cac(name);
-cli.version(version).option("--cwd [cwd]", "Current working directory").option("--sort-keys", "Sort keys when write pnpm-workspace.yaml").option("--compatibility <compatibility>", "Compatibility target (auto, v10, v11, v12)").option("--replace-deprecated", "Replace deprecated pnpm settings with new ones and remove old keys").option("--strategy <strategy>", "Strategy to handle conflicts (discard, merge, overwrite)").option("--no-yarn-resolutions", "Disable migrating resolutions field in package.json").option("--no-newline-between", "Disable adding newlines between each root keys").option("--no-clean-npmrc", "Disable removing pnpm settings in .npmrc file").option("--no-clean-package-json", "Disable removing pnpm fields in package.json").help();
-cli.command("").action(async (options) => {
+const cli = createCli();
+cli.command("").usage("[options]").action(async (options) => {
 	try {
 		consola.log(`\n${bold(magenta(name))} ${dim(`v${version}`)}`);
 		consola.log(dim("\n--------------\n"));