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,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 };
@@ -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(baseSpec, { basePath: usage.basePath });
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) || { calls: 0, lastSeen: null, params: {}, paramsTruncated: false };
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 = { applyUsageImpact, compileClientPatterns };
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 each query-parameter NAME was sent. Concrete
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 = { calls: 0, firstSeen: null, lastSeen: null, params: new Map(), paramsTruncated: false };
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 = { calls: 0, firstSeen: null, lastSeen: null, params: new Map(), paramsTruncated: false };
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 };