feat: introduce assert_return() (#48)

Author: simPod

README.md

@@ -12,6 +12,23 @@
 Function that should have never been called. 
 Useful for `default` case in exhaustive matching.
 
+### assert_return()
+
+Asserts the value via the expression and returns it.
+
+It's useful when you want to assert inline so for example you can keep the arrow function in place.
+
+It uses native `assert()` internally.
+
+```php
+use function Cdn77\Functions\assert_return;
+
+array_map(
+    fn (mixed $value) => new RequiresInt(assert_return($value, is_int(...))),
+    [1, 2, 3]
+);
+```
+
 ### noop()
 
 Does nothing. Useful e.g. for `match` expression that currently supports single-line expressions in blocks.

composer-dependency-analyser.php

@@ -3,8 +3,23 @@
 declare(strict_types=1);
 
 use ShipMonk\ComposerDependencyAnalyser\Config\Configuration;
+use ShipMonk\ComposerDependencyAnalyser\Config\ErrorType;
 
 $config = new Configuration();
 
 return $config
+    ->ignoreErrorsOnPath(
+        'tests/AssertTest.php',
+        [ErrorType::UNKNOWN_FUNCTION],
+    )
+    ->ignoreErrorsOnPackageAndPaths(
+        'phpstan/phpstan',
+        ['phpstan'],
+        [ErrorType::DEV_DEPENDENCY_IN_PROD],
+    )
+    ->ignoreErrorsOnPackageAndPaths(
+        'nikic/php-parser',
+        ['phpstan'],
+        [ErrorType::SHADOW_DEPENDENCY],
+    )
     ->addPathToScan(__DIR__ . '/src', isDev: false);

composer.json

@@ -35,6 +35,9 @@
         "shipmonk/composer-dependency-analyser": "^1.5"
     },
     "autoload": {
+        "psr-4": {
+            "Cdn77\\Functions\\PHPStan\\": "phpstan"
+        },
         "files": [
             "src/functions_include.php"
         ]
@@ -53,5 +56,12 @@
             "phpstan/extension-installer": true
         },
         "sort-packages": true
+    },
+    "extra": {
+        "phpstan": {
+            "includes": [
+                "phpstan-extension.neon"
+            ]
+        }
     }
 }

phpcs.xml.dist

@@ -7,6 +7,7 @@
 
     <rule ref="Cdn77" />
 
+    <file>composer-dependency-analyser.php</file>
     <file>src/</file>
     <file>tests/</file>
 </ruleset>

phpstan-extension.neon

@@ -0,0 +1,5 @@
+services:
+  -
+    class: Cdn77\Functions\PHPStan\AssertReturnFunctionTypeSpecifyingExtension
+    tags:
+      - phpstan.typeSpecifier.functionTypeSpecifyingExtension

phpstan.neon.dist

@@ -1,5 +1,9 @@
+includes:
+    - phpstan-extension.neon
+
 parameters:
     level: max
     paths:
         - %currentWorkingDirectory%/src
+        - %currentWorkingDirectory%/phpstan
         - %currentWorkingDirectory%/tests

phpstan/AssertReturnFunctionTypeSpecifyingExtension.php

@@ -0,0 +1,37 @@
+<?php declare(strict_types = 1);
+
+namespace Cdn77\Functions\PHPStan;
+
+use PhpParser\Node\Expr\FuncCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Analyser\SpecifiedTypes;
+use PHPStan\Analyser\TypeSpecifier;
+use PHPStan\Analyser\TypeSpecifierAwareExtension;
+use PHPStan\Analyser\TypeSpecifierContext;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Type\FunctionTypeSpecifyingExtension;
+
+class AssertReturnFunctionTypeSpecifyingExtension implements FunctionTypeSpecifyingExtension, TypeSpecifierAwareExtension
+{
+    private TypeSpecifier $typeSpecifier;
+
+    public function isFunctionSupported(FunctionReflection $functionReflection, FuncCall $node, TypeSpecifierContext $context): bool
+    {
+        return $functionReflection->getName() === 'Cdn77\Functions\assert_return';
+//            && isset($node->getArgs()[0]);
+    }
+
+    public function specifyTypes(FunctionReflection $functionReflection, FuncCall $node, Scope $scope, TypeSpecifierContext $context): SpecifiedTypes
+    {
+        $arg1 = $node->getArgs()[1]->value;
+        assert($arg1 instanceof FuncCall, 'Second argument of assert_return must be a function call');
+        $new = new \PhpParser\Node\Expr\FuncCall($arg1->name, [$node->getArgs()[0]], $arg1->getAttributes());
+        return $this->typeSpecifier->specifyTypesInCondition($scope, $new, TypeSpecifierContext::createTruthy());
+    }
+
+    public function setTypeSpecifier(TypeSpecifier $typeSpecifier): void
+    {
+        $this->typeSpecifier = $typeSpecifier;
+    }
+
+}

src/assert.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cdn77\Functions;
+
+use Throwable;
+
+use function assert;
+
+/** @phpstan-pure */
+function assert_return(mixed $value, callable $assertionFn, Throwable|string|null $description = null): mixed
+{
+    assert($assertionFn($value), $description);
+
+    return $value;
+}

src/functions_include.php

@@ -3,6 +3,7 @@
 declare(strict_types=1);
 
 require_once __DIR__ . '/absurd.php';
+require_once __DIR__ . '/assert.php';
 require_once __DIR__ . '/ds.php';
 require_once __DIR__ . '/generator.php';
 require_once __DIR__ . '/iterable.php';

tests/AssertTest.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cdn77\Functions\Tests;
+
+use PHPUnit\Framework\Attributes\CoversFunction;
+use PHPUnit\Framework\TestCase;
+
+use function Cdn77\Functions\assert_return;
+use function is_int;
+use function PHPStan\Testing\assertType;
+
+#[CoversFunction('Cdn77\Functions\assert_return')]
+final class AssertTest extends TestCase
+{
+    public function testAssertReturn(): void
+    {
+        $value = 1;
+        self::assertSame(
+            $value,
+            assert_return($value, is_int(...)),
+        );
+    }
+
+    public function phpstanType(mixed $value): void
+    {
+        $_ = assert_return($value, is_int(...));
+
+        assertType('int', $value);
+    }
+}