feat(merge): normalize operation-level tags and add post-merge validation (#1882)

Author: TristanSpeakEasy

pkg/merge/merge.go

@@ -19,6 +19,7 @@ import (
 	"github.com/speakeasy-api/openapi/openapi"
 	"github.com/speakeasy-api/openapi/overlay"
 	"github.com/speakeasy-api/openapi/sequencedmap"
+	openapiValidation "github.com/speakeasy-api/openapi/validation"
 	"github.com/speakeasy-api/openapi/yml"
 	"github.com/speakeasy-api/speakeasy/internal/log"
 	"github.com/speakeasy-api/speakeasy/internal/validation"
@@ -78,6 +79,11 @@ func MergeOpenAPIDocumentsWithNamespaces(ctx context.Context, inputs []MergeInpu
 		return err
 	}
 
+	// Validate the merged document by re-parsing without skipping validation
+	if err := validateMergedOutput(ctx, mergedSchema); err != nil {
+		return err
+	}
+
 	return nil
 }
 
@@ -113,6 +119,31 @@ func validate(ctx context.Context, schemaPath string, schema []byte, defaultRule
 	return nil
 }
 
+// validateMergedOutput re-parses the merged schema with validation enabled
+// and returns an error if any validation errors (not warnings) are found.
+func validateMergedOutput(ctx context.Context, schema []byte) error {
+	_, validationErrs, err := openapi.Unmarshal(ctx, bytes.NewReader(schema))
+	if err != nil {
+		return fmt.Errorf("merged document failed to parse: %w", err)
+	}
+
+	var errsOut []error
+	for _, validationErr := range validationErrs {
+		var ve *openapiValidation.Error
+		if errors.As(validationErr, &ve) && ve.Severity == openapiValidation.SeverityWarning {
+			log.From(ctx).Warn(fmt.Sprintf("merged document validation: %s", validationErr.Error()))
+		} else {
+			errsOut = append(errsOut, validationErr)
+		}
+	}
+
+	if len(errsOut) > 0 {
+		return multierror.Append(fmt.Errorf("merged document is invalid"), errsOut...)
+	}
+
+	return nil
+}
+
 func merge(ctx context.Context, inSchemas [][]byte, namespaces []string, yamlOut bool) ([]byte, error) {
 	// Validate namespace consistency
 	if err := validateNamespaceSlice(namespaces, len(inSchemas)); err != nil {
@@ -186,6 +217,10 @@ func merge(ctx context.Context, inSchemas [][]byte, namespaces []string, yamlOut
 	// (ignoring description/summary differences)
 	deduplicateEquivalentComponents(mergedDoc)
 
+	// Post-merge: normalize operation-level tag references to match
+	// the chosen document-level tag names (case-insensitive)
+	normalizeOperationTags(mergedDoc)
+
 	buf := bytes.NewBuffer(nil)
 	var err error
 
@@ -243,6 +278,7 @@ func MergeDocuments(mergedDoc, doc *openapi.OpenAPI) (*openapi.OpenAPI, []error)
 	initMergeState(state, mergedDoc, "")
 	merged, errs := mergeDocumentsWithState(state, mergedDoc, doc, "", 2)
 	deduplicateOperationIds(state, merged)
+	normalizeOperationTags(merged)
 	return merged, errs
 }
 
@@ -285,10 +321,11 @@ func mergeDocumentsWithState(state *mergeState, mergedDoc, doc *openapi.OpenAPI,
 	}
 
 	// Merge Tags (case-insensitive with content-aware disambiguation)
-	tagRenames := mergeTagsWithState(state, mergedDoc, doc, docNamespace, docCounter)
-	// Update operation-level tag references in both docs
-	updateOperationTagRefs(mergedDoc, tagRenames)
-	updateOperationTagRefs(doc, tagRenames)
+	tagResult := mergeTagsWithState(state, mergedDoc, doc, docNamespace, docCounter)
+	// Update operation-level tag references in each doc using its own rename map
+	// (case-insensitive matching, per-document maps avoid ambiguity)
+	updateOperationTagRefs(mergedDoc, tagResult.existingRenames)
+	updateOperationTagRefs(doc, tagResult.incomingRenames)
 
 	// Merge Paths (with method-level conflict detection and fragment disambiguation)
 	pathErrs := mergePathsWithState(state, mergedDoc, doc, docNamespace, docCounter)

pkg/merge/merge_tags.go

@@ -6,13 +6,26 @@ import (
 	"github.com/speakeasy-api/openapi/openapi"
 )
 
+// tagRenameResult holds separate rename maps for the existing (merged) document
+// and the incoming document. Keeping them separate allows case-insensitive
+// operation-level tag renaming without ambiguity — each map has at most one
+// entry per case-insensitive tag name.
+type tagRenameResult struct {
+	existingRenames map[string]string // renames for operations already in mergedDoc
+	incomingRenames map[string]string // renames for operations in the incoming doc
+}
+
 // mergeTagsWithState performs case-insensitive tag merging with content-aware disambiguation.
-// It returns a map of old tag name → new tag name for updating operation-level tag references.
-func mergeTagsWithState(state *mergeState, mergedDoc, doc *openapi.OpenAPI, docNamespace string, docCounter int) map[string]string {
-	tagRenames := make(map[string]string)
+// It returns separate rename maps for updating operation-level tag references in the
+// existing merged document and the incoming document.
+func mergeTagsWithState(state *mergeState, mergedDoc, doc *openapi.OpenAPI, docNamespace string, docCounter int) tagRenameResult {
+	result := tagRenameResult{
+		existingRenames: make(map[string]string),
+		incomingRenames: make(map[string]string),
+	}
 
 	if doc.Tags == nil {
-		return tagRenames
+		return result
 	}
 
 	if mergedDoc.Tags == nil {
@@ -53,7 +66,7 @@ func mergeTagsWithState(state *mergeState, mergedDoc, doc *openapi.OpenAPI, docN
 			mergedDoc.Tags[matchIdx] = newTag
 			// Record rename if the name changed (e.g. casing difference)
 			if oldName != newTag.Name {
-				tagRenames[oldName] = newTag.Name
+				result.existingRenames[oldName] = newTag.Name
 			}
 			// Update the tracker entry
 			state.tagTracker[key][matchEntry] = tagEntry{
@@ -70,7 +83,7 @@ func mergeTagsWithState(state *mergeState, mergedDoc, doc *openapi.OpenAPI, docN
 				oldName := existingTag.Name
 				newName := oldName + "_" + existingSuffix
 				existingTag.Name = newName
-				tagRenames[oldName] = newName
+				result.existingRenames[oldName] = newName
 				state.tagTracker[key][matchEntry] = tagEntry{
 					currentName: newName,
 					namespace:   entries[matchEntry].namespace,
@@ -82,7 +95,7 @@ func mergeTagsWithState(state *mergeState, mergedDoc, doc *openapi.OpenAPI, docN
 			newSuffix := disambiguatingSuffix(docNamespace, docCounter)
 			oldNewTagName := newTag.Name
 			newTag.Name = oldNewTagName + "_" + newSuffix
-			tagRenames[oldNewTagName] = newTag.Name
+			result.incomingRenames[oldNewTagName] = newTag.Name
 
 			mergedDoc.Tags = append(mergedDoc.Tags, newTag)
 			state.tagTracker[key] = append(state.tagTracker[key], tagEntry{
@@ -93,7 +106,7 @@ func mergeTagsWithState(state *mergeState, mergedDoc, doc *openapi.OpenAPI, docN
 		}
 	}
 
-	return tagRenames
+	return result
 }
 
 // findTagInMergedDoc locates the tag in mergedDoc.Tags that corresponds to one
@@ -174,19 +187,25 @@ func ptrStringEqual(a, b *string) bool {
 }
 
 // updateOperationTagRefs walks all operations in the document and updates
-// tag name references according to the renames map.
+// tag name references according to the renames map (case-insensitive).
 func updateOperationTagRefs(doc *openapi.OpenAPI, renames map[string]string) {
 	if len(renames) == 0 {
 		return
 	}
 
+	// Build case-insensitive lookup once and reuse for all operations.
+	ciRenames := make(map[string]string, len(renames))
+	for oldName, newName := range renames {
+		ciRenames[strings.ToLower(oldName)] = newName
+	}
+
 	if doc.Paths != nil {
 		for _, pathItem := range doc.Paths.All() {
 			if pathItem == nil || pathItem.Object == nil {
 				continue
 			}
 			for _, op := range pathItem.Object.All() {
-				renameOpTags(op, renames)
+				renameOpTags(op, ciRenames)
 			}
 		}
 	}
@@ -197,20 +216,73 @@ func updateOperationTagRefs(doc *openapi.OpenAPI, renames map[string]string) {
 				continue
 			}
 			for _, op := range pathItem.Object.All() {
-				renameOpTags(op, renames)
+				renameOpTags(op, ciRenames)
 			}
 		}
 	}
 }
 
-// renameOpTags updates the Tags slice of a single operation.
-func renameOpTags(op *openapi.Operation, renames map[string]string) {
+// renameOpTags updates the Tags slice of a single operation using a
+// pre-built case-insensitive rename map (lowercase keys → new names).
+func renameOpTags(op *openapi.Operation, ciRenames map[string]string) {
 	if op == nil {
 		return
 	}
+
 	for i, tag := range op.Tags {
-		if newName, ok := renames[tag]; ok {
+		if newName, ok := ciRenames[strings.ToLower(tag)]; ok {
 			op.Tags[i] = newName
 		}
 	}
 }
+
+// normalizeOperationTags is a post-merge pass that ensures all operation-level
+// tag references use the same casing as the document-level tag definitions.
+// This catches cases where operations reference tags with a casing that wasn't
+// directly involved in a rename (e.g. "PETS" when the rename only covered
+// "Pets" → "pets"), or where tags are used only in operations without any
+// document-level definition.
+func normalizeOperationTags(doc *openapi.OpenAPI) {
+	// Build canonical name map from document-level tags.
+	canonical := make(map[string]string, len(doc.Tags))
+	for _, tag := range doc.Tags {
+		canonical[strings.ToLower(tag.Name)] = tag.Name
+	}
+
+	normalize := func(op *openapi.Operation) {
+		if op == nil {
+			return
+		}
+		for i, tag := range op.Tags {
+			key := strings.ToLower(tag)
+			if chosen, ok := canonical[key]; ok {
+				op.Tags[i] = chosen
+			} else {
+				// Tag not defined at document level — use first occurrence as canonical.
+				canonical[key] = tag
+			}
+		}
+	}
+
+	if doc.Paths != nil {
+		for _, pathItem := range doc.Paths.All() {
+			if pathItem == nil || pathItem.Object == nil {
+				continue
+			}
+			for _, op := range pathItem.Object.All() {
+				normalize(op)
+			}
+		}
+	}
+
+	if doc.Webhooks != nil {
+		for _, pathItem := range doc.Webhooks.All() {
+			if pathItem == nil || pathItem.Object == nil {
+				continue
+			}
+			for _, op := range pathItem.Object.All() {
+				normalize(op)
+			}
+		}
+	}
+}