@htekdev/actions-debugger 1.0.23 → 1.0.24

package/errors/runner-environment/codeql-action-v2-deprecated.yml

@@ -0,0 +1,110 @@
+id: runner-environment-061
+title: "CodeQL Action v1/v2 Deprecated — Hard Failure with Upgrade Required Message"
+category: runner-environment
+severity: error
+tags:
+  - codeql
+  - code-scanning
+  - deprecated
+  - v2
+  - v3
+  - security
+  - breaking-change
+patterns:
+  - regex: "CodeQL Action major versions v1 and v2 have been deprecated"
+    flags: "i"
+  - regex: "Please update all occurrences of the CodeQL Action in your workflow files to v3"
+    flags: "i"
+  - regex: "github/codeql-action/.*@v[12]\\b"
+    flags: "i"
+error_messages:
+  - "Error: CodeQL Action major versions v1 and v2 have been deprecated. Please update all occurrences of the CodeQL Action in your workflow files to v3. For more information, see https://github.blog/changelog/2025-01-10-code-scanning-codeql-action-v2-is-now-deprecated/"
+  - "CodeQL Action v2 is now deprecated. Upgrade to v3."
+root_cause: |
+  GitHub retired CodeQL Action major versions v1 and v2 in January 2025. After the
+  retirement date, any workflow referencing `github/codeql-action/*@v1` or
+  `github/codeql-action/*@v2` produces a hard failure with the above error message
+  and does NOT perform code scanning.
+
+  The CodeQL action family includes multiple steps that must ALL be updated together:
+  - `github/codeql-action/init@v2`
+  - `github/codeql-action/autobuild@v2`
+  - `github/codeql-action/analyze@v2`
+  - `github/codeql-action/upload-sarif@v2`
+  - `github/codeql-action/resolve-environment@v2`
+
+  Missing even one of these (leaving it at `@v2` while updating others to `@v3`)
+  causes the workflow to fail. Repos created before 2024 using the default
+  GitHub-provided Code Scanning setup workflow are the most common source of
+  stale v2 references.
+
+  This is distinct from the generic `deprecated-action-version-auto-rejected` pattern
+  (runner-environment-037) which covers specific minor/patch versions of actions/cache,
+  actions/checkout, etc. The CodeQL deprecation applies to entire major versions v1 and v2
+  and produces a specific, different error message.
+fix: |
+  Replace every `github/codeql-action/*@v2` (and `@v1`) reference in all workflow files
+  with the corresponding `@v3` tag. All steps in the CodeQL workflow must be updated
+  together — a partial update (e.g., `init@v3` but `analyze@v2`) will still fail.
+
+  After updating, verify the workflow runs successfully by checking the Actions tab
+  and the Security → Code Scanning alerts page.
+fix_code:
+  - language: yaml
+    label: "Updated CodeQL workflow using v3 (all steps)"
+    code: |
+      name: "CodeQL Analysis"
+      on:
+        push:
+          branches: ["main"]
+        pull_request:
+          branches: ["main"]
+        schedule:
+          - cron: '0 6 * * 1'
+
+      jobs:
+        analyze:
+          name: Analyze (${{ matrix.language }})
+          runs-on: ubuntu-latest
+          permissions:
+            actions: read
+            contents: read
+            security-events: write
+
+          strategy:
+            matrix:
+              language: ['javascript', 'python']
+
+          steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Initialize CodeQL
+              uses: github/codeql-action/init@v3          # ← was @v2
+              with:
+                languages: ${{ matrix.language }}
+
+            - name: Autobuild
+              uses: github/codeql-action/autobuild@v3     # ← was @v2
+
+            - name: Perform CodeQL Analysis
+              uses: github/codeql-action/analyze@v3       # ← was @v2
+              with:
+                category: "/language:${{ matrix.language }}"
+  - language: yaml
+    label: "Bulk-find stale v2 references (shell one-liner)"
+    code: |
+      # Run from repo root to find all @v1 or @v2 codeql-action references:
+      # grep -rn "codeql-action/.*@v[12]" .github/workflows/
+prevention:
+  - "Use Dependabot for GitHub Actions to automatically open PRs when actions release new major versions."
+  - "Enable the 'Actions' section in Dependabot config (`package-ecosystem: github-actions`) for all repos with CodeQL workflows."
+  - "After any CodeQL major version update, verify Security → Code Scanning shows recent scans with no 'Tool not recognized' errors."
+  - "Search all workflow files for `codeql-action` references before major GitHub deprecation windows."
+docs:
+  - url: "https://github.blog/changelog/2025-01-10-code-scanning-codeql-action-v2-is-now-deprecated/"
+    label: "GitHub Changelog: Code scanning — CodeQL Action v2 is now deprecated (Jan 2025)"
+  - url: "https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages"
+    label: "GitHub Docs: CodeQL code scanning for compiled languages"
+  - url: "https://github.com/github/codeql-action/releases"
+    label: "github/codeql-action Releases — v3 changelog"

