angular-doctor 1.0.2 → 1.2.0

package/README.md

@@ -1,199 +1,219 @@
-# Angular Doctor
-
-Diagnose and improve Angular codebases with a single command.
-
-Angular Doctor scans your project for **Angular-specific lint issues** and **dead code**, then produces a **0–100 health score** plus actionable diagnostics.
-
----
-
-## ✨ Features
-
-- **Angular-aware linting** (components, directives, pipes, performance, architecture, TypeScript)
-- **Dead code detection** (unused files, exports, types) via [knip](https://knip.dev)
-- **Workspace support** (Angular CLI + npm/pnpm workspaces)
-- **Diff mode** to scan only changed files
-- **Markdown reports** for sharing results
-
----
-
-## ✅ Quick start
-
-Run at your Angular project root (or workspace root):
-
-```bash
-npx -y angular-doctor@latest .
-```
-
-![CLI output](docs/assets/cli-output.png)
-
-Generate a Markdown report in the current directory:
-
-```bash
-npx -y angular-doctor@latest . --report .
-```
-
-Show affected files and line numbers:
-
-```bash
-npx -y angular-doctor@latest . --verbose
-```
-
----
-
-## 🧭 Workspace support
-
-Angular Doctor automatically detects multiple projects:
-
-- **Angular CLI workspaces** — reads `angular.json` and scans each project inside `projects/`
-- **npm / pnpm workspaces** — detects packages with `@angular/core` from `workspaces` or `pnpm-workspace.yaml`
-
-When multiple projects are found:
-
-- **Interactive mode**: prompts for which projects to scan
-- **Non-interactive mode** (`-y`, CI): scans all detected projects
-
-Target a specific project (comma-separated for multiple):
-
-```bash
-npx -y angular-doctor@latest . --project my-app,my-lib
-```
-
----
-
-## ⚙️ CLI Options
-
-```
-Usage: angular-doctor [directory] [options]
-
-Options:
-  -v, --version         display the version number
-  --no-lint             skip linting
-  --no-dead-code        skip dead code detection
-  --verbose             show file details per rule
-  --score               output only the score
-  --report [path]       write a markdown report (optional output path)
-  --fast                speed up by skipping dead code and type-aware lint
-  -y, --yes             skip prompts, scan all workspace projects
-  --project <name>      select workspace project (comma-separated for multiple)
-  --diff [base]         scan only files changed vs base branch
-  -h, --help            display help for command
-```
-
----
-
-## 📝 Reports
-
-Use `--report` to write a Markdown report:
-
-- `--report` writes to the diagnostics temp folder
-- `--report .` writes to the current project directory
-- `--report ./reports` writes to a custom folder
-- `--report ./reports/scan.md` writes to a specific file
-
----
-
-## 🔧 Configuration
-
-Create an `angular-doctor.config.json` in your project root:
-
-```json
-{
-  "ignore": {
-    "rules": ["@angular-eslint/prefer-standalone"],
-    "files": ["src/generated/**"]
-  }
-}
-```
-
-Or use the `angularDoctor` key in `package.json`:
-
-```json
-{
-  "angularDoctor": {
-    "ignore": {
-      "rules": ["@angular-eslint/prefer-standalone"]
-    }
-  }
-}
-```
-
-### Config options
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `ignore.rules` | `string[]` | `[]` | Rules to suppress using the `plugin/rule` format |
-| `ignore.files` | `string[]` | `[]` | File paths to exclude, supports glob patterns |
-| `lint` | `boolean` | `true` | Enable/disable lint checks |
-| `deadCode` | `boolean` | `true` | Enable/disable dead code detection |
-| `verbose` | `boolean` | `false` | Show file details per rule |
-| `diff` | `boolean | string` | — | Scan only changed files |
-
----
-
-## 📦 Node.js API
-
-```typescript
-import { diagnose } from "angular-doctor/api";
-
-const result = await diagnose("./path/to/your/angular-project");
-
-console.log(result.score);       // { score: 82, label: "Great" }
-console.log(result.diagnostics); // Array of Diagnostic objects
-console.log(result.project);     // Detected framework, Angular version, etc.
-```
-
-Each diagnostic has the following shape:
-
-```typescript
-interface Diagnostic {
-  filePath: string;
-  plugin: string;
-  rule: string;
-  severity: "error" | "warning";
-  message: string;
-  help: string;
-  line: number;
-  column: number;
-  category: string;
-}
-```
-
----
-
-## 🧪 What it checks
-
-### Components
-- Missing `Component` / `Directive` class suffixes
-- Empty lifecycle methods
-- Missing lifecycle interfaces
-- Pipe not implementing `PipeTransform`
-
-### Performance
-- Missing `OnPush` change detection strategy
-- Outputs shadowing native DOM events
-
-### Architecture
-- Conflicting lifecycle hooks (`DoCheck` + `OnChanges`)
-- Use of `forwardRef`
-- Renamed inputs/outputs
-- Inline `inputs`/`outputs` metadata properties
-- Non-standalone components (Angular 17+)
-
-### TypeScript
-- Explicit `any` usage
-
-### Dead Code
-- Unused files
-- Unused exports and types
-
----
-
-## 💡 Inspiration
-
-Inspired by [react-doctor](https://github.com/millionco/react-doctor).
-
----
-
-## 📄 License
-
-MIT
+# Angular Doctor
+
+Diagnose and improve Angular codebases with a single command.
+
+Angular Doctor scans your project for **Angular-specific lint issues** and **dead code**, then produces a **0–100 health score** plus actionable diagnostics.
+
+---
+
+## ✨ Features
+
+- **Angular-aware linting** (components, directives, pipes, performance, architecture, TypeScript)
+- **Dead code detection** (unused files, exports, types) via [knip](https://knip.dev)
+- **Workspace support** (Angular CLI + npm/pnpm workspaces)
+- **Diff mode** to scan only changed files
+- **Markdown reports** for sharing results
+
+---
+
+## ✅ Quick start
+
+Run at your Angular project root (or workspace root):
+
+```bash
+npx -y angular-doctor@latest .
+```
+
+![CLI output](docs/assets/cli-output.png)
+
+Generate a Markdown report in the current directory:
+
+```bash
+npx -y angular-doctor@latest . --report .
+```
+
+Show affected files and line numbers:
+
+```bash
+npx -y angular-doctor@latest . --verbose
+```
+
+---
+
+## 🤖 Install for your coding agent
+
+Teach your coding agent to run Angular Doctor automatically after every Angular change:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/antonygiomarxdev/angular-doctor/main/install-skill.sh | bash
+```
+
+Supports **Cursor**, **Claude Code**, **Windsurf**, **Amp Code**, **Codex**, **Gemini CLI**, and **OpenCode**.
+
+Once installed, your agent will automatically run:
+
+```bash
+npx -y angular-doctor@latest . --verbose --diff
+```
+
+…after making Angular changes, catching issues before they reach review.
+
+---
+
+## 🧭 Workspace support
+
+Angular Doctor automatically detects multiple projects:
+
+- **Angular CLI workspaces** — reads `angular.json` and scans each project inside `projects/`
+- **npm / pnpm workspaces** — detects packages with `@angular/core` from `workspaces` or `pnpm-workspace.yaml`
+
+When multiple projects are found:
+
+- **Interactive mode**: prompts for which projects to scan
+- **Non-interactive mode** (`-y`, CI): scans all detected projects
+
+Target a specific project (comma-separated for multiple):
+
+```bash
+npx -y angular-doctor@latest . --project my-app,my-lib
+```
+
+---
+
+## ⚙️ CLI Options
+
+```
+Usage: angular-doctor [directory] [options]
+
+Options:
+  -v, --version         display the version number
+  --no-lint             skip linting
+  --no-dead-code        skip dead code detection
+  --verbose             show file details per rule
+  --score               output only the score
+  --report [path]       write a markdown report (optional output path)
+  --fast                speed up by skipping dead code and type-aware lint
+  -y, --yes             skip prompts, scan all workspace projects
+  --project <name>      select workspace project (comma-separated for multiple)
+  --diff [base]         scan only files changed vs base branch
+  -h, --help            display help for command
+```
+
+---
+
+## 📝 Reports
+
+Use `--report` to write a Markdown report:
+
+- `--report` writes to the diagnostics temp folder
+- `--report .` writes to the current project directory
+- `--report ./reports` writes to a custom folder
+- `--report ./reports/scan.md` writes to a specific file
+
+---
+
+## 🔧 Configuration
+
+Create an `angular-doctor.config.json` in your project root:
+
+```json
+{
+  "ignore": {
+    "rules": ["@angular-eslint/prefer-standalone"],
+    "files": ["src/generated/**"]
+  }
+}
+```
+
+Or use the `angularDoctor` key in `package.json`:
+
+```json
+{
+  "angularDoctor": {
+    "ignore": {
+      "rules": ["@angular-eslint/prefer-standalone"]
+    }
+  }
+}
+```
+
+### Config options
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `ignore.rules` | `string[]` | `[]` | Rules to suppress using the `plugin/rule` format |
+| `ignore.files` | `string[]` | `[]` | File paths to exclude, supports glob patterns |
+| `lint` | `boolean` | `true` | Enable/disable lint checks |
+| `deadCode` | `boolean` | `true` | Enable/disable dead code detection |
+| `verbose` | `boolean` | `false` | Show file details per rule |
+| `diff` | `boolean | string` | — | Scan only changed files |
+
+---
+
+## 📦 Node.js API
+
+```typescript
+import { diagnose } from "angular-doctor/api";
+
+const result = await diagnose("./path/to/your/angular-project");
+
+console.log(result.score);       // { score: 82, label: "Great" }
+console.log(result.diagnostics); // Array of Diagnostic objects
+console.log(result.project);     // Detected framework, Angular version, etc.
+```
+
+Each diagnostic has the following shape:
+
+```typescript
+interface Diagnostic {
+  filePath: string;
+  plugin: string;
+  rule: string;
+  severity: "error" | "warning";
+  message: string;
+  help: string;
+  line: number;
+  column: number;
+  category: string;
+}
+```
+
+---
+
+## 🧪 What it checks
+
+### Components
+- Missing `Component` / `Directive` class suffixes
+- Empty lifecycle methods
+- Missing lifecycle interfaces
+- Pipe not implementing `PipeTransform`
+
+### Performance
+- Missing `OnPush` change detection strategy
+- Outputs shadowing native DOM events
+
+### Architecture
+- Conflicting lifecycle hooks (`DoCheck` + `OnChanges`)
+- Use of `forwardRef`
+- Renamed inputs/outputs
+- Inline `inputs`/`outputs` metadata properties
+- Non-standalone components (Angular 17+)
+
+### TypeScript
+- Explicit `any` usage
+
+### Dead Code
+- Unused files
+- Unused exports and types
+
+---
+
+## 💡 Inspiration
+
+Inspired by [react-doctor](https://github.com/millionco/react-doctor).
+
+---
+
+## 📄 License
+
+MIT

package/bin/angular-doctor.js

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
-import "../dist/cli.mjs";
+#!/usr/bin/env node
+import "../dist/cli.mjs";

package/dist/cli.mjs

@@ -566,18 +566,22 @@ const KNIP_SEVERITY_MAP = {
 };
 const collectIssueRecords = (records, issueType, rootDirectory) => {
 	const diagnostics = [];
-	for (const issues of Object.values(records)) for (const issue of Object.values(issues)) diagnostics.push({
-		filePath: path.relative(rootDirectory, issue.filePath),
-		plugin: "knip",
-		rule: issueType,
-		severity: KNIP_SEVERITY_MAP[issueType] ?? "warning",
-		message: `${KNIP_MESSAGE_MAP[issueType]}: ${issue.symbol}`,
-		help: "",
-		line: 0,
-		column: 0,
-		category: KNIP_CATEGORY_MAP[issueType] ?? "Dead Code",
-		weight: 1
-	});
+	for (const issues of Object.values(records)) for (const issue of Object.values(issues)) {
+		const filePath = path.relative(rootDirectory, issue.filePath);
+		if (filePath.startsWith("..")) continue;
+		diagnostics.push({
+			filePath,
+			plugin: "knip",
+			rule: issueType,
+			severity: KNIP_SEVERITY_MAP[issueType] ?? "warning",
+			message: `${KNIP_MESSAGE_MAP[issueType]}: ${issue.symbol}`,
+			help: "",
+			line: 0,
+			column: 0,
+			category: KNIP_CATEGORY_MAP[issueType] ?? "Dead Code",
+			weight: 1
+		});
+	}
 	return diagnostics;
 };
 const silenced = async (fn) => {
@@ -602,6 +606,7 @@ const CONFIG_LOADING_ERROR_PATTERN = /Error loading .*\/([a-z-]+)\.config\./;
 const extractFailedPluginName = (error) => {
 	return String(error).match(CONFIG_LOADING_ERROR_PATTERN)?.[1] ?? null;
 };
+const ANGULAR_ENTRY_PATTERNS = ["**/*.module.ts", "**/*.routes.ts"];
 const runKnipWithOptions = async (knipCwd, workspaceName) => {
 	const options = await silenced(() => createOptions({
 		cwd: knipCwd,
@@ -609,6 +614,7 @@ const runKnipWithOptions = async (knipCwd, workspaceName) => {
 		...workspaceName ? { workspace: workspaceName } : {}
 	}));
 	const parsedConfig = options.parsedConfig;
+	if (fs.existsSync(path.join(knipCwd, "angular.json")) && parsedConfig["entry"] === void 0) parsedConfig["entry"] = ANGULAR_ENTRY_PATTERNS;
 	for (let attempt = 0; attempt <= MAX_KNIP_RETRIES; attempt++) try {
 		return await silenced(() => main(options));
 	} catch (error) {
@@ -622,22 +628,39 @@ const hasNodeModules = (directory) => {
 	const nodeModulesPath = path.join(directory, "node_modules");
 	return fs.existsSync(nodeModulesPath) && fs.statSync(nodeModulesPath).isDirectory();
 };
+/**
+* Searches upward from `directory` for an `angular.json` file and returns
+* the directory that contains it, or `null` if none is found.
+*/
+const findAngularWorkspaceRoot = (directory) => {
+	let current = directory;
+	while (true) {
+		if (fs.existsSync(path.join(current, "angular.json"))) return current;
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+};
 const runKnip = async (rootDirectory) => {
 	if (!hasNodeModules(rootDirectory)) return [];
-	const { issues } = await runKnipWithOptions(rootDirectory);
+	const { issues } = await runKnipWithOptions(findAngularWorkspaceRoot(rootDirectory) ?? rootDirectory);
 	const diagnostics = [];
-	for (const unusedFile of issues.files) diagnostics.push({
-		filePath: path.relative(rootDirectory, unusedFile),
-		plugin: "knip",
-		rule: "files",
-		severity: KNIP_SEVERITY_MAP["files"],
-		message: KNIP_MESSAGE_MAP["files"],
-		help: "This file is not imported by any other file in the project.",
-		line: 0,
-		column: 0,
-		category: KNIP_CATEGORY_MAP["files"],
-		weight: 1
-	});
+	for (const unusedFile of issues.files) {
+		const filePath = path.relative(rootDirectory, unusedFile);
+		if (filePath.startsWith("..")) continue;
+		diagnostics.push({
+			filePath,
+			plugin: "knip",
+			rule: "files",
+			severity: KNIP_SEVERITY_MAP["files"],
+			message: KNIP_MESSAGE_MAP["files"],
+			help: "This file is not imported by any other file in the project.",
+			line: 0,
+			column: 0,
+			category: KNIP_CATEGORY_MAP["files"],
+			weight: 1
+		});
+	}
 	for (const issueType of [
 		"exports",
 		"types",
@@ -1137,7 +1160,7 @@ const selectProjects = async (rootDirectory, projectFlag, skipPrompts) => {
 
 //#endregion
 //#region src/cli.ts
-const VERSION = "1.0.2";
+const VERSION = "1.2.0";
 const exitWithHint = () => {
 	logger.break();
 	logger.log("Cancelled.");