Drive prewarm bindings off command argDefs, not an allowlist

sembrestels · sembrestels · commit e69b9ffe0b36 · 2026-04-25T05:08:03.000+02:00
The prewarm walker previously fed `getCommandsUntilLine` a hardcoded
list of `["load", "set", "switch"]`, silently skipping every other
binding-producing command. Hovering `$voting` after `install $voting
voting:0.1.0`, `$myDao` after `new-dao`, `$myToken` after `new-token`,
or any variable defined by `deploy`, `sign`, `for` returned "no info";
helpers nested inside a `connect myDao { ... }` block whose body the
cursor wasn't in never reached the helper cache either.

Replaces the allowlist with a new `getAllCommandsUntilLine(line)`
traversal that visits every command in DFS pre-order regardless of
block nesting. Per-command behaviour is now driven entirely by the
node itself: `argDef.type === "variable"` seeds the USER binding,
custom argDef types with a `resolve()` hook (`module`, `dao`, ...)
get invoked, and any `eventCaptures` / `errorCaptures` on the node
seed placeholder bindings for their slot variables (and `boolVar`),
mirroring the runtime's `applyDestructure` `$`-prefixing rule. New
binding-producing commands therefore participate in prewarm with no
allowlist edits.

Hover suppresses the noisy `**Variable** $foo = $foo` rendering when
the binding value is the placeholder name (i.e. the command can't
predict its runtime output yet), so `$myContract` from `deploy`
shows as `**Variable** $myContract` rather than restating itself.

Adds regression coverage for the `deploy`-style variable, the
`-&gt; Evt(...) [$a $b]` event capture, and the `-!&gt;` / `-?!&gt;` error
capture (both destructure and boolVar shapes).

Made-with: Cursor
diff --git a/packages/core/src/EvmlAST.ts b/packages/core/src/EvmlAST.ts
@@ -38,6 +38,41 @@ export class EvmlAST implements AST {
     );
   }
 
+  /**
+   * Walk every command in the AST up to (and including) `line`,
+   * descending into every block expression regardless of whether it
+   * encloses `line`. Returns a flat list in DFS pre-order (parent
+   * before its block's children). Used by the prewarm walker so that
+   * hover sees bindings produced by any command — `set`, `deploy`,
+   * `new-dao`, `install`, `for`, `sign`, command-with-event/error
+   * captures, ... — without having to enumerate command names by hand.
+   */
+  getAllCommandsUntilLine(line: number): CommandExpressionNode[] {
+    return this.#getAllCommandsUntilLine(this.body, line);
+  }
+
+  #getAllCommandsUntilLine(
+    body: CommandExpressionNode[],
+    line: number,
+  ): CommandExpressionNode[] {
+    const out: CommandExpressionNode[] = [];
+    for (const c of body) {
+      if (c.loc?.start.line && c.loc.start.line > line) continue;
+      out.push(c);
+      for (const arg of c.args) {
+        if (arg.type === NodeType.BlockExpression) {
+          out.push(
+            ...this.#getAllCommandsUntilLine(
+              (arg as BlockExpressionNode).body,
+              line,
+            ),
+          );
+        }
+      }
+    }
+    return out;
+  }
+
   #getCommandAtLine(
     line: number,
     body: CommandExpressionNode[],
diff --git a/packages/core/src/hover/index.ts b/packages/core/src/hover/index.ts
@@ -360,12 +360,20 @@ export async function getHoverInfo(
     );
     const formatted = formatVariableValue(value, scriptLines);
 
+    // Commands like `deploy`, `new-dao`, `new-token`, `install`, `sign`
+    // and `for` produce a runtime value the prewarm walker can't
+    // predict; it seeds the binding with the variable's own name as a
+    // placeholder so subsequent hovers know the symbol is defined.
+    // Treat that as "no resolvable value yet" rather than rendering
+    // `**Variable** $voting = $voting`.
+    const isPlaceholder = formatted === token.value;
+
     // Single-line card: `**Variable** $name = value`. The address
     // card, if any, is appended as a separate section so the renderer
     // draws the green divider between the two — no need for a verbose
     // "(variable)" tag or "(defined on line N)" hint.
     const labelCard =
