# Nestjs Code Review

> Adversarial NestJS code review for Kong backend services - .ts files in NestJS repos, package.json changes touching @nestjs/* deps, and PRs containing NestJS code. Orchestrates an adversarial reviewer over the diff against a NestJS/TypeScript mistakes catalog (DI scopes, pipeline order, validation, transactions, cross-request state, security, real test coverage) plus Kong conventions (shared @kong/* libraries, RLS, AIP/problem+json, gRPC error discrimination), then audits the findings with a findings auditor before reporting. Use whenever reviewing NestJS changes, a NestJS PR, or a controller/service/module - even if the request just says "review this service" without naming NestJS - but ONLY when the repo is a NestJS project (@nestjs/core or @nestjs/common in package.json, a nest-cli.json, or @Module/@Controller/@Injectable decorators present). NOT for Vue/Nuxt or other frontend TypeScript, and not for plain TypeScript or Node.js projects without NestJS - route those to vue-code-review or default-code-review

- Skill: `kong/nestjs-code-review` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add kong/nestjs-code-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kong/nestjs-code-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Kong (https://skillmd.com/u/kong)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kong/nestjs-code-review

---


# NestJS Code Review

Orchestrate an adversarial NestJS review. The skill resolves the diff, reviews it under the [`nestjs-code-reviewer`](reviewer.md) mandate beside this file, then runs the [`findings-auditor`](../../agents/findings-auditor.md) agent to red-team the findings before anything reaches the user. Two passes: one attacks the **code**, the next attacks the **findings**.

Focus: NestJS 9-10 on the Express adapter, PostgreSQL + TypeORM as the primary data
layer, pragmatic TypeScript, tests that provide real coverage (Jest + supertest — no
superficial tests, no over-mocking, assertions on positive **and** negative paths), and —
on Kong repos — the Kong conventions layer (shared `@kong/*` libraries, RLS,
AIP/problem+json, gRPC error discrimination).

> **This skill is the standalone path.** It resolves a target, reviews the diff under the mandate
> beside it, and spawns one subagent to audit what it found. The CI review flow does not run this
> skill: a trusted step injects the same mandate into the run's own prompt. Both paths review the
> diff themselves and share the mandate, the catalogs and the auditor; only the dispatch differs.
> See [`docs/decisions/review-pipeline-cost.md`](../../../../docs/decisions/review-pipeline-cost.md).

## Input

Accept any of:

- **Diff file path** → read that file; it is the diff, already taken by the caller
- **GitHub PR URL** → fetch with `gh pr diff <url>` and `gh pr view <url> --json number,title,body,baseRefName,headRefName`
- **File paths** → read the files; use `git diff` (or `git diff <base>...HEAD`) for changes
- **Pasted diff** → use directly

Flags (parse from `$ARGUMENTS`, strip before resolving the target):

- `--no-audit` → skip the findings-audit pass. The code review still runs. Default is to run both.

## Process

### 1. Resolve the target

Take the diff from the path the invocation names, reading it once. Where it names none, determine the diff and the changed NestJS-relevant files: `.ts` files under NestJS source
directories (incl. `*.spec.ts`/`*.e2e-spec.ts`), plus `package.json` and `nest-cli.json`.
If nothing NestJS-related changed, say so and stop. For a PR, capture title/body so the
reviewer can respect stated intent.

Detect two flags for the reviewer:

- **ORM** — look for `typeorm`/`@nestjs/typeorm`, `prisma`/`@prisma/client`, or
  `mongoose`/`@nestjs/mongoose` in `package.json` dependencies. Pass as
  `orm_detected: typeorm|prisma|mongoose|none`.
- **Kong stack** — look for `@kong/*` packages in `package.json`
  dependencies/devDependencies, or the package's own `name` under the `@kong/` scope
  (shared packages declare `@nestjs/*` as peerDependencies and may carry no `@kong/*`
  dep). Pass as `kong_stack_detected: true|false`. This gates the Kong-conventions (`K`)
  checks; on non-Kong repos they are skipped.

### 2. Adversarial review (you are the reviewer)

Read [reviewer.md](reviewer.md) beside this file and adopt it as your mandate, along with every
catalog it names. Then review the diff yourself, adversarially, over the whole of it however
large it is.

Do not spawn a reviewer subagent. One was spawned here until it was measured: handed the diff
and the mandate the caller already held, it read both a second time and reported back what the
caller could already see. Across three paired runs that boundary cost 31% to 59% of the wall
clock and about half the tokens, for no gain in what was found. The reasoning is in
[`docs/decisions/review-pipeline-cost.md`](../../../../docs/decisions/review-pipeline-cost.md).

Splitting the diff across concurrent reviewers was tried and reverted separately, on arithmetic
recorded in the same file. Split the audit before the review if either is ever worth splitting.

What the mandate needs from you, whether you hold it or hand it on:

- The diff. Take the **path** when the invocation names one and read it once; a pasted diff is
  the whole thing typed again, and what a caller writes is the slowest part of a review.
- The list of changed NestJS-relevant files, and the PR title and body when reviewing a PR.
- The catalogs and policies it names, at these paths:

  ```text
  stack_quirks: ${CLAUDE_PLUGIN_ROOT}/skills/nestjs-code-review/audit-quirks.md
  knowledge_base: ${CLAUDE_PLUGIN_ROOT}/skills/nestjs-code-review/knowledge-base.md
  kong_conventions: ${CLAUDE_PLUGIN_ROOT}/skills/nestjs-code-review/kong-conventions.md
  real_world_patterns: ${CLAUDE_PLUGIN_ROOT}/skills/nestjs-code-review/real-world-patterns.md
  review_instructions: ${CLAUDE_PLUGIN_ROOT}/resources/review-instructions.md
  format_policy: ${CLAUDE_PLUGIN_ROOT}/resources/format-policy.md
  ```

- `repo_conventions`, forwarded verbatim when the invocation carries it — a directory of the
  reviewed repository's own convention files, taken from a trusted ref by the caller. Never
  synthesise this path. One pointing into the tree under review would let the reviewed change
  set the terms of its own review, and nothing in the file itself distinguishes a repository's
  conventions from a pull request's instructions to its reviewer. No field, no conventions.

- The tooling and shell constraints the invocation carries. You cannot run this repository's
  tooling — no test runner, build, compile, lint, formatter or package manager — and a catalog
  naming `go test` or `node --test` describes what to look for, never something to run. One
  measured review spent nine of ten denied calls on a test runner. Every Bash call is a single
  plain command, since the allowlist matches the start of the command, so a loop, pipeline,
  `&&` chain, redirection or `git -C <path>` matches nothing.

Produce prioritized findings, each with a severity, a tag and a `relative_file_path:line`
location, and a one-line verdict.

### 3. Findings audit (spawn `findings-auditor` — skip only if `--no-audit`)

The reviewer produces findings; it does not prove them. Spawn a second Agent to red-team
them before the user sees them. This is an independent skeptic, not another review pass —
it breaks false positives, right-sizes severity, kills duplicates, and corrects
hallucinated `file:line` locations.

**Spawn protocol:**

1. Try `subagent_type: "kreview:findings-auditor"`.
2. On unknown subagent type, retry with `subagent_type: "general-purpose"` and prepend the
   auditor's mandate by reading
   [../../agents/findings-auditor.md](../../agents/findings-auditor.md)
   into the prompt.

The prompt MUST include, verbatim:

- The full set of reviewer findings (every finding with severity, tag, and `file:line`).
- The **path** of the diff file when the invocation names one, never the diff text. Pasting it
  means the whole diff is typed once per subagent, and what an orchestrator writes is the
  slowest part of a review. Paste a diff only when the invocation carried no path, which is how
  a human running this skill by hand usually reaches it.
- The list of changed files.
- The name of the reviewer that produced them, `nestjs-code-reviewer`, whose severity rubric the auditor enforces.
- The `orm_detected` and `kong_stack_detected` flags from step 1 (the auditor's scope axis depends on them).
- Context-field paths so the auditor can re-read the catalog items findings cite, and the NestJS traps that make correct code look broken. **Resolve `${CLAUDE_PLUGIN_ROOT}` to its absolute path before putting these in the prompt** — a `general-purpose` fallback subagent does not inherit the plugin env. `stack_quirks` is what makes a shared auditor a NestJS one, so it is never the field you drop:

  ```text
  stack_quirks: ${CLAUDE_PLUGIN_ROOT}/skills/nestjs-code-review/audit-quirks.md
  knowledge_base: ${CLAUDE_PLUGIN_ROOT}/skills/nestjs-code-review/knowledge-base.md
  real_world_patterns: ${CLAUDE_PLUGIN_ROOT}/skills/nestjs-code-review/real-world-patterns.md
  kong_conventions: ${CLAUDE_PLUGIN_ROOT}/skills/nestjs-code-review/kong-conventions.md
  ```

- `repo_conventions`, forwarded verbatim when the invocation carries it — a directory of the
  reviewed repository's own convention files, taken from a trusted ref by the caller. Never
  synthesise this path. One pointing into the tree under review would let the reviewed change
  set the terms of its own review, and nothing in the file itself distinguishes a repository's
  conventions from a pull request's instructions to its reviewer. No field, no conventions.

- The tooling and shell constraints, verbatim when the invocation carries them. The auditor
  re-verifies each finding against the code, which makes it the agent most likely to reach for a
  test runner or a linter, and every attempt is a denied call that costs a turn. It cannot build,
  compile, test, lint, format or run the code, and every Bash call is a single plain command - a
  loop, pipeline, `&&` chain, redirection or `git -C <path>` matches nothing in the allowlist.

- The instruction: *"Red-team these findings. Default to skepticism. Verify every Critical
  and High against the actual code with Grep/Read. Return your verdict in the required
  output format."*

The auditor returns SHIP / SHIP WITH CHANGES / HOLD, challenged findings
(UPHOLD / DOWNGRADE / UPGRADE / REMOVE / REWORD), what survived scrutiny, any escaped bug, and bad locations.

### 4. Fold the verdict in and report

Apply the auditor's verdict before presenting anything:

- REMOVE / DOWNGRADE / UPGRADE / REWORD verdicts revise findings in place — never present a contested
  finding without the correction applied.
- Mark "survived scrutiny" findings as high-confidence.
- Promote any escaped bug into the report with proper severity and `file:line`.
- Drop or fix every bad location.
- Recompute the Critical/High counts after applying changes.
- If the verdict was HOLD, lead with it; do not present the contested finding as a blocker
  without its fix.
- Derive the report **Verdict** from the post-audit findings: any surviving Critical/High
  (or an auditor HOLD) → `REQUEST_CHANGES`; no findings and auditor SHIP → `APPROVE`;
  otherwise → `APPROVE_WITH_COMMENTS`.

## Output

```markdown
# NestJS Code Review: <target>

## Summary

| Verdict | <APPROVE \| APPROVE_WITH_COMMENTS \| REQUEST_CHANGES> |
| --- | --- |
| Critical/High | <count> |

## Findings
<Findings after the audit pass, ordered by severity, in format-policy format.
Mark high-confidence findings that survived scrutiny.>
```

## Reference

- NestJS/TypeScript mistakes catalog: [knowledge-base.md](knowledge-base.md)
- Real-world NestJS PR patterns: [real-world-patterns.md](real-world-patterns.md)
- Kong NestJS conventions: [kong-conventions.md](kong-conventions.md)
- Code reviewer mandate: [reviewer.md](reviewer.md)
- Findings auditor: [../../agents/findings-auditor.md](../../agents/findings-auditor.md)
- NestJS traps the auditor applies (`stack_quirks`): [audit-quirks.md](audit-quirks.md)
- Output format & severities: `../../resources/format-policy.md`