fix(reflect): improve circular reference detection in Reflector

Author: wilcorrea

src/Core/Reflect/Reflector.php

@@ -92,6 +92,8 @@ protected function introspect(array $parameters, Schema $schema, ?Field $parent
      */
     private function introspectSource(string $source, Schema $schema, Field $parent, array $path): void
     {
+        $originalSource = $source;
+
         $result = $this->introspector->analyze($source);
         $introspection = $result->introspectable();
         if ($introspection !== null) {
@@ -104,9 +106,25 @@ private function introspectSource(string $source, Schema $schema, Field $parent,
             return;
         }
 
-        $this->sources[] = $source;
+        $this->pushSources($originalSource, $source);
         $this->introspect($nestedParameters, $schema, $parent, $path);
+        $this->popSources($originalSource, $source);
+    }
+
+    private function pushSources(string $originalSource, string $source): void
+    {
+        $this->sources[] = $originalSource;
+        if ($originalSource !== $source) {
+            $this->sources[] = $source;
+        }
+    }
+
+    private function popSources(string $originalSource, string $source): void
+    {
         array_pop($this->sources);
+        if ($originalSource !== $source) {
+            array_pop($this->sources);
+        }
     }
 
     private function wouldCauseCircularReference(string $source): bool
@@ -125,7 +143,7 @@ private function extractParameters(string $source): array
         if (is_array($parameters)) {
             return $parameters;
         }
-        $parameters = Target::createFrom((string)$source)
+        $parameters = Target::createFrom((string) $source)
             ->getReflectionParameters();
         return $this->cache->set($key, $parameters);
     }

tests/Core/Reflect/ReflectorTest.php

@@ -16,6 +16,7 @@
 use Constructo\Test\Stub\Domain\Entity\Command\GameCommand;
 use Constructo\Test\Stub\Domain\Entity\Command\PersonCommand;
 use Constructo\Test\Stub\Domain\Entity\EmptyClass;
+use Constructo\Test\Stub\Reflector\Node;
 use Constructo\Test\Stub\Reflector\Sample;
 use Constructo\Testing\MakeExtension;
 use PHPUnit\Framework\TestCase;
@@ -312,4 +313,20 @@ public function __construct(
         $nestedKeys = array_filter(array_keys($rules), fn ($key) => str_starts_with((string) $key, 'empty_field.'));
         $this->assertEmpty($nestedKeys);
     }
+
+    public function testReflectorHandlesCircularReferenceViaCollection(): void
+    {
+        $schema = $this->reflector->reflect(Node::class);
+        $rules = $schema->rules();
+
+        $json = '{
+          "name": ["required", "string"],
+          "children": ["sometimes", "nullable", "array"],
+          "children.*.name": ["sometimes", "string"],
+          "children.*.children": ["sometimes", "nullable", "array"]
+        }';
+        $expected = json_decode($json, true);
+
+        $this->assertEquals($expected, $rules);
+    }
 }

tests/Stub/Reflector/Node.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Constructo\Test\Stub\Reflector;
+
+class Node
+{
+    public function __construct(
+        public readonly string $name,
+        public readonly ?NodeCollection $children = null,
+    ) {
+    }
+}

tests/Stub/Reflector/NodeCollection.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Constructo\Test\Stub\Reflector;
+
+use Constructo\Type\Collection;
+
+/**
+ * @extends Collection<Node>
+ */
+final class NodeCollection extends Collection
+{
+    public function current(): Node
+    {
+        return $this->validate($this->datum());
+    }
+
+    protected function validate(mixed $datum): Node
+    {
+        return ($datum instanceof Node) ? $datum : throw $this->exception(Node::class, $datum);
+    }
+}