Skip to content

Commit

Permalink
feat: puya debugging support (#2)
Browse files Browse the repository at this point in the history
* 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]>
  • Loading branch information
3 people committed Oct 25, 2024
1 parent c0a80eb commit 8714889
Show file tree
Hide file tree
Showing 22 changed files with 10,603 additions and 511 deletions.
4 changes: 4 additions & 0 deletions .mocharc.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
// .mocharc.js
module.exports = {
timeout: 30000, // 30 seconds
};
3 changes: 2 additions & 1 deletion .vscode/launch.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
6 changes: 6 additions & 0 deletions extension/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,12 @@
"breakpoints": [
{
"language": "teal"
},
{
"language": "python"
},
{
"language": "typescript"
}
],
"debuggers": [
Expand Down
17 changes: 15 additions & 2 deletions extension/src/configuration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
Expand Down
51 changes: 36 additions & 15 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 4 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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": {
Expand Down
40 changes: 8 additions & 32 deletions sampleWorkspace/.vscode/launch.json
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
]
Expand Down
12 changes: 12 additions & 0 deletions sampleWorkspace/README.md
Original file line number Diff line number Diff line change
@@ -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).
8 changes: 8 additions & 0 deletions sampleWorkspace/puya/.algokit/sources/opup/approval.teal.map
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"version": 3,
"sources": [
"opup.teal"
],
"names": [],
"mappings": ";AACA"
}
2 changes: 2 additions & 0 deletions sampleWorkspace/puya/.algokit/sources/opup/opup.teal
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
#pragma version 6
int 1
Loading

0 comments on commit 8714889

Please sign in to comment.