pnpm-settings-migrator 0.8.1 → 0.9.0

package/dist/cli.mjs

@@ -1,26 +1,29 @@
 import process from "node:process";
 import consola$1, { consola } from "consola";
 import { cac } from "cac";
-import { basename, dirname, join, resolve } from "pathe";
+import { basename, dirname, join, relative, resolve } from "pathe";
+import camelcaseKeys from "camelcase-keys";
 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 } 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 { glob } from "tinyglobby";
 import detectIndent from "detect-indent";
+import { Document, isMap, isNode, isScalar, isSeq, parseDocument, stringify } from "yaml";
+import { isDeepStrictEqual } from "node:util";
 //#region package.json
 var name = "pnpm-settings-migrator";
-var version = "0.8.1";
+var version = "0.9.0";
 //#endregion
 //#region src/cli-options.ts
 /**
 * Create the command-line parser shared by the executable and parser tests.
+*
+* @returns Configured command-line parser
 */
 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");
@@ -202,78 +205,6 @@ const PNPM_V11_REMOVED_SETTINGS = [
 	"useNodeVersion"
 ];
 //#endregion
-//#region src/options.ts
-/**
-* Default values for migration options.
-*/
-const DEFAULT_OPTIONS = {
-	cleanNpmrc: true,
-	cleanPackageJson: true,
-	compatibility: "auto",
-	newlineBetween: true,
-	replaceDeprecated: false,
-	showChanges: true,
-	sortKeys: false,
-	strategy: "merge",
-	yarnResolutions: true
-};
-const VALID_STRATEGIES = [
-	"discard",
-	"merge",
-	"overwrite"
-];
-const VALID_COMPATIBILITIES = [
-	"auto",
-	"v10",
-	"v11",
-	"v12"
-];
-function resolveCompatibility(compatibility) {
-	if (!compatibility) return DEFAULT_OPTIONS.compatibility;
-	if (VALID_COMPATIBILITIES.includes(compatibility)) return compatibility;
-	throw new Error(`Invalid compatibility: ${compatibility}. Expected one of: ${VALID_COMPATIBILITIES.join(", ")}`);
-}
-function resolveStrategy(strategy) {
-	if (!strategy) return DEFAULT_OPTIONS.strategy;
-	if (VALID_STRATEGIES.includes(strategy)) return strategy;
-	throw new Error(`Invalid strategy: ${strategy}. Expected one of: ${VALID_STRATEGIES.join(", ")}`);
-}
-/**
-* Resolve and normalize migration options with defaults.
-*
-* This function takes partial options and returns a complete options object
-* with all properties set to either the provided value or the default value.
-*
-* @param options - Partial migration options
-*
-* @returns Complete options object with all required properties
-*
-* @example
-* ```ts
-* // Use all defaults
-* const opts = resolveOptions()
-* // { cleanNpmrc: true, cleanPackageJson: true, cwd: '/current/dir', ... }
-*
-* // Override specific options
-* const opts = resolveOptions({ sortKeys: true, cleanNpmrc: false })
-* // { cleanNpmrc: false, cleanPackageJson: true, sortKeys: true, ... }
-* ```
-*/
-function resolveOptions(options = {}) {
-	return {
-		cleanNpmrc: options.cleanNpmrc ?? DEFAULT_OPTIONS.cleanNpmrc,
-		compatibility: resolveCompatibility(options.compatibility),
-		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,
-		cleanPackageJson: options.cleanPackageJson ?? DEFAULT_OPTIONS.cleanPackageJson,
-		replaceDeprecated: options.replaceDeprecated ?? DEFAULT_OPTIONS.replaceDeprecated
-	};
-}
-//#endregion
 //#region src/utils/fs.ts
 /**
 * Modulus that isolates Unix permission bits from a stat mode.
@@ -281,6 +212,10 @@ function resolveOptions(options = {}) {
 const FILE_PERMISSION_MODULUS = 512;
 /**
 * Resolve a filesystem path to a string suitable for a sibling temp file.
+*
+* @param path - Filesystem path to normalize
+*
+* @returns String path suitable for path manipulation
 */
 function resolvePathString(path) {
 	if (path instanceof URL) return fileURLToPath(path);
@@ -288,6 +223,10 @@ function resolvePathString(path) {
 }
 /**
 * Read an existing file's permission bits, if the file exists.
+*
+* @param path - Filesystem path to inspect
+*
+* @returns Unix permission bits, or `undefined` when the file does not exist
 */
 async function resolveExistingMode(path) {
 	try {
@@ -354,28 +293,190 @@ async function fsWriteFile(path, content) {
 //#region src/utils/color.ts
 /**
 * Apply dim terminal styling to a value.
+*
+* @param text - Text or number to style
+*
+* @returns ANSI-styled string
 */
 const dim = getColor("dim");
 /**
 * Apply green terminal styling to a value.
+*
+* @param text - Text or number to style
+*
+* @returns ANSI-styled string
 */
 const green = getColor("green");
 /**
 * Apply red terminal styling to a value.
+*
+* @param text - Text or number to style
+*
+* @returns ANSI-styled string
 */
 const red = getColor("red");
 /**
 * Apply bold terminal styling to a value.
+*
+* @param text - Text or number to style
+*
+* @returns ANSI-styled string
 */
 const bold = getColor("bold");
 /**
 * Apply magenta terminal styling to a value.
+*
+* @param text - Text or number to style
+*
+* @returns ANSI-styled string
 */
 const magenta = getColor("magenta");
 //#endregion
+//#region src/utils/deprecated-settings.ts
+/**
+* Replace deprecated audit fields with the structured `audit` setting.
+*
+* @param settings - Workspace settings to normalize in place
+*/
+function normalizeAuditSettings(settings) {
+	const level = settings.audit?.level ?? settings.auditLevel;
+	const ignore = settings.audit?.ignore ?? settings.auditConfig?.ignoreGhsas;
+	if (level !== void 0 || ignore !== void 0) settings.audit = {
+		...settings.audit,
+		...level === void 0 ? {} : { level },
+		...ignore === void 0 ? {} : { ignore }
+	};
+	Reflect.deleteProperty(settings, "auditConfig");
+	Reflect.deleteProperty(settings, "auditLevel");
+}
+/**
+* Replace deprecated update fields with the structured `update` setting.
+*
+* @param settings - Workspace settings to normalize in place
+*/
+function normalizeUpdateSettings(settings) {
+	const { updateConfig } = settings;
+	if (!updateConfig) return;
+	settings.update = {
+		...updateConfig.ignoreDependencies === void 0 ? {} : { ignoreDeps: updateConfig.ignoreDependencies },
+		...updateConfig.changeset === void 0 ? {} : { changeset: updateConfig.changeset },
+		...updateConfig.githubActions === void 0 ? {} : { githubActions: updateConfig.githubActions },
+		...updateConfig.githubActionsServer === void 0 ? {} : { githubActionsServer: updateConfig.githubActionsServer },
+		...settings.update
+	};
+	Reflect.deleteProperty(settings, "updateConfig");
+}
+/**
+* Replace former scalar aliases with their canonical v11+ settings.
+*
+* @param settings - Workspace settings to normalize in place
+*/
+function normalizeScalarAliases(settings) {
+	if (settings.cleanupUnusedCatalogs !== void 0) {
+		settings.catalogPrune ??= settings.cleanupUnusedCatalogs;
+		Reflect.deleteProperty(settings, "cleanupUnusedCatalogs");
+	}
+	if (settings.enableGlobalVirtualStore !== void 0) {
+		settings.virtualStoreType ??= settings.enableGlobalVirtualStore ? "global" : "project";
+		Reflect.deleteProperty(settings, "enableGlobalVirtualStore");
+	}
+}
+/**
+* Replace the older side-effects cache spellings with one structured value.
+*
+* @param settings - Workspace settings to normalize in place
+*/
+function normalizeSideEffectsCache(settings) {
+	const declared = settings.sideEffectsCache;
+	const readonly = settings.sideEffectsCacheReadonly;
+	const remote = settings.remoteSideEffectsCache;
+	if (readonly === void 0 && remote === void 0) return;
+	const structured = typeof declared === "object" && declared !== null ? declared : void 0;
+	const shorthand = typeof declared === "boolean" ? declared : void 0;
+	settings.sideEffectsCache = {
+		...shorthand === void 0 ? {} : {
+			read: readonly === true ? true : shorthand,
+			write: readonly === true ? false : shorthand
+		},
+		...readonly === void 0 || shorthand !== void 0 ? {} : {
+			read: readonly,
+			...readonly ? { write: false } : {}
+		},
+		...remote === void 0 ? {} : { remote },
+		...structured
+	};
+	Reflect.deleteProperty(settings, "remoteSideEffectsCache");
+	Reflect.deleteProperty(settings, "sideEffectsCacheReadonly");
+}
+function addRegistryScope(declarations, url, scope) {
+	declarations[url] ??= {};
+	const declaration = declarations[url];
+	declaration.scopes = [.../* @__PURE__ */ new Set([...declaration.scopes ?? [], scope])];
+}
+/**
+* Replace `namedRegistries` with URL-keyed registry declarations.
+*
+* A URL can expose only one canonical prefix. Conflicting legacy aliases are
+* therefore retained for manual resolution instead of being discarded.
+*
+* @param settings - Workspace settings to normalize in place
+* @param warnings - Collection that receives unresolved conflict warnings
+*/
+function normalizeNamedRegistries(settings, warnings) {
+	const { namedRegistries } = settings;
+	if (!namedRegistries) return;
+	const prefixesByUrl = /* @__PURE__ */ new Map();
+	for (const [prefix, url] of Object.entries(namedRegistries)) {
+		const prefixes = prefixesByUrl.get(url) ?? [];
+		prefixes.push(prefix);
+		prefixesByUrl.set(url, prefixes);
+	}
+	const conflicts = [...prefixesByUrl.entries()].filter(([, prefixes]) => prefixes.length > 1);
+	if (conflicts.length) {
+		warnings.push(`namedRegistries was kept because the new registries format supports one prefix per URL: ${conflicts.map(([url, prefixes]) => `${url} (${prefixes.join(", ")})`).join("; ")}.`);
+		return;
+	}
+	const declarations = {};
+	for (const [key, value] of Object.entries(settings.registries ?? {})) if (typeof value === "string") addRegistryScope(declarations, value, key === "default" ? "@" : key);
+	else declarations[key] = { ...value };
+	for (const [url, [prefix]] of prefixesByUrl) {
+		declarations[url] ??= {};
+		const declaration = declarations[url];
+		if (declaration.prefix && declaration.prefix !== prefix) {
+			warnings.push(`namedRegistries was kept because ${url} already declares prefix ${declaration.prefix}.`);
+			return;
+		}
+		declaration.prefix = prefix;
+	}
+	settings.registries = declarations;
+	Reflect.deleteProperty(settings, "namedRegistries");
+}
+/**
+* Replace aliases that remain accepted but are no longer canonical.
+*
+* @param settings - Workspace settings to normalize in place
+* @param warnings - Collection that receives unresolved conflict warnings
+*
+* @returns Nothing; settings and warnings are updated in place
+*/
+function normalizeCurrentAliases(settings, warnings) {
+	normalizeAuditSettings(settings);
+	normalizeUpdateSettings(settings);
+	normalizeScalarAliases(settings);
+	normalizeSideEffectsCache(settings);
+	normalizeNamedRegistries(settings, warnings);
+}
+//#endregion
 //#region src/utils/legacy-build-settings.ts
 /**
 * Read packages listed by the legacy `onlyBuiltDependenciesFile` setting.
+*
+* @param cwd - Workspace root directory
+* @param file - Path declared by the legacy setting
+*
+* @returns Validated package names, or an empty list when no file is declared
+*
+* @throws {TypeError} When the file does not contain an array of package names
 */
 async function readOnlyBuiltDependenciesFile(cwd, file) {
 	if (!file) return [];
@@ -387,6 +488,13 @@ async function readOnlyBuiltDependenciesFile(cwd, file) {
 /**
 * Read and validate one legacy build dependency list. Configuration files are
 * external input, so their runtime shape can differ from its declared type.
+*
+* @param settings - Workspace settings containing the legacy list
+* @param key - Legacy setting name to read
+*
+* @returns Validated package names, or an empty list when the setting is absent
+*
+* @throws {TypeError} When the setting is not an array of package names
 */
 function readLegacyBuildDependencyList(settings, key) {
 	const value = settings[key];
@@ -399,6 +507,11 @@ function readLegacyBuildDependencyList(settings, key) {
 }
 /**
 * Build an `allowBuilds` map from legacy build-script settings.
+*
+* @param incomingSettings - Legacy settings to read and normalize
+* @param cwd - Workspace root used to resolve dependency list files
+*
+* @returns Package permissions, or `undefined` when no legacy values exist
 */
 async function collectAllowBuildsFromLegacy(incomingSettings, cwd) {
 	const allowBuilds = {};
@@ -499,6 +612,7 @@ async function normalizeIncomingSettings(incomingSettings, options) {
 	const pmOnFail = resolvePmOnFail(incomingSettings);
 	if (pmOnFail) incomingSettings.pmOnFail = pmOnFail;
 	normalizeAuditConfig(incomingSettings, warnings);
+	if (replaceDeprecated) normalizeCurrentAliases(incomingSettings, warnings);
 	const runtimeVersion = resolveRuntimeVersion(incomingSettings, warnings);
 	if (incomingSettings.ignoreDepScripts !== void 0) warnings.push("ignoreDepScripts was removed in pnpm v11 and has no direct replacement.");
 	if (incomingSettings.ignorePatchFailures !== void 0) warnings.push("ignorePatchFailures was removed in pnpm v11; patch failures now always throw.");
@@ -559,6 +673,10 @@ const PNPM_V11_MAJOR = 11;
 const PNPM_V12_MAJOR = 12;
 /**
 * Resolve a pnpm major from a package manager declaration.
+*
+* @param hint - Package manager declaration to inspect
+*
+* @returns Detected pnpm major, or `undefined` when the hint does not match
 */
 function resolvePnpmMajor(hint) {
 	const match = hint?.match(/^pnpm@[\s<=>^~]*(?<major>\d+)(?:\.|\s|$)/u);
@@ -566,6 +684,10 @@ function resolvePnpmMajor(hint) {
 }
 /**
 * Normalize the single-or-array devEngines declaration.
+*
+* @param value - Optional single or multiple package manager declarations
+*
+* @returns Package manager declarations normalized to an array
 */
 function normalizePackageManagers(value) {
 	if (Array.isArray(value)) return value;
@@ -664,6 +786,380 @@ function mergeByStrategy(existing, incoming, strategy) {
 	}
 }
 //#endregion
+//#region src/settings-fields.ts
+/**
+* Settings that a project-level `pnpm-workspace.yaml` must never control.
+*
+* @see https://github.com/pnpm/pnpm/blob/main/pnpm11/config/reader/src/index.ts
+* @see https://github.com/pnpm/pnpm/blob/v12.2.1/pnpm/crates/config/src/refused_keys.rs
+*/
+const PNPM_PROJECT_REFUSED_SETTINGS = [
+	"allProjects",
+	"allProjectsGraph",
+	"authConfig",
+	"bin",
+	"cliOptions",
+	"configByUri",
+	"configDir",
+	"explicitlySetKeys",
+	"finders",
+	"globalBinDir",
+	"globalDir",
+	"globalPkgDir",
+	"hooks",
+	"npmrcAuthFile",
+	"packageManager",
+	"packageManagerNetworkConfig",
+	"packageManagerRegistries",
+	"pnpmHomeDir",
+	"prodAllProjectsGraph",
+	"prodOnlySelectedProjectDirs",
+	"rootProjectManifest",
+	"rootProjectManifestDir",
+	"scope",
+	"selectedProjectsGraph",
+	"stateDir",
+	"userConfig",
+	"userconfig",
+	"wantedPackageManager",
+	"workspaceDir"
+];
+/**
+* Settings added to, or recognized by, pnpm's v11 workspace config schema.
+* Combined with the v10 settings below to form the complete v11 allowlist.
+*
+* @see https://github.com/pnpm/pnpm/blob/main/pnpm11/config/reader/src/types.ts
+* @see https://github.com/pnpm/pnpm/blob/main/pnpm11/config/reader/src/unknownSettings.ts
+*/
+const PNPM_V11_ADDITIONAL_WORKSPACE_SETTINGS_FIELDS = [
+	"access",
+	"aggregateOutput",
+	"allowNew",
+	"allowSameVersion",
+	"audit",
+	"auditIgnorePrune",
+	"autoConfirmAllPrompts",
+	"bail",
+	"binLinks",
+	"catalog",
+	"catalogPrune",
+	"catalogs",
+	"changedFilesIgnorePattern",
+	"commitHooks",
+	"confirmModulesPurge",
+	"cpu",
+	"dedupePeers",
+	"depth",
+	"description",
+	"dev",
+	"dryRun",
+	"embedReadme",
+	"enablePnp",
+	"excludeLinksFromLockfile",
+	"extraBinPaths",
+	"extraEnv",
+	"fetchingConcurrency",
+	"filter",
+	"filterProd",
+	"force",
+	"frozenStore",
+	"git",
+	"gitTagVersion",
+	"global",
+	"globalPath",
+	"globalPrefix",
+	"hoistingLimits",
+	"ignoreCurrentSpecifiers",
+	"ignoreWorkspace",
+	"initAuthorEmail",
+	"initAuthorName",
+	"initAuthorUrl",
+	"initLicense",
+	"initPackageManager",
+	"initType",
+	"initVersion",
+	"json",
+	"legacyDirFiltering",
+	"libc",
+	"lockfileOnly",
+	"long",
+	"maxSockets",
+	"message",
+	"minimumReleaseAgeExcludePrune",
+	"minimumReleaseAgeIgnoreMissingTime",
+	"minimumReleaseAgeStrict",
+	"namedRegistries",
+	"nodeDownloadMirrors",
+	"nodeExperimentalPackageMap",
+	"nodePackageMapType",
+	"offline",
+	"only",
+	"os",
+	"packDestination",
+	"packGzipLevel",
+	"packageConfigs",
+	"packageLock",
+	"packages",
+	"parseable",
+	"patchesDir",
+	"pending",
+	"pmOnFail",
+	"pnpmExecPath",
+	"pnprServer",
+	"preferOffline",
+	"preserveAbsolutePaths",
+	"progress",
+	"provenance",
+	"publishBranch",
+	"recursive",
+	"registries",
+	"registriesByPrefix",
+	"registriesByScope",
+	"registry",
+	"registryOptionsByUrl",
+	"remoteSideEffectsCache",
+	"reporter",
+	"reporterHidePrefix",
+	"reverse",
+	"runtime",
+	"runtimeOnFail",
+	"save",
+	"saveCatalogName",
+	"saveDev",
+	"saveOptional",
+	"savePeer",
+	"saveProd",
+	"scriptsPrependNodePath",
+	"sideEffectsCacheRead",
+	"sideEffectsCacheWrite",
+	"signGitTag",
+	"skipManifestObfuscation",
+	"sort",
+	"stream",
+	"tasks",
+	"testPattern",
+	"trustLockfile",
+	"tryLoadDefaultPnpmfile",
+	"umask",
+	"update",
+	"useGitBranchLockfile",
+	"useLockfile",
+	"userAgent",
+	"version",
+	"versioning",
+	"virtualStoreOnly",
+	"virtualStoreType",
+	"workspacePackagePatterns",
+	"workspacePackages",
+	"workspacePrefix",
+	"workspaceRoot",
+	"yes"
+];
+const refusedProjectSettings = new Set(PNPM_PROJECT_REFUSED_SETTINGS);
+/**
+* Settings accepted by a pnpm v11 project workspace manifest.
+*/
+const PNPM_V11_WORKSPACE_SETTINGS_FIELDS = [.../* @__PURE__ */ new Set([...PNPM_V10_NPMRC_SETTINGS_FIELDS, ...PNPM_V11_ADDITIONAL_WORKSPACE_SETTINGS_FIELDS])].filter((field) => !refusedProjectSettings.has(field));
+/**
+* Settings that are supported by v11 but not by pnpm v12.
+*/
+const PNPM_V11_ONLY_WORKSPACE_SETTINGS = ["confirmModulesPurge", "packageConfigs"];
+/**
+* Settings introduced by pnpm v12.
+*/
+const PNPM_V12_ONLY_WORKSPACE_SETTINGS = [
+	"autoInstallPeersFromHighestMatch",
+	"externalDependencies",
+	"globalShims"
+];
+const v11OnlyWorkspaceSettings = new Set(PNPM_V11_ONLY_WORKSPACE_SETTINGS);
+/**
+* Settings accepted by a pnpm v12 project workspace manifest.
+*/
+const PNPM_V12_WORKSPACE_SETTINGS_FIELDS = [...PNPM_V11_WORKSPACE_SETTINGS_FIELDS.filter((field) => !v11OnlyWorkspaceSettings.has(field)), ...PNPM_V12_ONLY_WORKSPACE_SETTINGS];
+/**
+* Fields pnpm v11 accepts inside a `packageConfigs` entry.
+*/
+const PNPM_V11_PACKAGE_CONFIG_FIELDS = [
+	"hoist",
+	"modulesDir",
+	"overrides",
+	"saveExact",
+	"savePrefix"
+];
+//#endregion
+//#region src/utils/settings-schema.ts
+const PNPM_V10_WORKSPACE_SETTINGS_FIELDS = [
+	...PNPM_V10_NPMRC_SETTINGS_FIELDS,
+	"catalog",
+	"catalogs",
+	"packages"
+];
+const PROJECT_REFUSED_SETTINGS = new Set(PNPM_PROJECT_REFUSED_SETTINGS);
+const PNPM_V11_ONLY_SETTINGS = new Set(PNPM_V11_ONLY_WORKSPACE_SETTINGS);
+const PNPM_V11_SETTINGS = new Set(PNPM_V11_WORKSPACE_SETTINGS_FIELDS);
+const PNPM_V12_ONLY_SETTINGS = new Set(PNPM_V12_ONLY_WORKSPACE_SETTINGS);
+const PNPM_V12_SETTINGS = new Set(PNPM_V12_WORKSPACE_SETTINGS_FIELDS);
+const PNPM_V10_SETTINGS = new Set(PNPM_V10_WORKSPACE_SETTINGS_FIELDS);
+const REGISTRY_SETTINGS = /* @__PURE__ */ new Set([
+	"namedRegistries",
+	"registries",
+	"registriesByPrefix",
+	"registriesByScope",
+	"registry",
+	"registryOptionsByUrl"
+]);
+const REGISTRY_CREDENTIAL_KEYS = /* @__PURE__ */ new Set([
+	"auth",
+	"authtoken",
+	"password",
+	"token",
+	"tokenhelper",
+	"username"
+]);
+const WORKSPACE_SCHEMA_DIRECTIVE = "$schema";
+/**
+* Create an empty collection of schema selection issues.
+*
+* @returns Empty issue lists for every supported issue category
+*/
+function createSettingsIssues() {
+	return {
+		incompatible: [],
+		nonCamelCase: [],
+		refused: [],
+		unsafe: [],
+		unknown: [],
+		unsupported: []
+	};
+}
+function hasUrlCredentials(value) {
+	try {
+		const url = new URL(value);
+		return Boolean(url.username || url.password);
+	} catch {
+		return false;
+	}
+}
+function isRegistryCredentialKey(key) {
+	return REGISTRY_CREDENTIAL_KEYS.has(key.replaceAll("-", "").replaceAll("_", "").toLowerCase());
+}
+function isUnsafeRegistryUrl(value) {
+	return value.includes("${") || hasUrlCredentials(value);
+}
+function containsUnsafeRegistryValue(value, checkCredentialKeys = false) {
+	if (typeof value === "string") return isUnsafeRegistryUrl(value);
+	if (!value || typeof value !== "object") return false;
+	return Object.entries(value).some(([key, entryValue]) => checkCredentialKeys && isRegistryCredentialKey(key) || isUnsafeRegistryUrl(key) || containsUnsafeRegistryValue(entryValue, true));
+}
+function resolveCamelCaseKey(key) {
+	return Object.keys(camelcaseKeys({ [key]: true }))[0] ?? key;
+}
+function resolveTargetSettings(compatibility) {
+	switch (compatibility) {
+		case "v10": return PNPM_V10_SETTINGS;
+		case "v11": return PNPM_V11_SETTINGS;
+		case "v12": return PNPM_V12_SETTINGS;
+		default: throw new TypeError(`Unsupported compatibility target: ${compatibility}`);
+	}
+}
+function isSettingFromAnotherMajor(key, compatibility) {
+	if (compatibility === "v11") return PNPM_V12_ONLY_SETTINGS.has(key);
+	if (compatibility === "v12") return PNPM_V11_ONLY_SETTINGS.has(key);
+	return PNPM_V11_SETTINGS.has(key) || PNPM_V12_SETTINGS.has(key);
+}
+function resolveSettingIssue({ allowedFields, compatibility, key, npmrc, targetSettings, value }) {
+	if (!npmrc && key !== resolveCamelCaseKey(key)) return "nonCamelCase";
+	if (compatibility !== "v10" && PROJECT_REFUSED_SETTINGS.has(key)) return "refused";
+	if (REGISTRY_SETTINGS.has(key) && containsUnsafeRegistryValue(value)) return "unsafe";
+	if (!targetSettings.has(key)) return isSettingFromAnotherMajor(key, compatibility) ? "incompatible" : "unknown";
+	if (allowedFields && !allowedFields.has(key)) return "unsupported";
+}
+/**
+* Select settings that are valid for a concrete pnpm workspace schema.
+*
+* Unrecognized, refused, incompatible, and destination-specific unsupported
+* settings are reported but never returned for migration.
+*
+* @param rawSettings - Settings read from a legacy configuration source
+* @param compatibility - Concrete pnpm compatibility target
+* @param options - Source spelling and destination field restrictions
+*
+* @returns Selected settings, original source keys, and rejected field groups
+*/
+function selectPnpmSettings(rawSettings, compatibility, options = {}) {
+	const issues = createSettingsIssues();
+	const keys = [];
+	const settings = {};
+	const targetSettings = resolveTargetSettings(compatibility);
+	const allowedFields = options.allowedFields ? new Set(options.allowedFields) : void 0;
+	for (const [originalKey, value] of Object.entries(rawSettings)) {
+		const key = options.npmrc ? resolveCamelCaseKey(originalKey) : originalKey;
+		const issue = resolveSettingIssue({
+			allowedFields,
+			compatibility,
+			key,
+			npmrc: Boolean(options.npmrc),
+			targetSettings,
+			value
+		});
+		if (issue) issues[issue].push(originalKey);
+		else {
+			keys.push(originalKey);
+			settings[key] = value;
+		}
+	}
+	return {
+		issues,
+		keys,
+		settings
+	};
+}
+function assertPackageConfigFields(settings) {
+	const { packageConfigs } = settings;
+	if (packageConfigs === void 0) return;
+	const allowedFields = new Set(PNPM_V11_PACKAGE_CONFIG_FIELDS);
+	const entries = Array.isArray(packageConfigs) ? packageConfigs.flatMap((entry, index) => {
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new TypeError(`packageConfigs[${index}] must be an object with a match array.`);
+		const { match, ...config } = entry;
+		if (!Array.isArray(match) || !match.every((projectName) => typeof projectName === "string")) throw new TypeError(`packageConfigs[${index}].match must be an array of package names.`);
+		return [[`packageConfigs[${index}]`, config]];
+	}) : Object.entries(packageConfigs);
+	for (const [name, config] of entries) {
+		if (!config || typeof config !== "object" || Array.isArray(config)) throw new TypeError(`${name} must contain a project settings object.`);
+		const unsupported = Object.keys(config).filter((key) => !allowedFields.has(key));
+		if (unsupported.length) throw new TypeError(`${name} contains unsupported project settings: ${unsupported.map((key) => JSON.stringify(key)).join(", ")}.`);
+	}
+}
+function formatIssueList(keys) {
+	return keys.map((key) => JSON.stringify(key)).join(", ");
+}
+/**
+* Assert that an existing workspace manifest matches the selected pnpm major.
+*
+* The migrator refuses to rewrite a manifest containing ignored settings so a
+* migration cannot silently preserve invalid output.
+*
+* @param settings - Existing workspace settings to validate
+* @param compatibility - Concrete pnpm compatibility target
+*
+* @returns Nothing when all settings match the target schema
+*
+* @throws {TypeError} When the manifest contains incompatible settings
+*/
+function assertCompatibleWorkspaceSettings(settings, compatibility) {
+	if (compatibility === "v10") return;
+	const { issues } = selectPnpmSettings(Object.fromEntries(Object.entries(settings).filter(([key]) => key !== WORKSPACE_SCHEMA_DIRECTIVE)), compatibility);
+	const problems = [];
+	if (issues.refused.length) problems.push(`refused: ${formatIssueList(issues.refused)}`);
+	if (issues.incompatible.length) problems.push(`other pnpm major: ${formatIssueList(issues.incompatible)}`);
+	if (issues.nonCamelCase.length) problems.push(`not camelCase: ${formatIssueList(issues.nonCamelCase)}`);
+	if (issues.unknown.length) problems.push(`unrecognized: ${formatIssueList(issues.unknown)}`);
+	if (issues.unsafe.length) problems.push(`unsafe registry URL: ${formatIssueList(issues.unsafe)}`);
+	if (problems.length) throw new TypeError(`pnpm-workspace.yaml is incompatible with pnpm ${compatibility.slice(1)} (${problems.join("; ")}).`);
+	if (compatibility === "v11") assertPackageConfigFields(settings);
+}
+//#endregion
 //#region src/utils/npmrc.ts
 /**
 * Authentication and registry keys that must remain in `.npmrc`.
@@ -688,6 +1184,9 @@ const NPMRC_AUTH_OR_REGISTRY_KEYS = [
 * Pattern for pnpm's channel-specific Node.js mirror keys.
 */
 const NODE_MIRROR_KEY_PATTERN = /^node-mirror:(?<channel>.+)$/iu;
+function mergeSettingsIssues(target, source, sourceKeys) {
+	for (const reason of Object.keys(target)) if (source[reason].length) target[reason].push(...sourceKeys ?? source[reason]);
+}
 /**
 * Normalize `.npmrc` key for case-insensitive matching.
 *
@@ -762,23 +1261,26 @@ async function pruneNpmrc(path, compatibility, migratedKeys) {
 * 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`.
+* - `v11+`: selects target-schema settings and retains auth, registry,
+*   refused, incompatible, and unknown keys.
 *
 * @param path - Absolute path to the `.npmrc` file
 * @param compatibility - Concrete pnpm compatibility target
+* @param options - Optional destination-specific field restrictions
 *
 * @returns Migratable settings and their original `.npmrc` keys
 *
 * @throws {Error} When file reading or INI parsing fails
 */
-async function readMigratableNpmrc(path, compatibility) {
+async function readMigratableNpmrc(path, compatibility, options = {}) {
 	const raw = await readIniFile(path);
+	const issues = createSettingsIssues();
 	if (compatibility === "v10") {
 		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 {
+			issues,
 			keys,
 			settings: camelcaseKeys(migratable)
 		};
@@ -786,20 +1288,233 @@ async function readMigratableNpmrc(path, compatibility) {
 	const migratable = {};
 	const keys = [];
 	const nodeDownloadMirrors = {};
+	const nodeDownloadMirrorKeys = [];
 	for (const [key, value] of Object.entries(raw)) if (!isNpmrcAuthOrRegistryKey(key)) {
-		keys.push(key);
 		const nodeMirrorMatch = normalizeNpmrcKey(key).match(NODE_MIRROR_KEY_PATTERN);
-		if (nodeMirrorMatch?.groups?.channel) nodeDownloadMirrors[nodeMirrorMatch.groups.channel] = String(value);
-		else migratable[key] = value;
+		if (nodeMirrorMatch?.groups?.channel) {
+			nodeDownloadMirrorKeys.push(key);
+			nodeDownloadMirrors[nodeMirrorMatch.groups.channel] = String(value);
+		} else {
+			const selected = selectPnpmSettings({ [key]: value }, compatibility, {
+				allowedFields: options.allowedFields,
+				npmrc: true
+			});
+			keys.push(...selected.keys);
+			Object.assign(migratable, selected.settings);
+			mergeSettingsIssues(issues, selected.issues);
+		}
 	}
 	const settings = camelcaseKeys(migratable);
-	if (Object.keys(nodeDownloadMirrors).length) settings.nodeDownloadMirrors = nodeDownloadMirrors;
+	if (Object.keys(nodeDownloadMirrors).length) {
+		const selected = selectPnpmSettings({ nodeDownloadMirrors }, compatibility, { allowedFields: options.allowedFields });
+		if (selected.keys.length) {
+			keys.push(...nodeDownloadMirrorKeys);
+			settings.nodeDownloadMirrors = nodeDownloadMirrors;
+		} else mergeSettingsIssues(issues, selected.issues, nodeDownloadMirrorKeys);
+	}
 	return {
+		issues,
 		keys,
 		settings
 	};
 }
 //#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,
+		value: {}
+	};
+	const content = await fsReadFile(path);
+	return {
+		indent: detectIndent(content).indent,
+		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: 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
+* @param compatibility - Concrete pnpm compatibility target
+*
+* @returns Selected workspace settings and source cleanup metadata
+*/
+function resolvePackageJsonSettings(packageJson, yarnResolutions, compatibility) {
+	const selected = selectPnpmSettings(Object.fromEntries(Object.entries(packageJson.pnpm ?? {})), compatibility);
+	const migrateYarnResolutions = Boolean(yarnResolutions && packageJson.resolutions);
+	const pnpmSettings = migrateYarnResolutions ? {
+		...selected.settings,
+		overrides: defu(selected.settings.overrides, packageJson.resolutions)
+	} : { ...selected.settings };
+	if (pnpmSettings.overrides && !Object.keys(pnpmSettings.overrides).length) delete pnpmSettings.overrides;
+	return {
+		issues: selected.issues,
+		keys: selected.keys,
+		settings: pnpmSettings,
+		yarnResolutions: migrateYarnResolutions
+	};
+}
+//#endregion
+//#region src/utils/project-npmrc.ts
+function resolvePackageJsonPatterns(patterns) {
+	return patterns.map((pattern) => {
+		const negated = pattern.startsWith("!");
+		const workspacePattern = (negated ? pattern.slice(1) : pattern).replace(/\/+$/u, "");
+		const packageJsonPattern = workspacePattern === "." ? PACKAGE_JSON : `${workspacePattern}/${PACKAGE_JSON}`;
+		return negated ? `!${packageJsonPattern}` : packageJsonPattern;
+	});
+}
+/**
+* Collect unique workspace package patterns from multiple settings sources.
+*
+* @param settingsSources - Workspace settings that may declare package patterns
+*
+* @returns Unique package patterns in source order
+*/
+function collectWorkspacePackagePatterns(...settingsSources) {
+	return [...new Set(settingsSources.flatMap((settings) => Array.isArray(settings.packages) ? settings.packages : []))];
+}
+async function readProjectManifestCandidates(cwd, patterns) {
+	if (!patterns.some((pattern) => !pattern.startsWith("!"))) return {
+		candidates: [],
+		warnings: []
+	};
+	const rootPackageJsonPath = resolve(cwd, PACKAGE_JSON);
+	const packageJsonPaths = await glob(resolvePackageJsonPatterns(patterns), {
+		absolute: true,
+		cwd,
+		dot: true,
+		ignore: ["**/node_modules/**"],
+		onlyFiles: true
+	});
+	const candidateResults = await Promise.all([...new Set(packageJsonPaths)].sort().filter((packageJsonPath) => resolve(packageJsonPath) !== rootPackageJsonPath).map(async (packageJsonPath) => {
+		const projectDir = dirname(packageJsonPath);
+		const npmrcPath = resolve(projectDir, NPMRC);
+		if (!await fsExists(npmrcPath)) return {};
+		const packageJson = await readPackageJson(packageJsonPath, true);
+		if (!packageJson.value.name) return { warning: `${relative(cwd, npmrcPath)} was kept because its package.json has no name for packageConfigs matching.` };
+		return { candidate: {
+			npmrcPath,
+			packageJsonPath,
+			projectName: packageJson.value.name
+		} };
+	}));
+	const candidates = [];
+	const warnings = [];
+	for (const result of candidateResults) {
+		if (result.candidate) candidates.push(result.candidate);
+		if (result.warning) warnings.push(result.warning);
+	}
+	return {
+		candidates,
+		warnings
+	};
+}
+/**
+* Collect supported settings from subproject `.npmrc` files.
+*
+* pnpm v11 accepts five fields in `packageConfigs`. pnpm v12 does not support
+* `packageConfigs`, so its subproject settings are only reported and retained.
+*
+* @param cwd - Workspace root directory
+* @param patterns - Workspace package patterns used to discover subprojects
+* @param compatibility - Concrete pnpm compatibility target
+*
+* @returns Migratable project settings, source metadata, and warnings
+*/
+async function readProjectNpmrcMigrations(cwd, patterns, compatibility) {
+	if (compatibility === "v10") return {
+		packageConfigs: {},
+		projects: [],
+		warnings: []
+	};
+	const { candidates, warnings } = await readProjectManifestCandidates(cwd, patterns);
+	const candidatesByName = /* @__PURE__ */ new Map();
+	for (const candidate of candidates) {
+		const namedCandidates = candidatesByName.get(candidate.projectName) ?? [];
+		namedCandidates.push(candidate);
+		candidatesByName.set(candidate.projectName, namedCandidates);
+	}
+	const packageConfigs = {};
+	const projects = [];
+	const allowedFields = compatibility === "v11" ? PNPM_V11_PACKAGE_CONFIG_FIELDS : [];
+	const migrationResults = await Promise.all([...candidatesByName].map(async ([projectName, namedCandidates]) => {
+		if (namedCandidates.length > 1) return { warning: `Subproject .npmrc files for duplicate package name ${JSON.stringify(projectName)} were kept: ${namedCandidates.map((candidate) => relative(cwd, candidate.packageJsonPath)).join(", ")}.` };
+		const [candidate] = namedCandidates;
+		return { project: {
+			migratable: await readMigratableNpmrc(candidate.npmrcPath, compatibility, { allowedFields }),
+			npmrcPath: candidate.npmrcPath,
+			projectName
+		} };
+	}));
+	for (const result of migrationResults) {
+		if (result.warning) warnings.push(result.warning);
+		if (result.project) {
+			projects.push(result.project);
+			if (result.project.migratable.keys.length) packageConfigs[result.project.projectName] = result.project.migratable.settings;
+		}
+	}
+	return {
+		packageConfigs,
+		projects,
+		warnings
+	};
+}
+//#endregion
 //#region src/utils/settings-change.ts
 /**
 * Maximum dynamic-programming cells used for an exact line diff.
@@ -833,6 +1548,11 @@ function collectSettingsChanges(before, after) {
 *
 * This fallback deliberately gives up the exact LCS for unusually large
 * settings to keep reporting from exhausting memory after migration writes.
+*
+* @param beforeLines - YAML lines before migration
+* @param afterLines - YAML lines after migration
+*
+* @returns Classified diff lines in display order
 */
 function createLinearLineDiff(beforeLines, afterLines) {
 	let prefixLength = 0;
@@ -964,9 +1684,35 @@ function reportSettingsChanges(changes) {
 	}
 }
 //#endregion
+//#region src/utils/settings-issue-report.ts
+function formatIssueKeys(keys) {
+	return keys.map((key) => JSON.stringify(key)).join(", ");
+}
+/**
+* Report settings that were intentionally left in their source.
+*
+* @param options - Retained settings and destination context
+*
+* @returns Nothing; warnings are written through consola
+*/
+function reportSettingsIssues(options) {
+	const { compatibility, issues, projectConfig = false, source } = options;
+	if (issues.refused.length) consola$1.warn(`Kept project-refused settings in ${source}: ${formatIssueKeys(issues.refused)}. Configure machine settings globally and current-run paths on the command line.`);
+	if (issues.incompatible.length) consola$1.warn(`Kept settings in ${source} that are incompatible with pnpm ${compatibility.slice(1)}: ${formatIssueKeys(issues.incompatible)}.`);
+	if (issues.nonCamelCase.length) consola$1.warn(`Kept non-camelCase settings in ${source}: ${formatIssueKeys(issues.nonCamelCase)}. Workspace manifest keys must use camelCase.`);
+	if (issues.unknown.length) consola$1.warn(`Kept settings in ${source} that pnpm ${compatibility.slice(1)} does not recognize: ${formatIssueKeys(issues.unknown)}.`);
+	if (issues.unsupported.length) {
+		const destination = projectConfig && compatibility === "v12" ? "pnpm v12 does not support packageConfigs" : "packageConfigs only accepts hoist, modulesDir, overrides, saveExact, and savePrefix";
+		consola$1.warn(`Kept subproject settings in ${source}: ${formatIssueKeys(issues.unsupported)}; ${destination}.`);
+	}
+	if (issues.unsafe.length) consola$1.warn(`Kept unsafe registry settings in ${source}: ${formatIssueKeys(issues.unsafe)}. Remove credentials and dynamic URL interpolation before migrating them.`);
+}
+//#endregion
 //#region src/utils/yaml-document.ts
 /**
 * Sort every mapping in a YAML node without replacing its comments or anchors.
+*
+* @param node - YAML node whose nested mappings should be sorted
 */
 function sortYamlMappings(node) {
 	if (isMap(node)) {
@@ -983,6 +1729,11 @@ function sortYamlMappings(node) {
 /**
 * Apply semantic root changes to the parsed document while retaining untouched
 * YAML nodes and their source metadata.
+*
+* @param document - Parsed YAML document to update in place
+* @param options - Before/after settings and sorting preference
+*
+* @returns Nothing; the document is updated in place
 */
 function updateYamlDocument(document, options) {
 	const { after, before, sortKeys } = options;
@@ -992,91 +1743,253 @@ function updateYamlDocument(document, options) {
 }
 /**
 * Normalize blank lines immediately before root mapping keys.
+*
+* @param content - Serialized workspace YAML
+* @param newlineBetween - Whether root keys should be separated by blank lines
+*
+* @returns YAML with normalized root-key spacing
 */
 function formatRootSpacing(content, newlineBetween) {
 	return content.replace(/\n+(?=[^\s#][^:\n]*:)/gu, newlineBetween ? "\n\n" : "\n");
 }
 //#endregion
-//#region src/utils/config.ts
+//#region src/migration-persistence.ts
+const SETTINGS_WITHOUT_REPLACEMENT = /* @__PURE__ */ new Set(["ignoreDepScripts", "ignorePatchFailures"]);
+const REPLACEMENT_SETTING_KEYS = {
+	allowNonAppliedPatches: "allowUnusedPatches",
+	auditConfig: "audit",
+	auditLevel: "audit",
+	cleanupUnusedCatalogs: "catalogPrune",
+	enableGlobalVirtualStore: "virtualStoreType",
+	ignoredBuiltDependencies: "allowBuilds",
+	managePackageManagerVersions: "pmOnFail",
+	namedRegistries: "registries",
+	neverBuiltDependencies: "allowBuilds",
+	onlyBuiltDependencies: "allowBuilds",
+	onlyBuiltDependenciesFile: "allowBuilds",
+	packageManagerStrict: "pmOnFail",
+	packageManagerStrictVersion: "pmOnFail",
+	remoteSideEffectsCache: "sideEffectsCache",
+	sideEffectsCacheReadonly: "sideEffectsCache",
+	updateConfig: "update"
+};
+function cleanPackageJsonSettings({ migratedKeys, packageJson, settings, yarnResolutionsApplied }) {
+	let changed = false;
+	if (packageJson.value.pnpm) {
+		for (const key of migratedKeys) {
+			Reflect.deleteProperty(packageJson.value.pnpm, key);
+			changed = true;
+		}
+		if (!Object.keys(packageJson.value.pnpm).length) delete packageJson.value.pnpm;
+	}
+	if (settings.yarnResolutions && yarnResolutionsApplied) {
+		changed = true;
+		delete packageJson.value.resolutions;
+	}
+	return changed;
+}
+function containsMigratedValue(actual, expected) {
+	if (Array.isArray(actual) && Array.isArray(expected)) return expected.every((expectedItem) => actual.some((actualItem) => containsMigratedValue(actualItem, expectedItem)));
+	if (actual && expected && typeof actual === "object" && typeof expected === "object") return Object.entries(expected).every(([key, expectedValue]) => containsMigratedValue(actual[key], expectedValue));
+	return Object.is(actual, expected);
+}
+function resolveSourceRuntimeVersion(sourceSettings, targetKey) {
+	if (targetKey === "useNodeVersion") return Reflect.get(sourceSettings, "useNodeVersion");
+	const executionEnv = Reflect.get(sourceSettings, "executionEnv");
+	if (!executionEnv || typeof executionEnv !== "object" || Array.isArray(executionEnv)) return;
+	return executionEnv.nodeVersion;
+}
+function resolveReplacementSettingKey(sourceKey, targetKey, npmrc) {
+	if (npmrc && /^node-mirror:/iu.test(sourceKey)) return "nodeDownloadMirrors";
+	return REPLACEMENT_SETTING_KEYS[targetKey];
+}
+function selectAppliedRootKeys({ finalSettings, incomingSettings, keys, npmrc = false, runtimeApplied, runtimeVersion, sourceSettings }) {
+	return keys.filter((sourceKey) => {
+		const targetKey = npmrc ? Object.keys(camelcaseKeys({ [sourceKey]: true }))[0] ?? sourceKey : sourceKey;
+		if (!Object.hasOwn(incomingSettings, targetKey)) {
+			if (targetKey === "executionEnv" || targetKey === "useNodeVersion") {
+				const sourceRuntimeVersion = resolveSourceRuntimeVersion(sourceSettings, targetKey);
+				return runtimeApplied && typeof sourceRuntimeVersion === "string" && sourceRuntimeVersion === runtimeVersion;
+			}
+			if (SETTINGS_WITHOUT_REPLACEMENT.has(targetKey)) return false;
+			const replacementKey = resolveReplacementSettingKey(sourceKey, targetKey, npmrc);
+			if (!replacementKey || !Object.hasOwn(incomingSettings, replacementKey)) return true;
+			return containsMigratedValue(Reflect.get(finalSettings, replacementKey), Reflect.get(incomingSettings, replacementKey));
+		}
+		return containsMigratedValue(Reflect.get(finalSettings, targetKey), Reflect.get(incomingSettings, targetKey));
+	});
+}
+function resolveProjectConfig(settings, projectName) {
+	const { packageConfigs } = settings;
+	if (!packageConfigs || typeof packageConfigs !== "object" || Array.isArray(packageConfigs)) return;
+	const projectConfig = packageConfigs[projectName];
+	return projectConfig && typeof projectConfig === "object" && !Array.isArray(projectConfig) ? projectConfig : void 0;
+}
+function selectAppliedProjectKeys(project, finalSettings) {
+	const finalProjectConfig = resolveProjectConfig(finalSettings, project.projectName);
+	if (!finalProjectConfig) return [];
+	return project.migratable.keys.filter((sourceKey) => {
+		const targetKey = Object.keys(camelcaseKeys({ [sourceKey]: true }))[0] ?? sourceKey;
+		return containsMigratedValue(finalProjectConfig[targetKey], project.migratable.settings[targetKey]);
+	});
+}
 /**
-* Resolve the indentation width for a YAML document.
+* Persist destinations before pruning any legacy source file.
 *
-* @param content - Raw YAML content
+* @param options - Destination files, selected sources, and cleanup policy
 *
-* @returns Detected indentation width or the project default
+* @returns A promise that resolves after destinations and sources are persisted
 */
-function resolveYamlIndent(content) {
-	const detectedIndent = detectIndent(content).amount;
-	return detectedIndent > 0 ? detectedIndent : 2;
+async function persistMigration(options) {
+	const { cleanNpmrc, cleanPackageJson, compatibility, finalSettings, incomingSettings, npmrc, npmrcExists, npmrcPath, packageJson, packageJsonExists, packageJsonPath, packageJsonRuntimeChanged, packageJsonSettings, pnpmWorkspaceContent, pnpmWorkspacePath, projectNpmrcs, runtimeVersion } = options;
+	const appliedPackageJsonKeys = selectAppliedRootKeys({
+		finalSettings,
+		incomingSettings,
+		keys: packageJsonSettings.keys,
+		runtimeApplied: packageJsonRuntimeChanged,
+		runtimeVersion,
+		sourceSettings: packageJsonSettings.settings
+	});
+	const appliedNpmrcKeys = selectAppliedRootKeys({
+		finalSettings,
+		incomingSettings,
+		keys: npmrc.keys,
+		npmrc: true,
+		runtimeApplied: packageJsonRuntimeChanged,
+		runtimeVersion,
+		sourceSettings: npmrc.settings
+	});
+	const yarnResolutionsApplied = packageJsonSettings.yarnResolutions && containsMigratedValue(finalSettings.overrides, incomingSettings.overrides);
+	const packageJsonSettingsChanged = packageJsonExists && cleanPackageJson ? cleanPackageJsonSettings({
+		migratedKeys: appliedPackageJsonKeys,
+		packageJson,
+		settings: packageJsonSettings,
+		yarnResolutionsApplied
+	}) : false;
+	await fsWriteFile(pnpmWorkspacePath, pnpmWorkspaceContent);
+	if (packageJsonExists && (packageJsonRuntimeChanged || packageJsonSettingsChanged)) await fsWriteFile(packageJsonPath, JSON.stringify(packageJson.value, null, packageJson.indent));
+	if (!cleanNpmrc) return;
+	const pruneTasks = projectNpmrcs.projects.flatMap((project) => {
+		const appliedKeys = selectAppliedProjectKeys(project, finalSettings);
+		return appliedKeys.length ? [pruneNpmrc(project.npmrcPath, compatibility, appliedKeys)] : [];
+	});
+	if (npmrcExists && appliedNpmrcKeys.length) pruneTasks.push(pruneNpmrc(npmrcPath, compatibility, appliedNpmrcKeys));
+	await Promise.all(pruneTasks);
 }
+//#endregion
+//#region src/migration-sources.ts
 /**
-* Read and parse a package manifest when it exists.
-*
-* @param path - Absolute path to `package.json`
-* @param exists - Whether the package manifest exists
+* Read, schema-filter, report, and merge all legacy settings sources.
 *
-* @returns Parsed package manifest and detected indentation
+* @param options - Migration target and source configuration
 *
-* @throws {SyntaxError} When the package manifest contains invalid JSON
+* @returns Resolved source metadata and merged incoming settings
 */
-async function readPackageJson(path, exists) {
-	if (!exists) return {
-		indent: 2,
-		value: {}
+async function resolveMigrationSources(options) {
+	const { compatibility, cwd, npmrcExists, npmrcPath, packageJson, pnpmWorkspace, strategy, yarnResolutions } = options;
+	const npmrc = npmrcExists ? await readMigratableNpmrc(npmrcPath, compatibility) : {
+		issues: createSettingsIssues(),
+		keys: [],
+		settings: {}
 	};
-	const content = await fsReadFile(path);
+	reportSettingsIssues({
+		compatibility,
+		issues: npmrc.issues,
+		source: NPMRC
+	});
+	const packageJsonSettings = resolvePackageJsonSettings(packageJson, yarnResolutions, compatibility);
+	reportSettingsIssues({
+		compatibility,
+		issues: packageJsonSettings.issues,
+		source: `${PACKAGE_JSON}#pnpm`
+	});
+	const projectNpmrcs = await readProjectNpmrcMigrations(cwd, collectWorkspacePackagePatterns(mergeByStrategy(pnpmWorkspace, mergeByStrategy(packageJsonSettings.settings, npmrc.settings, "merge"), strategy)), compatibility);
+	for (const warning of projectNpmrcs.warnings) consola$1.warn(warning);
+	for (const project of projectNpmrcs.projects) reportSettingsIssues({
+		compatibility,
+		issues: project.migratable.issues,
+		projectConfig: true,
+		source: relative(cwd, project.npmrcPath)
+	});
+	const npmrcSettings = mergeByStrategy(npmrc.settings, Object.keys(projectNpmrcs.packageConfigs).length ? { packageConfigs: projectNpmrcs.packageConfigs } : {}, "merge");
 	return {
-		indent: detectIndent(content).indent,
-		value: JSON.parse(content)
+		incomingSettings: mergeByStrategy(packageJsonSettings.settings, npmrcSettings, "merge"),
+		npmrc,
+		packageJson: packageJsonSettings,
+		projectNpmrcs
 	};
 }
+//#endregion
+//#region src/options.ts
 /**
-* 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
+* Default values for migration options.
 */
-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: parsedValue ?? {}
-	};
+const DEFAULT_OPTIONS = {
+	cleanNpmrc: true,
+	cleanPackageJson: true,
+	compatibility: "auto",
+	newlineBetween: true,
+	replaceDeprecated: false,
+	showChanges: true,
+	sortKeys: false,
+	strategy: "merge",
+	yarnResolutions: true
+};
+const VALID_STRATEGIES = [
+	"discard",
+	"merge",
+	"overwrite"
+];
+const VALID_COMPATIBILITIES = [
+	"auto",
+	"v10",
+	"v11",
+	"v12"
+];
+function resolveCompatibility(compatibility) {
+	if (!compatibility) return DEFAULT_OPTIONS.compatibility;
+	if (VALID_COMPATIBILITIES.includes(compatibility)) return compatibility;
+	throw new Error(`Invalid compatibility: ${compatibility}. Expected one of: ${VALID_COMPATIBILITIES.join(", ")}`);
+}
+function resolveStrategy(strategy) {
+	if (!strategy) return DEFAULT_OPTIONS.strategy;
+	if (VALID_STRATEGIES.includes(strategy)) return strategy;
+	throw new Error(`Invalid strategy: ${strategy}. Expected one of: ${VALID_STRATEGIES.join(", ")}`);
 }
 /**
-* Resolve migratable pnpm settings from a package manifest.
+* Resolve and normalize migration options with defaults.
 *
-* Yarn resolutions are merged into pnpm overrides when enabled. Empty
-* overrides are removed from the result.
+* This function takes partial options and returns a complete options object
+* with all properties set to either the provided value or the default value.
 *
-* @param packageJson - Parsed package manifest
-* @param yarnResolutions - Whether to convert Yarn resolutions to pnpm overrides
+* @param options - Partial migration options
+*
+* @returns Complete options object with all required properties
+*
+* @example
+* ```ts
+* // Use all defaults
+* const opts = resolveOptions()
+* // { cleanNpmrc: true, cleanPackageJson: true, cwd: '/current/dir', ... }
 *
-* @returns Pnpm workspace settings resolved from the package manifest
+* // Override specific options
+* const opts = resolveOptions({ sortKeys: true, cleanNpmrc: false })
+* // { cleanNpmrc: false, cleanPackageJson: true, sortKeys: true, ... }
+* ```
 */
-function resolvePackageJsonSettings(packageJson, yarnResolutions) {
-	const pnpmSettings = yarnResolutions && packageJson.resolutions ? {
-		...packageJson.pnpm,
-		overrides: defu(packageJson.pnpm?.overrides, packageJson.resolutions)
-	} : { ...packageJson.pnpm };
-	if (pnpmSettings.overrides && !Object.keys(pnpmSettings.overrides).length) delete pnpmSettings.overrides;
-	return pnpmSettings;
+function resolveOptions(options = {}) {
+	return {
+		cleanNpmrc: options.cleanNpmrc ?? DEFAULT_OPTIONS.cleanNpmrc,
+		compatibility: resolveCompatibility(options.compatibility),
+		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,
+		cleanPackageJson: options.cleanPackageJson ?? DEFAULT_OPTIONS.cleanPackageJson,
+		replaceDeprecated: options.replaceDeprecated ?? DEFAULT_OPTIONS.replaceDeprecated
+	};
 }
 //#endregion
 //#region src/core.ts
@@ -1088,8 +2001,8 @@ function hasSettingsSources(npmrcExists, packageJsonExists, pnpmWorkspaceExists)
 	return false;
 }
 function hasMigratableSettings(sources) {
-	const { existingSettingsChanged, packageJson, pnpmSettingsInNpmrc, yarnResolutions } = sources;
-	return Boolean(existingSettingsChanged || packageJson.pnpm || yarnResolutions && packageJson.resolutions || Object.keys(pnpmSettingsInNpmrc).length);
+	const { existingSettingsChanged, npmrcKeys, packageJsonKeys, projectNpmrcKeys, yarnResolutions } = sources;
+	return Boolean(existingSettingsChanged || npmrcKeys.length || packageJsonKeys.length || projectNpmrcKeys.length || yarnResolutions);
 }
 function assertCanMigrateRuntime(runtimeVersion, packageJsonExists) {
 	if (runtimeVersion && !packageJsonExists) throw new Error("Cannot migrate the removed Node.js runtime setting without a package.json file.");
@@ -1112,10 +2025,13 @@ function reportMigrationChanges(showChanges, before = {}, after = {}) {
 * @param rawOptions.cwd - Current working directory (default: process.cwd())
 * @param rawOptions.cleanNpmrc - Whether to remove pnpm settings from `.npmrc` (default: true)
 * @param rawOptions.cleanPackageJson - Whether to remove pnpm field from `package.json` (default: true)
+* @param rawOptions.compatibility - Target pnpm major, or automatic detection (default: auto)
 * @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.replaceDeprecated - Whether to replace deprecated settings (default: false)
 * @param rawOptions.showChanges - Show settings changes after migration (default: true)
+* @param rawOptions.strategy - Conflict handling strategy (default: merge)
 *
 * @returns A promise that resolves when migration is complete
 *
@@ -1152,12 +2068,18 @@ async function migratePnpmSettings(rawOptions = {}) {
 		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 incomingSettings = mergeByStrategy(resolvePackageJsonSettings(packageJson.value, options.yarnResolutions), pnpmSettingsInNpmrc, "merge");
+		assertCompatibleWorkspaceSettings(pnpmWorkspace.value, compatibility);
+		const sources = await resolveMigrationSources({
+			compatibility,
+			cwd: options.cwd,
+			npmrcExists,
+			npmrcPath,
+			packageJson: packageJson.value,
+			pnpmWorkspace: pnpmWorkspace.value,
+			strategy: options.strategy,
+			yarnResolutions: options.yarnResolutions
+		});
+		const { incomingSettings } = sources;
 		const [existingNormalization, incomingNormalization] = await Promise.all([normalizeIncomingSettings(pnpmWorkspace.value, {
 			compatibility,
 			cwd: options.cwd,
@@ -1174,9 +2096,10 @@ async function migratePnpmSettings(rawOptions = {}) {
 		if (runtimeMigration.warning) consola$1.warn(runtimeMigration.warning);
 		if (!hasMigratableSettings({
 			existingSettingsChanged: existingNormalization.changed,
-			packageJson: packageJson.value,
-			pnpmSettingsInNpmrc,
-			yarnResolutions: options.yarnResolutions
+			npmrcKeys: sources.npmrc.keys,
+			packageJsonKeys: sources.packageJson.keys,
+			projectNpmrcKeys: sources.projectNpmrcs.projects.flatMap((project) => project.migratable.keys),
+			yarnResolutions: sources.packageJson.yarnResolutions
 		})) {
 			consola$1.warn("No pnpm settings fields to migrate");
 			reportMigrationChanges(options.showChanges);
@@ -1189,18 +2112,25 @@ async function migratePnpmSettings(rawOptions = {}) {
 			sortKeys: options.sortKeys
 		});
 		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;
-			delete packageJson.value.pnpm;
-			if (options.yarnResolutions && packageJson.value.resolutions) {
-				packageJsonChanged = true;
-				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);
+		await persistMigration({
+			cleanNpmrc: options.cleanNpmrc,
+			cleanPackageJson: options.cleanPackageJson,
+			compatibility,
+			finalSettings: pnpmWorkspaceResult,
+			incomingSettings,
+			npmrc: sources.npmrc,
+			npmrcExists,
+			npmrcPath,
+			packageJson,
+			packageJsonExists,
+			packageJsonPath,
+			packageJsonRuntimeChanged: runtimeMigration.changed,
+			packageJsonSettings: sources.packageJson,
+			pnpmWorkspaceContent: finalYamlContent,
+			pnpmWorkspacePath: pnpmWorkspaceYamlPath,
+			projectNpmrcs: sources.projectNpmrcs,
+			runtimeVersion
+		});
 		reportMigrationChanges(options.showChanges, pnpmWorkspaceBefore, pnpmWorkspaceResult);
 	} catch (err) {
 		consola$1.error("Failed to migrate pnpm settings:", err);