Break on fail during debugging (#2400)

This change updates the behavior of `fail` expressions during debugging
such that they trigger a new kind of `StepResultId` that propagates up
into the extension and will cause a debug session to stop just before
the failure is processed.



https://github.com/user-attachments/assets/30d11954-d9b4-460d-8a7a-ef5dfdb1b2f6

Author: swernli

compiler/qsc_eval/src/lib.rs

@@ -344,6 +344,7 @@ pub enum StepResult {
     StepIn,
     StepOut,
     Return(Value),
+    Fail,
 }
 
 trait AsIndex {
@@ -692,6 +693,10 @@ impl State {
                         None => continue,
                     }
                 }
+                Some(ExecGraphNode::Fail) => {
+                    self.idx += 1;
+                    return Ok(StepResult::Fail);
+                }
                 Some(ExecGraphNode::Jump(idx)) => {
                     self.idx = *idx;
                     continue;

compiler/qsc_fir/src/fir.rs

@@ -929,6 +929,8 @@ pub enum ExecGraphNode {
     PushScope,
     /// A pop of the current scope, used when tracking variables for debugging.
     PopScope,
+    /// A failure node, inserted just before a `fail` expression to halt execution for debugging.
+    Fail,
 }
 
 /// A sequenced block of statements.

compiler/qsc_lowerer/src/lib.rs

@@ -557,7 +557,15 @@ impl Lowerer {
                 let arg = self.lower_expr(arg);
                 fir::ExprKind::Call(call, arg)
             }
-            hir::ExprKind::Fail(message) => fir::ExprKind::Fail(self.lower_expr(message)),
+            hir::ExprKind::Fail(message) => {
+                // Ensure the right-hand side expression is lowered first so that it
+                // is executed before the fail node, if any.
+                let fail = fir::ExprKind::Fail(self.lower_expr(message));
+                if self.enable_debug {
+                    self.exec_graph.push(ExecGraphNode::Fail);
+                }
+                fail
+            }
             hir::ExprKind::Field(container, field) => {
                 let container = self.lower_expr(container);
                 let field = lower_field(field);

vscode/src/debugger/session.ts

@@ -336,6 +336,9 @@ export class QscDebugSession extends LoggingDebugSession {
       this.sendEvent(evt);
     } else if (result.id == StepResultId.Return) {
       await this.endSession(`ending session`, 0);
+    } else if (result.id == StepResultId.Fail) {
+      log.trace(`step result: ${result.id} ${result.value}`);
+      this.sendEvent(new StoppedEvent("exception", QscDebugSession.threadID));
     } else {
       log.trace(`step result: ${result.id} ${result.value}`);
       this.sendEvent(new StoppedEvent("step", QscDebugSession.threadID));
@@ -387,13 +390,22 @@ export class QscDebugSession extends LoggingDebugSession {
     // supports shots.
     for (let i = 0; i < args.shots; i++) {
       try {
-        const result = await this.debugService.evalContinue(
+        let result = await this.debugService.evalContinue(
           bps,
           this.eventTarget,
         );
 
+        // Ensure the circuit is updated before checking for fail, since the
+        // right-hand side of the fail expression may itself be a block that includes
+        // gate calls.
         await this.updateCircuit();
 
+        if (result.id == StepResultId.Fail) {
+          // This was a runtime failure in the program, so we need to continue to
+          // trigger the actual failure event.
+          result = await this.debugService.evalContinue(bps, this.eventTarget);
+        }
+
         if (result.id != StepResultId.Return) {
           await this.endSession(`execution didn't run to completion`, -1);
           return;

wasm/src/debug_service.rs

@@ -281,6 +281,10 @@ impl From<StepResult> for StructStepResult {
                 id: StepResultId::Return.into(),
                 value: 0,
             },
+            StepResult::Fail => StructStepResult {
+                id: StepResultId::Fail.into(),
+                value: 0,
+            },
         }
     }
 }
@@ -293,6 +297,7 @@ pub enum StepResultId {
     StepIn = 2,
     StepOut = 3,
     Return = 4,
+    Fail = 5,
 }
 
 impl From<StepResultId> for usize {