@typeonce/ritmo-devtools 0.14.0 → 0.16.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 (109) hide show
  1. package/CHANGELOG.md +283 -0
  2. package/README.md +303 -55
  3. package/dist/Desync.d.ts +23 -3
  4. package/dist/Desync.d.ts.map +1 -1
  5. package/dist/Desync.js +17 -15
  6. package/dist/Desync.js.map +1 -1
  7. package/dist/Determinism.d.ts +20 -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 +66 -31
  14. package/dist/Format.js.map +1 -1
  15. package/dist/Fuzz.d.ts +275 -0
  16. package/dist/Fuzz.d.ts.map +1 -0
  17. package/dist/Fuzz.js +362 -0
  18. package/dist/Fuzz.js.map +1 -0
  19. package/dist/Invariant.d.ts +9 -2
  20. package/dist/Invariant.d.ts.map +1 -1
  21. package/dist/Invariant.js.map +1 -1
  22. package/dist/Lint.d.ts +11 -5
  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 +196 -0
  28. package/dist/PlaywrightEngine.js.map +1 -0
  29. package/dist/Replay.d.ts +47 -23
  30. package/dist/Replay.d.ts.map +1 -1
  31. package/dist/Replay.js +26 -30
  32. package/dist/Replay.js.map +1 -1
  33. package/dist/ReplayNodeSink.d.ts.map +1 -1
  34. package/dist/ReplayNodeSink.js +4 -1
  35. package/dist/ReplayNodeSink.js.map +1 -1
  36. package/dist/ReplayVitePlugin.d.ts +1 -0
  37. package/dist/ReplayVitePlugin.d.ts.map +1 -1
  38. package/dist/ReplayVitePlugin.js.map +1 -1
  39. package/dist/Session.d.ts +224 -18
  40. package/dist/Session.d.ts.map +1 -1
  41. package/dist/Session.js +571 -58
  42. package/dist/Session.js.map +1 -1
  43. package/dist/Verify.d.ts +150 -0
  44. package/dist/Verify.d.ts.map +1 -0
  45. package/dist/Verify.js +154 -0
  46. package/dist/Verify.js.map +1 -0
  47. package/dist/cli.js +157 -16
  48. package/dist/cli.js.map +1 -1
  49. package/dist/index.d.ts +3 -2
  50. package/dist/index.d.ts.map +1 -1
  51. package/dist/index.js +3 -2
  52. package/dist/index.js.map +1 -1
  53. package/dist/internal/dependencyScan.d.ts +44 -0
  54. package/dist/internal/dependencyScan.d.ts.map +1 -0
  55. package/dist/internal/dependencyScan.js +313 -0
  56. package/dist/internal/dependencyScan.js.map +1 -0
  57. package/dist/internal/fuzzNetwork.d.ts +56 -0
  58. package/dist/internal/fuzzNetwork.d.ts.map +1 -0
  59. package/dist/internal/fuzzNetwork.js +96 -0
  60. package/dist/internal/fuzzNetwork.js.map +1 -0
  61. package/dist/internal/simulationCoverage.d.ts.map +1 -1
  62. package/dist/internal/simulationCoverage.js +2 -1
  63. package/dist/internal/simulationCoverage.js.map +1 -1
  64. package/dist/internal/skillLink.d.ts +14 -0
  65. package/dist/internal/skillLink.d.ts.map +1 -0
  66. package/dist/internal/skillLink.js +46 -0
  67. package/dist/internal/skillLink.js.map +1 -0
  68. package/dist/internal/values.d.ts +9 -1
  69. package/dist/internal/values.d.ts.map +1 -1
  70. package/dist/internal/values.js +11 -1
  71. package/dist/internal/values.js.map +1 -1
  72. package/dist/internal/verifyRunner.d.ts +19 -0
  73. package/dist/internal/verifyRunner.d.ts.map +1 -0
  74. package/dist/internal/verifyRunner.js +47 -0
  75. package/dist/internal/verifyRunner.js.map +1 -0
  76. package/dist/internal/version.d.ts +1 -1
  77. package/dist/internal/version.js +1 -1
  78. package/package.json +28 -3
  79. package/src/Desync.ts +40 -17
  80. package/src/Determinism.ts +49 -11
  81. package/src/Format.ts +101 -34
  82. package/src/Fuzz.ts +551 -0
  83. package/src/Invariant.ts +9 -2
  84. package/src/Lint.ts +11 -5
  85. package/src/PlaywrightEngine.ts +232 -0
  86. package/src/Replay.ts +100 -47
  87. package/src/ReplayNodeSink.ts +4 -1
  88. package/src/ReplayVitePlugin.ts +1 -0
  89. package/src/Session.ts +816 -73
  90. package/src/Verify.ts +276 -0
  91. package/src/cli.ts +150 -15
  92. package/src/index.ts +3 -2
  93. package/src/internal/dependencyScan.ts +356 -0
  94. package/src/internal/fuzzNetwork.ts +130 -0
  95. package/src/internal/simulationCoverage.ts +2 -1
  96. package/src/internal/skillLink.ts +53 -0
  97. package/src/internal/values.ts +20 -1
  98. package/src/internal/verifyRunner.ts +46 -0
  99. package/src/internal/version.ts +1 -1
  100. package/dist/Monitor.d.ts +0 -101
  101. package/dist/Monitor.d.ts.map +0 -1
  102. package/dist/Monitor.js +0 -602
  103. package/dist/Monitor.js.map +0 -1
  104. package/dist/internal/monitor.d.ts +0 -126
  105. package/dist/internal/monitor.d.ts.map +0 -1
  106. package/dist/internal/monitor.js +0 -279
  107. package/dist/internal/monitor.js.map +0 -1
  108. package/src/Monitor.ts +0 -713
  109. package/src/internal/monitor.ts +0 -370
