Report what a function assigns that its @var tag does not accept

The tag above `$x = null`, `$x = []`, a scalar, `new Foo()` or `static $x`
declares the type of the variable, so every write to it after the
declaration must leave it a subtype of the tag. The error is reported on
the line of the write - `$a[] = 'foo'`, `$s .= 'x'`, `$n++`,
`$l[50] = 1` on a list, `[$d] = ['x']` - and, for a generic `new` whose
template arguments the body infers differently, on the declaration.
Template arguments are compared both generalized like inferred ones and
precise - a tag more precise than the generalization (Collection<true>) is
fine - and one nothing in the body constrains is unknown.

The check follows the rule level through the new
RuleLevelHelper::isSuperTypeOf(), the accepts() counterpart: an assigned
type the tag is maybe a supertype of is reported from level 7 on (unions),
and a type holding `mixed` or a benevolent union the level does not check
yet is judged like accepts() judges it - `mixed` fits anywhere, a
benevolent union where one of its members does.

The @var tag over the two-pass driver's statement entries declared a list,
but the entries are keyed by the statement list's keys.

Closes phpstan/phpstan#14198

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VpbB99tJfUmeArX74xqvHv
Amp-Thread-ID: https://ampcode.com/threads/T-01a19219-4619-76d7-89f1-3dc38b076ad6

Author: ondrejmirtes

conf/config.level2.neon

@@ -19,6 +19,8 @@ conditionalTags:
 		phpstan.rules.rule: %featureToggles.checkDynamicConstantNameValues%
 	PHPStan\Rules\Constants\ValueAssignedToGlobalConstantRule:
 		phpstan.rules.rule: %featureToggles.checkDynamicConstantNameValues%
+	PHPStan\Rules\PhpDoc\VarTagReflectsUsagesRule:
+		phpstan.rules.rule: %featureToggles.varTagsReflectUsages%
 
 services:
 	-
@@ -32,3 +34,6 @@ services:
 
 	-
 		class: PHPStan\Rules\Constants\ValueAssignedToGlobalConstantRule
+
+	-
+		class: PHPStan\Rules\PhpDoc\VarTagReflectsUsagesRule

src/Analyser/StatementsHandler.php

@@ -813,7 +813,7 @@ private function processBodyStmtNodesTwoPass(
 		$scope = $scope->withTemplateArgumentFrame($frame)->withTemplateArgumentConstraints(null);
 		$recording = new RecordingNodeCallback();
 		$state = new StatementListWalkState($scope);
-		/** @var list<array{StatementListWalkState, int}> $entries the state and recording offset before each statement, plus the final ones */
+		/** @var array<int, array{StatementListWalkState, int}> $entries the state and recording offset before each statement, plus the final ones */
 		$entries = [];
 		$observationContext = $context->withoutTemplateArgumentResolution();
 		$suspendedGatherers = $nodeScopeResolver->suspendNodeGatherers();

src/Rules/PhpDoc/VarTagReflectsUsagesRule.php

@@ -0,0 +1,77 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\PhpDoc;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\Node\VarTagUsagesNode;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\Rules\RuleLevelHelper;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use PHPStan\Type\TypeUtils;
+use PHPStan\Type\VerbosityLevel;
+use function sprintf;
+
+/**
+ * A `@var` tag over `$x = null`, `$x = []`, a scalar, a `new` of a generic
+ * class or `static $x` declares what the variable holds in the rest of the
+ * function. A write that makes the variable hold something the tag does not
+ * accept - `$x[] = <element of another type>`, `$x .= ...`, `$x++` - and a
+ * template argument the body infers differently are reported.
+ *
+ * @implements Rule<VarTagUsagesNode>
+ */
+final class VarTagReflectsUsagesRule implements Rule
+{
+
+	public function __construct(private RuleLevelHelper $ruleLevelHelper)
+	{
+	}
+
+	public function getNodeType(): string
+	{
+		return VarTagUsagesNode::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		$varTagType = $node->getVarTagType();
+		$rejected = $this->getRejectedTypes($varTagType, $node->getAssignedType());
+		// a tag more precise than the generalized inferred template arguments
+		// (Collection<true>) is fine when it accepts the precise ones
+		if ($rejected === [] || $this->getRejectedTypes($varTagType, $node->getPreciseAssignedType()) === []) {
+			return [];
+		}
+		$usagesType = TypeCombinator::union(...$rejected);
+
+		$verbosity = VerbosityLevel::getRecommendedLevelByType($varTagType, $usagesType);
+
+		return [
+			RuleErrorBuilder::message(sprintf(
+				'PHPDoc tag @var with type %s does not accept type %s assigned to $%s.',
+				$varTagType->describe($verbosity),
+				$usagesType->describe($verbosity),
+				$node->getVariableName(),
+			))->identifier('varTag.usages')->build(),
+		];
+	}
+
+	/**
+	 * @return list<Type>
+	 */
+	private function getRejectedTypes(Type $varTagType, Type $assignedType): array
+	{
+		$rejected = [];
+		foreach (TypeUtils::flattenTypes($assignedType) as $type) {
+			if ($this->ruleLevelHelper->isSuperTypeOf($varTagType, $type)->result) {
+				continue;
+			}
+			$rejected[] = $type;
+		}
+
+		return $rejected;
+	}
+
+}

src/Rules/RuleLevelHelper.php

@@ -253,6 +253,56 @@ public function accepts(Type $acceptingType, Type $acceptedType, bool $strictTyp
 		);
 	}
 
+	/**
+	 * accepts() for a relationship accepts() does not describe - whether the
+	 * values of $subType fit into $superType, e.g. what a declared type must
+	 * hold - with the same rule level: nullables and unions are checked from
+	 * their levels on, and `mixed` and benevolent unions the level does not
+	 * check yet fit.
+	 *
+	 * @api
+	 */
+	public function isSuperTypeOf(Type $superType, Type $subType): RuleLevelHelperAcceptsResult
+	{
+		[$subType, $checkForUnion] = $this->transformAcceptedType($superType, $subType);
+		$superType = $this->transformCommonType($superType);
+
+		$isSuperType = $superType->isSuperTypeOf($subType);
+		if (!$isSuperType->yes() && $this->containsUncheckedType($subType)) {
+			// the level lets them in like accepts() does - `mixed` fits
+			// anywhere, a benevolent union where one of its members does
+			$accepts = $superType->accepts($subType, true);
+
+			return new RuleLevelHelperAcceptsResult(
+				$checkForUnion ? $accepts->yes() : !$accepts->no(),
+				$accepts->reasons,
+			);
+		}
+
+		return new RuleLevelHelperAcceptsResult(
+			$checkForUnion ? $isSuperType->yes() : !$isSuperType->no(),
+			$isSuperType->reasons,
+		);
+	}
+
+	/**
+	 * The `mixed` transformCommonType() left as it is (checked mixed became
+	 * StrictMixedType) and the benevolent unions transformAcceptedType() did.
+	 */
+	private function containsUncheckedType(Type $type): bool
+	{
+		$contains = false;
+		TypeTraverser::map($type, function (Type $type, callable $traverse) use (&$contains): Type {
+			if ($type instanceof MixedType || ($type instanceof BenevolentUnionType && !$this->checkBenevolentUnionTypes)) {
+				$contains = true;
+			}
+
+			return $contains ? $type : $traverse($type);
+		});
+
+		return $contains;
+	}
+
 	/**
 	 * @api
 	 * @param callable(Type $type): bool $unionTypeCriteriaCallback