fix(yml): keep folded block scalars stable across encode round trips (#244)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: AshGodfrey

marshaller/coremodel.go

@@ -177,6 +177,8 @@ func (c *CoreModel) Marshal(ctx context.Context, w io.Writer) error {
 			resetNodeStylesForYAML(nodeToMarshal, cfg)
 		}
 
+		yml.StabilizeFoldedScalars(nodeToMarshal)
+
 		enc := yaml.NewEncoder(w)
 		enc.SetIndent(cfg.Indentation)
 		if err := enc.Encode(nodeToMarshal); err != nil {

openapi/foldedscalar_marshalling_test.go

@@ -0,0 +1,52 @@
+package openapi_test
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"github.com/speakeasy-api/openapi/openapi"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// The trailing table row is indented one space further than the rows above it, which
+// makes yaml.v3 emit an extra line break before it on every encode. Marshalling has to
+// stay a fixed point regardless of whether an overlay was involved.
+const foldedScalarDocument = `openapi: 3.1.0
+info:
+  title: Test
+  version: 1.0.0
+  description: >-
+    ### Widgets
+
+    | Name | Kind |
+    | ---- | ---- |
+     | acme | ` + "`petstore`" + ` |
+paths: {}
+`
+
+func TestMarshal_FoldedScalar_SurvivesRepeatedRoundTrips(t *testing.T) {
+	t.Parallel()
+
+	ctx := t.Context()
+
+	doc, validationErrs, err := openapi.Unmarshal(ctx, strings.NewReader(foldedScalarDocument))
+	require.NoError(t, err)
+	require.Empty(t, validationErrs)
+
+	want := doc.Info.GetDescription()
+	require.Contains(t, want, "| acme |")
+
+	current := foldedScalarDocument
+	for i := range 3 {
+		doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(current))
+		require.NoError(t, err)
+
+		var buf bytes.Buffer
+		require.NoError(t, openapi.Marshal(ctx, doc, &buf))
+
+		current = buf.String()
+		assert.Equal(t, want, doc.Info.GetDescription(), "value changed after %d round trips", i+1)
+	}
+}

openapi/localize.go

@@ -14,6 +14,7 @@ import (
 	"github.com/speakeasy-api/openapi/references"
 	"github.com/speakeasy-api/openapi/sequencedmap"
 	"github.com/speakeasy-api/openapi/system"
+	"github.com/speakeasy-api/openapi/yml"
 	"gopkg.in/yaml.v3"
 )
 
@@ -581,6 +582,8 @@ func rewriteInternalReferences(content []byte, originalRef string, storage *loca
 	}
 
 	// Marshal back to YAML
+	yml.StabilizeFoldedScalars(&node)
+
 	updatedContent, err := yaml.Marshal(&node)
 	if err != nil {
 		return nil, fmt.Errorf("failed to marshal updated YAML: %w", err)

openapi/testdata/localize/input/components.yaml

@@ -2,6 +2,14 @@ components:
   schemas:
     User:
       type: object
+      # The last row is deliberately indented further: that is what makes yaml.v3
+      # inject a line break into a folded scalar on encode.
+      description: >-
+        ### User
+
+        | Field | Kind |
+        | ----- | ---- |
+         | id | string |
       required:
         - id
         - name

openapi/testdata/localize/output_counter/components.yaml

@@ -2,6 +2,12 @@ components:
     schemas:
         User:
             type: object
+            # The last row is deliberately indented further: that is what makes yaml.v3
+            # inject a line break into a folded scalar on encode.
+            description: |-
+                ### User
+                | Field | Kind | | ----- | ---- |
+                 | id | string |
             required:
                 - id
                 - name

openapi/testdata/localize/output_pathbased/components.yaml

@@ -2,6 +2,12 @@ components:
     schemas:
         User:
             type: object
+            # The last row is deliberately indented further: that is what makes yaml.v3
+            # inject a line break into a folded scalar on encode.
+            description: |-
+                ### User
+                | Field | Kind | | ----- | ---- |
+                 | id | string |
             required:
                 - id
                 - name

oq/foldedscalar_format_test.go

@@ -0,0 +1,114 @@
+package oq_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/speakeasy-api/openapi/graph"
+	"github.com/speakeasy-api/openapi/openapi"
+	"github.com/speakeasy-api/openapi/oq"
+	"github.com/speakeasy-api/openapi/references"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gopkg.in/yaml.v3"
+)
+
+// The trailing table row is indented one space further than the rows above it, which
+// makes yaml.v3 emit an extra line break before it on every encode. The break lands
+// inside the scalar, so it changes the decoded value rather than just the layout.
+const foldedScalarSpec = `openapi: 3.1.0
+info:
+  title: Test
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    Widget:
+      type: object
+      description: >-
+        ### Widgets
+
+        | Name | Kind |
+        | ---- | ---- |
+         | acme | ` + "`petstore`" + ` |
+`
+
+func loadFoldedScalarGraph(t *testing.T) *graph.SchemaGraph {
+	t.Helper()
+
+	ctx := t.Context()
+
+	doc, _, err := openapi.Unmarshal(ctx, strings.NewReader(foldedScalarSpec), openapi.WithSkipValidation())
+	require.NoError(t, err)
+	require.NotNil(t, doc)
+
+	idx := openapi.BuildIndex(ctx, doc, references.ResolveOptions{
+		RootDocument:   doc,
+		TargetDocument: doc,
+		TargetLocation: "spec.yaml",
+	})
+
+	return graph.Build(ctx, idx)
+}
+
+// formattedDescription pulls the description back out of a `key:\n  <schema>` wrapper.
+func formattedDescription(t *testing.T, formatted string) string {
+	t.Helper()
+
+	var decoded map[string]struct {
+		Description string `yaml:"description"`
+	}
+	require.NoError(t, yaml.Unmarshal([]byte(formatted), &decoded))
+	require.Len(t, decoded, 1)
+
+	for _, schema := range decoded {
+		return schema.Description
+	}
+
+	return ""
+}
+
+// `openapi spec query --format yaml` marshals graph nodes with its own encoder, so it
+// needs the same stabilization as every other encode boundary.
+func TestFormatYAML_FoldedScalarKeepsItsValue(t *testing.T) {
+	t.Parallel()
+
+	var want struct {
+		Components struct {
+			Schemas map[string]struct {
+				Description string `yaml:"description"`
+			} `yaml:"schemas"`
+		} `yaml:"components"`
+	}
+	require.NoError(t, yaml.Unmarshal([]byte(foldedScalarSpec), &want))
+	wantDescription := want.Components.Schemas["Widget"].Description
+	require.Contains(t, wantDescription, "| acme |")
+
+	g := loadFoldedScalarGraph(t)
+
+	result, err := oq.Execute(`schemas | where(name == "Widget")`, g)
+	require.NoError(t, err)
+	require.Len(t, result.Rows, 1)
+
+	formatted := oq.FormatYAML(result, g)
+	require.NotEmpty(t, formatted)
+
+	assert.Equal(t, wantDescription, formattedDescription(t, formatted))
+	assert.NotContains(t, formatted, ">-", "affected folded scalars should be emitted as literal blocks")
+}
+
+// Formatting the same result twice must not drift, since FormatYAML restyles graph
+// nodes in place.
+func TestFormatYAML_FoldedScalarIsAFixedPoint(t *testing.T) {
+	t.Parallel()
+
+	g := loadFoldedScalarGraph(t)
+
+	result, err := oq.Execute(`schemas | where(name == "Widget")`, g)
+	require.NoError(t, err)
+
+	first := oq.FormatYAML(result, g)
+	for i := range 3 {
+		assert.Equal(t, first, oq.FormatYAML(result, g), "output changed on format %d", i+2)
+	}
+}

oq/format.go

@@ -8,6 +8,7 @@ import (
 	gcf "github.com/blackwell-systems/gcf-go"
 	"github.com/speakeasy-api/openapi/graph"
 	"github.com/speakeasy-api/openapi/oq/expr"
+	"github.com/speakeasy-api/openapi/yml"
 	"gopkg.in/yaml.v3"
 )
 
@@ -310,6 +311,8 @@ func FormatYAML(result *Result, g *graph.SchemaGraph) string {
 				node,
 			},
 		}
