toolmenu 0.25.1 → 0.27.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 (62) hide show
  1. package/README.md +312 -35
  2. package/dist/args.d.ts +14 -2
  3. package/dist/args.js +44 -1
  4. package/dist/auth-check.d.ts +27 -0
  5. package/dist/auth-check.js +177 -0
  6. package/dist/auth.d.ts +7 -0
  7. package/dist/auth.js +29 -1
  8. package/dist/auto.d.ts +8 -0
  9. package/dist/auto.js +9 -2
  10. package/dist/breakdown.js +14 -10
  11. package/dist/cli.js +171 -56
  12. package/dist/clients.d.ts +13 -2
  13. package/dist/clients.js +65 -11
  14. package/dist/config.js +6 -0
  15. package/dist/diff.d.ts +35 -1
  16. package/dist/diff.js +57 -12
  17. package/dist/failures.js +4 -3
  18. package/dist/help.d.ts +1 -1
  19. package/dist/help.js +45 -17
  20. package/dist/history.js +5 -0
  21. package/dist/html.d.ts +29 -0
  22. package/dist/html.js +360 -0
  23. package/dist/index.d.ts +3 -2
  24. package/dist/index.js +3 -2
  25. package/dist/init.d.ts +14 -0
  26. package/dist/init.js +20 -6
  27. package/dist/junit.d.ts +17 -0
  28. package/dist/junit.js +87 -0
  29. package/dist/mcp-env.d.ts +6 -0
  30. package/dist/mcp-env.js +6 -0
  31. package/dist/mcp.d.ts +10 -0
  32. package/dist/mcp.js +86 -15
  33. package/dist/menu.d.ts +6 -0
  34. package/dist/menu.js +12 -1
  35. package/dist/options.d.ts +13 -0
  36. package/dist/options.js +4 -0
  37. package/dist/report.d.ts +14 -0
  38. package/dist/report.js +57 -51
  39. package/dist/review.d.ts +48 -0
  40. package/dist/review.js +212 -0
  41. package/dist/rule-docs.json +49 -4
  42. package/dist/rules/clients.d.ts +11 -0
  43. package/dist/rules/clients.js +65 -2
  44. package/dist/rules/determinism.d.ts +3 -0
  45. package/dist/rules/determinism.js +44 -7
  46. package/dist/rules/ids.js +5 -1
  47. package/dist/rules/index.js +5 -2
  48. package/dist/rules/output.d.ts +21 -0
  49. package/dist/rules/output.js +49 -0
  50. package/dist/rules/search.js +1 -1
  51. package/dist/rules/spec.d.ts +19 -0
  52. package/dist/rules/spec.js +86 -1
  53. package/dist/sanitize.d.ts +42 -0
  54. package/dist/sanitize.js +142 -0
  55. package/dist/sarif.d.ts +2 -0
  56. package/dist/sarif.js +2 -2
  57. package/dist/scan.d.ts +9 -2
  58. package/dist/scan.js +46 -24
  59. package/dist/session.d.ts +17 -0
  60. package/dist/session.js +119 -13
  61. package/dist/snapshot.js +2 -1
  62. package/package.json +5 -3
