ckb-cycle-tools 1.2.0 → 1.4.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,122 @@
4
4
  *
5
5
  * Pure: no network, no file system.
6
6
  */
7
+ import { asciiFrame } from "./flame.js";
8
+ /**
9
+ * A scenario's `overTxLimit`, read defensively (a report file is the PR's):
10
+ * undefined unless both numbers are there and the sum is over the limit.
11
+ */
12
+ export function overTxLimitOf(s) {
13
+ const o = s.overTxLimit;
14
+ if (!o || typeof o !== "object")
15
+ return undefined;
16
+ const { limit, sum } = o;
17
+ if (typeof limit !== "number" || typeof sum !== "number" || !(sum > limit))
18
+ return undefined;
19
+ return { limit, sum };
20
+ }
7
21
  /** How many functions a report keeps per group. */
8
22
  export const FUNCTION_LIMIT = 15;
23
+ /** The note on a group whose scenario's inputs differ between base and head. */
24
+ export const INPUTS_CHANGED = "inputs changed: the scenario's mock, transaction file or cycles.json entry differs from the base's";
25
+ const str = (v) => (typeof v === "string" && v ? v : undefined);
26
+ /**
27
+ * A report's manifest, read defensively: a report file is the PR's, any field
28
+ * may be missing or of another type. Undefined when there is none.
29
+ */
30
+ function manifestOf(r) {
31
+ const m = r.manifest;
32
+ if (!m || typeof m !== "object" || Array.isArray(m))
33
+ return undefined;
34
+ const d = (m.debugger && typeof m.debugger === "object" ? m.debugger : {});
35
+ const t = (m.tool && typeof m.tool === "object" ? m.tool : {});
36
+ const g = (m.git && typeof m.git === "object" ? m.git : undefined);
37
+ const scenarios = (Array.isArray(m.scenarios) ? m.scenarios : [])
38
+ .filter((s) => !!s && typeof s === "object" && typeof s.name === "string")
39
+ .map((s) => ({
40
+ name: s.name,
41
+ ...(typeof s.scriptVersion === "number" && { scriptVersion: s.scriptVersion }),
42
+ ...(str(s.inputs) && { inputs: str(s.inputs) }),
43
+ }));
44
+ return {
45
+ schema: 1,
46
+ tool: { name: str(t.name) ?? "", version: str(t.version) ?? "" },
47
+ debugger: {
48
+ version: str(d.version) ?? "",
49
+ ...(str(d.sha256) && { sha256: str(d.sha256) }),
50
+ ...(str(d.wasm) && { wasm: str(d.wasm) }),
51
+ },
52
+ ...(g && { git: { ...(str(g.commit) && { commit: str(g.commit) }), ...(str(g.binaries) && { binaries: str(g.binaries) }) } }),
53
+ ...(str(m.toolchain) && { toolchain: str(m.toolchain) }),
54
+ scenarios,
55
+ };
56
+ }
57
+ function summaryOf(m) {
58
+ return {
59
+ ...(m.tool.version && { tool: `${m.tool.name || "ckb-cycle-tools"} ${m.tool.version}` }),
60
+ ...(m.debugger.version && { debugger: m.debugger.version }),
61
+ ...(m.debugger.sha256 && { debuggerSha256: m.debugger.sha256 }),
62
+ ...(m.debugger.wasm && { wasm: m.debugger.wasm }),
63
+ ...(m.git?.commit && { commit: m.git.commit }),
64
+ ...(m.git?.binaries && { binariesCommit: m.git.binaries }),
65
+ ...(m.toolchain && { toolchain: m.toolchain }),
66
+ };
67
+ }
68
+ /**
69
+ * What the two manifests say about comparability: the scenarios whose inputs
70
+ * changed, environment differences (a gated diff fails on them), and notes.
71
+ * Text from the manifests goes in as is: the formatters clean it.
72
+ */
73
+ function compareManifests(base, head) {
74
+ const bm = manifestOf(base);
75
+ const hm = manifestOf(head);
76
+ const changed = new Set();
77
+ const environment = [];
78
+ const notes = [];
79
+ // A side with nothing measured (the Action's placeholder for a base without a
80
+ // cycles.json, or whose build failed) has nothing to check: no note for it.
81
+ const measured = (r) => r.scenarios.some((s) => !s.error);
82
+ // Two reports without one (both before 1.3.0) diff as they always did.
83
+ for (const [side, r, m] of [["base", base, bm], ["head", head, hm]]) {
84
+ if (!m && (bm || hm) && measured(r)) {
85
+ 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`);
86
+ }
87
+ }
88
+ if (bm && hm) {
89
+ const bd = bm.debugger;
90
+ const hd = hm.debugger;
91
+ // "unknown": no scenario ran on that side, which is an error row of its own.
92
+ const known = (v) => v && v !== "unknown";
93
+ if (known(bd.version) && known(hd.version) && bd.version !== hd.version)
94
+ environment.push(`ckb-debugger version: base ${bd.version}, head ${hd.version}`);
95
+ if (bd.sha256 && hd.sha256 && bd.sha256 !== hd.sha256) {
96
+ environment.push(`ckb-debugger binary: base sha256 ${bd.sha256}, head sha256 ${hd.sha256}`);
97
+ }
98
+ if (bd.wasm && hd.wasm && bd.wasm !== hd.wasm)
99
+ environment.push(`ckb-debugger WebAssembly build: base ${bd.wasm}, head ${hd.wasm}`);
100
+ if ((bd.wasm && hd.sha256 && !hd.wasm) || (hd.wasm && bd.sha256 && !bd.wasm)) {
101
+ environment.push(`ckb-debugger: one side ran the native binary, the other the WebAssembly build`);
102
+ }
103
+ const bs = new Map(bm.scenarios.map((s) => [s.name, s]));
104
+ for (const h of hm.scenarios) {
105
+ const b = bs.get(h.name);
106
+ if (!b)
107
+ continue;
108
+ if (b.inputs && h.inputs && b.inputs !== h.inputs) {
109
+ changed.add(h.name);
110
+ continue;
111
+ }
112
+ if (b.scriptVersion !== undefined && h.scriptVersion !== undefined && b.scriptVersion !== h.scriptVersion) {
113
+ environment.push(`scenario ${h.name}: CKB-VM version ${b.scriptVersion} on the base, ${h.scriptVersion} on the head`);
114
+ }
115
+ }
116
+ if ((bm.toolchain ?? "") !== (hm.toolchain ?? "") && bm.toolchain && hm.toolchain) {
117
+ notes.push(`the toolchain differs: base ${bm.toolchain}; head ${hm.toolchain}`);
118
+ }
119
+ }
120
+ const manifests = bm || hm ? { ...(bm && { base: summaryOf(bm) }), ...(hm && { head: summaryOf(hm) }) } : undefined;
121
+ return { changed, environment, notes, manifests };
122
+ }
9
123
  /** The message for a binary no scenario's cell deps match, in a report's `errors` and the diff. */
10
124
  export const unmatchedError = (name) => `binary "${name}" matched no cell dep in any scenario: check its outPoint / codeHash`;
11
125
  /** The base side of a new group that does not accept: compared with "did not run". */
@@ -31,6 +145,7 @@ export function diffReports(base, head, options = {}) {
31
145
  const rows = [];
32
146
  const baseByName = new Map(base.scenarios.map((s) => [s.name, s]));
33
147
  const headNames = new Set(head.scenarios.map((s) => s.name));
148
+ const manifests = compareManifests(base, head);
34
149
  const scenarioRows = (h, b) => {
35
150
  const name = (h ?? b).name;
36
151
  if (h?.error) {
@@ -45,30 +160,46 @@ export function diffReports(base, head, options = {}) {
45
160
  rows.push({ scenario: name, group: "", script: "", kind: "base-error", overThreshold: false, note: `base: ${b.error}` });
46
161
  }
47
162
  const baseGroups = new Map((b && !b.error ? b.groups : []).map((g) => [g.selector, g]));
163
+ // Inputs that differ: the two sides did not run the same transaction, so no group is compared.
164
+ const inputs = h && b && manifests.changed.has(name) ? INPUTS_CHANGED : undefined;
48
165
  for (const g of h?.groups ?? []) {
49
- rows.push(groupRow(name, baseGroups.get(g.selector), g, threshold));
166
+ rows.push(groupRow(name, baseGroups.get(g.selector), g, threshold, inputs));
50
167
  baseGroups.delete(g.selector);
51
168
  }
52
169
  for (const g of baseGroups.values())
53
- rows.push(groupRow(name, g, undefined, threshold));
170
+ rows.push(groupRow(name, g, undefined, threshold, inputs));
54
171
  };
55
172
  for (const h of head.scenarios)
56
173
  scenarioRows(h, baseByName.get(h.name));
57
174
  for (const b of base.scenarios)
58
175
  if (!headNames.has(b.name))
59
176
  scenarioRows(undefined, b);
177
+ // Over the node's per-transaction limit on the head, and not on the base: a rejection the groups do not show.
178
+ const overTxLimit = head.scenarios.flatMap((h) => {
179
+ const o = h.error ? undefined : overTxLimitOf(h);
180
+ const b = baseByName.get(h.name);
181
+ if (!o || (b && !b.error && overTxLimitOf(b)))
182
+ return [];
183
+ return [{ scenario: h.name, ...o, ...(!b || b.error ? { newScenario: true } : {}) }];
184
+ });
60
185
  const groups = rows.filter((r) => r.kind !== "error" && r.kind !== "base-error");
186
+ const unpaired = groups.filter((r) => r.inputsChanged);
61
187
  return {
62
188
  rows,
63
189
  resultChanges: rows.filter((r) => r.kind === "result").length,
64
190
  overThreshold: rows.filter((r) => r.overThreshold).length,
65
191
  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,
192
+ removed: groups.filter((r) => (r.kind === "removed" || r.notCompared) && !r.inputsChanged).length,
193
+ newGroups: groups.filter((r) => r.kind !== "removed" && !r.inputsChanged && (!r.base || r.base.result === NOT_RUN)).length,
68
194
  reportErrors: [...reportErrors("base", base), ...reportErrors("head", head)],
69
195
  warnings: head.scenarios.flatMap((s) => (s.warnings ?? []).map((text) => ({ scenario: s.name, text }))),
70
196
  ...(base.debugger && head.debugger && base.debugger !== head.debugger && { debuggers: { base: base.debugger, head: head.debugger } }),
71
197
  ...(threshold !== undefined && { threshold }),
198
+ ...(unpaired.length && { inputsChanged: unpaired.length, changedScenarios: [...new Set(unpaired.map((r) => r.scenario))] }),
199
+ ...(manifests.environment.length && { environment: manifests.environment }),
200
+ ...(manifests.notes.length && { notes: manifests.notes }),
201
+ ...(manifests.manifests && { manifests: manifests.manifests }),
202
+ ...(overTxLimit.length && { overTxLimit }),
72
203
  };
73
204
  }
74
205
  /**
@@ -88,10 +219,11 @@ function reportErrors(side, r) {
88
219
  }
89
220
  return [...out].map((e) => `${side}: ${e}`);
90
221
  }
91
- function groupRow(scenario, measured, h, threshold) {
222
+ function groupRow(scenario, measured, h, threshold, inputsChanged) {
92
223
  const side = (g) => ({ result: resultLabel(g), cycles: g.cycles });
93
224
  // 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;
225
+ // Or measured on other inputs: not the same transaction.
226
+ const b = h && (measured?.missingBinary || inputsChanged) ? undefined : measured;
95
227
  const row = {
96
228
  scenario,
97
229
  group: (h ?? b).selector,
@@ -103,6 +235,10 @@ function groupRow(scenario, measured, h, threshold) {
103
235
  };
104
236
  if (measured?.missingBinary)
105
237
  row.notCompared = `binary "${measured.missingBinary}" is not in the base checkout`;
238
+ if (inputsChanged) {
239
+ row.notCompared = inputsChanged;
240
+ row.inputsChanged = true;
241
+ }
106
242
  if (b && h) {
107
243
  row.delta = h.cycles - b.cycles;
108
244
  const changed = resultLabel(b) !== resultLabel(h);
@@ -134,15 +270,77 @@ function groupRow(scenario, measured, h, threshold) {
134
270
  row.spawned = h.spawned;
135
271
  if (h.profiled !== undefined)
136
272
  row.profiled = h.profiled;
273
+ const head = childrenOf(h);
274
+ if (head)
275
+ row.children = childDeltas(childrenOf(b), head);
276
+ if (typeof h.childrenNote === "string" && h.childrenNote)
277
+ row.childrenNote = h.childrenNote;
137
278
  }
138
279
  return row;
139
280
  }
281
+ /** A group's `children`, read defensively (a report file is the PR's): entries without a VM id or a name are dropped. */
282
+ function childrenOf(g) {
283
+ const list = g?.children;
284
+ if (!Array.isArray(list))
285
+ return undefined;
286
+ const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
287
+ return list
288
+ .filter((c) => !!c && typeof c === "object" && Number.isInteger(c.vm) && typeof c.script === "string")
289
+ .map((c) => ({
290
+ vm: c.vm,
291
+ parent: num(c.parent) ?? 0,
292
+ script: c.script,
293
+ ...(num(c.result) !== undefined && { result: num(c.result) }),
294
+ ...(str(c.error) && { error: str(c.error) }),
295
+ ...(num(c.profiled) !== undefined && { profiled: num(c.profiled) }),
296
+ ...(Array.isArray(c.functions) && {
297
+ functions: c.functions.filter((f) => !!f && typeof f === "object" && typeof f.name === "string" && num(f.self) !== undefined),
298
+ }),
299
+ ...(str(c.functionsWarning) && { functionsWarning: str(c.functionsWarning) }),
300
+ ...(str(c.failed) && { failed: str(c.failed) }),
301
+ }));
302
+ }
303
+ const childLabel = (c) => c.failed || c.result === undefined ? "not profiled" : resultLabel({ result: c.result, ...(c.error && { error: c.error }) });
304
+ /**
305
+ * Each spawned script on both sides, by VM id, in VM order. Without base
306
+ * children (an older report, an older debugger) every head child has no base
307
+ * side: what it costs is shown, not a change.
308
+ */
309
+ export function childDeltas(base, head) {
310
+ const vms = [...new Set([...head.map((c) => c.vm), ...(base ?? []).map((c) => c.vm)])].sort((x, y) => x - y);
311
+ return vms.map((vm) => {
312
+ const b = base?.find((c) => c.vm === vm);
313
+ const h = head.find((c) => c.vm === vm);
314
+ const side = (c) => ({ result: childLabel(c), ...(c.profiled !== undefined && !c.failed && { profiled: c.profiled }) });
315
+ const d = {
316
+ vm,
317
+ script: (h ?? b).script,
318
+ ...(b && { base: side(b) }),
319
+ ...(h && { head: side(h) }),
320
+ changed: false,
321
+ };
322
+ if (d.base?.profiled !== undefined && d.head?.profiled !== undefined)
323
+ d.delta = d.head.profiled - d.base.profiled;
324
+ d.changed = base !== undefined && (!b || !h || d.base.result !== d.head.result || (d.delta ?? 0) !== 0);
325
+ if (h?.functions)
326
+ d.functions = functionDeltas(b?.functions, h.functions);
327
+ const note = h?.failed ?? h?.functionsWarning;
328
+ if (note)
329
+ d.note = note;
330
+ return d;
331
+ });
332
+ }
140
333
  /**
141
334
  * The functions whose self cycles differ between two lists, largest change
142
335
  * first. One whose other side is not known (see FunctionDelta) is kept, ranked
143
336
  * by the side that is.
144
337
  */
145
338
  export function functionDeltas(base, head) {
339
+ // A report written by an older ckb-cycle-tools with a newer ckb-debugger can
340
+ // name `[u8; 32]` with a U+037E for the `;`: the same function either way.
341
+ const ascii = (list) => list.map((f) => ({ ...f, name: asciiFrame(f.name) }));
342
+ base = base && ascii(base);
343
+ head = ascii(head);
146
344
  const side = (list, name) => {
147
345
  if (!list)
148
346
  return undefined;
@@ -167,17 +365,33 @@ export function functionDeltas(base, head) {
167
365
  * run, an error in either report, and a base group with nothing to compare
168
366
  * against (removed, renamed, moved, or measured without its binary) unless
169
367
  * `allowRemoved`. A head group the VM stopped is a result change, and over any
170
- * `failAbove` threshold.
368
+ * `failAbove` threshold. With a gate set, a group that accepted on the base and
369
+ * rejects on the head (`ok` → `exit N` or a VM error) always fails, whatever its
370
+ * cycles: a cheaper rejection is not a saving. `failOnResultChange` fails on any
371
+ * result change besides (reject → accept, one exit code or VM error to another,
372
+ * a new group that does not accept). A new group has no base that accepted, so
373
+ * this rule leaves it alone: with `failAbove` alone it fails only as before (a
374
+ * new group the VM stopped is over the threshold). A scenario whose groups add
375
+ * up to more than the node's per-transaction limit on the head, and not on the
376
+ * base, counts as a group that starts rejecting (the node would reject it); a
377
+ * new scenario over the limit, as a new group that does not accept.
171
378
  */
172
379
  export function diffFailed(diff, options = {}) {
173
380
  const gated = options.failAbove !== undefined || options.failOnResultChange === true;
174
381
  return ((options.failAbove !== undefined && diff.overThreshold > 0) ||
175
382
  (options.failOnResultChange === true && diff.resultChanges > 0) ||
383
+ (gated && diff.rows.some(nowRejects)) ||
384
+ (gated && (diff.overTxLimit ?? []).some((o) => !o.newScenario)) ||
385
+ (options.failOnResultChange === true && (diff.overTxLimit?.length ?? 0) > 0) ||
176
386
  (gated && diff.baseErrors > 0) ||
177
387
  (gated && (diff.reportErrors?.length ?? 0) > 0) ||
178
388
  (gated && !options.allowRemoved && (diff.removed ?? 0) > 0) ||
389
+ (gated && !options.allowChangedInputs && (diff.inputsChanged ?? 0) > 0) ||
390
+ (gated && (diff.environment?.length ?? 0) > 0) ||
179
391
  diff.rows.some((r) => r.kind === "error"));
180
392
  }
393
+ /** A group that accepted on the base and rejects (an exit code or a VM error) on the head. */
394
+ const nowRejects = (r) => r.kind === "result" && r.base?.result === "ok" && r.head !== undefined && r.head.result !== "ok";
181
395
  const fmt = (n) => n.toLocaleString("en-US");
182
396
  const signed = (n) => (n > 0 ? `+${fmt(n)}` : n < 0 ? `-${fmt(-n)}` : "0");
183
397
  const pct = (p) => p === undefined ? "" : p === 0 ? "0%" : `${p > 0 ? "+" : "-"}${Math.abs(p) < 0.01 ? "<0.01" : Math.abs(p).toFixed(2)}%`;
@@ -188,11 +402,11 @@ function note(r, threshold) {
188
402
  case "result":
189
403
  return r.base.result === NOT_RUN
190
404
  ? `NEW, DOES NOT ACCEPT: ${r.head.result}${unpaired}`
191
- : `RESULT CHANGED: ${r.base.result} → ${r.head.result}`;
405
+ : `RESULT CHANGED: ${r.base.result} → ${r.head.result}${nowRejects(r) ? " (accepted on the base, rejects now)" : ""}`;
192
406
  case "new":
193
407
  return r.notCompared ? `NOT COMPARED: ${r.notCompared}` : "new";
194
408
  case "removed":
195
- return "REMOVED: no head group to compare with";
409
+ return r.inputsChanged ? `NOT IN THE HEAD (NOT COMPARED: ${r.notCompared})` : "REMOVED: no head group to compare with";
196
410
  case "error":
197
411
  return r.note ?? "error";
198
412
  case "base-error":
@@ -211,11 +425,14 @@ export function summarize(diff, clean = termLine) {
211
425
  const changed = groups.filter((r) => r.kind !== "same").length;
212
426
  const errors = diff.rows.filter((r) => r.kind === "error").length;
213
427
  // A new group has no base, so no percentage: the threshold cannot apply to it.
214
- const unchecked = diff.threshold === undefined ? 0 : groups.filter((r) => !r.base || r.base.result === NOT_RUN).length;
428
+ const unchecked = diff.threshold === undefined ? 0 : groups.filter((r) => !r.inputsChanged && (!r.base || r.base.result === NOT_RUN)).length;
215
429
  const s = (n) => (n > 1 ? "s" : "");
216
430
  const parts = [
217
431
  ...(diff.resultChanges ? [`${diff.resultChanges} result change${s(diff.resultChanges)}`] : []),
218
432
  ...(diff.overThreshold ? [`${diff.overThreshold} over the ${diff.threshold}% threshold`] : []),
433
+ ...(diff.overTxLimit?.length
434
+ ? [`${diff.overTxLimit.length} scenario${s(diff.overTxLimit.length)} over the node's per-transaction cycle limit (the node would reject)`]
435
+ : []),
219
436
  ...(errors ? [`${errors} scenario${s(errors)} failed to run`] : []),
220
437
  ...(diff.baseErrors ? [`${diff.baseErrors} scenario${s(diff.baseErrors)} could not run on the base`] : []),
221
438
  `${changed} of ${groups.length} script group${groups.length === 1 ? "" : "s"} changed`,
@@ -228,6 +445,10 @@ export function summarize(diff, clean = termLine) {
228
445
  ? [`${diff.removed} base group${s(diff.removed)} with nothing in the head to compare with (removed, renamed, moved or not built on the base)`]
229
446
  : []),
230
447
  ...(diff.reportErrors?.length ? [`${diff.reportErrors.length} report error${s(diff.reportErrors.length)}`] : []),
448
+ ...(diff.inputsChanged
449
+ ? [`${diff.inputsChanged} group${s(diff.inputsChanged)} NOT COMPARED: the inputs of ${diff.changedScenarios?.length ?? 0} scenario${s(diff.changedScenarios?.length ?? 0)} changed`]
450
+ : []),
451
+ ...(diff.environment?.length ? [`the base and head ran in different environments (${diff.environment.length} difference${s(diff.environment.length)})`] : []),
231
452
  ...(diff.debuggers
232
453
  ? [`the reports come from different debuggers (base ${clean(diff.debuggers.base)}, head ${clean(diff.debuggers.head)}): cycles can differ for that alone`]
233
454
  : []),
@@ -310,13 +531,53 @@ function functionBlocks(rows) {
310
531
  if (spawn && r.functions && r.kind !== "same") {
311
532
  out.push(`<details><summary>Functions in ${where}: none of its own changed</summary>`, "", md(spawn), "", "</details>", "");
312
533
  }
534
+ out.push(...childBlock(r, where));
313
535
  continue;
314
536
  }
315
537
  const shown = r.functions.slice(0, FUNCTIONS_SHOWN);
316
538
  const more = r.functions.length - shown.length;
317
539
  const n = r.functions.length;
318
540
  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>", "");
541
+ out.push(...childBlock(r, where));
542
+ }
543
+ return out;
544
+ }
545
+ /** A folded block per spawning group with child profiles: which spawned script changed, and its functions. */
546
+ function childBlock(r, where) {
547
+ if (r.kind === "same" || (!r.children?.length && !r.childrenNote))
548
+ return [];
549
+ const kids = r.children ?? [];
550
+ const compared = kids.some((c) => c.base);
551
+ const changed = kids.filter((c) => c.changed);
552
+ const summary = !kids.length
553
+ ? "not profiled"
554
+ : !compared
555
+ ? `${kids.length} profiled`
556
+ : changed.length
557
+ ? changed
558
+ .slice(0, 3)
559
+ .map((c) => `vm ${c.vm} ${html(c.script)} ${c.delta !== undefined && c.base && c.head ? signed(c.delta) : !c.base ? "new" : !c.head ? "gone" : html(c.head.result)}`)
560
+ .join(", ") + (changed.length > 3 ? `, and ${changed.length - 3} more` : "")
561
+ : "none changed";
562
+ const out = [`<details><summary>Spawned scripts in ${where}: ${summary}</summary>`, ""];
563
+ if (kids.length) {
564
+ out.push("| VM | Script | Base profiled | Head profiled | Δ |", "|---|---|---:|---:|---:|");
565
+ for (const c of kids) {
566
+ out.push(`| ${c.vm} | ${md(clipName(c.script))} | ${md(childSide(c.base))} | ${md(childSide(c.head))} | ${c.delta === undefined ? "" : signed(c.delta)} |`);
567
+ }
568
+ out.push("");
319
569
  }
570
+ for (const c of kids) {
571
+ const fns = (c.functions ?? []).slice(0, FUNCTIONS_SHOWN);
572
+ if (fns.length && (c.changed || !compared)) {
573
+ out.push(`Functions of vm ${c.vm} (${md(clipName(c.script))}):`, "", "| Function | Base self | Head self | Δ |", "|---|---:|---:|---:|", ...fns.map((f) => `| ${md(clipName(f.name))} | ${fnCell(f.base)} | ${fnCell(f.head)} | ${f.delta === undefined ? "" : signed(f.delta)} |`), "");
574
+ }
575
+ if (c.note)
576
+ out.push(`vm ${c.vm}: ${md(c.note)}`, "");
577
+ }
578
+ if (r.childrenNote)
579
+ out.push(md(r.childrenNote), "");
580
+ out.push(`<sub>${md(CHILDREN_FOOTNOTE)}</sub>`, "", "</details>", "");
320
581
  return out;
321
582
  }
