toolmenu 0.12.0 → 0.14.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.
Files changed (63) hide show
  1. package/README.md +84 -23
  2. package/dist/args.d.ts +31 -5
  3. package/dist/args.js +91 -14
  4. package/dist/auth.d.ts +4 -2
  5. package/dist/auth.js +59 -21
  6. package/dist/auto.d.ts +80 -6
  7. package/dist/auto.js +255 -19
  8. package/dist/breakdown.d.ts +2 -0
  9. package/dist/breakdown.js +64 -19
  10. package/dist/catalog.d.ts +87 -10
  11. package/dist/catalog.js +415 -58
  12. package/dist/cli.js +170 -185
  13. package/dist/close.d.ts +8 -0
  14. package/dist/close.js +18 -0
  15. package/dist/config.d.ts +7 -1
  16. package/dist/config.js +17 -0
  17. package/dist/connect.d.ts +14 -0
  18. package/dist/connect.js +150 -16
  19. package/dist/diff.d.ts +23 -1
  20. package/dist/diff.js +574 -120
  21. package/dist/difference.d.ts +2 -0
  22. package/dist/difference.js +13 -12
  23. package/dist/explain.d.ts +113 -0
  24. package/dist/explain.js +461 -0
  25. package/dist/failures.d.ts +15 -0
  26. package/dist/failures.js +59 -2
  27. package/dist/help.d.ts +11 -0
  28. package/dist/help.js +205 -0
  29. package/dist/history.d.ts +13 -0
  30. package/dist/history.js +86 -6
  31. package/dist/init.d.ts +93 -2
  32. package/dist/init.js +508 -21
  33. package/dist/menu.js +10 -2
  34. package/dist/options.d.ts +141 -0
  35. package/dist/options.js +50 -0
  36. package/dist/report.d.ts +2 -2
  37. package/dist/report.js +305 -101
  38. package/dist/rules/description.d.ts +7 -2
  39. package/dist/rules/description.js +86 -42
  40. package/dist/rules/determinism.d.ts +4 -1
  41. package/dist/rules/determinism.js +175 -11
  42. package/dist/rules/gated.d.ts +7 -0
  43. package/dist/rules/gated.js +77 -0
  44. package/dist/rules/ids.d.ts +1 -1
  45. package/dist/rules/ids.js +9 -4
  46. package/dist/rules/index.d.ts +6 -0
  47. package/dist/rules/index.js +18 -6
  48. package/dist/rules/naming.d.ts +1 -1
  49. package/dist/rules/naming.js +91 -21
  50. package/dist/rules/rule.d.ts +25 -0
  51. package/dist/rules/rule.js +25 -1
  52. package/dist/rules/spec.d.ts +6 -0
  53. package/dist/rules/spec.js +56 -9
  54. package/dist/rules/write.d.ts +1 -1
  55. package/dist/rules/write.js +64 -14
  56. package/dist/session.d.ts +34 -9
  57. package/dist/session.js +525 -94
  58. package/dist/snapshot.d.ts +8 -2
  59. package/dist/snapshot.js +33 -2
  60. package/dist/types.d.ts +21 -0
  61. package/dist/words.d.ts +5 -0
  62. package/dist/words.js +14 -0
  63. package/package.json +2 -2
