Fix stub @param types not applied inside method bodies (regression since 2.1.38)

.claude/skills/regression-test/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: regression-test
+description: Add a regression test for an already-fixed PHPStan bug given a GitHub issue number
+argument-hint: "[issue-number]"
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash(curl *), Bash(gh *), Bash(git *), Bash(make tests), Bash(vendor/bin/phpunit *), Bash(php *)
+---
+
+# Adding a regression test for a fixed PHPStan bug
+
+You are given a GitHub issue number. Your goal is to write a regression test that locks in the fix so the bug cannot silently resurface.
+
+## Step 1 — Gather context from the issue
+
+Fetch the GitHub issue and its comments:
+
+```
+gh issue view <number> --repo phpstan/phpstan --json title,body,comments
+```
+
+In the comments, look for:
+
+1. **phpstan-bot's commit link** — this identifies the commit that fixed the bug.
+2. **PHPStan Playground links** — URLs matching `https://phpstan.org/r/<UUID>`. These contain the reproducing code and the analysis results before and after the fix.
+
+For each playground link, fetch the sample data:
+
+```
+curl -s 'https://api.phpstan.org/sample?id=<UUID>'
+```
+
+The API returns JSON with:
+- `code` — the PHP code that was analysed
+- `level` — the PHPStan rule level used
+- `config.strictRules`, `config.bleedingEdge`, `config.treatPhpDocTypesAsCertain` — configuration flags
+- `versionedErrors` — array of `{phpVersion, errors: [{line, message, identifier}]}`
+
+The playground sample gives you the reproducing code and tells you what errors PHPStan produces (or should no longer produce) at each line. Use this to determine the correct test type and expected outcomes.
+
+## Step 2 — Decide which kind of test to write
+
+### Type-inference test (NSRT)
+
+Use when the bug is about **wrong inferred type, missing type narrowing, or incorrect type after control flow** — i.e., PHPStan reports the wrong type for an expression but no specific rule error is involved.
+
+- Create `tests/PHPStan/Analyser/nsrt/bug-<number>.php`
+- Use `assertType()` and optionally `assertNativeType()` to pin the correct types
+- The file is **auto-discovered** — no test-case class changes are needed
+
+Example (`tests/PHPStan/Analyser/nsrt/bug-12875.php`):
+
+```php
+<?php // lint >= 8.0
+
+declare(strict_types = 1);
+
+namespace Bug12875;
+
+use function PHPStan\Testing\assertType;
+
+interface HasFoo
+{
+	public function foo(): int;
+}
+
+interface HasBar
+{
+	public function bar(): int;
+}
+
+class HelloWorld
+{
+	/**
+	 * @param "foo"|"bar" $method
+	 * @param ($method is "foo" ? HasFoo : HasBar) $a
+	 * @param ($method is "foo" ? HasFoo : HasBar) $b
+	 */
+	public function add(string $method, HasFoo|HasBar $a, HasFoo|HasBar $b): void
+	{
+		assertType('int', $a->{$method}());
+		assertType('int', $b->{$method}());
+
+		$addInArrow = fn () => assertType('int', $a->{$method}());
+
+		$addInAnonymous = function () use ($a, $b, $method): void {
+			assertType('int', $a->{$method}());
+			assertType('int', $b->{$method}());
+		};
+	}
+}
+```
+
+### Rule test
+
+Use when the bug is about a **false positive** (rule reported an error that shouldn't exist) or a **false negative** (rule failed to report an error that should exist).
+
+1. **Find the relevant rule test case.** Search for the rule's identifier or class name:
+   ```
+   grep -r 'identifier' tests/PHPStan/Rules/ --include='*Test.php'
+   ```
+   Or look at the error identifier from the playground output (e.g., `argument.type` points to a rule in `Rules/Methods/` or `Rules/Functions/`).
+
+2. **Create the test data file** at `tests/PHPStan/Rules/<Category>/data/bug-<number>.php`.
+
+3. **Add a test method** in the corresponding `*Test.php` rule test case.
+
+Example — test data (`tests/PHPStan/Rules/Methods/data/bug-11470.php`):
+
+```php
+<?php declare(strict_types = 1);
+
+namespace Bug11470;
+
+use DateTimeImmutable;
+
+interface HelloWorld
+{
+	public function sayHello(): dateTimeImmutable;
+}
+
+interface HelloWorld2
+{
+	public function sayHello(dateTimeImmutable $a): void;
+}
+
+interface HelloWorld3
+{
+	public function sayHello(): ?dateTimeImmutable;
+}
+```
+
+Example — test method in `ExistingClassesInTypehintsRuleTest.php`:
+
+```php
+public function testBug11470(): void
+{
+	$this->analyse([__DIR__ . '/data/bug-11470.php'], [
+		[
+			'Class DateTimeImmutable referenced with incorrect case: dateTimeImmutable.',
+			9,
+		],
+		[
+			'Class DateTimeImmutable referenced with incorrect case: dateTimeImmutable.',
+			14,
+		],
+		[
+			'Class DateTimeImmutable referenced with incorrect case: dateTimeImmutable.',
+			19,
+		],
+	]);
+}
+```
+
+For **false-positive** fixes the expected-errors array is usually empty `[]`, meaning the code should analyse clean.
+
+## Step 3 — Write the test
+
+- Use the reproducing code from the playground sample as the basis for the test file.
+- Put it in the correct `namespace Bug<number>;`.
+- Add `use function PHPStan\Testing\assertType;` for NSRT tests.
+- If the playground code requires a minimum PHP version, add `// lint >= 8.0` (or whichever version) on the first line.
+- For rule tests, determine the expected errors from the playground `versionedErrors`. If the fix eliminated a false positive, expect `[]`. If the fix added a missing error, list the expected `[message, line]` pairs.
+
+## Step 4 — Verify the test
+
+Run the specific test to confirm it passes with the current (fixed) code:
+
+```bash
+# NSRT test — run the full NSRT suite or a filtered subset:
+vendor/bin/phpunit tests/PHPStan/Analyser/NodeScopeResolverTest.php --filter 'bug-<number>'
+
+# Rule test — run the specific test class:
+vendor/bin/phpunit tests/PHPStan/Rules/<Category>/<TestClass>.php --filter testBug<number>
+```
+
+## Step 5 — Confirm the test catches a regression
+
+Temporarily revert the fixing commit and verify the test fails:
+
+```bash
+git stash
+git revert --no-commit <fixing-commit-hash>
+vendor/bin/phpunit <test-command-from-step-4>
+# Expect failure
+git checkout .
+git stash pop
+```
+
+If the test passes even with the fix reverted, the test is not correctly covering the bug — revisit the assertions or the reproducing code.
+
+## Step 6 — Commit
+
+Stage the new/modified test files and commit. The commit message must include `Closes https://github.com/phpstan/phpstan/issues/<number>` so the upstream issue is closed automatically.
+
+```bash
+git add tests/
+git commit -m "Add regression test for #<number>
+
+Closes https://github.com/phpstan/phpstan/issues/<number>"
+```

.gitattributes

@@ -2,3 +2,5 @@
 *.stub linguist-language=PHP
 
 tests/PHPStan/Command/ErrorFormatter/data/WindowsNewlines.php eol=crlf
+
+.github/workflows/*.lock.yml linguist-generated=true merge=ours

.github/actions/downgrade-code/action.yml

@@ -0,0 +1,33 @@
+name: 'Downgrade code'
+description: 'Downgrade code'
+inputs:
+  php-version:
+    description: 'Original PHP version'
+    required: true
+runs:
+  using: "composite"
+  steps:
+
+    - name: "Change to simple-downgrade PHP version"
+      if: inputs.php-version == '7.4' || inputs.php-version == '8.0' || inputs.php-version == '8.1'
+      uses: "shivammathur/setup-php@v2"
+      with:
+        coverage: "none"
+        php-version: "8.4"
+
+    - name: "Transform source code"
+      if: inputs.php-version == '7.4' || inputs.php-version == '8.0' || inputs.php-version == '8.1'
+      shell: bash
+      run: |
+        composer install --no-interaction --no-progress --working-dir=compiler
+        ./compiler/vendor/bin/simple-downgrade downgrade -c build/downgrade.php ${{ inputs.php-version }}
+        composer dump
+
+    - name: "Re-store PHP version"
+      if: inputs.php-version == '7.4' || inputs.php-version == '8.0' || inputs.php-version == '8.1'
+      uses: "shivammathur/setup-php@v2"
+      with:
+        coverage: "none"
+        php-version: "${{ inputs.php-version }}"
+        ini-file: development
+        extensions: ds,mbstring