@rushstack/rush-sdk 5.137.0 → 5.138.0-pr4476.0

package/dist/rush-lib.d.ts

@@ -165,6 +165,10 @@ export declare class BuildCacheConfiguration {
      * The provider for interacting with the cloud build cache, if configured.
      */
     readonly cloudCacheProvider: ICloudBuildCacheProvider | undefined;
+    /**
+     * An optional salt to inject during calculation of the cache key. This can be used to invalidate the cache for all projects when the salt changes.
+     */
+    readonly cacheHashSalt: string | undefined;
     private constructor();
     /**
      * Attempts to load the build-cache.json data from the standard file path `common/config/rush/build-cache.json`.
@@ -965,6 +969,15 @@ export declare class _FlagFile<TState extends JsonObject = JsonObject> {
  */
 export declare type GetCacheEntryIdFunction = (options: IGenerateCacheEntryIdOptions) => string;
 
+/**
+ * Function that computes a new snapshot of the current state of the repository as of the current moment.
+ * Rush-level configuration state will have been bound during creation of the function.
+ * Captures the state of the environment, tracked files, and additional files.
+ *
+ * @beta
+ */
+export declare type GetInputsSnapshotAsyncFn = () => Promise<IInputsSnapshot | undefined>;
+
 /**
  * Part of IRushConfigurationJson.
  */
@@ -994,6 +1007,10 @@ declare interface IBaseBuildCacheJson {
      * The token parser is in CacheEntryId.ts
      */
     cacheEntryNamePattern?: string;
+    /**
+     * An optional salt to inject during calculation of the cache key. This can be used to invalidate the cache for all projects when the salt changes.
+     */
+    cacheHashSalt?: string;
 }
 
 /**
@@ -1342,11 +1359,10 @@ declare interface IEventHooksJson {
  */
 export declare interface IExecuteOperationsContext extends ICreateOperationsContext {
     /**
-     * The current state of the repository.
-     *
-     * Note that this is not defined during the initial operation creation.
+     * The current state of the repository, if available.
+     * Not part of the creation context to avoid the overhead of Git calls when initializing the graph.
      */
-    readonly projectChangeAnalyzer: ProjectChangeAnalyzer;
+    readonly inputsSnapshot?: IInputsSnapshot;
 }
 
 /**
@@ -1522,6 +1538,40 @@ declare interface IIndividualVersionJson extends IVersionPolicyJson {
     lockedMajor?: number;
 }
 
+/**
+ * Represents a synchronously-queryable in-memory snapshot of the state of the inputs to a Rush repository.
+ *
+ * The methods on this interface are idempotent and will return the same result regardless of when they are executed.
+ * @beta
+ */
+export declare interface IInputsSnapshot {
+    /**
+     * The raw hashes of all tracked files in the repository.
+     */
+    readonly hashes: ReadonlyMap<string, string>;
+    /**
+     * The directory that all paths in `hashes` are relative to.
+     */
+    readonly rootDirectory: string;
+    /**
+     * Gets the map of file paths to Git hashes that will be used to compute the local state hash of the operation.
+     * Exposed separately from the final state hash to facilitate detailed change detection.
+     *
+     * @param project - The Rush project to get hashes for
+     * @param operationName - The name of the operation (phase) to get hashes for. If omitted, returns a default set for the project, as used for bulk commands.
+     * @returns A map of file name to Git hash. For local files paths will be relative. Configured additional files may be absolute paths.
+     */
+    getTrackedFileHashesForOperation(project: IRushConfigurationProjectForSnapshot, operationName?: string): ReadonlyMap<string, string>;
+    /**
+     * Gets the state hash for the files owned by this operation, including the resolutions of package.json dependencies. This will later be combined with the hash of
+     * the command being executed and the final hashes of the operation's dependencies to compute the final hash for the operation.
+     * @param project - The Rush project to compute the state hash for
+     * @param operationName - The name of the operation (phase) to get hashes for. If omitted, returns a generic hash for the whole project, as used for bulk commands.
+     * @returns The local state hash for the project. This is a hash of the environment, the project's tracked files, and any additional files.
+     */
+    getOperationOwnStateHash(project: IRushConfigurationProjectForSnapshot, operationName?: string): string;
+}
+
 /**
  * Options to pass to the rush "launch" functions.
  *
@@ -1689,6 +1739,10 @@ export declare interface IOperationExecutionResult {
      * it later (for example to re-print errors at end of execution).
      */
     readonly error: Error | undefined;
+    /**
+     * If this operation is only present in the graph to maintain dependency relationships, this flag will be set to true.
+     */
+    readonly silent: boolean;
     /**
      * Object tracking execution timing.
      */
@@ -1705,6 +1759,10 @@ export declare interface IOperationExecutionResult {
      * The id of the runner which actually runs the building process in cobuild mode.
      */
     readonly cobuildRunnerId: string | undefined;
+    /**
+     * The relative path to the folder that contains operation metadata. This folder will be automatically included in cache entries.
+     */
+    readonly metadataFolderPath: string | undefined;
     /**
      * The paths to the log files, if applicable.
      */
@@ -2131,15 +2189,6 @@ export declare interface IPnpmPeerDependencyRules {
 
 export { IPrefixMatch }
 
-/**
- * @internal
- */
-export declare interface _IRawRepoState {
-    projectState: Map<RushConfigurationProject, Map<string, string>> | undefined;
-    rootDir: string;
-    rawHashes: Map<string, string>;
-}
-
 /**
  * Information about the currently executing command provided to plugins.
  * @beta
@@ -2234,6 +2283,11 @@ declare interface IRushConfigurationJson {
     variants?: IRushVariantOptionsJson[];
 }
 
+/**
+ * @beta
+ */
+export declare type IRushConfigurationProjectForSnapshot = Pick<RushConfigurationProject, 'projectFolder' | 'projectRelativeFolder'>;
+
 /**
  * This represents the JSON data object for a project entry in the rush.json configuration file.
  */
@@ -2725,6 +2779,12 @@ export declare class Operation {
      *  the project configuration.
      */
     settings: IOperationSettings | undefined;
+    /**
+     * If set to false, this operation will be skipped during evaluation (return OperationStatus.Skipped).
+     * This is useful for plugins to alter the scope of the operation graph across executions,
+     * e.g. to enable or disable unit test execution, or to include or exclude dependencies.
+     */
+    enabled: boolean;
     constructor(options: IOperationOptions);
     /**
      * The name of this operation, for logging.
@@ -2756,9 +2816,6 @@ export declare class _OperationMetadataManager {
     private readonly _logPath;
     private readonly _errorLogPath;
     private readonly _logChunksPath;
-    private readonly _relativeLogPath;
-    private readonly _relativeLogChunksPath;
-    private readonly _relativeErrorLogPath;
     constructor(options: _IOperationMetadataManagerOptions);
     /**
      * Returns the relative paths of the metadata files to project folder.
@@ -2767,7 +2824,7 @@ export declare class _OperationMetadataManager {
      * Example: `.rush/temp/operation/_phase_build/all.log`
      * Example: `.rush/temp/operation/_phase_build/error.log`
      */
-    get relativeFilepaths(): string[];
+    get metadataFolderPath(): string;
     saveAsync({ durationInSeconds, cobuildContextId, cobuildRunnerId, logPath, errorLogPath, logChunksPath }: _IOperationMetadata): Promise<void>;
     tryRestoreAsync({ terminal, terminalProvider, errorLogPath }: {
         terminalProvider: ITerminalProvider;
@@ -3289,53 +3346,27 @@ export declare type PnpmStoreOptions = PnpmStoreLocation;
  * @beta
  */
 export declare class ProjectChangeAnalyzer {
-    /**
-     * UNINITIALIZED === we haven't looked
-     * undefined === data isn't available (i.e. - git isn't present)
-     */
-    private _data;
-    private readonly _filteredData;
-    private readonly _projectStateCache;
     private readonly _rushConfiguration;
     private readonly _git;
     constructor(rushConfiguration: RushConfiguration);
     /**
-     * Try to get a list of the specified project's dependencies and their hashes.
-     *
-     * @remarks
-     * If the data can't be generated (i.e. - if Git is not present) this returns undefined.
-     *
-     * @internal
+     * Gets a list of projects that have changed in the current state of the repo
+     * when compared to the specified branch, optionally taking the shrinkwrap and settings in
+     * the rush-project.json file into consideration.
      */
-    _tryGetProjectDependenciesAsync(project: RushConfigurationProject, terminal: ITerminal): Promise<Map<string, string> | undefined>;
+    getChangedProjectsAsync(options: IGetChangedProjectsOptions): Promise<Set<RushConfigurationProject>>;
+    protected getChangesByProject(lookup: LookupByPath<RushConfigurationProject>, changedFiles: Map<string, IFileDiffStatus>): Map<RushConfigurationProject, Map<string, IFileDiffStatus>>;
     /**
+     * Gets a snapshot of the input state of the Rush workspace that can be queried for incremental
+     * build operations and use by the build cache.
      * @internal
      */
-    _ensureInitializedAsync(terminal: ITerminal): Promise<_IRawRepoState | undefined>;
+    _tryGetSnapshotProviderAsync(projectConfigurations: ReadonlyMap<RushConfigurationProject, RushProjectConfiguration>, terminal: ITerminal): Promise<GetInputsSnapshotAsyncFn | undefined>;
     /**
-     * The project state hash is calculated in the following way:
-     * - Project dependencies are collected (see ProjectChangeAnalyzer.getPackageDeps)
-     *   - If project dependencies cannot be collected (i.e. - if Git isn't available),
-     *     this function returns `undefined`
-     * - The (path separator normalized) repo-root-relative dependencies' file paths are sorted
-     * - A SHA1 hash is created and each (sorted) file path is fed into the hash and then its
-     *   Git SHA is fed into the hash
-     * - A hex digest of the hash is returned
-     *
      * @internal
      */
-    _tryGetProjectStateHashAsync(project: RushConfigurationProject, terminal: ITerminal): Promise<string | undefined>;
     _filterProjectDataAsync<T>(project: RushConfigurationProject, unfilteredProjectData: Map<string, T>, rootDir: string, terminal: ITerminal): Promise<Map<string, T>>;
-    /**
-     * Gets a list of projects that have changed in the current state of the repo
-     * when compared to the specified branch, optionally taking the shrinkwrap and settings in
-     * the rush-project.json file into consideration.
-     */
-    getChangedProjectsAsync(options: IGetChangedProjectsOptions): Promise<Set<RushConfigurationProject>>;
-    protected getChangesByProject(lookup: LookupByPath<RushConfigurationProject>, changedFiles: Map<string, IFileDiffStatus>): Map<RushConfigurationProject, Map<string, IFileDiffStatus>>;
-    private _getDataAsync;
     private _getIgnoreMatcherForProjectAsync;
-    private _getRepoDepsAsync;
 }
 
 /**

package/lib/api/BuildCacheConfiguration.d.ts

@@ -26,6 +26,10 @@ export interface IBaseBuildCacheJson {
      * The token parser is in CacheEntryId.ts
      */
     cacheEntryNamePattern?: string;
+    /**
+     * An optional salt to inject during calculation of the cache key. This can be used to invalidate the cache for all projects when the salt changes.
+     */
+    cacheHashSalt?: string;
 }
 /**
  * @public
@@ -72,6 +76,10 @@ export declare class BuildCacheConfiguration {
      * The provider for interacting with the cloud build cache, if configured.
      */
     readonly cloudCacheProvider: ICloudBuildCacheProvider | undefined;
+    /**
+     * An optional salt to inject during calculation of the cache key. This can be used to invalidate the cache for all projects when the salt changes.
+     */
+    readonly cacheHashSalt: string | undefined;
     private constructor();
     /**
      * Attempts to load the build-cache.json data from the standard file path `common/config/rush/build-cache.json`.

package/lib/index.d.ts

@@ -36,7 +36,8 @@ export { type ILaunchOptions, Rush } from './api/Rush';
 export { RushInternals as _RushInternals } from './api/RushInternals';
 export { ExperimentsConfiguration, type IExperimentsJson } from './api/ExperimentsConfiguration';
 export { CustomTipsConfiguration, CustomTipId, type ICustomTipsJson, type ICustomTipInfo, type ICustomTipItemJson, CustomTipSeverity, CustomTipType } from './api/CustomTipsConfiguration';
-export { ProjectChangeAnalyzer, type IGetChangedProjectsOptions, type IRawRepoState as _IRawRepoState } from './logic/ProjectChangeAnalyzer';
+export { ProjectChangeAnalyzer, type IGetChangedProjectsOptions } from './logic/ProjectChangeAnalyzer';
+export type { IInputsSnapshot, GetInputsSnapshotAsyncFn as GetInputsSnapshotAsyncFn, IRushConfigurationProjectForSnapshot } from './logic/incremental/InputsSnapshot';
 export type { IOperationRunner, IOperationRunnerContext } from './logic/operations/IOperationRunner';
 export type { IExecutionResult, IOperationExecutionResult } from './logic/operations/IOperationExecutionResult';
 export { type IOperationOptions, Operation } from './logic/operations/Operation';

package/lib/logic/ProjectChangeAnalyzer.d.ts

@@ -1,8 +1,10 @@
+import type { LookupByPath } from '@rushstack/lookup-by-path';
 import { type IFileDiffStatus } from '@rushstack/package-deps-hash';
 import type { ITerminal } from '@rushstack/terminal';
 import type { RushConfiguration } from '../api/RushConfiguration';
+import { RushProjectConfiguration } from '../api/RushProjectConfiguration';
 import type { RushConfigurationProject } from '../api/RushConfigurationProject';
-import type { LookupByPath } from '@rushstack/lookup-by-path';
+import { type GetInputsSnapshotAsyncFn } from './incremental/InputsSnapshot';
 /**
  * @beta
  */
@@ -34,52 +36,26 @@ export interface IRawRepoState {
  * @beta
  */
 export declare class ProjectChangeAnalyzer {
-    /**
-     * UNINITIALIZED === we haven't looked
-     * undefined === data isn't available (i.e. - git isn't present)
-     */
-    private _data;
-    private readonly _filteredData;
-    private readonly _projectStateCache;
     private readonly _rushConfiguration;
     private readonly _git;
     constructor(rushConfiguration: RushConfiguration);
     /**
-     * Try to get a list of the specified project's dependencies and their hashes.
-     *
-     * @remarks
-     * If the data can't be generated (i.e. - if Git is not present) this returns undefined.
-     *
-     * @internal
+     * Gets a list of projects that have changed in the current state of the repo
+     * when compared to the specified branch, optionally taking the shrinkwrap and settings in
+     * the rush-project.json file into consideration.
      */
-    _tryGetProjectDependenciesAsync(project: RushConfigurationProject, terminal: ITerminal): Promise<Map<string, string> | undefined>;
+    getChangedProjectsAsync(options: IGetChangedProjectsOptions): Promise<Set<RushConfigurationProject>>;
+    protected getChangesByProject(lookup: LookupByPath<RushConfigurationProject>, changedFiles: Map<string, IFileDiffStatus>): Map<RushConfigurationProject, Map<string, IFileDiffStatus>>;
     /**
+     * Gets a snapshot of the input state of the Rush workspace that can be queried for incremental
+     * build operations and use by the build cache.
      * @internal
      */
-    _ensureInitializedAsync(terminal: ITerminal): Promise<IRawRepoState | undefined>;
+    _tryGetSnapshotProviderAsync(projectConfigurations: ReadonlyMap<RushConfigurationProject, RushProjectConfiguration>, terminal: ITerminal): Promise<GetInputsSnapshotAsyncFn | undefined>;
     /**
-     * The project state hash is calculated in the following way:
-     * - Project dependencies are collected (see ProjectChangeAnalyzer.getPackageDeps)
-     *   - If project dependencies cannot be collected (i.e. - if Git isn't available),
-     *     this function returns `undefined`
-     * - The (path separator normalized) repo-root-relative dependencies' file paths are sorted
-     * - A SHA1 hash is created and each (sorted) file path is fed into the hash and then its
-     *   Git SHA is fed into the hash
-     * - A hex digest of the hash is returned
-     *
      * @internal
      */
-    _tryGetProjectStateHashAsync(project: RushConfigurationProject, terminal: ITerminal): Promise<string | undefined>;
     _filterProjectDataAsync<T>(project: RushConfigurationProject, unfilteredProjectData: Map<string, T>, rootDir: string, terminal: ITerminal): Promise<Map<string, T>>;
-    /**
-     * Gets a list of projects that have changed in the current state of the repo
-     * when compared to the specified branch, optionally taking the shrinkwrap and settings in
-     * the rush-project.json file into consideration.
-     */
-    getChangedProjectsAsync(options: IGetChangedProjectsOptions): Promise<Set<RushConfigurationProject>>;
-    protected getChangesByProject(lookup: LookupByPath<RushConfigurationProject>, changedFiles: Map<string, IFileDiffStatus>): Map<RushConfigurationProject, Map<string, IFileDiffStatus>>;
-    private _getDataAsync;
     private _getIgnoreMatcherForProjectAsync;
-    private _getRepoDepsAsync;
 }
 //# sourceMappingURL=ProjectChangeAnalyzer.d.ts.map

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

@@ -1,23 +1,33 @@
 import type { ITerminal } from '@rushstack/terminal';
 import type { RushConfigurationProject } from '../../api/RushConfigurationProject';
-import type { ProjectChangeAnalyzer } from '../ProjectChangeAnalyzer';
 import type { BuildCacheConfiguration } from '../../api/BuildCacheConfiguration';
 export interface IProjectBuildCacheOptions {
+    /**
+     * The repo-wide configuration for the build cache.
+     */
     buildCacheConfiguration: BuildCacheConfiguration;
+    /**
+     * The project to be cached.
+     */
     project: RushConfigurationProject;
+    /**
+     * Value from rush-project.json
+     */
     projectOutputFolderNames: ReadonlyArray<string>;
-    additionalProjectOutputFilePaths?: ReadonlyArray<string>;
-    additionalContext?: Record<string, string>;
-    configHash: string;
-    projectChangeAnalyzer: ProjectChangeAnalyzer;
+    /**
+     * The hash of all relevant inputs and configuration that uniquely identifies this execution.
+     */
+    operationStateHash: string;
+    /**
+     * The terminal to use for logging.
+     */
     terminal: ITerminal;
+    /**
+     * The name of the phase that is being cached.
+     */
     phaseName: string;
 }
 export declare class ProjectBuildCache {
-    /**
-     * null === we haven't tried to initialize yet
-     * undefined === unable to initialize
-     */
     private static _tarUtilityPromise;
     private readonly _project;
     private readonly _localBuildCacheProvider;
@@ -25,12 +35,11 @@ export declare class ProjectBuildCache {
     private readonly _buildCacheEnabled;
     private readonly _cacheWriteEnabled;
     private readonly _projectOutputFolderNames;
-    private readonly _additionalProjectOutputFilePaths;
-    private _cacheId;
+    private readonly _cacheId;
     private constructor();
     private static _tryGetTarUtility;
     get cacheId(): string | undefined;
-    static tryGetProjectBuildCacheAsync(options: IProjectBuildCacheOptions): Promise<ProjectBuildCache | undefined>;
+    static getProjectBuildCache(options: IProjectBuildCacheOptions): ProjectBuildCache;
     tryRestoreFromCacheAsync(terminal: ITerminal, specifiedCacheId?: string): Promise<boolean>;
     trySetCacheEntryAsync(terminal: ITerminal, specifiedCacheId?: string): Promise<boolean>;
     /**
@@ -40,6 +49,6 @@ export declare class ProjectBuildCache {
      */
     private _tryCollectPathsToCacheAsync;
     private _getTarLogFilePath;
-    private static _getCacheIdAsync;
+    private static _getCacheId;
 }
 //# sourceMappingURL=ProjectBuildCache.d.ts.map

package/lib/logic/incremental/InputsSnapshot.d.ts

@@ -0,0 +1,149 @@
+import { type IReadonlyLookupByPath } from '@rushstack/lookup-by-path';
+import type { RushConfigurationProject } from '../../api/RushConfigurationProject';
+import type { RushProjectConfiguration } from '../../api/RushProjectConfiguration';
+/**
+ * @beta
+ */
+export type IRushConfigurationProjectForSnapshot = Pick<RushConfigurationProject, 'projectFolder' | 'projectRelativeFolder'>;
+/**
+ * @internal
+ */
+export interface IInputsSnapshotProjectMetadata {
+    /**
+     * The contents of rush-project.json for the project, if available
+     */
+    projectConfig?: RushProjectConfiguration;
+    /**
+     * A map of operation name to additional files that should be included in the hash for that operation.
+     */
+    additionalFilesByOperationName?: ReadonlyMap<string, ReadonlySet<string>>;
+}
+export type IRushSnapshotProjectMetadataMap = ReadonlyMap<IRushConfigurationProjectForSnapshot, IInputsSnapshotProjectMetadata>;
+/**
+ * Function that computes a new snapshot of the current state of the repository as of the current moment.
+ * Rush-level configuration state will have been bound during creation of the function.
+ * Captures the state of the environment, tracked files, and additional files.
+ *
+ * @beta
+ */
+export type GetInputsSnapshotAsyncFn = () => Promise<IInputsSnapshot | undefined>;
+/**
+ * The parameters for constructing an {@link InputsSnapshot}.
+ * @internal
+ */
+export interface IInputsSnapshotParameters {
+    /**
+     * Hashes for files selected by `dependsOnAdditionalFiles`.
+     * Separated out to prevent being auto-assigned to a project.
+     */
+    additionalHashes?: ReadonlyMap<string, string>;
+    /**
+     * The environment to use for `dependsOnEnvVars`. By default performs a snapshot of process.env upon construction.
+     * @defaultValue \{ ...process.env \}
+     */
+    environment?: Record<string, string | undefined>;
+    /**
+     * File paths (keys into additionalHashes or hashes) to be included as part of every operation's dependencies.
+     */
+    globalAdditionalFiles?: Iterable<string>;
+    /**
+     * The hashes of all tracked files in the repository.
+     */
+    hashes: ReadonlyMap<string, string>;
+    /**
+     * Optimized lookup engine used to route `hashes` to individual projects.
+     */
+    lookupByPath: IReadonlyLookupByPath<IRushConfigurationProjectForSnapshot>;
+    /**
+     * Metadata for each project.
+     */
+    projectMap: IRushSnapshotProjectMetadataMap;
+    /**
+     * The directory that all relative paths are relative to.
+     */
+    rootDir: string;
+}
+/**
+ * Represents a synchronously-queryable in-memory snapshot of the state of the inputs to a Rush repository.
+ *
+ * The methods on this interface are idempotent and will return the same result regardless of when they are executed.
+ * @beta
+ */
+export interface IInputsSnapshot {
+    /**
+     * The raw hashes of all tracked files in the repository.
+     */
+    readonly hashes: ReadonlyMap<string, string>;
+    /**
+     * The directory that all paths in `hashes` are relative to.
+     */
+    readonly rootDirectory: string;
+    /**
+     * Gets the map of file paths to Git hashes that will be used to compute the local state hash of the operation.
+     * Exposed separately from the final state hash to facilitate detailed change detection.
+     *
+     * @param project - The Rush project to get hashes for
+     * @param operationName - The name of the operation (phase) to get hashes for. If omitted, returns a default set for the project, as used for bulk commands.
+     * @returns A map of file name to Git hash. For local files paths will be relative. Configured additional files may be absolute paths.
+     */
+    getTrackedFileHashesForOperation(project: IRushConfigurationProjectForSnapshot, operationName?: string): ReadonlyMap<string, string>;
+    /**
+     * Gets the state hash for the files owned by this operation, including the resolutions of package.json dependencies. This will later be combined with the hash of
+     * the command being executed and the final hashes of the operation's dependencies to compute the final hash for the operation.
+     * @param project - The Rush project to compute the state hash for
+     * @param operationName - The name of the operation (phase) to get hashes for. If omitted, returns a generic hash for the whole project, as used for bulk commands.
+     * @returns The local state hash for the project. This is a hash of the environment, the project's tracked files, and any additional files.
+     */
+    getOperationOwnStateHash(project: IRushConfigurationProjectForSnapshot, operationName?: string): string;
+}
+/**
+ * Represents a synchronously-queryable in-memory snapshot of the state of the inputs to a Rush repository.
+ * Any asynchronous work needs to be performed by the caller and the results passed to the constructor.
+ *
+ * @remarks
+ * All operations on this class will return the same result regardless of when they are executed.
+ *
+ * @internal
+ */
+export declare class InputsSnapshot implements IInputsSnapshot {
+    /**
+     * {@inheritdoc IInputsSnapshot.hashes}
+     */
+    readonly hashes: ReadonlyMap<string, string>;
+    /**
+     * {@inheritdoc IInputsSnapshot.rootDirectory}
+     */
+    readonly rootDirectory: string;
+    /**
+     * The metadata for each project. This is a superset of the information in `projectMap` and includes caching of queries.
+     */
+    private readonly _projectMetadataMap;
+    /**
+     * Hashes of files to be included in all result sets.
+     */
+    private readonly _globalAdditionalHashes;
+    /**
+     * Hashes for files selected by `dependsOnAdditionalFiles`.
+     */
+    private readonly _additionalHashes;
+    /**
+     * The environment to use for `dependsOnEnvVars`.
+     */
+    private readonly _environment;
+    /**
+     *
+     * @param params - The parameters for the snapshot
+     * @internal
+     */
+    constructor(params: IInputsSnapshotParameters);
+    /**
+     * {@inheritdoc}
+     */
+    getTrackedFileHashesForOperation(project: IRushConfigurationProjectForSnapshot, operationName?: string): ReadonlyMap<string, string>;
+    /**
+     * {@inheritdoc}
+     */
+    getOperationOwnStateHash(project: IRushConfigurationProjectForSnapshot, operationName?: string): string;
+    private _resolveHashes;
+}
+//# sourceMappingURL=InputsSnapshot.d.ts.map

package/lib/logic/{buildCache/getHashesForGlobsAsync.js → incremental/InputsSnapshot.js}

@@ -1 +1 @@
-module.exports = require("../../../lib-shim/index")._rushSdk_loadInternalModule("logic/buildCache/getHashesForGlobsAsync");
+module.exports = require("../../../lib-shim/index")._rushSdk_loadInternalModule("logic/incremental/InputsSnapshot");

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

@@ -1,13 +1,11 @@
 import { type TerminalWritable, type ITerminal } from '@rushstack/terminal';
 import { CobuildLock } from '../cobuild/CobuildLock';
 import { ProjectBuildCache } from '../buildCache/ProjectBuildCache';
-import { type IOperationSettings } from '../../api/RushProjectConfiguration';
 import type { CobuildConfiguration } from '../../api/CobuildConfiguration';
 import { DisjointSet } from '../cobuild/DisjointSet';
 import { PeriodicCallback } from './PeriodicCallback';
 import type { Operation } from './Operation';
 import type { IPhasedCommandPlugin, PhasedCommandHooks } from '../../pluginFramework/PhasedCommandHooks';
-import type { ProjectChangeAnalyzer } from '../ProjectChangeAnalyzer';
 import type { BuildCacheConfiguration } from '../../api/BuildCacheConfiguration';
 export interface IProjectDeps {
     files: {
@@ -18,10 +16,10 @@ export interface IProjectDeps {
 export interface IOperationBuildCacheContext {
     isCacheWriteAllowed: boolean;
     isCacheReadAllowed: boolean;
-    projectChangeAnalyzer: ProjectChangeAnalyzer;
-    projectBuildCache: ProjectBuildCache | undefined;
+    stateHash: string;
+    operationBuildCache: ProjectBuildCache | undefined;
     cacheDisabledReason: string | undefined;
-    operationSettings: IOperationSettings | undefined;
+    outputFolderNames: ReadonlyArray<string>;
     cobuildLock: CobuildLock | undefined;
     cobuildClusterId: string | undefined;
     buildCacheTerminal: ITerminal | undefined;
@@ -43,7 +41,7 @@ export declare class CacheableOperationPlugin implements IPhasedCommandPlugin {
     apply(hooks: PhasedCommandHooks): void;
     private _getBuildCacheContextByOperation;
     private _getBuildCacheContextByOperationOrThrow;
-    private _tryGetProjectBuildCacheAsync;
+    private _tryGetProjectBuildCache;
     private _tryGetLogOnlyProjectBuildCacheAsync;
     private _tryGetCobuildLockAsync;
     private _createBuildCacheTerminalAsync;

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

@@ -24,6 +24,10 @@ export interface IOperationExecutionResult {
      * it later (for example to re-print errors at end of execution).
      */
     readonly error: Error | undefined;
+    /**
+     * If this operation is only present in the graph to maintain dependency relationships, this flag will be set to true.
+     */
+    readonly silent: boolean;
     /**
      * Object tracking execution timing.
      */
@@ -40,6 +44,10 @@ export interface IOperationExecutionResult {
      * The id of the runner which actually runs the building process in cobuild mode.
      */
     readonly cobuildRunnerId: string | undefined;
+    /**
+     * The relative path to the folder that contains operation metadata. This folder will be automatically included in cache entries.
+     */
+    readonly metadataFolderPath: string | undefined;
     /**
      * The paths to the log files, if applicable.
      */

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

@@ -83,6 +83,12 @@ export declare class Operation {
      *  the project configuration.
      */
     settings: IOperationSettings | undefined;
+    /**
+     * If set to false, this operation will be skipped during evaluation (return OperationStatus.Skipped).
+     * This is useful for plugins to alter the scope of the operation graph across executions,
+     * e.g. to enable or disable unit test execution, or to include or exclude dependencies.
+     */
+    enabled: boolean;
     constructor(options: IOperationOptions);
     /**
      * The name of this operation, for logging.

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

@@ -8,6 +8,7 @@ import { OperationMetadataManager } from './OperationMetadataManager';
 import type { IPhase } from '../../api/CommandLineConfiguration';
 import type { RushConfigurationProject } from '../../api/RushConfigurationProject';
 import { type ILogFilePaths } from './ProjectLogWritable';
+import type { IOperationExecutionResult } from './IOperationExecutionResult';
 export interface IOperationExecutionRecordContext {
     streamCollator: StreamCollator;
     onOperationStatusChanged?: (record: OperationExecutionRecord) => void;
@@ -19,7 +20,7 @@ export interface IOperationExecutionRecordContext {
  *
  * @internal
  */
-export declare class OperationExecutionRecord implements IOperationRunnerContext {
+export declare class OperationExecutionRecord implements IOperationRunnerContext, IOperationExecutionResult {
     /**
      * The associated operation.
      */
@@ -87,6 +88,7 @@ export declare class OperationExecutionRecord implements IOperationRunnerContext
     get collatedWriter(): CollatedWriter;
     get nonCachedDurationMs(): number | undefined;
     get cobuildRunnerId(): string | undefined;
+    get metadataFolderPath(): string | undefined;
     get isTerminal(): boolean;
     /**
      * The current execution status of an operation. Operations start in the 'ready' state,
@@ -96,6 +98,7 @@ export declare class OperationExecutionRecord implements IOperationRunnerContext
      */
     get status(): OperationStatus;
     set status(newStatus: OperationStatus);
+    get silent(): boolean;
     /**
      * {@inheritdoc IOperationRunnerContext.runWithTerminalAsync}
      */

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

@@ -37,9 +37,6 @@ export declare class OperationMetadataManager {
     private readonly _logPath;
     private readonly _errorLogPath;
     private readonly _logChunksPath;
-    private readonly _relativeLogPath;
-    private readonly _relativeLogChunksPath;
-    private readonly _relativeErrorLogPath;
     constructor(options: IOperationMetadataManagerOptions);
     /**
      * Returns the relative paths of the metadata files to project folder.
@@ -48,7 +45,7 @@ export declare class OperationMetadataManager {
      * Example: `.rush/temp/operation/_phase_build/all.log`
      * Example: `.rush/temp/operation/_phase_build/error.log`
      */
-    get relativeFilepaths(): string[];
+    get metadataFolderPath(): string;
     saveAsync({ durationInSeconds, cobuildContextId, cobuildRunnerId, logPath, errorLogPath, logChunksPath }: IOperationMetaData): Promise<void>;
     tryRestoreAsync({ terminal, terminalProvider, errorLogPath }: {
         terminalProvider: ITerminalProvider;

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

@@ -8,6 +8,7 @@ export interface IOperationRunnerOptions {
     rushProject: RushConfigurationProject;
     rushConfiguration: RushConfiguration;
     commandToRun: string;
+    commandForHash: string;
     displayName: string;
     phase: IPhase;
     environment?: IEnvironment;
@@ -24,6 +25,7 @@ export declare class ShellOperationRunner implements IOperationRunner {
     readonly cacheable: boolean;
     readonly warningsAreAllowed: boolean;
     private readonly _commandToRun;
+    private readonly _commandForHash;
     private readonly _rushProject;
     private readonly _rushConfiguration;
     private readonly _environment?;

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

@@ -16,8 +16,9 @@ export declare function initializeShellOperationRunner(options: {
     displayName: string;
     rushConfiguration: RushConfiguration;
     commandToRun: string | undefined;
+    commandForHash?: string;
+    customParameterValues: ReadonlyArray<string>;
 }): IOperationRunner;
-export declare function getScriptToRun(rushProject: RushConfigurationProject, commandToRun: string, shellCommand: string | undefined): string | undefined;
 /**
  * Memoizer for custom parameter values by phase
  * @returns A function that returns the custom parameter values for a given phase

package/lib/pluginFramework/PhasedCommandHooks.d.ts

@@ -5,13 +5,13 @@ import type { IPhase } from '../api/CommandLineConfiguration';
 import type { RushConfiguration } from '../api/RushConfiguration';
 import type { RushConfigurationProject } from '../api/RushConfigurationProject';
 import type { Operation } from '../logic/operations/Operation';
-import type { ProjectChangeAnalyzer } from '../logic/ProjectChangeAnalyzer';
 import type { IExecutionResult, IOperationExecutionResult } from '../logic/operations/IOperationExecutionResult';
 import type { CobuildConfiguration } from '../api/CobuildConfiguration';
 import type { RushProjectConfiguration } from '../api/RushProjectConfiguration';
 import type { IOperationRunnerContext } from '../logic/operations/IOperationRunner';
 import type { ITelemetryData } from '../logic/Telemetry';
 import type { OperationStatus } from '../logic/operations/OperationStatus';
+import type { IInputsSnapshot } from '../logic/incremental/InputsSnapshot';
 /**
  * A plugin that interacts with a phased commands.
  * @alpha
@@ -92,11 +92,10 @@ export interface ICreateOperationsContext {
  */
 export interface IExecuteOperationsContext extends ICreateOperationsContext {
     /**
-     * The current state of the repository.
-     *
-     * Note that this is not defined during the initial operation creation.
+     * The current state of the repository, if available.
+     * Not part of the creation context to avoid the overhead of Git calls when initializing the graph.
      */
-    readonly projectChangeAnalyzer: ProjectChangeAnalyzer;
+    readonly inputsSnapshot?: IInputsSnapshot;
 }
 /**
  * Hooks into the execution process for phased commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rushstack/rush-sdk",
-  "version": "5.137.0",
+  "version": "5.138.0-pr4476.0",
   "description": "An API for interacting with the Rush engine",
   "repository": {
     "type": "git",
@@ -45,11 +45,11 @@
     "@types/webpack-env": "1.18.0",
     "webpack": "~5.95.0",
     "@rushstack/heft": "0.68.2",
-    "@microsoft/rush-lib": "5.137.0",
-    "@rushstack/stream-collator": "4.1.70",
     "local-node-rig": "1.0.0",
+    "@microsoft/rush-lib": "5.138.0-pr4476.0",
     "@rushstack/heft-webpack5-plugin": "0.11.0",
     "@rushstack/ts-command-line": "4.22.8",
+    "@rushstack/stream-collator": "4.1.70",
     "@rushstack/webpack-preserve-dynamic-require-plugin": "0.11.69"
   },
   "scripts": {

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

@@ -1,3 +0,0 @@
-import type { IRawRepoState } from '../ProjectChangeAnalyzer';
-export declare function getHashesForGlobsAsync(globPatterns: Iterable<string>, packagePath: string, repoState: IRawRepoState | undefined): Promise<Map<string, string>>;
-//# sourceMappingURL=getHashesForGlobsAsync.d.ts.map