Relativize outFolderName paths in TypeScript cache hash computation (#5533)

* Initial plan

* Fix non-portable hash computation by relativizing outFolderName paths and using base64url encoding

Co-authored-by: dmichon-msft <[email protected]>

* Fix: Use empty array instead of empty object as fallback for normalizedConfig

Co-authored-by: dmichon-msft <[email protected]>

* Normalize path separators to forward slashes in hash computation

Co-authored-by: dmichon-msft <[email protected]>

* Add changelog entry for cache hash portability fix

Co-authored-by: iclanton <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: dmichon-msft <[email protected]>
Co-authored-by: iclanton <[email protected]>

Author: 3 people

common/changes/@rushstack/heft-typescript-plugin/fix-cache-hash-portability_2026-01-04-03-06.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-typescript-plugin",
+      "comment": "Fix TypeScript build cache hash computation to use relative paths with normalized separators for portability across machines and platforms",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@rushstack/heft-typescript-plugin",
+  "email": "[email protected]"
+}

heft-plugins/heft-typescript-plugin/src/TypeScriptBuilder.ts

@@ -17,7 +17,7 @@ import type {
   IExtendedSolutionBuilder,
   ITypeScriptNodeSystem
 } from './internalTypings/TypeScriptInternals';
-import type { ITypeScriptConfigurationJson } from './TypeScriptPlugin';
+import type { ITypeScriptConfigurationJson, IEmitModuleKind } from './TypeScriptPlugin';
 import type { PerformanceMeasurer } from './Performance';
 import type {
   ICachedEmitModuleKind,
@@ -152,12 +152,17 @@ export class TypeScriptBuilder {
       // We only need to hash our additional Heft configuration.
       const configHash: crypto.Hash = crypto.createHash('sha1');
 
-      configHash.update(JSON.stringify(this._configuration.additionalModuleKindsToEmit || {}));
-      const serializedConfigHash: string = configHash
-        .digest('base64')
-        .slice(0, 8)
-        .replace(/\+/g, '-')
-        .replace(/\//g, '_');
+      // Relativize the outFolderName paths before hashing to ensure portability across different machines
+      const normalizedConfig: IEmitModuleKind[] =
+        this._configuration.additionalModuleKindsToEmit?.map((emitKind) => ({
+          ...emitKind,
+          outFolderName: Path.convertToSlashes(
+            path.relative(this._configuration.buildFolderPath, emitKind.outFolderName)
+          )
+        })) || [];
+
+      configHash.update(JSON.stringify(normalizedConfig));
+      const serializedConfigHash: string = configHash.digest('base64url').slice(0, 8);
 
       // This conversion is theoretically redundant, but it is here to make absolutely sure that the path is formatted
       // using only '/' as the directory separator so that incremental builds don't break on Windows.