Merge pull request #286 from afonsonf/enable-extension-in-the-web

Enable extension in browser environments

.gitignore

@@ -1,4 +1,6 @@
 out/
 node_modules/
 .vscode-test/
+.vscode-test-web/
 version
+*.vsix

.vscode/launch.json

@@ -14,7 +14,7 @@
             "outFiles": [
                 "${workspaceFolder}/out/**/*.js"
             ],
-            "preLaunchTask": "npm: watch"
+            "preLaunchTask": "npm: compile"
         },
         {
             "name": "Run Extension Tests",

.vscode/tasks.json

@@ -17,4 +17,4 @@
             }
         }
     ]
-}
+}

.vscodeignore

@@ -2,10 +2,13 @@
 .github/
 .vscode/
 .vscode-test/
+.vscode-test-web/
 # include languages/
 node_modules/
 out/src/
 out/tests/
+out/main.browser.js.map
+# include out/main.browser.js
 out/main.js.map
 # include out/main.js
 resources/images/screencast.gif

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 All forms of contribution are highly welcome! Feel free to file bugs, propose improvements, ask questions, send other feedback.
 
-For those, who whant to write some code, here's a short guide.
+For those, who want to write some code, here's a short guide.
 
 # Getting started
 
@@ -98,6 +98,55 @@ vsce package
 unzip -l *.vsix
 ```
 
+## Test extension in a web environment
+
+The extension has support for web environments such as [vscode.dev](https://code.visualstudio.com/docs/editor/vscode-web) but with only a limited set of features is enabled (different entrypoint from the main extension).
+
+Further read: https://code.visualstudio.com/api/extension-guides/web-extensions#test-your-web-extension
+
+#### Using @vscode/test-web
+
+This is the simplest method, however, at time of writing, it does not work in a Codespaces environment.
+
+To test the extension using [@vscode/test-web](https://github.com/microsoft/vscode-test-web) run:
+
+```shell
+# Optional: get some example files
+git clone https://github.com/tlaplus/Examples.git ~/Examples
+
+# Compile extension
+npm install
+npm run compile
+
+# Start a local vscode.dev with the tla+ extension
+npm install -g @vscode/test-web
+vscode-test-web  --extensionDevelopmentPath=. --headless=true ~/Examples
+# Open http://localhost:3000/ in a browser
+```
+
+#### Using vscode.dev
+
+For updated instructions see: https://code.visualstudio.com/api/extension-guides/web-extensions#test-your-web-extension-in-on-vscode.dev
+
+To run the extension in the actual vscode.dev environment run:
+
+```shell
+# From the extension root path, start a http server
+npx serve --cors -l 5000
+
+# In another terminal start a localtunnel to the previous http server
+npx localtunnel -p 5000
+
+# Open the generated url and click the "Click to Continue" button
+# Copy the generated url
+
+# Go to vscode.dev (suggestion to open in tlaplus examples folder: https://vscode.dev/github/tlaplus/Examples)
+# Ctrl+Shift+P > Developer: Install Extension from Location.. > Paste the generated url
+
+# Open devtools (F12) to check for errors
+# Ctrl+Shift+P > Developer: Show Running Extensions
+```
+
 # Overview
 
 The extension consists of the following components:
@@ -126,6 +175,7 @@ Most of the extension main code is located in the `src` directory. The only exce
 Names of files and subdirectories are usually self-descriptive. Here're the most interesting ones:
 
 - `src/main.ts` — This is the starting point of the extension. It sets things up when the extension is loaded.
+- `src/main.browser.ts` — Starting point for the extension in a browser environment.
 - `src/tla2tools.ts` — All calls to `tla2tools.jar` go through methods from this file.
 - `src/checkResultView.ts` — The main functions that are responsible for interaction between the main extension code and the Check Result View panel.
 - `src/commands/` — This directory contains implementation of all the [VS Code commands](https://code.visualstudio.com/api/extension-guides/command) that the extension provides.
@@ -148,7 +198,7 @@ There're some other useful stuff in the project:
 
 - `.vscode/` — VS Code configuration files that make working with the project easier.
 - `languages/` — Languages definition files.
-- `tools/` — Additional artefacts that are used by the extesion.
+- `tools/` — Additional artifacts that are used by the extension.
 
 # Source Code Style
 

esbuild.js

@@ -25,6 +25,17 @@ const extensionConfig = {
     external: ['vscode'],
 };
 
+// Config for extension source code (to be run in a Web-based context)
+/** @type BuildOptions */
+const extensionWebConfig = {
+    ...baseConfig,
+    platform: 'browser',
+    format: 'cjs',
+    entryPoints: ['./src/main.browser.ts'],
+    outfile: './out/main.browser.js',
+    external: ['vscode'],
+};
+
 // This watch config adheres to the conventions of the esbuild-problem-matchers
 // extension (https://github.com/connor4312/esbuild-problem-matchers#esbuild-via-js)
 /** @type BuildOptions */
@@ -55,10 +66,15 @@ const watchConfig = {
                 ...extensionConfig,
                 ...watchConfig,
             });
+            await build({
+                ...extensionWebConfig,
+                ...watchConfig,
+            });
             console.log('[watch] build finished');
         } else {
             // Build extension
             await build(extensionConfig);
+            await build(extensionWebConfig);
             console.log('build complete');
         }
     } catch (err) {

package.json

@@ -46,6 +46,7 @@
         "workspaceContains:**/*.tla"
     ],
     "main": "./out/main.js",
+    "browser": "./out/main.browser.js",
     "files": [
         "resources",
         "tools"
@@ -362,7 +363,7 @@
                     ],
                     "enumDescriptions": [
                         "TLC statistics will be shared along with the installation ID.",
-                        "TLC statistics will be shared witout the installation ID.",
+                        "TLC statistics will be shared without the installation ID.",
                         "No TLC statistics will be shared."
                     ]
                 },

src/main.browser.ts

@@ -0,0 +1,46 @@
+import * as vscode from 'vscode';
+
+import { CfgCompletionItemProvider } from './completions/cfgCompletions';
+import { TlaCompletionItemProvider } from './completions/tlaCompletions';
+import { TlaDeclarationsProvider, TlaDefinitionsProvider } from './declarations/tlaDeclarations';
+import { CfgOnTypeFormattingEditProvider } from './formatters/cfg';
+import { TlaOnTypeFormattingEditProvider } from './formatters/tla';
+import { TlaDocumentInfos } from './model/documentInfo';
+import { TlaDocumentSymbolsProvider } from './symbols/tlaSymbols';
+
+const LANG_TLAPLUS = 'tlaplus';
+const LANG_TLAPLUS_CFG = 'tlaplus_cfg';
+const tlaDocInfos = new TlaDocumentInfos();
+
+/**
+ * Extension entry point.
+ */
+export function activate(context: vscode.ExtensionContext): void {
+    context.subscriptions.push(
+        vscode.languages.registerOnTypeFormattingEditProvider(
+            LANG_TLAPLUS,
+            new TlaOnTypeFormattingEditProvider(),
+            '\n', 'd', 'e', 'f', 'r'),
+        vscode.languages.registerOnTypeFormattingEditProvider(
+            LANG_TLAPLUS_CFG,
+            new CfgOnTypeFormattingEditProvider(),
+            '\n'),
+        vscode.languages.registerDocumentSymbolProvider(
+            LANG_TLAPLUS,
+            new TlaDocumentSymbolsProvider(tlaDocInfos),
+            { label: 'TLA+' }),
+        vscode.languages.registerCompletionItemProvider(
+            LANG_TLAPLUS,
+            new TlaCompletionItemProvider(tlaDocInfos)),
+        vscode.languages.registerCompletionItemProvider(
+            LANG_TLAPLUS_CFG,
+            new CfgCompletionItemProvider()),
+        vscode.languages.registerDeclarationProvider(
+            LANG_TLAPLUS,
+            new TlaDeclarationsProvider(tlaDocInfos)),
+        vscode.languages.registerDefinitionProvider(
+            LANG_TLAPLUS,
+            new TlaDefinitionsProvider(tlaDocInfos)
+        )
+    );
+}