322
583
  const fnCell = (n) => (n === undefined ? "—" : fmt(n));
@@ -324,9 +585,20 @@ const fnCell = (n) => (n === undefined ? "—" : fmt(n));
324
585
  export function spawnNote(r) {
325
586
  const n = r.spawned ?? 0;
326
587
  const covers = r.profiled !== undefined && r.head?.cycles !== undefined ? ` (the profile covers ${fmt(r.profiled)} of its ${fmt(r.head.cycles)} cycles)` : "";
588
+ const own = r.children?.length ? ` ${n === 1 ? "Its" : "Their"} own profile${n === 1 ? " is" : "s are"} listed separately.` : "";
327
589
  return (`This script spawned ${n} other script${n === 1 ? "" : "s"}: ${n === 1 ? "its" : "their"} cycles are in the group's total, ` +
328
- `but not in these functions, which are the spawning script's own${covers}.`);
590
+ `but not in these functions, which are the spawning script's own${covers}.${own}`);
329
591
  }
592
+ /** What a spawned script's numbers are, under every list of them. */
593
+ export const CHILDREN_FOOTNOTE = "Profiled frames of each spawned script, from a ckb-debugger --vm-id replay of it: they leave out loading its binary and what the spawn costs the parent, so they do not add up to the group's cycles, which stay the total.";
594
+ const childSide = (s) => !s ? "—" : s.profiled === undefined ? s.result : s.result === "ok" ? fmt(s.profiled) : `${fmt(s.profiled)} (${s.result})`;
595
+ /** `vm 1 (spawn-child): profiled 19,093 → 635,605 (+616,512)`, plain text: the caller cleans it. */
596
+ function childLine(c) {
597
+ const what = !c.base ? `new, profiled ${childSide(c.head)}` : !c.head ? `gone (was ${childSide(c.base)})` : `profiled ${childSide(c.base)} → ${childSide(c.head)}${c.delta ? ` (${signed(c.delta)})` : ""}`;
598
+ return `vm ${c.vm} (${c.script}): ${what}`;
599
+ }
600
+ /** A spawned script's profile on the head alone (no base children to compare with). */
601
+ const childHeadLine = (c) => `vm ${c.vm} (${c.script}): profiled ${childSide(c.head)}`;
330
602
  /** The hidden marker that identifies the sticky comment, so it is updated instead of duplicated. */
