ima-claude 2.9.0

package/plugins/ima-claude/skills/php-fp/references/core-principles.md

@@ -0,0 +1,277 @@
+# PHP FP Core Principles
+
+Deep-dive into functional programming philosophy adapted for PHP 8.1+.
+
+## The Three Laws
+
+### 1. Purity: Same Input, Same Output
+
+```php
+<?php
+declare(strict_types=1);
+
+// PURE: Deterministic, no side effects
+function calculateTax(float $amount, float $rate): float {
+    return $amount * $rate;
+}
+
+// IMPURE: Uses external state
+function calculateTax(float $amount): float {
+    global $taxRate; // Hidden dependency
+    file_put_contents('/tmp/log', $amount); // Side effect
+    return $amount * $taxRate;
+}
+```
+
+**Test**: Can you call this function 1000 times with the same input and always get the same result without affecting anything else?
+
+### 2. Immutability: Never Mutate, Always Return New
+
+```php
+<?php
+declare(strict_types=1);
+
+// MUTATES: Modifies input
+function addTimestamp(array &$record): void {
+    $record['created_at'] = time();
+}
+
+// IMMUTABLE: Returns new array
+function addTimestamp(array $record): array {
+    return [...$record, 'created_at' => time()];
+}
+
+// IMMUTABLE: Collection operations
+function removeInactive(array $users): array {
+    return array_values(array_filter($users, fn($u) => $u['active']));
+}
+
+function updateById(array $items, int $id, array $updates): array {
+    return array_map(
+        fn($item) => $item['id'] === $id ? [...$item, ...$updates] : $item,
+        $items
+    );
+}
+```
+
+### 3. Composition: Small Functions, Combined Simply
+
+```php
+<?php
+declare(strict_types=1);
+
+// Build complex from simple - NO pipe() utility needed
+function processOrder(array $order): array {
+    $validated = validateOrder($order);
+    if (!$validated['success']) return $validated;
+
+    $calculated = calculateTotals($validated['data']);
+    if (!$calculated['success']) return $calculated;
+
+    return applyDiscounts($calculated['data']);
+}
+
+// Each function is small, pure, testable
+function validateOrder(array $order): array {
+    if (empty($order['items'])) {
+        return ['success' => false, 'error' => 'No items'];
+    }
+    return ['success' => true, 'data' => $order];
+}
+```
+
+## PHP-Native Patterns
+
+### Closures as First-Class Functions
+
+```php
+<?php
+declare(strict_types=1);
+
+// Factory returns configured closure
+function createValidator(int $minLength): Closure {
+    return fn(string $value): bool => strlen($value) >= $minLength;
+}
+
+$validateName = createValidator(2);
+$validateName('Jo'); // true
+
+// Compose validators
+function validateAll(array $validators): Closure {
+    return fn($value): bool => array_reduce(
+        $validators,
+        fn(bool $valid, callable $v) => $valid && $v($value),
+        true
+    );
+}
+
+$validateUsername = validateAll([
+    fn($v) => is_string($v),
+    fn($v) => strlen($v) >= 3,
+    fn($v) => strlen($v) <= 20,
+    fn($v) => preg_match('/^[a-z0-9_]+$/', $v) === 1,
+]);
+```
+
+### Match Expressions for Branching
+
+```php
+<?php
+declare(strict_types=1);
+
+// Pure branching with match
+function getStatusMessage(string $status): string {
+    return match($status) {
+        'pending' => 'Awaiting review',
+        'approved' => 'Ready to proceed',
+        'rejected' => 'Request denied',
+        'cancelled' => 'User cancelled',
+        default => 'Unknown status',
+    };
+}
+
+// Type-safe dispatch
+function processEvent(array $event): array {
+    return match($event['type']) {
+        'user.created' => handleUserCreated($event['data']),
+        'user.updated' => handleUserUpdated($event['data']),
+        'user.deleted' => handleUserDeleted($event['data']),
+        default => ['handled' => false, 'reason' => 'Unknown event'],
+    };
+}
+```
+
+### Readonly Properties for Immutable Objects
+
+```php
+<?php
+declare(strict_types=1);
+
+// Value objects with readonly (PHP 8.1+)
+readonly class Money {
+    public function __construct(
+        public int $amount,
+        public string $currency
+    ) {}
+
+    public function add(Money $other): Money {
+        if ($this->currency !== $other->currency) {
+            throw new InvalidArgumentException('Currency mismatch');
+        }
+        return new Money($this->amount + $other->amount, $this->currency);
+    }
+}
+
+// Usage - immutable by design
+$price = new Money(1000, 'USD');
+$tax = new Money(100, 'USD');
+$total = $price->add($tax); // New Money object
+```
+
+## Anti-Pattern Recognition
+
+### Hidden Mutation
+
+```php
+<?php
+// ANTI-PATTERN: Mutation disguised as transformation
+function processUser(array $user): array {
+    $user['processed_at'] = time(); // Mutates if passed by reference
+    return validateUser($user);
+}
+
+// CORRECT: Explicit new array
+function processUser(array $user): array {
+    return validateUser([
+        ...$user,
+        'processed_at' => time()
+    ]);
+}
+```
+
+### Configuration in Hot Paths
+
+```php
+<?php
+// ANTI-PATTERN: O(records x fields) - schema accessed every iteration
+function mapRecords(array $records, array $schema): array {
+    return array_map(function($record) use ($schema) {
+        return array_combine(
+            array_column($schema['fields'], 'name'),
+            array_map(fn($f) => $record[$f['key']], $schema['fields'])
+        );
+    }, $records);
+}
+
+// CORRECT: Pre-compile, then execute - O(records + fields)
+function createRecordMapper(array $schema): Closure {
+    $fields = $schema['fields'];
+    $names = array_column($fields, 'name');
+    $keys = array_column($fields, 'key');
+
+    return fn(array $record): array => array_combine(
+        $names,
+        array_map(fn($key) => $record[$key], $keys)
+    );
+}
+
+$mapper = createRecordMapper($schema); // Setup once
+$results = array_map($mapper, $records); // Linear execution
+```
+
+### Over-Engineering Validation
+
+```php
+<?php
+// ANTI-PATTERN: Complex machinery for simple check
+$emailValidator = (new ValidatorBuilder())
+    ->addRule(new FormatRule(new EmailPattern()))
+    ->addRule(new LengthRule(new Range(5, 254)))
+    ->addTransformer(new LowercaseTransformer())
+    ->build();
+
+// CORRECT: Simple, direct, readable
+function validateEmail(string $email): bool {
+    $normalized = strtolower(trim($email));
+    return strlen($normalized) >= 5
+        && strlen($normalized) <= 254
+        && filter_var($normalized, FILTER_VALIDATE_EMAIL) !== false;
+}
+```
+
+## Result Type Pattern
+
+Consistent error handling without exceptions for expected failures.
+
+```php
+<?php
+declare(strict_types=1);
+
+// Standard result shape
+function success(mixed $data): array {
+    return ['success' => true, 'data' => $data];
+}
+
+function failure(string $error, array $context = []): array {
+    return ['success' => false, 'error' => $error, 'context' => $context];
+}
+
+// Usage in pure functions
+function parseJson(string $json): array {
+    $data = json_decode($json, true);
+    return json_last_error() === JSON_ERROR_NONE
+        ? success($data)
+        : failure('Invalid JSON', ['error' => json_last_error_msg()]);
+}
+
+// Chain results
+function processInput(string $json): array {
+    $parsed = parseJson($json);
+    if (!$parsed['success']) return $parsed;
+
+    $validated = validateData($parsed['data']);
+    if (!$validated['success']) return $validated;
+
+    return transformData($validated['data']);
+}
+```

