Fix DCE to strip orphaned comments, sort discriminator mappings, remove dead code

- DCE now removes comments associated with eliminated declarations,
  preventing orphaned doc/inline comments in generated output
- Sort discriminator mapping values for deterministic codegen output
  regardless of Go map iteration order
- Delete unused structToFieldDict (V3 style functions do not use it)
- Wire client example into go:generate so it stays current
- Regenerate all output (net -3009 lines from improved DCE)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mromaszewicz-nv

codegen/internal/codegen.go

@@ -3,6 +3,7 @@ package codegen
 
 import (
 	"fmt"
+	"sort"
 	"strings"
 
 	"github.com/pb33f/libopenapi"
@@ -1041,12 +1042,16 @@ func collectUnionMembers(gen *TypeGenerator, parentDesc *SchemaDescriptor, membe
 		}
 	}
 
-	// Build reverse mapping: $ref path → []discriminator values
+	// Build reverse mapping: $ref path → []discriminator values.
+	// Sort values so output is deterministic regardless of map iteration order.
 	refToDiscValues := make(map[string][]string)
 	if parentDesc != nil && parentDesc.Discriminator != nil {
 		for discValue, refPath := range parentDesc.Discriminator.Mapping {
 			refToDiscValues[refPath] = append(refToDiscValues[refPath], discValue)
 		}
+		for ref := range refToDiscValues {
+			sort.Strings(refToDiscValues[ref])
+		}
 	}
 
 	for i, proxy := range memberProxies {

codegen/internal/dce/dce.go

@@ -94,15 +94,53 @@ func EliminateDeadCode(src string) (string, error) {
 		}
 	}
 
-	// Keep only reachable declarations.
+	// Keep only reachable declarations; collect positions of eliminated ones.
 	kept := append([]ast.Decl{}, roots...)
+	var eliminated []ast.Decl
 	for _, c := range candidates {
 		if isReachable(c.names, reachable) {
 			kept = append(kept, c.decl)
+		} else {
+			eliminated = append(eliminated, c.decl)
 		}
 	}
 	f.Decls = kept
 
