ima-claude 2.18.0 → 2.25.0

package/plugins/ima-claude/skills/js-fp/SKILL.md

@@ -5,64 +5,29 @@ description: "Core FP principles with anti-over-engineering focus - Simple > Com
 
 # JavaScript Functional Programming
 
-Core functional programming principles for JavaScript with anti-over-engineering enforcement. This skill provides error-preventing essentials and references to deep-dive content.
+## CRITICAL: Anti-Over-Engineering
 
-## When to Use This Skill
+**"Simple > Complex | Evidence > Assumptions"**
 
-- Implementing pure, testable functions
-- Need FP architectural guidance
-- Preventing over-engineering and custom FP utility creation
-- Comprehensive testing strategies
-- Evidence-based performance optimization
-
-## ⚠️ CRITICAL: Anti-Over-Engineering (PRIMARY FOCUS)
-
-**Core Principle**: "Simple > Complex | Evidence > Assumptions"
-
-> **Clarification**: This skill prevents CREATING custom FP utility functions (pipe, compose, curry) to make JavaScript "feel" like Haskell. Using established libraries (lodash, date-fns, etc.) is perfectly fine. FP is a mindset—pure functions, immutability, composition—not a rigid API signature.
-
-### Don't Create Custom FP Utilities
+FP is a mindset — pure functions, immutability, composition — not a rigid API signature. Never create custom FP utilities to make JavaScript "feel" like Haskell. Using established libraries (lodash, date-fns, etc.) is fine.
 
 ```javascript
-// ❌ DON'T CREATE: pipe() utility
+// ❌ DON'T CREATE pipe/compose/curry utilities
 const pipe = (...fns) => x => fns.reduce((v, f) => f(v), x)
 
-// ✅ INSTEAD: Native function calls with early returns
+// ✅ Native function calls with early returns
 const validateUser = (userData) => {
   const requiredCheck = validateRequired(['email', 'name'])(userData)
   if (!requiredCheck.valid) return requiredCheck
-
   const emailCheck = validateEmail(userData)
   if (!emailCheck.valid) return emailCheck
-
   return validateNameLength(userData)
 }
 
-// ❌ DON'T CREATE: compose() utility
-const compose = (...fns) => x => fns.reduceRight((v, f) => f(v), x)
-
-// ✅ INSTEAD: Direct function calls
-const processData = (raw) => {
-  const normalized = normalize(raw)
-  const validated = validate(normalized)
-  return transform(validated)
-}
-
-// ❌ DON'T CREATE: curry() utility
-const curry = (fn) => (...args) => args.length >= fn.length
-  ? fn(...args)
-  : (...more) => curry(fn)(...args, ...more)
-
-// ✅ INSTEAD: Native closures and function factories
-const createValidator = (rules) => (value) => {
-  const errors = rules.filter(rule => !rule.validator(value))
-  return errors.length === 0 ? { valid: true } : { valid: false, errors }
-}
-
-// ❌ DON'T CREATE: Custom monads
+// ❌ DON'T CREATE custom monads
 class Maybe { /* complex monad implementation */ }
 
-// ✅ INSTEAD: Native error handling and conditionals
+// ✅ Native error handling
 const getUser = async (id) => {
   try {
     const user = await fetchUser(id)
@@ -73,17 +38,16 @@ const getUser = async (id) => {
 }
 ```
 
-### Context-Appropriate Complexity
+**Context-appropriate complexity:**
 
 ```javascript
-// CLI Script: Simple and direct
+// CLI Script: simple and direct
 const processFile = (filePath) => {
   const data = readFileSync(filePath, 'utf8')
-  const lines = data.split('\n').filter(line => line.trim())
-  return lines.map(line => line.toUpperCase())
+  return data.split('\n').filter(line => line.trim()).map(line => line.toUpperCase())
 }
 
-// Production Service: Appropriate error handling
+// Production Service: appropriate error handling + logging
 const processFile = async (filePath, logger) => {
   try {
     const data = await readFile(filePath, 'utf8')
@@ -95,71 +59,46 @@ const processFile = async (filePath, logger) => {
     return { success: false, error: error.message }
   }
 }
-
-// Big Data System: Performance optimization with evidence
-const createFileProcessor = (config) => {
-  // Pre-compile expensive transformations
-  const transformers = config.transforms.map(compileTransformer)
-
-  return async (filePath, logger) => {
-    const stream = createReadStream(filePath)
-    return processStream(stream, transformers, logger)
-  }
-}
 ```
 
-## Core FP Patterns (Error-Preventing Essentials)
+## Core Patterns
 
 ### 1. Purity and Side Effect Isolation
 
