@rushstack/rush-sdk 5.97.0 → 5.97.1-pr3481.18

package/dist/rush-lib.d.ts

@@ -131,6 +131,55 @@ export declare class ApprovedPackagesPolicy {
     constructor(rushConfiguration: RushConfiguration, rushConfigurationJson: IRushConfigurationJson);
 }
 
+/**
+ * A base class for flag file.
+ * @internal
+ */
+export declare class _BaseFlag<T extends object = JsonObject> {
+    /**
+     * Flag file path
+     */
+    readonly 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 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.
@@ -210,6 +259,55 @@ export declare class ChangeManager {
  */
 export declare type CloudBuildCacheProviderFactory = (buildCacheJson: IBuildCacheJson) => ICloudBuildCacheProvider;
 
+/**
+ * Use this class to load and save the "common/config/rush/cobuild.json" config file.
+ * This file provides configuration options for the Rush Cobuild feature.
+ * @beta
+ */
+export declare class CobuildConfiguration {
+    private static _jsonSchema;
+    /**
+     * Indicates whether the cobuild feature is enabled.
+     * Typically it is enabled in the cobuild.json config file.
+     *
+     * Note: The orchestrator (or local users) should always have to opt into running with cobuilds by
+     * providing a cobuild context id. Even if cobuilds are "enabled" as a feature, they don't
+     * actually turn on for that particular build unless the cobuild context id is provided as an
+     * non-empty string.
+     */
+    readonly cobuildEnabled: boolean;
+    /**
+     * Cobuild context id
+     *
+     * @remarks
+     * The cobuild feature won't be enabled until the context id is provided as an non-empty string.
+     */
+    readonly cobuildContextId: string | undefined;
+    /**
+     * If true, Rush will automatically handle the leaf project with build cache "disabled" by writing
+     * to the cache in a special "log files only mode". This is useful when you want to use Cobuilds
+     * to improve the performance in CI validations and the leaf projects have not enabled cache.
+     */
+    readonly cobuildLeafProjectLogOnlyAllowed: boolean;
+    readonly cobuildLockProvider: ICobuildLockProvider;
+    private constructor();
+    /**
+     * Attempts to load the cobuild.json data from the standard file path `common/config/rush/cobuild.json`.
+     * If the file has not been created yet, then undefined is returned.
+     */
+    static tryLoadAsync(terminal: ITerminal, rushConfiguration: RushConfiguration, rushSession: RushSession): Promise<CobuildConfiguration | undefined>;
+    static getCobuildConfigFilePath(rushConfiguration: RushConfiguration): string;
+    private static _loadAsync;
+    get contextId(): string | undefined;
+    connectLockProviderAsync(): Promise<void>;
+    disconnectLockProviderAsync(): Promise<void>;
+}
+
+/**
+ * @beta
+ */
+export declare type CobuildLockProviderFactory = (cobuildJson: ICobuildJson) => ICobuildLockProvider;
+
 /**
  * Use this class to load and save the "common/config/rush/common-versions.json" config file.
  * This config file stores dependency version information that affects all projects in the repo.
@@ -339,6 +437,9 @@ export declare class EnvironmentConfiguration {
     private static _buildCacheCredential;
     private static _buildCacheEnabled;
     private static _buildCacheWriteAllowed;
+    private static _cobuildEnabled;
+    private static _cobuildContextId;
+    private static _cobuildLeafProjectLogOnlyAllowed;
     private static _gitBinaryPath;
     private static _tarBinaryPath;
     /**
@@ -394,6 +495,21 @@ export declare class EnvironmentConfiguration {
      * See {@link EnvironmentVariableNames.RUSH_BUILD_CACHE_WRITE_ALLOWED}
      */
     static get buildCacheWriteAllowed(): boolean | undefined;
+    /**
+     * If set, enables or disables the cobuild feature.
+     * See {@link EnvironmentVariableNames.RUSH_COBUILD_ENABLED}
+     */
+    static get cobuildEnabled(): boolean | undefined;
+    /**
+     * Provides a determined cobuild context id if configured
+     * See {@link EnvironmentVariableNames.RUSH_COBUILD_CONTEXT_ID}
+     */
+    static get cobuildContextId(): string | undefined;
+    /**
+     * If set, enables or disables the cobuild leaf project log only feature.
+     * See {@link EnvironmentVariableNames.RUSH_COBUILD_LEAF_PROJECT_LOG_ONLY_ALLOWED}
+     */
+    static get cobuildLeafProjectLogOnlyAllowed(): boolean | undefined;
     /**
      * Allows the git binary path to be explicitly provided.
      * See {@link EnvironmentVariableNames.RUSH_GIT_BINARY_PATH}
@@ -551,6 +667,29 @@ export declare const EnvironmentVariableNames: {
      * this environment variable is ignored.
      */
     readonly RUSH_BUILD_CACHE_WRITE_ALLOWED: "RUSH_BUILD_CACHE_WRITE_ALLOWED";
+    /**
+     * Setting this environment variable overrides the value of `cobuildEnabled` in the `cobuild.json`
+     * configuration file.
+     *
+     * @remarks
+     * Specify `1` to enable the cobuild or `0` to disable it.
+     *
+     * If there is no cobuild configured, then this environment variable is ignored.
+     */
+    readonly RUSH_COBUILD_ENABLED: "RUSH_COBUILD_ENABLED";
+    /**
+     * Setting this environment variable opt into running with cobuilds.
+     *
+     * @remarks
+     * If there is no cobuild configured, then this environment variable is ignored.
+     */
+    readonly RUSH_COBUILD_CONTEXT_ID: "RUSH_COBUILD_CONTEXT_ID";
+    /**
+     * If this variable is set to "1", When getting distributed builds, Rush will automatically handle the leaf project
+     * with build cache "disabled" by writing to the cache in a special "log files only mode". This is useful when you
+     * want to use Cobuilds to improve the performance in CI validations and the leaf projects have not enabled cache.
+     */
+    readonly RUSH_COBUILD_LEAF_PROJECT_LOG_ONLY_ALLOWED: "RUSH_COBUILD_LEAF_PROJECT_LOG_ONLY_ALLOWED";
     /**
      * Explicitly specifies the path for the Git binary that is invoked by certain Rush operations.
      */
@@ -714,6 +853,61 @@ export declare interface ICloudBuildCacheProvider {
     deleteCachedCredentialsAsync(terminal: ITerminal): Promise<void>;
 }
 
+/**
+ * @beta
+ */
+export declare interface ICobuildCompletedState {
+    status: OperationStatus.Success | OperationStatus.SuccessWithWarning | OperationStatus.Failure;
+    /**
+     * Completed state points to the cache id that was used to store the build cache.
+     * Note: Cache failed builds in a separate cache id
+     */
+    cacheId: string;
+}
+
+/**
+ * @beta
+ */
+export declare interface ICobuildContext {
+    /**
+     * The contextId is provided by the monorepo maintainer, it reads from environment variable {@link EnvironmentVariableNames.RUSH_COBUILD_CONTEXT_ID}.
+     * It ensure only the builds from the same given contextId cooperated. If user was more permissive,
+     * and wanted all PR and CI builds building anything with the same contextId to cooperate, then just
+     * set it to a static value.
+     */
+    contextId: string;
+    /**
+     * The id of cache. It should be keep same as the normal cacheId from ProjectBuildCache.
+     * Otherwise, there is a discrepancy in the success case then turning on cobuilds will
+     * fail to populate the normal build cache.
+     */
+    cacheId: string;
+    /**
+     * {@inheritdoc RushConstants.cobuildLockVersion}
+     */
+    version: number;
+}
+
+/**
+ * @beta
+ */
+export declare interface ICobuildJson {
+    cobuildEnabled: boolean;
+    cobuildLockProvider: string;
+}
+
+/**
+ * @beta
+ */
+export declare interface ICobuildLockProvider {
+    connectAsync(): Promise<void>;
+    disconnectAsync(): Promise<void>;
+    acquireLockAsync(context: ICobuildContext): Promise<boolean>;
+    renewLockAsync(context: ICobuildContext): Promise<void>;
+    setCompletedStateAsync(context: ICobuildContext, state: ICobuildCompletedState): Promise<void>;
+    getCompletedStateAsync(context: ICobuildContext): Promise<ICobuildCompletedState | undefined>;
+}
+
 /**
  * A collection of environment variables
  * @public
@@ -751,6 +945,10 @@ export declare interface ICreateOperationsContext {
      * The configuration for the build cache, if the feature is enabled.
      */
     readonly buildCacheConfiguration: BuildCacheConfiguration | undefined;
+    /**
+     * The configuration for the cobuild, if cobuild feature and build cache feature are both enabled.
+     */
+    readonly cobuildConfiguration: CobuildConfiguration | undefined;
     /**
      * The set of custom parameters for the executing command.
      * Maps from the `longName` field in command-line.json to the parser configuration in ts-command-line.
@@ -887,6 +1085,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;
     /**
      * If true, perform a clean install after when running `rush install` or `rush update` if the
      * `.npmrc` file has changed since the last install.
@@ -962,6 +1165,51 @@ 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[];
+    [key: string]: unknown;
+}
+
 /**
  * Options to pass to the rush "launch" functions.
  *
@@ -1157,10 +1405,6 @@ export declare interface IOperationRunner {
      * Name of the operation, for logging.
      */
     readonly name: string;
-    /**
-     * This flag determines if the operation is allowed to be skipped if up to date.
-     */
-    isSkipAllowed: boolean;
     /**
      * Indicates that this runner's duration has meaning.
      */
@@ -1174,10 +1418,6 @@ export declare interface IOperationRunner {
      * exit code
      */
     warningsAreAllowed: boolean;
-    /**
-     * Indicates if the output of this operation may be written to the cache
-     */
-    isCacheWriteAllowed: boolean;
     /**
      * Method to be executed for the operation.
      */
@@ -1215,7 +1455,34 @@ export declare interface IOperationRunnerContext {
     /**
      * Object used to track elapsed time.
      */
-    stopwatch: IStopwatchResult;
+    stopwatch: Stopwatch;
+    /**
+     * The current execution status of an operation. Operations start in the 'ready' state,
+     * but can be 'blocked' if an upstream operation failed. It is 'executing' when
+     * the operation is executing. Once execution is complete, it is either 'success' or
+     * 'failure'.
+     */
+    status: OperationStatus;
+    /**
+     * Error which occurred while executing this operation, this is stored in case we need
+     * it later (for example to re-print errors at end of execution).
+     */
+    error?: Error;
+    /**
+     * The set of operations that depend on this operation.
+     */
+    readonly consumers: Set<IOperationRunnerContext>;
+    /**
+     * The operation runner that is executing this operation.
+     */
+    readonly runner: IOperationRunner;
+    /**
+     * Normally the incremental build logic will rebuild changed projects as well as
+     * any projects that directly or indirectly depend on a changed project.
+     * If true, then the incremental build logic will only rebuild changed projects and
+     * ignore dependent projects.
+     */
+    readonly changedProjectsOnly: boolean;
 }
 
 /**
@@ -1456,6 +1723,7 @@ declare interface IRushConfigurationProjectJson {
     skipRushCheck?: boolean;
     publishFolder?: string;
     tags?: string[];
+    splitWorkspace?: boolean;
 }
 
 /**
@@ -1480,6 +1748,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.
  */
@@ -1743,19 +2021,9 @@ export declare interface _IYarnOptionsJson extends IPackageManagerOptionsJsonBas
  * it can invalidate the last install.
  * @internal
  */
-export declare class _LastInstallFlag {
-    private _state;
-    /**
-     * Returns the full path to the flag file
-     */
-    readonly path: string;
-    /**
-     * 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(options?: _ILockfileValidityCheckOptions): boolean;
@@ -1769,14 +2037,6 @@ export declare class _LastInstallFlag {
         rushVerb: string;
     }): boolean;
     private _isValid;
-    /**
-     * Writes the flag file to disk with the current state
-     */
-    create(): void;
-    /**
-     * Removes the flag file
-     */
-    clear(): void;
     /**
      * Returns the name of the flag file
      */
@@ -2091,10 +2351,18 @@ export declare enum OperationStatus {
      * The Operation is on the queue, ready to execute (but may be waiting for dependencies)
      */
     Ready = "READY",
+    /**
+     * The Operation is Queued
+     */
+    Queued = "QUEUED",
     /**
      * The Operation is currently executing
      */
     Executing = "EXECUTING",
+    /**
+     * The Operation is currently executing by a remote process
+     */
+    RemoteExecuting = "REMOTE EXECUTING",
     /**
      * The Operation completed successfully and did not write to standard output
      */
@@ -2264,6 +2532,14 @@ export declare class PhasedCommandHooks {
      * Hook is series for stable output.
      */
     readonly afterExecuteOperations: AsyncSeriesHook<[IExecutionResult, ICreateOperationsContext]>;
+    /**
+     * Hook invoked before executing a operation.
+     */
+    readonly beforeExecuteOperation: AsyncSeriesHook<[IOperationRunnerContext]>;
+    /**
+     * Hook invoked after executing a operation.
+     */
+    readonly afterExecuteOperation: AsyncSeriesHook<[IOperationRunnerContext]>;
     /**
      * Hook invoked after a run has finished and the command is watching for changes.
      * May be used to display additional relevant data to the user.
@@ -2624,6 +2900,8 @@ export declare class RushConfiguration {
     private _projects;
     private _projectsByName;
     private _projectsByTag;
+    private _filteredProjectsCache;
+    private _hasSplitWorkspaceProject;
     private _commonVersionsConfigurationsByVariant;
     /**
      * The name of the package manager being used to install dependencies
@@ -2678,6 +2956,12 @@ export declare class RushConfiguration {
      * Example: `C:\MyRepo\common\temp`
      */
     readonly 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`
+     */
+    readonly commonTempSplitFolder: string;
     /**
      * The folder where automation scripts are stored.  This is always a subfolder called "scripts"
      * under the common folder.
@@ -2732,6 +3016,21 @@ export declare class RushConfiguration {
      * or `C:\MyRepo\common\temp\pnpm-lock-preinstall.yaml`
      */
     readonly tempShrinkwrapPreinstallFilename: string;
+    /**
+     * The filename (without any path) of the shrinkwrap file for split workspace that is used by the package manager.
+     * @remarks
+     * This property merely reports the filename; the file itself may not actually exist.
+     * Example: `pnpm-lock.yaml`
+     */
+    readonly splitWorkspaceShrinkwrapFilename: 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`
+     */
+    readonly tempSplitWorkspaceShrinkwrapFilename: string;
     /**
      * The filename of the variant dependency data file.  By default this is
      * called 'current-variant.json' resides in the Rush common folder.
@@ -2987,6 +3286,11 @@ export declare class RushConfiguration {
      * @beta
      */
     get projectsByTag(): ReadonlyMap<string, ReadonlySet<RushConfigurationProject>>;
+    /**
+     * Search for projects according to filter
+     * @beta
+     */
+    getFilteredProjects(filter: IRushConfigurationProjectsFilter): RushConfigurationProject[];
     /**
      * Settings from the common-versions.json config file.
      * @remarks
@@ -3005,6 +3309,10 @@ export declare class RushConfiguration {
      * or "rush update".
      */
     get currentInstalledVariant(): string | undefined;
+    /**
+     * 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.
@@ -3037,6 +3345,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.
@@ -3072,6 +3385,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;
 }
 
 /**
@@ -3187,6 +3506,11 @@ export declare class RushConfigurationProject {
      * @beta
      */
     readonly tags: ReadonlySet<string>;
+    /**
+     * Whether this project is a split workspace project.
+     * @beta
+     */
+    readonly splitWorkspace: boolean;
     /** @internal */
     constructor(options: IRushConfigurationProjectOptions);
     /**
@@ -3296,6 +3620,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`
@@ -3401,6 +3731,15 @@ export declare class RushConstants {
      * Changing this ensures that cache entries generated by an old version will no longer register as a cache hit.
      */
     static readonly buildCacheVersion: number;
+    /**
+     * Cobuild configuration file.
+     */
+    static readonly cobuildFilename: string;
+    /**
+     * Cobuild version number, incremented when the logic to create cobuild lock changes.
+     * Changing this ensures that lock generated by an old version will no longer access as a cobuild lock.
+     */
+    static readonly cobuildLockVersion: number;
     /**
      * Per-project configuration filename.
      */
@@ -3566,12 +3905,15 @@ declare class RushPluginsConfiguration {
 export declare class RushSession {
     private readonly _options;
     private readonly _cloudBuildCacheProviderFactories;
+    private readonly _cobuildLockProviderFactories;
     readonly hooks: RushLifecycleHooks;
     constructor(options: IRushSessionOptions);
     getLogger(name: string): ILogger;
     get terminalProvider(): ITerminalProvider;
     registerCloudBuildCacheProviderFactory(cacheProviderName: string, factory: CloudBuildCacheProviderFactory): void;
     getCloudBuildCacheProviderFactory(cacheProviderName: string): CloudBuildCacheProviderFactory | undefined;
+    registerCobuildLockProviderFactory(cobuildLockProviderName: string, factory: CobuildLockProviderFactory): void;
+    getCobuildLockProviderFactory(cobuildLockProviderName: string): CobuildLockProviderFactory | undefined;
 }
 
 /**
@@ -3590,6 +3932,60 @@ export declare class RushUserConfiguration {
     static getRushUserFolderPath(): string;
 }
 
+/**
+ * Represents a typical timer/stopwatch which keeps track
+ * of elapsed time in between two events.
+ */
+declare class Stopwatch implements IStopwatchResult {
+    private _startTime;
+    private _endTime;
+    private _state;
+    private _getTime;
+    constructor(getTime?: () => number);
+    /**
+     * Static helper function which creates a stopwatch which is immediately started
+     */
+    static start(): Stopwatch;
+    get state(): StopwatchState;
+    /**
+     * Starts the stopwatch. Note that if end() has been called,
+     * reset() should be called before calling start() again.
+     */
+    start(): Stopwatch;
+    /**
+     * Stops executing the stopwatch and saves the current timestamp
+     */
+    stop(): Stopwatch;
+    /**
+     * Resets all values of the stopwatch back to the original
+     */
+    reset(): Stopwatch;
+    /**
+     * Displays how long the stopwatch has been executing in a human readable format.
+     */
+    toString(): string;
+    /**
+     * Get the duration in seconds.
+     */
+    get duration(): number;
+    /**
+     * Return the start time of the most recent stopwatch run.
+     */
+    get startTime(): number | undefined;
+    /**
+     * Return the end time of the most recent stopwatch run.
+     */
+    get endTime(): number | undefined;
+}
+
+/**
+ * Used with the Stopwatch class.
+ */
+declare enum StopwatchState {
+    Stopped = 1,
+    Started = 2
+}
+
 declare enum VersionFormatForCommit {
     wildcard = "wildcard",
     original = "original"