---
name: project-health-check
description: Run a comprehensive project health check covering dependencies, configuration, security, testing, and build integrity. Outputs a graded report card with actionable recommendations.
---

# Project Health Check

Run a full diagnostic on the current project and produce a graded health report.

## Steps

### 1. Detect Project Type

Identify the project ecosystem by checking for:

```
ls package.json pyproject.toml Cargo.toml go.mod pom.xml Gemfile
```

This skill focuses primarily on Node.js/TypeScript projects but adapts the checks as needed. Read `package.json` (or equivalent) to understand the project.

### 2. Run All Checks

Execute each check below. Record the result as PASS, WARN, or FAIL with details.

---

#### Check 1: Package Configuration

Read `package.json` and verify:

| Item | PASS | WARN | FAIL |
|------|------|------|------|
| `name` field | Present and valid | Missing or `unnamed` | - |
| `version` field | Follows semver | Present but not semver | Missing |
| `description` | Present, >10 chars | Present but short | Missing |
| `main` or `exports` | Points to existing file | Present but file missing | Missing for library |
| `scripts.start` | Present | - | Missing |
| `scripts.test` | Present and not `echo "Error..."` | Present but placeholder | Missing |
| `scripts.build` | Present (if TS/compiled) | - | Missing when needed |
| `scripts.lint` | Present | - | Missing |
| `engines` | Node version specified | - | Missing |
| `license` | Present | `UNLICENSED` | Missing |
| `private` | Set for apps | - | Missing for non-published apps |

Run `npm outdated 2>/dev/null || true` and check for outdated dependencies:
- PASS: All up to date or only minor updates
- WARN: Major version updates available
- FAIL: Dependencies with known vulnerabilities

Run `npm audit --json 2>/dev/null || true` if available:
- PASS: No vulnerabilities
- WARN: Low/moderate vulnerabilities
- FAIL: High/critical vulnerabilities

#### Check 2: Environment Configuration

```
ls -la .env .env.example .env.local .env.development .env.production 2>/dev/null
```

| Item | PASS | WARN | FAIL |
|------|------|------|------|
| `.env.example` exists | Yes | - | No, but `.env` exists |
| `.env` in `.gitignore` | Yes | - | No |
| `.env.example` matches `.env` | All keys present | Some keys missing | Major mismatch |

If both `.env` and `.env.example` exist, compare their keys (not values):
```
grep -oP '^[A-Z_]+=?' .env | sort
grep -oP '^[A-Z_]+=?' .env.example | sort
```

Check for secrets accidentally committed:
```
git log --all --diff-filter=A -- '*.env' '.env.*' 2>/dev/null
grep -rn "sk-\|sk_live\|AKIA\|-----BEGIN.*KEY" src/ lib/ app/ --include="*.ts" --include="*.js" --include="*.json" 2>/dev/null
```

#### Check 3: Essential Files

Check for the presence and quality of standard project files:

| File | PASS | WARN | FAIL |
|------|------|------|------|
| `README.md` | Exists, >500 chars, has install/usage sections | Exists but minimal | Missing |
| `.gitignore` | Exists, covers `node_modules`, `.env`, build output | Exists but incomplete | Missing |
| `LICENSE` or `LICENSE.md` | Exists | - | Missing (for open source) |
| `tsconfig.json` | Exists with `strict: true` (if TS) | Exists but not strict | Missing (if TS files present) |
| `.eslintrc*` or `eslint.config.*` | Exists | - | Missing |
| `.prettierrc*` or in `package.json` | Exists | - | Missing |
| `Dockerfile` | Exists (if deploy target) | - | Not checked |
| `.dockerignore` | Exists (if Dockerfile) | - | Missing (if Dockerfile) |
| `CI config` (`.github/workflows/`, `.gitlab-ci.yml`) | Exists | - | Missing |

#### Check 4: Code Quality & Linting

If a linter is configured, run it:
```
npx eslint . --max-warnings=0 2>/dev/null || npm run lint 2>/dev/null
```

- PASS: No errors or warnings
- WARN: Warnings only
- FAIL: Errors present

Check TypeScript compilation (if applicable):
```
npx tsc --noEmit 2>/dev/null
```

- PASS: No type errors
- WARN: -
- FAIL: Type errors found

#### Check 5: Testing

Detect the test framework and check coverage:

```
ls jest.config* vitest.config* .mocharc* karma.conf* 2>/dev/null
find . -name "*.test.*" -o -name "*.spec.*" | head -20
```