+	// Remove comments associated with eliminated declarations so
+	// go/printer doesn't emit orphaned doc/inline comments.
+	if len(eliminated) > 0 {
+		// Build line ranges for eliminated declarations: from the doc
+		// comment (or decl start) through the last line of the decl.
+		removedLines := make([]lineSpan, 0, len(eliminated))
+		for _, d := range eliminated {
+			start := d.Pos()
+			switch dd := d.(type) {
+			case *ast.GenDecl:
+				if dd.Doc != nil {
+					start = dd.Doc.Pos()
+				}
+			case *ast.FuncDecl:
+				if dd.Doc != nil {
+					start = dd.Doc.Pos()
+				}
+			}
+			removedLines = append(removedLines, lineSpan{
+				startLine: fset.Position(start).Line,
+				endLine:   fset.Position(d.End()).Line,
+			})
+		}
+
+		filtered := make([]*ast.CommentGroup, 0, len(f.Comments))
+		for _, cg := range f.Comments {
+			cgStart := fset.Position(cg.Pos()).Line
+			cgEnd := fset.Position(cg.End()).Line
+			if !linesOverlap(cgStart, cgEnd, removedLines) {
+				filtered = append(filtered, cg)
+			}
+		}
+		f.Comments = filtered
+	}
+
 	var buf strings.Builder
 	if err := printer.Fprint(&buf, fset, f); err != nil {
 		return "", err
@@ -151,6 +189,17 @@ func receiverTypeName(expr ast.Expr) string {
 	return ""
 }
 
+type lineSpan struct{ startLine, endLine int }
+
+func linesOverlap(cgStart, cgEnd int, spans []lineSpan) bool {
+	for _, s := range spans {
+		if cgStart >= s.startLine && cgEnd <= s.endLine {
+			return true
+		}
+	}
+	return false
+}
+
 func collectIdents(node ast.Node, idents map[string]bool) {
 	ast.Inspect(node, func(n ast.Node) bool {
 		if id, ok := n.(*ast.Ident); ok {

codegen/internal/dce/dce_test.go

@@ -0,0 +1,186 @@
+package dce
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestEliminateDeadCode_RemovesOrphanedComments(t *testing.T) {
+	src := `package gen
+
+func usedFunc() {
+	helperFunc()
+}
+
+// --- oapi-runtime begin ---
+
+// helperFunc is used by usedFunc.
+func helperFunc() {}
+
+// unusedFunc does nothing useful.
+// It has a multi-line doc comment.
+func unusedFunc() {}
+
+// --- oapi-runtime end ---
+`
+
+	result, err := EliminateDeadCode(src)
+	require.NoError(t, err)
+
+	assert.Contains(t, result, "helperFunc")
+	assert.NotContains(t, result, "unusedFunc")
+}
+
+func TestEliminateDeadCode_NoMarkers(t *testing.T) {
+	src := `package gen
+
+func foo() {}
+`
+	result, err := EliminateDeadCode(src)
+	require.NoError(t, err)
+	assert.Equal(t, src, result)
+}
+
+func TestEliminateDeadCode_AllUsed(t *testing.T) {
+	src := `package gen
+
+func caller() {
+	a()
+	b()
+}
+
+// --- oapi-runtime begin ---
+
+// a does something.
+func a() {}
+
+// b does something else.
+func b() {}
+
+// --- oapi-runtime end ---
+`
+
+	result, err := EliminateDeadCode(src)
+	require.NoError(t, err)
+
+	assert.Contains(t, result, "func a()")
+	assert.Contains(t, result, "func b()")
+	assert.Contains(t, result, "a does something")
+	assert.Contains(t, result, "b does something else")
+}
+
+func TestEliminateDeadCode_NoneUsed(t *testing.T) {
+	src := `package gen
+
+func caller() {}
+
+// --- oapi-runtime begin ---
+
+// orphanA is unused.
+func orphanA() {}
+
+// orphanB is also unused.
+func orphanB() {}
+
+// --- oapi-runtime end ---
+`
+
+	result, err := EliminateDeadCode(src)
+	require.NoError(t, err)
+
+	assert.NotContains(t, result, "orphanA")
+	assert.NotContains(t, result, "orphanB")
+}
+
+func TestEliminateDeadCode_InlineComments(t *testing.T) {
+	src := `package gen
+
+func caller() {
+	used()
+}
+
+// --- oapi-runtime begin ---
+
+func used() {} // keep this
+
+func unused() {} // drop this
+
+// --- oapi-runtime end ---
+`
+
+	result, err := EliminateDeadCode(src)
+	require.NoError(t, err)
+
+	assert.Contains(t, result, "keep this")
+	assert.NotContains(t, result, "drop this")
+}
+
+func TestEliminateDeadCode_TypeDecl(t *testing.T) {
+	src := `package gen
+
+// UsedType is referenced.
+type UsedType struct{}
+
+// --- oapi-runtime begin ---
+
+// helperType is used by UsedType (transitively).
+type helperType = UsedType
+
+// unusedType is not referenced.
+type unusedType struct {
+	field string
+}
+
+// --- oapi-runtime end ---
+`
+
+	result, err := EliminateDeadCode(src)
+	require.NoError(t, err)
+
+	// helperType is reachable because it references UsedType which is in roots,
+	// and helperType itself may or may not be reachable depending on the algorithm.
+	// The key assertion: unusedType and its comment should be gone.
+	assert.NotContains(t, result, "unusedType")
+	assert.NotContains(t, result, "unusedType is not referenced")
+}
+
+func TestEliminateDeadCode_PreservesNonRuntimeComments(t *testing.T) {
+	src := `package gen
+
+// Package-level comment that should survive.
+
+// caller calls helper.
+func caller() {
+	helper()
+}
+
+// --- oapi-runtime begin ---
+
+// helper is needed.
+func helper() {}
+
+// unused is not needed.
+func unused() {}
+
+// --- oapi-runtime end ---
+`
+
+	result, err := EliminateDeadCode(src)
+	require.NoError(t, err)
+
+	assert.Contains(t, result, "Package-level comment")
+	assert.Contains(t, result, "caller calls helper")
+	assert.Contains(t, result, "helper is needed")
+	assert.NotContains(t, result, "unused is not needed")
+	// The word "unused" should only not appear as a function or its comment
+	lines := strings.Split(result, "\n")
+	for _, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if strings.Contains(trimmed, "unused") && !strings.Contains(trimmed, "nolint") {
+			t.Errorf("unexpected reference to 'unused' in output: %s", trimmed)
+		}
+	}
+}

codegen/internal/runtime/params/helpers.go

@@ -438,34 +438,3 @@ func base64Decode1(enc *base64.Encoding, s string) ([]byte, error) {
 	}
 	return b, nil
 }
-
-// structToFieldDict converts a struct to a map of field names to string values.
-func structToFieldDict(value any) (map[string]string, error) {
-	v := reflect.ValueOf(value)
-	t := reflect.TypeOf(value)
-	fieldDict := make(map[string]string)
-
-	for i := 0; i < t.NumField(); i++ {
-		fieldT := t.Field(i)
-		tag := fieldT.Tag.Get("json")
-		fieldName := fieldT.Name
-		if tag != "" {
-			tagParts := strings.Split(tag, ",")
-			if tagParts[0] != "" {
-				fieldName = tagParts[0]
-			}
-		}
-		f := v.Field(i)
-
-		// Skip nil optional fields
-		if f.Type().Kind() == reflect.Ptr && f.IsNil() {
-			continue
-		}
-		str, err := primitiveToString(f.Interface())
-		if err != nil {
-			return nil, fmt.Errorf("error formatting field '%s': %w", fieldName, err)
-		}
-		fieldDict[fieldName] = str
-	}
-	return fieldDict, nil
-}

codegen/internal/test/components/one_of_discriminator_multi_mapping/output/types.gen.go

@@ -64,8 +64,8 @@ func TestOneOfDiscriminatorMultiMapping(t *testing.T) {
 }
 
 // TestFromConfigHTTPSetsDiscriminator verifies that FromConfigHTTP sets the
-// discriminator value. Note: V3 codegen forces the first mapping value
-// ("apache_server") regardless of what the caller sets.
+// discriminator value. V3 codegen forces the lexicographically first mapping
+// value ("another_server") regardless of what the caller sets.
 func TestFromConfigHTTPSetsDiscriminator(t *testing.T) {
 	var saveReq ConfigSaveReq
 	err := saveReq.FromConfigHTTP(ConfigHTTP{
@@ -77,9 +77,9 @@ func TestFromConfigHTTPSetsDiscriminator(t *testing.T) {
 
 	disc, err := saveReq.Discriminator()
 	require.NoError(t, err)
-	// V3 codegen forces "apache_server" — this documents the current behavior.
+	// V3 codegen forces "another_server" (sorted first among the HTTP mappings).
 	// If/when this is fixed to preserve the caller's value, change this assertion.
-	assert.Equal(t, "apache_server", disc)
+	assert.Equal(t, "another_server", disc)
 }
 
 func TestApplyDefaults(t *testing.T) {