feat: puya debugging support (#2)

* chore: adding option to treat null under sourcemap-locations as valid 'ignore' cases * chore: npm audit * chore: adding npm prepare script for installation via github * feat: add puya debug support (WIP) * chore: support for passing file contents for sourcemaps; puya/teal edge cases (#1) * chore: hiding locals on non puya sourcemaps; adding puya and teal example * chore: no tmpl vars offset edge case fix * chore: rel path for example on puya + teal * chore: workaround on skipping syntentic refs that does not require async file exists * feat: support direct file or encoded content for sourcemaps * refactor: make programSourcesDescription an object instead of JSON * chore: adding more edge cases * chore(src/common): Add program source entry file and type Added 'ProgramSourceEntryFile' and 'ProgramSourceEntry' to the common module. These types are used for parsing program source files. * chore: add support for 'null' sourcemap paths when user prefers ignores * chore: add mocharc file for global timeouts Also fixing a few tests * fix: move program forward call after inner transaction processing * chore: further refine puya example with third parties * feat: integrating Locals with existing expand avm methods * chore: adding puya unit test; moving process unit into program replay --------- Co-authored-by: Daniel McGregor <[email protected]> * fix: step backwards on puya sourcemaps * refactor: use different interface for CallStackFrame vs TraceReplayFrame capture lastIndex for when needing to walk backward in a program remove _ expandedAvmValueCache and instead handle the 'named' and 'indexed' filters correctly * feat: support evaluation of Puya variables * chore: reduce diff * chore: bumping to algosdkv3; adding puya-ts example; extra unit test; * fix: backwards compatibility with SimulateResponse encoded via algosdkv2 * fix: update unit tests to match latest examples * fix: hiding locals on non puya frontend sourcemap paths * chore: transferring advanced examples to extension repo * chore: apply suggestions from code review Co-authored-by: Neil Campbell <[email protected]> --------- Co-authored-by: Daniel McGregor <[email protected]> Co-authored-by: Neil Campbell <[email protected]>
algorandfoundation · Oct 14, 2024 · d5f7e60 · d5f7e60
1 parent c0a80eb
commit d5f7e60
Show file tree

Hide file tree

Showing 22 changed files with 10,619 additions and 511 deletions.
diff --git a/.mocharc.js b/.mocharc.js
@@ -0,0 +1,4 @@
+// .mocharc.js
+module.exports = {
+  timeout: 30000, // 30 seconds
+};
diff --git a/.vscode/launch.json b/.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",

diff --git a/extension/package.json b/extension/package.json
@@ -56,6 +56,12 @@
     "breakpoints": [
       {
         "language": "teal"
+      },
+      {
+        "language": "python"
+      },
+      {
+        "language": "typescript"
       }
     ],
     "debuggers": [

diff --git a/extension/src/configuration.ts b/extension/src/configuration.ts
@@ -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;
     }

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/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,11 +64,12 @@
     "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",
-    "algosdk": "^3.0.0-beta.1",
+    "algosdk": "^3.0.0",
     "await-notify": "^1.0.1"
   },
   "devDependencies": {

diff --git a/sampleWorkspace/.vscode/launch.json b/sampleWorkspace/.vscode/launch.json
@@ -8,160 +8,136 @@
       "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
     }
   ]

diff --git a/sampleWorkspace/README.md b/sampleWorkspace/README.md
@@ -0,0 +1,12 @@
+## 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`). Showcasing various ways to simulate traces with puya sourcemaps and sources.
+
+> **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).