specshield 3.4.11 → 3.4.12

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,5 +1,23 @@
1
1
  # SpecShield CLI changelog
2
2
 
3
+ ## Unreleased — usage-aware compare: "who does this change break?"
4
+
5
+ ### Added
6
+
7
+ - **`specshield usage import <logs...>`** — aggregates access logs (nginx/Apache combined
8
+ & common, AWS ALB, JSON lines; `.gz` and stdin) into `usage.json`: per endpoint × client
9
+ call counts, query-parameter names, first/last seen. Runs locally; stores no concrete
10
+ IDs, query values, IPs or bodies. `--spec`, `--base-path`, `--client ua|field:|extra:`
11
+ (with `hash:`), `--since`, `--append` (duplicate files skipped), `--format`.
12
+ - **`specshield usage show [file] [--spec]`** — top endpoints and clients; with `--spec`,
13
+ operations never called in the window and calls the spec doesn't document.
14
+ - **`compare --usage <file>`** — annotates breaking changes and warnings with the clients
15
+ that exercise them (exact for query parameters). Breaking changes with zero calls move to
16
+ `unusedBreakingChanges` and don't fail `--fail-on-breaking`, only when the usage covers
17
+ ≥ `--usage-min-days` (default 7), is ≤ 30 days old and matches the base spec.
18
+ Also `--usage-ignore-client`, `--no-usage-downgrade`, and a `usage:` block in
19
+ `.specshield.yml`. JSON output is unchanged unless `--usage` is given.
20
+
3
21
  ## 3.4.0 — 2026-07-29 — `govern` command (API governance in the CLI)
4
22
 
5
23
  ### Added
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) · [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) · [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)
@@ -250,6 +250,75 @@ specshield compare base.yaml target.yaml --output result.json
250
250
  specshield compare base.yaml target.yaml --ignore "DELETE /admin removed" --fail-on-breaking
251
251
  ```
252
252
 
253
+ ## Who does a change break? — usage-aware compare
254
+
255
+ A spec diff tells you **what** changed. Your access logs know **who** still calls it.
256
+ `specshield usage` joins the two, so every breaking change shows the clients it would
257
+ break — and a removal that nobody calls stops failing the build.
258
+
259
+ ```text
260
+ ✖ BREAKING CHANGES
261
+ ● DELETE /orders/{orderId}/receipt method was removed
262
+ ↳ impact: 1 client · 134 calls · last seen 72 min ago
263
+ MyShop-iOS/5.2 100% of calls 134 · last seen 72 min ago
264
+ ● Parameter "expand" (query) was removed from GET /orders
265
+ ↳ impact: 1 client · 200 calls sending "expand" · last seen 2 h ago
266
+ okhttp/4.12 33% of calls 200 · last seen 2 h ago
267
+
268
+ ✔ BREAKING BUT UNUSED — safe to ship
269
+ 0 calls between 2026-10-05 and 2026-10-25; these do not fail the build
270
+ ○ GET /legacy-report was removed
271
+ ```
272
+
273
+ **1. Turn access logs into a usage summary** (runs locally — raw logs never leave the machine):
274
+
275
+ ```bash
276
+ specshield usage import /var/log/nginx/access.log* --spec api/openapi.yaml
277
+ # → usage.json: per endpoint × client, call counts, query-parameter names, first/last seen
278
+ ```
279
+
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`.
283
+ - **Clients** are identified by User-Agent by default (`MyShop-iOS/5.2.1` → `MyShop-iOS/5.2`).
284
+ Use a better signal if you log one: `--client field:consumer.username` (JSON logs),
285
+ `--client extra:1` (first quoted field after the User-Agent in combined logs), and prefix
286
+ `hash:` for API keys — `--client hash:extra:1` stores a one-way hash, never the key.
287
+ - **Privacy:** only aggregates are stored — path templates, counts, timestamps, and query
288
+ parameter *names*. No IDs from concrete paths, no query values, no IPs, no bodies.
289
+ - `--spec` maps `/v1/orders/123` onto `/orders/{orderId}` exactly as your spec defines it
290
+ (base paths from `servers` / `basePath`, or `--base-path`). Without it, IDs are guessed.
291
+ - Add more days later with `--append` (a file imported twice is detected and skipped);
292
+ limit the window with `--since 30d`.
293
+
294
+ **2. Compare with impact:**
295
+
296
+ ```bash
297
+ specshield compare base.yaml target.yaml --usage usage.json --fail-on-breaking
298
+ ```
299
+
300
+ - **Endpoint and method removals, body/response field changes** → the clients calling that
301
+ operation. Access logs don't show which response fields a client reads, so for field
302
+ changes this is "clients that may be affected", and the report says so.
303
+ - **Query parameters** are judged exactly: a removed parameter affects only clients that
304
+ *send* it; a parameter that became required affects only clients that *omit* it.
305
+ - **Zero calls → "breaking but unused"**: listed separately and excluded from
306
+ `--fail-on-breaking`. SpecShield only does this when the evidence is good enough — at
307
+ least `--usage-min-days` (default 7) of logs, the newest no older than 30 days, and calls
308
+ that actually match the base spec. Otherwise the change stays breaking and the report
309
+ says why. `--no-usage-downgrade` keeps everything breaking and only annotates.
310
+ - Leave health checks and bots out: `--usage-ignore-client 'kube-probe/*' --usage-ignore-client healthcheck`.
311
+ - `--json` adds `impact` to each change, plus `unusedBreakingChanges`, `summary.unusedBreaking`
312
+ and a `usage` block. Without `--usage` the JSON is unchanged.
313
+
314
+ **3. Find dead and undocumented endpoints:**
315
+
316
+ ```bash
317
+ specshield usage show usage.json --spec api/openapi.yaml
318
+ # NEVER CALLED IN THIS WINDOW → candidates for deprecation
319
+ # CALLED BUT NOT IN THE SPEC → shadow endpoints your spec is missing
320
+ ```
321
+
253
322
  ## Remote Compare
