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 +18 -0
- package/README.md +81 -1
- package/package.json +1 -1
- package/src/cli.js +2 -0
- package/src/commands/compare.js +49 -0
- package/src/commands/usage.js +223 -0
- package/src/core/configLoader.js +25 -0
- package/src/core/outputFormatter.js +96 -3
- package/src/core/usage/clientIdentity.js +67 -0
- package/src/core/usage/format.js +31 -0
- package/src/core/usage/impact.js +222 -0
- package/src/core/usage/importLogs.js +85 -0
- package/src/core/usage/logParsers.js +262 -0
- package/src/core/usage/routeMatcher.js +127 -0
- package/src/core/usage/usageStore.js +213 -0
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.
|
|
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');
|
package/src/commands/compare.js
CHANGED
|
@@ -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;
|
package/src/core/configLoader.js
CHANGED
|
@@ -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
|
-
|
|
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 };
|