Source mapping: PC->TEAL map

[algochoi]

Problem

Developers currently have trouble mapping PC values to TEAL. A common use case is trying to see which assert in a TEAL program failed from a particular PC. We would like to create a standardized format to show this mapping using the Javascript standard.

Solution

Create a subcommand/flag for the goal clerk compile command that will generate a JSON of the source map.

{
"version" : 3,
"file": "lines.dis",
"sourceRoot": "",
"sources": ["foo.teal", "bar.teal"],
"names": ["src", "maps", "are", "fun"],
"mappings": "AACA;AACA;AACA;;AACA"
}

The format of the JSON should match the Javascript standard noted above, but for this ticket, we should only really be concerned with the sources field and the mappings field. The mapping is done in base64 VLQ encoding, and there is an implementation in the tealdbg that converts integers to VLQ.

There is a PR by @barnjamin that does a lot of the heavy lifting for this proposed solution, and can be used to convert the output into the standard above.

It would also be nice if this was supported in the REST endpoint as well with an optional parameter, e.g. ?map=true, but this could be a subject of a later ticket. It would also be nice to tackle this issue as well, since there seems to be high community interest: #1654

Example

myprog.teal

#pragma version 5

int 3
byte 0x03
btoi
==
assert

int 10
byte 0x10
btoi
==
assert

myprog.teal.map.json

{
  "source_name":"myprog.teal",
  "mapping":";2;;3;;;4;5;6;8;;9;;;10;11;12"
}

The code used to generate this is in this PR branch: #3726

The source map is generated by passing the -m flag to goal clerk compile.

Example decoder here: https://github.com/algochoi/teal-sourcemap-decoder/tree/examples

#pragma version 5

int 3            // PC: 1
byte 0x03        // PC: 3
btoi             // PC: 6
==               // PC: 7
assert           // PC: 8

int 10           // PC: 9
byte 0x10        // PC: 11
btoi             // PC: 14
==               // PC: 15
assert           // PC: 16

Dependencies

None

Urgency

Medium

[michaeldiamant]

Reminder: Release requires updating docs to reflect new goal cli parameter as discussed in #3726 (comment).