You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: CONTRIBUTING.md
+6-2
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,13 @@ Thank you for showing an interest in contributing.
4
4
5
5
This project is an early proof of concept of a language server for Sass written in Dart to make use of [sass_api](https://pub.dev/packages/sass_api).
6
6
7
-
Check the documentation to get started:
7
+
Note that the Sass parser currently requires a valid document to generate an AST ([sass/dart-sass#2476](https://github.com/sass/dart-sass/issues/2476)),
8
+
making it impossible to implement certain features such as completions/IntelliSense.
9
+
10
+
You are still welcome to test and contribute where you can. Check the documentation and list of open issues to get started:
Copy file name to clipboardexpand all lines: README.md
+24-5
Original file line number
Diff line number
Diff line change
@@ -2,10 +2,29 @@
2
2
3
3
This is a work-in-progress language server for Sass written in Dart to
4
4
use [sass_api](https://pub.dev/packages/sass_api).
5
+
It uses [the language server protocol](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#languageFeatures) (LSP).
5
6
6
-
See the [initial version roadmap](https://github.com/sass/dart-sass-language-server/issues/2) for the state of different features or check the documentation to get started:
[Development of new features is paused](https://github.com/sass/dart-sass/issues/2476). See the Issues and Pull request tabs for planned and partially implemented features.
10
+
11
+
The [Testing and debugging](docs/contributing/testing-and-debugging.md) docs explain how to run the language server from source code.
|[Go to definition](pkgs/sass_language_services/lib/src/features/go_to_definition/)|[textDocument/definition](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#textDocument_definition)|
See [Contributing](./CONTRIBUTING.md), but note that the parser currently requires a valid Sass document to generate an AST ([sass/dart-sass#2476](https://github.com/sass/dart-sass/issues/2476)).
1. Extend [language_configuration.dart](../../pkgs/sass_language_services/lib/src/configuration/language_configuration.dart) to parse the user's configuration for the feature.
13
+
2. Set defaults for the same user configuration in [the extension's package.json](../../extension/package.json) (look for the `"configuration"` key, and check for existing options).
14
+
3. Declare that the language server has the new capability in [language_server.dart](../../pkgs/sass_language_server/lib/src/language_server.dart) (look for `ServerCapabilities`).
15
+
4. Add a request handler for the feature in `language_server.dart` using `_connection.on<FeatureName>`. If a method doesn't exist for the feature, use the generic `_connection.peer.registerMethod()`.
16
+
5. Create a folder for the feature in [sass_language_services](../../pkgs/sass_language_services/lib/src/features/).
17
+
6. Implement the feature in a class that extends `LanguageFeature`.
18
+
- Look at existing features for some common patterns, such as how to parse a `TextDocument` to get the AST.
19
+
- You may want to know what AST node is at a given `Position`. See `node_at_offset_visitor.dart`.
20
+
- Use `findInWorkspace` to run a callback on each linked document, recursively (with a `lazy` option).
21
+
7. Add the feature to the public API in [language_services.dart](../../pkgs/sass_language_services/lib/src/language_services.dart).
22
+
8. Use the feature in the request handler in `language_server.dart`.
Copy file name to clipboardexpand all lines: docs/contributing/architecture.md
+10-2
Original file line number
Diff line number
Diff line change
@@ -15,11 +15,19 @@ We have this split so the language server features are reusable [for embedded la
15
15
16
16
This is the language server executable. Users will install this package, and the language client will run the server when needed.
17
17
18
+
This executable listens for incoming [JSON-RPC messages](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#languageServerProtocol). It handles [lifecycle messages](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#lifeCycleMessages) and [document synchronization](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#textDocument_synchronization) so the language server can keep track of the document and workspace state.
19
+
20
+
It has handlers for the different [language features](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#languageFeatures) and [workspace features](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#workspaceFeatures), but the implementation of those features are in [sass_language_services](#sass_language_services).
21
+
18
22
## sass_language_services
19
23
20
-
This is where you find the core functionality of the language server. Individual features are in the `lib/src/features/` directory. Each feature extends a base `LanguageFeature` class.
24
+
This is where you find the core functionality of the language server. Individual features are in the [lib/src/features/](../../pkgs/sass_language_services/lib/src/features/) directory. Each feature extends a base `LanguageFeature` class.
25
+
26
+
When used, all features parse a given `TextDocument` using [`sass_api`](https://pub.dev/packages/sass_api) to get the [`Stylesheet` node](https://pub.dev/documentation/sass_api/latest/sass/Stylesheet-class.html). Parses are cached, along with other often-used information such as resolved links.
27
+
28
+
A feature typically returns a `Future` of some kind so it can traverse linked documents in order to be workspace-aware for features like Go to definition and Hover.
21
29
22
-
When used, all features parse the given `TextDocument` using [`sass_api`](https://pub.dev/packages/sass_api) to get the [`Stylesheet` node](https://pub.dev/documentation/sass_api/latest/sass/Stylesheet-class.html). Parses are cached, along with other often-used information such as resolved links.
30
+
A feature also typically returns a language server protocol response type, such as [Hover](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#hover).
This builds an executable for your current operating system named `sass-language-server`.
18
+
This builds an executable for your current operating system named `sass-language-server`. You can add this to your `PATH` and use it with any editor that has an LSP client.
19
+
20
+
Run `sass-language-server --help` to see available options.
Copy file name to clipboardexpand all lines: docs/contributing/development-environment.md
-3
Original file line number
Diff line number
Diff line change
@@ -16,9 +16,6 @@ To work on the language extension, or test your changes in Visual Studio Code:
16
16
17
17
-[Node.js v20 or higher](https://nodejs.org/en)
18
18
-[Visual Studio Code](https://code.visualstudio.com/) or [VSCodium](https://github.com/VSCodium/vscodium) (we'll refer to Visual Studio Code, VS Code for short, in the documentation)
19
-
20
-
### Recommended software
21
-
22
19
-[Dart extension for VS Code](https://github.com/Dart-Code/Dart-Code)
Copy file name to clipboardexpand all lines: docs/contributing/testing-and-debugging.md
+13-26
Original file line number
Diff line number
Diff line change
@@ -4,19 +4,23 @@ Here we assume you have set up a [development environment](./development-environ
4
4
5
5
## Run the language extension and server
6
6
7
-
The quickest way to test the language server is to debug the language extension in Visual Studio Code. A debugging launch configuration is included in the repository. To use it:
7
+
The quickest way to test the language server is to debug the language extension in [Visual Studio Code](https://code.visualstudio.com). A debugging launch configuration is included in the repository. To use it:
8
8
9
9
1. Open this repository in VS Code.
10
-
2. Go to the Run and Debug view.
10
+
2. Go to the [Run and Debug view](https://code.visualstudio.com/docs/editor/debugging).
11
11
3. Pick Debug extension and language server from the menu.
12
12
4. Click Start debugging.
13
13
14
14
This will open another window of Visual Studio Code, this one running as an `[Extension Development Host]`.
15
15
16
-
### Find the link to Dart DevTools or VM service
16
+
### Attach the debugger
17
17
18
18
When debugging, the client runs [`dart run --enable-vm-service`](https://github.com/sass/dart-sass-language-server/blob/main/extension/src/server.ts#L49)
19
-
in the local `sass_language_server` package.
19
+
in the local `sass_language_server` package. This lets us attach a debugger to set breakpoints.
20
+
21
+
The video below demonstrates how to attach a debugger.
Use the `[Extension Development Host]` window to find the link to open Dart DevTools or to [attach the debugger](#attach-to-language-server).
22
26
@@ -32,37 +36,20 @@ The Dart VM service is listening on http://127.0.0.1:8181/SMIxtkPzlAY=/
32
36
The Dart DevTools debugger and profiler is available at: http://127.0.0.1:8181/SMIxtkPzlAY=/devtools/?uri=ws://127.0.0.1:8181/SMIxtkPzlAY=/ws
33
37
```
34
38
35
-
Click the second link to open Dart DevTools, or copy the first link to [attach a debugger](#attach-to-language-server).
36
-
37
-
38
-
39
-
### Attach to language server
40
-
41
-
The debugger in Dart DevTools is deprecated in favor the debugger that ships with [Dart for Visual Studio Code][vscodedart].
42
-
43
-
To start debugging in VS Code (provided you have the Dart extension):
44
-
45
-
1.[Run the language server and extension](#run-the-language-extension-and-server) in debug mode.
46
-
2.[Find the link to the Dart VM](#find-the-link-to-dart-devtools-or-vm-service).
47
-
48
-
You should see output similar to this in the `[Extension Development Host]`.
49
-
50
-
```
51
-
The Dart VM service is listening on http://127.0.0.1:8181/SMIxtkPzlAY=/
52
-
The Dart DevTools debugger and profiler is available at: http://127.0.0.1:8181/SMIxtkPzlAY=/devtools/?uri=ws://127.0.0.1:8181/SMIxtkPzlAY=/ws
53
-
```
54
-
55
39
Copy the first link, then go back to the Run and debug window where you started the language server and extension.
56
40
57
41
1. Click the Run and debug drop-down and run `Attach to language server`.
58
42
2. Paste the link you copied and hit Enter.
59
43
60
44
Your debugger should be attached, allowing you to place breakpoints and step through code.
61
45
62
-
_The video below demonstrates how to attach a debugger._
The second link in the Output pane is to the [Dart DevTools](https://dart.dev/tools/dart-devtools).
65
49
50
+
The debugger in Dart DevTools is deprecated in favor the debugger that ships with [Dart for Visual Studio Code][vscodedart], but the DevTools have other usefool tools such as a memory and CPU profiler.
51
+
52
+
66
53
67
54
### Test in VS Code without built-in SCSS features
Copy file name to clipboardexpand all lines: pkgs/sass_language_server/README.md
+6-2
Original file line number
Diff line number
Diff line change
@@ -4,12 +4,16 @@ A Dart implementation of a language server for Sass. The language server uses th
4
4
5
5
## Installing the Sass language server
6
6
7
-
### From Pub
7
+
See the contributing documentation for [how to build the language server](../../docs/contributing/building.md) so you can add it to your `PATH`.
8
+
9
+
<!--
8
10
9
-
<!-- Assuming this is how it will be -->
11
+
### From Pub
10
12
11
13
If you're a [Dart](https://dart.dev/get-dart) user, you can install the Sass language server globally using `pub global activate sass_language_server`, which will provide a `sass-language-server` executable.
12
14
15
+
-->
16
+
13
17
## Using the Sass language server
14
18
15
19
To use `sass-language-server` your editor needs a language client.
/// Includes an executable `sass-language-server`. Run `sass-language-server --help` to see available options.
4
+
///
5
+
/// The server listens for incoming [JSON-RPC messages](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#languageServerProtocol). It handles [lifecycle messages](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#lifeCycleMessages) and [document synchronization](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#textDocument_synchronization) so the language server can keep track of the document and workspace state.
6
+
///
7
+
/// It has handlers for the different [language features](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#languageFeatures) and [workspace features](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#workspaceFeatures), but the implementation of those features are in `sass_language_services`.
0 commit comments