package/dist/diff.js CHANGED
@@ -20,6 +20,7 @@ export const DIFF_RULES = {
20
20
  'diff/description': { severity: 'info', class: 'notice' },
21
21
  'diff/param-dropped': { severity: 'info', class: 'notice' },
22
22
  'diff/schema-other': { severity: 'info', class: 'notice' },
23
+ 'diff/param-default': { severity: 'info', class: 'notice' },
23
24
  // Restructured ($ref, $defs) but accepts the same input: bytes and tokens changed.
24
25
  'diff/schema-equivalent': { severity: 'info', class: 'notice' },
25
26
  // Only the declared $schema dialect changed: one finding for the menu.
@@ -30,6 +31,9 @@ export const DIFF_RULES = {
30
31
  'diff/annotations': { severity: 'info', class: 'notice' },
31
32
  'diff/other': { severity: 'info', class: 'notice' },
32
33
  'diff/order': { severity: 'info', class: 'notice' },
34
+ // A tool lost a parameter and gained a required one with a close name: likely a
35
+ // rename. A hint next to the two breaking findings, not a change of its own.
36
+ 'diff/param-renamed': { severity: 'warn' },
33
37
  'diff/version-bump': { severity: 'warn' },
34
38
  'diff/version-backwards': { severity: 'warn' },
35
39
  'diff/token-budget': { severity: 'error' },
@@ -40,6 +44,12 @@ export const DIFF_RULES = {
40
44
  'diff/catalog-added': { severity: 'info' },
41
45
  'diff/catalog-queries': { severity: 'info' },
42
46
  };
47
+ /**
48
+ * In fixes: the release a breaking change should ship in. Resolved once the
49
+ * versions are known (resolveFixes): "release it as 2.0.0", or "ship it in a
50
+ * major release" when there are none to check.
51
+ */
52
+ const BREAKING_RELEASE = '\u0000breaking-release\u0000';
43
53
  export function diffMenus(before, after, options = {}) {
44
54
  const raw = [];
45
55
  // Ignored tools leave the comparison entirely, so they can't pair into a
@@ -55,13 +65,35 @@ export function diffMenus(before, after, options = {}) {
55
65
  const renamedFrom = new Set(renames.map((r) => r.from.name));
56
66
  const renamedTo = new Set(renames.map((r) => r.to.name));
57
67
  for (const { from, to } of renames) {
58
- raw.push({ rule: 'diff/tool-renamed', tool: to.name, message: `${from.name} was renamed to ${to.name} (same parameters). Agents, saved prompts and evals that call ${from.name} break.` });
68
+ raw.push({
69
+ rule: 'diff/tool-renamed',
70
+ tool: to.name,
71
+ message: `${code(from.name)} was renamed to ${code(to.name)} (same parameters). Agents, saved prompts and evals that call ${code(from.name)} now get an unknown-tool error.`,
72
+ fix: `Keep ${code(from.name)} as an alias for one release, or ${BREAKING_RELEASE}.`,
73
+ });
59
74
  }
60
75
  for (const t of removed.filter((t) => !renamedFrom.has(t.name))) {
61
- raw.push({ rule: 'diff/tool-removed', tool: t.name, message: `${t.name} was removed. Anything that calls it breaks.` });
76
+ raw.push({
77
+ rule: 'diff/tool-removed',
78
+ tool: t.name,
79
+ message: `${code(t.name)} was removed. Calls to it now fail with an unknown-tool error.`,
80
+ fix: `Keep the removed tool (marked deprecated in its description) for one release, or ${BREAKING_RELEASE}.`,
81
+ across: {
82
+ key: 'diff/tool-removed',
83
+ say: (count, list) => `${count} were removed: ${list}. Calls to them now fail with an unknown-tool error.`,
84
+ },
85
+ });
62
86
  }
63
87
  for (const t of added.filter((t) => !renamedTo.has(t.name))) {
64
- raw.push({ rule: 'diff/tool-added', tool: t.name, message: `${t.name} was added (~${t.tokens} tokens).` });
88
+ raw.push({
89
+ rule: 'diff/tool-added',
90
+ tool: t.name,
91
+ message: `${code(t.name)} is new (~${fmt(t.tokens)} tokens, estimate).`,
92
+ across: {
93
+ key: 'diff/tool-added',
94
+ say: (count, list, members) => `${count} are new (~${fmt(members.reduce((n, m) => n + (newByName.get(m.tool)?.tokens ?? 0), 0))} tokens together, estimate): ${list}.`,
95
+ },
96
+ });
65
97
  }
66
98
  for (const t of newTools) {
67
99
  const old = oldByName.get(t.name);
@@ -72,25 +104,35 @@ export function diffMenus(before, after, options = {}) {
72
104
  raw.push(...compareTool(from, to).filter((f) => f.rule !== 'diff/description' && f.rule !== 'diff/other'));
73
105
  collapseDialects(raw);
74
106
  collapseMenuWide(raw);
75
- const moved = compareMenus(oldTools, newTools).filter((c) => c.kind === 'moved');
107
+ // A session's union menu is in unlock order, which no client was served: no order to compare.
108
+ const unordered = before.from === 'session' || after.from === 'session';
109
+ const moved = unordered ? [] : compareMenus(oldTools, newTools).filter((c) => c.kind === 'moved');
76
110
  if (moved.length) {
111
+ const names = moved.map((m) => m.tool);
77
112
  raw.push({
78
113
  rule: 'diff/order',
79
- message: `Tool order changed (${moved.map((m) => m.tool).join(', ')}). Only a notice between releases: prompt caches are short-lived, so a deploy costs roughly one rewrite. It matters within a session.`,
114
+ message: `The tool order changed: ${names.length === 1 ? `${code(names[0])} moved` : `${names.length} tools moved (${shortList(names)})`}. A new order rewrites the prompt cache once per deploy, so between releases it's only a notice; within a session it matters.`,
115
+ ...(names.length > LIST_SHORT ? { detail: [`moved: ${names.join(', ')}`] } : {}),
80
116
  });
81
117
  }
82
118
  raw.push(...compareCatalogs(before.catalog, after.catalog, ignored));
83
119
  // Ignored tools leave the token counts and the budget too.
84
120
  const tokens = tokenChange(oldTools, newTools);
85
121
  if (options.tokenBudget !== undefined && tokens.after > options.tokenBudget) {
122
+ const grew = tokens.tools.filter((t) => t.delta > 0).slice(0, 3);
86
123
  raw.push({
87
124
  rule: 'diff/token-budget',
88
- message: `The menu is ~${fmt(tokens.after)} tokens, over the budget of ${fmt(options.tokenBudget)} (estimate).`,
125
+ message: `The menu is ~${fmt(tokens.after)} tokens (estimate), ~${fmt(tokens.after - options.tokenBudget)} over the budget of ${fmt(options.tokenBudget)}. Every conversation that loads it pays that before its first message.`,
126
+ fix: grew.length
127
+ ? `Trim what grew most (${grew.map((t) => code(t.name)).join(', ')}), or raise tokenBudget in the config.`
128
+ : 'Trim the longest tool descriptions, or raise tokenBudget in the config.',
89
129
  });
90
130
  }
91
131
  // Only what survives ignore and 'off' counts toward the bump. Settled once:
92
- // the bump and the reported findings come from the same list.
93
- const changes = settle(raw, options);
132
+ // the bump and the reported findings come from the same list. Grouped after
133
+ // settling, so an ignored tool is never listed in a group.
134
+ const changes = groupAcrossTools(settle(raw, options), oldTools.length, newTools.length);
135
+ const classes = classCounts(changes);
94
136
  const suggestedBump = bumpFor(changes.map((f) => f.class));
95
137
  const versionRaw = [];
96
138
  const release = options.release
@@ -103,32 +145,146 @@ export function diffMenus(before, after, options = {}) {
103
145
  if (release && notChecked === 'version went backwards') {
104
146
  versionRaw.push({
105
147
  rule: 'diff/version-backwards',
106
- message: release.source === 'server'
107
- ? `The server-reported version went backwards: ${release.before} → ${release.after}.`
108
- : `${release.before} → ${release.after}: the version went backwards. Check the --release order.`,
109
- });
110
- }
111
- const required = requiredBump(suggestedBump, release?.before);
112
- if (release && actualBump && BUMP_RANK[actualBump] < BUMP_RANK[required]) {
113
- const what = release.source === 'server' ? 'The server-reported version' : 'The release version';
114
- versionRaw.push({
115
- rule: 'diff/version-bump',
116
- message: actualBump === 'none'
117
- ? `${what} stayed ${release.after} but the menu has ${suggestedBump === 'major' ? 'breaking' : suggestedBump === 'minor' ? 'new' : 'changed'} parts. Suggested: a ${required} bump.`
118
- : `${release.before} → ${release.after} is a ${actualBump} bump, but the menu has ${suggestedBump === 'major' ? 'breaking changes' : 'new features'}. Suggested: a ${required} bump.`,
148
+ message: `The ${release.source === 'server' ? 'server-reported' : 'release'} version went backwards (${release.before} → ${release.after}), so the bump can't be checked.`,
149
+ fix: release.source === 'server' ? 'Pass the release versions with --release old..new.' : 'Pass --release as old..new, the older release first.',
119
150
  });
120
151
  }
152
+ const required = release && actualBump ? requiredBump(suggestedBump, release.before) : undefined;
153
+ const short = release && actualBump && required && BUMP_RANK[actualBump] < BUMP_RANK[required];
154
+ if (short)
155
+ versionRaw.push(bumpFinding(release, actualBump, required, suggestedBump, classes));
156
+ resolveFixes(changes, release && required ? (short ? nextVersion(release.before, required) : 'enough') : undefined);
121
157
  return {
122
158
  before: before.server,
123
159
  after: after.server,
124
- findings: [...changes, ...settle(versionRaw, options)].sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]),
160
+ findings: [...changes, ...settle(versionRaw, options)].map(finished).sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]),
125
161
  tokens,
162
+ classes,
126
163
  suggestedBump,
164
+ ...(required ? { requiredBump: required } : {}),
127
165
  ...(actualBump ? { actualBump } : {}),
166
+ ...(short ? { releaseAs: nextVersion(release.before, required) } : {}),
128
167
  ...(release ? { release } : {}),
129
168
  ...(notChecked ? { bumpNotChecked: notChecked } : {}),
130
169
  };
131
170
  }
171
+ /** A name or path as code: `click.pageId`. */
172
+ function code(s) {
173
+ return '`' + s + '`';
174
+ }
175
+ /** How many names a message lists before "… (+N)"; detail has them all. */
176
+ const LIST_SHORT = 6;
177
+ function shortList(names) {
178
+ return names.length <= LIST_SHORT ? names.join(', ') : `${names.slice(0, LIST_SHORT).join(', ')}, … (+${names.length - LIST_SHORT})`;
179
+ }
180
+ /** "25 of 29 tools", "all 29 tools", "3 operations behind `search`". */
181
+ function countPhrase(n, total, behind) {
182
+ if (behind)
183
+ return `${n} operations behind ${code(behind)}`;
184
+ return n === total && n > 2 ? `all ${n} tools` : total > n ? `${n} of ${total} tools` : `${n} tools`;
185
+ }
186
+ function acrossKey(f) {
187
+ const r = f;
188
+ return r.across && r.tool ? [f.severity, r.behind ?? '', r.across.key, f.fix ?? '', f.confidence ?? ''].join('\u0000') : undefined;
189
+ }
190
+ /**
191
+ * The same change in several tools (the same rule, parameter path, and schema
192
+ * before and after: `pageId` made required in 25 tools) as one finding that
193
+ * lists them. Its tools go in `tools`, and in detail when there are more than a
194
+ * message lists. "n of total": removals count against the old menu's tools.
195
+ */
196
+ function groupAcrossTools(findings, oldTotal, newTotal) {
197
+ const byKey = new Map();
198
+ for (const f of findings) {
199
+ const key = acrossKey(f);
200
+ if (key !== undefined)
201
+ byKey.set(key, [...(byKey.get(key) ?? []), f]);
202
+ }
203
+ const out = [];
204
+ for (const f of findings) {
205
+ const key = acrossKey(f);
206
+ const list = key === undefined ? undefined : byKey.get(key);
207
+ if (!list || list.length < 2) {
208
+ out.push(f);
209
+ continue;
210
+ }
211
+ if (list[0] !== f)
212
+ continue;
213
+ const names = list.map((m) => m.tool);
214
+ const places = list.flatMap((m) => m.places ?? (m.place ? [m.place] : []));
215
+ const behind = f.behind;
216
+ // Removed tools are counted against the old menu (they're not in the new one);
217
+ // everything else is about tools in the new menu.
218
+ const total = f.rule === 'diff/tool-removed' ? oldTotal : newTotal;
219
+ const { tool: _tool, ...first } = f;
220
+ const detail = [...(f.detail ?? []), ...(names.length > LIST_SHORT ? [`${behind ? 'operations' : 'tools'}: ${names.join(', ')}`] : [])];
221
+ out.push({
222
+ ...first,
223
+ message: f.across.say(countPhrase(names.length, total, behind), shortList(names), list),
224
+ ...(detail.length ? { detail } : {}),
225
+ tools: names,
226
+ ...(places.length ? { places } : {}),
227
+ });
228
+ if (!detail.length)
229
+ delete out[out.length - 1].detail;
230
+ }
231
+ return out;
232
+ }
233
+ function classCounts(findings) {
234
+ const c = { breaking: { changes: 0, tools: 0 }, minor: { changes: 0, tools: 0 }, notice: { changes: 0, tools: 0 } };
235
+ const tools = { breaking: new Set(), minor: new Set(), notice: new Set() };
236
+ for (const f of findings) {
237
+ if (!f.class)
238
+ continue;
239
+ c[f.class].changes++;
240
+ for (const t of f.tools ?? (f.tool ? [f.tool] : []))
241
+ tools[f.class].add(t);
242
+ }
243
+ for (const k of Object.keys(c))
244
+ c[k].tools = tools[k].size;
245
+ return c;
246
+ }
247
+ /** Fill in the release a breaking change should ship in: a version, or "a major release". */
248
+ function resolveFixes(findings, next) {
249
+ const phrase = next === 'enough' ? 'say so in the release notes' : next ? `release it as ${next}` : 'ship it in a major release';
250
+ for (const f of findings)
251
+ if (f.fix)
252
+ f.fix = f.fix.split(BREAKING_RELEASE).join(phrase);
253
+ }
254
+ /** A finding without the fields only diff uses to build it. */
255
+ function finished(f) {
256
+ const { place: _p, head: _h, tail: _t, group: _g, node: _n, across: _a, behind: _b, ...rest } = f;
257
+ return rest;
258
+ }
259
+ const BUMP_WORD = { major: 'breaking changes', minor: 'new features', patch: 'other changes', none: 'no changes' };
260
+ /** The version bump is smaller than the changes call for: say by how much, and what to release instead. */
261
+ function bumpFinding(release, actual, required, suggested, classes) {
262
+ const what = suggested === 'major' ? classes.breaking : suggested === 'minor' ? classes.minor : classes.notice;
263
+ const changes = `${BUMP_WORD[suggested]} (${what.changes} change${what.changes === 1 ? '' : 's'}${what.tools ? ` in ${what.tools} tool${what.tools === 1 ? '' : 's'}` : ''})`;
264
+ const whose = release.source === 'server' ? 'The server-reported version' : 'The release version';
265
+ const v = parseSemver(release.before);
266
+ const zero = v.nums[0] === 0 && required !== suggested
267
+ ? ` Under 1.0.0 each step is one lower: npm's ^${release.before} accepts any ${v.nums[0]}.${v.nums[1]}.x, so breaking changes need a minor bump and new features a patch.`
268
+ : '';
269
+ const need = `${suggested === 'major' ? 'They need' : 'That needs'} a ${required} bump.${zero}`;
270
+ return {
271
+ rule: 'diff/version-bump',
272
+ message: actual === 'none'
273
+ ? `${whose} stayed ${release.after}, but the menu has ${changes}. ${need}`
274
+ : `${release.before} → ${release.after} is a ${actual} bump, but the menu has ${changes}. ${need}`,
275
+ fix: suggested === 'major'
276
+ ? `Release it as ${nextVersion(release.before, required)}, or make the breaking changes compatible (each one's next step says how).`
277
+ : `Release it as ${nextVersion(release.before, required)}.`,
278
+ };
279
+ }
280
+ /** The first version after `version` with this bump. */
281
+ function nextVersion(version, bump) {
282
+ const v = parseSemver(version);
283
+ if (!v)
284
+ return 'the next version';
285
+ const [M, m, p] = v.nums;
286
+ return bump === 'major' ? `${M + 1}.0.0` : bump === 'minor' ? `${M}.${m + 1}.0` : bump === 'patch' ? `${M}.${m}.${p + 1}` : version;
287
+ }
132
288
  /** The same $schema switch in several tools is one finding that names them. */
133
289
  function collapseDialects(raw) {
134
290
  const groups = new Map();
@@ -146,8 +302,9 @@ function collapseDialects(raw) {
146
302
  const names = list.map((r) => r.tool);
147
303
  raw.splice(at, 0, {
148
304
  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` : '')],
305
+ message: `${names.length} tools declare a different JSON Schema dialect ($schema ${pair}) and changed nothing else outside their parameters: most likely a schema generator upgrade. ${shortList(names)}.`,
306
+ ...(names.length > LIST_SHORT ? { detail: [`tools: ${names.join(', ')}`] } : {}),
307
+ tools: names,
151
308
  });
152
309
  }
153
310
  }
@@ -157,24 +314,31 @@ function collapseDialects(raw) {
157
314
  * across tools): one line naming the tools, every place in `places`.
158
315
  */
159
316
  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.`,
317
+ 'diff/properties-opened': {
318
+ say: (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.`,
319
+ },
320
+ 'diff/properties-closed': {
321
+ say: (t, p) => `${t} tools now reject properties they don't list (additionalProperties: false added at ${p} places). Calls that send an extra property fail validation.`,
322
+ fix: `Leave these objects open until a breaking release, or ${BREAKING_RELEASE}.`,
323
+ },
324
+ 'diff/schema-equivalent': { say: (t) => `${t} tools were restructured or respelled ($ref, $defs, key order) but accept the same input.` },
163
325
  };
164
326
  function collapseMenuWide(raw) {
165
- for (const [rule, summary] of Object.entries(MENU_WIDE)) {
327
+ for (const [rule, { say, fix }] of Object.entries(MENU_WIDE)) {
166
328
  const list = raw.filter((r) => r.rule === rule && r.tool);
167
329
  if (list.length < 2)
168
330
  continue;
169
331
  const at = raw.indexOf(list[0]);
170
332
  for (const r of list)
171
333
  raw.splice(raw.indexOf(r), 1);
172
- const places = list.flatMap((r) => r.places ?? [r.message.split(' ')[0].replace(/:$/, '')]);
334
+ const places = list.flatMap((r) => r.places ?? [r.place ?? r.tool]);
173
335
  const names = list.map((r) => r.tool);
174
336
  raw.splice(at, 0, {
175
337
  rule,
176
- message: summary(list.length, places.length),
177
- detail: [names.slice(0, 12).join(', ') + (names.length > 12 ? `, and ${names.length - 12} more` : '')],
338
+ message: `${say(list.length, places.length)} ${shortList(names)}.`,
339
+ ...(names.length > LIST_SHORT ? { detail: [`tools: ${names.join(', ')}`] } : {}),
340
+ ...(fix ? { fix } : {}),
341
+ tools: names,
178
342
  places,
179
343
  });
180
344
  }
@@ -191,7 +355,17 @@ function compareTool(old, t) {
191
355
  const out = [];
192
356
  const name = t.name;
193
357
  if ((old.description ?? '') !== (t.description ?? '')) {
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 ?? '') });
358
+ const detail = textDiff(old.description ?? '', t.description ?? '');
359
+ out.push({
360
+ rule: 'diff/description',
361
+ tool: name,
362
+ message: `${code(name)}: the description changed. Agents read it to choose the tool and its arguments.`,
363
+ detail,
364
+ across: {
365
+ key: `diff/description\u0000${digest(detail)}`,
366
+ say: (count, list) => `The description changed the same way in ${count}: ${list}. Agents read it to choose the tool and its arguments.`,
367
+ },
368
+ });
195
369
  }
196
370
  // Compared by what they accept, not how they're spelled: a block moved into
197
371
  // $defs and referenced is the same schema.
@@ -200,24 +374,37 @@ function compareTool(old, t) {
200
374
  // Too large to expand on either side: compare both as written, so an expanded
201
375
  // side isn't read against a $ref on the other ("object → any"), and say so.
202
376
  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';
377
+ // A schema generator upgrade moves `definitions` to `$defs` along with the dialect:
378
+ // as written, every $ref reads as pointing somewhere else. Said once, as the dialect.
379
+ const moved = !expanded && typeof old.inputSchema?.$schema === 'string' && typeof t.inputSchema?.$schema === 'string' && old.inputSchema.$schema !== t.inputSchema.$schema;
380
+ const [oldRaw, newRaw] = moved ? [defsPool(old.inputSchema), defsPool(t.inputSchema)] : [old.inputSchema, t.inputSchema];
381
+ const a = expanded ? ea.schema : oldRaw;
382
+ const b = expanded ? eb.schema : newRaw;
383
+ // The dialect itself is said below (diff/schema-dialect), not as a reason to look by hand.
384
+ const unversioned = (x) => { const { $schema: _s, ...rest } = (x ?? {}); return rest; };
385
+ if (!expanded && canonical(moved ? unversioned(oldRaw) : oldRaw) !== canonical(moved ? unversioned(newRaw) : newRaw)) {
386
+ const which = ea.expanded ? 'the new input schema expands' : eb.expanded ? 'the old input schema expands' : 'the old and new input schemas expand';
207
387
  out.push({
208
388
  rule: 'diff/schema-other',
209
389
  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.`,
390
+ message: `${code(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.`,
391
+ fix: 'Review the changes reported for this tool by hand.',
211
392
  });
212
393
  }
213
394
  const oldEmpty = isEmptySchema(a);
214
395
  const newEmpty = isEmptySchema(b);
215
396
  if (oldEmpty || newEmpty) {
216
397
  if (canonical(a) !== canonical(b)) {
398
+ const which = oldEmpty && newEmpty ? 'old and new input schemas are' : `${oldEmpty ? 'old' : 'new'} input schema is`;
217
399
  out.push({
218
400
  rule: 'diff/schema-other',
219
401
  tool: name,
220
- message: `${name}: the ${oldEmpty ? 'old' : 'new'} inputSchema is empty or invalid (no type, no properties), so parameter changes can't be classified.`,
402
+ message: `${code(name)}: the ${which} empty or invalid (no type, no properties), so its parameter changes can't be classified.`,
403
+ fix: newEmpty ? 'Check that the server still builds this schema: an empty one usually means a schema generator or SDK mismatch.' : 'Review its parameters by hand.',
404
+ across: {
405
+ key: `diff/schema-other\u0000empty\u0000${which}`,
406
+ say: (count, list) => `In ${count}, the ${which.replace(/ is$/, 's are')} empty or invalid (no type, no properties), so parameter changes can't be classified: ${list}.`,
407
+ },
221
408
  });
222
409
  }
223
410
  return out.concat(compareRest(old, t));
@@ -228,7 +415,7 @@ function compareTool(old, t) {
228
415
  // what they point to is compared here, definition by definition, by name. A
229
416
  // narrowed enum inside one is still breaking.
230
417
  if (!expanded)
231
- compareDefinitions({ tool: name, out }, name, old.inputSchema ?? {}, t.inputSchema ?? {});
418
+ compareDefinitions({ tool: name, out }, name, oldRaw ?? {}, newRaw ?? {});
232
419
  collapsePlaces(out, found);
233
420
  const shell = (s) => {
234
421
  const { properties: _p, required: _r, $defs: _d, definitions: _df, ...rest } = (s ?? {});
@@ -246,15 +433,23 @@ function compareTool(old, t) {
246
433
  // for the menu, below.
247
434
  if (canonical(ra) === canonical(rb)) {
248
435
  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] });
436
+ out.push({ rule: 'diff/schema-dialect', tool: name, message: `${code(name)}: the input schema declares a different JSON Schema dialect ($schema ${pair}), and nothing else outside its parameters changed.`, detail: [pair] });
437
+ }
438
+ else {
439
+ const keys = changedKeys(ra, rb);
440
+ out.push({
441
+ rule: 'diff/schema-other',
442
+ tool: name,
443
+ message: `${code(name)}: the input schema changed outside its parameters, in keywords toolmenu doesn't classify: ${keys}.`,
444
+ fix: 'Review it: a new constraint on the whole input can reject calls that worked.',
445
+ across: { key: `diff/schema-other\u0000shell\u0000${digest([ra, rb])}`, say: (count, list) => `The input schema changed the same way outside its parameters in ${count}, in keywords toolmenu doesn't classify (${keys}): ${list}.` },
446
+ });
250
447
  }
251
- else
252
- out.push({ rule: 'diff/schema-other', tool: name, message: `${name}: inputSchema changed outside its parameters (additionalProperties, $schema…). Review it.` });
253
448
  }
254
449
  // Never silent: the schemas differ, and nothing above says how. Spellings the
255
450
  // rules treat as one (a type as anyOf alternatives or a list) don't count.
256
451
  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.` });
452
+ out.push({ rule: 'diff/schema-other', tool: name, message: `${code(name)}: the input schema changed in a way toolmenu doesn't classify.`, fix: 'Review it by hand.' });
258
453
  }
259
454
  // Spelled differently, accepts the same: say so, so the refactor needs no review.
260
455
  if (canonical(a) === canonical(b) && canonical(old.inputSchema) !== canonical(t.inputSchema)) {
@@ -262,11 +457,20 @@ function compareTool(old, t) {
262
457
  out.push({
263
458
  rule: 'diff/schema-equivalent',
264
459
  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).`,
460
+ message: `${code(name)}: the input schema was 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
461
  });
267
462
  }
268
463
  return out.concat(compareRest(old, t));
269
464
  }
465
+ /** Which keywords differ between two schema fragments, with their values when short: `minProperties: (unset) → 1`. */
466
+ function changedKeys(a, b) {
467
+ const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])].filter((k) => canonical(a[k]) !== canonical(b[k])).sort();
468
+ const one = (k) => {
469
+ const pair = `${show(a[k])} → ${show(b[k])}`;
470
+ return pair.length <= 60 ? `${k} ${pair}` : k;
471
+ };
472
+ return keys.length > 5 ? `${keys.slice(0, 5).map(one).join(', ')}, and ${keys.length - 5} more` : keys.map(one).join(', ');
473
+ }
270
474
  /** A schema with every type written one way: `type: [sorted]`, for anyOf/oneOf type alternatives too. */
271
475
  function sameTypes(node) {
272
476
  if (Array.isArray(node))
@@ -297,6 +501,27 @@ function sameTypes(node) {
297
501
  }
298
502
  return out;
299
503
  }
504
+ /**
505
+ * The schema with `definitions` spelled `$defs`: its entries moved into `$defs`, and
506
+ * local `#/definitions/…` $refs pointing at `#/$defs/…`. The two are one place in a
507
+ * JSON pointer's eyes, so this changes no meaning. Used where two schemas are compared
508
+ * as written and their dialects differ.
509
+ */
510
+ function defsPool(schema) {
511
+ if (!schema || typeof schema !== 'object')
512
+ return schema;
513
+ const rewrite = (node) => {
514
+ if (Array.isArray(node))
515
+ return node.map(rewrite);
516
+ if (!node || typeof node !== 'object')
517
+ return node;
518
+ return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, k === '$ref' && typeof v === 'string' ? v.replace(/^#\/definitions\//, '#/$defs/') : rewrite(v)]));
519
+ };
520
+ const { definitions, ...rest } = rewrite(schema);
521
+ if (!definitions || typeof definitions !== 'object')
522
+ return rest;
523
+ return { ...rest, $defs: { ...definitions, ...(rest.$defs ?? {}) } };
524
+ }
300
525
  /** `$defs` and `definitions` entries of two unexpanded schemas, compared by name. */
301
526
  function compareDefinitions(w, name, oldS, newS) {
302
527
  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` : '');
@@ -305,13 +530,19 @@ function compareDefinitions(w, name, oldS, newS) {
305
530
  const removed = Object.keys(a).filter((k) => !(k in b));
306
531
  const added = Object.keys(b).filter((k) => !(k in a));
307
532
  // 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'}.` });
533
+ if (removed.length) {
534
+ w.out.push({
535
+ rule: 'diff/schema-other',
536
+ tool: w.tool,
537
+ message: `${code(name)}: ${pool} ${removed.length === 1 ? 'entry' : 'entries'} removed (${list(removed)}). The schema is too large to expand, so what referred to ${removed.length === 1 ? 'it' : 'them'} is compared by name only.`,
538
+ fix: `Review the parameters that referred to ${removed.length === 1 ? 'it' : 'them'}.`,
539
+ });
540
+ }
310
541
  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)}).` });
542
+ w.out.push({ rule: 'diff/schema-other', tool: w.tool, message: `${code(name)}: ${pool} ${added.length === 1 ? 'entry' : 'entries'} added (${list(added)}).` });
312
543
  for (const [k, def] of Object.entries(b)) {
313
544
  if (k in a)
314
- compareSchema(w, `${name}.${pool}.${k}`, `${name}.${pool}.${k}`, a[k], def, 1);
545
+ compareSchema(w, `${name}.${pool}.${k}`, a[k], def, 1);
315
546
  }
316
547
  }
317
548
  }
@@ -343,13 +574,50 @@ function digest(value) {
343
574
  * same schema before and after, and the same enclosing object: two independent
344
575
  * `limit` parameters removed from different objects are two findings, while one
345
576
  * definition used at five places has the same enclosing object at all five.
577
+ *
578
+ * The message is `place` + `head` + "." + `tail`: "`click.pageId` is new and
579
+ * required. Existing calls don't send it…". The same change in several tools
580
+ * (the same path inside each, the same schema before and after, descriptions
581
+ * aside) is said once for them all (groupAcrossTools): "`pageId` is new and
582
+ * required in 25 of 29 tools: click, drag, … (+19). Existing calls…".
346
583
  */
347
- function say(w, rule, place, text, node, detail, groupAs) {
348
- const field = place.replace(/( \([^()]*(?:\([^()]*\)[^()]*)*\))+$/, '').split('.').pop();
584
+ function say(w, rule, place, head, tail, node, more = {}) {
585
+ const { detail, groupAs, fix, confidence } = more;
586
+ const field = place.replace(/(\[\]|\([^()]*(?:\([^()]*\)[^()]*)*\))+$/, '').split('.').pop();
349
587
  // groupAs: findings that are one change wherever they're found in the tool,
350
588
  // 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 } : {}) });
589
+ const group = groupAs ?? [rule, head, tail, field, digest(node), w.scope ?? '', digest(detail)].join('\u0000');
590
+ const rel = place.startsWith(w.tool) ? place.slice(w.tool.length).replace(/^\./, '') : place;
591
+ w.out.push({
592
+ rule,
593
+ tool: w.tool,
594
+ message: sentence(code(place) + head, tail),
595
+ place,
596
+ head,
597
+ tail,
598
+ group,
599
+ node,
600
+ ...(detail ? { detail } : {}),
601
+ ...(fix ? { fix } : {}),
602
+ ...(confidence ? { confidence } : {}),
603
+ across: pathAcross(rule, rel, head, tail, node, detail),
604
+ });
605
+ }
606
+ /** "`x` was removed." + " Calls that…" */
607
+ function sentence(head, tail, more = '') {
608
+ return `${head}.${tail ? ' ' + tail : ''}${more ? ' ' + more : ''}`;
609
+ }
610
+ /** The same change at the same path inside several tools. */
611
+ function pathAcross(rule, rel, head, tail, node, detail, more = '', places = '') {
612
+ return {
613
+ key: [rule, rel, head, tail, digest(shape(node)), digest(detail), places].join('\u0000'),
614
+ say: (count, list) => sentence(`${rel ? code(rel) : 'The input schema'}${head} in ${count}: ${list}`, tail, more),
615
+ };
616
+ }
617
+ /** Values as code, at most eight: `news`, `d`, and 3 more. */
618
+ function values(list) {
619
+ const shown = list.slice(0, 8).map((v) => code(typeof v === 'string' ? v : JSON.stringify(v)));
620
+ return shown.join(', ') + (list.length > 8 ? `, and ${list.length - 8} more` : '');
353
621
  }
354
622
  /**
355
623
  * One object schema against its next version: which properties were removed,
@@ -366,56 +634,128 @@ function compareObject(outer, path, oldS, newS, depth) {
366
634
  const oldReq = new Set(oldS.required ?? []);
367
635
  const newReq = new Set(newS.required ?? []);
368
636
  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.` : '';
