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/profile.js CHANGED
@@ -1,10 +1,11 @@
1
1
  import { execFile } from "node:child_process";
2
- import { mkdtemp, rm, writeFile } from "node:fs/promises";
2
+ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
3
3
  import { tmpdir } from "node:os";
4
4
  import { join } from "node:path";
5
5
  import { promisify } from "node:util";
6
6
  import { checkDebuggerPath, resolveDebugger } from "./debugger.js";
7
- import { parseFolded } from "./flame.js";
7
+ import { elfFunctionNames } from "./elf.js";
8
+ import { nameAddresses, parseFolded } from "./flame.js";
8
9
  import { debuggerArgs, parseDebuggerRun, planReplay, replayGroups, selectorFor, TYPE_ID_CODE_HASH, } from "./replay.js";
9
10
  // The pure parts live in replay.ts, shared with the browser; existing imports keep working.
10
11
  export { checkTypeId, parseDebuggerOutput, parseDebuggerRun, parseNames, readTransactionJson, selectorFor, TYPE_ID_CODE_HASH, TYPE_ID_CYCLES, } from "./replay.js";
@@ -72,7 +73,10 @@ export async function profileTransaction(target, options = {}) {
72
73
  * code hash to an unstripped build of that script, used instead of the
73
74
  * deployed (stripped) binary so the frames have names; each such group is also
74
75
  * run with the deployed binary, to check the build behaves the same.
75
- * `scripts` limits the run to those selectors (`input.0.lock`, …).
76
+ * `scripts` limits the run to those selectors (`input.0.lock`, …). `readFile`
77
+ * reads the folded stacks the debugger wrote, and `readBinary` (node:fs when
78
+ * not given) the builds, for their symbol tables: both see the files where
79
+ * `runDebugger` does.
76
80
  */
77
81
  export async function flameTransaction(target, options) {
78
82
  const { exec, version: debuggerVersion } = await debuggerOf(options);
@@ -83,6 +87,15 @@ export async function flameTransaction(target, options) {
83
87
  const txFile = join(dir, "tx.json");
84
88
  await writeFile(txFile, JSON.stringify(plan.mock));
85
89
  const groups = [];
90
+ // Frames the profiler could not name from line info get their names from the build's symbol table,
91
+ // read and parsed once per build however many groups run it.
92
+ const readBinary = options.readBinary ?? ((path) => readFile(path).then((b) => new Uint8Array(b)));
93
+ const symbols = new Map();
94
+ const namesOf = (bin) => {
95
+ if (!symbols.has(bin))
96
+ symbols.set(bin, readBinary(bin).then(elfFunctionNames, () => new Map()));
97
+ return symbols.get(bin);
98
+ };
86
99
  for (const g of plan.groups) {
87
100
  const selector = selectorFor(g);
88
101
  if (options.scripts && !options.scripts.includes(selector))
@@ -99,7 +112,8 @@ export async function flameTransaction(target, options) {
99
112
  "--flamegraph-output",
100
113
  out,
101
114
  ]);
102
- const folded = parseFolded(await options.readFile(out).catch(() => ""));
115
+ const names = bin ? await namesOf(bin) : new Map();
116
+ const folded = nameAddresses(parseFolded(await options.readFile(out).catch(() => "")), names);
103
117
  // Flamegraph mode leaves out loading the binary, so result and cycles come
104
118
  // from plain runs: with the build, and with the deployed binary to compare.
105
119
  const parsed = runOut.exitCode === null ? parseDebuggerRun(runOut) : parseDebuggerRun(await exec([...base, ...(bin ? ["--bin", bin] : [])]));
package/dist/replay.d.ts CHANGED
@@ -112,7 +112,20 @@ export interface ReplayPlan {
112
112
  network: string;
113
113
  rpcUrl: string;
114
114
  }
115
- /** The script groups that run for a mock transaction, in first-appearance order. A cellbase runs none. */
115
+ /**
116
+ * Refuses a mock transaction that ckb-debugger would read as more than data.
117
+ * The debugger expands `{{ data <path> }}`, `{{ hash <path> }}`, `{{ def_type … }}`
118
+ * and `{{ ref_type … }}` in a tx file before parsing it (mock_tx_embed.rs), so
119
+ * such a string embeds any file on the machine that runs it, past `--root`.
120
+ * Every string must be hex (`0x…`), except `hash_type` and `dep_type`, which
121
+ * must be one of their names. Called on every mock before it is written for a
122
+ * debugger (groupsOf, so planReplay, profile, flame and report; wasmRunner).
123
+ */
124
+ export declare function checkMockTransaction(mock: unknown): void;
125
+ /**
126
+ * The script groups that run for a mock transaction, in first-appearance order.
127
+ * A cellbase runs none. A mock checkMockTransaction refuses is an error.
128
+ */
116
129
  export declare function groupsOf(mock: MockTransaction): ScriptGroup[];
117
130
  /**
118
131
  * Fetches what a replay needs: a committed transaction by hash (with the node's
package/dist/replay.js CHANGED
@@ -55,7 +55,8 @@ export function parseDebuggerOutput(out) {
55
55
  if (/^-?\d+$/.test(result) && cycles !== undefined)
56
56
  return { result: Number(result), cycles: BigInt(cycles), logs };
57
57
  // The VM stopped the script (invalid instruction, cycle limit, bad ELF…): a rejection, not a crash.
58
- return { result: -1, error: result.replace(CONTROL, "�"), cycles: cycles === undefined ? 0n : BigInt(cycles), logs };
58
+ // Never its cycles: a stopped run's count is not what the script costs (0, or wherever the VM gave up).
59
+ return { result: -1, error: result.replace(CONTROL, "�"), cycles: 0n, logs };
59
60
  }
60
61
  /**
61
62
  * Reads one run: its final result lines (parseDebuggerOutput), checked against
@@ -106,8 +107,49 @@ export function checkTypeId(g, tx) {
106
107
  const expected = ccc.hashCkb(ccc.bytesConcat(ccc.numLeToBytes(BigInt(first.since), 8), ccc.bytesFrom(first.previous_output.tx_hash), ccc.numLeToBytes(Number(first.previous_output.index), 4), ccc.numLeToBytes(g.outputs[0], 8)));
107
108
  return expected === g.args.toLowerCase() ? undefined : "type id: args do not match the first input";
108
109
  }
109
- /** The script groups that run for a mock transaction, in first-appearance order. A cellbase runs none. */
110
+ /** The string fields of a mock transaction that are names, not hex. */
111
+ const NAME_FIELDS = { hash_type: /^(type|data[0-9]*)$/, dep_type: /^(code|dep_group)$/ };
112
+ /**
113
+ * Refuses a mock transaction that ckb-debugger would read as more than data.
114
+ * The debugger expands `{{ data <path> }}`, `{{ hash <path> }}`, `{{ def_type … }}`
115
+ * and `{{ ref_type … }}` in a tx file before parsing it (mock_tx_embed.rs), so
116
+ * such a string embeds any file on the machine that runs it, past `--root`.
117
+ * Every string must be hex (`0x…`), except `hash_type` and `dep_type`, which
118
+ * must be one of their names. Called on every mock before it is written for a
119
+ * debugger (groupsOf, so planReplay, profile, flame and report; wasmRunner).
120
+ */
121
+ export function checkMockTransaction(mock) {
122
+ const refuse = (path, why) => {
123
+ throw new Error(`mock transaction refused: ${path} ${why}`);
124
+ };
125
+ const walk = (v, path, key) => {
126
+ if (typeof v === "string") {
127
+ if (v.includes("{{")) {
128
+ refuse(path, `contains "{{", a ckb-debugger template directive that reads files from the machine running it`);
129
+ }
130
+ const name = NAME_FIELDS[key];
131
+ if (name ? !name.test(v) : !/^0x[0-9a-fA-F]*$/.test(v))
132
+ refuse(path, name ? `is not a ${key}` : "is not 0x-prefixed hex");
133
+ }
134
+ else if (Array.isArray(v)) {
135
+ v.forEach((x, i) => walk(x, `${path}[${i}]`, key));
136
+ }
137
+ else if (v && typeof v === "object") {
138
+ for (const [k, x] of Object.entries(v)) {
139
+ if (k.includes("{{"))
140
+ refuse(path, `has a key containing "{{", a ckb-debugger template directive`);
141
+ walk(x, /^[A-Za-z_]\w*$/.test(k) ? `${path}.${k}` : `${path}[${JSON.stringify(k)}]`, k);
142
+ }
143
+ }
144
+ };
145
+ walk(mock, "mock", "");
146
+ }
147
+ /**
148
+ * The script groups that run for a mock transaction, in first-appearance order.
149
+ * A cellbase runs none. A mock checkMockTransaction refuses is an error.
150
+ */
110
151
  export function groupsOf(mock) {
152
+ checkMockTransaction(mock);
111
153
  if (isCellbase(mock.tx))
112
154
  return [];
113
155
  return groupScripts(mock.mock_info.inputs.map((c) => ({ lock: toScript(c.output.lock), type: c.output.type && toScript(c.output.type) })), mock.tx.outputs.map((o) => ({ lock: toScript(o.lock), type: o.type && toScript(o.type) })));
package/dist/report.d.ts CHANGED
@@ -73,6 +73,7 @@ export declare function groupResults(p: Profile): GroupResult[];
73
73
  */
74
74
  export declare function runReport(configPath: string, options?: ReportOptions): Promise<CycleReport & {
75
75
  errors: string[];
76
+ notices?: string[];
76
77
  }>;
77
78
  /**
78
79
  * `file` with its symlinks resolved, when it is inside one of `roots` (already
@@ -81,5 +82,9 @@ export declare function runReport(configPath: string, options?: ReportOptions):
81
82
  * binary absent from the base is a new binary, not an error).
82
83
  */
83
84
  export declare function confine(file: string, roots: string[] | undefined): Promise<string>;
84
- /** The report for a terminal: one block per scenario. */
85
+ /**
86
+ * The report for a terminal: one block per scenario. Every name, warning and
87
+ * error from the config, the build or the debugger goes through termLine (or
88
+ * termLines), so none can start a log line of its own.
89
+ */
85
90
  export declare function formatReport(report: CycleReport): string;
package/dist/report.js CHANGED
@@ -16,12 +16,12 @@
16
16
  */
17
17
  import { readFile, realpath, stat } from "node:fs/promises";
18
18
  import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
19
- import { FUNCTION_LIMIT, resultLabel } from "./diff.js";
19
+ import { FUNCTION_LIMIT, resultLabel, termLine, termLines, unmatchedError } from "./diff.js";
20
20
  import { functionCosts } from "./flame.js";
21
21
  import { buildMockTransaction, httpRpc, mockFromTransaction, scriptVersionAt } from "./mock.js";
22
22
  import { flameTransaction, parseNames, profileTransaction, readTransactionJson } from "./profile.js";
23
23
  import { consensusOf, nodeVerdict, PUBLIC_RPC } from "./replay.js";
24
- import { substituteBinaries } from "./substitute.js";
24
+ import { substituteBinaries, targetScriptKeys } from "./substitute.js";
25
25
  const HASH = /^0x[0-9a-fA-F]{64}$/;
26
26
  /** Parses and checks a cycles.json, with a message that says what to fix. */
27
27
  export function parseCyclesConfig(json) {
@@ -113,10 +113,19 @@ export async function runReport(configPath, options = {}) {
113
113
  // Only a network the config names is checked against the node; otherwise the
114
114
  // node says which chain it serves, and its own hardfork epochs are used.
115
115
  const network = config.network;
116
- const rpcUrl = options.rpcUrl ?? config.rpc;
117
- const baseNames = parseNames(Object.entries(config.names ?? {}).map(([k, v]) => `${k}=${v}`));
118
116
  const roots = options.roots?.length ? await Promise.all(options.roots.map((r) => realpath(resolve(r)))) : undefined;
117
+ // With roots the config is untrusted (a pull request's): it does not choose
118
+ // the host the runner sends requests to. Only --rpc, or the public node.
119
+ const notices = [];
120
+ if (roots && config.rpc !== undefined && options.rpcUrl === undefined) {
121
+ notices.push(`cycles.json "rpc" ignored under --root: the config does not choose the node; pass --rpc to use another`);
122
+ }
123
+ const rpcUrl = options.rpcUrl ?? (roots ? undefined : config.rpc);
124
+ const baseNames = parseNames(Object.entries(config.names ?? {}).map(([k, v]) => `${k}=${v}`));
119
125
  const inside = (file) => confine(file, roots);
126
+ // A binary resolves to null when it is absent from another checkout (the
127
+ // base, --binaries-from): that binary is new there, not broken. Only it, and
128
+ // the groups whose code it is, count as new; every other binary still swaps in.
120
129
  const binaries = new Map();
121
130
  const binary = (name) => {
122
131
  let p = binaries.get(name);
@@ -130,18 +139,18 @@ export async function runReport(configPath, options = {}) {
130
139
  ...(b.outPoint && { outPoint: b.outPoint }),
131
140
  ...(b.codeHash && { codeHash: b.codeHash }),
132
141
  }), (e) => {
133
- const err = new Error(`binary "${name}": cannot read ${b.path} (${e.message}); build it first`);
134
- // Absent from another checkout (the base): the scenario's code is new there, not broken.
135
- if (options.binariesRoot && e.code === "ENOENT")
136
- missingBinary.add(err);
137
- throw err;
142
+ if (options.binariesRoot && e.code === "ENOENT") {
143
+ missingNames.add(name);
144
+ return null;
145
+ }
146
+ throw new Error(`binary "${name}": cannot read ${b.path} (${e.message}); build it first`);
138
147
  });
139
148
  binaries.set(name, p);
140
149
  }
141
150
  return p;
142
151
  };
143
152
  const used = new Set();
144
- const missingBinary = new WeakSet();
153
+ const missingNames = new Set();
145
154
  let debuggerVersion;
146
155
  const scenarios = [];
147
156
  for (const s of config.scenarios) {
@@ -149,7 +158,13 @@ export async function runReport(configPath, options = {}) {
149
158
  try {
150
159
  const explicit = s.binaries !== undefined;
151
160
  const names = explicit ? s.binaries : Object.keys(config.binaries ?? {});
152
- const subs = await Promise.all(names.map(binary));
161
+ const loaded = await Promise.all(names.map(binary));
162
+ const subs = loaded.filter((b) => b !== null);
163
+ const missing = names.filter((_, i) => loaded[i] === null);
164
+ /** `codeHash:hashType` (lower case) → the missing binary that code stands for. */
165
+ const missingKeys = new Map();
166
+ const substituted = [];
167
+ const unmatched = [];
153
168
  const profileOptions = {
154
169
  ...(network && { network }),
155
170
  ...(rpcUrl && { rpcUrl }),
@@ -161,7 +176,7 @@ export async function runReport(configPath, options = {}) {
161
176
  let profile;
162
177
  let groups;
163
178
  const warnings = [];
164
- if (s.tx && !subs.length) {
179
+ if (s.tx && !subs.length && !missing.length) {
165
180
  // Nothing to swap: profile it as the CLI does, with the node's check.
166
181
  profile = await profileTransaction(s.tx, { ...profileOptions, scriptNames: baseNames });
167
182
  }
@@ -194,10 +209,24 @@ export async function runReport(configPath, options = {}) {
194
209
  const scriptNames = {};
195
210
  for (const a of applied) {
196
211
  used.add(a.name);
212
+ substituted.push(a.name);
197
213
  for (const k of a.scriptKeys)
198
214
  scriptNames[k] = a.name;
199
215
  warnings.push(...a.warnings.map((w) => `${a.name}: ${w}`));
200
216
  }
217
+ // Offered, and no cell dep here is its code: this scenario's scripts run
218
+ // the mock's own code, not this build (a mock dumped from an older build?).
219
+ for (const sub of subs) {
220
+ if (!substituted.includes(sub.name)) {
221
+ unmatched.push(sub.name);
222
+ warnings.push(`binary "${sub.name}" matches no cell dep in this scenario: any script of it here runs the mock's code, not this build (check its outPoint / codeHash, or re-dump the mock)`);
223
+ }
224
+ }
225
+ // Left as the mock has it: those groups measure the mock's code, not the build.
226
+ for (const name of missing) {
227
+ for (const k of targetScriptKeys(swapped, config.binaries[name]))
228
+ missingKeys.set(k, name);
229
+ }
201
230
  Object.assign(scriptNames, baseNames);
202
231
  profile = await profileTransaction(swapped, {
203
232
  ...profileOptions,
@@ -227,16 +256,24 @@ export async function runReport(configPath, options = {}) {
227
256
  if (nodeVerdict(profile) === "mismatch") {
228
257
  warnings.push(`the groups add up to ${profile.measuredCycles} cycles, the node reported ${profile.nodeCycles}`);
229
258
  }
230
- result = { name: s.name, groups: groups ?? groupResults(profile), ...(warnings.length && { warnings }) };
231
- }
232
- catch (e) {
259
+ groups ??= groupResults(profile);
260
+ for (const g of groups) {
261
+ const name = missingKeys.get(`${g.codeHash}:${g.hashType}`.toLowerCase());
262
+ if (name)
263
+ g.missingBinary = name;
264
+ }
233
265
  result = {
234
266
  name: s.name,
235
- error: e instanceof Error ? e.message : String(e),
236
- groups: [],
237
- ...(e instanceof Error && missingBinary.has(e) && { binaryMissing: true }),
267
+ groups,
268
+ ...(warnings.length && { warnings }),
269
+ ...(substituted.length && { substituted }),
270
+ ...(unmatched.length && { unmatched }),
271
+ ...(missing.length && { binaryMissing: true, missingBinaries: missing }),
238
272
  };
239
273
  }
274
+ catch (e) {
275
+ result = { name: s.name, error: e instanceof Error ? e.message : String(e), groups: [] };
276
+ }
240
277
  scenarios.push(result);
241
278
  options.onScenario?.(result);
242
279
  }
@@ -246,8 +283,8 @@ export async function runReport(configPath, options = {}) {
246
283
  // Only said when every scenario ran: one that failed may be the one that uses it.
247
284
  const offered = !errors.length && config.scenarios.some((s) => s.binaries === undefined) ? Object.keys(config.binaries ?? {}) : [];
248
285
  for (const name of offered) {
249
- if (!used.has(name) && !config.scenarios.some((s) => s.binaries?.includes(name))) {
250
- errors.push(`binary "${name}" matched no cell dep in any scenario: check its outPoint / codeHash`);
286
+ if (!used.has(name) && !missingNames.has(name) && !config.scenarios.some((s) => s.binaries?.includes(name))) {
287
+ errors.push(unmatchedError(name));
251
288
  }
252
289
  }
253
290
  return {
@@ -256,6 +293,7 @@ export async function runReport(configPath, options = {}) {
256
293
  ...(debuggerVersion && { debugger: debuggerVersion }),
257
294
  scenarios,
258
295
  errors,
296
+ ...(notices.length && { notices }),
259
297
  };
260
298
  }
261
299
  /**
@@ -360,37 +398,48 @@ async function realParent(p) {
360
398
  return join(await realParent(parent), basename(p));
361
399
  }
362
400
  }
363
- /** The report for a terminal: one block per scenario. */
401
+ /**
402
+ * The report for a terminal: one block per scenario. Every name, warning and
403
+ * error from the config, the build or the debugger goes through termLine (or
404
+ * termLines), so none can start a log line of its own.
405
+ */
364
406
  export function formatReport(report) {
365
407
  const fmt = (n) => n.toLocaleString("en-US");
408
+ const t = termLine;
366
409
  const rows = report.scenarios.flatMap((s) => s.error
367
- ? [[s.name, "", "", "error", ""]]
368
- : s.groups.map((g) => [s.name, g.selector, g.script, resultLabel(g), fmt(g.cycles)]));
410
+ ? [[t(s.name), "", "", "error", ""]]
411
+ : s.groups.map((g) => [t(s.name), t(g.selector), t(g.script), t(resultLabel(g)), fmt(g.cycles)]));
369
412
  const head = ["SCENARIO", "GROUP", "SCRIPT", "RESULT", "CYCLES"];
370
413
  const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
371
414
  const line = (cells) => cells.map((c, i) => (i === 4 ? c.padStart(widths[i]) : c.padEnd(widths[i]))).join(" ").trimEnd();
372
415
  const out = [line(head), ...rows.map(line)];
373
416
  for (const s of report.scenarios)
374
417
  if (s.error)
375
- out.push("", `${s.name}: ${s.error}`);
418
+ out.push("", `${t(s.name)}: ${termLines(s.error)}`);
376
419
  for (const s of report.scenarios)
377
420
  for (const w of s.warnings ?? [])
378
- out.push("", `${s.name}: warning: ${w}`);
421
+ out.push("", `${t(s.name)}: warning: ${t(w)}`);
422
+ for (const s of report.scenarios) {
423
+ for (const b of s.missingBinaries ?? []) {
424
+ const n = s.groups.filter((g) => g.missingBinary === b).length;
425
+ out.push("", `${t(s.name)}: binary ${t(b)} is not in this checkout: ${n} group${n === 1 ? "" : "s"} ran the mock's code instead, and count as not compared`);
426
+ }
427
+ }
379
428
  for (const s of report.scenarios) {
380
429
  for (const g of s.groups.filter((g) => g.error))
381
- out.push("", `${s.name} ${g.selector} stopped: ${g.error}`);
430
+ out.push("", `${t(s.name)} ${t(g.selector)} stopped: ${t(g.error)}`);
382
431
  }
383
432
  for (const s of report.scenarios) {
384
433
  for (const g of s.groups) {
385
434
  if (g.functionsWarning)
386
- out.push("", `${s.name} ${g.selector}: functions not recorded: ${g.functionsWarning}`);
435
+ out.push("", `${t(s.name)} ${t(g.selector)}: functions not recorded: ${t(g.functionsWarning)}`);
387
436
  else if (g.functions?.length) {
388
- const top = g.functions.slice(0, 3).map((f) => `${f.name} ${fmt(f.self)}`);
389
- out.push("", `${s.name} ${g.selector}: costliest functions (self cycles): ${top.join(", ")}`);
437
+ const top = g.functions.slice(0, 3).map((f) => `${t(f.name)} ${fmt(f.self)}`);
438
+ out.push("", `${t(s.name)} ${t(g.selector)}: costliest functions (self cycles): ${top.join(", ")}`);
390
439
  }
391
440
  }
392
441
  }
393
442
  if (report.debugger)
394
- out.push("", report.debugger);
443
+ out.push("", t(report.debugger));
395
444
  return out.join("\n");
396
445
  }
package/dist/scan.d.ts ADDED
@@ -0,0 +1,46 @@
1
+ import type { MockTransaction } from "./mock.js";
2
+ import type { CyclesConfig } from "./report.js";
3
+ export interface ScannedMock {
4
+ /** The scenario's name: the file name without `.json`. */
5
+ name: string;
6
+ /** Path of the file, as the config will name it. */
7
+ path: string;
8
+ mock: MockTransaction;
9
+ }
10
+ export interface ScannedBinary {
11
+ name: string;
12
+ /** Path of the binary, as the config will name it. */
13
+ path: string;
14
+ data: Uint8Array;
15
+ /** Path of `<name>.debug`, when there is one. */
16
+ symbols?: string;
17
+ }
18
+ export interface ScanResult {
19
+ config: CyclesConfig;
20
+ /** Binaries some mock deploys, by name. */
21
+ matched: string[];
22
+ /** Files in the binaries directory no mock deploys: a stale build, or a contract with no test. */
23
+ unused: string[];
24
+ /** Data hashes of code cells in the mocks that are none of the binaries (ckb-testtool's always-success, say). */
25
+ others: string[];
26
+ }
27
+ /** The cycles.json for these mocks and binaries. Pure: the caller reads the files. */
28
+ export declare function configFromMocks(mocks: ScannedMock[], binaries: ScannedBinary[], options?: {
29
+ functions?: boolean;
30
+ }): ScanResult;
31
+ export interface ScanOptions {
32
+ /** Where the contracts are built. Default `build/release`. */
33
+ binariesDir?: string;
34
+ /** The cycles.json to write; the paths in it are relative to it. Default `cycles.json`. */
35
+ out?: string;
36
+ /** Record each group's costliest functions, from the `.debug` builds. */
37
+ functions?: boolean;
38
+ }
39
+ /** Reads the mocks and the binaries, and writes the cycles.json. */
40
+ export declare function scanTestMocks(mocksDir: string, options?: ScanOptions): Promise<ScanResult & {
41
+ out: string;
42
+ }>;
43
+ /** What scan found, for stderr. */
44
+ export declare function formatScan(r: ScanResult & {
45
+ out: string;
46
+ }, binariesDir: string): string;
package/dist/scan.js ADDED
@@ -0,0 +1,122 @@
1
+ /**
2
+ * `ckb-cycles scan`: a cycles.json from the transactions a test suite wrote.
3
+ *
4
+ * The tests (Rust ckb-testtool, through integrations/ckb-testtool, or anything
5
+ * else that writes ckb-debugger mock transactions) leave one mock per
6
+ * transaction in a directory. Each becomes a `"mock"` scenario, named by its
7
+ * file. Each file in the binaries directory (a ckb-script-templates project's
8
+ * `build/release`) whose data hash is the data of a code cell dep in some mock
9
+ * becomes a binary, matched by that hash, with `<name>.debug` beside it as its
10
+ * symbols build.
11
+ *
12
+ * The hashes are those of the build the tests ran against, so the file is
13
+ * regenerated after each build rather than written by hand.
14
+ */
15
+ import { readdir, readFile, stat, writeFile } from "node:fs/promises";
16
+ import { basename, dirname, join, relative, resolve, sep } from "node:path";
17
+ import { ccc } from "@ckb-ccc/core";
18
+ import { termLine } from "./diff.js";
19
+ /** The cycles.json for these mocks and binaries. Pure: the caller reads the files. */
20
+ export function configFromMocks(mocks, binaries, options = {}) {
21
+ if (!mocks.length)
22
+ throw new Error("no mock transactions to scan");
23
+ const deployed = new Set();
24
+ for (const m of mocks) {
25
+ for (const d of m.mock.mock_info.cell_deps)
26
+ if (d.cell_dep.dep_type === "code")
27
+ deployed.add(ccc.hashCkb(d.data));
28
+ }
29
+ const found = {};
30
+ const matched = [];
31
+ const unused = [];
32
+ const hashes = new Set();
33
+ for (const b of [...binaries].sort((a, b) => a.name.localeCompare(b.name))) {
34
+ const codeHash = ccc.hashCkb(b.data);
35
+ if (!deployed.has(codeHash)) {
36
+ unused.push(b.name);
37
+ continue;
38
+ }
39
+ if (hashes.has(codeHash)) {
40
+ // Two files with the same bytes: the first one names it.
41
+ unused.push(b.name);
42
+ continue;
43
+ }
44
+ hashes.add(codeHash);
45
+ found[b.name] = { path: b.path, codeHash, ...(b.symbols && { symbols: b.symbols }) };
46
+ matched.push(b.name);
47
+ }
48
+ if (options.functions && !Object.values(found).some((b) => b.symbols)) {
49
+ throw new Error(`--functions needs a <name>.debug (an unstripped build) beside a binary the tests deploy`);
50
+ }
51
+ const config = {
52
+ ...(options.functions && { functions: true }),
53
+ binaries: found,
54
+ scenarios: [...mocks]
55
+ .sort((a, b) => a.name.localeCompare(b.name))
56
+ .map((m) => ({ name: m.name, mock: m.path })),
57
+ };
58
+ return { config, matched, unused, others: [...deployed].filter((h) => !hashes.has(h)).sort() };
59
+ }
60
+ const posix = (p) => p.split(sep).join("/");
61
+ /** Reads the mocks and the binaries, and writes the cycles.json. */
62
+ export async function scanTestMocks(mocksDir, options = {}) {
63
+ const out = resolve(options.out ?? "cycles.json");
64
+ const binariesDir = resolve(options.binariesDir ?? join("build", "release"));
65
+ const rel = (file) => posix(relative(dirname(out), file));
66
+ const mocks = [];
67
+ const mockFiles = (await readdir(mocksDir).catch((e) => {
68
+ if (e.code === "ENOENT")
69
+ throw new Error(`${mocksDir} does not exist: run the tests with CKB_CYCLES_MOCKS set to it`);
70
+ throw e;
71
+ }))
72
+ .filter((f) => f.endsWith(".json"))
73
+ .sort();
74
+ for (const f of mockFiles) {
75
+ const file = resolve(mocksDir, f);
76
+ let mock;
77
+ try {
78
+ mock = JSON.parse(await readFile(file, "utf8"));
79
+ }
80
+ catch (e) {
81
+ throw new Error(`${join(mocksDir, f)}: not JSON (${e instanceof Error ? e.message : e})`);
82
+ }
83
+ if (!mock?.mock_info || !mock.tx)
84
+ throw new Error(`${join(mocksDir, f)} is not a ckb-debugger mock transaction`);
85
+ mocks.push({ name: f.slice(0, -".json".length), path: rel(file), mock });
86
+ }
87
+ if (!mocks.length)
88
+ throw new Error(`no mock transactions in ${mocksDir}: run the tests with CKB_CYCLES_MOCKS set to it`);
89
+ const names = await readdir(binariesDir).catch((e) => {
90
+ if (e.code === "ENOENT")
91
+ throw new Error(`${options.binariesDir ?? "build/release"} does not exist: build the contracts first`);
92
+ throw e;
93
+ });
94
+ const binaries = [];
95
+ for (const name of names.filter((n) => !n.endsWith(".debug")).sort()) {
96
+ const file = join(binariesDir, name);
97
+ if (!(await stat(file)).isFile())
98
+ continue;
99
+ const debug = `${file}.debug`;
100
+ const symbols = await stat(debug).then((s) => s.isFile(), () => false);
101
+ binaries.push({ name, path: rel(file), data: new Uint8Array(await readFile(file)), ...(symbols && { symbols: rel(debug) }) });
102
+ }
103
+ const result = configFromMocks(mocks, binaries, { functions: options.functions });
104
+ await writeFile(out, JSON.stringify(result.config, null, 2) + "\n");
105
+ return { ...result, out };
106
+ }
107
+ /** What scan found, for stderr. */
108
+ export function formatScan(r, binariesDir) {
109
+ const short = (h) => `${h.slice(0, 10)}…${h.slice(-6)}`;
110
+ const lines = [
111
+ `${basename(r.out)}: ${r.config.scenarios.length} scenario(s), ${r.matched.length} binar${r.matched.length === 1 ? "y" : "ies"}` +
112
+ (r.matched.length ? ` (${r.matched.map(termLine).join(", ")})` : ""),
113
+ ];
114
+ if (!r.matched.length) {
115
+ lines.push(`no file in ${binariesDir} is deployed by any test: the report cannot swap in another build (rebuild, then rerun the tests?)`);
116
+ }
117
+ if (r.unused.length)
118
+ lines.push(`not deployed by any test: ${r.unused.map(termLine).join(", ")}`);
119
+ if (r.others.length)
120
+ lines.push(`code cells that are none of the binaries: ${r.others.map(short).join(", ")}`);
121
+ return lines.join("\n");
122
+ }
@@ -38,4 +38,11 @@ export declare function substituteBinaries(mock: MockTransaction, substitutions:
38
38
  mock: MockTransaction;
39
39
  applied: AppliedSubstitution[];
40
40
  };
41
+ /**
42
+ * The scripts (`codeHash:hashType` keys, lower case) that run the code a
43
+ * substitution would replace, in the mock as it is: for a binary that could
44
+ * not be read (absent from the base checkout), the groups whose numbers are
45
+ * the mock's code instead of that build's. Empty when it matches no cell dep.
46
+ */
47
+ export declare function targetScriptKeys(mock: MockTransaction, sub: Pick<BinarySubstitution, "outPoint" | "codeHash">): string[];
41
48
  export {};
@@ -46,20 +46,41 @@ export function substituteBinaries(mock, substitutions, options = {}) {
46
46
  }
47
47
  return { mock: next, applied };
48
48
  }
49
- function substituteOne(mock, sub, skipUnmatched) {
50
- const label = sub.name ?? sub.codeHash ?? (sub.outPoint && `${sub.outPoint.tx_hash}:${Number(sub.outPoint.index)}`);
51
- if (!sub.outPoint === !sub.codeHash)
52
- throw new Error(`substitution ${label}: give an out point or a code hash, not both`);
53
- const data = ccc.hexFrom(sub.data);
54
- const newDataHash = ccc.hashCkb(data);
49
+ /** The code cell deps a substitution would replace: by out point, or by data hash or type script hash. */
50
+ function targetsOf(mock, sub) {
55
51
  const want = sub.codeHash?.toLowerCase();
56
- const targets = mock.mock_info.cell_deps.filter((d) => {
52
+ return mock.mock_info.cell_deps.filter((d) => {
57
53
  if (d.cell_dep.dep_type !== "code")
58
54
  return false;
59
55
  if (sub.outPoint)
60
56
  return sameOutPoint(d.cell_dep.out_point, sub.outPoint);
61
57
  return ccc.hashCkb(d.data) === want || (d.output.type != null && typeHash(d.output.type) === want);
62
58
  });
59
+ }
60
+ /**
61
+ * The scripts (`codeHash:hashType` keys, lower case) that run the code a
62
+ * substitution would replace, in the mock as it is: for a binary that could
63
+ * not be read (absent from the base checkout), the groups whose numbers are
64
+ * the mock's code instead of that build's. Empty when it matches no cell dep.
65
+ */
66
+ export function targetScriptKeys(mock, sub) {
67
+ const keys = new Set();
68
+ for (const d of targetsOf(mock, sub)) {
69
+ const dataHash = ccc.hashCkb(d.data).toLowerCase();
70
+ for (const t of DATA_HASH_TYPES)
71
+ keys.add(`${dataHash}:${t}`);
72
+ if (d.output.type)
73
+ keys.add(`${typeHash(d.output.type)}:type`.toLowerCase());
74
+ }
75
+ return [...keys];
76
+ }
77
+ function substituteOne(mock, sub, skipUnmatched) {
78
+ const label = sub.name ?? sub.codeHash ?? (sub.outPoint && `${sub.outPoint.tx_hash}:${Number(sub.outPoint.index)}`);
79
+ if (!sub.outPoint === !sub.codeHash)
80
+ throw new Error(`substitution ${label}: give an out point or a code hash, not both`);
81
+ const data = ccc.hexFrom(sub.data);
82
+ const newDataHash = ccc.hashCkb(data);
83
+ const targets = targetsOf(mock, sub);
63
84
  if (!targets.length) {
64
85
  if (skipUnmatched)
65
86
  return undefined;
package/dist/wasm.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { RunDebugger } from "./replay.js";
1
+ import { type RunDebugger } from "./replay.js";
2
2
  export interface WasmRun {
3
3
  exitCode: number;
4
4
  stdout: string;
package/dist/wasm.js CHANGED
@@ -8,6 +8,7 @@
8
8
  * directory at `/`, and stdout/stderr are collected as text.
9
9
  */
10
10
  import { ConsoleStdout, File, OpenFile, PreopenDirectory, WASI } from "@bjorn3/browser_wasi_shim";
11
+ import { checkMockTransaction } from "./replay.js";
11
12
  /**
12
13
  * Runs the debugger once. `files` are placed in `/`, so `--tx-file /tx.json`
13
14
  * reads `files["tx.json"]`. A fresh instance each time: no state leaks between runs.
@@ -46,6 +47,12 @@ export const WASM_TX_FILE = "/tx.json";
46
47
  * WASM_TX_FILE: `replayGroups(plan, wasmRunner(module, tx), { txFile: WASM_TX_FILE, … })`.
47
48
  */
48
49
  export function wasmRunner(module, tx) {
50
+ // The bytes the debugger reads, checked as they are: no `{{ … }}` directive
51
+ // anywhere in them, and a mock checkMockTransaction accepts.
52
+ const text = new TextDecoder().decode(tx);
53
+ if (text.includes("{{"))
54
+ throw new Error(`mock transaction refused: contains "{{", a ckb-debugger template directive`);
55
+ checkMockTransaction(JSON.parse(text));
49
56
  // The whole run, exit code included: replayGroups checks the result lines against it.
50
57
  return (args) => runWasmDebugger(module, args, { "tx.json": tx });
51
58
  }