feat: puya debugging support

.mocharc.js

@@ -0,0 +1,4 @@
+// .mocharc.js
+module.exports = {
+  timeout: 30000, // 30 seconds
+};

.vscode/launch.json

@@ -6,11 +6,12 @@
       "type": "extensionHost",
       "request": "launch",
       "args": [
+        "--disable-extensions",
         "--extensionDevelopmentPath=${workspaceFolder}/extension",
         "${workspaceFolder}/sampleWorkspace"
       ],
       "outFiles": ["${workspaceFolder}/extension/dist/**/*.js"],
-      "preLaunchTask": "npm: extension watch"
+      "preLaunchTask": "npm: extension:build"
     },
     {
       "name": "Server",

extension/package.json

@@ -56,6 +56,9 @@
     "breakpoints": [
       {
         "language": "teal"
+      },
+      {
+        "language": "python"
       }
     ],
     "debuggers": [

extension/src/configuration.ts

@@ -10,7 +10,7 @@ export class AvmDebugConfigProvider
   implements vscode.DebugConfigurationProvider
 {
   /**
-   * Massage a debug configuration just before a debug session is being launched,
+   * Message a debug configuration just before a debug session is being launched,
    * e.g. add all missing attributes to the debug configuration.
    */
   resolveDebugConfiguration(
@@ -26,9 +26,22 @@ export class AvmDebugConfigProvider
       return null;
     }
 
-    if (!config.programSourcesDescriptionFile) {
+    if (
+      config.programSourcesDescription &&
+      !config.programSourcesDescriptionFolder
+    ) {
       vscode.window.showErrorMessage(
-        'Missing property "programSourcesDescriptionFile" in debug config',
+        'Missing property "programSourcesDescriptionFolder" in debug config',
+      );
+      return null;
+    }
+
+    if (
+      !config.programSourcesDescriptionFile &&
+      !config.programSourcesDescription
+    ) {
+      vscode.window.showErrorMessage(
+        'Either "programSourcesDescriptionFile" or "programSourcesDescription" + "programSourcesDescriptionFolder" must be provided in debug config',
       );
       return null;
     }

package.json

@@ -49,6 +49,7 @@
     "src"
   ],
   "scripts": {
+    "prepare": "npm run compile",
     "compile": "shx rm -rf out && tsc -p ./",
     "lint": "eslint src --ext ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -63,7 +64,8 @@
     "extension:publish": "vsce publish",
     "extension:publish-pre-release": "vsce publish --pre-release",
     "test": "ts-mocha -p tsconfig.json 'tests/**/*test.ts' --timeout 30s --diff false",
-    "test:coverage": "nyc npm run test"
+    "test:coverage": "nyc npm run test",
+    "pre-commit": "npm run lint && npm run typecheck && npm run format"
   },
   "dependencies": {
     "@vscode/debugadapter": "^1.64.0",

sampleWorkspace/.vscode/launch.json

@@ -8,160 +8,180 @@
       "type": "avm",
       "request": "launch",
       "name": "Debug App Box State Changes",
-
       "simulateTraceFile": "${workspaceFolder}/app-state-changes/box-simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/app-state-changes/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug App Global State Changes",
-
       "simulateTraceFile": "${workspaceFolder}/app-state-changes/global-simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/app-state-changes/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug App Local State Changes",
-
       "simulateTraceFile": "${workspaceFolder}/app-state-changes/local-simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/app-state-changes/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug Recursive App",
-
       "simulateTraceFile": "${workspaceFolder}/recursive-app/simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/recursive-app/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug Slot Machine",
-
       "simulateTraceFile": "${workspaceFolder}/slot-machine/simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/slot-machine/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug Sourcemap Test",
-
       "simulateTraceFile": "${workspaceFolder}/sourcemap-test/simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/sourcemap-test/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug Stack Scratch",
-
       "simulateTraceFile": "${workspaceFolder}/stack-scratch/simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/stack-scratch/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug Stepping Test",
-
       "simulateTraceFile": "${workspaceFolder}/stepping-test/simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/stepping-test/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug App Error",
-
       "simulateTraceFile": "${workspaceFolder}/errors/app/simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/errors/app/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug App from LogicSig Error",
-
       "simulateTraceFile": "${workspaceFolder}/errors/app-from-logicsig/simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/errors/app-from-logicsig/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug Inner App Error (App Reject)",
-
       "simulateTraceFile": "${workspaceFolder}/errors/inner-app/app-reject-simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/errors/inner-app/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug Inner App Error (Overspend)",
-
       "simulateTraceFile": "${workspaceFolder}/errors/inner-app/overspend-simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/errors/inner-app/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug LogicSig Error",
-
       "simulateTraceFile": "${workspaceFolder}/errors/logicsig/simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/errors/logicsig/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Debug Error Before LogicSig",
-
       "simulateTraceFile": "${workspaceFolder}/errors/logicsig-after-error/simulate-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/errors/logicsig-after-error/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Clear State Rejection",
-
       "simulateTraceFile": "${workspaceFolder}/errors/clear-state/rejection-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/errors/clear-state/sources.json",
-
       "stopOnEntry": true
     },
     {
       "type": "avm",
       "request": "launch",
       "name": "Clear State Error",
-
       "simulateTraceFile": "${workspaceFolder}/errors/clear-state/error-response.json",
       "programSourcesDescriptionFile": "${workspaceFolder}/errors/clear-state/sources.json",
-
+      "stopOnEntry": true
+    },
+    {
+      "type": "avm",
+      "request": "launch",
+      "name": "Debug Puya",
+      "simulateTraceFile": "${workspaceFolder}/puya/simulate-response.json",
+      "programSourcesDescriptionFile": "${workspaceFolder}/puya/sources.json",
+      "stopOnEntry": true
+    },
+    {
+      "type": "avm",
+      "request": "launch",
+      "name": "Debug Puya & Teal",
+      "simulateTraceFile": "${workspaceFolder}/puya_and_teal/simulate-response.json",
+      "programSourcesDescription": {
+        "txn-group-sources": [
+          {
+            "sourcemap-location": "first_app/approval.teal.tok.map",
+            "hash": "+M4WXURFSOFzatfICt2miBHDfm5qylmm279/3bZtKjI="
+          },
+          {
+            "sourcemap-location": "second_app/contract_approval.puya.map",
+            "hash": "Vg0dtzIh0CIFZN/+hJG/L+6gSSPPyjuzE0wDqGt0zyU="
+          },
+          {
+            "sourcemap-location": "delegated_lsig/lsig.puya.map",
+            "hash": "8Y7ddIVDDdijOZcTKzMOxqa3RpJOjUGswRdND/Hdddg="
+          }
+        ]
+      },
+      "programSourcesDescriptionFolder": "${workspaceFolder}/puya_and_teal/",
+      "stopOnEntry": true
+    },
+    {
+      "type": "avm",
+      "request": "launch",
+      "name": "Debug Puya with Third Party export",
+      "simulateTraceFile": "${workspaceFolder}/puya_third_parties/simulate-response.json",
+      "programSourcesDescription": {
+        "txn-group-sources": [
+          {
+            "sourcemap-location": "RSATester.approval.puya.map",
+            "hash": "sHHTmOJCdECH2FtRp7ukCKBX/bhw3MhiwEVLw5lakig="
+          },
+          {
+            "sourcemap-location": ".algokit/sources/opup/approval.teal.map",
+            "hash": "p0zHRDBy7V/S2TDcAaXYEd2OF8KSxV/1y0ceYEL6qxU="
+          }
+        ]
+      },
+      "programSourcesDescriptionFolder": "${workspaceFolder}/puya_third_parties/",
       "stopOnEntry": true
     }
   ]

sampleWorkspace/README.md

@@ -0,0 +1,13 @@
+## How to navigate examples?
+
+This folder contains sample workspaces representing various debugger use cases:
+
+- Simulate traces, TEAL sources and sourcemaps (e.g. `stack-scratch`, `stepping-test`, `app-state-changes`, `errors`). Various examples of using the debugger with TEAL sourcemaps and sources.
+- Simulate traces, [Puya](https://github.com/algorandfoundation/puya) sources and sourcemaps (e.g. `puya`, `puya_third_parties`). Showcasing various ways to simulate traces with puya sourcemaps and sources.
+- Simulate traces, TEAL sources & sourcemaps and Puya sources & sourcemaps (e.g. `puya_and_teal`). Showcasing the ability to mix and match TEAL and Puya frontend languages within the same debug session.
+
+> **Note:** The frontend language for Puya compiler scenarios is [Algorand Python](https://pypi.org/project/algorand-python/).
+
+### Launching sample workspaces
+
+Refer to the [launch.json](.vscode/launch.json) file to launch sample workspaces from VSCode. Keep the marketplace-based AlgoKit AVM Debugger extension disabled (if installed).