637
+ const requiredFix = (p, schema, was) => hasDefault(schema)
638
+ ? `Take ${code(p)} out of required: its default already covers calls that leave it out.`
639
+ : `${was} ${code(p)} optional and fall back to a default when it's missing, or ${BREAKING_RELEASE}.`;
369
640
  // Removing an optional parameter only breaks callers if the new schema rejects
370
641
  // unknown properties; otherwise calls that still send it stay valid.
371
642
  const closed = newS.additionalProperties === false;
372
643
  // additionalProperties: false removed, or added (absent, true and {} are one
373
644
  // spelling after expansion). zod 4 drops it from every object: one finding for
374
- // the tool (collapsePlaces), and one line for the menu (collapseOpenings).
645
+ // the tool (collapsePlaces), and one line for the menu (collapseMenuWide).
375
646
  const wasClosed = oldS.additionalProperties === false;
376
647
  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');
648
+ say(w, 'diff/properties-opened', path, ` now accepts properties it doesn't list (additionalProperties: false removed)`, '', null, { groupAs: 'diff/properties-opened' });
378
649
  }
379
650
  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');
651
+ say(w, 'diff/properties-closed', path, ` now rejects properties it doesn't list (additionalProperties: false added)`, 'Calls that send an extra property fail validation.', null, {
652
+ groupAs: 'diff/properties-closed',
653
+ fix: `Leave it open until a breaking release, or ${BREAKING_RELEASE}.`,
654
+ });
381
655
  }
