DX: Narrow docblock types in FixerConfiguration (#6580)

PHP-CS-Fixer · Aug 25, 2022 · 67e28fb · 67e28fb
1 parent 1000511
commit 67e28fb
Show file tree

Hide file tree

Showing 22 changed files with 92 additions and 54 deletions.
diff --git a/phpstan.neon b/phpstan.neon
@@ -23,6 +23,6 @@ parameters:
         -
             message: '#^.+no value type specified in iterable type.+\.$#'
             path: *
-            count: 482
+            count: 461
     tipsOfTheDay: false
     tmpDir: dev-tools/phpstan/cache
diff --git a/src/Console/Command/DescribeCommand.php b/src/Console/Command/DescribeCommand.php
@@ -196,19 +196,15 @@ private function describeRule(OutputInterface $output, string $name): void
 
                 if (null === $allowed) {
                     $allowed = array_map(
-                        static function (string $type): string {
-                            return '<comment>'.$type.'</comment>';
-                        },
-                        $option->getAllowedTypes()
+                        static fn (string $type): string => '<comment>'.$type.'</comment>',
+                        $option->getAllowedTypes(),
                     );
                 } else {
-                    foreach ($allowed as &$value) {
-                        if ($value instanceof AllowedValueSubset) {
-                            $value = 'a subset of <comment>'.HelpCommand::toString($value->getAllowedValues()).'</comment>';
-                        } else {
-                            $value = '<comment>'.HelpCommand::toString($value).'</comment>';
-                        }
-                    }
+                    $allowed = array_map(static function ($value): string {
+                        return $value instanceof AllowedValueSubset
+                            ? 'a subset of <comment>'.HelpCommand::toString($value->getAllowedValues()).'</comment>'
+                            : '<comment>'.HelpCommand::toString($value).'</comment>';
+                    }, $allowed);
                 }
 
                 $line .= ' ('.implode(', ', $allowed).')';

diff --git a/src/Console/Command/HelpCommand.php b/src/Console/Command/HelpCommand.php
@@ -50,14 +50,16 @@ public static function toString($value): string
 
     /**
      * Returns the allowed values of the given option that can be converted to a string.
+     *
+     * @return list<null|AllowedValueSubset|scalar>
      */
     public static function getDisplayableAllowedValues(FixerOptionInterface $option): ?array
     {
         $allowed = $option->getAllowedValues();
 
         if (null !== $allowed) {
             $allowed = array_filter($allowed, static function ($value): bool {
-                return !$value instanceof \Closure;
+                return null === $value || \is_scalar($value) || $value instanceof AllowedValueSubset;
             });
 
             usort($allowed, static function ($valueA, $valueB): int {

diff --git a/src/Documentation/FixerDocumentGenerator.php b/src/Documentation/FixerDocumentGenerator.php
@@ -148,19 +148,17 @@ public function generateFixerDocumentation(FixerInterface $fixer): string
 
                 if (null === $allowed) {
                     $allowedKind = 'Allowed types';
-                    $allowed = array_map(static function ($value): string {
-                        return '``'.$value.'``';
-                    }, $option->getAllowedTypes());
+                    $allowed = array_map(
+                        static fn ($value): string => '``'.$value.'``',
+                        $option->getAllowedTypes(),
+                    );
                 } else {
                     $allowedKind = 'Allowed values';
-
-                    foreach ($allowed as &$value) {
-                        if ($value instanceof AllowedValueSubset) {
-                            $value = 'a subset of ``'.HelpCommand::toString($value->getAllowedValues()).'``';
-                        } else {
-                            $value = '``'.HelpCommand::toString($value).'``';
-                        }
-                    }
+                    $allowed = array_map(static function ($value): string {
+                        return $value instanceof AllowedValueSubset
+                            ? 'a subset of ``'.HelpCommand::toString($value->getAllowedValues()).'``'
+                            : '``'.HelpCommand::toString($value).'``';
+                    }, $allowed);
                 }
 
                 $allowed = implode(', ', $allowed);

diff --git a/src/Documentation/ListDocumentGenerator.php b/src/Documentation/ListDocumentGenerator.php
@@ -108,19 +108,17 @@ static function (FixerInterface $fixer1, FixerInterface $fixer2): int {
 
                     if (null === $allowed) {
                         $allowedKind = 'Allowed types';
-                        $allowed = array_map(static function ($value): string {
-                            return '``'.$value.'``';
-                        }, $option->getAllowedTypes());
+                        $allowed = array_map(
+                            static fn ($value): string => '``'.$value.'``',
+                            $option->getAllowedTypes(),
+                        );
                     } else {
                         $allowedKind = 'Allowed values';
-
-                        foreach ($allowed as &$value) {
-                            if ($value instanceof AllowedValueSubset) {
-                                $value = 'a subset of ``'.HelpCommand::toString($value->getAllowedValues()).'``';
-                            } else {
-                                $value = '``'.HelpCommand::toString($value).'``';
-                            }
-                        }
+                        $allowed = array_map(static function ($value): string {
+                            return $value instanceof AllowedValueSubset
+                                ? 'a subset of ``'.HelpCommand::toString($value->getAllowedValues()).'``'
+                                : '``'.HelpCommand::toString($value).'``';
+                        }, $allowed);
                     }
 
                     $allowed = implode(', ', $allowed);

diff --git a/src/FixerConfiguration/AliasedFixerOptionBuilder.php b/src/FixerConfiguration/AliasedFixerOptionBuilder.php
@@ -42,7 +42,7 @@ public function setDefault($default): self
     }
 
     /**
-     * @param string[] $allowedTypes
+     * @param list<string> $allowedTypes
      */
     public function setAllowedTypes(array $allowedTypes): self
     {
@@ -51,6 +51,9 @@ public function setAllowedTypes(array $allowedTypes): self
         return $this;
     }
 
+    /**
+     * @param list<(callable(mixed): bool)|null|scalar> $allowedValues
+     */
     public function setAllowedValues(array $allowedValues): self
     {
         $this->optionBuilder->setAllowedValues($allowedValues);

diff --git a/src/FixerConfiguration/AllowedValueSubset.php b/src/FixerConfiguration/AllowedValueSubset.php
@@ -19,8 +19,14 @@
  */
 final class AllowedValueSubset
 {
+    /**
+     * @var list<string>
+     */
     private array $allowedValues;
 
+    /**
+     * @param list<string> $allowedValues
+     */
     public function __construct(array $allowedValues)
     {
         $this->allowedValues = $allowedValues;
@@ -46,6 +52,9 @@ public function __invoke($values): bool
         return true;
     }
 
+    /**
+     * @return list<string>
+     */
     public function getAllowedValues(): ?array
     {
         return $this->allowedValues;

diff --git a/src/FixerConfiguration/FixerConfigurationResolver.php b/src/FixerConfiguration/FixerConfigurationResolver.php
@@ -21,12 +21,12 @@
 final class FixerConfigurationResolver implements FixerConfigurationResolverInterface
 {
     /**
-     * @var FixerOptionInterface[]
+     * @var list<FixerOptionInterface>
      */
     private array $options = [];
 
     /**
-     * @var string[]
+     * @var list<string>
      */
     private array $registeredNames = [];
 

diff --git a/src/FixerConfiguration/FixerConfigurationResolverInterface.php b/src/FixerConfiguration/FixerConfigurationResolverInterface.php
@@ -17,7 +17,7 @@
 interface FixerConfigurationResolverInterface
 {
     /**
-     * @return FixerOptionInterface[]
+     * @return list<FixerOptionInterface>
      */
     public function getOptions(): array;
 

diff --git a/src/FixerConfiguration/FixerOption.php b/src/FixerConfiguration/FixerOption.php
@@ -28,12 +28,12 @@ final class FixerOption implements FixerOptionInterface
     private $default;
 
     /**
-     * @var null|string[]
+     * @var null|list<string>
      */
     private $allowedTypes;
 
     /**
-     * @var null|array
+     * @var null|list<(callable(mixed): bool)|null|scalar>
      */
     private $allowedValues;
 
@@ -43,8 +43,9 @@ final class FixerOption implements FixerOptionInterface
     private $normalizer;
 
     /**
-     * @param mixed         $default
-     * @param null|string[] $allowedTypes
+     * @param mixed             $default
+     * @param null|list<string> $allowedTypes
+     * @param null|list<(callable(mixed): bool)|null|scalar> $allowedValues
      */
     public function __construct(
         string $name,

diff --git a/src/FixerConfiguration/FixerOptionBuilder.php b/src/FixerConfiguration/FixerOptionBuilder.php
@@ -28,12 +28,12 @@ final class FixerOptionBuilder
     private bool $isRequired = true;
 
     /**
-     * @var null|string[]
+     * @var null|list<string>
      */
     private $allowedTypes;
 
     /**
-     * @var null|array
+     * @var null|list<(callable(mixed): bool)|null|scalar>
      */
     private $allowedValues;
 
@@ -67,7 +67,7 @@ public function setDefault($default): self
     }
 
     /**
-     * @param string[] $allowedTypes
+     * @param list<string> $allowedTypes
      *
      * @return $this
      */
@@ -79,6 +79,8 @@ public function setAllowedTypes(array $allowedTypes): self
     }
 
     /**
+     * @param list<(callable(mixed): bool)|null|scalar> $allowedValues
+     *
      * @return $this
      */
     public function setAllowedValues(array $allowedValues): self

diff --git a/src/FixerConfiguration/FixerOptionInterface.php b/src/FixerConfiguration/FixerOptionInterface.php
@@ -30,10 +30,13 @@ public function hasDefault(): bool;
     public function getDefault();
 
     /**
-     * @return null|string[]
+     * @return null|list<string>
      */
     public function getAllowedTypes(): ?array;
 
+    /**
+     * @return null|list<(callable(mixed): bool)|null|scalar>
+     */
     public function getAllowedValues(): ?array;
 
     public function getNormalizer(): ?\Closure;

diff --git a/src/FixerDefinition/CodeSample.php b/src/FixerDefinition/CodeSample.php
@@ -21,8 +21,14 @@ final class CodeSample implements CodeSampleInterface
 {
     private string $code;
 
+    /**
+     * @var null|array<string, mixed>
+     */
     private ?array $configuration;
 
+    /**
+     * @param null|array<string, mixed> $configuration
+     */
     public function __construct(string $code, ?array $configuration = null)
     {
         $this->code = $code;

diff --git a/src/FixerDefinition/CodeSampleInterface.php b/src/FixerDefinition/CodeSampleInterface.php
@@ -21,5 +21,8 @@ interface CodeSampleInterface
 {
     public function getCode(): string;
 
+    /**
+     * @return null|array<string, mixed>
+     */
     public function getConfiguration(): ?array;
 }
diff --git a/src/FixerDefinition/FileSpecificCodeSample.php b/src/FixerDefinition/FileSpecificCodeSample.php
@@ -25,6 +25,9 @@ final class FileSpecificCodeSample implements FileSpecificCodeSampleInterface
 
     private \SplFileInfo $splFileInfo;
 
+    /**
+     * @param null|array<string, mixed> $configuration
+     */
     public function __construct(
         string $code,
         \SplFileInfo $splFileInfo,

diff --git a/src/FixerDefinition/FixerDefinition.php b/src/FixerDefinition/FixerDefinition.php
@@ -22,7 +22,7 @@ final class FixerDefinition implements FixerDefinitionInterface
     private string $summary;
 
     /**
-     * @var CodeSampleInterface[]
+     * @var list<CodeSampleInterface>
      */
     private array $codeSamples;
 
@@ -31,8 +31,8 @@ final class FixerDefinition implements FixerDefinitionInterface
     private ?string $riskyDescription;
 
     /**
-     * @param CodeSampleInterface[] $codeSamples      array of samples, where single sample is [code, configuration]
-     * @param null|string           $riskyDescription null for non-risky fixer
+     * @param list<CodeSampleInterface> $codeSamples      array of samples, where single sample is [code, configuration]
+     * @param null|string               $riskyDescription null for non-risky fixer
      */
     public function __construct(
         string $summary,

diff --git a/src/FixerDefinition/FixerDefinitionInterface.php b/src/FixerDefinition/FixerDefinitionInterface.php
@@ -31,7 +31,7 @@ public function getRiskyDescription(): ?string;
     /**
      * Array of samples, where single sample is [code, configuration].
      *
-     * @return CodeSampleInterface[]
+     * @return list<CodeSampleInterface>
      */
     public function getCodeSamples(): array;
 }
diff --git a/src/FixerDefinition/VersionSpecificCodeSample.php b/src/FixerDefinition/VersionSpecificCodeSample.php
@@ -23,6 +23,9 @@ final class VersionSpecificCodeSample implements VersionSpecificCodeSampleInterf
 
     private VersionSpecificationInterface $versionSpecification;
 
+    /**
+     * @param null|array<string, mixed> $configuration
+     */
     public function __construct(
         string $code,
         VersionSpecificationInterface $versionSpecification,

diff --git a/src/FixerDefinition/VersionSpecification.php b/src/FixerDefinition/VersionSpecification.php
@@ -19,11 +19,20 @@
  */
 final class VersionSpecification implements VersionSpecificationInterface
 {
+    /**
+     * @var null|int<1, max>
+     */
     private ?int $minimum;
 
+    /**
+     * @var null|int<1, max>
+     */
     private ?int $maximum;
 
     /**
+     * @param null|int<1, max> $minimum
+     * @param null|int<1, max> $maximum
+     *
      * @throws \InvalidArgumentException
      */
     public function __construct(?int $minimum = null, ?int $maximum = null)
@@ -32,11 +41,13 @@ public function __construct(?int $minimum = null, ?int $maximum = null)
             throw new \InvalidArgumentException('Minimum or maximum need to be specified.');
         }
 
+        // @phpstan-ignore-next-line
         if (null !== $minimum && 1 > $minimum) {
             throw new \InvalidArgumentException('Minimum needs to be either null or an integer greater than 0.');
         }
 
         if (null !== $maximum) {
+            // @phpstan-ignore-next-line
             if (1 > $maximum) {
                 throw new \InvalidArgumentException('Maximum needs to be either null or an integer greater than 0.');
             }

diff --git a/tests/Console/Command/HelpCommandTest.php b/tests/Console/Command/HelpCommandTest.php
@@ -77,7 +77,7 @@ public function provideGetDisplayableAllowedValuesCases(): iterable
 
         yield [['A', 'B', 'x', 'z'], new FixerOption('foo', 'bar', false, null, ['string'], ['z', 'x', 'B', 'A'])];
 
-        yield [[0, 3, 9], new FixerOption('foo', 'bar', false, null, ['int'], [0, 3, 9, static fn () => null])];
+        yield [[0, 3, 9], new FixerOption('foo', 'bar', false, null, ['int'], [0, 3, 9, static fn () => true])];
 
         yield [null, new FixerOption('foo', 'bar')];
     }

diff --git a/tests/FixerConfiguration/AliasedFixerOptionTest.php b/tests/FixerConfiguration/AliasedFixerOptionTest.php
@@ -152,7 +152,7 @@ public function provideGetAllowedValuesCases(): array
 
     public function testGetAllowedValuesClosure(): void
     {
-        $option = new AliasedFixerOption(new FixerOption('foo', 'Bar.', true, null, null, [static fn () => null]), 'baz');
+        $option = new AliasedFixerOption(new FixerOption('foo', 'Bar.', true, null, null, [static fn () => true]), 'baz');
         $allowedTypes = $option->getAllowedValues();
         static::assertIsArray($allowedTypes);
         static::assertCount(1, $allowedTypes);

diff --git a/tests/FixerConfiguration/FixerOptionTest.php b/tests/FixerConfiguration/FixerOptionTest.php
@@ -83,7 +83,7 @@ public function testGetAllowedValues(): void
         $option = new FixerOption('foo', 'Bar.', true, null, null, ['baz', 'qux']);
         static::assertSame(['baz', 'qux'], $option->getAllowedValues());
 
-        $option = new FixerOption('foo', 'Bar.', true, null, null, [static fn () => null]);
+        $option = new FixerOption('foo', 'Bar.', true, null, null, [static fn () => true]);
         $allowedTypes = $option->getAllowedValues();
         static::assertIsArray($allowedTypes);
         static::assertCount(1, $allowedTypes);