Skip to content

Commit 5c55ebb

Browse files
fredbiclaude
andcommitted
docs(builders): consolidate alias-handling contract; scrub planning vocabulary
Documents the unified alias-handling contract across the three builders (schema, parameters, responses) in their README files and scrubs the planning-phase vocabulary that accumulated during the work but does not belong in the disclosed surface. Contract documentation: - schema/README.md §aliases — extended to cover both decl shape (mode-dependent: dissolve / $ref / expand) and use-site shape (annotation-gated: $ref alias name with `swagger:model`, dissolve otherwise; TransparentAliases supersedes). Adds notes on SimpleSchema reach contexts (non-body params, response headers), top-level swagger:parameters / swagger:response alias declarations (never produce model definitions), and the Rhs / Underlying / Unalias distinction across the three branches. - parameters/README.md §alias-handling — rewritten to defer to the schema contract and describe the parameters-specific reach contexts (top-level alias, body field, non-body field). - responses/README.md §alias-handling — same treatment for the responses builder. The historical `quirks-history` section is untouched. Vocabulary scrub across code, fixtures, and tests: - Rule-letter labels and workshop-cycle references removed from inline comments. The rules they named are now documented in the relevant README sections, so the comments point at the contract instead of carrying their own scaffolding. - `.claude/plans/` path references removed (those documents are not part of the disclosed repo surface). The two non-alias occurrences (the YAML dedupe documentation and the securitydefs witness) gain neutral phrasing. - Fixture godoc packages rewritten to describe what the fixture exercises rather than which workshop cycle produced it; the contract pointer cross-links to the relevant builder README. Test impact: goldens regenerate for the fixtures whose godoc text was rewritten (the description fields land in the captured spec). No behavioural changes — the asserted shapes are unchanged. Full suite green; lint clean. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
1 parent 5fab72f commit 5c55ebb

46 files changed

Lines changed: 711 additions & 726 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 65 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,22 @@
11
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
22
// SPDX-License-Identifier: Apache-2.0
33

4-
// Package alias_calibration_embed is the cycle-3 calibration fixture
5-
// for the W3 alias workshop. It tests the composition axis: how the
6-
// schema builder shapes a struct that EMBEDS another type, in four
7-
// permutations of how the embedded type is referenced:
8-
//
9-
// 1. Named struct, direct (EmbedsDirectStruct)
10-
// 2. Alias of struct (EmbedsAlias)
11-
// 3. Pointer to named struct (EmbedsPointer)
12-
// 4. Named interface (EmbedsInterface)
13-
//
14-
// In Go, (1), (2), and (3) refer to the SAME underlying type
15-
// (`Base`); `BaseAlias = Base` is a transparent rename, `*Base` is
16-
// just a pointer-to-Base. The type system cannot distinguish them.
17-
// Yet the schema builder today produces THREE different output
18-
// shapes for the same composition intent — the central Q8 question.
19-
//
20-
// The B2 probe from fix-quirks revealed:
21-
// - EmbedsDirectStruct → FLAT inline (id, name, extra)
22-
// - EmbedsAlias → allOf: [{$ref: BaseAlias}, {extra inline}]
23-
// - EmbedsPointer → FLAT inline (pointer peeled → named-direct)
24-
// - EmbedsInterface → FLAT inline (interface methods promoted)
25-
//
26-
// So the OUTLIER is alias-embed, not interface-embed (the Q8
27-
// original framing was wrong). Cycle 3 calibrates the workshop's
28-
// vocabulary on whether this asymmetry should hold, collapse, or
29-
// invert.
30-
//
31-
// Envelope and EnvelopeAnnotatedAlias bracket the FIELD-reach
32-
// site (Q-E): same Go type as BaseAlias / BaseAliasModeled, but
33-
// only one carries `swagger:model`. R6 makes the annotation the
34-
// gatekeeper for whether an alias surfaces as a first-class spec
35-
// entity (definition + $ref by alias name) or dissolves to its
36-
// unaliased target. The two envelopes pin both halves on one
37-
// canvas.
38-
//
39-
// 7 decls × 3 modes = 21 base cells, plus indirect impacts on Base /
40-
// BaseAlias / BaseAliasModeled / Methods which may surface as
41-
// standalone definitions.
42-
//
43-
// See `.claude/plans/workshops/alias-matrix.md` §5 and
44-
// `.claude/plans/workshops/alias-ledger.md` cycles 3 + 4.
4+
// Package alias_calibration_embed exercises the schema builder's
5+
// alias handling at two reach contexts:
6+
//
7+
// 1. Struct embedding — how does an embed produce inline-vs-allOf
8+
// shape across direct named, alias-of-struct, pointer, and
9+
// named-interface embeds?
10+
// 2. Field site — how does an annotated alias differ from an
11+
// unannotated alias when referenced as a struct field?
12+
//
13+
// The decls below pair each direct / alias / pointer embed against
14+
// its bidirectional companion (annotated vs unannotated alias
15+
// variants) so the per-mode shapes are visible side by side in the
16+
// captured goldens.
17+
//
18+
// See the schema builder's alias-handling contract for the rule:
19+
// [§aliases](../../../internal/builders/schema/README.md#aliases).
4520
package alias_calibration_embed
4621

