@rushstack/rush-sdk 5.63.1 → 5.64.0

package/dist/rush-lib.d.ts

@@ -6,12 +6,17 @@
 /// <reference types="node" />
 
 import { AsyncSeriesHook } from 'tapable';
+import { AsyncSeriesWaterfallHook } from 'tapable';
+import type { CollatedWriter } from '@rushstack/stream-collator';
+import type { CommandLineParameter } from '@rushstack/ts-command-line';
 import { HookMap } from 'tapable';
 import { IPackageJson } from '@rushstack/node-core-library';
 import { ITerminal } from '@rushstack/node-core-library';
 import { ITerminalProvider } from '@rushstack/node-core-library';
 import { JsonObject } from '@rushstack/node-core-library';
 import { PackageNameParser } from '@rushstack/node-core-library';
+import type { StdioSummarizer } from '@rushstack/terminal';
+import { SyncHook } from 'tapable';
 import { Terminal } from '@rushstack/node-core-library';
 
 /**
@@ -130,6 +135,52 @@ export declare class ApprovedPackagesPolicy {
     get nonbrowserApprovedPackages(): ApprovedPackagesConfiguration;
 }
 
+/**
+ * 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.
+ * @beta
+ */
+export declare class BuildCacheConfiguration {
+    private static _jsonSchema;
+    /**
+     * Indicates whether the build cache feature is enabled.
+     * Typically it is enabled in the build-cache.json config file.
+     */
+    readonly buildCacheEnabled: boolean;
+    /**
+     * Indicates whether or not writing to the cache is enabled.
+     */
+    cacheWriteEnabled: boolean;
+    /**
+     * Method to calculate the cache entry id for a project, phase, and project state.
+     */
+    readonly getCacheEntryId: GetCacheEntryIdFunction;
+    /**
+     * The provider for interacting with the local build cache.
+     */
+    readonly localCacheProvider: FileSystemBuildCacheProvider;
+    /**
+     * The provider for interacting with the cloud build cache, if configured.
+     */
+    readonly cloudCacheProvider: ICloudBuildCacheProvider | undefined;
+    private constructor();
+    /**
+     * Attempts to load the build-cache.json data from the standard file path `common/config/rush/build-cache.json`.
+     * If the file has not been created yet, then undefined is returned.
+     */
+    static tryLoadAsync(terminal: ITerminal, rushConfiguration: RushConfiguration, rushSession: RushSession): Promise<BuildCacheConfiguration | undefined>;
+    /**
+     * Loads the build-cache.json data from the standard file path `common/config/rush/build-cache.json`.
+     * If the file has not been created yet, or if the feature is not enabled, then an error is reported.
+     */
+    static loadAndRequireEnabledAsync(terminal: ITerminal, rushConfiguration: RushConfiguration, rushSession: RushSession): Promise<BuildCacheConfiguration>;
+    /**
+     * Gets the absolute path to the build-cache.json file in the specified rush workspace.
+     */
+    static getBuildCacheConfigFilePath(rushConfiguration: RushConfiguration): string;
+    private static _loadAsync;
+}
+
 /**
  * Type of version bumps
  * @public
@@ -582,6 +633,34 @@ export declare class ExperimentsConfiguration {
     get configuration(): Readonly<IExperimentsJson>;
 }
 
+/**
+ * A build cache provider using the local file system.
+ * Required by all cloud cache providers.
+ * @beta
+ */
+export declare class FileSystemBuildCacheProvider {
+    private readonly _cacheFolderPath;
+    constructor(options: IFileSystemBuildCacheProviderOptions);
+    /**
+     * Returns the absolute disk path for the specified cache id.
+     */
+    getCacheEntryPath(cacheId: string): string;
+    /**
+     * Validates that the specified cache id exists on disk, and returns the path if it does.
+     */
+    tryGetCacheEntryPathByIdAsync(terminal: ITerminal, cacheId: string): Promise<string | undefined>;
+    /**
+     * Writes the specified buffer to the corresponding file system path for the cache id.
+     */
+    trySetCacheEntryBufferAsync(terminal: ITerminal, cacheId: string, entryBuffer: Buffer): Promise<string>;
+}
+
+/**
+ * Calculates the cache entry id string for an operation.
+ * @beta
+ */
+export declare type GetCacheEntryIdFunction = (options: IGenerateCacheEntryIdOptions) => string;
+
 /**
  * Part of IRushConfigurationJson.
  */
