feat(debugger): inspect caller frame bindings (#997)

Author: ziflex

debug_session_benchmark_test.go

@@ -49,3 +49,55 @@ RETURN FOR i IN 1..100
 		}
 	}
 }
+
+func BenchmarkDebugSessionPausedCallerFrameInspection(b *testing.B) {
+	engine, err := New()
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer engine.Close()
+
+	plan, err := engine.CompileDebug(context.Background(), source.New("caller.fql", `LET base = 1
+FUNC outer(p) {
+  LET carried = base + p
+  FUNC inner(q) {
+    RETURN carried + q
+  }
+  LET result = inner(3)
+  RETURN result
+}
+RETURN outer(2)`))
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer plan.Close()
+
+	session, err := plan.NewDebugSession(context.Background())
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer session.Close()
+
+	if _, err := session.SetBreakpoint("caller.fql", 5); err != nil {
+		b.Fatal(err)
+	}
+	if _, err := session.Start(context.Background()); err != nil {
+		b.Fatal(err)
+	}
+	if _, err := session.Continue(context.Background()); err != nil {
+		b.Fatal(err)
+	}
+
+	b.ReportAllocs()
+	b.ResetTimer()
+
+	for b.Loop() {
+		locals, localsErr := session.FrameLocals(2)
+		if localsErr != nil {
+			b.Fatal(localsErr)
+		}
+		if len(locals) == 0 {
+			b.Fatal("caller frame has no locals")
+		}
+	}
+}

debug_session_udf_resolution_test.go

@@ -2,10 +2,13 @@ package ferret
 
 import (
 	"context"
+	"errors"
 	"strings"
 	"testing"
 
+	"github.com/MontFerret/ferret/v2/pkg/debugger"
 	"github.com/MontFerret/ferret/v2/pkg/diagnostics"
+	"github.com/MontFerret/ferret/v2/pkg/runtime"
 	"github.com/MontFerret/ferret/v2/pkg/source"
 )
 
