Initial commit

2025-11-29 18:16:40 +08:00
commit f125e90b9f
370 changed files with 67769 additions and 0 deletions
--- a/skills/analysis/bulletproof-react-auditor/README.md
+++ b/skills/analysis/bulletproof-react-auditor/README.md
@@ -0,0 +1,388 @@
+# 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