fix: prevent panic on invalid paths entries during index build (#197)

Author: TristanSpeakEasy

openapi/index_test.go

@@ -1220,6 +1220,52 @@ paths:
 	assert.Len(t, idx.InlinePathItems, 2, "should have 2 inline path items")
 }
 
+func TestBuildIndex_InvalidPathsEntries_NoPanicAndValidationErrors_Success(t *testing.T) {
+	t.Parallel()
+	ctx := t.Context()
+
+	yaml := `
+openapi: "3.1.0"
+info:
+  title: Test API
+  version: 1.0.0
+paths:
+  /api/v1/foo: []
+  foo: bar
+`
+
+	doc, validationErrs, err := openapi.Unmarshal(ctx, strings.NewReader(yaml))
+	require.NoError(t, err, "unmarshal should succeed")
+	require.NotNil(t, doc, "document should still be created")
+	require.NotEmpty(t, validationErrs, "invalid paths entries should produce validation errors")
+
+	var validationErrMessages []string
+	for _, validationErr := range validationErrs {
+		validationErrMessages = append(validationErrMessages, validationErr.Error())
+	}
+
+	require.Len(t, validationErrMessages, 2, "should report both invalid path entries")
+	assert.Contains(t, validationErrMessages[0], "validation-type-mismatch", "should classify invalid path entries as type mismatch")
+	assert.Contains(t, validationErrMessages[0], "paths./api/v1/foo", "should point to the invalid path key")
+	assert.Contains(t, validationErrMessages[0], "expected `object`, got sequence", "should explain that array path item values are invalid")
+	assert.Contains(t, validationErrMessages[1], "validation-type-mismatch", "should classify invalid path entries as type mismatch")
+	assert.Contains(t, validationErrMessages[1], "paths.foo", "should point to the invalid non-path key")
+	assert.Contains(t, validationErrMessages[1], "expected `object`, got scalar", "should explain that scalar path item values are invalid")
+
+	var idx *openapi.Index
+	assert.NotPanics(t, func() {
+		idx = openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+			RootDocument:   doc,
+			TargetDocument: doc,
+			TargetLocation: "test.yaml",
+		})
+	}, "indexing invalid paths entries should not panic")
+
+	require.NotNil(t, idx, "index should not be nil")
+	// Type mismatch validation errors for invalid path entries are surfaced by Unmarshal;
+	// BuildIndex should remain panic-free and produce a usable index for callers.
+}
+
 func TestBuildIndex_Parameters_Success(t *testing.T) {
 	t.Parallel()
 	ctx := t.Context()

openapi/sanitize.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"reflect"
 
 	"github.com/speakeasy-api/openapi/extensions"
 	"github.com/speakeasy-api/openapi/jsonschema/oas3"
@@ -599,8 +600,26 @@ func cleanUnknownPropertiesFromModel(model any) error {
 	return nil
 }
 
+func isNilAny(v any) bool {
+	if v == nil {
+		return true
+	}
+
+	rv := reflect.ValueOf(v)
+	switch rv.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Map, reflect.Pointer, reflect.Slice:
+		return rv.IsNil()
+	default:
+		return false
+	}
+}
+
 // getCoreModelFromAny attempts to extract a core model from various wrapper types
 func getCoreModelFromAny(model any) any {
+	if isNilAny(model) {
+		return nil
+	}
+
 	// Try direct core getter
 	type coreGetter interface {
 		GetCoreAny() any
@@ -609,7 +628,7 @@ func getCoreModelFromAny(model any) any {
 	var directCore any
 	if coreModel, ok := model.(coreGetter); ok {
 		directCore = coreModel.GetCoreAny()
-		if directCore != nil {
+		if !isNilAny(directCore) {
 			if coreModeler, ok := directCore.(marshaller.CoreModeler); ok {
 				if len(coreModeler.GetUnknownProperties()) > 0 {
 					return directCore
@@ -627,9 +646,9 @@ func getCoreModelFromAny(model any) any {
 
 	if navigable, ok := model.(navigableNoder); ok {
 		inner, err := navigable.GetNavigableNode()
-		if err == nil && inner != nil {
+		if err == nil && !isNilAny(inner) {
 			// Recursively try to get core from the inner value
-			if innerCore := getCoreModelFromAny(inner); innerCore != nil {
+			if innerCore := getCoreModelFromAny(inner); !isNilAny(innerCore) {
 				return innerCore
 			}
 		}
@@ -641,7 +660,7 @@ func getCoreModelFromAny(model any) any {
 // getRootNodeFromAny attempts to extract the root yaml.Node from various OpenAPI types.
 // This is used for node-to-operation mapping during indexing.
 func getRootNodeFromAny(model any) *yaml.Node {
-	if model == nil {
+	if isNilAny(model) {
 		return nil
 	}
 
@@ -661,14 +680,14 @@ func getRootNodeFromAny(model any) *yaml.Node {
 
 	if navigable, ok := model.(navigableNoder); ok {
 		inner, err := navigable.GetNavigableNode()
-		if err == nil && inner != nil {
+		if err == nil && !isNilAny(inner) {
 			// Recursively try to get root node from the inner value
 			return getRootNodeFromAny(inner)
 		}
 	}
 
 	// Try to get core model and extract root node from there
-	if core := getCoreModelFromAny(model); core != nil {
+	if core := getCoreModelFromAny(model); !isNilAny(core) {
 		if getter, ok := core.(rootNodeGetter); ok {
 			return getter.GetRootNode()
 		}