@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/_shared/.claude/rules/lang/typescript/generics.md

@@ -0,0 +1,356 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+---
+
+# TypeScript Generics & Advanced Types
+
+## Generic Basics
+
+```typescript
+// Generic function
+function identity<T>(value: T): T {
+  return value;
+}
+
+// Generic with constraint
+function getLength<T extends { length: number }>(item: T): number {
+  return item.length;
+}
+
+// Multiple type parameters
+function pair<K, V>(key: K, value: V): [K, V] {
+  return [key, value];
+}
+
+// Generic interface
+interface Repository<T> {
+  find(id: string): Promise<T | null>;
+  save(item: T): Promise<T>;
+  delete(id: string): Promise<void>;
+}
+
+// Generic class
+class Cache<T> {
+  private items = new Map<string, T>();
+
+  get(key: string): T | undefined {
+    return this.items.get(key);
+  }
+
+  set(key: string, value: T): void {
+    this.items.set(key, value);
+  }
+}
+```
+
+## Constraints
+
+```typescript
+// Extends constraint
+function merge<T extends object, U extends object>(a: T, b: U): T & U {
+  return { ...a, ...b };
+}
+
+// keyof constraint
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+// Constructor constraint
+function createInstance<T>(ctor: new () => T): T {
+  return new ctor();
+}
+
+// Multiple constraints
+function process<T extends Serializable & Validatable>(item: T): void {
+  item.validate();
+  item.serialize();
+}
+```
+
+## Utility Types
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  password: string;
+  createdAt: Date;
+}
+
+// Partial - all properties optional
+type UpdateUserDto = Partial<User>;
+// { id?: string; name?: string; ... }
+
+// Required - all properties required
+type CompleteUser = Required<User>;
+
+// Pick - select specific properties
+type UserCredentials = Pick<User, 'email' | 'password'>;
+// { email: string; password: string }
+
+// Omit - exclude properties
+type PublicUser = Omit<User, 'password'>;
+// { id: string; name: string; email: string; createdAt: Date }
+
+// Record - key-value mapping
+type UserRoles = Record<string, 'admin' | 'user' | 'guest'>;
+// { [key: string]: 'admin' | 'user' | 'guest' }
+
+// Readonly - immutable
+type ImmutableUser = Readonly<User>;
+
+// Extract - extract union members
+type StringOrNumber = string | number | boolean;
+type OnlyStrings = Extract<StringOrNumber, string>; // string
+
+// Exclude - remove union members
+type NoStrings = Exclude<StringOrNumber, string>; // number | boolean
+
+// NonNullable - remove null/undefined
+type MaybeString = string | null | undefined;
+type DefiniteString = NonNullable<MaybeString>; // string
+
+// ReturnType - get function return type
+function getUser() { return { id: '1', name: 'John' }; }
+type UserReturn = ReturnType<typeof getUser>;
+// { id: string; name: string }
+
+// Parameters - get function parameters
+type GetUserParams = Parameters<typeof getUser>; // []
+
+// Awaited - unwrap Promise
+type ResolvedUser = Awaited<Promise<User>>; // User
+```
+
+## Discriminated Unions
+
+```typescript
+// GOOD - discriminated union with literal type
+type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+
+function handleResult<T>(result: Result<T>): T | null {
+  if (result.success) {
+    return result.data; // TypeScript knows data exists
+  }
+  console.error(result.error); // TypeScript knows error exists
+  return null;
+}
+
+// API response pattern
+type ApiResponse<T> =
+  | { status: 'loading' }
+  | { status: 'success'; data: T }
+  | { status: 'error'; error: Error };
+
+function renderResponse<T>(response: ApiResponse<T>) {
+  switch (response.status) {
+    case 'loading':
+      return <Spinner />;
+    case 'success':
+      return <Data data={response.data} />;
+    case 'error':
+      return <Error error={response.error} />;
+  }
+}
+
+// Event pattern
+type AppEvent =
+  | { type: 'USER_LOGIN'; userId: string }
+  | { type: 'USER_LOGOUT' }
+  | { type: 'ITEM_ADDED'; itemId: string; quantity: number };
+
+function handleEvent(event: AppEvent) {
+  switch (event.type) {
+    case 'USER_LOGIN':
+      return login(event.userId);
+    case 'USER_LOGOUT':
+      return logout();
+    case 'ITEM_ADDED':
+      return addItem(event.itemId, event.quantity);
+  }
+}
+```
+
+## Type Guards
+
+```typescript
+// Type predicate (is)
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+function isUser(value: unknown): value is User {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    'email' in value
+  );
+}
+
+// Usage
+function process(value: unknown) {
+  if (isString(value)) {
+    console.log(value.toUpperCase()); // value is string
+  }
+  if (isUser(value)) {
+    console.log(value.email); // value is User
+  }
+}
+
+// Assertion function (asserts)
+function assertDefined<T>(value: T | null | undefined): asserts value is T {
+  if (value === null || value === undefined) {
+    throw new Error('Value is not defined');
+  }
+}
+
+// Usage
+function getUser(id: string): User | null {
+  return db.find(id);
+}
+
+const user = getUser('123');
+assertDefined(user); // Throws if null
+console.log(user.name); // user is User, not User | null
+
+// in operator narrowing
+interface Cat { meow(): void }
+interface Dog { bark(): void }
+
+function speak(animal: Cat | Dog) {
+  if ('meow' in animal) {
+    animal.meow();
+  } else {
+    animal.bark();
+  }
+}
+```
+
+## Const Assertions
+
+```typescript
+// Without as const - types are widened
+const config = {
+  endpoint: '/api',
+  methods: ['GET', 'POST'],
+};
+// type: { endpoint: string; methods: string[] }
+
+// With as const - literal types preserved
+const config = {
+  endpoint: '/api',
+  methods: ['GET', 'POST'],
+} as const;
+// type: { readonly endpoint: '/api'; readonly methods: readonly ['GET', 'POST'] }
+
+// Useful for union types from arrays
+const ROLES = ['admin', 'user', 'guest'] as const;
+type Role = typeof ROLES[number]; // 'admin' | 'user' | 'guest'
+
+// Object values as union
+const STATUS = {
+  PENDING: 'pending',
+  ACTIVE: 'active',
+  INACTIVE: 'inactive',
+} as const;
+type Status = typeof STATUS[keyof typeof STATUS];
+// 'pending' | 'active' | 'inactive'
+```
+
+## Conditional Types
+
+```typescript
+// Basic conditional
+type IsString<T> = T extends string ? true : false;
+
+type A = IsString<string>;  // true
+type B = IsString<number>;  // false
+
+// Infer keyword - extract types
+type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+
+type X = UnwrapPromise<Promise<string>>;  // string
+type Y = UnwrapPromise<number>;           // number
+
+// Extract array element type
+type ArrayElement<T> = T extends (infer E)[] ? E : never;
+
+type El = ArrayElement<string[]>; // string
+
+// Function return type extraction
+type GetReturn<T> = T extends (...args: any[]) => infer R ? R : never;
+
+// Distributive conditional types
+type ToArray<T> = T extends any ? T[] : never;
+
+type Distributed = ToArray<string | number>;
+// string[] | number[] (not (string | number)[])
+```
+
+## Mapped Types
+
+```typescript
+// Make all properties optional
+type Optional<T> = {
+  [K in keyof T]?: T[K];
+};
+
+// Make all properties readonly
+type Immutable<T> = {
+  readonly [K in keyof T]: T[K];
+};
+
+// Transform property types
+type Stringify<T> = {
+  [K in keyof T]: string;
+};
+
+// Key remapping (4.1+)
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+};
+
+interface Person {
+  name: string;
+  age: number;
+}
+
+type PersonGetters = Getters<Person>;
+// { getName: () => string; getAge: () => number }
+
+// Filter properties by type
+type OnlyStrings<T> = {
+  [K in keyof T as T[K] extends string ? K : never]: T[K];
+};
+```
+
+## Template Literal Types
+
+```typescript
+// Basic template literal
+type Greeting = `Hello, ${string}!`;
+
+// Event names
+type EventName = `on${Capitalize<'click' | 'focus' | 'blur'>}`;
+// 'onClick' | 'onFocus' | 'onBlur'
+
+// API routes
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type Route = '/users' | '/posts';
+type Endpoint = `${HttpMethod} ${Route}`;
+// 'GET /users' | 'GET /posts' | 'POST /users' | ...
+
+// CSS units
+type CSSUnit = 'px' | 'em' | 'rem' | '%';
+type CSSValue = `${number}${CSSUnit}`;
+
+const width: CSSValue = '100px';  // OK
+const height: CSSValue = '50%';   // OK
+```

package/configs/_shared/.claude/rules/lang/typescript/typescript.md

@@ -0,0 +1,212 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+---
+
+# TypeScript Code Style Rules
+
+## Strict Mode Required
+
+```json
+{
+  "strict": true,
+  "noImplicitAny": true,
+  "strictNullChecks": true
+}
+```
+
+## Type Guidelines
+
+### Interfaces vs Types
+
+```typescript
+// Interface for object shapes
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: Date;
+}
+
+// Type for unions/intersections
+type Status = 'pending' | 'active' | 'inactive';
+type Result<T> = { success: true; data: T } | { success: false; error: string };
+```
+
+### NEVER Use `any`
+
+**`any` is forbidden.** It disables type checking and defeats the purpose of TypeScript.
+
+| Instead of `any` | Use |
+|------------------|-----|
+| Unknown data | `unknown` + type guard |
+| Object with unknown keys | `Record<string, unknown>` |
+| Array of unknown | `unknown[]` |
+| Function args | Generics `<T>` |
+| JSON response | Define interface or use `unknown` |
+| Third-party lib | `@types/*` or declare module |
+
+```typescript
+// BAD - NEVER do this
+function process(data: any) { }
+const response = await fetch(url) as any;
+const items: any[] = [];
+
+// GOOD - unknown + type guard
+function process(data: unknown) {
+  if (isValidData(data)) {
+    // data is now typed
+  }
+}
+
+// GOOD - explicit type
+function process(data: UserInput) { }
+
+// GOOD - generic
+function transform<T>(data: T): T { }
+
+// GOOD - Record for dynamic keys
+const cache: Record<string, unknown> = {};
+```
+
+**Exception**: Only when interfacing with untyped legacy code, with explicit justification:
+```typescript
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Legacy API v1, see TECH-123
+const legacyResponse = await oldApi.fetch() as any;
+```
+
+### Explicit Return Types on Public Functions
+
+```typescript
+// BAD - inferred return type
+export function getUser(id: string) {
+  return db.users.findById(id);
+}
+
+// GOOD - explicit return type
+export function getUser(id: string): Promise<User | null> {
+  return db.users.findById(id);
+}
+```
+
+## Naming Conventions
+
+### Be Explicit - No Cryptic Names
+
+```typescript
+// BAD - cryptic names
+const c = getConfig();
+users.filter(u => u.a);
+const d = new Date();
+const tmp = calculate();
+
+// GOOD - explicit names
+const appConfig = getConfig();
+users.filter(user => user.isActive);
+const createdAt = new Date();
+const totalAmount = calculate();
+```
+
+### Named Constants Over Magic Numbers
+
+```typescript
+// BAD - magic numbers
+if (password.length < 8) { }
+setTimeout(fn, 86400000);
+
+// GOOD - named constants
+const MIN_PASSWORD_LENGTH = 8;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+
+if (password.length < MIN_PASSWORD_LENGTH) { }
+setTimeout(fn, ONE_DAY_MS);
+```
+
+## Lint Disable Rules
+
+```typescript
+// FORBIDDEN - no justification
+// eslint-disable-next-line
+const x = something;
+
+// ALLOWED - with explicit reason + ticket
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Legacy API returns any, see TECH-456
+const legacyData = await legacyApi.fetch();
+```
+
+## Function Guidelines
+
+### Small Functions (< 30 lines)
+
+```typescript
+// BAD - too long, multiple responsibilities
+async function processOrder(order: Order) {
+  // 50+ lines of validation, calculation, saving, emailing...
+}
+
+// GOOD - single responsibility
+async function processOrder(order: Order): Promise<OrderResult> {
+  validateOrder(order);
+  const total = calculateTotal(order);
+  const savedOrder = await saveOrder(order, total);
+  await sendConfirmation(savedOrder);
+  return savedOrder;
+}
+```
+
+### Max Nesting: 3 Levels - Use Early Returns
+
+```typescript
+// BAD - deep nesting
+function process(user: User | null) {
+  if (user) {
+    if (user.isActive) {
+      if (user.hasPermission) {
+        // do something
+      }
+    }
+  }
+}
+
+// GOOD - early returns
+function process(user: User | null) {
+  if (!user) return;
+  if (!user.isActive) return;
+  if (!user.hasPermission) return;
+
+  // do something
+}
+```
+
+## Error Handling
+
+### Never Swallow Errors Silently
+
+```typescript
+// BAD - silent failure
+try {
+  await saveUser(user);
+} catch (error) {
+  // empty catch
+}
+
+// GOOD - log with context
+try {
+  await saveUser(user);
+} catch (error) {
+  logger.error('Failed to save user', { userId: user.id, error });
+  throw error;
+}
+```
+
+### User-Facing vs Internal Errors
+
+```typescript
+// User-facing: clear, actionable message
+throw new BadRequestError('Email address is already registered');
+
+// Internal: detailed logs, generic user message
+logger.error('Database constraint violation', { error, userId });
+throw new InternalError('Unable to complete registration');
+```

package/configs/_shared/.claude/rules/quality/error-handling.md

@@ -0,0 +1,48 @@
+---
+paths:
+  - "**/*"
+---
+
+# Error Handling Principles
+
+## Core Rules
+
+- **Fail fast, fail loud** - Don't swallow errors silently
+- **Use typed errors** with error codes
+- **Separate user-facing from internal errors**
+- **Always log with context** before throwing
+
+## Error Categories
+
+| Type | HTTP Code | When to Use |
+|------|-----------|-------------|
+| Validation | 400 | Invalid input format |
+| Authentication | 401 | Missing/invalid credentials |
+| Authorization | 403 | Insufficient permissions |
+| Not Found | 404 | Resource doesn't exist |
+| Conflict | 409 | Duplicate resource |
+| Internal | 500 | Unexpected server error |
+
+## Error Response Format
+
+Consistent API error responses should include:
+- Error code (machine-readable)
+- Message (human-readable)
+- Details/context (optional)
+- Request ID (for correlation)
+
+## Anti-Patterns
+
+- Empty catch blocks
+- Logging without rethrowing
+- Exposing stack traces to users
+- Generic "Something went wrong" without logging details
+- Swallowing errors in fire-and-forget operations
+
+## Best Practices
+
+- Create error hierarchy with base error class
+- Include enough context for debugging
+- Use Result/Either pattern for expected failures
+- Implement retry with exponential backoff for transient errors
+- Centralize error handling (middleware/interceptor)

package/configs/_shared/.claude/rules/quality/logging.md

@@ -0,0 +1,45 @@
+---
+paths:
+  - "**/*"
+---
+
+# Logging Principles
+
+## Log Levels
+
+| Level | When to Use |
+|-------|-------------|
+| `debug` | Development details, variable values |
+| `info` | Business events, state changes |
+| `warn` | Recoverable issues, deprecations |
+| `error` | Failures requiring attention |
+
+## What to Log
+
+- Application lifecycle (startup, shutdown)
+- Business events (order placed, user registered)
+- External calls with duration (HTTP, DB)
+- Errors with full context
+
+## What NOT to Log
+
+- Passwords
+- Auth tokens
+- Credit card numbers
+- PII (SSN, personal data)
+- Full request bodies (may contain secrets)
+
+## Best Practices
+
+- **Structured logging** (JSON) in production
+- **Include context**: userId, requestId, traceId
+- **Redact sensitive fields** before logging
+- **Correlation IDs** across async operations
+- **Log at boundaries**: API entry/exit, external calls
+
+## Log Message Guidelines
+
+- Use consistent format across the codebase
+- Include actionable information
+- Avoid logging the same event multiple times
+- Don't log expected/handled errors at ERROR level