diff --git a/data/sidebar_manual_v1200.json b/data/sidebar_manual_v1200.json index a68a5336c..516432f57 100644 --- a/data/sidebar_manual_v1200.json +++ b/data/sidebar_manual_v1200.json @@ -67,7 +67,8 @@ "warning-numbers" ], "Guides": [ - "converting-from-js" + "converting-from-js", + "editor-code-analysis" ], "Extra": [ "newcomer-examples", diff --git a/pages/docs/manual/v12.0.0/editor-code-analysis.mdx b/pages/docs/manual/v12.0.0/editor-code-analysis.mdx new file mode 100644 index 000000000..eb4b7b612 --- /dev/null +++ b/pages/docs/manual/v12.0.0/editor-code-analysis.mdx @@ -0,0 +1,158 @@ +--- +title: "Editor" +metaTitle: "Editor" +description: "Documentation about ReScript editor plugins and code analysis" +canonical: "/docs/manual/v12.0.0/editor-plugins" +--- + +# Guide: Dead Code Analysis in ReScript + +This guide provides a detailed walkthrough on how to leverage ReScript’s powerful dead code analysis tools to maintain a clean, efficient, and distraction-free codebase. + +Dead code refers to code that's present in your codebase but is never executed. It can lead to: + +- Increased compilation times +- Confusion during development +- Misleading assumptions about functionality + +ReScript’s language design allows for accurate and efficient dead code analysis using the **ReScript Code Analyzer**, available via the official VSCode extension. + +### Prerequisites + +- ReScript VSCode extension (v1.8.2 or higher) + +### Activation + +1. Open the Command Palette: `Cmd/Ctrl + P` +2. Run: `> ReScript: Start Code Analyzer` + +### Deactivation + +- Run: `> ReScript: Stop Code Analyzer` +- Or click “Stop Code Analyzer” in the status bar + +### Result + +- The “Problems” pane populates with dead code warnings and suggestions. + +## Real-World Use Cases + +### 1. **Unused Record Fields** + +```rescript +type useReturn = { + items: array, + toggleItemChecked: string => unit, // ← Never used + setCheckedOnItem: (string, bool) => unit, + checkAll: unit => unit, + uncheckAll: unit => unit, +} +``` + +Remove unused fields to simplify code. + +### 2. **Unused Variant Cases** + +```rescript +type textType = + | Text(string) + | TextWithIcon({icon: React.element, text: string}) + | Render(React.element) // ← Never constructed +``` + +Removing unused variants allows simplifying rendering logic. + +### 3. **Unused Parts of State** + +```rescript +type validationState = Idle | Invalid | Valid + +type state = { + oldPassword: string, + newPassword: string, + newPasswordRepeated: string, + validationState: validationState, // ← Never read +} +``` + +Old validation logic might remain after refactors—clean it up. + +### 4. **Unnecessary Interface Exposure** + +```rescript +// DrilldownTarget.resi +MetricParam.parse // ← Never used +MetricParam.serialize // ← Never used +``` + +Keep interfaces minimal by removing unused exports. + +### 5. **Unused Functions** + +```rescript +let routerUrlToPath = ... // ← Never used +let routeUrlStartsWith = ... // ← Never used +``` + +Removing these often uncovers further unused logic. + +### 6. **Unused Components** + +Components never referenced in production should be removed, unless explicitly preserved. + + +## Keeping Some Dead Code + +### Use `@dead` and `@live` + +#### `@dead` + +Suppresses warnings but notifies if code becomes alive again. + +```rescript +type user = { + name: string, + @dead age: int, +} +``` + +#### `@live` + +Permanently marks code as alive (no future warnings). + +```rescript +@live +let getUserName = user => user.name +``` + +## Configuration + +Add to your `rescript.json`: + +```json +"reanalyze": { + "analysis": ["dce"], + "suppress": ["src/bindings", "src/stories", "src/routes"], + "unsuppress": [], + "transitive": false +} +``` + +### Options: + +- **analysis**: Enables dead code analysis (`"dce"`) +- **suppress**: Silences reporting for paths (still analyzes) +- **unsuppress**: Re-enables reports within suppressed paths +- **transitive**: Controls reporting of indirectly dead code + +**Recommendation:** Set `transitive: false` for incremental cleanup. + +## Summary + +ReScript’s dead code analyzer helps you: + +- Incrementally clean up your codebase +- Avoid confusion and complexity +- Improve long-term maintainability + +Use it regularly for the best results. diff --git a/pages/docs/manual/v12.0.0/editor-plugins.mdx b/pages/docs/manual/v12.0.0/editor-plugins.mdx index 471f1b7e2..59acdeeca 100644 --- a/pages/docs/manual/v12.0.0/editor-plugins.mdx +++ b/pages/docs/manual/v12.0.0/editor-plugins.mdx @@ -1,19 +1,52 @@ --- -title: "Editor Plugins" -description: "List of ReScript editor plugins" +title: "Editor" +metaTitle: "Editor" +description: "Documentation about ReScript editor plugins and code analysis" canonical: "/docs/manual/v12.0.0/editor-plugins" --- -# Editor Plugins +# Editor + +This section is about the editor plugin for ReScript. It adds syntax highlighting, autocomplete, type hints, formatting, code navigation, code analysis for `.res` and `.resi` files. + + +## Plugins - [VSCode](https://marketplace.visualstudio.com/items?itemName=chenglou92.rescript-vscode) - [Sublime Text](https://github.com/rescript-lang/rescript-sublime) - [Vim/Neovim](https://github.com/rescript-lang/vim-rescript) -## Community Supported +### Community Supported We don't officially support these; use them at your own risk! - [Neovim Tree-sitter](https://github.com/nkrkv/nvim-treesitter-rescript) - [IDEA](https://github.com/reasonml-editor/reasonml-idea-plugin) - [Emacs](https://github.com/jjlee/rescript-mode) + + +## Code analysis + +The code analysis provides extra checks for your ReScript project, such as detecting dead code and unhandled exceptions. It's powered by [reanalyze](https://github.com/rescript-association/reanalyze), which is built into the extension—no separate install required. + +### How to Use + +- Open the command palette and run: + `ReScript: Start Code Analyzer` +- Warnings like dead code will show inline in the editor. +- Suppression actions are available where applicable. +- To stop analysis, click **Stop Code Analyzer** in the status bar. + +### Configuration + +Add a `reanalyze` section to your `rescript.json` to control what the analyzer checks or ignores. You’ll get autocomplete for config options in the editor. +More details: [reanalyze config docs](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson) + +### Guide + +Look [here](editor-code-analysis) for a more detailed guide about how to use the code analysis tool. + +### Caveats + +- Doesn't support cross-package dead code analysis in monorepos. Run it per package instead. +