specshield 3.4.13 → 3.4.15

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.
@@ -3,6 +3,12 @@
3
3
  /**
4
4
  * Normalize an OpenAPI spec into a flat, consistent internal model.
5
5
  * Resolves simple $ref references from components.schemas.
6
+ *
7
+ * Swagger 2.0 is mapped onto the same model: `definitions` stand in for
8
+ * components.schemas, the `in: body` parameter becomes the request body,
9
+ * `responses.<code>.schema` is the response schema, and non-body parameters
10
+ * carry their type inline instead of under `schema`. Path-level parameters
11
+ * and `$ref` parameters/responses are resolved for both versions.
6
12
  */
7
13
  function normalizeSpec(spec) {
8
14
  if (!spec || typeof spec !== 'object') {
@@ -10,7 +16,12 @@ function normalizeSpec(spec) {
10
16
  }
11
17
 
12
18
  const components = spec.components || {};
13
- const schemas = components.schemas || {};
19
+ const schemas = components.schemas || spec.definitions || {};
20
+ const ctx = {
21
+ schemas,
22
+ parameters: components.parameters || spec.parameters || {},
23
+ responses: components.responses || spec.responses || {},
24
+ };
14
25
 
15
26
  const endpoints = {};
16
27
 
@@ -24,7 +35,7 @@ function normalizeSpec(spec) {
24
35
  for (const method of HTTP_METHODS) {
25
36
  if (!pathItem[method]) continue;
26
37
  const operation = pathItem[method];
27
- methods[method] = normalizeOperation(operation, schemas);
38
+ methods[method] = normalizeOperation(operation, pathItem.parameters, ctx);
28
39
  }
29
40
 
30
41
  if (Object.keys(methods).length > 0) {
@@ -39,25 +50,62 @@ function normalizeSpec(spec) {
39
50
  };
40
51
  }
41
52
 
42
- function normalizeOperation(operation, schemas) {
53
+ function normalizeOperation(operation, pathParams, ctx) {
54
+ const { schemas } = ctx;
55
+ const params = mergeParameters(pathParams, operation.parameters, ctx);
56
+ const body = params.find((p) => p.in === 'body'); // Swagger 2.0
43
57
  return {
44
58
  operationId: operation.operationId || null,
45
59
  summary: operation.summary || null,
46
- parameters: normalizeParameters(operation.parameters || [], schemas),
47
- requestBody: normalizeRequestBody(operation.requestBody, schemas),
48
- responses: normalizeResponses(operation.responses || {}, schemas),
60
+ parameters: normalizeParameters(params.filter((p) => p.in !== 'body'), schemas),
61
+ requestBody: body
62
+ ? (body.schema ? resolveSchema(body.schema, schemas) : null)
63
+ : normalizeRequestBody(operation.requestBody, schemas),
64
+ responses: normalizeResponses(operation.responses || {}, ctx),
49
65
  };
50
66
  }
51
67
 
68
+ /** Path-level parameters apply to every operation; an operation-level one with the same (in, name) overrides. */
69
+ function mergeParameters(pathParams, opParams, ctx) {
70
+ const byKey = new Map();
71
+ for (const raw of [...(Array.isArray(pathParams) ? pathParams : []), ...(Array.isArray(opParams) ? opParams : [])]) {
72
+ const p = derefParameter(raw, ctx);
73
+ if (!p || !p.name || !p.in) continue;
74
+ byKey.set(`${p.in}:${p.name}`, p);
75
+ }
76
+ return [...byKey.values()];
77
+ }
78
+
79
+ function derefParameter(p, ctx) {
80
+ if (!p || typeof p !== 'object' || !p.$ref) return p;
81
+ const name = refName(p.$ref, ['#/components/parameters/', '#/parameters/']);
82
+ return name ? ctx.parameters[name] || null : null;
83
+ }
84
+
52
85
  function normalizeParameters(params, schemas) {
53
86
  return params.map((p) => ({
54
87
  name: p.name,
55
88
  in: p.in,
56
89
  required: Boolean(p.required),
57
- schema: p.schema ? resolveSchema(p.schema, schemas) : null,
90
+ // Swagger 2.0 non-body parameters declare type/format/items/enum inline.
91
+ schema: p.schema
92
+ ? resolveSchema(p.schema, schemas)
93
+ : p.type ? resolveSchema(inlineParamSchema(p), schemas) : null,
58
94
  }));
59
95
  }
60
96
 
97
+ function inlineParamSchema(p) {
98
+ const { name, in: _in, required, description, collectionFormat, allowEmptyValue, ...schema } = p;
99
+ return schema;
100
+ }
101
+
102
+ function refName(ref, prefixes) {
103
+ for (const prefix of prefixes) {
104
+ if (typeof ref === 'string' && ref.startsWith(prefix)) return ref.slice(prefix.length);
105
+ }
106
+ return null;
107
+ }
108
+
61
109
  function normalizeRequestBody(requestBody, schemas) {
62
110
  if (!requestBody) return null;
63
111
  const content = requestBody.content || {};
@@ -66,10 +114,18 @@ function normalizeRequestBody(requestBody, schemas) {
66
114
  return resolveSchema(mediaType.schema, schemas);
67
115
  }
68
116
 
69
- function normalizeResponses(responses, schemas) {
117
+ function normalizeResponses(responses, ctx) {
118
+ const { schemas } = ctx;
70
119
  const result = {};
71
- for (const [statusCode, response] of Object.entries(responses)) {
120
+ for (const [statusCode, raw] of Object.entries(responses)) {
121
+ const response = raw && raw.$ref
122
+ ? ctx.responses[refName(raw.$ref, ['#/components/responses/', '#/responses/'])]
123
+ : raw;
72
124
  if (!response) continue;
125
+ if (response.schema) { // Swagger 2.0
126
+ result[statusCode] = resolveSchema(response.schema, schemas);
127
+ continue;
128
+ }
73
129
  const content = response.content || {};
74
130
  const mediaType = content['application/json'] || Object.values(content)[0];
75
131
  result[statusCode] = mediaType && mediaType.schema
@@ -96,8 +152,8 @@ function resolveSchema(schema, schemas, depth = 0) {
96
152
  if (depth > 10) return { type: 'circular' };
97
153
 
98
154
  if (schema.$ref) {
99
- const refName = schema.$ref.replace('#/components/schemas/', '');
100
- const resolved = schemas[refName];
155
+ const name = refName(schema.$ref, ['#/components/schemas/', '#/definitions/']);
156
+ const resolved = name ? schemas[name] : undefined;
101
157
  if (!resolved) return { type: 'unknown', ref: schema.$ref };
102
158
  return resolveSchema(resolved, schemas, depth + 1);
103
159
  }
@@ -38,6 +38,7 @@ function formatHuman(result) {
38
38
  lines.push(` ${chalk.gray('from:')} ${chalk.red(c.oldValue)} ${chalk.gray('→')} ${chalk.green(c.newValue)}`);
39
39
  }
40
40
  if (c.impact) lines.push(...formatImpact(c, { detailed: true }));
41
+ if (c.deprecation) lines.push(formatDeprecation(c));
41
42
  }
42
43
  lines.push('');
43
44
  }
@@ -45,13 +46,16 @@ function formatHuman(result) {
45
46
  if (unused.length > 0) {
46
47
  const w = result.usage && result.usage.window;
47
48
  lines.push(chalk.green.bold(' ✔ BREAKING BUT UNUSED — safe to ship'));
48
- lines.push(chalk.gray(` 0 calls ${w && w.from ? `between ${day(w.from)} and ${day(w.to)}` : 'in the usage window'}; these do not fail the build`));
49
+ const drained = unused.some((c) => c.deprecation && c.deprecation.drained);
50
+ lines.push(chalk.gray(` 0 calls ${w && w.from ? `between ${day(w.from)} and ${day(w.to)}` : 'in the usage window'}` +
51
+ (drained ? ` — or deprecated and quiet for ${result.usage.quietDays}+ days` : '') + '; these do not fail the build'));
49
52
  lines.push(chalk.gray(' ─────────────────────────────────────────'));
50
53
  for (const c of unused) {
51
54
  lines.push(` ${chalk.green('○')} ${c.description}`);
52
55
  if (c.impact && c.impact.basis === 'query-parameter') {
53
56
  lines.push(chalk.gray(` no client ${c.impact.parameterUse === 'omitted' ? 'omits' : 'sends'} "${c.impact.parameter}"`));
54
57
  }
58
+ if (c.deprecation) lines.push(formatDeprecation(c));
55
59
  }
56
60
  lines.push('');
57
61
  }
@@ -156,6 +160,23 @@ function formatImpact(c, { detailed }) {
156
160
  return lines;
157
161
  }
158
162
 
163
+ /** Removals only: was this deprecated in the base spec before it was removed? */
164
+ function formatDeprecation(c) {
165
+ const d = c.deprecation;
166
+ const used = c.impact && c.impact.verdict === 'used';
167
+ if (d.deprecated) {
168
+ const sunset = d.sunset ? ` (sunset ${d.sunset})` : '';
169
+ if (d.drained) {
170
+ return chalk.gray(` ↳ deprecated${sunset} · drained: last call ${day(c.impact.lastSeen)}, ${d.quietForDays} days before the newest log line`);
171
+ }
172
+ return used
173
+ ? chalk.yellow(` ↳ deprecated${sunset}, but still called — tell the clients above before removing it`)
174
+ : chalk.gray(` ↳ deprecated${sunset} and unused — removal is the planned last step`);
175
+ }
176
+ return chalk.yellow(' ↳ removed without being deprecated first — callers got no warning' +
177
+ (used ? '. Mark it `deprecated: true` and watch it drain: specshield deprecations' : ''));
178
+ }
179
+
159
180
  function scope(i) {
160
181
  if (i.basis !== 'query-parameter') return '';
161
182
  return i.parameterUse === 'omitted'
@@ -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-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 };