toolmenu 0.11.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/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
- const oldEmpty = isEmptySchema(old.inputSchema);
128
- const newEmpty = isEmptySchema(t.inputSchema);
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(old.inputSchema) !== canonical(t.inputSchema)) {
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 oldProps = old.inputSchema?.properties ?? {};
140
- const newProps = t.inputSchema?.properties ?? {};
141
- const oldReq = new Set(old.inputSchema?.required ?? []);
142
- const newReq = new Set(t.inputSchema?.required ?? []);
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 = t.inputSchema?.additionalProperties === false;
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 (!(p in newProps)) {
148
- out.push(oldReq.has(p) || closed
149
- ? { rule: 'diff/param-removed', tool: name, message: `${name}.${p} was removed. Calls that pass it can fail.` }
150
- : { rule: 'diff/param-dropped', tool: name, message: `${name}.${p} (optional) was removed. Calls that still send it stay valid, but the server may ignore it.` });
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
- out.push(newReq.has(p)
157
- ? { rule: 'diff/param-required', tool: name, message: `${name}.${p} is new and required. Existing calls don't send it.${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.` : ''}` }
158
- : { rule: 'diff/param-added', tool: name, message: `${name}.${p} is a new optional parameter.` });
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
- out.push({ rule: 'diff/param-required', tool: name, message: `${name}.${p} was optional and is now required.${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.` : ''}` });
163
- }
164
- else if (oldReq.has(p) && !newReq.has(p)) {
165
- out.push({ rule: 'diff/param-relaxed', tool: name, message: `${name}.${p} was required and is now optional.` });
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
- const oldType = typeOf(before);
168
- const newType = typeOf(schema);
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
- out.push(accepts(schema, before)
173
- ? { rule: 'diff/type-widened', tool: name, message: `${name}.${p} now accepts more types: ${oldType || 'any'} → ${newType || 'any'}.` }
174
- : { rule: 'diff/param-type', tool: name, message: `${name}.${p} changed type: ${oldType || 'any'} → ${newType || 'any'}. Calls that worked before can fail.` });
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, schema);
177
- if (e) {
178
- out.push({ rule: e.rule, tool: name, message: `${name}.${p}: ${e.message}` });
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
- // Array parameters: the element type and allowed values count like the
181
- // parameter's own (no items schema = any element).
182
- const isArray = (s) => typesOf(s)?.includes('array') ?? false;
183
- if (isArray(before) && isArray(schema)) {
184
- const oldItems = before.items ?? {};
185
- const newItems = schema.items ?? {};
186
- const oldItemType = typeOf(oldItems);
187
- const newItemType = typeOf(newItems);
188
- if (oldItemType !== newItemType) {
189
- out.push(accepts(newItems, oldItems)
190
- ? { rule: 'diff/type-widened', tool: name, message: `${name}.${p} (array items) now accept more types: ${oldItemType || 'any'} → ${newItemType || 'any'}.` }
191
- : { rule: 'diff/param-type', tool: name, message: `${name}.${p} (array items) changed type: ${oldItemType || 'any'} → ${newItemType || 'any'}. Calls that worked before can fail.` });
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
- // Whatever changed beyond type, enum and description is checked per
201
- // parameter, so a classified change elsewhere can't hide it.
202
- // A breaking type change already covers a reshaped schema: no duplicate
203
- // notice. A widened type can still bring new constraints, so it's checked.
204
- if ((oldType === newType || accepts(schema, before)) && canonical(residual(before)) !== canonical(residual(schema))) {
205
- out.push({ rule: 'diff/schema-other', tool: name, message: `${name}.${p}: changed in a way toolmenu doesn't classify (nested fields, constraints…). Review it.` });
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
- const shell = (s) => {
209
- const { properties: _p, required: _r, ...rest } = (s ?? {});
210
- return rest;
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
- if (canonical(shell(old.inputSchema)) !== canonical(shell(t.inputSchema))) {
213
- out.push({ rule: 'diff/schema-other', tool: name, message: `${name}: inputSchema changed outside its parameters (additionalProperties, $defs…). Review it.` });
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 props = Object.keys(t.inputSchema?.properties ?? {}).sort();
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(t.inputSchema.properties[p])])), required: [...(t.inputSchema?.required ?? [])].sort() });
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
- /** A parameter's schema without the parts diff classifies itself. */
339
- function residual(schema) {
340
- const { type: _t, enum: _e, description: _d, items, ...rest } = schema;
341
- // A type written as anyOf/oneOf alternatives is compared as the type.
342
- if (typeAlternatives(schema))
343
- delete rest[schema.anyOf ? 'anyOf' : 'oneOf'];
344
- if (items && typeof items === 'object') {
345
- const { enum: _ie, type: _it, ...itemRest } = items;
346
- return Object.keys(itemRest).length ? { ...rest, items: itemRest } : rest;
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.enum;
380
- const b = after.enum;
978
+ const a = allowedValues(before);
979
+ const b = allowedValues(after);
381
980
  if (!a && !b)
382
981
  return undefined;
383
982
  if (!a && b)