toolmenu 0.12.0 → 0.13.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 (58) hide show
  1. package/README.md +76 -20
  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 +53 -17
  6. package/dist/auto.d.ts +70 -6
  7. package/dist/auto.js +248 -17
  8. package/dist/breakdown.d.ts +2 -0
  9. package/dist/breakdown.js +62 -19
  10. package/dist/catalog.d.ts +87 -10
  11. package/dist/catalog.js +415 -58
  12. package/dist/cli.js +80 -170
  13. package/dist/config.d.ts +5 -1
  14. package/dist/config.js +14 -0
  15. package/dist/connect.d.ts +4 -0
  16. package/dist/connect.js +132 -11
  17. package/dist/diff.d.ts +23 -1
  18. package/dist/diff.js +526 -114
  19. package/dist/difference.d.ts +2 -0
  20. package/dist/difference.js +13 -12
  21. package/dist/explain.d.ts +103 -0
  22. package/dist/explain.js +434 -0
  23. package/dist/failures.d.ts +9 -0
  24. package/dist/failures.js +17 -0
  25. package/dist/help.d.ts +9 -0
  26. package/dist/help.js +198 -0
  27. package/dist/history.d.ts +13 -0
  28. package/dist/history.js +86 -6
  29. package/dist/init.d.ts +92 -2
  30. package/dist/init.js +507 -20
  31. package/dist/menu.js +10 -2
  32. package/dist/options.d.ts +135 -0
  33. package/dist/options.js +48 -0
  34. package/dist/report.d.ts +1 -1
  35. package/dist/report.js +229 -99
  36. package/dist/rules/description.d.ts +7 -2
  37. package/dist/rules/description.js +85 -42
  38. package/dist/rules/determinism.d.ts +3 -1
  39. package/dist/rules/determinism.js +145 -11
  40. package/dist/rules/ids.d.ts +1 -1
  41. package/dist/rules/ids.js +9 -4
  42. package/dist/rules/index.d.ts +6 -0
  43. package/dist/rules/index.js +12 -4
  44. package/dist/rules/naming.d.ts +1 -1
  45. package/dist/rules/naming.js +66 -19
  46. package/dist/rules/rule.d.ts +18 -0
  47. package/dist/rules/rule.js +25 -1
  48. package/dist/rules/spec.js +33 -9
  49. package/dist/rules/write.d.ts +1 -1
  50. package/dist/rules/write.js +42 -10
  51. package/dist/session.d.ts +18 -8
  52. package/dist/session.js +484 -92
  53. package/dist/snapshot.d.ts +2 -2
  54. package/dist/snapshot.js +17 -2
  55. package/dist/types.d.ts +14 -0
  56. package/dist/words.d.ts +5 -0
  57. package/dist/words.js +14 -0
  58. package/package.json +1 -1
package/dist/diff.js CHANGED
@@ -30,6 +30,9 @@ export const DIFF_RULES = {
30
30
  'diff/annotations': { severity: 'info', class: 'notice' },
31
31
  'diff/other': { severity: 'info', class: 'notice' },
32
32
  'diff/order': { severity: 'info', class: 'notice' },
33
+ // A tool lost a parameter and gained a required one with a close name: likely a
34
+ // rename. A hint next to the two breaking findings, not a change of its own.
35
+ 'diff/param-renamed': { severity: 'warn' },
33
36
  'diff/version-bump': { severity: 'warn' },
34
37
  'diff/version-backwards': { severity: 'warn' },
35
38
  'diff/token-budget': { severity: 'error' },
@@ -40,6 +43,12 @@ export const DIFF_RULES = {
40
43
  'diff/catalog-added': { severity: 'info' },
41
44
  'diff/catalog-queries': { severity: 'info' },
42
45
  };
46
+ /**
47
+ * In fixes: the release a breaking change should ship in. Resolved once the
48
+ * versions are known (resolveFixes): "release it as 2.0.0", or "ship it in a
49
+ * major release" when there are none to check.
50
+ */
51
+ const BREAKING_RELEASE = '\u0000breaking-release\u0000';
43
52
  export function diffMenus(before, after, options = {}) {
44
53
  const raw = [];
45
54
  // Ignored tools leave the comparison entirely, so they can't pair into a
@@ -55,13 +64,35 @@ export function diffMenus(before, after, options = {}) {
55
64
  const renamedFrom = new Set(renames.map((r) => r.from.name));
56
65
  const renamedTo = new Set(renames.map((r) => r.to.name));
57
66
  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.` });
67
+ raw.push({
68
+ rule: 'diff/tool-renamed',
69
+ tool: to.name,
70
+ 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.`,
71
+ fix: `Keep ${code(from.name)} as an alias for one release, or ${BREAKING_RELEASE}.`,
72
+ });
59
73
  }
60
74
  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.` });
75
+ raw.push({
76
+ rule: 'diff/tool-removed',
77
+ tool: t.name,
78
+ message: `${code(t.name)} was removed. Calls to it now fail with an unknown-tool error.`,
79
+ fix: `Keep the removed tool (marked deprecated in its description) for one release, or ${BREAKING_RELEASE}.`,
80
+ across: {
81
+ key: 'diff/tool-removed',
82
+ say: (count, list) => `${count} were removed: ${list}. Calls to them now fail with an unknown-tool error.`,
83
+ },
84
+ });
62
85
  }
63
86
  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).` });
87
+ raw.push({
88
+ rule: 'diff/tool-added',
89
+ tool: t.name,
90
+ message: `${code(t.name)} is new (~${fmt(t.tokens)} tokens, estimate).`,
91
+ across: {
92
+ key: 'diff/tool-added',
93
+ say: (count, list, members) => `${count} are new (~${fmt(members.reduce((n, m) => n + (newByName.get(m.tool)?.tokens ?? 0), 0))} tokens together, estimate): ${list}.`,
94
+ },
95
+ });
65
96
  }
