specshield 3.4.14 → 3.4.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,578 @@
1
+ 'use strict';
2
+
3
+ const L = require('./locate');
4
+ const { clone } = require('./ops');
5
+
6
+ /**
7
+ * One suggestion per breaking change: the expand-and-contract edit that keeps
8
+ * existing clients working, as ops on the TARGET spec. Nothing here is
9
+ * trusted — fixSpec re-runs the diff engine on every suggestion and drops the
10
+ * ones that don't remove their break or that add another.
11
+ *
12
+ * A suggestion: {
13
+ * strategy, short id, e.g. 'restore-deprecated-field'
14
+ * title, one line for the report
15
+ * detail, what the server has to do for the spec to be true
16
+ * ops, edits to the target spec (see ops.js)
17
+ * changes, the breaking diffs it addresses
18
+ * transforms, version transforms for the Spring layer (see shim/)
19
+ * }
20
+ * Changes with no safe spec-level edit come back as { strategy: null, reason }.
21
+ */
22
+
23
+ function suggest(change, ctx) {
24
+ const fn = STRATEGIES[change.type];
25
+ if (!fn) return none(change, 'no automatic fix for this kind of change');
26
+ try {
27
+ return fn(change, ctx) || none(change, 'could not locate it in the spec');
28
+ } catch (err) {
29
+ return none(change, `could not build a fix: ${err.message}`);
30
+ }
31
+ }
32
+
33
+ function none(change, reason) {
34
+ return { strategy: null, title: null, reason, ops: [], changes: [change], transforms: [] };
35
+ }
36
+
37
+ const STRATEGIES = {
38
+ ENDPOINT_REMOVED: restoreOperation,
39
+ METHOD_REMOVED: restoreOperation,
40
+ RESPONSE_FIELD_REMOVED: restoreField,
41
+ REQUEST_FIELD_REMOVED: restoreField,
42
+ PARAMETER_REMOVED: restoreParameter,
43
+ PARAMETER_BECAME_REQUIRED: parameterOptional,
44
+ PARAMETER_TYPE_CHANGED: revertParameterType,
45
+ REQUEST_REQUIRED_FIELD_ADDED: fieldOptional,
46
+ FIELD_BECAME_REQUIRED: fieldOptional,
47
+ REQUEST_FIELD_TYPE_CHANGED: revertFieldType,
48
+ RESPONSE_FIELD_TYPE_CHANGED: revertFieldType,
49
+ RESPONSE_REMOVED: restoreResponse,
50
+ ENUM_VALUE_REMOVED: restoreEnumValue,
51
+ RESPONSE_TYPE_CHANGED: bodyShapeChanged,
52
+ REQUEST_TYPE_CHANGED: bodyShapeChanged,
53
+ SCHEMA_REMOVED: restoreSchema,
54
+ SCHEMA_VARIANT_REMOVED: restoreVariant,
55
+ SCHEMA_DISCRIMINATOR_CHANGED: revertDiscriminator,
56
+ };
57
+
58
+ // ─── operations, responses, components ──────────────────────────────────────
59
+
60
+ function restoreOperation(c, { base, target, deprecate }) {
61
+ const m = c.method.toLowerCase();
62
+ const baseItem = L.get(base, ['paths', c.path]);
63
+ const baseOp = baseItem && baseItem[m];
64
+ if (!baseOp) return null;
65
+ const ops = [];
66
+ if (!L.get(target, ['paths', c.path]) && Array.isArray(baseItem.parameters)) {
67
+ ops.push({ op: 'set', path: ['paths', c.path, 'parameters'], value: baseItem.parameters });
68
+ }
69
+ ops.push({ op: 'set', path: ['paths', c.path, m], value: deprecate(clone(baseOp)) });
70
+ ops.push(...missingRefs(base, target, [baseOp, baseItem.parameters]));
71
+ return {
72
+ strategy: 'restore-deprecated-operation',
73
+ title: `Keep ${c.method.toUpperCase()} ${c.path}, marked deprecated`,
74
+ detail: 'Keep serving it until its callers have moved (`specshield deprecations` shows who still calls it), then remove it.',
75
+ ops, changes: [c], transforms: [],
76
+ };
77
+ }
78
+
79
+ function restoreResponse(c, { base, target }) {
80
+ const code = /^responses\.(.+)$/.exec(c.field)[1];
81
+ const op = L.operationPtr(target, c.method, c.path);
82
+ const value = L.get(base, ['paths', c.path, c.method.toLowerCase(), 'responses', code]);
83
+ if (!op || value === undefined) return null;
84
+ return {
85
+ strategy: 'restore-response',
86
+ title: `Keep documenting the ${code} response of ${c.method.toUpperCase()} ${c.path}`,
87
+ detail: `Clients may handle ${code}; keep it in the spec while the server can still return it.`,
88
+ ops: [{ op: 'set', path: [...op, 'responses', code], value }, ...missingRefs(base, target, [value])],
89
+ changes: [c], transforms: [],
90
+ };
91
+ }
92
+
93
+ function restoreSchema(c, { base, target, deprecate }) {
94
+ const name = c.field.replace(/^components\.schemas\./, '');
95
+ const where = base.components && base.components.schemas ? ['components', 'schemas', name] : ['definitions', name];
96
+ const value = L.get(base, where);
97
+ if (value === undefined) return null;
98
+ return {
99
+ strategy: 'restore-schema',
100
+ title: `Keep the ${name} schema, marked deprecated`,
101
+ detail: 'Code generated from the spec may still import it.',
102
+ ops: [{ op: 'set', path: where, value: deprecate(clone(value)) }, ...missingRefs(base, target, [value])],
103
+ changes: [c], transforms: [],
104
+ };
105
+ }
106
+
107
+ // ─── fields ─────────────────────────────────────────────────────────────────
108
+
109
+ function restoreField(c, ctx) {
110
+ const { base, target, deprecate } = ctx;
111
+ const parsed = L.parseField(c.field);
112
+ const last = parsed && parsed.steps[parsed.steps.length - 1];
113
+ if (parsed && ctx.reshaped.has(`${c.method} ${c.path} ${parsed.side} ${parsed.code}`)) {
114
+ return none(c, 'part of the body shape change of this operation (see below)');
115
+ }
116
+ if (!last || last.prop === undefined) return null;
117
+ const basePtr = L.fieldPtr(base, c.method, c.path, c.field);
118
+ const holder = L.parentObjectPtr(target, c.method, c.path, c.field);
119
+ if (!basePtr || !holder) return null;
120
+
121
+ const name = last.prop;
122
+ const renamedTo = ctx.renames.get(sig(c)) || null;
123
+ const request = parsed.side === 'request';
124
+ const value = deprecate(clone(L.get(base, basePtr)), renamedTo ? `Use \`${renamedTo}\` instead.` : null);
125
+ const ops = [{ op: 'set', path: [...holder, 'properties', name], value }, ...missingRefs(base, target, [L.get(base, basePtr)])];
126
+ // A response field keeps its guarantee; a request field comes back optional
127
+ // so clients already sending only the new shape stay valid.
128
+ if (!request && baseRequired(base, c, name)) ops.push({ op: 'push', path: [...holder, 'required'], value: name });
129
+
130
+ const transforms = [];
131
+ if (renamedTo) {
132
+ transforms.push({
133
+ ...where(c), side: parsed.side, kind: 'rename',
134
+ parent: parsed.steps.slice(0, -1), from: request ? name : renamedTo, to: request ? renamedTo : name,
135
+ });
136
+ }
137
+ return {
138
+ strategy: renamedTo ? 'keep-both-names' : 'restore-deprecated-field',
139
+ title: renamedTo
140
+ ? `\`${name}\` was renamed to \`${renamedTo}\`: ${request ? 'accept' : 'return'} both, \`${name}\` deprecated`
141
+ : `Keep ${request ? 'accepting' : 'returning'} \`${name}\`, marked deprecated`,
142
+ detail: request
143
+ ? (renamedTo
144
+ ? `The server must read \`${name}\` when \`${renamedTo}\` is absent.`
145
+ : `The server must keep accepting \`${name}\` (it may ignore it).`)
146
+ : (renamedTo
147
+ ? `The server must return \`${name}\` with the same value as \`${renamedTo}\`.`
148
+ : `The server must keep returning \`${name}\`.`),
149
+ ops, changes: [c], transforms,
150
+ };
151
+ }
152
+
153
+ function fieldOptional(c, { target }) {
154
+ const parsed = L.parseField(c.field);
155
+ const last = parsed && parsed.steps[parsed.steps.length - 1];
156
+ if (!last || last.prop === undefined) return null;
157
+ const parent = L.parentObjectPtr(target, c.method, c.path, c.field);
158
+ if (!parent) return null;
159
+ const holders = requiredHolders(target, parent, last.prop);
160
+ if (holders.length === 0) return null;
161
+ const propPtr = L.fieldPtr(target, c.method, c.path, c.field);
162
+ const prop = propPtr && L.get(target, L.derefPtr(target, propPtr));
163
+ const def = prop && prop.default !== undefined ? prop.default : undefined;
164
+ const request = parsed.side === 'request';
165
+ return {
166
+ strategy: 'make-optional',
167
+ title: `Make \`${last.prop}\` optional${def !== undefined ? ` (default ${JSON.stringify(def)})` : ''}`,
168
+ detail: request
169
+ ? (def !== undefined
170
+ ? `Clients that don't send it get the default ${JSON.stringify(def)}.`
171
+ : `Existing clients don't send \`${last.prop}\`: the server must pick a value when it is missing (add a \`default\` to document it).`)
172
+ : 'Clients never relied on it being present. Making it required in a response does not break readers; this keeps the gate green.',
173
+ ops: holders.map((h) => ({ op: 'pull', path: [...h, 'required'], value: last.prop })),
174
+ changes: [c],
175
+ transforms: request && def !== undefined
176
+ ? [{ ...where(c), side: 'request', kind: 'default', parent: parsed.steps.slice(0, -1), field: last.prop, value: def }]
177
+ : [],
178
+ };
179
+ }
180
+
181
+ function revertFieldType(c, { base, target, deprecate }) {
182
+ const parsed = L.parseField(c.field);
183
+ const basePtr = L.fieldPtr(base, c.method, c.path, c.field);
184
+ const targetPtr = L.fieldPtr(target, c.method, c.path, c.field);
185
+ if (!parsed || !basePtr || !targetPtr) return null;
186
+ const last = parsed.steps[parsed.steps.length - 1];
187
+ const request = parsed.side === 'request';
188
+ const oldNode = L.get(base, basePtr);
189
+ const ops = [{ op: 'set', path: targetPtr, value: oldNode }, ...missingRefs(base, target, [oldNode])];
190
+ const label = last.prop !== undefined ? `\`${last.prop}\`` : `"${c.field}"`;
191
+
192
+ // integer → integer:int64 is a format change, not a new kind of value:
193
+ // keep the old format, no new field, nothing for a version layer to do.
194
+ const kind = (t) => String(t || '').split(':')[0];
195
+ if (kind(c.oldValue) === kind(c.newValue)) {
196
+ return {
197
+ strategy: 'keep-old-format',
198
+ title: `Keep the format of ${label} as ${c.oldValue}`,
199
+ detail: `Generated clients map ${c.oldValue} and ${c.newValue} to different types. If the values really outgrew ${c.oldValue}, publish the wider field under a new name.`,
200
+ ops, changes: [c], transforms: [],
201
+ };
202
+ }
203
+
204
+ let added = null;
205
+ if (!request && last.prop !== undefined) {
206
+ // Expand: the new type moves to a new field next to the old one.
207
+ added = newFieldName(last.prop);
208
+ const holder = targetPtr.slice(0, -2);
209
+ if (!L.get(target, [...holder, 'properties', added])) {
210
+ ops.push({ op: 'set', path: [...holder, 'properties', added], value: clone(L.get(target, targetPtr)) });
211
+ }
212
+ ops[0] = { op: 'set', path: targetPtr, value: deprecate(clone(oldNode), `Use \`${added}\` (${c.newValue}) instead.`) };
213
+ }
214
+ const convertible = scalar(c.oldValue) && scalar(c.newValue);
215
+ return {
216
+ strategy: request ? 'accept-old-type' : 'keep-old-type-add-new-field',
217
+ title: request
218
+ ? `Keep ${label} as ${c.oldValue}`
219
+ : `Keep ${label} as ${c.oldValue}; return the ${c.newValue} value as \`${added || '<new field>'}\``,
220
+ detail: request
221
+ ? `Changing a request field's type rejects existing clients. Accept ${c.oldValue} and convert on the server, or add the ${c.newValue} value as a new field.`
222
+ : `Old clients keep parsing ${label} as ${c.oldValue}; new clients read \`${added}\`.`,
223
+ ops: added || request ? ops : ops.slice(0, 1),
224
+ changes: [c],
225
+ transforms: convertible
226
+ ? [{ ...where(c), side: parsed.side, kind: 'convert', steps: parsed.steps,
227
+ from: request ? c.oldValue : c.newValue, to: request ? c.newValue : c.oldValue }]
228
+ : [],
229
+ };
230
+ }
231
+
232
+ function restoreEnumValue(c, { base, target, enumRenames }) {
233
+ const ptr = enumPtr(target, c);
234
+ if (!ptr) return null;
235
+ const value = enumValue(base, c);
236
+ if (value === undefined) return null;
237
+ const renamedTo = enumRenames.get(`${c.method} ${c.path} ${c.field} ${c.oldValue}`);
238
+ const parsed = c.field.startsWith('parameters.') ? null : L.parseField(c.field);
239
+ const side = parsed ? parsed.side : 'request';
240
+ return {
241
+ strategy: 'restore-enum-value',
242
+ title: `Keep "${value}" as an allowed value of ${c.field.replace(/^(requestBody|responses\.\w+)\./, '')}` +
243
+ (renamedTo !== undefined ? ` (renamed to "${renamedTo}")` : ''),
244
+ detail: side === 'request'
245
+ ? `Existing clients still send "${value}"; the server must accept it${renamedTo !== undefined ? ` as "${renamedTo}"` : ''}.`
246
+ : `Old clients may not know ${renamedTo !== undefined ? `"${renamedTo}"` : 'the new values'}; keep "${value}" listed while you migrate them.`,
247
+ ops: [{ op: 'push', path: [...ptr, 'enum'], value }],
248
+ changes: [c],
249
+ transforms: renamedTo !== undefined && parsed
250
+ ? [{ ...where(c), side, kind: 'enum', steps: parsed.steps,
251
+ from: side === 'request' ? value : renamedTo, to: side === 'request' ? renamedTo : value }]
252
+ : [],
253
+ };
254
+ }
255
+
256
+ function bodyShapeChanged(c, ctx) {
257
+ const { base, target } = ctx;
258
+ const parsed = L.parseField(c.field);
259
+ if (!parsed) return null;
260
+ // Below the root this is a field whose type changed (the engine reports it
261
+ // twice); it gets the same fix, which mergeIdentical folds together.
262
+ if (parsed.steps.length > 0) return revertFieldType(c, ctx);
263
+ // A list response wrapped into an envelope: { data: [...] } where it was [...].
264
+ const bPtr = L.fieldPtr(base, c.method, c.path, c.field);
265
+ const bNode = bPtr && L.get(base, L.derefPtr(base, bPtr));
266
+ const tPtr = L.fieldPtr(target, c.method, c.path, c.field);
267
+ const tNode = tPtr && L.get(target, L.derefPtr(target, tPtr));
268
+ const wrapper = parsed.side === 'response' && bNode && bNode.type === 'array' && tNode
269
+ ? envelopeProperty(target, tPtr) : null;
270
+ if (!wrapper) return none(c, 'the body changed shape: this needs a new API version (see --spring for a version layer)');
271
+ // Changes inside the list's items aren't reported once the root changed
272
+ // type; diff the old list against the new `wrapper` property to find them.
273
+ const tProp = L.derefPtr(target, [...L.derefPtr(target, tPtr), 'properties', wrapper]);
274
+ const inner = ctx.nested
275
+ ? ctx.nested(mini(base, bNode), mini(target, L.get(target, tProp)))
276
+ // Applied after the unwrap, when the list is the root again: the
277
+ // nested steps ([items].…) are already right.
278
+ .map((t) => ({ ...t, ...where(c) }))
279
+ : [];
280
+ return {
281
+ strategy: null,
282
+ reason: `the list moved into \`${wrapper}\` — one schema can't describe both shapes, so this needs a version layer (--spring)`,
283
+ ops: [],
284
+ changes: [c],
285
+ transforms: [{ ...where(c), side: 'response', kind: 'unwrap', property: wrapper }, ...inner],
286
+ };
287
+ }
288
+
289
+ /** A one-operation spec around `schema`, sharing the document's components. */
290
+ function mini(doc, schema) {
291
+ const out = { openapi: '3.0.3', info: { title: 'nested', version: '0' },
292
+ paths: { '/_': { get: { responses: { 200: { description: '', content: { 'application/json': { schema } } } } } } } };
293
+ if (doc.components) out.components = doc.components;
294
+ if (doc.definitions) out.definitions = doc.definitions;
295
+ return out;
296
+ }
297
+
298
+ // ─── parameters ─────────────────────────────────────────────────────────────
299
+
300
+ function restoreParameter(c, { base, target, deprecate }) {
301
+ const name = c.field.replace(/^parameters\./, '');
302
+ const bp = L.findParameter(base, c.method, c.path, name);
303
+ const op = L.operationPtr(target, c.method, c.path);
304
+ if (!bp || !op) return null;
305
+ const value = deprecate(clone(bp.node));
306
+ value.required = value.in === 'path' ? true : false;
307
+ return {
308
+ strategy: 'restore-deprecated-parameter',
309
+ title: `Keep accepting the ${bp.node.in} parameter \`${name}\`, marked deprecated`,
310
+ detail: `Existing clients still send \`${name}\`; the server must accept it (it may ignore it).`,
311
+ ops: [{ op: 'push', path: [...op, 'parameters'], value }, ...missingRefs(base, target, [bp.node])],
312
+ changes: [c], transforms: [],
313
+ };
314
+ }
315
+
316
+ function parameterOptional(c, { target }) {
317
+ const name = c.field.replace(/^parameters\./, '');
318
+ const tp = L.findParameter(target, c.method, c.path, name);
319
+ if (!tp || tp.node.in === 'path') return null;
320
+ const def = tp.node.schema ? tp.node.schema.default : tp.node.default;
321
+ return {
322
+ strategy: 'make-optional',
323
+ title: `Make the ${tp.node.in} parameter \`${name}\` optional${def !== undefined ? ` (default ${JSON.stringify(def)})` : ''}`,
324
+ detail: def !== undefined
325
+ ? `Clients that don't send it get the default ${JSON.stringify(def)}.`
326
+ : `Existing clients don't send \`${name}\`: the server must pick a value when it is missing.`,
327
+ ops: [{ op: 'set', path: [...tp.ptr, 'required'], value: false }],
328
+ changes: [c], transforms: [],
329
+ };
330
+ }
331
+
332
+ function revertParameterType(c, { base, target }) {
333
+ const name = c.field.replace(/^parameters\./, '');
334
+ const bp = L.findParameter(base, c.method, c.path, name);
335
+ const tp = L.findParameter(target, c.method, c.path, name);
336
+ if (!bp || !tp) return null;
337
+ const ops = [];
338
+ if (bp.node.schema) ops.push({ op: 'set', path: [...tp.ptr, 'schema'], value: bp.node.schema });
339
+ for (const k of ['type', 'format', 'items', 'enum']) {
340
+ if (bp.node[k] !== undefined) ops.push({ op: 'set', path: [...tp.ptr, k], value: bp.node[k] });
341
+ else if (tp.node[k] !== undefined) ops.push({ op: 'delete', path: [...tp.ptr, k] });
342
+ }
343
+ return {
344
+ strategy: 'accept-old-type',
345
+ title: `Keep the parameter \`${name}\` as ${c.oldValue}`,
346
+ detail: `Existing clients send ${c.oldValue}. Parse it on the server, or add the ${c.newValue} value as a new parameter.`,
347
+ ops: [...ops, ...missingRefs(base, target, [bp.node])],
348
+ changes: [c], transforms: [],
349
+ };
350
+ }
351
+
352
+ // ─── variants, discriminators ───────────────────────────────────────────────
353
+
354
+ function restoreVariant(c, { base, target }) {
355
+ const m = /^(.*)\.(oneOf|anyOf)\[(\d+)\]$/.exec(c.field);
356
+ if (!m) return null;
357
+ const basePtr = L.fieldPtr(base, c.method, c.path, c.field);
358
+ const holder = L.fieldPtr(target, c.method, c.path, m[1]);
359
+ if (!basePtr || !holder) return null;
360
+ const owner = L.derefPtr(target, holder);
361
+ return {
362
+ strategy: 'restore-variant',
363
+ title: `Keep the removed ${m[2]} variant #${Number(m[3]) + 1}`,
364
+ detail: 'Clients may still send or receive that shape.',
365
+ ops: [{ op: 'insert', path: [...owner, m[2]], index: Number(m[3]), value: L.get(base, basePtr) },
366
+ ...missingRefs(base, target, [L.get(base, basePtr)])],
367
+ changes: [c], transforms: [],
368
+ };
369
+ }
370
+
371
+ function revertDiscriminator(c, { base, target }) {
372
+ const prefix = c.field.replace(/\.discriminator$/, '');
373
+ const bPtr = L.fieldPtr(base, c.method, c.path, prefix);
374
+ const tPtr = L.fieldPtr(target, c.method, c.path, prefix);
375
+ if (!bPtr || !tPtr) return null;
376
+ const bOwner = L.derefPtr(base, bPtr);
377
+ const tOwner = L.derefPtr(target, tPtr);
378
+ const value = L.get(base, [...bOwner, 'discriminator']);
379
+ return {
380
+ strategy: 'revert-discriminator',
381
+ title: `Keep "${c.oldValue}" as the discriminator`,
382
+ detail: 'Clients pick the variant by that property name.',
383
+ ops: [{ op: 'set', path: [...tOwner, 'discriminator'], value }],
384
+ changes: [c], transforms: [],
385
+ };
386
+ }
387
+
388
+ // ─── renames ────────────────────────────────────────────────────────────────
389
+
390
+ /**
391
+ * A field removed and another added under the same parent, with the same
392
+ * type and a related name (a shared word), is a rename: `status` →
393
+ * `paymentStatus`. Only an unambiguous pair counts. Being the only field of
394
+ * that type is not enough: on GitHub's real API history that matched
395
+ * `budget_type` → `expires_at`, and the Spring layer would have copied one
396
+ * field's data into an unrelated one.
397
+ */
398
+ function detectRenames(rawDiffs, baseNorm, targetNorm) {
399
+ const groups = new Map();
400
+ for (const d of rawDiffs) {
401
+ if (!/^(REQUEST|RESPONSE)_FIELD_(REMOVED|ADDED)$|^REQUEST_REQUIRED_FIELD_ADDED$/.test(d.type)) continue;
402
+ const parsed = L.parseField(d.field);
403
+ const last = parsed && parsed.steps[parsed.steps.length - 1];
404
+ if (!last || last.prop === undefined) continue;
405
+ const parent = d.field.slice(0, d.field.length - last.prop.length - 1);
406
+ const key = `${d.method} ${d.path} ${parent}`;
407
+ if (!groups.has(key)) groups.set(key, { removed: [], added: [] });
408
+ groups.get(key)[/REMOVED$/.test(d.type) ? 'removed' : 'added'].push({ d, name: last.prop });
409
+ }
410
+ const renames = new Map();
411
+ for (const { removed, added } of groups.values()) {
412
+ for (const r of removed) {
413
+ const rType = typeKey(normNode(baseNorm, r.d.method, r.d.path, r.d.field));
414
+ if (!rType) continue;
415
+ const sameType = added.filter((a) => typeKey(normNode(targetNorm, a.d.method, a.d.path, a.d.field)) === rType);
416
+ const rivals = removed.filter((x) => typeKey(normNode(baseNorm, x.d.method, x.d.path, x.d.field)) === rType);
417
+ const related = sameType.filter((a) => relatedNames(r.name, a.name));
418
+ const relatedRivals = rivals.filter((x) => sameType.some((a) => relatedNames(x.name, a.name)));
419
+ if (related.length === 1 && relatedRivals.length === 1) renames.set(sig(r.d), related[0].name);
420
+ }
421
+ }
422
+ return renames;
423
+ }
424
+
425
+ /**
426
+ * An enum value removed and exactly one added in the same place is a renamed
427
+ * value — if the enum also kept at least one value. Single-value enums are
428
+ * constants/discriminators: on GitHub's API history, oneOf variants that
429
+ * shifted position paired 9 unrelated constants ("github_resource" → "pull").
430
+ */
431
+ function detectEnumRenames(rawDiffs, baseNorm, targetNorm) {
432
+ const out = new Map();
433
+ const seen = new Set();
434
+ for (const d of rawDiffs) {
435
+ if (d.type !== 'ENUM_VALUE_REMOVED' || seen.has(`${d.method} ${d.path} ${d.field}`)) continue;
436
+ seen.add(`${d.method} ${d.path} ${d.field}`);
437
+ const b = enumOf(baseNorm, d);
438
+ const t = enumOf(targetNorm, d);
439
+ if (!b || !t) continue;
440
+ const removed = b.filter((v) => !t.includes(v));
441
+ const added = t.filter((v) => !b.includes(v));
442
+ const kept = b.filter((v) => t.includes(v));
443
+ if (removed.length === 1 && added.length === 1 && kept.length > 0) out.set(`${d.method} ${d.path} ${d.field} ${String(removed[0])}`, added[0]);
444
+ }
445
+ return out;
446
+ }
447
+
448
+ // ─── helpers ────────────────────────────────────────────────────────────────
449
+
450
+ /**
451
+ * "status" / "paymentStatus" share "status"; "created_at" / "createdAt" the
452
+ * same words. Short and filler words don't count: on GitHub's API history
453
+ * `do_not_enforce_on_create` and `review_on_push` matched on "on".
454
+ */
455
+ const FILLER = new Set(['the', 'and', 'for', 'with', 'from', 'not', 'into', 'url', 'urls']);
456
+ function relatedNames(a, b) {
457
+ const words = (n) => n.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[\s_-]+/)
458
+ .filter((w) => w.length > 2 && !FILLER.has(w));
459
+ const wb = new Set(words(b));
460
+ return words(a).some((w) => wb.has(w));
461
+ }
462
+
463
+ function sig(c) {
464
+ return `${c.type}|${c.method || ''}|${c.path || ''}|${c.field || ''}`;
465
+ }
466
+
467
+ function where(c) {
468
+ const parsed = L.parseField(c.field);
469
+ return { method: c.method.toUpperCase(), path: c.path, code: parsed ? parsed.code : null };
470
+ }
471
+
472
+ function scalar(t) {
473
+ return ['string', 'integer', 'number', 'boolean'].includes(String(t || '').split(':')[0]);
474
+ }
475
+
476
+ /** `status` → `statusV2`, `created_at` → `created_at_v2`. */
477
+ function newFieldName(name) {
478
+ return name.includes('_') ? `${name}_v2` : `${name}V2`;
479
+ }
480
+
481
+ /** Copies the components a restored piece references that the target no longer has. */
482
+ function missingRefs(base, target, nodes) {
483
+ const ops = [];
484
+ const refs = new Map();
485
+ for (const n of nodes) L.collectRefs(base, n, refs);
486
+ for (const ptr of refs.values()) {
487
+ if (L.get(target, ptr) === undefined && L.get(base, ptr) !== undefined) {
488
+ ops.push({ op: 'set', path: ptr, value: L.get(base, ptr) });
489
+ }
490
+ }
491
+ return ops;
492
+ }
493
+
494
+ function baseRequired(base, c, name) {
495
+ const holder = L.parentObjectPtr(base, c.method, c.path, c.field);
496
+ return Boolean(holder && requiredHolders(base, holder, name).length);
497
+ }
498
+
499
+ /** The schema objects (the holder and its allOf parts) whose `required` lists `name`. */
500
+ function requiredHolders(doc, ptr, name, depth = 0, out = []) {
501
+ const s = L.derefPtr(doc, ptr);
502
+ const node = s && L.get(doc, s);
503
+ if (!node || depth > 12) return out;
504
+ if (Array.isArray(node.required) && node.required.includes(name)) out.push(s);
505
+ (node.allOf || []).forEach((_, i) => requiredHolders(doc, [...s, 'allOf', i], name, depth + 1, out));
506
+ // The diff engine looks at the composed parent; required may sit one level up.
507
+ return out;
508
+ }
509
+
510
+ function enumPtr(doc, c) {
511
+ if (c.field.startsWith('parameters.')) {
512
+ const p = L.findParameter(doc, c.method, c.path, c.field.slice('parameters.'.length));
513
+ if (!p) return null;
514
+ return p.node.schema ? L.derefPtr(doc, [...p.ptr, 'schema']) : p.ptr;
515
+ }
516
+ const ptr = L.fieldPtr(doc, c.method, c.path, c.field);
517
+ return ptr && L.derefPtr(doc, ptr);
518
+ }
519
+
520
+ function enumValue(base, c) {
521
+ const ptr = enumPtr(base, c);
522
+ const node = ptr && L.get(base, ptr);
523
+ return node && Array.isArray(node.enum) ? node.enum.find((v) => String(v) === c.oldValue) : undefined;
524
+ }
525
+
526
+ function envelopeProperty(doc, ptr) {
527
+ const s = L.derefPtr(doc, ptr);
528
+ const node = s && L.get(doc, s);
529
+ const arrays = Object.keys((node && node.properties) || {}).filter((k) => {
530
+ const p = L.get(doc, L.derefPtr(doc, [...s, 'properties', k]));
531
+ return p && p.type === 'array';
532
+ });
533
+ return arrays.length === 1 ? arrays[0] : null;
534
+ }
535
+
536
+ function normNode(norm, method, path, field) {
537
+ const op = norm.endpoints[path] && norm.endpoints[path][method.toLowerCase()];
538
+ const parsed = L.parseField(field);
539
+ if (!op || !parsed) return null;
540
+ let cur = parsed.side === 'request' ? op.requestBody : op.responses[parsed.code];
541
+ for (const s of parsed.steps) {
542
+ if (!cur) return null;
543
+ if (s.prop !== undefined) cur = cur.properties && cur.properties[s.prop];
544
+ else if (s.items) cur = cur.items;
545
+ else if (s.map) cur = cur.additionalProperties;
546
+ else cur = cur[s.variant] && cur[s.variant][s.index];
547
+ }
548
+ return cur || null;
549
+ }
550
+
551
+ function enumOf(norm, d) {
552
+ if (d.field.startsWith('parameters.')) {
553
+ const op = norm.endpoints[d.path] && norm.endpoints[d.path][d.method.toLowerCase()];
554
+ const p = op && op.parameters.find((x) => x.name === d.field.slice('parameters.'.length));
555
+ return p && p.schema && p.schema.enum;
556
+ }
557
+ const n = normNode(norm, d.method, d.path, d.field);
558
+ return n && n.enum;
559
+ }
560
+
561
+ /** Type identity for rename detection. Enum values are left out: a renamed field may gain or lose values too. */
562
+ function typeKey(n) {
563
+ if (!n) return null;
564
+ return [n.type, n.format || '', n.items ? typeKey(n.items) : ''].join('|');
565
+ }
566
+
567
+ /** Operations whose request or response body root changed type: "GET /x response 200". */
568
+ function reshapedBodies(rawDiffs) {
569
+ const out = new Set();
570
+ for (const d of rawDiffs) {
571
+ if (d.type !== 'REQUEST_TYPE_CHANGED' && d.type !== 'RESPONSE_TYPE_CHANGED') continue;
572
+ const parsed = L.parseField(d.field);
573
+ if (parsed && parsed.steps.length === 0) out.add(`${d.method} ${d.path} ${parsed.side} ${parsed.code}`);
574
+ }
575
+ return out;
576
+ }
577
+
578
+ module.exports = { suggest, detectRenames, detectEnumRenames, reshapedBodies, sig, STRATEGIES };
@@ -38,20 +38,25 @@ function formatHuman(result) {
38
38
  lines.push(` ${chalk.gray('from:')} ${chalk.red(c.oldValue)} ${chalk.gray('→')} ${chalk.green(c.newValue)}`);
39
39
  }
