chore: phpdoc - rely on strict list/tuple/assoc instead of array (#7978)

.github/workflows/sca.yml

@@ -77,12 +77,6 @@ jobs:
       - name: Check - phpstan
         run: ./dev-tools/vendor/bin/phpstan analyse --ansi
 
-      - name: Check - well defined array keys
-        run: |
-          echo "Array types must explicitly declare key-type, i.e. as \`array<type-of-key, type-of-value>\`, \`list<type-of-value>\` or \`array{...}\` - instead of \`array<type-of-value>\` or \`type-of-value[]\`."
-          echo "Hint: don't apply those rules blindly, provide array key type explicitly\!"
-          ./php-cs-fixer check --rules=phpdoc_list_type,phpdoc_array_type tests/ --path-mode=intersection # @TODO run for whole project, when no more violations
-
       - name: Check - composer-unused
         run: ./dev-tools/vendor/bin/composer-unused --no-progress --excludePackage=composer/xdebug-handler
 
@@ -115,6 +109,13 @@ jobs:
             echo 'EOF' >> $GITHUB_ENV
           fi
 
+      - name: Check - well defined array keys
+        if: ${{ env.CHANGED_PHP_FILES }}
+        run: |
+          echo "Array types must explicitly declare key-type, i.e. as \`array<type-of-key, type-of-value>\`, \`list<type-of-value>\` or \`array{...}\` - instead of \`array<type-of-value>\` or \`type-of-value[]\`."
+          echo "Hint: don't apply those rules blindly, provide array key type explicitly\!"
+          ./php-cs-fixer check --config=dev-tools/.php-cs-fixer.well-defined-arrays.php --path-mode=intersection $CHANGED_PHP_FILES
+
       - name: Check - Mess Detector (phpmd)
         if: ${{ env.CHANGED_PHP_FILES }}
         run: |

dev-tools/.php-cs-fixer.well-defined-arrays.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+$config = require __DIR__.'/../.php-cs-fixer.dist.php';
+
+$config->setRules([
+    'phpdoc_array_type' => true,
+    'phpdoc_list_type' => true,
+]);
+
+return $config;

dev-tools/phpstan/baseline.php

@@ -121,11 +121,6 @@
 	'count' => 1,
 	'path' => __DIR__ . '/../../src/Console/Report/ListSetsReport/ReporterFactory.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Method PhpCsFixer\\\\Console\\\\WarningsDetector\\:\\:getWarnings\\(\\) should return list\\<string\\> but returns non\\-empty\\-array\\<string\\>\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/Console/WarningsDetector.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Only numeric types are allowed in \\+, int\\|false given on the left side\\.$#',
 	'count' => 1,
@@ -356,16 +351,6 @@
 	'count' => 1,
 	'path' => __DIR__ . '/../../src/Fixer/ClassNotation/OrderedTraitsFixer.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Parameter \\#1 \\$types of method PhpCsFixer\\\\Fixer\\\\ClassNotation\\\\OrderedTypesFixer\\:\\:runTypesThroughSortingAlgorithm\\(\\) expects list\\<array\\<string\\>\\|string\\>, array\\<list\\<array\\<string\\>\\|string\\>\\|string\\> given\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/Fixer/ClassNotation/OrderedTypesFixer.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Parameter \\#1 \\$types of method PhpCsFixer\\\\Fixer\\\\ClassNotation\\\\OrderedTypesFixer\\:\\:runTypesThroughSortingAlgorithm\\(\\) expects list\\<array\\<string\\>\\|string\\>, array\\<string\\> given\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/Fixer/ClassNotation/OrderedTypesFixer.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Only booleans are allowed in &&, int\\|false\\|null given on the left side\\.$#',
 	'count' => 1,
@@ -411,21 +396,11 @@
 	'count' => 1,
 	'path' => __DIR__ . '/../../src/Fixer/FunctionNotation/CombineNestedDirnameFixer.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Parameter \\#1 \\$flags of method PhpCsFixer\\\\Fixer\\\\FunctionNotation\\\\FopenFlagOrderFixer\\:\\:sortFlags\\(\\) expects list\\<string\\>, array\\<string\\> given\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/Fixer/FunctionNotation/FopenFlagOrderFixer.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Method PhpCsFixer\\\\Fixer\\\\FunctionNotation\\\\ImplodeCallFixer\\:\\:getArgumentIndices\\(\\) should return array\\<int, int\\> but returns array\\<int\\|string, int\\|null\\>\\.$#',
 	'count' => 1,
 	'path' => __DIR__ . '/../../src/Fixer/FunctionNotation/ImplodeCallFixer.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Method PhpCsFixer\\\\Fixer\\\\FunctionNotation\\\\NativeFunctionInvocationFixer\\:\\:normalizeFunctionNames\\(\\) should return array\\<string, true\\> but returns array\\<string\\|true\\>\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/Fixer/FunctionNotation/NativeFunctionInvocationFixer.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Parameter \\#1 \\$others of method PhpCsFixer\\\\Tokenizer\\\\Token\\:\\:equalsAny\\(\\) expects list\\<array\\{0\\: int, 1\\?\\: string\\}\\|PhpCsFixer\\\\Tokenizer\\\\Token\\|string\\>, array\\<int, array\\<int, int\\|string\\>\\> given\\.$#',
 	'count' => 1,
@@ -527,27 +502,7 @@
 	'path' => __DIR__ . '/../../src/Fixer/LanguageConstruct/CombineConsecutiveIssetsFixer.php',
 ];
 $ignoreErrors[] = [
-	'message' => '#^Parameter \\#2 \\$indices of method PhpCsFixer\\\\Fixer\\\\LanguageConstruct\\\\CombineConsecutiveIssetsFixer\\:\\:clearTokens\\(\\) expects list\\<int\\>, non\\-empty\\-array\\<int\\|null\\> given\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/Fixer/LanguageConstruct/CombineConsecutiveIssetsFixer.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Parameter \\#2 \\$indices of method PhpCsFixer\\\\Fixer\\\\LanguageConstruct\\\\CombineConsecutiveIssetsFixer\\:\\:getTokenClones\\(\\) expects list\\<int\\>, array\\<int\\> given\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/Fixer/LanguageConstruct/CombineConsecutiveIssetsFixer.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method PhpCsFixer\\\\Fixer\\\\LanguageConstruct\\\\FunctionToConstantFixer\\:\\:getReplacementTokenClones\\(\\) should return array\\{int, int, list\\<PhpCsFixer\\\\Tokenizer\\\\Token\\>\\} but returns array\\{int, int, array\\<PhpCsFixer\\\\Tokenizer\\\\Token\\>\\}\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/Fixer/LanguageConstruct/FunctionToConstantFixer.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Parameter \\#2 \\$items of method PhpCsFixer\\\\Tokenizer\\\\Tokens\\:\\:insertAt\\(\\) expects list\\<PhpCsFixer\\\\Tokenizer\\\\Token\\>\\|PhpCsFixer\\\\Tokenizer\\\\Token\\|PhpCsFixer\\\\Tokenizer\\\\Tokens, array\\<PhpCsFixer\\\\Tokenizer\\\\Token\\> given\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/Fixer/LanguageConstruct/FunctionToConstantFixer.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Property PhpCsFixer\\\\Fixer\\\\LanguageConstruct\\\\FunctionToConstantFixer\\:\\:\\$functionsFixMap \\(array\\<string, array\\<PhpCsFixer\\\\Tokenizer\\\\Token\\>\\>\\) does not accept array\\<int\\|string, array\\<PhpCsFixer\\\\Tokenizer\\\\Token\\>\\>\\.$#',
+	'message' => '#^Property PhpCsFixer\\\\Fixer\\\\LanguageConstruct\\\\FunctionToConstantFixer\\:\\:\\$functionsFixMap \\(array\\<string, list\\<PhpCsFixer\\\\Tokenizer\\\\Token\\>\\>\\) does not accept non\\-empty\\-array\\<int\\|string, list\\<PhpCsFixer\\\\Tokenizer\\\\Token\\>\\>\\.$#',
 	'count' => 1,
 	'path' => __DIR__ . '/../../src/Fixer/LanguageConstruct/FunctionToConstantFixer.php',
 ];