package/errors/runner-environment/macos-26-openssl-3-system-library-breaking.yml

@@ -0,0 +1,114 @@
+id: runner-environment-070
+title: "macOS 26 Upgrades OpenSSL from 1.1.1 to 3.x — Hardcoded openssl@1.1 Paths Break"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - openssl
+  - macos-26
+  - runner-image
+  - breaking-change
+  - homebrew
+patterns:
+  - regex: "Library not loaded.*openssl@1\\.1.*libssl\\.1\\.1\\.dylib"
+    flags: "i"
+  - regex: "ld.*library not found.*-lssl|cannot find.*libssl\\.1\\.1"
+    flags: "i"
+  - regex: "openssl@1\\.1.*not installed|brew.*openssl@1\\.1.*no longer"
+    flags: "i"
+  - regex: "Could not find OpenSSL|ssl.*version.*mismatch.*1\\.1"
+    flags: "i"
+  - regex: "OpenSSL 1\\.1\\.1.*required.*OpenSSL 3"
+    flags: "i"
+error_messages:
+  - "Library not loaded: /usr/local/opt/openssl@1.1/lib/libssl.1.1.dylib"
+  - "Library not loaded: /opt/homebrew/opt/openssl@1.1/lib/libssl.1.1.dylib"
+  - "ld: library not found for -lssl (referenced from build target)"
+  - "Could not find a package configuration file provided by 'OpenSSL'"
+  - "Could not link to OpenSSL library. Please install OpenSSL."
+root_cause: |
+  When macos-latest migrates to macos-26 (rolling out June 15 through July 15, 2026),
+  the system OpenSSL jumps from OpenSSL 1.1.1w (the last 1.x release, now EOL)
+  to OpenSSL 3.6.2. This is a major version change with breaking ABI differences.
+
+  Any workflow that hardcodes openssl@1.1 Homebrew paths or links against the
+  1.1.x shared libraries will fail because:
+
+  - Homebrew's openssl@1.1 formula is deprecated on macOS 26
+  - The shared library /opt/homebrew/opt/openssl@1.1/lib/libssl.1.1.dylib
+    no longer exists; it is replaced by openssl@3
+  - PKG_CONFIG_PATH and LDFLAGS pointing to openssl@1.1 resolve to nothing
+
+  Common breakage surfaces:
+  - Ruby gems with native extensions (openssl gem links against system OpenSSL)
+  - Python packages (pyOpenSSL, cryptography) that link against 1.x path
+  - CMake projects using find_package(OpenSSL) finding incompatible version
+  - Homebrew formulas linking transitively against openssl@1.1
+
+  Source: runner-images#14167 — macOS 15 vs macOS 26 software diff shows
+  OpenSSL jumps from 1.1.1w to 3.6.2.
+fix: |
+  Replace all openssl@1.1 references with openssl@3 (installed by default on macOS 26).
+
+  For Homebrew-based builds, use dynamic path detection:
+    OPENSSL_DIR=$(brew --prefix openssl@3)
+    export LDFLAGS="-L${OPENSSL_DIR}/lib"
+    export PKG_CONFIG_PATH="${OPENSSL_DIR}/lib/pkgconfig"
+
+  For Ruby gem compilation:
+    bundle config build.openssl --with-openssl-dir=$(brew --prefix openssl@3)
+
+  For CMake, pass OPENSSL_ROOT_DIR:
+    cmake -DOPENSSL_ROOT_DIR=$(brew --prefix openssl@3) ..
+fix_code:
+  - language: yaml
+    label: "Dynamic OpenSSL path — works on both macOS 15 and macOS 26"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Set OpenSSL environment variables
+              run: |
+                OPENSSL_PREFIX=$(brew --prefix openssl)
+                echo "OPENSSL_DIR=$OPENSSL_PREFIX" >> $GITHUB_ENV
+                echo "LDFLAGS=-L$OPENSSL_PREFIX/lib" >> $GITHUB_ENV
+                echo "CPPFLAGS=-I$OPENSSL_PREFIX/include" >> $GITHUB_ENV
+                echo "PKG_CONFIG_PATH=$OPENSSL_PREFIX/lib/pkgconfig" >> $GITHUB_ENV
+
+            - name: Build project
+              run: cmake -B build -DOPENSSL_ROOT_DIR=$OPENSSL_DIR && cmake --build build
+  - language: yaml
+    label: "Ruby bundler — configure openssl@3 for native extension builds"
+    code: |
+      jobs:
+        ruby-build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.4'
+                bundler-cache: true
+
+            - name: Configure OpenSSL for bundler
+              run: |
+                OPENSSL_DIR=$(brew --prefix openssl@3)
+                bundle config build.openssl --with-openssl-dir=$OPENSSL_DIR
+
+            - name: Install gems
+              run: bundle install
+prevention:
+  - "Never hardcode openssl@1.1 paths — always use $(brew --prefix openssl) dynamically."
+  - "Test your macOS workflows on macos-26 before macos-latest migrates (June 15 to July 15, 2026)."
+  - "Use macos-15 label to pin to the older image while migrating OpenSSL dependencies."
+  - "For language setup actions, ensure you use recent versions that handle OpenSSL 3 automatically."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "GitHub Announcement: macos-latest will use macos-26 in June 2026 (includes OpenSSL diff)"
+  - url: "https://www.openssl.org/news/changelog.html"
+    label: "OpenSSL 3.x Changelog"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "About GitHub-hosted runners"