| Item | PASS | WARN | FAIL |
|------|------|------|------|
| Test framework configured | Yes | - | No |
| Test files exist | >5 test files | 1-5 test files | 0 test files |
| Tests pass | All pass | Some skip | Failures |
| Coverage | >80% | 50-80% | <50% or not configured |

Run tests if configured (with a timeout):
```
timeout 120 npm test 2>&1 || true
```

If coverage is available:
```
npx vitest run --coverage 2>/dev/null || npx jest --coverage 2>/dev/null || true
```

#### Check 6: Build Verification

If a build script exists, try it:
```
timeout 120 npm run build 2>&1 || true
```

- PASS: Build succeeds with no warnings
- WARN: Build succeeds with warnings
- FAIL: Build fails

Check that build output exists and is gitignored:
```
ls dist/ build/ out/ .next/ 2>/dev/null
grep -q "dist\|build\|out\|\.next" .gitignore 2>/dev/null
```

#### Check 7: Security Baseline

| Item | PASS | WARN | FAIL |
|------|------|------|------|
| No secrets in source | Clean | - | Secrets found |
| `npm audit` clean | No high/critical | Low/moderate only | High/critical present |
| Helmet/CORS configured (if server) | Yes | Partial | No |
| Input validation present | Yes (Zod/Joi/etc.) | Manual validation | None found |
| Auth middleware exists (if API) | Yes | - | No (if routes exist) |

#### Check 8: Documentation Quality

| Item | PASS | WARN | FAIL |
|------|------|------|------|
| README has install instructions | Yes | - | No |
| README has usage/API docs | Yes | - | No |
| API endpoints documented | Yes (OpenAPI/JSDoc) | Partial | No |
| Code comments on complex logic | Present | Sparse | None |
| CHANGELOG exists | Yes | - | No (for published packages) |

### 3. Generate the Health Report

Output the report in this format:

```
# Project Health Report

**Project**: <name from package.json>
**Version**: <version>
**Date**: <current date>
**Runtime**: Node.js <detected version>

## Report Card

| # | Check                    | Status | Details |
|---|--------------------------|--------|---------|
| 1 | Package Configuration    | PASS   | All fields present, deps up to date |
| 2 | Environment Config       | WARN   | .env.example missing 2 keys |
| 3 | Essential Files          | PASS   | All standard files present |
| 4 | Code Quality & Linting   | FAIL   | 3 ESLint errors found |
| 5 | Testing                  | WARN   | 62% coverage (target: 80%) |
| 6 | Build                    | PASS   | Builds successfully |
| 7 | Security                 | PASS   | No vulnerabilities found |
| 8 | Documentation            | WARN   | Missing API documentation |

## Overall Grade: B+

Grading scale:
- A+: All PASS
- A:  All PASS, 1 WARN
- B+: All PASS/WARN, no FAIL, <=3 WARN
- B:  All PASS/WARN, no FAIL
- C:  1 FAIL
- D:  2 FAIL
- F:  3+ FAIL

## Critical Issues (Fix Now)

1. **[FAIL] Code Quality**: 3 ESLint errors in src/utils/parser.ts
   - Fix: Run `npx eslint src/utils/parser.ts --fix`

## Recommendations (Improve Later)

1. **[WARN] Environment**: Add missing keys to .env.example: `REDIS_URL`, `LOG_LEVEL`
2. **[WARN] Testing**: Increase coverage from 62% to 80%. Untested files:
   - src/services/payment.service.ts (0%)
   - src/utils/crypto.ts (0%)
3. **[WARN] Documentation**: Add API docs using JSDoc or OpenAPI spec

## What's Good

- Clean dependency audit
- TypeScript strict mode enabled
- CI pipeline configured
- Build output properly gitignored
```

### 4. Offer Quick Fixes

After the report, offer to automatically fix what can be fixed:

> I can automatically fix the following issues:
> 1. Create `.env.example` from current `.env` (keys only)
> 2. Run `npx eslint --fix` to auto-fix lint errors
> 3. Add missing entries to `.gitignore`
> 4. Add missing `package.json` fields
>
> Want me to fix any of these? (all / pick numbers / skip)

Apply requested fixes, then re-run the affected checks to confirm they now pass.

## Edge Cases

- **Monorepo**: If `workspaces` is detected in `package.json` or `lerna.json` / `pnpm-workspace.yaml` exists, run checks on each workspace package and aggregate results.
- **No package.json**: Report as FAIL for check 1 and adapt remaining checks. Ask the user what type of project this is.
- **CI environment**: Skip interactive prompts and output the report as plain text.
- **Very large projects**: Set timeouts on test and build commands. If they exceed 2 minutes, report as "SKIPPED (timeout)" rather than failing.