382
- for (const p of Object.keys(oldProps)) {
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]);
656
+ const gone = Object.keys(oldProps).filter((p) => !(p in newProps));
657
+ for (const p of gone) {
658
+ const fix = `Keep accepting ${code(p)} (marked deprecated) for one release, or ${BREAKING_RELEASE}.`;
659
+ if (oldReq.has(p)) {
660
+ say(w, 'diff/param-removed', `${path}.${p}`, ' was removed', `It was required, so every existing call sends it${closed ? ', and the object now rejects properties it doesn\'t list: those calls fail validation.' : ', and the server no longer reads it.'}`, oldProps[p], { fix });
661
+ }
662
+ else if (closed) {
663
+ say(w, 'diff/param-removed', `${path}.${p}`, ' (optional) was removed', 'The object rejects properties it doesn\'t list, so calls that still send it fail validation.', oldProps[p], { fix });
664
+ }
665
+ else {
666
+ 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]);
667
+ }
389
668
  }
669
+ const fresh = [];
390
670
  for (const [p, schema] of Object.entries(newProps)) {
391
671
  const before = oldProps[p];
392
672
  const at = `${path}.${p}`;
393
673
  if (!before) {
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);
674
+ if (newReq.has(p)) {
675
+ fresh.push(p);
676
+ say(w, 'diff/param-required', at, ' is new and required', `Existing calls don't send it, so they fail validation.${defaulted(schema)}`, schema, { fix: requiredFix(p, schema, 'Make') });
677
+ }
396
678
  else
397
- say(w, 'diff/param-added', at, ' is a new optional parameter.', schema);
679
+ say(w, 'diff/param-added', at, ' is a new optional parameter', '', schema);
398
680
  continue;
399
681
  }
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]);
682
+ if (!oldReq.has(p) && newReq.has(p)) {
683
+ say(w, 'diff/param-required', at, ' was optional and is now required', `Calls that leave it out fail validation.${defaulted(schema)}`, [before, schema], { fix: requiredFix(p, schema, 'Keep') });
684
+ }
402
685
  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);
