The deterministic NestJS devtool that catches AI mistakes.

nestjs-doctor is a free, open-source static analysis tool for NestJS that catches AI mistakes deterministically. It reads every @Module(), provider, endpoint and ORM entity from source and reports findings across security, correctness, architecture, performance and schema with a 0-100 score. No LLM at scan time, so code from Copilot, Cursor or Claude Code scores the same on your laptop and in CI.

Run it with npx, as a pre-commit hook, as a GitHub Action, in VS Code, or from a coding-agent skill. The HTML report draws the module graph, endpoint traces, an ER diagram for Prisma, TypeORM, Drizzle or MikroORM, and boot timings from one real start. Monorepos work.

Website → · 简体中文 →

Run this at your project root:

npx nestjs-doctor@latest .

A clean scan prints the score and nothing else. That is the expected result on a project the rules already agree with, and --report still draws the module graph, the traced endpoints and the schema diagram.

Add --verbose for file paths and line numbers.

To rescan after every change your coding agent makes, install the skill:

npx nestjs-doctor@latest --init

Build nestjs-doctor-report.html:

npx nestjs-doctor@latest . --report

Writes to the project root, or wherever --output names. One file: score summary, findings with a code viewer, and an interactive module graph. Traced HTTP endpoints, the schema ER diagram, and a rule playground get their own tabs. Module graph docs →

The report's share button, and --share-sections on the CLI, write a JSON slice of a scan: pick the score, a findings category, the endpoints, the schema, or the module graph. Sharing docs →

Add a few lines to main.ts, boot once, and --timings <path> gives the report a Boot trace tab. Every class sits on one absolute timeline, with a hover card per bar and graph nodes that say what each module cost. Boot trace docs →

Write .github/workflows/nestjs-doctor.yml:

npx nestjs-doctor@latest ci install

The action reviews every pull request and reports only what the change introduced, not the existing backlog. It posts a sticky summary comment, inline review comments on the changed lines, and a commit status with the score.

It never fails a check until you ask it to, unless the scanned directory holds no TypeScript files, which exits 2. Set blocking or min-score when ready. CI docs →

Install the agent skill:

npx nestjs-doctor@latest --init

Installs three skills: nestjs-doctor for scanning after a change, nestjs-boot-trace for a slow start, and nestjs-doctor-create-rule for conventions of your own. The first runs without being asked, after the agent writes Nest code. Works with Claude Code, Cursor, Codex, OpenCode, Windsurf, Gemini CLI, and more. Agent docs →

Optional. Drop a nestjs-doctor.config.json at your project root to turn rules or categories off, set a score floor, or point at a custom rules directory:

{
  "minScore": 80,
  "rules": {
    "performance/no-sync-io": false,
    "architecture/no-manual-instantiation": {
      "excludeClasses": ["Logger", "PinoLogger"]
    }
  },
  "categories": { "performance": false }
}

The same shape works as .nestjs-doctor.json, or as a "nestjs-doctor" key in package.json.

Configuration → · Custom rule configuration →

Every finding carries a file and a rule id you can suppress or configure, plus a line unless it reports against a schema entity.

Suppress a single finding inline:

// nestjs-doctor-ignore-next-line architecture/no-orm-in-controllers
constructor(private readonly prisma: PrismaService) {}

• VS Code: NestJS Doctor surfaces the same rules as you type. Docs →
• Any other editor: npx nestjs-doctor-lsp --stdio speaks LSP, so Neovim, Helix, and Emacs get the same rules. Docs →
• Other CI: GitLab Code Quality, SARIF for any code-scanning backend, or a markdown body to post yourself. Docs →
• Node API: diagnose() plus an incremental API for editors and long-running processes. Docs →
• Monorepos: detected from nest-cli.json, pnpm workspaces, package.json workspaces, Nx, or Lerna. Docs →

nestjs-doctor 是一个开源（MIT）的 NestJS 静态分析工具，专门用来发现 AI 生成代码中的问题，结果可复现。它直接分析源码中的每个 @Module()、provider、HTTP 接口和 ORM 实体，从安全、正确性、架构、性能、数据库 schema 五个维度打分（0–100），并逐条列出问题。

• 扫描时不启动应用，也不调用任何 LLM，同一个 commit 在本地和 CI 的得分一致。代码不会上传，只上报规则报错和匿名的使用数据（见 Telemetry）。

• 无需配置和注册：

  npx nestjs-doctor@latest .

  国内网络可走 npmmirror 镜像：npx --registry=https://registry.npmmirror.com nestjs-doctor@latest .

• 加 --report 生成 HTML 报告：模块依赖图（高亮循环依赖）、每个接口的调用链，以及 Prisma、TypeORM、Drizzle、MikroORM 的 ER 图。在 main.ts 里加几行代码、实际启动一次应用，再加 --timings <path>，报告会多出一个启动耗时页（文档）。

• 还可以接入 pre-commit 钩子、GitHub Action（只评论 PR 新引入的问题）、VS Code 扩展，或作为 AI 编程助手的 skill 使用。支持 monorepo。

文档（英文）：https://www.nestjs.doctor/docs?from=readme-zh

The CLI reports rule errors and anonymous run data to help us catch bugs and prioritize work.

We collect:

• Environment: CLI version, platform, Node version, and how it ran (npx, script, the installed skill, a coding agent, or CI)
• Project shape: file count, framework, ORM, Nest version (NO file contents)
• Rules fired: rule ids and counts only (e.g. security/no-eval) (NO code or specific findings)
• Rules that threw during the scan
• Commands run: one command_completed event when --init or ci install finishes, with command (init or ci_install) and from (flag or menu)

To opt out, run: npx nestjs-doctor@latest --no-telemetry. Details →

Issues and pull requests welcome. pnpm check && pnpm typecheck && pnpm test before opening one.

MIT © RoloBits