[Store] Add maxDepth to RstToctreeLoader for scoped indexing

chr-hertel · chr-hertel · commit dceb03069e0f · 2026-05-15T10:57:06.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+0.9
+---
+
+ * Add `maxDepth` constructor parameter to `RstToctreeLoader` to limit toctree recursion depth
+
 0.8
 ---
 
diff --git a/src/Document/Loader/RstToctreeLoader.php b/src/Document/Loader/RstToctreeLoader.php
@@ -29,7 +29,11 @@ public function __construct(
         private RstLoader $rstLoader = new RstLoader(),
         private bool $throwOnMissingEntry = false,
         private LoggerInterface $logger = new NullLogger(),
+        private ?int $maxDepth = null,
     ) {
+        if (null !== $maxDepth && $maxDepth < 0) {
+            throw new InvalidArgumentException(\sprintf('The maximum depth must be a non-negative integer or null, %d given.', $maxDepth));
+        }
     }
 
     /**
@@ -63,6 +67,10 @@ private function processFile(string $path, int $depth, string $rootDir): iterabl
 
         yield from $this->rstLoader->loadContent($content, $path, ['depth' => $depth]);
 
+        if (null !== $this->maxDepth && $depth >= $this->maxDepth) {
+            return;
+        }
+
         foreach ($this->parseToctreeEntries($content, \dirname($path), $rootDir) as $entryPath) {
             yield from $this->processFile($entryPath, $depth + 1, $rootDir);
         }
diff --git a/tests/Document/Loader/RstToctreeLoaderTest.php b/tests/Document/Loader/RstToctreeLoaderTest.php
@@ -270,6 +270,58 @@ public function testLoadToctreeSkipsMissingEntryByDefault()
         }
     }
 
+    public function testConstructorRejectsNegativeMaxDepth()
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('The maximum depth must be a non-negative integer or null, -1 given.');
+        new RstToctreeLoader(maxDepth: -1);
+    }
+
+    public function testMaxDepthZeroLoadsOnlySourceFile()
+    {
+        $loader = new RstToctreeLoader(maxDepth: 0);
+        $documents = iterator_to_array($loader->load($this->fixturesDir.'/with_absolute_toctree/index.rst'), false);
+
+        $titles = array_map(
+            static fn (EmbeddableDocumentInterface $doc): string => $doc->getMetadata()->getTitle() ?? '',
+            $documents,
+        );
+
+        $this->assertContains('Main Documentation', $titles);
+        $this->assertNotContains('Getting Started', $titles);
+        $this->assertNotContains('Setup', $titles);
+    }
+
+    public function testMaxDepthOneFollowsDirectEntriesOnly()
+    {
+        $loader = new RstToctreeLoader(maxDepth: 1);
+        $documents = iterator_to_array($loader->load($this->fixturesDir.'/with_absolute_toctree/index.rst'), false);
+
+        $titles = array_map(
+            static fn (EmbeddableDocumentInterface $doc): string => $doc->getMetadata()->getTitle() ?? '',
+            $documents,
+        );
+
+        $this->assertContains('Main Documentation', $titles);
+        $this->assertContains('Getting Started', $titles);
+        $this->assertNotContains('Setup', $titles);
+    }
+
+    public function testNullMaxDepthLoadsEntireTree()
+    {
+        $loader = new RstToctreeLoader(maxDepth: null);
+        $documents = iterator_to_array($loader->load($this->fixturesDir.'/with_absolute_toctree/index.rst'), false);
+
+        $titles = array_map(
+            static fn (EmbeddableDocumentInterface $doc): string => $doc->getMetadata()->getTitle() ?? '',
+            $documents,
+        );
+
+        $this->assertContains('Main Documentation', $titles);
+        $this->assertContains('Getting Started', $titles);
+        $this->assertContains('Setup', $titles);
+    }
+
     public function testLoadSectionOverflowCreatesMultipleChunks()
     {
         // Create a temporary file with a very long section
