source-academy / js-slang / 35590600188

86%

push

github

feat(conductor): CSE machine evaluators for Source §3–§4 (#2061)

* feat(conductor): CSE machine evaluators for Source §3-§4

Implements #2060. SourceCseEvaluator3/4 drive js-slang's CSE machine and
ship one CseSnapshot per step to the host's CSE tab.

§3/§4 only: the frontend gates the tab at chapter >= SOURCE_3
(ApplicationTypes.ts:245) and, under Conductor, shows it when the
language offers an evaluator carrying EvaluatorCapability.CSE. The
evaluator is hidden from the dropdown and auto-selected when the tab
opens, like the stepper.

The machine stays synchronous. In js-slang the CSE machine is the
visualiser, not the workhorse, so unlike py-slang — whose CSE machine
is its primary engine and is async throughout — nothing here needs to
await the host. generateCSEMachineStateStream is a plain function* and
is used as one.

Only the serialiser is new: the plugin trio in source-academy/plugins is
264 LOC of pure transport, and the renderer stays in the frontend. For
Source this is a round trip — serialise js-slang state, then have the
host's CseSnapshotAdapter rebuild js-slang-shaped objects for the same
renderer the non-conductor tab uses — so the adapter, not the protocol
types, is the real contract. Three conventions it depends on, all easy
to get silently wrong, are documented in serialize.ts: control and stash
are top-first, InstrType is a string enum passed through untouched, and
ENVIRONMENT instructions are matched on displayText rather than on
instrType.

Deliberately unlike #2004's serialiser:
- arrays serialise to full depth, with cycle detection, rather than
  truncating at depth 2 (which silently flattens ordinary list programs)
- steps are not deduplicated by rendered text: two steps can look
  identical while differing in the environments, and collapsing them
  desynchronises the step counter from the machine's own numbering
- closures send the machine's own rendering as displayValue, so the
  stash reads identically to the non-conductor... (continued)

3325 of 4424 branches covered (75.16%)

Branch coverage included in aggregate %.

178 of 194 new or added lines in 5 files covered. (91.75%)

7317 of 9051 relevant lines covered (80.84%)

178676.11 hits per line