DX: Narrow docblock types in Tokenizer (#6293)

narrow docblock types in tokenizer

phpstan.neon

@@ -23,15 +23,15 @@ parameters:
         -
             message: '#^Method .+ has parameter .+ with no value type specified in iterable type array\.$#'
             path: *
-            count: 379
+            count: 363
         -
             message: '#^Method .+ has parameter .+ with no value type specified in iterable type iterable\.$#'
             path: *
             count: 4
         -
             message: '#^Method .+ return type has no value type specified in iterable type array\.$#'
             path: *
-            count: 163
+            count: 153
         -
             message: '#^Method .+ return type has no value type specified in iterable type iterable\.$#'
             path: *
@@ -43,6 +43,6 @@ parameters:
         -
             message: '#^Property .+ type has no value type specified in iterable type array\.$#'
             path: *
-            count: 38
+            count: 37
     tipsOfTheDay: false
     tmpDir: dev-tools/phpstan/cache

src/Fixer/Alias/ModernizeStrposFixer.php

@@ -161,6 +161,9 @@ private function fixCall(Tokens $tokens, int $functionIndex, array $operatorIndi
         }
     }
 
+    /**
+     * @param -1|1 $direction
+     */
     private function getCompareTokens(Tokens $tokens, int $offsetIndex, int $direction): ?array
     {
         $operatorIndex = $tokens->getMeaningfulTokenSibling($offsetIndex, $direction);

src/Fixer/FunctionNotation/StaticLambdaFixer.php

@@ -115,7 +115,6 @@ private function findExpressionEnd(Tokens $tokens, int $index): int
                 break;
             }
 
-            /** @var null|array{isStart: bool, type: int} $blockType */
             $blockType = Tokens::detectBlockType($nextToken);
 
             if (null !== $blockType && $blockType['isStart']) {

src/Fixer/Import/OrderedImportsFixer.php

@@ -462,7 +462,7 @@ private function getNewOrder(array $uses, Tokens $tokens): array
                     }
 
                     $namespaceTokens = [];
-                    $nextPartIndex = $tokens->getTokenNotOfKindSibling($index, 1, [[','], [T_WHITESPACE]]);
+                    $nextPartIndex = $tokens->getTokenNotOfKindSibling($index, 1, [',', [T_WHITESPACE]]);
                     $startIndex = $nextPartIndex;
                     $index = $nextPartIndex;
 

src/Fixer/LanguageConstruct/ErrorSuppressionFixer.php

@@ -174,7 +174,7 @@ private function isDeprecationErrorCall(Tokens $tokens, int $index): bool
             return false;
         }
 
-        $endBraceIndex = $tokens->findBlockEnd(Tokens::BLOCK_TYPE_PARENTHESIS_BRACE, $tokens->getNextTokenOfKind($index, [T_STRING, '(']));
+        $endBraceIndex = $tokens->findBlockEnd(Tokens::BLOCK_TYPE_PARENTHESIS_BRACE, $tokens->getNextTokenOfKind($index, [[T_STRING], '(']));
         $prevIndex = $tokens->getPrevMeaningfulToken($endBraceIndex);
 
         if ($tokens[$prevIndex]->equals(',')) {

src/Fixer/Operator/NoSpaceAroundDoubleColonFixer.php

@@ -54,6 +54,9 @@ protected function applyFix(\SplFileInfo $file, Tokens $tokens): void
         }
     }
 
