gh-cskiro-claudex/skills/analysis/bulletproof-react-auditor/README.md

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

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

# 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:

{
  "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 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 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/ 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:

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

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