devflow-kit 0.9.0 → 1.1.0

package/shared/skills/performance-patterns/references/violations.md

@@ -0,0 +1,354 @@
+# Performance Violation Examples
+
+Extended violation patterns for performance reviews. Reference from main SKILL.md.
+
+## Algorithmic Violations
+
+### N+1 Query Variants
+
+**ORM Eager Loading Missing**
+```typescript
+// VIOLATION: Lazy loading triggers N queries
+const posts = await Post.findAll();
+for (const post of posts) {
+  console.log(post.author.name);  // N additional queries
+}
+```
+
+**GraphQL Resolver N+1**
+```typescript
+// VIOLATION: Resolver called per item
+const resolvers = {
+  Post: {
+    author: async (post) => {
+      return db.users.findById(post.authorId);  // N queries
+    }
+  }
+};
+```
+
+**Nested Loop Queries**
+```typescript
+// VIOLATION: Query inside nested loop
+for (const category of categories) {
+  for (const product of category.products) {
+    const reviews = await db.reviews.findByProductId(product.id);  // N*M queries
+  }
+}
+```
+
+### O(n^2) or Worse Patterns
+
+**Array.includes in Loop**
+```typescript
+// VIOLATION: O(n^2) - includes is O(n)
+function removeDuplicates(items: Item[]) {
+  const unique: Item[] = [];
+  for (const item of items) {
+    if (!unique.some(u => u.id === item.id)) {  // O(n) check each time
+      unique.push(item);
+    }
+  }
+  return unique;
+}
+```
+
+**Nested Array Methods**
+```typescript
+// VIOLATION: O(n*m) - filter inside map
+function matchItems(list1: Item[], list2: Item[]) {
+  return list1.map(item => ({
+    ...item,
+    matches: list2.filter(i => i.category === item.category)  // O(m) per item
+  }));
+}
+```
+
+**String Concatenation in Loop**
+```typescript
+// VIOLATION: O(n^2) string copies
+function buildCsv(rows: string[][]): string {
+  let csv = '';
+  for (const row of rows) {
+    csv += row.join(',') + '\n';  // Creates new string each time
+  }
+  return csv;
+}
+```
+
+### Inefficient Data Structure Usage
+
+**Object.keys/values/entries in Hot Path**
+```typescript
+// VIOLATION: Creates new array on each call
+function findInObject(obj: Record<string, Item>, predicate: (item: Item) => boolean) {
+  for (const key of Object.keys(obj)) {  // Allocates array
+    if (predicate(obj[key])) {
+      return obj[key];
+    }
+  }
+}
+```
+
+**Array as Queue/Stack**
+```typescript
+// VIOLATION: shift() is O(n)
+class Queue<T> {
+  private items: T[] = [];
+
+  dequeue(): T | undefined {
+    return this.items.shift();  // O(n) - reindexes entire array
+  }
+}
+```
+
+---
+
+## Database Violations
+
+### Missing Index Patterns
+
+**Unindexed Foreign Key**
+```sql
+-- VIOLATION: Joins without index
+SELECT * FROM orders o
+JOIN order_items oi ON o.id = oi.order_id  -- order_id likely unindexed
+WHERE o.customer_id = 123;
+```
+
+**Unindexed Filter Column**
+```typescript
+// VIOLATION: Filters on unindexed column
+const activeUsers = await db.query(
+  'SELECT * FROM users WHERE last_login > ?',  // last_login probably unindexed
+  [thirtyDaysAgo]
+);
+```
+
+**Composite Index Order Wrong**
+```sql
+-- Index exists: (customer_id, status)
+-- VIOLATION: Query doesn't use index efficiently
+SELECT * FROM orders WHERE status = 'pending';  -- Can't use composite index
+```
+
+### Inefficient Queries
+
+**LIKE with Leading Wildcard**
+```typescript
+// VIOLATION: Can't use index
+const results = await db.query(
+  'SELECT * FROM products WHERE name LIKE ?',
+  ['%laptop%']  // Leading % prevents index usage
+);
+```
+
+**OR Instead of IN**
+```typescript
+// VIOLATION: OR conditions often slower
+const users = await db.query(
+  'SELECT * FROM users WHERE status = ? OR status = ? OR status = ?',
+  ['active', 'pending', 'trial']
+);
+
+// Better: Use IN clause
+const users = await db.query(
+  'SELECT * FROM users WHERE status IN (?, ?, ?)',
+  ['active', 'pending', 'trial']
+);
+```
+
+**Sorting Without Index**
+```typescript
+// VIOLATION: ORDER BY on unindexed column causes filesort
+const recent = await db.query(
+  'SELECT * FROM logs ORDER BY created_at DESC LIMIT 100'  // No index on created_at
+);
+```
+
+---
+
+## Memory Violations
+
+### Memory Leak Patterns
+
+**Closure Retaining Large Object**
+```typescript
+// VIOLATION: Closure keeps entire large object alive
+function processLargeData(data: LargeObject) {
+  return () => {
+    console.log(data.id);  // Only needs id, but retains entire data object
+  };
+}
+```
+
+**Timer Without Cleanup**
+```typescript
+// VIOLATION: Interval never cleared
+class Poller {
+  start() {
+    setInterval(() => this.poll(), 1000);  // Runs forever
+  }
+}
+```
+
+**Observable Without Unsubscribe**
+```typescript
+// VIOLATION: Subscription never cleaned up
+class Component {
+  init() {
+    eventBus.subscribe('update', this.handleUpdate);  // Memory leak
+  }
+  // Missing cleanup method
+}
+```
+
+### Large Allocation Patterns
+
+**Spreading in Reduce**
+```typescript
+// VIOLATION: Creates new object on each iteration
+const merged = items.reduce((acc, item) => ({
+  ...acc,  // Copies entire accumulator each time
+  [item.id]: item
+}), {});
+```
+
+**Array.concat in Loop**
+```typescript
+// VIOLATION: Creates new array each iteration
+let all: Item[] = [];
+for (const batch of batches) {
+  all = all.concat(batch);  // O(n^2) total allocations
+}
+```
+
+**JSON Clone in Hot Path**
+```typescript
+// VIOLATION: Full serialization/parsing
+function processItem(item: Item) {
+  const copy = JSON.parse(JSON.stringify(item));  // Expensive!
+  // ... modify copy
+}
+```
+
+---
+
+## I/O Violations
+
+### Blocking Operations
+
+**Sync File Operations in Request Handler**
+```typescript
+// VIOLATION: Blocks event loop
+app.get('/config', (req, res) => {
+  const config = fs.readFileSync('./config.json');  // Blocks!
+  res.json(JSON.parse(config));
+});
+```
+
+**Sync Crypto Operations**
+```typescript
+// VIOLATION: CPU-intensive sync operation
+function hashPassword(password: string): string {
+  return crypto.pbkdf2Sync(password, salt, 100000, 64, 'sha512');  // Blocks!
+}
+```
+
+### Sequential vs Parallel
+
+**await in forEach (No Parallelism)**
+```typescript
+// VIOLATION: forEach doesn't wait, unpredictable behavior
+ids.forEach(async (id) => {
+  await processItem(id);  // Fire and forget!
+});
+```
+
+**Sequential Processing When Order Doesn't Matter**
+```typescript
+// VIOLATION: Could be parallel
+async function validateAll(items: Item[]) {
+  const results = [];
+  for (const item of items) {
+    results.push(await validate(item));  // Sequential but independent
+  }
+  return results;
+}
+```
+
+### Redundant Operations
+
+**Same Data Fetched Multiple Times**
+```typescript
+// VIOLATION: Duplicate API calls
+async function buildReport(userId: string) {
+  const user = await getUser(userId);
+  const profile = await getUserProfile(userId);  // Probably same data
+  const permissions = await getUserPermissions(userId);  // Another call
+}
+```
+
+**Cache Miss on Every Request**
+```typescript
+// VIOLATION: No caching strategy
+async function getConfig() {
+  return await fetchFromRemote('/config');  // Network call every time
+}
+```
+
+---
+
+## Frontend Violations
+
+### Re-render Patterns
+
+**Inline Object/Array in JSX**
+```tsx
+// VIOLATION: New reference every render
+<Component
+  options={{ show: true, animate: false }}  // New object each render
+  items={[1, 2, 3]}  // New array each render
+/>
+```
+
+**Inline Arrow in JSX**
+```tsx
+// VIOLATION: New function every render
+<Button onClick={() => handleClick(item.id)} />  // New function each render
+```
+
+**Missing Key or Index as Key**
+```tsx
+// VIOLATION: Index as key breaks reconciliation
+{items.map((item, index) => (
+  <Item key={index} {...item} />  // Index key causes issues on reorder
+))}
+```
+
+### Missing Optimization
+
+**Expensive Computation Every Render**
+```tsx
+// VIOLATION: Recalculates on every render
+function Dashboard({ data }) {
+  const stats = computeExpensiveStats(data);  // Runs every render
+  return <Stats data={stats} />;
+}
+```
+
+**Unthrottled Event Handler**
+```tsx
+// VIOLATION: Fires on every scroll pixel
+window.addEventListener('scroll', () => {
+  updateParallax();  // 60+ calls per second
+});
+```
+
+**Large Component Tree Without Code Splitting**
+```tsx
+// VIOLATION: Loads everything upfront
+import HugeChartLibrary from 'huge-chart-lib';
+import RarelyUsedFeature from './RarelyUsedFeature';
+// All loaded even if not used
+```