+    /**
+     * @param -1|1 $direction
+     */
     private function removeSpace(Tokens $tokens, int $index, int $direction): void
     {
         if (!$tokens[$index + $direction]->isWhitespace()) {

src/Fixer/Operator/OperatorLinebreakFixer.php

@@ -170,17 +170,16 @@ private function getExcludedIndices(Tokens $tokens): array
     {
         $colonIndices = [];
 
+        /** @var SwitchAnalysis $analysis */
         foreach (ControlCaseStructuresAnalyzer::findControlStructures($tokens, [T_SWITCH]) as $analysis) {
             foreach ($analysis->getCases() as $case) {
                 $colonIndices[] = $case->getColonIndex();
             }
 
-            if ($analysis instanceof SwitchAnalysis) {
-                $defaultAnalysis = $analysis->getDefaultAnalysis();
+            $defaultAnalysis = $analysis->getDefaultAnalysis();
 
-                if (null !== $defaultAnalysis) {
-                    $colonIndices[] = $defaultAnalysis->getColonIndex();
-                }
+            if (null !== $defaultAnalysis) {
+                $colonIndices[] = $defaultAnalysis->getColonIndex();
             }
         }
 

src/Fixer/Operator/TernaryOperatorSpacesFixer.php

@@ -130,17 +130,16 @@ private function getColonIndicesForSwitch(Tokens $tokens): array
     {
         $colonIndices = [];
 
+        /** @var SwitchAnalysis $analysis */
         foreach (ControlCaseStructuresAnalyzer::findControlStructures($tokens, [T_SWITCH]) as $analysis) {
             foreach ($analysis->getCases() as $case) {
                 $colonIndices[] = $case->getColonIndex();
             }
 
-            if ($analysis instanceof SwitchAnalysis) {
-                $defaultAnalysis = $analysis->getDefaultAnalysis();
+            $defaultAnalysis = $analysis->getDefaultAnalysis();
 
-                if (null !== $defaultAnalysis) {
-                    $colonIndices[] = $defaultAnalysis->getColonIndex();
-                }
+            if (null !== $defaultAnalysis) {
+                $colonIndices[] = $defaultAnalysis->getColonIndex();
             }
         }
 

src/Fixer/StringNotation/StringLengthToEmptyFixer.php

@@ -292,7 +292,6 @@ private function keepParentheses(Tokens $tokens, int $openParenthesisIndex, int
                 continue;
             }
 
-            /** @var null|array{isStart: bool, type: int} $blockType */
             $blockType = Tokens::detectBlockType($token);
 
             if (null !== $blockType && $blockType['isStart']) {

src/Tokenizer/Analyzer/Analysis/EnumAnalysis.php

@@ -20,12 +20,12 @@
 final class EnumAnalysis extends AbstractControlCaseStructuresAnalysis
 {
     /**
-     * @var CaseAnalysis[]
+     * @var list<CaseAnalysis>
      */
     private array $cases;
 
     /**
-     * @param CaseAnalysis[] $cases
+     * @param list<CaseAnalysis> $cases
      */
     public function __construct(int $index, int $open, int $close, array $cases)
     {
@@ -35,7 +35,7 @@ public function __construct(int $index, int $open, int $close, array $cases)
     }
 
     /**
-     * @return CaseAnalysis[]
+     * @return list<CaseAnalysis>
      */
     public function getCases(): array
     {

src/Tokenizer/Analyzer/Analysis/SwitchAnalysis.php

@@ -20,14 +20,14 @@
 final class SwitchAnalysis extends AbstractControlCaseStructuresAnalysis
 {
     /**
-     * @var CaseAnalysis[]
+     * @var list<CaseAnalysis>
      */
     private array $cases;
 
     private ?DefaultAnalysis $defaultAnalysis;
 
     /**
-     * @param CaseAnalysis[] $cases
+     * @param list<CaseAnalysis> $cases
      */
     public function __construct(int $index, int $open, int $close, array $cases, ?DefaultAnalysis $defaultAnalysis)
     {
@@ -38,7 +38,7 @@ public function __construct(int $index, int $open, int $close, array $cases, ?De
     }
 
     /**
-     * @return CaseAnalysis[]
+     * @return list<CaseAnalysis>
      */
     public function getCases(): array
     {

src/Tokenizer/Analyzer/Analysis/TypeAnalysis.php

@@ -28,7 +28,7 @@ final class TypeAnalysis implements StartEndTokenAwareAnalysis
      * @see https://php.net/manual/en/reserved.other-reserved-words.php
      * @see https://php.net/manual/en/language.pseudo-types.php
      *
-     * @var string[]
+     * @var list<string>
      */
     private static array $reservedTypes = [
         'array',

src/Tokenizer/Analyzer/BlocksAnalyzer.php

@@ -47,6 +47,9 @@ public function isBlock(Tokens $tokens, ?int $openIndex, ?int $closeIndex): bool
         return $closeIndex === $tokens->findBlockEnd($blockType, $openIndex);
     }
 
+    /**
+     * @return Tokens::BLOCK_TYPE_*
+     */
     private function getBlockType(Token $token): ?int
     {
         foreach (Tokens::getBlockEdgeDefinitions() as $blockType => $definition) {

src/Tokenizer/Analyzer/CommentsAnalyzer.php

@@ -113,8 +113,10 @@ public function isBeforeStructuralElement(Tokens $tokens, int $index): bool
      * Return array of indices that are part of a comment started at given index.
      *
      * @param int $index T_COMMENT index
+     *
+     * @return list<int>
      */
-    public function getCommentBlockIndices(Tokens $tokens, int $index): ?array
+    public function getCommentBlockIndices(Tokens $tokens, int $index): array
     {
         if (!$tokens[$index]->isGivenKind(T_COMMENT)) {
             throw new \InvalidArgumentException('Given index must point to a comment.');

src/Tokenizer/Analyzer/ControlCaseStructuresAnalyzer.php

@@ -25,7 +25,9 @@
 final class ControlCaseStructuresAnalyzer
 {
     /**
-     * @param int[] $types Token types of interest of which analyzes must be returned
+     * @param list<int> $types Token types of interest of which analyzes must be returned
+     *
+     * @return \Generator<int, AbstractControlCaseStructuresAnalysis>
      */
     public static function findControlStructures(Tokens $tokens, array $types): \Generator
     {
@@ -267,6 +269,9 @@ private static function findDefaultOpen(Tokens $tokens, int $kind, int $index):
         throw new \InvalidArgumentException(sprintf('Unexpected default for type "%d".', $kind));
     }
 
+    /**
+     * @return list<int>
+     */
     private static function getTypesWithCaseOrDefault(): array
     {
         $supportedTypes = [T_SWITCH];

src/Tokenizer/Analyzer/FunctionsAnalyzer.php

@@ -134,7 +134,7 @@ public function isGlobalFunctionCall(Tokens $tokens, int $index): bool
     }
 
     /**
-     * @return ArgumentAnalysis[]
+     * @return array<string, ArgumentAnalysis>
      */
     public function getFunctionArguments(Tokens $tokens, int $functionIndex): array
     {

src/Tokenizer/Analyzer/NamespaceUsesAnalyzer.php

@@ -26,7 +26,7 @@
 final class NamespaceUsesAnalyzer
 {
     /**
-     * @return NamespaceUseAnalysis[]
+     * @return list<NamespaceUseAnalysis>
      */
     public function getDeclarationsFromTokens(Tokens $tokens): array
     {
@@ -37,7 +37,7 @@ public function getDeclarationsFromTokens(Tokens $tokens): array
     }
 
     /**
-     * @return NamespaceUseAnalysis[]
+     * @return list<NamespaceUseAnalysis>
      */
     public function getDeclarationsInNamespace(Tokens $tokens, NamespaceAnalysis $namespace): array
     {
@@ -53,7 +53,7 @@ public function getDeclarationsInNamespace(Tokens $tokens, NamespaceAnalysis $na
     }
 
     /**
-     * @return NamespaceUseAnalysis[]
+     * @return list<NamespaceUseAnalysis>
      */
     private function getDeclarations(Tokens $tokens, array $useIndices): array
     {

src/Tokenizer/Analyzer/NamespacesAnalyzer.php

@@ -23,7 +23,7 @@
 final class NamespacesAnalyzer
 {
     /**
-     * @return NamespaceAnalysis[]
+     * @return list<NamespaceAnalysis>
      */
     public function getDeclarations(Tokens $tokens): array
     {

src/Tokenizer/Analyzer/RangeAnalyzer.php

@@ -29,6 +29,9 @@ private function __construct()
 
     /**
      * Meaningful compare of tokens within ranges.
+     *
+     * @param array{start: int, end: int} $range1
+     * @param array{start: int, end: int} $range2
      */
     public static function rangeEqualsRange(Tokens $tokens, array $range1, array $range2): bool
     {

src/Tokenizer/CT.php

@@ -87,6 +87,9 @@ public static function has(int $value): bool
         return isset($tokens[$value]);
     }
 
+    /**
+     * @return array<self::T_*, string>
+     */
     private static function getMapById(): array
     {
         static $constants;