claude-brain 0.15.2 → 0.16.0

package/packs/core/typescript.json

@@ -1,222 +1,222 @@
-{
-  "id": "core/typescript",
-  "name": "TypeScript Essentials",
-  "version": "1.0.0",
-  "stack": ["typescript"],
-  "description": "Type narrowing, strict mode patterns, generics, enums vs unions, and module best practices",
-  "author": "claude-brain",
-  "entries": [
-    {
-      "type": "best-practice",
-      "category": "Type Safety",
-      "title": "Prefer unknown over any",
-      "content": "Use `unknown` instead of `any` for values of uncertain type. Unlike `any`, `unknown` requires type narrowing before use, catching errors at compile time rather than runtime.",
-      "confidence": 0.95,
-      "tags": ["typescript", "type-safety", "strict-mode"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Type Safety",
-      "title": "Use discriminated unions for state modeling",
-      "content": "Model mutually exclusive states with discriminated unions using a literal type discriminant. This ensures exhaustive checking and prevents impossible states.",
-      "confidence": 0.95,
-      "tags": ["typescript", "unions", "state-management"],
-      "example": "type Result<T> = { status: 'success'; data: T } | { status: 'error'; error: Error }"
-    },
-    {
-      "type": "anti-pattern",
-      "category": "Type Safety",
-      "title": "Avoid type assertions as default escape hatch",
-      "content": "Avoid `as` type assertions to silence type errors. They bypass the type checker entirely. Instead, use type guards, narrowing, or fix the underlying type mismatch.",
-      "confidence": 0.9,
-      "tags": ["typescript", "type-safety", "anti-pattern"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Type Narrowing",
-      "title": "Use in operator for interface discrimination",
-      "content": "The `in` operator narrows types by checking for property existence. Combined with discriminated unions, it provides type-safe branching without runtime overhead.",
-      "confidence": 0.85,
-      "tags": ["typescript", "narrowing"],
-      "example": "if ('error' in result) { /* result is ErrorResult */ }"
-    },
-    {
-      "type": "best-practice",
-      "category": "Type Narrowing",
-      "title": "Use satisfies for type checking without widening",
-      "content": "The `satisfies` operator validates that an expression matches a type without changing the inferred type. Use it to catch errors while preserving literal types.",
-      "confidence": 0.9,
-      "tags": ["typescript", "satisfies", "type-inference"],
-      "example": "const routes = { home: '/', about: '/about' } satisfies Record<string, string>"
-    },
-    {
-      "type": "pattern",
-      "category": "Generics",
-      "title": "Constrain generics with extends",
-      "content": "Always constrain generic type parameters with `extends` when the function relies on specific properties. This provides better error messages and prevents misuse.",
-      "confidence": 0.9,
-      "tags": ["typescript", "generics"],
-      "example": "function getProperty<T extends object, K extends keyof T>(obj: T, key: K): T[K]"
-    },
-    {
-      "type": "anti-pattern",
-      "category": "Generics",
-      "title": "Avoid unnecessary generics",
-      "content": "Don't add generic type parameters that are only used once or don't provide additional type safety. A generic that appears in only the return type without constraining input is usually unnecessary.",
-      "confidence": 0.85,
-      "tags": ["typescript", "generics", "simplicity"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Enums vs Unions",
-      "title": "Prefer const objects or union types over enums",
-      "content": "TypeScript enums generate runtime code and have surprising behaviors (numeric enums allow any number). Prefer `as const` objects with derived union types for better tree-shaking and type inference.",
-      "confidence": 0.9,
-      "tags": ["typescript", "enums", "unions"],
-      "example": "const Status = { Active: 'active', Inactive: 'inactive' } as const;\ntype Status = typeof Status[keyof typeof Status];"
-    },
-    {
-      "type": "common-issue",
-      "category": "Strict Mode",
-      "title": "Enable strict mode in tsconfig.json",
-      "content": "Always enable `strict: true` in tsconfig.json. This enables strictNullChecks, noImplicitAny, strictFunctionTypes, and other checks that catch the majority of type-related bugs.",
-      "confidence": 0.95,
-      "tags": ["typescript", "strict-mode", "configuration"]
-    },
-    {
-      "type": "common-issue",
-      "category": "Strict Mode",
-      "title": "Handle null and undefined explicitly",
-      "content": "With strictNullChecks enabled, use optional chaining (?.), nullish coalescing (??), and explicit null checks. Never use non-null assertions (!) unless you can prove the value exists.",
-      "confidence": 0.9,
-      "tags": ["typescript", "null-safety", "strict-mode"]
-    },
-    {
-      "type": "pattern",
-      "category": "Utility Types",
-      "title": "Use built-in utility types effectively",
-      "content": "TypeScript provides Partial, Required, Pick, Omit, Record, ReturnType, Parameters, and more. Use these instead of manually redefining type transformations.",
-      "confidence": 0.9,
-      "tags": ["typescript", "utility-types"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Modules",
-      "title": "Use type-only imports for types",
-      "content": "Use `import type { ... }` for type-only imports. This ensures the import is erased at compile time, reducing bundle size and preventing circular dependency issues.",
-      "confidence": 0.9,
-      "tags": ["typescript", "modules", "imports"],
-      "example": "import type { Config } from './config'"
-    },
-    {
-      "type": "anti-pattern",
-      "category": "Type Safety",
-      "title": "Avoid using Function type",
-      "content": "The `Function` type accepts any function regardless of parameters or return type. Use specific function signatures like `(x: number) => string` or `(...args: unknown[]) => unknown`.",
-      "confidence": 0.9,
-      "tags": ["typescript", "type-safety"]
-    },
-    {
-      "type": "pattern",
-      "category": "Error Handling",
-      "title": "Type-safe error handling with instanceof narrowing",
-      "content": "In catch blocks, the error is `unknown`. Use `instanceof Error` to narrow it before accessing `.message` or `.stack`. Create custom error classes for domain-specific errors.",
-      "confidence": 0.9,
-      "tags": ["typescript", "error-handling"],
-      "example": "catch (error) { if (error instanceof Error) { log(error.message) } }"
-    },
-    {
-      "type": "best-practice",
-      "category": "Type Safety",
-      "title": "Use readonly for immutable data",
-      "content": "Mark arrays as `readonly T[]` and objects as `Readonly<T>` when mutation is not intended. This prevents accidental modification and communicates intent clearly.",
-      "confidence": 0.85,
-      "tags": ["typescript", "immutability", "readonly"]
-    },
-    {
-      "type": "pattern",
-      "category": "Type Guards",
-      "title": "Create custom type guard functions",
-      "content": "Use `is` return type annotations to create reusable type guards. These narrow types in conditional branches and can be tested independently.",
-      "confidence": 0.85,
-      "tags": ["typescript", "type-guards", "narrowing"],
-      "example": "function isString(value: unknown): value is string { return typeof value === 'string' }"
-    },
-    {
-      "type": "common-issue",
-      "category": "Async",
-      "title": "Always type async function return values",
-      "content": "Async functions always return a Promise. Explicitly typing the return as `Promise<T>` prevents accidentally returning the wrong type and makes the API contract clear.",
-      "confidence": 0.85,
-      "tags": ["typescript", "async", "promises"]
-    },
-    {
-      "type": "anti-pattern",
-      "category": "Type Safety",
-      "title": "Avoid excessive type casting chains",
-      "content": "If you need `value as unknown as TargetType`, the type system is telling you something is wrong. Fix the underlying type issue instead of casting through unknown.",
-      "confidence": 0.9,
-      "tags": ["typescript", "type-safety", "anti-pattern"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Configuration",
-      "title": "Use path aliases in tsconfig",
-      "content": "Configure path aliases in tsconfig.json compilerOptions.paths (e.g., `@/` mapping to `src/`) to avoid deep relative imports and make refactoring easier.",
-      "confidence": 0.85,
-      "tags": ["typescript", "configuration", "imports"],
-      "example": "\"paths\": { \"@/*\": [\"src/*\"] }"
-    },
-    {
-      "type": "pattern",
-      "category": "Inference",
-      "title": "Leverage type inference where possible",
-      "content": "Don't annotate types that TypeScript can infer. Over-annotating adds noise without safety. Annotate function parameters, return types of exported functions, and complex objects.",
-      "confidence": 0.85,
-      "tags": ["typescript", "inference", "readability"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Zod Integration",
-      "title": "Use Zod for runtime validation with type inference",
-      "content": "Zod schemas provide both runtime validation and compile-time types via `z.infer<typeof schema>`. Define the schema once and derive the type, keeping them in sync.",
-      "confidence": 0.85,
-      "tags": ["typescript", "zod", "validation"],
-      "example": "const UserSchema = z.object({ name: z.string() });\ntype User = z.infer<typeof UserSchema>;"
-    },
-    {
-      "type": "common-issue",
-      "category": "Modules",
-      "title": "Understand ESM vs CJS module resolution",
-      "content": "TypeScript's module resolution depends on moduleResolution setting. Use 'bundler' or 'nodenext' for modern projects. With ESM, imports require file extensions in output.",
-      "confidence": 0.8,
-      "tags": ["typescript", "modules", "esm", "commonjs"]
-    },
-    {
-      "type": "pattern",
-      "category": "Type Safety",
-      "title": "Use template literal types for string patterns",
-      "content": "Template literal types can enforce string patterns at the type level, like route paths, event names, or ID formats.",
-      "confidence": 0.8,
-      "tags": ["typescript", "template-literals"],
-      "example": "type EventName = `on${Capitalize<string>}`"
-    },
-    {
-      "type": "anti-pattern",
-      "category": "Type Safety",
-      "title": "Avoid using object type",
-      "content": "The `object` type is too broad — it matches arrays, functions, dates, and any non-primitive. Use `Record<string, unknown>` for key-value objects or define a specific interface.",
-      "confidence": 0.85,
-      "tags": ["typescript", "type-safety"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Error Handling",
-      "title": "Use Result types for expected failures",
-      "content": "For operations that can fail expectedly (validation, parsing), return a discriminated union Result type instead of throwing. Reserve exceptions for unexpected failures.",
-      "confidence": 0.85,
-      "tags": ["typescript", "error-handling", "result-type"],
-      "example": "type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E }"
-    }
-  ]
-}
+{
+  "id": "core/typescript",
+  "name": "TypeScript Essentials",
+  "version": "1.0.0",
+  "stack": ["typescript"],
+  "description": "Type narrowing, strict mode patterns, generics, enums vs unions, and module best practices",
+  "author": "claude-brain",
+  "entries": [
+    {
+      "type": "best-practice",
+      "category": "Type Safety",
+      "title": "Prefer unknown over any",
+      "content": "Use `unknown` instead of `any` for values of uncertain type. Unlike `any`, `unknown` requires type narrowing before use, catching errors at compile time rather than runtime.",
+      "confidence": 0.95,
+      "tags": ["typescript", "type-safety", "strict-mode"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Type Safety",
+      "title": "Use discriminated unions for state modeling",
+      "content": "Model mutually exclusive states with discriminated unions using a literal type discriminant. This ensures exhaustive checking and prevents impossible states.",
+      "confidence": 0.95,
+      "tags": ["typescript", "unions", "state-management"],
+      "example": "type Result<T> = { status: 'success'; data: T } | { status: 'error'; error: Error }"
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Type Safety",
+      "title": "Avoid type assertions as default escape hatch",
+      "content": "Avoid `as` type assertions to silence type errors. They bypass the type checker entirely. Instead, use type guards, narrowing, or fix the underlying type mismatch.",
+      "confidence": 0.9,
+      "tags": ["typescript", "type-safety", "anti-pattern"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Type Narrowing",
+      "title": "Use in operator for interface discrimination",
+      "content": "The `in` operator narrows types by checking for property existence. Combined with discriminated unions, it provides type-safe branching without runtime overhead.",
+      "confidence": 0.85,
+      "tags": ["typescript", "narrowing"],
+      "example": "if ('error' in result) { /* result is ErrorResult */ }"
+    },
+    {
+      "type": "best-practice",
+      "category": "Type Narrowing",
+      "title": "Use satisfies for type checking without widening",
+      "content": "The `satisfies` operator validates that an expression matches a type without changing the inferred type. Use it to catch errors while preserving literal types.",
+      "confidence": 0.9,
+      "tags": ["typescript", "satisfies", "type-inference"],
+      "example": "const routes = { home: '/', about: '/about' } satisfies Record<string, string>"
+    },
+    {
+      "type": "pattern",
+      "category": "Generics",
+      "title": "Constrain generics with extends",
+      "content": "Always constrain generic type parameters with `extends` when the function relies on specific properties. This provides better error messages and prevents misuse.",
+      "confidence": 0.9,
+      "tags": ["typescript", "generics"],
+      "example": "function getProperty<T extends object, K extends keyof T>(obj: T, key: K): T[K]"
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Generics",
+      "title": "Avoid unnecessary generics",
+      "content": "Don't add generic type parameters that are only used once or don't provide additional type safety. A generic that appears in only the return type without constraining input is usually unnecessary.",
+      "confidence": 0.85,
+      "tags": ["typescript", "generics", "simplicity"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Enums vs Unions",
+      "title": "Prefer const objects or union types over enums",
+      "content": "TypeScript enums generate runtime code and have surprising behaviors (numeric enums allow any number). Prefer `as const` objects with derived union types for better tree-shaking and type inference.",
+      "confidence": 0.9,
+      "tags": ["typescript", "enums", "unions"],
+      "example": "const Status = { Active: 'active', Inactive: 'inactive' } as const;\ntype Status = typeof Status[keyof typeof Status];"
+    },
+    {
+      "type": "common-issue",
+      "category": "Strict Mode",
+      "title": "Enable strict mode in tsconfig.json",
+      "content": "Always enable `strict: true` in tsconfig.json. This enables strictNullChecks, noImplicitAny, strictFunctionTypes, and other checks that catch the majority of type-related bugs.",
+      "confidence": 0.95,
+      "tags": ["typescript", "strict-mode", "configuration"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Strict Mode",
+      "title": "Handle null and undefined explicitly",
+      "content": "With strictNullChecks enabled, use optional chaining (?.), nullish coalescing (??), and explicit null checks. Never use non-null assertions (!) unless you can prove the value exists.",
+      "confidence": 0.9,
+      "tags": ["typescript", "null-safety", "strict-mode"]
+    },
+    {
+      "type": "pattern",
+      "category": "Utility Types",
+      "title": "Use built-in utility types effectively",
+      "content": "TypeScript provides Partial, Required, Pick, Omit, Record, ReturnType, Parameters, and more. Use these instead of manually redefining type transformations.",
+      "confidence": 0.9,
+      "tags": ["typescript", "utility-types"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Modules",
+      "title": "Use type-only imports for types",
+      "content": "Use `import type { ... }` for type-only imports. This ensures the import is erased at compile time, reducing bundle size and preventing circular dependency issues.",
+      "confidence": 0.9,
+      "tags": ["typescript", "modules", "imports"],
+      "example": "import type { Config } from './config'"
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Type Safety",
+      "title": "Avoid using Function type",
+      "content": "The `Function` type accepts any function regardless of parameters or return type. Use specific function signatures like `(x: number) => string` or `(...args: unknown[]) => unknown`.",
+      "confidence": 0.9,
+      "tags": ["typescript", "type-safety"]
+    },
+    {
+      "type": "pattern",
+      "category": "Error Handling",
+      "title": "Type-safe error handling with instanceof narrowing",
+      "content": "In catch blocks, the error is `unknown`. Use `instanceof Error` to narrow it before accessing `.message` or `.stack`. Create custom error classes for domain-specific errors.",
+      "confidence": 0.9,
+      "tags": ["typescript", "error-handling"],
+      "example": "catch (error) { if (error instanceof Error) { log(error.message) } }"
+    },
+    {
+      "type": "best-practice",
+      "category": "Type Safety",
+      "title": "Use readonly for immutable data",
+      "content": "Mark arrays as `readonly T[]` and objects as `Readonly<T>` when mutation is not intended. This prevents accidental modification and communicates intent clearly.",
+      "confidence": 0.85,
+      "tags": ["typescript", "immutability", "readonly"]
+    },
+    {
+      "type": "pattern",
+      "category": "Type Guards",
+      "title": "Create custom type guard functions",
+      "content": "Use `is` return type annotations to create reusable type guards. These narrow types in conditional branches and can be tested independently.",
+      "confidence": 0.85,
+      "tags": ["typescript", "type-guards", "narrowing"],
+      "example": "function isString(value: unknown): value is string { return typeof value === 'string' }"
+    },
+    {
+      "type": "common-issue",
+      "category": "Async",
+      "title": "Always type async function return values",
+      "content": "Async functions always return a Promise. Explicitly typing the return as `Promise<T>` prevents accidentally returning the wrong type and makes the API contract clear.",
+      "confidence": 0.85,
+      "tags": ["typescript", "async", "promises"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Type Safety",
+      "title": "Avoid excessive type casting chains",
+      "content": "If you need `value as unknown as TargetType`, the type system is telling you something is wrong. Fix the underlying type issue instead of casting through unknown.",
+      "confidence": 0.9,
+      "tags": ["typescript", "type-safety", "anti-pattern"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Configuration",
+      "title": "Use path aliases in tsconfig",
+      "content": "Configure path aliases in tsconfig.json compilerOptions.paths (e.g., `@/` mapping to `src/`) to avoid deep relative imports and make refactoring easier.",
+      "confidence": 0.85,
+      "tags": ["typescript", "configuration", "imports"],
+      "example": "\"paths\": { \"@/*\": [\"src/*\"] }"
+    },
+    {
+      "type": "pattern",
+      "category": "Inference",
+      "title": "Leverage type inference where possible",
+      "content": "Don't annotate types that TypeScript can infer. Over-annotating adds noise without safety. Annotate function parameters, return types of exported functions, and complex objects.",
+      "confidence": 0.85,
+      "tags": ["typescript", "inference", "readability"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Zod Integration",
+      "title": "Use Zod for runtime validation with type inference",
+      "content": "Zod schemas provide both runtime validation and compile-time types via `z.infer<typeof schema>`. Define the schema once and derive the type, keeping them in sync.",
+      "confidence": 0.85,
+      "tags": ["typescript", "zod", "validation"],
+      "example": "const UserSchema = z.object({ name: z.string() });\ntype User = z.infer<typeof UserSchema>;"
+    },
+    {
+      "type": "common-issue",
+      "category": "Modules",
+      "title": "Understand ESM vs CJS module resolution",
+      "content": "TypeScript's module resolution depends on moduleResolution setting. Use 'bundler' or 'nodenext' for modern projects. With ESM, imports require file extensions in output.",
+      "confidence": 0.8,
+      "tags": ["typescript", "modules", "esm", "commonjs"]
+    },
+    {
+      "type": "pattern",
+      "category": "Type Safety",
+      "title": "Use template literal types for string patterns",
+      "content": "Template literal types can enforce string patterns at the type level, like route paths, event names, or ID formats.",
+      "confidence": 0.8,
+      "tags": ["typescript", "template-literals"],
+      "example": "type EventName = `on${Capitalize<string>}`"
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Type Safety",
+      "title": "Avoid using object type",
+      "content": "The `object` type is too broad — it matches arrays, functions, dates, and any non-primitive. Use `Record<string, unknown>` for key-value objects or define a specific interface.",
+      "confidence": 0.85,
+      "tags": ["typescript", "type-safety"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Error Handling",
+      "title": "Use Result types for expected failures",
+      "content": "For operations that can fail expectedly (validation, parsing), return a discriminated union Result type instead of throwing. Reserve exceptions for unexpected failures.",
+      "confidence": 0.85,
+      "tags": ["typescript", "error-handling", "result-type"],
+      "example": "type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E }"
+    }
+  ]
+}