specshield 3.4.17 → 3.5.1

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,195 @@
1
+ 'use strict';
2
+
3
+ const { Command } = require('commander');
4
+ const chalk = require('chalk');
5
+ const fs = require('fs');
6
+ const { loadSpec } = require('../core/loadSpec');
7
+ const { parseSpec } = require('../core/parseSpec');
8
+ const { loadTraffic } = require('../core/replay/traffic');
9
+ const { runReplay, summarize } = require('../core/replay/runReplay');
10
+ const H = require('../core/prove/http');
11
+ const { plural } = require('../core/usage/format');
12
+ const logger = require('../utils/logger');
13
+ const exitAfterFlush = require('../utils/exitAfterFlush');
14
+
15
+ const replay = new Command('replay')
16
+ .description('Replay a sample of real captured requests (HAR or access logs) against a build of the new API, and report every request that worked before and fails now')
17
+ .requiredOption('--against <url>', 'The new build, e.g. http://localhost:8080')
18
+ .requiredOption('--from <file...>', 'Captured traffic: .har files and/or access logs (nginx/Apache, ALB, JSON lines; .gz ok)')
19
+ .option('--baseline <url>', 'The old build: send each request there too and compare side by side (recommended)')
20
+ .option('--spec <file>', 'The new spec: groups traffic by operation, spots removed routes, and checks responses against it')
21
+ .option('--old-spec <file>', 'The old spec: every response must still satisfy it — catches shape breaks even from access logs, which record no bodies')
22
+ .option('--base-path <path>', 'Path prefix in the captured URLs that the spec\'s paths leave out, e.g. /v1')
23
+ .option('--host <host...>', 'Only replay requests captured for these hosts')
24
+ .option('--sample <n>', 'At most this many requests in total', '200')
25
+ .option('--per-operation <n>', 'At most this many requests per operation', '5')
26
+ .option('--seed <n>', 'Sampling seed — the same seed replays the same requests', '1')
27
+ .option('--include-mutating', 'Also replay POST/PUT/PATCH/DELETE (they change data on the build)')
28
+ .option('--allow-remote', 'Allow --against/--baseline hosts that are not local or private')
29
+ .option('--header <header...>', 'Header added to every request, e.g. "Authorization: Bearer $TOKEN" (captured credentials are never replayed)')
30
+ .option('--concurrency <n>', 'Requests in flight', '4')
31
+ .option('--timeout <ms>', 'Per-request timeout', '10000')
32
+ .option('--format <format>', 'Access log format: auto, combined, alb, json', 'auto')
33
+ .option('--show-values', 'Print query values in the report (hidden by default; they can be personal data)')
34
+ .option('--no-summary', 'Skip the GitHub Actions job summary')
35
+ .option('--json', 'Output machine-readable JSON')
36
+ .action(async (opts) => {
37
+ try {
38
+ const against = H.targetUrl(opts.against, { allowRemote: opts.allowRemote });
39
+ const baseline = opts.baseline ? H.targetUrl(opts.baseline, { allowRemote: opts.allowRemote, flag: '--baseline' }) : null;
40
+ const spec = opts.spec ? parseSpec(await loadSpec(opts.spec), opts.spec) : null;
41
+ const oldSpec = opts.oldSpec ? parseSpec(await loadSpec(opts.oldSpec), opts.oldSpec) : null;
42
+ for (const f of opts.from) if (f !== '-' && !fs.existsSync(f)) throw new Error(`Traffic file not found: ${f}`);
43
+
44
+ const traffic = await loadTraffic(opts.from, {
45
+ format: opts.format,
46
+ spec: spec || oldSpec,
47
+ basePath: opts.basePath,
48
+ perOperation: positive(opts.perOperation, '--per-operation'),
49
+ limit: positive(opts.sample, '--sample'),
50
+ seed: Number(opts.seed) || 1,
51
+ includeMutating: opts.includeMutating,
52
+ hosts: opts.host ? new Set(opts.host.map((h) => h.toLowerCase())) : null,
53
+ });
54
+ if (traffic.records.length === 0) throw new Error(emptyReason(traffic.stats, opts));
55
+
56
+ const results = await runReplay(traffic.records, {
57
+ against, baseline,
58
+ headers: H.parseHeaders(opts.header),
59
+ timeoutMs: Number(opts.timeout) || 10000,
60
+ concurrency: positive(opts.concurrency, '--concurrency'),
61
+ spec,
62
+ oldSpec,
63
+ basePath: opts.basePath,
64
+ });
65
+ if (results.every((r) => r.verdict === 'error')) throw new Error(`Can't reach the build: ${results[0].detail}`);
66
+
67
+ const s = summarize(results);
68
+ const bodies = Boolean(baseline) || traffic.records.some((r) => r.recorded.json !== undefined);
69
+ const report = { against, baseline, reference: baseline ? 'baseline' : 'recorded', bodies, oldSpec: Boolean(oldSpec), traffic: traffic.stats, totals: s.totals, operations: s.operations };
70
+ if (opts.json) process.stdout.write(JSON.stringify(toJson(report, opts), null, 2) + '\n');
71
+ else process.stdout.write(render(report, opts) + '\n');
72
+
73
+ if (opts.summary !== false && process.env.GITHUB_ACTIONS === 'true' && process.env.GITHUB_STEP_SUMMARY) {
74
+ try { fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, markdown(report, opts) + '\n'); } catch { /* best-effort */ }
75
+ }
76
+ exitAfterFlush(s.totals.broken + s.totals.changed > 0 ? 1 : 0);
77
+ } catch (err) {
78
+ logger.error(`Error: ${err.message}`);
79
+ process.exit(2);
80
+ }
81
+ });
82
+
83
+ function positive(v, flag) {
84
+ const n = Number(v);
85
+ if (!Number.isInteger(n) || n < 1) throw new Error(`${flag} must be a whole number ≥ 1`);
86
+ return n;
87
+ }
88
+
89
+ function emptyReason(st, opts) {
90
+ if (st.read === 0) return 'No requests found in the traffic files';
91
+ if (st.bodilessWrites === st.read) return `All ${st.read} logged requests change data, and access logs don't record request bodies — record a HAR to replay writes`;
92
+ if (st.mutatingSkipped + st.bodilessWrites === st.read) return `All ${st.read} captured requests change data (POST/PUT/PATCH/DELETE); pass --include-mutating to replay them`;
93
+ if (st.otherHosts) return `No requests for ${opts.host.join(', ')} (${st.otherHosts} for other hosts)`;
94
+ return 'Nothing to replay after filtering';
95
+ }
96
+
97
+ /** "/orders?status=open&limit=5" → "/orders?status=…&limit=…" unless --show-values. */
98
+ function target(rec, showValues) {
99
+ if (!rec.query) return rec.path;
100
+ if (showValues) return `${rec.path}?${rec.query}`;
101
+ return `${rec.path}?${rec.query.split('&').map((p) => `${p.split('=')[0]}=…`).join('&')}`;
102
+ }
103
+
104
+ function toJson(r, opts) {
105
+ const req = (x) => ({
106
+ method: x.rec.method, target: target(x.rec, opts.showValues), operation: x.rec.operation,
107
+ reference: x.ref, build: x.cand, verdict: x.verdict, detail: x.detail,
108
+ ...(x.diff ? { missing: x.diff.missing.map(field), changed: x.diff.changed.map((c) => ({ ...c, path: field(c.path) })) } : {}),
109
+ ...(x.specDrift ? { specDrift: x.specDrift } : {}),
110
+ ...(x.oldContract ? { oldContract: x.oldContract } : {}),
111
+ ...(x.excerpt && opts.showValues ? { response: x.excerpt } : {}),
112
+ });
113
+ return {
114
+ against: r.against,
115
+ baseline: r.baseline,
116
+ reference: r.reference,
117
+ comparedBodies: r.bodies,
118
+ checkedAgainstOldSpec: r.oldSpec,
119
+ traffic: r.traffic,
120
+ totals: r.totals,
121
+ operations: r.operations.map(({ examples, drift, ...o }) => ({ ...o, examples: examples.map(req), specDrift: drift.map(req) })),
122
+ };
123
+ }
124
+
125
+ /** ".items[].id" → "items[].id" */
126
+ function field(p) {
127
+ return p.replace(/^\./, '') || '(root)';
128
+ }
129
+
130
+ const MARK = {
131
+ broken: chalk.red('✖'), changed: chalk.red('▲'), error: chalk.red('!'), inconclusive: chalk.yellow('?'), improved: chalk.cyan('↑'), ok: chalk.green('✔'),
132
+ };
133
+
134
+ function render(r, opts) {
135
+ const t = r.totals;
136
+ const lines = [''];
137
+ lines.push(chalk.bold(` SpecShield™ Replay — ${r.against}`));
138
+ lines.push(chalk.gray(' ─────────────────────────────────────────'));
139
+ const sources = r.traffic.files.map((f) => `${f.file} (${f.kind}, ${f.requests})`).join(', ');
140
+ lines.push(` ${chalk.gray('Traffic')} ${plural(r.traffic.sampled, 'request')} sampled from ${plural(r.traffic.considered, 'captured request')} across ${plural(r.traffic.operations, 'operation')}`);
141
+ lines.push(chalk.gray(` ${sources}`));
142
+ if (r.traffic.mutatingSkipped) lines.push(chalk.gray(` ${plural(r.traffic.mutatingSkipped, 'write')} not replayed (--include-mutating to replay them)`));
143
+ if (r.traffic.bodilessWrites) lines.push(chalk.gray(` ${plural(r.traffic.bodilessWrites, 'write')} from access logs not replayed: logs don't record request bodies`));
144
+ lines.push(` ${chalk.gray('Compared')} ${r.baseline ? `with the old build at ${r.baseline}, side by side` : 'with the recorded responses — use --baseline <old build> to rule out data differences'}`);
145
+ if (r.oldSpec) lines.push(chalk.gray(' and every response checked against the old spec'));
146
+ else if (!r.bodies) lines.push(chalk.yellow(' status codes only: access logs record no bodies — add --old-spec (or --baseline) to compare responses'));
147
+ lines.push('');
148
+
149
+ const bad = t.broken + t.changed;
150
+ if (bad === 0) lines.push(chalk.green(` ✔ No request that worked before fails now (${plural(results(t), 'request')}${!r.bodies && !r.oldSpec ? ', by status code' : ''})`));
151
+ else lines.push(chalk.red.bold(` ✖ ${plural(bad, 'request')} that worked before ${bad === 1 ? 'breaks' : 'break'} on the new build`));
152
+ const counts = Object.entries(t).filter(([, n]) => n > 0).map(([k, n]) => `${MARK[k]} ${n} ${k}`);
153
+ lines.push(` ${counts.join(' ')}`);
154
+
155
+ for (const o of r.operations) {
156
+ if (o.broken + o.changed + o.error + o.inconclusive === 0 && !o.drift.length) continue;
157
+ lines.push('');
158
+ const head = [o.broken && chalk.red(`${o.broken} broken`), o.changed && chalk.red(`${o.changed} changed`), o.inconclusive && chalk.yellow(`${o.inconclusive} inconclusive`), o.error && chalk.red(`${o.error} error`)].filter(Boolean).join(', ');
159
+ lines.push(` ${chalk.bold(o.operation)} ${chalk.gray(`${o.total} replayed`)}${head ? ` · ${head}` : ''}`);
160
+ for (const x of o.examples) {
161
+ lines.push(` ${MARK[x.verdict]} ${x.rec.method} ${target(x.rec, opts.showValues)}`);
162
+ lines.push(chalk.gray(` ${x.detail}`));
163
+ if (x.excerpt && opts.showValues) lines.push(chalk.gray(` response: ${x.excerpt}`));
164
+ }
165
+ for (const x of o.drift) lines.push(chalk.yellow(` ⚠ the build's response doesn't match the new spec: ${x.specDrift.join('; ')}`));
166
+ }
167
+ if (!opts.showValues && r.operations.some((o) => o.examples.some((x) => x.rec.query))) {
168
+ lines.push('');
169
+ lines.push(chalk.gray(' Query values are hidden (they can be personal data); --show-values prints them.'));
170
+ }
171
+ lines.push('');
172
+ return lines.join('\n');
173
+ }
174
+
175
+ function results(t) {
176
+ return Object.values(t).reduce((a, b) => a + b, 0);
177
+ }
178
+
179
+ function markdown(r, opts) {
180
+ const t = r.totals;
181
+ const bad = t.broken + t.changed;
182
+ const out = ['### SpecShield replay', ''];
183
+ out.push(bad ? `❌ **${plural(bad, 'request')} that worked before ${bad === 1 ? 'breaks' : 'break'} on the new build**` : `✅ No request that worked before fails now (${plural(results(t), 'request')} replayed)`);
184
+ out.push('', `Compared with ${r.baseline ? 'the old build, side by side' : 'the recorded responses'} · ${Object.entries(t).filter(([, n]) => n).map(([k, n]) => `${n} ${k}`).join(' · ')}`);
185
+ const rows = r.operations.filter((o) => o.examples.length);
186
+ if (rows.length) {
187
+ out.push('', '| Operation | Request | Result |', '|---|---|---|');
188
+ for (const o of rows) {
189
+ for (const x of o.examples) out.push(`| \`${o.operation}\` | \`${x.rec.method} ${target(x.rec, opts.showValues).replace(/\|/g, '\\|')}\` | ${x.verdict}: ${x.detail.replace(/\|/g, '\\|')} |`);
190
+ }
191
+ }
192
+ return out.join('\n');
193
+ }
194
+
195
+ module.exports = replay;
@@ -158,8 +158,10 @@ function validateConfig(config, filePath) {
158
158
  throw new Error(`Config error in "${filePath}": gate.${key} must be a string`);
159
159
  }
