@freshworks/shiftleft-tools 1.1.8

package/templates/skills/setup-mutation-tests/SKILL-node.md

@@ -0,0 +1,408 @@
+# Setup Mutation Tests — Node.js / Express
+
+Add Stryker mutation testing to a Node.js project using an **inspect-first, minimal-scope** approach.
+
+## CRITICAL: Mutate only meaningful files
+
+Stryker is **orders of magnitude slower** than unit tests. A broad `mutate: ['src/**/*.js']` on a medium service can take **30–60+ minutes** and produce noise from files that have no real logic to test.
+
+**You MUST:**
+
+1. **Never** use `src/**` or `src/**/*.js` as the mutate scope
+2. **Include only** files with branching business logic (conditions, loops, transformations, validation)
+3. **Exclude** thin wrappers, entry points, config, models, and route wiring
+4. **Audit every folder** under `src/` before writing `stryker.config.js` — do not copy-paste from another repo
+5. **Confirm file count** with the user before saving config (see Phase 2)
+
+**Two speed levers (use both):**
+
+| Lever | What | Effect |
+|-------|------|--------|
+| **Narrow `mutate` scope** | Only actions, services, serializers, middlewares (+ selective helpers) | Full scan: minutes not hours |
+| **`since` mode** | `yarn mutation-tests` — only files changed vs `origin/master` | Local runs: often under 1 min |
+
+Reserve `yarn mutation-tests:full` for Jenkins / pre-merge only.
+
+## When to Use
+
+Invoke when the user says:
+- "setup mutation tests", "add mutation testing", "add Stryker"
+- "measure test quality", "check unit test quality"
+- "my unit tests pass but I want to know if they're strong"
+
+---
+
+## What is Mutation Testing?
+
+Stryker makes small automated changes (mutations) to your source code — flipping `>` to `>=`, removing return values, negating conditions — then runs your Mocha/Jest tests against each mutation.
+
+- **Mutant killed** — your tests caught the change (good)
+- **Mutant survived** — your tests didn't catch it (weak assertion)
+
+Target: 80% high threshold, 60% low threshold. `break: 0` means CI never hard-fails on score alone — only on test failures.
+
+---
+
+## Why `since` mode matters
+
+Stryker on a large Node codebase can take 10-20 minutes. Running it on every local change makes it unusable. The solution:
+
+- **Local / `yarn mutation-tests`** — `since` mode: only mutates files changed vs `origin/master`. Takes 30 seconds if you changed 2 files. If no scoped files changed, exits immediately.
+- **Jenkins / `yarn mutation-tests:full`** — full mode: all scoped files, `--force` flag. Runs the complete scan. Slow but complete.
+
+This is the critical difference from Java PIT — Stryker needs this two-mode approach to be practical.
+
+---
+
+## Phase 1: Inspect
+
+### 1.1 Check if Stryker already exists
+
+```bash
+cat package.json | grep -i stryker
+ls stryker.config.js stryker.config.ts 2>/dev/null
+```
+
+- Found → check the existing configuration, skip to Phase 4 (Verify)
+- Not found → continue
+
+### 1.2 Discover the test runner
+
+```bash
+cat package.json | grep -E '"test"|"mocha"|"jest"'
+```
+
+This determines which Stryker runner plugin to install (`@stryker-mutator/mocha-runner` vs `@stryker-mutator/jest-runner`).
+
+### 1.3 Discover the source directory structure
+
+```bash
+ls src/
+find src -maxdepth 1 -type d | sort
+```
+
+Map what you find to these categories:
+
+| Folder | Include? | Reason |
+|--------|----------|--------|
+| `src/actions/` | **YES** | Core business logic |
+| `src/services/` | **YES** | Core business logic |
+| `src/serializers/` | **YES** if transforms data | Skip if pass-through only |
+| `src/middlewares/` | **YES** if validates/auth logic | Skip if one-line `next()` |
+| `src/validators/` | **YES** | Validation rules |
+| `src/helpers/` | **FILE BY FILE** | Often mostly external SDK wrappers — see 1.4 |
+| `src/controllers/` | **NO** | HTTP wiring — covered by Postman |
+| `src/routes/` | **NO** | Route registration only |
+| `src/models/` | **NO** | Sequelize/ORM definitions — no logic to kill |
+| `src/config/` | **NO** | Static config |
+| `src/constants/` | **NO** | Constants |
+| `src/migrations/` | **NO** | DB migrations |
+| `src/seeders/` | **NO** | Seed data |
+| `src/clients/` | **NO** | HTTP client wrappers |
+| `src/index.js`, `src/app.js` | **NO** | Bootstrap |
+
+### 1.3b Count files before proceeding
+
+After deciding folders, **count how many files** will be mutated:
+
+```bash
+# Example — adjust globs to match your planned mutate array
+find src/actions src/services src/middlewares -name '*.js' 2>/dev/null | wc -l
+```
+
+| Files in scope | Action |
+|----------------|--------|
+| **under 40** | Good — proceed |
+| **40–80** | Review exclusions — drop pass-through serializers/helpers |
+| **over 80** | **Stop** — scope is too wide; exclude more helpers/models or split by package |
+
+Show the count to the user in Phase 3. If over 80, ask which folders to drop before continuing.
+
+### 1.4 Inspect helpers (if `src/helpers/` exists)
+
+```bash
+ls src/helpers/
+```
+
+For each helper file, check if it only wraps an external service with no branching:
+
+```bash
+# Read the file — look for: does it only call an external SDK/API with no if/else?
+cat src/helpers/aws.js       # Wraps AWS SDK → EXCLUDE
+cat src/helpers/freshid.js   # Wraps FreshID API → EXCLUDE
+cat src/helpers/utils.js     # Has if/else logic → INCLUDE
+```
+
+Files to typically EXCLUDE from helpers (they only wrap external services):
+- `aws.js`, `chargebee.js`, `freshid.js`, `launchdarkly.js`
+- `emailNotifications.js`, `analytics.js`, `observability.js`
+- `mcp-gateway.js`, `mcp-gateway-util.js`
+- `mp-listings.js`, `mp-apps.js`
+- `constants.js`, `config.js`
+- `helpers/validator/schema/**` (JSON schema files, not logic)
+
+Files to typically INCLUDE: anything with **branching or computation** (`if`, `switch`, `for`, `?.`, `??`, `Math.`, string transforms).
+
+**Per-file inclusion test** — run for each candidate helper:
+
+```bash
+# Files with few branches are usually not worth mutating
+for f in src/helpers/*.js; do
+  branches=$(grep -cE '\b(if|else|switch|for|while|\?\?|\?\.)\b' "$f" 2>/dev/null || echo 0)
+  lines=$(wc -l < "$f" | tr -d ' ')
+  echo "$f  branches=$branches  lines=$lines"
+done
+```
+
+| Signal | Decision |
+|--------|----------|
+| Only calls external SDK, no `if`/`switch` | **EXCLUDE** |
+| `branches=0` and file is under 30 lines | **EXCLUDE** |
+| `branches >= 1` or non-trivial transform | **INCLUDE** |
+
+Read the file if unsure — **never include by folder glob alone** when `src/helpers/` is mixed.
+
+### 1.5 Find unit test location
+
+```bash
+ls test/unit/ test/ 2>/dev/null | head -20
+cat package.json | grep -A3 '"test"'
+```
+
+Note the test file pattern (e.g., `test/unit/**/*.test.js`) and any setup files (e.g., `test/unit/setup.js`).
+
+---
+
+## Phase 2: Reason
+
+Build the **smallest** `mutate` array that still covers real business logic.
+
+**Rules:**
+
+- One glob **per included folder** — only folders that exist in this repo
+- Add `!` exclusions for every external-wrapper file under included folders (especially `helpers/`)
+- **Do not** add `src/helpers/**/*.js` unless you listed specific included files — prefer listing individual helpers or a tight subfolder
+- **Never** add `src/controllers/**`, `src/routes/**`, `src/models/**`, `src/config/**`
+
+**mutate array example (freshapps-style layout):**
+
+```javascript
+mutate: [
+  'src/actions/**/*.js',
+  'src/serializers/**/*.js',
+  'src/middlewares/**/*.js',
+  'src/helpers/workflow.js',        // only if it has branching logic
+  '!src/helpers/aws.js',
+  '!src/helpers/freshid.js',
+  // ... every external wrapper explicitly excluded
+],
+```
+
+**Anti-patterns (reject if user or template suggests these):**
+
+```javascript
+// WRONG — too broad, will run forever
+mutate: ['src/**/*.js']
+
+// WRONG — helpers folder is mixed
+mutate: ['src/helpers/**/*.js']
+
+// WRONG — controllers have no unit-testable logic
+mutate: ['src/controllers/**/*.js']
+```
+
+**Stryker runner** — `mocha` or `jest` based on 1.2.
+
+**Two scripts to add to package.json**:
+- `"mutation-tests"` — `since` mode (fast, local dev): `./postman/scripts/runners/run-mutation-tests.sh`
+- `"mutation-tests:full"` — full mode (Jenkins CI): `./postman/scripts/runners/run-mutation-tests.sh --full`
+
+---
+
+## Phase 3: Confirm
+
+Show the user a summary before writing anything:
+
+```
+Mutation scope audit:
+  INCLUDED (32 files):
+    src/actions/      12 files
+    src/serializers/   8 files
+    src/middlewares/   5 files
+    src/helpers/       7 files (workflow.js, billing.js, …)
+  EXCLUDED (not meaningful to mutate):
+    src/controllers/  14 files — HTTP wiring
+    src/helpers/      11 files — aws.js, freshid.js, … (SDK wrappers)
+    src/models/        9 files — ORM definitions
+
+Estimated full-scan time: ~5–8 min (32 files) — NOT hours
+
+Stryker config:
+  mutate: [listed paths only — no src/**]
+  coverageAnalysis: perTest
+  incremental: true
+  Local: yarn mutation-tests (since mode — changed files only)
+  CI:    yarn mutation-tests:full (full scope above)
+
+Proceed? [Y/n]
+```
+
+If estimated file count is over 80, **do not proceed** until scope is reduced.
+
+Wait for confirmation before writing any files.
+
+---
+
+## Phase 4: Execute
+
+### 4.1 Install dependencies
+
+```bash
+yarn add --dev @stryker-mutator/core @stryker-mutator/mocha-runner
+# or for Jest:
+yarn add --dev @stryker-mutator/core @stryker-mutator/jest-runner
+```
+
+### 4.2 Create stryker.config.js
+
+```javascript
+'use strict';
+
+/** @type {import('@stryker-mutator/api/core').PartialStrykerOptions} */
+module.exports = {
+  packageManager: 'yarn',
+  testRunner: 'mocha',  // or 'jest'
+  reporters: ['html', 'json', 'clear-text', 'progress'],
+  htmlReporter: {
+    fileName: 'coverage/mutation/index.html'
+  },
+  jsonReporter: {
+    fileName: 'coverage/mutation/mutation-report.json'
+  },
+  mutate: [
+    // ONLY folders/files from Phase 1 audit — never src/**
+    'src/actions/**/*.js',
+    'src/serializers/**/*.js',
+    'src/middlewares/**/*.js',
+    // Add individual helpers OR exclude the whole folder — avoid helpers/**
+    // 'src/helpers/workflow.js',
+    '!src/controllers/**',
+    '!src/routes/**',
+    '!src/models/**',
+    '!src/config/**',
+    '!src/helpers/validator/schema/**/*.js',
+    '!src/helpers/aws.js',
+    '!src/helpers/chargebee.js',
+    '!src/helpers/freshid.js',
+    '!src/helpers/launchdarkly.js',
+    '!src/helpers/emailNotifications.js',
+    '!src/helpers/analytics.js',
+    '!src/helpers/observability.js',
+    '!src/helpers/constants.js',
+    '!src/helpers/config.js'
+  ],
+  coverageAnalysis: 'perTest',  // Fastest analysis mode
+  concurrency: 4,
+  incremental: true,            // Reuse previous results — speeds up repeated runs
+  incrementalFile: 'coverage/mutation/stryker-incremental.json',
+  ignorePatterns: ['postman/**', 'coverage/**'],
+  mochaOpts: {
+    // REPLACE with actual test file pattern from Phase 1
+    files: 'test/unit/**/*.test.js',
+    require: ['test/unit/setup.js'],  // Remove if no setup file
+    timeout: 10000
+  },
+  thresholds: {
+    high: 80,
+    low: 60,
+    break: 0  // Never hard-fail CI on score alone — only on test failures
+  },
+  tempDirName: 'coverage/mutation/.stryker-tmp'
+};
+```
+
+### 4.3 Add scripts to package.json
+
+```json
+{
+  "scripts": {
+    "mutation-tests": "./postman/scripts/runners/run-mutation-tests.sh",
+    "mutation-tests:full": "./postman/scripts/runners/run-mutation-tests.sh --full"
+  }
+}
+```
+
+### 4.4 Stage run-mutation-tests.sh from the shiftleft-tools package
+
+`runners/run-mutation-tests.sh` and `lib/cleanup-stryker.sh` are library scripts —
+they're staged from the installed package, not copied by hand. Run:
+
+```bash
+shiftleft stage-scripts
+```
+
+This pulls the current versions into `postman/scripts/` (gitignored, made
+executable) and is re-run automatically by `shiftleft test`. The `package.json`
+`mutation-tests` scripts above invoke `./postman/scripts/runners/run-mutation-tests.sh`,
+which will be present after staging.
+
+### 4.5 Add .gitignore entries
+
+Add to `.gitignore`:
+```
+coverage/mutation/.stryker-tmp/
+.stryker-incremental.json
+stryker.log
+```
+
+---
+
+## Phase 5: Verify
+
+Run in `since` mode first (only changed files — fast):
+
+```bash
+yarn mutation-tests
+```
+
+Expected output:
+- If no scoped files changed vs origin/master: "No scoped source files changed vs origin/master; skipping Stryker." (exit 0, this is correct)
+- If files changed: shows mutation score for changed files
+
+Run full mode to verify the full scope works:
+
+```bash
+yarn mutation-tests:full
+```
+
+Report is generated at `coverage/mutation/index.html`.
+
+### Report results to the user
+
+After the run completes:
+1. Report the mutation score — e.g. "74% of mutants killed (high: 80%, low: 60%)"
+2. Identify surviving mutants — list which classes have weak coverage
+3. Suggest fixes for top surviving mutants:
+
+| Surviving Mutant Type | Likely Cause | Fix |
+|---|---|---|
+| Negated condition | Test doesn't check the false branch | Add test for falsy case |
+| Removed method call | Side effect not asserted | Use `sinon.spy` and assert `.calledWith()` |
+| String literal changed | Hardcoded string not asserted | Assert on the actual return value |
+| Removed block | Error branch not tested | Add test that triggers the error path |
+
+---
+
+## Verification Checklist
+
+- [ ] `@stryker-mutator/core` installed in devDependencies
+- [ ] `stryker.config.js` `mutate` array has **no** `src/**` or `src/helpers/**` blanket globs
+- [ ] Mutate scope is **under 80 files** (count with `find` before saving)
+- [ ] Controllers, routes, models, config, migrations **excluded**
+- [ ] External-service wrapper files excluded from `mutate`
+- [ ] `coverageAnalysis: 'perTest'` and `incremental: true` set
+- [ ] `mutation-tests` and `mutation-tests:full` scripts added to package.json
+- [ ] `run-mutation-tests.sh` copied and executable
+- [ ] `yarn mutation-tests` works (since mode)
+- [ ] `yarn mutation-tests:full` works (full mode)
+- [ ] Score reported to user

package/templates/skills/setup-mutation-tests/SKILL.md

@@ -0,0 +1,9 @@
+# Setup Mutation Tests Skill
+
+## Detect Project Type First
+
+Before doing anything, detect the stack:
+
+1. `pom.xml` in project root → **Java Spring Boot** → read `SKILL-java.md` in this folder and follow it completely
+2. `package.json` (no `pom.xml`) → **Node.js** → read `SKILL-node.md` in this folder and follow it completely (mutate **only meaningful business-logic files** — never `src/**`)
+3. If unsure → ask the user: "Is this a Java or Node.js project?"