@rushstack/rush-sdk 5.76.1 → 5.77.2-pr3481.5

package/dist/rush-lib.d.ts

@@ -136,6 +136,59 @@ export declare class ApprovedPackagesPolicy {
     get nonbrowserApprovedPackages(): ApprovedPackagesConfiguration;
 }
 
+/**
+ * A base class for flag file.
+ * @internal
+ */
+export declare class _BaseFlag<T extends object = JsonObject> {
+    /**
+     * Flag file path
+     */
+    protected _path: string;
+    /**
+     * Content of the flag
+     */
+    protected _state: T;
+    /**
+     * Whether the current state is modified
+     */
+    protected _isModified: boolean;
+    /**
+     * Creates a new flag file
+     * @param folderPath - the folder that this flag is managing
+     * @param state - optional, the state that should be managed or compared
+     */
+    constructor(folderPath: string, state?: Partial<T>);
+    /**
+     * Returns true if the file exists and the contents match the current state.
+     */
+    isValid(): boolean;
+    /**
+     * Writes the flag file to disk with the current state
+     */
+    create(): void;
+    /**
+     * Merge new data into current state by lodash "merge"
+     */
+    mergeFromObject(data: JsonObject): void;
+    /**
+     * Writes the flag file to disk with the current state if modified
+     */
+    saveIfModified(): void;
+    /**
+     * Removes the flag file
+     */
+    clear(): void;
+    /**
+     * Returns the full path to the flag file
+     */
+    get path(): string;
+    /**
+     * Returns the name of the flag file
+     */
+    protected get flagName(): string;
+}
+
 /**
  * Use this class to load and save the "common/config/rush/build-cache.json" config file.
  * This file provides configuration options for cached project build output.
@@ -517,12 +570,12 @@ export declare enum EnvironmentVariableNames {
      */
     RUSH_GLOBAL_FOLDER = "RUSH_GLOBAL_FOLDER",
     /**
-     * Provides a credential for a remote build cache, if configured. Setting this environment variable
-     * overrides whatever credential has been saved in the local cloud cache credentials using
-     * `rush update-cloud-credentials`.
+     * Provides a credential for a remote build cache, if configured.  This credential overrides any cached credentials.
      *
      * @remarks
-     * This credential overrides any cached credentials.
+     * Setting this environment variable overrides whatever credential has been saved in the
+     * local cloud cache credentials using `rush update-cloud-credentials`.
+     *
      *
      * If Azure Blob Storage is used to store cache entries, this must be a SAS token serialized as query
      * parameters.
@@ -532,22 +585,28 @@ export declare enum EnvironmentVariableNames {
     RUSH_BUILD_CACHE_CREDENTIAL = "RUSH_BUILD_CACHE_CREDENTIAL",
     /**
      * Setting this environment variable overrides the value of `buildCacheEnabled` in the `build-cache.json`
-     * configuration file. Specify `1` to enable the build cache or `0` to disable it.
+     * configuration file.
+     *
+     * @remarks
+     * Specify `1` to enable the build cache or `0` to disable it.
      *
      * If set to `0`, this is equivalent to passing the `--disable-build-cache` flag.
+     *
+     * If there is no build cache configured, then this environment variable is ignored.
      */
     RUSH_BUILD_CACHE_ENABLED = "RUSH_BUILD_CACHE_ENABLED",
     /**
-     * Setting this environment variable overrides the value of `isCacheWriteAllowed` in the `build-cache.json`
-     * configuration file. Specify `1` to allow cache write and `0` to disable it.
+     * Overrides the value of `isCacheWriteAllowed` in the `build-cache.json` configuration file. The value of this
+     * environment variable must be `1` (for true) or `0` (for false). If there is no build cache configured, then
+     * this environment variable is ignored.
      */
     RUSH_BUILD_CACHE_WRITE_ALLOWED = "RUSH_BUILD_CACHE_WRITE_ALLOWED",
     /**
-     * Allows the git binary path to be explicitly specified.
+     * Explicitly specifies the path for the Git binary that is invoked by certain Rush operations.
      */
     RUSH_GIT_BINARY_PATH = "RUSH_GIT_BINARY_PATH",
     /**
-     * Allows the tar binary path to be explicitly specified.
+     * Explicitly specifies the path for the `tar` binary that is invoked by certain Rush operations.
      */
     RUSH_TAR_BINARY_PATH = "RUSH_TAR_BINARY_PATH",
     /**
@@ -869,6 +928,11 @@ export declare interface IExperimentsJson {
      * in common/config/rush/command-line.json.
      */
     phasedCommands?: boolean;
