toolmenu 0.11.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.
- package/README.md +150 -30
- package/dist/args.d.ts +31 -5
- package/dist/args.js +91 -14
- package/dist/auth.d.ts +4 -2
- package/dist/auth.js +61 -18
- package/dist/auto.d.ts +71 -7
- package/dist/auto.js +267 -13
- package/dist/breakdown.d.ts +35 -6
- package/dist/breakdown.js +179 -23
- package/dist/catalog.d.ts +87 -10
- package/dist/catalog.js +415 -58
- package/dist/cli.js +116 -178
- package/dist/compare.js +20 -5
- package/dist/config.d.ts +5 -1
- package/dist/config.js +14 -0
- package/dist/connect.d.ts +4 -0
- package/dist/connect.js +132 -11
- package/dist/diff.d.ts +35 -1
- package/dist/diff.js +1132 -121
- package/dist/difference.d.ts +2 -0
- package/dist/difference.js +13 -12
- package/dist/explain.d.ts +103 -0
- package/dist/explain.js +434 -0
- package/dist/failures.d.ts +55 -0
- package/dist/failures.js +103 -0
- package/dist/help.d.ts +9 -0
- package/dist/help.js +198 -0
- package/dist/history.d.ts +13 -0
- package/dist/history.js +86 -6
- package/dist/init.d.ts +100 -5
- package/dist/init.js +520 -26
- package/dist/menu.js +10 -2
- package/dist/options.d.ts +135 -0
- package/dist/options.js +48 -0
- package/dist/probe.d.ts +15 -3
- package/dist/probe.js +35 -11
- package/dist/report.d.ts +1 -1
- package/dist/report.js +229 -99
- package/dist/rules/description.d.ts +7 -2
- package/dist/rules/description.js +89 -43
- package/dist/rules/determinism.d.ts +3 -1
- package/dist/rules/determinism.js +146 -11
- 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 +15 -5
- package/dist/rules/naming.d.ts +1 -1
- package/dist/rules/naming.js +66 -19
- package/dist/rules/rule.d.ts +18 -0
- package/dist/rules/rule.js +25 -1
- package/dist/rules/spec.d.ts +2 -0
- package/dist/rules/spec.js +61 -8
- package/dist/rules/write.d.ts +1 -1
- package/dist/rules/write.js +42 -10
- package/dist/semver.js +1 -1
- package/dist/session.d.ts +56 -7
- package/dist/session.js +800 -94
- package/dist/snapshot.d.ts +2 -2
- package/dist/snapshot.js +25 -7
- package/dist/types.d.ts +14 -0
- package/dist/words.d.ts +5 -0
- package/dist/words.js +14 -0
- package/package.json +1 -1
package/dist/diff.js
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
1
2
|
import { canonical, compareMenus } from './compare.js';
|
|
3
|
+
import { countTokens } from './menu.js';
|
|
2
4
|
import { isCalendar, parseSemver } from './semver.js';
|
|
3
5
|
import { SEVERITY_RANK } from './types.js';
|
|
4
6
|
/** Every diff rule, its default severity and what it means for semver. */
|
|
@@ -18,9 +20,19 @@ export const DIFF_RULES = {
|
|
|
18
20
|
'diff/description': { severity: 'info', class: 'notice' },
|
|
19
21
|
'diff/param-dropped': { severity: 'info', class: 'notice' },
|
|
20
22
|
'diff/schema-other': { severity: 'info', class: 'notice' },
|
|
23
|
+
// Restructured ($ref, $defs) but accepts the same input: bytes and tokens changed.
|
|
24
|
+
'diff/schema-equivalent': { severity: 'info', class: 'notice' },
|
|
25
|
+
// Only the declared $schema dialect changed: one finding for the menu.
|
|
26
|
+
'diff/schema-dialect': { severity: 'info', class: 'notice' },
|
|
27
|
+
// additionalProperties: false removed (widens) or added (breaks callers sending extras).
|
|
28
|
+
'diff/properties-opened': { severity: 'info', class: 'minor' },
|
|
29
|
+
'diff/properties-closed': { severity: 'error', class: 'breaking' },
|
|
21
30
|
'diff/annotations': { severity: 'info', class: 'notice' },
|
|
22
31
|
'diff/other': { severity: 'info', class: 'notice' },
|
|
23
32
|
'diff/order': { severity: 'info', class: 'notice' },
|
|
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' },
|
|
24
36
|
'diff/version-bump': { severity: 'warn' },
|
|
25
37
|
'diff/version-backwards': { severity: 'warn' },
|
|
26
38
|
'diff/token-budget': { severity: 'error' },
|
|
@@ -31,6 +43,12 @@ export const DIFF_RULES = {
|
|
|
31
43
|
'diff/catalog-added': { severity: 'info' },
|
|
32
44
|
'diff/catalog-queries': { severity: 'info' },
|
|
33
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';
|
|
34
52
|
export function diffMenus(before, after, options = {}) {
|
|
35
53
|
const raw = [];
|
|
36
54
|
// Ignored tools leave the comparison entirely, so they can't pair into a
|
|
@@ -46,13 +64,35 @@ export function diffMenus(before, after, options = {}) {
|
|
|
46
64
|
const renamedFrom = new Set(renames.map((r) => r.from.name));
|
|
47
65
|
const renamedTo = new Set(renames.map((r) => r.to.name));
|
|
48
66
|
for (const { from, to } of renames) {
|
|
49
|
-
raw.push({
|
|
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
|
+
});
|
|
50
73
|
}
|
|
51
74
|
for (const t of removed.filter((t) => !renamedFrom.has(t.name))) {
|
|
52
|
-
raw.push({
|
|
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
|
+
});
|
|
53
85
|
}
|
|
54
86
|
for (const t of added.filter((t) => !renamedTo.has(t.name))) {
|
|
55
|
-
raw.push({
|
|
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
|
+
});
|
|
56
96
|
}
|
|
57
97
|
for (const t of newTools) {
|
|
58
98
|
const old = oldByName.get(t.name);
|
|
@@ -61,25 +101,35 @@ export function diffMenus(before, after, options = {}) {
|
|
|
61
101
|
}
|
|
62
102
|
for (const { from, to } of renames)
|
|
63
103
|
raw.push(...compareTool(from, to).filter((f) => f.rule !== 'diff/description' && f.rule !== 'diff/other'));
|
|
104
|
+
collapseDialects(raw);
|
|
105
|
+
collapseMenuWide(raw);
|
|
64
106
|
const moved = compareMenus(oldTools, newTools).filter((c) => c.kind === 'moved');
|
|
65
107
|
if (moved.length) {
|
|
108
|
+
const names = moved.map((m) => m.tool);
|
|
66
109
|
raw.push({
|
|
67
110
|
rule: 'diff/order',
|
|
68
|
-
message: `
|
|
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(', ')}`] } : {}),
|
|
69
113
|
});
|
|
70
114
|
}
|
|
71
115
|
raw.push(...compareCatalogs(before.catalog, after.catalog, ignored));
|
|
72
116
|
// Ignored tools leave the token counts and the budget too.
|
|
73
117
|
const tokens = tokenChange(oldTools, newTools);
|
|
74
118
|
if (options.tokenBudget !== undefined && tokens.after > options.tokenBudget) {
|
|
119
|
+
const grew = tokens.tools.filter((t) => t.delta > 0).slice(0, 3);
|
|
75
120
|
raw.push({
|
|
76
121
|
rule: 'diff/token-budget',
|
|
77
|
-
message: `The menu is ~${fmt(tokens.after)} tokens, over the budget of ${fmt(options.tokenBudget)}
|
|
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.',
|
|
78
126
|
});
|
|
79
127
|
}
|
|
80
128
|
// Only what survives ignore and 'off' counts toward the bump. Settled once:
|
|
81
|
-
// the bump and the reported findings come from the same list.
|
|
82
|
-
|
|
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);
|
|
83
133
|
const suggestedBump = bumpFor(changes.map((f) => f.class));
|
|
84
134
|
const versionRaw = [];
|
|
85
135
|
const release = options.release
|
|
@@ -92,160 +142,1032 @@ export function diffMenus(before, after, options = {}) {
|
|
|
92
142
|
if (release && notChecked === 'version went backwards') {
|
|
93
143
|
versionRaw.push({
|
|
94
144
|
rule: 'diff/version-backwards',
|
|
95
|
-
message: release.source === 'server'
|
|
96
|
-
|
|
97
|
-
: `${release.before} → ${release.after}: the version went backwards. Check the --release order.`,
|
|
98
|
-
});
|
|
99
|
-
}
|
|
100
|
-
const required = requiredBump(suggestedBump, release?.before);
|
|
101
|
-
if (release && actualBump && BUMP_RANK[actualBump] < BUMP_RANK[required]) {
|
|
102
|
-
const what = release.source === 'server' ? 'The server-reported version' : 'The release version';
|
|
103
|
-
versionRaw.push({
|
|
104
|
-
rule: 'diff/version-bump',
|
|
105
|
-
message: actualBump === 'none'
|
|
106
|
-
? `${what} stayed ${release.after} but the menu has ${suggestedBump === 'major' ? 'breaking' : suggestedBump === 'minor' ? 'new' : 'changed'} parts. Suggested: a ${required} bump.`
|
|
107
|
-
: `${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.',
|
|
108
147
|
});
|
|
109
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);
|
|
110
154
|
return {
|
|
111
155
|
before: before.server,
|
|
112
156
|
after: after.server,
|
|
113
|
-
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]),
|
|
114
158
|
tokens,
|
|
159
|
+
classes,
|
|
115
160
|
suggestedBump,
|
|
161
|
+
...(required ? { requiredBump: required } : {}),
|
|
116
162
|
...(actualBump ? { actualBump } : {}),
|
|
163
|
+
...(short ? { releaseAs: nextVersion(release.before, required) } : {}),
|
|
117
164
|
...(release ? { release } : {}),
|
|
118
165
|
...(notChecked ? { bumpNotChecked: notChecked } : {}),
|
|
119
166
|
};
|
|
120
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
|
+
}
|
|
285
|
+
/** The same $schema switch in several tools is one finding that names them. */
|
|
286
|
+
function collapseDialects(raw) {
|
|
287
|
+
const groups = new Map();
|
|
288
|
+
for (const r of raw)
|
|
289
|
+
if (r.rule === 'diff/schema-dialect')
|
|
290
|
+
groups.set(r.detail[0], [...(groups.get(r.detail[0]) ?? []), r]);
|
|
291
|
+
for (const [pair, list] of groups) {
|
|
292
|
+
if (list.length < 2) {
|
|
293
|
+
delete list[0].detail;
|
|
294
|
+
continue;
|
|
295
|
+
}
|
|
296
|
+
const at = raw.indexOf(list[0]);
|
|
297
|
+
for (const r of list)
|
|
298
|
+
raw.splice(raw.indexOf(r), 1);
|
|
299
|
+
const names = list.map((r) => r.tool);
|
|
300
|
+
raw.splice(at, 0, {
|
|
301
|
+
rule: 'diff/schema-dialect',
|
|
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,
|
|
305
|
+
});
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
/**
|
|
309
|
+
* Findings that are one change made to the whole menu, found in several tools
|
|
310
|
+
* (zod 4 dropping additionalProperties: false from every object; a refactor
|
|
311
|
+
* across tools): one line naming the tools, every place in `places`.
|
|
312
|
+
*/
|
|
313
|
+
const MENU_WIDE = {
|
|
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.` },
|
|
322
|
+
};
|
|
323
|
+
function collapseMenuWide(raw) {
|
|
324
|
+
for (const [rule, { say, fix }] of Object.entries(MENU_WIDE)) {
|
|
325
|
+
const list = raw.filter((r) => r.rule === rule && r.tool);
|
|
326
|
+
if (list.length < 2)
|
|
327
|
+
continue;
|
|
328
|
+
const at = raw.indexOf(list[0]);
|
|
329
|
+
for (const r of list)
|
|
330
|
+
raw.splice(raw.indexOf(r), 1);
|
|
331
|
+
const places = list.flatMap((r) => r.places ?? [r.place ?? r.tool]);
|
|
332
|
+
const names = list.map((r) => r.tool);
|
|
333
|
+
raw.splice(at, 0, {
|
|
334
|
+
rule,
|
|
335
|
+
message: `${say(list.length, places.length)} ${shortList(names)}.`,
|
|
336
|
+
...(names.length > LIST_SHORT ? { detail: [`tools: ${names.join(', ')}`] } : {}),
|
|
337
|
+
...(fix ? { fix } : {}),
|
|
338
|
+
tools: names,
|
|
339
|
+
places,
|
|
340
|
+
});
|
|
341
|
+
}
|
|
342
|
+
}
|
|
343
|
+
/**
|
|
344
|
+
* How deep a schema is compared field by field, counting every object, array
|
|
345
|
+
* items and union option on the way. 8 cut off a document schema's lists, tables
|
|
346
|
+
* and quotes (block → items → option → fields → items → option → …) while its
|
|
347
|
+
* paragraphs were compared, so one change read as an error at two places and
|
|
348
|
+
* "review it" at four. Recursion is bounded by resolveRefs, not by this.
|
|
349
|
+
*/
|
|
350
|
+
const MAX_DEPTH = 64;
|
|
121
351
|
function compareTool(old, t) {
|
|
122
352
|
const out = [];
|
|
123
353
|
const name = t.name;
|
|
124
354
|
if ((old.description ?? '') !== (t.description ?? '')) {
|
|
125
|
-
|
|
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
|
+
});
|
|
366
|
+
}
|
|
367
|
+
// Compared by what they accept, not how they're spelled: a block moved into
|
|
368
|
+
// $defs and referenced is the same schema.
|
|
369
|
+
const ea = expandRefs(old.inputSchema);
|
|
370
|
+
const eb = expandRefs(t.inputSchema);
|
|
371
|
+
// Too large to expand on either side: compare both as written, so an expanded
|
|
372
|
+
// side isn't read against a $ref on the other ("object → any"), and say so.
|
|
373
|
+
const expanded = ea.expanded && eb.expanded;
|
|
374
|
+
const a = expanded ? ea.schema : old.inputSchema;
|
|
375
|
+
const b = expanded ? eb.schema : t.inputSchema;
|
|
376
|
+
if (!expanded && canonical(old.inputSchema) !== canonical(t.inputSchema)) {
|
|
377
|
+
const which = ea.expanded ? 'the new input schema expands' : eb.expanded ? 'the old input schema expands' : 'the old and new input schemas expand';
|
|
378
|
+
out.push({
|
|
379
|
+
rule: 'diff/schema-other',
|
|
380
|
+
tool: name,
|
|
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.',
|
|
383
|
+
});
|
|
126
384
|
}
|
|
127
|
-
const oldEmpty = isEmptySchema(
|
|
128
|
-
const newEmpty = isEmptySchema(
|
|
385
|
+
const oldEmpty = isEmptySchema(a);
|
|
386
|
+
const newEmpty = isEmptySchema(b);
|
|
129
387
|
if (oldEmpty || newEmpty) {
|
|
130
|
-
if (canonical(
|
|
388
|
+
if (canonical(a) !== canonical(b)) {
|
|
389
|
+
const which = oldEmpty && newEmpty ? 'old and new input schemas are' : `${oldEmpty ? 'old' : 'new'} input schema is`;
|
|
131
390
|
out.push({
|
|
132
391
|
rule: 'diff/schema-other',
|
|
133
392
|
tool: name,
|
|
134
|
-
message: `${name}: the ${
|
|
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
|
+
},
|
|
135
399
|
});
|
|
136
400
|
}
|
|
137
401
|
return out.concat(compareRest(old, t));
|
|
138
402
|
}
|
|
139
|
-
const
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
403
|
+
const found = out.length;
|
|
404
|
+
compareObject({ tool: name, out }, name, a, b, 0);
|
|
405
|
+
// Compared as written (too large to expand): the parameters hold $refs, so
|
|
406
|
+
// what they point to is compared here, definition by definition, by name. A
|
|
407
|
+
// narrowed enum inside one is still breaking.
|
|
408
|
+
if (!expanded)
|
|
409
|
+
compareDefinitions({ tool: name, out }, name, old.inputSchema ?? {}, t.inputSchema ?? {});
|
|
410
|
+
collapsePlaces(out, found);
|
|
411
|
+
const shell = (s) => {
|
|
412
|
+
const { properties: _p, required: _r, $defs: _d, definitions: _df, ...rest } = (s ?? {});
|
|
413
|
+
// additionalProperties: false coming or going is said by compareObject.
|
|
414
|
+
if (rest.additionalProperties === false)
|
|
415
|
+
delete rest.additionalProperties;
|
|
416
|
+
return rest;
|
|
417
|
+
};
|
|
418
|
+
const [sa, sb] = [shell(a), shell(b)];
|
|
419
|
+
if (canonical(sa) !== canonical(sb)) {
|
|
420
|
+
const { $schema: da, ...ra } = sa;
|
|
421
|
+
const { $schema: db, ...rb } = sb;
|
|
422
|
+
// Only the declared dialect: a schema generator upgrade (zod 3 → 4 moved
|
|
423
|
+
// mongodb-mcp-server 3.0.0 from draft-07 to 2020-12 in every tool). Said once
|
|
424
|
+
// for the menu, below.
|
|
425
|
+
if (canonical(ra) === canonical(rb)) {
|
|
426
|
+
const pair = `${show(da)} → ${show(db)}`;
|
|
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
|
+
});
|
|
438
|
+
}
|
|
439
|
+
}
|
|
440
|
+
// Never silent: the schemas differ, and nothing above says how. Spellings the
|
|
441
|
+
// rules treat as one (a type as anyOf alternatives or a list) don't count.
|
|
442
|
+
if (expanded && out.length === found && canonical(sameTypes(a)) !== canonical(sameTypes(b))) {
|
|
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.' });
|
|
444
|
+
}
|
|
445
|
+
// Spelled differently, accepts the same: say so, so the refactor needs no review.
|
|
446
|
+
if (canonical(a) === canonical(b) && canonical(old.inputSchema) !== canonical(t.inputSchema)) {
|
|
447
|
+
const delta = countTokens(JSON.stringify(t.inputSchema ?? {})) - countTokens(JSON.stringify(old.inputSchema ?? {}));
|
|
448
|
+
out.push({
|
|
449
|
+
rule: 'diff/schema-equivalent',
|
|
450
|
+
tool: name,
|
|
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).`,
|
|
452
|
+
});
|
|
453
|
+
}
|
|
454
|
+
return out.concat(compareRest(old, t));
|
|
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
|
+
}
|
|
465
|
+
/** A schema with every type written one way: `type: [sorted]`, for anyOf/oneOf type alternatives too. */
|
|
466
|
+
function sameTypes(node) {
|
|
467
|
+
if (Array.isArray(node))
|
|
468
|
+
return node.map(sameTypes);
|
|
469
|
+
if (!node || typeof node !== 'object')
|
|
470
|
+
return node;
|
|
471
|
+
const s = node;
|
|
472
|
+
// Name → schema maps: their keys are names, not keywords (a property called
|
|
473
|
+
// `type` is a schema, not a type).
|
|
474
|
+
const out = Object.fromEntries(Object.entries(s).map(([k, v]) => [k, SCHEMA_MAPS.has(k) && v && typeof v === 'object' && !Array.isArray(v) ? mapValues(v, sameTypes) : sameTypes(v)]));
|
|
475
|
+
const alternatives = typeAlternatives(s);
|
|
476
|
+
if (alternatives) {
|
|
477
|
+
delete out.anyOf;
|
|
478
|
+
delete out.oneOf;
|
|
479
|
+
out.type = [...new Set(alternatives)].sort();
|
|
480
|
+
// The options' descriptions stay, as the node's (describedAs).
|
|
481
|
+
const described = describedAs(s);
|
|
482
|
+
if (described)
|
|
483
|
+
out.description = described;
|
|
484
|
+
}
|
|
485
|
+
else if (typeof s.type === 'string' || (Array.isArray(s.type) && s.type.every((t) => typeof t === 'string'))) {
|
|
486
|
+
out.type = [...new Set(Array.isArray(s.type) ? s.type : [s.type])].sort();
|
|
487
|
+
}
|
|
488
|
+
// A union accepts the same whatever order its options come in.
|
|
489
|
+
for (const k of ['anyOf', 'oneOf']) {
|
|
490
|
+
if (Array.isArray(out[k]))
|
|
491
|
+
out[k] = [...out[k]].sort((x, y) => (canonical(x) < canonical(y) ? -1 : canonical(x) > canonical(y) ? 1 : 0));
|
|
492
|
+
}
|
|
493
|
+
return out;
|
|
494
|
+
}
|
|
495
|
+
/** `$defs` and `definitions` entries of two unexpanded schemas, compared by name. */
|
|
496
|
+
function compareDefinitions(w, name, oldS, newS) {
|
|
497
|
+
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` : '');
|
|
498
|
+
for (const pool of ['$defs', 'definitions']) {
|
|
499
|
+
const [a, b] = [(oldS[pool] ?? {}), (newS[pool] ?? {})];
|
|
500
|
+
const removed = Object.keys(a).filter((k) => !(k in b));
|
|
501
|
+
const added = Object.keys(b).filter((k) => !(k in a));
|
|
502
|
+
// One line each for definitions only one side has: what refers to them is compared above.
|
|
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
|
+
}
|
|
511
|
+
if (added.length)
|
|
512
|
+
w.out.push({ rule: 'diff/schema-other', tool: w.tool, message: `${code(name)}: ${pool} ${added.length === 1 ? 'entry' : 'entries'} added (${list(added)}).` });
|
|
513
|
+
for (const [k, def] of Object.entries(b)) {
|
|
514
|
+
if (k in a)
|
|
515
|
+
compareSchema(w, `${name}.${pool}.${k}`, a[k], def, 1);
|
|
516
|
+
}
|
|
517
|
+
}
|
|
518
|
+
}
|
|
519
|
+
const DESCRIPTIVE = new Set(['description', 'title', 'examples', '$comment']);
|
|
520
|
+
/** A schema without the keywords that describe it but don't change what it accepts. */
|
|
521
|
+
function shape(node) {
|
|
522
|
+
if (Array.isArray(node))
|
|
523
|
+
return node.map(shape);
|
|
524
|
+
if (!node || typeof node !== 'object')
|
|
525
|
+
return node;
|
|
526
|
+
return Object.fromEntries(Object.entries(node)
|
|
527
|
+
.filter(([k]) => !DESCRIPTIVE.has(k))
|
|
528
|
+
.map(([k, v]) => [k, SCHEMA_MAPS.has(k) && v && typeof v === 'object' && !Array.isArray(v) ? mapValues(v, shape) : shape(v)]));
|
|
529
|
+
}
|
|
530
|
+
/** Keywords whose value maps names to schemas. */
|
|
531
|
+
const SCHEMA_MAPS = new Set(['properties', '$defs', 'definitions', 'patternProperties', 'dependentSchemas']);
|
|
532
|
+
function mapValues(map, f) {
|
|
533
|
+
return Object.fromEntries(Object.entries(map).map(([k, v]) => [k, f(v)]));
|
|
534
|
+
}
|
|
535
|
+
/** A short, stable fingerprint of a (canonical) value. */
|
|
536
|
+
function digest(value) {
|
|
537
|
+
return createHash('sha1').update(canonical(value ?? null)).digest('base64').slice(0, 16);
|
|
538
|
+
}
|
|
539
|
+
/**
|
|
540
|
+
* A finding at a place in the schema, about `node` (the schema there, before and
|
|
541
|
+
* after). The place and what changed are kept apart, so one change reached
|
|
542
|
+
* through a shared definition at several places can be said once
|
|
543
|
+
* (collapsePlaces). That takes the same rule and words, the same field name, the
|
|
544
|
+
* same schema before and after, and the same enclosing object: two independent
|
|
545
|
+
* `limit` parameters removed from different objects are two findings, while one
|
|
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…".
|
|
553
|
+
*/
|
|
554
|
+
function say(w, rule, place, head, tail, node, more = {}) {
|
|
555
|
+
const { detail, groupAs, fix, confidence } = more;
|
|
556
|
+
const field = place.replace(/(\[\]|\([^()]*(?:\([^()]*\)[^()]*)*\))+$/, '').split('.').pop();
|
|
557
|
+
// groupAs: findings that are one change wherever they're found in the tool,
|
|
558
|
+
// whatever the field (additionalProperties: false dropped from every object).
|
|
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` : '');
|
|
591
|
+
}
|
|
592
|
+
/**
|
|
593
|
+
* One object schema against its next version: which properties were removed,
|
|
594
|
+
* added, or became required or optional; each one that's in both is compared by
|
|
595
|
+
* compareSchema, under a path (`gen.body.text`).
|
|
596
|
+
*/
|
|
597
|
+
function compareObject(outer, path, oldS, newS, depth) {
|
|
598
|
+
// Findings inside this object group only with findings inside one that accepts
|
|
599
|
+
// the same (descriptions aside: a $ref with its own description is the same
|
|
600
|
+
// definition).
|
|
601
|
+
const w = { ...outer, scope: digest([shape(oldS), shape(newS)]) };
|
|
602
|
+
const oldProps = oldS.properties ?? {};
|
|
603
|
+
const newProps = newS.properties ?? {};
|
|
604
|
+
const oldReq = new Set(oldS.required ?? []);
|
|
605
|
+
const newReq = new Set(newS.required ?? []);
|
|
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}.`;
|
|
143
610
|
// Removing an optional parameter only breaks callers if the new schema rejects
|
|
144
611
|
// unknown properties; otherwise calls that still send it stay valid.
|
|
145
|
-
const closed =
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
612
|
+
const closed = newS.additionalProperties === false;
|
|
613
|
+
// additionalProperties: false removed, or added (absent, true and {} are one
|
|
614
|
+
// spelling after expansion). zod 4 drops it from every object: one finding for
|
|
615
|
+
// the tool (collapsePlaces), and one line for the menu (collapseMenuWide).
|
|
616
|
+
const wasClosed = oldS.additionalProperties === false;
|
|
617
|
+
if (wasClosed && newS.additionalProperties === undefined) {
|
|
618
|
+
say(w, 'diff/properties-opened', path, ` now accepts properties it doesn't list (additionalProperties: false removed)`, '', null, { groupAs: 'diff/properties-opened' });
|
|
619
|
+
}
|
|
620
|
+
else if (!wasClosed && oldS.additionalProperties === undefined && 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
|
+
});
|
|
625
|
+
}
|
|
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]);
|
|
151
637
|
}
|
|
152
638
|
}
|
|
639
|
+
const fresh = [];
|
|
153
640
|
for (const [p, schema] of Object.entries(newProps)) {
|
|
154
641
|
const before = oldProps[p];
|
|
642
|
+
const at = `${path}.${p}`;
|
|
155
643
|
if (!before) {
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
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
|
+
}
|
|
648
|
+
else
|
|
649
|
+
say(w, 'diff/param-added', at, ' is a new optional parameter', '', schema);
|
|
159
650
|
continue;
|
|
160
651
|
}
|
|
161
652
|
if (!oldReq.has(p) && newReq.has(p)) {
|
|
162
|
-
|
|
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') });
|
|
163
654
|
}
|
|
164
|
-
else if (oldReq.has(p) && !newReq.has(p))
|
|
165
|
-
|
|
655
|
+
else if (oldReq.has(p) && !newReq.has(p))
|
|
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;
|
|
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;
|
|
716
|
+
}
|
|
717
|
+
/**
|
|
718
|
+
* One schema against its next version, anywhere in a tool: its type, allowed
|
|
719
|
+
* values and description; array items, object fields and union options, each
|
|
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.
|
|
723
|
+
*/
|
|
724
|
+
function compareSchema(w, at, before, after, depth) {
|
|
725
|
+
// Past the limit, a change is said as such, not passed off as an unclassified one.
|
|
726
|
+
if (depth >= MAX_DEPTH) {
|
|
727
|
+
if (canonical(sameTypes(before)) !== canonical(sameTypes(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.' });
|
|
166
729
|
}
|
|
167
|
-
|
|
168
|
-
|
|
730
|
+
return;
|
|
731
|
+
}
|
|
732
|
+
const oldOptions = unionOf(before);
|
|
733
|
+
const newOptions = unionOf(after);
|
|
734
|
+
// anyOf/oneOf whose options are more than a type: zod's unions, discriminated
|
|
735
|
+
// unions, and .nullable() on anything but a primitive. A side that isn't a union
|
|
736
|
+
// is one option.
|
|
737
|
+
const union = oldOptions !== undefined || newOptions !== undefined;
|
|
738
|
+
const oldType = typeOf(before);
|
|
739
|
+
const newType = typeOf(after);
|
|
740
|
+
if (union) {
|
|
741
|
+
// The plain side's description is the node's, compared below, not an option's.
|
|
742
|
+
compareUnion(w, at, optionsOf(before), optionsOf(after), depth);
|
|
743
|
+
}
|
|
744
|
+
else {
|
|
169
745
|
if (oldType !== newType) {
|
|
170
746
|
// Widening (boolean → boolean|string, object → any) accepts every call that
|
|
171
747
|
// worked before; only a narrower or different type breaks callers.
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
748
|
+
const pair = `${oldType || 'any'} → ${newType || 'any'}`;
|
|
749
|
+
if (accepts(after, before))
|
|
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
|
+
}
|
|
175
756
|
}
|
|
176
|
-
const e = enumChange(before,
|
|
177
|
-
if (e)
|
|
178
|
-
|
|
757
|
+
const e = enumChange(before, after);
|
|
758
|
+
if (e)
|
|
759
|
+
say(w, e.rule, at, e.head, e.tail, [before, after], e.fix ? { fix: e.fix } : {});
|
|
760
|
+
}
|
|
761
|
+
// Array items: compared like a parameter of their own (no items schema = any element).
|
|
762
|
+
const isArray = (s) => typesOf(s)?.includes('array') ?? false;
|
|
763
|
+
const arrays = !union && isArray(before) && isArray(after);
|
|
764
|
+
if (arrays)
|
|
765
|
+
compareSchema(w, `${at}[]`, before.items ?? {}, after.items ?? {}, depth + 1);
|
|
766
|
+
const [da, db] = [describedAs(before), describedAs(after)];
|
|
767
|
+
if (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) });
|
|
769
|
+
}
|
|
770
|
+
const object = !union && hasProperties(before) && hasProperties(after);
|
|
771
|
+
if (object)
|
|
772
|
+
compareObject(w, at, before, after, depth + 1);
|
|
773
|
+
// What no rule above covers. A breaking type change already covers a reshaped
|
|
774
|
+
// schema: no duplicate notice. A widened type can still bring new constraints.
|
|
775
|
+
// A union against a plain schema is covered by its options entirely.
|
|
776
|
+
if (union && !(oldOptions && newOptions))
|
|
777
|
+
return;
|
|
778
|
+
const rest = (s) => residual(s, { object, items: arrays, union });
|
|
779
|
+
if ((union || oldType === newType || accepts(after, before)) && canonical(rest(before)) !== canonical(rest(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
|
+
});
|
|
783
|
+
}
|
|
784
|
+
}
|
|
785
|
+
/**
|
|
786
|
+
* A schema as a list of union options, when the other side is a union: its own
|
|
787
|
+
* anyOf/oneOf options if it has any (one option, or type-only ones, included),
|
|
788
|
+
* else itself, without its description (that's the node's, compared as the
|
|
789
|
+
* node's), as the one option.
|
|
790
|
+
*/
|
|
791
|
+
function optionsOf(s) {
|
|
792
|
+
const options = unionOptions(s);
|
|
793
|
+
return options && options.length > 0 ? options : [undescribed(s)];
|
|
794
|
+
}
|
|
795
|
+
/**
|
|
796
|
+
* What a schema says about itself: its description, or, for a type written as
|
|
797
|
+
* anyOf/oneOf alternatives, the descriptions its options carry. Sentry writes a
|
|
798
|
+
* nullable string as anyOf [{type: string, description}, {type: null}]; a
|
|
799
|
+
* description moved from the option to the node is the same one.
|
|
800
|
+
*/
|
|
801
|
+
function describedAs(s) {
|
|
802
|
+
const own = typeof s.description === 'string' ? s.description : '';
|
|
803
|
+
if (!typeAlternatives(s))
|
|
804
|
+
return own;
|
|
805
|
+
// Its own text and its options', each once: a change to either is seen, even
|
|
806
|
+
// when the field has a description of its own (review of #15, sentry-both).
|
|
807
|
+
const texts = [own, ...(s.anyOf ?? s.oneOf).map((o) => (typeof o.description === 'string' ? o.description : ''))].filter(Boolean);
|
|
808
|
+
return [...new Set(texts)].join(' ');
|
|
809
|
+
}
|
|
810
|
+
/** The options of an anyOf/oneOf that isn't just a list of types. */
|
|
811
|
+
function unionOf(s) {
|
|
812
|
+
const options = unionOptions(s);
|
|
813
|
+
if (!options || options.length === 0 || typeAlternatives(s))
|
|
814
|
+
return undefined;
|
|
815
|
+
return options;
|
|
816
|
+
}
|
|
817
|
+
/**
|
|
818
|
+
* anyOf/oneOf options, with an option that is itself only a union (a $ref to
|
|
819
|
+
* one, expanded: Notion's `parent` is anyOf [parentRequest, string], and
|
|
820
|
+
* parentRequest is anyOf of objects) flattened into its options: the same values
|
|
821
|
+
* are accepted either way.
|
|
822
|
+
*/
|
|
823
|
+
function unionOptions(s) {
|
|
824
|
+
const options = (s.anyOf ?? s.oneOf);
|
|
825
|
+
if (!Array.isArray(options))
|
|
826
|
+
return undefined;
|
|
827
|
+
return options.flatMap((o) => {
|
|
828
|
+
const inner = o && typeof o === 'object' ? (o.anyOf ?? o.oneOf) : undefined;
|
|
829
|
+
const pure = Array.isArray(inner) && Object.keys(o).every((k) => k === 'anyOf' || k === 'oneOf' || DESCRIPTIVE.has(k));
|
|
830
|
+
return pure ? (unionOptions(o) ?? [o]) : [o];
|
|
831
|
+
});
|
|
832
|
+
}
|
|
833
|
+
/**
|
|
834
|
+
* A schema with the spellings that accept the same input written one way, the ones
|
|
835
|
+
* schema generators switch between (zod 3 → 4 did both in chrome-devtools-mcp
|
|
836
|
+
* 1.9.0 → 1.10.1, 61 "review it"s): `additionalProperties: {}` is `true`, and an
|
|
837
|
+
* integer's `maximum: 2^53 − 1` / `minimum: −(2^53 − 1)` (zod 4 adds them to every
|
|
838
|
+
* `.int()`) exclude nothing a call can send.
|
|
839
|
+
*/
|
|
840
|
+
function unspelled(node) {
|
|
841
|
+
if (Array.isArray(node))
|
|
842
|
+
return node.map(unspelled);
|
|
843
|
+
if (!node || typeof node !== 'object')
|
|
844
|
+
return node;
|
|
845
|
+
const s = node;
|
|
846
|
+
const out = Object.fromEntries(Object.entries(s).map(([k, v]) => [k, SCHEMA_MAPS.has(k) && v && typeof v === 'object' && !Array.isArray(v) ? mapValues(v, unspelled) : unspelled(v)]));
|
|
847
|
+
// additionalProperties absent, true and {} all allow any extra property: written
|
|
848
|
+
// as absent. false stays (compareObject says when it comes or goes).
|
|
849
|
+
const a = out.additionalProperties;
|
|
850
|
+
if (a === true || (a && typeof a === 'object' && !Array.isArray(a) && Object.keys(a).length === 0))
|
|
851
|
+
delete out.additionalProperties;
|
|
852
|
+
// Property names are strings anyway (zod 4 adds this to z.record).
|
|
853
|
+
const names = out.propertyNames;
|
|
854
|
+
if (names && typeof names === 'object' && Object.keys(names).length === 1 && names.type === 'string')
|
|
855
|
+
delete out.propertyNames;
|
|
856
|
+
const integer = s.type === 'integer' || (Array.isArray(s.type) && s.type.includes('integer'));
|
|
857
|
+
if (integer && out.maximum === Number.MAX_SAFE_INTEGER)
|
|
858
|
+
delete out.maximum;
|
|
859
|
+
if (integer && out.minimum === Number.MIN_SAFE_INTEGER)
|
|
860
|
+
delete out.minimum;
|
|
861
|
+
return out;
|
|
862
|
+
}
|
|
863
|
+
/** A schema without its description, for comparing it as one option among others. */
|
|
864
|
+
function undescribed(s) {
|
|
865
|
+
const { description: _d, ...rest } = s;
|
|
866
|
+
return rest;
|
|
867
|
+
}
|
|
868
|
+
/**
|
|
869
|
+
* A union's options, paired old with new (pairOptions), each pair compared like
|
|
870
|
+
* any schema. An option gone is breaking; a new one widens.
|
|
871
|
+
*/
|
|
872
|
+
function compareUnion(outer, at, oldOptions, newOptions, depth) {
|
|
873
|
+
// Findings about the union, and inside its options, group by the union itself:
|
|
874
|
+
// one union definition shared by fields of different objects (a heading's
|
|
875
|
+
// content and a table cell's) is one change, whatever the objects around it.
|
|
876
|
+
const w = { ...outer, scope: digest([shape(oldOptions), shape(newOptions)]) };
|
|
877
|
+
const d = discriminator(oldOptions);
|
|
878
|
+
const key = d && d === discriminator(newOptions) ? d : undefined;
|
|
879
|
+
const { pairs, gone, fresh } = pairOptions(oldOptions, newOptions, key);
|
|
880
|
+
const oldLabels = optionLabels(oldOptions, key);
|
|
881
|
+
const newLabels = optionLabels(newOptions, key);
|
|
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
|
+
}
|
|
885
|
+
for (const o of fresh)
|
|
886
|
+
say(w, 'diff/type-widened', at, ` now also accepts ${article(newLabels.get(o))} ${code(newLabels.get(o))} option`, '', o);
|
|
887
|
+
for (const [prev, next] of pairs) {
|
|
888
|
+
const k = newLabels.get(next);
|
|
889
|
+
compareSchema(w, `${at}(${k})`, prev, next, depth + 1);
|
|
890
|
+
}
|
|
891
|
+
}
|
|
892
|
+
function article(word) {
|
|
893
|
+
return /^[aeiou]/i.test(word) ? 'an' : 'a';
|
|
894
|
+
}
|
|
895
|
+
/**
|
|
896
|
+
* Which old option became which new one. With a discriminator every option fixes
|
|
897
|
+
* (`kind: "text"`), by its value. Without one (a plain z.union of objects, an
|
|
898
|
+
* option that's an unexpanded $ref): identical options first, so a reorder or an
|
|
899
|
+
* option added in front changes nothing else; then options of the same type,
|
|
900
|
+
* objects by how many property names they share, best match first. An object
|
|
901
|
+
* option that shares no property name with any other is gone or new, not a
|
|
902
|
+
* reshaped one. Pairs come back in the new schema's order.
|
|
903
|
+
*/
|
|
904
|
+
function pairOptions(oldOptions, newOptions, key) {
|
|
905
|
+
const oldLeft = new Set(oldOptions.keys());
|
|
906
|
+
const newLeft = new Set(newOptions.keys());
|
|
907
|
+
const pairs = [];
|
|
908
|
+
const take = (i, j) => {
|
|
909
|
+
pairs.push([i, j]);
|
|
910
|
+
oldLeft.delete(i);
|
|
911
|
+
newLeft.delete(j);
|
|
912
|
+
};
|
|
913
|
+
// Old options by fingerprint, each computed once: matching is a lookup, not a
|
|
914
|
+
// scan (a 1,500-option union took 36 s).
|
|
915
|
+
const match = (fingerprint) => {
|
|
916
|
+
const byPrint = new Map();
|
|
917
|
+
oldOptions.forEach((o, i) => {
|
|
918
|
+
if (!oldLeft.has(i))
|
|
919
|
+
return;
|
|
920
|
+
const f = fingerprint(o);
|
|
921
|
+
byPrint.set(f, [...(byPrint.get(f) ?? []), i]);
|
|
922
|
+
});
|
|
923
|
+
for (const j of newOptions.keys()) {
|
|
924
|
+
if (!newLeft.has(j))
|
|
925
|
+
continue;
|
|
926
|
+
const i = byPrint.get(fingerprint(newOptions[j]))?.shift();
|
|
927
|
+
if (i !== undefined)
|
|
928
|
+
take(i, j);
|
|
179
929
|
}
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
930
|
+
};
|
|
931
|
+
if (key) {
|
|
932
|
+
// An option that's a $ref (unexpanded: a recursive one) has no discriminator
|
|
933
|
+
// value of its own: it pairs by its ref.
|
|
934
|
+
match((o) => (typeof o.$ref === 'string' ? `$ref ${o.$ref}` : canonical(fixedValue(o.properties?.[key]))));
|
|
935
|
+
}
|
|
936
|
+
else {
|
|
937
|
+
match((o) => canonical(sameTypes(o)));
|
|
938
|
+
const names = new Map([...oldOptions, ...newOptions].map((o) => [o, new Set(Object.keys(o.properties ?? {}))]));
|
|
939
|
+
const types = new Map([...oldOptions, ...newOptions].map((o) => [o, typeOf(o)]));
|
|
940
|
+
const candidates = [];
|
|
941
|
+
for (const i of oldLeft) {
|
|
942
|
+
for (const j of newLeft) {
|
|
943
|
+
const [a, b] = [oldOptions[i], newOptions[j]];
|
|
944
|
+
if (types.get(a) !== types.get(b))
|
|
945
|
+
continue;
|
|
946
|
+
let score = 0.5;
|
|
947
|
+
if (hasProperties(a) || hasProperties(b)) {
|
|
948
|
+
const [x, y] = [names.get(a), names.get(b)];
|
|
949
|
+
const all = new Set([...x, ...y]).size;
|
|
950
|
+
// Two objects with no properties at all have the same shape.
|
|
951
|
+
score = all === 0 ? 1 : [...x].filter((n) => y.has(n)).length / all;
|
|
952
|
+
}
|
|
953
|
+
if (score > 0)
|
|
954
|
+
candidates.push([score, i, j]);
|
|
192
955
|
}
|
|
193
|
-
const ie = enumChange(oldItems, newItems);
|
|
194
|
-
if (ie)
|
|
195
|
-
out.push({ rule: ie.rule, tool: name, message: `${name}.${p} (array items): ${ie.message}` });
|
|
196
956
|
}
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
//
|
|
202
|
-
//
|
|
203
|
-
//
|
|
204
|
-
|
|
205
|
-
|
|
957
|
+
candidates.sort((p, q) => q[0] - p[0] || p[1] - q[1] || p[2] - q[2]);
|
|
958
|
+
for (const [, i, j] of candidates)
|
|
959
|
+
if (oldLeft.has(i) && newLeft.has(j))
|
|
960
|
+
take(i, j);
|
|
961
|
+
// As many options left on each side: the ones that were edited (a type
|
|
962
|
+
// changed, an option emptied or given its first field). Paired in order,
|
|
963
|
+
// compared inside, rather than said as one removed and one added. Not two
|
|
964
|
+
// objects that each have fields and share none: that's one option replaced by
|
|
965
|
+
// another (pair-replace in the review of #15).
|
|
966
|
+
if (oldLeft.size > 0 && oldLeft.size === newLeft.size) {
|
|
967
|
+
const [olds, news] = [[...oldLeft].sort((a, b) => a - b), [...newLeft].sort((a, b) => a - b)];
|
|
968
|
+
const filled = (o) => names.get(o).size > 0;
|
|
969
|
+
olds.forEach((i, n) => {
|
|
970
|
+
if (!(filled(oldOptions[i]) && filled(newOptions[news[n]])))
|
|
971
|
+
take(i, news[n]);
|
|
972
|
+
});
|
|
206
973
|
}
|
|
207
974
|
}
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
975
|
+
pairs.sort((p, q) => p[1] - q[1]);
|
|
976
|
+
return {
|
|
977
|
+
pairs: pairs.map(([i, j]) => [oldOptions[i], newOptions[j]]),
|
|
978
|
+
gone: [...oldLeft].map((i) => oldOptions[i]),
|
|
979
|
+
fresh: [...newLeft].sort((a, b) => a - b).map((j) => newOptions[j]),
|
|
211
980
|
};
|
|
212
|
-
|
|
213
|
-
|
|
981
|
+
}
|
|
982
|
+
/**
|
|
983
|
+
* Each option's name in messages and paths: its discriminator value, or its shape
|
|
984
|
+
* (`object{path,url}`, the first three property names). Two options that would
|
|
985
|
+
* share a name get all their property names, then a number.
|
|
986
|
+
*/
|
|
987
|
+
function optionLabels(options, key) {
|
|
988
|
+
const label = (o, all) => {
|
|
989
|
+
if (key && hasProperties(o))
|
|
990
|
+
return `${key}=${JSON.stringify(fixedValue(o.properties[key]))}`;
|
|
991
|
+
if (typeof o.$ref === 'string')
|
|
992
|
+
return `$ref ${o.$ref}`;
|
|
993
|
+
const type = typeOf(o) || 'untyped';
|
|
994
|
+
if (!hasProperties(o))
|
|
995
|
+
return type;
|
|
996
|
+
const names = Object.keys(o.properties).sort();
|
|
997
|
+
return all || names.length <= 3 ? `${type}{${names.join(',')}}` : `${type}{${names.slice(0, 3).join(',')},…}`;
|
|
998
|
+
};
|
|
999
|
+
const short = options.map((o) => label(o, false));
|
|
1000
|
+
const named = options.map((o, i) => (short.filter((s) => s === short[i]).length > 1 ? label(o, true) : short[i]));
|
|
1001
|
+
const seen = new Map();
|
|
1002
|
+
return new Map(options.map((o, i) => {
|
|
1003
|
+
const n = (seen.get(named[i]) ?? 0) + 1;
|
|
1004
|
+
seen.set(named[i], n);
|
|
1005
|
+
return [o, named.filter((s) => s === named[i]).length > 1 ? `${named[i]} #${n}` : named[i]];
|
|
1006
|
+
}));
|
|
1007
|
+
}
|
|
1008
|
+
/**
|
|
1009
|
+
* The same change, said at several places of one tool (a shared definition five
|
|
1010
|
+
* block types use), as one finding that lists them: one change, one line, the
|
|
1011
|
+
* same classification everywhere.
|
|
1012
|
+
*/
|
|
1013
|
+
function collapsePlaces(out, from) {
|
|
1014
|
+
const groups = new Map();
|
|
1015
|
+
for (const r of out.slice(from)) {
|
|
1016
|
+
if (r.group === undefined)
|
|
1017
|
+
continue;
|
|
1018
|
+
groups.set(r.group, [...(groups.get(r.group) ?? []), r]);
|
|
1019
|
+
}
|
|
1020
|
+
for (const list of groups.values()) {
|
|
1021
|
+
if (list.length < 2)
|
|
1022
|
+
continue;
|
|
1023
|
+
const [first, ...rest] = list;
|
|
1024
|
+
// Same field, same schema, in identical enclosing objects: one definition,
|
|
1025
|
+
// reached from several places.
|
|
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`] : [])];
|
|
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'));
|
|
1033
|
+
for (const r of rest)
|
|
1034
|
+
out.splice(out.indexOf(r), 1);
|
|
1035
|
+
}
|
|
1036
|
+
// Grouping across tools goes by place (`place` stays until the finding is finished).
|
|
1037
|
+
for (const r of out.slice(from)) {
|
|
1038
|
+
delete r.group;
|
|
1039
|
+
delete r.node;
|
|
1040
|
+
}
|
|
1041
|
+
}
|
|
1042
|
+
/** A property every option is an object with, and fixes to one value. */
|
|
1043
|
+
function discriminator(options) {
|
|
1044
|
+
// A $ref option (a recursive definition left unexpanded) says nothing either way.
|
|
1045
|
+
const own = options.filter((o) => typeof o.$ref !== 'string');
|
|
1046
|
+
if (own.length === 0 || !own.every(hasProperties))
|
|
1047
|
+
return undefined;
|
|
1048
|
+
const names = Object.keys(own[0].properties).sort();
|
|
1049
|
+
return names.find((n) => own.every((o) => fixedValue(o.properties[n]) !== undefined));
|
|
1050
|
+
}
|
|
1051
|
+
function fixedValue(s) {
|
|
1052
|
+
if (!s)
|
|
1053
|
+
return undefined;
|
|
1054
|
+
if ('const' in s)
|
|
1055
|
+
return s.const;
|
|
1056
|
+
return Array.isArray(s.enum) && s.enum.length === 1 ? s.enum[0] : undefined;
|
|
1057
|
+
}
|
|
1058
|
+
function hasProperties(s) {
|
|
1059
|
+
return !!s && typeof s.properties === 'object' && s.properties !== null && !Array.isArray(s.properties);
|
|
1060
|
+
}
|
|
1061
|
+
/** Nodes a $ref expansion may produce before it gives up and compares the schema as spelled. */
|
|
1062
|
+
const MAX_EXPANDED_NODES = 50_000;
|
|
1063
|
+
/** How many times one $ref is followed inside itself: a recursive schema unrolled this deep. */
|
|
1064
|
+
const MAX_UNROLL = 1;
|
|
1065
|
+
/**
|
|
1066
|
+
* The schema with local $refs (`#/$defs/…`, `#/definitions/…`) replaced by what
|
|
1067
|
+
* they point to, and the root $defs dropped: two spellings of one schema compare
|
|
1068
|
+
* equal. A recursive definition is unrolled MAX_UNROLL level, then left as a
|
|
1069
|
+
* $ref: a change to it shows in the levels above, and its $defs entry needn't be
|
|
1070
|
+
* kept (keeping it made a recursive schema compare unequal to its own refactor,
|
|
1071
|
+
* with nothing reported). A $ref toolmenu can't follow (another document) stays as
|
|
1072
|
+
* it is. Keywords next to a $ref (a description) win over the target's.
|
|
1073
|
+
*/
|
|
1074
|
+
export function resolveRefs(schema) {
|
|
1075
|
+
return expandRefs(schema).schema;
|
|
1076
|
+
}
|
|
1077
|
+
/**
|
|
1078
|
+
* resolveRefs, saying whether it finished: past MAX_EXPANDED_NODES the schema
|
|
1079
|
+
* comes back as written, and `expanded` is false.
|
|
1080
|
+
*/
|
|
1081
|
+
function expandRefs(schema) {
|
|
1082
|
+
if (!schema || typeof schema !== 'object')
|
|
1083
|
+
return { schema, expanded: true };
|
|
1084
|
+
let nodes = 0;
|
|
1085
|
+
const pointer = (ref) => {
|
|
1086
|
+
let node = schema;
|
|
1087
|
+
for (const raw of ref.slice(2).split('/')) {
|
|
1088
|
+
if (!node || typeof node !== 'object')
|
|
1089
|
+
return undefined;
|
|
1090
|
+
node = node[decodeURIComponent(raw).replace(/~1/g, '/').replace(/~0/g, '~')];
|
|
1091
|
+
}
|
|
1092
|
+
return node;
|
|
1093
|
+
};
|
|
1094
|
+
const walk = (node, stack) => {
|
|
1095
|
+
if (++nodes > MAX_EXPANDED_NODES)
|
|
1096
|
+
throw new Error('too large');
|
|
1097
|
+
if (Array.isArray(node))
|
|
1098
|
+
return node.map((x) => walk(x, stack));
|
|
1099
|
+
if (!node || typeof node !== 'object')
|
|
1100
|
+
return node;
|
|
1101
|
+
const o = node;
|
|
1102
|
+
if (typeof o.$ref === 'string') {
|
|
1103
|
+
const target = o.$ref.startsWith('#/') ? pointer(o.$ref) : undefined;
|
|
1104
|
+
if (target && typeof target === 'object' && !Array.isArray(target) && stack.filter((r) => r === o.$ref).length < MAX_UNROLL) {
|
|
1105
|
+
const { $ref: _ref, ...siblings } = o;
|
|
1106
|
+
return { ...walk(target, [...stack, o.$ref]), ...walk(siblings, stack) };
|
|
1107
|
+
}
|
|
1108
|
+
}
|
|
1109
|
+
return Object.fromEntries(Object.entries(o).map(([k, v]) => [k, walk(v, stack)]));
|
|
1110
|
+
};
|
|
1111
|
+
const { $defs: _defs, definitions: _definitions, ...rest } = schema;
|
|
1112
|
+
try {
|
|
1113
|
+
return { schema: unspelled(walk(rest, [])), expanded: true };
|
|
1114
|
+
}
|
|
1115
|
+
catch {
|
|
1116
|
+
return { schema, expanded: false };
|
|
214
1117
|
}
|
|
215
|
-
|
|
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);
|
|
216
1122
|
}
|
|
217
1123
|
/** Operations behind a search tool, compared like tools where both runs found them. */
|
|
218
1124
|
function compareCatalogs(before, after, ignored) {
|
|
219
1125
|
if (!before && !after)
|
|
220
1126
|
return [];
|
|
221
1127
|
if (!before || !after) {
|
|
222
|
-
return [
|
|
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
|
+
];
|
|
223
1135
|
}
|
|
224
1136
|
const out = [];
|
|
225
|
-
const where = `behind ${after
|
|
1137
|
+
const where = `behind ${catalogSource(after)}`;
|
|
226
1138
|
if (JSON.stringify(before.queries) !== JSON.stringify(after.queries)) {
|
|
227
|
-
out.push({
|
|
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
|
+
});
|
|
228
1144
|
}
|
|
229
1145
|
const partial = [before, after].filter((c) => c.failed?.length);
|
|
230
1146
|
if (partial.length) {
|
|
231
|
-
out.push({
|
|
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
|
+
});
|
|
232
1152
|
}
|
|
233
1153
|
const oldOps = new Map(before.operations.filter((o) => !ignored(o.name)).map((o) => [o.name, o]));
|
|
234
1154
|
const newOps = new Map(after.operations.filter((o) => !ignored(o.name)).map((o) => [o.name, o]));
|
|
235
1155
|
for (const [name, op] of newOps) {
|
|
236
1156
|
const old = oldOps.get(name);
|
|
237
1157
|
if (!old) {
|
|
238
|
-
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.` });
|
|
239
1159
|
continue;
|
|
240
1160
|
}
|
|
241
1161
|
for (const r of compareTool(old, op))
|
|
242
|
-
out.push({ ...r, message:
|
|
1162
|
+
out.push({ ...r, message: `Behind ${catalogSource(after)}: ${r.message}`, behind: after.tool });
|
|
243
1163
|
}
|
|
244
1164
|
const missing = [...oldOps.keys()].filter((n) => !newOps.has(n));
|
|
245
1165
|
if (missing.length) {
|
|
246
1166
|
out.push({
|
|
247
1167
|
rule: 'diff/catalog-missing',
|
|
248
|
-
message: `${missing.length} operation${missing.length === 1 ? '' : 's'} ${where} weren't returned by the same queries this time: removed, renamed, or ranked lower.
|
|
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.',
|
|
249
1171
|
});
|
|
250
1172
|
}
|
|
251
1173
|
return out;
|
|
@@ -255,9 +1177,18 @@ const TOOL_FIELDS = new Set(['name', 'description', 'inputSchema', 'outputSchema
|
|
|
255
1177
|
function compareRest(old, t) {
|
|
256
1178
|
const out = [];
|
|
257
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 });
|
|
258
1182
|
if (canonical(old.outputSchema) !== canonical(t.outputSchema)) {
|
|
259
|
-
const what = old.outputSchema === undefined ? 'now declares an outputSchema' : t.outputSchema === undefined ? 'no longer declares an outputSchema' : 'outputSchema
|
|
260
|
-
|
|
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
|
+
});
|
|
261
1192
|
}
|
|
262
1193
|
const a = old.annotations ?? {};
|
|
263
1194
|
const b = t.annotations ?? {};
|
|
@@ -265,22 +1196,47 @@ function compareRest(old, t) {
|
|
|
265
1196
|
// destructiveHint true (meaningful only when not read-only).
|
|
266
1197
|
let safety = false;
|
|
267
1198
|
if (readOnly(a) && !readOnly(b)) {
|
|
268
|
-
out.push({
|
|
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
|
+
});
|
|
269
1205
|
safety = true;
|
|
270
1206
|
}
|
|
271
1207
|
else if (!readOnly(b) && !destructive(a) && destructive(b)) {
|
|
272
|
-
out.push({
|
|
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
|
+
});
|
|
273
1214
|
safety = true;
|
|
274
1215
|
}
|
|
275
1216
|
const changed = [...new Set([...Object.keys(a), ...Object.keys(b)])]
|
|
276
1217
|
.filter((k) => canonical(a[k]) !== canonical(b[k]))
|
|
277
|
-
.map((k) => `${k}
|
|
1218
|
+
.map((k) => `${k} ${show(a[k])} → ${show(b[k])}`);
|
|
278
1219
|
if (changed.length && !safety) {
|
|
279
|
-
|
|
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
|
+
});
|
|
280
1227
|
}
|
|
281
|
-
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();
|
|
282
1229
|
if (others.length) {
|
|
283
|
-
|
|
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
|
+
});
|
|
284
1240
|
}
|
|
285
1241
|
return out;
|
|
286
1242
|
}
|
|
@@ -316,10 +1272,11 @@ function findRenames(removed, added) {
|
|
|
316
1272
|
return pairs;
|
|
317
1273
|
}
|
|
318
1274
|
function paramKey(t) {
|
|
319
|
-
const
|
|
1275
|
+
const schema = resolveRefs(t.inputSchema);
|
|
1276
|
+
const props = Object.keys(schema?.properties ?? {}).sort();
|
|
320
1277
|
if (props.length === 0)
|
|
321
1278
|
return undefined;
|
|
322
|
-
return canonical({ props: Object.fromEntries(props.map((p) => [p, typeOf(
|
|
1279
|
+
return canonical({ props: Object.fromEntries(props.map((p) => [p, typeOf(schema.properties[p])])), required: [...(schema?.required ?? [])].sort() });
|
|
323
1280
|
}
|
|
324
1281
|
/** Does `next` accept every value type that `prev` accepted? */
|
|
325
1282
|
function accepts(next, prev) {
|
|
@@ -335,16 +1292,27 @@ function accepts(next, prev) {
|
|
|
335
1292
|
return false;
|
|
336
1293
|
return [...p].every((t) => n.has(t) || (t === 'integer' && n.has('number')));
|
|
337
1294
|
}
|
|
338
|
-
/**
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
1295
|
+
/**
|
|
1296
|
+
* A parameter's schema without the parts diff classifies itself: with `object`,
|
|
1297
|
+
* its properties, required list and additionalProperties: false (compareObject);
|
|
1298
|
+
* with `items`, its array items; with `union`, its options.
|
|
1299
|
+
*/
|
|
1300
|
+
function residual(schema, nested = {}) {
|
|
1301
|
+
const { type: _t, enum: _e, const: _c, description: _d, ...rest } = schema;
|
|
1302
|
+
// A type written as anyOf/oneOf alternatives is compared as the type; a union's
|
|
1303
|
+
// options are compared one by one.
|
|
1304
|
+
if (typeAlternatives(schema) || nested.union) {
|
|
1305
|
+
delete rest.anyOf;
|
|
1306
|
+
delete rest.oneOf;
|
|
1307
|
+
}
|
|
1308
|
+
if (nested.object) {
|
|
1309
|
+
delete rest.properties;
|
|
1310
|
+
delete rest.required;
|
|
1311
|
+
if (rest.additionalProperties === false)
|
|
1312
|
+
delete rest.additionalProperties;
|
|
347
1313
|
}
|
|
1314
|
+
if (nested.items)
|
|
1315
|
+
delete rest.items;
|
|
348
1316
|
return rest;
|
|
349
1317
|
}
|
|
350
1318
|
function typeOf(schema) {
|
|
@@ -375,26 +1343,65 @@ function typeAlternatives(schema) {
|
|
|
375
1343
|
}
|
|
376
1344
|
return types;
|
|
377
1345
|
}
|
|
1346
|
+
/** The values a schema limits itself to: its enum, or a const as a one-value enum. */
|
|
1347
|
+
function allowedValues(schema) {
|
|
1348
|
+
if (Array.isArray(schema.enum))
|
|
1349
|
+
return schema.enum;
|
|
1350
|
+
return 'const' in schema ? [schema.const] : undefined;
|
|
1351
|
+
}
|
|
378
1352
|
function enumChange(before, after) {
|
|
379
|
-
const a = before
|
|
380
|
-
const b = after
|
|
1353
|
+
const a = allowedValues(before);
|
|
1354
|
+
const b = allowedValues(after);
|
|
381
1355
|
if (!a && !b)
|
|
382
1356
|
return undefined;
|
|
383
|
-
if (!a && b)
|
|
384
|
-
return { rule: 'diff/enum-narrowed',
|
|
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
|
+
}
|
|
385
1360
|
if (a && !b)
|
|
386
|
-
return { rule: 'diff/enum-widened',
|
|
1361
|
+
return { rule: 'diff/enum-widened', head: ': no longer limited to a fixed set of values', tail: '' };
|
|
387
1362
|
const gone = a.filter((v) => !b.some((w) => canonical(w) === canonical(v)));
|
|
388
1363
|
const fresh = b.filter((v) => !a.some((w) => canonical(w) === canonical(v)));
|
|
389
|
-
if (gone.length)
|
|
390
|
-
return {
|
|
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
|
+
}
|
|
391
1372
|
if (fresh.length)
|
|
392
|
-
return { rule: 'diff/enum-widened',
|
|
1373
|
+
return { rule: 'diff/enum-widened', head: `: now also accepts ${values(fresh)}`, tail: '' };
|
|
393
1374
|
return undefined;
|
|
394
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
|
+
*/
|
|
395
1381
|
function textDiff(before, after) {
|
|
396
1382
|
const cut = (s) => (s.length > 240 ? s.slice(0, 237) + '…' : s);
|
|
397
|
-
|
|
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)')}`];
|
|
398
1405
|
}
|
|
399
1406
|
function tokenChange(before, after) {
|
|
400
1407
|
const names = new Set([...before, ...after].map((t) => t.name));
|
|
@@ -421,15 +1428,19 @@ function bumpFor(classes) {
|
|
|
421
1428
|
return 'patch';
|
|
422
1429
|
return 'none';
|
|
423
1430
|
}
|
|
424
|
-
/**
|
|
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
|
+
*/
|
|
425
1437
|
function requiredBump(suggested, version) {
|
|
426
1438
|
const v = parseSemver(version);
|
|
427
|
-
|
|
428
|
-
|
|
1439
|
+
if (!v || v.nums[0] !== 0)
|
|
1440
|
+
return suggested;
|
|
1441
|
+
if (v.nums[1] === 0)
|
|
429
1442
|
return 'none';
|
|
430
|
-
|
|
431
|
-
return 'minor';
|
|
432
|
-
return suggested;
|
|
1443
|
+
return suggested === 'major' ? 'minor' : suggested === 'minor' ? 'patch' : suggested;
|
|
433
1444
|
}
|
|
434
1445
|
/** Why a bump can't be judged: not semver, calendar, prerelease, or backwards. */
|
|
435
1446
|
function whyNotChecked(before, after) {
|