package/errors/runner-environment/macos-26-ruby-34-default-upgrade.yml

@@ -0,0 +1,114 @@
+id: runner-environment-072
+title: "macOS 26 Upgrades Default Ruby from 3.3 to 3.4 — Native Gem ABI Breaks"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - ruby
+  - macos-26
+  - runner-image
+  - breaking-change
+  - native-extensions
+patterns:
+  - regex: 'incompatible library version.*\.bundle|LoadError.*incompatible library'
+    flags: "i"
+  - regex: 'ruby.*3\.3.*required.*3\.4|Gem.*compiled.*Ruby 3\.3.*running.*3\.4'
+    flags: "i"
+  - regex: "Bundler.*RUBY_VERSION.*mismatch|native extension.*wrong Ruby version"
+    flags: "i"
+  - regex: 'Error loading.*\.bundle.*built for Ruby 3\.3'
+    flags: "i"
+error_messages:
+  - "LoadError: incompatible library version - /path/to/gem.bundle (expected 3.3, got 3.4)"
+  - "Bundler::GemNotFound: Could not find gem 'pg (>= 0) ruby' in locally installed gems"
+  - "An error occurred while installing nokogiri, and Bundler cannot continue."
+  - "Your Ruby version is 3.4.x, but your Gemfile specified 3.3.x"
+root_cause: |
+  When macos-latest migrates to macos-26 (June 15 through July 15, 2026), the default
+  system Ruby version jumps from 3.3.11 to 3.4.9. This is a minor Ruby version change
+  but it breaks any workflow that:
+
+  1. Has a Gemfile or .ruby-version pinning Ruby 3.3.x
+  2. Uses cached gem bundles built against Ruby 3.3's C ABI (native extensions
+     like nokogiri, pg, mysql2, ffi compile to .bundle files tied to the Ruby ABI)
+  3. Hardcodes RUBY_VERSION in build scripts or Gemfile.lock references
+
+  Ruby native extensions (.bundle files) are ABI-specific — gems compiled against
+  Ruby 3.3 cannot be loaded by Ruby 3.4 and vice versa. If a workflow caches
+  bundled gems from a prior run on macos-15 (Ruby 3.3) and restores them on
+  macos-26 (Ruby 3.4), native extension gems will fail to load.
+
+  Source: runner-images#14167 — macOS 15 vs macOS 26 software diff shows Ruby
+  jumping from 3.3.11 to 3.4.9.
+fix: |
+  Option 1 — Use ruby/setup-ruby to pin an explicit Ruby version (recommended):
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.3'  # or '3.4' to target the new default
+        bundler-cache: true
+
+  Option 2 — Add .ruby-version file to your repo specifying the target Ruby version.
+  setup-ruby will read this automatically.
+
+  Option 3 — Update your Gemfile to remove Ruby version constraint or bump it to 3.4:
+    # In Gemfile, remove or update:
+    # ruby '3.3'  <- remove or change to '3.4'
+
+  For cache invalidation: if you use actions/cache for bundler, include the Ruby
+  version in the cache key:
+    key: gems-${{ runner.os }}-ruby-${{ env.RUBY_VERSION }}-${{ hashFiles('**/Gemfile.lock') }}
+fix_code:
+  - language: yaml
+    label: "Pin Ruby version with setup-ruby (cross-image safe)"
+    code: |
+      jobs:
+        test:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: ruby/setup-ruby@v1
+              with:
+                # Pin explicitly — do not rely on runner default Ruby
+                ruby-version: '3.4'
+                bundler-cache: true
+
+            - name: Run tests
+              run: bundle exec rspec
+
+  - language: yaml
+    label: "Cache key including Ruby version to avoid ABI mismatch"
+    code: |
+      jobs:
+        test:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.4'
+
+            - name: Cache bundler gems
+              uses: actions/cache@v4
+              with:
+                path: vendor/bundle
+                # Include Ruby version in cache key to prevent ABI mismatch
+                key: gems-${{ runner.os }}-ruby-${{ env.RUBY_VERSION }}-${{ hashFiles('**/Gemfile.lock') }}
+                restore-keys: |
+                  gems-${{ runner.os }}-ruby-${{ env.RUBY_VERSION }}-
+
+            - name: Install gems
+              run: bundle install --path vendor/bundle
+prevention:
+  - "Always use ruby/setup-ruby with an explicit ruby-version — never rely on the runner's default Ruby."
+  - "Include the Ruby version in bundler cache keys to prevent loading native gems built for a different Ruby ABI."
+  - "Add a .ruby-version file to your repository to make the intended Ruby version visible and enforceable."
+  - "Test on macos-26 before macos-latest migrates to catch Ruby 3.3 to 3.4 incompatibilities early."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "GitHub Announcement: macos-latest will use macos-26 in June 2026 (includes Ruby version diff)"
+  - url: "https://github.com/ruby/setup-ruby"
+    label: "ruby/setup-ruby action"
+  - url: "https://www.ruby-lang.org/en/news/2024/12/25/ruby-3-4-0-released/"
+    label: "Ruby 3.4.0 Release Notes"

