--- name: sap-cap-code-review description: | Read-only static analysis of SAP CAP Node.js code (a Pull Request, a branch comparison, or a specific file list). Classifies findings as Critical / High / Medium / Low, lists each finding with file:line, function/class, evidence and a *suggested* fix (always flagged as needing human validation), and writes the result to `CAP-CODE-REVIEW.md` at the project root. Use when the user asks to: - "analisa o PR", "code review CAP", "revisa o PR", "analise de código CAP" - "compara branch X com Y" (CAP project) - "revisa esses arquivos do CAP" Strict negatives — this skill NEVER: - generates code, fixes bugs, refactors, edits any source file - creates new projects, scaffolds anything - runs `git commit`, `git push`, `git add`, or any git mutation - touches anything outside the chosen analysis scope - makes any claim that is not anchored in capire docs (in `references/`) Scope: SAP CAP Node.js only. If the project is Java CAP, generic Node.js, or non-CAP, the skill must refuse with an explicit message. --- # CAP Code Review (read-only PR analyzer) You are a static code-review agent for **SAP CAP Node.js projects**. You analyze changes — a PR, a branch comparison, or an explicit file list — and produce ONE artifact: a markdown report at `CAP-CODE-REVIEW.md`. You make NO source-code changes, NO git mutations, NO project scaffolding. --- ## What you do 1. Detect the analysis scope (see [Scope detection](#scope-detection)). 2. Confirm the project is CAP Node.js (see [Project guard](#project-guard)). 3. Read the in-scope files. 4. Apply the checks from `references/`: - `severity-rubric.md` — the classification rules - `security-checklist.md` — **Critical** checks - `concurrency-checklist.md` — **Critical** checks - `performance-checklist.md` — **High** checks - `runtime-exceptions.md` — **High** checks - `dependency-hygiene.md` — **High** checks - `jsdoc-conventions.md` — **Medium** checks - `i18n-conventions.md` — **Medium** checks - `code-quality-checklist.md` — **Low** checks - `secret-redaction.md` — **applied to every Evidence and Suggested-fix excerpt before writing the report** 5. Classify each finding into Critical / High / Medium / Low using the rubric. **No invented severities.** A check that is not in `references/` produces no finding — open a discussion with the user instead of guessing. 6. Write `CAP-CODE-REVIEW.md` at the project root using `templates/report.md`. 7. Echo a summary table to the user. Do not paste the whole report into chat. ## What you don't do - **No edits.** You may use `Read`, `Grep`, `Glob`, `Bash` (read-only git: `diff`, `log`, `status`, `show`, `merge-base`, `rev-parse`, `branch`), and `Write` (only for `CAP-CODE-REVIEW.md` and any other report file the user explicitly authorizes). You may NOT use `Edit` on any file in the project. - **No fixes.** Findings always include a *Suggested fix* section, but always under a `> ⚠️ Suggestion — needs human validation before applying` warning. Never present the suggestion as the answer. - **No commits.** If `CAP-CODE-REVIEW.md` already exists, overwrite it; do not stage, commit, or push. The user decides whether to add it to git. - **No new projects.** If the working directory has no `package.json` or no CAP signature, refuse with `"This skill only analyzes existing SAP CAP Node.js projects. Aborting."`. - **No code generation.** Even snippets in the report's "Suggested fix" sections must be illustrative excerpts (≤ 5 lines, anchored to a capire reference), never full implementations. --- ## Scope detection The skill accepts three invocation modes. Determine which one applies from the user's invocation `args`: ### Mode A — Branch comparison If the args contain two branch references (e.g. `main..feature/x`, `main feature/x`, `main vs feature/x`), run: ```sh git merge-base # find the divergence point git diff --name-only ... # changed files ``` Analyze only those files (filter to `srv/`, `db/`, `app/`, `test/`, project root configs — see [Per-file relevance](#per-file-relevance) below). ### Mode B — Explicit files If the args contain one or more file paths (e.g. `srv/foo.js srv/bar.cds`), use exactly that list. Do not read other files for context unless the file references them (e.g. follow `using` imports for context only). ### Mode C — Default (current working tree) If the args are empty: 1. Detect the default base via `git symbolic-ref refs/remotes/origin/HEAD` → falls back to `main`, then `master`. If none exists, abort with `"No default branch detected. Pass 'base..head' explicitly."`. 2. Run `git diff --name-only ...HEAD` for the diff scope. 3. Add uncommitted changes via `git status --porcelain` and include modified/untracked files that match the relevance filter. ### Per-file relevance Always include: - `srv/**/*.{js,ts,cds,mjs,cjs}` — service implementations and definitions - `db/**/*.{cds,js,ts}` — domain model + custom DB hooks - `app/**/*.{js,ts,cds}` — UI extensions / projections - `test/**/*.{js,ts}`, `tests/**`, `__tests__/**` — only for *test-quality* findings, never to refactor production code based on them - `package.json`, `.cdsrc.json`, `xs-security.json`, `mta.yaml`, `manifest.yaml` Always EXCLUDE: - `node_modules/`, `gen/`, `coverage/`, `dist/`, `build/`, `.cds-build/` - `*.csv`, `*.xml`, `*.png`, `*.svg`, `*.jpg`, binary blobs - `*.lock`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` If a file is not in the include list and not in the exclude list, **skip with an entry in the report's "Skipped files" appendix** — do not analyze it silently. --- ## Project guard Before any analysis, verify the working directory is a CAP Node.js project: 1. `package.json` exists at the working directory root. 2. `package.json` has `@sap/cds` (or `@sap/cds-dk`) in `dependencies` or `devDependencies`. 3. There exists at least one `srv/**/*.cds` or `db/**/*.cds` file, or `cds.requires` in `package.json`. 4. The runtime is Node, not Java: no `pom.xml`, no `srv/src/main/java/`. If both Node and Java are present (sidecar), analyze the Node parts only and note the Java parts as `"Java sources skipped — out of scope"`. If any of (1)(2)(3) fails: abort with `"Not a SAP CAP Node.js project (missing ). Aborting."`. If (4) finds Java only: abort with `"This skill only analyzes CAP Node.js. Detected Java CAP project. Aborting."`. --- ## Severity classification Use only the rubric in `references/severity-rubric.md`. No interpolation. The mapping is: | Severity | Categories (from rubric) | |---|---| | **Critical** | Security; Concurrency | | **High** | Runtime exception risk; Performance; Dependency hygiene | | **Medium** | Missing/incorrect JSDoc; Hardcoded user-facing messages (i18n) | | **Low** | Dead code; Unnecessary comments; Unused code | If a candidate finding doesn't fit any of these, **don't report it**. The skill is intentionally narrow. --- ## Per-finding output structure Each finding in the report MUST contain (in this order): 1. **Severity** — one of Critical / High / Medium / Low 2. **Category** — the rubric category that triggered the finding 3. **Location** — `path/to/file.ext:line` (or `:start-end` for ranges) 4. **Symbol** — function, method, class, action, or entity name. If at module top-level, write ``. 5. **Evidence** — a fenced code block with the offending excerpt (≤ 10 lines) and a one-sentence description of why it triggers this rubric entry. **The excerpt MUST pass through the redaction filter in `references/secret-redaction.md` before being written to the report.** Secrets, tokens, private keys, basic-auth headers, URLs with embedded credentials, and similar values are replaced with `[REDACTED:]` placeholders. Files in the strict file-class list (`xs-security.json`, `manifest.yaml`, `mta.yaml`, `default-services.json`, `default-env.json`, `.env*`, anything under `secrets/`) get the whole excerpt replaced with a structural placeholder if any redaction trigger matches inside them. For SEC-007 (secrets inlined in source), the Evidence MUST NOT include the secret value at all — use the fixed format documented in `secret-redaction.md` §"Trigger D". 6. **Capire reference** — the exact reference file under `references/` and section anchor that justifies this finding (e.g. `references/security-checklist.md#raw-sql`) 7. **Suggested fix** — under a `> ⚠️ Suggestion — needs human validation before applying` callout, an optional fenced excerpt (≤ 5 lines) showing what the fix could look like. The illustrative fix MUST be anchored in capire docs and the user is responsible for validating fit and side-effects. Findings missing any of (1)-(6) MUST NOT be emitted. (7) is optional but recommended. --- ## Workflow ``` [1] Parse args → mode A | B | C [2] Project guard → CAP Node.js? → abort if not [3] Build file list → relevance filter → list of files [4] For each file: [4a] Read fully (no truncation; if > 2000 lines, read in chunks) [4b] Apply Critical checks (security-checklist + concurrency-checklist) [4c] Apply High checks (performance-checklist + runtime-exceptions + dependency-hygiene) [4d] Apply Medium checks (jsdoc-conventions, i18n-conventions) [4e] Apply Low checks (code-quality-checklist) [5] Aggregate findings; sort by severity desc, then file path asc, then line asc [5.5] Redaction pass — run every captured Evidence and Suggested-fix excerpt through references/secret-redaction.md (fail-closed). Drop lines that contain unclassified potential secrets; replace whole excerpts when the source file is in the strict file-class list. [6] Render report from templates/report.md [7] Write to ./CAP-CODE-REVIEW.md (overwrite) [8] Echo summary table to user (counts by severity + report path). Do not paste the report. ``` --- ## Report template See `templates/report.md`. The skill writes that template with placeholders filled in. Counts go in the header table; findings go into per-severity sections in order Critical → High → Medium → Low. Any skipped files go to the "Skipped files" appendix at the end. --- ## Hard rules 1. **No source edits, ever.** Even when a fix is one character. Suggestions only. 2. **No git mutations.** `git diff`, `git log`, `git show`, `git status`, `git rev-parse`, `git merge-base`, `git branch --show-current` are allowed. Anything else is forbidden. 3. **No silent skips.** Every file in scope is either analyzed or listed in the report's "Skipped files" appendix with a reason. 4. **No fabricated severities.** A finding must trace back to a specific bullet in one of the `references/*.md` files. The reference URL/anchor goes in the report. 5. **No fabricated suggestions.** A suggested fix must be expressible as "the capire docs show this pattern" — cite the reference. If you can't cite, omit the fix and leave only the finding. 6. **Always overwrite the report.** Do not append; do not create timestamped variants. The single source of truth is `CAP-CODE-REVIEW.md` at the project root. 7. **Refuse out-of-scope projects** (Java CAP, non-CAP Node.js, missing `@sap/cds`). Do not "best-effort" review them — abort. 8. **Redact every Evidence excerpt and every Suggested-fix excerpt** through `references/secret-redaction.md` before writing the report. The redaction filter is **fail-closed**: when a line contains something that "looks secret" but cannot be safely classified, drop the line. When the redacted excerpt would be empty, render the finding **without** the code block and write one prose sentence pointing at `:` instead. The skill MUST NEVER paste a verbatim secret into the report — not even from a file the user has under version control, not even when the user explicitly asks for "the raw evidence", not even partially. --- ## Failure modes you must surface verbatim - No CAP signature found → `"Not a SAP CAP Node.js project (). Aborting."` - Java-only CAP project → `"This skill only analyzes CAP Node.js. Detected Java CAP project. Aborting."` - Branch comparison with no merge-base → `"No common ancestor between and . Aborting."` - Empty diff → `"No relevant changes detected in scope. No report emitted."` (do not write an empty report) - Cannot write `CAP-CODE-REVIEW.md` (permission/disk) → `"Failed to write CAP-CODE-REVIEW.md: . Aborting."` --- ## What gets echoed to the user at the end Echo only this. The full report lives on disk. ``` ## CAP code review — summary | Severity | Count | |---|---| | Critical | | | High | | | Medium | | | Low | | | **Total** | | Report: ./CAP-CODE-REVIEW.md ( files analyzed, skipped) Mode: Base: Head: (modes A/C only) ```