@@ -303,4 +306,140 @@ RETURN y`
 	if !strings.Contains(formatted, "udf-error.fql:4") || !strings.Contains(formatted, "RETURN b / 0") {
 		t.Fatalf("expected UDF error location, got:\n%s", formatted)
 	}
+	assertFrameValues(t, session, 1, map[string]string{"x": "1"})
+	value, err := session.EvaluateFrame(context.Background(), 1, "x + 1")
+	if err != nil || value.Display != "2" {
+		t.Fatalf("unexpected runtime-error caller evaluation: %#v, %v", value, err)
+	}
+}
+
+func TestDebugSessionCallerFramesExposeBindingsCellsAndParameters(t *testing.T) {
+	engine, err := New()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer engine.Close()
+
+	query := `VAR shared = 1
+FUNC outer(p) {
+  VAR x = p + shared - shared
+  FUNC inner(q) {
+    shared = shared + q
+    LET x = shared + q
+    RETURN x
+  }
+  LET result = inner(3)
+  RETURN result
+}
+LET box = {value: 10}
+LET x = 10
+RETURN outer(2) + x + @input + box.value - 10`
+	plan, err := engine.CompileDebug(context.Background(), source.New("caller-frames.fql", query))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer plan.Close()
+
+	session, err := plan.NewDebugSession(context.Background(), WithSessionParam("input", 5))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer session.Close()
+
+	breakpoint, err := session.SetBreakpoint("caller-frames.fql", 5)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !breakpoint.Bound || breakpoint.Line != 5 {
+		t.Fatalf("unexpected inner breakpoint: %#v", breakpoint)
+	}
+
+	if _, err := session.Start(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	event, err := session.Continue(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if event.Reason != DebugReasonBreakpoint || event.Location.Line != 5 || event.Depth != 2 {
+		t.Fatalf("unexpected nested stop: %#v", event)
+	}
+
+	frames, err := session.Frames()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(frames) != 3 || frames[0].Name != "inner" || frames[1].Name != "outer" || frames[2].Name != "<main>" {
+		t.Fatalf("unexpected nested frames: %#v", frames)
+	}
+
+	assertFrameValues(t, session, 0, map[string]string{"q": "3", "shared": "1", "@input": "5"})
+	assertFrameValues(t, session, 1, map[string]string{"p": "2", "x": "2", "shared": "1", "@input": "5"})
+	assertFrameValues(t, session, 2, map[string]string{"x": "10", "shared": "1", "@input": "5"})
+
+	callerLocals, err := session.FrameLocals(2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var callerReference debugger.ValueReference
+	for _, local := range callerLocals {
+		if local.Name == "box" {
+			callerReference = local.Value.Reference
+		}
+	}
+	if !callerReference.Valid() {
+		t.Fatalf("expected expandable caller value: %#v", callerLocals)
+	}
+
+	value, err := session.EvaluateFrame(context.Background(), 2, "x + shared + @input")
+	if err != nil || value.Display != "16" {
+		t.Fatalf("unexpected caller evaluation: %#v, %v", value, err)
+	}
+	if _, err := session.FrameLocals(-1); !errors.Is(err, runtime.ErrInvalidArgument) {
+		t.Fatalf("expected negative frame rejection, got %v", err)
+	}
+	if _, err := session.FrameLocals(len(frames)); !errors.Is(err, runtime.ErrNotFound) {
+		t.Fatalf("expected missing frame rejection, got %v", err)
+	}
+
+	event, err = session.Step(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if event.Location.Line != 6 {
+		t.Fatalf("unexpected mutable-cell step: %#v", event)
+	}
+	if _, err := session.Variables(callerReference); !errors.Is(err, runtime.ErrNotFound) {
+		t.Fatalf("expected caller reference to become stale on resume, got %v", err)
+	}
+	assertFrameValues(t, session, 0, map[string]string{"shared": "4", "@input": "5"})
+	assertFrameValues(t, session, 1, map[string]string{"x": "2", "shared": "4", "@input": "5"})
+	assertFrameValues(t, session, 2, map[string]string{"x": "10", "shared": "4", "@input": "5"})
+
+	value, err = session.EvaluateFrame(context.Background(), 1, "x + shared + @input")
+	if err != nil || value.Display != "11" {
+		t.Fatalf("unexpected mutable caller evaluation: %#v, %v", value, err)
+	}
+}
+
+func assertFrameValues(t *testing.T, session interface {
+	FrameLocals(int) ([]debugger.Variable, error)
+}, frame int, expected map[string]string) {
+	t.Helper()
+
+	locals, err := session.FrameLocals(frame)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	actual := make(map[string]string, len(locals))
+	for _, local := range locals {
+		actual[local.Name] = local.Value.Display
+	}
+
+	for name, value := range expected {
+		if actual[name] != value {
+			t.Fatalf("frame %d binding %q: expected %q, got %q in %#v", frame, name, value, actual[name], locals)
+		}
+	}
 }

pkg/debugger/session.go

@@ -316,6 +316,12 @@ func (s *Session) Frames() ([]Frame, error) {
 
 // Locals returns the visible top-frame locals followed by bound parameters.
 func (s *Session) Locals() ([]Variable, error) {
+	return s.FrameLocals(0)
+}
+
+// FrameLocals returns the visible locals and bound parameters for one paused
+// frame. Frame indexes follow Frames: zero is the current frame.
+func (s *Session) FrameLocals(frame int) ([]Variable, error) {
 	if err := s.lockCommand(); err != nil {
 		return nil, err
 	}
@@ -324,7 +330,7 @@ func (s *Session) Locals() ([]Variable, error) {
 	if err := s.ensureOpen(); err != nil {
 		return nil, err
 	}
-	locals, err := s.execution.Locals()
+	locals, err := s.frameLocals(frame)
 
 	if err != nil {
 		return nil, err
@@ -349,6 +355,18 @@ func (s *Session) Locals() ([]Variable, error) {
 	return out, nil
 }
 
+func (s *Session) frameLocals(frame int) ([]vm.DebugLocal, error) {
+	if inspector, ok := s.execution.(vm.DebugFrameInspector); ok {
+		return inspector.FrameLocals(frame)
+	}
+
+	if frame != 0 {
+		return nil, runtime.Error(runtime.ErrInvalidOperation, "debug execution does not support caller frame inspection")
+	}
+
+	return s.execution.Locals()
+}
+
 // Variables returns the child variables for one expandable debugger value from
 // the current paused state.
 func (s *Session) Variables(reference ValueReference) ([]Variable, error) {
@@ -408,6 +426,11 @@ func (s *Session) Variables(reference ValueReference) ([]Variable, error) {
 // rejects calls, queries, mutation, async/event behavior, and full collection
 // execution.
 func (s *Session) Evaluate(ctx context.Context, expression string) (Value, error) {
+	return s.EvaluateFrame(ctx, 0, expression)
+}
+
+// EvaluateFrame evaluates an expression against one paused frame.
+func (s *Session) EvaluateFrame(ctx context.Context, frame int, expression string) (Value, error) {
 	if err := s.lockCommand(); err != nil {
 		return Value{}, err
 	}
@@ -416,7 +439,7 @@ func (s *Session) Evaluate(ctx context.Context, expression string) (Value, error
 	if err := s.ensureOpen(); err != nil {
 		return Value{}, err
 	}
-	locals, err := s.execution.Locals()
+	locals, err := s.frameLocals(frame)
 
 	if err != nil {
 		return Value{}, err

pkg/debugger/session_concurrency_test.go

@@ -161,7 +161,7 @@ func TestSessionCloseClearsReferencesCreatedByActiveInspection(t *testing.T) {
 
 	localsDone := make(chan error, 1)
 	go func() {
-		_, err := session.Locals()
+		_, err := session.FrameLocals(0)
 		localsDone <- err
 	}()
 	waitForSignal(t, inspectStarted, "value inspection")

pkg/debugger/session_test.go

@@ -66,6 +66,13 @@ func TestSessionUsesInterfacesForBreakpointsEvaluationAndLifecycle(t *testing.T)
 	if value.Display != "2" || values.typeCalls == 0 || values.debugInfoCalls == 0 {
 		t.Fatalf("unexpected evaluated value: %#v", value)
 	}
+	if _, err := session.FrameLocals(1); !errors.Is(err, runtime.ErrInvalidOperation) {
+		t.Fatalf("expected legacy execution to reject caller inspection, got %v", err)
+	}
+	value, err = session.EvaluateFrame(context.Background(), 0, "x + 2")
+	if err != nil || value.Display != "3" {
+		t.Fatalf("unexpected legacy top-frame evaluation: %#v, %v", value, err)
+	}
 	if err := session.Close(); err != nil {
 		t.Fatal(err)
 	}