style: satisfy Psalm errorLevel 1 and deprecate ActiveRecord TransactionException

- Make leaf classes final (Facade, ConfigurationException, the Spiral/Laravel bridges) and mark ActiveQuery/ActiveRepository as @api since they are user extension points.
- Add the #[\Override] attributes and purity/immutability annotations Psalm requires at errorLevel 1, and type the repository $orderBy argument.
- Deprecate Cycle\ActiveRecord\Exception\Transaction\TransactionException, aliasing it to Cycle\Transaction\Exception\TransactionException (mirroring TransactionMode); the @throws now reference the cycle/transaction exception.
- Consolidate the IDE/static-analysis stubs into resources/stubs.php.

Author: roxblnfk

composer.lock

@@ -22,6 +22,6 @@
         </ignoreFiles>
     </projectFiles>
     <stubs>
-        <file name="stubs/TransactionMode.php"/>
+        <file name="resources/stubs.php"/>
     </stubs>
 </psalm>

psalm.xml

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\ActiveRecord\Exception\Transaction;
+
+/**
+ * IDE/static-analysis stub. It is never loaded at runtime — the real
+ * {@see TransactionException} is an alias of
+ * {@see \Cycle\Transaction\Exception\TransactionException} created in
+ * src/Exception/Transaction/TransactionException.php.
+ *
+ * @deprecated Use {@see \Cycle\Transaction\Exception\TransactionException} instead.
+ */
+final class TransactionException extends \RuntimeException {}
+
+namespace Cycle\ActiveRecord;
+
+/**
+ * IDE/static-analysis stub. It is never loaded at runtime — the real
+ * {@see TransactionMode} is an alias of
+ * {@see \Cycle\Transaction\TransactionMode} created in src/TransactionMode.php.
+ *
+ * @deprecated Use {@see \Cycle\Transaction\TransactionMode} instead.
+ */
+enum TransactionMode
+{
+    case Ignore;
+    case Current;
+    case OpenNew;
+}

resources/stubs.php

@@ -4,7 +4,6 @@
 
 namespace Cycle\ActiveRecord;
 
-use Cycle\ActiveRecord\Exception\Transaction\TransactionException;
 use Cycle\ActiveRecord\Internal\TransactionFacade;
 use Cycle\ActiveRecord\Query\ActiveQuery;
 use Cycle\Database\DatabaseInterface;
@@ -13,6 +12,7 @@
 use Cycle\ORM\ORMInterface;
 use Cycle\ORM\RepositoryInterface;
 use Cycle\ORM\SchemaInterface;
+use Cycle\Transaction\Exception\TransactionException;
 use Cycle\Transaction\TransactionMode;
 
 /**

src/ActiveRecord.php

@@ -7,8 +7,12 @@
 use Cycle\ActiveRecord\Facade;
 use Illuminate\Support\ServiceProvider;
 
-class ActiveRecordProvider extends ServiceProvider
+final class ActiveRecordProvider extends ServiceProvider
 {
+    /**
+     * @psalm-external-mutation-free
+     */
+    #[\Override]
     public function register(): void
     {
         Facade::setContainer($this->app);

src/Bridge/Laravel/Providers/ActiveRecordProvider.php

@@ -9,15 +9,22 @@
 use Spiral\Boot\Bootloader\Bootloader;
 use Spiral\Cycle\Bootloader\CycleOrmBootloader;
 
-class ActiveRecordBootloader extends Bootloader
+final class ActiveRecordBootloader extends Bootloader
 {
+    /**
+     * @psalm-pure
+     */
+    #[\Override]
     public function defineDependencies(): array
     {
         return [
             CycleOrmBootloader::class,
         ];
     }
 
+    /**
+     * @psalm-external-mutation-free
+     */
     public function init(ContainerInterface $container): void
     {
         Facade::setContainer($container);

src/Bridge/Spiral/Bootloader/ActiveRecordBootloader.php

@@ -4,4 +4,7 @@
 
 namespace Cycle\ActiveRecord\Exception;
 
+/**
+ * @psalm-mutable
+ */
 interface ActiveRecordException extends \Throwable {}

src/Exception/ActiveRecordException.php

@@ -4,4 +4,4 @@
 
 namespace Cycle\ActiveRecord\Exception;
 
-class ConfigurationException extends \RuntimeException implements ActiveRecordException {}
+final class ConfigurationException extends \RuntimeException implements ActiveRecordException {}

src/Exception/ConfigurationException.php

@@ -4,6 +4,5 @@
 
 namespace Cycle\ActiveRecord\Exception\Transaction;
 
-use Cycle\ActiveRecord\Exception\ActiveRecordException;
-
-class TransactionException extends \RuntimeException implements ActiveRecordException {}
+/** @psalm-suppress DeprecatedClass The alias intentionally targets the deprecated class name. */
+\class_alias(\Cycle\Transaction\Exception\TransactionException::class, TransactionException::class);

src/Exception/Transaction/TransactionException.php

@@ -13,12 +13,15 @@
 /**
  * @internal
  */
-class Facade
+final class Facade
 {
     private static ?ORMInterface $orm = null;
     private static ?ContainerInterface $container = null;
     private static ?DatabaseManager $dbal = null;
 
+    /**
+     * @psalm-external-mutation-free
+     */
     public static function setContainer(ContainerInterface $container): void
     {
         self::$container = $container;
@@ -40,6 +43,9 @@ public static function getDatabaseManager(): DatabaseManager
         return self::$dbal ??= self::getFromContainer(DatabaseManager::class);
     }
 
+    /**
+     * @psalm-external-mutation-free
+     */
     public static function reset(): void
     {
         self::$orm = null;