66
97
  for (const t of newTools) {
67
98
  const old = oldByName.get(t.name);
@@ -74,23 +105,31 @@ export function diffMenus(before, after, options = {}) {
74
105
  collapseMenuWide(raw);
75
106
  const moved = compareMenus(oldTools, newTools).filter((c) => c.kind === 'moved');
76
107
  if (moved.length) {
108
+ const names = moved.map((m) => m.tool);
77
109
  raw.push({
78
110
  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.`,
111
+ 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.`,
112
+ ...(names.length > LIST_SHORT ? { detail: [`moved: ${names.join(', ')}`] } : {}),
80
113
  });
81
114
  }
82
115
  raw.push(...compareCatalogs(before.catalog, after.catalog, ignored));
83
116
  // Ignored tools leave the token counts and the budget too.
84
117
  const tokens = tokenChange(oldTools, newTools);
85
118
  if (options.tokenBudget !== undefined && tokens.after > options.tokenBudget) {
119
+ const grew = tokens.tools.filter((t) => t.delta > 0).slice(0, 3);
86
120
  raw.push({
87
121
  rule: 'diff/token-budget',
88
- message: `The menu is ~${fmt(tokens.after)} tokens, over the budget of ${fmt(options.tokenBudget)} (estimate).`,
122
+ 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.`,
123
+ fix: grew.length
124
+ ? `Trim what grew most (${grew.map((t) => code(t.name)).join(', ')}), or raise tokenBudget in the config.`
125
+ : 'Trim the longest tool descriptions, or raise tokenBudget in the config.',
89
126
  });
90
127
  }
91
128
  // 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);
129
+ // the bump and the reported findings come from the same list. Grouped after
130
+ // settling, so an ignored tool is never listed in a group.
131
+ const changes = groupAcrossTools(settle(raw, options), oldTools.length, newTools.length);
132
+ const classes = classCounts(changes);
94
133
  const suggestedBump = bumpFor(changes.map((f) => f.class));
95
134
  const versionRaw = [];
96
135
  const release = options.release
@@ -103,32 +142,146 @@ export function diffMenus(before, after, options = {}) {
103
142
  if (release && notChecked === 'version went backwards') {
104
143
  versionRaw.push({
105
144
  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.`,
145
+ message: `The ${release.source === 'server' ? 'server-reported' : 'release'} version went backwards (${release.before} → ${release.after}), so the bump can't be checked.`,
146
+ fix: release.source === 'server' ? 'Pass the release versions with --release old..new.' : 'Pass --release as old..new, the older release first.',
119
147
  });
120
148
  }
149
+ const required = release && actualBump ? requiredBump(suggestedBump, release.before) : undefined;
150
+ const short = release && actualBump && required && BUMP_RANK[actualBump] < BUMP_RANK[required];
151
+ if (short)
152
+ versionRaw.push(bumpFinding(release, actualBump, required, suggestedBump, classes));
153
+ resolveFixes(changes, release && required ? (short ? nextVersion(release.before, required) : 'enough') : undefined);
121
154
  return {
122
155
  before: before.server,
123
156
  after: after.server,
124
- findings: [...changes, ...settle(versionRaw, options)].sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]),
157
+ findings: [...changes, ...settle(versionRaw, options)].map(finished).sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]),
125
158
  tokens,
159
+ classes,
126
160
  suggestedBump,
161
+ ...(required ? { requiredBump: required } : {}),
127
162
  ...(actualBump ? { actualBump } : {}),
163
+ ...(short ? { releaseAs: nextVersion(release.before, required) } : {}),
128
164
  ...(release ? { release } : {}),
129
165
  ...(notChecked ? { bumpNotChecked: notChecked } : {}),
130
166
  };
131
167
  }
168
+ /** A name or path as code: `click.pageId`. */
169
+ function code(s) {
170
+ return '`' + s + '`';
171
+ }
172
+ /** How many names a message lists before "… (+N)"; detail has them all. */
173
+ const LIST_SHORT = 6;
174
+ function shortList(names) {
175
+ return names.length <= LIST_SHORT ? names.join(', ') : `${names.slice(0, LIST_SHORT).join(', ')}, … (+${names.length - LIST_SHORT})`;
176
+ }
177
+ /** "25 of 29 tools", "all 29 tools", "3 operations behind `search`". */
178
+ function countPhrase(n, total, behind) {
179
+ if (behind)
180
+ return `${n} operations behind ${code(behind)}`;
181
+ return n === total && n > 2 ? `all ${n} tools` : total > n ? `${n} of ${total} tools` : `${n} tools`;
182
+ }
183
+ function acrossKey(f) {
184
+ const r = f;
185
+ return r.across && r.tool ? [f.severity, r.behind ?? '', r.across.key, f.fix ?? '', f.confidence ?? ''].join('\u0000') : undefined;
186
+ }
187
+ /**
188
+ * The same change in several tools (the same rule, parameter path, and schema
189
+ * before and after: `pageId` made required in 25 tools) as one finding that
190
+ * lists them. Its tools go in `tools`, and in detail when there are more than a
191
+ * message lists. "n of total": removals count against the old menu's tools.
192
+ */
193
+ function groupAcrossTools(findings, oldTotal, newTotal) {
194
+ const byKey = new Map();
195
+ for (const f of findings) {
196
+ const key = acrossKey(f);
197
+ if (key !== undefined)
198
+ byKey.set(key, [...(byKey.get(key) ?? []), f]);
199
+ }
200
+ const out = [];
201
+ for (const f of findings) {
202
+ const key = acrossKey(f);
203
+ const list = key === undefined ? undefined : byKey.get(key);
204
+ if (!list || list.length < 2) {
205
+ out.push(f);
206
+ continue;
207
+ }
208
+ if (list[0] !== f)
209
+ continue;
210
+ const names = list.map((m) => m.tool);
211
+ const places = list.flatMap((m) => m.places ?? (m.place ? [m.place] : []));
212
+ const behind = f.behind;
213
+ // Removed tools are counted against the old menu (they're not in the new one);
214
+ // everything else is about tools in the new menu.
215
+ const total = f.rule === 'diff/tool-removed' ? oldTotal : newTotal;
216
+ const { tool: _tool, ...first } = f;
217
+ const detail = [...(f.detail ?? []), ...(names.length > LIST_SHORT ? [`${behind ? 'operations' : 'tools'}: ${names.join(', ')}`] : [])];
218
+ out.push({
219
+ ...first,
220
+ message: f.across.say(countPhrase(names.length, total, behind), shortList(names), list),
221
+ ...(detail.length ? { detail } : {}),
222
+ tools: names,
223
+ ...(places.length ? { places } : {}),
224
+ });
225
+ if (!detail.length)
226
+ delete out[out.length - 1].detail;
227
+ }
228
+ return out;
229
+ }
230
+ function classCounts(findings) {
231
+ const c = { breaking: { changes: 0, tools: 0 }, minor: { changes: 0, tools: 0 }, notice: { changes: 0, tools: 0 } };
232
+ const tools = { breaking: new Set(), minor: new Set(), notice: new Set() };
233
+ for (const f of findings) {
234
+ if (!f.class)
235
+ continue;
236
+ c[f.class].changes++;
237
+ for (const t of f.tools ?? (f.tool ? [f.tool] : []))
238
+ tools[f.class].add(t);
239
+ }
240
+ for (const k of Object.keys(c))
241
+ c[k].tools = tools[k].size;
242
+ return c;
243
+ }
244
+ /** Fill in the release a breaking change should ship in: a version, or "a major release". */
245
+ function resolveFixes(findings, next) {
246
+ const phrase = next === 'enough' ? 'say so in the release notes' : next ? `release it as ${next}` : 'ship it in a major release';
247
+ for (const f of findings)
248
+ if (f.fix)
249
+ f.fix = f.fix.split(BREAKING_RELEASE).join(phrase);
250
+ }
251
+ /** A finding without the fields only diff uses to build it. */
252
+ function finished(f) {
253
+ const { place: _p, head: _h, tail: _t, group: _g, node: _n, across: _a, behind: _b, ...rest } = f;
254
+ return rest;
255
+ }
256
+ const BUMP_WORD = { major: 'breaking changes', minor: 'new features', patch: 'other changes', none: 'no changes' };
257
+ /** The version bump is smaller than the changes call for: say by how much, and what to release instead. */
258
+ function bumpFinding(release, actual, required, suggested, classes) {
259
+ const what = suggested === 'major' ? classes.breaking : suggested === 'minor' ? classes.minor : classes.notice;
260
+ const changes = `${BUMP_WORD[suggested]} (${what.changes} change${what.changes === 1 ? '' : 's'}${what.tools ? ` in ${what.tools} tool${what.tools === 1 ? '' : 's'}` : ''})`;
261
+ const whose = release.source === 'server' ? 'The server-reported version' : 'The release version';
262
+ const v = parseSemver(release.before);
263
+ const zero = v.nums[0] === 0 && required !== suggested
264
+ ? ` 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.`
265
+ : '';
266
+ const need = `${suggested === 'major' ? 'They need' : 'That needs'} a ${required} bump.${zero}`;
267
+ return {
268
+ rule: 'diff/version-bump',
269
+ message: actual === 'none'
270
+ ? `${whose} stayed ${release.after}, but the menu has ${changes}. ${need}`
271
+ : `${release.before} → ${release.after} is a ${actual} bump, but the menu has ${changes}. ${need}`,
272
+ fix: suggested === 'major'
273
+ ? `Release it as ${nextVersion(release.before, required)}, or make the breaking changes compatible (each one's next step says how).`
274
+ : `Release it as ${nextVersion(release.before, required)}.`,
275
+ };
276
+ }
277
+ /** The first version after `version` with this bump. */
278
+ function nextVersion(version, bump) {
279
+ const v = parseSemver(version);
280
+ if (!v)
281
+ return 'the next version';
282
+ const [M, m, p] = v.nums;
283
+ return bump === 'major' ? `${M + 1}.0.0` : bump === 'minor' ? `${M}.${m + 1}.0` : bump === 'patch' ? `${M}.${m}.${p + 1}` : version;
284
+ }
132
285
  /** The same $schema switch in several tools is one finding that names them. */