package/plugins/ima-claude/skills/php-fp/references/testing-patterns.md

@@ -0,0 +1,374 @@
+# PHP FP Testing Patterns
+
+Comprehensive testing philosophy for pure functions using PHPUnit.
+
+## Why Pure Functions Enable Better Testing
+
+Pure functions guarantee:
+- **Deterministic**: Same input always produces same output
+- **Isolated**: No side effects means tests never interfere
+- **Fast**: No I/O, network, or database needed
+- **Complete**: All edge cases can be systematically tested
+
+## The Test Matrix Approach
+
+### Systematic Type Coverage
+
+```php
+<?php
+declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+class ValidatorTest extends TestCase
+{
+    // Test expected use cases
+    #[DataProvider('validInputProvider')]
+    public function testAcceptsValidInput(mixed $input, bool $expected): void
+    {
+        $this->assertSame($expected, validatePositiveInteger($input));
+    }
+
+    public static function validInputProvider(): array
+    {
+        return [
+            'positive integer' => [5, true],
+            'large number' => [1000000, true],
+            'boundary: 1' => [1, true],
+            'zero' => [0, false],
+            'negative' => [-5, false],
+        ];
+    }
+
+    // Test ALL PHP types systematically
+    #[DataProvider('invalidTypeProvider')]
+    public function testRejectsInvalidTypes(mixed $input): void
+    {
+        $this->expectException(TypeError::class);
+        validatePositiveInteger($input);
+    }
+
+    public static function invalidTypeProvider(): array
+    {
+        return [
+            'null' => [null],
+            'string' => ['5'],
+            'float' => [5.0],
+            'bool true' => [true],
+            'bool false' => [false],
+            'empty array' => [[]],
+            'array with values' => [[1, 2, 3]],
+            'object' => [new stdClass()],
+            'closure' => [fn() => 5],
+        ];
+    }
+}
+```
+
+### Boundary Value Testing
+
+```php
+<?php
+declare(strict_types=1);
+
+class RangeValidatorTest extends TestCase
+{
+    private Closure $validator;
+
+    protected function setUp(): void
+    {
+        $this->validator = createRangeValidator(min: 0, max: 100);
+    }
+
+    #[DataProvider('boundaryProvider')]
+    public function testBoundaryValues(int $value, bool $expected): void
+    {
+        $this->assertSame($expected, ($this->validator)($value));
+    }
+
+    public static function boundaryProvider(): array
+    {
+        return [
+            'below min' => [-1, false],
+            'at min' => [0, true],
+            'above min' => [1, true],
+            'middle' => [50, true],
+            'below max' => [99, true],
+            'at max' => [100, true],
+            'above max' => [101, false],
+        ];
+    }
+}
+```
+
+## Testing Composed Functions
+
+### Test Components Independently
+
+```php
+<?php
+declare(strict_types=1);
+
+// Functions under test
+function normalizeEmail(string $email): string {
+    return strtolower(trim($email));
+}
+
+function validateEmailFormat(string $email): bool {
+    return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
+}
+
+function validateEmailDomain(string $email, array $blocked): bool {
+    $domain = substr($email, strpos($email, '@') + 1);
+    return !in_array($domain, $blocked, true);
+}
+
+// Test each component
+class EmailValidationTest extends TestCase
+{
+    public function testNormalizeEmail(): void
+    {
+        $this->assertSame('test@example.com', normalizeEmail('  TEST@EXAMPLE.COM  '));
+    }
+
+    #[DataProvider('formatProvider')]
+    public function testValidateEmailFormat(string $email, bool $valid): void
+    {
+        $this->assertSame($valid, validateEmailFormat($email));
+    }
+
+    public static function formatProvider(): array
+    {
+        return [
+            'valid' => ['test@example.com', true],
+            'no @' => ['testexample.com', false],
+            'no domain' => ['test@', false],
+            'no local' => ['@example.com', false],
+            'double @' => ['test@@example.com', false],
+        ];
+    }
+
+    public function testValidateEmailDomain(): void
+    {
+        $blocked = ['spam.com', 'temp.net'];
+
+        $this->assertTrue(validateEmailDomain('user@example.com', $blocked));
+        $this->assertFalse(validateEmailDomain('user@spam.com', $blocked));
+    }
+}
+```
+
+### Test the Composition
+
+```php
+<?php
+declare(strict_types=1);
+
+class EmailValidationIntegrationTest extends TestCase
+{
+    private Closure $validateEmail;
+
+    protected function setUp(): void
+    {
+        $blocked = ['spam.com'];
+        $this->validateEmail = createEmailValidator($blocked);
+    }
+
+    #[DataProvider('integrationProvider')]
+    public function testFullValidation(string $input, array $expected): void
+    {
+        $result = ($this->validateEmail)($input);
+        $this->assertSame($expected['success'], $result['success']);
+        if (!$expected['success']) {
+            $this->assertStringContainsString($expected['error'], $result['error']);
+        }
+    }
+
+    public static function integrationProvider(): array
+    {
+        return [
+            'valid email' => [
+                'USER@EXAMPLE.COM',
+                ['success' => true]
+            ],
+            'invalid format' => [
+                'not-an-email',
+                ['success' => false, 'error' => 'format']
+            ],
+            'blocked domain' => [
+                'user@spam.com',
+                ['success' => false, 'error' => 'blocked']
+            ],
+        ];
+    }
+}
+```
+
+## Testing Function Factories
+
+```php
+<?php
+declare(strict_types=1);
+
+class FunctionFactoryTest extends TestCase
+{
+    public function testCreateValidatorReturnsCallable(): void
+    {
+        $validator = createValidator(minLength: 5);
+        $this->assertIsCallable($validator);
+    }
+
+    public function testFactoryConfigurationIsCaptured(): void
+    {
+        $validator5 = createValidator(minLength: 5);
+        $validator10 = createValidator(minLength: 10);
+
+        // Same input, different results based on configuration
+        $this->assertTrue($validator5('hello'));    // 5 >= 5
+        $this->assertFalse($validator10('hello'));  // 5 < 10
+    }
+
+    public function testFactoryProducesIndependentInstances(): void
+    {
+        $v1 = createValidator(minLength: 3);
+        $v2 = createValidator(minLength: 3);
+
+        // Different instances, same behavior
+        $this->assertNotSame($v1, $v2);
+        $this->assertSame($v1('abc'), $v2('abc'));
+    }
+}
+```
+
+## Result Type Testing
+
+```php
+<?php
+declare(strict_types=1);
+
+class ResultTypeTest extends TestCase
+{
+    public function testSuccessResultStructure(): void
+    {
+        $result = divide(10.0, 2.0);
+
+        $this->assertArrayHasKey('success', $result);
+        $this->assertTrue($result['success']);
+        $this->assertArrayHasKey('data', $result);
+        $this->assertSame(5.0, $result['data']);
+    }
+
+    public function testFailureResultStructure(): void
+    {
+        $result = divide(10.0, 0.0);
+
+        $this->assertArrayHasKey('success', $result);
+        $this->assertFalse($result['success']);
+        $this->assertArrayHasKey('error', $result);
+        $this->assertIsString($result['error']);
+    }
+
+    public function testResultChaining(): void
+    {
+        // Test that failures short-circuit
+        $result = processCalculation(10.0, 0.0, 5.0);
+
+        $this->assertFalse($result['success']);
+        $this->assertStringContainsString('zero', $result['error']);
+    }
+}
+```
+
+## Mocking Dependencies
+
+```php
+<?php
+declare(strict_types=1);
+
+class ServiceWithDependenciesTest extends TestCase
+{
+    public function testUserServiceWithMocks(): void
+    {
+        // Create mock implementations
+        $mockHasher = $this->createMock(PasswordHasherInterface::class);
+        $mockHasher->method('hash')->willReturn('hashed_password');
+
+        $mockDb = $this->createMock(DatabaseInterface::class);
+        $mockDb->method('save')->willReturn(['id' => 1, 'name' => 'Test']);
+
+        // Inject mocks - DI makes this trivial
+        $result = saveUser(
+            ['name' => 'Test', 'password' => 'secret'],
+            $mockHasher,
+            $mockDb
+        );
+
+        $this->assertSame(1, $result['id']);
+    }
+
+    public function testPureFunctionNeedsNoMocks(): void
+    {
+        // Pure functions are trivially testable
+        $result = calculateDiscount(100.0, 0.1);
+        $this->assertSame(90.0, $result);
+        // No setup, no mocks, no cleanup
+    }
+}
+```
+
+## Performance Testing Pure Functions
+
+```php
+<?php
+declare(strict_types=1);
+
+class PerformanceTest extends TestCase
+{
+    public function testFactoryPerformanceGain(): void
+    {
+        $data = range(1, 10000);
+        $config = ['multiplier' => 2];
+
+        // Without factory: config accessed each iteration
+        $start = microtime(true);
+        $results1 = array_map(
+            fn($n) => $n * $config['multiplier'],
+            $data
+        );
+        $withoutFactory = microtime(true) - $start;
+
+        // With factory: config captured once
+        $processor = fn($n) => $n * 2; // Config pre-compiled
+        $start = microtime(true);
+        $results2 = array_map($processor, $data);
+        $withFactory = microtime(true) - $start;
+
+        $this->assertSame($results1, $results2);
+        // Factory should be faster (config not re-accessed)
+    }
+}
+```
+
+## Test Organization
+
+```
+tests/
+  Unit/
+    Validators/
+      EmailValidatorTest.php
+      RangeValidatorTest.php
+    Transformers/
+      DataMapperTest.php
+    Utils/
+      ResultTypeTest.php
+  Integration/
+    ValidationPipelineTest.php
+```
+
+**Key Principles**:
+1. One test class per function/factory
+2. Data providers for systematic coverage
+3. Test components independently, then composition
+4. Pure functions need no mocks
+5. Edge cases are cheap to test - test them all