@@ -676,11 +631,6 @@
 	'count' => 1,
 	'path' => __DIR__ . '/../../src/Fixer/PhpUnit/PhpUnitNoExpectationAnnotationFixer.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Method PhpCsFixer\\\\Fixer\\\\PhpUnit\\\\PhpUnitTestAnnotationFixer\\:\\:addTestAnnotation\\(\\) should return array\\<PhpCsFixer\\\\DocBlock\\\\Line\\> but returns array\\<PhpCsFixer\\\\DocBlock\\\\Line\\|string\\>\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/Fixer/PhpUnit/PhpUnitTestAnnotationFixer.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Method PhpCsFixer\\\\Fixer\\\\PhpUnit\\\\PhpUnitTestAnnotationFixer\\:\\:updateLines\\(\\) should return list\\<PhpCsFixer\\\\DocBlock\\\\Line\\> but returns array\\<int\\<0, max\\>, PhpCsFixer\\\\DocBlock\\\\Line\\>\\.$#',
 	'count' => 1,
@@ -726,11 +676,6 @@
 	'count' => 2,
 	'path' => __DIR__ . '/../../src/Fixer/Phpdoc/PhpdocAlignFixer.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Parameter \\#1 \\$types of method PhpCsFixer\\\\DocBlock\\\\DocBlock\\:\\:getAnnotationsOfType\\(\\) expects list\\<string\\>\\|string, array\\<string\\> given\\.$#',
