Add PhpdocTypeListFixer (#938)

Author: kubawerlos

.dev-tools/src/Priority/PriorityCollection.php

@@ -15,6 +15,7 @@
 use PhpCsFixer\FixerFactory;
 use PhpCsFixerCustomFixers\Fixer\CommentSurroundedBySpacesFixer;
 use PhpCsFixerCustomFixers\Fixer\NoCommentedOutCodeFixer;
+use PhpCsFixerCustomFixers\Fixer\PhpdocTypeListFixer;
 use PhpCsFixerCustomFixers\Fixers;
 use Tests\PriorityTest;
 
@@ -89,6 +90,7 @@ private function getFirstPriorityFixerWithoutPriority(): ?PriorityFixer
         static $firstFixers = [
             CommentSurroundedBySpacesFixer::class,
             NoCommentedOutCodeFixer::class,
+            PhpdocTypeListFixer::class,
         ];
 
         $priorityFixersWithoutPriorities = \array_filter(

CHANGELOG.md

@@ -1,5 +1,8 @@
 # CHANGELOG for PHP CS Fixer: custom fixers
 
+## v3.18.0
+- Add PhpdocTypeListFixer
+
 ## v3.17.0
 - PhpdocNoIncorrectVarAnnotationFixer - support promoted properties
 

README.md

@@ -5,7 +5,7 @@
 [![Latest stable version](https://img.shields.io/packagist/v/kubawerlos/php-cs-fixer-custom-fixers.svg?label=current%20version)](https://packagist.org/packages/kubawerlos/php-cs-fixer-custom-fixers)
 [![PHP version](https://img.shields.io/packagist/php-v/kubawerlos/php-cs-fixer-custom-fixers.svg)](https://php.net)
 [![License](https://img.shields.io/github/license/kubawerlos/php-cs-fixer-custom-fixers.svg)](LICENSE)
-![Tests](https://img.shields.io/badge/tests-3511-brightgreen.svg)
+![Tests](https://img.shields.io/badge/tests-3551-brightgreen.svg)
 [![Downloads](https://img.shields.io/packagist/dt/kubawerlos/php-cs-fixer-custom-fixers.svg)](https://packagist.org/packages/kubawerlos/php-cs-fixer-custom-fixers)
 
 [![CI Status](https://github.com/kubawerlos/php-cs-fixer-custom-fixers/workflows/CI/badge.svg?branch=main)](https://github.com/kubawerlos/php-cs-fixer-custom-fixers/actions)
@@ -545,6 +545,17 @@ The `@var` annotation must be on a single line if it is the only content.
  }
 ```
 
+#### PhpdocTypeListFixer
+PHPDoc type `list` must be used instead of `array` without a key type.
+```diff
+ <?php
+ /**
+- * @param array<string>
++ * @param list<string>
+  */
+ function foo($x) {}
+```
+
 #### PhpdocTypesCommaSpacesFixer
 PHPDoc types commas must not be preceded by a whitespace, and must be succeeded by a single whitespace.
 ```diff

src/Fixer/PhpUnitAssertArgumentsOrderFixer.php

@@ -78,7 +78,7 @@ public function fix(\SplFileInfo $file, Tokens $tokens): void
     {
         $phpUnitTestCaseIndicator = new PhpUnitTestCaseIndicator();
 
-        /** @var array<int> $indices */
+        /** @var list<int> $indices */
         foreach ($phpUnitTestCaseIndicator->findPhpUnitClasses($tokens) as $indices) {
             $this->fixArgumentsOrder($tokens, $indices[0], $indices[1]);
         }

src/Fixer/PhpdocArrayStyleFixer.php

@@ -37,11 +37,11 @@ function foo() { return [1, 2]; }
     }
 
     /**
-     * Must run before PhpdocAlignFixer, PhpdocTypesOrderFixer.
+     * Must run before PhpdocAlignFixer, PhpdocTypeListFixer, PhpdocTypesOrderFixer.
      */
     public function getPriority(): int
     {
-        return 1;
+        return 2;
     }
 
     protected function fixType(string $type): string

src/Fixer/PhpdocTypeListFixer.php

@@ -0,0 +1,48 @@
+<?php declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer: custom fixers.
+ *
+ * (c) 2018 Kuba Werłos
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace PhpCsFixerCustomFixers\Fixer;
+
+use PhpCsFixer\FixerDefinition\CodeSample;
+use PhpCsFixer\FixerDefinition\FixerDefinition;
+use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
+use PhpCsFixer\Preg;
+
+final class PhpdocTypeListFixer extends AbstractTypesFixer
+{
+    public function getDefinition(): FixerDefinitionInterface
+    {
+        return new FixerDefinition(
+            'PHPDoc type `list` must be used instead of `array` without a key type.',
+            [new CodeSample('<?php
+/**
+ * @param array<string>
+ */
+function foo($x) {}
+')],
+            '',
+        );
+    }
+
+    /**
+     * Must run before PhpdocAlignFixer, PhpdocTypesOrderFixer.
+     * Must run after CommentToPhpdocFixer, PhpdocArrayStyleFixer.
+     */
+    public function getPriority(): int
+    {
+        return 1;
+    }
+
+    protected function fixType(string $type): string
+    {
+        return Preg::replace('/array(?=<[^,]+(>|<|{|\\())/', 'list', $type);
+    }
+}

tests/Analyzer/Analysis/ConstructorAnalysisTest.php

@@ -64,7 +64,7 @@ public function __construct(Foo $x = null, ?Bar $y = null, float $z = 3.14) {}
     }
 
     /**
-     * @param array<string> $expected
+     * @param list<string> $expected
      *
      * @dataProvider provideGettingConstructorParameterNames80Cases
      *
@@ -80,7 +80,7 @@ public function testGettingConstructorParameterNames80(array $expected, string $
     }
 
     /**
-     * @return iterable<array{array<string>, string}>
+     * @return iterable<array{list<string>, string}>
      */
     public static function provideGettingConstructorParameterNames80Cases(): iterable
     {

tests/Fixer/PhpdocTypeListFixerTest.php

@@ -0,0 +1,77 @@
+<?php declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer: custom fixers.
+ *
+ * (c) 2018 Kuba Werłos
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Tests\Fixer;
+
+/**
+ * @internal
+ *
+ * @covers \PhpCsFixerCustomFixers\Fixer\PhpdocTypeListFixer
+ */
+final class PhpdocTypeListFixerTest extends AbstractFixerTestCase
+{
+    public function testIsRisky(): void
+    {
+        self::assertRiskiness(false);
+    }
+
+    /**
+     * @dataProvider provideFixCases
+     */
+    public function testFix(string $expected, ?string $input = null): void
+    {
+        $this->doTest($expected, $input);
+    }
+
+    /**
+     * @return iterable<array{0: string, 1?: string}>
+     */
+    public static function provideFixCases(): iterable
+    {
+        yield [
+            '<?php
+                /** @var array<int, string> */
+                /** @var array<int, array<string, bool>> */
+                /** @var array<int, array{string, string, string}> */
+            ',
+        ];
+
+        yield [
+            '<?php /** @var list<string> */',
+            '<?php /** @var array<string> */',
+        ];
+
+        yield [
+            '<?php /** @var list<list<list<string>>> */',
+            '<?php /** @var array<array<array<string>>> */',
+        ];
+
+        yield [
+            '<?php /** @var list<array<int, list<bool>>> */',
+            '<?php /** @var array<array<int, array<bool>>> */',
+        ];
+
+        yield [
+            '<?php /** @var array<int, list<array<string, bool>>> */',
+            '<?php /** @var array<int, array<array<string, bool>>> */',
+        ];
+
+        yield [
+            '<?php /** @var list<callable(int, int): string> */',
+            '<?php /** @var array<callable(int, int): string> */',
+        ];
+
+        yield [
+            '<?php /** @var non-empty-list<Type> */',
+            '<?php /** @var non-empty-array<Type> */',
+        ];
+    }
+}

tests/priority_fixtures/Custom_phpdoc_array_style,Custom_phpdoc_type_list.test

@@ -0,0 +1,15 @@
+--CONFIGURATION--
+{ "PhpCsFixerCustomFixers/phpdoc_array_style": true, "PhpCsFixerCustomFixers/phpdoc_type_list": true }
+--EXPECTED--
+<?php
+/**
+ * @return list<int>
+ */
+function bar() {}
+
+--INPUT--
+<?php
+/**
+ * @return int[]
+ */
+function bar() {}

tests/priority_fixtures/Custom_phpdoc_type_list,phpdoc_align.test

@@ -0,0 +1,17 @@
+--CONFIGURATION--
+{ "PhpCsFixerCustomFixers/phpdoc_type_list": true, "phpdoc_align": true }
+--EXPECTED--
+<?php
+/**
+ * @param list<int> $x
+ * @param string    $y
+ */
+function foo($x, $y) {}
+
+--INPUT--
+<?php
+/**
+ * @param array<int> $x
+ * @param string     $y
+ */
+function foo($x, $y) {}