@htekdev/actions-debugger 1.0.101 → 1.0.102

package/errors/runner-environment/homebrew-auto-update-macos-ci-slow.yml

@@ -0,0 +1,84 @@
+id: runner-environment-172
+title: 'Homebrew 4.x triggers auto-update on every brew install, adding 1-3 minutes to macOS CI'
+category: runner-environment
+severity: warning
+tags:
+  - macos
+  - homebrew
+  - brew
+  - slow-ci
+  - performance
+  - HOMEBREW_NO_AUTO_UPDATE
+patterns:
+  - regex: '==> Auto-updated Homebrew!|Updating Homebrew\.\.\.|Auto-update took'
+    flags: 'i'
+  - regex: 'Fetching https://formulae\.brew\.sh/api/(formula|cask)\.jws\.json'
+    flags: 'i'
+error_messages:
+  - "==> Auto-updated Homebrew!"
+  - "Updating Homebrew..."
+  - "Fetching https://formulae.brew.sh/api/formula.jws.json"
+  - "This operation has taken more than 5 minutes"
+root_cause: |
+  Homebrew 4.0 (released February 2023) replaced its previous approach of cloning the
+  homebrew-core and homebrew-cask Git repositories with downloading pre-computed JSON API
+  responses from formulae.brew.sh. While this reduced the on-disk size of the Homebrew
+  installation, Homebrew retained its auto-update behavior: by default, any brew install,
+  brew upgrade, or brew reinstall command triggers an auto-update check if the local
+  formula cache is older than HOMEBREW_AUTO_UPDATE_SECS (default: 300 seconds = 5 minutes).
+
+  On GitHub-hosted macOS runners, every fresh runner starts with a Homebrew installation
+  that has not been updated recently, so the first brew install in any job always triggers
+  a full API fetch from formulae.brew.sh. This fetch downloads large JSON manifests for
+  formula and cask databases and typically adds 1-3 minutes to the job. For workflows with
+  multiple parallel matrix jobs or multiple brew install calls, this overhead compounds.
+
+  Homebrew 4.x also added HOMEBREW_AUTO_UPDATE_SECS and related env vars to control this
+  behavior, but the default settings cause every fresh runner to update on first use.
+fix: |
+  Set HOMEBREW_NO_AUTO_UPDATE=1 as a workflow environment variable to disable automatic
+  updates entirely. The macOS runner image ships a recent-enough Homebrew installation for
+  most use cases. If you need the absolute latest formula versions for a specific tool,
+  run a single explicit brew update at the start of the job.
+
+  Also set HOMEBREW_NO_INSTALL_CLEANUP=1 to prevent cleanup passes that extend install time.
+fix_code:
+  - language: yaml
+    label: 'Disable Homebrew auto-update at workflow level (recommended)'
+    code: |
+      env:
+        HOMEBREW_NO_AUTO_UPDATE: '1'
+        HOMEBREW_NO_INSTALL_CLEANUP: '1'
+
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install build dependencies
+              run: brew install ninja cmake
+  - language: yaml
+    label: 'Run one explicit update then suppress auto-update per job'
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          env:
+            HOMEBREW_NO_AUTO_UPDATE: '1'
+            HOMEBREW_NO_INSTALL_CLEANUP: '1'
+          steps:
+            - name: Update Homebrew (once, explicit)
+              run: brew update
+            - name: Install tools
+              run: brew install ninja cmake
+prevention:
+  - 'Set HOMEBREW_NO_AUTO_UPDATE=1 and HOMEBREW_NO_INSTALL_CLEANUP=1 as top-level workflow env vars'
+  - 'Use actions/setup-* official actions instead of brew install when available (setup-python, setup-node, etc.)'
+  - 'Cache brew downloads using actions/cache with a key derived from a Brewfile or explicit package list'
+  - 'Set HOMEBREW_AUTO_UPDATE_SECS=86400 to limit auto-updates to at most once per day if you need periodic updates'
+docs:
+  - url: 'https://docs.brew.sh/Manpage#environment'
+    label: 'Homebrew environment variables — HOMEBREW_NO_AUTO_UPDATE'
+  - url: 'https://brew.sh/2023/02/16/homebrew-4.0.0/'
+    label: 'Homebrew 4.0.0 release notes — JSON API migration'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md'
+    label: 'macOS 15 runner image — preinstalled Homebrew version'

