Replace string-based references with targeted parameter attributes

- Use AssuranceParameter to detect assurance constructor params and assertion
  method inputs instead of string-based $parameter and $input properties
- Use ComposableParameter to detect prefix parameters instead of
  $prefixParameter boolean
- Derive prefix strings via FluentResolver::unresolve() instead of hardcoded
  lcfirst()
- Change composeRange from string to array{int, int|null} throughout the
  analysis pipeline (MethodMapBuilder, CacheGenerator, extensions, NEON schema)
- Add AssuranceMap, FluentTypeSpecifyingExtension, TypeStringResolver for
  PHPStan type narrowing
- Add ExtractsAssurance trait for shared assurance resolution
- Update NEON schema to accept int and array values in assurance entries
- Comprehensive test coverage for all new functionality

Author: alganet

README.md

@@ -1,8 +1,8 @@
 # Respect\FluentAnalysis
 
 PHPStan extension for [Respect/Fluent](https://github.com/Respect/Fluent) builders.
-Provides method resolution, parameter validation, and tuple-typed `getNodes()`
-without generated code.
+Provides method resolution, parameter validation, tuple-typed `getNodes()`, and
+type narrowing through assertion methods — without generated code.
 
 Fluent builders use `__call` to resolve method names to class instances. Since
 those methods don't exist as real declarations, PHPStan reports errors and can't
@@ -115,9 +115,52 @@ For builders using Respect/Fluent's composable prefixes (like Validation's
 `notEmail()`, `nullOrStringType()`), the extension resolves composed methods
 with correct parameter signatures.
 
+### Type narrowing
+
+Builders can narrow the type of a variable through assertion methods. Node
+classes declare their assurance via the `#[Assurance]` attribute, assertion
+methods are marked with `#[AssuranceAssertion]`, and `#[AssuranceParameter]`
+identifies the validated parameter and constructor parameters used for type
+resolution.
+
+Void assertion methods narrow unconditionally:
+
+```php
+$builder->intNode()->doAssert($x);
+// PHPStan now knows $x is int
+```
+
+Bool assertion methods work as type guards:
+
+```php
+if ($builder->intNode()->isOk($x)) {
+    // $x is int here
+}
+// $x is not int here
+```
+
+Chained nodes intersect their assurances:
+
+```php
+$builder->intNode()->numericNode()->doAssert($x);
+// int ∩ (int|float|numeric-string) = int
+```
+
+The extension supports several assurance modes through the `#[Assurance]`
+attribute:
+
+- **`type`** — a fixed type string (e.g. `int`, `float|int|numeric-string`)
+- **`#[AssuranceParameter]`** — the type is taken from a constructor parameter
+  annotated with the attribute (e.g. a class-string parameter)
+- **`from: value`** — narrows to the argument's literal type
+- **`from: member`** — narrows to the iterable value type of the argument
+- **`from: elements`** — narrows to an array of the inner assurance type
+- **`compose: union|intersect`** — combines assurances from multiple builder
+  arguments
+
 ## How it works
 
-The extension registers two PHPStan hooks:
+The extension registers three PHPStan hooks:
 
 1. **`FluentMethodsExtension`** (`MethodsClassReflectionExtension`) — tells
    PHPStan which methods exist on each builder, with parameters extracted from
@@ -127,27 +170,35 @@ The extension registers two PHPStan hooks:
    `DynamicStaticMethodReturnTypeExtension`) — intercepts each method call to
    track accumulated node types as a `GenericObjectType` wrapping a
    `ConstantArrayType` tuple. When `getNodes()` is called, the tuple is
-   returned directly.
+   returned directly. Also accumulates assurance types through the chain.
+
+3. **`FluentTypeSpecifyingExtension`** (`MethodTypeSpecifyingExtension`) —
+   enables type narrowing in control flow. When a builder's assertion method
+   is called, accumulated assurances are applied to narrow the input variable's
+   type. Supports void assertions (unconditional) and bool guards (conditional).
 
