389 lines
11 KiB
Markdown
389 lines
11 KiB
Markdown
# Bulletproof React Auditor Skill
|
|
|
|
> Comprehensive audit tool for React/TypeScript codebases based on Bulletproof React architecture principles
|
|
|
|
An Anthropic Skill that analyzes React applications for architectural issues, component anti-patterns, state management problems, and generates prioritized migration plans for adopting Bulletproof React patterns.
|
|
|
|
## Features
|
|
|
|
- **Progressive Disclosure**: Three-phase analysis (Discovery → Deep Analysis → Migration Plan)
|
|
- **React-Specific**: Tailored for React 16.8+ (hooks-based applications)
|
|
- **Comprehensive Analysis**:
|
|
- Project Structure (feature-based vs flat)
|
|
- Component Architecture (colocation, composition, size)
|
|
- State Management (appropriate tools for each state type)
|
|
- API Layer (centralized, type-safe patterns)
|
|
- Testing Strategy (testing trophy compliance)
|
|
- Styling Patterns (component libraries, utility CSS)
|
|
- Error Handling (boundaries, interceptors, tracking)
|
|
- Performance (code splitting, memoization, optimization)
|
|
- Security (authentication, authorization, XSS prevention)
|
|
- Standards Compliance (ESLint, TypeScript, naming conventions)
|
|
- **Multiple Report Formats**: Markdown, JSON, migration roadmaps
|
|
- **Prioritized Migration Plans**: P0-P3 severity with effort estimates
|
|
- **ASCII Structure Diagrams**: Visual before/after comparisons
|
|
- **Industry Standards**: Based on Bulletproof React best practices
|
|
|
|
## Installation
|
|
|
|
### Option 1: Claude Code (Recommended)
|
|
|
|
1. Clone or copy the `bulletproof-react-auditor` directory to your Claude skills directory
|
|
2. Ensure Python 3.8+ is installed
|
|
3. No additional dependencies required (uses Python standard library)
|
|
|
|
### Option 2: Manual Installation
|
|
|
|
```bash
|
|
cd ~/.claude/skills
|
|
git clone https://github.com/your-org/bulletproof-react-auditor.git
|
|
```
|
|
|
|
## Usage with Claude Code
|
|
|
|
### Basic Audit
|
|
|
|
```
|
|
Audit this React codebase using the bulletproof-react-auditor skill.
|
|
```
|
|
|
|
### Structure-Focused Audit
|
|
|
|
```
|
|
Run a structure audit on this React app against Bulletproof React patterns.
|
|
```
|
|
|
|
### Generate Migration Plan
|
|
|
|
```
|
|
Audit this React app and generate a migration plan to Bulletproof React architecture.
|
|
```
|
|
|
|
### Custom Scope
|
|
|
|
```
|
|
Audit this React codebase focusing on:
|
|
- Project structure and feature organization
|
|
- Component architecture patterns
|
|
- State management approach
|
|
```
|
|
|
|
## Direct Script Usage
|
|
|
|
```bash
|
|
# Full audit with Markdown report
|
|
python scripts/audit_engine.py /path/to/react-app --output audit.md
|
|
|
|
# Structure-focused audit
|
|
python scripts/audit_engine.py /path/to/react-app --scope structure,components --output report.md
|
|
|
|
# Generate migration plan
|
|
python scripts/audit_engine.py /path/to/react-app --migration-plan --output migration.md
|
|
|
|
# JSON output for CI/CD integration
|
|
python scripts/audit_engine.py /path/to/react-app --format json --output audit.json
|
|
|
|
# Quick health check only (Phase 1)
|
|
python scripts/audit_engine.py /path/to/react-app --phase quick
|
|
```
|
|
|
|
## Output Formats
|
|
|
|
### Markdown (Default)
|
|
|
|
Human-readable report with:
|
|
- ASCII structure diagrams (before/after)
|
|
- Detailed findings with code examples
|
|
- Step-by-step migration guidance
|
|
- Suitable for PRs, documentation, team reviews
|
|
|
|
### JSON
|
|
|
|
Machine-readable format for CI/CD integration:
|
|
```json
|
|
{
|
|
"summary": {
|
|
"compliance_score": 72,
|
|
"grade": "C",
|
|
"critical_issues": 3,
|
|
"migration_effort_days": 15
|
|
},
|
|
"findings": [...],
|
|
"metrics": {...},
|
|
"migration_plan": [...]
|
|
}
|
|
```
|
|
|
|
### Migration Plan
|
|
|
|
Prioritized roadmap with:
|
|
- P0-P3 priority levels
|
|
- Effort estimates per task
|
|
- Dependency chains
|
|
- Before/after code examples
|
|
- ADR templates
|
|
|
|
## Audit Criteria
|
|
|
|
The skill audits based on 10 Bulletproof React categories:
|
|
|
|
### 1. Project Structure
|
|
- Feature-based organization (80%+ code in features/)
|
|
- Unidirectional dependencies (shared → features → app)
|
|
- No cross-feature imports
|
|
- Proper feature boundaries
|
|
|
|
### 2. Component Architecture
|
|
- Component colocation (near usage)
|
|
- Limited props (< 7-10 per component)
|
|
- No large components (< 300 LOC)
|
|
- No nested render functions
|
|
- Proper abstraction (identify repetition first)
|
|
|
|
### 3. State Management
|
|
- Appropriate tool for each state type
|
|
- Local state preferred over global
|
|
- Server cache separated (React Query/SWR)
|
|
- Form state managed (React Hook Form)
|
|
- URL state utilized
|
|
|
|
### 4. API Layer
|
|
- Centralized API client
|
|
- Type-safe request declarations
|
|
- Colocated in features/
|
|
- Data fetching hooks
|
|
- Error handling
|
|
|
|
### 5. Testing Strategy
|
|
- Testing trophy (70% integration, 20% unit, 10% E2E)
|
|
- Semantic queries (getByRole preferred)
|
|
- User behavior testing (not implementation)
|
|
- 80%+ coverage on critical paths
|
|
|
|
### 6. Styling Patterns
|
|
- Consistent approach (component library or utility CSS)
|
|
- Colocated styles
|
|
- Design system usage
|
|
|
|
### 7. Error Handling
|
|
- API error interceptors
|
|
- Multiple error boundaries
|
|
- Error tracking service
|
|
- User-friendly messages
|
|
|
|
### 8. Performance
|
|
- Code splitting at routes
|
|
- Memoization patterns
|
|
- State localization
|
|
- Image optimization
|
|
- Bundle size monitoring
|
|
|
|
### 9. Security
|
|
- JWT with HttpOnly cookies
|
|
- Authorization (RBAC/PBAC)
|
|
- Input sanitization
|
|
- XSS prevention
|
|
|
|
### 10. Standards Compliance
|
|
- ESLint configured
|
|
- TypeScript strict mode
|
|
- Prettier setup
|
|
- Git hooks (Husky)
|
|
- Absolute imports
|
|
- Kebab-case naming
|
|
|
|
See [`reference/audit_criteria.md`](reference/audit_criteria.md) for complete checklist.
|
|
|
|
## Severity Levels
|
|
|
|
- **Critical (P0)**: Fix immediately (within 24 hours)
|
|
- Security vulnerabilities, breaking architectural patterns
|
|
|
|
- **High (P1)**: Fix this sprint (within 2 weeks)
|
|
- Major architectural violations, significant refactoring needed
|
|
|
|
- **Medium (P2)**: Fix next quarter (within 3 months)
|
|
- Component design issues, state management improvements
|
|
|
|
- **Low (P3)**: Backlog
|
|
- Styling consistency, minor optimizations
|
|
|
|
See [`reference/severity_matrix.md`](reference/severity_matrix.md) for detailed criteria.
|
|
|
|
## Migration Approach
|
|
|
|
### Phase 1: Foundation (Week 1-2)
|
|
1. Create feature folders structure
|
|
2. Move shared utilities to proper locations
|
|
3. Set up absolute imports
|
|
4. Configure ESLint for architecture rules
|
|
|
|
### Phase 2: Feature Extraction (Week 3-6)
|
|
1. Identify feature boundaries
|
|
2. Move components to features/
|
|
3. Colocate API calls with features
|
|
4. Extract feature-specific state
|
|
|
|
### Phase 3: Refinement (Week 7-10)
|
|
1. Refactor large components
|
|
2. Implement proper state management
|
|
3. Add error boundaries
|
|
4. Optimize performance
|
|
|
|
### Phase 4: Polish (Week 11-12)
|
|
1. Improve test coverage
|
|
2. Add documentation
|
|
3. Implement remaining patterns
|
|
4. Final review
|
|
|
|
## Examples
|
|
|
|
See the [`examples/`](examples/) directory for:
|
|
- Sample audit report (React app before Bulletproof)
|
|
- Complete migration plan with timeline
|
|
- Before/after structure comparisons
|
|
- Code transformation examples
|
|
|
|
## Architecture
|
|
|
|
```
|
|
bulletproof-react-auditor/
|
|
├── SKILL.md # Skill definition (Claude loads this)
|
|
├── README.md # This file
|
|
├── scripts/
|
|
│ ├── audit_engine.py # Core orchestrator
|
|
│ ├── analyzers/ # Specialized analyzers
|
|
│ │ ├── project_structure.py # Folder organization
|
|
│ │ ├── component_architecture.py # Component patterns
|
|
│ │ ├── state_management.py # State analysis
|
|
│ │ ├── api_layer.py # API patterns
|
|
│ │ ├── testing_strategy.py # Test quality
|
|
│ │ ├── styling_patterns.py # Styling approach
|
|
│ │ ├── error_handling.py # Error boundaries
|
|
│ │ ├── performance_patterns.py # React performance
|
|
│ │ ├── security_practices.py # React security
|
|
│ │ └── standards_compliance.py # ESLint, TS, Prettier
|
|
│ ├── report_generator.py # Multi-format reports
|
|
│ └── migration_planner.py # Prioritized roadmaps
|
|
├── reference/
|
|
│ ├── bulletproof_principles.md # Complete BR guide
|
|
│ ├── audit_criteria.md # Full checklist
|
|
│ ├── severity_matrix.md # Issue prioritization
|
|
│ └── migration_patterns.md # Common refactorings
|
|
└── examples/
|
|
├── sample_audit_report.md
|
|
├── migration_plan.md
|
|
└── before_after_structure.md
|
|
```
|
|
|
|
## Extending the Skill
|
|
|
|
### Adding a New Analyzer
|
|
|
|
1. Create `scripts/analyzers/your_analyzer.py`
|
|
2. Implement `analyze(codebase_path, metadata)` function
|
|
3. Add to `ANALYZERS` dict in `audit_engine.py`
|
|
|
|
Example:
|
|
```python
|
|
def analyze(codebase_path: Path, metadata: Dict) -> List[Dict]:
|
|
"""Analyze specific Bulletproof React pattern."""
|
|
findings = []
|
|
|
|
# Your analysis logic here
|
|
|
|
findings.append({
|
|
'severity': 'high',
|
|
'category': 'your_category',
|
|
'title': 'Issue title',
|
|
'current_state': 'What exists now',
|
|
'target_state': 'Bulletproof recommendation',
|
|
'migration_steps': ['Step 1', 'Step 2'],
|
|
'effort': 'medium',
|
|
})
|
|
|
|
return findings
|
|
```
|
|
|
|
## CI/CD Integration
|
|
|
|
### GitHub Actions Example
|
|
|
|
```yaml
|
|
name: Bulletproof React Audit
|
|
|
|
on: [pull_request]
|
|
|
|
jobs:
|
|
audit:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- name: Run Bulletproof Audit
|
|
run: |
|
|
python bulletproof-react-auditor/scripts/audit_engine.py . \
|
|
--format json \
|
|
--output audit-report.json
|
|
- name: Check Compliance Score
|
|
run: |
|
|
SCORE=$(jq '.summary.compliance_score' audit-report.json)
|
|
if [ "$SCORE" -lt 70 ]; then
|
|
echo "❌ Compliance score $SCORE below threshold (70)"
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Audit Before Major Refactoring**: Establish baseline before starting
|
|
2. **Incremental Migration**: Don't refactor everything at once
|
|
3. **Feature-by-Feature**: Migrate one feature at a time
|
|
4. **Test Coverage First**: Ensure tests before restructuring
|
|
5. **Team Alignment**: Share Bulletproof React principles with team
|
|
6. **Document Decisions**: Create ADRs for architectural changes
|
|
7. **Track Progress**: Re-run audits weekly to measure improvement
|
|
|
|
## Connor's Standards Integration
|
|
|
|
This skill enforces Connor's specific requirements:
|
|
- **TypeScript Strict Mode**: No `any` types allowed
|
|
- **Test Coverage**: 80%+ minimum on all code
|
|
- **Testing Trophy**: 70% integration, 20% unit, 10% E2E
|
|
- **Modern Testing**: Semantic queries (getByRole) preferred
|
|
- **No Brittle Tests**: Avoid testing implementation details
|
|
- **Code Quality**: No console.log, no `var`, strict equality
|
|
- **Git Standards**: Conventional commits, proper branch naming
|
|
|
|
## Limitations
|
|
|
|
- Static analysis only (no runtime profiling)
|
|
- React 16.8+ required (hooks-based)
|
|
- Best suited for SPA/SSG patterns
|
|
- Next.js apps may have additional patterns
|
|
- Large codebases may need scoped analysis
|
|
- Does not execute tests (analyzes test files)
|
|
|
|
## Version
|
|
|
|
**1.0.0** - Initial release
|
|
|
|
## Standards Compliance
|
|
|
|
Based on:
|
|
- Bulletproof React Official Guide
|
|
- Kent C. Dodds Testing Trophy
|
|
- React Best Practices 2024-25
|
|
- TypeScript Strict Mode Guidelines
|
|
- Connor's Development Standards
|
|
|
|
## License
|
|
|
|
Apache 2.0 (example skill for demonstration)
|
|
|
|
---
|
|
|
|
**Built with**: Python 3.8+
|
|
**Anthropic Skill Version**: 1.0
|
|
**Last Updated**: 2024-10-25
|
|
**Bulletproof React Version**: Based on v2024 guidelines
|