@@ -659,6 +738,52 @@ export declare interface IConfigurationEnvironmentVariable {
     override?: boolean;
 }
 
+/**
+ * Context used for creating operations to be executed.
+ * @alpha
+ */
+export declare interface ICreateOperationsContext {
+    /**
+     * The configuration for the build cache, if the feature is enabled.
+     */
+    readonly buildCacheConfiguration: BuildCacheConfiguration | 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.
+     */
+    readonly customParameters: ReadonlyMap<string, CommandLineParameter>;
+    /**
+     * If true, projects may read their output from cache or be skipped if already up to date.
+     * If false, neither of the above may occur, e.g. "rush rebuild"
+     */
+    readonly isIncrementalBuildAllowed: boolean;
+    /**
+     * If true, this is the initial run of the command.
+     * If false, this execution is in response to changes.
+     */
+    readonly isInitial: boolean;
+    /**
+     * If true, the command is running in watch mode.
+     */
+    readonly isWatch: boolean;
+    /**
+     * The set of phases selected for the current command execution.
+     */
+    readonly phaseSelection: ReadonlySet<IPhase>;
+    /**
+     * The current state of the repository
+     */
+    readonly projectChangeAnalyzer: ProjectChangeAnalyzer;
+    /**
+     * The set of Rush projects selected for the current command execution.
+     */
+    readonly projectSelection: ReadonlySet<RushConfigurationProject>;
+    /**
+     * The Rush configuration
+     */
+    readonly rushConfiguration: RushConfiguration;
+}
+
 /**
  * @beta
  */
@@ -735,6 +860,40 @@ export declare interface IExperimentsJson {
     phasedCommands?: boolean;
 }
 
+/**
+ * Options for creating a file system build cache provider.
+ * @beta
+ */
+export declare interface IFileSystemBuildCacheProviderOptions {
+    /**
+     * The workspace Rush configuration
+     */
+    rushConfiguration: RushConfiguration;
+    /**
+     * The user Rush configuration
+     */
+    rushUserConfiguration: RushUserConfiguration;
+}
+
+/**
+ * Options for generating the cache id for an operation.
+ * @beta
+ */
+export declare interface IGenerateCacheEntryIdOptions {
+    /**
+     * The name of the project
+     */
+    projectName: string;
+    /**
+     * The name of the phase
+     */
+    phaseName: string;
+    /**
+     * A hash of the input files
+     */
+    projectStateHash: string;
+}
+
 /**
  * @beta
  */
