specshield 3.4.16 → 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 +28 -0
- package/README.md +78 -12
- package/package.json +1 -1
- package/src/api/bdctClient.js +8 -0
- package/src/cli.js +4 -0
- package/src/commands/compare.js +2 -33
- package/src/commands/gate.js +307 -0
- package/src/commands/waivers.js +123 -0
- package/src/core/configLoader.js +34 -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/usage/applyUsage.js +63 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,33 @@
|
|
|
1
1
|
# SpecShield CLI changelog
|
|
2
2
|
|
|
3
|
+
## Unreleased — a gate teams can leave blocking: `specshield gate`
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **`specshield gate [spec]`** — the CI check. Compares the spec with the merge base of
|
|
8
|
+
the branch (never the base branch's tip or production), so changes merged since the
|
|
9
|
+
branch forked never fail an unrelated PR. Baseline from the CI event: GitHub
|
|
10
|
+
`pull_request`, `merge_group` (merge queue base), `push`; GitLab MR; Bitbucket PR;
|
|
11
|
+
else `origin`'s default branch; `--base` overrides. Shallow checkouts are fetched and
|
|
12
|
+
deepened as needed (`--no-fetch` to forbid). Writes a GitHub job summary and annotations.
|
|
13
|
+
- **Waivers** in `.specshield/waivers.yml`: change type, optional operation/field, and a
|
|
14
|
+
required owner, reason and expiry (≤ 90 days, `gate.maxWaiverDays`). Expired waivers stop
|
|
15
|
+
applying and say whose lapsed; invalid ones never apply; a waiver added in the PR that
|
|
16
|
+
matches nothing is flagged. `specshield waivers add` / `specshield waivers [list] [--check]`.
|
|
17
|
+
The legacy `ignore:` list still applies, and the gate says how to move it to a waiver.
|
|
18
|
+
- **Shadow mode** (`--shadow`, `gate.mode: shadow`): report what would have been blocked,
|
|
19
|
+
exit 0. `--upload` records each run for the dashboard's graduation report and prints its
|
|
20
|
+
headline ("Would have blocked 3 PRs — all 3 were real breaks. Safe to turn on blocking.").
|
|
21
|
+
- `gate.*` keys in `.specshield.yml`; `--usage` works as in `compare`.
|
|
22
|
+
|
|
23
|
+
### Tested on real data
|
|
24
|
+
|
|
25
|
+
- Redocly/museum-openapi-example PR #18 (open, far behind `main`), depth-1 checkout from
|
|
26
|
+
GitHub: comparing with `main`'s tip reports 14 breaking changes, all from commits merged
|
|
27
|
+
after the branch forked; the gate found the merge base (the PR's original base) over
|
|
28
|
+
HTTPS in ~1 s and reported 0.
|
|
29
|
+
|
|
30
|
+
|
|
3
31
|
## Unreleased — break → fix: `specshield fix`
|
|
4
32
|
|
|
5
33
|
### Added
|
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) · [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) · [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)
|
|
@@ -516,6 +516,68 @@ specshield fix base.yaml target.yaml --spring src/main/java --package com.acme.p
|
|
|
516
516
|
- Tested by compiling the generated code into a Spring Boot app and calling it as an old
|
|
517
517
|
and a new client (`test-harness/spring-compat/verify.sh`), on Spring Boot 3.2 and 3.5.
|
|
518
518
|
|
|
519
|
+
## A gate you can leave blocking: `specshield gate`
|
|
520
|
+
|
|
521
|
+
`compare` diffs two files you choose. `gate` is the CI check: it decides **which** spec a change is judged against, which breaks the team has accepted, and whether failing is safe yet.
|
|
522
|
+
|
|
523
|
+
```bash
|
|
524
|
+
specshield gate openapi.yaml # in CI, or locally on your branch
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
**Right baseline, automatically.** The spec is compared with the commit your branch started from (the merge base), never with the base branch's current tip and never with what's deployed. Against the tip, a branch that is behind sees every change merged since it forked as "removed", and a break that already landed fails every unrelated PR until someone notices — the fastest way for a gate to lose the team's trust. The baseline comes from the CI event:
|
|
528
|
+
|
|
529
|
+
| Where | Baseline |
|
|
530
|
+
|---|---|
|
|
531
|
+
| GitHub `pull_request` | merge base of the PR's base commit and HEAD |
|
|
532
|
+
| GitHub `merge_group` (merge queue) | the queue's base, so each PR is judged only on its own change |
|
|
533
|
+
| GitHub `push` | the commit before the push |
|
|
534
|
+
| GitLab merge request | `CI_MERGE_REQUEST_DIFF_BASE_SHA` |
|
|
535
|
+
| Bitbucket PR / anywhere else | merge base with the destination / `origin`'s default branch |
|
|
536
|
+
|
|
537
|
+
`--base <ref>` overrides it. CI checkouts are usually shallow: the gate fetches the base commit and deepens history until the merge base is reachable (`--no-fetch` to forbid that, or use `fetch-depth: 0`). A PR that doesn't touch the spec passes without a diff.
|
|
538
|
+
|
|
539
|
+
**Waivers with an owner, a reason and an expiry.** Accepted breaks live in `.specshield/waivers.yml`, committed with the change they accept so the waiver is reviewed in the same PR:
|
|
540
|
+
|
|
541
|
+
```bash
|
|
542
|
+
specshield waivers add response-field-removed --operation "GET /pets/{id}" --field legacy_id \
|
|
543
|
+
--owner @alice --reason "Mobile 4.2+ stopped reading it; older builds unsupported" --days 30 --ticket PET-12
|
|
544
|
+
specshield waivers # list: owner, reason, days left; --check exits 1 on expired/invalid ones
|
|
545
|
+
```
|
|
546
|
+
|
|
547
|
+
```yaml
|
|
548
|
+
waivers:
|
|
549
|
+
- change: response-field-removed # change type; "*" = any type on `operation`
|
|
550
|
+
operation: GET /pets/{id} # optional; "*" / "**" globs, "/pets/**" = any method
|
|
551
|
+
field: legacy_id # optional; name or dotted suffix
|
|
552
|
+
owner: "@alice"
|
|
553
|
+
reason: Mobile 4.2+ stopped reading it; older builds unsupported
|
|
554
|
+
created: "2026-10-27"
|
|
555
|
+
expires: "2026-11-26" # at most 90 days out (gate.maxWaiverDays)
|
|
556
|
+
ticket: PET-12
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
Owner, reason (10+ characters) and expiry are required; a waiver missing one never applies. A waiver with an `operation` must cover **every** endpoint the change affects. After the expiry day the change blocks again and the output says whose waiver lapsed. Without `operation`/`field` a waiver covers every change of that type — a policy decision the expiry forces someone to revisit. The legacy `ignore:` list still works, but the gate reports what it skipped and how to move it to a waiver. The SpecShield GitHub App reads the same file with the same rules.
|
|
560
|
+
|
|
561
|
+
**Shadow mode, then graduate.** `--shadow` (or `gate.mode: shadow`) reports what the gate would have blocked and always exits 0. Add `--upload` (Team plan) and each run lands on **Dashboard → Gate Readiness**, which shows after two weeks: *"Would have blocked 3 PRs — all 3 were real breaks. Safe to turn on blocking."* A PR fixed after the warning, or accepted with a waiver, counts as a real break; anything merged with an unwaived break is yours to mark *real* or *false alarm*. Any false alarm, or any failure on a PR that didn't touch the spec, keeps it from graduating.
|
|
562
|
+
|
|
563
|
+
**Merge queues.** Add `merge_group` to the workflow triggers; the gate reports on the queue's commit with the queue's base as baseline.
|
|
564
|
+
|
|
565
|
+
```yaml
|
|
566
|
+
# .github/workflows/api-gate.yml
|
|
567
|
+
on: [pull_request, merge_group]
|
|
568
|
+
jobs:
|
|
569
|
+
api-gate: # make this the required check
|
|
570
|
+
runs-on: ubuntu-latest
|
|
571
|
+
steps:
|
|
572
|
+
- uses: actions/checkout@v4 # shallow is fine; the gate fetches what it needs
|
|
573
|
+
- run: npx -y specshield@3 gate openapi.yaml --shadow --upload --org <org-key>
|
|
574
|
+
env: { SPECSHIELD_API_KEY: "${{ secrets.SPECSHIELD_API_KEY }}" }
|
|
575
|
+
```
|
|
576
|
+
|
|
577
|
+
In GitHub Actions the gate also writes a job summary and annotations (`--no-summary` to skip). With `--usage usage.json`, breaking changes no client calls stop blocking ([usage-aware compare](#who-does-a-change-break--usage-aware-compare)). Exit codes: `1` when something blocks in blocking mode, `0` otherwise, `2` on errors. `--json` prints the full result: baseline, blocking and waived changes, and waiver-file health.
|
|
578
|
+
|
|
579
|
+
---
|
|
580
|
+
|
|
519
581
|
## Remote Compare
|
|
520
582
|
|
|
521
583
|
Sends your specs to SpecShield's hosted diff engine. Useful for keeping the
|
|
@@ -595,18 +657,13 @@ time from the dashboard.
|
|
|
595
657
|
|
|
596
658
|
Install once at **Dashboard → GitHub Integration**, choose your repos, done. Every PR that touches the OpenAPI spec gets:
|
|
597
659
|
|
|
598
|
-
- A GitHub check run
|
|
599
|
-
- A sticky PR comment with the
|
|
600
|
-
-
|
|
660
|
+
- A GitHub check run visible on the PR, comparing the spec with the commit the branch started from (the merge base), not the base branch's moving tip
|
|
661
|
+
- A sticky PR comment with the breaking changes, any waived ones, and a ready-to-paste waiver
|
|
662
|
+
- Waivers read from `.specshield/waivers.yml` at the PR's head commit — the same file and rules as [`specshield gate`](#a-gate-you-can-leave-blocking-specshield-gate)
|
|
663
|
+
- Merge queue support: subscribe the App to **Merge group** events and the check runs on the queue's commit too
|
|
664
|
+
- **Shadow mode** for new repos: the check never fails, records what it would have blocked, and **Dashboard → Gate Readiness** tells you when it's safe to switch to blocking
|
|
601
665
|
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
```yaml
|
|
605
|
-
github:
|
|
606
|
-
specPath: api/openapi.yaml
|
|
607
|
-
failOnBreaking: true
|
|
608
|
-
commentOnPr: true
|
|
609
|
-
```
|
|
666
|
+
Spec path, waiver file and shadow/blocking mode are set per repository in **Dashboard → GitHub**.
|
|
610
667
|
|
|
611
668
|
---
|
|
612
669
|
|
|
@@ -1467,6 +1524,15 @@ severity: error # info | warning | error
|
|
|
1467
1524
|
ignore:
|
|
1468
1525
|
- "DELETE /admin removed" # match by substring; repeatable
|
|
1469
1526
|
|
|
1527
|
+
# CI gate (specshield gate; flags win).
|
|
1528
|
+
# gate:
|
|
1529
|
+
# spec: openapi.yaml
|
|
1530
|
+
# mode: shadow # shadow | blocking (default blocking)
|
|
1531
|
+
# waivers: .specshield/waivers.yml
|
|
1532
|
+
# maxWaiverDays: 90
|
|
1533
|
+
# upload: true # record runs for the readiness report (Team)
|
|
1534
|
+
# org: <org-key>
|
|
1535
|
+
|
|
1470
1536
|
# Usage-aware compare (same as --usage …; see "Who does a change break?").
|
|
1471
1537
|
# usage:
|
|
1472
1538
|
# file: usage.json
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specshield",
|
|
3
|
-
"version": "3.4.
|
|
3
|
+
"version": "3.4.17",
|
|
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/api/bdctClient.js
CHANGED
|
@@ -128,6 +128,13 @@ async function uploadDeprecationReport(server, apiToken, payload) {
|
|
|
128
128
|
} catch (err) { throw apiError(err); }
|
|
129
129
|
}
|
|
130
130
|
|
|
131
|
+
async function uploadGateRun(server, apiToken, payload) {
|
|
132
|
+
try {
|
|
133
|
+
const res = await buildClient(server, apiToken).post('/api/gate/runs', payload);
|
|
134
|
+
return res.data;
|
|
135
|
+
} catch (err) { throw apiError(err); }
|
|
136
|
+
}
|
|
137
|
+
|
|
131
138
|
module.exports = {
|
|
132
139
|
publishProviderSpec,
|
|
133
140
|
publishConsumerContract,
|
|
@@ -139,4 +146,5 @@ module.exports = {
|
|
|
139
146
|
listConsumerContracts,
|
|
140
147
|
governanceGate,
|
|
141
148
|
uploadDeprecationReport,
|
|
149
|
+
uploadGateRun,
|
|
142
150
|
};
|
package/src/cli.js
CHANGED
|
@@ -14,6 +14,8 @@ const whoamiCommand = require('./commands/whoami');
|
|
|
14
14
|
const usageCommand = require('./commands/usage');
|
|
15
15
|
const deprecationsCommand = require('./commands/deprecations');
|
|
16
16
|
const fixCommand = require('./commands/fix');
|
|
17
|
+
const gateCommand = require('./commands/gate');
|
|
18
|
+
const waiversCommand = require('./commands/waivers');
|
|
17
19
|
|
|
18
20
|
const program = new Command();
|
|
19
21
|
|
|
@@ -38,6 +40,8 @@ program.addCommand(whoamiCommand);
|
|
|
38
40
|
program.addCommand(usageCommand);
|
|
39
41
|
program.addCommand(deprecationsCommand);
|
|
40
42
|
program.addCommand(fixCommand);
|
|
43
|
+
program.addCommand(gateCommand);
|
|
44
|
+
program.addCommand(waiversCommand);
|
|
41
45
|
|
|
42
46
|
program.parseAsync(process.argv).catch((err) => {
|
|
43
47
|
const logger = require('./utils/logger');
|
package/src/commands/compare.js
CHANGED
|
@@ -3,7 +3,6 @@
|
|
|
3
3
|
const { Command } = require('commander');
|
|
4
4
|
const chalk = require('chalk');
|
|
5
5
|
const ora = require('ora');
|
|
6
|
-
const path = require('path');
|
|
7
6
|
const { loadSpec } = require('../core/loadSpec');
|
|
8
7
|
const { parseSpec } = require('../core/parseSpec');
|
|
9
8
|
const { normalizeSpec } = require('../core/normalizeSpec');
|
|
@@ -154,38 +153,8 @@ compare
|
|
|
154
153
|
});
|
|
155
154
|
|
|
156
155
|
async function applyUsage(result, base, options) {
|
|
157
|
-
const {
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
const usage = await loadUsage(options.usage);
|
|
161
|
-
const baseSpec = parseSpec(await loadSpec(base), base);
|
|
162
|
-
const num = (value, flag, max = Infinity) => {
|
|
163
|
-
const n = Number(value);
|
|
164
|
-
if (!Number.isFinite(n) || n < 0 || n > max) throw new Error(`${flag} must be a number from 0 to ${max}, got "${value}"`);
|
|
165
|
-
return n;
|
|
166
|
-
};
|
|
167
|
-
const minDays = num(options.usageMinDays, '--usage-min-days');
|
|
168
|
-
const maxAgeDays = num(options.usageMaxAge, '--usage-max-age');
|
|
169
|
-
const minCoverage = num(options.usageMinCoverage, '--usage-min-coverage', 100);
|
|
170
|
-
|
|
171
|
-
const { result: annotated, meta } = applyUsageImpact(result, {
|
|
172
|
-
usage,
|
|
173
|
-
baseSpec,
|
|
174
|
-
baseNorm: normalizeSpec(baseSpec),
|
|
175
|
-
file: path.basename(options.usage),
|
|
176
|
-
ignoreClients: options.usageIgnoreClient,
|
|
177
|
-
minDays,
|
|
178
|
-
maxAgeDays,
|
|
179
|
-
minCoverage,
|
|
180
|
-
downgrade: options.usageDowngrade,
|
|
181
|
-
});
|
|
182
|
-
if (!meta.trusted && meta.totalCalls > 0) {
|
|
183
|
-
logger.warn(`None of the calls in ${options.usage} match an operation in ${base}. ` +
|
|
184
|
-
'Is it the right usage file? If the API is served under a prefix, re-import with --base-path.');
|
|
185
|
-
}
|
|
186
|
-
const { annotateDeprecations } = require('../core/usage/deprecations');
|
|
187
|
-
const quietDays = num(options.usageQuietDays, '--usage-quiet-days');
|
|
188
|
-
return { ...annotateDeprecations(annotated, baseSpec, { meta, quietDays }), usage: { ...meta, quietDays } };
|
|
156
|
+
const { applyUsage: join } = require('../core/usage/applyUsage');
|
|
157
|
+
return join(result, parseSpec(await loadSpec(base), base), options, base);
|
|
189
158
|
}
|
|
190
159
|
|
|
191
160
|
async function runLocalComparison(base, target, options, spinner) {
|
|
@@ -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 };
|