Raise PHPStan to the max level

phpstan.neon

@@ -1,5 +1,5 @@
 parameters:
-    level: 5
+    level: max
     paths:
         - src
         - tests

spec/Token/TokenSpec.php

@@ -6,6 +6,7 @@
 
 use chrisjenkinson\StructuredDocumentParser\Token\NonexistentKeyException;
 use chrisjenkinson\StructuredDocumentParser\Token\TokenPosition;
+use InvalidArgumentException;
 use PhpSpec\ObjectBehavior;
 
 class TokenSpec extends ObjectBehavior
@@ -49,4 +50,23 @@ public function it_casts_to_a_string(): void
     {
         $this->__toString()->shouldReturn('Something (value)');
     }
+
+    public function it_has_the_matched_text(): void
+    {
+        $this->getText()->shouldReturn('value');
+    }
+
+    public function it_requires_the_matched_text_to_be_a_string(): void
+    {
+        $this->beConstructedWith('Something', ['all' => 13], new TokenPosition(3, 7));
+
+        $this->shouldThrow(InvalidArgumentException::class)->duringInstantiation();
+    }
+
+    public function it_requires_the_matched_text(): void
+    {
+        $this->beConstructedWith('Something', ['heading' => 'value'], new TokenPosition(3, 7));
+
+        $this->shouldThrow(InvalidArgumentException::class)->duringInstantiation();
+    }
 }

src/Finder/RegexFinder.php

@@ -7,7 +7,7 @@
 class RegexFinder
 {
     /**
-     * @var mixed[]
+     * @var array<int|string, string>
      */
     private array $matches = [];
 
@@ -32,6 +32,11 @@ public function find(string $text): bool
         return false;
     }
 
+    /**
+     * @param string[] $keys
+     *
+     * @return array<int|string, string>
+     */
     public function getMatches(array $keys): array
     {
         return array_intersect_key($this->matches, array_flip($keys));

src/Lexer/Lexer.php

@@ -93,7 +93,7 @@ private function tokeniseFromInitialState(string $text): TokenStream
 
             $tokens->add($token);
 
-            $length = mb_strlen($token->getValue('all'));
+            $length = mb_strlen($token->getText());
 
             if (0 < $length) {
                 $cursor->advance($length);

src/Matcher/MatchedText.php

@@ -25,6 +25,9 @@ public function get(string $key)
         return null;
     }
 
+    /**
+     * @return mixed[]
+     */
     public function getAll(): array
     {
         return $this->matches;

src/Node/AbstractNode.php

@@ -25,7 +25,7 @@ public function __toString(): string
     }
 
     /**
-     * @return array{attributes: array, nodes: NodeInterface[]}
+     * @return array{attributes: array<string, mixed>, nodes: NodeInterface[]}
      */
     public function jsonSerialize(): array
     {

src/NodeTraverser/NodeTraverser.php

@@ -65,6 +65,11 @@ public function traverseNode(NodeInterface $node): NodeInterface|NodeVisitorActi
         return $node;
     }
 
+    /**
+     * @param mixed[] $children
+     *
+     * @return mixed[]
+     */
     public function traverseChildren(array $children): array
     {
         $isList = array_is_list($children);
@@ -131,6 +136,9 @@ private function runTraverseNodeOnSubNodes(NodeInterface $node, array $children)
         }, $children);
     }
 
