Attempting to fix daveshanley/vacuum#850

trying to not incorrectly mutate the bundling output.

Author: daveshanley

bundler/bundler_test.go

@@ -94,6 +94,93 @@ func isEmptyRef(line string) bool {
 	return ref == "{}" || ref == ""
 }
 
+func TestBundleDocument_PreservesInvalidComponentMapRefsAndWarns(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	spec := `openapi: 3.0.3
+info:
+  title: Test API
+  version: 1.0.0
+components:
+  parameters:
+    $ref: "./params.yaml"
+    LocalParam:
+      name: local
+      in: query
+      schema:
+        type: string
+  schemas:
+    $ref: "./schemas.yaml"
+    LocalSchema:
+      type: object
+      properties:
+        local:
+          type: string
+paths:
+  /test:
+    get:
+      parameters:
+        - $ref: "#/components/parameters/LocalParam"
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/LocalSchema"
+`
+
+	params := `RemoteParam:
+  name: remote
+  in: query
+  schema:
+    type: string
+`
+
+	schemas := `RemoteSchema:
+  type: object
+  properties:
+    id:
+      type: string
+`
+
+	require.NoError(t, os.WriteFile(filepath.Join(tmpDir, "openapi.yaml"), []byte(spec), 0644))
+	require.NoError(t, os.WriteFile(filepath.Join(tmpDir, "params.yaml"), []byte(params), 0644))
+	require.NoError(t, os.WriteFile(filepath.Join(tmpDir, "schemas.yaml"), []byte(schemas), 0644))
+
+	var logBuf bytes.Buffer
+	cfg := &datamodel.DocumentConfiguration{
+		BasePath:            tmpDir,
+		AllowFileReferences: true,
+		Logger: slog.New(slog.NewJSONHandler(&logBuf, &slog.HandlerOptions{
+			Level: slog.LevelWarn,
+		})),
+	}
+
+	specBytes, err := os.ReadFile(filepath.Join(tmpDir, "openapi.yaml"))
+	require.NoError(t, err)
+
+	doc, err := libopenapi.NewDocumentWithConfiguration(specBytes, cfg)
+	require.NoError(t, err)
+
+	v3Doc, errs := doc.BuildV3Model()
+	require.NoError(t, errs)
+	require.NotNil(t, v3Doc)
+
+	bundledBytes, err := BundleDocument(&v3Doc.Model)
+	require.NoError(t, err)
+
+	bundledStr := string(bundledBytes)
+	assert.Contains(t, bundledStr, "$ref: \"./params.yaml\"")
+	assert.Contains(t, bundledStr, "$ref: \"./schemas.yaml\"")
+	assert.NotContains(t, bundledStr, "$ref: {}")
+
+	logOutput := logBuf.String()
+	assert.Contains(t, logOutput, "preserving invalid component map $ref entry during render")
+	assert.Contains(t, logOutput, "\"section\":\"parameters\"")
+	assert.Contains(t, logOutput, "\"section\":\"schemas\"")
+}
+
 func writeIssue831Fixture(t *testing.T) string {
 	t.Helper()
 

datamodel/high/v3/components.go

@@ -13,6 +13,7 @@ import (
 	"github.com/pb33f/libopenapi/datamodel/low/base"
 	low "github.com/pb33f/libopenapi/datamodel/low/v3"
 	"github.com/pb33f/libopenapi/orderedmap"
+	"github.com/pb33f/libopenapi/utils"
 	"go.yaml.in/yaml/v4"
 )
 
@@ -173,8 +174,11 @@ func (c *Components) Render() ([]byte, error) {
 
 // MarshalYAML will create a ready to render YAML representation of the Response object.
 func (c *Components) MarshalYAML() (interface{}, error) {
+	c.warnPreservedComponentMapRefs()
 	nb := high.NewNodeBuilder(c, c.low)
-	return nb.Render(), nil
+	rendered := nb.Render()
+	c.preserveInvalidComponentMapRefs(rendered)
+	return rendered, nil
 }
 
 // RenderInline will return a YAML representation of the Components object as a byte slice with references resolved.
@@ -185,7 +189,177 @@ func (c *Components) RenderInline() ([]byte, error) {
 
 // MarshalYAMLInline will create a ready to render YAML representation of the Components object with references resolved.
 func (c *Components) MarshalYAMLInline() (interface{}, error) {
+	c.warnPreservedComponentMapRefs()
 	nb := high.NewNodeBuilder(c, c.low)
 	nb.Resolve = true
-	return nb.Render(), nil
+	rendered := nb.Render()
+	c.preserveInvalidComponentMapRefs(rendered)
+	return rendered, nil
+}
+
+func (c *Components) warnPreservedComponentMapRefs() {
+	if c == nil || c.low == nil {
+		return
+	}
+	idx := c.low.GetIndex()
+	if idx == nil {
+		return
+	}
+	logger := idx.GetLogger()
+	if logger == nil {
+		return
+	}
+
+	warnComponentRefEntries(logger, low.SchemasLabel, c.low.Schemas.Value)
+	warnComponentRefEntries(logger, low.ResponsesLabel, c.low.Responses.Value)
+	warnComponentRefEntries(logger, low.ParametersLabel, c.low.Parameters.Value)
+	warnComponentRefEntries(logger, base.ExamplesLabel, c.low.Examples.Value)
+	warnComponentRefEntries(logger, low.RequestBodiesLabel, c.low.RequestBodies.Value)
+	warnComponentRefEntries(logger, low.HeadersLabel, c.low.Headers.Value)
+	warnComponentRefEntries(logger, low.SecuritySchemesLabel, c.low.SecuritySchemes.Value)
+	warnComponentRefEntries(logger, low.LinksLabel, c.low.Links.Value)
+	warnComponentRefEntries(logger, low.CallbacksLabel, c.low.Callbacks.Value)
+	warnComponentRefEntries(logger, low.PathItemsLabel, c.low.PathItems.Value)
+	warnComponentRefEntries(logger, low.MediaTypesLabel, c.low.MediaTypes.Value)
+}
+
+func warnComponentRefEntries[T any](
+	logger interface {
+		Warn(msg string, args ...any)
+	},
+	section string,
+	m *orderedmap.Map[lowmodel.KeyReference[string], lowmodel.ValueReference[T]],
+) {
+	if m == nil {
+		return
+	}
+
+	for pair := m.First(); pair != nil; pair = pair.Next() {
+		if pair.Key().Value != "$ref" {
+			continue
+		}
+		valueNode := pair.Value().ValueNode
+		if valueNode == nil || valueNode.Kind != yaml.ScalarNode {
+			continue
+		}
+		logger.Warn(
+			"preserving invalid component map $ref entry during render",
+			"section", section,
+			"ref", valueNode.Value,
+			"line", valueNode.Line,
+			"column", valueNode.Column,
+		)
+	}
+}
+
+// preserveInvalidComponentMapRefs patches the rendered Components YAML tree so that invalid
+// map-level "$ref" entries under component sections survive a render cycle unchanged.
+//
+// Inputs like:
+//
+//	components:
+//	  parameters:
+//	    $ref: "./params.yaml"
+//
+// are not valid OpenAPI component maps, but they do appear in the wild. The normal high-level
+// render path treats "$ref" as a literal component name and can otherwise collapse the scalar
+// value into an empty object. For these cases we preserve the original raw YAML nodes and pair
+// the behavior with a warning log, rather than silently rewriting the input.
+func (c *Components) preserveInvalidComponentMapRefs(rendered *yaml.Node) {
+	if c == nil || c.low == nil || rendered == nil || rendered.Kind != yaml.MappingNode {
+		return
+	}
+
+	preserveComponentRefEntries(rendered, low.SchemasLabel, c.low.Schemas.Value)
+	preserveComponentRefEntries(rendered, low.ResponsesLabel, c.low.Responses.Value)
+	preserveComponentRefEntries(rendered, low.ParametersLabel, c.low.Parameters.Value)
+	preserveComponentRefEntries(rendered, base.ExamplesLabel, c.low.Examples.Value)
+	preserveComponentRefEntries(rendered, low.RequestBodiesLabel, c.low.RequestBodies.Value)
+	preserveComponentRefEntries(rendered, low.HeadersLabel, c.low.Headers.Value)
+	preserveComponentRefEntries(rendered, low.SecuritySchemesLabel, c.low.SecuritySchemes.Value)
+	preserveComponentRefEntries(rendered, low.LinksLabel, c.low.Links.Value)
+	preserveComponentRefEntries(rendered, low.CallbacksLabel, c.low.Callbacks.Value)
+	preserveComponentRefEntries(rendered, low.PathItemsLabel, c.low.PathItems.Value)
+	preserveComponentRefEntries(rendered, low.MediaTypesLabel, c.low.MediaTypes.Value)
+}
+
+// preserveComponentRefEntries re-inserts a scalar "$ref" entry into the rendered YAML for a
+// specific component section. Only literal "$ref" keys backed by scalar low-level value nodes
+// are preserved; real component entries and malformed non-scalar values are ignored.
+func preserveComponentRefEntries[T any](
+	rendered *yaml.Node,
+	section string,
+	m *orderedmap.Map[lowmodel.KeyReference[string], lowmodel.ValueReference[T]],
+) {
+	if m == nil {
+		return
+	}
+
+	sectionNode := findMapValueNode(rendered, section)
+	for pair := m.First(); pair != nil; pair = pair.Next() {
+		if pair.Key().Value != "$ref" {
+			continue
+		}
+
+		valueNode := pair.Value().ValueNode
+		keyNode := pair.Key().KeyNode
+		if keyNode == nil || valueNode == nil || valueNode.Kind != yaml.ScalarNode {
+			continue
+		}
+
+		if sectionNode == nil {
+			sectionNode = utils.CreateEmptyMapNode()
+			rendered.Content = append(
+				rendered.Content,
+				utils.CreateStringNode(section),
+				sectionNode,
+			)
+		}
+		upsertMapNodeEntry(sectionNode, cloneYAMLNode(keyNode), cloneYAMLNode(valueNode))
+	}
+}
+
+// findMapValueNode returns the mapping value node for key from a YAML mapping node.
+func findMapValueNode(m *yaml.Node, key string) *yaml.Node {
+	if m == nil || m.Kind != yaml.MappingNode {
+		return nil
+	}
+	for i := 0; i < len(m.Content); i += 2 {
+		if m.Content[i].Value == key {
+			return m.Content[i+1]
+		}
+	}
+	return nil
+}
+
+// upsertMapNodeEntry replaces or appends a key/value pair in a YAML mapping node.
+func upsertMapNodeEntry(m *yaml.Node, keyNode, valueNode *yaml.Node) {
+	if m == nil || m.Kind != yaml.MappingNode || keyNode == nil || valueNode == nil {
+		return
+	}
+	for i := 0; i < len(m.Content); i += 2 {
+		if m.Content[i].Value == keyNode.Value {
+			m.Content[i] = keyNode
+			m.Content[i+1] = valueNode
+			return
+		}
+	}
+	m.Content = append(m.Content, keyNode, valueNode)
+}
+
+// cloneYAMLNode deep-copies a YAML node tree so preserved low-level nodes can be spliced into
+// rendered output without mutating the original parsed model.
+func cloneYAMLNode(node *yaml.Node) *yaml.Node {
+	if node == nil {
+		return nil
+	}
+
+	cloned := *node
+	if len(node.Content) > 0 {
+		cloned.Content = make([]*yaml.Node, len(node.Content))
+		for i, child := range node.Content {
+			cloned.Content[i] = cloneYAMLNode(child)
+		}
+	}
+	return &cloned
 }