1
/**
2
 * An ICE pair ranker: paste both sides' candidates and see the checklist RFC 8445 builds from them, in order.
3
 *
4
 * Three steps, each one a place to go wrong by hand:
5
 *
6
 *  1. **Pair** every local candidate with every remote one of the same component, transport and address family
7
 *     (section 6.1.2.2), and price each pair: 2^32*min(G,D) + 2*max(G,D) + (G>D?1:0), with G the controlling agent's
8
 *     candidate priority and D the controlled one's (6.1.2.3).
9
 *  2. **Replace** each server-reflexive or peer-reflexive local candidate by its base, the address its packets really
10
 *     leave from, and **prune** a pair that now duplicates a higher-priority one (6.1.2.4). A server-reflexive
11
 *     candidate is never checked on its own; its job is to tell the other side where to send.
12
 *  3. **Order** what is left by priority, and keep the first 100 (6.1.2.5). That is the order the checks run in.
13
 *
14
 * Candidates come from whatever the reader has: SDP `a=candidate` lines, a whole offer or answer, the JSON of an
15
 * RTCIceCandidate or a list of them, or the JSON of `getStats()`, whose local-candidate and remote-candidate entries
16
 * fill both sides at once. Copying the lines out by hand is the step people get wrong, so the tool does it.
17
 *
18
 * Priorities are read as given, never recomputed, because they are what the agents exchanged; each one is also
19
 * decoded into its type, local preference and component, so a hand-made line that does not match its own type is
20
 * visible.
21
 */
22
import type { Cell, Field, Output, Tool } from "@toolbench/sdk";
23

24
type Input = { local: string; remote: string; controlling: string };
25

26
class InputError extends Error {
27
  readonly input: string;
28
  constructor(message: string, input: string) {
29
    super(message);
30
    this.input = input;
31
  }
32
}
33

34
interface Candidate {
35
  where: string;
36
  foundation: string;
37
  component: number;
38
  transport: string;
39
  priority: number;
40
  address: string;
41
  port: number;
42
  type: string;
43
  raddr?: string;
44
  rport?: number;
45
  tcptype?: string;
46
}
47

48
const TYPE_PREF: Record<number, string> = { 126: "host", 110: "prflx", 100: "srflx", 0: "relay" };
49
const TYPE_NAME: Record<string, string> = { host: "host", srflx: "server-reflexive", prflx: "peer-reflexive", relay: "relayed" };
50
/** RFC 8445 section 5.1.2.2's recommended order. Only the order is a rule; the numbers are recommendations. */
51
const TYPE_RANK: Record<string, number> = { host: 3, prflx: 2, srflx: 1, relay: 0 };
52
/** The default checklist size, RFC 8445 section 6.1.2.5. */
53
const PAIR_LIMIT = 100;
54

55
/**
56
 * One `candidate:` attribute, as RFC 8839 section 5.1 writes it, at a known position. Each token stops at a quote,
57
 * a backslash or a comma, so the same expression reads a line of SDP and a candidate string inside JSON.
58
 */
