Merge pull request #16 from fastly/dora-add-lsp

Extend VCL language support

.eslintignore

@@ -0,0 +1,5 @@
+node_modules/**
+client/node_modules/**
+client/out/**
+server/node_modules/**
+server/out/**

.eslintrc.cjs

@@ -0,0 +1,16 @@
+/**@type {import('eslint').Linter.Config} */
+// eslint-disable-next-line no-undef
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint'],
+  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
+  rules: {
+    semi: [2, 'never'],
+    '@typescript-eslint/no-unused-vars': 0,
+    '@typescript-eslint/no-explicit-any': 0,
+    '@typescript-eslint/explicit-module-boundary-types': 0,
+    '@typescript-eslint/no-non-null-assertion': 0,
+    'no-case-declarations': 0,
+  }
+}

.github/workflows/test.yaml

@@ -0,0 +1,29 @@
+name: Test
+
+on: pull_request
+
+concurrency:
+  group: ${{ github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: macos-latest
+    steps:
+      - name: Check out the code
+        uses: actions/checkout@v4
+      - name: Install NodeJS
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: npm
+      - name: Install dependencies
+        run: npm install
+      - name: Compile the language client
+        run: npm run compile
+      - name: Test syntax highlighting
+        run: npm test
+      - name: Test LSP features
+        run: npm run test-client
+      - name: Test package
+        run: npm run package

.gitignore

@@ -5,3 +5,8 @@ icon.xcf
 light.png
 node_modules
 screenshots.xcf
+.DS_Store
+.tmp
+.tmp*
+.dora
+client/out

.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm run lint --fix

.vscode/launch.json

@@ -6,10 +6,34 @@
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "Extension",
       "type": "extensionHost",
       "request": "launch",
-      "args": ["--extensionDevelopmentPath=${workspaceFolder}"]
+      "name": "Fastly VCL Client",
+      "runtimeExecutable": "${execPath}",
+      "args": [
+        "--extensionDevelopmentPath=${workspaceRoot}"
+      ],
+      "outFiles": [
+        "${workspaceRoot}/client/out/**/*.js"
+      ],
+      "preLaunchTask": {
+        "type": "npm",
+        "script": "watch"
+      }
+    },
+    {
+      "name": "Client E2E Test",
+      "type": "extensionHost",
+      "request": "launch",
+      "runtimeExecutable": "${execPath}",
+      "args": [
+        "--extensionDevelopmentPath=${workspaceRoot}",
+        "--extensionTestsPath=${workspaceRoot}/client/out/test/index",
+        "${workspaceRoot}/client/testFixture"
+      ],
+      "outFiles": [
+        "${workspaceRoot}/client/out/test/**/*.js"
+      ]
     }
   ]
-}
+}

.vscode/tasks.json

@@ -0,0 +1,33 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "npm",
+      "script": "compile",
+      "group": "build",
+      "presentation": {
+        "panel": "dedicated",
+        "reveal": "never"
+      },
+      "problemMatcher": [
+        "$tsc"
+      ]
+    },
+    {
+      "type": "npm",
+      "script": "watch",
+      "isBackground": true,
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "presentation": {
+        "panel": "dedicated",
+        "reveal": "never"
+      },
+      "problemMatcher": [
+        "$tsc-watch"
+      ]
+    }
+  ]
+}

.vscodeignore