package/errors/runner-environment/python312-ast-str-num-removed-ubuntu24.yml

@@ -0,0 +1,74 @@
+id: runner-environment-171
+title: 'Python 3.12 removes deprecated ast.Str, ast.Num, ast.NameConstant on ubuntu-24.04 — older linters crash'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - python
+  - python-3.12
+  - ast
+  - linting
+  - pylint
+  - bandit
+patterns:
+  - regex: 'AttributeError: module ''ast'' has no attribute ''(Str|Num|NameConstant|Bytes)'''
+    flags: 'i'
+  - regex: 'ImportError.*pylint|cannot import name.*astroid|AttributeError.*ast\.(Str|Num)'
+    flags: 'i'
+error_messages:
+  - "AttributeError: module 'ast' has no attribute 'Str'"
+  - "AttributeError: module 'ast' has no attribute 'Num'"
+  - "AttributeError: module 'ast' has no attribute 'NameConstant'"
+  - "AttributeError: module 'ast' has no attribute 'Bytes'"
+root_cause: |
+  Ubuntu 24.04 ships Python 3.12 as the default system Python (/usr/bin/python3).
+  Python 3.12 permanently removed several deprecated AST node types that were soft-deprecated
+  since Python 3.8 and slated for removal in 3.12: ast.Str, ast.Num, ast.NameConstant,
+  ast.Bytes, and the legacy constant-value wrapper nodes.
+
+  Many popular static analysis tools directly referenced these internal AST nodes for
+  backward compatibility with Python 2 and early Python 3 code. Affected tools include:
+  - pylint < 3.0 (uses astroid which references ast.Str/ast.Num for constant folding)
+  - astroid < 3.0 (core dependency of pylint; crash on import with Python 3.12)
+  - bandit < 1.8.0 (security linter; uses ast.Str for string literal detection)
+  - flake8-bugbear < 23.x (some plugin versions reference ast.Num directly)
+  - pyflakes < 3.0 (uses ast.Str for format string analysis)
+
+  Workflows that install these linters without pinning minimum versions fail immediately
+  when the runner migrates from ubuntu-22.04 (Python 3.10) to ubuntu-24.04 (Python 3.12).
+  The error surfaces as an AttributeError during tool import, before any code is analyzed.
+fix: |
+  Upgrade the affected analysis tools to Python 3.12-compatible versions:
+  - pylint: upgrade to 3.0+ (requires astroid >= 3.0 simultaneously)
+  - bandit: upgrade to 1.8.0+
+  - flake8: upgrade to 7.0+ with compatible plugin versions
+
+  If an immediate upgrade is not feasible, pin the runner to ubuntu-22.04 (Python 3.10)
+  temporarily while the upgrade is planned. Ubuntu 22.04 runner support continues until
+  at least April 2027.
+fix_code:
+  - language: yaml
+    label: 'Upgrade linting tools to Python 3.12-compatible versions'
+    code: |
+      - name: Install Python linters (3.12 compatible)
+        run: pip install 'pylint>=3.0' 'astroid>=3.0' 'bandit>=1.8.0' 'flake8>=7.0'
+  - language: yaml
+    label: 'Temporary workaround — pin to ubuntu-22.04 (Python 3.10)'
+    code: |
+      jobs:
+        lint:
+          runs-on: ubuntu-22.04  # Python 3.10 — avoids ast.Str removal in 3.12
+prevention:
+  - 'Pin minimum versions for linting tools in requirements-dev.txt or pyproject.toml'
+  - 'Use actions/setup-python to control the Python version explicitly rather than relying on system Python'
+  - 'Test your CI toolchain against Python 3.12 before migrating to ubuntu-24.04'
+  - 'Review the Python 3.12 changelog for all removed deprecated features before upgrading'
+docs:
+  - url: 'https://docs.python.org/3.12/whatsnew/3.12.html#removed'
+    label: 'Python 3.12 Removed Features'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md'
+    label: 'Ubuntu 24.04 runner image software listing'
+  - url: 'https://pylint.readthedocs.io/en/stable/whatsnew/3.0/summary.html'
+    label: 'Pylint 3.0 migration and Python 3.12 compatibility notes'
+  - url: 'https://github.com/PyCQA/bandit/releases/tag/1.8.0'
+    label: 'bandit 1.8.0 release notes — Python 3.12 AST compatibility'

