Shuttle Explorer

Cargo.toml

@@ -11,6 +11,7 @@ categories = ["asynchronous", "concurrency", "development-tools::testing"]
 [dependencies]
 assoc = "0.1.3"
 bitvec = "1.0.1"
+cfg-if = "1.0"
 generator = "0.8.1"
 hex = "0.4.2"
 owo-colors = "3.5.0"
@@ -21,6 +22,11 @@ scoped-tls = "1.0.0"
 smallvec = { version = "1.11.2", features = ["const_new"] }
 tracing = { version = "0.1.36", default-features = false, features = ["std"] }
 
+# for annotation only
+regex = { version = "1.10.6", optional = true }
+serde = { version = "1.0", features = ["derive"], optional = true }
+serde_json = { version = "1.0", optional = true }
+
 [dev-dependencies]
 criterion = { version = "0.4.0", features = ["html_reports"] }
 futures = "0.3.15"
@@ -34,6 +40,10 @@ pin-project = "1.1.3"
 [lib]
 bench = false
 
+[features]
+default = []
+annotation = ["dep:serde", "dep:serde_json", "dep:regex"]
+
 [[bench]]
 name = "lock"
 harness = false

shuttle-explorer/.eslintrc.json

@@ -0,0 +1,30 @@
+{
+    "root": true,
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+        "ecmaVersion": 6,
+        "sourceType": "module"
+    },
+    "plugins": [
+        "@typescript-eslint"
+    ],
+    "rules": {
+        "@typescript-eslint/naming-convention": [
+            "warn",
+            {
+                "selector": "import",
+                "format": [ "camelCase", "PascalCase" ]
+            }
+        ],
+        "@typescript-eslint/semi": "warn",
+        "curly": "warn",
+        "eqeqeq": "warn",
+        "no-throw-literal": "warn",
+        "semi": "off"
+    },
+    "ignorePatterns": [
+        "out",
+        "dist",
+        "**/*.d.ts"
+    ]
+}

shuttle-explorer/.gitignore

@@ -0,0 +1,5 @@
+out
+dist
+node_modules
+.vscode-test/
+*.vsix

shuttle-explorer/.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+  // See http://go.microsoft.com/fwlink/?LinkId=827846
+  // for the documentation about the extensions.json format
+  "recommendations": ["dbaeumer.vscode-eslint", "connor4312.esbuild-problem-matchers", "ms-vscode.extension-test-runner"]
+}

shuttle-explorer/.vscode/launch.json

@@ -0,0 +1,21 @@
+// A launch configuration that compiles the extension and then opens it inside a new window
+// Use IntelliSense to learn about possible attributes.
+// Hover to view descriptions of existing attributes.
+// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+{
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"name": "Run Extension",
+			"type": "extensionHost",
+			"request": "launch",
+			"args": [
+				"--extensionDevelopmentPath=${workspaceFolder}"
+			],
+			"outFiles": [
+				"${workspaceFolder}/dist/**/*.js"
+			],
+			"preLaunchTask": "${defaultBuildTask}"
+		}
+	]
+}

shuttle-explorer/.vscode/settings.json

@@ -0,0 +1,13 @@
+// Place your settings in this file to overwrite default and user settings.
+{
+    "files.exclude": {
+        "out": false, // set this to true to hide the "out" folder with the compiled JS files
+        "dist": false // set this to true to hide the "dist" folder with the compiled JS files
+    },
+    "search.exclude": {
+        "out": true, // set this to false to include "out" folder in search results
+        "dist": true // set this to false to include "dist" folder in search results
+    },
+    // Turn off tsc task auto detection since we have the necessary tasks as npm scripts
+    "typescript.tsc.autoDetect": "off"
+}

shuttle-explorer/.vscode/tasks.json

@@ -0,0 +1,64 @@
+// See https://go.microsoft.com/fwlink/?LinkId=733558
+// for the documentation about the tasks.json format
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+            "label": "watch",
+            "dependsOn": [
+                "npm: watch:tsc",
+                "npm: watch:esbuild"
+            ],
+            "presentation": {
+                "reveal": "never"
+            },
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "type": "npm",
+            "script": "watch:esbuild",
+            "group": "build",
+            "problemMatcher": "$esbuild-watch",
+            "isBackground": true,
+            "label": "npm: watch:esbuild",
+            "presentation": {
+                "group": "watch",
+                "reveal": "never"
+            }
+        },
+		{
+            "type": "npm",
+            "script": "watch:tsc",
+            "group": "build",
+            "problemMatcher": "$tsc-watch",
+            "isBackground": true,
+            "label": "npm: watch:tsc",
+            "presentation": {
+                "group": "watch",
+                "reveal": "never"
+            }
+        },
+		{
+			"type": "npm",
+			"script": "watch-tests",
+			"problemMatcher": "$tsc-watch",
+			"isBackground": true,
+			"presentation": {
+				"reveal": "never",
+				"group": "watchers"
+			},
+			"group": "build"
+		},
+		{
+			"label": "tasks: watch-tests",
+			"dependsOn": [
+				"npm: watch",
+				"npm: watch-tests"
+			],
+			"problemMatcher": []
+		}
+	]
+}

shuttle-explorer/.vscodeignore