133
286
  function collapseDialects(raw) {
134
287
  const groups = new Map();
@@ -146,8 +299,9 @@ function collapseDialects(raw) {
146
299
  const names = list.map((r) => r.tool);
147
300
  raw.splice(at, 0, {
148
301
  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` : '')],
302
+ 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)}.`,
303
+ ...(names.length > LIST_SHORT ? { detail: [`tools: ${names.join(', ')}`] } : {}),
304
+ tools: names,
151
305
  });
152
306
  }
153
307
  }
@@ -157,24 +311,31 @@ function collapseDialects(raw) {
157
311
  * across tools): one line naming the tools, every place in `places`.
158
312
  */
159
313
  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.`,
314
+ 'diff/properties-opened': {
315
+ 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.`,
316
+ },
317
+ 'diff/properties-closed': {
318
+ 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.`,
319
+ fix: `Leave these objects open until a breaking release, or ${BREAKING_RELEASE}.`,
320
+ },
321
+ 'diff/schema-equivalent': { say: (t) => `${t} tools were restructured or respelled ($ref, $defs, key order) but accept the same input.` },
163
322
  };
164
323
  function collapseMenuWide(raw) {
165
- for (const [rule, summary] of Object.entries(MENU_WIDE)) {
324
+ for (const [rule, { say, fix }] of Object.entries(MENU_WIDE)) {
166
325
  const list = raw.filter((r) => r.rule === rule && r.tool);
167
326
  if (list.length < 2)
168
327
  continue;
169
328
  const at = raw.indexOf(list[0]);
170
329
  for (const r of list)
171
330
  raw.splice(raw.indexOf(r), 1);
172
- const places = list.flatMap((r) => r.places ?? [r.message.split(' ')[0].replace(/:$/, '')]);
331
+ const places = list.flatMap((r) => r.places ?? [r.place ?? r.tool]);
173
332
  const names = list.map((r) => r.tool);
174
333
  raw.splice(at, 0, {
175
334
  rule,
176
- message: summary(list.length, places.length),
177
- detail: [names.slice(0, 12).join(', ') + (names.length > 12 ? `, and ${names.length - 12} more` : '')],
335
+ message: `${say(list.length, places.length)} ${shortList(names)}.`,
336
+ ...(names.length > LIST_SHORT ? { detail: [`tools: ${names.join(', ')}`] } : {}),
337
+ ...(fix ? { fix } : {}),
338
+ tools: names,
178
339
  places,
179
340
  });
180
341
  }
@@ -191,7 +352,17 @@ function compareTool(old, t) {
191
352
  const out = [];
192
353
  const name = t.name;
193
354
  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 ?? '') });
355
+ const detail = textDiff(old.description ?? '', t.description ?? '');
356
+ out.push({
357
+ rule: 'diff/description',
358
+ tool: name,
359
+ message: `${code(name)}: the description changed. Agents read it to choose the tool and its arguments.`,
360
+ detail,
361
+ across: {
362
+ key: `diff/description\u0000${digest(detail)}`,
363
+ say: (count, list) => `The description changed the same way in ${count}: ${list}. Agents read it to choose the tool and its arguments.`,
364
+ },
365
+ });
195
366
  }
196
367
  // Compared by what they accept, not how they're spelled: a block moved into
197
368
  // $defs and referenced is the same schema.
@@ -203,21 +374,28 @@ function compareTool(old, t) {
203
374
  const a = expanded ? ea.schema : old.inputSchema;
204
375
  const b = expanded ? eb.schema : t.inputSchema;
205
376
  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
+ const which = ea.expanded ? 'the new input schema expands' : eb.expanded ? 'the old input schema expands' : 'the old and new input schemas expand';
207
378
  out.push({
208
379
  rule: 'diff/schema-other',
209
380
  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.`,
381
+ 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.`,
382
+ fix: 'Review the changes reported for this tool by hand.',
211
383
  });
212
384
  }
213
385
  const oldEmpty = isEmptySchema(a);
214
386
  const newEmpty = isEmptySchema(b);
215
387
  if (oldEmpty || newEmpty) {
216
388
  if (canonical(a) !== canonical(b)) {
389
+ const which = oldEmpty && newEmpty ? 'old and new input schemas are' : `${oldEmpty ? 'old' : 'new'} input schema is`;
217
390
  out.push({
218
391
  rule: 'diff/schema-other',
219
392
  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.`,
393
+ message: `${code(name)}: the ${which} empty or invalid (no type, no properties), so its parameter changes can't be classified.`,
394
+ 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.',
395
+ across: {
396
+ key: `diff/schema-other\u0000empty\u0000${which}`,
397
+ 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}.`,
398
+ },
221
399
  });
222
400
  }
223
401
  return out.concat(compareRest(old, t));
@@ -246,15 +424,23 @@ function compareTool(old, t) {
246
424
  // for the menu, below.
247
425
  if (canonical(ra) === canonical(rb)) {
248
426
  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] });
427
+ 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] });
428
+ }
429
+ else {
430
+ const keys = changedKeys(ra, rb);
431
+ out.push({
432
+ rule: 'diff/schema-other',
433
+ tool: name,
434
+ message: `${code(name)}: the input schema changed outside its parameters, in keywords toolmenu doesn't classify: ${keys}.`,
435
+ fix: 'Review it: a new constraint on the whole input can reject calls that worked.',
436
+ 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}.` },
437
+ });
250
438
  }
251
- else
252
- out.push({ rule: 'diff/schema-other', tool: name, message: `${name}: inputSchema changed outside its parameters (additionalProperties, $schema…). Review it.` });
253
439
  }
254
440
  // Never silent: the schemas differ, and nothing above says how. Spellings the
255
441
  // rules treat as one (a type as anyOf alternatives or a list) don't count.
256
442
  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.` });
