pnpm-settings-migrator 0.9.0 → 0.11.0

package/README.md

@@ -19,7 +19,8 @@ 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
+✔ 2 settings changed
+
   packages:
     - packages/*
 +   - apps/*
@@ -29,6 +30,40 @@ GitHub-style YAML diff. Removed lines are red and added lines are green:
 +   bar: 2.0.0
 ```
 
+When nothing needs updating, the only output is:
+
+```text
+ℹ No changes needed.
+```
+
+The CLI no longer prints a startup banner, missing optional files, a zero-change
+count, or a duplicate completion message. Use `--version` to see the version.
+Warnings are reserved for settings requiring attention. Information blocks have
+one blank line between them, with no extra blank lines at the start or end.
+
+Other outcomes are reported according to the files actually changed:
+
+- No configuration files: `ℹ No configuration files found.`
+- Source cleanup with no settings diff: `✔ Migration completed. Source settings cleaned up.`
+- Runtime migration with no settings diff: `✔ Migration completed. Node.js runtime updated in package.json.`
+- File formatting changes with no settings diff: `✔ Migration completed. Configuration files updated.`
+- Failure: one error report and exit code `1`.
+
+## Library usage
+
+```ts
+import { migratePnpmSettings } from 'pnpm-settings-migrator'
+
+const result = await migratePnpmSettings({ cwd: '/path/to/workspace' })
+```
+
+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`,
+`packageJsonRuntimeChanged`, `hasConfigurationFiles`, and `warnings`. Errors are
+thrown to the caller. Consumers that relied on console output should render the
+returned changes and warnings themselves.
+
 ## CLI Options
 
 ### `--cwd`
@@ -50,19 +85,52 @@ Sort keys when write `pnpm-workspace.yaml`.
 - **Type**: `'auto' | 'v10' | 'v11' | 'v12'`
 - **Default**: `'auto'`
 
-Compatibility target for migrated settings:
+Compatibility major for migrated settings:
+
+- `auto`: infer from `targetVersion`, `packageManager`, or
+  `devEngines.packageManager` (`pnpm@12+` => `v12`, `pnpm@11` => `v11`,
+  otherwise `v10`).
+- `v10`: keep legacy settings and migrate schema-aligned pnpm config keys from `.npmrc`.
+- `v11`: normalize to v11-compatible settings (`allowBuilds`, `allowUnusedPatches`, etc.).
+- `v12`: use the v12 schema, including `globalShims`, and enable additional
+  fields according to the confirmed target version.
 
-- `auto`: infer from `packageManager` or `devEngines.packageManager`
-  (`pnpm@12+` => `v12`, `pnpm@11` => `v11`, otherwise `v10`)
-- `v10`: keep legacy settings as-is and migrate schema-aligned pnpm config keys from `.npmrc`
-- `v11`: normalize to v11-compatible settings (`allowBuilds`, `allowUnusedPatches`, etc.)
-  and migrate recognized project settings from `.npmrc` to `pnpm-workspace.yaml`
-- `v12`: use the shared v11 schema plus the v12 delta, including
-  `globalShims`, while rejecting v11-only workspace settings.
+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
+the selected major; use `--target-version` to state the intended release.
 
 In `v11` and `v12` modes, the migrator validates existing workspace keys,
-filters incoming settings against the selected schema, and applies required
-normalization to legacy files and `pnpm-workspace.yaml`.
+filters incoming settings against the resolved capabilities, and applies
+required normalization to legacy files and `pnpm-workspace.yaml`.
+
+### `--target-version`
+
+- **Type**: `string` (an exact version such as `'12.4.0'`)
+- **Default**: inferred from the project when possible
+
+Override the target pnpm version without changing the project's package manager
+pin. Resolution order is explicit `targetVersion`, then `packageManager`, then
+`devEngines.packageManager`. An explicit `compatibility` major must agree with
+`targetVersion`; conflicts fail before any files are written.
+
+```ts
+await migratePnpmSettings() // Infer the target from the project
+await migratePnpmSettings({ compatibility: 'v12' }) // Infer a matching minor
+await migratePnpmSettings({ targetVersion: '12.4.0' }) // Target this exact release
+```
+
+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.
+
+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
+`cargoTargetDir`. On older or unconfirmed targets, a `tasks` object containing
+these fields stays in its source as a whole.
 
 Automated v10 to v11 conversions include:
 
@@ -81,20 +149,41 @@ Automated v10 to v11 conversions include:
 Notes:
 
 - `.npmrc` migration is aligned with the target pnpm workspace schema. Unknown
-  keys and settings supported only by a different pnpm major stay in `.npmrc`
+  keys and settings supported only by a different pnpm version stay in `.npmrc`
   with a warning.
 - In `v11` and `v12`, auth/registry keys and project-refused machine settings
   such as `globalDir`, `stateDir`, `configDir`, and `scope` stay in `.npmrc`.
 - Registry declarations containing embedded credentials or dynamic `${...}`
   URLs stay in their source with a warning.
-- In v11 workspaces, supported subproject `.npmrc` fields are moved to
-  `packageConfigs` by package name. pnpm v11 accepts `hoist`, `modulesDir`,
-  `overrides`, `saveExact`, and `savePrefix` there. pnpm v12 does not support
-  `packageConfigs`, so subproject settings are retained with a warning.
+- 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
+  environment variables. Existing dynamic proxy settings in YAML block migration.
+  The migrator never expands and writes these values.
+- pnpm v11 and confirmed stable v12 targets from 12.4.0 accept `packageConfigs`
+  as package-name maps or matcher arrays, with `hoist`, `modulesDir`,
+  `overrides`, `saveExact`, and `savePrefix`. Supported subproject `.npmrc`
+  fields are moved there by package name. pnpm 12.0–12.3 does not support
+  `packageConfigs`.
+- For v12 targets from 12.4.0, migrating `packageConfigs` or subproject settings
+  requires `sharedWorkspaceLockfile: false` in the merged workspace. Otherwise
+  source settings remain with a warning; existing `packageConfigs` blocks
+  migration until the effective lockfile mode is compatible. This restriction
+  does not apply to v11. The migrator does not change this mode automatically.
 - Cleanup removes only source keys represented in the final workspace after
   applying the selected merge strategy.
+  Each source is checked against its own values, including deprecated-key
+  replacements. Conflicting values in `.npmrc`, `package.json#pnpm`, or Yarn
+  resolutions remain in their original source.
   Unrecognized, refused, incompatible, or otherwise unsupported
   `package.json#pnpm` child keys remain in `package.json`.
+- Runtime migration writes `devEngines.runtime` before removing a workspace
+  runtime declaration. A failed write preserves source settings for retry.
+  If an existing runtime declaration conflicts with a workspace runtime, migration
+  stops before writing any files. An identical Node.js declaration is reused.
+- YAML aliases remain when their anchors are unchanged and precede them.
+  If replacement, removal, or sorting would invalidate an alias, its original
+  value is written explicitly so unrelated settings keep their values.
 - If no auth/registry lines remain after a v11 or v12 migration, the empty
   `.npmrc` is removed.
 - Values moved from `auditConfig.ignoreCves` still contain CVE IDs. Replace them
@@ -102,11 +191,30 @@ 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.
-- pnpm 12 is stable; this project verifies migrated output against pnpm 12.2.1
-  as well as pnpm 11.25.0. Its removed `pnpm install --resolution-only` CLI
+- Compatibility checks cover pnpm 11.26.0, 12.3.4, and 12.4.0, retaining
+  11.25.0 and 12.2.1 regressions. As audited on 2026-09-10, 12.3.4 is npm
+  `latest` and 12.4.0 is on `next-12`; the project stays pinned to 12.3.4. 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.
 
+For example, `--target-version 12.4.0` migrates this legacy configuration:
+
+```json
+{ "pnpm": { "pipelines": { "ci": ["build", "test"] }, "pipelineBase": "main" } }
+```
+
+into `pnpm-workspace.yaml` and removes the applied `pnpm` keys:
+
+```yaml
+pipelines:
+  ci: [build, test]
+pipelineBase: main
+```
+
+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.
+
 ### `--replace-deprecated`
 
 - **Type**: `boolean`
@@ -144,13 +252,29 @@ Strategy to handle conflicts when merging settings with existing `pnpm-workspace
 
 Disable migrating `resolutions` field in `package.json`.
 
+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
+`parent/**/child` remain in `resolutions` with a warning. Conflicting selectors
+that translate to the same pnpm key also remain for manual resolution.
+Only individual resolutions whose values reach the final workspace are removed.
+
+For example, an unsupported selector is now reported and retained instead of
+being copied into an override that prevents pnpm from installing:
+
+```text
+WARN Kept Yarn resolution "parent/**/child" in package.json: its selector cannot be translated safely to pnpm overrides.
+
+ℹ No changes needed.
+```
+
 ### `--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`.
+Hide the settings diff while keeping the outcome summary and warnings. This is a
+CLI display preference; library results always include settings changes.
 
 ### `--no-clean-npmrc`