source-academy / js-slang / 35698076645

86%

push

github

feat(conductor): wire up the autocomplete plugin, generated from docs/lib jsdoc (#2090)

* feat(conductor): wire up the autocomplete plugin, generated from docs/lib jsdoc

Closes #2079. There was no autocomplete in any Conductor Source
evaluator: typing `acc` in the playground offered nothing, where the
pre-Conductor editor offered `accumulate` with its documentation.

## Builtin data: mechanically generated from docs/lib/*.js, not scraped

The old (deleted in #2070) pipeline scraped autocomplete tooltips from
*rendered* jsdoc HTML, which only worked after `yarn docs` had already
run — a build-order dependency that broke CI once already (#2068).

Following py-slang's own solution to the identical problem:
scripts/autocomplete.mjs asks jsdoc for its own parsed doclet AST
directly (`-X`, jsdoc's "explain" mode — a pure parse step, no
rendering, no ordering requirement) against docs/lib/*.js, and writes
the simplified {name, title, description, meta} shape straight to
src/conductor/plugins/autocomplete/builtins/*.json. Output is
committed (matching py-slang's builtins/*.json), so a clean
`yarn build:evaluators` doesn't depend on this script having run —
but CI (nodejs.yml) now runs `yarn autocomplete` and diffs the result,
so a docs/lib edit that forgot to regenerate fails loudly instead of
silently going stale.

Filters out auxiliary.js (internal `__access_export__`-style loader
plumbing, never student-facing) and anything with no jsdoc comment
(list.js's own undocumented $accumulate/$append/$build_list helpers
that the real, documented functions wrap).

## The plugin itself

- resolver.ts — walks a real ESTree program (via acorn-walk's
  fullAncestor) to build the scope chain around the cursor, subsequence-
  matches against it plus chapter-gated keywords and the jsdoc-derived
  builtins, and scores inner scopes ahead of outer ones. Parses with
  acorn-loose, not the real parser: the buffer is normally *invalid*
  Source while a student is mid-keystrok... (continued)

2512 of 3044 branches covered (82.52%)

Branch coverage included in aggregate %.

114 of 119 new or added lines in 8 files covered. (95.8%)

4891 of 5596 relevant lines covered (87.4%)

294028.11 hits per line