@htekdev/actions-debugger 1.0.0 → 1.0.2

package/errors/yaml-syntax/missing-expression-wrapper.yml

@@ -0,0 +1,67 @@
+id: yaml-syntax-010
+title: "Expression Context Reference Without ${{ }} Wrapper Produces Literal String"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - yaml
+  - expressions
+  - context
+  - interpolation
+  - env
+  - variables
+patterns:
+  - regex: "github\\.sha|github\\.ref|github\\.actor"
+    flags: "i"
+  - regex: "env\\.[A-Z_]+ is not a valid"
+    flags: "i"
+error_messages:
+  - "Unexpected value 'github.sha'"
+  - "The expression 'github.ref' is not valid. Expected a string, number, boolean, or null literal."
+root_cause: |
+  GitHub Actions expressions must be wrapped in `${{ }}` to be evaluated. Without the
+  wrapper, the value is treated as a literal YAML string and passed verbatim.
+
+  This commonly happens in `env:` maps, `with:` inputs, and step outputs where developers
+  write `MY_VAR: github.sha` instead of `MY_VAR: ${{ github.sha }}`. The workflow runs
+  successfully but every downstream consumer sees the literal string `"github.sha"` rather
+  than the actual commit SHA.
+
+  The same issue affects `run:` steps using `echo $github.sha` (which bash interprets as
+  `$github` dot `sha`, producing an empty or unexpected value) instead of
+  `echo ${{ github.sha }}` or the equivalent `$GITHUB_SHA` environment variable.
+fix: |
+  Wrap every context reference in `${{ }}`. Prefer the built-in `GITHUB_*` environment
+  variables inside `run:` steps — they are always set and do not require expression syntax.
+fix_code:
+  - language: yaml
+    label: "WRONG — literal strings instead of expressions"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          env:
+            COMMIT: github.sha          # literal string "github.sha"
+            BRANCH: github.ref_name     # literal string "github.ref_name"
+          steps:
+            - run: echo "Building github.sha on github.ref_name"
+  - language: yaml
+    label: "CORRECT — use ${{ }} wrapper or built-in env vars"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          env:
+            COMMIT: ${{ github.sha }}
+            BRANCH: ${{ github.ref_name }}
+          steps:
+            # Inside run: steps, prefer built-in env vars — no expression syntax needed
+            - run: echo "Building $GITHUB_SHA on $GITHUB_REF_NAME"
+prevention:
+  - "Always wrap context references (`github.*`, `env.*`, `secrets.*`, `steps.*`) in `${{ }}`."
+  - "Inside `run:` steps, prefer the built-in `GITHUB_*` environment variables over expression syntax."
+  - "Use `actionlint` locally — it catches bare context references before you push."
+docs:
+  - url: "https://docs.github.com/en/actions/learn-github-actions/expressions"
+    label: "Expressions"
+  - url: "https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables"
+    label: "Default environment variables"

package/errors/yaml-syntax/needs-indirect-outputs.yml