package/errors/runner-environment/macos-26-xcode-default-265-pin-required.yml

@@ -0,0 +1,99 @@
+id: runner-environment-071
+title: "macOS 26 Default Xcode Switches to 26.5 on June 8 2026 — Unpin to Fix"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - xcode
+  - macos-26
+  - runner-image
+  - breaking-change
+  - ios
+patterns:
+  - regex: 'Xcode.*26\.4\.1.*not found|xcode.*version.*26\.4.*unavailable'
+    flags: "i"
+  - regex: 'your project.*not compatible.*Xcode 26\.5|requires Xcode.*26\.4'
+    flags: "i"
+  - regex: 'xcodebuild.*error.*incompatible.*project|DT_TOOLCHAIN.*not found.*26\.5'
+    flags: "i"
+  - regex: 'error.*The iOS Simulator.*26\.1.*required.*26\.5'
+    flags: "i"
+error_messages:
+  - "xcodebuild: error: The project requires Xcode 26.4.1, but the currently selected Xcode version is 26.5."
+  - "error: DT_TOOLCHAIN_DIR cannot be used to evaluate TOOLCHAIN_DIR. Use TOOLCHAINS setting instead."
+  - "Unable to boot the Simulator. The request to boot 'iOS 26.1 Simulator' was denied because the destination is incompatible with this version of Xcode."
+root_cause: |
+  Starting June 8, 2026 (rolling out over 2-4 days), GitHub is changing the default
+  Xcode on macOS-26 runners from Xcode 26.4.1 to Xcode 26.5. Workflows running on
+  macos-26 or macos-latest (after the macos-latest migration completes) that do not
+  explicitly pin an Xcode version will automatically get Xcode 26.5.
+
+  Xcode 26.5 is a new major release and may introduce build incompatibilities:
+  - Project files referencing deprecated Xcode 26.4 APIs
+  - iOS/macOS Simulator runtimes that only match Xcode 26.4.1
+  - Swift toolchain behavior differences between 26.4.1 and 26.5
+  - Build setting migrations required by the new Xcode version
+
+  Source: runner-images#14172 — official GitHub announcement for macOS 26 Xcode
+  default change.
+fix: |
+  Pin your Xcode version explicitly using either:
+
+  Option 1 — sudo xcode-select (no extra action required):
+    sudo xcode-select -s "/Applications/Xcode_26.4.1.app"
+
+  Option 2 — maxim-lobanov/setup-xcode action:
+    - uses: maxim-lobanov/setup-xcode@v1
+      with:
+        xcode-version: '26.4.1'
+
+  To list available Xcode versions on macos-26 runners, check the official
+  runner image documentation at:
+  https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md#xcode
+fix_code:
+  - language: yaml
+    label: "Pin Xcode version using setup-xcode action"
+    code: |
+      jobs:
+        build-ios:
+          runs-on: macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Select Xcode version
+              uses: maxim-lobanov/setup-xcode@v1
+              with:
+                xcode-version: '26.4.1'
+
+            - name: Build iOS app
+              run: xcodebuild -project MyApp.xcodeproj -scheme MyApp -sdk iphonesimulator build
+
+  - language: yaml
+    label: "Pin Xcode version using xcode-select directly"
+    code: |
+      jobs:
+        build-ios:
+          runs-on: macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Pin Xcode 26.4.1
+              run: sudo xcode-select -s "/Applications/Xcode_26.4.1.app"
+
+            - name: Verify Xcode version
+              run: xcodebuild -version
+
+            - name: Build
+              run: xcodebuild -scheme MyApp build
+prevention:
+  - "Always pin Xcode version explicitly on macOS runners — never rely on the default."
+  - "Use maxim-lobanov/setup-xcode@v1 with a specific xcode-version to make version changes visible in git diff."
+  - "Subscribe to runner-images announcements for advance notice of Xcode default version changes."
+  - "Audit your workflows for hardcoded Xcode version paths before macos-latest migrates to macos-26."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14172"
+    label: "GitHub Announcement: Default Xcode on macOS 26 will be set to 26.5 on 2026-06-08"
+  - url: "https://github.com/maxim-lobanov/setup-xcode"
+    label: "maxim-lobanov/setup-xcode action"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md#xcode"
+    label: "macOS 26 arm64 runner image README — available Xcode versions"