4722
// Base is the canonical struct used as the embedded target in
@@ -68,9 +43,9 @@ type Methods interface {
6843
Describe() string
6944
}
7045

71-
// EmbedsDirectStruct embeds Base directly. The B2 probe shape:
72-
// FLAT — `{type: object, properties: {id, name, extra}}` with no
73-
// allOf composition. Q8 baseline.
46+
// EmbedsDirectStruct embeds Base directly.
47+
// Expected: FLAT — `{type: object, properties: {id, name, extra}}`
48+
// with no allOf composition.
7449
//
7550
// swagger:model EmbedsDirectStruct
7651
type EmbedsDirectStruct struct {
@@ -80,9 +55,10 @@ type EmbedsDirectStruct struct {
8055
Extra string `json:"extra"`
8156
}
8257

83-
// EmbedsAlias embeds BaseAlias. The B2 probe shape: `allOf:
84-
// [{$ref: BaseAlias}, {properties: {extra}}]`. Q8 OUTLIER — same
85-
// Go type as EmbedsDirectStruct produces a DIFFERENT spec shape.
58+
// EmbedsAlias embeds BaseAlias (an unannotated alias of Base).
59+
// Expected: FLAT — same shape as EmbedsDirectStruct, because the
60+
// aliased embed dissolves to its named target and contributes
61+
// inline properties (not allOf composition).
8662
//
8763
// swagger:model EmbedsAlias
8864
type EmbedsAlias struct {
@@ -91,8 +67,8 @@ type EmbedsAlias struct {
9167
Extra string `json:"extra"`
9268
}
9369

94-
// EmbedsPointer embeds *Base. The B2 probe shape: FLAT (pointer is
95-
// peeled, then takes the named-direct path). Consistent with
70+
// EmbedsPointer embeds *Base. Expected: FLAT (pointer is peeled,
71+
// then takes the named-direct path). Consistent with
9672
// EmbedsDirectStruct.
9773
//
9874
// swagger:model EmbedsPointer
@@ -102,10 +78,9 @@ type EmbedsPointer struct {
10278
Extra string `json:"extra"`
10379
}
10480

105-
// EmbedsInterface embeds the named Methods interface. The B2 probe
106-
// shape: FLAT — method properties promoted into the outer schema
107-
// alongside Tag. Consistent with EmbedsDirectStruct (named embed
108-
// of any kind goes through buildNamedEmbedded which inlines).
81+
// EmbedsInterface embeds the named Methods interface. Expected:
82+
// FLAT — method properties promoted into the outer schema
83+
// alongside Tag.
10984
//
11085
// swagger:model EmbedsInterface
11186
type EmbedsInterface struct {
@@ -115,18 +90,12 @@ type EmbedsInterface struct {
11590
}
11691

11792
// Envelope compares Base and BaseAlias at the FIELD-reach site
118-
// (not embed). BaseAlias is intentionally UNANNOTATED — Q-E asks
119-
// whether the spec should expose this implementation-detail alias
120-
// or dissolve it to the unaliased target.
121-
//
122-
// Under R6 (the rule the W3 workshop converged on):
93+
// (not embed). BaseAlias is intentionally UNANNOTATED — at field
94+
// sites the unannotated alias dissolves to its unaliased target,
95+
// and the alias produces no `definitions` entry.
12396
//
12497
// - direct → {$ref: Base}
125-
// - viaAlias → {$ref: Base} (alias dissolves; unannotated → no entity)
126-
//
127-
// Pre-R6 (current Default / Ref behaviour, witnessed by the golden
128-
// captured at commit time) leaks the alias name into the field's
129-
// $ref target and manufactures a dangling BaseAlias definition.
98+
// - viaAlias → {$ref: Base} (unannotated alias dissolves)
13099
//
131100
// swagger:model Envelope
132101
type Envelope struct {
@@ -137,19 +106,14 @@ type Envelope struct {
137106
ViaAlias BaseAlias `json:"viaAlias"`
138107
}
139108

140-
// EmbedsAliasOptIn validates the bidirectional Q-D contract: when
141-
// the user EXPLICITLY annotates an aliased embed with
142-
// `swagger:allOf`, the resulting spec MUST use allOf composition
143-
// with a $ref to the embedded type. This is the shape that was
144-
// silently produced (without annotation) before the Q-D fix; it
145-
// remains available as an explicit opt-in.
146-
//
147-
// Combined with EmbedsAlias above, this fixture asserts:
148-
//
149-
// - Without `swagger:allOf` → flat inline (EmbedsAlias)
150-
// - With `swagger:allOf` → allOf with $ref (EmbedsAliasOptIn)
109+
// EmbedsAliasOptIn pins the explicit-opt-in side of the embed
110+
// contract: when the user annotates an aliased embed with
111+
// `swagger:allOf`, the spec uses allOf composition with a $ref.
112+
// The unannotated alias still dissolves to the unaliased target —
113+
// `swagger:allOf` governs composition shape only, not identity.
151114
//
152-
// The annotation is the SOLE gate; no other input flips composition.
115+
// - Without `swagger:allOf` → flat inline (EmbedsAlias above)
116+
// - With `swagger:allOf` → allOf with $ref to Base
153117
//
154118
// swagger:model EmbedsAliasOptIn
155119
type EmbedsAliasOptIn struct {
@@ -161,13 +125,10 @@ type EmbedsAliasOptIn struct {
161125
}
162126

163127
// EmbedsDirectStructOptIn mirrors EmbedsAliasOptIn but with a
164-
// direct named-struct embed instead of an alias embed — checks
165-
// that the explicit annotation works on non-aliased embeds too.
166-
// Pre-Q-D this case ALREADY worked (named-direct embed with
167-
// swagger:allOf → allOf with $ref to Base) — the annotation path
168-
// was never broken; only the *implicit* aliased-embed promotion
169-
// was wrong. Including this here triangulates: same annotation,
170-
// same shape, regardless of alias or direct.
128+
// direct named-struct embed instead of an alias embed —
129+
// triangulates that the explicit annotation works on non-aliased
130+
// embeds too. Same annotation, same shape, regardless of alias or
131+
// direct.
171132
//
172133
// swagger:model EmbedsDirectStructOptIn
173134
type EmbedsDirectStructOptIn struct {
@@ -182,35 +143,34 @@ type EmbedsDirectStructOptIn struct {
182143
// annotation is the user's explicit opt-in to exposing the alias
183144
// as a first-class spec entity.
184145
//
185-
// Q-E / R6 cuts the alias-handling rule along the annotation:
146+
// At field / element / allOf-member use sites:
186147
//
187148
// - BaseAlias (no annotation): aliasing is a Go implementation
188-
// detail; field/element use sites dissolve to `Base`, the
189-
// alias does not appear in `definitions`.
149+
// detail; use sites dissolve to `Base`, the alias does not
150+
// appear in `definitions`.
190151
// - BaseAliasModeled (swagger:model): the alias is a first-class
191-
// entity; field/element use sites keep `$ref:
192-
// BaseAliasModeled` and the alias gets its own definition
193-
// (chain under RefAliases, full structural under Expand,
194-
// dissolved under TransparentAliases — modes only affect the
195-
// decl shape, not whether it exists).
152+
// entity; use sites keep `$ref: BaseAliasModeled` and the alias
153+
// gets its own definition (chain under RefAliases, full
154+
// structural under Expand, structural-copy under
155+
// TransparentAliases — modes only affect the decl shape, not
156+
// whether the alias surfaces).
196157
//
197158
// swagger:model BaseAliasModeled
198159
type BaseAliasModeled = Base
199160

200161
// EmbedsAliasModeledOptIn is the bidirectional sibling of
201162
// EmbedsAliasOptIn. Both use `swagger:allOf` on the embedded
202-
// alias to opt into allOf composition, but they differ in
203-
// whether the alias itself is annotated:
163+
// alias to opt into allOf composition, but they differ in whether
164+
// the alias itself is annotated:
204165
//
205166
// - EmbedsAliasOptIn embeds BaseAlias (UNannotated)
206-
// → allOf $ref dissolves to Base (R6 — alias name not exposed)
167+
// → allOf $ref dissolves to Base (alias name not exposed)
207168
// - EmbedsAliasModeledOptIn embeds BaseAliasModeled (annotated)
208-
// → allOf $ref preserves BaseAliasModeled (R6 — annotated = first-class)
169+
// → allOf $ref preserves BaseAliasModeled (annotated → first-class)
209170
//
210-
// The pair pins both halves of the R6 contract under allOf
211-
// composition. `swagger:allOf` governs the SHAPE (composition vs
212-
// flat inline); `swagger:model` governs the IDENTITY (whether the
213-
// alias name appears as a $ref target). They are orthogonal.
171+
// `swagger:allOf` governs the SHAPE (composition vs flat inline);
172+
// `swagger:model` governs the IDENTITY (whether the alias name
173+
// appears as a $ref target). They are orthogonal.
214174
//
215175
// swagger:model EmbedsAliasModeledOptIn
216176
type EmbedsAliasModeledOptIn struct {
@@ -224,11 +184,11 @@ type EmbedsAliasModeledOptIn struct {
224184
// It exposes the ANNOTATED alias `BaseAliasModeled` at a field
225185
// site, alongside a direct `Base` field for comparison. Combined
226186
// with Envelope (which exercises the UNANNOTATED `BaseAlias`),
227-
// the two structs pin both halves of the Q-E / R6 contract on one
228-
// canvas:
187+
// the two structs pin both halves of the field-site contract on
188+
// one canvas:
229189
//
230190
// Envelope.direct → {$ref: Base}
231-
// Envelope.viaAlias → {$ref: Base} (R6: unannotated dissolves)
191+
// Envelope.viaAlias → {$ref: Base} (unannotated dissolves)
232192
// EnvelopeAnnotatedAlias.direct → {$ref: Base}
233193
// EnvelopeAnnotatedAlias.viaAliasModeled → {$ref: BaseAliasModeled}
234194
//
@@ -237,9 +197,10 @@ type EnvelopeAnnotatedAlias struct {
237197
// Direct field of type Base — control for comparison.
238198
Direct Base `json:"direct"`
239199

240-
// ViaAliasModeled — annotated alias as a field type. Under R6
241-
// this must keep its alias identity at the use site
200+
// ViaAliasModeled — annotated alias as a field type. The
201+
// annotated alias keeps its identity at the use site
242202
// regardless of mode (Default / Ref); Transparent still
243-
// dissolves it because Transparent supersedes annotation.
203+
// dissolves at use sites because Transparent supersedes
204+
// annotation.
244205
ViaAliasModeled BaseAliasModeled `json:"viaAliasModeled"`
245206
}

‎fixtures/enhancements/alias-calibration-primitive/types.go‎

Lines changed: 16 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,26 @@
11
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
22
// SPDX-License-Identifier: Apache-2.0
33

4-
// Package alias_calibration_primitive is the cycle-1 calibration
5-
// fixture for the W3 alias workshop. It is intentionally the smallest
6-
// possible alias-decl scenario, designed to surface the annotation-vs-
7-
// auto-discovery distinction Fred surfaced in cycle 1.
4+
// Package alias_calibration_primitive exercises the schema
5+
// builder's alias handling at the simplest decl-level scenario:
6+
// aliases of primitives, with the annotation-vs-auto-discovery
7+
// distinction visible side by side.
88
//
9-
// Three annotated aliases (UserID / Name / Active) sit alongside two
10-
// unannotated aliases (LegacyID / LegacyNick) — same primitive RHS,
11-
// only the swagger:model annotation differs. The Envelope struct
12-
// exposes both flavours as fields so the comparison is visible in
13-
// one spec output per mode.
9+
// Three annotated aliases (UserID / Name / Active) sit alongside
10+
// two unannotated aliases (LegacyID / LegacyNick) — same
11+
// primitive RHS, only the `swagger:model` annotation differs. The
12+
// Envelope struct exposes both flavours as fields so the
13+
// comparison is visible in one spec output per mode.
1414
//
15-
// Cells exercised (per mode):
15+
// Cells exercised:
1616
//
17-
// - decl-as-model × RHS=Basic × annotated → UserID, Name, Active
18-
// - field × RHS=Basic via annotated alias → Envelope.user, .nick, .on
19-
// - decl × RHS=Basic × UNANNOTATED → LegacyID, LegacyNick
20-
// - field × RHS=Basic via unannotated alias → Envelope.legacy, .legacyNick
17+
// - decl × annotated → UserID, Name, Active have own definitions
18+
// - field × annotated alias → Envelope.user, .nick, .on $ref the alias
19+
// - decl × UNANNOTATED → LegacyID, LegacyNick have no definition
20+
// - field × unannotated alias → Envelope.legacy, .legacyNick inline
2121
//
22-
// 10 cells × 3 modes = 30 judgments. The annotated/unannotated pair
23-
// directly tests Fred's rule: "swagger:model forces a definition + $ref;
24-
// auto-discovered should not produce a dangling definition."
25-
//
26-
// See `.claude/plans/workshops/alias-matrix.md` §6 and
27-
// `.claude/plans/workshops/alias-ledger.md` for the judgment record.
22+
// See the schema builder's alias-handling contract:
23+
// [§aliases](../../../internal/builders/schema/README.md#aliases).
2824
package alias_calibration_primitive
2925

3026
// UserID is an alias to int64 exposed as a top-level model.

‎fixtures/enhancements/alias-calibration-stdlib/types.go‎

Lines changed: 22 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,26 @@
11
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
22
// SPDX-License-Identifier: Apache-2.0
33

4-
// Package alias_calibration_stdlib is the cycle-2 calibration fixture
5-
// for the W3 alias workshop. Same structural pattern as cycle 1
6-
// (annotated decls + Envelope using them as fields + one unannotated
7-
// case for the R4 confirmation), but with stdlib-special RHS types
8-
// instead of primitives.
4+
// Package alias_calibration_stdlib exercises the schema builder's
5+
// alias handling for stdlib-special RHS types (`time.Time`,
6+
// `error`, `json.RawMessage`, `any`). `applyStdlibSpecials`
7+
// recognises these types at the schema layer; this fixture
8+
// asserts the recognizer fires across the `buildDeclAlias`
9+
// dispatch paths regardless of mode.
910
//
10-
// `applyStdlibSpecials` recognizes time.Time, error, json.RawMessage,
11-
// and any. The schema builder hits this recognizer in some code paths
12-
// but not all — Q3 is the bug that surfaces when `buildDeclAlias`'s
13-
// Expand branch walks `Underlying()` without checking specials first.
11+
// Cells exercised:
1412
//
15-
// Cells exercised (per mode):
13+
// - decl × annotated × stdlib(time.Time) → Timestamp
14+
// - decl × annotated × stdlib(error) → Err
15+
// - decl × annotated × stdlib(json.RawMessage) → Raw
16+
// - decl × unannotated × stdlib(time.Time) → SilentTime
17+
// - field × annotated alias → Envelope.at / .failure / .payload
18+
// - field × unannotated alias → Envelope.silent
1619
//
17-
// - decl-as-model × RHS=stdlib(time.Time) → Timestamp
18-
// - decl-as-model × RHS=stdlib(error) → Err
19-
// - decl-as-model × RHS=stdlib(json.RawMessage) → Raw
20-
// - decl × RHS=stdlib(time.Time) × UNANNOTATED → SilentTime
21-
// - field × RHS=stdlib(time.Time) via annotated alias → Envelope.at
22-
// - field × RHS=stdlib(error) via annotated alias → Envelope.failure
23-
// - field × RHS=stdlib(json.RawMessage) via annotated alias → Envelope.payload
24-
// - field × RHS=stdlib(time.Time) via unannotated alias → Envelope.silent
25-
//
26-
// 8 cells × 3 modes = 24 judgments. Designed to test where R1
27-
// (modes collapse for primitive RHS) breaks: stdlib-special RHS
28-
// produces *types.Named (not *types.Basic), so the $ref-branch
29-
// switch in schema.go:174 has a matching case — Default and Ref
30-
// may diverge.
31-
//
32-
// See `.claude/plans/workshops/alias-matrix.md` and
33-
// `.claude/plans/workshops/alias-ledger.md` cycle 2.
20+
// See the schema builder's alias-handling and special-types
21+
// contracts:
22+
// [§aliases](../../../internal/builders/schema/README.md#aliases),
23+
// [§special-types](../../../internal/builders/schema/README.md#special-types).
3424
package alias_calibration_stdlib
3525

3626
import (
@@ -58,9 +48,11 @@ type Err = error
5848
type Raw = json.RawMessage
5949

6050
// SilentTime is an alias to time.Time with NO swagger:model
61-
// annotation — reachable only via Envelope.Silent. Tests whether
62-
// R4 ("annotation gates definitions") holds for stdlib-special RHS
63-
// the way it did for primitive RHS in cycle 1.
51+
// annotation — reachable only via Envelope.Silent. Tests that the
52+
// annotation gate at use sites holds for stdlib-special RHS just
53+
// as it does for primitive RHS: the unannotated alias dissolves
54+
// and the recognizer's canonical shape lands inline at the
55+
// `Envelope.silent` field site.
6456
type SilentTime = time.Time
6557

6658
// Envelope uses all four aliases as field types: three annotated,

0 commit comments

Comments
 (0)
⌂ 换网址