fix(docs): ensure cross-package refs are inlined

The docs plugin was failing to inline type references for types defined in other design packages. This was because it processed each design root in isolation, resulting in an incomplete map of definitions when resolving refs.

This commit refactors the generator to first build a global map of all type definitions from all design roots. This complete map is then used for the inlining process, ensuring that cross-package and cross-service references are correctly resolved.

A new test case, , has been added to verify this behavior and prevent regressions.

Author: raphael

docs/generate.go

@@ -30,28 +30,59 @@ func init() { Register() }
 
 // Generate produces the documentation JSON file.
 func Generate(_ string, roots []eval.Root, files []*codegen.File) ([]*codegen.File, error) {
+	// First, build a complete map of all definitions from all roots.
+	// This ensures that cross-package type references can be resolved.
+	allDefs := make(map[string]*openapi.Schema)
 	for _, root := range roots {
 		if r, ok := root.(*expr.RootExpr); ok {
-			files = append(files, docsFile(r))
+			// Create a temporary, isolated context for each root to avoid global state pollution.
+			prev := openapi.Definitions
+			openapi.Definitions = make(map[string]*openapi.Schema)
+
+			for _, tpe := range r.Types {
+				if ut, ok := tpe.(*expr.UserTypeExpr); ok {
+					openapi.GenerateTypeDefinition(r.API, ut)
+				}
+			}
+			for _, rt := range r.ResultTypes {
+				openapi.GenerateResultTypeDefinition(r.API, rt, expr.DefaultView)
+			}
+
+			// Merge the generated definitions into the global map.
+			for n, s := range openapi.Definitions {
+				if _, exists := allDefs[n]; !exists {
+					allDefs[n] = dupSchema(s)
+				}
+			}
+
+			// Restore the original global definitions to maintain isolation.
+			openapi.Definitions = prev
+		}
+	}
+
+	for _, root := range roots {
+		if r, ok := root.(*expr.RootExpr); ok {
+			files = append(files, docsFile(r, allDefs))
 		}
 	}
 	return files, nil
 }
 