package/errors/runner-environment/macos-latest-label-switches-to-macos26.yml

@@ -0,0 +1,127 @@
+id: runner-environment-064
+title: "macos-latest Label Switching to macOS 26 — Toolchain and Brew Package Changes"
+category: runner-environment
+severity: warning
+tags:
+  - macos
+  - macos-latest
+  - macos-26
+  - runner-label
+  - homebrew
+  - toolchain
+  - migration
+patterns:
+  - regex: "macos.*26.*not supported"
+    flags: "i"
+  - regex: "No such file or directory.*clang|clang.*not found"
+    flags: "i"
+  - regex: "dyld.*Library not loaded"
+    flags: "i"
+  - regex: "Error: Cannot install in Homebrew on macOS.*without Command Line Tools"
+    flags: "i"
+  - regex: "macos-latest.*macos-26"
+    flags: "i"
+error_messages:
+  - "clang: error: no such file or directory"
+  - "dyld[12345]: Library not loaded: /usr/local/lib/libssl.1.1.dylib"
+  - "Error: Your CLT does not support macOS 26."
+  - "xcrun: error: SDK 'iphoneos' cannot be located"
+root_cause: |
+  Starting June 15, 2026, the `macos-latest` runner label is being migrated
+  from macOS 15 (Sequoia) to macOS 26 (runner-images#14167). The rollout
+  runs through July 15, 2026. Workflows pinned to `macos-latest` without
+  testing on macOS 26 may encounter failures from toolchain and package
+  differences between the two OS versions.
+
+  Key differences in macOS 26 runner images compared to macOS 15:
+
+  1. **Homebrew LLVM version bump**: LLVM jumped from 18 to 20 on macOS 26.
+     Hardcoded paths like `/opt/homebrew/opt/llvm@18/bin/clang` or env vars
+     referencing `llvm@18` binaries fail. POCO and other libraries built
+     against LLVM 18 ABI may link incorrectly.
+
+  2. **macOS SDK changes**: macOS 26 uses a newer Xcode and SDK toolchain.
+     Libraries and headers that existed in macOS 15 SDK may have moved,
+     been renamed, or removed under the macOS 26 (Tahoe) SDK.
+
+  3. **Homebrew formula versions**: Many Homebrew packages have newer
+     versions on macOS 26 images than on macOS 15. Formulas with no macOS 26
+     bottle may be built from source, increasing job time significantly.
+
+  4. **System library locations**: Dynamic library paths (e.g., for OpenSSL,
+     libpq, or other system libs installed via Homebrew) may differ between
+     macOS 15 and macOS 26 as Homebrew evolves its prefix structure.
+
+  5. **Xcode simulator SDK policy**: Only the 3 latest Xcode versions retain
+     platform tools/SDKs. Workflows using older Xcode/simulator versions
+     that worked on macOS 15 may not find the expected SDK on macOS 26.
+
+  Workflows that do not pin `macos-latest` and have never tested on macOS 26
+  may start failing after the migration completes.
+fix: |
+  1. **Pin to macOS 15 temporarily**: Replace `macos-latest` with `macos-15`
+     to preserve the current behavior while you test and migrate.
+
+  2. **Test on macOS 26 before migration**: Add a matrix job with
+     `macos-26` to identify failures before `macos-latest` switches.
+
+  3. **Fix hardcoded LLVM/Clang paths**: Update any hardcoded paths like
+     `/opt/homebrew/opt/llvm@18` to use `$(brew --prefix llvm)` or install
+     the specific version you need via `brew install llvm@18`.
+
+  4. **Update Homebrew formula pins**: Check for `@version`-pinned Homebrew
+     formulas that may no longer have macOS 26 bottles and either upgrade
+     or build from source explicitly.
+
+  5. **Audit system library dependencies**: For native extensions that link
+     against system or Homebrew libraries, verify library paths with
+     `brew --prefix <lib>` at runtime rather than hardcoding them.
+fix_code:
+  - language: yaml
+    label: "Pin to macos-15 while testing macOS 26 compatibility"
+    code: |
+      jobs:
+        build:
+          # Temporarily pin to macos-15 while migration is in progress
+          # macos-latest will point to macos-26 starting June 15, 2026
+          runs-on: macos-15
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+  - language: yaml
+    label: "Matrix to test both macOS 15 and 26 before migration"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [macos-15, macos-26]
+            fail-fast: false
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+  - language: yaml
+    label: "Use brew --prefix to resolve dynamic LLVM/library paths"
+    code: |
+      - name: Set up LLVM paths dynamically
+        run: |
+          # Instead of hardcoded /opt/homebrew/opt/llvm@18/bin/clang:
+          LLVM_PREFIX=$(brew --prefix llvm)
+          echo "CC=${LLVM_PREFIX}/bin/clang" >> $GITHUB_ENV
+          echo "CXX=${LLVM_PREFIX}/bin/clang++" >> $GITHUB_ENV
+          echo "${LLVM_PREFIX}/bin" >> $GITHUB_PATH
+prevention:
+  - "Never use macos-latest without testing the next macOS version first — GitHub announces label migrations weeks in advance in runner-images issues."
+  - "Pin to a specific macOS version (e.g., macos-15) for production workflows; use macos-latest only in exploratory or dependency-update workflows."
+  - "Avoid hardcoding Homebrew formula paths — always use `$(brew --prefix <formula>)` to resolve paths dynamically."
+  - "Run a matrix job spanning current and next macOS versions as part of your CI to catch breakage before a label migration lands."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "runner-images #14167: macos-latest will use macos-26 starting June 15, 2026"
+  - url: "https://github.blog/changelog/2026-05-14-github-actions-upcoming-image-migrations/"
+    label: "GitHub Changelog: Upcoming image migrations (May 2026)"
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "runner-images announcement: macOS 14 deprecation starting July 6, 2026"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories"
+    label: "GitHub Docs: Standard GitHub-hosted runners — available runner labels"

package/errors/runner-environment/node20-removed-toolcache-default-node22.yml

@@ -0,0 +1,104 @@
+id: runner-environment-062
+title: "Node.js 20 Removed from Toolcache — Default Node.js Changed to 22"
+category: runner-environment
+severity: error
+tags:
+  - nodejs
+  - node20
+  - node22
+  - toolcache
+  - eol
+  - setup-node
+  - runner-images
+patterns:
+  - regex: "node: not found"
+    flags: "i"
+  - regex: "node: No such file or directory"
+    flags: "i"
+  - regex: "Downloading Node\\.js (20\\.[0-9]+\\.[0-9]+)"
+    flags: "i"
+  - regex: "engines.*node.*>=\\s*20"
+    flags: "i"
+  - regex: "error node_modules.*requires node.*20"
+    flags: "i"
+error_messages:
+  - "node: not found"
+  - "Downloading Node.js 20.x.x (not pre-installed, downloading on demand)"
+  - "error: The engine 'node' is incompatible with this module. Expected version '^20.0.0'. Got '22.x.x'"
+  - "The engine 'node' is incompatible with this module. Expected version '>=20 <21'. Got '22.14.0'"
+root_cause: |
+  Node.js 20 reached end-of-life on April 30, 2026. Starting with runner image
+  updates rolled out May 19–26, 2026, Node.js 20 was removed from the toolcache
+  on ALL GitHub-hosted runner images (ubuntu-22.04, ubuntu-24.04, ubuntu-26.04,
+  macos-14, macos-15, macos-26, windows-2022, windows-2025, and ARM variants).
+
+  Two distinct impacts:
+
+  1. **Default Node.js version changed**: On runners where Node.js 20 was
+     previously the default (e.g., ubuntu-22.04, ubuntu-24.04, windows-2022,
+     macos-14), the default is now Node.js 22 (Maintenance LTS). Workflows
+     that call `node` or `npm` without an explicit `actions/setup-node` step
+     will now run on Node.js 22, potentially breaking packages with strict
+     engines constraints like `"node": "^20.0.0"`.
+
+  2. **setup-node now downloads Node.js 20**: If a workflow pins
+     `node-version: '20'` via `actions/setup-node`, it will no longer find
+     Node.js 20 in the toolcache and must download it on demand. This adds
+     download time and may fail if the registry is rate-limited or the runner
+     has no internet access (self-hosted runners with air-gapped environments).
+
+  Only Node.js 22 and Node.js 24 remain pre-installed in the toolcache on all
+  runner images after this change.
+fix: |
+  Option 1 — Upgrade to Node.js 22 or 24 (recommended):
+    Update your project to support Node.js 22 (current Maintenance LTS) or
+    Node.js 24 (Active LTS). Update package.json engines field, run tests on
+    the new version, and remove the explicit node-version pin (or update it).
+
+  Option 2 — Pin to Node.js 20 via setup-node (temporary):
+    If you cannot migrate yet, explicitly install Node.js 20 on every job
+    using `actions/setup-node`. Node.js 20 is still downloadable on demand —
+    it just won't be pre-cached. This will slow down your workflow.
+
+  Option 3 — Test with FORCE_JAVASCRIPT_ACTIONS_TO_NODE24:
+    Set `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` as a workflow env to test
+    how your action runtime behaves on Node.js 24 before fully migrating.
+fix_code:
+  - language: yaml
+    label: "Upgrade to Node.js 22 (recommended)"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'    # Node.js 22 is Maintenance LTS through 2026
+          cache: 'npm'
+  - language: yaml
+    label: "Pin Node.js 20 temporarily (still downloadable on demand)"
+    code: |
+      - name: Set up Node.js 20 (no longer pre-cached — will download)
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'    # EOL 2026-04-30; plan your migration to v22
+          cache: 'npm'
+  - language: yaml
+    label: "Use .nvmrc / .node-version to pin version in project root"
+    code: |
+      - name: Set up Node.js from .nvmrc
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'    # Update .nvmrc to 22 or 24
+          cache: 'npm'
+prevention:
+  - "Always specify an explicit node-version in actions/setup-node — never rely on the runner's ambient Node.js version."
+  - "Set `node-version-file: '.nvmrc'` and commit a .nvmrc file so all environments (local, CI, containers) use the same version."
+  - "Watch the runner-images Announcements tab for future EOL removals — set up GitHub notifications for the actions/runner-images repo."
+  - "Use `engines` in package.json with a range like `>=22 <25` to catch version incompatibilities in CI early."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14029"
+    label: "runner-images #14029: Node.js 20 removed, default changed to 22"
+  - url: "https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/"
+    label: "GitHub Changelog: Deprecation of Node 20 on GitHub Actions runners"
+  - url: "https://github.com/nodejs/release#readme"
+    label: "Node.js Release Schedule (EOL dates)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-pre-installed-software#nodejs-versions"
+    label: "GitHub Docs: Using pre-installed software — Node.js versions"