@@ -0,0 +1,91 @@
+id: yaml-syntax-011
+title: "Accessing Outputs from Non-Direct needs Dependency Fails"
+category: yaml-syntax
+severity: error
+tags:
+  - needs
+  - outputs
+  - context
+  - job-dependencies
+  - expressions
+patterns:
+  - regex: "Unrecognized named-value: 'needs'"
+    flags: "i"
+  - regex: "needs\\.[a-z_-]+\\.outputs\\.[a-z_-]+ is not available"
+    flags: "i"
+  - regex: "Job '[^']+' references output '[^']+' from job '[^']+' that is not a direct dependency"
+    flags: "i"
+error_messages:
+  - "Unrecognized named-value: 'needs'. Located at position 1 within expression: needs.build.outputs.version"
+  - "Job 'deploy' references output 'version' from job 'build' that is not a direct dependency"
+root_cause: |
+  The `needs` context is only populated for the direct dependencies listed in a job's
+  `needs:` array. A job cannot reference outputs from a grandparent job that is not in
+  its own `needs:` list, even if an intermediate job depends on it.
+
+  For example, if `test` needs `build`, and `deploy` needs `test`, then `deploy` cannot
+  access `needs.build.outputs.version` — only `needs.test.outputs.*` is available.
+  `deploy` would need to either also list `build` in its `needs:`, or `test` would need
+  to re-expose `build`'s output as its own output.
+fix: |
+  Either add the upstream job directly to the dependent job's `needs:` list, or re-expose
+  the needed output through each intermediate job in the chain.
+fix_code:
+  - language: yaml
+    label: "WRONG — accessing grandparent output without direct dependency"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            version: ${{ steps.tag.outputs.version }}
+          steps:
+            - id: tag
+              run: echo "version=1.2.3" >> $GITHUB_OUTPUT
+
+        test:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm test
+
+        deploy:
+          needs: test           # build is NOT in this list
+          runs-on: ubuntu-latest
+          steps:
+            # ERROR: needs.build.outputs.version is unavailable here
+            - run: echo "Deploying ${{ needs.build.outputs.version }}"
+  - language: yaml
+    label: "CORRECT option 1 — add build to deploy's needs directly"
+    code: |
+      jobs:
+        deploy:
+          needs: [test, build]   # both listed
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying ${{ needs.build.outputs.version }}"
+  - language: yaml
+    label: "CORRECT option 2 — propagate output through intermediate job"
+    code: |
+      jobs:
+        test:
+          needs: build
+          runs-on: ubuntu-latest
+          outputs:
+            version: ${{ needs.build.outputs.version }}  # re-expose
+          steps:
+            - run: npm test
+
+        deploy:
+          needs: test
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying ${{ needs.test.outputs.version }}"
+prevention:
+  - "Draw your job dependency graph before writing `needs:` — a job can only see outputs from jobs it directly depends on."
+  - "When a value needs to flow through multiple jobs, explicitly re-expose it as an output at each stage."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "Passing information between jobs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds"
+    label: "jobs.<job_id>.needs"

package/errors/yaml-syntax/reusable-workflow-missing-output-declaration.yml

@@ -0,0 +1,140 @@
+id: yaml-syntax-013
+title: "Reusable Workflow Output Missing on.workflow_call.outputs Declaration"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow-call
+  - outputs
+  - silent-failure
+  - job-outputs
+patterns:
+  - regex: "needs\\.[a-zA-Z0-9_-]+\\.outputs\\.[a-zA-Z0-9_-]+"
+    flags: "i"
+  - regex: "on\\.workflow_call\\.outputs.*not defined"
+    flags: "i"
+  - regex: "output.*reusable.*workflow.*empty"
+    flags: "i"
+error_messages:
+  - "The output variable was not found in the called workflow's on.workflow_call.outputs map."
+  - "Output 'version' not found in called workflow."
+root_cause: |
+  A called (reusable) workflow exposes job-level outputs but forgets to declare them at
+  the `workflow_call` trigger level. As a result the caller workflow's
+  `needs.<called-job>.outputs.<name>` expression evaluates to an empty string with NO
+  error message — a silent failure.
+
+  GitHub Actions requires a two-layer output declaration for reusable workflows:
+  1. The job inside the called workflow declares step outputs via `outputs:` on the job.
+  2. The called workflow's `on.workflow_call.outputs:` section explicitly maps workflow-
+     level output names to job-level output expressions.
+
+  If layer 2 is missing, the caller never receives the value even though layer 1 exists.
+  Because the expression resolves to an empty string (not an error), downstream steps may
+  silently receive wrong values — version tags become empty strings, Docker image names
+  become malformed, deploy environment names become blank.
+
+  A second variant occurs when accessing outputs from a called workflow that uses a matrix:
+  matrix job outputs cannot be aggregated automatically at the workflow level, so outputs
+  from individual matrix legs are inaccessible to the caller.
+fix: |
+  Add the `on.workflow_call.outputs:` section to the called workflow, mapping each
+  desired output name to the corresponding job output expression.
+
+  For matrix jobs: aggregate outputs into a single job (e.g. using `toJSON`) or use a
+  final non-matrix aggregator job inside the called workflow that reads matrix outputs
+  and re-exposes them as a single value.
+fix_code:
+  - language: yaml
+    label: "Called workflow — correct two-layer output declaration"
+    code: |
+      # .github/workflows/build-and-version.yml (CALLED workflow)
+      on:
+        workflow_call:
+          # Layer 2: workflow-level outputs (REQUIRED for caller to receive values)
+          outputs:
+            version:
+              description: "The computed version string"
+              value: ${{ jobs.build.outputs.version }}
+            artifact-name:
+              description: "Name of the uploaded artifact"
+              value: ${{ jobs.build.outputs.artifact-name }}
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # Layer 1: job-level outputs
+          outputs:
+            version: ${{ steps.compute-version.outputs.version }}
+            artifact-name: ${{ steps.upload.outputs.artifact-name }}
+          steps:
+            - id: compute-version
+              run: echo "version=1.2.3-${{ github.sha }}" >> $GITHUB_OUTPUT
+
+            - id: upload
+              uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+  - language: yaml
+    label: "Caller workflow — consuming outputs from called workflow"
+    code: |
+      # .github/workflows/deploy.yml (CALLER workflow)
+      jobs:
+        build:
+          uses: ./.github/workflows/build-and-version.yml
+          secrets: inherit
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy version
+              # This only works if the called workflow has on.workflow_call.outputs declared
+              run: |
+                echo "Deploying version: ${{ needs.build.outputs.version }}"
+                echo "Using artifact: ${{ needs.build.outputs.artifact-name }}"
+  - language: yaml
+    label: "Aggregate matrix outputs in a final job for caller consumption"
+    code: |
+      # Called workflow with matrix — aggregate results before exposing as outputs
+      on:
+        workflow_call:
+          outputs:
+            all-results:
+              value: ${{ jobs.aggregate.outputs.results }}
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              suite: [unit, integration, e2e]
+          outputs:
+            result-${{ matrix.suite }}: ${{ steps.run.outputs.result }}
+          steps:
+            - id: run
+              run: echo "result=passed" >> $GITHUB_OUTPUT
+
+        # Aggregator job: collects matrix outputs and re-exposes as single value
+        aggregate:
+          needs: test
+          runs-on: ubuntu-latest
+          outputs:
+            results: ${{ steps.collect.outputs.results }}
+          steps:
+            - id: collect
+              run: |
+                echo "results=${{ toJSON(needs.test.outputs) }}" >> $GITHUB_OUTPUT
+prevention:
+  - "Always declare `on.workflow_call.outputs:` in a reusable workflow if any caller needs its outputs."
+  - "Test output propagation by printing `${{ needs.<job>.outputs.<name> }}` in a debug step on the caller side."
+  - "Treat empty string outputs from called workflows as a sign of missing `on.workflow_call.outputs:` mapping."
+  - "Matrix jobs inside called workflows require an aggregator job — matrix outputs cannot be directly mapped."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-outputs-from-a-reusable-workflow"
+    label: "Reusable workflows: using outputs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_calloutputs"
+    label: "Workflow syntax: on.workflow_call.outputs"
+  - url: "https://stackoverflow.com/questions/73702333/github-actions-reuse-outputs-from-other-reusable-workflows"
+    label: "Stack Overflow: Reuse outputs from reusable workflows (82 upvotes)"