package/dist/html.js ADDED
@@ -0,0 +1,360 @@
1
+ /*
2
+ * The HTML report (--html <path>): one self-contained page per run of snapshot, diff
3
+ * or session, to keep as a CI artifact or send to someone.
4
+ *
5
+ * Static HTML and CSS: no script, no network. Fonts are asked for by name and fall
6
+ * back to the system's, so the file opens offline and looks the same from a CI
7
+ * artifact as from a laptop. The design follows the Board UI design system (its
8
+ * tokens, type scale and component recipes: stat cards, tables, chips, an alerts
9
+ * panel), with its accent re-tinted to the toolmenu logo's violet and the logo's mint
10
+ * check on clean rows. Light and dark follow the viewer's system setting.
11
+ */
12
+ import { agentMenu, isAppOnly } from './apps.js';
13
+ import { autoSummary } from './auto.js';
14
+ import { costLine, counts } from './report.js';
15
+ import { toolsOf } from './sarif.js';
16
+ import { stepsText } from './session.js';
17
+ import { basename } from 'node:path';
18
+ import { VERSION } from './version.js';
19
+ export function esc(text) {
20
+ return String(text).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
21
+ }
22
+ /** Backticked names in messages become code. */
23
+ const md = (text) => esc(text).replace(/`([^`]+)`/g, '<code>$1</code>');
24
+ const num = (n) => n.toLocaleString('en-US');
25
+ const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
26
+ const upper = (text) => text[0].toUpperCase() + text.slice(1);
27
+ const pct = (part, whole) => (whole > 0 ? Math.max(0, Math.min(100, (part / whole) * 100)) : 0).toFixed(2);
28
+ const SEVERITY = { error: ['rose', 'Error'], warn: ['yellow', 'Warning'], info: ['neutral', 'Info'] };
29
+ const ICON = {
30
+ tools: '<path d="M7.5 5.5h9M7.5 10h9M7.5 14.5h9"/><circle cx="4" cy="5.5" r=".9" fill="currentColor" stroke="none"/><circle cx="4" cy="10" r=".9" fill="currentColor" stroke="none"/><circle cx="4" cy="14.5" r=".9" fill="currentColor" stroke="none"/>',
31
+ tokens: '<path d="M10 3 17 6.5 10 10 3 6.5Z"/><path d="m3 10 7 3.5 7-3.5M3 13.5 10 17l7-3.5"/>',
32
+ error: '<circle cx="10" cy="10" r="7"/><path d="m7.5 7.5 5 5m0-5-5 5"/>',
33
+ warn: '<path d="M10 3.2 17.5 16H2.5Z"/><path d="M10 8.2v3.3"/><circle cx="10" cy="13.7" r=".6" fill="currentColor"/>',
34
+ tag: '<path d="M3.5 3.5h6l7 7-6 6-7-7Z"/><circle cx="7" cy="7" r="1.1" fill="currentColor" stroke="none"/>',
35
+ break: '<path d="M8 12 6.5 13.5a3 3 0 0 1-4.2-4.2L4 7.6M12 8l1.5-1.5a3 3 0 0 1 4.2 4.2L16 12.4M7 3v2M3 7h2M13 17v-2M17 13h-2"/>',
36
+ steps: '<circle cx="5" cy="5" r="1.8"/><circle cx="5" cy="15" r="1.8"/><path d="M5 6.8v6.4M9 5h8M9 15h8M9 10h5"/>',
37
+ };
38
+ const icon = (name) => `<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${ICON[name]}</svg>`;
39
+ const CHECK = '<svg class="check" viewBox="0 0 16 16" role="img" aria-label="No errors or warnings"><polyline points="3.5,8.5 6.6,11.5 12.5,5" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/></svg>';
40
+ const CHEVRON = '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m4 6 4 4 4-4"/></svg>';
41
+ const LOGO = '<svg viewBox="0 0 1024 1024" aria-hidden="true"><rect width="1024" height="1024" rx="232" fill="#6E56CF"/><rect x="150" y="480" width="140" height="64" rx="32" fill="#FFFFFF"/><rect x="250" y="296" width="190" height="432" rx="64" fill="#FFFFFF"/><rect x="400" y="340" width="420" height="68" rx="34" fill="#FFFFFF"/><rect x="400" y="478" width="320" height="68" rx="34" fill="#FFFFFF"/><rect x="400" y="616" width="190" height="68" rx="34" fill="#FFFFFF"/><polyline points="652,650 710,708 836,582" fill="none" stroke="#5EEAB5" stroke-width="68" stroke-linecap="round" stroke-linejoin="round"/></svg>';
42
+ const chip = (color, text, small = true) => `<span class="chip${small ? ' sm' : ''} ${color}">${esc(text)}</span>`;
43
+ function stat(name, label, value, badge) {
44
+ return `<section class="stat"><span class="icon">${icon(name)}</span><div><p class="t-body-m sec">${esc(label)}</p><div class="val"><span class="t-title-1 tnum">${esc(value)}</span>${badge ? chip(badge[0], badge[1], false) : ''}</div></div></section>`;
45
+ }
46
+ function heading(name, version, sub) {
47
+ return `<header class="head"><h1 class="t-title-1">${esc(name)}${version ? ` <span class="sec">${esc(version)}</span>` : ''}</h1><p class="sub t-body sec">${sub.map((s) => `<span>${s}</span>`).join('')}</p></header>`;
48
+ }
49
+ /** Each tool's status mark: an error dot, a warning dot, or the check. One pass over the findings. */
50
+ function statuses(findings) {
51
+ const worst = new Map();
52
+ for (const f of findings)
53
+ for (const t of toolsOf(f))
54
+ if (f.severity !== 'info' && worst.get(t) !== 'error')
55
+ worst.set(t, f.severity);
56
+ return (tool) => worst.get(tool) === 'error' ? '<span class="sdot rose" role="img" aria-label="Has an error"></span>'
57
+ : worst.get(tool) === 'warn' ? '<span class="sdot yellow" role="img" aria-label="Has a warning"></span>'
58
+ : CHECK;
59
+ }
60
+ /** The steps a finding is at: all of them for one found at several. */
61
+ const stepsOf = (f) => (f.steps?.length ? f.steps : f.step !== undefined ? [f.step] : []);
62
+ function tile(f, id) {
63
+ const tools = toolsOf(f);
64
+ const steps = stepsOf(f);
65
+ const where = [
66
+ steps.length ? upper(stepsText(steps)) : '',
67
+ tools.length === 1 ? tools[0] : tools.length > 1 ? `${tools.length} tools` : '',
68
+ ].filter(Boolean);
69
+ const [color, label] = SEVERITY[f.severity];
70
+ const tags = [...where.map((w) => chip('soft', w)), ...(f.confidence === 'unsure' ? ['<span class="chip sm soft" title="A heuristic, from names and words">Unsure</span>'] : [])];
71
+ return `<article class="tile"${id ? ` id="${id}"` : ''}>
72
+ <div class="tile-top"><span class="mono">${esc(f.rule)}</span>${chip(color, label)}</div>
73
+ ${tags.length ? `<div class="tags">${tags.join('')}</div>` : ''}
74
+ <p class="t-body2">${md(f.message)}</p>
75
+ ${f.detail?.length ? `<ul class="detail t-body2">${f.detail.map((d) => `<li>${md(d)}</li>`).join('')}</ul>` : ''}
76
+ ${f.fix ? `<p class="t-body2 next"><b>Next:</b> ${md(f.fix)}</p>` : ''}
77
+ </article>`;
78
+ }
79
+ function panel(title, findings, ids, openInfo = false) {
80
+ const loud = findings.filter((f) => f.severity !== 'info');
81
+ const info = findings.filter((f) => f.severity === 'info');
82
+ const c = counts(findings);
83
+ const summary = [c.error && plural(c.error, 'error', 'errors'), c.warn && plural(c.warn, 'warning', 'warnings'), c.info && `${c.info} info`].filter(Boolean).join(', ') || 'None';
84
+ return `<section class="panel" aria-label="${esc(title)}">
85
+ <div class="panel-head"><p class="t-body-m sec">${esc(title)}</p><p class="t-title-1">${summary}</p></div>
86
+ ${loud.map((f) => tile(f, ids?.get(f))).join('\n')}
87
+ ${info.length ? `<details class="more"${loud.length && !openInfo ? '' : ' open'}><summary><span class="row-gap"><span class="t-body-m">${loud.length ? 'Info findings' : 'All findings are info'}</span>${chip('neutral', String(info.length))}</span>${CHEVRON}</summary><div class="list">${info.map((f) => tile(f, ids?.get(f))).join('\n')}</div></details>` : ''}
88
+ ${findings.length ? '' : `<div class="empty">${CHECK}<span class="t-body-m">No findings</span></div>`}
89
+ </section>`;
90
+ }
91
+ function card(label, value, note, table, legend, extra = '') {
92
+ return `<section class="card">
93
+ <div class="card-head"><span class="t-body-m sec">${esc(label)}</span><span class="t-title-1">${esc(value)}</span>${note ? `<span class="t-body2 sec">${esc(note)}</span>` : ''}</div>
94
+ ${extra}
95
+ <div class="scroll">${table}</div>
96
+ ${legend ? `<div class="card-foot legend t-cap-m sec">${legend}</div>` : ''}
97
+ </section>`;
98
+ }
99
+ function page(title, body) {
100
+ return `<!doctype html>
101
+ <html lang="en">
102
+ <head>
103
+ <meta charset="utf-8">
104
+ <meta name="viewport" content="width=device-width, initial-scale=1">
105
+ <meta name="generator" content="toolmenu ${esc(VERSION)}">
106
+ <title>${esc(title)}</title>
107
+ <style>${CSS}</style>
108
+ </head>
109
+ <body>
110
+ <div class="page">
111
+ <div class="topbar"><span class="brand">${LOGO}<span class="t-headline">toolmenu</span></span></div>
112
+ <main>
113
+ ${body}
114
+ </main>
115
+ <footer class="foot t-cap-m sec"><span>toolmenu ${esc(VERSION)}</span><span>Token counts are estimates (o200k_base) of what the model reads.</span><span><a href="https://github.com/niksa90/toolmenu/blob/main/docs/RULES.md">Every rule</a>, or <code>toolmenu explain &lt;rule&gt;</code></span></footer>
116
+ </div>
117
+ </body>
118
+ </html>
119
+ `;
120
+ }
121
+ const isWrite = (t) => t.annotations?.readOnlyHint === false;
122
+ const protocolLine = (server) => (server.protocolVersion ? `Protocol ${esc(server.protocolVersion)}${server.era === 'legacy' ? ', 2025 handshake' : ''}` : '');
123
+ const appOnlyChip = '<span class="chip sm neutral" title="MCP Apps visibility without &quot;model&quot;: the agent isn\'t shown it">App only</span>';
124
+ const signed = (n) => (n > 0 ? `+${num(n)}` : n < 0 ? `−${num(-n)}` : '0');
125
+ /** The snapshot page. It counts as the text report does: every tool the server lists, app-only ones marked. */
126
+ export function snapshotHtml(menu, findings, options = {}) {
127
+ const c = counts(findings);
128
+ const { appOnly } = agentMenu(menu);
129
+ const max = Math.max(1, ...menu.tools.map((t) => t.tokens));
130
+ const writes = menu.tools.filter(isWrite).length;
131
+ const status = statuses(findings);
132
+ const rows = menu.tools
133
+ .map((t, i) => `<tr><td class="pos">${i}</td><td class="name">${esc(t.name)}${isAppOnly(t) ? appOnlyChip : isWrite(t) ? chip('purple', 'Writes') : ''}</td><td class="bar"><div class="meter"><span style="width:${pct(t.tokens, max)}%"></span></div></td><td class="num">~${num(t.tokens)}</td><td class="status">${status(t.name)}</td></tr>`)
134
+ .join('\n');
135
+ const table = `<table><thead><tr><th>#</th><th>Tool</th><th>Share of tokens</th><th class="num">Tokens</th><th class="status"><span class="sr">Status</span></th></tr></thead><tbody>${rows}</tbody></table>`;
136
+ const lists = [menu.prompts && plural(menu.prompts.length, 'prompt', 'prompts'), menu.resources && plural(menu.resources.length, 'resource', 'resources'), menu.resourceTemplates && plural(menu.resourceTemplates.length, 'resource template', 'resource templates')].filter(Boolean);
137
+ const notes = [
138
+ appOnly ? `${plural(appOnly.tools, 'tool isn\'t', 'tools aren\'t')} shown to the agent (MCP Apps visibility without "model", ~${num(appOnly.tokens)} tokens).` : '',
139
+ options.cost ? `${upper(costLine(options.cost))}.` : '',
140
+ lists.length ? `Also listed: ${lists.join(', ')}.` : '',
141
+ options.notOffered?.length ? `Not offered by the server: ${options.notOffered.join(', ')}.` : '',
142
+ options.outPath ? `Menu written to ${options.outPath}.` : '',
143
+ ].filter(Boolean);
144
+ const name = menu.server.name ?? 'MCP server';
145
+ const body = `${heading(name, menu.server.version, ['Snapshot', protocolLine(menu.server), esc(options.transport ?? '')].filter(Boolean))}
146
+ <div class="stats">
147
+ ${stat('tools', 'Tools', String(menu.tools.length), writes ? ['purple', plural(writes, 'write tool', 'write tools')] : undefined)}
148
+ ${options.cost?.upfront !== undefined ? stat('tokens', `Up front, as ${options.cost.label}`, `~${num(options.cost.upfront)}`, ['neutral', `of ~${num(menu.totalTokens)}`]) : stat('tokens', 'Tokens up front', `~${num(menu.totalTokens)}`, ['neutral', 'estimate'])}
149
+ ${stat('error', 'Errors', String(c.error), c.error ? undefined : ['lime', 'None'])}
150
+ ${stat('warn', 'Warnings', String(c.warn), c.warn ? undefined : ['lime', 'None'])}
151
+ </div>
152
+ <div class="main">
153
+ ${card('Tool menu, in server order', plural(menu.tools.length, 'tool', 'tools'), notes.join(' ') || undefined, table)}
154
+ ${panel('Findings', findings)}
155
+ </div>`;
156
+ return page(`toolmenu snapshot: ${name}`, body);
157
+ }
158
+ /**
159
+ * The diff page, from what diffMenus compared and decided (`tools`, from its onTools):
160
+ * the tools after the ignore globs, and which were added, removed and renamed. Token
161
+ * totals are the result's, which leave app-only tools out, as the text report's do.
162
+ */
163
+ export function diffHtml(result, tools, options = {}) {
164
+ const old = new Map(tools.before.map((t) => [t.name, t]));
165
+ const added = new Set(tools.added);
166
+ const renamedTo = new Map(tools.renamed.map((r) => [r.to, r.from]));
167
+ const gone = new Set(tools.removed);
168
+ const removed = tools.before.filter((t) => gone.has(t.name));
169
+ const described = new Set(result.findings.filter((f) => f.rule === 'diff/description').flatMap(toolsOf));
170
+ const max = Math.max(1, ...tools.after.map((t) => t.tokens), ...removed.map((t) => t.tokens));
171
+ const rows = tools.after.map((t, i) => {
172
+ const from = renamedTo.get(t.name);
173
+ const was = added.has(t.name) ? undefined : old.get(from ?? t.name)?.tokens;
174
+ const kept = was === undefined ? 0 : Math.min(was, t.tokens);
175
+ const delta = was === undefined ? undefined : t.tokens - was;
176
+ const change = was === undefined ? chip('lime', 'New') : delta > 0 ? chip('yellow', `+${num(delta)}`) : delta < 0 ? chip('soft', `−${num(-delta)}`) : '<span class="ter">0</span>';
177
+ const tag = from ? `<span class="chip sm rose" title="Was ${esc(from)}">Renamed</span>` : isAppOnly(t) ? appOnlyChip : described.has(t.name) ? chip('purple', 'Description') : '';
178
+ return `<tr><td class="pos">${tools.positions[i] ?? i}</td><td class="name">${esc(t.name)}${tag}${from ? `<div class="t-body2 sec">was ${esc(from)}</div>` : ''}</td><td class="bar"><div class="meter"><span class="grow" style="width:${pct(t.tokens, max)}%"></span><span style="width:${pct(kept, max)}%"></span></div></td><td class="num sec">${was === undefined ? '–' : `~${num(was)}`}</td><td class="num">~${num(t.tokens)}</td><td class="num">${change}</td></tr>`;
179
+ });
180
+ for (const t of removed) {
181
+ rows.push(`<tr class="gone"><td class="pos">–</td><td class="name">${esc(t.name)}</td><td class="bar"><div class="meter"><span class="ghost" style="width:${pct(t.tokens, max)}%"></span></div></td><td class="num sec">~${num(t.tokens)}</td><td class="num sec">–</td><td class="num">${chip('rose', 'Removed')}</td></tr>`);
182
+ }
183
+ const table = `<table><thead><tr><th>#</th><th>Tool</th><th>Now</th><th class="num">Before</th><th class="num">After</th><th class="num">Change</th></tr></thead><tbody>${rows.join('\n')}</tbody></table>`;
184
+ const t = result.tokens;
185
+ const share = t.before > 0 ? (Math.abs(t.delta) / t.before) * 100 : 0;
186
+ const growth = t.before === 0 ? signed(t.delta) : `${t.delta > 0 ? '+' : '−'}${share < 1 ? '<1' : Math.round(share)}%`;
187
+ const grew = tools.after.filter((x) => !added.has(x.name) && x.tokens > (old.get(renamedTo.get(x.name) ?? x.name)?.tokens ?? Infinity)).length;
188
+ const k = result.classes;
189
+ const bump = result.suggestedBump;
190
+ const [v0, v1] = [result.before.version, result.after.version];
191
+ const versions = v0 && v1 ? (v0 === v1 ? `Both report ${esc(v1)}` : `${esc(v0)} → ${esc(v1)}`) : '';
192
+ const file = (path) => `<code title="${esc(path)}">${esc(basename(path))}</code>`;
193
+ const files = options.paths ? `${file(options.paths[0])} → ${file(options.paths[1])}` : '';
194
+ // Removing or renaming a tool breaks callers: rose whenever either happened, whatever was added.
195
+ const moves = [added.size && `${added.size} new`, removed.length && `${removed.length} gone`, tools.renamed.length && `${tools.renamed.length} renamed`].filter(Boolean);
196
+ const toolsChip = moves.length ? [removed.length || tools.renamed.length ? 'rose' : 'lime', moves.join(', ')] : tools.ignored ? ['soft', `${tools.ignored} ignored`] : undefined;
197
+ const name = result.after.name ?? result.before.name ?? 'MCP server';
198
+ const body = `${heading(name, undefined, ['Diff', files, versions].filter(Boolean))}
199
+ <div class="stats">
200
+ ${stat('break', 'Breaking changes', String(k.breaking.changes), k.breaking.changes ? ['rose', plural(k.breaking.tools, 'tool', 'tools')] : ['lime', 'None'])}
201
+ ${stat('tag', 'Suggested bump', bump === 'none' ? 'None' : upper(bump), k.minor.changes ? ['soft', plural(k.minor.changes, 'minor change', 'minor changes')] : undefined)}
202
+ ${stat('tools', 'Tools', String(tools.after.length), toolsChip)}
203
+ ${stat('tokens', 'Tokens up front', `~${num(t.after)}`, t.delta ? [t.delta > 0 ? 'yellow' : 'lime', growth] : ['soft', 'unchanged'])}
204
+ </div>
205
+ <div class="main">
206
+ ${card('Token change, per tool', `${signed(t.delta)} tokens`, `${plural(grew, 'tool', 'tools')} grew, ${added.size} new, ${removed.length} removed${tools.renamed.length ? `, ${tools.renamed.length} renamed` : ''} · ~${num(t.before)} → ~${num(t.after)}`, table, '<span><i class="k-bar"></i>Before</span><span><i class="k-mint"></i>Added since</span>')}
207
+ ${panel('Changes', result.findings)}
208
+ </div>`;
209
+ return page(`toolmenu diff: ${name}`, body);
210
+ }
211
+ /** The session page. `menus`: the menu after each step, from session's onStepMenu. */
212
+ export function sessionHtml(result, menus = new Map()) {
213
+ const c = counts(result.findings);
214
+ const ids = new Map(result.findings.map((f, i) => [f, `finding-${i + 1}`]));
215
+ const stepsOf = (f) => (f.steps?.length ? f.steps : f.step !== undefined ? [f.step] : []);
216
+ const byStep = new Map();
217
+ for (const f of result.findings)
218
+ for (const n of stepsOf(f))
219
+ byStep.set(n, [...(byStep.get(n) ?? []), f]);
220
+ const before = byStep.get(0) ?? [];
221
+ const shown = new Set([...result.steps.map((s) => s.index), ...(before.length ? [0] : [])]);
222
+ // One scale for every strip: the tools after a step and those it removed, against the largest.
223
+ const total = (menu) => menu.reduce((n, t) => n + t.tokens, 0);
224
+ const max = Math.max(1, ...[...menus.values()].map(total));
225
+ const changed = result.steps.filter((s) => s.changed).map((s) => s.index);
226
+ const span = changed.length ? upper(stepsText(changed)) : 'No';
227
+ const strip = (menu) => menu ? `<div class="strip" aria-hidden="true">${menu.map((t) => `<span class="${t.change ?? ''}" style="flex-grow:${Math.max(t.tokens, 1)}" title="${esc(t.name)}, ~${num(t.tokens)}${t.change === 'removed' ? ', removed' : ''}"></span>`).join('')}</div>` : '<span class="ter">–</span>';
228
+ const fill = (menu) => (menu ? `<div class="fill" style="width:${pct(total(menu), max)}%">${strip(menu)}</div>` : strip(menu));
229
+ // The step's status first: a call answered before the menu couldn't be listed still failed.
230
+ const outcome = (s) => s.status === 'timed-out' ? chip('yellow', 'Timed out')
231
+ : s.status === 'failed' && s.outcome === 'answered' ? '<span class="chip sm rose" title="The call was answered; listing the menu after it failed">Failed after</span>'
232
+ : s.outcome === 'answered' ? chip('soft', 'Answered')
233
+ : s.outcome === 'tool-error' ? chip('yellow', 'Tool error')
234
+ : s.outcome === 'failed' ? chip('rose', 'Failed')
235
+ : s.outcome === 'not-sent' ? chip('rose', 'Not sent')
236
+ : s.outcome === 'needs-input' ? chip('purple', 'Asked for input')
237
+ : '<span class="ter">–</span>';
238
+ const links = (index) => (byStep.get(index) ?? []).map((f) => `<a class="chip sm ${SEVERITY[f.severity][0]}" href="#${ids.get(f)}">${esc(f.rule)}</a>`).join('');
239
+ const rows = result.steps.map((s) => {
240
+ const tags = links(s.index);
241
+ return `<tr class="${s.changed ? 'changed' : ''}"><td class="pos">${s.index}</td><td class="step"><code>${esc(s.label)}</code>${s.note ? `<div class="t-body2 sec">${esc(s.note)}</div>` : ''}${tags ? `<div class="tags">${tags}</div>` : ''}</td><td>${outcome(s)}</td><td>${fill(menus.get(s.index))}</td><td class="num">${s.tools}</td><td class="num">~${num(s.tokens)}</td></tr>`;
242
+ });
243
+ if (before.length)
244
+ rows.unshift(`<tr><td class="pos">0</td><td class="step"><span class="sec">Before the first step</span><div class="tags">${links(0)}</div></td><td><span class="ter">–</span></td><td><span class="ter">–</span></td><td class="num">${result.baseline.tools}</td><td class="num">~${num(result.baseline.tokens)}</td></tr>`);
245
+ const table = `<table><thead><tr><th>#</th><th>Step</th><th>Call</th><th>Menu after it</th><th class="num">Tools</th><th class="num">Tokens</th></tr></thead><tbody>${rows.join('\n')}</tbody></table>`;
246
+ const grew = result.final.tokens - result.baseline.tokens;
247
+ const fresh = result.connectionCheck === 'same' ? 'A fresh process starts with the same menu.' : result.connectionCheck === 'different' ? 'A fresh process starts with a different menu.' : undefined;
248
+ // Info findings start folded, unless a step row links into them.
249
+ const linkedInfo = result.findings.some((f) => f.severity === 'info' && stepsOf(f).some((n) => shown.has(n)));
250
+ // --auto: what it called and what it left out, as the text report says it.
251
+ const auto = result.auto ? autoSummary(result.auto) : [];
252
+ const autoBlock = auto.length ? `<details class="auto"><summary class="t-body-m">${esc(upper(auto[0].replace(/^auto: /, '')))}</summary>${auto.length > 1 ? `<ul class="t-body2 sec">${auto.slice(1).map((l) => `<li>${esc(l.trim())}</li>`).join('')}</ul>` : ''}</details>` : '';
253
+ const name = result.server.name ?? 'MCP server';
254
+ const body = `${heading(name, result.server.version, ['Session', `<code>${esc(result.scenario)}</code>`, protocolLine(result.server), esc(result.transport)].filter(Boolean))}
255
+ <div class="stats">
256
+ ${stat('error', 'Errors', String(c.error), c.error ? undefined : ['lime', 'None'])}
257
+ ${stat('warn', 'Warnings', String(c.warn), c.warn ? undefined : ['lime', 'None'])}
258
+ ${stat('steps', 'Menu changed', span, ['soft', plural(result.steps.length, 'step', 'steps')])}
259
+ ${stat('tokens', 'Tokens up front', `~${num(result.final.tokens)}`, grew ? [grew > 0 ? 'yellow' : 'lime', `${signed(grew)} in the session`] : ['soft', 'unchanged'])}
260
+ </div>
261
+ <div class="main">
262
+ ${card('The scenario, step by step', `${result.baseline.tools} → ${plural(result.final.tools, 'tool', 'tools')}`, fresh, table, '<span><i class="k-bar"></i>A tool, sized by tokens</span><span><i class="k-ins"></i>Inserted mid-list</span><span><i class="k-app"></i>Appended</span><span><i class="k-edit"></i>Edited or moved</span><span><i class="k-rem"></i>Removed</span>', autoBlock)}
263
+ ${panel('Findings', result.findings, ids, linkedInfo)}
264
+ </div>`;
265
+ return page(`toolmenu session: ${name}`, body);
266
+ }
267
+ const CSS = `
268
+ :root{--accent-500:#6E56CF;--mint:#5EEAB5;--text-primary:#0A0A0A;--text-secondary:#737373;--text-tertiary:#A3A3A3;--bg-full:#FFFFFF;--bg-primary:#FFFFFF;--bg-secondary:#F7F7F7;--bg-tertiary:#EBEBEB;--bg-inner:#FFFFFF;--border:#EBEBEB;--separator:#EBEBEB;--track:#EBEBEB;--bar:#6E56CF;--bar-soft:#EBE7FB;--lime-bg:#D9F99D;--lime-text:#3F6212;--rose-bg:#FECDD3;--rose-text:#9F1239;--yellow-bg:#FEF08A;--yellow-text:#854D0E;--purple-bg:#F3E8FF;--purple-text:#9333EA;--dot-rose:#F43F5E;--dot-rose-halo:#FFE4E6;--dot-yellow:#EAB308;--dot-yellow-halo:#FEF9C3;--shadow-card:0 1px 1px 0 rgb(0 0 0 / .05);--font-sans:Inter,ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;--font-mono:"JetBrains Mono",ui-monospace,SFMono-Regular,Menlo,Consolas,"Liberation Mono",monospace;color-scheme:light}
269
+ @media (prefers-color-scheme:dark){:root{--text-primary:#FAFAFA;--text-secondary:#A3A3A3;--text-tertiary:#8F8F8F;--bg-full:#121212;--bg-primary:#262626;--bg-secondary:#171717;--bg-tertiary:#3A3A3A;--bg-inner:#262626;--border:#404040;--separator:#3A3A3A;--track:#333333;--bar:#9580E2;--bar-soft:#4B3F82;--lime-bg:rgb(26 46 5 / .6);--lime-text:#84CC16;--rose-bg:rgb(76 5 25 / .6);--rose-text:#F43F5E;--yellow-bg:rgb(66 32 6 / .6);--yellow-text:#EAB308;--purple-bg:rgb(88 28 135 / .5);--purple-text:#D8B4FE;--dot-rose-halo:rgb(76 5 25 / .8);--dot-yellow-halo:rgb(66 32 6 / .8);--shadow-card:0 0 0 1px rgb(255 255 255 / .04);color-scheme:dark}}
270
+ *{box-sizing:border-box}
271
+ body{margin:0;background:var(--bg-full);color:var(--text-primary);font-family:var(--font-sans);font-size:14px;line-height:20px;-webkit-font-smoothing:antialiased}
272
+ p{margin:0}
273
+ .t-title-1{font-size:24px;line-height:34px;font-weight:500;margin:0}
274
+ .t-headline{font-size:16px;line-height:22px;font-weight:500}
275
+ .t-body-m{font-size:14px;line-height:20px;font-weight:500}
276
+ .t-body{font-size:14px;line-height:20px;font-weight:400}
277
+ .t-body2{font-size:13px;line-height:18px;font-weight:400}
278
+ .t-cap-m{font-size:12px;line-height:16px;font-weight:500;letter-spacing:.15px}
279
+ .sec{color:var(--text-secondary)}.ter{color:var(--text-tertiary)}.tnum{font-variant-numeric:tabular-nums}
280
+ .sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0)}
281
+ code,.mono{font-family:var(--font-mono);font-size:12.5px}
282
+ a{color:inherit}
283
+ :focus-visible{outline:2px solid var(--accent-500);outline-offset:2px;border-radius:6px}
284
+ svg{flex:none}
285
+ .page{max-width:1200px;margin:0 auto;padding:20px 16px 40px;display:grid;gap:24px}
286
+ main{display:grid;gap:24px}
287
+ .brand{display:flex;align-items:center;gap:8px}.brand svg{width:28px;height:28px}
288
+ .head .sub{display:flex;flex-wrap:wrap;gap:4px 16px;margin-top:2px}
289
+ .stats{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:16px}
290
+ .stat{display:flex;flex-direction:column;justify-content:space-between;gap:18px;min-height:132px;padding:16px;border-radius:16px;background:var(--bg-secondary);min-width:0}
291
+ .stat .icon{display:flex;padding:6px;border-radius:6px;background:var(--bg-primary);align-self:flex-start}
292
+ .stat .icon svg{width:20px;height:20px}
293
+ .stat .val{display:flex;flex-wrap:wrap;align-items:center;gap:8px}
294
+ .chip{display:inline-flex;align-items:center;padding:2px 6px;border-radius:6px;white-space:nowrap;font-size:14px;line-height:20px;font-weight:500;text-decoration:none}
295
+ .chip.sm{font-size:12px;line-height:16px;letter-spacing:.15px}
296
+ .chip.lime{background:var(--lime-bg);color:var(--lime-text)}.chip.rose{background:var(--rose-bg);color:var(--rose-text)}.chip.yellow{background:var(--yellow-bg);color:var(--yellow-text)}.chip.purple{background:var(--purple-bg);color:var(--purple-text)}.chip.neutral{background:var(--bg-tertiary);color:var(--text-secondary)}.chip.soft{background:var(--bg-secondary);color:var(--text-secondary)}
297
+ .sdot{display:inline-flex;width:12px;height:12px;border-radius:50%;align-items:center;justify-content:center}
298
+ .sdot::after{content:"";width:6px;height:6px;border-radius:50%}
299
+ .sdot.rose{background:var(--dot-rose-halo)}.sdot.rose::after{background:var(--dot-rose)}
300
+ .sdot.yellow{background:var(--dot-yellow-halo)}.sdot.yellow::after{background:var(--dot-yellow)}
301
+ .check{width:16px;height:16px;color:var(--mint)}
302
+ .main{display:grid;grid-template-columns:minmax(0,1.35fr) minmax(0,1fr);gap:16px;align-items:start}
303
+ .main>*{min-width:0}
304
+ .card{border:1px solid var(--border);border-radius:24px;background:var(--bg-primary);overflow:hidden}
305
+ .card-head{display:flex;flex-direction:column;gap:2px;padding:18px 20px 14px}
306
+ .card-foot{display:flex;flex-wrap:wrap;gap:6px 16px;padding:12px 20px 16px;border-top:1px solid var(--separator)}
307
+ .legend i{display:inline-block;width:10px;height:10px;border-radius:3px;margin-right:6px;vertical-align:-1px}
308
+ .k-bar{background:var(--bar)}.k-mint{background:var(--mint)}.k-ins{background:var(--dot-rose)}.k-app{background:var(--dot-yellow)}.k-edit{box-shadow:inset 0 0 0 1.5px var(--dot-rose)}.k-rem{background:repeating-linear-gradient(135deg,var(--dot-rose) 0 2px,transparent 2px 4px)}
309
+ .scroll{overflow-x:auto}
310
+ table{width:100%;border-collapse:collapse;text-align:left}
311
+ th{padding:10px 12px;font-size:14px;line-height:20px;font-weight:500;color:var(--text-tertiary);white-space:nowrap;background:var(--bg-secondary);border-top:1px solid var(--separator);border-bottom:1px solid var(--separator)}
312
+ td{padding:10px 12px;font-weight:500;vertical-align:middle}
313
+ tbody tr:not(:last-child){border-bottom:1px solid var(--separator)}
314
+ th:first-child,td:first-child{padding-left:20px}th:last-child,td:last-child{padding-right:20px}
315
+ .num{text-align:right;font-variant-numeric:tabular-nums;white-space:nowrap}
316
+ td.pos{color:var(--text-tertiary);font-variant-numeric:tabular-nums;width:1%}
317
+ td.name{white-space:nowrap}td.name .chip{margin-left:6px}
318
+ .status{width:1%;text-align:center}
319
+ tr.gone td.name{color:var(--text-secondary);text-decoration:line-through}
320
+ .meter{position:relative;height:6px;border-radius:999px;background:var(--track);min-width:90px;overflow:hidden}
321
+ .meter span{position:absolute;left:0;top:0;bottom:0;border-radius:999px;background:var(--bar)}
322
+ .meter span.grow{background:var(--mint)}.meter span.ghost{background:var(--text-tertiary)}
323
+ td.bar{width:34%}
324
+ .fill{min-width:4px}
325
+ .strip{display:flex;overflow:hidden;border-radius:3px;min-width:0}
326
+ .strip span{flex-basis:0;min-width:0;height:8px;background:var(--bar-soft);box-shadow:inset -1px 0 0 var(--bg-primary)}
327
+ td:has(.fill){min-width:150px}
328
+ tr.changed .strip span{background:var(--bar)}
329
+ .strip .inserted,tr.changed .strip .inserted{background:var(--dot-rose)}
330
+ .strip .appended,tr.changed .strip .appended{background:var(--dot-yellow)}
331
+ .strip .edited,.strip .moved,tr.changed .strip .edited,tr.changed .strip .moved{background:transparent;box-shadow:inset 0 0 0 1.5px var(--dot-rose)}
332
+ .strip .removed,tr.changed .strip .removed{background:repeating-linear-gradient(135deg,var(--dot-rose) 0 2px,transparent 2px 4px);opacity:.7}
333
+ td.step{max-width:280px}td.step code{overflow-wrap:anywhere}
334
+ .tags{display:flex;gap:6px;flex-wrap:wrap}td .tags{margin-top:6px}
335
+ .panel{background:var(--bg-secondary);border-radius:24px;padding:8px;display:grid;gap:8px}
336
+ .panel-head{padding:10px 10px 4px}
337
+ .tile{display:grid;gap:6px;padding:12px;border-radius:10px;background:var(--bg-inner);box-shadow:var(--shadow-card);scroll-margin-top:16px}
338
+ .tile:target{box-shadow:0 0 0 2px var(--accent-500)}
339
+ .tile-top{display:flex;justify-content:space-between;gap:10px;align-items:flex-start}
340
+ .tile-top .mono{font-weight:500;font-size:13px;overflow-wrap:anywhere}
341
+ .tile p{max-width:64ch}
342
+ .detail{margin:0;padding:0;list-style:none;display:grid;gap:2px;color:var(--text-secondary);overflow-wrap:anywhere}
343
+ .next b{font-weight:500;color:var(--text-secondary)}
344
+ details.more>summary{list-style:none;cursor:pointer;display:flex;align-items:center;justify-content:space-between;gap:10px;padding:12px;border-radius:10px;background:var(--bg-inner);box-shadow:var(--shadow-card)}
345
+ details.more>summary::-webkit-details-marker{display:none}
346
+ details.more>summary svg{color:var(--text-secondary);transition:transform .2s ease}
347
+ details.more[open]>summary svg{transform:rotate(180deg)}
348
+ details.more[open]>summary{margin-bottom:8px}
349
+ details.more .list{display:grid;gap:8px}
350
+ .row-gap{display:flex;gap:8px;align-items:center}
351
+ details.auto{margin:0 20px 14px;padding:10px 12px;border-radius:10px;background:var(--bg-secondary)}
352
+ details.auto summary{cursor:pointer}
353
+ details.auto ul{margin:8px 0 0;padding-left:18px;display:grid;gap:2px}
354
+ .empty{display:flex;gap:8px;align-items:center;padding:12px;border-radius:10px;background:var(--bg-inner);box-shadow:var(--shadow-card)}
355
+ .foot{display:flex;flex-wrap:wrap;gap:4px 20px}.foot a{color:var(--accent-500)}
356
+ @media (max-width:1000px){.stats{grid-template-columns:repeat(2,minmax(0,1fr))}.main{grid-template-columns:minmax(0,1fr)}}
357
+ @media (max-width:480px){.stat{min-height:116px;padding:14px}.stat .t-title-1{font-size:20px;line-height:28px}td.bar{min-width:110px}}
358
+ @media (prefers-reduced-motion:reduce){details.more>summary svg{transition:none}}
359
+ @media print{.card,.panel,.stat{break-inside:avoid}details.more::details-content{content-visibility:visible;display:block}}
360
+ `;
package/dist/index.d.ts CHANGED
@@ -1,9 +1,10 @@
1
1
  export { snapshot, type SnapshotOptions, type SnapshotResult } from './snapshot.js';
