• File: SchemaInterpreter.php
  • Full Path: /home/slvgwrnz/public_html/wp-content/plugins/elementor/vendor/wordpress/php-mcp-schema/src/Internal/SchemaInterpreter.php
  • Date Modified: 11/05/2026 9:17 AM
  • File size: 29.36 KB
  • MIME-type: text/x-php
  • Charset: utf-8
<?php

declare(strict_types=1);

namespace WP\McpSchema\Internal;

use WP\McpSchema\Exception\ValidationException;
use WP\McpSchema\Record;

/**
 * Bounded interpreter for the JSON Schema vocabulary used by supported MCP revisions.
 *
 * @internal
 */
final class SchemaInterpreter
{
    /** @var array<string, array<string, mixed>> */
    private $definitions;

    /** @var array<string, array{definition: string, versions: array<int, string>}> */
    private $records;

    /** @var array<string, class-string<Record>> */
    private $recordClassesByDefinition = array();

    /**
     * @var array<string, array{
     *   properties: array<string, array<string, mixed>>,
     *   required: array<string, true>,
     *   additional: mixed,
     *   additionalSpecified: bool
     * }>
     */
    private $objectShapesByDefinition = array();

    /** @var \Closure */
    private $recordFactory;

    /**
     * @param array<string, array<string, mixed>> $definitions
     * @param array<string, array{definition: string, versions: array<int, string>}> $records
     */
    public function __construct(array $definitions, string $revision, array $records)
    {
        $this->definitions = $definitions;
        $this->records     = $records;
        foreach ($records as $class => $metadata) {
            if (! in_array($revision, $metadata['versions'], true)) {
                continue;
            }
            if (isset($this->recordClassesByDefinition[$metadata['definition']])) {
                throw new \LogicException(sprintf(
                    'Revision %s maps definition %s to more than one record class.',
                    $revision,
                    $metadata['definition']
                ));
            }
            /** @var class-string<Record> $class */
            $this->recordClassesByDefinition[$metadata['definition']] = $class;
        }

        $factory = \Closure::bind(
            /**
             * @param class-string<Record> $class
             * @param array<string, mixed> $values
             * @param array<int, string>   $declaredFields
             */
            static function (string $class, array $values, array $declaredFields): Record {
                /** @var Record $record */
                $record = new $class($values, $declaredFields);

                return $record;
            },
            null,
            Record::class
        );
        if (! $factory instanceof \Closure) {
            throw new \LogicException('Unable to bind the private record hydrator.');
        }
        $this->recordFactory = $factory;
    }

    /**
     * @param class-string $rootClass
     * @param mixed        $value
     * @return object
     */
    public function hydrate(string $definition, string $rootClass, $value, bool $programmaticArrays)
    {
        $normalizer = new InputNormalizer($programmaticArrays);
        $normalized = $normalizer->normalize($value);
        $result     = $this->evaluateDefinition($definition, $normalized, '', 0, $rootClass, $programmaticArrays);
        if (! is_object($result) || ! $result instanceof $rootClass) {
            throw new \LogicException(sprintf('Hydrated %s does not implement requested root %s.', $definition, $rootClass));
        }

        return $result;
    }

    /**
     * @param mixed             $value
     * @param class-string|null $preferredClass
     * @return mixed
     */
    private function evaluateDefinition(
        string $name,
        $value,
        string $pointer,
        int $depth,
        ?string $preferredClass,
        bool $programmaticArrays
    ) {
        if (! isset($this->definitions[$name])) {
            throw new \LogicException(sprintf('Catalog reference points to unknown definition %s.', $name));
        }
        /** @var class-string<Record>|null $recordClass */
        $recordClass = $preferredClass !== null && isset($this->records[$preferredClass])
            ? $preferredClass
            : $this->recordClassForDefinition($name);
        if ($recordClass !== null) {
            return $this->evaluateObject(
                $this->objectShapeForDefinition($name),
                $value,
                $pointer,
                $depth,
                $recordClass,
                $programmaticArrays
            );
        }

        return $this->evaluateSchema(
            $this->definitions[$name],
            $value,
            $pointer,
            $depth,
            $programmaticArrays
        );
    }