-**Rule**: Separate business logic from side effects.
+Separate business logic from side effects. Pure core + impure shell.
 
 ```javascript
-// ❌ Impure - side effects mixed with logic
+// ❌ Side effects mixed with logic
 function calculateTotal(items) {
-  console.log('Processing items') // Side effect
-  total += items.reduce((sum, item) => sum + item.price, 0) // Mutation
+  console.log('Processing items')
+  total += items.reduce((sum, item) => sum + item.price, 0) // mutation
   return total
 }
 
-// ✅ Pure business logic
+// ✅ Pure logic
 const calculateTotal = (items) =>
   items.reduce((sum, item) => sum + item.price, 0)
 
 // ✅ Side effects isolated
 const logAndCalculate = (items, logger) => {
-  const total = calculateTotal(items) // Pure calculation
-  logger.log(`Total: ${total}`) // Side effect isolated
+  const total = calculateTotal(items)
+  logger.log(`Total: ${total}`)
   return total
 }
 ```
 
-**Benefits**:
-- 100% testable with all edge cases
-- Predictable behavior and debugging
-- Safe for parallel execution
-- Enables optimization through memoization
-
 ### 2. Composition Over Inheritance
 
-**Rule**: Build complex behavior from simple functions.
-
 ```javascript
-// ❌ Class hierarchy approach
-class BaseValidator {
-  validate() { throw new Error('Not implemented') }
-}
-class EmailValidator extends BaseValidator {
-  validate(value) { /* email logic */ }
-}
+// ❌ Class hierarchy
+class BaseValidator { validate() { throw new Error('Not implemented') } }
+class EmailValidator extends BaseValidator { validate(value) { /* email logic */ } }
 
-// ✅ Function composition (no utilities needed)
+// ✅ Function composition, no utilities needed
 const validateRequired = (value) => value != null && value !== ''
 const validateEmail = (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
-const validateLength = (min, max) => (value) =>
-  value.length >= min && value.length <= max
+const validateLength = (min, max) => (value) => value.length >= min && value.length <= max
 
-// Simple composition without pipe() utility
 const validateUserEmail = (email) => {
   if (!validateRequired(email)) return { valid: false, error: 'Required' }
   if (!validateEmail(email)) return { valid: false, error: 'Invalid email' }
@@ -168,18 +107,18 @@ const validateUserEmail = (email) => {
 }
 ```
 
-### 3. Dependency Injection Through Parameters
+### 3. Dependency Injection via Parameters
 
-**Rule**: Pass dependencies explicitly, avoid global state.
+Pass dependencies explicitly. No global state, no hidden dependencies.
 
 ```javascript
-// ❌ Hidden dependencies, hard to test
+// ❌ Hidden dependencies
 function saveUser(userData) {
-  const hashedPassword = bcrypt.hash(userData.password) // Hidden
-  return database.save({ ...userData, password: hashedPassword }) // Hidden
+  const hashedPassword = bcrypt.hash(userData.password)
+  return database.save({ ...userData, password: hashedPassword })
 }
 
-// ✅ Explicit dependencies, fully testable
+// ✅ Explicit dependencies
 const saveUser = async (userData, hasher, database) => {
   const hashedPassword = await hasher.hash(userData.password)
   return database.save({ ...userData, password: hashedPassword })
@@ -192,135 +131,84 @@ const createUserService = (hasher, database) => ({
 })
 ```
 
-### 4. Immutability Patterns
-
-**Rule**: Avoid mutations, create new objects/arrays.
+### 4. Immutability
 
 ```javascript
-// ❌ Mutation approach
+// ❌ Mutation
 function updateUserSettings(user, settings) {
-  user.settings = { ...user.settings, ...settings } // Mutates user
+  user.settings = { ...user.settings, ...settings }
   user.updatedAt = new Date()
   return user
 }
 
-// ✅ Immutable approach
+// ✅ Create new objects
 const updateUserSettings = (user, settings) => ({
   ...user,
   settings: { ...user.settings, ...settings },
   updatedAt: new Date()
 })
 
-// ✅ Array operations without mutation
 const addItem = (items, newItem) => [...items, newItem]
 const removeItem = (items, id) => items.filter(item => item.id !== id)
 const updateItem = (items, id, updates) =>
   items.map(item => item.id === id ? { ...item, ...updates } : item)
 ```
 
-## Testing Essentials (Enabled by Purity)
+## Testing (Enabled by Purity)
 
