feat(engine): give both platforms one debug switch to read

"Debug" had grown into three unconnected mechanisms: a boolean injected into
RomanjiConverter, a one-off configuration dump at startup, and KtorSimpleLogger
calls that Paper's stock log4j configuration never printed. Turning `debug: true`
on told an operator nothing about the Velocity handshake, which is what #228 is
actually about.

The vocabulary goes in engine because it is a contract before it is an
implementation: config.yml and the proxy's system property have to agree on what
`velocity,protocol` means, and a category added on one side must exist on the
other. Only the writing is left to the platforms.

The message is a lambda so that the chat path - instrumented once per message -
costs nothing while debugging is off. The `if (debugMode) logger.info("... $word")`
guards this replaces built their strings either way.

Both platform loggers write at INFO rather than at the level the content
deserves, because neither Paper's nor Velocity's stock logging configuration
prints anything below it, and asking operators to edit log4j before they can
answer a bug report is the friction this exists to remove.

Refs #228

Co-Authored-By: Claude <noreply@anthropic.com>

2 files changed, 121 insertions, 0 deletions

diff --git a/engine/src/test/kotlin/dev/m1sk9/lunaticChat/engine/debug/DebugCategoriesTest.kt b/engine/src/test/kotlin/dev/m1sk9/lunaticChat/engine/debug/DebugCategoriesTest.kt
new file mode 100644
index 0000000..44ccb86
--- /dev/null
+++ b/engine/src/test/kotlin/dev/m1sk9/lunaticChat/engine/debug/DebugCategoriesTest.kt
@@ -0,0 +1,76 @@
+package dev.m1sk9.lunaticChat.engine.debug
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+
+class DebugCategoriesTest {
+    @Test
+    fun `a true spelling switches every category on`() {
+        listOf("true", "TRUE", "yes", "on", "all", " true ").forEach { raw ->
+            val parsed = DebugCategories.parse(raw)
+
+            assertTrue(parsed.enabled, raw)
+            assertEquals(DebugCategory.entries.toSet(), parsed.active, raw)
+        }
+    }
+
+    @Test
+    fun `a false spelling switches every category off`() {
+        listOf("false", "FALSE", "no", "off", "none", "", "   ").forEach { raw ->
+            val parsed = DebugCategories.parse(raw)
+
+            assertFalse(parsed.enabled, raw)
+            assertEquals(emptySet(), parsed.active, raw)
+        }
+    }
+
+    @Test
+    fun `a comma separated list switches on exactly the categories it names`() {
+        val parsed = DebugCategories.parse("velocity,protocol")
+
+        assertTrue(parsed.enabled)
+        assertEquals(setOf(DebugCategory.VELOCITY, DebugCategory.PROTOCOL), parsed.active)
+        assertEquals(emptyList(), parsed.unknown)
+    }
+
+    @Test
+    fun `surrounding whitespace, casing and empty entries are ignored`() {
+        val parsed = DebugCategories.parse(" Velocity , , PROTOCOL ,")
+
+        assertEquals(setOf(DebugCategory.VELOCITY, DebugCategory.PROTOCOL), parsed.active)
+        assertEquals(emptyList(), parsed.unknown)
+    }
+
+    @Test
+    fun `an unknown name is reported without discarding the categories beside it`() {
+        val parsed = DebugCategories.parse("velocity,proxy")
+
+        assertEquals(setOf(DebugCategory.VELOCITY), parsed.active)
+        assertEquals(listOf("proxy"), parsed.unknown)
+    }
+
+    @Test
+    fun `a switch naming only unknown categories logs nothing`() {
+        val parsed = DebugCategories.parse("maybe")
+
+        assertEquals(emptySet(), parsed.active)
+        assertEquals(listOf("maybe"), parsed.unknown)
+    }
+
+    @Test
+    fun `resolve reads a list the way parse reads the same names spelled with commas`() {
+        assertEquals(
+            DebugCategories.parse("velocity,protocol"),
+            DebugCategories.resolve(listOf("velocity", "protocol")),
+        )
+    }
+
+    @Test
+    fun `every category is reachable by the key operators write`() {
+        DebugCategory.entries.forEach { category ->
+            assertEquals(category, DebugCategory.fromKey(category.key))
+        }
+    }
+}
diff --git a/engine/src/test/kotlin/dev/m1sk9/lunaticChat/engine/debug/DebugStateTest.kt b/engine/src/test/kotlin/dev/m1sk9/lunaticChat/engine/debug/DebugStateTest.kt
new file mode 100644
index 0000000..ae1456d
--- /dev/null
+++ b/engine/src/test/kotlin/dev/m1sk9/lunaticChat/engine/debug/DebugStateTest.kt
@@ -0,0 +1,45 @@
+package dev.m1sk9.lunaticChat.engine.debug
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+
+class DebugStateTest {
+    @Test
+    fun `a state starts on the categories it was built with`() {
+        val state = DebugState(setOf(DebugCategory.VELOCITY))
+
+        assertTrue(state.isEnabled(DebugCategory.VELOCITY))
+        assertFalse(state.isEnabled(DebugCategory.CHAT))
+    }
+
+    @Test
+    fun `replace drops the categories it does not list`() {
+        val state = DebugState(setOf(DebugCategory.VELOCITY, DebugCategory.CHAT))
+
+        state.replace(setOf(DebugCategory.PROTOCOL))
+
+        assertEquals(setOf(DebugCategory.PROTOCOL), state.enabled)
+    }
+
+    @Test
+    fun `set switches one category without touching the others`() {
+        val state = DebugState(setOf(DebugCategory.VELOCITY))
+
+        state.set(DebugCategory.CHAT, on = true)
+        state.set(DebugCategory.VELOCITY, on = false)
+
+        assertEquals(setOf(DebugCategory.CHAT), state.enabled)
+    }
+
+    @Test
+    fun `a state built from a set is unaffected by later changes to it`() {
+        val categories = mutableSetOf(DebugCategory.VELOCITY)
+        val state = DebugState(categories)
+
+        categories += DebugCategory.CHAT
+
+        assertEquals(setOf(DebugCategory.VELOCITY), state.enabled)
+    }
+}