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.
package/CHANGELOG.md CHANGED
@@ -1,9 +1,66 @@
1
1
  # SpecShield CLI changelog
2
2
 
3
- ## Unreleased — a gate teams can leave blocking: `specshield gate`
3
+ ## Unreleased — proof, not opinion: `specshield prove` and `specshield replay`
4
4
 
5
5
  ### Added
6
6
 
7
+ - **`specshield prove <base> <target>`**: for every breaking change, the exact request that
8
+ worked before and fails now. For a response change, it gives a body the new spec allows that
9
+ clients of the old spec reject.
10
+ - **How a witness is found.** Candidate values for the changed location are enums, bounds just
11
+ past the new limits, pattern matches, every `oneOf` branch, and absence. Each is validated
12
+ with ajv against both full specs.
13
+ - **Isolation.** The rest of the witness is repaired to satisfy both specs. Each request
14
+ witness carries a control that differs only at the change, which proves the cause.
15
+ - **Results.** Each change is one of: proven, example (real but not rejectable: a removed
16
+ optional field), compatible (with a structural reason), or no proof (with the reason why).
17
+ - **A sound subschema check** behind the *compatible* verdicts. It recognizes added optional
18
+ properties, extended enums, relaxed bounds, widened types and numeric formats, and `oneOf`
19
+ branches the engine reports as changed only because they were reordered.
20
+ - Recursive schemas are compared coinductively.
21
+ - It assumes a closed world (clients send only documented fields).
22
+ - **`prove --against <url>`** sends every witness to a running build and reports what it does.
23
+ - *confirmed*: the witness is rejected while its control is accepted.
24
+ - *not reproduced*: the build still accepts it, so the spec and the code disagree.
25
+ - *inconclusive*: credentials or test data, not the change.
26
+ - Writes are sent only with `--include-mutating`; remote hosts only with `--allow-remote`.
27
+ - **`specshield replay`** replays a seeded sample of real traffic against the new build.
28
+ - **Sources:** HAR files, or access logs (nginx/Apache, ALB, JSON lines).
29
+ - **Sampling:** stratified per operation.
30
+ - **References:** the old build side by side (`--baseline`), the recorded responses, or the
31
+ old spec as the oracle (`--old-spec`, which works from status-only access logs).
32
+ - **Verdicts:** broken (worked before, fails now), changed (lost fields or changed types), or
33
+ inconclusive (auth, throttling, a 404 that missing test data could explain).
34
+ - **Safety:** captured credentials are never replayed, query values are hidden unless
35
+ `--show-values`, and writes are never rebuilt from body-less logs.
36
+ - **`gate --prove`** (also `gate.prove: true` in `.specshield.yml`) attaches the proof to every
37
+ blocking finding, in the terminal and as a collapsible *Proof* section in the GitHub job summary.
38
+ - Form-encoded request bodies (OpenAPI 3 `application/x-www-form-urlencoded`, Swagger 2.0
39
+ `formData`) are proven on their parsed values and sent bracket-encoded.
40
+
41
+ ### Tested on real data
42
+
43
+ - **GitHub REST API**, Apr → Oct 2026, 112 findings: 35 proven, 11 by example, 41 compatible
44
+ (reordered `oneOf` rule branches, widened numeric formats, narrowed responses), 25 without
45
+ proof (removed status codes and shared schemas). 1.1 s.
46
+ - **Stripe**, Mar → Sep 2026, 112 findings: 89 proven, 19 by example, 4 without proof. Its
47
+ 1,972 per-endpoint changes ran in 16 s, after two fixes:
48
+ - spec components are now registered with ajv once, instead of recompiled per schema;
49
+ - the subschema check now compares lazily with memoization, instead of inlining.
50
+ - **Kubernetes** (Swagger 2.0), Jul → Oct 2026, 103 findings: 58 proven. 384 per-endpoint
51
+ "field became required" findings on responses are shown compatible.
52
+ - Every proof on all three was isolated to its own change.
53
+ - **A Spring Boot service**, old and new builds side by side: all 6 proofs confirmed on the new
54
+ build, and all 6 *not reproduced* on a build whose code hadn't changed. Replay from a HAR,
55
+ and from an nginx log with `--old-spec`, found the removed field, the type change and the
56
+ rejected writes.
57
+
58
+ ## 3.5.0 — 2026-10-29 — gate, fix, safe removal
59
+
60
+ ### A gate teams can leave blocking: `specshield gate`
61
+
62
+ #### Added
63
+
7
64
  - **`specshield gate [spec]`** — the CI check. Compares the spec with the merge base of
