@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
package/src/Verify.ts ADDED
@@ -0,0 +1,276 @@
1
+ /**
2
+ * Determinism checked across engines: one replay, played in this process and
3
+ * in other JavaScript engines (real browsers), must reach the same world
4
+ * after every tick. `Ops` promises the same bits on every engine and a
5
+ * replay recorded in one browser should verify in another; this is the
6
+ * check that runs both claims.
7
+ *
8
+ * - `acrossEngines(make, file, { engines })` plays the replay twice here
9
+ * (the reference, and a repeat of it), compares the reference with the
10
+ * recording's checkpoints, then with each engine's per-tick checksums. On
11
+ * the first tick an engine differs, it loads both worlds at that tick and
12
+ * names every differing value, as `Desync.compare` does.
13
+ * - An `Engine` is any place that can run the game: `PlaywrightEngine`
14
+ * (Node host) runs Chromium, WebKit, and Firefox headless. For another
15
+ * host (a webview, a console devkit), run `trace` and `snapshotAt` there
16
+ * and wrap them as an `Engine`.
17
+ *
18
+ * `ritmo-devtools verify <entry> <replay> --engines node,chromium,webkit,firefox`
19
+ * is this module from the command line. With no engines it is the quick
20
+ * check in this process alone (two runs and the recording), the one a test
21
+ * runs; with browsers it is the one to run before trusting a replay or a
22
+ * lockstep match across them.
23
+ *
24
+ * This module calls no platform API: engines are injected.
25
+ *
26
+ * @module Verify
27
+ * @docGroup devtools
28
+ *
29
+ * @example
30
+ * ```ts
31
+ * declare const replayTarget: (playback: Replay.Playback) => Replay.Target<typeof Game.schema, typeof Root>
32
+ * declare const file: Replay.ReplayFile
33
+ * // ---cut---
34
+ * const engines = PlaywrightEngine.make({ entry: "src/replay-target.ts", browsers: ["chromium", "webkit"] })
35
+ * const verified = await Verify.acrossEngines(replayTarget, file, { engines: engines.engines })
36
+ * await engines.close()
37
+ * if (!verified.ok) console.log(verified.error.text)
38
+ * ```
39
+ */
40
+ import * as Result from "@typeonce/ritmo/Result"
41
+ import type { Schema } from "@typeonce/ritmo/Schema"
42
+ import type * as Snapshot from "@typeonce/ritmo/Snapshot"
43
+
44
+ import * as Desync from "./Desync.ts"
45
+ import * as Format from "./Format.ts"
46
+ import * as Rendered from "./Rendered.ts"
47
+ import * as Replay from "./Replay.ts"
48
+
49
+ /** The world's checksum (`runtime.checksum()`) after each replayed tick, in tick order, the start's tick first. */
50
+ export type Hashes = ReadonlyArray<{ readonly tick: number; readonly hash: string }>
51
+
52
+ /** The engine cannot run here: the tool or browser that runs it is not installed. */
53
+ export interface EngineMissing {
54
+ readonly _tag: "EngineMissing"
55
+ readonly engine: string
56
+ /** What is missing. */
57
+ readonly reason: string
58
+ /** The command that installs it. */
59
+ readonly install: string
60
+ }
61
+
62
+ /** The engine started and could not finish: the game did not load or threw, or the replay did not open there. */
63
+ export interface EngineFailed {
64
+ readonly _tag: "EngineFailed"
65
+ readonly engine: string
66
+ readonly message: string
67
+ }
68
+
69
+ /** Why an engine produced no result. */
70
+ export type EngineError = EngineMissing | EngineFailed
71
+
72
+ /**
73
+ * A JavaScript engine that runs the game, other than this process:
74
+ * `PlaywrightEngine` for browsers, or one a host builds from `trace` and
75
+ * `snapshotAt` run there.
76
+ */
77
+ export interface Engine {
78
+ /** Its name in reports (`chromium`, `webkit`). */
79
+ readonly name: string
80
+ /** Plays the whole replay and returns the world's checksum after every tick: `trace` run there. */
81
+ readonly trace: (file: Replay.ReplayFile) => Promise<Result.Result<Hashes, EngineError>>
82
+ /** Plays the replay to the end of `tick` and returns the world: `snapshotAt` run there. */
83
+ readonly snapshotAt: (file: Replay.ReplayFile, tick: number) => Promise<Result.Result<Snapshot.WorldSnapshot, EngineError>>
84
+ }
85
+
86
+ /** The replay played to its end: the checksum after every tick. What an `Engine` runs in its own engine. */
87
+ export const trace = <S extends Schema.Any, Root>(
88
+ make: (playback: Replay.Playback) => Replay.Target<S, Root>,
89
+ file: Replay.ReplayFile
90
+ ): Result.Result<Hashes, Replay.ReplayError> => {
91
+ const opened = Replay.session(make, file)
92
+ if (!opened.ok) return opened
93
+ opened.value.play()
94
+ return Result.success([...opened.value.hashes()].sort(([left], [right]) => left - right).map(([tick, hash]) => ({ tick, hash })))
95
+ }
96
+
97
+ /** The world at the end of `tick` (a recorder tick number, or the start's tick), as plain data. What an `Engine` runs to explain a difference. */
98
+ export const snapshotAt = <S extends Schema.Any, Root>(
99
+ make: (playback: Replay.Playback) => Replay.Target<S, Root>,
100
+ file: Replay.ReplayFile,
101
+ tick: number
102
+ ): Result.Result<Snapshot.WorldSnapshot, Replay.ReplayError> => {
103
+ const opened = Replay.session(make, file)
104
+ if (!opened.ok) return opened
105
+ opened.value.play({ to: tick })
106
+ const snapshot = opened.value.snapshot()
107
+ return snapshot.ok ? snapshot : Result.failure({ _tag: "SnapshotFailed", error: snapshot.error })
108
+ }
109
+
110
+ /** The engine reached the same world as the reference after every tick. */
111
+ export interface Agreed {
112
+ readonly _tag: "Agreed"
113
+ readonly engine: string
114
+ /** Ticks compared, the start's tick not counted. */
115
+ readonly ticks: number
116
+ }
117
+
118
+ /**
119
+ * The first tick whose world differs. `against` is `"node"` (the reference
120
+ * run in this process; for `engine: "node"`, a second run there) or
121
+ * `"recording"` (the file's checkpoints, which hold only hashes, so
122
+ * `differences` is empty).
123
+ */
124
+ export interface Diverged {
125
+ readonly _tag: "Diverged"
126
+ readonly engine: string
127
+ readonly against: "node" | "recording"
128
+ readonly tick: number
129
+ /** Every differing value at `tick`, the reference's world as `mine`, the engine's as `theirs`. */
130
+ readonly differences: ReadonlyArray<Desync.Difference>
131
+ /** Why `differences` is empty, when it is: the worlds could not be loaded, or they are equal as saves (the hash covers more). */
132
+ readonly unexplained: string | undefined
133
+ }
134
+
135
+ /** What one engine's check found. */
136
+ export type Outcome = Agreed | Diverged | EngineError
137
+
138
+ /** Every engine agreed: the replay is deterministic here, matches its recording, and plays the same everywhere. */
139
+ export interface Verified {
140
+ readonly schedule: string
141
+ /** Ticks compared, the start's tick not counted. */
142
+ readonly ticks: number
143
+ /** `node` first, then each engine. */
144
+ readonly engines: ReadonlyArray<string>
145
+ }
146
+
147
+ /** The replay did not open in this process: the reference could not run, so nothing was compared. */
148
+ export interface ReplayInvalid {
149
+ readonly _tag: "ReplayInvalid"
150
+ readonly error: Replay.ReplayError
151
+ readonly text: string
152
+ }
153
+
154
+ /** Some engine did not agree: `outcomes` has one entry per engine, `node` first; narrow each by `_tag`. */
155
+ export interface NotVerified {
156
+ readonly _tag: "NotVerified"
157
+ readonly outcomes: ReadonlyArray<Outcome>
158
+ readonly text: string
159
+ }
160
+
161
+ /** Why `acrossEngines` failed. */
162
+ export type VerifyError = ReplayInvalid | NotVerified
163
+
164
+ /** Which engines `acrossEngines` compares with this process. */
165
+ export interface Options {
166
+ /** Engines checked against this process, in report order. None checks this process alone. */
167
+ readonly engines?: ReadonlyArray<Engine>
168
+ }
169
+
170
+ const firstDifference = (reference: Hashes, other: Hashes): number | undefined => {
171
+ const mine = new Map(reference.map(({ tick, hash }) => [tick, hash] as const))
172
+ const theirs = new Map(other.map(({ tick, hash }) => [tick, hash] as const))
173
+ return [...new Set([...mine.keys(), ...theirs.keys()])].sort((left, right) => left - right).find((tick) => mine.get(tick) !== theirs.get(tick))
174
+ }
175
+
176
+ /**
177
+ * Plays `file` in this process twice and in each engine, and returns
178
+ * `Verified` when every run reaches the same world after every tick as the
179
+ * reference run here, and the reference matches the recording's
180
+ * checkpoints. Otherwise it fails with `NotVerified`, one outcome per engine:
181
+ * `Diverged` names the first differing tick and every differing value
182
+ * there, and an engine that is not installed or did not finish is reported
183
+ * as `EngineMissing` / `EngineFailed`, never skipped.
184
+ *
185
+ * `make` is the game's replay factory, the one `Replay.session` takes;
186
+ * each engine loads the same one.
187
+ */
188
+ export const acrossEngines = async <S extends Schema.Any, Root>(
189
+ make: (playback: Replay.Playback) => Replay.Target<S, Root>,
190
+ file: Replay.ReplayFile,
191
+ options: Options = {}
192
+ ): Promise<Result.Result<Rendered.Rendered<Verified>, VerifyError>> => {
193
+ const reference = trace(make, file)
194
+ if (!reference.ok) {
195
+ return Result.failure({ _tag: "ReplayInvalid", error: reference.error, text: `the replay does not open here: ${JSON.stringify(reference.error)}` })
196
+ }
197
+ const here = (tick: number) => snapshotAt(make, file, tick)
198
+ const ticks = reference.value.length - 1
199
+ const outcomes: Array<Outcome> = []
200
+
201
+ const repeat = trace(make, file)
202
+ const repeated = repeat.ok ? firstDifference(reference.value, repeat.value) : undefined
203
+ // As `Replay.session` does, the recording is compared on the replayed ticks, not on the start it restores.
204
+ const checkpoints = file.checkpoints.filter(({ tick }) => tick > file.start.tick)
205
+ const recorded = firstDifference(reference.value.filter(({ tick }) => checkpoints.some((checkpoint) => checkpoint.tick === tick)), checkpoints)
206
+ if (!repeat.ok) {
207
+ outcomes.push({ _tag: "EngineFailed", engine: "node", message: `a second run did not open: ${JSON.stringify(repeat.error)}` })
208
+ } else if (repeated !== undefined) {
209
+ outcomes.push(await explain("node", "node", repeated, here, async (tick) => here(tick)))
210
+ } else if (recorded !== undefined) {
211
+ outcomes.push({ _tag: "Diverged", engine: "node", against: "recording", tick: recorded, differences: [], unexplained: "the recording holds only a hash at this tick" })
212
+ } else {
213
+ outcomes.push({ _tag: "Agreed", engine: "node", ticks })
214
+ }
215
+
216
+ outcomes.push(...await Promise.all((options.engines ?? []).map(async (engine): Promise<Outcome> => {
217
+ const traced = await engine.trace(file)
218
+ if (!traced.ok) return traced.error
219
+ const tick = firstDifference(reference.value, traced.value)
220
+ if (tick === undefined) return { _tag: "Agreed", engine: engine.name, ticks }
221
+ return explain(engine.name, "node", tick, here, (at) => engine.snapshotAt(file, at))
222
+ })))
223
+
224
+ if (outcomes.every((outcome) => outcome._tag === "Agreed")) {
225
+ const engines = outcomes.map((outcome) => outcome.engine)
226
+ return Result.success(Rendered.make(
227
+ { schedule: file.schedule, ticks, engines },
228
+ `verified ${ticks} ticks of ${file.schedule} on ${engines.join(", ")}: every engine reaches the same world as node after every tick, and node matches the recording`
229
+ ))
230
+ }
231
+ return Result.failure({ _tag: "NotVerified", outcomes, text: [`NOT verified: ${ticks} ticks of ${file.schedule}`, ...outcomes.map(describe)].join("\n") })
232
+ }
233
+
234
+ /** Loads both worlds at `tick` and lists what differs. */
235
+ const explain = async (
236
+ engine: string,
237
+ against: "node",
238
+ tick: number,
239
+ mine: (tick: number) => Result.Result<Snapshot.WorldSnapshot, Replay.ReplayError>,
240
+ theirs: (tick: number) => Promise<Result.Result<Snapshot.WorldSnapshot, Replay.ReplayError | EngineError>>
241
+ ): Promise<Diverged> => {
242
+ const left = mine(tick)
243
+ const right = await theirs(tick)
244
+ if (!left.ok || !right.ok) {
245
+ const error = left.ok ? right.ok ? undefined : right.error : left.error
246
+ return { _tag: "Diverged", engine, against, tick, differences: [], unexplained: `the worlds at this tick could not be loaded: ${JSON.stringify(error)}` }
247
+ }
248
+ const differences = Desync.compare(left.value, right.value).data
249
+ return {
250
+ _tag: "Diverged", engine, against, tick, differences,
251
+ unexplained: differences.length === 0 ? "the saves are equal: the checksum covers something a snapshot does not show" : undefined
252
+ }
253
+ }
254
+
255
+ const where = ({ path, entity }: Desync.Difference): string =>
256
+ entity === undefined ? path : `${Format.entity(entity)}${path.slice(`entity ${entity}`.length)}`
257
+
258
+ /** One outcome as text: the first line names the engine, the tick, and the first difference. */
259
+ const describe = (outcome: Outcome): string => {
260
+ switch (outcome._tag) {
261
+ case "Agreed":
262
+ return `${outcome.engine}: agrees with ${outcome.engine === "node" ? "a second node run and the recording" : "node"} over ${outcome.ticks} ticks`
263
+ case "EngineMissing":
264
+ return `${outcome.engine}: not installed (${outcome.reason}): ${outcome.install}`
265
+ case "EngineFailed":
266
+ return `${outcome.engine}: failed: ${outcome.message}`
267
+ case "Diverged": {
268
+ const reference = outcome.engine === outcome.against ? "a second node run" : outcome.against
269
+ const [first] = outcome.differences
270
+ const head = `tick ${outcome.tick}: ${outcome.engine} differs from ${reference}${first === undefined ? "" : ` in ${where(first)} (${Format.value(first.mine)} -> ${Format.value(first.theirs)})`}`
271
+ if (outcome.unexplained !== undefined) return `${head}\n ${outcome.unexplained}`
272
+ return [head, ` ${outcome.differences.length} difference${outcome.differences.length === 1 ? "" : "s"} (${reference} -> ${outcome.engine}):`,
273
+ ...outcome.differences.map((difference) => ` ${where(difference)}: ${Format.value(difference.mine)} -> ${Format.value(difference.theirs)}`)].join("\n")
274
+ }
275
+ }
276
+ }
package/src/cli.ts CHANGED
@@ -3,8 +3,10 @@
3
3
  * `ritmo-devtools`: devtools from the command line.
