Skip to content

Commit d8f654c

Browse files
fredbiclaude
andcommitted
feat(schema): resolve cross-package leaf type names in type-name keywords
The type-name keyword sites (swagger:type, swagger:additionalProperties, swagger:patternProperties) resolved a bare type name only within the annotating type's own package. A name referring to a model in another package was silently dropped with an "unknown type" diagnostic — a gap the name-identity work left open: it gave routes/responses cross-package leaf resolution but not these schema keywords, and a textual merge could not surface the inconsistency. Resolve a bare leaf the same way the reduce stage does: own package first (a local type wins), then uniquely across the scanned packages' annotated model set — - exactly one model with that leaf -> its definition (additionalProperties /patternProperties emit a $ref via DefKey, so reduce shortens it like any other; swagger:type inlines as before); - several -> a validate.ambiguous-type-name diagnostic and the reference is dropped (never guessed); - none -> the existing unknown-type diagnostic. Only the annotated model set (fixed before building) is searched, so the result is a pure function of the source, not of build order. Witness fixture keyword-xpkg-leaf covers the unique, ambiguous and swagger:type cases with a golden lock. Signed-off-by: Frederic BIDON <fredbi@yahoo.com> contributes to go-swagger#2251 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 5bbd33a commit d8f654c

11 files changed

Lines changed: 365 additions & 46 deletions

File tree

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package a
5+
6+
// swagger:model Widget
7+
type Widget struct {
8+
Kind string `json:"kind"`
9+
}
Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
// Package keywordxpkg witnesses cross-package leaf resolution for the
5+
// type-name keyword sites (swagger:additionalProperties,
6+
// swagger:patternProperties, swagger:type): a bare type name that lives in
7+
// ANOTHER package should resolve by leaf against the discovered model set —
8+
// uniquely (promote to its definition) or, when several packages share the
9+
// leaf, with an ambiguity diagnostic + drop.
10+
package keywordxpkg
11+
12+
import (
13+
"github.com/go-openapi/codescan/fixtures/enhancements/keyword-xpkg-leaf/a"
14+
"github.com/go-openapi/codescan/fixtures/enhancements/keyword-xpkg-leaf/b"
15+
"github.com/go-openapi/codescan/fixtures/enhancements/keyword-xpkg-leaf/dup1"
16+
"github.com/go-openapi/codescan/fixtures/enhancements/keyword-xpkg-leaf/dup2"
17+
)
18+
19+
// keep the cross-package imports referenced so the packages load.
20+
var (
21+
_ = a.Widget{}
22+
_ = b.Gadget{}
23+
_ = dup1.Thing{}
24+
_ = dup2.Thing{}
25+
)
26+
27+
// Bag carries additionalProperties referencing a cross-package model by leaf
28+
// (a.Widget). Unique leaf -> resolves to a $ref.
29+
//
30+
// swagger:model Bag
31+
// swagger:additionalProperties Widget
32+
type Bag struct {
33+
ID string `json:"id"`
34+
}
35+
36+
// Catalog carries patternProperties referencing a cross-package model by leaf
37+
// (a.Widget). Unique leaf -> resolves to a $ref.
38+
//
39+
// swagger:model Catalog
40+
// swagger:patternProperties "^item-": Widget
41+
type Catalog struct {
42+
ID string `json:"id"`
43+
}
44+
45+
// AmbiguousBag references a leaf (Thing) declared as a model in TWO packages
46+
// (dup1, dup2). Ambiguous -> diagnostic + the marker is dropped.
47+
//
48+
// swagger:model AmbiguousBag
49+
// swagger:additionalProperties Thing
50+
type AmbiguousBag struct {
51+
ID string `json:"id"`
52+
}
53+
54+
// Holder overrides a field type with swagger:type referencing a cross-package
55+
// model by leaf (b.Gadget). swagger:type inlines, so the field becomes the
56+
// Gadget structure in place.
57+
//
58+
// swagger:model Holder
59+
type Holder struct {
60+
// swagger:type Gadget
61+
Thing string `json:"thing"`
62+
}
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package b
5+
6+
// swagger:model Gadget
7+
type Gadget struct {
8+
Power int64 `json:"power"`
9+
}
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package dup1
5+
6+
// swagger:model Thing
7+
type Thing struct {
8+
X int64 `json:"x"`
9+
}
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package dup2
5+
6+
// swagger:model Thing
7+
type Thing struct {
8+
Y int64 `json:"y"`
9+
}
Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
{
2+
"swagger": "2.0",
3+
"paths": {},
4+
"definitions": {
5+
"AmbiguousBag": {
6+
"description": "AmbiguousBag references a leaf (Thing) declared as a model in TWO packages\n(dup1, dup2). Ambiguous -\u003e diagnostic + the marker is dropped.",
7+
"type": "object",
8+
"properties": {
9+
"id": {
10+
"type": "string",
11+
"x-go-name": "ID"
12+
}
13+
},
14+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/keyword-xpkg-leaf"
15+
},
16+
"Bag": {
17+
"description": "Bag carries additionalProperties referencing a cross-package model by leaf\n(a.Widget). Unique leaf -\u003e resolves to a $ref.",
18+
"type": "object",
19+
"properties": {
20+
"id": {
21+
"type": "string",
22+
"x-go-name": "ID"
23+
}
24+
},
25+
"additionalProperties": {
26+
"$ref": "#/definitions/Widget"
27+
},
28+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/keyword-xpkg-leaf"
29+
},
30+
"Catalog": {
31+
"description": "Catalog carries patternProperties referencing a cross-package model by leaf\n(a.Widget). Unique leaf -\u003e resolves to a $ref.",
32+
"type": "object",
33+
"properties": {
34+
"id": {
35+
"type": "string",
36+
"x-go-name": "ID"
37+
}
38+
},
39+
"patternProperties": {
40+
"^item-": {
41+
"$ref": "#/definitions/Widget"
42+
}
43+
},
44+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/keyword-xpkg-leaf"
45+
},
46+
"Dup1Thing": {
47+
"type": "object",
48+
"properties": {
49+
"x": {
50+
"type": "integer",
51+
"format": "int64",
52+
"x-go-name": "X"
53+
}
54+
},
55+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/keyword-xpkg-leaf/dup1"
56+
},
57+
"Dup2Thing": {
58+
"type": "object",
59+
"properties": {
60+
"y": {
61+
"type": "integer",
62+
"format": "int64",
63+
"x-go-name": "Y"
64+
}
65+
},
66+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/keyword-xpkg-leaf/dup2"
67+
},
68+
"Gadget": {
69+
"type": "object",
70+
"properties": {
71+
"power": {
72+
"type": "integer",
73+
"format": "int64",
74+
"x-go-name": "Power"
75+
}
76+
},
77+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/keyword-xpkg-leaf/b"
78+
},
79+
"Holder": {
80+
"description": "Holder overrides a field type with swagger:type referencing a cross-package\nmodel by leaf (b.Gadget). swagger:type inlines, so the field becomes the\nGadget structure in place.",
81+
"type": "object",
82+
"properties": {
83+
"thing": {
84+
"type": "object",
85+
"properties": {
86+
"power": {
87+
"type": "integer",
88+
"format": "int64",
89+
"x-go-name": "Power"
90+
}
91+
},
92+
"x-go-name": "Thing"
93+
}
94+
},
95+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/keyword-xpkg-leaf"
96+
},
97+
"Widget": {
98+
"type": "object",
99+
"properties": {
100+
"kind": {
101+
"type": "string",
102+
"x-go-name": "Kind"
103+
}
104+
},
105+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/keyword-xpkg-leaf/a"
106+
}
107+
}
108+
}

