Feat/integrate debugger

.github/workflows/package.yml

@@ -23,11 +23,14 @@ jobs:
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v2
-      - run: npm install
-      - uses: lannonbr/vsce-action@master
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          args: 'package'
+          node-version: 20
+      - run: npm install
+      - run: npm run typecheck:webview
+      - run: npm run test:unit
+      - run: npx @vscode/vsce package
 
       # Runs a single command using the runners shell
       # - name: Run a one-line script

.gitignore

@@ -9,4 +9,5 @@ client/tsconfig.tsbuildinfo
 .vscode-test
 out/
 server/tsconfig.tsbuildinfo
-tsconfig.tsbuildinfo
+tsconfig.tsbuildinfo
+client/out-unit

.prettierignore

@@ -2,4 +2,5 @@
 build
 coverage
 out
-used_keywords.jsonc
+used_keywords.jsonc
+client/src/debug/tests/fixtures/

.vscodeignore

@@ -11,4 +11,5 @@ scripts/**
 node_modules/**
 
 .gitignore
-.eslintignore
+.eslintignore
+examples/**

CONTRIBUTING.md

@@ -39,6 +39,19 @@ If you have all these tools already installed, you should be able to clone this
 
 Instead of using VS Code, you can run `npm run compile` manually.
 
+### Debugger
+
+The debugger code lives in `client/src/debug/`, one folder per feature (a folder imports only from `shared/` and itself). The debug adapter itself is `nu --dap`, which is part of Nushell (crate `nu-dap`). To work against an unreleased Nushell, build it (`cargo build --release -p nu` in a nushell checkout) and point `nushellLanguageServer.nushellExecutablePath` at `target/release/nu`. Then press F5, open a script from `examples/debug/` in the Extension Development Host and press F5 again.
+
+The webview pages (`*.html`) are copied to `out/debug/` and the visualizer's webview script is bundled separately (`npm run esbuild-webview`); `npm run compile` does both.
+
+### Tests
+
+Requires Node 20 LTS or newer (see `engines.node` in `package.json`).
+
+- `npm run test:unit`: `node:test` unit tests (`client/src/**/*.test.ts`, excluding the VS Code e2e tests in `client/src/test/`)
+- `npm run typecheck:webview`: type-checks the visualizer's browser code
+
 ## Regex Engine
 
 TIL - VSCode uses regexes for language syntax highlighting in \*.tmLanguage.json files. Those regexes and json are based on Textmate, which uses (and here is the secret-sauce) `oniguruma` flavor of syntax. See the cheat-sheet for the [syntax here](https://github.com/kkos/oniguruma/blob/master/doc/RE). Also there's a rust-crate called `onig` or `rust-onig` if we wanted to write something to help create compatible regular expressions.

README.md

@@ -15,6 +15,48 @@ This [extension for VSCode](https://marketplace.visualstudio.com/items?itemName=
 - Auto-complete built-in commands
 - Inlays / Hints
 - Configuration via vscode settings
+- Step debugging of Nushell scripts (`nu --dap`, Nushell 0.116+)
+
+## Finding `nu`
+
+The language server, the Nushell terminal profile and the debugger all use the same `nu`, looked up in this order:
+
+1. the `nushellLanguageServer.nushellExecutablePath` setting (when it is not the default `nu`);
+2. `nu` on your `PATH`.
+
+When neither finds `nu`, the extension points you to the [Nushell installation page](https://www.nushell.sh/book/installation.html) or the setting. Debugging needs Nushell 0.116.0 or newer.
+
+## Debugging
+
+Press **F5** in a `.nu` file (no `launch.json` needed), or add a configuration:
+
+```json
+{
+  "type": "nushell",
+  "request": "launch",
+  "name": "Debug nu script",
+  "program": "${file}",
+  "cwd": "${workspaceFolder}",
+  "args": [],
+  "stopOnEntry": false
+}
+```
+
+The debugger is built into Nushell (`nu --dap`, available from 0.116), so it needs no extra install. It supports:
+
+- breakpoints, conditional breakpoints (`$total > 4000`), logpoints (`total {$total}`) and exception breakpoints ("Runtime errors");
+- step over / into / out, through pipeline stages too, and a call stack with command names;
+- variables inspected to any depth, an Environment scope, and watch / hover / Debug Console expressions;
+- `def main` receives the launch `args`; scripts without `main` let you pick an entry point (`entryPoint`);
+- `input` / `input list` answered through native VS Code prompts;
+- **Visualize** (right-click a variable): tables as sortable, filterable grids, binaries as a hex view, JSON/XML strings formatted;
+- **Nushell Debug: Show IR**: a live view of the compiled IR of the current block;
+- **time travel**: Step Back / Reverse Continue over a recorded timeline (`nushellDebugger.timeTravel`, `nushellDebugger.timeTravelMaxSteps`);
+- hot restart, optionally whenever you save the debugged script (`nushellDebugger.restartOnSave`; auto-saves are ignored).
+
+Known limitations: launch only (no attach), externals get no interactive stdin, `input listen` is not supported, and variables can't be edited while paused.
+
+The `examples/debug/` folder has scripts that exercise each feature.
 
 ## Screenshot (v1.5.0)
 

client/src/debug/adapter/descriptor-factory.ts

@@ -0,0 +1,113 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import {
+  CancellationError,
+  DebugAdapterDescriptor,
+  DebugAdapterDescriptorFactory,
+  DebugAdapterExecutable,
+  Uri,
+  env,
+  window,
+} from 'vscode';
+
+import {
+  NUSHELL_DOWNLOAD_PAGE,
+  compareVersions,
+  parseNuVersion,
+} from '../../nushell/version';
+
+const execFileAsync = promisify(execFile);
+
+/** The first Nushell release that ships `nu --dap`. */
+export const MIN_DAP_VERSION = '0.116.0';
+
+/** Finds the `nu` to run; undefined when there is none, after telling the user. */
+export type NushellResolver = () => string | undefined;
+
+/**
+ * The debugger ships inside Nushell itself: `nu --dap` starts a Debug Adapter
+ * Protocol server over stdio — the same entry point Zed, Neovim, and any other
+ * DAP client use. All we do is find a `nu` (the same one the language server
+ * uses) and spawn it.
+ */
+export class AdapterDescriptorFactory implements DebugAdapterDescriptorFactory {
+  private readonly resolveNushell: NushellResolver;
+
+  constructor(resolveNushell: NushellResolver) {
+    this.resolveNushell = resolveNushell;
+  }
+
+  /**
+   * Cancels the launch when there is no usable `nu`. The resolver has already
+   * told the user (with buttons to download or configure), so cancelling keeps
+   * VS Code from showing a second error on top of it.
+   */
+  async createDebugAdapterDescriptor(): Promise<DebugAdapterDescriptor> {
+    const nu = this.resolveNushell();
+    if (!nu) {
+      throw new CancellationError();
+    }
+
+    // Normally a cache hit: the launch configuration provider checked first.
+    if (!(await confirmDapSupport(nu))) {
+      throw new CancellationError();
+    }
+
+    return new DebugAdapterExecutable(nu, ['--dap']);
+  }
+}
+
+/** `nu` paths already known to support `--dap`. */
+const supported = new Set<string>();
+
+/**
+ * Compares `nu --version` against {@link MIN_DAP_VERSION}; nightlies report
+ * the upcoming release (e.g. `0.116.0-nightly.3`), so they pass too. Not
+ * cached on failure: the user may upgrade `nu` before the next launch.
+ *
+ * False for a too old `nu`, after offering the Nushell download page; the
+ * caller cancels the launch. VS Code doesn't show an error for a cancelled
+ * launch, so this is the only message the user sees.
+ */
+export async function confirmDapSupport(nu: string): Promise<boolean> {
+  if (supported.has(nu)) {
+    return true;
+  }
+
+  const version = await nuVersion(nu);
+  if (!version) {
+    return true; // could not ask: let `nu --dap` speak for itself
+  }
+
+  if (compareVersions(version, MIN_DAP_VERSION) >= 0) {
+    supported.add(nu);
+    return true;
+  }
+
+  void offerDownloadPage(nu, version);
+  return false;
+}
+
+async function offerDownloadPage(nu: string, version: string): Promise<void> {
+  const openPage = 'Open download page';
+  const choice = await window.showWarningMessage(
+    `Debugging is disabled because it needs Nushell ${MIN_DAP_VERSION} or higher, ` +
+      `and ${nu} is version ${version}. Go to the Nushell download page?`,
+    openPage,
+  );
+
+  if (choice === openPage) {
+    await env.openExternal(Uri.parse(NUSHELL_DOWNLOAD_PAGE));
+  }
+}
+
+async function nuVersion(nu: string): Promise<string | undefined> {
+  try {
+    const { stdout } = await execFileAsync(nu, ['--version'], {
+      timeout: 10000,
+    });
+    return parseNuVersion(stdout);
+  } catch {
+    return undefined;
+  }
+}

client/src/debug/adapter/register.ts

@@ -0,0 +1,16 @@
+import * as vscode from 'vscode';
+
+import { DEBUG_TYPE } from '../shared/debug-type';
+import {
+  AdapterDescriptorFactory,
+  NushellResolver,
+} from './descriptor-factory';
+
+export function register(resolveNushell: NushellResolver): vscode.Disposable[] {
+  return [
+    vscode.debug.registerDebugAdapterDescriptorFactory(
+      DEBUG_TYPE,
+      new AdapterDescriptorFactory(resolveNushell),
+    ),
+  ];
+}

client/src/debug/ir/ir-listing.ts

@@ -0,0 +1,20 @@
+import { escapeHtml } from '../shared/escape-html';
+
+/** One IR line as HTML; the instruction we are paused on is marked so the page can scroll to it. */
+export function irLine(line: string, currentIndex: number): string {
+  if (!isInstructionAt(line, currentIndex)) {
+    return `<span>${escapeHtml(line)}\n</span>`;
+  }
+
+  return `<span class="current" id="cur">${escapeHtml(line)}\n</span>`;
+}
+
+/** IR lines are numbered `  12: instruction`; is this the one at `index`? */
+export function isInstructionAt(line: string, index: number): boolean {
+  const match = /^\s*(\d+):/.exec(line);
+  if (!match) {
+    return false;
+  }
+
+  return Number(match[1]) === index;
+}

client/src/debug/ir/ir-panel.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html>
+  <head>
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'none'; style-src 'unsafe-inline'; script-src 'nonce-{{nonce}}';"
+    />
+    <style>
+      body {
+        font-family: var(--vscode-editor-font-family, monospace);
+        font-size: var(--vscode-editor-font-size, 13px);
+      }
+      pre {
+        margin: 0;
+      }
+      .current {
+        display: inline-block;
+        width: 100%;
+        background: var(--vscode-editor-selectionBackground, #264f78);
+        font-weight: bold;
+      }
+      .hint {
+        color: var(--vscode-descriptionForeground, #999);
+      }
+    </style>
+  </head>
+  <body>
+    {{status}} {{listing}}
+    <script nonce="{{nonce}}">
+      document.getElementById('cur')?.scrollIntoView({ block: 'center' });
+    </script>
+  </body>
+</html>

client/src/debug/ir/ir-panel.ts

@@ -0,0 +1,86 @@
+import * as vscode from 'vscode';
+
+import { assetPath } from '../shared/assets';
+import { hint, makeNonce, renderTemplate } from '../shared/html';
+import { irLine } from './ir-listing';
+
+/** Body of the adapter's `nuDapIr` event, sent on every stop. */
+export interface IrEventBody {
+  text: string;
+  instructionIndex: number;
+  instructionCount: number; // unused here; part of the wire shape
+}
+
+// The singleton webview showing the IR of the block the debugger is paused in,
+// with the current instruction highlighted. Updates on every stop; shows the
+// most recent stop's IR if opened later. The page is ir-panel.html, copied to
+// out/debug/.
+
+let panel: vscode.WebviewPanel | undefined;
+let latest: IrEventBody | undefined;
+let ended = false;
+
+export function showIrPanel(): void {
+  if (panel) {
+    panel.reveal(vscode.ViewColumn.Beside, true);
+    return;
+  }
+
+  panel = vscode.window.createWebviewPanel(
+    'nuDapIr',
+    'Nushell IR',
+    { viewColumn: vscode.ViewColumn.Beside, preserveFocus: true },
+    { enableScripts: true },
+  );
+
+  panel.onDidDispose(() => {
+    panel = undefined;
+  });
+
+  render();
+}
+
+export function updateIrPanel(body: IrEventBody): void {
+  latest = body;
+  ended = false;
+  render();
+}
+
+export function markIrPanelEnded(): void {
+  ended = true;
+  render();
+}
+
+function render(): void {
+  if (!panel) {
+    return;
+  }
+
+  panel.webview.html = renderTemplate(assetPath('ir-panel.html'), {
+    nonce: makeNonce(),
+    status: status(),
+    listing: listing(),
+  });
+}
+
+function status(): string {
+  if (!ended) {
+    return '';
+  }
+
+  return hint('Debug session ended — showing the last stop.');
+}
+
+function listing(): string {
+  const shown = latest;
+  if (!shown) {
+    return hint(
+      'Waiting for the debugger to stop… (the IR of the current block is sent on every breakpoint/step)',
+    );
+  }
+
+  const lines = shown.text
+    .split('\n')
+    .map((line) => irLine(line, shown.instructionIndex));
+  return `<pre>${lines.join('')}</pre>`;
+}