    /**
     * @param array<string, mixed> $schema
     * @param mixed                $value
     * @return mixed
     */
    private function evaluateSchema(
        array $schema,
        $value,
        string $pointer,
        int $depth,
        bool $programmaticArrays
    ) {
        if ($depth > InputNormalizer::MAX_DEPTH) {
            throw new ValidationException($pointer, 'Schema evaluation exceeds the maximum nesting depth.');
        }

        if (isset($schema['$ref'])) {
            /** @var string $reference */
            $reference = $schema['$ref'];
            $name   = $this->referenceName($reference);
            $result = $this->evaluateDefinition($name, $value, $pointer, $depth, null, $programmaticArrays);
            $siblings = array_diff_key($schema, array('$ref' => true, 'description' => true));
            if ($siblings !== array()) {
                $this->evaluateSchema($siblings, $value, $pointer, $depth, $programmaticArrays);
            }

            return $result;
        }

        if (isset($schema['anyOf'])) {
            /** @var array<int, array<string, mixed>> $members */
            $members = $schema['anyOf'];

            return $this->evaluateAnyOf($members, $value, $pointer, $depth, $programmaticArrays);
        }

        $nominalAllOf = $this->nominalAllOfReference($schema);
        if ($nominalAllOf !== null) {
            $result = $this->evaluateDefinition(
                $nominalAllOf['name'],
                $value,
                $pointer,
                $depth,
                null,
                $programmaticArrays
            );
            /** @var array<int, array<string, mixed>> $members */
            $members = $schema['allOf'];
            foreach ($members as $index => $member) {
                if ($index === $nominalAllOf['index']) {
                    continue;
                }
                $this->evaluateSchema($member, $value, $pointer, $depth, $programmaticArrays);
            }
            $siblings = array_diff_key($schema, array('allOf' => true, 'description' => true));
            if ($siblings !== array()) {
                $this->evaluateSchema($siblings, $value, $pointer, $depth, $programmaticArrays);
            }

            return $result;
        }

        if ($this->constrainsObject($schema, array())) {
            return $this->evaluateObject(
                $this->objectShape($schema, array()),
                $value,
                $pointer,
                $depth,
                null,
                $programmaticArrays
            );
        }

        if (isset($schema['allOf'])) {
            /** @var array<int, array<string, mixed>> $members */
            $members = $schema['allOf'];
            $result  = $this->materializeAny($value);
            foreach ($members as $member) {
                $result = $this->evaluateSchema(
                    $member,
                    $value,
                    $pointer,
                    $depth,
                    $programmaticArrays
                );
            }
            $siblings = array_diff_key($schema, array('allOf' => true, 'description' => true));
            if ($siblings !== array()) {
                $result = $this->evaluateSchema(
                    $siblings,
                    $value,
                    $pointer,
                    $depth,
                    $programmaticArrays
                );
            }

            return $result;
        }

        if (array_key_exists('const', $schema) && ! self::jsonEquals($value, $schema['const'])) {
            throw new ValidationException($pointer, sprintf('Value must equal %s.', (string) json_encode($schema['const'])));
        }
        if (isset($schema['enum'])) {
            /** @var array<int, mixed> $enum */
            $enum = $schema['enum'];
            $matched = false;
            foreach ($enum as $allowed) {
                if (self::jsonEquals($value, $allowed)) {
                    $matched = true;
                    break;
                }
            }
            if (! $matched) {
                throw new ValidationException($pointer, 'Value is not one of the allowed enum members.');
            }
        }

        if (isset($schema['type']) && ! $this->matchesType($value, $schema['type'], $programmaticArrays)) {
            /** @var string|array<int, string> $schemaType */
            $schemaType = $schema['type'];
            $expected = is_array($schemaType) ? implode('|', $schemaType) : $schemaType;
            throw new ValidationException($pointer, sprintf('Expected %s, got %s.', $expected, self::valueType($value)));
        }
        if (isset($schema['minimum'])) {
            /** @var int|float $minimum */
            $minimum = $schema['minimum'];
            if (! is_int($value) && ! is_float($value) || $value < $minimum) {
                throw new ValidationException($pointer, sprintf('Number must be at least %s.', (string) $minimum));
            }
        }
        if (isset($schema['maximum'])) {
            /** @var int|float $maximum */
            $maximum = $schema['maximum'];
            if (! is_int($value) && ! is_float($value) || $value > $maximum) {
                throw new ValidationException($pointer, sprintf('Number must be at most %s.', (string) $maximum));
            }
        }

        // A type list such as ["array", "null"] accepts non-list values that
        // matchesType() already admitted, so list rules apply to lists only.
        $types = isset($schema['type']) ? (array) $schema['type'] : array();
        if (in_array('array', $types, true) && is_array($value) && InputNormalizer::isList($value)) {
            if (isset($schema['maxItems'])) {
                /** @var int $maxItems */
                $maxItems = $schema['maxItems'];
                if (count($value) > $maxItems) {
                    throw new ValidationException($pointer, sprintf('List must contain at most %d items.', $maxItems));
                }
            }
            $output = array();
            foreach ($value as $index => $item) {
                if (isset($schema['items'])) {
                    /** @var array<string, mixed> $itemSchema */
                    $itemSchema = $schema['items'];
                    $output[] = $this->evaluateSchema(
                        $itemSchema,
                        $item,
                        InputNormalizer::appendPointer($pointer, (string) $index),
                        $depth + 1,
                        $programmaticArrays
                    );
                } else {
                    $output[] = $this->materializeAny($item);
                }
            }

            return $output;
        }

        return $this->materializeAny($value);
    }

