From 58c3269d4c553c1e595adb5897908d9a2b2733ba Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Fri, 22 Jul 2022 15:40:19 -0300 Subject: [PATCH 1/5] new readme --- README.md | 159 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 105 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 92ca8b97f..b2636c114 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,44 @@ -# rescript-vscode - -The official VSCode plugin for ReScript. - -![Screen shot](https://user-images.githubusercontent.com/1909539/101266821-790b1400-3707-11eb-8e9f-fb7e36e660e6.gif) - -## Prerequisite - -You **must** have `rescript >=9.1` installed locally in your project, through the usual [npm installation](https://rescript-lang.org/docs/manual/latest/installation#integrate-into-existing-js-project). Older versions are not guaranteed to work. - -## Recommendation +

+ ReScript VSCode +

+ +

The official VSCode plugin for ReScript

+ +

+ + + + +

+ +

+ +

+ +## Contents + +- [📝 Prerequisite](#-prerequisite) +- [🌈 Supported Themes](#-supported-themes) +- [💡 Features](#-features) +- [📥 Installation](#-installation) +- [📦 Commands](#-commands) +- [🔨 Settings](#-settings) +- [🚀 Code Analyzer](#-code-analyzer) + - [Configuring the Code Analyzer](#configuring-the-code-analyzer) + - [Usage](#usage) + - [Caveats](#caveats) +- [🪄 Tips & Tricks](#-tips--tricks) + - [Hide generated files](#hide-generated-files) +- [⌨️ Use with Other Editors](#️-use-with-other-editors) +- [📰 Changelog](#-changelog) +- [👏 How to Contribute](#-how-to-contribute) +- [📄 License](#-license) + +## 📝 Prerequisite + +You **must** have [ReScript](https://www.npmjs.com/package/rescript) >= 9.1 installed locally in your project, through the usual [npm or yarn installation](https://rescript-lang.org/docs/manual/latest/installation#integrate-into-existing-js-project). Older versions are not guaranteed to work. + +## 🌈 Supported Themes Our highlighting works well with most popular VSCode themes, such as: @@ -22,15 +52,10 @@ The only 2 themes we don't (and can't) support, due to their lack of coloring, a - Dark (Visual Studio), Light (Visual Studio) -If your custom theme doesn't seem to highlight much (e.g. no colors for upper-case JSX tag, no distinction between module and variant), try one of the recommended themes to see if that's the problem. For more info, see [this post](https://github.com/rescript-lang/rescript-vscode/pull/8#issuecomment-764469070). - -## Installation +> **Note** +> If your custom theme doesn't seem to highlight much (e.g. no colors for upper-case JSX tag, no distinction between module and variant), try one of the recommended themes to see if that's the problem. For more info, see [this post](https://github.com/rescript-lang/rescript-vscode/pull/8#issuecomment-764469070). -The plugin's on [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=chenglou92.rescript-vscode). In VSCode, `cmd-shift-p` -> "Install Extensions", then find "rescript-vscode". - -The plugin activates on `.res` and `.resi` files. If you've already got Reason-Language-Server installed, it's possible that the latter took precedence over this one. Make sure you're using this plugin ("ReScript syntax") rather than Reason-Language-Server ("BuckleScript syntax"). - -## Features +## 💡 Features - Supports `.res`, `.resi` and `bsconfig.json`. - Syntax highlighting. @@ -49,71 +74,85 @@ The plugin activates on `.res` and `.resi` files. If you've already got Reason-L - `try`, `for`, etc. - Folding, and [custom folding](https://code.visualstudio.com/docs/editor/codebasics#_folding) through `//#region` and `//#endregion`. -### Commands +## 📥 Installation + +Launch VS Code Quick Open (`Ctrl+P`), paste the following command, and press enter. + +``` +ext install chenglou92.rescript-vscode +``` + +The plugin activates on `.res` and `.resi` files. If you've already got Reason-Language-Server installed, it's possible that the latter took precedence over this one. Make sure you're using this plugin ("ReScript syntax") rather than Reason-Language-Server ("BuckleScript syntax"). + +## 📦 Commands + +| Command | Description | +|------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ReScript: Create an interface file for this implementation file | Creates an interface file (`.resi`) for the current `.res` file, automatically filling in all types and values in the current file. | +| ReScript: Open the compiled JS file for this implementation file | Opens the compiled JS file for the current ReScript file. | +| ReScript: Switch implementation/interface | Switches between the implementation and interface file. If you're in a `.res` file, the command will open the corresponding `.resi` file (if it exists), and if you're in a `.resi` file the command will open the corresponding `.res` file. This can also be triggered with the keybinding `Alt+O`. | +| ReScript: Start Code Analyzer | This will start code analysis in the ReScript project of the file you run the command from. | -#### `> ReScript: Create an interface file for this implementation file.` +## 🔨 Settings -Creates an interface file (`.resi`) for the current `.res` file, automatically filling in all types and values in the current file. +You'll find all ReScript specific settings under the scope `rescript.settings`. -#### `> Open the compiled JS file for this implementation file.` +| Setting | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Autostarting ReScript builds | If there's no ReScript build running already in the opened project, the extension will prompt you and ask if you want to start a build automatically. You can turn off this automatic prompt via the setting `rescript.settings.askToStartBuild`. | +| ReScript Binary Path | The extension will look for the existence of a `/node_modules/.bin/rescript` file and use its directory as the `binaryPath`. If it does not find it at the project root (which is where the nearest `bsconfig.json` resides), it goes up folders in the filesystem recursively until it either finds it (often the case in monorepos) or hits the top level. To override this lookup process, the path can be configured explicitly using the setting `rescript.settings.binaryPath` | +| Autostarting the Code Analyzer | The Code Analyzer needs to be started manually by default. However, you can configure the extension to start the Code Analyzer automatically via the setting `rescript.settings.autoRunCodeAnalysis`. | -Opens the compiled JS file for the current ReScript file. +**Default settings:** -#### `> ReScript: Switch implementation/interface` +```jsonc +// Whether you want the extension to prompt for autostarting a ReScript build if a project is opened with no build running +"rescript.settings.askToStartBuild": true, -Switches between the implementation and interface file. If you're in a `.res` file, the command will open the corresponding `.resi` file (if it exists), and if you're in a `.resi` file the command will open the corresponding `.res` file. +// Automatically start ReScript's code analysis. +"rescript.settings.autoRunCodeAnalysis": false, -> This can also be triggered with the keybinding `Alt+O`. +// Path to the directory where ReScript binaries are. You can use it if you haven't or don't want to use the installed ReScript from node_modules in your project. +"rescript.settings.binaryPath": null +``` -### Code Analyzer +## 🚀 Code Analyzer The Code Analyzer is a mode in the extension that runs additional code analysis in your project. The analysis helps you find dead code at a granular level, find unhandled exceptions, and more. > The Code Analyzer uses [reanalyze](https://github.com/rescript-association/reanalyze), which is embedded in the extension, so you don't need to install anything extra to run it. -#### Configuring the Code Analyzer +### Configuring the Code Analyzer You'll need to configure what code analysis you want to run, and what (if any) directories you want to ignore. Configuration is done via adding `reanalyze` in `bsconfig.json`. You'll get autocomplete for what configuration options are valid. You can also read [all about configuring `reanalyze` here](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson). -##### Autostarting the Code Analyzer +### Usage -The Code Analyzer needs to be started manually by default. However, you can configure the extension to start the Code Analyzer automatically via the setting `rescript.settings.autoRunCodeAnalysis`. - -#### Usage - -Open the command palette and run `> ReScript: Start Code Analyzer`. This will start code analysis in the ReScript project of the file you run the command from. +Open the command palette and run `ReScript: Start Code Analyzer`. This will start code analysis in the ReScript project of the file you run the command from. Dead code is highlighted in the editor, and code actions for suppressing dead code warnings are available in most cases. When done, stop the code analysis mode by clicking the `Stop Code Analyzer` button in the editor status bar. This will clear all reported analysis warnings. -#### Caveats +### Caveats Currently does not work for full monorepo dead code analysis (although it should work for each monorepo package individually). -## Configuration - -You'll find all ReScript specific settings under the scope `rescript.settings`. Open your VSCode settings and type `rescript.settings` to see them. - -### Autostarting ReScript builds - -If there's no ReScript build running already in the opened project, the extension will prompt you and ask if you want to start a build automatically. You can turn off this automatic prompt via the setting `rescript.settings.askToStartBuild`. - -#### How does it find my ReScript binary? - -The extension will look for the existence of a `/node_modules/.bin/rescript` file and use its directory as the `binaryPath`. If it does not find it at the project root (which is where the nearest `bsconfig.json` resides), it goes up folders in the filesystem recursively until it either finds it (often the case in monorepos) or hits the top level. - -To override this lookup process, the path can be configured explicitly using the setting `rescript.settings.binaryPath`. +## 🪄 Tips & Tricks ### Hide generated files You can configure VSCode to collapse the JavaScript files ReScript generates under its source ReScript file. This will "hide" the generated files in the VSCode file explorer, but still leaving them accessible by expanding the source ReScript file they belong to. -Open your VSCode settings and type `editor.filenesting`. Enable the feature and scroll down to patterns. +Open your VSCode settings and type: -The example has two patterns added: - -![Shows configuration of file nesting patterns in VSCode.](https://user-images.githubusercontent.com/1457626/168123605-43ef53cf-f371-4f38-b488-d3cd081879de.png) +```jsonc +"explorer.fileNesting.enabled": true, +"explorer.fileNesting.patterns": { + "*.res": "${capture}.mjs, ${capture}.js, ${capture}.cmi, ${capture}.cmt, ${capture}.cmj", + "*.resi": "${capture}.res" +}, +``` This nests implementations under interfaces if they're present and nests all generated files under the main ReScript file. Adapt and tweak to your liking. @@ -121,7 +160,7 @@ A screenshot of the result: ![Shows the end result in VSCode, with ReScript related files nested under eachother appropriately.](https://user-images.githubusercontent.com/1457626/168123647-400e2f09-31e3-45a2-b74b-190c7c207446.png) -## Use with Other Editors +## ⌨️ Use with Other Editors This repo also contains a language server that can power other editors. **However, the language server in this project is a pure implementation detail. We don't guarantee its stability for other editors' consumption** apart from Vim and Sublime Text. @@ -130,3 +169,15 @@ Still, if you'd like to use this language-server with other editors: - Get the release binaries from the Github Releases page. - Unzip the `.vsix` and get the `server` folder. That's the only folder you need. - The language server will be at `server/out/server.js`. Call it through node, and optionally pass `--stdio` if your editor doesn't support the default JSONRPC. + +## 📰 Changelog + +See [CHANGELOG](CHANGELOG.md) + +## 👏 How to Contribute + +Read our [Contributing Guide](CONTRIBUTING.md) + +## 📄 License + +See the [LICENSE](LICENSE) file for details. From 6173d5f9f905f9a5bb732b0b3ad41216d2dea9e0 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Fri, 22 Jul 2022 15:43:13 -0300 Subject: [PATCH 2/5] fix license url --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b2636c114..2cc5de38c 100644 --- a/README.md +++ b/README.md @@ -180,4 +180,4 @@ Read our [Contributing Guide](CONTRIBUTING.md) ## 📄 License -See the [LICENSE](LICENSE) file for details. +See the [LICENSE](./LICENSE.txt) file for details. From 7086e831685760c7b8cadb4dddf454f4c4d0e2de Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Sun, 24 Jul 2022 13:39:54 -0300 Subject: [PATCH 3/5] update readme --- README.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2cc5de38c..f02a0aed3 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ReScript VSCode -

