@bastani/atomic 0.5.11 → 0.5.12-1

package/.agents/skills/typescript-expert/scripts/ts_diagnostic.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""
+TypeScript Project Diagnostic Script
+Analyzes TypeScript projects for configuration, performance, and common issues.
+"""
+
+import subprocess
+import sys
+import os
+import json
+from pathlib import Path
+
+def run_cmd(cmd: str) -> str:
+    """Run shell command and return output."""
+    try:
+        result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+        return result.stdout + result.stderr
+    except Exception as e:
+        return str(e)
+
+def check_versions():
+    """Check TypeScript and Node versions."""
+    print("\n📦 Versions:")
+    print("-" * 40)
+    
+    ts_version = run_cmd("npx tsc --version 2>/dev/null").strip()
+    node_version = run_cmd("node -v 2>/dev/null").strip()
+    
+    print(f"  TypeScript: {ts_version or 'Not found'}")
+    print(f"  Node.js: {node_version or 'Not found'}")
+
+def check_tsconfig():
+    """Analyze tsconfig.json settings."""
+    print("\n⚙️ TSConfig Analysis:")
+    print("-" * 40)
+    
+    tsconfig_path = Path("tsconfig.json")
+    if not tsconfig_path.exists():
+        print("⚠️ tsconfig.json not found")
+        return
+    
+    try:
+        with open(tsconfig_path) as f:
+            config = json.load(f)
+        
+        compiler_opts = config.get("compilerOptions", {})
+        
+        # Check strict mode
+        if compiler_opts.get("strict"):
+            print("✅ Strict mode enabled")
+        else:
+            print("⚠️ Strict mode NOT enabled")
+        
+        # Check important flags
+        flags = {
+            "noUncheckedIndexedAccess": "Unchecked index access protection",
+            "noImplicitOverride": "Implicit override protection",
+            "skipLibCheck": "Skip lib check (performance)",
+            "incremental": "Incremental compilation"
+        }
+        
+        for flag, desc in flags.items():
+            status = "✅" if compiler_opts.get(flag) else "⚪"
+            print(f"  {status} {desc}: {compiler_opts.get(flag, 'not set')}")
+        
+        # Check module settings
+        print(f"\n  Module: {compiler_opts.get('module', 'not set')}")
+        print(f"  Module Resolution: {compiler_opts.get('moduleResolution', 'not set')}")
+        print(f"  Target: {compiler_opts.get('target', 'not set')}")
+        
+    except json.JSONDecodeError:
+        print("❌ Invalid JSON in tsconfig.json")
+
+def check_tooling():
+    """Detect TypeScript tooling ecosystem."""
+    print("\n🛠️ Tooling Detection:")
+    print("-" * 40)
+    
+    pkg_path = Path("package.json")
+    if not pkg_path.exists():
+        print("⚠️ package.json not found")
+        return
+    
+    try:
+        with open(pkg_path) as f:
+            pkg = json.load(f)
+        
+        all_deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+        
+        tools = {
+            "biome": "Biome (linter/formatter)",
+            "eslint": "ESLint",
+            "prettier": "Prettier",
+            "vitest": "Vitest (testing)",
+            "jest": "Jest (testing)",
+            "turborepo": "Turborepo (monorepo)",
+            "turbo": "Turbo (monorepo)",
+            "nx": "Nx (monorepo)",
+            "lerna": "Lerna (monorepo)"
+        }
+        
+        for tool, desc in tools.items():
+            for dep in all_deps:
+                if tool in dep.lower():
+                    print(f"  ✅ {desc}")
+                    break
+                    
+    except json.JSONDecodeError:
+        print("❌ Invalid JSON in package.json")
+
+def check_monorepo():
+    """Check for monorepo configuration."""
+    print("\n📦 Monorepo Check:")
+    print("-" * 40)
+    
+    indicators = [
+        ("pnpm-workspace.yaml", "PNPM Workspace"),
+        ("lerna.json", "Lerna"),
+        ("nx.json", "Nx"),
+        ("turbo.json", "Turborepo")
+    ]
+    
+    found = False
+    for file, name in indicators:
+        if Path(file).exists():
+            print(f"  ✅ {name} detected")
+            found = True
+    
+    if not found:
+        print("  ⚪ No monorepo configuration detected")
+
+def check_type_errors():
+    """Run quick type check."""
+    print("\n🔍 Type Check:")
+    print("-" * 40)
+    
+    result = run_cmd("npx tsc --noEmit 2>&1 | head -20")
+    if "error TS" in result:
+        errors = result.count("error TS")
+        print(f"  ❌ {errors}+ type errors found")
+        print(result[:500])
+    else:
+        print("  ✅ No type errors")
+
+def check_any_usage():
+    """Check for any type usage."""
+    print("\n⚠️ 'any' Type Usage:")
+    print("-" * 40)
+    
+    result = run_cmd("grep -r ': any' --include='*.ts' --include='*.tsx' src/ 2>/dev/null | wc -l")
+    count = result.strip()
+    if count and count != "0":
+        print(f"  ⚠️ Found {count} occurrences of ': any'")
+        sample = run_cmd("grep -rn ': any' --include='*.ts' --include='*.tsx' src/ 2>/dev/null | head -5")
+        if sample:
+            print(sample)
+    else:
+        print("  ✅ No explicit 'any' types found")
+
+def check_type_assertions():
+    """Check for type assertions."""
+    print("\n⚠️ Type Assertions (as):")
+    print("-" * 40)
+    
+    result = run_cmd("grep -r ' as ' --include='*.ts' --include='*.tsx' src/ 2>/dev/null | grep -v 'import' | wc -l")
+    count = result.strip()
+    if count and count != "0":
+        print(f"  ⚠️ Found {count} type assertions")
+    else:
+        print("  ✅ No type assertions found")
+
+def check_performance():
+    """Check type checking performance."""
+    print("\n⏱️ Type Check Performance:")
+    print("-" * 40)
+    
+    result = run_cmd("npx tsc --extendedDiagnostics --noEmit 2>&1 | grep -E 'Check time|Files:|Lines:|Nodes:'")
+    if result.strip():
+        for line in result.strip().split('\n'):
+            print(f"  {line}")
+    else:
+        print("  ⚠️ Could not measure performance")
+
+def main():
+    print("=" * 50)
+    print("🔍 TypeScript Project Diagnostic Report")
+    print("=" * 50)
+    
+    check_versions()
+    check_tsconfig()
+    check_tooling()
+    check_monorepo()
+    check_any_usage()
+    check_type_assertions()
+    check_type_errors()
+    check_performance()
+    
+    print("\n" + "=" * 50)
+    print("✅ Diagnostic Complete")
+    print("=" * 50)
+
+if __name__ == "__main__":
+    main()

package/.agents/skills/typescript-react-reviewer/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: typescript-react-reviewer
+description: "Expert code reviewer for TypeScript + React 19 applications. Use when reviewing React code, identifying anti-patterns, evaluating state management, or assessing code maintainability. Triggers: code review requests, PR reviews, React architecture evaluation, identifying code smells, TypeScript type safety checks, useEffect abuse detection, state management review."
+metadata:
+   internal: true
+---
+
+# TypeScript + React 19 Code Review Expert
+
+Expert code reviewer with deep knowledge of React 19's new features, TypeScript best practices, state management patterns, and common anti-patterns.
+
+## Review Priority Levels
+
+### 🚫 Critical (Block Merge)
+
+These issues cause bugs, memory leaks, or architectural problems:
+
+| Issue                                          | Why It's Critical                   |
+| ---------------------------------------------- | ----------------------------------- |
+| `useEffect` for derived state                  | Extra render cycle, sync bugs       |
+| Missing cleanup in `useEffect`                 | Memory leaks                        |
+| Direct state mutation (`.push()`, `.splice()`) | Silent update failures              |
+| Conditional hook calls                         | Breaks Rules of Hooks               |
+| `key={index}` in dynamic lists                 | State corruption on reorder         |
+| `any` type without justification               | Type safety bypass                  |
+| `useFormStatus` in same component as `<form>`  | Always returns false (React 19 bug) |
+| Promise created inside render with `use()`     | Infinite loop                       |
+
+### ⚠️ High Priority
+
+| Issue                                         | Impact                          |
+| --------------------------------------------- | ------------------------------- |
+| Incomplete dependency arrays                  | Stale closures, missing updates |
+| Props typed as `any`                          | Runtime errors                  |
+| Unjustified `useMemo`/`useCallback`           | Unnecessary complexity          |
+| Missing Error Boundaries                      | Poor error UX                   |
+| Controlled input initialized with `undefined` | React warning                   |
+
+### 📝 Architecture/Style
+
+| Issue                             | Recommendation                |
+| --------------------------------- | ----------------------------- |
+| Component > 300 lines             | Split into smaller components |
+| Prop drilling > 2-3 levels        | Use composition or context    |
+| State far from usage              | Colocate state                |
+| Custom hooks without `use` prefix | Follow naming convention      |
+
+## Quick Detection Patterns
+
+### useEffect Abuse (Most Common Anti-Pattern)
+
+```typescript
+// ❌ WRONG: Derived state in useEffect
+const [firstName, setFirstName] = useState('');
+const [fullName, setFullName] = useState('');
+useEffect(() => {
+  setFullName(firstName + ' ' + lastName);
+}, [firstName, lastName]);
+
+// ✅ CORRECT: Compute during render
+const fullName = firstName + ' ' + lastName;
+```
+
+```typescript
+// ❌ WRONG: Event logic in useEffect
+useEffect(() => {
+  if (product.isInCart) showNotification('Added!');
+}, [product]);
+
+// ✅ CORRECT: Logic in event handler
+function handleAddToCart() {
+  addToCart(product);
+  showNotification('Added!');
+}
+```
+
+### React 19 Hook Mistakes
+
+```typescript
+// ❌ WRONG: useFormStatus in form component (always returns false)
+function Form() {
+  const { pending } = useFormStatus();
+  return <form action={submit}><button disabled={pending}>Send</button></form>;
+}
+
+// ✅ CORRECT: useFormStatus in child component
+function SubmitButton() {
+  const { pending } = useFormStatus();
+  return <button type="submit" disabled={pending}>Send</button>;
+}
+function Form() {
+  return <form action={submit}><SubmitButton /></form>;
+}
+```
+
+```typescript
+// ❌ WRONG: Promise created in render (infinite loop)
+function Component() {
+  const data = use(fetch('/api/data')); // New promise every render!
+}
+
+// ✅ CORRECT: Promise from props or state
+function Component({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise);
+}
+```
+
+### State Mutation Detection
+
+```typescript
+// ❌ WRONG: Mutations (no re-render)
+items.push(newItem);
+setItems(items);
+
+arr[i] = newValue;
+setArr(arr);
+
+// ✅ CORRECT: Immutable updates
+setItems([...items, newItem]);
+setArr(arr.map((x, idx) => idx === i ? newValue : x));
+```
+
+### TypeScript Red Flags
+
+```typescript
+// ❌ Red flags to catch
+const data: any = response;           // Unsafe any
+const items = arr[10];                // Missing undefined check
+const App: React.FC<Props> = () => {}; // Discouraged pattern
+
+// ✅ Preferred patterns
+const data: ResponseType = response;
+const items = arr[10]; // with noUncheckedIndexedAccess
+const App = ({ prop }: Props) => {};  // Explicit props
+```
+
+## Review Workflow
+
+1. **Scan for critical issues first** - Check for the patterns in "Critical (Block Merge)" section
+2. **Check React 19 usage** - See [react19-patterns.md](references/react19-patterns.md) for new API patterns
+3. **Evaluate state management** - Is state colocated? Server state vs client state separation?
+4. **Assess TypeScript safety** - Generic components, discriminated unions, strict config
+5. **Review for maintainability** - Component size, hook design, folder structure
+
+## Reference Documents
+
+For detailed patterns and examples:
+
+- **[react19-patterns.md](references/react19-patterns.md)** - React 19 new hooks (useActionState, useOptimistic, use), Server/Client Component boundaries
+- **[antipatterns.md](references/antipatterns.md)** - Comprehensive anti-pattern catalog with fixes
+- **[checklist.md](references/checklist.md)** - Full code review checklist for thorough reviews
+
+## State Management Quick Guide
+
+| Data Type                  | Solution                                   |
+| -------------------------- | ------------------------------------------ |
+| Server/async data          | TanStack Query (never copy to local state) |
+| Simple global UI state     | Zustand (~1KB, no Provider)                |
+| Fine-grained derived state | Jotai (~2.4KB)                             |
+| Component-local state      | useState/useReducer                        |
+| Form state                 | React 19 useActionState                    |
+
+### TanStack Query Anti-Pattern
+
+```typescript
+// ❌ NEVER copy server data to local state
+const { data } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos });
+const [todos, setTodos] = useState([]);
+useEffect(() => setTodos(data), [data]);
+
+// ✅ Query IS the source of truth
+const { data: todos } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos });
+```
+
+## TypeScript Config Recommendations
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+`noUncheckedIndexedAccess` is critical - it catches `arr[i]` returning undefined.
+
+## Immediate Red Flags
+
+When reviewing, flag these immediately:
+
+| Pattern                                      | Problem                     | Fix                |
+| -------------------------------------------- | --------------------------- | ------------------ |
+| `eslint-disable react-hooks/exhaustive-deps` | Hides stale closure bugs    | Refactor logic     |
+| Component defined inside component           | Remounts every render       | Move outside       |
+| `useState(undefined)` for inputs             | Uncontrolled warning        | Use empty string   |
+| `React.FC` with generics                     | Generic inference breaks    | Use explicit props |
+| Barrel files (`index.ts`) in app code        | Bundle bloat, circular deps | Direct imports     |