[FEATURE] Give DirectiveNode logger info, migrate logging directives

DirectiveNode now captures source location (file, line) once its
content is fully parsed -- available to createNode() for directives
that log a warning about their own content. Captured post-parse, not
at construction: the old dispatch always fully exhausts the content
iterator before a directive's own code runs, even for empty content,
so capturing earlier gave a different (wrong) line number -- caught
against directive-with-warning's exact log-line assertion.

Migrates TestLoggerDirective, SectionauthorDirective,
ConfigurationBlockDirective, and TabsDirective (paired with
TabDirective in the same commit, since migrating TabDirective alone
previously broke tabs_html -- TabsDirective inspects its children's
concrete type, which only resolves correctly once both are on the
compile-time model together). createNode() is the only method kept,
per jaapio's review on #1379.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PP4LkejR5PSubbhNmF4RkT
Signed-off-by: lina.wolf

Author: 2 people

packages/guides-restructured-text/src/RestructuredText/Directives/ConfigurationBlockDirective.php

@@ -18,8 +18,7 @@
 use phpDocumentor\Guides\Nodes\Configuration\ConfigurationBlockNode;
 use phpDocumentor\Guides\Nodes\Configuration\ConfigurationTab;
 use phpDocumentor\Guides\Nodes\Node;
-use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
-use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Nodes\DirectiveNode;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\String\Slugger\AsciiSlugger;
@@ -29,6 +28,7 @@
 use function get_debug_type;
 use function sprintf;
 
