toolmenu 0.7.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/LICENSE +21 -0
- package/README.md +311 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +283 -0
- package/dist/compare.d.ts +32 -0
- package/dist/compare.js +108 -0
- package/dist/config.d.ts +19 -0
- package/dist/config.js +27 -0
- package/dist/connect.d.ts +66 -0
- package/dist/connect.js +122 -0
- package/dist/diff.d.ts +58 -0
- package/dist/diff.js +404 -0
- package/dist/history.d.ts +88 -0
- package/dist/history.js +219 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +9 -0
- package/dist/menu.d.ts +9 -0
- package/dist/menu.js +57 -0
- package/dist/report.d.ts +11 -0
- package/dist/report.js +278 -0
- package/dist/routes.d.ts +22 -0
- package/dist/routes.js +76 -0
- package/dist/rules/description.d.ts +28 -0
- package/dist/rules/description.js +158 -0
- package/dist/rules/determinism.d.ts +2 -0
- package/dist/rules/determinism.js +35 -0
- package/dist/rules/ids.d.ts +11 -0
- package/dist/rules/ids.js +138 -0
- package/dist/rules/index.d.ts +11 -0
- package/dist/rules/index.js +42 -0
- package/dist/rules/naming.d.ts +4 -0
- package/dist/rules/naming.js +145 -0
- package/dist/rules/rule.d.ts +33 -0
- package/dist/rules/rule.js +1 -0
- package/dist/rules/spec.d.ts +5 -0
- package/dist/rules/spec.js +102 -0
- package/dist/rules/write.d.ts +3 -0
- package/dist/rules/write.js +55 -0
- package/dist/semver.d.ts +11 -0
- package/dist/semver.js +41 -0
- package/dist/session.d.ts +90 -0
- package/dist/session.js +519 -0
- package/dist/snapshot.d.ts +16 -0
- package/dist/snapshot.js +42 -0
- package/dist/types.d.ts +49 -0
- package/dist/types.js +1 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +3 -0
- package/dist/words.d.ts +14 -0
- package/dist/words.js +63 -0
- package/package.json +57 -0
- package/schemas/2024-11-05.json +2077 -0
- package/schemas/2025-03-26.json +2139 -0
- package/schemas/2025-06-18.json +2517 -0
- package/schemas/2025-11-25.json +4058 -0
- package/schemas/2026-07-28.json +3963 -0
package/dist/diff.js
ADDED
|
@@ -0,0 +1,404 @@
|
|
|
1
|
+
import { canonical, compareMenus } from './compare.js';
|
|
2
|
+
import { isCalendar, parseSemver } from './semver.js';
|
|
3
|
+
import { SEVERITY_RANK } from './types.js';
|
|
4
|
+
/** Every diff rule, its default severity and what it means for semver. */
|
|
5
|
+
export const DIFF_RULES = {
|
|
6
|
+
'diff/tool-removed': { severity: 'error', class: 'breaking' },
|
|
7
|
+
'diff/tool-renamed': { severity: 'error', class: 'breaking' },
|
|
8
|
+
'diff/param-removed': { severity: 'error', class: 'breaking' },
|
|
9
|
+
'diff/param-required': { severity: 'error', class: 'breaking' },
|
|
10
|
+
'diff/param-type': { severity: 'error', class: 'breaking' },
|
|
11
|
+
'diff/enum-narrowed': { severity: 'error', class: 'breaking' },
|
|
12
|
+
'diff/safety-hint': { severity: 'error', class: 'breaking' },
|
|
13
|
+
'diff/tool-added': { severity: 'info', class: 'minor' },
|
|
14
|
+
'diff/param-added': { severity: 'info', class: 'minor' },
|
|
15
|
+
'diff/param-relaxed': { severity: 'info', class: 'minor' },
|
|
16
|
+
'diff/enum-widened': { severity: 'info', class: 'minor' },
|
|
17
|
+
'diff/type-widened': { severity: 'info', class: 'minor' },
|
|
18
|
+
'diff/description': { severity: 'info', class: 'notice' },
|
|
19
|
+
'diff/param-dropped': { severity: 'info', class: 'notice' },
|
|
20
|
+
'diff/schema-other': { severity: 'info', class: 'notice' },
|
|
21
|
+
'diff/annotations': { severity: 'info', class: 'notice' },
|
|
22
|
+
'diff/other': { severity: 'info', class: 'notice' },
|
|
23
|
+
'diff/order': { severity: 'info', class: 'notice' },
|
|
24
|
+
'diff/version-bump': { severity: 'warn' },
|
|
25
|
+
'diff/version-backwards': { severity: 'warn' },
|
|
26
|
+
'diff/token-budget': { severity: 'error' },
|
|
27
|
+
};
|
|
28
|
+
export function diffMenus(before, after, options = {}) {
|
|
29
|
+
const raw = [];
|
|
30
|
+
// Ignored tools leave the comparison entirely, so they can't pair into a
|
|
31
|
+
// rename or show up as a reorder.
|
|
32
|
+
const ignored = ignoreMatcher(options.ignore);
|
|
33
|
+
const oldTools = before.tools.filter((t) => !ignored(t.name));
|
|
34
|
+
const newTools = after.tools.filter((t) => !ignored(t.name));
|
|
35
|
+
const oldByName = new Map(oldTools.map((t) => [t.name, t]));
|
|
36
|
+
const newByName = new Map(newTools.map((t) => [t.name, t]));
|
|
37
|
+
const removed = oldTools.filter((t) => !newByName.has(t.name));
|
|
38
|
+
const added = newTools.filter((t) => !oldByName.has(t.name));
|
|
39
|
+
const renames = findRenames(removed, added);
|
|
40
|
+
const renamedFrom = new Set(renames.map((r) => r.from.name));
|
|
41
|
+
const renamedTo = new Set(renames.map((r) => r.to.name));
|
|
42
|
+
for (const { from, to } of renames) {
|
|
43
|
+
raw.push({ rule: 'diff/tool-renamed', tool: to.name, message: `${from.name} was renamed to ${to.name} (same parameters). Agents, saved prompts and evals that call ${from.name} break.` });
|
|
44
|
+
}
|
|
45
|
+
for (const t of removed.filter((t) => !renamedFrom.has(t.name))) {
|
|
46
|
+
raw.push({ rule: 'diff/tool-removed', tool: t.name, message: `${t.name} was removed. Anything that calls it breaks.` });
|
|
47
|
+
}
|
|
48
|
+
for (const t of added.filter((t) => !renamedTo.has(t.name))) {
|
|
49
|
+
raw.push({ rule: 'diff/tool-added', tool: t.name, message: `${t.name} was added (~${t.tokens} tokens).` });
|
|
50
|
+
}
|
|
51
|
+
for (const t of newTools) {
|
|
52
|
+
const old = oldByName.get(t.name);
|
|
53
|
+
if (old)
|
|
54
|
+
raw.push(...compareTool(old, t));
|
|
55
|
+
}
|
|
56
|
+
for (const { from, to } of renames)
|
|
57
|
+
raw.push(...compareTool(from, to).filter((f) => f.rule !== 'diff/description' && f.rule !== 'diff/other'));
|
|
58
|
+
const moved = compareMenus(oldTools, newTools).filter((c) => c.kind === 'moved');
|
|
59
|
+
if (moved.length) {
|
|
60
|
+
raw.push({
|
|
61
|
+
rule: 'diff/order',
|
|
62
|
+
message: `Tool order changed (${moved.map((m) => m.tool).join(', ')}). Only a notice between releases: prompt caches are short-lived, so a deploy costs roughly one rewrite. It matters within a session.`,
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
// Ignored tools leave the token counts and the budget too.
|
|
66
|
+
const tokens = tokenChange(oldTools, newTools);
|
|
67
|
+
if (options.tokenBudget !== undefined && tokens.after > options.tokenBudget) {
|
|
68
|
+
raw.push({
|
|
69
|
+
rule: 'diff/token-budget',
|
|
70
|
+
message: `The menu is ~${fmt(tokens.after)} tokens, over the budget of ${fmt(options.tokenBudget)} (estimate).`,
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
// Only what survives ignore and 'off' counts toward the bump. Settled once:
|
|
74
|
+
// the bump and the reported findings come from the same list.
|
|
75
|
+
const changes = settle(raw, options);
|
|
76
|
+
const suggestedBump = bumpFor(changes.map((f) => f.class));
|
|
77
|
+
const versionRaw = [];
|
|
78
|
+
const release = options.release
|
|
79
|
+
? { ...options.release, source: 'release' }
|
|
80
|
+
: options.serverVersionIsRelease && before.server.version && after.server.version
|
|
81
|
+
? { before: before.server.version, after: after.server.version, source: 'server' }
|
|
82
|
+
: undefined;
|
|
83
|
+
const actualBump = release ? versionBump(release.before, release.after) : undefined;
|
|
84
|
+
const notChecked = release && !actualBump ? whyNotChecked(release.before, release.after) : undefined;
|
|
85
|
+
if (release && notChecked === 'version went backwards') {
|
|
86
|
+
versionRaw.push({
|
|
87
|
+
rule: 'diff/version-backwards',
|
|
88
|
+
message: release.source === 'server'
|
|
89
|
+
? `The server-reported version went backwards: ${release.before} → ${release.after}.`
|
|
90
|
+
: `${release.before} → ${release.after}: the version went backwards. Check the --release order.`,
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
const required = requiredBump(suggestedBump, release?.before);
|
|
94
|
+
if (release && actualBump && BUMP_RANK[actualBump] < BUMP_RANK[required]) {
|
|
95
|
+
const what = release.source === 'server' ? 'The server-reported version' : 'The release version';
|
|
96
|
+
versionRaw.push({
|
|
97
|
+
rule: 'diff/version-bump',
|
|
98
|
+
message: actualBump === 'none'
|
|
99
|
+
? `${what} stayed ${release.after} but the menu has ${suggestedBump === 'major' ? 'breaking' : suggestedBump === 'minor' ? 'new' : 'changed'} parts. Suggested: a ${required} bump.`
|
|
100
|
+
: `${release.before} → ${release.after} is a ${actualBump} bump, but the menu has ${suggestedBump === 'major' ? 'breaking changes' : 'new features'}. Suggested: a ${required} bump.`,
|
|
101
|
+
});
|
|
102
|
+
}
|
|
103
|
+
return {
|
|
104
|
+
before: before.server,
|
|
105
|
+
after: after.server,
|
|
106
|
+
findings: [...changes, ...settle(versionRaw, options)].sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]),
|
|
107
|
+
tokens,
|
|
108
|
+
suggestedBump,
|
|
109
|
+
...(actualBump ? { actualBump } : {}),
|
|
110
|
+
...(release ? { release } : {}),
|
|
111
|
+
...(notChecked ? { bumpNotChecked: notChecked } : {}),
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
function compareTool(old, t) {
|
|
115
|
+
const out = [];
|
|
116
|
+
const name = t.name;
|
|
117
|
+
if ((old.description ?? '') !== (t.description ?? '')) {
|
|
118
|
+
out.push({ rule: 'diff/description', tool: name, message: `${name}: description changed. It doesn't break the protocol, but it changes what the agent does.`, detail: textDiff(old.description ?? '', t.description ?? '') });
|
|
119
|
+
}
|
|
120
|
+
const oldEmpty = isEmptySchema(old.inputSchema);
|
|
121
|
+
const newEmpty = isEmptySchema(t.inputSchema);
|
|
122
|
+
if (oldEmpty || newEmpty) {
|
|
123
|
+
if (canonical(old.inputSchema) !== canonical(t.inputSchema)) {
|
|
124
|
+
out.push({
|
|
125
|
+
rule: 'diff/schema-other',
|
|
126
|
+
tool: name,
|
|
127
|
+
message: `${name}: the ${oldEmpty ? 'old' : 'new'} inputSchema is empty or invalid (no type, no properties), so parameter changes can't be classified.`,
|
|
128
|
+
});
|
|
129
|
+
}
|
|
130
|
+
return out.concat(compareRest(old, t));
|
|
131
|
+
}
|
|
132
|
+
const oldProps = old.inputSchema?.properties ?? {};
|
|
133
|
+
const newProps = t.inputSchema?.properties ?? {};
|
|
134
|
+
const oldReq = new Set(old.inputSchema?.required ?? []);
|
|
135
|
+
const newReq = new Set(t.inputSchema?.required ?? []);
|
|
136
|
+
// Removing an optional parameter only breaks callers if the new schema rejects
|
|
137
|
+
// unknown properties; otherwise calls that still send it stay valid.
|
|
138
|
+
const closed = t.inputSchema?.additionalProperties === false;
|
|
139
|
+
for (const p of Object.keys(oldProps)) {
|
|
140
|
+
if (!(p in newProps)) {
|
|
141
|
+
out.push(oldReq.has(p) || closed
|
|
142
|
+
? { rule: 'diff/param-removed', tool: name, message: `${name}.${p} was removed. Calls that pass it can fail.` }
|
|
143
|
+
: { rule: 'diff/param-dropped', tool: name, message: `${name}.${p} (optional) was removed. Calls that still send it stay valid, but the server may ignore it.` });
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
for (const [p, schema] of Object.entries(newProps)) {
|
|
147
|
+
const before = oldProps[p];
|
|
148
|
+
if (!before) {
|
|
149
|
+
out.push(newReq.has(p)
|
|
150
|
+
? { rule: 'diff/param-required', tool: name, message: `${name}.${p} is new and required. Existing calls don't send it.` }
|
|
151
|
+
: { rule: 'diff/param-added', tool: name, message: `${name}.${p} is a new optional parameter.` });
|
|
152
|
+
continue;
|
|
153
|
+
}
|
|
154
|
+
if (!oldReq.has(p) && newReq.has(p)) {
|
|
155
|
+
out.push({ rule: 'diff/param-required', tool: name, message: `${name}.${p} was optional and is now required.` });
|
|
156
|
+
}
|
|
157
|
+
else if (oldReq.has(p) && !newReq.has(p)) {
|
|
158
|
+
out.push({ rule: 'diff/param-relaxed', tool: name, message: `${name}.${p} was required and is now optional.` });
|
|
159
|
+
}
|
|
160
|
+
const oldType = typeOf(before);
|
|
161
|
+
const newType = typeOf(schema);
|
|
162
|
+
if (oldType !== newType) {
|
|
163
|
+
// Widening (boolean → boolean|string, object → any) accepts every call that
|
|
164
|
+
// worked before; only a narrower or different type breaks callers.
|
|
165
|
+
out.push(accepts(schema, before)
|
|
166
|
+
? { rule: 'diff/type-widened', tool: name, message: `${name}.${p} now accepts more types: ${oldType || 'any'} → ${newType || 'any'}.` }
|
|
167
|
+
: { rule: 'diff/param-type', tool: name, message: `${name}.${p} changed type: ${oldType || 'any'} → ${newType || 'any'}. Calls that worked before can fail.` });
|
|
168
|
+
}
|
|
169
|
+
const e = enumChange(before, schema);
|
|
170
|
+
if (e) {
|
|
171
|
+
out.push({ rule: e.rule, tool: name, message: `${name}.${p}: ${e.message}` });
|
|
172
|
+
}
|
|
173
|
+
// Array parameters: the element type and allowed values count like the
|
|
174
|
+
// parameter's own (no items schema = any element).
|
|
175
|
+
const isArray = (s) => (Array.isArray(s.type) ? s.type.includes('array') : s.type === 'array');
|
|
176
|
+
if (isArray(before) && isArray(schema)) {
|
|
177
|
+
const oldItems = before.items ?? {};
|
|
178
|
+
const newItems = schema.items ?? {};
|
|
179
|
+
const oldItemType = typeOf(oldItems);
|
|
180
|
+
const newItemType = typeOf(newItems);
|
|
181
|
+
if (oldItemType !== newItemType) {
|
|
182
|
+
out.push(accepts(newItems, oldItems)
|
|
183
|
+
? { rule: 'diff/type-widened', tool: name, message: `${name}.${p} (array items) now accept more types: ${oldItemType || 'any'} → ${newItemType || 'any'}.` }
|
|
184
|
+
: { rule: 'diff/param-type', tool: name, message: `${name}.${p} (array items) changed type: ${oldItemType || 'any'} → ${newItemType || 'any'}. Calls that worked before can fail.` });
|
|
185
|
+
}
|
|
186
|
+
const ie = enumChange(oldItems, newItems);
|
|
187
|
+
if (ie)
|
|
188
|
+
out.push({ rule: ie.rule, tool: name, message: `${name}.${p} (array items): ${ie.message}` });
|
|
189
|
+
}
|
|
190
|
+
if ((before.description ?? '') !== (schema.description ?? '')) {
|
|
191
|
+
out.push({ rule: 'diff/description', tool: name, message: `${name}.${p}: parameter description changed.`, detail: textDiff(String(before.description ?? ''), String(schema.description ?? '')) });
|
|
192
|
+
}
|
|
193
|
+
// Whatever changed beyond type, enum and description is checked per
|
|
194
|
+
// parameter, so a classified change elsewhere can't hide it.
|
|
195
|
+
// A breaking type change already covers a reshaped schema: no duplicate
|
|
196
|
+
// notice. A widened type can still bring new constraints, so it's checked.
|
|
197
|
+
if ((oldType === newType || accepts(schema, before)) && canonical(residual(before)) !== canonical(residual(schema))) {
|
|
198
|
+
out.push({ rule: 'diff/schema-other', tool: name, message: `${name}.${p}: changed in a way toolmenu doesn't classify (nested fields, constraints…). Review it.` });
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
const shell = (s) => {
|
|
202
|
+
const { properties: _p, required: _r, ...rest } = (s ?? {});
|
|
203
|
+
return rest;
|
|
204
|
+
};
|
|
205
|
+
if (canonical(shell(old.inputSchema)) !== canonical(shell(t.inputSchema))) {
|
|
206
|
+
out.push({ rule: 'diff/schema-other', tool: name, message: `${name}: inputSchema changed outside its parameters (additionalProperties, $defs…). Review it.` });
|
|
207
|
+
}
|
|
208
|
+
return out.concat(compareRest(old, t));
|
|
209
|
+
}
|
|
210
|
+
const TOOL_FIELDS = new Set(['name', 'description', 'inputSchema', 'outputSchema', 'annotations', 'tokens']);
|
|
211
|
+
/** Output schema, annotations and any other fields (title, icons, _meta…). */
|
|
212
|
+
function compareRest(old, t) {
|
|
213
|
+
const out = [];
|
|
214
|
+
const name = t.name;
|
|
215
|
+
if (canonical(old.outputSchema) !== canonical(t.outputSchema)) {
|
|
216
|
+
const what = old.outputSchema === undefined ? 'now declares an outputSchema' : t.outputSchema === undefined ? 'no longer declares an outputSchema' : 'outputSchema changed';
|
|
217
|
+
out.push({ rule: 'diff/schema-other', tool: name, message: `${name}: ${what}. Clients that validate structured output may notice.` });
|
|
218
|
+
}
|
|
219
|
+
const a = old.annotations ?? {};
|
|
220
|
+
const b = t.annotations ?? {};
|
|
221
|
+
// Compare effective hints, with the spec's defaults: readOnlyHint false,
|
|
222
|
+
// destructiveHint true (meaningful only when not read-only).
|
|
223
|
+
let safety = false;
|
|
224
|
+
if (readOnly(a) && !readOnly(b)) {
|
|
225
|
+
out.push({ rule: 'diff/safety-hint', tool: name, message: `${name} is no longer read-only. Clients and agents that auto-approve read-only tools will now call something that writes.` });
|
|
226
|
+
safety = true;
|
|
227
|
+
}
|
|
228
|
+
else if (!readOnly(b) && !destructive(a) && destructive(b)) {
|
|
229
|
+
out.push({ rule: 'diff/safety-hint', tool: name, message: `${name} was additive-only and is now destructive.` });
|
|
230
|
+
safety = true;
|
|
231
|
+
}
|
|
232
|
+
const changed = [...new Set([...Object.keys(a), ...Object.keys(b)])]
|
|
233
|
+
.filter((k) => canonical(a[k]) !== canonical(b[k]))
|
|
234
|
+
.map((k) => `${k}: ${show(a[k])} → ${show(b[k])}`);
|
|
235
|
+
if (changed.length && !safety) {
|
|
236
|
+
out.push({ rule: 'diff/annotations', tool: name, message: `${name}: annotations changed (${changed.join(', ')}).` });
|
|
237
|
+
}
|
|
238
|
+
const others = [...new Set([...Object.keys(old), ...Object.keys(t)])].filter((k) => !TOOL_FIELDS.has(k) && canonical(old[k]) !== canonical(t[k]));
|
|
239
|
+
if (others.length) {
|
|
240
|
+
out.push({ rule: 'diff/other', tool: name, message: `${name}: ${others.join(', ')} changed.` });
|
|
241
|
+
}
|
|
242
|
+
return out;
|
|
243
|
+
}
|
|
244
|
+
function readOnly(a) {
|
|
245
|
+
return a.readOnlyHint === true;
|
|
246
|
+
}
|
|
247
|
+
function destructive(a) {
|
|
248
|
+
return !readOnly(a) && a.destructiveHint !== false;
|
|
249
|
+
}
|
|
250
|
+
function show(value) {
|
|
251
|
+
return value === undefined ? '(unset)' : JSON.stringify(value);
|
|
252
|
+
}
|
|
253
|
+
function isEmptySchema(schema) {
|
|
254
|
+
return !schema || (schema.type === undefined && schema.properties === undefined);
|
|
255
|
+
}
|
|
256
|
+
/** Removed + added tools with the same non-empty parameter names and required set. */
|
|
257
|
+
function findRenames(removed, added) {
|
|
258
|
+
const pairs = [];
|
|
259
|
+
const used = new Set();
|
|
260
|
+
for (const from of removed) {
|
|
261
|
+
const key = paramKey(from);
|
|
262
|
+
if (!key)
|
|
263
|
+
continue;
|
|
264
|
+
const matches = added.filter((to) => !used.has(to.name) && paramKey(to) === key);
|
|
265
|
+
if (matches.length === 1) {
|
|
266
|
+
pairs.push({ from, to: matches[0] });
|
|
267
|
+
used.add(matches[0].name);
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
return pairs;
|
|
271
|
+
}
|
|
272
|
+
function paramKey(t) {
|
|
273
|
+
const props = Object.keys(t.inputSchema?.properties ?? {}).sort();
|
|
274
|
+
if (props.length === 0)
|
|
275
|
+
return undefined;
|
|
276
|
+
return canonical({ props: Object.fromEntries(props.map((p) => [p, typeOf(t.inputSchema.properties[p])])), required: [...(t.inputSchema?.required ?? [])].sort() });
|
|
277
|
+
}
|
|
278
|
+
/** Does `next` accept every value type that `prev` accepted? */
|
|
279
|
+
function accepts(next, prev) {
|
|
280
|
+
const types = (s) => (s.type === undefined ? undefined : new Set(Array.isArray(s.type) ? s.type : [s.type]));
|
|
281
|
+
const n = types(next);
|
|
282
|
+
const p = types(prev);
|
|
283
|
+
if (!n)
|
|
284
|
+
return true; // no type: anything goes
|
|
285
|
+
if (!p)
|
|
286
|
+
return false;
|
|
287
|
+
return [...p].every((t) => n.has(t) || (t === 'integer' && n.has('number')));
|
|
288
|
+
}
|
|
289
|
+
/** A parameter's schema without the parts diff classifies itself. */
|
|
290
|
+
function residual(schema) {
|
|
291
|
+
const { type: _t, enum: _e, description: _d, items, ...rest } = schema;
|
|
292
|
+
if (items && typeof items === 'object') {
|
|
293
|
+
const { enum: _ie, type: _it, ...itemRest } = items;
|
|
294
|
+
return Object.keys(itemRest).length ? { ...rest, items: itemRest } : rest;
|
|
295
|
+
}
|
|
296
|
+
return rest;
|
|
297
|
+
}
|
|
298
|
+
function typeOf(schema) {
|
|
299
|
+
const t = schema.type;
|
|
300
|
+
return Array.isArray(t) ? [...t].sort().join('|') : t ?? '';
|
|
301
|
+
}
|
|
302
|
+
function enumChange(before, after) {
|
|
303
|
+
const a = before.enum;
|
|
304
|
+
const b = after.enum;
|
|
305
|
+
if (!a && !b)
|
|
306
|
+
return undefined;
|
|
307
|
+
if (!a && b)
|
|
308
|
+
return { rule: 'diff/enum-narrowed', message: `now limited to ${b.map(String).join(', ')}.` };
|
|
309
|
+
if (a && !b)
|
|
310
|
+
return { rule: 'diff/enum-widened', message: `no longer limited to a fixed set of values.` };
|
|
311
|
+
const gone = a.filter((v) => !b.some((w) => canonical(w) === canonical(v)));
|
|
312
|
+
const fresh = b.filter((v) => !a.some((w) => canonical(w) === canonical(v)));
|
|
313
|
+
if (gone.length)
|
|
314
|
+
return { rule: 'diff/enum-narrowed', message: `no longer accepts ${gone.map(String).join(', ')}.` };
|
|
315
|
+
if (fresh.length)
|
|
316
|
+
return { rule: 'diff/enum-widened', message: `now also accepts ${fresh.map(String).join(', ')}.` };
|
|
317
|
+
return undefined;
|
|
318
|
+
}
|
|
319
|
+
function textDiff(before, after) {
|
|
320
|
+
const cut = (s) => (s.length > 240 ? s.slice(0, 237) + '…' : s);
|
|
321
|
+
return [`- ${cut(before) || '(none)'}`, `+ ${cut(after) || '(none)'}`];
|
|
322
|
+
}
|
|
323
|
+
function tokenChange(before, after) {
|
|
324
|
+
const names = new Set([...before, ...after].map((t) => t.name));
|
|
325
|
+
const oldTokens = new Map(before.map((t) => [t.name, t.tokens]));
|
|
326
|
+
const newTokens = new Map(after.map((t) => [t.name, t.tokens]));
|
|
327
|
+
const tools = [...names]
|
|
328
|
+
.map((name) => {
|
|
329
|
+
const b = oldTokens.get(name) ?? 0;
|
|
330
|
+
const a = newTokens.get(name) ?? 0;
|
|
331
|
+
return { name, before: b, after: a, delta: a - b };
|
|
332
|
+
})
|
|
333
|
+
.filter((t) => t.delta !== 0)
|
|
334
|
+
.sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta));
|
|
335
|
+
const total = (tools) => tools.reduce((sum, t) => sum + t.tokens, 0);
|
|
336
|
+
return { before: total(before), after: total(after), delta: total(after) - total(before), tools };
|
|
337
|
+
}
|
|
338
|
+
const BUMP_RANK = { none: 0, patch: 1, minor: 2, major: 3 };
|
|
339
|
+
function bumpFor(classes) {
|
|
340
|
+
if (classes.includes('breaking'))
|
|
341
|
+
return 'major';
|
|
342
|
+
if (classes.includes('minor'))
|
|
343
|
+
return 'minor';
|
|
344
|
+
if (classes.includes('notice'))
|
|
345
|
+
return 'patch';
|
|
346
|
+
return 'none';
|
|
347
|
+
}
|
|
348
|
+
/** Under 1.0.0, semver lets a minor bump carry breaking changes. */
|
|
349
|
+
function requiredBump(suggested, version) {
|
|
350
|
+
const v = parseSemver(version);
|
|
351
|
+
// 0.0.x promises nothing; 0.x lets a minor bump break.
|
|
352
|
+
if (v && v.nums[0] === 0 && v.nums[1] === 0)
|
|
353
|
+
return 'none';
|
|
354
|
+
if (v && v.nums[0] === 0 && suggested === 'major')
|
|
355
|
+
return 'minor';
|
|
356
|
+
return suggested;
|
|
357
|
+
}
|
|
358
|
+
/** Why a bump can't be judged: not semver, calendar, prerelease, or backwards. */
|
|
359
|
+
function whyNotChecked(before, after) {
|
|
360
|
+
const a = parseSemver(before);
|
|
361
|
+
const b = parseSemver(after);
|
|
362
|
+
if (!a || !b)
|
|
363
|
+
return 'not semver';
|
|
364
|
+
if (isCalendar(a) || isCalendar(b))
|
|
365
|
+
return 'calendar version';
|
|
366
|
+
if (a.pre || b.pre)
|
|
367
|
+
return 'prerelease';
|
|
368
|
+
return 'version went backwards';
|
|
369
|
+
}
|
|
370
|
+
export function versionBump(before, after) {
|
|
371
|
+
const a = parseSemver(before);
|
|
372
|
+
const b = parseSemver(after);
|
|
373
|
+
if (!a || !b)
|
|
374
|
+
return undefined;
|
|
375
|
+
// Calendar versions and prereleases make no compatibility promise to compare.
|
|
376
|
+
if (isCalendar(a) || isCalendar(b) || a.pre || b.pre)
|
|
377
|
+
return undefined;
|
|
378
|
+
for (const [i, bump] of [[0, 'major'], [1, 'minor'], [2, 'patch']]) {
|
|
379
|
+
if (b.nums[i] !== a.nums[i])
|
|
380
|
+
return b.nums[i] > a.nums[i] ? bump : undefined;
|
|
381
|
+
}
|
|
382
|
+
return 'none';
|
|
383
|
+
}
|
|
384
|
+
function ignoreMatcher(globs) {
|
|
385
|
+
const res = (globs ?? []).map((g) => new RegExp('^' + g.split('*').map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$'));
|
|
386
|
+
return (name) => res.some((re) => re.test(name));
|
|
387
|
+
}
|
|
388
|
+
function settle(raw, options) {
|
|
389
|
+
const ignored = ignoreMatcher(options.ignore);
|
|
390
|
+
const findings = [];
|
|
391
|
+
for (const r of raw) {
|
|
392
|
+
const configured = options.rules?.[r.rule];
|
|
393
|
+
if (configured === 'off')
|
|
394
|
+
continue;
|
|
395
|
+
if (r.tool && ignored(r.tool))
|
|
396
|
+
continue;
|
|
397
|
+
const rule = DIFF_RULES[r.rule];
|
|
398
|
+
findings.push({ ...r, severity: configured ?? rule.severity, ...(rule.class ? { class: rule.class } : {}) });
|
|
399
|
+
}
|
|
400
|
+
return findings.sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]);
|
|
401
|
+
}
|
|
402
|
+
function fmt(n) {
|
|
403
|
+
return n.toLocaleString('en-US');
|
|
404
|
+
}
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import { compareVersions } from './semver.js';
|
|
2
|
+
import { type Bump } from './diff.js';
|
|
3
|
+
import type { Severity } from './types.js';
|
|
4
|
+
export interface PublishedVersion {
|
|
5
|
+
version: string;
|
|
6
|
+
/** ISO publish time, when the registry says. */
|
|
7
|
+
published?: string;
|
|
8
|
+
}
|
|
9
|
+
/** Where versions come from and how they get installed. Swappable for tests. */
|
|
10
|
+
export interface PackageSource {
|
|
11
|
+
versions(pkg: string): Promise<PublishedVersion[]>;
|
|
12
|
+
install(pkg: string, version: string, dir: string, options: {
|
|
13
|
+
allowScripts: boolean;
|
|
14
|
+
timeoutMs: number;
|
|
15
|
+
}): Promise<void>;
|
|
16
|
+
}
|
|
17
|
+
/** The npm registry, through the user's own npm (their config, proxy and registry). */
|
|
18
|
+
export declare const npmSource: PackageSource;
|
|
19
|
+
export type FailureReason = 'install-failed' | 'no-bin' | 'needs-env' | 'needs-args' | 'timeout' | 'crashed';
|
|
20
|
+
/** Dependencies worth recording: they decide the protocol and how schemas get built (FINDINGS F4). */
|
|
21
|
+
export declare const WATCHED_DEPENDENCIES: string[];
|
|
22
|
+
export interface HistoryRow {
|
|
23
|
+
version: string;
|
|
24
|
+
published?: string;
|
|
25
|
+
status: 'ok' | 'failed';
|
|
26
|
+
reason?: FailureReason;
|
|
27
|
+
error?: string;
|
|
28
|
+
/** What the package asks for (its package.json). */
|
|
29
|
+
declared?: Record<string, string>;
|
|
30
|
+
/** What npm actually installed today, every copy in the tree. */
|
|
31
|
+
resolved?: Record<string, string[]>;
|
|
32
|
+
protocolVersion?: string;
|
|
33
|
+
/** What the server says about itself. Often not the npm version (FINDINGS F5). */
|
|
34
|
+
serverInfo?: {
|
|
35
|
+
name?: string;
|
|
36
|
+
version?: string;
|
|
37
|
+
};
|
|
38
|
+
tools?: number;
|
|
39
|
+
tokens?: number;
|
|
40
|
+
counts?: Record<Severity, number>;
|
|
41
|
+
rules?: Record<string, number>;
|
|
42
|
+
/** Compared with the previous version that worked. */
|
|
43
|
+
diff?: {
|
|
44
|
+
from: string;
|
|
45
|
+
tokenDelta: number;
|
|
46
|
+
breaking: number;
|
|
47
|
+
minor: number;
|
|
48
|
+
notice: number;
|
|
49
|
+
suggestedBump: Bump;
|
|
50
|
+
actualBump?: Bump;
|
|
51
|
+
/** The release's version bump is smaller than its changes call for (diff/version-bump). */
|
|
52
|
+
bumpTooSmall: boolean;
|
|
53
|
+
breakingChanges: string[];
|
|
54
|
+
};
|
|
55
|
+
menuFile?: string;
|
|
56
|
+
}
|
|
57
|
+
export interface HistoryResult {
|
|
58
|
+
package: string;
|
|
59
|
+
installedAt: string;
|
|
60
|
+
totalVersions: number;
|
|
61
|
+
rows: HistoryRow[];
|
|
62
|
+
}
|
|
63
|
+
export interface HistoryOptions {
|
|
64
|
+
/** How many of the most recent versions to inspect. Default 10; Infinity for all. */
|
|
65
|
+
versions?: number;
|
|
66
|
+
includePrereleases?: boolean;
|
|
67
|
+
/** Extra arguments passed to the server's bin. */
|
|
68
|
+
args?: string[];
|
|
69
|
+
env?: Record<string, string>;
|
|
70
|
+
/** Which bin to run when the package has several. */
|
|
71
|
+
bin?: string;
|
|
72
|
+
/** Command template instead of the bin: {bin} and {dir} are filled in. */
|
|
73
|
+
cmd?: string;
|
|
74
|
+
allowScripts?: boolean;
|
|
75
|
+
installTimeoutMs?: number;
|
|
76
|
+
timeoutMs?: number;
|
|
77
|
+
/** Where menus and history.json go. */
|
|
78
|
+
outDir: string;
|
|
79
|
+
keepInstalls?: boolean;
|
|
80
|
+
source?: PackageSource;
|
|
81
|
+
onProgress?: (message: string) => void;
|
|
82
|
+
}
|
|
83
|
+
export declare function history(pkg: string, options: HistoryOptions): Promise<HistoryResult>;
|
|
84
|
+
export declare function classifyFailure(error: unknown): FailureReason;
|
|
85
|
+
/** The lines that say what went wrong, not the stack trace. */
|
|
86
|
+
export declare function summarizeError(error: unknown): string;
|
|
87
|
+
export declare function historyCsv(result: HistoryResult): string;
|
|
88
|
+
export { compareVersions };
|