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/cli.js
ADDED
|
@@ -0,0 +1,354 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
import { parseArgs } from "node:util";
|
|
5
|
+
import { diffFailed, diffReports, formatMarkdown, formatText } from "./diff.js";
|
|
6
|
+
import { buildMockTransaction, httpRpc, mockFromTransaction } from "./mock.js";
|
|
7
|
+
import { flameTree, foldedTotal, formatFolded, functionCosts, renderFlameSvg } from "./flame.js";
|
|
8
|
+
import { flameTransaction, parseNames, profileTransaction, readTransactionJson } from "./profile.js";
|
|
9
|
+
import { PUBLIC_RPC } from "./replay.js";
|
|
10
|
+
import { formatReport, runReport } from "./report.js";
|
|
11
|
+
const USAGE = `usage: ckb-cycles <tx-hash> [--mainnet] [--rpc <url>] [--timeout <s>] [--debugger <path>]
|
|
12
|
+
[--json] [--name <code-hash>[:<hash-type>]=<label> ...]
|
|
13
|
+
ckb-cycles --file <tx.json> [same options]
|
|
14
|
+
ckb-cycles report <cycles.json> [--json <out.json>] [--binaries-from <dir>]
|
|
15
|
+
[--root <dir> ...] [--rpc <url>] [--timeout <s>] [--debugger <path>]
|
|
16
|
+
ckb-cycles diff <base.json> <head.json> [--markdown] [--fail-above <percent>]
|
|
17
|
+
[--fail-on-result-change] [--title <s>] [--base-label <s>] [--head-label <s>]
|
|
18
|
+
ckb-cycles mock <tx-hash> | --file <tx.json> [-o <mock.json>] [--mainnet] [--rpc <url>]
|
|
19
|
+
[--timeout <s>]
|
|
20
|
+
ckb-cycles flame <tx-hash> | --file <tx.json> [-o <dir>] [--script <selector> ...]
|
|
21
|
+
[--bin <code-hash>=<elf> ...] [--top <n>] [--mainnet] [--rpc <url>] [--debugger <path>]
|
|
22
|
+
|
|
23
|
+
Replays a CKB transaction in ckb-debugger, one run per script group, and prints
|
|
24
|
+
the cycles each group cost.
|
|
25
|
+
|
|
26
|
+
<tx-hash> a committed transaction; the sum is checked against the node
|
|
27
|
+
--file a transaction that is not on chain: one about to be sent, or one
|
|
28
|
+
the node rejected. Shows which script refuses it and why. JSON in
|
|
29
|
+
the node's RPC shape, a get_transaction result, or ccc.stringify(tx)
|
|
30
|
+
--rpc the node to ask. Its chain and hardfork epochs (get_consensus)
|
|
31
|
+
decide the CKB-VM version, whatever the flags say; --mainnet with
|
|
32
|
+
a node that serves another chain stops with an error
|
|
33
|
+
--timeout seconds to wait for each RPC answer (default 30)
|
|
34
|
+
--name a label for your own script, shown instead of its code hash;
|
|
35
|
+
repeat for several. Without :<hash-type> it applies to all of them
|
|
36
|
+
|
|
37
|
+
Exit codes: 0 every script accepts (and the sum matches the node's)
|
|
38
|
+
1 a script rejects, or the sum differs from the node's
|
|
39
|
+
2 usage or environment error: bad arguments, node unreachable,
|
|
40
|
+
transaction not found, ckb-debugger missing or unreadable output
|
|
41
|
+
|
|
42
|
+
report runs every scenario in a cycles.json (see README) and records each
|
|
43
|
+
script group's result and cycles; --json writes them for diff.
|
|
44
|
+
--binaries-from <dir> reads the binaries from another checkout
|
|
45
|
+
(the PR's base). A binary with "symbols" in a scenario with
|
|
46
|
+
"functions" also records the group's costliest functions.
|
|
47
|
+
--root <dir> (repeatable) refuses any file the config names
|
|
48
|
+
outside those directories, symlinks resolved: for CI, where
|
|
49
|
+
the cycles.json comes from a pull request
|
|
50
|
+
Exits 2 if a scenario could not run: a rejection is a result,
|
|
51
|
+
not an error
|
|
52
|
+
diff compares two reports group by group: Δ cycles, Δ%, and any group
|
|
53
|
+
whose result changed (ok → exit 12, or back). --fail-above exits 1
|
|
54
|
+
when a group grows by more than that percentage (a new group
|
|
55
|
+
has no base, so no percentage: it is never over the threshold),
|
|
56
|
+
--fail-on-result-change when a result changed, including a new
|
|
57
|
+
group that does not accept. A scenario the head could not run
|
|
58
|
+
always exits 1; one the base could not run exits 1 when either
|
|
59
|
+
flag is set
|
|
60
|
+
mock saves a transaction as a ckb-debugger mock transaction, every cell
|
|
61
|
+
it touches included, so a scenario can replay it with no node
|
|
62
|
+
flame where inside each script the cycles go: ckb-debugger's flamegraph
|
|
63
|
+
mode per script group. Prints the costliest functions and writes
|
|
64
|
+
<dir>/<selector>.svg and .folded (for speedscope or inferno), in
|
|
65
|
+
./flame by default. A deployed binary is usually stripped, so it is
|
|
66
|
+
one frame: --bin gives an unstripped build of the same code (its
|
|
67
|
+
cycles are checked against the deployed binary's). The profile
|
|
68
|
+
leaves out loading the binary, so it is a little under the group's
|
|
69
|
+
cycles`;
|
|
70
|
+
const fmt = (n) => n.toLocaleString("en-US");
|
|
71
|
+
const short = (h, n = 6) => (h.length > 2 * n + 2 ? `${h.slice(0, n + 2)}…${h.slice(-n)}` : h);
|
|
72
|
+
function table(p) {
|
|
73
|
+
const total = p.measuredCycles || 1n;
|
|
74
|
+
const rows = p.groups.map((g) => [
|
|
75
|
+
g.role,
|
|
76
|
+
g.name ?? short(g.codeHash),
|
|
77
|
+
g.selector,
|
|
78
|
+
g.error ? "error" : g.result === 0 ? "ok" : `exit ${g.result}`,
|
|
79
|
+
fmt(g.cycles),
|
|
80
|
+
`${((Number(g.cycles) / Number(total)) * 100).toFixed(1)}%`,
|
|
81
|
+
]);
|
|
82
|
+
const head = ["GROUP", "SCRIPT", "RUN AT", "RESULT", "CYCLES", "SHARE"];
|
|
83
|
+
const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
|
|
84
|
+
const line = (cells) => cells.map((c, i) => (i >= 4 ? c.padStart(widths[i]) : c.padEnd(widths[i]))).join(" ");
|
|
85
|
+
const title = p.nodeCycles === undefined && p.status === "not on chain" ? "tx not on chain" : `tx ${p.hash} (${p.status})`;
|
|
86
|
+
const out = [title, "", line(head), ...rows.map(line), ""];
|
|
87
|
+
out.push(`measured (sum of groups) ${fmt(p.measuredCycles)}`);
|
|
88
|
+
if (p.nodeCycles !== undefined) {
|
|
89
|
+
const match = p.nodeCycles === p.measuredCycles;
|
|
90
|
+
out.push(`reported by node ${fmt(p.nodeCycles)} ${match ? "✓ match" : "✗ MISMATCH"}`);
|
|
91
|
+
}
|
|
92
|
+
else if (p.status === "committed") {
|
|
93
|
+
out.push("reported by node not recorded by this node (try another with --rpc)");
|
|
94
|
+
}
|
|
95
|
+
out.push(`${p.env.debugger} · CKB-VM v${p.env.scriptVersion} for type scripts · ${p.env.network} · ${p.env.rpcUrl}`);
|
|
96
|
+
for (const g of p.groups.filter((g) => g.error))
|
|
97
|
+
out.push("", `${g.selector} stopped: ${g.error}`);
|
|
98
|
+
for (const g of p.groups.filter((g) => g.logs.length)) {
|
|
99
|
+
out.push("", `${g.selector} logged:`, ...g.logs.map((l) => ` ${l}`));
|
|
100
|
+
}
|
|
101
|
+
return out.join("\n");
|
|
102
|
+
}
|
|
103
|
+
/** `--timeout <seconds>` → milliseconds; usage error (exit 2) for anything but a positive number. */
|
|
104
|
+
function timeoutOf(value) {
|
|
105
|
+
if (value === undefined)
|
|
106
|
+
return {};
|
|
107
|
+
const seconds = Number(value);
|
|
108
|
+
if (!(seconds > 0))
|
|
109
|
+
throw new Error("--timeout expects a number of seconds, e.g. 30");
|
|
110
|
+
return { timeoutMs: seconds * 1000 };
|
|
111
|
+
}
|
|
112
|
+
const toJson = (v) => JSON.stringify(v, (_, x) => (typeof x === "bigint" ? x.toString() : x), 2);
|
|
113
|
+
async function reportCommand(args) {
|
|
114
|
+
const { values, positionals } = parseArgs({
|
|
115
|
+
args,
|
|
116
|
+
allowPositionals: true,
|
|
117
|
+
options: {
|
|
118
|
+
json: { type: "string" },
|
|
119
|
+
rpc: { type: "string" },
|
|
120
|
+
timeout: { type: "string" },
|
|
121
|
+
debugger: { type: "string" },
|
|
122
|
+
"binaries-from": { type: "string" },
|
|
123
|
+
root: { type: "string", multiple: true },
|
|
124
|
+
},
|
|
125
|
+
});
|
|
126
|
+
if (positionals.length !== 1) {
|
|
127
|
+
console.log(USAGE);
|
|
128
|
+
return 2;
|
|
129
|
+
}
|
|
130
|
+
const report = await runReport(positionals[0], {
|
|
131
|
+
...(values.rpc && { rpcUrl: values.rpc }),
|
|
132
|
+
...timeoutOf(values.timeout),
|
|
133
|
+
...(values.debugger && { debuggerPath: values.debugger }),
|
|
134
|
+
...(values["binaries-from"] && { binariesRoot: values["binaries-from"] }),
|
|
135
|
+
...(values.root && { roots: values.root }),
|
|
136
|
+
onScenario: (s) => console.error(`${s.error ? "✗" : "·"} ${s.name}`),
|
|
137
|
+
});
|
|
138
|
+
const { errors, ...data } = report;
|
|
139
|
+
if (values.json)
|
|
140
|
+
await writeFile(values.json, toJson(data) + "\n");
|
|
141
|
+
console.log(formatReport(data));
|
|
142
|
+
for (const e of errors)
|
|
143
|
+
console.error(`error: ${e}`);
|
|
144
|
+
return errors.length ? 2 : 0;
|
|
145
|
+
}
|
|
146
|
+
async function readReport(path) {
|
|
147
|
+
const r = JSON.parse(await readFile(path, "utf8"));
|
|
148
|
+
if (r?.tool !== "ckb-cycles" || !Array.isArray(r.scenarios))
|
|
149
|
+
throw new Error(`${path} is not a ckb-cycles report`);
|
|
150
|
+
return r;
|
|
151
|
+
}
|
|
152
|
+
async function diffCommand(args) {
|
|
153
|
+
const { values, positionals } = parseArgs({
|
|
154
|
+
args,
|
|
155
|
+
allowPositionals: true,
|
|
156
|
+
options: {
|
|
157
|
+
markdown: { type: "boolean" },
|
|
158
|
+
"fail-above": { type: "string" },
|
|
159
|
+
"fail-on-result-change": { type: "boolean" },
|
|
160
|
+
"base-label": { type: "string" },
|
|
161
|
+
"head-label": { type: "string" },
|
|
162
|
+
title: { type: "string" },
|
|
163
|
+
},
|
|
164
|
+
});
|
|
165
|
+
if (positionals.length !== 2) {
|
|
166
|
+
console.log(USAGE);
|
|
167
|
+
return 2;
|
|
168
|
+
}
|
|
169
|
+
const failAbove = values["fail-above"] === undefined ? undefined : Number(values["fail-above"]);
|
|
170
|
+
if (failAbove !== undefined && !(failAbove >= 0)) {
|
|
171
|
+
console.error("error: --fail-above expects a percentage, e.g. 5");
|
|
172
|
+
return 2;
|
|
173
|
+
}
|
|
174
|
+
const options = { ...(failAbove !== undefined && { failAbove }), failOnResultChange: values["fail-on-result-change"] };
|
|
175
|
+
const diff = diffReports(await readReport(positionals[0]), await readReport(positionals[1]), options);
|
|
176
|
+
console.log(values.markdown
|
|
177
|
+
? formatMarkdown(diff, {
|
|
178
|
+
...(values.title && { title: values.title }),
|
|
179
|
+
...(values["base-label"] && { baseLabel: values["base-label"] }),
|
|
180
|
+
...(values["head-label"] && { headLabel: values["head-label"] }),
|
|
181
|
+
})
|
|
182
|
+
: formatText(diff));
|
|
183
|
+
return diffFailed(diff, options) ? 1 : 0;
|
|
184
|
+
}
|
|
185
|
+
async function mockCommand(args) {
|
|
186
|
+
const { values, positionals } = parseArgs({
|
|
187
|
+
args,
|
|
188
|
+
allowPositionals: true,
|
|
189
|
+
options: {
|
|
190
|
+
file: { type: "string" },
|
|
191
|
+
out: { type: "string", short: "o" },
|
|
192
|
+
mainnet: { type: "boolean" },
|
|
193
|
+
rpc: { type: "string" },
|
|
194
|
+
timeout: { type: "string" },
|
|
195
|
+
},
|
|
196
|
+
});
|
|
197
|
+
const [hash] = positionals;
|
|
198
|
+
if (positionals.length > 1 || !hash === !values.file || (hash && !/^0x[0-9a-fA-F]{64}$/.test(hash))) {
|
|
199
|
+
console.log(USAGE);
|
|
200
|
+
return 2;
|
|
201
|
+
}
|
|
202
|
+
const rpc = httpRpc(values.rpc ?? PUBLIC_RPC[values.mainnet ? "mainnet" : "testnet"], timeoutOf(values.timeout));
|
|
203
|
+
const mock = values.file
|
|
204
|
+
? await mockFromTransaction(rpc, readTransactionJson(await readFile(values.file, "utf8")))
|
|
205
|
+
: (await buildMockTransaction(rpc, hash)).mock;
|
|
206
|
+
if (values.out)
|
|
207
|
+
await writeFile(values.out, toJson(mock) + "\n");
|
|
208
|
+
else
|
|
209
|
+
console.log(toJson(mock));
|
|
210
|
+
return 0;
|
|
211
|
+
}
|
|
212
|
+
/** `--bin 0xabc…=target/release/my-script` → flameTransaction's bins. */
|
|
213
|
+
function parseBins(flags) {
|
|
214
|
+
const bins = {};
|
|
215
|
+
for (const flag of flags) {
|
|
216
|
+
const m = /^(0x[0-9a-fA-F]{64})=(.+)$/.exec(flag);
|
|
217
|
+
if (!m)
|
|
218
|
+
throw new Error(`--bin expects <code-hash>=<path to an ELF>, got "${flag}"`);
|
|
219
|
+
bins[m[1].toLowerCase()] = m[2];
|
|
220
|
+
}
|
|
221
|
+
return bins;
|
|
222
|
+
}
|
|
223
|
+
async function flameCommand(args) {
|
|
224
|
+
const { values, positionals } = parseArgs({
|
|
225
|
+
args,
|
|
226
|
+
allowPositionals: true,
|
|
227
|
+
options: {
|
|
228
|
+
file: { type: "string" },
|
|
229
|
+
out: { type: "string", short: "o" },
|
|
230
|
+
script: { type: "string", multiple: true },
|
|
231
|
+
bin: { type: "string", multiple: true },
|
|
232
|
+
top: { type: "string" },
|
|
233
|
+
mainnet: { type: "boolean" },
|
|
234
|
+
rpc: { type: "string" },
|
|
235
|
+
timeout: { type: "string" },
|
|
236
|
+
debugger: { type: "string" },
|
|
237
|
+
name: { type: "string", multiple: true },
|
|
238
|
+
},
|
|
239
|
+
});
|
|
240
|
+
const [hash] = positionals;
|
|
241
|
+
if (positionals.length > 1 || !hash === !values.file || (hash && !/^0x[0-9a-fA-F]{64}$/.test(hash))) {
|
|
242
|
+
console.log(USAGE);
|
|
243
|
+
return 2;
|
|
244
|
+
}
|
|
245
|
+
const top = values.top === undefined ? 8 : Number(values.top);
|
|
246
|
+
if (!(Number.isInteger(top) && top > 0))
|
|
247
|
+
throw new Error("--top expects a positive whole number");
|
|
248
|
+
const target = values.file ? readTransactionJson(await readFile(values.file, "utf8")) : hash;
|
|
249
|
+
const { plan, groups, debugger: version } = await flameTransaction(target, {
|
|
250
|
+
...(values.mainnet && { network: "mainnet" }),
|
|
251
|
+
...(values.rpc && { rpcUrl: values.rpc }),
|
|
252
|
+
...timeoutOf(values.timeout),
|
|
253
|
+
...(values.debugger && { debuggerPath: values.debugger }),
|
|
254
|
+
scriptNames: parseNames(values.name ?? []),
|
|
255
|
+
bins: parseBins(values.bin ?? []),
|
|
256
|
+
...(values.script && { scripts: values.script }),
|
|
257
|
+
readFile: (path) => readFile(path, "utf8"),
|
|
258
|
+
});
|
|
259
|
+
if (!groups.length) {
|
|
260
|
+
console.error("error: no script group to profile (check --script)");
|
|
261
|
+
return 2;
|
|
262
|
+
}
|
|
263
|
+
const dir = values.out ?? "flame";
|
|
264
|
+
await mkdir(dir, { recursive: true });
|
|
265
|
+
const out = [`tx ${plan.hash} (${plan.status})`, ""];
|
|
266
|
+
let bad = false;
|
|
267
|
+
for (const g of groups) {
|
|
268
|
+
const label = g.name ?? short(g.codeHash);
|
|
269
|
+
const profiled = foldedTotal(g.folded);
|
|
270
|
+
out.push(`${g.selector} ${label} ${g.error ? "error" : g.result === 0 ? "ok" : `exit ${g.result}`} ${fmt(g.cycles)} cycles`);
|
|
271
|
+
if (g.bin) {
|
|
272
|
+
// Same cycles and the same verdict, and neither run stopped by the VM: two stopped
|
|
273
|
+
// runs both report 0 cycles, which proves nothing (review, 27 Oct).
|
|
274
|
+
const same = g.deployedCycles === g.cycles && g.deployedResult === g.result && !g.error && !g.deployedError;
|
|
275
|
+
out.push(` --bin ${g.bin}: ${same ? "same cycles as the deployed binary" : `✗ ${fmt(g.deployedCycles ?? 0n)} cycles, result ${g.deployedError ? "vm error" : g.deployedResult} with the deployed binary: this build is not that code`}`);
|
|
276
|
+
bad ||= !same;
|
|
277
|
+
}
|
|
278
|
+
if (!g.folded.size) {
|
|
279
|
+
out.push(" no profile written (the run stopped before it could be profiled?)", "");
|
|
280
|
+
continue;
|
|
281
|
+
}
|
|
282
|
+
const costs = functionCosts(g.folded);
|
|
283
|
+
if (costs.length === 1)
|
|
284
|
+
out.push(" one frame: the binary has no symbols. Pass an unstripped build with --bin <code-hash>=<elf>");
|
|
285
|
+
out.push(` profiled ${fmt(profiled)} cycles (loading the binary is not profiled)`, " SELF TOTAL FUNCTION");
|
|
286
|
+
for (const c of costs.slice(0, top))
|
|
287
|
+
out.push(` ${fmt(c.self).padStart(10)} ${fmt(c.total).padStart(10)} ${c.name}`);
|
|
288
|
+
const base = join(dir, g.selector);
|
|
289
|
+
await writeFile(`${base}.folded`, formatFolded(g.folded) + "\n");
|
|
290
|
+
await writeFile(`${base}.svg`, renderFlameSvg(flameTree(g.folded, g.selector), { title: `${g.selector} · ${label}` }));
|
|
291
|
+
out.push(` → ${base}.svg, ${base}.folded`, "");
|
|
292
|
+
}
|
|
293
|
+
out.push(`${version} · CKB-VM v${plan.scriptVersion} for type scripts · ${plan.network} · ${plan.rpcUrl}`);
|
|
294
|
+
console.log(out.join("\n"));
|
|
295
|
+
return bad || groups.some((g) => g.result !== 0) ? 1 : 0;
|
|
296
|
+
}
|
|
297
|
+
async function main() {
|
|
298
|
+
const [command, ...rest] = process.argv.slice(2);
|
|
299
|
+
if (command === "report")
|
|
300
|
+
return reportCommand(rest);
|
|
301
|
+
if (command === "diff")
|
|
302
|
+
return diffCommand(rest);
|
|
303
|
+
if (command === "mock")
|
|
304
|
+
return mockCommand(rest);
|
|
305
|
+
if (command === "flame")
|
|
306
|
+
return flameCommand(rest);
|
|
307
|
+
const { values, positionals } = parseArgs({
|
|
308
|
+
allowPositionals: true,
|
|
309
|
+
options: {
|
|
310
|
+
mainnet: { type: "boolean" },
|
|
311
|
+
rpc: { type: "string" },
|
|
312
|
+
timeout: { type: "string" },
|
|
313
|
+
debugger: { type: "string" },
|
|
314
|
+
json: { type: "boolean" },
|
|
315
|
+
file: { type: "string" },
|
|
316
|
+
name: { type: "string", multiple: true },
|
|
317
|
+
help: { type: "boolean", short: "h" },
|
|
318
|
+
},
|
|
319
|
+
});
|
|
320
|
+
const [hash] = positionals;
|
|
321
|
+
if (values.help || (!hash && !values.file) || (hash && values.file)) {
|
|
322
|
+
console.log(USAGE);
|
|
323
|
+
return values.help ? 0 : 2;
|
|
324
|
+
}
|
|
325
|
+
if (hash && !/^0x[0-9a-fA-F]{64}$/.test(hash)) {
|
|
326
|
+
console.error("error: expected a transaction hash: 0x followed by 64 hex characters");
|
|
327
|
+
return 2;
|
|
328
|
+
}
|
|
329
|
+
const target = values.file ? readTransactionJson(await readFile(values.file, "utf8")) : hash;
|
|
330
|
+
const p = await profileTransaction(target, {
|
|
331
|
+
// Only an explicit --mainnet is passed on, and checked against the node;
|
|
332
|
+
// without it, the node itself says which chain it serves.
|
|
333
|
+
...(values.mainnet && { network: "mainnet" }),
|
|
334
|
+
...(values.rpc && { rpcUrl: values.rpc }),
|
|
335
|
+
...timeoutOf(values.timeout),
|
|
336
|
+
...(values.debugger && { debuggerPath: values.debugger }),
|
|
337
|
+
scriptNames: parseNames(values.name ?? []),
|
|
338
|
+
});
|
|
339
|
+
if (values.json) {
|
|
340
|
+
console.log(JSON.stringify(p, (_, v) => (typeof v === "bigint" ? v.toString() : v), 2));
|
|
341
|
+
}
|
|
342
|
+
else {
|
|
343
|
+
console.log(table(p));
|
|
344
|
+
}
|
|
345
|
+
const mismatch = p.nodeCycles !== undefined && p.nodeCycles !== p.measuredCycles;
|
|
346
|
+
return mismatch || p.groups.some((g) => g.result !== 0) ? 1 : 0;
|
|
347
|
+
}
|
|
348
|
+
// 1 is a verdict (a script rejects, a sum differs, a diff over its thresholds);
|
|
349
|
+
// anything thrown is the tool not getting that far: 2, so a CI job asserting a
|
|
350
|
+
// rejection with `test $? = 1` does not pass when the node is down.
|
|
351
|
+
main().then((code) => process.exit(code), (e) => {
|
|
352
|
+
console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
|
|
353
|
+
process.exit(2);
|
|
354
|
+
});
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Finds the native `ckb-debugger` executable.
|
|
3
|
+
*
|
|
4
|
+
* On Windows, offckb installs the real binary into its own data directory and
|
|
5
|
+
* puts only a `ckb-debugger.cmd` shim on PATH. A shell-less `child_process`
|
|
6
|
+
* spawn cannot resolve a bare name to a `.cmd` file, so tools that spawn
|
|
7
|
+
* `ckb-debugger` directly fail there. This resolver returns a path to the real
|
|
8
|
+
* `.exe` instead, so callers can spawn it without a shell.
|
|
9
|
+
*
|
|
10
|
+
* Order: `CKB_DEBUGGER_PATH`, then PATH (executables only, never `.cmd`), then
|
|
11
|
+
* offckb's tools directory on Windows.
|
|
12
|
+
*/
|
|
13
|
+
export interface ResolveOptions {
|
|
14
|
+
env?: NodeJS.ProcessEnv;
|
|
15
|
+
platform?: NodeJS.Platform;
|
|
16
|
+
exists?: (path: string) => boolean;
|
|
17
|
+
}
|
|
18
|
+
export declare class DebuggerNotFoundError extends Error {
|
|
19
|
+
readonly searched: string[];
|
|
20
|
+
constructor(searched: string[]);
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Checks a path given explicitly (`CKB_DEBUGGER_PATH`, `--debugger`): it must
|
|
24
|
+
* exist, and must not be a `.cmd`/`.bat` shim, which Node cannot spawn without
|
|
25
|
+
* a shell (it fails with a bare `spawn EINVAL`).
|
|
26
|
+
*/
|
|
27
|
+
export declare function checkDebuggerPath(path: string, exists?: (path: string) => boolean): string;
|
|
28
|
+
export declare function resolveDebugger(options?: ResolveOptions): string;
|
package/dist/debugger.js
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import { existsSync } from "node:fs";
|
|
2
|
+
import { delimiter, join } from "node:path";
|
|
3
|
+
export class DebuggerNotFoundError extends Error {
|
|
4
|
+
searched;
|
|
5
|
+
constructor(searched) {
|
|
6
|
+
super(`ckb-debugger not found. Set CKB_DEBUGGER_PATH (or pass --debugger), or install it with ` +
|
|
7
|
+
`\`offckb debugger\` or from the ckb-standalone-debugger releases. ` +
|
|
8
|
+
`Searched:\n ${searched.join("\n ")}`);
|
|
9
|
+
this.searched = searched;
|
|
10
|
+
this.name = "DebuggerNotFoundError";
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Checks a path given explicitly (`CKB_DEBUGGER_PATH`, `--debugger`): it must
|
|
15
|
+
* exist, and must not be a `.cmd`/`.bat` shim, which Node cannot spawn without
|
|
16
|
+
* a shell (it fails with a bare `spawn EINVAL`).
|
|
17
|
+
*/
|
|
18
|
+
export function checkDebuggerPath(path, exists = existsSync) {
|
|
19
|
+
if (/\.(cmd|bat)$/i.test(path)) {
|
|
20
|
+
throw new Error(`${path} is a Windows shim, which cannot be run without a shell. Point to the real ckb-debugger.exe ` +
|
|
21
|
+
`instead: offckb installs it in %LOCALAPPDATA%\\offckb-nodejs\\Data\\tools\\ckb-debugger.exe`);
|
|
22
|
+
}
|
|
23
|
+
// An explicit path that does not exist is a configuration error, not
|
|
24
|
+
// something to silently fall past.
|
|
25
|
+
if (!exists(path))
|
|
26
|
+
throw new DebuggerNotFoundError([path]);
|
|
27
|
+
return path;
|
|
28
|
+
}
|
|
29
|
+
export function resolveDebugger(options = {}) {
|
|
30
|
+
const env = options.env ?? process.env;
|
|
31
|
+
const platform = options.platform ?? process.platform;
|
|
32
|
+
const exists = options.exists ?? existsSync;
|
|
33
|
+
const isWindows = platform === "win32";
|
|
34
|
+
const binary = isWindows ? "ckb-debugger.exe" : "ckb-debugger";
|
|
35
|
+
const searched = [];
|
|
36
|
+
const explicit = env.CKB_DEBUGGER_PATH;
|
|
37
|
+
if (explicit)
|
|
38
|
+
return checkDebuggerPath(explicit, exists);
|
|
39
|
+
const pathVar = env.PATH ?? env.Path ?? "";
|
|
40
|
+
// On Windows, path.delimiter is ";" — but resolve with the target platform's
|
|
41
|
+
// delimiter so the function can be tested for either platform anywhere.
|
|
42
|
+
const sep = isWindows ? ";" : platform === process.platform ? delimiter : ":";
|
|
43
|
+
for (const dir of pathVar.split(sep).filter(Boolean)) {
|
|
44
|
+
const candidate = join(dir, binary);
|
|
45
|
+
searched.push(candidate);
|
|
46
|
+
if (exists(candidate))
|
|
47
|
+
return candidate;
|
|
48
|
+
}
|
|
49
|
+
if (isWindows && env.LOCALAPPDATA) {
|
|
50
|
+
const offckb = join(env.LOCALAPPDATA, "offckb-nodejs", "Data", "tools", binary);
|
|
51
|
+
searched.push(offckb);
|
|
52
|
+
if (exists(offckb))
|
|
53
|
+
return offckb;
|
|
54
|
+
}
|
|
55
|
+
throw new DebuggerNotFoundError(searched);
|
|
56
|
+
}
|
package/dist/diff.d.ts
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
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
|
+
/** What `ckb-cycles report` writes. */
|
|
8
|
+
export interface CycleReport {
|
|
9
|
+
tool: "ckb-cycles";
|
|
10
|
+
version: 1;
|
|
11
|
+
/** ckb-debugger's `--version`, so two reports can be checked for comparability. */
|
|
12
|
+
debugger?: string;
|
|
13
|
+
scenarios: ScenarioResult[];
|
|
14
|
+
}
|
|
15
|
+
export interface ScenarioResult {
|
|
16
|
+
name: string;
|
|
17
|
+
/** Set when the scenario could not be run at all (a missing file, a node that is down). */
|
|
18
|
+
error?: string;
|
|
19
|
+
groups: GroupResult[];
|
|
20
|
+
/** Warnings from binary substitution, kept so a reader can tell why a result changed. */
|
|
21
|
+
warnings?: string[];
|
|
22
|
+
/**
|
|
23
|
+
* The scenario could not run because a binary it needs does not exist where
|
|
24
|
+
* `--binaries-from` points. On the base of a pull request, that is a scenario
|
|
25
|
+
* whose code is new in the head: its groups count as new, not as a base error.
|
|
26
|
+
*/
|
|
27
|
+
binaryMissing?: boolean;
|
|
28
|
+
}
|
|
29
|
+
export interface GroupResult {
|
|
30
|
+
/** ckb-debugger's selector, e.g. `input.0.lock`: the key a group is matched by across reports. */
|
|
31
|
+
selector: string;
|
|
32
|
+
role: "lock" | "type";
|
|
33
|
+
/** A name for the script, or its short code hash. */
|
|
34
|
+
script: string;
|
|
35
|
+
codeHash: string;
|
|
36
|
+
hashType: string;
|
|
37
|
+
/** The script's exit code: 0 accepts. -1 with `error` when the VM stopped it. */
|
|
38
|
+
result: number;
|
|
39
|
+
error?: string;
|
|
40
|
+
cycles: number;
|
|
41
|
+
/**
|
|
42
|
+
* The costliest functions of the run, heaviest self first (at most
|
|
43
|
+
* FUNCTION_LIMIT). Only for a group whose binary has a `symbols` build.
|
|
44
|
+
*/
|
|
45
|
+
functions?: FunctionResult[];
|
|
46
|
+
/** Why `functions` were not recorded although asked for (the symbols build costs other cycles…). */
|
|
47
|
+
functionsWarning?: string;
|
|
48
|
+
}
|
|
49
|
+
export interface FunctionResult {
|
|
50
|
+
name: string;
|
|
51
|
+
/** Cycles spent in the function itself. */
|
|
52
|
+
self: number;
|
|
53
|
+
/** Cycles spent in it and everything it called. */
|
|
54
|
+
total: number;
|
|
55
|
+
}
|
|
56
|
+
/** How many functions a report keeps per group. */
|
|
57
|
+
export declare const FUNCTION_LIMIT = 15;
|
|
58
|
+
/**
|
|
59
|
+
* One function's self cycles on each side. A side is undefined when it is not
|
|
60
|
+
* known: no functions were recorded there, or the function is not in a list
|
|
61
|
+
* that was cut at FUNCTION_LIMIT. In a shorter list, absent means 0.
|
|
62
|
+
*/
|
|
63
|
+
export interface FunctionDelta {
|
|
64
|
+
name: string;
|
|
65
|
+
base?: number;
|
|
66
|
+
head?: number;
|
|
67
|
+
/** Set when both sides are known. */
|
|
68
|
+
delta?: number;
|
|
69
|
+
}
|
|
70
|
+
/** `error`: the head could not run the scenario. `base-error`: the base could not, so nothing was compared. */
|
|
71
|
+
export type RowKind = "same" | "changed" | "result" | "new" | "removed" | "error" | "base-error";
|
|
72
|
+
export interface DiffRow {
|
|
73
|
+
scenario: string;
|
|
74
|
+
/** The group's selector, or "" for a row about the whole scenario. */
|
|
75
|
+
group: string;
|
|
76
|
+
script: string;
|
|
77
|
+
base?: {
|
|
78
|
+
result: string;
|
|
79
|
+
cycles?: number;
|
|
80
|
+
};
|
|
81
|
+
head?: {
|
|
82
|
+
result: string;
|
|
83
|
+
cycles?: number;
|
|
84
|
+
};
|
|
85
|
+
delta?: number;
|
|
86
|
+
/** Percentage change; undefined when the base cost nothing. */
|
|
87
|
+
percent?: number;
|
|
88
|
+
kind: RowKind;
|
|
89
|
+
/** The increase is over the threshold. */
|
|
90
|
+
overThreshold: boolean;
|
|
91
|
+
/** Free text for an error row. */
|
|
92
|
+
note?: string;
|
|
93
|
+
/** Functions whose self cycles changed, largest change first (when the head recorded functions). */
|
|
94
|
+
functions?: FunctionDelta[];
|
|
95
|
+
/** The head's reason for not recording functions. */
|
|
96
|
+
functionsWarning?: string;
|
|
97
|
+
}
|
|
98
|
+
export interface CycleDiff {
|
|
99
|
+
rows: DiffRow[];
|
|
100
|
+
/**
|
|
101
|
+
* Groups whose accept/reject outcome changed (ok → exit 12, exit 12 → ok,
|
|
102
|
+
* exit 12 → exit 13), and new groups that do not accept: a new group is
|
|
103
|
+
* compared with "did not run".
|
|
104
|
+
*/
|
|
105
|
+
resultChanges: number;
|
|
106
|
+
/** Groups whose cycles grew by more than the threshold. */
|
|
107
|
+
overThreshold: number;
|
|
108
|
+
/** Scenarios the base could not run: their head groups had nothing to be compared with. */
|
|
109
|
+
baseErrors: number;
|
|
110
|
+
threshold?: number;
|
|
111
|
+
}
|
|
112
|
+
export interface DiffOptions {
|
|
113
|
+
/** Percent. An increase above it is flagged, and makes `failed` true. */
|
|
114
|
+
failAbove?: number;
|
|
115
|
+
/** A changed outcome makes `failed` true. */
|
|
116
|
+
failOnResultChange?: boolean;
|
|
117
|
+
}
|
|
118
|
+
/** `ok`, `exit 12`, or `error` (the VM stopped the script). */
|
|
119
|
+
export declare function resultLabel(g: Pick<GroupResult, "result" | "error">): string;
|
|
120
|
+
export declare function diffReports(base: CycleReport, head: CycleReport, options?: DiffOptions): CycleDiff;
|
|
121
|
+
/**
|
|
122
|
+
* The functions whose self cycles differ between two lists, largest change
|
|
123
|
+
* first. One whose other side is not known (see FunctionDelta) is kept, ranked
|
|
124
|
+
* by the side that is.
|
|
125
|
+
*/
|
|
126
|
+
export declare function functionDeltas(base: FunctionResult[] | undefined, head: FunctionResult[]): FunctionDelta[];
|
|
127
|
+
/**
|
|
128
|
+
* Whether the diff should fail a check, per the options it was made with. A
|
|
129
|
+
* scenario the head could not run always fails; one the base could not run
|
|
130
|
+
* fails whenever a threshold is set, since nothing in it was checked.
|
|
131
|
+
*/
|
|
132
|
+
export declare function diffFailed(diff: CycleDiff, options?: DiffOptions): boolean;
|
|
133
|
+
/** One line saying what matters, for the top of a comment or terminal output. */
|
|
134
|
+
export declare function summarize(diff: CycleDiff): string;
|
|
135
|
+
/** How many changed functions a comment lists per group. */
|
|
136
|
+
export declare const FUNCTIONS_SHOWN = 10;
|
|
137
|
+
/** The hidden marker that identifies the sticky comment, so it is updated instead of duplicated. */
|
|
138
|
+
export declare const COMMENT_MARKER = "<!-- ckb-cycles-report -->";
|
|
139
|
+
export interface MarkdownOptions {
|
|
140
|
+
title?: string;
|
|
141
|
+
/** e.g. a short commit hash, shown in the header line. */
|
|
142
|
+
baseLabel?: string;
|
|
143
|
+
headLabel?: string;
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* A markdown comment: what changed in a table, unchanged groups folded away.
|
|
147
|
+
* Result changes come first, since an accept turning into a reject (or the
|
|
148
|
+
* reverse) matters more than any cycle count.
|
|
149
|
+
*/
|
|
150
|
+
export declare function formatMarkdown(diff: CycleDiff, options?: MarkdownOptions): string;
|
|
151
|
+
/** The same table for a terminal. */
|
|
152
|
+
export declare function formatText(diff: CycleDiff): string;
|