fix: resolve RedisCache array offset error and improve discovery diagnostics

- Fix RedisCache driver to handle MGET failures gracefully with fallback
- Add comprehensive discovery context comparison debug tools
- Identify root cause: WEB context discovery missing 166 items vs CLI
- WEB context missing RequestFactory class entirely (52 vs 69 commands)
- Improved exception handling with detailed binding diagnostics

src/Framework/Design/Analyzer/ColorAnalysisResult.php

@@ -102,6 +102,7 @@ final readonly class ColorAnalysisResult
 
     /**
      * Gibt die häufigsten Farbformate zurück
+     * @return array<string, int>
      */
     public function getMostUsedFormats(): array
     {
@@ -118,6 +119,7 @@ final readonly class ColorAnalysisResult
 
     /**
      * Gibt Farbpaletten-Zusammenfassung zurück
+     * @return array<string, mixed>
      */
     public function getPaletteSummary(): array
     {
@@ -134,6 +136,7 @@ final readonly class ColorAnalysisResult
 
     /**
      * Gibt die problematischsten Farbkombinationen zurück
+     * @return array<int, array<string, mixed>>
      */
     public function getWorstContrastPairs(): array
     {
@@ -150,6 +153,7 @@ final readonly class ColorAnalysisResult
 
     /**
      * Gibt priorisierte Verbesserungs-Aktionen zurück
+     * @return array<int, array<string, string>>
      */
     public function getPrioritizedActions(): array
     {
@@ -192,6 +196,7 @@ final readonly class ColorAnalysisResult
 
     /**
      * Gibt Format-Empfehlungen zurück
+     * @return array<int, array<string, string>>
      */
     public function getFormatRecommendations(): array
     {
@@ -230,6 +235,7 @@ final readonly class ColorAnalysisResult
 
     /**
      * Konvertiert zu Array für Export
+     * @return array<string, mixed>
      */
     public function toArray(): array
     {

src/Framework/Design/Analyzer/ColorAnalyzer.php

@@ -394,6 +394,7 @@ final readonly class ColorAnalyzer
 
     /**
      * Konvertiert RGB zu HSL
+     * @return array{h: float, s: float, l: float}
      */
     private function rgbToHsl(RGBColor $rgb): array
     {

src/Framework/Design/Analyzer/ConventionCheckResult.php

@@ -20,6 +20,7 @@ final readonly class ConventionCheckResult
 
     /**
      * Gruppiert Violations nach Schweregrad
+     * @return array<string, array<int, array<string, mixed>>>
      */
     public function getViolationsBySeverity(): array
     {
@@ -39,6 +40,7 @@ final readonly class ConventionCheckResult
 
     /**
      * Gibt die schlimmsten Problembereiche zurück
+     * @return array<string, int|float>
      */
     public function getWorstAreas(): array
     {
@@ -50,6 +52,7 @@ final readonly class ConventionCheckResult
 
     /**
      * Gibt die besten Bereiche zurück
+     * @return array<string, int|float>
      */
     public function getBestAreas(): array
     {
@@ -61,6 +64,7 @@ final readonly class ConventionCheckResult
 
     /**
      * Gibt priorisierte Action Items zurück
+     * @return array<int, array<string, string>>
      */
     public function getPrioritizedActions(): array
     {
@@ -95,6 +99,7 @@ final readonly class ConventionCheckResult
 
     /**
      * Berechnet Verbesserungs-Potenzial
+     * @return array<string, array<string, int|float>>
      */
     public function getImprovementPotential(): array
     {
@@ -120,6 +125,7 @@ final readonly class ConventionCheckResult
 
     /**
      * Konvertiert zu Array für Export
+     * @return array<string, mixed>
      */
     public function toArray(): array
     {

src/Framework/Design/Analyzer/TokenAnalysisResult.php

@@ -23,6 +23,7 @@ final readonly class TokenAnalysisResult
 
     /**
      * Gibt die häufigsten Token-Typen zurück
+     * @return array<string, int>
      */
     public function getMostUsedTokenTypes(): array
     {
@@ -39,6 +40,7 @@ final readonly class TokenAnalysisResult
 
     /**
      * Gibt Token-Coverage-Statistiken zurück
+     * @return array<string, int|float>
      */
     public function getTokenCoverage(): array
     {
@@ -55,6 +57,7 @@ final readonly class TokenAnalysisResult
 
     /**
      * Gibt Empfehlungs-Prioritäten zurück
+     * @return array<int, array<string, string>>
      */
     public function getRecommendationPriorities(): array
     {
@@ -75,6 +78,7 @@ final readonly class TokenAnalysisResult
 
     /**
      * Konvertiert zu Array für Export
+     * @return array<string, mixed>
      */
     public function toArray(): array
     {

src/Framework/Design/ComponentScanner.php

@@ -16,6 +16,9 @@ use App\Framework\Filesystem\FilePath;
  */
 final readonly class ComponentScanner
 {
+    /**
+     * @param array<string|FilePath> $cssFiles
+     */
     public function scanComponents(array $cssFiles): ComponentRegistry
     {
         $components = [];
@@ -41,13 +44,17 @@ final readonly class ComponentScanner
         return new ComponentRegistry($components);
     }
 
+    /**
+     * @return array<Component>
+     */
     private function extractComponentsFromCss(string $cssContent, string $filePath): array
     {
         $components = [];
         $processedComponents = [];
 
         // Remove comments
-        $cssContent = preg_replace('/\/\*.*?\*\//s', '', $cssContent);
+        $cleanedContent = preg_replace('/\/\*.*?\*\//s', '', $cssContent);
+        $cssContent = $cleanedContent !== null ? $cleanedContent : $cssContent;
 
         // Find all CSS selectors with improved regex that handles nested braces
         preg_match_all('/([^{}]+)\s*{([^{}]*(?:{[^{}]*}[^{}]*)*)}/s', $cssContent, $matches, PREG_SET_ORDER);
@@ -91,8 +98,16 @@ final readonly class ComponentScanner
     private function analyzeSelector(string $selector, string $cssRules, string $filePath): ?Component
     {
         // Clean up selector - remove :where, :is wrappers
-        $selector = preg_replace('/:where\s*\((.*?)\)/', '$1', $selector);
-        $selector = preg_replace('/:is\s*\((.*?)\)/', '$1', $selector);
+        $cleanedSelector = preg_replace('/:where\s*\((.*?)\)/', '$1', $selector);
+        $selector = $cleanedSelector !== null ? $cleanedSelector : $selector;
+
+        $cleanedSelector = preg_replace('/:is\s*\((.*?)\)/', '$1', $selector);
+        $selector = $cleanedSelector !== null ? $cleanedSelector : $selector;
+
+        // Ensure selector is non-empty string
+        if (empty($selector)) {
+            return null;
+        }
 
         // Skip pseudo-elements and certain pseudo-classes
         if (preg_match('/::/', $selector) || preg_match('/:not\(/', $selector)) {

src/Framework/Design/Parser/ClassNameParser.php

@@ -14,6 +14,7 @@ final readonly class ClassNameParser
 {
     /**
      * Extrahiert CSS-Klassennamen aus Content
+     * @return array<int, CssClass>
      */
     public function extractFromContent(string $content): array
     {
@@ -35,6 +36,8 @@ final readonly class ClassNameParser
 
     /**
      * Erkennt Component-Patterns in den CSS-Klassen
+     * @param array<int, CssClass> $classNames
+     * @return array<int, ComponentPattern>
      */
     public function detectPatterns(array $classNames): array
     {

src/Framework/Design/Parser/CssParser.php

@@ -30,6 +30,9 @@ final readonly class CssParser
         }
 
         $content = file_get_contents($filePath->toString());
+        if ($content === false) {
+            throw new \RuntimeException("Failed to read CSS file: {$filePath->toString()}");
+        }
 
         return $this->parseContent($content, $filePath);
     }
@@ -69,6 +72,8 @@ final readonly class CssParser
 
     /**
      * Parst mehrere CSS-Dateien
+     * @param array<int, FilePath|string> $filePaths
+     * @return array<int, CssParseResult>
      */
     public function parseFiles(array $filePaths): array
     {
@@ -84,6 +89,7 @@ final readonly class CssParser
 
     /**
      * Parst alle CSS-Dateien in einem Verzeichnis
+     * @return array<int, CssParseResult>
      */
     public function parseDirectory(string $directory, bool $recursive = true): array
     {
@@ -99,6 +105,7 @@ final readonly class CssParser
 
     /**
      * Extrahiert CSS-Regeln aus dem Content
+     * @return array<int, CssRule>
      */
     private function extractRules(string $content): array
     {
@@ -130,6 +137,7 @@ final readonly class CssParser
 
     /**
      * Parst Selektoren (durch Komma getrennt)
+     * @return array<int, CssSelector>
      */
     private function parseSelectors(string $selectorText): array
     {
@@ -148,6 +156,7 @@ final readonly class CssParser
 
     /**
      * Parst CSS Properties
+     * @return array<int, CssProperty>
      */
     private function parseProperties(string $propertiesText): array
     {

src/Framework/Design/Service/TokenAnalyzer.php

@@ -15,6 +15,10 @@ use App\Framework\Design\ValueObjects\TokenCategory;
  */
 final readonly class TokenAnalyzer
 {
+    /**
+     * @param array<int, CustomProperty> $customProperties
+     * @return array<int, DesignToken>
+     */
     public function categorizeTokens(array $customProperties): array
     {
         $tokens = [];
@@ -33,6 +37,10 @@ final readonly class TokenAnalyzer
         return $tokens;
     }
 
+    /**
+     * @param array<int, CustomProperty> $customProperties
+     * @return array<string, int>
+     */
     public function analyzeNamingPatterns(array $customProperties): array
     {
         $patterns = [

src/Framework/Design/ValueObjects/ComponentPattern.php

@@ -74,6 +74,7 @@ final readonly class ComponentPattern
 
     /**
      * Gibt alle Klassennamen als Strings zurück
+     * @return array<int, string>
      */
     public function getClassNames(): array
     {
@@ -113,6 +114,7 @@ final readonly class ComponentPattern
 
     /**
      * Gibt Pattern-spezifische Informationen zurück
+     * @return array<string, mixed>
      */
     public function getPatternInfo(): array
     {
@@ -139,6 +141,7 @@ final readonly class ComponentPattern
 
     /**
      * Analysiert BEM-Struktur
+     * @return array<string, mixed>
      */
     private function getBemStructure(): array
     {
@@ -154,6 +157,10 @@ final readonly class ComponentPattern
         ];
     }
 
+    /**
+     * @param array<int, mixed> $elements
+     * @param array<int, mixed> $modifiers
+     */
     private function getBemCompleteness(array $elements, array $modifiers): string
     {
         if (empty($elements) && empty($modifiers)) {
@@ -171,6 +178,9 @@ final readonly class ComponentPattern
         return 'full_bem';
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function toArray(): array
     {
         return [

src/Framework/Design/ValueObjects/CssRule.php

@@ -21,6 +21,7 @@ final readonly class CssRule
 
     /**
      * Gibt alle Selektor-Strings zurück
+     * @return array<int, string>
      */
     public function getSelectorStrings(): array
     {
@@ -29,6 +30,7 @@ final readonly class CssRule
 
     /**
      * Gibt alle Property-Namen zurück
+     * @return array<int, string>
      */
     public function getPropertyNames(): array
     {
@@ -51,6 +53,7 @@ final readonly class CssRule
 
     /**
      * Gibt alle Properties einer bestimmten Kategorie zurück
+     * @return array<int, CssProperty>
      */
     public function getPropertiesByCategory(CssPropertyCategory $category): array
     {

src/Framework/Design/ValueObjects/CssSelector.php

@@ -78,6 +78,7 @@ final readonly class CssSelector
 
     /**
      * Extrahiert alle CSS-Klassennamen aus dem Selektor
+     * @return array<int, string>
      */
     public function extractClasses(): array
     {
@@ -88,6 +89,7 @@ final readonly class CssSelector
 
     /**
      * Extrahiert alle IDs aus dem Selektor
+     * @return array<int, string>
      */
     public function extractIds(): array
     {
@@ -98,6 +100,7 @@ final readonly class CssSelector
 
     /**
      * Extrahiert alle Element-Namen aus dem Selektor
+     * @return array<int, string>
      */
     public function extractElements(): array
     {

src/Framework/Design/ValueObjects/DesignToken.php

@@ -62,6 +62,7 @@ final readonly class DesignToken
 
     /**
      * Konvertiert zu Array für Export/Serialisierung
+     * @return array<string, mixed>
      */
     public function toArray(): array
     {