@htekdev/actions-debugger 1.0.14 → 1.0.16

package/dist/db/search.js

@@ -112,9 +112,11 @@ function matchEntry(entry, input) {
         }
     }
     // 3. Title keyword matching (lowest confidence)
+    // Require words > 5 chars to avoid false positives from common short words
+    // (e.g. "text", "that", "some", "runs", "jobs" appearing in unrelated inputs)
     const inputLower = input.toLowerCase();
     const titleWords = entry.title.toLowerCase().split(/\s+/);
-    const matchingWords = titleWords.filter(w => w.length > 3 && inputLower.includes(w));
+    const matchingWords = titleWords.filter(w => w.length > 5 && inputLower.includes(w));
     if (matchingWords.length >= 2) {
         bestScore = Math.max(bestScore, 20 + matchingWords.length * 5);
     }

package/dist/db/search.js.map

@@ -1 +1 @@
-{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/db/search.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,yEAAyE;AACzE,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEhC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,EAAiB,EACjB,YAAoB,EACpB,aAAqB,CAAC;IAEtB,4BAA4B;IAC5B,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;IACtD,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACvC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACtG,CAAC;IACH,CAAC;IAED,2BAA2B;IAC3B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAC1C,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,EAAiB,EACjB,KAAa,EACb,OAIC;IAED,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,EAAE,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAC9D,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACvC,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrE,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;QAC/B,gBAAgB;QAChB,IAAI,QAAQ,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ;YAAE,SAAS;QACtD,IAAI,QAAQ,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ;YAAE,SAAS;QAEtD,IAAI,KAAK,GAAG,CAAC,CAAC;QAEd,+BAA+B;QAC/B,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QAC7C,IAAI,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YACpC,KAAK,IAAI,GAAG,CAAC;QACf,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;gBAC9B,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;oBAAE,KAAK,IAAI,EAAE,CAAC;YAC7C,CAAC;QACH,CAAC;QAED,YAAY;QACZ,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;YACzC,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAAE,KAAK,IAAI,EAAE,CAAC;QAC/C,CAAC;QAED,mBAAmB;QACnB,MAAM,cAAc,GAAG,KAAK,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;QACtD,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,IAAI,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,KAAK,IAAI,EAAE,CAAC;QACjD,CAAC;QAED,YAAY;QACZ,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QACzC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,KAAK,IAAI,EAAE,CAAC;QAC3C,CAAC;QAED,uBAAuB;QACvB,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,cAAc,IAAI,EAAE,EAAE,CAAC;YAC7C,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC3C,KAAK,IAAI,EAAE,CAAC;gBACZ,MAAM;YACR,CAAC;QACH,CAAC;QAED,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAC1C,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CAAC,KAAiB,EAAE,KAAa;IAClD,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,iDAAiD;IACjD,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,GAAG,CAAC;YACnC,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAC5C,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnB,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;YACvB,SAAS;QACX,CAAC;IACH,CAAC;IAED,kCAAkC;IAClC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,cAAc,IAAI,EAAE,EAAE,CAAC;QAC7C,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACtC,CAAC;QACD,gBAAgB;QAChB,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,gDAAgD;IAChD,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACvC,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1D,MAAM,aAAa,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IACrF,IAAI,aAAa,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAC9B,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,GAAG,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/db/search.ts"],"names":[],"mappings":"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"}

package/dist/tools/suggest-fix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"suggest-fix.d.ts","sourceRoot":"","sources":["../../src/tools/suggest-fix.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGhE;;GAEG;AACH,wBAAgB,UAAU,CACxB,EAAE,EAAE,aAAa,EACjB,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,GAChB,UAAU,EAAE,CAUd;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CA8CjE"}
+{"version":3,"file":"suggest-fix.d.ts","sourceRoot":"","sources":["../../src/tools/suggest-fix.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGhE;;GAEG;AACH,wBAAgB,UAAU,CACxB,EAAE,EAAE,aAAa,EACjB,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,GAChB,UAAU,EAAE,CAed;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CA8CjE"}

package/dist/tools/suggest-fix.js

@@ -8,7 +8,11 @@ import { lookupByPattern, searchByKeyword } from "../db/search.js";
 export function suggestFix(db, errorContext, category) {
     // Try regex matching first
     let results = lookupByPattern(db, errorContext, 5);
-    // If no regex matches, try keyword search
+    // Apply category filter if provided (pattern matching doesn't filter by category)
+    if (category) {
+        results = results.filter(r => r.entry.category === category);
+    }
+    // If no matches after filtering, fall back to keyword search with category filter
     if (results.length === 0) {
         results = searchByKeyword(db, errorContext, { category, maxResults: 5 });
     }

package/dist/tools/suggest-fix.js.map

@@ -1 +1 @@
-{"version":3,"file":"suggest-fix.js","sourceRoot":"","sources":["../../src/tools/suggest-fix.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEnE;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,EAAiB,EACjB,YAAoB,EACpB,QAAiB;IAEjB,2BAA2B;IAC3B,IAAI,OAAO,GAAG,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC;IAEnD,0CAA0C;IAC1C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAqB;IACvD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,4CAA4C;YAC5C,EAAE;YACF,UAAU;YACV,2DAA2D;YAC3D,+DAA+D;YAC/D,mFAAmF;SACpF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,KAAK,GAAG;QACZ,qBAAqB,IAAI,CAAC,KAAK,EAAE;QACjC,EAAE;QACF,iBAAiB,IAAI,CAAC,QAAQ,oBAAoB,IAAI,CAAC,QAAQ,EAAE;QACjE,EAAE;QACF,iBAAiB;QACjB,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE;QACtB,EAAE;QACF,UAAU;QACV,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;KAChB,CAAC;IAEF,IAAI,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,6BAA6B,CAAC,CAAC;QAC9C,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,4BAA4B,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"suggest-fix.js","sourceRoot":"","sources":["../../src/tools/suggest-fix.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEnE;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,EAAiB,EACjB,YAAoB,EACpB,QAAiB;IAEjB,2BAA2B;IAC3B,IAAI,OAAO,GAAG,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC;IAEnD,kFAAkF;IAClF,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;IAC/D,CAAC;IAED,kFAAkF;IAClF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAqB;IACvD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,4CAA4C;YAC5C,EAAE;YACF,UAAU;YACV,2DAA2D;YAC3D,+DAA+D;YAC/D,mFAAmF;SACpF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,KAAK,GAAG;QACZ,qBAAqB,IAAI,CAAC,KAAK,EAAE;QACjC,EAAE;QACF,iBAAiB,IAAI,CAAC,QAAQ,oBAAoB,IAAI,CAAC,QAAQ,EAAE;QACjE,EAAE;QACF,iBAAiB;QACjB,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE;QACtB,EAAE;QACF,UAAU;QACV,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;KAChB,CAAC;IAEF,IAAI,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,6BAA6B,CAAC,CAAC;QAC9C,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,4BAA4B,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/errors/caching-artifacts/cache-key-too-long.yml

@@ -0,0 +1,93 @@
+id: caching-artifacts-015
+title: "actions/cache Key Exceeds 512-Character Limit — Cache Action Fails"
+category: caching-artifacts
+severity: error
+tags:
+  - actions/cache
+  - cache-key
+  - key-length
+  - 512-char
+  - restore
+  - save
+patterns:
+  - regex: "Cache key is too long"
+    flags: "i"
+  - regex: "cache.*key.*exceed|key.*too long"
+    flags: "i"
+error_messages:
+  - "Cache key is too long"
+  - "Error: Cache key is too long (max: 512 characters)"
+root_cause: |
+  The `actions/cache` action enforces a maximum cache key length of **512 characters**.
+  When the `key:` or any `restore-keys:` entry exceeds this limit, the action fails
+  immediately with "Cache key is too long" — no cache is saved or restored.
+
+  This limit is hit most often when developers concatenate multiple dynamic values into
+  a single key without length management:
+  - Long branch names (`github.ref_name` on feature branches can be 60+ chars)
+  - Full commit SHAs (`github.sha` = 40 chars)
+  - `github.event_name` + `github.actor` + `github.run_id` (11+ chars) combined with a
+    long dependency hash
+  - `toJSON()` output of a context object embedded directly into the key
+  - Monorepo setups that include multiple file paths in a single hashFiles() call with
+    deeply nested directory structures
+
+  The 512-character limit applies per key entry, including each `restore-keys` line.
+  Keys that would cause the action to fail entirely, leaving the job without any cache.
+
+  Source: GitHub Docs — actions/cache usage limits
+fix: |
+  Shorten the cache key to stay under 512 characters. The primary strategies are:
+
+  1. **Use `hashFiles()` for dependency content** — hashing a lockfile produces a
+     consistent 64-character SHA256 output regardless of the file's contents.
+  2. **Remove redundant dynamic parts** — `github.run_id` is almost never appropriate
+     in a cache key (it changes every run, defeating cache sharing entirely).
+  3. **Truncate long branch names** — use `github.ref_name` only if needed, or hash it.
+  4. **Avoid embedding JSON strings** — never embed `toJSON()` outputs directly in keys.
+  5. **Use `restore-keys` for partial matching** instead of encoding multiple variants
+     into one long key.
+fix_code:
+  - language: yaml
+    label: "Broken — key too long from excessive concatenation"
+    code: |
+      # ❌ BROKEN: Key may exceed 512 chars with long branch names + run context
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-${{ github.workflow }}-${{ github.ref }}-${{ github.sha }}-${{ github.run_id }}-${{ hashFiles('**/package-lock.json', '**/yarn.lock', '**/pnpm-lock.yaml', 'packages/*/package-lock.json') }}
+  - language: yaml
+    label: "Fixed — concise key using OS + short context + lockfile hash"
+    code: |
+      # ✅ FIXED: OS prefix + workflow + lockfile hash — short and deterministic
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-
+  - language: yaml
+    label: "Fixed — long branch names: hash github.ref_name if needed"
+    code: |
+      # ✅ FIXED: When you need branch-scoped caches, hash the ref instead of embedding it
+      - name: Compute short ref hash
+        id: ref-hash
+        run: echo "value=$(echo '${{ github.ref }}' | sha256sum | cut -c1-16)" >> $GITHUB_OUTPUT
+
+      - uses: actions/cache@v4
+        with:
+          path: .build-cache
+          key: build-${{ runner.os }}-${{ steps.ref-hash.outputs.value }}-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            build-${{ runner.os }}-
+prevention:
+  - "Keep cache keys under 400 characters to leave comfortable headroom below the 512-char limit."
+  - "Never include `github.run_id` or `github.run_number` in cache keys — these values change every run and prevent cache hits entirely."
+  - "Prefer `hashFiles()` over embedding actual file content or long path lists into keys — the hash output is always 64 chars."
+  - "When branch-scoped caching is needed, hash `github.ref` to a short prefix rather than embedding the full ref string."
+  - "Test key length in a debug step: `run: echo \"Key length: $(echo -n '${{ KEY_EXPRESSION }}' | wc -c)\"`"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache"
+    label: "GitHub Docs: Cache restrictions and usage limits (512-char key limit)"
+  - url: "https://github.com/actions/cache#inputs"
+    label: "actions/cache inputs — key and restore-keys documentation"

package/errors/caching-artifacts/cache-path-not-exist-skipped.yml

@@ -0,0 +1,152 @@
+id: caching-artifacts-017
+title: "actions/cache Path Validation Error — Specified Path Does Not Exist, Cache Skipped"
+category: caching-artifacts
+severity: warning
+tags:
+  - cache
+  - path
+  - path-validation
+  - cache-miss
+  - warning
+  - actions-cache
+patterns:
+  - regex: "Path Validation Error.*Path.*specified.*action.*caching.*do.*not exist"
+    flags: "i"
+  - regex: "Warning.*Path.*caching.*do.*not exist.*no cache.*saved"
+    flags: "i"
+  - regex: "no cache.*being saved.*path.*not exist"
+    flags: "i"
+error_messages:
+  - "Warning: Path Validation Error: Path(s) specified in the action for caching do(es) not exist, hence no cache is being saved."
+root_cause: |
+  `actions/cache` validates that all paths listed under the `path:` key actually
+  exist on disk **at the time the `Post cache` step runs** (the post-job cleanup
+  step that performs the cache save). If any path does not exist, the action logs a
+  warning and **silently skips the cache save entirely** — no cache entry is written
+  even if other listed paths do exist.
+
+  **Common causes:**
+
+  1. **Conditional install step** — the path is only created when a specific install
+     step runs (e.g., `npm ci` or `pip install`), but the cache step's `key` matched
+     a previous cache, so the install step was skipped. The path therefore doesn't
+     exist when the post step runs.
+
+  2. **Wrong working directory** — the `path:` is relative (e.g., `node_modules`)
+     but the working directory for the run step differs from where `actions/cache`
+     expects to find it.
+
+  3. **Build output cached too early** — the `path:` references build output that
+     hasn't been generated yet (e.g., caching `dist/` before the build step runs).
+
+  4. **Typo in path** — a simple typo (e.g., `node-modules` vs `node_modules`) means
+     the directory is never created under that name.
+
+  5. **Cross-OS path format** — Windows backslash vs Linux forward slash mismatch
+     when the same workflow runs on multiple OS targets.
+
+  The action exits 0 (no failure), making this a **silent failure** — the workflow
+  appears to succeed, but the cache is never saved. Subsequent runs always experience
+  a full cache miss, causing slower CI without any visible error.
+
+  Source: mkdocs-material issue#7990, actions/cache documentation
+fix: |
+  1. **Verify the path exists before relying on it** — add a diagnostic step that
+     lists the directory structure before the cache save to confirm paths are present.
+
+  2. **Always run the install step** — do not skip install steps based on
+     `cache-hit == 'true'`. Instead, use `cache-hit` to skip the install when the
+     restore succeeded, but still let the cache post step validate paths:
+
+     ```yaml
+     - uses: actions/cache@v4
+       id: cache-node
+       with:
+         path: node_modules
+         key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
+
+     - run: npm ci
+       if: steps.cache-node.outputs.cache-hit != 'true'
+     ```
+
+  3. **Use `setup-node` with caching** — instead of managing cache manually,
+     `actions/setup-node` with `cache: 'npm'` handles path validation internally.
+
+  4. **Check for path typos** — confirm the literal path string matches exactly
+     what is created on disk (case-sensitive on Linux).
+fix_code:
+  - language: yaml
+    label: "Correct pattern — run install only on cache miss, cache path always present"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/cache@v4
+              id: npm-cache
+              with:
+                path: ~/.npm        # Cache the npm cache dir — always exists
+                key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+                restore-keys: |
+                  ${{ runner.os }}-npm-
+
+            # Always run npm ci so node_modules always exists for the cache post step
+            - run: npm ci
+
+            # ❌ Wrong — skipping npm ci on cache hit means node_modules may not exist
+            # - run: npm ci
+            #   if: steps.npm-cache.outputs.cache-hit != 'true'
+  - language: yaml
+    label: "Use setup-node built-in cache instead of manual actions/cache"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # setup-node handles path validation and cache lifecycle correctly
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '20'
+                cache: 'npm'   # Manages npm cache path validation internally
+
+            - run: npm ci
+  - language: yaml
+    label: "Debug step — print path existence before cache save"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/cache@v4
+              with:
+                path: |
+                  ~/.cache/pip
+                  .venv
+                key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
+
+            - run: pip install -r requirements.txt --target .venv
+
+            # Diagnostic — verify paths exist before cache post step runs
+            - name: Verify cache paths
+              run: |
+                echo "~/.cache/pip exists: $(test -d ~/.cache/pip && echo YES || echo NO)"
+                echo ".venv exists: $(test -d .venv && echo YES || echo NO)"
+prevention:
+  - "Always ensure every path listed under `actions/cache path:` is unconditionally created during the job — do not gate install steps on cache-hit in a way that leaves paths missing."
+  - "Prefer `setup-*` actions with their built-in `cache:` input over raw `actions/cache` — they manage path validation and lifecycle correctly."
+  - "Add a diagnostic step after your install/build steps to verify that each cached path exists before relying on the cache post step."
+  - "Use absolute paths (e.g., `~/.npm`, `~/.cache/pip`) rather than relative paths when caching language package caches."
+  - "Enable `ACTIONS_RUNNER_DEBUG: true` in repository secrets to get verbose cache-step output that reveals path validation details."
+docs:
+  - url: "https://github.com/actions/cache/blob/main/README.md"
+    label: "actions/cache README — path and key documentation"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Docs: Caching dependencies to speed up workflows"
+  - url: "https://github.com/squidfunk/mkdocs-material/issues/7990"
+    label: "mkdocs-material#7990 — Path Validation Error real-world example"

package/errors/caching-artifacts/cache-save-same-key-html-conflict.yml

@@ -0,0 +1,109 @@
+id: caching-artifacts-020
+title: "actions/cache save fails with HTML error when identical key already exists for same ref"
+category: caching-artifacts
+severity: warning
+tags:
+  - cache
+  - cache-save
+  - 409-conflict
+  - pr-ref
+  - retry-loop
+  - key-collision
+patterns:
+  - regex: "Attempt \\d+ of \\d+ failed with error.*Unexpected token '<'"
+    flags: "i"
+  - regex: "cache.*already exists.*ref|key.*already.*saved.*ref"
+    flags: "i"
+  - regex: "Unexpected token '<'.*DOCTYPE|<!DOCTYPE.*cache"
+    flags: "im"
+error_messages:
+  - "Attempt 1 of 5 failed with error: Unexpected token '<', \"<!DOCTYPE ...\" is not valid JSON"
+  - "Failed to save: Unexpected token '<'"
+  - "Attempt 5 of 5 failed with error: Unexpected token '<'"
+root_cause: |
+  actions/cache v3 and v4 use the GitHub cache service to save cache entries
+  scoped to a key + ref combination. When a workflow run saves a cache entry
+  under a given key for refs/pull/N/merge, subsequent runs against the same
+  PR ref that produce the EXACT same cache key will attempt to save again.
+
+  The cache service rejects the duplicate write with an HTTP 409 response.
+  However, the response body is an HTML error page rather than a JSON error
+  object. The cache toolkit's retry logic does not recognize the HTML response
+  as a permanent, non-retryable conflict — it treats it as a transient network
+  error and retries up to 5 times with exponential backoff (~20-30 seconds
+  total wasted time before all attempts are exhausted).
+
+  The cache entry itself is not updated or overwritten (actions/cache v4 uses
+  immutable cache entries), but the 5-retry failure loop causes the post-job
+  cleanup step to report errors in the workflow log, adding noise and wasted
+  time to every successive commit pushed to a long-lived PR branch.
+
+  This is most visible in actions that use deterministic, content-addressed
+  cache keys (e.g., a Bun binary cache keyed on its checksum) where every
+  run produces the same key for the same PR.
+fix: |
+  Add a dynamic component to the cache key that changes between runs so that
+  consecutive runs on the same PR ref never attempt to save over an existing
+  entry. Using ${{ github.run_id }} or ${{ github.run_attempt }} as part of
+  the key ensures each run gets a unique save slot.
+
+  If you specifically want a stable cache that all runs on a PR share (only
+  save once), use restore-keys for lookup and add a save condition so the
+  save step only runs when a cache miss occurred:
+
+    if: steps.cache.outputs.cache-hit != 'true'
+
+  For large dependency caches, prefer restore-keys with a prefix approach so
+  partial hits are possible and saves only happen when the lockfile changes.
+fix_code:
+  - language: yaml
+    label: "Use restore-keys + conditional save to avoid same-key conflicts"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Cache Bun binary
+              id: bun-cache
+              uses: actions/cache@v4
+              with:
+                path: ~/.bun/install/cache
+                # Lock file hash in key + restore-keys for partial fallback
+                key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb') }}
+                restore-keys: |
+                  ${{ runner.os }}-bun-
+
+            # Only save if there was a cache miss — avoids HTML 409 on same PR
+            - name: Save Bun cache (miss only)
+              if: steps.bun-cache.outputs.cache-hit != 'true'
+              uses: actions/cache/save@v4
+              with:
+                path: ~/.bun/install/cache
+                key: ${{ steps.bun-cache.outputs.cache-primary-key }}
+  - language: yaml
+    label: "Include run_id in cache key to guarantee a unique save slot per run"
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: .build/
+          # run_id makes every run's save unique — no 409 conflicts
+          key: ${{ runner.os }}-build-${{ hashFiles('**/*.go') }}-${{ github.run_id }}
+          restore-keys: |
+            ${{ runner.os }}-build-${{ hashFiles('**/*.go') }}-
+            ${{ runner.os }}-build-
+prevention:
+  - "Use restore-keys for cache lookup and actions/cache/save with an if: cache-hit != 'true' guard to skip redundant saves"
+  - "Avoid fully deterministic cache keys that never change between runs on the same PR; add a per-run or per-lockfile component"
+  - "Treat 'Unexpected token <' in cache post-job as a 409 key-collision signal, not a network error"
+  - "Use actions/cache v4's separate save/restore actions for fine-grained control over when saves actually occur"
+docs:
+  - url: "https://github.com/actions/cache"
+    label: "actions/cache — GitHub Actions cache action documentation"
+  - url: "https://github.com/actions/cache/blob/main/tips-and-workarounds.md"
+    label: "actions/cache — Tips and workarounds (immutability, restore-keys)"
+  - url: "https://github.com/anthropics/claude-code-action/issues/1252"
+    label: "anthropics/claude-code-action#1252 — Cache save HTML 409 on same PR ref"
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache"
+    label: "GitHub Docs — Cache restrictions and immutability"

package/errors/caching-artifacts/docker-buildx-gha-cache-capacity.yml

@@ -0,0 +1,107 @@
+id: caching-artifacts-019
+title: "Docker BuildKit type=gha cache silently stops working when repo cache is full"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - docker
+  - buildkit
+  - buildx
+  - cache
+  - gha-cache
+  - type-gha
+patterns:
+  - regex: "cache export feature is currently not supported"
+    flags: "i"
+  - regex: "failed to fetch remote cache"
+    flags: "i"
+  - regex: "importing cache manifest from gha"
+    flags: "i"
+  - regex: "exporting cache.*SKIPPED"
+    flags: "i"
+error_messages:
+  - "WARNING: cache export feature is currently not supported for docker driver"
+  - "#0 importing cache manifest from gha"
+  - "failed to fetch remote cache: importing cache manifest: not found"
+  - "WARNING: failed to get cache: httpReadSeeker: failed open: unexpected status code 410 Gone"
+root_cause: |
+  Docker BuildKit supports storing build layer cache directly in GitHub Actions
+  cache (type=gha) via docker/build-push-action. This cache backend shares the
+  same 10 GB per-repository cache limit enforced by actions/cache.
+
+  When large images or many active branches push their layer caches, the 10 GB
+  limit is reached. GitHub silently evicts the oldest cache entries using LRU
+  eviction. On the next run the build starts from scratch with no layers cached,
+  but the workflow still reports success — the only symptom is a much slower
+  build with no warning.
+
+  Additional silent failure mode: using the default docker driver (not
+  docker-container) causes "cache export feature is currently not supported"
+  warnings that are easy to miss. The type=gha backend requires the
+  docker-container (or docker-buildx) driver and the containerd image store.
+
+  Per-key limits: individual cache entries exceeding ~5 GB may fail to write
+  completely, resulting in partial caches that are never reusable on restore.
+fix: |
+  Use mode=min so that only the final image layer is cached rather than all
+  intermediate build stages. This dramatically reduces cache pressure.
+
+  For large production images that need full layer caching, use
+  cache-to: type=registry pointing to GHCR (free for public repos) to bypass
+  the 10 GB GitHub Actions cache limit entirely.
+
+  Always configure setup-buildx-action before build-push-action to ensure
+  the docker-container driver is active and type=gha export is supported.
+fix_code:
+  - language: yaml
+    label: "Use mode=min and ensure docker-container driver is configured"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v3
+              # docker-container driver is the default for setup-buildx-action
+              # Required for type=gha cache export to work at all
+
+            - name: Build and push
+              uses: docker/build-push-action@v6
+              with:
+                push: true
+                tags: ghcr.io/${{ github.repository }}:latest
+                cache-from: type=gha
+                cache-to: type=gha,mode=min  # min = final layer only, not all stages
+  - language: yaml
+    label: "Use GHCR registry cache to bypass the 10 GB GitHub Actions cache limit"
+    code: |
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push with registry cache
+        uses: docker/build-push-action@v6
+        with:
+          push: true
+          tags: ghcr.io/${{ github.repository }}:latest
+          cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache
+          cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache,mode=max
+prevention:
+  - "Always add docker/setup-buildx-action before docker/build-push-action to enable type=gha"
+  - "Prefer mode=min for type=gha to minimize cache footprint per build"
+  - "Monitor cache usage in Settings > Actions > Caches — eviction is silent until builds slow down"
+  - "Use scope parameter to separate caches per branch: cache-to: type=gha,scope=${{ github.ref_name }},mode=min"
+  - "For large production images prefer type=registry (GHCR) over type=gha to avoid the 10 GB cap"
+docs:
+  - url: "https://docs.docker.com/build/ci/github-actions/cache/#github-cache"
+    label: "Docker Docs — GitHub Actions cache backend for BuildKit"
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy"
+    label: "GitHub Docs — Cache usage limits and eviction policy (10 GB limit)"
+  - url: "https://github.com/docker/build-push-action/issues/818"
+    label: "docker/build-push-action#818 — type=gha cache eviction behavior"
+  - url: "https://github.com/docker/setup-buildx-action"
+    label: "docker/setup-buildx-action — Required to enable BuildKit cache backends"