Bulletproof React Auditor

Audits React/TypeScript codebases against Bulletproof React architecture with migration planning.

When to Use

Natural Language Triggers (semantic matching, not keywords):

• Questions about React project structure or organization
• Mentions of "bulletproof react" or feature-based architecture
• Requests to audit, review, or improve React codebase
• Planning migrations or refactoring React applications
• Seeking guidance on component patterns or folder structure

Use Cases:

• Setting up new React project structure
• Reorganizing existing flat codebase
• Auditing architecture against Bulletproof standards
• Planning migration to feature-based patterns
• Code review for structural anti-patterns
• Generating refactoring guidance and ADRs

Bulletproof Structure Target

src/
├── app/           # Routes, providers
├── components/    # Shared components ONLY
├── config/        # Global config
├── features/      # Feature modules (most code)
│   └── feature/
│       ├── api/
│       ├── components/
│       ├── hooks/
│       ├── stores/
│       └── types/
├── hooks/         # Shared hooks
├── lib/           # Third-party configs
├── stores/        # Global state
├── testing/       # Test utilities
├── types/         # Shared types
└── utils/         # Shared utilities

Audit Categories

Usage Examples

# Basic audit
Audit this React codebase using bulletproof-react-auditor.

# Structure focus
Run structure audit against Bulletproof React patterns.

# Migration plan
Generate migration plan to Bulletproof architecture.

# Custom scope
Audit focusing on structure, components, and state management.

Output Formats

1. Markdown Report - ASCII diagrams, code examples
2. JSON Report - Machine-readable for CI/CD
3. Migration Plan - Roadmap with effort estimates

Priority Levels

Connor's Standards Enforced

• TypeScript strict mode (no any)
• 80%+ test coverage
• Testing trophy: 70% integration, 20% unit, 10% E2E
• No console.log in production
• Semantic queries (getByRole preferred)

Best Practices

1. Fix folder organization before component refactoring
2. Extract features before other changes
3. Maintain test coverage during migration
4. Incremental migration, not all at once
5. Document decisions with ADRs

Limitations

• Static analysis only
• Requires React 16.8+ (hooks)
• Best for SPA/SSG (Next.js differs)
• Large codebases need scoped analysis

Resources

• Bulletproof React Guide
• Project Structure
• Sample App

References

See reference/ for:

• Complete Bulletproof principles guide
• Detailed audit criteria checklist
• Migration patterns and examples
• ADR templates