Generics type projections (call-site variance)

Author: jiripudil

doc/grammars/type.abnf

@@ -28,7 +28,11 @@ Atomic
 	/ TokenParenthesesOpen ParenthesizedType TokenParenthesesClose [Array]
 
 Generic
-	= TokenAngleBracketOpen Type *(TokenComma Type) TokenAngleBracketClose
+	= TokenAngleBracketOpen GenericTypeArgument *(TokenComma GenericTypeArgument) TokenAngleBracketClose
+
+GenericTypeArgument
+    = [TokenContravariant / TokenCovariant] Type
+    / TokenWildcard
 
 Callable
 	= TokenParenthesesOpen [CallableParameters] TokenParenthesesClose TokenColon CallableReturnType
@@ -188,6 +192,15 @@ TokenIs
 TokenNot
 	= %s"not" 1*ByteHorizontalWs
 
+TokenContravariant
+    = %s"contravariant" 1*ByteHorizontalWs
+
+TokenCovariant
+    = %s"covariant" 1*ByteHorizontalWs
+
+TokenWildcard
+	= "*" *ByteHorizontalWs
+
 TokenIdentifier
 	= [ByteBackslash] ByteIdentifierFirst *ByteIdentifierSecond *(ByteBackslash ByteIdentifierFirst *ByteIdentifierSecond) *ByteHorizontalWs
 

src/Ast/Type/GenericTypeNode.php

@@ -4,10 +4,16 @@
 
 use PHPStan\PhpDocParser\Ast\NodeAttributes;
 use function implode;
+use function sprintf;
 
 class GenericTypeNode implements TypeNode
 {
 
+	public const VARIANCE_INVARIANT = 'invariant';
+	public const VARIANCE_COVARIANT = 'covariant';
+	public const VARIANCE_CONTRAVARIANT = 'contravariant';
+	public const VARIANCE_BIVARIANT = 'bivariant';
+
 	use NodeAttributes;
 
 	/** @var IdentifierTypeNode */
@@ -16,16 +22,33 @@ class GenericTypeNode implements TypeNode
 	/** @var TypeNode[] */
 	public $genericTypes;
 
-	public function __construct(IdentifierTypeNode $type, array $genericTypes)
+	/** @var (self::VARIANCE_*)[] */
+	public $variances;
+
+	public function __construct(IdentifierTypeNode $type, array $genericTypes, array $variances = [])
 	{
 		$this->type = $type;
 		$this->genericTypes = $genericTypes;
+		$this->variances = $variances;
 	}
 
 
 	public function __toString(): string
 	{
-		return $this->type . '<' . implode(', ', $this->genericTypes) . '>';
+		$genericTypes = [];
+
+		foreach ($this->genericTypes as $index => $type) {
+			$variance = $this->variances[$index] ?? self::VARIANCE_INVARIANT;
+			if ($variance === self::VARIANCE_INVARIANT) {
+				$genericTypes[] = (string) $type;
+			} elseif ($variance === self::VARIANCE_BIVARIANT) {
+				$genericTypes[] = '*';
+			} else {
+				$genericTypes[] = sprintf('%s %s', $variance, $type);
+			}
+		}
+
+		return $this->type . '<' . implode(', ', $genericTypes) . '>';
 	}
 
 }

src/Parser/TypeParser.php

@@ -323,24 +323,54 @@ public function parseGeneric(TokenIterator $tokens, Ast\Type\IdentifierTypeNode
 	{
 		$tokens->consumeTokenType(Lexer::TOKEN_OPEN_ANGLE_BRACKET);
 		$tokens->tryConsumeTokenType(Lexer::TOKEN_PHPDOC_EOL);
-		$genericTypes = [$this->parse($tokens)];
+
+		$genericTypes = [];
+		$variances = [];
+
+		[$genericTypes[], $variances[]] = $this->parseGenericTypeArgument($tokens);
 
 		$tokens->tryConsumeTokenType(Lexer::TOKEN_PHPDOC_EOL);
 
 		while ($tokens->tryConsumeTokenType(Lexer::TOKEN_COMMA)) {
 			$tokens->tryConsumeTokenType(Lexer::TOKEN_PHPDOC_EOL);
 			if ($tokens->tryConsumeTokenType(Lexer::TOKEN_CLOSE_ANGLE_BRACKET)) {
 				// trailing comma case
-				return new Ast\Type\GenericTypeNode($baseType, $genericTypes);
+				return new Ast\Type\GenericTypeNode($baseType, $genericTypes, $variances);
 			}
-			$genericTypes[] = $this->parse($tokens);
+			[$genericTypes[], $variances[]] = $this->parseGenericTypeArgument($tokens);
 			$tokens->tryConsumeTokenType(Lexer::TOKEN_PHPDOC_EOL);
 		}
 
 		$tokens->tryConsumeTokenType(Lexer::TOKEN_PHPDOC_EOL);
 		$tokens->consumeTokenType(Lexer::TOKEN_CLOSE_ANGLE_BRACKET);
 
-		return new Ast\Type\GenericTypeNode($baseType, $genericTypes);
+		return new Ast\Type\GenericTypeNode($baseType, $genericTypes, $variances);
+	}
+
+
+	/**
+	 * @phpstan-impure
+	 * @return array{Ast\Type\TypeNode, Ast\Type\GenericTypeNode::VARIANCE_*}
+	 */
+	public function parseGenericTypeArgument(TokenIterator $tokens): array
+	{
+		if ($tokens->tryConsumeTokenType(Lexer::TOKEN_WILDCARD)) {
+			return [
+				new Ast\Type\IdentifierTypeNode('mixed'),
+				Ast\Type\GenericTypeNode::VARIANCE_BIVARIANT,
+			];
+		}
+
+		if ($tokens->tryConsumeTokenValue('contravariant')) {
+			$variance = Ast\Type\GenericTypeNode::VARIANCE_CONTRAVARIANT;
+		} elseif ($tokens->tryConsumeTokenValue('covariant')) {
+			$variance = Ast\Type\GenericTypeNode::VARIANCE_COVARIANT;
+		} else {
+			$variance = Ast\Type\GenericTypeNode::VARIANCE_INVARIANT;
+		}
+
+		$type = $this->parse($tokens);
+		return [$type, $variance];
 	}