fix: address CodeRabbit review findings from PR #359

- jsonpath: guard against typed-nil map[string]any in Modify root path
  (a typed nil passes the type assertion but panics on write)
- parser: handle []any in promoteSchemaOrBool for OAS 2.0 tuple-form
  items arrays (matches existing decodeSchemaOrBool YAML path)
- tests: add TestModifyRoot_InvalidDoc for non-map and typed-nil cases
- tests: add Items bool and tuple-array round-trip cases to schema JSON tests
- tests: add TestConvertOAS2ParameterToOAS3_ArrayWithoutItems for nil Items

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

Author: erraggy

converter/helpers_test.go

@@ -740,6 +740,26 @@ func TestConvertOAS2ParameterToOAS3_ItemsCollectionFormat(t *testing.T) {
 		"should warn about non-csv collectionFormat on items")
 }
 
+// TestConvertOAS2ParameterToOAS3_ArrayWithoutItems verifies that an array
+// parameter with nil Items is handled gracefully.
+func TestConvertOAS2ParameterToOAS3_ArrayWithoutItems(t *testing.T) {
+	c := newConverter()
+	result := &ConversionResult{}
+
+	param := &parser.Parameter{
+		Name: "tags",
+		In:   "query",
+		Type: "array",
+		// Items intentionally nil
+	}
+
+	converted := c.convertOAS2ParameterToOAS3(param, result, "test")
+	require.NotNil(t, converted)
+	require.NotNil(t, converted.Schema)
+	assert.Equal(t, "array", converted.Schema.Type, "Schema.Type should be array")
+	assert.Nil(t, converted.Schema.Items, "Schema.Items should be nil when source has no Items")
+}
+
 // newConverter creates a Converter for unit testing helpers using the same
 // initialization path as production code.
 func newConverter() *Converter {

internal/jsonpath/eval.go

@@ -119,11 +119,12 @@ func (p *Path) Remove(doc any) (any, error) {
 // the caller's variable cannot be reassigned.
 func (p *Path) Modify(doc any, fn func(any) any) error {
 	if len(p.segments) < 2 {
-		if _, ok := doc.(map[string]any); !ok {
-			return fmt.Errorf("jsonpath: root path Modify requires a map document; got %T", doc)
+		m, ok := doc.(map[string]any)
+		if !ok || m == nil {
+			return fmt.Errorf("jsonpath: root path Modify requires a non-nil map document; got %T", doc)
 		}
 		// fn is expected to mutate the map in place; return value is ignored.
-		fn(doc)
+		fn(m)
 		return nil
 	}
 

internal/jsonpath/jsonpath_test.go

@@ -1042,6 +1042,24 @@ func TestModifyRoot(t *testing.T) {
 	assert.Equal(t, "api.example.com", doc["host"], "root Modify should merge into document")
 }
 
+// TestModifyRoot_InvalidDoc verifies that Modify on root path "$" returns an
+// error for non-map and typed-nil map documents.
+func TestModifyRoot_InvalidDoc(t *testing.T) {
+	p, err := Parse("$")
+	require.NoError(t, err)
+
+	t.Run("non-map value returns error", func(t *testing.T) {
+		err := p.Modify("not a map", func(v any) any { return v })
+		require.Error(t, err)
+	})
+
+	t.Run("typed-nil map returns error", func(t *testing.T) {
+		var doc map[string]any
+		err := p.Modify(doc, func(v any) any { return v })
+		require.Error(t, err)
+	})
+}
+
 // TestRemoveArrayIndex_Splices verifies that Remove on an index segment produces
 // a correctly spliced slice (no nil gaps) — regression for issue #351.
 func TestRemoveArrayIndex_Splices(t *testing.T) {

parser/schema_json.go

@@ -122,11 +122,11 @@ func (s *Schema) UnmarshalJSON(data []byte) error {
 // map cannot be round-tripped through JSON into a *Schema, so callers get a
 // clear parse error rather than a silent type-assertion panic downstream.
 func promoteSchemaOrBool(v any) (any, error) {
-	switch v.(type) {
+	switch val := v.(type) {
 	case nil, bool, *Schema:
 		return v, nil
 	case map[string]any:
-		data, err := json.Marshal(v)
+		data, err := json.Marshal(val)
 		if err != nil {
 			return nil, fmt.Errorf("parser: schema field promotion: %w", err)
 		}
@@ -135,6 +135,19 @@ func promoteSchemaOrBool(v any) (any, error) {
 			return nil, fmt.Errorf("parser: schema field promotion: %w", err)
 		}
 		return s, nil
+	case []any:
+		// OAS 2.0 tuple validation: items can be an array of schemas.
+		schemas := make([]*Schema, 0, len(val))
+		for _, elem := range val {
+			promoted, err := promoteSchemaOrBool(elem)
+			if err != nil {
+				return nil, err
+			}
+			if s, ok := promoted.(*Schema); ok {
+				schemas = append(schemas, s)
+			}
+		}
+		return schemas, nil
 	}
 	return v, nil
 }

parser/schema_json_test.go

@@ -295,6 +295,24 @@ func TestSchemaJSONRoundTrip(t *testing.T) {
 		assert.True(t, ok, "Items should be *Schema after JSON unmarshal, not map[string]any")
 	})
 
+	t.Run("Items bool true preserved (OAS 3.1+)", func(t *testing.T) {
+		data := []byte(`{"type":"array","items":true}`)
+		var s Schema
+		require.NoError(t, json.Unmarshal(data, &s))
+		b, ok := s.Items.(bool)
+		assert.True(t, ok, "items true should remain bool")
+		assert.True(t, b)
+	})
+
+	t.Run("Items array decoded as []*Schema (OAS 2.0 tuple)", func(t *testing.T) {
+		data := []byte(`{"type":"array","items":[{"type":"string"},{"type":"integer"}]}`)
+		var s Schema
+		require.NoError(t, json.Unmarshal(data, &s))
+		arr, ok := s.Items.([]*Schema)
+		assert.True(t, ok, "items array should be []*Schema after JSON unmarshal")
+		assert.Len(t, arr, 2)
+	})
+
 	t.Run("additionalProperties object decoded as *Schema", func(t *testing.T) {
 		data := []byte(`{"type":"object","additionalProperties":{"type":"string"}}`)
 		var s Schema