nestjs-doctor 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,1505 @@
+import { join, resolve } from "node:path";
+import { defineCommand, runMain } from "citty";
+import { performance } from "node:perf_hooks";
+import { Project, SyntaxKind } from "ts-morph";
+import { readFile } from "node:fs/promises";
+import { glob } from "tinyglobby";
+import pc from "picocolors";
+import ora from "ora";
+
+//#region src/engine/ast-parser.ts
+function createAstParser(files) {
+	const project = new Project({
+		compilerOptions: {
+			strict: true,
+			target: 99,
+			module: 99,
+			skipFileDependencyResolution: true
+		},
+		skipAddingFilesFromTsConfig: true
+	});
+	for (const file of files) project.addSourceFileAtPath(file);
+	return project;
+}
+
+//#endregion
+//#region src/engine/module-graph.ts
+const FORWARD_REF_REGEX = /=>\s*(\w+)/;
+function buildModuleGraph(project, files) {
+	const modules = new Map();
+	const edges = new Map();
+	for (const filePath of files) {
+		const sourceFile = project.getSourceFile(filePath);
+		if (!sourceFile) continue;
+		for (const cls of sourceFile.getClasses()) {
+			const moduleDecorator = cls.getDecorator("Module");
+			if (!moduleDecorator) continue;
+			const name = cls.getName() ?? "AnonymousModule";
+			const args = moduleDecorator.getArguments()[0];
+			const node = {
+				name,
+				filePath,
+				classDeclaration: cls,
+				imports: [],
+				exports: [],
+				providers: [],
+				controllers: []
+			};
+			if (args && args.getKind() === SyntaxKind.ObjectLiteralExpression) {
+				const obj = args.asKind(SyntaxKind.ObjectLiteralExpression);
+				if (obj) {
+					node.imports = extractArrayPropertyNames(obj, "imports");
+					node.exports = extractArrayPropertyNames(obj, "exports");
+					node.providers = extractArrayPropertyNames(obj, "providers");
+					node.controllers = extractArrayPropertyNames(obj, "controllers");
+				}
+			}
+			modules.set(name, node);
+		}
+	}
+	for (const [name, node] of modules) {
+		const importSet = new Set();
+		for (const imp of node.imports) if (modules.has(imp)) importSet.add(imp);
+		edges.set(name, importSet);
+	}
+	return {
+		modules,
+		edges
+	};
+}
+function extractArrayPropertyNames(obj, propertyName) {
+	const prop = obj.getProperty(propertyName);
+	if (!prop) return [];
+	const initializer = prop.getChildrenOfKind(SyntaxKind.ArrayLiteralExpression)[0];
+	if (!initializer) return [];
+	return initializer.getElements().map((el) => {
+		const text = el.getText();
+		if (text.startsWith("forwardRef")) {
+			const match = text.match(FORWARD_REF_REGEX);
+			return match ? match[1] : text;
+		}
+		if (text.startsWith("...")) return text.slice(3).trim();
+		return text;
+	});
+}
+function findCircularDeps(graph) {
+	const cycles = [];
+	const visited = new Set();
+	const recursionStack = new Set();
+	function dfs(node, path) {
+		visited.add(node);
+		recursionStack.add(node);
+		const neighbors = graph.edges.get(node) ?? new Set();
+		for (const neighbor of neighbors) if (!visited.has(neighbor)) dfs(neighbor, [...path, neighbor]);
+		else if (recursionStack.has(neighbor)) {
+			const cycleStart = path.indexOf(neighbor);
+			if (cycleStart !== -1) cycles.push(path.slice(cycleStart));
+			else cycles.push([...path, neighbor]);
+		}
+		recursionStack.delete(node);
+	}
+	for (const moduleName of graph.modules.keys()) if (!visited.has(moduleName)) dfs(moduleName, [moduleName]);
+	return cycles;
+}
+
+//#endregion
+//#region src/rules/types.ts
+function isProjectRule(rule) {
+	return rule.meta.scope === "project";
+}
+
+//#endregion
+//#region src/engine/rule-runner.ts
+function runRules(project, files, rules, options) {
+	const diagnostics = [];
+	const fileRules = [];
+	const projectRules = [];
+	for (const rule of rules) if (isProjectRule(rule)) projectRules.push(rule);
+	else fileRules.push(rule);
+	for (const filePath of files) {
+		const sourceFile = project.getSourceFile(filePath);
+		if (!sourceFile) continue;
+		for (const rule of fileRules) {
+			const context = {
+				sourceFile,
+				filePath,
+				report(partial) {
+					diagnostics.push({
+						...partial,
+						rule: rule.meta.id,
+						category: rule.meta.category,
+						severity: rule.meta.severity
+					});
+				}
+			};
+			try {
+				rule.check(context);
+			} catch {}
+		}
+	}
+	for (const rule of projectRules) {
+		const context = {
+			project,
+			files,
+			moduleGraph: options.moduleGraph,
+			providers: options.providers,
+			config: options.config,
+			report(partial) {
+				diagnostics.push({
+					...partial,
+					rule: rule.meta.id,
+					category: rule.meta.category,
+					severity: rule.meta.severity
+				});
+			}
+		};
+		try {
+			rule.check(context);
+		} catch {}
+	}
+	return diagnostics;
+}
+
+//#endregion
+//#region src/engine/type-resolver.ts
+const IMPORT_TYPE_REGEX = /import\([^)]+\)\.(\w+)/;
+const GENERIC_TYPE_REGEX$3 = /^(\w+)</;
+function resolveProviders(project, files) {
+	const providers = new Map();
+	for (const filePath of files) {
+		const sourceFile = project.getSourceFile(filePath);
+		if (!sourceFile) continue;
+		for (const cls of sourceFile.getClasses()) {
+			if (!cls.getDecorator("Injectable")) continue;
+			const name = cls.getName();
+			if (!name) continue;
+			const ctor = cls.getConstructors()[0];
+			const dependencies = ctor ? ctor.getParameters().map((p) => {
+				const typeText = p.getType().getText();
+				return extractSimpleTypeName(typeText);
+			}) : [];
+			const publicMethodCount = cls.getMethods().filter((m) => {
+				const scope = m.getScope();
+				return !scope || scope === "public";
+			}).length;
+			providers.set(name, {
+				name,
+				filePath,
+				classDeclaration: cls,
+				dependencies,
+				publicMethodCount
+			});
+		}
+	}
+	return providers;
+}
+function extractSimpleTypeName(typeText) {
+	const importMatch = typeText.match(IMPORT_TYPE_REGEX);
+	if (importMatch) return importMatch[1];
+	const genericMatch = typeText.match(GENERIC_TYPE_REGEX$3);
+	if (genericMatch) return genericMatch[1];
+	return typeText;
+}
+
+//#endregion
+//#region src/rules/architecture/no-barrel-export-internals.ts
+const INTERNAL_PATTERNS = [
+	/Repository$/,
+	/\.repository$/,
+	/\.entity$/,
+	/\.schema$/,
+	/\.guard$/,
+	/\.interceptor$/,
+	/\.pipe$/,
+	/\.filter$/,
+	/\.strategy$/
+];
+const noBarrelExportInternals = {
+	meta: {
+		id: "architecture/no-barrel-export-internals",
+		category: "architecture",
+		severity: "info",
+		description: "Don't re-export internal implementation details from barrel files",
+		help: "Only export the module's public API (services, DTOs, interfaces) from index.ts files."
+	},
+	check(context) {
+		if (!context.filePath.endsWith("/index.ts")) return;
+		for (const exportDecl of context.sourceFile.getExportDeclarations()) {
+			const moduleSpecifier = exportDecl.getModuleSpecifierValue();
+			if (!moduleSpecifier) continue;
+			const isInternal = INTERNAL_PATTERNS.some((p) => p.test(moduleSpecifier));
+			if (isInternal) context.report({
+				filePath: context.filePath,
+				message: `Barrel file re-exports internal module '${moduleSpecifier}'.`,
+				help: this.meta.help,
+				line: exportDecl.getStartLineNumber(),
+				column: 1
+			});
+			for (const namedExport of exportDecl.getNamedExports()) {
+				const name = namedExport.getName();
+				if (name.endsWith("Repository") || name.endsWith("Entity") || name.endsWith("Schema")) context.report({
+					filePath: context.filePath,
+					message: `Barrel file re-exports internal type '${name}'.`,
+					help: this.meta.help,
+					line: namedExport.getStartLineNumber(),
+					column: 1
+				});
+			}
+		}
+	}
+};
+
+//#endregion
+//#region src/engine/decorator-utils.ts
+function hasDecorator(cls, name) {
+	return cls.getDecorator(name) !== void 0;
+}
+function isController(cls) {
+	return hasDecorator(cls, "Controller");
+}
+function isService(cls) {
+	return hasDecorator(cls, "Injectable");
+}
+
+//#endregion
+//#region src/rules/architecture/no-business-logic-in-controllers.ts
+const HTTP_DECORATORS = new Set([
+	"Get",
+	"Post",
+	"Put",
+	"Patch",
+	"Delete",
+	"Head",
+	"Options",
+	"All"
+]);
+const noBusinessLogicInControllers = {
+	meta: {
+		id: "architecture/no-business-logic-in-controllers",
+		category: "architecture",
+		severity: "error",
+		description: "Controllers should only handle HTTP concerns — move business logic to services",
+		help: "Extract branches, loops, and complex calculations into a service method."
+	},
+	check(context) {
+		for (const cls of context.sourceFile.getClasses()) {
+			if (!isController(cls)) continue;
+			for (const method of cls.getMethods()) {
+				const isEndpoint = method.getDecorators().some((d) => HTTP_DECORATORS.has(d.getName()));
+				if (!isEndpoint) continue;
+				const body = method.getBody();
+				if (!body) continue;
+				const ifStatements = body.getDescendantsOfKind(SyntaxKind.IfStatement);
+				const forStatements = body.getDescendantsOfKind(SyntaxKind.ForStatement);
+				const forInStatements = body.getDescendantsOfKind(SyntaxKind.ForInStatement);
+				const forOfStatements = body.getDescendantsOfKind(SyntaxKind.ForOfStatement);
+				const whileStatements = body.getDescendantsOfKind(SyntaxKind.WhileStatement);
+				const switchStatements = body.getDescendantsOfKind(SyntaxKind.SwitchStatement);
+				const loopCount = forStatements.length + forInStatements.length + forOfStatements.length + whileStatements.length;
+				if (ifStatements.length > 1 || loopCount > 0 || switchStatements.length > 0) context.report({
+					filePath: context.filePath,
+					message: `Controller method '${method.getName()}' contains business logic (${ifStatements.length} if, ${loopCount} loops, ${switchStatements.length} switch). Move to a service.`,
+					help: this.meta.help,
+					line: method.getStartLineNumber(),
+					column: 1
+				});
+				const callExpressions = body.getDescendantsOfKind(SyntaxKind.CallExpression);
+				const complexArrayOps = callExpressions.filter((call) => {
+					const expr = call.getExpression();
+					if (expr.getKind() === SyntaxKind.PropertyAccessExpression) {
+						const propAccess = expr.asKind(SyntaxKind.PropertyAccessExpression);
+						const name = propAccess?.getName();
+						return name === "map" || name === "filter" || name === "reduce" || name === "sort" || name === "flatMap";
+					}
+					return false;
+				});
+				if (complexArrayOps.length > 1) context.report({
+					filePath: context.filePath,
+					message: `Controller method '${method.getName()}' contains data transformation logic (${complexArrayOps.length} array operations). Move to a service.`,
+					help: this.meta.help,
+					line: method.getStartLineNumber(),
+					column: 1
+				});
+			}
+		}
+	}
+};
+
+//#endregion
+//#region src/rules/architecture/no-circular-module-deps.ts
+const noCircularModuleDeps = {
+	meta: {
+		id: "architecture/no-circular-module-deps",
+		category: "architecture",
+		severity: "error",
+		description: "Circular dependencies in @Module() import graph",
+		help: "Break the cycle by extracting shared logic into a separate module or using forwardRef().",
+		scope: "project"
+	},
+	check(context) {
+		const cycles = findCircularDeps(context.moduleGraph);
+		for (const cycle of cycles) {
+			const cycleStr = cycle.join(" -> ");
+			const firstModule = context.moduleGraph.modules.get(cycle[0]);
+			context.report({
+				filePath: firstModule?.filePath ?? "unknown",
+				message: `Circular module dependency detected: ${cycleStr}`,
+				help: this.meta.help,
+				line: firstModule?.classDeclaration.getStartLineNumber() ?? 1,
+				column: 1
+			});
+		}
+	}
+};
+
+//#endregion
+//#region src/rules/architecture/no-god-module.ts
+const DEFAULT_MAX_PROVIDERS = 10;
+const DEFAULT_MAX_IMPORTS = 15;
+const noGodModule = {
+	meta: {
+		id: "architecture/no-god-module",
+		category: "architecture",
+		severity: "warning",
+		description: "Modules with too many providers or imports should be split into smaller feature modules",
+		help: "Split this module into smaller, focused feature modules.",
+		scope: "project"
+	},
+	check(context) {
+		const maxProviders = context.config.thresholds?.godModuleProviders ?? DEFAULT_MAX_PROVIDERS;
+		const maxImports = context.config.thresholds?.godModuleImports ?? DEFAULT_MAX_IMPORTS;
+		for (const mod of context.moduleGraph.modules.values()) {
+			if (mod.providers.length > maxProviders) context.report({
+				filePath: mod.filePath,
+				message: `Module '${mod.name}' has ${mod.providers.length} providers (max: ${maxProviders}). Consider splitting into smaller modules.`,
+				help: this.meta.help,
+				line: mod.classDeclaration.getStartLineNumber(),
+				column: 1
+			});
+			if (mod.imports.length > maxImports) context.report({
+				filePath: mod.filePath,
+				message: `Module '${mod.name}' has ${mod.imports.length} imports (max: ${maxImports}). Consider grouping into feature modules.`,
+				help: this.meta.help,
+				line: mod.classDeclaration.getStartLineNumber(),
+				column: 1
+			});
+		}
+	}
+};
+
+//#endregion
+//#region src/rules/architecture/no-god-service.ts
+const DEFAULT_MAX_METHODS = 10;
+const DEFAULT_MAX_DEPS = 8;
+const noGodService = {
+	meta: {
+		id: "architecture/no-god-service",
+		category: "architecture",
+		severity: "warning",
+		description: "Services with too many public methods or dependencies should be split",
+		help: "Split this service into smaller, focused services with single responsibilities.",
+		scope: "project"
+	},
+	check(context) {
+		const maxMethods = context.config.thresholds?.godServiceMethods ?? DEFAULT_MAX_METHODS;
+		const maxDeps = context.config.thresholds?.godServiceDeps ?? DEFAULT_MAX_DEPS;
+		for (const provider of context.providers.values()) {
+			if (provider.publicMethodCount > maxMethods) context.report({
+				filePath: provider.filePath,
+				message: `Service '${provider.name}' has ${provider.publicMethodCount} public methods (max: ${maxMethods}). Consider splitting.`,
+				help: this.meta.help,
+				line: provider.classDeclaration.getStartLineNumber(),
+				column: 1
+			});
+			if (provider.dependencies.length > maxDeps) context.report({
+				filePath: provider.filePath,
+				message: `Service '${provider.name}' has ${provider.dependencies.length} dependencies (max: ${maxDeps}). Consider splitting.`,
+				help: this.meta.help,
+				line: provider.classDeclaration.getStartLineNumber(),
+				column: 1
+			});
+		}
+	}
+};
+
+//#endregion
+//#region src/rules/architecture/no-manual-instantiation.ts
+const noManualInstantiation = {
+	meta: {
+		id: "architecture/no-manual-instantiation",
+		category: "architecture",
+		severity: "error",
+		description: "Do not manually instantiate @Injectable classes — use NestJS dependency injection",
+		help: "Register the class as a provider in a module and inject it via the constructor."
+	},
+	check(context) {
+		const newExpressions = context.sourceFile.getDescendantsOfKind(SyntaxKind.NewExpression);
+		for (const expr of newExpressions) {
+			const exprText = expr.getExpression().getText();
+			if (exprText.endsWith("Service") || exprText.endsWith("Repository") || exprText.endsWith("Guard") || exprText.endsWith("Interceptor") || exprText.endsWith("Pipe") || exprText.endsWith("Filter") || exprText.endsWith("Gateway") || exprText.endsWith("Resolver")) context.report({
+				filePath: context.filePath,
+				message: `Manual instantiation of '${exprText}' detected. Use dependency injection instead.`,
+				help: this.meta.help,
+				line: expr.getStartLineNumber(),
+				column: 1
+			});
+		}
+	}
+};
+
+//#endregion
+//#region src/rules/architecture/no-orm-in-controllers.ts
+const DOTTED_SUFFIX_REGEX$2 = /\.(\w+)$/;
+const GENERIC_TYPE_REGEX$2 = /^(\w+)</;
+const ORM_TYPES$1 = new Set([
+	"PrismaService",
+	"PrismaClient",
+	"EntityManager",
+	"DataSource",
+	"Repository",
+	"Connection",
+	"MongooseModel",
+	"InjectModel",
+	"InjectRepository",
+	"MikroORM",
+	"DrizzleService"
+]);
+const noOrmInControllers = {
+	meta: {
+		id: "architecture/no-orm-in-controllers",
+		category: "architecture",
+		severity: "error",
+		description: "Controllers must not inject ORM services directly — use a service layer",
+		help: "Inject a service that wraps the ORM instead of using the ORM directly in controllers."
+	},
+	check(context) {
+		for (const cls of context.sourceFile.getClasses()) {
+			if (!isController(cls)) continue;
+			const ctor = cls.getConstructors()[0];
+			if (!ctor) continue;
+			for (const param of ctor.getParameters()) {
+				const typeText = param.getType().getText();
+				const typeName = extractTypeName$2(typeText);
+				if (ORM_TYPES$1.has(typeName)) {
+					const nameNode = param.getNameNode();
+					context.report({
+						filePath: context.filePath,
+						message: `Controller injects ORM type '${typeName}' directly. Use a service layer.`,
+						help: this.meta.help,
+						line: nameNode.getStartLineNumber(),
+						column: nameNode.getStartLinePos() + 1
+					});
+				}
+			}
+			for (const param of cls.getConstructors()[0]?.getParameters() ?? []) for (const decorator of param.getDecorators()) {
+				const name = decorator.getName();
+				if (name === "InjectRepository" || name === "InjectModel") context.report({
+					filePath: context.filePath,
+					message: `Controller uses @${name}() decorator. Move data access to a service.`,
+					help: this.meta.help,
+					line: decorator.getStartLineNumber(),
+					column: 1
+				});
+			}
+		}
+	}
+};
+function extractTypeName$2(typeText) {
+	const match = typeText.match(DOTTED_SUFFIX_REGEX$2);
+	if (match) return match[1];
+	const genericMatch = typeText.match(GENERIC_TYPE_REGEX$2);
+	if (genericMatch) return genericMatch[1];
+	return typeText;
+}
+
+//#endregion
+//#region src/rules/architecture/no-orm-in-services.ts
+const DOTTED_SUFFIX_REGEX$1 = /\.(\w+)$/;
+const GENERIC_TYPE_REGEX$1 = /^(\w+)</;
+const ORM_TYPES = new Set([
+	"PrismaService",
+	"PrismaClient",
+	"EntityManager",
+	"DataSource",
+	"Connection",
+	"MikroORM"
+]);
+const noOrmInServices = {
+	meta: {
+		id: "architecture/no-orm-in-services",
+		category: "architecture",
+		severity: "warning",
+		description: "Services should use repository abstractions instead of ORM directly",
+		help: "Create a repository class that wraps ORM calls and inject that instead."
+	},
+	check(context) {
+		for (const cls of context.sourceFile.getClasses()) {
+			if (!isService(cls)) continue;
+			const className = cls.getName() ?? "";
+			if (className.endsWith("Repository") || className.endsWith("Repo")) continue;
+			const ctor = cls.getConstructors()[0];
+			if (!ctor) continue;
+			for (const param of ctor.getParameters()) {
+				const typeText = param.getType().getText();
+				const typeName = extractTypeName$1(typeText);
+				if (ORM_TYPES.has(typeName)) {
+					const nameNode = param.getNameNode();
+					context.report({
+						filePath: context.filePath,
+						message: `Service injects ORM type '${typeName}' directly. Consider using a repository abstraction.`,
+						help: this.meta.help,
+						line: nameNode.getStartLineNumber(),
+						column: nameNode.getStartLinePos() + 1
+					});
+				}
+				for (const decorator of param.getDecorators()) {
+					const name = decorator.getName();
+					if (name === "InjectRepository" || name === "InjectModel") context.report({
+						filePath: context.filePath,
+						message: `Service uses @${name}() directly. Consider wrapping in a repository class.`,
+						help: this.meta.help,
+						line: decorator.getStartLineNumber(),
+						column: 1
+					});
+				}
+			}
+		}
+	}
+};
+function extractTypeName$1(typeText) {
+	const match = typeText.match(DOTTED_SUFFIX_REGEX$1);
+	if (match) return match[1];
+	const genericMatch = typeText.match(GENERIC_TYPE_REGEX$1);
+	if (genericMatch) return genericMatch[1];
+	return typeText;
+}
+
+//#endregion
+//#region src/rules/architecture/no-repository-in-controllers.ts
+const DOTTED_SUFFIX_REGEX = /\.(\w+)$/;
+const GENERIC_TYPE_REGEX = /^(\w+)</;
+const REPOSITORY_PATTERNS = [/Repository$/, /Repo$/];
+const noRepositoryInControllers = {
+	meta: {
+		id: "architecture/no-repository-in-controllers",
+		category: "architecture",
+		severity: "error",
+		description: "Controllers must not inject repositories directly — use the service layer",
+		help: "Move database access to a service and inject the service into the controller instead."
+	},
+	check(context) {
+		for (const cls of context.sourceFile.getClasses()) {
+			if (!isController(cls)) continue;
+			const ctor = cls.getConstructors()[0];
+			if (!ctor) continue;
+			for (const param of ctor.getParameters()) {
+				const typeText = param.getType().getText();
+				const typeName = extractTypeName(typeText);
+				if (REPOSITORY_PATTERNS.some((p) => p.test(typeName))) {
+					const nameNode = param.getNameNode();
+					context.report({
+						filePath: context.filePath,
+						message: `Controller injects repository '${typeName}' directly. Use a service layer instead.`,
+						help: this.meta.help,
+						line: nameNode.getStartLineNumber(),
+						column: nameNode.getStartLinePos() + 1
+					});
+				}
+			}
+			for (const imp of context.sourceFile.getImportDeclarations()) {
+				const moduleSpecifier = imp.getModuleSpecifierValue();
+				if (moduleSpecifier.includes("/repositories/") || moduleSpecifier.includes("/repositories")) context.report({
+					filePath: context.filePath,
+					message: `Controller imports from repository path '${moduleSpecifier}'.`,
+					help: this.meta.help,
+					line: imp.getStartLineNumber(),
+					column: 1
+				});
+			}
+		}
+	}
+};
+function extractTypeName(typeText) {
+	const match = typeText.match(DOTTED_SUFFIX_REGEX);
+	if (match) return match[1];
+	const genericMatch = typeText.match(GENERIC_TYPE_REGEX);
+	if (genericMatch) return genericMatch[1];
+	return typeText;
+}
+
+//#endregion
+//#region src/rules/architecture/prefer-constructor-injection.ts
+const preferConstructorInjection = {
+	meta: {
+		id: "architecture/prefer-constructor-injection",
+		category: "architecture",
+		severity: "warning",
+		description: "Prefer constructor injection over @Inject() property injection",
+		help: "Move the dependency to a constructor parameter instead of using property injection."
+	},
+	check(context) {
+		for (const cls of context.sourceFile.getClasses()) {
+			if (!(isService(cls) || isController(cls))) continue;
+			for (const prop of cls.getProperties()) {
+				const hasInjectDecorator = prop.getDecorator("Inject");
+				if (!hasInjectDecorator) continue;
+				context.report({
+					filePath: context.filePath,
+					message: `Property '${prop.getName()}' uses @Inject() decorator. Prefer constructor injection.`,
+					help: this.meta.help,
+					line: prop.getStartLineNumber(),
+					column: 1
+				});
+			}
+		}
+	}
+};
+
+//#endregion
+//#region src/rules/architecture/prefer-interface-injection.ts
+const preferInterfaceInjection = {
+	meta: {
+		id: "architecture/prefer-interface-injection",
+		category: "architecture",
+		severity: "info",
+		description: "Consider injecting abstract classes instead of concrete implementations for testability",
+		help: "Create an abstract class and use a custom provider token for better testability."
+	},
+	check(context) {
+		for (const cls of context.sourceFile.getClasses()) {
+			if (!isService(cls)) continue;
+			const ctor = cls.getConstructors()[0];
+			if (!ctor) continue;
+			for (const param of ctor.getParameters()) {
+				const typeNode = param.getTypeNode();
+				if (!typeNode) continue;
+				const typeText = typeNode.getText();
+				if (typeText === "ConfigService" || typeText === "Logger" || typeText === "EventEmitter2" || typeText === "HttpService" || typeText === "JwtService" || typeText === "ModuleRef" || typeText.startsWith("Cache")) continue;
+				if (typeText.endsWith("Service") && !typeText.startsWith("Abstract") && !typeText.startsWith("I")) {
+					const className = cls.getName() ?? "";
+					if (className.endsWith("Service") && typeText !== className) context.report({
+						filePath: context.filePath,
+						message: `Service '${className}' injects concrete '${typeText}'. Consider using an abstract class for testability.`,
+						help: this.meta.help,
+						line: param.getStartLineNumber(),
+						column: 1
+					});
+				}
+			}
+		}
+	}
+};
+
+//#endregion
+//#region src/rules/architecture/require-feature-modules.ts
+const MAX_DIRECT_PROVIDERS = 5;
+const requireFeatureModules = {
+	meta: {
+		id: "architecture/require-feature-modules",
+		category: "architecture",
+		severity: "warning",
+		description: "AppModule should import feature modules rather than declaring many providers directly",
+		help: "Group related providers into feature modules and import them in AppModule.",
+		scope: "project"
+	},
+	check(context) {
+		const appModule = context.moduleGraph.modules.get("AppModule");
+		if (!appModule) return;
+		if (appModule.providers.length > MAX_DIRECT_PROVIDERS && appModule.imports.length < appModule.providers.length) context.report({
+			filePath: appModule.filePath,
+			message: `AppModule declares ${appModule.providers.length} providers directly. Group them into feature modules.`,
+			help: this.meta.help,
+			line: appModule.classDeclaration.getStartLineNumber(),
+			column: 1
+		});
+	}
+};
+
+//#endregion
+//#region src/rules/architecture/require-module-boundaries.ts
+const INTERNAL_PATHS = [
+	"/repositories/",
+	"/entities/",
+	"/dto/",
+	"/guards/",
+	"/interceptors/",
+	"/pipes/",
+	"/strategies/"
+];
+const requireModuleBoundaries = {
+	meta: {
+		id: "architecture/require-module-boundaries",
+		category: "architecture",
+		severity: "info",
+		description: "Avoid deep imports into other feature modules' internals",
+		help: "Import from the module's public API (barrel export) instead of reaching into its internals."
+	},
+	check(context) {
+		for (const imp of context.sourceFile.getImportDeclarations()) {
+			const moduleSpecifier = imp.getModuleSpecifierValue();
+			if (!moduleSpecifier.startsWith(".")) continue;
+			if (!moduleSpecifier.includes("../")) continue;
+			const crossesModuleBoundary = INTERNAL_PATHS.some((p) => moduleSpecifier.includes(p));
+			if (crossesModuleBoundary) context.report({
+				filePath: context.filePath,
+				message: `Import '${moduleSpecifier}' reaches into another module's internals.`,
+				help: this.meta.help,
+				line: imp.getStartLineNumber(),
+				column: 1
+			});
+		}
+	}
+};
+
+//#endregion
+//#region src/rules/correctness/prefer-readonly-injection.ts
+const preferReadonlyInjection = {
+	meta: {
+		id: "correctness/prefer-readonly-injection",
+		category: "correctness",
+		severity: "warning",
+		description: "Constructor DI parameters should be readonly to prevent accidental reassignment",
+		help: "Add the 'readonly' modifier to the constructor parameter."
+	},
+	check(context) {
+		for (const cls of context.sourceFile.getClasses()) {
+			if (!(isService(cls) || isController(cls))) continue;
+			const ctor = cls.getConstructors()[0];
+			if (!ctor) continue;
+			for (const param of ctor.getParameters()) {
+				if (!(param.hasModifier("private") || param.hasModifier("protected") || param.hasModifier("public"))) continue;
+				if (!param.isReadonly()) {
+					const nameNode = param.getNameNode();
+					context.report({
+						filePath: context.filePath,
+						message: `Constructor parameter '${param.getName()}' should be readonly.`,
+						help: this.meta.help,
+						line: nameNode.getStartLineNumber(),
+						column: nameNode.getStartLinePos() + 1
+					});
+				}
+			}
+		}
+	}
+};
+
+//#endregion
+//#region src/rules/security/no-hardcoded-secrets.ts
+const SECRET_PATTERNS = [
+	{
+		pattern: /^[A-Za-z0-9+/]{40,}={0,2}$/,
+		name: "Base64 key"
+	},
+	{
+		pattern: /^sk[-_][a-zA-Z0-9]{20,}$/,
+		name: "Secret key"
+	},
+	{
+		pattern: /^pk[-_][a-zA-Z0-9]{20,}$/,
+		name: "Public key (in source)"
+	},
+	{
+		pattern: /^ghp_[a-zA-Z0-9]{36,}$/,
+		name: "GitHub personal access token"
+	},
+	{
+		pattern: /^github_pat_[a-zA-Z0-9_]{22,}$/,
+		name: "GitHub fine-grained PAT"
+	},
+	{
+		pattern: /^gho_[a-zA-Z0-9]{36,}$/,
+		name: "GitHub OAuth token"
+	},
+	{
+		pattern: /^xox[bpras]-[a-zA-Z0-9-]+$/,
+		name: "Slack token"
+	},
+	{
+		pattern: /^eyJ[a-zA-Z0-9_-]{10,}\.[a-zA-Z0-9_-]{10,}\./,
+		name: "JWT token"
+	},
+	{
+		pattern: /^AKIA[0-9A-Z]{16}$/,
+		name: "AWS Access Key ID"
+	},
+	{
+		pattern: /^[a-f0-9]{64}$/,
+		name: "Hex-encoded secret (64 chars)"
+	}
+];
+const VARIABLE_NAME_PATTERNS = [
+	/secret/i,
+	/password/i,
+	/passwd/i,
+	/api[_-]?key/i,
+	/auth[_-]?token/i,
+	/private[_-]?key/i,
+	/access[_-]?key/i,
+	/client[_-]?secret/i
+];
+const noHardcodedSecrets = {
+	meta: {
+		id: "security/no-hardcoded-secrets",
+		category: "security",
+		severity: "error",
+		description: "Detect hardcoded secrets, API keys, and tokens in source code",
+		help: "Move secrets to environment variables and access them via ConfigService."
+	},
+	check(context) {
+		const stringLiterals = context.sourceFile.getDescendantsOfKind(SyntaxKind.StringLiteral);
+		for (const literal of stringLiterals) {
+			const value = literal.getLiteralValue();
+			if (value.length < 16) continue;
+			if (literal.getParent()?.getKind() === SyntaxKind.ImportDeclaration) continue;
+			for (const { pattern, name } of SECRET_PATTERNS) if (pattern.test(value)) {
+				context.report({
+					filePath: context.filePath,
+					message: `Possible hardcoded ${name} detected.`,
+					help: this.meta.help,
+					line: literal.getStartLineNumber(),
+					column: 1
+				});
+				break;
+			}
+		}
+		const variableDeclarations = context.sourceFile.getDescendantsOfKind(SyntaxKind.VariableDeclaration);
+		for (const decl of variableDeclarations) {
+			const name = decl.getName();
+			const initializer = decl.getInitializer();
+			if (!initializer) continue;
+			if (initializer.getKind() !== SyntaxKind.StringLiteral) continue;
+			const isSuspiciousName = VARIABLE_NAME_PATTERNS.some((p) => p.test(name));
+			if (!isSuspiciousName) continue;
+			const value = initializer.getText().slice(1, -1);
+			if (value.length >= 8 && !value.includes("${") && !value.startsWith("process.env") && value !== "your-secret-here" && value !== "changeme" && value !== "password") context.report({
+				filePath: context.filePath,
+				message: `Variable '${name}' appears to contain a hardcoded secret.`,
+				help: this.meta.help,
+				line: decl.getStartLineNumber(),
+				column: 1
+			});
+		}
+		const propertyAssignments = context.sourceFile.getDescendantsOfKind(SyntaxKind.PropertyAssignment);
+		for (const prop of propertyAssignments) {
+			const name = prop.getName();
+			const initializer = prop.getInitializer();
+			if (!initializer) continue;
+			if (initializer.getKind() !== SyntaxKind.StringLiteral) continue;
+			const isSuspiciousName = VARIABLE_NAME_PATTERNS.some((p) => p.test(name));
+			if (!isSuspiciousName) continue;
+			const value = initializer.getText().slice(1, -1);
+			if (value.length >= 8 && !value.includes("${") && !value.startsWith("process.env")) context.report({
+				filePath: context.filePath,
+				message: `Property '${name}' appears to contain a hardcoded secret.`,
+				help: this.meta.help,
+				line: prop.getStartLineNumber(),
+				column: 1
+			});
+		}
+	}
+};
+
+//#endregion
+//#region src/rules/index.ts
+const allRules = [
+	noBusinessLogicInControllers,
+	noRepositoryInControllers,
+	noOrmInControllers,
+	noOrmInServices,
+	noManualInstantiation,
+	preferConstructorInjection,
+	preferInterfaceInjection,
+	requireModuleBoundaries,
+	noBarrelExportInternals,
+	noCircularModuleDeps,
+	noGodModule,
+	noGodService,
+	requireFeatureModules,
+	preferReadonlyInjection,
+	noHardcodedSecrets
+];
+
+//#endregion
+//#region src/scorer/labels.ts
+function getScoreLabel(score) {
+	if (score >= 90) return "Excellent";
+	if (score >= 75) return "Good";
+	if (score >= 50) return "Fair";
+	if (score >= 25) return "Poor";
+	return "Critical";
+}
+
+//#endregion
+//#region src/scorer/weights.ts
+const SEVERITY_WEIGHTS = {
+	error: 3,
+	warning: 1.5,
+	info: .5
+};
+const CATEGORY_MULTIPLIERS = {
+	security: 1.5,
+	correctness: 1.3,
+	architecture: 1,
+	performance: .8
+};
+
+//#endregion
+//#region src/scorer/index.ts
+function calculateScore(diagnostics, fileCount) {
+	if (fileCount === 0) return {
+		value: 100,
+		label: getScoreLabel(100)
+	};
+	let totalPenalty = 0;
+	for (const d of diagnostics) {
+		const severityWeight = SEVERITY_WEIGHTS[d.severity];
+		const categoryMultiplier = CATEGORY_MULTIPLIERS[d.category];
+		totalPenalty += severityWeight * categoryMultiplier;
+	}
+	const normalizedPenalty = totalPenalty / fileCount;
+	const value = Math.max(0, Math.min(100, Math.round(100 - normalizedPenalty * 10)));
+	return {
+		value,
+		label: getScoreLabel(value)
+	};
+}
+
+//#endregion
+//#region src/types/config.ts
+const DEFAULT_CONFIG = {
+	include: ["**/*.ts"],
+	exclude: [
+		"node_modules/**",
+		"dist/**",
+		"build/**",
+		"coverage/**",
+		"**/*.spec.ts",
+		"**/*.test.ts",
+		"**/*.e2e-spec.ts",
+		"**/*.d.ts"
+	]
+};
+
+//#endregion
+//#region src/core/config-loader.ts
+const CONFIG_FILENAMES = ["nestjs-doctor.config.json", ".nestjs-doctor.json"];
+async function loadConfig(targetPath, configPath) {
+	if (configPath) return readConfigFile(configPath);
+	for (const filename of CONFIG_FILENAMES) try {
+		return await readConfigFile(join(targetPath, filename));
+	} catch {}
+	try {
+		const pkgRaw = await readFile(join(targetPath, "package.json"), "utf-8");
+		const pkg = JSON.parse(pkgRaw);
+		if (pkg["nestjs-doctor"] && typeof pkg["nestjs-doctor"] === "object") return mergeConfig(pkg["nestjs-doctor"]);
+	} catch {}
+	return { ...DEFAULT_CONFIG };
+}
+async function readConfigFile(path) {
+	const raw = await readFile(path, "utf-8");
+	const parsed = JSON.parse(raw);
+	return mergeConfig(parsed);
+}
+function mergeConfig(userConfig) {
+	return {
+		...DEFAULT_CONFIG,
+		...userConfig,
+		exclude: [...DEFAULT_CONFIG.exclude ?? [], ...userConfig.exclude ?? []]
+	};
+}
+
+//#endregion
+//#region src/core/file-collector.ts
+async function collectFiles(targetPath, config = {}) {
+	const include = config.include ?? DEFAULT_CONFIG.include;
+	const exclude = config.exclude ?? DEFAULT_CONFIG.exclude;
+	const files = await glob(include, {
+		cwd: targetPath,
+		absolute: true,
+		ignore: exclude
+	});
+	return files.sort();
+}
+
+//#endregion
+//#region src/core/match-glob-pattern.ts
+const REGEX_SPECIAL_CHARACTERS = /[.+^${}()|[\]\\]/g;
+const compileGlobPattern = (pattern) => {
+	const normalizedPattern = pattern.replace(/\\/g, "/");
+	let regexSource = "^";
+	let characterIndex = 0;
+	while (characterIndex < normalizedPattern.length) if (normalizedPattern[characterIndex] === "*" && normalizedPattern[characterIndex + 1] === "*") if (normalizedPattern[characterIndex + 2] === "/") {
+		regexSource += "(?:.+/)?";
+		characterIndex += 3;
+	} else {
+		regexSource += ".*";
+		characterIndex += 2;
+	}
+	else if (normalizedPattern[characterIndex] === "*") {
+		regexSource += "[^/]*";
+		characterIndex++;
+	} else if (normalizedPattern[characterIndex] === "?") {
+		regexSource += "[^/]";
+		characterIndex++;
+	} else {
+		regexSource += normalizedPattern[characterIndex].replace(REGEX_SPECIAL_CHARACTERS, "\\$&");
+		characterIndex++;
+	}
+	regexSource += "$";
+	return new RegExp(regexSource);
+};
+
+//#endregion
+//#region src/core/filter-diagnostics.ts
+const filterIgnoredDiagnostics = (diagnostics, config) => {
+	const ignoredRules = new Set(Array.isArray(config.ignore?.rules) ? config.ignore.rules : []);
+	const ignoredFilePatterns = Array.isArray(config.ignore?.files) ? config.ignore.files.map(compileGlobPattern) : [];
+	if (ignoredRules.size === 0 && ignoredFilePatterns.length === 0) return diagnostics;
+	return diagnostics.filter((diagnostic) => {
+		if (ignoredRules.has(diagnostic.rule)) return false;
+		const normalizedPath = diagnostic.filePath.replace(/\\/g, "/");
+		if (ignoredFilePatterns.some((pattern) => pattern.test(normalizedPath))) return false;
+		return true;
+	});
+};
+
+//#endregion
+//#region src/core/project-detector.ts
+async function detectProject(targetPath) {
+	const pkgPath = join(targetPath, "package.json");
+	let pkg = {};
+	try {
+		const raw = await readFile(pkgPath, "utf-8");
+		pkg = JSON.parse(raw);
+	} catch {}
+	const allDeps = {
+		...pkg.dependencies,
+		...pkg.devDependencies
+	};
+	const nestVersion = extractVersion(allDeps["@nestjs/core"]);
+	const orm = detectOrm(allDeps);
+	const framework = detectFramework(allDeps);
+	return {
+		name: pkg.name ?? "unknown",
+		nestVersion,
+		orm,
+		framework,
+		moduleCount: 0,
+		fileCount: 0
+	};
+}
+function extractVersion(version) {
+	if (!version) return null;
+	return version.replace(/[\^~>=<]/g, "");
+}
+function detectOrm(deps) {
+	if (deps["@prisma/client"]) return "prisma";
+	if (deps.typeorm) return "typeorm";
+	if (deps["@mikro-orm/core"]) return "mikro-orm";
+	if (deps.sequelize) return "sequelize";
+	if (deps.mongoose) return "mongoose";
+	if (deps["drizzle-orm"]) return "drizzle";
+	return null;
+}
+function detectFramework(deps) {
+	if (deps["@nestjs/platform-fastify"]) return "fastify";
+	if (deps["@nestjs/platform-express"]) return "express";
+	if (deps["@nestjs/core"]) return "express";
+	return null;
+}
+
+//#endregion
+//#region src/core/scanner.ts
+async function scan(targetPath, options = {}) {
+	const startTime = performance.now();
+	const config = await loadConfig(targetPath, options.config);
+	const project = await detectProject(targetPath);
+	const files = await collectFiles(targetPath, config);
+	project.fileCount = files.length;
+	const astProject = createAstParser(files);
+	const moduleGraph = buildModuleGraph(astProject, files);
+	const providers = resolveProviders(astProject, files);
+	const rules = filterRules(config);
+	const rawDiagnostics = runRules(astProject, files, rules, {
+		moduleGraph,
+		providers,
+		config
+	});
+	const diagnostics = filterIgnoredDiagnostics(rawDiagnostics, config);
+	project.moduleCount = moduleGraph.modules.size;
+	const score = calculateScore(diagnostics, files.length);
+	const summary = buildSummary(diagnostics);
+	const elapsedMs = performance.now() - startTime;
+	return {
+		score,
+		diagnostics,
+		project,
+		summary,
+		elapsedMs
+	};
+}
+function filterRules(config) {
+	return allRules.filter((rule) => {
+		const ruleConfig = config.rules?.[rule.meta.id];
+		if (ruleConfig === false) return false;
+		if (typeof ruleConfig === "object" && ruleConfig.enabled === false) return false;
+		const categoryEnabled = config.categories?.[rule.meta.category];
+		if (categoryEnabled === false) return false;
+		return true;
+	});
+}
+function buildSummary(diagnostics) {
+	return {
+		total: diagnostics.length,
+		errors: diagnostics.filter((d) => d.severity === "error").length,
+		warnings: diagnostics.filter((d) => d.severity === "warning").length,
+		info: diagnostics.filter((d) => d.severity === "info").length,
+		byCategory: {
+			security: diagnostics.filter((d) => d.category === "security").length,
+			performance: diagnostics.filter((d) => d.category === "performance").length,
+			correctness: diagnostics.filter((d) => d.category === "correctness").length,
+			architecture: diagnostics.filter((d) => d.category === "architecture").length
+		}
+	};
+}
+
+//#endregion
+//#region src/cli/flags.ts
+const flags = {
+	verbose: {
+		type: "boolean",
+		description: "Show file paths and line numbers per diagnostic",
+		default: false
+	},
+	score: {
+		type: "boolean",
+		description: "Output only the numeric score (for CI)",
+		default: false
+	},
+	json: {
+		type: "boolean",
+		description: "JSON output",
+		default: false
+	},
+	config: {
+		type: "string",
+		description: "Config file path"
+	}
+};
+
+//#endregion
+//#region src/cli/output/highlighter.ts
+const highlighter = {
+	error: pc.red,
+	warn: pc.yellow,
+	info: pc.cyan,
+	success: pc.green,
+	dim: pc.dim
+};
+
+//#endregion
+//#region src/cli/output/logger.ts
+const ANSI_ESCAPE_PATTERN = /\u001B\[[0-9;]*m/g;
+const stripAnsi = (text) => text.replace(ANSI_ESCAPE_PATTERN, "");
+const loggerCaptureState = {
+	isEnabled: false,
+	lines: []
+};
+const captureLogLine = (text) => {
+	if (!loggerCaptureState.isEnabled) return;
+	loggerCaptureState.lines.push(stripAnsi(text));
+};
+const writeLogLine = (text) => {
+	console.log(text);
+	captureLogLine(text);
+};
+const logger = {
+	error(...args) {
+		writeLogLine(highlighter.error(args.join(" ")));
+	},
+	warn(...args) {
+		writeLogLine(highlighter.warn(args.join(" ")));
+	},
+	info(...args) {
+		writeLogLine(highlighter.info(args.join(" ")));
+	},
+	success(...args) {
+		writeLogLine(highlighter.success(args.join(" ")));
+	},
+	dim(...args) {
+		writeLogLine(highlighter.dim(args.join(" ")));
+	},
+	log(...args) {
+		writeLogLine(args.join(" "));
+	},
+	break() {
+		writeLogLine("");
+	}
+};
+
+//#endregion
+//#region src/cli/output/console-reporter.ts
+const PERFECT_SCORE = 100;
+const SCORE_BAR_WIDTH = 50;
+const SCORE_GOOD_THRESHOLD = 75;
+const SCORE_OK_THRESHOLD = 50;
+const MILLISECONDS_PER_SECOND = 1e3;
+const BOX_HORIZONTAL_PADDING = 1;
+const BOX_OUTER_INDENT = 2;
+const SEVERITY_ORDER = {
+	error: 0,
+	warning: 1,
+	info: 2
+};
+const createFramedLine = (plainText, renderedText = plainText) => ({
+	plainText,
+	renderedText
+});
+const colorizeByScore = (text, score) => {
+	if (score >= SCORE_GOOD_THRESHOLD) return highlighter.success(text);
+	if (score >= SCORE_OK_THRESHOLD) return highlighter.warn(text);
+	return highlighter.error(text);
+};
+const colorizeBySeverity = (text, severity) => {
+	if (severity === "error") return highlighter.error(text);
+	if (severity === "warning") return highlighter.warn(text);
+	return highlighter.info(text);
+};
+const getSeverityIcon = (severity) => {
+	if (severity === "error") return "✗";
+	if (severity === "warning") return "⚠";
+	return "●";
+};
+const formatElapsedTime = (elapsedMs) => {
+	if (elapsedMs < MILLISECONDS_PER_SECOND) return `${Math.round(elapsedMs)}ms`;
+	return `${(elapsedMs / MILLISECONDS_PER_SECOND).toFixed(1)}s`;
+};
+const getNestBirds = (score) => {
+	if (score >= SCORE_GOOD_THRESHOLD) return ["◠ ◠ ◠", "╰───╯"];
+	if (score >= SCORE_OK_THRESHOLD) return ["• • •", "╰───╯"];
+	return ["x x x", "╰───╯"];
+};
+const getStarRating = (score) => {
+	if (score >= 90) return "★★★★★";
+	if (score >= 75) return "★★★★☆";
+	if (score >= 50) return "★★★☆☆";
+	if (score >= 25) return "★★☆☆☆";
+	return "★☆☆☆☆";
+};
+const buildScoreBarSegments = (score) => {
+	const filledCount = Math.round(score / PERFECT_SCORE * SCORE_BAR_WIDTH);
+	const emptyCount = SCORE_BAR_WIDTH - filledCount;
+	return {
+		filled: "█".repeat(filledCount),
+		empty: "░".repeat(emptyCount)
+	};
+};
+const buildPlainScoreBar = (score) => {
+	const { filled, empty } = buildScoreBarSegments(score);
+	return `${filled}${empty}`;
+};
+const buildScoreBar = (score) => {
+	const { filled, empty } = buildScoreBarSegments(score);
+	return colorizeByScore(filled, score) + highlighter.dim(empty);
+};
+const printFramedBox = (framedLines) => {
+	if (framedLines.length === 0) return;
+	const borderColorizer = highlighter.dim;
+	const outerIndent = " ".repeat(BOX_OUTER_INDENT);
+	const horizontalPadding = " ".repeat(BOX_HORIZONTAL_PADDING);
+	const maxLineLength = Math.max(...framedLines.map((l) => l.plainText.length));
+	const borderLine = "─".repeat(maxLineLength + BOX_HORIZONTAL_PADDING * 2);
+	logger.log(`${outerIndent}${borderColorizer(`┌${borderLine}┐`)}`);
+	for (const line of framedLines) {
+		const trailing = " ".repeat(maxLineLength - line.plainText.length);
+		logger.log(`${outerIndent}${borderColorizer("│")}${horizontalPadding}${line.renderedText}${trailing}${horizontalPadding}${borderColorizer("│")}`);
+	}
+	logger.log(`${outerIndent}${borderColorizer(`└${borderLine}┘`)}`);
+};
+const groupByRule = (diagnostics) => {
+	const groups = new Map();
+	for (const d of diagnostics) {
+		const key = d.rule;
+		const group = groups.get(key) ?? [];
+		group.push(d);
+		groups.set(key, group);
+	}
+	return groups;
+};
+const sortBySeverity = (groups) => [...groups].sort(([, a], [, b]) => SEVERITY_ORDER[a[0].severity] - SEVERITY_ORDER[b[0].severity]);
+const buildFileLineMap = (diagnostics) => {
+	const fileLines = new Map();
+	for (const d of diagnostics) {
+		const lines = fileLines.get(d.filePath) ?? [];
+		if (d.line > 0) lines.push(d.line);
+		fileLines.set(d.filePath, lines);
+	}
+	return fileLines;
+};
+const collectAffectedFiles = (diagnostics) => new Set(diagnostics.map((d) => d.filePath));
+const printDiagnostics = (diagnostics, verbose) => {
+	const ruleGroups = groupByRule(diagnostics);
+	const sortedGroups = sortBySeverity([...ruleGroups.entries()]);
+	for (const [, ruleDiagnostics] of sortedGroups) {
+		const first = ruleDiagnostics[0];
+		const icon = colorizeBySeverity(getSeverityIcon(first.severity), first.severity);
+		const count = ruleDiagnostics.length;
+		const countLabel = count > 1 ? colorizeBySeverity(` (${count})`, first.severity) : "";
+		logger.log(`  ${icon} ${first.message}${countLabel}`);
+		if (first.help) logger.dim(`    ${first.help}`);
+		if (verbose) {
+			const fileLines = buildFileLineMap(ruleDiagnostics);
+			for (const [filePath, lines] of fileLines) {
+				const lineLabel = lines.length > 0 ? `: ${lines.join(", ")}` : "";
+				logger.dim(`    ${filePath}${lineLabel}`);
+			}
+		}
+		logger.break();
+	}
+};
+function printConsoleReport(result, verbose) {
+	const { score, diagnostics, project, summary, elapsedMs } = result;
+	logger.break();
+	const framedLines = [];
+	const scoreColorizer = (text) => colorizeByScore(text, score.value);
+	const [birds, nest] = getNestBirds(score.value);
+	framedLines.push(createFramedLine("┌───────┐", scoreColorizer("┌───────┐")));
+	framedLines.push(createFramedLine(`│ ${birds} │  NestJS Doctor`, `${scoreColorizer(`│ ${birds} │`)}  NestJS Doctor`));
+	framedLines.push(createFramedLine(`│ ${nest} │`, scoreColorizer(`│ ${nest} │`)));
+	framedLines.push(createFramedLine("└───────┘", scoreColorizer("└───────┘")));
+	framedLines.push(createFramedLine(""));
+	const stars = getStarRating(score.value);
+	const scoreLinePlain = `${score.value} / ${PERFECT_SCORE}  ${stars}  ${score.label}`;
+	const scoreLineRendered = `${colorizeByScore(String(score.value), score.value)} / ${PERFECT_SCORE}  ${colorizeByScore(stars, score.value)}  ${colorizeByScore(score.label, score.value)}`;
+	framedLines.push(createFramedLine(scoreLinePlain, scoreLineRendered));
+	framedLines.push(createFramedLine(""));
+	framedLines.push(createFramedLine(buildPlainScoreBar(score.value), buildScoreBar(score.value)));
+	framedLines.push(createFramedLine(""));
+	const elapsed = formatElapsedTime(elapsedMs);
+	const affectedFileCount = collectAffectedFiles(diagnostics).size;
+	const summaryParts = [];
+	const summaryPartsPlain = [];
+	if (summary.errors > 0) {
+		const errorText = `✗ ${summary.errors} error${summary.errors === 1 ? "" : "s"}`;
+		summaryPartsPlain.push(errorText);
+		summaryParts.push(highlighter.error(errorText));
+	}
+	if (summary.warnings > 0) {
+		const warnText = `⚠ ${summary.warnings} warning${summary.warnings === 1 ? "" : "s"}`;
+		summaryPartsPlain.push(warnText);
+		summaryParts.push(highlighter.warn(warnText));
+	}
+	if (summary.info > 0) {
+		const infoText = `● ${summary.info} info`;
+		summaryPartsPlain.push(infoText);
+		summaryParts.push(highlighter.info(infoText));
+	}
+	if (diagnostics.length === 0) {
+		const noIssuesText = "No issues found!";
+		summaryPartsPlain.push(noIssuesText);
+		summaryParts.push(highlighter.success(noIssuesText));
+	}
+	const fileCountText = diagnostics.length > 0 ? `across ${affectedFileCount}/${project.fileCount} files` : `${project.fileCount} files scanned`;
+	const elapsedText = `in ${elapsed}`;
+	summaryPartsPlain.push(fileCountText);
+	summaryPartsPlain.push(elapsedText);
+	summaryParts.push(highlighter.dim(fileCountText));
+	summaryParts.push(highlighter.dim(elapsedText));
+	framedLines.push(createFramedLine(summaryPartsPlain.join("  "), summaryParts.join("  ")));
+	printFramedBox(framedLines);
+	logger.break();
+	const projectInfoParts = [`Project: ${project.name}`];
+	if (project.nestVersion) projectInfoParts.push(`NestJS ${project.nestVersion}`);
+	if (project.orm) projectInfoParts.push(project.orm);
+	projectInfoParts.push(`${project.moduleCount} modules`);
+	logger.dim(`  ${projectInfoParts.join(" | ")}`);
+	logger.break();
+	if (diagnostics.length === 0) return;
+	printDiagnostics(diagnostics, verbose);
+	if (!verbose) {
+		logger.dim("  Run with --verbose for file paths and line numbers");
+		logger.break();
+	}
+}
+
+//#endregion
+//#region src/cli/output/json-reporter.ts
+function printJsonReport(result) {
+	console.log(JSON.stringify(result, null, 2));
+}
+
+//#endregion
+//#region src/cli/output/spinner.ts
+let sharedInstance = null;
+let activeCount = 0;
+const pendingTexts = new Set();
+const finalize = (method, originalText, displayText) => {
+	pendingTexts.delete(originalText);
+	activeCount--;
+	if (activeCount <= 0 || !sharedInstance) {
+		sharedInstance?.[method](displayText);
+		sharedInstance = null;
+		activeCount = 0;
+		return;
+	}
+	sharedInstance.stop();
+	ora(displayText).start()[method](displayText);
+	const [remainingText] = pendingTexts;
+	if (remainingText) sharedInstance.text = remainingText;
+	sharedInstance.start();
+};
+const spinner = (text) => ({ start() {
+	activeCount++;
+	pendingTexts.add(text);
+	if (sharedInstance) sharedInstance.text = text;
+	else sharedInstance = ora({ text }).start();
+	return {
+		succeed: (displayText) => finalize("succeed", text, displayText),
+		fail: (displayText) => finalize("fail", text, displayText)
+	};
+} });
+
+//#endregion
+//#region src/cli/index.ts
+const main = defineCommand({
+	meta: {
+		name: "nestjs-doctor",
+		version: "0.1.0",
+		description: "Diagnostic CLI tool that scans NestJS codebases and produces a health score"
+	},
+	args: {
+		path: {
+			type: "positional",
+			description: "Path to the NestJS project (defaults to current directory)",
+			default: ".",
+			required: false
+		},
+		...flags
+	},
+	async run({ args }) {
+		const targetPath = resolve(args.path ?? ".");
+		const isSilent = args.score || args.json;
+		const scanSpinner = isSilent ? null : spinner("Scanning...").start();
+		const result = await scan(targetPath, { config: args.config });
+		if (scanSpinner) {
+			const { project } = result;
+			const detailParts = [`Scanned ${highlighter.info(String(project.fileCount))} files`];
+			if (project.nestVersion) detailParts.push(`NestJS ${highlighter.info(project.nestVersion)}`);
+			if (project.orm) detailParts.push(highlighter.info(project.orm));
+			scanSpinner.succeed(detailParts.join(" | "));
+		}
+		if (args.score) {
+			console.log(result.score.value);
+			return;
+		}
+		if (args.json) {
+			printJsonReport(result);
+			return;
+		}
+		printConsoleReport(result, args.verbose ?? false);
+		if (result.summary.errors > 0) process.exit(1);
+	}
+});
+runMain(main);
+
+//#endregion