feat: prompt to install extension on wasm step

package.json

@@ -125,6 +125,7 @@
     "@types/ws": "^8.5.3",
     "@typescript-eslint/eslint-plugin": "^5.17.0",
     "@typescript-eslint/parser": "^5.17.0",
+    "@vscode/dwarf-debugging": "file:../vscode-dwarf-debugging/vscode-dwarf-debugging-0.0.2.tgz",
     "@vscode/test-electron": "^2.2.3",
     "chai": "^4.3.6",
     "chai-as-promised": "^7.1.1",

src/adapter/dwarf/dwarfModuleProvider.ts

@@ -0,0 +1,18 @@
+/*---------------------------------------------------------
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------*/
+
+export const IDwarfModuleProvider = Symbol('IDwarfModuleProvider');
+
+export interface IDwarfModuleProvider {
+  /**
+   * Loads the dwarf module if it exists.
+   */
+  load(): Promise<typeof import('@vscode/dwarf-debugging') | undefined>;
+
+  /**
+   * Prompts the user to install the dwarf module (called if the module is
+   * not installed.)
+   */
+  prompt(): void;
+}

src/adapter/dwarf/dwarfModuleProviderImpl.ts

@@ -0,0 +1,40 @@
+/*---------------------------------------------------------
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------*/
+
+import type * as dwf from '@vscode/dwarf-debugging';
+import * as l10n from '@vscode/l10n';
+import { inject, injectable } from 'inversify';
+import Dap from '../../dap/api';
+import { IDapApi } from '../../dap/connection';
+import { IDwarfModuleProvider } from './dwarfModuleProvider';
+
+const name = '@vscode/dwarf-debugging';
+
+@injectable()
+export class DwarfModuleProvider implements IDwarfModuleProvider {
+  private didPrompt = false;
+
+  constructor(@inject(IDapApi) private readonly dap: Dap.Api) {}
+
+  public async load(): Promise<typeof dwf | undefined> {
+    try {
+      return await import(name);
+    } catch {
+      return undefined;
+    }
+  }
+
+  public prompt() {
+    if (!this.didPrompt) {
+      this.didPrompt = true;
+      this.dap.output({
+        output: l10n.t(
+          'You may install the `{}` module via npm for enhanced WebAssembly debugging',
+          name,
+        ),
+        category: 'console',
+      });
+    }
+  }
+}

src/adapter/wasmSymbolProvider.ts → src/adapter/dwarf/wasmSymbolProvider.ts

@@ -2,17 +2,18 @@
  * Copyright (C) Microsoft Corporation. All rights reserved.
  *--------------------------------------------------------*/
 
-import type { IWasmWorker, MethodReturn, spawn } from '@vscode/dwarf-debugging';
+import type { IWasmWorker, MethodReturn } from '@vscode/dwarf-debugging';
 import { randomUUID } from 'crypto';
 import { inject, injectable } from 'inversify';
-import Cdp from '../cdp/api';
-import { ICdpApi } from '../cdp/connection';
-import { binarySearch } from '../common/arrayUtils';
-import { IDisposable } from '../common/disposable';
-import { ILogger, LogTag } from '../common/logging';
-import { once } from '../common/objUtils';
-import { Base0Position, IPosition } from '../common/positions';
-import { getSourceSuffix } from './templates';
+import Cdp from '../../cdp/api';
+import { ICdpApi } from '../../cdp/connection';
+import { binarySearch } from '../../common/arrayUtils';
+import { IDisposable } from '../../common/disposable';
+import { ILogger, LogTag } from '../../common/logging';
+import { once } from '../../common/objUtils';
+import { Base0Position, IPosition } from '../../common/positions';
+import { getSourceSuffix } from '../templates';
+import { IDwarfModuleProvider } from './dwarfModuleProvider';
 
 export const IWasmSymbolProvider = Symbol('IWasmSymbolProvider');
 
@@ -21,27 +22,29 @@ export interface IWasmSymbolProvider {
   loadWasmSymbols(script: Cdp.Debugger.ScriptParsedEvent): Promise<IWasmSymbols>;
 }
 
