Improve ecmarkup API for use in a language service
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 245
- Forks
- 80
- Avg merge
- 10h 46m
- Merged PRs (30d)
- 2
Description
I'm rewriting my ecmarkup vscode extension, and one of the issues I'm running into is that the ecmarkup API isn't usable for language service/editor scenarios. Some of that can be addressed by fully exposing the API (instead of the current very narrow TypeScript API for Spec), but other necessary requirements would be:
- A mode where
<emu-import>tags are not inlined into the document - API for accessing linter without requiring a full build
- API for accessing collected biblios and references without requiring a full build
- Support for error recovery (beyond JSDOM/HTML's default error recovery)
- This one is probably more complicated as its not something supported by JSDOM out of the box (see below)
- API for accessing ecmarkdown AST w/o translating to HTML
- API for accessing grammarkdown AST w/o translating to HTML
- API to access all imported files (when not inlined)
- A config file mechanism for specifying options like whether to include esbiblio, and what files should be considered part of the build (or at least, the root file for the build), so that the language service can identify the root document and related documents from a workspace folder.
I'm currently writing a dedicated parser using the HTML scanner from vscode-html-languageservice to achieve this, but that means re-implementing all of the errors, warnings, reference collection, lint rules, etc. of ecmarkup to avoid the heavy cost of generating output that isn't used. Reducing such overhead is especially important in an editor to avoid typing delays and completion delays.
The editor scenarios I'm hoping to provide include (based on what I provide for grammarkdown-vscode):
- Validation — Showing error and warning diagnostics, lint errors, etc.
- Find Definition (a.k.a. Go To Definition) — Jumping to a definition for an algorithm, nonterminal, definition, etc. across ecmarkup, ecmarkdown, and grammarkdown
- Find References — For finding all references to algorithms, nonterminals, definitions, etc. across ecmarkup, ecmarkdown, and grammarkdown
- Hover — For quick info about an algorithm, nonterminal parameters, definitions, etc.
- Signature Help — To show argument lists and completions for algorithms, nonterminal parameters, etc.
- Completions — For attributes, Nonterminals, Algorithm names, Definitions, etc.
- Rename
- Document Symbols
- Workspace Symbols
- Call Hierarchy — For calls to/from an algorithm or to/from a production.
In addition I'm considering features such as:
- Inserting a copy of original spec text in a proposal, i.e., type
<emu-clause id="sec-blockand get a suggestion to insert the current spec text forsec-blockfor modification. - Extract to file using
<emu-import - Code actions/refactors (if there are scenarios that make sense)
- Document formatting to align with lint rules
- Code actions to fix lint errors in-editor
By error recovery, I'm more specifically talking about cases where unclosed <emu- tags are more likely to be closed in a real document, such as the fact an <emu-grammar or <emu-alg likely won't contain any other <emu- tags or HTML block tags, so should be "automatically" closed when those tags are encountered. This is important when offering completions in an editor, as an <emu-grammar, <emu-alg, <emu-eqn, <emu-table, etc. that consumes the rest of the document as its contents won't be able to offer completions. I'm not sure if its possible to hook JSDOM or parse5 to handle these cases, however.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the current narrow TypeScript API for Spec and the full-build path, then compare them with the language-service requirements listed here. The issue describes multiple possible API and parsing changes rather than a single entry point; completion would require narrowing the scope and defining which editor scenarios and recovery behavior are supported.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100