ckb-cycle-tools 1.2.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);
@@ -167,17 +302,33 @@ export function functionDeltas(base, head) {
167
302
  * run, an error in either report, and a base group with nothing to compare
168
303
  * against (removed, renamed, moved, or measured without its binary) unless
169
304
  * `allowRemoved`. A head group the VM stopped is a result change, and over any
170
- * `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.
171
315
  */
172
316
  export function diffFailed(diff, options = {}) {
173
317
  const gated = options.failAbove !== undefined || options.failOnResultChange === true;
174
318
  return ((options.failAbove !== undefined && diff.overThreshold > 0) ||
175
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) ||
176
323
  (gated && diff.baseErrors > 0) ||
177
324
  (gated && (diff.reportErrors?.length ?? 0) > 0) ||
178
325
  (gated && !options.allowRemoved && (diff.removed ?? 0) > 0) ||
326
+ (gated && !options.allowChangedInputs && (diff.inputsChanged ?? 0) > 0) ||
327
+ (gated && (diff.environment?.length ?? 0) > 0) ||
179
328
  diff.rows.some((r) => r.kind === "error"));
180
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";
181
332
  const fmt = (n) => n.toLocaleString("en-US");
182
333
  const signed = (n) => (n > 0 ? `+${fmt(n)}` : n < 0 ? `-${fmt(-n)}` : "0");
183
334
  const pct = (p) => p === undefined ? "" : p === 0 ? "0%" : `${p > 0 ? "+" : "-"}${Math.abs(p) < 0.01 ? "<0.01" : Math.abs(p).toFixed(2)}%`;
@@ -188,11 +339,11 @@ function note(r, threshold) {
188
339
  case "result":
189
340
  return r.base.result === NOT_RUN
190
341
  ? `NEW, DOES NOT ACCEPT: ${r.head.result}${unpaired}`
191
- : `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)" : ""}`;
192
343
  case "new":
193
344
  return r.notCompared ? `NOT COMPARED: ${r.notCompared}` : "new";
194
345
  case "removed":
195
- 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";
196
347
  case "error":
197
348
  return r.note ?? "error";
198
349
  case "base-error":
@@ -211,11 +362,14 @@ export function summarize(diff, clean = termLine) {
211
362
  const changed = groups.filter((r) => r.kind !== "same").length;
212
363
  const errors = diff.rows.filter((r) => r.kind === "error").length;
213
364
  // 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;
365
+ const unchecked = diff.threshold === undefined ? 0 : groups.filter((r) => !r.inputsChanged && (!r.base || r.base.result === NOT_RUN)).length;
215
366
  const s = (n) => (n > 1 ? "s" : "");
216
367
  const parts = [
217
368
  ...(diff.resultChanges ? [`${diff.resultChanges} result change${s(diff.resultChanges)}`] : []),
218
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
+ : []),
219
373
  ...(errors ? [`${errors} scenario${s(errors)} failed to run`] : []),
220
374
  ...(diff.baseErrors ? [`${diff.baseErrors} scenario${s(diff.baseErrors)} could not run on the base`] : []),
221
375
  `${changed} of ${groups.length} script group${groups.length === 1 ? "" : "s"} changed`,
@@ -228,6 +382,10 @@ export function summarize(diff, clean = termLine) {
228
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)`]
229
383
  : []),
230
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)})`] : []),
231
389
  ...(diff.debuggers
232
390
  ? [`the reports come from different debuggers (base ${clean(diff.debuggers.base)}, head ${clean(diff.debuggers.head)}): cycles can differ for that alone`]
233
391
  : []),
