@typeonce/ritmo-devtools 0.16.1 → 0.17.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.
@@ -31,7 +31,7 @@
31
31
  import type { Debug, HostClock } from "@typeonce/ritmo"
32
32
  import type * as Inspector from "@typeonce/ritmo/Inspector"
33
33
  import type { Schema } from "@typeonce/ritmo/Schema"
34
- import type { AnyScheduleOrder, ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule"
34
+ import type { ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule"
35
35
  import type { LabelsInspector, Target as SessionTarget, ValidateLabels } from "./Session.ts"
36
36
 
37
37
  /** A fresh debug runtime, already set up, and its runnable schedules. */
@@ -44,7 +44,7 @@ export interface Target<
44
44
  Machines extends Record<string, unknown> = Record<string, unknown>
45
45
  > {
46
46
  readonly runtime: SessionTarget<S, Root, Services, Resources, Machines>
47
- readonly schedules: Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>
47
+ readonly schedules: Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any>>>
48
48
  }
49
49
 
50
50
  /** Inputs supplied to each build, including diagnostic reruns. */
package/src/Format.ts CHANGED
@@ -74,9 +74,12 @@ export const value = (input: unknown, options: ValueOptions = {}): string => {
74
74
  return current.toString()
75
75
  case "function":
76
76
  return "[fn]"
77
+ case "object":
78
+ // `null`, arrays, and objects: below.
79
+ break
77
80
  }
78
81
  if (current === null) return "null"
79
- const object = current as object
82
+ const object = current
80
83
  if (seen.has(object)) return "[cycle]"
81
84
  const prototype = Object.getPrototypeOf(object) as object | null
82
85
  const className = prototype === null || prototype === Object.prototype || Array.isArray(object)
package/src/Fuzz.ts CHANGED
@@ -54,7 +54,7 @@
54
54
  import { Clock } from "@typeonce/ritmo"
55
55
  import type { Descriptor } from "@typeonce/ritmo/Descriptor"
56
56
  import * as Result from "@typeonce/ritmo/Result"
57
- import type { AnyScheduleOrder, ExecutableScheduleDefinition, Source } from "@typeonce/ritmo/Schedule"
57
+ import type { ExecutableScheduleDefinition, Source } from "@typeonce/ritmo/Schedule"
58
58
  import type { Schema } from "@typeonce/ritmo/Schema"
59
59
  import type * as Snapshot from "@typeonce/ritmo/Snapshot"
60
60
  import type * as Checkpoint from "@typeonce/ritmo/Checkpoint"
@@ -69,7 +69,7 @@ import * as Rendered from "./Rendered.ts"
69
69
  import * as Replay from "./Replay.ts"
70
70
  import * as Session from "./Session.ts"
71
71
 
72
- type AnySchedule<S extends Schema.Any, Root> = ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>
72
+ type AnySchedule<S extends Schema.Any, Root> = ExecutableScheduleDefinition<S, any, Root, any, any>
73
73
 
74
74
  /** One fuzzed source, made with {@link input}: what `run` feeds a `snapshot()` service every frame. */
75
75
  export interface Input<Name extends string = string, Data = unknown> {
@@ -166,7 +166,7 @@ export interface Network {
166
166
  export interface Options<
167
167
  Name extends string,
168
168
  Names extends string,
169
- Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>>
169
+ Invariants extends ReadonlyArray<Invariant>
170
170
  > {
171
171
  /** The schedule to fuzz: the one ticked once per simulation step. Its name in the replay. */
172
172
  readonly schedule: Name
@@ -284,6 +284,8 @@ const violationOf = (stop: Session.Stop): Violation | InvalidOptions | undefined
284
284
  switch (stop.reason) {
285
285
  case "completed":
286
286
  case "until":
287
+ // Fuzz sessions take no labels, so a labels inspector never throws here.
288
+ case "labels-threw":
287
289
  return undefined
288
290
  case "invariant":
289
291
  return { _tag: "InvariantViolated", invariant: stop.invariant, message: stop.message }
@@ -361,7 +363,7 @@ export const run = <
361
363
  Resources extends object,
362
364
  Machines extends Record<string, unknown>,
363
365
  const Name extends keyof Schedules & string,
364
- const Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly [],
366
+ const Invariants extends ReadonlyArray<Invariant> = readonly [],
365
367
  const Net extends Network | undefined = undefined
366
368
  >(
367
369
  make: (playback: Replay.Playback) => Replay.Target<S, Root, Schedules, Services, Resources, Machines>,
package/src/Lint.ts CHANGED
@@ -42,12 +42,12 @@
42
42
  * ```
43
43
  */
44
44
  import type * as Debug from "@typeonce/ritmo/Debug"
45
- import type { AnyScheduleOrder, ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule"
45
+ import type { ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule"
46
46
  import type { Schema } from "@typeonce/ritmo/Schema"
47
47
 
48
48
  import * as Rendered from "./Rendered.ts"
49
49
 
50
- type AnySchedule<S extends Schema.Any, Root> = ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>
50
+ type AnySchedule<S extends Schema.Any, Root> = ExecutableScheduleDefinition<S, any, Root, any, any>
51
51
 
52
52
  /** What `lintTarget` returns. */
53
53
  export interface Target<S extends Schema.Any, Root> {
package/src/Replay.ts CHANGED
@@ -58,7 +58,7 @@ import type { Descriptor } from "@typeonce/ritmo/Descriptor"
58
58
  import type * as Inspector from "@typeonce/ritmo/Inspector"
59
59
  import type * as Requirement from "@typeonce/ritmo/Requirement"
60
60
  import * as Result from "@typeonce/ritmo/Result"
61
- import type { AnyScheduleOrder, ExecutableScheduleDefinition, IsPlain, Source } from "@typeonce/ritmo/Schedule"
61
+ import type { ExecutableScheduleDefinition, IsPlain, Source } from "@typeonce/ritmo/Schedule"
62
62
  import type { Schema } from "@typeonce/ritmo/Schema"
63
63
  import type * as Snapshot from "@typeonce/ritmo/Snapshot"
64
64
 
@@ -68,7 +68,7 @@ import { libraryVersion } from "./internal/version.ts"
68
68
  import * as Rendered from "./Rendered.ts"
69
69
  import * as Session from "./Session.ts"
70
70
 
71
- type AnySchedule<S extends Schema.Any, Root> = ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>
71
+ type AnySchedule<S extends Schema.Any, Root> = ExecutableScheduleDefinition<S, any, Root, any, any>
72
72
 
73
73
  /** The `@typeonce/ritmo-devtools` version written into replay files. */
74
74
  export const version = libraryVersion
@@ -174,7 +174,7 @@ export interface RecorderOptions<S extends Schema.Any, Root, Recorded extends An
174
174
  /** Saves by itself: when a tick fails or throws, and when an invariant breaks (once until it holds again). */
175
175
  readonly saveOn?: {
176
176
  readonly failure?: boolean
177
- readonly invariants?: ReadonlyArray<Invariant<Invariant.CheckInspector>>
177
+ readonly invariants?: ReadonlyArray<Invariant>
178
178
  }
179
179
  }
180
180
 
@@ -458,7 +458,7 @@ export interface Target<
458
458
 
459
459
  /** How `session` checks the replayed ticks and names what they touch. */
460
460
  export interface SessionOptions<
461
- Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly [],
461
+ Invariants extends ReadonlyArray<Invariant> = readonly [],
462
462
  Labels extends Session.LabelsInspector = never
463
463
  > {
464
464
  /**
@@ -508,7 +508,7 @@ export const session = <
508
508
  Services extends Record<string, unknown>,
509
509
  Resources extends object,
510
510
  Machines extends Record<string, unknown>,
511
- const Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly [],
511
+ const Invariants extends ReadonlyArray<Invariant> = readonly [],
512
512
  const Labels extends Session.LabelsInspector<Root> = never
513
513
  >(
514
514
  make: (playback: Playback) => Target<S, Root, Schedules, Services, Resources, Machines>,
package/src/Session.ts CHANGED
@@ -87,7 +87,7 @@ export interface Target<
87
87
  Machines extends Record<string, unknown> = Record<string, unknown>
88
88
  > {
89
89
  readonly debug: Debug.Handle<S, Root>
90
- readonly tryTick: (schedule: ExecutableScheduleDefinition<S, any, any, any, any, AnyScheduleOrder>) => Result.Result<void, unknown>
90
+ readonly tryTick: (schedule: ExecutableScheduleDefinition<S, any, any, any, any>) => Result.Result<void, unknown>
91
91
  readonly inspect: (inspector: never) => unknown
92
92
  readonly services: Services
93
93
  readonly resourceValues: Resources
@@ -95,7 +95,7 @@ export interface Target<
95
95
  }
96
96
 
97
97
  type InvariantRequirementErrors<
98
- Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>>,
98
+ Invariants extends ReadonlyArray<Invariant>,
99
99
  Services extends Record<string, unknown>,
100
100
  Resources extends object,
101
101
  Machines extends Record<string, unknown>
@@ -110,7 +110,7 @@ type InvariantRequirementErrors<
110
110
  * the runtime does not provide, naming each one.
111
111
  */
112
112
  export type ValidateInvariants<
113
- Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>>,
113
+ Invariants extends ReadonlyArray<Invariant>,
114
114
  Services extends Record<string, unknown>,
115
115
  Resources extends object,
116
116
  Machines extends Record<string, unknown>
@@ -169,11 +169,11 @@ export interface Options<
169
169
  S extends Schema.Any,
170
170
  Root,
171
171
  Names extends string,
172
- Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly [],
172
+ Invariants extends ReadonlyArray<Invariant> = readonly [],
173
173
  Labels extends LabelsInspector<Root> = never
174
174
  > {
175
175
  /** The schedules `run` can drive, by name. Also names them in traces. */
176
- readonly schedules: Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>
176
+ readonly schedules: Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any>>>
177
177
  /**
178
178
  * More schedules to include in `describe()`, its lints, and the access
179
179
  * maps, without making them runnable: typically a render schedule that
@@ -182,7 +182,7 @@ export interface Options<
182
182
  * Their services show as not provided, which is not a lint. A name
183
183
  * already in `schedules` does not compile.
184
184
  */
185
- readonly describe?: Readonly<Record<string, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>> & {
185
+ readonly describe?: Readonly<Record<string, ExecutableScheduleDefinition<S, any, Root, any, any>>> & {
186
186
  readonly [Name in NoInfer<Names>]?: "already a runnable schedule in schedules: give the described-only schedule another name"
187
187
  }
188
188
  /** Events the host publishes with `runtime.send`: written, for the lints (see `Debug.Handle.declareHostEvents`). */
@@ -502,7 +502,7 @@ export interface SteppedFrame<System> {
502
502
  export interface Session<
503
503
  S extends Schema.Any,
504
504
  Names extends string,
505
- Schedules extends Readonly<Record<Names, unknown>> = Readonly<Record<Names, ExecutableScheduleDefinition<S, any, any, any, any, AnyScheduleOrder>>>
505
+ Schedules extends Readonly<Record<Names, unknown>> = Readonly<Record<Names, ExecutableScheduleDefinition<S, any, any, any, any>>>
506
506
  > {
507
507
  /** Ticks the named schedule frame by frame; stops at the first failure, defect, or violated invariant. */
508
508
  readonly run: (name: Names, options?: RunOptions) => Rendered.Rendered<RunResult>
@@ -600,7 +600,7 @@ export const make = <
600
600
  Resources extends object,
601
601
  Machines extends Record<string, unknown>,
602
602
  const Names extends string,
603
- const Schedules extends Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>,
603
+ const Schedules extends Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any>>>,
604
604
  const Invariants extends ReadonlyArray<Invariant<Inspector.InspectorDefinition<any, string | undefined, Root, any, any>>> = readonly [],
605
605
  const Labels extends LabelsInspector<Root> = never
606
606
  >(
@@ -615,7 +615,7 @@ export const make = <
615
615
  const debug = runtime.debug
616
616
  const capacity = options.history ?? 600
617
617
  const format = options.format ?? {}
618
- const schedules = options.schedules as Readonly<Record<string, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>
618
+ const schedules = options.schedules as Readonly<Record<string, ExecutableScheduleDefinition<S, any, Root, any, any>>>
619
619
  const described = options.describe ?? {}
620
620
  debug.nameSchedules({ ...described, ...schedules })
621
621
  debug.declareHostEvents(options.hostEvents ?? [])
@@ -812,6 +812,16 @@ export const make = <
812
812
  case "overwrite":
813
813
  checkComponent(command.system, effect.component, effect.after, event.frame, effect.entity)
814
814
  break
815
+ // No component value written: nothing to check.
816
+ case "remove":
817
+ case "despawn":
818
+ case "relate":
819
+ case "unrelate":
820
+ case "relationDropped":
821
+ case "relationFailure":
822
+ case "requirementViolated":
823
+ case "staleTarget":
824
+ break
815
825
  }
816
826
  }
817
827
  }
@@ -826,6 +836,12 @@ export const make = <
826
836
  warn("transition-failed", `transition:${event.machine}:${String(event.from)}:${String(event.to)}`, `transition ${Format.transition(event)} ${event.outcome}`, event.frame)
827
837
  }
828
838
  break
839
+ // A frame starts above; schedule bounds and restores carry nothing to check.
840
+ case "frame":
841
+ case "schedule.start":
842
+ case "schedule.end":
843
+ case "restore":
844
+ break
829
845
  }
830
846
  }
831
847
  /** The last `failure.ignored` event seen, for `run` to stop on. */
@@ -1042,7 +1058,7 @@ export const make = <
1042
1058
  if (!result.ok) {
1043
1059
  ended = { result: Result.failure(result.error) }
1044
1060
  stepping = undefined
1045
- return Result.failure(failureStop(result.error, frame) as StepStop)
1061
+ return Result.failure(failureStop(result.error, frame))
1046
1062
  }
1047
1063
  if (result.value.ended) stepping = undefined
1048
1064
  return Result.success(result.value)
package/src/cli.ts CHANGED
@@ -21,10 +21,10 @@
21
21
  * A missing or unreadable config, one with `extends`, or one that never turns
22
22
  * the rule on prints why the check was skipped and does not fail.
23
23
  *
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.
24
+ * Last, it notes each Ritmo skill (`ritmo`, `ritmo-prototype`) the project
25
+ * does not link from the installed package (`.agents/skills/<skill>` or
26
+ * `.claude/skills/<skill>`, see `SETUP.md`), or holds a copy of it that goes
27
+ * stale on upgrade. The note never fails the lint.
28
28
  *
29
29
  * `verify` imports `<entry>` (a module exporting `replayTarget`, the
30
30
  * `make(playback)` factory `Replay.session` takes), plays the replay file in
@@ -1,53 +1,75 @@
1
1
  /**
2
2
  * The skill check for the `ritmo-devtools lint` CLI (Node only): whether the
3
- * project links the Ritmo skill from the installed package, as `SETUP.md`
4
- * step 2 says, so the game's agent reads the playbooks of the installed
3
+ * project links each Ritmo skill from the installed package, as `SETUP.md`
4
+ * step 2 says, so the game's agent reads the skills of the installed
5
5
  * version. It is a note: it never fails the lint, since where an agent reads
6
6
  * skills from is the project's choice.
7
7
  */
8
8
  import { lstatSync, realpathSync } from "node:fs"
9
9
  import { join, sep } from "node:path"
10
10
 
11
+ /** The skills `@typeonce/ritmo` ships, with what an agent misses without each. */
12
+ const skills = {
13
+ ritmo: "reads the playbooks for this Ritmo version",
14
+ "ritmo-prototype": "can prototype a mechanic with this Ritmo version"
15
+ } as const
16
+
17
+ export type Skill = keyof typeof skills
18
+
11
19
  /** The folders agents read skills from, relative to the working directory. */
12
- const folders = [".agents/skills/ritmo", ".claude/skills/ritmo"] as const
20
+ const folders = (skill: Skill) => [`.agents/skills/${skill}`, `.claude/skills/${skill}`] as const
13
21
 
14
22
  export type SkillLink =
15
- | { readonly _tag: "Linked"; readonly path: string }
16
- | { readonly _tag: "Copied"; readonly path: string }
17
- | { readonly _tag: "Missing" }
23
+ | { readonly _tag: "Linked"; readonly skill: Skill; readonly path: string }
24
+ | { readonly _tag: "Copied"; readonly skill: Skill; readonly path: string }
25
+ | { readonly _tag: "Missing"; readonly skill: Skill }
18
26
 
19
- // A link into an installed `@typeonce/ritmo` package's skill: `node_modules/@typeonce/ritmo/skills/ritmo`, or pnpm's store path to it.
20
- const isInstalledSkill = (path: string): boolean =>
21
- path.includes(`${sep}node_modules${sep}`) && path.endsWith(join("@typeonce", "ritmo", "skills", "ritmo"))
27
+ // A link into an installed `@typeonce/ritmo` package's skill: `node_modules/@typeonce/ritmo/skills/<skill>`,
28
+ // pnpm's store path to it, or wherever the project's own `node_modules/@typeonce/ritmo` resolves (a `link:` checkout).
29
+ const isInstalledSkill = (cwd: string, path: string, skill: Skill): boolean => {
30
+ if (path.includes(`${sep}node_modules${sep}`) && path.endsWith(join("@typeonce", "ritmo", "skills", skill))) return true
31
+ try {
32
+ return path === realpathSync(join(cwd, "node_modules", "@typeonce", "ritmo", "skills", skill))
33
+ } catch {
34
+ return false
35
+ }
36
+ }
22
37
 
23
- /** Where the skill is in `cwd`: linked from the installed package, copied in, or missing. */
24
- export const check = (cwd: string): SkillLink => {
38
+ const checkSkill = (cwd: string, skill: Skill): SkillLink => {
25
39
  let copied: string | undefined
26
- for (const folder of folders) {
40
+ for (const folder of folders(skill)) {
27
41
  const path = join(cwd, folder)
28
42
  try {
29
43
  const stat = lstatSync(path)
30
- if (stat.isSymbolicLink() && isInstalledSkill(realpathSync(path))) return { _tag: "Linked", path: folder }
44
+ if (stat.isSymbolicLink() && isInstalledSkill(cwd, realpathSync(path), skill)) return { _tag: "Linked", skill, path: folder }
31
45
  copied ??= folder
32
46
  } catch {
33
47
  // Not there (or a dangling link): look at the next folder.
34
48
  }
35
49
  }
36
- return copied === undefined ? { _tag: "Missing" } : { _tag: "Copied", path: copied }
50
+ return copied === undefined ? { _tag: "Missing", skill } : { _tag: "Copied", skill, path: copied }
37
51
  }
38
52
 
39
- /** The CLI text for a skill check: nothing when linked, a note otherwise. */
40
- export const format = (link: SkillLink): string => {
53
+ /** Where each skill is in `cwd`: linked from the installed package, copied in, or missing. */
54
+ export const check = (cwd: string): ReadonlyArray<SkillLink> =>
55
+ (Object.keys(skills) as ReadonlyArray<Skill>).map((skill) => checkSkill(cwd, skill))
56
+
57
+ const formatOne = (link: SkillLink): string => {
58
+ const installed = `node_modules/@typeonce/ritmo/skills/${link.skill}`
41
59
  switch (link._tag) {
42
60
  case "Linked":
43
61
  return ""
44
62
  case "Missing":
45
- return `note skill-not-linked\n`
46
- + ` No ${folders.join(" or ")} links to node_modules/@typeonce/ritmo/skills/ritmo.\n`
47
- + ` Link it (SETUP.md step 2) so your agent reads the playbooks for this Ritmo version.`
63
+ return `note skill-not-linked ${link.skill}\n`
64
+ + ` No ${folders(link.skill).join(" or ")} links to ${installed}.\n`
65
+ + ` Link it (SETUP.md step 2) so your agent ${skills[link.skill]}.`
48
66
  case "Copied":
49
67
  return `note skill-copied ${link.path}\n`
50
- + ` This is a copy of the Ritmo skill, or a link to somewhere else: it goes stale on the next upgrade.\n`
51
- + ` Replace it with a link to node_modules/@typeonce/ritmo/skills/ritmo (SETUP.md step 2).`
68
+ + ` This is a copy of the ${link.skill} skill, or a link to somewhere else: it goes stale on the next upgrade.\n`
69
+ + ` Replace it with a link to ${installed} (SETUP.md step 2).`
52
70
  }
53
71
  }
72
+
73
+ /** The CLI text for the skill checks: nothing when every skill is linked, a note per skill otherwise. */
74
+ export const format = (links: ReadonlyArray<SkillLink>): string =>
75
+ links.map(formatOne).filter((text) => text !== "").join("\n")
@@ -3,4 +3,4 @@
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.16.1"
6
+ export const libraryVersion = "0.17.0"