TemplateArgumentFrame.php

<?php declare(strict_types = 1);

namespace PHPStan\Analyser\Generics;

use PhpParser\Node;
use PhpParser\Node\Expr;
use PHPStan\Analyser\ConditionalExpressionHolder;
use PHPStan\Analyser\MutatingScope;
use PHPStan\Reflection\ParametersAcceptor;
use PHPStan\Reflection\ResolvedFunctionVariant;
use PHPStan\Turbo\ShadowedByTurboExtension;
use PHPStan\Type\Generic\TemplateType;
use PHPStan\Type\Generic\UnresolvedTemplateArgumentType;
use PHPStan\Type\Type;
use PHPStan\Type\TypeTraverser;
use function array_keys;
use function spl_object_id;
use function sprintf;

/**
 * Immutable template inference context carried by a scope. The observation walk
 * and the resolved walk use distinct instances, including in saved callbacks.
 */
#[ShadowedByTurboExtension(implementation: __DIR__ . '/../../../turbo-ext/src/TemplateArgumentFrame.cpp')]
final class TemplateArgumentFrame
{

	/**
	 * Set on the synthetic nodes handlers build for an on-demand pricing (the
	 * parent constructor's `new`, a fabricated offsetGet()/__toString() call):
	 * a fresh node every walk, so it can never be a site the second pass finds
	 * again. Markers keyed by such a node are re-keyed by the handler that
	 * built it or stay unobserved.
	 */
	public const SYNTHETIC_SITE_ATTRIBUTE = 'templateArgumentSyntheticSite';

	/**
	 * Set on a node a handler builds in place of the real one (the nullsafe
	 * call's plain twin) to the real node, which is the site.
	 */
	public const ORIGINAL_SITE_ATTRIBUTE = 'templateArgumentOriginalSite';

	/**
	 * The return type of a call the analyser walks: the variant's return type
	 * with the inferred template arguments unresolved/resolved under the
	 * scope's frame, the legacy (generalizing) one otherwise.
	 */
	public static function returnTypeOfCall(ParametersAcceptor $acceptor, MutatingScope $scope, Expr $site, ?bool $allowUnresolved = null): Type
	{
		$frame = $scope->getCurrentTemplateArgumentFrame();
		if ($frame === null || !$acceptor instanceof ResolvedFunctionVariant) {
			return $acceptor->getReturnType();
		}
		$originalSite = $site->getAttribute(self::ORIGINAL_SITE_ATTRIBUTE);

		return $acceptor->getReturnTypeWithUnresolvedTemplateArguments(
			$originalSite instanceof Expr ? $originalSite : $site,
			$frame,
			$allowUnresolved ?? !$scope->nativeTypesPromoted,
		);
	}

	/**
	 * @param array<string, Type>|null $resolutions null during collection
	 * @param array<int, true> $siteStatementIndexes
	 * @param Node\Stmt[] $closureSignatureStmts the statements of $closureSignatureBody
	 * @param array<int, true> $settledClosureSites spl_object_id() of the closure nodes
	 * @param bool $observingClosures the template arguments are resolved, the closure signatures observed again
	 * @param array<int, array{Expr\Closure, int, bool}> $byRefSites spl_object_id() of the closure node => the node, its statement index, whether every invocation was seen
	 * @param array<int, array{Expr\Variable, Type, Type}> $staticVariableTypes spl_object_id() of a `static` variable node => the node, its phpdoc and native type - see StaticVariableInference
	 * @param array<int, array{Node\Stmt\Static_, array<string, ConditionalExpressionHolder[]>}> $staticVariableConditionalExpressions spl_object_id() of the last statement of a run of `static` statements => the statement, the conditional expressions between the run's variables - see StaticVariableInference::getRuns()
	 */
	public function __construct(
		private readonly ?self $parent,
		private readonly ?array $resolutions = null,
		private readonly array $siteStatementIndexes = [],
		private readonly ?Node $closureSignatureBody = null,
		private readonly array $closureSignatureStmts = [],
		private readonly array $settledClosureSites = [],
		private readonly bool $observingClosures = false,
		private readonly array $byRefSites = [],
		private readonly array $staticVariableTypes = [],
		private readonly array $staticVariableConditionalExpressions = [],
	)
	{
	}

	/**
	 * @return array{Type, Type}|null
	 */
	public function getStaticVariableTypes(Expr\Variable $var): ?array
	{
		$types = $this->staticVariableTypes[spl_object_id($var)] ?? null;
		if ($types === null || $types[0] !== $var) {
			return null;
		}

		return [$types[1], $types[2]];
	}