443
+ 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
444
  }
259
445
  // Spelled differently, accepts the same: say so, so the refactor needs no review.
260
446
  if (canonical(a) === canonical(b) && canonical(old.inputSchema) !== canonical(t.inputSchema)) {
@@ -262,11 +448,20 @@ function compareTool(old, t) {
262
448
  out.push({
263
449
  rule: 'diff/schema-equivalent',
264
450
  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).`,
451
+ 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
452
  });
267
453
  }
268
454
  return out.concat(compareRest(old, t));
269
455
  }
456
+ /** Which keywords differ between two schema fragments, with their values when short: `minProperties: (unset) → 1`. */
457
+ function changedKeys(a, b) {
458
+ const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])].filter((k) => canonical(a[k]) !== canonical(b[k])).sort();
459
+ const one = (k) => {
460
+ const pair = `${show(a[k])} → ${show(b[k])}`;
461
+ return pair.length <= 60 ? `${k} ${pair}` : k;
462
+ };
463
+ return keys.length > 5 ? `${keys.slice(0, 5).map(one).join(', ')}, and ${keys.length - 5} more` : keys.map(one).join(', ');
464
+ }
270
465
  /** A schema with every type written one way: `type: [sorted]`, for anyOf/oneOf type alternatives too. */
271
466
  function sameTypes(node) {
272
467
  if (Array.isArray(node))
@@ -305,13 +500,19 @@ function compareDefinitions(w, name, oldS, newS) {
305
500
  const removed = Object.keys(a).filter((k) => !(k in b));
306
501
  const added = Object.keys(b).filter((k) => !(k in a));
307
502
  // 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'}.` });
503
+ if (removed.length) {
504
+ w.out.push({
505
+ rule: 'diff/schema-other',
506
+ tool: w.tool,
507
+ 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.`,
508
+ fix: `Review the parameters that referred to ${removed.length === 1 ? 'it' : 'them'}.`,
509
+ });
510
+ }
310
511
  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)}).` });
512
+ w.out.push({ rule: 'diff/schema-other', tool: w.tool, message: `${code(name)}: ${pool} ${added.length === 1 ? 'entry' : 'entries'} added (${list(added)}).` });
312
513
  for (const [k, def] of Object.entries(b)) {
313
514
  if (k in a)
314
- compareSchema(w, `${name}.${pool}.${k}`, `${name}.${pool}.${k}`, a[k], def, 1);
515
+ compareSchema(w, `${name}.${pool}.${k}`, a[k], def, 1);
315
516
  }
316
517
  }
317
518
  }
