[rush] Add an option to make the Rush operation hash depend on the NodeJS version.

common/changes/@microsoft/rush-lib/rush-project-dependsOnNodeVersion_2026-02-17-00-00.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Add a new `dependsOnNodeVersion` setting for operation entries in rush-project.json. When enabled, the Node.js version is included in the build cache hash, ensuring that cached outputs are invalidated when the Node.js version changes. Accepts `true` (alias for `\"patch\"`), `\"major\"`, `\"minor\"`, or `\"patch\"` to control the granularity of version matching.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/reviews/api/rush-lib.api.md

@@ -669,6 +669,7 @@ export interface IOperationSettings {
     allowCobuildWithoutCache?: boolean;
     dependsOnAdditionalFiles?: string[];
     dependsOnEnvVars?: string[];
+    dependsOnNodeVersion?: boolean | NodeVersionGranularity;
     disableBuildCacheForOperation?: boolean;
     ignoreChangedProjectsOnlyFlag?: boolean;
     operationName: string;
@@ -961,6 +962,9 @@ export class LockStepVersionPolicy extends VersionPolicy {
 
 export { LookupByPath }
 
+// @alpha
+export type NodeVersionGranularity = 'major' | 'minor' | 'patch';
+
 // @public
 export class NpmOptionsConfiguration extends PackageManagerOptionsConfigurationBase {
     // @internal

libraries/rush-lib/src/api/RushProjectConfiguration.ts

@@ -72,6 +72,17 @@ export interface IRushPhaseSharding {
   shardOperationSettings?: unknown;
 }
 
+/**
+ * The granularity at which the Node.js version is included in the build cache hash.
+ *
+ * - `"major"` — includes only the major version (e.g. `18`)
+ * - `"minor"` — includes the major and minor version (e.g. `18.17`)
+ * - `"patch"` — includes the full version (e.g. `18.17.1`)
+ *
+ * @alpha
+ */
+export type NodeVersionGranularity = 'major' | 'minor' | 'patch';
+
 /**
  * @alpha
  */
@@ -112,6 +123,20 @@ export interface IOperationSettings {
    */
   dependsOnEnvVars?: string[];
 
+  /**
+   * Specifies whether and at what granularity the Node.js version should be included in the hash
+   * used for the build cache. When enabled, changing the Node.js version at the specified granularity
+   * will invalidate cached outputs and cause the operation to be re-executed. This is useful for
+   * projects that produce Node.js-version-specific outputs, such as native module builds.
+   *
+   * Allowed values:
+   * - `true` — alias for `"patch"`, includes the full version (e.g. `18.17.1`)
+   * - `"major"` — includes only the major version (e.g. `18`)
+   * - `"minor"` — includes the major and minor version (e.g. `18.17`)
+   * - `"patch"` — includes the full version (e.g. `18.17.1`)
+   */
+  dependsOnNodeVersion?: boolean | NodeVersionGranularity;
+
   /**
    * An optional list of glob (minimatch) patterns pointing to files that can affect this operation.
    * The hash values of the contents of these files will become part of the final hash when reading

libraries/rush-lib/src/index.ts

@@ -79,6 +79,7 @@ export { RushConfigurationProject } from './api/RushConfigurationProject';
 export {
   type IRushProjectJson as _IRushProjectJson,
   type IOperationSettings,
+  type NodeVersionGranularity,
   RushProjectConfiguration,
   type IRushPhaseSharding
 } from './api/RushProjectConfiguration';

libraries/rush-lib/src/logic/incremental/InputsSnapshot.ts

@@ -10,7 +10,11 @@ import { type IReadonlyLookupByPath, LookupByPath } from '@rushstack/lookup-by-p
 import { InternalError, Path, Sort } from '@rushstack/node-core-library';
 
 import type { RushConfigurationProject } from '../../api/RushConfigurationProject';
-import type { IOperationSettings, RushProjectConfiguration } from '../../api/RushProjectConfiguration';
+import type {
+  IOperationSettings,
+  NodeVersionGranularity,
+  RushProjectConfiguration
+} from '../../api/RushProjectConfiguration';
 import { RushConstants } from '../RushConstants';
 
 /**
@@ -90,6 +94,11 @@ export interface IInputsSnapshotParameters {
    * @defaultValue \{ ...process.env \}
    */
   environment?: Record<string, string | undefined>;
+  /**
+   * The Node.js version string to use for `dependsOnNodeVersion`. Defaults to `process.version`.
+   * @defaultValue process.version
+   */
+  nodeVersion?: string;
   /**
    * File paths (keys into additionalHashes or hashes) to be included as part of every operation's dependencies.
    */
@@ -205,6 +214,10 @@ export class InputsSnapshot implements IInputsSnapshot {
    * The environment to use for `dependsOnEnvVars`.
    */
   private readonly _environment: Record<string, string | undefined>;
+  /**
+   * Pre-computed Node.js version strings at each granularity level for `dependsOnNodeVersion`.
+   */
+  private readonly _nodeVersionByGranularity: Readonly<Record<NodeVersionGranularity, string>>;
 
   /**
    *
@@ -219,6 +232,7 @@ export class InputsSnapshot implements IInputsSnapshot {
       hashes,
       hasUncommittedChanges,
       lookupByPath,
+      nodeVersion = process.version,
       rootDir
     } = params;
     const projectMetadataMap: Map<
@@ -274,6 +288,8 @@ export class InputsSnapshot implements IInputsSnapshot {
     this._globalAdditionalHashes = globalAdditionalHashes;
     // Snapshot the environment so that queries are not impacted by when they happen
     this._environment = environment;
+    // Parse Node.js version once so it doesn't need to be re-parsed per operation
+    this._nodeVersionByGranularity = _parseNodeVersion(nodeVersion);
     this.hashes = hashes;
     this.hasUncommittedChanges = hasUncommittedChanges;
     this.rootDirectory = rootDir;
@@ -380,7 +396,7 @@ export class InputsSnapshot implements IInputsSnapshot {
         const operationSettings: Readonly<IOperationSettings> | undefined =
           record.projectConfig?.operationSettingsByOperationName.get(operationName);
         if (operationSettings) {
-          const { dependsOnEnvVars, outputFolderNames } = operationSettings;
+          const { dependsOnEnvVars, dependsOnNodeVersion, outputFolderNames } = operationSettings;
           if (dependsOnEnvVars) {
             // As long as we enumerate environment variables in a consistent order, we will get a stable hash.
             // Changing the order in rush-project.json will change the hash anyway since the file contents are part of the hash.
@@ -389,6 +405,12 @@ export class InputsSnapshot implements IInputsSnapshot {
             }
           }
 
+          if (dependsOnNodeVersion) {
+            const granularity: NodeVersionGranularity =
+              dependsOnNodeVersion === true ? 'patch' : dependsOnNodeVersion;
+            hasher.update(`${hashDelimiter}nodeVersion=${this._nodeVersionByGranularity[granularity]}`);
+          }
+
           if (outputFolderNames) {
             hasher.update(`${hashDelimiter}${JSON.stringify(outputFolderNames)}`);
           }
@@ -421,6 +443,24 @@ export class InputsSnapshot implements IInputsSnapshot {
   }
 }
 
+/**
+ * Parses a Node.js version string once and returns pre-computed strings for each granularity level.
+ *
+ * @param rawVersion - The full Node.js version string (e.g. `v18.17.1`)
+ * @returns An object with pre-computed version strings for `major`, `minor`, and `patch` granularities
+ */
+function _parseNodeVersion(rawVersion: string): Record<NodeVersionGranularity, string> {
+  // Strip leading 'v' if present
+  const version: string = rawVersion.startsWith('v') ? rawVersion.slice(1) : rawVersion;
+  const [major, minor]: string[] = version.split('.');
+
+  return {
+    major,
+    minor: `${major}.${minor}`,
+    patch: version
+  };
+}
+
 function getOrCreateProjectFilter(
   record: IInternalInputsSnapshotProjectMetadata
 ): (filePath: string) => boolean {