Output

Source: src/cli/formatters/console-reporter.ts, src/cli/formatters/json-reporter.ts

Renders the finished scan in the requested format. Humans want the visual console report, while CI pipelines and tooling integrations want the machine formats, --score and --json.

Input is the scan result:

interface DiagnoseResult {
  score: Score
  diagnostics: Diagnostic[]
  project: ProjectInfo
  summary: DiagnoseSummary
  ruleErrors: RuleErrorInfo[]
  schema?: SerializedSchemaGraph
  elapsedMs: number
}
 
interface DiagnoseSummary {
  total: number
  errors: number
  warnings: number
  info: number
  byCategory: Record<Category, number>
}

The visual report includes:

• ASCII art NestJS bird (happy, neutral, or sad based on score)
• Score display: 82 / 100 ★★★★☆ Good
• Score bar visualization
• Summary: error, warning and info counts, file count, elapsed time
• Project info: name, NestJS version, ORM, module count
• Diagnostics grouped by rule and help text, sorted by severity
• With --verbose: file paths and line numbers per diagnostic

The help text is part of the grouping key, so one rule can print several groups when it offers a different fix each time. security/no-vulnerable-nestjs-packages names a different upgrade target per advisory, and each gets its own group.

Color coding:

• Green: score >= 75
• Yellow: score >= 50
• Red: score < 50

Full DiagnoseResult as pretty-printed JSON to stdout:

npx nestjs-doctor . --json

Useful for piping into other tools:

npx nestjs-doctor . --json | jq '.diagnostics[] | select(.severity == "error")'

The numeric score and nothing else:

npx nestjs-doctor . --score
# Output: 82

Useful for CI scripts that need to capture the score:

SCORE=$(npx nestjs-doctor . --score)

The document the HTML report embeds, as versioned JSON: score, findings, summary, module graph, providers, endpoints, code graph, schema, rule examples, source text, and the slices behind Sharing a report. Written to nestjs-doctor-report.json beside the scanned project, or wherever --output points:

npx nestjs-doctor . --format report-json
npx nestjs-doctor . --format report-json --output report.json --sources touched

The HTML report is rendered from the same artifact, so the two always agree. --sources controls how much source text it carries: all (default), touched (only files with findings), or none. --timings embeds boot timings in the graph the same way it does for --report.

The codeGraph field holds one node per declared method and one edge per call site, encoded. The endpoint graph nests a subtree under each route, so one method that five routes reach appears in five subtrees.

Only the report artifact carries the code graph, so the console report, --json and --score do not build it. See Code graph.

A slice of the same result for someone else to read, limited to the sections you name. Written to nestjs-doctor-shared.json beside the scanned project:

npx nestjs-doctor . --share-sections score,findings:security

It runs alongside whichever format produced the report, rather than replacing it, and the notice naming the file goes to stderr. See Sharing a report.

In monorepo mode, the console report shows the combined score and diagnostics first, exactly as it does for a single project. A per-project breakdown table follows:

  Project     Score    Files   Errors  Warnings  Info
  api         85/100   42      1       3         0
  admin       78/100   31      2       2         1
  shared      95/100   18      0       1         0

A finding two sub-projects both report is counted once, against the first of them. The error, warning and info columns count only what the combined result took, so they add up to the totals above. Each score is recalculated from that same kept set.

In an interactive terminal this breakdown renders as the score screen's two-pane browser instead of a table. See The menu.

Generates a single HTML file with an interactive report:

npx nestjs-doctor . --report

The report has up to six tabs:

• Summary: health score overview with a category breakdown.
• Findings: source-level diagnostics with a code viewer and fix examples.
• Modules Graph: clustered module diagram with cycles in red and a per-module detail panel. See Module graph.
• Endpoints: badged Beta, traced HTTP routes per controller with their dependency chains. Controllers and handlers behind a project wrapper decorator, meaning a custom decorator composing @Controller() or @Get(), are resolved and traced too.
• Relational Schema: entity-relationship diagram of the database models.
• Lab: custom rule playground for writing and testing your own rules.

Endpoints and Relational Schema stay hidden until there is data, so a project with no controllers and no ORM entities sees four.

The file is written to nestjs-doctor-report.html in the project root and auto-opened in the default browser.

Pass --output to write it somewhere else, so a scan leaves the scanned repository untouched:

npx nestjs-doctor . --report --output /tmp/health.html

A relative path resolves against the working directory, and missing parent directories are created.

--timings overlays real construction times from a captured boot onto that graph. See Boot trace.

Two gates produce 1: the --min-score threshold, and the severity gate set by --blocking. The severity gate defaults per output mode, so the same findings exit 1 under the console report and 0 under --format json. See Exit codes for the defaults.

Both gates run after output, so the report is always emitted, whatever the exit code.