160
160
  }
161
- if (g.upload !== undefined && typeof g.upload !== 'boolean') {
162
- throw new Error(`Config error in "${filePath}": gate.upload must be a boolean`);
161
+ for (const key of ['upload', 'prove']) {
162
+ if (g[key] !== undefined && typeof g[key] !== 'boolean') {
163
+ throw new Error(`Config error in "${filePath}": gate.${key} must be a boolean`);
164
+ }
163
165
  }
164
166
  valid.gate = {
165
167
  spec: g.spec,
@@ -167,6 +169,7 @@ function validateConfig(config, filePath) {
167
169
  waivers: g.waivers,
168
170
  maxWaiverDays: g.maxWaiverDays !== undefined ? Number(g.maxWaiverDays) : undefined,
169
171
  upload: g.upload,
172
+ prove: g.prove,
170
173
  org: g.org,
171
174
  };
172
175
  }
@@ -10,6 +10,7 @@ const { classifyChanges } = require('../classifyChanges');
10
10
  const { resolveBaseline } = require('./baseline');
11
11
  const G = require('./git');
12
12
  const W = require('./waivers');
13
+ const P = require('../prove');
13
14
 
14
15
  /**
15
16
  * One gate run: the spec at the merge base vs the spec in the working tree,
@@ -23,7 +24,7 @@ async function runGate(opts) {
23
24
  const {
24
25
  spec, cwd = process.cwd(), base, env = process.env, fetch = true,
25
26
  mode = 'blocking', waiversFile = W.DEFAULT_FILE, maxWaiverDays = W.DEFAULT_MAX_DAYS,
26
- ignore = [], usage = null, now = Date.now(),
27
+ ignore = [], usage = null, now = Date.now(), prove = false,
27
28
  } = opts;
28
29
  if (!['blocking', 'shadow'].includes(mode)) throw new Error(`mode must be "blocking" or "shadow", got "${mode}"`);
29
30
 
@@ -69,11 +70,13 @@ async function runGate(opts) {
69
70
  try { baseW = baseWText ? W.parseWaivers(baseWText, wOpts).waivers : []; } catch { /* the baseline's file may predate today's rules */ }
