@rushstack/rush-sdk 5.96.0 → 5.97.1-pr3949

package/lib/api/EnvironmentConfiguration.d.ts

@@ -9,7 +9,7 @@ export interface IEnvironmentConfigurationInitializeOptions {
  * Names of environment variables used by Rush.
  * @beta
  */
-export declare enum EnvironmentVariableNames {
+export declare const EnvironmentVariableNames: {
     /**
      * This variable overrides the temporary folder used by Rush.
      * The default value is "common/temp" under the repository root.
@@ -17,43 +17,43 @@ export declare enum EnvironmentVariableNames {
      * @remarks This environment variable is not compatible with workspace installs. If attempting
      * to move the PNPM store path, see the `RUSH_PNPM_STORE_PATH` environment variable.
      */
-    RUSH_TEMP_FOLDER = "RUSH_TEMP_FOLDER",
+    readonly RUSH_TEMP_FOLDER: "RUSH_TEMP_FOLDER";
     /**
      * This variable overrides the version of Rush that will be installed by
      * the version selector.  The default value is determined by the "rushVersion"
      * field from rush.json.
      */
-    RUSH_PREVIEW_VERSION = "RUSH_PREVIEW_VERSION",
+    readonly RUSH_PREVIEW_VERSION: "RUSH_PREVIEW_VERSION";
     /**
      * If this variable is set to "1", Rush will not fail the build when running a version
      * of Node that does not match the criteria specified in the "nodeSupportedVersionRange"
      * field from rush.json.
      */
-    RUSH_ALLOW_UNSUPPORTED_NODEJS = "RUSH_ALLOW_UNSUPPORTED_NODEJS",
+    readonly RUSH_ALLOW_UNSUPPORTED_NODEJS: "RUSH_ALLOW_UNSUPPORTED_NODEJS";
     /**
      * Setting this environment variable overrides the value of `allowWarningsInSuccessfulBuild`
      * in the `command-line.json` configuration file. Specify `1` to allow warnings in a successful build,
      * or `0` to disallow them. (See the comments in the command-line.json file for more information).
      */
-    RUSH_ALLOW_WARNINGS_IN_SUCCESSFUL_BUILD = "RUSH_ALLOW_WARNINGS_IN_SUCCESSFUL_BUILD",
+    readonly RUSH_ALLOW_WARNINGS_IN_SUCCESSFUL_BUILD: "RUSH_ALLOW_WARNINGS_IN_SUCCESSFUL_BUILD";
     /**
      * This variable selects a specific installation variant for Rush to use when installing
      * and linking package dependencies.
      * For more information, see the command-line help for the `--variant` parameter
      * and this article:  https://rushjs.io/pages/advanced/installation_variants/
      */
-    RUSH_VARIANT = "RUSH_VARIANT",
+    readonly RUSH_VARIANT: "RUSH_VARIANT";
     /**
      * Specifies the maximum number of concurrent processes to launch during a build.
      * For more information, see the command-line help for the `--parallelism` parameter for "rush build".
      */
-    RUSH_PARALLELISM = "RUSH_PARALLELISM",
+    readonly RUSH_PARALLELISM: "RUSH_PARALLELISM";
     /**
      * If this variable is set to "1", Rush will create symlinks with absolute paths instead
      * of relative paths. This can be necessary when a repository is moved during a build or
      * if parts of a repository are moved into a sandbox.
      */
-    RUSH_ABSOLUTE_SYMLINKS = "RUSH_ABSOLUTE_SYMLINKS",
+    readonly RUSH_ABSOLUTE_SYMLINKS: "RUSH_ABSOLUTE_SYMLINKS";
     /**
      * When using PNPM as the package manager, this variable can be used to configure the path that
      * PNPM will use as the store directory.
@@ -61,18 +61,18 @@ export declare enum EnvironmentVariableNames {
      * If a relative path is used, then the store path will be resolved relative to the process's
      * current working directory.  An absolute path is recommended.
      */
-    RUSH_PNPM_STORE_PATH = "RUSH_PNPM_STORE_PATH",
+    readonly RUSH_PNPM_STORE_PATH: "RUSH_PNPM_STORE_PATH";
     /**
      * When using PNPM as the package manager, this variable can be used to control whether or not PNPM
      * validates the integrity of the PNPM store during installation. The value of this environment variable must be
      * `1` (for true) or `0` (for false). If not specified, defaults to the value in .npmrc.
      */
-    RUSH_PNPM_VERIFY_STORE_INTEGRITY = "RUSH_PNPM_VERIFY_STORE_INTEGRITY",
+    readonly RUSH_PNPM_VERIFY_STORE_INTEGRITY: "RUSH_PNPM_VERIFY_STORE_INTEGRITY";
     /**
      * This environment variable can be used to specify the `--target-folder` parameter
      * for the "rush deploy" command.
      */
-    RUSH_DEPLOY_TARGET_FOLDER = "RUSH_DEPLOY_TARGET_FOLDER",
+    readonly RUSH_DEPLOY_TARGET_FOLDER: "RUSH_DEPLOY_TARGET_FOLDER";
     /**
      * Overrides the location of the `~/.rush` global folder where Rush stores temporary files.
      *
@@ -89,7 +89,7 @@ export declare enum EnvironmentVariableNames {
      *
      * POSIX is a registered trademark of the Institute of Electrical and Electronic Engineers, Inc.
      */
-    RUSH_GLOBAL_FOLDER = "RUSH_GLOBAL_FOLDER",
+    readonly RUSH_GLOBAL_FOLDER: "RUSH_GLOBAL_FOLDER";
     /**
      * Provides a credential for a remote build cache, if configured.  This credential overrides any cached credentials.
      *
@@ -103,7 +103,7 @@ export declare enum EnvironmentVariableNames {
      *
      * For information on SAS tokens, see here: https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview
      */
-    RUSH_BUILD_CACHE_CREDENTIAL = "RUSH_BUILD_CACHE_CREDENTIAL",
+    readonly RUSH_BUILD_CACHE_CREDENTIAL: "RUSH_BUILD_CACHE_CREDENTIAL";
     /**
      * Setting this environment variable overrides the value of `buildCacheEnabled` in the `build-cache.json`
      * configuration file.
@@ -113,26 +113,49 @@ export declare enum EnvironmentVariableNames {
      *
      * If there is no build cache configured, then this environment variable is ignored.
      */
-    RUSH_BUILD_CACHE_ENABLED = "RUSH_BUILD_CACHE_ENABLED",
+    readonly RUSH_BUILD_CACHE_ENABLED: "RUSH_BUILD_CACHE_ENABLED";
     /**
      * 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",
+    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.
      */
-    RUSH_GIT_BINARY_PATH = "RUSH_GIT_BINARY_PATH",
+    readonly RUSH_GIT_BINARY_PATH: "RUSH_GIT_BINARY_PATH";
     /**
      * Explicitly specifies the path for the `tar` binary that is invoked by certain Rush operations.
      */
-    RUSH_TAR_BINARY_PATH = "RUSH_TAR_BINARY_PATH",
+    readonly RUSH_TAR_BINARY_PATH: "RUSH_TAR_BINARY_PATH";
     /**
      * Internal variable that explicitly specifies the path for the version of `@microsoft/rush-lib` being executed.
      * Will be set upon loading Rush.
      */
-    RUSH_LIB_PATH = "_RUSH_LIB_PATH",
+    readonly RUSH_LIB_PATH: "_RUSH_LIB_PATH";
     /**
      * When Rush executes shell scripts, it sometimes changes the working directory to be a project folder or
      * the repository root folder.  The original working directory (where the Rush command was invoked) is assigned
@@ -142,8 +165,8 @@ export declare enum EnvironmentVariableNames {
      * The `RUSH_INVOKED_FOLDER` variable is the same idea as the `INIT_CWD` variable that package managers
      * assign when they execute lifecycle scripts.
      */
-    RUSH_INVOKED_FOLDER = "RUSH_INVOKED_FOLDER"
-}
+    readonly RUSH_INVOKED_FOLDER: "RUSH_INVOKED_FOLDER";
+};
 /**
  * Provides Rush-specific environment variable data. All Rush environment variables must start with "RUSH_". This class
  * is designed to be used by RushConfiguration.
@@ -164,6 +187,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;
     /**
@@ -219,6 +245,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}

package/lib/index.d.ts

@@ -9,6 +9,7 @@ export { INpmOptionsJson as _INpmOptionsJson, NpmOptionsConfiguration } from './
 export { IYarnOptionsJson as _IYarnOptionsJson, YarnOptionsConfiguration } from './logic/yarn/YarnOptionsConfiguration';
 export { IPnpmOptionsJson as _IPnpmOptionsJson, PnpmStoreOptions, PnpmOptionsConfiguration } from './logic/pnpm/PnpmOptionsConfiguration';
 export { BuildCacheConfiguration } from './api/BuildCacheConfiguration';
+export { CobuildConfiguration, ICobuildJson } from './api/CobuildConfiguration';
 export { GetCacheEntryIdFunction, IGenerateCacheEntryIdOptions } from './logic/buildCache/CacheEntryId';
 export { FileSystemBuildCacheProvider, IFileSystemBuildCacheProviderOptions } from './logic/buildCache/FileSystemBuildCacheProvider';
 export { IPhase } from './api/CommandLineConfiguration';
@@ -36,7 +37,7 @@ export { IOperationRunner, IOperationRunnerContext } from './logic/operations/IO
 export { IExecutionResult, IOperationExecutionResult } from './logic/operations/IOperationExecutionResult';
 export { IOperationOptions, Operation } from './logic/operations/Operation';
 export { OperationStatus } from './logic/operations/OperationStatus';
-export { RushSession, IRushSessionOptions, CloudBuildCacheProviderFactory } from './pluginFramework/RushSession';
+export { RushSession, IRushSessionOptions, CloudBuildCacheProviderFactory, CobuildLockProviderFactory } from './pluginFramework/RushSession';
 export { IRushCommand, IGlobalCommand, IPhasedCommand, RushLifecycleHooks } from './pluginFramework/RushLifeCycle';
 export { ICreateOperationsContext, PhasedCommandHooks } from './pluginFramework/PhasedCommandHooks';
 export { IRushPlugin } from './pluginFramework/IRushPlugin';
@@ -44,6 +45,7 @@ export { IBuiltInPluginConfiguration as _IBuiltInPluginConfiguration } from './p
 export { IRushPluginConfigurationBase as _IRushPluginConfigurationBase } from './api/RushPluginsConfiguration';
 export { ILogger } from './pluginFramework/logging/Logger';
 export { ICloudBuildCacheProvider } from './logic/buildCache/ICloudBuildCacheProvider';
+export { ICobuildLockProvider, ICobuildContext, ICobuildCompletedState } from './logic/cobuild/ICobuildLockProvider';
 export { ICredentialCacheOptions, ICredentialCacheEntry, CredentialCache } from './logic/CredentialCache';
 export type { ITelemetryData, ITelemetryMachineInfo, ITelemetryOperationResult } from './logic/Telemetry';
 export { IStopwatchResult } from './utilities/Stopwatch';

package/lib/logic/RushConstants.d.ts

@@ -148,6 +148,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.
      */

package/lib/logic/buildCache/ProjectBuildCache.d.ts

@@ -1,10 +1,10 @@
 import { ITerminal } from '@rushstack/node-core-library';
+import { RushConfigurationProject } from '../../api/RushConfigurationProject';
 import { ProjectChangeAnalyzer } from '../ProjectChangeAnalyzer';
-import { RushProjectConfiguration } from '../../api/RushProjectConfiguration';
 import { BuildCacheConfiguration } from '../../api/BuildCacheConfiguration';
 export interface IProjectBuildCacheOptions {
     buildCacheConfiguration: BuildCacheConfiguration;
-    projectConfiguration: RushProjectConfiguration;
+    project: RushConfigurationProject;
     projectOutputFolderNames: ReadonlyArray<string>;
     additionalProjectOutputFilePaths?: ReadonlyArray<string>;
     additionalContext?: Record<string, string>;
@@ -30,10 +30,11 @@ export declare class ProjectBuildCache {
     private _cacheId;
     private constructor();
     private static _tryGetTarUtility;
+    get cacheId(): string | undefined;
     static tryGetProjectBuildCache(options: IProjectBuildCacheOptions): Promise<ProjectBuildCache | undefined>;
     private static _validateProject;
-    tryRestoreFromCacheAsync(terminal: ITerminal): Promise<boolean>;
-    trySetCacheEntryAsync(terminal: ITerminal): Promise<boolean>;
+    tryRestoreFromCacheAsync(terminal: ITerminal, specifiedCacheId?: string): Promise<boolean>;
+    trySetCacheEntryAsync(terminal: ITerminal, specifiedCacheId?: string): Promise<boolean>;
     /**
      * Walks the declared output folders of the project and collects a list of files.
      * @returns The list of output files as project-relative paths, or `undefined` if a

package/lib/logic/cobuild/CobuildLock.d.ts

@@ -0,0 +1,24 @@
+import type { CobuildConfiguration } from '../../api/CobuildConfiguration';
+import type { ProjectBuildCache } from '../buildCache/ProjectBuildCache';
+import type { OperationStatus } from '../operations/OperationStatus';
+import type { ICobuildContext } from './ICobuildLockProvider';
+export interface ICobuildLockOptions {
+    cobuildConfiguration: CobuildConfiguration;
+    projectBuildCache: ProjectBuildCache;
+}
+export interface ICobuildCompletedState {
+    status: OperationStatus.Success | OperationStatus.SuccessWithWarning | OperationStatus.Failure;
+    cacheId: string;
+}
+export declare class CobuildLock {
+    readonly projectBuildCache: ProjectBuildCache;
+    readonly cobuildConfiguration: CobuildConfiguration;
+    private _cobuildContext;
+    constructor(options: ICobuildLockOptions);
+    setCompletedStateAsync(state: ICobuildCompletedState): Promise<void>;
+    getCompletedStateAsync(): Promise<ICobuildCompletedState | undefined>;
+    tryAcquireLockAsync(): Promise<boolean>;
+    renewLockAsync(): Promise<void>;
+    get cobuildContext(): ICobuildContext;
+}
+//# sourceMappingURL=CobuildLock.d.ts.map

package/lib/logic/cobuild/CobuildLock.js

@@ -0,0 +1 @@
+module.exports = require("../../../lib-shim/index")._rushSdk_loadInternalModule("logic/cobuild/CobuildLock");

package/lib/logic/cobuild/ICobuildLockProvider.d.ts

@@ -0,0 +1,46 @@
+import type { OperationStatus } from '../operations/OperationStatus';
+/**
+ * @beta
+ */
+export 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 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 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>;
+}
+//# sourceMappingURL=ICobuildLockProvider.d.ts.map

package/lib/logic/cobuild/ICobuildLockProvider.js

@@ -0,0 +1 @@
+module.exports = require("../../../lib-shim/index")._rushSdk_loadInternalModule("logic/cobuild/ICobuildLockProvider");

package/lib/logic/operations/AsyncOperationQueue.d.ts

@@ -1,6 +1,16 @@
 import { OperationExecutionRecord } from './OperationExecutionRecord';
 /**
- * Implmentation of the async iteration protocol for a collection of IOperation objects.
+ * When the queue returns an unassigned operation, it means there is at least one remote executing operation,
+ * at this time, the caller has a chance to make a decision:
+ * 1. Manually invoke `tryGetRemoteExecutingOperation()` to get the remote executing operation.
+ * 2. If there is no remote executing operation available, wait for some time and return in callback, which
+ * internally invoke `assignOperations()` to assign new operations.
+ * NOTE: the caller must wait for some time to avoid busy loop and burn CPU cycles.
+ */
+export declare const UNASSIGNED_OPERATION: 'UNASSIGNED_OPERATION';
+export declare type IOperationIteratorResult = OperationExecutionRecord | typeof UNASSIGNED_OPERATION;
+/**
+ * Implementation of the async iteration protocol for a collection of IOperation objects.
  * The async iterator will wait for an operation to be ready for execution, or terminate if there are no more operations.
  *
  * @remarks
@@ -8,9 +18,12 @@ import { OperationExecutionRecord } from './OperationExecutionRecord';
  * it must manually invoke `assignOperations()` after performing the updates, otherwise iterators will
  * stall until another operations completes.
  */
-export declare class AsyncOperationQueue implements AsyncIterable<OperationExecutionRecord>, AsyncIterator<OperationExecutionRecord> {
+export declare class AsyncOperationQueue implements AsyncIterable<IOperationIteratorResult>, AsyncIterator<IOperationIteratorResult> {
     private readonly _queue;
     private readonly _pendingIterators;
+    private readonly _totalOperations;
+    private readonly _completedOperations;
+    private _isDone;
     /**
      * @param operations - The set of operations to be executed
      * @param sortFn - A function that sorts operations in reverse priority order:
@@ -23,17 +36,23 @@ export declare class AsyncOperationQueue implements AsyncIterable<OperationExecu
      * For use with `for await (const operation of taskQueue)`
      * @see {AsyncIterator}
      */
-    next(): Promise<IteratorResult<OperationExecutionRecord>>;
+    next(): Promise<IteratorResult<IOperationIteratorResult>>;
+    /**
+     * Set a callback to be invoked when one operation is completed.
+     * If all operations are completed, set the queue to done, resolve all pending iterators in next cycle.
+     */
+    complete(record: OperationExecutionRecord): void;
     /**
      * Routes ready operations with 0 dependencies to waiting iterators. Normally invoked as part of `next()`, but
      * if the caller does not update operation dependencies prior to calling `next()`, may need to be invoked manually.
      */
     assignOperations(): void;
+    tryGetRemoteExecutingOperation(): OperationExecutionRecord | undefined;
     /**
      * Returns this queue as an async iterator, such that multiple functions iterating this object concurrently
      * receive distinct iteration results.
      */
-    [Symbol.asyncIterator](): AsyncIterator<OperationExecutionRecord>;
+    [Symbol.asyncIterator](): AsyncIterator<IOperationIteratorResult>;
 }
 export interface IOperationSortFunction {
     /**

package/lib/logic/operations/CacheableOperationPlugin.d.ts

@@ -0,0 +1,21 @@
+import { CobuildLock } from '../cobuild/CobuildLock';
+import { ProjectBuildCache } from '../buildCache/ProjectBuildCache';
+import type { IPhasedCommandPlugin, PhasedCommandHooks } from '../../pluginFramework/PhasedCommandHooks';
+export interface IOperationBuildCacheContext {
+    isCacheWriteAllowed: boolean;
+    isCacheReadAllowed: boolean;
+    isSkipAllowed: boolean;
+    projectBuildCache: ProjectBuildCache | undefined;
+    cobuildLock: CobuildLock | undefined;
+}
+export declare class CacheableOperationPlugin implements IPhasedCommandPlugin {
+    private _buildCacheContextByOperationRunner;
+    apply(hooks: PhasedCommandHooks): void;
+    private _applyShellOperationRunner;
+    private _getBuildCacheContextByRunner;
+    private _getBuildCacheContextByRunnerOrThrow;
+    private _tryGetProjectBuildCacheAsync;
+    private _tryGetLogOnlyProjectBuildCacheAsync;
+    private _tryGetCobuildLockAsync;
+}
+//# sourceMappingURL=CacheableOperationPlugin.d.ts.map

package/lib/logic/operations/CacheableOperationPlugin.js

@@ -0,0 +1 @@
+module.exports = require("../../../lib-shim/index")._rushSdk_loadInternalModule("logic/operations/CacheableOperationPlugin");

package/lib/logic/operations/IOperationRunner.d.ts

@@ -2,7 +2,7 @@ import type { StdioSummarizer } from '@rushstack/terminal';
 import type { CollatedWriter } from '@rushstack/stream-collator';
 import type { OperationStatus } from './OperationStatus';
 import type { OperationMetadataManager } from './OperationMetadataManager';
-import type { IStopwatchResult } from '../../utilities/Stopwatch';
+import type { Stopwatch } from '../../utilities/Stopwatch';
 /**
  * Information passed to the executing `IOperationRunner`
  *
@@ -34,7 +34,34 @@ export 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;
 }
 /**
  * The `Operation` class is a node in the dependency graph of work that needs to be scheduled by the
@@ -48,10 +75,6 @@ export 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.
      */
@@ -65,10 +88,6 @@ export 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.
      */

package/lib/logic/operations/OperationExecutionManager.d.ts

@@ -8,6 +8,8 @@ export interface IOperationExecutionManagerOptions {
     parallelism: number;
     changedProjectsOnly: boolean;
     destination?: TerminalWritable;
+    beforeExecuteOperation?: (operation: OperationExecutionRecord) => Promise<void>;
+    afterExecuteOperation?: (operation: OperationExecutionRecord) => Promise<void>;
     onOperationStatusChanged?: (record: OperationExecutionRecord) => void;
     beforeExecuteOperations?: (records: Map<Operation, OperationExecutionRecord>) => Promise<void>;
 }
@@ -27,11 +29,14 @@ export declare class OperationExecutionManager {
     private readonly _colorsNewlinesTransform;
     private readonly _streamCollator;
     private readonly _terminal;
+    private readonly _beforeExecuteOperation?;
+    private readonly _afterExecuteOperation?;
     private readonly _onOperationStatusChanged?;
     private readonly _beforeExecuteOperations?;
     private _hasAnyFailures;
     private _hasAnyNonAllowedWarnings;
     private _completedOperations;
+    private _executionQueue;
     constructor(operations: Set<Operation>, options: IOperationExecutionManagerOptions);
     private _streamCollator_onWriterActive;
     /**

package/lib/logic/operations/OperationExecutionRecord.d.ts

@@ -10,9 +10,12 @@ export interface IOperationExecutionRecordContext {
     onOperationStatusChanged?: (record: OperationExecutionRecord) => void;
     debugMode: boolean;
     quietMode: boolean;
+    changedProjectsOnly: boolean;
 }
 /**
  * Internal class representing everything about executing an operation
+ *
+ * @internal
  */
 export declare class OperationExecutionRecord implements IOperationRunnerContext {
     /**
@@ -37,6 +40,7 @@ export declare class OperationExecutionRecord implements IOperationRunnerContext
      * operation to execute, the operation with the highest criticalPathLength is chosen.
      *
      * Example:
+     * ```
      *        (0) A
      *             \
      *          (1) B     C (0)         (applications)
@@ -53,6 +57,7 @@ export declare class OperationExecutionRecord implements IOperationRunnerContext
      * X has a score of 1, since the only package which depends on it is A
      * Z has a score of 2, since only X depends on it, and X has a score of 1
      * Y has a score of 2, since the chain Y->X->C is longer than Y->C
+     * ```
      *
      * The algorithm is implemented in AsyncOperationQueue.ts as calculateCriticalPathLength()
      */
@@ -76,8 +81,9 @@ export declare class OperationExecutionRecord implements IOperationRunnerContext
     get name(): string;
     get debugMode(): boolean;
     get quietMode(): boolean;
+    get changedProjectsOnly(): boolean;
     get collatedWriter(): CollatedWriter;
     get nonCachedDurationMs(): number | undefined;
-    executeAsync(onResult: (record: OperationExecutionRecord) => void): Promise<void>;
+    executeAsync(onResult: (record: OperationExecutionRecord) => Promise<void>): Promise<void>;
 }
 //# sourceMappingURL=OperationExecutionRecord.d.ts.map

package/lib/logic/operations/OperationRunnerHooks.d.ts

@@ -0,0 +1,50 @@
+import { AsyncSeriesWaterfallHook } from 'tapable';
+import type { ITerminal } from '@rushstack/node-core-library';
+import type { IOperationRunnerContext } from './IOperationRunner';
+import type { OperationStatus } from './OperationStatus';
+import type { IProjectDeps, ShellOperationRunner } from './ShellOperationRunner';
+import type { RushConfigurationProject } from '../../api/RushConfigurationProject';
+import type { IPhase } from '../../api/CommandLineConfiguration';
+/**
+ * A plugin tht interacts with a operation runner
+ */
+export interface IOperationRunnerPlugin {
+    /**
+     * Applies this plugin.
+     */
+    apply(hooks: OperationRunnerHooks): void;
+}
+export interface IOperationRunnerBeforeExecuteContext {
+    context: IOperationRunnerContext;
+    runner: ShellOperationRunner;
+    earlyReturnStatus: OperationStatus | undefined;
+    terminal: ITerminal;
+    projectDeps: IProjectDeps | undefined;
+    lastProjectDeps: IProjectDeps | undefined;
+    trackedProjectFiles: string[] | undefined;
+    logPath: string;
+    errorLogPath: string;
+    rushProject: RushConfigurationProject;
+    phase: IPhase;
+    commandName: string;
+    commandToRun: string;
+}
+export interface IOperationRunnerAfterExecuteContext {
+    context: IOperationRunnerContext;
+    terminal: ITerminal;
+    /**
+     * Exit code of the operation command
+     */
+    exitCode: number;
+    status: OperationStatus;
+    taskIsSuccessful: boolean;
+}
+/**
+ * Hooks into the lifecycle of the operation runner
+ *
+ */
+export declare class OperationRunnerHooks {
+    beforeExecute: AsyncSeriesWaterfallHook<IOperationRunnerBeforeExecuteContext>;
+    afterExecute: AsyncSeriesWaterfallHook<IOperationRunnerAfterExecuteContext>;
+}
+//# sourceMappingURL=OperationRunnerHooks.d.ts.map

package/lib/logic/operations/OperationRunnerHooks.js

@@ -0,0 +1 @@
+module.exports = require("../../../lib-shim/index")._rushSdk_loadInternalModule("logic/operations/OperationRunnerHooks");

package/lib/logic/operations/OperationStatus.d.ts

@@ -7,10 +7,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
      */

package/lib/logic/operations/PeriodicCallback.d.ts

@@ -0,0 +1,20 @@
+export declare type ICallbackFn = () => Promise<void> | void;
+export interface IPeriodicCallbackOptions {
+    interval: number;
+}
+/**
+ * A help class to run callbacks in a loop with a specified interval.
+ *
+ * @beta
+ */
+export declare class PeriodicCallback {
+    private _callbacks;
+    private _interval;
+    private _intervalId;
+    private _isRunning;
+    constructor(options: IPeriodicCallbackOptions);
+    addCallback(callback: ICallbackFn): void;
+    start(): void;
+    stop(): void;
+}
+//# sourceMappingURL=PeriodicCallback.d.ts.map