8
65
  the branch (never the base branch's tip or production), so changes merged since the
9
66
  branch forked never fail an unrelated PR. Baseline from the CI event: GitHub
@@ -20,7 +77,7 @@
20
77
  headline ("Would have blocked 3 PRs — all 3 were real breaks. Safe to turn on blocking.").
21
78
  - `gate.*` keys in `.specshield.yml`; `--usage` works as in `compare`.
22
79
 
23
- ### Tested on real data
80
+ #### Tested on real data
24
81
 
25
82
  - Redocly/museum-openapi-example PR #18 (open, far behind `main`), depth-1 checkout from
26
83
  GitHub: comparing with `main`'s tip reports 14 breaking changes, all from commits merged
@@ -28,9 +85,9 @@
28
85
  HTTPS in ~1 s and reported 0.
29
86
 
30
87
 
31
- ## Unreleased — break → fix: `specshield fix`
88
+ ### Break → fix: `specshield fix`
32
89
 
33
- ### Added
90
+ #### Added
34
91
 
35
92
  - **`specshield fix <base> <target>`** writes the non-breaking version of a breaking
36
93
  change as minimal edits to the target spec (comments and layout kept): renamed fields
@@ -46,7 +103,7 @@
46
103
  - `compare` points at `specshield fix` when it finds breaking changes.
47
104
  - `specshield deprecations` also honours `x-deprecated: true` (Swagger 2.0 schemas).
48
105
 
49
- ### Tested on real data
106
+ #### Tested on real data
50
107
 
51
108
  - Kubernetes `swagger.json` v1.37.1 → master: 552 breaking changes, all fixed and verified
52
109
  (7 s); an independent `compare` of v1.37.1 against the fixed spec reports 0.
@@ -57,9 +114,9 @@
57
114
  between single-value constants of `oneOf` variants that moved. A format-only change
58
115
  (`integer` → `int64`) no longer suggests a new field.
59
116
 
60
- ## Unreleased — safe removal: deprecate → watch traffic drain → remove
117
+ ### Safe removal: deprecate → watch traffic drain → remove
61
118
 
62
- ### Added
119
+ #### Added
63
120
 
64
121
  - **`specshield deprecations <spec> --usage usage.json`** lists everything the spec marks
65
122
  `deprecated: true` (or gives an `x-sunset` date) — operations, parameters, request and
@@ -76,7 +133,7 @@
76
133
  - `usage import` records calls per week per client and when each query parameter was last
77
134
  sent (additive `weeks` / `paramsLastSeen` in usage.json; older files still load).
78
135
 
79
- ### Tested on real data
136
+ #### Tested on real data
80
137
 
81
138
  Kubernetes' published CI audit log (106,445 requests) against the official
82
139
  `swagger.json`, with the upstream deprecations marked (the `v1 Endpoints` API, deprecated
package/README.md CHANGED
@@ -42,7 +42,7 @@ What the CLI does:
42
42
  - [vs. Alternatives](#vs-alternatives) · [Pricing](#pricing)
43
43
 
44
44
  **Commands — local & hosted compare**
45
- - [Local Compare](#local-compare) · [**Who does a change break? (usage-aware compare)**](#who-does-a-change-break--usage-aware-compare) · [**Safe removal: deprecate → drain → remove**](#safe-removal-deprecate--watch-traffic-drain--remove) · [**Break → fix: `specshield fix`**](#break--fix-generate-the-non-breaking-version) · [**CI gate: `specshield gate`**](#a-gate-you-can-leave-blocking-specshield-gate) · [Remote Compare](#remote-compare) · [Comparison History](#comparison-history) · [Share a Comparison](#share-a-comparison) · [GitHub App PR Checks](#github-app--pr-checks)
45
+ - [Local Compare](#local-compare) · [**Who does a change break? (usage-aware compare)**](#who-does-a-change-break--usage-aware-compare) · [**Safe removal: deprecate → drain → remove**](#safe-removal-deprecate--watch-traffic-drain--remove) · [**Break → fix: `specshield fix`**](#break--fix-generate-the-non-breaking-version) · [**CI gate: `specshield gate`**](#a-gate-you-can-leave-blocking-specshield-gate) · [**Proof: `prove` & `replay`**](#proof-not-opinion-specshield-prove-and-specshield-replay) · [Remote Compare](#remote-compare) · [Comparison History](#comparison-history) · [Share a Comparison](#share-a-comparison) · [GitHub App PR Checks](#github-app--pr-checks)
46
46
 
47
47
  **Governance — lint & gate**
48
48
  - [`specshield govern`](#governance--lint-a-spec-and-gate-the-pr)
@@ -578,6 +578,99 @@ In GitHub Actions the gate also writes a job summary and annotations (`--no-summ
578
578
 
579
579
  ---
580
580
 
581
+ ## Proof, not opinion: `specshield prove` and `specshield replay`
582
+
583
+ A diff says *"breaking change"*. A reviewer asks *"does it actually break anything?"* — and a gate that can't answer gets overruled. `prove` answers with the exact request that worked before and fails now; `replay` answers with real traffic.
584
+
585
+ ```bash
586
+ specshield prove openapi-v1.yaml openapi-v2.yaml
587
+ ```
588
+
589
+ ```
590
+ PROOF Field "requestBody.channel" was added to POST /payments (required)
591
+ worked before POST /payments {"amount":1.5,"currency":"USD","customerId":"cus_1"}
592
+ fails now body is missing required field "channel"
593
+ reproduce curl -X POST "$BASE_URL/payments" -H 'Content-Type: application/json' -d '{"amount":1.5,…}'
594
+
595
+ PROOF Response field "amount" changed type — 3 endpoints: GET /payments, POST /payments, GET /payments/{paymentId}
596
+ request GET /payments/PAY-1
597
+ new spec allows {"paymentId":"abc","amount":"abc","currency":"abc","status":"abc"} (200)
598
+ old clients reject it response.amount must be number
599
+
600
+ COMPATIBLE Field "responses.200.message" became required in PATCH /budgets/{id}
601
+ Everything the new schema lets the server send here, the old schema accepted too (checked schema against schema), so old clients can't break on this change.
602
+ ```
603
+
604
+ **How a proof is made.** For each breaking change, `prove` generates values the old contract accepts at the changed location — enum values, boundaries just past the new limits, strings matching the old pattern, every `oneOf` branch, leaving the field out — builds a whole request around each, and validates it with ajv against **both** full specs. A *request* witness is accepted by the old spec and rejected by the new one; a *response* witness is a body the new spec lets the server send that a client built on the old spec rejects.
605
+
606
+ Two rules keep proofs honest:
607
+
608
+ - **Isolation.** Every other part of the witness is repaired until both specs accept it, so it fails for this change alone — not for the three other changes in the same release. Where no value can satisfy both (a field that went from integer to string next door), the conflict is listed separately as *also*.
609
+ - **A control.** Each request witness ships with its control: the same request with only the changed value swapped for one the new spec accepts. When the control passes, the change is provably the cause.
610
+
611
+ Every change gets one of four results:
612
+
613
+ | Result | Meaning |
614
+ |---|---|
615
+ | **PROOF** | A witness, validated against both specs as above |
616
+ | **EXAMPLE** | The change is real but schemas can't reject anything — a removed optional response field, a parameter the server will now ignore. Shown as a concrete before/after |
617
+ | **COMPATIBLE** | No witness exists, and a structural argument says why: the new schema accepts everything the old one did (a sound subschema check), only a numeric format changed, `oneOf` branches were reordered, the change only narrows what a server sends |
618
+ | **NO PROOF** | No witness found; the reason says why (a removed status code has no payload to show) |
619
+
620
+ **Against a running build.** `--against http://localhost:8080` sends every witness to the new build and reports what it does: *confirmed* (rejected, while the control got a 2xx), *not reproduced* (the build still accepts it — the spec and the code disagree), *inconclusive* (both rejected: credentials or test data, not the change). Only `GET`/`HEAD`/`OPTIONS` are sent unless you pass `--include-mutating`; only local and private hosts are allowed unless you pass `--allow-remote`; `--header "Authorization: Bearer $TOKEN"` adds credentials.
621
+
622
+ ```bash
623
+ specshield prove v1.yaml v2.yaml --against http://localhost:8080 --include-mutating
624
+ # On http://localhost:8080: 6 confirmed
625
+ # … on the build ✔ confirmed — HTTP 400: rejected, while the same request valid under the new spec got HTTP 201
626
+ ```
627
+
628
+ **In the gate.** `specshield gate --prove` (or `gate.prove: true`) attaches the proof to every blocking change — in the terminal, and as a collapsible *Proof* section with the request, the reason and a `curl` command in the GitHub job summary.
629
+
630
+ ### Replay real traffic: `specshield replay`
631
+
632
+ Synthetic witnesses show what *can* break; replay shows what *does*, for the requests your clients actually send.
633
+
634
+ ```bash
635
+ # Side by side: the old build and the new one, same data — the strongest comparison
636
+ specshield replay --from traffic.har --against http://localhost:8082 --baseline http://localhost:8081 --spec v2.yaml
637
+
638
+ # Access logs (nginx/Apache, ALB, JSON lines; .gz ok) record no bodies: use the old spec as the oracle
639
+ specshield replay --from access.log --against http://localhost:8082 --old-spec v1.yaml
640
+ ```
641
+
642
+ ```
643
+ ✖ 10 requests that worked before break on the new build
644
+ ✔ 1 ok ✖ 2 broken ▲ 8 changed
645
+
646
+ POST /payments 2 replayed · 2 broken
647
+ ✖ POST /payments
648
+ worked before (HTTP 201), fails now (HTTP 400)
649
+ GET /payments/{paymentId} 5 replayed · 4 changed
650
+ ▲ GET /payments/PAY-1
651
+ missing receiptUrl; amount number → string
652
+ ```
653
+
654
+ - **Sampling.** Up to `--per-operation` requests (default 5) from every operation, `--sample` (default 200) in total, taken round-robin so rare operations survive the cut. Reservoir sampling with a `--seed`: the same seed replays the same requests.
655
+ - **What is compared.** With `--baseline <old build>`, each request goes to both builds — only the code differs. Without it, the recorded HAR response is the reference, and a `404` is *inconclusive* (missing test data explains it as well as a removed route). Response shapes are compared, not values: a field the old response had and the new one lacks, or a type that changed, is *changed*; different data is not. `--old-spec` checks every response against the old contract; `--spec` groups traffic by operation, spots removed routes and flags responses that don't match the new spec.
656
+ - **Safe by default.** Writes are replayed only with `--include-mutating`, and never from access logs (they don't record bodies). Captured credentials — `Authorization`, cookies, anything named like a key or token — are never replayed; pass your own with `--header`. Query values are hidden in the report unless `--show-values`. Only local and private hosts without `--allow-remote`.
657
+
658
+ Exit codes for both: `1` when something breaks (`prove`: breaking changes, as `compare`; `replay`: a request that worked before fails now), `0` otherwise, `2` on errors. `--json` prints everything, including each witness, its control and, with `--against`, what the build did.
659
+
660
+ **Tested on real data.**
661
+
662
+ | Spec pair | Findings | Proven | Example | Compatible | No proof | Time |
663
+ |---|---|---|---|---|---|---|
664
+ | GitHub REST API, Apr → Oct 2026 | 112 | 35 | 11 | 41 | 25 | 1.1 s |
665
+ | Stripe API, Mar → Sep 2026 (form bodies) | 112 | 89 | 19 | 0 | 4 | 16 s |
666
+ | Kubernetes (Swagger 2.0), Jul → Oct 2026 | 103 | 58 | 0 | 0 | 45 | 2.6 s |
667
+
668
+ Every proof was isolated to its own change. The *compatible* findings on GitHub are rule branches GitHub reordered inside a `oneOf` (the engine compares branches by position), numeric formats that only widened, and response fields that became required. *No proof* is almost entirely removed status codes and removed shared schemas, which are proven through the endpoints that used them. On Kubernetes, 384 of the per-endpoint "field became required" findings sit on responses and are shown compatible, while the same fields on requests are proven. Against a Spring Boot service whose old and new builds ran side by side, all 6 proofs were confirmed on the new build. All 6 were *not reproduced* on a build whose code hadn't changed.
669
+
670
+ **Limits.** Witnesses are built for JSON and form bodies. The subschema check assumes a closed world — clients send only fields the spec documents — which is what every compatibility check assumes; it is sound (a *compatible* verdict holds for every instance) but incomplete: regex inclusion, `not` and `if/then` are reported as *no proof* rather than guessed. Pattern strings are generated for the regex features API specs use; lookarounds and backreferences are skipped.
671
+
672
+ ---
673
+
581
674
  ## Remote Compare
582
675
 
583
676
  Sends your specs to SpecShield's hosted diff engine. Useful for keeping the
@@ -1706,7 +1799,7 @@ Per-subcommand flags:
1706
1799
  | Code | Meaning |
1707
1800
  |---|---|
1708
1801
  | `0` | Clean — no breaking changes / deployable / all probes pass |
1709
- | `1` | Breaking changes found / not deployable / one or more probes failed |
1802
+ | `1` | Breaking changes found / not deployable / one or more probes failed / a replayed request that worked before fails now |
1710
1803
  | `2` | Config error, missing token, or runtime error |
1711
1804
 
1712
1805
  ---
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specshield",
3
- "version": "3.4.17",
3
+ "version": "3.5.1",
4
4
  "description": "Contract compatibility testing for APIs — catch breaking OpenAPI changes before they reach your consumers, with can-i-deploy deploy gating and GitHub PR checks. (a.k.a. bidirectional contract testing.)",
5
5
  "main": "src/cli.js",
6
6
  "homepage": "https://specshield.io",
package/src/cli.js CHANGED
@@ -16,6 +16,8 @@ const deprecationsCommand = require('./commands/deprecations');
16
16
  const fixCommand = require('./commands/fix');
17
17
  const gateCommand = require('./commands/gate');
18
18
  const waiversCommand = require('./commands/waivers');
19
+ const proveCommand = require('./commands/prove');
20
+ const replayCommand = require('./commands/replay');
19
21
 
20
22
  const program = new Command();
21
23
 
@@ -42,6 +44,8 @@ program.addCommand(deprecationsCommand);
42
44
  program.addCommand(fixCommand);
43
45
  program.addCommand(gateCommand);
44
46
  program.addCommand(waiversCommand);
47
+ program.addCommand(proveCommand);
48
+ program.addCommand(replayCommand);
45
49
 
46
50
  program.parseAsync(process.argv).catch((err) => {
47
51
  const logger = require('./utils/logger');
@@ -10,6 +10,7 @@ const { usageOptions } = require('../core/usage/applyUsage');
10
10
  const W = require('../core/gate/waivers');
11
11
  const G = require('../core/gate/git');
12
12
  const { plural } = require('../core/usage/format');
13
+ const R = require('../core/prove/render');
13
14
  const { uploadGateRun } = require('../api/bdctClient');
14
15
  const { getStoredApiKey } = require('../config/localConfig');
15
16
  const logger = require('../utils/logger');
@@ -25,6 +26,7 @@ const gate = new Command('gate')
25
26
  .option('--max-waiver-days <n>', `Longest a waiver may run before it must be renewed (default: ${W.DEFAULT_MAX_DAYS})`)
26
27
  .option('--no-fetch', 'Never run git fetch, even when the baseline commit is missing from a shallow clone')
27
28
  .option('--usage <file>', 'usage.json from "specshield usage import" — breaking changes no client uses stop blocking')
29
+ .option('--prove', 'Attach a proof to every breaking change: the request that worked at the baseline and fails now')
28
30
  .option('--no-summary', 'Skip the GitHub Actions job summary and annotations')
29
31
  .option('--upload', 'Record this run on your SpecShield dashboard, for the shadow-mode graduation report (Team plan)')
30
32
  .option('--org <key>', 'Org key for --upload (default: gate.org or bdct.org in .specshield.yml)')
@@ -50,6 +52,7 @@ const gate = new Command('gate')
50
52
  maxWaiverDays,
51
53
  ignore: config.ignore || [],
52
54
  usage: usage.usage ? usage : null,
55
+ prove: Boolean(opts.prove || g.prove),
53
56
  });
54
57
 
55
58
  if (opts.upload || g.upload) r.upload = await upload(r, { ...opts, org: opts.org || g.org });
@@ -180,6 +183,7 @@ function render(r) {
180
183
  if (c.expiredWaiver) {
181
184
  lines.push(chalk.yellow(` waiver expired ${c.expiredWaiver.expires} (owner ${c.expiredWaiver.owner}) — renew it or fix the change`));
182
185
  }
186
+ if (c.proof) lines.push(...R.lines(c.proof, { pad: ' ' }));
183
187
  lines.push(chalk.gray(` intended? ${waiveCommand(c, r.waivers.file)}`));
184
188
  }
185
189
  }
@@ -278,6 +282,15 @@ function markdown(r) {
278
282
  const { where, what } = label(c);
279
283
  md.push(`| ${cell(what)} | ${cell(where || '—')} | ${c.expiredWaiver ? `waiver expired ${c.expiredWaiver.expires}` : ''} |`);
280
284
  }
285
+ const proven = r.blocking.filter((c) => c.proof && (c.proof.status === 'proven' || c.proof.status === 'example'));
286
+ if (proven.length) {
287
+ md.push('');
288
+ md.push(`<details><summary>Proof for ${plural(proven.length, 'change')}</summary>`);
289
+ for (const c of proven) {
290
+ md.push('', `#### ${cell(label(c).what)}`, '', R.markdown(c.proof));
291
+ }
292
+ md.push('', '</details>');
293
+ }
281
294
  md.push('');
282
295
  md.push(`Intended? Add a waiver with an owner, a reason and an expiry: \`${waiveCommand(r.blocking[0], r.waivers.file)}\``);
283
296
  }
@@ -0,0 +1,149 @@
1
+ 'use strict';
2
+
3
+ const { Command } = require('commander');
4
+ const chalk = require('chalk');
5
+ const { loadSpec } = require('../core/loadSpec');
6
+ const { parseSpec } = require('../core/parseSpec');
7
+ const { prove } = require('../core/prove');
8
+ const { confirmAll } = require('../core/prove/execute');
9
+ const R = require('../core/prove/render');
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 prove_ = new Command('prove')
16
+ .description('Proof, not opinion: for every breaking change, the exact request that worked before and fails now — checked against both specs, and optionally against a running build')
17
+ .argument('<base>', 'The spec your clients use today')
18
+ .argument('<target>', 'The new spec')
19
+ .option('--against <url>', 'Send each witness to a running build of the new API and report what it does')
20
+ .option('--header <header...>', 'Header for --against requests, e.g. "Authorization: Bearer $TOKEN" (repeatable)')
21
+ .option('--include-mutating', 'With --against, also send POST/PUT/PATCH/DELETE witnesses (they may change data)')
22
+ .option('--allow-remote', 'Allow --against to target a host that is not local or private')
23
+ .option('--timeout <ms>', 'Per-request timeout for --against', '10000')
24
+ .option('--base-url <url>', 'Base URL to print in the curl commands (default: $BASE_URL, or --against)')
25
+ .option('--warnings', 'Also prove constraint warnings (tightened min/max/length/pattern), which never fail the build')
26
+ .option('--json', 'Output machine-readable JSON')
27
+ .action(async (basePath, targetPath, opts) => {
28
+ try {
29
+ const baseDoc = parseSpec(await loadSpec(basePath), basePath);
30
+ const targetDoc = parseSpec(await loadSpec(targetPath), targetPath);
31
+ const r = prove(baseDoc, targetDoc);
32
+ const shown = opts.warnings ? [...r.breaking, ...r.warnings] : r.breaking;
33
+
34
+ let against = null;
35
+ if (opts.against) {
36
+ against = H.targetUrl(opts.against, { allowRemote: opts.allowRemote });
37
+ const items = shown.filter((c) => c.proof).map((c) => ({ diff: c.proof.diff, witness: c.proof }));
38
+ await confirmAll(items, {
39
+ baseDoc, targetDoc, against,
40
+ headers: H.parseHeaders(opts.header),
41
+ includeMutating: opts.includeMutating,
42
+ timeoutMs: Number(opts.timeout) || 10000,
43
+ });
44
+ const sent = items.filter((i) => i.witness.run.outcome !== 'skipped');
45
+ if (sent.length && sent.every((i) => i.witness.run.outcome === 'error')) {
46
+ throw new Error(`Can't reach ${against}: ${sent[0].witness.run.detail}`);
47
+ }
48
+ }
49
+
50
+ if (opts.json) {
51
+ process.stdout.write(JSON.stringify(toJson(r, { baseDoc, targetDoc, against, warnings: opts.warnings }), null, 2) + '\n');
52
+ } else {
53
+ process.stdout.write(render(r, { baseDoc, targetDoc, against, base: opts.baseUrl || against, warnings: opts.warnings }) + '\n');
54
+ }
55
+ exitAfterFlush(r.breaking.length > 0 ? 1 : 0);
56
+ } catch (err) {
57
+ logger.error(`Error: ${err.message}`);
58
+ process.exit(2);
59
+ }
60
+ });
61
+
62
+ function title(doc) {
63
+ const t = (doc.info && doc.info.title) || 'API';
64
+ return { title: t, version: doc.info && doc.info.version ? String(doc.info.version) : null };
65
+ }
66
+
67
+ function toJson(r, { baseDoc, targetDoc, against, warnings }) {
68
+ const item = (c) => {
69
+ const { proof, ...change } = c;
70
+ return { ...change, proof: proof ? strip(proof) : null };
71
+ };
72
+ return {
73
+ base: title(baseDoc),
74
+ target: title(targetDoc),
75
+ against,
76
+ summary: { ...r.summary, ...(against ? { onTheBuild: runCounts(r.breaking) } : {}) },
77
+ breakingChanges: r.breaking.map(item),
78
+ warnings: warnings ? r.warnings.map(item) : r.warnings.map(({ proof, ...c }) => c),
79
+ nonBreaking: r.nonBreaking,
80
+ };
81
+ }
82
+
83
+ function strip(p) {
84
+ const { diff, ...rest } = p;
85
+ return { ...rest, at: diff };
86
+ }
87
+
88
+ function runCounts(changes) {
89
+ const out = {};
90
+ for (const c of changes) if (c.proof && c.proof.run) out[c.proof.run.outcome] = (out[c.proof.run.outcome] || 0) + 1;
91
+ return out;
92
+ }
93
+
94
+ function render(r, { baseDoc, targetDoc, against, base, warnings }) {
95
+ const b = title(baseDoc);
96
+ const t = title(targetDoc);
97
+ const lines = [''];
98
+ lines.push(chalk.bold(` SpecShield™ Prove — ${t.title}${b.version ? ` ${b.version}` : ''} →${t.version ? ` ${t.version}` : ''}`));
99
+ lines.push(chalk.gray(' ─────────────────────────────────────────'));
100
+ if (r.breaking.length === 0) {
101
+ lines.push(chalk.green(' ✔ No breaking changes — nothing to prove.'));
102
+ } else {
103
+ const s = r.summary;
104
+ const parts = [`${chalk.green(`${s.proven} proven`)} with a failing request`];
105
+ if (s.example) parts.push(chalk.yellow(`${s.example} shown by example`));
106
+ if (s.compatible) parts.push(chalk.cyan(`${s.compatible} compatible on their own`));
107
+ if (s.unproven) parts.push(chalk.gray(`${s.unproven} without proof`));
108
+ lines.push(` ${plural(s.total, 'breaking change')} · ${parts.join(' · ')}`);
109
+ lines.push(chalk.gray(' Every proof is checked against both specs: the old one accepts it, the new one rejects it.'));
110
+ if (against) {
111
+ const counts = runCounts(r.breaking);
112
+ lines.push(` On ${against}: ` + Object.entries(counts).map(([k, n]) => `${n} ${k}`).join(' · '));
113
+ }
114
+ for (const c of r.breaking) block(lines, c, base);
115
+ }
116
+ const provable = r.warnings.filter((c) => c.proof && c.proof.status === 'proven');
117
+ if (warnings && r.warnings.length) {
118
+ lines.push('');
119
+ lines.push(chalk.yellow.bold(` Warnings (${r.warnings.length}) — reported, never fail the build`));
120
+ for (const c of r.warnings) block(lines, c, base);
121
+ } else if (provable.length) {
122
+ lines.push('');
123
+ lines.push(chalk.gray(` ${plural(provable.length, 'constraint warning')} also ${provable.length === 1 ? 'has' : 'have'} a failing request — see them with --warnings.`));
124
+ }
125
+ if (!base && r.breaking.some((c) => c.proof && c.proof.request)) {
126
+ lines.push('');
127
+ lines.push(chalk.gray(' Set BASE_URL to run the curl commands, e.g. export BASE_URL=http://localhost:8080'));
128
+ }
129
+ lines.push('');
130
+ return lines.join('\n');
131
+ }
132
+
133
+ /** A merged change's description lists every endpoint (with repeats); name a few, count them all. */
134
+ function headline(c) {
135
+ const eps = [...new Set(c.affectedEndpoints || [])];
136
+ if (eps.length < 2) return c.description;
137
+ const head = c.description.replace(/ \(affects \d+ endpoints?:.*\)$/, '');
138
+ return `${head} — ${eps.length} endpoints: ${eps.slice(0, 3).join(', ')}${eps.length > 3 ? ` and ${eps.length - 3} more` : ''}`;
139
+ }
140
+
141
+ function block(lines, c, base) {
142
+ lines.push('');
143
+ lines.push(` ${R.badge(c.proof)} ${headline(c)}`);
144
+ // A merged change already names its endpoints in the description.
145
+ if (c.method && !(c.affectedEndpoints && c.affectedEndpoints.length > 1)) lines.push(chalk.gray(` ${c.method.toUpperCase()} ${c.path}`));
146
+ lines.push(...R.lines(c.proof, { base }));
147
+ }
148
+
149
+ module.exports = prove_;