@elyracode/doctor 0.4.4

package/README.md

@@ -0,0 +1,63 @@
+# @elyracode/doctor
+
+Project health analysis for Elyra -- security audit, dependency check, code quality, and more.
+
+## Install
+
+```
+elyra install npm:@elyracode/doctor
+```
+
+## Commands
+
+- `/doctor` -- Run all health checks and send the report to the agent for analysis
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `project_health_check` | Run health checks. Can filter by category: security, dependencies, config, code-debt, code-quality, git, project |
+
+## Checks
+
+| Check | What it does |
+|-------|-------------|
+| **Security** | Runs `npm audit` and `composer audit` for known vulnerabilities |
+| **Dependencies** | Checks for outdated npm packages |
+| **Configuration** | Compares .env with .env.example for missing keys |
+| **Code Debt** | Scans for TODO, FIXME, HACK, WORKAROUND comments |
+| **Code Quality** | Finds source files over 500 lines |
+| **Git** | Reports uncommitted changes and untracked files |
+| **Project** | Checks for essential files (.gitignore, README, configs) |
+
+## Usage
+
+```
+> Run a health check on this project
+> Are there any security vulnerabilities?
+> How many TODO comments are in the codebase?
+> Check if my .env is missing any keys
+```
+
+The agent runs the checks automatically and suggests fixes based on findings.
+
+## Report Format
+
+```
+# Project Health Report
+
+Errors: 1 | Warnings: 3 | Info: 5
+
+## Errors
+- [Security] 2 critical/high npm vulnerabilities found
+
+## Warnings
+- [Dependencies] 12 outdated npm packages
+- [Code Debt] Found 8 debt markers: 5 TODO, 2 FIXME, 1 HACK
+- [Code Quality] 3 files over 500 lines
+
+## Info
+- [Configuration] All .env.example keys present in .env
+- [Git] Working tree clean
+- [Project] All essential files present
+```

package/extensions/checks.ts