59
const CANDIDATE =
60
  /candidate:([^\s"\\,]+)\s+(\d+)\s+([^\s"\\,]+)\s+(\d+)\s+([^\s"\\,]+)\s+(\d+)\s+typ\s+([^\s"\\,]+)((?:\s+[a-z][a-z-]*\s+[^\s"\\,]+)*)/iy;
61
/** Where a candidate attribute starts: "candidate:" not inside a longer word, so not "remote-candidates:". */
62
const START = /(?<![\w-])candidate:/gi;
63

64
interface Parsed {
65
  candidates: Candidate[];
66
  /** getStats' remote-candidate entries, which fill the other side when it was left empty. */
67
  others: Candidate[];
68
  repeats: number;
69
  lite: boolean;
70
  source: "lines" | "stats";
71
}
72

73
function fromLines(text: string, input: string): Candidate[] {
74
  const out: Candidate[] = [];
75
  for (const start of text.matchAll(START)) {
76
    CANDIDATE.lastIndex = start.index;
77
    const m = CANDIDATE.exec(text);
78
    const line = text.slice(0, start.index).split("\n").length;
79
    if (!m) {
80
      throw new InputError(
81
        `Line ${line} has a candidate that does not parse: expected "candidate:<foundation> <component> <transport> <priority> <address> <port> typ <type>".`,
82
        input,
83
      );
84
    }
85
    const extras = m[8] ?? "";
86
    const raddr = /\braddr\s+([^\s"\\,]+)/.exec(extras)?.[1];
87
    const rport = /\brport\s+(\d+)/.exec(extras)?.[1];
88
    const tcptype = /\btcptype\s+(\w+)/.exec(extras)?.[1];
89
    const type = m[7]!.toLowerCase();
90
    if (!TYPE_NAME[type]) throw new InputError(`Line ${line} has type "${m[7]}", but ICE's types are host, srflx, prflx and relay.`, input);
91
    out.push({
92
      where: `line ${line}`,
93
      foundation: m[1]!,
94
      component: Number(m[2]),
95
      transport: m[3]!.toLowerCase(),
96
      priority: Number(m[4]),
97
      address: m[5]!,
98
      port: Number(m[6]),
99
      type,
100
      ...(raddr ? { raddr } : {}),
101
      ...(rport ? { rport: Number(rport) } : {}),
102
      ...(tcptype ? { tcptype: tcptype.toLowerCase() } : {}),
103
    });
104
  }
105
  return out;
106
}
107

108
type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
109

110
/**
111
 * getStats' candidate entries (W3C webrtc-stats, RTCIceCandidateStats), from `JSON.stringify([...report.values()])`,
112
 * an object keyed by id, or `[...report]` pairs: every object anywhere in the paste whose `type` is local-candidate or
113
 * remote-candidate. getStats has no component, because a bundled, rtcp-muxed call has only one, so it is 1.
114
 */
115
function fromStats(text: string): { local: Candidate[]; remote: Candidate[] } | undefined {
116
  const trimmed = text.trim();
117
  if (!/^[[{]/.test(trimmed)) return undefined;
118
  let json: Json;
119
  try {
120
    json = JSON.parse(trimmed) as Json;
121
  } catch {
122
    return undefined;
123
  }
124
  const local: Candidate[] = [];
125
  const remote: Candidate[] = [];
126
  const walk = (v: Json): void => {
127
    if (Array.isArray(v)) return v.forEach(walk);
128
    if (v === null || typeof v !== "object") return;
129
    const t = v.type;
130
    if (t === "local-candidate" || t === "remote-candidate") {
131
      const side = t === "local-candidate" ? local : remote;
132
      const address = String(v.address ?? v.ip ?? "");
133
      const type = String(v.candidateType ?? "").toLowerCase();
134
      if (address && TYPE_NAME[type] && typeof v.port === "number" && typeof v.priority === "number") {
135
        side.push({
136
          where: `entry ${String(v.id ?? side.length + 1)}`,
137
          foundation: String(v.foundation ?? v.id ?? side.length + 1),
138
          component: 1,
139
          transport: String(v.protocol ?? "udp").toLowerCase(),
140
          priority: v.priority,
141
          address,
142
          port: v.port,
143
          type,
144
          ...(typeof v.relatedAddress === "string" && v.relatedAddress ? { raddr: v.relatedAddress } : {}),
145
          ...(typeof v.relatedPort === "number" ? { rport: v.relatedPort } : {}),
146
          ...(typeof v.tcpType === "string" ? { tcptype: v.tcpType } : {}),
147
        });
148
      }
149
      return;
150
    }
151
    Object.values(v).forEach(walk);
152
  };
153
  walk(json);
154
  return local.length || remote.length ? { local, remote } : undefined;
155
}
156

157
/** The same candidate pasted twice, from two m-sections of an unbundled SDP or two copies of a line. */
158
function dedupe(list: Candidate[]): { kept: Candidate[]; repeats: number } {
159
  const seen = new Set<string>();
160
  const kept = list.filter((c) => {
161
    const key = `${c.component}|${c.transport}|${c.address}|${c.port}|${c.type}`;
162
    if (seen.has(key)) return false;
163
    seen.add(key);
164
    return true;
165
  });
166
  return { kept, repeats: list.length - kept.length };
167
}
168

169
function parse(text: string, input: string): Parsed {
170
  const lite = /(?:^|\n)\s*a=ice-lite\b/.test(text);
171
  const stats = fromStats(text);
172
  if (stats) {
173
    const a = dedupe(stats.local);
174
    const b = dedupe(stats.remote);
175
    return { candidates: a.kept, others: b.kept, repeats: a.repeats + b.repeats, lite, source: "stats" };
176
  }
177
  const { kept, repeats } = dedupe(fromLines(text, input));
178
  return { candidates: kept, others: [], repeats, lite, source: "lines" };
179
}
180

181
/** IPv4, IPv6, or an mDNS name, which a browser uses to hide a private address and which pairs with either. */
182
function family(address: string): "v4" | "v6" | "mdns" {
183
  if (/\.local\.?$/i.test(address)) return "mdns";
184
  return address.includes(":") ? "v6" : "v4";
185
}
186

187
/** An address the internet cannot route to: RFC 1918, carrier-grade NAT, link-local, unique-local IPv6. */
188
function isPrivate(address: string): boolean {
189
  if (family(address) === "mdns") return true;
190
  const v4 = /^(\d+)\.(\d+)\./.exec(address);
191
  if (v4) {
192
    const [a, b] = [Number(v4[1]), Number(v4[2])];
193
    return a === 10 || a === 127 || (a === 172 && b >= 16 && b < 32) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b < 128) || (a === 169 && b === 254);
194
  }
195
  return /^(?:f[cd]|fe[89ab])/i.test(address) || address === "::1";
196
}
197

198
const pairPriority = (g: number, d: number) => 2n ** 32n * BigInt(Math.min(g, d)) + 2n * BigInt(Math.max(g, d)) + (g > d ? 1n : 0n);
199

200
/** The base a check is sent from: a reflexive candidate's related address, which is the host it was learned from. */
201
function base(c: Candidate, locals: Candidate[]): Candidate {
202
  if (c.type !== "srflx" && c.type !== "prflx") return c;
203
  return locals.find((l) => l.type === "host" && l.address === c.raddr && l.port === c.rport && l.component === c.component) ?? c;
204
}
205

206
/*
207
 * A reflexive candidate whose related address names no listed host. Browsers send "raddr 0.0.0.0" to hide it, and
208
 * the check still leaves from a host, so calling the candidate its own base would teach the opposite of the RFC.
209
 * It is not pruned either: the host may simply not be in the list, and then this pair is checked.
210
 */
211
const reflexive = (c: Candidate) => c.type === "srflx" || c.type === "prflx";
212

213
/** TCP candidates pair active with passive and simultaneous-open with itself (RFC 6544 section 6.2). */
214
function tcpCompatible(l: Candidate, r: Candidate): boolean {
215
  if (l.transport !== "tcp" || !l.tcptype || !r.tcptype) return true;
216
  if (l.tcptype === "so") return r.tcptype === "so";
217
  return (l.tcptype === "active" && r.tcptype === "passive") || (l.tcptype === "passive" && r.tcptype === "active");
218
}
219

220
function decode(p: number): string {
221
  const tp = Math.floor(p / 2 ** 24);
222
  return `Type preference ${tp}${TYPE_PREF[tp] ? `, which is ${TYPE_PREF[tp]} in RFC 8445's recommended values` : ""}. Local preference ${(p >>> 8) & 0xffff}, component ${256 - (p & 0xff)}.`;
223
}
224

225
type Tone = "good" | "warn" | "bad";
226
type Action = { tone: Tone | "normal"; problem: string; fix: string };
227

228
/** A relay that outranks a direct path on its own side: its checks run first and its traffic goes through a server. */
229
function rankProblem(side: Candidate[], name: string): Action | undefined {
230
  const tp = (c: Candidate) => Math.floor(c.priority / 2 ** 24);
231
  for (const a of side) {
232
    for (const b of side) {
233
      if (TYPE_RANK[a.type]! < TYPE_RANK[b.type]! && tp(a) > tp(b)) {
234
        return {
235
          tone: "warn",
236
          problem: `The ${name} ${a.type} candidate on ${a.where} has a higher type preference (${tp(a)}) than the ${b.type} on ${b.where} (${tp(b)}).`,
237
          fix: `RFC 8445 asks for host above peer-reflexive above server-reflexive above relayed. With this order, checks through the ${a.type} candidate run first. If the stack was configured by hand, put the type preferences back in that order.`,
238
        };
239
      }
240
    }
241
  }
242
  return undefined;
243
}
244

245
export default {
246
  run(input: Input) {
247
    try {
248
      const mine = parse(input.local, "local");
249
      const theirs = input.remote.trim() ? parse(input.remote, "remote") : undefined;
250
      const locals = mine.candidates;
251
      // One getStats paste has both sides; the remote box can then stay empty.
252
      const remotes = theirs ? (theirs.source === "stats" && theirs.candidates.length === 0 ? theirs.others : theirs.candidates) : mine.others;
253
      if (locals.length === 0) {
254
        throw new InputError("No local candidates found. Paste a=candidate lines, a whole SDP, RTCIceCandidate JSON, or the JSON of getStats().", "local");
255
      }
256
      if (remotes.length === 0) {
257
        throw new InputError(
258
          mine.source === "stats"
259
            ? "The getStats paste has no remote-candidate entries. Paste the other side's candidates here."
260
            : "No remote candidates found. Paste the other side's a=candidate lines, its SDP, or getStats JSON with remote-candidate entries.",
261
          "remote",
262
        );
263
      }
264
      const localControls = input.controlling !== "remote";
265
      const repeats = mine.repeats + (theirs?.repeats ?? 0);
266

267
      type Pair = { l: Candidate; r: Candidate; b: Candidate; priority: bigint; state: "check" | "pruned" | "over"; same?: Pair };
268
      const pairs: Pair[] = [];
269
      for (const l of locals) {
270
        for (const r of remotes) {
271
          if (l.component !== r.component || l.transport !== r.transport || !tcpCompatible(l, r)) continue;
272
          const fl = family(l.address);
273
          const fr = family(r.address);
274
          if (fl !== "mdns" && fr !== "mdns" && fl !== fr) continue;
275
          const [g, d] = localControls ? [l.priority, r.priority] : [r.priority, l.priority];
276
          pairs.push({ l, r, b: base(l, locals), priority: pairPriority(g, d), state: "check" });
277
        }
278
      }
279
      if (pairs.length === 0) {
280
        throw new InputError("No candidates can be paired: a pair needs the same component, the same transport and the same address family on both sides.", "remote");
281
      }
282
      pairs.sort((a, b) => (a.priority > b.priority ? -1 : a.priority < b.priority ? 1 : 0));
283
      const seen = new Map<string, Pair>();
284
      let kept = 0;
285
      for (const p of pairs) {
286
        const key = `${p.b.address}:${p.b.port}|${p.r.address}:${p.r.port}|${p.l.component}`;
287
        const earlier = seen.get(key);
288
        if (earlier) {
289
          p.state = "pruned";
290
          p.same = earlier;
291
        } else if (++kept > PAIR_LIMIT) {
292
          p.state = "over";
293
        } else seen.set(key, p);
294
      }
295
      const checks = pairs.filter((p) => p.state === "check");
296
      const pruned = pairs.filter((p) => p.state === "pruned").length;
297
      const over = pairs.filter((p) => p.state === "over").length;
298
      const label = (c: Candidate) => `${c.type} ${c.address}:${c.port}`;
299
      const words = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
300

301
      // What to do, worst first. Each is a rule a reader can act on, not a restatement of the table.
302
      const actions: Action[] = [];
303
      const remoteLite = theirs?.lite ?? false;
304
      if (mine.lite && remoteLite) {
305
        actions.push({ tone: "warn", problem: "Both sides are ICE-lite.", fix: "Between two lite agents no connectivity checks are sent at all (RFC 8445 section 6.1.1), so this order never runs. One side has to run full ICE." });
306
      } else if (remoteLite && !localControls) {
307
        actions.push({ tone: "warn", problem: "The remote side is ICE-lite, and a lite agent is always the controlled one.", fix: "Set the controlling side to Local (RFC 8445 section 6.1.1)." });
308
      } else if (mine.lite && localControls) {
309
        actions.push({ tone: "warn", problem: "The local side is ICE-lite, and a lite agent is always the controlled one.", fix: "Set the controlling side to Remote (RFC 8445 section 6.1.1)." });
310
      }
311
      const anyRelay = [...locals, ...remotes].some((c) => c.type === "relay");
312
      if (!anyRelay) {
313
        const publicRemote = remotes.some((c) => c.type === "host" && !isPrivate(c.address));
314
        actions.push(
315
          publicRemote
316
            ? {
317
                tone: "normal",
318
                problem: "Neither side has a relayed candidate, but the remote side has a public host address.",
319
                fix: "That usually connects. Only a network that blocks UDP stops it; a TURN server over TCP or TLS on port 443 is the fallback.",
320
              }
321
            : {
322
                tone: "warn",
323
                problem: "Neither side has a relayed candidate, so there is no fallback through a server.",
324
                fix: "If a firewall blocks UDP, or both NATs give a new port per destination, every check fails and the call never connects. Add a TURN server to iceServers.",
325
              },
326
        );
327
      }
328
      for (const problem of [rankProblem(locals, "local"), rankProblem(remotes, "remote")]) if (problem) actions.push(problem);
329
      if (over) {
330
        actions.push({
331
          tone: "warn",
332
          problem: `${words(pairs.length - pruned, "pair is", "pairs are")} left after pruning, more than the ${PAIR_LIMIT} a checklist holds by default.`,
333
          fix: `The lowest ${words(over, "pair is", "pairs are")} never checked (RFC 8445 section 6.1.2.5). Gather fewer candidates, for example one network interface.`,
334
        });
335
      }
336
      const mdnsRemote = remotes.filter((c) => family(c.address) === "mdns").length;
337
      if (mdnsRemote) {
338
        actions.push({
339
          tone: "normal",
340
          problem: `${words(mdnsRemote, "remote host candidate is an mDNS name", "remote host candidates are mDNS names")}, ending in .local.`,
341
          fix: "A name like that only resolves on the same local network. Across the internet, the reflexive or relayed pairs carry the call.",
342
        });
343
      }
344
      const hidden = locals.filter((c) => reflexive(c) && base(c, locals) === c).length;
345
      if (hidden) {
346
        actions.push({
347
          tone: "normal",
348
          problem: `${words(hidden, "local reflexive candidate does", "local reflexive candidates do")} not say which host address ${hidden === 1 ? "it was" : "they were"} learned from.`,
349
          fix: "Browsers hide it as raddr 0.0.0.0. Its pairs are kept here; if the host it came from is listed, the browser prunes them.",
350
        });
351
      }
352
      const unpaired = [...locals.map((c) => ["local", c] as const), ...remotes.map((c) => ["remote", c] as const)].filter(
353
        ([side, c]) => !pairs.some((p) => (side === "local" ? p.l : p.r) === c),
354
      );
355
      if (unpaired.length) {
356
        actions.push({
357
          tone: "normal",
358
          problem: `${words(unpaired.length, "candidate has", "candidates have")} nothing to pair with: ${unpaired.map(([side, c]) => `${side} ${label(c)}`).join(", ")}.`,
359
          fix: "A pair needs the same component, transport and address family on both sides. An IPv6 candidate needs an IPv6 one on the other side.",
360
        });
361
      }
362
      if (repeats) {
363
        actions.push({
364
          tone: "normal",
365
          problem: `${words(repeats, "candidate was", "candidates were")} pasted more than once.`,
366
          fix: "Each is counted once. An SDP without BUNDLE repeats its candidates in every media section.",
367
        });
368
      }
369
      const worst = { bad: 0, warn: 1, normal: 2, good: 3 };
370
      actions.sort((a, b) => worst[a.tone] - worst[b.tone]);
371

372
      /*
373
       * The answer is a list, so it is drawn as one: the computed order, which the tool works out from the RFC and
374
       * does not observe. The arithmetic and the candidates' own priorities go last, for the reader checking it.
375
       */
376
      const method: Field[] = [
377
        {
378
          group: "Roles",
379
          label: "Controlling",
380
          value: localControls ? "local" : "remote",
381
          note: "Its candidate priorities are G in the pair formula, the other side's D.",
382
        },
383
        { group: "Roles", label: "Pair priority", value: "2^32 x min(G, D) + 2 x max(G, D) + (G > D ? 1 : 0)", note: "RFC 8445 section 6.1.2.3" },
384
        {
385
          group: "Roles",
386
          label: "Read from",
387
          value: mine.source === "stats" || theirs?.source === "stats" ? "getStats() JSON" : "candidate attributes",
388
          note: mine.source === "stats" && !theirs ? "The local-candidate and remote-candidate entries of one report." : "Every candidate: attribute in the paste, wherever it was.",
389
        },
390
        ...locals.map((c) => ({ group: "Local candidates", label: `${c.type}, ${c.where}`, value: String(c.priority), note: decode(c.priority) })),
391
        ...remotes.map((c) => ({ group: "Remote candidates", label: `${c.type}, ${c.where}`, value: String(c.priority), note: decode(c.priority) })),
392
      ];
393
      const order = new Map(checks.map((p, i) => [p, i + 1]));
394
      const via = (p: Pair) => (p.l.type === "relay" || p.r.type === "relay" ? "TURN" : "direct");
395
      const ranked: Output = {
396
        kind: "table",
397
        role: "comparison",
398
        id: "order",
399
        caption: `Computed check order, highest priority first. ${localControls ? "Local" : "Remote"} side controls`,
400
        columns: [
401
          { label: "#", align: "end", mono: true, wrap: "none", rowHeader: true },
402
          { label: "Local", mono: true, wrap: "none" },
403
          { label: "Remote", mono: true, wrap: "none" },
404
          { label: "Route", wrap: "prose" },
405
          { label: "Priority", align: "end", mono: true, wrap: "none" },
406
        ],
407
        rows: checks.map((p): Cell[] => [
408
          { text: String(order.get(p)), mono: true },
409
          { text: label(p.l), mono: true },
410
          { text: label(p.r), mono: true },
411
          via(p),
412
          { text: String(p.priority), mono: true, tone: "muted" },
413
        ]),
414
      };
415
      const dropped = pairs.filter((p) => p.state !== "check");
416
      const prunedTable: Output | null = dropped.length
417
        ? {
418
            kind: "table",
419
            role: "decoded",
420
            id: "pruned",
421
            caption: over
422
              ? `Pruned, ${words(pruned, "pair", "pairs")} sending the same check as one above, and ${over} past the ${PAIR_LIMIT} a checklist holds`
423
              : `Pruned: ${pruned === 1 ? "this pair sends" : "these pairs send"} the same check, from the same place to the same place, as one above`,
424
            columns: [
425
              { label: "Local", mono: true, wrap: "none", rowHeader: true },
426
              { label: "Sent from", mono: true, wrap: "none" },
427
              { label: "Remote", mono: true, wrap: "none" },
428
              { label: "Same as", align: "end", wrap: "none" },
429
            ],
430
            rows: dropped.map((p): Cell[] => [
431
              { text: label(p.l), mono: true },
432
              { text: p.b !== p.l ? `${p.b.address}:${p.b.port}` : reflexive(p.l) ? "a host, hidden" : `${p.l.address}:${p.l.port}`, mono: true },
433
              { text: label(p.r), mono: true },
434
              p.same ? `#${order.get(p.same)}` : { text: `over ${PAIR_LIMIT}`, tone: "muted" },
435
            ]),
436
          }
437
        : null;
438
      const severity = (t: Action["tone"]) => (t === "bad" ? "Problem" : t === "warn" ? "Warning" : "Note");
439
      const findings: Output | null = actions.length
440
        ? {
441
            kind: "table",
442
            role: "findings",
443
            id: "findings",
444
            caption: "What to look at, most serious first",
445
            columns: [
446
              { label: "Severity", wrap: "none" },
447
              { label: "What we found", wrap: "prose" },
448
              { label: "What it means and what to do", wrap: "prose" },
449
            ],
450
            rows: actions.map((a): Cell[] => [{ text: severity(a.tone), tone: a.tone === "normal" ? "muted" : a.tone === "good" ? "muted" : a.tone }, a.problem, a.fix]),
451
          }
452
        : null;
453
      /*
454
       * The grid the post draws: local candidates down, remote across, each cell the pair's place in the check
455
       * order. A rank is a quantity of "how far down the list", so the one-hue scale gives a later check more ink (the
456
       * host decides which end that is in each theme) and the key's "1 runs first" says which way to read it; a pruned or
457
       * impossible pair is an empty cell rather than a colour that would claim a place.
458
       *
459
       * Only when both sides have two candidates or more: with one on either side it is a single row or column, and a
460
       * gradient along it says nothing the numbered list does not.
461
       */
462
      const values = locals.map((l) =>
463
        remotes.map((r) => {
464
          const p = pairs.find((x) => x.l === l && x.r === r);
465
          return p && p.state === "check" ? (order.get(p) ?? null) : null;
466
        }),
467
      );
468
      const heatmap: Output | null =
469
        locals.length >= 2 && remotes.length >= 2
470
          ? {
471
              kind: "heatmap",
472
              heatmap: {
473
                label: "Check order (1 runs first)",
474
                xLabel: "Remote",
475
                yLabel: "Local",
476
                x: remotes.map((c) => `${c.type} ${c.port}`),
477
                y: locals.map((c) => `${c.type} ${c.port}`),
478
                values,
479
                scale: "sequential",
480
              },
481
            }
482
          : null;
483
      const urgent = actions.some((a) => a.tone === "warn" || a.tone === "bad");
484
      const parts: Output[] = [ranked];
485
      if (findings && urgent) parts.push(findings);
486
      if (prunedTable) parts.push(prunedTable);
487
      if (findings && !urgent) parts.push(findings);
488
      if (heatmap) parts.push(heatmap);
489
      parts.push({ kind: "fields", role: "method", id: "method", fields: method });
490
      return { kind: "group", parts };
491
    } catch (error) {
492
      if (error instanceof InputError) return { kind: "error", message: error.message, input: error.input };
493
      throw error;
494
    }
495
  },
496
} satisfies Tool<Input>;