    /**
     * @param array<int, array<string, mixed>> $members
     * @param mixed                            $value
     * @return mixed
     */
    private function evaluateAnyOf(
        array $members,
        $value,
        string $pointer,
        int $depth,
        bool $programmaticArrays
    ) {
        $fields = $this->objectFields($value, $programmaticArrays);
        if ($fields === null) {
            foreach ($members as $member) {
                try {
                    return $this->evaluateSchema($member, $value, $pointer, $depth, $programmaticArrays);
                } catch (ValidationException $exception) {
                    // Scalar unions preserve canonical first-match hydration.
                }
            }
            throw new ValidationException($pointer, 'Value does not match any allowed union member.');
        }

        $candidates = $this->flattenUnionMembers($members, array());
        $hasSuccess = false;
        $firstResult = null;
        $hasObjectResult = false;
        $bestResult = null;
        $bestCoverage = -1;
        foreach ($candidates as $member) {
            $coverage = $this->declaredKeyCoverage($member, $fields);
            try {
                $result = $this->evaluateSchema($member, $value, $pointer, $depth, $programmaticArrays);
            } catch (ValidationException $exception) {
                continue;
            }
            // Preserve an empty PHP list when a member accepts it without object conversion.
            if ($value === array() && $result === array()) {
                return $result;
            }
            if (! $hasSuccess) {
                $hasSuccess = true;
                $firstResult = $result;
            }
            if ($coverage !== null && (! $hasObjectResult || $coverage > $bestCoverage)) {
                $hasObjectResult = true;
                $bestCoverage = $coverage;
                $bestResult = $result;
            }
        }

        if ($hasObjectResult) {
            return $bestResult;
        }
        if ($hasSuccess) {
            return $firstResult;
        }

        throw new ValidationException($pointer, 'Value does not match any allowed union member.');
    }

    /**
     * @param array<int, array<string, mixed>> $members
     * @param array<int, string>               $seen
     * @return array<int, array<string, mixed>>
     */
    private function flattenUnionMembers(array $members, array $seen): array
    {
        $flattened = array();
        foreach ($members as $member) {
            $nested = null;
            $name = null;
            $siblings = array_diff_key($member, array('anyOf' => true, 'description' => true));
            if (isset($member['anyOf']) && $siblings === array()) {
                /** @var array<int, array<string, mixed>> $nested */
                $nested = $member['anyOf'];
            } elseif (isset($member['$ref'])) {
                /** @var string $reference */
                $reference = $member['$ref'];
                $name = $this->referenceName($reference);
                $target = $this->definitions[$name];
                $targetSiblings = array_diff_key($target, array('anyOf' => true, 'description' => true));
                if (isset($target['anyOf']) && $targetSiblings === array()) {
                    /** @var array<int, array<string, mixed>> $nested */
                    $nested = $target['anyOf'];
                }
            }

            if ($nested === null) {
                $flattened[] = $member;
                continue;
            }
            if ($name !== null && in_array($name, $seen, true)) {
                throw new \LogicException(sprintf('Recursive union composition at %s.', $name));
            }
            $flattened = array_merge(
                $flattened,
                $this->flattenUnionMembers(
                    $nested,
                    $name === null ? $seen : array_merge($seen, array($name))
                )
            );
        }

        return $flattened;
    }

