pnpm-settings-migrator 0.7.0 → 0.8.0

package/README.md

@@ -15,6 +15,20 @@ Run in your workspace root:
 pnpm dlx pnpm-settings-migrator
 ```
 
+After migration, the CLI reports how many root settings changed and shows a
+GitHub-style YAML diff. Removed lines are red and added lines are green:
+
+```text
+ℹ 2 settings changed
+  packages:
+    - packages/*
++   - apps/*
+
+  overrides:
+    foo: 1.0.0
++   bar: 2.0.0
+```
+
 ## CLI Options
 
 ### `--cwd`
@@ -113,6 +127,14 @@ Strategy to handle conflicts when merging settings with existing `pnpm-workspace
 
 Disable migrating `resolutions` field in `package.json`.
 
+### `--no-show-changes`
+
+- **Type**: `boolean`
+- **Default behavior**: `showChanges=true` (use this flag to disable)
+
+Disable showing the settings diff after migration. Library consumers can set
+`showChanges: false`.
+
 ### `--no-clean-npmrc`
 
 - **Type**: `boolean`

package/dist/cli.mjs

@@ -2,7 +2,7 @@ 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 { Document, parse, stringify } from "yaml";
 import { access, readFile, rm, writeFile } from "node:fs/promises";
 import { getColor } from "consola/utils";
 import { isPlainObject, isUndefined, pick } from "@ntnyq/utils";
@@ -10,10 +10,11 @@ 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 detectIndent from "detect-indent";
 //#region package.json
 var name = "pnpm-settings-migrator";
-var version = "0.7.0";
+var version = "0.8.0";
 //#endregion
 //#region src/constants.ts
 const NPMRC = ".npmrc";
@@ -158,6 +159,7 @@ const DEFAULT_OPTIONS = {
 	cwd: process.cwd(),
 	newlineBetween: true,
 	replaceDeprecated: false,
+	showChanges: true,
 	sortKeys: false,
 	strategy: "merge",
 	yarnResolutions: true
@@ -210,6 +212,7 @@ function resolveOptions(options = {}) {
 		compatibility: resolveCompatibility(options.compatibility),
 		cwd: options.cwd ?? DEFAULT_OPTIONS.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,45 +223,73 @@ function resolveOptions(options = {}) {
 //#endregion
 //#region src/utils/fs.ts
 /**
-* Check if a path exists
-* @param path - given path
-* @returns `true` if exists, false otherwise
+* 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");
 }
 getColor("cyan");
 getColor("yellow");
+/**
+* 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
+/**
+* Legacy build settings that can be replaced for pnpm v10.
+*/
 const PNPM_REPLACEABLE_IN_V10_SETTINGS = [
 	"allowNonAppliedPatches",
 	"ignoredBuiltDependencies",
@@ -268,6 +299,14 @@ const PNPM_REPLACEABLE_IN_V10_SETTINGS = [
 ];
 /**
 * Read packages listed by the legacy `onlyBuiltDependenciesFile` setting.
+*
+* @param cwd - Working directory used to resolve the referenced file
+* @param file - Relative path stored in `onlyBuiltDependenciesFile`
+*
+* @returns Package names read from the referenced JSON file
+*
+* @throws {TypeError} When the referenced JSON value is not a string array
+* @throws {SyntaxError} When the referenced file contains invalid JSON
 */
 async function readOnlyBuiltDependenciesFile(cwd, file) {
 	if (!file) return [];
@@ -278,6 +317,11 @@ async function readOnlyBuiltDependenciesFile(cwd, file) {
 }
 /**
 * Build an `allowBuilds` map from legacy build-script settings.
+*
+* @param incomingSettings - Settings containing legacy build declarations
+* @param cwd - Working directory used to resolve referenced files
+*
+* @returns Package-to-permission map, or `undefined` when no entries exist
 */
 async function collectAllowBuildsFromLegacy(incomingSettings, cwd) {
 	const allowBuilds = {};
@@ -289,6 +333,10 @@ async function collectAllowBuildsFromLegacy(incomingSettings, cwd) {
 }
 /**
 * 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 +347,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 +363,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 +377,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 +417,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 +444,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,10 +457,22 @@ 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 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;
@@ -470,6 +558,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 +577,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 +608,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);
@@ -521,6 +627,8 @@ function isNpmrcAuthOrRegistryKey(key) {
 * 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
 *
@@ -547,30 +655,18 @@ 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);
@@ -598,11 +694,136 @@ async function readMigratableNpmrc(path, compatibility) {
 	};
 }
 //#endregion
+//#region src/utils/settings-change.ts
+/**
+* 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 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) {
+	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");
+}
+/**
+* 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));
+}
+/**
+* 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/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,6 +835,16 @@ 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 {
 		indent: 2,
@@ -625,6 +856,17 @@ async function readPnpmWorkspace(path, exists) {
 		value: parse(content) ?? {}
 	};
 }
+/**
+* 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 +891,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 +912,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,8 +942,12 @@ 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: [],
@@ -729,6 +980,7 @@ 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);
@@ -752,6 +1004,7 @@ async function migratePnpmSettings(rawOptions = {}) {
 			}
 		}
 		if (packageJsonExists && packageJsonChanged) await fsWriteFile(packageJsonPath, JSON.stringify(packageJson.value, null, packageJson.indent));
+		reportMigrationChanges(options.showChanges, pnpmWorkspaceBefore, pnpmWorkspaceResult);
 	} catch (err) {
 		consola$1.error("Failed to migrate pnpm settings:", err);
 		throw err;
@@ -760,7 +1013,7 @@ 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.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").help();
 cli.command("").action(async (options) => {
 	try {
 		consola.log(`\n${bold(magenta(name))} ${dim(`v${version}`)}`);

package/dist/index.d.mts

@@ -51,6 +51,12 @@ interface Options {
    * @default false
    */
   replaceDeprecated?: boolean;
+  /**
+   * Whether to show a settings diff after migration
+   *
+   * @default true
+   */
+  showChanges?: boolean;
   /**
    * Sort keys when write `pnpm-workspace.yaml`
    *
@@ -227,6 +233,7 @@ type PnpmWorkspace = PnpmSettings & PnpmSettingsDeprecated & PnpmSettingsV11 & P
  * @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
  *

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import consola from "consola";
 import { resolve } from "pathe";
-import { Document, parse } from "yaml";
+import { Document, parse, stringify } from "yaml";
 import process from "node:process";
 import { access, readFile, rm, writeFile } from "node:fs/promises";
 import { getColor } from "consola/utils";
@@ -9,6 +9,7 @@ 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 detectIndent from "detect-indent";
 //#region src/constants.ts
 const NPMRC = ".npmrc";
@@ -153,6 +154,7 @@ const DEFAULT_OPTIONS = {
 	cwd: process.cwd(),
 	newlineBetween: true,
 	replaceDeprecated: false,
+	showChanges: true,
 	sortKeys: false,
 	strategy: "merge",
 	yarnResolutions: true
@@ -205,6 +207,7 @@ function resolveOptions(options = {}) {
 		compatibility: resolveCompatibility(options.compatibility),
 		cwd: options.cwd ?? DEFAULT_OPTIONS.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,
@@ -215,45 +218,67 @@ function resolveOptions(options = {}) {
 //#endregion
 //#region src/utils/fs.ts
 /**
-* Check if a path exists
-* @param path - given path
-* @returns `true` if exists, false otherwise
+* 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");
 }
 getColor("cyan");
 getColor("yellow");
+/**
+* Apply dim terminal styling to a value.
+*/
 const dim = getColor("dim");
-getColor("green");
-getColor("red");
+/**
+* Apply green terminal styling to a value.
+*/
+const green = getColor("green");
+/**
+* Apply red terminal styling to a value.
+*/
+const red = getColor("red");
 getColor("bold");
 getColor("magenta");
 //#endregion
 //#region src/utils/compatibility.ts
+/**
+* Legacy build settings that can be replaced for pnpm v10.
+*/
 const PNPM_REPLACEABLE_IN_V10_SETTINGS = [
 	"allowNonAppliedPatches",
 	"ignoredBuiltDependencies",
@@ -263,6 +288,14 @@ const PNPM_REPLACEABLE_IN_V10_SETTINGS = [
 ];
 /**
 * Read packages listed by the legacy `onlyBuiltDependenciesFile` setting.
+*
+* @param cwd - Working directory used to resolve the referenced file
+* @param file - Relative path stored in `onlyBuiltDependenciesFile`
+*
+* @returns Package names read from the referenced JSON file
+*
+* @throws {TypeError} When the referenced JSON value is not a string array
+* @throws {SyntaxError} When the referenced file contains invalid JSON
 */
 async function readOnlyBuiltDependenciesFile(cwd, file) {
 	if (!file) return [];
@@ -273,6 +306,11 @@ async function readOnlyBuiltDependenciesFile(cwd, file) {
 }
 /**
 * Build an `allowBuilds` map from legacy build-script settings.
+*
+* @param incomingSettings - Settings containing legacy build declarations
+* @param cwd - Working directory used to resolve referenced files
+*
+* @returns Package-to-permission map, or `undefined` when no entries exist
 */
 async function collectAllowBuildsFromLegacy(incomingSettings, cwd) {
 	const allowBuilds = {};
@@ -284,6 +322,10 @@ async function collectAllowBuildsFromLegacy(incomingSettings, cwd) {
 }
 /**
 * 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;
@@ -294,6 +336,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;
@@ -305,6 +352,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;
@@ -314,6 +366,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;
@@ -349,8 +406,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 };
@@ -369,6 +433,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;
@@ -376,10 +446,22 @@ 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 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;
@@ -465,6 +547,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",
@@ -481,15 +566,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();
@@ -501,6 +597,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,6 +616,8 @@ function isNpmrcAuthOrRegistryKey(key) {
 * 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
 *
@@ -542,30 +644,18 @@ 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);
@@ -593,11 +683,136 @@ async function readMigratableNpmrc(path, compatibility) {
 	};
 }
 //#endregion
+//#region src/utils/settings-change.ts
+/**
+* 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 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) {
+	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");
+}
+/**
+* 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));
+}
+/**
+* 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.info(`${changes.length} ${changes.length === 1 ? "setting" : "settings"} changed`);
+	for (const [index, change] of changes.entries()) {
+		if (index > 0) consola.log("");
+		for (const line of createSettingsDiffLines(change)) if (line.kind === "added") consola.log(green(`+ ${line.value}`));
+		else if (line.kind === "removed") consola.log(red(`- ${line.value}`));
+		else consola.log(dim(`  ${line.value}`));
+	}
+}
+//#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,
@@ -609,6 +824,16 @@ 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 {
 		indent: 2,
@@ -620,6 +845,17 @@ async function readPnpmWorkspace(path, exists) {
 		value: parse(content) ?? {}
 	};
 }
+/**
+* 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,
@@ -644,6 +880,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`.
 *
@@ -661,6 +901,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
 *
@@ -690,8 +931,12 @@ 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: [],
@@ -724,6 +969,7 @@ async function migratePnpmSettings(rawOptions = {}) {
 			yarnResolutions: options.yarnResolutions
 		})) {
 			consola.warn("No pnpm settings fields to migrate");
+			reportMigrationChanges(options.showChanges);
 			return;
 		}
 		const pnpmWorkspaceResult = mergeByStrategy(pnpmWorkspace.value, incomingSettings, options.strategy);
@@ -747,6 +993,7 @@ async function migratePnpmSettings(rawOptions = {}) {
 			}
 		}
 		if (packageJsonExists && packageJsonChanged) await fsWriteFile(packageJsonPath, JSON.stringify(packageJson.value, null, packageJson.indent));
+		reportMigrationChanges(options.showChanges, pnpmWorkspaceBefore, pnpmWorkspaceResult);
 	} catch (err) {
 		consola.error("Failed to migrate pnpm settings:", err);
 		throw err;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pnpm-settings-migrator",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Move pnpm settings from `pnpm` field in `package.json` and `.npmrc` file to `pnpm-workspace.yaml`",
   "keywords": [
     "migrator",
@@ -52,13 +52,13 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.3.0",
     "bumpp": "^12.2.1",
     "husky": "^9.1.7",
     "nano-staged": "^1.0.2",
     "npm-run-all2": "^9.0.3",
-    "oxfmt": "^0.64.0",
-    "oxlint": "^1.79.0",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11"