[rush] Upgrade pnpm-sync-lib to v0.3.3 for pnpm v10 compatibility

[gavinxgu]

tiktok/pnpm-sync#40
tiktok/pnpm-sync#43

Summary

Upgrade pnpm-sync-lib to v0.3.3 for pnpm v10 compatibility

Details

1. Upgrade pnpm-sync-lib to Version 0.3.3

Updated package.json to upgrade pnpm-sync-lib from the previous version to 0.3.3, ensuring full compatibility with pnpm v10. This change builds upon the foundation established in tiktok/pnpm-sync#40 (pnpm v9 support) and tiktok/pnpm-sync#43 (pnpm v10 support).

2. Adopt Official pnpm readWantedLockfile Methods

Integrated official pnpm methods in BaseInstallManager.ts to support both v6 and v9 lockfile formats:

// Via rush-pnpm-kit-v8 and rush-pnpm-kit-v9 packages
const lockfileV9: ILockfile | null = await pnpmKitV9.lockfileFs.readWantedLockfile(
  pnpmLockFolder,
  options
);

const lockfileV6: ILockfile | null = await pnpmKitV8.lockfileFs.readWantedLockfile(
  pnpmLockFolder,
  options
);

This implementation provides backward compatibility while supporting the latest pnpm lockfile formats, with automatic detection based on lockfile version.

3. Enhanced Multi-Version pnpm Support

During the upgrade to pnpm v10, packages like @pnpm/lockfile-file and @pnpm/lockfile.fs have peer dependency requirements for @pnpm/logger, but these dependencies were not being properly satisfied, causing warnings or errors during installation.

Solution Implementation

The solution leverages the pnpm-kit architecture - a set of version-specific wrapper packages that encapsulate pnpm functionality for different pnpm versions. As part of this upgrade, three new rush-pnpm-kit packages were added (@rushstack/rush-pnpm-kit-v8, @rushstack/rush-pnpm-kit-v9, and @rushstack/rush-pnpm-kit-v10) to provide comprehensive support across pnpm versions. This modular approach allows Rush to support multiple pnpm versions simultaneously while ensuring proper dependency resolution.

1. Adding @pnpm/logger as Direct Dependencies

@pnpm/logger has been added as a direct dependency in each pnpm-kit package:

libraries/rush-pnpm-kit-v8/package.json

{
  "dependencies": {
    "@pnpm/dependency-path-pnpm-v8": "npm:@pnpm/dependency-path@~2.1.8",
    "@pnpm/lockfile-file-pnpm-lock-v6": "npm:@pnpm/lockfile-file@~8.1.8",
    "@pnpm/logger": "~5.0.0"
  }
}

libraries/rush-pnpm-kit-v9/package.json

{
  "dependencies": {
    "@pnpm/dependency-path-pnpm-v9": "npm:@pnpm/dependency-path@~5.1.7",
    "@pnpm/lockfile.fs-pnpm-lock-v9": "npm:@pnpm/lockfile.fs@~1001.1.11",
    "@pnpm/logger": "~1001.0.0"
  }
}

libraries/rush-pnpm-kit-v10/package.json

{
  "dependencies": {
    "@pnpm/dependency-path-pnpm-v10": "npm:@pnpm/dependency-path@~1000.0.9",
    "@pnpm/lockfile.fs-pnpm-lock-v9": "npm:@pnpm/lockfile.fs@~1001.1.11",
    "@pnpm/logger": "~1001.0.0"
  }
}

2. Modular Encapsulation and Export

Each package exports similar modules with version-appropriate implementations:

export * as lockfileFs from './lockfileFs';
export * as logger from './logger';

3. Usage in Other Packages

In libraries/rush-lib/src/logic/base/BaseInstallManager.ts, different kit versions are imported to handle different lockfile formats:

import * as pnpmKitV8 from '@rushstack/rush-pnpm-kit-v8';
import * as pnpmKitV9 from '@rushstack/rush-pnpm-kit-v9';

// Used in pnpmSyncPrepareAsync call
readPnpmLockfile: async (lockfilePath: string, options) => {
  const pnpmLockFolder: string = path.dirname(lockfilePath);

  // First attempt to read v9 format lockfile
  const lockfileV9: ILockfile | null = await pnpmKitV9.lockfileFs.readWantedLockfile(
    pnpmLockFolder,
    options
  );

  if (lockfileV9?.lockfileVersion.toString().startsWith('9')) {
    return lockfileV9;
  }

  // If not v9 format, attempt to read v6 format
  const lockfileV6: ILockfile | null = await pnpmKitV8.lockfileFs.readWantedLockfile(
    pnpmLockFolder,
    options
  );

  if (lockfileV6?.lockfileVersion.toString().startsWith('6')) {
    return lockfileV6;
  }

  return undefined;
}

How it was tested

Impacted documentation

[gavinxgu]

@iclanton Could you please review my code? Thank you!

[octogonz]

@gavinxgu unlike the above rules, this new rule seems to affect the dependency graph of the published Rush package. That would mean that the dependency versions being tested by our CI will be different from somebody who does npm install -g @microsoft/rush, right? If so, is there a way to avoid this problem? (e.g. rush update --full)

[gavinxgu]

@octogonz I've got an idea - similar to how Heft storybook kit does it, we can organize pnpm's internal packages by version into separate packages like rush-pnpm-kit-v8, rush-pnpm-kit-v9, and rush-pnpm-kit-v10. Then when we need to use different version-specific methods, we just import from the corresponding lib. This way we can avoid those unmet peerDeps issues.

[gavinxgu]

@octogonz I've updated the implementation by introducing the concept of pnpm-kit to avoid unmet peer dependencies, and I've also cleaned up and refactored how the Rush repository references pnpm npm packages.