+    /**
+     * If true, rush install or rush update implicitly specify --ignore-scripts during pnpm install,
+     * and run install lifecycle scripts by pnpm rebuild --pending after pnpm install successfully.
+     */
+    deferredInstallationScripts?: boolean;
 }
 
 /**
@@ -935,6 +999,50 @@ declare interface IIndividualVersionJson extends IVersionPolicyJson {
     lockedMajor?: number;
 }
 
+/**
+ * This represents the JSON data structure for the "last-install.flag" file.
+ * @internal
+ */
+export declare interface _ILastInstallFlagJson {
+    /**
+     * Current node version
+     */
+    node: string;
+    /**
+     * Current package manager name
+     */
+    packageManager: PackageManagerName;
+    /**
+     * Current package manager version
+     */
+    packageManagerVersion: string;
+    /**
+     * Current rush json folder
+     */
+    rushJsonFolder: string;
+    /**
+     * The content of package.json, used in the flag file of autoinstaller
+     */
+    packageJson?: IPackageJson;
+    /**
+     * Same with pnpmOptions.pnpmStorePath in rush.json
+     */
+    storePath?: string;
+    /**
+     * True when "useWorkspaces" is true in rush.json
+     */
+    workspaces?: true;
+    /**
+     * True when user explicitly specify "--ignore-scripts" CLI parameter or deferredInstallationScripts
+     */
+    ignoreScripts?: true;
+    /**
+     * When specified, it is a list of selected projects during partial install
+     * It is undefined when full install
+     */
+    selectedProjectNames?: string[];
+}
+
 /**
  * Options to pass to the rush "launch" functions.
  *
@@ -1300,6 +1408,7 @@ declare interface IRushConfigurationProjectJson {
     skipRushCheck?: boolean;
     publishFolder?: string;
     tags?: string[];
+    splitWorkspace?: boolean;
 }
 
 /**
@@ -1324,6 +1433,16 @@ declare interface IRushConfigurationProjectOptions {
     allowedProjectTags: Set<string> | undefined;
 }
 
+/**
+ * The filter parameters to search from all projects.
+ */
+declare interface IRushConfigurationProjectsFilter {
+    /**
+     * If true, filter out projects that specify splitWorkspace as true.
+     */
+    splitWorkspace: boolean;
+}
+
 /**
  * Part of IRushConfigurationJson.
  */