40
40
  if (c.impact) lines.push(...formatImpact(c, { detailed: true }));
41
+ if (c.deprecation) lines.push(formatDeprecation(c));
41
42
  }
43
+ lines.push(chalk.gray(' Get a non-breaking version of this change: specshield fix <base> <target>'));
42
44
  lines.push('');
43
45
  }
44
46
 
45
47
  if (unused.length > 0) {
46
48
  const w = result.usage && result.usage.window;
47
49
  lines.push(chalk.green.bold(' ✔ BREAKING BUT UNUSED — safe to ship'));
48
- lines.push(chalk.gray(` 0 calls ${w && w.from ? `between ${day(w.from)} and ${day(w.to)}` : 'in the usage window'}; these do not fail the build`));
50
+ const drained = unused.some((c) => c.deprecation && c.deprecation.drained);
51
+ lines.push(chalk.gray(` 0 calls ${w && w.from ? `between ${day(w.from)} and ${day(w.to)}` : 'in the usage window'}` +
52
+ (drained ? ` — or deprecated and quiet for ${result.usage.quietDays}+ days` : '') + '; these do not fail the build'));
49
53
  lines.push(chalk.gray(' ─────────────────────────────────────────'));
50
54
  for (const c of unused) {
51
55
  lines.push(` ${chalk.green('○')} ${c.description}`);
52
56
  if (c.impact && c.impact.basis === 'query-parameter') {
53
57
  lines.push(chalk.gray(` no client ${c.impact.parameterUse === 'omitted' ? 'omits' : 'sends'} "${c.impact.parameter}"`));
54
58
  }
59
+ if (c.deprecation) lines.push(formatDeprecation(c));
55
60
  }
56
61
  lines.push('');
57
62
  }
