nestjs-doctor 0.4.17 → 0.4.19

package/README.md

@@ -19,7 +19,7 @@
 </p>
 
 <p align="center">
-  40 built-in rules across <b>security</b>, <b>performance</b>, <b>correctness</b>, and <b>architecture</b>. Outputs a <b>0-100 score</b> with actionable diagnostics. Zero config. Monorepo support. Catches the anti-patterns that AI-generated code introduce (slop code).
+  43 built-in rules across <b>security</b>, <b>performance</b>, <b>correctness</b>, <b>architecture</b>, and <b>schema</b>. Outputs a <b>0-100 score</b> with actionable diagnostics. Zero config. Monorepo support. Catches the anti-patterns that AI-generated code introduce (slop code).
 </p>
 
 ---
@@ -46,7 +46,7 @@ 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.
+Self-contained HTML file with five sections: score summary, source-level diagnostics with code viewer, interactive module graph, schema ER diagram, and a custom rule playground. Opens in your browser.
 
 ![Module Graph](https://nestjs.doctor/module-graph.png)
 
@@ -60,7 +60,7 @@ Install [NestJS Doctor](https://marketplace.visualstudio.com/items?itemName=rolo
 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.
+Same 43 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.
 
@@ -169,10 +169,22 @@ Also works as a `"nestjs-doctor"` key in `package.json`.
 | `minScore` | `number` | Minimum passing score (0-100). Exits with code 1 if below threshold |
 | `ignore.rules` | `string[]` | Rule IDs to suppress |
 | `ignore.files` | `string[]` | Glob patterns for files whose diagnostics are hidden |
-| `rules` | `Record<string, boolean>` | Enable/disable individual rules |
+| `rules` | `Record<string, RuleOverride \| boolean>` | Enable/disable individual rules, override severity, and pass rule-specific options |
 | `categories` | `Record<string, boolean>` | Enable/disable entire categories |
 | `customRulesDir` | `string` | Path to a directory containing custom rule files |
 
+Example rule-specific override:
+
+```json
+{
+  "rules": {
+    "architecture/no-manual-instantiation": {
+      "excludeClasses": ["Logger", "PinoLogger"]
+    }
+  }
+}
+```
+
 ---
 
 ## Custom Rules
@@ -189,7 +201,7 @@ import type { RuleContext } from "nestjs-doctor";
 export const noTodoComments = {
   meta: {
     id: "no-todo-comments",
-    category: "correctness",        // "security" | "performance" | "correctness" | "architecture"
+    category: "correctness",        // "security" | "performance" | "correctness" | "architecture" | "schema"
     severity: "warning",            // "error" | "warning" | "info"
     description: "TODO comments should be resolved before merging",
     help: "Replace the TODO with an implementation or open an issue.",
@@ -203,7 +215,7 @@ export const noTodoComments = {
       const pos = context.sourceFile.getLineAndColumnAtPos(match.index);
       context.report({
         message: "Unresolved TODO comment",
-        file: context.filePath,
+        filePath: context.filePath,
         line: pos.line,
       });
     }
@@ -248,6 +260,19 @@ Output includes a combined score and a per-project breakdown.
 
 ---
 
+## Schema Analysis
+
+Auto-detected from Prisma schema files (`schema.prisma`) or TypeORM entity decorators (`@Entity()`). When a schema is found, nestjs-doctor extracts entity-relationship data and:
+
+- Renders an **interactive ER diagram** in the Schema tab of the HTML report (sidebar entity tree + canvas diagram + problems panel)
+- Runs **3 schema-specific rules** covering primary keys, timestamps, and cascade configuration
+
+Supported ORMs: **Prisma**, **TypeORM**.
+
+See the [schema rules documentation](https://nestjs.doctor/docs/rules/schema) for the full rule list.
+
+---
+
 ## Scoring
 
 Weighted by severity and category, normalized by file count:
@@ -256,7 +281,8 @@ Weighted by severity and category, normalized by file count:
 |----------|--------|-|----------|------------|
 | error | 3.0 | | security | 1.5x |
 | warning | 1.5 | | correctness | 1.3x |
-| info | 0.5 | | architecture | 1.0x |
+| info | 0.5 | | schema | 1.1x |
+| | | | architecture | 1.0x |
 | | | | performance | 0.8x |
 
 | Score | Label |
@@ -287,7 +313,7 @@ mono.combined;      // Merged DiagnoseResult
 
 ---
 
-## Rules (40)
+## Rules (43)
 
 ### Security (9)
 
@@ -307,7 +333,7 @@ mono.combined;      // Merged DiagnoseResult
 
 | Rule | Severity | What it catches |
 |------|----------|-----------------|
-| `no-missing-injectable` | error | Provider in module missing `@Injectable()` |
+| `no-missing-injectable` | error | Provider with constructor deps missing `@Injectable()` |
 | `no-duplicate-routes` | error | Same method + path + version twice in a controller |
 | `no-missing-guard-method` | error | Guard class missing `canActivate()` |
 | `no-missing-pipe-method` | error | Pipe class missing `transform()` |
@@ -349,4 +375,10 @@ mono.combined;      // Merged DiagnoseResult
 | `no-unused-module-exports` | info | Module exports unused by importers |
 | `no-orphan-modules` | info | Module never imported by any other module |
 
+### Schema (3)
 
+| Rule | Severity | What it catches |
+|------|----------|-----------------|
+| `schema/require-primary-key` | error | Entity without a primary key column |
+| `schema/require-timestamps` | warning | Entity missing createdAt/updatedAt columns |
+| `schema/require-cascade-rule` | info | Relation missing explicit onDelete behavior |

package/dist/api/index.d.mts

@@ -1,6 +1,87 @@
 import { ClassDeclaration, Project, SourceFile } from "ts-morph";
 
-//#region src/engine/type-resolver.d.ts
+//#region src/common/config.d.ts
+interface RuleOverride {
+  enabled?: boolean;
+  excludeClasses?: string[];
+  options?: Record<string, unknown>;
+  severity?: Severity;
+}
+interface NestjsDoctorIgnoreConfig {
+  files?: string[];
+  rules?: string[];
+}
+interface NestjsDoctorConfig {
+  categories?: Partial<Record<Category, boolean>>;
+  customRulesDir?: string;
+  exclude?: string[];
+  ignore?: NestjsDoctorIgnoreConfig;
+  include?: string[];
+  minScore?: number;
+  rules?: Record<string, RuleOverride | boolean>;
+}
+//#endregion
+//#region src/common/schema.d.ts
+interface SchemaColumn {
+  defaultValue?: string;
+  hasIndex?: boolean;
+  isGenerated: boolean;
+  isNullable: boolean;
+  isPrimary: boolean;
+  isUnique: boolean;
+  name: string;
+  type: string;
+}
+interface SchemaRelation {
+  fromEntity: string;
+  isNullable: boolean;
+  onDelete?: string;
+  propertyName: string;
+  toEntity: string;
+  type: "one-to-one" | "one-to-many" | "many-to-one" | "many-to-many";
+}
+interface SchemaEntity {
+  columns: SchemaColumn[];
+  filePath: string;
+  indexes?: {
+    columns: string[];
+    isUnique: boolean;
+  }[];
+  name: string;
+  relations: SchemaRelation[];
+  tableName: string;
+}
+/**
+ * In-memory schema graph used during analysis.
+ * Entities are stored in a Map for O(1) lookup by name.
+ */
+interface SchemaGraph {
+  entities: Map<string, SchemaEntity>;
+  orm: string;
+  relations: SchemaRelation[];
+}
+/**
+ * JSON-safe version of SchemaGraph for HTML reports and API responses.
+ * Entities are flattened to an array since Maps are not serializable.
+ */
+interface SerializedSchemaGraph {
+  entities: SerializedSchemaEntity[];
+  orm: string;
+  relations: SchemaRelation[];
+}
+/**
+ * JSON-safe version of SchemaEntity (omits indexes since they are
+ * only needed during rule analysis, not in serialized output).
+ */
+interface SerializedSchemaEntity {
+  columns: SchemaColumn[];
+  filePath: string;
+  name: string;
+  relations: SchemaRelation[];
+  tableName: string;
+}
+//#endregion
+//#region src/engine/graph/type-resolver.d.ts
 interface ProviderInfo {
   classDeclaration: ClassDeclaration;
   dependencies: string[];
@@ -10,7 +91,7 @@ interface ProviderInfo {
 }
 declare function updateProvidersForFile(providers: Map<string, ProviderInfo>, project: Project, filePath: string): void;
 //#endregion
-//#region src/engine/module-graph.d.ts
+//#region src/engine/graph/module-graph.d.ts
 interface ModuleNode {
   classDeclaration: ClassDeclaration;
   controllers: string[];
@@ -27,47 +108,8 @@ interface ModuleGraph {
 }
 declare function updateModuleGraphForFile(graph: ModuleGraph, project: Project, filePath: string): void;
 //#endregion
-//#region src/types/diagnostic.d.ts
-type Severity = "error" | "warning" | "info";
-type Category = "security" | "performance" | "correctness" | "architecture";
-interface SourceLine {
-  line: number;
-  text: string;
-}
-interface Diagnostic {
-  category: Category;
-  column: number;
-  filePath: string;
-  help: string;
-  line: number;
-  message: string;
-  rule: string;
-  scope?: RuleScope;
-  severity: Severity;
-  sourceLines?: SourceLine[];
-}
-//#endregion
-//#region src/types/config.d.ts
-interface RuleOverride {
-  enabled?: boolean;
-  severity?: Severity;
-}
-interface NestjsDoctorIgnoreConfig {
-  files?: string[];
-  rules?: string[];
-}
-interface NestjsDoctorConfig {
-  categories?: Partial<Record<Category, boolean>>;
-  customRulesDir?: string;
-  exclude?: string[];
-  ignore?: NestjsDoctorIgnoreConfig;
-  include?: string[];
-  minScore?: number;
-  rules?: Record<string, RuleOverride | boolean>;
-}
-//#endregion
-//#region src/rules/types.d.ts
-type RuleScope = "file" | "project";
+//#region src/engine/rules/types.d.ts
+type RuleScope = "file" | "project" | "schema";
 interface RuleMeta {
   category: Category;
   description: string;
@@ -76,9 +118,10 @@ interface RuleMeta {
   scope?: RuleScope;
   severity: Severity;
 }
-interface RuleContext {
+interface CodeRuleContext {
+  config?: NestjsDoctorConfig;
   filePath: string;
-  report(diagnostic: Omit<Diagnostic, "rule" | "category" | "severity">): void;
+  report(diagnostic: Omit<CodeDiagnostic, "rule" | "category" | "severity" | "scope">): void;
   sourceFile: SourceFile;
 }
 interface ProjectRuleContext {
@@ -87,19 +130,57 @@ interface ProjectRuleContext {
   moduleGraph: ModuleGraph;
   project: Project;
   providers: Map<string, ProviderInfo>;
-  report(diagnostic: Omit<Diagnostic, "rule" | "category" | "severity">): void;
+  report(diagnostic: Omit<CodeDiagnostic, "rule" | "category" | "severity" | "scope">): void;
+}
+interface SchemaRuleContext {
+  orm: string;
+  report(diagnostic: Omit<SchemaDiagnostic, "rule" | "category" | "severity" | "scope">): void;
+  schemaGraph: SchemaGraph;
 }
 interface Rule {
-  check(context: RuleContext): void;
+  check(context: CodeRuleContext): void;
   meta: RuleMeta;
 }
 interface ProjectRule {
   check(context: ProjectRuleContext): void;
   meta: RuleMeta;
 }
-type AnyRule = Rule | ProjectRule;
+interface SchemaRule {
+  check(context: SchemaRuleContext): void;
+  meta: RuleMeta;
+}
+type AnyRule = Rule | ProjectRule | SchemaRule;
 //#endregion
-//#region src/types/result.d.ts
+//#region src/common/diagnostic.d.ts
+type Severity = "error" | "warning" | "info";
+type Category = "security" | "performance" | "correctness" | "architecture" | "schema";
+interface SourceLine {
+  line: number;
+  text: string;
+}
+interface BaseDiagnostic {
+  category: Category;
+  filePath: string;
+  help: string;
+  message: string;
+  rule: string;
+  scope?: RuleScope;
+  severity: Severity;
+}
+interface CodeDiagnostic extends BaseDiagnostic {
+  column: number;
+  line: number;
+  sourceLines?: SourceLine[];
+}
+interface SchemaDiagnostic extends BaseDiagnostic {
+  entity: string;
+  schemaColumn?: string;
+}
+type Diagnostic = CodeDiagnostic | SchemaDiagnostic;
+declare function isCodeDiagnostic(d: Diagnostic): d is CodeDiagnostic;
+declare function isSchemaDiagnostic(d: Diagnostic): d is SchemaDiagnostic;
+//#endregion
+//#region src/common/result.d.ts
 interface Score {
   label: string;
   value: number;
@@ -128,6 +209,7 @@ interface DiagnoseResult {
   elapsedMs: number;
   project: ProjectInfo;
   ruleErrors: RuleErrorInfo[];
+  schema?: SerializedSchemaGraph;
   score: Score;
   summary: DiagnoseSummary;
 }
@@ -142,54 +224,116 @@ interface MonorepoResult {
   subProjects: SubProjectResult[];
 }
 //#endregion
-//#region src/core/scanner.d.ts
-interface ScanOptions {
-  config?: string;
+//#region src/common/errors.d.ts
+declare class NestjsDoctorError extends Error {
+  constructor(message: string);
+}
+declare class ConfigurationError extends NestjsDoctorError {
+  constructor(message: string);
+}
+declare class ScanError extends NestjsDoctorError {
+  constructor(message: string);
+}
+declare class ValidationError extends NestjsDoctorError {
+  constructor(message: string);
+}
+//#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[];
+  config: NestjsDoctorConfig;
+  customRuleWarnings: string[];
+  fileRules: Rule[];
+  projectRules: ProjectRule[];
+  schemaRules: SchemaRule[];
 }
-interface ScanContext {
+declare function resolveScanConfig(targetPath: string, configPath?: string): Promise<ScanConfig>;
+//#endregion
+//#region src/engine/project-detector.d.ts
+interface MonorepoInfo {
+  projects: Map<string, string>;
+}
+//#endregion
+//#region src/engine/analysis-context.d.ts
+interface AnalysisContext {
   astProject: Project;
   config: NestjsDoctorConfig;
   fileRules: Rule[];
   files: string[];
   moduleGraph: ModuleGraph;
+  project: ProjectInfo;
   projectRules: ProjectRule[];
   providers: Map<string, ProviderInfo>;
+  schemaGraph?: SchemaGraph;
+  schemaRules: SchemaRule[];
   targetPath: string;
 }
-declare function prepareScan(targetPath: string, options?: ScanOptions): Promise<{
-  context: ScanContext;
+declare function buildAnalysisContext(targetPath: string, scanConfig: ScanConfig): Promise<AnalysisContext>;
+declare function prepareAnalysis(targetPath: string, options?: {
+  config?: string;
+}): Promise<{
+  context: AnalysisContext;
   customRuleWarnings: string[];
 }>;
-declare function updateFile(context: ScanContext, filePath: string): void;
-declare function scanFile(context: ScanContext, filePath: string): {
+declare function updateFile(context: AnalysisContext, filePath: string): void;
+//#endregion
+//#region src/engine/diagnostician.d.ts
+interface RawDiagnosticOutput {
+  diagnostics: Diagnostic[];
+  elapsedMs: number;
+  ruleErrors: RuleErrorInfo[];
+}
+declare function checkFile(context: AnalysisContext, filePath: string): {
   diagnostics: Diagnostic[];
   errors: RuleErrorInfo[];
 };
-declare function scanAllFiles(context: ScanContext): {
+declare function checkAllFiles(context: AnalysisContext): {
   diagnostics: Diagnostic[];
   errors: RuleErrorInfo[];
 };
-declare function scanProject(context: ScanContext): {
+declare function checkProject(context: AnalysisContext): {
+  diagnostics: Diagnostic[];
+  errors: RuleErrorInfo[];
+};
+declare function checkSchema(context: AnalysisContext): {
   diagnostics: Diagnostic[];
   errors: RuleErrorInfo[];
 };
 //#endregion
-//#region src/rules/index.d.ts
-declare function getRules(): AnyRule[];
-//#endregion
-//#region src/types/errors.d.ts
-declare class NestjsDoctorError extends Error {
-  constructor(message: string);
-}
-declare class ConfigurationError extends NestjsDoctorError {
-  constructor(message: string);
-}
-declare class ScanError extends NestjsDoctorError {
-  constructor(message: string);
+//#region src/engine/result-builder.d.ts
+interface EngineResult {
+  customRuleWarnings: string[];
+  files: string[];
+  moduleGraph: ModuleGraph;
+  providers: Map<string, ProviderInfo>;
+  result: DiagnoseResult;
+  schemaGraph: SchemaGraph;
 }
-declare class ValidationError extends NestjsDoctorError {
-  constructor(message: string);
+interface MonorepoEngineResult {
+  customRuleWarnings: string[];
+  moduleGraphs: Map<string, ModuleGraph>;
+  result: MonorepoResult;
 }
+declare function buildResult(context: AnalysisContext, rawOutput: RawDiagnosticOutput, customRuleWarnings?: string[]): EngineResult;
+//#endregion
+//#region src/engine/scanner.d.ts
+type AutoScanResult = {
+  isMonorepo: true;
+  monorepo: MonorepoEngineResult;
+} | {
+  isMonorepo: false;
+  single: EngineResult;
+};
+declare function autoScan(targetPath: string, options?: {
+  config?: string;
+  monorepo?: MonorepoInfo;
+}): Promise<AutoScanResult>;
+//#endregion
+//#region src/engine/schema/extract.d.ts
+declare function extractSchema(project: Project, files: string[], orm: string | null, targetPath: string): SchemaGraph;
 //#endregion
 //#region src/api/index.d.ts
 /**
@@ -218,5 +362,4 @@ declare function diagnoseMonorepo(path: string, options?: {
   config?: string;
 }): Promise<MonorepoResult>;
 //#endregion
-export { type AnyRule, type Category, ConfigurationError, type DiagnoseResult, type DiagnoseSummary, type Diagnostic, type MonorepoResult, type NestjsDoctorConfig, NestjsDoctorError, type ProjectInfo, type ProjectRule, type ProjectRuleContext, type Rule, type RuleContext, type RuleErrorInfo, type RuleMeta, type ScanContext, ScanError, type Score, type Severity, type SubProjectResult, ValidationError, diagnose, diagnoseMonorepo, getRules, prepareScan, scanAllFiles, scanFile, scanProject, updateFile, updateModuleGraphForFile, updateProvidersForFile };
-//# sourceMappingURL=index.d.mts.map
+export { type AnalysisContext, type AnyRule, type AutoScanResult, type BaseDiagnostic, type Category, type CodeDiagnostic, type CodeRuleContext, type CodeRuleContext as RuleContext, ConfigurationError, type DiagnoseResult, type DiagnoseSummary, type Diagnostic, 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, buildResult, checkAllFiles, checkFile, checkProject, checkSchema, diagnose, diagnoseMonorepo, extractSchema, getRules, isCodeDiagnostic, isSchemaDiagnostic, prepareAnalysis, resolveScanConfig, updateFile, updateModuleGraphForFile, updateProvidersForFile };