specshield 3.4.14 → 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,34 @@
1
1
  # SpecShield CLI changelog
2
2
 
3
- ## Unreleased — Kubernetes audit logs, Swagger 2.0 bodies
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
4
32
 
5
33
  Tested on the Kubernetes project's own published data: the API-server audit log of
6
34
  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) · [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,105 @@ 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
+
338
437
  ## Remote Compare
339
438
 
340
439
  Sends your specs to SpecShield's hosted diff engine. Useful for keeping the
@@ -1294,6 +1393,9 @@ ignore:
1294
1393
  # maxAgeDays: 30
1295
1394
  # minCoverage: 25
1296
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
1297
1399
 
1298
1400
  # Hosted compare (set --remote on the CLI to override).
1299
1401
  remote:
@@ -1358,6 +1460,7 @@ specshield compare <base> <target> [options]
1358
1460
  | `--usage-max-age <days>` | The newest log line may be at most this old for unused changes to pass (default `30`) |
1359
1461
  | `--usage-min-coverage <pct>` | Percent of spec operations that must appear in the logs for unused changes to pass (default `25`) |
1360
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) |
1361
1464
  | `--timeout <ms>` | Request timeout for remote mode (default `10000`) |
1362
1465
 
1363
1466
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specshield",
3
- "version": "3.4.14",
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`);
@@ -38,6 +38,7 @@ function formatHuman(result) {
38
38
  lines.push(` ${chalk.gray('from:')} ${chalk.red(c.oldValue)} ${chalk.gray('→')} ${chalk.green(c.newValue)}`);
39
39
  }
40
40
  if (c.impact) lines.push(...formatImpact(c, { detailed: true }));
41
+ if (c.deprecation) lines.push(formatDeprecation(c));
41
42
  }
42
43
  lines.push('');
43
44
  }
@@ -45,13 +46,16 @@ function formatHuman(result) {
45
46
  if (unused.length > 0) {
46
47
  const w = result.usage && result.usage.window;
47
48
  lines.push(chalk.green.bold(' ✔ BREAKING BUT UNUSED — safe to ship'));
48
- lines.push(chalk.gray(` 0 calls ${w && w.from ? `between ${day(w.from)} and ${day(w.to)}` : 'in the usage window'}; these do not fail the build`));
49
+ const drained = unused.some((c) => c.deprecation && c.deprecation.drained);
50
+ lines.push(chalk.gray(` 0 calls ${w && w.from ? `between ${day(w.from)} and ${day(w.to)}` : 'in the usage window'}` +
51
+ (drained ? ` — or deprecated and quiet for ${result.usage.quietDays}+ days` : '') + '; these do not fail the build'));
49
52
  lines.push(chalk.gray(' ─────────────────────────────────────────'));
50
53
  for (const c of unused) {
51
54
  lines.push(` ${chalk.green('○')} ${c.description}`);
52
55
  if (c.impact && c.impact.basis === 'query-parameter') {
53
56
  lines.push(chalk.gray(` no client ${c.impact.parameterUse === 'omitted' ? 'omits' : 'sends'} "${c.impact.parameter}"`));
54
57
  }
58
+ if (c.deprecation) lines.push(formatDeprecation(c));
55
59
  }
56
60
  lines.push('');
57
61
  }
@@ -156,6 +160,23 @@ function formatImpact(c, { detailed }) {
156
160
  return lines;
157
161
  }
158
162
 
163
+ /** Removals only: was this deprecated in the base spec before it was removed? */
164
+ function formatDeprecation(c) {
165
+ const d = c.deprecation;
166
+ const used = c.impact && c.impact.verdict === 'used';
167
+ if (d.deprecated) {
168
+ const sunset = d.sunset ? ` (sunset ${d.sunset})` : '';
169
+ if (d.drained) {
170
+ return chalk.gray(` ↳ deprecated${sunset} · drained: last call ${day(c.impact.lastSeen)}, ${d.quietForDays} days before the newest log line`);
171
+ }
172
+ return used
173
+ ? chalk.yellow(` ↳ deprecated${sunset}, but still called — tell the clients above before removing it`)
174
+ : chalk.gray(` ↳ deprecated${sunset} and unused — removal is the planned last step`);
175
+ }
176
+ return chalk.yellow(' ↳ removed without being deprecated first — callers got no warning' +
177
+ (used ? '. Mark it `deprecated: true` and watch it drain: specshield deprecations' : ''));
178
+ }
179
+
159
180
  function scope(i) {
160
181
  if (i.basis !== 'query-parameter') return '';
161
182
  return i.parameterUse === 'omitted'
@@ -0,0 +1,438 @@
1
+ 'use strict';
2
+
3
+ const { indexUsage, downgradeBlocker, isObjectSchema, compileClientPatterns, BODYLESS_METHODS } = require('./impact');
4
+ const { resolveSchema } = require('../normalizeSpec');
5
+ const { weekOf } = require('./usageStore');
6
+
7
+ /**
8
+ * Safe-removal workflow: deprecate → watch traffic drain → remove.
9
+ *
10
+ * collectDeprecations() lists what the spec marks `deprecated: true` (or gives
11
+ * an `x-sunset` date): operations, parameters, and request/response fields.
12
+ * deprecationReport() joins that list to a usage file and says, per item, who
13
+ * still calls it and whether it is safe to remove:
14
+ *
15
+ * in-use called in the last week of the usage window
16
+ * quiet draining: no calls for a week or more, but not for
17
+ * `quietDays` yet — keep watching
18
+ * safe-to-remove no calls for at least `quietDays`
19
+ * unverifiable a body field or header: logs can't show who sends or reads
20
+ * it, and the endpoint is still called
21
+ * no-data the usage file can't support a verdict (stale, filtered…)
22
+ *
23
+ * A deprecated property of a shared schema (one `$ref`'d component used by
24
+ * many operations) is one item — `kind: 'schema-field'` — judged by the
25
+ * traffic of every operation that uses it. Listing it once per operation and
26
+ * status code turned one deprecation (Kubernetes' ObjectMeta.selfLink) into
27
+ * 1,700 rows on real data.
28
+ *
29
+ * Field paths match the compare engine's (`parameters.sort`,
30
+ * `requestBody.owner.name`, `responses.200.items[items].tag`) so a removal in
31
+ * compare can be tied back to its deprecation.
32
+ */
33
+
34
+ const DAY = 86400e3;
35
+ const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
36
+ const MAX_DEPTH = 12;
37
+ const STATUS_ORDER = ['in-use', 'unverifiable', 'quiet', 'no-data', 'safe-to-remove'];
38
+ // A call this recent means "still in use", not "draining".
39
+ const ACTIVE_DAYS = 7;
40
+
41
+ function collectDeprecations(spec) {
42
+ const items = [];
43
+ const seen = new Set();
44
+ const push = (item) => {
45
+ if (seen.has(item.key)) return;
46
+ seen.add(item.key);
47
+ items.push(item);
48
+ };
49
+ const components = spec.components || {};
50
+ const ctx = {
51
+ schemas: components.schemas || spec.definitions || {},
52
+ parameters: components.parameters || spec.parameters || {},
53
+ responses: components.responses || spec.responses || {},
54
+ requestBodies: components.requestBodies || {},
55
+ };
56
+
57
+ for (const [path, pathItem] of Object.entries(spec.paths || {})) {
58
+ if (!pathItem || typeof pathItem !== 'object') continue;
59
+ for (const m of HTTP_METHODS) {
60
+ const op = pathItem[m];
61
+ if (!op || typeof op !== 'object') continue;
62
+ const method = m.toUpperCase();
63
+ const base = { method, path };
64
+
65
+ if (isDeprecated(op)) {
66
+ // Everything under a deprecated operation goes with it — listing its
67
+ // fields too would only repeat the same callers.
68
+ push({ ...base, key: `${method} ${path}`, kind: 'operation', field: null, sunset: sunsetOf(op), summary: op.summary || null });
69
+ continue;
70
+ }
71
+
72
+ let body = null;
73
+ for (const p of mergeParameters(pathItem.parameters, op.parameters, ctx)) {
74
+ if (p.in === 'body') { body = p.schema || null; continue; } // Swagger 2.0
75
+ if (!isDeprecated(p)) continue;
76
+ push({
77
+ ...base, key: `${method} ${path} parameters.${p.name}`, kind: 'parameter',
78
+ field: `parameters.${p.name}`, in: p.in, name: p.name, sunset: sunsetOf(p),
79
+ objectSchema: p.in === 'query' && isObjectSchema(paramSchema(p, ctx)),
80
+ });
81
+ }
82
+
83
+ const requestBody = deref(op.requestBody, ctx.requestBodies, '#/components/requestBodies/');
84
+ if (requestBody && requestBody.content) body = mediaSchema(requestBody.content);
85
+ if (body) walkSchema(body, 'requestBody', { ...base, kind: 'request-field' }, ctx, push, [], null);
86
+
87
+ for (const [code, raw] of Object.entries(op.responses || {})) {
88
+ const resp = deref(raw, ctx.responses, '#/components/responses/', '#/responses/');
89
+ if (!resp) continue;
90
+ const schema = resp.schema || (resp.content ? mediaSchema(resp.content) : null);
91
+ if (schema) walkSchema(schema, `responses.${code}`, { ...base, kind: 'response-field' }, ctx, push, [], null);
92
+ }
93
+ }
94
+ }
95
+ return items;
96
+ }
97
+
98
+ /**
99
+ * `origin` names where a property is declared, independent of the operation:
100
+ * "Pet.owner.phone" for a property reached through the Pet component. Null
101
+ * for inline schemas, which belong to their one operation.
102
+ */
103
+ function walkSchema(raw, prefix, base, ctx, push, refStack, origin) {
104
+ if (!raw || typeof raw !== 'object' || refStack.length > MAX_DEPTH) return;
105
+ let schema = raw;
106
+ let stack = refStack;
107
+ if (raw.$ref) {
108
+ if (refStack.includes(raw.$ref)) return; // recursive schema
109
+ schema = deref(raw, ctx.schemas, '#/components/schemas/', '#/definitions/');
110
+ if (!schema) return;
111
+ stack = [...refStack, raw.$ref];
112
+ origin = schemaName(raw.$ref);
113
+ }
114
+ const sub = (suffix) => (origin ? `${origin}${suffix}` : null);
115
+ for (const part of schema.allOf || []) walkSchema(part, prefix, base, ctx, push, stack, origin);
116
+ for (const key of ['oneOf', 'anyOf']) {
117
+ (schema[key] || []).forEach((v, i) => walkSchema(v, `${prefix}[${i}]`, base, ctx, push, stack, sub(`[${i}]`)));
118
+ }
119
+ for (const [name, prop] of Object.entries(schema.properties || {})) {
120
+ const field = `${prefix}.${name}`;
121
+ const resolved = prop && prop.$ref ? deref(prop, ctx.schemas, '#/components/schemas/', '#/definitions/') : prop;
122
+ // `deprecated` beside a $ref is how 3.1 marks a referenced property; on the
123
+ // target schema it marks every use of it.
124
+ if (isDeprecated(prop) || isDeprecated(resolved)) {
125
+ push({
126
+ ...base, key: `${base.method} ${base.path} ${field}`, field, sunset: sunsetOf(prop) || sunsetOf(resolved),
127
+ origin: isDeprecated(prop) ? sub(`.${name}`) : schemaName(prop.$ref),
128
+ });
129
+ continue;
130
+ }
131
+ walkSchema(prop, field, base, ctx, push, stack, sub(`.${name}`));
132
+ }
133
+ if (schema.items) walkSchema(schema.items, `${prefix}[items]`, base, ctx, push, stack, sub('[items]'));
134
+ }
135
+
136
+ /**
137
+ * Folds the per-operation occurrences of a shared-schema property into one
138
+ * 'schema-field' item. A property used by a single operation stays as it is.
139
+ */
140
+ function groupDeprecations(occurrences) {
141
+ const groups = new Map();
142
+ const out = [];
143
+ for (const o of occurrences) {
144
+ if (!o.origin) { out.push(o); continue; }
145
+ let g = groups.get(o.origin);
146
+ if (!g) {
147
+ g = { key: `schema ${o.origin}`, kind: 'schema-field', method: null, path: null, field: o.origin,
148
+ sunset: o.sunset, occurrences: [], first: o };
149
+ groups.set(o.origin, g);
150
+ out.push(g);
151
+ }
152
+ g.occurrences.push({ method: o.method, path: o.path, field: o.field, side: o.kind === 'request-field' ? 'request' : 'response' });
153
+ }
154
+ return out.map((i) => {
155
+ if (i.kind !== 'schema-field') return i;
156
+ const { first, ...g } = i;
157
+ return new Set(g.occurrences.map((o) => `${o.method} ${o.path}`)).size === 1 && g.occurrences.length === 1 ? first : g;
158
+ });
159
+ }
160
+
161
+ /**
162
+ * Joins the deprecations of `spec` to a usage file. Without usage, every item
163
+ * is 'no-data' — the report then only lists what is deprecated.
164
+ */
165
+ function deprecationReport({
166
+ spec, usage = null, file = 'usage.json', quietDays = 30, ignoreClients = [],
167
+ maxAgeDays = 30, minCoverage = 25, contacts = {}, now = Date.now(),
168
+ }) {
169
+ const items = groupDeprecations(collectDeprecations(spec));
170
+ const contactOf = compileContacts(contacts);
171
+ let meta = null;
172
+ let opIndex = new Map();
173
+ let blocker = 'no usage file was given (--usage)';
174
+
175
+ if (usage) {
176
+ ({ opIndex, meta } = indexUsage(usage, spec, { file, ignoreClients, now }));
177
+ blocker = downgradeBlocker(meta, { downgrade: true, minDays: 0, maxAgeDays, minCoverage });
178
+ }
179
+ const to = meta && meta.window.to ? Date.parse(meta.window.to) : null;
180
+ const activeSince = to !== null ? to - Math.min(ACTIVE_DAYS, quietDays) * DAY : null;
181
+
182
+ const out = items.map((item) => {
183
+ const judged = judge(item, opIndex, { activeSince, to, meta, quietDays, blocker });
184
+ const { objectSchema, origin, ...rest } = item;
185
+ const r = { ...rest, ...judged };
186
+ r.clients = r.clients.map((c) => ({ ...c, contact: contactOf(c.id) }));
187
+ const sunsetMs = item.sunset ? Date.parse(item.sunset) : NaN;
188
+ if (!Number.isNaN(sunsetMs)) {
189
+ r.daysToSunset = Math.ceil((sunsetMs - now) / DAY);
190
+ r.pastSunset = r.daysToSunset < 0 && (r.status === 'in-use' || r.status === 'unverifiable');
191
+ }
192
+ return r;
193
+ }).sort((a, b) =>
194
+ STATUS_ORDER.indexOf(a.status) - STATUS_ORDER.indexOf(b.status) ||
195
+ (b.pastSunset === true) - (a.pastSunset === true) ||
196
+ b.calls - a.calls || a.key.localeCompare(b.key));
197
+
198
+ const summary = { total: out.length, pastSunset: out.filter((i) => i.pastSunset).length };
199
+ for (const s of STATUS_ORDER) summary[camel(s)] = out.filter((i) => i.status === s).length;
200
+
201
+ return {
202
+ api: { title: (spec.info && spec.info.title) || null, version: (spec.info && spec.info.version) || null },
203
+ quietDays,
204
+ usage: meta ? { ...meta, evidence: blocker === null ? 'ok' : blocker } : null,
205
+ summary,
206
+ items: out,
207
+ };
208
+ }
209
+
210
+ /** The operations whose callers an item is judged by, each once. */
211
+ function operationsOf(item) {
212
+ if (item.kind !== 'schema-field') {
213
+ // A GET carries no request body: nobody can be sending the field.
214
+ if (item.kind === 'request-field' && BODYLESS_METHODS.has(item.method)) return [];
215
+ return [`${item.method} ${item.path}`];
216
+ }
217
+ const ops = new Set();
218
+ for (const o of item.occurrences) {
219
+ if (o.side === 'request' && BODYLESS_METHODS.has(o.method)) continue;
220
+ ops.add(`${o.method} ${o.path}`);
221
+ }
222
+ return [...ops];
223
+ }
224
+
225
+ function judge(item, opIndex, { activeSince, to, meta, quietDays, blocker }) {
226
+ const ops = operationsOf(item);
227
+ const sources = ops.map((op) => opIndex.get(op)).filter(Boolean);
228
+ // Logs record the query string, so a scalar query parameter is judged by who
229
+ // sends it. Header/cookie/path params and body fields are judged by who
230
+ // calls the endpoint, which can only ever clear them, never convict them.
231
+ const byParam = item.kind === 'parameter' && item.in === 'query' && !item.objectSchema &&
232
+ !sources.some((byClient) => [...byClient.values()].some((c) => c.paramsTruncated));
233
+ const exact = item.kind === 'operation' || byParam;
234
+
235
+ const byId = new Map();
236
+ const weeks = {};
237
+ for (const byClient of sources) {
238
+ for (const [id, c] of byClient) {
239
+ const calls = byParam ? c.params[item.name] || 0 : c.calls;
240
+ if (calls <= 0) continue;
241
+ const seen = byParam ? c.paramsLastSeen[item.name] ?? c.lastSeen : c.lastSeen;
242
+ const agg = byId.get(id) || { id, calls: 0, lastSeen: null };
243
+ agg.calls += calls;
244
+ if (seen !== null && (agg.lastSeen === null || seen > agg.lastSeen)) agg.lastSeen = seen;
245
+ byId.set(id, agg);
246
+ // Weekly counts are per endpoint: they describe a parameter's senders
247
+ // only as "callers of the endpoint", so parameters get none.
248
+ if (!byParam) for (const [w, n] of Object.entries(c.weeks)) weeks[w] = (weeks[w] || 0) + n;
249
+ }
250
+ }
251
+ const clients = [...byId.values()]
252
+ .map((c) => ({ id: c.id, calls: c.calls, lastSeen: c.lastSeen === null ? null : new Date(c.lastSeen).toISOString() }))
253
+ .sort((a, b) => b.calls - a.calls || a.id.localeCompare(b.id));
254
+ const calls = clients.reduce((n, c) => n + c.calls, 0);
255
+ const lastSeen = clients.reduce((t, c) => (c.lastSeen && (!t || c.lastSeen > t) ? c.lastSeen : t), null);
256
+ const recent = clients.filter((c) => c.lastSeen && Date.parse(c.lastSeen) >= activeSince);
257
+ const hasWeeks = Object.keys(weeks).length > 0; // usage files before 3.4.15 have none
258
+
259
+ const r = {
260
+ ...(item.kind === 'schema-field' ? { operations: ops.length } : {}),
261
+ basis: exact ? (byParam ? 'query-parameter' : 'operation') : 'endpoint',
262
+ calls,
263
+ lastSeen,
264
+ clients,
265
+ weeks: hasWeeks ? weekSeries(weeks, meta.window) : [],
266
+ };
267
+
268
+ if (blocker !== null) return { ...r, status: 'no-data', reason: blocker };
269
+ if (recent.length > 0) {
270
+ if (exact) {
271
+ return { ...r, status: 'in-use', reason: `${plural(recent.length, 'client')} called it in the last ${Math.min(ACTIVE_DAYS, quietDays)} days` };
272
+ }
273
+ return {
274
+ ...r, status: 'unverifiable',
275
+ reason: `access logs don't show ${item.kind === 'parameter' ? `the ${item.in} parameter` : 'body fields'}, ` +
276
+ `and ${plural(recent.length, 'client')} still ${recent.length === 1 ? 'calls' : 'call'} ` +
277
+ (item.kind === 'schema-field' ? `operations that use it (${ops.length})` : 'the endpoint'),
278
+ };
279
+ }
280
+ const quietFor = lastSeen ? (to - Date.parse(lastSeen)) / DAY : meta.days;
281
+ if (quietFor >= quietDays) {
282
+ return { ...r, status: 'safe-to-remove', quietForDays: Math.floor(quietFor), reason: lastSeen
283
+ ? `last called ${Math.floor(quietFor)} days before the newest log line`
284
+ : `never called in ${Math.floor(quietFor)} days of logs` };
285
+ }
286
+ return {
287
+ ...r, status: 'quiet', quietForDays: Math.floor(quietFor),
288
+ reason: `no calls for ${Math.floor(quietFor)} of the ${quietDays} days needed`,
289
+ };
290
+ }
291
+
292
+ /**
293
+ * Calls per week across the whole usage window, zero-filled so a week with no
294
+ * calls shows as a drop instead of vanishing. The first and last week are
295
+ * marked partial when the logs cover only part of them.
296
+ */
297
+ function weekSeries(weeks, window) {
298
+ if (!window || !window.from || !window.to) return [];
299
+ const from = Date.parse(window.from);
300
+ const to = Date.parse(window.to);
301
+ const out = [];
302
+ for (let t = Date.parse(weekOf(from)); t <= to; t += 7 * DAY) {
303
+ const week = new Date(t).toISOString().slice(0, 10);
304
+ const entry = { week, calls: weeks[week] || 0 };
305
+ if (t < from || t + 7 * DAY - 1 > to) entry.partial = true;
306
+ out.push(entry);
307
+ }
308
+ return out.slice(-26);
309
+ }
310
+
311
+ // ─── compare integration ────────────────────────────────────────────────────
312
+
313
+ const REMOVAL_TYPES = new Set([
314
+ 'ENDPOINT_REMOVED', 'METHOD_REMOVED', 'PARAMETER_REMOVED', 'REQUEST_FIELD_REMOVED', 'RESPONSE_FIELD_REMOVED',
315
+ ]);
316
+
317
+ /**
318
+ * Marks every removal in a compare result with whether the base spec had
319
+ * deprecated it first: `deprecation: { deprecated, sunset?, drained? }`. A
320
+ * removal that skipped deprecation gave its callers no warning.
321
+ *
322
+ * Deprecation is the gate's other half: a deprecated item whose callers all
323
+ * stopped at least `quietDays` before the newest log line has drained, and
324
+ * stops failing the build like an unused change — the same verdict
325
+ * `specshield deprecations` gives it.
326
+ */
327
+ function annotateDeprecations(result, baseSpec, { meta = null, quietDays = 30 } = {}) {
328
+ const byKey = new Map(collectDeprecations(baseSpec).map((i) => [i.key, i]));
329
+ const to = meta && meta.window && meta.window.to ? Date.parse(meta.window.to) : null;
330
+ const annotate = (c) => {
331
+ if (!REMOVAL_TYPES.has(c.type)) return c;
332
+ const item = deprecationFor(c, byKey);
333
+ if (!item) return { ...c, deprecation: { deprecated: false } };
334
+ const deprecation = { deprecated: true, sunset: item.sunset || null };
335
+ if (c.impact && c.impact.verdict === 'used' && c.impact.lastSeen && to !== null) {
336
+ const quietFor = Math.floor((to - Date.parse(c.impact.lastSeen)) / DAY);
337
+ if (quietFor >= quietDays) Object.assign(deprecation, { drained: true, quietForDays: quietFor });
338
+ }
339
+ return { ...c, deprecation };
340
+ };
341
+ let breakingChanges = result.breakingChanges.map(annotate);
342
+ let unusedBreakingChanges = (result.unusedBreakingChanges || []).map(annotate);
343
+ if (meta && meta.downgrade && meta.downgrade.enabled) {
344
+ const drained = (c) => Boolean(c.deprecation && c.deprecation.drained);
345
+ unusedBreakingChanges = [...unusedBreakingChanges, ...breakingChanges.filter(drained)];
346
+ breakingChanges = breakingChanges.filter((c) => !drained(c));
347
+ }
348
+ return { ...result, breakingChanges, unusedBreakingChanges };
349
+ }
350
+
351
+ function deprecationFor(change, byKey) {
352
+ const endpoints = change.path && change.method
353
+ ? [`${change.method.toUpperCase()} ${change.path}`]
354
+ : (change.affectedEndpoints || []).map((e) => e.replace(/^(\S+)/, (m) => m.toUpperCase()));
355
+ if (endpoints.length === 0) return null;
356
+ const leaf = change.field ? change.field.split('.').pop() : null;
357
+ const found = endpoints.map((ep) => {
358
+ // The whole operation was deprecated: everything in it went with it.
359
+ if (byKey.has(ep)) return byKey.get(ep);
360
+ if (!change.field) return null;
361
+ if (byKey.has(`${ep} ${change.field}`)) return byKey.get(`${ep} ${change.field}`);
362
+ // A merged $ref change carries the first endpoint's field path; elsewhere
363
+ // the same property sits under another prefix. Match it by its leaf name.
364
+ for (const [key, item] of byKey) {
365
+ if (key.startsWith(`${ep} `) && item.field && item.field.split('.').pop() === leaf &&
366
+ item.field.startsWith(change.field.startsWith('requestBody') ? 'requestBody' : 'responses')) return item;
367
+ }
368
+ return null;
369
+ });
370
+ // Only "deprecated" if it was deprecated everywhere it was removed from.
371
+ return found.every(Boolean) ? found[0] : null;
372
+ }
373
+
374
+ // ─── spec helpers ───────────────────────────────────────────────────────────
375
+
376
+ function isDeprecated(node) {
377
+ return Boolean(node && typeof node === 'object' && (node.deprecated === true || node['x-sunset']));
378
+ }
379
+
380
+ /** `x-sunset: 2026-12-31` — YAML parses an unquoted date to a Date. */
381
+ function sunsetOf(node) {
382
+ const v = node && node['x-sunset'];
383
+ if (!v) return null;
384
+ const d = v instanceof Date ? v : new Date(String(v));
385
+ return Number.isNaN(d.getTime()) ? String(v) : d.toISOString().slice(0, 10);
386
+ }
387
+
388
+ function schemaName(ref) {
389
+ return typeof ref === 'string' ? ref.slice(ref.lastIndexOf('/') + 1) : null;
390
+ }
391
+
392
+ function deref(node, table, ...prefixes) {
393
+ if (!node || typeof node !== 'object' || !node.$ref) return node || null;
394
+ for (const prefix of prefixes) {
395
+ if (node.$ref.startsWith(prefix)) return table[node.$ref.slice(prefix.length)] || null;
396
+ }
397
+ return null;
398
+ }
399
+
400
+ function mergeParameters(pathParams, opParams, ctx) {
401
+ const byKey = new Map();
402
+ for (const raw of [...(Array.isArray(pathParams) ? pathParams : []), ...(Array.isArray(opParams) ? opParams : [])]) {
403
+ const p = deref(raw, ctx.parameters, '#/components/parameters/', '#/parameters/');
404
+ if (p && p.name && p.in) byKey.set(`${p.in}:${p.name}`, p);
405
+ }
406
+ return [...byKey.values()];
407
+ }
408
+
409
+ function paramSchema(p, ctx) {
410
+ if (p.schema) return resolveSchema(p.schema, ctx.schemas);
411
+ return p.type ? { type: p.type } : null;
412
+ }
413
+
414
+ function mediaSchema(content) {
415
+ const media = content['application/json'] || Object.values(content)[0];
416
+ return (media && media.schema) || null;
417
+ }
418
+
419
+ /**
420
+ * usage.contacts: { "<client id, or * glob>": "<email, Slack channel, …>" } —
421
+ * first match wins. Unlike --usage-ignore-client, a pattern without * must
422
+ * match the whole id: "app" must not hand myapp's callers to app's owner.
423
+ */
424
+ function compileContacts(contacts) {
425
+ const entries = Object.entries(contacts || {}).map(([pattern, contact]) => [
426
+ pattern.includes('*') ? compileClientPatterns([pattern]) : (id) => id.toLowerCase() === pattern.toLowerCase(),
427
+ String(contact),
428
+ ]);
429
+ return (id) => {
430
+ for (const [test, contact] of entries) if (test(id)) return contact;
431
+ return null;
432
+ };
433
+ }
434
+
435
+ function plural(n, word) { return `${n} ${word}${n === 1 ? '' : 's'}`; }
436
+ function camel(s) { return s.replace(/-(\w)/g, (_, c) => c.toUpperCase()); }
437
+
438
+ module.exports = { collectDeprecations, groupDeprecations, deprecationReport, annotateDeprecations, STATUS_ORDER };
@@ -42,10 +42,38 @@ function applyUsageImpact(result, opts) {
42
42
  downgrade = true, now = Date.now(),
43
43
  } = opts;
