Add support for placing string literals into PHPStan types (#111)

* Add support for placing string literals into PHPStan types for parameters and return values.

* Update the stubs.

* Update visitor.php

Co-authored-by: IanDelMar <42134098+IanDelMar@users.noreply.github.com>

* Regenerate the stubs and remove some more redundant functions in the map file.

* Apply suggestions from code review

Co-authored-by: IanDelMar <42134098+IanDelMar@users.noreply.github.com>

* Regenerate the stubs.

* Revert some unnecessary changes.

---------

Co-authored-by: IanDelMar <42134098+IanDelMar@users.noreply.github.com>

Author: johnbillion

functionMap.php

@@ -22,12 +22,10 @@
  * @link https://github.com/phpstan/phpstan-src/blob/1.5.x/resources/functionMap.php
  */
 return [
-    'add_meta_box' => ['void', 'context'=>'"normal"|"side"|"advanced"', 'priority'=>'"high"|"core"|"default"|"low"'],
     'addslashes_gpc' => ['T', '@phpstan-template'=>'T', 'gpc'=>'T'],
     'get_objects_in_term' => [null, 'args'=>'array{order?: string}'],
     'have_posts' => [null, '@phpstan-impure'=>''],
     'rawurlencode_deep' => ['T', '@phpstan-template'=>'T', 'value'=>'T'],
-    'remove_meta_box' => ['void', 'context'=>'"normal"|"side"|"advanced"'],
     'sanitize_category' => ['T', '@phpstan-template'=>'T of array|object', 'category'=>'T'],
     'sanitize_post' => ['T', '@phpstan-template'=>'T of array|object', 'post'=>'T'],
     'sanitize_term' => ['T', '@phpstan-template'=>'T of array|object', 'term'=>'T'],
@@ -41,7 +39,6 @@
     'WP_Http::head' => [$httpReturnType],
     'WP_Http::post' => [$httpReturnType],
     'WP_Http::request' => [$httpReturnType],
-    'WP_List_Table::bulk_actions' => ['void', 'which'=>'"top"|"bottom"'],
     'WP_List_Table::display_tablenav' => ['void', 'which'=>'"top"|"bottom"'],
     'WP_List_Table::pagination' => ['void', 'which'=>'"top"|"bottom"'],
     'WP_List_Table::set_pagination_args' => ['void', 'args'=>'array{total_items?: int, total_pages?: int, per_page?: int}'],
@@ -125,7 +122,6 @@
     'wp_loginout' => ['($display is true ? void : string)'],
     'wp_register' => ['($display is true ? void : string)'],
     'wp_title' => ['($display is true ? void : string)'],
-    'wp_script_is' => [null, 'status' => "'enqueued'|'registered'|'queue'|'to_do'|'done'"],
     'WP_Filesystem_Direct::dirlist' => [$filesystemDirlistReturnType],
     'WP_Filesystem_FTPext::dirlist' => [$filesystemDirlistReturnType],
     'WP_Filesystem_Base::dirlist' => [$filesystemDirlistReturnType],

visitor.php

@@ -43,7 +43,7 @@ public function isArrayShape(): bool
             }
         }
 
-        return true;
+        return $this->hasChildren();
     }
 
     public function isMixedShape(): bool
@@ -60,6 +60,11 @@ public function isMixedShape(): bool
 
         return false;
     }
+
+    public function hasChildren(): bool
+    {
+        return count($this->children) > 0;
+    }
 }
 
 final class WordPressTag extends WithChildren
@@ -89,6 +94,17 @@ final class WordPressTag extends WithChildren
      */
     public function format(): array
     {
+        if (! $this->hasChildren()) {
+            return [
+                sprintf(
+                    '%s %s%s',
+                    $this->tag,
+                    $this->type,
+                    ($this->name !== null) ? (' $' . $this->name) : ''
+                )
+            ];
+        }
+
         if ($this->isMixedShape()) {
             return [];
         }
@@ -711,6 +727,17 @@ private function getAdditionFromParam(Param $tag): ?WordPressTag
             return null;
         }
 
+        $tagDescriptionType = self::getTypeNameFromDescription($tagDescription, $tagVariableType);
+
+        if ($tagDescriptionType !== null) {
+            $tag = new WordPressTag();
+            $tag->tag = '@phpstan-param';
+            $tag->type = $tagDescriptionType;
+            $tag->name = $tagVariableName;
+
+            return $tag;
+        }
+
         $elements = self::getElementsFromDescription($tagDescription, true);
 
         if (count($elements) === 0) {
@@ -746,6 +773,16 @@ private function getAdditionFromReturn(Return_ $tag): ?WordPressTag
             return null;
         }
 
+        $tagDescriptionType = self::getTypeNameFromDescription($tagDescription, $tagVariableType);
+
+        if ($tagDescriptionType !== null) {
+            $tag = new WordPressTag();
+            $tag->tag = '@phpstan-return';
+            $tag->type = $tagDescriptionType;
+
+            return $tag;
+        }
+
         $elements = self::getElementsFromDescription($tagDescription, false);
 
         if (count($elements) === 0) {
@@ -796,6 +833,54 @@ private static function getAdditionFromVar(Var_ $tag): ?WordPressTag
         return $tag;
     }
 
+    private static function getTypeNameFromDescription(Description $tagVariableDescription, Type $tagVariableType): ?string
+    {
+        if (!($tagVariableType instanceof \phpDocumentor\Reflection\Types\String_)) {
+            return null;
+        }
+
+        return self::getTypeNameFromDescriptionString($tagVariableDescription->__toString());
+    }
+
+    private static function getTypeNameFromDescriptionString(string $tagDescription = null): ?string
+    {
+        if ($tagDescription === null) {
+            return null;
+        }
+
+        $fullDescription = str_replace("\n", ' ', $tagDescription);
+
+        /**
+         * This matches phrases that contain a list of two or more single-quoted strings, with the last
+         * item separated by 'or' or 'and'. The Oxford comma is optional. For example:
+         *
+         * - Either 'am', 'pm', 'AM', or 'PM'
+         * - Accepts 'comment' or 'term'
+         * - Either 'plugin' or 'theme'
+         * - Accepts 'big', or 'little'.
+         * - One of 'default', 'theme', or 'custom'
+         * - Either 'network-active', 'active' or 'inactive'
+         * - : 'top' or 'bottom'
+         */
+        $matched = preg_match("#(?>returns|either|one of|accepts|values are|:) ('.+'),? (?>or|and) '([^']+)'#i", $fullDescription, $matches);
+
+        if (! $matched) {
+            return null;
+        }
+
+        list(, $items, $final) = $matches;
+
+        // Pluck out phrases between single quotes, so messy sentences are handled:
+        preg_match_all("#'([^']+)'#", $items, $matches);
+
+        list(,$accepted) = $matches;
+
+        // Append the final item:
+        $accepted[] = $final;
+
+        return "'" . implode("'|'", $accepted) . "'";
+    }
+
     private static function getTypeNameFromType(Type $tagVariableType): ?string
     {
         return self::getTypeNameFromString($tagVariableType->__toString());