ckb-cycle-tools 0.0.0-stage → 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/report.js ADDED
@@ -0,0 +1,445 @@
1
+ /**
2
+ * `ckb-cycles report`: runs every scenario in a `cycles.json` and records the
3
+ * cycles and result of each script group, for `ckb-cycles diff` to compare.
4
+ *
5
+ * A scenario is a transaction in one of three forms:
6
+ * - `"mock"`: a ckb-debugger mock transaction (every cell it touches, inline).
7
+ * Needs no node at all, so it is what CI should use.
8
+ * - `"file"`: a transaction in the node's RPC shape (or CCC's), as `--file` reads
9
+ * it. The cells it spends and depends on are fetched from a node.
10
+ * - `"tx"`: a transaction hash, fetched from a node.
11
+ *
12
+ * `"binaries"` swaps a deployed script for the one built from the commit under
13
+ * test (see substitute.ts for the rules). A binary with `"symbols"` (an
14
+ * unstripped build of the same code) can also say which functions its cycles
15
+ * went to, in scenarios with `"functions": true`.
16
+ */
17
+ import { readFile, realpath, stat } from "node:fs/promises";
18
+ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
19
+ import { FUNCTION_LIMIT, resultLabel, termLine, termLines, unmatchedError } from "./diff.js";
20
+ import { functionCosts } from "./flame.js";
21
+ import { buildMockTransaction, httpRpc, mockFromTransaction, scriptVersionAt } from "./mock.js";
22
+ import { flameTransaction, parseNames, profileTransaction, readTransactionJson } from "./profile.js";
23
+ import { consensusOf, nodeVerdict, PUBLIC_RPC } from "./replay.js";
24
+ import { substituteBinaries, targetScriptKeys } from "./substitute.js";
25
+ const HASH = /^0x[0-9a-fA-F]{64}$/;
26
+ /** Parses and checks a cycles.json, with a message that says what to fix. */
27
+ export function parseCyclesConfig(json) {
28
+ const fail = (msg) => {
29
+ throw new Error(`cycles.json: ${msg}`);
30
+ };
31
+ let c;
32
+ try {
33
+ c = JSON.parse(json);
34
+ }
35
+ catch (e) {
36
+ return fail(`not valid JSON (${e instanceof Error ? e.message : e})`);
37
+ }
38
+ if (!c || typeof c !== "object" || !Array.isArray(c.scenarios))
39
+ fail(`expected { "scenarios": [ ... ] }`);
40
+ if (c.network !== undefined && c.network !== "testnet" && c.network !== "mainnet") {
41
+ fail(`"network" must be "testnet" or "mainnet"`);
42
+ }
43
+ if (c.names !== undefined)
44
+ parseNames(Object.entries(c.names).map(([k, v]) => `${k}=${v}`));
45
+ for (const [name, b] of Object.entries(c.binaries ?? {})) {
46
+ if (!b || typeof b.path !== "string")
47
+ fail(`binary "${name}" needs a "path"`);
48
+ if (!b.outPoint === !b.codeHash)
49
+ fail(`binary "${name}" needs either "outPoint" or "codeHash"`);
50
+ if (b.codeHash !== undefined && !HASH.test(b.codeHash))
51
+ fail(`binary "${name}": "codeHash" must be 0x + 64 hex`);
52
+ if (b.outPoint && (!HASH.test(b.outPoint.tx_hash ?? "") || !/^0x[0-9a-fA-F]+$/.test(b.outPoint.index ?? ""))) {
53
+ fail(`binary "${name}": "outPoint" must be { "tx_hash": "0x…", "index": "0x0" }`);
54
+ }
55
+ if (b.symbols !== undefined && (typeof b.symbols !== "string" || !b.symbols))
56
+ fail(`binary "${name}": "symbols" must be a path`);
57
+ }
58
+ if (c.functions !== undefined && typeof c.functions !== "boolean")
59
+ fail(`"functions" must be true or false`);
60
+ const seen = new Set();
61
+ for (const s of c.scenarios) {
62
+ if (!s || typeof s.name !== "string" || !s.name)
63
+ fail(`every scenario needs a "name"`);
64
+ if (seen.has(s.name))
65
+ fail(`two scenarios are named "${s.name}"`);
66
+ seen.add(s.name);
67
+ const sources = [s.tx, s.file, s.mock].filter((v) => v !== undefined);
68
+ if (sources.length !== 1)
69
+ fail(`scenario "${s.name}" needs exactly one of "tx", "file", "mock"`);
70
+ for (const k of ["file", "mock"]) {
71
+ if (s[k] !== undefined && (typeof s[k] !== "string" || !s[k]))
72
+ fail(`scenario "${s.name}": "${k}" must be a path`);
73
+ }
74
+ if (s.tx !== undefined && !HASH.test(s.tx))
75
+ fail(`scenario "${s.name}": "tx" must be a transaction hash`);
76
+ for (const b of s.binaries ?? [])
77
+ if (!c.binaries?.[b])
78
+ fail(`scenario "${s.name}" uses unknown binary "${b}"`);
79
+ if (s.scriptVersion !== undefined && ![0, 1, 2].includes(s.scriptVersion)) {
80
+ fail(`scenario "${s.name}": "scriptVersion" must be 0, 1 or 2`);
81
+ }
82
+ if (s.functions !== undefined && typeof s.functions !== "boolean")
83
+ fail(`scenario "${s.name}": "functions" must be true or false`);
84
+ }
85
+ // Functions come only from a symbols build: asking without one would record nothing, silently.
86
+ if (c.scenarios.some((s) => s.functions ?? c.functions) && !Object.values(c.binaries ?? {}).some((b) => b.symbols)) {
87
+ fail(`"functions" needs a binary with "symbols" (an unstripped build of the same code)`);
88
+ }
89
+ return c;
90
+ }
91
+ const short = (h, n = 6) => (h.length > 2 * n + 2 ? `${h.slice(0, n + 2)}…${h.slice(-n)}` : h);
92
+ export function groupResults(p) {
93
+ return p.groups.map((g) => ({
94
+ selector: g.selector,
95
+ role: g.role,
96
+ script: g.name ?? short(g.codeHash),
97
+ codeHash: g.codeHash,
98
+ hashType: g.hashType,
99
+ result: g.result,
100
+ ...(g.error && { error: g.error }),
101
+ cycles: Number(g.cycles),
102
+ }));
103
+ }
104
+ /**
105
+ * Runs every scenario of a cycles.json. A scenario that cannot run is recorded
106
+ * with its error rather than ending the report, so one broken scenario does not
107
+ * hide the others' numbers.
108
+ */
109
+ export async function runReport(configPath, options = {}) {
110
+ const config = parseCyclesConfig(await readFile(configPath, "utf8"));
111
+ const dir = dirname(resolve(configPath));
112
+ const binDir = options.binariesRoot ? resolve(options.binariesRoot) : dir;
113
+ // Only a network the config names is checked against the node; otherwise the
114
+ // node says which chain it serves, and its own hardfork epochs are used.
115
+ const network = config.network;
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}`));
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.
129
+ const binaries = new Map();
130
+ const binary = (name) => {
131
+ let p = binaries.get(name);
132
+ if (!p) {
133
+ const b = config.binaries[name];
134
+ p = inside(resolve(binDir, b.path))
135
+ .then((file) => readFile(file))
136
+ .then((data) => ({
137
+ name,
138
+ data: new Uint8Array(data),
139
+ ...(b.outPoint && { outPoint: b.outPoint }),
140
+ ...(b.codeHash && { codeHash: b.codeHash }),
141
+ }), (e) => {
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`);
147
+ });
148
+ binaries.set(name, p);
149
+ }
150
+ return p;
151
+ };
152
+ const used = new Set();
153
+ const missingNames = new Set();
154
+ let debuggerVersion;
155
+ const scenarios = [];
156
+ for (const s of config.scenarios) {
157
+ let result;
158
+ try {
159
+ const explicit = s.binaries !== undefined;
160
+ const names = explicit ? s.binaries : Object.keys(config.binaries ?? {});
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 = [];
168
+ const profileOptions = {
169
+ ...(network && { network }),
170
+ ...(rpcUrl && { rpcUrl }),
171
+ ...(options.timeoutMs !== undefined && { timeoutMs: options.timeoutMs }),
172
+ ...(options.debuggerPath && { debuggerPath: options.debuggerPath }),
173
+ ...(options.runDebugger && { runDebugger: options.runDebugger }),
174
+ ...(s.scriptVersion !== undefined && { scriptVersion: s.scriptVersion }),
175
+ };
176
+ let profile;
177
+ let groups;
178
+ const warnings = [];
179
+ if (s.tx && !subs.length && !missing.length) {
180
+ // Nothing to swap: profile it as the CLI does, with the node's check.
181
+ profile = await profileTransaction(s.tx, { ...profileOptions, scriptNames: baseNames });
182
+ }
183
+ else {
184
+ const url = rpcUrl ?? PUBLIC_RPC[network ?? "testnet"];
185
+ const rpc = () => httpRpc(url, { ...(options.timeoutMs !== undefined && { timeoutMs: options.timeoutMs }) });
186
+ let mock;
187
+ let scriptVersion = s.scriptVersion;
188
+ if (s.mock) {
189
+ mock = JSON.parse(await readFile(await inside(resolve(dir, s.mock)), "utf8"));
190
+ if (!mock?.mock_info || !mock.tx)
191
+ throw new Error(`${s.mock} is not a ckb-debugger mock transaction`);
192
+ }
193
+ else if (s.file) {
194
+ mock = await mockFromTransaction(rpc(), readTransactionJson(await readFile(await inside(resolve(dir, s.file)), "utf8")));
195
+ }
196
+ else {
197
+ const node = rpc();
198
+ const [built, consensus] = await Promise.all([
199
+ buildMockTransaction(node, s.tx),
200
+ consensusOf(node, url, { ...(network && { network }), ...(rpcUrl && { rpcUrl }) }),
201
+ ]);
202
+ mock = built.mock;
203
+ if (scriptVersion === undefined && built.epoch !== undefined) {
204
+ scriptVersion = scriptVersionAt(consensus?.vmEpochs ?? network ?? "testnet", built.epoch);
205
+ }
206
+ }
207
+ const { mock: swapped, applied } = substituteBinaries(mock, subs, { skipUnmatched: !explicit });
208
+ // A substituted binary is labelled by its name; "names" still wins.
209
+ const scriptNames = {};
210
+ for (const a of applied) {
211
+ used.add(a.name);
212
+ substituted.push(a.name);
213
+ for (const k of a.scriptKeys)
214
+ scriptNames[k] = a.name;
215
+ warnings.push(...a.warnings.map((w) => `${a.name}: ${w}`));
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
+ }
230
+ Object.assign(scriptNames, baseNames);
231
+ profile = await profileTransaction(swapped, {
232
+ ...profileOptions,
233
+ ...(scriptVersion !== undefined && { scriptVersion }),
234
+ scriptNames,
235
+ });
236
+ // The scripts whose code is a binary with symbols, when the scenario asks for functions.
237
+ const symbols = new Map();
238
+ if (s.functions ?? config.functions) {
239
+ for (const a of applied) {
240
+ const sym = config.binaries[a.name].symbols;
241
+ if (sym)
242
+ for (const k of a.scriptKeys)
243
+ symbols.set(k.toLowerCase(), sym);
244
+ }
245
+ }
246
+ if (symbols.size) {
247
+ groups = groupResults(profile);
248
+ await recordFunctions(groups, swapped, symbols, binDir, inside, {
249
+ ...profileOptions,
250
+ ...(scriptVersion !== undefined && { scriptVersion }),
251
+ });
252
+ }
253
+ }
254
+ debuggerVersion ??= profile.env.debugger;
255
+ // Kept with the scenario: numbers that do not add up to the node's are not to be trusted.
256
+ if (nodeVerdict(profile) === "mismatch") {
257
+ warnings.push(`the groups add up to ${profile.measuredCycles} cycles, the node reported ${profile.nodeCycles}`);
258
+ }
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
+ }
265
+ result = {
266
+ name: s.name,
267
+ groups,
268
+ ...(warnings.length && { warnings }),
269
+ ...(substituted.length && { substituted }),
270
+ ...(unmatched.length && { unmatched }),
271
+ ...(missing.length && { binaryMissing: true, missingBinaries: missing }),
272
+ };
273
+ }
274
+ catch (e) {
275
+ result = { name: s.name, error: e instanceof Error ? e.message : String(e), groups: [] };
276
+ }
277
+ scenarios.push(result);
278
+ options.onScenario?.(result);
279
+ }
280
+ const errors = scenarios.filter((s) => s.error).map((s) => `scenario "${s.name}": ${s.error}`);
281
+ // A binary offered to every scenario that none of them uses is almost always
282
+ // a wrong out point or code hash: the report would measure the old code.
283
+ // Only said when every scenario ran: one that failed may be the one that uses it.
284
+ const offered = !errors.length && config.scenarios.some((s) => s.binaries === undefined) ? Object.keys(config.binaries ?? {}) : [];
285
+ for (const name of offered) {
286
+ if (!used.has(name) && !missingNames.has(name) && !config.scenarios.some((s) => s.binaries?.includes(name))) {
287
+ errors.push(unmatchedError(name));
288
+ }
289
+ }
290
+ return {
291
+ tool: "ckb-cycles",
292
+ version: 1,
293
+ ...(debuggerVersion && { debugger: debuggerVersion }),
294
+ scenarios,
295
+ errors,
296
+ ...(notices.length && { notices }),
297
+ };
298
+ }
299
+ /**
300
+ * Adds `functions` to each group whose script (`codeHash:hashType`) is in
301
+ * `symbols` (to the symbols build's path in the config), from a flamegraph run
302
+ * of that group with that build. A build that does not cost the same cycles as
303
+ * the binary it stands for is not the same code: the group gets a warning instead.
304
+ */
305
+ async function recordFunctions(groups, mock, symbols, binDir, inside, options) {
306
+ const fmt = (n) => n.toLocaleString("en-US");
307
+ const symbolsOf = (g) => symbols.get(`${g.codeHash}:${g.hashType}`.toLowerCase());
308
+ const wanted = groups.filter((g) => symbolsOf(g));
309
+ const bins = {};
310
+ for (const g of wanted) {
311
+ let file;
312
+ try {
313
+ file = await inside(resolve(binDir, symbolsOf(g)));
314
+ }
315
+ catch (e) {
316
+ g.functionsWarning = e instanceof Error ? e.message : String(e);
317
+ continue;
318
+ }
319
+ // A missing build is said on its group; the cycles are measured all the same.
320
+ const found = await stat(file).then((st) => st.isFile(), () => false);
321
+ if (found)
322
+ bins[g.codeHash] = file;
323
+ else
324
+ g.functionsWarning = `cannot read the symbols build ${symbolsOf(g)}: build it first`;
325
+ }
326
+ const run = wanted.filter((g) => bins[g.codeHash]);
327
+ if (!run.length)
328
+ return;
329
+ let flame;
330
+ try {
331
+ flame = await flameTransaction(mock, {
332
+ ...options,
333
+ bins,
334
+ scripts: run.map((g) => g.selector),
335
+ readFile: (path) => readFile(path, "utf8"),
336
+ });
337
+ }
338
+ catch (e) {
339
+ for (const g of run)
340
+ g.functionsWarning = `the flamegraph run failed: ${e instanceof Error ? e.message : String(e)}`;
341
+ return;
342
+ }
343
+ for (const g of run) {
344
+ const f = flame.groups.find((f) => f.selector === g.selector);
345
+ if (!f)
346
+ g.functionsWarning = "the flamegraph run did not profile this group";
347
+ else if (f.cycles !== BigInt(g.cycles) || resultLabel(f) !== resultLabel(g)) {
348
+ g.functionsWarning =
349
+ `the symbols build ${symbolsOf(g)} runs ${fmt(f.cycles)} cycles (${resultLabel(f)}), the binary ${fmt(g.cycles)} (${resultLabel(g)}): ` +
350
+ "not the same code, so its functions would not describe this binary";
351
+ }
352
+ else if (!f.folded.size)
353
+ g.functionsWarning = "the profiler recorded no stacks";
354
+ else {
355
+ g.functions = functionCosts(f.folded)
356
+ .slice(0, FUNCTION_LIMIT)
357
+ .map((c) => ({ name: c.name, self: Number(c.self), total: Number(c.total) }));
358
+ }
359
+ }
360
+ }
361
+ /**
362
+ * `file` with its symlinks resolved, when it is inside one of `roots` (already
363
+ * resolved); an error otherwise. A file that does not exist is checked by its
364
+ * path and returned as given, so reading it fails with the usual ENOENT (a
365
+ * binary absent from the base is a new binary, not an error).
366
+ */
367
+ export async function confine(file, roots) {
368
+ if (!roots)
369
+ return file;
370
+ const real = await realpath(file).catch((e) => {
371
+ if (e.code === "ENOENT")
372
+ return undefined;
373
+ throw e;
374
+ });
375
+ const within = (p) => roots.some((root) => {
376
+ const rel = relative(root, p);
377
+ return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
378
+ });
379
+ if (!within(real ?? (await realParent(resolve(file))))) {
380
+ throw new Error(`${file} is outside the checkout (${roots.join(", ")}): not read`);
381
+ }
382
+ return real ?? file;
383
+ }
384
+ /**
385
+ * A missing file's path with its nearest existing ancestor resolved, so it compares
386
+ * like the roots do (Windows runners' temp dir is an 8.3 short name, RUNNER~1).
387
+ */
388
+ async function realParent(p) {
389
+ const parent = dirname(p);
390
+ if (parent === p)
391
+ return p;
392
+ try {
393
+ return join(await realpath(parent), basename(p));
394
+ }
395
+ catch (e) {
396
+ if (e.code !== "ENOENT")
397
+ throw e;
398
+ return join(await realParent(parent), basename(p));
399
+ }
400
+ }
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
+ */
406
+ export function formatReport(report) {
407
+ const fmt = (n) => n.toLocaleString("en-US");
408
+ const t = termLine;
409
+ const rows = report.scenarios.flatMap((s) => s.error
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)]));
412
+ const head = ["SCENARIO", "GROUP", "SCRIPT", "RESULT", "CYCLES"];
413
+ const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
414
+ const line = (cells) => cells.map((c, i) => (i === 4 ? c.padStart(widths[i]) : c.padEnd(widths[i]))).join(" ").trimEnd();
415
+ const out = [line(head), ...rows.map(line)];
416
+ for (const s of report.scenarios)
417
+ if (s.error)
418
+ out.push("", `${t(s.name)}: ${termLines(s.error)}`);
419
+ for (const s of report.scenarios)
420
+ for (const w of s.warnings ?? [])
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
+ }
428
+ for (const s of report.scenarios) {
429
+ for (const g of s.groups.filter((g) => g.error))
430
+ out.push("", `${t(s.name)} ${t(g.selector)} stopped: ${t(g.error)}`);
431
+ }
432
+ for (const s of report.scenarios) {
433
+ for (const g of s.groups) {
434
+ if (g.functionsWarning)
435
+ out.push("", `${t(s.name)} ${t(g.selector)}: functions not recorded: ${t(g.functionsWarning)}`);
436
+ else if (g.functions?.length) {
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(", ")}`);
439
+ }
440
+ }
441
+ }
442
+ if (report.debugger)
443
+ out.push("", t(report.debugger));
444
+ return out.join("\n");
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
+ }
@@ -0,0 +1,48 @@
1
+ import type { MockTransaction, RpcOutPoint } from "./mock.js";
2
+ type Hex = string;
3
+ export interface BinarySubstitution {
4
+ /** A label for messages, and for the script in reports. */
5
+ name?: string;
6
+ /** The new binary, as bytes or 0x-hex. */
7
+ data: Uint8Array | Hex;
8
+ /** The cell dep to replace. Give this or `codeHash`. */
9
+ outPoint?: RpcOutPoint;
10
+ /** Replace every code dep whose data hash or type script hash is this. */
11
+ codeHash?: Hex;
12
+ }
13
+ export interface AppliedSubstitution {
14
+ name?: string;
15
+ /** The cell deps that now hold the new binary. */
16
+ outPoints: RpcOutPoint[];
17
+ oldDataHash: Hex;
18
+ newDataHash: Hex;
19
+ /**
20
+ * The code hashes scripts can now reach the binary by, as `codeHash:hashType`
21
+ * keys (the form profileTransaction's `scriptNames` takes).
22
+ */
23
+ scriptKeys: string[];
24
+ /** How many scripts had their code hash rewritten (data hash types only). */
25
+ rewritten: number;
26
+ warnings: string[];
27
+ }
28
+ /**
29
+ * Applies the substitutions in order and returns a new mock; the input is not
30
+ * modified. Throws if a substitution matches no code dep, since silently
31
+ * measuring the old binary would be the worst possible result — unless
32
+ * `skipUnmatched`, for a binary offered to every scenario, which only some use;
33
+ * the ones that matched are in `applied`.
34
+ */
35
+ export declare function substituteBinaries(mock: MockTransaction, substitutions: BinarySubstitution[], options?: {
36
+ skipUnmatched?: boolean;
37
+ }): {
38
+ mock: MockTransaction;
39
+ applied: AppliedSubstitution[];
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[];
48
+ export {};