4
4
  *
5
5
  * ritmo-devtools lint <entry>
6
+ * ritmo-devtools verify <entry> <replay> [--engines node,chromium,webkit,firefox] [--json]
7
+ * ritmo-devtools scan <entry> [--json]
6
8
  *
7
- * Imports `<entry>` (a module exporting `lintTarget`, see the `Lint` module),
9
+ * `lint` imports `<entry>` (a module exporting `lintTarget`, see the `Lint` module),
8
10
  * prints every lint of its schedules with its fix, and exits with 1 when one
9
11
  * is a warning. Info-level lints are printed and do not fail.
10
12
  *
@@ -19,20 +21,59 @@
19
21
  * A missing or unreadable config, one with `extends`, or one that never turns
20
22
  * the rule on prints why the check was skipped and does not fail.
21
23
  *
22
- * Exit codes: 0 ok, 1 lint warning or uncovered module, 2 usage error.
24
+ * Last, it notes when the project does not link the Ritmo skill from the
25
+ * installed package (`.agents/skills/ritmo` or `.claude/skills/ritmo`, see
26
+ * `SETUP.md`), or holds a copy that goes stale on upgrade. The note never
27
+ * fails the lint.
28
+ *
29
+ * `verify` imports `<entry>` (a module exporting `replayTarget`, the
30
+ * `make(playback)` factory `Replay.session` takes), plays the replay file in
31
+ * Node and in each listed browser engine, and prints the first tick whose
32
+ * checksum differs from Node's, with every value that differs there (see the
33
+ * `Verify` module). Node always runs, as the reference; `--engines node` (the
34
+ * default) needs no other dependency. Browser engines need `playwright` and
35
+ * `vite` (see the `PlaywrightEngine` module); one that is not installed is
36
+ * printed with its install command and fails the check. `--json` prints the
37
+ * result as JSON instead of text.
38
+ *
39
+ * `scan` resolves every file `<entry>` (the simulation entry) imports,
40
+ * `node_modules` included, and runs the oxlint rules `ritmo/use-ops-for-math`,
41
+ * `ritmo/use-clock-for-time`, and `ritmo/use-random-for-randomness` over them,
42
+ * so a dependency that calls `Math.sin`, `Date.now`, or `Math.random` shows
43
+ * before a desync does. Findings are printed per package with what to do next;
44
+ * `--json` prints them as JSON instead. It is a hint, not a verdict: it exits
45
+ * with 0 with or without findings. It needs `rolldown` (Vite 8 includes it)
46
+ * and the game's `oxlint` with `@typeonce/oxlint-plugin-ritmo`; a missing one
47
+ * is printed with its install command and exits with 2.
48
+ *
49
+ * Exit codes: 0 ok (and every `scan` that ran), 1 lint warning, uncovered
50
+ * module, or an engine that differs or did not run, 2 usage error (for `scan`
51
+ * also an unreadable entry, an import that does not resolve, or a missing tool).
23
52
  * Requires Node 22.15 or later for `module.registerHooks`; on older Node it
