make stubbed constant types configurable with comment

src/Psalm/Internal/PhpVisitor/Reflector/ExpressionScanner.php

@@ -6,8 +6,10 @@
 use Psalm\Aliases;
 use Psalm\Codebase;
 use Psalm\Config;
+use Psalm\Exception\DocblockParseException;
 use Psalm\Exception\FileIncludeException;
 use Psalm\Internal\Analyzer\ClassLikeAnalyzer;
+use Psalm\Internal\Analyzer\CommentAnalyzer;
 use Psalm\Internal\Analyzer\Statements\Expression\CallAnalyzer;
 use Psalm\Internal\Analyzer\Statements\Expression\Fetch\ConstFetchAnalyzer;
 use Psalm\Internal\Analyzer\Statements\Expression\IncludeAnalyzer;
@@ -151,7 +153,29 @@ private static function registerClassMapFunctionCall(
                         $type_provider,
                         $second_arg_value,
                         $aliases,
-                    ) ?? Type::getMixed();
+                    );
+
+                    // allow docblocks to override the declared value to make constants in stubs configurable
+                    $doc_comment = $second_arg_value->getDocComment();
+                    if ($doc_comment) {
+                        try {
+                            $var_comments = CommentAnalyzer::getTypeFromComment($doc_comment, $file_scanner, $aliases);
+                            foreach ($var_comments as $var_comment) {
+                                if ($var_comment->type) {
+                                    $const_type = $var_comment->type;
+                                }
+
+                                // only check the first @var comment
+                                break;
+                            }
+                        } catch (DocblockParseException $e) {
+                            // do nothing
+                        }
+                    }
+
+                    if ($const_type === null) {
+                        $const_type = Type::getMixed();
+                    }
 
                     $config = Config::getInstance();
 

tests/StubTest.php

@@ -693,6 +693,48 @@ public function testConditionalConstantDefined(): void
         $this->analyzeFile($file_path, new Context());
     }
 
+    /**
+     * @runInSeparateProcess
+     */
+    public function testStubbedConstantVarCommentType(): void
+    {
+        $this->project_analyzer = $this->getProjectAnalyzerWithConfig(
+            TestConfig::loadFromXML(
+                dirname(__DIR__),
+                '<?xml version="1.0"?>
+                <psalm
+                    errorLevel="1"
+                >
+                    <projectFiles>
+                        <directory name="src" />
+                    </projectFiles>
+
+                    <stubs>
+                        <file name="tests/fixtures/stubs/constant_var_comment.phpstub" />
+                    </stubs>
+                </psalm>',
+            ),
+        );
+
+        $file_path = getcwd() . '/src/somefile.php';
+
+        $this->addFile(
+            $file_path,
+            '<?php
+                /**
+                 * @param non-empty-string $arg
+                 * @return void
+                 */
+                function hello($arg) {
+                    echo $arg;
+                }
+
+                hello(FOO_BAR);',
+        );
+
+        $this->analyzeFile($file_path, new Context());
+    }
+
     /**
      * @runInSeparateProcess
      */

tests/fixtures/stubs/constant_var_comment.phpstub

@@ -0,0 +1,3 @@
+<?php
+
+define('FOO_BAR', /** @var non-empty-string */ 'world');