project-health-auditor

Project Health Auditor

Inspired by claude-code-plugins-plus

Purpose

Analyze codebase health across multiple dimensions: code quality, dependencies, security, testing, documentation, and architecture.

Audit Categories

1. Code Quality

Complexity Analysis

# Count lines per file (identify large files)
find src -name "*.ts" -o -name "*.js" | xargs wc -l | sort -n

# Find long functions (over 50 lines)
# Check for deeply nested code
# Identify duplicate code patterns

Code Smells

| Smell | Indicator | Action | |-------|-----------|--------| | Long files | >500 lines | Split into modules | | Long functions | >50 lines | Extract methods | | Deep nesting | >4 levels | Flatten logic | | Many parameters | >5 params | Use objects | | Duplicate code | Similar blocks | Extract shared | | Dead code | Unused exports | Remove | | Magic numbers | Hardcoded values | Use constants |

Checklist

## Code Quality Audit
- [ ] No files over 500 lines
- [ ] No functions over 50 lines
- [ ] No nesting deeper than 4 levels
- [ ] No functions with >5 parameters
- [ ] No obvious code duplication
- [ ] No dead/unused code
- [ ] Consistent naming conventions
- [ ] Proper error handling

2. Dependencies

Dependency Health

# Check outdated packages (npm)
npm outdated

# Check for vulnerabilities
npm audit

# Analyze bundle size
npx webpack-bundle-analyzer

# Check unused dependencies
npx depcheck

Evaluation Criteria

| Metric | Healthy | Warning | Critical | |--------|---------|---------|----------| | Outdated (major) | 0 | 1-3 | >3 | | Outdated (minor) | <5 | 5-10 | >10 | | Vulnerabilities | 0 | Low/Med | High/Crit | | Unused deps | 0 | 1-3 | >3 | | Bundle size | <500KB | 500KB-1MB | >1MB |

Checklist

## Dependencies Audit
- [ ] No critical vulnerabilities
- [ ] No high vulnerabilities
- [ ] <3 major version updates pending
- [ ] No unused dependencies
- [ ] Lock file in sync
- [ ] Bundle size reasonable

3. Security

Security Checks

# Check for secrets in code
grep -r "password\|secret\|api_key\|token" --include="*.ts" --include="*.js"

# Check for hardcoded credentials
grep -r "Bearer \|Basic " --include="*.ts"

# Check .env is gitignored
cat .gitignore | grep ".env"

Security Audit Points

| Check | Concern | Solution | |-------|---------|----------| | Secrets in code | Credential exposure | Use env vars | | .env committed | Secret leak | Add to .gitignore | | SQL strings | SQL injection | Use parameterized queries | | User input in HTML | XSS | Sanitize/escape | | Outdated deps | Known vulns | Update regularly | | No rate limiting | DoS | Add rate limits | | No input validation | Injection | Validate all inputs |

Checklist

## Security Audit
- [ ] No hardcoded secrets
- [ ] .env files gitignored
- [ ] Dependencies scanned for vulns
- [ ] Input validation in place
- [ ] Output encoding for XSS
- [ ] SQL injection prevention
- [ ] Authentication implemented
- [ ] Authorization checks exist

4. Testing

Test Coverage Analysis

# Run tests with coverage (npm/jest)
npm test -- --coverage

# Run tests with coverage (pytest)
pytest --cov=src --cov-report=html

Coverage Standards

| Metric | Good | Acceptable | Poor | |--------|------|------------|------| | Line coverage | >80% | 60-80% | <60% | | Branch coverage | >70% | 50-70% | <50% | | Function coverage | >80% | 60-80% | <60% |

Checklist

## Testing Audit
- [ ] Unit tests exist
- [ ] Integration tests exist
- [ ] Line coverage >60%
- [ ] Critical paths tested
- [ ] Edge cases covered
- [ ] Tests run in CI
- [ ] Test execution <5 min
- [ ] No flaky tests

5. Documentation

Documentation Inventory

# Check for README
ls README.md

# Check for API docs
ls docs/ || ls documentation/

# Check for inline docs (JSDoc, docstrings)
grep -r "@param\|@returns\|Args:\|Returns:" src/

Documentation Standards

| Doc Type | Purpose | Required | |----------|---------|----------| | README.md | Project overview | Always | | CONTRIBUTING.md | Contribution guide | Open source | | API docs | Endpoint reference | APIs | | Code comments | Complex logic | As needed | | Architecture docs | System design | Large projects | | CHANGELOG.md | Version history | Libraries |

Checklist

## Documentation Audit
- [ ] README exists and current
- [ ] Installation instructions
- [ ] Usage examples
- [ ] API documentation
- [ ] Contributing guide
- [ ] License specified
- [ ] Complex code documented

6. Architecture

Architecture Review

| Aspect | Check | Concern | |--------|-------|---------| | Coupling | Import chains | Tight coupling | | Cohesion | Module size | God modules | | Layers | Directory structure | Layer violations | | Dependencies | Package.json | Circular deps | | Config | Hardcoded values | Environment issues |

Common Issues

## Architecture Smells
- Circular dependencies
- God classes/modules
- Feature envy (cross-module reaching)
- Shotgun surgery (changes touch many files)
- Inappropriate intimacy (modules know too much)

Checklist

## Architecture Audit
- [ ] Clear module boundaries
- [ ] No circular dependencies
- [ ] Proper layer separation
- [ ] Configuration externalized
- [ ] Environment-specific settings
- [ ] Scalability considered
- [ ] Single responsibility

Health Report Template

# Project Health Report

**Project:** [Name]
**Date:** [Date]
**Auditor:** Claude

## Summary

| Category | Score | Status |
|----------|-------|--------|
| Code Quality | X/10 | 🟢/🟡/🔴 |
| Dependencies | X/10 | 🟢/🟡/🔴 |
| Security | X/10 | 🟢/🟡/🔴 |
| Testing | X/10 | 🟢/🟡/🔴 |
| Documentation | X/10 | 🟢/🟡/🔴 |
| Architecture | X/10 | 🟢/🟡/🔴 |
| **Overall** | **X/10** | **Status** |

## Critical Issues (Fix Immediately)
1. [Issue description]
2. [Issue description]

## High Priority (Fix Soon)
1. [Issue description]
2. [Issue description]

## Recommendations
1. [Recommendation]
2. [Recommendation]

## Technical Debt
- [Debt item with estimated effort]
- [Debt item with estimated effort]

Quick Commands

# Full audit script
echo "=== Code Stats ===" && cloc src/
echo "=== Dependencies ===" && npm outdated
echo "=== Security ===" && npm audit
echo "=== Test Coverage ===" && npm test -- --coverage
echo "=== TODO/FIXME ===" && grep -r "TODO\|FIXME" src/