@@ -156,6 +161,23 @@ function formatImpact(c, { detailed }) {
156
161
  return lines;
157
162
  }
158
163
 
164
+ /** Removals only: was this deprecated in the base spec before it was removed? */
165
+ function formatDeprecation(c) {
166
+ const d = c.deprecation;
167
+ const used = c.impact && c.impact.verdict === 'used';
168
+ if (d.deprecated) {
169
+ const sunset = d.sunset ? ` (sunset ${d.sunset})` : '';
170
+ if (d.drained) {
171
+ return chalk.gray(` ↳ deprecated${sunset} · drained: last call ${day(c.impact.lastSeen)}, ${d.quietForDays} days before the newest log line`);
172
+ }
173
+ return used
174
+ ? chalk.yellow(` ↳ deprecated${sunset}, but still called — tell the clients above before removing it`)
175
+ : chalk.gray(` ↳ deprecated${sunset} and unused — removal is the planned last step`);
176
+ }
177
+ return chalk.yellow(' ↳ removed without being deprecated first — callers got no warning' +
178
+ (used ? '. Mark it `deprecated: true` and watch it drain: specshield deprecations' : ''));
179
+ }
180
+
159
181
  function scope(i) {
160
182
  if (i.basis !== 'query-parameter') return '';
161
183
  return i.parameterUse === 'omitted'