@htekdev/actions-debugger 1.0.91 → 1.0.92

package/errors/runner-environment/windows-max-path-260-npm-build-failure.yml

@@ -0,0 +1,87 @@
+id: runner-environment-158
+title: 'Windows MAX_PATH 260-character limit causes npm and build tool failures'
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - max-path
+  - npm
+  - node_modules
+  - path-length
+  - enoent
+  - build
+patterns:
+  - regex: 'The filename or extension is too long'
+    flags: 'i'
+  - regex: 'ENOENT.*node_modules.*node_modules'
+    flags: 'i'
+  - regex: 'error MSB3095.*path.*too long'
+    flags: 'i'
+  - regex: 'The system cannot find the path specified'
+    flags: 'i'
+error_messages:
+  - "The filename or extension is too long."
+  - "ENOENT: no such file or directory, open 'C:\\Users\\runner\\work\\..."
+  - "error MSB3095: Invalid argument. 'path' is too long."
+  - "npm ERR! path C:\\Users\\runner\\work\\..."
+root_cause: |
+  Windows enforces a 260-character maximum path length (MAX_PATH) inherited from
+  the Win32 API. Deep node_modules dependency trees easily exceed this limit: the
+  GitHub-hosted runner workspace is already at
+  C:\Users\runner\work\<repository>\<repository>\ (~50 characters) before any
+  source files are added. A typical transitive npm dependency path like
+  node_modules\pkg\node_modules\sub\node_modules\deep\index.js can push the total
+  well past 260 characters. MSBuild, Java build tools, and other Windows toolchains
+  have the same limitation.
+
+  GitHub-hosted Windows runners (windows-2022, windows-latest) have the
+  LongPathsEnabled registry key set to 1 at the OS level, but Git must still be
+  separately configured with core.longpaths = true, and some Node.js internal APIs
+  call the legacy Win32 CreateFile path which ignores the registry opt-in unless
+  the application explicitly declares long-path awareness in its executable manifest.
+  The result is ENOENT or "path too long" failures that appear to indicate missing
+  files rather than a path-length limit.
+fix: |
+  Option 1 (most effective): Use a short path: in actions/checkout to reduce the
+  base path length. path: a sets the workspace to C:\...\work\repo\a.
+  Option 2: Configure Git long paths and use --legacy-peer-deps to flatten
+  npm dependency nesting.
+  Option 3: Shorten the repository name, which directly reduces the workspace
+  path length.
+fix_code:
+  - language: yaml
+    label: 'Use short checkout path to reduce base path length'
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                path: a   # Reduces base path by ~20-30 characters vs default
+            - run: npm ci
+              working-directory: a
+  - language: yaml
+    label: 'Enable Git long paths and flatten npm tree'
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - name: Configure Git long paths
+              run: git config --global core.longpaths true
+            - uses: actions/checkout@v4
+            - name: Install with flattened dependencies
+              run: npm ci --legacy-peer-deps
+prevention:
+  - 'Use path: a (or another single-char name) in actions/checkout to reduce baseline path length on Windows'
+  - 'Keep GitHub repository names short when Windows CI is required'
+  - 'Avoid deeply nested workspace directory structures'
+  - 'Run npm ci --legacy-peer-deps to reduce node_modules nesting on npm 7+ which introduced deeper trees'
+docs:
+  - url: 'https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation'
+    label: 'Microsoft Docs: Maximum file path limitation (MAX_PATH)'
+  - url: 'https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreprotectNTFS'
+    label: 'Git: core.longpaths config'
+  - url: 'https://docs.npmjs.com/cli/v10/commands/npm-ci'
+    label: 'npm ci — clean install'

package/errors/silent-failures/pull-request-branches-filter-not-inherited.yml

