Skip to content

Commit 7028936

Browse files
committed
feat(bundler): classify ambiguous refs by source slot during composition
Track the OpenAPI path of every $ref through the index as `Reference.SourcePath`, then use it in the composed bundler to infer a component bucket when the target node's shape is ambiguous (sparse responses, description-only objects, bare-file refs). Refs that previously fell back to inlining can now be lifted into the correct `components` slot, with contextual map keys preventing collisions when the same target is referenced from different slots.
1 parent 313d137 commit 7028936

14 files changed

Lines changed: 1684 additions & 279 deletions

‎bundler/bundler.go‎

Lines changed: 124 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)
⌂ 换网址