-func docsFile(r *expr.RootExpr) *codegen.File {
-
+func docsFile(r *expr.RootExpr, allDefs map[string]*openapi.Schema) *codegen.File {
 	docs := &data{
 		API:      apiDocs(r.API),
 		Services: servicesDocs(r),
 	}
 
 	// Default behavior: use global OpenAPI definitions to preserve ordering and
 	// compatibility with existing golden tests.
-	defs := openapi.Definitions
+	defs := allDefs
 
 	// If either option is enabled, build a local definition map for this root
 	// and apply transforms/inlining as needed, isolating from global state.
-	if plugexpr.Root.UseJSONTags || plugexpr.Root.InlineRefs {
+	if plugexpr.Root.UseJSONTags {
+		// Re-scope the definitions to only those present in the current root,
+		// but use the globally-aware `allDefs` for lookups during transforms.
 		local := make(map[string]*openapi.Schema)
 		prev := openapi.Definitions
 		openapi.Definitions = make(map[string]*openapi.Schema)
@@ -63,8 +94,10 @@ func docsFile(r *expr.RootExpr) *codegen.File {
 		for _, rt := range r.ResultTypes {
 			openapi.GenerateResultTypeDefinition(r.API, rt, expr.DefaultView)
 		}
-		for n, s := range openapi.Definitions {
-			local[n] = dupSchema(s)
+		for n := range openapi.Definitions {
+			if def, ok := allDefs[n]; ok {
+				local[n] = dupSchema(def)
+			}
 		}
 		openapi.Definitions = prev
 
@@ -92,31 +125,38 @@ func docsFile(r *expr.RootExpr) *codegen.File {
 
 	// Inline $refs if requested via DSL flag.
 	if plugexpr.Root.InlineRefs {
+		// When inlining, use the complete set of definitions from all roots
+		// to ensure cross-package references can be resolved.
+		inliningDefs := allDefs
+		if plugexpr.Root.UseJSONTags {
+			inliningDefs = transformDefinitionsWithJSONTagsHybrid(r, allDefs, nil)
+		}
+
 		// Inline inside service payloads/results/errors.
 		for _, svc := range docs.Services {
 			for _, m := range svc.Methods {
 				if m.Payload != nil && m.Payload.Type != nil {
-					inlineRefsInSchema(m.Payload.Type, defs, make(map[string]bool))
+					inlineRefsInSchema(m.Payload.Type, inliningDefs, make(map[string]bool))
 				}
 				if m.StreamingPayload != nil && m.StreamingPayload.Type != nil {
-					inlineRefsInSchema(m.StreamingPayload.Type, defs, make(map[string]bool))
+					inlineRefsInSchema(m.StreamingPayload.Type, inliningDefs, make(map[string]bool))
 				}
 				if m.Result != nil && m.Result.Type != nil {
-					inlineRefsInSchema(m.Result.Type, defs, make(map[string]bool))
+					inlineRefsInSchema(m.Result.Type, inliningDefs, make(map[string]bool))
 				}
 				if m.StreamingResult != nil && m.StreamingResult.Type != nil {
-					inlineRefsInSchema(m.StreamingResult.Type, defs, make(map[string]bool))
+					inlineRefsInSchema(m.StreamingResult.Type, inliningDefs, make(map[string]bool))
 				}
 				for _, e := range m.Errors {
 					if e != nil && e.Type != nil {
-						inlineRefsInSchema(e.Type, defs, make(map[string]bool))
+						inlineRefsInSchema(e.Type, inliningDefs, make(map[string]bool))
 					}
 				}
 			}
 		}
 		// Inline inside definitions themselves (properties that refer to other defs).
 		for _, def := range defs {
-			inlineRefsInSchema(def, defs, make(map[string]bool))
+			inlineRefsInSchema(def, inliningDefs, make(map[string]bool))
 		}
 	}
 

docs/generate_test.go

@@ -291,3 +291,110 @@ func TestJSONTagsAndInlineRefs_Complex(t *testing.T) {
 		t.Fatalf("expected required array in result type, got: %#v", rt)
 	}
 }
+
+func TestInlineRefs_MethodRootPayloadResult(t *testing.T) {
+	t.Cleanup(func() { plugexpr.Root.UseJSONTags = false; plugexpr.Root.InlineRefs = false })
+
+	docsMap := genDocs(t, func() {
+		InlineRefs()
+		API("Test", func() {})
+		var PayloadType = Type("PayloadType", func() {
+			Field(1, "Foo", String)
+			Required("Foo")
+		})
+		var ResultType = Type("ResultType", func() {
+			Field(1, "Bar", String)
+			Required("Bar")
+		})
+		Service("S", func() {
+			Method("M1", func() {
+				Payload(PayloadType)
+				Result(ResultType)
+				HTTP(func() { GET("/") })
+				GRPC(func() {})
+			})
+		})
+	})
+
+	svc := docsMap["services"].(map[string]any)["S"].(map[string]any)
+	methods := svc["methods"].(map[string]any)
+	m1 := methods["M1"].(map[string]any)
+	pt := m1["payload"].(map[string]any)["type"].(map[string]any)
+	if _, hasRef := pt["$ref"]; hasRef {
+		t.Fatalf("expected inlined payload schema at method root, found $ref: %#v", pt)
+	}
+	rt := m1["result"].(map[string]any)["type"].(map[string]any)
+	if _, hasRef := rt["$ref"]; hasRef {
+		t.Fatalf("expected inlined result schema at method root, found $ref: %#v", rt)
+	}
+}
+
+func TestInlineRefs_CrossPackage(t *testing.T) {
+	t.Cleanup(func() { plugexpr.Root.UseJSONTags = false; plugexpr.Root.InlineRefs = false })
+	docsMap := genDocs(t, func() {
+		InlineRefs()
+		API("Test", func() {})
+		// Service "S1" uses a type from a different package.
+		Service("S1", func() {
+			Method("M1", func() {
+				Payload(testdata.CrossPackageType)
+				HTTP(func() { GET("/") })
+				GRPC(func() {})
+			})
+		})
+	})
+
+	svc := docsMap["services"].(map[string]any)["S1"].(map[string]any)
+	methods := svc["methods"].(map[string]any)
+	m1 := methods["M1"].(map[string]any)
+	pt := m1["payload"].(map[string]any)["type"].(map[string]any)
+	if _, hasRef := pt["$ref"]; hasRef {
+		t.Fatalf("expected inlined payload schema for cross-package type, found $ref: %#v", pt)
+	}
+	assert.Equal(t, "object", pt["type"])
+	props := pt["properties"].(map[string]any)
+	_, hasA := props["A"]
+	assert.True(t, hasA)
+}
+
+func TestInlineRefs_CrossService(t *testing.T) {
+	t.Cleanup(func() { plugexpr.Root.UseJSONTags = false; plugexpr.Root.InlineRefs = false })
+	docsMap := genDocs(t, func() {
+		InlineRefs()
+		API("Test", func() {})
+		var SharedType = Type("SharedType", func() {
+			Field(1, "A", String)
+			Required("A")
+		})
+		Service("S1", func() {
+			Method("M1", func() {
+				Payload(SharedType)
+				HTTP(func() { GET("/") })
+				GRPC(func() {})
+			})
+		})
+		Service("S2", func() {
+			Method("M2", func() {
+				Payload(SharedType)
+				HTTP(func() { GET("/s2") })
+				GRPC(func() {})
+			})
+		})
+	})
+
+	// Check S1
+	s1 := docsMap["services"].(map[string]any)["S1"].(map[string]any)
+	m1 := s1["methods"].(map[string]any)["M1"].(map[string]any)
+	pt1 := m1["payload"].(map[string]any)["type"].(map[string]any)
+	if _, hasRef := pt1["$ref"]; hasRef {
+		t.Fatalf("S1: expected inlined payload schema for shared type, found $ref: %#v", pt1)
+	}
+
+	// Check S2
+	s2 := docsMap["services"].(map[string]any)["S2"].(map[string]any)
+	m2 := s2["methods"].(map[string]any)["M2"].(map[string]any)
+	pt2 := m2["payload"].(map[string]any)["type"].(map[string]any)
+	if _, hasRef := pt2["$ref"]; hasRef {
+		t.Fatalf("S2: expected inlined payload schema for shared type, found $ref: %#v", pt2)
+	}
+}