refactor: documents

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

core/lib/Logger/LogLevelSeverity.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace KTXC\Logger;
+
+use Psr\Log\LogLevel;
+
+/**
+ * Maps PSR-3 log level strings to integer severity values.
+ *
+ * Lower integer = higher severity (matches RFC 5424 / syslog convention):
+ *   emergency = 0, alert = 1, critical = 2, error = 3,
+ *   warning = 4, notice = 5, info = 6, debug = 7
+ */
+class LogLevelSeverity
+{
+    private const MAP = [
+        LogLevel::EMERGENCY => 0,
+        LogLevel::ALERT     => 1,
+        LogLevel::CRITICAL  => 2,
+        LogLevel::ERROR     => 3,
+        LogLevel::WARNING   => 4,
+        LogLevel::NOTICE    => 5,
+        LogLevel::INFO      => 6,
+        LogLevel::DEBUG     => 7,
+    ];
+
+    /**
+     * Returns the integer severity for a PSR-3 level string.
+     *
+     * @throws \InvalidArgumentException for unknown level strings
+     */
+    public static function severity(string $level): int
+    {
+        $normalized = strtolower($level);
+
+        if (!array_key_exists($normalized, self::MAP)) {
+            throw new \InvalidArgumentException(
+                sprintf(
+                    'Unknown log level "%s". Valid levels are: %s.',
+                    $level,
+                    implode(', ', array_keys(self::MAP))
+                )
+            );
+        }
+
+        return self::MAP[$normalized];
+    }
+
+    /**
+     * Validates that a level string is a known PSR-3 level.
+     *
+     * @throws \InvalidArgumentException for unknown level strings
+     */
+    public static function validate(string $level): void
+    {
+        self::severity($level); // throws on unknown
+    }
+
+    /**
+     * Returns all valid PSR-3 level strings ordered from most to least severe.
+     *
+     * @return string[]
+     */
+    public static function levels(): array
+    {
+        return array_keys(self::MAP);
+    }
+}