Psalm

.github/workflows/ci.yml

@@ -9,3 +9,5 @@ on:
 jobs:
   build:
     uses: Exanlv/ci/.github/workflows/php-unit-tests.yml@main
+  psalm:
+    uses: Exanlv/ci/.github/workflows/psalm-l1.yml@main

composer.json

@@ -16,16 +16,24 @@
             "Tests\\": "tests"
         }
     },
+    "require": {
+        "php": "^8.4"
+    },
     "require-dev": {
-        "php": "^8.4",
         "symfony/var-dumper": "^7.4",
         "phpunit/phpunit": "^11.5",
         "friendsofphp/php-cs-fixer": "^3.92",
-        "exan/pudocumenter": "^0.1.7"
+        "exan/pudocumenter": "^0.1.7",
+        "vimeo/psalm": "^6.16"
     },
     "scripts": {
         "test": "phpunit tests",
 
+        "psalm": "psalm --no-cache",
+
+        "psalm-fix": "psalm --no-cache --alter --issues=MissingReturnType,MissingClosureReturnType,InvalidReturnType,InvalidNullableReturnType,InvalidFalsableReturnType,MissingParamType,MissingPropertyType,MismatchingDocblockParamType,MismatchingDocblockReturnType,LessSpecificReturnType,PossiblyUndefinedVariable,PossiblyUndefinedGlobalVariable,UnusedMethod,PossiblyUnusedMethod,UnusedProperty,PossiblyUnusedProperty,UnusedVariable,UnnecessaryVarAnnotation,ParamNameMismatch",
+
+
         "csf": "php-cs-fixer fix --using-cache=no --allow-risky=yes",
         "cs": "php-cs-fixer fix --using-cache=no --allow-risky=yes --dry-run"
     }

psalm.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0"?>
+<psalm
+    errorLevel="4"
+    resolveFromConfigFile="true"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://getpsalm.org/schema/config"
+    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+    findUnusedBaselineEntry="true"
+    findUnusedCode="true"
+>
+    <projectFiles>
+        <directory name="src" />
+        <ignoreFiles>
+            <directory name="vendor" />
+        </ignoreFiles>
+    </projectFiles>
+
+    <issueHandlers>
+        <PossiblyUnusedMethod errorLevel="suppress" />
+        <PossiblyUnusedProperty errorLevel="suppress" />
+        <PossiblyUnusedParam errorLevel="suppress" />
+        <PossiblyUnusedReturnValue errorLevel="suppress" />
+        <UnusedMethod errorLevel="suppress" />
+        <UnusedProperty errorLevel="suppress" />
+        <UnusedVariable errorLevel="suppress" />
+        <UnusedClass errorLevel="suppress" />
+        <ClassMustBeFinal errorLevel="suppress" />
+    </issueHandlers>
+</psalm>

src/Analyzer/Dto/Yanked.php

@@ -9,6 +9,6 @@
     public function __construct(
         public ?array $namespace,
         public array $uses,
-        public ?array $args,
+        public ?array $arg,
     ) {}
 }

src/Analyzer/Extractor/Nemaspace.php