-	'count' => 2,
-	'path' => __DIR__ . '/../../src/Fixer/Phpdoc/PhpdocOrderFixer.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Cannot call method getEnd\\(\\) on PhpCsFixer\\\\DocBlock\\\\Annotation\\|false\\.$#',
 	'count' => 1,
@@ -746,18 +691,13 @@
 	'count' => 1,
 	'path' => __DIR__ . '/../../src/Fixer/Phpdoc/PhpdocParamOrderFixer.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Parameter \\#1 \\$names of static method PhpCsFixer\\\\Utils\\:\\:naturalLanguageJoin\\(\\) expects list\\<string\\>, array\\<string\\> given\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/../../src/Fixer/Phpdoc/PhpdocReturnSelfReferenceFixer.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Parameter \\#1 \\$callback of function array_map expects \\(callable\\(int\\|string\\)\\: mixed\\)\\|null, Closure\\(string\\)\\: string given\\.$#',
 	'count' => 1,
 	'path' => __DIR__ . '/../../src/Fixer/Phpdoc/PhpdocTagTypeFixer.php',
 ];
 $ignoreErrors[] = [
-	'message' => '#^Parameter \\#1 \\$parts of method PhpCsFixer\\\\Fixer\\\\Phpdoc\\\\PhpdocTagTypeFixer\\:\\:tagIsSurroundedByText\\(\\) expects list\\<string\\>, array\\<string\\> given\\.$#',
+	'message' => '#^Parameter \\#1 \\$parts of method PhpCsFixer\\\\Fixer\\\\Phpdoc\\\\PhpdocTagTypeFixer\\:\\:tagIsSurroundedByText\\(\\) expects list\\<string\\>, array\\<int\\<0, max\\>, string\\> given\\.$#',
 	'count' => 1,
 	'path' => __DIR__ . '/../../src/Fixer/Phpdoc/PhpdocTagTypeFixer.php',
 ];

src/Console/ConfigurationResolver.php

@@ -355,7 +355,7 @@ public function getLinter(): LinterInterface
     /**
      * Returns path.
      *
-     * @return string[]
+     * @return list<string>
      */
     public function getPath(): array
     {

src/Console/Output/ErrorOutput.php

@@ -40,7 +40,7 @@ public function __construct(OutputInterface $output)
     }
 
     /**
-     * @param Error[] $errors
+     * @param list<Error> $errors
      */
     public function listErrors(string $process, array $errors): void
     {

src/Console/SelfUpdate/NewVersionChecker.php

@@ -28,7 +28,7 @@ final class NewVersionChecker implements NewVersionCheckerInterface
     private VersionParser $versionParser;
 
     /**
-     * @var null|string[]
+     * @var null|list<string>
      */
     private $availableVersions;
 
@@ -94,6 +94,9 @@ private function retrieveAvailableVersions(): void
             }
         }
 
-        $this->availableVersions = Semver::rsort($this->availableVersions);
+        $versions = Semver::rsort($this->availableVersions);
+        \assert(array_is_list($versions)); // Semver::rsort provides soft `array` type, let's validate and ensure proper type for SCA
+
+        $this->availableVersions = $versions;
     }
 }

src/Console/WarningsDetector.php

@@ -27,7 +27,7 @@ final class WarningsDetector
     private ToolInfoInterface $toolInfo;
 
     /**
-     * @var string[]
+     * @var list<string>
      */
     private array $warnings = [];
 
@@ -68,9 +68,9 @@ public function getWarnings(): array
             return [];
         }
 
-        return array_unique(array_merge(
+        return array_values(array_unique(array_merge(
             $this->warnings,
             ['If you need help while solving warnings, ask at https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/discussions/, we will help you!']
-        ));
+        )));
     }
 }

src/DocBlock/TagComparator.php

