Merge pull request #12077 from danog/purity-template-arg-count

Purity templates: omitted purity arguments, instanceof narrowing, inference of templated calls

Author: danog

src/Psalm/Internal/Analyzer/Statements/Expression/Call/Method/MethodCallPurityAnalyzer.php

@@ -149,16 +149,17 @@ public static function analyze(
 
         // @psalm-purity-from-template: the call also needs the capabilities of the closures the
         // templates are bound to here; this can only make the call less pure, never more
-        $method_capabilities = CallPurityResolver::getCallCapabilities(
+        $template_capabilities = CallPurityResolver::getCallCapabilities(
             $statements_analyzer,
             $codebase,
             $method_storage,
-            $method_capabilities,
+            Capabilities::NONE,
             $template_result,
             $class_template_params,
             self::isThis($stmt->var),
             self::isFromGlobalState($statements_analyzer, $stmt->var),
         );
+        $method_capabilities |= $template_capabilities;
 
         // whether the result may come from global state depends on what this call reads,
         // not on what it writes through its by-reference arguments
@@ -199,6 +200,11 @@ public static function analyze(
             self::receiverAllowsInternalMutations($statements_analyzer, $stmt->var),
         );
 
+        // the callee's level does not include what its purity templates are bound to here
+        if ($template_capabilities !== Capabilities::NONE) {
+            $statements_analyzer->signalMutationOnlyInferred($template_capabilities);
+        }
+
         if ($reads_globals) {
             $stmt->setAttribute(GlobalStateAnalyzer::ATTRIBUTE, true);
         }
@@ -251,6 +257,7 @@ public static function analyze(
                     && !$method_storage->throws
                     && !$method_storage->return_type?->isNever()
                     && !$method_storage->signature_return_type?->isNever()
+                    && !self::isCalledForItsTemplatesEffects($method_storage)
                 ) {
                     IssueBuffer::maybeAdd(
                         new UnusedMethodCall(
@@ -319,4 +326,18 @@ public static function analyze(
             }
         }
     }
+
+    /**
+     * A void method whose purity comes from purity templates (`Iterator::next()`) is called for the
+     * effects of what they are bound to, or of its own engine state (the cursor of an iterator):
+     * its call is not unused even when they turn out to be none.
+     *
+     * @psalm-mutation-free
+     */
+    public static function isCalledForItsTemplatesEffects(MethodStorage $method_storage): bool
+    {
+        return $method_storage->purity_from_templates !== []
+            && ($method_storage->return_type?->isVoid() === true
+                || $method_storage->signature_return_type?->isVoid() === true);
+    }
 }

src/Psalm/Internal/Analyzer/Statements/Expression/Call/NewAnalyzer.php

@@ -836,13 +836,15 @@ private static function analyzeConstructorPurity(
         $cased_method_id = 'constructor ' . $codebase->methods->getCasedMethodId($declaring_method_id);
 
         // the constructor only mutates the new object: what it does to it is fine
-        $resolved_capabilities = CallPurityResolver::getCallCapabilities(
+        $template_capabilities = CallPurityResolver::getCallCapabilities(
             $statements_analyzer,
             $codebase,
             $method_storage,
-            $method_storage->capabilities & ~(Capabilities::READ_PROPS | Capabilities::WRITE_THIS_PROPS),
+            Capabilities::NONE,
             $template_result,
         );
+        $resolved_capabilities = $template_capabilities
+            | ($method_storage->capabilities & ~(Capabilities::READ_PROPS | Capabilities::WRITE_THIS_PROPS));
 
         $args = $stmt->getArgs();
 
@@ -868,6 +870,11 @@ private static function analyzeConstructorPurity(
             true,
         );
 
+        // the constructor's level does not include what its purity templates are bound to here
+        if ($template_capabilities !== Capabilities::NONE) {
+            $statements_analyzer->signalMutationOnlyInferred($template_capabilities);
+        }
+
         // the constructor may have stored global state in the new object: what it reads, not
         // what it writes through its by-reference arguments
         if (($resolved_capabilities & Capabilities::READ_GLOBALS) !== 0) {

src/Psalm/Internal/Analyzer/Statements/Expression/Call/StaticMethod/ExistingAtomicStaticCallAnalyzer.php

@@ -295,14 +295,16 @@ public static function analyze(
 
             $call_args = $stmt->isFirstClassCallable() ? [] : $stmt->getArgs();
 
-            $resolved_capabilities = CallPurityResolver::getCallCapabilities(
+            // what the purity templates of the method are bound to here
+            $template_capabilities = CallPurityResolver::getCallCapabilities(
                 $statements_analyzer,
                 $codebase,
                 $method_storage,
-                $method_storage->capabilities,
+                Capabilities::NONE,
                 $template_result,
                 $found_generic_params ?? [],
             );
+            $resolved_capabilities = $method_storage->capabilities | $template_capabilities;
 
             $call_capabilities = ByRefArgumentAnalyzer::adjustCapabilities(
                 $statements_analyzer,
@@ -329,6 +331,11 @@ public static function analyze(
                 $method_storage,
             );
 
+            // the callee's level does not include what its purity templates are bound to here
+            if ($template_capabilities !== Capabilities::NONE) {
+                $statements_analyzer->signalMutationOnlyInferred($template_capabilities);
+            }
+
             // what this call reads, not what it writes through its by-reference arguments
             if (($resolved_capabilities & Capabilities::READ_GLOBALS) !== 0) {
                 $stmt->setAttribute(GlobalStateAnalyzer::ATTRIBUTE, true);

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

@@ -585,6 +585,12 @@ public function start(PhpParser\Node\Stmt\ClassLike $node): ?bool
                     }
 
                     if (!isset($docblock_info->purity_template_defaults[$purity_template])) {
+                        // without a default, a purity argument left out (`Box`) stands for the
+                        // template's upper bound
+                        if ($bound !== null && Capabilities::isPurityType($bound)) {
+                            $storage->template_defaults[$purity_template] = $bound;
+                        }
+
                         continue;
                     }
 

src/Psalm/Internal/Type/AssertionReconciler.php

@@ -65,7 +65,9 @@
 use Psalm\Type\Union;
 
 use function array_intersect_key;
+use function array_keys;
 use function array_merge;
+use function array_search;
 use function count;
 use function is_string;
 
@@ -435,7 +437,19 @@ private static function refine(
                     && ($codebase->classExists($existing_var_type_part->value)
                         || $codebase->interfaceExists($existing_var_type_part->value))
                 ) {
-                    $existing_var_type_part = $existing_var_type_part->addIntersectionType($new_type_part);
+                    $intersected_type_part = $new_type_part;
+
+                    if ($existing_var_type_part instanceof TGenericObject
+                        && !$new_type_part instanceof TGenericObject
+                    ) {
+                        $intersected_type_part = self::inferTemplateParamsFromParent(
+                            $codebase,
+                            $new_type_part,
+                            $existing_var_type_part,
+                        );
+                    }
+
+                    $existing_var_type_part = $existing_var_type_part->addIntersectionType($intersected_type_part);
                     $acceptable_atomic_types[] = $existing_var_type_part;
                 }
 
@@ -598,6 +612,80 @@ private static function filterTypeWithAnother(
         return null;
     }
 
+    /**
+     * Narrowing a `Parent` to a child class whose templates are passed straight to Parent's
+     * (`@extends Parent`, `@implements Iterator[P]`) gives the child those arguments:
+     * `Iterator[pure]` narrowed to `Child` is a `Child[pure]`.
+     *
+     * @psalm-capabilities read-props
+     */
+    private static function inferTemplateParamsFromParent(
+        Codebase $codebase,
+        TNamedObject $child,
+        TGenericObject $parent,
+    ): TNamedObject {
+        if (!$codebase->classlike_storage_provider->has($child->value)
+            || !$codebase->classlike_storage_provider->has($parent->value)
+        ) {
+            return $child;
+        }
+
+        $child_storage = $codebase->classlike_storage_provider->get($child->value);
+        $parent_storage = $codebase->classlike_storage_provider->get($parent->value);
+
+        $extended_params = $child_storage->template_extended_params[$parent_storage->name] ?? null;
+
+        if ($child_storage->template_types === null
+            || $child_storage->template_types === []
+            || $parent_storage->template_types === null
+            || $parent_storage->template_types === []
+            || $extended_params === null
+        ) {
+            return $child;
+        }
+
+        $parent_template_names = array_keys($parent_storage->template_types);
+        $type_params = [];
+
+        foreach (array_keys($child_storage->template_types) as $template_name) {
+            $inferred = null;
+
+            foreach ($extended_params as $parent_template_name => $extended_type) {
+                $offset = array_search($parent_template_name, $parent_template_names, true);
+
+                if ($offset === false || !isset($parent->type_params[$offset]) || !$extended_type->isSingle()) {
+                    continue;
+                }
+
+                $extended_atomic = $extended_type->getSingleAtomic();
+
+                if ($extended_atomic instanceof TTemplateParam
+                    && $extended_atomic->param_name === $template_name
+                    && $extended_atomic->defining_class === $child_storage->name
+                ) {
+                    $inferred = $parent->type_params[$offset];
+                    break;
+                }
+            }
+
+            if ($inferred === null) {
+                // a template not passed straight to the parent: nothing is known about it
+                return $child;
+            }
+
+            $type_params[] = $inferred;
+        }
+
+        return new TGenericObject(
+            $child->value,
+            $type_params,
+            false,
+            $child->is_static,
+            $child->extra_types,
+            $child->from_docblock,
+        );
+    }
+
     private static function filterAtomicWithAnother(
         Atomic &$type_1_atomic,
         Atomic $type_2_atomic,
@@ -662,6 +750,10 @@ private static function filterAtomicWithAnother(
             && ($codebase->interfaceExists($type_1_atomic->value)
                 || $codebase->interfaceExists($type_2_atomic->value))
         ) {
+            if ($type_1_atomic instanceof TGenericObject && !$type_2_atomic instanceof TGenericObject) {
+                $type_2_atomic = self::inferTemplateParamsFromParent($codebase, $type_2_atomic, $type_1_atomic);
+            }
+
             return $type_2_atomic->addIntersectionType($type_1_atomic);
         }
 

src/Psalm/Internal/Type/PurityArguments.php

@@ -78,6 +78,23 @@ public static function fit(array $type_params, ClassLikeStorage $storage): bool
             && count($purity_args) <= count($storage->template_types ?? []) - $type_template_count;
     }
 
+    /**
+     * The type parameters of a use of the class without the purity arguments it has no purity
+     * templates for: what `static[P]` becomes for a late static class that binds `P` itself
+     * (`@extends Base[pure]`) and so declares no purity template of its own.
+     *
+     * @param array $type_params
+     * @return list
+     * @psalm-mutation-free
+     */
+    public static function trim(array $type_params, ClassLikeStorage $storage): array
+    {
+        [$type_args, $purity_args] = self::split($type_params);
+        $purity_template_count = count($storage->template_types ?? []) - self::countTypeTemplates($storage);
+
+        return [...$type_args, ...array_slice($purity_args, 0, $purity_template_count)];
+    }
+
     /**
      * The type parameters of a use of the class, with the purity arguments in the positions of the
      * purity templates: `Foo[pure]`, for a class with type templates, gives them their bounds.

src/Psalm/Internal/Type/TypeExpander.php

@@ -693,6 +693,17 @@ private static function expandNamedObject(
                         $is_static,
                         $is_static_resolved,
                     );
+
+                    if ($codebase->classlike_storage_provider->has($static_class_type->value)) {
+                        $type_params = PurityArguments::trim(
+                            $return_type->type_params,
+                            $codebase->classlike_storage_provider->get($static_class_type->value),
+                        );
+
+                        if ($type_params !== [] && count($type_params) !== count($return_type->type_params)) {
+                            $return_type = $return_type->setTypeParams($type_params);
+                        }
+                    }
                 } elseif ($static_class_type instanceof TNamedObject) {
                     $return_type = $static_class_type->setIsStatic(
                         $is_static,

tests/FileManipulation/PureAnnotationAdditionTest.php

@@ -262,6 +262,49 @@ public function hook(): int {
                 'issues_to_fix' => ['MissingPureAnnotation'],
                 'safe_types' => true,
             ],
+            'dontSuggestWhatAClassBoundPurityTemplateExceeds' => [
+                'input' => '
+                    /**
+                     * @psalm-purity-template P
+                     */
+                    abstract class Base {
+                        /**
+                         * @psalm-capabilities read-props
+                         * @psalm-purity-from-template P
+                         */
+                        public function limit(): int {
+                            return 1;
+                        }
+                    }
+
+                    final class Db extends Base {
+                        public function limit(): int {
+                            return parent::limit() + 1;
+                        }
+                    }',
+                'output' => '
+                    /**
+                     * @psalm-purity-template P
+                     */
+                    abstract class Base {
+                        /**
+                         * @psalm-capabilities read-props
+                         * @psalm-purity-from-template P
+                         */
+                        public function limit(): int {
+                            return 1;
+                        }
+                    }
+
+                    final class Db extends Base {
+                        public function limit(): int {
+                            return parent::limit() + 1;
+                        }
+                    }',
+                'php_version' => '8.1',
+                'issues_to_fix' => ['MissingPureAnnotation'],
+                'safe_types' => true,
+            ],
             'addPureAnnotationToFunction' => [
                 'input' => '
                     function foo(string $s): string {