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 CHANGED
@@ -1,6 +1,60 @@
1
1
  # SpecShield CLI changelog
2
2
 
3
- ## Unreleased — usage-aware compare: "who does this change break?"
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, Envoy/Traefik, ECS). Auto-detected; `.gz`
282
- files and stdin (`-`) work. Force one with `--format combined|alb|json`.
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.13",
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",
@@ -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');
@@ -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;
@@ -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`);