@htekdev/actions-debugger 1.0.13 → 1.0.15

package/errors/yaml-syntax/fromjson-empty-string-crash.yml

@@ -0,0 +1,99 @@
+id: yaml-syntax-021
+title: "fromJSON() on empty or undefined step output throws Unexpected end of JSON input"
+category: yaml-syntax
+severity: error
+tags:
+  - fromjson
+  - outputs
+  - expression
+  - json
+  - step-outputs
+  - dynamic-matrix
+patterns:
+  - regex: "Unexpected end of JSON input"
+    flags: "i"
+  - regex: "Invalid JSON for parameter"
+    flags: "i"
+  - regex: "is not valid JSON"
+    flags: "i"
+  - regex: "fromJSON.*failed"
+    flags: "i"
+error_messages:
+  - "Unexpected end of JSON input"
+  - "Error: Invalid JSON for parameter 'matrix': Unexpected end of JSON input"
+  - "Error: The expression result is not valid JSON"
+root_cause: |
+  fromJSON() is a GitHub Actions expression function that parses a JSON string.
+  When the input string is empty ("") — which happens when a step output was
+  never set or when the step that set it was skipped due to an if: condition —
+  fromJSON() throws a fatal parse error: "Unexpected end of JSON input".
+
+  This is especially common in dynamic matrix strategies:
+
+    matrix:
+      include: ${{ fromJSON(steps.generate.outputs.matrix) }}
+
+  If the generate step was skipped (e.g., if: github.event_name == 'push'),
+  steps.generate.outputs.matrix evaluates to empty string, and fromJSON("")
+  crashes the entire job before any steps run.
+
+  The expression evaluator does NOT treat empty string as null or as valid
+  empty JSON — it passes the raw empty string directly to the JSON parser,
+  which rejects it immediately.
+fix: |
+  Provide a fallback JSON value using the || operator so that fromJSON always
+  receives valid JSON even when the output is empty:
+
+    fromJSON(steps.generate.outputs.matrix || '[]')
+    fromJSON(steps.generate.outputs.config || '{}')
+
+  For dynamic matrix strategies, also ensure the generating step always
+  outputs valid JSON (at minimum '[]' or '{}') rather than leaving the
+  output unset when there is nothing to process.
+
+  Add an if: condition on downstream jobs to skip entirely when the matrix
+  output is empty or equals the empty-array sentinel.
+fix_code:
+  - language: yaml
+    label: "Guard fromJSON with a valid JSON fallback using the || operator"
+    code: |
+      jobs:
+        compute-matrix:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.gen.outputs.matrix }}
+          steps:
+            - id: gen
+              run: |
+                # Always emit valid JSON — even when there is nothing to build
+                TARGETS=$(cat targets.json 2>/dev/null || echo '[]')
+                echo "matrix=$TARGETS" >> $GITHUB_OUTPUT
+
+        build:
+          needs: compute-matrix
+          if: ${{ needs.compute-matrix.outputs.matrix != '[]' }}
+          strategy:
+            matrix:
+              # fromJSON never sees empty string — falls back to []
+              include: ${{ fromJSON(needs.compute-matrix.outputs.matrix || '[]') }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Building ${{ matrix.target }}"
+  - language: yaml
+    label: "Inline fallback for dynamic matrix include"
+    code: |
+      strategy:
+        matrix:
+          include: ${{ fromJSON(needs.setup.outputs.matrix || '[{"env":"default"}]') }}
+prevention:
+  - "Always provide a valid JSON fallback: fromJSON(steps.x.outputs.val || '{}')"
+  - "Ensure output-producing steps always write a value even if it is an empty array or object"
+  - "Add if: conditions to skip downstream jobs entirely when the matrix output is empty"
+  - "Validate fromJSON expressions with an empty-output test scenario in a draft workflow"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson"
+    label: "GitHub Docs — fromJSON expression function"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "GitHub Docs — Passing information between jobs using outputs"
+  - url: "https://github.com/orgs/community/discussions/26671"
+    label: "GitHub Community #26671 — fromJSON fails when output is empty string"

package/errors/yaml-syntax/if-bang-negation-yaml-tag.yml

@@ -0,0 +1,145 @@
+id: yaml-syntax-020
+title: "if: !cancelled() Triggers YAML Tag Parse Error — Must Quote or Use Expression Syntax"
+category: yaml-syntax
+severity: error
+tags:
+  - if-condition
+  - cancelled
+  - yaml-tag
+  - expression-syntax
+  - negation
+  - bang-operator
+  - always-run
+  - parse-error
+patterns:
+  - regex: "if:\\s*!(?:cancelled|failure|success|always)\\(\\)"
+    flags: "im"
+  - regex: "mapping values are not allowed here|did not find expected key|could not find expected"
+    flags: "i"
+  - regex: "yaml.*tag.*!\\w+|Unknown tag"
+    flags: "i"
+error_messages:
+  - "mapping values are not allowed here"
+  - "could not find expected ':'"
+  - "did not find expected key"
+  - "Error: YAMLException: bad indentation of a mapping entry"
+  - "Invalid workflow file: You have an error in your yaml syntax"
+root_cause: |
+  In YAML, `!` is a reserved indicator used to specify **explicit type tags**
+  (e.g., `!!str`, `!python/object`). When you write an unquoted `if:` value starting
+  with `!`, the YAML parser interprets it as a tag application — NOT as boolean negation.
+
+  For example:
+  ```
+  if: !cancelled()   # YAML reads this as: apply tag "cancelled()" to null value
+  ```
+
+  Because `!cancelled()` is an invalid YAML tag application (no value follows the tag,
+  or the parentheses make it syntactically invalid as a tag identifier), this causes a
+  YAML parse error and the entire workflow file is rejected with messages like
+  "mapping values are not allowed here" or "bad indentation of a mapping entry".
+
+  This is a common mistake because developers familiar with programming languages expect
+  `!` to be a boolean NOT operator, which it is inside GitHub Actions expressions
+  (`${{ !cancelled() }}`), but NOT in bare YAML string values.
+
+  Affected operators:
+  - `if: !cancelled()` → YAML tag error
+  - `if: !failure()`   → YAML tag error
+  - `if: !success()`   → YAML tag error (rare, but same pattern)
+
+  The fix is either:
+  1. Wrap in expression delimiters: `if: ${{ !cancelled() }}`
+  2. Quote the value:             `if: "!cancelled()"`
+  Both forms are valid GitHub Actions `if:` conditions.
+
+  Source: GitHub Community Discussion — common YAML parse error with if: conditions
+  Source: GitHub Actions documentation — Expressions syntax
+fix: |
+  Choose one of two equivalent fixes:
+
+  Option 1 — Use expression syntax (recommended, more explicit):
+    `if: ${{ !cancelled() }}`
+
+  Option 2 — Quote the string (also valid):
+    `if: "!cancelled()"`
+
+  Both options tell the YAML parser to treat the value as a plain string / expression,
+  bypassing the tag interpretation.
+
+  Note: Inside `${{ }}` expression blocks, `!` IS the boolean NOT operator and works
+  as expected. Outside those blocks, bare YAML values starting with `!` are parsed as
+  YAML type tags.
+fix_code:
+  - language: yaml
+    label: "Fix: use ${{ }} expression syntax for negation"
+    code: |
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          steps:
+            # ❌ WRONG: YAML parse error — ! is a YAML tag indicator
+            - name: Run unless cancelled (broken)
+              if: !cancelled()
+              run: ./cleanup.sh
+
+            # ✅ CORRECT: wrap in expression delimiters
+            - name: Run unless cancelled (fixed)
+              if: ${{ !cancelled() }}
+              run: ./cleanup.sh
+
+            # ✅ ALSO CORRECT: quote the string
+            - name: Run unless cancelled (also fixed)
+              if: "!cancelled()"
+              run: ./cleanup.sh
+
+  - language: yaml
+    label: "Common patterns: negating status check functions"
+    code: |
+      jobs:
+        notify:
+          runs-on: ubuntu-latest
+          steps:
+            # Run step if previous steps did NOT fail
+            - name: Send success notification
+              if: ${{ !failure() }}
+              run: ./notify-success.sh
+
+            # Run if job was NOT cancelled (catch failures too)
+            - name: Always-ish cleanup (skips on cancel)
+              if: ${{ !cancelled() }}
+              run: ./cleanup.sh
+
+            # Job-level condition: run this job if parent was not skipped or failed
+            # (equivalent to always() but excluding explicitly-failed states)
+
+  - language: yaml
+    label: "Using always() instead of !cancelled() when appropriate"
+    code: |
+      jobs:
+        report:
+          runs-on: ubuntu-latest
+          # always() runs regardless of success, failure, OR cancellation
+          # !cancelled() runs on success OR failure, but NOT cancellation
+          steps:
+            - name: Report always (even if cancelled)
+              if: always()
+              run: ./post-report.sh
+
+            - name: Report unless cancelled
+              if: ${{ !cancelled() }}
+              run: ./post-report-unless-cancelled.sh
+
+prevention:
+  - "Always wrap boolean expressions using `!`, `&&`, or `||` inside `${{ }}` delimiters in `if:` conditions."
+  - "Quote any `if:` value that starts with `!` if you prefer not to use expression syntax."
+  - "Use `always()` when you want to run regardless of success, failure, AND cancellation."
+  - "Use `!cancelled()` (inside `${{ }}`) when you want to run on success or failure, but not cancellation."
+  - "Lint workflows with `actionlint` locally — it catches YAML tag parse errors before push."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#operators"
+    label: "GitHub Docs: Expressions — operators (! boolean NOT)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#status-check-functions"
+    label: "GitHub Docs: Expressions — status check functions (cancelled, failure, success)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif"
+    label: "GitHub Docs: Workflow syntax — steps.if"

package/errors/yaml-syntax/local-action-path-always-top-level.yml

@@ -0,0 +1,142 @@
+id: yaml-syntax-019
+title: "Local Composite Action 'uses:' Paths Always Resolve From Repository Root"
+category: yaml-syntax
+severity: error
+tags:
+  - composite-action
+  - local-action
+  - uses
+  - path-resolution
+  - runner
+  - file-not-found
+patterns:
+  - regex: "Can't find '.*action\\.ya?ml'"
+    flags: "i"
+  - regex: "Unable to resolve action.*local"
+    flags: "i"
+  - regex: "Action.*not found.*\\./"
+    flags: "i"
+  - regex: "Error.*action.ya?ml.*does not exist"
+    flags: "i"
+error_messages:
+  - "Can't find 'action.yml', 'action.yaml' or 'Dockerfile' under '/home/runner/work/repo/repo/actions/my-action'. Did you forget to run actions/checkout?"
+  - "Error: Unable to resolve action `./actions/my-action`, unable to find action at path: /home/runner/work/repo/repo/actions/my-action"
+  - "Error: Can't find action.yml at referenced path ./relative/path/to/action"
+root_cause: |
+  When referencing a **local composite action** with a relative path (`uses: ./path/to/action`),
+  the GitHub Actions runner **always resolves the path relative to the root of the repository
+  that was checked out**, regardless of where the calling workflow or action lives.
+
+  This surprises developers who expect relative paths to resolve from the current file's
+  location (like `import './relative'` in Node.js or `include` in languages). GitHub Actions
+  does not work that way.
+
+  **Common mistake — calling a composite action from another composite action:**
+  ```yaml
+  # In .github/actions/build/action.yml
+  runs:
+    using: composite
+    steps:
+      - uses: ./actions/shared/setup   # Developer expects: relative to THIS file's location
+                                        # Reality: resolves from repo root → correct if structure matches
+                                        # BUT: when called FROM another repo, it resolves in the caller's repo
+  ```
+
+  **Cross-repo misunderstanding:**
+  When a reusable workflow or composite action is stored in a **different repository** and
+  called externally (e.g., `uses: org/shared-actions/.github/workflows/build.yml@main`),
+  local `./` paths inside that called action resolve from the **caller's** repository root,
+  not the shared action's repository. The files don't exist there.
+
+  **Why it fails:**
+  - The runner checks out the correct repo but resolves `./` from that checkout root
+  - Nested relative paths in composite actions called from another repo fail entirely
+  - Error messages mention the runner's workspace path, making the root cause unclear
+
+  Source: actions/runner#1348
+fix: |
+  **Option 1 (recommended): Use absolute repository-relative paths from the repo root**
+
+  Design your repository layout so all local action references make sense from the repo root.
+  All `uses: ./` paths must be valid paths starting from the repository root.
+
+  **Option 2: Publish shared actions as versioned releases**
+
+  For actions shared across repositories, publish them as proper GitHub Actions in their
+  own repository and reference them with `uses: org/repo/path@version` rather than
+  relative paths.
+
+  **Option 3: Avoid nesting composite actions that reference other local actions**
+
+  Flatten composite action steps so they do not call other local composite actions with
+  relative paths — inline the shared steps or extract them into a single action.
+fix_code:
+  - language: yaml
+    label: "Broken — relative path in composite action misunderstood as file-relative"
+    code: |
+      # ❌ BROKEN: Developer expects ./setup to resolve relative to this action file
+      # File: .github/actions/build/action.yml
+      runs:
+        using: composite
+        steps:
+          # This resolves from REPO ROOT as ./setup — NOT from .github/actions/build/
+          - uses: ./setup          # Fails if there is no 'setup/action.yml' at repo root
+          - uses: ./shared/lint    # Same problem
+
+      # ✅ What the developer meant (but is not how it works):
+      #   ./setup → .github/actions/build/setup/action.yml  (WRONG assumption)
+      # What the runner does:
+      #   ./setup → <repo-root>/setup/action.yml            (CORRECT behavior)
+  - language: yaml
+    label: "Fixed — use full repo-root-relative paths"
+    code: |
+      # ✅ FIXED: Use paths that are correct relative to the repo root
+      # Repo layout:
+      #   .github/actions/build/action.yml
+      #   .github/actions/setup/action.yml   ← shared action
+
+      # File: .github/actions/build/action.yml
+      runs:
+        using: composite
+        steps:
+          - uses: ./.github/actions/setup   # ✅ Correct: resolves from repo root
+  - language: yaml
+    label: "Fixed — publish shared action to its own repo for cross-repo use"
+    code: |
+      # ✅ FIXED: For cross-repo shared actions, publish as a versioned action
+      # Instead of local ./path references, use:
+      runs:
+        using: composite
+        steps:
+          - uses: org/shared-actions/setup@v1   # ✅ Explicit repo + version reference
+
+      # This avoids ALL path resolution ambiguity when calling across repositories
+  - language: yaml
+    label: "Fixed — flatten composite action to avoid nested local references"
+    code: |
+      # ✅ ALTERNATIVE: Inline shared steps instead of nesting composite calls
+      # File: .github/actions/build/action.yml
+      runs:
+        using: composite
+        steps:
+          # Inline what ./setup would have done:
+          - name: Setup Node
+            uses: actions/setup-node@v4
+            with:
+              node-version: '20'
+          - name: Install dependencies
+            run: npm ci
+            shell: bash
+prevention:
+  - "Always verify that local `uses: ./path` references point to valid paths from the **repository root**, not from the file containing the reference."
+  - "Use `ls .github/actions/` and verify the path structure before expecting `./` local action references to resolve correctly."
+  - "For actions used across multiple repositories, always use a versioned `org/repo/path@ref` reference — never `./` relative paths."
+  - "Avoid deeply nested composite actions that call other local composite actions; flatten where possible to reduce path resolution complexity."
+  - "When a composite action is called from an external repo via `uses: org/repo/.github/workflows/...`, remember that all `./` paths inside it resolve in the CALLER's repo."
+docs:
+  - url: "https://github.com/actions/runner/issues/1348"
+    label: "actions/runner#1348 — Local composite action path resolution always from top-level repo"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/about-custom-actions#using-an-action-in-the-same-repository-as-a-workflow"
+    label: "GitHub Docs: Using a local action in the same repository"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action"
+    label: "GitHub Docs: Creating a composite action"

package/package.json

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