@@ -343,13 +544,50 @@ function digest(value) {
343
544
  * same schema before and after, and the same enclosing object: two independent
344
545
  * `limit` parameters removed from different objects are two findings, while one
345
546
  * definition used at five places has the same enclosing object at all five.
547
+ *
548
+ * The message is `place` + `head` + "." + `tail`: "`click.pageId` is new and
549
+ * required. Existing calls don't send it…". The same change in several tools
550
+ * (the same path inside each, the same schema before and after, descriptions
551
+ * aside) is said once for them all (groupAcrossTools): "`pageId` is new and
552
+ * required in 25 of 29 tools: click, drag, … (+19). Existing calls…".
346
553
  */
347
- function say(w, rule, place, text, node, detail, groupAs) {
348
- const field = place.replace(/( \([^()]*(?:\([^()]*\)[^()]*)*\))+$/, '').split('.').pop();
554
+ function say(w, rule, place, head, tail, node, more = {}) {
555
+ const { detail, groupAs, fix, confidence } = more;
556
+ const field = place.replace(/(\[\]|\([^()]*(?:\([^()]*\)[^()]*)*\))+$/, '').split('.').pop();
349
557
  // groupAs: findings that are one change wherever they're found in the tool,
350
558
  // 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 } : {}) });
559
+ const group = groupAs ?? [rule, head, tail, field, digest(node), w.scope ?? '', digest(detail)].join('\u0000');
560
+ const rel = place.startsWith(w.tool) ? place.slice(w.tool.length).replace(/^\./, '') : place;
561
+ w.out.push({
562
+ rule,
563
+ tool: w.tool,
564
+ message: sentence(code(place) + head, tail),
565
+ place,
566
+ head,
567
+ tail,
568
+ group,
569
+ node,
570
+ ...(detail ? { detail } : {}),
571
+ ...(fix ? { fix } : {}),
572
+ ...(confidence ? { confidence } : {}),
573
+ across: pathAcross(rule, rel, head, tail, node, detail),
574
+ });
575
+ }
576
+ /** "`x` was removed." + " Calls that…" */
577
+ function sentence(head, tail, more = '') {
578
+ return `${head}.${tail ? ' ' + tail : ''}${more ? ' ' + more : ''}`;
579
+ }
580
+ /** The same change at the same path inside several tools. */
581
+ function pathAcross(rule, rel, head, tail, node, detail, more = '', places = '') {
582
+ return {
583
+ key: [rule, rel, head, tail, digest(shape(node)), digest(detail), places].join('\u0000'),
584
+ say: (count, list) => sentence(`${rel ? code(rel) : 'The input schema'}${head} in ${count}: ${list}`, tail, more),
585
+ };
586
+ }
587
+ /** Values as code, at most eight: `news`, `d`, and 3 more. */
588
+ function values(list) {
589
+ const shown = list.slice(0, 8).map((v) => code(typeof v === 'string' ? v : JSON.stringify(v)));
590
+ return shown.join(', ') + (list.length > 8 ? `, and ${list.length - 8} more` : '');
353
591
  }
354
592
  /**
355
593
  * One object schema against its next version: which properties were removed,
@@ -366,56 +604,128 @@ function compareObject(outer, path, oldS, newS, depth) {
366
604
  const oldReq = new Set(oldS.required ?? []);
367
605
  const newReq = new Set(newS.required ?? []);
368
606
  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.` : '';
607
+ const requiredFix = (p, schema, was) => hasDefault(schema)
608
+ ? `Take ${code(p)} out of required: its default already covers calls that leave it out.`
609
+ : `${was} ${code(p)} optional and fall back to a default when it's missing, or ${BREAKING_RELEASE}.`;
369
610
  // Removing an optional parameter only breaks callers if the new schema rejects
370
611
  // unknown properties; otherwise calls that still send it stay valid.
371
612
  const closed = newS.additionalProperties === false;
372
613
  // additionalProperties: false removed, or added (absent, true and {} are one
373
614
  // spelling after expansion). zod 4 drops it from every object: one finding for
374
- // the tool (collapsePlaces), and one line for the menu (collapseOpenings).
615
+ // the tool (collapsePlaces), and one line for the menu (collapseMenuWide).
375
616
  const wasClosed = oldS.additionalProperties === false;
376
617
  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');
618
+ say(w, 'diff/properties-opened', path, ` now accepts properties it doesn't list (additionalProperties: false removed)`, '', null, { groupAs: 'diff/properties-opened' });
378
619
  }
379
620
  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');
621
+ 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, {
622
+ groupAs: 'diff/properties-closed',
623
+ fix: `Leave it open until a breaking release, or ${BREAKING_RELEASE}.`,
624
+ });
381
625
  }
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]);
626
+ const gone = Object.keys(oldProps).filter((p) => !(p in newProps));
627
+ for (const p of gone) {
628
+ const fix = `Keep accepting ${code(p)} (marked deprecated) for one release, or ${BREAKING_RELEASE}.`;
629
+ if (oldReq.has(p)) {
630
+ 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 });
631
+ }
632
+ else if (closed) {
633
+ 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 });
634
+ }
635
+ else {
636
+ 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]);
637
+ }
389
638
  }
639
+ const fresh = [];
390
640
  for (const [p, schema] of Object.entries(newProps)) {
391
641
  const before = oldProps[p];
392
642
  const at = `${path}.${p}`;
393
643
  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);
644
+ if (newReq.has(p)) {
645
+ fresh.push(p);
646
+ 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') });
647
+ }
396
648
  else
397
- say(w, 'diff/param-added', at, ' is a new optional parameter.', schema);
649
+ say(w, 'diff/param-added', at, ' is a new optional parameter', '', schema);
398
650
  continue;
399
651
  }
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]);
652
+ if (!oldReq.has(p) && newReq.has(p)) {
653
+ 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') });
654
+ }
402
655
  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);
656
+ say(w, 'diff/param-relaxed', at, ' was required and is now optional', '', [before, schema]);
657
+ compareSchema(w, at, before, schema, depth);
658
+ }
659
+ for (const [from, to] of likelyRenames(gone, fresh, oldProps, newProps)) {
660
+ const [a, b] = [typeOf(oldProps[from]), typeOf(newProps[to])];
661
+ const types = a === b ? (a ? `both ${a}` : 'both untyped') : `${a || 'any'} → ${b === 'array' ? `array of ${typeOf(newProps[to].items ?? {}) || 'any'}` : b || 'any'}`;
662
+ 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]], {
663
+ 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.`,
664
+ confidence: 'unsure',
665
+ });
666
+ }
667
+ }
668
+ /**
669
+ * Removed parameters that look renamed to a new required one next to them: a
670
+ * close name (case, separators, a plural, one or two letters) and the same
671
+ * type, or an array of it. Only one-to-one: a name close to two others is no
672
+ * guess.
673
+ */
674
+ function likelyRenames(gone, fresh, oldProps, newProps) {
675
+ const fits = (from, to) => closeNames(from, to) && sameKind(oldProps[from], newProps[to]);
676
+ const pairs = [];
677
+ for (const from of gone) {
678
+ const to = fresh.filter((n) => fits(from, n));
679
+ if (to.length === 1 && gone.filter((g) => fits(g, to[0])).length === 1)
680
+ pairs.push([from, to[0]]);
681
+ }
682
+ return pairs;
683
+ }
684
+ function closeNames(a, b) {
685
+ const norm = (s) => s.toLowerCase().replace(/[-_.\s]/g, '');
686
+ const [x, y] = [norm(a), norm(b)];
687
+ if (x === y)
688
+ return true;
689
+ const [short, long] = x.length <= y.length ? [x, y] : [y, x];
690
+ if (long === `${short}s` || long === `${short}es` || (short.endsWith('y') && long === `${short.slice(0, -1)}ies`))
691
+ return true;
692
+ if (short.length < 5)
693
+ return false;
694
+ return editDistance(x, y) <= (long.length >= 10 ? 2 : 1);
695
+ }
696
+ function editDistance(a, b) {
697
+ let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
698
+ for (let i = 1; i <= a.length; i++) {
699
+ const row = [i];
700
+ for (let j = 1; j <= b.length; j++)
701
+ row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
702
+ prev = row;
405
703
  }
704
+ return prev[b.length];
705
+ }
706
+ /** The same type, or one side an array of the other's type. */
707
+ function sameKind(a, b) {
708
+ const [x, y] = [typeOf(a), typeOf(b)];
709
+ if (x === y)
710
+ return true;
711
+ if (y === 'array')
712
+ return typeOf(b.items ?? {}) === x;
713
+ if (x === 'array')
714
+ return typeOf(a.items ?? {}) === y;
715
+ return false;
406
716
  }
407
717
  /**
408
718
  * One schema against its next version, anywhere in a tool: its type, allowed
409
719
  * 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)`).
720
+ * compared the same way; and whatever's left, as one "review it". `at` is its
721
+ * path, and the path nested fields hang off: `gen.rows[]` for array items,
722
+ * `gen.block(kind="text")` for a union option.
413
723
  */
414
- function compareSchema(w, at, label, before, after, depth) {
724
+ function compareSchema(w, at, before, after, depth) {
415
725
  // Past the limit, a change is said as such, not passed off as an unclassified one.
416
726
  if (depth >= MAX_DEPTH) {
417
727
  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]);
728
+ 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
729
  }
420
730
  return;
421
731
  }
@@ -429,29 +739,33 @@ function compareSchema(w, at, label, before, after, depth) {
429
739
  const newType = typeOf(after);
430
740
  if (union) {
431
741
  // 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);
742
+ compareUnion(w, at, optionsOf(before), optionsOf(after), depth);
433
743
  }
434
744
  else {
435
745
  if (oldType !== newType) {
436
746
  // Widening (boolean → boolean|string, object → any) accepts every call that
437
747
  // worked before; only a narrower or different type breaks callers.
748
+ const pair = `${oldType || 'any'} → ${newType || 'any'}`;
438
749
  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]);
750
+ say(w, 'diff/type-widened', at, ` now accepts more types: ${pair}`, '', [before, after]);
751
+ else {
752
+ say(w, 'diff/param-type', at, ` changed type: ${pair}`, `Calls that send ${oldType ? `${article(oldType)} ${oldType}` : 'any other type'} fail validation.`, [before, after], {
753
+ 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}.`,
754
+ });
755
+ }
442
756
  }
443
757
  const e = enumChange(before, after);
444
758
  if (e)
445
- say(w, e.rule, label, `: ${e.message}`, [before, after]);
759
+ say(w, e.rule, at, e.head, e.tail, [before, after], e.fix ? { fix: e.fix } : {});
446
760
  }
447
761
  // Array items: compared like a parameter of their own (no items schema = any element).
448
762
  const isArray = (s) => typesOf(s)?.includes('array') ?? false;
449
763
  const arrays = !union && isArray(before) && isArray(after);
450
764
  if (arrays)
451
- compareSchema(w, `${at}[]`, `${label} (array items)`, before.items ?? {}, after.items ?? {}, depth + 1);
765
+ compareSchema(w, `${at}[]`, before.items ?? {}, after.items ?? {}, depth + 1);
452
766
  const [da, db] = [describedAs(before), describedAs(after)];
453
767
  if (da !== db) {
454
- say(w, 'diff/description', label, `: ${label.endsWith(')') ? 'description' : 'parameter description'} changed.`, [before, after], textDiff(da, db));
768
+ say(w, 'diff/description', at, ': the description changed', 'Agents read it to fill in the value.', [before, after], { detail: textDiff(da, db) });
455
769
  }
456
770
  const object = !union && hasProperties(before) && hasProperties(after);
457
771
  if (object)
@@ -463,7 +777,9 @@ function compareSchema(w, at, label, before, after, depth) {
463
777
  return;
464
778
  const rest = (s) => residual(s, { object, items: arrays, union });
465
779
  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]);
780
+ say(w, 'diff/schema-other', at, ` changed in keywords toolmenu doesn't classify: ${changedKeys(rest(before), rest(after))}`, '', [before, after], {
781
+ fix: 'Review it: a tighter constraint (a lower maximum, a new pattern or format) rejects calls that met the old one.',
782
+ });
467
783
  }
468
784
  }
