feat: split Go module and build caches

Reuse downloaded modules across Go versions, runner architectures, and
runner images on the same OS instead of duplicating them in each build
cache archive.

Restore and save each entry independently, running operations in parallel
when safe. Serialize restores for overlapping or aliased paths, preserve
the original paths for the post step, and report cache-hit only when both
entries match their primary keys.

Update the documented manual restore keys and generated action bundles.

__tests__/cache-restore.test.ts

@@ -1,5 +1,8 @@
+/// <reference types="node" />
+
 import {jest, describe, it, expect, beforeEach, afterEach} from '@jest/globals';
 import fs from 'fs';
+import path from 'path';
 
 jest.unstable_mockModule('@actions/cache', () => ({
   saveCache: jest.fn(),
@@ -50,91 +53,349 @@ const core = await import('@actions/core');
 const glob = await import('@actions/glob');
 const cacheRestore = await import('../src/cache-restore.js');
 const cacheUtils = await import('../src/cache-utils.js');
-import type {PackageManagerInfo} from '../src/package-managers.js';
+const {run: saveCaches} = await import('../src/cache-save.js');
+import type {CacheDirectory} from '../src/cache-utils.js';
+
+function deferred() {
+  let resolve!: () => void;
+  const promise = new Promise<void>(done => {
+    resolve = done;
+  });
+  return {promise, resolve};
+}
 
 describe('restoreCache', () => {
-  let hashFilesSpy: jest.Mock<typeof glob.hashFiles>;
-  let getCacheDirectoryPathSpy: jest.Mock<
-    typeof cacheUtils.getCacheDirectoryPath
+  const hashFilesSpy = glob.hashFiles as jest.Mock<typeof glob.hashFiles>;
+  const getCacheDirectoryPathSpy =
+    cacheUtils.getCacheDirectoryPath as jest.Mock<
+      typeof cacheUtils.getCacheDirectoryPath
+    >;
+  const restoreCacheSpy = cache.restoreCache as jest.Mock<
+    typeof cache.restoreCache
   >;
-  let restoreCacheSpy: jest.Mock<typeof cache.restoreCache>;
-  let infoSpy: jest.Mock<typeof core.info>;
-  let setOutputSpy: jest.Mock<typeof core.setOutput>;
+  const saveCacheSpy = cache.saveCache as jest.Mock<typeof cache.saveCache>;
+  const infoSpy = core.info as jest.Mock<typeof core.info>;
+  const setOutputSpy = core.setOutput as jest.Mock<typeof core.setOutput>;
 
   const versionSpec = '1.13.1';
   const packageManager = 'default';
   const cacheDependencyPath = 'path';
-
-  let originalWorkspace: string | undefined;
+  const modulePath = 'module_cache_directory';
+  const buildPath = 'build_cache_directory';
+  const directories: CacheDirectory[] = [
+    {kind: 'modules', path: modulePath},
+    {kind: 'build', path: buildPath}
+  ];
+  const originalEnv = {...process.env};
+  const originalArch = Object.getOwnPropertyDescriptor(process, 'arch')!;
+  const originalPlatform = Object.getOwnPropertyDescriptor(
+    process,
+    'platform'
+  )!;
 
   beforeEach(() => {
-    originalWorkspace = process.env.GITHUB_WORKSPACE;
-    process.env.GITHUB_WORKSPACE = '/test/workspace';
-    //Arrange
-    hashFilesSpy = glob.hashFiles as jest.Mock<typeof glob.hashFiles>;
-    getCacheDirectoryPathSpy = cacheUtils.getCacheDirectoryPath as jest.Mock<
-      typeof cacheUtils.getCacheDirectoryPath
-    >;
-    restoreCacheSpy = cache.restoreCache as jest.Mock<
-      typeof cache.restoreCache
-    >;
-    infoSpy = core.info as jest.Mock<typeof core.info>;
-    setOutputSpy = core.setOutput as jest.Mock<typeof core.setOutput>;
-
-    getCacheDirectoryPathSpy.mockImplementation(
-      (PackageManager: PackageManagerInfo) => {
-        return Promise.resolve([
-          'cache_directory_path',
-          'cache_directory_path'
-        ]);
-      }
-    );
+    jest.resetAllMocks();
+    process.env = {
+      ...originalEnv,
+      GITHUB_WORKSPACE: '/test/workspace',
+      RUNNER_OS: 'Linux',
+      ImageOS: 'ubuntu24'
+    };
+    Object.defineProperty(process, 'arch', {value: 'x64'});
+    Object.defineProperty(process, 'platform', {value: 'linux'});
+    hashFilesSpy.mockResolvedValue('file_hash');
+    getCacheDirectoryPathSpy.mockResolvedValue(directories);
+    restoreCacheSpy.mockResolvedValue(undefined);
+    saveCacheSpy.mockResolvedValue(1);
   });
 
   afterEach(() => {
-    process.env.GITHUB_WORKSPACE = originalWorkspace;
+    process.env = {...originalEnv};
+    Object.defineProperty(process, 'arch', originalArch);
+    Object.defineProperty(process, 'platform', originalPlatform);
     jest.restoreAllMocks();
   });
 
+  const restore = (version = versionSpec) =>
+    cacheRestore.restoreCache(version, packageManager, cacheDependencyPath);
+
+  const requestedKeys = () => {
+    const moduleCall = restoreCacheSpy.mock.calls.find(
+      ([paths]) => paths[0] === modulePath
+    );
+    const buildCall = restoreCacheSpy.mock.calls.find(
+      ([paths]) => paths[0] === buildPath
+    );
+    expect(moduleCall).toBeDefined();
+    expect(buildCall).toBeDefined();
+    return {modules: moduleCall![1], build: buildCall![1]};
+  };
+
   it('should throw if dependency file path is not valid', async () => {
-    // Arrange
-    hashFilesSpy.mockImplementation(() => Promise.resolve(''));
-    // Act + Assert
-    await expect(
-      cacheRestore.restoreCache(
-        versionSpec,
-        packageManager,
-        cacheDependencyPath
-      )
-    ).rejects.toThrow(
+    hashFilesSpy.mockResolvedValue('');
+
+    await expect(restore()).rejects.toThrow(
       'Some specified paths were not resolved, unable to cache dependencies.'
     );
+    expect(restoreCacheSpy).not.toHaveBeenCalled();
+    expect(setOutputSpy).toHaveBeenLastCalledWith('cache-hit', false);
   });
 
-  it('should inform if cache hit is not occurred', async () => {
-    // Arrange
-    hashFilesSpy.mockImplementation(() => Promise.resolve('file_hash'));
-    restoreCacheSpy.mockImplementation(() => Promise.resolve(''));
-    // Act + Assert
+  it('restores modules and build outputs as separate cache entries', async () => {
+    await restore();
+
+    const keys = requestedKeys();
+    expect(keys.modules).not.toBe(keys.build);
+    expect(restoreCacheSpy).toHaveBeenCalledTimes(2);
+    expect(restoreCacheSpy).toHaveBeenCalledWith([modulePath], keys.modules);
+    expect(restoreCacheSpy).toHaveBeenCalledWith([buildPath], keys.build);
+    expect(infoSpy).toHaveBeenCalledWith('modules cache is not found');
+    expect(infoSpy).toHaveBeenCalledWith('build cache is not found');
+  });
+
+  it.each([
+    {platform: 'linux', firstFails: false},
+    {platform: 'linux', firstFails: true},
+    {platform: 'win32', firstFails: false},
+    {platform: 'win32', firstFails: true}
+  ])(
+    'starts both restores concurrently on $platform and waits for both (first fails=$firstFails)',
+    async ({platform, firstFails}) => {
+      Object.defineProperty(process, 'platform', {value: platform});
+      const started = [deferred(), deferred()];
+      const release = [deferred(), deferred()];
+      let completed = false;
+      restoreCacheSpy.mockImplementation(async (paths, key) => {
+        const index = paths[0] === modulePath ? 0 : 1;
+        started[index].resolve();
+        await release[index].promise;
+        if (index === 0 && firstFails) {
+          throw new Error('Module cache unavailable');
+        }
+        return key;
+      });
+
+      const pending = restore().then(() => {
+        completed = true;
+      });
+      try {
+        await Promise.all(started.map(signal => signal.promise));
+        release[0].resolve();
+        // Let the first completion propagate while the second stays blocked.
+        await new Promise<void>(resolve => setImmediate(resolve));
+        expect(completed).toBe(false);
+        expect(core.saveState).not.toHaveBeenCalled();
+        expect(setOutputSpy).not.toHaveBeenCalledWith('cache-hit', true);
+      } finally {
+        release.forEach(signal => signal.resolve());
+        await pending;
+      }
+
+      expect(setOutputSpy).toHaveBeenLastCalledWith('cache-hit', !firstFails);
+      expect(core.saveState).toHaveBeenCalledTimes(1);
+    }
+  );
+
+  it.each(['linux', 'win32'])(
+    'restores overlapping directories sequentially on %s',
+    async platform => {
+      Object.defineProperty(process, 'platform', {value: platform});
+      getCacheDirectoryPathSpy.mockResolvedValue([
+        directories[0],
+        {kind: 'build', path: path.join(modulePath, 'build')}
+      ]);
+      const firstStarted = deferred();
+      const releaseFirst = deferred();
+      restoreCacheSpy.mockImplementation(async (paths, key) => {
+        if (paths[0] === modulePath) {
+          firstStarted.resolve();
+          await releaseFirst.promise;
+        }
+        return key;
+      });
+
+      const pending = restore();
+      try {
+        await firstStarted.promise;
+        expect(restoreCacheSpy).toHaveBeenCalledTimes(1);
+      } finally {
+        releaseFirst.resolve();
+        await pending;
+      }
+
+      expect(restoreCacheSpy).toHaveBeenCalledTimes(2);
+      expect(setOutputSpy).toHaveBeenLastCalledWith('cache-hit', true);
+    }
+  );
+
+  it.each([
+    {modules: false, build: false},
+    {modules: true, build: false},
+    {modules: false, build: true},
+    {modules: true, build: true}
+  ])(
+    'reports hits and saves misses independently (modules=$modules, build=$build)',
+    async hits => {
+      const state = new Map<string, string>();
+      (core.saveState as jest.Mock<typeof core.saveState>).mockImplementation(
+        (name, value) => {
+          state.set(name, JSON.stringify(value));
+        }
+      );
+      (core.getState as jest.Mock<typeof core.getState>).mockImplementation(
+        name => state.get(name) || ''
+      );
+      (
+        core.getBooleanInput as jest.Mock<typeof core.getBooleanInput>
+      ).mockReturnValue(true);
+      jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+      restoreCacheSpy.mockImplementation(async (paths, key) =>
+        hits[paths[0] === modulePath ? 'modules' : 'build'] ? key : undefined
+      );
+
+      await restore();
+      const keys = requestedKeys();
+      expect(setOutputSpy).toHaveBeenLastCalledWith(
+        'cache-hit',
+        hits.modules && hits.build
+      );
+
+      // Changing the Go environment later must not change the saved paths.
+      process.env.GOMODCACHE = 'different_module_cache';
+      process.env.GOCACHE = 'different_build_cache';
+      await saveCaches();
+
+      for (const {kind, path} of directories) {
+        if (hits[kind]) {
+          expect(saveCacheSpy).not.toHaveBeenCalledWith([path], keys[kind]);
+        } else {
+          expect(saveCacheSpy).toHaveBeenCalledWith([path], keys[kind]);
+        }
+      }
+      expect(saveCacheSpy).toHaveBeenCalledTimes(
+        Number(!hits.modules) + Number(!hits.build)
+      );
+    }
+  );
+
+  it('does not report a full hit for a non-primary cache match', async () => {
+    restoreCacheSpy.mockImplementation(async (_paths, key) => `${key}-other`);
+
+    await restore();
+
+    expect(setOutputSpy).toHaveBeenLastCalledWith('cache-hit', false);
+  });
+
+  it.each(directories)(
+    'continues restoring when the $kind cache fails',
+    async ({kind, path}) => {
+      restoreCacheSpy.mockImplementation(async (paths, key) => {
+        if (paths[0] === path) {
+          throw new Error('Unable to reach the service');
+        }
+        return key;
+      });
+
+      await restore();
+
+      expect(restoreCacheSpy).toHaveBeenCalledTimes(2);
+      expect(core.warning).toHaveBeenCalledWith(
+        `Restore ${kind} cache failed: Unable to reach the service`
+      );
+      expect(setOutputSpy).toHaveBeenLastCalledWith('cache-hit', false);
+    }
+  );
+
+  it.each(directories)(
+    'restores only $kind when the other directory cannot be resolved',
+    async directory => {
+      getCacheDirectoryPathSpy.mockResolvedValue([directory]);
+      restoreCacheSpy.mockImplementation(async (_paths, key) => key);
+
+      await restore();
+
+      expect(restoreCacheSpy).toHaveBeenCalledTimes(1);
+      expect(restoreCacheSpy).toHaveBeenCalledWith(
+        [directory.path],
+        expect.any(String)
+      );
+      expect(setOutputSpy).toHaveBeenLastCalledWith('cache-hit', false);
+    }
+  );
+
+  it('reuses modules across Go versions without reusing build outputs', async () => {
+    await restore();
+    const before = requestedKeys();
+    restoreCacheSpy.mockClear();
+
+    await restore('1.26.1');
+    const after = requestedKeys();
+
+    expect(after.modules).toBe(before.modules);
+    expect(after.build).not.toBe(before.build);
+  });
+
+  it.each([
+    {
+      name: 'runner architecture',
+      change: () => Object.defineProperty(process, 'arch', {value: 'arm64'})
+    },
+    {
+      name: 'runner image',
+      change: () => {
+        process.env.ImageOS = 'ubuntu26';
+      }
+    }
+  ])('reuses only modules when the $name changes', async ({change}) => {
+    await restore();
+    const before = requestedKeys();
+    restoreCacheSpy.mockClear();
+
+    change();
+    await restore();
+    const after = requestedKeys();
+
+    expect(after.modules).toBe(before.modules);
+    expect(after.build).not.toBe(before.build);
+  });
+
+  it('keeps both cache entries isolated by runner OS', async () => {
+    await restore();
+    const before = requestedKeys();
+    restoreCacheSpy.mockClear();
+
+    process.env.RUNNER_OS = 'Windows';
+    await restore();
+    const after = requestedKeys();
+
+    expect(after.modules).not.toBe(before.modules);
+    expect(after.build).not.toBe(before.build);
+  });
+
+  it('invalidates both cache entries when the dependency hash changes', async () => {
+    await restore();
+    const before = requestedKeys();
+    restoreCacheSpy.mockClear();
+
+    hashFilesSpy.mockResolvedValue('different_file_hash');
+    await restore();
+    const after = requestedKeys();
+
+    expect(after.modules).not.toBe(before.modules);
+    expect(after.build).not.toBe(before.build);
+  });
+
+  it('hashes the configured dependency paths for both cache entries', async () => {
+    const dependencyPaths = 'go.sum\ntools/go.sum';
+
     await cacheRestore.restoreCache(
       versionSpec,
       packageManager,
-      cacheDependencyPath
+      dependencyPaths
     );
-    expect(infoSpy).toHaveBeenCalledWith('Cache is not found');
-  });
 
-  it('should set output if cache hit is occurred', async () => {
-    // Arrange
-    hashFilesSpy.mockImplementation(() => Promise.resolve('file_hash'));
-    restoreCacheSpy.mockImplementation(() => Promise.resolve('cache_key'));
-    // Act + Assert
-    await cacheRestore.restoreCache(
-      versionSpec,
-      packageManager,
-      cacheDependencyPath
-    );
-    expect(setOutputSpy).toHaveBeenCalledWith('cache-hit', true);
+    expect(hashFilesSpy).toHaveBeenCalledWith(dependencyPaths);
+    expect(restoreCacheSpy).toHaveBeenCalledTimes(2);
   });
 
   it('should throw if dependency file is not found in workspace', async () => {

__tests__/cache-save.test.ts

@@ -1,3 +1,5 @@
+/// <reference types="node" />
+
 import {jest, describe, it, expect, beforeEach, afterEach} from '@jest/globals';
 
 jest.unstable_mockModule('@actions/cache', () => ({
@@ -22,26 +24,22 @@ const realFs = (await import('fs')).default;
 const fsExports = {...realFs, existsSync: jest.fn()};
 jest.unstable_mockModule('fs', () => ({...fsExports, default: fsExports}));
 
-// Import real cache-utils (with mocked @actions) before mocking it
-const realCacheUtils = await import('../src/cache-utils.js');
-
-jest.unstable_mockModule('../src/cache-utils.js', () => ({
-  ...realCacheUtils,
-  getCacheDirectoryPath: jest.fn()
-}));
-
 const cache = await import('@actions/cache');
 const core = await import('@actions/core');
 const fs = (await import('fs')).default;
-const cacheUtils = await import('../src/cache-utils.js');
 const {run} = await import('../src/cache-save.js');
-const {State} = await import('../src/constants.js');
+import type {CacheEntry} from '../src/cache-utils.js';
+
+function deferred() {
+  let resolve!: () => void;
+  const promise = new Promise<void>(done => {
+    resolve = done;
+  });
+  return {promise, resolve};
+}
 
 describe('cache-save', () => {
-  const primaryKey = 'primary-key';
-
-  let primaryKeyValue: string;
-  let matchedKeyValue: string;
+  let entries: CacheEntry[];
 
   let getBooleanInputSpy: jest.Mock<typeof core.getBooleanInput>;
   let getStateSpy: jest.Mock<typeof core.getState>;
@@ -50,14 +48,21 @@ describe('cache-save', () => {
   let debugSpy: jest.Mock<typeof core.debug>;
   let setFailedSpy: jest.Mock<typeof core.setFailed>;
   let saveCacheSpy: jest.Mock<typeof cache.saveCache>;
-  let getCacheDirectoryPathSpy: jest.Mock<
-    typeof cacheUtils.getCacheDirectoryPath
-  >;
   let existsSpy: jest.Mock<typeof fs.existsSync>;
 
   beforeEach(() => {
-    primaryKeyValue = primaryKey;
-    matchedKeyValue = 'matched-key';
+    entries = [
+      {
+        kind: 'modules',
+        path: 'module_cache_directory',
+        primaryKey: 'modules-primary-key'
+      },
+      {
+        kind: 'build',
+        path: 'build_cache_directory',
+        primaryKey: 'build-primary-key'
+      }
+    ];
 
     getBooleanInputSpy = core.getBooleanInput as jest.Mock<
       typeof core.getBooleanInput
@@ -65,15 +70,7 @@ describe('cache-save', () => {
     getBooleanInputSpy.mockReturnValue(true);
 
     getStateSpy = core.getState as jest.Mock<typeof core.getState>;
-    getStateSpy.mockImplementation((key: string) => {
-      if (key === State.CachePrimaryKey) {
-        return primaryKeyValue;
-      }
-      if (key === State.CacheMatchedKey) {
-        return matchedKeyValue;
-      }
-      return '';
-    });
+    getStateSpy.mockImplementation(() => JSON.stringify(entries));
 
     infoSpy = core.info as jest.Mock<typeof core.info>;
     infoSpy.mockImplementation(() => undefined);
@@ -90,18 +87,12 @@ describe('cache-save', () => {
     saveCacheSpy = cache.saveCache as jest.Mock<typeof cache.saveCache>;
     saveCacheSpy.mockImplementation(() => Promise.resolve(0));
 
-    getCacheDirectoryPathSpy = cacheUtils.getCacheDirectoryPath as jest.Mock<
-      typeof cacheUtils.getCacheDirectoryPath
-    >;
-    getCacheDirectoryPathSpy.mockImplementation(() =>
-      Promise.resolve(['cache_directory_path', 'cache_directory_path'])
-    );
-
     existsSpy = fs.existsSync as jest.Mock<typeof fs.existsSync>;
     existsSpy.mockImplementation(() => true);
   });
 
   afterEach(() => {
+    jest.restoreAllMocks();
     jest.clearAllMocks();
   });
 
@@ -115,78 +106,201 @@ describe('cache-save', () => {
     expect(setFailedSpy).not.toHaveBeenCalled();
   });
 
+  it.each([false, true])(
+    'starts both saves concurrently and waits before exiting (first fails=%s)',
+    async firstFails => {
+      const started = [deferred(), deferred()];
+      const release = [deferred(), deferred()];
+      const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+        return undefined as never;
+      });
+      saveCacheSpy.mockImplementation(async paths => {
+        const index = paths[0] === entries[0].path ? 0 : 1;
+        started[index].resolve();
+        await release[index].promise;
+        if (index === 0 && firstFails) {
+          throw new Error('Module cache unavailable');
+        }
+        return 1;
+      });
+
+      const pending = run(true);
+      try {
+        await Promise.all(started.map(signal => signal.promise));
+        release[0].resolve();
+        // Let the first completion propagate while the second stays blocked.
+        await new Promise<void>(resolve => setImmediate(resolve));
+        expect(exitSpy).not.toHaveBeenCalled();
+      } finally {
+        release.forEach(signal => signal.resolve());
+        await pending;
+      }
+
+      expect(exitSpy).toHaveBeenCalledTimes(1);
+      expect(exitSpy).toHaveBeenCalledWith(0);
+      expect(infoSpy).toHaveBeenCalledWith(
+        `Cache saved with the key: ${entries[1].primaryKey}`
+      );
+      expect(setFailedSpy).not.toHaveBeenCalled();
+    }
+  );
+
   it('does not save cache when there are no cache folders on the disk', async () => {
     existsSpy.mockImplementation(() => false);
 
     await run();
 
-    expect(warningSpy).toHaveBeenCalledWith(
-      'There are no cache folders on the disk'
+    for (const {kind, path} of entries) {
+      expect(infoSpy).toHaveBeenCalledWith(
+        `[warning]${kind} cache folder doesn't exist on disk: ${path}`
+      );
+    }
+    expect(saveCacheSpy).not.toHaveBeenCalled();
+    expect(setFailedSpy).not.toHaveBeenCalled();
+  });
+
+  it.each(['modules', 'build'])(
+    'saves the other cache when the %s directory is missing',
+    async kind => {
+      const missing = entries.find(entry => entry.kind === kind)!;
+      const existing = entries.find(entry => entry.kind !== kind)!;
+      existsSpy.mockImplementation(path => path !== missing.path);
+
+      await run();
+
+      expect(saveCacheSpy).toHaveBeenCalledTimes(1);
+      expect(saveCacheSpy).toHaveBeenCalledWith(
+        [existing.path],
+        existing.primaryKey
+      );
+      expect(setFailedSpy).not.toHaveBeenCalled();
+    }
+  );
+
+  it('does not save cache when no cache entries were prepared', async () => {
+    getStateSpy.mockReturnValue('');
+
+    await run();
+
+    expect(infoSpy).toHaveBeenCalledWith(
+      'Cache keys were not generated. Please check the log messages above for more errors or information'
     );
     expect(saveCacheSpy).not.toHaveBeenCalled();
     expect(setFailedSpy).not.toHaveBeenCalled();
   });
 
-  it('does not save cache when the primary key was not generated', async () => {
-    primaryKeyValue = '';
+  it('does not fail the workflow if the saved state is invalid', async () => {
+    getStateSpy.mockReturnValue('{');
 
     await run();
 
-    expect(infoSpy).toHaveBeenCalledWith(
-      'Primary key was not generated. Please check the log messages above for more errors or information'
-    );
+    expect(warningSpy).toHaveBeenCalledWith(expect.any(String));
     expect(saveCacheSpy).not.toHaveBeenCalled();
     expect(setFailedSpy).not.toHaveBeenCalled();
   });
 
-  it('does not save cache when a cache hit occurred on the primary key', async () => {
-    matchedKeyValue = primaryKey;
+  it('does not save either cache when both primary keys were hit', async () => {
+    for (const entry of entries) {
+      entry.matchedKey = entry.primaryKey;
+    }
 
     await run();
 
-    expect(infoSpy).toHaveBeenCalledWith(
-      `Cache hit occurred on the primary key ${primaryKey}, not saving cache.`
-    );
     expect(saveCacheSpy).not.toHaveBeenCalled();
-    expect(setFailedSpy).not.toHaveBeenCalled();
-  });
-
-  it('saves cache when the primary key differs from the matched key', async () => {
-    await run();
-
-    expect(saveCacheSpy).toHaveBeenCalled();
-    expect(infoSpy).toHaveBeenCalledWith(
-      `Cache saved with the key: ${primaryKey}`
-    );
     expect(warningSpy).not.toHaveBeenCalled();
     expect(setFailedSpy).not.toHaveBeenCalled();
   });
 
-  it('save with -1 cacheId , should not fail workflow', async () => {
-    saveCacheSpy.mockImplementation(() => Promise.resolve(-1));
+  it.each(['modules', 'build'])(
+    'skips only the %s cache when its primary key was hit',
+    async kind => {
+      const hit = entries.find(entry => entry.kind === kind)!;
+      const miss = entries.find(entry => entry.kind !== kind)!;
+      hit.matchedKey = hit.primaryKey;
 
+      await run();
+
+      expect(saveCacheSpy).toHaveBeenCalledTimes(1);
+      expect(saveCacheSpy).toHaveBeenCalledWith([miss.path], miss.primaryKey);
+      expect(warningSpy).not.toHaveBeenCalled();
+      expect(setFailedSpy).not.toHaveBeenCalled();
+    }
+  );
+
+  it('saves both cache directories under separate keys on a cold run', async () => {
     await run();
 
-    expect(saveCacheSpy).toHaveBeenCalled();
-    expect(debugSpy).toHaveBeenCalledWith(
-      `Cache was not saved for the key: ${primaryKey}`
-    );
-    expect(infoSpy).not.toHaveBeenCalledWith(
-      `Cache saved with the key: ${primaryKey}`
-    );
+    expect(saveCacheSpy).toHaveBeenCalledTimes(2);
+    for (const {path, primaryKey} of entries) {
+      expect(saveCacheSpy).toHaveBeenCalledWith([path], primaryKey);
+      expect(infoSpy).toHaveBeenCalledWith(
+        `Cache saved with the key: ${primaryKey}`
+      );
+    }
     expect(warningSpy).not.toHaveBeenCalled();
     expect(setFailedSpy).not.toHaveBeenCalled();
   });
 
-  it('saves with error from toolkit, should not fail workflow', async () => {
-    saveCacheSpy.mockImplementation(() =>
-      Promise.reject(new Error('Unable to reach the service'))
-    );
+  it('saves caches restored from non-primary matches', async () => {
+    for (const entry of entries) {
+      entry.matchedKey = `${entry.primaryKey}-other`;
+    }
 
     await run();
 
-    expect(saveCacheSpy).toHaveBeenCalled();
-    expect(warningSpy).toHaveBeenCalledWith('Unable to reach the service');
+    expect(saveCacheSpy).toHaveBeenCalledTimes(2);
+    expect(warningSpy).not.toHaveBeenCalled();
     expect(setFailedSpy).not.toHaveBeenCalled();
   });
+
+  it.each(['modules', 'build'])(
+    'continues saving when the %s cache reservation fails',
+    async kind => {
+      const failed = entries.find(entry => entry.kind === kind)!;
+      const saved = entries.find(entry => entry.kind !== kind)!;
+      saveCacheSpy.mockImplementation(async paths =>
+        paths[0] === failed.path ? -1 : 1
+      );
+
+      await run();
+
+      expect(saveCacheSpy).toHaveBeenCalledTimes(2);
+      expect(debugSpy).toHaveBeenCalledWith(
+        `Cache was not saved for the key: ${failed.primaryKey}`
+      );
+      expect(infoSpy).not.toHaveBeenCalledWith(
+        `Cache saved with the key: ${failed.primaryKey}`
+      );
+      expect(infoSpy).toHaveBeenCalledWith(
+        `Cache saved with the key: ${saved.primaryKey}`
+      );
+      expect(warningSpy).not.toHaveBeenCalled();
+      expect(setFailedSpy).not.toHaveBeenCalled();
+    }
+  );
+
+  it.each(['modules', 'build'])(
+    'continues saving when the %s cache upload throws',
+    async kind => {
+      const failed = entries.find(entry => entry.kind === kind)!;
+      const saved = entries.find(entry => entry.kind !== kind)!;
+      saveCacheSpy.mockImplementation(async paths => {
+        if (paths[0] === failed.path) {
+          throw new Error('Unable to reach the service');
+        }
+        return 1;
+      });
+
+      await run();
+
+      expect(saveCacheSpy).toHaveBeenCalledTimes(2);
+      expect(warningSpy).toHaveBeenCalledWith(
+        `Save ${kind} cache failed: Unable to reach the service`
+      );
+      expect(infoSpy).toHaveBeenCalledWith(
+        `Cache saved with the key: ${saved.primaryKey}`
+      );
+      expect(setFailedSpy).not.toHaveBeenCalled();
+    }
+  );
 });

__tests__/cache-utils.test.ts

@@ -1,4 +1,14 @@
-import {jest, describe, it, expect, beforeEach, afterAll} from '@jest/globals';
+import {
+  jest,
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  afterAll
+} from '@jest/globals';
+import fs from 'fs';
+import path from 'path';
 
 jest.unstable_mockModule('@actions/exec', () => ({
   exec: jest.fn(),
@@ -84,7 +94,10 @@ describe('getPackageManagerInfo', () => {
     const packageManagerName = 'default';
     const expectedResult = {
       dependencyFilePattern: 'go.mod',
-      cacheFolderCommandList: ['go env GOMODCACHE', 'go env GOCACHE']
+      cacheFolderCommandList: [
+        {kind: 'modules', command: 'go env GOMODCACHE'},
+        {kind: 'build', command: 'go env GOCACHE'}
+      ]
     };
 
     //Act + Assert
@@ -112,16 +125,29 @@ describe('getCacheDirectoryPath', () => {
 
   const validPackageManager: PackageManagerInfo = {
     dependencyFilePattern: 'go.mod',
-    cacheFolderCommandList: ['go env GOMODCACHE', 'go env GOCACHE']
+    cacheFolderCommandList: [
+      {kind: 'modules', command: 'go env GOMODCACHE'},
+      {kind: 'build', command: 'go env GOCACHE'}
+    ]
   };
 
   it('should return path to the cache folders which specified package manager uses', async () => {
     //Arrange
     getExecOutputSpy.mockImplementation(async (commandLine: string) => {
-      return {exitCode: 0, stdout: 'path/to/cache/folder', stderr: ''};
+      return {
+        exitCode: 0,
+        stdout:
+          commandLine === 'go env GOMODCACHE'
+            ? 'path/to/modules'
+            : 'path/to/build',
+        stderr: ''
+      };
     });
 
-    const expectedResult = ['path/to/cache/folder', 'path/to/cache/folder'];
+    const expectedResult = [
+      {kind: 'modules', path: 'path/to/modules'},
+      {kind: 'build', path: 'path/to/build'}
+    ];
 
     //Act + Assert
     return cacheUtils
@@ -129,27 +155,43 @@ describe('getCacheDirectoryPath', () => {
       .then(data => expect(data).toEqual(expectedResult));
   });
 
-  it('should return path to the cache folder if one command return empty str', async () => {
-    //Arrange
-    getExecOutputSpy.mockImplementationOnce(async (commandLine: string) => {
-      return {exitCode: 0, stdout: 'path/to/cache/folder', stderr: ''};
-    });
+  it.each(validPackageManager.cacheFolderCommandList)(
+    'preserves the $kind identity when the other command returns an empty path',
+    async ({kind, command}) => {
+      getExecOutputSpy.mockImplementation(async commandLine => ({
+        exitCode: 0,
+        stdout: commandLine === command ? 'path/to/cache/folder' : '',
+        stderr: ''
+      }));
 
-    getExecOutputSpy.mockImplementationOnce(async (commandLine: string) => {
-      return {exitCode: 0, stdout: '', stderr: ''};
-    });
+      await expect(
+        cacheUtils.getCacheDirectoryPath(validPackageManager)
+      ).resolves.toEqual([{kind, path: 'path/to/cache/folder'}]);
+    }
+  );
 
-    const expectedResult = ['path/to/cache/folder'];
+  it.each(validPackageManager.cacheFolderCommandList)(
+    'preserves the $kind identity when the other command fails',
+    async ({kind, command}) => {
+      getExecOutputSpy.mockImplementation(async commandLine => {
+        if (commandLine !== command) {
+          throw new Error('Could not run go env');
+        }
+        return {exitCode: 0, stdout: 'path/to/cache/folder', stderr: ''};
+      });
 
-    //Act + Assert
-    return cacheUtils
-      .getCacheDirectoryPath(validPackageManager)
-      .then(data => expect(data).toEqual(expectedResult));
-  });
+      await expect(
+        cacheUtils.getCacheDirectoryPath(validPackageManager)
+      ).resolves.toEqual([{kind, path: 'path/to/cache/folder'}]);
+      expect(core.info).toHaveBeenCalledWith(
+        expect.stringContaining('Could not run go env')
+      );
+    }
+  );
 
   it('should throw if the both commands return empty str', async () => {
     getExecOutputSpy.mockImplementation(async (commandLine: string) => {
-      return {exitCode: 10, stdout: '', stderr: ''};
+      return {exitCode: 0, stdout: '', stderr: ''};
     });
 
     //Act + Assert
@@ -158,7 +200,7 @@ describe('getCacheDirectoryPath', () => {
     }).rejects.toThrow();
   });
 
-  it('should throw if the specified package name is invalid', async () => {
+  it('should throw if both commands fail', async () => {
     getExecOutputSpy.mockImplementation(async (commandLine: string) => {
       return {exitCode: 10, stdout: '', stderr: 'Error message'};
     });
@@ -170,6 +212,139 @@ describe('getCacheDirectoryPath', () => {
   });
 });
 
+describe('canRestoreCachesInParallel', () => {
+  const originalPlatform = Object.getOwnPropertyDescriptor(
+    process,
+    'platform'
+  )!;
+  const directoryStat = fs.lstatSync(process.cwd());
+
+  beforeEach(() => {
+    Object.defineProperty(process, 'platform', {value: 'linux'});
+    jest.spyOn(fs, 'lstatSync').mockReturnValue(directoryStat);
+    jest
+      .spyOn(fs, 'realpathSync')
+      .mockImplementation(directory => path.resolve(directory.toString()));
+  });
+
+  afterEach(() => {
+    Object.defineProperty(process, 'platform', originalPlatform);
+    jest.restoreAllMocks();
+  });
+
+  it.each([
+    {modules: 'cache/modules', build: 'cache/build', parallel: true},
+    {modules: 'cache', build: 'cache-build', parallel: true},
+    {modules: 'cache', build: 'cache', parallel: false},
+    {modules: 'cache', build: 'cache/build', parallel: false},
+    {modules: 'cache/modules', build: 'cache', parallel: false},
+    {modules: 'cache', build: 'cache/../cache', parallel: false}
+  ])(
+    'checks overlapping paths: $modules and $build',
+    ({modules, build, parallel}) => {
+      expect(
+        cacheUtils.canRestoreCachesInParallel([
+          {kind: 'modules', path: modules},
+          {kind: 'build', path: build}
+        ])
+      ).toBe(parallel);
+    }
+  );
+
+  it('allows concurrent Windows restores with disjoint paths', () => {
+    Object.defineProperty(process, 'platform', {value: 'win32'});
+
+    expect(
+      cacheUtils.canRestoreCachesInParallel([
+        {kind: 'modules', path: 'cache/modules'},
+        {kind: 'build', path: 'cache/build'}
+      ])
+    ).toBe(true);
+  });
+
+  it.each(['darwin', 'win32'])(
+    'handles case-insensitive paths conservatively on %s',
+    platform => {
+      Object.defineProperty(process, 'platform', {value: platform});
+
+      expect(
+        cacheUtils.canRestoreCachesInParallel([
+          {kind: 'modules', path: 'cache'},
+          {kind: 'build', path: 'CACHE/build'}
+        ])
+      ).toBe(false);
+    }
+  );
+
+  it.each([true, false])(
+    'serializes symlink aliases with missing cache directories (overlap=%s)',
+    overlap => {
+      const alias = path.resolve('alias');
+      const target = path.resolve('target');
+      jest.spyOn(fs, 'lstatSync').mockImplementation(directory => {
+        if (directory !== alias && directory !== target) {
+          throw Object.assign(new Error('Missing path'), {code: 'ENOENT'});
+        }
+        return directoryStat;
+      });
+      jest.spyOn(fs, 'realpathSync').mockReturnValue(target);
+
+      expect(
+        cacheUtils.canRestoreCachesInParallel([
+          {kind: 'modules', path: path.join(alias, 'modules')},
+          {
+            kind: 'build',
+            path: path.join(target, overlap ? 'modules/build' : 'build')
+          }
+        ])
+      ).toBe(false);
+    }
+  );
+
+  it.each(['nested alias', 'alias through module cache'])(
+    'serializes restores when the %s resolves outside the module cache',
+    scenario => {
+      const modules = path.resolve('modules');
+      const target = path.resolve('external-build');
+      const alias = path.join(modules, 'build-link');
+      const build =
+        scenario === 'nested alias'
+          ? path.join(alias, 'cache')
+          : path.resolve('build-alias', 'cache');
+      jest.spyOn(fs, 'realpathSync').mockImplementation(directory => {
+        const absolute = path.resolve(directory.toString());
+        if (absolute === build) {
+          return path.join(target, 'cache');
+        }
+        if (absolute === path.dirname(build)) {
+          return scenario === 'nested alias' ? target : alias;
+        }
+        return absolute;
+      });
+
+      expect(
+        cacheUtils.canRestoreCachesInParallel([
+          {kind: 'modules', path: modules},
+          {kind: 'build', path: build}
+        ])
+      ).toBe(false);
+    }
+  );
+
+  it('falls back to sequential restores when path resolution fails', () => {
+    jest.spyOn(fs, 'realpathSync').mockImplementation(() => {
+      throw new Error('Cannot resolve path');
+    });
+
+    expect(
+      cacheUtils.canRestoreCachesInParallel([
+        {kind: 'modules', path: 'cache/modules'},
+        {kind: 'build', path: 'cache/build'}
+      ])
+    ).toBe(false);
+  });
+});
+
 describe('isCacheFeatureAvailable', () => {
   //Arrange
   const isFeatureAvailableSpy = cache.isFeatureAvailable as jest.Mock<