Walk bare $ref chains iteratively, not by mutual recursion

A chain of {"$ref": ...} nodes is meant to cost nothing regardless of
length, but cost()/refCost() resolved it by mutual recursion - one
native call frame per link. A chain long enough (~17-20k links, well
within default maxProperties/maxDepth combined across sibling maps)
exhausted the stack or its backing memory before the subschema budget
or depth ceiling ever got a chance to refuse it: the guard was
bypassable by the exact class of input it exists to stop.

refCost() now walks the chain in a loop at constant stack depth,
handing only the schema found at the end of it to cost() for its own
already depth-bounded recursion.

Author: chr-hertel

src/Capability/Discovery/SchemaComplexityGuard.php

@@ -171,35 +171,69 @@ private function cost(array $node, array $root, array $stack, int $depth, object
     }
 
     /**
+     * Chases a same-document `$ref`, and every bare `$ref` it in turn points
+     * to, without recursing: a node that is only `{"$ref": ...}` contributes
+     * nothing of its own, so a schema chaining many of them (a "flat" `$defs`
+     * indirection) is meant to be free regardless of length. Resolving that
+     * chain by mutual recursion with {@see cost()} spent one native call
+     * frame per link, so a chain long enough — a size none of the other
+     * bounds catch, since a chain's cost is deliberately independent of its
+     * length — exhausted the stack or the memory backing it before this
+     * class ever got to refuse anything. Walking the chain in a loop keeps
+     * this at constant stack depth; only the schema found at the end of it,
+     * if any, is handed to cost() for its own depth-bounded recursion.
+     *
      * @param array<string, mixed> $root
-     * @param list<string>         $stack
+     * @param list<string>         $stack pointers being resolved by an enclosing call
      */
     private function refCost(string $pointer, array $root, array $stack, int $depth, object $memo): int
     {
-        // A back-edge: recursive schemas are legitimate, and how far one
-        // unrolls is decided by the data, not the schema.
-        if (\in_array($pointer, $stack, true)) {
-            return 1;
-        }
+        $visited = [];
 
-        if (isset($memo->{$pointer})) {
-            return $memo->{$pointer};
-        }
+        while (true) {
+            // A back-edge: recursive schemas are legitimate, and how far one
+            // unrolls is decided by the data, not the schema.
+            if (\in_array($pointer, $stack, true) || isset($visited[$pointer])) {
+                return $this->memoizeAll($visited, 1, $memo);
+            }
+
+            if (isset($memo->{$pointer})) {
+                return $this->memoizeAll($visited, $memo->{$pointer}, $memo);
+            }
+
+            $target = self::resolve($pointer, $root);
+
+            if (null === $target) {
+                // Unresolvable same-document pointers are the validator's
+                // business to report; nothing here can be expensive.
+                return $this->memoizeAll($visited, 1, $memo);
+            }
 
-        $target = self::resolve($pointer, $root);
+            $visited[$pointer] = true;
 
-        if (null === $target) {
-            // Unresolvable same-document pointers are the validator's business
-            // to report; nothing here can be expensive.
-            return 1;
+            if (!isset($target['$ref']) || !\is_string($target['$ref'])) {
+                // Depth is lexical nesting, which following a reference is
+                // not: a long chain of `$defs` referring to one another is
+                // flat and cheap. What bounds this is the subschema budget
+                // and the cycle check above, and the pointer set is finite,
+                // so the walk is too.
+                $cost = $this->cost($target, $root, [...$stack, ...array_keys($visited)], $depth, $memo);
+
+                return $this->memoizeAll($visited, $cost, $memo);
+            }
+
+            $pointer = $target['$ref'];
         }
+    }
 
-        // Depth is lexical nesting, which following a reference is not: a long
-        // chain of `$defs` referring to one another is flat and cheap. What
-        // bounds this is the subschema budget and the cycle check above, and
-        // the pointer set is finite, so the recursion is too.
-        $cost = $this->cost($target, $root, [...$stack, $pointer], $depth, $memo);
-        $memo->{$pointer} = $cost;
+    /**
+     * @param array<string, true> $pointers
+     */
+    private function memoizeAll(array $pointers, int $cost, object $memo): int
+    {
+        foreach ($pointers as $pointer => $_) {
+            $memo->{$pointer} = $cost;
+        }
 
         return $cost;
     }

tests/Unit/Capability/Discovery/SchemaComplexityGuardTest.php

@@ -160,6 +160,27 @@ public function testLongLocalRefChainIsAllowed(): void
         $this->assertNull($this->guard->check(['$defs' => $defs, '$ref' => '#/$defs/a60']));
     }
 
+    #[TestDox('a long chain of bare $refs is walked without recursing per link')]
+    public function testLongLocalRefChainDoesNotRecursePerLink(): void
+    {
+        // Bare {"$ref": ...} nodes chained together are meant to be free
+        // regardless of length, and used to be resolved by mutual recursion
+        // between cost() and refCost(): one native call frame per link. A
+        // chain long enough exhausted the stack, or the memory backing it,
+        // long before the subschema budget below ever got a chance to fire —
+        // 20,000 links reliably faulted with the old implementation. This
+        // uses a guard with a raised budget so the chain is not refused for
+        // an unrelated reason, and asserts it resolves at all.
+        $defs = ['a0' => ['type' => 'string']];
+        for ($i = 1; $i < 20_000; ++$i) {
+            $defs['a'.$i] = ['$ref' => '#/$defs/a'.($i - 1)];
+        }
+
+        $guard = new SchemaComplexityGuard(maxSubschemas: 1_000_000, maxProperties: 1_000_000);
+
+        $this->assertNull($guard->check(['$defs' => $defs, '$ref' => '#/$defs/a19999']));
+    }
+
     #[TestDox('a recursive schema is allowed: how far it unrolls is the data\'s doing')]
     public function testRecursiveSchemaIsAllowed(): void
     {