@typeonce/ritmo-devtools 0.9.0 → 0.11.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 (70) hide show
  1. package/CHANGELOG.md +274 -0
  2. package/README.md +33 -9
  3. package/dist/Format.d.ts +1 -0
  4. package/dist/Format.d.ts.map +1 -1
  5. package/dist/Format.js.map +1 -1
  6. package/dist/Invariant.d.ts +2 -1
  7. package/dist/Invariant.d.ts.map +1 -1
  8. package/dist/Invariant.js.map +1 -1
  9. package/dist/Lint.d.ts +1 -0
  10. package/dist/Lint.d.ts.map +1 -1
  11. package/dist/Lint.js.map +1 -1
  12. package/dist/Monitor.d.ts +2 -0
  13. package/dist/Monitor.d.ts.map +1 -1
  14. package/dist/Monitor.js.map +1 -1
  15. package/dist/Rendered.d.ts +2 -0
  16. package/dist/Rendered.d.ts.map +1 -1
  17. package/dist/Rendered.js +2 -0
  18. package/dist/Rendered.js.map +1 -1
  19. package/dist/Replay.d.ts +8 -2
  20. package/dist/Replay.d.ts.map +1 -1
  21. package/dist/Replay.js.map +1 -1
  22. package/dist/ReplayNodeSink.d.ts +1 -0
  23. package/dist/ReplayNodeSink.d.ts.map +1 -1
  24. package/dist/ReplayNodeSink.js +1 -0
  25. package/dist/ReplayNodeSink.js.map +1 -1
  26. package/dist/ReplayVitePlugin.d.ts +5 -1
  27. package/dist/ReplayVitePlugin.d.ts.map +1 -1
  28. package/dist/ReplayVitePlugin.js +4 -0
  29. package/dist/ReplayVitePlugin.js.map +1 -1
  30. package/dist/ReplayViteSink.d.ts +5 -0
  31. package/dist/ReplayViteSink.d.ts.map +1 -1
  32. package/dist/ReplayViteSink.js +4 -0
  33. package/dist/ReplayViteSink.js.map +1 -1
  34. package/dist/Session.d.ts +38 -6
  35. package/dist/Session.d.ts.map +1 -1
  36. package/dist/Session.js +12 -4
  37. package/dist/Session.js.map +1 -1
  38. package/dist/cli.js +28 -1
  39. package/dist/cli.js.map +1 -1
  40. package/dist/index.d.ts +1 -0
  41. package/dist/index.d.ts.map +1 -1
  42. package/dist/index.js +1 -0
  43. package/dist/index.js.map +1 -1
  44. package/dist/internal/monitor.d.ts +3 -1
  45. package/dist/internal/monitor.d.ts.map +1 -1
  46. package/dist/internal/monitor.js.map +1 -1
  47. package/dist/internal/simulationCoverage.d.ts +18 -0
  48. package/dist/internal/simulationCoverage.d.ts.map +1 -0
  49. package/dist/internal/simulationCoverage.js +135 -0
  50. package/dist/internal/simulationCoverage.js.map +1 -0
  51. package/dist/internal/version.d.ts +1 -1
  52. package/dist/internal/version.d.ts.map +1 -1
  53. package/dist/internal/version.js +1 -1
  54. package/dist/internal/version.js.map +1 -1
  55. package/package.json +4 -3
  56. package/src/Format.ts +1 -0
  57. package/src/Invariant.ts +2 -1
  58. package/src/Lint.ts +1 -0
  59. package/src/Monitor.ts +2 -0
  60. package/src/Rendered.ts +2 -0
  61. package/src/Replay.ts +7 -1
  62. package/src/ReplayNodeSink.ts +1 -0
  63. package/src/ReplayVitePlugin.ts +5 -1
  64. package/src/ReplayViteSink.ts +5 -0
  65. package/src/Session.ts +38 -6
  66. package/src/cli.ts +27 -1
  67. package/src/index.ts +1 -0
  68. package/src/internal/monitor.ts +3 -1
  69. package/src/internal/simulationCoverage.ts +136 -0
  70. package/src/internal/version.ts +1 -1
