ckb-cycle-tools 1.1.0 → 1.3.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/diff.js CHANGED
@@ -4,8 +4,121 @@
4
4
  *
5
5
  * Pure: no network, no file system.
6
6
  */
7
+ /**
8
+ * A scenario's `overTxLimit`, read defensively (a report file is the PR's):
9
+ * undefined unless both numbers are there and the sum is over the limit.
10
+ */
11
+ export function overTxLimitOf(s) {
12
+ const o = s.overTxLimit;
13
+ if (!o || typeof o !== "object")
14
+ return undefined;
15
+ const { limit, sum } = o;
16
+ if (typeof limit !== "number" || typeof sum !== "number" || !(sum > limit))
17
+ return undefined;
18
+ return { limit, sum };
19
+ }
7
20
  /** How many functions a report keeps per group. */
8
21
  export const FUNCTION_LIMIT = 15;
22
+ /** The note on a group whose scenario's inputs differ between base and head. */
23
+ export const INPUTS_CHANGED = "inputs changed: the scenario's mock, transaction file or cycles.json entry differs from the base's";
24
+ const str = (v) => (typeof v === "string" && v ? v : undefined);
25
+ /**
26
+ * A report's manifest, read defensively: a report file is the PR's, any field
27
+ * may be missing or of another type. Undefined when there is none.
28
+ */
29
+ function manifestOf(r) {
30
+ const m = r.manifest;
31
+ if (!m || typeof m !== "object" || Array.isArray(m))
32
+ return undefined;
33
+ const d = (m.debugger && typeof m.debugger === "object" ? m.debugger : {});
34
+ const t = (m.tool && typeof m.tool === "object" ? m.tool : {});
35
+ const g = (m.git && typeof m.git === "object" ? m.git : undefined);
36
+ const scenarios = (Array.isArray(m.scenarios) ? m.scenarios : [])
37
+ .filter((s) => !!s && typeof s === "object" && typeof s.name === "string")
38
+ .map((s) => ({
39
+ name: s.name,
40
+ ...(typeof s.scriptVersion === "number" && { scriptVersion: s.scriptVersion }),
41
+ ...(str(s.inputs) && { inputs: str(s.inputs) }),
42
+ }));
43
+ return {
44
+ schema: 1,
45
+ tool: { name: str(t.name) ?? "", version: str(t.version) ?? "" },
46
+ debugger: {
47
+ version: str(d.version) ?? "",
48
+ ...(str(d.sha256) && { sha256: str(d.sha256) }),
49
+ ...(str(d.wasm) && { wasm: str(d.wasm) }),
50
+ },
51
+ ...(g && { git: { ...(str(g.commit) && { commit: str(g.commit) }), ...(str(g.binaries) && { binaries: str(g.binaries) }) } }),
52
+ ...(str(m.toolchain) && { toolchain: str(m.toolchain) }),
53
+ scenarios,
54
+ };
55
+ }
56
+ function summaryOf(m) {
57
+ return {
58
+ ...(m.tool.version && { tool: `${m.tool.name || "ckb-cycle-tools"} ${m.tool.version}` }),
59
+ ...(m.debugger.version && { debugger: m.debugger.version }),
60
+ ...(m.debugger.sha256 && { debuggerSha256: m.debugger.sha256 }),
61
+ ...(m.debugger.wasm && { wasm: m.debugger.wasm }),
62
+ ...(m.git?.commit && { commit: m.git.commit }),
63
+ ...(m.git?.binaries && { binariesCommit: m.git.binaries }),
64
+ ...(m.toolchain && { toolchain: m.toolchain }),
65
+ };
66
+ }
67
+ /**
68
+ * What the two manifests say about comparability: the scenarios whose inputs
69
+ * changed, environment differences (a gated diff fails on them), and notes.
70
+ * Text from the manifests goes in as is: the formatters clean it.
71
+ */
72
+ function compareManifests(base, head) {
73
+ const bm = manifestOf(base);
74
+ const hm = manifestOf(head);
75
+ const changed = new Set();
76
+ const environment = [];
77
+ const notes = [];
78
+ // A side with nothing measured (the Action's placeholder for a base without a
79
+ // cycles.json, or whose build failed) has nothing to check: no note for it.
80
+ const measured = (r) => r.scenarios.some((s) => !s.error);
81
+ // Two reports without one (both before 1.3.0) diff as they always did.
82
+ for (const [side, r, m] of [["base", base, bm], ["head", head, hm]]) {
83
+ if (!m && (bm || hm) && measured(r)) {
84
+ notes.push(`the ${side} report has no manifest (written before ckb-cycle-tools 1.3.0?): its inputs, debugger binary and CKB-VM versions were not checked`);
85
+ }
86
+ }
87
+ if (bm && hm) {
88
+ const bd = bm.debugger;
89
+ const hd = hm.debugger;
90
+ // "unknown": no scenario ran on that side, which is an error row of its own.
91
+ const known = (v) => v && v !== "unknown";
92
+ if (known(bd.version) && known(hd.version) && bd.version !== hd.version)
93
+ environment.push(`ckb-debugger version: base ${bd.version}, head ${hd.version}`);
94
+ if (bd.sha256 && hd.sha256 && bd.sha256 !== hd.sha256) {
95
+ environment.push(`ckb-debugger binary: base sha256 ${bd.sha256}, head sha256 ${hd.sha256}`);
96
+ }
97
+ if (bd.wasm && hd.wasm && bd.wasm !== hd.wasm)
98
+ environment.push(`ckb-debugger WebAssembly build: base ${bd.wasm}, head ${hd.wasm}`);
99
+ if ((bd.wasm && hd.sha256 && !hd.wasm) || (hd.wasm && bd.sha256 && !bd.wasm)) {
100
+ environment.push(`ckb-debugger: one side ran the native binary, the other the WebAssembly build`);
101
+ }
102
+ const bs = new Map(bm.scenarios.map((s) => [s.name, s]));
103
+ for (const h of hm.scenarios) {
104
+ const b = bs.get(h.name);
105
+ if (!b)
106
+ continue;
107
+ if (b.inputs && h.inputs && b.inputs !== h.inputs) {
108
+ changed.add(h.name);
109
+ continue;
110
+ }
111
+ if (b.scriptVersion !== undefined && h.scriptVersion !== undefined && b.scriptVersion !== h.scriptVersion) {
112
+ environment.push(`scenario ${h.name}: CKB-VM version ${b.scriptVersion} on the base, ${h.scriptVersion} on the head`);
113
+ }
114
+ }
115
+ if ((bm.toolchain ?? "") !== (hm.toolchain ?? "") && bm.toolchain && hm.toolchain) {
116
+ notes.push(`the toolchain differs: base ${bm.toolchain}; head ${hm.toolchain}`);
117
+ }
118
+ }
119
+ const manifests = bm || hm ? { ...(bm && { base: summaryOf(bm) }), ...(hm && { head: summaryOf(hm) }) } : undefined;
120
+ return { changed, environment, notes, manifests };
121
+ }
9
122
  /** The message for a binary no scenario's cell deps match, in a report's `errors` and the diff. */