24
53
  * prints that coverage was not checked.
25
54
  *
26
55
  * @module cli
27
56
  * @docGroup devtools
28
57
  */
58
+ import { readFileSync } from "node:fs"
29
59
  import { resolve } from "node:path"
30
60
  import { pathToFileURL } from "node:url"
31
61
 
62
+ import * as DependencyScan from "./internal/dependencyScan.ts"
32
63
  import * as SimulationCoverage from "./internal/simulationCoverage.ts"
64
+ import * as SkillLink from "./internal/skillLink.ts"
33
65
  import * as Lint from "./Lint.ts"
66
+ import * as Replay from "./Replay.ts"
67
+ import * as Verify from "./Verify.ts"
34
68
 
35
- const usage = "usage: ritmo-devtools lint <entry>\n <entry> exports lintTarget: () => { runtime, schedules, describe?, hostEvents? } (see the Lint module)"
69
+ const usage = [
70
+ "usage: ritmo-devtools lint <entry>",
71
+ " ritmo-devtools verify <entry> <replay> [--engines node,chromium,webkit,firefox] [--json]",
72
+ " ritmo-devtools scan <entry> [--json]",
73
+ " lint: <entry> exports lintTarget: () => { runtime, schedules, describe?, hostEvents? } (see the Lint module)",
74
+ " verify: <entry> exports replayTarget: (playback) => { runtime, schedules, hostClock } (see the Verify module)",
75
+ " scan: <entry> is the simulation's entry module; every file it imports, node_modules included, is checked for Math, clock, and randomness calls"
76
+ ].join("\n")
36
77
 
