pnpm-settings-migrator 0.18.0 → 0.20.0

package/README.md

@@ -70,7 +70,7 @@ const result = await migratePnpmSettings({ cwd: '/path/to/workspace' })
 <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`
+contains `settingsChanges` (before/after effective workspace settings, including includes), `changedFiles`
 (absolute paths, including created or removed files), `sourceSettingsCleaned`,
 `packageJsonRuntimeChanged`, `hasConfigurationFiles`, and `warnings`. Errors are
 thrown to the caller. Consumers that relied on console output should render the
@@ -92,7 +92,7 @@ Current working directory.
 - **Type**: `boolean`
 - **Default**: `false`
 
-Sort keys when write `pnpm-workspace.yaml`.
+Sort keys in written workspace and local include YAML documents.
 
 ### `--compatibility`
 
@@ -268,6 +268,91 @@ placeholders. On older targets, the complete cache section stays in its source.
 Invalid nested values and unknown fields also preserve the complete source
 section; existing incompatible workspace values block writes.
 
+For pnpm 12.15.0 and later stable v12 releases, `bootConfig` accepts bootstrap
+release-age and trust-policy settings: `minimumReleaseAge`,
+`minimumReleaseAgeExclude`, `minimumReleaseAgeStrict`,
+`minimumReleaseAgeIgnoreMissingTime`, `trustPolicy`, `trustPolicyExclude`, and
+`trustPolicyIgnoreAfter`. The section and individual fields may be null.
+Bootstrap policy stays separate from normal install policy; neither is copied
+into the other. Unknown nested keys or invalid values preserve the entire section.
+
+`maxTarballUnpackedSize` requires 11.28.7+ or 12.15.0+ and accepts a nonnegative
+safe integer in bytes, or null to leave pnpm's default effective. Numeric
+`.npmrc` values become YAML numbers. The migrator does not add pnpm's 4 GiB
+default. From 11.28.7, v11 also accepts `autoInstallPeersFromHighestMatch`
+(boolean or null) and `externalDependencies` (string array or null).
+
+From 12.15.0, `lockfile.integrityTarget` accepts `resource`, `tar`, or null,
+and npm `registries` declarations accept `serverType: pnpr` for tar registries.
+Unsupported nested fields keep the complete lockfile or registry section in its
+source. For example, `lockfile: { integrityTarget: tar }` migrates at 12.15.0
+and remains in the source at 12.14.0.
+
+pnpm 12.15's `include` delegates settings to local YAML files or declared
+config dependencies. The migrator reads the effective workspace and writes
+settings to their physical owners, preserving the include index, YAML comments,
+and unchanged files. Explicit lists reserve settings even when absent;
+`'*'` is allowed only for local files and owns the settings they already define.
+`catalog` / `catalogs.default` refer to the default catalog, `catalogs.name`
+selects one named catalog, and `catalogs` reserves every catalog.
+
+```yaml
+include:
+  ./config/layout.yaml: [modulesDir, packages]
+  ./config/catalogs.yaml: [catalogs.frontend]
+  '@acme/policy': [minimumReleaseAge, trustPolicy]
+configDependencies:
+  '@acme/policy': 1.0.0
+```
+
+A legacy `modulesDir: ./node_modules` value is written as
+`modulesDir: ../node_modules` in `config/layout.yaml`, keeping the same location.
+Path settings, package globs, pnpmfiles, patch paths, and local catalog/override
+specifiers use the owning file's directory. New settings without an owner stay
+in the root. `discard`, `merge`, and `overwrite` apply inside local owners.
+YAML merge keys participate in ownership checks and are expanded when removing
+an inherited legacy key is necessary.
+
+Config dependencies remain read-only. The migrator reads each installed
+package's `pnpm.config` entry under `node_modules/.pnpm-config`. A source value
+already represented by that policy can be cleaned; conflicting values remain
+with diagnostics under every strategy. If a policy package is not installed or
+its installed version differs from the proposed declaration, its delegated
+source values remain until the matching version is installed and migration is
+run again. Legacy workspace settings are also retained when conversion would
+lose their values behind a read-only replacement. The migrator does not install
+packages. Nested includes, overlapping
+owners, undelegated fields, invalid entries, and paths escaping a config
+dependency's package stop migration before writes. Included local files must
+already exist; installed policy files cannot also be writable destinations,
+including through symlinks or hard links. A merge that would define both
+`catalog` and `catalogs.default` stops before writes; consolidate them into one
+form first. All destinations are
+validated and rendered before writing, and legacy sources are retained if any
+destination write fails. Credentials and trusted global settings keep their
+existing protections. Earlier or unconfirmed targets retain incoming include
+indexes with diagnostics and reject existing included workspaces.
+
+From pnpm 12.16.0, `strictSsl` and `runtime` accept booleans or null,
+`localAddress` and `tag` accept strings or null, and `requiredScripts` accepts
+string arrays or null. These settings remain in their sources for earlier or
+unconfirmed v12 targets. `runtime: false` disables installing declared runtimes;
+`tag: next` selects that distribution tag when adding a package without a version.
+Invalid IP address strings stay unchanged because pnpm treats them as unset.
+String placeholders are preserved without expansion. Invalid types keep the
+complete setting in its source. For example, `required-scripts[]=build` becomes
+`requiredScripts: [build]` at 12.16.0 and stays in `.npmrc` at 12.15.0.
+
+From pnpm 11.28.9, v11 registry declarations also accept `serverType: pnpr`.
+Earlier or unconfirmed v11 targets retain the complete registry map. The setting
+does not enable v12-only registry fields such as `networkConcurrency` or `ecosystem`.
+
+pnpm 12.16 no longer consumes `scriptsPrependNodePath`, so the migrator keeps
+incoming values in their sources and rejects existing workspace values before
+writes. Project `ci` values and the global-only `symlinkedLockfileTargetDirs`
+also stay in their sources. Configure the latter in trusted global configuration
+or through `PNPM_CONFIG_SYMLINKED_LOCKFILE_TARGET_DIRS`.
+
 pnpm v12 reads `filter` and `filterProd` from CLI arguments or `updateConfig`
 hooks, not workspace YAML. These settings remain in their source with
 diagnostics for v12 targets; existing YAML containing them blocks migration.
@@ -320,6 +405,24 @@ Notes:
 - Invalid registry locations, including relative paths and object property names
   such as `__proto__`, remain in their sources with diagnostics. Registry
   conversion never uses inherited object properties as declarations.
+- Registry maps are validated as a whole, including declarations without
+  versioned fields. An invalid sibling
+  declaration keeps every registry in its source under all merge strategies;
+  existing incompatible maps block migration before any writes.
+- A URL key must name a declaration object. String values are accepted only in
+  the legacy scope map representation, whose keys cannot look like URLs.
+  Invalid registry settings remain intact in `package.json` and `.npmrc`, while
+  unrelated valid settings can still migrate and be cleaned from their sources.
+- Legacy `<scope>: <url>` routes and URL-keyed declarations cannot be mixed,
+  including when `replaceDeprecated` introduces the mixture. The structure is
+  checked independently of versioned registry fields.
+- Registry prefixes must be unique. A scope may be repeated only when it routes
+  to the same registry after the target pnpm version's URL normalization. From
+  12.11.1, the exact HTTPS and protocol-relative npm `.com` registry roots are
+  equivalent to `.org`; earlier or unconfirmed v12 targets compare them literally.
+  Routing conflicts introduced by merging or deprecated-setting conversion stop
+  migration before any destination writes
+  or source cleanup, including when registries belong to an included YAML file.
 - Dynamic `${...}` values in `httpProxy`, `httpsProxy`, `noProxy`, `proxy`, and
   `noproxy` stay in their source for every target. Project YAML does not expand
   these placeholders; configure them globally in trusted configuration or use
@@ -364,18 +467,29 @@ 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.28.6 and 12.14.0, including 11.28.0,
-  11.28.1, 11.28.2, 11.28.3, 11.28.4, 11.28.5, 12.7.0, 12.8.0, 12.8.1,
-  12.8.2, 12.9.0, 12.9.1, 12.10.0, 12.10.1, 12.11.0, 12.11.1, 12.11.2,
-  12.12.0, 12.12.1, and 12.13.0.
+- Compatibility checks cover pnpm 11.28.9 and 12.16.1, including 11.28.0,
+  11.28.1, 11.28.2, 11.28.3, 11.28.4, 11.28.5, 11.28.6, 12.7.0, 12.8.0,
+  12.8.1, 12.8.2, 12.9.0, 12.9.1, 12.10.0, 12.10.1, 12.11.0, 12.11.1,
+  12.11.2, 12.12.0, 12.12.1, 12.13.0, 12.14.0, 11.28.7, 11.28.8,
+  12.15.0, and 12.16.0.
   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-10-17](docs/research/pnpm-settings-bump-2026-10-17.md),
-  npm `latest` and the highest confirmed stable release are 12.14.0, also on
-  `latest-12` and `next-12`. The v11 target is 11.28.6 on both `latest-11` and
-  `next-11`. The project is pinned to 12.14.0. These checks verify the documented
-  fixtures, not every setting in every release. v10 has unit regressions and
-  source review through 10.34.7; real v10 consumption remains unverified.
+  As [audited on 2026-10-29](docs/research/pnpm-settings-bump-2026-10-29.md),
+  npm `latest` and the highest confirmed stable release are 12.16.1, also on
+  `latest-12` and `next-12`. The highest stable v11 release, 11.28.9, is on
+  `latest-11` and `next-11`. GitHub marks both targets as non-prereleases.
+  The project is pinned to 12.16.1. These checks verify the
+  documented fixtures, not every setting in every release. Local and config
+  dependency `include` consumption is verified on 12.15.0, with 12.14.0 as the
+  preceding boundary. v10 has unit regressions and source review
+  through 10.34.9; real v10 consumption remains unverified. The 12.16 fixtures
+  verify TLS certificate handling against a temporary HTTPS registry, dist-tag
+  selection, runtime suppression, required script enforcement, and frozen
+  installs. They use OpenSSL to create a disposable certificate.
+  Routing fixtures at 11.28.8, 11.28.9, 12.9.0, 12.10.0, 12.11.0, 12.11.1,
+  12.11.2, 12.15.0, and 12.16.1 verify prefix/scope conflicts, mixed registry
+  representations after conversion, and rejection before writes under all three
+  strategies. They compare native URL normalization across the 12.11.1 boundary.
   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.