	/**
	 * @return array<string, ConditionalExpressionHolder[]>
	 */
	public function getStaticVariableConditionalExpressions(Node\Stmt\Static_ $stmt): array
	{
		$conditionalExpressions = $this->staticVariableConditionalExpressions[spl_object_id($stmt)] ?? null;
		if ($conditionalExpressions === null || $conditionalExpressions[0] !== $stmt) {
			return [];
		}

		return $conditionalExpressions[1];
	}

	/**
	 * The frame with the inferred types of the body's `static` variables; the
	 * statements holding them are walked again in the second pass. The walks
	 * inferring the types observed, so on a resolved frame the markers of the
	 * types are replaced by what the frame resolved them to - as the second
	 * pass replaces them at their sites.
	 *
	 * @param array<int, array{Expr\Variable, Type, Type}> $staticVariableTypes
	 * @param array<int, true> $statementIndexes
	 * @param array<int, array{Node\Stmt\Static_, array<string, ConditionalExpressionHolder[]>}> $conditionalExpressions
	 */
	public function withStaticVariableTypes(array $staticVariableTypes, array $statementIndexes, array $conditionalExpressions = []): self
	{
		if ($this->resolutions !== null) {
			foreach ($staticVariableTypes as $id => [$var, $type, $nativeType]) {
				$staticVariableTypes[$id] = [$var, $this->resolveMarkers($type), $this->resolveMarkers($nativeType)];
			}
		}

		return new self(
			$this->parent,
			$this->resolutions,
			$this->siteStatementIndexes + $statementIndexes,
			$this->closureSignatureBody,
			$this->closureSignatureStmts,
			$this->settledClosureSites,
			$this->observingClosures,
			$this->byRefSites,
			$staticVariableTypes,
			$conditionalExpressions,
		);
	}

	/**
	 * How the second pass treats the by-ref uses of a closure created in this
	 * frame's body - see ClosureSignatureInference::getByRefSiteMode().
	 *
	 * @return 'local'|'escaped'|null
	 */
	public function getByRefSiteMode(Expr $site): ?string
	{
		$byRefSite = $this->byRefSites[spl_object_id($site)] ?? null;
		if ($byRefSite !== null && $byRefSite[0] === $site) {
			return $byRefSite[2] ? 'local' : 'escaped';
		}

		return $this->parent !== null ? $this->parent->getByRefSiteMode($site) : null;
	}

	/**
	 * The closures of this frame's body whose every invocation was seen, with
	 * the index of the statement creating them.
	 *
	 * @return list<array{Expr\Closure, int}>
	 */
	public function getLocalByRefSites(): array
	{
		$sites = [];
		foreach ($this->byRefSites as [$site, $statementIndex, $local]) {
			if (!$local) {
				continue;
			}
			$sites[] = [$site, $statementIndex];
		}

		return $sites;
	}

	/**
	 * The resolved frame with the closure signatures observed in the closure
	 * observation pass (see TemplateArgumentResolver::resolveObservedClosures()).
	 *
	 * @param array<string, Type> $closureResolutions
	 * @param array<int, true> $closureSiteStatementIndexes
	 * @param array<int, true> $settledClosureSites
	 * @param array<int, array{Expr\Closure, int, bool}> $byRefSites
	 */
	public function withObservedClosures(array $closureResolutions, array $closureSiteStatementIndexes, array $settledClosureSites, array $byRefSites = []): self
	{
		return new self(
			$this->parent,
			($this->resolutions ?? []) + $closureResolutions,
			$this->siteStatementIndexes + $closureSiteStatementIndexes,
			$this->closureSignatureBody,
			$this->closureSignatureStmts,
			$settledClosureSites,
			byRefSites: $byRefSites,
			staticVariableTypes: $this->staticVariableTypes,
			staticVariableConditionalExpressions: $this->staticVariableConditionalExpressions,
		);
	}

	/**
	 * Whether the closure's signature resolved to exactly what its markers stood
	 * for while observing - its ClosureType keeps them, see
	 * TemplateArgumentResolver::resolve().
	 */
	public function isSettledClosureSite(Expr $site): bool
	{
		if (isset($this->settledClosureSites[spl_object_id($site)])) {
			return true;
		}

		return $this->parent !== null && $this->parent->isSettledClosureSite($site);
	}