44
44
 
45
+ const { opIndex, meta } = indexUsage(usage, baseSpec, { file, ignoreClients, now });
46
+
47
+ const blocker = downgradeBlocker(meta, { downgrade, minDays, maxAgeDays, minCoverage });
48
+ meta.downgrade = { enabled: blocker === null, reason: blocker };
49
+
50
+ const ctx = { opIndex, baseSpec, baseNorm, trusted: meta.trusted };
51
+ const annotate = (c) => (meta.trusted ? { ...c, impact: computeImpact(c, ctx) } : c);
52
+
53
+ let breakingChanges = result.breakingChanges.map(annotate);
54
+ const warnings = result.warnings.map(annotate);
55
+ let unusedBreakingChanges = [];
56
+
57
+ if (meta.downgrade.enabled) {
58
+ unusedBreakingChanges = breakingChanges.filter((c) => c.impact && c.impact.verdict === 'unused');
59
+ breakingChanges = breakingChanges.filter((c) => !(c.impact && c.impact.verdict === 'unused'));
60
+ }
61
+
62
+ return {
63
+ result: { ...result, breakingChanges, warnings, unusedBreakingChanges },
64
+ meta,
65
+ };
66
+ }
67
+
68
+ /**
69
+ * Maps a usage file onto the operations of `spec`:
70
+ * opIndex "GET /orders/{id}" → Map(clientId → { calls, lastSeen, params, paramsLastSeen, weeks, paramsTruncated })
71
+ * meta window, totals, coverage — the evidence the downgrade guards judge
72
+ */
73
+ function indexUsage(usage, spec, { file = 'usage.json', ignoreClients = [], now = Date.now() } = {}) {
45
74
  const ignore = compileClientPatterns(ignoreClients);
46
- const matcher = createRouteMatcher(baseSpec, { basePath: usage.basePath });
75
+ const matcher = createRouteMatcher(spec, { basePath: usage.basePath });
47
76
 
48
- // "GET /orders/{id}" → Map(clientId → { calls, lastSeen, params, paramsTruncated })
49
77
  const opIndex = new Map();
50
78
  let totalCalls = 0;
51
79
  let matchedCalls = 0;
@@ -63,11 +91,17 @@ function applyUsageImpact(result, opts) {
63
91
  const key = `${m.method} ${m.template}`;
64
92
  if (!opIndex.has(key)) opIndex.set(key, new Map());
65
93
  const byClient = opIndex.get(key);
66
- const agg = byClient.get(c.id) || { calls: 0, lastSeen: null, params: {}, paramsTruncated: false };
94
+ const agg = byClient.get(c.id) ||
95
+ { calls: 0, lastSeen: null, params: {}, paramsLastSeen: {}, weeks: {}, paramsTruncated: false };
67
96
  agg.calls += c.calls;
68
97
  const seen = toMs(c.lastSeen);
69
98
  if (seen !== null && (agg.lastSeen === null || seen > agg.lastSeen)) agg.lastSeen = seen;
70
99
  for (const [name, n] of Object.entries(c.params || {})) agg.params[name] = (agg.params[name] || 0) + n;
100
+ for (const [name, t] of Object.entries(c.paramsLastSeen || {})) {
101
+ const ms = toMs(t);
102
+ if (ms !== null && !(agg.paramsLastSeen[name] >= ms)) agg.paramsLastSeen[name] = ms;
103
+ }
104
+ for (const [week, n] of Object.entries(c.weeks || {})) agg.weeks[week] = (agg.weeks[week] || 0) + n;
71
105
  if (c.paramsTruncated) agg.paramsTruncated = true;
72
106
  byClient.set(c.id, agg);
73
107
  }
@@ -93,26 +127,7 @@ function applyUsageImpact(result, opts) {
93
127
  operationsTotal: matcher.operations.length,
94
128
  trusted: matchedCalls > 0,
95
129
  };
96
-
97
- const blocker = downgradeBlocker(meta, { downgrade, minDays, maxAgeDays, minCoverage });
98
- meta.downgrade = { enabled: blocker === null, reason: blocker };
99
-
100
- const ctx = { opIndex, baseSpec, baseNorm, trusted: meta.trusted };
101
- const annotate = (c) => (meta.trusted ? { ...c, impact: computeImpact(c, ctx) } : c);
102
-
103
- let breakingChanges = result.breakingChanges.map(annotate);
104
- const warnings = result.warnings.map(annotate);
105
- let unusedBreakingChanges = [];
106
-
107
- if (meta.downgrade.enabled) {
108
- unusedBreakingChanges = breakingChanges.filter((c) => c.impact && c.impact.verdict === 'unused');
109
- breakingChanges = breakingChanges.filter((c) => !(c.impact && c.impact.verdict === 'unused'));
110
- }
111
-
112
- return {
113
- result: { ...result, breakingChanges, warnings, unusedBreakingChanges },
114
- meta,
115
- };
130
+ return { opIndex, meta, matcher };
116
131
  }
