[Bharat Middha (bmiddha)]

Summary

rush add and rush upgrade-interactive ignored PNPM catalogs. rush add wrote literal versions for cataloged packages and rejected foo@catalog:, and both commands replaced a project's existing catalog: references with versions.

Now rush add writes a catalog reference when a catalog entry matches, like pnpm's catalogMode: prefer, and it accepts explicit catalog: specifiers. When a cataloged dependency changes, both commands update the catalog entry in pnpm-config.json, like pnpm update.

Details

• Catalogs come from the subspace's pnpm-config.json, falling back to common/config/rush/pnpm-config.json. pnpm-config.json doesn't vary by --variant, so --variant still selects only common-versions.json.
• When several catalogs have the package, Rush prefers one the target projects already reference it through, then one other projects use, then default. If the choice is still ambiguous, Rush writes a version as before and prints a note.
• If a requested range differs from the catalog entry, Rush writes it as a version and prints a note. With --make-consistent, Rush updates the catalog entry instead. Other projects' catalog references are then kept in sync through the entry, instead of being skipped with a warning.
• Rush never replaces an existing catalog reference with a version. Without --make-consistent, a different version is an error.
• npm-check skips non-SemVer specifiers, so upgrade-interactive resolves catalog references before checking. That needed @rushstack/npm-check-fork to honor cwdPackageJson. The ensureConsistentVersions check uses the versions after the catalog change, because the change affects every consumer of the entry.
• Rush only adds or updates catalog entries, never removes them. If the edited pnpm-config.json is shared with subspaces the command doesn't update, Rush prints the rush update --subspace <name> commands needed to keep their lockfiles in sync.
• Repos without catalogs, and npm and yarn repos, behave as before.

How it was tested

• New unit tests: PackageJsonUpdater.test.ts covers the rush add and upgrade-interactive cases using the catalog test repos, AddAction.test.ts covers parsing catalog: specifiers, and NpmCheckState.test.ts covers cwdPackageJson.
• Ran locally: rush build --production --to @microsoft/rush with no warnings, heft test --production in rush-lib and npm-check-fork, and rush change --verify. A few unrelated rush-lib suites time out on my machine; they pass in CI.

Impacted documentation

• https://rushjs.io/pages/commands/rush_add/
• https://rushjs.io/pages/commands/rush_upgrade-interactive/