@@ -0,0 +1,135 @@
1
+ /**
2
+ * Simulation coverage for the `ritmo-devtools lint` CLI (Node only): which
3
+ * modules the simulation loads that the oxlint simulation rules
4
+ * (`ritmo/keep-simulation-headless` and its neighbours) do not cover.
5
+ *
6
+ * @internal
7
+ */
8
+ import { readFileSync, realpathSync } from "node:fs";
9
+ import * as Module from "node:module";
10
+ import { dirname, isAbsolute, join, matchesGlob, relative, sep } from "node:path";
11
+ import { fileURLToPath } from "node:url";
12
+ const configName = ".oxlintrc.json";
13
+ const rule = "ritmo/keep-simulation-headless";
14
+ /** Starts recording every `file:` module Node loads from now on. `undefined` when this Node has no `module.registerHooks` (before 22.15). */
15
+ export const recordLoads = () => {
16
+ if (typeof Module.registerHooks !== "function")
17
+ return undefined;
18
+ const urls = new Set();
19
+ Module.registerHooks({
20
+ load: (url, context, nextLoad) => {
21
+ if (url.startsWith("file:"))
22
+ urls.add(url);
23
+ return nextLoad(url, context);
24
+ }
25
+ });
26
+ return () => [...urls];
27
+ };
28
+ const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
29
+ /** Removes `//` and `/* *\/` comments outside strings, then trailing commas before `}` or `]`. */
30
+ const stripJsonc = (text) => {
31
+ let out = "";
32
+ let index = 0;
33
+ while (index < text.length) {
34
+ const char = text[index];
35
+ if (char === "\"") {
36
+ let end = index + 1;
37
+ while (end < text.length && text[end] !== "\"")
38
+ end += text[end] === "\\" ? 2 : 1;
39
+ out += text.slice(index, end + 1);
40
+ index = end + 1;
41
+ }
42
+ else if (char === "/" && text[index + 1] === "/") {
43
+ while (index < text.length && text[index] !== "\n")
44
+ index++;
45
+ }
46
+ else if (char === "/" && text[index + 1] === "*") {
47
+ const end = text.indexOf("*/", index + 2);
48
+ index = end === -1 ? text.length : end + 2;
49
+ }
50
+ else {
51
+ out += char;
52
+ index++;
53
+ }
54
+ }
55
+ return out.replace(/("(?:[^"\\]|\\.)*")|,(\s*[}\]])/g, (match, string, close) => string !== undefined ? match : close);
56
+ };
57
+ /** `true` on, `false` off, `undefined` when the value does not set the rule. */
58
+ const severity = (value) => {
59
+ const level = Array.isArray(value) ? value[0] : value;
60
+ if (level === "error" || level === "warn" || level === 1 || level === 2)
61
+ return true;
62
+ if (level === "off" || level === 0)
63
+ return false;
64
+ return undefined;
65
+ };
66
+ const globs = (value) => Array.isArray(value) ? value.filter((glob) => typeof glob === "string") : [];
67
+ const matches = (file, patterns) => patterns.some((pattern) => matchesGlob(file, pattern));
68
+ /**
69
+ * Reads `.oxlintrc.json` in `cwd` and returns the loaded modules inside its
70
+ * directory (outside `node_modules`, not the entry) where `ritmo/keep-simulation-headless`
71
+ * is not on, as posix paths relative to the config, sorted.
72
+ */
73
+ export const check = (cwd, entry, loaded) => {
74
+ const configPath = join(cwd, configName);
75
+ let text;
76
+ try {
77
+ text = readFileSync(configPath, "utf8");
78
+ }
79
+ catch {
80
+ return { checked: false, reason: `no ${configName} in ${cwd}` };
81
+ }
82
+ let config;
83
+ try {
84
+ config = JSON.parse(stripJsonc(text));
85
+ }
86
+ catch {
87
+ return { checked: false, reason: `${configName} is not valid JSON with comments` };
88
+ }
89
+ if (!isRecord(config))
90
+ return { checked: false, reason: `${configName} is not an object` };
91
+ if (config["extends"] !== undefined)
92
+ return { checked: false, reason: `${configName} uses "extends", which this check does not follow` };
93
+ const topLevel = isRecord(config["rules"]) ? severity(config["rules"][rule]) : undefined;
94
+ const overrides = (Array.isArray(config["overrides"]) ? config["overrides"] : []).filter(isRecord).map((override) => ({
95
+ files: globs(override["files"]),
96
+ setting: isRecord(override["rules"]) ? severity(override["rules"][rule]) : undefined
97
+ }));
98
+ if (topLevel !== true && !overrides.some((override) => override.setting === true)) {
99
+ return { checked: false, reason: `no rules in ${configName} turn on ${rule}` };
100
+ }
101
+ const ignored = globs(config["ignorePatterns"]);
102
+ const root = realpathSync(dirname(configPath));
103
+ const entryPath = realpathSync(entry);
104
+ const uncovered = new Set();
105
+ for (const url of loaded) {
106
+ let file;
107
+ try {
108
+ file = realpathSync(fileURLToPath(url));
109
+ }
110
+ catch {
111
+ continue;
112
+ }
113
+ const path = relative(root, file);
114
+ if (file === entryPath || path === "" || path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path))
115
+ continue;
116
+ const posix = path.split(sep).join("/");
117
+ if (posix.split("/").includes("node_modules"))
118
+ continue;
119
+ let on = topLevel === true;
120
+ for (const override of overrides) {
121
+ if (override.setting !== undefined && matches(posix, override.files))
122
+ on = override.setting;
123
+ }
124
+ if (!on || matches(posix, ignored))
125
+ uncovered.add(posix);
126
+ }
127
+ return { checked: true, uncovered: [...uncovered].sort() };
128
+ };
129
+ /** The CLI text for a coverage result: a "not checked" line, or one block per uncovered module. */
130
+ export const format = (coverage) => !coverage.checked
131
+ ? `simulation coverage not checked: ${coverage.reason}`
132
+ : coverage.uncovered.map((file) => `uncovered-simulation-module ${file}\n`
133
+ + ` The simulation loads this file, but the simulation rules in ${configName} do not cover it.\n`
134
+ + ` Add it to the simulation override's "files", or stop importing values from it.`).join("\n");
135
+ //# sourceMappingURL=simulationCoverage.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"simulationCoverage.js","sourceRoot":"","sources":["../../src/internal/simulationCoverage.ts"],"names":[],"mappings":"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"}
@@ -3,5 +3,5 @@
3
3
  * `package.json` by `scripts/sync-version.ts` (run by \`pnpm version-packages\`)
4
4
  * and checked by a test.
5
5
  */
6
- export declare const libraryVersion = "0.9.0";
6
+ export declare const libraryVersion = "0.11.0";
7
7
  //# sourceMappingURL=version.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/internal/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAU,CAAA"}
1
+ {"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/internal/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,cAAc,WAAW,CAAA"}
@@ -3,5 +3,5 @@
3
3
  * `package.json` by `scripts/sync-version.ts` (run by \`pnpm version-packages\`)
4
4
  * and checked by a test.
5
5
  */
6
- export const libraryVersion = "0.9.0";
6
+ export const libraryVersion = "0.11.0";
7
7
  //# sourceMappingURL=version.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/internal/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAA"}
1
+ {"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/internal/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@typeonce/ritmo-devtools",
3
- "version": "0.9.0",
3
+ "version": "0.11.0",
4
4
  "description": "Headless debug sessions, trace history, text reports, and a live browser monitor for Ritmo runtimes",
5
5
  "author": "Sandro Maglione",
6
6
  "license": "MIT",
@@ -27,6 +27,7 @@
27
27
  "src/**/*.ts",
28
28
  "dist",
29
29
  "README.md",
30
+ "CHANGELOG.md",
30
31
  "LICENSE"
31
32
  ],
32
33
  "bin": {
@@ -50,10 +51,10 @@
50
51
  "provenance": true
51
52
  },
52
53
  "dependencies": {
53
- "@typeonce/ritmo": "^0.9.0"
54
+ "@typeonce/ritmo": "^0.11.0"
54
55
  },
55
56
  "engines": {
56
- "node": ">=20"
57
+ "node": ">=22.15"
57
58
  },
58
59
  "scripts": {
59
60
  "build": "tsc -b tsconfig.json --pretty false",
package/src/Format.ts CHANGED
@@ -11,6 +11,7 @@
11
11
  */
12
12
  import type * as Debug from "@typeonce/ritmo/Debug"
13
13
 
14
+ /** How much of a nested value the text output prints. */
14
15
  export interface ValueOptions {
15
16
  /** Nesting depth printed before `…`. Defaults to 3. */
16
17
  readonly depth?: number
package/src/Invariant.ts CHANGED
@@ -27,7 +27,7 @@
27
27
  * return undefined
28
28
  * }))
29
29
  *
30
- * const session = Session.make(runtime, { schedules: { update }, invariants: [PlayerInsideWorld] })
30
+ * const session = Session.make(runtime, { hostClock, schedules: { update }, invariants: [PlayerInsideWorld] })
31
31
  * ```
32
32
  */
33
33
  import type * as Inspector from "@typeonce/ritmo/Inspector"
@@ -37,6 +37,7 @@ export namespace Invariant {
37
37
  export type CheckInspector = Inspector.InspectorDefinition<any, string | undefined, any, any, any>
38
38
  }
39
39
 
40
+ /** A named read-only world check, made with {@link fromInspector}. */
40
41
  export interface Invariant<I extends Invariant.CheckInspector = Invariant.CheckInspector> {
41
42
  /** The inspector's name, printed when the invariant is violated. */
42
43
  readonly name: I["name"]
package/src/Lint.ts CHANGED
@@ -49,6 +49,7 @@ export interface Target<S extends Schema.Any, Root> {
49
49
  readonly hostEvents?: ReadonlyArray<Schema.EventDescriptor<S>>
50
50
  }
51
51
 
52
+ /** The result of {@link run}: every lint, counts by severity, and the verdict. */
52
53
  export interface Report {
53
54
  readonly lints: ReadonlyArray<Debug.Lint>
54
55
  readonly warnings: number
package/src/Monitor.ts CHANGED
@@ -52,6 +52,7 @@ export interface Target<S extends Schema.Any, Root> {
52
52
  readonly debug: Debug.Handle<S, Root>
53
53
  }
54
54
 
55
+ /** What `attach` shows, where, and how the panel is opened. */
55
56
  export interface Options<S extends Schema.Any, Root> {
56
57
  /**
57
58
  * The schedules the game ticks, by name. They name the schedules in the
@@ -84,6 +85,7 @@ export interface Options<S extends Schema.Any, Root> {
84
85
  readonly replay?: { readonly save: (reason: string) => unknown }
85
86
  }
86
87
 
88
+ /** An attached monitor panel, from `attach`. */
87
89
  export interface Monitor {
88
90
  readonly open: () => void
89
91
  readonly close: () => void
package/src/Rendered.ts CHANGED
@@ -12,6 +12,7 @@
12
12
 
13
13
  const inspectSymbol = Symbol.for("nodejs.util.inspect.custom")
14
14
 
15
+ /** A value of `A` that prints as `text`; read `data` in code. */
15
16
  export class Rendered<A> {
16
17
  readonly data: A
17
18
  readonly text: string
@@ -34,4 +35,5 @@ export class Rendered<A> {
34
35
  }
35
36
  }
36
37
 
38
+ /** Pairs data with its text. */
37
39
  export const make = <A>(data: A, text: string): Rendered<A> => new Rendered(data, text)
package/src/Replay.ts CHANGED
@@ -40,7 +40,8 @@
40
40
  * })
41
41
  *
42
42
  * // later, in Node:
43
- * const replay = Replay.session(makeReplaySimulation, Replay.parse(JSON.parse(text)))
43
+ * const file = Replay.parse(JSON.parse(text))
44
+ * const replay = file.ok ? Replay.session(makeReplaySimulation, file.value) : file
44
45
  * if (replay.ok) console.log(replay.value.play().text)
45
46
  * ```
46
47
  */
@@ -164,6 +165,7 @@ export interface Recordable<S extends Schema.Any, Root> {
164
165
  readonly inspect: (inspector: never) => unknown
165
166
  }
166
167
 
168
+ /** What `recorder` records, how much it keeps, and where and when it saves. */
167
169
  export interface RecorderOptions<S extends Schema.Any, Root, Recorded extends AnySchedule<S, Root>> {
168
170
  /** The schedule to record: the one ticked once per simulation step. */
169
171
  readonly schedule: Recorded
@@ -175,6 +177,7 @@ export interface RecorderOptions<S extends Schema.Any, Root, Recorded extends An
175
177
  readonly step: Clock.Step
176
178
  /** Seconds between world snapshots. Defaults to 5. */
177
179
  readonly every?: number
180
+ /** Where `save` hands each replay (`memorySink`, `ReplayNodeSink`, `ReplayViteSink`). */
178
181
  readonly sink: Sink
179
182
  /**
180
183
  * Wall time, for `savedAt` (milliseconds since the epoch): sinks name
@@ -189,6 +192,7 @@ export interface RecorderOptions<S extends Schema.Any, Root, Recorded extends An
189
192
  }
190
193
  }
191
194
 
195
+ /** A running recorder, from `recorder`. */
192
196
  export interface Recorder {
193
197
  /** Hands the current window to the sink, with `reason`, and returns it. */
194
198
  readonly save: (reason: string) => ReplayFile
@@ -430,6 +434,7 @@ export interface Target<S extends Schema.Any, Root> {
430
434
  readonly schedules: Readonly<Record<string, AnySchedule<S, Root>>>
431
435
  }
432
436
 
437
+ /** What one `ReplaySession.play` did: the session run, and the checkpoints that differ. */
433
438
  export interface PlayResult {
434
439
  /** The session's run of the replayed ticks. */
435
440
  readonly run: Session.RunResult
@@ -437,6 +442,7 @@ export interface PlayResult {
437
442
  readonly diverged: ReadonlyArray<{ readonly tick: number; readonly recorded: string; readonly replayed: string }>
438
443
  }
439
444
 
445
+ /** An opened replay, from `session`, restored to its start and ready to `play`. */
440
446
  export interface ReplaySession<S extends Schema.Any, Names extends string> {
441
447
  /** The devtools session the ticks run in: `why`, `journal`, `report` work as in any run. */
442
448
  readonly session: Session.Session<S, Names>
@@ -24,6 +24,7 @@ export interface NodeSink extends Replay.Sink {
24
24
  export const fileName = (file: Replay.ReplayFile): string =>
25
25
  `${new Date(file.savedAt).toISOString().replaceAll(":", "-")}-tick-${file.ticks.at(-1)?.tick ?? file.start.tick}.json`
26
26
 
27
+ /** A sink writing each replay as a JSON file in `directory` (created if missing), named by {@link fileName}. */
27
28
  export const make = (options: { readonly directory: string }): NodeSink => {
28
29
  const written: Array<string> = []
29
30
  return {
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * A Vite plugin (Node side) that receives the replays `ReplayViteSink`
3
3
  * posts from the page and writes them into the game's repository as
4
- * `.replays/<time>.json`, logging the path, the tick count, and the reason.
4
+ * `.replays/<time>-tick-<tick>.json`, logging the path, the tick count, and the reason.
5
5
  * Development only: it does nothing in a build.
6
6
  *
7
7
  * Add `.replays/` to the game's `.gitignore`.
@@ -37,6 +37,10 @@ export interface Plugin {
37
37
  readonly configureServer: (server: DevServer) => void
38
38
  }
39
39
 
40
+ /**
41
+ * The plugin. `directory` is relative to the Vite root and defaults to
42
+ * `.replays`. A post that is not a replay is answered with status 400.
43
+ */
40
44
  export const plugin = (options: { readonly directory?: string } = {}): Plugin => ({
41
45
  name: "ritmo-replays",
42
46
  apply: "serve",
@@ -18,6 +18,7 @@ import type * as Replay from "./Replay.ts"
18
18
  /** The dev server's endpoint for replays (what `ReplayVitePlugin` serves). */
19
19
  export const endpoint = "/__ritmo/replays"
20
20
 
21
+ /** What `make` posts with. */
21
22
  export interface Options {
22
23
  /** The page's `fetch` (or any function with its shape for these two arguments). */
23
24
  readonly fetch: (url: string, init: { readonly method: "POST"; readonly headers: Readonly<Record<string, string>>; readonly body: string }) => Promise<unknown>
@@ -25,6 +26,10 @@ export interface Options {
25
26
  readonly onError?: (error: unknown) => void
26
27
  }
27
28
 
29
+ /**
30
+ * A sink posting each replay to {@link endpoint}, without waiting for the
31
+ * answer. Use `ReplayNodeSink` instead outside a browser.
32
+ */
28
33
  export const make = (options: Options): Replay.Sink => ({
29
34
  save: (file) => {
30
35
  void options.fetch(endpoint, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(file) })
package/src/Session.ts CHANGED
@@ -14,10 +14,11 @@
14
14
  * - `system(name)` shows one system's declared access and recent activity.
15
15
  * - `describe()`, `dump(filter)`, `streams()` render the core debug handle.
16
16
  * - `report()` summarizes per-system timing and warnings accumulated while
17
- * tracing: missed reads, commands still pending at the end of a frame,
18
- * failed transitions, skipped systems that discarded messages, NaN or
19
- * infinite numbers written anywhere, and entity counts that keep growing
20
- * through a run.
17
+ * tracing: failed systems, missed reads, commands and next states still
18
+ * pending at the end of a frame, failed transitions, skipped systems that
19
+ * discarded messages, sent events no system reads, NaN or infinite numbers
20
+ * written anywhere, entity counts that keep growing through a run, and
21
+ * failed tick results nobody read.
21
22
  *
22
23
  * Everything returns a `Rendered` value that prints as text.
23
24
  *
@@ -27,6 +28,7 @@
27
28
  * @example
28
29
  * ```ts
29
30
  * const session = Session.make(runtime, {
31
+ * hostClock: HostClock.test(),
30
32
  * schedules: { setup: setupSchedule, update: updateSchedule },
31
33
  * invariants: [PlayerInsideWorld]
32
34
  * })
@@ -95,6 +97,7 @@ export type ValidateInvariants<
95
97
  ? unknown
96
98
  : { readonly __fixInvariantRequirements__: InvariantRequirementErrors<Invariants, Services, Resources, Machines> }
97
99
 
100
+ /** What `Session.make` drives and checks, and how it prints. */
98
101
  export interface Options<
99
102
  S extends Schema.Any,
100
103
  Root,
@@ -130,6 +133,7 @@ export interface Options<
130
133
  readonly format?: Format.ValueOptions
131
134
  }
132
135
 
136
+ /** How long `session.run` ticks: `frames` frames, or fewer when `until` returns `true`. */
133
137
  export interface RunOptions {
134
138
  /** Frames to run. Defaults to 1. */
135
139
  readonly frames?: number
@@ -164,6 +168,7 @@ export type Stop =
164
168
  readonly when: "next-tick" | "session-end"
165
169
  }
166
170
 
171
+ /** What one `session.run` did and why it stopped; its text is the run summary. */
167
172
  export interface RunResult {
168
173
  readonly schedule: string
169
174
  /** Whether the run completed or reached `until`. */
@@ -173,7 +178,7 @@ export interface RunResult {
173
178
  readonly range: readonly [number, number] | undefined
174
179
  readonly stop: Stop
175
180
  readonly ms: number
176
- /** Warning-level lints over the named schedules; details in `describe()`. */
181
+ /** Warning-level `describe()` lints (the named schedules and what the runtime has seen); details in `describe()`. */
177
182
  readonly lintWarnings: number
178
183
  /** Warnings raised during this run, by code; details in `report()`. */
179
184
  readonly warnings: Readonly<Partial<Record<Warning["code"], number>>>
@@ -193,6 +198,10 @@ export interface PopulationRange {
193
198
  readonly end: number
194
199
  }
195
200
 
201
+ /**
202
+ * Narrows `session.journal`: every field given must match. Without a filter
203
+ * the journal lists the whole kept history.
204
+ */
196
205
  export interface JournalFilter<S extends Schema.Any> {
197
206
  /** One frame or an inclusive `[from, to]` range. */
198
207
  readonly frames?: number | readonly [number, number]
@@ -217,6 +226,7 @@ export interface JournalFilter<S extends Schema.Any> {
217
226
  readonly verbose?: boolean
218
227
  }
219
228
 
229
+ /** One system's runs and timing over the session, in `report()` and `system(name)`. */
220
230
  export interface SystemStats {
221
231
  readonly system: string
222
232
  readonly runs: number
@@ -229,6 +239,11 @@ export interface SystemStats {
229
239
  readonly maxMs: number
230
240
  }
231
241
 
242
+ /**
243
+ * A problem the session saw while tracing a run, counted by kind and
244
+ * subject. Unlike `Debug.Lint` (from `describe()`, about the declarations
245
+ * and the session so far), a warning is raised by what one run did.
246
+ */
232
247
  export interface Warning {
233
248
  readonly code:
234
249
  | "missed-read"
@@ -247,6 +262,7 @@ export interface Warning {
247
262
  readonly lastFrame: number
248
263
  }
249
264
 
265
+ /** What `session.report()` summarizes: timing per system, warnings, held streams, lints, and population. */
250
266
  export interface Report {
251
267
  readonly frames: number
252
268
  readonly history: readonly [number, number] | undefined
@@ -254,28 +270,38 @@ export interface Report {
254
270
  readonly warnings: ReadonlyArray<Warning>
255
271
  /** Streams held past the two-frame window by a reader, or with lagged readers. */
256
272
  readonly streams: ReadonlyArray<Debug.StreamStatus>
257
- /** Static lints over the named schedules (see `describe()`). */
273
+ /** The `describe()` lints: the named schedules and what the runtime has seen. */
258
274
  readonly lints: ReadonlyArray<Debug.Lint>
259
275
  /** Live entities and entities per component now. */
260
276
  readonly population: Debug.Population
261
277
  }
262
278
 
279
+ /** What `session.system(name)` shows: the system's declared access, its stats, and its recent journal lines. */
263
280
  export interface SystemActivity {
264
281
  readonly description: Debug.SystemDescription | undefined
265
282
  readonly stats: SystemStats | undefined
266
283
  readonly recent: ReadonlyArray<Format.Line>
267
284
  }
268
285
 
286
+ /** A debug session made by `Session.make`; see the module description for each query. */
269
287
  export interface Session<S extends Schema.Any, Names extends string> {
288
+ /** Ticks the named schedule frame by frame; stops at the first failure, defect, or violated invariant. */
270
289
  readonly run: (name: Names, options?: RunOptions) => Rendered.Rendered<RunResult>
290
+ /** What happened in the kept history, one fact per line. */
271
291
  readonly journal: (filter?: JournalFilter<S>) => Rendered.Rendered<ReadonlyArray<Format.Line>>
292
+ /** Latest changes to one entity's component, and the systems whose `spawns` could have spawned it. Use `whyResource` for resources. */
272
293
  readonly why: (entity: number, component: Schema.ComponentDescriptor<S>, options?: { readonly limit?: number }) => Rendered.Rendered<ReadonlyArray<Format.Line>>
273
294
  /** Latest changes to one resource and the systems that made them. */
274
295
  readonly whyResource: (resource: Schema.ResourceDescriptor<S>, options?: { readonly limit?: number }) => Rendered.Rendered<ReadonlyArray<Format.Line>>
296
+ /** One system's declared access and recent activity. */
275
297
  readonly system: (name: string, options?: { readonly limit?: number }) => Rendered.Rendered<SystemActivity>
298
+ /** `debug.describe()`, lints first. */
276
299
  readonly describe: () => Rendered.Rendered<Debug.Description>
300
+ /** `debug.dump(filter)`: the current world. */
277
301
  readonly dump: (filter?: Debug.DumpFilter<S>) => Rendered.Rendered<Debug.WorldDump>
302
+ /** `debug.streams()`: each stream's size and readers. */
278
303
  readonly streams: () => Rendered.Rendered<ReadonlyArray<Debug.StreamStatus>>
304
+ /** Per-system timing, warnings, held streams, lints, and population since the session started. */
279
305
  readonly report: () => Rendered.Rendered<Report>
280
306
  /** Frames run by the runtime so far. */
281
307
  readonly frame: () => number
@@ -316,6 +342,12 @@ const growsSteadily = (samples: ReadonlyArray<number>): boolean => {
316
342
  const describeError = (error: unknown): { readonly kind?: unknown; readonly system?: unknown; readonly error?: unknown; readonly requirements?: unknown; readonly issues?: ReadonlyArray<{ readonly message: string }> } =>
317
343
  typeof error === "object" && error !== null ? error : {}
318
344
 
345
+ /**
346
+ * Starts a session over a runtime made with `debug: { hostClock }`: names
347
+ * `schedules` (and `describe`) on its debug handle and starts tracing. A
348
+ * name in both `schedules` and `describe` throws. Use `Lint.run` instead
349
+ * for a pass/fail lint check, and `Replay.session` to open a saved replay.
350
+ */
319
351
  export const make = <
320
352
  S extends Schema.Any,
321
353
  Root,
package/src/cli.ts CHANGED
@@ -8,12 +8,28 @@
8
8
  * prints every lint of its schedules with its fix, and exits with 1 when one
9
9
  * is a warning. Info-level lints are printed and do not fail.
10
10
  *
11
+ * It also checks simulation coverage: every module that importing `<entry>`
12
+ * loads (inside the directory of `.oxlintrc.json` in the working directory,
13
+ * outside `node_modules`) must have `ritmo/keep-simulation-headless` on in that
14
+ * config, so the oxlint simulation rules check it. Each one that does not is
15
+ * printed as `uncovered-simulation-module` and exits with 1. Only modules
16
+ * loaded by importing the entry are checked: modules imported inside
17
+ * `lintTarget` (such as render schedules passed to `describe`) or loaded later
18
+ * are host code and are not. Type-only imports never load and are not checked.
19
+ * A missing or unreadable config, one with `extends`, or one that never turns
20
+ * the rule on prints why the check was skipped and does not fail.
21
+ *
22
+ * Exit codes: 0 ok, 1 lint warning or uncovered module, 2 usage error.
23
+ * Requires Node 22.15 or later for `module.registerHooks`; on older Node it
24
+ * prints that coverage was not checked.
25
+ *
11
26
  * @module cli
12
27
  * @docGroup devtools
13
28
  */
14
29
  import { resolve } from "node:path"
15
30
  import { pathToFileURL } from "node:url"
16
31
 
32
+ import * as SimulationCoverage from "./internal/simulationCoverage.ts"
17
33
  import * as Lint from "./Lint.ts"
18
34
 
19
35
  const usage = "usage: ritmo-devtools lint <entry>\n <entry> exports lintTarget: () => { runtime, schedules, describe?, hostEvents? } (see the Lint module)"
@@ -36,7 +52,10 @@ const main = async (args: ReadonlyArray<string>): Promise<number> => {
36
52
  console.error(usage)
37
53
  return 2
38
54
  }
55
+ const loads = SimulationCoverage.recordLoads()
39
56
  const loaded: unknown = await import(pathToFileURL(resolve(entry)).href)
57
+ // Snapshot before lintTarget runs: modules it imports (render schedules to describe) are host code.
58
+ const simulationModules = loads?.()
40
59
  const make = isRecord(loaded) ? loaded["lintTarget"] : undefined
41
60
  if (typeof make !== "function") {
42
61
  console.error(`${entry} must export lintTarget: a function returning { runtime, schedules, describe? } (see the Lint module)`)
@@ -49,7 +68,14 @@ const main = async (args: ReadonlyArray<string>): Promise<number> => {
49
68
  }
50
69
  const report = Lint.run(target)
51
70
  console.log(report.text)
52
- return report.data.ok ? 0 : 1
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
74
+ }
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
53
79
  }
54
80
 
55
81
  process.exitCode = await main(process.argv.slice(2))
package/src/index.ts CHANGED
@@ -8,4 +8,5 @@ export * as Replay from "./Replay.ts"
8
8
  export * as Rendered from "./Rendered.ts"
9
9
  export * as Session from "./Session.ts"
10
10
 
11
+ /** The package's identifier. */
11
12
  export const packageTag = "devtools" as const
@@ -33,8 +33,9 @@ export interface ScheduleWindow {
33
33
  readonly maxMs: number
34
34
  }
35
35
 
36
+ /** One closed sample window, from `Collector.sample`. */
36
37
  export interface Sample {
37
- /** `performance.now()` when the window closed. */
38
+ /** The `now` passed to `sample` when the window closed. */
38
39
  readonly at: number
39
40
  readonly seconds: number
40
41
  readonly systems: ReadonlyMap<string, SystemWindow>
@@ -44,6 +45,7 @@ export interface Sample {
44
45
  readonly overheadMs: number
45
46
  }
46
47
 
48
+ /** A problem the panel flags, counted by kind and subject (a subset of the session `Warning` codes). */
47
49
  export interface Alert {
48
50
  readonly code: "system-failed" | "non-finite-value" | "discarded-messages" | "ignored-failure"
49
51
  readonly message: string