-**Philosophy**: Pure functions enable testing all edge cases systematically.
+Pure functions enable systematic edge case coverage.
 
 ```javascript
-// Traditional testing (limited coverage)
 describe('calculateDiscount', () => {
-  it('should calculate 10% discount', () => {
-    expect(calculateDiscount(100, 0.1)).toBe(10)
+  const testCases = [
+    [100, 0.1, 10],
+    [50, 0.2, 10],
+    [0, 0.1, 0]
+  ]
+  testCases.forEach(([price, rate, expected]) => {
+    it(`${rate*100}% on ${price} = ${expected}`, () =>
+      expect(calculateDiscount(price, rate)).toBe(expected))
   })
-})
-
-// FP comprehensive testing (all edge cases)
-describe('calculateDiscount - FP Comprehensive', () => {
-  describe('valid inputs', () => {
-    const testCases = [
-      [100, 0.1, 10],
-      [50, 0.2, 10],
-      [0, 0.1, 0]
-    ]
-
-    testCases.forEach(([price, rate, expected]) => {
-      it(`${rate*100}% discount on ${price} = ${expected}`, () => {
-        expect(calculateDiscount(price, rate)).toBe(expected)
-      })
-    })
-  })
-
-  describe('all data types - systematic edge cases', () => {
-    const invalidTypes = [null, undefined, NaN, true, [], {}, '100']
 
-    invalidTypes.forEach(input => {
-      it(`handles ${typeof input} gracefully`, () => {
-        expect(() => calculateDiscount(input, 0.1)).not.toThrow()
-        expect(calculateDiscount(input, 0.1)).toBe(0)
-      })
+  const invalidTypes = [null, undefined, NaN, true, [], {}, '100']
+  invalidTypes.forEach(input => {
+    it(`handles ${typeof input} gracefully`, () => {
+      expect(() => calculateDiscount(input, 0.1)).not.toThrow()
+      expect(calculateDiscount(input, 0.1)).toBe(0)
     })
   })
 })
 ```
 
-## Performance Patterns (Evidence-Based)
+## Performance (Evidence-Based Only)
 
-**⚠️ IMPORTANT**: Optimize only when needed with evidence.
-
-### Configuration Pre-Compilation (When Actually Needed)
-
-**Use When**: Processing large datasets (>10K items) with repeated configuration access.
+Optimize only when measured. For large datasets (>10K items), pre-compile configuration.
 
 ```javascript
-// Problem: O(records × fields) complexity
+// Problem: O(records × fields) — repeated config access per record
 function processRecords(records, schema) {
-  return records.map(record => {
-    return schema.fields.reduce((obj, field) => { // ← Repeated config access
+  return records.map(record =>
+    schema.fields.reduce((obj, field) => {
       obj[field.name] = transformField(record[field.name], field.type)
       return obj
-    }, {})
-  })
+    }, {}))
 }
 
-// Solution: O(records + fields) - pre-compile configuration
-function createRecordProcessor(schema) {
-  // Setup once - extract expensive configuration
+// Solution: O(records + fields) — pay config cost once
+const createRecordProcessor = (schema) => {
   const fieldProcessors = schema.fields.map(field =>
-    value => transformField(value, field.type)
-  )
-
+    value => transformField(value, field.type))
   return record => fieldProcessors.reduce((obj, processor, i) => {
     obj[schema.fields[i].name] = processor(record[schema.fields[i].name])
     return obj
   }, {})
 }
 
-// Usage: Configuration cost paid once
-const processor = createRecordProcessor(schema) // Setup phase
-const results = records.map(processor) // Linear execution
+const processor = createRecordProcessor(schema) // setup once
+const results = records.map(processor)           // linear execution
 ```
 