    /**
     * @param array<string, mixed> $member
     * @param array<string, mixed> $fields
     */
    private function declaredKeyCoverage(array $member, array $fields): ?int
    {
        if (! $this->constrainsObject($member, array())) {
            return null;
        }
        $properties = $this->objectShape($member, array())['properties'];
        $coverage = 0;
        foreach ($fields as $field => $_value) {
            if (array_key_exists((string) $field, $properties)) {
                ++$coverage;
            }
        }

        return $coverage;
    }

    /**
     * @param array{properties: array<string, array<string, mixed>>, required: array<string, true>, additional: mixed} $shape
     * @param mixed $value
     * @param class-string<Record>|null $recordClass
     * @return Record|\stdClass
     */
    private function evaluateObject(
        array $shape,
        $value,
        string $pointer,
        int $depth,
        ?string $recordClass,
        bool $programmaticArrays
    ) {
        $fields = $this->objectFields($value, $programmaticArrays);
        if ($fields === null) {
            throw new ValidationException($pointer, sprintf('Expected object, got %s.', self::valueType($value)));
        }

        foreach ($shape['required'] as $field => $_required) {
            if (! array_key_exists($field, $fields)) {
                throw new ValidationException(
                    InputNormalizer::appendPointer($pointer, $field),
                    'Required field is missing.'
                );
            }
        }

        $hydrated = array();
        foreach ($fields as $field => $item) {
            $fieldPointer = InputNormalizer::appendPointer($pointer, (string) $field);
            if (isset($shape['properties'][$field])) {
                $hydrated[$field] = $this->evaluateSchema(
                    $shape['properties'][$field],
                    $item,
                    $fieldPointer,
                    $depth + 1,
                    $programmaticArrays
                );
                continue;
            }
            if ($shape['additional'] === false) {
                throw new ValidationException($fieldPointer, 'Additional field is not allowed.');
            }
            if (is_array($shape['additional']) && $shape['additional'] !== array()) {
                $hydrated[$field] = $this->evaluateSchema(
                    $shape['additional'],
                    $item,
                    $fieldPointer,
                    $depth + 1,
                    $programmaticArrays
                );
            } else {
                $hydrated[$field] = $this->materializeAny($item);
            }
        }

        $declared = array_keys($shape['properties']);
        if ($recordClass !== null) {
            /** @var Record $record */
            $record = ($this->recordFactory)($recordClass, $hydrated, $declared);

            return $record;
        }

        $output = new \stdClass();
        foreach ($hydrated as $field => $item) {
            $output->{$field} = $item;
        }

        return $output;
    }

    /**
     * @param mixed $value
     * @return array<string, mixed>|null
     */
    private function objectFields($value, bool $programmaticArrays): ?array
    {
        if ($value instanceof \stdClass) {
            /** @var array<string, mixed> $fields */
            $fields = get_object_vars($value);

            return $fields;
        }
        if (
            ! $programmaticArrays ||
            ! is_array($value) ||
            ($value !== array() && InputNormalizer::isList($value))
        ) {
            return null;
        }

        $fields = array();
        foreach ($value as $key => $item) {
            $fields[(string) $key] = $item;
        }

        return $fields;
    }

