ckb-cycle-tools 1.0.0 → 1.2.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 CHANGED
@@ -2,21 +2,24 @@
2
2
  import { mkdir, readFile, writeFile } from "node:fs/promises";
3
3
  import { join } from "node:path";
4
4
  import { parseArgs } from "node:util";
5
- import { diffFailed, diffReports, formatMarkdown, formatText } from "./diff.js";
5
+ import { diffFailed, diffReports, formatMarkdown, formatText, termLine, termLines } from "./diff.js";
6
6
  import { buildMockTransaction, httpRpc, mockFromTransaction } from "./mock.js";
7
7
  import { flameTree, foldedTotal, formatFolded, functionCosts, renderFlameSvg } from "./flame.js";
8
8
  import { flameTransaction, parseNames, profileTransaction, readTransactionJson } from "./profile.js";
9
9
  import { PUBLIC_RPC } from "./replay.js";
10
10
  import { formatReport, runReport } from "./report.js";
11
+ import { formatScan, scanTestMocks } from "./scan.js";
11
12
  const USAGE = `usage: ckb-cycles <tx-hash> [--mainnet] [--rpc <url>] [--timeout <s>] [--debugger <path>]
12
13
  [--json] [--name <code-hash>[:<hash-type>]=<label> ...]
13
14
  ckb-cycles --file <tx.json> [same options]
14
15
  ckb-cycles report <cycles.json> [--json <out.json>] [--binaries-from <dir>]
15
16
  [--root <dir> ...] [--rpc <url>] [--timeout <s>] [--debugger <path>]
16
17
  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
+ [--fail-on-result-change] [--allow-removed] [--title <s>]
19
+ [--base-label <s>] [--head-label <s>]
18
20
  ckb-cycles mock <tx-hash> | --file <tx.json> [-o <mock.json>] [--mainnet] [--rpc <url>]
19
21
  [--timeout <s>]
22
+ ckb-cycles scan <mocks-dir> [--binaries <dir>] [-o <cycles.json>] [--functions]
20
23
  ckb-cycles flame <tx-hash> | --file <tx.json> [-o <dir>] [--script <selector> ...]
21
24
  [--bin <code-hash>=<elf> ...] [--top <n>] [--mainnet] [--rpc <url>] [--debugger <path>]
22
25
 
@@ -46,19 +49,33 @@ Exit codes: 0 every script accepts (and the sum matches the node's)
46
49
  "functions" also records the group's costliest functions.
47
50
  --root <dir> (repeatable) refuses any file the config names
48
51
  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
+ the cycles.json comes from a pull request;
53
+ its "rpc" is then ignored (--rpc still applies)
54
+ Exits 2 if a scenario could not run, or a binary matched no
55
+ cell dep in any scenario (both also in the JSON's "errors"):
56
+ a rejection is a result, not an error. A binary missing from
57
+ --binaries-from is left as the mock has it: only the groups
58
+ whose code it is are marked, and not compared
52
59
  diff compares two reports group by group: Δ cycles, Δ%, and any group
53
60
  whose result changed (ok → exit 12, or back). --fail-above exits 1
54
61
  when a group grows by more than that percentage (a new group
55
62
  has no base, so no percentage: it is never over the threshold),
56
63
  --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
64
+ group that does not accept, or a group the VM stopped (also
65
+ over any --fail-above). A scenario the head could not run
66
+ always exits 1. With either flag set, so does anything left
67
+ unchecked: a scenario the base could not run, an error in
68
+ either report, a base group with nothing in the head to
69
+ compare with (removed, renamed, moved, or its binary not built
70
+ on the base); --allow-removed accepts the last
60
71
  mock saves a transaction as a ckb-debugger mock transaction, every cell
61
72
  it touches included, so a scenario can replay it with no node
73
+ scan writes a cycles.json from the mock transactions a test suite wrote
74
+ (ckb-testtool with CKB_CYCLES_MOCKS set, see integrations/ckb-testtool):
75
+ one scenario per file, and each file in --binaries (default
76
+ build/release) that a test deployed, matched by its data hash, with
77
+ <name>.debug as its symbols build. --functions records each group's
78
+ costliest functions. -o defaults to cycles.json
62
79
  flame where inside each script the cycles go: ckb-debugger's flamegraph
63
80
  mode per script group. Prints the costliest functions and writes
64
81
  <dir>/<selector>.svg and .folded (for speedscope or inferno), in
@@ -73,7 +90,7 @@ function table(p) {
73
90
  const total = p.measuredCycles || 1n;
74
91
  const rows = p.groups.map((g) => [
75
92
  g.role,
76
- g.name ?? short(g.codeHash),
93
+ termLine(g.name ?? short(g.codeHash)),
77
94
  g.selector,
78
95
  g.error ? "error" : g.result === 0 ? "ok" : `exit ${g.result}`,
79
96
  fmt(g.cycles),
@@ -92,11 +109,11 @@ function table(p) {
92
109
  else if (p.status === "committed") {
93
110
  out.push("reported by node not recorded by this node (try another with --rpc)");
94
111
  }
95
- out.push(`${p.env.debugger} · CKB-VM v${p.env.scriptVersion} for type scripts · ${p.env.network} · ${p.env.rpcUrl}`);
112
+ out.push(`${termLine(p.env.debugger)} · CKB-VM v${p.env.scriptVersion} for type scripts · ${p.env.network} · ${p.env.rpcUrl}`);
96
113
  for (const g of p.groups.filter((g) => g.error))
97
- out.push("", `${g.selector} stopped: ${g.error}`);
114
+ out.push("", `${g.selector} stopped: ${termLine(g.error)}`);
98
115
  for (const g of p.groups.filter((g) => g.logs.length)) {
99
- out.push("", `${g.selector} logged:`, ...g.logs.map((l) => ` ${l}`));
116
+ out.push("", `${g.selector} logged:`, ...g.logs.map((l) => ` ${termLine(l)}`));
100
117
  }
101
118
  return out.join("\n");
102
119
  }
@@ -133,14 +150,18 @@ async function reportCommand(args) {
133
150
  ...(values.debugger && { debuggerPath: values.debugger }),
134
151
  ...(values["binaries-from"] && { binariesRoot: values["binaries-from"] }),
135
152
  ...(values.root && { roots: values.root }),
136
- onScenario: (s) => console.error(`${s.error ? "✗" : "·"} ${s.name}`),
153
+ onScenario: (s) => console.error(`${s.error ? "✗" : "·"} ${termLine(s.name)}`),
137
154
  });
138
- const { errors, ...data } = report;
155
+ const { errors, notices, ...data } = report;
156
+ // The errors go in the JSON too: a gated diff fails on them, so a CI step that
157
+ // ignores this exit code (the Action's `|| true`) still gets the verdict.
139
158
  if (values.json)
140
- await writeFile(values.json, toJson(data) + "\n");
159
+ await writeFile(values.json, toJson({ ...data, ...(errors.length && { errors }) }) + "\n");
141
160
  console.log(formatReport(data));
161
+ for (const n of notices ?? [])
162
+ console.error(`warning: ${termLine(n)}`);
142
163
  for (const e of errors)
143
- console.error(`error: ${e}`);
164
+ console.error(`error: ${termLines(e)}`);
144
165
  return errors.length ? 2 : 0;
145
166
  }
146
167
  async function readReport(path) {
@@ -157,6 +178,7 @@ async function diffCommand(args) {
157
178
  markdown: { type: "boolean" },
158
179
  "fail-above": { type: "string" },
159
180
  "fail-on-result-change": { type: "boolean" },
181
+ "allow-removed": { type: "boolean" },
160
182
  "base-label": { type: "string" },
161
183
  "head-label": { type: "string" },
162
184
  title: { type: "string" },
@@ -171,7 +193,11 @@ async function diffCommand(args) {
171
193
  console.error("error: --fail-above expects a percentage, e.g. 5");
172
194
  return 2;
173
195
  }
174
- const options = { ...(failAbove !== undefined && { failAbove }), failOnResultChange: values["fail-on-result-change"] };
196
+ const options = {
197
+ ...(failAbove !== undefined && { failAbove }),
198
+ failOnResultChange: values["fail-on-result-change"],
199
+ allowRemoved: values["allow-removed"],
200
+ };
175
201
  const diff = diffReports(await readReport(positionals[0]), await readReport(positionals[1]), options);
176
202
  console.log(values.markdown
177
203
  ? formatMarkdown(diff, {
@@ -209,6 +235,29 @@ async function mockCommand(args) {
209
235
  console.log(toJson(mock));
210
236
  return 0;
211
237
  }
238
+ async function scanCommand(args) {
239
+ const { values, positionals } = parseArgs({
240
+ args,
241
+ allowPositionals: true,
242
+ options: {
243
+ binaries: { type: "string" },
244
+ out: { type: "string", short: "o" },
245
+ functions: { type: "boolean" },
246
+ },
247
+ });
248
+ if (positionals.length !== 1) {
249
+ console.log(USAGE);
250
+ return 2;
251
+ }
252
+ const binariesDir = values.binaries ?? "build/release";
253
+ const r = await scanTestMocks(positionals[0], {
254
+ binariesDir,
255
+ ...(values.out && { out: values.out }),
256
+ ...(values.functions && { functions: true }),
257
+ });
258
+ console.error(formatScan(r, binariesDir));
259
+ return 0;
260
+ }
212
261
  /** `--bin 0xabc…=target/release/my-script` → flameTransaction's bins. */
213
262
  function parseBins(flags) {
214
263
  const bins = {};
@@ -265,14 +314,14 @@ async function flameCommand(args) {
265
314
  const out = [`tx ${plan.hash} (${plan.status})`, ""];
266
315
  let bad = false;
267
316
  for (const g of groups) {
268
- const label = g.name ?? short(g.codeHash);
317
+ const label = termLine(g.name ?? short(g.codeHash));
269
318
  const profiled = foldedTotal(g.folded);
270
319
  out.push(`${g.selector} ${label} ${g.error ? "error" : g.result === 0 ? "ok" : `exit ${g.result}`} ${fmt(g.cycles)} cycles`);
271
320
  if (g.bin) {
272
321
  // Same cycles and the same verdict, and neither run stopped by the VM: two stopped
273
322
  // runs both report 0 cycles, which proves nothing (review, 27 Oct).
274
323
  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`}`);
324
+ out.push(` --bin ${termLine(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
325
  bad ||= !same;
277
326
  }
278
327
  if (!g.folded.size) {
@@ -282,15 +331,20 @@ async function flameCommand(args) {
282
331
  const costs = functionCosts(g.folded);
283
332
  if (costs.length === 1)
284
333
  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");
334
+ out.push(` profiled ${fmt(profiled)} cycles (loading the binary is not profiled)`);
335
+ if (g.spawned) {
336
+ const n = g.spawned;
337
+ out.push(` spawned ${n} other script${n === 1 ? "" : "s"}: ${n === 1 ? "its" : "their"} cycles are in the ${fmt(g.cycles)}, not in this profile`, " (ckb-debugger profiles only the spawning script; --bin replaces only its binary)");
338
+ }
339
+ out.push(" SELF TOTAL FUNCTION");
286
340
  for (const c of costs.slice(0, top))
287
- out.push(` ${fmt(c.self).padStart(10)} ${fmt(c.total).padStart(10)} ${c.name}`);
341
+ out.push(` ${fmt(c.self).padStart(10)} ${fmt(c.total).padStart(10)} ${termLine(c.name)}`);
288
342
  const base = join(dir, g.selector);
289
343
  await writeFile(`${base}.folded`, formatFolded(g.folded) + "\n");
290
344
  await writeFile(`${base}.svg`, renderFlameSvg(flameTree(g.folded, g.selector), { title: `${g.selector} · ${label}` }));
291
345
  out.push(` → ${base}.svg, ${base}.folded`, "");
292
346
  }
293
- out.push(`${version} · CKB-VM v${plan.scriptVersion} for type scripts · ${plan.network} · ${plan.rpcUrl}`);
347
+ out.push(`${termLine(version)} · CKB-VM v${plan.scriptVersion} for type scripts · ${plan.network} · ${plan.rpcUrl}`);
294
348
  console.log(out.join("\n"));
295
349
  return bad || groups.some((g) => g.result !== 0) ? 1 : 0;
296
350
  }
@@ -304,6 +358,8 @@ async function main() {
304
358
  return mockCommand(rest);
305
359
  if (command === "flame")
306
360
  return flameCommand(rest);
361
+ if (command === "scan")
362
+ return scanCommand(rest);
307
363
  const { values, positionals } = parseArgs({
308
364
  allowPositionals: true,
309
365
  options: {
@@ -349,6 +405,6 @@ async function main() {
349
405
  // anything thrown is the tool not getting that far: 2, so a CI job asserting a
350
406
  // rejection with `test $? = 1` does not pass when the node is down.
351
407
  main().then((code) => process.exit(code), (e) => {
352
- console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
408
+ console.error(`error: ${termLines(e instanceof Error ? e.message : String(e))}`);
353
409
  process.exit(2);
354
410
  });
package/dist/diff.d.ts CHANGED
@@ -11,6 +11,12 @@ export interface CycleReport {
11
11
  /** ckb-debugger's `--version`, so two reports can be checked for comparability. */
12
12
  debugger?: string;
13
13
  scenarios: ScenarioResult[];
14
+ /**
15
+ * What made `report` exit 2, beyond the scenarios' own errors: a binary that
16
+ * matched no cell dep in any scenario, so nothing measured it. A gated diff
17
+ * fails on these, from either side.
18
+ */
19
+ errors?: string[];
14
20
  }
15
21
  export interface ScenarioResult {
16
22
  name: string;
@@ -19,12 +25,19 @@ export interface ScenarioResult {
19
25
  groups: GroupResult[];
20
26
  /** Warnings from binary substitution, kept so a reader can tell why a result changed. */
21
27
  warnings?: string[];
28
+ /** The binaries swapped into this scenario. */
29
+ substituted?: string[];
30
+ /** Binaries offered to this scenario (it lists none) that match none of its cell deps. */
31
+ unmatched?: string[];
22
32
  /**
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.
33
+ * A binary the scenario was offered does not exist where `--binaries-from`
34
+ * points (`missingBinaries` names them). The scenario ran with the others;
35
+ * the groups whose code is a missing one carry `missingBinary` and are not
36
+ * compared. (A report before 1.1.0 set this with `error` instead, and no
37
+ * groups: then every head group of the scenario counts as new.)
26
38
  */
27
39
  binaryMissing?: boolean;
40
+ missingBinaries?: string[];
28
41
  }
29
42
  export interface GroupResult {
30
43
  /** ckb-debugger's selector, e.g. `input.0.lock`: the key a group is matched by across reports. */
@@ -37,7 +50,13 @@ export interface GroupResult {
37
50
  /** The script's exit code: 0 accepts. -1 with `error` when the VM stopped it. */
38
51
  result: number;
39
52
  error?: string;
53
+ /** Cycles; 0 when the VM stopped the script (`error`), whose count is not a cost. */
40
54
  cycles: number;
55
+ /**
56
+ * The binary this group's code stands for was not in the checkout (the base):
57
+ * its numbers are the mock's code, not that build's, so it is not compared.
58
+ */
59
+ missingBinary?: string;
41
60
  /**
42
61
  * The costliest functions of the run, heaviest self first (at most
43
62
  * FUNCTION_LIMIT). Only for a group whose binary has a `symbols` build.
@@ -45,6 +64,14 @@ export interface GroupResult {
45
64
  functions?: FunctionResult[];
46
65
  /** Why `functions` were not recorded although asked for (the symbols build costs other cycles…). */
47
66
  functionsWarning?: string;
67
+ /**
68
+ * How many scripts this one spawned (CKB2023 `spawn`), seen by the run that
69
+ * recorded `functions`. Their cycles are in `cycles`, but `functions` cover
70
+ * only this script: ckb-debugger profiles the root VM alone.
71
+ */
72
+ spawned?: number;
73
+ /** With `spawned`: the cycles the function profile covers (the root script's own run). */
74
+ profiled?: number;
48
75
  }
49
76
  export interface FunctionResult {
50
77
  name: string;
@@ -94,6 +121,12 @@ export interface DiffRow {
94
121
  functions?: FunctionDelta[];
95
122
  /** The head's reason for not recording functions. */
96
123
  functionsWarning?: string;
124
+ /** The head's script spawned this many others, whose cycles no function accounts for. */
125
+ spawned?: number;
126
+ /** With `spawned`: the cycles the head's function profile covers. */
127
+ profiled?: number;
128
+ /** Why the base side of this group was not compared (its binary was not in the base checkout). */
129
+ notCompared?: string;
97
130
  }
98
131
  export interface CycleDiff {
99
132
  rows: DiffRow[];
@@ -107,6 +140,26 @@ export interface CycleDiff {
107
140
  overThreshold: number;
108
141
  /** Scenarios the base could not run: their head groups had nothing to be compared with. */
109
142
  baseErrors: number;
143
+ /**
144
+ * Base groups with nothing in the head to be compared with: removed, renamed
145
+ * or moved (another scenario name or selector), or measured without their
146
+ * binary (`notCompared`). A gated diff fails on them unless `allowRemoved`.
147
+ */
148
+ removed: number;
149
+ /** Head groups with no base group. Reported, never a failure on their own. */
150
+ newGroups: number;
151
+ /** Either report's own errors (`base: ...`, `head: ...`): a gated diff fails on them. */
152
+ reportErrors: string[];
153
+ /** The head's scenario warnings, for the comment. */
154
+ warnings: {
155
+ scenario: string;
156
+ text: string;
157
+ }[];
158
+ /** Set when the two reports name different ckb-debugger versions. */
159
+ debuggers?: {
160
+ base: string;
161
+ head: string;
162
+ };
110
163
  threshold?: number;
111
164
  }
112
165
  export interface DiffOptions {
@@ -114,8 +167,16 @@ export interface DiffOptions {
114
167
  failAbove?: number;
115
168
  /** A changed outcome makes `failed` true. */
116
169
  failOnResultChange?: boolean;
170
+ /** Removed, renamed or uncompared base groups do not fail a gated diff. */
171
+ allowRemoved?: boolean;
117
172
  }
118
- /** `ok`, `exit 12`, or `error` (the VM stopped the script). */
173
+ /** The message for a binary no scenario's cell deps match, in a report's `errors` and the diff. */
174
+ export declare const unmatchedError: (name: string) => string;
175
+ /**
176
+ * `ok`, `exit 12`, or `error: <kind>` when the VM stopped the script: the
177
+ * debugger's message without its `key=value` details (a pc, an instruction),
178
+ * so "invalid instruction" and "max cycles exceeded" are different results.
179
+ */
119
180
  export declare function resultLabel(g: Pick<GroupResult, "result" | "error">): string;
120
181
  export declare function diffReports(base: CycleReport, head: CycleReport, options?: DiffOptions): CycleDiff;
121
182
  /**
@@ -126,14 +187,39 @@ export declare function diffReports(base: CycleReport, head: CycleReport, option
126
187
  export declare function functionDeltas(base: FunctionResult[] | undefined, head: FunctionResult[]): FunctionDelta[];
127
188
  /**
128
189
  * 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.
190
+ * scenario the head could not run always fails. With a gate set (either
191
+ * option), so does anything that was not checked: a scenario the base could not
192
+ * run, an error in either report, and a base group with nothing to compare
193
+ * against (removed, renamed, moved, or measured without its binary) unless
194
+ * `allowRemoved`. A head group the VM stopped is a result change, and over any
195
+ * `failAbove` threshold.
131
196
  */
132
197
  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;
198
+ /**
199
+ * One line saying what matters, for the top of a comment or terminal output.
200
+ * Text from the reports in it (debugger versions) goes through `clean`:
201
+ * termLine by default, the markdown escape in a comment.
202
+ */
203
+ export declare function summarize(diff: CycleDiff, clean?: (s: string) => string): string;
204
+ /**
205
+ * Text from a config, a build or a node (scenario, script and function names,
206
+ * warnings) for a terminal or a CI log: oneLine, and never `::` at the start of
207
+ * a line, which GitHub Actions would run as a workflow command (`::error::`,
208
+ * `::add-mask::`, `::stop-commands::`); a zero-width space breaks it.
209
+ */
210
+ export declare const termLine: (s: string) => string;
211
+ /** termLine for text that keeps its line breaks (a debugger's output in an error): each line cleaned the same way. */
212
+ export declare const termLines: (s: string) => string;
135
213
  /** How many changed functions a comment lists per group. */
136
214
  export declare const FUNCTIONS_SHOWN = 10;
215
+ /** What a function list leaves out when the script spawned others: their cycles. */
216
+ export declare function spawnNote(r: {
217
+ spawned?: number;
218
+ profiled?: number;
219
+ head?: {
220
+ cycles?: number;
221
+ };
222
+ }): string;
137
223
  /** The hidden marker that identifies the sticky comment, so it is updated instead of duplicated. */
138
224
  export declare const COMMENT_MARKER = "<!-- ckb-cycles-report -->";
139
225
  export interface MarkdownOptions {