build(ci): optimize AppMap test binaries cache and eliminate save churn

Prevent the GitHub Actions AppMap test binaries cache from growing
unboundedly, and completely eliminate redundant cache save churn (zipping
and network uploads) on steady-state runs.

- Transition from `actions/cache@v5` to explicit, decoupled
  `actions/cache/restore@v5` and `actions/cache/save@v5` steps.
- Add `id: restore-cache` to track the matched key retrieved from GitHub.
- Create `.github/workflows/clean-cache.js` to parse version numbers of
  surviving binaries, prune old releases, delete test stub files, and
  export a SHA-256 hash of the final stable binaries set to `$GITHUB_OUTPUT`.
- Configure the `Save AppMap test binaries cache` step to compare the new
  hash-based key against the matched/restored key. If they match, the step
  is completely skipped, saving network bandwidth and runner CPU.
- Configure steps with `continue-on-error: true` to defensively guard the
  build from any unexpected script/cache failures.
- Add descriptive comments in the workflow explaining the decoupled restore/save
  setup, the pruning logic, and the matched-key conditional optimization.

Author: dividedmind

.github/workflows/build.yml

@@ -45,11 +45,15 @@ jobs:
               with:
                   cache-disabled: true
 
-            - name: Cache AppMap test binaries
-              uses: actions/cache@v5
+            # Restore cached AppMap/Scanner test binaries from previous runs using restore-keys.
+            # We explicitly use actions/cache/restore (instead of actions/cache) to decouple
+            # restoring and saving, allowing us to only save a new cache when new versions are downloaded.
+            - name: Restore AppMap test binaries cache
+              id: restore-cache
+              uses: actions/cache/restore@v5
               with:
                   path: ~/.cache/appmap-test
-                  key: appmap-test-binaries-${{ runner.os }}-${{ github.run_id }}
+                  key: appmap-test-binaries-${{ runner.os }}-initial
                   restore-keys: appmap-test-binaries-${{ runner.os }}-
 
             # https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#rate-limits-for-requests-from-github-actions
@@ -73,6 +77,26 @@ jobs:
                       build/reports/
                       **/build/reports/
 
+            # Clean up the cache directory before saving to keep it lean.
+            # The script sorts downloaded binaries by SemVer, deletes old versions,
+            # prunes test stubs, and outputs a SHA-256 hash of the surviving stable files.
+            - name: Clean AppMap test binaries cache
+              id: clean-cache
+              if: always()
+              continue-on-error: true
+              run: node .github/workflows/clean-cache.js
+
+            # Save the cache with the unique hash of the preserved binaries.
+            # To avoid CPU and network upload churn on identical states (since GitHub caches are immutable),
+            # we explicitly skip saving if the newly generated key matches the key we restored from.
+            - name: Save AppMap test binaries cache
+              if: always() && steps.clean-cache.outputs.cache_hash != '' && steps.clean-cache.outputs.cache_hash != 'empty' && steps.restore-cache.outputs.cache-matched-key != format('appmap-test-binaries-{0}-{1}', runner.os, steps.clean-cache.outputs.cache_hash)
+              continue-on-error: true
+              uses: actions/cache/save@v5
+              with:
+                  path: ~/.cache/appmap-test
+                  key: appmap-test-binaries-${{ runner.os }}-${{ steps.clean-cache.outputs.cache_hash }}
+
             - name: Save AppMaps
               uses: actions/cache/save@v5
               if: runner.os == 'Linux' && matrix.platform_version == '251'

.github/workflows/clean-cache.js

