ckb-cycle-tools 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/diff.js CHANGED
@@ -6,11 +6,25 @@
6
6
  */
7
7
  /** How many functions a report keeps per group. */
8
8
  export const FUNCTION_LIMIT = 15;
9
+ /** The message for a binary no scenario's cell deps match, in a report's `errors` and the diff. */
10
+ export const unmatchedError = (name) => `binary "${name}" matched no cell dep in any scenario: check its outPoint / codeHash`;
9
11
  /** The base side of a new group that does not accept: compared with "did not run". */
10
12
  const NOT_RUN = "not run";
11
- /** `ok`, `exit 12`, or `error` (the VM stopped the script). */
13
+ /**
14
+ * `ok`, `exit 12`, or `error: <kind>` when the VM stopped the script: the
15
+ * debugger's message without its `key=value` details (a pc, an instruction),
16
+ * so "invalid instruction" and "max cycles exceeded" are different results.
17
+ */
12
18
  export function resultLabel(g) {
13
- return g.error ? "error" : g.result === 0 ? "ok" : `exit ${g.result}`;
19
+ return g.error ? `error: ${errorKind(g.error)}` : g.result === 0 ? "ok" : `exit ${g.result}`;
20
+ }
21
+ function errorKind(error) {
22
+ const kind = error
23
+ .replace(/\s*\b\w+=\S*/g, "")
24
+ .replace(/\b0x[0-9a-fA-F]+\b/g, "")
25
+ .replace(/\s+/g, " ")
26
+ .trim();
27
+ return (kind || "vm").slice(0, 80);
14
28
  }
