visual_debugger/scripts/dump_debug_graph.py

#!/usr/bin/env python3
"""Drives both the C++ and Rust debug builds under gdb to their equivalent
breakpoint (right after the 30/20/10 list is built), evaluates
$debug_graph(list) exactly as VS Code's "Debug Visualizer" extension would
(via -data-evaluate-expression), and replays the extension's own
parseEvaluationResultFromGenericDebugAdapter algorithm on the raw result --
so we can tell, without going through the VS Code UI, whether our JSON will
actually be recognized or whether the extension will fall back to its
generic byte-walk visualization.

The parsing port below mirrors:
  external/vscode-debug-visualizer/extension/src/VisualizationBackend/
    parseEvaluationResultFromGenericDebugAdapter.ts
Keep it in sync if that file changes upstream.

Writes debug_cpp.json / debug_rust.json into the output directory (default
~/lg, matching the style of the extension's own captured dumps): either the
resolved data object on success, or a {"PARSE_ERROR": ..., "raw": ...}
diagnostic on failure.

For the C++ build specifically, the breakpoint sits inside
`if (const int* top = list.peek_front())`, so `top` is a live local pointing
at the head node's `data` field (the node's first member, so its address
equals the node's own address, but its *static type* is just `const int*` --
gdb has no way to know it's secretly interior to a `Node<int>`). VS Code's
"debugVisualizer.debugAdapterConfigurations" expressionTemplate wraps
whatever you type in the Watch box as $debug_graph(${expr}), so typing
plain `top` evaluates $debug_graph(top) -- not $debug_graph(list, ...): we
replay that exact call and verify it still delves into the full list. This
relies on gdb/debug_graph.py's auto-discovery of sibling locals (here,
`list`, a struct type it *can* walk) merging into the same node graph as
`top`'s address, rather than requiring `top` to be passed as an explicit
watched root.
"""
import json
import re
import subprocess
import sys
from pathlib import Path

REPO = Path(__file__).resolve().parent.parent


def run_gdb(gdb_bin, binary, break_file, break_line, expr="$debug_graph(list)"):
    commands = [
        "-gdb-set print elements 0",
        "-gdb-set print characters 0",
        "source %s" % (REPO / "gdb" / "debug_graph.py"),
        "-break-insert %s:%d" % (break_file, break_line),
        "-exec-run",
        '-data-evaluate-expression "%s"' % expr.replace('"', '\\"'),
    ]
    proc = subprocess.run(
        [gdb_bin, "--interpreter=mi", binary],
        input="\n".join(commands).encode(),
        stdout=subprocess.PIPE,
        stderr=subprocess.STDOUT,
        timeout=15,
        cwd=str(REPO),
    )
    out = proc.stdout.decode(errors="replace")
    matches = re.findall(r'\^done,value="(.*)"\s*$', out, re.M)
    errors = re.findall(r'\^error,msg="(.*)"\s*$', out, re.M)
    if not matches:
        raise RuntimeError("no ^done,value=... in gdb output; errors=%r\n---\n%s" % (errors, out))
    return matches[-1]


def is_enclosed_with(s, ch):
    return s.startswith(ch) and s.endswith(ch) and len(s) >= 2


def parse_like_extension(mi_escaped_value):
    """Port of parseEvaluationResultFromGenericDebugAdapter, applied to the
    raw MI `value="..."` payload (itself one layer of MI's own
    string-escaping around whatever gdb's evaluate actually reported)."""
    result_text = json.loads('"' + mi_escaped_value + '"')  # undo MI's escaping
    json_data = result_text.strip()

    try:
        try:
            if is_enclosed_with(json_data, '"') or is_enclosed_with(json_data, "'"):
                json_data2 = json_data[1:-1]
            else:
                json_data2 = json_data
            result_obj = json.loads(json_data2)
        except Exception:
            # "in case of C++": the whole thing is itself a JSON string
            # literal; unwrap it once, then parse *that* as JSON.
            s = json.loads(json_data)
            result_obj = json.loads(s)
        return {"ok": True, "data": result_obj}
    except Exception as e:
        return {"ok": False, "error": str(e), "raw": result_text}