-Both extensions share a `MethodMap` that resolves method names to target
-class FQCNs, with parent-class fallback for builder inheritance.
+The extensions share a `MethodMap` for method resolution and an `AssuranceMap`
+for type narrowing configuration, both with parent-class fallback for builder
+inheritance.
 
 The `generate` command reads the `#[FluentNamespace]` attribute from each
 builder, extracts the factory's resolver and namespaces, discovers classes,
 and uses `FluentResolver::unresolve()` to derive method names from class names.
 
-## vs. `@mixin`-style interfaces
-
-|                     | FluentAnalysis                      | `@mixin`                             |
-|---------------------|-------------------------------------|--------------------------------------|
-| Generated files     | None (one small neon cache)         | Interface files per builder + prefix |
-| Return type         | `Builder<array{A, B, C}>`           | `Builder` (via `@mixin`)             |
-| `getNodes()` type   | `array{A, B, C}` (exact tuple)      | `array<int, Node>` (generic)         |
-| Element access      | `$nodes[0]` typed as `A`            | `mixed`                              |
-| Deprecation         | Forwarded automatically             | Must regenerate                      |
-| Composable prefixes | Resolved from cache                 | Full method signatures               |
-| IDE support         | PHPStan-powered (PhpStorm, VS Code) | Direct IDE autocomplete              |
-| Maintenance         | Re-run `generate` on class changes  | Manual/generated                     |
-
-Both approaches work. Use FluentAnalysis for precise type tracking. Use `@mixin`s
-for broader IDE autocomplete without PHPStan.
+## FluentAnalysis vs FluentGen
+
+Another similar project is [FluentGen](https://github.com/Respect/FluentGen).
+
+Both are complementary, offering IDE support and type inference as separate packages.
+
+|                     | FluentAnalysis                       | FluentGen                            |
+|---------------------|--------------------------------------|--------------------------------------|
+| Generated files     | None (one small neon cache)          | Interface files per builder + prefix |
+| Return type         | `Builder<array{A, B, C}>`            | `Builder` (via `@mixin`)             |
+| `getNodes()` type   | `array{A, B, C}` (exact tuple)       | `array<int, Node>` (generic)         |
+| Element access      | `$nodes[0]` typed as `A`             | `mixed`                              |
+| Deprecation         | Forwarded automatically              | Must regenerate                      |
+| Composable prefixes | Resolved from cache                  | Full method signatures               |
+| Type narrowing      | Assertion methods narrow input types | Not supported                        |
+| IDE support         | PHPStan-powered (PhpStorm, VS Code)  | Direct IDE autocomplete              |
+| Maintenance         | Re-run `generate` on class changes   | Manual/generated                     |

composer.json

@@ -6,7 +6,7 @@
     "require": {
         "php": "^8.5",
         "phpstan/phpstan": "^2.1",
-        "respect/fluent": "^1.0",
+        "respect/fluent": "^2.0",
         "symfony/console": "^6.0|^7.0"
     },
     "require-dev": {

composer.lock

@@ -1,10 +1,14 @@
 parameters:
 	fluent:
 		methods: []
+		assurances: []
+		assertions: []
 
 parametersSchema:
 	fluent: structure([
-		methods: arrayOf(arrayOf(string()))
+		methods: arrayOf(arrayOf(string())),
+		assurances: arrayOf(arrayOf(arrayOf(anyOf(string(), int(), listOf(anyOf(int(), type('null'))))))),
+		assertions: arrayOf(listOf(string()))
 	])
 
 services:
@@ -13,6 +17,12 @@ services:
 		arguments:
 			methods: %fluent.methods%
 
+	fluentAssuranceMap:
+		class: Respect\FluentAnalysis\AssuranceMap
+		arguments:
+			assurances: %fluent.assurances%
+			assertions: %fluent.assertions%
+
 	-
 		class: Respect\FluentAnalysis\FluentMethodsExtension
 		arguments:
@@ -24,6 +34,16 @@ services:
 		class: Respect\FluentAnalysis\FluentDynamicReturnTypeExtension
 		arguments:
 			methodMap: @fluentMethodMap
+			assuranceMap: @fluentAssuranceMap
+			targetClass: Respect\Fluent\Builders\FluentBuilder
 		tags:
 			- phpstan.broker.dynamicMethodReturnTypeExtension
 			- phpstan.broker.dynamicStaticMethodReturnTypeExtension
+
+	-
+		class: Respect\FluentAnalysis\FluentTypeSpecifyingExtension
+		arguments:
+			assuranceMap: @fluentAssuranceMap
+			targetClass: Respect\Fluent\Builders\FluentBuilder
+		tags:
+			- phpstan.typeSpecifier.methodTypeSpecifyingExtension

extension.neon

@@ -17,6 +17,10 @@
     <!-- PHPStan fixtures require global functions and assertType strings use long FQCNs -->
     <rule ref="Squiz.Functions.GlobalFunction.Found">
         <exclude-pattern>tests/fixtures/</exclude-pattern>
+        <exclude-pattern>tests/assertions/</exclude-pattern>
+    </rule>
+    <rule ref="Squiz.Commenting.FunctionComment.WrongStyle">
+        <exclude-pattern>tests/assertions/</exclude-pattern>
     </rule>
     <rule ref="Generic.Files.LineLength.TooLong">
         <exclude-pattern>tests/assertions/</exclude-pattern>

phpcs.xml.dist

@@ -21,9 +21,11 @@
             <directory>src</directory>
         </include>
         <exclude>
-            <!-- Runs inside PHPStan's DI container; not reachable by Xdebug.
+            <!-- Run inside PHPStan's DI container; not reachable by Xdebug.
                  Covered by Integration/TypeInference assertType tests. -->
             <file>src/FluentDynamicReturnTypeExtension.php</file>
+            <file>src/FluentTypeSpecifyingExtension.php</file>
+            <file>src/ExtractsAssurance.php</file>
         </exclude>
     </source>
 </phpunit>

phpunit.xml.dist

@@ -0,0 +1,73 @@
+<?php
+
+/*
+ * SPDX-License-Identifier: ISC
+ * SPDX-FileCopyrightText: (c) Respect Project Contributors
+ * SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+ */
+
+declare(strict_types=1);
+
+namespace Respect\FluentAnalysis;
+
+use PHPStan\Reflection\ClassReflection;
+
+use function in_array;
+
+/**
+ * @phpstan-type AssuranceEntry array{
+ *     type?: string,
+ *     parameterIndex?: int,
+ *     from?: string,
+ *     compose?: string,
+ *     composeRange?: array{int, int|null},
+ *     wrapperModifier?: string,
+ * }
+ */
+final readonly class AssuranceMap
+{
+    /**
+     * @param array<string, array<string, AssuranceEntry>> $assurances
+     * @param array<string, list<string>> $assertions
+     */
+    public function __construct(
+        private array $assurances = [],
+        private array $assertions = [],
+    ) {
+    }
+
+    /** @return AssuranceEntry|null */
+    public function resolveAssurance(ClassReflection $classReflection, string $methodName): array|null
+    {
+        $className = $classReflection->getName();
+
+        if (isset($this->assurances[$className][$methodName])) {
+            return $this->assurances[$className][$methodName];
+        }
+
+        foreach ($this->assurances as $registeredClass => $methods) {
+            if ($classReflection->is($registeredClass) && isset($methods[$methodName])) {
+                return $methods[$methodName];
+            }
+        }
+
+        return null;
+    }
+
+    public function isAssertionMethod(ClassReflection $classReflection, string $methodName): bool
+    {
+        $className = $classReflection->getName();
+
+        if (isset($this->assertions[$className])) {
+            return in_array($methodName, $this->assertions[$className], true);
+        }
+
+        foreach ($this->assertions as $registeredClass => $methods) {
+            if ($classReflection->is($registeredClass) && in_array($methodName, $methods, true)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}