@@ -1440,7 +1559,7 @@ export declare interface IStopwatchResult {
 export declare interface ITelemetryData {
     /**
      * Command name
-     * @example 'build'
+     * @example `"build"`
      */
     readonly name: string;
     /**
@@ -1452,25 +1571,86 @@ export declare interface ITelemetryData {
      */
     readonly result: 'Succeeded' | 'Failed';
     /**
-     * The timestamp of the telemetry logging
+     * The millisecond-resolution timestamp of the telemetry logging
      * @example 1648001893024
      */
-    readonly timestamp?: number;
+    readonly timestampMs?: number;
     /**
-     * The platform the command was executed on, reads from process.platform
-     * @example darwin, win32, linux...
+     * The platform the command was executed on, based on the Node.js `process.platform()` API
+     * @example `"darwin"`, `"win32"`, `"linux"`
      */
     readonly platform?: string;
     /**
-     * The rush version
-     * @example 5.63.0
+     * The Rush version
+     * @example `5.63.0`
      */
     readonly rushVersion?: string;
+    /**
+     * Detailed information about the host machine.
+     */
+    readonly machineInfo?: ITelemetryMachineInfo;
+    /**
+     * Only applicable to phased commands. Provides detailed results by operation.
+     * Keys are operation names, values contain result, timing information, and dependencies.
+     */
+    readonly operationResults?: Record<string, ITelemetryOperationResult>;
     readonly extraData?: {
         [key: string]: string | number | boolean;
     };
 }
 
+/**
+ * @beta
+ */
+export declare interface ITelemetryMachineInfo {
+    /**
+     * The CPU architecture
+     * @example `"AMD64"`
+     */
+    machineArchitecture: string;
+    /**
+     * The CPU model
+     * * @example `"AMD Ryzen 7 3700X 8-Core Processor"`
+     */
+    machineCpu: string;
+    /**
+     * The number of logical CPU cores.
+     */
+    machineCores: number;
+    /**
+     * The total amount of RAM on the machine, in MiB.
+     */
+    machineTotalMemoryMiB: number;
+    /**
+     * The amount of free RAM on the machine at the end of execution, in MiB.
+     */
+    machineFreeMemoryMiB: number;
+}
+
+/**
+ * @beta
+ */
+export declare interface ITelemetryOperationResult {
+    /**
+     * The names of operations that this operation depends on.
+     */
+    dependencies: string[];
+    /**
+     * The status code for the operation.
+     */
+    result: string;
+    /**
+     * A timestamp in milliseconds (from `performance.now()`) when the operation started.
+     * If the operation was blocked, will be `undefined`.
+     */
+    startTimestampMs?: number;
+    /**
+     * A timestamp in milliseconds (from `performance.now()`) when the operation finished.
+     * If the operation was blocked, will be `undefined`.
+     */
+    endTimestampMs?: number;
+}
+
 /**
  * Options for `RushConfiguration.tryFindRushJsonLocation`.
  * @public
@@ -1521,16 +1701,9 @@ export declare interface _IYarnOptionsJson extends IPackageManagerOptionsJsonBas
  * it can invalidate the last install.
  * @internal
  */
-export declare class _LastInstallFlag {
-    private _path;
-    private _state;
-    /**
-     * Creates a new LastInstall flag
-     * @param folderPath - the folder that this flag is managing
-     * @param state - optional, the state that should be managed or compared
-     */
-    constructor(folderPath: string, state?: JsonObject);
+export declare class _LastInstallFlag extends _BaseFlag<_ILastInstallFlagJson> {
     /**
+     * @override
      * Returns true if the file exists and the contents match the current state.
      */
     isValid(): boolean;
@@ -1542,18 +1715,6 @@ export declare class _LastInstallFlag {
      */
     checkValidAndReportStoreIssues(): boolean;
     private _isValid;
-    /**
-     * Writes the flag file to disk with the current state
-     */
-    create(): void;
-    /**
-     * Removes the flag file
-     */
-    clear(): void;
-    /**
-     * Returns the full path to the flag file
-     */
-    get path(): string;
     /**
      * Returns the name of the flag file
      */
@@ -2206,6 +2367,7 @@ export declare class RushConfiguration {
     private _changesFolder;
     private _commonFolder;
     private _commonTempFolder;
+    private _commonTempSplitFolder;
     private _commonScriptsFolder;
     private _commonRushConfigFolder;
     private _packageManager;
@@ -2214,8 +2376,10 @@ export declare class RushConfiguration {
     private _npmTmpFolder;
     private _yarnCacheFolder;
     private _shrinkwrapFilename;
+    private _splitWorkspaceShrinkwrapFilename;
     private _tempShrinkwrapFilename;
     private _tempShrinkwrapPreinstallFilename;
+    private _tempSplitWorkspaceShrinkwrapFilename;
     private _currentVariantJsonFilename;
     private _packageManagerToolVersion;
     private _packageManagerToolFilename;
@@ -2246,6 +2410,8 @@ export declare class RushConfiguration {
     private _projects;
     private _projectsByName;
     private _projectsByTag;
+    private _filteredProjectsCache;
+    private _hasSplitWorkspaceProject;
     private _commonVersionsConfigurationsByVariant;
     private _versionPolicyConfiguration;
     private _versionPolicyConfigurationFilePath;
@@ -2338,6 +2504,12 @@ export declare class RushConfiguration {
      * Example: `C:\MyRepo\common\temp`
      */
     get commonTempFolder(): string;
+    /**
+     * The folder where temporary files will be stored.  This is always a subfolder called "temp"
+     * under the common folder.
+     * Example: `C:\MyRepo\common\temp-split`
+     */
+    get commonTempSplitFolder(): string;
     /**
      * The folder where automation scripts are stored.  This is always a subfolder called "scripts"
      * under the common folder.
@@ -2395,6 +2567,7 @@ export declare class RushConfiguration {
      * Example: `npm-shrinkwrap.json` or `pnpm-lock.yaml`
      */
     get shrinkwrapFilename(): string;
+    get splitWorkspaceShrinkwrapFilename(): string;
     /**
      * The full path of the temporary shrinkwrap file that is used during "rush install".
      * This file may get rewritten by the package manager during installation.
@@ -2403,6 +2576,14 @@ export declare class RushConfiguration {
      * Example: `C:\MyRepo\common\temp\npm-shrinkwrap.json` or `C:\MyRepo\common\temp\pnpm-lock.yaml`
      */
     get tempShrinkwrapFilename(): string;
+    /**
+     * The full path of the temporary shrinkwrap file for split workspace that is used during
+     * "rush install". This file may get rewritten by the package manager during installation.
+     * @remarks
+     * This property merely reports the filename; the file itself may not actually exist.
+     * Example: `C:\MyRepo\common\temp-split\pnpm-lock.yaml`
+     */
+    get tempSplitWorkspaceShrinkwrapFilename(): string;
     /**
      * The full path of a backup copy of tempShrinkwrapFilename. This backup copy is made
      * before installation begins, and can be compared to determine how the package manager
@@ -2562,6 +2743,11 @@ export declare class RushConfiguration {
      * @beta
      */
     get projectsByTag(): ReadonlyMap<string, ReadonlySet<RushConfigurationProject>>;
+    /**
+     * Search for projects according to filter
+     * @beta
+     */
+    getFilteredProjects(filter: IRushConfigurationProjectsFilter): RushConfigurationProject[];
     /**
      * {@inheritDoc NpmOptionsConfiguration}
      */
@@ -2608,6 +2794,10 @@ export declare class RushConfiguration {
      * The rush hooks. It allows customized scripts to run at the specified point.
      */
     get packageNameParser(): PackageNameParser;
+    /**
+     * Is there any split workspace project.
+     */
+    get hasSplitWorkspaceProject(): boolean;
     /**
      * Gets the path to the common-versions.json config file for a specific variant.
      * @param variant - The name of the current variant in use by the active command.
@@ -2640,6 +2830,11 @@ export declare class RushConfiguration {
      * @param variant - The name of the current variant in use by the active command.
      */
     getCommittedShrinkwrapFilename(variant?: string | undefined): string;
+    /**
+     * Gets the committed shrinkwrap file name for split workspace.
+     * @param variant - The name of the current variant in use by the active command.
+     */
+    getCommittedSplitWorkspaceShrinkwrapFilename(): string;
     /**
      * Gets the absolute path for "pnpmfile.js" for a specific variant.
      * @param variant - The name of the current variant in use by the active command.
@@ -2694,6 +2889,12 @@ export declare class RushConfiguration {
      */
     tryGetProjectForPath(currentFolderPath: string): RushConfigurationProject | undefined;
     private _getVariantConfigFolderPath;
+    /**
+     * Split workspace can only works on PNPM with "useWorkspaces" enabled.
+     * The workspace project can NOT depend on a split workspace project.
+     * The split workspace project CAN depend on a workspace project.
+     */
+    private _validateSplitWorkspaceRelationships;
 }
 
 /**
@@ -2719,6 +2920,7 @@ export declare class RushConfigurationProject {
     private readonly _publishFolder;
     private readonly _rushConfiguration;
     private readonly _tags;
+    private readonly _splitWorkspace;
     private _versionPolicy;
     private _dependencyProjects;
     private _consumingProjects;
@@ -2876,10 +3078,21 @@ export declare class RushConfigurationProject {
      */
     get isMainProject(): boolean;
     /**
-     * The set of tags applied to this project.
+     * An optional set of custom tags that can be used to select this project.
+     *
+     * @remarks
+     * For example, adding `my-custom-tag` will allow this project to be selected by the
+     * command `rush list --only tag:my-custom-tag`.  The tag name must be one or more words separated
+     * by hyphens, where a word may contain lowercase letters, digits, and the period character.
+     *
      * @beta
      */
     get tags(): ReadonlySet<string>;
+    /**
+     * Whether this project is a split workspace project.
+     * @beta
+     */
+    get splitWorkspace(): boolean;
 }
 
 /**
@@ -2927,6 +3140,12 @@ export declare class RushConstants {
      * Example: `C:\MyRepo\common\temp`
      */
     static readonly rushTempFolderName: string;
+    /**
+     * The folder name ("temp-split") under the common folder, or under the .rush folder in each project's directory where
+     * temporary files will be stored.
+     * Example: `C:\MyRepo\common\temp-split`
+     */
+    static readonly rushTempSplitFolderName: string;
     /**
      * The folder name ("projects") where temporary projects will be stored.
      * Example: `C:\MyRepo\common\temp\projects`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rushstack/rush-sdk",
-  "version": "5.76.1",
+  "version": "5.77.2-pr3481.5",
   "description": "An API for interacting with the Rush engine",
   "repository": {
     "type": "git",
@@ -12,18 +12,18 @@
   "typings": "dist/rush-lib.d.ts",
   "license": "MIT",
   "dependencies": {
-    "@rushstack/node-core-library": "3.50.1",
+    "@rushstack/node-core-library": "3.51.1",
     "@types/node-fetch": "1.6.9",
     "tapable": "2.2.1"
   },
   "devDependencies": {
-    "@microsoft/rush-lib": "5.76.1",
+    "@microsoft/rush-lib": "5.77.2-pr3481.5",
     "@rushstack/eslint-config": "3.0.0",
-    "@rushstack/heft": "0.47.0",
-    "@rushstack/heft-node-rig": "1.10.0",
-    "@rushstack/stream-collator": "4.0.193",
+    "@rushstack/heft": "0.47.5",
+    "@rushstack/heft-node-rig": "1.10.7",
+    "@rushstack/stream-collator": "4.0.200",
     "@rushstack/ts-command-line": "4.12.2",
-    "@rushstack/terminal": "0.3.62",
+    "@rushstack/terminal": "0.3.69",
     "@types/heft-jest": "1.0.1",
     "@types/semver": "7.3.5",
     "@types/webpack-env": "1.13.0"
@@ -32,6 +32,5 @@
     "build": "heft build --clean",
     "_phase:build": "heft build --clean",
     "_phase:test": "heft test --no-build"
-  },
-  "readme": "## @rushstack/rush-sdk\n\nThis is a companion package for the Rush tool.  See the [@microsoft/rush](https://www.npmjs.com/package/@microsoft/rush) package for details.\n\n⚠ ***THIS PACKAGE IS EXPERIMENTAL*** ⚠\n\nThe **@rushstack/rush-sdk** package acts as a lightweight proxy for accessing the APIs of the **@microsoft/rush-lib** engine.  It is intended to support three different use cases:\n\n1. Rush plugins should import from **@rushstack/rush-sdk** instead of **@microsoft/rush-lib**.  This gives plugins full access to Rush APIs while avoiding a redundant installation of those packages.  At runtime, the APIs will be bound to the correct `rushVersion` from **rush.json**, and guaranteed to be the same **@microsoft/rush-lib** module instance as the plugin host.\n\n2. When authoring unit tests for a Rush plugin, developers should add **@microsoft/rush-lib** to their **package.json** `devDependencies`.  In this context, **@rushstack/rush-sdk** will resolve to that instance for testing purposes.\n\n3. For scripts and tools that are designed to be used in a Rush monorepo, in the future **@rushstack/rush-sdk** will automatically invoke **install-run-rush.js** and load the local installation.  This ensures that tools load a compatible version of the Rush engine for the given branch.  Once this is implemented, **@rushstack/rush-sdk** can replace **@microsoft/rush-lib** entirely as the official API interface, with the latter serving as the underlying implementation.\n\n\nThe **@rushstack/rush-sdk** API declarations are identical to the corresponding version of **@microsoft/rush-lib**.\n\n## Debugging\n\nVerbose logging can be turn on by set environment variable `RUSH_SDK_DEBUG` to `1`\n\n\n## Links\n\n- [CHANGELOG.md](\n  https://github.com/microsoft/rushstack/blob/main/apps/rush/CHANGELOG.md) - Find\n  out what's new in the latest version\n- [API Reference](https://api.rushstack.io/pages/rush-lib/)\n\nRush is part of the [Rush Stack](https://rushstack.io/) family of projects.\n"
+  }
 }