[BCB] Refactor TypeSpecifier::create() method and SpecifiedTypes constructor parameters

Author: ondrejmirtes

UPGRADING.md

@@ -26,4 +26,24 @@ Now, `throw $e;` is represented as a `Stmt\Expression` that contains an `Expr\Th
 
 See [UPGRADING](https://github.com/phpstan/phpdoc-parser/blob/2.0.x/UPGRADING.md) guide for phpstan/phpdoc-parser.
 
-TODO
+### Changed `TypeSpecifier::create()` and `SpecifiedTypes` constructor parameters
+
+[`PHPStan\Analyser\TypeSpecifier::create()`](https://apiref.phpstan.org/2.0.x/PHPStan.Analyser.TypeSpecifier.html#_create) now accepts (all parameters are required):
+
+* `Expr $expr`
+* `Type $type`
+* `TypeSpecifierContext $context`
+* `Scope $scope`
+
+If you want to change `$overwrite` or `$rootExpr` (previous parameters also used to be accepted by this method), call `setAlwaysOverwriteTypes()` and `setRootExpr()` on [`SpecifiedTypes`](https://apiref.phpstan.org/2.0.x/PHPStan.Analyser.SpecifiedTypes.html) (object returned by `TypeSpecifier::create()`). These methods return a new object (SpecifiedTypes is immutable).
+
+[`SpecifiedTypes`](https://apiref.phpstan.org/2.0.x/PHPStan.Analyser.SpecifiedTypes.html) constructor now accepts:
+
+* `array $sureTypes`
+* `array $sureNotTypes`
+
+If you want to change `$overwrite` or `$rootExpr` (previous parameters also used to be accepted by the constructor), call `setAlwaysOverwriteTypes()` and `setRootExpr()`. These methods return a new object (SpecifiedTypes is immutable).
+
+### Changed `TypeSpecifier::specifyTypesInCondition()`
+
+This method now longer accepts `Expr $rootExpr`. If you want to change it, call `setRootExpr()` on [`SpecifiedTypes`](https://apiref.phpstan.org/2.0.x/PHPStan.Analyser.SpecifiedTypes.html) (object returned by `TypeSpecifier::specifyTypesInCondition()`). `setRootExpr()` method returns a new object (SpecifiedTypes is immutable).

src/Analyser/SpecifiedTypes.php

@@ -9,22 +9,78 @@
 final class SpecifiedTypes
 {
 
+	private bool $overwrite = false;
+
+	/** @var array<string, ConditionalExpressionHolder[]> */
+	private array $newConditionalExpressionHolders = [];
+
+	private ?Expr $rootExpr = null;
+
 	/**
 	 * @api
 	 * @param array<string, array{Expr, Type}> $sureTypes
 	 * @param array<string, array{Expr, Type}> $sureNotTypes
-	 * @param array<string, ConditionalExpressionHolder[]> $newConditionalExpressionHolders
 	 */
 	public function __construct(
 		private array $sureTypes = [],
 		private array $sureNotTypes = [],
-		private bool $overwrite = false,
-		private array $newConditionalExpressionHolders = [],
-		private ?Expr $rootExpr = null,
 	)
 	{
 	}
 
+	/**
+	 * Normally, $sureTypes in truthy context are used to intersect with the pre-existing type.
+	 * And $sureNotTypes are used to remove type from the pre-existing type.
+	 *
+	 * Example: By default, non-empty-string intersected with '' (ConstantStringType) will lead to NeverType.
+	 * Because it's not possible to narrow non-empty-string to an empty string.
+	 *
+	 * In rare cases, a type-specifying extension might want to overwrite the pre-existing types
+	 * without taking the pre-existing types into consideration.
+	 *
+	 * In that case it should also call setAlwaysOverwriteTypes() on
+	 * the returned object.
+	 *
+	 * ! Only do this if you're certain. Otherwise, this is a source of common bugs. !
+	 *
+	 * @api
+	 */
+	public function setAlwaysOverwriteTypes(): self
+	{
+		$self = new self($this->sureTypes, $this->sureNotTypes);
+		$self->overwrite = true;
+		$self->newConditionalExpressionHolders = $this->newConditionalExpressionHolders;
+		$self->rootExpr = $this->rootExpr;
+
+		return $self;
+	}
+
+	/**
+	 * @api
+	 */
+	public function setRootExpr(?Expr $rootExpr): self
+	{
+		$self = new self($this->sureTypes, $this->sureNotTypes);
+		$self->overwrite = $this->overwrite;
+		$self->newConditionalExpressionHolders = $this->newConditionalExpressionHolders;
+		$self->rootExpr = $rootExpr;
+
+		return $self;
+	}
+
+	/**
+	 * @param array<string, ConditionalExpressionHolder[]> $newConditionalExpressionHolders
+	 */
+	public function setNewConditionalExpressionHolders(array $newConditionalExpressionHolders): self
+	{
+		$self = new self($this->sureTypes, $this->sureNotTypes);
+		$self->overwrite = $this->overwrite;
+		$self->newConditionalExpressionHolders = $newConditionalExpressionHolders;
+		$self->rootExpr = $this->rootExpr;
+
+		return $self;
+	}
+
 	/**
 	 * @api
 	 * @return array<string, array{Expr, Type}>
@@ -90,7 +146,12 @@ public function intersectWith(SpecifiedTypes $other): self
 			];
 		}
 
-		return new self($sureTypeUnion, $sureNotTypeUnion, $this->overwrite && $other->overwrite, [], $rootExpr);
+		$result = new self($sureTypeUnion, $sureNotTypeUnion);
+		if ($this->overwrite && $other->overwrite) {
+			$result = $result->setAlwaysOverwriteTypes();
+		}
+
+		return $result->setRootExpr($rootExpr);
 	}
 
 	/** @api */
@@ -122,7 +183,12 @@ public function unionWith(SpecifiedTypes $other): self
 			];
 		}
 
-		return new self($sureTypeUnion, $sureNotTypeUnion, $this->overwrite || $other->overwrite, [], $rootExpr);
+		$result = new self($sureTypeUnion, $sureNotTypeUnion);
+		if ($this->overwrite || $other->overwrite) {
+			$result = $result->setAlwaysOverwriteTypes();
+		}
+
+		return $result->setRootExpr($rootExpr);
 	}
 
 	public function normalize(Scope $scope): self
@@ -138,7 +204,12 @@ public function normalize(Scope $scope): self
 			$sureTypes[$exprString][1] = TypeCombinator::remove($sureTypes[$exprString][1], $sureNotType);
 		}
 
-		return new self($sureTypes, [], $this->overwrite, $this->newConditionalExpressionHolders, $this->rootExpr);
+		$result = new self($sureTypes, []);
+		if ($this->overwrite) {
+			$result = $result->setAlwaysOverwriteTypes();
+		}
+
+		return $result->setRootExpr($this->rootExpr);
 	}
 
 	private function mergeRootExpr(?Expr $rootExprA, ?Expr $rootExprB): ?Expr