chore: add VSCode extension page

.cargo/config.toml

@@ -5,6 +5,7 @@ codegen = "run -p xtask_codegen --"
 codegen-configuration = "run -p xtask_codegen --features configuration -- configuration"
 codegen-schema = "run -p xtask_codegen --features schema -- schema"
 codegen-bindings = "run -p xtask_codegen --features schema -- bindings"
+codegen-website = "run -p xtask_codegen --features website -- website"
 lintdoc = "run -p xtask_lintdoc --"
 documentation = """
     doc \

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## CLI
+## Configuration
+## Editors
+## Formatter
+## Linter
+## Parser
+## VSCode
+## JavaScript APIs
+
+## 12.1.0
+
 ### CLI
 
 #### Other changes
@@ -34,6 +45,13 @@ when there are breaking changes.
 - Fix false positive diagnostics that [`useCamelCase`](https://docs.rome.tools/lint/rules/usecamelcase/) caused to private class members
 
 ### Configuration
+
+- Add `vcs` property, to opt-in the VCS integration:
+  - `vcs.enabled`, to enable or not the integration;
+  - `vcs.clientKind`, the supported clients;
+  - `vcs.useIgnoreFile`, to ignore the files/paths inside the file;
+  - `vcs.root`, an optional path to the root of the VCS;
+
 ### Editors
 
  - Fix an issue where the VSCode extension duplicates text when using VSCode git utilities [#4338]

website/src/components/Vscode.astro

@@ -0,0 +1,7 @@
+---
+import Vcscode from "/components/reference/README.md"
+---
+
+<div>
+	<Vcscode />
+</div>

website/src/components/reference/README.md

@@ -0,0 +1,111 @@
+# Rome VS Code Extension
+
+[Rome](https://rome.tools/) unifies your development stack by combining the functionality of separate tools. It uses a single configuration file, has fantastic performance, and works with any stack. This extension brings Rome to your editor so that you can:
+
+- Format files *on save* or when issuing the *Format Document* command
+- See lints while you type and apply code fixes
+- Perform refactors
+
+## Installation
+
+You can install the code extension by heading to the extension's [Visual Studio Code Market Place page](https://marketplace.visualstudio.com/items?itemName=rome.rome) or from within VS Code by either:
+
+- Open the *extensions* tab (_View_ → _Extensions)_ and search for Rome.
+- Open the _Quick Open Overlay_ (<kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd>P</kbd> or _Go -> Go to File_), enter `ext install rome.rome`, and hit enter.
+
+## Getting Started
+
+### Default Formatter
+
+Configure Rome as the default formatter for supported files to ensure that VS Code uses Rome over other formatters that you may have installed. You can do so by opening a JavaScript or TypeScript and then:
+
+- Open the Command Palette (<kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd title="Shift">⇧</kbd>+<kbd>P</kbd> or View → Command Palette)
+- Select _Format Document With…_
+- Select _Configure Default Formatter…_
+- Select Rome
+
+You can also enable Rome for specific languages only:
+
+- [Open the `settings.json`](https://code.visualstudio.com/docs/getstarted/settings#_settingsjson): open the _Command Palette_(<kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd title="Shift">⇧</kbd>+<kbd>P</kbd>) and select _Preferences: Open User Settings (JSON)_
+- And set the `editor.defaultFormatter` to `rome.rome` for the desired language
+
+```json
+{
+	"editor.defaultFormatter": "<other formatter>",
+	"[javascript]": {
+		"editor.defaultFormatter": "rome.rome"
+	}
+}
+```
+
+This configuration sets Rome as the default formatter for JavaScript files. All other files will be formatted using `<other formatter>`
+
+## Configuration Resolution
+
+The extension automatically loads the `rome.json` file from the workspace’s root directory.
+
+## Rome Resolution
+
+The extension tries to use Rome from your project's local dependencies (`node_modules/rome`). We recommend adding Rome as a project dependency to ensure that NPM scripts and the extension use the same Rome version.
+
+You can also explicitly specify the `rome` binary the extension should use by configuring the `rome.lspBin` setting in your editor options.
+
+If the project has no dependency on Rome and no explicit path is configured, the extension uses the Rome version included in its bundle.
+
+## Usage
+
+### Format document
+
+To format an entire document, open the _Command Palette_ (<kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd title="Shift">⇧</kbd>+<kbd>P</kbd>) and select _Format Document_.
+
+To format a text range, select the text you want to format, open the _Command Palette_ (<kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd title="Shift">⇧</kbd>+<kbd>P</kbd>), and select _Format Selection_.
+
+### Format on save
+
+Rome respects VS Code's _Format on Save_ setting. To enable format on save, open the settings (_File_ -> _Preferences_ -> _Settings_), search for `editor.formatOnSave`, and enable the option.
+
+### Fix on save
+
+Rome respects VS Code's _Code Actions On Save_ setting. To enable fix on save, add `"editor.codeActionsOnSave": { "quickfix.rome": true }` in vscode settings.json.
+
+### Imports Sorting [Experimental]
+
+The Rome VS Code extension has experimental support for imports sorting through the "Organize Imports" code action. By default this action can be run using the <kbd title="Shift">⇧</kbd>+<kbd>Alt</kbd>+<kbd>O</kbd> keyboard shortcut, or is accessible through the _Command Palette_ (<kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd title="Shift">⇧</kbd>+<kbd>P</kbd>) by selecting _Organize Imports_.
+
+You can add the following to your editor configuration if you want the action to run automatically on save instead of calling it manually:
+
+```json
+{
+	"editor.codeActionsOnSave":{
+		"source.organizeImports.rome": true
+	}
+}
+```
+
+## Extension Settings
+
+### `rome.lspBin`
+
+The `rome.lspBin` option overrides the Rome binary used by the extension. The workspace folder is used as the base path if the path is relative.
+
+### `rome.rename`
+
+Enables Rome to handle renames in the workspace (experimental).
+
+### `rome.requireConfiguration`
+
+Disables formatting, linting, and syntax errors for projects without a `rome.json` file. Requires Rome 12 or newer.
+
+## Known limitations
+
+### Configuration per sub-directory
+
+Rome doesn’t yet support loading the `rome.json` file from a directory other than the workspace root ([issue 3576](https://github.com/rome/tools/issues/3576), [issue 3289](https://github.com/rome/tools/issues/3289)). That means it is currently impossible to enable Rome only for a specific sub-folder or to use different configurations for different folders.
+
+### Configuration resolution for multi-root workspaces
+
+Rome isn't yet able to pick up the `rome.json` configuration in [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) if the configuration isn't in the first root folder ([issue 3538](https://github.com/rome/tools/issues/3538)). You can work around this limitation by making the folder with the configuration the first root folder of the workspace (drag it to the top).
+
+### Disable Rome for workspaces without a `rome.json` configuration
+
+You can set Rome's [`rome.requireConfiguration`](#romerequireconfiguration) setting to `true` to disable Rome's formatter, linter, and syntax errors for projects without a `rome.json` file.

website/src/pages/vscode.mdx

@@ -0,0 +1,117 @@
+---
+title: VSCode extension
+emoji: 💻
+category: reference
+description: Notes about the Rome's VSCode extension
+---
+# Rome VS Code Extension
+
+[Rome](https://rome.tools/) unifies your development stack by combining the functionality of separate tools. It uses a single configuration file, has fantastic performance, and works with any stack. This extension brings Rome to your editor so that you can:
+
+- Format files *on save* or when issuing the *Format Document* command
+- See lints while you type and apply code fixes
+- Perform refactors
+
+## Installation
+
+You can install the code extension by heading to the extension's [Visual Studio Code Market Place page](https://marketplace.visualstudio.com/items?itemName=rome.rome) or from within VS Code by either:
+
+- Open the *extensions* tab (_View_ → _Extensions)_ and search for Rome.
+- Open the _Quick Open Overlay_ (<kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd>P</kbd> or _Go -> Go to File_), enter `ext install rome.rome`, and hit enter.
+
+## Getting Started
+
+### Default Formatter
+
+Configure Rome as the default formatter for supported files to ensure that VS Code uses Rome over other formatters that you may have installed. You can do so by opening a JavaScript or TypeScript and then:
+
+- Open the Command Palette (<kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd title="Shift">⇧</kbd>+<kbd>P</kbd> or View → Command Palette)
+- Select _Format Document With…_
+- Select _Configure Default Formatter…_
+- Select Rome
+
+You can also enable Rome for specific languages only:
+
+- [Open the `settings.json`](https://code.visualstudio.com/docs/getstarted/settings#_settingsjson): open the _Command Palette_(<kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd title="Shift">⇧</kbd>+<kbd>P</kbd>) and select _Preferences: Open User Settings (JSON)_
+- And set the `editor.defaultFormatter` to `rome.rome` for the desired language
+
+```json
+{
+	"editor.defaultFormatter": "<other formatter>",
+	"[javascript]": {
+		"editor.defaultFormatter": "rome.rome"
+	}
+}
+```
+
+This configuration sets Rome as the default formatter for JavaScript files. All other files will be formatted using `<other formatter>`
+
+## Configuration Resolution
+
+The extension automatically loads the `rome.json` file from the workspace’s root directory.
+
+## Rome Resolution
+
+The extension tries to use Rome from your project's local dependencies (`node_modules/rome`). We recommend adding Rome as a project dependency to ensure that NPM scripts and the extension use the same Rome version.
+
+You can also explicitly specify the `rome` binary the extension should use by configuring the `rome.lspBin` setting in your editor options.
+
+If the project has no dependency on Rome and no explicit path is configured, the extension uses the Rome version included in its bundle.
+
+## Usage
+
+### Format document
+
+To format an entire document, open the _Command Palette_ (<kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd title="Shift">⇧</kbd>+<kbd>P</kbd>) and select _Format Document_.
+
+To format a text range, select the text you want to format, open the _Command Palette_ (<kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd title="Shift">⇧</kbd>+<kbd>P</kbd>), and select _Format Selection_.
+
+### Format on save
+
+Rome respects VS Code's _Format on Save_ setting. To enable format on save, open the settings (_File_ -> _Preferences_ -> _Settings_), search for `editor.formatOnSave`, and enable the option.
+
+### Fix on save
+
+Rome respects VS Code's _Code Actions On Save_ setting. To enable fix on save, add `"editor.codeActionsOnSave": { "quickfix.rome": true }` in vscode settings.json.
+
+### Imports Sorting [Experimental]
+
+The Rome VS Code extension has experimental support for imports sorting through the "Organize Imports" code action. By default this action can be run using the <kbd title="Shift">⇧</kbd>+<kbd>Alt</kbd>+<kbd>O</kbd> keyboard shortcut, or is accessible through the _Command Palette_ (<kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd title="Shift">⇧</kbd>+<kbd>P</kbd>) by selecting _Organize Imports_.
+
+You can add the following to your editor configuration if you want the action to run automatically on save instead of calling it manually:
+
+```json
+{
+	"editor.codeActionsOnSave":{
+		"source.organizeImports.rome": true
+	}
+}
+```
+
+## Extension Settings
+
+### `rome.lspBin`
+
+The `rome.lspBin` option overrides the Rome binary used by the extension. The workspace folder is used as the base path if the path is relative.
+
+### `rome.rename`
+
+Enables Rome to handle renames in the workspace (experimental).
+
+### `rome.requireConfiguration`
+
+Disables formatting, linting, and syntax errors for projects without a `rome.json` file. Requires Rome 12 or newer.
+
+## Known limitations
+
+### Configuration per sub-directory
+
+Rome doesn’t yet support loading the `rome.json` file from a directory other than the workspace root ([issue 3576](https://github.com/rome/tools/issues/3576), [issue 3289](https://github.com/rome/tools/issues/3289)). That means it is currently impossible to enable Rome only for a specific sub-folder or to use different configurations for different folders.
+
+### Configuration resolution for multi-root workspaces
+
+Rome isn't yet able to pick up the `rome.json` configuration in [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) if the configuration isn't in the first root folder ([issue 3538](https://github.com/rome/tools/issues/3538)). You can work around this limitation by making the folder with the configuration the first root folder of the workspace (drag it to the top).
+
+### Disable Rome for workspaces without a `rome.json` configuration
+
+You can set Rome's [`rome.requireConfiguration`](#romerequireconfiguration) setting to `true` to disable Rome's formatter, linter, and syntax errors for projects without a `rome.json` file.

xtask/codegen/Cargo.toml

@@ -36,4 +36,5 @@ rome_service = { path = "../../crates/rome_service", features = ["schemars"], op
 
 [features]
 configuration = ["rome_analyze", "rome_js_analyze", "rome_js_syntax", "pulldown-cmark"]
+website = []
 schema = ["schemars", "serde_json", "rome_rowan", "rome_service", "rome_js_syntax", "rome_js_factory", "rome_js_formatter", "rome_json_formatter", "rome_json_parser", "rome_diagnostics"]

xtask/codegen/src/generate_website.rs

@@ -0,0 +1,21 @@
+use std::fs;
+use xtask::{project_root, Result};
+
+const FRONTMATTER: &str = r#"---
+title: VSCode extension
+emoji: 💻
+category: reference
+description: Notes about the Rome's VSCode extension
+---
+"#;
+
+pub fn generate_website() -> Result<()> {
+    fs::remove_file(project_root().join("website/src/pages/vscode.mdx")).ok();
+    let readme = fs::read_to_string(project_root().join("editors/vscode/README.md"))?;
+
+    let page = format!("{FRONTMATTER}{readme}");
+
+    fs::write(project_root().join("website/src/pages/vscode.mdx"), page)?;
+
+    Ok(())
+}

xtask/codegen/src/lib.rs

@@ -11,6 +11,7 @@ mod generate_nodes;
 mod generate_nodes_mut;
 mod generate_syntax_factory;
 mod generate_syntax_kinds;
+pub mod generate_website;
 mod json_kinds_src;
 mod kinds_src;
 mod parser_tests;
@@ -28,6 +29,7 @@ use xtask::{glue::fs2, Mode, Result};
 pub use self::ast::generate_ast;
 pub use self::formatter::generate_formatters;
 pub use self::generate_analyzer::generate_analyzer;
+pub use self::generate_website::generate_website;
 pub use self::parser_tests::generate_parser_tests;
 pub use self::unicode::generate_tables;
 

xtask/codegen/src/main.rs

@@ -22,6 +22,7 @@ use crate::promote_rule::promote_rule;
 use generate_new_lintrule::*;
 use xtask_codegen::{
     generate_analyzer, generate_ast, generate_formatters, generate_parser_tests, generate_tables,
+    generate_website,
 };
 
 fn main() -> Result<()> {
@@ -77,12 +78,18 @@ fn main() -> Result<()> {
             generate_workspace_bindings(Mode::Overwrite)?;
             Ok(())
         }
+        #[cfg(feature = "website")]
+        "website" => {
+            generate_website()?;
+            Ok(())
+        }
         "all" => {
             generate_tables()?;
             generate_grammar(args);
             generate_parser_tests(Mode::Overwrite)?;
             generate_formatters();
             generate_analyzer()?;
+            generate_website()?;
             #[cfg(feature = "configuration")]
             generate_rules_configuration(Mode::Overwrite)?;
             #[cfg(feature = "schema")]