ckb-cycle-tools 0.0.0-stage → 1.0.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 ADDED
@@ -0,0 +1,325 @@
1
+ /**
2
+ * Compares two cycle reports — the base of a pull request and its head — group
3
+ * by group, and formats the result for a terminal or a PR comment.
4
+ *
5
+ * Pure: no network, no file system.
6
+ */
7
+ /** How many functions a report keeps per group. */
8
+ export const FUNCTION_LIMIT = 15;
9
+ /** The base side of a new group that does not accept: compared with "did not run". */
10
+ const NOT_RUN = "not run";
11
+ /** `ok`, `exit 12`, or `error` (the VM stopped the script). */
12
+ export function resultLabel(g) {
13
+ return g.error ? "error" : g.result === 0 ? "ok" : `exit ${g.result}`;
14
+ }
15
+ export function diffReports(base, head, options = {}) {
16
+ const threshold = options.failAbove;
17
+ const rows = [];
18
+ const baseByName = new Map(base.scenarios.map((s) => [s.name, s]));
19
+ const headNames = new Set(head.scenarios.map((s) => s.name));
20
+ const scenarioRows = (h, b) => {
21
+ const name = (h ?? b).name;
22
+ if (h?.error) {
23
+ rows.push({ scenario: name, group: "", script: "", kind: "error", overThreshold: false, note: `head: ${h.error}` });
24
+ return;
25
+ }
26
+ // 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.
29
+ if (h && b?.error && !b.binaryMissing) {
30
+ rows.push({ scenario: name, group: "", script: "", kind: "base-error", overThreshold: false, note: `base: ${b.error}` });
31
+ }
32
+ const baseGroups = new Map((b && !b.error ? b.groups : []).map((g) => [g.selector, g]));
33
+ for (const g of h?.groups ?? []) {
34
+ rows.push(groupRow(name, baseGroups.get(g.selector), g, threshold));
35
+ baseGroups.delete(g.selector);
36
+ }
37
+ for (const g of baseGroups.values())
38
+ rows.push(groupRow(name, g, undefined, threshold));
39
+ };
40
+ for (const h of head.scenarios)
41
+ scenarioRows(h, baseByName.get(h.name));
42
+ for (const b of base.scenarios)
43
+ if (!headNames.has(b.name))
44
+ scenarioRows(undefined, b);
45
+ return {
46
+ rows,
47
+ resultChanges: rows.filter((r) => r.kind === "result").length,
48
+ overThreshold: rows.filter((r) => r.overThreshold).length,
49
+ baseErrors: rows.filter((r) => r.kind === "base-error").length,
50
+ ...(threshold !== undefined && { threshold }),
51
+ };
52
+ }
53
+ function groupRow(scenario, b, h, threshold) {
54
+ const side = (g) => ({ result: resultLabel(g), cycles: g.cycles });
55
+ const row = {
56
+ scenario,
57
+ group: (h ?? b).selector,
58
+ script: (h ?? b).script,
59
+ ...(b && { base: side(b) }),
60
+ ...(h && { head: side(h) }),
61
+ kind: !b ? "new" : !h ? "removed" : "same",
62
+ overThreshold: false,
63
+ };
64
+ if (b && h) {
65
+ 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);
71
+ }
72
+ else if (h && resultLabel(h) !== "ok") {
73
+ // A new group that does not accept: against "did not run", its result changed.
74
+ row.kind = "result";
75
+ row.base = { result: NOT_RUN };
76
+ }
77
+ if (h?.functions)
78
+ row.functions = functionDeltas(b?.functions, h.functions);
79
+ if (h?.functionsWarning)
80
+ row.functionsWarning = h.functionsWarning;
81
+ return row;
82
+ }
83
+ /**
84
+ * The functions whose self cycles differ between two lists, largest change
85
+ * first. One whose other side is not known (see FunctionDelta) is kept, ranked
86
+ * by the side that is.
87
+ */
88
+ export function functionDeltas(base, head) {
89
+ const side = (list, name) => {
90
+ if (!list)
91
+ return undefined;
92
+ const f = list.find((f) => f.name === name);
93
+ return f ? f.self : list.length < FUNCTION_LIMIT ? 0 : undefined;
94
+ };
95
+ const names = [...new Set([...head.map((f) => f.name), ...(base ?? []).map((f) => f.name)])];
96
+ const size = (d) => Math.abs(d.delta ?? d.head ?? d.base ?? 0);
97
+ return names
98
+ .map((name) => {
99
+ const b = side(base, name);
100
+ const h = side(head, name);
101
+ return { name, ...(b !== undefined && { base: b }), ...(h !== undefined && { head: h }), ...(b !== undefined && h !== undefined && { delta: h - b }) };
102
+ })
103
+ .filter((d) => d.delta !== 0)
104
+ .sort((x, y) => size(y) - size(x) || (x.name < y.name ? -1 : x.name > y.name ? 1 : 0));
105
+ }
106
+ /**
107
+ * 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.
110
+ */
111
+ export function diffFailed(diff, options = {}) {
112
+ const gated = options.failAbove !== undefined || options.failOnResultChange === true;
113
+ return ((options.failAbove !== undefined && diff.overThreshold > 0) ||
114
+ (options.failOnResultChange === true && diff.resultChanges > 0) ||
115
+ (gated && diff.baseErrors > 0) ||
116
+ diff.rows.some((r) => r.kind === "error"));
117
+ }
118
+ const fmt = (n) => n.toLocaleString("en-US");
119
+ const signed = (n) => (n > 0 ? `+${fmt(n)}` : n < 0 ? `-${fmt(-n)}` : "0");
120
+ const pct = (p) => p === undefined ? "" : p === 0 ? "0%" : `${p > 0 ? "+" : "-"}${Math.abs(p) < 0.01 ? "<0.01" : Math.abs(p).toFixed(2)}%`;
121
+ const cell = (s) => !s || s.result === NOT_RUN ? "—" : s.result === "ok" ? fmt(s.cycles ?? 0) : `${fmt(s.cycles ?? 0)} (${s.result})`;
122
+ function note(r, threshold) {
123
+ switch (r.kind) {
124
+ case "result":
125
+ return r.base.result === NOT_RUN
126
+ ? `NEW, DOES NOT ACCEPT: ${r.head.result}`
127
+ : `RESULT CHANGED: ${r.base.result} → ${r.head.result}`;
128
+ case "new":
129
+ return "new";
130
+ case "removed":
131
+ return "removed";
132
+ case "error":
133
+ return r.note ?? "error";
134
+ case "base-error":
135
+ return `NOT COMPARED: ${r.note ?? "base: error"}`;
136
+ default:
137
+ return r.overThreshold ? `over ${threshold}%` : "";
138
+ }
139
+ }
140
+ /** One line saying what matters, for the top of a comment or terminal output. */
141
+ export function summarize(diff) {
142
+ const groups = diff.rows.filter((r) => r.kind !== "error" && r.kind !== "base-error");
143
+ const changed = groups.filter((r) => r.kind !== "same").length;
144
+ const errors = diff.rows.filter((r) => r.kind === "error").length;
145
+ // A new group has no base, so no percentage: the threshold cannot apply to it.
146
+ const unchecked = diff.threshold === undefined ? 0 : groups.filter((r) => !r.base || r.base.result === NOT_RUN).length;
147
+ const s = (n) => (n > 1 ? "s" : "");
148
+ const parts = [
149
+ ...(diff.resultChanges ? [`${diff.resultChanges} result change${s(diff.resultChanges)}`] : []),
150
+ ...(diff.overThreshold ? [`${diff.overThreshold} over the ${diff.threshold}% threshold`] : []),
151
+ ...(errors ? [`${errors} scenario${s(errors)} failed to run`] : []),
152
+ ...(diff.baseErrors ? [`${diff.baseErrors} scenario${s(diff.baseErrors)} could not run on the base`] : []),
153
+ `${changed} of ${groups.length} script group${groups.length === 1 ? "" : "s"} changed`,
154
+ ...(unchecked
155
+ ? [`${unchecked} new group${s(unchecked)} not checked against the ${diff.threshold}% threshold (no base to compare with)`]
156
+ : []),
157
+ ];
158
+ return parts.join(", ");
159
+ }
160
+ const MD_ESCAPE = /[|\\`*_<>[\]~&!]/g;
161
+ /**
162
+ * Characters that never belong in a name: C0/C1 controls, and the bidi overrides
163
+ * and isolates that make a name read differently from what it is (review, 27 Oct).
164
+ */
165
+ const INVISIBLE = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g;
166
+ /**
167
+ * Applied after escaping. GitHub links @mentions and #refs after rendering, where a
168
+ * backslash is gone, and turns a bare `https://\u2026` or `www.\u2026` into a link: a
169
+ * zero-width space stops each of them.
170
+ */
171
+ const unlink = (s) => s
172
+ .replace(/([@#])(?=\w)/g, "$1\u200b")
173
+ .replace(/:\/\//g, ":\u200b//")
174
+ .replace(/\b(www)\./gi, "$1\u200b.");
175
+ /**
176
+ * The longest scenario name, script name or note a comment shows: one long
177
+ * name repeated on every row would pass GitHub's size limit on its own.
178
+ */
179
+ const TEXT_MAX = 300;
180
+ const oneLine = (s) => {
181
+ const t = String(s).replace(/[\r\n]+/g, " ").replace(INVISIBLE, "");
182
+ return t.length > TEXT_MAX ? `${t.slice(0, TEXT_MAX - 1)}\u2026` : t;
183
+ };
184
+ /**
185
+ * Text from the PR's own files (scenario and script names, the title, error
186
+ * messages) as inert markdown: one clipped line, no table breaks, no
187
+ * formatting, no mentions, no links.
188
+ */
189
+ const md = (s) => unlink(oneLine(s).replace(MD_ESCAPE, (c) => `\\${c}`));
190
+ /** Text for inside an HTML tag (a `<summary>`, which GitHub does not read as markdown). */
191
+ const html = (s) => unlink(oneLine(s)
192
+ .replace(/&/g, "&amp;")
193
+ .replace(/</g, "&lt;")
194
+ .replace(/>/g, "&gt;"));
195
+ /**
196
+ * A code span. A selector or a commit label is plain (`input.0.lock`); anything
197
+ * else (a hand-made report) goes in `<code>`, escaped like any text, where a
198
+ * backtick cannot end it early.
199
+ */
200
+ const code = (s) => (/^[\w.:-]+$/.test(s) ? `\`${s}\`` : `<code>${md(s)}</code>`);
201
+ /** How many changed functions a comment lists per group. */
202
+ export const FUNCTIONS_SHOWN = 10;
203
+ /** The longest function name a comment shows; Rust generics can run to kilobytes. */
204
+ const NAME_MAX = 120;
205
+ const clipName = (name) => (name.length > NAME_MAX ? `${name.slice(0, NAME_MAX - 1)}…` : name);
206
+ /**
207
+ * GitHub refuses a comment over 65,536 characters, and the Action would then
208
+ * leave the previous push's comment in place (review, 27 Oct). Function blocks
209
+ * are dropped first when the comment would not fit.
210
+ */
211
+ const COMMENT_MAX = 60_000;
212
+ /** A folded block per group that recorded functions: which of them changed, or why none were recorded. */
213
+ function functionBlocks(rows) {
214
+ const out = [];
215
+ for (const r of rows) {
216
+ const where = `${html(r.scenario)} · <code>${html(r.group)}</code> (${html(r.script)})`;
217
+ if (r.functionsWarning) {
218
+ out.push(`<details><summary>Functions in ${where}: not recorded</summary>`, "", md(r.functionsWarning), "", "</details>", "");
219
+ continue;
220
+ }
221
+ if (!r.functions?.length)
222
+ continue;
223
+ const shown = r.functions.slice(0, FUNCTIONS_SHOWN);
224
+ const more = r.functions.length - shown.length;
225
+ const n = r.functions.length;
226
+ out.push(`<details><summary>Functions in ${where}: ${n} function${n === 1 ? "" : "s"} changed</summary>`, "", "| Function | Base self | Head self | Δ |", "|---|---:|---:|---:|", ...shown.map((f) => `| ${md(clipName(f.name))} | ${fnCell(f.base)} | ${fnCell(f.head)} | ${f.delta === undefined ? "" : signed(f.delta)} |`), "", ...(more > 0 ? [`and ${more} more.`, ""] : []), `<sub>Self cycles, from ckb-debugger's profiler with the symbols build; — means not among the ${FUNCTION_LIMIT} costliest (or not recorded).</sub>`, "", "</details>", "");
227
+ }
228
+ return out;
229
+ }
230
+ const fnCell = (n) => (n === undefined ? "—" : fmt(n));
231
+ /** The hidden marker that identifies the sticky comment, so it is updated instead of duplicated. */
232
+ export const COMMENT_MARKER = "<!-- ckb-cycles-report -->";
233
+ /**
234
+ * A markdown comment: what changed in a table, unchanged groups folded away.
235
+ * Result changes come first, since an accept turning into a reject (or the
236
+ * reverse) matters more than any cycle count.
237
+ */
238
+ export function formatMarkdown(diff, options = {}) {
239
+ const order = { error: 0, "base-error": 0.5, result: 1, changed: 2, new: 3, removed: 4, same: 5 };
240
+ const rank = (r) => order[r.kind] - (r.overThreshold ? 0.5 : 0);
241
+ const rows = [...diff.rows].sort((a, b) => rank(a) - rank(b));
242
+ const shown = rows.filter((r) => r.kind !== "same");
243
+ const same = rows.filter((r) => r.kind === "same");
244
+ const head = "| Scenario | Group | Script | Base | Head | Δ | Δ% | |\n|---|---|---|---:|---:|---:|---:|---|";
245
+ const line = (r) => {
246
+ 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)}` +
249
+ ` | ${r.delta === undefined ? "" : signed(r.delta)} | ${pct(r.percent)} | ${flag ? (strong ? `**${md(flag)}**` : md(flag)) : ""} |`);
250
+ };
251
+ 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}.`, ""];
253
+ const footer = ["<sub>Generated by ckb-cycles (ckb-cycle-tools): each scenario replayed in ckb-debugger, one run per script group.</sub>"];
254
+ let table = shown.length ? [head, ...shown.map(line), ""] : ["No script group changed its cycles or its result.", ""];
255
+ let blocks = functionBlocks(shown);
256
+ let unchanged = same.length
257
+ ? [
258
+ `<details><summary>${same.length} unchanged group${same.length === 1 ? "" : "s"}</summary>`,
259
+ "",
260
+ "| Scenario | Group | Script | Cycles | Result |",
261
+ "|---|---|---|---:|---|",
262
+ ...same.map((r) => `| ${md(r.scenario)} | ${code(r.group)} | ${md(r.script)} | ${fmt(r.head.cycles ?? 0)} | ${md(r.head.result)} |`),
263
+ "",
264
+ "</details>",
265
+ "",
266
+ ]
267
+ : [];
268
+ // Over GitHub's limit the comment is refused, and the previous push's comment
269
+ // would stay up with old numbers. Least useful first: the function details,
270
+ // the unchanged groups, then the last (least important) changed rows.
271
+ const size = () => [...top, ...table, ...blocks, ...unchanged, ...footer].join("\n").length;
272
+ const s = (n) => (n === 1 ? "" : "s");
273
+ if (size() >= COMMENT_MAX && blocks.length) {
274
+ blocks = ["<sub>Function details left out: the comment would pass GitHub's size limit.</sub>", ""];
275
+ }
276
+ if (size() >= COMMENT_MAX && same.length) {
277
+ unchanged = [`<sub>${same.length} unchanged group${s(same.length)} left out: the comment would pass GitHub's size limit.</sub>`, ""];
278
+ }
279
+ if (size() >= COMMENT_MAX && shown.length) {
280
+ const rows = table.slice(2, -1);
281
+ const room = COMMENT_MAX - size() + rows.join("\n").length - 200;
282
+ let kept = 0;
283
+ for (let used = 0; kept < rows.length && used + rows[kept].length + 1 < room; kept++)
284
+ used += rows[kept].length + 1;
285
+ const cut = rows.length - kept;
286
+ 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
+ }
288
+ return [...top, ...table, ...blocks, ...unchanged, ...footer].join("\n");
289
+ }
290
+ /** The same table for a terminal. */
291
+ export function formatText(diff) {
292
+ const header = ["SCENARIO", "GROUP", "SCRIPT", "BASE", "HEAD", "Δ", "Δ%", ""];
293
+ const rows = diff.rows.map((r) => [
294
+ r.scenario,
295
+ r.group,
296
+ r.script,
297
+ cell(r.base),
298
+ cell(r.head),
299
+ r.delta === undefined ? "" : signed(r.delta),
300
+ pct(r.percent),
301
+ note(r, diff.threshold),
302
+ ]);
303
+ const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
304
+ const right = new Set([3, 4, 5, 6]);
305
+ const line = (cells) => cells
306
+ .map((c, i) => (right.has(i) ? c.padStart(widths[i]) : c.padEnd(widths[i])))
307
+ .join(" ")
308
+ .trimEnd();
309
+ // Under the table, one line per group that recorded functions: the largest changes.
310
+ const functions = [];
311
+ for (const r of diff.rows.filter((r) => r.kind !== "same")) {
312
+ const where = `${r.scenario} ${r.group}`;
313
+ if (r.functionsWarning)
314
+ functions.push(`functions in ${where} not recorded: ${r.functionsWarning}`);
315
+ else if (r.functions?.length) {
316
+ const top = r.functions
317
+ .slice(0, 5)
318
+ .map((f) => (f.delta !== undefined ? `${f.name} ${signed(f.delta)}` : `${f.name} ${fnText(f.base)} → ${fnText(f.head)}`));
319
+ const more = r.functions.length - top.length;
320
+ functions.push(`functions in ${where}: ${top.join(", ")}${more > 0 ? `, and ${more} more` : ""}`);
321
+ }
322
+ }
323
+ return [summarize(diff), "", line(header), ...rows.map(line), ...(functions.length ? ["", ...functions] : [])].join("\n");
324
+ }
325
+ const fnText = (n) => (n === undefined ? "?" : fmt(n));
@@ -0,0 +1,59 @@
1
+ /**
2
+ * Flamegraphs of where a script's cycles go, from ckb-debugger's own profiler
3
+ * (`--enable-flamegraph --flamegraph-output`). ckb-debugger writes folded
4
+ * stacks, one `frame;frame;… cycles` line per sample, with the same stack on
5
+ * many lines and every frame as `<source path>:<function>`. Here they are
6
+ * merged, the paths dropped, and drawn as an SVG. Plain TypeScript with no Node
7
+ * built-ins, like replay.ts, so the browser can draw the same thing.
8
+ *
9
+ * A deployed binary is usually stripped: its whole run is one frame. Pass an
10
+ * unstripped build of the same code (`ckb-debugger --bin`) to see functions.
11
+ */
12
+ /** Stack (frames joined by `;`, outermost first) → cycles. */
13
+ export type Folded = Map<string, bigint>;
14
+ /**
15
+ * `E:\…\src\main.rs:session_lock::lock_hash` → `session_lock::lock_hash`. The
16
+ * path ends at the first `.<ext>:`; `??:func_0x114e4` (no symbols) keeps its address.
17
+ */
18
+ export declare function frameName(frame: string): string;
19
+ /**
20
+ * Splits a folded stack into frames. `;` separates frames, but Rust names hold
21
+ * it too (`[u8; 32]`), so a `;` inside brackets belongs to the name.
22
+ */
23
+ export declare function splitStack(stack: string): string[];
24
+ /** The deepest stack kept; deeper frames are folded into one. */
25
+ export declare const MAX_DEPTH = 256;
26
+ /** Parses ckb-debugger's folded output: identical stacks merged, frames named by function only. */
27
+ export declare function parseFolded(text: string): Folded;
28
+ export declare const foldedTotal: (f: Folded) => bigint;
29
+ /** Back to text, one merged stack per line, heaviest first: the format speedscope and inferno read. */
30
+ export declare function formatFolded(f: Folded): string;
31
+ export interface FunctionCost {
32
+ name: string;
33
+ /** Cycles spent in the function itself. */
34
+ self: bigint;
35
+ /** Cycles spent in it and everything it called (counted once per stack, so recursion is not doubled). */
36
+ total: bigint;
37
+ }
38
+ /** Every function with its self and total cycles, heaviest self first. */
39
+ export declare function functionCosts(f: Folded): FunctionCost[];
40
+ export interface FlameNode {
41
+ name: string;
42
+ value: bigint;
43
+ children: FlameNode[];
44
+ }
45
+ /** The call tree: each node's value is the cycles of every stack through it. Children heaviest first. */
46
+ export declare function flameTree(f: Folded, rootName?: string): FlameNode;
47
+ /**
48
+ * A self-contained SVG flamegraph: root at the bottom, width proportional to
49
+ * cycles, a tooltip (`<title>`) with the cycles and share on every frame.
50
+ * Frames narrower than `minWidth` pixels are left out. Colours are fixed per
51
+ * function name, so the same function looks the same in two graphs.
52
+ */
53
+ export declare function renderFlameSvg(tree: FlameNode, opts?: {
54
+ title?: string;
55
+ width?: number;
56
+ minWidth?: number;
57
+ }): string;
58
+ /** The `All cycles: N` line ckb-debugger prints in flamegraph mode: what the profile covers. */
59
+ export declare function profiledCycles(output: string): bigint | undefined;
package/dist/flame.js ADDED
@@ -0,0 +1,179 @@
1
+ /**
2
+ * Flamegraphs of where a script's cycles go, from ckb-debugger's own profiler
3
+ * (`--enable-flamegraph --flamegraph-output`). ckb-debugger writes folded
4
+ * stacks, one `frame;frame;… cycles` line per sample, with the same stack on
5
+ * many lines and every frame as `<source path>:<function>`. Here they are
6
+ * merged, the paths dropped, and drawn as an SVG. Plain TypeScript with no Node
7
+ * built-ins, like replay.ts, so the browser can draw the same thing.
8
+ *
9
+ * A deployed binary is usually stripped: its whole run is one frame. Pass an
10
+ * unstripped build of the same code (`ckb-debugger --bin`) to see functions.
11
+ */
12
+ /**
13
+ * `E:\…\src\main.rs:session_lock::lock_hash` → `session_lock::lock_hash`. The
14
+ * path ends at the first `.<ext>:`; `??:func_0x114e4` (no symbols) keeps its address.
15
+ */
16
+ export function frameName(frame) {
17
+ const f = frame.trim();
18
+ if (f.startsWith("??:"))
19
+ return f.slice(3);
20
+ const m = /^.*?\.[A-Za-z0-9]+:(.+)$/.exec(f);
21
+ return m ? m[1] : f;
22
+ }
23
+ /**
24
+ * Splits a folded stack into frames. `;` separates frames, but Rust names hold
25
+ * it too (`[u8; 32]`), so a `;` inside brackets belongs to the name.
26
+ */
27
+ export function splitStack(stack) {
28
+ const frames = [];
29
+ let depth = 0;
30
+ let start = 0;
31
+ for (let i = 0; i < stack.length; i++) {
32
+ const c = stack[i];
33
+ if (c === "<" || c === "[" || c === "(" || c === "{")
34
+ depth++;
35
+ else if ((c === ">" || c === "]" || c === ")" || c === "}") && depth > 0)
36
+ depth--;
37
+ else if (c === ";" && depth === 0) {
38
+ frames.push(stack.slice(start, i));
39
+ start = i + 1;
40
+ }
41
+ }
42
+ frames.push(stack.slice(start));
43
+ return frames;
44
+ }
45
+ /** The deepest stack kept; deeper frames are folded into one. */
46
+ export const MAX_DEPTH = 256;
47
+ /** Parses ckb-debugger's folded output: identical stacks merged, frames named by function only. */
48
+ export function parseFolded(text) {
49
+ const folded = new Map();
50
+ for (const line of text.split(/\r?\n/)) {
51
+ const m = /^(.*\S)\s+(\d+)$/.exec(line);
52
+ if (!m)
53
+ continue;
54
+ // A real CKB script nests nowhere near this deep; a hostile file could, and
55
+ // the tree is walked recursively (review, 27 Oct). Deeper frames fold into the last.
56
+ const frames = splitStack(m[1]).map(frameName);
57
+ if (frames.length > MAX_DEPTH)
58
+ frames.splice(MAX_DEPTH - 1, frames.length, "…");
59
+ // Rejoined with ";" as the frame separator: a name's own "; " (with a space) stays inside it.
60
+ const stack = frames.join(";");
61
+ folded.set(stack, (folded.get(stack) ?? 0n) + BigInt(m[2]));
62
+ }
63
+ return folded;
64
+ }
65
+ export const foldedTotal = (f) => [...f.values()].reduce((s, v) => s + v, 0n);
66
+ /** Back to text, one merged stack per line, heaviest first: the format speedscope and inferno read. */
67
+ export function formatFolded(f) {
68
+ return [...f.entries()]
69
+ .sort((a, b) => (a[1] === b[1] ? (a[0] < b[0] ? -1 : 1) : a[1] > b[1] ? -1 : 1))
70
+ .map(([s, v]) => `${s} ${v}`)
71
+ .join("\n");
72
+ }
73
+ /** Every function with its self and total cycles, heaviest self first. */
74
+ export function functionCosts(f) {
75
+ const costs = new Map();
76
+ const at = (name) => costs.get(name) ?? costs.set(name, { name, self: 0n, total: 0n }).get(name);
77
+ for (const [stack, v] of f) {
78
+ const frames = splitStack(stack);
79
+ at(frames[frames.length - 1]).self += v;
80
+ for (const name of new Set(frames))
81
+ at(name).total += v;
82
+ }
83
+ return [...costs.values()].sort((a, b) => (a.self === b.self ? (a.name < b.name ? -1 : 1) : a.self > b.self ? -1 : 1));
84
+ }
85
+ /** The call tree: each node's value is the cycles of every stack through it. Children heaviest first. */
86
+ export function flameTree(f, rootName = "all") {
87
+ const root = { name: rootName, value: 0n, children: [] };
88
+ // Children by name, so a wide profile is not quadratic (review, 27 Oct).
89
+ const index = new Map();
90
+ for (const [stack, v] of f) {
91
+ root.value += v;
92
+ let node = root;
93
+ for (const name of splitStack(stack)) {
94
+ const byName = index.get(node) ?? index.set(node, new Map()).get(node);
95
+ let child = byName.get(name);
96
+ if (!child) {
97
+ child = { name, value: 0n, children: [] };
98
+ node.children.push(child);
99
+ byName.set(name, child);
100
+ }
101
+ child.value += v;
102
+ node = child;
103
+ }
104
+ }
105
+ const sort = (n) => {
106
+ n.children.sort((a, b) => (a.value === b.value ? 0 : a.value > b.value ? -1 : 1));
107
+ n.children.forEach(sort);
108
+ };
109
+ sort(root);
110
+ return root;
111
+ }
112
+ const escape = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
113
+ const fmt = (n) => n.toLocaleString("en-US");
114
+ /**
115
+ * A self-contained SVG flamegraph: root at the bottom, width proportional to
116
+ * cycles, a tooltip (`<title>`) with the cycles and share on every frame.
117
+ * Frames narrower than `minWidth` pixels are left out. Colours are fixed per
118
+ * function name, so the same function looks the same in two graphs.
119
+ */
120
+ export function renderFlameSvg(tree, opts = {}) {
121
+ const width = opts.width ?? 1200;
122
+ const minWidth = opts.minWidth ?? 0.5;
123
+ const row = 18;
124
+ const top = 34;
125
+ const total = tree.value || 1n;
126
+ let depth = 0;
127
+ const rects = [];
128
+ const draw = (n, x, level) => {
129
+ const w = (Number(n.value) / Number(total)) * width;
130
+ if (w < minWidth)
131
+ return;
132
+ depth = Math.max(depth, level);
133
+ rects.push(`<g data-level="${level}" data-x="${x.toFixed(2)}"><title>${escape(n.name)} — ${fmt(n.value)} cycles (${((Number(n.value) / Number(total)) * 100).toFixed(1)}%)</title>` +
134
+ `<rect x="${x.toFixed(2)}" y="LEVEL${level}" width="${Math.max(w - 0.5, 0.5).toFixed(2)}" height="${row - 1}" rx="2" fill="${colour(n.name)}"/>` +
135
+ (w > 40 ? `<text x="${(x + 4).toFixed(2)}" y="TEXT${level}">${escape(clip(n.name, Math.floor((w - 8) / 7)))}</text>` : "") +
136
+ `</g>`);
137
+ let cx = x;
138
+ for (const c of n.children) {
139
+ draw(c, cx, level + 1);
140
+ cx += (Number(c.value) / Number(total)) * width;
141
+ }
142
+ };
143
+ draw(tree, 0, 0);
144
+ const height = top + (depth + 1) * row + 8;
145
+ // Root at the bottom: level 0 is the last row.
146
+ const body = rects
147
+ .join("\n")
148
+ .replace(/y="LEVEL(\d+)"/g, (_, l) => `y="${height - 8 - (Number(l) + 1) * row}"`)
149
+ .replace(/y="TEXT(\d+)"/g, (_, l) => `y="${height - 8 - (Number(l) + 1) * row + 12.5}"`);
150
+ const title = escape(opts.title ?? "cycles");
151
+ return [
152
+ `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" font-family="JetBrains Mono, ui-monospace, monospace" font-size="11">`,
153
+ `<rect width="100%" height="100%" fill="#0d1117"/>`,
154
+ `<text x="4" y="20" fill="#c9d1d9" font-size="13">${title} · ${fmt(tree.value)} cycles</text>`,
155
+ `<g fill="#0d1117">`,
156
+ body,
157
+ `</g>`,
158
+ `</svg>`,
159
+ ].join("\n");
160
+ }
161
+ function clip(s, chars) {
162
+ if (chars <= 1)
163
+ return "";
164
+ return s.length <= chars ? s : s.slice(0, Math.max(chars - 1, 1)) + "…";
165
+ }
166
+ /** A warm colour from the name, stable across graphs. */
167
+ function colour(name) {
168
+ let h = 0;
169
+ for (let i = 0; i < name.length; i++)
170
+ h = (h * 31 + name.charCodeAt(i)) >>> 0;
171
+ const hue = 10 + (h % 45); // red to amber
172
+ const light = 45 + ((h >>> 8) % 15);
173
+ return `hsl(${hue} 75% ${light}%)`;
174
+ }
175
+ /** The `All cycles: N` line ckb-debugger prints in flamegraph mode: what the profile covers. */
176
+ export function profiledCycles(output) {
177
+ const m = /^All cycles:\s*(\d+)/m.exec(output);
178
+ return m ? BigInt(m[1]) : undefined;
179
+ }
@@ -0,0 +1,20 @@
1
+ export { checkDebuggerPath, DebuggerNotFoundError, resolveDebugger } from "./debugger.js";
2
+ export type { ResolveOptions } from "./debugger.js";
3
+ export { analyzeTransaction, groupScripts, knownScriptNames, TransactionNotFoundError } from "./analyze.js";
4
+ export type { ScriptGroup, TxAnalysis } from "./analyze.js";
5
+ export { buildMockTransaction, httpRpc, isCellbase, mockFromTransaction, nodeConsensus, parseOutPointVec, scriptVersionAt, } from "./mock.js";
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";
8
+ export type { DebuggerOutput, GroupRun, Profile, ProfiledGroup, ReplayOptions, ReplayPlan, RunDebugger } from "./replay.js";
9
+ export { flameTransaction, profileTransaction, runNativeDebugger } from "./profile.js";
10
+ export type { FlameGroup, ProfileOptions } from "./profile.js";
11
+ export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, renderFlameSvg, splitStack, } from "./flame.js";
12
+ export type { FlameNode, Folded, FunctionCost } from "./flame.js";
13
+ export { runWasmDebugger, wasmDebuggerVersion, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
14
+ export type { WasmRun } from "./wasm.js";
15
+ export { substituteBinaries } from "./substitute.js";
16
+ export type { AppliedSubstitution, BinarySubstitution } from "./substitute.js";
17
+ export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, resultLabel, summarize, } from "./diff.js";
18
+ export type { CycleDiff, CycleReport, DiffOptions, DiffRow, FunctionDelta, FunctionResult, GroupResult, MarkdownOptions, ScenarioResult } from "./diff.js";
19
+ export { formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
20
+ export type { BinaryConfig, CyclesConfig, ReportOptions, ScenarioConfig } from "./report.js";
package/dist/index.js ADDED
@@ -0,0 +1,10 @@
1
+ export { checkDebuggerPath, DebuggerNotFoundError, resolveDebugger } from "./debugger.js";
2
+ export { analyzeTransaction, groupScripts, knownScriptNames, TransactionNotFoundError } from "./analyze.js";
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";
5
+ export { flameTransaction, profileTransaction, runNativeDebugger } from "./profile.js";
6
+ export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, renderFlameSvg, splitStack, } from "./flame.js";
7
+ export { runWasmDebugger, wasmDebuggerVersion, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
8
+ export { substituteBinaries } from "./substitute.js";
9
+ export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, resultLabel, summarize, } from "./diff.js";
10
+ export { formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";