‎internal/builders/schema/additional_properties.go‎

Lines changed: 13 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ package schema
55

66
import (
77
"go/token"
8-
"go/types"
98

109
"github.com/go-openapi/codescan/internal/builders/resolvers"
1110
"github.com/go-openapi/codescan/internal/ifaces"
@@ -103,38 +102,22 @@ func (s *Builder) resolveAdditionalPropertiesType(arg string, target *oaispec.Sc
103102
return true
104103
}
105104

106-
// Type-name reference → $ref (buildFromType on the named type, NOT its
107-
// Underlying, so buildNamedType emits the reference and registers it for
108-
// discovery).
109-
if s.refAdditionalPropertiesTypeName(base, inner) {
110-
return true
105+
// Type-name reference → $ref. Resolve the leaf in the builder's own
106+
// package first, then uniquely across the scanned packages' models
107+
// (name-identity leaf resolution). buildFromType uses the NAMED type
108+
// (not its Underlying) so buildNamedType emits the $ref and registers it
109+
// for discovery.
110+
decl, found, ambiguous := s.resolveNamedTypeLeaf(base, pos)
111+
if ambiguous {
112+
return false // diagnostic already recorded
113+
}
114+
if found {
115+
if t := declNamedType(decl); t != nil && s.buildFromType(t, inner) == nil {
116+
return true
117+
}
111118
}
112119

113120
s.RecordDiagnostic(grammar.Warnf(pos, grammar.CodeUnsupportedType,
114121
"swagger:additionalProperties: unknown type %q", base))
115122
return false
116123
}
117-
118-
// refAdditionalPropertiesTypeName resolves a type name declared in the
119-
// builder's package onto target, producing a $ref for a model (or inlining a
120-
// non-model leaf, exactly as a field of that type would). Returns false when
121-
// there is no such declaration.
122-
func (s *Builder) refAdditionalPropertiesTypeName(name string, tgt ifaces.SwaggerTypable) bool {
123-
if s.Decl == nil || s.Decl.Pkg == nil {
124-
return false
125-
}
126-
decl, ok := s.Ctx.FindDecl(s.Decl.Pkg.PkgPath, name)
127-
if !ok || decl == nil {
128-
return false
129-
}
130-
var t types.Type
131-
switch {
132-
case decl.Type != nil:
133-
t = decl.Type
134-
case decl.Alias != nil:
135-
t = decl.Alias
136-
default:
137-
return false
138-
}
139-
return s.buildFromType(t, tgt) == nil
140-
}

‎internal/builders/schema/type_override.go‎

Lines changed: 52 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import (
1212
"github.com/go-openapi/codescan/internal/builders/validations"
1313
"github.com/go-openapi/codescan/internal/ifaces"
1414
"github.com/go-openapi/codescan/internal/parsers/grammar"
15+
"github.com/go-openapi/codescan/internal/scanner"
1516
oaispec "github.com/go-openapi/spec"
1617
)
1718

@@ -91,8 +92,16 @@ func (s *Builder) resolveTypeBase(base string, target ifaces.SwaggerTypable, own
9192
}
9293

9394
// Otherwise a type-name reference: inline a known definition in place.
94-
if s.inlineNamedTypeRef(base, target) {
95-
return true
95+
// Resolve the leaf in the builder's own package first, then uniquely
96+
// across the scanned packages' models (name-identity leaf resolution).
97+
decl, found, ambiguous := s.resolveNamedTypeLeaf(base, pos)
98+
if ambiguous {
99+
return false // diagnostic already recorded
100+
}
101+
if found {
102+
if t := declNamedType(decl); t != nil && s.buildFromType(t.Underlying(), target) == nil {
103+
return true
104+
}
96105
}
97106

98107
s.RecordDiagnostic(grammar.Warnf(pos, grammar.CodeUnsupportedType,
@@ -142,27 +151,54 @@ func (s *Builder) inlineGoType(t types.Type, target ifaces.SwaggerTypable) bool
142151
return s.buildFromType(base.Underlying(), target) == nil
143152
}
144153

145-
// inlineNamedTypeRef resolves name to a definition declared in the builder's
146-
// current package and inlines its schema in place (no $ref). Returns false
147-
// when the builder has no package context or no such definition exists.
148-
func (s *Builder) inlineNamedTypeRef(name string, target ifaces.SwaggerTypable) bool {
149-
if s.Decl == nil || s.Decl.Pkg == nil {
150-
return false
154+
// resolveNamedTypeLeaf resolves a bare type name written in a type-name
155+
// keyword (swagger:type / swagger:additionalProperties /
156+
// swagger:patternProperties) to its declaration. It looks in the builder's
157+
// own package first — a local type wins (intent) — then, failing that,
158+
// resolves the leaf across the scanned packages' annotated model set
159+
// (name-identity leaf resolution, mirroring routes' resolveDefinitionByLeaf):
160+
//
161+
// - exactly one model with that leaf -> (decl, true, false);
162+
// - several -> records an ambiguity diagnostic and returns (nil, false, true);
163+
// - none -> (nil, false, false), leaving the caller to emit unknown-type.
164+
func (s *Builder) resolveNamedTypeLeaf(name string, pos token.Position) (decl *scanner.EntityDecl, found, ambiguous bool) {
165+
if s.Decl != nil && s.Decl.Pkg != nil {
166+
if d, ok := s.Ctx.FindDecl(s.Decl.Pkg.PkgPath, name); ok && d != nil {
167+
return d, true, false
168+
}
151169
}
152-
decl, ok := s.Ctx.FindDecl(s.Decl.Pkg.PkgPath, name)
153-
if !ok || decl == nil {
154-
return false
170+
171+
matches := s.Ctx.FindModelsByLeaf(name)
172+
switch len(matches) {
173+
case 0:
174+
return nil, false, false
175+
case 1:
176+
return matches[0], true, false
177+
default:
178+
pkgs := make([]string, 0, len(matches))
179+
for _, m := range matches {
180+
pkgs = append(pkgs, m.Obj().Pkg().Path())
181+
}
182+
s.RecordDiagnostic(grammar.Warnf(pos, grammar.CodeAmbiguousTypeName,
183+
"type name %q is ambiguous: declared as a model in %d packages [%s]; "+
184+
"use a same-package type or a swagger:model override to disambiguate",
185+
name, len(matches), strings.Join(pkgs, ", ")))
186+
return nil, false, true
155187
}
156-
var t types.Type
188+
}
189+
190+
// declNamedType returns the named or alias type a decl carries (nil if
191+
// neither). The caller decides whether to emit it as a $ref (the named type)
192+
// or inline it (its Underlying).
193+
func declNamedType(decl *scanner.EntityDecl) types.Type {
157194
switch {
158195
case decl.Type != nil:
159-
t = decl.Type
196+
return decl.Type
160197
case decl.Alias != nil:
161-
t = decl.Alias
198+
return decl.Alias
162199
default:
163-
return false
200+
return nil
164201
}
165-
return s.buildFromType(t.Underlying(), target) == nil
166202
}
167203

168204
// swagger:type keyword values that are not resolved as scalar/builtin type

0 commit comments

Comments
 (0)
⌂ 换网址