Chore: Add Rector with safe rule bucket and CI refactor check (#247)

Introduces Rector for automated refactoring, wired up via:

- rector.php config targeting src/ and tests/ with PHP 8.3 level set
  plus CODE_QUALITY, DEAD_CODE, EARLY_RETURN, and INSTANCEOF sets.
  Rules with BC risk or behavioural shifts (readonly, explicit bool
  compare, empty() rewrites, type-hint additions, random_int swaps)
  are explicitly skipped.
- composer refactor / refactor:check scripts.
- Checks / Refactor CI job running rector in dry-run.
- Safe-bucket refactor applied across the codebase: strict_types
  declarations, #[\Override] attributes, str_contains / str_starts_with,
  null-coalescing, match over switch where safe, dead code removal,
  and docblock cleanup.

Author: loks0n

.github/workflows/ci.yml

@@ -48,6 +48,34 @@ jobs:
       - name: PHPStan
         run: composer analyze
 
+  refactor:
+    name: Checks / Refactor
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          extensions: swoole
+          coverage: none
+
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/cache@v5
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: composer-${{ hashFiles('composer.lock') }}
+          restore-keys: composer-
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-interaction --ignore-platform-req=ext-opentelemetry
+
+      - name: Rector (dry run)
+        run: composer refactor:check
+
   unit:
     name: Tests / Unit / PHP ${{ matrix.php }}
     runs-on: ubuntu-latest

composer.json

@@ -25,6 +25,8 @@
         "format": "vendor/bin/pint",
         "format:check": "vendor/bin/pint --test",
         "analyze": "vendor/bin/phpstan analyse -c phpstan.neon --memory-limit 512M",
+        "refactor": "vendor/bin/rector process",
+        "refactor:check": "vendor/bin/rector process --dry-run",
         "test": "vendor/bin/phpunit --configuration phpunit.xml"
     },
     "require": {
@@ -54,6 +56,7 @@
         "laravel/pint": "1.*",
         "phpstan/phpstan": "^2.0",
         "phpunit/phpunit": "^9.5.25",
+        "rector/rector": "^2.0",
         "swoole/ide-helper": "4.8.3"
     }
 }

composer.lock

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\CodeQuality\Rector\Empty_\SimplifyEmptyCheckOnEmptyArrayRector;
+use Rector\CodeQuality\Rector\Identical\FlipTypeControlToUseExclusiveTypeRector;
+use Rector\CodeQuality\Rector\If_\ExplicitBoolCompareRector;
+use Rector\CodeQuality\Rector\Ternary\SwitchNegatedTernaryRector;
+use Rector\Config\RectorConfig;
+use Rector\DeadCode\Rector\Cast\RecastingRemovalRector;
+use Rector\Strict\Rector\Empty_\DisallowedEmptyRuleFixerRector;
+use Rector\Php55\Rector\String_\StringClassNameToClassConstantRector;
+use Rector\Php70\Rector\FuncCall\RandomFunctionRector;
+use Rector\Php74\Rector\Property\RestoreDefaultNullToNullableTypePropertyRector;
+use Rector\Php80\Rector\Class_\ClassPropertyAssignToConstructorPromotionRector;
+use Rector\Php81\Rector\FuncCall\NullToStrictStringFuncCallArgRector;
+use Rector\Php81\Rector\Property\ReadOnlyPropertyRector;
+use Rector\Php82\Rector\Class_\ReadOnlyClassRector;
+use Rector\Set\ValueObject\LevelSetList;
+use Rector\Set\ValueObject\SetList;
+use Rector\TypeDeclaration\Rector\ClassMethod\ParamTypeByParentCallTypeRector;
+use Rector\TypeDeclaration\Rector\Property\TypedPropertyFromAssignsRector;
+use Rector\TypeDeclaration\Rector\Property\TypedPropertyFromStrictConstructorRector;
+
+return RectorConfig::configure()
+    ->withPaths([
+        __DIR__ . '/src',
+        __DIR__ . '/tests',
+    ])
+    ->withPhpSets(php83: true)
+    ->withSets([
+        LevelSetList::UP_TO_PHP_83,
+        SetList::CODE_QUALITY,
+        SetList::DEAD_CODE,
+        SetList::EARLY_RETURN,
+        SetList::INSTANCEOF,
+    ])
+    ->withImportNames(importShortClasses: false, removeUnusedImports: true)
+    ->withSkip([
+        // BC breaks in a published library
+        ReadOnlyPropertyRector::class,
+        ReadOnlyClassRector::class,
+
+        // Changes truthy semantics — "0", null, "" behave differently
+        ExplicitBoolCompareRector::class,
+        SimplifyEmptyCheckOnEmptyArrayRector::class,
+
+        // Can throw TypeError on previously-working callers (library is public API)
+        TypedPropertyFromAssignsRector::class,
+        TypedPropertyFromStrictConstructorRector::class,
+        ParamTypeByParentCallTypeRector::class,
+
+        // Different distribution and failure mode than rand()
+        RandomFunctionRector::class,
+
+        // Subtle casting/control-flow shifts — apply manually
+        RecastingRemovalRector::class,
+        FlipTypeControlToUseExclusiveTypeRector::class,
+        SwitchNegatedTernaryRector::class,
+        StringClassNameToClassConstantRector::class,
+
+        // Promoted properties / nullable defaults — BC shape changes for library
+        ClassPropertyAssignToConstructorPromotionRector::class,
+        RestoreDefaultNullToNullableTypePropertyRector::class,
+
+        // empty() replacement rarely covers every falsy case Rector's type info misses
+        DisallowedEmptyRuleFixerRector::class,
+
+        // Throws TypeError when args are objects/arrays — review per-call
+        NullToStrictStringFuncCallArgRector::class,
+    ]);

rector.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Utopia\Http;
 
 use Utopia\DI\Container;