@@ -508,7 +508,7 @@ func composeWithOrigins(model *v3.Document, compositionConfig *BundleComposition
508508 return nil , err
509509 }
510510
511- // Step 1: Collect discriminator mappings WITH context (early)
511+ // Collect discriminator mappings before ref processing so mapping-only targets can be composed.
512512 discriminatorMappings := collectDiscriminatorMappingNodesWithContext (rolodex )
513513
514514 cf := & handleIndexConfig {
@@ -523,10 +523,9 @@ func composeWithOrigins(model *v3.Document, compositionConfig *BundleComposition
523523 origins : make (ComponentOriginMap ),
524524 }
525525
526- // Step 2: Enqueue mapping targets for composition (AFTER cf is created, BEFORE handleIndex)
527- // Pass rootIndex so we can skip root-local #/ refs
526+ // Enqueue mapping targets after cf exists; root-local #/ refs stay in place.
528527 enqueueDiscriminatorMappingTargets (discriminatorMappings , cf , rootIndex )
529- // Refresh indexes in case mapping resolution loaded new ones
528+ // Refresh indexes in case mapping resolution loaded new ones.
530529 cf .indexes = rolodex .GetIndexes ()
531530 if err := validateDiscriminatorMappings (rolodex ); err != nil {
532531 return nil , err
@@ -545,7 +544,10 @@ func composeWithOrigins(model *v3.Document, compositionConfig *BundleComposition
545544 for _ , ref := range cf .refMap .FromOldest () {
546545 err := processReference (model , ref , cf )
547546 errs = append (errs , err )
548- processedNodes .Set (ref .ref .FullDefinition , ref )
547+ processedNodes .Set (ref .mapKey , ref )
548+ if ref .ref != nil && ref .mapKey != ref .ref .FullDefinition {
549+ processedNodes .Set (ref .ref .FullDefinition , ref )
550+ }
549551 }
550552
551553 slices .SortFunc (indexes , func (i , j * index.SpecIndex ) int {
@@ -555,56 +557,20 @@ func composeWithOrigins(model *v3.Document, compositionConfig *BundleComposition
555557 return 0
556558 })
557559
558- // Step 3: Remap indexed refs
560+ // Remap indexed refs.
559561 remapIndex (rootIndex , processedNodes )
560562
561563 for _ , idx := range indexes {
562564 remapIndex (idx , processedNodes )
563565 }
564566
565- // Step 4: Update discriminator mappings (uses renameRef for collision handling)
567+ // Update discriminator mapping values after component names are final.
566568 updateDiscriminatorMappingsComposed (discriminatorMappings , processedNodes , rolodex )
567569
568- // Step 5: Inline handling with guard for synthetic discriminator refs
569- // anything that could not be recomposed and needs inlining
570- inlinedPaths := make (map [string ]* yaml.Node )
571- for _ , pr := range cf .inlineRequired {
572- // Skip synthetic refs from discriminator mappings - their seqRef.Node is a
573- // scalar value node, not a $ref node with Content array
574- if pr .fromDiscriminator {
575- continue
576- }
577-
578- if pr .refPointer != "" {
579-
580- // if the ref is a pointer to an external pointer, then we need to stitch it.
581- uri := strings .Split (pr .refPointer , "#/" )
582- if len (uri ) == 2 {
583- if uri [0 ] != "" {
584- if ! filepath .IsAbs (uri [0 ]) && ! strings .HasPrefix (uri [0 ], "http" ) {
585- // if the uri is not absolute, then we need to make it absolute.
586- uri [0 ] = utils .CheckPathOverlap (filepath .Dir (pr .idx .GetSpecAbsolutePath ()), uri [0 ], string (os .PathSeparator ))
587- }
588- pointerRef := pr .idx .FindComponent (context .Background (), strings .Join (uri , "#/" ))
589- pr .seqRef .Node .Content = pointerRef .Node .Content
590- // Track this inlined content for reuse
591- if pr .ref != nil {
592- inlinedPaths [pr .ref .FullDefinition ] = pointerRef .Node
593- }
594- continue
595- }
596- }
597- }
598- pr .seqRef .Node .Content = pr .ref .Node .Content
599- // Track this inlined content for reuse
600- if pr .ref != nil {
601- inlinedPaths [pr .ref .FullDefinition ] = pr .ref .Node
602- }
603- }
570+ // Inline anything that could not be recomposed.
571+ inlinedPaths := inlineRequiredRefs (cf .inlineRequired , rolodex )
604572
605- // Step 6: Tree walk for any remaining unindexed refs
606- // Re-fetch indexes since new ones may have been loaded during composition
607- // (e.g., discriminator mapping targets that weren't indexed initially)
573+ // Rewrite any remaining unindexed refs after mapping resolution loads new indexes.
608574 allLoadedIndexes := rolodex .GetIndexes ()
609575 rewriteAllRefs (rootIndex , processedNodes , rolodex )
610576 for _ , idx := range allLoadedIndexes {
@@ -672,7 +638,7 @@ func compose(model *v3.Document, compositionConfig *BundleCompositionConfig) ([]
672638 return nil , err
673639 }
674640
675- // Collect discriminator mappings WITH context (early)
641+ // Collect discriminator mappings before ref processing so mapping-only targets can be composed.
676642 discriminatorMappings := collectDiscriminatorMappingNodesWithContext (rolodex )
677643
678644 cf := & handleIndexConfig {
@@ -687,10 +653,9 @@ func compose(model *v3.Document, compositionConfig *BundleCompositionConfig) ([]
687653 origins : make (ComponentOriginMap ),
688654 }
689655
690- // Enqueue mapping targets for composition (AFTER cf is created, BEFORE handleIndex)
691- // Pass rootIndex so we can skip root-local #/ refs
656+ // Enqueue mapping targets after cf exists; root-local #/ refs stay in place.
692657 enqueueDiscriminatorMappingTargets (discriminatorMappings , cf , rootIndex )
693- // Refresh indexes in case mapping resolution loaded new ones
658+ // Refresh indexes in case mapping resolution loaded new ones.
694659 cf .indexes = rolodex .GetIndexes ()
695660 if err := validateDiscriminatorMappings (rolodex ); err != nil {
696661 return nil , err
@@ -709,7 +674,10 @@ func compose(model *v3.Document, compositionConfig *BundleCompositionConfig) ([]
709674 for _ , ref := range cf .refMap .FromOldest () {
710675 err := processReference (model , ref , cf )
711676 errs = append (errs , err )
712- processedNodes .Set (ref .ref .FullDefinition , ref )
677+ processedNodes .Set (ref .mapKey , ref )
678+ if ref .ref != nil && ref .mapKey != ref .ref .FullDefinition {
679+ processedNodes .Set (ref .ref .FullDefinition , ref )
680+ }
713681 }
714682
715683 slices .SortFunc (indexes , func (i , j * index.SpecIndex ) int {
@@ -719,56 +687,20 @@ func compose(model *v3.Document, compositionConfig *BundleCompositionConfig) ([]
719687 return 0
720688 })
721689
722- // Remap indexed refs
690+ // Remap indexed refs.
723691 remapIndex (rootIndex , processedNodes )
724692
725693 for _ , idx := range indexes {
726694 remapIndex (idx , processedNodes )
727695 }
728696
729- // Update discriminator mappings (uses renameRef for collision handling)
697+ // Update discriminator mapping values after component names are final.
730698 updateDiscriminatorMappingsComposed (discriminatorMappings , processedNodes , rolodex )
731699
732- // Inline handling with guard for synthetic discriminator refs
733- // anything that could not be recomposed and needs inlining
734- inlinedPaths := make (map [string ]* yaml.Node )
735- for _ , pr := range cf .inlineRequired {
736- // Skip synthetic refs from discriminator mappings - their seqRef.Node is a
737- // scalar value node, not a $ref node with a Content array
738- if pr .fromDiscriminator {
739- continue
740- }
741-
742- if pr .refPointer != "" {
700+ // Inline anything that could not be recomposed.
701+ inlinedPaths := inlineRequiredRefs (cf .inlineRequired , rolodex )
743702
744- // if the ref is a pointer to an external pointer, then we need to stitch it.
745- uri := strings .Split (pr .refPointer , "#/" )
746- if len (uri ) == 2 {
747- if uri [0 ] != "" {
748- if ! filepath .IsAbs (uri [0 ]) && ! strings .HasPrefix (uri [0 ], "http" ) {
749- // if the uri is not absolute, then we need to make it absolute.
750- uri [0 ] = utils .CheckPathOverlap (filepath .Dir (pr .idx .GetSpecAbsolutePath ()), uri [0 ], string (os .PathSeparator ))
751- }
752- pointerRef := pr .idx .FindComponent (context .Background (), strings .Join (uri , "#/" ))
753- pr .seqRef .Node .Content = pointerRef .Node .Content
754- // Track this inlined content for reuse
755- if pr .ref != nil {
756- inlinedPaths [pr .ref .FullDefinition ] = pointerRef .Node
757- }
758- continue
759- }
760- }
761- }
762- pr .seqRef .Node .Content = pr .ref .Node .Content
763- // Track this inlined content for reuse
764- if pr .ref != nil {
765- inlinedPaths [pr .ref .FullDefinition ] = pr .ref .Node
766- }
767- }
768-
769- // Tree walk for any remaining unindexed refs
770- // Re-fetch indexes since new ones may have been loaded during composition
771- // (e.g., discriminator mapping targets that weren't indexed initially)
703+ // Rewrite any remaining unindexed refs after mapping resolution loads new indexes.
772704 allLoadedIndexes := rolodex .GetIndexes ()
773705 rewriteAllRefs (rootIndex , processedNodes , rolodex )
774706 for _ , idx := range allLoadedIndexes {
@@ -802,6 +734,103 @@ func compose(model *v3.Document, compositionConfig *BundleCompositionConfig) ([]
802734 return b , errors .Join (errs ... )
803735}
804736
737+ // inlineRequiredRefs inlines refs that cannot be represented as root components.
738+ func inlineRequiredRefs (required []* processRef , rolodex * index.Rolodex ) map [string ]* yaml.Node {
739+ inlinedPaths := make (map [string ]* yaml.Node )
740+ if len (required ) == 0 {
741+ return inlinedPaths
742+ }
743+
744+ refsByDefinition := sequencedRefsByFullDefinition (rolodex )
745+ for _ , pr := range required {
746+ inlinedNode := inlineProcessRef (pr )
747+ if inlinedNode == nil {
748+ continue
749+ }
750+ if pr .ref != nil {
751+ inlinedPaths [pr .ref .FullDefinition ] = inlinedNode
752+ }
753+ inlineMatchingRefs (pr , inlinedNode , refsByDefinition )
754+ }
755+ return inlinedPaths
756+ }
757+
758+ // sequencedRefsByFullDefinition buckets refs once for inlineRequiredRefs.
759+ func sequencedRefsByFullDefinition (rolodex * index.Rolodex ) map [string ][]* index.Reference {
760+ refsByDefinition := make (map [string ][]* index.Reference )
761+ if rolodex == nil {
762+ return refsByDefinition
763+ }
764+
765+ indexes := append ([]* index.SpecIndex {}, rolodex .GetIndexes ()... )
766+ indexes = append (indexes , rolodex .GetRootIndex ())
767+ seen := make (map [* index.SpecIndex ]struct {}, len (indexes ))
768+
769+ for _ , idx := range indexes {
770+ if idx == nil {
771+ continue
772+ }
773+ if _ , ok := seen [idx ]; ok {
774+ continue
775+ }
776+ seen [idx ] = struct {}{}
777+
778+ for _ , seqRef := range idx .GetRawReferencesSequenced () {
779+ if seqRef == nil || seqRef .IsExtensionRef || seqRef .Node == nil || seqRef .FullDefinition == "" {
780+ continue
781+ }
782+ refsByDefinition [seqRef .FullDefinition ] = append (refsByDefinition [seqRef .FullDefinition ], seqRef )
783+ }
784+ }
785+ return refsByDefinition
786+ }
787+
788+ // inlineProcessRef replaces the source ref node with its resolved target node.
789+ func inlineProcessRef (pr * processRef ) * yaml.Node {
790+ if pr == nil || pr .fromDiscriminator || pr .seqRef == nil || pr .seqRef .Node == nil || pr .ref == nil {
791+ return nil
792+ }
793+
794+ if pr .refPointer != "" {
795+ uri := strings .Split (pr .refPointer , "#/" )
796+ if len (uri ) == 2 && uri [0 ] != "" {
797+ if ! filepath .IsAbs (uri [0 ]) && ! strings .HasPrefix (uri [0 ], "http" ) {
798+ uri [0 ] = utils .CheckPathOverlap (filepath .Dir (pr .idx .GetSpecAbsolutePath ()), uri [0 ], string (os .PathSeparator ))
799+ }
800+ pointerRef := pr .idx .FindComponent (context .Background (), strings .Join (uri , "#/" ))
801+ if pointerRef == nil || pointerRef .Node == nil {
802+ return nil
803+ }
804+ pr .seqRef .Node .Content = pointerRef .Node .Content
805+ return pointerRef .Node
806+ }
807+ }
808+
809+ if pr .ref .Node == nil {
810+ return nil
811+ }
812+ pr .seqRef .Node .Content = pr .ref .Node .Content
813+ return pr .ref .Node
814+ }
815+
816+ // inlineMatchingRefs applies the same inline replacement to repeated matching refs.
817+ func inlineMatchingRefs (pr * processRef , inlinedNode * yaml.Node , refsByDefinition map [string ][]* index.Reference ) {
818+ if pr == nil || pr .ref == nil || inlinedNode == nil || refsByDefinition == nil {
819+ return
820+ }
821+ key := pr .mapKey
822+ if key == "" {
823+ key = processRefMapKey (pr .ref , pr .seqRef )
824+ }
825+
826+ for _ , seqRef := range refsByDefinition [pr .ref .FullDefinition ] {
827+ if contextualProcessRefKey (pr .ref .FullDefinition , seqRef ) != key {
828+ continue
829+ }
830+ seqRef .Node .Content = inlinedNode .Content
831+ }
832+ }
833+
805834// resolveBundleInlineConfig resolves the inlineLocalRefs setting from the fallback chain:
806835// 1. BundleInlineConfig.InlineLocalRefs (explicit per-call)
807836// 2. DocumentConfiguration.BundleInlineRefs (document-wide default)
@@ -1341,9 +1370,8 @@ func updateDiscriminatorMappingsComposed(mappings []*discriminatorMappingWithCon
13411370 continue
13421371 }
13431372
1344- // Use the cached canonicalKey and targetIdx from enqueue time.
1345- // At enqueue time, we captured ref.FullDefinition BEFORE any mutation.
1346- // Using SearchIndexForReference again here would return a potentially mutated
1373+ // Use the canonicalKey and targetIdx captured before bundling mutates refs.
1374+ // Calling SearchIndexForReference again here could return a mutated
13471375 // ref.FullDefinition that won't match processedNodes keys.
13481376 canonicalKey := mapping .canonicalKey
13491377 targetIdx := mapping .targetIdx
@@ -1359,7 +1387,7 @@ func updateDiscriminatorMappingsComposed(mappings []*discriminatorMappingWithCon
13591387 continue
13601388 }
13611389 canonicalKey = ref .FullDefinition
1362- targetIdx = refIdx // Use the resolved index, NOT mapping.sourceIdx
1390+ targetIdx = refIdx // Use the resolved index, not mapping.sourceIdx.
13631391 }
13641392
13651393 // Gate rewrites on processedNodes presence.
0 commit comments