    /**
     * @param array<string, mixed> $schema
     * @param array<int, string>   $seen
     * @return array{properties: array<string, array<string, mixed>>, required: array<string, true>, additional: mixed, additionalSpecified: bool}
     */
    private function objectShape(array $schema, array $seen): array
    {
        $shape = array(
            'properties'          => array(),
            'required'            => array(),
            'additional'          => true,
            'additionalSpecified' => false,
        );
        if (isset($schema['$ref'])) {
            /** @var string $reference */
            $reference = $schema['$ref'];
            $name = $this->referenceName($reference);
            if (in_array($name, $seen, true)) {
                throw new \LogicException(sprintf('Recursive object composition at %s.', $name));
            }
            $this->mergeShape(
                $shape,
                $this->objectShapeForDefinition($name, $seen)
            );
        }
        /** @var array<int, array<string, mixed>> $allOf */
        $allOf = $schema['allOf'] ?? array();
        foreach ($allOf as $member) {
            $this->mergeShape($shape, $this->objectShape($member, $seen));
        }
        /** @var array<string, array<string, mixed>> $properties */
        $properties = $schema['properties'] ?? array();
        foreach ($properties as $field => $propertySchema) {
            if (isset($shape['properties'][$field])) {
                $shape['properties'][$field] = array(
                    'allOf' => array($shape['properties'][$field], $propertySchema),
                );
            } else {
                $shape['properties'][$field] = $propertySchema;
            }
        }
        /** @var array<int, string> $required */
        $required = $schema['required'] ?? array();
        foreach ($required as $field) {
            $shape['required'][$field] = true;
        }
        if (array_key_exists('additionalProperties', $schema)) {
            $shape['additional']          = $schema['additionalProperties'];
            $shape['additionalSpecified'] = true;
        }

        return $shape;
    }

    /**
     * @param array<int, string> $seen
     * @return array{properties: array<string, array<string, mixed>>, required: array<string, true>, additional: mixed, additionalSpecified: bool}
     */
    private function objectShapeForDefinition(string $name, array $seen = array()): array
    {
        if (isset($this->objectShapesByDefinition[$name])) {
            return $this->objectShapesByDefinition[$name];
        }
        if (! isset($this->definitions[$name])) {
            throw new \LogicException(sprintf('Catalog reference points to unknown definition %s.', $name));
        }
        if (in_array($name, $seen, true)) {
            throw new \LogicException(sprintf('Recursive object composition at %s.', $name));
        }

        $shape = $this->objectShape(
            $this->definitions[$name],
            array_merge($seen, array($name))
        );
        $this->objectShapesByDefinition[$name] = $shape;

        return $shape;
    }

    /**
     * @param array<string, mixed> $schema
     * @return array{name: string, index: int}|null
     */
    private function nominalAllOfReference(array $schema): ?array
    {
        if (! isset($schema['allOf']) || ! is_array($schema['allOf'])) {
            return null;
        }
        $references = array();
        foreach ($schema['allOf'] as $index => $member) {
            if (! isset($member['$ref'])) {
                continue;
            }
            $siblings = array_diff_key($member, array('$ref' => true, 'description' => true));
            if ($siblings === array()) {
                $references[] = array('index' => $index, 'member' => $member);
            }
        }
        if (count($references) !== 1) {
            return null;
        }

        /** @var string $reference */
        $reference = $references[0]['member']['$ref'];
        $name = $this->referenceName($reference);
        if ($this->recordClassForDefinition($name) === null) {
            return null;
        }
        $baseProperties = $this->objectShapeForDefinition($name)['properties'];
        $refinements = array();
        foreach ($schema['allOf'] as $index => $member) {
            if ($index !== $references[0]['index']) {
                $refinements[] = $member;
            }
        }
        $siblings = array_diff_key($schema, array('allOf' => true, 'description' => true));
        if ($siblings !== array()) {
            $refinements[] = $siblings;
        }

        foreach ($refinements as $refinement) {
            $shape = $this->objectShape($refinement, array());
            foreach (array_keys($shape['properties'] + $shape['required']) as $field) {
                if (! array_key_exists($field, $baseProperties)) {
                    return null;
                }
            }
        }

        return array('name' => $name, 'index' => $references[0]['index']);
    }

    /**
     * Whether a schema intersection constrains the value as an object.
     *
     * JSON Schema permits `allOf` for primitive refinements as well as object
     * composition. Only object intersections may be flattened into a property
     * shape; primitive intersections must evaluate each member independently.
     *
     * @param array<string, mixed> $schema
     * @param array<int, string>   $seen
     */
    private function constrainsObject(array $schema, array $seen): bool
    {
        if (($schema['type'] ?? null) === 'object' || isset($schema['properties'])) {
            return true;
        }
        if (isset($schema['$ref'])) {
            /** @var string $reference */
            $reference = $schema['$ref'];
            $name = $this->referenceName($reference);
            if (in_array($name, $seen, true)) {
                return false;
            }

            return $this->constrainsObject(
                $this->definitions[$name],
                array_merge($seen, array($name))
            );
        }
        /** @var array<int, array<string, mixed>> $allOf */
        $allOf = $schema['allOf'] ?? array();
        foreach ($allOf as $member) {
            if ($this->constrainsObject($member, $seen)) {
                return true;
            }
        }

        return false;
    }