686
+ say(w, 'diff/param-relaxed', at, ' was required and is now optional', '', [before, schema]);
687
+ compareSchema(w, at, before, schema, depth);
688
+ }
689
+ for (const [from, to] of likelyRenames(gone, fresh, oldProps, newProps)) {
690
+ const [a, b] = [typeOf(oldProps[from]), typeOf(newProps[to])];
691
+ const types = a === b ? (a ? `both ${a}` : 'both untyped') : `${a || 'any'} → ${b === 'array' ? `array of ${typeOf(newProps[to].items ?? {}) || 'any'}` : b || 'any'}`;
692
+ say(w, 'diff/param-renamed', `${path}.${from}`, ` → ${code(to)} looks like a rename`, `${code(from)} was removed and ${code(to)} is new and required (${types}). Both stay breaking for existing calls.`, [oldProps[from], newProps[to]], {
693
+ fix: `If it is a rename, accept ${code(from)} for one more release and treat it as ${code(to)}; either way, name the rename in the release notes.`,
694
+ confidence: 'unsure',
695
+ });
405
696
  }
406
697
  }
698
+ /**
699
+ * Removed parameters that look renamed to a new required one next to them: a
700
+ * close name (case, separators, a plural, one or two letters) and the same
701
+ * type, or an array of it. Only one-to-one: a name close to two others is no
702
+ * guess.
703
+ */
704
+ function likelyRenames(gone, fresh, oldProps, newProps) {
705
+ const fits = (from, to) => closeNames(from, to) && sameKind(oldProps[from], newProps[to]);
706
+ const pairs = [];
707
+ for (const from of gone) {
708
+ const to = fresh.filter((n) => fits(from, n));
709
+ if (to.length === 1 && gone.filter((g) => fits(g, to[0])).length === 1)
710
+ pairs.push([from, to[0]]);
711
+ }
712
+ return pairs;
713
+ }
714
+ function closeNames(a, b) {
715
+ const norm = (s) => s.toLowerCase().replace(/[-_.\s]/g, '');
716
+ const [x, y] = [norm(a), norm(b)];
717
+ if (x === y)
718
+ return true;
719
+ const [short, long] = x.length <= y.length ? [x, y] : [y, x];
720
+ if (long === `${short}s` || long === `${short}es` || (short.endsWith('y') && long === `${short.slice(0, -1)}ies`))
721
+ return true;
722
+ if (short.length < 5)
723
+ return false;
724
+ return editDistance(x, y) <= (long.length >= 10 ? 2 : 1);
725
+ }
726
+ function editDistance(a, b) {
727
+ let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
728
+ for (let i = 1; i <= a.length; i++) {
729
+ const row = [i];
730
+ for (let j = 1; j <= b.length; j++)
731
+ row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
732
+ prev = row;
733
+ }
734
+ return prev[b.length];
735
+ }
736
+ /** The same type, or one side an array of the other's type. */
737
+ function sameKind(a, b) {
738
+ const [x, y] = [typeOf(a), typeOf(b)];
739
+ if (x === y)
740
+ return true;
741
+ if (y === 'array')
742
+ return typeOf(b.items ?? {}) === x;
743
+ if (x === 'array')
744
+ return typeOf(a.items ?? {}) === y;
745
+ return false;
746
+ }
407
747
  /**
408
748
  * One schema against its next version, anywhere in a tool: its type, allowed
409
749
  * 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)`).
750
+ * compared the same way; and whatever's left, as one "review it". `at` is its
751
+ * path, and the path nested fields hang off: `gen.rows[]` for array items,
752
+ * `gen.block(kind="text")` for a union option.
413
753
  */
