pnpm-settings-migrator 0.12.0 → 0.14.0

package/README.md

@@ -15,6 +15,9 @@ Run in your workspace root:
 pnpm dlx pnpm-settings-migrator
 ```
 
+<details>
+<summary>CLI output and migration outcomes</summary>
+
 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:
 
@@ -49,6 +52,8 @@ Other outcomes are reported according to the files actually changed:
 - File formatting changes with no settings diff: `✔ Migration completed. Configuration files updated.`
 - Failure: one error report and exit code `1`.
 
+</details>
+
 ## Library usage
 
 ```ts
@@ -57,6 +62,9 @@ import { migratePnpmSettings } from 'pnpm-settings-migrator'
 const result = await migratePnpmSettings({ cwd: '/path/to/workspace' })
 ```
 
+<details>
+<summary>Library results and error handling</summary>
+
 Library calls now return a `MigrationResult` and do not print logs. The result
 contains `settingsChanges` (before/after root workspace settings), `changedFiles`
 (absolute paths, including created or removed files), `sourceSettingsCleaned`,
@@ -64,6 +72,8 @@ contains `settingsChanges` (before/after root workspace settings), `changedFiles
 thrown to the caller. Consumers that relied on console output should render the
 returned changes and warnings themselves.
 
+</details>
+
 ## CLI Options
 
 ### `--cwd`
@@ -95,6 +105,9 @@ Compatibility major for migrated settings:
 - `v12`: use the v12 schema, including `globalShims`, and enable additional
   fields according to the confirmed target version.
 
+<details>
+<summary>Compatibility resolution and validation</summary>
+
 An explicit major still uses a matching version from the project declarations.
 For example, `--compatibility v12` with `packageManager: "pnpm@12.4.0"` enables
 12.4 capabilities. A pin to another major supplies no minor capabilities for
@@ -104,6 +117,8 @@ In `v11` and `v12` modes, the migrator validates existing workspace keys,
 filters incoming settings against the resolved capabilities, and applies
 required normalization to legacy files and `pnpm-workspace.yaml`.
 
+</details>
+
 ### `--target-version`
 
 - **Type**: `string` (an exact version such as `'12.4.0'`)
