nestjs-doctor 0.2.0 → 0.3.0

package/README.md

@@ -96,11 +96,45 @@ Usage: nestjs-doctor [directory] [options]
   --json          JSON output (for tooling)
   --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 Claude Code skill
   -h, --help      Show help
 ```
 
 ---
 
+## Claude Code
+
+nestjs-doctor ships with a [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code/skills) that scans your codebase and fixes issues interactively.
+
+### Setup
+
+If you haven't already, install as a devDependency:
+
+```bash
+pnpm add -D nestjs-doctor
+```
+
+Then scaffold the skill:
+
+```bash
+npx nestjs-doctor --init
+```
+
+This creates `.claude/skills/nestjs-doctor/SKILL.md` in your project. Commit it so every contributor gets the skill automatically.
+
+### Usage
+
+In Claude Code, type:
+
+```
+/nestjs-doctor
+/nestjs-doctor src/
+```
+
+Claude will scan your codebase, present a prioritized health report, and offer to fix every issue found.
+
+---
+
 ## Configuration
 
 Optional. Create `nestjs-doctor.config.json` in your project root:

package/dist/cli/index.mjs

@@ -2,11 +2,12 @@
 import { createRequire } from "node:module";
 import { join, resolve } from "node:path";
 import { defineCommand, runMain } from "citty";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { performance } from "node:perf_hooks";
 import { Project, SyntaxKind } from "ts-morph";
 import { glob } from "tinyglobby";
 import picomatch from "picomatch";
+import { existsSync } from "node:fs";
 import pc from "picocolors";
 import ora from "ora";
 
@@ -2526,27 +2527,14 @@ const flags = {
 	config: {
 		type: "string",
 		description: "Config file path"
+	},
+	init: {
+		type: "boolean",
+		description: "Set up the /nestjs-doctor Claude Code skill in your project",
+		default: false
 	}
 };
 
-//#endregion
-//#region src/cli/min-score.ts
-const validateMinScoreArg = (raw) => {
-	if (raw.trim() === "") return `Invalid --min-score value: "${raw}". Must be an integer between 0 and 100.`;
-	const num = Number(raw);
-	if (!Number.isInteger(num)) return `Invalid --min-score value: "${raw}". Must be an integer between 0 and 100.`;
-	if (num < 0 || num > 100) return `Invalid --min-score value: "${raw}". Must be an integer between 0 and 100.`;
-	return null;
-};
-const resolveMinScore = (cliValue, configValue) => {
-	if (cliValue !== void 0) return Number(cliValue);
-	return configValue;
-};
-const checkMinScore = (actualScore, minScore) => {
-	if (minScore === void 0) return true;
-	return actualScore >= minScore;
-};
-
 //#endregion
 //#region src/cli/output/highlighter.ts
 const highlighter = {
@@ -2597,6 +2585,41 @@ const logger = {
 	}
 };
 
+//#endregion
+//#region src/cli/init-skill.ts
+const SKILL_DIR = ".claude/skills/nestjs-doctor";
+const SKILL_FILE = "SKILL.md";
+const initSkill = async (targetPath) => {
+	const skillDir = join(targetPath, SKILL_DIR);
+	const skillPath = join(skillDir, SKILL_FILE);
+	if (existsSync(skillPath)) {
+		logger.info(`${SKILL_DIR}/${SKILL_FILE} already exists — skipping.`);
+		return;
+	}
+	const template = await readFile(createRequire(import.meta.url).resolve("../../skill/SKILL.md"), "utf-8");
+	await mkdir(skillDir, { recursive: true });
+	await writeFile(skillPath, template, "utf-8");
+	logger.success(`Created ${SKILL_DIR}/${SKILL_FILE} — use /nestjs-doctor in Claude Code to scan and fix your NestJS project.`);
+};
+
+//#endregion
+//#region src/cli/min-score.ts
+const validateMinScoreArg = (raw) => {
+	if (raw.trim() === "") return `Invalid --min-score value: "${raw}". Must be an integer between 0 and 100.`;
+	const num = Number(raw);
+	if (!Number.isInteger(num)) return `Invalid --min-score value: "${raw}". Must be an integer between 0 and 100.`;
+	if (num < 0 || num > 100) return `Invalid --min-score value: "${raw}". Must be an integer between 0 and 100.`;
+	return null;
+};
+const resolveMinScore = (cliValue, configValue) => {
+	if (cliValue !== void 0) return Number(cliValue);
+	return configValue;
+};
+const checkMinScore = (actualScore, minScore) => {
+	if (minScore === void 0) return true;
+	return actualScore >= minScore;
+};
+
 //#endregion
 //#region src/cli/output/console-reporter.ts
 const PERFECT_SCORE = 100;
@@ -2859,6 +2882,10 @@ runMain(defineCommand({
 	},
 	async run({ args }) {
 		const targetPath = resolve(args.path ?? ".");
+		if (args.init) {
+			await initSkill(targetPath);
+			return;
+		}
 		const isSilent = args.score || args.json;
 		const rawMinScore = args["min-score"];
 		if (rawMinScore !== void 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-doctor",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Diagnostic CLI tool that scans NestJS codebases and produces a health score with actionable diagnostics",
   "type": "module",
   "bin": {
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "skill"
   ],
   "keywords": [
     "nestjs",

package/skill/SKILL.md

@@ -0,0 +1,119 @@
+---
+description: Scan a NestJS project with nestjs-doctor, present a health report, and fix issues interactively
+disable-model-invocation: true
+allowed-tools: Bash, Read, Edit, Glob, Grep, Write
+---
+
+# /nestjs-doctor — NestJS Health Scanner & Fixer
+
+Scan the NestJS codebase, present a prioritized health report, and offer to fix every issue found.
+
+## Step 1: Scan
+
+Run nestjs-doctor and capture the full JSON output:
+
+```!
+npx nestjs-doctor $ARGUMENTS --json 2>/dev/null
+```
+
+## Step 2: Summarize
+
+Parse the JSON output above. Present a summary:
+
+- **Score**: value / 100 (label)
+- **Severity counts**: errors, warnings, info
+- **Project info**: name, NestJS version, ORM, file count, module count
+
+## Step 3: Report
+
+Group diagnostics by severity (errors first, then warnings, then info). Within each severity, group by category (security > correctness > architecture > performance).
+
+For each group show:
+- Rule name and severity
+- Message and help text
+- Number of occurrences
+- Affected file paths (with line numbers)
+
+If there are more than 30 diagnostics, show the top 30 (prioritizing errors and warnings) and ask if the user wants to see the rest.
+
+## Step 4: Offer to Fix
+
+Ask the developer what they want to fix:
+1. **Fix all** — apply fixes for every diagnostic
+2. **Fix by category** — fix all issues in a specific category (security, correctness, architecture, performance)
+3. **Fix specific rules** — fix only specific rule violations
+4. **Review only** — no changes, just the report
+
+## Step 5: Fix
+
+For each diagnostic to fix:
+1. Read the affected file
+2. Apply the appropriate fix based on the rule (see Fix Guide below)
+3. Explain what was changed and why
+
+### Fix Guide by Rule
+
+#### Security
+
+- **no-hardcoded-secrets**: Extract the secret value to an environment variable. Import `ConfigService`, inject it, and use `this.configService.get('ENV_VAR_NAME')`. Add the env var name to `.env.example` if it exists.
+- **no-wildcard-cors**: Replace `origin: '*'` or `origin: true` with an explicit allowlist array or `configService.get('CORS_ORIGINS').split(',')`.
+- **no-unsafe-raw-query**: Replace template literal interpolation in raw SQL with parameterized queries. Use `$1, $2` placeholders (Postgres) or `?` (MySQL) and pass values as the second argument.
+- **no-eval**: Remove `eval()` or `new Function()`. Replace with safe alternatives: `JSON.parse()` for JSON, a proper expression parser for dynamic evaluation, or refactor to avoid dynamic code execution entirely.
+- **no-csrf-disabled**: Remove the code that explicitly disables CSRF protection, or add a comment explaining why it's intentionally disabled with a `// nestjs-doctor-ignore` comment.
+- **no-dangerous-redirects**: Validate redirect URLs against an allowlist of trusted domains. Never pass user input directly to `res.redirect()`.
+- **no-weak-crypto**: Replace `createHash('md5')` or `createHash('sha1')` with `createHash('sha256')` or stronger.
+- **no-exposed-env-vars**: Replace direct `process.env.X` access with `ConfigService`. Inject `ConfigService` and use `this.configService.get('X')` or `this.configService.getOrThrow('X')`.
+- **require-validation-pipe**: Add a validation pipe. Either add `@UsePipes(new ValidationPipe())` to the handler/controller, or use a global validation pipe in `main.ts`, or add a DTO class with `class-validator` decorators.
+- **no-exposed-stack-trace**: Remove `error.stack` from response objects. Log the stack trace server-side with `this.logger.error(error.stack)` and return a generic error message to the client.
+- **require-auth-guard**: Add `@UseGuards(AuthGuard)` to the controller class or individual routes. If intentionally public, add a comment explaining why.
+
+#### Correctness
+
+- **no-missing-injectable**: Add `@Injectable()` decorator to the class. Import it from `@nestjs/common`.
+- **no-duplicate-routes**: Remove or rename the duplicate route. Change the HTTP method or path to make each route unique.
+- **no-missing-guard-method**: Add the `canActivate(context: ExecutionContext): boolean | Promise<boolean> | Observable<boolean>` method to the guard class. Implement `CanActivate` interface.
+- **no-missing-pipe-method**: Add the `transform(value: any, metadata: ArgumentMetadata)` method to the pipe class. Implement `PipeTransform` interface.
+- **no-missing-filter-catch**: Add the `catch(exception: T, host: ArgumentHost)` method to the exception filter class. Implement `ExceptionFilter` interface.
+- **no-missing-interceptor-method**: Add the `intercept(context: ExecutionContext, next: CallHandler): Observable<any>` method. Implement `NestInterceptor` interface.
+- **require-inject-decorator**: Add `@Inject('TOKEN_NAME')` decorator to untyped constructor parameters, or add a proper type annotation.
+- **prefer-readonly-injection**: Add the `readonly` modifier to constructor-injected parameters: `constructor(private readonly myService: MyService)`.
+- **require-lifecycle-interface**: Add the corresponding interface to the class implements clause. E.g., if using `onModuleInit()`, add `implements OnModuleInit`.
+- **no-empty-handlers**: Add implementation to the empty HTTP handler. If it's a placeholder, add a `throw new NotImplementedException()`.
+- **no-async-without-await**: Either add an `await` expression, remove the `async` keyword, or if it intentionally returns a Promise, remove `async` and return the promise directly.
+- **no-duplicate-module-metadata**: Remove duplicate entries from `@Module()` arrays (providers, controllers, imports, exports).
+- **no-missing-module-decorator**: Add `@Module({})` decorator to the class. Import it from `@nestjs/common`.
+
+#### Architecture
+
+- **no-business-logic-in-controllers**: Extract the business logic (loops, complex conditionals, data transforms) into a service method. The controller should only call the service and return the result.
+- **no-repository-in-controllers**: Remove the repository injection from the controller. Create or use an existing service that wraps the repository, and inject that service instead.
+- **no-orm-in-controllers**: Remove PrismaService/EntityManager/DataSource injection from the controller. Create or use an existing service that wraps the ORM operations.
+- **no-circular-module-deps**: Break the circular dependency. Extract shared functionality into a separate module, use `forwardRef(() => Module)`, or restructure the module boundaries.
+- **no-manual-instantiation**: Replace `new SomeService()` with constructor injection. Add the service to the module's providers and inject it via the constructor.
+- **no-orm-in-services**: Consider introducing a repository layer. Create a repository class that wraps ORM operations, and inject the repository into the service instead of the ORM directly.
+- **no-god-module**: Split the module into smaller, focused feature modules. Group related providers together and create dedicated modules for each feature area.
+- **no-god-service**: Split the service into smaller, focused services. Extract groups of related methods into separate service classes.
+- **require-feature-modules**: Move providers out of AppModule into dedicated feature modules. Create feature modules and register providers there instead.
+- **prefer-constructor-injection**: Replace `@Inject()` property injection with constructor injection. Move the dependency to a constructor parameter.
+- **require-module-boundaries**: Replace deep imports (`import { X } from '../other-module/services/x.service'`) with imports through the module's public API (barrel file / index.ts).
+- **prefer-interface-injection**: Consider creating an interface/abstract class for the dependency and injecting that instead of the concrete implementation.
+- **no-barrel-export-internals**: Remove repository re-exports from barrel files. Repositories should only be accessible within their own module.
+
+#### Performance
+
+- **no-sync-io**: Replace synchronous I/O (`readFileSync`, `writeFileSync`, etc.) with async equivalents (`readFile`, `writeFile` from `fs/promises`).
+- **no-query-in-loop**: Replace the N+1 query pattern. Use batch queries, `Promise.all()`, or eager loading/joins to fetch all related data in a single query.
+- **no-blocking-constructor**: Move async operations and loops out of the constructor into `onModuleInit()` lifecycle hook. Implement `OnModuleInit` interface.
+- **no-dynamic-require**: Replace `require(variable)` with a static import or a switch/map pattern that uses static `require()` calls.
+- **no-unused-providers**: Remove the unused provider from the module's providers array, or start using it. If it's intended for external consumers, add it to the module's exports.
+- **no-logging-in-loops**: Move logging outside the loop, log a summary after the loop completes, or use conditional logging (e.g., log every Nth iteration).
+- **no-unnecessary-async**: Remove the `async` keyword since the function contains no `await` expressions. If it returns a Promise, return it directly without `async`.
+- **prefer-pagination**: Add pagination parameters (`skip`/`take`, `limit`/`offset`, or cursor-based) to `findMany()`/`find()` calls to avoid loading unbounded result sets.
+- **no-unused-module-exports**: Remove the unused export from the module's exports array, or start importing the module where the exported provider is needed.
+- **no-orphan-modules**: Import this module in another module that needs it, or remove it if it's truly unused. If it's the root module, this can be ignored.
+
+## Step 6: Verify
+
+After applying fixes, suggest re-running the scan:
+
+> Fixes applied. Run `/nestjs-doctor` again to verify the score improved.