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/CHANGELOG.md +416 -213
- package/README.md +859 -659
- package/dist/children.d.ts +100 -0
- package/dist/children.js +146 -0
- package/dist/cli.js +64 -9
- package/dist/diff.d.ts +223 -2
- package/dist/diff.js +358 -13
- package/dist/elf.d.ts +13 -0
- package/dist/elf.js +52 -0
- package/dist/flame.d.ts +61 -3
- package/dist/flame.js +81 -4
- package/dist/index.d.ts +12 -7
- package/dist/index.js +8 -5
- package/dist/manifest.d.ts +37 -0
- package/dist/manifest.js +107 -0
- package/dist/mock.d.ts +5 -0
- package/dist/mock.js +2 -1
- package/dist/profile.d.ts +21 -0
- package/dist/profile.js +29 -2
- package/dist/replay.d.ts +98 -1
- package/dist/replay.js +107 -1
- package/dist/report.d.ts +18 -2
- package/dist/report.js +175 -13
- package/dist/spawn.d.ts +29 -0
- package/dist/spawn.js +77 -0
- package/dist/wasm.d.ts +22 -1
- package/dist/wasm.js +31 -1
- package/package.json +4 -2
package/dist/diff.d.ts
CHANGED
|
@@ -17,6 +17,61 @@ export interface CycleReport {
|
|
|
17
17
|
* fails on these, from either side.
|
|
18
18
|
*/
|
|
19
19
|
errors?: string[];
|
|
20
|
+
/**
|
|
21
|
+
* What the numbers were measured with (1.3.0 and later). A diff checks the two
|
|
22
|
+
* sides' manifests: changed scenario inputs, another debugger, another CKB-VM.
|
|
23
|
+
*/
|
|
24
|
+
manifest?: ReportManifest;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* A reproducibility manifest. Every string in it can come from a pull request
|
|
28
|
+
* (a path in its cycles.json, the toolchain its build printed): whatever shows
|
|
29
|
+
* it cleans it as any other report text.
|
|
30
|
+
*/
|
|
31
|
+
export interface ReportManifest {
|
|
32
|
+
/** This object's layout. */
|
|
33
|
+
schema: 1;
|
|
34
|
+
/** The package that wrote the report, e.g. `{ name: "ckb-cycle-tools", version: "1.3.0" }`. */
|
|
35
|
+
tool: {
|
|
36
|
+
name: string;
|
|
37
|
+
version: string;
|
|
38
|
+
};
|
|
39
|
+
debugger: {
|
|
40
|
+
/** `--version`, as the report's `debugger`. */
|
|
41
|
+
version: string;
|
|
42
|
+
/** The native binary every scenario ran, and its sha256. */
|
|
43
|
+
path?: string;
|
|
44
|
+
sha256?: string;
|
|
45
|
+
/** For a WebAssembly build: its id (the sha256 of the .wasm). */
|
|
46
|
+
wasm?: string;
|
|
47
|
+
};
|
|
48
|
+
/** The commit checked out where the cycles.json is, and where the binaries came from with --binaries-from. */
|
|
49
|
+
git?: {
|
|
50
|
+
commit?: string;
|
|
51
|
+
binaries?: string;
|
|
52
|
+
};
|
|
53
|
+
/** Free text the caller gave (`--toolchain`): the compiler and build profile, e.g. `rustc -V`. */
|
|
54
|
+
toolchain?: string;
|
|
55
|
+
scenarios: ScenarioManifest[];
|
|
56
|
+
}
|
|
57
|
+
export interface ScenarioManifest {
|
|
58
|
+
name: string;
|
|
59
|
+
/** The CKB-VM version the scenario's `hash_type: "type"` scripts ran on. */
|
|
60
|
+
scriptVersion?: number;
|
|
61
|
+
/**
|
|
62
|
+
* sha256 over what decides what the scenario runs: its cycles.json entry
|
|
63
|
+
* (canonical, without its name or file path) and its mock or transaction file
|
|
64
|
+
* as read. Two reports with the same scenario name and a different hash did
|
|
65
|
+
* not measure the same thing.
|
|
66
|
+
*/
|
|
67
|
+
inputs?: string;
|
|
68
|
+
/** The binaries swapped in, as read: the path the config gives, sha256, size in bytes. */
|
|
69
|
+
binaries?: {
|
|
70
|
+
name: string;
|
|
71
|
+
path: string;
|
|
72
|
+
sha256: string;
|
|
73
|
+
size: number;
|
|
74
|
+
}[];
|
|
20
75
|
}
|
|
21
76
|
export interface ScenarioResult {
|
|
22
77
|
name: string;
|
|
@@ -38,7 +93,35 @@ export interface ScenarioResult {
|
|
|
38
93
|
*/
|
|
39
94
|
binaryMissing?: boolean;
|
|
40
95
|
missingBinaries?: string[];
|
|
96
|
+
/**
|
|
97
|
+
* Set when some group rejects (added after 1.2.0): the selector of the group the
|
|
98
|
+
* node would stop at, the first failing one in its order (lock groups, then
|
|
99
|
+
* type groups, each by script hash). The node reports no cycles for a
|
|
100
|
+
* rejected transaction, so the groups' cycles, each run on its own, do not
|
|
101
|
+
* add up to anything the node spends.
|
|
102
|
+
*/
|
|
103
|
+
nodeStopsAt?: string;
|
|
104
|
+
/**
|
|
105
|
+
* Set only when the groups' cycles add up to more than the node's limit for
|
|
106
|
+
* one transaction (added after 1.3.0): `limit` is the consensus
|
|
107
|
+
* `max_block_cycles` (3,500,000,000 on mainnet and testnet), `sum` the groups'
|
|
108
|
+
* cycles. ckb-debugger gives each group that limit on its own; the node gives
|
|
109
|
+
* it to the whole transaction, so it would reject this one (exceeded max
|
|
110
|
+
* cycles). `nodeStopsAt` names the group where the running sum passes it.
|
|
111
|
+
*/
|
|
112
|
+
overTxLimit?: {
|
|
113
|
+
limit: number;
|
|
114
|
+
sum: number;
|
|
115
|
+
};
|
|
41
116
|
}
|
|
117
|
+
/**
|
|
118
|
+
* A scenario's `overTxLimit`, read defensively (a report file is the PR's):
|
|
119
|
+
* undefined unless both numbers are there and the sum is over the limit.
|
|
120
|
+
*/
|
|
121
|
+
export declare function overTxLimitOf(s: ScenarioResult): {
|
|
122
|
+
limit: number;
|
|
123
|
+
sum: number;
|
|
124
|
+
} | undefined;
|
|
42
125
|
export interface GroupResult {
|
|
43
126
|
/** ckb-debugger's selector, e.g. `input.0.lock`: the key a group is matched by across reports. */
|
|
44
127
|
selector: string;
|
|
@@ -52,6 +135,14 @@ export interface GroupResult {
|
|
|
52
135
|
error?: string;
|
|
53
136
|
/** Cycles; 0 when the VM stopped the script (`error`), whose count is not a cost. */
|
|
54
137
|
cycles: number;
|
|
138
|
+
/**
|
|
139
|
+
* Set on every group of a scenario where some group rejects (added after 1.2.0):
|
|
140
|
+
* whether the node would run this group at all. It stops at the first failing
|
|
141
|
+
* group in its order (the scenario's `nodeStopsAt`); every group is still run
|
|
142
|
+
* on its own here, so the ones after it have a result and cycles the node
|
|
143
|
+
* would never produce. Absent when every group accepts: the node runs them all.
|
|
144
|
+
*/
|
|
145
|
+
nodeReaches?: boolean;
|
|
55
146
|
/**
|
|
56
147
|
* The binary this group's code stands for was not in the checkout (the base):
|
|
57
148
|
* its numbers are the mock's code, not that build's, so it is not compared.
|
|
@@ -72,6 +163,36 @@ export interface GroupResult {
|
|
|
72
163
|
spawned?: number;
|
|
73
164
|
/** With `spawned`: the cycles the function profile covers (the root script's own run). */
|
|
74
165
|
profiled?: number;
|
|
166
|
+
/**
|
|
167
|
+
* With `spawned` (added after 1.3.0, ckb-debugger 1.1.2 and later): each
|
|
168
|
+
* spawned script's own profile, from a `--vm-id` replay of it. Its numbers
|
|
169
|
+
* are profiled frames, not a split of `cycles`: they leave out loading the
|
|
170
|
+
* binary and what the spawn costs the parent. `cycles` stays the total.
|
|
171
|
+
*/
|
|
172
|
+
children?: ChildResult[];
|
|
173
|
+
/** With `spawned`: why some or all spawned scripts have no profile of their own (an older ckb-debugger, a replay that failed). */
|
|
174
|
+
childrenNote?: string;
|
|
175
|
+
}
|
|
176
|
+
/** A spawned script's own profile, in a report (added after 1.3.0). */
|
|
177
|
+
export interface ChildResult {
|
|
178
|
+
/** Its VM id (ckb-debugger's `--vm-id`): what a child is matched by across reports. */
|
|
179
|
+
vm: number;
|
|
180
|
+
/** The VM that spawned it: 0 is the group's own script. */
|
|
181
|
+
parent: number;
|
|
182
|
+
/** A name for the binary it ran (the config's binary name), or its short data hash. */
|
|
183
|
+
script: string;
|
|
184
|
+
/** The data hash of the binary it ran. */
|
|
185
|
+
codeHash?: string;
|
|
186
|
+
/** The replay's exit code: -1 with `error` when the VM stopped it. Absent with `failed`. */
|
|
187
|
+
result?: number;
|
|
188
|
+
error?: string;
|
|
189
|
+
/** The cycles in its profiled frames. Absent with `failed`. */
|
|
190
|
+
profiled?: number;
|
|
191
|
+
/** Its costliest functions, heaviest self first (at most FUNCTION_LIMIT), when its binary has a symbols build. */
|
|
192
|
+
functions?: FunctionResult[];
|
|
193
|
+
functionsWarning?: string;
|
|
194
|
+
/** Why it has no profile: the replay could not be run or read. */
|
|
195
|
+
failed?: string;
|
|
75
196
|
}
|
|
76
197
|
export interface FunctionResult {
|
|
77
198
|
name: string;
|
|
@@ -94,6 +215,29 @@ export interface FunctionDelta {
|
|
|
94
215
|
/** Set when both sides are known. */
|
|
95
216
|
delta?: number;
|
|
96
217
|
}
|
|
218
|
+
/** A spawned script on both sides of a diff, matched by VM id. Its numbers are profiled frames. */
|
|
219
|
+
export interface ChildDelta {
|
|
220
|
+
vm: number;
|
|
221
|
+
/** The head's name for it (the base's when it is gone). */
|
|
222
|
+
script: string;
|
|
223
|
+
/** Each side's result (`ok`, `exit 9`, `not profiled`) and profiled cycles; a side is absent when it had no such VM. */
|
|
224
|
+
base?: {
|
|
225
|
+
result: string;
|
|
226
|
+
profiled?: number;
|
|
227
|
+
};
|
|
228
|
+
head?: {
|
|
229
|
+
result: string;
|
|
230
|
+
profiled?: number;
|
|
231
|
+
};
|
|
232
|
+
/** Set when both sides have profiled cycles. */
|
|
233
|
+
delta?: number;
|
|
234
|
+
/** Its profiled cycles or result differ, or it is on one side only. */
|
|
235
|
+
changed: boolean;
|
|
236
|
+
/** Its functions whose self cycles changed, when the head recorded them. */
|
|
237
|
+
functions?: FunctionDelta[];
|
|
238
|
+
/** Why the head has no functions or no profile for it. */
|
|
239
|
+
note?: string;
|
|
240
|
+
}
|
|
97
241
|
/** `error`: the head could not run the scenario. `base-error`: the base could not, so nothing was compared. */
|
|
98
242
|
export type RowKind = "same" | "changed" | "result" | "new" | "removed" | "error" | "base-error";
|
|
99
243
|
export interface DiffRow {
|
|
@@ -125,8 +269,24 @@ export interface DiffRow {
|
|
|
125
269
|
spawned?: number;
|
|
126
270
|
/** With `spawned`: the cycles the head's function profile covers. */
|
|
127
271
|
profiled?: number;
|
|
128
|
-
/**
|
|
272
|
+
/** With `spawned`: each spawned script's profile on both sides, by VM id (head reports from 1.1.2 debuggers, added after 1.3.0). */
|
|
273
|
+
children?: ChildDelta[];
|
|
274
|
+
/** The head's reason some spawned scripts have no profile of their own. */
|
|
275
|
+
childrenNote?: string;
|
|
276
|
+
/** Why the base side of this group was not compared (its binary was not in the base checkout, its inputs changed). */
|
|
129
277
|
notCompared?: string;
|
|
278
|
+
/** Not compared because the scenario's inputs differ between the two reports' manifests. */
|
|
279
|
+
inputsChanged?: boolean;
|
|
280
|
+
}
|
|
281
|
+
/** One side's manifest, as a comment shows it. */
|
|
282
|
+
export interface ManifestSummary {
|
|
283
|
+
tool?: string;
|
|
284
|
+
debugger?: string;
|
|
285
|
+
debuggerSha256?: string;
|
|
286
|
+
wasm?: string;
|
|
287
|
+
commit?: string;
|
|
288
|
+
binariesCommit?: string;
|
|
289
|
+
toolchain?: string;
|
|
130
290
|
}
|
|
131
291
|
export interface CycleDiff {
|
|
132
292
|
rows: DiffRow[];
|
|
@@ -161,6 +321,40 @@ export interface CycleDiff {
|
|
|
161
321
|
head: string;
|
|
162
322
|
};
|
|
163
323
|
threshold?: number;
|
|
324
|
+
/**
|
|
325
|
+
* Groups not compared because their scenario's inputs (mock, transaction
|
|
326
|
+
* file, cycles.json entry) differ between the manifests. A gated diff fails
|
|
327
|
+
* on them unless `allowChangedInputs`.
|
|
328
|
+
*/
|
|
329
|
+
inputsChanged?: number;
|
|
330
|
+
/** The scenarios whose inputs changed. */
|
|
331
|
+
changedScenarios?: string[];
|
|
332
|
+
/**
|
|
333
|
+
* Why the two reports did not run in the same environment, from their
|
|
334
|
+
* manifests: another ckb-debugger (version or binary), another CKB-VM version
|
|
335
|
+
* for a scenario. A gated diff fails on any.
|
|
336
|
+
*/
|
|
337
|
+
environment?: string[];
|
|
338
|
+
/** What could not be checked, or differs without failing: a report without a manifest, another toolchain. */
|
|
339
|
+
notes?: string[];
|
|
340
|
+
/** Each side's manifest, short, for the comment. */
|
|
341
|
+
manifests?: {
|
|
342
|
+
base?: ManifestSummary;
|
|
343
|
+
head?: ManifestSummary;
|
|
344
|
+
};
|
|
345
|
+
/**
|
|
346
|
+
* Head scenarios whose groups add up to more than the node's per-transaction
|
|
347
|
+
* limit while the base's did not (`newScenario`: no base scenario ran to
|
|
348
|
+
* compare with). The node would reject them (exceeded max cycles) though every
|
|
349
|
+
* group may accept: a gated diff fails on one the base ran under the limit, as
|
|
350
|
+
* on a group that starts rejecting; `failOnResultChange` on any.
|
|
351
|
+
*/
|
|
352
|
+
overTxLimit?: {
|
|
353
|
+
scenario: string;
|
|
354
|
+
limit: number;
|
|
355
|
+
sum: number;
|
|
356
|
+
newScenario?: boolean;
|
|
357
|
+
}[];
|
|
164
358
|
}
|
|
165
359
|
export interface DiffOptions {
|
|
166
360
|
/** Percent. An increase above it is flagged, and makes `failed` true. */
|
|
@@ -169,7 +363,11 @@ export interface DiffOptions {
|
|
|
169
363
|
failOnResultChange?: boolean;
|
|
170
364
|
/** Removed, renamed or uncompared base groups do not fail a gated diff. */
|
|
171
365
|
allowRemoved?: boolean;
|
|
366
|
+
/** Scenarios whose inputs changed (manifest hashes differ) do not fail a gated diff; still not compared. */
|
|
367
|
+
allowChangedInputs?: boolean;
|
|
172
368
|
}
|
|
369
|
+
/** The note on a group whose scenario's inputs differ between base and head. */
|
|
370
|
+
export declare const INPUTS_CHANGED = "inputs changed: the scenario's mock, transaction file or cycles.json entry differs from the base's";
|
|
173
371
|
/** The message for a binary no scenario's cell deps match, in a report's `errors` and the diff. */
|
|
174
372
|
export declare const unmatchedError: (name: string) => string;
|
|
175
373
|
/**
|
|
@@ -179,6 +377,12 @@ export declare const unmatchedError: (name: string) => string;
|
|
|
179
377
|
*/
|
|
180
378
|
export declare function resultLabel(g: Pick<GroupResult, "result" | "error">): string;
|
|
181
379
|
export declare function diffReports(base: CycleReport, head: CycleReport, options?: DiffOptions): CycleDiff;
|
|
380
|
+
/**
|
|
381
|
+
* Each spawned script on both sides, by VM id, in VM order. Without base
|
|
382
|
+
* children (an older report, an older debugger) every head child has no base
|
|
383
|
+
* side: what it costs is shown, not a change.
|
|
384
|
+
*/
|
|
385
|
+
export declare function childDeltas(base: ChildResult[] | undefined, head: ChildResult[]): ChildDelta[];
|
|
182
386
|
/**
|
|
183
387
|
* The functions whose self cycles differ between two lists, largest change
|
|
184
388
|
* first. One whose other side is not known (see FunctionDelta) is kept, ranked
|
|
@@ -192,7 +396,16 @@ export declare function functionDeltas(base: FunctionResult[] | undefined, head:
|
|
|
192
396
|
* run, an error in either report, and a base group with nothing to compare
|
|
193
397
|
* against (removed, renamed, moved, or measured without its binary) unless
|
|
194
398
|
* `allowRemoved`. A head group the VM stopped is a result change, and over any
|
|
195
|
-
* `failAbove` threshold.
|
|
399
|
+
* `failAbove` threshold. With a gate set, a group that accepted on the base and
|
|
400
|
+
* rejects on the head (`ok` → `exit N` or a VM error) always fails, whatever its
|
|
401
|
+
* cycles: a cheaper rejection is not a saving. `failOnResultChange` fails on any
|
|
402
|
+
* result change besides (reject → accept, one exit code or VM error to another,
|
|
403
|
+
* a new group that does not accept). A new group has no base that accepted, so
|
|
404
|
+
* this rule leaves it alone: with `failAbove` alone it fails only as before (a
|
|
405
|
+
* new group the VM stopped is over the threshold). A scenario whose groups add
|
|
406
|
+
* up to more than the node's per-transaction limit on the head, and not on the
|
|
407
|
+
* base, counts as a group that starts rejecting (the node would reject it); a
|
|
408
|
+
* new scenario over the limit, as a new group that does not accept.
|
|
196
409
|
*/
|
|
197
410
|
export declare function diffFailed(diff: CycleDiff, options?: DiffOptions): boolean;
|
|
198
411
|
/**
|
|
@@ -219,7 +432,10 @@ export declare function spawnNote(r: {
|
|
|
219
432
|
head?: {
|
|
220
433
|
cycles?: number;
|
|
221
434
|
};
|
|
435
|
+
children?: unknown[];
|
|
222
436
|
}): string;
|
|
437
|
+
/** What a spawned script's numbers are, under every list of them. */
|
|
438
|
+
export declare 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.";
|
|
223
439
|
/** The hidden marker that identifies the sticky comment, so it is updated instead of duplicated. */
|
|
224
440
|
export declare const COMMENT_MARKER = "<!-- ckb-cycles-report -->";
|
|
225
441
|
export interface MarkdownOptions {
|
|
@@ -234,5 +450,10 @@ export interface MarkdownOptions {
|
|
|
234
450
|
* reverse) matters more than any cycle count.
|
|
235
451
|
*/
|
|
236
452
|
export declare function formatMarkdown(diff: CycleDiff, options?: MarkdownOptions): string;
|
|
453
|
+
/**
|
|
454
|
+
* One line per side that has a manifest: tool, debugger (and its binary's
|
|
455
|
+
* hash), commit, toolchain. Plain text: the caller cleans it (md or termLine).
|
|
456
|
+
*/
|
|
457
|
+
export declare function manifestLines(diff: CycleDiff): string[];
|
|
237
458
|
/** The same table for a terminal. */
|
|
238
459
|
export declare function formatText(diff: CycleDiff): string;
|