@@ -354,7 +512,18 @@ export function formatMarkdown(diff, options = {}) {
354
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`] : []), ""]
355
513
  : [];
356
514
  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>"];
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
+ ];
358
527
  let table = shown.length ? [head, ...shown.map(line), ""] : ["No script group changed its cycles or its result.", ""];
359
528
  let blocks = functionBlocks(shown);
360
529
  let warnings = diff.warnings?.length ? warningBlock(diff.warnings) : [];
@@ -395,6 +564,43 @@ export function formatMarkdown(diff, options = {}) {
395
564
  }
396
565
  return [...top, ...table, ...blocks, ...warnings, ...unchanged, ...footer].join("\n");
397
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
+ }
398
604
  /** How many scenario warnings a comment lists. */
399
605
  const WARNINGS_SHOWN = 50;
400
606
  /** The head's scenario warnings, folded: why a number may not be the build's (a binary no cell dep matched). */
@@ -448,16 +654,24 @@ export function formatText(diff) {
448
654
  else if (r.functions && r.spawned)
449
655
  functions.push(`functions in ${where}: none of its own changed. ${spawnNote(r)}`);
450
656
  }
451
- 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)}`);
452
663
  const warnings = (diff.warnings ?? []).map((w) => `${termLine(w.scenario)}: warning: ${termLine(w.text)}`);
664
+ const manifest = manifestLines(diff).map((l) => termLine(`manifest ${l}`));
453
665
  return [
454
666
  summarize(diff),
455
667
  ...(errors.length ? ["", ...errors] : []),
668
+ ...(environment.length || notes.length ? ["", ...environment, ...notes] : []),
456
669
  "",
457
670
  line(header),
458
671
  ...rows.map(line),
459
672
  ...(functions.length ? ["", ...functions] : []),
460
673
  ...(warnings.length ? ["", ...warnings] : []),
674
+ ...(manifest.length ? ["", ...manifest] : []),
461
675
  ].join("\n");
462
676
  }
463
677
  const fnText = (n) => (n === undefined ? "?" : fmt(n));
