@typeonce/ritmo-devtools 0.9.0 → 0.10.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 +264 -0
- package/README.md +33 -9
- package/dist/Replay.d.ts +1 -1
- package/dist/Replay.d.ts.map +1 -1
- package/dist/cli.js +28 -1
- package/dist/cli.js.map +1 -1
- package/dist/internal/simulationCoverage.d.ts +18 -0
- package/dist/internal/simulationCoverage.d.ts.map +1 -0
- package/dist/internal/simulationCoverage.js +135 -0
- package/dist/internal/simulationCoverage.js.map +1 -0
- package/dist/internal/version.d.ts +1 -1
- package/dist/internal/version.d.ts.map +1 -1
- package/dist/internal/version.js +1 -1
- package/dist/internal/version.js.map +1 -1
- package/package.json +4 -3
- package/src/cli.ts +27 -1
- package/src/internal/simulationCoverage.ts +136 -0
- package/src/internal/version.ts +1 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
# @typeonce/ritmo-devtools
|
|
2
|
+
|
|
3
|
+
## 0.10.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 7002f4d: **Everything a game's agent needs now ships with the packages, and `ritmo-devtools lint` reports simulation modules the lint rules miss.**
|
|
8
|
+
|
|
9
|
+
- **Breaking: `ritmo-devtools lint` fails on an uncovered simulation module.** Every module the entry loads that the `ritmo/keep-simulation-headless` override in `.oxlintrc.json` does not cover is reported as `uncovered-simulation-module`, and the command exits 1. Add the module (or its folder) to the simulation override's `"files"`, or stop importing values from it. Modules loaded only inside `lintTarget` are not checked. Requires Node 22.15 or newer (`engines.node` is now `>=22.15`).
|
|
10
|
+
- **An agent skill ships with `@typeonce/ritmo`** in `skills/ritmo/SKILL.md`, for every change: where the docs are, and principles for where a game's code and state belong. Link it into the folder the game's agent reads skills from, for example `ln -s ../../node_modules/@typeonce/ritmo/skills/ritmo .agents/skills/ritmo`. `SETUP.md` in `@typeonce/ritmo` is the one-time setup: the base packages and checks every game uses, the add-ons, and linking the skill.
|
|
11
|
+
- **Every package ships its `CHANGELOG.md`.** The upgrade notes for 0.8.0 and 0.9.0 are in the `@typeonce/ritmo` changelog.
|
|
12
|
+
- **JSDoc corrections.** Examples no longer provide randomness or time as services (use the `Random` resource and `Clock`), the `Command` module example declares its commands, inspector docs state that `added`/`changed` reads report records since the inspector's previous evaluation, and every example uses prefixed names (`"Game/Position"`). Guidance that lived only in the repository's guides (spawn order, `ReadonlyValue` helpers, re-entering a state, `thisTick` and plugin systems, service effects and rollback) is now in the JSDoc.
|
|
13
|
+
- Package READMEs link other packages' READMEs by GitHub URL, so the links work on npm.
|
|
14
|
+
|
|
15
|
+
### Patch Changes
|
|
16
|
+
|
|
17
|
+
- Updated dependencies [7002f4d]
|
|
18
|
+
- Updated dependencies [388a696]
|
|
19
|
+
- @typeonce/ritmo@0.10.0
|
|
20
|
+
|
|
21
|
+
## 0.9.0
|
|
22
|
+
|
|
23
|
+
### Patch Changes
|
|
24
|
+
|
|
25
|
+
- c2c32e0: **API additions from a second review.**
|
|
26
|
+
|
|
27
|
+
- **Writes take what reads return.** `set`, `update`, `emit`, `runtime.send`, `Command.entry`, and plain `[Descriptor, value]` entries accept `ReadonlyValue<T>`, so a value read from one cell (deeply readonly) can be written to another without a copy or a cast.
|
|
28
|
+
- **`Clock.durationOfSteps(step, n)`** builds a duration from a whole number of steps, instead of a round trip through seconds and `durationRaw`. A literal zero, negative, or fractional count does not compile; a computed one throws.
|
|
29
|
+
- **`Game.Entity.id(handle)`** returns the entity id a handle names, so games no longer store the id beside the handle.
|
|
30
|
+
- **Save migrations.** `Game.Runtime.make({ saves: Snapshot.migrations(Snapshot.migration(1, ...), Snapshot.migration(2, ...)) })`: snapshots carry a `gameVersion` (the last step; 0 without migrations and for older saves), and `restore` runs every step after the save's version in order, checking the structure after each, before validating as usual. A save newer than the last step fails with `NewerGameVersion`. Steps must be numbered 1, 2, 3, ... in order (checked at compile time and at runtime).
|
|
31
|
+
- **Docs** now state that a system does not see its own writes as changes (it does see its own events), how long `Condition.stateChanged` holds, that a sub-state value set at the marker its parent leaves is dropped, and that `restore` keeps a current resource the save lacks.
|
|
32
|
+
|
|
33
|
+
- d47a4f9: **Runtime fixes from a review of 0.8.0.** No API changes; each fix restores what the docs already promised.
|
|
34
|
+
|
|
35
|
+
- **Sub-states enter with their parent.** A sub-state now gets its entry value at the parent's commit, before any `onEnter` schedule runs. A failing `onEnter` of the parent no longer leaves it without a value (`inState` false and `set` failing with `SubStateInactive` until the parent came back), and its `despawnOnEnter` scopes no longer despawn what the parent's `onEnter` just spawned. The `onEnter` schedules still run parents first.
|
|
36
|
+
- **A queued transition survives a transition schedule setting the same machine.** A value queued before `applyStateTransitions(...)` is committed there even when an `onEnter` / `onExit` of an earlier machine also calls `set` on it; that newer value waits for the next marker.
|
|
37
|
+
- **`snapshot` and `restore` throw while a schedule is running**, like `send`. A restore from a system let its queued spawns overwrite restored entities, and a snapshot captured writes a failing system then rolled back. `tryTick` now sets the same guard, so `send` inside `tryTick` throws too.
|
|
38
|
+
- **`restore` rejects an unknown scope name** with the new `UnknownScope` error, instead of putting entities in a scope nothing can name.
|
|
39
|
+
- **`describe()` counts reads inside `Query.anyOf`**, so `component-never-read` no longer fires for a component read only through `anyOf`, and `read-before-write` sees it. A system placed directly and under `Schedule.when` / `pauseWhen` is one entry with both placements and the conditions of each.
|
|
40
|
+
- **`Collide2` stops a circle that starts exactly touching a wall** and moves into it, instead of moving it through the wall: `sweepCircleBox` / `sweepCircleBoxes` now report a hit at time 0, and `moveCircle` blocks. This happens whenever a game places a body exactly at a wall without a skin (a snapped spawn point, or a projectile set to a sweep's contact point). Moving away from the wall or sliding along it is unchanged. A game that fingerprints its simulation will see fights that touched a wall this way play differently: re-record the fingerprints with the upgrade.
|
|
41
|
+
- **Replays carry input into their window.** A replay saved after unchanged input (holding a direction longer than `keep`) had no input on its first ticks and handed systems `undefined` when played.
|
|
42
|
+
- **`Session.run` stops with `invariant-threw`** when an invariant throws, naming the invariant and the error, instead of throwing out of `run` and losing the run's text.
|
|
43
|
+
- The `Snapshot` docs now say that unread `runtime.send` events survive a restore, as they always did.
|
|
44
|
+
|
|
45
|
+
- 330246e: **Safety follow-ups from a second review.** Each closes a way a game could go wrong silently; see Upgrading under 0.9.0 in the `@typeonce/ritmo` CHANGELOG.md.
|
|
46
|
+
|
|
47
|
+
- **A `SpawnedId` is valid only in the run that spawned it.** Kept in a closure or resource and passed to `commands.despawn` / `commands.remove` in a later run, it could name an entity despawned meanwhile whose id was reused. Such a command is now skipped, traced as a `staleTarget` effect, and reported by the new `stale-target` lint (`Debug.StaleTarget`). Keep the entity id or a handle and resolve it through a query.
|
|
48
|
+
- **`any` and `never` are not descriptor values.** `Descriptor.Component<any>()`, `Resource`, `Event`, `Service`, and the transient variants fail at the constructor: `any` turned off every check on the descriptor, and `never` erased the fragment listing it.
|
|
49
|
+
- **A saved component cannot require a transient one.** `Schema.bind` rejects `Schema.requires(Ghost, Trail)` when only `Trail` is transient: a restore brought `Ghost` back without it. A transient requirer may still require a transient component.
|
|
50
|
+
- **Queries with `added` / `changed` filters have no lookups.** `get`, `getHandle`, `single`, `children`, and `descendants` failed with `QueryMismatch` whenever the target had not changed since the system's previous run; they no longer compile there. Declare a second query without filters to resolve entities. `each()` and `singleOptional()` are unchanged. The handle types are now `QueryIteration` and `QueryLookups` (`QueryHandle` combines them).
|
|
51
|
+
- **A transition's exit phase is one transaction.** When a system in `onExit` / `onTransition` fails, everything the phase did (component writes, resources, events, queued next states and commands, stream positions) is undone and the transition stays queued, so the retry starts from the same state instead of running the earlier exit systems twice. These schedules can no longer contain `applyDeferred()`.
|
|
52
|
+
- **A service or machine provided twice does not compile.** `Runtime.services` / `Runtime.machines` kept the last of two provisions; the second now fails, naming it.
|
|
53
|
+
- **`RenderSync` recovers from dropped removals.** After a pause longer than a stream keeps entries, the removals it missed left nodes on screen; when its removal stream reports `lagged()`, it now destroys every node whose entity no longer matches. Give each `RenderSync.system` its own registry.
|
|
54
|
+
- **New lint `stream-loss-unread`.** On a debug runtime, a reader of events, transition events, removed, despawned, or relation failures that lost entries without checking `lagged()` is a warning, and one reading under `pauseWhen` without checking it is noted (`Debug.StreamLoss`).
|
|
55
|
+
|
|
56
|
+
- Updated dependencies [c2c32e0]
|
|
57
|
+
- Updated dependencies [9cca78b]
|
|
58
|
+
- Updated dependencies [6c09482]
|
|
59
|
+
- Updated dependencies [ecfd0f1]
|
|
60
|
+
- Updated dependencies [d47a4f9]
|
|
61
|
+
- Updated dependencies [330246e]
|
|
62
|
+
- Updated dependencies [7f2b2dd]
|
|
63
|
+
- @typeonce/ritmo@0.9.0
|
|
64
|
+
|
|
65
|
+
## 0.8.0
|
|
66
|
+
|
|
67
|
+
### Minor Changes
|
|
68
|
+
|
|
69
|
+
- 0b22113: **Immutable components.** `Descriptor.Component`, `ConstructedComponent`, and `TransientComponent` take an optional `{ immutable: true }` for data that says what an entity is (a kind, a team, a tile). Queries can only read such a component: `Game.Query.write(Kind)` is a compile error naming the fix (`replace it with commands.insert(entity, Game.Command.entry(Kind, ...))`), and it throws the same message when an erased type reaches it. Replacing the component with `commands.insert` still marks it changed for `Game.Query.changed(Kind)`. Descriptors declared without the option keep their exact type.
|
|
70
|
+
|
|
71
|
+
- `Descriptor.isImmutable(descriptor)` reports the option at runtime.
|
|
72
|
+
- `describe()` component entries gain `immutable`, and the text report prints it.
|
|
73
|
+
|
|
74
|
+
- a0fac0a: **`Game.Query.anyOf`.** `anyOf(...filters)` takes two or more `added` / `changed` filters and matches an entity once when any of them passes since the reading system's previous run, for example to redraw when either the position or the sprite changed. Filters listed side by side in `filters: [...]` still all have to pass. `anyOf` does not nest, and `Game.Condition.check` rejects it like every other change filter.
|
|
75
|
+
|
|
76
|
+
- `RenderSync.system` now builds one query per sync system (an `anyOf` of its added and changed filters) instead of one query per trigger plus deduplication.
|
|
77
|
+
- `Debug.QueryDescription` gains `anyOf` (one entry per `anyOf` filter, with its `added` and `changed` components); code that builds a `QueryDescription` by hand must add it. The text report prints it as `any of (...)`, and Monitor counts its components as reads.
|
|
78
|
+
|
|
79
|
+
- 0b22113: **Breaking: required components; `insert` and `remove` take a query match.** See Upgrading under 0.8.0 in the `@typeonce/ritmo` CHANGELOG.md.
|
|
80
|
+
|
|
81
|
+
A fragment declares what always comes together: `Schema.fragment({ components: { ... }, requires: [Schema.requires(Player, Position, Velocity)] })`. Requirements chain, may name components of other fragments of the same `Schema.bind` (checked there), and are never filled in with defaults.
|
|
82
|
+
|
|
83
|
+
- `commands.spawn` / `spawnIn` reject a draft missing a required component, naming the requirer and the missing component. Drafts may be partial while they are built with `Game.Command.extend`.
|
|
84
|
+
- `Game.System.spawns(Player)` also allows what `Player` requires, transitively, so hand-kept lists of a draft's components are no longer needed.
|
|
85
|
+
- **Breaking:** `commands.remove` takes `match.entity` (or the id `commands.spawn` returned in this run), never a raw id, and removes several components in one call: `commands.remove(match.entity, Player, Velocity)`. Removing a required component compiles only when its requirers are removed in the same call or excluded by the query's `without`.
|
|
86
|
+
- `commands.insert` takes `match.entity` (or a spawned id) as well as a raw id: the target's query proof plus the entries inserted together must cover what the inserted components require. A raw id still inserts components without requirements.
|
|
87
|
+
- When commands are applied, a spawn, insert, or remove that would break a requirement (a query proof gone stale within one flush, erased types) is skipped whole, traced as a `requirementViolated` effect, and reported by the new `requirement-violated` lint.
|
|
88
|
+
- `restore` rejects a saved entity missing a required component with the new `MissingRequiredComponent` error. Requirements on transient components are not checked there, since saves skip them.
|
|
89
|
+
- `describe()` component entries gain `requires`. `Command.InternalWorld` now inserts and removes several components per call (`insertComponents`, `removeComponents`), and `spawnEntity` reports whether it spawned.
|
|
90
|
+
|
|
91
|
+
- a0fac0a: **Resource change detection.** `Game.System.changedResource(R)` declares a resource read whose view adds `changed()`: whether a committed write left a different value since this system's previous completed run. Use it for work worth doing only when a value moved, such as rewriting a HUD label, instead of keeping a "last value" in `local`.
|
|
92
|
+
|
|
93
|
+
- A write of an equal value is not a change: primitives compare with `Object.is`, plain objects and arrays by their entries, other objects by reference. This differs from `Game.Query.changed`, where every component write counts.
|
|
94
|
+
- The first run reports `true`. Writes rolled back by a failed system are not changes, a system does not see its own writes as changes, and a reader skipped by a run condition sees the change when it runs again.
|
|
95
|
+
- `Game.Condition.check` rejects it ("changedResource consumes a per-reader cursor, which a check does not have: use Game.System.readResource here, and changedResource in the gated system"); writing a resource in a check now names `readResource` too.
|
|
96
|
+
- `Game.System.thisTick(changedResource(R))` joins the compile-time and runtime order checks.
|
|
97
|
+
- `describe()` lists these reads in `SystemDescription.resources.changed` (they stay in `reads`), the text report prints them as "reads resources when changed", and the new `resource-changed-never-written` lint warns when no described system writes a resource read with `changedResource`.
|
|
98
|
+
|
|
99
|
+
- a580c9c: **Scopes despawned by state changes.** `Game.EntityScope(name, { despawnOnExit: [Flow, "Playing"] })` (or `despawnOnEnter`) despawns every member of the scope when `applyStateTransitions(...)` commits that state change: after the `onExit` schedules, which still see the members, and before the `onEnter` schedules, so what they spawn survives. A restart no longer needs a despawn system, a `despawnsScope` permission, and an `applyDeferred()` placed between despawn and respawn. The despawn goes through the normal path (`readDespawned`, `RenderSync`, hierarchy cascades) and appears in the trace as `despawnScope <name>` from `onExit(<machine>=<state>)`.
|
|
100
|
+
|
|
101
|
+
- Scopes register with the game when defined, so the runtime knows every trigger; scope names are now unique per game (`Duplicate entity scope name`).
|
|
102
|
+
- A state that does not exist, or a machine of another game, fails to compile. `Game.Condition.inState` and `stateChanged` now reject another game's machine where the condition is built, with the message `<machine> is a state machine of another game: use a machine defined with this game's Game.StateMachine(...)`.
|
|
103
|
+
- New lint `scope-trigger-never-applied`: a trigger whose machine the runtime does not provide, whose next state no described system queues, or that no described schedule applies. `describe()` gains `scopes` (each with its triggers), printed in the text report.
|
|
104
|
+
|
|
105
|
+
- a580c9c: **Sub-states.** `Game.StateMachine(name, values, { within: [Parent, state] })` declares a machine that exists only while `Parent` is in `state`. Each time the parent enters that state, the sub-state enters the value given to `Game.Runtime.machine(...)`; when the parent leaves it, the sub-state's `onExit` schedules run before the parent's and it loses its value. `Game.Condition.inState(Sub, x)` therefore implies the parent's state, replacing an `and(inState(Parent, ...), inState(Sub, ...))` on every system and the `onExit` system that reset the second machine.
|
|
106
|
+
|
|
107
|
+
- For sub-states only: `machines.x.get()` is `Value | undefined`, `nextMachines.x.set` / `setIfChanged` return a `Result` failing with `SubStateInactive` (nothing is queued) while the parent is elsewhere, and transition snapshots use `undefined` for the side where it does not exist. Top-level machines keep their exact types.
|
|
108
|
+
- Snapshots leave out an inactive sub-state; `restore` rejects a saved sub-state value whose parent is elsewhere with the new `InactiveSubState` error, and enters the entry value when a save has the parent in its state but no sub-state value.
|
|
109
|
+
- `describe()` machine entries gain `provided` and `within`; the text report and traces print a missing value as `(inactive)`. `Debug.TransitionEvent` `from` / `to` may be `undefined`.
|
|
110
|
+
- The unused `Machine.MachineView`, `NextMachineView`, `TransitionView`, and `TransitionEventView` interfaces are removed; system views are `System.MachineReadView`, `NextMachineWriteView`, `TransitionReadView`, and `TransitionEventReadView`.
|
|
111
|
+
|
|
112
|
+
### Patch Changes
|
|
113
|
+
|
|
114
|
+
- Updated dependencies [0b22113]
|
|
115
|
+
- Updated dependencies [a0fac0a]
|
|
116
|
+
- Updated dependencies [0b22113]
|
|
117
|
+
- Updated dependencies [a0fac0a]
|
|
118
|
+
- Updated dependencies [a580c9c]
|
|
119
|
+
- Updated dependencies [a580c9c]
|
|
120
|
+
- @typeonce/ritmo@0.8.0
|
|
121
|
+
|
|
122
|
+
## 0.7.0
|
|
123
|
+
|
|
124
|
+
### Minor Changes
|
|
125
|
+
|
|
126
|
+
- 84eac37: Add simulation time through `Clock.hz`, a validated `Clock.resource`, and a schedule built by `Clock.system`. A held clock sets `dt` to zero and preserves its step. Durations carry their rate, reject sub-step literals, and validate seconds from data through `durationRaw`. Restoring a clock saved at another rate fails validation.
|
|
127
|
+
|
|
128
|
+
`FixedLoop.start` and `Replay.recorder` take `step: Clock.hz(...)` instead of `stepSeconds`, sharing one fixed step with the simulation. `HostClock` supplies host timing through an injected contract; browser hosts can use `BrowserHostClock.make(window)`. Debug runtimes use `debug: { hostClock }` and the monitor requires an explicit DOM host.
|
|
129
|
+
|
|
130
|
+
Add `Determinism.check` over a factory of fresh headless debug runtimes and scripted inputs. It compares all component and resource values, including transient values, and reruns the first differing frame to name its system or schedule marker. Execution failures, defects, and reused runtimes fail explicitly. This checks repeatability on the current engine.
|
|
131
|
+
|
|
132
|
+
New replay files and the lint CLI use the Ritmo name.
|
|
133
|
+
|
|
134
|
+
- 7ebd9af: One way to do each thing. Breaking changes, with no deprecated aliases:
|
|
135
|
+
|
|
136
|
+
- **Systems fail with `Result.failure(error)`.** The `Fx` module is removed (`Fx.fail`, `succeed`, `sync`, `map`, `flatMap`, `access`, `accessService`, `provide`, `runSync`). A system returns nothing or a `Result`; returning `Result.failure(error)` rolls back its ECS writes, drops its commands and events, and types `error` into the tick result exactly like `Fx.fail` did. Replace `return Fx.fail(e)` with `return Result.failure(e)`; a returned lookup failure (`if (!found.ok) return found`) also works. `SystemDefinition` and `Schema.BoundSystem` lose their success type parameter: `SystemDefinition<Spec, E, Root, Name, Needs>`, `BoundSystem<S, Root, Spec, E, Name, Needs>`.
|
|
137
|
+
- **`Feature` is removed** (`Schema.Feature.define` / `compose`). A plugin is a function `(Game, options) => System | Schedule`, like `RenderSync.system(Game, ...)`; list every fragment in one `Schema.bind(...)`.
|
|
138
|
+
- **`Schema.merge` is removed**: use `Schema.bind(A, B, ...)`.
|
|
139
|
+
- **A descriptor owns its validator.** `Definition` is removed: validate through the constructed descriptor (`Game.Command.entryRaw(Position, raw)`, for example in a draft built once at module load) or call the constructor (`Vector2.result(raw)`). `Command.entryResult` is removed: `entryRaw` is the one way to validate raw input at spawn. `setResult` / `updateResult` are removed from write cells: use `setRaw` / `updateRaw` on constructed descriptors. `Brand` is documented as a tool for packages that author validated value types.
|
|
140
|
+
- **`Descriptor.State` is renamed `Descriptor.EntityState`** (per-entity state, not to be confused with the game-wide `Game.StateMachine`). Related names follow: `EntityStateDescriptor`, `EntityStateValue`, `EntityStateTransitions`, `isEntityState`, `EntityStateWriteCell`, and the transition failure `EntityStateMismatchError` with `_tag: "EntityStateMismatch"` and `component` (was `state`) naming the component.
|
|
141
|
+
- **Silent failures are loud.** `RemovedReadView` and `DespawnedReadView` gain `lagged()`, like event readers. `describe()` reports a `relation-failure-never-read` warning for a relation that commands have related or reordered while no described system reads its failures.
|
|
142
|
+
- **Devtools invariants are typed.** `Invariant.make(name, () => ...)` is replaced by `Invariant.fromInspector(Game.Inspector(name, access, check))`, where `check` returns a violation message or `undefined`. `Session.make` rejects at compile time an invariant that reads a resource, service, or machine the runtime does not provide. `Runtime.ValidateInspector` is exported for tools like this.
|
|
143
|
+
- JSDoc now states when to use each of `EntityScope` / `Hierarchy`, `when` / `pauseWhen` (on a system and on `Schedule.when` / `Schedule.pauseWhen`), `tryTick` / `tick`, and `Game.StateMachine` / `Descriptor.EntityState`.
|
|
144
|
+
- **`Game.System.thisTick(read)`**: wraps `readEvent(E)` or `readResource(R)` to require that every system writing it runs earlier in the same `runtime.tick(...)` call. `tick` checks it at compile time ("ApplyDamage needs Damage from this tick, but its writer UpdateFrostFields runs after it: move ..."), and calls whose order is not statically known (a read with no writer compiles); `tryTick` checks it at runtime (`TickOrderViolation`) and `describe()` reports `this-tick-order`. Schedule types gain a sixth parameter (`Order`); constraint positions accept any with `Schedule.AnyScheduleOrder`.
|
|
145
|
+
- **Lint as a tool.** `ritmo-devtools lint <entry>` (and `Lint.run` in code) prints every lint of a game's schedules with its fix, and exits 1 on warnings (info does not fail). The entry module exports `lintTarget: () => { runtime, schedules, describe? }`. `Debug.Lint` gains `fix`, the change that resolves it.
|
|
146
|
+
- **Replays.** `Replay.recorder(runtime, { schedule, name, keep, stepSeconds, sink, hostClock, saveOn? })` keeps the last seconds of one schedule's ticks (periodic snapshots, source-service values as changes, host sends) and saves them through a `Replay.Sink`: `Replay.memorySink`, `ReplayNodeSink` (files), `ReplayViteSink` with `ReplayVitePlugin` (dev server), and Monitor's new `replay` option ("Save replay" button). A recorded schedule whose services are not plain-data `snapshot()` sources or plain data is a compile error. `Replay.session`, `verify`, and `extract` replay a file headless. Core's `Debug.Handle` gains `observeHost` (tick start/end and sends, without tracing).
|
|
147
|
+
- **`debug` takes a host clock: `debug: { hostClock }`** (`debug: true` is removed). Core and devtools read no platform clock or globals: the new core `HostClock` module is the injected contract (`HostClock.standard` is `Date.now`, `HostClock.test()` is a manual clock at 0 with `adjust(ms)` returning a `Result`, `HostClock.elapsed` clamps negative durations), and `BrowserHostClock.make(window)` in the browser package reads `window.performance`. A value that may be `undefined` (`debug: import.meta.env.DEV ? { hostClock } : undefined`) gives an optional `debug` handle that code must check, so a dev-only debug runtime needs no second runtime type; omitting `debug` attaches nothing. Devtools take the clock and host explicitly: `Session.make(runtime, { ..., hostClock })`, `Replay.recorder(runtime, { ..., hostClock })`, a replay target returns `hostClock`, and `Monitor.attach(runtime, { ..., host: window })`. With `HostClock.test()` every timing is 0, so session and replay text is identical across runs.
|
|
148
|
+
- **Lookups go through declared queries.** `lookup.get(id, Q)`, `lookup.getHandle(h, Q)`, `lookup.childMatches(id, R, Q)`, and `lookup.descendantMatches(id, R, Q)` are removed: they let a system read or write components it never declared. Use `queries.x.get(id)`, `queries.x.getHandle(h)` (same intent proof), `queries.x.children(id, R)`, and `queries.x.descendants(id, R, options)` on a query in the spec. `lookup` keeps the id-returning helpers (`related`, `relatedSources`, `parent`, `ancestors`, `descendants`, `root`).
|
|
149
|
+
- **Systems declare their commands.** A system has `commands` only when its spec declares them: `commands: Game.System.commands(Game.System.spawns(Position, Enemy), Game.System.inserts(Stunned), Game.System.removes(Stunned), Game.System.despawns(Enemy), Game.System.despawnsScope(Level), Game.System.relates(ChildOf))`. Each method exists only with its permission, and only for what it lists; errors name the fix ("Noise is not declared in this system's commands: add it to Game.System.spawns(...)"). Drafts built from spread arrays or conditional entries are checked over every component they may hold. `despawn` takes `match.entity` from a query proving one of the `despawns` components, or the `SpawnedId` that `spawn` / `spawnIn` returned in the same run, never a raw id. The draft builder `Game.Command.insert` is renamed `Game.Command.extend` (it clashed with `commands.insert`). Spawn-time relations in a draft (`Game.Command.relate(draft, ...)`) are part of the spawn and need no `relates`.
|
|
150
|
+
- **`Game.System.thisTick(query)`**: a query that needs this tick's command changes. Its writers are systems whose declared commands can change what it matches (`spawns` covering every component it requires, or `inserts` / `removes` of any component it names, optional slots, `with`, `without`, and filters included; `despawns` never count). `runtime.tick(...)` rejects a writer that runs after the reader, and one before it with no `applyDeferred()` in between ("AimAtNewest needs this tick's commands for queries.enemies, but SpawnWave queues them with no applyDeferred() in between: add Game.Schedule.applyDeferred() after SpawnWave"). Transition bundles count at their `applyStateTransitions(...)` step (which applies queued commands first), as if every schedule in them runs, markers inside included; this now also holds for event and resource reads. `tryTick` and the `this-tick-order` lint check the same at runtime (`OrderIssue.kind` gains `"unflushedWriter"`); `tryTick` checks each schedule once. Transition schedules and bundles carry their order (a sixth / seventh type parameter, defaulting to any order).
|
|
151
|
+
- **Fix: a `Game.Query(...)` written inline in a spec keeps omitted lists empty.** Without `with` (or `without`, `filters`, relation lists) an inline query in `queries: { ... }` took the spec's widened list type (every component), so it proved every component to `despawn` and `getHandle`. Omitted lists are now `[]` wherever the query is written.
|
|
152
|
+
- **Devtools read declared command permissions.** `describe()` lists each system's permissions (`SystemDescription.commands`) and indexes `spawns` / `inserts` / `removes` as component writers, so `component-never-read` covers components only commands write. `relation-failure-never-read` also fires for a declared `relates` before any command ran. New `command-permission-unused` lint (info): on a debug runtime, "X may insert C but never did in this session" for systems that ran. `session.why(entity, Component)` names the systems whose `spawns` could have spawned the entity.
|
|
153
|
+
- **Ignored tick failures are reported (debug only).** A failed `tick` / `tryTick` result whose `ok` nobody read is reported as a `failure.ignored` trace and host event (`frame`, `schedule`, `system`, `error`, `skipped`: the systems that did not run, `when: "next-tick" | "session-end"`) at the start of the next tick, or by the new `debug.checkIgnoredFailures()`. Core emits only. Devtools: `Session.run` stops with `reason: "ignored-failure"`, `report()` / `journal()` show "tick failure ignored: Load failed with "level file missing"; 2 later systems did not run (not read before the next tick)", the replay recorder saves on it (`saveOn.failure`), and the monitor raises an alert.
|
|
154
|
+
|
|
155
|
+
### Patch Changes
|
|
156
|
+
|
|
157
|
+
- 358401a: Link the bevy-ts migration guide from each published package README.
|
|
158
|
+
- Updated dependencies [84eac37]
|
|
159
|
+
- Updated dependencies [7ebd9af]
|
|
160
|
+
- Updated dependencies [358401a]
|
|
161
|
+
- @typeonce/ritmo@0.7.0
|
|
162
|
+
|
|
163
|
+
## 0.6.0
|
|
164
|
+
|
|
165
|
+
### Minor Changes
|
|
166
|
+
|
|
167
|
+
- 130cb6e: Rename the package family from `@typeonce/bevy-ts*` to `@typeonce/ritmo*`.
|
|
168
|
+
Update imports, workspace dependencies, type identity markers, examples, and
|
|
169
|
+
documentation together. There are no compatibility aliases; use the matching
|
|
170
|
+
Ritmo package for each previous Bevy TS package. The separate release preparation
|
|
171
|
+
change coordinates the repository rename and retirement of the generated
|
|
172
|
+
documentation site.
|
|
173
|
+
Use "The agent-first type safe ECS runtime" in package metadata,
|
|
174
|
+
documentation, and brand assets.
|
|
175
|
+
|
|
176
|
+
### Patch Changes
|
|
177
|
+
|
|
178
|
+
- a8e0473: Retire the generated documentation site and point package homepages, source links,
|
|
179
|
+
and issue links to the Ritmo repository in the Typeonce GitHub organization.
|
|
180
|
+
Keep source JSDoc and repository guides, including the Pixi walkthrough in its
|
|
181
|
+
example README.
|
|
182
|
+
- Updated dependencies [a8e0473]
|
|
183
|
+
- Updated dependencies [130cb6e]
|
|
184
|
+
- Updated dependencies [a1f18a8]
|
|
185
|
+
- @typeonce/ritmo@0.6.0
|
|
186
|
+
|
|
187
|
+
## 0.5.0
|
|
188
|
+
|
|
189
|
+
### Patch Changes
|
|
190
|
+
|
|
191
|
+
- @typeonce/bevy-ts@0.5.0
|
|
192
|
+
|
|
193
|
+
## 0.4.0
|
|
194
|
+
|
|
195
|
+
### Minor Changes
|
|
196
|
+
|
|
197
|
+
- e2b2275: New package `@typeonce/bevy-ts-render`: the renderer-agnostic part of `@typeonce/bevy-ts-pixi`, the entity-keyed node registry (`NodeRegistry.make`) and the render sync systems (`RenderSync.system`, `RenderSync.interpolate`), for games drawn with Three.js, the DOM, or any other renderer.
|
|
198
|
+
|
|
199
|
+
**Breaking:** import `NodeRegistry` and `RenderSync` from `@typeonce/bevy-ts-render`. Pixi exports only `PixiNodeRegistry`, with `make(container)` replacing `NodeRegistry.inContainer(container)`. The platform-prefixed adapter implements the generic registry contract and is provided through the existing typed runtime service API. The old Pixi modules and re-exports are removed immediately. Pixi depends only on the render package, dropping its unused browser and core dependencies.
|
|
200
|
+
|
|
201
|
+
This combines the four planned steps into one 0.4.0 release of the fixed package group.
|
|
202
|
+
|
|
203
|
+
- `Game.Schedule.pauseWhen` retains event-reader cursors during a pause. Ordinary `when` gates still discard messages across mode changes and take precedence over pause gates in either nesting order. Stream capacity bounds retention, and debug traces expose whether a skipped run held messages.
|
|
204
|
+
- A system's optional `local` factory owns scratch state per runtime, shared by gated copies. Locals are neither rolled back nor snapshotted and are rebuilt after successful restore. Debug descriptions show which systems declare them.
|
|
205
|
+
- Optional and conditional local factories preserve `undefined` in the callback type. Factories allocate fresh scratch state without side effects; mode changes preserve locals, and values needing cleanup belong in host-managed services.
|
|
206
|
+
- `runtime.send` immediately publishes a schema event from the host at a fresh tick. Calls during a tick or with unknown descriptors throw. Unread host messages survive restore without replaying to readers that already consumed them. Devtools trace sends and include external producers in event lints.
|
|
207
|
+
- **Breaking:** `EntityId` and `Handle` are branded numbers. Replace `id.value` and `handle.value` with `id` and `handle`. Handles now compare by numeric identity and work as `Set` keys without allocating objects. `decodeHandle` and `Decode.handle` accept only positive integer numbers. Object-shaped handles are rejected, including inside snapshots; snapshots write numbers.
|
|
208
|
+
- The guides cover fallible lookups, inspector machine reads, `Query.Cells`, shared access objects, simulation-owned time, and seeded random state. `Feature` remains supported and is documented in the package-authoring guide.
|
|
209
|
+
|
|
210
|
+
### Patch Changes
|
|
211
|
+
|
|
212
|
+
- Updated dependencies [e2b2275]
|
|
213
|
+
- @typeonce/bevy-ts@0.4.0
|
|
214
|
+
|
|
215
|
+
## 0.3.0
|
|
216
|
+
|
|
217
|
+
### Minor Changes
|
|
218
|
+
|
|
219
|
+
- de2a112: Add `Monitor.attach(runtime, { schedules, pick?, locate? })`: a live browser panel that shows how a running game works, toggled with the backslash key or a corner button.
|
|
220
|
+
|
|
221
|
+
- **Overview:** schedule tick times, the busiest systems, entity counts per component with sparklines, state machines, and alerts (failed systems, NaN or infinite writes, discarded messages).
|
|
222
|
+
- **Systems:** each schedule's systems in order, grouped by run conditions. Each one shows its writes, events, spawns (learned while running), and reads, with a live working/idle/skipped status. Hover a name to highlight its writers and readers.
|
|
223
|
+
- **Entity:** pick an entity on screen, by id, or by component, and follow its components and changes live.
|
|
224
|
+
|
|
225
|
+
The monitor observes the runtime only while it is open. `Monitor.Collector` exposes the same data without DOM.
|
|
226
|
+
|
|
227
|
+
- c4d1add: Debug visibility for risks that types cannot rule out.
|
|
228
|
+
|
|
229
|
+
- `Debug.Handle.population()` returns the live entity count and the number of entities per component. It is cheap enough to sample every frame.
|
|
230
|
+
- A new info lint, `read-before-write`, names systems that read a component, resource, or event earlier in a schedule than the first system that writes it there, so they see the previous run's value (for events, one run late).
|
|
231
|
+
- Devtools sessions warn with `non-finite-value` when any traced component write, resource write, event, spawn, or insert contains NaN or an infinity. The warning names the system, the entity, and the path.
|
|
232
|
+
- Runs sample the population every frame. They return `entities` (start, peak, end) and `growing`, and warn with `population-growing` when a component's lowest count rises through every quarter of a run of at least 60 frames.
|
|
233
|
+
- `run()` lists the warnings it raised, both as text and in `warnings`. `report()` ends with the current population.
|
|
234
|
+
|
|
235
|
+
### Patch Changes
|
|
236
|
+
|
|
237
|
+
- Updated dependencies [2b0fb7e]
|
|
238
|
+
- Updated dependencies [c4d1add]
|
|
239
|
+
- Updated dependencies [bd9bdd5]
|
|
240
|
+
- Updated dependencies [bd9bdd5]
|
|
241
|
+
- Updated dependencies [94bdc32]
|
|
242
|
+
- Updated dependencies [bd9bdd5]
|
|
243
|
+
- @typeonce/bevy-ts@0.3.0
|
|
244
|
+
|
|
245
|
+
## 0.2.0
|
|
246
|
+
|
|
247
|
+
### Minor Changes
|
|
248
|
+
|
|
249
|
+
- 4b3a312: `Session.make(runtime, { schedules, describe })`: `describe` names more schedules for `describe()`, its lints, and the access maps without making them runnable. A headless session can now include a game's render schedule (which needs services the headless runtime lacks), so events and components only rendering reads are no longer reported as never read.
|
|
250
|
+
|
|
251
|
+
### Patch Changes
|
|
252
|
+
|
|
253
|
+
- Updated dependencies [4b3a312]
|
|
254
|
+
- Updated dependencies [4b3a312]
|
|
255
|
+
- Updated dependencies [4b3a312]
|
|
256
|
+
- @typeonce/bevy-ts@0.2.0
|
|
257
|
+
|
|
258
|
+
## 0.1.1
|
|
259
|
+
|
|
260
|
+
### Patch Changes
|
|
261
|
+
|
|
262
|
+
- c95a102: First release published from CI through npm trusted publishing, with provenance attestations. Declarations are now verified against consumers on both TypeScript 7 and TypeScript 6. No API or output changes.
|
|
263
|
+
- Updated dependencies [c95a102]
|
|
264
|
+
- @typeonce/bevy-ts@0.1.1
|
package/README.md
CHANGED
|
@@ -1,7 +1,5 @@
|
|
|
1
1
|
# `@typeonce/ritmo-devtools`
|
|
2
2
|
|
|
3
|
-
Migrating from bevy-ts? See the [package migration guide](https://github.com/typeonce-dev/ritmo/blob/main/MIGRATION.md).
|
|
4
|
-
|
|
5
3
|
`Determinism.check` compares the same scripted simulation twice, including
|
|
6
4
|
transient components that snapshots omit:
|
|
7
5
|
|
|
@@ -44,12 +42,13 @@ if (runtime.debug !== undefined) Monitor.attach({ debug: runtime.debug }, { sche
|
|
|
44
42
|
|
|
45
43
|
## The debugging loop
|
|
46
44
|
|
|
47
|
-
1. **Get a headless runtime.**
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
script
|
|
45
|
+
1. **Get a headless runtime.** Keep the game's simulation (schema, systems,
|
|
46
|
+
and the schedules ticked at the fixed step) in modules that import no
|
|
47
|
+
renderer or page API. Build those schedules on a runtime made with
|
|
48
|
+
`debug: { hostClock: HostClock.test() }`, and feed input from
|
|
49
|
+
`Keyboard.scripted(bindings, timeline)` (from `@typeonce/ritmo-browser`)
|
|
50
|
+
instead of the page. Put that in a script that makes the runtime, the
|
|
51
|
+
`Session`, and the run (see the cheat sheet below), and run it with Node.
|
|
53
52
|
2. **Read the lints, then orient.** `session.describe()` starts with lints
|
|
54
53
|
(events nobody reads, next states no marker applies, relations whose
|
|
55
54
|
failures nobody reads, ...); a warning there is often the whole answer. Then it lists every schedule step, each
|
|
@@ -75,7 +74,7 @@ if (runtime.debug !== undefined) Monitor.attach({ debug: runtime.debug }, { sche
|
|
|
75
74
|
to the game so the bug stays fixed.
|
|
76
75
|
|
|
77
76
|
```sh
|
|
78
|
-
node --import tsx
|
|
77
|
+
node --import tsx debug.ts
|
|
79
78
|
```
|
|
80
79
|
|
|
81
80
|
## Cheat sheet
|
|
@@ -206,6 +205,31 @@ data without DOM, for a custom UI.
|
|
|
206
205
|
|
|
207
206
|
The report also starts with the static lints from `describe()`.
|
|
208
207
|
|
|
208
|
+
## Lint from the command line
|
|
209
|
+
|
|
210
|
+
`ritmo-devtools lint <entry>` is the pass/fail check for a game's `check`
|
|
211
|
+
script. `<entry>` exports `lintTarget` (see the `Lint` module): it prints
|
|
212
|
+
every lint of the schedules with its fix and exits with 1 on a warning.
|
|
213
|
+
|
|
214
|
+
```sh
|
|
215
|
+
ritmo-devtools lint src/simulation.ts
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
It also checks that the oxlint simulation rules from
|
|
219
|
+
`@typeonce/oxlint-plugin-ritmo` cover the simulation. Every module that
|
|
220
|
+
importing `<entry>` loads, inside the directory of the `.oxlintrc.json` in the
|
|
221
|
+
working directory and outside `node_modules`, must have
|
|
222
|
+
`ritmo/keep-simulation-headless` on there (overrides apply in order, the last
|
|
223
|
+
match wins; `ignorePatterns` matches are uncovered). Modules imported inside
|
|
224
|
+
`lintTarget` or later (render schedules passed to `describe`) are host code
|
|
225
|
+
and are not checked, nor are type-only imports. A missing config, one with
|
|
226
|
+
`extends`, or one that never turns the rule on prints why the check was
|
|
227
|
+
skipped and does not fail. The check needs Node 22.15 or later.
|
|
228
|
+
|
|
229
|
+
| Code | Meaning |
|
|
230
|
+
|---|---|
|
|
231
|
+
| `uncovered-simulation-module` | The simulation loads this file, but no simulation override in `.oxlintrc.json` covers it, so oxlint never checks it for platform, time, randomness, or math calls. Add it to the override's `files`, or stop importing values from it. Exits with 1. |
|
|
232
|
+
|
|
209
233
|
The trace shows what systems wrote, not what they read. When a system writes
|
|
210
234
|
a wrong value from correct inputs, the journal narrows the bug to that
|
|
211
235
|
system (it runs, in order, and writes this value) and the rest is its code.
|
package/dist/Replay.d.ts
CHANGED
|
@@ -57,7 +57,7 @@ import * as Rendered from "./Rendered.ts";
|
|
|
57
57
|
import * as Session from "./Session.ts";
|
|
58
58
|
type AnySchedule<S extends Schema.Any, Root> = ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>;
|
|
59
59
|
/** The `@typeonce/ritmo-devtools` version written into replay files. */
|
|
60
|
-
export declare const version = "0.
|
|
60
|
+
export declare const version = "0.10.0";
|
|
61
61
|
/** An input service: one value per call, such as a keyboard's actions this step. */
|
|
62
62
|
export interface Source<Data> {
|
|
63
63
|
readonly snapshot: () => Data;
|
package/dist/Replay.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Replay.d.ts","sourceRoot":"","sources":["../src/Replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,KAAK,KAAK,KAAK,MAAM,uBAAuB,CAAA;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,KAAK,KAAK,WAAW,MAAM,6BAA6B,CAAA;AAC/D,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAA;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAA;AAC9F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,KAAK,QAAQ,MAAM,0BAA0B,CAAA;AAGzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE/C,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC,KAAK,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI,IAAI,4BAA4B,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,gBAAgB,CAAC,CAAA;AAErH,wEAAwE;AACxE,eAAO,MAAM,OAAO,
|
|
1
|
+
{"version":3,"file":"Replay.d.ts","sourceRoot":"","sources":["../src/Replay.ts"],"names":[],"mappings":"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"}
|
package/dist/cli.js
CHANGED
|
@@ -16,11 +16,27 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
|
|
|
16
16
|
* prints every lint of its schedules with its fix, and exits with 1 when one
|
|
17
17
|
* is a warning. Info-level lints are printed and do not fail.
|
|
18
18
|
*
|
|
19
|
+
* It also checks simulation coverage: every module that importing `<entry>`
|
|
20
|
+
* loads (inside the directory of `.oxlintrc.json` in the working directory,
|
|
21
|
+
* outside `node_modules`) must have `ritmo/keep-simulation-headless` on in that
|
|
22
|
+
* config, so the oxlint simulation rules check it. Each one that does not is
|
|
23
|
+
* printed as `uncovered-simulation-module` and exits with 1. Only modules
|
|
24
|
+
* loaded by importing the entry are checked: modules imported inside
|
|
25
|
+
* `lintTarget` (such as render schedules passed to `describe`) or loaded later
|
|
26
|
+
* are host code and are not. Type-only imports never load and are not checked.
|
|
27
|
+
* A missing or unreadable config, one with `extends`, or one that never turns
|
|
28
|
+
* the rule on prints why the check was skipped and does not fail.
|
|
29
|
+
*
|
|
30
|
+
* Exit codes: 0 ok, 1 lint warning or uncovered module, 2 usage error.
|
|
31
|
+
* Requires Node 22.15 or later for `module.registerHooks`; on older Node it
|
|
32
|
+
* prints that coverage was not checked.
|
|
33
|
+
*
|
|
19
34
|
* @module cli
|
|
20
35
|
* @docGroup devtools
|
|
21
36
|
*/
|
|
22
37
|
import { resolve } from "node:path";
|
|
23
38
|
import { pathToFileURL } from "node:url";
|
|
39
|
+
import * as SimulationCoverage from "./internal/simulationCoverage.js";
|
|
24
40
|
import * as Lint from "./Lint.js";
|
|
25
41
|
const usage = "usage: ritmo-devtools lint <entry>\n <entry> exports lintTarget: () => { runtime, schedules, describe?, hostEvents? } (see the Lint module)";
|
|
26
42
|
const isRecord = (value) => typeof value === "object" && value !== null;
|
|
@@ -38,7 +54,10 @@ const main = async (args) => {
|
|
|
38
54
|
console.error(usage);
|
|
39
55
|
return 2;
|
|
40
56
|
}
|
|
57
|
+
const loads = SimulationCoverage.recordLoads();
|
|
41
58
|
const loaded = await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(entry)).href));
|
|
59
|
+
// Snapshot before lintTarget runs: modules it imports (render schedules to describe) are host code.
|
|
60
|
+
const simulationModules = loads?.();
|
|
42
61
|
const make = isRecord(loaded) ? loaded["lintTarget"] : undefined;
|
|
43
62
|
if (typeof make !== "function") {
|
|
44
63
|
console.error(`${entry} must export lintTarget: a function returning { runtime, schedules, describe? } (see the Lint module)`);
|
|
@@ -51,7 +70,15 @@ const main = async (args) => {
|
|
|
51
70
|
}
|
|
52
71
|
const report = Lint.run(target);
|
|
53
72
|
console.log(report.text);
|
|
54
|
-
|
|
73
|
+
if (simulationModules === undefined) {
|
|
74
|
+
console.log("simulation coverage not checked: needs Node 22.15 or later (module.registerHooks)");
|
|
75
|
+
return report.data.ok ? 0 : 1;
|
|
76
|
+
}
|
|
77
|
+
const coverage = SimulationCoverage.check(process.cwd(), resolve(entry), simulationModules);
|
|
78
|
+
const text = SimulationCoverage.format(coverage);
|
|
79
|
+
if (text !== "")
|
|
80
|
+
console.log(text);
|
|
81
|
+
return report.data.ok && (!coverage.checked || coverage.uncovered.length === 0) ? 0 : 1;
|
|
55
82
|
};
|
|
56
83
|
process.exitCode = await main(process.argv.slice(2));
|
|
57
84
|
//# sourceMappingURL=cli.js.map
|
package/dist/cli.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;;;;;AACA
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** Starts recording every `file:` module Node loads from now on. `undefined` when this Node has no `module.registerHooks` (before 22.15). */
|
|
2
|
+
export declare const recordLoads: () => (() => ReadonlyArray<string>) | undefined;
|
|
3
|
+
export type Coverage = {
|
|
4
|
+
readonly checked: false;
|
|
5
|
+
readonly reason: string;
|
|
6
|
+
} | {
|
|
7
|
+
readonly checked: true;
|
|
8
|
+
readonly uncovered: ReadonlyArray<string>;
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* Reads `.oxlintrc.json` in `cwd` and returns the loaded modules inside its
|
|
12
|
+
* directory (outside `node_modules`, not the entry) where `ritmo/keep-simulation-headless`
|
|
13
|
+
* is not on, as posix paths relative to the config, sorted.
|
|
14
|
+
*/
|
|
15
|
+
export declare const check: (cwd: string, entry: string, loaded: ReadonlyArray<string>) => Coverage;
|
|
16
|
+
/** The CLI text for a coverage result: a "not checked" line, or one block per uncovered module. */
|
|
17
|
+
export declare const format: (coverage: Coverage) => string;
|
|
18
|
+
//# sourceMappingURL=simulationCoverage.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"simulationCoverage.d.ts","sourceRoot":"","sources":["../../src/internal/simulationCoverage.ts"],"names":[],"mappings":"AAeA,6IAA6I;AAC7I,eAAO,MAAM,WAAW,QAAO,CAAC,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,SAU9D,CAAA;AAED,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE,CAAA;AA4CzE;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAS,MAAM,SAAS,MAAM,UAAU,aAAa,CAAC,MAAM,CAAC,KAAG,QA8CjF,CAAA;AAED,mGAAmG;AACnG,eAAO,MAAM,MAAM,aAAc,QAAQ,KAAG,MAO5B,CAAA"}
|
|
@@ -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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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/internal/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,cAAc,
|
|
1
|
+
{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/internal/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,cAAc,WAAW,CAAA"}
|
package/dist/internal/version.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/internal/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,
|
|
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.
|
|
3
|
+
"version": "0.10.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.
|
|
54
|
+
"@typeonce/ritmo": "^0.10.0"
|
|
54
55
|
},
|
|
55
56
|
"engines": {
|
|
56
|
-
"node": ">=
|
|
57
|
+
"node": ">=22.15"
|
|
57
58
|
},
|
|
58
59
|
"scripts": {
|
|
59
60
|
"build": "tsc -b tsconfig.json --pretty false",
|
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
|
-
|
|
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))
|
|
@@ -0,0 +1,136 @@
|
|
|
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
|
+
|
|
13
|
+
const configName = ".oxlintrc.json"
|
|
14
|
+
const rule = "ritmo/keep-simulation-headless"
|
|
15
|
+
|
|
16
|
+
/** Starts recording every `file:` module Node loads from now on. `undefined` when this Node has no `module.registerHooks` (before 22.15). */
|
|
17
|
+
export const recordLoads = (): (() => ReadonlyArray<string>) | undefined => {
|
|
18
|
+
if (typeof Module.registerHooks !== "function") return undefined
|
|
19
|
+
const urls = new Set<string>()
|
|
20
|
+
Module.registerHooks({
|
|
21
|
+
load: (url, context, nextLoad) => {
|
|
22
|
+
if (url.startsWith("file:")) urls.add(url)
|
|
23
|
+
return nextLoad(url, context)
|
|
24
|
+
}
|
|
25
|
+
})
|
|
26
|
+
return () => [...urls]
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export type Coverage =
|
|
30
|
+
| { readonly checked: false; readonly reason: string }
|
|
31
|
+
| { readonly checked: true; readonly uncovered: ReadonlyArray<string> }
|
|
32
|
+
|
|
33
|
+
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
34
|
+
typeof value === "object" && value !== null && !Array.isArray(value)
|
|
35
|
+
|
|
36
|
+
/** Removes `//` and `/* *\/` comments outside strings, then trailing commas before `}` or `]`. */
|
|
37
|
+
const stripJsonc = (text: string): string => {
|
|
38
|
+
let out = ""
|
|
39
|
+
let index = 0
|
|
40
|
+
while (index < text.length) {
|
|
41
|
+
const char = text[index]!
|
|
42
|
+
if (char === "\"") {
|
|
43
|
+
let end = index + 1
|
|
44
|
+
while (end < text.length && text[end] !== "\"") end += text[end] === "\\" ? 2 : 1
|
|
45
|
+
out += text.slice(index, end + 1)
|
|
46
|
+
index = end + 1
|
|
47
|
+
} else if (char === "/" && text[index + 1] === "/") {
|
|
48
|
+
while (index < text.length && text[index] !== "\n") index++
|
|
49
|
+
} else if (char === "/" && text[index + 1] === "*") {
|
|
50
|
+
const end = text.indexOf("*/", index + 2)
|
|
51
|
+
index = end === -1 ? text.length : end + 2
|
|
52
|
+
} else {
|
|
53
|
+
out += char
|
|
54
|
+
index++
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
return out.replace(/("(?:[^"\\]|\\.)*")|,(\s*[}\]])/g, (match, string: string | undefined, close: string | undefined) =>
|
|
58
|
+
string !== undefined ? match : close!)
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** `true` on, `false` off, `undefined` when the value does not set the rule. */
|
|
62
|
+
const severity = (value: unknown): boolean | undefined => {
|
|
63
|
+
const level = Array.isArray(value) ? value[0] : value
|
|
64
|
+
if (level === "error" || level === "warn" || level === 1 || level === 2) return true
|
|
65
|
+
if (level === "off" || level === 0) return false
|
|
66
|
+
return undefined
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
const globs = (value: unknown): ReadonlyArray<string> =>
|
|
70
|
+
Array.isArray(value) ? value.filter((glob): glob is string => typeof glob === "string") : []
|
|
71
|
+
|
|
72
|
+
const matches = (file: string, patterns: ReadonlyArray<string>): boolean =>
|
|
73
|
+
patterns.some((pattern) => matchesGlob(file, pattern))
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Reads `.oxlintrc.json` in `cwd` and returns the loaded modules inside its
|
|
77
|
+
* directory (outside `node_modules`, not the entry) where `ritmo/keep-simulation-headless`
|
|
78
|
+
* is not on, as posix paths relative to the config, sorted.
|
|
79
|
+
*/
|
|
80
|
+
export const check = (cwd: string, entry: string, loaded: ReadonlyArray<string>): Coverage => {
|
|
81
|
+
const configPath = join(cwd, configName)
|
|
82
|
+
let text: string
|
|
83
|
+
try {
|
|
84
|
+
text = readFileSync(configPath, "utf8")
|
|
85
|
+
} catch {
|
|
86
|
+
return { checked: false, reason: `no ${configName} in ${cwd}` }
|
|
87
|
+
}
|
|
88
|
+
let config: unknown
|
|
89
|
+
try {
|
|
90
|
+
config = JSON.parse(stripJsonc(text))
|
|
91
|
+
} catch {
|
|
92
|
+
return { checked: false, reason: `${configName} is not valid JSON with comments` }
|
|
93
|
+
}
|
|
94
|
+
if (!isRecord(config)) return { checked: false, reason: `${configName} is not an object` }
|
|
95
|
+
if (config["extends"] !== undefined) return { checked: false, reason: `${configName} uses "extends", which this check does not follow` }
|
|
96
|
+
const topLevel = isRecord(config["rules"]) ? severity(config["rules"][rule]) : undefined
|
|
97
|
+
const overrides = (Array.isArray(config["overrides"]) ? config["overrides"] : []).filter(isRecord).map((override) => ({
|
|
98
|
+
files: globs(override["files"]),
|
|
99
|
+
setting: isRecord(override["rules"]) ? severity(override["rules"][rule]) : undefined
|
|
100
|
+
}))
|
|
101
|
+
if (topLevel !== true && !overrides.some((override) => override.setting === true)) {
|
|
102
|
+
return { checked: false, reason: `no rules in ${configName} turn on ${rule}` }
|
|
103
|
+
}
|
|
104
|
+
const ignored = globs(config["ignorePatterns"])
|
|
105
|
+
const root = realpathSync(dirname(configPath))
|
|
106
|
+
const entryPath = realpathSync(entry)
|
|
107
|
+
const uncovered = new Set<string>()
|
|
108
|
+
for (const url of loaded) {
|
|
109
|
+
let file: string
|
|
110
|
+
try {
|
|
111
|
+
file = realpathSync(fileURLToPath(url))
|
|
112
|
+
} catch {
|
|
113
|
+
continue
|
|
114
|
+
}
|
|
115
|
+
const path = relative(root, file)
|
|
116
|
+
if (file === entryPath || path === "" || path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path)) continue
|
|
117
|
+
const posix = path.split(sep).join("/")
|
|
118
|
+
if (posix.split("/").includes("node_modules")) continue
|
|
119
|
+
let on = topLevel === true
|
|
120
|
+
for (const override of overrides) {
|
|
121
|
+
if (override.setting !== undefined && matches(posix, override.files)) on = override.setting
|
|
122
|
+
}
|
|
123
|
+
if (!on || matches(posix, ignored)) uncovered.add(posix)
|
|
124
|
+
}
|
|
125
|
+
return { checked: true, uncovered: [...uncovered].sort() }
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** The CLI text for a coverage result: a "not checked" line, or one block per uncovered module. */
|
|
129
|
+
export const format = (coverage: Coverage): string =>
|
|
130
|
+
!coverage.checked
|
|
131
|
+
? `simulation coverage not checked: ${coverage.reason}`
|
|
132
|
+
: coverage.uncovered.map((file) =>
|
|
133
|
+
`uncovered-simulation-module ${file}\n`
|
|
134
|
+
+ ` The simulation loads this file, but the simulation rules in ${configName} do not cover it.\n`
|
|
135
|
+
+ ` Add it to the simulation override's "files", or stop importing values from it.`
|
|
136
|
+
).join("\n")
|
package/src/internal/version.ts
CHANGED