2
2
  export { connect, listTools, type Target, type Connection } from './connect.js';
3
3
  export { buildMenu, countTokens, loadMenu, toolTokens } from './menu.js';
4
- export { diffMenus, versionBump, DIFF_RULES, type DiffResult, type DiffOptions, type DiffFinding, type ChangeClass, type Bump, type TokenChange } from './diff.js';
4
+ export { reviewMenus, formatReview, fileFindings, type ReviewResult, type ReviewOptions, type Verdict } from './review.js';
5
+ export { diffMenus, comparedTools, versionBump, DIFF_RULES, type DiffTools, type DiffResult, type DiffOptions, type DiffFinding, type ChangeClass, type Bump, type TokenChange } from './diff.js';
5
6
  export { history, historyCsv, npmSource, classifyFailure, WATCHED_DEPENDENCIES, type HistoryResult, type HistoryRow, type HistoryOptions, type PackageSource, type PublishedVersion, type FailureReason } from './history.js';
6
- export { session, loadScenario, parseScenario, changeFindings, starterScenario, type Scenario, type Step, type SessionResult, type SessionOptions, type StepRecord, type Scope } from './session.js';
7
+ export { session, stepMenu, loadScenario, parseScenario, changeFindings, starterScenario, type StepTool, type Scenario, type Step, type SessionResult, type SessionOptions, type StepRecord, type Scope } from './session.js';
7
8
  export { compareMenus, cacheBreak, canonical, type ToolChange, type ChangeKind, type CacheBreak } from './compare.js';