10
123
  export const unmatchedError = (name) => `binary "${name}" matched no cell dep in any scenario: check its outPoint / codeHash`;
11
124
  /** The base side of a new group that does not accept: compared with "did not run". */
@@ -31,6 +144,7 @@ export function diffReports(base, head, options = {}) {
31
144
  const rows = [];
32
145
  const baseByName = new Map(base.scenarios.map((s) => [s.name, s]));
33
146
  const headNames = new Set(head.scenarios.map((s) => s.name));
147
+ const manifests = compareManifests(base, head);
34
148
  const scenarioRows = (h, b) => {
35
149
  const name = (h ?? b).name;
36
150
  if (h?.error) {
@@ -45,30 +159,46 @@ export function diffReports(base, head, options = {}) {
45
159
  rows.push({ scenario: name, group: "", script: "", kind: "base-error", overThreshold: false, note: `base: ${b.error}` });
46
160
  }
47
161
  const baseGroups = new Map((b && !b.error ? b.groups : []).map((g) => [g.selector, g]));
162
+ // Inputs that differ: the two sides did not run the same transaction, so no group is compared.
163
+ const inputs = h && b && manifests.changed.has(name) ? INPUTS_CHANGED : undefined;
48
164
  for (const g of h?.groups ?? []) {
49
- rows.push(groupRow(name, baseGroups.get(g.selector), g, threshold));
165
+ rows.push(groupRow(name, baseGroups.get(g.selector), g, threshold, inputs));
50
166
  baseGroups.delete(g.selector);
51
167
  }
52
168
  for (const g of baseGroups.values())
53
- rows.push(groupRow(name, g, undefined, threshold));
169
+ rows.push(groupRow(name, g, undefined, threshold, inputs));
54
170
  };
55
171
  for (const h of head.scenarios)
56
172
  scenarioRows(h, baseByName.get(h.name));
57
173
  for (const b of base.scenarios)
58
174
  if (!headNames.has(b.name))
59
175
  scenarioRows(undefined, b);
176
+ // Over the node's per-transaction limit on the head, and not on the base: a rejection the groups do not show.
177
+ const overTxLimit = head.scenarios.flatMap((h) => {
178
+ const o = h.error ? undefined : overTxLimitOf(h);
179
+ const b = baseByName.get(h.name);
180
+ if (!o || (b && !b.error && overTxLimitOf(b)))
181
+ return [];
182
+ return [{ scenario: h.name, ...o, ...(!b || b.error ? { newScenario: true } : {}) }];
183
+ });
60
184
  const groups = rows.filter((r) => r.kind !== "error" && r.kind !== "base-error");
185
+ const unpaired = groups.filter((r) => r.inputsChanged);
61
186
  return {
62
187
  rows,
63
188
  resultChanges: rows.filter((r) => r.kind === "result").length,
64
189
  overThreshold: rows.filter((r) => r.overThreshold).length,
65
190
  baseErrors: rows.filter((r) => r.kind === "base-error").length,
66
- removed: groups.filter((r) => r.kind === "removed" || r.notCompared).length,
67
- newGroups: groups.filter((r) => r.kind !== "removed" && (!r.base || r.base.result === NOT_RUN)).length,
191
+ removed: groups.filter((r) => (r.kind === "removed" || r.notCompared) && !r.inputsChanged).length,
192
+ newGroups: groups.filter((r) => r.kind !== "removed" && !r.inputsChanged && (!r.base || r.base.result === NOT_RUN)).length,
68
193
  reportErrors: [...reportErrors("base", base), ...reportErrors("head", head)],
69
194
  warnings: head.scenarios.flatMap((s) => (s.warnings ?? []).map((text) => ({ scenario: s.name, text }))),
70
195
  ...(base.debugger && head.debugger && base.debugger !== head.debugger && { debuggers: { base: base.debugger, head: head.debugger } }),
71
196
  ...(threshold !== undefined && { threshold }),
197
+ ...(unpaired.length && { inputsChanged: unpaired.length, changedScenarios: [...new Set(unpaired.map((r) => r.scenario))] }),
198
+ ...(manifests.environment.length && { environment: manifests.environment }),
199
+ ...(manifests.notes.length && { notes: manifests.notes }),
200
+ ...(manifests.manifests && { manifests: manifests.manifests }),
201
+ ...(overTxLimit.length && { overTxLimit }),
72
202
  };
73
203
  }
74
204
  /**
@@ -88,10 +218,11 @@ function reportErrors(side, r) {
88
218
  }
89
219
  return [...out].map((e) => `${side}: ${e}`);
90
220
  }
91
- function groupRow(scenario, measured, h, threshold) {
221
+ function groupRow(scenario, measured, h, threshold, inputsChanged) {
92
222
  const side = (g) => ({ result: resultLabel(g), cycles: g.cycles });
93
223
  // Measured without its binary (not in the base checkout): the mock's code, not the base's build.
94
- const b = h && measured?.missingBinary ? undefined : measured;
224
+ // Or measured on other inputs: not the same transaction.
225
+ const b = h && (measured?.missingBinary || inputsChanged) ? undefined : measured;
95
226
  const row = {
96
227
  scenario,
97
228
  group: (h ?? b).selector,
@@ -103,6 +234,10 @@ function groupRow(scenario, measured, h, threshold) {
103
234
  };
104
235
  if (measured?.missingBinary)
105
236
  row.notCompared = `binary "${measured.missingBinary}" is not in the base checkout`;
237
+ if (inputsChanged) {
238
+ row.notCompared = inputsChanged;
239
+ row.inputsChanged = true;
240
+ }
106
241
  if (b && h) {
107
242
  row.delta = h.cycles - b.cycles;
108
243
  const changed = resultLabel(b) !== resultLabel(h);
@@ -130,6 +265,11 @@ function groupRow(scenario, measured, h, threshold) {
130
265
  row.functions = functionDeltas(b?.functions, h.functions);
131
266
  if (h?.functionsWarning)
132
267
  row.functionsWarning = h.functionsWarning;
268
+ if (h?.spawned) {
269
+ row.spawned = h.spawned;
270
+ if (h.profiled !== undefined)
271
+ row.profiled = h.profiled;
272
+ }
133
273
  return row;
134
274
  }
135
275
  /**
@@ -162,17 +302,33 @@ export function functionDeltas(base, head) {
162
302
  * run, an error in either report, and a base group with nothing to compare
163
303
  * against (removed, renamed, moved, or measured without its binary) unless
164
304
  * `allowRemoved`. A head group the VM stopped is a result change, and over any
165
- * `failAbove` threshold.
305
+ * `failAbove` threshold. With a gate set, a group that accepted on the base and
306
+ * rejects on the head (`ok` → `exit N` or a VM error) always fails, whatever its
307
+ * cycles: a cheaper rejection is not a saving. `failOnResultChange` fails on any
308
+ * result change besides (reject → accept, one exit code or VM error to another,
309
+ * a new group that does not accept). A new group has no base that accepted, so
310
+ * this rule leaves it alone: with `failAbove` alone it fails only as before (a
311
+ * new group the VM stopped is over the threshold). A scenario whose groups add
312
+ * up to more than the node's per-transaction limit on the head, and not on the
313
+ * base, counts as a group that starts rejecting (the node would reject it); a
314
+ * new scenario over the limit, as a new group that does not accept.
166
315
  */
167
316
  export function diffFailed(diff, options = {}) {
168
317
  const gated = options.failAbove !== undefined || options.failOnResultChange === true;
169
318
  return ((options.failAbove !== undefined && diff.overThreshold > 0) ||
170
319
  (options.failOnResultChange === true && diff.resultChanges > 0) ||
320
+ (gated && diff.rows.some(nowRejects)) ||
321
+ (gated && (diff.overTxLimit ?? []).some((o) => !o.newScenario)) ||
322
+ (options.failOnResultChange === true && (diff.overTxLimit?.length ?? 0) > 0) ||
171
323
  (gated && diff.baseErrors > 0) ||
172
324
  (gated && (diff.reportErrors?.length ?? 0) > 0) ||
173
325
  (gated && !options.allowRemoved && (diff.removed ?? 0) > 0) ||
326
+ (gated && !options.allowChangedInputs && (diff.inputsChanged ?? 0) > 0) ||
327
+ (gated && (diff.environment?.length ?? 0) > 0) ||
174
328
  diff.rows.some((r) => r.kind === "error"));
175
329
  }
330
+ /** A group that accepted on the base and rejects (an exit code or a VM error) on the head. */
331
+ const nowRejects = (r) => r.kind === "result" && r.base?.result === "ok" && r.head !== undefined && r.head.result !== "ok";
176
332
  const fmt = (n) => n.toLocaleString("en-US");
177
333
  const signed = (n) => (n > 0 ? `+${fmt(n)}` : n < 0 ? `-${fmt(-n)}` : "0");
178
334
  const pct = (p) => p === undefined ? "" : p === 0 ? "0%" : `${p > 0 ? "+" : "-"}${Math.abs(p) < 0.01 ? "<0.01" : Math.abs(p).toFixed(2)}%`;
@@ -183,11 +339,11 @@ function note(r, threshold) {
183
339
  case "result":
184
340
  return r.base.result === NOT_RUN
185
341
  ? `NEW, DOES NOT ACCEPT: ${r.head.result}${unpaired}`
186
- : `RESULT CHANGED: ${r.base.result} → ${r.head.result}`;
342
+ : `RESULT CHANGED: ${r.base.result} → ${r.head.result}${nowRejects(r) ? " (accepted on the base, rejects now)" : ""}`;
187
343
  case "new":
188
344
  return r.notCompared ? `NOT COMPARED: ${r.notCompared}` : "new";
189
345
  case "removed":
190
- return "REMOVED: no head group to compare with";
346
+ return r.inputsChanged ? `NOT IN THE HEAD (NOT COMPARED: ${r.notCompared})` : "REMOVED: no head group to compare with";
191
347
  case "error":
192
348
  return r.note ?? "error";
193
349
  case "base-error":
@@ -206,11 +362,14 @@ export function summarize(diff, clean = termLine) {
206
362
  const changed = groups.filter((r) => r.kind !== "same").length;
207
363
  const errors = diff.rows.filter((r) => r.kind === "error").length;
208
364
  // A new group has no base, so no percentage: the threshold cannot apply to it.
209
- const unchecked = diff.threshold === undefined ? 0 : groups.filter((r) => !r.base || r.base.result === NOT_RUN).length;
365
+ const unchecked = diff.threshold === undefined ? 0 : groups.filter((r) => !r.inputsChanged && (!r.base || r.base.result === NOT_RUN)).length;
210
366
  const s = (n) => (n > 1 ? "s" : "");
211
367
  const parts = [
212
368
  ...(diff.resultChanges ? [`${diff.resultChanges} result change${s(diff.resultChanges)}`] : []),
213
369
  ...(diff.overThreshold ? [`${diff.overThreshold} over the ${diff.threshold}% threshold`] : []),
370
+ ...(diff.overTxLimit?.length
371
+ ? [`${diff.overTxLimit.length} scenario${s(diff.overTxLimit.length)} over the node's per-transaction cycle limit (the node would reject)`]
372
+ : []),
214
373
  ...(errors ? [`${errors} scenario${s(errors)} failed to run`] : []),
215
374
  ...(diff.baseErrors ? [`${diff.baseErrors} scenario${s(diff.baseErrors)} could not run on the base`] : []),
216
375
  `${changed} of ${groups.length} script group${groups.length === 1 ? "" : "s"} changed`,
@@ -223,6 +382,10 @@ export function summarize(diff, clean = termLine) {
223
382
  ? [`${diff.removed} base group${s(diff.removed)} with nothing in the head to compare with (removed, renamed, moved or not built on the base)`]
224
383
  : []),
225
384
  ...(diff.reportErrors?.length ? [`${diff.reportErrors.length} report error${s(diff.reportErrors.length)}`] : []),
385
+ ...(diff.inputsChanged
386
+ ? [`${diff.inputsChanged} group${s(diff.inputsChanged)} NOT COMPARED: the inputs of ${diff.changedScenarios?.length ?? 0} scenario${s(diff.changedScenarios?.length ?? 0)} changed`]
387
+ : []),
388
+ ...(diff.environment?.length ? [`the base and head ran in different environments (${diff.environment.length} difference${s(diff.environment.length)})`] : []),
226
389
  ...(diff.debuggers
227
390
  ? [`the reports come from different debuggers (base ${clean(diff.debuggers.base)}, head ${clean(diff.debuggers.head)}): cycles can differ for that alone`]
228
391
  : []),
@@ -299,16 +462,29 @@ function functionBlocks(rows) {
299
462
  out.push(`<details><summary>Functions in ${where}: not recorded</summary>`, "", md(r.functionsWarning), "", "</details>", "");
300
463
  continue;
301
464
  }
302
- if (!r.functions?.length)
465
+ const spawn = r.spawned ? spawnNote(r) : undefined;
466
+ if (!r.functions?.length) {
467
+ // No function of the script itself changed: with spawned scripts, that is where the change is.
468
+ if (spawn && r.functions && r.kind !== "same") {
469
+ out.push(`<details><summary>Functions in ${where}: none of its own changed</summary>`, "", md(spawn), "", "</details>", "");
470
+ }
303
471
  continue;
472
+ }
304
473
  const shown = r.functions.slice(0, FUNCTIONS_SHOWN);
305
474
  const more = r.functions.length - shown.length;
306
475
  const n = r.functions.length;
307
- out.push(`<details><summary>Functions in ${where}: ${n} function${n === 1 ? "" : "s"} changed</summary>`, "", "| Function | Base self | Head self | Δ |", "|---|---:|---:|---:|", ...shown.map((f) => `| ${md(clipName(f.name))} | ${fnCell(f.base)} | ${fnCell(f.head)} | ${f.delta === undefined ? "" : signed(f.delta)} |`), "", ...(more > 0 ? [`and ${more} more.`, ""] : []), `<sub>Self cycles, from ckb-debugger's profiler with the symbols build; — means not among the ${FUNCTION_LIMIT} costliest (or not recorded).</sub>`, "", "</details>", "");
476
+ out.push(`<details><summary>Functions in ${where}: ${n} function${n === 1 ? "" : "s"} changed</summary>`, "", "| Function | Base self | Head self | Δ |", "|---|---:|---:|---:|", ...shown.map((f) => `| ${md(clipName(f.name))} | ${fnCell(f.base)} | ${fnCell(f.head)} | ${f.delta === undefined ? "" : signed(f.delta)} |`), "", ...(more > 0 ? [`and ${more} more.`, ""] : []), ...(spawn ? [md(spawn), ""] : []), `<sub>Self cycles, from ckb-debugger's profiler with the symbols build; — means not among the ${FUNCTION_LIMIT} costliest (or not recorded).</sub>`, "", "</details>", "");
308
477
  }
309
478
  return out;
310
479
  }
311
480
  const fnCell = (n) => (n === undefined ? "—" : fmt(n));
481
+ /** What a function list leaves out when the script spawned others: their cycles. */
482
+ export function spawnNote(r) {
483
+ const n = r.spawned ?? 0;
484
+ const covers = r.profiled !== undefined && r.head?.cycles !== undefined ? ` (the profile covers ${fmt(r.profiled)} of its ${fmt(r.head.cycles)} cycles)` : "";
485
+ return (`This script spawned ${n} other script${n === 1 ? "" : "s"}: ${n === 1 ? "its" : "their"} cycles are in the group's total, ` +
486
+ `but not in these functions, which are the spawning script's own${covers}.`);
487
+ }
312
488
  /** The hidden marker that identifies the sticky comment, so it is updated instead of duplicated. */
313
489
  export const COMMENT_MARKER = "<!-- ckb-cycles-report -->";
314
490
  /**
@@ -336,7 +512,18 @@ export function formatMarkdown(diff, options = {}) {
336
512
  ? [`**Report errors** (nothing measured what they name):`, "", ...diff.reportErrors.slice(0, 20).map((e) => `- ${md(e)}`), ...(diff.reportErrors.length > 20 ? [`- and ${diff.reportErrors.length - 20} more`] : []), ""]
337
513
  : [];
338
514
  top.push(...errors);
339
- const footer = ["<sub>Generated by ckb-cycles (ckb-cycle-tools): each scenario replayed in ckb-debugger, one run per script group.</sub>"];
515
+ if (diff.overTxLimit?.length)
516
+ top.push(...overTxLimitBlock(diff.overTxLimit, md, "**"), "");
517
+ // Not the same environment: a gated check fails on it. Then what could not be checked.
518
+ if (diff.environment?.length) {
519
+ top.push(`**The base and head ran in different environments**: cycles can differ for that alone (a diff with fail-above or fail-on-result-change fails on it):`, "", ...diff.environment.slice(0, 20).map((e) => `- ${md(e)}`), ...(diff.environment.length > 20 ? [`- and ${diff.environment.length - 20} more`] : []), "");
520
+ }
521
+ if (diff.notes?.length)
522
+ top.push(...diff.notes.slice(0, 10).map((n) => `**Note:** ${md(n)}`), "");
523
+ const footer = [
524
+ ...manifestLines(diff).map((l) => `<sub>${md(l)}</sub>`),
525
+ "<sub>Generated by ckb-cycles (ckb-cycle-tools): each scenario replayed in ckb-debugger, one run per script group.</sub>",
526
+ ];
340
527
  let table = shown.length ? [head, ...shown.map(line), ""] : ["No script group changed its cycles or its result.", ""];
341
528
  let blocks = functionBlocks(shown);
342
529
  let warnings = diff.warnings?.length ? warningBlock(diff.warnings) : [];
@@ -377,6 +564,43 @@ export function formatMarkdown(diff, options = {}) {
377
564
  }
378
565
  return [...top, ...table, ...blocks, ...warnings, ...unchanged, ...footer].join("\n");
379
566
  }
567
+ const shortHash = (h) => (/^[0-9a-f]{12,}$/i.test(h) ? h.slice(0, 12) : h);
568
+ /**
569
+ * One line per side that has a manifest: tool, debugger (and its binary's
570
+ * hash), commit, toolchain. Plain text: the caller cleans it (md or termLine).
571
+ */
572
+ export function manifestLines(diff) {
573
+ const out = [];
574
+ for (const side of ["base", "head"]) {
575
+ const m = diff.manifests?.[side];
576
+ if (!m)
577
+ continue;
578
+ const parts = [
579
+ ...(m.debugger ? [`${m.debugger}${m.debuggerSha256 ? ` (sha256 ${shortHash(m.debuggerSha256)})` : m.wasm ? ` (wasm ${shortHash(m.wasm)})` : ""}`] : []),
580
+ ...(m.commit ? [`commit ${shortHash(m.commit)}`] : []),
581
+ ...(m.binariesCommit && m.binariesCommit !== m.commit ? [`binaries from ${shortHash(m.binariesCommit)}`] : []),
582
+ ...(m.toolchain ? [`toolchain: ${m.toolchain}`] : []),
583
+ ...(m.tool ? [m.tool] : []),
584
+ ];
585
+ if (parts.length)
586
+ out.push(`${side}: ${parts.join(" · ")}`);
587
+ }
588
+ return out;
589
+ }
590
+ /**
591
+ * The head scenarios newly over the node's per-transaction limit, one line each.
592
+ * `clean` cleans the scenario name (md or termLine); `strong` wraps the heading.
593
+ */
594
+ function overTxLimitBlock(over, clean, strong) {
595
+ const shown = over.slice(0, 20).map((o) => `- ${clean(o.scenario)}: ${fmt(o.sum)} cycles over the node's per-transaction limit of ${fmt(o.limit)}: ` +
596
+ `the node would reject this transaction (exceeded max cycles)${o.newScenario ? " (new scenario)" : " (under it on the base)"}`);
597
+ return [
598
+ `${strong}Over the node's per-transaction limit${strong}: ckb-debugger gives each group the whole limit, the node gives it to the whole transaction:`,
599
+ ...(strong ? [""] : []),
600
+ ...shown,
601
+ ...(over.length > shown.length ? [`- and ${over.length - shown.length} more`] : []),
602
+ ];
603
+ }
380
604
  /** How many scenario warnings a comment lists. */
381
605
  const WARNINGS_SHOWN = 50;
382
606
  /** The head's scenario warnings, folded: why a number may not be the build's (a binary no cell dep matched). */
@@ -424,18 +648,30 @@ export function formatText(diff) {
424
648
  .map((f) => `${termLine(f.name)} ${f.delta !== undefined ? signed(f.delta) : `${fnText(f.base)} → ${fnText(f.head)}`}`);
425
649
  const more = r.functions.length - top.length;
426
650
  functions.push(`functions in ${where}: ${top.join(", ")}${more > 0 ? `, and ${more} more` : ""}`);
651
+ if (r.spawned)
652
+ functions.push(` ${spawnNote(r)}`);
427
653
  }
654
+ else if (r.functions && r.spawned)
655
+ functions.push(`functions in ${where}: none of its own changed. ${spawnNote(r)}`);
428
656
  }
429
- const errors = (diff.reportErrors ?? []).map((e) => `error: ${termLine(e)}`);
657
+ const errors = [
658
+ ...(diff.overTxLimit?.length ? overTxLimitBlock(diff.overTxLimit, termLine, "") : []),
659
+ ...(diff.reportErrors ?? []).map((e) => `error: ${termLine(e)}`),
660
+ ];
661
+ const environment = (diff.environment ?? []).map((e) => `environment differs: ${termLine(e)}`);
662
+ const notes = (diff.notes ?? []).map((n) => `note: ${termLine(n)}`);
430
663
  const warnings = (diff.warnings ?? []).map((w) => `${termLine(w.scenario)}: warning: ${termLine(w.text)}`);
664
+ const manifest = manifestLines(diff).map((l) => termLine(`manifest ${l}`));
431
665
  return [
432
666
  summarize(diff),
433
667
  ...(errors.length ? ["", ...errors] : []),
668
+ ...(environment.length || notes.length ? ["", ...environment, ...notes] : []),
434
669
  "",
435
670
  line(header),
436
671
  ...rows.map(line),
437
672
  ...(functions.length ? ["", ...functions] : []),
438
673
  ...(warnings.length ? ["", ...warnings] : []),
674
+ ...(manifest.length ? ["", ...manifest] : []),
439
675
  ].join("\n");
440
676
  }
