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.
- package/README.md +84 -23
- package/dist/args.d.ts +31 -5
- package/dist/args.js +91 -14
- package/dist/auth.d.ts +4 -2
- package/dist/auth.js +59 -21
- package/dist/auto.d.ts +80 -6
- package/dist/auto.js +255 -19
- package/dist/breakdown.d.ts +2 -0
- package/dist/breakdown.js +64 -19
- package/dist/catalog.d.ts +87 -10
- package/dist/catalog.js +415 -58
- package/dist/cli.js +170 -185
- package/dist/close.d.ts +8 -0
- package/dist/close.js +18 -0
- package/dist/config.d.ts +7 -1
- package/dist/config.js +17 -0
- package/dist/connect.d.ts +14 -0
- package/dist/connect.js +150 -16
- package/dist/diff.d.ts +23 -1
- package/dist/diff.js +574 -120
- package/dist/difference.d.ts +2 -0
- package/dist/difference.js +13 -12
- package/dist/explain.d.ts +113 -0
- package/dist/explain.js +461 -0
- package/dist/failures.d.ts +15 -0
- package/dist/failures.js +59 -2
- package/dist/help.d.ts +11 -0
- package/dist/help.js +205 -0
- package/dist/history.d.ts +13 -0
- package/dist/history.js +86 -6
- package/dist/init.d.ts +93 -2
- package/dist/init.js +508 -21
- package/dist/menu.js +10 -2
- package/dist/options.d.ts +141 -0
- package/dist/options.js +50 -0
- package/dist/report.d.ts +2 -2
- package/dist/report.js +305 -101
- package/dist/rules/description.d.ts +7 -2
- package/dist/rules/description.js +86 -42
- package/dist/rules/determinism.d.ts +4 -1
- package/dist/rules/determinism.js +175 -11
- package/dist/rules/gated.d.ts +7 -0
- package/dist/rules/gated.js +77 -0
- package/dist/rules/ids.d.ts +1 -1
- package/dist/rules/ids.js +9 -4
- package/dist/rules/index.d.ts +6 -0
- package/dist/rules/index.js +18 -6
- package/dist/rules/naming.d.ts +1 -1
- package/dist/rules/naming.js +91 -21
- package/dist/rules/rule.d.ts +25 -0
- package/dist/rules/rule.js +25 -1
- package/dist/rules/spec.d.ts +6 -0
- package/dist/rules/spec.js +56 -9
- package/dist/rules/write.d.ts +1 -1
- package/dist/rules/write.js +64 -14
- package/dist/session.d.ts +34 -9
- package/dist/session.js +525 -94
- package/dist/snapshot.d.ts +8 -2
- package/dist/snapshot.js +33 -2
- package/dist/types.d.ts +21 -0
- package/dist/words.d.ts +5 -0
- package/dist/words.js +14 -0
- 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({
|
|
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({
|
|
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({
|
|
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
|
-
|
|
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: `
|
|
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)}
|
|
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
|
-
|
|
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
|
-
|
|
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: `${
|
|
150
|
-
|
|
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':
|
|
161
|
-
|
|
162
|
-
|
|
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,
|
|
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.
|
|
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:
|
|
177
|
-
|
|
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
|
-
|
|
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
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
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
|
|
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 ${
|
|
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,
|
|
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}:
|
|
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}:
|
|
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}:
|
|
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({
|
|
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}`,
|
|
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,
|
|
348
|
-
const
|
|
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,
|
|
352
|
-
|
|
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 (
|
|
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)
|
|
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)
|
|
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
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
if (oldReq.has(p)
|
|
386
|
-
say(w, 'diff/param-removed', `${path}.${p}`, ' was removed
|
|
387
|
-
|
|
388
|
-
|
|
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
|
-
|
|
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
|
|
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,
|
|
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
|
|
404
|
-
compareSchema(w, at,
|
|
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
|
|
411
|
-
* nested fields hang off
|
|
412
|
-
*
|
|
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,
|
|
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',
|
|
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,
|
|
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',
|
|
440
|
-
else
|
|
441
|
-
say(w, 'diff/param-type',
|
|
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,
|
|
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}[]`,
|
|
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',
|
|
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
|
-
|
|
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',
|
|
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,
|
|
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',
|
|
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',
|
|
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})`,
|
|
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
|
-
|
|
710
|
-
|
|
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 [
|
|
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
|
|
1179
|
+
const where = `behind ${catalogSource(after)}`;
|
|
807
1180
|
if (JSON.stringify(before.queries) !== JSON.stringify(after.queries)) {
|
|
808
|
-
out.push({
|
|
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({
|
|
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:
|
|
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.
|
|
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
|
|
841
|
-
|
|
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({
|
|
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({
|
|
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}
|
|
1260
|
+
.map((k) => `${k} ${show(a[k])} → ${show(b[k])}`);
|
|
859
1261
|
if (changed.length && !safety) {
|
|
860
|
-
|
|
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
|
-
|
|
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',
|
|
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',
|
|
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 {
|
|
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',
|
|
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
|
-
|
|
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
|
-
/**
|
|
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
|
-
|
|
1027
|
-
|
|
1481
|
+
if (!v || v.nums[0] !== 0)
|
|
1482
|
+
return suggested;
|
|
1483
|
+
if (v.nums[1] === 0)
|
|
1028
1484
|
return 'none';
|
|
1029
|
-
|
|
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) {
|