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.
Files changed (63) hide show
  1. package/README.md +84 -23
  2. package/dist/args.d.ts +31 -5
  3. package/dist/args.js +91 -14
  4. package/dist/auth.d.ts +4 -2
  5. package/dist/auth.js +59 -21
  6. package/dist/auto.d.ts +80 -6
  7. package/dist/auto.js +255 -19
  8. package/dist/breakdown.d.ts +2 -0
  9. package/dist/breakdown.js +64 -19
  10. package/dist/catalog.d.ts +87 -10
  11. package/dist/catalog.js +415 -58
  12. package/dist/cli.js +170 -185
  13. package/dist/close.d.ts +8 -0
  14. package/dist/close.js +18 -0
  15. package/dist/config.d.ts +7 -1
  16. package/dist/config.js +17 -0
  17. package/dist/connect.d.ts +14 -0
  18. package/dist/connect.js +150 -16
  19. package/dist/diff.d.ts +23 -1
  20. package/dist/diff.js +574 -120
  21. package/dist/difference.d.ts +2 -0
  22. package/dist/difference.js +13 -12
  23. package/dist/explain.d.ts +113 -0
  24. package/dist/explain.js +461 -0
  25. package/dist/failures.d.ts +15 -0
  26. package/dist/failures.js +59 -2
  27. package/dist/help.d.ts +11 -0
  28. package/dist/help.js +205 -0
  29. package/dist/history.d.ts +13 -0
  30. package/dist/history.js +86 -6
  31. package/dist/init.d.ts +93 -2
  32. package/dist/init.js +508 -21
  33. package/dist/menu.js +10 -2
  34. package/dist/options.d.ts +141 -0
  35. package/dist/options.js +50 -0
  36. package/dist/report.d.ts +2 -2
  37. package/dist/report.js +305 -101
  38. package/dist/rules/description.d.ts +7 -2
  39. package/dist/rules/description.js +86 -42
  40. package/dist/rules/determinism.d.ts +4 -1
  41. package/dist/rules/determinism.js +175 -11
  42. package/dist/rules/gated.d.ts +7 -0
  43. package/dist/rules/gated.js +77 -0
  44. package/dist/rules/ids.d.ts +1 -1
  45. package/dist/rules/ids.js +9 -4
  46. package/dist/rules/index.d.ts +6 -0
  47. package/dist/rules/index.js +18 -6
  48. package/dist/rules/naming.d.ts +1 -1
  49. package/dist/rules/naming.js +91 -21
  50. package/dist/rules/rule.d.ts +25 -0
  51. package/dist/rules/rule.js +25 -1
  52. package/dist/rules/spec.d.ts +6 -0
  53. package/dist/rules/spec.js +56 -9
  54. package/dist/rules/write.d.ts +1 -1
  55. package/dist/rules/write.js +64 -14
  56. package/dist/session.d.ts +34 -9
  57. package/dist/session.js +525 -94
  58. package/dist/snapshot.d.ts +8 -2
  59. package/dist/snapshot.js +33 -2
  60. package/dist/types.d.ts +21 -0
  61. package/dist/words.d.ts +5 -0
  62. package/dist/words.js +14 -0
  63. package/package.json +2 -2
package/dist/report.js CHANGED
@@ -1,5 +1,7 @@
1
- import { stepLabel } from './session.js';
2
- import { breakdown, breakdownLines } from './breakdown.js';
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
- const where = breakdownLines(breakdown(menu), menu.tools.length);
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
- return `${plural(c.error, 'error')}, ${plural(c.warn, 'warning')}, ${c.info} info`;
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 classes = { breaking: 0, minor: 0, notice: 0 };
99
- for (const f of d.findings)
100
- if (f.class)
101
- classes[f.class]++;
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::${headline}. ${tokenLine}. ${bumpLine}.`].join('\n');
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 ${headline}`,
135
- ` ${beforeTools} → ${afterTools} tools · ${tokenLine}`,
136
- ` ${classes.breaking} breaking · ${classes.minor} minor · ${classes.notice} notice · ${bumpLine}`,
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
- export function formatHistory(h, format, outDir) {
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, '&lt;')}</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 failSummary = failed.length ? ` (${Object.entries(reasons).map(([k, n]) => `${k} ${n}`).join(', ')})` : '';
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}::failed: ${r.reason}`]
163
- : (r.diff?.breakingChanges ?? []).map((m) => `::error title=toolmenu history ${r.version}::${m}`));
164
- return [...lines, `::notice title=toolmenu history::${h.package}: ${ok.length} of ${h.rows.length} versions inspected${failSummary}`].join('\n');
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 table = [
168
- ['version', 'published', 'protocol', 'tools', 'tokens', 'sdk', 'zod', 'findings', 'vs previous'],
169
- ...h.rows.map((r) => r.status === 'failed'
170
- ? [r.version, r.published?.slice(0, 10) ?? '', `failed: ${r.reason}`, '', '', sdkOf(r), (r.resolved?.zod ?? []).join('+') || '-', '', '']
171
- : [
172
- r.version,
173
- r.published?.slice(0, 10) ?? '',
174
- r.protocolVersion ?? '?',
175
- String(r.tools ?? ''),
176
- `~${(r.tokens ?? 0).toLocaleString('en-US')}`,
177
- sdkOf(r),
178
- (r.resolved?.zod ?? []).join('+') || '-',
179
- [r.counts?.error ? `${r.counts.error} err` : '', r.counts?.warn ? `${r.counts.warn} warn` : ''].filter(Boolean).join(' ') || 'clean',
180
- r.diff
181
- ? `${signed(r.diff.tokenDelta)} tokens · ${[r.diff.breaking && `${r.diff.breaking} breaking`, r.diff.minor && `${r.diff.minor} minor`, r.diff.notice && `${r.diff.notice} notice`].filter(Boolean).join(' · ') || 'no changes'}`
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
- ` last ${h.rows.length} of ${h.totalVersions} published versions · installed ${h.installedAt.slice(0, 10)}`,
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('Failed:');
204
- for (const r of failed)
205
- lines.push(` ${r.version}: ${r.reason}. ${(r.error ?? '').split('\n')[0].slice(0, 160)}`);
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(`${h.rows.length} inspected · ${ok.length} ok · ${failed.length} failed${failSummary} · wrote ${outDir}`);
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.step ? `step ${f.step} (${s.steps[f.step - 1]?.label}): ${f.message}` : f.message }))).join('\n');
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
- ...(autoLine(s) ? [autoLine(s), ''] : []),
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.step ? `Step ${f.step}: ${f.message}` : f.message }))),
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
- ...(autoLine(s) ? [` ${autoLine(s)}`] : []),
241
- ` fresh-${s.transport === 'stdio' ? 'process' : 'connection'} check: ${s.connectionCheck === undefined ? 'not checked' : s.connectionCheck === 'same' ? 'the same menu' : 'a DIFFERENT menu'}`,
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
- step.changed ? 'menu changed' : step.status === 'ok' ? 'no change' : '',
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
- /** One line on what --auto called and what it left out, and how to reach more. */
285
- function autoLine(s) {
286
- if (!s.auto)
287
- return undefined;
288
- const by = (r) => s.auto.skipped.filter((x) => x.reason === r);
289
- const needs = by('needs values');
290
- const params = [...new Set(needs.flatMap((x) => x.missing ?? []))];
291
- const parts = [
292
- by('not read-only').length && `${by('not read-only').length} not read-only`,
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}\` | ${mdCell([f.message, ...(f.detail ?? [])].join(' · '))} |`;
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 { Rule } from './rule.js';
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
- /** The cut in characters, and how to name it in a message. */
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 {};