Refactor RemoteThread to improve section frame handling

(#for, #each, #if)

Signed-off-by: azerr <[email protected]>

Author: angelozerr

independent-projects/qute/core/src/main/java/io/quarkus/qute/LoopSectionHelper.java

@@ -45,6 +45,10 @@ public class LoopSectionHelper implements SectionHelper {
         this.engine = context.getEngine();
     }
 
+    public String getMetadataPrefix() {
+        return metadataPrefix;
+    }
+
     @Override
     public CompletionStage<ResultNode> resolve(SectionResolutionContext context) {
         return context.resolutionContext().evaluate(iterable).thenCompose(it -> {

independent-projects/qute/debug/src/main/java/io/quarkus/qute/debug/agent/DebuggeeAgent.java

@@ -1,6 +1,6 @@
 package io.quarkus.qute.debug.agent;
 
-import static io.quarkus.qute.debug.agent.RemoteStackFrame.EMPTY_STACK_FRAMES;
+import static io.quarkus.qute.debug.agent.frames.RemoteStackFrame.EMPTY_STACK_FRAMES;
 import static io.quarkus.qute.debug.agent.scopes.RemoteScope.EMPTY_SCOPES;
 
 import java.net.URI;
@@ -37,6 +37,7 @@
 import io.quarkus.qute.debug.agent.breakpoints.RemoteBreakpoint;
 import io.quarkus.qute.debug.agent.completions.CompletionSupport;
 import io.quarkus.qute.debug.agent.evaluations.EvaluationSupport;
+import io.quarkus.qute.debug.agent.frames.RemoteStackFrame;
 import io.quarkus.qute.debug.agent.source.SourceReferenceRegistry;
 import io.quarkus.qute.debug.agent.source.SourceTemplateRegistry;
 import io.quarkus.qute.debug.agent.variables.VariablesRegistry;
@@ -177,7 +178,7 @@ public void onStartTemplate(TemplateEvent event) {
      *
      * @param event the resolve event representing the current node.
      */
-    public void onTemplateNode(ResolveEvent event) {
+    public void onBeforeResolve(ResolveEvent event) {
         if (!isEnabled()) {
             return;
         }
@@ -188,7 +189,15 @@ public void onTemplateNode(ResolveEvent event) {
         output(args);
 
         RemoteThread debuggee = getOrCreateDebuggeeThread();
-        debuggee.onTemplateNode(event);
+        debuggee.onBeforeResolve(event);
+    }
+
+    public void onAfterResolve(ResolveEvent event) {
+        if (!isEnabled()) {
+            return;
+        }
+        RemoteThread debuggee = getOrCreateDebuggeeThread();
+        debuggee.onAfterResolve(event);
     }
 
     /**

independent-projects/qute/debug/src/main/java/io/quarkus/qute/debug/agent/DebuggerEvalContext.java

@@ -7,6 +7,7 @@
 import io.quarkus.qute.EvalContext;
 import io.quarkus.qute.Expression;
 import io.quarkus.qute.ResolutionContext;
+import io.quarkus.qute.debug.agent.frames.RemoteStackFrame;
 
 /**
  * Implementation of {@link EvalContext} used by the Qute debugger.

independent-projects/qute/debug/src/main/java/io/quarkus/qute/debug/agent/DebuggerTraceListener.java

@@ -39,7 +39,12 @@ public DebuggerTraceListener(DebuggeeAgent agent) {
      */
     @Override
     public void onBeforeResolve(ResolveEvent event) {
-        agent.onTemplateNode(event);
+        agent.onBeforeResolve(event);
+    }
+
+    @Override
+    public void onAfterResolve(ResolveEvent event) {
+        agent.onAfterResolve(event);
     }
 
     /**

independent-projects/qute/debug/src/main/java/io/quarkus/qute/debug/agent/RemoteThread.java

@@ -17,6 +17,8 @@
 import io.quarkus.qute.debug.ThreadEvent;
 import io.quarkus.qute.debug.ThreadEvent.ThreadStatus;
 import io.quarkus.qute.debug.agent.breakpoints.RemoteBreakpoint;
+import io.quarkus.qute.debug.agent.frames.RemoteStackFrame;
+import io.quarkus.qute.debug.agent.frames.SectionFrameGroup;
 import io.quarkus.qute.trace.ResolveEvent;
 
 /**
@@ -65,6 +67,8 @@ public class RemoteThread extends Thread {
      */
     private transient final LinkedList<RemoteStackFrame> frames;
 
+    private transient final LinkedList<SectionFrameGroup> sectionFrameStack;
+
     /**
      * Reference to the agent managing this thread.
      */
@@ -88,6 +92,7 @@ public class RemoteThread extends Thread {
     public RemoteThread(java.lang.Thread thread, DebuggeeAgent agent) {
         this.lock = new Object();
         this.frames = new LinkedList<>();
+        this.sectionFrameStack = new LinkedList<>();
         super.setId((int) thread.getId());
         super.setName(thread.getName());
         this.agent = agent;
@@ -158,35 +163,68 @@ public boolean isStopped() {
     }
 
     /**
-     * Called when a Qute template node is about to be resolved.
+     * Called before a Qute template node is resolved.
+     * <p>
+     * Updates the current stack frames and handles section frame groups for
+     * template sections (loops, conditionals, etc.).
+     * </p>
+     *
      * <p>
-     * This method updates the stack frames and determines whether
-     * execution should be suspended due to a breakpoint or step condition.
+     * Sections include constructs like #for, #each, #if, and any other Qute
+     * section nodes. Each section has its own SectionFrameGroup which tracks
+     * the stack frames created while rendering that section.
      * </p>
      *
-     * @param event the {@link ResolveEvent} representing the node resolution
+     * @param event the ResolveEvent representing the node resolution
      */
-    public void onTemplateNode(ResolveEvent event) {
+    public void onBeforeResolve(ResolveEvent event) {
         if (this.isStopped()) {
             return;
         }
 
         var engine = event.getEngine();
-        RemoteStackFrame frame = new RemoteStackFrame(event, getCurrentFrame(), agent.getSourceTemplateRegistry(engine),
-                agent.getVariablesRegistry(), this);
+
+        // Create a new stack frame for the current node
+        RemoteStackFrame frame = new RemoteStackFrame(
+                event,
+                getCurrentFrame(),
+                agent.getSourceTemplateRegistry(engine),
+                agent.getVariablesRegistry(),
+                this);
+
+        // Handle section frames (loops / #for / #each / #if / other sections)
+        var sectionGroup = sectionFrameStack.isEmpty() ? null : sectionFrameStack.getFirst();
+        if (sectionGroup != null) {
+            // Update the section frame group index if iteration has changed and detach old frames
+            sectionGroup.detachFramesIfIndexChanged(event.getContext().getData(), frames);
+            // Add the current frame to the section group
+            sectionGroup.addFrame(frame);
+        }
+
+        // If the current node is a section, push a new SectionFrameGroup to track its frames
+        if (event.getTemplateNode().isSection()) {
+            sectionFrameStack.addFirst(new SectionFrameGroup(event.getTemplateNode().asSection().getHelper()));
+        }
+
+        // Add the frame to the main thread stack
         this.frames.addFirst(frame);
+
         String templateId = frame.getTemplateId();
         URI sourceUri = frame.getTemplateUri();
         RemoteStackFrame previous = frame.getPrevious();
 
+        // Step handling: suspend if stop condition matches
         if (this.stopCondition != null && this.stopCondition.test(event.getTemplateNode())) {
             // suspend and wait because of step reason.
             this.suspendAndWait(StoppedReason.STEP);
         } else {
+            // Breakpoint handling: suspend if a breakpoint matches this frame
             int lineNumber = frame.getLine();
             RemoteBreakpoint breakpoint = agent.getBreakpoint(sourceUri, templateId, lineNumber, engine);
             if (breakpoint != null // a breakpoint matches the frame line number
-                    && (previous == null || !previous.getTemplateId().equals(templateId) || previous.getLine() != lineNumber
+                    && (previous == null
+                            || !previous.getTemplateId().equals(templateId)
+                            || previous.getLine() != lineNumber
                             || event.getTemplateNode().isExpression())
                     && breakpoint.checkCondition(frame)) {
                 // suspend and wait because of breakpoint reason.
@@ -195,6 +233,29 @@ public void onTemplateNode(ResolveEvent event) {
         }
     }
 
+    /**
+     * Called after a Qute template node has been resolved.
+     * <p>
+     * Cleans up section frame groups if the resolved node was a section.
+     * This includes loops (#for / #each), conditionals (#if), or any other
+     * section nodes. Frames accumulated during the section are detached from
+     * the main thread stack when the section ends.
+     * </p>
+     *
+     * @param event the ResolveEvent representing the node resolution
+     */
+    public void onAfterResolve(ResolveEvent event) {
+        if (this.isStopped()) {
+            return;
+        }
+
+        // If the node is a section, pop its SectionFrameGroup and detach its frames
+        if (event.getTemplateNode().isSection()) {
+            var sectionGroup = sectionFrameStack.removeFirst();
+            sectionGroup.detachFrames(frames);
+        }
+    }
+
     /**
      * Suspends execution of the render thread and waits for debugger interaction,
      * such as "step", "resume", or expression evaluation.

independent-projects/qute/debug/src/main/java/io/quarkus/qute/debug/agent/breakpoints/RemoteBreakpoint.java

@@ -6,7 +6,7 @@
 import org.eclipse.lsp4j.debug.Source;
 
 import io.quarkus.qute.TemplateNode;
-import io.quarkus.qute.debug.agent.RemoteStackFrame;
+import io.quarkus.qute.debug.agent.frames.RemoteStackFrame;
 
 /**
  * Represents a remote breakpoint set by the client through the Debug Adapter Protocol (DAP).

independent-projects/qute/debug/src/main/java/io/quarkus/qute/debug/agent/completions/CompletionContext.java

@@ -11,7 +11,7 @@
 import org.eclipse.lsp4j.debug.CompletionItemType;
 import org.eclipse.lsp4j.debug.CompletionsResponse;
 
-import io.quarkus.qute.debug.agent.RemoteStackFrame;
+import io.quarkus.qute.debug.agent.frames.RemoteStackFrame;
 import io.quarkus.qute.debug.agent.resolvers.ValueResolverContext;
 
 /**

independent-projects/qute/debug/src/main/java/io/quarkus/qute/debug/agent/completions/CompletionSupport.java

@@ -8,7 +8,7 @@
 import org.eclipse.lsp4j.debug.CompletionsResponse;
 
 import io.quarkus.qute.debug.agent.DebuggeeAgent;
-import io.quarkus.qute.debug.agent.RemoteStackFrame;
+import io.quarkus.qute.debug.agent.frames.RemoteStackFrame;
 import io.quarkus.qute.debug.agent.resolvers.ValueResolverRegistry;
 
 /**

independent-projects/qute/debug/src/main/java/io/quarkus/qute/debug/agent/evaluations/EvaluationSupport.java

@@ -9,7 +9,7 @@
 import org.eclipse.lsp4j.jsonrpc.messages.ResponseErrorCode;
 
 import io.quarkus.qute.debug.agent.DebuggeeAgent;
-import io.quarkus.qute.debug.agent.RemoteStackFrame;
+import io.quarkus.qute.debug.agent.frames.RemoteStackFrame;
 import io.quarkus.qute.debug.agent.variables.VariablesHelper;
 
 /**

independent-projects/qute/debug/src/main/java/io/quarkus/qute/debug/agent/RemoteStackFrame.java renamed to independent-projects/qute/debug/src/main/java/io/quarkus/qute/debug/agent/frames/RemoteStackFrame.java

@@ -1,4 +1,4 @@
-package io.quarkus.qute.debug.agent;
+package io.quarkus.qute.debug.agent.frames;
 
 import java.net.URI;
 import java.util.ArrayList;
@@ -13,6 +13,8 @@
 import io.quarkus.qute.EvalContext;
 import io.quarkus.qute.TemplateNode;
 import io.quarkus.qute.TextNode;
+import io.quarkus.qute.debug.agent.DebuggerEvalContext;
+import io.quarkus.qute.debug.agent.RemoteThread;
 import io.quarkus.qute.debug.agent.evaluations.ConditionalExpressionHelper;
 import io.quarkus.qute.debug.agent.scopes.GlobalsScope;
 import io.quarkus.qute.debug.agent.scopes.LocalsScope;
@@ -263,7 +265,7 @@ public Engine getEngine() {
     }
 
     /** @return the current {@link ResolveEvent} associated with this frame */
-    ResolveEvent getEvent() {
+    public ResolveEvent getEvent() {
         return event;
     }