fix(type-safety): eliminate 35 PHPStan level-9 errors across codebase

Runners (CsFixerRunner, PhpStanRunner, PhpUnitRunner, PsalmRunner,
RectorRunner, ComposerAuditRunner):
- Add #[Override] attribute to toolName(), vendorBin(), defaultArguments()

PhpStanConfigGenerator:
- Remove checkMissingIterableValueType and checkGenericClassInNonGenericObjectType
  (removed from PHPStan 2.x core; cause Invalid configuration errors)

CsFixerConfigGenerator:
- Add (string) cast on preg_replace() return values in exportRules()

Devkit.php:
- Add false !== guard before str_contains() in appendGitignore()
- Add SplFileInfo @var in removeRecursive() foreach

DevkitConfig.php:
- Add @var array<string, mixed> before assigning overrides
- Fix toolVersions() to filter array<string,string> via array_filter

MigrationDetector.php + MigrationReport.php:
- Add false !== guard on file_get_contents() and json_encode()
- Extract requireDev with @var and is_array() for type-safe access
- Fix removePackagesFromComposer() to write back updated requireDev
- Add SplFileInfo @var in removeRecursive() foreach

ProjectDetector.php:
- Add false !== guard on file_get_contents()
- Extract psr4Source, psr4Test, projectName with proper is_array() guards
- Fix detectNamespace(): double is_array() for autoload + psr-4 sub-access
- Fix detectPhpVersion(): use is_string() instead of (string) cast
- Precise @var annotations for all array parameters

Result: PHPStan level 9 -> 0 errors, PHPUnit 41/41 OK

Author: walmir-silva

bin/build-phar.php