+    /**
+     * @param array<string, mixed> $attributes
+     */
     private function runTraverseChildrenOnAttributes(NodeInterface $node, array $attributes): void
     {
         array_walk($attributes, function ($attribute, $key) use (&$node): void {

src/State/AmbiguousTokenFoundException.php

@@ -24,11 +24,11 @@ public function __construct(
         int $code = 0,
         ?Throwable $previous = null
     ) {
-        $matches = array_map(
-            static fn (string $matcherName, MatchedText $matchedText): string => sprintf('%s (%s)', $matcherName, TextExcerpt::of($matchedText->getAll()['all'])),
-            $calledMatchers,
-            $matchedTokens
-        );
+        $matches = array_map(static function (string $matcherName, MatchedText $matchedText): string {
+            $all = $matchedText->getAll()['all'] ?? null;
+
+            return sprintf('%s (%s)', $matcherName, TextExcerpt::of(is_string($all) ? $all : ''));
+        }, $calledMatchers, $matchedTokens);
 
         $message = sprintf(
             'Ambiguous token found with state %s at line %d, column %d: matchers %s',
@@ -41,11 +41,17 @@ public function __construct(
         parent::__construct($message, $code, $previous);
     }
 
+    /**
+     * @return string[]
+     */
     public function getCalledMatchers(): array
     {
         return $this->calledMatchers;
     }
 
+    /**
+     * @return MatchedText[]
+     */
     public function getMatchedTokens(): array
     {
         return $this->matchedTokens;

src/Token/Token.php

@@ -4,8 +4,12 @@
 
 namespace chrisjenkinson\StructuredDocumentParser\Token;
 
+use InvalidArgumentException;
+
 class Token implements TokenInterface
 {
+    private readonly string $text;
+
     /**
      * @param mixed[] $value
      */
@@ -14,11 +18,21 @@ public function __construct(
         private readonly array $value,
         private readonly TokenPosition $position
     ) {
+        if (!isset($value['all']) || !is_string($value['all'])) {
+            throw new InvalidArgumentException(sprintf('Token %s needs a string "all" value', $type));
+        }
+
+        $this->text = $value['all'];
     }
 
     public function __toString(): string
     {
-        return sprintf('%s (%s)', $this->getType(), trim($this->getValue('all')));
+        return sprintf('%s (%s)', $this->getType(), trim($this->getText()));
+    }
+
+    public function getText(): string
+    {
+        return $this->text;
     }
 
     /**

src/Token/TokenInterface.php

@@ -17,6 +17,11 @@ public function getValue(string $key): mixed;
 
     public function getType(): string;
 
+    /**
+     * The text the token consumed from the input.
+     */
+    public function getText(): string;
+
     public function getPosition(): TokenPosition;
 
     public function hasKey(string $key): bool;

src/Token/TokenStream.php

@@ -55,12 +55,12 @@ public function getCurrentToken(): ?TokenInterface
      */
     public function expectTokenType(string $expectedType): bool
     {
-        if (0 === count($this)) {
+        $currentToken = $this->getCurrentToken();
+
+        if (null === $currentToken) {
             throw new RuntimeException(sprintf('No more tokens; expected %s', $expectedType));
         }
 
-        $currentToken = $this->getCurrentToken();
-
         if ($expectedType !== $currentToken->getType()) {
             throw new RuntimeException(
                 sprintf('Token type is %s; expected %s', $currentToken->getType(), $expectedType)
@@ -77,12 +77,12 @@ public function expectTokenType(string $expectedType): bool
      */
     public function expectTokenTypes(array $expectedTypes): bool
     {
-        if (0 === count($this)) {
+        $currentToken = $this->getCurrentToken();
+
+        if (null === $currentToken) {
             throw new RuntimeException(sprintf('No more tokens; expected any of %s', implode(', ', $expectedTypes)));
         }
 
-        $currentToken = $this->getCurrentToken();
-
         $expected = array_filter($expectedTypes, static fn ($expectedType) => $expectedType === $currentToken->getType());
 
         if (count($expected) >= 1) {

src/Visitor/VisitableInterface.php

@@ -12,7 +12,9 @@
  *
  *     public function accept(VisitorInterface $visitor): mixed
  *     {
- *         assert($visitor instanceof MarkdownVisitor);
+ *         if (!$visitor instanceof MarkdownVisitor) {
+ *             throw new InvalidArgumentException('Heading can only be visited by a MarkdownVisitor');
+ *         }
  *
  *         return $visitor->visitHeading($this);
  *     }

tests/NodeTraverser/NodeTraverserTest.php

@@ -29,6 +29,8 @@ public function testItReplacesANode(): void
 
         $node = $traverser->traverse($node);
 
+        Assert::assertNotNull($node);
+
         Assert::assertFalse($node->hasNode('ChildNode'));
         Assert::assertInstanceOf(NodeFromVisitor::class, $node->getNode('NodeFromVisitor'));
     }
@@ -52,6 +54,8 @@ public function testItCanChangeGrandchildrenNodes(): void
 
         $node = $traverser->traverse($node);
 
+        Assert::assertNotNull($node);
+
         Assert::assertEquals('replacement', $node->getNode('ChildNode')->getNode('GrandchildNode')->getAttribute('testAttribute'));
     }
 
@@ -66,6 +70,8 @@ public function testItRemovesAChildNode(): void
 
         $node = $traverser->traverse($node);
 
+        Assert::assertNotNull($node);
+
         Assert::assertFalse($node->hasNode('ChildNode'));
     }
 
@@ -80,6 +86,8 @@ public function testItRemovesAChildNodeWhenAVisitorReturnsTheRemoveNodeAction():
 
         $node = $traverser->traverse($node);
 
+        Assert::assertNotNull($node);
+
         Assert::assertFalse($node->hasNode('ChildNode'));
     }
 
@@ -109,6 +117,8 @@ public function testItPreservesKeysOfArrayAttributesWithoutNodes(): void
 
         $node = $traverser->traverse($node);
 
+        Assert::assertNotNull($node);
+
         Assert::assertSame([5 => 'five', 9 => 'nine'], $node->getAttribute('values'));
     }
 
@@ -124,6 +134,8 @@ public function testItPreservesKeysWhenRemovingANodeFromAKeyedArrayAttribute():
 
         $node = $traverser->traverse($node);
 
+        Assert::assertNotNull($node);
+
         Assert::assertSame(['second' => $keep], $node->getAttribute('children'));
     }
 
@@ -139,6 +151,8 @@ public function testItReindexesAListAttributeWhenRemovingANode(): void
 
         $node = $traverser->traverse($node);
 
+        Assert::assertNotNull($node);
+
         Assert::assertSame([$keep], $node->getAttribute('children'));
     }
 
@@ -154,6 +168,8 @@ public function testItVisitsNodesInNestedArrayAttributes(): void
 
         $node = $traverser->traverse($node);
 
+        Assert::assertNotNull($node);
+
         Assert::assertSame(['group' => [$keep]], $node->getAttribute('children'));
     }
 }