specshield 3.4.15 → 3.4.17
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 +57 -0
- package/README.md +160 -12
- package/package.json +3 -2
- package/src/api/bdctClient.js +8 -0
- package/src/cli.js +6 -0
- package/src/commands/compare.js +2 -33
- package/src/commands/fix.js +173 -0
- package/src/commands/gate.js +307 -0
- package/src/commands/waivers.js +123 -0
- package/src/core/classifyChanges.js +1 -1
- package/src/core/configLoader.js +34 -0
- package/src/core/fix/fixSpec.js +179 -0
- package/src/core/fix/locate.js +263 -0
- package/src/core/fix/ops.js +233 -0
- package/src/core/fix/shim/spring.js +532 -0
- package/src/core/fix/shim/transforms.js +231 -0
- package/src/core/fix/strategies.js +578 -0
- package/src/core/gate/baseline.js +142 -0
- package/src/core/gate/git.js +44 -0
- package/src/core/gate/runGate.js +140 -0
- package/src/core/gate/waivers.js +270 -0
- package/src/core/outputFormatter.js +1 -0
- package/src/core/usage/applyUsage.js +63 -0
- package/src/core/usage/deprecations.js +1 -1
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { Command } = require('commander');
|
|
4
|
+
const chalk = require('chalk');
|
|
5
|
+
const fs = require('fs');
|
|
6
|
+
const { loadConfig } = require('../core/configLoader');
|
|
7
|
+
const { loadProjectConfig } = require('../core/projectConfig');
|
|
8
|
+
const { runGate } = require('../core/gate/runGate');
|
|
9
|
+
const { usageOptions } = require('../core/usage/applyUsage');
|
|
10
|
+
const W = require('../core/gate/waivers');
|
|
11
|
+
const G = require('../core/gate/git');
|
|
12
|
+
const { plural } = require('../core/usage/format');
|
|
13
|
+
const { uploadGateRun } = require('../api/bdctClient');
|
|
14
|
+
const { getStoredApiKey } = require('../config/localConfig');
|
|
15
|
+
const logger = require('../utils/logger');
|
|
16
|
+
const exitAfterFlush = require('../utils/exitAfterFlush');
|
|
17
|
+
|
|
18
|
+
const gate = new Command('gate')
|
|
19
|
+
.description('CI gate: breaking changes in this branch vs the commit it started from, with owned, expiring waivers and a shadow mode')
|
|
20
|
+
.argument('[spec]', 'The OpenAPI spec in this repository (default: gate.spec or github.specPath in .specshield.yml)')
|
|
21
|
+
.option('--base <ref>', 'Branch or commit to compare against (default: detected from CI, else origin\'s default branch); the merge base with HEAD is used')
|
|
22
|
+
.option('--mode <mode>', 'blocking (fail the build) or shadow (report what would have been blocked, never fail)')
|
|
23
|
+
.option('--shadow', 'Same as --mode shadow')
|
|
24
|
+
.option('--waivers <file>', `Waiver file (default: ${W.DEFAULT_FILE})`)
|
|
25
|
+
.option('--max-waiver-days <n>', `Longest a waiver may run before it must be renewed (default: ${W.DEFAULT_MAX_DAYS})`)
|
|
26
|
+
.option('--no-fetch', 'Never run git fetch, even when the baseline commit is missing from a shallow clone')
|
|
27
|
+
.option('--usage <file>', 'usage.json from "specshield usage import" — breaking changes no client uses stop blocking')
|
|
28
|
+
.option('--no-summary', 'Skip the GitHub Actions job summary and annotations')
|
|
29
|
+
.option('--upload', 'Record this run on your SpecShield dashboard, for the shadow-mode graduation report (Team plan)')
|
|
30
|
+
.option('--org <key>', 'Org key for --upload (default: gate.org or bdct.org in .specshield.yml)')
|
|
31
|
+
.option('--repo <name>', 'Repository name for --upload (default: from CI, else the origin remote)')
|
|
32
|
+
.option('--api-token <token>', 'API key for --upload (default: SPECSHIELD_API_KEY or "specshield login")')
|
|
33
|
+
.option('--server <url>', 'SpecShield server for --upload')
|
|
34
|
+
.option('--config <path>', 'Path to .specshield.yml')
|
|
35
|
+
.option('--json', 'Output machine-readable JSON')
|
|
36
|
+
.action(async (specArg, opts) => {
|
|
37
|
+
try {
|
|
38
|
+
const config = await loadConfig(opts.config);
|
|
39
|
+
const g = config.gate || {};
|
|
40
|
+
const spec = specArg || g.spec || (config.github && config.github.specPath);
|
|
41
|
+
if (!spec) throw new Error('Which spec? Pass it as an argument (specshield gate openapi.yaml) or set gate.spec in .specshield.yml');
|
|
42
|
+
const mode = opts.shadow ? 'shadow' : (opts.mode || g.mode || 'blocking');
|
|
43
|
+
const maxWaiverDays = opts.maxWaiverDays !== undefined ? Number(opts.maxWaiverDays) : (g.maxWaiverDays || W.DEFAULT_MAX_DAYS);
|
|
44
|
+
if (!(maxWaiverDays >= 1)) throw new Error('--max-waiver-days must be a number ≥ 1');
|
|
45
|
+
|
|
46
|
+
const usage = usageOptions(config, { usage: opts.usage });
|
|
47
|
+
const r = await runGate({
|
|
48
|
+
spec, mode, base: opts.base, fetch: opts.fetch,
|
|
49
|
+
waiversFile: opts.waivers || g.waivers || W.DEFAULT_FILE,
|
|
50
|
+
maxWaiverDays,
|
|
51
|
+
ignore: config.ignore || [],
|
|
52
|
+
usage: usage.usage ? usage : null,
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
if (opts.upload || g.upload) r.upload = await upload(r, { ...opts, org: opts.org || g.org });
|
|
56
|
+
|
|
57
|
+
if (opts.json) process.stdout.write(JSON.stringify(r, null, 2) + '\n');
|
|
58
|
+
else process.stdout.write(render(r) + '\n');
|
|
59
|
+
|
|
60
|
+
if (opts.summary !== false && process.env.GITHUB_ACTIONS === 'true') {
|
|
61
|
+
annotate(r);
|
|
62
|
+
if (process.env.GITHUB_STEP_SUMMARY) {
|
|
63
|
+
try { fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, markdown(r) + '\n'); } catch { /* summary is best-effort */ }
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
exitAfterFlush(r.verdict === 'block' ? 1 : 0);
|
|
67
|
+
} catch (err) {
|
|
68
|
+
logger.error(`Error: ${err.message}`);
|
|
69
|
+
process.exit(2);
|
|
70
|
+
}
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
// ─── upload ─────────────────────────────────────────────────────────────────
|
|
74
|
+
|
|
75
|
+
/** Never fails the gate: a dashboard outage must not block merges. */
|
|
76
|
+
async function upload(r, opts) {
|
|
77
|
+
try {
|
|
78
|
+
const project = loadProjectConfig();
|
|
79
|
+
const bdct = project.bdct || {};
|
|
80
|
+
const orgKey = opts.org || (bdct.org && bdct.org !== '<replace-me>' ? bdct.org : null);
|
|
81
|
+
if (!orgKey) throw new Error('needs an org key: pass --org <key> or set gate.org in .specshield.yml');
|
|
82
|
+
const repo = opts.repo || r.ci.repo || repoFromRemote();
|
|
83
|
+
if (!repo) throw new Error('could not tell the repository name: pass --repo owner/name');
|
|
84
|
+
const token = opts.apiToken || process.env.SPECSHIELD_API_KEY || (await getStoredApiKey());
|
|
85
|
+
if (!token) throw new Error('no API key: set SPECSHIELD_API_KEY or pass --api-token');
|
|
86
|
+
const res = await uploadGateRun(opts.server || bdct.server, token, payload(r, orgKey, repo));
|
|
87
|
+
return { ok: true, id: res && res.id, url: res && res.url, readiness: (res && res.readiness) || null };
|
|
88
|
+
} catch (err) {
|
|
89
|
+
const reason = err.status === 402 ? 'the graduation report needs a paid plan (Team or above)' : err.message.replace(/^API error/, 'server said');
|
|
90
|
+
logger.warn(`Gate result not uploaded: ${reason}`);
|
|
91
|
+
return { ok: false, error: reason };
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
function payload(r, orgKey, repo) {
|
|
96
|
+
const item = (c) => ({ key: c.key, change: c.change, operations: c.operations, field: c.field || null, description: c.description || null });
|
|
97
|
+
return {
|
|
98
|
+
orgKey,
|
|
99
|
+
repo,
|
|
100
|
+
pr: r.ci.pr,
|
|
101
|
+
prTitle: r.ci.title,
|
|
102
|
+
provider: r.ci.provider,
|
|
103
|
+
event: r.ci.event,
|
|
104
|
+
headSha: r.head.sha,
|
|
105
|
+
baseSha: r.baseline.sha,
|
|
106
|
+
spec: r.spec,
|
|
107
|
+
mode: r.mode,
|
|
108
|
+
verdict: r.verdict,
|
|
109
|
+
specTouched: r.specTouched,
|
|
110
|
+
specStatus: r.specStatus,
|
|
111
|
+
blocking: r.blocking.map((c) => ({ ...item(c), expiredWaiver: c.expiredWaiver ? { owner: c.expiredWaiver.owner, expires: c.expiredWaiver.expires } : null })),
|
|
112
|
+
waived: r.waived.map((c) => ({ ...item(c), owner: c.waiver.owner, reason: c.waiver.reason, expires: c.waiver.expires })),
|
|
113
|
+
unused: r.unused.length,
|
|
114
|
+
waivers: {
|
|
115
|
+
total: r.waivers.total,
|
|
116
|
+
active: (r.waivers.counts.active || 0),
|
|
117
|
+
expiring: r.waivers.expiring.length,
|
|
118
|
+
expired: r.waivers.expired.length,
|
|
119
|
+
invalid: r.waivers.invalid.length,
|
|
120
|
+
},
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
function repoFromRemote() {
|
|
125
|
+
const url = G.git(['remote', 'get-url', 'origin'], { allowFail: true });
|
|
126
|
+
const m = url && /[:/]([^/:]+\/[^/]+?)(\.git)?$/.exec(url);
|
|
127
|
+
return m ? m[1] : null;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
// ─── human output ───────────────────────────────────────────────────────────
|
|
131
|
+
|
|
132
|
+
function waiveCommand(c, file) {
|
|
133
|
+
const s = W.suggestFor(c);
|
|
134
|
+
const q = (v) => `"${v.replace(/"/g, '\\"')}"`;
|
|
135
|
+
return ['specshield waivers add', s.change,
|
|
136
|
+
s.operation ? `--operation ${q(s.operation)}` : null,
|
|
137
|
+
s.field ? `--field ${q(s.field)}` : null,
|
|
138
|
+
'--owner <you> --reason "<why this is safe>" --days 30',
|
|
139
|
+
file !== W.DEFAULT_FILE ? `--file ${q(file)}` : null].filter(Boolean).join(' ');
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function label(c) {
|
|
143
|
+
const ops = c.operations && c.operations.length ? c.operations : [];
|
|
144
|
+
const what = c.description || c.change;
|
|
145
|
+
// Merged changes already name their endpoints in the description.
|
|
146
|
+
if (ops.length === 0 || ops.every((o) => what.includes(o))) return { where: '', what };
|
|
147
|
+
const where = ops.length <= 2 ? ops.join(', ') : `${ops.slice(0, 2).join(', ')} and ${ops.length - 2} more`;
|
|
148
|
+
return { where, what };
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
function render(r) {
|
|
152
|
+
const lines = [''];
|
|
153
|
+
lines.push(chalk.bold(` SpecShield™ Gate — ${r.spec}`));
|
|
154
|
+
lines.push(chalk.gray(' ─────────────────────────────────────────'));
|
|
155
|
+
lines.push(` ${chalk.gray('Baseline')} ${r.baseline.sha.slice(0, 12)} ${chalk.gray(`— where this branch started from ${r.baseline.from}`)}`);
|
|
156
|
+
if (r.baseline.fetched.length) lines.push(chalk.gray(` fetched ${r.baseline.fetched.join(', ')} to find it`));
|
|
157
|
+
lines.push(` ${chalk.gray('Mode')} ${r.mode === 'shadow' ? `${chalk.yellow('shadow')} ${chalk.gray('— reports what it would block; never fails the build')}` : 'blocking'}`);
|
|
158
|
+
lines.push('');
|
|
159
|
+
|
|
160
|
+
if (r.specStatus === 'unchanged') {
|
|
161
|
+
lines.push(chalk.green(' ✔ This change doesn\'t touch the spec — nothing to check.'));
|
|
162
|
+
} else if (r.specStatus === 'added') {
|
|
163
|
+
lines.push(chalk.green(' ✔ The spec is new in this change — nothing to compare it with.'));
|
|
164
|
+
} else if (r.blocking.length === 0) {
|
|
165
|
+
const notes = [];
|
|
166
|
+
if (r.waived.length) notes.push(`${plural(r.waived.length, 'waived change')}`);
|
|
167
|
+
if (r.unused.length) notes.push(`${r.unused.length} unused by any client`);
|
|
168
|
+
lines.push(chalk.green(` ✔ No breaking changes block this change`) + (notes.length ? chalk.gray(` (${notes.join(', ')})`) : '') +
|
|
169
|
+
(r.nonBreaking ? chalk.gray(` · ${plural(r.nonBreaking, 'non-breaking change')}`) : ''));
|
|
170
|
+
} else {
|
|
171
|
+
const head = r.verdict === 'would-block'
|
|
172
|
+
? chalk.yellow.bold(` ▲ Shadow mode: would have blocked this change — ${plural(r.blocking.length, 'breaking change')}`)
|
|
173
|
+
: chalk.red.bold(` ✖ ${plural(r.blocking.length, 'breaking change')} block${r.blocking.length === 1 ? 's' : ''} this change`);
|
|
174
|
+
lines.push(head);
|
|
175
|
+
for (const c of r.blocking) {
|
|
176
|
+
const { where, what } = label(c);
|
|
177
|
+
lines.push('');
|
|
178
|
+
lines.push(` ${chalk.red('●')} ${what}`);
|
|
179
|
+
if (where) lines.push(chalk.gray(` ${where}`));
|
|
180
|
+
if (c.expiredWaiver) {
|
|
181
|
+
lines.push(chalk.yellow(` waiver expired ${c.expiredWaiver.expires} (owner ${c.expiredWaiver.owner}) — renew it or fix the change`));
|
|
182
|
+
}
|
|
183
|
+
lines.push(chalk.gray(` intended? ${waiveCommand(c, r.waivers.file)}`));
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
if (r.waived.length) {
|
|
188
|
+
lines.push('');
|
|
189
|
+
lines.push(chalk.bold(` Waived (${r.waived.length})`));
|
|
190
|
+
for (const c of r.waived) {
|
|
191
|
+
const { where, what } = label(c);
|
|
192
|
+
lines.push(` ${chalk.green('✔')} ${what}${where ? chalk.gray(` · ${where}`) : ''}`);
|
|
193
|
+
const w = c.waiver;
|
|
194
|
+
lines.push(chalk.gray(` ${w.owner}, until ${w.expires}${w.ticket ? ` (${w.ticket})` : ''}: ${w.reason}`) +
|
|
195
|
+
(w.status === 'expiring' ? chalk.yellow(' expires soon') : ''));
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
if (r.unused.length) {
|
|
199
|
+
lines.push('');
|
|
200
|
+
lines.push(chalk.gray(` ${plural(r.unused.length, 'breaking change')} not blocking: no client called ${r.unused.length === 1 ? 'it' : 'them'} in the usage data.`));
|
|
201
|
+
}
|
|
202
|
+
if (r.ignored.length) {
|
|
203
|
+
lines.push('');
|
|
204
|
+
lines.push(chalk.yellow(` ${plural(r.ignored.length, 'breaking change')} skipped by the "ignore:" list in .specshield.yml, which has no owner or expiry.`));
|
|
205
|
+
lines.push(chalk.gray(` Move ${r.ignored.length === 1 ? 'it' : 'them'} to ${r.waivers.file}: ${waiveCommand(r.ignored[0], r.waivers.file)}`));
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
const wl = waiverLines(r);
|
|
209
|
+
if (wl.length) { lines.push(''); lines.push(...wl.map((l) => ` ${l}`)); }
|
|
210
|
+
|
|
211
|
+
if (r.upload) {
|
|
212
|
+
lines.push('');
|
|
213
|
+
lines.push(r.upload.ok ? chalk.green(' ✔ Recorded on your dashboard') + (r.upload.url ? chalk.gray(` ${r.upload.url}`) : '') : chalk.yellow(` Not recorded on the dashboard: ${r.upload.error}`));
|
|
214
|
+
if (r.upload.readiness && r.upload.readiness.headline) lines.push(chalk.gray(` Readiness: ${r.upload.readiness.headline}`));
|
|
215
|
+
}
|
|
216
|
+
lines.push('');
|
|
217
|
+
return lines.join('\n');
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
function waiverLines(r) {
|
|
221
|
+
const w = r.waivers;
|
|
222
|
+
const out = [];
|
|
223
|
+
for (const x of w.invalid) out.push(chalk.red(`✖ ${w.file} waiver #${x.index + 1} (${x.change || '?'}) doesn't apply: ${x.errors.join('; ')}`));
|
|
224
|
+
for (const x of w.unmatchedAdded) out.push(chalk.yellow(`▲ The waiver you added for ${describeWaiver(x)} matches no breaking change here — check change, operation and field.`));
|
|
225
|
+
if (w.expired.length) out.push(chalk.yellow(`▲ ${plural(w.expired.length, 'expired waiver')} in ${w.file} — delete ${w.expired.length === 1 ? 'it' : 'them'} or renew with a new expiry: ${w.expired.map(describeWaiver).join('; ')}`));
|
|
226
|
+
if (w.expiring.length) out.push(chalk.gray(`${plural(w.expiring.length, 'waiver')} expire${w.expiring.length === 1 ? 's' : ''} within ${W.EXPIRING_DAYS} days: ${w.expiring.map((x) => `${describeWaiver(x)} (${x.owner}, ${x.expires})`).join('; ')}`));
|
|
227
|
+
return out;
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
function describeWaiver(w) {
|
|
231
|
+
return [w.change, w.operation, w.field].filter(Boolean).join(' ');
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
// ─── GitHub Actions ─────────────────────────────────────────────────────────
|
|
235
|
+
|
|
236
|
+
function esc(s) {
|
|
237
|
+
return String(s).replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
|
|
238
|
+
}
|
|
239
|
+
function escProp(s) {
|
|
240
|
+
return esc(s).replace(/:/g, '%3A').replace(/,/g, '%2C');
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
function annotate(r) {
|
|
244
|
+
const level = r.verdict === 'would-block' ? 'warning' : 'error';
|
|
245
|
+
const file = `file=${escProp(r.spec)}`;
|
|
246
|
+
for (const c of r.blocking) {
|
|
247
|
+
const { where, what } = label(c);
|
|
248
|
+
const title = r.verdict === 'would-block' ? 'Breaking API change (shadow mode)' : 'Breaking API change';
|
|
249
|
+
const extra = c.expiredWaiver ? ` — waiver expired ${c.expiredWaiver.expires}` : '';
|
|
250
|
+
process.stdout.write(`::${level} ${file},title=${escProp(title)}::${esc(`${what}${where ? ` (${where})` : ''}${extra}`)}\n`);
|
|
251
|
+
}
|
|
252
|
+
for (const x of r.waivers.expired) {
|
|
253
|
+
process.stdout.write(`::warning file=${escProp(r.waivers.file)},title=Expired waiver::${esc(`${describeWaiver(x)} expired ${x.expires} (owner ${x.owner})`)}\n`);
|
|
254
|
+
}
|
|
255
|
+
for (const x of r.waivers.invalid) {
|
|
256
|
+
process.stdout.write(`::error file=${escProp(r.waivers.file)},title=Invalid waiver::${esc(`#${x.index + 1}: ${x.errors.join('; ')}`)}\n`);
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
function markdown(r) {
|
|
261
|
+
const md = [];
|
|
262
|
+
const icon = r.verdict === 'pass' ? '✅' : r.verdict === 'would-block' ? '🟡' : '❌';
|
|
263
|
+
md.push(`### ${icon} SpecShield gate — \`${r.spec}\``);
|
|
264
|
+
md.push('');
|
|
265
|
+
md.push(`Compared with \`${r.baseline.sha.slice(0, 12)}\`, where this branch started from ${r.baseline.from}. Mode: **${r.mode}**.`);
|
|
266
|
+
md.push('');
|
|
267
|
+
if (r.specStatus === 'unchanged') md.push('This change doesn\'t touch the spec.');
|
|
268
|
+
else if (r.specStatus === 'added') md.push('The spec is new in this change.');
|
|
269
|
+
else if (r.blocking.length === 0) md.push(`No breaking changes block this change${r.waived.length ? ` (${r.waived.length} waived)` : ''}.`);
|
|
270
|
+
else {
|
|
271
|
+
md.push(r.verdict === 'would-block'
|
|
272
|
+
? `**Shadow mode:** would have blocked this change — ${plural(r.blocking.length, 'breaking change')}.`
|
|
273
|
+
: `**${plural(r.blocking.length, 'breaking change')}** block this change.`);
|
|
274
|
+
md.push('');
|
|
275
|
+
md.push('| Change | Where | |');
|
|
276
|
+
md.push('|---|---|---|');
|
|
277
|
+
for (const c of r.blocking) {
|
|
278
|
+
const { where, what } = label(c);
|
|
279
|
+
md.push(`| ${cell(what)} | ${cell(where || '—')} | ${c.expiredWaiver ? `waiver expired ${c.expiredWaiver.expires}` : ''} |`);
|
|
280
|
+
}
|
|
281
|
+
md.push('');
|
|
282
|
+
md.push(`Intended? Add a waiver with an owner, a reason and an expiry: \`${waiveCommand(r.blocking[0], r.waivers.file)}\``);
|
|
283
|
+
}
|
|
284
|
+
if (r.waived.length) {
|
|
285
|
+
md.push('');
|
|
286
|
+
md.push('<details><summary>Waived</summary>');
|
|
287
|
+
md.push('');
|
|
288
|
+
for (const c of r.waived) md.push(`- ${cell(label(c).what)} — ${cell(c.waiver.owner)}, until ${c.waiver.expires}: ${cell(c.waiver.reason)}`);
|
|
289
|
+
md.push('');
|
|
290
|
+
md.push('</details>');
|
|
291
|
+
}
|
|
292
|
+
const w = r.waivers;
|
|
293
|
+
if (w.expired.length || w.invalid.length || w.expiring.length) {
|
|
294
|
+
md.push('');
|
|
295
|
+
if (w.invalid.length) md.push(`- ${plural(w.invalid.length, 'invalid waiver')} in \`${w.file}\` (not applied)`);
|
|
296
|
+
if (w.expired.length) md.push(`- ${plural(w.expired.length, 'expired waiver')} in \`${w.file}\` — delete or renew`);
|
|
297
|
+
if (w.expiring.length) md.push(`- ${plural(w.expiring.length, 'waiver')} expiring within ${W.EXPIRING_DAYS} days`);
|
|
298
|
+
}
|
|
299
|
+
return md.join('\n');
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
function cell(s) {
|
|
303
|
+
return String(s).replace(/\|/g, '\\|').replace(/\n/g, ' ');
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
module.exports = gate;
|
|
307
|
+
module.exports._internal = { render, markdown, payload, waiveCommand };
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { Command } = require('commander');
|
|
4
|
+
const chalk = require('chalk');
|
|
5
|
+
const path = require('path');
|
|
6
|
+
const { loadConfig } = require('../core/configLoader');
|
|
7
|
+
const W = require('../core/gate/waivers');
|
|
8
|
+
const { plural } = require('../core/usage/format');
|
|
9
|
+
const logger = require('../utils/logger');
|
|
10
|
+
const exitAfterFlush = require('../utils/exitAfterFlush');
|
|
11
|
+
|
|
12
|
+
const DAY = 86400000;
|
|
13
|
+
|
|
14
|
+
async function settings(opts) {
|
|
15
|
+
const config = await loadConfig(opts.config);
|
|
16
|
+
const g = config.gate || {};
|
|
17
|
+
const maxDays = opts.maxDays !== undefined ? Number(opts.maxDays) : (g.maxWaiverDays || W.DEFAULT_MAX_DAYS);
|
|
18
|
+
if (!(maxDays >= 1)) throw new Error('--max-days must be a number ≥ 1');
|
|
19
|
+
return { file: opts.file || g.waivers || W.DEFAULT_FILE, maxDays };
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const add = new Command('add')
|
|
23
|
+
.description('Accept a breaking change: add a waiver with an owner, a reason and an expiry')
|
|
24
|
+
.argument('<change>', 'Change type, e.g. response-field-removed (as printed by "specshield gate"); "*" with --operation for every change there')
|
|
25
|
+
.option('--operation <op>', 'Limit to an operation: "GET /pets/{id}"; * and ** glob path segments; "/pets/**" = any method')
|
|
26
|
+
.option('--field <name>', 'Limit to a field (name or dotted path suffix)')
|
|
27
|
+
.requiredOption('--owner <who>', 'Who answers for this waiver, e.g. @alice or team-payments')
|
|
28
|
+
.requiredOption('--reason <text>', 'Why this break is acceptable — what a reviewer needs to know')
|
|
29
|
+
.option('--days <n>', 'Expire after n days (default 30)')
|
|
30
|
+
.option('--expires <date>', 'Expire after this day (YYYY-MM-DD) instead of --days')
|
|
31
|
+
.option('--ticket <id>', 'A ticket or issue that tracks the follow-up')
|
|
32
|
+
.option('--file <path>', `Waiver file (default: ${W.DEFAULT_FILE})`)
|
|
33
|
+
.option('--max-days <n>', `Longest allowed waiver (default: gate.maxWaiverDays or ${W.DEFAULT_MAX_DAYS})`)
|
|
34
|
+
.option('--config <path>', 'Path to .specshield.yml')
|
|
35
|
+
.action(async (change, opts) => {
|
|
36
|
+
try {
|
|
37
|
+
const { file, maxDays } = await settings(opts);
|
|
38
|
+
if (opts.days && opts.expires) throw new Error('Use either --days or --expires, not both');
|
|
39
|
+
const created = W.today();
|
|
40
|
+
let expires = opts.expires;
|
|
41
|
+
if (!expires) {
|
|
42
|
+
const days = opts.days !== undefined ? Number(opts.days) : 30;
|
|
43
|
+
if (!(Number.isInteger(days) && days >= 1)) throw new Error('--days must be a whole number ≥ 1');
|
|
44
|
+
expires = new Date(Date.parse(created) + days * DAY).toISOString().slice(0, 10);
|
|
45
|
+
}
|
|
46
|
+
const waiver = { change, operation: opts.operation, field: opts.field, owner: opts.owner, reason: opts.reason, created, expires, ticket: opts.ticket };
|
|
47
|
+
const checked = W.validate(waiver, 0, { maxDays });
|
|
48
|
+
if (checked.errors.length) throw new Error(`Waiver not added: ${checked.errors.join('; ')}`);
|
|
49
|
+
await W.addWaiver(path.resolve(file), { ...waiver, change: checked.change, operation: checked.operation ? normalizeOp(checked.operation) : undefined });
|
|
50
|
+
process.stdout.write(chalk.green(`✔ Waiver added to ${file}`) + chalk.gray(` — ${[checked.change, checked.operation, checked.field].filter(Boolean).join(' ')}, ${checked.owner}, until ${expires}`) + '\n');
|
|
51
|
+
process.stdout.write(chalk.gray(' Commit it with the change it accepts, so the waiver is reviewed with the PR.') + '\n');
|
|
52
|
+
} catch (err) {
|
|
53
|
+
logger.error(`Error: ${err.message}`);
|
|
54
|
+
process.exit(2);
|
|
55
|
+
}
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
function normalizeOp(op) {
|
|
59
|
+
const p = W.parseOperation(op);
|
|
60
|
+
return p.method === '*' ? p.path : `${p.method} ${p.path}`;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
const list = new Command('list')
|
|
64
|
+
.description('List waivers with their owner and expiry; --check fails on expired or invalid ones')
|
|
65
|
+
.option('--file <path>', `Waiver file (default: ${W.DEFAULT_FILE})`)
|
|
66
|
+
.option('--max-days <n>', `Longest allowed waiver (default: gate.maxWaiverDays or ${W.DEFAULT_MAX_DAYS})`)
|
|
67
|
+
.option('--check', 'Exit 1 when a waiver is expired or invalid (for a scheduled CI job)')
|
|
68
|
+
.option('--config <path>', 'Path to .specshield.yml')
|
|
69
|
+
.option('--json', 'Output machine-readable JSON')
|
|
70
|
+
.action(async (opts) => {
|
|
71
|
+
try {
|
|
72
|
+
const { file, maxDays } = await settings(opts);
|
|
73
|
+
const { exists, waivers } = await W.loadWaivers(path.resolve(file), { maxDays, file });
|
|
74
|
+
const rows = waivers.map((w) => ({ ...w, status: W.status(w), daysLeft: W.daysLeft(w) }));
|
|
75
|
+
const bad = rows.filter((w) => w.status === 'expired' || w.status === 'invalid');
|
|
76
|
+
if (opts.json) {
|
|
77
|
+
process.stdout.write(JSON.stringify({ file, exists, waivers: rows }, null, 2) + '\n');
|
|
78
|
+
} else {
|
|
79
|
+
process.stdout.write(renderList(file, exists, rows) + '\n');
|
|
80
|
+
}
|
|
81
|
+
exitAfterFlush(opts.check && bad.length ? 1 : 0);
|
|
82
|
+
} catch (err) {
|
|
83
|
+
logger.error(`Error: ${err.message}`);
|
|
84
|
+
process.exit(2);
|
|
85
|
+
}
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
function renderList(file, exists, rows) {
|
|
89
|
+
const lines = [''];
|
|
90
|
+
lines.push(chalk.bold(` Waivers — ${file}`));
|
|
91
|
+
lines.push(chalk.gray(' ─────────────────────────────────────────'));
|
|
92
|
+
if (!exists || rows.length === 0) {
|
|
93
|
+
lines.push(chalk.gray(` ${exists ? 'The file has no waivers.' : 'No waiver file yet.'} Add one with: specshield waivers add <change> --owner <you> --reason "<why>"`));
|
|
94
|
+
lines.push('');
|
|
95
|
+
return lines.join('\n');
|
|
96
|
+
}
|
|
97
|
+
const counts = rows.reduce((m, w) => ({ ...m, [w.status]: (m[w.status] || 0) + 1 }), {});
|
|
98
|
+
lines.push(` ${plural(rows.length, 'waiver')}` + ['active', 'expiring', 'expired', 'invalid']
|
|
99
|
+
.filter((s) => counts[s]).map((s) => ` · ${color(s)(`${counts[s]} ${s}`)}`).join(''));
|
|
100
|
+
for (const w of rows) {
|
|
101
|
+
lines.push('');
|
|
102
|
+
const what = [w.change || '?', w.operation, w.field].filter(Boolean).join(' ');
|
|
103
|
+
const when = w.status === 'invalid' ? 'invalid'
|
|
104
|
+
: w.status === 'expired' ? `expired ${w.expires}`
|
|
105
|
+
: `${w.daysLeft === 0 ? 'expires today' : `${plural(w.daysLeft, 'day')} left`} (${w.expires})`;
|
|
106
|
+
lines.push(` ${color(w.status)('●')} ${what} ${color(w.status)(when)}`);
|
|
107
|
+
if (w.owner || w.reason) lines.push(chalk.gray(` ${w.owner || 'no owner'}${w.ticket ? ` · ${w.ticket}` : ''}: ${w.reason || 'no reason'}`));
|
|
108
|
+
if (w.errors.length) lines.push(chalk.red(` ${w.errors.join('; ')}`));
|
|
109
|
+
}
|
|
110
|
+
lines.push('');
|
|
111
|
+
return lines.join('\n');
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
function color(status) {
|
|
115
|
+
return { active: chalk.green, expiring: chalk.yellow, expired: chalk.red, invalid: chalk.red }[status] || chalk.gray;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
const waivers = new Command('waivers')
|
|
119
|
+
.description('Accepted breaking changes for "specshield gate": each with an owner, a reason and an expiry')
|
|
120
|
+
.addCommand(list, { isDefault: true })
|
|
121
|
+
.addCommand(add);
|
|
122
|
+
|
|
123
|
+
module.exports = waivers;
|
package/src/core/configLoader.js
CHANGED
|
@@ -142,6 +142,40 @@ function validateConfig(config, filePath) {
|
|
|
142
142
|
}
|
|
143
143
|
}
|
|
144
144
|
|
|
145
|
+
if (config.gate !== undefined && config.gate !== null) {
|
|
146
|
+
const g = config.gate;
|
|
147
|
+
if (typeof g !== 'object' || Array.isArray(g)) {
|
|
148
|
+
throw new Error(`Config error in "${filePath}": gate must be an object`);
|
|
149
|
+
}
|
|
150
|
+
if (g.mode !== undefined && !['blocking', 'shadow'].includes(g.mode)) {
|
|
151
|
+
throw new Error(`Config error in "${filePath}": gate.mode must be "blocking" or "shadow"`);
|
|
152
|
+
}
|
|
153
|
+
if (g.maxWaiverDays !== undefined && !(Number(g.maxWaiverDays) >= 1)) {
|
|
154
|
+
throw new Error(`Config error in "${filePath}": gate.maxWaiverDays must be a number ≥ 1`);
|
|
155
|
+
}
|
|
156
|
+
for (const key of ['spec', 'waivers', 'org']) {
|
|
157
|
+
if (g[key] !== undefined && typeof g[key] !== 'string') {
|
|
158
|
+
throw new Error(`Config error in "${filePath}": gate.${key} must be a string`);
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
if (g.upload !== undefined && typeof g.upload !== 'boolean') {
|
|
162
|
+
throw new Error(`Config error in "${filePath}": gate.upload must be a boolean`);
|
|
163
|
+
}
|
|
164
|
+
valid.gate = {
|
|
165
|
+
spec: g.spec,
|
|
166
|
+
mode: g.mode,
|
|
167
|
+
waivers: g.waivers,
|
|
168
|
+
maxWaiverDays: g.maxWaiverDays !== undefined ? Number(g.maxWaiverDays) : undefined,
|
|
169
|
+
upload: g.upload,
|
|
170
|
+
org: g.org,
|
|
171
|
+
};
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
// `specshield init` writes the spec path here; the gate falls back to it.
|
|
175
|
+
if (config.github && typeof config.github === 'object' && typeof config.github.specPath === 'string') {
|
|
176
|
+
valid.github = { specPath: config.github.specPath };
|
|
177
|
+
}
|
|
178
|
+
|
|
145
179
|
return valid;
|
|
146
180
|
}
|
|
147
181
|
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { normalizeSpec } = require('../normalizeSpec');
|
|
4
|
+
const { diffSpecs } = require('../diffEngine');
|
|
5
|
+
const { BREAKING_TYPES } = require('../classifyChanges');
|
|
6
|
+
const { suggest, detectRenames, detectEnumRenames, reshapedBodies, sig } = require('./strategies');
|
|
7
|
+
const { applyOps, clone } = require('./ops');
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Break → fix. For every breaking change between `baseDoc` and `targetDoc`
|
|
11
|
+
* (raw parsed specs), proposes the expand-and-contract edit to the target
|
|
12
|
+
* that keeps existing clients working — and keeps it only if the diff engine
|
|
13
|
+
* agrees: applied on top of the fixes accepted so far, the suggestion must
|
|
14
|
+
* remove the breaking change(s) it addresses and must not introduce any other
|
|
15
|
+
* breaking change. Suggestions are applied in that order, so the returned
|
|
16
|
+
* `fixedDoc` is exactly what was verified.
|
|
17
|
+
*/
|
|
18
|
+
function fixSpec(baseDoc, targetDoc, { sunset = null, depth = 0 } = {}) {
|
|
19
|
+
const baseNorm = normalizeSpec(baseDoc);
|
|
20
|
+
const raw = diffSpecs(baseNorm, normalizeSpec(targetDoc));
|
|
21
|
+
const breaking = raw.filter((d) => BREAKING_TYPES.has(d.type));
|
|
22
|
+
const original = new Set(breaking.map(sig));
|
|
23
|
+
const deprecate = deprecator(targetDoc, sunset);
|
|
24
|
+
|
|
25
|
+
// Fixes depend on each other: restoring a removed field that references an
|
|
26
|
+
// enum which lost a value brings that enum break into view, and only a
|
|
27
|
+
// second round can fix it. So run rounds; within a round a fix is accepted
|
|
28
|
+
// when it removes its own break(s), even if it exposes another. At the end the
|
|
29
|
+
// result must contain no break the original target didn't have — otherwise
|
|
30
|
+
// fall back to strict mode, where no fix may introduce anything.
|
|
31
|
+
const relaxed = run({ baseDoc, targetDoc, baseNorm, deprecate, depth, strict: false });
|
|
32
|
+
const ok = [...relaxed.currentBreaking].every((x) => original.has(x));
|
|
33
|
+
const result = ok ? relaxed : run({ baseDoc, targetDoc, baseNorm, deprecate, depth, strict: true });
|
|
34
|
+
|
|
35
|
+
return {
|
|
36
|
+
suggestions: result.suggestions,
|
|
37
|
+
fixedDoc: result.current,
|
|
38
|
+
ops: result.ops,
|
|
39
|
+
before: breaking.length,
|
|
40
|
+
after: result.currentBreaking.size,
|
|
41
|
+
remaining: breaking.filter((c) => result.currentBreaking.has(sig(c))),
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
function run({ baseDoc, targetDoc, baseNorm, deprecate, depth, strict }) {
|
|
46
|
+
let current = clone(targetDoc);
|
|
47
|
+
let currentBreaking = breakingSigs(baseNorm, current);
|
|
48
|
+
const ops = [];
|
|
49
|
+
const all = [];
|
|
50
|
+
const seen = new Set();
|
|
51
|
+
|
|
52
|
+
for (let round = 0; round < 5; round++) {
|
|
53
|
+
const raw = diffSpecs(baseNorm, normalizeSpec(current));
|
|
54
|
+
const ctx = {
|
|
55
|
+
base: baseDoc,
|
|
56
|
+
target: current,
|
|
57
|
+
renames: detectRenames(raw, baseNorm, normalizeSpec(current)),
|
|
58
|
+
enumRenames: detectEnumRenames(raw, baseNorm, normalizeSpec(current)),
|
|
59
|
+
reshaped: reshapedBodies(raw),
|
|
60
|
+
deprecate,
|
|
61
|
+
// Transforms for changes nested inside a reshaped body (see bodyShapeChanged).
|
|
62
|
+
nested: depth < 2
|
|
63
|
+
? (b, t) => fixSpec(b, t, { depth: depth + 1 }).suggestions.flatMap((x) => x.transforms)
|
|
64
|
+
: null,
|
|
65
|
+
};
|
|
66
|
+
const fresh = raw.filter((d) => BREAKING_TYPES.has(d.type) && !seen.has(sig(d)));
|
|
67
|
+
if (fresh.length === 0 && round > 0) break;
|
|
68
|
+
const suggestions = mergeIdentical(raw.filter((d) => BREAKING_TYPES.has(d.type) && (round === 0 || !seen.has(sig(d)) || retry(all, d)))
|
|
69
|
+
.map((c) => suggest(c, ctx)));
|
|
70
|
+
for (const d of raw) if (BREAKING_TYPES.has(d.type)) seen.add(sig(d));
|
|
71
|
+
|
|
72
|
+
let progress = false;
|
|
73
|
+
for (const s of suggestions) {
|
|
74
|
+
if (!s.strategy) { s.status = 'manual'; continue; }
|
|
75
|
+
if (s.changes.every((c) => !currentBreaking.has(sig(c)))) { s.status = 'covered'; continue; }
|
|
76
|
+
let candidate;
|
|
77
|
+
let after;
|
|
78
|
+
try {
|
|
79
|
+
candidate = applyOps(clone(current), s.ops);
|
|
80
|
+
after = breakingSigs(baseNorm, candidate);
|
|
81
|
+
} catch (err) {
|
|
82
|
+
reject(s, `the edited spec no longer parses: ${err.message}`);
|
|
83
|
+
continue;
|
|
84
|
+
}
|
|
85
|
+
const unfixed = s.changes.filter((c) => after.has(sig(c)));
|
|
86
|
+
const introduced = [...after].filter((x) => !currentBreaking.has(x));
|
|
87
|
+
if (unfixed.length > 0) { reject(s, 'the diff engine still reports the breaking change'); continue; }
|
|
88
|
+
// Relaxed rounds let a fix expose a break that a later round fixes (a
|
|
89
|
+
// restored field brings its enum's removed value back into view); the
|
|
90
|
+
// final subset check in fixSpec keeps that honest.
|
|
91
|
+
if (introduced.length > 0 && strict) {
|
|
92
|
+
reject(s, `it would add a breaking change: ${describe(introduced[0])}`);
|
|
93
|
+
continue;
|
|
94
|
+
}
|
|
95
|
+
s.status = 'verified';
|
|
96
|
+
current = candidate;
|
|
97
|
+
currentBreaking = after;
|
|
98
|
+
ops.push(...s.ops);
|
|
99
|
+
progress = true;
|
|
100
|
+
}
|
|
101
|
+
mergeInto(all, suggestions);
|
|
102
|
+
if (!progress) break;
|
|
103
|
+
}
|
|
104
|
+
return { suggestions: all, current, currentBreaking, ops };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** A change rejected in an earlier round gets another chance once other fixes landed. */
|
|
108
|
+
function retry(all, d) {
|
|
109
|
+
return all.some((s) => s.status === 'rejected' && s.changes.some((c) => sig(c) === sig(d)));
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** Later rounds' verdicts replace earlier ones for the same changes. */
|
|
113
|
+
function mergeInto(all, next) {
|
|
114
|
+
for (const s of next) {
|
|
115
|
+
const keys = new Set(s.changes.map(sig));
|
|
116
|
+
for (let i = all.length - 1; i >= 0; i--) {
|
|
117
|
+
if (all[i].changes.some((c) => keys.has(sig(c))) && all[i].status !== 'verified') all.splice(i, 1);
|
|
118
|
+
}
|
|
119
|
+
if (s.status === 'covered' && all.some((x) => x.status === 'verified' && x.changes.some((c) => keys.has(sig(c))))) continue;
|
|
120
|
+
all.push(s);
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
function reject(s, reason) {
|
|
125
|
+
s.status = 'rejected';
|
|
126
|
+
s.reason = reason;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
function breakingSigs(baseNorm, doc) {
|
|
130
|
+
return new Set(diffSpecs(baseNorm, normalizeSpec(doc)).filter((d) => BREAKING_TYPES.has(d.type)).map(sig));
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
function describe(signature) {
|
|
134
|
+
const [type, method, path, field] = signature.split('|');
|
|
135
|
+
return `${type}${method ? ` ${method.toUpperCase()} ${path}` : ''}${field ? ` ${field}` : ''}`;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* A change to a shared component shows up once per operation that uses it;
|
|
140
|
+
* the fix is the same edit each time. One suggestion, many changes.
|
|
141
|
+
*/
|
|
142
|
+
function mergeIdentical(list) {
|
|
143
|
+
const byOps = new Map();
|
|
144
|
+
const out = [];
|
|
145
|
+
for (const s of list) {
|
|
146
|
+
if (!s.strategy || s.ops.length === 0) { out.push(s); continue; }
|
|
147
|
+
const key = JSON.stringify(s.ops);
|
|
148
|
+
const prev = byOps.get(key);
|
|
149
|
+
if (prev) {
|
|
150
|
+
prev.changes.push(...s.changes);
|
|
151
|
+
prev.transforms.push(...s.transforms);
|
|
152
|
+
continue;
|
|
153
|
+
}
|
|
154
|
+
byOps.set(key, s);
|
|
155
|
+
out.push(s);
|
|
156
|
+
}
|
|
157
|
+
return out;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* Marks a restored node deprecated the way the spec's version allows:
|
|
162
|
+
* `deprecated: true` (OpenAPI 3; beside a $ref it is honoured by 3.1 and
|
|
163
|
+
* ignored by 3.0 tools), `x-deprecated` on Swagger 2.0 schemas, and
|
|
164
|
+
* `x-sunset` when a sunset date was given.
|
|
165
|
+
*/
|
|
166
|
+
function deprecator(targetDoc, sunset) {
|
|
167
|
+
const swagger2 = typeof targetDoc.swagger === 'string';
|
|
168
|
+
return (node, note = null) => {
|
|
169
|
+
if (!node || typeof node !== 'object') return node;
|
|
170
|
+
const isSchemaish = !node.responses && !node.in;
|
|
171
|
+
if (swagger2 && isSchemaish) node['x-deprecated'] = true;
|
|
172
|
+
else node.deprecated = true;
|
|
173
|
+
if (sunset) node['x-sunset'] = sunset;
|
|
174
|
+
if (note && !node.$ref) node.description = node.description ? `${node.description} Deprecated: ${note}` : `Deprecated: ${note}`;
|
|
175
|
+
return node;
|
|
176
|
+
};
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
module.exports = { fixSpec };
|