37
78
  const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null
38
79
 
@@ -47,11 +88,15 @@ const isTarget = (value: unknown): value is Lint.Target<any, any> =>
47
88
  && (value["hostEvents"] === undefined || Array.isArray(value["hostEvents"]))
48
89
 
49
90
  const main = async (args: ReadonlyArray<string>): Promise<number> => {
50
- const [command, entry] = args
51
- if (command !== "lint" || entry === undefined) {
52
- console.error(usage)
53
- return 2
54
- }
91
+ const [command, ...rest] = args
92
+ if (command === "lint" && rest.length === 1) return lint(rest[0]!)
93
+ if (command === "verify") return verify(rest)
94
+ if (command === "scan") return scan(rest)
95
+ console.error(usage)
96
+ return 2
97
+ }
98
+
99
+ const lint = async (entry: string): Promise<number> => {
55
100
  const loads = SimulationCoverage.recordLoads()
56
101
  const loaded: unknown = await import(pathToFileURL(resolve(entry)).href)
57
102
  // Snapshot before lintTarget runs: modules it imports (render schedules to describe) are host code.
@@ -68,14 +113,104 @@ const main = async (args: ReadonlyArray<string>): Promise<number> => {
68
113
  }
69
114
  const report = Lint.run(target)
70
115
  console.log(report.text)
71
- if (simulationModules === undefined) {
72
- console.log("simulation coverage not checked: needs Node 22.15 or later (module.registerHooks)")
73
- return report.data.ok ? 0 : 1
116
+ const status = (() => {
117
+ if (simulationModules === undefined) {
118
+ console.log("simulation coverage not checked: needs Node 22.15 or later (module.registerHooks)")
119
+ return report.data.ok ? 0 : 1
120
+ }
121
+ const coverage = SimulationCoverage.check(process.cwd(), resolve(entry), simulationModules)
122
+ const text = SimulationCoverage.format(coverage)
123
+ if (text !== "") console.log(text)
124
+ return report.data.ok && (!coverage.checked || coverage.uncovered.length === 0) ? 0 : 1
125
+ })()
126
+ // A note only: it never changes the exit code.
127
+ const skill = SkillLink.format(SkillLink.check(process.cwd()))
128
+ if (skill !== "") console.log(skill)
129
+ return status
130
+ }
131
+
132
+ const engineNames = ["node", "chromium", "webkit", "firefox"] as const
133
+
134
+ const verify = async (args: ReadonlyArray<string>): Promise<number> => {
135
+ const positional: Array<string> = []
136
+ let engines: ReadonlyArray<string> = ["node"]
137
+ let json = false
138
+ for (let index = 0; index < args.length; index++) {
139
+ const arg = args[index]!
140
+ if (arg === "--json") json = true
141
+ else if (arg === "--engines") engines = (args[++index] ?? "").split(",").filter((name) => name !== "")
142
+ else if (arg.startsWith("--engines=")) engines = arg.slice("--engines=".length).split(",").filter((name) => name !== "")
143
+ else positional.push(arg)
144
+ }
145
+ const [entry, replay] = positional
146
+ if (entry === undefined || replay === undefined || positional.length !== 2) {
147
+ console.error(usage)
148
+ return 2
149
+ }
150
+ const unknown = engines.filter((name) => !(engineNames as ReadonlyArray<string>).includes(name))
151
+ if (engines.length === 0 || unknown.length > 0) {
152
+ console.error(`--engines takes a comma-separated list of ${engineNames.join(", ")}${unknown.length > 0 ? `; unknown: ${unknown.join(", ")}` : ""}`)
153
+ return 2
154
+ }
155
+ let data: unknown
156
+ try {
157
+ data = JSON.parse(readFileSync(resolve(replay), "utf8"))
158
+ } catch (error) {
159
+ console.error(`${replay} could not be read as JSON: ${error instanceof Error ? error.message : String(error)}`)
160
+ return 2
161
+ }
162
+ const file = Replay.parse(data)
163
+ if (!file.ok) {
164
+ console.error(`${replay} is not a replay file: ${file.error._tag === "InvalidReplay" ? file.error.message : file.error._tag}`)
165
+ return 2
166
+ }
167
+ const loaded: unknown = await import(pathToFileURL(resolve(entry)).href)
168
+ const make = isRecord(loaded) ? loaded["replayTarget"] : undefined
169
+ if (typeof make !== "function") {
170
+ console.error(`${entry} must export replayTarget: (playback) => { runtime, schedules, hostClock } (see the Verify module)`)
171
+ return 2
172
+ }
173
+ // The browser adapter, and with it playwright and vite, loads only when a browser is listed.
174
+ const browsers = engines.filter((name) => name !== "node")
175
+ const PlaywrightEngine = browsers.length > 0 ? await import("./PlaywrightEngine.ts") : undefined
176
+ const playwright = PlaywrightEngine?.make({ entry, browsers: browsers.filter(PlaywrightEngine.isBrowser) })
177
+ let result: Awaited<ReturnType<typeof Verify.acrossEngines>>
178
+ try {
179
+ // The entry's type is checked where it is written; here only its shape is known.
180
+ result = await Verify.acrossEngines(make as (playback: Replay.Playback) => Replay.Target<any, any>, file.value, { engines: playwright?.engines ?? [] })
181
+ } catch (error) {
182
+ console.error(`replayTarget in ${entry} threw: ${error instanceof Error ? error.stack ?? error.message : String(error)}`)
183
+ return 2
184
+ } finally {
185
+ await playwright?.close()
74
186
  }
75
- const coverage = SimulationCoverage.check(process.cwd(), resolve(entry), simulationModules)
76
- const text = SimulationCoverage.format(coverage)
77
- if (text !== "") console.log(text)
78
- return report.data.ok && (!coverage.checked || coverage.uncovered.length === 0) ? 0 : 1
187
+ console.log(json ? JSON.stringify(result.ok ? { ok: true, ...result.value.data } : { ok: false, ...withoutText(result.error) }, null, 2) : result.ok ? result.value.text : result.error.text)
188
+ return result.ok ? 0 : 1
79
189
  }
80
190
 
191
+ const scan = async (args: ReadonlyArray<string>): Promise<number> => {
192
+ const json = args.includes("--json")
193
+ const positional = args.filter((arg) => arg !== "--json")
194
+ if (positional.length !== 1 || positional[0]!.startsWith("-")) {
195
+ console.error(usage)
196
+ return 2
197
+ }
198
+ const result = await DependencyScan.run(positional[0]!, process.cwd())
199
+ if (!result.ok) {
200
+ const error = result.error
201
+ console.error(error._tag === "ToolMissing"
202
+ ? `scan needs ${error.tool}, which is not installed: ${error.install}`
203
+ : error._tag === "ResolveFailed"
204
+ ? `the imports of ${positional[0]} could not be resolved: ${error.message}`
205
+ : error._tag === "LintFailed"
206
+ ? `oxlint did not run: ${error.message}`
207
+ : error.message)
208
+ return 2
209
+ }
210
+ console.log(json ? JSON.stringify(result.value, null, 2) : DependencyScan.format(result.value))
211
+ return 0
212
+ }
213
+
214
+ const withoutText = ({ text: _text, ...error }: Verify.VerifyError) => error
215
+
81
216
  process.exitCode = await main(process.argv.slice(2))
package/src/index.ts CHANGED
@@ -1,13 +1,14 @@
1
- /** Debug sessions, trace history, text reports, and a live browser monitor for ritmo runtimes. */
1
+ /** Headless debug sessions, trace history, text reports, replays, and fuzzing for ritmo runtimes. */
2
2
  export * as Format from "./Format.ts"
3
+ export * as Fuzz from "./Fuzz.ts"
3
4
  export * as Desync from "./Desync.ts"
4
5
  export * as Determinism from "./Determinism.ts"
5
6
  export * as Invariant from "./Invariant.ts"
6
7
  export * as Lint from "./Lint.ts"
7
- export * as Monitor from "./Monitor.ts"
8
8
  export * as Replay from "./Replay.ts"
9
9
  export * as Rendered from "./Rendered.ts"
10
10
  export * as Session from "./Session.ts"
11
+ export * as Verify from "./Verify.ts"
11
12
 
12
13
  /** The package's identifier. */
13
14
  export const packageTag = "devtools" as const