specshield 3.4.11 → 3.4.13

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,38 @@
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`, `--usage-max-age`, `--usage-min-coverage`,
19
+ `--no-usage-downgrade`, and a `usage:` block in `.specshield.yml`. JSON output is
20
+ unchanged unless `--usage` is given.
21
+
22
+ ### Fixed (found by testing on real logs — SEART-GHS API + live spec, Elastic, AWS ALB examples)
23
+
24
+ - Object-typed query parameters (Spring DTOs) were judged by their own name, which never
25
+ appears in URLs, and reported as unused while 1,491 calls sent their fields.
26
+ - Filtered or sampled logs made unseen endpoints look unused: unused changes now pass only
27
+ when ≥ 25% of the spec's operations appear in the logs (`--usage-min-coverage`).
28
+ - The 30-day staleness guard couldn't be relaxed for archived logs (`--usage-max-age`).
29
+ - JSON logs: added the field names of Elastic (`agent`, `response`), Caddy, Traefik, Envoy
30
+ and Google Cloud LB; previously Elastic JSON gave 1 client where the same events in
31
+ combined format gave 36.
32
+ - Multi-word User-Agent products are kept ("Debian APT-HTTP/1.3", not "Debian").
33
+ - `usage import --host` filters by host; ALB/JSON logs from a load balancer serving
34
+ several APIs no longer mix their traffic, and the import warns when hosts are mixed.
35
+
3
36
  ## 3.4.0 — 2026-07-29 — `govern` command (API governance in the CLI)
4
37
 
5
38
  ### 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,84 @@ 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
+ - **One load balancer, several APIs?** ALB and JSON logs record the host; pass
294
+ `--host api.example.com` (repeatable, `*.example.com` globs) so another API's traffic
295
+ doesn't count as usage of this one. The import warns when it sees mixed hosts.
296
+ - **Import logs from every server.** If several instances each write their own log,
297
+ import all of them — logs from one node make the others' clients look like non-users.
298
+
299
+ **2. Compare with impact:**
300
+
301
+ ```bash
302
+ specshield compare base.yaml target.yaml --usage usage.json --fail-on-breaking
303
+ ```
304
+
305
+ - **Endpoint and method removals, body/response field changes** → the clients calling that
306
+ operation. Access logs don't show which response fields a client reads, so for field
307
+ changes this is "clients that may be affected", and the report says so.
308
+ - **Query parameters** are judged exactly: a removed parameter affects only clients that
309
+ *send* it; a parameter that became required affects only clients that *omit* it.
310
+ - **Zero calls → "breaking but unused"**: listed separately and excluded from
311
+ `--fail-on-breaking`. SpecShield only does this when the evidence is good enough — at
312
+ least `--usage-min-days` (default 7) of logs, the newest no older than `--usage-max-age`
313
+ (default 30) days, calls that match the base spec, and at least `--usage-min-coverage`
314
+ (default 25) percent of the spec's operations seen in the logs — fewer usually means the
315
+ logs are filtered, sampled or from one server of several. Otherwise the change stays
316
+ breaking and the report says why. `--no-usage-downgrade` keeps everything breaking.
317
+ - Object-typed query parameters (e.g. a Spring `@ModelAttribute` DTO) are sent as their
318
+ properties, not under their own name, so they're judged by who calls the endpoint.
319
+ - Leave health checks and bots out: `--usage-ignore-client 'kube-probe/*' --usage-ignore-client healthcheck`.
320
+ - `--json` adds `impact` to each change, plus `unusedBreakingChanges`, `summary.unusedBreaking`
321
+ and a `usage` block. Without `--usage` the JSON is unchanged.
322
+
323
+ **3. Find dead and undocumented endpoints:**
324
+
325
+ ```bash
326
+ specshield usage show usage.json --spec api/openapi.yaml
327
+ # NEVER CALLED IN THIS WINDOW → candidates for deprecation
328
+ # CALLED BUT NOT IN THE SPEC → shadow endpoints your spec is missing
329
+ ```
330
+
253
331
  ## Remote Compare
254
332
 
255
333
  Sends your specs to SpecShield's hosted diff engine. Useful for keeping the
@@ -1201,6 +1279,15 @@ severity: error # info | warning | error
1201
1279
  ignore:
1202
1280
  - "DELETE /admin removed" # match by substring; repeatable
1203
1281
 
1282
+ # Usage-aware compare (same as --usage …; see "Who does a change break?").
1283
+ # usage:
1284
+ # file: usage.json
1285
+ # ignoreClients: ["kube-probe/*"]
1286
+ # minDays: 7
1287
+ # maxAgeDays: 30
1288
+ # minCoverage: 25
1289
+ # downgrade: true
1290
+
1204
1291
  # Hosted compare (set --remote on the CLI to override).
1205
1292
  remote:
1206
1293
  enabled: false
@@ -1258,6 +1345,12 @@ specshield compare <base> <target> [options]
1258
1345
  | `--severity <level>` | Minimum severity shown: `info` / `warning` / `error` (default `info`) |
1259
1346
  | `--config <path>` | Path to `.specshield.yml` |
1260
1347
  | `--remote-url <url>` | Override the hosted API base URL |
1348
+ | `--usage <file>` | `usage.json` from `specshield usage import` — show which clients each breaking change affects |
1349
+ | `--usage-ignore-client <pattern>` | Leave a client out of the impact (repeatable; `*` globs, otherwise substring) |
1350
+ | `--usage-min-days <n>` | Days of usage needed before an unused breaking change stops failing the build (default `7`) |
1351
+ | `--usage-max-age <days>` | The newest log line may be at most this old for unused changes to pass (default `30`) |
1352
+ | `--usage-min-coverage <pct>` | Percent of spec operations that must appear in the logs for unused changes to pass (default `25`) |
1353
+ | `--no-usage-downgrade` | Annotate impact only; keep unused breaking changes breaking |
1261
1354
  | `--timeout <ms>` | Request timeout for remote mode (default `10000`) |
1262
1355
 
1263
1356
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specshield",
3
- "version": "3.4.11",
3
+ "version": "3.4.13",
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,12 @@ 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('--usage-max-age <days>', 'Newest log line may be at most this old for unused changes to pass (default: 30)')
50
+ .option('--usage-min-coverage <pct>', 'Percent of spec operations that must appear in the logs for unused changes to pass (default: 25)')
51
+ .option('--no-usage-downgrade', 'Annotate impact only; keep unused breaking changes as breaking')
46
52
  .action(async (base, target, opts) => {
47
53
  try {
48
54
  // Load config
@@ -83,6 +89,13 @@ compare
83
89
  // Apply severity filter
84
90
  result = filterBySeverity(result, options.severity);
85
91
 
92
+ // Join the changes to real traffic. Runs after the ignore list and
93
+ // severity filter so it only annotates what will be reported, and
94
+ // before the exit code so unused breaking changes don't fail the build.
95
+ if (options.usage) {
96
+ result = await applyUsage(result, base, options);
97
+ }
98
+
86
99
  // Output
87
100
  if (options.json) {
88
101
  const jsonOutput = formatJson(result);
@@ -139,6 +152,39 @@ compare
139
152
  }
140
153
  });
141
154
 
155
+ async function applyUsage(result, base, options) {
156
+ const { loadUsage } = require('../core/usage/usageStore');
157
+ const { applyUsageImpact } = require('../core/usage/impact');
158
+
159
+ const usage = await loadUsage(options.usage);
160
+ const baseSpec = parseSpec(await loadSpec(base), base);
161
+ const num = (value, flag, max = Infinity) => {
162
+ const n = Number(value);
163
+ if (!Number.isFinite(n) || n < 0 || n > max) throw new Error(`${flag} must be a number from 0 to ${max}, got "${value}"`);
164
+ return n;
165
+ };
166
+ const minDays = num(options.usageMinDays, '--usage-min-days');
167
+ const maxAgeDays = num(options.usageMaxAge, '--usage-max-age');
168
+ const minCoverage = num(options.usageMinCoverage, '--usage-min-coverage', 100);
169
+
170
+ const { result: annotated, meta } = applyUsageImpact(result, {
171
+ usage,
172
+ baseSpec,
173
+ baseNorm: normalizeSpec(baseSpec),
174
+ file: path.basename(options.usage),
175
+ ignoreClients: options.usageIgnoreClient,
176
+ minDays,
177
+ maxAgeDays,
178
+ minCoverage,
179
+ downgrade: options.usageDowngrade,
180
+ });
181
+ if (!meta.trusted && meta.totalCalls > 0) {
182
+ logger.warn(`None of the calls in ${options.usage} match an operation in ${base}. ` +
183
+ 'Is it the right usage file? If the API is served under a prefix, re-import with --base-path.');
184
+ }
185
+ return { ...annotated, usage: meta };
186
+ }
187
+
142
188
  async function runLocalComparison(base, target, options, spinner) {
143
189
  if (spinner) spinner.text = 'Loading base spec...';
144
190
  const baseRaw = await loadSpec(base);
@@ -257,6 +303,23 @@ function mergeOptions(config, cliOpts) {
257
303
  remote: cliOpts.remote || (config.remote && config.remote.enabled) || false,
258
304
  remoteUrl: cliOpts.remoteUrl || null,
259
305
  timeout: cliOpts.timeout || (config.remote && config.remote.timeout) || 10000,
306
+ usage: cliOpts.usage || (config.usage && config.usage.file) || null,
307
+ usageIgnoreClient: [
308
+ ...(cliOpts.usageIgnoreClient || []),
309
+ ...((config.usage && config.usage.ignoreClients) || []),
310
+ ],
311
+ usageMinDays: cliOpts.usageMinDays !== undefined
312
+ ? cliOpts.usageMinDays
313
+ : config.usage && config.usage.minDays !== undefined ? config.usage.minDays : 7,
314
+ usageMaxAge: cliOpts.usageMaxAge !== undefined
315
+ ? cliOpts.usageMaxAge
316
+ : config.usage && config.usage.maxAgeDays !== undefined ? config.usage.maxAgeDays : 30,
317
+ usageMinCoverage: cliOpts.usageMinCoverage !== undefined
318
+ ? cliOpts.usageMinCoverage
319
+ : config.usage && config.usage.minCoverage !== undefined ? config.usage.minCoverage : 25,
320
+ usageDowngrade: cliOpts.usageDowngrade === false
321
+ ? false
322
+ : !(config.usage && config.usage.downgrade === false),
260
323
  };
261
324
  }
262
325
 
@@ -0,0 +1,243 @@
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('--host <name>', 'Only count requests for this host, e.g. api.example.com or *.example.com (repeatable)', collect, [])
32
+ .option('--since <duration>', 'Only count requests newer than this, e.g. 30d')
33
+ .option('--append', 'Add to an existing --out file instead of replacing it')
34
+ .action(async (logs, opts) => {
35
+ try {
36
+ const clientSpec = parseClientSpec(opts.client);
37
+ const sinceMs = opts.since ? Date.now() - parseDuration(opts.since) : null;
38
+
39
+ let spec = null;
40
+ let matcher = null;
41
+ if (opts.spec) {
42
+ spec = parseSpec(await loadSpec(opts.spec), opts.spec);
43
+ matcher = createRouteMatcher(spec, { basePath: opts.basePath });
44
+ }
45
+
46
+ let existing = null;
47
+ if (opts.append && await fsExtra.pathExists(opts.out)) {
48
+ existing = await loadUsage(opts.out);
49
+ if (existing.client !== clientSpec.spec) {
50
+ throw new Error(`${opts.out} identifies clients by "${existing.client}", not "${clientSpec.spec}". Use the same --client to append.`);
51
+ }
52
+ }
53
+
54
+ const aggregator = new UsageAggregator({ clientSpec, matcher, sinceMs, hosts: opts.host });
55
+ const sources = existing ? [...(existing.sources || [])] : [];
56
+ const seen = new Set(sources.map((s) => s.fingerprint).filter(Boolean));
57
+ const imported = [];
58
+
59
+ for (const file of logs) {
60
+ if (file !== '-') {
61
+ const fp = await fingerprintFile(file).catch(() => null);
62
+ if (fp && seen.has(fp)) {
63
+ logger.warn(`Skipping ${file} — already imported into ${opts.out}`);
64
+ continue;
65
+ }
66
+ }
67
+ const r = await importLogFile(file, { format: opts.format, aggregator });
68
+ if (r.fingerprint) seen.add(r.fingerprint);
69
+ imported.push(r);
70
+ sources.push({ file: r.file, format: r.format, lines: r.lines, parsed: r.parsed, fingerprint: r.fingerprint });
71
+ if (r.parsed === 0 && r.lines > 0) logger.warn(`${file}: no request lines recognised as ${r.format}`);
72
+ }
73
+
74
+ if (aggregator.stats.requests === 0 && !existing) {
75
+ throw new Error('No requests were counted. Check the log format (--format), --since, and that the files are access logs.');
76
+ }
77
+ const runStats = { ...aggregator.stats };
78
+ if (existing) aggregator.absorb(existing);
79
+
80
+ const out = aggregator.toJSON({
81
+ generator: `specshield-cli ${version}`,
82
+ client: clientSpec.spec,
83
+ spec: spec ? { title: (spec.info && spec.info.title) || null, version: (spec.info && spec.info.version) || null } : null,
84
+ basePath: opts.basePath || (existing && existing.basePath) || null,
85
+ sources,
86
+ });
87
+ await fsExtra.outputFile(opts.out, JSON.stringify(out, null, 2) + '\n');
88
+
89
+ printImportSummary(out, imported, runStats, {
90
+ outFile: opts.out, matcher, appended: !!existing, hostsSeen: aggregator.hostsSeen, hostFilter: opts.host.length > 0,
91
+ });
92
+ exitAfterFlush(0);
93
+ } catch (err) {
94
+ logger.error(`Error: ${err.message}`);
95
+ process.exit(2);
96
+ }
97
+ });
98
+
99
+ function printImportSummary(out, imported, run, { outFile, matcher, appended, hostsSeen, hostFilter }) {
100
+ const lines = [];
101
+ const parsed = imported.reduce((n, r) => n + r.parsed, 0);
102
+ const skipped = imported.reduce((n, r) => n + r.skipped, 0);
103
+ const formats = [...new Set(imported.map((r) => r.format).filter(Boolean))].join(', ') || '—';
104
+ const clients = new Set(out.endpoints.flatMap((e) => e.clients.map((c) => c.id)));
105
+
106
+ if (imported.length === 0) {
107
+ process.stdout.write(chalk.gray(` Nothing new to import — ${outFile} is unchanged.`) + '\n');
108
+ return;
109
+ }
110
+ lines.push(chalk.green(`✔ ${appended ? 'Updated' : 'Wrote'} ${outFile}`));
111
+ lines.push(` ${plural(parsed, 'request')} from ${plural(imported.length, 'file')} (${formats})` +
112
+ (out.window.from ? ` · ${day(out.window.from)} → ${day(out.window.to)} (${spanDays(out.window)} days)` : ''));
113
+ lines.push(` ${plural(out.endpoints.length, 'endpoint')} · ${plural(clients.size, 'client')}` +
114
+ (matcher ? ` · ${fmt(run.matched)} matched the spec · ${fmt(run.unmatched)} not in the spec` : ''));
115
+ if (run.notFound) lines.push(chalk.gray(` ${plural(run.notFound, 'request')} to unknown paths answered 404/405 skipped (scanners)`));
116
+ if (run.otherHost) lines.push(chalk.gray(` ${plural(run.otherHost, 'request')} for other hosts skipped (--host)`));
117
+ if (!hostFilter && hostsSeen.size > 1) {
118
+ const top = [...hostsSeen.entries()].sort((a, b) => b[1] - a[1]).slice(0, 4).map(([h, n]) => `${h} (${fmt(n)})`);
119
+ lines.push(chalk.yellow(` Requests for ${hostsSeen.size} hosts are mixed: ${top.join(', ')}${hostsSeen.size > 4 ? ', …' : ''}.`));
120
+ lines.push(chalk.yellow(' If they are different APIs, re-import with --host <name> so they don\'t count as usage of this one.'));
121
+ }
122
+ if (run.tooOld) lines.push(chalk.gray(` ${plural(run.tooOld, 'request')} older than --since skipped`));
123
+ if (run.overflow) lines.push(chalk.yellow(` ${plural(run.overflow, 'request')} dropped: endpoint limit reached (use --spec to group paths)`));
124
+ if (skipped) lines.push(chalk.gray(` ${plural(skipped, 'line')} skipped (not a request)`));
125
+
126
+ if (clients.size === 1 && clients.has('unknown')) {
127
+ lines.push(chalk.yellow(' Every request has client "unknown" — the logs carry no User-Agent. Pick another signal with --client.'));
128
+ }
129
+ if (matcher && run.requests > 0 && run.matched / run.requests < 0.5) {
130
+ lines.push(chalk.yellow(` Only ${pct(run.matched / run.requests)} of requests matched the spec.` +
131
+ (matcher.basePaths.length ? '' : ' If the API is served under a prefix, pass --base-path (e.g. --base-path /api).')));
132
+ }
133
+ if (!matcher) {
134
+ lines.push(chalk.gray(' Tip: pass --spec openapi.yaml to group paths exactly as the spec defines them.'));
135
+ }
136
+ lines.push('');
137
+ lines.push(` Next: ${chalk.cyan(`specshield compare base.yaml target.yaml --usage ${outFile}`)}`);
138
+ process.stdout.write(lines.join('\n') + '\n');
139
+ }
140
+
141
+ // ─── usage show ─────────────────────────────────────────────────────────────
142
+
143
+ usage
144
+ .command('show')
145
+ .description('Summarise a usage file; with --spec, list endpoints nobody calls and calls the spec does not document')
146
+ .argument('[file]', 'Usage file', 'usage.json')
147
+ .option('--spec <file>', 'OpenAPI spec to check against')
148
+ .option('--top <n>', 'How many endpoints to list', '15')
149
+ .option('--json', 'Output machine-readable JSON')
150
+ .action(async (file, opts) => {
151
+ try {
152
+ const data = await loadUsage(file);
153
+ const top = Math.max(1, parseInt(opts.top, 10) || 15);
154
+ let unused = null;
155
+ let undocumented = null;
156
+ let calledCount = 0;
157
+
158
+ if (opts.spec) {
159
+ const spec = parseSpec(await loadSpec(opts.spec), opts.spec);
160
+ const matcher = createRouteMatcher(spec, { basePath: data.basePath });
161
+ const called = new Set();
162
+ undocumented = [];
163
+ for (const e of data.endpoints) {
164
+ const m = matcher.match(e.method, e.path);
165
+ if (m && m.operation) called.add(`${m.method} ${m.template}`);
166
+ else undocumented.push({ method: e.method, path: e.path, calls: e.calls, lastSeen: e.lastSeen, clients: e.clients.length });
167
+ }
168
+ calledCount = called.size;
169
+ unused = matcher.operations
170
+ .filter((o) => !called.has(`${o.method} ${o.template}`))
171
+ .map((o) => ({ method: o.method, path: o.template }));
172
+ }
173
+
174
+ if (opts.json) {
175
+ process.stdout.write(JSON.stringify({
176
+ window: data.window,
177
+ totalCalls: data.endpoints.reduce((n, e) => n + e.calls, 0),
178
+ endpoints: data.endpoints.slice(0, top),
179
+ ...(unused ? { unusedOperations: unused, undocumentedEndpoints: undocumented } : {}),
180
+ }, null, 2) + '\n');
181
+ return exitAfterFlush(0);
182
+ }
183
+
184
+ process.stdout.write(renderShow(data, { top, unused, undocumented, seenOps: calledCount }) + '\n');
185
+ exitAfterFlush(0);
186
+ } catch (err) {
187
+ logger.error(`Error: ${err.message}`);
188
+ process.exit(2);
189
+ }
190
+ });
191
+
192
+ function renderShow(data, { top, unused, undocumented, seenOps }) {
193
+ const lines = [];
194
+ const total = data.endpoints.reduce((n, e) => n + e.calls, 0);
195
+ lines.push('');
196
+ lines.push(chalk.bold(' SpecShield™ API Usage'));
197
+ lines.push(chalk.gray(' ─────────────────────────────────────────'));
198
+ lines.push(` ${plural(total, 'call')} · ${plural(data.endpoints.length, 'endpoint')}` +
199
+ (data.window.from ? ` · ${day(data.window.from)} → ${day(data.window.to)} (${spanDays(data.window)} days)` : '') +
200
+ chalk.gray(` clients by ${data.client}`));
201
+ lines.push('');
202
+
203
+ for (const e of data.endpoints.slice(0, top)) {
204
+ lines.push(` ${chalk.bold(e.method.padEnd(6))} ${e.path} ${chalk.gray(plural(e.calls, 'call'))}`);
205
+ const shown = e.clients.slice(0, 3);
206
+ for (const c of shown) {
207
+ lines.push(chalk.gray(` ${c.id.padEnd(28)} ${pct(c.calls / e.calls).padStart(4)} last seen ${ago(c.lastSeen)}`));
208
+ }
209
+ if (e.clients.length > shown.length) lines.push(chalk.gray(` …and ${plural(e.clients.length - shown.length, 'more client')}`));
210
+ }
211
+ if (data.endpoints.length > top) lines.push(chalk.gray(` …${data.endpoints.length - top} more endpoint(s) — raise --top`));
212
+
213
+ if (unused) {
214
+ lines.push('');
215
+ lines.push(chalk.green.bold(` ✔ NEVER CALLED IN THIS WINDOW (${unused.length}) — candidates for deprecation`));
216
+ lines.push(chalk.gray(' ─────────────────────────────────────────'));
217
+ const total = unused.length + seenOps;
218
+ if (total > 0 && seenOps / total < 0.25) {
219
+ lines.push(chalk.yellow(` Only ${seenOps} of ${total} operations appear in these logs. If the logs are filtered,`));
220
+ lines.push(chalk.yellow(' sampled or from one server of several, this list is not reliable.'));
221
+ }
222
+ if (unused.length === 0) lines.push(chalk.gray(' Every operation in the spec was called.'));
223
+ for (const o of unused) lines.push(` ${chalk.green('○')} ${o.method} ${o.path}`);
224
+ }
225
+ if (undocumented) {
226
+ lines.push('');
227
+ lines.push(chalk.yellow.bold(` ⚠ CALLED BUT NOT IN THE SPEC (${undocumented.length})`));
228
+ lines.push(chalk.gray(' ─────────────────────────────────────────'));
229
+ if (undocumented.length === 0) lines.push(chalk.gray(' All traffic matches a documented operation.'));
230
+ for (const u of undocumented.slice(0, top)) {
231
+ lines.push(` ${chalk.yellow('!')} ${u.method} ${u.path} ${chalk.gray(`${plural(u.calls, 'call')} · ${plural(u.clients, 'client')}`)}`);
232
+ }
233
+ if (undocumented.length > top) lines.push(chalk.gray(` …${undocumented.length - top} more`));
234
+ }
235
+ lines.push('');
236
+ return lines.join('\n');
237
+ }
238
+
239
+ function collect(value, previous) {
240
+ return previous.concat([value]);
241
+ }
242
+
243
+ module.exports = usage;
@@ -105,6 +105,38 @@ 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
+ for (const key of ['maxAgeDays', 'minCoverage']) {
120
+ if (u[key] !== undefined && !(Number(u[key]) >= 0)) {
121
+ throw new Error(`Config error in "${filePath}": usage.${key} must be a number ≥ 0`);
122
+ }
123
+ }
124
+ if (u.downgrade !== undefined && typeof u.downgrade !== 'boolean') {
125
+ throw new Error(`Config error in "${filePath}": usage.downgrade must be a boolean`);
126
+ }
127
+ valid.usage = {
128
+ file: u.file || null,
129
+ ignoreClients: (u.ignoreClients || []).filter(Boolean).map(String),
130
+ minDays: u.minDays !== undefined ? Number(u.minDays) : undefined,
131
+ maxAgeDays: u.maxAgeDays !== undefined ? Number(u.maxAgeDays) : undefined,
132
+ minCoverage: u.minCoverage !== undefined ? Number(u.minCoverage) : undefined,
133
+ downgrade: u.downgrade,
134
+ };
135
+ } else {
136
+ throw new Error(`Config error in "${filePath}": usage must be a file path or an object`);
137
+ }
138
+ }
139
+
108
140
  return valid;
109
141
  }
110
142