refactor: finalize deserializer interfaces and cleanup docs

Author: RAV64

README.md

@@ -93,27 +93,27 @@ public class AppConfig {
 ```java
 import org.msuo.config2java.*;
 
-AppConfig luaCfg = LuaDeserializer.deserialize(
+AppConfig luaCfg = new LuaDeserializer().deserialize(
     "return { name = 'svc', port = 9090, mode = 'PROD' }",
     AppConfig.class
 );
 
-AppConfig groovyCfg = GroovyDeserializer.deserialize(
+AppConfig groovyCfg = new GroovyDeserializer().deserialize(
     "return [name: 'svc', port: 9090, mode: 'PROD']",
     AppConfig.class
 );
 
-AppConfig tomlCfg = TomlDeserializer.deserialize(
+AppConfig tomlCfg = new TomlDeserializer().deserialize(
     "name = 'svc'\nport = 9090\nmode = 'PROD'",
     AppConfig.class
 );
 
-AppConfig jsonCfg = JsonDeserializer.deserialize(
+AppConfig jsonCfg = new JsonDeserializer().deserialize(
     "{\"name\":\"svc\",\"port\":9090,\"mode\":\"PROD\"}",
     AppConfig.class
 );
 
-AppConfig xmlCfg = XmlDeserializer.deserialize(
+AppConfig xmlCfg = new XmlDeserializer().deserialize(
     "<config><name>svc</name><port>9090</port><mode>PROD</mode></config>",
     AppConfig.class
 );
@@ -126,7 +126,7 @@ The exception message also includes a tree view of failing paths.
 
 ```java
 try {
-    JsonDeserializer.deserialize("{\"port\":0}", AppConfig.class);
+    new JsonDeserializer().deserialize("{\"port\":0}", AppConfig.class);
 } catch (ConfigDeserializationException ex) {
     ex.forEachError((segments, error) ->
         System.out.println(segments + " -> " + error.getErrorType().getClass().getSimpleName())
@@ -142,7 +142,7 @@ Parse/eval failures are separate and throw `ConfigSourceException`.
 
 ```java
 try {
-    TomlDeserializer.deserialize("name = ", AppConfig.class);
+    new TomlDeserializer().deserialize("name = ", AppConfig.class);
 } catch (ConfigSourceException ex) {
     System.out.println(ex.phase());   // parse or evaluate
     System.out.println(ex.format());  // TOML / JSON / XML / Lua / Groovy

errors.md

@@ -20,7 +20,7 @@ Example:
 
 ```java
 try {
-    JsonDeserializer.deserialize(source, MyCfg.class);
+    new JsonDeserializer().deserialize(source, MyCfg.class);
 } catch (ConfigDeserializationException ex) {
     ex.forEachError((segments, error) -> {
         System.out.println(segments);
@@ -131,7 +131,7 @@ Handling errors via API:
 
 ```java
 try {
-    JsonDeserializer.deserialize(source, ShowcaseCfg.class);
+    new JsonDeserializer().deserialize(source, ShowcaseCfg.class);
 } catch (ConfigDeserializationException ex) {
     // Stable assertions should use API values, not message-string matching.
     ex.forEachError((segments, error) ->

modules/deserializer/README.md

@@ -29,6 +29,18 @@ implementation "org.msuo:deserializer:<version>"
 
 ## For language implementers
 
+`Deserializer` defines the required API:
+
+- implement `deserialize(String source, Class<T> configClass)`
+- reuse default file overloads from the interface (`Path` / `File`)
+
+Script formats can implement `ScriptDeserializer`, which adds:
+
+- `deserialize(String, Class<T>, Map<String, String> env, Map<String, ?> globals)`
+- default no-injection `deserialize(String, Class<T>)`
+
+`AbstractScriptDeserializer` provides shared env/global normalization and delegates format-specific parsing through `parse(...)`.
+
 A language module typically:
 
 1. Parses source text into native objects.
@@ -37,9 +49,6 @@ A language module typically:
 
 The core mapper then handles the rest.
 
-`Deserializer` defines the required `deserialize(CharSequence, Class<T>)` contract and provides default file/path overloads.
-`ScriptInputNormalizer` provides shared helpers for script-backed modules (Lua, Groovy) to normalize injected environment/global maps.
-
 ## Error model
 
 `ConfigDeserializationException` exposes:

modules/deserializer/src/main/java/org/msuo/config2java/AbstractScriptDeserializer.java

@@ -0,0 +1,45 @@
+package org.msuo.config2java;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+public abstract class AbstractScriptDeserializer implements ScriptDeserializer {
+
+    @Override
+    public final <T> T deserialize(
+        String source,
+        Class<T> configClass,
+        Map<String, String> environment,
+        Map<String, ?> globals
+    ) {
+        return ObjectMapper.deserialize(
+            parse(
+                source,
+                normalizeEnvironment(environment),
+                normalizeGlobals(globals)
+            ),
+            configClass
+        );
+    }
+
+    protected abstract ConfigValue parse(
+        String source,
+        Map<String, String> environment,
+        Map<String, Object> globals
+    );
+
+    private static Map<String, String> normalizeEnvironment(
+        Map<String, String> environment
+    ) {
+        return environment == null
+            ? Collections.emptyMap()
+            : Collections.unmodifiableMap(new LinkedHashMap<>(environment));
+    }
+
+    private static Map<String, Object> normalizeGlobals(Map<String, ?> globals) {
+        return globals == null
+            ? Collections.emptyMap()
+            : Collections.unmodifiableMap(new LinkedHashMap<>(globals));
+    }
+}

modules/deserializer/src/main/java/org/msuo/config2java/ConfigDeserializationException.java

@@ -33,11 +33,7 @@ public PathNode getErrorPathTree() {
 
     @Override
     public String getMessage() {
-        return buildMessage(PathTreeFormatter.format(getErrorPathTree()));
-    }
-
-    private static String buildMessage(String pathTree) {
-        return "Config deserialization failed:\n" + pathTree;
+        return "Config deserialization failed:\n" + PathTreeFormatter.format(getErrorPathTree());
     }
 
     public static final class PathNode {

modules/deserializer/src/main/java/org/msuo/config2java/Deserializer.java

@@ -9,11 +9,11 @@
 
 public interface Deserializer {
 
-    <T> T deserialize(CharSequence source, Class<T> configClass);
+    <T> T deserialize(String source, Class<T> configClass);
 
     default <T> T deserialize(Path file, Charset charset, Class<T> configClass)
         throws IOException {
-        return deserialize((CharSequence) Files.readString(file, charset), configClass);
+        return deserialize(Files.readString(file, charset), configClass);
     }
 
     default <T> T deserialize(Path file, Class<T> configClass)

modules/deserializer/src/main/java/org/msuo/config2java/ErrorCollector.java

@@ -43,8 +43,16 @@ private static List<String> toPathSegments(Path path) {
         Path.Segment[] segments = path.segments();
         List<String> out = new ArrayList<>(Math.max(0, segments.length - 1));
         for (int i = 1; i < segments.length; i++) {
-            out.add(PathTextFormatter.label(segments[i]));
+            out.add(toPathLabel(segments[i]));
         }
         return out;
     }
+
+    private static String toPathLabel(Path.Segment segment) {
+        if (segment.kind == Path.SegmentKind.ROOT) return "$";
+        if (segment.kind == Path.SegmentKind.FIELD) return String.valueOf(segment.value);
+        if (segment.kind == Path.SegmentKind.INDEX) return "[" + String.valueOf(segment.value) + "]";
+        if (segment.kind == Path.SegmentKind.MAP_KEY) return "[" + String.valueOf(segment.value) + "]";
+        return "{" + String.valueOf(segment.value) + "}";
+    }
 }

modules/deserializer/src/main/java/org/msuo/config2java/PathTextFormatter.java

@@ -0,0 +1,24 @@
+package org.msuo.config2java;
+
+import java.util.Collections;
+import java.util.Map;
+
+public interface ScriptDeserializer extends Deserializer {
+
+    <T> T deserialize(
+        String source,
+        Class<T> configClass,
+        Map<String, String> environment,
+        Map<String, ?> globals
+    );
+
+    @Override
+    default <T> T deserialize(String source, Class<T> configClass) {
+        return deserialize(
+            source,
+            configClass,
+            Collections.emptyMap(),
+            Collections.emptyMap()
+        );
+    }
+}