specshield 3.4.10 → 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 +161 -208
- 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/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 };
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const crypto = require('crypto');
|
|
4
|
+
const { lookup } = require('./logParsers');
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Who made a request. The `--client` option picks the signal:
|
|
8
|
+
*
|
|
9
|
+
* ua User-Agent, reduced to "product/major.minor" (default)
|
|
10
|
+
* field:<dot.path> a field of a JSON log line, e.g. field:consumer.username (Kong)
|
|
11
|
+
* extra:<n> the n-th quoted field after the User-Agent in a combined
|
|
12
|
+
* log, e.g. an nginx log_format that appends "$http_x_client_id"
|
|
13
|
+
*
|
|
14
|
+
* Prefix any source with `hash:` (e.g. hash:field:request.headers.x-api-key)
|
|
15
|
+
* to store a one-way hash instead of the value. Use it for API keys: the key
|
|
16
|
+
* never lands in usage.json, but the same key always maps to the same client.
|
|
17
|
+
*/
|
|
18
|
+
function parseClientSpec(spec) {
|
|
19
|
+
const raw = String(spec || 'ua').trim();
|
|
20
|
+
const hash = raw.startsWith('hash:');
|
|
21
|
+
const source = hash ? raw.slice(5) : raw;
|
|
22
|
+
|
|
23
|
+
if (source === 'ua') return { spec: raw, hash, kind: 'ua' };
|
|
24
|
+
let m = /^field:(.+)$/.exec(source);
|
|
25
|
+
if (m) return { spec: raw, hash, kind: 'field', field: m[1] };
|
|
26
|
+
m = /^extra:(\d+)$/.exec(source);
|
|
27
|
+
if (m && Number(m[1]) >= 1) return { spec: raw, hash, kind: 'extra', index: Number(m[1]) - 1 };
|
|
28
|
+
|
|
29
|
+
throw new Error(`Invalid --client "${raw}". Use ua, field:<path>, extra:<n> — optionally prefixed with hash:`);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
function clientIdOf(record, clientSpec) {
|
|
33
|
+
let value;
|
|
34
|
+
if (clientSpec.kind === 'ua') {
|
|
35
|
+
value = normalizeUserAgent(record.userAgent);
|
|
36
|
+
if (value === null) return 'unknown';
|
|
37
|
+
} else if (clientSpec.kind === 'field') {
|
|
38
|
+
const v = record.json ? lookup(record.json, clientSpec.field) : undefined;
|
|
39
|
+
value = v === undefined || v === null || v === '' ? null : String(Array.isArray(v) ? v[0] : v);
|
|
40
|
+
} else {
|
|
41
|
+
value = record.extras[clientSpec.index] ?? null;
|
|
42
|
+
}
|
|
43
|
+
if (value === null) return 'unknown';
|
|
44
|
+
if (clientSpec.hash) return `hash:${crypto.createHash('sha256').update(value).digest('hex').slice(0, 12)}`;
|
|
45
|
+
return value.length > 120 ? value.slice(0, 120) : value;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* "MyShop-iOS/5.2.1 CFNetwork/1410 Darwin/22.6" → "MyShop-iOS/5.2"
|
|
50
|
+
* "okhttp/4.12.0" → "okhttp/4.12"
|
|
51
|
+
* "Mozilla/5.0 (Windows NT 10.0; …) Chrome/…" → "browser"
|
|
52
|
+
*
|
|
53
|
+
* Keeping major.minor groups patch releases of one app version together —
|
|
54
|
+
* the useful question is "is anyone still on 5.2?", not "on 5.2.1 vs 5.2.3?".
|
|
55
|
+
*/
|
|
56
|
+
function normalizeUserAgent(ua) {
|
|
57
|
+
if (!ua) return null;
|
|
58
|
+
const s = ua.trim();
|
|
59
|
+
if (!s) return null;
|
|
60
|
+
if (/^Mozilla\//.test(s)) return 'browser';
|
|
61
|
+
const first = s.split(/\s+/)[0];
|
|
62
|
+
const m = /^([^/]+)\/(\d+)(?:\.(\d+))?/.exec(first);
|
|
63
|
+
if (m) return `${m[1]}/${m[2]}${m[3] !== undefined ? `.${m[3]}` : ''}`;
|
|
64
|
+
return first.length > 60 ? first.slice(0, 60) : first;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
module.exports = { parseClientSpec, clientIdOf, normalizeUserAgent };
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/** Small formatting helpers shared by `usage show` and the compare impact report. */
|
|
4
|
+
|
|
5
|
+
function fmt(n) { return Number(n).toLocaleString('en-US'); }
|
|
6
|
+
|
|
7
|
+
/** plural(1, 'client') → "1 client"; plural(3, 'call') → "3 calls". */
|
|
8
|
+
function plural(n, word) { return `${fmt(n)} ${word}${n === 1 ? '' : 's'}`; }
|
|
9
|
+
|
|
10
|
+
function pct(x) {
|
|
11
|
+
if (x > 0 && x < 0.01) return '<1%';
|
|
12
|
+
return `${Math.round(x * 100)}%`;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
function day(iso) { return iso ? iso.slice(0, 10) : '—'; }
|
|
16
|
+
|
|
17
|
+
function spanDays(w) {
|
|
18
|
+
if (!w || !w.from || !w.to) return null;
|
|
19
|
+
return Math.round(((Date.parse(w.to) - Date.parse(w.from)) / 86400e3) * 10) / 10;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function ago(iso, now = Date.now()) {
|
|
23
|
+
if (!iso) return 'unknown';
|
|
24
|
+
const s = Math.max(0, (now - Date.parse(iso)) / 1000);
|
|
25
|
+
if (s < 90) return 'just now';
|
|
26
|
+
if (s < 5400) return `${Math.round(s / 60)} min ago`;
|
|
27
|
+
if (s < 129600) return `${Math.round(s / 3600)} h ago`;
|
|
28
|
+
return `${Math.round(s / 86400)} days ago`;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
module.exports = { fmt, plural, pct, day, spanDays, ago };
|