-### Function Factories for Reusable Logic
-
-```javascript
-// Create specialized functions instead of generic ones
-const createValidator = (rules) => (value) => {
-  const errors = []
-  for (const rule of rules) {
-    if (!rule.validator(value)) {
-      errors.push(rule.message)
-    }
-  }
-  return errors.length === 0 ? { valid: true } : { valid: false, errors }
-}
-
-// Usage: Configure once, use many times
-const validateEmail = createValidator([
-  { validator: v => typeof v === 'string', message: 'Must be string' },
-  { validator: v => v.includes('@'), message: 'Must contain @' },
-  { validator: v => v.length > 5, message: 'Too short' }
-])
-```
-
-## Language-Specific Idioms
-
-### Native JavaScript Patterns
+## Native JavaScript Idioms
 
 ```javascript
 // Native array methods over loops
@@ -330,134 +218,25 @@ const processUsers = (users) =>
     .map(user => ({ ...user, displayName: `${user.firstName} ${user.lastName}` }))
     .sort((a, b) => a.lastName.localeCompare(b.lastName))
 
-// Native async/await over callbacks
+// async/await with result types
 const fetchUserData = async (userId, fetcher) => {
   try {
-    const user = await fetcher.getUser(userId)
-    const preferences = await fetcher.getPreferences(userId)
-    return { ...user, preferences }
+    const [user, preferences] = await Promise.all([
+      fetcher.getUser(userId),
+      fetcher.getPreferences(userId)
+    ])
+    return { success: true, data: { ...user, preferences } }
   } catch (error) {
-    return { error: error.message }
-  }
-}
-
-// WeakMap for performance when appropriate
-const createMemoized = () => {
-  const cache = new WeakMap()
-  return (obj, computeFn) => {
-    if (cache.has(obj)) return cache.get(obj)
-    const result = computeFn(obj)
-    cache.set(obj, result)
-    return result
-  }
-}
-```
-
-## Quality Gates (Pre-Implementation Checklist)
-
-1. **"Can this be pure?"** → Separate business logic from side effects
-2. **"Can this use native patterns?"** → Avoid creating custom FP utilities, use language features
-3. **"Can this be simplified?"** → Choose simple solution over complex abstraction
-4. **"Is this complexity justified?"** → Evidence-based complexity decisions
-5. **"Is this testable?"** → Pure functions enable comprehensive testing
-6. **"Is this context-appropriate?"** → CLI script ≠ production service ≠ big data system
-
-## When to Load Additional Content
-
-### Deep Principles and Explanations
-**File**: `core-principles.md` (~800 lines)
-**When**: Learning mode, explaining WHY, architectural decisions
-**Contains**: Complete FP philosophy, detailed pattern explanations, cross-pattern comparisons
-
-### Comprehensive Anti-Patterns
-**File**: `anti-patterns.md` (~400 lines)
-**When**: Code review, preventing specific mistakes, team training
-**Contains**: Exhaustive anti-patterns, common mistakes, migration strategies
-
-### Testing Methodology
-**File**: `testing-patterns.md` (~500 lines)
-**When**: Building test suites, improving coverage, edge case analysis
-**Contains**: Full testing strategies, edge case patterns, property-based testing
-
-### Performance Deep-Dive
-**File**: `performance-patterns.md` (~400 lines)
-**When**: Performance issues identified, optimization needed, benchmarking
-**Contains**: Detailed optimization strategies, profiling techniques, benchmarking patterns
-
-### Working Examples
-**Directory**: `examples/`
-**When**: Learning implementation, need working code, integration examples
-**Contains**: Complete working examples with tests
-
-## Integration with Domain Skills
-
-This core skill provides the foundation for domain-specific skills:
-
-- **js-fp-api**: Node.js API patterns with FP principles
-- **js-fp-react**: React component patterns with FP principles
-- **js-fp-vue**: Vue.js component patterns with FP principles
-- **js-fp-wordpress**: WordPress patterns with FP principles
-
-Each domain skill references this core and adds domain-specific patterns.
-
-## Common Use Cases
-
-### Data Validation
-```javascript
-const createValidationRules = (schema) => {
-  const rules = schema.map(rule => ({
-    field: rule.field,
-    validator: compileValidator(rule.type, rule.options),
-    message: rule.message
-  }))
-
-  return (data) => {
-    const errors = []
-    for (const rule of rules) {
-      if (!rule.validator(data[rule.field])) {
-        errors.push({ field: rule.field, message: rule.message })
-      }
-    }
-    return errors.length === 0 ? { valid: true } : { valid: false, errors }
+    return { success: false, error: error.message }
   }
 }
 ```
 
-### Data Transformation
-```javascript
-// Pipeline without utilities - native chaining
-const processUserData = (rawData) => {
-  const normalized = normalizeUserData(rawData)
-  if (!normalized.valid) return normalized
-
-  const validated = validateUserData(normalized.data)
-  if (!validated.valid) return validated
-
-  const enhanced = enhanceWithDefaults(validated.data)
-  return { valid: true, data: enhanced }
-}
-```
-
-## Success Metrics
-
-### Code Quality
-- **Simplicity**: Readable, maintainable code over clever solutions
-- **Testability**: 100% testable pure functions with edge case coverage
-- **Native Integration**: Uses language features effectively
-- **Context-Appropriate**: Matches complexity to actual requirements
-
-### Performance (When Needed)
-- **Evidence-Based**: Optimizations backed by measurements
-- **Appropriate Scale**: Simple solutions for small/medium data
-- **Native Optimization**: Leverages language/runtime optimizations
-- **Avoid Over-Engineering**: No complex monitoring for simple apps
-
-### Maintainability
-- **Predictable Patterns**: Consistent FP approaches
-- **Easy Testing**: Comprehensive test coverage enabled by purity
-- **Simple Maintenance**: Easy to understand and modify
-- **Documentation**: Clear examples and usage patterns
-
-## Philosophy
+## Pre-Implementation Checklist
 
-*"Pure functions, native language patterns, appropriate complexity, and comprehensive testing for maintainable, predictable code that respects the language and solves real problems simply."*
+1. Can this be pure? — separate business logic from side effects
+2. Can this use native patterns? — avoid custom FP utilities
+3. Can this be simplified? — prefer simple over clever
+4. Is complexity justified? — evidence, not assumptions
+5. Is this testable? — pure functions enable comprehensive coverage
+6. Is this context-appropriate? — CLI script ≠ production service