feat: add embedded spec FS and ParseSpec/ParseOverlay functions

Add spec.Java and spec.Overlays as embed.FS for accessing YAML spec
files without filesystem paths. Add ParseSpec and ParseOverlay functions
that accept []byte, enabling consumers to load specs from embedded data
or other non-filesystem sources.

Author: xaionaro@dx.center

spec/specs.go

@@ -0,0 +1,14 @@
+// Package spec embeds the Java API spec and overlay YAML files.
+package spec
+
+import "embed"
+
+// Java contains the Java API spec YAML files.
+//
+//go:embed java/*.yaml
+var Java embed.FS
+
+// Overlays contains the overlay YAML files.
+//
+//go:embed overlays/java/*.yaml
+var Overlays embed.FS

tools/pkg/javagen/overlay.go

@@ -27,11 +27,14 @@ func LoadOverlay(path string) (*Overlay, error) {
 		}
 		return nil, fmt.Errorf("read overlay %s: %w", path, err)
 	}
+	return ParseOverlay(data)
+}
 
+// ParseOverlay parses an overlay from YAML data.
+func ParseOverlay(data []byte) (*Overlay, error) {
 	var ov Overlay
 	if err := yaml.Unmarshal(data, &ov); err != nil {
-		return nil, fmt.Errorf("parse overlay %s: %w", path, err)
+		return nil, fmt.Errorf("parse overlay: %w", err)
 	}
-
 	return &ov, nil
 }

tools/pkg/javagen/spec.go

@@ -16,14 +16,18 @@ func LoadSpec(path string) (*Spec, error) {
 	if err != nil {
 		return nil, fmt.Errorf("read %s: %w", path, err)
 	}
+	return ParseSpec(data)
+}
 
+// ParseSpec validates and parses a Java API spec from YAML data.
+func ParseSpec(data []byte) (*Spec, error) {
 	var spec Spec
 	if err := yaml.Unmarshal(data, &spec); err != nil {
-		return nil, fmt.Errorf("parse %s: %w", path, err)
+		return nil, fmt.Errorf("parse spec: %w", err)
 	}
 
 	if err := validateSpec(&spec); err != nil {
-		return nil, fmt.Errorf("validate %s: %w", path, err)
+		return nil, fmt.Errorf("validate spec: %w", err)
 	}
 
 	return &spec, nil