toolmenu 0.10.0 → 0.12.0
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/README.md +86 -20
- package/dist/auth.js +8 -1
- package/dist/auto.d.ts +1 -1
- package/dist/auto.js +24 -1
- package/dist/breakdown.d.ts +33 -6
- package/dist/breakdown.js +129 -16
- package/dist/catalog.d.ts +20 -0
- package/dist/catalog.js +100 -17
- package/dist/cli.js +39 -11
- package/dist/compare.js +20 -5
- package/dist/config.d.ts +3 -0
- package/dist/diff.d.ts +13 -1
- package/dist/diff.js +671 -72
- package/dist/failures.d.ts +46 -0
- package/dist/failures.js +86 -0
- package/dist/init.d.ts +8 -3
- package/dist/init.js +14 -7
- package/dist/probe.d.ts +15 -3
- package/dist/probe.js +35 -11
- package/dist/rules/description.js +4 -1
- package/dist/rules/determinism.js +2 -1
- package/dist/rules/index.js +3 -1
- package/dist/rules/spec.d.ts +2 -0
- package/dist/rules/spec.js +29 -0
- package/dist/semver.js +1 -1
- package/dist/session.d.ts +42 -3
- package/dist/session.js +354 -40
- package/dist/snapshot.js +8 -5
- package/package.json +1 -1
package/dist/diff.js
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
1
2
|
import { canonical, compareMenus } from './compare.js';
|
|
3
|
+
import { countTokens } from './menu.js';
|
|
2
4
|
import { isCalendar, parseSemver } from './semver.js';
|
|
3
5
|
import { SEVERITY_RANK } from './types.js';
|
|
4
6
|
/** Every diff rule, its default severity and what it means for semver. */
|
|
@@ -18,6 +20,13 @@ export const DIFF_RULES = {
|
|
|
18
20
|
'diff/description': { severity: 'info', class: 'notice' },
|
|
19
21
|
'diff/param-dropped': { severity: 'info', class: 'notice' },
|
|
20
22
|
'diff/schema-other': { severity: 'info', class: 'notice' },
|
|
23
|
+
// Restructured ($ref, $defs) but accepts the same input: bytes and tokens changed.
|
|
24
|
+
'diff/schema-equivalent': { severity: 'info', class: 'notice' },
|
|
25
|
+
// Only the declared $schema dialect changed: one finding for the menu.
|
|
26
|
+
'diff/schema-dialect': { severity: 'info', class: 'notice' },
|
|
27
|
+
// additionalProperties: false removed (widens) or added (breaks callers sending extras).
|
|
28
|
+
'diff/properties-opened': { severity: 'info', class: 'minor' },
|
|
29
|
+
'diff/properties-closed': { severity: 'error', class: 'breaking' },
|
|
21
30
|
'diff/annotations': { severity: 'info', class: 'notice' },
|
|
22
31
|
'diff/other': { severity: 'info', class: 'notice' },
|
|
23
32
|
'diff/order': { severity: 'info', class: 'notice' },
|
|
@@ -61,6 +70,8 @@ export function diffMenus(before, after, options = {}) {
|
|
|
61
70
|
}
|
|
62
71
|
for (const { from, to } of renames)
|
|
63
72
|
raw.push(...compareTool(from, to).filter((f) => f.rule !== 'diff/description' && f.rule !== 'diff/other'));
|
|
73
|
+
collapseDialects(raw);
|
|
74
|
+
collapseMenuWide(raw);
|
|
64
75
|
const moved = compareMenus(oldTools, newTools).filter((c) => c.kind === 'moved');
|
|
65
76
|
if (moved.length) {
|
|
66
77
|
raw.push({
|
|
@@ -118,16 +129,91 @@ export function diffMenus(before, after, options = {}) {
|
|
|
118
129
|
...(notChecked ? { bumpNotChecked: notChecked } : {}),
|
|
119
130
|
};
|
|
120
131
|
}
|
|
132
|
+
/** The same $schema switch in several tools is one finding that names them. */
|
|
133
|
+
function collapseDialects(raw) {
|
|
134
|
+
const groups = new Map();
|
|
135
|
+
for (const r of raw)
|
|
136
|
+
if (r.rule === 'diff/schema-dialect')
|
|
137
|
+
groups.set(r.detail[0], [...(groups.get(r.detail[0]) ?? []), r]);
|
|
138
|
+
for (const [pair, list] of groups) {
|
|
139
|
+
if (list.length < 2) {
|
|
140
|
+
delete list[0].detail;
|
|
141
|
+
continue;
|
|
142
|
+
}
|
|
143
|
+
const at = raw.indexOf(list[0]);
|
|
144
|
+
for (const r of list)
|
|
145
|
+
raw.splice(raw.indexOf(r), 1);
|
|
146
|
+
const names = list.map((r) => r.tool);
|
|
147
|
+
raw.splice(at, 0, {
|
|
148
|
+
rule: 'diff/schema-dialect',
|
|
149
|
+
message: `${list.length} tools declare a different JSON Schema dialect ($schema ${pair}), and nothing else outside their parameters changed: most likely a schema generator upgrade.`,
|
|
150
|
+
detail: [names.slice(0, 12).join(', ') + (names.length > 12 ? `, and ${names.length - 12} more` : '')],
|
|
151
|
+
});
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Findings that are one change made to the whole menu, found in several tools
|
|
156
|
+
* (zod 4 dropping additionalProperties: false from every object; a refactor
|
|
157
|
+
* across tools): one line naming the tools, every place in `places`.
|
|
158
|
+
*/
|
|
159
|
+
const MENU_WIDE = {
|
|
160
|
+
'diff/properties-opened': (t, p) => `${t} tools now accept properties they don't list (additionalProperties: false removed, at ${p} places): most likely a schema generator upgrade (zod 4 writes nothing where zod 3 wrote false).`,
|
|
161
|
+
'diff/properties-closed': (t, p) => `${t} tools now reject properties they don't list (additionalProperties: false added, at ${p} places). Calls that send one can fail.`,
|
|
162
|
+
'diff/schema-equivalent': (t) => `${t} tools are restructured or spelled differently but accept the same input.`,
|
|
163
|
+
};
|
|
164
|
+
function collapseMenuWide(raw) {
|
|
165
|
+
for (const [rule, summary] of Object.entries(MENU_WIDE)) {
|
|
166
|
+
const list = raw.filter((r) => r.rule === rule && r.tool);
|
|
167
|
+
if (list.length < 2)
|
|
168
|
+
continue;
|
|
169
|
+
const at = raw.indexOf(list[0]);
|
|
170
|
+
for (const r of list)
|
|
171
|
+
raw.splice(raw.indexOf(r), 1);
|
|
172
|
+
const places = list.flatMap((r) => r.places ?? [r.message.split(' ')[0].replace(/:$/, '')]);
|
|
173
|
+
const names = list.map((r) => r.tool);
|
|
174
|
+
raw.splice(at, 0, {
|
|
175
|
+
rule,
|
|
176
|
+
message: summary(list.length, places.length),
|
|
177
|
+
detail: [names.slice(0, 12).join(', ') + (names.length > 12 ? `, and ${names.length - 12} more` : '')],
|
|
178
|
+
places,
|
|
179
|
+
});
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* How deep a schema is compared field by field, counting every object, array
|
|
184
|
+
* items and union option on the way. 8 cut off a document schema's lists, tables
|
|
185
|
+
* and quotes (block → items → option → fields → items → option → …) while its
|
|
186
|
+
* paragraphs were compared, so one change read as an error at two places and
|
|
187
|
+
* "review it" at four. Recursion is bounded by resolveRefs, not by this.
|
|
188
|
+
*/
|
|
189
|
+
const MAX_DEPTH = 64;
|
|
121
190
|
function compareTool(old, t) {
|
|
122
191
|
const out = [];
|
|
123
192
|
const name = t.name;
|
|
124
193
|
if ((old.description ?? '') !== (t.description ?? '')) {
|
|
125
194
|
out.push({ rule: 'diff/description', tool: name, message: `${name}: description changed. It doesn't break the protocol, but it changes what the agent does.`, detail: textDiff(old.description ?? '', t.description ?? '') });
|
|
126
195
|
}
|
|
127
|
-
|
|
128
|
-
|
|
196
|
+
// Compared by what they accept, not how they're spelled: a block moved into
|
|
197
|
+
// $defs and referenced is the same schema.
|
|
198
|
+
const ea = expandRefs(old.inputSchema);
|
|
199
|
+
const eb = expandRefs(t.inputSchema);
|
|
200
|
+
// Too large to expand on either side: compare both as written, so an expanded
|
|
201
|
+
// side isn't read against a $ref on the other ("object → any"), and say so.
|
|
202
|
+
const expanded = ea.expanded && eb.expanded;
|
|
203
|
+
const a = expanded ? ea.schema : old.inputSchema;
|
|
204
|
+
const b = expanded ? eb.schema : t.inputSchema;
|
|
205
|
+
if (!expanded && canonical(old.inputSchema) !== canonical(t.inputSchema)) {
|
|
206
|
+
const which = ea.expanded ? 'the new inputSchema expands' : eb.expanded ? 'the old inputSchema expands' : 'the old and new inputSchemas expand';
|
|
207
|
+
out.push({
|
|
208
|
+
rule: 'diff/schema-other',
|
|
209
|
+
tool: name,
|
|
210
|
+
message: `${name}: ${which} past ${fmt(MAX_EXPANDED_NODES)} nodes through ${ea.expanded || eb.expanded ? 'its' : 'their'} $refs, so both are compared as written, $defs entries by name: a $ref moved to another name reads as a change. Review it.`,
|
|
211
|
+
});
|
|
212
|
+
}
|
|
213
|
+
const oldEmpty = isEmptySchema(a);
|
|
214
|
+
const newEmpty = isEmptySchema(b);
|
|
129
215
|
if (oldEmpty || newEmpty) {
|
|
130
|
-
if (canonical(
|
|
216
|
+
if (canonical(a) !== canonical(b)) {
|
|
131
217
|
out.push({
|
|
132
218
|
rule: 'diff/schema-other',
|
|
133
219
|
tool: name,
|
|
@@ -136,83 +222,578 @@ function compareTool(old, t) {
|
|
|
136
222
|
}
|
|
137
223
|
return out.concat(compareRest(old, t));
|
|
138
224
|
}
|
|
139
|
-
const
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
225
|
+
const found = out.length;
|
|
226
|
+
compareObject({ tool: name, out }, name, a, b, 0);
|
|
227
|
+
// Compared as written (too large to expand): the parameters hold $refs, so
|
|
228
|
+
// what they point to is compared here, definition by definition, by name. A
|
|
229
|
+
// narrowed enum inside one is still breaking.
|
|
230
|
+
if (!expanded)
|
|
231
|
+
compareDefinitions({ tool: name, out }, name, old.inputSchema ?? {}, t.inputSchema ?? {});
|
|
232
|
+
collapsePlaces(out, found);
|
|
233
|
+
const shell = (s) => {
|
|
234
|
+
const { properties: _p, required: _r, $defs: _d, definitions: _df, ...rest } = (s ?? {});
|
|
235
|
+
// additionalProperties: false coming or going is said by compareObject.
|
|
236
|
+
if (rest.additionalProperties === false)
|
|
237
|
+
delete rest.additionalProperties;
|
|
238
|
+
return rest;
|
|
239
|
+
};
|
|
240
|
+
const [sa, sb] = [shell(a), shell(b)];
|
|
241
|
+
if (canonical(sa) !== canonical(sb)) {
|
|
242
|
+
const { $schema: da, ...ra } = sa;
|
|
243
|
+
const { $schema: db, ...rb } = sb;
|
|
244
|
+
// Only the declared dialect: a schema generator upgrade (zod 3 → 4 moved
|
|
245
|
+
// mongodb-mcp-server 3.0.0 from draft-07 to 2020-12 in every tool). Said once
|
|
246
|
+
// for the menu, below.
|
|
247
|
+
if (canonical(ra) === canonical(rb)) {
|
|
248
|
+
const pair = `${show(da)} → ${show(db)}`;
|
|
249
|
+
out.push({ rule: 'diff/schema-dialect', tool: name, message: `${name}: inputSchema declares a different JSON Schema dialect ($schema ${pair}), and nothing else outside its parameters changed.`, detail: [pair] });
|
|
250
|
+
}
|
|
251
|
+
else
|
|
252
|
+
out.push({ rule: 'diff/schema-other', tool: name, message: `${name}: inputSchema changed outside its parameters (additionalProperties, $schema…). Review it.` });
|
|
253
|
+
}
|
|
254
|
+
// Never silent: the schemas differ, and nothing above says how. Spellings the
|
|
255
|
+
// rules treat as one (a type as anyOf alternatives or a list) don't count.
|
|
256
|
+
if (expanded && out.length === found && canonical(sameTypes(a)) !== canonical(sameTypes(b))) {
|
|
257
|
+
out.push({ rule: 'diff/schema-other', tool: name, message: `${name}: inputSchema changed in a way toolmenu doesn't classify. Review it.` });
|
|
258
|
+
}
|
|
259
|
+
// Spelled differently, accepts the same: say so, so the refactor needs no review.
|
|
260
|
+
if (canonical(a) === canonical(b) && canonical(old.inputSchema) !== canonical(t.inputSchema)) {
|
|
261
|
+
const delta = countTokens(JSON.stringify(t.inputSchema ?? {})) - countTokens(JSON.stringify(old.inputSchema ?? {}));
|
|
262
|
+
out.push({
|
|
263
|
+
rule: 'diff/schema-equivalent',
|
|
264
|
+
tool: name,
|
|
265
|
+
message: `${name}: inputSchema restructured ($ref, $defs, key order) but accepts the same input: ${delta === 0 ? 'no change in size' : `~${fmt(Math.abs(delta))} tokens ${delta < 0 ? 'fewer' : 'more'}`} (estimate).`,
|
|
266
|
+
});
|
|
267
|
+
}
|
|
268
|
+
return out.concat(compareRest(old, t));
|
|
269
|
+
}
|
|
270
|
+
/** A schema with every type written one way: `type: [sorted]`, for anyOf/oneOf type alternatives too. */
|
|
271
|
+
function sameTypes(node) {
|
|
272
|
+
if (Array.isArray(node))
|
|
273
|
+
return node.map(sameTypes);
|
|
274
|
+
if (!node || typeof node !== 'object')
|
|
275
|
+
return node;
|
|
276
|
+
const s = node;
|
|
277
|
+
// Name → schema maps: their keys are names, not keywords (a property called
|
|
278
|
+
// `type` is a schema, not a type).
|
|
279
|
+
const out = Object.fromEntries(Object.entries(s).map(([k, v]) => [k, SCHEMA_MAPS.has(k) && v && typeof v === 'object' && !Array.isArray(v) ? mapValues(v, sameTypes) : sameTypes(v)]));
|
|
280
|
+
const alternatives = typeAlternatives(s);
|
|
281
|
+
if (alternatives) {
|
|
282
|
+
delete out.anyOf;
|
|
283
|
+
delete out.oneOf;
|
|
284
|
+
out.type = [...new Set(alternatives)].sort();
|
|
285
|
+
// The options' descriptions stay, as the node's (describedAs).
|
|
286
|
+
const described = describedAs(s);
|
|
287
|
+
if (described)
|
|
288
|
+
out.description = described;
|
|
289
|
+
}
|
|
290
|
+
else if (typeof s.type === 'string' || (Array.isArray(s.type) && s.type.every((t) => typeof t === 'string'))) {
|
|
291
|
+
out.type = [...new Set(Array.isArray(s.type) ? s.type : [s.type])].sort();
|
|
292
|
+
}
|
|
293
|
+
// A union accepts the same whatever order its options come in.
|
|
294
|
+
for (const k of ['anyOf', 'oneOf']) {
|
|
295
|
+
if (Array.isArray(out[k]))
|
|
296
|
+
out[k] = [...out[k]].sort((x, y) => (canonical(x) < canonical(y) ? -1 : canonical(x) > canonical(y) ? 1 : 0));
|
|
297
|
+
}
|
|
298
|
+
return out;
|
|
299
|
+
}
|
|
300
|
+
/** `$defs` and `definitions` entries of two unexpanded schemas, compared by name. */
|
|
301
|
+
function compareDefinitions(w, name, oldS, newS) {
|
|
302
|
+
const list = (names) => [...names].sort((x, y) => x.localeCompare(y, 'en', { numeric: true })).slice(0, 8).join(', ') + (names.length > 8 ? `, and ${names.length - 8} more` : '');
|
|
303
|
+
for (const pool of ['$defs', 'definitions']) {
|
|
304
|
+
const [a, b] = [(oldS[pool] ?? {}), (newS[pool] ?? {})];
|
|
305
|
+
const removed = Object.keys(a).filter((k) => !(k in b));
|
|
306
|
+
const added = Object.keys(b).filter((k) => !(k in a));
|
|
307
|
+
// One line each for definitions only one side has: what refers to them is compared above.
|
|
308
|
+
if (removed.length)
|
|
309
|
+
w.out.push({ rule: 'diff/schema-other', tool: w.tool, message: `${name}: ${pool} ${removed.length === 1 ? 'entry' : 'entries'} removed (${list(removed)}). Review what referred to ${removed.length === 1 ? 'it' : 'them'}.` });
|
|
310
|
+
if (added.length)
|
|
311
|
+
w.out.push({ rule: 'diff/schema-other', tool: w.tool, message: `${name}: ${pool} ${added.length === 1 ? 'entry' : 'entries'} added (${list(added)}).` });
|
|
312
|
+
for (const [k, def] of Object.entries(b)) {
|
|
313
|
+
if (k in a)
|
|
314
|
+
compareSchema(w, `${name}.${pool}.${k}`, `${name}.${pool}.${k}`, a[k], def, 1);
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
const DESCRIPTIVE = new Set(['description', 'title', 'examples', '$comment']);
|
|
319
|
+
/** A schema without the keywords that describe it but don't change what it accepts. */
|
|
320
|
+
function shape(node) {
|
|
321
|
+
if (Array.isArray(node))
|
|
322
|
+
return node.map(shape);
|
|
323
|
+
if (!node || typeof node !== 'object')
|
|
324
|
+
return node;
|
|
325
|
+
return Object.fromEntries(Object.entries(node)
|
|
326
|
+
.filter(([k]) => !DESCRIPTIVE.has(k))
|
|
327
|
+
.map(([k, v]) => [k, SCHEMA_MAPS.has(k) && v && typeof v === 'object' && !Array.isArray(v) ? mapValues(v, shape) : shape(v)]));
|
|
328
|
+
}
|
|
329
|
+
/** Keywords whose value maps names to schemas. */
|
|
330
|
+
const SCHEMA_MAPS = new Set(['properties', '$defs', 'definitions', 'patternProperties', 'dependentSchemas']);
|
|
331
|
+
function mapValues(map, f) {
|
|
332
|
+
return Object.fromEntries(Object.entries(map).map(([k, v]) => [k, f(v)]));
|
|
333
|
+
}
|
|
334
|
+
/** A short, stable fingerprint of a (canonical) value. */
|
|
335
|
+
function digest(value) {
|
|
336
|
+
return createHash('sha1').update(canonical(value ?? null)).digest('base64').slice(0, 16);
|
|
337
|
+
}
|
|
338
|
+
/**
|
|
339
|
+
* A finding at a place in the schema, about `node` (the schema there, before and
|
|
340
|
+
* after). The place and what changed are kept apart, so one change reached
|
|
341
|
+
* through a shared definition at several places can be said once
|
|
342
|
+
* (collapsePlaces). That takes the same rule and words, the same field name, the
|
|
343
|
+
* same schema before and after, and the same enclosing object: two independent
|
|
344
|
+
* `limit` parameters removed from different objects are two findings, while one
|
|
345
|
+
* definition used at five places has the same enclosing object at all five.
|
|
346
|
+
*/
|
|
347
|
+
function say(w, rule, place, text, node, detail, groupAs) {
|
|
348
|
+
const field = place.replace(/( \([^()]*(?:\([^()]*\)[^()]*)*\))+$/, '').split('.').pop();
|
|
349
|
+
// groupAs: findings that are one change wherever they're found in the tool,
|
|
350
|
+
// whatever the field (additionalProperties: false dropped from every object).
|
|
351
|
+
const group = groupAs ?? [rule, text, field, digest(node), w.scope ?? '', digest(detail)].join('\u0000');
|
|
352
|
+
w.out.push({ rule, tool: w.tool, message: place + text, place, text, group, ...(detail ? { detail } : {}) });
|
|
353
|
+
}
|
|
354
|
+
/**
|
|
355
|
+
* One object schema against its next version: which properties were removed,
|
|
356
|
+
* added, or became required or optional; each one that's in both is compared by
|
|
357
|
+
* compareSchema, under a path (`gen.body.text`).
|
|
358
|
+
*/
|
|
359
|
+
function compareObject(outer, path, oldS, newS, depth) {
|
|
360
|
+
// Findings inside this object group only with findings inside one that accepts
|
|
361
|
+
// the same (descriptions aside: a $ref with its own description is the same
|
|
362
|
+
// definition).
|
|
363
|
+
const w = { ...outer, scope: digest([shape(oldS), shape(newS)]) };
|
|
364
|
+
const oldProps = oldS.properties ?? {};
|
|
365
|
+
const newProps = newS.properties ?? {};
|
|
366
|
+
const oldReq = new Set(oldS.required ?? []);
|
|
367
|
+
const newReq = new Set(newS.required ?? []);
|
|
368
|
+
const defaulted = (schema) => hasDefault(schema) ? ` It has a default (${show(schema.default)}), so the server may still accept calls without it, but clients that validate arguments won't.` : '';
|
|
143
369
|
// Removing an optional parameter only breaks callers if the new schema rejects
|
|
144
370
|
// unknown properties; otherwise calls that still send it stay valid.
|
|
145
|
-
const closed =
|
|
371
|
+
const closed = newS.additionalProperties === false;
|
|
372
|
+
// additionalProperties: false removed, or added (absent, true and {} are one
|
|
373
|
+
// spelling after expansion). zod 4 drops it from every object: one finding for
|
|
374
|
+
// the tool (collapsePlaces), and one line for the menu (collapseOpenings).
|
|
375
|
+
const wasClosed = oldS.additionalProperties === false;
|
|
376
|
+
if (wasClosed && newS.additionalProperties === undefined) {
|
|
377
|
+
say(w, 'diff/properties-opened', path, ` now accepts properties it doesn't list (additionalProperties: false removed).`, null, undefined, 'diff/properties-opened');
|
|
378
|
+
}
|
|
379
|
+
else if (!wasClosed && oldS.additionalProperties === undefined && closed) {
|
|
380
|
+
say(w, 'diff/properties-closed', path, ` now rejects properties it doesn't list (additionalProperties: false added). Calls that send one can fail.`, null, undefined, 'diff/properties-closed');
|
|
381
|
+
}
|
|
146
382
|
for (const p of Object.keys(oldProps)) {
|
|
147
|
-
if (
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
383
|
+
if (p in newProps)
|
|
384
|
+
continue;
|
|
385
|
+
if (oldReq.has(p) || closed)
|
|
386
|
+
say(w, 'diff/param-removed', `${path}.${p}`, ' was removed. Calls that pass it can fail.', oldProps[p]);
|
|
387
|
+
else
|
|
388
|
+
say(w, 'diff/param-dropped', `${path}.${p}`, ' (optional) was removed. Calls that still send it stay valid, but the server may ignore it.', oldProps[p]);
|
|
152
389
|
}
|
|
153
390
|
for (const [p, schema] of Object.entries(newProps)) {
|
|
154
391
|
const before = oldProps[p];
|
|
392
|
+
const at = `${path}.${p}`;
|
|
155
393
|
if (!before) {
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
394
|
+
if (newReq.has(p))
|
|
395
|
+
say(w, 'diff/param-required', at, ` is new and required. Existing calls don't send it.${defaulted(schema)}`, schema);
|
|
396
|
+
else
|
|
397
|
+
say(w, 'diff/param-added', at, ' is a new optional parameter.', schema);
|
|
159
398
|
continue;
|
|
160
399
|
}
|
|
161
|
-
if (!oldReq.has(p) && newReq.has(p))
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
400
|
+
if (!oldReq.has(p) && newReq.has(p))
|
|
401
|
+
say(w, 'diff/param-required', at, ` was optional and is now required.${defaulted(schema)}`, [before, schema]);
|
|
402
|
+
else if (oldReq.has(p) && !newReq.has(p))
|
|
403
|
+
say(w, 'diff/param-relaxed', at, ' was required and is now optional.', [before, schema]);
|
|
404
|
+
compareSchema(w, at, at, before, schema, depth);
|
|
405
|
+
}
|
|
406
|
+
}
|
|
407
|
+
/**
|
|
408
|
+
* One schema against its next version, anywhere in a tool: its type, allowed
|
|
409
|
+
* values and description; array items, object fields and union options, each
|
|
410
|
+
* compared the same way; and whatever's left, as one "review it". `at` is the path
|
|
411
|
+
* nested fields hang off (`gen.rows[]`); `label` names this schema in messages
|
|
412
|
+
* (`gen.rows (array items)`).
|
|
413
|
+
*/
|
|
414
|
+
function compareSchema(w, at, label, before, after, depth) {
|
|
415
|
+
// Past the limit, a change is said as such, not passed off as an unclassified one.
|
|
416
|
+
if (depth >= MAX_DEPTH) {
|
|
417
|
+
if (canonical(sameTypes(before)) !== canonical(sameTypes(after))) {
|
|
418
|
+
say(w, 'diff/schema-other', label, `: changed more than ${MAX_DEPTH} levels deep, below where toolmenu compares field by field. Review it.`, [before, after]);
|
|
166
419
|
}
|
|
167
|
-
|
|
168
|
-
|
|
420
|
+
return;
|
|
421
|
+
}
|
|
422
|
+
const oldOptions = unionOf(before);
|
|
423
|
+
const newOptions = unionOf(after);
|
|
424
|
+
// anyOf/oneOf whose options are more than a type: zod's unions, discriminated
|
|
425
|
+
// unions, and .nullable() on anything but a primitive. A side that isn't a union
|
|
426
|
+
// is one option.
|
|
427
|
+
const union = oldOptions !== undefined || newOptions !== undefined;
|
|
428
|
+
const oldType = typeOf(before);
|
|
429
|
+
const newType = typeOf(after);
|
|
430
|
+
if (union) {
|
|
431
|
+
// The plain side's description is the node's, compared below, not an option's.
|
|
432
|
+
compareUnion(w, at, label, optionsOf(before), optionsOf(after), depth);
|
|
433
|
+
}
|
|
434
|
+
else {
|
|
169
435
|
if (oldType !== newType) {
|
|
170
436
|
// Widening (boolean → boolean|string, object → any) accepts every call that
|
|
171
437
|
// worked before; only a narrower or different type breaks callers.
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
438
|
+
if (accepts(after, before))
|
|
439
|
+
say(w, 'diff/type-widened', label, ` now accepts more types: ${oldType || 'any'} → ${newType || 'any'}.`, [before, after]);
|
|
440
|
+
else
|
|
441
|
+
say(w, 'diff/param-type', label, ` changed type: ${oldType || 'any'} → ${newType || 'any'}. Calls that worked before can fail.`, [before, after]);
|
|
175
442
|
}
|
|
176
|
-
const e = enumChange(before,
|
|
177
|
-
if (e)
|
|
178
|
-
|
|
443
|
+
const e = enumChange(before, after);
|
|
444
|
+
if (e)
|
|
445
|
+
say(w, e.rule, label, `: ${e.message}`, [before, after]);
|
|
446
|
+
}
|
|
447
|
+
// Array items: compared like a parameter of their own (no items schema = any element).
|
|
448
|
+
const isArray = (s) => typesOf(s)?.includes('array') ?? false;
|
|
449
|
+
const arrays = !union && isArray(before) && isArray(after);
|
|
450
|
+
if (arrays)
|
|
451
|
+
compareSchema(w, `${at}[]`, `${label} (array items)`, before.items ?? {}, after.items ?? {}, depth + 1);
|
|
452
|
+
const [da, db] = [describedAs(before), describedAs(after)];
|
|
453
|
+
if (da !== db) {
|
|
454
|
+
say(w, 'diff/description', label, `: ${label.endsWith(')') ? 'description' : 'parameter description'} changed.`, [before, after], textDiff(da, db));
|
|
455
|
+
}
|
|
456
|
+
const object = !union && hasProperties(before) && hasProperties(after);
|
|
457
|
+
if (object)
|
|
458
|
+
compareObject(w, at, before, after, depth + 1);
|
|
459
|
+
// What no rule above covers. A breaking type change already covers a reshaped
|
|
460
|
+
// schema: no duplicate notice. A widened type can still bring new constraints.
|
|
461
|
+
// A union against a plain schema is covered by its options entirely.
|
|
462
|
+
if (union && !(oldOptions && newOptions))
|
|
463
|
+
return;
|
|
464
|
+
const rest = (s) => residual(s, { object, items: arrays, union });
|
|
465
|
+
if ((union || oldType === newType || accepts(after, before)) && canonical(rest(before)) !== canonical(rest(after))) {
|
|
466
|
+
say(w, 'diff/schema-other', label, `: changed in a way toolmenu doesn't classify (constraints, formats, combinators…). Review it.`, [before, after]);
|
|
467
|
+
}
|
|
468
|
+
}
|
|
469
|
+
/**
|
|
470
|
+
* A schema as a list of union options, when the other side is a union: its own
|
|
471
|
+
* anyOf/oneOf options if it has any (one option, or type-only ones, included),
|
|
472
|
+
* else itself, without its description (that's the node's, compared as the
|
|
473
|
+
* node's), as the one option.
|
|
474
|
+
*/
|
|
475
|
+
function optionsOf(s) {
|
|
476
|
+
const options = unionOptions(s);
|
|
477
|
+
return options && options.length > 0 ? options : [undescribed(s)];
|
|
478
|
+
}
|
|
479
|
+
/**
|
|
480
|
+
* What a schema says about itself: its description, or, for a type written as
|
|
481
|
+
* anyOf/oneOf alternatives, the descriptions its options carry. Sentry writes a
|
|
482
|
+
* nullable string as anyOf [{type: string, description}, {type: null}]; a
|
|
483
|
+
* description moved from the option to the node is the same one.
|
|
484
|
+
*/
|
|
485
|
+
function describedAs(s) {
|
|
486
|
+
const own = typeof s.description === 'string' ? s.description : '';
|
|
487
|
+
if (!typeAlternatives(s))
|
|
488
|
+
return own;
|
|
489
|
+
// Its own text and its options', each once: a change to either is seen, even
|
|
490
|
+
// when the field has a description of its own (review of #15, sentry-both).
|
|
491
|
+
const texts = [own, ...(s.anyOf ?? s.oneOf).map((o) => (typeof o.description === 'string' ? o.description : ''))].filter(Boolean);
|
|
492
|
+
return [...new Set(texts)].join(' ');
|
|
493
|
+
}
|
|
494
|
+
/** The options of an anyOf/oneOf that isn't just a list of types. */
|
|
495
|
+
function unionOf(s) {
|
|
496
|
+
const options = unionOptions(s);
|
|
497
|
+
if (!options || options.length === 0 || typeAlternatives(s))
|
|
498
|
+
return undefined;
|
|
499
|
+
return options;
|
|
500
|
+
}
|
|
501
|
+
/**
|
|
502
|
+
* anyOf/oneOf options, with an option that is itself only a union (a $ref to
|
|
503
|
+
* one, expanded: Notion's `parent` is anyOf [parentRequest, string], and
|
|
504
|
+
* parentRequest is anyOf of objects) flattened into its options: the same values
|
|
505
|
+
* are accepted either way.
|
|
506
|
+
*/
|
|
507
|
+
function unionOptions(s) {
|
|
508
|
+
const options = (s.anyOf ?? s.oneOf);
|
|
509
|
+
if (!Array.isArray(options))
|
|
510
|
+
return undefined;
|
|
511
|
+
return options.flatMap((o) => {
|
|
512
|
+
const inner = o && typeof o === 'object' ? (o.anyOf ?? o.oneOf) : undefined;
|
|
513
|
+
const pure = Array.isArray(inner) && Object.keys(o).every((k) => k === 'anyOf' || k === 'oneOf' || DESCRIPTIVE.has(k));
|
|
514
|
+
return pure ? (unionOptions(o) ?? [o]) : [o];
|
|
515
|
+
});
|
|
516
|
+
}
|
|
517
|
+
/**
|
|
518
|
+
* A schema with the spellings that accept the same input written one way, the ones
|
|
519
|
+
* schema generators switch between (zod 3 → 4 did both in chrome-devtools-mcp
|
|
520
|
+
* 1.9.0 → 1.10.1, 61 "review it"s): `additionalProperties: {}` is `true`, and an
|
|
521
|
+
* integer's `maximum: 2^53 − 1` / `minimum: −(2^53 − 1)` (zod 4 adds them to every
|
|
522
|
+
* `.int()`) exclude nothing a call can send.
|
|
523
|
+
*/
|
|
524
|
+
function unspelled(node) {
|
|
525
|
+
if (Array.isArray(node))
|
|
526
|
+
return node.map(unspelled);
|
|
527
|
+
if (!node || typeof node !== 'object')
|
|
528
|
+
return node;
|
|
529
|
+
const s = node;
|
|
530
|
+
const out = Object.fromEntries(Object.entries(s).map(([k, v]) => [k, SCHEMA_MAPS.has(k) && v && typeof v === 'object' && !Array.isArray(v) ? mapValues(v, unspelled) : unspelled(v)]));
|
|
531
|
+
// additionalProperties absent, true and {} all allow any extra property: written
|
|
532
|
+
// as absent. false stays (compareObject says when it comes or goes).
|
|
533
|
+
const a = out.additionalProperties;
|
|
534
|
+
if (a === true || (a && typeof a === 'object' && !Array.isArray(a) && Object.keys(a).length === 0))
|
|
535
|
+
delete out.additionalProperties;
|
|
536
|
+
// Property names are strings anyway (zod 4 adds this to z.record).
|
|
537
|
+
const names = out.propertyNames;
|
|
538
|
+
if (names && typeof names === 'object' && Object.keys(names).length === 1 && names.type === 'string')
|
|
539
|
+
delete out.propertyNames;
|
|
540
|
+
const integer = s.type === 'integer' || (Array.isArray(s.type) && s.type.includes('integer'));
|
|
541
|
+
if (integer && out.maximum === Number.MAX_SAFE_INTEGER)
|
|
542
|
+
delete out.maximum;
|
|
543
|
+
if (integer && out.minimum === Number.MIN_SAFE_INTEGER)
|
|
544
|
+
delete out.minimum;
|
|
545
|
+
return out;
|
|
546
|
+
}
|
|
547
|
+
/** A schema without its description, for comparing it as one option among others. */
|
|
548
|
+
function undescribed(s) {
|
|
549
|
+
const { description: _d, ...rest } = s;
|
|
550
|
+
return rest;
|
|
551
|
+
}
|
|
552
|
+
/**
|
|
553
|
+
* A union's options, paired old with new (pairOptions), each pair compared like
|
|
554
|
+
* any schema. An option gone is breaking; a new one widens.
|
|
555
|
+
*/
|
|
556
|
+
function compareUnion(outer, at, label, oldOptions, newOptions, depth) {
|
|
557
|
+
// Findings about the union, and inside its options, group by the union itself:
|
|
558
|
+
// one union definition shared by fields of different objects (a heading's
|
|
559
|
+
// content and a table cell's) is one change, whatever the objects around it.
|
|
560
|
+
const w = { ...outer, scope: digest([shape(oldOptions), shape(newOptions)]) };
|
|
561
|
+
const d = discriminator(oldOptions);
|
|
562
|
+
const key = d && d === discriminator(newOptions) ? d : undefined;
|
|
563
|
+
const { pairs, gone, fresh } = pairOptions(oldOptions, newOptions, key);
|
|
564
|
+
const oldLabels = optionLabels(oldOptions, key);
|
|
565
|
+
const newLabels = optionLabels(newOptions, key);
|
|
566
|
+
for (const o of gone)
|
|
567
|
+
say(w, 'diff/param-type', label, `: no longer accepts the ${oldLabels.get(o)} option. Calls that sent it can fail.`, o);
|
|
568
|
+
for (const o of fresh)
|
|
569
|
+
say(w, 'diff/type-widened', label, ` now also accepts ${article(newLabels.get(o))} ${newLabels.get(o)} option.`, o);
|
|
570
|
+
for (const [prev, next] of pairs) {
|
|
571
|
+
const k = newLabels.get(next);
|
|
572
|
+
compareSchema(w, `${at}(${k})`, `${label} (${k} option)`, prev, next, depth + 1);
|
|
573
|
+
}
|
|
574
|
+
}
|
|
575
|
+
function article(word) {
|
|
576
|
+
return /^[aeiou]/i.test(word) ? 'an' : 'a';
|
|
577
|
+
}
|
|
578
|
+
/**
|
|
579
|
+
* Which old option became which new one. With a discriminator every option fixes
|
|
580
|
+
* (`kind: "text"`), by its value. Without one (a plain z.union of objects, an
|
|
581
|
+
* option that's an unexpanded $ref): identical options first, so a reorder or an
|
|
582
|
+
* option added in front changes nothing else; then options of the same type,
|
|
583
|
+
* objects by how many property names they share, best match first. An object
|
|
584
|
+
* option that shares no property name with any other is gone or new, not a
|
|
585
|
+
* reshaped one. Pairs come back in the new schema's order.
|
|
586
|
+
*/
|
|
587
|
+
function pairOptions(oldOptions, newOptions, key) {
|
|
588
|
+
const oldLeft = new Set(oldOptions.keys());
|
|
589
|
+
const newLeft = new Set(newOptions.keys());
|
|
590
|
+
const pairs = [];
|
|
591
|
+
const take = (i, j) => {
|
|
592
|
+
pairs.push([i, j]);
|
|
593
|
+
oldLeft.delete(i);
|
|
594
|
+
newLeft.delete(j);
|
|
595
|
+
};
|
|
596
|
+
// Old options by fingerprint, each computed once: matching is a lookup, not a
|
|
597
|
+
// scan (a 1,500-option union took 36 s).
|
|
598
|
+
const match = (fingerprint) => {
|
|
599
|
+
const byPrint = new Map();
|
|
600
|
+
oldOptions.forEach((o, i) => {
|
|
601
|
+
if (!oldLeft.has(i))
|
|
602
|
+
return;
|
|
603
|
+
const f = fingerprint(o);
|
|
604
|
+
byPrint.set(f, [...(byPrint.get(f) ?? []), i]);
|
|
605
|
+
});
|
|
606
|
+
for (const j of newOptions.keys()) {
|
|
607
|
+
if (!newLeft.has(j))
|
|
608
|
+
continue;
|
|
609
|
+
const i = byPrint.get(fingerprint(newOptions[j]))?.shift();
|
|
610
|
+
if (i !== undefined)
|
|
611
|
+
take(i, j);
|
|
179
612
|
}
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
613
|
+
};
|
|
614
|
+
if (key) {
|
|
615
|
+
// An option that's a $ref (unexpanded: a recursive one) has no discriminator
|
|
616
|
+
// value of its own: it pairs by its ref.
|
|
617
|
+
match((o) => (typeof o.$ref === 'string' ? `$ref ${o.$ref}` : canonical(fixedValue(o.properties?.[key]))));
|
|
618
|
+
}
|
|
619
|
+
else {
|
|
620
|
+
match((o) => canonical(sameTypes(o)));
|
|
621
|
+
const names = new Map([...oldOptions, ...newOptions].map((o) => [o, new Set(Object.keys(o.properties ?? {}))]));
|
|
622
|
+
const types = new Map([...oldOptions, ...newOptions].map((o) => [o, typeOf(o)]));
|
|
623
|
+
const candidates = [];
|
|
624
|
+
for (const i of oldLeft) {
|
|
625
|
+
for (const j of newLeft) {
|
|
626
|
+
const [a, b] = [oldOptions[i], newOptions[j]];
|
|
627
|
+
if (types.get(a) !== types.get(b))
|
|
628
|
+
continue;
|
|
629
|
+
let score = 0.5;
|
|
630
|
+
if (hasProperties(a) || hasProperties(b)) {
|
|
631
|
+
const [x, y] = [names.get(a), names.get(b)];
|
|
632
|
+
const all = new Set([...x, ...y]).size;
|
|
633
|
+
// Two objects with no properties at all have the same shape.
|
|
634
|
+
score = all === 0 ? 1 : [...x].filter((n) => y.has(n)).length / all;
|
|
635
|
+
}
|
|
636
|
+
if (score > 0)
|
|
637
|
+
candidates.push([score, i, j]);
|
|
192
638
|
}
|
|
193
|
-
const ie = enumChange(oldItems, newItems);
|
|
194
|
-
if (ie)
|
|
195
|
-
out.push({ rule: ie.rule, tool: name, message: `${name}.${p} (array items): ${ie.message}` });
|
|
196
|
-
}
|
|
197
|
-
if ((before.description ?? '') !== (schema.description ?? '')) {
|
|
198
|
-
out.push({ rule: 'diff/description', tool: name, message: `${name}.${p}: parameter description changed.`, detail: textDiff(String(before.description ?? ''), String(schema.description ?? '')) });
|
|
199
639
|
}
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
640
|
+
candidates.sort((p, q) => q[0] - p[0] || p[1] - q[1] || p[2] - q[2]);
|
|
641
|
+
for (const [, i, j] of candidates)
|
|
642
|
+
if (oldLeft.has(i) && newLeft.has(j))
|
|
643
|
+
take(i, j);
|
|
644
|
+
// As many options left on each side: the ones that were edited (a type
|
|
645
|
+
// changed, an option emptied or given its first field). Paired in order,
|
|
646
|
+
// compared inside, rather than said as one removed and one added. Not two
|
|
647
|
+
// objects that each have fields and share none: that's one option replaced by
|
|
648
|
+
// another (pair-replace in the review of #15).
|
|
649
|
+
if (oldLeft.size > 0 && oldLeft.size === newLeft.size) {
|
|
650
|
+
const [olds, news] = [[...oldLeft].sort((a, b) => a - b), [...newLeft].sort((a, b) => a - b)];
|
|
651
|
+
const filled = (o) => names.get(o).size > 0;
|
|
652
|
+
olds.forEach((i, n) => {
|
|
653
|
+
if (!(filled(oldOptions[i]) && filled(newOptions[news[n]])))
|
|
654
|
+
take(i, news[n]);
|
|
655
|
+
});
|
|
206
656
|
}
|
|
207
657
|
}
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
658
|
+
pairs.sort((p, q) => p[1] - q[1]);
|
|
659
|
+
return {
|
|
660
|
+
pairs: pairs.map(([i, j]) => [oldOptions[i], newOptions[j]]),
|
|
661
|
+
gone: [...oldLeft].map((i) => oldOptions[i]),
|
|
662
|
+
fresh: [...newLeft].sort((a, b) => a - b).map((j) => newOptions[j]),
|
|
663
|
+
};
|
|
664
|
+
}
|
|
665
|
+
/**
|
|
666
|
+
* Each option's name in messages and paths: its discriminator value, or its shape
|
|
667
|
+
* (`object{path,url}`, the first three property names). Two options that would
|
|
668
|
+
* share a name get all their property names, then a number.
|
|
669
|
+
*/
|
|
670
|
+
function optionLabels(options, key) {
|
|
671
|
+
const label = (o, all) => {
|
|
672
|
+
if (key && hasProperties(o))
|
|
673
|
+
return `${key}=${JSON.stringify(fixedValue(o.properties[key]))}`;
|
|
674
|
+
if (typeof o.$ref === 'string')
|
|
675
|
+
return `$ref ${o.$ref}`;
|
|
676
|
+
const type = typeOf(o) || 'untyped';
|
|
677
|
+
if (!hasProperties(o))
|
|
678
|
+
return type;
|
|
679
|
+
const names = Object.keys(o.properties).sort();
|
|
680
|
+
return all || names.length <= 3 ? `${type}{${names.join(',')}}` : `${type}{${names.slice(0, 3).join(',')},…}`;
|
|
211
681
|
};
|
|
212
|
-
|
|
213
|
-
|
|
682
|
+
const short = options.map((o) => label(o, false));
|
|
683
|
+
const named = options.map((o, i) => (short.filter((s) => s === short[i]).length > 1 ? label(o, true) : short[i]));
|
|
684
|
+
const seen = new Map();
|
|
685
|
+
return new Map(options.map((o, i) => {
|
|
686
|
+
const n = (seen.get(named[i]) ?? 0) + 1;
|
|
687
|
+
seen.set(named[i], n);
|
|
688
|
+
return [o, named.filter((s) => s === named[i]).length > 1 ? `${named[i]} #${n}` : named[i]];
|
|
689
|
+
}));
|
|
690
|
+
}
|
|
691
|
+
/**
|
|
692
|
+
* The same change, said at several places of one tool (a shared definition five
|
|
693
|
+
* block types use), as one finding that lists them: one change, one line, the
|
|
694
|
+
* same classification everywhere.
|
|
695
|
+
*/
|
|
696
|
+
function collapsePlaces(out, from) {
|
|
697
|
+
const groups = new Map();
|
|
698
|
+
for (const r of out.slice(from)) {
|
|
699
|
+
if (r.group === undefined)
|
|
700
|
+
continue;
|
|
701
|
+
groups.set(r.group, [...(groups.get(r.group) ?? []), r]);
|
|
702
|
+
}
|
|
703
|
+
for (const list of groups.values()) {
|
|
704
|
+
if (list.length < 2)
|
|
705
|
+
continue;
|
|
706
|
+
const [first, ...rest] = list;
|
|
707
|
+
// Same field, same schema, in identical enclosing objects: one definition,
|
|
708
|
+
// reached from several places.
|
|
709
|
+
first.message = `${first.place}${first.text} The same change at ${rest.length} more place${rest.length === 1 ? '' : 's'}, in the same definition.`;
|
|
710
|
+
first.detail = [...(first.detail ?? []), ...rest.slice(0, 10).map((r) => `also at ${r.place}`), ...(rest.length > 10 ? [`…and ${rest.length - 10} more`] : [])];
|
|
711
|
+
first.places = list.map((r) => r.place);
|
|
712
|
+
for (const r of rest)
|
|
713
|
+
out.splice(out.indexOf(r), 1);
|
|
714
|
+
}
|
|
715
|
+
for (const r of out.slice(from)) {
|
|
716
|
+
delete r.place;
|
|
717
|
+
delete r.text;
|
|
718
|
+
delete r.group;
|
|
719
|
+
}
|
|
720
|
+
}
|
|
721
|
+
/** A property every option is an object with, and fixes to one value. */
|
|
722
|
+
function discriminator(options) {
|
|
723
|
+
// A $ref option (a recursive definition left unexpanded) says nothing either way.
|
|
724
|
+
const own = options.filter((o) => typeof o.$ref !== 'string');
|
|
725
|
+
if (own.length === 0 || !own.every(hasProperties))
|
|
726
|
+
return undefined;
|
|
727
|
+
const names = Object.keys(own[0].properties).sort();
|
|
728
|
+
return names.find((n) => own.every((o) => fixedValue(o.properties[n]) !== undefined));
|
|
729
|
+
}
|
|
730
|
+
function fixedValue(s) {
|
|
731
|
+
if (!s)
|
|
732
|
+
return undefined;
|
|
733
|
+
if ('const' in s)
|
|
734
|
+
return s.const;
|
|
735
|
+
return Array.isArray(s.enum) && s.enum.length === 1 ? s.enum[0] : undefined;
|
|
736
|
+
}
|
|
737
|
+
function hasProperties(s) {
|
|
738
|
+
return !!s && typeof s.properties === 'object' && s.properties !== null && !Array.isArray(s.properties);
|
|
739
|
+
}
|
|
740
|
+
/** Nodes a $ref expansion may produce before it gives up and compares the schema as spelled. */
|
|
741
|
+
const MAX_EXPANDED_NODES = 50_000;
|
|
742
|
+
/** How many times one $ref is followed inside itself: a recursive schema unrolled this deep. */
|
|
743
|
+
const MAX_UNROLL = 1;
|
|
744
|
+
/**
|
|
745
|
+
* The schema with local $refs (`#/$defs/…`, `#/definitions/…`) replaced by what
|
|
746
|
+
* they point to, and the root $defs dropped: two spellings of one schema compare
|
|
747
|
+
* equal. A recursive definition is unrolled MAX_UNROLL level, then left as a
|
|
748
|
+
* $ref: a change to it shows in the levels above, and its $defs entry needn't be
|
|
749
|
+
* kept (keeping it made a recursive schema compare unequal to its own refactor,
|
|
750
|
+
* with nothing reported). A $ref toolmenu can't follow (another document) stays as
|
|
751
|
+
* it is. Keywords next to a $ref (a description) win over the target's.
|
|
752
|
+
*/
|
|
753
|
+
export function resolveRefs(schema) {
|
|
754
|
+
return expandRefs(schema).schema;
|
|
755
|
+
}
|
|
756
|
+
/**
|
|
757
|
+
* resolveRefs, saying whether it finished: past MAX_EXPANDED_NODES the schema
|
|
758
|
+
* comes back as written, and `expanded` is false.
|
|
759
|
+
*/
|
|
760
|
+
function expandRefs(schema) {
|
|
761
|
+
if (!schema || typeof schema !== 'object')
|
|
762
|
+
return { schema, expanded: true };
|
|
763
|
+
let nodes = 0;
|
|
764
|
+
const pointer = (ref) => {
|
|
765
|
+
let node = schema;
|
|
766
|
+
for (const raw of ref.slice(2).split('/')) {
|
|
767
|
+
if (!node || typeof node !== 'object')
|
|
768
|
+
return undefined;
|
|
769
|
+
node = node[decodeURIComponent(raw).replace(/~1/g, '/').replace(/~0/g, '~')];
|
|
770
|
+
}
|
|
771
|
+
return node;
|
|
772
|
+
};
|
|
773
|
+
const walk = (node, stack) => {
|
|
774
|
+
if (++nodes > MAX_EXPANDED_NODES)
|
|
775
|
+
throw new Error('too large');
|
|
776
|
+
if (Array.isArray(node))
|
|
777
|
+
return node.map((x) => walk(x, stack));
|
|
778
|
+
if (!node || typeof node !== 'object')
|
|
779
|
+
return node;
|
|
780
|
+
const o = node;
|
|
781
|
+
if (typeof o.$ref === 'string') {
|
|
782
|
+
const target = o.$ref.startsWith('#/') ? pointer(o.$ref) : undefined;
|
|
783
|
+
if (target && typeof target === 'object' && !Array.isArray(target) && stack.filter((r) => r === o.$ref).length < MAX_UNROLL) {
|
|
784
|
+
const { $ref: _ref, ...siblings } = o;
|
|
785
|
+
return { ...walk(target, [...stack, o.$ref]), ...walk(siblings, stack) };
|
|
786
|
+
}
|
|
787
|
+
}
|
|
788
|
+
return Object.fromEntries(Object.entries(o).map(([k, v]) => [k, walk(v, stack)]));
|
|
789
|
+
};
|
|
790
|
+
const { $defs: _defs, definitions: _definitions, ...rest } = schema;
|
|
791
|
+
try {
|
|
792
|
+
return { schema: unspelled(walk(rest, [])), expanded: true };
|
|
793
|
+
}
|
|
794
|
+
catch {
|
|
795
|
+
return { schema, expanded: false };
|
|
214
796
|
}
|
|
215
|
-
return out.concat(compareRest(old, t));
|
|
216
797
|
}
|
|
217
798
|
/** Operations behind a search tool, compared like tools where both runs found them. */
|
|
218
799
|
function compareCatalogs(before, after, ignored) {
|
|
@@ -316,10 +897,11 @@ function findRenames(removed, added) {
|
|
|
316
897
|
return pairs;
|
|
317
898
|
}
|
|
318
899
|
function paramKey(t) {
|
|
319
|
-
const
|
|
900
|
+
const schema = resolveRefs(t.inputSchema);
|
|
901
|
+
const props = Object.keys(schema?.properties ?? {}).sort();
|
|
320
902
|
if (props.length === 0)
|
|
321
903
|
return undefined;
|
|
322
|
-
return canonical({ props: Object.fromEntries(props.map((p) => [p, typeOf(
|
|
904
|
+
return canonical({ props: Object.fromEntries(props.map((p) => [p, typeOf(schema.properties[p])])), required: [...(schema?.required ?? [])].sort() });
|
|
323
905
|
}
|
|
324
906
|
/** Does `next` accept every value type that `prev` accepted? */
|
|
325
907
|
function accepts(next, prev) {
|
|
@@ -335,16 +917,27 @@ function accepts(next, prev) {
|
|
|
335
917
|
return false;
|
|
336
918
|
return [...p].every((t) => n.has(t) || (t === 'integer' && n.has('number')));
|
|
337
919
|
}
|
|
338
|
-
/**
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
920
|
+
/**
|
|
921
|
+
* A parameter's schema without the parts diff classifies itself: with `object`,
|
|
922
|
+
* its properties, required list and additionalProperties: false (compareObject);
|
|
923
|
+
* with `items`, its array items; with `union`, its options.
|
|
924
|
+
*/
|
|
925
|
+
function residual(schema, nested = {}) {
|
|
926
|
+
const { type: _t, enum: _e, const: _c, description: _d, ...rest } = schema;
|
|
927
|
+
// A type written as anyOf/oneOf alternatives is compared as the type; a union's
|
|
928
|
+
// options are compared one by one.
|
|
929
|
+
if (typeAlternatives(schema) || nested.union) {
|
|
930
|
+
delete rest.anyOf;
|
|
931
|
+
delete rest.oneOf;
|
|
347
932
|
}
|
|
933
|
+
if (nested.object) {
|
|
934
|
+
delete rest.properties;
|
|
935
|
+
delete rest.required;
|
|
936
|
+
if (rest.additionalProperties === false)
|
|
937
|
+
delete rest.additionalProperties;
|
|
938
|
+
}
|
|
939
|
+
if (nested.items)
|
|
940
|
+
delete rest.items;
|
|
348
941
|
return rest;
|
|
349
942
|
}
|
|
350
943
|
function typeOf(schema) {
|
|
@@ -375,9 +968,15 @@ function typeAlternatives(schema) {
|
|
|
375
968
|
}
|
|
376
969
|
return types;
|
|
377
970
|
}
|
|
971
|
+
/** The values a schema limits itself to: its enum, or a const as a one-value enum. */
|
|
972
|
+
function allowedValues(schema) {
|
|
973
|
+
if (Array.isArray(schema.enum))
|
|
974
|
+
return schema.enum;
|
|
975
|
+
return 'const' in schema ? [schema.const] : undefined;
|
|
976
|
+
}
|
|
378
977
|
function enumChange(before, after) {
|
|
379
|
-
const a = before
|
|
380
|
-
const b = after
|
|
978
|
+
const a = allowedValues(before);
|
|
979
|
+
const b = allowedValues(after);
|
|
381
980
|
if (!a && !b)
|
|
382
981
|
return undefined;
|
|
383
982
|
if (!a && b)
|