def verify_top_delves_into_list(data):
    """Checks that evaluating bare `top` -- i.e. $debug_graph(top), exactly
    what VS Code's expressionTemplate produces for a Watch box containing
    just "top" -- still shows the whole 30/20/10 list rather than stopping
    at a lone scalar leaf. Returns True/False and prints why."""
    nodes = data.get("nodes", [])
    edges = data.get("edges", [])
    roots_by_name = {r.get("name"): r for r in data.get("roots", [])}

    # Other auto-discovered locals (e.g. a `char*` local) can legitimately
    # produce their own bare scalar-leaf nodes -- only care whether *some*
    # node looks like a real Node<int> (data+next), i.e. top's address got
    # upgraded into the full struct rather than stopping at a lone int.
    node_shaped = [
        n for n in nodes
        if [f.get("name") for f in n.get("fields", [])] == ["data", "next"]
    ]
    if not node_shaped:
        print("  VERIFY FAIL: $debug_graph(top) produced no data+next Node-shaped node -- "
              "top's address was never upgraded to the full Node it coincides with "
              "(nodes=%r)" % [n.get("id") for n in nodes])
        return False

    next_edges = [e for e in edges if e.get("label") == "next"]
    if len(next_edges) < 2:
        print("  VERIFY FAIL: expected 2 'next' edges chaining the 30/20/10 nodes, found %d "
              "(edges=%r)" % (len(next_edges), edges))
        return False

    if "list" not in roots_by_name:
        print("  VERIFY FAIL: 'list' was not auto-discovered as a sibling local alongside "
              "top (roots=%r)" % data.get("roots"))
        return False

    print("  VERIFY OK: $debug_graph(top) delves into the full list -- %d nodes, %d 'next' "
          "edges, 'list' auto-discovered as a %r root"
          % (len(nodes), len(next_edges), roots_by_name["list"].get("kind")))
    return True


def dump(label, gdb_bin, binary, break_file, break_line, out_dir, expr="$debug_graph(list)", verify=None):
    ok = True
    try:
        raw_value = run_gdb(gdb_bin, binary, break_file, break_line, expr)
    except Exception as e:
        result = {"PARSE_ERROR": "gdb invocation failed", "detail": str(e)}
        ok = False
    else:
        parsed = parse_like_extension(raw_value)
        if parsed["ok"]:
            result = parsed["data"]
            if verify is not None:
                ok = verify(result)
        else:
            result = {
                "PARSE_ERROR": parsed["error"],
                "raw": parsed["raw"],
                "note": "This is what the Debug Visualizer extension would fail to parse, "
                "triggering its generic byte-walk fallback (constructGraphFromVariablesReference).",
            }
            ok = False

    out_path = out_dir / ("debug_%s.json" % label)
    out_path.write_text(json.dumps(result, indent=4))
    print("Wrote %s (%s)" % (out_path, "OK" if "PARSE_ERROR" not in result else "PARSE_ERROR"))
    return ok


def main():
    out_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.home() / "lg"
    out_dir.mkdir(parents=True, exist_ok=True)

    ok_cpp = dump("cpp", "gdb", str(REPO / "cpp" / "list_example_cpp"), "cpp/main.cpp", 70, out_dir)
    ok_cpp_top = dump(
        "cpp_top", "gdb", str(REPO / "cpp" / "list_example_cpp"), "cpp/main.cpp", 70, out_dir,
        expr="$debug_graph(top)",
        verify=verify_top_delves_into_list,
    )
    ok_rust = dump("rust", "rust-gdb", str(REPO / "target" / "debug" / "list_example"), "src/main.rs", 51, out_dir)

    if not (ok_cpp and ok_cpp_top and ok_rust):
        sys.exit(1)


if __name__ == "__main__":
    main()