Enumerate constant strings from bounded regex quantifications (a?, a{n}, a{n,m})

- In `RegexGroupParser::walkGroupAst()`, a `#quantification` node previously
  always discarded the accumulated literals (`onlyLiterals(null)`), so any
  quantified atom degraded a constant-string group to `non-falsy-string`.
- Add `getQuantifiedLiterals()`: for a bounded quantification over constant
  literals it walks the quantified atom standalone, enumerates the repetition
  via `repeatLiterals()` (`a?` => `'a'|''`, `a{2}` => `'aa'`, `a{1,2}` =>
  `'a'|'aa'`), and cross-combines the result with the literals accumulated so
  far. Unbounded quantifiers (`*`, `+`, `{n,}`) and non-literal atoms keep
  returning `null` so the group stays non-constant.
- Reset `inOptionalQuantification` while walking the quantified atom so a
  multi-token concatenation inside an optional group (e.g. `(a(bc)?d)`) keeps
  accumulating its literals instead of being nulled.
- Add a named `LITERALS_LIMIT` constant to bail out to a plain string type
  instead of exploding on deeply nested optional/bounded quantifications.
- Update `preg_match_shapes.php` expectations that now infer precise constant
  unions (`(a|bc?)` => `'a'|'b'|'bc'`, `(a(b)?)` => `'a'|'ab'`, etc.).

Author: phpstan-bot

src/Type/Regex/RegexGroupParser.php

@@ -23,6 +23,7 @@
 use PHPStan\Type\TypeCombinator;
 use PHPStan\Type\UnionType;
 use function array_key_exists;
+use function array_pop;
 use function array_values;
 use function count;
 use function in_array;
@@ -44,6 +45,10 @@ final class RegexGroupParser
 		'J', // rare modifier too complicated to support
 	];
 
+	// upper bound on the number of constant string literals enumerated from a group,
+	// to avoid combinatorial explosion from nested optional/bounded quantifications
+	private const LITERALS_LIMIT = 100;
+
 	private static ?Parser $parser = null;
 
 	/** @var array<string, ?TreeNode> */
@@ -473,6 +478,7 @@ private function walkGroupAst(
 	): RegexGroupWalkResult
 	{
 		$children = $ast->getChildren();
+		$quantifiedLiterals = null;
 
 		if (
 			$ast->getId() === '#concatenation'
@@ -506,7 +512,7 @@ private function walkGroupAst(
 				}
 			}
 		} elseif ($ast->getId() === '#quantification') {
-			[$min] = $this->getQuantificationRange($ast);
+			[$min, $max] = $this->getQuantificationRange($ast);
 
 			if ($min === 0) {
 				$walkResult = $walkResult->inOptionalQuantification(true);
@@ -521,6 +527,10 @@ private function walkGroupAst(
 				}
 			}
 
+			// "a?" yields 'a'|'', "a{1,2}" yields 'a'|'aa', etc. so a bounded quantification
+			// over constant literals can be combined with the surrounding literals
+			$quantifiedLiterals = $this->getQuantifiedLiterals($ast, $min, $max, $inClass, $patternModifiers, $walkResult);
+
 			$walkResult = $walkResult->onlyLiterals(null);
 		} elseif ($ast->getId() === '#class' && $walkResult->getOnlyLiterals() !== null) {
 			$inClass = true;
@@ -626,9 +636,108 @@ private function walkGroupAst(
 			);
 		}
 
+		if ($ast->getId() === '#quantification') {
+			// the bottom walk above nulls the literals via the quantifier token,
+			// so restore the literals enumerated up-front for bounded quantifications
+			$walkResult = $walkResult->onlyLiterals($quantifiedLiterals);
+		}
+
 		return $walkResult;
 	}
 
