specshield 3.4.13 → 3.4.15
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 +55 -1
- package/README.md +114 -4
- package/package.json +1 -1
- package/src/api/bdctClient.js +8 -0
- package/src/cli.js +2 -0
- package/src/commands/compare.js +7 -1
- package/src/commands/deprecations.js +236 -0
- package/src/core/configLoader.js +6 -1
- package/src/core/normalizeSpec.js +67 -11
- package/src/core/outputFormatter.js +22 -1
- package/src/core/usage/deprecations.js +438 -0
- package/src/core/usage/impact.js +62 -28
- package/src/core/usage/logParsers.js +39 -1
- package/src/core/usage/usageStore.js +32 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,60 @@
|
|
|
1
1
|
# SpecShield CLI changelog
|
|
2
2
|
|
|
3
|
-
## Unreleased —
|
|
3
|
+
## Unreleased — safe removal: deprecate → watch traffic drain → remove
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **`specshield deprecations <spec> --usage usage.json`** lists everything the spec marks
|
|
8
|
+
`deprecated: true` (or gives an `x-sunset` date) — operations, parameters, request and
|
|
9
|
+
response fields — with who still calls it, the last call, calls per week, and a status:
|
|
10
|
+
still called · can't verify · quiet · safe to remove · no verdict. `--quiet-days`
|
|
11
|
+
(default 30), `--csv` (callers for outreach, spreadsheet-formula safe), `--fail-on
|
|
12
|
+
past-sunset|in-use`, `--json`, and `--upload --org <key>` to the dashboard (Team plan).
|
|
13
|
+
- `.specshield.yml` `usage.contacts` maps client ids (or `*` globs) to an owner, shown in
|
|
14
|
+
the report and the CSV; `usage.quietDays` sets the quiet period.
|
|
15
|
+
- `compare --usage` marks every removal with whether the base spec deprecated it first
|
|
16
|
+
(`deprecation` in `--json`). A deprecated item with no calls for `--usage-quiet-days`
|
|
17
|
+
(default 30) has drained and no longer fails the build; one still called stays breaking
|
|
18
|
+
with its callers; a removal that was never deprecated is flagged.
|
|
19
|
+
- `usage import` records calls per week per client and when each query parameter was last
|
|
20
|
+
sent (additive `weeks` / `paramsLastSeen` in usage.json; older files still load).
|
|
21
|
+
|
|
22
|
+
### Tested on real data
|
|
23
|
+
|
|
24
|
+
Kubernetes' published CI audit log (106,445 requests) against the official
|
|
25
|
+
`swagger.json`, with the upstream deprecations marked (the `v1 Endpoints` API, deprecated
|
|
26
|
+
in v1.33; the `watch` endpoints; 9 fields documented as deprecated). Every per-operation
|
|
27
|
+
count for the Endpoints API matched the raw audit events exactly. This run found that a
|
|
28
|
+
deprecated property of a shared schema (`ObjectMeta.selfLink`) was listed once per
|
|
29
|
+
operation and status code — 1,733 rows — so such properties are now one row each.
|
|
30
|
+
|
|
31
|
+
## 3.4.14 — 2026-10-26 — Kubernetes audit logs, Swagger 2.0 bodies
|
|
32
|
+
|
|
33
|
+
Tested on the Kubernetes project's own published data: the API-server audit log of
|
|
34
|
+
CI job `ci-kubernetes-audit-kind-conformance` (219,507 events, k8s master `765dd1d`) and
|
|
35
|
+
the official `api/openapi-spec/swagger.json` at `765dd1d` and `v1.37.1`. Impact numbers
|
|
36
|
+
were checked against counts taken directly from the raw audit events.
|
|
37
|
+
|
|
38
|
+
### Added
|
|
39
|
+
|
|
40
|
+
- `usage import` reads **Kubernetes API-server audit logs** (`audit.k8s.io` Events):
|
|
41
|
+
verbs map to HTTP methods, and only the final stage (`ResponseComplete`/`Panic`) is
|
|
42
|
+
counted — the same request is otherwise logged up to three times.
|
|
43
|
+
|
|
44
|
+
### Fixed
|
|
45
|
+
|
|
46
|
+
- **Swagger 2.0 request and response bodies were not compared.** `#/definitions/` refs,
|
|
47
|
+
the `in: body` parameter and `responses.<code>.schema` were ignored, so a removed or
|
|
48
|
+
newly required field reported "No changes". Comparing Kubernetes v1.37.1 → master now
|
|
49
|
+
finds the 18 schemas whose fields became required.
|
|
50
|
+
- Path-level parameters and `$ref` parameters/responses (OpenAPI 3 and Swagger 2.0) are
|
|
51
|
+
now resolved; they were skipped before.
|
|
52
|
+
- Usage impact of request-body changes no longer counts `GET`/`HEAD`/`OPTIONS` calls, and a
|
|
53
|
+
merged change listing the same endpoint twice no longer double-counts its traffic (on
|
|
54
|
+
Kubernetes data: 551 → 12 calls for `events.k8s.io/v1` Event fields, matching the raw
|
|
55
|
+
log exactly).
|
|
56
|
+
|
|
57
|
+
## 3.4.13 — 2026-10-25 — usage-aware compare: "who does this change break?"
|
|
4
58
|
|
|
5
59
|
### Added
|
|
6
60
|
|
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) · [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)
|
|
@@ -278,8 +278,13 @@ specshield usage import /var/log/nginx/access.log* --spec api/openapi.yaml
|
|
|
278
278
|
```
|
|
279
279
|
|
|
280
280
|
- **Formats:** nginx/Apache combined & common, AWS ALB, and JSON lines (nginx JSON
|
|
281
|
-
`log_format`, Kong file-log, API Gateway,
|
|
282
|
-
|
|
281
|
+
`log_format`, Kong file-log, API Gateway, Caddy, Traefik, Envoy, Google Cloud LB, ECS,
|
|
282
|
+
and **Kubernetes API-server audit logs**). Auto-detected; `.gz` files and stdin (`-`)
|
|
283
|
+
work. Force one with `--format combined|alb|json`.
|
|
284
|
+
- **Kubernetes:** point it at the API-server audit log and the cluster's
|
|
285
|
+
`swagger.json`, and identify clients by their authenticated identity:
|
|
286
|
+
`specshield usage import audit.log --spec swagger.json --client field:user.username`.
|
|
287
|
+
Each request is counted once (final audit stage only).
|
|
283
288
|
- **Clients** are identified by User-Agent by default (`MyShop-iOS/5.2.1` → `MyShop-iOS/5.2`).
|
|
284
289
|
Use a better signal if you log one: `--client field:consumer.username` (JSON logs),
|
|
285
290
|
`--client extra:1` (first quoted field after the User-Agent in combined logs), and prefix
|
|
@@ -304,7 +309,9 @@ specshield compare base.yaml target.yaml --usage usage.json --fail-on-breaking
|
|
|
304
309
|
|
|
305
310
|
- **Endpoint and method removals, body/response field changes** → the clients calling that
|
|
306
311
|
operation. Access logs don't show which response fields a client reads, so for field
|
|
307
|
-
changes this is "clients that may be affected", and the report says so.
|
|
312
|
+
changes this is "clients that may be affected", and the report says so. Request-body
|
|
313
|
+
changes (a field removed or made required) count only calls that send a body — `GET`
|
|
314
|
+
traffic can't be affected by them.
|
|
308
315
|
- **Query parameters** are judged exactly: a removed parameter affects only clients that
|
|
309
316
|
*send* it; a parameter that became required affects only clients that *omit* it.
|
|
310
317
|
- **Zero calls → "breaking but unused"**: listed separately and excluded from
|
|
@@ -328,6 +335,105 @@ specshield usage show usage.json --spec api/openapi.yaml
|
|
|
328
335
|
# CALLED BUT NOT IN THE SPEC → shadow endpoints your spec is missing
|
|
329
336
|
```
|
|
330
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
|
+
|
|
331
437
|
## Remote Compare
|
|
332
438
|
|
|
333
439
|
Sends your specs to SpecShield's hosted diff engine. Useful for keeping the
|
|
@@ -1287,6 +1393,9 @@ ignore:
|
|
|
1287
1393
|
# maxAgeDays: 30
|
|
1288
1394
|
# minCoverage: 25
|
|
1289
1395
|
# downgrade: true
|
|
1396
|
+
# quietDays: 30 # deprecated + no calls this long = safe to remove
|
|
1397
|
+
# contacts: # who to tell, per client id (* globs)
|
|
1398
|
+
# ShopApp-iOS/*: ios-team@shop.example
|
|
1290
1399
|
|
|
1291
1400
|
# Hosted compare (set --remote on the CLI to override).
|
|
1292
1401
|
remote:
|
|
@@ -1351,6 +1460,7 @@ specshield compare <base> <target> [options]
|
|
|
1351
1460
|
| `--usage-max-age <days>` | The newest log line may be at most this old for unused changes to pass (default `30`) |
|
|
1352
1461
|
| `--usage-min-coverage <pct>` | Percent of spec operations that must appear in the logs for unused changes to pass (default `25`) |
|
|
1353
1462
|
| `--no-usage-downgrade` | Annotate impact only; keep unused breaking changes breaking |
|
|
1463
|
+
| `--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) |
|
|
1354
1464
|
| `--timeout <ms>` | Request timeout for remote mode (default `10000`) |
|
|
1355
1465
|
|
|
1356
1466
|
```bash
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specshield",
|
|
3
|
-
"version": "3.4.
|
|
3
|
+
"version": "3.4.15",
|
|
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
|
@@ -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,7 @@ 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');
|
|
15
16
|
|
|
16
17
|
const program = new Command();
|
|
17
18
|
|
|
@@ -34,6 +35,7 @@ program.addCommand(historyCommand);
|
|
|
34
35
|
program.addCommand(shareCommand);
|
|
35
36
|
program.addCommand(whoamiCommand);
|
|
36
37
|
program.addCommand(usageCommand);
|
|
38
|
+
program.addCommand(deprecationsCommand);
|
|
37
39
|
|
|
38
40
|
program.parseAsync(process.argv).catch((err) => {
|
|
39
41
|
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;
|
package/src/core/configLoader.js
CHANGED
|
@@ -116,7 +116,7 @@ function validateConfig(config, filePath) {
|
|
|
116
116
|
if (u.minDays !== undefined && !(Number(u.minDays) >= 0)) {
|
|
117
117
|
throw new Error(`Config error in "${filePath}": usage.minDays must be a number ≥ 0`);
|
|
118
118
|
}
|
|
119
|
-
for (const key of ['maxAgeDays', 'minCoverage']) {
|
|
119
|
+
for (const key of ['maxAgeDays', 'minCoverage', 'quietDays']) {
|
|
120
120
|
if (u[key] !== undefined && !(Number(u[key]) >= 0)) {
|
|
121
121
|
throw new Error(`Config error in "${filePath}": usage.${key} must be a number ≥ 0`);
|
|
122
122
|
}
|
|
@@ -124,6 +124,9 @@ function validateConfig(config, filePath) {
|
|
|
124
124
|
if (u.downgrade !== undefined && typeof u.downgrade !== 'boolean') {
|
|
125
125
|
throw new Error(`Config error in "${filePath}": usage.downgrade must be a boolean`);
|
|
126
126
|
}
|
|
127
|
+
if (u.contacts !== undefined && (typeof u.contacts !== 'object' || u.contacts === null || Array.isArray(u.contacts))) {
|
|
128
|
+
throw new Error(`Config error in "${filePath}": usage.contacts must map client ids to contacts`);
|
|
129
|
+
}
|
|
127
130
|
valid.usage = {
|
|
128
131
|
file: u.file || null,
|
|
129
132
|
ignoreClients: (u.ignoreClients || []).filter(Boolean).map(String),
|
|
@@ -131,6 +134,8 @@ function validateConfig(config, filePath) {
|
|
|
131
134
|
maxAgeDays: u.maxAgeDays !== undefined ? Number(u.maxAgeDays) : undefined,
|
|
132
135
|
minCoverage: u.minCoverage !== undefined ? Number(u.minCoverage) : undefined,
|
|
133
136
|
downgrade: u.downgrade,
|
|
137
|
+
quietDays: u.quietDays !== undefined ? Number(u.quietDays) : undefined,
|
|
138
|
+
contacts: u.contacts || {},
|
|
134
139
|
};
|
|
135
140
|
} else {
|
|
136
141
|
throw new Error(`Config error in "${filePath}": usage must be a file path or an object`);
|