project-health-check

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.