NestJS Code Audit

Inspect the current user's NestJS project and return one consolidated report of verified code problems and evidence-backed risks. Audit only; do not modify the target project.

Pre-execution conflict guard

Before editing files or running any state-changing command, reconcile active instructions. Read-only inspection may continue.

Prerequisites

Confirm root, scope, instructions, Git state, installed versions/dependencies, and safe checks. Preserve user changes. Load semantic-review.md for the requested semantic lanes; sibling skills are optional deeper guidance, not installation prerequisites. Read other active skills only when their decisions overlap.

Primary ownership

This skill owns read-only quality evidence, finding deduplication, severity, and report assembly. When installed and relevant, coordinate with:

• nestjs-architecture-principles: module, dependency, data, and transaction boundaries.
• nestjs-oop-design-patterns: object responsibilities, invariants, and patterns.
• nestjs-features-performance: lifecycle, API/security, testing, runtime, and performance.
• nestjs-professional-software-engineering: implementation and verification.
• nestjs-feature-audit: branch-specific roadmap gate and feature reporting.
• nestjs-git-commit-pr-message: authorized Git publication and CI follow-up.

These are decision boundaries, not required dependencies. Retain domain ownership when handing work to another workflow.

Conflict test

Resolve incompatible findings, unsafe checks, or missing evidence using explicit user intent, repository contracts, verified runtime constraints, then the narrowest owner. Keep one finding per root cause; unresolved claims belong in Needs verification. If an action crosses the audit boundary, stop before mutation. An audit alone never authorizes fixes; if the user explicitly requested both, finish the read-only audit first, then enter the authorized implementation phase without asking for the same approval again.

Invocation

Preferred portable invocation:

$nestjs-code-audit
$nestjs-code-audit full src/payments
$nestjs-code-audit static
$nestjs-code-audit security src/auth

Codex CLI/IDE custom-prompt alias, when installed:

/prompts:nestjs-audit
/prompts:nestjs-audit full src/payments

Codex does not provide arbitrary bare user-defined commands such as /Nestjs audit; keep the supported alias explicit.

Actions

Action	Coverage
full (default)	Safe static gates plus architecture, object design, runtime, security, testing, and delivery review
static	Syntax, TypeScript, lint, configuration, and directly related toolchain failures
architecture	Modules, dependencies, data/write ownership, transactions, events, ports, and service boundaries
design	Responsibilities, invariants, coupling, abstractions, patterns, and refactoring risks
runtime	Nest lifecycle, API/errors, reliability, performance evidence, health, shutdown, and delivery
security	Input, identity/access, tenant isolation, secrets, output, abuse controls, and security tests
tests	Test-layer choice, missing boundary coverage, flaky lifecycle risks, and safely runnable checks

An optional repository-relative scope follows the action. If the first argument is not a recognized action, treat all arguments as the scope/focus and use full. For focused actions, load only the relevant lanes in the bundled semantic reference, plus any available specialist guidance needed for a cross-lane blocker. Report only the requested scope.

Audit workflow

1. Establish eligibility and scope

1. Resolve the current working directory and optional user scope without escaping the repository root.
2. Read AGENTS.md and other repository instructions, package.json, lockfiles, nest-cli.json, TypeScript and lint configuration, bootstrap files, module files, tests, and deployment manifests that affect the scope.
3. Verify that @nestjs/core is declared or that the repository is clearly a NestJS workspace. If not, stop and report that this audit is not applicable.
4. Record the current branch and dirty state. Do not alter or discard existing changes.
5. State a one-sentence baseline of the observed architecture. Do not infer Clean Architecture, DDD, CQRS, or microservices from folder names.

2. Collect deterministic evidence

Use the bundled collector from this skill's directory:

node scripts/collect-quality-evidence.mjs --root "$PWD" --run

Add --scope <relative-path> when the user requested a narrower audit. The collector:

• reads manifests and source files without changing them;
• identifies the package manager and available quality scripts;
• runs only allow-listed, non-fixing ESLint and tsc --noEmit commands when --run is present;
• never installs dependencies, runs builds, updates snapshots, writes coverage, or invokes arbitrary package scripts;
• returns JSON containing command results and heuristic review candidates.

If dependencies are missing or a command is unsafe, unavailable, timed out, or outside scope, record it as not run. Do not reinterpret a missing check as a pass. Never run lint --fix, format/write commands, migrations, deployment commands, live integration tests, or tests that may reach shared infrastructure during this audit.

3. Review four evidence lanes

Toolchain correctness

• Report parser, TypeScript, and lint diagnostics exactly enough to locate the problem.
• Deduplicate cascaded compiler errors when they share one root cause.
• Separate command failure from a code finding, such as missing dependencies or broken configuration.

Architecture

Trace bootstrap entry points, module imports/exports, provider visibility, request/message paths, persistence ownership, transactions, events, and external adapters. Confirm cycles or boundary leaks from real imports and call paths. Do not report architectural preference as a defect.

Object design and maintainability

Inspect responsibilities, dependency clusters, invariant placement, repeated conditional variation, framework/vendor leakage, hidden service location, speculative abstractions, and risky refactor seams. File length or a regex signal alone is not a finding.

Runtime, security, and verification

Inspect lifecycle placement, validation, authentication/authorization, tenant/resource ownership, public error and response contracts, secrets/logging, query and resource bounds, timeouts/retries/idempotency, health/shutdown, test boundaries, and deployment evidence when present. Do not claim performance problems without measurements.

4. Verify and deduplicate findings

A confirmed finding needs:

• a stable ID: TOOL, ARCH, OOP, RUN, SEC, or TEST plus a number;
• severity: critical, high, medium, or low;
• primary owning skill;
• file and line evidence plus the relevant import, call path, diagnostic, or configuration;
• concrete impact, not only a rule name;
• the smallest safe remedy;
• a validation step that could prove the remedy.

Use critical only for a present security, data-loss, tenant-isolation, or severe availability risk. High requires likely incorrect behavior or a boundary flaw blocking a known change. Medium requires a credible maintainability, correctness, or operability cost. Low is a localized improvement with limited risk.

Move unverified regex signals, suspected dead code, possible performance issues, and checks blocked by missing dependencies to Needs verification. Do not inflate the report with style preferences or multiple findings for one root cause.

Required report

Return Markdown in this order:

1. Audit verdict: pass, pass with risks, or fail; audited scope; one-sentence baseline.
2. Quality gates: syntax/TypeScript, lint, tests if safely available, and audit coverage, each marked pass, fail, or not run with the exact command or reason.
3. Finding summary: counts by severity and owner.
4. Confirmed findings: ordered by severity and impact, using the evidence/remedy/validation contract above.
5. Needs verification: candidate, missing evidence, and smallest next check.
6. Healthy patterns: only notable controls actually verified in the repository.
7. Recommended order: a short, dependency-aware remediation sequence; implement only in a distinct phase if the user explicitly authorized those fixes.

If there are no confirmed problems, say so and list the checks that were not run. A clean lint result is not proof of sound architecture, security, runtime behavior, or test coverage.

Reference routing

Need	Load
Review architecture, objects, runtime, and healthy controls without sibling skills	semantic-review.md
Decide which checks may run without modifying the project	check-policy.md
Assign and deduplicate findings across the three domain skills	finding-ownership.md
Format the final audit consistently	report-template.md

---

Canonical source: skills/nestjs-code-audit/SKILL.md. This page is generated during the documentation build.