Merge pull request 'feat: ConfigValidator + plugin command dispatcher' (#117) from dev into main

lib/Enterprise/ConfigValidator.php

@@ -0,0 +1,247 @@
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: MokoStandards.Enterprise
+ * INGROUP: MokoStandards.Enterprise
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /lib/Enterprise/ConfigValidator.php
+ * BRIEF: Validate project config against plugin JSON schema
+ */
+
+declare(strict_types=1);
+
+namespace MokoEnterprise;
+
+class ConfigValidator
+{
+    /** @var array<int, string> */
+    private array $errors = [];
+
+    /** @var array<int, string> */
+    private array $warnings = [];
+
+    /**
+     * Validate config data against a JSON schema.
+     *
+     * @param array<string, mixed> $config Config to validate
+     * @param array<string, mixed> $schema JSON Schema definition
+     * @return bool True if valid
+     */
+    public function validate(array $config, array $schema): bool
+    {
+        $this->errors = [];
+        $this->warnings = [];
+
+        $this->validateNode($config, $schema, '');
+
+        return empty($this->errors);
+    }
+
+    /** @return array<int, string> */
+    public function getErrors(): array
+    {
+        return $this->errors;
+    }
+
+    /** @return array<int, string> */
+    public function getWarnings(): array
+    {
+        return $this->warnings;
+    }
+
+    /**
+     * @param mixed $data
+     * @param array<string, mixed> $schema
+     */
+    private function validateNode(
+        mixed $data,
+        array $schema,
+        string $path
+    ): void {
+        $type = $schema['type'] ?? null;
+
+        if ($type !== null && !$this->checkType($data, $type)) {
+            $actual = gettype($data);
+            $this->errors[] = $path === ''
+                ? "Root must be {$type}, got {$actual}"
+                : "{$path}: expected {$type}, got {$actual}";
+            return;
+        }
+
+        if ($type === 'object') {
+            $this->validateObject($data, $schema, $path);
+        }
+
+        if ($type === 'array' && isset($schema['items'])) {
+            $this->validateArray($data, $schema, $path);
+        }
+
+        if (isset($schema['enum'])) {
+            $this->validateEnum($data, $schema['enum'], $path);
+        }
+
+        if ($type === 'string') {
+            $this->validateString($data, $schema, $path);
+        }
+
+        if ($type === 'integer' || $type === 'number') {
+            $this->validateNumber($data, $schema, $path);
+        }
+    }
+
+    /**
+     * @param array<string, mixed> $data
+     * @param array<string, mixed> $schema
+     */
+    private function validateObject(
+        array $data,
+        array $schema,
+        string $path
+    ): void {
+        $properties = $schema['properties'] ?? [];
+        $required = $schema['required'] ?? [];
+
+        foreach ($required as $field) {
+            if (!array_key_exists($field, $data)) {
+                $fieldPath = $path === '' ? $field : "{$path}.{$field}";
+                $this->errors[] = "{$fieldPath}: required field missing";
+            }
+        }
+
+        foreach ($properties as $field => $fieldSchema) {
+            if (!array_key_exists($field, $data)) {
+                continue;
+            }
+
+            $fieldPath = $path === '' ? $field : "{$path}.{$field}";
+            $this->validateNode($data[$field], $fieldSchema, $fieldPath);
+        }
+
+        $known = array_keys($properties);
+
+        foreach (array_keys($data) as $field) {
+            if (!in_array($field, $known, true)) {
+                $fieldPath = $path === '' ? $field : "{$path}.{$field}";
+                $this->warnings[] = "{$fieldPath}: unknown property";
+            }
+        }
+    }
+
+    /**
+     * @param array<int, mixed> $data
+     * @param array<string, mixed> $schema
+     */
+    private function validateArray(
+        array $data,
+        array $schema,
+        string $path
+    ): void {
+        $itemSchema = $schema['items'];
+
+        foreach ($data as $i => $item) {
+            $this->validateNode(
+                $item,
+                $itemSchema,
+                "{$path}[{$i}]"
+            );
+        }
+
+        if (
+            isset($schema['minItems'])
+            && count($data) < $schema['minItems']
+        ) {
+            $this->errors[] = "{$path}: "
+                . "needs at least {$schema['minItems']} items";
+        }
+    }
+
+    /**
+     * @param mixed $data
+     * @param array<int, mixed> $allowed
+     */
+    private function validateEnum(
+        mixed $data,
+        array $allowed,
+        string $path
+    ): void {
+        if (!in_array($data, $allowed, true)) {
+            $values = implode(', ', $allowed);
+            $label = $path ?: 'value';
+            $this->errors[] = "{$label}: "
+                . "'{$data}' not in [{$values}]";
+        }
+    }
+
+    /**
+     * @param array<string, mixed> $schema
+     */
+    private function validateString(
+        mixed $data,
+        array $schema,
+        string $path
+    ): void {
+        if (!is_string($data)) {
+            return;
+        }
+
+        if (
+            isset($schema['minLength'])
+            && strlen($data) < $schema['minLength']
+        ) {
+            $this->errors[] = "{$path}: "
+                . "too short (min {$schema['minLength']})";
+        }
+
+        if (
+            isset($schema['pattern'])
+            && !preg_match('/' . $schema['pattern'] . '/', $data)
+        ) {
+            $this->errors[] = "{$path}: "
+                . "does not match pattern {$schema['pattern']}";
+        }
+    }
+
+    /**
+     * @param array<string, mixed> $schema
+     */
+    private function validateNumber(
+        mixed $data,
+        array $schema,
+        string $path
+    ): void {
+        if (!is_numeric($data)) {
+            return;
+        }
+
+        if (isset($schema['minimum']) && $data < $schema['minimum']) {
+            $this->errors[] = "{$path}: "
+                . "below minimum {$schema['minimum']}";
+        }
+
+        if (isset($schema['maximum']) && $data > $schema['maximum']) {
+            $this->errors[] = "{$path}: "
+                . "above maximum {$schema['maximum']}";
+        }
+    }
+
+    private function checkType(mixed $data, string $type): bool
+    {
+        return match ($type) {
+            'object' => is_array($data),
+            'array' => is_array($data)
+                && array_is_list($data),
+            'string' => is_string($data),
+            'integer' => is_int($data),
+            'number' => is_int($data) || is_float($data),
+            'boolean' => is_bool($data),
+            'null' => is_null($data),
+            default => true,
+        };
+    }
+}

tests/Unit/ConfigValidatorTest.php

@@ -0,0 +1,141 @@
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace MokoStandards\Tests\Unit;
+
+use MokoEnterprise\ConfigValidator;
+use PHPUnit\Framework\TestCase;
+
+class ConfigValidatorTest extends TestCase
+{
+    private ConfigValidator $validator;
+
+    protected function setUp(): void
+    {
+        $this->validator = new ConfigValidator();
+    }
+
+    public function testValidConfigPasses(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'name' => ['type' => 'string'],
+                'version' => ['type' => 'string'],
+            ],
+            'required' => ['name'],
+        ];
+
+        $config = ['name' => 'MyProject', 'version' => '1.0'];
+
+        $this->assertTrue($this->validator->validate($config, $schema));
+        $this->assertEmpty($this->validator->getErrors());
+    }
+
+    public function testMissingRequiredField(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'name' => ['type' => 'string'],
+            ],
+            'required' => ['name'],
+        ];
+
+        $this->assertFalse($this->validator->validate([], $schema));
+        $this->assertStringContainsString(
+            'required',
+            $this->validator->getErrors()[0]
+        );
+    }
+
+    public function testEnumValidation(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'type' => [
+                    'type' => 'string',
+                    'enum' => ['component', 'module', 'plugin'],
+                ],
+            ],
+        ];
+
+        $valid = ['type' => 'component'];
+        $this->assertTrue($this->validator->validate($valid, $schema));
+
+        $invalid = ['type' => 'banana'];
+        $this->assertFalse($this->validator->validate($invalid, $schema));
+    }
+
+    public function testNestedObjectValidation(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'db' => [
+                    'type' => 'object',
+                    'properties' => [
+                        'host' => ['type' => 'string'],
+                        'port' => ['type' => 'integer'],
+                    ],
+                    'required' => ['host'],
+                ],
+            ],
+        ];
+
+        $valid = ['db' => ['host' => 'localhost', 'port' => 3306]];
+        $this->assertTrue($this->validator->validate($valid, $schema));
+
+        $invalid = ['db' => ['port' => 3306]];
+        $this->assertFalse($this->validator->validate($invalid, $schema));
+    }
+
+    public function testUnknownPropertiesWarn(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'name' => ['type' => 'string'],
+            ],
+        ];
+
+        $config = ['name' => 'ok', 'extra' => 'unknown'];
+        $this->assertTrue($this->validator->validate($config, $schema));
+        $this->assertNotEmpty($this->validator->getWarnings());
+    }
+
+    public function testTypeMismatch(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'count' => ['type' => 'integer'],
+            ],
+        ];
+
+        $invalid = ['count' => 'not-a-number'];
+        $this->assertFalse($this->validator->validate($invalid, $schema));
+    }
+
+    public function testStringMinLength(): void
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [
+                'name' => ['type' => 'string', 'minLength' => 3],
+            ],
+        ];
+
+        $short = ['name' => 'ab'];
+        $this->assertFalse($this->validator->validate($short, $schema));
+
+        $ok = ['name' => 'abc'];
+        $this->assertTrue($this->validator->validate($ok, $schema));
+    }
+}