package/errors/yaml-syntax/secrets-in-if.yml

@@ -1,55 +1,55 @@
-id: yaml-syntax-005
-title: "secrets.* in if: Conditions — Silent Failures"
-category: yaml-syntax
-severity: silent-failure
-tags:
-  - secrets
-  - if
-  - expressions
-  - contexts
-  - env
-patterns:
-  - regex: "Unrecognized named-value: 'secrets'"
-    flags: "i"
-  - regex: "The workflow is not valid\\..*named-value: 'secrets'"
-    flags: "i"
-  - regex: "Context access might be invalid: secrets\\."
-    flags: "i"
-error_messages:
-  - "Unrecognized named-value: 'secrets'"
-root_cause: |
-  The `secrets` context is not available everywhere an expression can appear, and using
-  `secrets.*` directly inside an `if:` condition is a common trap. Depending on where the
-  expression is evaluated, GitHub Actions can reject the workflow or effectively treat the
-  check as unavailable.
-
-  The safe pattern is to map the secret into an environment variable first, then evaluate
-  the environment variable in the `if:` expression.
-fix: |
-  Pass the secret through `env:` and reference `env.NAME` in the `if:`. This keeps the
-  conditional supported and avoids direct `secrets.*` access in the condition.
-fix_code:
-  - language: yaml
-    label: "Gate a step using env instead of secrets directly"
-    code: |
-      jobs:
-        publish:
-          runs-on: ubuntu-latest
-          env:
-            HAS_TOKEN: ${{ secrets.NPM_TOKEN }}
-          steps:
-            - name: Publish
-              if: ${{ env.HAS_TOKEN != '' }}
-              run: npm publish
-prevention:
-  - "Do not reference `secrets.*` directly in `if:` unless the docs explicitly allow that context."
-  - "Promote secrets into `env` when a step should be conditionally gated."
-  - "Check the contexts reference before using a context in expressions."
-docs:
-  - url: "https://docs.github.com/en/actions/learn-github-actions/contexts"
-    label: "Contexts"
-  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif"
-    label: "jobs.<job_id>.steps[*].if"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "Secrets in if conditions"
+id: yaml-syntax-005
+title: "secrets.* in if: Conditions — Silent Failures"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - secrets
+  - if
+  - expressions
+  - contexts
+  - env
+patterns:
+  - regex: "Unrecognized named-value: 'secrets'"
+    flags: "i"
+  - regex: "The workflow is not valid\\..*named-value: 'secrets'"
+    flags: "i"
+  - regex: "Context access might be invalid: secrets\\."
+    flags: "i"
+error_messages:
+  - "Unrecognized named-value: 'secrets'"
+root_cause: |
+  The `secrets` context is not available everywhere an expression can appear, and using
+  `secrets.*` directly inside an `if:` condition is a common trap. Depending on where the
+  expression is evaluated, GitHub Actions can reject the workflow or effectively treat the
+  check as unavailable.
+
+  The safe pattern is to map the secret into an environment variable first, then evaluate
+  the environment variable in the `if:` expression.
+fix: |
+  Pass the secret through `env:` and reference `env.NAME` in the `if:`. This keeps the
+  conditional supported and avoids direct `secrets.*` access in the condition.
+fix_code:
+  - language: yaml
+    label: "Gate a step using env instead of secrets directly"
+    code: |
+      jobs:
+        publish:
+          runs-on: ubuntu-latest
+          env:
+            HAS_TOKEN: ${{ secrets.NPM_TOKEN }}
+          steps:
+            - name: Publish
+              if: ${{ env.HAS_TOKEN != '' }}
+              run: npm publish
+prevention:
+  - "Do not reference `secrets.*` directly in `if:` unless the docs explicitly allow that context."
+  - "Promote secrets into `env` when a step should be conditionally gated."
+  - "Check the contexts reference before using a context in expressions."
+docs:
+  - url: "https://docs.github.com/en/actions/learn-github-actions/contexts"
+    label: "Contexts"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif"
+    label: "jobs.<job_id>.steps[*].if"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Secrets in if conditions"

