codecruise 0.1.0

package/config/agents/stack/shared-ts/rules/critical.md

@@ -0,0 +1,315 @@
+# Critical Rules - TypeScript
+
+Must-follow rules for type safety. Violations block PR merge.
+
+---
+
+## Strict Mode
+
+### TS-001: Enable all strict flags
+
+```json
+// tsconfig.json - REQUIRED settings
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "forceConsistentCasingInFileNames": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+### TS-002: Never use `any`
+
+```typescript
+// BAD
+function process(data: any) { ... }
+const result = response as any;
+
+// GOOD
+function process(data: unknown) {
+  if (isValidData(data)) { ... }
+}
+
+// If truly unknown, use unknown and narrow
+function parseJson(text: string): unknown {
+  return JSON.parse(text);
+}
+```
+
+### TS-003: Never use non-null assertion carelessly
+
+```typescript
+// BAD - crashes if undefined
+const user = users.find(u => u.id === id)!;
+const name = user.name!;
+
+// GOOD - handle undefined
+const user = users.find(u => u.id === id);
+if (!user) throw new NotFoundError('User');
+
+// Or with nullish coalescing
+const name = user.name ?? 'Unknown';
+```
+
+---
+
+## Type Safety
+
+### TS-004: Prefer explicit return types for public APIs
+
+```typescript
+// BAD - inferred types can change unexpectedly
+export function getUser(id: string) {
+  return db.user.findUnique({ where: { id } });
+}
+
+// GOOD - explicit contract
+export function getUser(id: string): Promise<User | null> {
+  return db.user.findUnique({ where: { id } });
+}
+```
+
+### TS-005: Use const assertions for literals
+
+```typescript
+// BAD - type is string[]
+const statuses = ['pending', 'active', 'done'];
+
+// GOOD - type is readonly ['pending', 'active', 'done']
+const statuses = ['pending', 'active', 'done'] as const;
+
+// Useful for type derivation
+type Status = typeof statuses[number]; // 'pending' | 'active' | 'done'
+```
+
+### TS-006: Avoid type assertions except for narrowing
+
+```typescript
+// BAD - bypasses type checking
+const user = response as User;
+
+// GOOD - validate first
+const user = userSchema.parse(response);
+
+// OK - narrowing after check
+if (isUser(response)) {
+  const user = response; // Type is narrowed
+}
+
+// OK - when TypeScript can't infer
+const element = document.getElementById('root') as HTMLDivElement | null;
+```
+
+---
+
+## Null Safety
+
+### TS-007: Handle all nullable values
+
+```typescript
+// BAD - might be undefined
+const items = data.items.map(i => i.name);
+
+// GOOD - check first
+const items = data.items?.map(i => i.name) ?? [];
+
+// Or throw if required
+if (!data.items) throw new Error('Items required');
+const items = data.items.map(i => i.name);
+```
+
+### TS-008: Use noUncheckedIndexedAccess
+
+```typescript
+// With noUncheckedIndexedAccess: true
+
+const arr = [1, 2, 3];
+const first = arr[0]; // Type is number | undefined
+
+// Must handle
+if (first !== undefined) {
+  console.log(first + 1);
+}
+
+// Or use at() with check
+const last = arr.at(-1);
+if (last !== undefined) { ... }
+```
+
+### TS-009: Distinguish null vs undefined
+
+```typescript
+// null = intentionally empty
+// undefined = not set
+
+interface User {
+  name: string;
+  nickname: string | null;    // User chose no nickname
+  deletedAt?: Date;           // Not deleted = undefined
+}
+
+// Check appropriately
+if (user.nickname === null) {
+  // User explicitly has no nickname
+}
+
+if (user.deletedAt === undefined) {
+  // User is not deleted
+}
+```
+
+---
+
+## Imports & Exports
+
+### TS-010: Use type imports for types
+
+```typescript
+// BAD - imports at runtime
+import { User, UserService } from './user';
+
+// GOOD - type-only imports
+import type { User } from './user';
+import { UserService } from './user';
+
+// Or combined
+import { UserService, type User } from './user';
+```
+
+### TS-011: Export types alongside values
+
+```typescript
+// BAD - types not exported
+const userSchema = z.object({ ... });
+// User type only available internally
+
+// GOOD - export both
+export const userSchema = z.object({ ... });
+export type User = z.infer<typeof userSchema>;
+```
+
+### TS-012: Use barrel exports carefully
+
+```typescript
+// index.ts
+export { userSchema, type User } from './user';
+export { orderSchema, type Order } from './order';
+
+// Avoid re-exporting everything
+// BAD - pulls in everything
+export * from './user';
+export * from './order';
+
+// GOOD - explicit exports
+export { User, userSchema, createUser } from './user';
+```
+
+---
+
+## Async Safety
+
+### TS-013: Always handle Promise rejections
+
+```typescript
+// BAD - unhandled rejection
+someAsyncFunction();
+
+// GOOD - handle or await
+await someAsyncFunction();
+
+// Or with catch
+someAsyncFunction().catch(handleError);
+
+// In event handlers
+button.addEventListener('click', async () => {
+  try {
+    await handleClick();
+  } catch (error) {
+    showError(error);
+  }
+});
+```
+
+### TS-014: Type async function returns
+
+```typescript
+// BAD
+async function fetchUser(id: string) {
+  const response = await fetch(`/users/${id}`);
+  return response.json();
+}
+
+// GOOD
+async function fetchUser(id: string): Promise<User> {
+  const response = await fetch(`/users/${id}`);
+  const data = await response.json();
+  return userSchema.parse(data);
+}
+```
+
+---
+
+## Error Handling
+
+### TS-015: Use typed errors
+
+```typescript
+// Define error types
+class AppError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode: number = 500
+  ) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(resource: string, id?: string) {
+    super(
+      id ? `${resource} ${id} not found` : `${resource} not found`,
+      'NOT_FOUND',
+      404
+    );
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(
+    message: string,
+    public details: Array<{ field: string; message: string }>
+  ) {
+    super(message, 'VALIDATION_ERROR', 400);
+  }
+}
+```
+
+### TS-016: Narrow unknown errors
+
+```typescript
+// BAD
+try { ... } catch (e) {
+  console.log(e.message); // e is unknown
+}
+
+// GOOD
+try { ... } catch (e) {
+  if (e instanceof Error) {
+    console.log(e.message);
+  } else {
+    console.log('Unknown error', e);
+  }
+}
+
+// Or use a helper
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  return 'Unknown error';
+}
+```

package/config/agents/stack/shared-ts/rules/patterns.md

@@ -0,0 +1,384 @@
+# TypeScript Patterns
+
+Common patterns for clean, type-safe code.
+
+---
+
+## Utility Types
+
+### PAT-001: Use built-in utility types
+
+```typescript
+// Partial - all properties optional
+type UpdateUser = Partial<User>;
+
+// Required - all properties required
+type CompleteUser = Required<User>;
+
+// Pick - subset of properties
+type UserCredentials = Pick<User, 'email' | 'password'>;
+
+// Omit - exclude properties
+type PublicUser = Omit<User, 'password' | 'hashedPassword'>;
+
+// Record - object with known keys
+type StatusMap = Record<OrderStatus, string>;
+
+// Readonly - immutable
+type FrozenConfig = Readonly<Config>;
+```
+
+### PAT-002: Create custom utility types
+
+```typescript
+// Make specific keys optional
+type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+type CreateUser = PartialBy<User, 'id' | 'createdAt'>;
+
+// Make specific keys required
+type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+type UserWithEmail = RequiredBy<PartialUser, 'email'>;
+
+// Deep partial
+type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+```
+
+### PAT-003: Extract types from existing code
+
+```typescript
+// From function return
+type UserResult = Awaited<ReturnType<typeof getUser>>;
+
+// From array element
+type OrderItem = Order['items'][number];
+
+// From object values
+const STATUS = { pending: 1, active: 2, done: 3 } as const;
+type StatusKey = keyof typeof STATUS; // 'pending' | 'active' | 'done'
+type StatusValue = typeof STATUS[StatusKey]; // 1 | 2 | 3
+
+// From Zod schema
+type User = z.infer<typeof userSchema>;
+```
+
+---
+
+## Discriminated Unions
+
+### PAT-004: Model state with discriminated unions
+
+```typescript
+// Instead of optional flags
+// BAD
+interface Request {
+  status: 'loading' | 'success' | 'error';
+  data?: User;
+  error?: Error;
+  isLoading?: boolean;
+}
+
+// GOOD - discriminated union
+type RequestState<T> =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: T }
+  | { status: 'error'; error: Error };
+
+// Usage with exhaustive checking
+function render(state: RequestState<User>) {
+  switch (state.status) {
+    case 'idle':
+      return <Placeholder />;
+    case 'loading':
+      return <Spinner />;
+    case 'success':
+      return <UserCard user={state.data} />;
+    case 'error':
+      return <Error message={state.error.message} />;
+  }
+}
+```
+
+### PAT-005: Use never for exhaustive checks
+
+```typescript
+function assertNever(value: never): never {
+  throw new Error(`Unexpected value: ${value}`);
+}
+
+type Shape = { kind: 'circle'; radius: number } | { kind: 'square'; side: number };
+
+function getArea(shape: Shape): number {
+  switch (shape.kind) {
+    case 'circle':
+      return Math.PI * shape.radius ** 2;
+    case 'square':
+      return shape.side ** 2;
+    default:
+      return assertNever(shape); // Compile error if new shape added
+  }
+}
+```
+
+---
+
+## Type Guards
+
+### PAT-006: Create custom type guards
+
+```typescript
+// Simple type guard
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+// Object type guard
+function isUser(value: unknown): value is User {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    'email' in value
+  );
+}
+
+// With Zod (preferred)
+function isUser(value: unknown): value is User {
+  return userSchema.safeParse(value).success;
+}
+
+// Array type guard
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every(isString);
+}
+```
+
+### PAT-007: Use assertion functions
+
+```typescript
+function assertDefined<T>(
+  value: T | undefined | null,
+  message?: string
+): asserts value is T {
+  if (value === undefined || value === null) {
+    throw new Error(message ?? 'Value is not defined');
+  }
+}
+
+// Usage
+const user = users.find(u => u.id === id);
+assertDefined(user, `User ${id} not found`);
+// user is now User (not User | undefined)
+```
+
+---
+
+## Generics
+
+### PAT-008: Use generics for reusable types
+
+```typescript
+// Generic response wrapper
+interface ApiResponse<T> {
+  data: T;
+  timestamp: Date;
+}
+
+// Generic result type
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+// Generic with constraints
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+// Generic with default
+interface Paginated<T, Meta = { page: number; total: number }> {
+  items: T[];
+  meta: Meta;
+}
+```
+
+### PAT-009: Constrain generics appropriately
+
+```typescript
+// Require specific shape
+function clone<T extends object>(obj: T): T {
+  return { ...obj };
+}
+
+// Require specific properties
+function getId<T extends { id: string }>(item: T): string {
+  return item.id;
+}
+
+// Multiple constraints
+function merge<T extends object, U extends object>(a: T, b: U): T & U {
+  return { ...a, ...b };
+}
+```
+
+---
+
+## Async Patterns
+
+### PAT-010: Type async iterators
+
+```typescript
+async function* paginate<T>(
+  fetcher: (page: number) => Promise<{ items: T[]; hasMore: boolean }>
+): AsyncGenerator<T[], void, unknown> {
+  let page = 1;
+  let hasMore = true;
+
+  while (hasMore) {
+    const result = await fetcher(page);
+    yield result.items;
+    hasMore = result.hasMore;
+    page++;
+  }
+}
+
+// Usage
+for await (const batch of paginate(fetchUsers)) {
+  await processUsers(batch);
+}
+```
+
+### PAT-011: Use AbortSignal for cancellation
+
+```typescript
+async function fetchWithTimeout<T>(
+  url: string,
+  options: { timeout: number; signal?: AbortSignal }
+): Promise<T> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), options.timeout);
+
+  // Combine signals
+  options.signal?.addEventListener('abort', () => controller.abort());
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    return response.json();
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+```
+
+---
+
+## Object Patterns
+
+### PAT-012: Use satisfies for type checking with inference
+
+```typescript
+// satisfies checks type but preserves literal types
+const config = {
+  port: 3000,
+  host: 'localhost',
+  debug: true,
+} satisfies Config;
+
+// config.port is number, not widened
+// But still validated against Config shape
+
+// Useful for route definitions
+const routes = {
+  home: '/',
+  users: '/users',
+  userDetail: '/users/:id',
+} satisfies Record<string, string>;
+
+// routes.home is '/', not string
+```
+
+### PAT-013: Immutable updates
+
+```typescript
+// Spread for shallow copies
+const updated = { ...user, name: 'New Name' };
+
+// For arrays
+const added = [...items, newItem];
+const removed = items.filter(i => i.id !== id);
+const replaced = items.map(i => i.id === id ? updated : i);
+
+// For nested updates
+const nested = {
+  ...state,
+  user: {
+    ...state.user,
+    profile: {
+      ...state.user.profile,
+      name: 'New Name',
+    },
+  },
+};
+
+// Or use immer for complex updates
+import { produce } from 'immer';
+const nested = produce(state, draft => {
+  draft.user.profile.name = 'New Name';
+});
+```
+
+---
+
+## Module Patterns
+
+### PAT-014: Use namespace for grouping
+
+```typescript
+// Group related functions
+export const User = {
+  create: (data: CreateUserData): User => ({ ... }),
+  validate: (user: unknown): user is User => userSchema.safeParse(user).success,
+  format: (user: User): string => `${user.name} <${user.email}>`,
+} as const;
+
+// Usage
+const user = User.create({ name: 'John', email: 'john@example.com' });
+if (User.validate(data)) { ... }
+```
+
+### PAT-015: Builder pattern for complex objects
+
+```typescript
+class QueryBuilder<T> {
+  private filters: Filter[] = [];
+  private sortBy?: string;
+  private limit?: number;
+
+  where(filter: Filter): this {
+    this.filters.push(filter);
+    return this;
+  }
+
+  orderBy(field: keyof T): this {
+    this.sortBy = String(field);
+    return this;
+  }
+
+  take(count: number): this {
+    this.limit = count;
+    return this;
+  }
+
+  build(): Query<T> {
+    return { filters: this.filters, sortBy: this.sortBy, limit: this.limit };
+  }
+}
+
+// Usage
+const query = new QueryBuilder<User>()
+  .where({ field: 'status', op: 'eq', value: 'active' })
+  .orderBy('createdAt')
+  .take(10)
+  .build();
+```