	/** The frame of the body this frame's body is written in. */
	public function getParent(): ?self
	{
		return $this->parent;
	}

	/**
	 * The function-like body the frame observes, asked only when a closure in
	 * it has its signature inferred (see ClosureSignatureInference::isClosedBody()).
	 */
	public function getClosureSignatureBody(): ?Node
	{
		return $this->closureSignatureBody;
	}

	/** @return Node\Stmt[] */
	public function getClosureSignatureStmts(): array
	{
		return $this->closureSignatureStmts;
	}

	public function isObserving(): bool
	{
		return $this->resolutions === null;
	}

	/**
	 * Whether closures get signature markers and their sends are collected:
	 * in the observation pass, and in the closure observation pass that walks
	 * with the template arguments already resolved.
	 */
	public function isObservingClosures(): bool
	{
		return $this->resolutions === null || $this->observingClosures;
	}

	public function firstSiteStatementIndex(): ?int
	{
		$first = null;
		foreach (array_keys($this->siteStatementIndexes) as $index) {
			if ($first !== null && $index >= $first) {
				continue;
			}

			$first = $index;
		}

		return $first;
	}

	public function ownsSiteInStatement(int $statementIndex): bool
	{
		return isset($this->siteStatementIndexes[$statementIndex]);
	}

	public function hasSiteAtOrAfter(int $statementIndex): bool
	{
		foreach (array_keys($this->siteStatementIndexes) as $index) {
			if ($index >= $statementIndex) {
				return true;
			}
		}

		return false;
	}

	/**
	 * The resolution of the site's template argument, or - for a site this
	 * frame never observed (never asked during the observation pass, a native
	 * flavour) - what an unconstrained argument resolves to.
	 */
	public function resolveOrUnconstrained(Expr $site, TemplateType $template): Type
	{
		return $this->resolve($site, $template->getName()) ?? self::resolveUnconstrained($site, $template, fn (Expr $site, string $templateName): ?Type => $this->resolve($site, $templateName));
	}

	/**
	 * Nothing was inferred, sent or passed in: use the template's default or
	 * bound, resolving sibling arguments in dependent bounds (`U of T`).
	 * An unknown argument does not imply that the object holds nothing.
	 *
	 * @param callable(Expr, string): ?Type $resolve
	 */
	public static function resolveUnconstrained(Expr $site, TemplateType $template, callable $resolve): Type
	{
		$default = $template->getDefault();
		if ($default !== null) {
			return $default;
		}

		$bound = $template->getBound();
		if (!$bound->hasTemplateOrLateResolvableType()) {
			return $bound;
		}

		$scope = $template->getScope();

		return TypeTraverser::map($bound, static function (Type $type, callable $traverse) use ($site, $scope, $resolve): Type {
			if ($type instanceof TemplateType && $type->getScope()->equals($scope)) {
				return $resolve($site, $type->getName()) ?? $type->getDefault() ?? $traverse($type->getBound());
			}

			return $traverse($type);
		});
	}

	/**
	 * The resolved type of a template argument of the site, or null for a site
	 * this frame and its parents never observed.
	 */
	public function resolve(Expr $site, string $templateName): ?Type
	{
		$key = self::key($site, $templateName);
		if (isset($this->resolutions[$key])) {
			return $this->resolutions[$key];
		}

		if ($this->parent !== null) {
			return $this->parent->resolve($site, $templateName);
		}

		return null;
	}

	/**
	 * Distinguishes cache entries computed while observing from those computed
	 * with the resolutions installed (the closure type cache keys on scope state
	 * that does not change between the two passes).
	 */
	public function getResolutionCacheKeySuffix(): string
	{
		$frame = $this;
		while ($frame !== null) {
			if (!$frame->isObserving()) {
				return sprintf('|templateArguments:%d', spl_object_id($frame));
			}

			$frame = $frame->parent;
		}

		return '';
	}

	private function resolveMarkers(Type $type): Type
	{
		return TypeTraverser::map($type, function (Type $type, callable $traverse): Type {
			if ($type instanceof UnresolvedTemplateArgumentType && !$type->isClosureSignature()) {
				$site = $type->getSite();

				return $traverse($this->resolve($site, $type->getTemplateName()) ?? $type->getInitialType() ?? $this->resolveOrUnconstrained($site, $type->getTemplate()));
			}

			return $traverse($type);
		});
	}

	private static function key(Expr $site, string $templateName): string
	{
		return spl_object_id($site) . '#' . $templateName;
	}

}