Change API

.gitignore

@@ -12,3 +12,4 @@
 /tests/fixtures/symlinktest/*
 
 .idea/
+.vscode/

src/Psalm/Codebase.php

@@ -60,6 +60,7 @@
 use Psalm\Type\Atomic\TLiteralInt;
 use Psalm\Type\Atomic\TLiteralString;
 use Psalm\Type\Atomic\TNamedObject;
+use Psalm\Type\ImmutableUnion;
 use Psalm\Type\TaintKindGroup;
 use Psalm\Type\Union;
 use ReflectionProperty;
@@ -638,7 +639,7 @@ public function getClosureStorage(string $file_path, string $closure_id): Functi
         );
     }
 
-    public function addGlobalConstantType(string $const_id, Union $type): void
+    public function addGlobalConstantType(string $const_id, Union|ImmutableUnion $type): void
     {
         self::$stubbed_constants[$const_id] = $type;
     }
@@ -1755,7 +1756,7 @@ public function getCompletionItemsForPartialSymbol(
     /**
      * @return list<CompletionItem>
      */
-    public function getCompletionItemsForType(Union $type): array
+    public function getCompletionItemsForType(Union|ImmutableUnion $type): array
     {
         $completion_items = [];
         foreach ($type->getAtomicTypes() as $atomic_type) {
@@ -1876,8 +1877,8 @@ public function removeTemporaryFileChanges(string $file_path): void
      * should be a subset of the function parameter type.
      */
     public function isTypeContainedByType(
-        Union $input_type,
-        Union $container_type
+        Union|ImmutableUnion $input_type,
+        Union|ImmutableUnion $container_type
     ): bool {
         return UnionTypeComparator::isContainedBy($this, $input_type, $container_type);
     }
@@ -1896,8 +1897,8 @@ public function isTypeContainedByType(
      * not a subtype of the required type.
      */
     public function canTypeBeContainedByType(
-        Union $input_type,
-        Union $container_type
+        Union|ImmutableUnion $input_type,
+        Union|ImmutableUnion $container_type
     ): bool {
         return UnionTypeComparator::canBeContainedBy($this, $input_type, $container_type);
     }
@@ -1948,7 +1949,7 @@ public function queueClassLikeForScanning(
      * @psalm-suppress PossiblyUnusedMethod
      */
     public function addTaintSource(
-        Union $expr_type,
+        Union|ImmutableUnion $expr_type,
         string $taint_id,
         array $taints = TaintKindGroup::ALL_INPUT,
         ?CodeLocation $code_location = null

src/Psalm/Context.php

@@ -13,6 +13,7 @@
 use Psalm\Storage\FunctionLikeStorage;
 use Psalm\Type\Atomic\DependentType;
 use Psalm\Type\Atomic\TArray;
+use Psalm\Type\ImmutableUnion;
 use Psalm\Type\Union;
 use RuntimeException;
 
@@ -678,7 +679,7 @@ public static function removeReconciledClauses(array $clauses, array $changed_va
     public static function filterClauses(
         string $remove_var_id,
         array $clauses,
-        ?Union $new_type = null,
+        Union|ImmutableUnion|null $new_type = null,
         ?StatementsAnalyzer $statements_analyzer = null
     ): array {
         $new_type_string = $new_type ? $new_type->getId() : '';
@@ -744,7 +745,7 @@ public static function filterClauses(
 
     public function removeVarFromConflictingClauses(
         string $remove_var_id,
-        ?Union $new_type = null,
+        Union|ImmutableUnion|null $new_type = null,
         ?StatementsAnalyzer $statements_analyzer = null
     ): void {
         $this->clauses = self::filterClauses($remove_var_id, $this->clauses, $new_type, $statements_analyzer);
@@ -757,8 +758,8 @@ public function removeVarFromConflictingClauses(
      */
     public function removeDescendents(
         string $remove_var_id,
-        Union $existing_type,
-        ?Union $new_type = null,
+        Union|ImmutableUnion $existing_type,
+        Union|ImmutableUnion|null $new_type = null,
         ?StatementsAnalyzer $statements_analyzer = null
     ): void {
         $this->removeVarFromConflictingClauses(
@@ -775,18 +776,13 @@ public function removeDescendents(
                 $this->remove($var_id, false);
             }
 
-            $builder = null;
             foreach ($type->getAtomicTypes() as $atomic_type) {
                 if ($atomic_type instanceof DependentType
                     && $atomic_type->getVarId() === $remove_var_id
                 ) {
-                    $builder ??= $type->getBuilder();
-                    $builder->addType($atomic_type->getReplacement());
+                    $type->addType($atomic_type->getReplacement());
                 }
             }
-            if ($builder) {
-                $type = $builder->build();
-            }
         }
     }
 

src/Psalm/Internal/Analyzer/ClassAnalyzer.php

@@ -76,6 +76,7 @@
 use Psalm\Type\Atomic\TNamedObject;
 use Psalm\Type\Atomic\TNull;
 use Psalm\Type\Atomic\TTemplateParam;
+use Psalm\Type\ImmutableUnion;
 use Psalm\Type\Union;
 use UnexpectedValueException;
 
@@ -790,11 +791,13 @@ public static function addContextProperties(
 
                     $template_result = new TemplateResult([], $lower_bounds);
 
-                    $guide_property_type = TemplateInferredTypeReplacer::replace($guide_property_type,
+                    $guide_property_type = TemplateInferredTypeReplacer::replace(
+                        $guide_property_type,
                         $template_result,
                         $codebase
                     );
-                    $property_type = TemplateInferredTypeReplacer::replace($property_type,
+                    $property_type = TemplateInferredTypeReplacer::replace(
+                        $property_type,
                         $template_result,
                         $codebase
                     );
@@ -1291,11 +1294,7 @@ static function (FunctionLikeParameter $param): PhpParser\Node\Arg {
                         );
                     } elseif (!$property_storage->has_default) {
                         if (isset($this->inferred_property_types[$property_name])) {
-                            $this->inferred_property_types[$property_name] =
-                                $this->inferred_property_types[$property_name]
-                                    ->getBuilder()
-                                    ->addType(new TNull())
-                                    ->build();
+                            $this->inferred_property_types[$property_name]->addType(new TNull());
                             $this->inferred_property_types[$property_name]->setFromDocblock();
                         }
                     }
@@ -1591,7 +1590,7 @@ private function analyzeProperty(
     private static function addOrUpdatePropertyType(
         ProjectAnalyzer $project_analyzer,
         PhpParser\Node\Stmt\Property $property,
-        Union $inferred_type,
+        Union|ImmutableUnion $inferred_type,
         StatementsSource $source,
         bool $docblock_only = false
     ): void {

src/Psalm/Internal/Analyzer/FunctionLike/ReturnTypeAnalyzer.php

@@ -50,6 +50,7 @@
 use Psalm\Type\Atomic\TNamedObject;
 use Psalm\Type\Atomic\TNever;
 use Psalm\Type\Atomic\TNull;
+use Psalm\Type\ImmutableUnion;
 use Psalm\Type\Union;
 
 use function array_diff;
@@ -80,7 +81,7 @@ public static function verifyReturnType(
         SourceAnalyzer $source,
         NodeDataProvider $type_provider,
         FunctionLikeAnalyzer $function_like_analyzer,
-        ?Union $return_type = null,
+        Union|ImmutableUnion|null $return_type = null,
         ?string $fq_class_name = null,
         ?string $static_fq_class_name = null,
         ?CodeLocation $return_type_location = null,
@@ -242,7 +243,7 @@ public static function verifyReturnType(
         if ($number_of_types > 1) {
             $inferred_return_type_parts = array_filter(
                 $inferred_return_type_parts,
-                static fn(Union $union_type): bool => !$union_type->isNever()
+                static fn(Union|ImmutableUnion $union_type): bool => !$union_type->isNever()
             );
         }
 
@@ -936,7 +937,7 @@ public static function checkReturnType(
     private static function addOrUpdateReturnType(
         FunctionLike $function,
         ProjectAnalyzer $project_analyzer,
-        Union $inferred_return_type,
+        Union|ImmutableUnion $inferred_return_type,
         StatementsSource $source,
         bool $docblock_only = false,
         ?FunctionLikeStorage $function_like_storage = null

src/Psalm/Internal/Analyzer/FunctionLikeAnalyzer.php

@@ -57,6 +57,7 @@
 use Psalm\Type\Atomic\TList;
 use Psalm\Type\Atomic\TNamedObject;
 use Psalm\Type\Atomic\TTemplateParam;
+use Psalm\Type\ImmutableUnion;
 use Psalm\Type\Union;
 use UnexpectedValueException;
 
@@ -1416,7 +1417,7 @@ private function alterParams(
     public function verifyReturnType(
         array $function_stmts,
         StatementsAnalyzer $statements_analyzer,
-        ?Union $return_type = null,
+        Union|ImmutableUnion|null $return_type = null,
         ?string $fq_class_name = null,
         ?CodeLocation $return_type_location = null,
         bool $did_explicitly_return = false,
@@ -1441,7 +1442,7 @@ public function verifyReturnType(
     public function addOrUpdateParamType(
         ProjectAnalyzer $project_analyzer,
         string $param_name,
-        Union $inferred_return_type,
+        Union|ImmutableUnion $inferred_return_type,
         bool $docblock_only = false
     ): void {
         $manipulator = FunctionDocblockManipulator::getForFunction(
@@ -1738,7 +1739,7 @@ public static function clearCache(): void
         self::$no_effects_hashes = [];
     }
 
-    public function getLocalReturnType(Union $storage_return_type, bool $final = false): Union
+    public function getLocalReturnType(Union|ImmutableUnion $storage_return_type, bool $final = false): Union
     {
         if ($this->local_return_type) {
             return $this->local_return_type;

src/Psalm/Internal/Analyzer/MethodComparator.php

@@ -34,6 +34,7 @@
 use Psalm\Type;
 use Psalm\Type\Atomic\TNull;
 use Psalm\Type\Atomic\TTemplateParam;
+use Psalm\Type\ImmutableUnion;
 use Psalm\Type\Union;
 
 use function array_filter;
@@ -555,7 +556,7 @@ private static function compareMethodSignatureParams(
         MethodStorage $guide_method_storage,
         MethodStorage $implementer_method_storage,
         FunctionLikeParameter $guide_param,
-        Union $implementer_param_signature_type,
+        Union|ImmutableUnion $implementer_param_signature_type,
         string $cased_guide_method_id,
         string $cased_implementer_method_id,
         CodeLocation $code_location,
@@ -676,8 +677,8 @@ private static function compareMethodDocblockParams(
         MethodStorage $implementer_method_storage,
         string $cased_guide_method_id,
         string $cased_implementer_method_id,
-        Union $guide_param_type,
-        Union $implementer_param_type,
+        Union|ImmutableUnion $guide_param_type,
+        Union|ImmutableUnion $implementer_param_type,
         CodeLocation $code_location,
         array $suppressed_issues
     ): void {
@@ -839,7 +840,7 @@ private static function compareMethodSignatureReturnTypes(
         ClassLikeStorage $implementer_classlike_storage,
         MethodStorage $guide_method_storage,
         MethodStorage $implementer_method_storage,
-        Union $guide_signature_return_type,
+        Union|ImmutableUnion $guide_signature_return_type,
         string $cased_guide_method_id,
         string $implementer_called_class_name,
         string $cased_implementer_method_id,
@@ -925,8 +926,8 @@ private static function compareMethodDocblockReturnTypes(
         ClassLikeStorage $guide_classlike_storage,
         ClassLikeStorage $implementer_classlike_storage,
         MethodStorage $implementer_method_storage,
-        Union $guide_return_type,
-        Union $implementer_return_type,
+        Union|ImmutableUnion $guide_return_type,
+        Union|ImmutableUnion $implementer_return_type,
         string $cased_guide_method_id,
         string $implementer_called_class_name,
         ?MethodIdentifier $implementer_declaring_method_id,
@@ -1055,7 +1056,7 @@ private static function compareMethodDocblockReturnTypes(
     private static function transformTemplates(
         array $template_extended_params,
         string $base_class_name,
-        Union $templated_type,
+        Union|ImmutableUnion $templated_type,
         Codebase $codebase
     ): void {
         if (isset($template_extended_params[$base_class_name])) {
@@ -1092,7 +1093,8 @@ private static function transformTemplates(
 
             $template_result = new TemplateResult([], $template_types);
 
-            $templated_type = TemplateInferredTypeReplacer::replace($templated_type,
+            $templated_type = TemplateInferredTypeReplacer::replace(
+                $templated_type,
                 $template_result,
                 $codebase
             );

src/Psalm/Internal/Analyzer/NamespaceAnalyzer.php

@@ -8,6 +8,7 @@
 use Psalm\Context;
 use Psalm\Internal\Provider\NodeDataProvider;
 use Psalm\Type;
+use Psalm\Type\ImmutableUnion;
 use Psalm\Type\Union;
 use ReflectionProperty;
 use UnexpectedValueException;
@@ -124,7 +125,7 @@ public function getNamespace(): string
         return $this->namespace_name;
     }
 
-    public function setConstType(string $const_name, Union $const_type): void
+    public function setConstType(string $const_name, Union|ImmutableUnion $const_type): void
     {
         self::$public_namespace_constants[$this->namespace_name][$const_name] = $const_type;
     }

src/Psalm/Internal/Analyzer/Statements/Block/ForeachAnalyzer.php

@@ -57,6 +57,7 @@
 use Psalm\Type\Atomic\TObjectWithProperties;
 use Psalm\Type\Atomic\TTemplateParam;
 use Psalm\Type\Atomic\TVoid;
+use Psalm\Type\ImmutableUnion;
 use Psalm\Type\Union;
 use UnexpectedValueException;
 
@@ -392,7 +393,7 @@ public static function checkIteratorType(
         StatementsAnalyzer $statements_analyzer,
         PhpParser\NodeAbstract $stmt,
         PhpParser\Node\Expr $expr,
-        Union $iterator_type,
+        Union|ImmutableUnion $iterator_type,
         Codebase $codebase,
         Context $context,
         ?Union &$key_type,

src/Psalm/Internal/Analyzer/Statements/Expression/ArrayAnalyzer.php

@@ -40,6 +40,7 @@
 use Psalm\Type\Atomic\TString;
 use Psalm\Type\Atomic\TTemplateParam;
 use Psalm\Type\Atomic\TTrue;
+use Psalm\Type\ImmutableUnion;
 use Psalm\Type\Union;
 
 use function array_merge;
@@ -516,7 +517,7 @@ private static function handleUnpackedArray(
         StatementsAnalyzer $statements_analyzer,
         ArrayCreationInfo $array_creation_info,
         PhpParser\Node\Expr\ArrayItem $item,
-        Union $unpacked_array_type,
+        Union|ImmutableUnion $unpacked_array_type,
         Codebase $codebase
     ): void {
         foreach ($unpacked_array_type->getAtomicTypes() as $unpacked_atomic_type) {