@@ -1,370 +0,0 @@
1
- /**
2
- * The data side of the monitor: folds trace events into per-system and
3
- * per-schedule windows, samples the population, keeps alerts and the
4
- * activity of one selected entity. No DOM, so it runs (and is tested) in Node.
5
- *
6
- * Nothing here keeps trace values beyond the selected entity's recent lines:
7
- * every event is reduced to counts and dropped, so a long session costs no
8
- * memory.
9
- */
10
- import type * as Debug from "@typeonce/ritmo/Debug"
11
-
12
- import * as Format from "../Format.ts"
13
- import { nonFinitePath } from "./values.ts"
14
-
15
- /** What one system did during one sample window. */
16
- export interface SystemWindow {
17
- readonly runs: number
18
- readonly skips: number
19
- readonly failures: number
20
- readonly ms: number
21
- readonly maxMs: number
22
- readonly writes: number
23
- readonly events: number
24
- readonly commands: number
25
- readonly spawns: number
26
- readonly despawns: number
27
- }
28
-
29
- /** Top-level schedule runs (ticks) during one sample window. */
30
- export interface ScheduleWindow {
31
- readonly ticks: number
32
- readonly ms: number
33
- readonly maxMs: number
34
- }
35
-
36
- /** One closed sample window, from `Collector.sample`. */
37
- export interface Sample {
38
- /** The `now` passed to `sample` when the window closed. */
39
- readonly at: number
40
- readonly seconds: number
41
- readonly systems: ReadonlyMap<string, SystemWindow>
42
- readonly schedules: ReadonlyMap<string, ScheduleWindow>
43
- readonly population: Debug.Population
44
- /** Time spent folding trace events during the window. */
45
- readonly overheadMs: number
46
- }
47
-
48
- /** A problem the panel flags, counted by kind and subject (a subset of the session `Warning` codes). */
49
- export interface Alert {
50
- readonly code: "system-failed" | "non-finite-value" | "discarded-messages" | "ignored-failure"
51
- readonly message: string
52
- readonly count: number
53
- readonly firstFrame: number
54
- readonly lastFrame: number
55
- }
56
-
57
- /** One change to the selected entity. */
58
- export interface EntityLine {
59
- readonly frame: number
60
- readonly system: string
61
- readonly text: string
62
- }
63
-
64
- /** Entities one system spawned, grouped by their component set. */
65
- export interface SpawnKind {
66
- readonly components: ReadonlyArray<string>
67
- readonly count: number
68
- }
69
-
70
- type MutableWindow = { -readonly [K in keyof SystemWindow]: SystemWindow[K] }
71
- type MutableSchedule = { -readonly [K in keyof ScheduleWindow]: ScheduleWindow[K] }
72
- type MutableAlert = { -readonly [K in keyof Alert]: Alert[K] }
73
-
74
- const emptyWindow = (): MutableWindow => ({
75
- runs: 0, skips: 0, failures: 0, ms: 0, maxMs: 0, writes: 0, events: 0, commands: 0, spawns: 0, despawns: 0
76
- })
77
-
78
- export interface CollectorOptions {
79
- /** Samples kept for sparklines. */
80
- readonly history?: number
81
- /** Lines kept for the selected entity. */
82
- readonly entityLines?: number
83
- }
84
-
85
- export class Collector {
86
- readonly history: Array<Sample> = []
87
- readonly alerts = new Map<string, MutableAlert>()
88
- /** The condition that last skipped each system. */
89
- readonly skippedBy = new Map<string, string>()
90
- /** The last error of each system that failed. */
91
- readonly lastError = new Map<string, string>()
92
- /** Frame of each system's latest run that wrote something. */
93
- readonly lastWrite = new Map<string, number>()
94
- private readonly spawnKinds = new Map<string, Map<string, SpawnKind>>()
95
- private systems = new Map<string, MutableWindow>()
96
- private schedules = new Map<string, MutableSchedule>()
97
- private overhead = 0
98
- private windowStart: number
99
- private selected: number | undefined
100
- private lines: Array<EntityLine> = []
101
- private readonly maxHistory: number
102
- private readonly maxLines: number
103
- private readonly population: () => Debug.Population
104
-
105
- private readonly clock: () => number
106
-
107
- /** `now` reads the host clock (milliseconds); the collector times its own work with it. */
108
- constructor(population: () => Debug.Population, now: () => number, options: CollectorOptions = {}) {
109
- this.population = population
110
- this.clock = now
111
- this.windowStart = now()
112
- this.maxHistory = options.history ?? 60
113
- this.maxLines = options.entityLines ?? 40
114
- }
115
-
116
- /** Folds one trace event. Pass it to `debug.observe`. */
117
- readonly observe = (event: Debug.TraceEvent): void => {
118
- const started = this.clock()
119
- switch (event.type) {
120
- case "system":
121
- this.onSystem(event)
122
- break
123
- case "system.skipped": {
124
- this.windowOf(event.system).skips += 1
125
- this.skippedBy.set(event.system, event.held ? `${event.condition} (paused, holding its stream entries)` : event.condition)
126
- for (const discarded of event.discarded) {
127
- this.alert(
128
- "discarded-messages",
129
- `discarded:${event.system}:${discarded.stream}`,
130
- `${event.system} was skipped (${event.condition}) and discarded ${discarded.stream}`,
131
- event.frame
132
- )
133
- }
134
- break
135
- }
136
- case "deferred":
137
- this.onDeferred(event)
138
- break
139
- case "failure.ignored":
140
- this.alert("ignored-failure", `ignored:${event.frame}`, Format.ignoredFailure(event), event.frame)
141
- break
142
- case "schedule.end":
143
- if (!event.schedule.includes(" > ")) {
144
- const schedule = this.scheduleOf(event.schedule)
145
- schedule.ticks += 1
146
- schedule.ms += event.ms
147
- schedule.maxMs = Math.max(schedule.maxMs, event.ms)
148
- }
149
- break
150
- }
151
- this.overhead += Math.max(0, this.clock() - started)
152
- }
153
-
154
- private windowOf(system: string): MutableWindow {
155
- let window = this.systems.get(system)
156
- if (!window) {
157
- window = emptyWindow()
158
- this.systems.set(system, window)
159
- }
160
- return window
161
- }
162
-
163
- private scheduleOf(name: string): MutableSchedule {
164
- let schedule = this.schedules.get(name)
165
- if (!schedule) {
166
- schedule = { ticks: 0, ms: 0, maxMs: 0 }
167
- this.schedules.set(name, schedule)
168
- }
169
- return schedule
170
- }
171
-
172
- private alert(code: Alert["code"], key: string, message: string, frame: number) {
173
- const existing = this.alerts.get(key)
174
- if (existing) {
175
- existing.count += 1
176
- existing.lastFrame = frame
177
- } else {
178
- this.alerts.set(key, { code, message, count: 1, firstFrame: frame, lastFrame: frame })
179
- }
180
- }
181
-
182
- private checkFinite(system: string, subject: string, value: unknown, frame: number, entity?: number) {
183
- const path = nonFinitePath(value)
184
- if (path === undefined) return
185
- this.alert(
186
- "non-finite-value",
187
- `nonfinite:${system}:${subject}`,
188
- `${system} wrote NaN or an infinity to ${entity === undefined ? "" : `e${entity} `}${subject}${path}`,
189
- frame
190
- )
191
- }
192
-
193
- private line(frame: number, system: string, text: string) {
194
- this.lines.push({ frame, system, text })
195
- if (this.lines.length > this.maxLines) this.lines.shift()
196
- }
197
-
198
- private onSystem(event: Debug.SystemEvent) {
199
- const window = this.windowOf(event.system)
200
- window.runs += 1
201
- window.ms += event.ms
202
- window.maxMs = Math.max(window.maxMs, event.ms)
203
- if (event.outcome !== "ok") {
204
- window.failures += 1
205
- const error = Format.value(event.error)
206
- this.lastError.set(event.system, error)
207
- this.alert("system-failed", `failed:${event.system}`, `${event.system} ${event.outcome === "defect" ? "threw" : "failed"}: ${error}`, event.frame)
208
- return
209
- }
210
- const written = event.writes.length + event.resources.length
211
- window.writes += written
212
- window.commands += event.commands.length
213
- if (written > 0) this.lastWrite.set(event.system, event.frame)
214
- for (const write of event.writes) {
215
- this.checkFinite(event.system, write.component, write.after, event.frame, write.entity)
216
- if (write.entity === this.selected) this.line(event.frame, event.system, `${write.component} ${Format.change(write.before, write.after)}`)
217
- }
218
- for (const write of event.resources) this.checkFinite(event.system, write.resource, write.after, event.frame)
219
- for (const emit of event.events) {
220
- window.events += emit.values.length
221
- this.checkFinite(event.system, emit.event, emit.values, event.frame)
222
- }
223
- }
224
-
225
- private onDeferred(event: Debug.DeferredEvent) {
226
- for (const command of event.commands) {
227
- const window = this.windowOf(command.system)
228
- for (const effect of command.effects) {
229
- switch (effect.kind) {
230
- case "spawn": {
231
- window.spawns += 1
232
- const components = Object.keys(effect.components).sort()
233
- const kinds = this.spawnKinds.get(command.system) ?? new Map<string, SpawnKind>()
234
- this.spawnKinds.set(command.system, kinds)
235
- const key = components.join(",")
236
- kinds.set(key, { components, count: (kinds.get(key)?.count ?? 0) + 1 })
237
- for (const [component, value] of Object.entries(effect.components)) {
238
- this.checkFinite(command.system, component, value, event.frame, effect.entity)
239
- }
240
- if (effect.entity === this.selected) this.line(event.frame, command.system, `spawned with ${components.join(", ")}`)
241
- break
242
- }
243
- case "despawn":
244
- window.despawns += 1
245
- if (effect.entity === this.selected) this.line(event.frame, command.system, "despawned")
246
- break
247
- case "insert":
248
- this.checkFinite(command.system, effect.component, effect.value, event.frame, effect.entity)
249
- if (effect.entity === this.selected) this.line(event.frame, command.system, `+${effect.component} ${Format.value(effect.value)}`)
250
- break
251
- case "overwrite":
252
- this.checkFinite(command.system, effect.component, effect.after, event.frame, effect.entity)
253
- if (effect.entity === this.selected) this.line(event.frame, command.system, `${effect.component} ${Format.change(effect.before, effect.after)}`)
254
- break
255
- case "remove":
256
- if (effect.entity === this.selected) this.line(event.frame, command.system, `-${effect.component}`)
257
- break
258
- case "relate":
259
- case "unrelate":
260
- case "relationFailure":
261
- if (effect.entity === this.selected) this.line(event.frame, command.system, `${effect.kind} ${effect.relation}`)
262
- break
263
- }
264
- }
265
- }
266
- }
267
-
268
- /** Closes the current window and starts a new one. */
269
- sample(now: number): Sample {
270
- const sample: Sample = {
271
- at: now,
272
- seconds: Math.max(1e-6, (now - this.windowStart) / 1000),
273
- systems: this.systems,
274
- schedules: this.schedules,
275
- population: this.population(),
276
- overheadMs: this.overhead
277
- }
278
- this.history.push(sample)
279
- if (this.history.length > this.maxHistory) this.history.shift()
280
- this.systems = new Map()
281
- this.schedules = new Map()
282
- this.overhead = 0
283
- this.windowStart = now
284
- return sample
285
- }
286
-
287
- /** Entities a system spawned, by component set, most frequent first. */
288
- spawnsOf(system: string): ReadonlyArray<SpawnKind> {
289
- return [...(this.spawnKinds.get(system)?.values() ?? [])].sort((left, right) => right.count - left.count)
290
- }
291
-
292
- /**
293
- * What a system spawns, one name per kind: the component of that kind found
294
- * in the fewest spawn kinds seen so far (from any system); ties are broken
295
- * by `compare` (for example: fewest live entities, then most readers).
296
- */
297
- spawnNames(system: string, compare: (left: string, right: string) => number): ReadonlyArray<string> {
298
- const kindsWith = new Map<string, number>()
299
- const all = new Map<string, ReadonlyArray<string>>()
300
- for (const kinds of this.spawnKinds.values()) {
301
- for (const [key, kind] of kinds) all.set(key, kind.components)
302
- }
303
- for (const components of all.values()) {
304
- for (const component of components) kindsWith.set(component, (kindsWith.get(component) ?? 0) + 1)
305
- }
306
- const names = this.spawnsOf(system).map((kind) =>
307
- [...kind.components].sort((left, right) =>
308
- (kindsWith.get(left) ?? 0) - (kindsWith.get(right) ?? 0) || compare(left, right) || left.localeCompare(right))[0] ?? "entity")
309
- return [...new Set(names)]
310
- }
311
-
312
- /** Follows one entity's changes from now on (`undefined` stops). */
313
- select(entity: number | undefined): void {
314
- if (entity === this.selected) return
315
- this.selected = entity
316
- this.lines = []
317
- }
318
-
319
- get selection(): number | undefined {
320
- return this.selected
321
- }
322
-
323
- get entityLines(): ReadonlyArray<EntityLine> {
324
- return this.lines
325
- }
326
-
327
- /** Clears alerts, e.g. after the user dismissed them. */
328
- clearAlerts(): void {
329
- this.alerts.clear()
330
- }
331
- }
332
-
333
- /** Totals of a system over the last `count` samples. */
334
- export const recentSystem = (history: ReadonlyArray<Sample>, system: string, count: number): SystemWindow & { readonly seconds: number } => {
335
- const total = emptyWindow()
336
- let seconds = 0
337
- for (const sample of history.slice(-count)) {
338
- seconds += sample.seconds
339
- const window = sample.systems.get(system)
340
- if (!window) continue
341
- total.runs += window.runs
342
- total.skips += window.skips
343
- total.failures += window.failures
344
- total.ms += window.ms
345
- total.maxMs = Math.max(total.maxMs, window.maxMs)
346
- total.writes += window.writes
347
- total.events += window.events
348
- total.commands += window.commands
349
- total.spawns += window.spawns
350
- total.despawns += window.despawns
351
- }
352
- return { ...total, seconds }
353
- }
354
-
355
- /** Totals of a top-level schedule over the last `count` samples. */
356
- export const recentSchedule = (history: ReadonlyArray<Sample>, schedule: string, count: number): ScheduleWindow & { readonly seconds: number } => {
357
- let ticks = 0
358
- let ms = 0
359
- let maxMs = 0
360
- let seconds = 0
361
- for (const sample of history.slice(-count)) {
362
- seconds += sample.seconds
363
- const window = sample.schedules.get(schedule)
364
- if (!window) continue
365
- ticks += window.ticks
366
- ms += window.ms
367
- maxMs = Math.max(maxMs, window.maxMs)
368
- }
369
- return { ticks, ms, maxMs, seconds }
370
- }