specshield 3.4.14 → 3.4.16
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 +58 -1
- package/README.md +186 -1
- package/package.json +3 -2
- package/src/api/bdctClient.js +8 -0
- package/src/cli.js +4 -0
- package/src/commands/compare.js +7 -1
- package/src/commands/deprecations.js +236 -0
- package/src/commands/fix.js +173 -0
- package/src/core/classifyChanges.js +1 -1
- package/src/core/configLoader.js +6 -1
- package/src/core/fix/fixSpec.js +179 -0
- package/src/core/fix/locate.js +263 -0
- package/src/core/fix/ops.js +233 -0
- package/src/core/fix/shim/spring.js +532 -0
- package/src/core/fix/shim/transforms.js +231 -0
- package/src/core/fix/strategies.js +578 -0
- package/src/core/outputFormatter.js +23 -1
- package/src/core/usage/deprecations.js +438 -0
- package/src/core/usage/impact.js +42 -24
- package/src/core/usage/usageStore.js +32 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,63 @@
|
|
|
1
1
|
# SpecShield CLI changelog
|
|
2
2
|
|
|
3
|
-
## Unreleased —
|
|
3
|
+
## Unreleased — break → fix: `specshield fix`
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **`specshield fix <base> <target>`** writes the non-breaking version of a breaking
|
|
8
|
+
change as minimal edits to the target spec (comments and layout kept): renamed fields
|
|
9
|
+
keep both names, removed things come back `deprecated` (`--sunset`), newly required
|
|
10
|
+
input becomes optional, type changes keep the old type, removed enum values return.
|
|
11
|
+
Every fix is verified by re-running the diff engine; one that leaves its break or adds
|
|
12
|
+
another is not applied. `--out`, `--write`, `--dry-run`, `--json`.
|
|
13
|
+
- **`--spring <dir> --package <pkg>`** generates a Spring Boot 3 version layer
|
|
14
|
+
(`ResponseBodyAdvice`/`RequestBodyAdvice`): old clients get the old JSON shape (renames,
|
|
15
|
+
scalar conversions, enum mappings, request defaults, list envelopes), each rewrite
|
|
16
|
+
checked on sample payloads against the old schema first. Compiled and tested in a Spring
|
|
17
|
+
Boot 3.2 and 3.5 app (`test-harness/spring-compat/verify.sh`).
|
|
18
|
+
- `compare` points at `specshield fix` when it finds breaking changes.
|
|
19
|
+
- `specshield deprecations` also honours `x-deprecated: true` (Swagger 2.0 schemas).
|
|
20
|
+
|
|
21
|
+
### Tested on real data
|
|
22
|
+
|
|
23
|
+
- Kubernetes `swagger.json` v1.37.1 → master: 552 breaking changes, all fixed and verified
|
|
24
|
+
(7 s); an independent `compare` of v1.37.1 against the fixed spec reports 0.
|
|
25
|
+
- GitHub's REST API description, April → October 2026 (13 MB): 429 breaking changes, all
|
|
26
|
+
fixed and verified (22 s), independently re-checked. This run removed two kinds of
|
|
27
|
+
guesses: "renames" between unrelated fields that happened to be the only ones of a type
|
|
28
|
+
(`budget_type` → `expires_at`; now a rename needs a shared word), and enum "renames"
|
|
29
|
+
between single-value constants of `oneOf` variants that moved. A format-only change
|
|
30
|
+
(`integer` → `int64`) no longer suggests a new field.
|
|
31
|
+
|
|
32
|
+
## Unreleased — safe removal: deprecate → watch traffic drain → remove
|
|
33
|
+
|
|
34
|
+
### Added
|
|
35
|
+
|
|
36
|
+
- **`specshield deprecations <spec> --usage usage.json`** lists everything the spec marks
|
|
37
|
+
`deprecated: true` (or gives an `x-sunset` date) — operations, parameters, request and
|
|
38
|
+
response fields — with who still calls it, the last call, calls per week, and a status:
|
|
39
|
+
still called · can't verify · quiet · safe to remove · no verdict. `--quiet-days`
|
|
40
|
+
(default 30), `--csv` (callers for outreach, spreadsheet-formula safe), `--fail-on
|
|
41
|
+
past-sunset|in-use`, `--json`, and `--upload --org <key>` to the dashboard (Team plan).
|
|
42
|
+
- `.specshield.yml` `usage.contacts` maps client ids (or `*` globs) to an owner, shown in
|
|
43
|
+
the report and the CSV; `usage.quietDays` sets the quiet period.
|
|
44
|
+
- `compare --usage` marks every removal with whether the base spec deprecated it first
|
|
45
|
+
(`deprecation` in `--json`). A deprecated item with no calls for `--usage-quiet-days`
|
|
46
|
+
(default 30) has drained and no longer fails the build; one still called stays breaking
|
|
47
|
+
with its callers; a removal that was never deprecated is flagged.
|
|
48
|
+
- `usage import` records calls per week per client and when each query parameter was last
|
|
49
|
+
sent (additive `weeks` / `paramsLastSeen` in usage.json; older files still load).
|
|
50
|
+
|
|
51
|
+
### Tested on real data
|
|
52
|
+
|
|
53
|
+
Kubernetes' published CI audit log (106,445 requests) against the official
|
|
54
|
+
`swagger.json`, with the upstream deprecations marked (the `v1 Endpoints` API, deprecated
|
|
55
|
+
in v1.33; the `watch` endpoints; 9 fields documented as deprecated). Every per-operation
|
|
56
|
+
count for the Endpoints API matched the raw audit events exactly. This run found that a
|
|
57
|
+
deprecated property of a shared schema (`ObjectMeta.selfLink`) was listed once per
|
|
58
|
+
operation and status code — 1,733 rows — so such properties are now one row each.
|
|
59
|
+
|
|
60
|
+
## 3.4.14 — 2026-10-26 — Kubernetes audit logs, Swagger 2.0 bodies
|
|
4
61
|
|
|
5
62
|
Tested on the Kubernetes project's own published data: the API-server audit log of
|
|
6
63
|
CI job `ci-kubernetes-audit-kind-conformance` (219,507 events, k8s master `765dd1d`) and
|
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) · [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) · [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)
|
|
@@ -335,6 +335,187 @@ specshield usage show usage.json --spec api/openapi.yaml
|
|
|
335
335
|
# CALLED BUT NOT IN THE SPEC → shadow endpoints your spec is missing
|
|
336
336
|
```
|
|
337
337
|
|
|
338
|
+
## Safe removal: deprecate → watch traffic drain → remove
|
|
339
|
+
|
|
340
|
+
Deprecation usually means a spreadsheet, a calendar reminder and hope. Mark it in the
|
|
341
|
+
spec instead, and SpecShield tracks who still calls it until it is safe to delete.
|
|
342
|
+
|
|
343
|
+
**1. Mark what is going away** — an operation, a parameter, or a schema property:
|
|
344
|
+
|
|
345
|
+
```yaml
|
|
346
|
+
paths:
|
|
347
|
+
/v1/pets:
|
|
348
|
+
get:
|
|
349
|
+
deprecated: true
|
|
350
|
+
x-sunset: 2026-12-31 # optional: the date you plan to remove it
|
|
351
|
+
/pets:
|
|
352
|
+
get:
|
|
353
|
+
parameters:
|
|
354
|
+
- { name: sort, in: query, deprecated: true, schema: { type: string } }
|
|
355
|
+
components:
|
|
356
|
+
schemas:
|
|
357
|
+
Pet:
|
|
358
|
+
properties:
|
|
359
|
+
tag: { type: string, deprecated: true }
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
**2. See who still uses it** (same `usage.json` as above):
|
|
363
|
+
|
|
364
|
+
```bash
|
|
365
|
+
specshield deprecations api/openapi.yaml --usage usage.json --csv callers.csv
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
```text
|
|
369
|
+
SpecShield™ Deprecations — Pets API
|
|
370
|
+
usage.json · 2026-08-26 → 2026-10-24 (59 days) · safe after 30 quiet days
|
|
371
|
+
3 deprecated items · 1 still called · 1 quiet · 1 safe to remove
|
|
372
|
+
|
|
373
|
+
✖ STILL CALLED (1) — not safe to remove
|
|
374
|
+
GET /v1/pets · sunset 2026-09-30 PASSED 25 days ago
|
|
375
|
+
2 clients · 840 calls · last call 2 days ago weekly ▇█▇▅▃▁··▂
|
|
376
|
+
ShopApp-iOS/5.2 820 last 2 days ago → ios-team@shop.example
|
|
377
|
+
partner-x/1.0 20 last 41 days ago
|
|
378
|
+
|
|
379
|
+
○ QUIET (1) — no calls, keep watching
|
|
380
|
+
GET /pets query parameter "sort"
|
|
381
|
+
no calls for 11 of the 30 days needed
|
|
382
|
+
|
|
383
|
+
✔ SAFE TO REMOVE (1)
|
|
384
|
+
GET /pets/{id}/old-photo
|
|
385
|
+
last called 45 days before the newest log line
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
| Status | Meaning |
|
|
389
|
+
|---|---|
|
|
390
|
+
| **still called** | a client called it in the last 7 days of the logs |
|
|
391
|
+
| **can't verify** | a header or body field: logs don't show who sends or reads it, and the operation is still called |
|
|
392
|
+
| **quiet** | draining — no calls for a week or more, but not for `--quiet-days` (default 30) yet |
|
|
393
|
+
| **safe to remove** | no calls for at least `--quiet-days` |
|
|
394
|
+
| **no verdict** | the usage file can't support one (stale, filtered, no timestamps) — the report says why |
|
|
395
|
+
|
|
396
|
+
- Query parameters are judged by who **sends** them; operations by who calls them.
|
|
397
|
+
- A deprecated property of a shared schema (`$ref`'d by many operations) is **one** row,
|
|
398
|
+
judged by the traffic of every operation that uses it.
|
|
399
|
+
- **Who to tell:** map clients to owners in `.specshield.yml` and the report (and
|
|
400
|
+
`--csv`) names them:
|
|
401
|
+
|
|
402
|
+
```yaml
|
|
403
|
+
usage:
|
|
404
|
+
file: usage.json
|
|
405
|
+
quietDays: 30
|
|
406
|
+
contacts:
|
|
407
|
+
ShopApp-iOS/*: ios-team@shop.example # * globs; otherwise the exact client id
|
|
408
|
+
partner-x/1.0: "#partner-x"
|
|
409
|
+
```
|
|
410
|
+
- `--fail-on past-sunset` exits 1 when anything past its `x-sunset` date is still
|
|
411
|
+
called; `--fail-on in-use` when anything deprecated is still used. `--json` for scripts.
|
|
412
|
+
|
|
413
|
+
**3. Remove it — the compare gate knows it was deprecated:**
|
|
414
|
+
|
|
415
|
+
```bash
|
|
416
|
+
specshield compare base.yaml target.yaml --usage usage.json --fail-on-breaking
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
- Removing a deprecated item that is **still called** fails, listing the callers:
|
|
420
|
+
`↳ deprecated (sunset 2026-09-30), but still called — tell the clients above before removing it`.
|
|
421
|
+
- A deprecated item with **no calls for `--usage-quiet-days`** (default 30) has drained:
|
|
422
|
+
its removal passes, like an unused change.
|
|
423
|
+
- A removal that **was never deprecated** is flagged: `↳ removed without being deprecated first`.
|
|
424
|
+
|
|
425
|
+
**4. Track the drain week by week (Team plan):** add `--upload --org <orgKey>` and every
|
|
426
|
+
run is stored on your dashboard (**Deprecations** page): the latest status per API, who
|
|
427
|
+
still calls what, weekly calls per item, and the history across uploads. When an item
|
|
428
|
+
becomes safe to remove, passes its sunset while still called, or is called again after
|
|
429
|
+
going quiet, SpecShield posts to Slack (subscribe a webhook to **Deprecation update**)
|
|
430
|
+
and emails whoever uploaded. Only the report is sent — counts per client, never logs.
|
|
431
|
+
|
|
432
|
+
```bash
|
|
433
|
+
# e.g. weekly in CI, after importing the week's logs
|
|
434
|
+
specshield deprecations api/openapi.yaml --usage usage.json --upload --org acme --api payments
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
## Break → fix: generate the non-breaking version
|
|
438
|
+
|
|
439
|
+
A blocked PR with no way forward is why teams switch gates off. `specshield fix` takes
|
|
440
|
+
the change that broke the gate and writes the **non-breaking version** of it — the
|
|
441
|
+
expand-and-contract edit you'd make by hand if you had the time.
|
|
442
|
+
|
|
443
|
+
```bash
|
|
444
|
+
specshield fix api/openapi.base.yaml api/openapi.yaml
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
```text
|
|
448
|
+
SpecShield™ Fix — Payments API 1.0.0 → 2.0.0
|
|
449
|
+
16 breaking changes · 14 fixed · 2 need a decision
|
|
450
|
+
Each fix was re-checked with the diff engine: it removes its breaking change and adds none.
|
|
451
|
+
|
|
452
|
+
✔ `status` was renamed to `paymentStatus`: return both, `status` deprecated
|
|
453
|
+
POST /payments, GET /payments/{id}
|
|
454
|
+
→ The server must return `status` with the same value as `paymentStatus`.
|
|
455
|
+
✔ Make `currency` optional (default "EUR")
|
|
456
|
+
→ Clients that don't send it get the default "EUR".
|
|
457
|
+
✔ Keep `amount` as integer; return the string value as `amountV2`
|
|
458
|
+
✔ Keep "ENABLED" as an allowed value of status (renamed to "ACTIVE")
|
|
459
|
+
✔ Keep GET /payments/{id}/receipt, marked deprecated
|
|
460
|
+
…
|
|
461
|
+
✖ NEEDS A DECISION (2)
|
|
462
|
+
● Type of "responses.200" changed from "array" to "object" in GET /payments
|
|
463
|
+
the list moved into `data` — one schema can't describe both shapes, so this needs a version layer (--spring)
|
|
464
|
+
|
|
465
|
+
✔ Wrote openapi.fixed.yaml (12 edits, comments and layout kept)
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
| The change | The fix |
|
|
469
|
+
|---|---|
|
|
470
|
+
| Field or parameter renamed | keep both names, the old one `deprecated` (a rename needs the same type **and** a shared word in the name) |
|
|
471
|
+
| Field, parameter, operation, response or schema removed | restore it, `deprecated` (`--sunset 2027-03-31` adds `x-sunset`) — then `specshield deprecations` tracks it draining |
|
|
472
|
+
| Request field or parameter became required | optional again; the report says the server must default it |
|
|
473
|
+
| Field type changed | request: keep the old type · response: keep the old type, new type as `<field>V2` |
|
|
474
|
+
| Format only (`integer` → `int64`) | keep the old format |
|
|
475
|
+
| Enum value removed | keep it (a value renamed while others stay is recognised) |
|
|
476
|
+
| Body changed shape (list → `{ data: [...] }`) | no spec can say both → `--spring` |
|
|
477
|
+
|
|
478
|
+
- **Nothing unverified is written.** Every fix is applied and the diff engine re-run; a fix
|
|
479
|
+
that leaves its breaking change or adds another is dropped and listed with the reason.
|
|
480
|
+
Fixes that depend on each other (restoring a field brings back an enum value it needs)
|
|
481
|
+
are applied in rounds, and the result may not contain any break the target didn't have.
|
|
482
|
+
- The fix is written to `<target>.fixed.yaml` (or `--out`, or `--write` in place) as
|
|
483
|
+
minimal edits: comments, ordering and quoting of every untouched line are kept, so
|
|
484
|
+
`git diff` shows only the fix. `--dry-run` writes nothing; `--json` for scripts.
|
|
485
|
+
- Exit code `0` when everything was fixed, `1` when something still needs a decision.
|
|
486
|
+
- Each fix tells you what the **server** must do for the spec to be true — return the old
|
|
487
|
+
field too, accept the old value, default a missing one.
|
|
488
|
+
|
|
489
|
+
### Spring Boot: old clients keep the old shape
|
|
490
|
+
|
|
491
|
+
Some changes can't be undone in the spec — a list wrapped in an envelope, a field that now
|
|
492
|
+
holds a string. `--spring` generates a Stripe-style **version layer** for a Spring Boot 3
|
|
493
|
+
service instead: the controllers speak only the new API; clients that don't send
|
|
494
|
+
`X-API-Version: 2.0.0` get the old JSON, and their old requests are upgraded on the way in.
|
|
495
|
+
|
|
496
|
+
```bash
|
|
497
|
+
specshield fix base.yaml target.yaml --spring src/main/java --package com.acme.payments.compat
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
- Generated: `ApiVersion_2_0_0.java` (this change's rewrites, as data) plus a small fixed
|
|
501
|
+
runtime — a `ResponseBodyAdvice` and a `RequestBodyAdvice` on Jackson. No changes to
|
|
502
|
+
your controllers.
|
|
503
|
+
- Rewrites: rename a field, convert a scalar's type (`"1250"` ↔ `1250`, only when the value
|
|
504
|
+
converts exactly), map an enum value, default a missing request field, unwrap a list from
|
|
505
|
+
its envelope — at any depth, inside arrays and maps.
|
|
506
|
+
- **Checked before it is generated**: for every operation, a sample payload of the new
|
|
507
|
+
shape is rewritten and validated against the *old* schema (and old requests against the
|
|
508
|
+
new one). A rewrite that can't produce the old shape is not generated — e.g. a required
|
|
509
|
+
field the new code no longer returns at all — and the report says why.
|
|
510
|
+
- Renames and enum mappings are inferred from the diff; they're marked
|
|
511
|
+
`/* inferred rename — check */` in the generated code.
|
|
512
|
+
- Clients with no version header are treated as on the old version, so existing
|
|
513
|
+
integrations keep working without a change. Set the header name with
|
|
514
|
+
`--version-header` or `specshield.compat.header`; a later `fix` run adds another
|
|
515
|
+
`ApiVersion_<v>` class and the layer chains them.
|
|
516
|
+
- Tested by compiling the generated code into a Spring Boot app and calling it as an old
|
|
517
|
+
and a new client (`test-harness/spring-compat/verify.sh`), on Spring Boot 3.2 and 3.5.
|
|
518
|
+
|
|
338
519
|
## Remote Compare
|
|
339
520
|
|
|
340
521
|
Sends your specs to SpecShield's hosted diff engine. Useful for keeping the
|
|
@@ -1294,6 +1475,9 @@ ignore:
|
|
|
1294
1475
|
# maxAgeDays: 30
|
|
1295
1476
|
# minCoverage: 25
|
|
1296
1477
|
# downgrade: true
|
|
1478
|
+
# quietDays: 30 # deprecated + no calls this long = safe to remove
|
|
1479
|
+
# contacts: # who to tell, per client id (* globs)
|
|
1480
|
+
# ShopApp-iOS/*: ios-team@shop.example
|
|
1297
1481
|
|
|
1298
1482
|
# Hosted compare (set --remote on the CLI to override).
|
|
1299
1483
|
remote:
|
|
@@ -1358,6 +1542,7 @@ specshield compare <base> <target> [options]
|
|
|
1358
1542
|
| `--usage-max-age <days>` | The newest log line may be at most this old for unused changes to pass (default `30`) |
|
|
1359
1543
|
| `--usage-min-coverage <pct>` | Percent of spec operations that must appear in the logs for unused changes to pass (default `25`) |
|
|
1360
1544
|
| `--no-usage-downgrade` | Annotate impact only; keep unused breaking changes breaking |
|
|
1545
|
+
| `--usage-quiet-days <n>` | A deprecated item nobody called for this many days may be removed (default `30`) — see [Safe removal](#safe-removal-deprecate--watch-traffic-drain--remove) |
|
|
1361
1546
|
| `--timeout <ms>` | Request timeout for remote mode (default `10000`) |
|
|
1362
1547
|
|
|
1363
1548
|
```bash
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specshield",
|
|
3
|
-
"version": "3.4.
|
|
3
|
+
"version": "3.4.16",
|
|
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",
|
|
@@ -72,7 +72,8 @@
|
|
|
72
72
|
"fs-extra": "^11.2.0",
|
|
73
73
|
"js-yaml": "^4.1.0",
|
|
74
74
|
"ora": "^5.4.1",
|
|
75
|
-
"prompts": "^2.4.2"
|
|
75
|
+
"prompts": "^2.4.2",
|
|
76
|
+
"yaml": "^2.8.1"
|
|
76
77
|
},
|
|
77
78
|
"devDependencies": {
|
|
78
79
|
"jest": "^29.7.0"
|
package/src/api/bdctClient.js
CHANGED
|
@@ -121,6 +121,13 @@ async function governanceGate(server, apiToken, payload) {
|
|
|
121
121
|
} catch (err) { throw apiError(err); }
|
|
122
122
|
}
|
|
123
123
|
|
|
124
|
+
async function uploadDeprecationReport(server, apiToken, payload) {
|
|
125
|
+
try {
|
|
126
|
+
const res = await buildClient(server, apiToken).post('/api/deprecations/reports', payload);
|
|
127
|
+
return res.data;
|
|
128
|
+
} catch (err) { throw apiError(err); }
|
|
129
|
+
}
|
|
130
|
+
|
|
124
131
|
module.exports = {
|
|
125
132
|
publishProviderSpec,
|
|
126
133
|
publishConsumerContract,
|
|
@@ -131,4 +138,5 @@ module.exports = {
|
|
|
131
138
|
listProviderSpecs,
|
|
132
139
|
listConsumerContracts,
|
|
133
140
|
governanceGate,
|
|
141
|
+
uploadDeprecationReport,
|
|
134
142
|
};
|
package/src/cli.js
CHANGED
|
@@ -12,6 +12,8 @@ const historyCommand = require('./commands/history');
|
|
|
12
12
|
const shareCommand = require('./commands/share');
|
|
13
13
|
const whoamiCommand = require('./commands/whoami');
|
|
14
14
|
const usageCommand = require('./commands/usage');
|
|
15
|
+
const deprecationsCommand = require('./commands/deprecations');
|
|
16
|
+
const fixCommand = require('./commands/fix');
|
|
15
17
|
|
|
16
18
|
const program = new Command();
|
|
17
19
|
|
|
@@ -34,6 +36,8 @@ program.addCommand(historyCommand);
|
|
|
34
36
|
program.addCommand(shareCommand);
|
|
35
37
|
program.addCommand(whoamiCommand);
|
|
36
38
|
program.addCommand(usageCommand);
|
|
39
|
+
program.addCommand(deprecationsCommand);
|
|
40
|
+
program.addCommand(fixCommand);
|
|
37
41
|
|
|
38
42
|
program.parseAsync(process.argv).catch((err) => {
|
|
39
43
|
const logger = require('./utils/logger');
|
package/src/commands/compare.js
CHANGED
|
@@ -49,6 +49,7 @@ compare
|
|
|
49
49
|
.option('--usage-max-age <days>', 'Newest log line may be at most this old for unused changes to pass (default: 30)')
|
|
50
50
|
.option('--usage-min-coverage <pct>', 'Percent of spec operations that must appear in the logs for unused changes to pass (default: 25)')
|
|
51
51
|
.option('--no-usage-downgrade', 'Annotate impact only; keep unused breaking changes as breaking')
|
|
52
|
+
.option('--usage-quiet-days <n>', 'A deprecated item nobody called for this many days may be removed (default: 30)')
|
|
52
53
|
.action(async (base, target, opts) => {
|
|
53
54
|
try {
|
|
54
55
|
// Load config
|
|
@@ -182,7 +183,9 @@ async function applyUsage(result, base, options) {
|
|
|
182
183
|
logger.warn(`None of the calls in ${options.usage} match an operation in ${base}. ` +
|
|
183
184
|
'Is it the right usage file? If the API is served under a prefix, re-import with --base-path.');
|
|
184
185
|
}
|
|
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 } };
|
|
186
189
|
}
|
|
187
190
|
|
|
188
191
|
async function runLocalComparison(base, target, options, spinner) {
|
|
@@ -317,6 +320,9 @@ function mergeOptions(config, cliOpts) {
|
|
|
317
320
|
usageMinCoverage: cliOpts.usageMinCoverage !== undefined
|
|
318
321
|
? cliOpts.usageMinCoverage
|
|
319
322
|
: config.usage && config.usage.minCoverage !== undefined ? config.usage.minCoverage : 25,
|
|
323
|
+
usageQuietDays: cliOpts.usageQuietDays !== undefined
|
|
324
|
+
? cliOpts.usageQuietDays
|
|
325
|
+
: config.usage && config.usage.quietDays !== undefined ? config.usage.quietDays : 30,
|
|
320
326
|
usageDowngrade: cliOpts.usageDowngrade === false
|
|
321
327
|
? false
|
|
322
328
|
: !(config.usage && config.usage.downgrade === false),
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { Command } = require('commander');
|
|
4
|
+
const chalk = require('chalk');
|
|
5
|
+
const fsExtra = require('fs-extra');
|
|
6
|
+
const { loadSpec } = require('../core/loadSpec');
|
|
7
|
+
const { parseSpec } = require('../core/parseSpec');
|
|
8
|
+
const { loadConfig } = require('../core/configLoader');
|
|
9
|
+
const { loadProjectConfig } = require('../core/projectConfig');
|
|
10
|
+
const { loadUsage } = require('../core/usage/usageStore');
|
|
11
|
+
const { deprecationReport } = require('../core/usage/deprecations');
|
|
12
|
+
const { fmt, plural, day, spanDays, ago } = require('../core/usage/format');
|
|
13
|
+
const { getStoredApiKey } = require('../config/localConfig');
|
|
14
|
+
const { uploadDeprecationReport } = require('../api/bdctClient');
|
|
15
|
+
const logger = require('../utils/logger');
|
|
16
|
+
const exitAfterFlush = require('../utils/exitAfterFlush');
|
|
17
|
+
|
|
18
|
+
const FAIL_ON = ['none', 'past-sunset', 'in-use'];
|
|
19
|
+
const MAX_CLIENTS_SHOWN = 5;
|
|
20
|
+
|
|
21
|
+
const deprecations = new Command('deprecations')
|
|
22
|
+
.description('Deprecate → watch traffic drain → remove: who still calls each deprecated endpoint, parameter and field')
|
|
23
|
+
.argument('<spec>', 'OpenAPI spec with `deprecated: true` (and optional `x-sunset: YYYY-MM-DD`) markings')
|
|
24
|
+
.option('--usage <file>', 'usage.json from "specshield usage import" (default: usage.file in .specshield.yml)')
|
|
25
|
+
.option('--quiet-days <n>', 'Days without a call before an item is safe to remove (default: 30)')
|
|
26
|
+
.option('--usage-ignore-client <pattern>', 'Leave a client out, e.g. health checks (repeatable; * globs)', collect, [])
|
|
27
|
+
.option('--usage-max-age <days>', 'Newest log line may be at most this old (default: 30)')
|
|
28
|
+
.option('--usage-min-coverage <pct>', 'Percent of spec operations that must appear in the logs (default: 25)')
|
|
29
|
+
.option('--fail-on <when>', `Exit 1 when: ${FAIL_ON.join(' | ')}`, 'none')
|
|
30
|
+
.option('--json', 'Output machine-readable JSON')
|
|
31
|
+
.option('--output <file>', 'Also save the JSON report to this file')
|
|
32
|
+
.option('--csv <file>', 'Write the remaining callers (item, client, calls, last call, contact) as CSV for outreach')
|
|
33
|
+
.option('--upload', 'Send the report to your SpecShield dashboard (Team plan) to track the drain week by week')
|
|
34
|
+
.option('--org <key>', 'Org key for --upload (default: bdct.org in .specshield.yml)')
|
|
35
|
+
.option('--api <name>', 'API name for --upload (default: the spec title)')
|
|
36
|
+
.option('--server <url>', 'SpecShield server URL')
|
|
37
|
+
.option('--api-token <token>', 'API token (overrides env / stored config)')
|
|
38
|
+
.option('--config <path>', 'Path to .specshield.yml config file')
|
|
39
|
+
.action(async (specPath, opts) => {
|
|
40
|
+
try {
|
|
41
|
+
if (!FAIL_ON.includes(opts.failOn)) throw new Error(`--fail-on must be one of ${FAIL_ON.join(', ')}`);
|
|
42
|
+
const config = await loadConfig(opts.config);
|
|
43
|
+
const u = config.usage || {};
|
|
44
|
+
const usageFile = opts.usage || u.file || null;
|
|
45
|
+
|
|
46
|
+
const spec = parseSpec(await loadSpec(specPath), specPath);
|
|
47
|
+
const usage = usageFile ? await loadUsage(usageFile) : null;
|
|
48
|
+
const report = deprecationReport({
|
|
49
|
+
spec,
|
|
50
|
+
usage,
|
|
51
|
+
file: usageFile,
|
|
52
|
+
quietDays: num(opts.quietDays ?? u.quietDays ?? 30, '--quiet-days'),
|
|
53
|
+
ignoreClients: [...opts.usageIgnoreClient, ...(u.ignoreClients || [])],
|
|
54
|
+
maxAgeDays: num(opts.usageMaxAge ?? u.maxAgeDays ?? 30, '--usage-max-age'),
|
|
55
|
+
minCoverage: num(opts.usageMinCoverage ?? u.minCoverage ?? 25, '--usage-min-coverage', 100),
|
|
56
|
+
contacts: u.contacts || {},
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
if (opts.upload) report.upload = await upload(report, spec, opts);
|
|
60
|
+
|
|
61
|
+
const json = JSON.stringify(report, null, 2);
|
|
62
|
+
if (opts.json) process.stdout.write(json + '\n');
|
|
63
|
+
else process.stdout.write(renderReport(report) + '\n');
|
|
64
|
+
if (opts.output) await fsExtra.outputFile(opts.output, json + '\n');
|
|
65
|
+
if (opts.csv) {
|
|
66
|
+
await fsExtra.outputFile(opts.csv, toCsv(report));
|
|
67
|
+
if (!opts.json) logger.info(`Callers written to ${opts.csv}`);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const s = report.summary;
|
|
71
|
+
const failed = (opts.failOn === 'past-sunset' && s.pastSunset > 0) ||
|
|
72
|
+
(opts.failOn === 'in-use' && s.inUse + s.unverifiable > 0);
|
|
73
|
+
exitAfterFlush(failed ? 1 : 0);
|
|
74
|
+
} catch (err) {
|
|
75
|
+
if (err.status === 402) {
|
|
76
|
+
logger.error('Uploading deprecation reports requires a paid plan (Team or above). See https://specshield.io/pricing');
|
|
77
|
+
} else {
|
|
78
|
+
logger.error(`Error: ${err.message}`);
|
|
79
|
+
}
|
|
80
|
+
process.exit(2);
|
|
81
|
+
}
|
|
82
|
+
});
|
|
83
|
+
|
|
84
|
+
async function upload(report, spec, opts) {
|
|
85
|
+
const project = loadProjectConfig();
|
|
86
|
+
const bdct = project.bdct || {};
|
|
87
|
+
const orgKey = opts.org || (bdct.org !== '<replace-me>' ? bdct.org : null);
|
|
88
|
+
const apiName = opts.api || (spec.info && spec.info.title);
|
|
89
|
+
if (!orgKey) throw new Error('--upload needs an org key: pass --org <key> (shown by "specshield whoami" or on the dashboard)');
|
|
90
|
+
if (!apiName) throw new Error('--upload needs an API name: pass --api <name> (the spec has no info.title)');
|
|
91
|
+
const token = opts.apiToken || process.env.SPECSHIELD_API_KEY || (await getStoredApiKey());
|
|
92
|
+
if (!token) throw new Error('No API token found. Pass --api-token, set SPECSHIELD_API_KEY, or run: specshield login --api-key <KEY>');
|
|
93
|
+
const res = await uploadDeprecationReport(opts.server || bdct.server, token, { orgKey, apiName, report });
|
|
94
|
+
return { orgKey, apiName, id: res && res.id, url: res && res.url, changes: (res && res.changes) || [] };
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
// ─── Human output ───────────────────────────────────────────────────────────
|
|
98
|
+
|
|
99
|
+
const SECTIONS = [
|
|
100
|
+
['in-use', (n) => chalk.red.bold(` ✖ STILL CALLED (${n}) — not safe to remove`)],
|
|
101
|
+
['unverifiable', (n) => chalk.yellow.bold(` ? CAN'T VERIFY FROM LOGS (${n}) — the endpoint is still called`)],
|
|
102
|
+
['quiet', (n) => chalk.cyan.bold(` ○ QUIET (${n}) — no calls, keep watching`)],
|
|
103
|
+
['no-data', (n) => chalk.gray.bold(` · NO VERDICT (${n})`)],
|
|
104
|
+
['safe-to-remove', (n) => chalk.green.bold(` ✔ SAFE TO REMOVE (${n})`)],
|
|
105
|
+
];
|
|
106
|
+
|
|
107
|
+
function renderReport(r) {
|
|
108
|
+
const lines = [''];
|
|
109
|
+
const s = r.summary;
|
|
110
|
+
lines.push(chalk.bold(` SpecShield™ Deprecations${r.api.title ? ` — ${r.api.title}` : ''}`));
|
|
111
|
+
lines.push(chalk.gray(' ─────────────────────────────────────────'));
|
|
112
|
+
if (s.total === 0) {
|
|
113
|
+
lines.push(' Nothing in this spec is marked deprecated.');
|
|
114
|
+
lines.push(chalk.gray(' Mark an operation, parameter or schema property with `deprecated: true`'));
|
|
115
|
+
lines.push(chalk.gray(' (and optionally `x-sunset: YYYY-MM-DD`) to start tracking who still uses it.'));
|
|
116
|
+
lines.push('');
|
|
117
|
+
return lines.join('\n');
|
|
118
|
+
}
|
|
119
|
+
if (r.usage) {
|
|
120
|
+
const w = r.usage.window;
|
|
121
|
+
lines.push(chalk.gray(` ${r.usage.file} · ${day(w.from)} → ${day(w.to)} (${spanDays(w)} days) · ` +
|
|
122
|
+
`safe after ${r.quietDays} quiet days`));
|
|
123
|
+
if (r.usage.evidence !== 'ok') lines.push(chalk.yellow(` No verdicts: ${r.usage.evidence}.`));
|
|
124
|
+
}
|
|
125
|
+
lines.push(` ${plural(s.total, 'deprecated item')} · ` + [
|
|
126
|
+
s.inUse && chalk.red(`${s.inUse} still called`),
|
|
127
|
+
s.unverifiable && chalk.yellow(`${s.unverifiable} can't verify`),
|
|
128
|
+
s.quiet && chalk.cyan(`${s.quiet} quiet`),
|
|
129
|
+
s.safeToRemove && chalk.green(`${s.safeToRemove} safe to remove`),
|
|
130
|
+
s.pastSunset && chalk.red.bold(`${s.pastSunset} past sunset`),
|
|
131
|
+
].filter(Boolean).join(' · '));
|
|
132
|
+
|
|
133
|
+
for (const [status, header] of SECTIONS) {
|
|
134
|
+
const items = r.items.filter((i) => i.status === status);
|
|
135
|
+
if (items.length === 0) continue;
|
|
136
|
+
lines.push('');
|
|
137
|
+
lines.push(header(items.length));
|
|
138
|
+
lines.push(chalk.gray(' ─────────────────────────────────────────'));
|
|
139
|
+
if (status === 'no-data' && r.usage === null) {
|
|
140
|
+
lines.push(chalk.gray(' Pass --usage usage.json to see who still calls these.'));
|
|
141
|
+
for (const i of items) lines.push(` ${label(i)}${sunsetNote(i)}`);
|
|
142
|
+
continue;
|
|
143
|
+
}
|
|
144
|
+
for (const i of items) lines.push(...renderItem(i));
|
|
145
|
+
}
|
|
146
|
+
if (r.upload) {
|
|
147
|
+
lines.push('');
|
|
148
|
+
lines.push(chalk.green(` ✔ Uploaded to ${r.upload.orgKey} / ${r.upload.apiName}`) + (r.upload.url ? chalk.gray(` ${r.upload.url}`) : ''));
|
|
149
|
+
if (r.upload.changes.length) lines.push(chalk.bold(' Since the last upload:'));
|
|
150
|
+
for (const c of r.upload.changes) {
|
|
151
|
+
lines.push(` ${c.key} ` + (c.to === 'safe-to-remove' ? chalk.green('→ safe to remove')
|
|
152
|
+
: c.to === 'past-sunset' ? chalk.red(`→ past its sunset, ${plural(c.clients, 'client')} still calling`)
|
|
153
|
+
: chalk.yellow(`→ called again by ${plural(c.clients, 'client')}`)));
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
lines.push('');
|
|
157
|
+
return lines.join('\n');
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
function renderItem(i) {
|
|
161
|
+
const lines = [` ${label(i)}${sunsetNote(i)}`];
|
|
162
|
+
if (i.status === 'in-use' || i.status === 'unverifiable') {
|
|
163
|
+
lines.push(chalk.gray(` ${plural(i.clients.length, 'client')} · ${plural(i.calls, 'call')} · last call ${ago(i.lastSeen)}`) +
|
|
164
|
+
(i.weeks.length > 1 ? chalk.gray(' weekly ') + sparkline(i.weeks) : ''));
|
|
165
|
+
const shown = i.clients.slice(0, MAX_CLIENTS_SHOWN);
|
|
166
|
+
const width = Math.min(32, Math.max(...shown.map((c) => c.id.length)));
|
|
167
|
+
for (const c of shown) {
|
|
168
|
+
lines.push(` ${chalk.bold(c.id.padEnd(width))} ${fmt(c.calls).padStart(8)} ` +
|
|
169
|
+
chalk.gray(`last ${ago(c.lastSeen)}`) + (c.contact ? chalk.cyan(` → ${c.contact}`) : ''));
|
|
170
|
+
}
|
|
171
|
+
if (i.clients.length > shown.length) lines.push(chalk.gray(` …and ${i.clients.length - shown.length} more (--csv for all)`));
|
|
172
|
+
} else {
|
|
173
|
+
lines.push(chalk.gray(` ${i.reason}`) + (i.weeks.length > 1 && i.calls > 0 ? chalk.gray(' weekly ') + sparkline(i.weeks) : ''));
|
|
174
|
+
}
|
|
175
|
+
if (i.status === 'unverifiable') lines.push(chalk.gray(` (${i.reason})`));
|
|
176
|
+
return lines;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
function label(i) {
|
|
180
|
+
if (i.kind === 'schema-field') {
|
|
181
|
+
const n = new Set(i.occurrences.map((o) => `${o.method} ${o.path}`)).size;
|
|
182
|
+
return `${chalk.bold('schema')} ${chalk.magenta(i.field)}` + chalk.gray(` used by ${plural(n, 'operation')}`);
|
|
183
|
+
}
|
|
184
|
+
const op = `${chalk.bold(i.method.padEnd(6))} ${i.path}`;
|
|
185
|
+
if (i.kind === 'operation') return op;
|
|
186
|
+
if (i.kind === 'parameter') return `${op} ${chalk.magenta(`${i.in} parameter "${i.name}"`)}`;
|
|
187
|
+
return `${op} ${chalk.magenta(i.field)}`;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
function sunsetNote(i) {
|
|
191
|
+
if (!i.sunset) return '';
|
|
192
|
+
if (i.daysToSunset === undefined) return chalk.gray(` · sunset ${i.sunset}`);
|
|
193
|
+
if (i.pastSunset) return chalk.red.bold(` · sunset ${i.sunset} PASSED ${-i.daysToSunset} days ago`);
|
|
194
|
+
if (i.daysToSunset < 0) return chalk.gray(` · sunset ${i.sunset} (passed)`);
|
|
195
|
+
return chalk.gray(` · sunset ${i.sunset} (in ${plural(i.daysToSunset, 'day')})`);
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
const BARS = '▁▂▃▄▅▆▇█';
|
|
199
|
+
/** Weekly calls, oldest → newest; · is a week with none. Partial weeks (window edges) are dimmed. */
|
|
200
|
+
function sparkline(weeks) {
|
|
201
|
+
const max = Math.max(...weeks.map((w) => w.calls), 1);
|
|
202
|
+
return weeks.map((w) => {
|
|
203
|
+
if (w.calls === 0) return chalk.gray('·');
|
|
204
|
+
const ch = BARS[Math.min(7, Math.floor((w.calls / max) * 7.999))];
|
|
205
|
+
return w.partial ? chalk.gray(ch) : chalk.yellow(ch);
|
|
206
|
+
}).join('');
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
function toCsv(r) {
|
|
210
|
+
const rows = [['item', 'kind', 'status', 'sunset', 'client', 'calls', 'last_call', 'contact']];
|
|
211
|
+
for (const i of r.items) {
|
|
212
|
+
for (const c of i.clients) {
|
|
213
|
+
rows.push([i.key, i.kind, i.status, i.sunset || '', c.id, c.calls, c.lastSeen || '', c.contact || '']);
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
return rows.map((row) => row.map(csvCell).join(',')).join('\n') + '\n';
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
function csvCell(v) {
|
|
220
|
+
const s = String(v);
|
|
221
|
+
// A leading = + - @ makes spreadsheets evaluate the cell; client ids come from logs.
|
|
222
|
+
const safe = /^[=+\-@]/.test(s) ? `'${s}` : s;
|
|
223
|
+
return /[",\n]/.test(safe) ? `"${safe.replace(/"/g, '""')}"` : safe;
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
function num(value, flag, max = Infinity) {
|
|
227
|
+
const n = Number(value);
|
|
228
|
+
if (!Number.isFinite(n) || n < 0 || n > max) throw new Error(`${flag} must be a number from 0 to ${max}, got "${value}"`);
|
|
229
|
+
return n;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
function collect(value, previous) {
|
|
233
|
+
return previous.concat([value]);
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
module.exports = deprecations;
|