List refactoring (v6)

UPGRADING.md

@@ -1,6 +1,12 @@
 # Upgrading from Psalm 4 to Psalm 5
 ## Changed
 
+- [BC] Psalm 5.1 will switch its internal representation of `list<T>` and `non-empty-list<T>` from the TList and TNonEmptyList classes to an unsealed list shape: the TList, TNonEmptyList and TCallableList classes will be removed.
+  Nothing will change for users: `list<T>` and `non-empty-list<T>` syntax will remain supported and its semantics unchanged.
+  Psalm 5.0 already deprecates the `TList`, `TNonEmptyList` and `TCallableList` classes: use `\Psalm\Type::getListAtomic`, `\Psalm\Type::getNonEmptyListAtomic` and `\Psalm\Type::getCallableListAtomic` to instantiate list atomics, or directly instantiate TKeyedArray objects with `is_list=true` where appropriate.
+
+- [BC] The only optional boolean parameter of `TKeyedArray::getGenericArrayType` was removed, and will be replaced with a string parameter with a different meaning in Psalm 5.1.
+
 - [BC] Shaped arrays can now be sealed: this brings many assertion improvements and bugfixes, see [the docs for more info](https://psalm.dev/docs/annotating_code/type_syntax/array_types/#sealed-object-like-arrays).
 
 - [BC] All atomic types, `Psalm\Type\Union`, `Psalm\CodeLocation` and storages are fully immutable, use the new setter methods or the new constructors to change properties: these setter methods will return new instances without altering the original instance.  

docs/running_psalm/plugins/plugins_type_system.md

@@ -185,8 +185,6 @@ foreach (range(1,1) as $_) $a[(string)rand(0,1)] = rand(0,1); // array<string,in
 
 `TCallableArray` - denotes an array that is _also_ `callable`.
 
-`TCallableList` - denotes a list that is _also_ `callable`.
-
 `TCallableKeyedArray` - denotes an object-like array that is _also_ `callable`.
 
 `TClassStringMap` - Represents an array where the type of each value is a function of its string key value

psalm-baseline.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<files psalm-version="dev-master@53e3889745852409b704e0035d93e0819d522912">
+<files psalm-version="dev-master@12188caad4b2e4fd7a49a7199e97af2ba1d4c58e">
   <file src="examples/TemplateChecker.php">
     <PossiblyUndefinedIntArrayOffset occurrences="2">
       <code>$comment_block-&gt;tags['variablesfrom'][0]</code>
@@ -72,6 +72,9 @@
     </PossiblyUndefinedIntArrayOffset>
   </file>
   <file src="src/Psalm/Internal/Analyzer/Statements/Expression/AssertionFinder.php">
+    <DeprecatedClass occurrences="1">
+      <code>new Atomic\TList(Type::getMixed())</code>
+    </DeprecatedClass>
     <PossiblyUndefinedIntArrayOffset occurrences="28">
       <code>$assertion-&gt;rule[0]</code>
       <code>$assertion-&gt;rule[0]</code>
@@ -103,6 +106,13 @@
       <code>$gettype_expr-&gt;getArgs()[0]</code>
     </PossiblyUndefinedIntArrayOffset>
   </file>
+  <file src="src/Psalm/Internal/Analyzer/Statements/Expression/Assignment/ArrayAssignmentAnalyzer.php">
+    <DeprecatedClass occurrences="3">
+      <code>$array_atomic_type</code>
+      <code>$array_atomic_type</code>
+      <code>$array_atomic_type</code>
+    </DeprecatedClass>
+  </file>
   <file src="src/Psalm/Internal/Analyzer/Statements/Expression/BinaryOp/ArithmeticOpAnalyzer.php">
     <PossiblyUndefinedIntArrayOffset occurrences="2">
       <code>$invalid_left_messages[0]</code>
@@ -113,18 +123,34 @@
     <ComplexMethod occurrences="1">
       <code>verifyType</code>
     </ComplexMethod>
+    <DeprecatedClass occurrences="4">
+      <code>$array_type</code>
+      <code>$unpacked_atomic_array</code>
+      <code>TKeyedArray|TArray|TClassStringMap</code>
+      <code>TKeyedArray|TArray|TClassStringMap|null</code>
+    </DeprecatedClass>
     <PossiblyUndefinedIntArrayOffset occurrences="3">
       <code>$non_existent_method_ids[0]</code>
       <code>$parts[1]</code>
       <code>explode('::', $cased_method_id)[1]</code>
     </PossiblyUndefinedIntArrayOffset>
   </file>
   <file src="src/Psalm/Internal/Analyzer/Statements/Expression/Call/ArgumentsAnalyzer.php">
+    <DeprecatedClass occurrences="2">
+      <code>$array_type</code>
+      <code>$array_type</code>
+    </DeprecatedClass>
     <PossiblyUndefinedIntArrayOffset occurrences="1">
       <code>$arg_function_params[$argument_offset][0]</code>
     </PossiblyUndefinedIntArrayOffset>
   </file>
   <file src="src/Psalm/Internal/Analyzer/Statements/Expression/Call/ArrayFunctionArgumentsAnalyzer.php">
+    <DeprecatedClass occurrences="4">
+      <code>$array_arg_type</code>
+      <code>$array_type</code>
+      <code>$array_type</code>
+      <code>$replacement_array_type</code>
+    </DeprecatedClass>
     <PossiblyUndefinedIntArrayOffset occurrences="4">
       <code>$args[0]</code>
       <code>$args[0]</code>
@@ -155,6 +181,14 @@
     </PossiblyUndefinedIntArrayOffset>
   </file>
   <file src="src/Psalm/Internal/Analyzer/Statements/Expression/Fetch/ArrayFetchAnalyzer.php">
+    <DeprecatedClass occurrences="6">
+      <code>$array_type</code>
+      <code>$array_type</code>
+      <code>$type</code>
+      <code>$type</code>
+      <code>TArray|TKeyedArray|TClassStringMap</code>
+      <code>TList</code>
+    </DeprecatedClass>
     <ReferenceConstraintViolation occurrences="3">
       <code>$stmt_type</code>
       <code>$stmt_type</code>
@@ -192,6 +226,9 @@
     </PossiblyUndefinedIntArrayOffset>
   </file>
   <file src="src/Psalm/Internal/Codebase/InternalCallMapHandler.php">
+    <DeprecatedClass occurrences="1">
+      <code>$array_atomic_type</code>
+    </DeprecatedClass>
     <PossiblyUndefinedIntArrayOffset occurrences="2">
       <code>$callables[0]</code>
       <code>$callables[0]</code>
@@ -286,6 +323,9 @@
     </RedundantCondition>
   </file>
   <file src="src/Psalm/Internal/PhpVisitor/Reflector/FunctionLikeDocblockScanner.php">
+    <DeprecatedClass occurrences="1">
+      <code>$array_type</code>
+    </DeprecatedClass>
     <PossiblyUndefinedIntArrayOffset occurrences="1">
       <code>$flow_parts[0]</code>
     </PossiblyUndefinedIntArrayOffset>
@@ -300,6 +340,33 @@
       <code>$cs[0]</code>
     </PossiblyUndefinedIntArrayOffset>
   </file>
+  <file src="src/Psalm/Internal/Provider/ReturnTypeProvider/InArrayReturnTypeProvider.php">
+    <DeprecatedClass occurrences="1">
+      <code>$array_arg_type</code>
+    </DeprecatedClass>
+  </file>
+  <file src="src/Psalm/Internal/Scanner/PhpStormMetaScanner.php">
+    <DeprecatedClass occurrences="2">
+      <code>$array_atomic_type</code>
+      <code>$array_atomic_type</code>
+    </DeprecatedClass>
+  </file>
+  <file src="src/Psalm/Internal/Type/Comparator/ArrayTypeComparator.php">
+    <DeprecatedClass occurrences="6">
+      <code>$container_type_part</code>
+      <code>$container_type_part</code>
+      <code>$input_type_part</code>
+      <code>$input_type_part</code>
+      <code>TArray|TKeyedArray|TClassStringMap</code>
+      <code>TArray|TKeyedArray|TClassStringMap</code>
+    </DeprecatedClass>
+  </file>
+  <file src="src/Psalm/Internal/Type/Comparator/AtomicTypeComparator.php">
+    <DeprecatedClass occurrences="2">
+      <code>TList::class</code>
+      <code>TList::class</code>
+    </DeprecatedClass>
+  </file>
   <file src="src/Psalm/Internal/Type/Comparator/CallableTypeComparator.php">
     <LessSpecificReturnStatement occurrences="1">
       <code>$callable</code>
@@ -308,13 +375,19 @@
       <code>TCallable|TClosure|null</code>
     </MoreSpecificReturnType>
   </file>
+  <file src="src/Psalm/Internal/Type/SimpleAssertionReconciler.php">
+    <DeprecatedClass occurrences="3">
+      <code>TList::class</code>
+    </DeprecatedClass>
+  </file>
   <file src="src/Psalm/Internal/Type/TemplateStandinTypeReplacer.php">
     <ImpureMethodCall occurrences="2">
       <code>getClassTemplateTypes</code>
       <code>has</code>
     </ImpureMethodCall>
   </file>
   <file src="src/Psalm/Internal/Type/TypeCombiner.php">
+    <DeprecatedClass occurrences="1"/>
     <PossiblyUndefinedIntArrayOffset occurrences="6">
       <code>$combination-&gt;array_type_params[1]</code>
       <code>$combination-&gt;array_type_params[1]</code>
@@ -349,6 +422,13 @@
       <code>traverse</code>
     </ImpureMethodCall>
   </file>
+  <file src="src/Psalm/Type.php">
+    <DeprecatedClass occurrences="3">
+      <code>new TCallableList($of, null, null, $from_docblock)</code>
+      <code>new TList($of, $from_docblock)</code>
+      <code>new TNonEmptyList($of, null, null, $from_docblock)</code>
+    </DeprecatedClass>
+  </file>
   <file src="src/Psalm/Type/Atomic.php">
     <ImpureMethodCall occurrences="12">
       <code>classExtendsOrImplements</code>
@@ -394,6 +474,11 @@
       <code>getMostSpecificTypeFromBounds</code>
     </ImpureMethodCall>
   </file>
+  <file src="src/Psalm/Type/Atomic/TCallableList.php">
+    <DeprecatedClass occurrences="1">
+      <code>TNonEmptyList</code>
+    </DeprecatedClass>
+  </file>
   <file src="src/Psalm/Type/Atomic/TClassString.php">
     <ImpureMethodCall occurrences="1">
       <code>replace</code>
@@ -441,6 +526,11 @@
       <code>$cloned-&gt;type_param</code>
     </ImpurePropertyAssignment>
   </file>
+  <file src="src/Psalm/Type/Atomic/TNonEmptyList.php">
+    <DeprecatedClass occurrences="1">
+      <code>TList</code>
+    </DeprecatedClass>
+  </file>
   <file src="src/Psalm/Type/Atomic/TObjectWithProperties.php">
     <ImpureMethodCall occurrences="2">
       <code>replace</code>
@@ -506,6 +596,11 @@
       <code>allFloatLiterals</code>
     </PossiblyUnusedMethod>
   </file>
+  <file src="tests/Config/Plugin/Hook/CustomArrayMapFunctionStorageProvider.php">
+    <DeprecatedClass occurrences="1">
+      <code>new Type\Atomic\TList($last_callable_arg-&gt;return_type ?? Type::getMixed())</code>
+    </DeprecatedClass>
+  </file>
   <file src="tests/Internal/Codebase/InternalCallMapHandlerTest.php">
     <UnusedPsalmSuppress occurrences="1">
       <code>UndefinedMethod</code>

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

@@ -13,7 +13,6 @@
 use Psalm\Type\Atomic\TGenericObject;
 use Psalm\Type\Atomic\TIterable;
 use Psalm\Type\Atomic\TKeyedArray;
-use Psalm\Type\Atomic\TList;
 use Psalm\Type\Atomic\TNamedObject;
 use Psalm\Type\Union;
 
@@ -263,10 +262,6 @@ private static function processYieldTypes(
                 $type = $type->getGenericArrayType();
             }
 
-            if ($type instanceof TList) {
-                $type = new TArray([Type::getInt(), $type->type_param]);
-            }
-
             if ($type instanceof TArray) {
                 [$key_type_param, $value_type_param] = $type->type_params;
 

src/Psalm/Internal/Analyzer/FunctionLikeAnalyzer.php

@@ -54,7 +54,6 @@
 use Psalm\Type\Atomic\TArray;
 use Psalm\Type\Atomic\TClosure;
 use Psalm\Type\Atomic\TGenericObject;
-use Psalm\Type\Atomic\TList;
 use Psalm\Type\Atomic\TMixed;
 use Psalm\Type\Atomic\TNamedObject;
 use Psalm\Type\Atomic\TTemplateParam;
@@ -1161,7 +1160,7 @@ private function processParams(
                     ]);
                 } else {
                     $var_type = new Union([
-                        new TList($param_type),
+                        Type::getListAtomic($param_type),
                     ], [
                         'by_ref' => $function_param->by_ref,
                         'parent_nodes' => $parent_nodes

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

@@ -40,18 +40,14 @@
 use Psalm\Type\Atomic;
 use Psalm\Type\Atomic\Scalar;
 use Psalm\Type\Atomic\TArray;
-use Psalm\Type\Atomic\TDependentListKey;
 use Psalm\Type\Atomic\TFalse;
 use Psalm\Type\Atomic\TGenericObject;
-use Psalm\Type\Atomic\TIntRange;
 use Psalm\Type\Atomic\TIterable;
 use Psalm\Type\Atomic\TKeyedArray;
-use Psalm\Type\Atomic\TList;
 use Psalm\Type\Atomic\TMixed;
 use Psalm\Type\Atomic\TNamedObject;
 use Psalm\Type\Atomic\TNever;
 use Psalm\Type\Atomic\TNonEmptyArray;
-use Psalm\Type\Atomic\TNonEmptyList;
 use Psalm\Type\Atomic\TNull;
 use Psalm\Type\Atomic\TObject;
 use Psalm\Type\Atomic\TObjectWithProperties;
@@ -390,8 +386,6 @@ public static function analyze(
     /**
      * @param PhpParser\Node\Stmt\Foreach_|PhpParser\Node\Expr\YieldFrom $stmt
      *
-     * @psalm-suppress ComplexMethod
-     *
      * @return false|null
      */
     public static function checkIteratorType(
@@ -467,43 +461,19 @@ public static function checkIteratorType(
 
             if ($iterator_atomic_type instanceof TArray
                 || $iterator_atomic_type instanceof TKeyedArray
-                || $iterator_atomic_type instanceof TList
             ) {
                 if ($iterator_atomic_type instanceof TKeyedArray) {
-                    if ($iterator_atomic_type->fallback_params === null) {
-                        $all_possibly_undefined = true;
-                        foreach ($iterator_atomic_type->properties as $prop) {
-                            if (!$prop->possibly_undefined) {
-                                $all_possibly_undefined = false;
-                                break;
-                            }
-                        }
-                        if ($all_possibly_undefined) {
-                            $always_non_empty_array = false;
-                        }
-                    } else {
-                        $always_non_empty_array = false;
-                    }
-                    $iterator_atomic_type = $iterator_atomic_type->getGenericArrayType();
-                } elseif ($iterator_atomic_type instanceof TList) {
-                    $list_var_id = ExpressionIdentifier::getExtendedVarId(
-                        $expr,
-                        $statements_analyzer->getFQCLN(),
-                        $statements_analyzer
-                    );
-
-                    if (!$iterator_atomic_type instanceof TNonEmptyList) {
+                    if (!$iterator_atomic_type->isNonEmpty()) {
                         $always_non_empty_array = false;
                     }
 
-                    $iterator_atomic_type = new TArray([
-                        $list_var_id
-                            ? new Union([
-                                new TDependentListKey($list_var_id)
-                            ])
-                            : new Union([new TIntRange(0, null)]),
-                        $iterator_atomic_type->type_param
-                    ]);
+                    $iterator_atomic_type = $iterator_atomic_type->getGenericArrayType(
+                        ExpressionIdentifier::getExtendedVarId(
+                            $expr,
+                            $statements_analyzer->getFQCLN(),
+                            $statements_analyzer
+                        )
+                    );
                 } elseif (!$iterator_atomic_type instanceof TNonEmptyArray) {
                     $always_non_empty_array = false;
                 }

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

@@ -29,14 +29,12 @@
 use Psalm\Type\Atomic\TFloat;
 use Psalm\Type\Atomic\TInt;
 use Psalm\Type\Atomic\TKeyedArray;
-use Psalm\Type\Atomic\TList;
 use Psalm\Type\Atomic\TLiteralClassString;
 use Psalm\Type\Atomic\TLiteralFloat;
 use Psalm\Type\Atomic\TLiteralInt;
 use Psalm\Type\Atomic\TLiteralString;
 use Psalm\Type\Atomic\TMixed;
 use Psalm\Type\Atomic\TNonEmptyArray;
-use Psalm\Type\Atomic\TNonEmptyList;
 use Psalm\Type\Atomic\TObjectWithProperties;
 use Psalm\Type\Atomic\TString;
 use Psalm\Type\Atomic\TTemplateParam;
@@ -146,9 +144,9 @@ public static function analyze(
 
         if ($array_creation_info->all_list) {
             if ($array_creation_info->can_be_empty) {
-                $array_type = new TList($item_value_type ?? Type::getMixed());
+                $array_type = Type::getListAtomic($item_value_type ?? Type::getMixed());
             } else {
-                $array_type = new TNonEmptyList($item_value_type ?? Type::getMixed());
+                $array_type = Type::getNonEmptyListAtomic($item_value_type ?? Type::getMixed());
             }
 
             $stmt_type = new Union([
@@ -552,7 +550,7 @@ private static function handleUnpackedArray(
             } else {
                 $codebase = $statements_analyzer->getCodebase();
 
-                if (!$unpacked_atomic_type instanceof TNonEmptyList
+                if (!($unpacked_atomic_type instanceof TKeyedArray && $unpacked_atomic_type->isNonEmpty())
                     && !$unpacked_atomic_type instanceof TNonEmptyArray
                 ) {
                     $all_non_empty = false;