469
785
  /**
@@ -553,7 +869,7 @@ function undescribed(s) {
553
869
  * A union's options, paired old with new (pairOptions), each pair compared like
554
870
  * any schema. An option gone is breaking; a new one widens.
555
871
  */
556
- function compareUnion(outer, at, label, oldOptions, newOptions, depth) {
872
+ function compareUnion(outer, at, oldOptions, newOptions, depth) {
557
873
  // Findings about the union, and inside its options, group by the union itself:
558
874
  // one union definition shared by fields of different objects (a heading's
559
875
  // content and a table cell's) is one change, whatever the objects around it.
@@ -563,13 +879,14 @@ function compareUnion(outer, at, label, oldOptions, newOptions, depth) {
563
879
  const { pairs, gone, fresh } = pairOptions(oldOptions, newOptions, key);
564
880
  const oldLabels = optionLabels(oldOptions, key);
565
881
  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);
882
+ for (const o of gone) {
883
+ 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}.` });
884
+ }
568
885
  for (const o of fresh)
569
- say(w, 'diff/type-widened', label, ` now also accepts ${article(newLabels.get(o))} ${newLabels.get(o)} option.`, o);
886
+ say(w, 'diff/type-widened', at, ` now also accepts ${article(newLabels.get(o))} ${code(newLabels.get(o))} option`, '', o);
570
887
  for (const [prev, next] of pairs) {
571
888
  const k = newLabels.get(next);
572
- compareSchema(w, `${at}(${k})`, `${label} (${k} option)`, prev, next, depth + 1);
889
+ compareSchema(w, `${at}(${k})`, prev, next, depth + 1);
573
890
  }
574
891
  }
575
892
  function article(word) {
@@ -706,16 +1023,20 @@ function collapsePlaces(out, from) {
706
1023
  const [first, ...rest] = list;
707
1024
  // Same field, same schema, in identical enclosing objects: one definition,
708
1025
  // 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`] : [])];
1026
+ const more = `The same change at ${rest.length} more place${rest.length === 1 ? '' : 's'}, in the same definition.`;
1027
+ const rel = (r) => (r.place.startsWith(r.tool) ? r.place.slice(r.tool.length).replace(/^\./, '') : r.place);
1028
+ const original = first.detail;
1029
+ first.message = sentence(code(first.place) + first.head, first.tail, more);
1030
+ first.detail = [...(original ?? []), ...rest.slice(0, 10).map((r) => `also at ${rel(r)}`), ...(rest.length > 10 ? [`…and ${rest.length - 10} more`] : [])];
711
1031
  first.places = list.map((r) => r.place);