441
677
  const fnText = (n) => (n === undefined ? "?" : fmt(n));
package/dist/flame.d.ts CHANGED
@@ -61,5 +61,19 @@ export declare function renderFlameSvg(tree: FlameNode, opts?: {
61
61
  width?: number;
62
62
  minWidth?: number;
63
63
  }): string;
64
- /** The `All cycles: N` line ckb-debugger prints in flamegraph mode: what the profile covers. */
64
+ /**
65
+ * The `All cycles: N` line ckb-debugger prints in flamegraph mode: what the
66
+ * profile covers. The last one: when the script spawns other scripts, the
67
+ * debugger first runs the whole group (printing its full total) to record
68
+ * the syscalls, then profiles the root script alone ("Actual run").
69
+ */
65
70
  export declare function profiledCycles(output: string): bigint | undefined;
71
+ /**
72
+ * How many scripts the profiled script spawned (CKB2023 `spawn`), from the
73
+ * `Spawn tree:` lines ckb-debugger prints in flamegraph mode: one per VM,
74
+ * the root first (`Spawn tree: 0 …`, then `Spawn tree: └── 1 …`). 0 when
75
+ * there are none. The debugger profiles only the root VM, so the spawned
76
+ * scripts' cycles are in the group's total but in none of its frames. (A
77
+ * script could print such a line itself; this count only adds a note.)
78
+ */
79
+ export declare function spawnedScripts(output: string): number;
package/dist/flame.js CHANGED
@@ -192,8 +192,28 @@ function colour(name) {
192
192
  const light = 45 + ((h >>> 8) % 15);
193
193
  return `hsl(${hue} 75% ${light}%)`;
194
194
  }