254
323
 
255
324
  Sends your specs to SpecShield's hosted diff engine. Useful for keeping the
@@ -1201,6 +1270,13 @@ severity: error # info | warning | error
1201
1270
  ignore:
1202
1271
  - "DELETE /admin removed" # match by substring; repeatable
1203
1272
 
1273
+ # Usage-aware compare (same as --usage …; see "Who does a change break?").
1274
+ # usage:
1275
+ # file: usage.json
1276
+ # ignoreClients: ["kube-probe/*"]
1277
+ # minDays: 7
1278
+ # downgrade: true
1279
+
1204
1280
  # Hosted compare (set --remote on the CLI to override).
1205
1281
  remote:
1206
1282
  enabled: false
@@ -1258,6 +1334,10 @@ specshield compare <base> <target> [options]
1258
1334
  | `--severity <level>` | Minimum severity shown: `info` / `warning` / `error` (default `info`) |
1259
1335
  | `--config <path>` | Path to `.specshield.yml` |
1260
1336
  | `--remote-url <url>` | Override the hosted API base URL |
1337
+ | `--usage <file>` | `usage.json` from `specshield usage import` — show which clients each breaking change affects |
1338
+ | `--usage-ignore-client <pattern>` | Leave a client out of the impact (repeatable; `*` globs, otherwise substring) |
1339
+ | `--usage-min-days <n>` | Days of usage needed before an unused breaking change stops failing the build (default `7`) |
1340
+ | `--no-usage-downgrade` | Annotate impact only; keep unused breaking changes breaking |
1261
1341
  | `--timeout <ms>` | Request timeout for remote mode (default `10000`) |
1262
1342
 
1263
1343
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specshield",
3
- "version": "3.4.11",
3
+ "version": "3.4.12",
4
4
  "description": "Contract compatibility testing for APIs — catch breaking OpenAPI changes before they reach your consumers, with can-i-deploy deploy gating and GitHub PR checks. (a.k.a. bidirectional contract testing.)",
5
5
  "main": "src/cli.js",
6
6
  "homepage": "https://specshield.io",
package/src/cli.js CHANGED
@@ -11,6 +11,7 @@ const governCommand = require('./commands/govern');
11
11
  const historyCommand = require('./commands/history');
12
12
  const shareCommand = require('./commands/share');
13
13
  const whoamiCommand = require('./commands/whoami');
14
+ const usageCommand = require('./commands/usage');
14
15
 
15
16
  const program = new Command();
16
17
 
@@ -32,6 +33,7 @@ program.addCommand(governCommand);
32
33
  program.addCommand(historyCommand);
33
34
  program.addCommand(shareCommand);
34
35
  program.addCommand(whoamiCommand);
36
+ program.addCommand(usageCommand);
35
37
 
