enforce required generic params

shmax · shmax · commit 56e8cfb292e5 · 2026-04-01T14:19:51.000-07:00
diff --git a/src/Rules/Classes/LocalTypeAliasesCheck.php b/src/Rules/Classes/LocalTypeAliasesCheck.php
@@ -221,6 +221,22 @@ public function checkInTraitDefinitionContext(ClassReflection $reflection): arra
 					->build();
 			}
 
+			foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($resolvedType) as [$innerAliasName, $missingParams]) {
+				if ($innerAliasName === $aliasName) {
+					continue; // alias body contains its own template type placeholders — not a raw usage
+				}
+				$errors[] = RuleErrorBuilder::message(sprintf(
+					'%s %s has type alias %s with generic type alias %s but does not specify its types: %s',
+					$reflection->getClassTypeDescription(),
+					$reflection->getDisplayName(),
+					$aliasName,
+					$innerAliasName,
+					$missingParams,
+				))
+					->identifier('missingType.generics')
+					->build();
+			}
+
 			foreach ($this->missingTypehintCheck->getCallablesWithMissingSignature($resolvedType) as $callableType) {
 				$errors[] = RuleErrorBuilder::message(sprintf(
 					'%s %s has type alias %s with no signature specified for %s.',
diff --git a/src/Rules/Classes/MethodTagCheck.php b/src/Rules/Classes/MethodTagCheck.php
@@ -190,6 +190,19 @@ private function checkMethodTypeInTraitDefinitionContext(ClassReflection $classR
 				->build();
 		}
 
+		foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($type) as [$aliasName, $missingParams]) {
+			$errors[] = RuleErrorBuilder::message(sprintf(
+				'PHPDoc tag @method for method %s::%s() %s contains generic type alias %s but does not specify its types: %s',
+				$classReflection->getDisplayName(),
+				$methodName,
+				$description,
+				$aliasName,
+				$missingParams,
+			))
+				->identifier('missingType.generics')
+				->build();
+		}
+
 		foreach ($this->missingTypehintCheck->getIterableTypesWithMissingValueTypehint($type) as $iterableType) {
 			$iterableTypeDescription = $iterableType->describe(VerbosityLevel::typeOnly());
 			$errors[] = RuleErrorBuilder::message(sprintf(
diff --git a/src/Rules/Classes/MixinCheck.php b/src/Rules/Classes/MixinCheck.php
@@ -99,6 +99,16 @@ public function checkInTraitDefinitionContext(ClassReflection $classReflection):
 					->build();
 			}
 
+			foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($type) as [$aliasName, $missingParams]) {
+				$errors[] = RuleErrorBuilder::message(sprintf(
+					'PHPDoc tag @mixin contains generic type alias %s but does not specify its types: %s',
+					$aliasName,
+					$missingParams,
+				))
+					->identifier('missingType.generics')
+					->build();
+			}
+
 			foreach ($this->missingTypehintCheck->getCallablesWithMissingSignature($type) as $callableType) {
 				$errors[] = RuleErrorBuilder::message(sprintf(
 					'%s %s has PHPDoc tag @mixin with no signature specified for %s.',
diff --git a/src/Rules/Classes/PropertyTagCheck.php b/src/Rules/Classes/PropertyTagCheck.php
@@ -171,6 +171,19 @@ private function checkPropertyTypeInTraitDefinitionContext(ClassReflection $clas
 				->build();
 		}
 
+		foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($type) as [$aliasName, $missingParams]) {
+			$errors[] = RuleErrorBuilder::message(sprintf(
+				'PHPDoc tag %s for property %s::$%s contains generic type alias %s but does not specify its types: %s',
+				$tagName,
+				$classReflection->getDisplayName(),
+				$propertyName,
+				$aliasName,
+				$missingParams,
+			))
+				->identifier('missingType.generics')
+				->build();
+		}
+
 		foreach ($this->missingTypehintCheck->getIterableTypesWithMissingValueTypehint($type) as $iterableType) {
 			$iterableTypeDescription = $iterableType->describe(VerbosityLevel::typeOnly());
 			$errors[] = RuleErrorBuilder::message(sprintf(
diff --git a/src/Rules/Constants/MissingClassConstantTypehintRule.php b/src/Rules/Constants/MissingClassConstantTypehintRule.php
@@ -83,6 +83,18 @@ private function processSingleConstant(ClassReflection $classReflection, string
 				->build();
 		}
 
+		foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($constantType) as [$aliasName, $missingParams]) {
+			$errors[] = RuleErrorBuilder::message(sprintf(
+				'Constant %s::%s with generic type alias %s does not specify its types: %s',
+				$constantReflection->getDeclaringClass()->getDisplayName(),
+				$constantName,
+				$aliasName,
+				$missingParams,
+			))
+				->identifier('missingType.generics')
+				->build();
+		}
+
 		foreach ($this->missingTypehintCheck->getCallablesWithMissingSignature($constantType) as $callableType) {
 			$errors[] = RuleErrorBuilder::message(sprintf(
 				'Constant %s::%s type has no signature specified for %s.',
diff --git a/src/Rules/Functions/MissingFunctionParameterTypehintRule.php b/src/Rules/Functions/MissingFunctionParameterTypehintRule.php
@@ -105,6 +105,18 @@ private function checkFunctionParameter(FunctionReflection $functionReflection,
 				->build();
 		}
 
+		foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($parameterType) as [$aliasName, $missingParams]) {
+			$messages[] = RuleErrorBuilder::message(sprintf(
+				'Function %s() has %s with generic type alias %s but does not specify its types: %s',
+				$functionReflection->getName(),
+				$parameterMessage,
+				$aliasName,
+				$missingParams,
+			))
+				->identifier('missingType.generics')
+				->build();
+		}
+
 		foreach ($this->missingTypehintCheck->getCallablesWithMissingSignature($parameterType) as $callableType) {
 			$messages[] = RuleErrorBuilder::message(sprintf(
 				'Function %s() has %s with no signature specified for %s.',
diff --git a/src/Rules/Functions/MissingFunctionReturnTypehintRule.php b/src/Rules/Functions/MissingFunctionReturnTypehintRule.php
@@ -67,6 +67,17 @@ public function processNode(Node $node, Scope $scope): array
 				->build();
 		}
 
+		foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($returnType) as [$aliasName, $missingParams]) {
+			$messages[] = RuleErrorBuilder::message(sprintf(
+				'Function %s() return type with generic type alias %s does not specify its types: %s',
+				$functionReflection->getName(),
+				$aliasName,
+				$missingParams,
+			))
+				->identifier('missingType.generics')
+				->build();
+		}
+
 		foreach ($this->missingTypehintCheck->getCallablesWithMissingSignature($returnType) as $callableType) {
 			$messages[] = RuleErrorBuilder::message(sprintf(
 				'Function %s() return type has no signature specified for %s.',
diff --git a/src/Rules/Methods/MissingMethodParameterTypehintRule.php b/src/Rules/Methods/MissingMethodParameterTypehintRule.php
@@ -108,6 +108,19 @@ private function checkMethodParameter(MethodReflection $methodReflection, string
 				->build();
 		}
 
+		foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($parameterType) as [$aliasName, $missingParams]) {
+			$messages[] = RuleErrorBuilder::message(sprintf(
+				'Method %s::%s() has %s with generic type alias %s but does not specify its types: %s',
+				$methodReflection->getDeclaringClass()->getDisplayName(),
+				$methodReflection->getName(),
+				$parameterMessage,
+				$aliasName,
+				$missingParams,
+			))
+				->identifier('missingType.generics')
+				->build();
+		}
+
 		foreach ($this->missingTypehintCheck->getCallablesWithMissingSignature($parameterType) as $callableType) {
 			$messages[] = RuleErrorBuilder::message(sprintf(
 				'Method %s::%s() has %s with no signature specified for %s.',
diff --git a/src/Rules/Methods/MissingMethodReturnTypehintRule.php b/src/Rules/Methods/MissingMethodReturnTypehintRule.php
@@ -79,6 +79,18 @@ public function processNode(Node $node, Scope $scope): array
 				->build();
 		}
 
+		foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($returnType) as [$aliasName, $missingParams]) {
+			$messages[] = RuleErrorBuilder::message(sprintf(
+				'Method %s::%s() return type with generic type alias %s does not specify its types: %s',
+				$methodReflection->getDeclaringClass()->getDisplayName(),
+				$methodReflection->getName(),
+				$aliasName,
+				$missingParams,
+			))
+				->identifier('missingType.generics')
+				->build();
+		}
+
 		foreach ($this->missingTypehintCheck->getCallablesWithMissingSignature($returnType) as $callableType) {
 			$messages[] = RuleErrorBuilder::message(sprintf(
 				'Method %s::%s() return type has no signature specified for %s.',
diff --git a/src/Rules/Methods/MissingMethodSelfOutTypeRule.php b/src/Rules/Methods/MissingMethodSelfOutTypeRule.php
@@ -72,6 +72,19 @@ public function processNode(Node $node, Scope $scope): array
 				->build();
 		}
 
+		foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($selfOutType) as [$aliasName, $missingParams]) {
+			$messages[] = RuleErrorBuilder::message(sprintf(
+				'Method %s::%s() has %s with generic type alias %s but does not specify its types: %s',
+				$classReflection->getDisplayName(),
+				$methodReflection->getName(),
+				$phpDocTagMessage,
+				$aliasName,
+				$missingParams,
+			))
+				->identifier('missingType.generics')
+				->build();
+		}
+
 		foreach ($this->missingTypehintCheck->getCallablesWithMissingSignature($selfOutType) as $callableType) {
 			$messages[] = RuleErrorBuilder::message(sprintf(
 				'Method %s::%s() has %s with no signature specified for %s.',
diff --git a/src/Rules/MissingTypehintCheck.php b/src/Rules/MissingTypehintCheck.php
@@ -27,6 +27,7 @@
 use function array_filter;
 use function array_keys;
 use function array_merge;
+use function array_unique;
 use function count;
 use function implode;
 use function in_array;
@@ -170,6 +171,31 @@ public function getNonGenericObjectTypesWithGenericClass(Type $type): array
 		return $objectTypes;
 	}
 
+	/**
+	 * @return list<array{string, string}> List of [aliasName, missingTypeParamNames]
+	 */
+	public function getRawGenericTypeAliasesUsage(Type $type): array
+	{
+		/** @var array<string, list<string>> $found */
+		$found = [];
+		TypeTraverser::map($type, static function (Type $type, callable $traverse) use (&$found): Type {
+			if ($type instanceof TemplateType) {
+				$aliasName = $type->getScope()->getTypeAliasName();
+				if ($aliasName !== null && $type->getDefault() === null) {
+					$found[$aliasName][] = $type->getName();
+				}
+				return $type;
+			}
+			return $traverse($type);
+		});
+
+		$result = [];
+		foreach ($found as $aliasName => $paramNames) {
+			$result[] = [$aliasName, implode(', ', array_unique($paramNames))];
+		}
+		return $result;
+	}
+
 	/**
 	 * @return Type[]
 	 */
diff --git a/src/Rules/PhpDoc/AssertRuleHelper.php b/src/Rules/PhpDoc/AssertRuleHelper.php
@@ -200,6 +200,18 @@ public function check(
 					->build();
 			}
 
+			foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($assertedType) as [$aliasName, $missingParams]) {
+				$errors[] = RuleErrorBuilder::message(sprintf(
+					'PHPDoc tag %s for %s contains generic type alias %s but does not specify its types: %s',
+					$tagName,
+					$assertedExprString,
+					$aliasName,
+					$missingParams,
+				))
+					->identifier('missingType.generics')
+					->build();
+			}
+
 			foreach ($this->missingTypehintCheck->getCallablesWithMissingSignature($assertedType) as $callableType) {
 				$errors[] = RuleErrorBuilder::message(sprintf(
 					'PHPDoc tag %s for %s has no signature specified for %s.',
diff --git a/src/Rules/PhpDoc/InvalidPhpDocVarTagTypeRule.php b/src/Rules/PhpDoc/InvalidPhpDocVarTagTypeRule.php
@@ -121,6 +121,17 @@ public function processNode(Node $node, Scope $scope): array
 						->identifier('missingType.generics')
 						->build();
 				}
+
+				foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($varTagType) as [$aliasName, $missingParams]) {
+					$errors[] = RuleErrorBuilder::message(sprintf(
+						'%s contains generic type alias %s but does not specify its types: %s',
+						$identifier,
+						$aliasName,
+						$missingParams,
+					))
+						->identifier('missingType.generics')
+						->build();
+				}
 			}
 
 			$escapedIdentifier = SprintfHelper::escapeFormatString($identifier);
diff --git a/src/Rules/Properties/MissingPropertyTypehintRule.php b/src/Rules/Properties/MissingPropertyTypehintRule.php
@@ -77,6 +77,18 @@ public function processNode(Node $node, Scope $scope): array
 				->build();
 		}
 
+		foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($propertyType) as [$aliasName, $missingParams]) {
+			$messages[] = RuleErrorBuilder::message(sprintf(
+				'Property %s::$%s with generic type alias %s does not specify its types: %s',
+				$propertyReflection->getDeclaringClass()->getDisplayName(),
+				$node->getName(),
+				$aliasName,
+				$missingParams,
+			))
+				->identifier('missingType.generics')
+				->build();
+		}
+
 		foreach ($this->missingTypehintCheck->getCallablesWithMissingSignature($propertyType) as $callableType) {
 			$messages[] = RuleErrorBuilder::message(sprintf(
 				'Property %s::$%s type has no signature specified for %s.',
diff --git a/src/Rules/Properties/SetPropertyHookParameterRule.php b/src/Rules/Properties/SetPropertyHookParameterRule.php
@@ -146,6 +146,19 @@ public function processNode(Node $node, Scope $scope): array
 				->build();
 		}
 
+		foreach ($this->missingTypehintCheck->getRawGenericTypeAliasesUsage($parameterType) as [$aliasName, $missingParams]) {
+			$errors[] = RuleErrorBuilder::message(sprintf(
+				'Set hook for property %s::$%s has parameter $%s with generic type alias %s but does not specify its types: %s',
+				$classReflection->getDisplayName(),
+				$hookReflection->getHookedPropertyName(),
+				$parameter->getName(),
+				$aliasName,
+				$missingParams,
+			))
+				->identifier('missingType.generics')
+				->build();
+		}
+
 		foreach ($this->missingTypehintCheck->getCallablesWithMissingSignature($parameterType) as $callableType) {
 			$errors[] = RuleErrorBuilder::message(sprintf(
 				'Set hook for property %s::$%s has parameter $%s with no signature specified for %s.',
diff --git a/src/Type/Generic/TemplateTypeScope.php b/src/Type/Generic/TemplateTypeScope.php
@@ -3,6 +3,9 @@
 namespace PHPStan\Type\Generic;
 
 use function sprintf;
+use function str_starts_with;
+use function strlen;
+use function substr;
 
 final class TemplateTypeScope
 {
@@ -48,6 +51,22 @@ public function getFunctionName(): ?string
 		return $this->functionName;
 	}
 
+	/** @api */
+	public function isTypeAlias(): bool
+	{
+		return $this->functionName !== null && str_starts_with($this->functionName, '__typeAlias_');
+	}
+
+	/** @api */
+	public function getTypeAliasName(): ?string
+	{
+		if (!$this->isTypeAlias()) {
+			return null;
+		}
+
+		return substr($this->functionName, strlen('__typeAlias_'));
+	}
+
 	/** @api */
 	public function equals(self $other): bool
 	{
diff --git a/test-generic-aliases.php b/test-generic-aliases.php
diff --git a/test-type-error-demo.php b/test-type-error-demo.php
