[ANN] `@rescript/language-server` and `@rescript/tools` released

Announcements
1

We’re very happy to announce that the first versions of two long sought after packages have just been released - @rescript/language-server and @rescript/tools!

The ReScript Language Server as an NPM package

The ReScript Language Server that powers the VSCode extension will now ship as a standalone NPM package @rescript/language-server. This will make it magnitudes simpler to integrate an up-to-date version of the language server in other editors that also uses language servers.

The language server package will be released together with each stable VSCode editor extension release. You can read more about how to use it here: https://github.com/rescript-lang/rescript-vscode/tree/master/server

Automatic doc extraction and reanalyze

The second package we’re shipping is @rescript/tools. In the first release, it comes with the following capabilities:

Automatic doc extraction

It’s finally possible to automatically extract everything needed to generate documentation from your ReScript code using a CLI. rescript-tools doc src/SomeEntryRescriptFile.res will go into the target file and extract a JSON structure containing everything needed to generate documentation driven by your ReScript source code. This includes information about all modules, let bindings, types, as well as ReScript signatures for each, extra information about record fields and variant constructors, and so on. All docstrings are naturally included in the output.

The package also comes with ReScript bindings to the generated JSON structure. Read more about this and how to use it here: https://github.com/rescript-lang/rescript-vscode/tree/master/tools

What we’re currently missing (PRs welcome) is a basic markdown “renderer” we can ship with the CLI, so there’s a way to get ready-made documentation out in markdown files via a single command for the situations where you don’t want to do anything fancy with the docs yourself. So, just a simple “JSON structure → markdown” generator. Please reach out if you’re interested in helping out with this.

reanalyze

Reanalyze, ReScript’s dedicated code analyzer for dead code/exceptions/termination analysis lives inside of the editor extension and is best used from inside of the VSCode editor extension. But, there are cases when you’d want to run reanalyze outside of the editor - CI, CLI tools, and so on.

The tools package exposes reanalyze outside of the editor extension again via the tools CLI. Read more about using reanalyze from the CLI here: https://github.com/rescript-lang/rescript-vscode/tree/master/tools

Final words

Feels great to finally get these out. This is a milestone for us given that it’s something we’ve been working on for a long time. Thanks to everyone who’s helped out with this in whatever capacity. And a special thanks to @aspeddro who’s spent a lot of time getting this over the finish line.

Please try these out and don’t be afraid to give feedback, suggestions etc as you test the tools out in the real world. We want to make these tools as good as we can.

35 Likes
2

Thanks Gabriel!
We have @cristianoc reanalyze package installed and running in our deployment pipeline. Is this reanalyze different?

TIA
Alex

3

The dedicated reanalyze package that’s on npm is from before reanalyze was integrated into the editor tooling. So using it through the tools package instead means using an as up to date version of reanalyze as possible.

EDIT: One concrete upside is that rescript.json works with the reanalyze in tools, but the old one requires the (soon to be legacy) bsconfig.json.

2 Likes
4

Love it! I’m going to experiment with the coc.nvim extension for ReScript

5

@aspeddro even updated nvim-lspconfig! :bowing_man: Awesome!

1 Like
6

@zth I’m interested in experimenting in markdown generating code. Is there any project with lots of documentation that I can try out the tool with?

1 Like
7

Awesome! I think Core is a good starting point - quite a lot of code and almost all of that code has docstrings and embedded examples:

Looking forward to seeing what you come up with!

3 Likes
8

Super interested in trying something with rescript tools, what’s the typical way to interface with a package like this? Since there’s no node api I assume I’ll need to use execSync or something and read the output, should I try to use the actual command or run node node_modules/@rescript/tools/src/Cli.bs.js?

9

You can leverage npx quite easily to run the tools package. Here’s an example from the RescriptRelay CLI “remove unused fields” command, which uses reanalyze from the tools package to do some dead code analysis:

3 Likes
10

@Exegetech did you end up with something working?

Today, I finally made some time to tinker around with creating a (rescript/node) lib transforming RescriptTools.Docgen.doc to a markdown string.

It seems like the hardest part is to manipulate markdown inside of the docstrings to match the overall intendation. (e.g. Core docs often use ## Example, but when rendering the whole module’s docs, h2 headings should probably be reserved to actually structure the document).
Nothing too complicated, but I’d like to smoothen some of the rougher edges, before sharing my approach.

So consider this just a headsup. And please share, if anyone alread started working on something similar!

4 Likes
11

Please do publish a WIP repo if you have. Would be fantastic to see if we can collaborate a few people and get a good version of this shipped.

I have an idea for a simple static site generator (written in ReScript) that we can also build to have a single command or similar for just turning doc extraction into a full blown site.

1 Like
12

@zth just published my repo: rescript-tools-doc-md
I’m thankfull for any feedback or suggestions!

P.S: It seems like I had a similar idea (about a rescript cli doc generator) for the passed 5 years, but now the parts may finally fall in to place. :slight_smile:

5 Likes
13

Some thoughts.

One thing we should think about is what format is best for those who maintain libraries.

I was thinking about generating static HTML. The advantage is that they are simple files that can be hosted on github. In this case we would have a pre-defined style. The user could open the browser and see the documentation rendered.

Rust also generates static HTML. Another simple case, gleam lang: gleam_stdlib · v0.34.0

Markdown output

I think we need to generate several .md files, where each folder is a module.

Some libraries use docusaurus to document the package. An example, Ancestor (https://github.com/rescriptbr/ancestor/tree/main/website/docs).

Structure example:

.
|-- docs/
|----- api/
|--------- array/
|------------ index.md (top level values and types inside Array module - if exists)
|------------ result (Array.Result module)
|---------------- index.md (all types and values inside Array.Result)
3 Likes
14

I wonder how to use ReSCript with zed.dev
Do I have to run the rescript-language-server on the terminal?

15

zed does not yet support external lsp configuration officially.

According to the source code released yesterday, it seems implemented in the form of a wasm plugin.

Since rescript lsp does not have a wasm build, it may require porting implementation into another lang or using an additional toolchain such as javy.

FYI I experimented with getting a wasm build of the rescript compiler using wasm_of_ocaml, and it pretty much works, but has some problems integrating with the external fs, still investigating.

1 Like
16

It shouldn’t be difficult to add rescript support

Here is an example to add Deno LSP: Add Deno LSP support by lino-levan · Pull Request #5816 · zed-industries/zed · GitHub

1 Like
17

Oh right using LspAdapter seems much easier!

1 Like
18

Zed support would be amazing!

3 Likes
19

Got the ReScript in Zed working! This is just stitching together the GitHub - rescript-lang/tree-sitter-rescript: ReScript parser for Tree-Sitter for grammar and GitHub - rescript-lang/rescript-vscode: Official VSCode plugin for ReScript for the LSP.

image
image2880×1624 451 KB

PR to zed extensions is pending Add ReScript extension by KidkArolis · Pull Request #572 · zed-industries/extensions · GitHub review and merge, after that it should be possible to find the ReScript extension directly in Zed :crossed_fingers:

And here’s the source if you want to try and compile it locally: GitHub - humaans/rescript-zed: ReScript support for Zed editor

This extension, in particular the LSP does not seem to be working very smoothly yet, it crashes with fs.writeFileSync(undefined) error somewhere in the cli.js quite easily, so will have to continue debugging. But at least this gives you the syntax highlighting!

12 Likes
20

Awesome work, thank you! I am very keen to give Zed a try when the LSP works. Keep us updated!

1 Like