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/flame.js CHANGED
@@ -62,6 +62,26 @@ export function parseFolded(text) {
62
62
  }
63
63
  return folded;
64
64
  }
65
+ /**
66
+ * Renames each `func_0x<address>` frame (code the profiler found no line info
67
+ * for) to the function starting at that address in `names` (elf.ts), merging
68
+ * stacks that become the same. Frames it has no name for keep their address.
69
+ */
70
+ export function nameAddresses(f, names) {
71
+ if (!names.size)
72
+ return f;
73
+ const out = new Map();
74
+ for (const [stack, v] of f) {
75
+ const renamed = splitStack(stack)
76
+ .map((frame) => {
77
+ const m = /^func_0x([0-9a-fA-F]+)$/.exec(frame);
78
+ return (m && names.get(BigInt(`0x${m[1]}`))) || frame;
79
+ })
80
+ .join(";");
81
+ out.set(renamed, (out.get(renamed) ?? 0n) + v);
82
+ }
83
+ return out;
84
+ }
65
85
  export const foldedTotal = (f) => [...f.values()].reduce((s, v) => s + v, 0n);
66
86
  /** Back to text, one merged stack per line, heaviest first: the format speedscope and inferno read. */
67
87
  export function formatFolded(f) {
@@ -172,8 +192,28 @@ function colour(name) {
172
192
  const light = 45 + ((h >>> 8) % 15);
173
193
  return `hsl(${hue} 75% ${light}%)`;
174
194
  }
175
- /** The `All cycles: N` line ckb-debugger prints in flamegraph mode: what the profile covers. */
195
+ /**
196
+ * The `All cycles: N` line ckb-debugger prints in flamegraph mode: what the
197
+ * profile covers. The last one: when the script spawns other scripts, the
198
+ * debugger first runs the whole group (printing its full total) to record
199
+ * the syscalls, then profiles the root script alone ("Actual run").
200
+ */
176
201
  export function profiledCycles(output) {
177
- const m = /^All cycles:\s*(\d+)/m.exec(output);
178
- return m ? BigInt(m[1]) : undefined;
202
+ const all = [...output.matchAll(/^All cycles:\s*(\d+)/gm)];
203
+ return all.length ? BigInt(all[all.length - 1][1]) : undefined;
204
+ }
205
+ /**
206
+ * How many scripts the profiled script spawned (CKB2023 `spawn`), from the
207
+ * `Spawn tree:` lines ckb-debugger prints in flamegraph mode: one per VM,
208
+ * the root first (`Spawn tree: 0 …`, then `Spawn tree: └── 1 …`). 0 when
209
+ * there are none. The debugger profiles only the root VM, so the spawned
210
+ * scripts' cycles are in the group's total but in none of its frames. (A
211
+ * script could print such a line itself; this count only adds a note.)
212
+ */
213
+ export function spawnedScripts(output) {
214
+ const ids = new Set();
215
+ for (const m of output.matchAll(/^Spawn tree: [\s─-╿]*(\d+)\s/gm))
216
+ ids.add(m[1]);
217
+ ids.delete("0");
218
+ return ids.size;
179
219
  }
package/dist/index.d.ts CHANGED
@@ -4,11 +4,11 @@ export { analyzeTransaction, groupScripts, knownScriptNames, TransactionNotFound
4
4
  export type { ScriptGroup, TxAnalysis } from "./analyze.js";
5
5
  export { buildMockTransaction, httpRpc, isCellbase, mockFromTransaction, nodeConsensus, parseOutPointVec, scriptVersionAt, } from "./mock.js";
6
6
  export type { HttpRpcOptions, MockTransaction, NodeConsensus, Rpc, RpcOutPoint, RpcTransaction, VmEpochs } from "./mock.js";
7
- export { checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
7
+ export { checkMockTransaction, checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
8
8
  export type { DebuggerOutput, GroupRun, Profile, ProfiledGroup, ReplayOptions, ReplayPlan, RunDebugger } from "./replay.js";
9
9
  export { flameTransaction, profileTransaction, runNativeDebugger } from "./profile.js";
10
10
  export type { FlameGroup, ProfileOptions } from "./profile.js";
11
- export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, renderFlameSvg, splitStack, } from "./flame.js";
11
+ export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, spawnedScripts, renderFlameSvg, splitStack, } from "./flame.js";
12
12
  export type { FlameNode, Folded, FunctionCost } from "./flame.js";
13
13
  export { runWasmDebugger, wasmDebuggerVersion, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
14
14
  export type { WasmRun } from "./wasm.js";
@@ -18,3 +18,5 @@ export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FU
18
18
  export type { CycleDiff, CycleReport, DiffOptions, DiffRow, FunctionDelta, FunctionResult, GroupResult, MarkdownOptions, ScenarioResult } from "./diff.js";
19
19
  export { formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
20
20
  export type { BinaryConfig, CyclesConfig, ReportOptions, ScenarioConfig } from "./report.js";
21
+ export { configFromMocks, formatScan, scanTestMocks } from "./scan.js";
22
+ export type { ScanOptions, ScanResult, ScannedBinary, ScannedMock } from "./scan.js";
package/dist/index.js CHANGED
@@ -1,10 +1,11 @@
1
1
  export { checkDebuggerPath, DebuggerNotFoundError, resolveDebugger } from "./debugger.js";
2
2
  export { analyzeTransaction, groupScripts, knownScriptNames, TransactionNotFoundError } from "./analyze.js";
3
3
  export { buildMockTransaction, httpRpc, isCellbase, mockFromTransaction, nodeConsensus, parseOutPointVec, scriptVersionAt, } from "./mock.js";
4
- export { checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
4
+ export { checkMockTransaction, checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
5
5
  export { flameTransaction, profileTransaction, runNativeDebugger } from "./profile.js";
6
- export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, renderFlameSvg, splitStack, } from "./flame.js";
6
+ export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, spawnedScripts, renderFlameSvg, splitStack, } from "./flame.js";
7
7
  export { runWasmDebugger, wasmDebuggerVersion, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
8
8
  export { substituteBinaries } from "./substitute.js";
9
9
  export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, resultLabel, summarize, } from "./diff.js";
10
10
  export { formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
11
+ export { configFromMocks, formatScan, scanTestMocks } from "./scan.js";
package/dist/profile.d.ts CHANGED
@@ -49,18 +49,28 @@ export interface FlameGroup {
49
49
  /** With `bin`: the exit code of that run (with the deployed binary), and whether the VM stopped it. */
50
50
  deployedResult?: number;
51
51
  deployedError?: string;
52
+ /**
53
+ * How many scripts this group's script spawned (CKB2023 `spawn`). ckb-debugger
54
+ * profiles only the root script: the spawned ones' cycles are in `cycles`
55
+ * but in no frame of `folded`, and `--bin` replaces only the root's binary.
56
+ */
57
+ spawned?: number;
52
58
  }
53
59
  /**
54
60
  * Profiles each script group with ckb-debugger's flamegraph mode. `bins` maps a
55
61
  * code hash to an unstripped build of that script, used instead of the
56
62
  * deployed (stripped) binary so the frames have names; each such group is also
57
63
  * run with the deployed binary, to check the build behaves the same.
58
- * `scripts` limits the run to those selectors (`input.0.lock`, …).
64
+ * `scripts` limits the run to those selectors (`input.0.lock`, …). `readFile`
65
+ * reads the folded stacks the debugger wrote, and `readBinary` (node:fs when
66
+ * not given) the builds, for their symbol tables: both see the files where
67
+ * `runDebugger` does.
59
68
  */
60
69
  export declare function flameTransaction(target: string | RpcTransaction | MockTransaction, options: ProfileOptions & {
61
70
  bins?: Record<string, string>;
62
71
  scripts?: string[];
63
72
  readFile: (path: string) => Promise<string>;
73
+ readBinary?: (path: string) => Promise<Uint8Array>;
64
74
  }): Promise<{
65
75
  plan: ReplayPlan;
66
76
  groups: FlameGroup[];
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, spawnedScripts } 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,9 @@ 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 spawned = spawnedScripts(runOut.stdout);
116
+ const names = bin ? await namesOf(bin) : new Map();
117
+ const folded = nameAddresses(parseFolded(await options.readFile(out).catch(() => "")), names);
103
118
  // Flamegraph mode leaves out loading the binary, so result and cycles come
104
119
  // from plain runs: with the build, and with the deployed binary to compare.
105
120
  const parsed = runOut.exitCode === null ? parseDebuggerRun(runOut) : parseDebuggerRun(await exec([...base, ...(bin ? ["--bin", bin] : [])]));
@@ -113,6 +128,7 @@ export async function flameTransaction(target, options) {
113
128
  ...(parsed.error && { error: parsed.error }),
114
129
  cycles: parsed.cycles,
115
130
  folded,
131
+ ...(spawned && { spawned }),
116
132
  ...(bin &&
117
133
  deployed && {
118
134
  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";
20
- import { functionCosts } from "./flame.js";
19
+ import { FUNCTION_LIMIT, resultLabel, spawnNote, termLine, termLines, unmatchedError } from "./diff.js";
20
+ import { foldedTotal, 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
  /**
@@ -304,6 +342,10 @@ async function recordFunctions(groups, mock, symbols, binDir, inside, options) {
304
342
  }
305
343
  for (const g of run) {
306
344
  const f = flame.groups.find((f) => f.selector === g.selector);
345
+ if (f?.spawned) {
346
+ g.spawned = f.spawned;
347
+ g.profiled = Number(foldedTotal(f.folded));
348
+ }
307
349
  if (!f)
308
350
  g.functionsWarning = "the flamegraph run did not profile this group";
309
351
  else if (f.cycles !== BigInt(g.cycles) || resultLabel(f) !== resultLabel(g)) {
@@ -360,37 +402,50 @@ async function realParent(p) {
360
402
  return join(await realParent(parent), basename(p));
361
403
  }
362
404
  }
363
- /** The report for a terminal: one block per scenario. */
405
+ /**
406
+ * The report for a terminal: one block per scenario. Every name, warning and
407
+ * error from the config, the build or the debugger goes through termLine (or
408
+ * termLines), so none can start a log line of its own.
409
+ */
364
410
  export function formatReport(report) {
365
411
  const fmt = (n) => n.toLocaleString("en-US");
412
+ const t = termLine;
366
413
  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)]));
414
+ ? [[t(s.name), "", "", "error", ""]]
415
+ : s.groups.map((g) => [t(s.name), t(g.selector), t(g.script), t(resultLabel(g)), fmt(g.cycles)]));
369
416
  const head = ["SCENARIO", "GROUP", "SCRIPT", "RESULT", "CYCLES"];
370
417
  const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
371
418
  const line = (cells) => cells.map((c, i) => (i === 4 ? c.padStart(widths[i]) : c.padEnd(widths[i]))).join(" ").trimEnd();
372
419
  const out = [line(head), ...rows.map(line)];
373
420
  for (const s of report.scenarios)
374
421
  if (s.error)
375
- out.push("", `${s.name}: ${s.error}`);
422
+ out.push("", `${t(s.name)}: ${termLines(s.error)}`);
376
423
  for (const s of report.scenarios)
377
424
  for (const w of s.warnings ?? [])
378
- out.push("", `${s.name}: warning: ${w}`);
425
+ out.push("", `${t(s.name)}: warning: ${t(w)}`);
426
+ for (const s of report.scenarios) {
427
+ for (const b of s.missingBinaries ?? []) {
428
+ const n = s.groups.filter((g) => g.missingBinary === b).length;
429
+ 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`);
430
+ }
431
+ }
379
432
  for (const s of report.scenarios) {
380
433
  for (const g of s.groups.filter((g) => g.error))
381
- out.push("", `${s.name} ${g.selector} stopped: ${g.error}`);
434
+ out.push("", `${t(s.name)} ${t(g.selector)} stopped: ${t(g.error)}`);
382
435
  }
383
436
  for (const s of report.scenarios) {
384
437
  for (const g of s.groups) {
385
438
  if (g.functionsWarning)
386
- out.push("", `${s.name} ${g.selector}: functions not recorded: ${g.functionsWarning}`);
439
+ out.push("", `${t(s.name)} ${t(g.selector)}: functions not recorded: ${t(g.functionsWarning)}`);
387
440
  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(", ")}`);
441
+ const top = g.functions.slice(0, 3).map((f) => `${t(f.name)} ${fmt(f.self)}`);
442
+ out.push("", `${t(s.name)} ${t(g.selector)}: costliest functions (self cycles): ${top.join(", ")}`);
443
+ if (g.spawned)
444
+ out.push(` ${spawnNote({ ...g, head: g })}`);
390
445
  }
391
446
  }
392
447
  }
393
448
  if (report.debugger)
394
- out.push("", report.debugger);
449
+ out.push("", t(report.debugger));
395
450
  return out.join("\n");
396
451
  }
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;