@@ -15,7 +15,7 @@
 class Nemaspace
 {
     public function __construct(
-        private readonly TokenEmitter $tokenEmitter,
+        public readonly TokenEmitter $tokenEmitter,
         private ?array &$namespace,
     ) {
         $this->tokenEmitter->on(TokenFilter::ofType(T_NAMESPACE), function (array $token): void {

src/Analyzer/TokenEmitter.php

@@ -10,10 +10,13 @@
 class TokenEmitter
 {
     /**
-     * @var array<int, array{match: Closure, handler: Closure, once: bool}>
+     * @var array<int, array{match?: Closure, handler: Closure, once?: bool}>
      */
     private array $handlers = [];
 
+    /**
+     * @psalm-return int<100000, 999999>
+     */
     public function on(Closure $match, Closure $handler): int
     {
         $id = $this->getId();
@@ -22,6 +25,9 @@ public function on(Closure $match, Closure $handler): int
         return $id;
     }
 
+    /**
+     * @psalm-return int<100000, 999999>
+     */
     public function onLineChange(Closure $handler): int
     {
         $line = 0;
@@ -38,6 +44,9 @@ public function onLineChange(Closure $handler): int
         });
     }
 
+    /**
+     * @psalm-return int<100000, 999999>
+     */
     public function all(Closure $handler): int
     {
         $id = $this->getId();
@@ -52,6 +61,11 @@ public function once(Closure $match, Closure $handler): void
         $this->handlers[$id] = ['match' => $match, 'handler' => $handler, 'once' => true];
     }
 
+    /**
+     * @return int[]
+     *
+     * @psalm-return list{int<100000, 999999>, int<100000, 999999>}
+     */
     public function counter(Closure $up, Closure $down, int &$value): array
     {
         return [
@@ -71,6 +85,9 @@ public function remove(int ...$ids): void
         }
     }
 
+    /**
+     * @psalm-return int<100000, 999999>
+     */
     private function getId(): int
     {
         do {

src/Analyzer/TokenFilter.php

@@ -9,16 +9,25 @@
 /** @internal */
 class TokenFilter
 {
-    public static function eq(mixed $value): Closure
+    /**
+     * @psalm-return Closure(array|string):bool
+     */
+    public static function eq(string $value): Closure
     {
         return fn (array|string $token) => $token === $value;
     }
 
+    /**
+     * @psalm-return Closure(array|string):bool
+     */
     public static function ofType(int $type): Closure
     {
         return fn (array|string $token) => is_array($token) && $token[0] === $type;
     }
 
+    /**
+     * @psalm-return Closure(array|string):bool
+     */
     public static function any(Closure ...$closures): Closure
     {
         return function (array|string $token) use ($closures) {

src/Analyzer/Utilize.php

@@ -40,15 +40,19 @@ private function format(string $fullyQualifiedClass): string
      * @param string $declaringNamespace
      * @param array<int, array<int, string|array{0:int, 1:string, 2:int}>> $uses
      */
-    public static function fromTokens(?string $declaringNamespace, array $uses): static
+    public static function fromTokens(?string $declaringNamespace, array $uses): self
     {
         $convertedUses = array_merge(...array_map(static::parseLine(...), $uses));
 
-        return new static($declaringNamespace, array_merge(...$convertedUses));
+        return new self($declaringNamespace, array_merge(...$convertedUses));
     }
 
     /**
      * @param array<int, string|array{0:int, 1:string, 2:int}> $line
+     *
+     * @return array[]
+     *
+     * @psalm-return array<int<0, max>, array>
      */
     private static function parseLine($line): array
     {
@@ -61,7 +65,10 @@ private static function parseLine($line): array
 
     /**
      * @param array<int, string|array{0:int, 1:string, 2:int}> $tokens
-     * @return array<int, array<int, string|array{0:int, 1:string, 2:int}>>
+     *
+     * @return ((int|string)[]|string)[][]
+     *
+     * @psalm-return array<int<0, max>, list<array{0: int, 1: string, 2: int}|string>>
      */
     private static function individualUses($tokens): array
     {
@@ -103,11 +110,16 @@ private static function parseIndividualUse(array $use): array
         }
 
         if (count($use) === 5 && is_array($use[2]) && $use[2][1] === 'as') {
-            // use Some\Potentially\Namespaced\Class as Alias
+            // use Some\Class as Alias
+
+            /** @var array{0: int, 1: string, 2: int} */
             $trueImport = array_shift($use);
+            /** @var array{0: int, 1: string, 2: int} */
             $alias = array_pop($use);
 
-            return [$alias[1] => $trueImport[1]];
+            return [
+                $alias[1] => $trueImport[1],
+            ];
         }
 
         // use Some\Potentially\Namespaced\{Class, Or\Other\Class}
@@ -116,6 +128,10 @@ private static function parseIndividualUse(array $use): array
 
     /**
      * @param array<int, string|array{0:int, 1:string, 2:int}> $tokens
+     *
+     * @return string[]
+     *
+     * @psalm-return array<string, string>
      */
     private static function parseGroupUse(array $tokens): array
     {
@@ -132,7 +148,7 @@ private static function parseGroupUse(array $tokens): array
         $imports = static::splitGroupUse($tokens);
 
         return array_merge(...array_map(function (array $tokens) use ($namespacePrefix) {
-            while (count($tokens) && is_array($tokens) && $tokens[0][0] === T_WHITESPACE) {
+            while (count($tokens) && is_array($tokens[0]) && $tokens[0][0] === T_WHITESPACE) {
                 array_shift($tokens);
             }
 
@@ -152,7 +168,10 @@ private static function parseGroupUse(array $tokens): array
 
     /**
      * @param array<int, string|array{0:int, 1:string, 2:int}> $tokens
-     * @return array<int, array<int, string|array{0:int, 1:string, 2:int}>>
+     *
+     * @return ((int|string)[]|string)[][]
+     *
+     * @psalm-return array<int<0, max>, list<array{0: int, 1: string, 2: int}|string>>
      */
     private static function splitGroupUse(array $tokens): array
     {

src/Args/Arr.php

@@ -8,11 +8,17 @@
 
 class Arr
 {
+    /**
+     * @psalm-return Closure(array):bool
+     */
     public static function count(int $expectedCount): Closure
     {
         return fn (array $actual): bool => count($actual) === $expectedCount;
     }
 
+    /**
+     * @psalm-return Closure(array):bool
+     */
     public static function partial(array $expectation): Closure
     {
         $validator = function (array $actual, array $expectation) use (&$validator): bool {

src/Args/Date.php

@@ -9,11 +9,17 @@
 
 class Date
 {
+    /**
+     * @psalm-return Closure(DateTimeInterface):bool
+     */
     public static function before(DateTimeInterface $beforeDate): Closure
     {
         return fn (DateTimeInterface $date): bool => $date < $beforeDate;
     }
 
+    /**
+     * @psalm-return Closure(DateTimeInterface):bool
+     */
     public static function after(DateTimeInterface $beforeDate): Closure
     {
         return fn (DateTimeInterface $date): bool => $date > $beforeDate;

src/Args/Number.php

@@ -8,16 +8,25 @@
 
 class Number
 {
+    /**
+     * @psalm-return Closure(float|int):bool
+     */
     public static function lt(int|float $lessThan): Closure
     {
         return fn (int|float $actual): bool => $actual < $lessThan;
     }
 
+    /**
+     * @psalm-return Closure(float|int):bool
+     */
     public static function gt(int|float $greaterThan): Closure
     {
         return fn (int|float $actual): bool => $actual > $greaterThan;
     }
 
+    /**
+     * @psalm-return Closure(float|int):bool
+     */
     public static function range(int|float $min, int|float $max): Closure
     {
         return fn (int|float $actual): bool => $actual >= $min && $actual <= $max;

src/Args/Str.php

@@ -8,11 +8,17 @@
 
 class Str
 {
+    /**
+     * @psalm-return Closure(string):bool
+     */
     public static function length(int $expectedLength): Closure
     {
         return fn (string $actual): bool => strlen($actual) === $expectedLength;
     }
 
+    /**
+     * @psalm-return Closure(string):bool
+     */
     public static function contains(string $needle): Closure
     {
         return fn (string $actual): bool => str_contains(strtolower($actual), strtolower($needle));

src/Class/Mocker.php

@@ -16,7 +16,8 @@
 class Mocker
 {
     public private(set) array $interfaces = [];
-    public private(set) string $extends;
+    /** @var null|class-string */
+    public private(set) ?string $extends = null;
 
     public function getCode(): string
     {
@@ -37,7 +38,7 @@ public function getCode(): string
 
         $creator = 'return new class ';
 
-        if (isset($this->extends)) {
+        if ($this->extends !== null) {
             $parent = str_contains($this->extends, '@anonymous')
                 ? get_parent_class($this->extends)
                 : $this->extends;

src/Expectation.php

@@ -35,6 +35,9 @@ public function with(mixed ...$expectedArg): Expectation
         return new Expectation($this->classMock, $this->methodName, $filteredCalls, $this->expectation);
     }
 
+    /**
+     * @psalm-return int<0, max>
+     */
     private function callsAmount(): int
     {
         return count($this->calls);
@@ -75,6 +78,9 @@ public function dd(): never
             dd($data);
         }
 
+        /**
+         * @psalm-suppress ForbiddenCode
+         */
         var_dump($this->calls);
         die();
     }

src/Expector/Expectation.php

@@ -15,7 +15,7 @@ class Expectation
 {
     use FiltersMethodArgs;
 
-    public private(set) array $with;
+    public private(set) ?array $with = null;
 
     private MockedClassInterface $mock;
 
@@ -44,7 +44,7 @@ public function matches(DetailedMethodCall $call): bool
             return false;
         }
 
-        if (isset($this->with) && empty(
+        if ($this->with !== null && empty(
             $this->filterArgs([$call->call->args], $this->with)
         )) {
             return false;