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/