Diagnose and fix your NestJS code in one command.

40 built-in rules across security, performance, correctness, and architecture. Outputs a 0-100 score with actionable diagnostics. Zero config. Monorepo support. Catches the anti-patterns that AI-generated code introduce (slop code).

npx nestjs-doctor@latest .

With file paths and line numbers:

npx nestjs-doctor@latest . --verbose

npx nestjs-doctor@latest . --report

Self-contained HTML file with four sections: score summary, source-level diagnostics with code viewer, interactive module graph, and a custom rule playground. Opens in your browser.

Install NestJS Doctor from the VS Code Marketplace. Requires nestjs-doctor as a dev dependency — the extension's LSP server loads it from your workspace.

npm install -D nestjs-doctor

Same 40 rules as the CLI, surfaced as inline diagnostics in the editor and in the Problems panel. Files are scanned on open and on save with a configurable debounce.

Use NestJS Doctor: Scan Project from the command palette to trigger a full scan manually.

Pin it as a devDependency:

npm install -D nestjs-doctor

Use --min-score to gate on a minimum health score:

npx nestjs-doctor . --min-score 75

Or wire it into package.json:

{
  "scripts": {
    "health": "nestjs-doctor . --min-score 75"
  }
}

Exit codes: 1 if the score is below threshold, 2 for bad input.

Usage: nestjs-doctor [directory] [options]

  --verbose       Show file paths and line numbers per diagnostic
  --score         Output only the numeric score (for CI)
  --json          JSON output (for tooling)
  --report        Generate an interactive HTML report (--graph also works)
  --min-score <n> Minimum passing score (0-100). Exits with code 1 if below threshold
  --config <p>    Path to config file
  --init          Set up the /nestjs-doctor skill for AI coding agents
  -h, --help      Show help

Ships with skills for popular AI coding agents. Run --init to auto-detect installed agents and install the nestjs-doctor skill for each one:

npm install -D nestjs-doctor
npx nestjs-doctor --init

A project-level fallback is always written to .agents/nestjs-doctor/. Commit it so every contributor gets the skill automatically.

--init installs two skills per agent:

Optional. Create nestjs-doctor.config.json in your project root:

{
  "minScore": 75,
  "ignore": {
    "rules": ["architecture/no-orm-in-services"],
    "files": ["src/generated/**"]
  },
  "rules": {
    "architecture/no-barrel-export-internals": false
  },
  "categories": {
    "performance": false
  }
}

Also works as a "nestjs-doctor" key in package.json.

Extend the built-in rule set with project-specific checks. Only .ts files are supported.

Each .ts file in the custom rules directory must export an object with a meta descriptor and a check function:

import type { RuleContext } from "nestjs-doctor";

export const noTodoComments = {
  meta: {
    id: "no-todo-comments",
    category: "correctness",        // "security" | "performance" | "correctness" | "architecture"
    severity: "warning",            // "error" | "warning" | "info"
    description: "TODO comments should be resolved before merging",
    help: "Replace the TODO with an implementation or open an issue.",
    // scope: "file",              // optional — "file" (default) or "project"
  },
  check(context: RuleContext) {
    const text = context.sourceFile.getFullText();
    const regex = /\/\/\s*TODO/gi;
    let match: RegExpExecArray | null;
    while ((match = regex.exec(text)) !== null) {
      const pos = context.sourceFile.getLineAndColumnAtPos(match.index);
      context.report({
        message: "Unresolved TODO comment",
        file: context.filePath,
        line: pos.line,
      });
    }
  },
};

Rule IDs are automatically prefixed with custom/ (e.g. no-todo-comments becomes custom/no-todo-comments).

Set customRulesDir in your config file:

{
  "customRulesDir": "./rules"
}

Invalid rules produce warnings but never crash the scan. Common issues — missing check function, invalid category/severity, syntax errors — are surfaced in CLI output so you can fix them without blocking the rest of the analysis.

Auto-detected from nest-cli.json. When "monorepo": true is set, each sub-project is scanned independently and results are merged.

{
  "monorepo": true,
  "projects": {
    "api": { "root": "apps/api" },
    "admin": { "root": "apps/admin" },
    "shared": { "root": "libs/shared" }
  }
}

Output includes a combined score and a per-project breakdown.

Weighted by severity and category, normalized by file count:

import { diagnose, diagnoseMonorepo } from "nestjs-doctor";

const result = await diagnose("./my-nestjs-app");
result.score;       // { value: 82, label: "Good" }
result.diagnostics; // Diagnostic[]
result.summary;     // { total, errors, warnings, info, byCategory }

const mono = await diagnoseMonorepo("./my-monorepo");
mono.isMonorepo;    // true
mono.subProjects;   // [{ name: "api", result }, ...]
mono.combined;      // Merged DiagnoseResult