    /**
     * @param array{properties: array<string, array<string, mixed>>, required: array<string, true>, additional: mixed, additionalSpecified: bool} $target
     * @param array{properties: array<string, array<string, mixed>>, required: array<string, true>, additional: mixed, additionalSpecified: bool} $source
     */
    private function mergeShape(array &$target, array $source): void
    {
        foreach ($source['properties'] as $field => $schema) {
            if (isset($target['properties'][$field])) {
                $target['properties'][$field] = array(
                    'allOf' => array($target['properties'][$field], $schema),
                );
            } else {
                $target['properties'][$field] = $schema;
            }
        }
        $target['required'] += $source['required'];
        if ($source['additionalSpecified']) {
            $target['additional']          = $source['additional'];
            $target['additionalSpecified'] = true;
        }
    }

    /**
     * @param mixed $expected
     * @param mixed $value
     */
    private function matchesType($value, $expected, bool $programmaticArrays): bool
    {
        foreach ((array) $expected as $type) {
            if ($type === 'null' && $value === null) return true;
            if ($type === 'boolean' && is_bool($value)) return true;
            if ($type === 'string' && is_string($value)) return true;
            if ($type === 'number' && (is_int($value) || is_float($value))) return true;
            if (
                $type === 'integer' &&
                (
                    is_int($value) ||
                    is_float($value) &&
                    is_finite($value) &&
                    floor($value) === $value &&
                    $value >= (float) PHP_INT_MIN &&
                    $value < -((float) PHP_INT_MIN)
                )
            ) {
                return true;
            }
            if ($type === 'array' && is_array($value) && InputNormalizer::isList($value)) return true;
            if (
                $type === 'object' &&
                (
                    $value instanceof \stdClass ||
                    $programmaticArrays &&
                    is_array($value) &&
                    ($value === array() || ! InputNormalizer::isList($value))
                )
            ) {
                return true;
            }
        }

        return false;
    }

    /**
     * @param mixed $value
     * @return mixed
     */
    private function materializeAny($value)
    {
        if ($value instanceof \stdClass) {
            $output = new \stdClass();
            foreach (get_object_vars($value) as $key => $item) {
                $output->{$key} = $this->materializeAny($item);
            }

            return $output;
        }
        if (! is_array($value)) {
            return $value;
        }
        if (InputNormalizer::isList($value)) {
            return array_map(array($this, 'materializeAny'), $value);
        }

        $output = new \stdClass();
        foreach ($value as $key => $item) {
            $output->{(string) $key} = $this->materializeAny($item);
        }

        return $output;
    }

    private function recordClassForDefinition(string $definition): ?string
    {
        return $this->recordClassesByDefinition[$definition] ?? null;
    }

    private function referenceName(string $reference): string
    {
        if (! preg_match('/^#\/\$defs\/([A-Za-z][A-Za-z0-9]*)$/', $reference, $matches)) {
            throw new \LogicException(sprintf('Unsupported catalog reference %s.', $reference));
        }

        return $matches[1];
    }

    /**
     * @param mixed $left
     * @param mixed $right
     */
    private static function jsonEquals($left, $right): bool
    {
        if ((is_int($left) || is_float($left)) && (is_int($right) || is_float($right))) {
            return $left == $right;
        }

        return $left === $right;
    }

    /**
     * @param mixed $value
     */
    private static function valueType($value): string
    {
        if ($value instanceof \stdClass) return 'object';
        if (is_array($value)) return InputNormalizer::isList($value) ? 'array' : 'object-like PHP array';
        if (is_int($value)) return 'integer';
        if (is_float($value)) return 'number';
        if (is_bool($value)) return 'boolean';
        if ($value === null) return 'null';

        return gettype($value);
    }
}