@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.
- package/CHANGELOG.md +312 -0
- package/README.md +336 -58
- package/dist/Desync.d.ts +49 -0
- package/dist/Desync.d.ts.map +1 -0
- package/dist/Desync.js +51 -0
- package/dist/Desync.js.map +1 -0
- 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/Lint.d.ts +9 -3
- package/dist/Lint.d.ts.map +1 -1
- package/dist/Lint.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 +43 -34
- package/dist/Replay.d.ts.map +1 -1
- package/dist/Replay.js +27 -33
- 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 +4 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -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 +100 -0
- 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/Lint.ts +9 -3
- package/src/PlaywrightEngine.ts +229 -0
- package/src/Replay.ts +98 -74
- package/src/Session.ts +806 -72
- package/src/Verify.ts +273 -0
- package/src/cli.ts +131 -8
- package/src/index.ts +4 -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/Session.ts
CHANGED
|
@@ -7,21 +7,34 @@
|
|
|
7
7
|
* - `run(name, { frames, until })` ticks a schedule frame by frame and stops
|
|
8
8
|
* at the first system failure, thrown defect, or violated invariant (an
|
|
9
9
|
* invariant that throws stops it as `invariant-threw`).
|
|
10
|
+
* - `step(name)` begins one frame and runs it a step at a time
|
|
11
|
+
* (`until(System)`, `next()`, `finish()`), for a value that goes wrong
|
|
12
|
+
* between two systems of one frame. `journal`, `why`, and `dump` show the
|
|
13
|
+
* partial frame.
|
|
10
14
|
* - `journal(filter)` lists what happened, one fact per line, filtered by
|
|
11
15
|
* frames, entity, component, resource, event, machine, system, or kind.
|
|
12
16
|
* - `why(entity, component)` lists the latest changes to one component, and
|
|
13
|
-
* the systems whose declared `spawns` could have spawned the entity.
|
|
17
|
+
* the systems whose declared `spawns` could have spawned the entity. With
|
|
18
|
+
* `depth` above 1 it follows each change back through what the writing
|
|
19
|
+
* system declared it reads, one level per step (see {@link WhyOptions}).
|
|
14
20
|
* - `system(name)` shows one system's declared access and recent activity.
|
|
15
21
|
* - `describe()`, `dump(filter)`, `streams()` render the core debug handle.
|
|
16
22
|
* - `report()` summarizes per-system timing and warnings accumulated while
|
|
17
23
|
* tracing: failed systems, missed reads, commands and next states still
|
|
18
24
|
* pending at the end of a frame, failed transitions, skipped systems that
|
|
19
25
|
* discarded messages, sent events no system reads, NaN or infinite numbers
|
|
20
|
-
* written anywhere,
|
|
26
|
+
* written anywhere, numbers written outside a field's declared `range`
|
|
27
|
+
* (the descriptor's `meta` option), entity counts that keep growing through a run, and
|
|
21
28
|
* failed tick results nobody read.
|
|
22
29
|
*
|
|
23
30
|
* Everything returns a `Rendered` value that prints as text.
|
|
24
31
|
*
|
|
32
|
+
* With `labels`, every entity in that text prints as `player e12` instead of
|
|
33
|
+
* `e12`: journal and `why` lines, `dump`, report warnings, and invariant
|
|
34
|
+
* messages. Labels are evaluated after every frame of a `run`, so a line
|
|
35
|
+
* shows the label its entity had at the end of the line's frame; an entity
|
|
36
|
+
* despawned by then keeps the last label it had.
|
|
37
|
+
*
|
|
25
38
|
* @module Session
|
|
26
39
|
* @docGroup devtools
|
|
27
40
|
*
|
|
@@ -30,7 +43,8 @@
|
|
|
30
43
|
* const session = Session.make(runtime, {
|
|
31
44
|
* hostClock: HostClock.test(),
|
|
32
45
|
* schedules: { setup: setupSchedule, update: updateSchedule },
|
|
33
|
-
* invariants: [PlayerInsideWorld]
|
|
46
|
+
* invariants: [PlayerInsideWorld],
|
|
47
|
+
* labels: Labels
|
|
34
48
|
* })
|
|
35
49
|
* session.run("setup")
|
|
36
50
|
* console.log(session.run("update", { frames: 300 }))
|
|
@@ -38,19 +52,19 @@
|
|
|
38
52
|
* console.log(session.journal({ frames: [180, 185], entity: 1 }))
|
|
39
53
|
* ```
|
|
40
54
|
*/
|
|
41
|
-
import { HostClock } from "@typeonce/ritmo"
|
|
55
|
+
import { HostClock, Result } from "@typeonce/ritmo"
|
|
42
56
|
import type * as Debug from "@typeonce/ritmo/Debug"
|
|
43
57
|
import type * as Inspector from "@typeonce/ritmo/Inspector"
|
|
44
58
|
import type * as Machine from "@typeonce/ritmo/Machine"
|
|
45
|
-
import type * as Result from "@typeonce/ritmo/Result"
|
|
46
59
|
import type * as Runtime from "@typeonce/ritmo/Runtime"
|
|
47
60
|
import type { AnyScheduleOrder, ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule"
|
|
48
61
|
import type { Schema } from "@typeonce/ritmo/Schema"
|
|
62
|
+
import type { SystemDefinition } from "@typeonce/ritmo/System"
|
|
49
63
|
|
|
50
64
|
import * as Format from "./Format.ts"
|
|
51
65
|
import type { Invariant } from "./Invariant.ts"
|
|
52
66
|
import * as Rendered from "./Rendered.ts"
|
|
53
|
-
import { nonFinitePath } from "./internal/values.ts"
|
|
67
|
+
import { nonFinitePath, rangesOf } from "./internal/values.ts"
|
|
54
68
|
|
|
55
69
|
/**
|
|
56
70
|
* What a session needs from a runtime: its debug handle, the dynamic
|
|
@@ -97,12 +111,59 @@ export type ValidateInvariants<
|
|
|
97
111
|
? unknown
|
|
98
112
|
: { readonly __fixInvariantRequirements__: InvariantRequirementErrors<Invariants, Services, Resources, Machines> }
|
|
99
113
|
|
|
114
|
+
/**
|
|
115
|
+
* Names entities in devtools text: a `Game.Inspector` returning a
|
|
116
|
+
* `ReadonlyMap<number, string>` from entity id to label (`player`,
|
|
117
|
+
* `enemy:slime`). It reads the world like an invariant does and is checked
|
|
118
|
+
* the same way; {@link ValidateLabels} rejects one returning anything else.
|
|
119
|
+
* It runs only in a debug session: the game and its runtime never call it.
|
|
120
|
+
*
|
|
121
|
+
* @example
|
|
122
|
+
* ```ts
|
|
123
|
+
* const Labels = Game.Inspector("labels", {
|
|
124
|
+
* queries: { players: Game.Query({ selection: { position: Game.Query.read(Position) }, with: [Player] }) }
|
|
125
|
+
* }, ({ queries }) => new Map(queries.players.each().map((match) => [match.entity.id, "player"] as const)))
|
|
126
|
+
* Session.make(runtime, { hostClock, schedules: { update }, labels: Labels })
|
|
127
|
+
* ```
|
|
128
|
+
*/
|
|
129
|
+
export type LabelsInspector<Root = any> = Inspector.InspectorDefinition<any, unknown, Root, any, any>
|
|
130
|
+
|
|
131
|
+
type LabelsRequirementErrors<
|
|
132
|
+
Labels extends Inspector.Inspector.Any,
|
|
133
|
+
Services extends Record<string, unknown>,
|
|
134
|
+
Resources extends object,
|
|
135
|
+
Machines extends Record<string, unknown>
|
|
136
|
+
> = Runtime.ValidateInspector<Labels, Services, Resources, Machines> extends {
|
|
137
|
+
readonly __fixRuntimeRequirements__: infer Errors
|
|
138
|
+
}
|
|
139
|
+
? Errors
|
|
140
|
+
: never
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Rejects a `labels` inspector that does not return a
|
|
144
|
+
* `ReadonlyMap<number, string>`, or that reads a resource, service, or
|
|
145
|
+
* machine the runtime does not provide (named like invariants' are).
|
|
146
|
+
*/
|
|
147
|
+
export type ValidateLabels<
|
|
148
|
+
Labels extends Inspector.Inspector.Any,
|
|
149
|
+
Services extends Record<string, unknown>,
|
|
150
|
+
Resources extends object,
|
|
151
|
+
Machines extends Record<string, unknown>
|
|
152
|
+
> = [Labels] extends [never]
|
|
153
|
+
? unknown
|
|
154
|
+
: [Inspector.Inspector.Value<Labels>] extends [ReadonlyMap<number, string>]
|
|
155
|
+
? [LabelsRequirementErrors<Labels, Services, Resources, Machines>] extends [never]
|
|
156
|
+
? unknown
|
|
157
|
+
: { readonly __fixLabelsRequirements__: LabelsRequirementErrors<Labels, Services, Resources, Machines> }
|
|
158
|
+
: { readonly __fixLabels__: "labels must return a ReadonlyMap<number, string> from entity id to label" }
|
|
159
|
+
|
|
100
160
|
/** What `Session.make` drives and checks, and how it prints. */
|
|
101
161
|
export interface Options<
|
|
102
162
|
S extends Schema.Any,
|
|
103
163
|
Root,
|
|
104
164
|
Names extends string,
|
|
105
|
-
Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly []
|
|
165
|
+
Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly [],
|
|
166
|
+
Labels extends LabelsInspector<Root> = never
|
|
106
167
|
> {
|
|
107
168
|
/** The schedules `run` can drive, by name. Also names them in traces. */
|
|
108
169
|
readonly schedules: Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>
|
|
@@ -124,6 +185,14 @@ export interface Options<
|
|
|
124
185
|
* stops the run. Built with `Invariant.fromInspector(Game.Inspector(...))`.
|
|
125
186
|
*/
|
|
126
187
|
readonly invariants?: Invariants
|
|
188
|
+
/**
|
|
189
|
+
* Names entities in all text output (`player e12`), from a
|
|
190
|
+
* {@link LabelsInspector}. Evaluated after every frame of a `run` (and
|
|
191
|
+
* when a query finds frames ticked outside `run`), so journal lines show
|
|
192
|
+
* the label from the end of their frame; despawned entities keep their
|
|
193
|
+
* last label.
|
|
194
|
+
*/
|
|
195
|
+
readonly labels?: Labels
|
|
127
196
|
/** Frames of trace history kept for `journal` and `why`. Defaults to 600. */
|
|
128
197
|
readonly history?: number
|
|
129
198
|
/**
|
|
@@ -156,6 +225,8 @@ export type Stop =
|
|
|
156
225
|
| { readonly reason: "invariant"; readonly frame: number; readonly invariant: string; readonly message: string }
|
|
157
226
|
/** The invariant itself threw: a bug in the check, not a violation. Fix the check, then run again. */
|
|
158
227
|
| { readonly reason: "invariant-threw"; readonly frame: number; readonly invariant: string; readonly error: unknown }
|
|
228
|
+
/** The `labels` inspector threw: a bug in it. Fix it, then run again. */
|
|
229
|
+
| { readonly reason: "labels-threw"; readonly frame: number; readonly error: unknown }
|
|
159
230
|
/**
|
|
160
231
|
* A failed tick result nobody read (for example a setup tick the game ran
|
|
161
232
|
* before this run): `frame` is the failed tick's, `skipped` the systems
|
|
@@ -229,6 +300,46 @@ export interface JournalFilter<S extends Schema.Any> {
|
|
|
229
300
|
readonly verbose?: boolean
|
|
230
301
|
}
|
|
231
302
|
|
|
303
|
+
/**
|
|
304
|
+
* How far `why` and `whyResource` look back.
|
|
305
|
+
*
|
|
306
|
+
* The trace records what systems wrote, not what they read, so a level
|
|
307
|
+
* past the first comes from declarations: under each change, one indented
|
|
308
|
+
* `read` line per read the writing system declares, each with the latest
|
|
309
|
+
* traced fact that could have produced the value it saw then:
|
|
310
|
+
*
|
|
311
|
+
* - an event: what was published to it since the system's previous run,
|
|
312
|
+
* and by which system (or `runtime.send`);
|
|
313
|
+
* - a component of the written entity, read in the query that wrote it: the
|
|
314
|
+
* latest write, spawn, or insert of it on that entity before the run;
|
|
315
|
+
* - a component of any other query: only how many entities match it now,
|
|
316
|
+
* since the trace does not say which ones the system read;
|
|
317
|
+
* - a resource: its latest write before the run;
|
|
318
|
+
* - a machine: its latest transition or field update before the run.
|
|
319
|
+
*
|
|
320
|
+
* Every such line ends in `(declared)`: a possible cause, not an observed
|
|
321
|
+
* read. A system already in the chain is printed with `(cycle: not
|
|
322
|
+
* followed)` and not followed again.
|
|
323
|
+
*
|
|
324
|
+
* @example
|
|
325
|
+
* ```ts
|
|
326
|
+
* session.why(12, Health, { depth: 3 })
|
|
327
|
+
* // f181 update Game/ApplyDamage write e12 Game/Health 70 -> 40
|
|
328
|
+
* // read Game/Damage [{amount:30}] (declared), emitted by Game/Hitscan at f181
|
|
329
|
+
* // read e12 Game/Aim {target:7} (declared), written by Game/AimAtNewest at f180
|
|
330
|
+
* ```
|
|
331
|
+
*/
|
|
332
|
+
export interface WhyOptions {
|
|
333
|
+
/** Changes listed, and reads listed under each change. Defaults to 5. */
|
|
334
|
+
readonly limit?: number
|
|
335
|
+
/**
|
|
336
|
+
* Levels printed: 1 (the default) lists the changes alone; 2 adds what
|
|
337
|
+
* each writing system declared it reads and who produced it; 3 adds the
|
|
338
|
+
* reads of those producers, and so on.
|
|
339
|
+
*/
|
|
340
|
+
readonly depth?: number
|
|
341
|
+
}
|
|
342
|
+
|
|
232
343
|
/** One system's runs and timing over the session, in `report()` and `system(name)`. */
|
|
233
344
|
export interface SystemStats {
|
|
234
345
|
readonly system: string
|
|
@@ -257,6 +368,7 @@ export interface Warning {
|
|
|
257
368
|
| "sent-event-unread"
|
|
258
369
|
| "system-failed"
|
|
259
370
|
| "non-finite-value"
|
|
371
|
+
| "out-of-range"
|
|
260
372
|
| "population-growing"
|
|
261
373
|
| "ignored-failure"
|
|
262
374
|
readonly message: string
|
|
@@ -286,16 +398,122 @@ export interface SystemActivity {
|
|
|
286
398
|
readonly recent: ReadonlyArray<Format.Line>
|
|
287
399
|
}
|
|
288
400
|
|
|
401
|
+
type AnySystem = SystemDefinition<any, any, any, any, any>
|
|
402
|
+
|
|
403
|
+
/** The systems a schedule runs as its own steps: nested schedules included, transition schedules (run inside a marker) not. */
|
|
404
|
+
type StepSystemsIn<Entry> =
|
|
405
|
+
Entry extends AnySystem ? Entry
|
|
406
|
+
: Entry extends { readonly kind: "applyStateTransitions" } ? never
|
|
407
|
+
: Entry extends { readonly __order?: (_: never) => infer Order extends AnyScheduleOrder } ? StepSystemsIn<Order["entries"][number]>
|
|
408
|
+
: never
|
|
409
|
+
|
|
410
|
+
/**
|
|
411
|
+
* The systems `frame.until(...)` accepts for one schedule: the systems it
|
|
412
|
+
* runs as steps, so a system of another schedule does not compile. A
|
|
413
|
+
* schedule whose type was widened accepts any system, and `until` reports
|
|
414
|
+
* one it does not run as `notAhead`.
|
|
415
|
+
*/
|
|
416
|
+
export type StepSystem<Schedule> = [StepSystemsIn<Schedule>] extends [never] ? AnySystem : StepSystemsIn<Schedule>
|
|
417
|
+
|
|
418
|
+
/**
|
|
419
|
+
* Why a step call did not get where it was asked to.
|
|
420
|
+
*
|
|
421
|
+
* - `frameEnded`: the frame already ended (its last step ran, or a system
|
|
422
|
+
* failed); nothing ran. `finish()` reports the frame.
|
|
423
|
+
* - `notAhead`: the system is not among the steps left (it already ran
|
|
424
|
+
* this frame, or the schedule does not run it as a step); nothing ran.
|
|
425
|
+
* - `failure` / `defect`: a system returned a failure or a step threw; the
|
|
426
|
+
* steps after it do not run this frame, and the frame ended.
|
|
427
|
+
* - `missingRequirements` / `tickOrder`: the frame never began, as `run`
|
|
428
|
+
* reports them.
|
|
429
|
+
*/
|
|
430
|
+
export type StepStop =
|
|
431
|
+
| { readonly reason: "frameEnded"; readonly frame: number }
|
|
432
|
+
| { readonly reason: "notAhead"; readonly frame: number; readonly system: string; readonly remaining: ReadonlyArray<Debug.StepDescription> }
|
|
433
|
+
| Extract<Stop, { readonly reason: "failure" | "defect" | "missingRequirements" | "tickOrder" }>
|
|
434
|
+
|
|
435
|
+
/** Where `frame.until(system)` stopped: before `system`, which has not run yet. */
|
|
436
|
+
export interface StepReached {
|
|
437
|
+
readonly frame: number
|
|
438
|
+
readonly system: string
|
|
439
|
+
/** The steps this call ran, in order (empty when `system` was already next). */
|
|
440
|
+
readonly ran: ReadonlyArray<Debug.StepDescription>
|
|
441
|
+
}
|
|
442
|
+
|
|
443
|
+
/** The step `frame.next()` ran. */
|
|
444
|
+
export interface StepRan {
|
|
445
|
+
readonly frame: number
|
|
446
|
+
readonly step: Debug.StepDescription
|
|
447
|
+
/** `true` when it was the last step: the frame ended, and `finish()` evaluates it. */
|
|
448
|
+
readonly ended: boolean
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
/** A violated or throwing invariant found by `frame.check()`. */
|
|
452
|
+
export type CheckStop = Extract<Stop, { readonly reason: "invariant" | "invariant-threw" }>
|
|
453
|
+
|
|
454
|
+
/**
|
|
455
|
+
* One frame of a schedule run a step at a time, begun by `session.step(name)`.
|
|
456
|
+
* Each system run still commits at its end, markers apply at their position,
|
|
457
|
+
* and reader cursors advance as in `run`: only the pauses are new. While it
|
|
458
|
+
* is open, `run`, `step`, and the runtime's `tick`, `send`, `snapshot`,
|
|
459
|
+
* `restore`, `checkpoint`, and `rewind` are refused; `finish()` it first.
|
|
460
|
+
*/
|
|
461
|
+
export interface SteppedFrame<System> {
|
|
462
|
+
/**
|
|
463
|
+
* Runs the steps (systems and markers) before `system` and stops before
|
|
464
|
+
* it. Takes the system value placed in the schedule, so names that repeat
|
|
465
|
+
* across schedules stay unambiguous and a system the schedule does not
|
|
466
|
+
* run does not compile.
|
|
467
|
+
*/
|
|
468
|
+
readonly until: (system: System) => Rendered.Rendered<Result.Result<StepReached, StepStop>>
|
|
469
|
+
/** Runs exactly one step. */
|
|
470
|
+
readonly next: () => Rendered.Rendered<Result.Result<StepRan, StepStop>>
|
|
471
|
+
/** The steps not run yet, in order; empty once the frame has ended. */
|
|
472
|
+
readonly remaining: () => Rendered.Rendered<ReadonlyArray<Debug.StepDescription>>
|
|
473
|
+
/**
|
|
474
|
+
* Evaluates the session's invariants now, between two steps. An invariant
|
|
475
|
+
* may legitimately fail mid-frame (a marker later in the frame applies the
|
|
476
|
+
* commands that restore it), so this is only an explicit question:
|
|
477
|
+
* `finish()` checks the invariants at the end of the frame, as `run` does.
|
|
478
|
+
* Like labels, it reads the world through inspectors, which advances the
|
|
479
|
+
* world's change tick: tick numbers in this frame then differ from an
|
|
480
|
+
* unstepped run's.
|
|
481
|
+
*/
|
|
482
|
+
readonly check: () => Rendered.Rendered<Result.Result<void, CheckStop>>
|
|
483
|
+
/**
|
|
484
|
+
* Runs the rest of the frame and reports it as `run(name, { frames: 1 })`
|
|
485
|
+
* would: the same `RunResult`, with labels and invariants evaluated at the
|
|
486
|
+
* end of the frame. A system failure or defect during an earlier step is
|
|
487
|
+
* its stop. Calling it again returns the same result.
|
|
488
|
+
*/
|
|
489
|
+
readonly finish: () => Rendered.Rendered<RunResult>
|
|
490
|
+
}
|
|
491
|
+
|
|
289
492
|
/** A debug session made by `Session.make`; see the module description for each query. */
|
|
290
|
-
export interface Session<
|
|
493
|
+
export interface Session<
|
|
494
|
+
S extends Schema.Any,
|
|
495
|
+
Names extends string,
|
|
496
|
+
Schedules extends Readonly<Record<Names, unknown>> = Readonly<Record<Names, ExecutableScheduleDefinition<S, any, any, any, any, AnyScheduleOrder>>>
|
|
497
|
+
> {
|
|
291
498
|
/** Ticks the named schedule frame by frame; stops at the first failure, defect, or violated invariant. */
|
|
292
499
|
readonly run: (name: Names, options?: RunOptions) => Rendered.Rendered<RunResult>
|
|
500
|
+
/**
|
|
501
|
+
* Begins one frame of the named schedule, to run it a step at a time (see
|
|
502
|
+
* {@link SteppedFrame}). Use it when a value goes wrong between two systems
|
|
503
|
+
* of one frame; use `run` for whole frames.
|
|
504
|
+
*/
|
|
505
|
+
readonly step: <Name extends Names>(name: Name) => SteppedFrame<StepSystem<Schedules[Name]>>
|
|
293
506
|
/** What happened in the kept history, one fact per line. */
|
|
294
507
|
readonly journal: (filter?: JournalFilter<S>) => Rendered.Rendered<ReadonlyArray<Format.Line>>
|
|
295
|
-
/**
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
508
|
+
/**
|
|
509
|
+
* Latest changes to one entity's component, and the systems whose `spawns`
|
|
510
|
+
* could have spawned it; with `depth` above 1, what each writing system
|
|
511
|
+
* declared it reads, under each change ({@link WhyOptions}). Use
|
|
512
|
+
* `whyResource` for resources.
|
|
513
|
+
*/
|
|
514
|
+
readonly why: (entity: number, component: Schema.ComponentDescriptor<S>, options?: WhyOptions) => Rendered.Rendered<ReadonlyArray<Format.Line>>
|
|
515
|
+
/** Latest changes to one resource and the systems that made them; `depth` as for `why`. */
|
|
516
|
+
readonly whyResource: (resource: Schema.ResourceDescriptor<S>, options?: WhyOptions) => Rendered.Rendered<ReadonlyArray<Format.Line>>
|
|
299
517
|
/** One system's declared access and recent activity. */
|
|
300
518
|
readonly system: (name: string, options?: { readonly limit?: number }) => Rendered.Rendered<SystemActivity>
|
|
301
519
|
/** `debug.describe()`, lints first. */
|
|
@@ -315,8 +533,13 @@ export interface Session<S extends Schema.Any, Names extends string> {
|
|
|
315
533
|
interface FrameRecord {
|
|
316
534
|
readonly frame: number
|
|
317
535
|
readonly events: Array<Debug.TraceEvent>
|
|
536
|
+
/** The labels at the end of this frame, when they were evaluated then. */
|
|
537
|
+
labels?: ReadonlyMap<number, string>
|
|
318
538
|
}
|
|
319
539
|
|
|
540
|
+
/** `e12` tokens in free text (not `&e12` handles), as an invariant writes them. */
|
|
541
|
+
const entityToken = /(?<![\w&])e(\d+)\b/g
|
|
542
|
+
|
|
320
543
|
const inRange = (frame: number, frames: number | readonly [number, number] | undefined): boolean =>
|
|
321
544
|
frames === undefined ? true
|
|
322
545
|
: typeof frames === "number" ? frame === frames
|
|
@@ -342,6 +565,16 @@ const growsSteadily = (samples: ReadonlyArray<number>): boolean => {
|
|
|
342
565
|
return true
|
|
343
566
|
}
|
|
344
567
|
|
|
568
|
+
/** The stop for a failed tick or step result, as `run` reports it. */
|
|
569
|
+
const failureStop = (failure: unknown, frame: number): Extract<Stop, { readonly reason: "failure" | "missingRequirements" | "tickOrder" }> => {
|
|
570
|
+
const error = describeError(failure)
|
|
571
|
+
return error.kind === "MissingRuntimeRequirements"
|
|
572
|
+
? { reason: "missingRequirements", frame, requirements: error.requirements }
|
|
573
|
+
: error.kind === "TickOrderViolation"
|
|
574
|
+
? { reason: "tickOrder", frame, issues: (error.issues ?? []).map((issue) => issue.message) }
|
|
575
|
+
: { reason: "failure", frame, system: typeof error.system === "string" ? error.system : "(unknown)", error: error.error }
|
|
576
|
+
}
|
|
577
|
+
|
|
345
578
|
const describeError = (error: unknown): { readonly kind?: unknown; readonly system?: unknown; readonly error?: unknown; readonly requirements?: unknown; readonly issues?: ReadonlyArray<{ readonly message: string }> } =>
|
|
346
579
|
typeof error === "object" && error !== null ? error : {}
|
|
347
580
|
|
|
@@ -358,12 +591,18 @@ export const make = <
|
|
|
358
591
|
Resources extends object,
|
|
359
592
|
Machines extends Record<string, unknown>,
|
|
360
593
|
const Names extends string,
|
|
361
|
-
const
|
|
594
|
+
const Schedules extends Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>,
|
|
595
|
+
const Invariants extends ReadonlyArray<Invariant<Inspector.InspectorDefinition<any, string | undefined, Root, any, any>>> = readonly [],
|
|
596
|
+
const Labels extends LabelsInspector<Root> = never
|
|
362
597
|
>(
|
|
363
598
|
runtime: Target<S, Root, Services, Resources, Machines>,
|
|
364
|
-
options:
|
|
365
|
-
|
|
366
|
-
|
|
599
|
+
options:
|
|
600
|
+
& Options<S, Root, Names, Invariants, Labels>
|
|
601
|
+
& { readonly schedules: Schedules }
|
|
602
|
+
& ValidateInvariants<Invariants, Services, Resources, Machines>
|
|
603
|
+
& ValidateLabels<Labels, Services, Resources, Machines>
|
|
604
|
+
): Session<S, Names, Schedules> => {
|
|
605
|
+
const inspect = runtime.inspect as (inspector: Inspector.Inspector.Any) => unknown
|
|
367
606
|
const debug = runtime.debug
|
|
368
607
|
const capacity = options.history ?? 600
|
|
369
608
|
const format = options.format ?? {}
|
|
@@ -385,8 +624,45 @@ export const make = <
|
|
|
385
624
|
}
|
|
386
625
|
return entry
|
|
387
626
|
}
|
|
388
|
-
const
|
|
389
|
-
|
|
627
|
+
const labelsInspector = options.labels as LabelsInspector | undefined
|
|
628
|
+
/** Each labelled entity's latest label; a despawned entity keeps its last one. */
|
|
629
|
+
const lastLabels = new Map<number, string>()
|
|
630
|
+
/** The labels of the last evaluation. */
|
|
631
|
+
let latestLabels: ReadonlyMap<number, string> = new Map()
|
|
632
|
+
/** Evaluates the labels for the frame that just ended and stamps it on its record. */
|
|
633
|
+
const evaluateLabels = (): void => {
|
|
634
|
+
if (labelsInspector === undefined) return
|
|
635
|
+
const labels = inspect(labelsInspector) as ReadonlyMap<number, string>
|
|
636
|
+
const dropped = [...latestLabels.keys()].filter((id) => !labels.has(id))
|
|
637
|
+
// An entity that lost its label while alive has none now; a despawned one keeps it.
|
|
638
|
+
if (dropped.length > 0) for (const alive of debug.dump({ entities: dropped }).entities) lastLabels.delete(alive.id)
|
|
639
|
+
for (const [id, label] of labels) lastLabels.set(id, label)
|
|
640
|
+
latestLabels = labels
|
|
641
|
+
current.labels = labels
|
|
642
|
+
}
|
|
643
|
+
/** Evaluates labels when frames ran outside `run` (queries print the latest world). */
|
|
644
|
+
const refreshLabels = (): void => {
|
|
645
|
+
if (labelsInspector === undefined || current.labels !== undefined) return
|
|
646
|
+
try {
|
|
647
|
+
evaluateLabels()
|
|
648
|
+
} catch {
|
|
649
|
+
// A throwing labels inspector stops `run` as `labels-threw`; queries print ids alone.
|
|
650
|
+
}
|
|
651
|
+
}
|
|
652
|
+
/** The labels for a line of `frame`: that frame's (or the next evaluated one's), then each entity's last. */
|
|
653
|
+
const labelsAt = (frame: number): Format.Labels | undefined => {
|
|
654
|
+
if (labelsInspector === undefined) return undefined
|
|
655
|
+
const own = history.find((entry) => entry.frame >= frame && entry.labels !== undefined)?.labels
|
|
656
|
+
return { get: (id) => own?.get(id) ?? lastLabels.get(id) }
|
|
657
|
+
}
|
|
658
|
+
const nowLabels = (): Format.Labels | undefined => {
|
|
659
|
+
refreshLabels()
|
|
660
|
+
return labelsAt(debug.frame())
|
|
661
|
+
}
|
|
662
|
+
|
|
663
|
+
type WarningMessage = string | ((labels: Format.Labels | undefined) => string)
|
|
664
|
+
const warnings = new Map<string, { code: Warning["code"]; message: WarningMessage; count: number; firstFrame: number; lastFrame: number }>()
|
|
665
|
+
const warn = (code: Warning["code"], key: string, message: WarningMessage, frame: number) => {
|
|
390
666
|
const existing = warnings.get(key)
|
|
391
667
|
if (existing) {
|
|
392
668
|
existing.count += 1
|
|
@@ -428,11 +704,34 @@ export const make = <
|
|
|
428
704
|
warn(
|
|
429
705
|
"non-finite-value",
|
|
430
706
|
`nonfinite:${system}:${subject}`,
|
|
431
|
-
`${system} wrote a NaN or infinite number to ${entity === undefined ? "" :
|
|
707
|
+
(labels) => `${system} wrote a NaN or infinite number to ${entity === undefined ? "" : `${Format.entity(entity, labels)} `}${subject}${path} (first at f${frame}; why() shows its history)`,
|
|
432
708
|
frame
|
|
433
709
|
)
|
|
434
710
|
}
|
|
435
711
|
|
|
712
|
+
/** The declared ranges of every component and resource field, by descriptor name, read from `describe()` on the first write. */
|
|
713
|
+
let ranges: ReturnType<typeof rangesOf> | undefined
|
|
714
|
+
const checkRange = (kind: "component" | "resource", system: string, subject: string, value: unknown, frame: number, entity?: number) => {
|
|
715
|
+
ranges ??= rangesOf(debug.describe())
|
|
716
|
+
const fields = ranges[kind].get(subject)
|
|
717
|
+
if (fields === undefined || typeof value !== "object" || value === null) return
|
|
718
|
+
for (const [field, min, max] of fields) {
|
|
719
|
+
const written = (value as Readonly<Record<string, unknown>>)[field]
|
|
720
|
+
// NaN and infinities are `non-finite-value` warnings.
|
|
721
|
+
if (typeof written !== "number" || !Number.isFinite(written) || (written >= min && written <= max)) continue
|
|
722
|
+
warn(
|
|
723
|
+
"out-of-range",
|
|
724
|
+
`range:${system}:${subject}.${field}`,
|
|
725
|
+
(labels) => `${entity === undefined ? "" : `${Format.entity(entity, labels)} `}${subject}.${field} written as ${Format.value(written)}, declared range [${Format.value(min)}, ${Format.value(max)}] by ${system} at frame ${frame}`,
|
|
726
|
+
frame
|
|
727
|
+
)
|
|
728
|
+
}
|
|
729
|
+
}
|
|
730
|
+
const checkComponent = (system: string, subject: string, value: unknown, frame: number, entity: number) => {
|
|
731
|
+
checkFinite(system, subject, value, frame, entity)
|
|
732
|
+
checkRange("component", system, subject, value, frame, entity)
|
|
733
|
+
}
|
|
734
|
+
|
|
436
735
|
const record = (event: Debug.TraceEvent) => {
|
|
437
736
|
if (event.type === "frame") {
|
|
438
737
|
checkPending(current.frame)
|
|
@@ -452,8 +751,11 @@ export const make = <
|
|
|
452
751
|
warn("system-failed", `failed:${event.system}`, `${event.system} ${event.outcome === "defect" ? "threw" : "failed"}: ${Format.value(event.error, format)}`, event.frame)
|
|
453
752
|
} else {
|
|
454
753
|
if (event.commands.length > 0) pending.set(event.system, (pending.get(event.system) ?? 0) + event.commands.length)
|
|
455
|
-
for (const write of event.writes)
|
|
456
|
-
for (const write of event.resources)
|
|
754
|
+
for (const write of event.writes) checkComponent(event.system, write.component, write.after, event.frame, write.entity)
|
|
755
|
+
for (const write of event.resources) {
|
|
756
|
+
checkFinite(event.system, write.resource, write.after, event.frame)
|
|
757
|
+
checkRange("resource", event.system, write.resource, write.after, event.frame)
|
|
758
|
+
}
|
|
457
759
|
for (const emit of event.events) checkFinite(event.system, emit.event, emit.values, event.frame)
|
|
458
760
|
for (const next of event.nextStates) {
|
|
459
761
|
if (next.value === undefined) pendingStates.delete(next.machine)
|
|
@@ -493,13 +795,13 @@ export const make = <
|
|
|
493
795
|
for (const effect of command.effects) {
|
|
494
796
|
switch (effect.kind) {
|
|
495
797
|
case "spawn":
|
|
496
|
-
for (const [component, value] of Object.entries(effect.components))
|
|
798
|
+
for (const [component, value] of Object.entries(effect.components)) checkComponent(command.system, component, value, event.frame, effect.entity)
|
|
497
799
|
break
|
|
498
800
|
case "insert":
|
|
499
|
-
|
|
801
|
+
checkComponent(command.system, effect.component, effect.value, event.frame, effect.entity)
|
|
500
802
|
break
|
|
501
803
|
case "overwrite":
|
|
502
|
-
|
|
804
|
+
checkComponent(command.system, effect.component, effect.after, event.frame, effect.entity)
|
|
503
805
|
break
|
|
504
806
|
}
|
|
505
807
|
}
|
|
@@ -531,12 +833,50 @@ export const make = <
|
|
|
531
833
|
return first === undefined ? undefined : [first.frame, history[history.length - 1]!.frame]
|
|
532
834
|
}
|
|
533
835
|
|
|
836
|
+
/** The first invariant violated (or throwing) now, in order. */
|
|
837
|
+
const checkInvariants = (frame: number): CheckStop | undefined => {
|
|
838
|
+
for (const invariant of options.invariants ?? []) {
|
|
839
|
+
let message: string | undefined
|
|
840
|
+
try {
|
|
841
|
+
message = inspect(invariant.inspector) as string | undefined
|
|
842
|
+
} catch (error) {
|
|
843
|
+
return { reason: "invariant-threw", frame, invariant: invariant.name, error }
|
|
844
|
+
}
|
|
845
|
+
if (message !== undefined) return { reason: "invariant", frame, invariant: invariant.name, message }
|
|
846
|
+
}
|
|
847
|
+
return undefined
|
|
848
|
+
}
|
|
849
|
+
|
|
850
|
+
/** What a run compares against: taken before its first frame begins. */
|
|
851
|
+
const startRun = () => {
|
|
852
|
+
takeIgnored()
|
|
853
|
+
return {
|
|
854
|
+
started: options.hostClock.now(),
|
|
855
|
+
warningsBefore: new Map([...warnings].map(([key, warning]) => [key, warning.count])),
|
|
856
|
+
initial: debug.population()
|
|
857
|
+
}
|
|
858
|
+
}
|
|
859
|
+
|
|
860
|
+
/** The frame `session.step` has open, if any. */
|
|
861
|
+
let stepping: { readonly name: string; readonly frame: number } | undefined
|
|
862
|
+
const refuseWhileStepping = (call: string): void => {
|
|
863
|
+
if (stepping !== undefined) throw new Error(`${call} was called while frame f${stepping.frame} of ${stepping.name} is being stepped: call finish() on it first`)
|
|
864
|
+
}
|
|
865
|
+
|
|
534
866
|
const run = (name: Names, runOptions: RunOptions = {}): Rendered.Rendered<RunResult> => {
|
|
867
|
+
refuseWhileStepping(`session.run(${name})`)
|
|
535
868
|
const schedule = schedules[name]!
|
|
869
|
+
return runFrames(name, runOptions, startRun(), () => runtime.tryTick(schedule))
|
|
870
|
+
}
|
|
871
|
+
|
|
872
|
+
/** Ticks `frames` frames with `tickFrame` and reports them; `run` and `finish()` share it. */
|
|
873
|
+
const runFrames = (
|
|
874
|
+
name: string,
|
|
875
|
+
runOptions: RunOptions,
|
|
876
|
+
{ started, warningsBefore, initial }: ReturnType<typeof startRun>,
|
|
877
|
+
tickFrame: () => Result.Result<void, unknown>
|
|
878
|
+
): Rendered.Rendered<RunResult> => {
|
|
536
879
|
const frames = runOptions.frames ?? 1
|
|
537
|
-
const started = options.hostClock.now()
|
|
538
|
-
const warningsBefore = new Map([...warnings].map(([key, warning]) => [key, warning.count]))
|
|
539
|
-
const initial = debug.population()
|
|
540
880
|
const entityCounts: Array<number> = []
|
|
541
881
|
const componentCounts = new Map<string, Array<number>>(Object.keys(initial.components).map((name) => [name, []]))
|
|
542
882
|
const sample = () => {
|
|
@@ -547,11 +887,10 @@ export const make = <
|
|
|
547
887
|
let first: number | undefined
|
|
548
888
|
let last: number | undefined
|
|
549
889
|
let stop: Stop = { reason: "completed" }
|
|
550
|
-
takeIgnored()
|
|
551
890
|
for (let index = 0; index < frames; index++) {
|
|
552
891
|
let result: Result.Result<void, unknown>
|
|
553
892
|
try {
|
|
554
|
-
result =
|
|
893
|
+
result = tickFrame()
|
|
555
894
|
} catch (defect) {
|
|
556
895
|
const frame = debug.frame()
|
|
557
896
|
first ??= frame
|
|
@@ -570,28 +909,16 @@ export const make = <
|
|
|
570
909
|
break
|
|
571
910
|
}
|
|
572
911
|
if (!result.ok) {
|
|
573
|
-
|
|
574
|
-
stop = error.kind === "MissingRuntimeRequirements"
|
|
575
|
-
? { reason: "missingRequirements", frame, requirements: error.requirements }
|
|
576
|
-
: error.kind === "TickOrderViolation"
|
|
577
|
-
? { reason: "tickOrder", frame, issues: (error.issues ?? []).map((issue) => issue.message) }
|
|
578
|
-
: { reason: "failure", frame, system: typeof error.system === "string" ? error.system : "(unknown)", error: error.error }
|
|
912
|
+
stop = failureStop(result.error, frame)
|
|
579
913
|
break
|
|
580
914
|
}
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
} catch (error) {
|
|
587
|
-
checked = { reason: "invariant-threw", frame, invariant: invariant.name, error }
|
|
588
|
-
break
|
|
589
|
-
}
|
|
590
|
-
if (message !== undefined) {
|
|
591
|
-
checked = { reason: "invariant", frame, invariant: invariant.name, message }
|
|
592
|
-
break
|
|
593
|
-
}
|
|
915
|
+
try {
|
|
916
|
+
evaluateLabels()
|
|
917
|
+
} catch (error) {
|
|
918
|
+
stop = { reason: "labels-threw", frame, error }
|
|
919
|
+
break
|
|
594
920
|
}
|
|
921
|
+
const checked = checkInvariants(frame)
|
|
595
922
|
if (checked) {
|
|
596
923
|
stop = checked
|
|
597
924
|
break
|
|
@@ -645,21 +972,163 @@ export const make = <
|
|
|
645
972
|
const warningText = raisedCodes.length === 0
|
|
646
973
|
? ""
|
|
647
974
|
: `\nwarnings during the run (see report()): ${raisedCodes.map(([code, count]) => `${code} x${count}`).join(", ")}`
|
|
648
|
-
return Rendered.make(data, renderRun(data, format) + lintText + warningText)
|
|
975
|
+
return Rendered.make(data, renderRun(data, format, labelsAt(debug.frame())) + lintText + warningText)
|
|
976
|
+
}
|
|
977
|
+
|
|
978
|
+
const step = (name: Names): SteppedFrame<AnySystem> => {
|
|
979
|
+
refuseWhileStepping(`session.step(${name})`)
|
|
980
|
+
const schedule = schedules[name]!
|
|
981
|
+
const start = startRun()
|
|
982
|
+
const begun = debug.beginFrame(schedule)
|
|
983
|
+
const frame = debug.frame()
|
|
984
|
+
const cursor = begun.ok ? begun.value : undefined
|
|
985
|
+
/** Why the frame never began (missing requirements, `thisTick` order). */
|
|
986
|
+
const notBegun = begun.ok ? undefined : failureStop(begun.error, frame) as StepStop
|
|
987
|
+
/** How the frame ended before `finish()`: a failed system's result, or a thrown defect. */
|
|
988
|
+
let ended: { readonly result: Result.Result<void, unknown> } | { readonly defect: unknown } | undefined
|
|
989
|
+
let finished: Rendered.Rendered<RunResult> | undefined
|
|
990
|
+
if (cursor !== undefined && cursor.remaining().length > 0) stepping = { name, frame }
|
|
991
|
+
|
|
992
|
+
const head = notBegun === undefined ? `step ${name} f${frame}` : `step ${name}`
|
|
993
|
+
const stopText = (stop: StepStop): string => {
|
|
994
|
+
switch (stop.reason) {
|
|
995
|
+
case "frameEnded":
|
|
996
|
+
return `${head}: the frame has ended; finish() reports it`
|
|
997
|
+
case "notAhead":
|
|
998
|
+
return `${head}: ${stop.system} is not ahead (it already ran this frame, or ${name} does not run it as a step); nothing ran. Remaining: ${stop.remaining.length === 0 ? "(none)" : stop.remaining.map(Format.step).join(", ")}`
|
|
999
|
+
case "failure":
|
|
1000
|
+
return `${head}: ${stop.system} FAILED: ${Format.value(stop.error, format)}; the frame ended, finish() reports it`
|
|
1001
|
+
case "defect":
|
|
1002
|
+
return `${head}: DEFECT: ${stop.error instanceof Error ? stop.error.stack ?? stop.error.message : Format.value(stop.error, format)}`
|
|
1003
|
+
case "missingRequirements":
|
|
1004
|
+
return `${head}: NOT BEGUN: missing runtime requirements ${Format.value(stop.requirements, format)}`
|
|
1005
|
+
case "tickOrder":
|
|
1006
|
+
return `${head}: NOT BEGUN: ${stop.issues.join("; ")}`
|
|
1007
|
+
}
|
|
1008
|
+
}
|
|
1009
|
+
const remainingSteps = (): ReadonlyArray<Debug.StepDescription> =>
|
|
1010
|
+
cursor === undefined || ended !== undefined ? [] : cursor.remaining()
|
|
1011
|
+
const nextText = (): string => {
|
|
1012
|
+
const left = remainingSteps()
|
|
1013
|
+
return left.length === 0 ? "the frame ended, finish() reports it" : `next: ${Format.step(left[0]!)}`
|
|
1014
|
+
}
|
|
1015
|
+
const unavailable = (): StepStop | undefined =>
|
|
1016
|
+
notBegun ?? (remainingSteps().length === 0 ? { reason: "frameEnded", frame } : undefined)
|
|
1017
|
+
|
|
1018
|
+
/** Runs one step; a failure or defect ends the frame. */
|
|
1019
|
+
const advance = (): Result.Result<Debug.StepOutcome, StepStop> => {
|
|
1020
|
+
const stop = unavailable()
|
|
1021
|
+
if (stop !== undefined) return Result.failure(stop)
|
|
1022
|
+
let result: Result.Result<Debug.StepOutcome, unknown>
|
|
1023
|
+
try {
|
|
1024
|
+
result = cursor!.next()
|
|
1025
|
+
} catch (defect) {
|
|
1026
|
+
ended = { defect }
|
|
1027
|
+
stepping = undefined
|
|
1028
|
+
return Result.failure({ reason: "defect", frame, error: defect })
|
|
1029
|
+
} finally {
|
|
1030
|
+
// Labels evaluated mid-frame are evaluated again for the world after this step.
|
|
1031
|
+
if (current.frame === frame) delete current.labels
|
|
1032
|
+
}
|
|
1033
|
+
if (!result.ok) {
|
|
1034
|
+
ended = { result: Result.failure(result.error) }
|
|
1035
|
+
stepping = undefined
|
|
1036
|
+
return Result.failure(failureStop(result.error, frame) as StepStop)
|
|
1037
|
+
}
|
|
1038
|
+
if (result.value.ended) stepping = undefined
|
|
1039
|
+
return Result.success(result.value)
|
|
1040
|
+
}
|
|
1041
|
+
|
|
1042
|
+
const stepped: SteppedFrame<AnySystem> = {
|
|
1043
|
+
until: (system) => {
|
|
1044
|
+
const unavailableStop = unavailable()
|
|
1045
|
+
const left = remainingSteps()
|
|
1046
|
+
const offset = schedule.steps
|
|
1047
|
+
.slice(schedule.steps.length - left.length)
|
|
1048
|
+
.findIndex((entry) => "ordering" in entry && entry.ordering.key === system.ordering.key)
|
|
1049
|
+
const stop: StepStop | undefined = unavailableStop
|
|
1050
|
+
?? (offset === -1 ? { reason: "notAhead", frame, system: system.name, remaining: left } : undefined)
|
|
1051
|
+
if (stop !== undefined) return Rendered.make(Result.failure(stop), stopText(stop))
|
|
1052
|
+
const ran: Array<Debug.StepDescription> = []
|
|
1053
|
+
for (let index = 0; index < offset; index++) {
|
|
1054
|
+
const result = advance()
|
|
1055
|
+
if (!result.ok) return Rendered.make(Result.failure(result.error), stopText(result.error))
|
|
1056
|
+
ran.push(result.value.step)
|
|
1057
|
+
}
|
|
1058
|
+
const reached: StepReached = { frame, system: system.name, ran }
|
|
1059
|
+
return Rendered.make(
|
|
1060
|
+
Result.success(reached),
|
|
1061
|
+
`${head}: stopped before ${system.name}; ${ran.length === 0 ? "nothing ran" : `ran ${ran.map(Format.step).join(", ")}`}`
|
|
1062
|
+
)
|
|
1063
|
+
},
|
|
1064
|
+
next: () => {
|
|
1065
|
+
const result = advance()
|
|
1066
|
+
if (!result.ok) return Rendered.make(Result.failure(result.error), stopText(result.error))
|
|
1067
|
+
const ran: StepRan = { frame, step: result.value.step, ended: result.value.ended }
|
|
1068
|
+
return Rendered.make(Result.success(ran), `${head}: ran ${Format.step(ran.step)}; ${nextText()}`)
|
|
1069
|
+
},
|
|
1070
|
+
remaining: () => {
|
|
1071
|
+
const left = remainingSteps()
|
|
1072
|
+
return Rendered.make(left, left.length === 0
|
|
1073
|
+
? `${head}: no steps left; ${finished === undefined ? "finish() reports the frame" : "finished"}`
|
|
1074
|
+
: `${head}: ${left.length} steps left: ${left.map(Format.step).join(", ")}`)
|
|
1075
|
+
},
|
|
1076
|
+
check: () => {
|
|
1077
|
+
const at = remainingSteps()
|
|
1078
|
+
const where = at.length === 0 ? "at the end of the frame" : `before ${Format.step(at[0]!)}`
|
|
1079
|
+
const stop = checkInvariants(frame)
|
|
1080
|
+
if (stop === undefined) return Rendered.make(Result.success(undefined), `${head}: invariants hold ${where}`)
|
|
1081
|
+
const text = stop.reason === "invariant"
|
|
1082
|
+
? `${head}: INVARIANT "${stop.invariant}" violated ${where}: ${stop.message.replace(entityToken, (_token, id: string) => Format.entity(Number(id), nowLabels()))} (it may hold again by the end of the frame)`
|
|
1083
|
+
: `${head}: INVARIANT "${stop.invariant}" threw ${where}: ${stop.error instanceof Error ? stop.error.stack ?? stop.error.message : Format.value(stop.error, format)}`
|
|
1084
|
+
return Rendered.make(Result.failure(stop), text)
|
|
1085
|
+
},
|
|
1086
|
+
finish: () => {
|
|
1087
|
+
finished ??= runFrames(name, {}, start, () => {
|
|
1088
|
+
if (!begun.ok) return begun
|
|
1089
|
+
if (ended !== undefined) {
|
|
1090
|
+
if ("defect" in ended) throw ended.defect
|
|
1091
|
+
return ended.result
|
|
1092
|
+
}
|
|
1093
|
+
try {
|
|
1094
|
+
while (cursor!.remaining().length > 0) {
|
|
1095
|
+
const result = cursor!.next()
|
|
1096
|
+
if (!result.ok) return result
|
|
1097
|
+
}
|
|
1098
|
+
return Result.success(undefined)
|
|
1099
|
+
} finally {
|
|
1100
|
+
stepping = undefined
|
|
1101
|
+
}
|
|
1102
|
+
})
|
|
1103
|
+
return finished
|
|
1104
|
+
}
|
|
1105
|
+
}
|
|
1106
|
+
return stepped
|
|
649
1107
|
}
|
|
650
1108
|
|
|
651
1109
|
/** Lines hidden by the last `collectLines` call because they record no change. */
|
|
652
1110
|
let hidden = 0
|
|
653
1111
|
|
|
654
|
-
const collectLines = (filter: JournalFilter<S>): Array<Format.Line> =>
|
|
1112
|
+
const collectLines = (filter: JournalFilter<S>): Array<Format.Line> => collectSourced(filter).map((entry) => entry.line)
|
|
1113
|
+
|
|
1114
|
+
/** The journal lines of `filter`, each with its event's position in {@link flatTrace}. */
|
|
1115
|
+
const collectSourced = (filter: JournalFilter<S>): Array<{ readonly line: Format.Line; readonly at: number }> => {
|
|
655
1116
|
hidden = 0
|
|
1117
|
+
refreshLabels()
|
|
656
1118
|
const subject = filter.component?.name ?? filter.resource?.name ?? filter.event?.name ?? filter.machine?.name
|
|
657
|
-
|
|
658
|
-
const
|
|
659
|
-
|
|
660
|
-
|
|
1119
|
+
// `slice(-last)` keeps the journal's meaning of `last` (0 keeps everything).
|
|
1120
|
+
const first = filter.last === undefined ? 0 : history.length - history.slice(-filter.last).length
|
|
1121
|
+
const result: Array<{ readonly line: Format.Line; readonly at: number }> = []
|
|
1122
|
+
let at = 0
|
|
1123
|
+
for (const [index, entry] of history.entries()) {
|
|
1124
|
+
if (index < first || !inRange(entry.frame, filter.frames)) {
|
|
1125
|
+
at += entry.events.length
|
|
1126
|
+
continue
|
|
1127
|
+
}
|
|
1128
|
+
const labels = labelsAt(entry.frame)
|
|
661
1129
|
for (const event of entry.events) {
|
|
662
|
-
|
|
1130
|
+
const position = at++
|
|
1131
|
+
for (const line of Format.lines(event, format, labels)) {
|
|
663
1132
|
if (filter.entity !== undefined && line.entity !== filter.entity) continue
|
|
664
1133
|
if (subject !== undefined && line.subject !== subject && !(line.kind === "effect" && line.subject === undefined && filter.entity !== undefined)) continue
|
|
665
1134
|
if (filter.system !== undefined && line.system !== filter.system) continue
|
|
@@ -669,7 +1138,7 @@ export const make = <
|
|
|
669
1138
|
hidden += 1
|
|
670
1139
|
continue
|
|
671
1140
|
}
|
|
672
|
-
result.push(line)
|
|
1141
|
+
result.push({ line, at: position })
|
|
673
1142
|
}
|
|
674
1143
|
}
|
|
675
1144
|
}
|
|
@@ -690,21 +1159,23 @@ export const make = <
|
|
|
690
1159
|
return Rendered.make(lines, renderLines(`journal: ${lines.length} lines (${rangeText()}${hiddenText})`, lines))
|
|
691
1160
|
}
|
|
692
1161
|
|
|
693
|
-
const why = (entity: number, component: Schema.ComponentDescriptor<S>, whyOptions:
|
|
694
|
-
const
|
|
1162
|
+
const why = (entity: number, component: Schema.ComponentDescriptor<S>, whyOptions: WhyOptions = {}) => {
|
|
1163
|
+
const sourced = collectSourced({ entity, component, kinds: ["write", "effect"], limit: whyOptions.limit ?? 5 })
|
|
1164
|
+
const lines = followReads(sourced, whyOptions)
|
|
695
1165
|
const currentValue = debug.dump({ entities: [entity] }).entities[0]
|
|
1166
|
+
const name = Format.entity(entity, nowLabels())
|
|
696
1167
|
const now = currentValue === undefined
|
|
697
|
-
?
|
|
1168
|
+
? `${name} is not alive`
|
|
698
1169
|
: component.name in currentValue.components
|
|
699
|
-
?
|
|
700
|
-
:
|
|
701
|
-
const changes =
|
|
1170
|
+
? `${name} ${component.name} is now ${Format.value(currentValue.components[component.name], format)}`
|
|
1171
|
+
: `${name} has no ${component.name} now`
|
|
1172
|
+
const changes = sourced.length === 0
|
|
702
1173
|
? `${now}; no change to it in ${rangeText()}`
|
|
703
|
-
: `${now}; last ${
|
|
1174
|
+
: `${now}; last ${sourced.length} changes (oldest first):`
|
|
704
1175
|
const spawners = spawnersOf(currentValue === undefined ? [component.name] : Object.keys(currentValue.components), component.name)
|
|
705
1176
|
const header = `${changes}\n${spawners.length === 0
|
|
706
1177
|
? `no described system declares spawns of ${component.name}`
|
|
707
|
-
: `could have spawned it: ${spawners.join(", ")}`}`
|
|
1178
|
+
: `could have spawned it: ${spawners.join(", ")}`}${readsNote(lines)}`
|
|
708
1179
|
return Rendered.make(lines, renderLines(header, lines))
|
|
709
1180
|
}
|
|
710
1181
|
|
|
@@ -722,18 +1193,275 @@ export const make = <
|
|
|
722
1193
|
.map((system) => system.name)
|
|
723
1194
|
}
|
|
724
1195
|
|
|
725
|
-
const whyResource = (resource: Schema.ResourceDescriptor<S>, whyOptions:
|
|
726
|
-
const lines =
|
|
1196
|
+
const whyResource = (resource: Schema.ResourceDescriptor<S>, whyOptions: WhyOptions = {}) => {
|
|
1197
|
+
const lines = followReads(collectSourced({ resource, kinds: ["resource"], limit: whyOptions.limit ?? 5 }), whyOptions)
|
|
727
1198
|
const resources = debug.dump({ limit: 0 }).resources
|
|
728
1199
|
const now = resource.name in resources
|
|
729
1200
|
? `${resource.name} is now ${Format.value(resources[resource.name], format)}`
|
|
730
1201
|
: `${resource.name} has no value now`
|
|
731
|
-
const
|
|
1202
|
+
const changes = lines.filter((line) => line.depth === 0).length
|
|
1203
|
+
const header = changes === 0
|
|
732
1204
|
? `${now}; no change to it in ${rangeText()}`
|
|
733
|
-
: `${now}; last ${
|
|
1205
|
+
: `${now}; last ${changes} changes (oldest first):${readsNote(lines)}`
|
|
734
1206
|
return Rendered.make(lines, renderLines(header, lines))
|
|
735
1207
|
}
|
|
736
1208
|
|
|
1209
|
+
/** The header note `why` adds when it printed declared reads. */
|
|
1210
|
+
const readsNote = (lines: ReadonlyArray<Format.Line>): string =>
|
|
1211
|
+
lines.some((line) => line.depth > 0)
|
|
1212
|
+
? "\nindented: what each writing system declared it reads, and the latest fact that could have produced it (declared: possible causes, not observed reads)"
|
|
1213
|
+
: ""
|
|
1214
|
+
|
|
1215
|
+
/** Every kept trace event, oldest first; {@link collectSourced} positions index into it. */
|
|
1216
|
+
const flatTrace = (): ReadonlyArray<Debug.TraceEvent> => history.flatMap((entry) => entry.events)
|
|
1217
|
+
|
|
1218
|
+
/**
|
|
1219
|
+
* The changes `why` lists, each followed (with `depth` above 1) by the
|
|
1220
|
+
* reads its system declared, depth first. Positions are in trace order, so
|
|
1221
|
+
* "before the run" is what the system could have seen.
|
|
1222
|
+
*/
|
|
1223
|
+
const followReads = (sourced: ReadonlyArray<{ readonly line: Format.Line; readonly at: number }>, whyOptions: WhyOptions): Array<Format.Line> => {
|
|
1224
|
+
const depth = whyOptions.depth ?? 1
|
|
1225
|
+
const limit = whyOptions.limit ?? 5
|
|
1226
|
+
if (depth <= 1 || sourced.length === 0) return sourced.map((entry) => entry.line)
|
|
1227
|
+
const trace = flatTrace()
|
|
1228
|
+
const systems = new Map(debug.describe().systems.map((entry) => [entry.name, entry] as const))
|
|
1229
|
+
let world: ReadonlyArray<Debug.EntityDump> | undefined
|
|
1230
|
+
const worldNow = () => (world ??= debug.dump().entities)
|
|
1231
|
+
|
|
1232
|
+
/** The latest committed run of `system` before `before`. */
|
|
1233
|
+
const runBefore = (system: string, before: number): { readonly at: number; readonly run: Debug.SystemEvent } | undefined => {
|
|
1234
|
+
for (let at = before - 1; at >= 0; at--) {
|
|
1235
|
+
const event = trace[at]!
|
|
1236
|
+
if (event.type === "system" && event.system === system && event.outcome === "ok") return { at, run: event }
|
|
1237
|
+
}
|
|
1238
|
+
return undefined
|
|
1239
|
+
}
|
|
1240
|
+
/** Where the stream reads of the run at `at` start: after the system's previous run, or the discarding skip. */
|
|
1241
|
+
const readsSince = (system: string, at: number): number => {
|
|
1242
|
+
for (let index = at - 1; index >= 0; index--) {
|
|
1243
|
+
const event = trace[index]!
|
|
1244
|
+
if ((event.type === "system" && event.system === system) || (event.type === "system.skipped" && event.system === system && !event.held)) return index + 1
|
|
1245
|
+
}
|
|
1246
|
+
return 0
|
|
1247
|
+
}
|
|
1248
|
+
const latest = <A>(before: number, find: (event: Debug.TraceEvent, at: number) => A | undefined): A | undefined => {
|
|
1249
|
+
for (let at = before - 1; at >= 0; at--) {
|
|
1250
|
+
const found = find(trace[at]!, at)
|
|
1251
|
+
if (found !== undefined) return found
|
|
1252
|
+
}
|
|
1253
|
+
return undefined
|
|
1254
|
+
}
|
|
1255
|
+
|
|
1256
|
+
/** A run whose reads can be followed: the entity and component (or resource) it wrote, which its own reads skip. */
|
|
1257
|
+
interface Cause {
|
|
1258
|
+
readonly at: number
|
|
1259
|
+
readonly run: Debug.SystemEvent
|
|
1260
|
+
readonly entity: number | undefined
|
|
1261
|
+
readonly subject: string | undefined
|
|
1262
|
+
}
|
|
1263
|
+
interface Read {
|
|
1264
|
+
readonly frame: number
|
|
1265
|
+
readonly schedule: string
|
|
1266
|
+
readonly system: string | undefined
|
|
1267
|
+
readonly entity: number | undefined
|
|
1268
|
+
readonly subject: string
|
|
1269
|
+
readonly text: string
|
|
1270
|
+
readonly next: Cause | undefined
|
|
1271
|
+
}
|
|
1272
|
+
|
|
1273
|
+
const readsOf = (cause: Cause): Array<Read> => {
|
|
1274
|
+
const { run } = cause
|
|
1275
|
+
const description = systems.get(run.system)
|
|
1276
|
+
const here = { frame: run.frame, schedule: run.schedule, system: undefined, entity: undefined, next: undefined }
|
|
1277
|
+
if (description === undefined) {
|
|
1278
|
+
return [{ ...here, subject: run.system, text: `${run.system} is in no named or described schedule: its declared reads are unknown` }]
|
|
1279
|
+
}
|
|
1280
|
+
const reads: Array<Read> = []
|
|
1281
|
+
const since = readsSince(run.system, cause.at)
|
|
1282
|
+
for (const name of description.events.reads) {
|
|
1283
|
+
const before = reads.length
|
|
1284
|
+
for (let at = since; at < cause.at; at++) {
|
|
1285
|
+
const event = trace[at]!
|
|
1286
|
+
if (event.type === "runtime.sent" && event.event === name) {
|
|
1287
|
+
reads.push({ ...here, frame: event.frame, schedule: "", subject: name, text: `read ${name} ${Format.value([event.value], format)} (declared), sent by runtime.send at f${event.frame}` })
|
|
1288
|
+
}
|
|
1289
|
+
if (event.type === "system" && event.outcome === "ok") {
|
|
1290
|
+
for (const emitted of event.events) {
|
|
1291
|
+
if (emitted.event !== name) continue
|
|
1292
|
+
reads.push({
|
|
1293
|
+
frame: event.frame,
|
|
1294
|
+
schedule: event.schedule,
|
|
1295
|
+
system: event.system,
|
|
1296
|
+
entity: undefined,
|
|
1297
|
+
subject: name,
|
|
1298
|
+
text: `read ${name} ${Format.value(emitted.values, format)} (declared), emitted by ${event.system} at f${event.frame}`,
|
|
1299
|
+
next: { at, run: event, entity: undefined, subject: undefined }
|
|
1300
|
+
})
|
|
1301
|
+
}
|
|
1302
|
+
}
|
|
1303
|
+
}
|
|
1304
|
+
if (reads.length === before) {
|
|
1305
|
+
reads.push({ ...here, subject: name, text: `read ${name} (declared): nothing published to it since ${run.system}'s previous run` })
|
|
1306
|
+
}
|
|
1307
|
+
}
|
|
1308
|
+
for (const query of description.queries) {
|
|
1309
|
+
const components = [...query.reads, ...query.writes, ...query.optional]
|
|
1310
|
+
if (cause.entity !== undefined && cause.subject !== undefined && query.writes.includes(cause.subject)) {
|
|
1311
|
+
const entity = cause.entity
|
|
1312
|
+
for (const name of components.filter((component) => component !== cause.subject)) {
|
|
1313
|
+
reads.push(componentRead(cause, entity, name))
|
|
1314
|
+
}
|
|
1315
|
+
} else if (components.length > 0) {
|
|
1316
|
+
const required = [...query.reads, ...query.writes, ...query.with]
|
|
1317
|
+
const count = worldNow().filter((dumped) =>
|
|
1318
|
+
required.every((name) => name in dumped.components) && !query.without.some((name) => name in dumped.components)).length
|
|
1319
|
+
reads.push({
|
|
1320
|
+
...here,
|
|
1321
|
+
subject: components[0]!,
|
|
1322
|
+
text: `read ${components.join(", ")} of ${count} matching ${count === 1 ? "entity" : "entities"} now (declared; the trace does not say which it read)`
|
|
1323
|
+
})
|
|
1324
|
+
}
|
|
1325
|
+
}
|
|
1326
|
+
for (const name of new Set([...description.resources.reads, ...description.resources.writes])) {
|
|
1327
|
+
if (name === cause.subject && cause.entity === undefined) continue
|
|
1328
|
+
const found = latest(cause.at, (event, at) => {
|
|
1329
|
+
if (event.type !== "system" || event.outcome !== "ok") return undefined
|
|
1330
|
+
// An equal-value write did not produce the value; the change before it did.
|
|
1331
|
+
const write = event.resources.find((entry) => entry.resource === name && !Format.sameValue(entry.before, entry.after))
|
|
1332
|
+
return write === undefined ? undefined : { at, event, write }
|
|
1333
|
+
})
|
|
1334
|
+
reads.push(found === undefined
|
|
1335
|
+
? { ...here, subject: name, text: `read resource ${name} (declared): no change to it in ${rangeText()}` }
|
|
1336
|
+
: {
|
|
1337
|
+
frame: found.event.frame,
|
|
1338
|
+
schedule: found.event.schedule,
|
|
1339
|
+
system: found.event.system,
|
|
1340
|
+
entity: undefined,
|
|
1341
|
+
subject: name,
|
|
1342
|
+
text: `read resource ${name} ${Format.value(found.write.after, format)} (declared), written by ${found.event.system} at f${found.event.frame}`,
|
|
1343
|
+
next: { at: found.at, run: found.event, entity: undefined, subject: name }
|
|
1344
|
+
})
|
|
1345
|
+
}
|
|
1346
|
+
for (const name of new Set([...description.machines.reads, ...description.machines.updates])) {
|
|
1347
|
+
const found = latest(cause.at, (event, at): Read | undefined => {
|
|
1348
|
+
if (event.type === "transition" && event.machine === name && (event.outcome === "applied" || event.outcome === "enterFailed")) {
|
|
1349
|
+
return { ...here, frame: event.frame, schedule: event.schedule, subject: name, text: `read machine ${name} (declared): transition ${Format.transition(event)} ${event.outcome} at f${event.frame}` }
|
|
1350
|
+
}
|
|
1351
|
+
if (event.type !== "system" || event.outcome !== "ok" || event.system === run.system) return undefined
|
|
1352
|
+
const write = event.machines.find((entry) => entry.machine === name)
|
|
1353
|
+
return write === undefined ? undefined : {
|
|
1354
|
+
frame: event.frame,
|
|
1355
|
+
schedule: event.schedule,
|
|
1356
|
+
system: event.system,
|
|
1357
|
+
entity: undefined,
|
|
1358
|
+
subject: name,
|
|
1359
|
+
text: `read machine ${name} ${Format.change(write.before, write.after, format)} (declared), updated by ${event.system} at f${event.frame}`,
|
|
1360
|
+
next: { at, run: event, entity: undefined, subject: undefined }
|
|
1361
|
+
}
|
|
1362
|
+
})
|
|
1363
|
+
reads.push(found ?? { ...here, subject: name, text: `read machine ${name} (declared): no transition in ${rangeText()}` })
|
|
1364
|
+
}
|
|
1365
|
+
if (reads.length === 0) reads.push({ ...here, subject: run.system, text: `${run.system} declares no other reads (declared)` })
|
|
1366
|
+
return reads
|
|
1367
|
+
}
|
|
1368
|
+
|
|
1369
|
+
/** The latest value of `component` on `entity` before the cause's run, and what produced it. */
|
|
1370
|
+
const componentRead = (cause: Cause, entity: number, component: string): Read => {
|
|
1371
|
+
const name = Format.entity(entity, labelsAt(cause.run.frame))
|
|
1372
|
+
const found = latest(cause.at, (event, at): Read | undefined => {
|
|
1373
|
+
if (event.type === "system" && event.outcome === "ok") {
|
|
1374
|
+
const write = event.writes.find((entry) => entry.entity === entity && entry.component === component && !Format.sameValue(entry.before, entry.after))
|
|
1375
|
+
return write === undefined ? undefined : {
|
|
1376
|
+
frame: event.frame,
|
|
1377
|
+
schedule: event.schedule,
|
|
1378
|
+
system: event.system,
|
|
1379
|
+
entity,
|
|
1380
|
+
subject: component,
|
|
1381
|
+
text: `read ${name} ${component} ${Format.value(write.after, format)} (declared), written by ${event.system} at f${event.frame}`,
|
|
1382
|
+
next: { at, run: event, entity, subject: component }
|
|
1383
|
+
}
|
|
1384
|
+
}
|
|
1385
|
+
if (event.type !== "deferred") return undefined
|
|
1386
|
+
for (const command of [...event.commands].reverse()) {
|
|
1387
|
+
for (const effect of [...command.effects].reverse()) {
|
|
1388
|
+
if (effect.entity !== entity) continue
|
|
1389
|
+
const value = effect.kind === "spawn" ? (component in effect.components ? { found: effect.components[component] } : undefined)
|
|
1390
|
+
: effect.kind === "insert" && effect.component === component ? { found: effect.value }
|
|
1391
|
+
: effect.kind === "overwrite" && effect.component === component ? { found: effect.after }
|
|
1392
|
+
: undefined
|
|
1393
|
+
if (value === undefined) continue
|
|
1394
|
+
const queued = runBefore(command.system, at)
|
|
1395
|
+
return {
|
|
1396
|
+
frame: event.frame,
|
|
1397
|
+
schedule: event.schedule,
|
|
1398
|
+
system: command.system,
|
|
1399
|
+
entity,
|
|
1400
|
+
subject: component,
|
|
1401
|
+
text: `read ${name} ${component} ${Format.value(value.found, format)} (declared), ${effect.kind === "spawn" ? "spawned" : "inserted"} by ${command.system} at f${event.frame}`,
|
|
1402
|
+
next: queued === undefined ? undefined : { ...queued, entity: undefined, subject: undefined }
|
|
1403
|
+
}
|
|
1404
|
+
}
|
|
1405
|
+
}
|
|
1406
|
+
return undefined
|
|
1407
|
+
})
|
|
1408
|
+
return found ?? { frame: cause.run.frame, schedule: cause.run.schedule, system: undefined, entity, subject: component, text: `read ${name} ${component} (declared): no change to it in ${rangeText()}`, next: undefined }
|
|
1409
|
+
}
|
|
1410
|
+
|
|
1411
|
+
const toLine = (read: Read, level: number, suffix: string): Format.Line => {
|
|
1412
|
+
const label = read.entity === undefined ? undefined : labelsAt(read.frame)?.get(read.entity)
|
|
1413
|
+
return {
|
|
1414
|
+
kind: "read",
|
|
1415
|
+
frame: read.frame,
|
|
1416
|
+
schedule: read.schedule,
|
|
1417
|
+
system: read.system,
|
|
1418
|
+
entity: read.entity,
|
|
1419
|
+
label: label === "" ? undefined : label,
|
|
1420
|
+
subject: read.subject,
|
|
1421
|
+
text: `${read.text}${suffix}`,
|
|
1422
|
+
noop: false,
|
|
1423
|
+
depth: level
|
|
1424
|
+
}
|
|
1425
|
+
}
|
|
1426
|
+
|
|
1427
|
+
const out: Array<Format.Line> = []
|
|
1428
|
+
const follow = (cause: Cause, level: number, chain: ReadonlySet<string>) => {
|
|
1429
|
+
const reads = readsOf(cause)
|
|
1430
|
+
for (const read of reads.slice(0, limit)) {
|
|
1431
|
+
const cycle = read.next !== undefined && chain.has(read.next.run.system)
|
|
1432
|
+
out.push(toLine(read, level, cycle ? " (cycle: not followed)" : ""))
|
|
1433
|
+
if (read.next !== undefined && !cycle && level + 1 < depth) follow(read.next, level + 1, new Set([...chain, read.next.run.system]))
|
|
1434
|
+
}
|
|
1435
|
+
if (reads.length > limit) {
|
|
1436
|
+
out.push({
|
|
1437
|
+
kind: "read",
|
|
1438
|
+
frame: cause.run.frame,
|
|
1439
|
+
schedule: cause.run.schedule,
|
|
1440
|
+
system: undefined,
|
|
1441
|
+
entity: undefined,
|
|
1442
|
+
label: undefined,
|
|
1443
|
+
subject: undefined,
|
|
1444
|
+
text: `…+${reads.length - limit} more declared reads of ${cause.run.system} (raise limit to see them)`,
|
|
1445
|
+
noop: false,
|
|
1446
|
+
depth: level
|
|
1447
|
+
})
|
|
1448
|
+
}
|
|
1449
|
+
}
|
|
1450
|
+
/** The run behind a listed change: the writing run, or for an applied command the run that queued it. */
|
|
1451
|
+
const causeOf = (line: Format.Line, at: number): Cause | undefined => {
|
|
1452
|
+
const event = trace[at]
|
|
1453
|
+
if (event?.type === "system") return { at, run: event, entity: line.entity, subject: line.subject }
|
|
1454
|
+
const queued = event?.type === "deferred" && line.system !== undefined ? runBefore(line.system, at) : undefined
|
|
1455
|
+
return queued === undefined ? undefined : { ...queued, entity: undefined, subject: undefined }
|
|
1456
|
+
}
|
|
1457
|
+
for (const { line, at } of sourced) {
|
|
1458
|
+
out.push(line)
|
|
1459
|
+
const cause = causeOf(line, at)
|
|
1460
|
+
if (cause !== undefined) follow(cause, 1, new Set([cause.run.system]))
|
|
1461
|
+
}
|
|
1462
|
+
return out
|
|
1463
|
+
}
|
|
1464
|
+
|
|
737
1465
|
const statsFor = (system: string): SystemStats | undefined => {
|
|
738
1466
|
const entry = stats.get(system)
|
|
739
1467
|
return entry === undefined ? undefined : { system, ...entry }
|
|
@@ -766,7 +1494,10 @@ export const make = <
|
|
|
766
1494
|
frames: debug.frame(),
|
|
767
1495
|
history: historyRange(),
|
|
768
1496
|
systems,
|
|
769
|
-
warnings: [...warnings.values()].map((warning) => ({
|
|
1497
|
+
warnings: [...warnings.values()].map((warning) => ({
|
|
1498
|
+
...warning,
|
|
1499
|
+
message: typeof warning.message === "string" ? warning.message : warning.message(labelsAt(warning.firstFrame))
|
|
1500
|
+
})),
|
|
770
1501
|
streams: debug.streams().filter((stream) => stream.heldBy !== undefined || stream.readers.some((reader) => reader.lagged)),
|
|
771
1502
|
lints: debug.describe().lints,
|
|
772
1503
|
population: debug.population()
|
|
@@ -790,6 +1521,7 @@ export const make = <
|
|
|
790
1521
|
|
|
791
1522
|
return {
|
|
792
1523
|
run,
|
|
1524
|
+
step: step as Session<S, Names, Schedules>["step"],
|
|
793
1525
|
journal,
|
|
794
1526
|
why,
|
|
795
1527
|
whyResource,
|
|
@@ -800,7 +1532,7 @@ export const make = <
|
|
|
800
1532
|
},
|
|
801
1533
|
dump: (filter) => {
|
|
802
1534
|
const dumped = debug.dump(filter)
|
|
803
|
-
return Rendered.make(dumped, Format.dump(dumped, format))
|
|
1535
|
+
return Rendered.make(dumped, Format.dump(dumped, format, nowLabels()))
|
|
804
1536
|
},
|
|
805
1537
|
streams: () => {
|
|
806
1538
|
const status = debug.streams()
|
|
@@ -815,7 +1547,7 @@ export const make = <
|
|
|
815
1547
|
}
|
|
816
1548
|
}
|
|
817
1549
|
|
|
818
|
-
const renderRun = (result: RunResult, format: Format.ValueOptions): string => {
|
|
1550
|
+
const renderRun = (result: RunResult, format: Format.ValueOptions, labels: Format.Labels | undefined): string => {
|
|
819
1551
|
const frames = result.range === undefined ? "no frames" : `f${result.range[0]}-f${result.range[1]}`
|
|
820
1552
|
const head = `run ${result.schedule}: ${result.frames} frames (${frames}) in ${Format.value(result.ms)}ms`
|
|
821
1553
|
const stop = result.stop
|
|
@@ -831,9 +1563,11 @@ const renderRun = (result: RunResult, format: Format.ValueOptions): string => {
|
|
|
831
1563
|
case "defect":
|
|
832
1564
|
return `${head}, DEFECT at f${stop.frame}: ${stop.error instanceof Error ? stop.error.stack ?? stop.error.message : Format.value(stop.error, format)}`
|
|
833
1565
|
case "invariant":
|
|
834
|
-
return `${head}, INVARIANT "${stop.invariant}" violated at f${stop.frame}: ${stop.message}`
|
|
1566
|
+
return `${head}, INVARIANT "${stop.invariant}" violated at f${stop.frame}: ${stop.message.replace(entityToken, (_token, id: string) => Format.entity(Number(id), labels))}`
|
|
835
1567
|
case "invariant-threw":
|
|
836
1568
|
return `${head}, INVARIANT "${stop.invariant}" threw at f${stop.frame}: ${stop.error instanceof Error ? stop.error.stack ?? stop.error.message : Format.value(stop.error, format)}`
|
|
1569
|
+
case "labels-threw":
|
|
1570
|
+
return `${head}, LABELS threw at f${stop.frame}: ${stop.error instanceof Error ? stop.error.stack ?? stop.error.message : Format.value(stop.error, format)}`
|
|
837
1571
|
case "tickOrder":
|
|
838
1572
|
return `${head}, NOT RUN after f${stop.frame}: ${stop.issues.join("; ")}`
|
|
839
1573
|
case "ignored-failure":
|