check-project-health 1.0.0

package/README.md

@@ -0,0 +1,114 @@
+# check-project-health
+
+[![npm version](https://img.shields.io/npm/v/check-project-health.svg)](https://www.npmjs.com/package/check-project-health)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Node version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
+
+**Terminal health dashboard for developers.** Run one command in any project directory and get a beautiful, real-time health report: dependencies, git status, code quality, environment config, tests, and security — all in one place.
+
+```
+  ╭─────────────────────────────────────╮
+  │   🏥 PROJECT HEALTH REPORT          │
+  │   Score: 78/100   Grade: B          │
+  │   Status: Good                      │
+  ╰─────────────────────────────────────╯
+
+  ┌──────────────────┬────────┬──────────┬────────────────────────────┐
+  │ Checker           │ Score  │ Status   │ Summary                    │
+  ├──────────────────┼────────┼──────────┼────────────────────────────┤
+  │ Dependencies     │ 85     │ ✅ ok    │ 2 packages outdated         │
+  │ Git              │ 90     │ ✅ ok    │ Repository in good shape    │
+  │ Code Quality     │ 72     │ ⚠️ warn  │ 5 TODOs across 2 files      │
+  └──────────────────┴────────┴──────────┴────────────────────────────┘
+```
+
+---
+
+## Installation
+
+```bash
+npm install -g check-project-health
+```
+
+---
+
+## Usage
+
+Run from any project directory (uses current working directory):
+
+```bash
+check-project-health
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output raw JSON instead of the visual dashboard (for CI or tooling) |
+| `--no-color` | Disable colored output |
+| `--skip <checkers>` | Comma-separated checker names to skip (e.g. `--skip "Git,Security"`) |
+| `--run-tests` | Run the test script as part of the Tests checker (adds time) |
+
+**Examples:**
+
+```bash
+check-project-health --json > report.json
+check-project-health --no-color
+check-project-health --skip "Tests,Security"
+check-project-health --run-tests
+```
+
+---
+
+## How checkers work
+
+| Checker | Weight | What it does |
+|---------|--------|--------------|
+| **Dependencies** | 25% | Runs `npm outdated`, penalizes major/minor/patch outdated packages, suggests updates |
+| **Git** | 20% | Uses `simple-git`: status (untracked, modified, staged), last commit age, branch, unpushed commits |
+| **Code Quality** | 15% | Scans `.js`, `.ts`, `.jsx`, `.tsx`, `.vue`, `.py` for TODO, FIXME, HACK, XXX, BUG comments |
+| **Environment** | 20% | Compares `.env` and `.env.example` keys; warns if keys are missing or undocumented |
+| **Tests** | 10% | Looks for test script, test files (`*.test.js`, `*.spec.js`, configs); optionally runs tests with `--run-tests` |
+| **Security** | 10% | Runs `npm audit`, scores by severity (critical/high/moderate/low), suggests `npm audit fix` |
+
+**Scoring:** Each checker returns a 0–100 score. The overall score is a weighted average. Grades: **A** (90+), **B** (75+), **C** (60+), **D** (45+), **F** (&lt;45).
+
+---
+
+## Adding custom checkers
+
+1. Create a new file in `src/checkers/`, e.g. `src/checkers/custom.js`.
+2. Export a default async function with signature:
+   ```js
+   export default async function check(projectPath, options = {}) {
+     return {
+       name: 'Custom',
+       weight: 10,
+       status: 'ok' | 'warn' | 'fail' | 'skip' | 'error',
+       score: 0–100,
+       summary: 'One-line summary',
+       details: ['Detail 1', 'Detail 2'],
+       fixes: ['Suggested command or action'],
+     };
+   }
+   ```
+3. Register it in `src/checkers/index.js`:
+   ```js
+   import checkCustom from './custom.js';
+   const checkers = [
+     // ...existing
+     { name: 'Custom', check: checkCustom },
+   ];
+   ```
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue or PR on GitHub. Ensure tests and lint pass before submitting.
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import figlet from 'figlet';
+import ora from 'ora';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { runEngine } from '../src/engine.js';
+import { calculateScore } from '../src/scorer.js';
+import { renderDashboard } from '../src/ui/dashboard.js';
+import { colors } from '../src/ui/colors.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+program
+  .name('check-project-health')
+  .description('Analyze a project and show a terminal health dashboard')
+  .option('--json', 'Output raw JSON instead of the visual dashboard')
+  .option('--no-color', 'Disable colored output')
+  .option('--skip <checkers>', 'Comma-separated list of checker names to skip')
+  .option('--run-tests', 'Run test script as part of Tests checker')
+  .parse(process.argv);
+
+const opts = program.opts();
+const projectPath = process.cwd();
+const skipList = opts.skip ? opts.skip.split(',').map((s) => s.trim()) : [];
+const runTests = opts.runTests ?? false;
+
+async function main() {
+  if (!opts.json) {
+    console.log(
+      colors.title(
+        figlet.textSync('check-project-health', { horizontalLayout: 'fitted', font: 'Slant' })
+      )
+    );
+    console.log(colors.dim('  Analyzing your project...\n'));
+  }
+
+  const spinner = opts.json ? null : ora('Running health checkers...').start();
+
+  try {
+    const results = await runEngine(projectPath, { skipList, runTests });
+    const { score, grade, label } = calculateScore(results);
+
+    if (spinner) spinner.succeed('Analysis complete.\n');
+
+    if (opts.json) {
+      console.log(
+        JSON.stringify(
+          { score, grade, label, results, timestamp: new Date().toISOString() },
+          null,
+          2
+        )
+      );
+      return;
+    }
+
+    renderDashboard({ results, score, grade, label }, { color: opts.color !== false });
+  } catch (err) {
+    if (spinner) spinner.fail('Analysis failed.');
+    console.error(colors.fail('\nError: ' + (err.message || String(err))));
+    if (err.stack && process.env.DEBUG) {
+      console.error(colors.dim(err.stack));
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "check-project-health",
+  "version": "1.0.0",
+  "description": "Terminal health dashboard for developers",
+  "author": "Yash Nandvana <contact@yashnandvana.in>",
+  "license": "MIT",
+  "homepage": "https://github.com/yash-nandvana/project-health#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yash-nandvana/project-health.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yash-nandvana/project-health/issues"
+  },
+  "bin": {
+    "check-project-health": "./bin/cli.js"
+  },
+  "main": "./src/engine.js",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "cli",
+    "developer-tools",
+    "health",
+    "dashboard",
+    "devtools",
+    "npm-audit",
+    "git",
+    "terminal"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "cli-table3": "^0.6.3",
+    "glob": "^10.3.10",
+    "simple-git": "^3.22.0",
+    "ora": "^8.0.1",
+    "boxen": "^8.0.0",
+    "figlet": "^1.7.0"
+  }
+}

package/src/checkers/dependencies.js

@@ -0,0 +1,113 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import execAsync from '../utils/execAsync.js';
+
+const WEIGHT = 25;
+const PENALTY = { major: 10, minor: 5, patch: 2 };
+
+function statusFromScore(score) {
+  if (score >= 80) return 'ok';
+  if (score >= 50) return 'warn';
+  return 'fail';
+}
+
+/**
+ * @param {string} projectPath
+ * @returns {Promise<import('./index.js').CheckerResult>}
+ */
+export default async function checkDependencies(projectPath) {
+  const pkgPath = join(projectPath, 'package.json');
+  let pkg;
+  try {
+    const raw = await readFile(pkgPath, 'utf-8');
+    pkg = JSON.parse(raw);
+  } catch (err) {
+    return {
+      name: 'Dependencies',
+      weight: WEIGHT,
+      status: 'skip',
+      score: 0,
+      summary: 'No package.json found',
+      details: [],
+      fixes: [],
+    };
+  }
+
+  const deps = {
+    ...(pkg.dependencies || {}),
+    ...(pkg.devDependencies || {}),
+  };
+  const totalDeps = Object.keys(deps).length;
+
+  if (totalDeps === 0) {
+    return {
+      name: 'Dependencies',
+      weight: WEIGHT,
+      status: 'ok',
+      score: 100,
+      summary: 'No dependencies to check',
+      details: [],
+      fixes: [],
+    };
+  }
+
+  let outdated = {};
+  try {
+    const { stdout } = await execAsync('npm outdated --json', projectPath);
+    outdated = JSON.parse(stdout.trim() || '{}');
+  } catch (e) {
+    if (e.code === 1 && e.stdout) {
+      try {
+        outdated = JSON.parse((e.stdout || '').trim() || '{}');
+      } catch (_) {}
+    }
+  }
+
+  const details = [];
+  const fixes = new Set(['Run: npm update']);
+  let deduction = 0;
+
+  for (const [name, info] of Object.entries(outdated)) {
+    if (!info || typeof info !== 'object') continue;
+    const current = info.current || info.wanted || '?';
+    const latest = info.latest ?? info.wanted ?? '?';
+    let type = 'patch';
+    if (typeof latest === 'string' && typeof current === 'string') {
+      const [curMajor] = current.split('.').map(Number);
+      const [latMajor, latMinor] = latest.split('.').map(Number);
+      if (latMajor > curMajor) type = 'major';
+      else if (latMinor > (current.split('.')[1] || 0)) type = 'minor';
+    }
+    deduction += PENALTY[type] || 2;
+    details.push(`${name}: ${current} → ${latest} (${type})`);
+    if (type === 'major') fixes.add(`Run: npm install ${name}@latest`);
+  }
+
+  const count = { major: 0, minor: 0, patch: 0 };
+  for (const [, info] of Object.entries(outdated)) {
+    if (!info || typeof info !== 'object') continue;
+    const current = String(info.current || info.wanted || '');
+    const latest = String(info.latest ?? info.wanted ?? '');
+    const [curMajor] = current.split('.').map(Number);
+    const [latMajor, latMinor] = latest.split('.').map(Number);
+    if (latMajor > curMajor) count.major++;
+    else if (latMinor > parseInt(current.split('.')[1], 10)) count.minor++;
+    else count.patch++;
+  }
+
+  const score = Math.max(0, 100 - deduction);
+  const summary =
+    Object.keys(outdated).length === 0
+      ? `All ${totalDeps} packages up to date`
+      : `${Object.keys(outdated).length} packages outdated (${count.major} major, ${count.minor} minor, ${count.patch} patch)`;
+
+  return {
+    name: 'Dependencies',
+    weight: WEIGHT,
+    status: statusFromScore(score),
+    score,
+    summary,
+    details,
+    fixes: Array.from(fixes),
+  };
+}

package/src/checkers/env.js

@@ -0,0 +1,117 @@
+import { readFile, access } from 'fs/promises';
+import { join } from 'path';
+
+const WEIGHT = 20;
+
+function parseEnvKeys(content) {
+  const keys = new Set();
+  const lines = (content || '').split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq > 0) {
+      const key = trimmed.slice(0, eq).trim();
+      if (key) keys.add(key);
+    }
+  }
+  return keys;
+}
+
+/**
+ * @param {string} projectPath
+ * @returns {Promise<import('./index.js').CheckerResult>}
+ */
+export default async function checkEnv(projectPath) {
+  const examplePath = join(projectPath, '.env.example');
+  const envPath = join(projectPath, '.env');
+
+  let hasExample = false;
+  try {
+    await access(examplePath);
+    hasExample = true;
+  } catch (_) {}
+
+  if (!hasExample) {
+    return {
+      name: 'Environment',
+      weight: WEIGHT,
+      status: 'skip',
+      score: 0,
+      summary: 'No .env.example found',
+      details: [],
+      fixes: ['Add a .env.example documenting required environment variables'],
+    };
+  }
+
+  let exampleContent = '';
+  let envContent = '';
+  try {
+    exampleContent = await readFile(examplePath, 'utf-8');
+  } catch (err) {
+    return {
+      name: 'Environment',
+      weight: WEIGHT,
+      status: 'error',
+      score: 0,
+      summary: 'Could not read .env.example',
+      details: [],
+      fixes: [],
+    };
+  }
+
+  let hasEnv = false;
+  try {
+    await access(envPath);
+    hasEnv = true;
+    envContent = await readFile(envPath, 'utf-8');
+  } catch (_) {}
+
+  if (!hasEnv) {
+    return {
+      name: 'Environment',
+      weight: WEIGHT,
+      status: 'warn',
+      score: 50,
+      summary: '.env.example exists but .env is missing',
+      details: ['.env file not found'],
+      fixes: ['Copy .env.example to .env and fill in values: cp .env.example .env'],
+    };
+  }
+
+  const exampleKeys = parseEnvKeys(exampleContent);
+  const envKeys = parseEnvKeys(envContent);
+
+  const missingInEnv = [...exampleKeys].filter((k) => !envKeys.has(k));
+  const undocumented = [...envKeys].filter((k) => !exampleKeys.has(k));
+
+  let score = 100;
+  score -= missingInEnv.length * 20;
+  score -= undocumented.length * 10;
+  score = Math.max(0, score);
+
+  const status = score >= 80 ? 'ok' : score >= 50 ? 'warn' : 'fail';
+  const details = [];
+  if (missingInEnv.length) details.push(`Missing in .env: ${missingInEnv.join(', ')}`);
+  if (undocumented.length) details.push(`Undocumented in .env.example: ${undocumented.join(', ')}`);
+  const fixes = [];
+  if (missingInEnv.length) fixes.push('Add missing keys to .env from .env.example');
+  if (undocumented.length) fixes.push('Document all .env keys in .env.example');
+
+  const summary =
+    score === 100
+      ? '.env and .env.example are in sync'
+      : missingInEnv.length
+        ? `${missingInEnv.length} key(s) missing in .env`
+        : `${undocumented.length} key(s) not in .env.example`;
+
+  return {
+    name: 'Environment',
+    weight: WEIGHT,
+    status,
+    score,
+    summary,
+    details,
+    fixes,
+  };
+}

package/src/checkers/git.js

@@ -0,0 +1,122 @@
+import simpleGit from 'simple-git';
+
+const WEIGHT = 20;
+
+function statusFromScore(score) {
+  if (score >= 80) return 'ok';
+  if (score >= 50) return 'warn';
+  return 'fail';
+}
+
+/**
+ * @param {string} projectPath
+ * @returns {Promise<import('./index.js').CheckerResult>}
+ */
+export default async function checkGit(projectPath) {
+  const git = simpleGit({ baseDir: projectPath });
+  let score = 100;
+  const details = [];
+  const fixes = [];
+
+  try {
+    const isRepo = await git.checkIsRepo();
+    if (!isRepo) {
+      return {
+        name: 'Git',
+        weight: WEIGHT,
+        status: 'skip',
+        score: 0,
+        summary: 'Not a git repository',
+        details: [],
+        fixes: ['Run: git init'],
+      };
+    }
+  } catch (_) {
+    return {
+      name: 'Git',
+      weight: WEIGHT,
+      status: 'error',
+      score: 0,
+      summary: 'Git check failed',
+      details: [],
+      fixes: [],
+    };
+  }
+
+  try {
+    const status = await git.status();
+    const untracked = status.not_added?.length ?? 0;
+    const modified = status.modified?.length ?? 0;
+    const staged = status.staged?.length ?? 0;
+
+    if (untracked > 10) {
+      score -= 15;
+      details.push(`${untracked} untracked files`);
+      fixes.push('Add or ignore untracked files: git add . or update .gitignore');
+    }
+    if (modified > 5) {
+      score -= 10;
+      details.push(`${modified} modified files`);
+      fixes.push('Commit or stash changes: git add . && git commit -m "..."');
+    }
+    if (staged > 0) details.push(`${staged} staged files`);
+
+    const log = await git.log({ maxCount: 1 });
+    const lastCommit = log.latest?.date;
+    if (lastCommit) {
+      const daysSince = (Date.now() - new Date(lastCommit).getTime()) / (1000 * 60 * 60 * 24);
+      if (daysSince > 30) {
+        score -= 20;
+        details.push(`${Math.floor(daysSince)} days since last commit`);
+        fixes.push('Commit regularly to keep history fresh');
+      }
+    } else {
+      details.push('No commits yet');
+    }
+
+    const branch = await git.revparse(['--abbrev-ref', 'HEAD']);
+    const branchName = branch.trim().replace(/\r\n?/g, '');
+    details.push(`Branch: ${branchName}`);
+
+    try {
+      const remotes = await git.getRemotes(true);
+      if (Object.keys(remotes).length > 0) {
+        const pushStatus = await git.status();
+        const ahead = pushStatus.ahead ?? 0;
+        if (ahead > 0) {
+          score -= 10;
+          details.push(`${ahead} unpushed commit(s)`);
+          fixes.push('Push your commits: git push');
+        }
+      }
+    } catch (_) {}
+
+    score = Math.max(0, score);
+    const summary =
+      score >= 80
+        ? 'Repository in good shape'
+        : score >= 50
+          ? 'Some git issues to address'
+          : 'Git health needs attention';
+
+    return {
+      name: 'Git',
+      weight: WEIGHT,
+      status: statusFromScore(score),
+      score,
+      summary,
+      details,
+      fixes,
+    };
+  } catch (err) {
+    return {
+      name: 'Git',
+      weight: WEIGHT,
+      status: 'error',
+      score: 0,
+      summary: 'Checker failed: ' + (err.message || 'Unknown error'),
+      details: [],
+      fixes: [],
+    };
+  }
+}

package/src/checkers/index.js

@@ -0,0 +1,30 @@
+/**
+ * @typedef {Object} CheckerResult
+ * @property {string} name
+ * @property {number} weight
+ * @property {'ok'|'warn'|'fail'|'skip'|'error'} status
+ * @property {number} score
+ * @property {string} summary
+ * @property {string[]} details
+ * @property {string[]} fixes
+ */
+
+import checkDependencies from './dependencies.js';
+import checkGit from './git.js';
+import checkTodos from './todos.js';
+import checkEnv from './env.js';
+import checkTests from './tests.js';
+import checkSecurity from './security.js';
+
+/** @type {{ name: string, check: (path: string, options?: any) => Promise<CheckerResult> }[]} */
+const checkers = [
+  { name: 'Dependencies', check: checkDependencies },
+  { name: 'Git', check: checkGit },
+  { name: 'Code Quality', check: checkTodos },
+  { name: 'Environment', check: checkEnv },
+  { name: 'Tests', check: checkTests },
+  { name: 'Security', check: checkSecurity },
+];
+
+export default checkers;
+export { checkDependencies, checkGit, checkTodos, checkEnv, checkTests, checkSecurity };

package/src/checkers/security.js

@@ -0,0 +1,98 @@
+import execAsync from '../utils/execAsync.js';
+
+const WEIGHT = 10;
+const PENALTY = { critical: 30, high: 15, moderate: 5, low: 1 };
+
+function statusFromScore(score) {
+  if (score >= 80) return 'ok';
+  if (score >= 50) return 'warn';
+  return 'fail';
+}
+
+/**
+ * @param {string} projectPath
+ * @returns {Promise<import('./index.js').CheckerResult>}
+ */
+export default async function checkSecurity(projectPath) {
+  let raw = '';
+  try {
+    const { stdout } = await execAsync('npm audit --json', projectPath);
+    raw = stdout;
+  } catch (e) {
+    if (e.stdout) raw = e.stdout;
+    else
+      return {
+        name: 'Security',
+        weight: WEIGHT,
+        status: 'skip',
+        score: 100,
+        summary: 'npm audit not available (no package.json or no deps)',
+        details: [],
+        fixes: [],
+      };
+  }
+
+  let data = {};
+  try {
+    raw = (raw || '').trim().replace(/\r\n/g, '\n');
+    data = JSON.parse(raw || '{}');
+  } catch (_) {
+    return {
+      name: 'Security',
+      weight: WEIGHT,
+      status: 'ok',
+      score: 100,
+      summary: 'No vulnerabilities reported',
+      details: [],
+      fixes: [],
+    };
+  }
+
+  const vulns = data.vulnerabilities || {};
+  const counts = { critical: 0, high: 0, moderate: 0, low: 0 };
+  const details = [];
+  const fixCommands = new Set();
+
+  for (const [name, v] of Object.entries(vulns)) {
+    if (!v || typeof v !== 'object') continue;
+    const sev = (v.severity || 'moderate').toLowerCase();
+    if (counts[sev] !== undefined) counts[sev]++;
+    details.push(`${name}: ${sev} - ${v.via?.[0]?.title || v.via?.[0]?.url || 'vulnerability'}`);
+    if (v.fixAvailable && typeof v.fixAvailable === 'object' && v.fixAvailable.name) {
+      fixCommands.add(`npm audit fix`);
+    }
+  }
+
+  if (data.auditReportVersion >= 2 && data.metadata?.vulnerabilities) {
+    const meta = data.metadata.vulnerabilities;
+    counts.critical = meta.critical ?? 0;
+    counts.high = meta.high ?? 0;
+    counts.moderate = meta.moderate ?? 0;
+    counts.low = meta.low ?? 0;
+  }
+
+  let score = 100;
+  score -= (counts.critical || 0) * PENALTY.critical;
+  score -= (counts.high || 0) * PENALTY.high;
+  score -= (counts.moderate || 0) * PENALTY.moderate;
+  score -= (counts.low || 0) * PENALTY.low;
+  score = Math.max(0, score);
+
+  if (score < 100 && !fixCommands.size) fixCommands.add('npm audit fix');
+
+  const total = counts.critical + counts.high + counts.moderate + counts.low;
+  const summary =
+    total === 0
+      ? 'No known vulnerabilities'
+      : `${total} vulnerability(ies): ${counts.critical} critical, ${counts.high} high, ${counts.moderate} moderate, ${counts.low} low`;
+
+  return {
+    name: 'Security',
+    weight: WEIGHT,
+    status: statusFromScore(score),
+    score,
+    summary,
+    details: details.slice(0, 20),
+    fixes: Array.from(fixCommands),
+  };
+}

package/src/checkers/tests.js

@@ -0,0 +1,142 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { glob } from 'glob';
+import execAsync from '../utils/execAsync.js';
+
+const WEIGHT = 10;
+
+/**
+ * @param {string} projectPath
+ * @param {{ runTests?: boolean }} [options]
+ * @returns {Promise<import('./index.js').CheckerResult>}
+ */
+export default async function checkTests(projectPath, options = {}) {
+  const runTests = options.runTests === true;
+  const pkgPath = join(projectPath, 'package.json');
+  let pkg;
+  try {
+    const raw = await readFile(pkgPath, 'utf-8');
+    pkg = JSON.parse(raw);
+  } catch (_) {
+    return {
+      name: 'Tests',
+      weight: WEIGHT,
+      status: 'skip',
+      score: 0,
+      summary: 'No package.json',
+      details: [],
+      fixes: [],
+    };
+  }
+
+  const scripts = pkg.scripts || {};
+  const hasTestScript = !!(
+    scripts.test ||
+    scripts['test:ci'] ||
+    scripts['test:unit'] ||
+    scripts['test:integration']
+  );
+
+  const patterns = [
+    '**/*.test.js',
+    '**/*.spec.js',
+    '**/*.test.ts',
+    '**/*.spec.ts',
+    '**/__tests__/**',
+  ];
+  let testFiles = [];
+  try {
+    for (const p of patterns) {
+      const files = await glob(p, { cwd: projectPath, ignore: ['**/node_modules/**'] });
+      testFiles = testFiles.concat(files);
+    }
+    testFiles = [...new Set(testFiles)];
+  } catch (_) {}
+
+  const configs = [
+    'jest.config.js',
+    'jest.config.ts',
+    'jest.config.cjs',
+    'vitest.config.js',
+    'vitest.config.ts',
+    '.mocharc.js',
+    '.mocharc.json',
+    'vitest.config.js',
+  ];
+  let hasConfig = false;
+  for (const c of configs) {
+    if (existsSync(join(projectPath, c))) {
+      hasConfig = true;
+      break;
+    }
+  }
+
+  let score = 0;
+  let status = 'fail';
+  let summary = 'No tests found';
+  const details = [];
+  const fixes = [];
+
+  if (!hasTestScript && testFiles.length === 0 && !hasConfig) {
+    return {
+      name: 'Tests',
+      weight: WEIGHT,
+      status: 'warn',
+      score: 0,
+      summary: 'No test setup detected',
+      details: [],
+      fixes: ['Add a test script to package.json and test files (*.test.js, *.spec.js, etc.)'],
+    };
+  }
+
+  if (testFiles.length === 0 && !hasConfig) {
+    score = hasTestScript ? 50 : 0;
+    summary = 'Test script exists but no test files or config found';
+    details.push('Add *.test.js / *.spec.js or jest/vitest config');
+    fixes.push('Create test files or add jest.config.js / vitest.config.js');
+  } else if (!hasConfig) {
+    score = 50;
+    summary = 'Test files found but no framework config';
+    details.push(`${testFiles.length} test file(s), no jest/vitest/mocha config`);
+    fixes.push('Add jest.config.js, vitest.config.js, or .mocharc.js');
+  } else {
+    score = 80;
+    summary = 'Test setup detected';
+    details.push(`${testFiles.length} test file(s), config present`);
+  }
+
+  if (runTests && hasTestScript && score >= 80) {
+    try {
+      const timeout = 30000;
+      const { stdout, stderr } = await Promise.race([
+        execAsync('npm test -- --passWithNoTests 2>&1', projectPath),
+        new Promise((_, rej) => setTimeout(() => rej(new Error('Test run timed out')), timeout)),
+      ]);
+      const out = (stdout + stderr).replace(/\r\n/g, '\n');
+      if (/passed|✓|ok\s+\d+\s+test/i.test(out) && !/failed|✗|Error:/i.test(out)) {
+        score = 100;
+        summary = 'Tests pass';
+        details.push('Last run: passed');
+      } else {
+        details.push('Run: npm test (some tests may have failed)');
+        fixes.push('Fix failing tests: npm test');
+      }
+    } catch (err) {
+      details.push('Test run failed or timed out: ' + (err.message || ''));
+      fixes.push('Run: npm test');
+    }
+  }
+
+  status = score >= 80 ? 'ok' : score >= 50 ? 'warn' : 'fail';
+
+  return {
+    name: 'Tests',
+    weight: WEIGHT,
+    status,
+    score: Math.min(100, score),
+    summary,
+    details,
+    fixes,
+  };
+}

package/src/checkers/todos.js

@@ -0,0 +1,86 @@
+import scanFiles from '../utils/fileScanner.js';
+import { readFile } from 'fs/promises';
+
+const WEIGHT = 15;
+const EXTENSIONS = ['.js', '.ts', '.jsx', '.tsx', '.vue', '.py'];
+const PATTERN = /(?:^|\s)(TODO|FIXME|HACK|XXX|BUG)\s*:?/gi;
+const PENALTY = { todo: 2, fixme: 5, hack: 8, xxx: 3, bug: 6 };
+
+/**
+ * @param {string} projectPath
+ * @returns {Promise<import('./index.js').CheckerResult>}
+ */
+export default async function checkTodos(projectPath) {
+  let files;
+  try {
+    files = await scanFiles(projectPath, EXTENSIONS);
+  } catch (err) {
+    return {
+      name: 'Code Quality',
+      weight: WEIGHT,
+      status: 'error',
+      score: 0,
+      summary: 'File scan failed',
+      details: [],
+      fixes: [],
+    };
+  }
+
+  const byFile = new Map();
+  let totalDeduction = 0;
+
+  for (const filePath of files) {
+    let content;
+    try {
+      content = await readFile(filePath, 'utf-8');
+    } catch (_) {
+      continue;
+    }
+    const counts = { todo: 0, fixme: 0, hack: 0, xxx: 0, bug: 0 };
+    let m;
+    const re = new RegExp(PATTERN.source, 'gi');
+    while ((m = re.exec(content)) !== null) {
+      const key = m[1].toLowerCase();
+      if (counts[key] !== undefined) {
+        counts[key]++;
+        totalDeduction += PENALTY[key] ?? 2;
+      }
+    }
+    const total = Object.values(counts).reduce((a, b) => a + b, 0);
+    if (total > 0) {
+      const relative = filePath.replace(projectPath, '').replace(/^[/\\]/, '') || filePath;
+      byFile.set(relative, counts);
+    }
+  }
+
+  const score = Math.max(0, 100 - totalDeduction);
+  const status = score >= 80 ? 'ok' : score >= 50 ? 'warn' : 'fail';
+  const parts = [];
+  for (const [file, counts] of byFile) {
+    const segs = [];
+    if (counts.todo) segs.push(`${counts.todo} TODO(s)`);
+    if (counts.fixme) segs.push(`${counts.fixme} FIXME(s)`);
+    if (counts.hack) segs.push(`${counts.hack} HACK(s)`);
+    if (counts.xxx) segs.push(`${counts.xxx} XXX(s)`);
+    if (counts.bug) segs.push(`${counts.bug} BUG(s)`);
+    parts.push(`${file} — ${segs.join(', ')}`);
+  }
+  const totalItems = [...byFile.values()].reduce(
+    (a, c) => a + (c.todo + c.fixme + c.hack + c.xxx + c.bug),
+    0
+  );
+  const summary =
+    totalItems === 0
+      ? 'No TODO/FIXME/HACK comments found'
+      : `${totalItems} comment(s) across ${byFile.size} file(s)`;
+
+  return {
+    name: 'Code Quality',
+    weight: WEIGHT,
+    status,
+    score,
+    summary,
+    details: parts,
+    fixes: totalItems > 0 ? ['Address TODO/FIXME/HACK comments or remove them'] : [],
+  };
+}

package/src/engine.js

@@ -0,0 +1,47 @@
+import checkers from './checkers/index.js';
+
+const TIMEOUT_MS = 30000;
+
+function withTimeout(promise, ms, name) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error(`Checker "${name}" timed out after ${ms}ms`)), ms)
+    ),
+  ]);
+}
+
+/**
+ * @param {string} projectPath
+ * @param {{ skipList?: string[], runTests?: boolean }} [options]
+ * @returns {Promise<import('./checkers/index.js').CheckerResult[]>}
+ */
+export async function runEngine(projectPath, options = {}) {
+  const { skipList = [], runTests = false } = options;
+  const skipSet = new Set(skipList.map((s) => s.toLowerCase().trim()));
+
+  const toRun = checkers.filter((c) => !skipSet.has(c.name.toLowerCase()));
+
+  const results = await Promise.allSettled(
+    toRun.map(({ name, check }) => {
+      const fn = () => check(projectPath, { runTests });
+      return withTimeout(fn(), TIMEOUT_MS, name);
+    })
+  );
+
+  return results.map((settled, i) => {
+    const { name } = toRun[i];
+    if (settled.status === 'fulfilled') {
+      return settled.value;
+    }
+    return {
+      name,
+      weight: 0,
+      status: 'error',
+      score: 0,
+      summary: 'Checker failed: ' + (settled.reason?.message || 'Unknown error'),
+      details: [],
+      fixes: [],
+    };
+  });
+}

package/src/scorer.js

@@ -0,0 +1,32 @@
+/**
+ * @param {import('./checkers/index.js').CheckerResult[]} results
+ * @returns {{ score: number, grade: 'A'|'B'|'C'|'D'|'F', label: string }}
+ */
+export function calculateScore(results) {
+  const withWeight = results.filter((r) => r.status !== 'skip' && r.weight > 0);
+  const totalWeight = withWeight.reduce((sum, r) => sum + r.weight, 0);
+  if (totalWeight === 0) {
+    return { score: 0, grade: 'F', label: 'Critical' };
+  }
+  const weightedSum = withWeight.reduce((sum, r) => sum + r.score * r.weight, 0);
+  const score = Math.round(weightedSum / totalWeight);
+  const clamped = Math.max(0, Math.min(100, score));
+
+  let grade = 'F';
+  let label = 'Critical';
+  if (clamped >= 90) {
+    grade = 'A';
+    label = 'Excellent';
+  } else if (clamped >= 75) {
+    grade = 'B';
+    label = 'Good';
+  } else if (clamped >= 60) {
+    grade = 'C';
+    label = 'Fair';
+  } else if (clamped >= 45) {
+    grade = 'D';
+    label = 'Poor';
+  }
+
+  return { score: clamped, grade, label };
+}

package/src/ui/colors.js

@@ -0,0 +1,19 @@
+import chalk from 'chalk';
+
+export const colors = {
+  ok: chalk.green,
+  warn: chalk.yellow,
+  fail: chalk.red,
+  info: chalk.cyan,
+  dim: chalk.gray,
+  bold: chalk.bold,
+  title: chalk.bold.white,
+};
+
+export const gradeColors = {
+  A: chalk.green,
+  B: chalk.cyan,
+  C: chalk.yellow,
+  D: chalk.magenta,
+  F: chalk.red,
+};

package/src/ui/dashboard.js

@@ -0,0 +1,84 @@
+import boxen from 'boxen';
+import Table from 'cli-table3';
+import { colors, gradeColors } from './colors.js';
+
+const STATUS_ICONS = { ok: '✅', warn: '⚠️', fail: '❌', skip: '⏭️', error: '❌' };
+
+/**
+ * @param {{ results: import('../checkers/index.js').CheckerResult[], score: number, grade: string, label: string }} data
+ * @param {{ color?: boolean }} [opts]
+ */
+export function renderDashboard(data, opts = {}) {
+  const useColor = opts.color !== false;
+  const c = useColor ? colors : { ok: id, warn: id, fail: id, info: id, dim: id, bold: id, title: id };
+  const gc = useColor ? gradeColors : { A: id, B: id, C: id, D: id, F: id };
+  function id(x) {
+    return x;
+  }
+
+  const { results, score, grade, label } = data;
+
+  const header = [
+    '',
+    c.title('  🏥 PROJECT HEALTH REPORT  '),
+    c.bold(`  Score: ${score}/100   Grade: ${grade}  `),
+    `  Status: ${(gc[grade] || id)(label)}  `,
+    '',
+  ].join('\n');
+
+  console.log(
+    boxen(header, {
+      padding: 1,
+      margin: 1,
+      borderStyle: 'round',
+      borderColor: useColor ? 'gray' : undefined,
+    })
+  );
+
+  const table = new Table({
+    head: [c.bold('Checker'), c.bold('Score'), c.bold('Status'), c.bold('Summary')],
+    colWidths: [18, 8, 10, 44],
+    wordWrap: true,
+    style: { head: [], border: useColor ? [] : [] },
+  });
+
+  for (const r of results) {
+    const icon = STATUS_ICONS[r.status] || '  ';
+    const statusStr = `${icon} ${r.status}`;
+    const scoreStr = r.status === 'skip' ? '—' : `${r.score}`;
+    const rowColor = r.status === 'ok' ? c.ok : r.status === 'warn' ? c.warn : c.fail;
+    table.push([
+      rowColor(r.name),
+      scoreStr,
+      rowColor(statusStr),
+      rowColor(r.summary.length > 42 ? r.summary.slice(0, 39) + '...' : r.summary),
+    ]);
+  }
+  console.log(table.toString());
+
+  const nonOk = results.filter((r) => r.status !== 'ok' && r.status !== 'skip' && r.details?.length);
+  if (nonOk.length > 0) {
+    console.log(c.bold('\n  Details\n'));
+    for (const r of nonOk) {
+      console.log(c.dim(`  ${r.name}:`));
+      for (const d of r.details) {
+        console.log(c.dim('    • ' + d));
+      }
+      console.log('');
+    }
+  }
+
+  const withFixes = results.filter((r) => r.fixes?.length);
+  if (withFixes.length > 0) {
+    console.log(c.bold('  Suggested fixes\n'));
+    for (const r of withFixes) {
+      console.log(c.info(`  ${r.name}:`));
+      for (const f of r.fixes) {
+        console.log(c.dim('    ' + f));
+      }
+      console.log('');
+    }
+  }
+
+  console.log(c.dim('  Run with --json to export results.\n'));
+}

package/src/ui/spinner.js

@@ -0,0 +1,10 @@
+import ora from 'ora';
+
+/**
+ * Create a loading spinner for CLI feedback
+ * @param {string} [text] - Initial text
+ * @returns {ora.Ora}
+ */
+export function createSpinner(text = 'Loading...') {
+  return ora(text);
+}

package/src/utils/execAsync.js

@@ -0,0 +1,15 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execPromise = promisify(exec);
+
+/**
+ * Promise wrapper for child_process.exec
+ * @param {string} command - Command to execute
+ * @param {string} [cwd] - Working directory
+ * @returns {Promise<{ stdout: string, stderr: string }>}
+ */
+export default async function execAsync(command, cwd) {
+  const options = cwd ? { cwd, maxBuffer: 1024 * 1024 } : { maxBuffer: 1024 * 1024 };
+  return execPromise(command, options);
+}

package/src/utils/fileScanner.js

@@ -0,0 +1,48 @@
+import { readdir } from 'fs/promises';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);
+
+/**
+ * Recursively scan a directory for files matching given extensions.
+ * Skips node_modules, .git, dist, build, coverage.
+ * @param {string} dir - Directory to scan (absolute path)
+ * @param {string[]} extensions - File extensions to match (e.g. ['.js', '.ts'])
+ * @returns {Promise<string[]>} Array of absolute file paths
+ */
+export default async function scanFiles(dir, extensions = []) {
+  const normalizedExt = new Set(
+    extensions.map((e) => (e.startsWith('.') ? e.toLowerCase() : `.${e.toLowerCase()}`))
+  );
+  const results = [];
+
+  async function walk(currentDir) {
+    let entries;
+    try {
+      entries = await readdir(currentDir, { withFileTypes: true });
+    } catch (err) {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) {
+          await walk(fullPath);
+        }
+      } else if (entry.isFile()) {
+        const ext = entry.name.includes('.')
+          ? `.${entry.name.split('.').pop().toLowerCase()}`
+          : '';
+        if (normalizedExt.size === 0 || normalizedExt.has(ext)) {
+          results.push(fullPath);
+        }
+      }
+    }
+  }
+
+  await walk(dir);
+  return results;
+}