@@ -0,0 +1,313 @@
+/**
+ * Individual health checks for elyra doctor.
+ * Each check runs without LLM -- pure file/process analysis.
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+export interface Finding {
+	severity: "error" | "warning" | "info";
+	category: string;
+	message: string;
+	file?: string;
+}
+
+// ── Check: Security audit (npm/composer) ──
+
+export function checkSecurityAudit(cwd: string): Finding[] {
+	const findings: Finding[] = [];
+
+	// npm audit
+	if (existsSync(join(cwd, "package.json"))) {
+		try {
+			const result = execSync("npm audit --json 2>/dev/null", {
+				cwd,
+				timeout: 30000,
+				encoding: "utf-8",
+			});
+			const audit = JSON.parse(result);
+			const vulns = audit.metadata?.vulnerabilities ?? {};
+			const critical = (vulns.critical ?? 0) + (vulns.high ?? 0);
+			const moderate = vulns.moderate ?? 0;
+			const low = vulns.low ?? 0;
+			if (critical > 0) {
+				findings.push({ severity: "error", category: "Security", message: `${critical} critical/high npm vulnerabilities found` });
+			}
+			if (moderate > 0) {
+				findings.push({ severity: "warning", category: "Security", message: `${moderate} moderate npm vulnerabilities found` });
+			}
+			if (low > 0) {
+				findings.push({ severity: "info", category: "Security", message: `${low} low npm vulnerabilities found` });
+			}
+		} catch {
+			// npm audit returns non-zero when vulnerabilities exist
+			try {
+				const result = execSync("npm audit --json 2>/dev/null || true", {
+					cwd,
+					timeout: 30000,
+					encoding: "utf-8",
+				});
+				if (result.includes('"critical"') || result.includes('"high"')) {
+					findings.push({ severity: "error", category: "Security", message: "npm security vulnerabilities detected. Run `npm audit` for details." });
+				}
+			} catch {
+				// Skip if npm audit fails entirely
+			}
+		}
+	}
+
+	// composer audit
+	if (existsSync(join(cwd, "composer.json"))) {
+		try {
+			execSync("composer audit --format=json 2>/dev/null", {
+				cwd,
+				timeout: 30000,
+				encoding: "utf-8",
+			});
+		} catch (error) {
+			if (error && typeof error === "object" && "status" in error && (error as { status: unknown }).status !== 0) {
+				findings.push({ severity: "warning", category: "Security", message: "Composer security vulnerabilities detected. Run `composer audit` for details." });
+			}
+		}
+	}
+
+	if (findings.length === 0 && (existsSync(join(cwd, "package.json")) || existsSync(join(cwd, "composer.json")))) {
+		findings.push({ severity: "info", category: "Security", message: "No known vulnerabilities found" });
+	}
+
+	return findings;
+}
+
+// ── Check: Outdated dependencies ──
+
+export function checkOutdatedDeps(cwd: string): Finding[] {
+	const findings: Finding[] = [];
+
+	if (existsSync(join(cwd, "package.json"))) {
+		try {
+			const result = execSync("npm outdated --json 2>/dev/null || true", {
+				cwd,
+				timeout: 30000,
+				encoding: "utf-8",
+			});
+			const outdated = JSON.parse(result || "{}");
+			const count = Object.keys(outdated).length;
+			if (count > 10) {
+				findings.push({ severity: "warning", category: "Dependencies", message: `${count} outdated npm packages. Run \`npm outdated\` for details.` });
+			} else if (count > 0) {
+				findings.push({ severity: "info", category: "Dependencies", message: `${count} outdated npm packages` });
+			} else {
+				findings.push({ severity: "info", category: "Dependencies", message: "All npm packages are up to date" });
+			}
+		} catch {
+			// Skip
+		}
+	}
+
+	return findings;
+}
+
+// ── Check: Missing .env keys ──
+
+export function checkEnvFile(cwd: string): Finding[] {
+	const findings: Finding[] = [];
+	const examplePath = join(cwd, ".env.example");
+	const envPath = join(cwd, ".env");
+
+	if (!existsSync(examplePath)) return findings;
+
+	if (!existsSync(envPath)) {
+		findings.push({ severity: "error", category: "Configuration", message: ".env file is missing (but .env.example exists)" });
+		return findings;
+	}
+
+	const exampleKeys = parseEnvKeys(readFileSync(examplePath, "utf-8"));
+	const envKeys = parseEnvKeys(readFileSync(envPath, "utf-8"));
+	const missing = exampleKeys.filter((k) => !envKeys.includes(k));
+
+	if (missing.length > 0) {
+		findings.push({
+			severity: "warning",
+			category: "Configuration",
+			message: `${missing.length} keys in .env.example missing from .env: ${missing.slice(0, 5).join(", ")}${missing.length > 5 ? ` (+${missing.length - 5} more)` : ""}`,
+		});
+	} else {
+		findings.push({ severity: "info", category: "Configuration", message: "All .env.example keys present in .env" });
+	}
+
+	return findings;
+}
+
+function parseEnvKeys(content: string): string[] {
+	return content
+		.split("\n")
+		.map((l) => l.trim())
+		.filter((l) => l && !l.startsWith("#"))
+		.map((l) => l.split("=")[0].trim())
+		.filter((k) => k.length > 0);
+}
+
+// ── Check: TODO/FIXME/HACK comments ──
+
+export function checkCodeDebt(cwd: string): Finding[] {
+	const findings: Finding[] = [];
+
+	try {
+		const result = execSync(
+			"grep -rn --include='*.php' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' --include='*.vue' --include='*.blade.php' -E '(TODO|FIXME|HACK|XXX|WORKAROUND):?' . 2>/dev/null | head -100 || true",
+			{ cwd, timeout: 15000, encoding: "utf-8" },
+		);
+		const lines = result.trim().split("\n").filter((l) => l.length > 0);
+		if (lines.length > 0) {
+			const todoCount = lines.filter((l) => /TODO/i.test(l)).length;
+			const fixmeCount = lines.filter((l) => /FIXME/i.test(l)).length;
+			const hackCount = lines.filter((l) => /HACK|WORKAROUND/i.test(l)).length;
+			const parts: string[] = [];
+			if (todoCount > 0) parts.push(`${todoCount} TODO`);
+			if (fixmeCount > 0) parts.push(`${fixmeCount} FIXME`);
+			if (hackCount > 0) parts.push(`${hackCount} HACK/WORKAROUND`);
+			findings.push({
+				severity: hackCount > 0 || fixmeCount > 0 ? "warning" : "info",
+				category: "Code Debt",
+				message: `Found ${lines.length} debt markers: ${parts.join(", ")}`,
+			});
+		} else {
+			findings.push({ severity: "info", category: "Code Debt", message: "No TODO/FIXME/HACK comments found" });
+		}
+	} catch {
+		// Skip
+	}
+
+	return findings;
+}
+
+// ── Check: Large files ──
+
+export function checkLargeFiles(cwd: string): Finding[] {
+	const findings: Finding[] = [];
+	const threshold = 500; // lines
+	const largeFiles: string[] = [];
+
+	function scan(dir: string, depth: number): void {
+		if (depth > 5) return;
+		try {
+			for (const entry of readdirSync(dir)) {
+				if (entry.startsWith(".") || entry === "node_modules" || entry === "vendor" || entry === "dist" || entry === "build") continue;
+				const fullPath = join(dir, entry);
+				const stat = statSync(fullPath);
+				if (stat.isDirectory()) {
+					scan(fullPath, depth + 1);
+				} else if (stat.isFile() && /\.(php|ts|tsx|js|jsx|vue)$/.test(entry)) {
+					const content = readFileSync(fullPath, "utf-8");
+					const lineCount = content.split("\n").length;
+					if (lineCount > threshold) {
+						largeFiles.push(`${relative(cwd, fullPath)} (${lineCount} lines)`);
+					}
+				}
+			}
+		} catch {
+			// Permission errors etc
+		}
+	}
+
+	scan(cwd, 0);
+
+	if (largeFiles.length > 0) {
+		findings.push({
+			severity: "warning",
+			category: "Code Quality",
+			message: `${largeFiles.length} files over ${threshold} lines: ${largeFiles.slice(0, 5).join(", ")}${largeFiles.length > 5 ? ` (+${largeFiles.length - 5} more)` : ""}`,
+		});
+	} else {
+		findings.push({ severity: "info", category: "Code Quality", message: `No source files over ${threshold} lines` });
+	}
+
+	return findings;
+}
+
+// ── Check: Git status ──
+
+export function checkGitStatus(cwd: string): Finding[] {
+	const findings: Finding[] = [];
+
+	if (!existsSync(join(cwd, ".git"))) {
+		findings.push({ severity: "warning", category: "Git", message: "Not a git repository" });
+		return findings;
+	}
+
+	try {
+		const status = execSync("git status --porcelain 2>/dev/null", { cwd, timeout: 10000, encoding: "utf-8" });
+		const lines = status.trim().split("\n").filter((l) => l.length > 0);
+		const untracked = lines.filter((l) => l.startsWith("??")).length;
+		const modified = lines.filter((l) => !l.startsWith("??")).length;
+
+		if (modified > 0) {
+			findings.push({ severity: "info", category: "Git", message: `${modified} uncommitted change${modified > 1 ? "s" : ""}` });
+		}
+		if (untracked > 0) {
+			findings.push({ severity: "info", category: "Git", message: `${untracked} untracked file${untracked > 1 ? "s" : ""}` });
+		}
+		if (modified === 0 && untracked === 0) {
+			findings.push({ severity: "info", category: "Git", message: "Working tree clean" });
+		}
+	} catch {
+		// Skip
+	}
+
+	return findings;
+}
+
+// ── Check: Missing project essentials ──
+
+export function checkProjectEssentials(cwd: string): Finding[] {
+	const findings: Finding[] = [];
+
+	const checks: Array<{ file: string; label: string; severity: Finding["severity"] }> = [
+		{ file: ".gitignore", label: ".gitignore", severity: "warning" },
+		{ file: "README.md", label: "README.md", severity: "warning" },
+		{ file: ".env.example", label: ".env.example", severity: "info" },
+	];
+
+	// Laravel-specific
+	if (existsSync(join(cwd, "artisan"))) {
+		checks.push(
+			{ file: "phpunit.xml", label: "PHPUnit config (phpunit.xml)", severity: "info" },
+			{ file: "database/migrations", label: "Database migrations", severity: "info" },
+		);
+	}
+
+	// Node-specific
+	if (existsSync(join(cwd, "package.json"))) {
+		checks.push(
+			{ file: "tsconfig.json", label: "TypeScript config", severity: "info" },
+		);
+	}
+
+	for (const check of checks) {
+		if (!existsSync(join(cwd, check.file))) {
+			findings.push({ severity: check.severity, category: "Project", message: `Missing ${check.label}` });
+		}
+	}
+
+	if (findings.length === 0) {
+		findings.push({ severity: "info", category: "Project", message: "All essential files present" });
+	}
+
+	return findings;
+}
+
+// ── Run all checks ──
+
+export function runAllChecks(cwd: string): Finding[] {
+	return [
+		...checkSecurityAudit(cwd),
+		...checkOutdatedDeps(cwd),
+		...checkEnvFile(cwd),
+		...checkCodeDebt(cwd),
+		...checkLargeFiles(cwd),
+		...checkGitStatus(cwd),
+		...checkProjectEssentials(cwd),
+	];
+}

package/extensions/index.ts

@@ -0,0 +1,111 @@
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { Type } from "typebox";
+import { type Finding, runAllChecks } from "./checks.js";
+
+export default function (elyra: ExtensionAPI): void {
+	// ── Command: /doctor ──
+	elyra.registerCommand("doctor", {
+		description: "Run project health analysis",
+		handler: async (_args: string, ctx) => {
+			ctx.ui.notify("Running health checks...");
+
+			const cwd = process.cwd();
+			const findings = runAllChecks(cwd);
+			const report = formatReport(findings);
+
+			elyra.sendUserMessage(
+				`Here is the project health report. Analyze the findings and suggest the most important fixes:\n\n${report}`,
+			);
+		},
+	});
+
+	// ── Tool: project_health_check ──
+	elyra.registerTool({
+		name: "project_health_check",
+		label: "Project Health Check",
+		description:
+			"Analyze the current project for security vulnerabilities, outdated dependencies, " +
+			"missing configuration, code debt (TODO/FIXME/HACK), large files, and git status. " +
+			"Use this when the user asks about project health, code quality, or wants an audit.",
+		parameters: Type.Object({
+			category: Type.Optional(
+				Type.Union(
+					[
+						Type.Literal("all"),
+						Type.Literal("security"),
+						Type.Literal("dependencies"),
+						Type.Literal("config"),
+						Type.Literal("code-debt"),
+						Type.Literal("code-quality"),
+						Type.Literal("git"),
+						Type.Literal("project"),
+					],
+					{ description: "Check category to run (default: all)" },
+				),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			const cwd = process.cwd();
+			const findings = runAllChecks(cwd);
+
+			const filtered =
+				!params.category || params.category === "all"
+					? findings
+					: findings.filter((f) => f.category.toLowerCase().replace(/\s+/g, "-") === params.category);
+
+			const report = formatReport(filtered);
+
+			return {
+				content: [{ type: "text", text: report }],
+				details: {
+					errors: filtered.filter((f) => f.severity === "error").length,
+					warnings: filtered.filter((f) => f.severity === "warning").length,
+					info: filtered.filter((f) => f.severity === "info").length,
+				},
+			};
+		},
+	});
+}
+
+function formatReport(findings: Finding[]): string {
+	const errors = findings.filter((f) => f.severity === "error");
+	const warnings = findings.filter((f) => f.severity === "warning");
+	const infos = findings.filter((f) => f.severity === "info");
+
+	const lines: string[] = [
+		"# Project Health Report",
+		"",
+		`Errors: ${errors.length} | Warnings: ${warnings.length} | Info: ${infos.length}`,
+		"",
+	];
+
+	if (errors.length > 0) {
+		lines.push("## Errors");
+		for (const f of errors) {
+			lines.push(`- [${f.category}] ${f.message}${f.file ? ` (${f.file})` : ""}`);
+		}
+		lines.push("");
+	}
+
+	if (warnings.length > 0) {
+		lines.push("## Warnings");
+		for (const f of warnings) {
+			lines.push(`- [${f.category}] ${f.message}${f.file ? ` (${f.file})` : ""}`);
+		}
+		lines.push("");
+	}
+
+	if (infos.length > 0) {
+		lines.push("## Info");
+		for (const f of infos) {
+			lines.push(`- [${f.category}] ${f.message}${f.file ? ` (${f.file})` : ""}`);
+		}
+		lines.push("");
+	}
+
+	if (findings.length === 0) {
+		lines.push("No findings. Project looks healthy.");
+	}
+
+	return lines.join("\n");
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@elyracode/doctor",
+  "version": "0.4.4",
+  "description": "Elyra extension for project health analysis -- dependency audit, security checks, code quality, and more",
+  "type": "module",
+  "keywords": [
+    "elyra-package",
+    "doctor",
+    "health-check",
+    "audit",
+    "code-quality"
+  ],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/doctor"
+  },
+  "elyra": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}