Add IDE type narrowing to generated validator mixins

Make validator chains narrow types for IDEs and PHPStan without the
FluentAnalysis extension, driven entirely by the generated src/Mixins PHPDoc.

- Annotate src/Validators with #[Assurance] / #[AssuranceSubject] declaring
  each rule's assured type.
- Regenerate src/Mixins: Chain becomes generic (@template-covariant TSure);
  static entry methods narrow to Chain<concrete>; assert()/check() carry an
  unconditional @phpstan-assert TSure. Container rules (key/property/length/
  max/min) and the concrete prefix forms (nullOrIntType, keyIntType,
  allIntType) narrow; argument-wrapping and compose forms stay Chain<mixed>
  so a raw (non-fluent) Validator argument is still accepted.
- isValid() intentionally does not narrow: its only conditional form is a
  two-way guard, unsound for inexact rules on the false branch.
- Add the tests/inference static-narrowing suite (no extension config) and
  run it in CI; scope the phpstan/phpcs accommodations for generated mixins.

Author: alganet

.github/workflows/ci-code.yml

@@ -27,6 +27,7 @@ jobs:
 
       - run: composer phpunit
       - run: composer pest
+      - run: composer inference
 
   code-coverage:
     name: Code Coverage

composer.json

@@ -5,6 +5,8 @@
     "type": "library",
     "homepage": "http://respect.github.io/",
     "license": "MIT",
+    "minimum-stability": "dev",
+    "prefer-stable": true,
     "authors": [
         {
             "name": "Respect/Validation Contributors",
@@ -23,7 +25,7 @@
         "php": ">=8.5",
         "psr/container": "^2.0",
         "respect/config": "^3.0",
-        "respect/fluent": "^2.0",
+        "respect/fluent": "3.0.x-dev",
         "respect/parameter": "^3.0",
         "respect/string-formatter": "^1.7",
         "respect/stringifier": "^3.0",
@@ -45,7 +47,7 @@
         "psr/http-message": "^1.0 || ^2.0",
         "ramsey/uuid": "^4",
         "respect/coding-standard": "^5.0",
-        "respect/fluentgen": "^2.0",
+        "respect/fluentgen": "2.1.x-dev",
         "sebastian/diff": "^7.0",
         "sokil/php-isocodes": "^4.2.1",
         "sokil/php-isocodes-db-only": "^4.0",
@@ -87,6 +89,7 @@
         "phpcs": "vendor/bin/phpcs",
         "phpstan": "vendor/bin/phpstan analyze",
         "phpunit": "vendor/bin/phpunit --testsuite=unit",
+        "inference": "vendor/bin/phpunit --testsuite=inference",
         "smoke-complete": "bin/console smoke-tests:check-complete",
         "spdx-lint": "bin/console lint:spdx",
         "qa": [
@@ -95,6 +98,7 @@
             "@phpstan",
             "@phpunit",
             "@pest",
+            "@inference",
             "@docs",
             "@smoke-complete"
         ]

composer.lock

@@ -15,6 +15,9 @@
     <file>src-dev/</file>
     <file>tests/</file>
 
+    <!-- PHPStan type-inference fixtures: intentional global functions + assertType() calls. -->
+    <exclude-pattern>tests/inference/assertions/*</exclude-pattern>
+
     <rule ref="Respect" />
 
     <!-- Exclusions -->
@@ -28,6 +31,21 @@
         <exclude-pattern>src/Mixins/</exclude-pattern>
         <exclude-pattern>tests/feature/</exclude-pattern>
     </rule>
+    <!-- Generated mixin docblocks carry @template/@param/@return narrowing types whose
+         formatting (annotation groups, fully-qualified class names, bare iterable item
+         types, null ordering) is the generator's concern, not hand-maintained style. -->
+    <rule ref="SlevomatCodingStandard.Commenting.DocCommentSpacing">
+        <exclude-pattern>src/Mixins/</exclude-pattern>
+    </rule>
+    <rule ref="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly.ReferenceViaFullyQualifiedName">
+        <exclude-pattern>src/Mixins/</exclude-pattern>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingTraversableTypeHintSpecification">
+        <exclude-pattern>src/Mixins/</exclude-pattern>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.NullTypeHintOnLastPosition">
+        <exclude-pattern>src/Mixins/</exclude-pattern>
+    </rule>
     <rule ref="SlevomatCodingStandard.Functions.StaticClosure.ClosureNotStatic">
         <exclude-pattern>tests/Pest.php</exclude-pattern>
         <exclude-pattern>tests/feature</exclude-pattern>

phpcs.xml.dist

@@ -23,6 +23,16 @@ parameters:
       path: tests/src/Message/TestingHandler.php
     - message: '/Property Respect\\Validation\\Test\\Stubs\\.+::\$[a-zA-Z]+ is never read, only written./'
       path: tests/src/Stubs
+    -
+      # Why: src/Mixins/* are generated typing aids. Their @return Chain<...> carry the
+      # narrowing types derived from #[Assurance] (the same ones FluentAnalysis computes
+      # at analysis time), e.g. bare `array` or `ArrayAccess`. Fully parameterising those
+      # generics would only clutter the IDE-facing types without adding narrowing value.
+      identifier: missingType.iterableValue
+      path: src/Mixins/*
+    -
+      identifier: missingType.generics
+      path: src/Mixins/*
   level: 8
   treatPhpDocTypesAsCertain: false
   paths:

phpstan.neon.dist

@@ -14,6 +14,9 @@
     <testsuite name="feature">
       <directory suffix="Test.php">./tests/feature</directory>
     </testsuite>
+    <testsuite name="inference">
+      <directory suffix="Test.php">tests/inference/</directory>
+    </testsuite>
   </testsuites>
   <source>
     <include>

phpunit.xml.dist

@@ -18,6 +18,7 @@
 use Respect\FluentGen\Fluent\MethodBuilder;
 use Respect\FluentGen\Fluent\MixinGenerator;
 use Respect\FluentGen\Fluent\PrefixConstantsGenerator;
+use Respect\FluentGen\Fluent\TerminalMethod;
 use Respect\FluentGen\NamespaceScanner;
 use Respect\Validation\Mixins\Chain;
 use Respect\Validation\Validator;
@@ -82,13 +83,37 @@ interfaces: [
                     suffix: 'Builder',
                     returnType: Chain::class,
                     static: true,
+                    emitNarrowing: true,
                 ),
                 new InterfaceConfig(
                     suffix: 'Chain',
                     returnType: Chain::class,
                     rootExtends: [Validator::class],
                     rootComment: '@mixin ValidatorBuilder',
                     rootUses: [ValidatorBuilder::class],
+                    emitNarrowing: true,
+                    templateParam: 'TSure',
+                    terminalMethods: [
+                        new TerminalMethod(
+                            name: 'assert',
+                            returnType: 'void',
+                            parameters: ['input' => 'mixed'],
+                            comments: ['@phpstan-assert TSure $input', '@psalm-assert TSure $input'],
+                            optionalParameters: ['template' => 'mixed'],
+                        ),
+                        new TerminalMethod(
+                            name: 'check',
+                            returnType: 'void',
+                            parameters: ['input' => 'mixed'],
+                            comments: ['@phpstan-assert TSure $input', '@psalm-assert TSure $input'],
+                            optionalParameters: ['template' => 'mixed'],
+                        ),
+                        new TerminalMethod(
+                            name: 'isValid',
+                            returnType: 'bool',
+                            parameters: ['input' => 'mixed'],
+                        ),
+                    ],
                 ),
             ],
         );