15
29
  export function diffReports(base, head, options = {}) {
16
30
  const threshold = options.failAbove;
@@ -24,8 +38,9 @@ export function diffReports(base, head, options = {}) {
24
38
  return;
25
39
  }
26
40
  // A base that could not run the scenario has nothing to compare against, so
27
- // every group is new. Unless the scenario's binary is new in the head, that
28
- // is the base being broken, and the gate must not pass over it in silence.
41
+ // every group is new. That is the base being broken, and the gate must not
42
+ // pass over it in silence. (Only a report before 1.1.0 records a missing
43
+ // binary as a scenario error with binaryMissing; its groups count as new.)
29
44
  if (h && b?.error && !b.binaryMissing) {
30
45
  rows.push({ scenario: name, group: "", script: "", kind: "base-error", overThreshold: false, note: `base: ${b.error}` });
31
46
  }
@@ -42,16 +57,41 @@ export function diffReports(base, head, options = {}) {
42
57
  for (const b of base.scenarios)
43
58
  if (!headNames.has(b.name))
44
59
  scenarioRows(undefined, b);
60
+ const groups = rows.filter((r) => r.kind !== "error" && r.kind !== "base-error");
45
61
  return {
46
62
  rows,
47
63
  resultChanges: rows.filter((r) => r.kind === "result").length,
48
64
  overThreshold: rows.filter((r) => r.overThreshold).length,
49
65
  baseErrors: rows.filter((r) => r.kind === "base-error").length,
66
+ removed: groups.filter((r) => r.kind === "removed" || r.notCompared).length,
67
+ newGroups: groups.filter((r) => r.kind !== "removed" && (!r.base || r.base.result === NOT_RUN)).length,
68
+ reportErrors: [...reportErrors("base", base), ...reportErrors("head", head)],
69
+ warnings: head.scenarios.flatMap((s) => (s.warnings ?? []).map((text) => ({ scenario: s.name, text }))),
70
+ ...(base.debugger && head.debugger && base.debugger !== head.debugger && { debuggers: { base: base.debugger, head: head.debugger } }),
50
71
  ...(threshold !== undefined && { threshold }),
51
72
  };
52
73
  }
53
- function groupRow(scenario, b, h, threshold) {
74
+ /**
75
+ * A report's errors other than its scenarios' own (those are rows already),
76
+ * and, from its scenarios, any binary offered but swapped in nowhere: a report
77
+ * written without its `errors` still says that nothing measured that binary.
78
+ */
79
+ function reportErrors(side, r) {
80
+ const ofScenarios = new Set(r.scenarios.filter((s) => s.error).map((s) => `scenario "${s.name}": ${s.error}`));
81
+ const out = new Set((Array.isArray(r.errors) ? r.errors : []).map(String).filter((e) => !ofScenarios.has(e)));
82
+ // As the report does: only when every scenario ran (one that failed may be the one that uses it).
83
+ if (!ofScenarios.size) {
84
+ const swapped = new Set(r.scenarios.flatMap((s) => s.substituted ?? []));
85
+ for (const name of new Set(r.scenarios.flatMap((s) => s.unmatched ?? [])))
86
+ if (!swapped.has(name))
87
+ out.add(unmatchedError(name));
88
+ }
89
+ return [...out].map((e) => `${side}: ${e}`);
90
+ }
91
+ function groupRow(scenario, measured, h, threshold) {
54
92
  const side = (g) => ({ result: resultLabel(g), cycles: g.cycles });
93
+ // Measured without its binary (not in the base checkout): the mock's code, not the base's build.
94
+ const b = h && measured?.missingBinary ? undefined : measured;
55
95
  const row = {
56
96
  scenario,
57
97
  group: (h ?? b).selector,
@@ -61,18 +101,30 @@ function groupRow(scenario, b, h, threshold) {
61
101
  kind: !b ? "new" : !h ? "removed" : "same",
62
102
  overThreshold: false,
63
103
  };
104
+ if (measured?.missingBinary)
105
+ row.notCompared = `binary "${measured.missingBinary}" is not in the base checkout`;
64
106
  if (b && h) {
65
107
  row.delta = h.cycles - b.cycles;
66
- if (b.cycles > 0)
67
- row.percent = (row.delta / b.cycles) * 100;
68
- row.kind = resultLabel(b) !== resultLabel(h) ? "result" : row.delta !== 0 ? "changed" : "same";
69
- row.overThreshold =
70
- threshold !== undefined && row.delta > 0 && (row.percent === undefined || row.percent > threshold);
108
+ const changed = resultLabel(b) !== resultLabel(h);
109
+ row.kind = changed ? "result" : row.delta !== 0 ? "changed" : "same";
110
+ // A run the VM stopped has no cost to compare: no percentage, no growth.
111
+ if (!b.error && !h.error) {
112
+ if (b.cycles > 0)
113
+ row.percent = (row.delta / b.cycles) * 100;
114
+ row.overThreshold =
115
+ threshold !== undefined && row.delta > 0 && (row.percent === undefined || row.percent > threshold);
116
+ }
117
+ // The VM stopped the head (past the cycle limit, a bad instruction): its 0
118
+ // cycles are not a saving. Under --fail-above that is over any threshold.
119
+ if (h.error && changed && threshold !== undefined)
120
+ row.overThreshold = true;
71
121
  }
72
122
  else if (h && resultLabel(h) !== "ok") {
73
123
  // A new group that does not accept: against "did not run", its result changed.
74
124
  row.kind = "result";
75
125
  row.base = { result: NOT_RUN };
126
+ if (h.error && threshold !== undefined)
127
+ row.overThreshold = true;
76
128
  }
77
129
  if (h?.functions)
78
130
  row.functions = functionDeltas(b?.functions, h.functions);
@@ -105,14 +157,20 @@ export function functionDeltas(base, head) {
105
157
  }
106
158
  /**
107
159
  * Whether the diff should fail a check, per the options it was made with. A
108
- * scenario the head could not run always fails; one the base could not run
109
- * fails whenever a threshold is set, since nothing in it was checked.
160
+ * scenario the head could not run always fails. With a gate set (either
161
+ * option), so does anything that was not checked: a scenario the base could not
162
+ * run, an error in either report, and a base group with nothing to compare
163
+ * against (removed, renamed, moved, or measured without its binary) unless
164
+ * `allowRemoved`. A head group the VM stopped is a result change, and over any
165
+ * `failAbove` threshold.
110
166
  */
111
167
  export function diffFailed(diff, options = {}) {
112
168
  const gated = options.failAbove !== undefined || options.failOnResultChange === true;
113
169
  return ((options.failAbove !== undefined && diff.overThreshold > 0) ||
114
170
  (options.failOnResultChange === true && diff.resultChanges > 0) ||
115
171
  (gated && diff.baseErrors > 0) ||
172
+ (gated && (diff.reportErrors?.length ?? 0) > 0) ||
173
+ (gated && !options.allowRemoved && (diff.removed ?? 0) > 0) ||
116
174
  diff.rows.some((r) => r.kind === "error"));
117
175
  }
118
176
  const fmt = (n) => n.toLocaleString("en-US");
@@ -120,15 +178,16 @@ const signed = (n) => (n > 0 ? `+${fmt(n)}` : n < 0 ? `-${fmt(-n)}` : "0");
120
178
  const pct = (p) => p === undefined ? "" : p === 0 ? "0%" : `${p > 0 ? "+" : "-"}${Math.abs(p) < 0.01 ? "<0.01" : Math.abs(p).toFixed(2)}%`;
121
179
  const cell = (s) => !s || s.result === NOT_RUN ? "—" : s.result === "ok" ? fmt(s.cycles ?? 0) : `${fmt(s.cycles ?? 0)} (${s.result})`;
122
180
  function note(r, threshold) {
181
+ const unpaired = r.notCompared ? ` (NOT COMPARED: ${r.notCompared})` : "";
123
182
  switch (r.kind) {
124
183
  case "result":
125
184
  return r.base.result === NOT_RUN
126
- ? `NEW, DOES NOT ACCEPT: ${r.head.result}`
185
+ ? `NEW, DOES NOT ACCEPT: ${r.head.result}${unpaired}`
127
186
  : `RESULT CHANGED: ${r.base.result} → ${r.head.result}`;
128
187
  case "new":
129
- return "new";
188
+ return r.notCompared ? `NOT COMPARED: ${r.notCompared}` : "new";
130
189
  case "removed":
131
- return "removed";
190
+ return "REMOVED: no head group to compare with";
132
191
  case "error":
133
192
  return r.note ?? "error";
134
193
  case "base-error":
@@ -137,8 +196,12 @@ function note(r, threshold) {
137
196
  return r.overThreshold ? `over ${threshold}%` : "";
138
197
  }
139
198
  }
140
- /** One line saying what matters, for the top of a comment or terminal output. */
141
- export function summarize(diff) {
199
+ /**
200
+ * One line saying what matters, for the top of a comment or terminal output.
201
+ * Text from the reports in it (debugger versions) goes through `clean`:
202
+ * termLine by default, the markdown escape in a comment.
203
+ */
204
+ export function summarize(diff, clean = termLine) {
142
205
  const groups = diff.rows.filter((r) => r.kind !== "error" && r.kind !== "base-error");
143
206
  const changed = groups.filter((r) => r.kind !== "same").length;
144
207
  const errors = diff.rows.filter((r) => r.kind === "error").length;
@@ -153,6 +216,15 @@ export function summarize(diff) {
153
216
  `${changed} of ${groups.length} script group${groups.length === 1 ? "" : "s"} changed`,
154
217
  ...(unchecked
155
218
  ? [`${unchecked} new group${s(unchecked)} not checked against the ${diff.threshold}% threshold (no base to compare with)`]
219
+ : diff.newGroups
220
+ ? [`${diff.newGroups} new group${s(diff.newGroups)}`]
221
+ : []),
222
+ ...(diff.removed
223
+ ? [`${diff.removed} base group${s(diff.removed)} with nothing in the head to compare with (removed, renamed, moved or not built on the base)`]
224
+ : []),
225
+ ...(diff.reportErrors?.length ? [`${diff.reportErrors.length} report error${s(diff.reportErrors.length)}`] : []),
226
+ ...(diff.debuggers
227
+ ? [`the reports come from different debuggers (base ${clean(diff.debuggers.base)}, head ${clean(diff.debuggers.head)}): cycles can differ for that alone`]
156
228
  : []),
157
229
  ];
158
230
  return parts.join(", ");
@@ -181,6 +253,15 @@ const oneLine = (s) => {
181
253
  const t = String(s).replace(/[\r\n]+/g, " ").replace(INVISIBLE, "");
182
254
  return t.length > TEXT_MAX ? `${t.slice(0, TEXT_MAX - 1)}\u2026` : t;
183
255
  };
256
+ /**
257
+ * Text from a config, a build or a node (scenario, script and function names,
258
+ * warnings) for a terminal or a CI log: oneLine, and never `::` at the start of
259
+ * a line, which GitHub Actions would run as a workflow command (`::error::`,
260
+ * `::add-mask::`, `::stop-commands::`); a zero-width space breaks it.
261
+ */
262
+ export const termLine = (s) => oneLine(s).replace(/^(\s*):(?=:)/, "$1:\u200b");
263
+ /** termLine for text that keeps its line breaks (a debugger's output in an error): each line cleaned the same way. */
264
+ export const termLines = (s) => String(s).split(/\r?\n|\r/).map(termLine).join("\n");
184
265
  /**
185
266
  * Text from the PR's own files (scenario and script names, the title, error
186
267
  * messages) as inert markdown: one clipped line, no table breaks, no
@@ -244,15 +325,21 @@ export function formatMarkdown(diff, options = {}) {
244
325
  const head = "| Scenario | Group | Script | Base | Head | Δ | Δ% | |\n|---|---|---|---:|---:|---:|---:|---|";
245
326
  const line = (r) => {
246
327
  const flag = note(r, diff.threshold);
247
- const strong = r.kind === "result" || r.kind === "error" || r.kind === "base-error" || r.overThreshold;
248
- return (`| ${md(r.scenario)} | ${r.group ? code(r.group) : ""} | ${md(r.script)} | ${cell(r.base)} | ${cell(r.head)}` +
328
+ const strong = r.kind === "result" || r.kind === "error" || r.kind === "base-error" || r.kind === "removed" || r.overThreshold || !!r.notCompared;
329
+ return (`| ${md(r.scenario)} | ${r.group ? code(r.group) : ""} | ${md(r.script)} | ${md(cell(r.base))} | ${md(cell(r.head))}` +
249
330
  ` | ${r.delta === undefined ? "" : signed(r.delta)} | ${pct(r.percent)} | ${flag ? (strong ? `**${md(flag)}**` : md(flag)) : ""} |`);
250
331
  };
251
332
  const vs = options.baseLabel && options.headLabel ? ` (${code(options.baseLabel)} → ${code(options.headLabel)})` : "";
252
- const top = [COMMENT_MARKER, `### ${md(options.title ?? "Cycle report")}`, "", `${summarize(diff)}${vs}.`, ""];
333
+ const top = [COMMENT_MARKER, `### ${md(options.title ?? "Cycle report")}`, "", `${summarize(diff, md)}${vs}.`, ""];
334
+ // A report's own errors fail a gated check: they go right under the summary.
335
+ const errors = diff.reportErrors?.length
336
+ ? [`**Report errors** (nothing measured what they name):`, "", ...diff.reportErrors.slice(0, 20).map((e) => `- ${md(e)}`), ...(diff.reportErrors.length > 20 ? [`- and ${diff.reportErrors.length - 20} more`] : []), ""]
337
+ : [];
338
+ top.push(...errors);
253
339
  const footer = ["<sub>Generated by ckb-cycles (ckb-cycle-tools): each scenario replayed in ckb-debugger, one run per script group.</sub>"];
254
340
  let table = shown.length ? [head, ...shown.map(line), ""] : ["No script group changed its cycles or its result.", ""];
255
341
  let blocks = functionBlocks(shown);
342
+ let warnings = diff.warnings?.length ? warningBlock(diff.warnings) : [];
256
343
  let unchanged = same.length
257
344
  ? [
258
345
  `<details><summary>${same.length} unchanged group${same.length === 1 ? "" : "s"}</summary>`,
@@ -268,8 +355,11 @@ export function formatMarkdown(diff, options = {}) {
268
355
  // Over GitHub's limit the comment is refused, and the previous push's comment
269
356
  // would stay up with old numbers. Least useful first: the function details,
270
357
  // the unchanged groups, then the last (least important) changed rows.
271
- const size = () => [...top, ...table, ...blocks, ...unchanged, ...footer].join("\n").length;
358
+ const size = () => [...top, ...table, ...blocks, ...warnings, ...unchanged, ...footer].join("\n").length;
272
359
  const s = (n) => (n === 1 ? "" : "s");
360
+ if (size() >= COMMENT_MAX && warnings.length) {
361
+ warnings = [`<sub>${diff.warnings.length} scenario warning${s(diff.warnings.length)} left out: the comment would pass GitHub's size limit.</sub>`, ""];
362
+ }
273
363
  if (size() >= COMMENT_MAX && blocks.length) {
274
364
  blocks = ["<sub>Function details left out: the comment would pass GitHub's size limit.</sub>", ""];
275
365
  }
@@ -285,7 +375,23 @@ export function formatMarkdown(diff, options = {}) {
285
375
  const cut = rows.length - kept;
286
376
  table = [...table.slice(0, 2), ...rows.slice(0, kept), "", `<sub>${cut} more changed row${s(cut)} left out: the comment would pass GitHub's size limit.</sub>`, ""];
287
377
  }
288
- return [...top, ...table, ...blocks, ...unchanged, ...footer].join("\n");
378
+ return [...top, ...table, ...blocks, ...warnings, ...unchanged, ...footer].join("\n");
379
+ }
380
+ /** How many scenario warnings a comment lists. */
381
+ const WARNINGS_SHOWN = 50;
382
+ /** The head's scenario warnings, folded: why a number may not be the build's (a binary no cell dep matched). */
383
+ function warningBlock(warnings) {
384
+ const n = warnings.length;
385
+ const shown = warnings.slice(0, WARNINGS_SHOWN);
386
+ return [
387
+ `<details><summary>${n} scenario warning${n === 1 ? "" : "s"}</summary>`,
388
+ "",
389
+ ...shown.map((w) => `- ${md(w.scenario)}: ${md(w.text)}`),
390
+ ...(n > shown.length ? [`- and ${n - shown.length} more`] : []),
391
+ "",
392
+ "</details>",
393
+ "",
394
+ ];
289
395
  }
290
396
  /** The same table for a terminal. */
291
397
  export function formatText(diff) {
@@ -299,7 +405,7 @@ export function formatText(diff) {
299
405
  r.delta === undefined ? "" : signed(r.delta),
300
406
  pct(r.percent),
301
407
  note(r, diff.threshold),
302
- ]);
408
+ ].map(termLine));
303
409
  const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
304
410
  const right = new Set([3, 4, 5, 6]);
305
411
  const line = (cells) => cells
@@ -309,17 +415,27 @@ export function formatText(diff) {
309
415
  // Under the table, one line per group that recorded functions: the largest changes.
310
416
  const functions = [];
311
417
  for (const r of diff.rows.filter((r) => r.kind !== "same")) {
312
- const where = `${r.scenario} ${r.group}`;
418
+ const where = `${termLine(r.scenario)} ${termLine(r.group)}`;
313
419
  if (r.functionsWarning)
314
- functions.push(`functions in ${where} not recorded: ${r.functionsWarning}`);
420
+ functions.push(`functions in ${where} not recorded: ${termLine(r.functionsWarning)}`);
315
421
  else if (r.functions?.length) {
316
422
  const top = r.functions
317
423
  .slice(0, 5)
318
- .map((f) => (f.delta !== undefined ? `${f.name} ${signed(f.delta)}` : `${f.name} ${fnText(f.base)} → ${fnText(f.head)}`));
424
+ .map((f) => `${termLine(f.name)} ${f.delta !== undefined ? signed(f.delta) : `${fnText(f.base)} → ${fnText(f.head)}`}`);
319
425
  const more = r.functions.length - top.length;
320
426
  functions.push(`functions in ${where}: ${top.join(", ")}${more > 0 ? `, and ${more} more` : ""}`);
321
427
  }
322
428
  }
323
- return [summarize(diff), "", line(header), ...rows.map(line), ...(functions.length ? ["", ...functions] : [])].join("\n");
429
+ const errors = (diff.reportErrors ?? []).map((e) => `error: ${termLine(e)}`);
430
+ const warnings = (diff.warnings ?? []).map((w) => `${termLine(w.scenario)}: warning: ${termLine(w.text)}`);
431
+ return [
432
+ summarize(diff),
433
+ ...(errors.length ? ["", ...errors] : []),
434
+ "",
435
+ line(header),
436
+ ...rows.map(line),
437
+ ...(functions.length ? ["", ...functions] : []),
438
+ ...(warnings.length ? ["", ...warnings] : []),
439
+ ].join("\n");
324
440
  }
325
441
  const fnText = (n) => (n === undefined ? "?" : fmt(n));
package/dist/elf.d.ts ADDED
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Function names from an ELF symbol table, for the frames ckb-debugger's
3
+ * profiler cannot name. The profiler names a frame from the DWARF line table;
4
+ * code without line info (the `_start` that ckb-std writes in assembly, the
5
+ * allocator shims rustc generates) comes out as `func_0x<address>`. The symbol
6
+ * table of the same unstripped build still has those names. Without them, a
7
+ * function that moved between two builds shows in a diff as one address gone
8
+ * and another new. Plain TypeScript with no Node built-ins, like flame.ts.
9
+ */
10
+ /** Start address → name (demangled when it can be), of every function symbol in `.symtab`. */
11
+ export declare function elfFunctionNames(elf: Uint8Array): Map<bigint, string>;
12
+ /**
13
+ * A Rust symbol name as `crate::module::function`, for the plain paths a
14
+ * symbol table mostly holds: legacy (`_ZN…E`, hash dropped) and v0 (`_R…`).
15
+ * Anything it does not follow (generics, trait impls) comes back unchanged:
16
+ * still a stable name, only a less readable one.
17
+ */
18
+ export declare function demangle(name: string): string;
package/dist/elf.js ADDED
@@ -0,0 +1,209 @@
1
+ /**
2
+ * Function names from an ELF symbol table, for the frames ckb-debugger's
3
+ * profiler cannot name. The profiler names a frame from the DWARF line table;
4
+ * code without line info (the `_start` that ckb-std writes in assembly, the
5
+ * allocator shims rustc generates) comes out as `func_0x<address>`. The symbol
6
+ * table of the same unstripped build still has those names. Without them, a
7
+ * function that moved between two builds shows in a diff as one address gone
8
+ * and another new. Plain TypeScript with no Node built-ins, like flame.ts.
9
+ */
10
+ /** `__text_start`, `__init_array_end`, `_etext`, `_stext`, `end` and the like: labels, not functions. */
11
+ const LINKER_MARKER = /^(__\w*_(start|end)|_?_?(etext|edata|end|stext|ftext)|__executable_start|__ehdr_start|__global_pointer\$)$/;
12
+ /** Start address → name (demangled when it can be), of every function symbol in `.symtab`. */
13
+ export function elfFunctionNames(elf) {
14
+ const names = new Map();
15
+ // ELF64 little-endian only: what a CKB script is (RISC-V 64).
16
+ if (elf.length < 64 || elf[0] !== 0x7f || elf[1] !== 0x45 || elf[2] !== 0x4c || elf[3] !== 0x46)
17
+ return names;
18
+ if (elf[4] !== 2 || elf[5] !== 1)
19
+ return names;
20
+ const view = new DataView(elf.buffer, elf.byteOffset, elf.byteLength);
21
+ const u16 = (o) => view.getUint16(o, true);
22
+ const u32 = (o) => view.getUint32(o, true);
23
+ const u64 = (o) => view.getBigUint64(o, true);
24
+ const inside = (o, n) => o >= 0 && n >= 0 && o + n <= elf.length;
25
+ const shoff = Number(u64(0x28));
26
+ const shentsize = u16(0x3a);
27
+ const shnum = u16(0x3c);
28
+ if (shentsize < 64 || !inside(shoff, shentsize * shnum))
29
+ return names;
30
+ const section = (i) => {
31
+ const o = shoff + i * shentsize;
32
+ return { type: u32(o + 4), flags: u64(o + 8), offset: Number(u64(o + 0x18)), size: Number(u64(o + 0x20)), link: u32(o + 0x28), entsize: Number(u64(o + 0x38)) };
33
+ };
34
+ const SHT_SYMTAB = 2;
35
+ const SHF_EXECINSTR = 0x4n;
36
+ // SHN_LORESERVE and up: SHN_ABS, SHN_COMMON, SHN_XINDEX. Not an address in code.
37
+ const SHN_LORESERVE = 0xff00;
38
+ const inCode = (shndx) => shndx < shnum && (section(shndx).flags & SHF_EXECINSTR) !== 0n;
39
+ for (let i = 0; i < shnum; i++) {
40
+ const symtab = section(i);
41
+ if (symtab.type !== SHT_SYMTAB || symtab.entsize < 24 || !inside(symtab.offset, symtab.size))
42
+ continue;
43
+ if (symtab.link >= shnum)
44
+ continue;
45
+ const strtab = section(symtab.link);
46
+ if (!inside(strtab.offset, strtab.size))
47
+ continue;
48
+ const decoder = new TextDecoder();
49
+ for (let o = symtab.offset; o + symtab.entsize <= symtab.offset + symtab.size; o += symtab.entsize) {
50
+ const nameOff = u32(o);
51
+ const info = elf[o + 4];
52
+ const shndx = u16(o + 6);
53
+ const value = u64(o + 8);
54
+ const type = info & 0xf;
55
+ // STT_FUNC, or STT_NOTYPE for a global label in assembly (`_start`) in an
56
+ // executable section, defined in a real section (not SHN_UNDEF or SHN_ABS).
57
+ if (!(type === 2 || (type === 0 && info >> 4 !== 0)) || shndx === 0 || shndx >= SHN_LORESERVE || nameOff === 0 || nameOff >= strtab.size)
58
+ continue;
59
+ if (type === 0 && !inCode(shndx))
60
+ continue;
61
+ let end = strtab.offset + nameOff;
62
+ while (end < strtab.offset + strtab.size && elf[end] !== 0)
63
+ end++;
64
+ const raw = decoder.decode(elf.subarray(strtab.offset + nameOff, end));
65
+ if (!raw || raw.startsWith("$") || raw.startsWith(".L"))
66
+ continue;
67
+ // Section bounds the linker or a linker script defines; one can sit at `_start`'s address.
68
+ if (type === 0 && LINKER_MARKER.test(raw))
69
+ continue;
70
+ // A function and a label at the same address: the function's name wins.
71
+ if (type === 2 || !names.has(value))
72
+ names.set(value, demangle(raw));
73
+ }
74
+ }
75
+ return names;
76
+ }
77
+ /**
78
+ * A Rust symbol name as `crate::module::function`, for the plain paths a
79
+ * symbol table mostly holds: legacy (`_ZN…E`, hash dropped) and v0 (`_R…`).
80
+ * Anything it does not follow (generics, trait impls) comes back unchanged:
81
+ * still a stable name, only a less readable one.
82
+ */
83
+ export function demangle(name) {
84
+ if (name.startsWith("_ZN"))
85
+ return demangleLegacy(name) ?? name;
86
+ if (name.startsWith("_R"))
87
+ return demangleV0(name) ?? name;
88
+ return name;
89
+ }
90
+ function demangleLegacy(name) {
91
+ const parts = [];
92
+ let i = 3;
93
+ while (i < name.length && name[i] !== "E") {
94
+ const m = /^\d+/.exec(name.slice(i));
95
+ if (!m)
96
+ return undefined;
97
+ const len = Number(m[0]);
98
+ i += m[0].length;
99
+ if (i + len > name.length)
100
+ return undefined;
101
+ parts.push(name.slice(i, i + len));
102
+ i += len;
103
+ }
104
+ if (name[i] !== "E" || !parts.length)
105
+ return undefined;
106
+ if (parts.length > 1 && /^h[0-9a-f]{16}$/.test(parts[parts.length - 1]))
107
+ parts.pop();
108
+ const out = [];
109
+ for (const p of parts) {
110
+ const s = unescapeLegacy(p);
111
+ if (s === undefined)
112
+ return undefined;
113
+ out.push(s);
114
+ }
115
+ return out.join("::");
116
+ }
117
+ const LEGACY_ESCAPES = { SP: "@", BP: "*", RF: "&", LT: "<", GT: ">", LP: "(", RP: ")", C: "," };
118
+ /** One legacy path element: `$RF$`, `$u7b$` and the rest decoded, `..` as `::`. Undefined on an escape it does not know. */
119
+ function unescapeLegacy(part) {
120
+ // An element that would start with `$` is written `_$`.
121
+ let s = part.startsWith("_$") ? part.slice(1) : part;
122
+ let out = "";
123
+ while (s) {
124
+ if (s.startsWith("..")) {
125
+ out += "::";
126
+ s = s.slice(2);
127
+ }
128
+ else if (s[0] === "$") {
129
+ const end = s.indexOf("$", 1);
130
+ if (end < 0)
131
+ return undefined;
132
+ const esc = s.slice(1, end);
133
+ const code = /^u[0-9a-f]{1,6}$/.test(esc) ? parseInt(esc.slice(1), 16) : -1;
134
+ const ch = LEGACY_ESCAPES[esc] ?? (code >= 0 && code <= 0x10ffff ? String.fromCodePoint(code) : undefined);
135
+ if (ch === undefined)
136
+ return undefined;
137
+ out += ch;
138
+ s = s.slice(end + 1);
139
+ }
140
+ else {
141
+ const m = /^[^$.]+|^\./.exec(s);
142
+ out += m[0];
143
+ s = s.slice(m[0].length);
144
+ }
145
+ }
146
+ return out;
147
+ }
148
+ function demangleV0(name) {
149
+ let i = 2;
150
+ const peek = () => name[i];
151
+ // `s<base62>_`: a disambiguator, not part of the name.
152
+ const skipDisambiguator = () => {
153
+ if (peek() !== "s")
154
+ return true;
155
+ const end = name.indexOf("_", i);
156
+ if (end < 0)
157
+ return false;
158
+ i = end + 1;
159
+ return true;
160
+ };
161
+ const ident = () => {
162
+ if (!skipDisambiguator())
163
+ return undefined;
164
+ if (peek() === "u")
165
+ return undefined; // punycode: leave it to a real demangler
166
+ const m = /^\d+/.exec(name.slice(i));
167
+ if (!m)
168
+ return undefined;
169
+ const len = Number(m[0]);
170
+ i += m[0].length;
171
+ if (peek() === "_")
172
+ i++;
173
+ if (i + len > name.length)
174
+ return undefined;
175
+ const s = name.slice(i, i + len);
176
+ i += len;
177
+ return s;
178
+ };
179
+ const path = (depth) => {
180
+ if (depth > 64)
181
+ return undefined;
182
+ const tag = name[i++];
183
+ if (tag === "C")
184
+ return ident();
185
+ if (tag === "N") {
186
+ const ns = name[i++];
187
+ const parent = path(depth + 1);
188
+ if (parent === undefined)
189
+ return undefined;
190
+ const id = ident();
191
+ if (id === undefined)
192
+ return undefined;
193
+ if (ns === "C")
194
+ return `${parent}::{closure}`;
195
+ if (ns >= "A" && ns <= "Z")
196
+ return `${parent}::{${id || "shim"}}`;
197
+ return `${parent}::${id}`;
198
+ }
199
+ return undefined;
200
+ };
201
+ if (/^\d/.test(name.slice(i)))
202
+ return undefined; // an encoding version this does not know
203
+ const p = path(0);
204
+ if (p === undefined)
205
+ return undefined;
206
+ // What may follow the path: an instantiating crate, or a suffix LLVM added.
207
+ const rest = name.slice(i);
208
+ return rest === "" || rest.startsWith("C") || rest.startsWith(".") ? p : undefined;
209
+ }
package/dist/flame.d.ts CHANGED
@@ -25,6 +25,12 @@ export declare function splitStack(stack: string): string[];
25
25
  export declare const MAX_DEPTH = 256;
26
26
  /** Parses ckb-debugger's folded output: identical stacks merged, frames named by function only. */
27
27
  export declare function parseFolded(text: string): Folded;
28
+ /**
29
+ * Renames each `func_0x<address>` frame (code the profiler found no line info
30
+ * for) to the function starting at that address in `names` (elf.ts), merging
31
+ * stacks that become the same. Frames it has no name for keep their address.
32
+ */
33
+ export declare function nameAddresses(f: Folded, names: Map<bigint, string>): Folded;
28
34
  export declare const foldedTotal: (f: Folded) => bigint;
29
35
  /** Back to text, one merged stack per line, heaviest first: the format speedscope and inferno read. */
30
36
  export declare function formatFolded(f: Folded): string;
package/dist/flame.js CHANGED
@@ -62,6 +62,26 @@ export function parseFolded(text) {
62
62
  }
63
63
  return folded;
64
64
  }
65
+ /**
66
+ * Renames each `func_0x<address>` frame (code the profiler found no line info
67
+ * for) to the function starting at that address in `names` (elf.ts), merging
68
+ * stacks that become the same. Frames it has no name for keep their address.
69
+ */
70
+ export function nameAddresses(f, names) {
71
+ if (!names.size)
72
+ return f;
73
+ const out = new Map();
74
+ for (const [stack, v] of f) {
75
+ const renamed = splitStack(stack)
76
+ .map((frame) => {
77
+ const m = /^func_0x([0-9a-fA-F]+)$/.exec(frame);
78
+ return (m && names.get(BigInt(`0x${m[1]}`))) || frame;
79
+ })
80
+ .join(";");
81
+ out.set(renamed, (out.get(renamed) ?? 0n) + v);
82
+ }
83
+ return out;
84
+ }
65
85
  export const foldedTotal = (f) => [...f.values()].reduce((s, v) => s + v, 0n);
66
86
  /** Back to text, one merged stack per line, heaviest first: the format speedscope and inferno read. */
67
87
  export function formatFolded(f) {
package/dist/index.d.ts CHANGED
@@ -4,7 +4,7 @@ export { analyzeTransaction, groupScripts, knownScriptNames, TransactionNotFound
4
4
  export type { ScriptGroup, TxAnalysis } from "./analyze.js";
5
5
  export { buildMockTransaction, httpRpc, isCellbase, mockFromTransaction, nodeConsensus, parseOutPointVec, scriptVersionAt, } from "./mock.js";
6
6
  export type { HttpRpcOptions, MockTransaction, NodeConsensus, Rpc, RpcOutPoint, RpcTransaction, VmEpochs } from "./mock.js";
7
- export { checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
7
+ export { checkMockTransaction, checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
8
8
  export type { DebuggerOutput, GroupRun, Profile, ProfiledGroup, ReplayOptions, ReplayPlan, RunDebugger } from "./replay.js";
9
9
  export { flameTransaction, profileTransaction, runNativeDebugger } from "./profile.js";
10
10
  export type { FlameGroup, ProfileOptions } from "./profile.js";
@@ -18,3 +18,5 @@ export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FU
18
18
  export type { CycleDiff, CycleReport, DiffOptions, DiffRow, FunctionDelta, FunctionResult, GroupResult, MarkdownOptions, ScenarioResult } from "./diff.js";
19
19
  export { formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
20
20
  export type { BinaryConfig, CyclesConfig, ReportOptions, ScenarioConfig } from "./report.js";
21
+ export { configFromMocks, formatScan, scanTestMocks } from "./scan.js";
22
+ export type { ScanOptions, ScanResult, ScannedBinary, ScannedMock } from "./scan.js";
package/dist/index.js CHANGED
@@ -1,10 +1,11 @@
1
1
  export { checkDebuggerPath, DebuggerNotFoundError, resolveDebugger } from "./debugger.js";
2
2
  export { analyzeTransaction, groupScripts, knownScriptNames, TransactionNotFoundError } from "./analyze.js";
3
3
  export { buildMockTransaction, httpRpc, isCellbase, mockFromTransaction, nodeConsensus, parseOutPointVec, scriptVersionAt, } from "./mock.js";
4
- export { checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
4
+ export { checkMockTransaction, checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
5
5
  export { flameTransaction, profileTransaction, runNativeDebugger } from "./profile.js";
6
6
  export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, renderFlameSvg, splitStack, } from "./flame.js";
7
7
  export { runWasmDebugger, wasmDebuggerVersion, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
8
8
  export { substituteBinaries } from "./substitute.js";
9
9
  export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, resultLabel, summarize, } from "./diff.js";
10
10
  export { formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
11
+ export { configFromMocks, formatScan, scanTestMocks } from "./scan.js";
package/dist/profile.d.ts CHANGED
@@ -55,12 +55,16 @@ export interface FlameGroup {
55
55
  * code hash to an unstripped build of that script, used instead of the
56
56
  * deployed (stripped) binary so the frames have names; each such group is also
57
57
  * run with the deployed binary, to check the build behaves the same.
58
- * `scripts` limits the run to those selectors (`input.0.lock`, …).
58
+ * `scripts` limits the run to those selectors (`input.0.lock`, …). `readFile`
59
+ * reads the folded stacks the debugger wrote, and `readBinary` (node:fs when
60
+ * not given) the builds, for their symbol tables: both see the files where
61
+ * `runDebugger` does.
59
62
  */
60
63
  export declare function flameTransaction(target: string | RpcTransaction | MockTransaction, options: ProfileOptions & {
61
64
  bins?: Record<string, string>;
62
65
  scripts?: string[];
63
66
  readFile: (path: string) => Promise<string>;
67
+ readBinary?: (path: string) => Promise<Uint8Array>;
64
68
  }): Promise<{
65
69
  plan: ReplayPlan;
66
70
  groups: FlameGroup[];