414
- function compareSchema(w, at, label, before, after, depth) {
754
+ function compareSchema(w, at, before, after, depth) {
415
755
  // Past the limit, a change is said as such, not passed off as an unclassified one.
416
756
  if (depth >= MAX_DEPTH) {
417
757
  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]);
758
+ say(w, 'diff/schema-other', at, ` changed more than ${MAX_DEPTH} levels deep, below where toolmenu compares field by field`, '', [before, after], { fix: 'Review it by hand.' });
419
759
  }
420
760
  return;
421
761
  }
@@ -429,29 +769,33 @@ function compareSchema(w, at, label, before, after, depth) {
429
769
  const newType = typeOf(after);
430
770
  if (union) {
431
771
  // 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);
772
+ compareUnion(w, at, optionsOf(before), optionsOf(after), depth);
433
773
  }
434
774
  else {
435
775
  if (oldType !== newType) {
436
776
  // Widening (boolean → boolean|string, object → any) accepts every call that
437
777
  // worked before; only a narrower or different type breaks callers.
778
+ const pair = `${oldType || 'any'} → ${newType || 'any'}`;
438
779
  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]);
780
+ say(w, 'diff/type-widened', at, ` now accepts more types: ${pair}`, '', [before, after]);
781
+ else {
782
+ say(w, 'diff/param-type', at, ` changed type: ${pair}`, `Calls that send ${oldType ? `${article(oldType)} ${oldType}` : 'any other type'} fail validation.`, [before, after], {
783
+ fix: oldType && newType ? `Accept both (${[...new Set([...oldType.split('|'), ...newType.split('|')])].join('|')}) for one release, or ${BREAKING_RELEASE}.` : `Restore the old type, or ${BREAKING_RELEASE}.`,
784
+ });
785
+ }
442
786
  }
443
787
  const e = enumChange(before, after);
444
788
  if (e)
445
- say(w, e.rule, label, `: ${e.message}`, [before, after]);
789
+ say(w, e.rule, at, e.head, e.tail, [before, after], e.fix ? { fix: e.fix } : {});
446
790
  }
447
791
  // Array items: compared like a parameter of their own (no items schema = any element).
448
792
  const isArray = (s) => typesOf(s)?.includes('array') ?? false;
449
793
  const arrays = !union && isArray(before) && isArray(after);
450
794
  if (arrays)
451
- compareSchema(w, `${at}[]`, `${label} (array items)`, before.items ?? {}, after.items ?? {}, depth + 1);
795
+ compareSchema(w, `${at}[]`, before.items ?? {}, after.items ?? {}, depth + 1);
452
796
  const [da, db] = [describedAs(before), describedAs(after)];
453
797
  if (da !== db) {
454
- say(w, 'diff/description', label, `: ${label.endsWith(')') ? 'description' : 'parameter description'} changed.`, [before, after], textDiff(da, db));
798
+ say(w, 'diff/description', at, ': the description changed', 'Agents read it to fill in the value.', [before, after], { detail: textDiff(da, db) });
455
799
  }
456
800
  const object = !union && hasProperties(before) && hasProperties(after);
457
801
  if (object)
@@ -461,9 +805,23 @@ function compareSchema(w, at, label, before, after, depth) {
461
805
  // A union against a plain schema is covered by its options entirely.
462
806
  if (union && !(oldOptions && newOptions))
463
807
  return;
464
- const rest = (s) => residual(s, { object, items: arrays, union });
808
+ // A default is the value a call that leaves the parameter out gets: said with both
809
+ // values, not as an unclassified keyword (a date default built from the clock).
810
+ const shown = (v) => (v === undefined ? '(none)' : JSON.stringify(v));
811
+ if (canonical(before.default) !== canonical(after.default)) {
812
+ say(w, 'diff/param-default', at, `: the default changed: ${shown(before.default)} → ${shown(after.default)}`, 'Calls that leave it out now get the new value.', [before, after], {
813
+ fix: 'If the default is built from the clock or the environment, give a fixed one or none, and say in the description what an absent value means.',
814
+ });
815
+ }
816
+ const rest = (s) => {
817
+ const r = residual(s, { object, items: arrays, union });
818
+ delete r.default;
819
+ return r;
820
+ };
465
821
  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]);
822
+ say(w, 'diff/schema-other', at, ` changed in keywords toolmenu doesn't classify: ${changedKeys(rest(before), rest(after))}`, '', [before, after], {
823
+ fix: 'Review it: a tighter constraint (a lower maximum, a new pattern or format) rejects calls that met the old one.',
824
+ });
467
825
  }
468
826
  }
469
827
  /**
@@ -553,7 +911,7 @@ function undescribed(s) {
553
911
  * A union's options, paired old with new (pairOptions), each pair compared like
554
912
  * any schema. An option gone is breaking; a new one widens.
555
913
  */
556
- function compareUnion(outer, at, label, oldOptions, newOptions, depth) {
914
+ function compareUnion(outer, at, oldOptions, newOptions, depth) {
557
915
  // Findings about the union, and inside its options, group by the union itself:
558
916
  // one union definition shared by fields of different objects (a heading's
559
917
  // content and a table cell's) is one change, whatever the objects around it.
@@ -563,13 +921,14 @@ function compareUnion(outer, at, label, oldOptions, newOptions, depth) {
563
921
  const { pairs, gone, fresh } = pairOptions(oldOptions, newOptions, key);
564
922
  const oldLabels = optionLabels(oldOptions, key);
565
923
  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);
924
+ for (const o of gone) {
925
+ say(w, 'diff/param-type', at, `: no longer accepts the ${code(oldLabels.get(o))} option`, 'Calls that send it fail validation.', o, { fix: `Keep accepting that option for one release, or ${BREAKING_RELEASE}.` });
926
+ }
568
927
  for (const o of fresh)
569
- say(w, 'diff/type-widened', label, ` now also accepts ${article(newLabels.get(o))} ${newLabels.get(o)} option.`, o);
928
+ say(w, 'diff/type-widened', at, ` now also accepts ${article(newLabels.get(o))} ${code(newLabels.get(o))} option`, '', o);
570
929
  for (const [prev, next] of pairs) {
571
930
  const k = newLabels.get(next);
572
- compareSchema(w, `${at}(${k})`, `${label} (${k} option)`, prev, next, depth + 1);
931
+ compareSchema(w, `${at}(${k})`, prev, next, depth + 1);
573
932
  }
574
933
  }
575
934
  function article(word) {
@@ -706,16 +1065,20 @@ function collapsePlaces(out, from) {
706
1065
  const [first, ...rest] = list;
707
1066
  // Same field, same schema, in identical enclosing objects: one definition,
708
1067
  // 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`] : [])];
1068
+ const more = `The same change at ${rest.length} more place${rest.length === 1 ? '' : 's'}, in the same definition.`;
1069
+ const rel = (r) => (r.place.startsWith(r.tool) ? r.place.slice(r.tool.length).replace(/^\./, '') : r.place);
1070
+ const original = first.detail;
1071
+ first.message = sentence(code(first.place) + first.head, first.tail, more);
1072
+ first.detail = [...(original ?? []), ...rest.slice(0, 10).map((r) => `also at ${rel(r)}`), ...(rest.length > 10 ? [`…and ${rest.length - 10} more`] : [])];
711
1073
  first.places = list.map((r) => r.place);
1074
+ first.across = pathAcross(first.rule, rel(first), first.head, first.tail, first.node, original, more, list.map(rel).join('\u0000'));
712
1075
  for (const r of rest)
713
1076
  out.splice(out.indexOf(r), 1);
714
1077
  }
1078
+ // Grouping across tools goes by place (`place` stays until the finding is finished).
715
1079
  for (const r of out.slice(from)) {
716
- delete r.place;
717
- delete r.text;
718
1080
  delete r.group;
1081
+ delete r.node;
719
1082
  }
720
1083
  }
721
1084
  /** A property every option is an object with, and fixes to one value. */
@@ -795,38 +1158,58 @@ function expandRefs(schema) {
795
1158
  return { schema, expanded: false };
796
1159
  }
797
1160
  }
