5123 followups (#5182)

* Make LinkType a string union.

* Remove RushConnectError.

* Remove the 'path' dependency.

* fixup! Remove the 'path' dependency.

* Asyncify BaseLinkManager._createSymlinkAsync.

* Replace FileSystem.createSymbolicLinkFolderAsync with BaseLinkManager._createSymlinkAsync, which handles quirks between Windows and non-Windows.

* Clean up some logic around paths existing.

* Plumb terminal around from parser.

* Stop constructing a new terminal in RushConnnect.

* Rename IRushLinkFileState to IRushLinkFileStateJson.

* Clean up the RushConnect API some more.

* Future-proof a FileSystem reference.

* Limit concurrency in a few places.

* fixup! Limit concurrency in a few places.

* Clean up a few variable names.

* Clean up BaseSymlinkPackageAction.

* Refactor of the links file.

* fixup! Replace FileSystem.createSymbolicLinkFolderAsync with BaseLinkManager._createSymlinkAsync, which handles quirks between Windows and non-Windows.

* fixup! Refactor of the links file.

* fixup! Clean up the RushConnect API some more.

* fixup! Clean up the RushConnect API some more.

* Some wordsmithing of link- and bridge-package commands.

* fixup! Refactor of the links file.

* More wordsmithing.

* fixup! Some wordsmithing of link- and bridge-package commands.

* Rush change.

* Update libraries/rush-lib/src/api/test/__snapshots__/RushCommandLine.test.ts.snap

* Update libraries/rush-lib/src/cli/actions/BridgePackageAction.ts

* Rename RushConnect --> HotlinkManager
Rename BaseSymlinkPackageAction --> BaseHotlinkPackageAction

* Update docs to use hotlink terminology

* Rename rush-project-link-state.json --> rush-hotlink-state.json

* Update snapshots

---------

Co-authored-by: Ian Clanton-Thuon <iclanton@users.noreply.github.com>
Co-authored-by: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>

Author: 3 people

common/changes/@microsoft/rush/5123-followups_2025-04-03-02-23.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "",
+      "type": "none",
+      "packageName": "@microsoft/rush"
+    }
+  ],
+  "packageName": "@microsoft/rush",
+  "email": "iclanton@users.noreply.github.com"
+}

common/reviews/api/rush-lib.api.md

