---
description: "Code Standards & Quality"
globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
alwaysApply: false
---

# Code Standards for Roadcrew

All code must follow these standards without exception.

## TypeScript & Type Safety

- **No bare `any`** — explicitly type all parameters and returns
- **Explicit return types on ALL functions** — use `Function` only as absolute last resort
- **Always use optional chaining** — `obj?.prop` instead of `obj && obj.prop`
- **Await all Promises** — never ignore async operations
```typescript
// ✅ GOOD
export function parseConfig(data: unknown): Config | null {
  if (!data) return null;
  return data as Config;
}

// ❌ BAD - bare any, no return type
export function parseConfig(data: any) {
  if (data) return data;
}
```

## Error Handling

- **Throw meaningful errors** with context, never silent failures
- **Use custom error classes** for different failure modes
- **Always log stack traces** for debugging
```typescript
// ✅ GOOD
class ValidationError extends Error {
  constructor(message: string, public field: string) {
    super(`Validation failed on '${field}': ${message}`);
  }
}

// ❌ BAD - silent failure
if (!valid) return false;
```

## Code Organization

- **One responsibility per function**
- **Keep functions under 30 lines** (refactor if longer)
- **Use descriptive names** — avoid `tmp`, `x`, `getData`
- **Import organization**: external → internal → types

## Performance

- **Avoid N+1 queries** — batch operations
- **Cache computed values** (ttl-based, not indefinite)
- **Profile before optimizing** — measure first
- **Lazy load large dependencies**

## Related Rules

- **Documentation standards:** See `05-documentation.mdc`
- **Testing requirements:** See `06-testing.mdc`
- **GitHub operations:** See `03-github.mdc`

## Code Review Checklist

All PRs must pass these checks:
- ❌ Bare `any` types
- ❌ Missing return types
- ❌ Silent error handling
- ❌ Functions over 30 lines
- ❌ Untested code (see `04-testing.mdc`)
- ❌ Missing JSDoc on exports (see `03-documentation.mdc`)