@@ -28,6 +28,8 @@ final class TagComparator
     /**
      * Groups of tags that should be allowed to immediately follow each other.
      *
+     * @var list<list<string>>
+     *
      * @internal
      */
     public const DEFAULT_GROUPS = [
@@ -40,7 +42,7 @@ final class TagComparator
     /**
      * Should the given tags be kept together, or kept apart?
      *
-     * @param string[][] $groups
+     * @param list<list<string>> $groups
      */
     public static function shouldBeTogether(Tag $first, Tag $second, array $groups = self::DEFAULT_GROUPS): bool
     {

src/DocBlock/TypeExpression.php

@@ -220,12 +220,12 @@ final class TypeExpression
     private ?NamespaceAnalysis $namespace;
 
     /**
-     * @var NamespaceUseAnalysis[]
+     * @var list<NamespaceUseAnalysis>
      */
     private array $namespaceUses;
 
     /**
-     * @param NamespaceUseAnalysis[] $namespaceUses
+     * @param list<NamespaceUseAnalysis> $namespaceUses
      */
     public function __construct(string $value, ?NamespaceAnalysis $namespace, array $namespaceUses)
     {

src/Doctrine/Annotation/Token.php

@@ -66,7 +66,7 @@ public function getPosition(): int
     /**
      * Returns whether the token type is one of the given types.
      *
-     * @param int|int[] $types
+     * @param int|list<int> $types
      */
     public function isType($types): bool
     {

src/Doctrine/Annotation/Tokens.php

@@ -27,7 +27,7 @@
 final class Tokens extends \SplFixedArray
 {
     /**
-     * @param string[] $ignoredTags
+     * @param list<string> $ignoredTags
      *
      * @throws \InvalidArgumentException
      */

src/Documentation/FixerDocumentGenerator.php

@@ -296,7 +296,7 @@ public static function getSetsOfRule(string $ruleName): array
     }
 
     /**
-     * @param FixerInterface[] $fixers
+     * @param list<FixerInterface> $fixers
      */
     public function generateFixersDocumentationIndex(array $fixers): string
     {

src/Documentation/RuleSetDocumentationGenerator.php

@@ -33,7 +33,7 @@ public function __construct(DocumentationLocator $locator)
     }
 
     /**
-     * @param FixerInterface[] $fixers
+     * @param list<FixerInterface> $fixers
      */
     public function generateRuleSetsDocumentation(RuleSetDescriptionInterface $definition, array $fixers): string
     {

src/Fixer/Basic/NoTrailingCommaInSinglelineFixer.php

@@ -95,7 +95,7 @@ protected function applyFix(\SplFileInfo $file, Tokens $tokens): void
 
     private function shouldBeCleared(Tokens $tokens, int $openIndex): bool
     {
-        /** @var string[] $elements */
+        /** @var list<string> $elements */
         $elements = $this->configuration['elements'];
 
         if ($tokens[$openIndex]->isGivenKind(CT::T_ARRAY_SQUARE_BRACE_OPEN)) {

src/Fixer/ClassNotation/OrderedTypesFixer.php

@@ -304,7 +304,7 @@ private function isTypeSortable(TypeAnalysis $type): bool
     }
 
     /**
-     * @return array{0: list<string|string[]>, 1: string}
+     * @return array{0: list<list<string>|string>, 1: string}
      */
     private function collectDisjunctiveNormalFormTypes(string $type): array
     {
@@ -320,7 +320,7 @@ private function collectDisjunctiveNormalFormTypes(string $type): array
     }
 
     /**
-     * @return array{0: string[], 1: string}
+     * @return array{0: list<string>, 1: string}
      */
     private function collectUnionOrIntersectionTypes(string $type): array
     {
@@ -336,9 +336,9 @@ private function collectUnionOrIntersectionTypes(string $type): array
     }
 
     /**
-     * @param list<string|string[]> $types
+     * @param list<list<string>|string> $types
      *
-     * @return list<string|string[]>
+     * @return ($types is list<string> ? list<string> : list<list<string>>)
      */
     private function runTypesThroughSortingAlgorithm(array $types): array
     {
@@ -379,9 +379,9 @@ private function runTypesThroughSortingAlgorithm(array $types): array
     }
 
     /**
-     * @param array<int, string|string[]> $types
+     * @param list<list<string>|string> $types
      *
-     * @return array<int, Token>
+     * @return list<Token>
      */
     private function createTypeDeclarationTokens(array $types, string $glue, bool $isDisjunctive = false): array
     {

src/Fixer/ClassNotation/SingleTraitInsertPerStatementFixer.php

@@ -70,7 +70,7 @@ protected function applyFix(\SplFileInfo $file, Tokens $tokens): void
     }
 
     /**
-     * @param int[] $candidates ',' indices to fix
+     * @param list<int> $candidates ',' indices to fix
      */
     private function fixTraitUse(Tokens $tokens, int $useTraitIndex, array $candidates): void
     {

src/Fixer/ControlStructure/EmptyLoopConditionFixer.php

@@ -131,7 +131,7 @@ private static function clearNotCommentsInRange(Tokens $tokens, int $indexStart,
     }
 
     /**
-     * @param Token[] $replacement
+     * @param list<Token> $replacement
      */
     private static function cloneAndInsert(Tokens $tokens, int $index, array $replacement): void
     {

src/Fixer/ControlStructure/NoUnneededControlParenthesesFixer.php

@@ -36,7 +36,7 @@
 final class NoUnneededControlParenthesesFixer extends AbstractFixer implements ConfigurableFixerInterface
 {
     /**
-     * @var int[]
+     * @var list<int>
      */
     private const BLOCK_TYPES = [
         Tokens::BLOCK_TYPE_ARRAY_INDEX_CURLY_BRACE,