@@ -0,0 +1,73 @@
+id: silent-failures-086
+title: 'on.pull_request does not inherit branches filter from sibling on.push trigger'
+category: silent-failures
+severity: silent-failure
+tags:
+  - pull_request
+  - push
+  - branches-filter
+  - trigger
+  - unexpected-runs
+  - filter-inheritance
+patterns:
+  - regex: 'on:\s*\n\s*push:\s*\n\s*branches:\s*\n.*\n\s*pull_request:\s*\n(?!\s*branches:)'
+    flags: 'ms'
+error_messages: []
+root_cause: |
+  When a workflow defines multiple triggers under on:, each trigger's configuration
+  is fully independent — there is no filter inheritance between sibling triggers.
+  A common pattern is to restrict on.push to specific branches (e.g., main,
+  release/**) while adding on.pull_request with no branches: key, expecting the
+  PR trigger to respect the same branch scope.
+
+  In YAML mapping semantics, on.push.branches: [main] applies exclusively to push
+  events. on.pull_request with no branches: key means "trigger for pull requests
+  targeting ANY branch in the repository." This causes the workflow to run on every
+  PR opened against feature branches, release candidates, or any other branch —
+  running expensive CI on PRs the developer intended to exclude.
+
+  The GitHub Actions UI shows these runs as triggered by pull_request with no
+  indication that the branches: filter was missing. The behavior appears correct
+  (workflow ran) but occurs on unintended PRs.
+fix: |
+  Explicitly add a branches: filter to on.pull_request that defines the target
+  branches for which CI should run. Note that on.pull_request.branches matches the
+  BASE branch (the branch the PR targets), not the head/feature branch.
+fix_code:
+  - language: yaml
+    label: 'Explicit branches filter on both triggers'
+    code: |
+      on:
+        push:
+          branches: [main, 'release/**']
+        pull_request:
+          branches: [main, 'release/**']  # Required — NOT inherited from on.push
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm test
+  - language: yaml
+    label: 'Common mistake — missing branches on pull_request'
+    code: |
+      # WRONG — pull_request triggers for ALL target branches
+      on:
+        push:
+          branches: [main]
+        pull_request:           # No branches filter — triggers for every PR
+      # CORRECT
+      on:
+        push:
+          branches: [main]
+        pull_request:
+          branches: [main]      # Only PRs targeting main
+prevention:
+  - 'Review each trigger block independently — on.push and on.pull_request filters are never shared'
+  - 'Add an explicit branches: under on.pull_request whenever you use branches: under on.push'
+  - 'Remember: on.pull_request.branches matches the BASE branch of the PR, not the feature branch'
+  - 'Use actionlint to validate trigger configurations before committing'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#using-filters'
+    label: 'GitHub Docs: Using filters — each trigger is configured independently'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore'
+    label: 'GitHub Actions: pull_request branches filter matches base branch'

package/errors/triggers/delete-event-fires-branch-and-tag.yml

@@ -0,0 +1,75 @@
+id: triggers-061
+title: 'on.delete fires for branch and tag deletion — no ref_type filter at trigger level'
+category: triggers
+severity: silent-failure
+tags:
+  - delete
+  - ref_type
+  - branch
+  - tag
+  - unexpected-runs
+patterns:
+  - regex: 'on:\s*\n\s*delete:'
+    flags: 'ms'
+error_messages: []
+root_cause: |
+  The on.delete event fires whenever any branch or tag is deleted in the repository.
+  Unlike some events that support a types: activity filter, on.delete has no types
+  option — there is no trigger-level way to restrict it to branch deletions only or
+  tag deletions only. Workflows that perform branch-specific cleanup (removing
+  temporary deployment environments, rotating secrets, updating external project
+  boards, or archiving feature branch artifacts) run for EVERY tag deletion as well,
+  unless an explicit runtime condition is added inside the workflow.
+
+  The on.create event has the same dual-fire behavior (documented separately). Both
+  events expose github.event.ref_type in the workflow context as either 'branch' or
+  'tag', but this value is only available inside the workflow body — it cannot be
+  used as a trigger-level filter.
+
+  A common scenario: a workflow cleans up branch-specific cloud environments on
+  delete. When a developer deletes the release tag v1.2.3, the workflow fires
+  unexpectedly — potentially tearing down a production environment that was deployed
+  from that tag.
+fix: |
+  Add an if: condition using github.event.ref_type to guard jobs or steps that
+  should only execute for one type of deletion. Use 'branch' or 'tag' as the
+  comparison value.
+fix_code:
+  - language: yaml
+    label: 'Guard cleanup by ref_type at the job level'
+    code: |
+      on:
+        delete:
+      jobs:
+        cleanup-branch-environment:
+          # Only run for branch deletions — skip tag deletions
+          if: github.event.ref_type == 'branch'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Remove branch-specific deployment
+              run: echo "Cleaning up env for branch ${{ github.event.ref }}"
+  - language: yaml
+    label: 'Separate jobs for branch vs tag deletion'
+    code: |
+      on:
+        delete:
+      jobs:
+        cleanup-branch:
+          if: github.event.ref_type == 'branch'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Branch deleted ${{ github.event.ref }}"
+        cleanup-tag:
+          if: github.event.ref_type == 'tag'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Tag deleted ${{ github.event.ref }}"
+prevention:
+  - 'Always guard on.delete workflow jobs with if: github.event.ref_type == ''branch'' or ''tag'''
+  - 'Be aware that on.create has the same behavior — both create and delete fire for branches and tags'
+  - 'Test delete workflows by deleting both a branch and a tag to verify they behave as expected'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#delete'
+    label: 'GitHub Docs: delete event — fires for branches and tags'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs: github.event.ref_type context'

package/errors/triggers/pull-request-review-all-types-default.yml

@@ -0,0 +1,69 @@
+id: triggers-062
+title: 'on.pull_request_review fires for all review types (submitted, edited, dismissed) when types is omitted'
+category: triggers
+severity: silent-failure
+tags:
+  - pull_request_review
+  - review
+  - types
+  - dismissed
+  - submitted
+  - unexpected-runs
+patterns:
+  - regex: 'on:\s*\n\s*pull_request_review:\s*\n(?!\s*types:)'
+    flags: 'ms'
+error_messages: []
+root_cause: |
+  The pull_request_review event fires for three activity types:
+    - submitted: a new review is posted (approved, changes_requested, or commented)
+    - edited: a reviewer edits their review comment text
+    - dismissed: an existing approval or changes_requested review is dismissed
+
+  When on.pull_request_review: is specified without a types: filter, GitHub fires
+  the workflow for ALL three activity types. Developers typically use this event to
+  trigger a deployment or notification on PR approval. Without types: [submitted],
+  the workflow also runs when a reviewer edits their comment spelling or when an
+  approval is dismissed by a maintainer — often causing incorrect or failed workflow
+  runs in contexts where the PR is no longer in an approved state.
+
+  This behavior mirrors on.pull_request without types: (which fires for opened,
+  synchronize, and reopened by default) but is arguably more surprising because
+  "editing a review comment" and "dismissing a review" are far less common
+  developer actions than submitting a new review.
+fix: |
+  Add types: [submitted] to restrict the trigger to new review submissions.
+  If you only want to react to approvals specifically, also add an if: condition
+  checking github.event.review.state == 'approved'.
+fix_code:
+  - language: yaml
+    label: 'Restrict to submitted reviews only'
+    code: |
+      on:
+        pull_request_review:
+          types: [submitted]   # Only new review submissions — not edited or dismissed
+      jobs:
+        notify-on-review:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Review state ${{ github.event.review.state }}"
+  - language: yaml
+    label: 'Trigger only on PR approvals'
+    code: |
+      on:
+        pull_request_review:
+          types: [submitted]
+      jobs:
+        deploy-on-approval:
+          if: github.event.review.state == 'approved'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "PR approved — proceeding with staging deploy"
+prevention:
+  - 'Always specify types: [submitted] under on.pull_request_review unless dismissed or edited is explicitly needed'
+  - 'Combine types: [submitted] with if: github.event.review.state == ''approved'' for approval-gated workflows'
+  - 'Test pull_request_review workflows by also dismissing reviews to ensure unexpected runs are avoided'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_review'
+    label: 'GitHub Docs: pull_request_review event — activity types'
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request_review'
+    label: 'GitHub Webhooks: pull_request_review payload — review.state values'

package/package.json

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