+		yml.StabilizeFoldedScalars(wrapper)
+
 		data, err := yaml.Marshal(wrapper)
 		if err != nil {
 			sb.WriteString("# error marshalling: " + err.Error() + "\n")

overlay/apply.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/speakeasy-api/jsonpath/pkg/jsonpath/config"
 	"github.com/speakeasy-api/jsonpath/pkg/jsonpath/token"
+	"github.com/speakeasy-api/openapi/yml"
 	"gopkg.in/yaml.v3"
 )
 
@@ -30,6 +31,8 @@ func (o *Overlay) ApplyTo(root *yaml.Node) error {
 		}
 	}
 
+	yml.StabilizeFoldedScalars(root)
+
 	return nil
 }
 
@@ -84,6 +87,9 @@ func (o *Overlay) ApplyToStrict(root *yaml.Node) ([]string, error) {
 	if len(multiError) > 0 {
 		return warnings, fmt.Errorf("error applying overlay (strict): %v", strings.Join(multiError, ","))
 	}
+
+	yml.StabilizeFoldedScalars(root)
+
 	return warnings, nil
 }
 

overlay/foldedscalar.go

@@ -0,0 +1,17 @@
+package overlay
+
+import (
+	"github.com/speakeasy-api/openapi/yml"
+)
+
+// stabilizeFoldedScalars restyles folded block scalars in the overlay's own update
+// payloads so that serializing the overlay round trips unchanged.
+func (o *Overlay) stabilizeFoldedScalars() {
+	if o == nil {
+		return
+	}
+
+	for i := range o.Actions {
+		yml.StabilizeFoldedScalars(&o.Actions[i].Update)
+	}
+}