331
603
  export const COMMENT_MARKER = "<!-- ckb-cycles-report -->";
332
604
  /**
@@ -354,7 +626,18 @@ export function formatMarkdown(diff, options = {}) {
354
626
  ? [`**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`] : []), ""]
355
627
  : [];
356
628
  top.push(...errors);
357
- const footer = ["<sub>Generated by ckb-cycles (ckb-cycle-tools): each scenario replayed in ckb-debugger, one run per script group.</sub>"];
629
+ if (diff.overTxLimit?.length)
630
+ top.push(...overTxLimitBlock(diff.overTxLimit, md, "**"), "");
631
+ // Not the same environment: a gated check fails on it. Then what could not be checked.
632
+ if (diff.environment?.length) {
633
+ 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`] : []), "");
634
+ }
635
+ if (diff.notes?.length)
636
+ top.push(...diff.notes.slice(0, 10).map((n) => `**Note:** ${md(n)}`), "");
637
+ const footer = [
638
+ ...manifestLines(diff).map((l) => `<sub>${md(l)}</sub>`),
639
+ "<sub>Generated by ckb-cycles (ckb-cycle-tools): each scenario replayed in ckb-debugger, one run per script group.</sub>",
640
+ ];
358
641
  let table = shown.length ? [head, ...shown.map(line), ""] : ["No script group changed its cycles or its result.", ""];
359
642
  let blocks = functionBlocks(shown);
360
643
  let warnings = diff.warnings?.length ? warningBlock(diff.warnings) : [];
@@ -395,6 +678,43 @@ export function formatMarkdown(diff, options = {}) {
395
678
  }
396
679
  return [...top, ...table, ...blocks, ...warnings, ...unchanged, ...footer].join("\n");
397
680
  }
681
+ const shortHash = (h) => (/^[0-9a-f]{12,}$/i.test(h) ? h.slice(0, 12) : h);
682
+ /**
683
+ * One line per side that has a manifest: tool, debugger (and its binary's
684
+ * hash), commit, toolchain. Plain text: the caller cleans it (md or termLine).
685
+ */
686
+ export function manifestLines(diff) {
687
+ const out = [];
688
+ for (const side of ["base", "head"]) {
689
+ const m = diff.manifests?.[side];
690
+ if (!m)
691
+ continue;
692
+ const parts = [
693
+ ...(m.debugger ? [`${m.debugger}${m.debuggerSha256 ? ` (sha256 ${shortHash(m.debuggerSha256)})` : m.wasm ? ` (wasm ${shortHash(m.wasm)})` : ""}`] : []),
694
+ ...(m.commit ? [`commit ${shortHash(m.commit)}`] : []),
695
+ ...(m.binariesCommit && m.binariesCommit !== m.commit ? [`binaries from ${shortHash(m.binariesCommit)}`] : []),
696
+ ...(m.toolchain ? [`toolchain: ${m.toolchain}`] : []),
697
+ ...(m.tool ? [m.tool] : []),
698
+ ];
699
+ if (parts.length)
700
+ out.push(`${side}: ${parts.join(" · ")}`);
701
+ }
702
+ return out;
703
+ }
704
+ /**
705
+ * The head scenarios newly over the node's per-transaction limit, one line each.
706
+ * `clean` cleans the scenario name (md or termLine); `strong` wraps the heading.
707
+ */
708
+ function overTxLimitBlock(over, clean, strong) {
709
+ 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)}: ` +
710
+ `the node would reject this transaction (exceeded max cycles)${o.newScenario ? " (new scenario)" : " (under it on the base)"}`);
711
+ return [
712
+ `${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:`,
713
+ ...(strong ? [""] : []),
714
+ ...shown,
715
+ ...(over.length > shown.length ? [`- and ${over.length - shown.length} more`] : []),
716
+ ];
717
+ }
398
718
  /** How many scenario warnings a comment lists. */
399
719
  const WARNINGS_SHOWN = 50;
400
720
  /** The head's scenario warnings, folded: why a number may not be the build's (a binary no cell dep matched). */
@@ -447,17 +767,42 @@ export function formatText(diff) {
447
767
  }
448
768
  else if (r.functions && r.spawned)
449
769
  functions.push(`functions in ${where}: none of its own changed. ${spawnNote(r)}`);
770
+ if (r.children?.length) {
771
+ const compared = r.children.some((c) => c.base);
772
+ const kids = compared ? r.children.filter((c) => c.changed) : r.children;
773
+ if (!kids.length)
774
+ functions.push(` spawned scripts: none changed (profiled frames)`);
775
+ for (const c of kids) {
776
+ const fns = (c.functions ?? [])
777
+ .filter((f) => f.delta !== undefined)
778
+ .slice(0, 3)
779
+ .map((f) => `${termLine(f.name)} ${signed(f.delta)}`);
780
+ functions.push(` spawned ${termLine(compared ? childLine(c) : childHeadLine(c))}${fns.length ? `; ${fns.join(", ")}` : ""}`);
781
+ if (c.note)
782
+ functions.push(` ${termLine(c.note)}`);
783
+ }
784
+ }
785
+ if (r.childrenNote)
786
+ functions.push(` spawned scripts: ${termLine(r.childrenNote)}`);
450
787
  }
451
- const errors = (diff.reportErrors ?? []).map((e) => `error: ${termLine(e)}`);
788
+ const errors = [
789
+ ...(diff.overTxLimit?.length ? overTxLimitBlock(diff.overTxLimit, termLine, "") : []),
790
+ ...(diff.reportErrors ?? []).map((e) => `error: ${termLine(e)}`),
791
+ ];
792
+ const environment = (diff.environment ?? []).map((e) => `environment differs: ${termLine(e)}`);
793
+ const notes = (diff.notes ?? []).map((n) => `note: ${termLine(n)}`);
452
794
  const warnings = (diff.warnings ?? []).map((w) => `${termLine(w.scenario)}: warning: ${termLine(w.text)}`);
795
+ const manifest = manifestLines(diff).map((l) => termLine(`manifest ${l}`));
453
796
  return [
454
797
  summarize(diff),
455
798
  ...(errors.length ? ["", ...errors] : []),
799
+ ...(environment.length || notes.length ? ["", ...environment, ...notes] : []),
456
800
  "",
457
801
  line(header),
458
802
  ...rows.map(line),
459
803
  ...(functions.length ? ["", ...functions] : []),
460
804
  ...(warnings.length ? ["", ...warnings] : []),
805
+ ...(manifest.length ? ["", ...manifest] : []),
461
806
  ].join("\n");
462
807
  }
463
808
  const fnText = (n) => (n === undefined ? "?" : fmt(n));
package/dist/elf.d.ts CHANGED
@@ -16,3 +16,16 @@ export declare function elfFunctionNames(elf: Uint8Array): Map<bigint, string>;
16
16
  * still a stable name, only a less readable one.
17
17
  */
18
18
  export declare function demangle(name: string): string;
19
+ /**
20
+ * The code a CKB-VM runs from an ELF: the entry point and each executable
21
+ * `PT_LOAD` segment (its address and the bytes the file gives it), in program
22
+ * header order. A build and its stripped copy have the same code; the
23
+ * stripped one only loses sections no segment loads (symbols, debug info).
24
+ * Undefined for anything that is not a 64-bit little-endian ELF with code.
25
+ */
26
+ export declare function elfCode(elf: Uint8Array): Uint8Array | undefined;
27
+ /**
28
+ * Whether two ELFs run the same code (elfCode): an unstripped build and the
29
+ * binary it stands for. Undefined when either is not an ELF this can read.
30
+ */
31
+ export declare function sameCode(a: Uint8Array, b: Uint8Array): boolean | undefined;
package/dist/elf.js CHANGED
@@ -207,3 +207,55 @@ function demangleV0(name) {
207
207
  const rest = name.slice(i);
208
208
  return rest === "" || rest.startsWith("C") || rest.startsWith(".") ? p : undefined;
209
209
  }
210
+ /**
211
+ * The code a CKB-VM runs from an ELF: the entry point and each executable
212
+ * `PT_LOAD` segment (its address and the bytes the file gives it), in program
213
+ * header order. A build and its stripped copy have the same code; the
214
+ * stripped one only loses sections no segment loads (symbols, debug info).
215
+ * Undefined for anything that is not a 64-bit little-endian ELF with code.
216
+ */
217
+ export function elfCode(elf) {
218
+ if (elf.length < 64 || elf[0] !== 0x7f || elf[1] !== 0x45 || elf[2] !== 0x4c || elf[3] !== 0x46)
219
+ return undefined;
220
+ if (elf[4] !== 2 || elf[5] !== 1)
221
+ return undefined;
222
+ const view = new DataView(elf.buffer, elf.byteOffset, elf.byteLength);
223
+ const phoff = Number(view.getBigUint64(0x20, true));
224
+ const phentsize = view.getUint16(0x36, true);
225
+ const phnum = view.getUint16(0x38, true);
226
+ if (phentsize < 56 || phoff + phentsize * phnum > elf.length)
227
+ return undefined;
228
+ const parts = [elf.subarray(0x18, 0x20)];
229
+ for (let i = 0; i < phnum; i++) {
230
+ const o = phoff + i * phentsize;
231
+ const PT_LOAD = 1;
232
+ const PF_X = 1;
233
+ if (view.getUint32(o, true) !== PT_LOAD || !(view.getUint32(o + 4, true) & PF_X))
234
+ continue;
235
+ const offset = Number(view.getBigUint64(o + 8, true));
236
+ const size = Number(view.getBigUint64(o + 0x20, true));
237
+ if (offset + size > elf.length)
238
+ return undefined;
239
+ parts.push(elf.subarray(o + 0x10, o + 0x18), elf.subarray(offset, offset + size));
240
+ }
241
+ if (parts.length === 1)
242
+ return undefined;
243
+ const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
244
+ let at = 0;
245
+ for (const p of parts) {
246
+ out.set(p, at);
247
+ at += p.length;
248
+ }
249
+ return out;
250
+ }
251
+ /**
252
+ * Whether two ELFs run the same code (elfCode): an unstripped build and the
253
+ * binary it stands for. Undefined when either is not an ELF this can read.
254
+ */
255
+ export function sameCode(a, b) {
256
+ const x = elfCode(a);
257
+ const y = elfCode(b);
258
+ if (!x || !y)
259
+ return undefined;
260
+ return x.length === y.length && x.every((v, i) => v === y[i]);
261
+ }