release: merge develop into main

Changes from develop:
- test(scanner): completar cobertura de ComposerNamespaceResolver (33% → 66% methods, 70% → 93% lines)
- test(filter): completar cobertura de AttributeFilter para 100%
- test(cache): completar cobertura de FileCacheStrategy (71% → 85% methods, 93% → 96% lines)
- fix: suprimir PHP Warnings com @ operator em file_get_contents e mkdir
- docs: atualizar README com casos de uso reais e exemplos completos
- docs: padronizar README com layout premium do kariricode-devkit

Quality: cs-fixer ✓ | phpstan L9 ✓ | psalm ✓ | phpunit 222 tests ✓
Coverage: 95.44% lines

Author: walmir-silva

README.md

@@ -12,11 +12,16 @@
  *
  * Typical configuration: Memory (L1) → File (L2).
  * On L1 miss + L2 hit, result is promoted to L1.
+ *
+ * @package KaririCode\ClassDiscovery\Cache
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ * @license MIT
+ * @since   3.0.0
  */
-final class ChainCacheStrategy implements CacheStrategy
+final readonly class ChainCacheStrategy implements CacheStrategy
 {
     /** @var array<CacheStrategy> */
-    private readonly array $tiers;
+    private array $tiers;
 
     public function __construct(CacheStrategy ...$tiers)
     {

src/Cache/ChainCacheStrategy.php

@@ -13,13 +13,18 @@
  *
  * OPcache-friendly when using var_export format. Production-grade
  * with atomic writes (write to temp, rename) to prevent corruption.
+ *
+ * @package KaririCode\ClassDiscovery\Cache
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ * @license MIT
+ * @since   3.0.0
  */
-final class FileCacheStrategy implements CacheStrategy
+final readonly class FileCacheStrategy implements CacheStrategy
 {
     public function __construct(
         private readonly string $cacheDirectory,
     ) {
-        if (! is_dir($this->cacheDirectory) && ! mkdir($this->cacheDirectory, 0o755, true)) {
+        if (! is_dir($this->cacheDirectory) && ! @mkdir($this->cacheDirectory, 0o755, true)) {
             throw DiscoveryException::cacheCorruption('init', "Cannot create cache directory: {$this->cacheDirectory}");
         }
     }

src/Cache/FileCacheStrategy.php

@@ -12,6 +12,11 @@
  *
  * No persistence — cache lives only during the request lifecycle.
  * Zero I/O overhead. Ideal for dev mode with hot-reload.
+ *
+ * @package KaririCode\ClassDiscovery\Cache
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ * @license MIT
+ * @since   3.0.0
  */
 final class MemoryCacheStrategy implements CacheStrategy
 {

src/Cache/MemoryCacheStrategy.php

@@ -11,6 +11,11 @@
  *
  * Backed enum: int values map to PHP's native Attribute::TARGET_* bitmask.
  * ARFA 1.3 E-003: backed enums permitted when external representation required.
+ *
+ * @package KaririCode\ClassDiscovery\Enum
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ * @license MIT
+ * @since   3.0.0
  */
 enum AttributeTarget: int
 {

src/Enum/AttributeTarget.php

@@ -8,6 +8,11 @@
  * Scanner strategy classification.
  *
  * Pure enum: no external representation required.
+ *
+ * @package KaririCode\ClassDiscovery\Enum
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ * @license MIT
+ * @since   3.0.0
  */
 enum ScannerType
 {

src/Enum/ScannerType.php

@@ -12,13 +12,18 @@
  *
  * Use static factories: CompositeFilter::any(...) for OR-logic,
  * CompositeFilter::all(...) for AND-logic.
+ *
+ * @package KaririCode\ClassDiscovery\Filter
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ * @license MIT
+ * @since   3.0.0
  */
-final class CompositeFilter implements ClassFilter
+final readonly class CompositeFilter implements ClassFilter
 {
     /** @var list<ClassFilter> */
-    private readonly array $filters;
+    private array $filters;
 
-    private readonly bool $requireAll;
+    private bool $requireAll;
 
     /**
      * @param list<ClassFilter> $filters

src/Filter/CompositeFilter.php

@@ -7,6 +7,14 @@
 use KaririCode\ClassDiscovery\Contract\ClassFilter;
 use KaririCode\ClassDiscovery\Result\ClassMetadata;
 
+/**
+ * Filters classes by implemented interface.
+ *
+ * @package KaririCode\ClassDiscovery\Filter
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ * @license MIT
+ * @since   3.0.0
+ */
 final readonly class InterfaceFilter implements ClassFilter
 {
     public function __construct(

src/Filter/InterfaceFilter.php

@@ -7,6 +7,14 @@
 use KaririCode\ClassDiscovery\Contract\ClassFilter;
 use KaririCode\ClassDiscovery\Result\ClassMetadata;
 
+/**
+ * Filters classes by namespace prefix.
+ *
+ * @package KaririCode\ClassDiscovery\Filter
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ * @license MIT
+ * @since   3.0.0
+ */
 final readonly class NamespaceFilter implements ClassFilter
 {
     public function __construct(

src/Filter/NamespaceFilter.php

@@ -15,8 +15,13 @@
  * PSR-16 compliant cache with the discovery system.
  *
  * Optional dependency: kariricode/cache
+ *
+ * @package KaririCode\ClassDiscovery\Integration
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ * @license MIT
+ * @since   3.1.0
  */
-final class CacheBridge implements CacheStrategy
+final readonly class CacheBridge implements CacheStrategy
 {
     /**
      * @param object $simpleCache PSR-16 CacheInterface instance