feat(pmdb): add a gdb-like JS debugger for pmjs

Can be enabled by `pmjs --inspect`

Author: Xmader

python/pythonmonkey/cli/pmjs.py

@@ -6,6 +6,8 @@
 import sys, os, signal, getopt
 import readline
 import pythonmonkey as pm
+from pythonmonkey.lib.pmdb import pmdbEnable
+
 globalThis = pm.eval("globalThis")
 evalOpts = { 'filename': __file__, 'fromPythonFrame': True, 'strict': False } # type: pm.EvalOptions
 
@@ -287,6 +289,7 @@ def usage():
   -r, --require...     module to preload (option can be repeated)
   -v, --version        print PythonMonkey version
   --use-strict         evaluate -e, -p, and REPL code in strict mode
+  --inspect            enable pmdb, a gdb-like JavaScript debugger interface
   
 Environment variables:
 TZ                            specify the timezone configuration
@@ -320,7 +323,7 @@ def main():
     global requirePath
 
     try:
-        opts, args = getopt.getopt(sys.argv[1:], "hie:p:r:v", ["help", "eval=", "print=", "require=", "version", "use-strict"])
+        opts, args = getopt.getopt(sys.argv[1:], "hie:p:r:v", ["help", "eval=", "print=", "require=", "version", "use-strict", "inspect"])
     except getopt.GetoptError as err:
         # print help information and exit:
         print(err)  # will print something like "option -a not recognized"
@@ -347,6 +350,8 @@ def main():
             enterRepl = False
         elif o in ("-r", "--require"):
             globalThis.require(a)
+        elif o in ("--inspect"):
+            pmdbEnable(pm.eval("debuggerGlobal"))
         else:
             assert False, "unhandled option"
 

python/pythonmonkey/lib/pmdb.py

@@ -0,0 +1,109 @@
+# @file     pmdb - A gdb-like JavaScript debugger interface for pmjs
+#                  Enabled by `pmjs --inspect`
+# @author   Tom Tang <[email protected]>
+# @date     July 2023
+
+def debuggerInput(prompt: str):
+  try:
+    return input(prompt) # blocking
+  except KeyboardInterrupt:
+    print("\b\bQuit") # to match the behaviour of gdb 
+    return ""
+  except Exception as e:
+    print(e)
+    return ""
+
+def pmdbEnable(debuggerGlobalObject):
+  debuggerGlobalObject.eval("""(debuggerInput, _pythonPrint) => {
+  const dbg = new Debugger()
+  const mainDebuggee = dbg.addDebuggee(mainGlobal)
+  dbg.uncaughtExceptionHook = (e) => {
+    _pythonPrint(e)
+  }
+
+  function makeDebuggeeValue (val) {
+    if (val instanceof Debugger.Object) {
+      return dbg.adoptDebuggeeValue(val)
+    } else {
+      // See https://firefox-source-docs.mozilla.org/js/Debugger/Debugger.Object.html#makedebuggeevalue-value
+      return mainDebuggee.makeDebuggeeValue(val)
+    }
+  }
+
+  function print (...args) {
+    const logger = makeDebuggeeValue(mainGlobal.console.log)
+    logger.apply(logger, args.map(makeDebuggeeValue))
+  }
+  
+  function printErr (...args) {
+    const logger = makeDebuggeeValue(mainGlobal.console.error)
+    logger.apply(logger, args.map(makeDebuggeeValue))
+  }
+  
+  function getCommandInputs () {
+    const input = debuggerInput("(pmdb) > ") // blocking
+    const [_, command, rest] = input.match(/\\s*(\\w+)?(?:\\s+(.*))?/)
+    return { command, rest }
+  }
+
+  function enterDebuggerLoop (frame) {
+    const metadata = frame.script.getOffsetMetadata(frame.offset)
+    if (!metadata.isBreakpoint) {
+      // This bytecode offset does not qualify as a breakpoint, skipping
+      return
+    }
+    
+    blockingLoop: while (true) {
+      const { command, rest } = getCommandInputs() // blocking
+      switch (command) {
+        case "c":
+        case "cont":
+          // Continue execution until next breakpoint or `debugger` statement
+          frame.onStep = undefined // clear step next handler
+          break blockingLoop;
+        case "n":
+        case "next":
+          // Step next
+          frame.onStep = function () { enterDebuggerLoop(this) } // add handler
+          break blockingLoop;
+        case "bt":
+        case "backtrace":
+          // Print backtrace of current execution frame
+          // FIXME: we currently implement this using Error.stack
+          print(frame.eval("(new Error).stack.split('\\\\n').slice(1).join('\\\\n')").return)
+          continue blockingLoop;
+        case "l":
+        case "line": {
+          // Print current line
+          const src = frame.script.source.text
+          const line = src.split('\\n').slice(metadata.lineNumber-1, metadata.lineNumber).join('\\n')
+          print(line)
+          continue blockingLoop;
+        }
+        case "p":
+        case "exec":
+        case "print": {
+          // Execute an expression in debugging script's context and print its value
+          const result = frame.eval(rest)
+          if (result.throw) printErr(result.throw) // on error
+          else print(result.return) // on success
+          continue blockingLoop;
+        }
+        case "q":
+        case "quit":
+        case "kill":
+          // Force exit the program
+          mainGlobal.python.exit(127)
+          break blockingLoop;
+        case "":
+        case undefined:
+          // no-op
+          continue blockingLoop;
+        default:
+          print(`Undefined command: "${command}"`)
+      }
+    }
+  }
+
+  dbg.onDebuggerStatement = (frame) => enterDebuggerLoop(frame)
+  }""")(debuggerInput, print)