+	/**
+	 * Enumerate the constant strings a bounded quantification (like "a?", "a{2}", "a{1,3}")
+	 * produces, combined with the literals accumulated so far. Returns null when the result
+	 * cannot be enumerated (unbounded quantifier, non-literal atom, or too many combinations).
+	 *
+	 * @return array<string>|null
+	 */
+	private function getQuantifiedLiterals(TreeNode $ast, ?int $min, ?int $max, bool $inClass, string $patternModifiers, RegexGroupWalkResult $walkResult): ?array
+	{
+		$prefixLiterals = $walkResult->getOnlyLiterals();
+		if ($prefixLiterals === null || $min === null || $max === null) {
+			return null;
+		}
+
+		// walk the quantified atom standalone (everything but the trailing quantifier token);
+		// the atom itself is not optional, so reset the flag to let concatenations accumulate literals
+		$atomChildren = $ast->getChildren();
+		array_pop($atomChildren);
+
+		$atomResult = $walkResult->onlyLiterals([])->inOptionalQuantification(false);
+		foreach ($atomChildren as $atomChild) {
+			$atomResult = $this->walkGroupAst($atomChild, $inClass, $patternModifiers, $atomResult);
+		}
+
+		$atomLiterals = $atomResult->getOnlyLiterals();
+		if ($atomLiterals === null) {
+			return null;
+		}
+
+		$repeatedLiterals = $this->repeatLiterals($atomLiterals, $min, $max);
+		if ($repeatedLiterals === null) {
+			return null;
+		}
+
+		$newLiterals = [];
+		foreach ($repeatedLiterals as $repeatedLiteral) {
+			if ($prefixLiterals === []) {
+				$newLiterals[] = $repeatedLiteral;
+			} else {
+				foreach ($prefixLiterals as $prefixLiteral) {
+					$newLiterals[] = $prefixLiteral . $repeatedLiteral;
+				}
+			}
+
+			if (count($newLiterals) > self::LITERALS_LIMIT) {
+				return null;
+			}
+		}
+
+		return $newLiterals;
+	}
+
+	/**
+	 * @param array<string> $literals
+	 * @return array<string>|null
+	 */
+	private function repeatLiterals(array $literals, int $min, int $max): ?array
+	{
+		$collected = [];
+		if ($min === 0) {
+			$collected[''] = '';
+		}
+
+		$current = [''];
+		for ($k = 1; $k <= $max; $k++) {
+			$next = [];
+			foreach ($current as $prefix) {
+				foreach ($literals as $literal) {
+					$next[] = $prefix . $literal;
+				}
+
+				if (count($next) > self::LITERALS_LIMIT) {
+					return null;
+				}
+			}
+			$current = $next;
+
+			if ($k < $min) {
+				continue;
+			}
+
+			foreach ($current as $value) {
+				$collected[$value] = $value;
+			}
+
+			if (count($collected) > self::LITERALS_LIMIT) {
+				return null;
+			}
+		}
+
+		return array_values($collected);
+	}
+
 	private function isMaybeEmptyNode(TreeNode $node, string $patternModifiers, bool &$isNonFalsy): bool
 	{
 		if ($node->getId() === '#quantification') {

tests/PHPStan/Analyser/nsrt/bug-14820.php

@@ -0,0 +1,58 @@
+<?php declare(strict_types = 1);
+
+namespace Bug14820;
+
+use function PHPStan\Testing\assertType;
+
+function doFoo(string $s): void
+{
+	// a single optional literal yields the literal or the empty string,
+	// combined with the surrounding literals
+	if (preg_match('~(ab?)~', $s, $m)) {
+		assertType("array{non-falsy-string, 'a'|'ab'}", $m);
+	}
+
+	if (preg_match('~(ab?c)~', $s, $m)) {
+		assertType("array{non-falsy-string, 'abc'|'ac'}", $m);
+	}
+
+	// optional in front
+	if (preg_match('~(a?bc)~', $s, $m)) {
+		assertType("array{non-falsy-string, 'abc'|'bc'}", $m);
+	}
+
+	// two optionals combine into the full cross-product
+	if (preg_match('~(a?b?)~', $s, $m)) {
+		assertType("array{string, ''|'a'|'ab'|'b'}", $m);
+	}
+
+	// optional over a (sub) group of literals
+	if (preg_match('~(a(bc)?d)~', $s, $m)) {
+		assertType("array{0: non-falsy-string, 1: 'abcd'|'ad', 2?: 'bc'}", $m);
+	}
+
+	// optional over an alternation
+	if (preg_match('~(a(b|c)?d)~', $s, $m)) {
+		assertType("array{0: non-falsy-string, 1: 'abd'|'acd'|'ad', 2?: 'b'|'c'}", $m);
+	}
+
+	// the classic colour/color example
+	if (preg_match('~(colou?r)~', $s, $m)) {
+		assertType("array{non-falsy-string, 'color'|'colour'}", $m);
+	}
+
+	// exactly-n repetition of a literal
+	if (preg_match('~(ab{2}c)~', $s, $m)) {
+		assertType("array{non-falsy-string, 'abbc'}", $m);
+	}
+
+	// n-to-m repetition of a literal
+	if (preg_match('~(ab{1,2}c)~', $s, $m)) {
+		assertType("array{non-falsy-string, 'abbc'|'abc'}", $m);
+	}
+
+	// unbounded repetition stays non-constant
+	if (preg_match('~(ab*c)~', $s, $m)) {
+		assertType('array{non-falsy-string, non-falsy-string}', $m);
+	}
+}

tests/PHPStan/Analyser/nsrt/preg_match_shapes.php

@@ -236,10 +236,10 @@ function doFoo(string $row): void
 		assertType("array{non-falsy-string, 'ab', 'b'}", $matches);
 	}
 	if (preg_match('~^(a(b)?)$~', $row, $matches) === 1) {
-		assertType("array{0: non-falsy-string, 1: non-falsy-string, 2?: 'b'}", $matches);
+		assertType("array{0: non-falsy-string, 1: 'a'|'ab', 2?: 'b'}", $matches);
 	}
 	if (preg_match('~^(a(b)?)?$~', $row, $matches) === 1) {
-		assertType("list{0: string, 1?: non-falsy-string, 2?: 'b'}", $matches);
+		assertType("list{0: string, 1?: 'a'|'ab', 2?: 'b'}", $matches);
 	}
 }
 
@@ -612,19 +612,19 @@ function (string $s): void {
 
 function (string $s): void {
 	if (preg_match('/Price: (a|bc?)/', $s, $matches)) {
-		assertType("array{non-falsy-string, non-falsy-string}", $matches);
+		assertType("array{non-falsy-string, 'a'|'b'|'bc'}", $matches);
 	}
 };
 
 function (string $s): void {
 	if (preg_match('/Price: (?<named>a|bc?)/', $s, $matches)) {
-		assertType("array{0: non-falsy-string, named: non-falsy-string, 1: non-falsy-string}", $matches);
+		assertType("array{0: non-falsy-string, named: 'a'|'b'|'bc', 1: 'a'|'b'|'bc'}", $matches);
 	}
 };
 
 function (string $s): void {
 	if (preg_match('/Price: (a|0c?)/', $s, $matches)) {
-		assertType("array{non-falsy-string, non-empty-string}", $matches);
+		assertType("array{non-falsy-string, '0'|'0c'|'a'}", $matches);
 	}
 };