8
9
  export { MENU_RULES, runRules, type Rule, type RuleContext, type RuleSettings } from './rules/index.js';
9
10
  export { loadRoutes, routeScores, type Routes } from './routes.js';
package/dist/index.js CHANGED
@@ -1,9 +1,10 @@
1
1
  export { snapshot } from './snapshot.js';
2
2
  export { connect, listTools } from './connect.js';
3
3
  export { buildMenu, countTokens, loadMenu, toolTokens } from './menu.js';
4
- export { diffMenus, versionBump, DIFF_RULES } from './diff.js';
4
+ export { reviewMenus, formatReview, fileFindings } from './review.js';
5
+ export { diffMenus, comparedTools, versionBump, DIFF_RULES } from './diff.js';
5
6
  export { history, historyCsv, npmSource, classifyFailure, WATCHED_DEPENDENCIES } from './history.js';
6
- export { session, loadScenario, parseScenario, changeFindings, starterScenario } from './session.js';
7
+ export { session, stepMenu, loadScenario, parseScenario, changeFindings, starterScenario } from './session.js';
7
8
  export { compareMenus, cacheBreak, canonical } from './compare.js';
8
9
  export { MENU_RULES, runRules } from './rules/index.js';
9
10
  export { loadRoutes, routeScores } from './routes.js';
