nestjs-doctor 0.5.0 → 0.6.0

package/README.md

@@ -66,6 +66,113 @@ Use `NestJS Doctor: Scan Project` from the command palette to trigger a full sca
 
 ---
 
+## GitHub Action
+
+Reviews every pull request and reports **only what the change introduced**, not
+your existing backlog. Posts a sticky summary comment, inline review comments on
+the changed lines, and a commit status with the score.
+
+```yaml
+# .github/workflows/nestjs-doctor.yml
+name: NestJS Doctor
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+  statuses: write
+
+jobs:
+  doctor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # required for `scope: changed`
+      - uses: RoloBits/nestjs-doctor@v1
+```
+
+`fetch-depth: 0` matters. `scope: changed` compares against the **merge base**
+of your branch and its target, which a shallow checkout can't resolve — the
+action falls back to the base branch tip, or, if it can't reach that either, to
+reporting every finding in the changed files. It says which happened in the
+comment.
+
+### Inputs
+
+| Input | Default | Description |
+|-------|---------|-------------|
+| `directory` | `.` | Project directory to scan |
+| `scope` | `changed` | `changed` (only what the pull request introduced), `files` (everything in the changed files), `lines` (only the changed lines), `full` (the whole project) |
+| `blocking` | `none` | Severity that fails the workflow: `none`, `warning`, `error` |
+| `min-score` | — | Fail when the project's score drops below this |
+| `config` | — | Path to a config file |
+| `comment` | `true` | Sticky pull request summary comment |
+| `review-comments` | `true` | Inline review comments on changed lines |
+| `commit-status` | `true` | Commit status with the score |
+| `sarif` | `false` | Also write a SARIF report |
+| `sarif-file` | `nestjs-doctor.sarif` | Where the SARIF report goes |
+| `silence-missing-baseline-warning` | `false` | Hide the degraded-scope warning |
+| `github-token` | `${{ github.token }}` | Token used to comment and set the status |
+| `node-version` | `22` | Node.js version |
+| `version` | `latest` | nestjs-doctor version to run |
+
+### Failing the build
+
+Out of the box the action **never fails** — it comments and sets a status, and
+you decide what to do about it. Enforcement is opt-in through two independent
+gates, and either one failing fails the run.
+
+```yaml
+      - uses: RoloBits/nestjs-doctor@v1
+        with:
+          blocking: error # any error the change introduced fails the run
+          min-score: 80 # …and so does a project score below 80
+```
+
+`blocking` gates on the findings **actually reported**, so with the default
+`scope: changed` it fires only on what the pull request introduced — your
+existing backlog cannot fail somebody else's pull request. `none` (the default)
+never fails, `warning` fails on any error or warning, `error` on errors only.
+
+`min-score` gates on the **whole project**, always, whatever the scope. That is
+deliberate — narrowing a report must not make a codebase look healthier than it
+is — but it does mean a high enough threshold can fail a pull request for debt
+it did not create. Use `blocking` on its own to gate purely on the change.
+
+### Outputs
+
+`score`, `label`, `total-issues`, `fixed-issues`, `error-count`,
+`warning-count`, `affected-files`, `report-file`, `sarif-file`.
+
+Pushes to the default branch always scan the whole project and never fail the
+run — they are a health snapshot, surfaced through the job summary and the
+commit status, so `main` doesn't go red on pre-existing findings.
+
+### Code scanning
+
+Turn on `sarif` to send findings to the repository's Security tab:
+
+```yaml
+      - uses: RoloBits/nestjs-doctor@v1
+        id: doctor
+        with:
+          scope: full
+          sarif: "true"
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always() && steps.doctor.outputs.sarif-file != ''
+        with:
+          sarif_file: ${{ steps.doctor.outputs.sarif-file }}
+```
+
+Add `security-events: write` to the job's `permissions`.
+
+---
+
 ## CI
 
 Pin it as a devDependency:
@@ -90,19 +197,84 @@ Or wire it into `package.json`:
 }
 ```
 
-Exit codes: `1` if the score is below threshold, `2` for bad input.
+Exit codes: `1` if a gate fails, `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
+  --verbose             Show file paths and line numbers per diagnostic
+  --score               Output only the numeric score (for CI)
+  --json                JSON output (for tooling)
+  --format <f>          console (default), json, sarif, gitlab, markdown, github
+  --output <path>       Write the formatted output to a file instead of stdout
+  --json-compact        Emit JSON-based formats without indentation
+  --scope <s>           full (default), files, lines, changed
+  --base <ref>          Git ref to compare against (auto-detected)
+  --staged              Scope to the staged files, for pre-commit hooks
+  --changed-files-from  Path to a newline-separated list of changed files
+  --blocking <level>    Severity that fails the run: none, warning, error
+  --min-score <n>       Minimum passing score (0-100)
+  --report              Generate an interactive HTML report (--graph also works)
+  --config <p>          Path to config file
+  --list-rules          List every built-in rule and exit
+  --init                Set up the /nestjs-doctor skill for AI coding agents
+  -h, --help            Show help
+```
+
+### Scoping to a change
+
+The whole project is always analysed — cross-file rules like
+`no-circular-module-deps` and `no-unused-providers` need it — so `--scope` only
+narrows what gets **reported**.
+
+| Scope | Reports |
+|-------|---------|
+| `full` | Every finding in the project (the default) |
+| `files` | Findings in files the change touched |
+| `lines` | Findings on the lines the change touched |
+| `changed` | Findings the change introduced, measured against the base revision |
+
+```bash
+# What did this branch introduce?
+npx nestjs-doctor . --scope changed --base origin/main
+
+# Pre-commit hook: only what you are about to commit
+npx nestjs-doctor . --staged --blocking error
+```
+
+`changed` scans the base revision in a temporary git worktree and subtracts the
+findings that were already there. Findings are matched on rule, file, message,
+and source text rather than line number, so unrelated edits above a finding
+don't make it look new. If the base can't be reached the scan degrades to
+`files` and warns rather than reporting a delta it never measured.
+
+**The score always reflects the whole project**, whatever the scope — narrowing
+the report can't make a codebase look healthier than it is. `--min-score` gates
+on that project score; `--blocking` gates on the reported findings.
+
+### Blocking
+
+| Level | Fails the run when |
+|-------|--------------------|
+| `none` | Never — advisory only |
+| `warning` | Any error or warning is reported |
+| `error` | Any error is reported |
+
+The default preserves long-standing behaviour: `error` for the console report,
+`none` for `--json` and `--score`, which historically only failed on
+`--min-score`. Pass `--blocking` explicitly to make both paths behave the same.
+
+### Other CI systems
+
+```bash
+# GitLab Code Quality widget
+npx nestjs-doctor . --format gitlab --output gl-code-quality-report.json
+
+# SARIF, for any code-scanning backend
+npx nestjs-doctor . --format sarif --output nestjs-doctor.sarif
+
+# A markdown body to post as a merge request comment
+npx nestjs-doctor . --format markdown --output comment.md
 ```
 
 ---

package/dist/api/index.d.mts

@@ -313,6 +313,30 @@ interface EndpointGraph {
   endpoints: EndpointNode[];
 }
 //#endregion
+//#region src/common/scope.d.ts
+/**
+ * How much of a scan gets reported: everything, the changed files, the changed
+ * lines, or what the change introduced. Every mode analyses the whole project.
+ */
+type ScopeMode = "full" | "files" | "lines" | "changed";
+declare const SCOPE_MODES: ScopeMode[];
+declare function isScopeMode(value: string): value is ScopeMode;
+/** Scope metadata attached to a result so consumers can see what was reported. */
+interface ScopeInfo {
+  /** Present in `changed` mode: whether the base revision could be scanned. */
+  baselineAvailable?: boolean;
+  baseRef?: string;
+  /** Files the scope narrowed to, not the change's total file count. */
+  changedFiles?: number;
+  /** Files the change touched before filtering, when the caller knows it. */
+  changedFilesTotal?: number;
+  /** Set when the requested mode could not be honoured. */
+  degradedFrom?: ScopeMode;
+  /** Present in `changed` mode: findings the change resolved. */
+  fixed?: number;
+  mode: ScopeMode;
+}
+//#endregion
 //#region src/common/result.d.ts
 interface Score {
   label: string;
@@ -344,6 +368,8 @@ interface DiagnoseResult {
   project: ProjectInfo;
   ruleErrors: RuleErrorInfo[];
   schema?: SerializedSchemaGraph;
+  /** What `diagnostics` and `summary` cover. Absent when nothing was narrowed. */
+  scope?: ScopeInfo;
   score: Score;
   summary: DiagnoseSummary;
 }
@@ -372,18 +398,6 @@ declare class ValidationError extends NestjsDoctorError {
   constructor(message: string);
 }
 //#endregion
-//#region src/engine/graph/endpoint-graph.d.ts
-declare function buildEndpointGraph(project: Project, files: string[], providers: Map<string, ProviderInfo>): EndpointGraph;
-/**
- * Layer 2: traces method-level call chains for a specific endpoint.
- * Returns the full recursive call tree through injected dependencies.
- */
-declare function traceEndpointCalls(endpoint: EndpointNode, providers: Map<string, ProviderInfo>, project: Project): MethodCallNode[];
-declare function updateEndpointGraphForFile(graph: EndpointGraph, project: Project, filePath: string, providers: Map<string, ProviderInfo>): void;
-//#endregion
-//#region src/engine/rules/index.d.ts
-declare function getRules(): AnyRule[];
-//#endregion
 //#region src/engine/config/scan-config.d.ts
 interface ScanConfig {
   combinedRules: AnyRule[];
@@ -400,6 +414,132 @@ interface MonorepoInfo {
   projects: Map<string, string>;
 }
 //#endregion
+//#region src/engine/git.d.ts
+/** A contiguous run of lines on the new side of a diff hunk. */
+interface LineRange {
+  end: number;
+  start: number;
+}
+interface GitRepo {
+  /** Scanned directory relative to {@link root}, posix, `""` at the root. */
+  prefix: string;
+  /** Absolute path of the repository root, as git reports it. */
+  root: string;
+  /** Absolute path of the directory being scanned, as the caller gave it. */
+  targetPath: string;
+}
+/** Resolves the repository that contains `targetPath`, or `null` if there is none. */
+declare function findGitRepo(targetPath: string): GitRepo | null;
+/**
+ * Picks the ref to compare against: explicit, then `GITHUB_BASE_REF`, then the
+ * remote's default branch, then conventional names. `null` if none resolve.
+ */
+declare function resolveBaseRef(repo: GitRepo, explicit?: string): string | null;
+/** Files added, modified, or renamed between the merge base of `base` and HEAD. */
+declare function getChangedFiles(repo: GitRepo, base: string): string[] | null;
+/** Files staged in the index — the set a pre-commit hook should look at. */
+declare function getStagedFiles(repo: GitRepo): string[] | null;
+/** New-side line ranges introduced between the merge base of `base` and HEAD. */
+declare function getChangedLineRanges(repo: GitRepo, base: string): Map<string, LineRange[]> | null;
+interface BaseCheckout {
+  /** Removes the temporary worktree. Safe to call more than once. */
+  cleanup(): void;
+  /** Absolute path mirroring the scanned directory at the base revision. */
+  targetPath: string;
+}
+/**
+ * Checks the base revision out into a detached worktree under the OS temp
+ * directory. `null` when the base is unreachable.
+ */
+declare function checkoutBase(repo: GitRepo, base: string): BaseCheckout | null;
+//#endregion
+//#region src/engine/scope.d.ts
+interface ScopeOptions {
+  /** Git ref to compare against. Auto-detected when omitted. */
+  base?: string;
+  /** Path to a newline-separated list of changed files (CI hand-off). */
+  changedFilesFrom?: string;
+  mode: ScopeMode;
+  /** Compare against the index instead of a ref. */
+  staged?: boolean;
+  targetPath: string;
+}
+interface ResolvedScope {
+  baseRef: string | null;
+  /** Absolute paths of the changed files, or `null` in `full` mode. */
+  files: Set<string> | null;
+  lineRanges: Map<string, LineRange[]> | null;
+  /** The mode actually in force — may be a degraded `requestedMode`. */
+  mode: ScopeMode;
+  repo: GitRepo | null;
+  requestedMode: ScopeMode;
+  warnings: string[];
+}
+/**
+ * Works out which files, and lines, the reported set narrows to. Every failure
+ * path degrades to a wider scope with a warning.
+ */
+declare function resolveScope(options: ScopeOptions): ResolvedScope;
+/** Narrows a diagnostic set to the resolved scope. `changed` is applied by the caller. */
+declare function applyScope(diagnostics: Diagnostic[], scope: ResolvedScope): Diagnostic[];
+/** Builds the {@link ScopeInfo} recorded on a result. */
+declare function buildScopeInfo(scope: ResolvedScope, extra?: {
+  baselineAvailable?: boolean;
+  fixed?: number;
+}): ScopeInfo | undefined;
+//#endregion
+//#region src/engine/baseline.d.ts
+interface BaselineDelta {
+  /** False when the base could not be checked out — callers should degrade. */
+  available: boolean;
+  /** Findings the change resolved. */
+  fixed: number;
+  /** Findings with no counterpart at the base. */
+  introduced: Diagnostic[];
+  warnings: string[];
+}
+/**
+ * Which of HEAD's findings the change introduced. `available: false` when the
+ * base revision cannot be materialised.
+ */
+declare function computeBaselineDelta(headDiagnostics: Diagnostic[], scope: ResolvedScope, targetPath: string, scanConfig: ScanConfig, monorepo?: MonorepoInfo): Promise<BaselineDelta>;
+//#endregion
+//#region src/engine/fingerprint.d.ts
+/** Path of `filePath` relative to `targetPath`, always with forward slashes. */
+declare function toRelativePath(targetPath: string, filePath: string): string;
+/**
+ * Stable identity for a diagnostic: rule, path, message, and the anchor line's
+ * text. Excludes line and column, which shift under unrelated edits.
+ */
+declare function diagnosticIdentity(diagnostic: Diagnostic, targetPath: string): string;
+/** Hex digest of {@link diagnosticIdentity} — the form reporters emit. */
+declare function fingerprint(diagnostic: Diagnostic, targetPath: string): string;
+/** Counts identities, so repeated findings subtract one at a time. */
+declare function countIdentities(diagnostics: Diagnostic[], targetPath: string): Map<string, number>;
+interface DiagnosticDelta {
+  /** Findings present at the base that are gone at HEAD. */
+  fixed: number;
+  /** Findings at HEAD with no counterpart at the base. */
+  introduced: Diagnostic[];
+}
+/**
+ * Subtracts the base revision's findings from HEAD's. Each side's identities
+ * are computed against its own root.
+ */
+declare function diffDiagnostics(head: Diagnostic[], base: Diagnostic[], targetPath: string, baseTargetPath: string): DiagnosticDelta;
+//#endregion
+//#region src/engine/graph/endpoint-graph.d.ts
+declare function buildEndpointGraph(project: Project, files: string[], providers: Map<string, ProviderInfo>): EndpointGraph;
+/**
+ * Layer 2: traces method-level call chains for a specific endpoint.
+ * Returns the full recursive call tree through injected dependencies.
+ */
+declare function traceEndpointCalls(endpoint: EndpointNode, providers: Map<string, ProviderInfo>, project: Project): MethodCallNode[];
+declare function updateEndpointGraphForFile(graph: EndpointGraph, project: Project, filePath: string, providers: Map<string, ProviderInfo>): void;
+//#endregion
+//#region src/engine/rules/index.d.ts
+declare function getRules(): AnyRule[];
+//#endregion
 //#region src/engine/analysis-context.d.ts
 interface AnalysisContext {
   astProject: Project;
@@ -462,6 +602,11 @@ interface MonorepoEngineResult {
   moduleGraphs: Map<string, ModuleGraph>;
   result: MonorepoResult;
 }
+/**
+ * Replaces a result's diagnostics and recomputes the summary. The score is
+ * carried over: it measures the project, not the reported subset.
+ */
+declare function withScopedDiagnostics(result: DiagnoseResult, diagnostics: Diagnostic[], scope: ScopeInfo | undefined): DiagnoseResult;
 declare function buildResult(context: AnalysisContext, rawOutput: RawDiagnosticOutput, customRuleWarnings?: string[]): EngineResult;
 //#endregion
 //#region src/engine/scanner.d.ts
@@ -480,6 +625,107 @@ declare function autoScan(targetPath: string, options?: {
 //#region src/engine/schema/extract.d.ts
 declare function extractSchema(project: Project, files: string[], orm: string | null, targetPath: string): SchemaGraph;
 //#endregion
+//#region src/formatters/gitlab-report.d.ts
+interface CodeQualityIssue {
+  check_name: string;
+  description: string;
+  fingerprint: string;
+  location: {
+    lines: {
+      begin: number;
+    };
+    path: string;
+  };
+  severity: string;
+}
+/** Renders a result in the CodeClimate subset GitLab's Code Quality reads. */
+declare function buildCodeQualityReport(result: DiagnoseResult, targetPath: string): CodeQualityIssue[];
+//#endregion
+//#region src/formatters/markdown-report.d.ts
+/** Lets a CI job find and rewrite its own comment instead of stacking new ones. */
+declare const MARKDOWN_COMMENT_MARKER = "<!-- nestjs-doctor:summary -->";
+interface MarkdownReportOptions {
+  commitSha?: string;
+  monorepo?: MonorepoResult;
+  runUrl?: string;
+  scope?: ScopeInfo;
+  targetPath: string;
+  version: string;
+  warnings?: string[];
+}
+/** Renders a result as the markdown a CI job posts. */
+declare function buildMarkdownReport(result: DiagnoseResult, options: MarkdownReportOptions): string;
+//#endregion
+//#region src/formatters/sarif-report.d.ts
+type SarifLevel = "error" | "warning" | "note";
+interface SarifRule {
+  fullDescription: {
+    text: string;
+  };
+  help: {
+    markdown: string;
+    text: string;
+  };
+  helpUri: string;
+  id: string;
+  name: string;
+  properties: {
+    problem: {
+      severity: string;
+    };
+    tags: string[];
+  };
+  shortDescription: {
+    text: string;
+  };
+}
+interface SarifResult {
+  level: SarifLevel;
+  locations: {
+    physicalLocation: {
+      artifactLocation: {
+        uri: string;
+        uriBaseId: string;
+      };
+      region: {
+        startColumn?: number;
+        startLine: number;
+      };
+    };
+  }[];
+  message: {
+    text: string;
+  };
+  partialFingerprints: Record<string, string>;
+  ruleId: string;
+  ruleIndex: number;
+}
+interface SarifLog {
+  $schema: string;
+  runs: {
+    columnKind: string;
+    originalUriBaseIds: Record<string, {
+      uri: string;
+    }>;
+    results: SarifResult[];
+    tool: {
+      driver: {
+        informationUri: string;
+        name: string;
+        rules: SarifRule[];
+        semanticVersion: string;
+        version: string;
+      };
+    };
+  }[];
+  version: string;
+}
+/**
+ * Renders a result as a SARIF 2.1.0 log, with an explicit `partialFingerprints`
+ * on every result.
+ */
+declare function buildSarifLog(result: DiagnoseResult, targetPath: string, version: string): SarifLog;
+//#endregion
 //#region src/api/index.d.ts
 /**
  * Scans a single NestJS project and returns a health diagnostic result.
@@ -507,4 +753,4 @@ declare function diagnoseMonorepo(path: string, options?: {
   config?: string;
 }): Promise<MonorepoResult>;
 //#endregion
-export { type AnalysisContext, type AnyRule, type AutoScanResult, type BaseDiagnostic, type Category, type CodeDiagnostic, type CodeRuleContext, type CodeRuleContext as RuleContext, ConfigurationError, type DependencyType, type DiagnoseResult, type DiagnoseSummary, type Diagnostic, type EndpointGraph, type EndpointNode, type MethodCallNode, type MethodDependencyNode, type MonorepoResult, type NestjsDoctorConfig, NestjsDoctorError, type ProjectInfo, type ProjectRule, type ProjectRuleContext, type RawDiagnosticOutput, type Rule, type RuleErrorInfo, type RuleMeta, type ScanConfig, ScanError, type SchemaColumn, type SchemaDiagnostic, type SchemaEntity, type SchemaGraph, type SchemaRelation, type SchemaRule, type SchemaRuleContext, type Score, type SerializedSchemaGraph, type Severity, type SubProjectResult, ValidationError, autoScan, buildAnalysisContext, buildEndpointGraph, buildResult, checkAllFiles, checkFile, checkProject, checkSchema, diagnose, diagnoseMonorepo, extractSchema, getRules, isCodeDiagnostic, isSchemaDiagnostic, prepareAnalysis, resolveScanConfig, traceEndpointCalls, updateEndpointGraphForFile, updateFile, updateModuleGraphForFile, updateProvidersForFile };
+export { type AnalysisContext, type AnyRule, type AutoScanResult, type BaseCheckout, type BaseDiagnostic, type BaselineDelta, type Category, type CodeDiagnostic, type CodeQualityIssue, type CodeRuleContext, type CodeRuleContext as RuleContext, ConfigurationError, type DependencyType, type DiagnoseResult, type DiagnoseSummary, type Diagnostic, type DiagnosticDelta, type EndpointGraph, type EndpointNode, type GitRepo, type LineRange, MARKDOWN_COMMENT_MARKER, type MarkdownReportOptions, type MethodCallNode, type MethodDependencyNode, type MonorepoResult, type NestjsDoctorConfig, NestjsDoctorError, type ProjectInfo, type ProjectRule, type ProjectRuleContext, type RawDiagnosticOutput, type ResolvedScope, type Rule, type RuleErrorInfo, type RuleMeta, SCOPE_MODES, type SarifLog, type ScanConfig, ScanError, type SchemaColumn, type SchemaDiagnostic, type SchemaEntity, type SchemaGraph, type SchemaRelation, type SchemaRule, type SchemaRuleContext, type ScopeInfo, type ScopeMode, type ScopeOptions, type Score, type SerializedSchemaGraph, type Severity, type SubProjectResult, ValidationError, applyScope, autoScan, buildAnalysisContext, buildCodeQualityReport, buildEndpointGraph, buildMarkdownReport, buildResult, buildSarifLog, buildScopeInfo, checkAllFiles, checkFile, checkProject, checkSchema, checkoutBase, computeBaselineDelta, countIdentities, diagnose, diagnoseMonorepo, diagnosticIdentity, diffDiagnostics, extractSchema, findGitRepo, fingerprint, getChangedFiles, getChangedLineRanges, getRules, getStagedFiles, isCodeDiagnostic, isSchemaDiagnostic, isScopeMode, prepareAnalysis, resolveBaseRef, resolveScanConfig, resolveScope, toRelativePath, traceEndpointCalls, updateEndpointGraphForFile, updateFile, updateModuleGraphForFile, updateProvidersForFile, withScopedDiagnostics };