feat: added npm audit fix to dependabot PRs

Author: mfranzke

.github/WORKFLOWS.md

@@ -14,9 +14,10 @@ This is the main orchestrator workflow that runs analysis tasks in parallel, the
 
 **Stage 1: Parallel Analysis** (All run simultaneously, no build required)
 
-- **Lint & Code Style** - XO linting, Markdown linting, Package checks by publint, Prettier checks
+- **Lint & Code Style** - XO linting, Markdown linting, Package checks by publint, Prettier checks, Spell checking with codespell
 - **Quality Analysis** - Test coverage, quality metrics (embedded quality checks)
-- **Security Analysis** - CodeQL security scanning (embedded security checks)
+- **Security Analysis** - CodeQL security scanning (calls `codeql.yml`)
+- **Audit Fix for Dependabot** - Automatically suggests `npm audit fix` for Dependabot PRs (calls `audit-fix-pr.yml`, conditional)
 
 **Stage 2: Build & Test** (Requires all Stage 1 to pass)
 
@@ -135,6 +136,35 @@ _Note: Comprehensive linting has been moved to default.yml to avoid duplication_
 
 _Note: This workflow remains independent as it handles specialized release processes_
 
+### 9. **Audit Fix for Dependabot PRs** (`.github/workflows/audit-fix-pr.yml`)
+
+**Triggers:** Dependabot PRs, Workflow calls from default.yml
+
+**Features:**
+
+- Automatically runs `npm audit fix` on Dependabot PRs
+- Creates follow-up PRs with security fixes when audit issues are found
+- Branches off the Dependabot PR for seamless integration
+- Adds appropriate labels (`security`, `dependabot`) for easy tracking
+- Only runs when Dependabot is the actor, minimizing unnecessary executions
+
+**Workflow:**
+
+1. Dependabot creates a PR with dependency updates
+2. Audit-fix workflow detects it's a Dependabot PR
+3. Runs `npm audit fix` to resolve any security vulnerabilities
+4. If changes are found, creates a new PR based on the Dependabot branch
+5. The new PR includes the audit fixes on top of the dependency updates
+
+**Benefits:**
+
+- **Proactive Security**: Catches and fixes security issues introduced by dependency updates
+- **Modular Design**: Separate workflow file maintains clean separation of concerns
+- **Automated Resolution**: Reduces manual intervention for common security fixes
+- **Clear Tracking**: Separate PRs make it easy to review security changes independently
+
+_Note: This workflow can run independently on PRs or be called from default.yml as part of the main pipeline_
+
 ## Workflow Architecture
 
 ### Parallel + Sequential Design
@@ -146,7 +176,8 @@ Default.yml (Orchestrator)
 ├── Stage 1: Parallel Analysis (simultaneous)
 │   ├── Lint & Code Style
 │   ├── Quality Analysis (with embedded testing)
-│   └── Security Analysis (CodeQL)
+│   ├── Security Analysis (CodeQL)
+│   └── Audit Fix for Dependabot (conditional)
 ├── Stage 2: CI Tests & Build (requires all Stage 1)
 ├── Stage 3: Performance Tests (conditional, requires Stage 2)
 ├── Stage 4: Deploy (main only, requires Stages 2-3)
@@ -258,6 +289,7 @@ All workflows use npm caching with `actions/setup-node@v4` to speed up dependenc
 - **CodeQL Analysis**: Automated security scanning
 - **npm audit**: Dependency vulnerability checking
 - **Dependabot**: Automated dependency updates
+- **Audit Fix Automation**: Automatically suggests `npm audit fix` for Dependabot PRs by creating follow-up PRs with security fixes
 - **Private security reporting**: Configured in issue templates
 
 ## Usage Examples

.github/workflows/audit-fix-pr.yml

@@ -0,0 +1,70 @@
+name: Suggest npm audit fix for Dependabot PRs
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    branches: [main]
+  workflow_call:
+
+jobs:
+  audit-fix:
+    if: github.actor == 'dependabot[bot]'
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit fix
+        run: npm audit fix
+
+      - name: Check if only package-lock.json changed
+        id: changes
+        run: |
+          git diff --name-only > changed_files.txt
+          cat changed_files.txt
+
+          if grep -Fxq "package-lock.json" changed_files.txt && [ "$(wc -l < changed_files.txt)" -eq 1 ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create PR with audit fix
+        if: steps.changes.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "chore: npm audit fix"
+          branch: "refactor-auditfix-${{ github.head_ref }}"
+          title: "chore: Apply npm audit fix on top of #${{ github.event.pull_request.number }}"
+          labels: security, dependabot
+          body: |
+            This PR applies `npm audit fix` on top of the Dependabot PR #${{ github.event.pull_request.number }}.
+
+            It is created automatically to suggest applying security updates that `npm audit fix` can resolve.
+          base: ${{ github.head_ref }}
+
+      - name: Approve PR
+        env:
+          GH_TOKEN: ${{ secrets.PAT_TOKEN }}
+        run: |
+          gh pr review ${{ steps.create-pr.outputs.pull-request-url }} --approve
+
+      - name: Enable Auto-Merge
+        env:
+          GH_TOKEN: ${{ secrets.PAT_TOKEN }}
+        run: |
+          gh pr merge ${{ steps.create-pr.outputs.pull-request-url }} --auto --squash

.github/workflows/default.yml

@@ -101,10 +101,19 @@ jobs:
       security-events: write
       packages: read
 
+  audit-fix:
+    name: Suggest npm audit fix for Dependabot PRs
+    uses: ./.github/workflows/audit-fix-pr.yml
+    secrets: inherit
+    permissions:
+      contents: write
+      pull-requests: write
+
   # Stage 2: Build and comprehensive testing (requires all analysis to pass)
   ci:
     name: CI Tests & Build
     needs: [lint, quality, security]
+    if: always() && (needs.lint.result == 'success') && (needs.quality.result == 'success') && (needs.security.result == 'success')
     uses: ./.github/workflows/ci.yml
     secrets: inherit
     permissions: