ghcopilot-hub 1.0.0

package/hub/skills/typescript/references/perf-execution-cache-locality.md

@@ -0,0 +1,178 @@
+# Predictable Execution and Cache Locality
+
+## Load Scope & Quick Navigation
+
+Load this file for data-layout and access-pattern optimization (sequential access, struct-of-arrays, branch predictability).
+
+Do NOT load this file for basic TS syntax, naming conventions, or type-system-only concerns.
+
+Quick navigation:
+
+- Access pattern choice → [Sequential vs Random Access](#sequential-vs-random-access)
+- Data layout choice → [Struct-of-Arrays vs Array-of-Structs](#struct-of-arrays-vs-array-of-structs)
+
+## Issues
+
+- Poor data structure layout for access pattern
+- Random access patterns that could be sequential
+- Struct-of-arrays vs array-of-structs mismatches
+- Scattered memory access in tight loops
+- Unpredictable control flow
+
+## Optimizations
+
+- Sequential memory access patterns
+- Group related data together
+- Use flat arrays instead of nested structures
+- Consider columnar layout for analytics workloads
+- Write code with clear, predictable execution paths
+
+## Examples
+
+### Sequential vs Random Access
+
+**❌ Incorrect: random access pattern**
+
+```ts
+const users = new Map();
+users.set("id1", { name: "Alice", age: 30 });
+users.set("id2", { name: "Bob", age: 25 });
+
+// Random access through Map
+for (const id of shuffledIds) {
+  process(users.get(id));
+}
+```
+
+**✅ Correct: sequential access**
+
+```ts
+const users = [
+  { id: "id1", name: "Alice", age: 30 },
+  { id: "id2", name: "Bob", age: 25 },
+];
+
+// Sequential memory access
+for (let i = 0; i < users.length; i++) {
+  process(users[i]);
+}
+```
+
+### Struct-of-Arrays vs Array-of-Structs
+
+**❌ Incorrect: array-of-structs for columnar access**
+
+```ts
+const particles = [
+  { x: 1, y: 2, vx: 0.1, vy: 0.2 },
+  { x: 3, y: 4, vx: 0.3, vy: 0.4 },
+  // ... thousands more
+];
+
+// Need only x coordinates - poor cache usage
+for (let i = 0; i < particles.length; i++) {
+  updateX(particles[i].x);
+}
+```
+
+**✅ Correct: struct-of-arrays for columnar workload**
+
+```ts
+const particles = {
+  x: [1, 3 /* ... */],
+  y: [2, 4 /* ... */],
+  vx: [0.1, 0.3 /* ... */],
+  vy: [0.2, 0.4 /* ... */],
+};
+
+// Sequential access to contiguous memory
+for (let i = 0; i < particles.x.length; i++) {
+  updateX(particles.x[i]);
+}
+```
+
+### Flat Arrays vs Nested Structures
+
+**❌ Incorrect: nested object access**
+
+```ts
+const grid = {
+  rows: [{ cells: [{ value: 1 }, { value: 2 }] }, { cells: [{ value: 3 }, { value: 4 }] }],
+};
+
+for (const row of grid.rows) {
+  for (const cell of row.cells) {
+    process(cell.value);
+  }
+}
+```
+
+**✅ Correct: flat array**
+
+```ts
+const values = [1, 2, 3, 4];
+const width = 2;
+
+for (let i = 0; i < values.length; i++) {
+  process(values[i]);
+}
+```
+
+### Group Related Data
+
+**❌ Incorrect: scattered data access**
+
+```ts
+const ids = [1, 2, 3];
+const names = ["Alice", "Bob", "Charlie"];
+const ages = [30, 25, 35];
+
+for (let i = 0; i < ids.length; i++) {
+  processUser(ids[i], names[i], ages[i]);
+}
+```
+
+**✅ Correct: grouped data**
+
+```ts
+const users = [
+  { id: 1, name: "Alice", age: 30 },
+  { id: 2, name: "Bob", age: 25 },
+  { id: 3, name: "Charlie", age: 35 },
+];
+
+for (let i = 0; i < users.length; i++) {
+  const user = users[i];
+  processUser(user.id, user.name, user.age);
+}
+```
+
+### Predictable Control Flow
+
+**❌ Incorrect: unpredictable branches**
+
+```ts
+function process(items) {
+  for (const item of items) {
+    if (Math.random() > 0.5) {
+      handleA(item);
+    } else {
+      handleB(item);
+    }
+  }
+}
+```
+
+**✅ Correct: predictable branches**
+
+```ts
+function process(items) {
+  for (const item of items) {
+    if (item.type === "A") {
+      handleA(item);
+    } else {
+      handleB(item);
+    }
+  }
+}
+```

package/hub/skills/typescript/references/reduce-branching.md

@@ -0,0 +1,147 @@
+# Reduce Branching
+
+## Load Scope & Quick Navigation
+
+Load this file when conditionals/switches are deeply nested or repeated and control flow dominates complexity.
+
+Do NOT load this file when the primary issue is array pass count or cache-locality/data-layout concerns.
+
+Quick navigation:
+
+- Replace conditional chains → [Switch to Lookup Table](#switch-to-lookup-table)
+- Flatten deep nesting → [Nested Conditionals to Early Returns](#nested-conditionals-to-early-returns)
+
+## Issues
+
+- Excessive nested conditionals (>3 levels)
+- Switch statements that could be lookup tables
+- Repeated condition checks in same scope
+- Polymorphic branching on hot paths
+- Type guards that could be avoided
+
+## Optimizations
+
+- Convert switch/if-chains to object/Map lookups
+- Hoist invariant conditions
+- Use early returns to reduce nesting
+- Replace runtime type checks with compile-time guarantees
+
+## Examples
+
+### Switch to Lookup Table
+
+**❌ Incorrect: conditional checks**
+
+```ts
+if (thing === "ONE") {
+  /*...*/
+}
+
+if (thing === "TWO") {
+  /*...*/
+}
+
+if (thing === "THREE") {
+  /*...*/
+}
+```
+
+**✅ Correct: lookup table**
+
+```ts
+const lookup = {
+  ONE: {
+    /*...*/
+  },
+  TWO: {
+    /*...*/
+  },
+  THREE: {
+    /*...*/
+  },
+};
+
+const action = lookup[thing];
+```
+
+### Nested Conditionals to Early Returns
+
+**❌ Incorrect: excessive nesting**
+
+```ts
+function process(data) {
+  if (data) {
+    if (data.isValid) {
+      if (data.user) {
+        if (data.user.hasPermission) {
+          return doWork(data);
+        }
+      }
+    }
+  }
+  return null;
+}
+```
+
+**✅ Correct: early returns**
+
+```ts
+function process(data) {
+  if (!data) return null;
+  if (!data.isValid) return null;
+  if (!data.user) return null;
+  if (!data.user.hasPermission) return null;
+
+  return doWork(data);
+}
+```
+
+### Hoist Invariant Conditions
+
+**❌ Incorrect: repeated checks**
+
+```ts
+for (const item of items) {
+  if (config.enableFeature && item.active) {
+    process(item);
+  }
+}
+```
+
+**✅ Correct: hoist invariant**
+
+```ts
+if (config.enableFeature) {
+  for (const item of items) {
+    if (item.active) {
+      process(item);
+    }
+  }
+}
+```
+
+### Runtime Type Checks to Compile-Time
+
+**❌ Incorrect: runtime branching**
+
+```ts
+function format(value: string | number) {
+  if (typeof value === "string") {
+    return value.toUpperCase();
+  } else {
+    return value.toFixed(2);
+  }
+}
+```
+
+**✅ Correct: separate functions**
+
+```ts
+function formatString(value: string): string {
+  return value.toUpperCase();
+}
+
+function formatNumber(value: number): string {
+  return value.toFixed(2);
+}
+```

package/hub/skills/typescript/references/reduce-looping.md

@@ -0,0 +1,203 @@
+# Reduce Looping
+
+## Load Scope & Quick Navigation
+
+Load this file when performance issues come from extra collection passes, repeated lookups, or nested iterations.
+
+Do NOT load this file for branching structure redesign or type-modeling decisions.
+
+Quick navigation:
+
+- Collapse chained passes → [Chained Methods to Single Reduce](#chained-methods-to-single-reduce)
+- Replace repeated O(n) checks → [Linear Search to O(1) Lookup](#linear-search-to-o1-lookup)
+- Remove nested loop-side filtering → [Array Methods in Loops](#array-methods-in-loops)
+
+## Issues
+
+- Multiple passes over same array (`.map().filter().reduce()`)
+- Unnecessary array creation (spreading, slicing)
+- Array methods in loops
+- Linear searches that could use Sets/Maps
+- Incorrect collection type for access pattern
+
+## Optimizations
+
+- Combine multiple array operations into single pass
+- Use index-based loops for performance-critical paths
+- Replace O(n) lookups with O(1) using Set/Map
+- Use typed arrays for numeric data
+- Reuse arrays when function owns them (local scope, not returned/exposed)
+
+## Examples
+
+### Chained Methods to Single Reduce
+
+**❌ Incorrect: two iterations**
+
+```ts
+const result = arr.filter(predicate).map(mapper);
+```
+
+**✅ Correct: single iteration**
+
+```ts
+const result = arr.reduce((acc, curr) => (predicate(curr) ? [...acc, mapper(curr)] : acc), []);
+```
+
+### Linear Search to O(1) Lookup
+
+**❌ Incorrect: O(n)**
+
+```ts
+const keys = Object.keys(someObj);
+if (keys.includes(id)) {
+  /**/
+}
+```
+
+**✅ Correct: O(1)**
+
+```ts
+const keys = new Set(Object.keys(someObj));
+if (keys.has(id)) {
+  /**/
+}
+```
+
+### Array Methods in Loops
+
+**❌ Incorrect: nested iterations**
+
+```ts
+for (const user of users) {
+  const active = items.filter((item) => item.userId === user.id);
+  process(active);
+}
+```
+
+**✅ Correct: build lookup once**
+
+```ts
+const itemsByUser = new Map();
+for (const item of items) {
+  if (!itemsByUser.has(item.userId)) {
+    itemsByUser.set(item.userId, []);
+  }
+  itemsByUser.get(item.userId).push(item);
+}
+
+for (const user of users) {
+  const active = itemsByUser.get(user.id) || [];
+  process(active);
+}
+```
+
+### Build Index Maps for Repeated Lookups
+
+**❌ Incorrect: (O(n) per lookup)**
+
+```ts
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map((order) => ({
+    ...order,
+    user: users.find((u) => u.id === order.userId),
+  }));
+}
+```
+
+**✅ Correct: (O(1) per lookup)**
+
+```ts
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map((u) => [u.id, u]));
+
+  return orders.map((order) => ({
+    ...order,
+    user: userById.get(order.userId),
+  }));
+}
+```
+
+### Combine Multiple Array Iterations
+
+> Multiple .filter() or .map() calls iterate the array multiple times. Combine into one loop.
+
+**❌ Incorrect: 3 iterations**`
+
+```ts
+const admins = users.filter((u) => u.isAdmin);
+const testers = users.filter((u) => u.isTester);
+const inactive = users.filter((u) => !u.isActive);
+```
+
+**✅ Correct: 1 iteration**
+
+```ts
+const admins: User[] = [];
+const testers: User[] = [];
+const inactive: User[] = [];
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user);
+  if (user.isTester) testers.push(user);
+  if (!user.isActive) inactive.push(user);
+}
+```
+
+### Unnecessary Array Creation
+
+**❌ Incorrect: creates intermediate arrays**
+
+```ts
+const result = [...arr].slice(0, 10).map(transform);
+```
+
+**✅ Correct: process directly**
+
+```ts
+const result = [];
+const len = Math.min(arr.length, 10);
+for (let i = 0; i < len; i++) {
+  result.push(transform(arr[i]));
+}
+```
+
+### Index-Based Loops for Hot Paths
+
+**❌ Incorrect: slower iteration**
+
+```ts
+for (const item of largeArray) {
+  // performance-critical operation
+  processPixel(item);
+}
+```
+
+**✅ Correct: index-based**
+
+```ts
+const len = largeArray.length;
+for (let i = 0; i < len; i++) {
+  processPixel(largeArray[i]);
+}
+```
+
+### Typed Arrays for Numeric Data
+
+**❌ Incorrect: generic array**
+
+```ts
+const pixels = new Array(width * height);
+for (let i = 0; i < pixels.length; i++) {
+  pixels[i] = Math.random() * 255;
+}
+```
+
+**✅ Correct: typed array**
+
+```ts
+const pixels = new Uint8Array(width * height);
+for (let i = 0; i < pixels.length; i++) {
+  pixels[i] = Math.random() * 255;
+}
+```

package/hub/skills/typescript/references/style-and-types.md

@@ -0,0 +1,171 @@
+# TypeScript Style & Typing Notes
+
+## Load Scope & Quick Navigation
+
+Load this file for naming conventions, `satisfies` vs `as const`, baseline utility types, type guards, and `import type` usage.
+
+Do NOT load this file for branch/loop performance diagnostics when dedicated perf references are required.
+
+Quick navigation:
+
+- Naming/casing guidance → [Naming Conventions (Casing)](#naming-conventions-casing)
+- `as const` vs `satisfies` tradeoffs → [as const vs satisfies](#as-const-vs-satisfies)
+- Utility types cheat sheet → [Utility Types](#utility-types)
+- Type guards baseline → [Type Guards](#type-guards)
+- Type-only imports → [Import Types](#import-types)
+
+## Naming Conventions (Casing)
+
+Use a single, consistent casing strategy by context. Avoid mixing styles in the same scope unless required by external systems.
+
+### Recommended Usage
+
+- **camelCase**: variables, functions, methods, local state, parameters.
+- **PascalCase**: types, interfaces, classes, React components.
+- **kebab-case**: URLs, route segments, file names for static assets.
+- **snake_case**: avoid in TS/JS; only for external APIs or database schemas.
+
+### Examples
+
+```ts
+// camelCase
+const userId = "123";
+function getUserById(id: string) {}
+
+// PascalCase
+type UserId = string;
+interface UserProfile {}
+class UserService {}
+
+// kebab-case (URLs)
+// /user-profile/123
+
+// snake_case (external APIs / DB fields)
+interface UserApiResponse {
+  user_id: string;
+  created_at: string;
+}
+```
+
+### Interop Guidance
+
+When consuming snake_case data from APIs, map to camelCase at the boundary (infrastructure layer) so the rest of the app remains consistent.
+
+---
+
+## `as const` vs `satisfies`
+
+### Summary
+
+- **`as const`**: narrows literals and makes values deeply readonly.
+- **`satisfies`**: validates the shape while preserving the most specific inferred type.
+- **Combine both** when you need immutability **and** validation.
+
+### Practical Differences
+
+```ts
+interface Theme {
+  colors: Record<string, string>;
+  spacing: Record<string, number>;
+}
+
+// ✅ Validate shape + keep exact keys
+const theme = {
+  colors: { primary: "#3b82f6", secondary: "#10b981" },
+  spacing: { sm: 8, md: 16, lg: 24 },
+} satisfies Theme;
+
+// ✅ Immutable + validated
+const themeConst = {
+  colors: { primary: "#3b82f6", secondary: "#10b981" },
+  spacing: { sm: 8, md: 16, lg: 24 },
+} as const satisfies Theme;
+
+// ⚠️ `as const` only (no validation)
+const themeOnlyConst = {
+  colors: { primary_typo: "#3b82f6" },
+  spacing: { sm: 8 },
+} as const;
+```
+
+### Common Pitfall
+
+Avoid `const x: Type = ...` for config objects because the type annotation widens literals and erases exact keys. Prefer `satisfies` so typos are caught at compile time while keeping precise inference.
+
+---
+
+## Avoid TypeScript `enum`
+
+### Why
+
+- Adds runtime artifacts and non-idiomatic JS behavior.
+- Creates tight coupling to enum members instead of values.
+- Reduces flexibility when interoperating with plain strings.
+
+### Preferred Alternatives
+
+#### 1) Const object + derived union (recommended)
+
+```ts
+const ROLE = {
+  ADMIN: "ADMIN",
+  USER: "USER",
+  GUEST: "GUEST",
+} as const;
+
+type Role = (typeof ROLE)[keyof typeof ROLE];
+
+function setRole(role: Role) {}
+
+setRole(ROLE.ADMIN);
+setRole("ADMIN");
+```
+
+#### 2) Literal union (small sets)
+
+```ts
+type Size = "sm" | "md" | "lg";
+```
+
+### Avoid
+
+```ts
+enum RoleEnum {
+  ADMIN = "ADMIN",
+  USER = "USER",
+  GUEST = "GUEST",
+}
+```
+
+---
+
+## Utility Types
+
+```ts
+Pick<User, "id" | "name">; // Select fields
+Omit<User, "id">; // Exclude fields
+Partial<User>; // All optional
+Required<User>; // All required
+Readonly<User>; // All readonly
+Record<string, User>; // Object type
+Extract<Union, "a" | "b">; // Extract from union
+Exclude<Union, "a">; // Exclude from union
+NonNullable<T | null>; // Remove null/undefined
+ReturnType<typeof fn>; // Function return type
+Parameters<typeof fn>; // Function params tuple
+```
+
+## Type Guards
+
+```ts
+function isUser(value: unknown): value is User {
+  return typeof value === "object" && value !== null && "id" in value && "name" in value;
+}
+```
+
+## Import Types
+
+```ts
+import type { User } from "./types";
+import { type Config, createUser } from "./utils";
+```

package/hub/skills/typescript/references/type-vs-interface.md

@@ -0,0 +1,27 @@
+# Type vs. Interface
+
+## Load Scope & Quick Navigation
+
+Load this file when deciding modeling strategy for aliases/unions/intersections versus class/declaration-merging contracts.
+
+Do NOT load this file for runtime performance tuning.
+
+Prefer `type` over `interface` for type aliases, unions, intersections, branded types, and functional patterns. Use `interface` only when you absolutely need:
+
+- Declaration merging (intentional extensibility)
+- Class implementation contracts (`implements`)
+- Legacy API compatibility
+
+**❌ Incorrect: interface not preferred for use case**
+
+```ts
+interface AvatarProps {
+  avatar: string;
+}
+```
+
+**✅ Correct: type preferred for use case**
+
+```ts
+type AvatarProps = { avatar: string };
+```