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 CHANGED
@@ -1,6 +1,63 @@
1
1
  # SpecShield CLI changelog
2
2
 
3
- ## Unreleased — Kubernetes audit logs, Swagger 2.0 bodies
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.14",
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"
@@ -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');
@@ -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
- return { ...annotated, usage: meta };
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;