package/shared/skills/react/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: react
+description: This skill should be used when the user works with React components (.tsx/.jsx), asks about "hooks", "state management", "context providers", "memo optimization", "useEffect", or discusses component composition and rendering performance. Provides patterns for hooks, state, effects, memoization, and React-specific architecture.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.tsx"
+    - "**/*.jsx"
+  exclude:
+    - "node_modules/**"
+    - "**/*.test.*"
+    - "**/*.spec.*"
+---
+
+# React Patterns
+
+Reference for React-specific patterns, component design, hooks, and performance optimization.
+
+## Iron Law
+
+> **COMPOSITION OVER PROPS**
+>
+> Use children and compound components, not prop drilling. If a component has >5 props,
+> it's doing too much. Split it. If you're passing data through 3+ levels, use context
+> or composition. Props are for configuration, not data plumbing.
+
+## When This Skill Activates
+
+- Working with React codebases
+- Creating components and hooks
+- Managing state and side effects
+- Optimizing render performance
+
+---
+
+## Component Patterns
+
+### Functional Component Structure
+
+```tsx
+export function UserCard({ user, className }: UserCardProps) {
+  const [isExpanded, setIsExpanded] = useState(false); // 1. Hooks first
+  const displayName = user.firstName + ' ' + user.lastName; // 2. Derived state
+  const handleToggle = () => setIsExpanded((prev) => !prev); // 3. Handlers
+  return ( // 4. Render
+    <div className={cn('user-card', className)}>
+      <h3>{displayName}</h3>
+      {isExpanded && <UserDetails user={user} />}
+      <button onClick={handleToggle}>{isExpanded ? 'Collapse' : 'Expand'}</button>
+    </div>
+  );
+}
+```
+
+### Composition Over Props
+
+```tsx
+function Card({ children }: { children: React.ReactNode }) {
+  return <div className="card">{children}</div>;
+}
+Card.Header = ({ children }) => <div className="card-header">{children}</div>;
+Card.Body = ({ children }) => <div className="card-body">{children}</div>;
+
+// Usage - flexible, not rigid props
+<Card>
+  <Card.Header><h2>Title</h2></Card.Header>
+  <Card.Body><p>Content</p></Card.Body>
+</Card>
+```
+
+---
+
+## Hook Patterns
+
+```tsx
+function useLocalStorage<T>(key: string, initialValue: T) {
+  const [value, setValue] = useState<T>(() => {
+    const stored = localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initialValue;
+  });
+  useEffect(() => localStorage.setItem(key, JSON.stringify(value)), [key, value]);
+  return [value, setValue] as const;
+}
+```
+
+---
+
+## State Management
+
+```tsx
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+export function AuthProvider({ children }: { children: React.ReactNode }) {
+  const [user, setUser] = useState<User | null>(null);
+  const login = async (creds: Credentials) => setUser(await authApi.login(creds));
+  const logout = () => { authApi.logout(); setUser(null); };
+  return <AuthContext.Provider value={{ user, login, logout }}>{children}</AuthContext.Provider>;
+}
+
+export function useAuth() {
+  const ctx = useContext(AuthContext);
+  if (!ctx) throw new Error('useAuth must be used within AuthProvider');
+  return ctx;
+}
+```
+
+---
+
+## Performance
+
+```tsx
+function UserList({ users, filter }: { users: User[]; filter: string }) {
+  const filtered = useMemo(() => users.filter((u) => u.name.includes(filter)), [users, filter]);
+  const onClick = useCallback(() => console.log('Clicked'), []);
+  return <ul>{filtered.map((u) => <MemoItem key={u.id} user={u} onClick={onClick} />)}</ul>;
+}
+const MemoItem = memo(({ user }: { user: User }) => <li>{user.name}</li>);
+```
+
+---
+
+## Async Parallelization
+
+```tsx
+// CORRECT: Independent fetches run in parallel
+async function loadDashboard(userId: string) {
+  const [user, orders, preferences] = await Promise.all([
+    fetchUser(userId),
+    fetchOrders(userId),
+    fetchPreferences(userId),
+  ]);
+  return { user, orders, preferences };
+}
+
+// VIOLATION: Sequential fetches (3x slower)
+async function loadDashboardSlow(userId: string) {
+  const user = await fetchUser(userId);
+  const orders = await fetchOrders(userId);
+  const preferences = await fetchPreferences(userId);
+  return { user, orders, preferences };
+}
+```
+
+---
+
+## Bundle Size
+
+```tsx
+// CORRECT: Direct imports (tree-shakable)
+import { Button } from '@/components/Button';
+import { Card } from '@/components/Card';
+
+// VIOLATION: Barrel imports (imports entire library)
+import { Button, Card } from '@/components';
+
+// CORRECT: Dynamic import for heavy components
+const Chart = lazy(() => import('./Chart'));
+const Editor = lazy(() => import('./Editor'));
+
+function Dashboard() {
+  return (
+    <Suspense fallback={<Skeleton />}>
+      {showChart && <Chart data={data} />}
+    </Suspense>
+  );
+}
+```
+
+---
+
+## Re-render Optimization
+
+```tsx
+// CORRECT: Primitive deps (stable references)
+useEffect(() => {
+  fetchData(userId, isActive);
+}, [userId, isActive]); // primitives don't cause unnecessary runs
+
+// VIOLATION: Object/array deps (new reference every render)
+useEffect(() => {
+  fetchData(options);
+}, [options]); // { page: 1 } !== { page: 1 }
+
+// CORRECT: Stable callback with useCallback
+const handleClick = useCallback((id: string) => {
+  setSelected(id);
+}, []); // no deps = stable reference
+
+// VIOLATION: Inline function (new reference every render)
+<List onItemClick={(id) => setSelected(id)} />
+```
+
+---
+
+## Image Optimization
+
+```tsx
+// CORRECT: Optimized image with all attributes
+<img
+  src={url}
+  alt={description}
+  width={400}
+  height={300}
+  loading="lazy"
+  decoding="async"
+  style={{ aspectRatio: '4/3' }}
+/>
+
+// VIOLATION: Unoptimized image
+<img src={url} />  // No dimensions, no lazy loading, layout shift
+```
+
+---
+
+## Data Structure Performance
+
+```tsx
+// CORRECT: Set for O(1) membership checks
+const selectedIds = new Set(selected);
+const isSelected = (id: string) => selectedIds.has(id);
+
+// VIOLATION: Array.includes is O(n)
+const isSelected = (id: string) => selected.includes(id);
+
+// CORRECT: Map for key-value lookups
+const usersById = new Map(users.map(u => [u.id, u]));
+const getUser = (id: string) => usersById.get(id);
+
+// VIOLATION: Array.find is O(n)
+const getUser = (id: string) => users.find(u => u.id === id);
+```
+
+---
+
+## Anti-Patterns
+
+```tsx
+// BAD: Derived state in useState | GOOD: useMemo
+const filtered = useMemo(() => items.filter(i => i.active), [items]);
+
+// BAD: Missing dependency | GOOD: Include all deps
+useEffect(() => { fetchData(userId); }, [userId]);
+
+// BAD: State update in render | GOOD: Use effect
+useEffect(() => { setState(value); }, [value]);
+```
+
+---
+
+## Extended References
+
+- `references/patterns.md` - Render props, reducers, virtualization, lazy loading
+- `references/hooks.md` - useQuery, useDebouncedValue, usePrevious, useClickOutside
+- `references/forms.md` - Controlled forms, validation hooks, multi-step forms
+- `references/error-handling.md` - Error boundaries, async error handling
+
+---
+
+## Checklist
+
+- [ ] Hooks at top level only
+- [ ] All useEffect deps included
+- [ ] useCallback for handlers passed to children
+- [ ] useMemo for expensive computations
+- [ ] Context at appropriate level
+- [ ] Error boundaries around risky components
+- [ ] Keys on list items (not index)
+- [ ] Loading/error states handled
+- [ ] Accessibility (aria-*, role)
+- [ ] Independent fetches parallelized with Promise.all
+- [ ] No barrel imports (direct imports for tree-shaking)
+- [ ] Large components lazy-loaded
+- [ ] Object/array deps avoided in useEffect (use primitives)
+- [ ] Set/Map used for lookups instead of Array.includes/find
+- [ ] Images have dimensions, lazy loading, and aspect-ratio