feat: Add AddReturnDocblockForScalarArrayFromAssignsRector (#7151)

* Add a more specific return docblock for scalar lists when we are certain of the types inside the array (eg. when they were initialised and returned within the same function)

* Fixes for PHPStan

* Update rules/TypeDeclaration/Rector/ClassMethod/AddReturnDocblockForScalarArrayFromAssignsRector.php

Co-authored-by: Abdul Malik Ikhsan <samsonasik@gmail.com>

---------

Co-authored-by: Abdul Malik Ikhsan <samsonasik@gmail.com>

Author: imliam

rules-tests/TypeDeclaration/Rector/ClassMethod/AddReturnDocblockForScalarArrayFromAssignsRector/AddReturnDocblockForScalarArrayFromAssignsRectorTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\AddReturnDocblockForScalarArrayFromAssignsRector;
+
+use Iterator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Rector\Testing\PHPUnit\AbstractRectorTestCase;
+
+final class AddReturnDocblockForScalarArrayFromAssignsRectorTest extends AbstractRectorTestCase
+{
+    #[DataProvider('provideData')]
+    public function test(string $filePath): void
+    {
+        $this->doTestFile($filePath);
+    }
+
+    public static function provideData(): Iterator
+    {
+        return self::yieldFilesFromDirectory(__DIR__ . '/Fixture');
+    }
+
+    public function provideConfigFilePath(): string
+    {
+        return __DIR__ . '/config/configured_rule.php';
+    }
+}

rules-tests/TypeDeclaration/Rector/ClassMethod/AddReturnDocblockForScalarArrayFromAssignsRector/Fixture/simple_array_assigns.php.inc

@@ -0,0 +1,139 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\AddReturnDocblockForScalarArrayFromAssignsRector\Fixture;
+
+function getSomeItems()
+{
+    $items = [];
+    $items[] = 'hey';
+    $items[] = 'hello';
+    return $items;
+}
+
+class SomeClass
+{
+    public function getStringItems()
+    {
+        $items = [];
+        $items[] = 'first';
+        $items[] = 'second';
+        return $items;
+    }
+
+    public function getIntItems()
+    {
+        $numbers = [];
+        $numbers[] = 1;
+        $numbers[] = 2;
+        $numbers[] = 3;
+        return $numbers;
+    }
+
+    public function getFloatItems()
+    {
+        $floats = [];
+        $floats[] = 1.5;
+        $floats[] = 2.5;
+        return $floats;
+    }
+}
+
+function withNativeArrayType(): array
+{
+    $items = [];
+    $items[] = 'native';
+    $items[] = 'array';
+    return $items;
+}
+
+class WithNativeArrayReturn
+{
+    public function getNumbers(): array
+    {
+        $numbers = [];
+        $numbers[] = 42;
+        $numbers[] = 100;
+        return $numbers;
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\AddReturnDocblockForScalarArrayFromAssignsRector\Fixture;
+
+/**
+ * @return string[]
+ */
+function getSomeItems()
+{
+    $items = [];
+    $items[] = 'hey';
+    $items[] = 'hello';
+    return $items;
+}
+
+class SomeClass
+{
+    /**
+     * @return string[]
+     */
+    public function getStringItems()
+    {
+        $items = [];
+        $items[] = 'first';
+        $items[] = 'second';
+        return $items;
+    }
+
+    /**
+     * @return int[]
+     */
+    public function getIntItems()
+    {
+        $numbers = [];
+        $numbers[] = 1;
+        $numbers[] = 2;
+        $numbers[] = 3;
+        return $numbers;
+    }
+
+    /**
+     * @return float[]
+     */
+    public function getFloatItems()
+    {
+        $floats = [];
+        $floats[] = 1.5;
+        $floats[] = 2.5;
+        return $floats;
+    }
+}
+
+/**
+ * @return string[]
+ */
+function withNativeArrayType(): array
+{
+    $items = [];
+    $items[] = 'native';
+    $items[] = 'array';
+    return $items;
+}
+
+class WithNativeArrayReturn
+{
+    /**
+     * @return int[]
+     */
+    public function getNumbers(): array
+    {
+        $numbers = [];
+        $numbers[] = 42;
+        $numbers[] = 100;
+        return $numbers;
+    }
+}
+
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/AddReturnDocblockForScalarArrayFromAssignsRector/Fixture/skip_various_cases.php.inc

@@ -0,0 +1,85 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\AddReturnDocblockForScalarArrayFromAssignsRector\Fixture;
+
+class SkipAlreadyHasReturnType
+{
+    /**
+     * @return array
+     */
+    public function getItems()
+    {
+        $items = [];
+        $items[] = 'value';
+        return $items;
+    }
+}
+
+class SkipIterableReturnType
+{
+    public function getItems(): iterable
+    {
+        $items = [];
+        $items[] = 'value';
+        return $items;
+    }
+}
+
+class SkipMixedTypes
+{
+    public function getMixedItems()
+    {
+        $items = [];
+        $items[] = 'string';
+        $items[] = 123;
+        return $items;
+    }
+}
+
+class SkipNoArrayInit
+{
+    public function getItems()
+    {
+        $items[] = 'value';
+        return $items;
+    }
+}
+
+class SkipNoReturnVariable
+{
+    public function getItems()
+    {
+        $items = [];
+        $items[] = 'value';
+        return [];
+    }
+}
+
+class SkipExplicitKey
+{
+    public function getItems()
+    {
+        $items = [];
+        $items['key'] = 'value';
+        return $items;
+    }
+}
+
+class SkipMixedTypesInMultipleVariables
+{
+    public function getItems()
+    {
+        $strings = [];
+        $strings[] = 'string';
+        
+        $mixed = [];
+        $mixed[] = 'string';
+        $mixed[] = 123;
+        
+        if (rand(0, 1)) {
+            return $strings;
+        }
+        
+        return $mixed;
+    }
+}

rules-tests/TypeDeclaration/Rector/ClassMethod/AddReturnDocblockForScalarArrayFromAssignsRector/config/configured_rule.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\Config\RectorConfig;
+use Rector\TypeDeclaration\Rector\ClassMethod\AddReturnDocblockForScalarArrayFromAssignsRector;
+
+return RectorConfig::configure()
+    ->withRules([AddReturnDocblockForScalarArrayFromAssignsRector::class]);