@en element-ref autocomplete from the last snapshot (#11)

SnapshotIndex subscribes to ReplayRunner events. On start it captures
the per-step commands from event.steps. On a stepSuccess where the
corresponding command is snapshot, it parses event.stdout with
^@(eN)\s+\[type\](?:\s+"label")? and replaces its cache, firing
onDidChange.

ElementRefCompletionProvider triggers on @ and returns the cached
refs whenever the cursor is right after @\w*. Each item shows the
ref id as the label, type · "label" as the detail, and a small
markdown popup with type/label fields. sortText preserves snapshot
order so the picker mirrors the on-screen layout.

Workflow: add `snapshot -i` early in the .ad, run that line via the
Run CodeLens, then typing @ anywhere downstream lists refs like
@e3 [text] "Sign in" — pick one and `click @e3` is filled in.

Author: azizbecha

src/extension.ts

@@ -15,6 +15,7 @@ import { PlatformDiagnostics } from './diagnostics/platformValidator';
 import { RunOutputPanel } from './panels/runOutputPanel';
 import { SettingsPanel } from './panels/settingsPanel';
 import { CommandCompletionProvider } from './providers/completionProvider';
+import { ElementRefCompletionProvider } from './providers/elementRefCompletionProvider';
 import { CommandHoverProvider } from './providers/hoverProvider';
 import { RunStepCodeLensProvider } from './providers/runStepCodeLensProvider';
 import { ValueCompletionProvider } from './providers/valueCompletionProvider';
@@ -24,6 +25,7 @@ import { ReplayRunner } from './runners/replayRunner';
 import { AdFileIndex } from './services/adFileIndex';
 import { AgentDeviceConfig } from './services/config';
 import { DeviceCatalog, type DeviceEntry } from './services/deviceCatalog';
+import { SnapshotIndex } from './services/snapshotIndex';
 import { AgentDeviceTestController } from './testing/agentDeviceTestController';
 import { formatDuration } from './util/duration';
 import { pluralize } from './util/pluralize';
@@ -51,7 +53,10 @@ export function activate(context: vscode.ExtensionContext): void {
   const reportWriter = new HtmlReportWriter(runner, config);
   context.subscriptions.push(reportWriter);
 
-  registerLanguageProviders(context);
+  const snapshotIndex = new SnapshotIndex(runner);
+  context.subscriptions.push(snapshotIndex);
+
+  registerLanguageProviders(context, snapshotIndex);
   registerDiagnostics(context);
   registerRunOutputPanel(context, runner, fileIndex, reportWriter);
   registerSettingsPanel(context, config);
@@ -206,7 +211,10 @@ function registerSettingsCommand(context: vscode.ExtensionContext): void {
   );
 }
 
-function registerLanguageProviders(context: vscode.ExtensionContext): void {
+function registerLanguageProviders(
+  context: vscode.ExtensionContext,
+  snapshotIndex: SnapshotIndex,
+): void {
   const completion = new CommandCompletionProvider(
     COMMANDS,
     DIRECTIVES,
@@ -240,6 +248,15 @@ function registerLanguageProviders(context: vscode.ExtensionContext): void {
     ),
   );
 
+  const elementRefs = new ElementRefCompletionProvider(snapshotIndex);
+  context.subscriptions.push(
+    vscode.languages.registerCompletionItemProvider(
+      LANGUAGE_ID,
+      elementRefs,
+      ...ElementRefCompletionProvider.triggerCharacters,
+    ),
+  );
+
   const hover = new CommandHoverProvider(COMMAND_BY_NAME, DIRECTIVE_BY_NAME);
   context.subscriptions.push(vscode.languages.registerHoverProvider(LANGUAGE_ID, hover));
 

src/providers/elementRefCompletionProvider.ts

@@ -0,0 +1,59 @@
+import * as vscode from 'vscode';
+
+import type { SnapshotIndex } from '../services/snapshotIndex';
+
+const TRIGGER_PATTERN = /@\w*$/;
+
+export class ElementRefCompletionProvider implements vscode.CompletionItemProvider {
+  static readonly triggerCharacters: readonly string[] = ['@'];
+
+  constructor(private readonly index: SnapshotIndex) {}
+
+  provideCompletionItems(
+    document: vscode.TextDocument,
+    position: vscode.Position,
+  ): vscode.CompletionItem[] {
+    const refs = this.index.refs;
+    if (refs.length === 0) {
+      return [];
+    }
+    const linePrefix = document.lineAt(position.line).text.slice(0, position.character);
+    if (!TRIGGER_PATTERN.test(linePrefix)) {
+      return [];
+    }
+    return refs.map((ref, idx) => {
+      const item = new vscode.CompletionItem(`@${ref.id}`, vscode.CompletionItemKind.Reference);
+      item.insertText = `@${ref.id}`;
+      item.detail = formatDetail(ref);
+      item.sortText = `00${idx.toString().padStart(4, '0')}`;
+      const md = new vscode.MarkdownString(formatMarkdown(ref));
+      md.supportHtml = false;
+      item.documentation = md;
+      return item;
+    });
+  }
+}
+
+function formatDetail(ref: { type?: string; label?: string }): string {
+  if (ref.type && ref.label) {
+    return `${ref.type} · ${ref.label}`;
+  }
+  if (ref.type) {
+    return ref.type;
+  }
+  if (ref.label) {
+    return ref.label;
+  }
+  return 'element ref';
+}
+
+function formatMarkdown(ref: { id: string; type?: string; label?: string }): string {
+  const lines = ['*From the most recent snapshot.*'];
+  if (ref.type) {
+    lines.push(`Type: \`${ref.type}\``);
+  }
+  if (ref.label) {
+    lines.push(`Label: \`${ref.label}\``);
+  }
+  return lines.join('\n\n');
+}

src/services/snapshotIndex.ts

@@ -0,0 +1,98 @@
+import * as vscode from 'vscode';
+
+import type { ReplayEvent, ReplayRunner } from '../runners/replayRunner';
+
+export interface SnapshotRef {
+  readonly id: string;
+  readonly type?: string;
+  readonly label?: string;
+}
+
+const REF_LINE = /^\s*@(e\d+)\s+\[([^\]]+)\](?:\s+"((?:[^"\\]|\\.)*)")?/;
+
+export class SnapshotIndex implements vscode.Disposable {
+  private readonly emitter = new vscode.EventEmitter<void>();
+  private readonly disposables: vscode.Disposable[] = [];
+  private currentRefs: readonly SnapshotRef[] = [];
+  private currentScriptPath: string | null = null;
+  private stepCommands: readonly string[] = [];
+  private currentRunScriptPath: string | null = null;
+
+  readonly onDidChange = this.emitter.event;
+
+  constructor(runner: ReplayRunner) {
+    this.disposables.push(runner.onEvent((event) => this.handleEvent(event)));
+  }
+
+  dispose(): void {
+    this.emitter.dispose();
+    for (const disposable of this.disposables) {
+      disposable.dispose();
+    }
+  }
+
+  get refs(): readonly SnapshotRef[] {
+    return this.currentRefs;
+  }
+
+  get scriptPath(): string | null {
+    return this.currentScriptPath;
+  }
+
+  private handleEvent(event: ReplayEvent): void {
+    switch (event.type) {
+      case 'start':
+        this.stepCommands = event.steps.map((s) => firstToken(s.display));
+        this.currentRunScriptPath = event.scriptPath;
+        break;
+      case 'stepSuccess': {
+        const command = this.stepCommands[event.index];
+        if (command !== 'snapshot' || !this.currentRunScriptPath) {
+          return;
+        }
+        const refs = parseSnapshotRefs(event.stdout);
+        if (refs.length === 0) {
+          return;
+        }
+        this.currentRefs = refs;
+        this.currentScriptPath = this.currentRunScriptPath;
+        this.emitter.fire();
+        break;
+      }
+      case 'end':
+        this.stepCommands = [];
+        this.currentRunScriptPath = null;
+        break;
+    }
+  }
+}
+
+export function parseSnapshotRefs(stdout: string): SnapshotRef[] {
+  const refs: SnapshotRef[] = [];
+  const seen = new Set<string>();
+  for (const line of stdout.split(/\r?\n/)) {
+    const match = REF_LINE.exec(line);
+    if (!match) {
+      continue;
+    }
+    const [, id, type, label] = match;
+    if (!id || seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    refs.push({
+      id,
+      type: type?.trim(),
+      label: label ? unescapeLabel(label) : undefined,
+    });
+  }
+  return refs;
+}
+
+function firstToken(line: string): string {
+  return line.split(/\s+/)[0] ?? '';
+}
+
+function unescapeLabel(value: string): string {
+  return value.replace(/\\(.)/g, '$1');
+}