@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/typescript-pro/steering/advanced-types.md

@@ -0,0 +1,262 @@
+# Advanced Types
+
+> Reference for: TypeScript Pro
+> Load when: Generics, conditional types, mapped types, template literals
+
+## Generic Constraints
+
+```typescript
+// Basic constraint
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+// Multiple constraints
+interface HasId { id: number; }
+interface HasName { name: string; }
+
+function merge<T extends HasId, U extends HasName>(obj1: T, obj2: U): T & U {
+  return { ...obj1, ...obj2 };
+}
+
+// Generic constraint with default
+type ApiResponse<T = unknown, E = Error> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+
+// Constraint with infer
+type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+type Result = UnwrapPromise<Promise<string>>; // string
+```
+
+## Conditional Types
+
+```typescript
+// Basic conditional type
+type IsString<T> = T extends string ? true : false;
+
+// Distributive conditional types
+type ToArray<T> = T extends any ? T[] : never;
+type StringOrNumberArray = ToArray<string | number>; // string[] | number[]
+
+// Non-distributive (use tuple)
+type ToArrayNonDist<T> = [T] extends [any] ? T[] : never;
+type BothArray = ToArrayNonDist<string | number>; // (string | number)[]
+
+// Nested conditionals for type extraction
+type Flatten<T> = T extends Array<infer U>
+  ? U extends Array<infer V>
+    ? Flatten<V>
+    : U
+  : T;
+
+type Nested = Flatten<string[][][]>; // string
+
+// Exclude null/undefined
+type NonNullable<T> = T extends null | undefined ? never : T;
+```
+
+## Mapped Types
+
+```typescript
+// Basic mapped type
+type ReadOnly<T> = {
+  readonly [K in keyof T]: T[K];
+};
+
+// Optional properties
+type Partial<T> = {
+  [K in keyof T]?: T[K];
+};
+
+// Required properties
+type Required<T> = {
+  [K in keyof T]-?: T[K]; // Remove optional modifier
+};
+
+// Key remapping with 'as'
+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; }
+
+// Filtering keys
+type PickByType<T, U> = {
+  [K in keyof T as T[K] extends U ? K : never]: T[K];
+};
+
+type StringFields = PickByType<Person, string>; // { name: string }
+```
+
+## Template Literal Types
+
+```typescript
+// Basic template literal
+type EmailLocale = 'en' | 'es' | 'fr';
+type EmailType = 'welcome' | 'reset-password';
+type EmailTemplate = `${EmailLocale}_${EmailType}`;
+// 'en_welcome' | 'en_reset-password' | 'es_welcome' | ...
+
+// Intrinsic string manipulation
+type Uppercase<S extends string> = intrinsic;
+type Lowercase<S extends string> = intrinsic;
+type Capitalize<S extends string> = intrinsic;
+type Uncapitalize<S extends string> = intrinsic;
+
+type EventName<T extends string> = `on${Capitalize<T>}`;
+type ClickEvent = EventName<'click'>; // 'onClick'
+
+// Template literal with mapped types
+type CSSProperties = {
+  [K in 'color' | 'background' | 'border' as `--${K}`]: string;
+};
+// { '--color': string; '--background': string; '--border': string }
+
+// Pattern matching with infer
+type ExtractRouteParams<T extends string> =
+  T extends `${infer _Start}/:${infer Param}/${infer Rest}`
+    ? Param | ExtractRouteParams<`/${Rest}`>
+    : T extends `${infer _Start}/:${infer Param}`
+    ? Param
+    : never;
+
+type Params = ExtractRouteParams<'/users/:id/posts/:postId'>; // 'id' | 'postId'
+```
+
+## Higher-Kinded Types (Simulation)
+
+```typescript
+// Type-level function simulation
+interface TypeClass<F> {
+  map: <A, B>(f: (a: A) => B, fa: any) => any;
+}
+
+// Functor pattern
+type Maybe<T> = { type: 'just'; value: T } | { type: 'nothing' };
+
+const MaybeFunctor: TypeClass<Maybe<any>> = {
+  map: <A, B>(f: (a: A) => B, ma: Maybe<A>): Maybe<B> => {
+    return ma.type === 'just'
+      ? { type: 'just', value: f(ma.value) }
+      : { type: 'nothing' };
+  }
+};
+
+// Builder pattern with generics
+type Builder<T, K extends keyof T = never> = {
+  with<P extends Exclude<keyof T, K>>(
+    key: P,
+    value: T[P]
+  ): Builder<T, K | P>;
+  build(): K extends keyof T ? T : never;
+};
+```
+
+## Recursive Types
+
+```typescript
+// JSON type
+type JSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JSONValue[]
+  | { [key: string]: JSONValue };
+
+// Deep partial
+type DeepPartial<T> = T extends object ? {
+  [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+
+// Deep readonly
+type DeepReadonly<T> = T extends object ? {
+  readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+
+// Path type for nested objects
+type PathsToProps<T> = T extends object ? {
+  [K in keyof T]: K extends string
+    ? T[K] extends object
+      ? K | `${K}.${PathsToProps<T[K]>}`
+      : K
+    : never;
+}[keyof T] : never;
+
+interface User {
+  profile: {
+    name: string;
+    settings: {
+      theme: string;
+    };
+  };
+}
+
+type UserPaths = PathsToProps<User>;
+// 'profile' | 'profile.name' | 'profile.settings' | 'profile.settings.theme'
+```
+
+## Variance and Contravariance
+
+```typescript
+// Covariance (return types)
+type Producer<T> = () => T;
+let stringProducer: Producer<string> = () => 'hello';
+let objectProducer: Producer<object> = stringProducer; // OK: string is object
+
+// Contravariance (parameter types)
+type Consumer<T> = (value: T) => void;
+let objectConsumer: Consumer<object> = (obj) => console.log(obj);
+let stringConsumer: Consumer<string> = objectConsumer; // OK in strict mode
+
+// Invariance (mutable properties)
+interface Box<T> {
+  value: T;
+  setValue(v: T): void;
+}
+
+let stringBox: Box<string> = { value: '', setValue: (v) => {} };
+// let objectBox: Box<object> = stringBox; // Error: invariant
+```
+
+## Type-Level Programming
+
+```typescript
+// Type-level addition (limited)
+type Length<T extends any[]> = T['length'];
+type Concat<A extends any[], B extends any[]> = [...A, ...B];
+
+// Type-level conditionals
+type If<Condition extends boolean, Then, Else> =
+  Condition extends true ? Then : Else;
+
+// Type-level equality
+type Equal<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends
+  (<T>() => T extends Y ? 1 : 2) ? true : false;
+
+// Assert equal types (for testing)
+type Assert<T extends true> = T;
+type Test = Assert<Equal<1 | 2, 2 | 1>>; // OK
+```
+
+## Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| `T extends U ? X : Y` | Conditional type logic |
+| `infer R` | Extract types from patterns |
+| `K in keyof T` | Iterate over object keys |
+| `as NewKey` | Remap keys in mapped types |
+| Template literals | String pattern types |
+| `T extends any` | Distributive conditionals |
+| `[T] extends [any]` | Non-distributive check |
+| `-?` modifier | Remove optional |
+| `readonly` modifier | Make immutable |

package/Ai Agent Workflow/powers/typescript-pro/steering/configuration.md

@@ -0,0 +1,448 @@
+# TypeScript Configuration
+
+> Reference for: TypeScript Pro
+> Load when: tsconfig options, strict mode, project references
+
+## Strict Mode Configuration
+
+```json
+{
+  "compilerOptions": {
+    // Strict type checking
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+
+    // Additional checks
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+
+    // Module resolution
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+
+    // Emit
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "removeComments": false,
+    "importHelpers": true,
+
+    // Interop
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+
+    // Target
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+
+    // Skip checking
+    "skipLibCheck": true
+  }
+}
+```
+
+## Project References
+
+```json
+// Root tsconfig.json
+{
+  "files": [],
+  "references": [
+    { "path": "./packages/shared" },
+    { "path": "./packages/frontend" },
+    { "path": "./packages/backend" }
+  ]
+}
+
+// packages/shared/tsconfig.json
+{
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src/**/*"]
+}
+
+// packages/frontend/tsconfig.json
+{
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "references": [
+    { "path": "../shared" }
+  ],
+  "include": ["src/**/*"]
+}
+```
+
+## Module Resolution Strategies
+
+```json
+// Node16/NodeNext (recommended for Node.js)
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true
+  }
+}
+
+// Bundler (for bundlers like Vite, esbuild)
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "moduleDetection": "force"
+  }
+}
+
+// Classic (legacy, avoid)
+{
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "node"
+  }
+}
+```
+
+## Path Mapping
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@components/*": ["src/components/*"],
+      "@utils/*": ["src/utils/*"],
+      "@shared/*": ["../shared/src/*"],
+      "@types": ["src/types/index.ts"]
+    }
+  }
+}
+```
+
+```typescript
+// Usage with path mapping
+import { Button } from '@components/Button';
+import { formatDate } from '@utils/date';
+import type { User } from '@types';
+```
+
+## Incremental Compilation
+
+```json
+{
+  "compilerOptions": {
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/.tsbuildinfo",
+    "composite": true
+  }
+}
+```
+
+## Declaration Files
+
+```json
+{
+  "compilerOptions": {
+    // Generate .d.ts files
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": false,
+
+    // Bundle declarations
+    "declarationDir": "./types",
+
+    // For libraries
+    "stripInternal": true
+  }
+}
+```
+
+```typescript
+// Using JSDoc for .d.ts generation
+/**
+ * Creates a user
+ * @param name - User's name
+ * @param email - User's email
+ * @returns The created user
+ * @example
+ * ```ts
+ * const user = createUser('John', 'john@example.com');
+ * ```
+ */
+export function createUser(name: string, email: string): User {
+  return { id: generateId(), name, email };
+}
+```
+
+## Build Optimization
+
+```json
+{
+  "compilerOptions": {
+    // Performance
+    "skipLibCheck": true,
+    "skipDefaultLibCheck": true,
+
+    // Faster builds
+    "incremental": true,
+    "assumeChangesOnlyAffectDirectDependencies": true,
+
+    // Smaller output
+    "removeComments": true,
+    "importHelpers": true,
+
+    // Tree shaking support
+    "module": "ESNext",
+    "target": "ES2020"
+  }
+}
+```
+
+## Multiple Configurations
+
+```json
+// tsconfig.json (base)
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "ES2022"
+  }
+}
+
+// tsconfig.build.json (production)
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "sourceMap": false,
+    "removeComments": true,
+    "declaration": true
+  },
+  "exclude": ["**/*.test.ts", "**/*.spec.ts"]
+}
+
+// tsconfig.test.json (testing)
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["jest", "node"],
+    "esModuleInterop": true
+  },
+  "include": ["src/**/*.test.ts", "src/**/*.spec.ts"]
+}
+```
+
+## Framework-Specific Configs
+
+```json
+// React + Vite
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "strict": true
+  }
+}
+
+// Next.js
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+
+// Node.js + Express
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "sourceMap": true
+  }
+}
+```
+
+## Custom Type Definitions
+
+```typescript
+// src/types/global.d.ts
+declare global {
+  interface Window {
+    myApp: {
+      version: string;
+      config: AppConfig;
+    };
+  }
+
+  namespace NodeJS {
+    interface ProcessEnv {
+      DATABASE_URL: string;
+      API_KEY: string;
+      NODE_ENV: 'development' | 'production' | 'test';
+    }
+  }
+}
+
+export {};
+
+// src/types/modules.d.ts
+declare module '*.svg' {
+  const content: string;
+  export default content;
+}
+
+declare module '*.css' {
+  const classes: { [key: string]: string };
+  export default classes;
+}
+
+declare module 'untyped-library' {
+  export function doSomething(value: string): number;
+}
+```
+
+## Compiler API Usage
+
+```typescript
+// programmatic compilation
+import ts from 'typescript';
+
+function compile(fileNames: string[], options: ts.CompilerOptions): void {
+  const program = ts.createProgram(fileNames, options);
+  const emitResult = program.emit();
+
+  const allDiagnostics = ts
+    .getPreEmitDiagnostics(program)
+    .concat(emitResult.diagnostics);
+
+  allDiagnostics.forEach(diagnostic => {
+    if (diagnostic.file) {
+      const { line, character } = ts.getLineAndCharacterOfPosition(
+        diagnostic.file,
+        diagnostic.start!
+      );
+      const message = ts.flattenDiagnosticMessageText(
+        diagnostic.messageText,
+        '\n'
+      );
+      console.log(
+        `${diagnostic.file.fileName} (${line + 1},${character + 1}): ${message}`
+      );
+    } else {
+      console.log(
+        ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')
+      );
+    }
+  });
+
+  const exitCode = emitResult.emitSkipped ? 1 : 0;
+  console.log(`Process exiting with code '${exitCode}'.`);
+  process.exit(exitCode);
+}
+
+compile(['src/index.ts'], {
+  noEmitOnError: true,
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ES2022,
+  strict: true
+});
+```
+
+## Performance Monitoring
+
+```json
+{
+  "compilerOptions": {
+    "diagnostics": true,
+    "extendedDiagnostics": true,
+    "generateCpuProfile": "profile.cpuprofile",
+    "explainFiles": true
+  }
+}
+```
+
+```bash
+# Run with diagnostics
+tsc --diagnostics
+
+# Extended diagnostics
+tsc --extendedDiagnostics
+
+# Generate trace
+tsc --generateTrace trace
+
+# Analyze with @typescript/analyze-trace
+npx @typescript/analyze-trace trace
+```
+
+## Quick Reference
+
+| Option | Purpose |
+|--------|---------|
+| `strict` | Enable all strict checks |
+| `composite` | Enable project references |
+| `incremental` | Enable incremental compilation |
+| `skipLibCheck` | Skip .d.ts checking for faster builds |
+| `esModuleInterop` | Better CommonJS interop |
+| `moduleResolution` | How modules are resolved |
+| `paths` | Path mapping for imports |
+| `declaration` | Generate .d.ts files |
+| `sourceMap` | Generate source maps |
+| `noEmit` | Don't emit output (type check only) |
+| `isolatedModules` | Each file can be transpiled separately |
+| `allowImportingTsExtensions` | Import .ts files directly |