Use a separate stack for brackets

colinodell · colinodell · commit a8df15c6bc23 · 2024-12-07T10:17:03.000-05:00
See commonmark/commonmark.js#101
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,9 +11,11 @@ Updates should follow the [Keep a CHANGELOG](https://keepachangelog.com/) princi
 - Added `RegexHelper::isWhitespace()` method to check if a given character is an ASCII whitespace character
 - Added `CacheableDelimiterProcessorInterface` to ensure linear complexity for dynamic delimiter processing
 - Added `table/max_autocompleted_cells` config option to prevent denial of service attacks when parsing large tables
+- Added `Bracket` delimiter type to optimize bracket parsing
 
 ### Changed
 
+- `[` and `]` are no longer added as `Delimiter` objects on the stack; a new `Bracket` type with its own stack is used instead
 - `UrlAutolinkParser` no longer parses URLs with more than 127 subdomains
 - Expanded reference links can no longer exceed 100kb, or the size of the input document (whichever is greater)
 - Several small performance optimizations
@@ -93,6 +95,8 @@ Updates should follow the [Keep a CHANGELOG](https://keepachangelog.com/) princi
 
 - Returning dynamic values from `DelimiterProcessorInterface::getDelimiterUse()` is deprecated
     - You should instead implement `CacheableDelimiterProcessorInterface` to help the engine perform caching to avoid performance issues.
+- Deprecated `DelimiterInterface::isActive()` and `DelimiterInterface::setActive()`, as these are no longer used by the engine
+- Deprecated `DelimiterStack::removeEarlierMatches()` and `DelimiterStack::searchByCharacter()`, as these are no longer used by the engine
 
 ### Fixed
 
diff --git a/src/Delimiter/Bracket.php b/src/Delimiter/Bracket.php
@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the league/commonmark package.
+ *
+ * (c) Colin O'Dell <colinodell@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace League\CommonMark\Delimiter;
+
+use League\CommonMark\Node\Node;
+
+final class Bracket
+{
+    private Node $node;
+    private ?Bracket $previous;
+    private ?DelimiterInterface $previousDelimiter;
+    private bool $hasNext = false;
+    private int $index;
+    private bool $image;
+    private bool $active = true;
+
+    public function __construct(Node $node, ?Bracket $previous, ?DelimiterInterface $previousDelimiter, int $index, bool $image)
+    {
+        $this->node              = $node;
+        $this->previous          = $previous;
+        $this->previousDelimiter = $previousDelimiter;
+        $this->index             = $index;
+        $this->image             = $image;
+    }
+
+    public function getNode(): Node
+    {
+        return $this->node;
+    }
+
+    public function getPrevious(): ?Bracket
+    {
+        return $this->previous;
+    }
+
+    public function getPreviousDelimiter(): ?DelimiterInterface
+    {
+        return $this->previousDelimiter;
+    }
+
+    public function hasNext(): bool
+    {
+        return $this->hasNext;
+    }
+
+    public function getIndex(): int
+    {
+        return $this->index;
+    }
+
+    public function isImage(): bool
+    {
+        return $this->image;
+    }
+
+    public function isActive(): bool
+    {
+        return $this->active;
+    }
+
+    /**
+     * @internal
+     */
+    public function setHasNext(bool $hasNext): void
+    {
+        $this->hasNext = $hasNext;
+    }
+
+    /**
+     * @internal
+     */
+    public function setActive(bool $active): void
+    {
+        $this->active = $active;
+    }
+}
diff --git a/src/Delimiter/DelimiterInterface.php b/src/Delimiter/DelimiterInterface.php
@@ -24,8 +24,14 @@ public function canClose(): bool;
 
     public function canOpen(): bool;
 
+    /**
+     * @deprecated This method is no longer used internally and will be removed in 3.0
+     */
     public function isActive(): bool;
 
+    /**
+     * @deprecated This method is no longer used internally and will be removed in 3.0
+     */
     public function setActive(bool $active): void;
 
     public function getChar(): string;
diff --git a/src/Delimiter/DelimiterStack.php b/src/Delimiter/DelimiterStack.php
@@ -22,12 +22,16 @@
 use League\CommonMark\Delimiter\Processor\CacheableDelimiterProcessorInterface;
 use League\CommonMark\Delimiter\Processor\DelimiterProcessorCollection;
 use League\CommonMark\Node\Inline\AdjacentTextMerger;
+use League\CommonMark\Node\Node;
 
 final class DelimiterStack
 {
     /** @psalm-readonly-allow-private-mutation */
     private ?DelimiterInterface $top = null;
 
+    /** @psalm-readonly-allow-private-mutation */
+    private ?Bracket $brackets = null;
+
     public function push(DelimiterInterface $newDelimiter): void
     {
         $newDelimiter->setPrevious($this->top);
@@ -39,6 +43,26 @@ public function push(DelimiterInterface $newDelimiter): void
         $this->top = $newDelimiter;
     }
 
+    /**
+     * @internal
+     */
+    public function addBracket(Node $node, int $index, bool $image): void
+    {
+        if ($this->brackets !== null) {
+            $this->brackets->setHasNext(true);
+        }
+
+        $this->brackets = new Bracket($node, $this->brackets, $this->top, $index, $image);
+    }
+
+    /**
+     * @psalm-immutable
+     */
+    public function getLastBracket(): ?Bracket
+    {
+        return $this->brackets;
+    }
+
     private function findEarliest(?DelimiterInterface $stackBottom = null): ?DelimiterInterface
     {
         $delimiter = $this->top;
@@ -49,6 +73,22 @@ private function findEarliest(?DelimiterInterface $stackBottom = null): ?Delimit
         return $delimiter;
     }
 
+    /**
+     * @internal
+     */
+    public function removeBracket(): void
+    {
+        if ($this->brackets === null) {
+            return;
+        }
+
+        $this->brackets = $this->brackets->getPrevious();
+
+        if ($this->brackets !== null) {
+            $this->brackets->setHasNext(false);
+        }
+    }
+
     public function removeDelimiter(DelimiterInterface $delimiter): void
     {
         if ($delimiter->getPrevious() !== null) {
@@ -98,6 +138,9 @@ public function removeAll(?DelimiterInterface $stackBottom = null): void
         }
     }
 
+    /**
+     * @deprecated This method is no longer used internally and will be removed in 3.0
+     */
     public function removeEarlierMatches(string $character): void
     {
         $opener = $this->top;
@@ -111,6 +154,22 @@ public function removeEarlierMatches(string $character): void
     }
 
     /**
+     * @internal
+     */
+    public function deactivateLinkOpeners(): void
+    {
+        $opener = $this->brackets;
+        while ($opener !== null) {
+            if (! $opener->isImage()) {
+                $opener->setActive(false);
+            }
+            $opener = $opener->getPrevious();
+        }
+    }
+
+    /**
+     * @deprecated This method is no longer used internally and will be removed in 3.0
+     *
      * @param string|string[] $characters
      */
     public function searchByCharacter($characters): ?DelimiterInterface
@@ -233,6 +292,12 @@ public function processDelimiters(?DelimiterInterface $stackBottom, DelimiterPro
      */
     public function __destruct()
     {
-        $this->removeAll();
+        while ($this->top) {
+            $this->removeDelimiter($this->top);
+        }
+
+        while ($this->brackets) {
+            $this->removeBracket();
+        }
     }
 }
diff --git a/src/Extension/CommonMark/Parser/Inline/BangParser.php b/src/Extension/CommonMark/Parser/Inline/BangParser.php
@@ -16,7 +16,6 @@
 
 namespace League\CommonMark\Extension\CommonMark\Parser\Inline;
 
-use League\CommonMark\Delimiter\Delimiter;
 use League\CommonMark\Node\Inline\Text;
 use League\CommonMark\Parser\Inline\InlineParserInterface;
 use League\CommonMark\Parser\Inline\InlineParserMatch;
@@ -38,8 +37,7 @@ public function parse(InlineParserContext $inlineContext): bool
         $inlineContext->getContainer()->appendChild($node);
 
         // Add entry to stack for this opener
-        $delimiter = new Delimiter('!', 1, $node, true, false, $cursor->getPosition());
-        $inlineContext->getDelimiterStack()->push($delimiter);
+        $inlineContext->getDelimiterStack()->addBracket($node, $cursor->getPosition(), true);
 
         return true;
     }
diff --git a/src/Extension/CommonMark/Parser/Inline/CloseBracketParser.php b/src/Extension/CommonMark/Parser/Inline/CloseBracketParser.php
@@ -16,6 +16,7 @@
 
 namespace League\CommonMark\Extension\CommonMark\Parser\Inline;
 
+use League\CommonMark\Delimiter\Bracket;
 use League\CommonMark\Environment\EnvironmentAwareInterface;
 use League\CommonMark\Environment\EnvironmentInterface;
 use League\CommonMark\Extension\CommonMark\Node\Inline\AbstractWebResource;
@@ -46,14 +47,14 @@ public function getMatchDefinition(): InlineParserMatch
     public function parse(InlineParserContext $inlineContext): bool
     {
         // Look through stack of delimiters for a [ or !
-        $opener = $inlineContext->getDelimiterStack()->searchByCharacter(['[', '!']);
+        $opener = $inlineContext->getDelimiterStack()->getLastBracket();
         if ($opener === null) {
             return false;
         }
 
         if (! $opener->isActive()) {
-            // no matched opener; remove from emphasis stack
-            $inlineContext->getDelimiterStack()->removeDelimiter($opener);
+            // no matched opener; remove from stack
+            $inlineContext->getDelimiterStack()->removeBracket();
 
             return false;
         }
@@ -70,21 +71,19 @@ public function parse(InlineParserContext $inlineContext): bool
         // Inline link?
         if ($result = $this->tryParseInlineLinkAndTitle($cursor)) {
             $link = $result;
-        } elseif ($link = $this->tryParseReference($cursor, $inlineContext->getReferenceMap(), $opener->getIndex(), $startPos)) {
+        } elseif ($link = $this->tryParseReference($cursor, $inlineContext->getReferenceMap(), $opener, $startPos)) {
             $reference = $link;
             $link      = ['url' => $link->getDestination(), 'title' => $link->getTitle()];
         } else {
-            // No match
-            $inlineContext->getDelimiterStack()->removeDelimiter($opener); // Remove this opener from stack
+            // No match; remove this opener from stack
+            $inlineContext->getDelimiterStack()->removeBracket();
             $cursor->restoreState($previousState);
 
             return false;
         }
 
-        $isImage = $opener->getChar() === '!';
-
-        $inline = $this->createInline($link['url'], $link['title'], $isImage, $reference ?? null);
-        $opener->getInlineNode()->replaceWith($inline);
+        $inline = $this->createInline($link['url'], $link['title'], $opener->isImage(), $reference ?? null);
+        $opener->getNode()->replaceWith($inline);
         while (($label = $inline->next()) !== null) {
             // Is there a Mention or Link contained within this link?
             // CommonMark does not allow nested links, so we'll restore the original text.
@@ -104,17 +103,18 @@ public function parse(InlineParserContext $inlineContext): bool
 
         // Process delimiters such as emphasis inside link/image
         $delimiterStack = $inlineContext->getDelimiterStack();
-        $stackBottom    = $opener->getPrevious();
+        $stackBottom    = $opener->getPreviousDelimiter();
         $delimiterStack->processDelimiters($stackBottom, $this->environment->getDelimiterProcessors());
+        $delimiterStack->removeBracket();
         $delimiterStack->removeAll($stackBottom);
 
         // Merge any adjacent Text nodes together
         AdjacentTextMerger::mergeChildNodes($inline);
 
         // processEmphasis will remove this and later delimiters.
         // Now, for a link, we also remove earlier link openers (no links in links)
-        if (! $isImage) {
-            $inlineContext->getDelimiterStack()->removeEarlierMatches('[');
+        if (! $opener->isImage()) {
+            $inlineContext->getDelimiterStack()->deactivateLinkOpeners();
         }
 
         return true;
@@ -168,21 +168,23 @@ private function tryParseInlineLinkAndTitle(Cursor $cursor): ?array
         return ['url' => $dest, 'title' => $title];
     }
 
-    private function tryParseReference(Cursor $cursor, ReferenceMapInterface $referenceMap, ?int $openerIndex, int $startPos): ?ReferenceInterface
+    private function tryParseReference(Cursor $cursor, ReferenceMapInterface $referenceMap, Bracket $opener, int $startPos): ?ReferenceInterface
     {
-        if ($openerIndex === null) {
-            return null;
-        }
-
         $savePos     = $cursor->saveState();
         $beforeLabel = $cursor->getPosition();
         $n           = LinkParserHelper::parseLinkLabel($cursor);
-        if ($n === 0 || $n === 2) {
-            $start  = $openerIndex;
-            $length = $startPos - $openerIndex;
-        } else {
+        if ($n > 2) {
             $start  = $beforeLabel + 1;
             $length = $n - 2;
+        } elseif (! $opener->hasNext()) {
+            // Empty or missing second label means to use the first label as the reference.
+            // The reference must not contain a bracket. If we know there's a bracket, we don't even bother checking it.
+            $start  = $opener->getIndex();
+            $length = $startPos - $start;
+        } else {
+            $cursor->restoreState($savePos);
+
+            return null;
         }
 
         $referenceLabel = $cursor->getSubstring($start, $length);
diff --git a/src/Extension/CommonMark/Parser/Inline/OpenBracketParser.php b/src/Extension/CommonMark/Parser/Inline/OpenBracketParser.php
@@ -16,7 +16,6 @@
 
 namespace League\CommonMark\Extension\CommonMark\Parser\Inline;
 
-use League\CommonMark\Delimiter\Delimiter;
 use League\CommonMark\Node\Inline\Text;
 use League\CommonMark\Parser\Inline\InlineParserInterface;
 use League\CommonMark\Parser\Inline\InlineParserMatch;
@@ -36,8 +35,7 @@ public function parse(InlineParserContext $inlineContext): bool
         $inlineContext->getContainer()->appendChild($node);
 
         // Add entry to stack for this opener
-        $delimiter = new Delimiter('[', 1, $node, true, false, $inlineContext->getCursor()->getPosition());
-        $inlineContext->getDelimiterStack()->push($delimiter);
+        $inlineContext->getDelimiterStack()->addBracket($node, $inlineContext->getCursor()->getPosition(), false);
 
         return true;
     }
diff --git a/tests/unit/Delimiter/DelimiterStackTest.php b/tests/unit/Delimiter/DelimiterStackTest.php