@@ -1,8 +1,30 @@
-.gitignore
+.git*
 .vscode-test/**
 .vscode/**
 dark.png
 icon.xcf
 light.png
 screenshots.xcf
-vsc-extension-quickstart.md
+DEVELOPMENT.md
+**/tsconfig.json
+**/tsconfig.base.json
+.dora
+.husky
+scripts/**
+test/**
+client/testFixture
+client/src/**
+client/README.md
+*.vsix
+.tmp
+.tmp*
+node_modules/**/LICENSE
+node_modules/**/*.md
+node_modules/**/*.cmd
+node_modules/**/*.txt
+node_modules/**/*.d.ts
+node_modules/@*/**
+node_modules/fastly-vcl-lsp/src/**
+node_modules/fastly-vcl-language-client/src/test/**
+node_modules/fastly-vcl-language-client/out/test/**
+node_modules/fastly-vcl-language-client/testFixture/**

CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to the "vscode-fastly-vcl" extension will be documented in t
 
 Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how to structure this file.
 
+## UNRELEASED
+
+### Added
+
+- Integration with [`fastly-vcl-lsp`](https://www.npmjs.com/package/fastly-vcl-lsp).
+- Support for completions, including context-aware completions (functions, variables, headers, Fastly macros).
+- Signature help for functions.
+- Boilerplate snippets for subroutines.
+- Show documentation on hover.
+- Diagnostics (using [`falco`](https://github.com/ysugimoto/falco) – Linux & Darwin, ARM/AMD64 only).
+- Indentation and folding range directives in the language configuration.
+
+### Changed
+
+- Comments must start with `//`.
+
 ## [1.0.4] - 2022-11-03
 
 ### Changed

DEVELOPMENT.md

@@ -0,0 +1,136 @@
+# Development
+
+## What's in the folder
+
+- `package.json` - this is the manifest file in which you declare your language support and define the location of the grammar file that has been copied into your extension.
+- `syntaxes/vcl.tmLanguage.json` - this is the Text mate grammar file that is used for tokenization.
+- `language-configuration.json` - this is the language configuration, defining the tokens that are used for comments and brackets.
+- `client/` - this is the Language Server Protocol client that talks to the LSP server ([`fastly-vcl-lsp`](https://www.npmjs.com/package/fastly-vcl-lsp)).
+
+## Building and running this extension
+
+You'll need [Node.js](https://nodejs.org) and [npm](https://www.npmjs.com/): 
+
+```term
+brew install npm
+npm i node@lts
+```
+
+To develop this extension on your machine, clone this repository and install its dependencies:
+
+```term
+gh repo clone fastly/vscode-fastly-vcl
+cd vscode-fastly-vcl
+npm i
+```
+
+### Local development server
+
+1. Open this folder in VS Code.
+1. Run `Cmd+Shift+B` to start compiling the client in watch mode.
+1. Press `Cmd+Shift+D` to switch to the **Run and Debug View** in the sidebar.
+1. Select `Fastly VCL Client` from the drop down.
+1. Press **▷** to run the launch config with the debugger attached (`F5`).
+1. In the [Extension Development Host](https://code.visualstudio.com/api/get-started/your-first-extension#:~:text=Then%2C%20inside%20the%20editor%2C%20press%20F5.%20This%20will%20compile%20and%20run%20the%20extension%20in%20a%20new%20Extension%20Development%20Host%20window.) instance of VSCode, open a document in `Fastly VCL` language mode. 
+1. Save the file with a `.vcl` extension. 
+1. Use it as a scratchpad to try out all the features!
+
+### Testing
+
+To run the grammar tests:
+
+```bash
+npm test
+```
+
+The test cases are stored as markdown files under `test/colorize-fixtures`. Grammar test results are stored under `test/colorize-results`, which are automatically generated from the fixtures.
+
+To run the LSP tests:
+
+```bash
+npm run test-client
+```
+
+### Packaging and installation
+
+Run the following command to compile the VSCode extension as a `.vsix` file.
+
+```term
+npm run package
+```
+
+Then, either run `code --install-extension vscode-fastly-vcl-{VERSION}.vsix` or follow the steps below to install the extension: 
+
+1. Press `Cmd+Shift+X` to go to the VS Code extension tab.
+1. Click the ellipsis (above "Search Extensions in Marketplace") and pick `Install from VSIX...` from the dropdown.
+1. Install the `.vsix` file you created.
+
+![How to install a VSIX](https://github.com/doramatadora/vscode-fastly-vcl/assets/12828487/090175b9-ae10-4982-a6b8-81f42998e587)
+
+### Contributing
+
+Please open a pull request with your changes.
+
+## Functionality
+
+### Syntax highlighting (VSCode capability)
+
+This uses a JSON [TextMate language grammar](https://macromates.com/manual/en/language_grammars): [syntaxes/vcl.tmLanguage.json](syntaxes/vcl.tmLanguage.json), a structured collection of regular expressions, to tokenize the text into scopes such as:
+
+- `keyword.control.vcl`
+- `variable.other.vcl`
+- `string.quoted.double.vcl`
+- `comment.line.number-sign.vcl`
+
+For example, the extension scopes Fastly code macros as control keywords using a regular expression in JSON:
+
+```json
+{
+  "name": "keyword.control.vcl",
+  "match": "^\\s*#FASTLY\\s+(deliver|error|fetch|hash|hit|log|miss|pass|recv)\\s*$"
+}
+```
+
+Visual Studio Code themes such as GitHub Dark Default or the default Light+ map scopes to colours and styles.
+
+The GitHub Dark default theme maps the keyword scope to red using a JavaScript object:
+
+```js
+{
+  scope: "keyword",
+  settings: {
+    foreground: lightDark(scale.red[5], scale.red[3])
+  }
+}
+```
+
+
+### Fastly VCL LSP capabilities
+
+The [Fastly VCL Language Server Protocol (LSP) server](https://www.npmjs.com/package/fastly-vcl-lsp) works for `.vcl` files. The server is still in an early state. The following list tracks the protocol features that are supported:
+
+- [ ] `textDocument/codeAction`
+- [x] `textDocument/completion` (incl. `completion/resolve`)
+- [ ] `textDocument/definition`
+- [x] `textDocument/didChange (incremental)`
+- [x] `textDocument/didClose`
+- [x] `textDocument/didOpen`
+- [x] `textDocument/didSave`
+- [ ] `textDocument/documentHighlight`
+- [x] `textDocument/documentSymbol`
+- [ ] `textDocument/executeCommand`
+- [ ] `textDocument/formatting`
+- [x] `textDocument/hover`
+- [ ] `textDocument/inlayHint`
+- [ ] `textDocument/prepareCallHierarchy`
+- [ ] `callHierarchy/incomingCalls`
+- [ ] `callHierarchy/outgoingCalls`
+- [ ] `textDocument/prepareRename`
+- [ ] `textDocument/rangeFormatting`
+- [ ] `textDocument/references`
+- [ ] `textDocument/rename`
+- [ ] `textDocument/selectionRange`
+- [x] `textDocument/signatureHelp`
+- [ ] `workspace/symbol`
+- [x] `workspace/didChangeConfiguration`
+- [ ] `workspace/executeCommand`