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

.gitignore

@@ -13,3 +13,33 @@
 
 *.swp
 .vscode/*
+
+*.out
+*.test
+gengoalint
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Binaries for programs and plugins
+*.so
+*.so.*
+*.a
+*.dll
+*.exe
+*.exe~
+*.test
+*.out
+*.log
+
+# vendored dependencies
+vendor/
+
+# protoc
+protoc-*/

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,45 @@ func TestJSONTagsAndInlineRefs_Complex(t *testing.T) {
 		t.Fatalf("expected required array in result type, got: %#v", rt)
 	}
 }
+
+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)
+	}
+}

docs/testdata/no-payload-array-return.json

@@ -1 +1 @@
-{"api":{"name":"Test API","version":"0.0.1","servers":{"Test API":{"name":"Test API","description":"Default server for Test API","services":["Service"],"hosts":{"localhost":{"name":"localhost","server":"Test API","uris":["http://localhost:80","grpc://localhost:8080"]}}}}},"services":{"Service":{"name":"Service","methods":{"Method":{"name":"Method","result":{"type":{"type":"array","items":{"type":"string","example":"In voluptatem consectetur."}},"example":["Accusamus saepe et sit.","Deleniti soluta veritatis odit minus voluptatum."]}}}}},"definitions":{"User":{"title":"User","type":"object","properties":{"att1":{"type":"string","example":"In voluptatem consectetur."},"att2":{"type":"integer","example":443436312039258672,"format":"int64"}},"example":{"att1":"Accusamus saepe et sit.","att2":8511135955551101225}}}}
+{"api":{"name":"Test API","version":"0.0.1","servers":{"Test API":{"name":"Test API","description":"Default server for Test API","services":["Service"],"hosts":{"localhost":{"name":"localhost","server":"Test API","uris":["http://localhost:80","grpc://localhost:8080"]}}}}},"services":{"Service":{"name":"Service","methods":{"Method":{"name":"Method","result":{"type":{"type":"array","items":{"type":"string","example":"In voluptatem consectetur."}},"example":["Accusamus saepe et sit.","Deleniti soluta veritatis odit minus voluptatum."]}}}}},"definitions":{}}

docs/testdata/no-payload-map-return.json

@@ -1 +1 @@
-{"api":{"name":"Test API","version":"0.0.1","servers":{"Test API":{"name":"Test API","description":"Default server for Test API","services":["Service"],"hosts":{"localhost":{"name":"localhost","server":"Test API","uris":["http://localhost:80","grpc://localhost:8080"]}}}}},"services":{"Service":{"name":"Service","methods":{"Method":{"name":"Method","result":{"type":{"type":"object","additionalProperties":{"type":"integer","example":650424415,"format":"int32"}},"example":{"Consectetur consequatur necessitatibus accusamus saepe et.":1637648643}}}}}},"definitions":{"User":{"title":"User","type":"object","properties":{"att1":{"type":"string","example":"In voluptatem consectetur."},"att2":{"type":"integer","example":443436312039258672,"format":"int64"}},"example":{"att1":"Accusamus saepe et sit.","att2":8511135955551101225}}}}
+{"api":{"name":"Test API","version":"0.0.1","servers":{"Test API":{"name":"Test API","description":"Default server for Test API","services":["Service"],"hosts":{"localhost":{"name":"localhost","server":"Test API","uris":["http://localhost:80","grpc://localhost:8080"]}}}}},"services":{"Service":{"name":"Service","methods":{"Method":{"name":"Method","result":{"type":{"type":"object","additionalProperties":{"type":"integer","example":650424415,"format":"int32"}},"example":{"Consectetur consequatur necessitatibus accusamus saepe et.":1637648643}}}}}},"definitions":{}}

docs/testdata/no-payload-primitive-return.json