-      formatted != null
+      formatted != null && !isPlaceholder
         ? `**Variable** ${token.value} = ${formatted}`
         : `**Variable** ${token.value}`;
     const sections: string[] = [labelCard];
diff --git a/packages/core/src/scriptWalk.ts b/packages/core/src/scriptWalk.ts
@@ -4,6 +4,8 @@ import type {
   CompletionContext,
   DestructurePatternNode,
   DestructureSlot,
+  ErrorCaptureNode,
+  EventCaptureNode,
   HelperResolver,
   ICommand,
   ModuleBinding,
@@ -262,8 +264,64 @@ function seedDestructureSlots(
 // Walk
 // ---------------------------------------------------------------------------
 
+/** Seed every `EventCapture` / `ErrorCapture` slot on a command as a
+ *  USER binding. The walker can't predict the runtime value (logs and
+ *  reverts only exist at execution time), so the bindings hold a
+ *  placeholder name that the hover renderer suppresses — what matters
+ *  is that the variable *exists* in the prewarm snapshot, so hovering
+ *  `$err` later renders `**Variable** $err` instead of "no info".
+ *
+ *  Note: capture slots are parsed WITHOUT the `$` prefix (the runtime
+ *  prefixes them when calling `applyDestructure`). We mirror that here
+ *  so the hover lookup `bindings.getBindingValue("$err", USER)` finds
+ *  the placeholder. */
+function seedCapturePlaceholders(
+  slots: DestructureSlot[],
+  bindings: BindingsManager,
+): void {
+  for (const s of slots) {
+    if (typeof s === "string") {
+      const key = `$${s}`;
+      try {
+        bindings.setBinding(key, key, USER);
+      } catch {
+        // binding already exists
+      }
+    } else if (Array.isArray(s)) {
+      seedCapturePlaceholders(s, bindings);
+    }
+  }
+}
+
+function seedCaptureBindings(
+  c: CommandExpressionNode,
+  bindings: BindingsManager,
+): void {
+  const captures: Array<EventCaptureNode | ErrorCaptureNode> = [
+    ...(c.eventCaptures ?? []),
+    ...(c.errorCaptures ?? []),
+  ];
+  for (const cap of captures) {
+    seedCapturePlaceholders(cap.captures, bindings);
+    if ("boolVar" in cap && cap.boolVar) {
+      try {
+        bindings.setBinding(`$${cap.boolVar}`, `$${cap.boolVar}`, USER);
+      } catch {
+        // binding already exists
+      }
+    }
+  }
+}
+
 /** Walk a list of fully-typed command nodes and resolve any bindings they
- *  produce (variable → USER, custom type with resolve → arbitrary bindings).
+ *  produce (variable → USER, custom type with resolve → arbitrary bindings,
+ *  event/error captures → USER placeholders).
+ *
+ *  Per-command behaviour is driven by the command's own argDefs (looking
+ *  for `type: "variable"` or a custom type with a `resolve()` hook) and
+ *  by any `eventCaptures` / `errorCaptures` attached to the node — never
+ *  by command-name allowlists. New binding-producing commands therefore
+ *  participate in prewarm automatically.
  *
  *  When `history` is provided, each `set`-style variable assignment is also
  *  appended to it as `{ line, value }`. Hover uses this to render the value
@@ -286,6 +344,12 @@ export async function walkCommandsForBindings(
     }
     const commandModule = c.module ?? parentModule;
 
+    // Even when the command isn't registered (e.g. an aragonos command
+    // before `load aragonos` has run, or a typo) the user can still
+    // attach event/error captures to it — seed those so hover finds
+    // the symbols even when the command resolution fails.
+    seedCaptureBindings(c, bindings);
+
     const command = await resolveCommandNode(c, bindings, commandModule);
     if (!command) continue;
 
@@ -414,16 +478,24 @@ export interface WalkResult {
 }
 
 /**
- * Parse `script` and walk all `load` / `set` / `switch` commands up to and
- * including `upToLine`. Helper-function results are written into
- * `moduleCache`'s CACHE space (using the same key shape as completions),
- * which is what makes hover's address card visible for `@ens(...)` etc.
+ * Parse `script` and walk every command up to (and including) `upToLine`,
+ * producing the bindings + variable history hover needs to render rich
+ * cards. Helper-function results are also written into `moduleCache`'s
+ * CACHE space (using the same key shape as completions), which is what
+ * makes hover's address card visible for `@ens(...)` etc.
  *
- * `upToLine` is 1-indexed (matches `Position.line`).  Pass `Infinity` to walk
- * the entire script.
+ * Per-command behaviour is purely argDef-driven (see
+ * `walkCommandsForBindings`): commands with `type: "variable"` argDefs
+ * seed USER bindings, custom-typed argDefs with a `resolve()` hook get
+ * invoked, and any `eventCaptures` / `errorCaptures` on a node seed
+ * placeholder bindings for the captured slots. This means new
+ * binding-producing commands work automatically — no allowlist edits.
+ *
+ * `upToLine` is 1-indexed (matches `Position.line`). Pass `Infinity` to
+ * walk the entire script.
  *
  * Returns the per-walk USER bindings and the effective chainId after any
- * `switch` commands.  Failures during parsing or RPC lookup are swallowed —
+ * `switch` commands. Failures during parsing or RPC lookup are swallowed —
  * the function always resolves so callers can use it as a best-effort
  * pre-warm step.
  */
@@ -456,24 +528,18 @@ export async function walkScript(
     }
   }
 
-  const commandNodes: CommandExpressionNode[] = (
-    ast?.getCommandsUntilLine(upToLine, ["load", "set", "switch"]) ?? []
-  ).filter((c: CommandExpressionNode) => {
-    const itHasCommandsBlock = hasCommandsBlock(c);
-    const loc = c.loc;
-    if (
-      !itHasCommandsBlock ||
-      (itHasCommandsBlock &&
-        loc &&
-        upToLine >= loc.start.line &&
-        upToLine <= loc.end.line)
-    ) {
-      return true;
-    }
-    return false;
-  });
-
-  // Apply switch commands to find the effective client/chain.
+  // Walk EVERY command up to `upToLine`, including those inside blocks
+  // that don't enclose the cursor (e.g. a `connect myDao { ... }`
+  // block whose body installs apps the rest of the script references).
+  // The per-command logic in `walkCommandsForBindings` already decides
+  // what to do based on each command's argDefs and capture nodes — no
+  // command-name allowlist required.
+  const commandNodes: CommandExpressionNode[] =
+    ast?.getAllCommandsUntilLine(upToLine) ?? [];
+
+  // Apply switch commands to find the effective client/chain. `switch`
+  // is the only command that mutates *which* chain the rest of the
+  // walk runs against, so it gets a dedicated pre-pass.
   let effectiveClient = client;
   for (const c of commandNodes) {
     const switchedChainId = resolveSwitchChainId(c, bindings);
@@ -510,16 +576,13 @@ export async function walkScript(
     variableHistory,
   );
 
-  // Second pass: populate the helper cache for *all* commands the user
-  // might hover over, not just the ones that produce bindings. Without
-  // this, `print @token(DAI)` and similar helpers used as direct args
-  // to non-binding commands never reach the cache and the hover card
-  // can't show their resolved address. Helpers already evaluated
-  // during `walkCommandsForBindings` are cache hits and re-add no
-  // network cost.
-  const allCommandNodes: CommandExpressionNode[] =
-    ast?.getCommandsUntilLine(upToLine) ?? [];
-  await prewarmHelperExpressions(allCommandNodes, resolveNode);
+  // Second pass: populate the helper cache for *every* command the
+  // user might hover over, including helpers inside non-binding
+  // commands (`print @token(DAI)`) and helpers nested deep inside
+  // `connect myDao { ... }` blocks. Helpers already evaluated during
+  // `walkCommandsForBindings` are cache hits and re-add no network
+  // cost.
+  await prewarmHelperExpressions(commandNodes, resolveNode);
 
   return { bindings, chainId, client: effectiveClient, variableHistory };
 }
diff --git a/packages/core/test/integration/hover.test.ts b/packages/core/test/integration/hover.test.ts
@@ -115,6 +115,68 @@ describe("Core > hover", () => {
       expect(c).to.match(/\*\*EOA\*\*|\*\*Contract\*\*/);
     });
 
+    it("seeds variable bindings for any command with a `type: variable` argDef", async () => {
+      // Regression: previously the prewarm walker only visited
+      // `load`/`set`/`switch` commands, so variables created by
+      // commands like `deploy`, `new-dao`, `new-token`, `install`,
+      // `sign` and `for` were never seeded — hovering them returned
+      // null. The walker now visits every command and trusts each
+      // command's own argDefs to decide what to bind, so any
+      // `type: "variable"` argDef on any command participates in
+      // prewarm automatically.
+      const script = "deploy $myContract Foo.sol\nprint $myContract";
+      const evm = ctx.createEvm();
+      await evm.prewarm(script);
+      const result = await evm.getHoverInfo(script, { line: 2, col: 8 });
+      expect(result).to.not.be.null;
+      const c = result!.contents.join("\n");
+      expect(c).to.include("**Variable**");
+      expect(c).to.include("$myContract");
+      // Placeholder bindings (value === name) shouldn't render as
+      // `$myContract = $myContract` — that's noise.
+      expect(c).to.not.include("= $myContract");
+    });
+
+    it("seeds variable bindings for event-capture slots", async () => {
+      // The `-> Withdrawn(uint, address) [$amount $to]` syntax
+      // attaches an `EventCaptureNode` to a command. The walker has to
+      // descend into `c.eventCaptures` and seed each slot as a USER
+      // placeholder so hover finds `$amount` even though no command
+      // argDef declares it.
+      const script =
+        "exec $contract withdraw() -> Withdrawn(uint,address) [$amount $to]\nprint $amount";
+      const evm = ctx.createEvm();
+      await evm.prewarm(script);
+      const result = await evm.getHoverInfo(script, { line: 2, col: 8 });
+      expect(result).to.not.be.null;
+      const c = result!.contents.join("\n");
+      expect(c).to.include("**Variable**");
+      expect(c).to.include("$amount");
+      expect(c).to.not.include("= $amount");
+    });
+
+    it("seeds variable bindings for error-capture slots and bool flags", async () => {
+      // `-!> Err(uint) [$shortfall]` (required) and `-?!> Err $e`
+      // (optional, boolean) both produce USER bindings the walker
+      // must seed so hover finds them. We exercise both shapes in one
+      // script — the boolVar variant goes through a different code
+      // path than the destructure-slot variant.
+      const script = [
+        "exec $contract transfer(uint) 100 -!> InsufficientBalance(uint) [$shortfall]",
+        "exec $contract approve(address,uint) $spender 1 -?!> Unauthorized() $authErr",
+        "print $shortfall",
+        "print $authErr",
+      ].join("\n");
+      const evm = ctx.createEvm();
+      await evm.prewarm(script);
+      const shortfall = await evm.getHoverInfo(script, { line: 3, col: 8 });
+      const authErr = await evm.getHoverInfo(script, { line: 4, col: 8 });
+      expect(shortfall).to.not.be.null;
+      expect(shortfall!.contents.join("\n")).to.include("$shortfall");
+      expect(authErr).to.not.be.null;
+      expect(authErr!.contents.join("\n")).to.include("$authErr");
+    });
+
     it("appends the address card under @token(...) when used as a direct arg to a non-binding command", async () => {
       // Regression: previously the prewarm walker only visited
       // `load`/`set`/`switch` commands, so helpers used as direct args to