-@injectable()
-export class StubWasmSymbolProvider implements IWasmSymbolProvider {
-  constructor(@inject(ICdpApi) private readonly cdp: Cdp.Api) {}
-
-  public loadWasmSymbols(script: Cdp.Debugger.ScriptParsedEvent): Promise<IWasmSymbols> {
-    return Promise.resolve(new DecompiledWasmSymbols(script, this.cdp, []));
-  }
-}
-
 @injectable()
 export class WasmSymbolProvider implements IWasmSymbolProvider, IDisposable {
-  private worker?: IWasmWorker;
+  /** Running worker, `null` signals that the dwarf module was not available */
+  private worker?: IWasmWorker | null;
+
+  private readonly doPrompt = once(() => this.dwarf.prompt());
 
   constructor(
-    private readonly spawnDwarf: typeof spawn,
+    @inject(IDwarfModuleProvider) private readonly dwarf: IDwarfModuleProvider,
     @inject(ICdpApi) private readonly cdp: Cdp.Api,
     @inject(ILogger) private readonly logger: ILogger,
   ) {}
 
   public async loadWasmSymbols(script: Cdp.Debugger.ScriptParsedEvent): Promise<IWasmSymbols> {
     const rpc = await this.getWorker();
+    if (!rpc) {
+      const syms = new DecompiledWasmSymbols(script, this.cdp, []);
+      // disassembly is a good signal for a prompt, since that means a user
+      // will have stepped into and be looking at webassembly code.
+      syms.onDidDisassemble = this.doPrompt;
+      return syms;
+    }
+
     const moduleId = randomUUID();
 
     const symbolsUrl = script.debugSymbols?.externalURL;
@@ -81,11 +84,17 @@ export class WasmSymbolProvider implements IWasmSymbolProvider, IDisposable {
   }
 
   private async getWorker() {
-    if (this.worker) {
-      return this.worker.rpc;
+    if (this.worker !== undefined) {
+      return this.worker?.rpc;
+    }
+
+    const dwarf = await this.dwarf.load();
+    if (!dwarf) {
+      this.worker = null;
+      return undefined;
     }
 
-    this.worker = this.spawnDwarf({
+    this.worker = dwarf.spawn({
       getWasmGlobal: (index, stopId) => this.loadWasmValue(`globals[${index}]`, stopId),
       getWasmLocal: (index, stopId) => this.loadWasmValue(`locals[${index}]`, stopId),
       getWasmOp: (index, stopId) => this.loadWasmValue(`stack[${index}]`, stopId),
@@ -192,6 +201,9 @@ class DecompiledWasmSymbols implements IWasmSymbols {
   /** @inheritdoc */
   public readonly files: readonly string[];
 
+  /** Called whenever disassembly is requested for a source/ */
+  public onDidDisassemble?: () => void;
+
   constructor(
     protected readonly event: Cdp.Debugger.ScriptParsedEvent,
     protected readonly cdp: Cdp.Api,
@@ -204,6 +216,7 @@ class DecompiledWasmSymbols implements IWasmSymbols {
   /** @inheritdoc */
   public async getDisassembly(): Promise<string> {
     const { lines } = await this.doDisassemble();
+    this.onDidDisassemble?.();
     return lines.join('\n');
   }
 

src/adapter/source.ts

@@ -16,8 +16,8 @@ import * as sourceUtils from '../common/sourceUtils';
 import { prettyPrintAsSourceMap } from '../common/sourceUtils';
 import * as utils from '../common/urlUtils';
 import Dap from '../dap/api';
+import { IWasmSymbols } from './dwarf/wasmSymbolProvider';
 import type { SourceContainer } from './sourceContainer';
-import { IWasmSymbols } from './wasmSymbolProvider';
 
 // Represents a text source visible to the user.
 //

src/adapter/sourceContainer.ts

@@ -23,6 +23,7 @@ import { sourceMapParseFailed } from '../dap/errors';
 import { IInitializeParams } from '../ioc-extras';
 import { IStatistics } from '../telemetry/classification';
 import { extractErrorDetails } from '../telemetry/dapTelemetryReporter';
+import { IWasmSymbolProvider, IWasmSymbols } from './dwarf/wasmSymbolProvider';
 import { IResourceProvider } from './resourceProvider';
 import { ScriptSkipper } from './scriptSkipper/implementation';
 import { IScriptSkipper } from './scriptSkipper/scriptSkipper';
@@ -43,7 +44,6 @@ import {
   uiToRawOffset,
 } from './source';
 import { Script } from './threads';
-import { IWasmSymbolProvider, IWasmSymbols } from './wasmSymbolProvider';
 
 function isUiLocation(loc: unknown): loc is IUiLocation {
   return (

src/adapter/variableStore.ts

@@ -16,6 +16,7 @@ import Dap from '../dap/api';
 import { IDapApi } from '../dap/connection';
 import * as errors from '../dap/errors';
 import { ProtocolError } from '../dap/protocolError';
+import { IWasmVariable, IWasmVariableEvaluation, WasmScope } from './dwarf/wasmSymbolProvider';
 import * as objectPreview from './objectPreview';
 import { MapPreview, SetPreview } from './objectPreview/betterTypes';
 import { PreviewContextType } from './objectPreview/contexts';
@@ -32,7 +33,6 @@ import {
 import { invokeGetter } from './templates/invokeGetter';
 import { readMemory } from './templates/readMemory';
 import { writeMemory } from './templates/writeMemory';
-import { IWasmVariable, IWasmVariableEvaluation, WasmScope } from './wasmSymbolProvider';
 
 const getVariableId = (() => {
   let last = 0;

src/ioc-extras.ts

@@ -2,6 +2,7 @@
  * Copyright (C) Microsoft Corporation. All rights reserved.
  *--------------------------------------------------------*/
 
+import type * as dwf from '@vscode/dwarf-debugging';
 import { promises as fsPromises } from 'fs';
 import { interfaces } from 'inversify';
 import type * as vscode from 'vscode';
@@ -69,6 +70,16 @@ export type FsPromises = typeof fsPromises;
  */
 export const BrowserFinder = Symbol('IBrowserFinder');
 
+/**
+ * Symbol for the `@vscode/dwarf-debugging` module, in IDwarfDebugging.
+ */
+export const DwarfDebugging = Symbol('DwarfDebugging');
+
+/**
+ * Type for {@link DwarfDebugging}
+ */
+export type DwarfDebugging = () => Promise<typeof dwf | undefined>;
+
 /**
  * Location the extension is running in.
  */

src/ioc.ts

@@ -32,6 +32,7 @@ import { IConsole } from './adapter/console';
 import { Console } from './adapter/console/console';
 import { Diagnostics } from './adapter/diagnosics';
 import { DiagnosticToolSuggester } from './adapter/diagnosticToolSuggester';
+import { IWasmSymbolProvider, WasmSymbolProvider } from './adapter/dwarf/wasmSymbolProvider';
 import { Evaluator, IEvaluator } from './adapter/evaluator';
 import { ExceptionPauseService, IExceptionPauseService } from './adapter/exceptionPauseService';
 import { IPerformanceProvider, PerformanceProviderFactory } from './adapter/performance';
@@ -48,11 +49,6 @@ import { IScriptSkipper } from './adapter/scriptSkipper/scriptSkipper';
 import { SmartStepper } from './adapter/smartStepping';
 import { SourceContainer } from './adapter/sourceContainer';
 import { IVueFileMapper, VueFileMapper } from './adapter/vueFileMapper';
-import {
-  IWasmSymbolProvider,
-  StubWasmSymbolProvider,
-  WasmSymbolProvider,
-} from './adapter/wasmSymbolProvider';
 import Cdp from './cdp/api';
 import { ICdpApi } from './cdp/connection';
 import { ObservableMap } from './common/datastructure/observableMap';
@@ -125,6 +121,8 @@ import { NullTelemetryReporter } from './telemetry/nullTelemetryReporter';
 import { ITelemetryReporter } from './telemetry/telemetryReporter';
 import { IShutdownParticipants, ShutdownParticipants } from './ui/shutdownParticipants';
 import { registerTopLevelSessionComponents, registerUiComponents } from './ui/ui-ioc';
+import { IDwarfModuleProvider } from './adapter/dwarf/dwarfModuleProvider';
+import { DwarfModuleProvider } from './adapter/dwarf/dwarfModuleProviderImpl';
 
 /**
  * Contains IOC container factories for the extension. We use Inverisfy, which
@@ -197,6 +195,7 @@ export const createTargetContainer = (
   container.bind(IEvaluator).to(Evaluator).inSingletonScope();
   container.bind(IConsole).to(Console).inSingletonScope();
   container.bind(IShutdownParticipants).to(ShutdownParticipants).inSingletonScope();
+  container.bind(IWasmSymbolProvider).to(WasmSymbolProvider).inSingletonScope();
 
   container.bind(BasicCpuProfiler).toSelf();
   container.bind(BasicHeapProfiler).toSelf();
@@ -210,20 +209,6 @@ export const createTargetContainer = (
     .inSingletonScope()
     .onActivation(trackDispose);
 
-  try {
-    // todo: temporarily ignore import errors until the module is published
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    //@ts-ignore
-    const dwarf = require('@vscode/dwarf-debugging');
-    container
-      .bind(IWasmSymbolProvider)
-      .toDynamicValue(ctx => new WasmSymbolProvider(dwarf.spawn, cdp, ctx.container.get(ILogger)))
-      .inSingletonScope()
-      .onActivation(trackDispose);
-  } catch {
-    container.bind(IWasmSymbolProvider).to(StubWasmSymbolProvider).inSingletonScope();
-  }
-
   return container;
 };
 
@@ -290,6 +275,10 @@ export const createTopLevelSessionContainer = (parent: Container) => {
     )
     .inSingletonScope();
 
+  if (!container.isBound(IDwarfModuleProvider)) {
+    container.bind(IDwarfModuleProvider).to(DwarfModuleProvider).inSingletonScope();
+  }
+
   const browserFinderFactory = (ctor: BrowserFinderCtor) => (ctx: interfaces.Context) =>
     new ctor(ctx.container.get(ProcessEnv), ctx.container.get(FS), ctx.container.get(Execa));