@@ -1 +1 @@
-{"api":{"name":"Test API","version":"0.0.1","servers":{"Test API":{"name":"Test API","description":"Default server for Test API","services":["Service"],"hosts":{"localhost":{"name":"localhost","server":"Test API","uris":["http://localhost:80","grpc://localhost:8080"]}}}}},"services":{"Service":{"name":"Service","methods":{"Method":{"name":"Method","result":{"type":{"type":"string"},"example":"In voluptatem consectetur."}}}}},"definitions":{"User":{"title":"User","type":"object","properties":{"att1":{"type":"string","example":"In voluptatem consectetur."},"att2":{"type":"integer","example":443436312039258672,"format":"int64"}},"example":{"att1":"Accusamus saepe et sit.","att2":8511135955551101225}}}}
+{"api":{"name":"Test API","version":"0.0.1","servers":{"Test API":{"name":"Test API","description":"Default server for Test API","services":["Service"],"hosts":{"localhost":{"name":"localhost","server":"Test API","uris":["http://localhost:80","grpc://localhost:8080"]}}}}},"services":{"Service":{"name":"Service","methods":{"Method":{"name":"Method","result":{"type":{"type":"string"},"example":"In voluptatem consectetur."}}}}},"definitions":{}}

docs/testdata/no-payload-user-return.json

@@ -1 +1 @@
-{"api":{"name":"Test API","version":"0.0.1","servers":{"Test API":{"name":"Test API","description":"Default server for Test API","services":["Service"],"hosts":{"localhost":{"name":"localhost","server":"Test API","uris":["http://localhost:80","grpc://localhost:8080"]}}}}},"services":{"Service":{"name":"Service","methods":{"Method":{"name":"Method","result":{"type":{"$ref":"#/definitions/User"},"example":{"att1":"In voluptatem consectetur.","att2":443436312039258672}}}}}},"definitions":{"User":{"title":"User","type":"object","properties":{"att1":{"type":"string","example":"In voluptatem consectetur."},"att2":{"type":"integer","example":443436312039258672,"format":"int64"}},"example":{"att1":"Accusamus saepe et sit.","att2":8511135955551101225}}}}
+{"api":{"name":"Test API","version":"0.0.1","servers":{"Test API":{"name":"Test API","description":"Default server for Test API","services":["Service"],"hosts":{"localhost":{"name":"localhost","server":"Test API","uris":["http://localhost:80","grpc://localhost:8080"]}}}}},"services":{"Service":{"name":"Service","methods":{"Method":{"name":"Method","result":{"type":{"$ref":"#/definitions/User"},"example":{"att1":"Soluta veritatis odit minus voluptatum sunt commodi.","att2":2887366790483849171}}}}}},"definitions":{"User":{"title":"User","type":"object","properties":{"att1":{"type":"string","example":"In voluptatem consectetur."},"att2":{"type":"integer","example":443436312039258672,"format":"int64"}},"example":{"att1":"Accusamus saepe et sit.","att2":8511135955551101225}}}}

docs/testdata/user-payload-no-return.json

@@ -1 +1 @@
-{"api":{"name":"Test API","version":"0.0.1","servers":{"Test API":{"name":"Test API","description":"Default server for Test API","services":["Service"],"hosts":{"localhost":{"name":"localhost","server":"Test API","uris":["http://localhost:80","grpc://localhost:8080"]}}}}},"services":{"Service":{"name":"Service","methods":{"Method":{"name":"Method","payload":{"type":{"$ref":"#/definitions/User"},"example":{"att1":"Soluta veritatis odit minus voluptatum sunt commodi.","att2":2887366790483849171}}}}}},"definitions":{"User":{"title":"User","type":"object","properties":{"att1":{"type":"string","example":"In voluptatem consectetur."},"att2":{"type":"integer","example":443436312039258672,"format":"int64"}},"example":{"att1":"Accusamus saepe et sit.","att2":8511135955551101225}}}}
+{"api":{"name":"Test API","version":"0.0.1","servers":{"Test API":{"name":"Test API","description":"Default server for Test API","services":["Service"],"hosts":{"localhost":{"name":"localhost","server":"Test API","uris":["http://localhost:80","grpc://localhost:8080"]}}}}},"services":{"Service":{"name":"Service","methods":{"Method":{"name":"Method","payload":{"type":{"$ref":"#/definitions/User"},"example":{"att1":"Exercitationem suscipit deleniti.","att2":7517419439717785447}}}}}},"definitions":{"User":{"title":"User","type":"object","properties":{"att1":{"type":"string","example":"In voluptatem consectetur."},"att2":{"type":"integer","example":443436312039258672,"format":"int64"}},"example":{"att1":"Accusamus saepe et sit.","att2":8511135955551101225}}}}