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.
- package/CHANGELOG.md +55 -1
- package/README.md +114 -4
- package/package.json +1 -1
- package/src/api/bdctClient.js +8 -0
- package/src/cli.js +2 -0
- package/src/commands/compare.js +7 -1
- package/src/commands/deprecations.js +236 -0
- package/src/core/configLoader.js +6 -1
- package/src/core/normalizeSpec.js +67 -11
- package/src/core/outputFormatter.js +22 -1
- package/src/core/usage/deprecations.js +438 -0
- package/src/core/usage/impact.js +62 -28
- package/src/core/usage/logParsers.js +39 -1
- package/src/core/usage/usageStore.js +32 -5
|
@@ -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,
|
|
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,
|
|
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(
|
|
47
|
-
requestBody:
|
|
48
|
-
|
|
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
|
-
|
|
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,
|
|
117
|
+
function normalizeResponses(responses, ctx) {
|
|
118
|
+
const { schemas } = ctx;
|
|
70
119
|
const result = {};
|
|
71
|
-
for (const [statusCode,
|
|
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
|
|
100
|
-
const resolved = schemas[
|
|
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
|
-
|
|
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 };
|