1161
+ /** What the operations are behind: the search tool or router by name, or "the command routers" as words. */
1162
+ function catalogSource(c) {
1163
+ return (c.routers?.length ?? 0) > 1 ? c.tool : code(c.tool);
1164
+ }
798
1165
  /** Operations behind a search tool, compared like tools where both runs found them. */
799
1166
  function compareCatalogs(before, after, ignored) {
800
1167
  if (!before && !after)
801
1168
  return [];
802
1169
  if (!before || !after) {
803
- return [{ rule: 'diff/catalog-queries', message: `Only the ${before ? 'older' : 'newer'} snapshot has a catalog (snapshot --catalog), so the operations behind ${(before ?? after).tool} weren't compared.` }];
1170
+ return [
1171
+ {
1172
+ rule: 'diff/catalog-queries',
1173
+ message: `Only the ${before ? 'older' : 'newer'} snapshot has a catalog (snapshot --catalog), so the operations behind ${catalogSource((before ?? after))} weren't compared.`,
1174
+ fix: 'Snapshot both versions with --catalog.',
1175
+ },
1176
+ ];
804
1177
  }
805
1178
  const out = [];
806
- const where = `behind ${after.tool}`;
1179
+ const where = `behind ${catalogSource(after)}`;
807
1180
  if (JSON.stringify(before.queries) !== JSON.stringify(after.queries)) {
808
- out.push({ rule: 'diff/catalog-queries', message: `The two catalogs were read with different queries, so operations found on one side only say little. Pin them with catalog.queries in the config.` });
1181
+ out.push({
1182
+ rule: 'diff/catalog-queries',
1183
+ message: "The two catalogs were read with different queries, so an operation found on one side only may just not have matched the other side's queries.",
1184
+ fix: 'Pin the queries with catalog.queries in the config, and snapshot both again.',
1185
+ });
809
1186
  }
810
1187
  const partial = [before, after].filter((c) => c.failed?.length);
811
1188
  if (partial.length) {
812
- out.push({ rule: 'diff/catalog-queries', message: `${partial.length === 2 ? 'Both catalogs are' : `The ${partial[0] === before ? 'older' : 'newer'} catalog is`} partial: some queries failed (rate limits or errors), so operations found on one side only say even less.` });
1189
+ out.push({
1190
+ rule: 'diff/catalog-queries',
1191
+ message: `${partial.length === 2 ? 'Both catalogs are' : `The ${partial[0] === before ? 'older' : 'newer'} catalog is`} partial: some queries failed (rate limits or errors), so operations found on one side only say even less.`,
1192
+ fix: 'Snapshot again with --catalog once the rate limit has reset.',
1193
+ });
813
1194
  }
814
1195
  const oldOps = new Map(before.operations.filter((o) => !ignored(o.name)).map((o) => [o.name, o]));
815
1196
  const newOps = new Map(after.operations.filter((o) => !ignored(o.name)).map((o) => [o.name, o]));
816
1197
  for (const [name, op] of newOps) {
817
1198
  const old = oldOps.get(name);
818
1199
  if (!old) {
819
- out.push({ rule: 'diff/catalog-added', tool: name, message: `${name} (${where}) is new, or newly found by the same queries.` });
1200
+ out.push({ rule: 'diff/catalog-added', tool: name, message: `${code(name)} (${where}) is new, or newly found by the same queries.` });
820
1201
  continue;
821
1202
  }
822
1203
  for (const r of compareTool(old, op))
823
- out.push({ ...r, message: `${r.message.replace(/\.$/, '')} (an operation ${where}).` });
1204
+ out.push({ ...r, message: `Behind ${catalogSource(after)}: ${r.message}`, behind: after.tool });
824
1205
  }
825
1206
  const missing = [...oldOps.keys()].filter((n) => !newOps.has(n));
826
1207
  if (missing.length) {
827
1208
  out.push({
828
1209
  rule: 'diff/catalog-missing',
829
- message: `${missing.length} operation${missing.length === 1 ? '' : 's'} ${where} weren't returned by the same queries this time: removed, renamed, or ranked lower. Check before relying on them: ${missing.slice(0, 8).join(', ')}${missing.length > 8 ? ', …' : ''}.`,
1210
+ message: `${missing.length} operation${missing.length === 1 ? '' : 's'} ${where} weren't returned by the same queries this time: removed, renamed, or ranked lower. ${shortList(missing)}.`,
1211
+ ...(missing.length > LIST_SHORT ? { detail: [`operations: ${missing.join(', ')}`] } : {}),
1212
+ fix: 'Search for them by name before relying on them.',
830
1213
  });
831
1214
  }
832
1215
  return out;
@@ -836,9 +1219,18 @@ const TOOL_FIELDS = new Set(['name', 'description', 'inputSchema', 'outputSchema
836
1219
  function compareRest(old, t) {
837
1220
  const out = [];
838
1221
  const name = t.name;
1222
+ // Tool-level changes that read the same in any tool: said once for all of them.
1223
+ const same = (key, say) => ({ key, say });
839
1224
  if (canonical(old.outputSchema) !== canonical(t.outputSchema)) {
840
- const what = old.outputSchema === undefined ? 'now declares an outputSchema' : t.outputSchema === undefined ? 'no longer declares an outputSchema' : 'outputSchema changed';
841
- out.push({ rule: 'diff/schema-other', tool: name, message: `${name}: ${what}. Clients that validate structured output may notice.` });
1225
+ const what = old.outputSchema === undefined ? 'now declares an outputSchema' : t.outputSchema === undefined ? 'no longer declares an outputSchema' : 'changed its outputSchema';
1226
+ const why = old.outputSchema === undefined ? 'Clients that validate structured output will check results against it.' : t.outputSchema === undefined ? 'Clients that relied on structured output get none described.' : 'Clients that validate structured output check results against the new one.';
1227
+ out.push({
1228
+ rule: 'diff/schema-other',
1229
+ tool: name,
1230
+ message: `${code(name)} ${what}. ${why}`,
1231
+ ...(t.outputSchema !== undefined ? { fix: 'Check that what the tool returns matches it.' } : {}),
1232
+ across: same(`output\u0000${what}`, (count, list) => `${count[0].toUpperCase()}${count.slice(1)} ${what.replace(/^now declares/, 'now declare').replace(/^no longer declares/, 'no longer declare').replace(/^changed its/, 'changed their')}: ${list}. ${why}`),
1233
+ });
842
1234
  }
843
1235
  const a = old.annotations ?? {};
844
1236
  const b = t.annotations ?? {};
@@ -846,22 +1238,47 @@ function compareRest(old, t) {
846
1238
  // destructiveHint true (meaningful only when not read-only).
847
1239
  let safety = false;
848
1240
  if (readOnly(a) && !readOnly(b)) {
849
- out.push({ rule: 'diff/safety-hint', tool: name, message: `${name} is no longer read-only. Clients and agents that auto-approve read-only tools will now call something that writes.` });
1241
+ out.push({
1242
+ rule: 'diff/safety-hint',
1243
+ tool: name,
1244
+ message: `${code(name)} is no longer marked read-only (readOnlyHint ${show(a.readOnlyHint)} → ${show(b.readOnlyHint)}). Clients that auto-approve read-only tools will now ask first, or, if set to trust the server, call something that may write.`,
1245
+ fix: 'If the tool still only reads, restore readOnlyHint: true; if it writes now, say so in the release notes.',
1246
+ });
850
1247
  safety = true;
851
1248
  }
852
1249
  else if (!readOnly(b) && !destructive(a) && destructive(b)) {
853
- out.push({ rule: 'diff/safety-hint', tool: name, message: `${name} was additive-only and is now destructive.` });
1250
+ out.push({
1251
+ rule: 'diff/safety-hint',
1252
+ tool: name,
1253
+ message: `${code(name)} was marked additive-only and is now destructive (destructiveHint ${show(a.destructiveHint)} → ${show(b.destructiveHint)}; unset means destructive). Clients that auto-approve additive tools may now ask first.`,
1254
+ fix: 'If the tool still never deletes or overwrites, set destructiveHint: false; if it does now, say so in the release notes.',
1255
+ });
854
1256
  safety = true;
855
1257
  }
856
1258
  const changed = [...new Set([...Object.keys(a), ...Object.keys(b)])]
857
1259
  .filter((k) => canonical(a[k]) !== canonical(b[k]))
858
- .map((k) => `${k}: ${show(a[k])} → ${show(b[k])}`);
1260
+ .map((k) => `${k} ${show(a[k])} → ${show(b[k])}`);
859
1261
  if (changed.length && !safety) {
860
- out.push({ rule: 'diff/annotations', tool: name, message: `${name}: annotations changed (${changed.join(', ')}).` });
1262
+ const what = changed.join(', ');
1263
+ out.push({
1264
+ rule: 'diff/annotations',
1265
+ tool: name,
1266
+ message: `${code(name)}: annotations changed (${what}).`,
1267
+ across: same(`annotations\u0000${what}`, (count, list) => `Annotations changed the same way (${what}) in ${count}: ${list}.`),
1268
+ });
861
1269
  }
862
- const others = [...new Set([...Object.keys(old), ...Object.keys(t)])].filter((k) => !TOOL_FIELDS.has(k) && canonical(old[k]) !== canonical(t[k]));
1270
+ const others = [...new Set([...Object.keys(old), ...Object.keys(t)])].filter((k) => !TOOL_FIELDS.has(k) && canonical(old[k]) !== canonical(t[k])).sort();
863
1271
  if (others.length) {
864
- out.push({ rule: 'diff/other', tool: name, message: `${name}: ${others.join(', ')} changed.` });
1272
+ const what = others.map((k) => {
1273
+ const pair = `${show(old[k])} → ${show(t[k])}`;
1274
+ return pair.length <= 60 ? `${k} ${pair}` : k;
1275
+ }).join(', ');
1276
+ out.push({
1277
+ rule: 'diff/other',
1278
+ tool: name,
1279
+ message: `${code(name)}: ${what} changed. Clients may show these; the agent may read them.`,
1280
+ across: same(`other\u0000${what}`, (count, list) => `The same fields changed (${what}) in ${count}: ${list}. Clients may show these; the agent may read them.`),
1281
+ });
865
1282
  }
866
1283
  return out;
867
1284
  }
@@ -979,21 +1396,54 @@ function enumChange(before, after) {
979
1396
  const b = allowedValues(after);
980
1397
  if (!a && !b)
981
1398
  return undefined;
982
- if (!a && b)
983
- return { rule: 'diff/enum-narrowed', message: `now limited to ${b.map(String).join(', ')}.` };
1399
+ if (!a && b) {
1400
+ return { rule: 'diff/enum-narrowed', head: `: now limited to ${values(b)}`, tail: 'Calls that send any other value fail validation.', fix: `Accept other values for one more release, or ${BREAKING_RELEASE}.` };
1401
+ }
984
1402
  if (a && !b)
985
- return { rule: 'diff/enum-widened', message: `no longer limited to a fixed set of values.` };
1403
+ return { rule: 'diff/enum-widened', head: ': no longer limited to a fixed set of values', tail: '' };
986
1404
  const gone = a.filter((v) => !b.some((w) => canonical(w) === canonical(v)));
987
1405
  const fresh = b.filter((v) => !a.some((w) => canonical(w) === canonical(v)));
988
- if (gone.length)
989
- return { rule: 'diff/enum-narrowed', message: `no longer accepts ${gone.map(String).join(', ')}.` };
1406
+ if (gone.length) {
1407
+ return {
1408
+ rule: 'diff/enum-narrowed',
1409
+ head: `: no longer accepts ${values(gone)}`,
1410
+ tail: `Calls that send ${gone.length === 1 ? 'it' : 'them'} fail validation.`,
1411
+ fix: `Restore ${gone.length === 1 ? values(gone) : 'them'}, or ${BREAKING_RELEASE}.`,
1412
+ };
1413
+ }
990
1414
  if (fresh.length)
991
- return { rule: 'diff/enum-widened', message: `now also accepts ${fresh.map(String).join(', ')}.` };
1415
+ return { rule: 'diff/enum-widened', head: `: now also accepts ${values(fresh)}`, tail: '' };
992
1416
  return undefined;
993
1417
  }
1418
+ /**
1419
+ * A text change as two lines, whitespace flattened (a description's line breaks
1420
+ * would break the report's layout). A long text shows only where it changed,
1421
+ * with a few words around it: "- …for the currently selected page since…".
1422
+ */
994
1423
  function textDiff(before, after) {
995
1424
  const cut = (s) => (s.length > 240 ? s.slice(0, 237) + '…' : s);
996
- return [`- ${cut(before) || '(none)'}`, `+ ${cut(after) || '(none)'}`];
1425
+ const flat = (s) => s.replace(/\s+/g, ' ').trim();
1426
+ const [a, b] = [flat(before), flat(after)];
1427
+ // Only whitespace changed: show it.
1428
+ if (a === b)
1429
+ return [`- ${cut(JSON.stringify(before))}`, `+ ${cut(JSON.stringify(after))}`];
1430
+ if (a.length <= 160 && b.length <= 160)
1431
+ return [`- ${a || '(none)'}`, `+ ${b || '(none)'}`];
1432
+ const [wa, wb] = [a.split(' '), b.split(' ')];
1433
+ let start = 0;
1434
+ while (start < wa.length && start < wb.length && wa[start] === wb[start])
1435
+ start++;
1436
+ let end = 0;
1437
+ while (end < wa.length - start && end < wb.length - start && wa[wa.length - 1 - end] === wb[wb.length - 1 - end])
1438
+ end++;
1439
+ const context = 4;
1440
+ const from = Math.max(0, start - context);
1441
+ const excerpt = (words) => {
1442
+ const to = Math.min(words.length, words.length - end + context);
1443
+ const text = words.slice(from, to).join(' ');
1444
+ return `${from > 0 ? '…' : ''}${text || '(nothing)'}${to < words.length ? '…' : ''}`;
1445
+ };
1446
+ return [`- ${cut(a ? excerpt(wa) : '(none)')}`, `+ ${cut(b ? excerpt(wb) : '(none)')}`];
997
1447
  }
998
1448
  function tokenChange(before, after) {
999
1449
  const names = new Set([...before, ...after].map((t) => t.name));
@@ -1020,15 +1470,19 @@ function bumpFor(classes) {
1020
1470
  return 'patch';
1021
1471
  return 'none';
1022
1472
  }
1023
- /** Under 1.0.0, semver lets a minor bump carry breaking changes. */
1473
+ /**
1474
+ * The smallest bump a release line needs for these changes. From 1.0.0, what
1475
+ * semver says. Under 1.0.0 each step is one lower, as npm's caret reads it
1476
+ * (^0.2.3 accepts any 0.2.x, never 0.3.0): breaking changes need a minor bump,
1477
+ * new features a patch. Under 0.1.0 (^0.0.3 accepts only 0.0.3) anything goes.
1478
+ */
1024
1479
  function requiredBump(suggested, version) {
1025
1480
  const v = parseSemver(version);
1026
- // 0.0.x promises nothing; 0.x lets a minor bump break.
1027
- if (v && v.nums[0] === 0 && v.nums[1] === 0)
1481
+ if (!v || v.nums[0] !== 0)
1482
+ return suggested;
1483
+ if (v.nums[1] === 0)
1028
1484
  return 'none';
1029
- if (v && v.nums[0] === 0 && suggested === 'major')
1030
- return 'minor';
1031
- return suggested;
1485
+ return suggested === 'major' ? 'minor' : suggested === 'minor' ? 'patch' : suggested;
1032
1486
  }
1033
1487
  /** Why a bump can't be judged: not semver, calendar, prerelease, or backwards. */
1034
1488
  function whyNotChecked(before, after) {