package/dist/init.d.ts CHANGED
@@ -1,4 +1,18 @@
1
1
  import type { Target } from './connect.js';
2
+ /**
3
+ * The actions the workflow uses, pinned to the commit of a release (the version in a
4
+ * comment): a tag can be moved to other code, a commit can't. Dependabot's
5
+ * github-actions updates keep pins like these current. The toolmenu Action itself is
6
+ * named by its version tag: this release's commit isn't known when it's built.
7
+ */
8
+ export declare const ACTIONS: {
9
+ readonly checkout: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1';
10
+ readonly node: 'actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0';
11
+ readonly pnpm: 'pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6.1.1';
12
+ readonly uv: 'astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0';
13
+ readonly python: 'actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0';
14
+ readonly go: 'actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0';
15
+ };
2
16
  export type ProjectKind = 'node' | 'python' | 'go' | 'rust' | 'unknown';
3
17
  export interface Project {
4
18
  kind: ProjectKind;
package/dist/init.js CHANGED
@@ -4,6 +4,20 @@ import { mkdir, writeFile } from 'node:fs/promises';
4
4
  import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
5
5
  import { parse as parseYaml } from 'yaml';
6
6
  import { VERSION } from './version.js';
7
+ /**
8
+ * The actions the workflow uses, pinned to the commit of a release (the version in a
9
+ * comment): a tag can be moved to other code, a commit can't. Dependabot's
10
+ * github-actions updates keep pins like these current. The toolmenu Action itself is
11
+ * named by its version tag: this release's commit isn't known when it's built.
12
+ */
13
+ export const ACTIONS = {
14
+ checkout: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1',
15
+ node: 'actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0',
16
+ pnpm: 'pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6.1.1',
17
+ uv: 'astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0',
18
+ python: 'actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0',
19
+ go: 'actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0',
20
+ };
7
21
  /**
8
22
  * What the project in `dir` looks like, and how CI gets it ready to run. `root` is
9
23
  * the repository root: CI works from there, so steps for a project in a subfolder
@@ -58,8 +72,8 @@ export function detectProject(dir, root = dir) {
58
72
  runs,
59
73
  creates: [...new Set([at(installDir, 'node_modules'), at(rel, 'node_modules'), ...(build ? [rel] : [])])],
60
74
  setup: [
61
- ...(pm === 'pnpm' ? ['- uses: pnpm/action-setup@v6'] : []),
62
- '- uses: actions/setup-node@v7',
75
+ ...(pm === 'pnpm' ? [`- uses: ${ACTIONS.pnpm}`] : []),
76
+ `- uses: ${ACTIONS.node}`,
63
77
  ` with: { node-version: 22${cache} }`,
64
78
  ...(installDir === rel ? step(runs[0], rel) : [...step(install, installDir), ...(build ? step(build, rel) : [])]),
65
79
  ],
@@ -79,13 +93,13 @@ export function detectProject(dir, root = dir) {
79
93
  creates: uvLock ? [at(uvLock.dir, '.venv')] : [],
80
94
  // setup-uv has no floating major tag (v10): only full versions resolve.
81
95
  setup: uv
82
- ? ['- uses: astral-sh/setup-uv@v10.2.0', ...step(run, rel)]
83
- : ['- uses: actions/setup-python@v7', " with: { python-version: '3.12' }", ...step(run, rel)],
96
+ ? [`- uses: ${ACTIONS.uv}`, ...step(run, rel)]
97
+ : [`- uses: ${ACTIONS.python}`, " with: { python-version: '3.12' }", ...step(run, rel)],
84
98
  };
85
99
  }
86
100
  if (has('go.mod')) {
87
101
  // go build ./... keeps no binary unless it matches one main package: nothing counted.
88
- return { kind: 'go', file: at(rel, 'go.mod'), dir: rel, runs: ['go build ./...'], creates: [], setup: ['- uses: actions/setup-go@v7', ` with: { go-version-file: ${at(rel, 'go.mod')} }`, ...step('go build ./...', rel)] };
102
+ return { kind: 'go', file: at(rel, 'go.mod'), dir: rel, runs: ['go build ./...'], creates: [], setup: [`- uses: ${ACTIONS.go}`, ` with: { go-version-file: ${at(rel, 'go.mod')} }`, ...step('go build ./...', rel)] };
89
103
  }
90
104
  if (has('Cargo.toml'))
91
105
  return { kind: 'rust', file: at(rel, 'Cargo.toml'), dir: rel, runs: ['cargo build --release'], creates: [at(rel, 'target')], setup: step('cargo build --release', rel) };
@@ -169,7 +183,7 @@ export function workflowYaml(opts) {
169
183
  ' toolmenu:',
170
184
  ' runs-on: ubuntu-latest',
171
185
  ' steps:',
172
- ' - uses: actions/checkout@v7',
186
+ ` - uses: ${ACTIONS.checkout}`,
173
187
  ...(t.kind === 'stdio' ? opts.project.setup.map((l) => ` ${l}`) : []),
174
188
  ` - uses: niksa90/toolmenu@v${VERSION}`,
175
189
  ' with:',
@@ -0,0 +1,17 @@
1
+ import { type Finding, type Severity } from './types.js';
2
+ export interface JunitOptions {
3
+ /** snapshot, diff or session: the suite's name. */
4
+ command: string;
5
+ /** Findings at or above this level fail (default: error, as --fail-on). */
6
+ failOn?: Severity;
7
+ /** The menu file or server checked, shown as the suite's property. */
8
+ target?: string;
9
+ }
10
+ /**
11
+ * Text that is safe inside an XML attribute or element: C0 controls XML can't hold are
12
+ * dropped; the rest a terminal or a reader would act on or not see (CR, DEL, C1, bidi
13
+ * and other format characters; the same class reports escape) as character references,
14
+ * so --format junit printed to a terminal carries none of them raw.
15
+ */
16
+ export declare function xml(text: string): string;
17
+ export declare function toJunit(findings: Finding[], options: JunitOptions): string;
package/dist/junit.js ADDED
@@ -0,0 +1,87 @@
1
+ /*
2
+ * JUnit XML output, for CI systems that show test results natively: GitLab merge
3
+ * requests, Jenkins, Azure DevOps, CircleCI, Buildkite and GitHub test-report actions.
4
+ *
5
+ * Each finding is one test case. Findings at or above --fail-on are <failure>s, so the
6
+ * test report agrees with the exit code; findings below it pass, with their text in
7
+ * <system-out>. A run with no findings is one passing case, so the CI system records
8
+ * that the check ran rather than finding an empty report.
9
+ *
10
+ * A case's name is the tool it's about (and which of that rule's findings on that
11
+ * tool), not the message: messages carry counts that change between runs, and CI
12
+ * systems track a test's history by its name.
13
+ */
14
+ import { HIDDEN_SOURCE } from './sanitize.js';
15
+ import { SEVERITY_RANK } from './types.js';
16
+ import { VERSION } from './version.js';
17
+ import { toolsOf } from './sarif.js';
18
+ /** Hidden characters but tab and newline, which XML keeps as they are. */
19
+ const HIDDEN_IN_XML = new RegExp(`(?![\\t\\n])${HIDDEN_SOURCE}`, 'gu');
20
+ /**
21
+ * Text that is safe inside an XML attribute or element: C0 controls XML can't hold are
22
+ * dropped; the rest a terminal or a reader would act on or not see (CR, DEL, C1, bidi
23
+ * and other format characters; the same class reports escape) as character references,
24
+ * so --format junit printed to a terminal carries none of them raw.
25
+ */
26
+ export function xml(text) {
27
+ return text
28
+ .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]/g, '')
29
+ .replace(/&/g, '&amp;')
30
+ .replace(/</g, '&lt;')
31
+ .replace(/>/g, '&gt;')
32
+ .replace(/"/g, '&quot;')
33
+ .replace(HIDDEN_IN_XML, (c) => `&#x${c.codePointAt(0).toString(16)};`);
34
+ }
35
+ function body(f) {
36
+ return [
37
+ f.message,
38
+ ...(f.detail ?? []),
39
+ ...(f.step !== undefined ? [`step: ${f.steps?.length ? f.steps.join(', ') : f.step}`] : []),
40
+ ...(f.fix ? [`→ Next: ${f.fix}`] : []),
41
+ ...(f.confidence === 'unsure' ? ['(unsure: a heuristic, from names and words)'] : []),
42
+ `toolmenu explain ${f.rule}`,
43
+ ].join('\n');
44
+ }
45
+ export function toJunit(findings, options) {
46
+ const failOn = options.failOn ?? 'error';
47
+ const suite = `toolmenu ${options.command}`;
48
+ const seen = new Map();
49
+ const cases = [];
50
+ let failures = 0;
51
+ for (const f of findings) {
52
+ const tools = toolsOf(f);
53
+ // One case per tool, as SARIF has one result per tool.
54
+ for (const tool of tools.length ? tools : [undefined]) {
55
+ const key = `${f.rule}\u0000${tool ?? ''}`;
56
+ const nth = seen.get(key) ?? 0;
57
+ seen.set(key, nth + 1);
58
+ const name = `${tool ?? '(menu)'}${nth ? ` #${nth + 1}` : ''}`;
59
+ const open = ` <testcase classname="${xml(`toolmenu.${options.command}.${f.rule}`)}" name="${xml(name)}" time="0">`;
60
+ if (SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) {
61
+ failures++;
62
+ cases.push(`${open}\n <failure type="${f.severity}" message="${xml(f.message)}">${xml(body(f))}</failure>\n </testcase>`);
63
+ }
64
+ else {
65
+ cases.push(`${open}\n <system-out>${xml(`${f.severity}: ${body(f)}`)}</system-out>\n </testcase>`);
66
+ }
67
+ }
68
+ }
69
+ if (!cases.length)
70
+ cases.push(` <testcase classname="${xml(`toolmenu.${options.command}`)}" name="no findings" time="0"/>`);
71
+ const properties = [
72
+ ` <property name="toolmenu.version" value="${xml(VERSION)}"/>`,
73
+ ` <property name="fail-on" value="${failOn}"/>`,
74
+ ...(options.target ? [` <property name="target" value="${xml(options.target)}"/>`] : []),
75
+ ];
76
+ return [
77
+ '<?xml version="1.0" encoding="UTF-8"?>',
78
+ `<testsuites name="toolmenu" tests="${cases.length}" failures="${failures}" errors="0" time="0">`,
79
+ ` <testsuite name="${xml(suite)}" tests="${cases.length}" failures="${failures}" errors="0" skipped="0" time="0">`,
80
+ ' <properties>',
81
+ ...properties,
82
+ ' </properties>',
83
+ ...cases,
84
+ ' </testsuite>',
85
+ '</testsuites>',
86
+ ].join('\n');
87
+ }
package/dist/mcp-env.d.ts CHANGED
@@ -3,3 +3,9 @@
3
3
  * values), shared with the CLI. Its own module so the CLI doesn't load the server SDK.
4
4
  */
5
5
  export declare const SECRET_ARGS_ENV = "TOOLMENU_MCP_ARGS";
6
+ /**
7
+ * The same, for anyone: a JSON array of arguments the CLI adds before "--", so
8
+ * --header, --env and --client-secret values stay off the command line (which other
9
+ * local users can read with ps). The Action passes its headers and env this way.
10
+ */
11
+ export declare const ARGS_ENV = "TOOLMENU_ARGS";
package/dist/mcp-env.js CHANGED
@@ -3,3 +3,9 @@
3
3
  * values), shared with the CLI. Its own module so the CLI doesn't load the server SDK.
4
4
  */
5
5
  export const SECRET_ARGS_ENV = 'TOOLMENU_MCP_ARGS';
6
+ /**
7
+ * The same, for anyone: a JSON array of arguments the CLI adds before "--", so
8
+ * --header, --env and --client-secret values stay off the command line (which other
9
+ * local users can read with ps). The Action passes its headers and env this way.
10
+ */
11
+ export const ARGS_ENV = 'TOOLMENU_ARGS';