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/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;
@@ -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;