@@ -869,6 +1028,89 @@ export declare class IndividualVersionPolicy extends VersionPolicy {
 export declare interface _INpmOptionsJson extends IPackageManagerOptionsJsonBase {
 }
 
+/**
+ * Options for constructing a new Operation.
+ * @alpha
+ */
+export declare interface IOperationOptions {
+    /**
+     * The Rush phase associated with this Operation, if any
+     */
+    phase?: IPhase | undefined;
+    /**
+     * The Rush project associated with this Operation, if any
+     */
+    project?: RushConfigurationProject | undefined;
+    /**
+     * When the scheduler is ready to process this `Operation`, the `runner` implements the actual work of
+     * running the operation.
+     */
+    runner?: IOperationRunner | undefined;
+}
+
+/**
+ * The `Operation` class is a node in the dependency graph of work that needs to be scheduled by the
+ * `OperationExecutionManager`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
+ * implementation manages the actual process for running a single operation.
+ *
+ * @beta
+ */
+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.
+     */
+    reportTiming: boolean;
+    /**
+     * Indicates that this runner is architectural and should not be reported on.
+     */
+    silent: boolean;
+    /**
+     * If set to true, a warning result should not make Rush exit with a nonzero
+     * 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.
+     */
+    executeAsync(context: IOperationRunnerContext): Promise<OperationStatus>;
+}
+
+/**
+ * Information passed to the executing `IOperationRunner`
+ *
+ * @beta
+ */
+export declare interface IOperationRunnerContext {
+    /**
+     * The writer into which this `IOperationRunner` should write its logs.
+     */
+    collatedWriter: CollatedWriter;
+    /**
+     * If Rush was invoked with `--debug`
+     */
+    debugMode: boolean;
+    /**
+     * Defaults to `true`. Will be `false` if Rush was invoked with `--verbose`.
+     */
+    quietMode: boolean;
+    /**
+     * Object used to report a summary at the end of the Rush invocation.
+     */
+    stdioSummarizer: StdioSummarizer;
+}
+
 /**
  * Options for the package manager.
  * @public
@@ -880,11 +1122,57 @@ export declare interface IPackageManagerOptionsJsonBase {
     environmentVariables?: IConfigurationEnvironment;
 }
 
+/**
+ * Metadata about a phase.
+ * @alpha
+ */
+export declare interface IPhase {
+    /**
+     * The name of this phase.
+     */
+    name: string;
+    /**
+     * If set to "true," this this phase was generated from a bulk command, and
+     * was not explicitly defined in the command-line.json file.
+     */
+    isSynthetic: boolean;
+    /**
+     * This property is used in the name of the filename for the logs generated by this
+     * phase. This is a filesystem-safe version of the phase name. For example,
+     * a phase with name "_phase:compile" has a `logFilenameIdentifier` of "_phase_compile".
+     */
+    logFilenameIdentifier: string;
+    /**
+     * The set of custom command line parameters that are relevant to this phase.
+     */
+    associatedParameters: Set<CommandLineParameter>;
+    /**
+     * The resolved dependencies of the phase
+     */
+    dependencies: {
+        self: Set<IPhase>;
+        upstream: Set<IPhase>;
+    };
+    /**
+     * Normally Rush requires that each project's package.json has a \"scripts\" entry matching the phase name. To disable this check, set \"ignoreMissingScript\" to true.
+     */
+    ignoreMissingScript: boolean;
+    /**
+     * By default, Rush returns a nonzero exit code if errors or warnings occur during a command. If this option is set to \"true\", Rush will return a zero exit code if warnings occur during the execution of this phase.
+     */
+    allowWarningsOnSuccess: boolean;
+}
+
 /**
  * Information about the currently executing phased script command (as defined in command-line.json, or default "build" or "rebuild") provided to plugins.
  * @beta
  */
 export declare interface IPhasedCommand extends IRushCommand {
+    /**
+     * Hooks into the execution of the current phased command
+     * @alpha
+     */
+    readonly hooks: PhasedCommandHooks;
 }
 
 /**
@@ -1321,6 +1609,91 @@ export declare class NpmOptionsConfiguration extends PackageManagerOptionsConfig
     constructor(json: _INpmOptionsJson);
 }
 
+/**
+ * The `Operation` class is a node in the dependency graph of work that needs to be scheduled by the
+ * `OperationExecutionManager`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
+ * implementation manages the actual process of running a single operation.
+ *
+ * The graph of `Operation` instances will be cloned into a separate execution graph after processing.
+ *
+ * @alpha
+ */
+export declare class Operation {
+    /**
+     * The Rush phase associated with this Operation, if any
+     */
+    readonly associatedPhase: IPhase | undefined;
+    /**
+     * The Rush project associated with this Operation, if any
+     */
+    readonly associatedProject: RushConfigurationProject | undefined;
+    /**
+     * A set of all dependencies which must be executed before this operation is complete.
+     */
+    readonly dependencies: Set<Operation>;
+    /**
+     * When the scheduler is ready to process this `Operation`, the `runner` implements the actual work of
+     * running the operation.
+     */
+    runner: IOperationRunner | undefined;
+    /**
+     * The weight for this operation. This scalar is the contribution of this operation to the
+     * `criticalPathLength` calculation above. Modify to indicate the following:
+     * - `weight` === 1: indicates that this operation has an average duration
+     * - `weight` &gt; 1: indicates that this operation takes longer than average and so the scheduler
+     *     should try to favor starting it over other, shorter operations. An example might be an operation that
+     *     bundles an entire application and runs whole-program optimization.
+     * - `weight` &lt; 1: indicates that this operation takes less time than average and so the scheduler
+     *     should favor other, longer operations over it. An example might be an operation to unpack a cached
+     *     output, or an operation using NullOperationRunner, which might use a value of 0.
+     */
+    weight: number;
+    constructor(options?: IOperationOptions);
+    /**
+     * The name of this operation, for logging.
+     */
+    get name(): string | undefined;
+}
+
+/**
+ * Enumeration defining potential states of an operation
+ * @beta
+ */
+export declare enum OperationStatus {
+    /**
+     * The Operation is on the queue, ready to execute (but may be waiting for dependencies)
+     */
+    Ready = "READY",
+    /**
+     * The Operation is currently executing
+     */
+    Executing = "EXECUTING",
+    /**
+     * The Operation completed successfully and did not write to standard output
+     */
+    Success = "SUCCESS",
+    /**
+     * The Operation completed successfully, but wrote to standard output
+     */
+    SuccessWithWarning = "SUCCESS WITH WARNINGS",
+    /**
+     * The Operation was skipped via the legacy incremental build logic
+     */
+    Skipped = "SKIPPED",
+    /**
+     * The Operation had its outputs restored from the build cache
+     */
+    FromCache = "FROM CACHE",
+    /**
+     * The Operation failed
+     */
+    Failure = "FAILURE",
+    /**
+     * The Operation could not be executed because one or more of its dependencies failed
+     */
+    Blocked = "BLOCKED"
+}
+
 /**
  * @public
  */