1032
+ first.across = pathAcross(first.rule, rel(first), first.head, first.tail, first.node, original, more, list.map(rel).join('\u0000'));
712
1033
  for (const r of rest)
713
1034
  out.splice(out.indexOf(r), 1);
714
1035
  }
1036
+ // Grouping across tools goes by place (`place` stays until the finding is finished).
715
1037
  for (const r of out.slice(from)) {
716
- delete r.place;
717
- delete r.text;
718
1038
  delete r.group;
1039
+ delete r.node;
719
1040
  }
720
1041
  }
721
1042
  /** A property every option is an object with, and fixes to one value. */
@@ -795,38 +1116,58 @@ function expandRefs(schema) {
795
1116
  return { schema, expanded: false };
796
1117
  }
797
1118
  }
1119
+ /** What the operations are behind: the search tool or router by name, or "the command routers" as words. */
1120
+ function catalogSource(c) {
1121
+ return (c.routers?.length ?? 0) > 1 ? c.tool : code(c.tool);
1122
+ }
798
1123
  /** Operations behind a search tool, compared like tools where both runs found them. */
799
1124
  function compareCatalogs(before, after, ignored) {
800
1125
  if (!before && !after)
801
1126
  return [];
802
1127
  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.` }];
1128
+ return [
1129
+ {
1130
+ rule: 'diff/catalog-queries',
1131
+ message: `Only the ${before ? 'older' : 'newer'} snapshot has a catalog (snapshot --catalog), so the operations behind ${catalogSource((before ?? after))} weren't compared.`,
1132
+ fix: 'Snapshot both versions with --catalog.',
1133
+ },
1134
+ ];
804
1135
  }
805
1136
  const out = [];
806
- const where = `behind ${after.tool}`;
1137
+ const where = `behind ${catalogSource(after)}`;
807
1138
  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.` });
1139
+ out.push({
1140
+ rule: 'diff/catalog-queries',
1141
+ 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.",
1142
+ fix: 'Pin the queries with catalog.queries in the config, and snapshot both again.',
1143
+ });
809
1144
  }
810
1145
  const partial = [before, after].filter((c) => c.failed?.length);
811
1146
  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.` });
1147
+ out.push({
1148
+ rule: 'diff/catalog-queries',
1149
+ 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.`,
1150
+ fix: 'Snapshot again with --catalog once the rate limit has reset.',
1151
+ });
813
1152
  }
814
1153
  const oldOps = new Map(before.operations.filter((o) => !ignored(o.name)).map((o) => [o.name, o]));
815
1154
  const newOps = new Map(after.operations.filter((o) => !ignored(o.name)).map((o) => [o.name, o]));
816
1155
  for (const [name, op] of newOps) {
817
1156
  const old = oldOps.get(name);
818
1157
  if (!old) {
819
- out.push({ rule: 'diff/catalog-added', tool: name, message: `${name} (${where}) is new, or newly found by the same queries.` });
1158
+ out.push({ rule: 'diff/catalog-added', tool: name, message: `${code(name)} (${where}) is new, or newly found by the same queries.` });
820
1159
  continue;
821
1160
  }
822
1161
  for (const r of compareTool(old, op))
823
- out.push({ ...r, message: `${r.message.replace(/\.$/, '')} (an operation ${where}).` });
1162
+ out.push({ ...r, message: `Behind ${catalogSource(after)}: ${r.message}`, behind: after.tool });
824
1163
  }
825
1164
  const missing = [...oldOps.keys()].filter((n) => !newOps.has(n));
826
1165
  if (missing.length) {
827
1166
  out.push({
828
1167
  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 ? ', …' : ''}.`,
1168
+ 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)}.`,
1169
+ ...(missing.length > LIST_SHORT ? { detail: [`operations: ${missing.join(', ')}`] } : {}),
1170
+ fix: 'Search for them by name before relying on them.',
830
1171
  });
831
1172
  }
832
1173
  return out;
@@ -836,9 +1177,18 @@ const TOOL_FIELDS = new Set(['name', 'description', 'inputSchema', 'outputSchema
836
1177
  function compareRest(old, t) {
837
1178
  const out = [];
838
1179
  const name = t.name;
1180
+ // Tool-level changes that read the same in any tool: said once for all of them.
1181
+ const same = (key, say) => ({ key, say });
839
1182
  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.` });
1183
+ const what = old.outputSchema === undefined ? 'now declares an outputSchema' : t.outputSchema === undefined ? 'no longer declares an outputSchema' : 'changed its outputSchema';
1184
+ 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.';
1185
+ out.push({
1186
+ rule: 'diff/schema-other',
1187
+ tool: name,
1188
+ message: `${code(name)} ${what}. ${why}`,
1189
+ ...(t.outputSchema !== undefined ? { fix: 'Check that what the tool returns matches it.' } : {}),
1190
+ 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}`),
1191
+ });
842
1192
  }
843
1193
  const a = old.annotations ?? {};
844
1194
  const b = t.annotations ?? {};
@@ -846,22 +1196,47 @@ function compareRest(old, t) {
846
1196
  // destructiveHint true (meaningful only when not read-only).
847
1197
  let safety = false;
848
1198
  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.` });
1199
+ out.push({
1200
+ rule: 'diff/safety-hint',
1201
+ tool: name,
1202
+ 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.`,
1203
+ fix: 'If the tool still only reads, restore readOnlyHint: true; if it writes now, say so in the release notes.',
1204
+ });
850
1205
  safety = true;
851
1206
  }
852
1207
  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.` });
