Duolith docs

0066. The compiler service gives a page outline; the language server's features come in six checked groups

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: toolchain work package (WP15), pending Mik's approval
  • Planning item: WP15 (toolchain), goal 5

Context

The language server answered diagnostics, completion, hover, definition, rename, formatting and quick fixes. Editors also expect an outline, folding, smart selection, links, workspace symbols, semantic colouring, inlay hints, highlights, call hierarchy, refactors and linked editing. Each of these needs to know where elements, tag names and attributes are written. Scanning markup with regular expressions in TypeScript would give a second, wrong parser.

Decision

  • **pageOutline(source) joins the compiler service** (crates/wasm/api.d.ts). It returns the script block's range, the style blocks' ranges and the element tree as the parser sees it: each element's name, kind (element, component or flow), range, the range of its name and of its closing name, its attributes (name, name range, value kind, value, value range) and its children. Offsets are UTF-16, as elsewhere at this boundary. It never fails: a page that does not parse gives what was parsed.
  • **The features are listed in packages/language-server/checklist.yaml**, in six groups: 1 Checking, 2 Writing, 3 Navigation (the existing features), 4 Structure (document symbols, folding, selection ranges, document links, workspace symbols), 5 Insight (semantic tokens, inlay hints, document highlights, call hierarchy), 6 Refactoring (wrap in <view>, extract to component, linked editing).
  • Every feature has an LSP test, through the existing harness against the built server; test/checklist.test.ts fails if an entry has none.
  • What the groups do, briefly: an href to a route links to and hints at the page that serves it (→ post/[id].duo, or → no page); workspace symbols list routes and components; semantic tokens mark components (class), control flow (keyword), events (event), directives (macro) and attributes (property); call hierarchy runs along component placements.
  • Extract to component turns what the markup reads into props. The names its {expressions} read but do not declare become props when the script block declares them or a list around the element binds them (its item and index). Each prop gets the type it was written with, or can be read with at a glance (state("") is string, state<Todo[]> makes a list item Todo, a function's written parameter types); anything else is any, never a guess. Imports the markup uses are copied, with relative paths fixed, and so are the type aliases and interfaces the props mention. The rules of the page's <style> blocks for the classes the markup uses are copied into the component's own <style> block, since page classes are scoped to the page. The action is shown disabled, saying why, whenever the new component would not build as the page did: markup that assigns such a name (count += 1, bind:value={name}) would need a bindable prop (decision 0029); a class whose rule also needs a class outside the markup (.list .row), or sits in an at-rule, cannot move; a component the page does not import cannot be imported by the new one either. A test applies the edit to a copy of the fixture project and runs duolith build on it.

Alternatives considered

OptionWhy not
Parse markup in the language serverA second parser that disagrees with the compiler on edge cases
Return the full syntax treeLarger, and ties the server to the tree's internal shape; the outline is what features need
Extract only markup without expressionsMost markup worth extracting reads something; leaving it out made the refactor rare
Ask TypeScript's checker for each prop's typeThe script view's types depend on the whole project; the declared or plainly read type is enough, and any is honest when it is not plain

Consequences

  • The compiler service contract grows by one function; the language server memoises the last outline, so a burst of requests for one version parses once.
  • Workspace symbols are answered once per request although Volar keeps one language service per TypeScript project.