36
38
  program.parseAsync(process.argv).catch((err) => {
37
39
  const logger = require('./utils/logger');
@@ -43,6 +43,10 @@ compare
43
43
  .option('--api-key <key>', 'API key for hosted mode (overrides env and stored config)')
44
44
  .option('--remote-url <url>', 'Override the hosted API base URL')
45
45
  .option('--timeout <ms>', 'Request timeout for remote mode (ms)', '10000')
46
+ .option('--usage <file>', 'usage.json from "specshield usage import" — show which clients each breaking change affects')
47
+ .option('--usage-ignore-client <pattern>', 'Leave a client out of the impact, e.g. health checks (repeatable; * globs)', collect, [])
48
+ .option('--usage-min-days <n>', 'Days of usage needed before an unused breaking change stops failing the build (default: 7)')
49
+ .option('--no-usage-downgrade', 'Annotate impact only; keep unused breaking changes as breaking')
46
50
  .action(async (base, target, opts) => {
47
51
  try {
48
52
  // Load config
@@ -83,6 +87,13 @@ compare
83
87
  // Apply severity filter
84
88
  result = filterBySeverity(result, options.severity);
85
89
 
90
+ // Join the changes to real traffic. Runs after the ignore list and
91
+ // severity filter so it only annotates what will be reported, and
92
+ // before the exit code so unused breaking changes don't fail the build.
93
+ if (options.usage) {
94
+ result = await applyUsage(result, base, options);
95
+ }
96
+
86
97
  // Output
87
98
  if (options.json) {
88
99
  const jsonOutput = formatJson(result);
@@ -139,6 +150,33 @@ compare
139
150
  }
140
151
  });
141
152
 
153
+ async function applyUsage(result, base, options) {
154
+ const { loadUsage } = require('../core/usage/usageStore');
155
+ const { applyUsageImpact } = require('../core/usage/impact');
156
+
157
+ const usage = await loadUsage(options.usage);
158
+ const baseSpec = parseSpec(await loadSpec(base), base);
159
+ const minDays = Number(options.usageMinDays);
160
+ if (!Number.isFinite(minDays) || minDays < 0) {
161
+ throw new Error(`--usage-min-days must be a number ≥ 0, got "${options.usageMinDays}"`);
162
+ }
163
+
164
+ const { result: annotated, meta } = applyUsageImpact(result, {
165
+ usage,
166
+ baseSpec,
167
+ baseNorm: normalizeSpec(baseSpec),
168
+ file: path.basename(options.usage),
169
+ ignoreClients: options.usageIgnoreClient,
170
+ minDays,
171
+ downgrade: options.usageDowngrade,
172
+ });
173
+ if (!meta.trusted && meta.totalCalls > 0) {
174
+ logger.warn(`None of the calls in ${options.usage} match an operation in ${base}. ` +
175
+ 'Is it the right usage file? If the API is served under a prefix, re-import with --base-path.');
176
+ }
177
+ return { ...annotated, usage: meta };
178
+ }
179
+
142
180
  async function runLocalComparison(base, target, options, spinner) {
143
181
  if (spinner) spinner.text = 'Loading base spec...';
144
182
  const baseRaw = await loadSpec(base);
@@ -257,6 +295,17 @@ function mergeOptions(config, cliOpts) {
257
295
  remote: cliOpts.remote || (config.remote && config.remote.enabled) || false,
258
296
  remoteUrl: cliOpts.remoteUrl || null,
259
297
  timeout: cliOpts.timeout || (config.remote && config.remote.timeout) || 10000,
298
+ usage: cliOpts.usage || (config.usage && config.usage.file) || null,
299
+ usageIgnoreClient: [
300
+ ...(cliOpts.usageIgnoreClient || []),
301
+ ...((config.usage && config.usage.ignoreClients) || []),
302
+ ],
303
+ usageMinDays: cliOpts.usageMinDays !== undefined
304
+ ? cliOpts.usageMinDays
305
+ : config.usage && config.usage.minDays !== undefined ? config.usage.minDays : 7,
306
+ usageDowngrade: cliOpts.usageDowngrade === false
307
+ ? false
308
+ : !(config.usage && config.usage.downgrade === false),
260
309
  };
261
310
  }
262
311
 
@@ -0,0 +1,223 @@
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 { createRouteMatcher } = require('../core/usage/routeMatcher');
9
+ const { parseClientSpec } = require('../core/usage/clientIdentity');
10
+ const { UsageAggregator, loadUsage, parseDuration } = require('../core/usage/usageStore');
11
+ const { importLogFile, fingerprintFile } = require('../core/usage/importLogs');
12
+ const { fmt, plural, pct, day, spanDays, ago } = require('../core/usage/format');
13
+ const logger = require('../utils/logger');
14
+ const exitAfterFlush = require('../utils/exitAfterFlush');
15
+ const { version } = require('../../package.json');
16
+
17
+ const usage = new Command('usage')
18
+ .description('Learn who calls which endpoint from access logs, so compare can say who a change breaks');
19
+
20
+ // ─── usage import ───────────────────────────────────────────────────────────
21
+
22
+ usage
23
+ .command('import')
24
+ .description('Aggregate access logs into usage.json (raw logs never leave this machine)')
25
+ .argument('<logs...>', 'Access log files (.gz ok), or - for stdin')
26
+ .option('--out <file>', 'Where to write the usage summary', 'usage.json')
27
+ .option('--spec <file>', 'OpenAPI spec to map request paths onto its path templates (recommended)')
28
+ .option('--format <format>', 'Log format: auto | combined | alb | json', 'auto')
29
+ .option('--client <source>', 'How to identify clients: ua | field:<path> | extra:<n>, optionally hash:-prefixed', 'ua')
30
+ .option('--base-path <path>', 'Path prefix the API is served under, e.g. /api/v1 (default: from the spec servers)')
31
+ .option('--since <duration>', 'Only count requests newer than this, e.g. 30d')
32
+ .option('--append', 'Add to an existing --out file instead of replacing it')
33
+ .action(async (logs, opts) => {
34
+ try {
35
+ const clientSpec = parseClientSpec(opts.client);
36
+ const sinceMs = opts.since ? Date.now() - parseDuration(opts.since) : null;
37
+
38
+ let spec = null;
39
+ let matcher = null;
40
+ if (opts.spec) {
41
+ spec = parseSpec(await loadSpec(opts.spec), opts.spec);
42
+ matcher = createRouteMatcher(spec, { basePath: opts.basePath });
43
+ }
44
+
45
+ let existing = null;
46
+ if (opts.append && await fsExtra.pathExists(opts.out)) {
47
+ existing = await loadUsage(opts.out);
48
+ if (existing.client !== clientSpec.spec) {
49
+ throw new Error(`${opts.out} identifies clients by "${existing.client}", not "${clientSpec.spec}". Use the same --client to append.`);
50
+ }
51
+ }
52
+
53
+ const aggregator = new UsageAggregator({ clientSpec, matcher, sinceMs });
54
+ const sources = existing ? [...(existing.sources || [])] : [];
55
+ const seen = new Set(sources.map((s) => s.fingerprint).filter(Boolean));
56
+ const imported = [];
57
+
58
+ for (const file of logs) {
59
+ if (file !== '-') {
60
+ const fp = await fingerprintFile(file).catch(() => null);
61
+ if (fp && seen.has(fp)) {
62
+ logger.warn(`Skipping ${file} — already imported into ${opts.out}`);
63
+ continue;
64
+ }
65
+ }
66
+ const r = await importLogFile(file, { format: opts.format, aggregator });
67
+ if (r.fingerprint) seen.add(r.fingerprint);
68
+ imported.push(r);
69
+ sources.push({ file: r.file, format: r.format, lines: r.lines, parsed: r.parsed, fingerprint: r.fingerprint });
70
+ if (r.parsed === 0 && r.lines > 0) logger.warn(`${file}: no request lines recognised as ${r.format}`);
71
+ }
72
+
73
+ if (aggregator.stats.requests === 0 && !existing) {
74
+ throw new Error('No requests were counted. Check the log format (--format), --since, and that the files are access logs.');
75
+ }
76
+ const runStats = { ...aggregator.stats };
77
+ if (existing) aggregator.absorb(existing);
78
+
79
+ const out = aggregator.toJSON({
80
+ generator: `specshield-cli ${version}`,
81
+ client: clientSpec.spec,
82
+ spec: spec ? { title: (spec.info && spec.info.title) || null, version: (spec.info && spec.info.version) || null } : null,
83
+ basePath: opts.basePath || (existing && existing.basePath) || null,
84
+ sources,
85
+ });
86
+ await fsExtra.outputFile(opts.out, JSON.stringify(out, null, 2) + '\n');
87
+
88
+ printImportSummary(out, imported, runStats, { outFile: opts.out, matcher, appended: !!existing });
89
+ exitAfterFlush(0);
90
+ } catch (err) {
91
+ logger.error(`Error: ${err.message}`);
92
+ process.exit(2);
93
+ }
94
+ });
95
+
96
+ function printImportSummary(out, imported, run, { outFile, matcher, appended }) {
97
+ const lines = [];
98
+ const parsed = imported.reduce((n, r) => n + r.parsed, 0);
99
+ const skipped = imported.reduce((n, r) => n + r.skipped, 0);
100
+ const formats = [...new Set(imported.map((r) => r.format).filter(Boolean))].join(', ') || '—';
101
+ const clients = new Set(out.endpoints.flatMap((e) => e.clients.map((c) => c.id)));
102
+
103
+ if (imported.length === 0) {
104
+ process.stdout.write(chalk.gray(` Nothing new to import — ${outFile} is unchanged.`) + '\n');
105
+ return;
106
+ }
107
+ lines.push(chalk.green(`✔ ${appended ? 'Updated' : 'Wrote'} ${outFile}`));
108
+ lines.push(` ${plural(parsed, 'request')} from ${plural(imported.length, 'file')} (${formats})` +
109
+ (out.window.from ? ` · ${day(out.window.from)} → ${day(out.window.to)} (${spanDays(out.window)} days)` : ''));
110
+ lines.push(` ${plural(out.endpoints.length, 'endpoint')} · ${plural(clients.size, 'client')}` +
111
+ (matcher ? ` · ${fmt(run.matched)} matched the spec · ${fmt(run.unmatched)} not in the spec` : ''));
112
+ if (run.notFound) lines.push(chalk.gray(` ${plural(run.notFound, 'request')} to unknown paths answered 404/405 skipped (scanners)`));
113
+ if (run.tooOld) lines.push(chalk.gray(` ${plural(run.tooOld, 'request')} older than --since skipped`));
114
+ if (run.overflow) lines.push(chalk.yellow(` ${plural(run.overflow, 'request')} dropped: endpoint limit reached (use --spec to group paths)`));
115
+ if (skipped) lines.push(chalk.gray(` ${plural(skipped, 'line')} skipped (not a request)`));
116
+
117
+ if (clients.size === 1 && clients.has('unknown')) {
118
+ lines.push(chalk.yellow(' Every request has client "unknown" — the logs carry no User-Agent. Pick another signal with --client.'));
119
+ }
120
+ if (matcher && run.requests > 0 && run.matched / run.requests < 0.5) {
121
+ lines.push(chalk.yellow(` Only ${pct(run.matched / run.requests)} of requests matched the spec.` +
122
+ (matcher.basePaths.length ? '' : ' If the API is served under a prefix, pass --base-path (e.g. --base-path /api).')));
123
+ }
124
+ if (!matcher) {
125
+ lines.push(chalk.gray(' Tip: pass --spec openapi.yaml to group paths exactly as the spec defines them.'));
126
+ }
127
+ lines.push('');
128
+ lines.push(` Next: ${chalk.cyan(`specshield compare base.yaml target.yaml --usage ${outFile}`)}`);
129
+ process.stdout.write(lines.join('\n') + '\n');
130
+ }
131
+
132
+ // ─── usage show ─────────────────────────────────────────────────────────────
133
+
134
+ usage
135
+ .command('show')
136
+ .description('Summarise a usage file; with --spec, list endpoints nobody calls and calls the spec does not document')
137
+ .argument('[file]', 'Usage file', 'usage.json')
138
+ .option('--spec <file>', 'OpenAPI spec to check against')
139
+ .option('--top <n>', 'How many endpoints to list', '15')
140
+ .option('--json', 'Output machine-readable JSON')
141
+ .action(async (file, opts) => {
142
+ try {
143
+ const data = await loadUsage(file);
144
+ const top = Math.max(1, parseInt(opts.top, 10) || 15);
145
+ let unused = null;
146
+ let undocumented = null;
147
+
148
+ if (opts.spec) {
149
+ const spec = parseSpec(await loadSpec(opts.spec), opts.spec);
150
+ const matcher = createRouteMatcher(spec, { basePath: data.basePath });
151
+ const called = new Set();
152
+ undocumented = [];
153
+ for (const e of data.endpoints) {
154
+ const m = matcher.match(e.method, e.path);
155
+ if (m && m.operation) called.add(`${m.method} ${m.template}`);
156
+ else undocumented.push({ method: e.method, path: e.path, calls: e.calls, lastSeen: e.lastSeen, clients: e.clients.length });
157
+ }
158
+ unused = matcher.operations
159
+ .filter((o) => !called.has(`${o.method} ${o.template}`))
160
+ .map((o) => ({ method: o.method, path: o.template }));
161
+ }
162
+
163
+ if (opts.json) {
164
+ process.stdout.write(JSON.stringify({
165
+ window: data.window,
166
+ totalCalls: data.endpoints.reduce((n, e) => n + e.calls, 0),
167
+ endpoints: data.endpoints.slice(0, top),
168
+ ...(unused ? { unusedOperations: unused, undocumentedEndpoints: undocumented } : {}),
169
+ }, null, 2) + '\n');
170
+ return exitAfterFlush(0);
171
+ }
172
+
173
+ process.stdout.write(renderShow(data, { top, unused, undocumented }) + '\n');
174
+ exitAfterFlush(0);
175
+ } catch (err) {
176
+ logger.error(`Error: ${err.message}`);
177
+ process.exit(2);
178
+ }
179
+ });
180
+
181
+ function renderShow(data, { top, unused, undocumented }) {
182
+ const lines = [];
183
+ const total = data.endpoints.reduce((n, e) => n + e.calls, 0);
184
+ lines.push('');
185
+ lines.push(chalk.bold(' SpecShield™ API Usage'));
186
+ lines.push(chalk.gray(' ─────────────────────────────────────────'));
187
+ lines.push(` ${plural(total, 'call')} · ${plural(data.endpoints.length, 'endpoint')}` +
188
+ (data.window.from ? ` · ${day(data.window.from)} → ${day(data.window.to)} (${spanDays(data.window)} days)` : '') +
189
+ chalk.gray(` clients by ${data.client}`));
190
+ lines.push('');
191
+
192
+ for (const e of data.endpoints.slice(0, top)) {
193
+ lines.push(` ${chalk.bold(e.method.padEnd(6))} ${e.path} ${chalk.gray(plural(e.calls, 'call'))}`);
194
+ const shown = e.clients.slice(0, 3);
195
+ for (const c of shown) {
196
+ lines.push(chalk.gray(` ${c.id.padEnd(28)} ${pct(c.calls / e.calls).padStart(4)} last seen ${ago(c.lastSeen)}`));
197
+ }
198
+ if (e.clients.length > shown.length) lines.push(chalk.gray(` …and ${e.clients.length - shown.length} more client(s)`));
199
+ }
200
+ if (data.endpoints.length > top) lines.push(chalk.gray(` …${data.endpoints.length - top} more endpoint(s) — raise --top`));
201
+
202
+ if (unused) {
203
+ lines.push('');
204
+ lines.push(chalk.green.bold(` ✔ NEVER CALLED IN THIS WINDOW (${unused.length}) — candidates for deprecation`));
205
+ lines.push(chalk.gray(' ─────────────────────────────────────────'));
206
+ if (unused.length === 0) lines.push(chalk.gray(' Every operation in the spec was called.'));
207
+ for (const o of unused) lines.push(` ${chalk.green('○')} ${o.method} ${o.path}`);
208
+ }
209
+ if (undocumented) {
210
+ lines.push('');
211
+ lines.push(chalk.yellow.bold(` ⚠ CALLED BUT NOT IN THE SPEC (${undocumented.length})`));
212
+ lines.push(chalk.gray(' ─────────────────────────────────────────'));
213
+ if (undocumented.length === 0) lines.push(chalk.gray(' All traffic matches a documented operation.'));
214
+ for (const u of undocumented.slice(0, top)) {
215
+ lines.push(` ${chalk.yellow('!')} ${u.method} ${u.path} ${chalk.gray(`${plural(u.calls, 'call')} · ${plural(u.clients, 'client')}`)}`);
216
+ }
217
+ if (undocumented.length > top) lines.push(chalk.gray(` …${undocumented.length - top} more`));
218
+ }
219
+ lines.push('');
220
+ return lines.join('\n');
221
+ }
222
+
223
+ module.exports = usage;
@@ -105,6 +105,31 @@ function validateConfig(config, filePath) {
105
105
  };
106
106
  }
107
107
 
108
+ if (config.usage !== undefined && config.usage !== null) {
109
+ if (typeof config.usage === 'string') {
110
+ valid.usage = { file: config.usage };
111
+ } else if (typeof config.usage === 'object' && !Array.isArray(config.usage)) {
112
+ const u = config.usage;
113
+ if (u.ignoreClients !== undefined && !Array.isArray(u.ignoreClients)) {
114
+ throw new Error(`Config error in "${filePath}": usage.ignoreClients must be an array`);
115
+ }
116
+ if (u.minDays !== undefined && !(Number(u.minDays) >= 0)) {
117
+ throw new Error(`Config error in "${filePath}": usage.minDays must be a number ≥ 0`);
118
+ }
119
+ if (u.downgrade !== undefined && typeof u.downgrade !== 'boolean') {
120
+ throw new Error(`Config error in "${filePath}": usage.downgrade must be a boolean`);
121
+ }
122
+ valid.usage = {
123
+ file: u.file || null,
124
+ ignoreClients: (u.ignoreClients || []).filter(Boolean).map(String),
125
+ minDays: u.minDays !== undefined ? Number(u.minDays) : undefined,
126
+ downgrade: u.downgrade,
127
+ };
128
+ } else {
129
+ throw new Error(`Config error in "${filePath}": usage must be a file path or an object`);
130
+ }
131
+ }
132
+
108
133
  return valid;
109
134
  }
110
135
 
@@ -1,12 +1,14 @@
1
1
  'use strict';
2
2
 
3
3
  const chalk = require('chalk');
4
+ const { fmt, plural, pct, day, spanDays, ago } = require('./usage/format');
4
5
 
5
6
  function formatHuman(result) {
6
7
  const lines = [];
7
8
  const { breakingChanges, additions, modifications, warnings } = result;
9
+ const unused = result.unusedBreakingChanges || [];
8
10
 
9
- const total = breakingChanges.length + additions.length + modifications.length + warnings.length;
11
+ const total = breakingChanges.length + additions.length + modifications.length + warnings.length + unused.length;
10
12
 
11
13
  if (total === 0) {
12
14
  lines.push(chalk.green('✔ No changes detected between the two specs.'));
@@ -21,8 +23,10 @@ function formatHuman(result) {
21
23
  ` ${chalk.red.bold(`${breakingChanges.length} breaking`)} ` +
22
24
  `${chalk.green(`${additions.length} additions`)} ` +
23
25
  `${chalk.yellow(`${modifications.length} modifications`)} ` +
24
- `${chalk.gray(`${warnings.length} warnings`)}`
26
+ `${chalk.gray(`${warnings.length} warnings`)}` +
27
+ (result.usage ? ` ${chalk.green(`${unused.length} breaking but unused`)}` : '')
25
28
  );
29
+ if (result.usage) lines.push(...formatUsageHeader(result.usage));
26
30
  lines.push('');
27
31
 
28
32
  if (breakingChanges.length > 0) {
@@ -33,6 +37,21 @@ function formatHuman(result) {
33
37
  if (c.oldValue && c.newValue) {
34
38
  lines.push(` ${chalk.gray('from:')} ${chalk.red(c.oldValue)} ${chalk.gray('→')} ${chalk.green(c.newValue)}`);
35
39
  }
40
+ if (c.impact) lines.push(...formatImpact(c, { detailed: true }));
41
+ }
42
+ lines.push('');
43
+ }
44
+
45
+ if (unused.length > 0) {
46
+ const w = result.usage && result.usage.window;
47
+ 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
+ lines.push(chalk.gray(' ─────────────────────────────────────────'));
50
+ for (const c of unused) {
51
+ lines.push(` ${chalk.green('○')} ${c.description}`);
52
+ if (c.impact && c.impact.basis === 'query-parameter') {
53
+ lines.push(chalk.gray(` no client ${c.impact.parameterUse === 'omitted' ? 'omits' : 'sends'} "${c.impact.parameter}"`));
54
+ }
36
55
  }
37
56
  lines.push('');
38
57
  }
@@ -63,6 +82,7 @@ function formatHuman(result) {
63
82
  lines.push(chalk.gray(' ─────────────────────────────────────────'));
64
83
  for (const c of warnings) {
65
84
  lines.push(` ${chalk.gray('!')} ${c.description}`);
85
+ if (c.impact) lines.push(...formatImpact(c, { detailed: false }));
66
86
  }
67
87
  // Whether a constraint change actually breaks depends on which side of the
68
88
  // contract it sits on, which this engine does not track. Say so rather than
@@ -82,8 +102,73 @@ function formatHuman(result) {
82
102
  return lines.join('\n');
83
103
  }
84
104
 
105
+ // ─── Usage impact ───────────────────────────────────────────────────────────
106
+
107
+ const MAX_CLIENTS_SHOWN = 5;
108
+
109
+ function formatUsageHeader(u) {
110
+ const lines = [];
111
+ if (!u.trusted) {
112
+ lines.push(chalk.yellow(` Usage: ${u.file} was not applied — none of its calls match an operation in the base spec.`));
113
+ return lines;
114
+ }
115
+ const span = spanDays(u.window);
116
+ lines.push(chalk.gray(
117
+ ` Usage: ${u.file} · ${u.window.from ? `${day(u.window.from)} → ${day(u.window.to)}` : 'no timestamps'}` +
118
+ (span !== null ? ` (${span} days)` : '') +
119
+ ` · ${plural(u.matchedCalls, 'call')} · ${plural(u.clients, 'client')}` +
120
+ (u.ignoredCalls ? ` · ${fmt(u.ignoredCalls)} ignored` : '')));
121
+ if (!u.downgrade.enabled && u.downgrade.reason !== 'disabled by --no-usage-downgrade') {
122
+ lines.push(chalk.yellow(` Unused breaking changes still fail the build: ${u.downgrade.reason}.`));
123
+ }
124
+ return lines;
125
+ }
126
+
127
+ function formatImpact(c, { detailed }) {
128
+ const i = c.impact;
129
+ const lines = [];
130
+ if (i.verdict === 'unknown') {
131
+ lines.push(chalk.gray(` ↳ impact: unknown — ${i.reason}`));
132
+ return lines;
133
+ }
134
+ if (i.verdict === 'unused') {
135
+ lines.push(chalk.green(` ↳ impact: 0 calls${scope(i)} — nobody would notice this change`));
136
+ return lines;
137
+ }
138
+
139
+ const n = i.clients.length;
140
+ lines.push(chalk.yellow(
141
+ ` ↳ impact: ${plural(n, 'client')} · ${plural(i.calls, 'call')}${scope(i)}` +
142
+ ` · last seen ${ago(i.lastSeen)}`));
143
+ if (detailed) {
144
+ const width = Math.min(32, Math.max(...i.clients.slice(0, MAX_CLIENTS_SHOWN).map((x) => x.id.length)));
145
+ for (const cl of i.clients.slice(0, MAX_CLIENTS_SHOWN)) {
146
+ lines.push(
147
+ ` ${chalk.bold(cl.id.padEnd(width))} ${pct(cl.share).padStart(4)} of calls ` +
148
+ chalk.gray(`${fmt(cl.calls)} · last seen ${ago(cl.lastSeen)}`));
149
+ }
150
+ if (n > MAX_CLIENTS_SHOWN) lines.push(chalk.gray(` …and ${n - MAX_CLIENTS_SHOWN} more`));
151
+ if (i.basis === 'endpoint' && isFieldLevel(c)) {
152
+ lines.push(chalk.gray(' (clients calling this endpoint — access logs do not show which fields they use)'));
153
+ }
154
+ }
155
+ return lines;
156
+ }
157
+
158
+ function scope(i) {
159
+ if (i.basis !== 'query-parameter') return '';
160
+ return i.parameterUse === 'omitted'
161
+ ? ` without "${i.parameter}"`
162
+ : ` sending "${i.parameter}"`;
163
+ }
164
+
165
+ /** Changes below the operation level, where "calls the endpoint" over-approximates "is affected". */
166
+ function isFieldLevel(c) {
167
+ return !['ENDPOINT_REMOVED', 'METHOD_REMOVED'].includes(c.type);
168
+ }
169
+
85
170
  function formatJson(result) {
86
- return {
171
+ const out = {
87
172
  summary: {
88
173
  breaking: result.breakingChanges.length,
89
174
  additions: result.additions.length,
@@ -95,6 +180,14 @@ function formatJson(result) {
95
180
  modifications: result.modifications,
96
181
  warnings: result.warnings,
97
182
  };
183
+ // Additive only, and only with --usage: CI consumers parsing the existing
184
+ // shape see no difference unless they opt in.
185
+ if (result.usage) {
186
+ out.summary.unusedBreaking = (result.unusedBreakingChanges || []).length;
187
+ out.unusedBreakingChanges = result.unusedBreakingChanges || [];
188
+ out.usage = result.usage;
189
+ }
190
+ return out;
98
191
  }
99
192
 
100
193
  module.exports = { formatHuman, formatJson };