@@ -120,12 +135,20 @@ await migratePnpmSettings({ compatibility: 'v12' }) // Infer a matching minor
 await migratePnpmSettings({ targetVersion: '12.4.0' }) // Target this exact release
 ```
 
+<details>
+<summary>Version inference and supported version formats</summary>
+
 Version ranges are not accepted by `targetVersion`. Project ranges, conflicting
 `devEngines` entries, prereleases, and declarations without a confirmed matching
 version retain the base major schema. Build metadata on exact stable versions
 is accepted. Later stable minors automatically inherit known capabilities;
 there are no minor-specific compatibility options.
 
+</details>
+
+<details>
+<summary>Version-specific settings and requirements</summary>
+
 For pnpm 12.4.0 and later stable v12 releases, the migrator additionally accepts
 `trustPolicyExcludePrune`, `python`, `cargo`, `pipelines`, `pipelineBase`, and
 `packageConfigs`, plus task fields `outputs`, `inputs`, `env`, `cache`, and
@@ -150,6 +173,32 @@ never migrated into the project workspace.
 On the v11 line, `trustPolicyExcludePrune` requires a confirmed stable version
 from 11.27.0 onward; v12 support still starts at 12.4.0.
 
+For pnpm 12.6.0 and later stable v12 releases, the migrator accepts `autoDedupe`,
+`saveTypes`, `tagVersionPrefix`, and signed 32-bit `tasks.*.priority` values.
+`progress` and `loglevel` also require 12.6.0 for v12 targets, when pnpm first
+consumes them from workspace configuration; their v11 support is unchanged.
+Invalid values and fields unsupported by the target remain in their sources.
+The global-only `macosBackup` setting is preserved with a project-refused warning.
+
+`forceIgnoresPlatform` requires pnpm 11.28.0+ or 12.7.0+. pnpm's defaults differ
+between those majors; the migrator only moves explicit values. For v12,
+`publishWaitTimeout` and `reporter` require 12.7.0+. The timeout is a nonnegative
+safe integer in milliseconds (zero disables waiting); numeric `.npmrc` values
+are converted to YAML numbers. Reporter values are `default`, `append-only`,
+`ndjson`, and `silent`, or preserved environment placeholders.
+
+From 11.28.0 / 12.7.0, dynamic `userAgent` values remain in their sources because
+pnpm ignores project values containing environment placeholders. From 11.28.1,
+invalid `patchedDependencies` maps and non-array `packages` values are retained
+with diagnostics. From 12.8.2, `globalShims` belongs in trusted global
+configuration and is retained with an incompatibility warning. Existing
+workspaces containing these incompatible values fail validation before writes.
+
+</details>
+
+<details>
+<summary>Automated v10 to v11 conversions</summary>
+
 Automated v10 to v11 conversions include:
 
 - `managePackageManagerVersions`, `packageManagerStrict`, and
@@ -164,6 +213,11 @@ Automated v10 to v11 conversions include:
 - removal of `ignoreDepScripts` and `ignorePatchFailures`, which have no v11
   equivalent
 
+</details>
+
+<details>
+<summary>Migration rules, limitations, and compatibility coverage</summary>
+
 Notes:
 
 - `.npmrc` migration is aligned with the target pnpm workspace schema. Unknown
@@ -214,12 +268,21 @@ Notes:
 - The migrator does not update the `packageManager` version, CI environment variables,
   shell setup, or pnpm commands in scripts. When `packageManager` still pins pnpm 10,
   pass `--compatibility v11` explicitly and update the pin separately.
-- Compatibility checks cover pnpm 11.27.1 and 12.5.1, retaining 11.25.0,
-  11.26.0, 12.2.1, 12.3.4, 12.4.0, 12.4.2, and 12.5.0 regressions.
-  As audited on 2026-09-22, npm `latest` is 12.5.1 and `latest-11` is 11.27.1;
-  the project is pinned to 12.5.1. Its removed `pnpm install --resolution-only` CLI
-  flag is outside this settings migrator's scope; replace it with
-  `pnpm peers check` in scripts before upgrading.
+- Compatibility checks cover pnpm 11.28.2 and 12.8.2, including 11.28.0,
+  11.28.1, 12.7.0, 12.8.0, and 12.8.1. Earlier regressions remain at 11.25.0,
+  11.26.0, 11.27.1, 12.2.1, 12.3.4, 12.4.0, 12.4.2, 12.5.0, 12.5.1, and 12.6.0.
+  As [audited on 2026-09-30](docs/research/pnpm-settings-bump-2026-09-30.md),
+  npm `latest` is 12.8.1; the highest confirmed stable release is 12.8.2 on
+  `next-12`. The project is pinned to 12.8.1. These checks verify the documented
+  fixtures, not every setting in every release. v10 has unit regressions and
+  source review through 10.34.6; real v10 consumption remains unverified.
+  The removed `pnpm install --resolution-only` CLI flag is outside this settings
+  migrator's scope; replace it with `pnpm peers check` in scripts before upgrading.
+
+</details>
+
+<details>
+<summary>Target version migration example</summary>
 
 For example, `--target-version 12.4.0` migrates this legacy configuration:
 
@@ -239,6 +302,8 @@ With `--target-version 12.3.4`, these settings remain in `package.json` with an
 incompatibility warning. See the [version audit](docs/research/pnpm-recent-settings-audit-2026-09-10.md)
 for the upstream release and schema references.
 
+</details>
+
 ### `--replace-deprecated`
 
 - **Type**: `boolean`
@@ -246,6 +311,9 @@ for the upstream release and schema references.
 
 Force replacing deprecated pnpm settings with new keys and remove old keys during migration.
 
+<details>
+<summary>Deprecated setting conversion examples</summary>
+
 Example conversions:
 
 - `allowNonAppliedPatches` -> `allowUnusedPatches`
@@ -258,6 +326,8 @@ Example conversions:
   `sideEffectsCache`
 - non-conflicting `namedRegistries` aliases -> URL-keyed `registries`
 
+</details>
+
 ### `--strategy`
 
 - **Type**: `'discard' | 'merge' | 'overwrite'`
@@ -269,6 +339,10 @@ Strategy to handle conflicts when merging settings with existing `pnpm-workspace
 - `merge`: Deep merge with array deduplication. Arrays are combined and deduplicated, objects are recursively merged, primitives keep existing values.
 - `overwrite`: Use incoming values, only keep existing keys not present in incoming settings. For nested objects, merges keys from both.
 
+`packageConfigs` matcher arrays preserve order and repeated entries because the
+last matching entry wins. With `merge`, incoming matchers follow existing ones;
+an overlapping end/start sequence is reused to keep repeated migrations stable.
+
 ### `--no-yarn-resolutions`
 
 - **Type**: `boolean`
@@ -276,6 +350,9 @@ Strategy to handle conflicts when merging settings with existing `pnpm-workspace
 
 Disable migrating `resolutions` field in `package.json`.
 
+<details>
+<summary>Yarn selector translation and warnings</summary>
+
 By default, plain package names are copied to pnpm overrides and global Yarn
 selectors are translated: `**/foo` becomes `foo`, and `**/@scope/foo` becomes
 `@scope/foo`. Path-specific selectors such as `parent/child` and
@@ -292,6 +369,8 @@ WARN Kept Yarn resolution "parent/**/child" in package.json: its selector cannot
 ℹ No changes needed.
 ```
 
+</details>
+
 ### `--no-show-changes`
 
 - **Type**: `boolean`
@@ -325,6 +404,9 @@ Disable adding newlines between each root keys.
 
 This document demonstrates how different merge strategies work when migrating pnpm settings.
 
+<details>
+<summary>Compare merge strategies with configuration examples</summary>
+
 ### Scenario
 
 Existing `pnpm-workspace.yaml`:
@@ -459,6 +541,8 @@ peerDependencyRules:
     - vue-router # Arrays merged and deduplicated
 ```
 
+</details>
+
 ## Context
 
 - [Moving settings to pnpm-workspace.yaml](https://github.com/orgs/pnpm/discussions/9037)