toolmenu 0.12.0 → 0.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +84 -23
- package/dist/args.d.ts +31 -5
- package/dist/args.js +91 -14
- package/dist/auth.d.ts +4 -2
- package/dist/auth.js +59 -21
- package/dist/auto.d.ts +80 -6
- package/dist/auto.js +255 -19
- package/dist/breakdown.d.ts +2 -0
- package/dist/breakdown.js +64 -19
- package/dist/catalog.d.ts +87 -10
- package/dist/catalog.js +415 -58
- package/dist/cli.js +170 -185
- package/dist/close.d.ts +8 -0
- package/dist/close.js +18 -0
- package/dist/config.d.ts +7 -1
- package/dist/config.js +17 -0
- package/dist/connect.d.ts +14 -0
- package/dist/connect.js +150 -16
- package/dist/diff.d.ts +23 -1
- package/dist/diff.js +574 -120
- package/dist/difference.d.ts +2 -0
- package/dist/difference.js +13 -12
- package/dist/explain.d.ts +113 -0
- package/dist/explain.js +461 -0
- package/dist/failures.d.ts +15 -0
- package/dist/failures.js +59 -2
- package/dist/help.d.ts +11 -0
- package/dist/help.js +205 -0
- package/dist/history.d.ts +13 -0
- package/dist/history.js +86 -6
- package/dist/init.d.ts +93 -2
- package/dist/init.js +508 -21
- package/dist/menu.js +10 -2
- package/dist/options.d.ts +141 -0
- package/dist/options.js +50 -0
- package/dist/report.d.ts +2 -2
- package/dist/report.js +305 -101
- package/dist/rules/description.d.ts +7 -2
- package/dist/rules/description.js +86 -42
- package/dist/rules/determinism.d.ts +4 -1
- package/dist/rules/determinism.js +175 -11
- package/dist/rules/gated.d.ts +7 -0
- package/dist/rules/gated.js +77 -0
- package/dist/rules/ids.d.ts +1 -1
- package/dist/rules/ids.js +9 -4
- package/dist/rules/index.d.ts +6 -0
- package/dist/rules/index.js +18 -6
- package/dist/rules/naming.d.ts +1 -1
- package/dist/rules/naming.js +91 -21
- package/dist/rules/rule.d.ts +25 -0
- package/dist/rules/rule.js +25 -1
- package/dist/rules/spec.d.ts +6 -0
- package/dist/rules/spec.js +56 -9
- package/dist/rules/write.d.ts +1 -1
- package/dist/rules/write.js +64 -14
- package/dist/session.d.ts +34 -9
- package/dist/session.js +525 -94
- package/dist/snapshot.d.ts +8 -2
- package/dist/snapshot.js +33 -2
- package/dist/types.d.ts +21 -0
- package/dist/words.d.ts +5 -0
- package/dist/words.js +14 -0
- package/package.json +2 -2
package/dist/report.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
|
-
import { stepLabel } from './session.js';
|
|
2
|
-
import {
|
|
1
|
+
import { clip, stepLabel, stepsText } from './session.js';
|
|
2
|
+
import { SEVERITY_RANK } from './types.js';
|
|
3
|
+
import { breakdown, breakdownLines, breakdownMarkdown } from './breakdown.js';
|
|
4
|
+
import { autoSummary } from './auto.js';
|
|
3
5
|
const LABEL = { error: 'ERROR', warn: 'WARN ', info: 'INFO ' };
|
|
4
6
|
export function counts(findings) {
|
|
5
7
|
const c = { error: 0, warn: 0, info: 0 };
|
|
@@ -53,31 +55,32 @@ export function formatSnapshot(menu, findings, format, outPath) {
|
|
|
53
55
|
return lines.join('\n');
|
|
54
56
|
}
|
|
55
57
|
function mdBreakdown(menu) {
|
|
56
|
-
|
|
57
|
-
if (!where.length)
|
|
58
|
-
return [];
|
|
59
|
-
return ['', `<details><summary>${where[0]}</summary>`, '', '```', ...where.slice(1).map((l) => l.trimStart()), '```', '', '</details>'];
|
|
58
|
+
return breakdownMarkdown(breakdown(menu), menu.tools.length);
|
|
60
59
|
}
|
|
61
60
|
function findingLines(findings) {
|
|
62
61
|
const lines = [];
|
|
63
62
|
for (const f of findings) {
|
|
64
|
-
lines.push(`${LABEL[f.severity]} ${f.rule}`);
|
|
63
|
+
lines.push(`${LABEL[f.severity]} ${f.rule}${unsureMark(f)}`);
|
|
65
64
|
lines.push(` ${f.message}`);
|
|
66
65
|
for (const d of f.detail ?? [])
|
|
67
66
|
lines.push(` ${d}`);
|
|
67
|
+
if (f.fix)
|
|
68
|
+
lines.push(` → Next: ${f.fix}`);
|
|
68
69
|
}
|
|
69
70
|
lines.push(findings.length ? '' : 'No findings.');
|
|
70
71
|
return lines;
|
|
71
72
|
}
|
|
73
|
+
/** The last line of every report: ✗ with errors, ! with warnings, ✓ otherwise. */
|
|
72
74
|
function summaryLine(findings) {
|
|
73
75
|
const c = counts(findings);
|
|
74
|
-
|
|
76
|
+
const mark = c.error ? '✗' : c.warn ? '!' : '✓';
|
|
77
|
+
return `${mark} ${plural(c.error, 'error')}, ${plural(c.warn, 'warning')}, ${c.info} info`;
|
|
75
78
|
}
|
|
76
79
|
function githubLines(findings) {
|
|
77
80
|
return findings.map((f) => {
|
|
78
81
|
const level = f.severity === 'error' ? 'error' : f.severity === 'warn' ? 'warning' : 'notice';
|
|
79
|
-
const body = [f.message, ...(f.detail ?? [])].join('\n').replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
|
|
80
|
-
return `::${level} title=toolmenu ${f.rule}::${body}`;
|
|
82
|
+
const body = [f.message, ...(f.detail ?? []), ...(f.fix ? [`→ Next: ${f.fix}`] : [])].join('\n').replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
|
|
83
|
+
return `::${level} title=toolmenu ${f.rule}${unsureMark(f)}::${body}`;
|
|
81
84
|
});
|
|
82
85
|
}
|
|
83
86
|
function signed(n) {
|
|
@@ -91,49 +94,54 @@ function tokenSentence(d) {
|
|
|
91
94
|
return `this release saves ~${n} tokens in every conversation that loads the menu`;
|
|
92
95
|
return 'no change in menu size';
|
|
93
96
|
}
|
|
97
|
+
/** "3 breaking (25 tools) · 2 minor (2 tools) · 11 notice (10 tools)": changes, and the tools they touch. */
|
|
98
|
+
function classLine(d) {
|
|
99
|
+
const part = (c) => {
|
|
100
|
+
const { changes, tools } = d.classes[c];
|
|
101
|
+
return `${changes} ${c}${changes && tools ? ` (${plural(tools, 'tool')})` : ''}`;
|
|
102
|
+
};
|
|
103
|
+
return `${part('breaking')} · ${part('minor')} · ${part('notice')}`;
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* The version verdict: the bump these changes suggest, then whether the release's
|
|
107
|
+
* bump is enough (and what to release instead), or why it wasn't checked.
|
|
108
|
+
*/
|
|
109
|
+
function bumpVerdict(d, md = false) {
|
|
110
|
+
const b = (s) => (md ? `**${s}**` : s);
|
|
111
|
+
const suggested = `suggested bump: ${b(d.suggestedBump)}`;
|
|
112
|
+
if (!d.actualBump || !d.release)
|
|
113
|
+
return { line: `${suggested} · not checked (${d.bumpNotChecked ?? 'pass --release old..new'})`, short: false };
|
|
114
|
+
const pair = `${d.release.before} → ${d.release.after} is a ${d.actualBump} bump`;
|
|
115
|
+
const required = d.requiredBump ?? d.suggestedBump;
|
|
116
|
+
const below1 = required !== d.suggestedBump ? ` (under 1.0.0 ${required === 'none' ? 'anything goes' : `a ${required} is enough`})` : '';
|
|
117
|
+
const rank = { none: 0, patch: 1, minor: 2, major: 3 };
|
|
118
|
+
if (rank[d.actualBump] >= rank[required])
|
|
119
|
+
return { line: `${suggested} · ${pair}: enough${below1}`, short: false };
|
|
120
|
+
return { line: `${suggested} · ${pair}: ${b(`too small, release ${d.releaseAs ?? `a ${required}`}`)}${below1}`, short: true };
|
|
121
|
+
}
|
|
122
|
+
function releasePair(d) {
|
|
123
|
+
// Name the release versions when there are some; otherwise say whose version this is.
|
|
124
|
+
return d.release?.source === 'release' ? `${d.release.before} → ${d.release.after}` : `${d.before.version ?? '?'} → ${d.after.version ?? '?'} (server-reported)`;
|
|
125
|
+
}
|
|
94
126
|
export function formatDiff(d, beforeTools, afterTools, format) {
|
|
95
127
|
if (format === 'json') {
|
|
96
128
|
return JSON.stringify({ command: 'diff', ...d, counts: counts(d.findings) }, null, 2);
|
|
97
129
|
}
|
|
98
|
-
const
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
// Name the release versions when there are some; otherwise say whose version this is.
|
|
103
|
-
const pair = d.release?.source === 'release'
|
|
104
|
-
? `${d.release.before} → ${d.release.after}`
|
|
105
|
-
: `${d.before.version ?? '?'} → ${d.after.version ?? '?'} (server-reported)`;
|
|
106
|
-
const actual = d.actualBump ?? `not checked (${d.bumpNotChecked ?? 'pass --release'})`;
|
|
107
|
-
const headline = `${d.after.name ?? d.before.name ?? 'server'} ${pair}`;
|
|
108
|
-
const tokenLine = `~${d.tokens.before.toLocaleString('en-US')} → ~${d.tokens.after.toLocaleString('en-US')} tokens (${signed(d.tokens.delta)}, estimate): ${tokenSentence(d)}`;
|
|
109
|
-
const bumpLine = `suggested bump: ${d.suggestedBump} · actual: ${actual}`;
|
|
130
|
+
const name = d.after.name ?? d.before.name ?? 'server';
|
|
131
|
+
const pair = releasePair(d);
|
|
132
|
+
const verdict = bumpVerdict(d);
|
|
133
|
+
const tokenLine = `~${d.tokens.before.toLocaleString('en-US')} → ~${d.tokens.after.toLocaleString('en-US')} (${signed(d.tokens.delta)}, estimate): ${tokenSentence(d)}`;
|
|
110
134
|
if (format === 'github') {
|
|
111
|
-
return [...githubLines(d.findings), `::notice title=toolmenu diff::${
|
|
112
|
-
}
|
|
113
|
-
if (format === 'markdown') {
|
|
114
|
-
const lines = [
|
|
115
|
-
`### toolmenu diff: \`${d.after.name ?? d.before.name ?? 'server'}\` ${pair}`,
|
|
116
|
-
'',
|
|
117
|
-
`**${signed(d.tokens.delta)} tokens** (~${d.tokens.before.toLocaleString('en-US')} → ~${d.tokens.after.toLocaleString('en-US')}, estimate): ${tokenSentence(d)}.`,
|
|
118
|
-
'',
|
|
119
|
-
`**${classes.breaking} breaking** · ${classes.minor} minor · ${classes.notice} notice · suggested bump: **${d.suggestedBump}** (actual: ${actual}) · ${beforeTools} → ${afterTools} tools`,
|
|
120
|
-
'',
|
|
121
|
-
...mdFindings(d.findings),
|
|
122
|
-
];
|
|
123
|
-
if (d.tokens.tools.length) {
|
|
124
|
-
lines.push('', '<details><summary>Token change by tool (estimate)</summary>', '', '| Tool | Before | After | Change |', '|---|---:|---:|---:|');
|
|
125
|
-
for (const t of d.tokens.tools.slice(0, 30))
|
|
126
|
-
lines.push(`| \`${t.name}\` | ${t.before.toLocaleString('en-US')} | ${t.after.toLocaleString('en-US')} | ${signed(t.delta)} |`);
|
|
127
|
-
if (d.tokens.tools.length > 30)
|
|
128
|
-
lines.push(`| …and ${d.tokens.tools.length - 30} more | | | |`);
|
|
129
|
-
lines.push('', '</details>');
|
|
130
|
-
}
|
|
131
|
-
return lines.join('\n');
|
|
135
|
+
return [...githubLines(d.findings), `::notice title=toolmenu diff::${name} ${pair}. Changes: ${classLine(d)}. Tokens: ${tokenLine}. Version: ${verdict.line}.`].join('\n');
|
|
132
136
|
}
|
|
137
|
+
if (format === 'markdown')
|
|
138
|
+
return mdDiff(d, beforeTools, afterTools);
|
|
133
139
|
const lines = [
|
|
134
|
-
`toolmenu diff ${
|
|
135
|
-
` ${
|
|
136
|
-
` ${
|
|
140
|
+
`toolmenu diff ${name} ${pair}`,
|
|
141
|
+
` changes ${classLine(d)}`,
|
|
142
|
+
` version ${verdict.line}`,
|
|
143
|
+
` tokens ${tokenLine}`,
|
|
144
|
+
` tools ${beforeTools} → ${afterTools}`,
|
|
137
145
|
'',
|
|
138
146
|
...findingLines(d.findings),
|
|
139
147
|
];
|
|
@@ -148,66 +156,189 @@ export function formatDiff(d, beforeTools, afterTools, format) {
|
|
|
148
156
|
lines.push(summaryLine(d.findings));
|
|
149
157
|
return lines.join('\n');
|
|
150
158
|
}
|
|
151
|
-
|
|
159
|
+
/** The diff as a PR comment: the verdict first, then the changes by class, notices folded. */
|
|
160
|
+
function mdDiff(d, beforeTools, afterTools) {
|
|
161
|
+
const name = d.after.name ?? d.before.name ?? 'server';
|
|
162
|
+
const verdict = bumpVerdict(d, true);
|
|
163
|
+
const c = d.classes;
|
|
164
|
+
const headline = [
|
|
165
|
+
c.breaking.changes ? `**${plural(c.breaking.changes, 'breaking change')}** in ${plural(c.breaking.tools, 'tool')}` : 'No breaking changes',
|
|
166
|
+
`${c.minor.changes} minor`,
|
|
167
|
+
`${c.notice.changes} notice${c.notice.changes === 1 ? '' : 's'}`,
|
|
168
|
+
`**${signed(d.tokens.delta)} tokens** (~${d.tokens.before.toLocaleString('en-US')} → ~${d.tokens.after.toLocaleString('en-US')}, estimate)`,
|
|
169
|
+
`${beforeTools} → ${afterTools} tools`,
|
|
170
|
+
].join(' · ');
|
|
171
|
+
const lines = [`### toolmenu diff: \`${name}\` ${releasePair(d)}`, '', headline, '', `> **Version:** ${verdict.line}`, ''];
|
|
172
|
+
if (d.tokens.delta !== 0)
|
|
173
|
+
lines.splice(lines.length - 1, 0, '>', `> **Tokens:** ${tokenSentence(d)}.`);
|
|
174
|
+
const table = (findings) => ['| | Rule | Change |', '|---|---|---|', ...findings.map(mdDiffRow)];
|
|
175
|
+
// Sections follow the severity the user's rules set, not only the class: a
|
|
176
|
+
// notice raised to error fails CI, so it's shown, never folded; a breaking
|
|
177
|
+
// rule lowered to info is folded with the notices.
|
|
178
|
+
const loud = (f) => f.severity !== 'info';
|
|
179
|
+
const breaking = d.findings.filter((f) => f.class === 'breaking' && loud(f));
|
|
180
|
+
const checks = d.findings.filter((f) => f.class !== 'breaking' && f.class !== 'minor' && loud(f));
|
|
181
|
+
const minor = d.findings.filter((f) => f.class === 'minor');
|
|
182
|
+
const quiet = d.findings.filter((f) => f.class !== 'minor' && !loud(f));
|
|
183
|
+
if (breaking.length)
|
|
184
|
+
lines.push(`#### Breaking (${breaking.length})`, '', ...table(breaking), '');
|
|
185
|
+
if (checks.length)
|
|
186
|
+
lines.push(`#### To check (${checks.length})`, '', ...table(checks), '');
|
|
187
|
+
if (minor.length)
|
|
188
|
+
lines.push(`#### New (${minor.length}, minor)`, '', ...table(minor), '');
|
|
189
|
+
if (quiet.length)
|
|
190
|
+
lines.push(`<details><summary>Notices (${quiet.length})</summary>`, '', ...table(quiet), '', '</details>', '');
|
|
191
|
+
if (!d.findings.length)
|
|
192
|
+
lines.push('No findings.', '');
|
|
193
|
+
if (d.tokens.tools.length) {
|
|
194
|
+
lines.push('<details><summary>Token change by tool (estimate)</summary>', '', '| Tool | Before | After | Change |', '|---|---:|---:|---:|');
|
|
195
|
+
for (const t of d.tokens.tools.slice(0, 30))
|
|
196
|
+
lines.push(`| \`${t.name}\` | ${t.before.toLocaleString('en-US')} | ${t.after.toLocaleString('en-US')} | ${signed(t.delta)} |`);
|
|
197
|
+
if (d.tokens.tools.length > 30)
|
|
198
|
+
lines.push(`| …and ${d.tokens.tools.length - 30} more | | | |`);
|
|
199
|
+
lines.push('', '</details>', '');
|
|
200
|
+
}
|
|
201
|
+
lines.push(summaryLine(d.findings));
|
|
202
|
+
return lines.join('\n');
|
|
203
|
+
}
|
|
204
|
+
/** One diff finding as a table row: a long tool list folds, a text change shows as -/+ lines. */
|
|
205
|
+
function mdDiffRow(f) {
|
|
206
|
+
const detail = (f.detail ?? []).map((line) => {
|
|
207
|
+
const list = /^(tools|operations|moved): (.*)$/.exec(line);
|
|
208
|
+
if (list)
|
|
209
|
+
return `<details><summary>all ${list[2].split(', ').length} ${list[1] === 'moved' ? 'moved tools' : list[1]}</summary>${mdCell(list[2])}</details>`;
|
|
210
|
+
return `<br><sub>${mdCell(line).replace(/</g, '<')}</sub>`;
|
|
211
|
+
});
|
|
212
|
+
const sev = f.severity === 'error' ? '**error**' : f.severity;
|
|
213
|
+
return `| ${sev} | \`${f.rule}\`${f.confidence === 'unsure' ? ' · _unsure_' : ''} | ${mdCell(f.message)}${detail.join('')}${f.fix ? `<br>**→ Next:** ${mdCell(f.fix)}` : ''} |`;
|
|
214
|
+
}
|
|
215
|
+
export function formatHistory(h, format, outDir, csvPath) {
|
|
152
216
|
if (format === 'json')
|
|
153
|
-
return JSON.stringify({ command: 'history', ...h }, null, 2);
|
|
217
|
+
return JSON.stringify({ command: 'history', ...h, written: { dir: outDir, csv: csvPath ?? null } }, null, 2);
|
|
154
218
|
const ok = h.rows.filter((r) => r.status === 'ok');
|
|
155
219
|
const failed = h.rows.filter((r) => r.status === 'failed');
|
|
220
|
+
const breaking = h.rows.filter((r) => r.diff?.breakingChanges.length);
|
|
156
221
|
const reasons = {};
|
|
157
222
|
for (const r of failed)
|
|
158
223
|
reasons[r.reason ?? 'crashed'] = (reasons[r.reason ?? 'crashed'] ?? 0) + 1;
|
|
159
|
-
const
|
|
224
|
+
const reasonList = Object.entries(reasons).map(([k, n]) => `${n} ${k}`).join(', ');
|
|
225
|
+
const mark = ok.length === 0 && h.rows.length ? '✗' : failed.length || breaking.length ? '!' : '✓';
|
|
226
|
+
const summary = [
|
|
227
|
+
`${mark} ${ok.length} of ${plural(h.rows.length, 'version')} inspected`,
|
|
228
|
+
...(failed.length ? [`${failed.length} failed (${reasonList})`] : []),
|
|
229
|
+
// "No breaking changes" only when there was something to compare.
|
|
230
|
+
...(breaking.length ? [`${plural(breaking.length, 'release')} with breaking changes`] : ok.length > 1 ? ['no breaking changes'] : []),
|
|
231
|
+
].join(' · ');
|
|
232
|
+
const scope = `the last ${h.rows.length} of ${h.totalVersions} published versions, installed ${h.installedAt.slice(0, 10)}: dependencies resolve as of that day, not as shipped`;
|
|
233
|
+
const saved = `menus and history.json in ${outDir}${csvPath ? ` · CSV in ${csvPath}` : ''}`;
|
|
234
|
+
const failure = (r) => r.message ?? `${r.reason}: ${(r.error ?? '').split('\n')[0].slice(0, 160)}`;
|
|
160
235
|
if (format === 'github') {
|
|
161
236
|
const lines = h.rows.flatMap((r) => r.status === 'failed'
|
|
162
|
-
? [`::warning title=toolmenu history ${r.version}
|
|
163
|
-
: (r.diff?.breakingChanges ?? []).map((m) => `::error title=toolmenu history ${r.version}::${m}`));
|
|
164
|
-
return [...lines, `::notice title=toolmenu history::${h.package}: ${
|
|
237
|
+
? [`::warning title=toolmenu history ${r.version} (${r.reason}${r.confidence === 'unsure' ? ' · unsure' : ''})::${ghEscape([failure(r), ...(r.fix ? [`→ Next: ${r.fix}`] : [])].join('\n'))}`]
|
|
238
|
+
: (r.diff?.breakingChanges ?? []).map((m) => `::error title=toolmenu history ${r.version}::${ghEscape(`${m} (vs ${r.diff.from})`)}`));
|
|
239
|
+
return [...lines, `::notice title=toolmenu history::${ghEscape(`${h.package}: ${summary.slice(2)}. ${saved}.`)}`].join('\n');
|
|
165
240
|
}
|
|
166
241
|
const sdkOf = (r) => (r.resolved?.['@modelcontextprotocol/sdk'] ?? r.resolved?.['@modelcontextprotocol/server'] ?? []).join('+') || '-';
|
|
167
|
-
const
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
242
|
+
const zodOf = (r) => (r.resolved?.zod ?? []).join('+') || '-';
|
|
243
|
+
const findingsOf = (r) => [r.counts?.error ? `${r.counts.error} err` : '', r.counts?.warn ? `${r.counts.warn} warn` : ''].filter(Boolean).join(' ') || 'clean';
|
|
244
|
+
const versus = (r) => {
|
|
245
|
+
if (!r.diff)
|
|
246
|
+
return '—';
|
|
247
|
+
const d = r.diff;
|
|
248
|
+
const changes = [d.breaking && `${d.breaking} breaking`, d.minor && `${d.minor} minor`, d.notice && `${d.notice} notice`].filter(Boolean).join(' · ') || 'no changes';
|
|
249
|
+
return `${signed(d.tokenDelta)} tokens · ${changes}${d.bumpTooSmall ? ` · bump too small (${d.actualBump ?? '?'}, needs ${d.suggestedBump})` : ''}`;
|
|
250
|
+
};
|
|
251
|
+
const head = ['version', 'published', 'protocol', 'tools', 'tokens', 'sdk', 'zod', 'findings', 'vs previous'];
|
|
252
|
+
const cells = (r) => r.status === 'failed'
|
|
253
|
+
? [r.version, r.published?.slice(0, 10) ?? '', `failed: ${r.reason}`, '', '', sdkOf(r), zodOf(r), '', '']
|
|
254
|
+
: [r.version, r.published?.slice(0, 10) ?? '', r.protocolVersion ?? '?', String(r.tools ?? ''), `~${(r.tokens ?? 0).toLocaleString('en-US')}`, sdkOf(r), zodOf(r), findingsOf(r), versus(r)];
|
|
255
|
+
if (format === 'markdown') {
|
|
256
|
+
const lines = [
|
|
257
|
+
`### toolmenu history: \`${h.package}\``,
|
|
258
|
+
'',
|
|
259
|
+
`${scope.charAt(0).toUpperCase()}${scope.slice(1)}.`,
|
|
260
|
+
'',
|
|
261
|
+
`| ${head.join(' | ')} |`,
|
|
262
|
+
`|${head.map((_, i) => (i >= 3 && i <= 4 ? '---:' : '---')).join('|')}|`,
|
|
263
|
+
...h.rows.map((r) => `| ${cells(r).map((c, i) => (i === 2 && r.status === 'failed' ? `**${mdCell(c)}**` : mdCell(c))).join(' | ')} |`),
|
|
264
|
+
];
|
|
265
|
+
if (breaking.length) {
|
|
266
|
+
lines.push('', '**Breaking changes**', '');
|
|
267
|
+
for (const r of breaking) {
|
|
268
|
+
for (const m of r.diff.breakingChanges.slice(0, BREAKING_SHOWN))
|
|
269
|
+
lines.push(`- \`${r.version}\` (vs ${r.diff.from}): ${mdCell(m)}`);
|
|
270
|
+
if (r.diff.breakingChanges.length > BREAKING_SHOWN)
|
|
271
|
+
lines.push(`- \`${r.version}\`: …and ${r.diff.breakingChanges.length - BREAKING_SHOWN} more (all in history.json)`);
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
if (failed.length) {
|
|
275
|
+
lines.push('', `**Failed** (${failed.length} of ${h.rows.length})`, '');
|
|
276
|
+
for (const g of failureGroups(failed, failure))
|
|
277
|
+
lines.push(`- \`${g.versions}\` · ${g.row.reason}${g.row.confidence === 'unsure' ? ' · _unsure_' : ''}: ${mdCell(g.message)}${g.fix ? `<br>**→ Next:** ${mdCell(g.fix)}` : ''}`);
|
|
278
|
+
}
|
|
279
|
+
lines.push('', `**${summary}**`, '', `<sub>${saved.charAt(0).toUpperCase()}${saved.slice(1)}.</sub>`);
|
|
280
|
+
return lines.join('\n');
|
|
281
|
+
}
|
|
282
|
+
const table = [head, ...h.rows.map(cells)];
|
|
185
283
|
const widths = table[0].map((_, c) => Math.max(...table.map((row) => row[c].length)));
|
|
186
284
|
const lines = [
|
|
187
285
|
`toolmenu history ${h.package}`,
|
|
188
|
-
`
|
|
189
|
-
` (each version was installed today: dependencies resolve as of today, not as shipped)`,
|
|
286
|
+
` ${scope}`,
|
|
190
287
|
'',
|
|
191
288
|
...table.map((row) => ' ' + row.map((cell, c) => cell.padEnd(widths[c])).join(' ').trimEnd()),
|
|
192
289
|
'',
|
|
193
290
|
];
|
|
194
|
-
const breaking = h.rows.filter((r) => r.diff?.breakingChanges.length);
|
|
195
291
|
if (breaking.length) {
|
|
196
292
|
lines.push('Breaking changes:');
|
|
197
|
-
for (const r of breaking)
|
|
198
|
-
for (const m of r.diff.breakingChanges)
|
|
293
|
+
for (const r of breaking) {
|
|
294
|
+
for (const m of r.diff.breakingChanges.slice(0, BREAKING_SHOWN))
|
|
199
295
|
lines.push(` ${r.version} (vs ${r.diff.from}): ${m}`);
|
|
296
|
+
if (r.diff.breakingChanges.length > BREAKING_SHOWN)
|
|
297
|
+
lines.push(` ${r.version}: …and ${r.diff.breakingChanges.length - BREAKING_SHOWN} more (all in history.json)`);
|
|
298
|
+
}
|
|
200
299
|
lines.push('');
|
|
201
300
|
}
|
|
202
301
|
if (failed.length) {
|
|
203
|
-
lines.push(
|
|
204
|
-
for (const
|
|
205
|
-
lines.push(` ${
|
|
302
|
+
lines.push(`Failed (${failed.length} of ${h.rows.length}):`);
|
|
303
|
+
for (const g of failureGroups(failed, failure)) {
|
|
304
|
+
lines.push(` ${g.versions} ${g.row.reason}${g.row.confidence === 'unsure' ? ' · unsure' : ''}`);
|
|
305
|
+
lines.push(` ${g.message}`);
|
|
306
|
+
if (g.fix)
|
|
307
|
+
lines.push(` → Next: ${g.fix}`);
|
|
308
|
+
}
|
|
206
309
|
lines.push('');
|
|
207
310
|
}
|
|
208
|
-
lines.push(
|
|
311
|
+
lines.push(summary, ` ${saved}`);
|
|
209
312
|
return lines.join('\n');
|
|
210
313
|
}
|
|
314
|
+
/** Breaking changes listed per release in history's text and markdown; the rest are in history.json. */
|
|
315
|
+
const BREAKING_SHOWN = 5;
|
|
316
|
+
/**
|
|
317
|
+
* Failed versions with the same words and next step, as one entry naming them: "0.2.0, 0.3.0 … 0.4.0 (6 versions)".
|
|
318
|
+
* The words name the version (npm couldn't install pkg@0.2.0), so they're compared, and a
|
|
319
|
+
* group of several shown, with "@<version>" in its place.
|
|
320
|
+
*/
|
|
321
|
+
function failureGroups(failed, failure) {
|
|
322
|
+
const bare = (text, version) => text.split(`@${version}`).join('@<version>');
|
|
323
|
+
const groups = new Map();
|
|
324
|
+
for (const r of failed) {
|
|
325
|
+
const key = `${r.reason}\n${bare(failure(r), r.version)}\n${bare(r.fix ?? '', r.version)}`;
|
|
326
|
+
groups.set(key, [...(groups.get(key) ?? []), r]);
|
|
327
|
+
}
|
|
328
|
+
return [...groups.values()].map((rows) => {
|
|
329
|
+
const row = rows[0];
|
|
330
|
+
const shown = (text) => (rows.length === 1 ? text : bare(text, row.version));
|
|
331
|
+
return {
|
|
332
|
+
row,
|
|
333
|
+
message: shown(failure(row)),
|
|
334
|
+
fix: row.fix === undefined ? undefined : shown(row.fix),
|
|
335
|
+
versions: rows.length === 1 ? row.version : rows.length <= 3 ? rows.map((r) => r.version).join(', ') : `${rows[0].version}, ${rows[1].version} … ${rows[rows.length - 1].version} (${rows.length} versions)`,
|
|
336
|
+
};
|
|
337
|
+
});
|
|
338
|
+
}
|
|
339
|
+
function ghEscape(text) {
|
|
340
|
+
return text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
|
|
341
|
+
}
|
|
211
342
|
export function formatSession(s, format) {
|
|
212
343
|
if (format === 'json') {
|
|
213
344
|
// The union menu itself goes to --union-out; the report says how big it is.
|
|
@@ -215,7 +346,7 @@ export function formatSession(s, format) {
|
|
|
215
346
|
return JSON.stringify({ command: 'session', ...rest, union: { tools: union.tools.length, totalTokens: union.totalTokens }, counts: counts(s.findings) }, null, 2);
|
|
216
347
|
}
|
|
217
348
|
if (format === 'github') {
|
|
218
|
-
return githubLines(s.findings.map((f) => ({ ...f, message: f
|
|
349
|
+
return githubLines(s.findings.map((f) => ({ ...f, message: stepPrefix(f, `step ${f.step} (${s.steps[(f.step ?? 1) - 1]?.label}): `) }))).join('\n');
|
|
219
350
|
}
|
|
220
351
|
if (format === 'markdown') {
|
|
221
352
|
const lines = [
|
|
@@ -223,12 +354,15 @@ export function formatSession(s, format) {
|
|
|
223
354
|
'',
|
|
224
355
|
`\`${s.server.name ?? 'server'}\` ${s.server.version ?? ''} · protocol ${s.server.protocolVersion ?? '?'} · ${s.transport} · ${s.baseline.tools} → ${s.final.tools} tools · ~${s.baseline.tokens.toLocaleString('en-US')} → ~${s.final.tokens.toLocaleString('en-US')} tokens (estimate)`,
|
|
225
356
|
'',
|
|
226
|
-
...(
|
|
357
|
+
...(s.auto ? [...autoSummary(s.auto).map((l, i) => (i === 0 ? `**${l.replace(/^auto: /, 'auto:** ')}` : `- ${l.trim()}`)), ''] : []),
|
|
358
|
+
...(callCounts(s) ? [`**Calls:** ${callCounts(s)}`, ''] : []),
|
|
359
|
+
...(menuChange(s) ? [`**Menu:** ${menuChange(s)}`, ''] : []),
|
|
360
|
+
...causes(s.findings, (count, f, where, text) => count ? `**${count}:**` : `- ${f.severity === 'error' ? '**ERROR**' : LABEL[f.severity].trim()} \`${f.rule}\` · ${where} · ${mdCell(text)}`),
|
|
227
361
|
'| Step | Menu | list_changed | Scope |',
|
|
228
362
|
'|---|---|---|---|',
|
|
229
363
|
...s.steps.map((st) => `| ${st.index}. ${mdCell(st.label)} | ${st.status !== 'ok' ? st.status : st.changed ? `changed (${st.tools} tools)` : 'no change'} | ${st.changed ? (st.listChanged ? 'received' : '**missing**') : ''} | ${st.scope ?? ''} |`),
|
|
230
364
|
'',
|
|
231
|
-
...mdFindings(s.findings.map((f) => ({ ...f, message: f
|
|
365
|
+
...mdFindings(s.findings.map((f) => ({ ...f, message: stepPrefix(f, `Step ${f.step}: `) }))),
|
|
232
366
|
];
|
|
233
367
|
return lines.join('\n');
|
|
234
368
|
}
|
|
@@ -237,26 +371,37 @@ export function formatSession(s, format) {
|
|
|
237
371
|
`toolmenu session ${s.scenario}`,
|
|
238
372
|
` ${s.server.name ?? 'server'} ${s.server.version ?? ''} · protocol ${s.server.protocolVersion ?? '?'} · ${s.transport}`,
|
|
239
373
|
` baseline: ${plural(s.baseline.tools, 'tool')} · ${tok(s.baseline.tokens)} tokens (estimate) · listening for list_changed: ${s.listening ? 'yes' : 'no'}`,
|
|
240
|
-
...(
|
|
241
|
-
|
|
374
|
+
...(s.auto ? autoSummary(s.auto).map((l, i) => (i === 0 ? ` ${l}` : ` ${l}`)) : []),
|
|
375
|
+
...(callCounts(s) ? [` calls: ${callCounts(s)}`] : []),
|
|
376
|
+
// Before the first step only: what a fresh one sees after a change is each step's scope.
|
|
377
|
+
` fresh-${s.transport === 'stdio' ? 'process' : 'connection'} check of the starting menu: ${s.connectionCheck === undefined ? 'not checked' : s.connectionCheck === 'same' ? 'the same' : 'DIFFERENT'}`,
|
|
242
378
|
'',
|
|
379
|
+
...(menuChange(s) ? [`menu: ${menuChange(s)}`] : []),
|
|
380
|
+
...causes(s.findings, (count, f, where, text) => (count ? `${count}:` : ` ${LABEL[f.severity]} ${f.rule} · ${where} · ${text}`)),
|
|
243
381
|
];
|
|
244
382
|
const at = (step) => s.findings.filter((f) => f.step === step);
|
|
245
383
|
const block = (findings) => {
|
|
246
384
|
for (const f of findings) {
|
|
247
|
-
lines.push(` ${LABEL[f.severity]} ${f.rule}`);
|
|
385
|
+
lines.push(` ${LABEL[f.severity]} ${f.rule}${unsureMark(f)}`);
|
|
248
386
|
lines.push(` ${f.message}`);
|
|
249
387
|
for (const d of f.detail ?? [])
|
|
250
388
|
lines.push(` ${d}`);
|
|
389
|
+
if (f.fix)
|
|
390
|
+
lines.push(` → Next: ${f.fix}`);
|
|
251
391
|
}
|
|
252
392
|
};
|
|
253
393
|
block(at(0));
|
|
254
394
|
if (at(0).length)
|
|
255
395
|
lines.push('');
|
|
396
|
+
let before = s.baseline.tools;
|
|
256
397
|
for (const step of s.steps) {
|
|
398
|
+
const delta = step.tools - before;
|
|
399
|
+
before = step.tools;
|
|
257
400
|
const facts = [
|
|
258
401
|
step.status !== 'ok' ? step.status : '',
|
|
259
|
-
|
|
402
|
+
// A tool error or a failure is said in the step's note; an answer otherwise wouldn't be said at all.
|
|
403
|
+
step.outcome === 'answered' ? 'answered' : '',
|
|
404
|
+
step.changed ? `menu changed${delta ? ` · ${delta > 0 ? '+' : '−'}${plural(Math.abs(delta), 'tool')}` : ''}` : step.status === 'ok' ? 'no change' : '',
|
|
260
405
|
step.changed ? (step.listChanged ? 'list_changed received' : 'no list_changed') : '',
|
|
261
406
|
step.scope ? `scope: ${step.scope}` : '',
|
|
262
407
|
step.note ?? '',
|
|
@@ -275,26 +420,85 @@ export function formatSession(s, format) {
|
|
|
275
420
|
lines.push(summaryLine(s.findings));
|
|
276
421
|
return lines.join('\n');
|
|
277
422
|
}
|
|
423
|
+
/**
|
|
424
|
+
* A session's errors and warnings, one line each, before the step log: what to fix
|
|
425
|
+
* without reading every step. `line` renders the count heading (count set) or one
|
|
426
|
+
* finding, info included. Empty when there are no findings.
|
|
427
|
+
*/
|
|
428
|
+
function causes(findings, line) {
|
|
429
|
+
// Errors first, info last; the step order within each (the sort is stable).
|
|
430
|
+
const all = [...findings].sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]);
|
|
431
|
+
if (!all.length)
|
|
432
|
+
return [];
|
|
433
|
+
const c = counts(findings);
|
|
434
|
+
const count = [c.error ? plural(c.error, 'error') : '', c.warn ? plural(c.warn, 'warning') : '', c.info ? `${c.info} info` : ''].filter(Boolean).join(', ');
|
|
435
|
+
const out = [line(count)];
|
|
436
|
+
for (const f of all) {
|
|
437
|
+
const where = f.steps?.length ? stepsText(f.steps) : f.step === 0 ? 'before step 1' : f.step ? `step ${f.step}` : 'the whole run';
|
|
438
|
+
// Without the "Steps 2 and 7: " the line already says.
|
|
439
|
+
const text = lead(f.message.replace(/^Steps? [\d–, and]+: /, ''), 100);
|
|
440
|
+
out.push(line(undefined, f, `${f.confidence === 'unsure' ? 'unsure · ' : ''}${where}`, text));
|
|
441
|
+
}
|
|
442
|
+
return [...out, ''];
|
|
443
|
+
}
|
|
444
|
+
/**
|
|
445
|
+
* The start of a message, at most `max` characters: up to the last sentence end
|
|
446
|
+
* that fits, or cut with an ellipsis when none does. A sentence end inside quotes
|
|
447
|
+
* or brackets, or after "vs." or "e.g.", isn't one (a server's quoted words).
|
|
448
|
+
*/
|
|
449
|
+
function lead(text, max) {
|
|
450
|
+
if (text.length <= max)
|
|
451
|
+
return text;
|
|
452
|
+
let depth = 0;
|
|
453
|
+
let straight = false;
|
|
454
|
+
let end = -1;
|
|
455
|
+
for (let i = 0; i < max; i++) {
|
|
456
|
+
const ch = text[i];
|
|
457
|
+
if (ch === '"')
|
|
458
|
+
straight = !straight;
|
|
459
|
+
else if ('“(['.includes(ch))
|
|
460
|
+
depth++;
|
|
461
|
+
else if ('”)]'.includes(ch))
|
|
462
|
+
depth = Math.max(0, depth - 1);
|
|
463
|
+
else if (ch === '.' && depth === 0 && !straight && text[i + 1] === ' ' && /[A-Z+~]/.test(text[i + 2] ?? '') && !/\b(vs|e\.g|i\.e|etc)$/i.test(text.slice(0, i)))
|
|
464
|
+
end = i;
|
|
465
|
+
}
|
|
466
|
+
return end > 0 ? text.slice(0, end + 1) : clip(text, max);
|
|
467
|
+
}
|
|
468
|
+
/** "menu: 5 → 8 tools (+3) · ~290 → ~479 tokens (+189, estimate) · changed at steps 2, 4, 5 and 7", or nothing when it never changed. */
|
|
469
|
+
function menuChange(s) {
|
|
470
|
+
const changed = s.steps.filter((st) => st.changed).map((st) => st.index);
|
|
471
|
+
if (!changed.length)
|
|
472
|
+
return undefined;
|
|
473
|
+
const signed = (n) => (n >= 0 ? `+${n.toLocaleString('en-US')}` : `−${Math.abs(n).toLocaleString('en-US')}`);
|
|
474
|
+
const tools = s.final.tools - s.baseline.tools;
|
|
475
|
+
const tokens = s.final.tokens - s.baseline.tokens;
|
|
476
|
+
return `${s.baseline.tools} → ${s.final.tools} tools${tools ? ` (${signed(tools)})` : ''} · ~${s.baseline.tokens.toLocaleString('en-US')} → ~${s.final.tokens.toLocaleString('en-US')} tokens (${signed(tokens)}, estimate) · changed at ${stepsText(changed)}`;
|
|
477
|
+
}
|
|
478
|
+
/** "calls: 6 · 6 answered, 0 tool errors, 0 failed" (and how many weren't sent), or nothing without call steps. */
|
|
479
|
+
function callCounts(s) {
|
|
480
|
+
const calls = s.steps.filter((st) => st.outcome);
|
|
481
|
+
if (!calls.length)
|
|
482
|
+
return undefined;
|
|
483
|
+
const n = (o) => calls.filter((st) => st.outcome === o).length;
|
|
484
|
+
const notSent = n('not-sent');
|
|
485
|
+
return `${calls.length} · ${n('answered')} answered, ${plural(n('tool-error'), 'tool error')}, ${n('failed')} failed${notSent ? `, ${notSent} not sent` : ''}`;
|
|
486
|
+
}
|
|
278
487
|
export function formatPlan(scenario, name) {
|
|
279
488
|
const lines = [`toolmenu session --plan ${name}`, ` allow_writes: ${scenario.allowWrites}${scenario.allowWrites ? '' : ' (tools not marked readOnlyHint will be refused)'}`, ''];
|
|
280
489
|
scenario.steps.forEach((step, i) => lines.push(`step ${i + 1}: ${stepLabel(step)}${step.kind === 'wait_for' ? ` (up to ${step.timeoutMs} ms)` : ''}`));
|
|
281
490
|
lines.push('', 'After every step the menu is listed and compared with the one before. Nothing was run.');
|
|
282
491
|
return lines.join('\n');
|
|
283
492
|
}
|
|
284
|
-
/**
|
|
285
|
-
function
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
by('open world').length && `${by('open world').length} marked openWorldHint: true (--open-world to call them)`,
|
|
294
|
-
needs.length && `${needs.length} need values the schema doesn't give (${params.slice(0, 6).join(', ')}${params.length > 6 ? ', …' : ''}: write a scenario, or --save-scenario and fill them in)`,
|
|
295
|
-
by('over the call budget').length && `${by('over the call budget').length} over --max-calls`,
|
|
296
|
-
].filter(Boolean);
|
|
297
|
-
return `auto: called ${s.auto.called.length} tool${s.auto.called.length === 1 ? '' : 's'}${parts.length ? ` · skipped ${parts.join(', ')}` : ''}`;
|
|
493
|
+
/** " · unsure" after the rule, for findings that are a heuristic or an inference. */
|
|
494
|
+
function unsureMark(f) {
|
|
495
|
+
return f.confidence === 'unsure' ? ' · unsure' : '';
|
|
496
|
+
}
|
|
497
|
+
/** The step a session finding belongs to, unless its message already names its steps. */
|
|
498
|
+
function stepPrefix(f, prefix) {
|
|
499
|
+
if (!f.step || /^steps? \d/i.test(f.message))
|
|
500
|
+
return f.message;
|
|
501
|
+
return prefix + f.message;
|
|
298
502
|
}
|
|
299
503
|
function mdCell(text) {
|
|
300
504
|
return text.replace(/\|/g, '\\|').replace(/\n/g, ' ');
|
|
@@ -302,7 +506,7 @@ function mdCell(text) {
|
|
|
302
506
|
function mdFindings(findings) {
|
|
303
507
|
if (findings.length === 0)
|
|
304
508
|
return ['No findings.'];
|
|
305
|
-
const row = (f) => `| ${f.severity === 'error' ? '**error**' : f.severity} | \`${f.rule}
|
|
509
|
+
const row = (f) => `| ${f.severity === 'error' ? '**error**' : f.severity} | \`${f.rule}\`${f.confidence === 'unsure' ? ' · _unsure_' : ''} | ${mdCell([f.message, ...(f.detail ?? [])].join(' · '))}${f.fix ? `<br>**→ Next:** ${mdCell(f.fix)}` : ''} |`;
|
|
306
510
|
const head = ['| | Rule | Finding |', '|---|---|---|'];
|
|
307
511
|
const loud = findings.filter((f) => f.severity !== 'info');
|
|
308
512
|
const quiet = findings.filter((f) => f.severity === 'info');
|
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
import type { MenuTool } from '../types.js';
|
|
2
|
-
import type
|
|
2
|
+
import { type Rule } from './rule.js';
|
|
3
3
|
export declare const CLIENT_LIMITS: Record<string, number>;
|
|
4
4
|
export declare const DEFAULT_CLIENT = "claude-code";
|
|
5
|
-
/**
|
|
5
|
+
/**
|
|
6
|
+
* The cut in characters, the client to name in a message ("Claude Code", "your
|
|
7
|
+
* client"), and whether it's toolmenu's assumption rather than the user's setting.
|
|
8
|
+
*/
|
|
6
9
|
export declare function resolveLimit(setting: number | string | undefined): {
|
|
7
10
|
limit: number;
|
|
8
11
|
who: string;
|
|
12
|
+
assumed: boolean;
|
|
9
13
|
};
|
|
10
14
|
interface Instruction {
|
|
11
15
|
at: number;
|
|
@@ -25,4 +29,5 @@ export declare function pastTheCut(text: string, otherTools: string[], limit: nu
|
|
|
25
29
|
export declare function sentInFull(tool: MenuTool, patterns: string[] | undefined): boolean;
|
|
26
30
|
export declare const buried: Rule;
|
|
27
31
|
export declare const cut: Rule;
|
|
32
|
+
export declare const lateInstruction: Rule;
|
|
28
33
|
export {};
|