195
- /** 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
+ */
196
201
  export function profiledCycles(output) {
197
- const m = /^All cycles:\s*(\d+)/m.exec(output);
198
- 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;
199
219
  }
package/dist/index.d.ts CHANGED
@@ -4,18 +4,19 @@ 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 { checkMockTransaction, checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
7
+ export { checkMockTransaction, checkTypeId, debuggerArgs, DEFAULT_TX_CYCLE_LIMIT, groupsOf, nodeOrder, nodeStop, nodeVerdict, overTxLimitLines, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, sumLines, } 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";
15
15
  export { substituteBinaries } from "./substitute.js";
16
16
  export type { AppliedSubstitution, BinarySubstitution } from "./substitute.js";
17
- export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, resultLabel, summarize, } from "./diff.js";
18
- export type { CycleDiff, CycleReport, DiffOptions, DiffRow, FunctionDelta, FunctionResult, GroupResult, MarkdownOptions, ScenarioResult } from "./diff.js";
17
+ export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, INPUTS_CHANGED, manifestLines, resultLabel, summarize, } from "./diff.js";
18
+ export type { CycleDiff, CycleReport, DiffOptions, DiffRow, FunctionDelta, FunctionResult, GroupResult, ManifestSummary, MarkdownOptions, ReportManifest, ScenarioManifest, ScenarioResult, } from "./diff.js";
19
+ export { canonicalJson, fileDigest, gitCommit, inputsHash, scenarioInputs, toolchainOf } from "./manifest.js";
19
20
  export { formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
20
21
  export type { BinaryConfig, CyclesConfig, ReportOptions, ScenarioConfig } from "./report.js";
21
22
  export { configFromMocks, formatScan, scanTestMocks } from "./scan.js";
package/dist/index.js CHANGED
@@ -1,11 +1,12 @@
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 { checkMockTransaction, checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
4
+ export { checkMockTransaction, checkTypeId, debuggerArgs, DEFAULT_TX_CYCLE_LIMIT, groupsOf, nodeOrder, nodeStop, nodeVerdict, overTxLimitLines, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, sumLines, } 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
- export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, resultLabel, summarize, } from "./diff.js";
9
+ export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, INPUTS_CHANGED, manifestLines, resultLabel, summarize, } from "./diff.js";
10
+ export { canonicalJson, fileDigest, gitCommit, inputsHash, scenarioInputs, toolchainOf } from "./manifest.js";
10
11
  export { formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
11
12
  export { configFromMocks, formatScan, scanTestMocks } from "./scan.js";
@@ -0,0 +1,37 @@
1
+ import type { ScenarioConfig } from "./report.js";
2
+ export declare const sha256: (data: Uint8Array | string) => string;
3
+ /** The sha256 and size of a file, read as a stream (a debugger binary is tens of MB). */
4
+ export declare function fileDigest(path: string): Promise<{
5
+ sha256: string;
6
+ size: number;
7
+ }>;
8
+ /** This package's name and version, from its package.json ("unknown" if it cannot be read). */
9
+ export declare function toolIdentity(): Promise<{
10
+ name: string;
11
+ version: string;
12
+ }>;
13
+ /**
14
+ * The commit checked out at `dir`, or undefined: not a git checkout, no git, or
15
+ * anything else. Never fails the report. Only a commit id is kept, whatever git printed.
16
+ */
17
+ export declare function gitCommit(dir: string): Promise<string | undefined>;
18
+ /** JSON with object keys sorted at every level: the same value always gives the same text. */
19
+ export declare function canonicalJson(value: unknown): string;
20
+ /**
21
+ * The part of a scenario's cycles.json entry that decides what runs: its form
22
+ * (and transaction hash), the binaries it names, its CKB-VM version, and for a
23
+ * transaction fetched from a node, the network. Not its name (the key it is
24
+ * matched by), the path of its file (whose bytes are hashed instead: a moved
25
+ * file with the same bytes is the same input), nor `functions` (which records
26
+ * names, not cycles).
27
+ */
28
+ export declare function scenarioInputs(s: ScenarioConfig, network: string | undefined): Record<string, unknown>;
29
+ /**
30
+ * sha256 over a scenario's inputs: the canonical entry (scenarioInputs), then
31
+ * the bytes of its mock or transaction file exactly as read, if it has one.
32
+ */
33
+ export declare function inputsHash(entry: Record<string, unknown>, file?: Uint8Array): string;
34
+ /** The longest toolchain description a report keeps. */
35
+ export declare const TOOLCHAIN_MAX = 4096;
36
+ /** A toolchain description as a report keeps it: trimmed, clipped; undefined when empty. */
37
+ export declare function toolchainOf(s: string | undefined): string | undefined;