Escape schema resources and reuse compiled plans

internal/validate/standard_validator.go

@@ -12,6 +12,7 @@ import (
 	"os"
 	"path"
 	"path/filepath"
+	"runtime"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/promptkit/internal/domain"
@@ -94,10 +95,11 @@ func (v *StandardValidator) PrepareValidation(ctx context.Context, contract doma
 		return nil, err
 	}
 	compiler := newSchemaCompiler(standardSchemaLoader{root: schemaRoot})
-	if err := compiler.AddResource(resolvedSchemaPath, schemaDocument); err != nil {
+	resourceURL := fileSchemaResourceURL(resolvedSchemaPath)
+	if err := compiler.AddResource(resourceURL.String(), schemaDocument); err != nil {
 		return nil, fmt.Errorf("failed to register JSON schema %q: %w", resolvedSchemaPath, err)
 	}
-	schema, err := compiler.Compile(resolvedSchemaPath)
+	schema, err := compiler.Compile(resourceURL.String())
 	if err != nil {
 		return nil, fmt.Errorf("failed to compile JSON schema %q: %w", resolvedSchemaPath, err)
 	}
@@ -126,10 +128,10 @@ func (v *FSValidator) PrepareValidation(ctx context.Context, contract domain.Out
 	}
 	resourceURL := fsSchemaResourceURL(schemaName)
 	compiler := newSchemaCompiler(fsSchemaLoader{fsys: v.fsys, root: filecatalog.CleanFSRoot(v.root)})
-	if err := compiler.AddResource(resourceURL, schemaDocument); err != nil {
+	if err := compiler.AddResource(resourceURL.String(), schemaDocument); err != nil {
 		return nil, fmt.Errorf("failed to register JSON schema %q: %w", schemaName, err)
 	}
-	schema, err := compiler.Compile(resourceURL)
+	schema, err := compiler.Compile(resourceURL.String())
 	if err != nil {
 		return nil, fmt.Errorf("failed to compile JSON schema %q: %w", schemaName, err)
 	}
@@ -225,7 +227,8 @@ func (v *StandardValidator) validateJSONSchema(instance any, schemaPath string)
 		return nil, err
 	}
 	compiler := newSchemaCompiler(standardSchemaLoader{root: schemaRoot})
-	schema, err := compiler.Compile(resolvedSchemaPath)
+	resourceURL := fileSchemaResourceURL(resolvedSchemaPath)
+	schema, err := compiler.Compile(resourceURL.String())
 	if err != nil {
 		return nil, fmt.Errorf("failed to compile JSON schema %q: %w", resolvedSchemaPath, err)
 	}
@@ -247,10 +250,10 @@ func (v *FSValidator) validateJSONSchema(instance any, schemaPath string) ([]str
 		return nil, fmt.Errorf("failed to compile JSON schema %q: %w", schemaName, err)
 	}
 	compiler := newSchemaCompiler(fsSchemaLoader{fsys: v.fsys, root: filecatalog.CleanFSRoot(v.root)})
-	if err := compiler.AddResource(resourceURL, schemaDoc); err != nil {
+	if err := compiler.AddResource(resourceURL.String(), schemaDoc); err != nil {
 		return nil, fmt.Errorf("failed to register JSON schema %q: %w", schemaName, err)
 	}
-	schema, err := compiler.Compile(resourceURL)
+	schema, err := compiler.Compile(resourceURL.String())
 	if err != nil {
 		return nil, fmt.Errorf("failed to compile JSON schema %q: %w", schemaName, err)
 	}
@@ -279,47 +282,6 @@ func decodeJSONValue(body []byte) (any, error) {
 	return nil, errors.New("multiple JSON values")
 }
 
-func (v *StandardValidator) LoadSchemaDocument(ctx context.Context, schemaPath string) (any, error) {
-	select {
-	case <-ctx.Done():
-		return nil, ctx.Err()
-	default:
-	}
-
-	resolved, err := v.resolveSchemaPath(schemaPath)
-	if err != nil {
-		return nil, err
-	}
-
-	raw, err := os.ReadFile(resolved)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read schema file %q: %w", resolved, err)
-	}
-
-	doc, err := decodeJSONValue(raw)
-	if err != nil {
-		return nil, fmt.Errorf("failed to decode JSON schema %q: %w", resolved, err)
-	}
-	if err := validateSchemaDialect(doc); err != nil {
-		return nil, fmt.Errorf("failed to decode JSON schema %q: %w", resolved, err)
-	}
-	return doc, nil
-}
-
-func (v *FSValidator) LoadSchemaDocument(ctx context.Context, schemaPath string) (any, error) {
-	select {
-	case <-ctx.Done():
-		return nil, ctx.Err()
-	default:
-	}
-
-	_, doc, err := v.loadSchemaDocument(schemaPath)
-	if err != nil {
-		return nil, err
-	}
-	return doc, nil
-}
-
 func (v *StandardValidator) resolveSchemaPath(schemaPath string) (string, error) {
 	if strings.TrimSpace(schemaPath) == "" {
 		return "", errors.New("schema path is required for json_schema validation")
@@ -427,8 +389,19 @@ func cleanSchemaFSPath(schemaPath string) (string, error) {
 	return cleaned, nil
 }
 
-func fsSchemaResourceURL(schemaName string) string {
-	return "promptkit-schema:///" + strings.TrimPrefix(path.Clean(schemaName), "/")
+func fileSchemaResourceURL(schemaName string) *url.URL {
+	filePath := filepath.ToSlash(schemaName)
+	if runtime.GOOS == "windows" && !strings.HasPrefix(filePath, "/") {
+		filePath = "/" + filePath
+	}
+	return &url.URL{Scheme: "file", Path: filePath}
+}
+
+func fsSchemaResourceURL(schemaName string) *url.URL {
+	return &url.URL{
+		Scheme: "promptkit-schema",
+		Path:   "/" + strings.TrimPrefix(path.Clean(schemaName), "/"),
+	}
 }
 
 func newSchemaCompiler(loader jsonschema.URLLoader) *jsonschema.Compiler {
@@ -462,6 +435,10 @@ type standardSchemaLoader struct {
 }
 
 func (l standardSchemaLoader) Load(resourceURL string) (any, error) {
+	parsed, err := url.Parse(resourceURL)
+	if err != nil || parsed.Scheme != "file" || parsed.Host != "" || parsed.RawQuery != "" || parsed.Opaque != "" {
+		return nil, fmt.Errorf("schema reference %q is not a contained file reference", resourceURL)
+	}
 	fileName, err := (jsonschema.FileLoader{}).ToFile(resourceURL)
 	if err != nil {
 		return nil, fmt.Errorf("schema reference %q is not a contained file reference: %w", resourceURL, err)
@@ -521,13 +498,10 @@ func (l fsSchemaLoader) Load(resourceURL string) (any, error) {
 	if err != nil {
 		return nil, fmt.Errorf("invalid schema reference %q: %w", resourceURL, err)
 	}
-	if parsed.Scheme != "promptkit-schema" || parsed.Host != "" {
+	if parsed.Scheme != "promptkit-schema" || parsed.Host != "" || parsed.RawQuery != "" || parsed.Opaque != "" {
 		return nil, fmt.Errorf("schema reference %q is not allowed", resourceURL)
 	}
-	name, err := url.PathUnescape(strings.TrimPrefix(parsed.Path, "/"))
-	if err != nil {
-		return nil, fmt.Errorf("invalid schema reference %q: %w", resourceURL, err)
-	}
+	name := strings.TrimPrefix(parsed.Path, "/")
 	name = path.Clean(name)
 	if l.root == "." {
 		if strings.HasPrefix(name, "../") || name == ".." {

internal/validate/standard_validator_test.go

@@ -3,9 +3,11 @@ package validate
 import (
 	"context"
 	"encoding/json"
+	"net/url"
 	"os"
 	"path/filepath"
 	"reflect"
+	"runtime"
 	"strconv"
 	"strings"
 	"testing"
@@ -330,55 +332,6 @@ func TestStandardValidatorJSONSchemaCompilationError(t *testing.T) {
 	}
 }
 
-func TestStandardValidatorLoadSchemaDocumentSuccess(t *testing.T) {
-	tmp := t.TempDir()
-	if err := os.WriteFile(filepath.Join(tmp, "schema.json"), []byte(`{
-  "type": "object",
-  "properties": {
-    "name": {"type": "string"}
-  }
-}`), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	v := NewStandardValidator(tmp)
-	loader, ok := v.(SchemaDocumentLoader)
-	if !ok {
-		t.Fatal("standard validator must implement SchemaDocumentLoader")
-	}
-
-	doc, err := loader.LoadSchemaDocument(context.Background(), "schema.json")
-	if err != nil {
-		t.Fatalf("expected no error, got %v", err)
-	}
-
-	obj, ok := doc.(map[string]any)
-	if !ok {
-		t.Fatalf("expected object document, got %#v", doc)
-	}
-	if obj["type"] != "object" {
-		t.Fatalf("expected schema type=object, got %#v", obj["type"])
-	}
-}
-
-func TestStandardValidatorLoadSchemaDocumentInvalidJSON(t *testing.T) {
-	tmp := t.TempDir()
-	if err := os.WriteFile(filepath.Join(tmp, "schema.json"), []byte(`{`), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	v := NewStandardValidator(tmp)
-	loader, ok := v.(SchemaDocumentLoader)
-	if !ok {
-		t.Fatal("standard validator must implement SchemaDocumentLoader")
-	}
-
-	_, err := loader.LoadSchemaDocument(context.Background(), "schema.json")
-	if err == nil {
-		t.Fatal("expected decode error")
-	}
-}
-
 func TestFSValidatorJSONSchemaSuccess(t *testing.T) {
 	v := NewFSValidator(fstest.MapFS{
 		"schemas/events.schema.json": &fstest.MapFile{Data: []byte(`{
@@ -461,17 +414,70 @@ func TestFSValidatorPreparedSchemaSurvivesSourceMutation(t *testing.T) {
 	}
 }
 
-func TestFSValidatorJSONSchemaRegistrationError(t *testing.T) {
-	v := NewFSValidator(fstest.MapFS{
-		"schemas/%zz.json": &fstest.MapFile{Data: []byte(`{"type":"object"}`)},
-	}, "schemas")
+func TestFSValidatorEscapesSchemaResourcePath(t *testing.T) {
+	for _, schemaName := range []string{"%zz.json", "space name.json", "hash#.json", "query?.json", "rún.json"} {
+		t.Run(schemaName, func(t *testing.T) {
+			v := NewFSValidator(fstest.MapFS{
+				"schemas/" + schemaName: &fstest.MapFile{Data: []byte(`{"type":"object"}`)},
+			}, "schemas")
 
-	res, err := v.Validate(context.Background(), &domain.Artifact{Body: []byte(`{}`)}, domain.OutputContract{
+			res, err := v.Validate(context.Background(), &domain.Artifact{Body: []byte(`{}`)}, domain.OutputContract{
+				ValidationMode: domain.ValidationJSONSchema,
+				SchemaPath:     schemaName,
+			})
+			if err != nil || !res.IsValid {
+				t.Fatalf("validate schema %q: result=%#v error=%v", schemaName, res, err)
+			}
+		})
+	}
+}
+
+func TestSchemaReferencesPreserveEscapedFilenames(t *testing.T) {
+	for _, name := range []string{"%2F.json", "space name.json", "hash#.json", "query?.json", "rún.json"} {
+		t.Run(name, func(t *testing.T) {
+			rootName := "root-" + name
+			childName := "child-" + name
+			childPath := "nested/" + childName
+			reference := (&url.URL{Path: childPath}).EscapedPath()
+			rootSchema := []byte(`{"$ref":` + strconv.Quote(reference) + `}`)
+			childSchema := []byte(`{"type":"integer","minimum":2}`)
+
+			t.Run("fs.FS", func(t *testing.T) {
+				validator := NewFSValidator(fstest.MapFS{
+					"schemas/" + rootName:  &fstest.MapFile{Data: rootSchema},
+					"schemas/" + childPath: &fstest.MapFile{Data: childSchema},
+				}, "schemas")
+				assertSchemaValidation(t, validator, rootName)
+			})
+
+			t.Run("operating system files", func(t *testing.T) {
+				if runtime.GOOS == "windows" && strings.ContainsAny(rootName+childName, `<>:"/\|?*`) {
+					t.Skip("filename is not legal on Windows")
+				}
+				root := t.TempDir()
+				if err := os.Mkdir(filepath.Join(root, "nested"), 0o755); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.WriteFile(filepath.Join(root, rootName), rootSchema, 0o644); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.WriteFile(filepath.Join(root, filepath.FromSlash(childPath)), childSchema, 0o644); err != nil {
+					t.Fatal(err)
+				}
+				assertSchemaValidation(t, NewStandardValidator(root), rootName)
+			})
+		})
+	}
+}
+
+func assertSchemaValidation(t *testing.T, validator Validator, schemaPath string) {
+	t.Helper()
+	result, err := validator.Validate(context.Background(), &domain.Artifact{Body: []byte(`2`)}, domain.OutputContract{
 		ValidationMode: domain.ValidationJSONSchema,
-		SchemaPath:     "%zz.json",
+		SchemaPath:     schemaPath,
 	})
-	if err == nil || !strings.Contains(err.Error(), "failed to register JSON schema") {
-		t.Fatalf("expected schema registration error, got result=%#v error=%v", res, err)
+	if err != nil || !result.IsValid {
+		t.Fatalf("validate schema %q: result=%#v error=%v", schemaPath, result, err)
 	}
 }
 
@@ -561,25 +567,6 @@ func TestFSValidatorSingleSchemaFileUsesBaseName(t *testing.T) {
 	}
 }
 
-func TestFSValidatorLoadSchemaDocument(t *testing.T) {
-	v := NewFSValidator(fstest.MapFS{
-		"schemas/schema.json": &fstest.MapFile{Data: []byte(`{"type":"object"}`)},
-	}, "schemas")
-	loader, ok := v.(SchemaDocumentLoader)
-	if !ok {
-		t.Fatal("fs validator must implement SchemaDocumentLoader")
-	}
-
-	doc, err := loader.LoadSchemaDocument(context.Background(), "schema.json")
-	if err != nil {
-		t.Fatalf("expected no error, got %v", err)
-	}
-	obj, ok := doc.(map[string]any)
-	if !ok || obj["type"] != "object" {
-		t.Fatalf("unexpected schema document: %#v", doc)
-	}
-}
-
 func TestStandardValidatorJSONSchemaReferenceBoundaries(t *testing.T) {
 	root := t.TempDir()
 	if err := os.WriteFile(filepath.Join(root, "child.json"), []byte(`{

internal/validate/validator.go

@@ -24,8 +24,3 @@ type PreparedValidation interface {
 type ValidationPreparer interface {
 	PrepareValidation(ctx context.Context, contract domain.OutputContract) (PreparedValidation, error)
 }
-
-// SchemaDocumentLoader loads JSON schema documents using validator path semantics.
-type SchemaDocumentLoader interface {
-	LoadSchemaDocument(ctx context.Context, schemaPath string) (any, error)
-}