@typeonce/ritmo-devtools 0.13.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.
Files changed (92) hide show
  1. package/CHANGELOG.md +312 -0
  2. package/README.md +336 -58
  3. package/dist/Desync.d.ts +49 -0
  4. package/dist/Desync.d.ts.map +1 -0
  5. package/dist/Desync.js +51 -0
  6. package/dist/Desync.js.map +1 -0
  7. package/dist/Determinism.d.ts +17 -6
  8. package/dist/Determinism.d.ts.map +1 -1
  9. package/dist/Determinism.js +11 -3
  10. package/dist/Determinism.js.map +1 -1
  11. package/dist/Format.d.ts +43 -8
  12. package/dist/Format.d.ts.map +1 -1
  13. package/dist/Format.js +63 -31
  14. package/dist/Format.js.map +1 -1
  15. package/dist/Fuzz.d.ts +268 -0
  16. package/dist/Fuzz.d.ts.map +1 -0
  17. package/dist/Fuzz.js +355 -0
  18. package/dist/Fuzz.js.map +1 -0
  19. package/dist/Invariant.d.ts +6 -2
  20. package/dist/Invariant.d.ts.map +1 -1
  21. package/dist/Invariant.js.map +1 -1
  22. package/dist/Lint.d.ts +9 -3
  23. package/dist/Lint.d.ts.map +1 -1
  24. package/dist/Lint.js.map +1 -1
  25. package/dist/PlaywrightEngine.d.ts +29 -0
  26. package/dist/PlaywrightEngine.d.ts.map +1 -0
  27. package/dist/PlaywrightEngine.js +193 -0
  28. package/dist/PlaywrightEngine.js.map +1 -0
  29. package/dist/Replay.d.ts +43 -34
  30. package/dist/Replay.d.ts.map +1 -1
  31. package/dist/Replay.js +27 -33
  32. package/dist/Replay.js.map +1 -1
  33. package/dist/Session.d.ts +214 -17
  34. package/dist/Session.d.ts.map +1 -1
  35. package/dist/Session.js +563 -57
  36. package/dist/Session.js.map +1 -1
  37. package/dist/Verify.d.ts +147 -0
  38. package/dist/Verify.d.ts.map +1 -0
  39. package/dist/Verify.js +151 -0
  40. package/dist/Verify.js.map +1 -0
  41. package/dist/cli.js +136 -8
  42. package/dist/cli.js.map +1 -1
  43. package/dist/index.d.ts +4 -2
  44. package/dist/index.d.ts.map +1 -1
  45. package/dist/index.js +4 -2
  46. package/dist/index.js.map +1 -1
  47. package/dist/internal/dependencyScan.d.ts +44 -0
  48. package/dist/internal/dependencyScan.d.ts.map +1 -0
  49. package/dist/internal/dependencyScan.js +313 -0
  50. package/dist/internal/dependencyScan.js.map +1 -0
  51. package/dist/internal/fuzzNetwork.d.ts +56 -0
  52. package/dist/internal/fuzzNetwork.d.ts.map +1 -0
  53. package/dist/internal/fuzzNetwork.js +96 -0
  54. package/dist/internal/fuzzNetwork.js.map +1 -0
  55. package/dist/internal/values.d.ts +9 -1
  56. package/dist/internal/values.d.ts.map +1 -1
  57. package/dist/internal/values.js +11 -1
  58. package/dist/internal/values.js.map +1 -1
  59. package/dist/internal/verifyRunner.d.ts +19 -0
  60. package/dist/internal/verifyRunner.d.ts.map +1 -0
  61. package/dist/internal/verifyRunner.js +47 -0
  62. package/dist/internal/verifyRunner.js.map +1 -0
  63. package/dist/internal/version.d.ts +1 -1
  64. package/dist/internal/version.js +1 -1
  65. package/package.json +28 -3
  66. package/src/Desync.ts +100 -0
  67. package/src/Determinism.ts +46 -11
  68. package/src/Format.ts +99 -34
  69. package/src/Fuzz.ts +544 -0
  70. package/src/Invariant.ts +6 -2
  71. package/src/Lint.ts +9 -3
  72. package/src/PlaywrightEngine.ts +229 -0
  73. package/src/Replay.ts +98 -74
  74. package/src/Session.ts +806 -72
  75. package/src/Verify.ts +273 -0
  76. package/src/cli.ts +131 -8
  77. package/src/index.ts +4 -2
  78. package/src/internal/dependencyScan.ts +356 -0
  79. package/src/internal/fuzzNetwork.ts +130 -0
  80. package/src/internal/values.ts +20 -1
  81. package/src/internal/verifyRunner.ts +46 -0
  82. package/src/internal/version.ts +1 -1
  83. package/dist/Monitor.d.ts +0 -101
  84. package/dist/Monitor.d.ts.map +0 -1
  85. package/dist/Monitor.js +0 -602
  86. package/dist/Monitor.js.map +0 -1
  87. package/dist/internal/monitor.d.ts +0 -126
  88. package/dist/internal/monitor.d.ts.map +0 -1
  89. package/dist/internal/monitor.js +0 -279
  90. package/dist/internal/monitor.js.map +0 -1
  91. package/src/Monitor.ts +0 -713
  92. 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). Numbers are rounded to at most 3 decimals for display;
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((step, index) => {
209
- const text = step.kind === "system" ? step.system
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 entity per line, then resources, machines, and pending commands. */
233
- export const dump = (input: Debug.WorldDump, options: ValueOptions = {}): string => {
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 entity of input.entities) {
238
- const components = Object.entries(entity.components).map(([name, component]) => `${name}=${value(component, options)}`)
239
- const relations = Object.entries(entity.relations).map(([name, target]) => `${name}->e${target}`)
240
- lines.push(`e${entity.id} ${[...components, ...relations].join(" ")}`)
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 e${input.entity} ${Object.entries(input.components).map(([name, component]) => `${name}=${value(component, options)}`).join(" ")}`
323
+ return `spawn ${id} ${Object.entries(input.components).map(([name, component]) => `${name}=${value(component, options)}`).join(" ")}`
281
324
  case "despawn":
282
- return `despawn e${input.entity}`
325
+ return `despawn ${id}`
283
326
  case "insert":
284
- return `insert e${input.entity} ${input.component}=${value(input.value, options)}`
327
+ return `insert ${id} ${input.component}=${value(input.value, options)}`
285
328
  case "overwrite":
286
- return `insert e${input.entity} ${input.component} ${change(input.before, input.after, options)}`
329
+ return `insert ${id} ${input.component} ${change(input.before, input.after, options)}`
287
330
  case "remove":
288
- return `remove e${input.entity} ${input.component}`
331
+ return `remove ${id} ${input.component}`
289
332
  case "relate":
290
- return `relate e${input.entity} ${input.relation}->e${input.target}`
333
+ return `relate ${id} ${input.relation}->${entity(input.target, labels)}`
291
334
  case "unrelate":
292
- return `unrelate e${input.entity} ${input.relation}`
335
+ return `unrelate ${id} ${input.relation}`
293
336
  case "relationFailure":
294
- return `relation failure e${input.entity} ${input.relation}: ${input.error}`
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} e${input.entity}: ${input.component} requires ${input.missing}`
343
+ return `skipped ${input.command} ${id}: ${input.component} requires ${input.missing}`
297
344
  case "staleTarget":
298
- return `skipped ${input.command} e${input.entity}: id spawned in an earlier run`
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. Frame and schedule
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 e${write.entity} ${write.component} ${change(write.before, write.after, options)}${rolledBack}` })
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)" : ""}`