The official VSCode plugin for ReScript

+

The Official VSCode plugin for ReScript

@@ -99,8 +99,9 @@ You'll find all ReScript specific settings under the scope `rescript.settings`. | Setting | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Autostarting ReScript builds | If there's no ReScript build running already in the opened project, the extension will prompt you and ask if you want to start a build automatically. You can turn off this automatic prompt via the setting `rescript.settings.askToStartBuild`. | +| Prompt to Start Build | If there's no ReScript build running already in the opened project, the extension will prompt you and ask if you want to start a build automatically. You can turn off this automatic prompt via the setting `rescript.settings.askToStartBuild`. | | ReScript Binary Path | The extension will look for the existence of a `/node_modules/.bin/rescript` file and use its directory as the `binaryPath`. If it does not find it at the project root (which is where the nearest `bsconfig.json` resides), it goes up folders in the filesystem recursively until it either finds it (often the case in monorepos) or hits the top level. To override this lookup process, the path can be configured explicitly using the setting `rescript.settings.binaryPath` | +| Inlay Hints (experimental) | This allows an editor to place annotations inline with text to display type hints. Enable using `rescript.settings.inlayHints.enable: true` | | Autostarting the Code Analyzer | The Code Analyzer needs to be started manually by default. However, you can configure the extension to start the Code Analyzer automatically via the setting `rescript.settings.autoRunCodeAnalysis`. | **Default settings:** @@ -114,6 +115,12 @@ You'll find all ReScript specific settings under the scope `rescript.settings`. // Path to the directory where ReScript binaries are. You can use it if you haven't or don't want to use the installed ReScript from node_modules in your project. "rescript.settings.binaryPath": null + +// Enable (experimental) inlay hints. +"rescript.settings.inlayHints.enable": true + +// Maximum length of character for inlay hints. Set to null to have an unlimited length. Inlay hints that exceed the maximum length will not be shown +"rescript.settings.inlayHints.maxLength": 25 ``` ## 🚀 Code Analyzer From 7a5c5871649f12102561d3dd9db012c64a242fa8 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Sun, 24 Jul 2022 13:42:06 -0300 Subject: [PATCH 4/5] sync with master --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index f02a0aed3..c00fab34f 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,7 @@ The only 2 themes we don't (and can't) support, due to their lack of coloring, a - Autocomplete. - Find references. - Rename. +- Inlay Hints - Snippets to ease a few syntaxes: - `external` features such as `@bs.module` and `@bs.val` - `try`, `for`, etc. From 6dbc8fe3f4a6c8908f1ae9e766ed5d495f3e38a2 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Mon, 25 Jul 2022 12:26:15 -0300 Subject: [PATCH 5/5] sync with master --- README.md | 25 ++++--------------------- 1 file changed, 4 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 4acfb71d8..6cc1b47a3 100644 --- a/README.md +++ b/README.md @@ -103,6 +103,7 @@ You'll find all ReScript specific settings under the scope `rescript.settings`. | Prompt to Start Build | If there's no ReScript build running already in the opened project, the extension will prompt you and ask if you want to start a build automatically. You can turn off this automatic prompt via the setting `rescript.settings.askToStartBuild`. | | ReScript Binary Path | The extension will look for the existence of a `/node_modules/.bin/rescript` file and use its directory as the `binaryPath`. If it does not find it at the project root (which is where the nearest `bsconfig.json` resides), it goes up folders in the filesystem recursively until it either finds it (often the case in monorepos) or hits the top level. To override this lookup process, the path can be configured explicitly using the setting `rescript.settings.binaryPath` | | Inlay Hints (experimental) | This allows an editor to place annotations inline with text to display type hints. Enable using `rescript.settings.inlayHints.enable: true` | +| Code Lens (experimental) | This tells the editor to add code lenses to function definitions, showing its full type above the definition. Enable using `rescript.settings.codeLens: true` | | Autostarting the Code Analyzer | The Code Analyzer needs to be started manually by default. However, you can configure the extension to start the Code Analyzer automatically via the setting `rescript.settings.autoRunCodeAnalysis`. | **Default settings:** @@ -122,6 +123,9 @@ You'll find all ReScript specific settings under the scope `rescript.settings`. // Maximum length of character for inlay hints. Set to null to have an unlimited length. Inlay hints that exceed the maximum length will not be shown "rescript.settings.inlayHints.maxLength": 25 + +// Enable (experimental) code lens for function definitions. +"rescript.settings.codeLens": true ``` ## 🚀 Code Analyzer @@ -148,27 +152,6 @@ Currently does not work for full monorepo dead code analysis (although it should ## 🪄 Tips & Tricks -### Inlay Hints (experimental) - -This allows an editor to place annotations inline with text to display type hints. - -```jsonc -// Enable (experimental) inlay hints. -rescript.settings.inlayHints.enable: true - -// Maximum length of character for inlay hints. Set to null to have an unlimited length. Inlay hints that exceed the maximum length will not be shown -rescript.settings.inlayHints.maxLength: 25 -``` - -### Code Lens (experimental) - -This tells the editor to add code lenses to function definitions, showing its full type above the definition. - -```jsonc -// Enable (experimental) code lens. -rescript.settings.codeLens: true -``` - ### Hide generated files You can configure VSCode to collapse the JavaScript files ReScript generates under its source ReScript file. This will "hide" the generated files in the VSCode file explorer, but still leaving them accessible by expanding the source ReScript file they belong to.