117
132
 
118
133
  /** Why "zero calls" isn't strong enough evidence to stop failing the build — or null. */
@@ -256,4 +271,7 @@ function compileClientPatterns(patterns) {
256
271
  function round1(n) { return Math.round(n * 10) / 10; }
257
272
  function round3(n) { return Math.round(n * 1000) / 1000; }
258
273
 
259
- module.exports = { applyUsageImpact, compileClientPatterns };
274
+ module.exports = {
275
+ applyUsageImpact, indexUsage, downgradeBlocker, endpointsOf, isObjectSchema, compileClientPatterns,
276
+ REQUEST_BODY_TYPES, BODYLESS_METHODS,
277
+ };
@@ -9,7 +9,8 @@ const { clientIdOf } = require('./clientIdentity');
9
9
  * Aggregates request records into the usage summary written to usage.json.
10
10
  *
11
11
  * Only aggregates are kept: per (method, path template, client) a call count,
12
- * first/last seen, and how often each query-parameter NAME was sent. Concrete
12
+ * first/last seen, calls per week, and how often (and how recently) each
13
+ * query-parameter NAME was sent. Concrete
13
14
  * paths (which carry IDs), query values, IPs and bodies are never stored — the
14
15
  * file is safe to commit or upload.
15
16
  */
@@ -19,6 +20,7 @@ const VERSION = 1;
19
20
  const MAX_ENDPOINTS = 5000;
20
21
  const MAX_UNMATCHED = 500;
21
22
  const MAX_PARAMS = 50;
23
+ const MAX_WEEKS = 26;
22
24
 
23
25
  class UsageAggregator {
24
26
  /**
@@ -87,7 +89,7 @@ class UsageAggregator {
87
89
  const clientId = clientIdOf(record, this.clientSpec);
88
90
  let c = ep.clients.get(clientId);
89
91
  if (!c) {
90
- c = { calls: 0, firstSeen: null, lastSeen: null, params: new Map(), paramsTruncated: false };
92
+ c = newClient();
91
93
  ep.clients.set(clientId, c);
92
94
  }
93
95
  c.calls++;
@@ -96,11 +98,14 @@ class UsageAggregator {
96
98
  if (c.lastSeen === null || record.time > c.lastSeen) c.lastSeen = record.time;
97
99
  if (this.from === null || record.time < this.from) this.from = record.time;
98
100
  if (this.to === null || record.time > this.to) this.to = record.time;
101
+ const week = weekOf(record.time);
102
+ c.weeks.set(week, (c.weeks.get(week) || 0) + 1);
99
103
  }
100
104
  for (const name of queryParamNames(record.query)) {
101
105
  if (c.params.has(name)) c.params.set(name, c.params.get(name) + 1);
102
106
  else if (c.params.size < MAX_PARAMS) c.params.set(name, 1);
103
- else c.paramsTruncated = true;
107
+ else { c.paramsTruncated = true; continue; }
108
+ if (record.time !== null) c.paramsLastSeen.set(name, maxTime(c.paramsLastSeen.get(name) ?? null, record.time));
104
109
  }
105
110
 
106
111
  this.stats.requests++;
@@ -121,7 +126,7 @@ class UsageAggregator {
121
126
  for (const ec of e.clients) {
122
127
  let c = ep.clients.get(ec.id);
123
128
  if (!c) {
124
- c = { calls: 0, firstSeen: null, lastSeen: null, params: new Map(), paramsTruncated: false };
129
+ c = newClient();
125
130
  ep.clients.set(ec.id, c);
126
131
  }
127
132
  c.calls += ec.calls;
@@ -132,6 +137,10 @@ class UsageAggregator {
132
137
  else if (c.params.size < MAX_PARAMS) c.params.set(name, n);
133
138
  else c.paramsTruncated = true;
134
139
  }
140
+ for (const [name, t] of Object.entries(ec.paramsLastSeen || {})) {
141
+ if (c.params.has(name)) c.paramsLastSeen.set(name, maxTime(c.paramsLastSeen.get(name) ?? null, toMs(t)));
142
+ }
143
+ for (const [week, n] of Object.entries(ec.weeks || {})) c.weeks.set(week, (c.weeks.get(week) || 0) + n);
135
144
  if (ec.paramsTruncated) c.paramsTruncated = true;
136
145
  }
137
146
  }
@@ -146,7 +155,11 @@ class UsageAggregator {
146
155
  .map(([id, c]) => {
147
156
  const out = { id, calls: c.calls, firstSeen: toIso(c.firstSeen), lastSeen: toIso(c.lastSeen) };
148
157
  if (c.params.size > 0) out.params = Object.fromEntries([...c.params.entries()].sort((a, b) => b[1] - a[1]));
158
+ if (c.paramsLastSeen.size > 0) {
159
+ out.paramsLastSeen = Object.fromEntries([...c.paramsLastSeen.entries()].map(([n, t]) => [n, toIso(t)]));
160
+ }
149
161
  if (c.paramsTruncated) out.paramsTruncated = true;
162
+ if (c.weeks.size > 0) out.weeks = Object.fromEntries([...c.weeks.entries()].sort().slice(-MAX_WEEKS));
150
163
  return out;
151
164
  })
152
165
  .sort((a, b) => b.calls - a.calls || a.id.localeCompare(b.id));
@@ -171,6 +184,20 @@ class UsageAggregator {
171
184
  }
172
185
  }
173
186
 
187
+ function newClient() {
188
+ return {
189
+ calls: 0, firstSeen: null, lastSeen: null,
190
+ params: new Map(), paramsLastSeen: new Map(), paramsTruncated: false, weeks: new Map(),
191
+ };
192
+ }
193
+
194
+ /** The Monday (UTC) starting the week of `ms`, as "YYYY-MM-DD" — the key of usage.json `weeks`. */
195
+ function weekOf(ms) {
196
+ const d = new Date(ms);
197
+ const monday = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()) - ((d.getUTCDay() + 6) % 7) * 86400e3;
198
+ return new Date(monday).toISOString().slice(0, 10);
199
+ }
200
+
174
201
  /** --host values: exact host names, or globs like "*.example.com". Null = no filter. */
175
202
  function compileHostFilter(hosts) {
176
203
  const list = (hosts || []).filter(Boolean).map((h) => String(h).toLowerCase());
@@ -232,4 +259,4 @@ function toIso(ms) { return ms === null || ms === undefined ? null : new Date(ms
232
259
  function minTime(a, b) { return a === null ? b : b === null ? a : Math.min(a, b); }
233
260
  function maxTime(a, b) { return a === null ? b : b === null ? a : Math.max(a, b); }
234
261
 
235
- module.exports = { UsageAggregator, loadUsage, validateUsage, parseDuration, toMs, FORMAT, VERSION };
262
+ module.exports = { UsageAggregator, loadUsage, validateUsage, parseDuration, toMs, weekOf, FORMAT, VERSION };