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

zth · November 3, 2023, 2:08pm

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.

mouton · November 3, 2023, 4:23pm

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

TIA
Alex

zth · November 3, 2023, 5:06pm

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.

cometkim · November 5, 2023, 8:57pm

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

joakin · November 6, 2023, 11:39pm

@aspeddro even updated nvim-lspconfig! Awesome!

Exegetech · November 13, 2023, 6:10pm

@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?

zth · November 13, 2023, 6:38pm

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!

hellos3b · November 23, 2023, 10:13pm

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?

zth · November 24, 2023, 7:13am

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:

github.com

zth/rescript-relay/blob/master/packages/rescript-relay-cli/commands/removeUnusedFieldsCommand.ts#L58


      
            ci?: boolean;
            verbose?: boolean;
            debug?: boolean;
          }) => {
            const relayConfig = loadRelayConfig();
            const artifactDirectoryLocation =
              getRelayArtifactDirectoryLocation(relayConfig);
          
          
  const spinner = ora("Analyzing ReScript project").start();
          
          
  const p = cp.spawn("npx", ["--yes", "@rescript/tools", "reanalyze", "-dce"]);
          
          
  if (p.stdout == null) {
              console.error("Something went wrong.");
              process.exit(1);
            }
          
          
  let data = "";
          
          
  p.stdout.on("data", (d) => {
              data += d;