From d924ee385e471e0de66ff8c34a1184527fa8fe6d Mon Sep 17 00:00:00 2001
From: Ivan Moroz <menvil.menvil@gmail.com>
Date: Fri, 29 May 2026 00:10:33 +0300
Subject: [PATCH] CONV-042: Implement options schema validator

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../InvalidOptionsSchemaException.php         | 43 ++++++++++
 .../Converters/OptionsSchemaValidator.php     | 79 +++++++++++++++++++
 2 files changed, 122 insertions(+)
 create mode 100644 app/Support/Converters/Exceptions/InvalidOptionsSchemaException.php
 create mode 100644 app/Support/Converters/OptionsSchemaValidator.php

diff --git a/app/Support/Converters/Exceptions/InvalidOptionsSchemaException.php b/app/Support/Converters/Exceptions/InvalidOptionsSchemaException.php
new file mode 100644
index 0000000..91e469f
--- /dev/null
+++ b/app/Support/Converters/Exceptions/InvalidOptionsSchemaException.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Support\Converters\Exceptions;
+
+use DomainException;
+
+final class InvalidOptionsSchemaException extends DomainException
+{
+    public static function becauseFieldIsInvalid(): self
+    {
+        return new self('Options schema field must be an array.');
+    }
+
+    public static function becauseKeyIsMissing(): self
+    {
+        return new self('Options schema field is missing the "key" attribute.');
+    }
+
+    public static function becauseKeyIsDuplicated(string $key): self
+    {
+        return new self("Options schema contains duplicate field key: {$key}.");
+    }
+
+    public static function becauseTypeIsUnsupported(string $type): self
+    {
+        return new self("Options schema field type is not supported: {$type}.");
+    }
+
+    public static function becauseLabelIsMissing(string $key): self
+    {
+        return new self("Options schema field [{$key}] is missing the \"label\" attribute.");
+    }
+
+    public static function becauseOptionsAreRequired(string $key): self
+    {
+        return new self("Options schema field [{$key}] requires a non-empty \"options\" list.");
+    }
+
+    public static function becauseOptionItemIsInvalid(string $key): self
+    {
+        return new self("Options schema field [{$key}] contains an invalid option entry.");
+    }
+}
diff --git a/app/Support/Converters/OptionsSchemaValidator.php b/app/Support/Converters/OptionsSchemaValidator.php
new file mode 100644
index 0000000..5e92e2b
--- /dev/null
+++ b/app/Support/Converters/OptionsSchemaValidator.php
@@ -0,0 +1,79 @@
+<?php
+
+namespace App\Support\Converters;
+
+use App\Support\Converters\Exceptions\InvalidOptionsSchemaException;
+
+final class OptionsSchemaValidator
+{
+    private const SUPPORTED_TYPES = [
+        'select',
+        'segmented',
+        'toggle',
+        'color',
+        'number',
+        'range',
+    ];
+
+    private const TYPES_REQUIRING_OPTIONS = [
+        'select',
+        'segmented',
+    ];
+
+    public function validate(array $schema): void
+    {
+        $keys = [];
+
+        foreach ($schema as $field) {
+            if (! is_array($field)) {
+                throw InvalidOptionsSchemaException::becauseFieldIsInvalid();
+            }
+
+            $key = $field['key'] ?? null;
+            $type = $field['type'] ?? null;
+            $label = $field['label'] ?? null;
+
+            if (! is_string($key) || $key === '') {
+                throw InvalidOptionsSchemaException::becauseKeyIsMissing();
+            }
+
+            if (in_array($key, $keys, true)) {
+                throw InvalidOptionsSchemaException::becauseKeyIsDuplicated($key);
+            }
+
+            $keys[] = $key;
+
+            if (! is_string($type) || ! in_array($type, self::SUPPORTED_TYPES, true)) {
+                throw InvalidOptionsSchemaException::becauseTypeIsUnsupported((string) $type);
+            }
+
+            if (! is_string($label) || $label === '') {
+                throw InvalidOptionsSchemaException::becauseLabelIsMissing($key);
+            }
+
+            if (in_array($type, self::TYPES_REQUIRING_OPTIONS, true)) {
+                $this->validateChoiceOptions($key, $field['options'] ?? null);
+            }
+        }
+    }
+
+    private function validateChoiceOptions(string $key, mixed $options): void
+    {
+        if (! is_array($options) || $options === []) {
+            throw InvalidOptionsSchemaException::becauseOptionsAreRequired($key);
+        }
+
+        foreach ($options as $option) {
+            if (! is_array($option)) {
+                throw InvalidOptionsSchemaException::becauseOptionItemIsInvalid($key);
+            }
+
+            $value = $option['value'] ?? null;
+            $label = $option['label'] ?? null;
+
+            if ($value === null || ! is_string($label) || $label === '') {
+                throw InvalidOptionsSchemaException::becauseOptionItemIsInvalid($key);
+            }
+        }
+    }
+}