fix: rebase vendor extension $refs in composed bundles

Rewrite $ref values nested under x-* extension keys so they are relative to the bundled root document instead of their original source file, and skip extension refs during composer remapping so they are not lifted into components or inlined.

Author: daveshanley

bundler/bundler.go

@@ -538,6 +538,7 @@ func composeWithOrigins(model *v3.Document, compositionConfig *BundleComposition
 	if err := handleDiscriminatorMappingIndexes(cf, rootIndex, rolodex); err != nil {
 		return nil, err
 	}
+	rewriteExtensionRefsForComposedBundle(rolodex)
 
 	processedNodes := orderedmap.New[string, *processRef]()
 	var errs []error
@@ -701,6 +702,7 @@ func compose(model *v3.Document, compositionConfig *BundleCompositionConfig) ([]
 	if err := handleDiscriminatorMappingIndexes(cf, rootIndex, rolodex); err != nil {
 		return nil, err
 	}
+	rewriteExtensionRefsForComposedBundle(rolodex)
 
 	processedNodes := orderedmap.New[string, *processRef]()
 	var errs []error

bundler/bundler_composer.go

@@ -62,6 +62,9 @@ func handleIndex(c *handleIndexConfig) error {
 	var indexesToExplore []*index.SpecIndex
 
 	for _, sequenced := range sequencedReferences {
+		if sequenced.IsExtensionRef {
+			continue
+		}
 		mappedReference := mappedReferences[sequenced.FullDefinition]
 
 		// Check for invalid sibling properties if strict validation is enabled

bundler/bundler_ref_rewrite_test.go

@@ -1128,6 +1128,85 @@ properties:
 		"Extension internal refs should be preserved as-is")
 }
 
+func TestBundlerComposed_RewritesExcludedVendorExtensionDollarRefsFromExternalPathItem(t *testing.T) {
+	tmpDir := t.TempDir()
+	rootBytes := writeComposedExtensionRefFixture(t, tmpDir)
+
+	config := datamodel.NewDocumentConfiguration()
+	config.BasePath = tmpDir
+	config.AllowFileReferences = true
+	config.ExcludeExtensionRefs = true
+
+	bundled, err := BundleBytesComposed(rootBytes, config, nil)
+	require.NoError(t, err)
+
+	bundledStr := string(bundled)
+	assert.Contains(t, bundledStr, "code_samples/C_sharp/echo/post.cs")
+	assert.NotContains(t, bundledStr, "../code_samples/C_sharp/echo/post.cs")
+
+	doc, err := libopenapi.NewDocumentWithConfiguration(bundled, &datamodel.DocumentConfiguration{
+		BasePath:             tmpDir,
+		AllowFileReferences:  true,
+		ExcludeExtensionRefs: true,
+	})
+	require.NoError(t, err)
+	v3Doc, buildErr := doc.BuildV3Model()
+	require.NoError(t, buildErr)
+	require.NotNil(t, v3Doc)
+}
+
+func TestBundlerComposed_RewritesIncludedVendorExtensionDollarRefsWithoutComposingThem(t *testing.T) {
+	tmpDir := t.TempDir()
+	rootBytes := writeComposedExtensionRefFixture(t, tmpDir)
+
+	config := datamodel.NewDocumentConfiguration()
+	config.BasePath = tmpDir
+	config.AllowFileReferences = true
+
+	bundled, err := BundleBytesComposed(rootBytes, config, nil)
+	require.NoError(t, err)
+
+	bundledStr := string(bundled)
+	assert.Contains(t, bundledStr, "code_samples/C_sharp/echo/post.cs")
+	assert.NotContains(t, bundledStr, "../code_samples/C_sharp/echo/post.cs")
+	assert.NotContains(t, bundledStr, "Console.WriteLine",
+		"Extension $refs should be rebased, not composed or inlined")
+}
+
+func writeComposedExtensionRefFixture(t *testing.T, tmpDir string) []byte {
+	t.Helper()
+
+	rootSpec := `openapi: 3.1.0
+info:
+  title: Test API
+  version: 1.0.0
+paths:
+  /echo:
+    $ref: ./paths/echo.yaml
+`
+
+	echoPath := `post:
+  summary: Echo
+  responses:
+    '200':
+      description: OK
+  x-codeSamples:
+    - lang: C#
+      source:
+        $ref: ../code_samples/C_sharp/echo/post.cs
+`
+
+	require.NoError(t, os.WriteFile(filepath.Join(tmpDir, "openapi.yaml"), []byte(rootSpec), 0644))
+	require.NoError(t, os.MkdirAll(filepath.Join(tmpDir, "paths"), 0755))
+	require.NoError(t, os.WriteFile(filepath.Join(tmpDir, "paths", "echo.yaml"), []byte(echoPath), 0644))
+	require.NoError(t, os.MkdirAll(filepath.Join(tmpDir, "code_samples", "C_sharp", "echo"), 0755))
+	require.NoError(t, os.WriteFile(filepath.Join(tmpDir, "code_samples", "C_sharp", "echo", "post.cs"), []byte(`Console.WriteLine("hello");`), 0644))
+
+	rootBytes, err := os.ReadFile(filepath.Join(tmpDir, "openapi.yaml"))
+	require.NoError(t, err)
+	return rootBytes
+}
+
 // TestBundlerComposed_HandlesEmptyMappingValues verifies that empty discriminator
 // mapping values don't cause errors
 func TestBundlerComposed_HandlesEmptyMappingValues(t *testing.T) {

bundler/composer_functions.go

@@ -215,6 +215,9 @@ func remapIndex(idx *index.SpecIndex, processedNodes *orderedmap.Map[string, *pr
 	rewiredRefNodes := make(map[*yaml.Node]struct{}, len(seq))
 
 	for _, sequenced := range seq {
+		if sequenced.IsExtensionRef {
+			continue
+		}
 		if refValNode := utils.GetRefValueNode(sequenced.Node); refValNode != nil {
 			rewiredRefNodes[refValNode] = struct{}{}
 		}
@@ -224,6 +227,9 @@ func remapIndex(idx *index.SpecIndex, processedNodes *orderedmap.Map[string, *pr
 	mapped := idx.GetMappedReferences()
 
 	for _, mRef := range mapped {
+		if mRef.IsExtensionRef {
+			continue
+		}
 		if refValNode := utils.GetRefValueNode(mRef.Node); refValNode != nil {
 			if _, ok := rewiredRefNodes[refValNode]; ok {
 				continue

bundler/composer_functions_test.go

@@ -13,6 +13,7 @@ import (
 	"github.com/pb33f/libopenapi/orderedmap"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"go.yaml.in/yaml/v4"
 )
 
 func TestHandleFileImport_StripsFragment(t *testing.T) {
@@ -36,6 +37,30 @@ func TestWalkAndRewriteRefs_NilNode(t *testing.T) {
 	})
 }
 
+func TestRemapIndexSkipsMappedExtensionRefs(t *testing.T) {
+	var root yaml.Node
+	require.NoError(t, yaml.Unmarshal([]byte(`openapi: 3.1.0`), &root))
+	idx := index.NewSpecIndexWithConfig(&root, index.CreateOpenAPIIndexConfig())
+
+	refNode := &yaml.Node{
+		Kind: yaml.MappingNode,
+		Content: []*yaml.Node{
+			{Kind: yaml.ScalarNode, Value: "$ref"},
+			{Kind: yaml.ScalarNode, Value: "./sample.md"},
+		},
+	}
+	idx.SetMappedReferences(map[string]*index.Reference{
+		"./sample.md": {
+			FullDefinition: "./sample.md",
+			Node:           refNode,
+			IsExtensionRef: true,
+		},
+	})
+
+	remapIndex(idx, orderedmap.New[string, *processRef]())
+	assert.Equal(t, "./sample.md", refNode.Content[1].Value)
+}
+
 func TestResolveRefToComposed_PreservesExternalRefs(t *testing.T) {
 	assert.Equal(t, "https://example.com/schema.json", resolveRefToComposed("https://example.com/schema.json", nil, nil, nil))
 	assert.Equal(t, "urn:example:thing", resolveRefToComposed("urn:example:thing", nil, nil, nil))

bundler/extension_refs.go

@@ -6,7 +6,11 @@ package bundler
 
 import (
 	"context"
+	"os"
+	"path/filepath"
+	"strings"
 
+	"github.com/pb33f/libopenapi/utils"
 	"go.yaml.in/yaml/v4"
 
 	"github.com/pb33f/libopenapi/index"
@@ -123,3 +127,118 @@ func replaceRefNodeWithContent(refNode, content *yaml.Node) {
 	refNode.LineComment = content.LineComment
 	refNode.FootComment = content.FootComment
 }
+
+// rewriteExtensionRefsForComposedBundle rebases $ref values found under x-* extension
+// keys from their original source file location to the bundled root document.
+func rewriteExtensionRefsForComposedBundle(rolodex *index.Rolodex) {
+	if rolodex == nil {
+		return
+	}
+	rootIdx := rolodex.GetRootIndex()
+	if rootIdx == nil {
+		return
+	}
+	rewriteExtensionRefsForComposedIndex(rootIdx, rootIdx)
+	for _, idx := range rolodex.GetIndexes() {
+		rewriteExtensionRefsForComposedIndex(idx, rootIdx)
+	}
+}
+
+func rewriteExtensionRefsForComposedIndex(sourceIdx, rootIdx *index.SpecIndex) {
+	if sourceIdx == nil || rootIdx == nil {
+		return
+	}
+	if sourceIdx.GetSpecAbsolutePath() == rootIdx.GetSpecAbsolutePath() {
+		return
+	}
+	walkAndRewriteComposedExtensionRefs(sourceIdx.GetRootNode(), sourceIdx, rootIdx, false)
+}
+
+func walkAndRewriteComposedExtensionRefs(node *yaml.Node, sourceIdx, rootIdx *index.SpecIndex, inExtension bool) {
+	if node == nil {
+		return
+	}
+	switch node.Kind {
+	case yaml.DocumentNode:
+		for _, child := range node.Content {
+			walkAndRewriteComposedExtensionRefs(child, sourceIdx, rootIdx, inExtension)
+		}
+	case yaml.SequenceNode:
+		for _, child := range node.Content {
+			walkAndRewriteComposedExtensionRefs(child, sourceIdx, rootIdx, inExtension)
+		}
+	case yaml.MappingNode:
+		for i := 0; i+1 < len(node.Content); i += 2 {
+			keyNode := node.Content[i]
+			valueNode := node.Content[i+1]
+			if keyNode == nil {
+				continue
+			}
+			childInExtension := inExtension || strings.HasPrefix(keyNode.Value, "x-")
+			if childInExtension && keyNode.Value == "$ref" && valueNode != nil && valueNode.Kind == yaml.ScalarNode {
+				valueNode.Value = rebaseExtensionRefForComposed(valueNode.Value, sourceIdx, rootIdx)
+				continue
+			}
+			walkAndRewriteComposedExtensionRefs(valueNode, sourceIdx, rootIdx, childInExtension)
+		}
+	}
+}
+
+func rebaseExtensionRefForComposed(refValue string, sourceIdx, rootIdx *index.SpecIndex) string {
+	pathPart, fragment := splitRefPathAndFragment(refValue)
+	if pathPart == "" {
+		if fragment == "" || sourceIdx == nil || sourceIdx.GetSpecAbsolutePath() == "" || isExternalRefURI(sourceIdx.GetSpecAbsolutePath()) {
+			return refValue
+		}
+		pathPart = sourceIdx.GetSpecAbsolutePath()
+	}
+	if isExternalRefURI(pathPart) {
+		return refValue
+	}
+	sourceDir := specDir(sourceIdx)
+	rootDir := specDir(rootIdx)
+	if sourceDir == "" || rootDir == "" {
+		return refValue
+	}
+	targetPath := pathPart
+	if !filepath.IsAbs(targetPath) {
+		targetPath = utils.CheckPathOverlap(sourceDir, targetPath, string(os.PathSeparator))
+	}
+	absTarget, err := filepath.Abs(targetPath)
+	if err != nil {
+		return refValue
+	}
+	relTarget, err := filepath.Rel(rootDir, absTarget)
+	if err != nil {
+		return filepath.ToSlash(absTarget) + fragment
+	}
+	return filepath.ToSlash(relTarget) + fragment
+}
+
+func splitRefPathAndFragment(refValue string) (string, string) {
+	pathPart, fragment, found := strings.Cut(refValue, "#")
+	if found {
+		return pathPart, "#" + fragment
+	}
+	return refValue, ""
+}
+
+func isExternalRefURI(refPath string) bool {
+	return strings.HasPrefix(refPath, "http://") ||
+		strings.HasPrefix(refPath, "https://") ||
+		strings.HasPrefix(refPath, "urn:")
+}
+
+func specDir(idx *index.SpecIndex) string {
+	if idx == nil {
+		return ""
+	}
+	specPath := idx.GetSpecAbsolutePath()
+	if specPath == "" || isExternalRefURI(specPath) {
+		return ""
+	}
+	if filepath.Ext(specPath) == "" {
+		return specPath
+	}
+	return filepath.Dir(specPath)
+}