package/errors/runner-environment/setup-go-eol-version-not-in-tool-cache.yml

@@ -0,0 +1,78 @@
+id: runner-environment-173
+title: 'actions/setup-go with EOL Go versions (1.21, 1.22) not in runner tool cache — slow downloads or failures'
+category: runner-environment
+severity: warning
+tags:
+  - setup-go
+  - go
+  - golang
+  - eol
+  - tool-cache
+  - go-version
+patterns:
+  - regex: 'go version [\d.]+ is not in the tool-cache.*Falling back to download|go\d+\.\d+\.?\d*.*not found.*tool.cache'
+    flags: 'i'
+  - regex: 'Downloading go[\d.]+.*from https://dl\.google\.com/go'
+    flags: 'i'
+  - regex: 'Failed to download Go from|Unable to find Go version.*in cache'
+    flags: 'i'
+error_messages:
+  - "go version 1.21.x is not in the tool-cache. Falling back to downloading from https://dl.google.com/go"
+  - "go version 1.22.x is not in the tool-cache. Falling back to downloading from https://dl.google.com/go"
+  - "Failed to download Go from https://dl.google.com/go"
+  - "Unable to find Go version 1.21 in cache"
+root_cause: |
+  GitHub removes end-of-life Go versions from the runner image tool cache after their
+  official support window closes. Go follows a two-release support policy: only the two
+  most recent major releases receive security updates. Once a version is EOL, it is no
+  longer pre-installed on new runner images.
+
+  Affected versions as of 2025-2026:
+  - Go 1.21 — EOL February 6, 2024 (removed from runner tool cache ~Q2 2024)
+  - Go 1.22 — EOL August 6, 2025 (removed from runner tool cache ~Q4 2025)
+
+  When actions/setup-go requests a version not in the tool cache, it falls back to
+  downloading the Go toolchain from dl.google.com/go. This fallback:
+  1. Adds 30-90 seconds of download time per job (depending on network speed)
+  2. Fails entirely in self-hosted runners without internet access or strict outbound
+     firewall rules blocking dl.google.com
+  3. May fail intermittently if the Google CDN experiences transient issues
+
+  Workflows with many parallel matrix jobs (e.g., matrix of Go versions or OS targets)
+  multiply this overhead: 20 parallel jobs each downloading Go = 20 concurrent CDN requests.
+fix: |
+  Upgrade to a currently-supported Go version. As of 2025-2026, the two supported releases
+  are Go 1.23 and Go 1.24. Both are pre-cached in the runner tool cache and resolve
+  instantly without any network download.
+
+  Use the go-version-file input to read the version from go.mod, ensuring your CI always
+  matches your project's declared Go version.
+fix_code:
+  - language: yaml
+    label: 'Pin to a supported Go version (no tool-cache miss)'
+    code: |
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'   # or '1.23' — both are in the runner tool cache
+          cache: true
+  - language: yaml
+    label: 'Use go-version-file to read version from go.mod'
+    code: |
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'  # reads `go 1.24` directive from go.mod
+          cache: true
+prevention:
+  - 'Keep go-version in your workflows aligned with the go directive in go.mod'
+  - 'Upgrade Go versions proactively before EOL — the Go team announces EOL dates 6 months in advance'
+  - 'Use go-version-file: go.mod so your CI automatically follows your module declaration'
+  - 'Monitor https://go.dev/doc/devel/release for maintenance status of Go releases'
+docs:
+  - url: 'https://go.dev/doc/devel/release'
+    label: 'Go release history and maintenance policy'
+  - url: 'https://github.com/actions/setup-go'
+    label: 'actions/setup-go — go-version and go-version-file inputs'
+  - url: 'https://github.com/actions/runner-images'
+    label: 'GitHub runner images — preinstalled tool versions'

package/errors/yaml-syntax/env-context-unavailable-defaults-run-working-directory.yml