@@ -0,0 +1,128 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+function parseSemVer(versionStr) {
+    if (versionStr.startsWith('v')) {
+        versionStr = versionStr.substring(1);
+    }
+    const [main, prerelease] = versionStr.split('-');
+    const parts = main.split('.').map(Number);
+    return {
+        parts,
+        prerelease: prerelease || null
+    };
+}
+
+function compareSemVer(v1, v2) {
+    const s1 = parseSemVer(v1);
+    const s2 = parseSemVer(v2);
+
+    for (let i = 0; i < 3; i++) {
+        const p1 = s1.parts[i] || 0;
+        const p2 = s2.parts[i] || 0;
+        if (p1 !== p2) {
+            return p1 - p2;
+        }
+    }
+
+    if (s1.prerelease && !s2.prerelease) return -1;
+    if (!s1.prerelease && s2.prerelease) return 1;
+
+    if (s1.prerelease && s2.prerelease) {
+        return s1.prerelease.localeCompare(s2.prerelease, undefined, { numeric: true, sensitivity: 'base' });
+    }
+
+    return 0;
+}
+
+const cacheDir = process.argv[2] || path.join(os.homedir(), '.cache', 'appmap-test');
+
+console.log(`Target cache directory: ${cacheDir}`);
+
+if (!fs.existsSync(cacheDir)) {
+    console.log(`Cache directory does not exist. Nothing to clean.`);
+    if (process.env.GITHUB_OUTPUT) {
+        fs.appendFileSync(process.env.GITHUB_OUTPUT, `cache_hash=empty\n`);
+    }
+    process.exit(0);
+}
+
+try {
+    const files = fs.readdirSync(cacheDir);
+    // Matches names like appmap-linux-x64-1.2.3 and appmap-win-x64-1.2.3.exe
+    // The lazy quantifier "+?" ensures we do not greedily swallow .exe if present
+    const nameRegex = /^(appmap|scanner)-([a-z0-9]+)-([a-z0-9]+)-([0-9a-zA-Z_.-]+?)(?:\.exe)?$/i;
+
+    const groups = {};
+
+    for (const file of files) {
+        const match = file.match(nameRegex);
+        if (!match) {
+            console.log(`Skipping non-matching file: ${file}`);
+            continue;
+        }
+
+        const tool = match[1].toLowerCase();
+        const platform = match[2].toLowerCase();
+        const arch = match[3].toLowerCase();
+        const version = match[4];
+
+        const key = `${tool}-${platform}-${arch}`;
+        if (!groups[key]) {
+            groups[key] = [];
+        }
+        groups[key].push({
+            filename: file,
+            version: version
+        });
+    }
+
+    for (const key of Object.keys(groups)) {
+        const groupFiles = groups[key];
+        if (groupFiles.length <= 1) {
+            console.log(`Group ${key} has ${groupFiles.length} file(s). No cleanup needed.`);
+            continue;
+        }
+
+        // Sort descending (highest version first)
+        groupFiles.sort((a, b) => compareSemVer(b.version, a.version));
+
+        const keep = groupFiles[0];
+        console.log(`Group ${key}: keeping ${keep.filename} (${keep.version})`);
+
+        for (let i = 1; i < groupFiles.length; i++) {
+            const discard = groupFiles[i];
+            const fullPath = path.join(cacheDir, discard.filename);
+            console.log(`  Deleting obsolete version: ${discard.filename} (${discard.version})`);
+            try {
+                fs.unlinkSync(fullPath);
+            } catch (err) {
+                console.error(`  Failed to delete ${discard.filename}:`, err);
+            }
+        }
+    }
+
+    // Compute a hash of the remaining matching files to uniquely identify this cache state.
+    // Since we delete obsolete files, stub files, etc., the remaining files will be exactly
+    // the stable versions we want to cache.
+    const remainingFiles = fs.readdirSync(cacheDir)
+        .filter(f => nameRegex.test(f))
+        .sort();
+
+    const hashInput = remainingFiles.join(',');
+    const hash = crypto.createHash('sha256').update(hashInput).digest('hex');
+
+    console.log(`Remaining cache files: ${remainingFiles.join(', ') || '(none)'}`);
+    console.log(`Generated cache hash: ${hash}`);
+
+    if (process.env.GITHUB_OUTPUT) {
+        fs.appendFileSync(process.env.GITHUB_OUTPUT, `cache_hash=${hash}\n`);
+    }
+
+    console.log('Cache cleanup complete.');
+} catch (err) {
+    console.error('Error during cache cleanup:', err);
+    process.exit(1);
+}