ckb-cycle-tools 1.0.0 → 1.1.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) {
@@ -284,13 +333,13 @@ async function flameCommand(args) {
284
333
  out.push(" one frame: the binary has no symbols. Pass an unstripped build with --bin <code-hash>=<elf>");
285
334
  out.push(` profiled ${fmt(profiled)} cycles (loading the binary is not profiled)`, " SELF TOTAL FUNCTION");
286
335
  for (const c of costs.slice(0, top))
287
- out.push(` ${fmt(c.self).padStart(10)} ${fmt(c.total).padStart(10)} ${c.name}`);
336
+ out.push(` ${fmt(c.self).padStart(10)} ${fmt(c.total).padStart(10)} ${termLine(c.name)}`);
288
337
  const base = join(dir, g.selector);
289
338
  await writeFile(`${base}.folded`, formatFolded(g.folded) + "\n");
290
339
  await writeFile(`${base}.svg`, renderFlameSvg(flameTree(g.folded, g.selector), { title: `${g.selector} · ${label}` }));
291
340
  out.push(` → ${base}.svg, ${base}.folded`, "");
292
341
  }
293
- out.push(`${version} · CKB-VM v${plan.scriptVersion} for type scripts · ${plan.network} · ${plan.rpcUrl}`);
342
+ out.push(`${termLine(version)} · CKB-VM v${plan.scriptVersion} for type scripts · ${plan.network} · ${plan.rpcUrl}`);
294
343
  console.log(out.join("\n"));
295
344
  return bad || groups.some((g) => g.result !== 0) ? 1 : 0;
296
345
  }
@@ -304,6 +353,8 @@ async function main() {
304
353
  return mockCommand(rest);
305
354
  if (command === "flame")
306
355
  return flameCommand(rest);
356
+ if (command === "scan")
357
+ return scanCommand(rest);
307
358
  const { values, positionals } = parseArgs({
308
359
  allowPositionals: true,
309
360
  options: {
@@ -349,6 +400,6 @@ async function main() {
349
400
  // anything thrown is the tool not getting that far: 2, so a CI job asserting a
350
401
  // rejection with `test $? = 1` does not pass when the node is down.
351
402
  main().then((code) => process.exit(code), (e) => {
352
- console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
403
+ console.error(`error: ${termLines(e instanceof Error ? e.message : String(e))}`);
353
404
  process.exit(2);
354
405
  });
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.
@@ -94,6 +113,8 @@ export interface DiffRow {
94
113
  functions?: FunctionDelta[];
95
114
  /** The head's reason for not recording functions. */
96
115
  functionsWarning?: string;
116
+ /** Why the base side of this group was not compared (its binary was not in the base checkout). */
117
+ notCompared?: string;
97
118
  }
98
119
  export interface CycleDiff {
99
120
  rows: DiffRow[];
@@ -107,6 +128,26 @@ export interface CycleDiff {
107
128
  overThreshold: number;
108
129
  /** Scenarios the base could not run: their head groups had nothing to be compared with. */
109
130
  baseErrors: number;
131
+ /**
132
+ * Base groups with nothing in the head to be compared with: removed, renamed
133
+ * or moved (another scenario name or selector), or measured without their
134
+ * binary (`notCompared`). A gated diff fails on them unless `allowRemoved`.
135
+ */
136
+ removed: number;
137
+ /** Head groups with no base group. Reported, never a failure on their own. */
138
+ newGroups: number;
139
+ /** Either report's own errors (`base: ...`, `head: ...`): a gated diff fails on them. */
140
+ reportErrors: string[];
141
+ /** The head's scenario warnings, for the comment. */
142
+ warnings: {
143
+ scenario: string;
144
+ text: string;
145
+ }[];
146
+ /** Set when the two reports name different ckb-debugger versions. */
147
+ debuggers?: {
148
+ base: string;
149
+ head: string;
150
+ };
110
151
  threshold?: number;
111
152
  }
112
153
  export interface DiffOptions {
@@ -114,8 +155,16 @@ export interface DiffOptions {
114
155
  failAbove?: number;
115
156
  /** A changed outcome makes `failed` true. */
116
157
  failOnResultChange?: boolean;
158
+ /** Removed, renamed or uncompared base groups do not fail a gated diff. */
159
+ allowRemoved?: boolean;
117
160
  }
118
- /** `ok`, `exit 12`, or `error` (the VM stopped the script). */
161
+ /** The message for a binary no scenario's cell deps match, in a report's `errors` and the diff. */
162
+ export declare const unmatchedError: (name: string) => string;
163
+ /**
164
+ * `ok`, `exit 12`, or `error: <kind>` when the VM stopped the script: the
165
+ * debugger's message without its `key=value` details (a pc, an instruction),
166
+ * so "invalid instruction" and "max cycles exceeded" are different results.
167
+ */
119
168
  export declare function resultLabel(g: Pick<GroupResult, "result" | "error">): string;
120
169
  export declare function diffReports(base: CycleReport, head: CycleReport, options?: DiffOptions): CycleDiff;
121
170
  /**
@@ -126,12 +175,29 @@ export declare function diffReports(base: CycleReport, head: CycleReport, option
126
175
  export declare function functionDeltas(base: FunctionResult[] | undefined, head: FunctionResult[]): FunctionDelta[];
127
176
  /**
128
177
  * 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.
178
+ * scenario the head could not run always fails. With a gate set (either
179
+ * option), so does anything that was not checked: a scenario the base could not
180
+ * run, an error in either report, and a base group with nothing to compare
181
+ * against (removed, renamed, moved, or measured without its binary) unless
182
+ * `allowRemoved`. A head group the VM stopped is a result change, and over any
183
+ * `failAbove` threshold.
131
184
  */
132
185
  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;
186
+ /**
187
+ * One line saying what matters, for the top of a comment or terminal output.
188
+ * Text from the reports in it (debugger versions) goes through `clean`:
189
+ * termLine by default, the markdown escape in a comment.
190
+ */
191
+ export declare function summarize(diff: CycleDiff, clean?: (s: string) => string): string;
192
+ /**
193
+ * Text from a config, a build or a node (scenario, script and function names,
194
+ * warnings) for a terminal or a CI log: oneLine, and never `::` at the start of
195
+ * a line, which GitHub Actions would run as a workflow command (`::error::`,
196
+ * `::add-mask::`, `::stop-commands::`); a zero-width space breaks it.
197
+ */
198
+ export declare const termLine: (s: string) => string;
199
+ /** termLine for text that keeps its line breaks (a debugger's output in an error): each line cleaned the same way. */
200
+ export declare const termLines: (s: string) => string;
135
201
  /** How many changed functions a comment lists per group. */
136
202
  export declare const FUNCTIONS_SHOWN = 10;
137
203
  /** The hidden marker that identifies the sticky comment, so it is updated instead of duplicated. */