@@ -0,0 +1,113 @@
+id: yaml-syntax-065
+title: 'env context unavailable in defaults.run.working-directory — "Unrecognized named-value: env"'
+category: yaml-syntax
+severity: error
+tags:
+  - env
+  - context
+  - defaults
+  - working-directory
+  - expression
+  - context-availability
+patterns:
+  - regex: 'Unrecognized named-value: ''env''.*defaults|defaults.*working.directory.*env'
+    flags: 'i'
+  - regex: 'The workflow is not valid.*defaults\.run\.working-directory.*env\.'
+    flags: 'i'
+  - regex: 'Unrecognized named-value: ''env''.*position.*working.directory'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/<workflow>.yml (Line: X, Col: Y): Unrecognized named-value: 'env'. Located at position 1 within expression: env.WORKING_DIR"
+  - "Unrecognized named-value: 'env'"
+root_cause: |
+  The `env` context is only available during step execution — not at job evaluation time.
+  `defaults.run.working-directory` is a job-level field evaluated before any steps run,
+  so GitHub Actions rejects references to `env.*` inside it with "Unrecognized named-value: 'env'".
+
+  This is the same fundamental limitation that affects other job-level fields (if:,
+  runs-on, timeout-minutes, continue-on-error) but is less documented for defaults.run.
+
+  Common patterns that fail:
+  - Setting a shared working directory from a workflow-level env variable:
+      env:
+        APP_DIR: './packages/app'
+      jobs:
+        build:
+          defaults:
+            run:
+              working-directory: ${{ env.APP_DIR }}  # FAILS — env not available here
+
+  - Reading an env var set in another job:
+      jobs:
+        setup:
+          ...
+        build:
+          defaults:
+            run:
+              working-directory: ${{ env.BUILD_DIR }}  # FAILS — env from another job not visible
+
+  The limitation applies to all expressions in defaults.run.working-directory and
+  defaults.run.shell at both the workflow level and the job level.
+fix: |
+  Replace env context references in defaults.run.working-directory with contexts that are
+  available at job evaluation time:
+
+  1. Use vars.* (repository or environment variables configured in Settings) for static paths
+  2. Use inputs.* if inside a reusable workflow called with workflow_call
+  3. Set working-directory on each individual step instead of at defaults level
+  4. Use an outputs chain from a prior job if the path is computed dynamically
+fix_code:
+  - language: yaml
+    label: 'WRONG — env context in defaults.run.working-directory (fails)'
+    code: |
+      env:
+        APP_DIR: './packages/app'
+
+      jobs:
+        build:
+          defaults:
+            run:
+              working-directory: ${{ env.APP_DIR }}  # Error: Unrecognized named-value 'env'
+  - language: yaml
+    label: 'FIX option 1 — use vars context (repository variable)'
+    code: |
+      # Configure APP_DIR in Settings > Secrets and variables > Variables
+      jobs:
+        build:
+          defaults:
+            run:
+              working-directory: ${{ vars.APP_DIR }}  # repository variable — available at job level
+  - language: yaml
+    label: 'FIX option 2 — set working-directory on each step directly'
+    code: |
+      jobs:
+        build:
+          env:
+            APP_DIR: './packages/app'
+          steps:
+            - name: Build
+              run: npm run build
+              working-directory: ${{ env.APP_DIR }}  # env IS available at step level
+            - name: Test
+              run: npm test
+              working-directory: ${{ env.APP_DIR }}
+  - language: yaml
+    label: 'FIX option 3 — hardcode the path in defaults.run'
+    code: |
+      jobs:
+        build:
+          defaults:
+            run:
+              working-directory: ./packages/app  # literal path, no context expression needed
+prevention:
+  - 'Only use vars.*, github.*, inputs.*, or needs.*.outputs.* in job-level expressions — env.* is never available at job level'
+  - 'For shared working directories, prefer literal paths in defaults.run.working-directory over expressions'
+  - 'If the path must be dynamic, use step-level working-directory instead of defaults.run'
+  - 'Use actionlint to validate workflows locally — it catches env context misuse in job-level fields'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/setting-default-values-for-jobs'
+    label: 'GitHub Actions — Setting default values for jobs (defaults.run)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability'
+    label: 'GitHub Actions context availability by workflow key'
+  - url: 'https://github.com/rhysd/actionlint'
+    label: 'actionlint — static checker that validates context availability'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.101",
+  "version": "1.0.102",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",