@@ -1434,6 +1807,24 @@ export declare abstract class PackageManagerOptionsConfigurationBase implements
     protected constructor(json: IPackageManagerOptionsJsonBase);
 }
 
+/**
+ * Hooks into the execution process for phased commands
+ * @alpha
+ */
+export declare class PhasedCommandHooks {
+    /**
+     * Hook invoked to create operations for execution.
+     * Use the context to distinguish between the initial run and phased runs.
+     */
+    readonly createOperations: AsyncSeriesWaterfallHook<[Set<Operation>, ICreateOperationsContext]>;
+    /**
+     * 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.
+     * Only relevant when running in watch mode.
+     */
+    readonly waitingForChanges: SyncHook<void>;
+}
+
 /**
  * Options that are only used when the PNPM package manager is selected.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rushstack/rush-sdk",
-  "version": "5.63.1",
+  "version": "5.64.0",
   "description": "An API for interacting with the Rush engine",
   "repository": {
     "type": "git",
@@ -17,10 +17,13 @@
     "tapable": "2.2.1"
   },
   "devDependencies": {
-    "@microsoft/rush-lib": "5.63.1",
+    "@microsoft/rush-lib": "5.64.0",
     "@rushstack/eslint-config": "2.5.2",
-    "@rushstack/heft": "0.44.4",
-    "@rushstack/heft-node-rig": "1.8.2",
+    "@rushstack/heft": "0.44.5",
+    "@rushstack/heft-node-rig": "1.8.3",
+    "@rushstack/stream-collator": "4.0.160",
+    "@rushstack/ts-command-line": "4.10.7",
+    "@rushstack/terminal": "0.3.29",
     "@types/heft-jest": "1.0.1",
     "@types/semver": "7.3.5",
     "@types/webpack-env": "1.13.0"