@@ -0,0 +1,14 @@
+.vscode/**
+.vscode-test/**
+out/**
+node_modules/**
+src/**
+.gitignore
+.yarnrc
+esbuild.js
+vsc-extension-quickstart.md
+**/tsconfig.json
+**/.eslintrc.json
+**/*.map
+**/*.ts
+**/.vscode-test.*

shuttle-explorer/README.md

@@ -0,0 +1,34 @@
+# Shuttle Explorer
+
+Timeline visualiser for [Shuttle](https://github.com/awslabs/shuttle).
+
+## Building
+
+To use the extension, it is currently required to build it from source. Pre-requisites include:
+
+- VS Code 1.92.0 or later
+- `node` 18.20 and `npm` 10.5 (other versions are probably fine too)
+- [esbuild Problem Matcher extension](https://marketplace.visualstudio.com/items?itemName=connor4312.esbuild-problem-matchers), installed either globally or in the Shuttle Explorer workspace. **Without this extension the builds will fail silently!**
+
+Steps:
+
+1. Clone this repository.
+2. Navigate to the Shuttle Explorer directory in a terminal, run `npm install`.
+3. Open the Shuttle Explorer directory in VS Code.
+4. Press F5 or find "Run > Start Debugging" in the menu. Accept a debug configuration if prompted.
+  - In the background, two tasks should spawn: a TypeScript watcher, and an esbuild watcher. You should be able to see both in the "terminal" window, and neither should be reporting an error. If the esbuild watcher is marked as "pending", you need the esbuild Problem Matcher extension.
+  - The TypeScript sources in `src` should be compiled down to JavaScript, output into the `dist` folder.
+5. A new VS Code window (the "extension host") should open.
+6. (Optionally,) open a workspace in the new window, to see the code cursors.
+7. From the command palette (cmd + shift + P), find "Shuttle Explorer: Focus on Home View" to reveal the extension.
+8. Press the "file" button in the top-left corner of the extension panel, or use "View annotated schedule" in the command palette to pick a JSON file to visualise.
+
+Notes:
+
+- Things may go wrong before the extension host window is open. Look at the problems panel, see if there are any problems. Look at the terminal window, to see if the background tasks are running and not reporting any errors.
+- Things may go wrong after the extension host window is open. In that window, look at the console (command palette: "Developer: Open Webview Developer Tools") to look for any errors.
+- After closing the Shuttle Explorer panel, re-opening it will probably not work. Reload the window (cmd + R or command palette: "Developer: Reload Window") to start again.
+
+During development:
+
+- While the extension is running, changing TypeScript files in `src` should trigger an automatic re-compilation. Simply reload the window (cmd + R or command palette: "Developer: Reload Window") with the extension to see the new changes. (Sometimes, the window spontaneously closes after reloading it. Re-start with F5 if this happens.)

shuttle-explorer/esbuild.js

@@ -0,0 +1,83 @@
+const esbuild = require("esbuild");
+
+const production = process.argv.includes("--production");
+const watch = process.argv.includes("--watch");
+
+/**
+ * @type {import("esbuild").Plugin}
+ */
+// note: the [watch] prefix here is important, see
+// https://github.com/connor4312/esbuild-problem-matchers/blob/51e17a9f4464dd008bfc07871482b94dc87901ce/package.json#L97
+const esbuildProblemMatcherPlugin = {
+  name: "esbuild-problem-matcher",
+
+  setup(build) {
+    build.onStart(() => {
+      console.log("[watch] build started");
+    });
+    build.onEnd((result) => {
+      result.errors.forEach(({ text, location }) => {
+        console.error(`✘ [ERROR] ${text}`);
+        console.error(`    ${location.file}:${location.line}:${location.column}:`);
+      });
+      console.log("[watch] build finished");
+    });
+  },
+};
+
+async function mainBackend() {
+  const ctx = await esbuild.context({
+    entryPoints: [
+      "src/backend/main.mts"
+    ],
+    bundle: true,
+    format: "cjs",
+    minify: production,
+    sourcemap: !production,
+    sourcesContent: false,
+    platform: "node",
+    outfile: "dist/backend/main.js",
+    external: ["vscode"],
+    logLevel: "silent",
+    plugins: [
+      esbuildProblemMatcherPlugin,
+    ],
+  });
+  if (watch) {
+    await ctx.watch();
+  } else {
+    await ctx.rebuild();
+    await ctx.dispose();
+  }
+}
+
+async function mainFrontend() {
+  const ctx = await esbuild.context({
+    entryPoints: [
+      "src/frontend/main.mts" 
+    ],
+    bundle: true,
+    format: "esm",
+    minify: production,
+    sourcemap: !production,
+    sourcesContent: false,
+    platform: "browser",
+    outfile: "dist/frontend/main.js",
+    external: [],
+    logLevel: "silent",
+    plugins: [
+      esbuildProblemMatcherPlugin,
+    ],
+  });
+  if (watch) {
+    await ctx.watch();
+  } else {
+    await ctx.rebuild();
+    await ctx.dispose();
+  }
+}
+
+Promise.any([mainBackend(), mainFrontend()]).catch(e => {
+  console.error(e);
+  process.exit(1);
+});