specshield 3.4.15 → 3.4.17
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.
- package/CHANGELOG.md +57 -0
- package/README.md +160 -12
- package/package.json +3 -2
- package/src/api/bdctClient.js +8 -0
- package/src/cli.js +6 -0
- package/src/commands/compare.js +2 -33
- package/src/commands/fix.js +173 -0
- package/src/commands/gate.js +307 -0
- package/src/commands/waivers.js +123 -0
- package/src/core/classifyChanges.js +1 -1
- package/src/core/configLoader.js +34 -0
- package/src/core/fix/fixSpec.js +179 -0
- package/src/core/fix/locate.js +263 -0
- package/src/core/fix/ops.js +233 -0
- package/src/core/fix/shim/spring.js +532 -0
- package/src/core/fix/shim/transforms.js +231 -0
- package/src/core/fix/strategies.js +578 -0
- package/src/core/gate/baseline.js +142 -0
- package/src/core/gate/git.js +44 -0
- package/src/core/gate/runGate.js +140 -0
- package/src/core/gate/waivers.js +270 -0
- package/src/core/outputFormatter.js +1 -0
- package/src/core/usage/applyUsage.js +63 -0
- package/src/core/usage/deprecations.js +1 -1
|
@@ -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 };
|