package/dist/index.d.ts CHANGED
@@ -4,7 +4,7 @@ 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";
@@ -14,8 +14,9 @@ export { runWasmDebugger, wasmDebuggerVersion, wasmOutput, wasmRunner, WASM_TX_F
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
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;
@@ -0,0 +1,107 @@
1
+ /**
2
+ * What a report's numbers were measured with, so two reports can be checked for
3
+ * comparability (review #46, point 4): the tool, the debugger binary, the
4
+ * commit, the toolchain, and per scenario the CKB-VM version, a hash of its
5
+ * inputs and the binaries swapped into it. Node only (hashes files, runs git);
6
+ * the shape is in diff.ts, which compares it.
7
+ */
8
+ import { execFile } from "node:child_process";
9
+ import { createHash } from "node:crypto";
10
+ import { createReadStream } from "node:fs";
11
+ import { readFile } from "node:fs/promises";
12
+ export const sha256 = (data) => createHash("sha256").update(data).digest("hex");
13
+ /** The sha256 and size of a file, read as a stream (a debugger binary is tens of MB). */
14
+ export function fileDigest(path) {
15
+ return new Promise((resolve, reject) => {
16
+ const hash = createHash("sha256");
17
+ let size = 0;
18
+ createReadStream(path)
19
+ .on("data", (chunk) => {
20
+ const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
21
+ size += bytes.length;
22
+ hash.update(bytes);
23
+ })
24
+ .on("error", reject)
25
+ .on("end", () => resolve({ sha256: hash.digest("hex"), size }));
26
+ });
27
+ }
28
+ /** This package's name and version, from its package.json ("unknown" if it cannot be read). */
29
+ export async function toolIdentity() {
30
+ try {
31
+ const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
32
+ return { name: String(pkg.name ?? "ckb-cycle-tools"), version: String(pkg.version ?? "unknown") };
33
+ }
34
+ catch {
35
+ return { name: "ckb-cycle-tools", version: "unknown" };
36
+ }
37
+ }
38
+ const COMMIT = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
39
+ /**
40
+ * The commit checked out at `dir`, or undefined: not a git checkout, no git, or
41
+ * anything else. Never fails the report. Only a commit id is kept, whatever git printed.
42
+ */
43
+ export function gitCommit(dir) {
44
+ return new Promise((resolve) => {
45
+ try {
46
+ execFile("git", ["rev-parse", "--verify", "--quiet", "HEAD"], { cwd: dir, timeout: 10_000, windowsHide: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" } }, (err, stdout) => {
47
+ const out = String(stdout ?? "").trim().toLowerCase();
48
+ resolve(!err && COMMIT.test(out) ? out : undefined);
49
+ });
50
+ }
51
+ catch {
52
+ resolve(undefined);
53
+ }
54
+ });
55
+ }
56
+ /** JSON with object keys sorted at every level: the same value always gives the same text. */
57
+ export function canonicalJson(value) {
58
+ if (Array.isArray(value))
59
+ return `[${value.map(canonicalJson).join(",")}]`;
60
+ if (value && typeof value === "object") {
61
+ const o = value;
62
+ return `{${Object.keys(o)
63
+ .filter((k) => o[k] !== undefined)
64
+ .sort()
65
+ .map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`)
66
+ .join(",")}}`;
67
+ }
68
+ return JSON.stringify(value) ?? "null";
69
+ }
70
+ /**
71
+ * The part of a scenario's cycles.json entry that decides what runs: its form
72
+ * (and transaction hash), the binaries it names, its CKB-VM version, and for a
73
+ * transaction fetched from a node, the network. Not its name (the key it is
74
+ * matched by), the path of its file (whose bytes are hashed instead: a moved
75
+ * file with the same bytes is the same input), nor `functions` (which records
76
+ * names, not cycles).
77
+ */
78
+ export function scenarioInputs(s, network) {
79
+ const kind = s.mock !== undefined ? "mock" : s.file !== undefined ? "file" : "tx";
80
+ return {
81
+ kind,
82
+ ...(s.tx !== undefined && { tx: s.tx.toLowerCase() }),
83
+ ...(s.binaries !== undefined && { binaries: [...s.binaries].sort() }),
84
+ ...(s.scriptVersion !== undefined && { scriptVersion: s.scriptVersion }),
85
+ ...(kind !== "mock" && { network: network ?? null }),
86
+ };
87
+ }
88
+ /**
89
+ * sha256 over a scenario's inputs: the canonical entry (scenarioInputs), then
90
+ * the bytes of its mock or transaction file exactly as read, if it has one.
91
+ */
92
+ export function inputsHash(entry, file) {
93
+ const h = createHash("sha256");
94
+ h.update("ckb-cycles inputs v1\n");
95
+ h.update(canonicalJson(entry));
96
+ h.update("\n");
97
+ if (file)
98
+ h.update(file);
99
+ return h.digest("hex");
100
+ }
101
+ /** The longest toolchain description a report keeps. */
102
+ export const TOOLCHAIN_MAX = 4096;
103
+ /** A toolchain description as a report keeps it: trimmed, clipped; undefined when empty. */
104
+ export function toolchainOf(s) {
105
+ const t = (s ?? "").trim();
106
+ return t ? (t.length > TOOLCHAIN_MAX ? `${t.slice(0, TOOLCHAIN_MAX - 1)}…` : t) : undefined;
107
+ }
package/dist/mock.d.ts CHANGED
@@ -82,6 +82,11 @@ export interface NodeConsensus {
82
82
  /** "mainnet", "testnet", or the chain id for any other chain. */
83
83
  network: string;
84
84
  vmEpochs: VmEpochs;
85
+ /**
86
+ * The consensus `max_block_cycles`, when the node gives it: the node verifies
87
+ * each transaction under this one limit (see DEFAULT_TX_CYCLE_LIMIT).
88
+ */
89
+ maxBlockCycles?: bigint;
85
90
  }
86
91
  /**
87
92
  * Asks the node which chain it serves and when its hardforks took effect, so a
package/dist/mock.js CHANGED
@@ -94,7 +94,8 @@ export async function nodeConsensus(rpc) {
94
94
  return f.epoch_number === null ? Infinity : Number(f.epoch_number);
95
95
  };
96
96
  const network = c.id === "ckb" ? "mainnet" : c.id === "ckb_testnet" ? "testnet" : c.id;
97
- return { chain: c.id, network, vmEpochs: [epochOf("0032"), epochOf("0049")] };
97
+ const max = typeof c.max_block_cycles === "string" && /^0x[0-9a-fA-F]+$/.test(c.max_block_cycles) ? BigInt(c.max_block_cycles) : undefined;
98
+ return { chain: c.id, network, vmEpochs: [epochOf("0032"), epochOf("0049")], ...(max !== undefined && max > 0n && { maxBlockCycles: max }) };
98
99
  }
99
100
  /** Parses a molecule OutPointVec: u32 LE count, then 36-byte out points. */
100
101
  export function parseOutPointVec(data) {