70
71
 
71
72
  let breaking = [];
73
+ let docs = null;
72
74
  if (out.specStatus === 'deleted') {
73
75
  breaking = [{ type: 'SPEC_REMOVED', path: null, method: null, field: null, severity: 'error', description: `The spec ${specRel} was deleted` }];
74
76
  } else if (out.specStatus === 'changed') {
75
77
  const baseDoc = parseSpec(baseText, specRel);
76
78
  const headDoc = parseSpec(headText, specRel);
79
+ docs = { baseDoc, headDoc };
77
80
  let result = classifyChanges(diffSpecs(normalizeSpec(baseDoc), normalizeSpec(headDoc)));
78
81
  out.nonBreaking = result.additions.length + result.modifications.length + result.warnings.length;
79
82
  if (ignore.length) {
@@ -91,6 +94,12 @@ async function runGate(opts) {
91
94
  }
92
95
 
93
96
  out.breaking = breaking.map(withKey);
97
+ if (prove && docs) {
98
+ // A proof per finding: the request that worked at the baseline and fails now.
99
+ const proofs = P.witnesses(docs.baseDoc, docs.headDoc);
100
+ out.breaking = out.breaking.map((c) => ({ ...c, proof: P.proofFor(c, proofs) }));
101
+ out.proofs = P.summarize(out.breaking);
102
+ }
94
103
  const { blocking, waived, used } = W.applyWaivers(out.breaking, headW.waivers, now);
95
104
  out.blocking = blocking;
96
105
  out.waived = waived;
@@ -0,0 +1,241 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * One operation's contract, read from a raw spec (OpenAPI 3.x or Swagger 2.0):
5
+ * its parameters, request body and responses. Plus the two things a witness
6
+ * needs from it: build an HTTP request, and say whether a request satisfies it.
7
+ *
8
+ * Request = {
9
+ * method: 'POST', path: '/orders/{id}',
10
+ * params: { 'path:id': 1, 'query:limit': 10, 'header:X-Trace': 'abc' }, // typed values
11
+ * body: <JSON> | undefined,
12
+ * }
13
+ *
14
+ * Parameter values are kept typed; they are checked the way a server reads
15
+ * them off the wire (strings parsed into the declared type).
16
+ */
17
+
18
+ const L = require('../fix/locate');
19
+ const S = require('./schema');
20
+ const { generate, OMIT } = require('./instance');
21
+
22
+ const JSON_TYPE = /^application\/(.+\+)?json$|^\*\/\*$/i;
23
+ const FORM_TYPE = /^application\/x-www-form-urlencoded$/i;
24
+
25
+ function contractOf(doc, method, path) {
26
+ const m = method.toLowerCase();
27
+ const op = L.operationPtr(doc, m, path);
28
+ if (!op) return { doc, method: m.toUpperCase(), path, exists: false, params: [], body: null, responses: {} };
29
+
30
+ const params = [];
31
+ let body = null;
32
+ for (const { node } of L.parameterPtrs(doc, m, path)) {
33
+ if (node.in === 'body') {
34
+ body = { schema: node.schema || null, required: Boolean(node.required), mediaType: 'application/json', json: true, form: false, structured: true };
35
+ continue;
36
+ }
37
+ // Swagger 2.0 formData fields stay parameters (the diff engine reports them
38
+ // as parameters); they travel as a form body.
39
+ params.push({
40
+ name: node.name,
41
+ in: node.in,
42
+ key: `${node.in}:${node.name}`,
43
+ required: node.in === 'path' ? true : Boolean(node.required),
44
+ schema: node.schema || (node.type ? inlineSchema(node) : node.content ? contentSchema(node.content) : null),
45
+ style: node.style || null,
46
+ explode: node.explode,
47
+ collectionFormat: node.collectionFormat || null,
48
+ });
49
+ }
50
+
51
+ const rb = S.deref(doc, L.get(doc, [...op, 'requestBody']));
52
+ if (rb && rb.content) {
53
+ const types = Object.keys(rb.content);
54
+ const jsonType = types.find((t) => JSON_TYPE.test(t));
55
+ const formType = types.find((t) => FORM_TYPE.test(t));
56
+ const type = jsonType || formType || types[0];
57
+ body = {
58
+ schema: (rb.content[type] && rb.content[type].schema) || null,
59
+ required: Boolean(rb.required),
60
+ mediaType: type,
61
+ json: Boolean(jsonType),
62
+ form: !jsonType && Boolean(formType),
63
+ structured: Boolean(jsonType || formType),
64
+ };
65
+ }
66
+
67
+ const responses = {};
68
+ for (const code of Object.keys(L.get(doc, [...op, 'responses']) || {})) {
69
+ const ptr = L.responseSchemaPtr(doc, m, path, code);
70
+ responses[code] = { schema: ptr ? L.get(doc, ptr) : null };
71
+ }
72
+ return { doc, method: m.toUpperCase(), path, exists: true, params, body, responses };
73
+ }
74
+
75
+ /** Swagger 2.0 non-body parameters declare their schema inline. */
76
+ function inlineSchema(p) {
77
+ const { name, in: _in, required, description, collectionFormat, allowEmptyValue, ...schema } = p;
78
+ return schema;
79
+ }
80
+
81
+ function contentSchema(content) {
82
+ const first = Object.values(content)[0];
83
+ return first && first.schema ? first.schema : null;
84
+ }
85
+
86
+ /** The response entry a status code falls under: exact, "2XX", then "default". */
87
+ function responseFor(contract, code) {
88
+ const c = String(code);
89
+ const r = contract.responses;
90
+ for (const key of [c, `${c[0]}XX`, `${c[0]}xx`, 'default']) if (r[key]) return { key, ...r[key] };
91
+ return null;
92
+ }
93
+
94
+ // ─── building requests ──────────────────────────────────────────────────────
95
+
96
+ /**
97
+ * A request for `contract`. Required parameters always; optional ones too with
98
+ * `full`. `target` puts one value in place: { param: 'query:limit', value } or
99
+ * { body: steps, value } (value may be OMIT). `like` copies parameter values
100
+ * from another request where this contract declares the same parameter, so a
101
+ * witness and its control differ only where they must.
102
+ */
103
+ function buildRequest(contract, { full = false, variant = 0, examples = true, target = null, like = null } = {}) {
104
+ const { doc } = contract;
105
+ const params = {};
106
+ for (const p of contract.params) {
107
+ if (target && target.param === p.key) {
108
+ if (target.value !== OMIT) params[p.key] = target.value;
109
+ continue;
110
+ }
111
+ if (like && like.params[p.key] !== undefined) { params[p.key] = like.params[p.key]; continue; }
112
+ if (!p.required && !full) continue;
113
+ params[p.key] = p.schema ? generate(doc, p.schema, { side: 'request', full, examples, variant }) : 'abc';
114
+ }
115
+ if (target && target.param && !contract.params.some((p) => p.key === target.param) && target.value !== OMIT) {
116
+ params[target.param] = target.value;
117
+ }
118
+
119
+ let body;
120
+ if (contract.body && contract.body.structured && contract.body.schema) {
121
+ const bodyTarget = target && target.body ? { steps: target.body, value: target.value } : null;
122
+ if (like && like.body !== undefined && !bodyTarget) body = like.body;
123
+ else if (contract.body.required || full || bodyTarget || (like && like.body !== undefined)) {
124
+ body = generate(doc, contract.body.schema, { side: 'request', full, examples, variant, target: bodyTarget });
125
+ }
126
+ }
127
+ return { method: contract.method, path: contract.path, params, body, mediaType: contract.body ? contract.body.mediaType : null };
128
+ }
129
+
130
+ // ─── checking requests ──────────────────────────────────────────────────────
131
+
132
+ /**
133
+ * Does `req` satisfy `contract`? Returns the reasons it doesn't, each tagged
134
+ * with the part of the request it is about ({ part: 'query:limit' | 'body' |
135
+ * 'operation' }). Undeclared parameters are not an error — servers ignore them.
136
+ */
137
+ function checkRequest(contract, req) {
138
+ const problems = [];
139
+ if (!contract.exists) {
140
+ return [{ part: 'operation', message: `${contract.method} ${contract.path} is not in this spec`, errors: [] }];
141
+ }
142
+ for (const p of contract.params) {
143
+ const v = req.params[p.key];
144
+ if (v === undefined) {
145
+ if (p.required) problems.push({ part: p.key, message: `${p.in} parameter "${p.name}" is required`, errors: [] });
146
+ continue;
147
+ }
148
+ if (!p.schema) continue;
149
+ const r = S.validator(contract.doc, p.schema, { side: 'request', kind: 'param' })(wire(v));
150
+ if (!r.ok) problems.push({ part: p.key, message: r.errors.map((e) => S.describeError(e, `${p.in} parameter "${p.name}"`)).join('; '), errors: r.errors });
151
+ }
152
+ const b = contract.body;
153
+ if (b && b.structured && b.schema) {
154
+ if (req.body === undefined) {
155
+ if (b.required) problems.push({ part: 'body', message: 'a request body is required', errors: [] });
156
+ } else {
157
+ // Form fields arrive as text and are parsed into the declared types, like parameters.
158
+ const r = S.validator(contract.doc, b.schema, { side: 'request', kind: b.form ? 'param' : 'body' })(req.body);
159
+ if (!r.ok) problems.push({ part: 'body', label: 'body', message: r.errors.map((e) => S.describeError(e)).join('; '), errors: r.errors });
160
+ }
161
+ }
162
+ return problems;
163
+ }
164
+
165
+ /** A parameter value as a server receives it: strings (or a list of them). */
166
+ function wire(v) {
167
+ if (Array.isArray(v)) return v.map((x) => (typeof x === 'object' && x !== null ? JSON.stringify(x) : String(x)));
168
+ if (v !== null && typeof v === 'object') return v; // deepObject: leave as an object
169
+ return String(v);
170
+ }
171
+
172
+ /** Check a response body against the contract's schema for `code`. */
173
+ function checkResponse(contract, code, body) {
174
+ const r = responseFor(contract, code);
175
+ if (!r) return { ok: false, documented: false, errors: [{ path: '', keyword: 'status', message: `status ${code} is not documented`, params: {} }] };
176
+ if (!r.schema) return { ok: true, documented: true, errors: [] };
177
+ return { documented: true, ...S.validator(contract.doc, r.schema, { side: 'response' })(body) };
178
+ }
179
+
180
+ // ─── rendering ──────────────────────────────────────────────────────────────
181
+
182
+ /** "/orders/{id}?limit=10" with values filled in, plus the headers. */
183
+ function urlOf(contract, req) {
184
+ let path = req.path;
185
+ const query = [];
186
+ const headers = {};
187
+ const form = [];
188
+ for (const [key, v] of Object.entries(req.params)) {
189
+ const [loc, ...rest] = key.split(':');
190
+ const name = rest.join(':');
191
+ const p = contract.params.find((x) => x.key === key) || { name, in: loc };
192
+ if (loc === 'path') path = path.split(`{${name}}`).join(encodeURIComponent(serialize(v, p, ',')));
193
+ else if (loc === 'query') {
194
+ const explode = p.explode !== undefined ? p.explode : (p.collectionFormat ? p.collectionFormat === 'multi' : true);
195
+ if (Array.isArray(v) && explode) for (const x of v) query.push(`${encodeURIComponent(name)}=${encodeURIComponent(scalar(x))}`);
196
+ else query.push(`${encodeURIComponent(name)}=${encodeURIComponent(serialize(v, p, delimiter(p)))}`);
197
+ } else if (loc === 'formData') {
198
+ const explode = p.collectionFormat === 'multi';
199
+ if (Array.isArray(v) && explode) for (const x of v) form.push(`${encodeURIComponent(name)}=${encodeURIComponent(scalar(x))}`);
200
+ else form.push(`${encodeURIComponent(name)}=${encodeURIComponent(serialize(v, p, delimiter(p)))}`);
201
+ } else if (loc === 'header') headers[name] = serialize(v, p, ',');
202
+ else if (loc === 'cookie') headers.Cookie = [headers.Cookie, `${name}=${serialize(v, p, ',')}`].filter(Boolean).join('; ');
203
+ }
204
+ return { path: path + (query.length ? `?${query.join('&')}` : ''), headers, form: form.length ? form.join('&') : null };
205
+ }
206
+
207
+ /**
208
+ * A form body for a structured value, in the bracket notation most servers
209
+ * parse (Rails, PHP, Stripe): a[b]=1&list[0]=x.
210
+ */
211
+ function formEncode(value, prefix = '') {
212
+ const out = [];
213
+ const add = (k, v) => out.push(`${encodeURIComponent(k).replace(/%5B/g, '[').replace(/%5D/g, ']')}=${encodeURIComponent(v)}`);
214
+ const walk = (v, key) => {
215
+ if (v === undefined) return;
216
+ if (v === null) { add(key, ''); return; }
217
+ if (Array.isArray(v)) { v.forEach((x, i) => walk(x, `${key}[${i}]`)); return; }
218
+ if (typeof v === 'object') { for (const [k, x] of Object.entries(v)) walk(x, key ? `${key}[${k}]` : k); return; }
219
+ add(key, String(v));
220
+ };
221
+ walk(value, prefix);
222
+ return out.join('&');
223
+ }
224
+
225
+ function delimiter(p) {
226
+ if (p.collectionFormat === 'ssv' || p.style === 'spaceDelimited') return ' ';
227
+ if (p.collectionFormat === 'pipes' || p.style === 'pipeDelimited') return '|';
228
+ if (p.collectionFormat === 'tsv') return '\t';
229
+ return ',';
230
+ }
231
+
232
+ function serialize(v, p, sep) {
233
+ if (Array.isArray(v)) return v.map(scalar).join(sep);
234
+ return scalar(v);
235
+ }
236
+
237
+ function scalar(v) {
238
+ return v !== null && typeof v === 'object' ? JSON.stringify(v) : String(v);
239
+ }
240
+
241
+ module.exports = { contractOf, responseFor, buildRequest, checkRequest, checkResponse, urlOf, wire, formEncode, JSON_TYPE };
@@ -0,0 +1,135 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * `prove --against <url>`: send each witness to a running build of the new
5
+ * API and see whether the build behaves the way the new spec says it will.
6
+ *
7
+ * Every request witness travels with a control — the same request, valid under
8
+ * the new spec. A rejected witness next to an accepted control is a confirmed
9
+ * break; both rejected means the build is refusing something else (missing
10
+ * credentials, missing test data), so the result is inconclusive rather than
11
+ * a false confirmation.
12
+ *
13
+ * confirmed the build does what the witness predicts
14
+ * not-reproduced it doesn't: it accepts the request, or still sends what
15
+ * old clients expect — the spec and the code disagree
16
+ * inconclusive the outcome can't be attributed to the change
17
+ * skipped not sent (a write without --include-mutating, or no witness)
18
+ * error no response
19
+ */
20
+
21
+ const L = require('../fix/locate');
22
+ const C = require('./contract');
23
+ const H = require('./http');
24
+ const { relatesTo } = require('./relate');
25
+ const S = require('./schema');
26
+
27
+ async function confirmAll(items, opts) {
28
+ const { baseDoc, against, headers = {}, includeMutating = false, timeoutMs = 10000, concurrency = 4, http = H.send } = opts;
29
+ const run = async ({ diff, witness: w }) => {
30
+ if (!w.request || (w.status !== 'proven' && w.status !== 'example')) return { outcome: 'skipped', detail: 'nothing to send' };
31
+ if (!includeMutating && !H.SAFE_METHODS.has(w.request.method)) {
32
+ return { outcome: 'skipped', detail: `${w.request.method} changes data; pass --include-mutating to send it` };
33
+ }
34
+ const call = (req) => http({
35
+ method: req.method,
36
+ url: against + req.path,
37
+ headers: { ...headers, ...req.headers },
38
+ body: req.bodyText || (req.body === null ? undefined : JSON.stringify(req.body)),
39
+ timeoutMs,
40
+ });
41
+ try {
42
+ const res = await call(w.request);
43
+ const out = { status: res.status, ...judge(diff, w, res, baseDoc) };
44
+ if (w.expect === 'rejected' && w.control && res.status >= 400 && res.status !== 401 && res.status !== 403) {
45
+ const ctrl = await call(w.control);
46
+ out.controlStatus = ctrl.status;
47
+ Object.assign(out, withControl(res, ctrl));
48
+ }
49
+ return out;
50
+ } catch (err) {
51
+ return { outcome: 'error', detail: H.describeNetworkError(err) };
52
+ }
53
+ };
54
+ const results = await H.pool(items, concurrency, run);
55
+ items.forEach((it, i) => { it.witness.run = results[i]; });
56
+ return items;
57
+ }
58
+
59
+ function judge(diff, w, res, baseDoc) {
60
+ const s = res.status;
61
+ if (s === 401 || s === 403) return { outcome: 'inconclusive', detail: `HTTP ${s} — the build wants credentials; pass them with --header` };
62
+
63
+ if (w.expect === 'not-found' || w.expect === 'method-not-allowed') {
64
+ if (s === 404 || s === 405 || s === 501) return { outcome: 'confirmed', detail: `HTTP ${s}: the operation is gone` };
65
+ if (s < 400) return { outcome: 'not-reproduced', detail: `HTTP ${s}: the build still serves it, though the new spec removed it` };
66
+ return { outcome: 'inconclusive', detail: `HTTP ${s}` };
67
+ }
68
+
69
+ if (w.expect === 'rejected') {
70
+ if (s < 400) return { outcome: 'not-reproduced', detail: `HTTP ${s}: the build accepted it. The new spec says it should be rejected — the spec and the code disagree` };
71
+ return { outcome: 'confirmed', detail: `HTTP ${s}: rejected${s >= 500 ? ' (a server error, not a 4xx)' : ''}`, weak: true };
72
+ }
73
+
74
+ if (w.expect === 'ignored') {
75
+ if (s >= 400) return { outcome: 'confirmed', detail: `HTTP ${s}: the build rejects requests that still send it` };
76
+ return { outcome: 'inconclusive', detail: `HTTP ${s}: accepted — whether the value is still used can't be seen from outside` };
77
+ }
78
+
79
+ if (w.expect === 'response') {
80
+ const code = w.response.status;
81
+ if (!sameStatus(code, s)) return { outcome: 'inconclusive', detail: `HTTP ${s} instead of ${code} — check the test data` };
82
+ if (res.json === undefined) return { outcome: 'inconclusive', detail: `HTTP ${s} with no JSON body` };
83
+ const parsed = L.parseField(diff.field);
84
+ const oldC = C.contractOf(baseDoc, diff.method, diff.path);
85
+ const check = C.checkResponse(oldC, code, res.json);
86
+ const related = parsed ? (check.errors || []).filter((e) => relatesTo([e], parsed.steps)) : [];
87
+ if (related.length) {
88
+ return { outcome: 'confirmed', detail: `the build's response breaks old clients: ${related.map((e) => S.describeError(e, 'response')).join('; ')}` };
89
+ }
90
+ if (parsed && emptyAlong(res.json, parsed.steps)) return { outcome: 'inconclusive', detail: 'the response had no data at that field (an empty list?) — seed some test data' };
91
+ if (w.status === 'example' && parsed && present(res.json, parsed.steps)) {
92
+ return { outcome: 'not-reproduced', detail: `the build still sends ${diff.field.replace(/^responses\.[^.]+\./, '')}` };
93
+ }
94
+ return { outcome: w.status === 'example' ? 'confirmed' : 'not-reproduced', detail: w.status === 'example' ? 'the field is gone from the response' : 'the response still matches what old clients expect here' };
95
+ }
96
+ return { outcome: 'inconclusive', detail: `HTTP ${s}` };
97
+ }
98
+
99
+ function withControl(res, ctrl) {
100
+ if (ctrl.status < 400) {
101
+ return { outcome: 'confirmed', weak: false, detail: `HTTP ${res.status}: rejected, while the same request valid under the new spec got HTTP ${ctrl.status}` };
102
+ }
103
+ return { outcome: 'inconclusive', weak: false, detail: `HTTP ${res.status}, but the control request was rejected too (HTTP ${ctrl.status}) — check credentials and test data` };
104
+ }
105
+
106
+ function sameStatus(documented, actual) {
107
+ const d = String(documented);
108
+ const a = String(actual);
109
+ if (d === a) return true;
110
+ if (/^[1-5]xx$/i.test(d)) return d[0] === a[0];
111
+ return d === 'default';
112
+ }
113
+
114
+ /** Walks an actual response along diff steps; true when an array on the way is empty. */
115
+ function emptyAlong(body, steps) {
116
+ let cur = body;
117
+ for (const s of steps) {
118
+ if (cur === null || cur === undefined) return false;
119
+ if (s.items) { if (!Array.isArray(cur)) return false; if (cur.length === 0) return true; cur = cur[0]; } else if (s.prop !== undefined) cur = cur[s.prop];
120
+ else if (s.map) { const k = Object.keys(cur)[0]; if (k === undefined) return true; cur = cur[k]; }
121
+ }
122
+ return false;
123
+ }
124
+
125
+ function present(body, steps) {
126
+ let cur = body;
127
+ for (const s of steps) {
128
+ if (cur === null || cur === undefined) return false;
129
+ if (s.items) { if (!Array.isArray(cur) || !cur.length) return false; cur = cur[0]; } else if (s.prop !== undefined) { if (!(s.prop in Object(cur))) return false; cur = cur[s.prop]; }
130
+ else if (s.map) { const k = Object.keys(cur)[0]; if (k === undefined) return false; cur = cur[k]; }
131
+ }
132
+ return cur !== undefined;
133
+ }
134
+
135
+ module.exports = { confirmAll, judge };