|
| 1 | +// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers |
| 2 | +// SPDX-License-Identifier: Apache-2.0 |
| 3 | + |
| 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 also includes a field-site comparison (Base vs |
| 32 | +// BaseAlias as field types) so the field-reach behaviour is on |
| 33 | +// the same canvas as the embed-reach behaviour. |
| 34 | +// |
| 35 | +// 5 decls × 3 modes = 15 base cells, plus indirect impacts on Base / |
| 36 | +// BaseAlias / Methods which may surface as standalone definitions. |
| 37 | +// |
| 38 | +// See `.claude/plans/workshops/alias-matrix.md` §5 and |
| 39 | +// `.claude/plans/workshops/alias-ledger.md` cycle 3. |
| 40 | +package alias_calibration_embed |
| 41 | + |
| 42 | +// Base is the canonical struct used as the embedded target in |
| 43 | +// every variant below. Two fields so we can see the FLAT vs allOf |
| 44 | +// distinction in the output. |
| 45 | +// |
| 46 | +// swagger:model Base |
| 47 | +type Base struct { |
| 48 | + // required: true |
| 49 | + ID int64 `json:"id"` |
| 50 | + |
| 51 | + Name string `json:"name"` |
| 52 | +} |
| 53 | + |
| 54 | +// BaseAlias is a transparent rename of Base. In Go, BaseAlias and |
| 55 | +// Base are LITERALLY the same type — `types.Unalias(BaseAlias) == |
| 56 | +// Base`, reflection cannot distinguish them. |
| 57 | +type BaseAlias = Base |
| 58 | + |
| 59 | +// Methods is a named interface with one valid property-shaped |
| 60 | +// method, used to test embed-of-interface. |
| 61 | +type Methods interface { |
| 62 | + // Describe returns a human-readable label. |
| 63 | + Describe() string |
| 64 | +} |
| 65 | + |
| 66 | +// EmbedsDirectStruct embeds Base directly. The B2 probe shape: |
| 67 | +// FLAT — `{type: object, properties: {id, name, extra}}` with no |
| 68 | +// allOf composition. Q8 baseline. |
| 69 | +// |
| 70 | +// swagger:model EmbedsDirectStruct |
| 71 | +type EmbedsDirectStruct struct { |
| 72 | + Base |
| 73 | + |
| 74 | + // Extra is a field unique to the outer struct. |
| 75 | + Extra string `json:"extra"` |
| 76 | +} |
| 77 | + |
| 78 | +// EmbedsAlias embeds BaseAlias. The B2 probe shape: `allOf: |
| 79 | +// [{$ref: BaseAlias}, {properties: {extra}}]`. Q8 OUTLIER — same |
| 80 | +// Go type as EmbedsDirectStruct produces a DIFFERENT spec shape. |
| 81 | +// |
| 82 | +// swagger:model EmbedsAlias |
| 83 | +type EmbedsAlias struct { |
| 84 | + BaseAlias |
| 85 | + |
| 86 | + Extra string `json:"extra"` |
| 87 | +} |
| 88 | + |
| 89 | +// EmbedsPointer embeds *Base. The B2 probe shape: FLAT (pointer is |
| 90 | +// peeled, then takes the named-direct path). Consistent with |
| 91 | +// EmbedsDirectStruct. |
| 92 | +// |
| 93 | +// swagger:model EmbedsPointer |
| 94 | +type EmbedsPointer struct { |
| 95 | + *Base |
| 96 | + |
| 97 | + Extra string `json:"extra"` |
| 98 | +} |
| 99 | + |
| 100 | +// EmbedsInterface embeds the named Methods interface. The B2 probe |
| 101 | +// shape: FLAT — method properties promoted into the outer schema |
| 102 | +// alongside Tag. Consistent with EmbedsDirectStruct (named embed |
| 103 | +// of any kind goes through buildNamedEmbedded which inlines). |
| 104 | +// |
| 105 | +// swagger:model EmbedsInterface |
| 106 | +type EmbedsInterface struct { |
| 107 | + Methods |
| 108 | + |
| 109 | + Tag string `json:"tag"` |
| 110 | +} |
| 111 | + |
| 112 | +// Envelope compares Base and BaseAlias at the FIELD-reach site |
| 113 | +// (not embed). Cycles 1-2 showed annotated aliases produce a |
| 114 | +// $ref to the def at field sites; we want to see whether the |
| 115 | +// alias-vs-named asymmetry persists at the field site or only at |
| 116 | +// the embed site. |
| 117 | +// |
| 118 | +// swagger:model Envelope |
| 119 | +type Envelope struct { |
| 120 | + // Direct field of type Base. |
| 121 | + Direct Base `json:"direct"` |
| 122 | + |
| 123 | + // ViaAlias field of type BaseAlias — same underlying as Direct. |
| 124 | + ViaAlias BaseAlias `json:"viaAlias"` |
| 125 | +} |
| 126 | + |
| 127 | +// EmbedsAliasOptIn validates the bidirectional Q-D contract: when |
| 128 | +// the user EXPLICITLY annotates an aliased embed with |
| 129 | +// `swagger:allOf`, the resulting spec MUST use allOf composition |
| 130 | +// with a $ref to the embedded type. This is the shape that was |
| 131 | +// silently produced (without annotation) before the Q-D fix; it |
| 132 | +// remains available as an explicit opt-in. |
| 133 | +// |
| 134 | +// Combined with EmbedsAlias above, this fixture asserts: |
| 135 | +// |
| 136 | +// - Without `swagger:allOf` → flat inline (EmbedsAlias) |
| 137 | +// - With `swagger:allOf` → allOf with $ref (EmbedsAliasOptIn) |
| 138 | +// |
| 139 | +// The annotation is the SOLE gate; no other input flips composition. |
| 140 | +// |
| 141 | +// swagger:model EmbedsAliasOptIn |
| 142 | +type EmbedsAliasOptIn struct { |
| 143 | + // swagger:allOf |
| 144 | + BaseAlias |
| 145 | + |
| 146 | + // Extra is a field unique to the outer struct. |
| 147 | + Extra string `json:"extra"` |
| 148 | +} |
| 149 | + |
| 150 | +// EmbedsDirectStructOptIn mirrors EmbedsAliasOptIn but with a |
| 151 | +// direct named-struct embed instead of an alias embed — checks |
| 152 | +// that the explicit annotation works on non-aliased embeds too. |
| 153 | +// Pre-Q-D this case ALREADY worked (named-direct embed with |
| 154 | +// swagger:allOf → allOf with $ref to Base) — the annotation path |
| 155 | +// was never broken; only the *implicit* aliased-embed promotion |
| 156 | +// was wrong. Including this here triangulates: same annotation, |
| 157 | +// same shape, regardless of alias or direct. |
| 158 | +// |
| 159 | +// swagger:model EmbedsDirectStructOptIn |
| 160 | +type EmbedsDirectStructOptIn struct { |
| 161 | + // swagger:allOf |
| 162 | + Base |
| 163 | + |
| 164 | + Extra string `json:"extra"` |
| 165 | +} |
0 commit comments