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/CHANGELOG.md +44 -0
- package/LICENSE +21 -0
- package/README.md +394 -3
- package/dist/analyze.d.ts +50 -0
- package/dist/analyze.js +95 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +354 -0
- package/dist/debugger.d.ts +28 -0
- package/dist/debugger.js +56 -0
- package/dist/diff.d.ts +152 -0
- package/dist/diff.js +325 -0
- package/dist/flame.d.ts +59 -0
- package/dist/flame.js +179 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.js +10 -0
- package/dist/mock.d.ts +109 -0
- package/dist/mock.js +197 -0
- package/dist/profile.d.ts +68 -0
- package/dist/profile.js +130 -0
- package/dist/replay.d.ts +154 -0
- package/dist/replay.js +254 -0
- package/dist/report.d.ts +85 -0
- package/dist/report.js +396 -0
- package/dist/substitute.d.ts +41 -0
- package/dist/substitute.js +122 -0
- package/dist/wasm.d.ts +22 -0
- package/dist/wasm.js +51 -0
- package/package.json +68 -6
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, "&")
|
|
193
|
+
.replace(/</g, "<")
|
|
194
|
+
.replace(/>/g, ">"));
|
|
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));
|
package/dist/flame.d.ts
ADDED
|
@@ -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, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """);
|
|
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
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -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";
|