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.
- package/CHANGELOG.md +58 -1
- package/README.md +186 -1
- package/package.json +3 -2
- package/src/api/bdctClient.js +8 -0
- package/src/cli.js +4 -0
- package/src/commands/compare.js +7 -1
- package/src/commands/deprecations.js +236 -0
- package/src/commands/fix.js +173 -0
- package/src/core/classifyChanges.js +1 -1
- package/src/core/configLoader.js +6 -1
- 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/outputFormatter.js +23 -1
- package/src/core/usage/deprecations.js +438 -0
- package/src/core/usage/impact.js +42 -24
- package/src/core/usage/usageStore.js +32 -5
|
@@ -0,0 +1,438 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { indexUsage, downgradeBlocker, isObjectSchema, compileClientPatterns, BODYLESS_METHODS } = require('./impact');
|
|
4
|
+
const { resolveSchema } = require('../normalizeSpec');
|
|
5
|
+
const { weekOf } = require('./usageStore');
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Safe-removal workflow: deprecate → watch traffic drain → remove.
|
|
9
|
+
*
|
|
10
|
+
* collectDeprecations() lists what the spec marks `deprecated: true` (or gives
|
|
11
|
+
* an `x-sunset` date): operations, parameters, and request/response fields.
|
|
12
|
+
* deprecationReport() joins that list to a usage file and says, per item, who
|
|
13
|
+
* still calls it and whether it is safe to remove:
|
|
14
|
+
*
|
|
15
|
+
* in-use called in the last week of the usage window
|
|
16
|
+
* quiet draining: no calls for a week or more, but not for
|
|
17
|
+
* `quietDays` yet — keep watching
|
|
18
|
+
* safe-to-remove no calls for at least `quietDays`
|
|
19
|
+
* unverifiable a body field or header: logs can't show who sends or reads
|
|
20
|
+
* it, and the endpoint is still called
|
|
21
|
+
* no-data the usage file can't support a verdict (stale, filtered…)
|
|
22
|
+
*
|
|
23
|
+
* A deprecated property of a shared schema (one `$ref`'d component used by
|
|
24
|
+
* many operations) is one item — `kind: 'schema-field'` — judged by the
|
|
25
|
+
* traffic of every operation that uses it. Listing it once per operation and
|
|
26
|
+
* status code turned one deprecation (Kubernetes' ObjectMeta.selfLink) into
|
|
27
|
+
* 1,700 rows on real data.
|
|
28
|
+
*
|
|
29
|
+
* Field paths match the compare engine's (`parameters.sort`,
|
|
30
|
+
* `requestBody.owner.name`, `responses.200.items[items].tag`) so a removal in
|
|
31
|
+
* compare can be tied back to its deprecation.
|
|
32
|
+
*/
|
|
33
|
+
|
|
34
|
+
const DAY = 86400e3;
|
|
35
|
+
const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
|
|
36
|
+
const MAX_DEPTH = 12;
|
|
37
|
+
const STATUS_ORDER = ['in-use', 'unverifiable', 'quiet', 'no-data', 'safe-to-remove'];
|
|
38
|
+
// A call this recent means "still in use", not "draining".
|
|
39
|
+
const ACTIVE_DAYS = 7;
|
|
40
|
+
|
|
41
|
+
function collectDeprecations(spec) {
|
|
42
|
+
const items = [];
|
|
43
|
+
const seen = new Set();
|
|
44
|
+
const push = (item) => {
|
|
45
|
+
if (seen.has(item.key)) return;
|
|
46
|
+
seen.add(item.key);
|
|
47
|
+
items.push(item);
|
|
48
|
+
};
|
|
49
|
+
const components = spec.components || {};
|
|
50
|
+
const ctx = {
|
|
51
|
+
schemas: components.schemas || spec.definitions || {},
|
|
52
|
+
parameters: components.parameters || spec.parameters || {},
|
|
53
|
+
responses: components.responses || spec.responses || {},
|
|
54
|
+
requestBodies: components.requestBodies || {},
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
for (const [path, pathItem] of Object.entries(spec.paths || {})) {
|
|
58
|
+
if (!pathItem || typeof pathItem !== 'object') continue;
|
|
59
|
+
for (const m of HTTP_METHODS) {
|
|
60
|
+
const op = pathItem[m];
|
|
61
|
+
if (!op || typeof op !== 'object') continue;
|
|
62
|
+
const method = m.toUpperCase();
|
|
63
|
+
const base = { method, path };
|
|
64
|
+
|
|
65
|
+
if (isDeprecated(op)) {
|
|
66
|
+
// Everything under a deprecated operation goes with it — listing its
|
|
67
|
+
// fields too would only repeat the same callers.
|
|
68
|
+
push({ ...base, key: `${method} ${path}`, kind: 'operation', field: null, sunset: sunsetOf(op), summary: op.summary || null });
|
|
69
|
+
continue;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
let body = null;
|
|
73
|
+
for (const p of mergeParameters(pathItem.parameters, op.parameters, ctx)) {
|
|
74
|
+
if (p.in === 'body') { body = p.schema || null; continue; } // Swagger 2.0
|
|
75
|
+
if (!isDeprecated(p)) continue;
|
|
76
|
+
push({
|
|
77
|
+
...base, key: `${method} ${path} parameters.${p.name}`, kind: 'parameter',
|
|
78
|
+
field: `parameters.${p.name}`, in: p.in, name: p.name, sunset: sunsetOf(p),
|
|
79
|
+
objectSchema: p.in === 'query' && isObjectSchema(paramSchema(p, ctx)),
|
|
80
|
+
});
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
const requestBody = deref(op.requestBody, ctx.requestBodies, '#/components/requestBodies/');
|
|
84
|
+
if (requestBody && requestBody.content) body = mediaSchema(requestBody.content);
|
|
85
|
+
if (body) walkSchema(body, 'requestBody', { ...base, kind: 'request-field' }, ctx, push, [], null);
|
|
86
|
+
|
|
87
|
+
for (const [code, raw] of Object.entries(op.responses || {})) {
|
|
88
|
+
const resp = deref(raw, ctx.responses, '#/components/responses/', '#/responses/');
|
|
89
|
+
if (!resp) continue;
|
|
90
|
+
const schema = resp.schema || (resp.content ? mediaSchema(resp.content) : null);
|
|
91
|
+
if (schema) walkSchema(schema, `responses.${code}`, { ...base, kind: 'response-field' }, ctx, push, [], null);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
return items;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* `origin` names where a property is declared, independent of the operation:
|
|
100
|
+
* "Pet.owner.phone" for a property reached through the Pet component. Null
|
|
101
|
+
* for inline schemas, which belong to their one operation.
|
|
102
|
+
*/
|
|
103
|
+
function walkSchema(raw, prefix, base, ctx, push, refStack, origin) {
|
|
104
|
+
if (!raw || typeof raw !== 'object' || refStack.length > MAX_DEPTH) return;
|
|
105
|
+
let schema = raw;
|
|
106
|
+
let stack = refStack;
|
|
107
|
+
if (raw.$ref) {
|
|
108
|
+
if (refStack.includes(raw.$ref)) return; // recursive schema
|
|
109
|
+
schema = deref(raw, ctx.schemas, '#/components/schemas/', '#/definitions/');
|
|
110
|
+
if (!schema) return;
|
|
111
|
+
stack = [...refStack, raw.$ref];
|
|
112
|
+
origin = schemaName(raw.$ref);
|
|
113
|
+
}
|
|
114
|
+
const sub = (suffix) => (origin ? `${origin}${suffix}` : null);
|
|
115
|
+
for (const part of schema.allOf || []) walkSchema(part, prefix, base, ctx, push, stack, origin);
|
|
116
|
+
for (const key of ['oneOf', 'anyOf']) {
|
|
117
|
+
(schema[key] || []).forEach((v, i) => walkSchema(v, `${prefix}[${i}]`, base, ctx, push, stack, sub(`[${i}]`)));
|
|
118
|
+
}
|
|
119
|
+
for (const [name, prop] of Object.entries(schema.properties || {})) {
|
|
120
|
+
const field = `${prefix}.${name}`;
|
|
121
|
+
const resolved = prop && prop.$ref ? deref(prop, ctx.schemas, '#/components/schemas/', '#/definitions/') : prop;
|
|
122
|
+
// `deprecated` beside a $ref is how 3.1 marks a referenced property; on the
|
|
123
|
+
// target schema it marks every use of it.
|
|
124
|
+
if (isDeprecated(prop) || isDeprecated(resolved)) {
|
|
125
|
+
push({
|
|
126
|
+
...base, key: `${base.method} ${base.path} ${field}`, field, sunset: sunsetOf(prop) || sunsetOf(resolved),
|
|
127
|
+
origin: isDeprecated(prop) ? sub(`.${name}`) : schemaName(prop.$ref),
|
|
128
|
+
});
|
|
129
|
+
continue;
|
|
130
|
+
}
|
|
131
|
+
walkSchema(prop, field, base, ctx, push, stack, sub(`.${name}`));
|
|
132
|
+
}
|
|
133
|
+
if (schema.items) walkSchema(schema.items, `${prefix}[items]`, base, ctx, push, stack, sub('[items]'));
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* Folds the per-operation occurrences of a shared-schema property into one
|
|
138
|
+
* 'schema-field' item. A property used by a single operation stays as it is.
|
|
139
|
+
*/
|
|
140
|
+
function groupDeprecations(occurrences) {
|
|
141
|
+
const groups = new Map();
|
|
142
|
+
const out = [];
|
|
143
|
+
for (const o of occurrences) {
|
|
144
|
+
if (!o.origin) { out.push(o); continue; }
|
|
145
|
+
let g = groups.get(o.origin);
|
|
146
|
+
if (!g) {
|
|
147
|
+
g = { key: `schema ${o.origin}`, kind: 'schema-field', method: null, path: null, field: o.origin,
|
|
148
|
+
sunset: o.sunset, occurrences: [], first: o };
|
|
149
|
+
groups.set(o.origin, g);
|
|
150
|
+
out.push(g);
|
|
151
|
+
}
|
|
152
|
+
g.occurrences.push({ method: o.method, path: o.path, field: o.field, side: o.kind === 'request-field' ? 'request' : 'response' });
|
|
153
|
+
}
|
|
154
|
+
return out.map((i) => {
|
|
155
|
+
if (i.kind !== 'schema-field') return i;
|
|
156
|
+
const { first, ...g } = i;
|
|
157
|
+
return new Set(g.occurrences.map((o) => `${o.method} ${o.path}`)).size === 1 && g.occurrences.length === 1 ? first : g;
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Joins the deprecations of `spec` to a usage file. Without usage, every item
|
|
163
|
+
* is 'no-data' — the report then only lists what is deprecated.
|
|
164
|
+
*/
|
|
165
|
+
function deprecationReport({
|
|
166
|
+
spec, usage = null, file = 'usage.json', quietDays = 30, ignoreClients = [],
|
|
167
|
+
maxAgeDays = 30, minCoverage = 25, contacts = {}, now = Date.now(),
|
|
168
|
+
}) {
|
|
169
|
+
const items = groupDeprecations(collectDeprecations(spec));
|
|
170
|
+
const contactOf = compileContacts(contacts);
|
|
171
|
+
let meta = null;
|
|
172
|
+
let opIndex = new Map();
|
|
173
|
+
let blocker = 'no usage file was given (--usage)';
|
|
174
|
+
|
|
175
|
+
if (usage) {
|
|
176
|
+
({ opIndex, meta } = indexUsage(usage, spec, { file, ignoreClients, now }));
|
|
177
|
+
blocker = downgradeBlocker(meta, { downgrade: true, minDays: 0, maxAgeDays, minCoverage });
|
|
178
|
+
}
|
|
179
|
+
const to = meta && meta.window.to ? Date.parse(meta.window.to) : null;
|
|
180
|
+
const activeSince = to !== null ? to - Math.min(ACTIVE_DAYS, quietDays) * DAY : null;
|
|
181
|
+
|
|
182
|
+
const out = items.map((item) => {
|
|
183
|
+
const judged = judge(item, opIndex, { activeSince, to, meta, quietDays, blocker });
|
|
184
|
+
const { objectSchema, origin, ...rest } = item;
|
|
185
|
+
const r = { ...rest, ...judged };
|
|
186
|
+
r.clients = r.clients.map((c) => ({ ...c, contact: contactOf(c.id) }));
|
|
187
|
+
const sunsetMs = item.sunset ? Date.parse(item.sunset) : NaN;
|
|
188
|
+
if (!Number.isNaN(sunsetMs)) {
|
|
189
|
+
r.daysToSunset = Math.ceil((sunsetMs - now) / DAY);
|
|
190
|
+
r.pastSunset = r.daysToSunset < 0 && (r.status === 'in-use' || r.status === 'unverifiable');
|
|
191
|
+
}
|
|
192
|
+
return r;
|
|
193
|
+
}).sort((a, b) =>
|
|
194
|
+
STATUS_ORDER.indexOf(a.status) - STATUS_ORDER.indexOf(b.status) ||
|
|
195
|
+
(b.pastSunset === true) - (a.pastSunset === true) ||
|
|
196
|
+
b.calls - a.calls || a.key.localeCompare(b.key));
|
|
197
|
+
|
|
198
|
+
const summary = { total: out.length, pastSunset: out.filter((i) => i.pastSunset).length };
|
|
199
|
+
for (const s of STATUS_ORDER) summary[camel(s)] = out.filter((i) => i.status === s).length;
|
|
200
|
+
|
|
201
|
+
return {
|
|
202
|
+
api: { title: (spec.info && spec.info.title) || null, version: (spec.info && spec.info.version) || null },
|
|
203
|
+
quietDays,
|
|
204
|
+
usage: meta ? { ...meta, evidence: blocker === null ? 'ok' : blocker } : null,
|
|
205
|
+
summary,
|
|
206
|
+
items: out,
|
|
207
|
+
};
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/** The operations whose callers an item is judged by, each once. */
|
|
211
|
+
function operationsOf(item) {
|
|
212
|
+
if (item.kind !== 'schema-field') {
|
|
213
|
+
// A GET carries no request body: nobody can be sending the field.
|
|
214
|
+
if (item.kind === 'request-field' && BODYLESS_METHODS.has(item.method)) return [];
|
|
215
|
+
return [`${item.method} ${item.path}`];
|
|
216
|
+
}
|
|
217
|
+
const ops = new Set();
|
|
218
|
+
for (const o of item.occurrences) {
|
|
219
|
+
if (o.side === 'request' && BODYLESS_METHODS.has(o.method)) continue;
|
|
220
|
+
ops.add(`${o.method} ${o.path}`);
|
|
221
|
+
}
|
|
222
|
+
return [...ops];
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
function judge(item, opIndex, { activeSince, to, meta, quietDays, blocker }) {
|
|
226
|
+
const ops = operationsOf(item);
|
|
227
|
+
const sources = ops.map((op) => opIndex.get(op)).filter(Boolean);
|
|
228
|
+
// Logs record the query string, so a scalar query parameter is judged by who
|
|
229
|
+
// sends it. Header/cookie/path params and body fields are judged by who
|
|
230
|
+
// calls the endpoint, which can only ever clear them, never convict them.
|
|
231
|
+
const byParam = item.kind === 'parameter' && item.in === 'query' && !item.objectSchema &&
|
|
232
|
+
!sources.some((byClient) => [...byClient.values()].some((c) => c.paramsTruncated));
|
|
233
|
+
const exact = item.kind === 'operation' || byParam;
|
|
234
|
+
|
|
235
|
+
const byId = new Map();
|
|
236
|
+
const weeks = {};
|
|
237
|
+
for (const byClient of sources) {
|
|
238
|
+
for (const [id, c] of byClient) {
|
|
239
|
+
const calls = byParam ? c.params[item.name] || 0 : c.calls;
|
|
240
|
+
if (calls <= 0) continue;
|
|
241
|
+
const seen = byParam ? c.paramsLastSeen[item.name] ?? c.lastSeen : c.lastSeen;
|
|
242
|
+
const agg = byId.get(id) || { id, calls: 0, lastSeen: null };
|
|
243
|
+
agg.calls += calls;
|
|
244
|
+
if (seen !== null && (agg.lastSeen === null || seen > agg.lastSeen)) agg.lastSeen = seen;
|
|
245
|
+
byId.set(id, agg);
|
|
246
|
+
// Weekly counts are per endpoint: they describe a parameter's senders
|
|
247
|
+
// only as "callers of the endpoint", so parameters get none.
|
|
248
|
+
if (!byParam) for (const [w, n] of Object.entries(c.weeks)) weeks[w] = (weeks[w] || 0) + n;
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
const clients = [...byId.values()]
|
|
252
|
+
.map((c) => ({ id: c.id, calls: c.calls, lastSeen: c.lastSeen === null ? null : new Date(c.lastSeen).toISOString() }))
|
|
253
|
+
.sort((a, b) => b.calls - a.calls || a.id.localeCompare(b.id));
|
|
254
|
+
const calls = clients.reduce((n, c) => n + c.calls, 0);
|
|
255
|
+
const lastSeen = clients.reduce((t, c) => (c.lastSeen && (!t || c.lastSeen > t) ? c.lastSeen : t), null);
|
|
256
|
+
const recent = clients.filter((c) => c.lastSeen && Date.parse(c.lastSeen) >= activeSince);
|
|
257
|
+
const hasWeeks = Object.keys(weeks).length > 0; // usage files before 3.4.15 have none
|
|
258
|
+
|
|
259
|
+
const r = {
|
|
260
|
+
...(item.kind === 'schema-field' ? { operations: ops.length } : {}),
|
|
261
|
+
basis: exact ? (byParam ? 'query-parameter' : 'operation') : 'endpoint',
|
|
262
|
+
calls,
|
|
263
|
+
lastSeen,
|
|
264
|
+
clients,
|
|
265
|
+
weeks: hasWeeks ? weekSeries(weeks, meta.window) : [],
|
|
266
|
+
};
|
|
267
|
+
|
|
268
|
+
if (blocker !== null) return { ...r, status: 'no-data', reason: blocker };
|
|
269
|
+
if (recent.length > 0) {
|
|
270
|
+
if (exact) {
|
|
271
|
+
return { ...r, status: 'in-use', reason: `${plural(recent.length, 'client')} called it in the last ${Math.min(ACTIVE_DAYS, quietDays)} days` };
|
|
272
|
+
}
|
|
273
|
+
return {
|
|
274
|
+
...r, status: 'unverifiable',
|
|
275
|
+
reason: `access logs don't show ${item.kind === 'parameter' ? `the ${item.in} parameter` : 'body fields'}, ` +
|
|
276
|
+
`and ${plural(recent.length, 'client')} still ${recent.length === 1 ? 'calls' : 'call'} ` +
|
|
277
|
+
(item.kind === 'schema-field' ? `operations that use it (${ops.length})` : 'the endpoint'),
|
|
278
|
+
};
|
|
279
|
+
}
|
|
280
|
+
const quietFor = lastSeen ? (to - Date.parse(lastSeen)) / DAY : meta.days;
|
|
281
|
+
if (quietFor >= quietDays) {
|
|
282
|
+
return { ...r, status: 'safe-to-remove', quietForDays: Math.floor(quietFor), reason: lastSeen
|
|
283
|
+
? `last called ${Math.floor(quietFor)} days before the newest log line`
|
|
284
|
+
: `never called in ${Math.floor(quietFor)} days of logs` };
|
|
285
|
+
}
|
|
286
|
+
return {
|
|
287
|
+
...r, status: 'quiet', quietForDays: Math.floor(quietFor),
|
|
288
|
+
reason: `no calls for ${Math.floor(quietFor)} of the ${quietDays} days needed`,
|
|
289
|
+
};
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
/**
|
|
293
|
+
* Calls per week across the whole usage window, zero-filled so a week with no
|
|
294
|
+
* calls shows as a drop instead of vanishing. The first and last week are
|
|
295
|
+
* marked partial when the logs cover only part of them.
|
|
296
|
+
*/
|
|
297
|
+
function weekSeries(weeks, window) {
|
|
298
|
+
if (!window || !window.from || !window.to) return [];
|
|
299
|
+
const from = Date.parse(window.from);
|
|
300
|
+
const to = Date.parse(window.to);
|
|
301
|
+
const out = [];
|
|
302
|
+
for (let t = Date.parse(weekOf(from)); t <= to; t += 7 * DAY) {
|
|
303
|
+
const week = new Date(t).toISOString().slice(0, 10);
|
|
304
|
+
const entry = { week, calls: weeks[week] || 0 };
|
|
305
|
+
if (t < from || t + 7 * DAY - 1 > to) entry.partial = true;
|
|
306
|
+
out.push(entry);
|
|
307
|
+
}
|
|
308
|
+
return out.slice(-26);
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
// ─── compare integration ────────────────────────────────────────────────────
|
|
312
|
+
|
|
313
|
+
const REMOVAL_TYPES = new Set([
|
|
314
|
+
'ENDPOINT_REMOVED', 'METHOD_REMOVED', 'PARAMETER_REMOVED', 'REQUEST_FIELD_REMOVED', 'RESPONSE_FIELD_REMOVED',
|
|
315
|
+
]);
|
|
316
|
+
|
|
317
|
+
/**
|
|
318
|
+
* Marks every removal in a compare result with whether the base spec had
|
|
319
|
+
* deprecated it first: `deprecation: { deprecated, sunset?, drained? }`. A
|
|
320
|
+
* removal that skipped deprecation gave its callers no warning.
|
|
321
|
+
*
|
|
322
|
+
* Deprecation is the gate's other half: a deprecated item whose callers all
|
|
323
|
+
* stopped at least `quietDays` before the newest log line has drained, and
|
|
324
|
+
* stops failing the build like an unused change — the same verdict
|
|
325
|
+
* `specshield deprecations` gives it.
|
|
326
|
+
*/
|
|
327
|
+
function annotateDeprecations(result, baseSpec, { meta = null, quietDays = 30 } = {}) {
|
|
328
|
+
const byKey = new Map(collectDeprecations(baseSpec).map((i) => [i.key, i]));
|
|
329
|
+
const to = meta && meta.window && meta.window.to ? Date.parse(meta.window.to) : null;
|
|
330
|
+
const annotate = (c) => {
|
|
331
|
+
if (!REMOVAL_TYPES.has(c.type)) return c;
|
|
332
|
+
const item = deprecationFor(c, byKey);
|
|
333
|
+
if (!item) return { ...c, deprecation: { deprecated: false } };
|
|
334
|
+
const deprecation = { deprecated: true, sunset: item.sunset || null };
|
|
335
|
+
if (c.impact && c.impact.verdict === 'used' && c.impact.lastSeen && to !== null) {
|
|
336
|
+
const quietFor = Math.floor((to - Date.parse(c.impact.lastSeen)) / DAY);
|
|
337
|
+
if (quietFor >= quietDays) Object.assign(deprecation, { drained: true, quietForDays: quietFor });
|
|
338
|
+
}
|
|
339
|
+
return { ...c, deprecation };
|
|
340
|
+
};
|
|
341
|
+
let breakingChanges = result.breakingChanges.map(annotate);
|
|
342
|
+
let unusedBreakingChanges = (result.unusedBreakingChanges || []).map(annotate);
|
|
343
|
+
if (meta && meta.downgrade && meta.downgrade.enabled) {
|
|
344
|
+
const drained = (c) => Boolean(c.deprecation && c.deprecation.drained);
|
|
345
|
+
unusedBreakingChanges = [...unusedBreakingChanges, ...breakingChanges.filter(drained)];
|
|
346
|
+
breakingChanges = breakingChanges.filter((c) => !drained(c));
|
|
347
|
+
}
|
|
348
|
+
return { ...result, breakingChanges, unusedBreakingChanges };
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
function deprecationFor(change, byKey) {
|
|
352
|
+
const endpoints = change.path && change.method
|
|
353
|
+
? [`${change.method.toUpperCase()} ${change.path}`]
|
|
354
|
+
: (change.affectedEndpoints || []).map((e) => e.replace(/^(\S+)/, (m) => m.toUpperCase()));
|
|
355
|
+
if (endpoints.length === 0) return null;
|
|
356
|
+
const leaf = change.field ? change.field.split('.').pop() : null;
|
|
357
|
+
const found = endpoints.map((ep) => {
|
|
358
|
+
// The whole operation was deprecated: everything in it went with it.
|
|
359
|
+
if (byKey.has(ep)) return byKey.get(ep);
|
|
360
|
+
if (!change.field) return null;
|
|
361
|
+
if (byKey.has(`${ep} ${change.field}`)) return byKey.get(`${ep} ${change.field}`);
|
|
362
|
+
// A merged $ref change carries the first endpoint's field path; elsewhere
|
|
363
|
+
// the same property sits under another prefix. Match it by its leaf name.
|
|
364
|
+
for (const [key, item] of byKey) {
|
|
365
|
+
if (key.startsWith(`${ep} `) && item.field && item.field.split('.').pop() === leaf &&
|
|
366
|
+
item.field.startsWith(change.field.startsWith('requestBody') ? 'requestBody' : 'responses')) return item;
|
|
367
|
+
}
|
|
368
|
+
return null;
|
|
369
|
+
});
|
|
370
|
+
// Only "deprecated" if it was deprecated everywhere it was removed from.
|
|
371
|
+
return found.every(Boolean) ? found[0] : null;
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
// ─── spec helpers ───────────────────────────────────────────────────────────
|
|
375
|
+
|
|
376
|
+
function isDeprecated(node) {
|
|
377
|
+
return Boolean(node && typeof node === 'object' && (node.deprecated === true || node['x-deprecated'] === true || node['x-sunset']));
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
/** `x-sunset: 2026-12-31` — YAML parses an unquoted date to a Date. */
|
|
381
|
+
function sunsetOf(node) {
|
|
382
|
+
const v = node && node['x-sunset'];
|
|
383
|
+
if (!v) return null;
|
|
384
|
+
const d = v instanceof Date ? v : new Date(String(v));
|
|
385
|
+
return Number.isNaN(d.getTime()) ? String(v) : d.toISOString().slice(0, 10);
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
function schemaName(ref) {
|
|
389
|
+
return typeof ref === 'string' ? ref.slice(ref.lastIndexOf('/') + 1) : null;
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
function deref(node, table, ...prefixes) {
|
|
393
|
+
if (!node || typeof node !== 'object' || !node.$ref) return node || null;
|
|
394
|
+
for (const prefix of prefixes) {
|
|
395
|
+
if (node.$ref.startsWith(prefix)) return table[node.$ref.slice(prefix.length)] || null;
|
|
396
|
+
}
|
|
397
|
+
return null;
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
function mergeParameters(pathParams, opParams, ctx) {
|
|
401
|
+
const byKey = new Map();
|
|
402
|
+
for (const raw of [...(Array.isArray(pathParams) ? pathParams : []), ...(Array.isArray(opParams) ? opParams : [])]) {
|
|
403
|
+
const p = deref(raw, ctx.parameters, '#/components/parameters/', '#/parameters/');
|
|
404
|
+
if (p && p.name && p.in) byKey.set(`${p.in}:${p.name}`, p);
|
|
405
|
+
}
|
|
406
|
+
return [...byKey.values()];
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
function paramSchema(p, ctx) {
|
|
410
|
+
if (p.schema) return resolveSchema(p.schema, ctx.schemas);
|
|
411
|
+
return p.type ? { type: p.type } : null;
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
function mediaSchema(content) {
|
|
415
|
+
const media = content['application/json'] || Object.values(content)[0];
|
|
416
|
+
return (media && media.schema) || null;
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
/**
|
|
420
|
+
* usage.contacts: { "<client id, or * glob>": "<email, Slack channel, …>" } —
|
|
421
|
+
* first match wins. Unlike --usage-ignore-client, a pattern without * must
|
|
422
|
+
* match the whole id: "app" must not hand myapp's callers to app's owner.
|
|
423
|
+
*/
|
|
424
|
+
function compileContacts(contacts) {
|
|
425
|
+
const entries = Object.entries(contacts || {}).map(([pattern, contact]) => [
|
|
426
|
+
pattern.includes('*') ? compileClientPatterns([pattern]) : (id) => id.toLowerCase() === pattern.toLowerCase(),
|
|
427
|
+
String(contact),
|
|
428
|
+
]);
|
|
429
|
+
return (id) => {
|
|
430
|
+
for (const [test, contact] of entries) if (test(id)) return contact;
|
|
431
|
+
return null;
|
|
432
|
+
};
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
function plural(n, word) { return `${n} ${word}${n === 1 ? '' : 's'}`; }
|
|
436
|
+
function camel(s) { return s.replace(/-(\w)/g, (_, c) => c.toUpperCase()); }
|
|
437
|
+
|
|
438
|
+
module.exports = { collectDeprecations, groupDeprecations, deprecationReport, annotateDeprecations, STATUS_ORDER };
|
package/src/core/usage/impact.js
CHANGED
|
@@ -42,10 +42,38 @@ function applyUsageImpact(result, opts) {
|
|
|
42
42
|
downgrade = true, now = Date.now(),
|
|
43
43
|
} = opts;
|
|
44
44
|
|
|
45
|
+
const { opIndex, meta } = indexUsage(usage, baseSpec, { file, ignoreClients, now });
|
|
46
|
+
|
|
47
|
+
const blocker = downgradeBlocker(meta, { downgrade, minDays, maxAgeDays, minCoverage });
|
|
48
|
+
meta.downgrade = { enabled: blocker === null, reason: blocker };
|
|
49
|
+
|
|
50
|
+
const ctx = { opIndex, baseSpec, baseNorm, trusted: meta.trusted };
|
|
51
|
+
const annotate = (c) => (meta.trusted ? { ...c, impact: computeImpact(c, ctx) } : c);
|
|
52
|
+
|
|
53
|
+
let breakingChanges = result.breakingChanges.map(annotate);
|
|
54
|
+
const warnings = result.warnings.map(annotate);
|
|
55
|
+
let unusedBreakingChanges = [];
|
|
56
|
+
|
|
57
|
+
if (meta.downgrade.enabled) {
|
|
58
|
+
unusedBreakingChanges = breakingChanges.filter((c) => c.impact && c.impact.verdict === 'unused');
|
|
59
|
+
breakingChanges = breakingChanges.filter((c) => !(c.impact && c.impact.verdict === 'unused'));
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
return {
|
|
63
|
+
result: { ...result, breakingChanges, warnings, unusedBreakingChanges },
|
|
64
|
+
meta,
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Maps a usage file onto the operations of `spec`:
|
|
70
|
+
* opIndex "GET /orders/{id}" → Map(clientId → { calls, lastSeen, params, paramsLastSeen, weeks, paramsTruncated })
|
|
71
|
+
* meta window, totals, coverage — the evidence the downgrade guards judge
|
|
72
|
+
*/
|
|
73
|
+
function indexUsage(usage, spec, { file = 'usage.json', ignoreClients = [], now = Date.now() } = {}) {
|
|
45
74
|
const ignore = compileClientPatterns(ignoreClients);
|
|
46
|
-
const matcher = createRouteMatcher(
|
|
75
|
+
const matcher = createRouteMatcher(spec, { basePath: usage.basePath });
|
|
47
76
|
|
|
48
|
-
// "GET /orders/{id}" → Map(clientId → { calls, lastSeen, params, paramsTruncated })
|
|
49
77
|
const opIndex = new Map();
|
|
50
78
|
let totalCalls = 0;
|
|
51
79
|
let matchedCalls = 0;
|
|
@@ -63,11 +91,17 @@ function applyUsageImpact(result, opts) {
|
|
|
63
91
|
const key = `${m.method} ${m.template}`;
|
|
64
92
|
if (!opIndex.has(key)) opIndex.set(key, new Map());
|
|
65
93
|
const byClient = opIndex.get(key);
|
|
66
|
-
const agg = byClient.get(c.id) ||
|
|
94
|
+
const agg = byClient.get(c.id) ||
|
|
95
|
+
{ calls: 0, lastSeen: null, params: {}, paramsLastSeen: {}, weeks: {}, paramsTruncated: false };
|
|
67
96
|
agg.calls += c.calls;
|
|
68
97
|
const seen = toMs(c.lastSeen);
|
|
69
98
|
if (seen !== null && (agg.lastSeen === null || seen > agg.lastSeen)) agg.lastSeen = seen;
|
|
70
99
|
for (const [name, n] of Object.entries(c.params || {})) agg.params[name] = (agg.params[name] || 0) + n;
|
|
100
|
+
for (const [name, t] of Object.entries(c.paramsLastSeen || {})) {
|
|
101
|
+
const ms = toMs(t);
|
|
102
|
+
if (ms !== null && !(agg.paramsLastSeen[name] >= ms)) agg.paramsLastSeen[name] = ms;
|
|
103
|
+
}
|
|
104
|
+
for (const [week, n] of Object.entries(c.weeks || {})) agg.weeks[week] = (agg.weeks[week] || 0) + n;
|
|
71
105
|
if (c.paramsTruncated) agg.paramsTruncated = true;
|
|
72
106
|
byClient.set(c.id, agg);
|
|
73
107
|
}
|
|
@@ -93,26 +127,7 @@ function applyUsageImpact(result, opts) {
|
|
|
93
127
|
operationsTotal: matcher.operations.length,
|
|
94
128
|
trusted: matchedCalls > 0,
|
|
95
129
|
};
|
|
96
|
-
|
|
97
|
-
const blocker = downgradeBlocker(meta, { downgrade, minDays, maxAgeDays, minCoverage });
|
|
98
|
-
meta.downgrade = { enabled: blocker === null, reason: blocker };
|
|
99
|
-
|
|
100
|
-
const ctx = { opIndex, baseSpec, baseNorm, trusted: meta.trusted };
|
|
101
|
-
const annotate = (c) => (meta.trusted ? { ...c, impact: computeImpact(c, ctx) } : c);
|
|
102
|
-
|
|
103
|
-
let breakingChanges = result.breakingChanges.map(annotate);
|
|
104
|
-
const warnings = result.warnings.map(annotate);
|
|
105
|
-
let unusedBreakingChanges = [];
|
|
106
|
-
|
|
107
|
-
if (meta.downgrade.enabled) {
|
|
108
|
-
unusedBreakingChanges = breakingChanges.filter((c) => c.impact && c.impact.verdict === 'unused');
|
|
109
|
-
breakingChanges = breakingChanges.filter((c) => !(c.impact && c.impact.verdict === 'unused'));
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
return {
|
|
113
|
-
result: { ...result, breakingChanges, warnings, unusedBreakingChanges },
|
|
114
|
-
meta,
|
|
115
|
-
};
|
|
130
|
+
return { opIndex, meta, matcher };
|
|
116
131
|
}
|
|
117
132
|
|
|
118
133
|
/** Why "zero calls" isn't strong enough evidence to stop failing the build — or null. */
|
|
@@ -256,4 +271,7 @@ function compileClientPatterns(patterns) {
|
|
|
256
271
|
function round1(n) { return Math.round(n * 10) / 10; }
|
|
257
272
|
function round3(n) { return Math.round(n * 1000) / 1000; }
|
|
258
273
|
|
|
259
|
-
module.exports = {
|
|
274
|
+
module.exports = {
|
|
275
|
+
applyUsageImpact, indexUsage, downgradeBlocker, endpointsOf, isObjectSchema, compileClientPatterns,
|
|
276
|
+
REQUEST_BODY_TYPES, BODYLESS_METHODS,
|
|
277
|
+
};
|
|
@@ -9,7 +9,8 @@ const { clientIdOf } = require('./clientIdentity');
|
|
|
9
9
|
* Aggregates request records into the usage summary written to usage.json.
|
|
10
10
|
*
|
|
11
11
|
* Only aggregates are kept: per (method, path template, client) a call count,
|
|
12
|
-
* first/last seen, and how often
|
|
12
|
+
* first/last seen, calls per week, and how often (and how recently) each
|
|
13
|
+
* query-parameter NAME was sent. Concrete
|
|
13
14
|
* paths (which carry IDs), query values, IPs and bodies are never stored — the
|
|
14
15
|
* file is safe to commit or upload.
|
|
15
16
|
*/
|
|
@@ -19,6 +20,7 @@ const VERSION = 1;
|
|
|
19
20
|
const MAX_ENDPOINTS = 5000;
|
|
20
21
|
const MAX_UNMATCHED = 500;
|
|
21
22
|
const MAX_PARAMS = 50;
|
|
23
|
+
const MAX_WEEKS = 26;
|
|
22
24
|
|
|
23
25
|
class UsageAggregator {
|
|
24
26
|
/**
|
|
@@ -87,7 +89,7 @@ class UsageAggregator {
|
|
|
87
89
|
const clientId = clientIdOf(record, this.clientSpec);
|
|
88
90
|
let c = ep.clients.get(clientId);
|
|
89
91
|
if (!c) {
|
|
90
|
-
c =
|
|
92
|
+
c = newClient();
|
|
91
93
|
ep.clients.set(clientId, c);
|
|
92
94
|
}
|
|
93
95
|
c.calls++;
|
|
@@ -96,11 +98,14 @@ class UsageAggregator {
|
|
|
96
98
|
if (c.lastSeen === null || record.time > c.lastSeen) c.lastSeen = record.time;
|
|
97
99
|
if (this.from === null || record.time < this.from) this.from = record.time;
|
|
98
100
|
if (this.to === null || record.time > this.to) this.to = record.time;
|
|
101
|
+
const week = weekOf(record.time);
|
|
102
|
+
c.weeks.set(week, (c.weeks.get(week) || 0) + 1);
|
|
99
103
|
}
|
|
100
104
|
for (const name of queryParamNames(record.query)) {
|
|
101
105
|
if (c.params.has(name)) c.params.set(name, c.params.get(name) + 1);
|
|
102
106
|
else if (c.params.size < MAX_PARAMS) c.params.set(name, 1);
|
|
103
|
-
else c.paramsTruncated = true;
|
|
107
|
+
else { c.paramsTruncated = true; continue; }
|
|
108
|
+
if (record.time !== null) c.paramsLastSeen.set(name, maxTime(c.paramsLastSeen.get(name) ?? null, record.time));
|
|
104
109
|
}
|
|
105
110
|
|
|
106
111
|
this.stats.requests++;
|
|
@@ -121,7 +126,7 @@ class UsageAggregator {
|
|
|
121
126
|
for (const ec of e.clients) {
|
|
122
127
|
let c = ep.clients.get(ec.id);
|
|
123
128
|
if (!c) {
|
|
124
|
-
c =
|
|
129
|
+
c = newClient();
|
|
125
130
|
ep.clients.set(ec.id, c);
|
|
126
131
|
}
|
|
127
132
|
c.calls += ec.calls;
|
|
@@ -132,6 +137,10 @@ class UsageAggregator {
|
|
|
132
137
|
else if (c.params.size < MAX_PARAMS) c.params.set(name, n);
|
|
133
138
|
else c.paramsTruncated = true;
|
|
134
139
|
}
|
|
140
|
+
for (const [name, t] of Object.entries(ec.paramsLastSeen || {})) {
|
|
141
|
+
if (c.params.has(name)) c.paramsLastSeen.set(name, maxTime(c.paramsLastSeen.get(name) ?? null, toMs(t)));
|
|
142
|
+
}
|
|
143
|
+
for (const [week, n] of Object.entries(ec.weeks || {})) c.weeks.set(week, (c.weeks.get(week) || 0) + n);
|
|
135
144
|
if (ec.paramsTruncated) c.paramsTruncated = true;
|
|
136
145
|
}
|
|
137
146
|
}
|
|
@@ -146,7 +155,11 @@ class UsageAggregator {
|
|
|
146
155
|
.map(([id, c]) => {
|
|
147
156
|
const out = { id, calls: c.calls, firstSeen: toIso(c.firstSeen), lastSeen: toIso(c.lastSeen) };
|
|
148
157
|
if (c.params.size > 0) out.params = Object.fromEntries([...c.params.entries()].sort((a, b) => b[1] - a[1]));
|
|
158
|
+
if (c.paramsLastSeen.size > 0) {
|
|
159
|
+
out.paramsLastSeen = Object.fromEntries([...c.paramsLastSeen.entries()].map(([n, t]) => [n, toIso(t)]));
|
|
160
|
+
}
|
|
149
161
|
if (c.paramsTruncated) out.paramsTruncated = true;
|
|
162
|
+
if (c.weeks.size > 0) out.weeks = Object.fromEntries([...c.weeks.entries()].sort().slice(-MAX_WEEKS));
|
|
150
163
|
return out;
|
|
151
164
|
})
|
|
152
165
|
.sort((a, b) => b.calls - a.calls || a.id.localeCompare(b.id));
|
|
@@ -171,6 +184,20 @@ class UsageAggregator {
|
|
|
171
184
|
}
|
|
172
185
|
}
|
|
173
186
|
|
|
187
|
+
function newClient() {
|
|
188
|
+
return {
|
|
189
|
+
calls: 0, firstSeen: null, lastSeen: null,
|
|
190
|
+
params: new Map(), paramsLastSeen: new Map(), paramsTruncated: false, weeks: new Map(),
|
|
191
|
+
};
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/** The Monday (UTC) starting the week of `ms`, as "YYYY-MM-DD" — the key of usage.json `weeks`. */
|
|
195
|
+
function weekOf(ms) {
|
|
196
|
+
const d = new Date(ms);
|
|
197
|
+
const monday = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()) - ((d.getUTCDay() + 6) % 7) * 86400e3;
|
|
198
|
+
return new Date(monday).toISOString().slice(0, 10);
|
|
199
|
+
}
|
|
200
|
+
|
|
174
201
|
/** --host values: exact host names, or globs like "*.example.com". Null = no filter. */
|
|
175
202
|
function compileHostFilter(hosts) {
|
|
176
203
|
const list = (hosts || []).filter(Boolean).map((h) => String(h).toLowerCase());
|
|
@@ -232,4 +259,4 @@ function toIso(ms) { return ms === null || ms === undefined ? null : new Date(ms
|
|
|
232
259
|
function minTime(a, b) { return a === null ? b : b === null ? a : Math.min(a, b); }
|
|
233
260
|
function maxTime(a, b) { return a === null ? b : b === null ? a : Math.max(a, b); }
|
|
234
261
|
|
|
235
|
-
module.exports = { UsageAggregator, loadUsage, validateUsage, parseDuration, toMs, FORMAT, VERSION };
|
|
262
|
+
module.exports = { UsageAggregator, loadUsage, validateUsage, parseDuration, toMs, weekOf, FORMAT, VERSION };
|