@typeonce/ritmo-devtools 0.14.0 → 0.15.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 +241 -0
- package/README.md +296 -55
- package/dist/Desync.d.ts +17 -3
- package/dist/Desync.d.ts.map +1 -1
- package/dist/Desync.js +17 -15
- package/dist/Desync.js.map +1 -1
- package/dist/Determinism.d.ts +17 -6
- package/dist/Determinism.d.ts.map +1 -1
- package/dist/Determinism.js +11 -3
- package/dist/Determinism.js.map +1 -1
- package/dist/Format.d.ts +43 -8
- package/dist/Format.d.ts.map +1 -1
- package/dist/Format.js +63 -31
- package/dist/Format.js.map +1 -1
- package/dist/Fuzz.d.ts +268 -0
- package/dist/Fuzz.d.ts.map +1 -0
- package/dist/Fuzz.js +355 -0
- package/dist/Fuzz.js.map +1 -0
- package/dist/Invariant.d.ts +6 -2
- package/dist/Invariant.d.ts.map +1 -1
- package/dist/Invariant.js.map +1 -1
- package/dist/PlaywrightEngine.d.ts +29 -0
- package/dist/PlaywrightEngine.d.ts.map +1 -0
- package/dist/PlaywrightEngine.js +193 -0
- package/dist/PlaywrightEngine.js.map +1 -0
- package/dist/Replay.d.ts +40 -22
- package/dist/Replay.d.ts.map +1 -1
- package/dist/Replay.js +20 -27
- package/dist/Replay.js.map +1 -1
- package/dist/Session.d.ts +214 -17
- package/dist/Session.d.ts.map +1 -1
- package/dist/Session.js +563 -57
- package/dist/Session.js.map +1 -1
- package/dist/Verify.d.ts +147 -0
- package/dist/Verify.d.ts.map +1 -0
- package/dist/Verify.js +151 -0
- package/dist/Verify.js.map +1 -0
- package/dist/cli.js +136 -8
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +3 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -2
- package/dist/index.js.map +1 -1
- package/dist/internal/dependencyScan.d.ts +44 -0
- package/dist/internal/dependencyScan.d.ts.map +1 -0
- package/dist/internal/dependencyScan.js +313 -0
- package/dist/internal/dependencyScan.js.map +1 -0
- package/dist/internal/fuzzNetwork.d.ts +56 -0
- package/dist/internal/fuzzNetwork.d.ts.map +1 -0
- package/dist/internal/fuzzNetwork.js +96 -0
- package/dist/internal/fuzzNetwork.js.map +1 -0
- package/dist/internal/values.d.ts +9 -1
- package/dist/internal/values.d.ts.map +1 -1
- package/dist/internal/values.js +11 -1
- package/dist/internal/values.js.map +1 -1
- package/dist/internal/verifyRunner.d.ts +19 -0
- package/dist/internal/verifyRunner.d.ts.map +1 -0
- package/dist/internal/verifyRunner.js +47 -0
- package/dist/internal/verifyRunner.js.map +1 -0
- package/dist/internal/version.d.ts +1 -1
- package/dist/internal/version.js +1 -1
- package/package.json +28 -3
- package/src/Desync.ts +34 -17
- package/src/Determinism.ts +46 -11
- package/src/Format.ts +99 -34
- package/src/Fuzz.ts +544 -0
- package/src/Invariant.ts +6 -2
- package/src/PlaywrightEngine.ts +229 -0
- package/src/Replay.ts +87 -43
- package/src/Session.ts +806 -72
- package/src/Verify.ts +273 -0
- package/src/cli.ts +131 -8
- package/src/index.ts +3 -2
- package/src/internal/dependencyScan.ts +356 -0
- package/src/internal/fuzzNetwork.ts +130 -0
- package/src/internal/values.ts +20 -1
- package/src/internal/verifyRunner.ts +46 -0
- package/src/internal/version.ts +1 -1
- package/dist/Monitor.d.ts +0 -101
- package/dist/Monitor.d.ts.map +0 -1
- package/dist/Monitor.js +0 -602
- package/dist/Monitor.js.map +0 -1
- package/dist/internal/monitor.d.ts +0 -126
- package/dist/internal/monitor.d.ts.map +0 -1
- package/dist/internal/monitor.js +0 -279
- package/dist/internal/monitor.js.map +0 -1
- package/src/Monitor.ts +0 -713
- package/src/internal/monitor.ts +0 -370
package/src/Format.ts
CHANGED
|
@@ -3,13 +3,15 @@
|
|
|
3
3
|
*
|
|
4
4
|
* The output is meant to be read in a terminal or pasted into a prompt, so it
|
|
5
5
|
* favors one line per fact and short, stable prefixes (`e12` for entity 12,
|
|
6
|
-
* `f40` for frame 40).
|
|
6
|
+
* `f40` for frame 40). An entity with a label prints as `player e12`
|
|
7
|
+
* (see {@link entity}). Numbers are rounded to at most 3 decimals for display;
|
|
7
8
|
* the underlying data keeps exact values.
|
|
8
9
|
*
|
|
9
10
|
* @module Format
|
|
10
11
|
* @docGroup devtools
|
|
11
12
|
*/
|
|
12
13
|
import type * as Debug from "@typeonce/ritmo/Debug"
|
|
14
|
+
import type { FieldMeta } from "@typeonce/ritmo/Descriptor"
|
|
13
15
|
import type * as Machine from "@typeonce/ritmo/Machine"
|
|
14
16
|
|
|
15
17
|
/** How much of a nested value the text output prints. */
|
|
@@ -20,6 +22,26 @@ export interface ValueOptions {
|
|
|
20
22
|
readonly items?: number
|
|
21
23
|
}
|
|
22
24
|
|
|
25
|
+
/**
|
|
26
|
+
* Entity id to label, read when printing entities. A session gets them from
|
|
27
|
+
* its `labels` inspector (a `ReadonlyMap<number, string>` is one); pass
|
|
28
|
+
* `runtime.inspect(Labels)` where a function takes labels as data, such as
|
|
29
|
+
* `Desync.compare`.
|
|
30
|
+
*/
|
|
31
|
+
export interface Labels {
|
|
32
|
+
// A method, so a map keyed by branded entity ids (`match.entity.id`) is labels too.
|
|
33
|
+
get(entity: number): string | undefined
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* The one way devtools prints an entity: `player e12` when `labels` names
|
|
38
|
+
* it, `e12` otherwise. An empty label counts as none.
|
|
39
|
+
*/
|
|
40
|
+
export const entity = (id: number, labels?: Labels): string => {
|
|
41
|
+
const label = labels?.get(id)
|
|
42
|
+
return label === undefined || label === "" ? `e${id}` : `${label} e${id}`
|
|
43
|
+
}
|
|
44
|
+
|
|
23
45
|
const formatNumber = (value: number): string => {
|
|
24
46
|
if (!Number.isFinite(value) || Number.isInteger(value)) return String(value)
|
|
25
47
|
const rounded = Math.round(value * 1000) / 1000
|
|
@@ -139,6 +161,7 @@ export const system = (input: Debug.SystemDescription): string => {
|
|
|
139
161
|
add("reads removed", input.removed)
|
|
140
162
|
if (input.despawned) lines.push(" reads despawned")
|
|
141
163
|
add("reads relation failures", input.relationFailures)
|
|
164
|
+
add("reads dropped relations", input.droppedRelations)
|
|
142
165
|
add("services", input.services.filter((name) => !input.consumes.includes(name)))
|
|
143
166
|
add("consumes (drains each run)", input.consumes)
|
|
144
167
|
add("may spawn", input.commands.spawns)
|
|
@@ -160,17 +183,33 @@ export const lintLines = (lints: ReadonlyArray<Debug.Lint>): Array<string> => [
|
|
|
160
183
|
...(lints.length === 0 ? ["(none)"] : lints.map((lint) => `${lint.severity} ${lint.code}: ${lint.message}`))
|
|
161
184
|
]
|
|
162
185
|
|
|
186
|
+
/**
|
|
187
|
+
* One field's declared metadata (a constructor's `meta` option, listed by
|
|
188
|
+
* `describe()`) on one line: `hp: points, range [0, 100], "Hit points left."`.
|
|
189
|
+
*/
|
|
190
|
+
export const fieldMeta = (field: string, meta: FieldMeta): string => {
|
|
191
|
+
const parts = [
|
|
192
|
+
...(meta.unit === undefined ? [] : [meta.unit]),
|
|
193
|
+
...(meta.range === undefined ? [] : [`range [${formatNumber(meta.range[0])}, ${formatNumber(meta.range[1])}]`]),
|
|
194
|
+
...(meta.hint === undefined ? [] : [JSON.stringify(meta.hint)])
|
|
195
|
+
]
|
|
196
|
+
return `${field}: ${parts.join(", ")}`
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
const metaLines = (meta: Readonly<Record<string, FieldMeta>>): Array<string> =>
|
|
200
|
+
Object.entries(meta).map(([field, entry]) => ` ${fieldMeta(field, entry)}`)
|
|
201
|
+
|
|
163
202
|
/** The static description as sections: lints, schema, schedules, systems, access. */
|
|
164
203
|
export const description = (input: Debug.Description): string => {
|
|
165
204
|
const lines: Array<string> = []
|
|
166
205
|
lines.push("# Components")
|
|
167
206
|
for (const component of input.components) {
|
|
168
207
|
const notes = [component.storage, ...(component.immutable ? ["immutable"] : []), ...(component.requires.length > 0 ? [`requires ${component.requires.join(", ")}`] : [])]
|
|
169
|
-
lines.push(`${component.name} (${notes.join(", ")})
|
|
208
|
+
lines.push(`${component.name} (${notes.join(", ")})`, ...metaLines(component.meta))
|
|
170
209
|
}
|
|
171
210
|
lines.push("", "# Resources")
|
|
172
211
|
for (const resource of input.resources) {
|
|
173
|
-
lines.push(`${resource.name} (${resource.storage}${resource.present ? "" : ", no value"})
|
|
212
|
+
lines.push(`${resource.name} (${resource.storage}${resource.present ? "" : ", no value"})`, ...metaLines(resource.meta))
|
|
174
213
|
}
|
|
175
214
|
if (input.events.length > 0) {
|
|
176
215
|
lines.push("", "# Events")
|
|
@@ -205,11 +244,8 @@ export const description = (input: Debug.Description): string => {
|
|
|
205
244
|
if (input.schedules.length === 0) lines.push("(none named; call runtime.debug.nameSchedules({...}))")
|
|
206
245
|
for (const schedule of input.schedules) {
|
|
207
246
|
lines.push(`${schedule.name}:`)
|
|
208
|
-
schedule.steps.forEach((
|
|
209
|
-
|
|
210
|
-
: step.kind === "applyDeferred" ? "<applyDeferred>"
|
|
211
|
-
: `<applyStateTransitions${step.schedules.length > 0 ? `: ${step.schedules.join(", ")}` : ""}>`
|
|
212
|
-
lines.push(` ${String(index).padStart(2)} ${text}`)
|
|
247
|
+
schedule.steps.forEach((entry, index) => {
|
|
248
|
+
lines.push(` ${String(index).padStart(2)} ${step(entry)}`)
|
|
213
249
|
})
|
|
214
250
|
}
|
|
215
251
|
if (input.systems.length > 0) {
|
|
@@ -229,15 +265,21 @@ export const description = (input: Debug.Description): string => {
|
|
|
229
265
|
return [...lintLines(input.lints), "", ...lines].join("\n")
|
|
230
266
|
}
|
|
231
267
|
|
|
232
|
-
/** One
|
|
233
|
-
export const
|
|
268
|
+
/** One schedule step: the system's name, or `<applyDeferred>` / `<applyStateTransitions: ...>` for a marker. */
|
|
269
|
+
export const step = (input: Debug.StepDescription): string =>
|
|
270
|
+
input.kind === "system" ? input.system
|
|
271
|
+
: input.kind === "applyDeferred" ? "<applyDeferred>"
|
|
272
|
+
: `<applyStateTransitions${input.schedules.length > 0 ? `: ${input.schedules.join(", ")}` : ""}>`
|
|
273
|
+
|
|
274
|
+
/** One entity per line (named with `labels`), then resources, machines, and pending commands. */
|
|
275
|
+
export const dump = (input: Debug.WorldDump, options: ValueOptions = {}, labels?: Labels): string => {
|
|
234
276
|
const lines: Array<string> = [
|
|
235
277
|
`frame ${input.frame} (tick ${input.tick}), ${input.entities.length} of ${input.entityCount} entities`
|
|
236
278
|
]
|
|
237
|
-
for (const
|
|
238
|
-
const components = Object.entries(
|
|
239
|
-
const relations = Object.entries(
|
|
240
|
-
lines.push(
|
|
279
|
+
for (const dumped of input.entities) {
|
|
280
|
+
const components = Object.entries(dumped.components).map(([name, component]) => `${name}=${value(component, options)}`)
|
|
281
|
+
const relations = Object.entries(dumped.relations).map(([name, target]) => `${name}->${entity(target, labels)}`)
|
|
282
|
+
lines.push(`${entity(dumped.id, labels)} ${[...components, ...relations].join(" ")}`)
|
|
241
283
|
}
|
|
242
284
|
const resources = Object.entries(input.resources)
|
|
243
285
|
if (resources.length > 0) {
|
|
@@ -274,28 +316,33 @@ export const streams = (input: ReadonlyArray<Debug.StreamStatus>): string => {
|
|
|
274
316
|
return lines.join("\n")
|
|
275
317
|
}
|
|
276
318
|
|
|
277
|
-
const effect = (input: Debug.Effect, options: ValueOptions): string => {
|
|
319
|
+
const effect = (input: Debug.Effect, options: ValueOptions, labels: Labels | undefined): string => {
|
|
320
|
+
const id = entity(input.entity, labels)
|
|
278
321
|
switch (input.kind) {
|
|
279
322
|
case "spawn":
|
|
280
|
-
return `spawn
|
|
323
|
+
return `spawn ${id} ${Object.entries(input.components).map(([name, component]) => `${name}=${value(component, options)}`).join(" ")}`
|
|
281
324
|
case "despawn":
|
|
282
|
-
return `despawn
|
|
325
|
+
return `despawn ${id}`
|
|
283
326
|
case "insert":
|
|
284
|
-
return `insert
|
|
327
|
+
return `insert ${id} ${input.component}=${value(input.value, options)}`
|
|
285
328
|
case "overwrite":
|
|
286
|
-
return `insert
|
|
329
|
+
return `insert ${id} ${input.component} ${change(input.before, input.after, options)}`
|
|
287
330
|
case "remove":
|
|
288
|
-
return `remove
|
|
331
|
+
return `remove ${id} ${input.component}`
|
|
289
332
|
case "relate":
|
|
290
|
-
return `relate
|
|
333
|
+
return `relate ${id} ${input.relation}->${entity(input.target, labels)}`
|
|
291
334
|
case "unrelate":
|
|
292
|
-
return `unrelate
|
|
335
|
+
return `unrelate ${id} ${input.relation}`
|
|
293
336
|
case "relationFailure":
|
|
294
|
-
return `relation failure
|
|
337
|
+
return `relation failure ${id} ${input.relation}: ${input.error}`
|
|
338
|
+
case "relationDropped": {
|
|
339
|
+
const target = entity(input.target, labels)
|
|
340
|
+
return `${input.relation} from ${id} to ${target} dropped: ${target} despawned`
|
|
341
|
+
}
|
|
295
342
|
case "requirementViolated":
|
|
296
|
-
return `skipped ${input.command}
|
|
343
|
+
return `skipped ${input.command} ${id}: ${input.component} requires ${input.missing}`
|
|
297
344
|
case "staleTarget":
|
|
298
|
-
return `skipped ${input.command}
|
|
345
|
+
return `skipped ${input.command} ${id}: id spawned in an earlier run`
|
|
299
346
|
}
|
|
300
347
|
}
|
|
301
348
|
|
|
@@ -314,6 +361,8 @@ export type LineKind =
|
|
|
314
361
|
| "transition"
|
|
315
362
|
| "restore"
|
|
316
363
|
| "ignored"
|
|
364
|
+
/** A read the writing system declared, under a `why` line; only `why` and `whyResource` with `depth` above 1 print them. */
|
|
365
|
+
| "read"
|
|
317
366
|
|
|
318
367
|
/**
|
|
319
368
|
* The text for a failed tick result nobody read: who failed, with what, how
|
|
@@ -392,6 +441,8 @@ export interface Line {
|
|
|
392
441
|
readonly system: string | undefined
|
|
393
442
|
/** The entity the line is about, when there is one. */
|
|
394
443
|
readonly entity: number | undefined
|
|
444
|
+
/** That entity's label, when the labels given to {@link lines} name it. */
|
|
445
|
+
readonly label: string | undefined
|
|
395
446
|
/** The component, resource, event, machine, or stream the line is about. */
|
|
396
447
|
readonly subject: string | undefined
|
|
397
448
|
readonly text: string
|
|
@@ -400,13 +451,27 @@ export interface Line {
|
|
|
400
451
|
* the current state, or a skip that discarded nothing.
|
|
401
452
|
*/
|
|
402
453
|
readonly noop: boolean
|
|
454
|
+
/**
|
|
455
|
+
* How far back the line is from the value asked about: 0 for every
|
|
456
|
+
* journal line and each change `why` lists; 1 for a read the system
|
|
457
|
+
* behind a depth-0 line declared, 2 for one behind that, and so on
|
|
458
|
+
* (`why(..., { depth })`). Lines above 0 are `read` lines and print
|
|
459
|
+
* indented under the line they explain.
|
|
460
|
+
*/
|
|
461
|
+
readonly depth: number
|
|
403
462
|
}
|
|
404
463
|
|
|
405
464
|
/**
|
|
406
|
-
* Splits one trace event into printable lines
|
|
407
|
-
* boundaries produce no lines.
|
|
465
|
+
* Splits one trace event into printable lines, naming entities with
|
|
466
|
+
* `labels`. Frame and schedule boundaries produce no lines.
|
|
408
467
|
*/
|
|
409
|
-
export const lines = (event: Debug.TraceEvent, options: ValueOptions = {}): ReadonlyArray<Line> =>
|
|
468
|
+
export const lines = (event: Debug.TraceEvent, options: ValueOptions = {}, labels?: Labels): ReadonlyArray<Line> =>
|
|
469
|
+
rawLines(event, options, labels).map((line) => {
|
|
470
|
+
const label = line.entity === undefined ? undefined : labels?.get(line.entity)
|
|
471
|
+
return { ...line, label: label === "" ? undefined : label, depth: 0 }
|
|
472
|
+
})
|
|
473
|
+
|
|
474
|
+
const rawLines = (event: Debug.TraceEvent, options: ValueOptions, labels: Labels | undefined): ReadonlyArray<Omit<Line, "label" | "depth">> => {
|
|
410
475
|
switch (event.type) {
|
|
411
476
|
case "frame":
|
|
412
477
|
case "schedule.start":
|
|
@@ -454,7 +519,7 @@ export const lines = (event: Debug.TraceEvent, options: ValueOptions = {}): Read
|
|
|
454
519
|
text: `sent ${event.event} ${value(event.value)} (runtime.send)`
|
|
455
520
|
}]
|
|
456
521
|
case "deferred": {
|
|
457
|
-
const result: Array<Line
|
|
522
|
+
const result: Array<Omit<Line, "label" | "depth">> = []
|
|
458
523
|
for (const command of event.commands) {
|
|
459
524
|
if (command.effects.length === 0) {
|
|
460
525
|
result.push({ kind: "effect", frame: event.frame, schedule: event.schedule, system: command.system, entity: undefined, subject: undefined, noop: true, text: `${event.marker}: ${command.tag} had no effect` })
|
|
@@ -468,7 +533,7 @@ export const lines = (event: Debug.TraceEvent, options: ValueOptions = {}): Read
|
|
|
468
533
|
entity: applied.entity,
|
|
469
534
|
subject: "component" in applied ? applied.component : "relation" in applied ? applied.relation : undefined,
|
|
470
535
|
noop: applied.kind === "overwrite" && sameValue(applied.before, applied.after),
|
|
471
|
-
text: `${event.marker}: ${effect(applied, options)}`
|
|
536
|
+
text: `${event.marker}: ${effect(applied, options, labels)}`
|
|
472
537
|
})
|
|
473
538
|
}
|
|
474
539
|
}
|
|
@@ -476,13 +541,13 @@ export const lines = (event: Debug.TraceEvent, options: ValueOptions = {}): Read
|
|
|
476
541
|
}
|
|
477
542
|
case "system": {
|
|
478
543
|
const base = { frame: event.frame, schedule: event.schedule, system: event.system }
|
|
479
|
-
const result: Array<Line
|
|
544
|
+
const result: Array<Omit<Line, "label" | "depth">> = []
|
|
480
545
|
const rolledBack = event.outcome === "ok" ? "" : " (rolled back)"
|
|
481
546
|
if (event.outcome !== "ok") {
|
|
482
547
|
result.push({ ...base, kind: "failure", entity: undefined, subject: undefined, noop: false, text: `${event.outcome}: ${value(event.error, options)}` })
|
|
483
548
|
}
|
|
484
549
|
for (const write of event.writes) {
|
|
485
|
-
result.push({ ...base, kind: "write", entity: write.entity, subject: write.component, noop: sameValue(write.before, write.after), text: `write
|
|
550
|
+
result.push({ ...base, kind: "write", entity: write.entity, subject: write.component, noop: sameValue(write.before, write.after), text: `write ${entity(write.entity, labels)} ${write.component} ${change(write.before, write.after, options)}${rolledBack}` })
|
|
486
551
|
}
|
|
487
552
|
for (const write of event.resources) {
|
|
488
553
|
result.push({ ...base, kind: "resource", entity: undefined, subject: write.resource, noop: sameValue(write.before, write.after), text: `resource ${write.resource} ${change(write.before, write.after, options)}${rolledBack}` })
|
|
@@ -510,6 +575,6 @@ export const lines = (event: Debug.TraceEvent, options: ValueOptions = {}): Read
|
|
|
510
575
|
}
|
|
511
576
|
}
|
|
512
577
|
|
|
513
|
-
/** `f12 update Game/Move write e3
|
|
578
|
+
/** `f12 update Game/Move write e3 ...`; a line with `depth` above 0 prints its text alone, indented two spaces per level. */
|
|
514
579
|
export const line = (input: Line): string =>
|
|
515
|
-
`f${input.frame} ${input.schedule} ${input.system ?? "-"} ${input.text}${input.noop && (input.kind === "write" || input.kind === "resource" || input.kind === "effect") ? " (unchanged)" : ""}`
|
|
580
|
+
input.depth > 0 ? `${" ".repeat(input.depth)}${input.text}` : `f${input.frame} ${input.schedule} ${input.system ?? "-"} ${input.text}${input.noop && (input.kind === "write" || input.kind === "resource" || input.kind === "effect") ? " (unchanged)" : ""}`
|