+#[Attributes\Directive(name: 'configuration-block')]
 final class ConfigurationBlockDirective extends SubDirective
 {
     private SluggerInterface $slugger;
@@ -47,22 +47,14 @@ public function __construct(
         $this->slugger = new AsciiSlugger();
     }
 
-    public function getName(): string
+    public function createNode(DirectiveNode $directiveNode): Node
     {
-        return 'configuration-block';
-    }
-
-    protected function processSub(
-        BlockContext $blockContext,
-        CollectionNode $collectionNode,
-        Directive $directive,
-    ): Node {
         $tabs = [];
-        foreach ($collectionNode->getValue() as $child) {
+        foreach ($directiveNode->getChildren() as $child) {
             if (!$child instanceof CodeNode) {
                 $this->logger->warning(
                     sprintf('The ".. configuration-block::" directive only supports code blocks, "%s" given.', get_debug_type($child)),
-                    $blockContext->getLoggerInformation(),
+                    $directiveNode->getLoggerInformation(),
                 );
 
                 continue;

packages/guides-restructured-text/src/RestructuredText/Directives/SectionauthorDirective.php

@@ -15,12 +15,17 @@
 
 use phpDocumentor\Guides\Nodes\AuthorNode;
 use phpDocumentor\Guides\Nodes\Node;
-use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
-use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Nodes\DirectiveNode;
 use Psr\Log\LoggerInterface;
 
 use function preg_match;
 
+/**
+ * When the default domain contains a class directive, this directive will be shadowed. Therefore, Sphinx re-exports it as rst-class.
+ *
+ * See https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rstclass
+ */
+#[Attributes\Directive(name: 'sectionauthor', aliases: ['codeauthor'])]
 final class SectionauthorDirective extends BaseDirective
 {
     /** @see https://regex101.com/r/vGy4Uu/1 */
@@ -31,41 +36,19 @@ public function __construct(
     ) {
     }
 
-    public function getName(): string
-    {
-        return 'sectionauthor';
-    }
-
-    /**
-     * When the default domain contains a class directive, this directive will be shadowed. Therefore, Sphinx re-exports it as rst-class.
-     *
-     * See https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rstclass
-     *
-     * @return string[]
-     */
-    public function getAliases(): array
+    public function createNode(DirectiveNode $directiveNode): Node|null
     {
-        return ['codeauthor'];
-    }
-
-    /** {@inheritDoc}
-     *
-     * @param Directive $directive
-     */
-    public function process(
-        BlockContext $blockContext,
-        Directive $directive,
-    ): Node|null {
+        $directive = $directiveNode->getDirective();
         $input = $directive->getData();
         $directiveName = $directive->getName();
         if ($input === '') {
-            $this->logger->warning('`.. ' . $directiveName . ' ::` directive could not be parsed: `' . $input . '`', $blockContext->getLoggerInformation());
+            $this->logger->warning('`.. ' . $directiveName . ' ::` directive could not be parsed: `' . $input . '`', $directiveNode->getLoggerInformation());
 
             return null;
         }
 
         if (!preg_match(self::NAME_EMAIL_REGEX, $input, $matches)) {
-            $this->logger->warning('Content of `.. ' . $directiveName . ':: name <email>` must specify a name and can also specify an email', $blockContext->getLoggerInformation());
+            $this->logger->warning('Content of `.. ' . $directiveName . ':: name <email>` must specify a name and can also specify an email', $directiveNode->getLoggerInformation());
 
             return null;
         }

packages/guides-restructured-text/src/RestructuredText/Directives/TabDirective.php

@@ -13,12 +13,10 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Directives;
 
-use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Nodes\DirectiveNode;
 use phpDocumentor\Guides\RestructuredText\Nodes\TabNode;
-use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
-use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
 use function class_alias;
 use function class_exists;
@@ -27,22 +25,13 @@
 use function str_replace;
 use function strtolower;
 
+#[Attributes\Directive(name: 'tab')]
 final class TabDirective extends SubDirective
 {
-    public function getName(): string
+    public function createNode(DirectiveNode $directiveNode): Node
     {
-        return 'tab';
-    }
+        $directive = $directiveNode->getDirective();
 
-    /** {@inheritDoc}
-     *
-     * @param Directive $directive
-     */
-    protected function processSub(
-        BlockContext $blockContext,
-        CollectionNode $collectionNode,
-        Directive $directive,
-    ): Node {
         if (is_string($directive->getOption('key')->getValue())) {
             $key = strtolower($directive->getOption('key')->getValue());
         } else {
@@ -59,7 +48,7 @@ protected function processSub(
             $directive->getDataNode() ?? new InlineCompoundNode(),
             $key,
             $active,
-            $collectionNode->getChildren(),
+            $directiveNode->getChildren(),
         );
     }
 }

packages/guides-restructured-text/src/RestructuredText/Directives/TabsDirective.php

@@ -18,16 +18,16 @@
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
 use phpDocumentor\Guides\RestructuredText\Nodes\AbstractTabNode;
+use phpDocumentor\Guides\RestructuredText\Nodes\DirectiveNode;
 use phpDocumentor\Guides\RestructuredText\Nodes\TabsNode;
-use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
-use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 use Psr\Log\LoggerInterface;
 
 use function class_alias;
 use function class_exists;
 use function is_string;
 
+#[Attributes\Directive(name: 'tabs')]
 final class TabsDirective extends SubDirective
 {
     private int $tabsCounter = 0;
@@ -41,23 +41,12 @@ public function __construct(
         parent::__construct($startingRule);
     }
 
-    public function getName(): string
+    public function createNode(DirectiveNode $directiveNode): Node
     {
-        return 'tabs';
-    }
-
-    /** {@inheritDoc}
-     *
-     * @param Directive $directive
-     */
-    protected function processSub(
-        BlockContext $blockContext,
-        CollectionNode $collectionNode,
-        Directive $directive,
-    ): Node {
+        $directive = $directiveNode->getDirective();
         $tabs = [];
         $hasActive = false;
-        foreach ($collectionNode->getChildren() as $child) {
+        foreach ($directiveNode->getChildren() as $child) {
             if ($child instanceof AbstractTabNode) {
                 if ($child->isActive()) {
                     if (!$hasActive) {
@@ -72,7 +61,7 @@ protected function processSub(
             } else {
                 $this->logger->warning(
                     'The "tabs" directive may only contain children of type "tab". The following node was found: ' . $child::class,
-                    $blockContext->getLoggerInformation(),
+                    $directiveNode->getLoggerInformation(),
                 );
             }
         }

packages/guides-restructured-text/src/RestructuredText/Directives/TestLoggerDirective.php

@@ -13,11 +13,9 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Directives;
 
-use phpDocumentor\Guides\Nodes\CollectionNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Nodes\ContainerNode;
-use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
-use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Nodes\DirectiveNode;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 use Psr\Log\LoggerInterface;
 
@@ -26,6 +24,7 @@
  *
  * @link https://docutils.sourceforge.io/docs/ref/rst/directives.html#container
  */
+#[Attributes\Directive(name: 'testlogger')]
 final class TestLoggerDirective extends SubDirective
 {
     public function __construct(
@@ -35,22 +34,11 @@ public function __construct(
         parent::__construct($startingRule);
     }
 
-    public function getName(): string
+    public function createNode(DirectiveNode $directiveNode): Node
     {
-        return 'testlogger';
-    }
-
-    /** {@inheritDoc}
-     *
-     * @param Directive $directive
-     */
-    protected function processSub(
-        BlockContext $blockContext,
-        CollectionNode $collectionNode,
-        Directive $directive,
-    ): Node {
-        $this->logger->warning('Test logging in directives', $blockContext->getLoggerInformation());
+        $this->logger->warning('Test logging in directives', $directiveNode->getLoggerInformation());
 
-        return (new ContainerNode($collectionNode->getChildren()))->withOptions(['class' => $directive->getData()]);
+        return (new ContainerNode($directiveNode->getChildren()))
+            ->withOptions(['class' => $directiveNode->getDirective()->getData()]);
     }
 }

packages/guides-restructured-text/src/RestructuredText/Nodes/DirectiveNode.php

@@ -20,6 +20,9 @@
 /** @extends CompoundNode<Node> */
 final class DirectiveNode extends CompoundNode
 {
+    /** @var array<string, int|string> */
+    private array $loggerInformation = [];
+
     /** @param Node[] $children */
     public function __construct(private readonly Directive $directive, array $children = [])
     {
@@ -30,4 +33,23 @@ public function getDirective(): Directive
     {
         return $this->directive;
     }
+
+    /**
+     * Source location info (file, line), set once the directive's content has
+     * been fully parsed -- available to createNode() for directives that need
+     * to log a warning about their own content, since createNode() itself has
+     * no access to BlockContext.
+     *
+     * @param array<string, int|string> $loggerInformation
+     */
+    public function setLoggerInformation(array $loggerInformation): void
+    {
+        $this->loggerInformation = $loggerInformation;
+    }
+
+    /** @return array<string, int|string> */
+    public function getLoggerInformation(): array
+    {
+        return $this->loggerInformation;
+    }
 }

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/DirectiveRule.php

@@ -95,10 +95,14 @@ public function apply(BlockContext $blockContext, CompoundNode|null $on = null):
         $buffer = $this->collectDirectiveContents($documentIterator);
 
         if ($this->startingRule !== null && $directiveHandler->isUpgraded()) {
-            $node = $this->startingRule->apply(
-                new BlockContext($blockContext->getDocumentParserContext(), $buffer->getLinesString(), true, $documentIterator->key()),
-                new DirectiveNode($directive),
-            );
+            $subBlockContext = new BlockContext($blockContext->getDocumentParserContext(), $buffer->getLinesString(), true, $documentIterator->key());
+            $directiveNode = new DirectiveNode($directive);
+            $node = $this->startingRule->apply($subBlockContext, $directiveNode);
+            // Captured only after the sub-parse has fully consumed $subBlockContext's
+            // content, matching what a directive's own logging call would have seen
+            // under the old (non-upgraded) dispatch, where content is always parsed
+            // before the directive's own code runs.
+            $directiveNode->setLoggerInformation($subBlockContext->getLoggerInformation());
 
             if ($node === null) {
                 return null;