perf: consume pre-rendered usage snippets to skip duplicate AST resolution (#1870)

- Adds `GenerateOverlayFromRawSnippets` to build code sample overlays
from pre-rendered snippet output, skipping a redundant
`usagegen.Generate()` call
- Threads `RenderedUsageSnippets` from `sdkgen.Generate()` through
`GenerationAccess` to `runCodeSamples`
- Falls back to existing `GenerateOverlay` path when pre-rendered
snippets are unavailable

Author: bradcypert

go.mod

@@ -38,7 +38,7 @@ require (
 	github.com/speakeasy-api/huh v1.1.2
 	github.com/speakeasy-api/jq v0.1.1-0.20251107233444-84d7e49e84a4
 	github.com/speakeasy-api/openapi v1.16.1
-	github.com/speakeasy-api/openapi-generation/v2 v2.814.0
+	github.com/speakeasy-api/openapi-generation/v2 v2.816.0
 	github.com/speakeasy-api/sdk-gen-config v1.49.0
 	github.com/speakeasy-api/speakeasy-agent-mode-content v0.2.0
 	github.com/speakeasy-api/speakeasy-client-sdk-go/v3 v3.26.7

go.sum

@@ -538,8 +538,8 @@ github.com/speakeasy-api/libopenapi v0.21.9-fixhiddencomps-fixed h1:PL/kpBY5vkBm
 github.com/speakeasy-api/libopenapi v0.21.9-fixhiddencomps-fixed/go.mod h1:Gc8oQkjr2InxwumK0zOBtKN9gIlv9L2VmSVIUk2YxcU=
 github.com/speakeasy-api/openapi v1.16.1 h1:eUFWR7wqqT2GNXqOPMTbbW1zJE28qT1m1dWmNMEhviI=
 github.com/speakeasy-api/openapi v1.16.1/go.mod h1:aiVj+JnirrwZDtKegt0hQrj/ixl3v17EkN2YGnTuSro=
-github.com/speakeasy-api/openapi-generation/v2 v2.814.0 h1:XhtCx72DW1JJrIoNfYCbN6vVoGlp8Lh2FwbL92QCDyM=
-github.com/speakeasy-api/openapi-generation/v2 v2.814.0/go.mod h1:cY7IhImqvA0lY8iCzATzqZTFERVpfsmnzPsuxqCrzHQ=
+github.com/speakeasy-api/openapi-generation/v2 v2.816.0 h1:0W23h9FGGh3X4DoqKDJvZqk9GVH/GghkUL+6EmeQ4tg=
+github.com/speakeasy-api/openapi-generation/v2 v2.816.0/go.mod h1:cY7IhImqvA0lY8iCzATzqZTFERVpfsmnzPsuxqCrzHQ=
 github.com/speakeasy-api/openapi/openapi/linter/customrules v0.0.0-20260206023826-2483fb8e98b4 h1:gV+lYeVNNJG9X3Sl9Su3cRh1iF/oNqzvb5Ijq2QR8jY=
 github.com/speakeasy-api/openapi/openapi/linter/customrules v0.0.0-20260206023826-2483fb8e98b4/go.mod h1:1zQpVio7X6QJDtyNdUguCgZ+IC7CzKhhjvNgJdvGVF0=
 github.com/speakeasy-api/sdk-gen-config v1.49.0 h1:zwOBNfQtip564bOcWEUSwwJxSGQGkWA15R8xIxFTgHs=

internal/run/target.go

@@ -8,6 +8,7 @@ import (
 	"strings"
 
 	"github.com/hashicorp/go-version"
+	"github.com/speakeasy-api/openapi-generation/v2/pkg/generate"
 	sdkGenConfig "github.com/speakeasy-api/sdk-gen-config"
 	"github.com/speakeasy-api/sdk-gen-config/workflow"
 	"github.com/speakeasy-api/speakeasy-core/auth"
@@ -240,6 +241,7 @@ func (w *Workflow) runTarget(ctx context.Context, target string) (*SourceResult,
 			StreamableGeneration:  w.StreamableGeneration,
 			ReleaseNotes:          changelogContent,
 			WorkflowStep:          genStep,
+			RenderUsageSnippets:   t.CodeSamplesEnabled(),
 		},
 	)
 	if err != nil {
@@ -253,7 +255,7 @@ func (w *Workflow) runTarget(ctx context.Context, target string) (*SourceResult,
 
 	if t.CodeSamplesEnabled() {
 		codeSamplesStep := rootStep.NewSubstep("Generating Code Samples")
-		namespaceName, digest, err := w.runCodeSamples(ctx, codeSamplesStep, *t.CodeSamples, t.Target, sourcePath, t.Output)
+		namespaceName, digest, err := w.runCodeSamples(ctx, codeSamplesStep, *t.CodeSamples, t.Target, sourcePath, t.Output, generationAccess.RenderedUsageSnippets)
 		if err != nil {
 			// Block by default. Only warn if explicitly set to non-blocking
 			if t.CodeSamples.Blocking == nil || *t.CodeSamples.Blocking {
@@ -298,8 +300,10 @@ func (w *Workflow) runTarget(ctx context.Context, target string) (*SourceResult,
 	return sourceRes, &targetResult, nil
 }
 
-// Returns codeSamples namespace name and digest
-func (w *Workflow) runCodeSamples(ctx context.Context, codeSamplesStep *workflowTracking.WorkflowStep, codeSamples workflow.CodeSamples, target, sourcePath string, targetOutputPath *string) (string, string, error) {
+// Returns codeSamples namespace name and digest.
+// If preRendered is non-nil with content, it is used to build the overlay directly,
+// avoiding a second AST resolution pass.
+func (w *Workflow) runCodeSamples(ctx context.Context, codeSamplesStep *workflowTracking.WorkflowStep, codeSamples workflow.CodeSamples, target, sourcePath string, targetOutputPath *string, preRendered *generate.RenderedUsageSnippets) (string, string, error) {
 	configPath := "."
 	writeFileLocation := codeSamples.Output
 
@@ -312,7 +316,14 @@ func (w *Workflow) runCodeSamples(ctx context.Context, codeSamplesStep *workflow
 		}
 	}
 
-	overlayString, err := codesamples.GenerateOverlay(ctx, sourcePath, "", "", configPath, writeFileLocation, []string{target}, true, false, codeSamples)
+	var overlayString string
+	var err error
+
+	if preRendered != nil && preRendered.RawOutput != "" {
+		overlayString, err = codesamples.GenerateOverlayFromRawSnippets(ctx, preRendered.RawOutput, target, sourcePath, writeFileLocation, true, codeSamples)
+	} else {
+		overlayString, err = codesamples.GenerateOverlay(ctx, sourcePath, "", "", configPath, writeFileLocation, []string{target}, true, false, codeSamples)
+	}
 	if err != nil {
 		return "", "", err
 	}

internal/sdkgen/sdkgen.go

@@ -38,9 +38,10 @@ import (
 var PromptForCustomCode = prompts.PromptForCustomCode
 
 type GenerationAccess struct {
-	AccessAllowed bool
-	Message       string
-	Level         *shared.Level
+	AccessAllowed         bool
+	Message               string
+	Level                 *shared.Level
+	RenderedUsageSnippets *generate.RenderedUsageSnippets // pre-rendered snippets from SDK generation (nil if not requested)
 }
 
 type CancellableGeneration struct {
@@ -85,6 +86,10 @@ type GenerateOptions struct {
 	// WorkflowStep enables running prompts through the workflow visualizer.
 	// If nil, prompts will run directly without visualizer integration.
 	WorkflowStep *workflowTracking.WorkflowStep
+
+	// RenderUsageSnippets opts in to pre-rendering standalone usage snippets
+	// during SDK generation, reusing the already-resolved AST.
+	RenderUsageSnippets bool
 }
 
 func Generate(ctx context.Context, opts GenerateOptions) (*GenerationAccess, error) {
@@ -178,6 +183,9 @@ func Generate(ctx context.Context, opts GenerateOptions) (*GenerationAccess, err
 	if opts.SkipVersioning {
 		generatorOpts = append(generatorOpts, generate.WithSkipVersioning(opts.SkipVersioning))
 	}
+	if opts.RenderUsageSnippets {
+		generatorOpts = append(generatorOpts, generate.WithRenderUsageSnippets())
+	}
 
 	// Track the current generation step for error reporting
 	failedStepMessage := ""
@@ -320,8 +328,9 @@ func Generate(ctx context.Context, opts GenerateOptions) (*GenerationAccess, err
 	}
 
 	return &GenerationAccess{
-		AccessAllowed: generationAccess,
-		Message:       message,
+		AccessAllowed:         generationAccess,
+		Message:               message,
+		RenderedUsageSnippets: g.GetRenderedUsageSnippets(),
 	}, nil
 }
 

pkg/codesamples/codesamples.go

@@ -33,16 +33,15 @@ type CodeSampleExampleSource struct {
 }
 
 func GenerateOverlay(ctx context.Context, schema, header, token, configPath, overlayFilename string, langs []string, isWorkflow bool, isSilent bool, opts workflow.CodeSamples) (string, error) {
-	targetToCodeSamples := map[string][]usagegen.UsageSnippet{}
-	isJSON := filepath.Ext(schema) == ".json"
-
 	if isSilent {
 		logger := log.From(ctx)
 		var logs bytes.Buffer
 		logCapture := logger.WithWriter(&logs)
 		ctx = log.With(ctx, logCapture)
 	}
 
+	var allSnippets []usagegen.UsageSnippet
+
 	for _, lang := range langs {
 		usageOutput := &bytes.Buffer{}
 
@@ -72,11 +71,34 @@ func GenerateOverlay(ctx context.Context, schema, header, token, configPath, ove
 			return "", err
 		}
 
-		for _, snippet := range snippets {
-			target := overlay.NewTargetSelector(snippet.Path, snippet.Method)
+		allSnippets = append(allSnippets, snippets...)
+	}
+
+	return buildOverlay(allSnippets, schema, langs[0], overlayFilename, isWorkflow, opts)
+}
 
-			targetToCodeSamples[target] = append(targetToCodeSamples[target], snippet)
-		}
+// GenerateOverlayFromRawSnippets builds a code samples overlay from pre-rendered
+// raw snippet output, bypassing the need to create a new Generator and re-resolve
+// the AST. The rawOutput is expected to contain "// Usage snippet provided for ..."
+// sections as produced by standalone.ts.
+func GenerateOverlayFromRawSnippets(ctx context.Context, rawOutput, lang, schema string, overlayFilename string, isWorkflow bool, opts workflow.CodeSamples) (string, error) {
+	snippets, err := usagegen.ParseUsageOutput(lang, rawOutput)
+	if err != nil {
+		return "", err
+	}
+
+	log.From(ctx).Infof("\nUsing pre-rendered usage snippets for %s\n\n", lang)
+
+	return buildOverlay(snippets, schema, lang, overlayFilename, isWorkflow, opts)
+}
+
+func buildOverlay(snippets []usagegen.UsageSnippet, schema, lang, overlayFilename string, isWorkflow bool, opts workflow.CodeSamples) (string, error) {
+	isJSON := filepath.Ext(schema) == ".json"
+
+	targetToCodeSamples := map[string][]usagegen.UsageSnippet{}
+	for _, snippet := range snippets {
+		target := overlay.NewTargetSelector(snippet.Path, snippet.Method)
+		targetToCodeSamples[target] = append(targetToCodeSamples[target], snippet)
 	}
 
 	var actions []overlay.Action
@@ -102,10 +124,10 @@ func GenerateOverlay(ctx context.Context, schema, header, token, configPath, ove
 	}
 
 	if isWorkflow {
-		title = fmt.Sprintf("CodeSamples overlay for %s target", langs[0])
+		title = fmt.Sprintf("CodeSamples overlay for %s target", lang)
 	}
 
-	overlay := &overlay.Overlay{
+	o := &overlay.Overlay{
 		Version: "1.0.0",
 		Info: overlay.Info{
 			Title:   title,
@@ -115,10 +137,10 @@ func GenerateOverlay(ctx context.Context, schema, header, token, configPath, ove
 	}
 
 	if !isWorkflow {
-		overlay.Extends = extends
+		o.Extends = extends
 	}
 
-	overlayString, err := overlay.ToString()
+	overlayString, err := o.ToString()
 	if err != nil {
 		return "", err
 	}