Enhances 'spfx project upgrade' with overrides

[milanholemans]

Closes #7208

[Copilot]

Pull request overview

Enhances the SPFx project upgrade experience by introducing package override handling via package-manager CLIs, so recommended install steps don’t fail due to missing package.json overrides.

Changes:

• Added support for parsing and aggregating override / removeOverride package-manager commands (npm/pnpm) and ordering them before install/uninstall.
• Replaced the previous JSON-based @rushstack/heft override rule with a DependencyRule-based override rule emitting CLI commands.
• Removed yarn as an accepted --packageManager for spfx project upgrade and updated docs/tests accordingly.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/utils/packageManager.ts	Adds override/removeOverride command support and ordering in command reduction.
src/m365/spfx/commands/project/project-upgrade/upgrade-1.23.0-rc.0.ts	Switches to the new override rule for @rushstack/heft.
src/m365/spfx/commands/project/project-upgrade/upgrade-1.22.0.ts	Switches to the new override rule for @rushstack/heft.
src/m365/spfx/commands/project/project-upgrade/rules/FN027001_OVERRIDES_rushstack_heft.ts	Introduces a new rule that models the override via DependencyRule.
src/m365/spfx/commands/project/project-upgrade/rules/FN027001_OVERRIDES_rushstack_heft.spec.ts	Adds tests for the new override rule.
src/m365/spfx/commands/project/project-upgrade/rules/FN021009_PKG_overrides_rushstack_heft.ts	Removes the old JSON-based override rule implementation.
src/m365/spfx/commands/project/project-upgrade/rules/DependencyRule.ts	Extends DependencyRule to support overrides and emit override CLI operations.
src/m365/spfx/commands/project/project-upgrade/rules/DependencyRule.spec.ts	Adds coverage for override dependency behavior in DependencyRule.
src/m365/spfx/commands/project/project-upgrade.ts	Adds override token replacement, adjusts command aggregation, and removes yarn from supported upgrade package managers.
src/m365/spfx/commands/project/project-upgrade.spec.ts	Updates tests for new override behavior and removes yarn-related tests.
src/m365/spfx/commands/project/project-doctor.ts	Updates doctor command aggregation plumbing to accept override buckets.
docs/docs/cmd/spfx/project/project-upgrade.mdx	Updates docs to reflect supported package managers for upgrade.

Comments suppressed due to low confidence (3)

src/m365/spfx/commands/project/project-upgrade.ts:551

• getReportData only routes commands through mapPackageManagerCommand when the resolution contains 'npm'. For --packageManager pnpm, all pnpm install/uninstall/override commands will go to commandsToExecute and then get filtered out of the generated summary script (because the later filter removes package manager commands), so the report can omit required pnpm steps. Consider detecting commands for the selected package manager (npm/pnpm) instead of hardcoding 'npm', or calling mapPackageManagerCommand unconditionally and falling back when no match occurs.

    findings.forEach(f => {
      if (f.resolutionType === 'cmd') {
        if (f.resolution.indexOf('npm') > -1) {
          packageManager.mapPackageManagerCommand({
            command: f.resolution,
            packagesDevExact,
            packagesDepExact,
            packagesDepUn,
            packagesDevUn,
            packagesOverride,
            packagesOverrideRemove,
            packageMgr: this.packageManager
          });
        }
        else {
          commandsToExecute.push(f.resolution);
        }
      }

src/m365/spfx/commands/project/project-upgrade/rules/DependencyRule.ts:66

• When isOverride is true, versionEntry is assumed to be a string and is passed into semver range logic. In npm, overrides[package] can also be an object (nested overrides). In that case #needsUpdate will throw and return false, which would incorrectly suppress a required finding. Consider verifying typeof versionEntry === 'string' (and treating non-string values as needing an update/removal) before calling #needsUpdate.

    const projectDependencies: Hash | undefined = this.isOverride ? project.packageJson.overrides : this.isDevDep ? project.packageJson.devDependencies : project.packageJson.dependencies;
    const versionEntry: string | null = projectDependencies ? projectDependencies[this.packageName] : '';
    if (this.add) {
      let jsonProperty: string = this.isOverride ? 'overrides' : this.isDevDep ? 'devDependencies' : 'dependencies';

      if (versionEntry) {
        jsonProperty += `.${this.packageName}`;

        if (this.#needsUpdate(this.packageVersion, versionEntry)) {
          const node = this.getAstNodeFromFile(project.packageJson, jsonProperty);
          this.addFindingWithPosition(findings, node);
        }
      }

src/m365/spfx/commands/project/project-upgrade/rules/FN027001_OVERRIDES_rushstack_heft.spec.ts:8

• Test suite name is outdated: describe('FN021009_PKG_overrides_rushstack_heft', ...) no longer matches the rule under test (FN027001_OVERRIDES_rushstack_heft). Rename the describe block so the test output and grep-ability reflect the new rule ID/name.

[waldekmastykarz]

PR Review Summary

PR: #7223 - Enhances 'spfx project upgrade' with overrides
Author: @milanholemans

Overview

Great enhancement! The approach of using npm pkg set/npm pkg delete to manage overrides before install/uninstall is solid and directly addresses the ordering problem described in #7208. The refactoring of FN021009 into FN027001 using DependencyRule is a clean simplification. The yarn removal is well-motivated by the comment about yarn's CLI not supporting setting overrides.

A few minor items below.

Findings

1. [Warning] FN027001_OVERRIDES_rushstack_heft.spec.ts (line 5) — The describe block label still references the old rule ID. See inline comment.
2. [Suggestion] upgrade-1.22.0.ts (line 166) — Trailing newline removed at end of file. Consider keeping it for consistency.
3. [Suggestion] FN027001_OVERRIDES_rushstack_heft.ts (line 11) — Missing trailing newline at end of file.
4. [Suggestion] project-upgrade.mdx (line 22) — Minor grammar nit. See inline comment.

Checklist Coverage

Verified: single quotes, async/await, no any types in new code, no commented-out code, class naming convention, logger patterns, test coverage for new override functionality, documentation updated.

---

Reviewed against the PR checklist.