pnpm-settings-migrator 0.8.1 → 0.10.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`
@@ -56,13 +91,13 @@ Compatibility target for migrated settings:
   (`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 all non auth/registry `.npmrc` entries to `pnpm-workspace.yaml`
-- `v12`: use the same settings-key migration as `v11`. Lockfile migration and
-  validation are outside this tool's scope.
+  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.
 
-In `v11` and `v12` modes, normalization is applied both to settings read from
-legacy files and to deprecated settings already present in
-`pnpm-workspace.yaml`.
+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`.
 
 Automated v10 to v11 conversions include:
 
@@ -80,12 +115,21 @@ Automated v10 to v11 conversions include:
 
 Notes:
 
-- `.npmrc` migration is aligned with pnpm workspace config fields such as `node-linker`,
-  hoist settings, lockfile settings, store settings, proxy settings, and other pnpm
-  runtime/install options.
-- Workspace manifest-only fields such as `packages`, `catalog`, and `catalogs` are not
-  migrated from `.npmrc`.
-- In `v11` and `v12`, auth/registry-related keys still stay in `.npmrc`.
+- `.npmrc` migration is aligned with the target pnpm workspace schema. Unknown
+  keys and settings supported only by a different pnpm major 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.
+- Cleanup removes only source keys represented in the final workspace after
+  applying the selected merge strategy.
+  Unrecognized, refused, incompatible, or otherwise unsupported
+  `package.json#pnpm` child keys remain in `package.json`.
 - 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
@@ -93,9 +137,10 @@ 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 currently a release candidate. 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.
+- 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
+  flag is outside this settings migrator's scope; replace it with
+  `pnpm peers check` in scripts before upgrading.
 
 ### `--replace-deprecated`
 
@@ -108,6 +153,13 @@ Example conversions:
 
 - `allowNonAppliedPatches` -> `allowUnusedPatches`
 - `onlyBuiltDependencies` / `ignoredBuiltDependencies` / `neverBuiltDependencies` -> `allowBuilds`
+- `auditLevel` / `auditConfig` -> `audit`
+- `updateConfig` -> `update`
+- `cleanupUnusedCatalogs` -> `catalogPrune`
+- `enableGlobalVirtualStore` -> `virtualStoreType`
+- `sideEffectsCacheReadonly` / `remoteSideEffectsCache` -> structured
+  `sideEffectsCache`
+- non-conflicting `namedRegistries` aliases -> URL-keyed `registries`
 
 ### `--strategy`
 
@@ -132,8 +184,8 @@ Disable migrating `resolutions` field in `package.json`.
 - **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`
 
@@ -147,7 +199,7 @@ Disable removing pnpm settings in `.npmrc` file.
 - **Type**: `boolean`
 - **Default behavior**: `cleanPackageJson=true` (use this flag to disable)
 
-Disable removing `pnpm` field in `package.json`.
+Disable removing migrated child keys from the `pnpm` field in `package.json`.
 
 ### `--no-newline-between`