@@ -1372,22 +1372,23 @@ export class RushConstants {
     // @deprecated
     static readonly pinnedVersionsFilename: 'pinned-versions.json';
     static readonly pnpmConfigFilename: 'pnpm-config.json';
-    static readonly pnpmDependenciesFolderName: '.pnpm';
     static readonly pnpmfileGlobalFilename: 'global-pnpmfile.cjs';
     static readonly pnpmfileV1Filename: 'pnpmfile.js';
     static readonly pnpmfileV6Filename: '.pnpmfile.cjs';
     static readonly pnpmModulesFilename: '.modules.yaml';
     static readonly pnpmPatchesCommonFolderName: `pnpm-patches`;
     static readonly pnpmPatchesFolderName: 'patches';
+    static readonly pnpmSyncFilename: '.pnpm-sync.json';
     static readonly pnpmV3ShrinkwrapFilename: 'pnpm-lock.yaml';
+    static readonly pnpmVirtualStoreFolderName: '.pnpm';
     static readonly projectImpactGraphFilename: 'project-impact-graph.yaml';
     static readonly projectRushFolderName: '.rush';
     static readonly projectShrinkwrapFilename: 'shrinkwrap-deps.json';
     static readonly rebuildCommandName: 'rebuild';
     static readonly repoStateFilename: 'repo-state.json';
     static readonly rushAlertsConfigFilename: 'rush-alerts.json';
+    static readonly rushHotlinkStateFilename: 'rush-hotlink-state.json';
     static readonly rushJsonFilename: 'rush.json';
-    static readonly rushLinkStateFilename: 'rush-link-state.json';
     static readonly rushLogsFolderName: 'rush-logs';
     static readonly rushPackageName: '@microsoft/rush';
     static readonly rushPluginManifestFilename: 'rush-plugin-manifest.json';

libraries/rush-lib/src/api/RushProjectConfiguration.ts

@@ -12,7 +12,7 @@ import type { IPhase } from './CommandLineConfiguration';
 import { OverlappingPathAnalyzer } from '../utilities/OverlappingPathAnalyzer';
 import schemaJson from '../schemas/rush-project.schema.json';
 import anythingSchemaJson from '../schemas/rush-project.schema.json';
-import { RushConnect } from '../utilities/RushConnect';
+import { HotlinkManager } from '../utilities/HotlinkManager';
 import type { RushConfiguration } from './RushConfiguration';
 
 /**
@@ -349,10 +349,9 @@ export class RushProjectConfiguration {
   ): string | undefined {
     const rushConfiguration: RushConfiguration | undefined = this.project.rushConfiguration;
     if (rushConfiguration) {
-      const rushConnect: RushConnect = RushConnect.loadFromLinkStateFile(rushConfiguration);
-      const subspaceNameList: string[] = Object.keys(rushConnect.rushLinkState ?? {});
-      if (subspaceNameList.includes(this.project.subspace.subspaceName)) {
-        return 'Caching has been disabled for this project because it is a linked package.';
+      const hotlinkManager: HotlinkManager = HotlinkManager.loadFromRushConfiguration(rushConfiguration);
+      if (hotlinkManager.hasAnyHotlinksInSubspace(this.project.subspace.subspaceName)) {
+        return 'Caching has been disabled for this project because it is in a subspace with hotlinked dependencies.';
       }
     }
 

libraries/rush-lib/src/api/test/__snapshots__/RushCommandLine.test.ts.snap

@@ -1141,23 +1141,23 @@ Object {
       "actionName": "bridge-package",
       "parameters": Array [
         Object {
-          "description": "The folder path of a locally built project, whose installation will be simulated using node_modules symlinks.  This folder will be the target of the symlinks.",
+          "description": "The path of folder of a project outside of this Rush repo, whose installation will be simulated using node_modules symlinks (\\"hotlinks\\").  This folder is the symlink target.",
           "environmentVariable": undefined,
           "kind": "String",
           "longName": "--path",
           "required": true,
           "shortName": undefined,
         },
         Object {
-          "description": "A list of Rush project names to connect to the external package. If not specified, uses the project in the current working directory.",
+          "description": "A list of Rush project names that will be hotlinked to the \\"--path\\" folder. If not specified, the default is the project of the current working directory.",
           "environmentVariable": undefined,
           "kind": "StringList",
           "longName": "--project",
           "required": false,
           "shortName": undefined,
         },
         Object {
-          "description": "It will directly replace the output for the specified version of the package, which requires you to have that package installed under the specified name in advance.",
+          "description": "Specify which installed versions should be hotlinked.  If omitted, the default is all versions (\\"*).",
           "environmentVariable": undefined,
           "kind": "String",
           "longName": "--version",
@@ -1170,15 +1170,15 @@ Object {
       "actionName": "link-package",
       "parameters": Array [
         Object {
-          "description": "The folder path of a locally built project, whose installation will be simulated using node_modules symlinks.  This folder will be the target of the symlinks.",
+          "description": "The path of folder of a project outside of this Rush repo, whose installation will be simulated using node_modules symlinks (\\"hotlinks\\").  This folder is the symlink target.",
           "environmentVariable": undefined,
           "kind": "String",
           "longName": "--path",
           "required": true,
           "shortName": undefined,
         },
         Object {
-          "description": "A list of Rush project names to connect to the external package. If not specified, uses the project in the current working directory.",
+          "description": "A list of Rush project names that will be hotlinked to the \\"--path\\" folder. If not specified, the default is the project of the current working directory.",
           "environmentVariable": undefined,
           "kind": "StringList",
           "longName": "--project",

libraries/rush-lib/src/cli/RushXCommandLine.ts

@@ -228,7 +228,7 @@ export class RushXCommandLine {
       const { configuration: experiments } = rushConfiguration?.experimentsConfiguration;
 
       if (experiments?.usePnpmSyncForInjectedDependencies) {
-        const pnpmSyncJsonPath: string = packageFolder + '/node_modules/.pnpm-sync.json';
+        const pnpmSyncJsonPath: string = `${packageFolder}/${RushConstants.nodeModulesFolderName}/${RushConstants.pnpmSyncFilename}`;
         if (await FileSystem.existsAsync(pnpmSyncJsonPath)) {
           const { PackageExtractor } = await import(
             /* webpackChunkName: 'PackageExtractor' */

libraries/rush-lib/src/cli/actions/AlertAction.ts

@@ -1,15 +1,13 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import { ConsoleTerminalProvider, Terminal } from '@rushstack/terminal';
 import type { CommandLineFlagParameter, CommandLineStringParameter } from '@rushstack/ts-command-line';
 
 import type { RushCommandLineParser } from '../RushCommandLineParser';
 import { BaseRushAction } from './BaseRushAction';
 import { RushAlerts } from '../../utilities/RushAlerts';
 
 export class AlertAction extends BaseRushAction {
-  private readonly _terminal: Terminal;
   private readonly _snoozeParameter: CommandLineStringParameter;
   private readonly _snoozeTimeFlagParameter: CommandLineFlagParameter;
 
@@ -23,7 +21,6 @@ export class AlertAction extends BaseRushAction {
         '  The alert definitions can be found in the rush-alerts.json config file.',
       parser
     });
-    this._terminal = new Terminal(new ConsoleTerminalProvider({ verboseEnabled: parser.isDebug }));
 
     this._snoozeParameter = this.defineStringParameter({
       parameterLongName: '--snooze',
@@ -41,7 +38,7 @@ export class AlertAction extends BaseRushAction {
   public async runAsync(): Promise<void> {
     const rushAlerts: RushAlerts = await RushAlerts.loadFromConfigurationAsync(
       this.rushConfiguration,
-      this._terminal
+      this.terminal
     );
     const snoozeAlertId: string | undefined = this._snoozeParameter.value;
     if (snoozeAlertId) {

libraries/rush-lib/src/cli/actions/BaseAddAndRemoveAction.ts

@@ -79,6 +79,7 @@ export abstract class BaseAddAndRemoveAction extends BaseRushAction {
       /* webpackChunkName: 'PackageJsonUpdater' */ '../../logic/PackageJsonUpdater'
     );
     const updater: PackageJsonUpdaterType.PackageJsonUpdater = new packageJsonUpdater.PackageJsonUpdater(
+      this.terminal,
       this.rushConfiguration,
       this.rushGlobalFolder
     );

libraries/rush-lib/src/cli/actions/BaseAutoinstallerAction.ts

@@ -2,14 +2,12 @@
 // See LICENSE in the project root for license information.
 
 import type { IRequiredCommandLineStringParameter } from '@rushstack/ts-command-line';
-import type { ITerminal } from '@rushstack/terminal';
 
 import { BaseRushAction, type IBaseRushActionOptions } from './BaseRushAction';
 import { Autoinstaller } from '../../logic/Autoinstaller';
 
 export abstract class BaseAutoinstallerAction extends BaseRushAction {
   protected readonly _name: IRequiredCommandLineStringParameter;
-  protected readonly _terminal: ITerminal;
 
   public constructor(options: IBaseRushActionOptions) {
     super(options);
@@ -21,8 +19,6 @@ export abstract class BaseAutoinstallerAction extends BaseRushAction {
       description:
         'The name of the autoinstaller, which must be one of the folders under common/autoinstallers.'
     });
-
-    this._terminal = this.parser.terminal;
   }
 
   protected abstract prepareAsync(autoinstaller: Autoinstaller): Promise<void>;
@@ -37,7 +33,7 @@ export abstract class BaseAutoinstallerAction extends BaseRushAction {
 
     await this.prepareAsync(autoinstaller);
 
-    this._terminal.writeLine();
-    this._terminal.writeLine('Success.');
+    this.terminal.writeLine();
+    this.terminal.writeLine('Success.');
   }
 }

…/cli/actions/BaseSymlinkPackageAction.ts …/cli/actions/BaseHotlinkPackageAction.tslibraries/rush-lib/src/cli/actions/BaseSymlinkPackageAction.ts renamed to libraries/rush-lib/src/cli/actions/BaseHotlinkPackageAction.ts libraries/rush-lib/src/cli/actions/BaseSymlinkPackageAction.ts renamed to libraries/rush-lib/src/cli/actions/BaseHotlinkPackageAction.ts

@@ -1,16 +1,20 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import type { CommandLineStringListParameter, CommandLineStringParameter } from '@rushstack/ts-command-line';
+import type {
+  CommandLineStringListParameter,
+  IRequiredCommandLineStringParameter
+} from '@rushstack/ts-command-line';
 import path from 'path';
 import type { RushConfigurationProject } from '../../api/RushConfigurationProject';
-import { RushConnect } from '../../utilities/RushConnect';
+import { HotlinkManager } from '../../utilities/HotlinkManager';
 import { BaseRushAction, type IBaseRushActionOptions } from './BaseRushAction';
 import { Async } from '@rushstack/node-core-library';
+import { RushConstants } from '../../logic/RushConstants';
 
-export abstract class BaseSymlinkPackageAction extends BaseRushAction {
+export abstract class BaseHotlinkPackageAction extends BaseRushAction {
   protected readonly _projectList: CommandLineStringListParameter;
-  protected readonly _pathParameter: CommandLineStringParameter;
+  protected readonly _pathParameter: IRequiredCommandLineStringParameter;
 
   protected constructor(options: IBaseRushActionOptions) {
     super(options);
@@ -20,24 +24,24 @@ export abstract class BaseSymlinkPackageAction extends BaseRushAction {
       argumentName: 'PATH',
       required: true,
       description:
-        'The folder path of a locally built project, whose installation will be simulated using node_modules' +
-        ' symlinks.  This folder will be the target of the symlinks.'
+        'The path of folder of a project outside of this Rush repo, whose installation will be simulated using' +
+        ' node_modules symlinks ("hotlinks").  This folder is the symlink target.'
     });
 
     this._projectList = this.defineStringListParameter({
       parameterLongName: '--project',
       required: false,
       argumentName: 'PROJECT',
       description:
-        'A list of Rush project names to connect to the external package. ' +
-        'If not specified, uses the project in the current working directory.'
+        'A list of Rush project names that will be hotlinked to the "--path" folder. ' +
+        'If not specified, the default is the project of the current working directory.'
     });
   }
 
   protected abstract connectPackageAsync(
     consumerPackage: RushConfigurationProject,
     linkedPackagePath: string,
-    rushConnect: RushConnect
+    hotlinkManager: HotlinkManager
   ): Promise<void>;
 
   protected async getProjectsToLinkAsync(): Promise<Set<RushConfigurationProject>> {
@@ -49,7 +53,7 @@ export abstract class BaseSymlinkPackageAction extends BaseRushAction {
         const project: RushConfigurationProject | undefined =
           this.rushConfiguration.getProjectByName(projectName);
         if (!project) {
-          throw new Error(`The project "${projectName}" was not found in the "rush.json"`);
+          throw new Error(`The project "${projectName}" was not found in "${RushConstants.rushPackageName}"`);
         }
         projectsToLink.add(project);
       }
@@ -66,12 +70,16 @@ export abstract class BaseSymlinkPackageAction extends BaseRushAction {
   }
 
   protected async runAsync(): Promise<void> {
-    const rushConnect: RushConnect = RushConnect.loadFromLinkStateFile(this.rushConfiguration);
-    const linkedPackagePath: string = path.resolve(this._pathParameter.value!);
+    const hotlinkManager: HotlinkManager = HotlinkManager.loadFromRushConfiguration(this.rushConfiguration);
+    const linkedPackagePath: string = path.resolve(process.cwd(), this._pathParameter.value);
     const projectsToLink: Set<RushConfigurationProject> = await this.getProjectsToLinkAsync();
 
-    await Async.forEachAsync(projectsToLink, async (project) => {
-      await this.connectPackageAsync(project, linkedPackagePath, rushConnect);
-    });
+    await Async.forEachAsync(
+      projectsToLink,
+      async (project) => {
+        await this.connectPackageAsync(project, linkedPackagePath, hotlinkManager);
+      },
+      { concurrency: 5 }
+    );
   }
 }

libraries/rush-lib/src/cli/actions/BaseInstallAction.ts

@@ -8,7 +8,7 @@ import type {
   IRequiredCommandLineIntegerParameter
 } from '@rushstack/ts-command-line';
 import { AlreadyReportedError } from '@rushstack/node-core-library';
-import { type ITerminal, Colorize } from '@rushstack/terminal';
+import { Colorize } from '@rushstack/terminal';
 
 import { BaseRushAction, type IBaseRushActionOptions } from './BaseRushAction';
 import { Event } from '../../api/EventHooks';
@@ -37,7 +37,6 @@ interface ISubspaceInstallationData {
  * This is the common base class for InstallAction and UpdateAction.
  */
 export abstract class BaseInstallAction extends BaseRushAction {
-  protected readonly _terminal: ITerminal;
   protected readonly _variantParameter: CommandLineStringParameter;
   protected readonly _purgeParameter: CommandLineFlagParameter;
   protected readonly _bypassPolicyParameter: CommandLineFlagParameter;
@@ -56,8 +55,6 @@ export abstract class BaseInstallAction extends BaseRushAction {
   public constructor(options: IBaseRushActionOptions) {
     super(options);
 
-    this._terminal = options.parser.terminal;
-
     this._purgeParameter = this.defineFlagParameter({
       parameterLongName: '--purge',
       parameterShortName: '-p',
@@ -126,8 +123,8 @@ export abstract class BaseInstallAction extends BaseRushAction {
         this.rushConfiguration.subspacesConfiguration?.preventSelectingAllSubspaces &&
         !this._selectionParameters?.didUserSelectAnything()
       ) {
-        this._terminal.writeLine();
-        this._terminal.writeLine(
+        this.terminal.writeLine();
+        this.terminal.writeLine(
           Colorize.red(
             `The subspaces preventSelectingAllSubspaces configuration is enabled, which enforces installation for a specified set of subspace,` +
               ` passed by the "${SUBSPACE_LONG_ARG_NAME}" parameter or selected from targeted projects using any project selector.`
@@ -177,13 +174,13 @@ export abstract class BaseInstallAction extends BaseRushAction {
     if (selectedSubspaces) {
       // Check each subspace for version inconsistencies
       for (const subspace of selectedSubspaces) {
-        VersionMismatchFinder.ensureConsistentVersions(this.rushConfiguration, this._terminal, {
+        VersionMismatchFinder.ensureConsistentVersions(this.rushConfiguration, this.terminal, {
           subspace,
           variant
         });
       }
     } else {
-      VersionMismatchFinder.ensureConsistentVersions(this.rushConfiguration, this._terminal, {
+      VersionMismatchFinder.ensureConsistentVersions(this.rushConfiguration, this.terminal, {
         subspace: undefined,
         variant
       });