package/errors/yaml-syntax/unexpected-yaml-key.yml

@@ -1,69 +1,69 @@
-id: yaml-syntax-001
-title: "Unexpected or Typo'd YAML Keys"
-category: yaml-syntax
-severity: error
-tags:
-  - yaml
-  - syntax
-  - validation
-  - keys
-  - typos
-patterns:
-  - regex: "Unexpected value '\\w+'"
-    flags: "i"
-  - regex: "unexpected key \"\\w+\" for step"
-    flags: "i"
-  - regex: "The workflow is not valid\\..*Unexpected value '\\w+'"
-    flags: "i"
-error_messages:
-  - "Unexpected value 'default'"
-  - "Unexpected value 'Shell'"
-  - "Unexpected value 'branch'"
-root_cause: |
-  GitHub Actions workflow keys are schema-validated and case-sensitive. A typo like
-  `default:` instead of `defaults:`, `Shell:` instead of `shell:`, or `branch:` instead
-  of `branches:` is treated as an unknown key and the workflow is rejected before it runs.
-
-  This usually happens when copying snippets from memory or mixing YAML conventions from
-  other tools into GitHub Actions syntax.
-fix: |
-  Replace the invalid key with the exact schema-supported key name. Double-check plural
-  forms and casing against the workflow syntax reference.
-
-  Common fixes:
-  - `default:` -> `defaults:`
-  - `Shell:` -> `shell:`
-  - `branch:` -> `branches:`
-fix_code:
-  - language: yaml
-    label: "Use valid GitHub Actions keys"
-    code: |
-      name: CI
-
-      on:
-        push:
-          branches:
-            - main
-
-      defaults:
-        run:
-          shell: bash
-
-      jobs:
-        test:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v4
-            - run: npm test
-prevention:
-  - "Validate workflow files against the GitHub Actions workflow syntax docs before committing."
-  - "Prefer editing from working examples instead of typing keys from memory."
-  - "Use code review checks for `defaults`, `shell`, and `branches` because those typos are common."
-docs:
-  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
-    label: "Workflow syntax for GitHub Actions"
-  - url: "https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions"
-    label: "Understanding GitHub Actions"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "YAML validation and typo'd keys"
+id: yaml-syntax-001
+title: "Unexpected or Typo'd YAML Keys"
+category: yaml-syntax
+severity: error
+tags:
+  - yaml
+  - syntax
+  - validation
+  - keys
+  - typos
+patterns:
+  - regex: "Unexpected value '\\w+'"
+    flags: "i"
+  - regex: "unexpected key \"\\w+\" for step"
+    flags: "i"
+  - regex: "The workflow is not valid\\..*Unexpected value '\\w+'"
+    flags: "i"
+error_messages:
+  - "Unexpected value 'default'"
+  - "Unexpected value 'Shell'"
+  - "Unexpected value 'branch'"
+root_cause: |
+  GitHub Actions workflow keys are schema-validated and case-sensitive. A typo like
+  `default:` instead of `defaults:`, `Shell:` instead of `shell:`, or `branch:` instead
+  of `branches:` is treated as an unknown key and the workflow is rejected before it runs.
+
+  This usually happens when copying snippets from memory or mixing YAML conventions from
+  other tools into GitHub Actions syntax.
+fix: |
+  Replace the invalid key with the exact schema-supported key name. Double-check plural
+  forms and casing against the workflow syntax reference.
+
+  Common fixes:
+  - `default:` -> `defaults:`
+  - `Shell:` -> `shell:`
+  - `branch:` -> `branches:`
+fix_code:
+  - language: yaml
+    label: "Use valid GitHub Actions keys"
+    code: |
+      name: CI
+
+      on:
+        push:
+          branches:
+            - main
+
+      defaults:
+        run:
+          shell: bash
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - "Validate workflow files against the GitHub Actions workflow syntax docs before committing."
+  - "Prefer editing from working examples instead of typing keys from memory."
+  - "Use code review checks for `defaults`, `shell`, and `branches` because those typos are common."
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
+    label: "Workflow syntax for GitHub Actions"
+  - url: "https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions"
+    label: "Understanding GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "YAML validation and typo'd keys"