1208
+ out.push({
1209
+ rule: 'diff/safety-hint',
1210
+ tool: name,
1211
+ 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.`,
1212
+ fix: 'If the tool still never deletes or overwrites, set destructiveHint: false; if it does now, say so in the release notes.',
1213
+ });
854
1214
  safety = true;
855
1215
  }
856
1216
  const changed = [...new Set([...Object.keys(a), ...Object.keys(b)])]
857
1217
  .filter((k) => canonical(a[k]) !== canonical(b[k]))
858
- .map((k) => `${k}: ${show(a[k])} → ${show(b[k])}`);
1218
+ .map((k) => `${k} ${show(a[k])} → ${show(b[k])}`);
859
1219
  if (changed.length && !safety) {
860
- out.push({ rule: 'diff/annotations', tool: name, message: `${name}: annotations changed (${changed.join(', ')}).` });
1220
+ const what = changed.join(', ');
1221
+ out.push({
1222
+ rule: 'diff/annotations',
1223
+ tool: name,
1224
+ message: `${code(name)}: annotations changed (${what}).`,
1225
+ across: same(`annotations\u0000${what}`, (count, list) => `Annotations changed the same way (${what}) in ${count}: ${list}.`),
1226
+ });
861
1227
  }
862
- const others = [...new Set([...Object.keys(old), ...Object.keys(t)])].filter((k) => !TOOL_FIELDS.has(k) && canonical(old[k]) !== canonical(t[k]));
1228
+ const others = [...new Set([...Object.keys(old), ...Object.keys(t)])].filter((k) => !TOOL_FIELDS.has(k) && canonical(old[k]) !== canonical(t[k])).sort();
863
1229
  if (others.length) {
864
- out.push({ rule: 'diff/other', tool: name, message: `${name}: ${others.join(', ')} changed.` });
1230
+ const what = others.map((k) => {
1231
+ const pair = `${show(old[k])} → ${show(t[k])}`;
1232
+ return pair.length <= 60 ? `${k} ${pair}` : k;
1233
+ }).join(', ');
1234
+ out.push({
1235
+ rule: 'diff/other',
1236
+ tool: name,
1237
+ message: `${code(name)}: ${what} changed. Clients may show these; the agent may read them.`,
1238
+ across: same(`other\u0000${what}`, (count, list) => `The same fields changed (${what}) in ${count}: ${list}. Clients may show these; the agent may read them.`),
1239
+ });
865
1240
  }
866
1241
  return out;
867
1242
  }
@@ -979,21 +1354,54 @@ function enumChange(before, after) {
979
1354
  const b = allowedValues(after);
980
1355
  if (!a && !b)
981
1356
  return undefined;
982
- if (!a && b)
983
- return { rule: 'diff/enum-narrowed', message: `now limited to ${b.map(String).join(', ')}.` };
1357
+ if (!a && b) {
1358
+ 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}.` };
1359
+ }
984
1360
  if (a && !b)
985
- return { rule: 'diff/enum-widened', message: `no longer limited to a fixed set of values.` };
1361
+ return { rule: 'diff/enum-widened', head: ': no longer limited to a fixed set of values', tail: '' };
986
1362
  const gone = a.filter((v) => !b.some((w) => canonical(w) === canonical(v)));
987
1363
  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(', ')}.` };
1364
+ if (gone.length) {
1365
+ return {
1366
+ rule: 'diff/enum-narrowed',
1367
+ head: `: no longer accepts ${values(gone)}`,
1368
+ tail: `Calls that send ${gone.length === 1 ? 'it' : 'them'} fail validation.`,
1369
+ fix: `Restore ${gone.length === 1 ? values(gone) : 'them'}, or ${BREAKING_RELEASE}.`,
1370
+ };
1371
+ }
990
1372
  if (fresh.length)
991
- return { rule: 'diff/enum-widened', message: `now also accepts ${fresh.map(String).join(', ')}.` };
1373
+ return { rule: 'diff/enum-widened', head: `: now also accepts ${values(fresh)}`, tail: '' };
992
1374
  return undefined;
993
1375
  }
1376
+ /**
1377
+ * A text change as two lines, whitespace flattened (a description's line breaks
1378
+ * would break the report's layout). A long text shows only where it changed,
1379
+ * with a few words around it: "- …for the currently selected page since…".
1380
+ */
994
1381
  function textDiff(before, after) {
995
1382
  const cut = (s) => (s.length > 240 ? s.slice(0, 237) + '…' : s);
996
- return [`- ${cut(before) || '(none)'}`, `+ ${cut(after) || '(none)'}`];
1383
+ const flat = (s) => s.replace(/\s+/g, ' ').trim();
1384
+ const [a, b] = [flat(before), flat(after)];
1385
+ // Only whitespace changed: show it.
1386
+ if (a === b)
1387
+ return [`- ${cut(JSON.stringify(before))}`, `+ ${cut(JSON.stringify(after))}`];
1388
+ if (a.length <= 160 && b.length <= 160)
1389
+ return [`- ${a || '(none)'}`, `+ ${b || '(none)'}`];
1390
+ const [wa, wb] = [a.split(' '), b.split(' ')];
1391
+ let start = 0;
1392
+ while (start < wa.length && start < wb.length && wa[start] === wb[start])
1393
+ start++;
1394
+ let end = 0;
1395
+ while (end < wa.length - start && end < wb.length - start && wa[wa.length - 1 - end] === wb[wb.length - 1 - end])
1396
+ end++;
1397
+ const context = 4;
1398
+ const from = Math.max(0, start - context);
1399
+ const excerpt = (words) => {
1400
+ const to = Math.min(words.length, words.length - end + context);
1401
+ const text = words.slice(from, to).join(' ');
1402
+ return `${from > 0 ? '…' : ''}${text || '(nothing)'}${to < words.length ? '…' : ''}`;
1403
+ };
1404
+ return [`- ${cut(a ? excerpt(wa) : '(none)')}`, `+ ${cut(b ? excerpt(wb) : '(none)')}`];
997
1405
  }
998
1406
  function tokenChange(before, after) {
999
1407
  const names = new Set([...before, ...after].map((t) => t.name));
@@ -1020,15 +1428,19 @@ function bumpFor(classes) {
1020
1428
  return 'patch';
1021
1429
  return 'none';
1022
1430
  }
1023
- /** Under 1.0.0, semver lets a minor bump carry breaking changes. */
1431
+ /**
1432
+ * The smallest bump a release line needs for these changes. From 1.0.0, what
1433
+ * semver says. Under 1.0.0 each step is one lower, as npm's caret reads it
1434
+ * (^0.2.3 accepts any 0.2.x, never 0.3.0): breaking changes need a minor bump,
1435
+ * new features a patch. Under 0.1.0 (^0.0.3 accepts only 0.0.3) anything goes.
1436
+ */
1024
1437
  function requiredBump(suggested, version) {
1025
1438
  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)
1439
+ if (!v || v.nums[0] !== 0)
1440
+ return suggested;
1441
+ if (v.nums[1] === 0)
1028
1442
  return 'none';
1029
- if (v && v.nums[0] === 0 && suggested === 'major')
1030
- return 'minor';
1031
- return suggested;
1443
+ return suggested === 'major' ? 'minor' : suggested === 'minor' ? 'patch' : suggested;
1032
1444
  }
1033
1445
  /** Why a bump can't be judged: not semver, calendar, prerelease, or backwards. */
1034
1446
  function whyNotChecked(before, after) {