Merge branch 'main' into blake/spec-3.2

Author: TristanSpeakEasy

README.md

@@ -15,7 +15,8 @@
 
 <p align="center">
   <p align="center">
-    <img  width="200px" alt="OpenAPI" src="https://github.com/user-attachments/assets/555a0899-5719-42ee-b4b1-ece8d1d812ea">
+    <img  width="200px" alt="OpenAPI" src="https://github.com/user-attachments/assets/b9fa9c14-1c6f-4d8b-910f-15e5f962bab6">
+
   </p>
   <h1 align="center"><b>OpenAPI</b></h1>
   <p align="center">A set of packages and tools for working with <a href="https://www.speakeasy.com/openapi">OpenAPI Specification documents</a>. <br /> Used directly in Speakeasy's product to power our <a href="https://www.speakeasy.com/product/sdk-generation">SDK Generation</a> and <a href="https://www.speakeasy.com/product/gram">Gram</a> products.

cmd/openapi/go.mod

@@ -6,7 +6,7 @@ require (
 	github.com/charmbracelet/bubbles v0.21.0
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/lipgloss v1.1.0
-	github.com/speakeasy-api/openapi v1.11.3-0.20251208054628-3d74e4534686
+	github.com/speakeasy-api/openapi v1.11.4-0.20251208232812-c8a601825ff5
 	github.com/spf13/cobra v1.10.1
 	github.com/stretchr/testify v1.11.1
 	gopkg.in/yaml.v3 v3.0.1

cmd/openapi/go.sum

@@ -75,8 +75,8 @@ github.com/sergi/go-diff v1.1.0 h1:we8PVUC3FE2uYfodKH/nBHMSetSfHDR6scGdBi+erh0=
 github.com/sergi/go-diff v1.1.0/go.mod h1:STckp+ISIX8hZLjrqAeVduY0gWCT9IjLuqbuNXdaHfM=
 github.com/speakeasy-api/jsonpath v0.6.2 h1:Mys71yd6u8kuowNCR0gCVPlVAHCmKtoGXYoAtcEbqXQ=
 github.com/speakeasy-api/jsonpath v0.6.2/go.mod h1:ymb2iSkyOycmzKwbEAYPJV/yi2rSmvBCLZJcyD+VVWw=
-github.com/speakeasy-api/openapi v1.11.3-0.20251208054628-3d74e4534686 h1:6i29DwrR+lBf6jxvl0UDsgMORmmLEyNFJ8nHcFtDEoY=
-github.com/speakeasy-api/openapi v1.11.3-0.20251208054628-3d74e4534686/go.mod h1:ITV3em4IFe1Hd4gX5Peq9TE7+Rfd/WIHZE/aqxNgihg=
+github.com/speakeasy-api/openapi v1.11.4-0.20251208232812-c8a601825ff5 h1:RQzb/8G4zpMhAp/qLiz1Y6FMByUW8AG+FZUedWVcrTM=
+github.com/speakeasy-api/openapi v1.11.4-0.20251208232812-c8a601825ff5/go.mod h1:ITV3em4IFe1Hd4gX5Peq9TE7+Rfd/WIHZE/aqxNgihg=
 github.com/spf13/cobra v1.10.1 h1:lJeBwCfmrnXthfAupyUTzJ/J4Nc1RsHC/mSRU2dll/s=
 github.com/spf13/cobra v1.10.1/go.mod h1:7SmJGaTHFVBY0jW4NXGluQoLvhqFQM+6XSKD+P4XaB0=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=

openapi/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <p align="center">
-    <img  width="200px" alt="OpenAPI" src="https://github.com/user-attachments/assets/555a0899-5719-42ee-b4b1-ece8d1d812ea">
+    <img  width="200px" alt="OpenAPI" src="https://github.com/user-attachments/assets/b9fa9c14-1c6f-4d8b-910f-15e5f962bab6">
   </p>
   <h1 align="center"><b>OpenAPI Parser</b></h1>
   <p align="center">An API for working with <a href="https://spec.openapis.org/oas/v3.1.1">OpenAPI documents</a> including: read, walk, create, mutate, validate, and upgrade

overlay/README.md

@@ -25,16 +25,16 @@
 
 ## Features
 
-- **OpenAPI Overlay Specification Compliance**: Full implementation of the [OpenAPI Overlay Specification](https://github.com/OAI/Overlay-Specification/blob/3f398c6/versions/1.0.0.md) (2023-10-12)
+- **OpenAPI Overlay Specification Compliance**: Full implementation of the [OpenAPI Overlay Specification](https://github.com/OAI/Overlay-Specification/blob/3f398c6/versions/1.0.0.md) (2023-10-12) and [version 1.1.0](https://github.com/OAI/Overlay-Specification/blob/e2c3cec/versions/1.1.0-dev.md)
 - **JSONPath Target Selection**: Uses JSONPath expressions to select nodes for modification
-- **Remove and Update Actions**: Support for both remove actions (pruning nodes) and update actions (merging values)
+- **Remove, Update, and Copy Actions**: Support for remove actions (pruning nodes), update actions (merging values), and copy actions (duplicating or moving nodes)
 - **Flexible Input/Output**: Works with both YAML and JSON formats
 - **Batch Operations**: Apply multiple modifications to large numbers of nodes in a single operation
 - **YAML v1.2 Support**: Uses [gopkg.in/yaml.v3](https://pkg.go.dev/gopkg.in/yaml.v3) for YAML v1.2 parsing (superset of JSON)
 
 ## About OpenAPI Overlays
 
-This specification defines a means of editing an OpenAPI Specification file by applying a list of actions. Each action is either a remove action that prunes nodes or an update that merges a value into nodes. The nodes impacted are selected by a target expression which uses JSONPath.
+This specification defines a means of editing an OpenAPI Specification file by applying a list of actions. Each action is either a remove action that prunes nodes or an update that merges a value into nodes. The nodes impacted are selected by a target expression which uses JSONPath. This implementation also supports [version 1.1.0](https://github.com/OAI/Overlay-Specification/blob/e2c3cec/versions/1.1.0-dev.md) which adds a `copy` action for duplicating or moving nodes within the document.
 
 The specification itself says very little about the input file to be modified or the output file. The presumed intention is that the input and output be an OpenAPI Specification, but that is not required.
 

overlay/apply.go

@@ -12,12 +12,17 @@ import (
 // ApplyTo will take an overlay and apply its changes to the given YAML
 // document.
 func (o *Overlay) ApplyTo(root *yaml.Node) error {
+	// Priority is: remove > update > copy
+	// Copy has no impact if remove is true or update contains a value
 	for _, action := range o.Actions {
 		var err error
-		if action.Remove {
+		switch {
+		case action.Remove:
 			err = o.applyRemoveAction(root, action, nil)
-		} else {
+		case !action.Update.IsZero():
 			err = o.applyUpdateAction(root, action, &[]string{})
+		case action.Copy != "":
+			err = o.applyCopyAction(root, action, &[]string{})
 		}
 
 		if err != nil {
@@ -32,6 +37,9 @@ func (o *Overlay) ApplyToStrict(root *yaml.Node) ([]string, error) {
 	multiError := []string{}
 	warnings := []string{}
 	hasFilterExpression := false
+
+	// Priority is: remove > update > copy
+	// Copy has no impact if remove is true or update contains a value
 	for i, action := range o.Actions {
 		tokens := token.NewTokenizer(action.Target, config.WithPropertyNameExtension()).Tokenize()
 		for _, tok := range tokens {
@@ -45,19 +53,27 @@ func (o *Overlay) ApplyToStrict(root *yaml.Node) ([]string, error) {
 		if err != nil {
 			multiError = append(multiError, err.Error())
 		}
-		if action.Remove {
+
+		// Determine action type based on priority: remove > update > copy
+		actionType := "unknown"
+		switch {
+		case action.Remove:
+			actionType = "remove"
 			err = o.applyRemoveAction(root, action, &actionWarnings)
-			if err != nil {
-				multiError = append(multiError, err.Error())
-			}
-		} else {
+		case !action.Update.IsZero():
+			actionType = "update"
 			err = o.applyUpdateAction(root, action, &actionWarnings)
-			if err != nil {
-				multiError = append(multiError, err.Error())
-			}
+		case action.Copy != "":
+			actionType = "copy"
+			err = o.applyCopyAction(root, action, &actionWarnings)
+		default:
+			err = fmt.Errorf("unknown action type: %v", action)
+		}
+		if err != nil {
+			return nil, err
 		}
 		for _, warning := range actionWarnings {
-			warnings = append(warnings, fmt.Sprintf("update action (%v / %v) target=%s: %s", i+1, len(o.Actions), action.Target, warning))
+			warnings = append(warnings, fmt.Sprintf("%s action (%v / %v) target=%s: %s", actionType, i+1, len(o.Actions), action.Target, warning))
 		}
 	}
 
@@ -87,6 +103,24 @@ func (o *Overlay) validateSelectorHasAtLeastOneTarget(root *yaml.Node, action Ac
 		return fmt.Errorf("selector %q did not match any targets", action.Target)
 	}
 
+	// For copy actions, validate the source path (only if copy will actually be applied)
+	// Copy has no impact if remove is true or update contains a value
+	if action.Copy != "" && !action.Remove && action.Update.IsZero() {
+		sourcePath, err := o.NewPath(action.Copy, nil)
+		if err != nil {
+			return err
+		}
+
+		sourceNodes := sourcePath.Query(root)
+		if len(sourceNodes) == 0 {
+			return fmt.Errorf("copy source selector %q did not match any nodes", action.Copy)
+		}
+
+		if len(sourceNodes) > 1 {
+			return fmt.Errorf("copy source selector %q matched multiple nodes (%d), expected exactly one", action.Copy, len(sourceNodes))
+		}
+	}
+
 	return nil
 }
 
@@ -189,6 +223,13 @@ func mergeNode(node *yaml.Node, merge *yaml.Node) bool {
 // node.
 func mergeMappingNode(node *yaml.Node, merge *yaml.Node) bool {
 	anyChange := false
+
+	// If the target is an empty flow-style mapping and we're merging content,
+	// convert to block style for better readability
+	if len(node.Content) == 0 && node.Style == yaml.FlowStyle && len(merge.Content) > 0 {
+		node.Style = 0 // Reset to default (block) style
+	}
+
 NextKey:
 	for i := 0; i < len(merge.Content); i += 2 {
 		mergeKey := merge.Content[i].Value
@@ -236,3 +277,63 @@ func clone(node *yaml.Node) *yaml.Node {
 	}
 	return newNode
 }
+
+// applyCopyAction applies a copy action to the document
+// This is a stub implementation for the copy feature from Overlay Specification v1.1.0
+func (o *Overlay) applyCopyAction(root *yaml.Node, action Action, warnings *[]string) error {
+	if action.Target == "" {
+		return nil
+	}
+
+	if action.Copy == "" {
+		return nil
+	}
+
+	// Parse the source path
+	sourcePath, err := o.NewPath(action.Copy, warnings)
+	if err != nil {
+		return fmt.Errorf("invalid copy source path %q: %w", action.Copy, err)
+	}
+
+	// Query the source nodes
+	sourceNodes := sourcePath.Query(root)
+	if len(sourceNodes) == 0 {
+		// Source not found - in non-strict mode this is silently ignored
+		// In strict mode, this will be caught by validateSelectorHasAtLeastOneTarget
+		if warnings != nil {
+			*warnings = append(*warnings, fmt.Sprintf("copy source %q not found", action.Copy))
+		}
+		return nil
+	}
+
+	if len(sourceNodes) > 1 {
+		return fmt.Errorf("copy source path %q matched multiple nodes (%d), expected exactly one", action.Copy, len(sourceNodes))
+	}
+
+	sourceNode := sourceNodes[0]
+
+	// Parse the target path
+	targetPath, err := o.NewPath(action.Target, warnings)
+	if err != nil {
+		return fmt.Errorf("invalid target path %q: %w", action.Target, err)
+	}
+
+	// Query the target nodes
+	targetNodes := targetPath.Query(root)
+
+	// Copy the source node to each target
+	didMakeChange := false
+	for _, targetNode := range targetNodes {
+		// Clone the source node to avoid reference issues
+		copiedNode := clone(sourceNode)
+
+		// Merge the copied node into the target
+		didMakeChange = mergeNode(targetNode, copiedNode) || didMakeChange
+	}
+
+	if !didMakeChange && warnings != nil {
+		*warnings = append(*warnings, "does nothing")
+	}
+
+	return nil
+}

overlay/apply_test.go

@@ -270,6 +270,21 @@ func cloneNode(node *yaml.Node) *yaml.Node {
 	return clone
 }
 
+func TestApplyTo_CopyVersionToHeader(t *testing.T) {
+	t.Parallel()
+
+	node, err := loader.LoadSpecification("testdata/openapi-version-header.yaml")
+	require.NoError(t, err)
+
+	o, err := loader.LoadOverlay("testdata/overlay-version-header.yaml")
+	require.NoError(t, err)
+
+	err = o.ApplyTo(node)
+	require.NoError(t, err)
+
+	NodeMatchesFile(t, node, "testdata/openapi-version-header-expected.yaml")
+}
+
 func TestApplyToOld(t *testing.T) {
 	t.Parallel()