package/errors/yaml-syntax/working-directory-ignored-on-uses.yml

@@ -0,0 +1,66 @@
+id: yaml-syntax-012
+title: "working-directory Silently Ignored on uses: Action Steps"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - working-directory
+  - uses
+  - run
+  - composite
+  - silent
+  - monorepo
+patterns:
+  - regex: "working-directory"
+    flags: "i"
+error_messages:
+  - "The key 'working-directory' is not valid for a step that uses an action."
+root_cause: |
+  The `working-directory` step property only applies to `run:` steps. When set on a step
+  that uses `uses:`, GitHub Actions silently ignores it (or in stricter runtime versions,
+  emits a warning but still executes the action from its own checkout root).
+
+  This catches developers off-guard in monorepo setups where they try to scope an action
+  such as `actions/setup-node` to a subdirectory. The action always runs from the workspace
+  root regardless of `working-directory`.
+
+  If a custom composite action needs to operate in a specific directory, the caller must
+  pass the path as an `with:` input, or the composite action must use `cd` internally.
+fix: |
+  Remove `working-directory` from any `uses:` step. Pass the directory as an explicit
+  `with:` input if the action supports it, or add a separate `run: cd path && ...` step.
+fix_code:
+  - language: yaml
+    label: "WRONG — working-directory on a uses: step (silently ignored)"
+    code: |
+      steps:
+        - uses: actions/setup-node@v4
+          working-directory: ./packages/api   # has no effect
+          with:
+            node-version: 20
+
+        - uses: ./.github/actions/lint
+          working-directory: ./packages/ui    # also silently ignored
+  - language: yaml
+    label: "CORRECT — use an explicit run step to change directory first"
+    code: |
+      steps:
+        # setup-node always reads from workspace root
+        - uses: actions/setup-node@v4
+          with:
+            node-version: 20
+            cache: npm
+            cache-dependency-path: packages/api/package-lock.json
+
+        # For run: steps, working-directory works correctly
+        - name: Lint UI package
+          run: npx eslint .
+          working-directory: ./packages/ui
+prevention:
+  - "Only use `working-directory` on `run:` steps — never on `uses:` steps."
+  - "For actions that need a path, look for a `path` or `working-directory` `with:` input in the action's README."
+  - "Run `actionlint` locally — it will flag `working-directory` on `uses:` steps."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswith"
+    label: "jobs.<job_id>.steps[*].with"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun"
+    label: "jobs.<job_id>.steps[*].run"