@@ -0,0 +1,105 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Manual PHAR builder for kcode — bypasses Box chdir() bug on PHP 8.4
+ */
+
+$root    = dirname(__DIR__);
+$output  = $root . '/build/kcode.phar';
+
+if (file_exists($output)) {
+    unlink($output);
+}
+
+@mkdir($root . '/build', 0755, true);
+
+$phar = new Phar($output, 0, 'kcode.phar');
+$phar->startBuffering();
+
+echo "📦 Building kcode.phar...\n";
+
+// ── 1. Add src/ ────────────────────────────────────────────
+$added = 0;
+$srcDir = $root . '/src';
+$it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($srcDir, FilesystemIterator::SKIP_DOTS));
+foreach ($it as $file) {
+    if ($file->isFile() && $file->getExtension() === 'php') {
+        $relative = 'src/' . $it->getSubPathname();
+        $phar[$relative] = file_get_contents($file->getPathname());
+        $added++;
+    }
+}
+echo "  + src/: $added PHP files\n";
+
+// ── 2. Add vendor/ (PHP files only, no tests/docs) ─────────
+$vendorDir = $root . '/vendor';
+$excludeDirs = ['Tests', 'tests', 'test', 'doc', 'docs', 'examples', '.github'];
+
+$vendorIt = new RecursiveIteratorIterator(
+    new RecursiveDirectoryIterator($vendorDir, FilesystemIterator::SKIP_DOTS),
+    RecursiveIteratorIterator::LEAVES_ONLY
+);
+
+$vendorAdded = 0;
+foreach ($vendorIt as $file) {
+    if (!$file->isFile()) continue;
+    $path = $file->getPathname();
+    
+    // Skip test/doc directories
+    $skip = false;
+    foreach ($excludeDirs as $ex) {
+        if (str_contains($path, DIRECTORY_SEPARATOR . $ex . DIRECTORY_SEPARATOR)) {
+            $skip = true;
+            break;
+        }
+    }
+    if ($skip) continue;
+
+    // Only PHP and JSON files
+    $ext = $file->getExtension();
+    if (!in_array($ext, ['php', 'json'], true)) continue;
+
+    $relative = 'vendor/' . substr($path, strlen($vendorDir) + 1);
+    $phar[$relative] = file_get_contents($path);
+    $vendorAdded++;
+}
+echo "  + vendor/: $vendorAdded files\n";
+
+// ── 3. Add LICENSE ──────────────────────────────────────────
+$phar['LICENSE'] = file_get_contents($root . '/LICENSE');
+echo "  + LICENSE\n";
+
+// ── 4. Set bin/kcode as the entry point (stub) ─────────────
+$kcodeContent = file_get_contents($root . '/bin/kcode');
+$phar['bin/kcode'] = $kcodeContent;
+
+$stub = <<<'STUB'
+#!/usr/bin/env php
+<?php
+/*
+ * KaririCode Devkit — kcode
+ *
+ * Unified quality toolchain for KaririCode Framework.
+ *
+ * (c) Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+Phar::mapPhar('kcode.phar');
+require 'phar://kcode.phar/bin/kcode';
+__HALT_COMPILER();
+STUB;
+
+$phar->setStub($stub);
+echo "  + stub (bin/kcode entry point)\n";
+
+// ── 5. Finalize ─────────────────────────────────────────────
+$phar->stopBuffering();
+$phar->compressFiles(Phar::GZ);
+chmod($output, 0755);
+
+$size = round(filesize($output) / 1024 / 1024, 2);
+echo "\n✅ Built: $output ($size MB)\n";
+echo "   Files: " . count($phar) . "\n";

src/Command/AbstractCommand.php

@@ -24,27 +24,27 @@ abstract public function execute(Devkit $devkit, array $arguments): int;
 
     protected function info(string $message): void
     {
-        \fwrite(\STDOUT, "\033[32m✓\033[0m {$message}" . \PHP_EOL);
+        fwrite(\STDOUT, "\033[32m✓\033[0m {$message}" . \PHP_EOL);
     }
 
     protected function warning(string $message): void
     {
-        \fwrite(\STDOUT, "\033[33m⚠\033[0m {$message}" . \PHP_EOL);
+        fwrite(\STDOUT, "\033[33m⚠\033[0m {$message}" . \PHP_EOL);
     }
 
     protected function error(string $message): void
     {
-        \fwrite(\STDERR, "\033[31m✗\033[0m {$message}" . \PHP_EOL);
+        fwrite(\STDERR, "\033[31m✗\033[0m {$message}" . \PHP_EOL);
     }
 
     protected function line(string $message = ''): void
     {
-        \fwrite(\STDOUT, $message . \PHP_EOL);
+        fwrite(\STDOUT, $message . \PHP_EOL);
     }
 
     protected function banner(string $title): void
     {
-        $ruler = \str_repeat('─', 60);
+        $ruler = str_repeat('─', 60);
         $this->line("\033[36m{$ruler}\033[0m");
         $this->line("\033[1m  {$title}\033[0m");
         $this->line("\033[36m{$ruler}\033[0m");
@@ -65,15 +65,15 @@ protected function section(string $title): void
     protected function confirm(string $question, bool $default = false): bool
     {
         $hint = $default ? '[Y/n]' : '[y/N]';
-        \fwrite(\STDOUT, "\033[33m?\033[0m {$question} {$hint} ");
+        fwrite(\STDOUT, "\033[33m?\033[0m {$question} {$hint} ");
 
-        $input = \trim((string) \fgets(\STDIN));
+        $input = trim((string) fgets(\STDIN));
 
         if ('' === $input) {
             return $default;
         }
 
-        return \in_array(\strtolower($input), ['y', 'yes', 'sim', 's'], true);
+        return \in_array(strtolower($input), ['y', 'yes', 'sim', 's'], true);
     }
 
     // ── Argument Helpers ──────────────────────────────────────────
@@ -100,8 +100,8 @@ protected function option(array $arguments, string $key, ?string $default = null
         $prefix = "--{$key}=";
 
         foreach ($arguments as $arg) {
-            if (\str_starts_with($arg, $prefix)) {
-                return \substr($arg, \strlen($prefix));
+            if (str_starts_with($arg, $prefix)) {
+                return substr($arg, \strlen($prefix));
             }
         }
 
@@ -116,9 +116,9 @@ protected function option(array $arguments, string $key, ?string $default = null
      */
     protected function positional(array $arguments): array
     {
-        return \array_values(\array_filter(
+        return array_values(array_filter(
             $arguments,
-            static fn (string $arg): bool => !\str_starts_with($arg, '--'),
+            static fn (string $arg): bool => ! str_starts_with($arg, '--'),
         ));
     }
 
@@ -131,9 +131,9 @@ protected function positional(array $arguments): array
      */
     protected function passthrough(array $arguments, array $consume = []): array
     {
-        return \array_values(\array_filter(
+        return array_values(array_filter(
             $arguments,
-            static fn (string $arg): bool => !\in_array($arg, $consume, true),
+            static fn (string $arg): bool => ! \in_array($arg, $consume, true),
         ));
     }
 }

src/Command/AnalyseCommand.php

@@ -13,24 +13,27 @@
  */
 final class AnalyseCommand extends AbstractCommand
 {
+    #[\Override]
     public function name(): string
     {
         return 'analyse';
     }
 
+    #[\Override]
     public function description(): string
     {
         return 'Run static analysis (PHPStan + Psalm)';
     }
 
+    #[\Override]
     public function execute(Devkit $devkit, array $arguments): int
     {
         $this->banner('KaririCode Devkit — Analyse');
 
         $exitCode = 0;
 
         foreach (['phpstan', 'psalm'] as $tool) {
-            if (!$devkit->isToolAvailable($tool)) {
+            if (! $devkit->isToolAvailable($tool)) {
                 $this->warning("{$tool} not available — skipping");
 
                 continue;
@@ -44,7 +47,7 @@ public function execute(Devkit $devkit, array $arguments): int
                 $this->info(\sprintf('%s passed (%.2fs)', $tool, $result->elapsedSeconds));
             } else {
                 $this->error(\sprintf('%s failed — exit code %d (%.2fs)', $tool, $result->exitCode, $result->elapsedSeconds));
-                $exitCode = \max($exitCode, $result->exitCode);
+                $exitCode = max($exitCode, $result->exitCode);
             }
 
             $this->line();

src/Command/Application.php

@@ -33,7 +33,7 @@ public function register(AbstractCommand $command): void
     public function run(array $argv): int
     {
         // Strip script name
-        \array_shift($argv);
+        array_shift($argv);
 
         if ([] === $argv || $this->isHelp($argv)) {
             $this->printUsage();
@@ -47,20 +47,20 @@ public function run(array $argv): int
             return 0;
         }
 
-        $commandName = \array_shift($argv);
+        $commandName = array_shift($argv);
         $command = $this->commands[$commandName] ?? null;
 
         if (null === $command) {
-            \fwrite(\STDERR, "\033[31m✗\033[0m Unknown command: {$commandName}" . \PHP_EOL);
-            \fwrite(\STDERR, "  Run \033[1mkcode --help\033[0m for available commands." . \PHP_EOL);
+            fwrite(\STDERR, "\033[31m✗\033[0m Unknown command: {$commandName}" . \PHP_EOL);
+            fwrite(\STDERR, "  Run \033[1mkcode --help\033[0m for available commands." . \PHP_EOL);
 
             return 1;
         }
 
         try {
             return $command->execute($this->devkit, $argv);
         } catch (\Throwable $exception) {
-            \fwrite(\STDERR, "\033[31m✗\033[0m {$exception->getMessage()}" . \PHP_EOL);
+            fwrite(\STDERR, "\033[31m✗\033[0m {$exception->getMessage()}" . \PHP_EOL);
 
             return 1;
         }
@@ -82,7 +82,7 @@ private function isVersion(array $argv): bool
 
     private function printVersion(): void
     {
-        \fwrite(\STDOUT, \sprintf(
+        fwrite(\STDOUT, \sprintf(
             "\033[1mKaririCode Devkit\033[0m %s" . \PHP_EOL,
             Devkit::version(),
         ));
@@ -91,28 +91,28 @@ private function printVersion(): void
     private function printUsage(): void
     {
         $this->printVersion();
-        \fwrite(\STDOUT, \PHP_EOL);
-        \fwrite(\STDOUT, "\033[33mUsage:\033[0m" . \PHP_EOL);
-        \fwrite(\STDOUT, "  kcode <command> [options] [arguments]" . \PHP_EOL . \PHP_EOL);
-        \fwrite(\STDOUT, "\033[33mAvailable commands:\033[0m" . \PHP_EOL);
+        fwrite(\STDOUT, \PHP_EOL);
+        fwrite(\STDOUT, "\033[33mUsage:\033[0m" . \PHP_EOL);
+        fwrite(\STDOUT, "  kcode <command> [options] [arguments]" . \PHP_EOL . \PHP_EOL);
+        fwrite(\STDOUT, "\033[33mAvailable commands:\033[0m" . \PHP_EOL);
 
         $maxLen = 0;
 
         foreach ($this->commands as $name => $command) {
-            $maxLen = \max($maxLen, \strlen($name));
+            $maxLen = max($maxLen, \strlen($name));
         }
 
         foreach ($this->commands as $name => $command) {
-            \fwrite(\STDOUT, \sprintf(
+            fwrite(\STDOUT, \sprintf(
                 "  \033[32m%-{$maxLen}s\033[0m  %s" . \PHP_EOL,
                 $name,
                 $command->description(),
             ));
         }
 
-        \fwrite(\STDOUT, \PHP_EOL);
-        \fwrite(\STDOUT, "\033[33mOptions:\033[0m" . \PHP_EOL);
-        \fwrite(\STDOUT, "  \033[32m-h, --help\033[0m     Show this help" . \PHP_EOL);
-        \fwrite(\STDOUT, "  \033[32m-V, --version\033[0m  Show version" . \PHP_EOL);
+        fwrite(\STDOUT, \PHP_EOL);
+        fwrite(\STDOUT, "\033[33mOptions:\033[0m" . \PHP_EOL);
+        fwrite(\STDOUT, "  \033[32m-h, --help\033[0m     Show this help" . \PHP_EOL);
+        fwrite(\STDOUT, "  \033[32m-V, --version\033[0m  Show version" . \PHP_EOL);
     }
 }

src/Command/CleanCommand.php

@@ -13,16 +13,19 @@
  */
 final class CleanCommand extends AbstractCommand
 {
+    #[\Override]
     public function name(): string
     {
         return 'clean';
     }
 
+    #[\Override]
     public function description(): string
     {
         return 'Remove .kcode/build/ (caches, coverage, reports)';
     }
 
+    #[\Override]
     public function execute(Devkit $devkit, array $arguments): int
     {
         $this->banner('KaririCode Devkit — Clean');

src/Command/CsFixCommand.php

@@ -13,16 +13,19 @@
  */
 final class CsFixCommand extends AbstractCommand
 {
+    #[\Override]
     public function name(): string
     {
         return 'cs:fix';
     }
 
+    #[\Override]
     public function description(): string
     {
         return 'Fix code style (--check for dry-run)';
     }
 
+    #[\Override]
     public function execute(Devkit $devkit, array $arguments): int
     {
         $dryRun = $this->hasFlag($arguments, '--check', '--dry-run');

src/Command/FormatCommand.php

@@ -13,16 +13,19 @@
  */
 final class FormatCommand extends AbstractCommand
 {
+    #[\Override]
     public function name(): string
     {
         return 'format';
     }
 
+    #[\Override]
     public function description(): string
     {
         return 'Apply all formatting (cs:fix + rector --fix)';
     }
 
+    #[\Override]
     public function execute(Devkit $devkit, array $arguments): int
     {
         $this->banner('KaririCode Devkit — Format');
@@ -55,7 +58,7 @@ public function execute(Devkit $devkit, array $arguments): int
                 $this->info(\sprintf('Rector done (%.2fs)', $result->elapsedSeconds));
             } else {
                 $this->error(\sprintf('Rector failed (%.2fs)', $result->elapsedSeconds));
-                $exitCode = \max($exitCode, $result->exitCode);
+                $exitCode = max($exitCode, $result->exitCode);
             }
         }