project-structure-enforcer

Enforce 2026 folder structure best practices with **BLOCKING** validation.

## Validation Rules

### BLOCKING Rules (exit 1)

| Rule | Check | Example Violation |
|------|-------|-------------------|
| **Max Nesting** | Max 4 levels from src/ or app/ | `src/a/b/c/d/e/file.ts` |
| **No Barrel Files** | No index.ts re-exports | `src/components/index.ts` |
| **Component Location** | React components in components/ or features/ | `src/utils/Button.tsx` |
| **Hook Location** | Custom hooks in hooks/ directory | `src/components/useAuth.ts` |
| **Import Direction** | Unidirectional: shared → features → app | `features/` importing from `app/` |

## Expected Folder Structures

### React/Next.js (Frontend)

```
src/
├── app/              # Next.js App Router (pages)
│   ├── (auth)/       # Route groups
│   ├── api/          # API routes
│   └── layout.tsx
├── components/       # Reusable UI components
│   ├── ui/           # Primitive components
│   └── forms/        # Form components
├── features/         # Feature modules (self-contained)
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── types.ts
│   └── dashboard/
├── hooks/            # Global custom hooks
├── lib/              # Third-party integrations
├── services/         # API clients
├── types/            # Global TypeScript types
└── utils/            # Pure utility functions
```

### FastAPI (Backend)

```
app/
├── routers/          # API route handlers
│   ├── router_users.py
│   ├── router_auth.py
│   └── deps.py       # Shared dependencies
├── services/         # Business logic layer
│   ├── user_service.py
│   └── auth_service.py
├── repositories/     # Data access layer
│   ├── user_repository.py
│   └── base_repository.py
├── schemas/          # Pydantic models
│   ├── user_schema.py
│   └── auth_schema.py
├── models/           # SQLAlchemy models
│   ├── user_model.py
│   └── base.py
├── core/             # Config, security, deps
│   ├── config.py
│   ├── security.py