specshield 3.4.16 → 3.5.0

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,270 @@
1
+ 'use strict';
2
+
3
+ const fsExtra = require('fs-extra');
4
+ const jsYaml = require('js-yaml');
5
+ const YAML = require('yaml');
6
+
7
+ /**
8
+ * Waivers: accepted breaking changes, each with an owner, a reason and an
9
+ * expiry. They live in the repository (default .specshield/waivers.yml), so
10
+ * adding one is a reviewed diff in the PR that needs it, and the same file is
11
+ * read by `specshield gate` and the SpecShield GitHub App.
12
+ *
13
+ * waivers:
14
+ * - change: response-field-removed # change type (required); "*" = any type on `operation`
15
+ * operation: GET /pets/{id} # optional: METHOD /path, "*" method, * / ** path globs
16
+ * field: legacy_id # optional: field name or path suffix
17
+ * owner: "@alice" # required
18
+ * reason: Clients stopped reading it in v4.2 (required)
19
+ * expires: 2026-12-31 # required; the waiver stops applying after this day (UTC)
20
+ * created: 2026-10-27 # written by `specshield waivers add`
21
+ * ticket: PAY-123 # optional
22
+ *
23
+ * Without `operation` and `field` a waiver covers every change of that type —
24
+ * a policy decision, which the expiry forces someone to revisit.
25
+ *
26
+ * Matching rules (mirrored by the backend's GateWaivers.java):
27
+ * change the change's type, kebab-case (RESPONSE_FIELD_REMOVED → response-field-removed)
28
+ * operation must cover EVERY endpoint the change affects
29
+ * field equals the change's field, its last segment, or a dot-suffix of it
30
+ */
31
+
32
+ const DEFAULT_FILE = '.specshield/waivers.yml';
33
+ const DEFAULT_MAX_DAYS = 90;
34
+ const EXPIRING_DAYS = 7;
35
+ const DAY = 86400000;
36
+
37
+ function changeId(type) {
38
+ return String(type || '').trim().toLowerCase().replace(/_/g, '-');
39
+ }
40
+
41
+ function today(now = Date.now()) {
42
+ return new Date(now).toISOString().slice(0, 10);
43
+ }
44
+
45
+ function toDate(v) {
46
+ if (v instanceof Date && !Number.isNaN(v.getTime())) return v.toISOString().slice(0, 10);
47
+ if (typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v.trim()) && !Number.isNaN(Date.parse(v.trim()))) return v.trim();
48
+ return null;
49
+ }
50
+
51
+ function daysBetween(a, b) {
52
+ return Math.round((Date.parse(b) - Date.parse(a)) / DAY);
53
+ }
54
+
55
+ /** Reads and validates the waiver file. A missing file is no waivers; bad YAML throws. */
56
+ async function loadWaivers(file, opts = {}) {
57
+ if (!(await fsExtra.pathExists(file))) return { file, exists: false, waivers: [] };
58
+ return { file, exists: true, ...parseWaivers(await fsExtra.readFile(file, 'utf8'), { ...opts, file }) };
59
+ }
60
+
61
+ function parseWaivers(text, { file = DEFAULT_FILE, maxDays = DEFAULT_MAX_DAYS, now = Date.now() } = {}) {
62
+ let doc;
63
+ try {
64
+ doc = jsYaml.load(text);
65
+ } catch (err) {
66
+ throw new Error(`${file} is not valid YAML: ${err.message.split('\n')[0]}`);
67
+ }
68
+ if (doc === null || doc === undefined) return { waivers: [] };
69
+ const list = Array.isArray(doc) ? doc : doc.waivers;
70
+ if (list === undefined || list === null) return { waivers: [] };
71
+ if (!Array.isArray(list)) throw new Error(`${file}: "waivers" must be a list`);
72
+ return { waivers: list.map((w, i) => validate(w, i, { maxDays, now })) };
73
+ }
74
+
75
+ /** Normalizes one waiver and lists what's wrong with it; a waiver with errors never applies. */
76
+ function validate(raw, index, { maxDays = DEFAULT_MAX_DAYS, now = Date.now() } = {}) {
77
+ const errors = [];
78
+ const w = raw && typeof raw === 'object' ? raw : {};
79
+ const str = (v) => (v === undefined || v === null ? '' : String(v).trim());
80
+ const out = {
81
+ index,
82
+ change: changeId(w.change || w.type),
83
+ operation: str(w.operation) || null,
84
+ field: str(w.field) || null,
85
+ owner: str(w.owner),
86
+ reason: str(w.reason),
87
+ expires: toDate(w.expires),
88
+ created: toDate(w.created),
89
+ ticket: str(w.ticket) || null,
90
+ errors,
91
+ };
92
+ if (!raw || typeof raw !== 'object') errors.push('must be a mapping with change, owner, reason and expires');
93
+ if (!out.change) errors.push('change is required (e.g. response-field-removed)');
94
+ else if (out.change !== '*' && !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(out.change)) errors.push(`change "${out.change}" is not a change type`);
95
+ if (out.change === '*' && !out.operation) errors.push('change: "*" needs an operation — it would waive every breaking change');
96
+ if (out.operation && !parseOperation(out.operation)) errors.push(`operation "${out.operation}" must look like "GET /pets/{id}" or "/pets/**"`);
97
+ if (!out.owner) errors.push('owner is required — who answers for this waiver');
98
+ if (!out.reason) errors.push('reason is required — why this break is acceptable');
99
+ else if (out.reason.length < 10) errors.push('reason is too short to tell a reviewer why');
100
+ if (!w.expires) errors.push(`expires is required (YYYY-MM-DD, at most ${maxDays} days out)`);
101
+ else if (!out.expires) errors.push(`expires "${w.expires instanceof Date ? w.expires : w.expires}" must be a date like 2026-12-31`);
102
+ else {
103
+ const from = out.created || today(now);
104
+ if (daysBetween(from, out.expires) > maxDays) {
105
+ errors.push(`expires ${out.expires} is more than ${maxDays} days after ${out.created ? `created ${out.created}` : 'today'} — waivers must be revisited`);
106
+ }
107
+ if (out.created && out.created > out.expires) errors.push('created is after expires');
108
+ }
109
+ return out;
110
+ }
111
+
112
+ function status(w, now = Date.now()) {
113
+ if (w.errors.length) return 'invalid';
114
+ const t = today(now);
115
+ if (t > w.expires) return 'expired';
116
+ return daysBetween(t, w.expires) <= EXPIRING_DAYS ? 'expiring' : 'active';
117
+ }
118
+
119
+ function daysLeft(w, now = Date.now()) {
120
+ return w.expires ? daysBetween(today(now), w.expires) : null;
121
+ }
122
+
123
+ // ─── matching ───────────────────────────────────────────────────────────────
124
+
125
+ function parseOperation(op) {
126
+ const m = /^\s*(?:([A-Za-z]+|\*)\s+)?(\/\S*)\s*$/.exec(op || '');
127
+ if (!m) return null;
128
+ return { method: m[1] ? m[1].toUpperCase() : '*', path: m[2] };
129
+ }
130
+
131
+ function pathMatches(pattern, path) {
132
+ const norm = (p) => p.replace(/\{[^}]+\}/g, '{}').replace(/\/+$/, '') || '/';
133
+ const pat = norm(pattern).split('/');
134
+ const segs = norm(path).split('/');
135
+ const go = (i, j) => {
136
+ if (i === pat.length) return j === segs.length;
137
+ if (pat[i] === '**') {
138
+ for (let k = j; k <= segs.length; k++) if (go(i + 1, k)) return true;
139
+ return false;
140
+ }
141
+ if (j === segs.length) return false;
142
+ return (pat[i] === '*' || pat[i] === segs[j]) && go(i + 1, j + 1);
143
+ };
144
+ return go(0, 0);
145
+ }
146
+
147
+ function opMatches(op, endpoint) {
148
+ const [method, ...rest] = endpoint.split(' ');
149
+ const path = rest.join(' ');
150
+ return (op.method === '*' || op.method === method.toUpperCase()) && pathMatches(op.path, path);
151
+ }
152
+
153
+ /** Every "METHOD /path" a change affects. */
154
+ function endpointsOf(change) {
155
+ if (Array.isArray(change.affectedEndpoints) && change.affectedEndpoints.length) return change.affectedEndpoints;
156
+ if (change.method && change.path) return [`${change.method.toUpperCase()} ${change.path}`];
157
+ return [];
158
+ }
159
+
160
+ function fieldMatches(want, field) {
161
+ if (!field) return false;
162
+ const clean = (f) => String(f).replace(/\[[^\]]*\]/g, '').replace(/^(query|path|header|cookie):/, '');
163
+ const f = clean(field);
164
+ const w = clean(want);
165
+ if (f === w) return true;
166
+ const segs = f.split('.').map((s) => s.replace(/^(query|path|header|cookie):/, ''));
167
+ if (segs[segs.length - 1] === w) return true;
168
+ return f.endsWith(`.${w}`);
169
+ }
170
+
171
+ function matches(w, change) {
172
+ if (w.errors.length) return false;
173
+ if (w.change !== '*' && w.change !== changeId(change.type)) return false;
174
+ if (w.operation) {
175
+ const op = parseOperation(w.operation);
176
+ const eps = endpointsOf(change);
177
+ if (eps.length === 0 || !eps.every((e) => opMatches(op, e))) return false;
178
+ }
179
+ if (w.field && !fieldMatches(w.field, change.field)) return false;
180
+ return true;
181
+ }
182
+
183
+ /**
184
+ * Splits breaking changes into the ones still blocking and the ones an active
185
+ * waiver accepts. A change matched only by an expired waiver keeps blocking
186
+ * and carries `expiredWaiver`, so the output can say why it's back.
187
+ */
188
+ function applyWaivers(breaking, waivers, now = Date.now()) {
189
+ const blocking = [];
190
+ const waived = [];
191
+ const used = new Set();
192
+ for (const c of breaking) {
193
+ const hits = waivers.filter((w) => matches(w, c));
194
+ const live = hits.find((w) => status(w, now) !== 'expired');
195
+ if (live) {
196
+ used.add(live.index);
197
+ waived.push({ ...c, waiver: brief(live, now) });
198
+ } else if (hits.length) {
199
+ blocking.push({ ...c, expiredWaiver: brief(hits[0], now) });
200
+ } else {
201
+ blocking.push(c);
202
+ }
203
+ }
204
+ return { blocking, waived, used };
205
+ }
206
+
207
+ function brief(w, now) {
208
+ return { change: w.change, operation: w.operation, field: w.field, owner: w.owner, reason: w.reason, expires: w.expires, ticket: w.ticket, status: status(w, now) };
209
+ }
210
+
211
+ /** Waivers added or edited in this change (not identical to one in the baseline file). */
212
+ function newSince(head, base) {
213
+ const key = (w) => JSON.stringify([w.change, w.operation, w.field, w.owner, w.reason, w.expires, w.ticket]);
214
+ const before = new Set(base.map(key));
215
+ return head.filter((w) => !before.has(key(w)));
216
+ }
217
+
218
+ /** The waiver a change would need — exactly that change, nothing broader. */
219
+ function suggestFor(change) {
220
+ const eps = endpointsOf(change);
221
+ return {
222
+ change: changeId(change.type),
223
+ operation: eps.length === 1 ? eps[0] : null,
224
+ field: change.field ? String(change.field).split('.').pop().replace(/\[[^\]]*\]/g, '') || null : null,
225
+ };
226
+ }
227
+
228
+ function needsQuotes(str) {
229
+ if (/^[@`|>!&*%#?{[,'"-]/.test(str)) return true;
230
+ try { return jsYaml.load(str) !== str; } catch { return true; }
231
+ }
232
+
233
+ // ─── writing ────────────────────────────────────────────────────────────────
234
+
235
+ const HEADER = [
236
+ 'Accepted breaking changes, read by `specshield gate` and the SpecShield GitHub App.',
237
+ 'Each waiver needs an owner, a reason and an expiry; an expired waiver stops applying.',
238
+ 'Add one with: specshield waivers add <change> --operation "GET /path" --owner @you --reason "..." --days 30',
239
+ ].join('\n');
240
+
241
+ /** Appends a waiver to the file, keeping comments and layout. Returns the file text. */
242
+ async function addWaiver(file, waiver) {
243
+ const exists = await fsExtra.pathExists(file);
244
+ const text = exists ? await fsExtra.readFile(file, 'utf8') : '';
245
+ const doc = text.trim() ? YAML.parseDocument(text) : new YAML.Document({ waivers: [] });
246
+ if (!text.trim()) doc.commentBefore = HEADER.split('\n').map((l) => ` ${l}`).join('\n');
247
+ if (doc.errors && doc.errors.length) throw new Error(`${file} is not valid YAML: ${doc.errors[0].message}`);
248
+ let seq = doc.get('waivers');
249
+ if (!YAML.isSeq(seq)) {
250
+ if (YAML.isSeq(doc.contents)) seq = doc.contents;
251
+ else { doc.set('waivers', doc.createNode([])); seq = doc.get('waivers'); }
252
+ }
253
+ const entry = {};
254
+ for (const k of ['change', 'operation', 'field', 'owner', 'reason', 'created', 'expires', 'ticket']) {
255
+ if (waiver[k] !== undefined && waiver[k] !== null && waiver[k] !== '') entry[k] = waiver[k];
256
+ }
257
+ const node = doc.createNode(entry);
258
+ // Dates stay strings in the file, and "@alice" needs quoting in YAML.
259
+ YAML.visit(node, { Scalar(_, s) { if (typeof s.value === 'string' && needsQuotes(s.value)) s.type = YAML.Scalar.QUOTE_DOUBLE; } });
260
+ seq.items.push(node);
261
+ const out = doc.toString({ lineWidth: 0 });
262
+ await fsExtra.outputFile(file, out);
263
+ return out;
264
+ }
265
+
266
+ module.exports = {
267
+ DEFAULT_FILE, DEFAULT_MAX_DAYS, EXPIRING_DAYS,
268
+ changeId, today, loadWaivers, parseWaivers, validate, status, daysLeft,
269
+ parseOperation, pathMatches, fieldMatches, endpointsOf, matches, applyWaivers, newSince, suggestFor, addWaiver,
270
+ };
@@ -0,0 +1,63 @@
1
+ 'use strict';
2
+
3
+ const path = require('path');
4
+ const { normalizeSpec } = require('../normalizeSpec');
5
+ const { loadUsage } = require('./usageStore');
6
+ const { applyUsageImpact } = require('./impact');
7
+ const { annotateDeprecations } = require('./deprecations');
8
+ const logger = require('../../utils/logger');
9
+
10
+ /**
11
+ * Joins a classified result to real traffic (compare --usage, gate --usage):
12
+ * annotates each change with the clients it affects, moves unused breaking
13
+ * changes to unusedBreakingChanges when the evidence is good enough, and
14
+ * marks deprecated items that have drained.
15
+ *
16
+ * `baseSpec` is the parsed base spec; `baseLabel` names it in warnings.
17
+ */
18
+ async function applyUsage(result, baseSpec, options, baseLabel = 'the base spec') {
19
+ const usage = await loadUsage(options.usage);
20
+ const num = (value, flag, max = Infinity) => {
21
+ const n = Number(value);
22
+ if (!Number.isFinite(n) || n < 0 || n > max) throw new Error(`${flag} must be a number from 0 to ${max}, got "${value}"`);
23
+ return n;
24
+ };
25
+ const minDays = num(options.usageMinDays, '--usage-min-days');
26
+ const maxAgeDays = num(options.usageMaxAge, '--usage-max-age');
27
+ const minCoverage = num(options.usageMinCoverage, '--usage-min-coverage', 100);
28
+
29
+ const { result: annotated, meta } = applyUsageImpact(result, {
30
+ usage,
31
+ baseSpec,
32
+ baseNorm: normalizeSpec(baseSpec),
33
+ file: path.basename(options.usage),
34
+ ignoreClients: options.usageIgnoreClient,
35
+ minDays,
36
+ maxAgeDays,
37
+ minCoverage,
38
+ downgrade: options.usageDowngrade,
39
+ });
40
+ if (!meta.trusted && meta.totalCalls > 0) {
41
+ logger.warn(`None of the calls in ${options.usage} match an operation in ${baseLabel}. ` +
42
+ 'Is it the right usage file? If the API is served under a prefix, re-import with --base-path.');
43
+ }
44
+ const quietDays = num(options.usageQuietDays, '--usage-quiet-days');
45
+ return { ...annotateDeprecations(annotated, baseSpec, { meta, quietDays }), usage: { ...meta, quietDays } };
46
+ }
47
+
48
+ /** The usage options from .specshield.yml's `usage:` block, overridden by flags. */
49
+ function usageOptions(config, cliOpts) {
50
+ const u = config.usage || {};
51
+ const pick = (flag, key, def) => (cliOpts[flag] !== undefined ? cliOpts[flag] : u[key] !== undefined ? u[key] : def);
52
+ return {
53
+ usage: cliOpts.usage || u.file || null,
54
+ usageIgnoreClient: [...(cliOpts.usageIgnoreClient || []), ...(u.ignoreClients || [])],
55
+ usageMinDays: pick('usageMinDays', 'minDays', 7),
56
+ usageMaxAge: pick('usageMaxAge', 'maxAgeDays', 30),
57
+ usageMinCoverage: pick('usageMinCoverage', 'minCoverage', 25),
58
+ usageQuietDays: pick('usageQuietDays', 'quietDays', 30),
59
+ usageDowngrade: cliOpts.usageDowngrade === false ? false : u.downgrade !== false,
60
+ };
61
+ }
62
+
63
+ module.exports = { applyUsage, usageOptions };