Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor language service #137

Merged
merged 7 commits into from
Apr 24, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 2 additions & 0 deletions .eslintignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
vscode-extension/test/e2e/
vscode-extension/test/web/
1 change: 1 addition & 0 deletions .eslintrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
],
"plugins": ["@typescript-eslint", "prettier", "import"],
"rules": {
"@typescript-eslint/ban-types": "off",
"@typescript-eslint/no-namespace": "off",
"@typescript-eslint/no-explicit-any": "off",
"import/no-unresolved": "off",
Expand Down
2 changes: 2 additions & 0 deletions .github/FUNDING.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
github: [wkillerud]
ko_fi: williamkillerud
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,14 @@
logs/
*.log
npm-debug.log*
.cpuprofile
.heapprofile

# Dependency directory
node_modules/
!vscode-extension/test/fixtures/node_modules
!vscode-extension/test/fixtures/completion/node_modules
!vscode-extension/test/fixtures/pkg-import/node_modules

# Compiled and temporary files
dist/
Expand Down
2 changes: 1 addition & 1 deletion .vscode/extensions.json
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
"recommendations": ["amodio.tsl-problem-matcher"]
"recommendations": ["vitest.explorer"]
}
45 changes: 4 additions & 41 deletions .vscode/launch.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
"autoAttachChildProcesses": true
},
{
"name": "Launch Web Extension in VS Code",
"name": "Launch web extension",
"type": "extensionHost",
"debugWebWorkerHost": true,
"request": "launch",
Expand All @@ -24,51 +24,14 @@
"autoAttachChildProcesses": true
},
{
"name": "Integration Tests",
"name": "Launch end-to-end tests",
"type": "extensionHost",
"request": "launch",
"runtimeExecutable": "${execPath}",
"args": [
"--extensionDevelopmentPath=${workspaceFolder}/vscode-extension",
"--extensionTestsPath=${workspaceFolder}/vscode-extension/out/test/e2e/suite",
"${workspaceFolder}/vscode-extension/out/test/fixtures/"
],
"outFiles": ["${workspaceFolder}/vscode-extension/out/test/e2e/**/*.js"]
},
{
"type": "chrome",
"request": "attach",
"name": "Attach to web integration test",
"skipFiles": ["<node_internals>/**"],
"port": 9229,
"timeout": 30000, // give it time to download vscode if needed
"resolveSourceMapLocations": [
"!**/vs/**", // exclude core vscode sources
"!**/static/build/extensions/**" // exclude built-in extensions
],
"presentation": {
"hidden": true
}
},
{
"type": "node",
"request": "launch",
"name": "Launch web integration test",
"outputCapture": "std",
"program": "${workspaceFolder}/vscode-extension/out/test/web/runTest.js",
"args": ["--waitForDebugger=9229"],
"cascadeTerminateToConfigurations": ["Launch web integration test"],
"presentation": {
"hidden": true
}
}
],
"compounds": [
{
"name": "Web Integration Tests",
"configurations": [
"Launch web integration test",
"Attach to web integration test"
"--extensionTestsPath=${workspaceFolder}/vscode-extension/test/e2e/suite",
"${workspaceFolder}/vscode-extension/test/fixtures/"
]
}
]
Expand Down
1 change: 0 additions & 1 deletion .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
{
"mochaExplorer.cwd": "server",
"somesass.scannerDepth": 30,
"somesass.scannerExclude": [
"**/.git/**",
Expand Down
10 changes: 0 additions & 10 deletions .vscode/tasks.json

This file was deleted.

10 changes: 10 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
While not an official Sass project, we strive to follow the [Sass Community Guidelines](https://sass-lang.com/community-guidelines/).

- Be considerate
- Be open and inviting
- Be respectful
- Take responsibility for our words and actions
- Be collaborative
- Value decisiveness, clarity and open communication
- Be responsive and helpful
- Step down considerately
151 changes: 3 additions & 148 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,152 +1,8 @@
# Contributing

Thank you for showing an interest in contributing, be it to the language server or to the VS Code extension 🌟
Thank you for showing an interest in contributing, be it to the language server, to the VS Code extension, the documentation, or in some other way 🌟

Before you start, please make a [new Issue](https://github.com/wkillerud/some-sass/issues/new/choose). I don't always make new issues for all the things I work on. By making a new Issue we can avoid duplicating our efforts.

## Development environment

You need these things installed:

- Node.js LTS
- For the VS Code extension, but recommended either way:
- Visual Studio Code stable
- The extension _TypeScript + Webpack Problem Matchers_ (`amodio.tsl-problem-matcher`)

```
# install dependencies
npm install
# confirm existing tests are running
npm test
```

### If using VS Code

Go to the _Run and Debug_ pane in VS Code and run _Launch extension_. Rebuild the project and restart the debugging session to see changes take effect.

If you get a warning, ensure you have the _TypeScript + Webpack Problem Matchers_ (`amodio.tsl-problem-matcher`) extension installed and active.

## Architecture

This extension consists of a [client for VS Code](https://github.com/wkillerud/some-sass/blob/main/vscode-extension) and a [language server](https://github.com/wkillerud/some-sass/blob/main/packages/language-server). The client starts the server on activation.

The server then:

1. [scans the workspace](https://github.com/wkillerud/some-sass/blob/main/packages/language-server/src/scanner.ts)
2. [parses](https://github.com/wkillerud/some-sass/blob/main/packages/language-server/src/parser/parser.ts) SCSS code
3. puts the parsed documents in a [in-memory context](https://github.com/wkillerud/some-sass/blob/main/packages/language-server/src/context-provider.ts)

The client requests information from the server when needed, and notifies the server when a file changes.

See [packages/langauge-server/src/server.ts](https://github.com/wkillerud/some-sass/blob/main/packages/langauge-server/src/server.ts) for the event listeners on the server side, and the [features folder in the server](https://github.com/wkillerud/some-sass/tree/main/packages/language-server/src/features) for code supporting the different features.

```mermaid
sequenceDiagram
Client->>+Server: Extension activated
Server->Server: Scans for SCSS
Server->-Server: Parses SCSS
Client->>Server: Hover
Server-->>Client: Provide hover info
Client->>+Server: Changing file
Server->Server: Re-parse changed file
Server-->>-Client: Provide code suggestions
```

### Browser version

This extension also works with VS Code in the browser. It works more or less the same as the regular Node version, except it doesn't have direct access to the file system.

To work around this, [the server](https://github.com/wkillerud/some-sass/blob/main/packages/language-server/src/file-system-provider.ts) makes requests to [the client](https://github.com/wkillerud/some-sass/blob/main/vscode-extension/src/client.ts), which then uses the [FileSystem API](https://code.visualstudio.com/api/references/vscode-api#FileSystem) to work with files and directories, before sending the result back to the server.

```mermaid
sequenceDiagram
Client->>Server: Extension activated
Server->>Client: Get list of files in the workspace
Client-->>Server: List of files
Server->>Client: Get contents of file
Client-->>+Server: Contents of file
Server->-Server: Parse SCSS
Client->>Server: Hover
Server-->>Client: Provide hover info
```

## Manual testing

To test your changes in VS Code:

- Go to the Run and Debug section
- Run the `Launch extension` configuration

A new window should open with the title `[Extension Development Host]`. In this window you can open whatever project you want to use for testing. If you don't have one you can open the folder `vscode-extension/test/fixtures/` in this repository.

Every time you make a change you need to restart `Launch extension`.

Test your changes and see if they work.

### Test the browser version

This extension also works in the browser. Run `npm run start:web` to open VS Code in a browser and test your changes.

Docs: [Test your web extension](https://code.visualstudio.com/api/extension-guides/web-extensions#test-your-web-extension)

## Debugging

### Debugging the Node (or regular) version

You can set breakpoints to inspect what happens in your code. At time of writing you must set these breakpoints in the _compiled output_ in `vscode-extension/dist/node-server.js`.

Open `vscode-extension/dist/node-server.js`, search for a function name close to where you want to debug, and place breakpoints where you would like. Then:

- Go to the Run and Debug pane in VS Code.
- Select `Launch extension` and start debugging.

You should see the code pause on your breakpoint. If not, try to place breakpoints elsewhere. Something unexpected may stop you from reaching your code.

### Debugging the browser version

You have two options when to debug the browser version:

1. Run in VS Code:

- Go to the Run and Debug section
- Run the _Launch Web Extension in VS Code_ configuration
- Open `vscode-extension/dist/browser-server.js`, search for a function name close to where you want to debug, and place breakpoints where you would like.

2. Run in Chromium:
- In a terminal, run `npm run start:web`
- Open the Chromium developer tools and set breakpoints in the Sources pane.

### Debugging unit tests

Tests compile to `packages/language-server/out/test/`. If you want to debug using a unit test, you have to set breakpoints on the compiled output.

Find your test, or the code you want to debug in the `packages/language-server/out/` folder, and set breakpoints.

The extension Mocha Test Explorer (`hbenl.vscode-mocha-test-adapter`) is useful to launch individual tests in debug mode. Install the extension, open your unit test, and press the Debug button that should appear over your test.

### Debugging integration tests

Integration tests run in the Extension Development Host, and are more realistic than unit tests. However, sometimes they can be tricky to write. You can debug the tests themselves.

This method of debugging is **not recommended** if you want to debug the functionality itself. Instead, debug using the Client + Server configuration explained above, and perform the test manually.

If you want to debug the integration tests there are a few things to keep in mind, since tests run in this way use your main stable install of VS Code (not Insiders, like from the terminal):

- You will need to install Vetur (`octref.vetur`), Astro (`astro-build.astro-vscode`) and Svelte for VS Code (`svelte.svelte-vscode`).
- You **must** use default settings for Some Sass. Tip: use the included Workspace Settings.
- To compile changes in test code, run `npm run compile` in the `e2e` directory.

You set breakpoints in the compiled output. Integration tests compile to `vscode-extension/out/suite/`. Breakpoints can _only be set in test code_, meaning any code in the `e2e/out/` folder.

Breakpoints set, go to the _Run and Debug_ pane in VS Code and run the Integration Tests configuration.

### Debugging integration tests for the browser version

Like [debugging integration tests](#debugging-integration-tests), do this when you want to debug the tests themselves rather than functionality. The web integration tests compile to in `web/src/suite/`.

Set breakpoints in the compiled output (`web/dist/suite/index.js`).

At time of writing you may have to set the breakpoints after the debugger has attached. I've had the best success rate clicking repeatedly to set the breakpoint.
The best place to get started is [the guide for new contributors](https://wkillerud.github.io/some-sass/contributing/new-contributors.html).

## Conventional commits

Expand All @@ -157,10 +13,9 @@ Two assets are published:
- The language server is published to npm
- The VS Code extension is published to Visual Studio Marketplace and Open VSX

Keep both in mind when deciding whether a change is a patch, minor or major release.

| Commit message | Release type |
| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `docs: added a guide for configuring sublime text` | Patch. Bugfix release, updates for runtime dependencies. |
| `fix: update css-languageservice` | Patch. Bugfix release, updates for runtime dependencies. |
| `feat: add support for show keyword in forward` | Minor. New feature release. |
| `refactor: remove reduntant options for latest language version`<br><br>`BREAKING CHANGE: The scanImportedFiles option has been removed.` | Major. Breaking release, like removing an option or changing `engines` version. <br /> (Note that the `BREAKING CHANGE: ` token must be in the footer of the commit) |
43 changes: 38 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,48 @@
# Some Sass

In this repo you'll find:
Some Sass is a [language server extension][langext] for [Visual Studio Code][vscode]. It brings improved code suggestions, documentation and code navigation for [SCSS][scss].

- the [Some Sass](./vscode-extension#readme) extension for VS Code
- the [SCSS language server that powers it](./packages/language-server#readme)
Some features include:

The language server is [published independently to npm](https://www.npmjs.com/package/some-sass-language-server), and can be used with any editor that has a [language server protocol (LSP)](https://microsoft.github.io/language-server-protocol/) client.
- Full support for [`@use`][use] and [`@forward`][forward], including aliases, prefixes and hiding.
- Workspace-wide code navigation and refactoring, such as Rename Symbol.
- Rich documentation through [SassDoc][sassdoc].
- Language features for [`%placeholders`][placeholder], both when using them and writing them.

## Editors with clients
![](./docs/src/images/highlight-reel.gif)

## Get the extension

You can find the extension here:

- On the [Visual Studio Code Marketplace][vsmarketplace].
- On the [Open VSX Registry][openvsx].
- In the [Releases section on GitHub][ghreleases].

See the User guide section to learn more about what the extension can do.

## Some Sass Language Server

Some Sass is also a language server using the [Language Server Protocol (LSP)][lsp].

The language server is [published on npm][npm], and can be used with any editor that has an LSP client. See [Getting started](./language-server/getting-started.md) to learn more.

### Editors with clients

The language server has clients for

- [Visual Studio Code](./vscode-extension#readme)
- [Neovim](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#somesass_ls)

[lsp]: https://microsoft.github.io/language-server-protocol/
[npm]: https://www.npmjs.com/package/some-sass-language-server
[scss]: https://sass-lang.com/documentation/syntax/
[use]: https://sass-lang.com/documentation/at-rules/use/
[forward]: https://sass-lang.com/documentation/at-rules/forward/
[langext]: https://code.visualstudio.com/api/language-extensions/language-server-extension-guide
[sassdoc]: http://sassdoc.com
[placeholder]: https://sass-lang.com/documentation/style-rules/placeholder-selectors/
[vscode]: https://code.visualstudio.com/
[vsmarketplace]: https://marketplace.visualstudio.com/items?itemName=SomewhatStationery.some-sass
[openvsx]: https://open-vsx.org/extension/SomewhatStationery/some-sass
[ghreleases]: https://github.com/wkillerud/some-sass/releases
46 changes: 45 additions & 1 deletion docs/src/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,47 @@
# Some Sass

Hello, World!
Some Sass is a [language server extension][langext] for [Visual Studio Code][vscode]. It brings improved code suggestions, documentation and code navigation for [SCSS][scss].

Some features include:

- Full support for [`@use`][use] and [`@forward`][forward], including aliases, prefixes and hiding.
- Workspace-wide code navigation and refactoring, such as Rename Symbol.
- Rich documentation through [SassDoc][sassdoc].
- Language features for [`%placeholders`][placeholder], both when using them and writing them.

![](./images/highlight-reel.gif)

## Get the extension

You can find the extension here:

- On the [Visual Studio Code Marketplace][vsmarketplace].
- On the [Open VSX Registry][openvsx].
- In the [Releases section on GitHub][ghreleases].

See the User guide section to learn more about what the extension can do.

## Some Sass Language Server

Some Sass is also a language server using the [Language Server Protocol (LSP)][lsp].

The language server is [published on npm][npm], and can be used with any editor that has an LSP client. See [Getting started](./language-server/getting-started.md) to learn more.

## Navigating the docs

To navigate between pages you can click the arrow buttons, press the left and right arrow keys on your keyboard, or use the sidebar menu.

To search click the magnifying class icon to the top left or press `s` on your keyboard.

[lsp]: https://microsoft.github.io/language-server-protocol/
[npm]: https://www.npmjs.com/package/some-sass-language-server
[scss]: https://sass-lang.com/documentation/syntax/
[use]: https://sass-lang.com/documentation/at-rules/use/
[forward]: https://sass-lang.com/documentation/at-rules/forward/
[langext]: https://code.visualstudio.com/api/language-extensions/language-server-extension-guide
[sassdoc]: http://sassdoc.com
[placeholder]: https://sass-lang.com/documentation/style-rules/placeholder-selectors/
[vscode]: https://code.visualstudio.com/
[vsmarketplace]: https://marketplace.visualstudio.com/items?itemName=SomewhatStationery.some-sass
[openvsx]: https://open-vsx.org/extension/SomewhatStationery/some-sass
[ghreleases]: https://github.com/wkillerud/some-sass/releases
Loading
Loading