Goal: Source mapping PC to TEAL

cmd/goal/clerk.go

@@ -18,6 +18,7 @@ package main
 
 import (
 	"encoding/base64"
+	"encoding/json"
 	"fmt"
 	"io"
 	"os"
@@ -49,6 +50,7 @@ var (
 	rejectsFilename string
 	closeToAddress  string
 	noProgramOutput bool
+	writeSourceMap  bool
 	signProgram     bool
 	programSource   string
 	argB64Strings   []string
@@ -123,6 +125,7 @@ func init() {
 
 	compileCmd.Flags().BoolVarP(&disassemble, "disassemble", "D", false, "disassemble a compiled program")
 	compileCmd.Flags().BoolVarP(&noProgramOutput, "no-out", "n", false, "don't write contract program binary")
+	compileCmd.Flags().BoolVarP(&writeSourceMap, "map", "m", false, "write out assembly map")
 	compileCmd.Flags().BoolVarP(&signProgram, "sign", "s", false, "sign program, output is a binary signed LogicSig record")
 	compileCmd.Flags().StringVarP(&outFilename, "outfile", "o", "", "Filename to write program bytes or signed LogicSig to")
 	compileCmd.Flags().StringVarP(&account, "account", "a", "", "Account address to sign the program (If not specified, uses default account)")
@@ -927,7 +930,7 @@ func mustReadFile(fname string) []byte {
 	return contents
 }
 
-func assembleFile(fname string) (program []byte) {
+func assembleFileImpl(fname string) *logic.OpStream {
 	text, err := readFile(fname)
 	if err != nil {
 		reportErrorf("%s: %s", fname, err)
@@ -948,9 +951,19 @@ func assembleFile(fname string) (program []byte) {
 		}
 	}
 
+	return ops
+}
+
+func assembleFile(fname string) []byte {
+	ops := assembleFileImpl(fname)
 	return ops.Program
 }
 
+func assembleFileWithMap(fname string) ([]byte, logic.SourceMap) {
+	ops := assembleFileImpl(fname)
+	return ops.Program, logic.GetSourceMap([]string{fname}, ops.OffsetToLine)
+}
+
 func disassembleFile(fname, outname string) {
 	program, err := readFile(fname)
 	if err != nil {
@@ -997,7 +1010,7 @@ var compileCmd = &cobra.Command{
 				disassembleFile(fname, outFilename)
 				continue
 			}
-			program := assembleFile(fname)
+			program, sourceMap := assembleFileWithMap(fname)
 			outblob := program
 			outname := outFilename
 			if outname == "" {
@@ -1036,6 +1049,17 @@ var compileCmd = &cobra.Command{
 					reportErrorf("%s: %s", outname, err)
 				}
 			}
+			if writeSourceMap {
+				mapname := fname + ".map"
+				pcblob, err := json.Marshal(sourceMap)
+				if err != nil {
+					reportErrorf("%s: %s", mapname, err)
+				}
+				err = writeFile(mapname, pcblob, 0666)
+				if err != nil {
+					reportErrorf("%s: %s", mapname, err)
+				}
+			}
 			if !signProgram && outname != stdoutFilenameValue {
 				pd := logic.HashProgram(program)
 				addr := basics.Address(pd)

data/transactions/logic/assembler.go

@@ -267,7 +267,7 @@ func (ops *OpStream) RecordSourceLine() {
 	ops.OffsetToLine[ops.pending.Len()] = ops.sourceLine - 1
 }
 
-// ReferToLabel records an opcode label refence to resolve later
+// ReferToLabel records an opcode label reference to resolve later
 func (ops *OpStream) ReferToLabel(pc int, label string) {
 	ops.labelReferences = append(ops.labelReferences, labelReference{ops.sourceLine, pc, label})
 }

data/transactions/logic/sourcemap.go

@@ -0,0 +1,94 @@
+// Copyright (C) 2019-2022 Algorand, Inc.
+// This file is part of go-algorand
+//
+// go-algorand is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// go-algorand is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with go-algorand.  If not, see <https://www.gnu.org/licenses/>.
+
+package logic
+
+import (
+	"bytes"
+	"strings"
+)
+
+// sourceMapVersion is currently 3: https://sourcemaps.info/spec.html
+const sourceMapVersion = 3
+const b64table string = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+// SourceMap contains details from the source to assembly process
+// currently contains map of TEAL source line to assembled bytecode position
+// and details about the template variables contained in the source file
+type SourceMap struct {
+	Version    int      `json:"version"`
+	File       string   `json:"file"`
+	SourceRoot string   `json:"sourceRoot"`
+	Sources    []string `json:"sources"`
+	Names      []string `json:"names"`
+	Mapping    string   `json:"mapping"`
+}
+
+// GetSourceMap returns a struct containing details about
+// the assembled file and encoded mappings to the source file.
+func GetSourceMap(sourceNames []string, offsetToLine map[int]int) SourceMap {
+	maxPC := 0
+	for pc := range offsetToLine {
+		if pc > maxPC {
+			maxPC = pc
+		}
+	}
+
+	// Array where index is the PC and value is the line.
+	pcToLine := make([]string, maxPC+1)
+	for pc := range pcToLine {
+		if line, ok := offsetToLine[pc]; ok {
+			pcToLine[pc] = MakeSourceMapLine(0, 0, line, 0)
+		} else {
+			pcToLine[pc] = ""
+		}
+	}
+
+	// Encode the source map into a string
+	encodedMapping := strings.Join(pcToLine, ";")
+
+	return SourceMap{
+		Version: sourceMapVersion,
+		File:    "", // Assembled file does not have a name.
+		Sources: sourceNames,
+		Names:   []string{}, // TEAL code does not generate any names.
+		Mapping: encodedMapping,
+	}
+}
+
+// IntToVLQ writes out value to bytes.Buffer
+func IntToVLQ(v int, buf *bytes.Buffer) {
+	v <<= 1
+	if v < 0 {
+		v = -v
+		v |= 1
+	}
+	for v >= 32 {
+		buf.WriteByte(b64table[32|(v&31)])
+		v >>= 5
+	}
+	buf.WriteByte(b64table[v])
+}
+
+// MakeSourceMapLine creates source map mapping's line entry
+func MakeSourceMapLine(tcol, sindex, sline, scol int) string {
+	buf := bytes.NewBuffer(nil)
+	IntToVLQ(tcol, buf)
+	IntToVLQ(sindex, buf)
+	IntToVLQ(sline, buf)
+	IntToVLQ(scol, buf)
+	return buf.String()
+}

data/transactions/logic/sourcemap_test.go

@@ -0,0 +1,63 @@
+// Copyright (C) 2019-2022 Algorand, Inc.
+// This file is part of go-algorand
+//
+// go-algorand is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// go-algorand is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with go-algorand.  If not, see <https://www.gnu.org/licenses/>.
+
+package logic
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/algorand/go-algorand/test/partitiontest"
+	"github.com/stretchr/testify/require"
+)
+
+func TestGetSourceMap(t *testing.T) {
+	partitiontest.PartitionTest(t)
+	a := require.New(t)
+
+	sourceNames := []string{"test.teal"}
+	offsetToLine := map[int]int{
+		1: 1,
+		2: 2,
+		3: 5,
+	}
+	actualSourceMap := GetSourceMap(sourceNames, offsetToLine)
+
+	a.Equal(sourceMapVersion, actualSourceMap.Version)
+	a.Equal("", actualSourceMap.File)
+	a.Equal(sourceNames, actualSourceMap.Sources)
+	a.Equal([]string{}, actualSourceMap.Names)
+
+	// Check encoding for each line.
+	splitMapping := strings.Split(actualSourceMap.Mapping, ";")
+	for pc := range splitMapping {
+		if line, ok := offsetToLine[pc]; ok {
+			a.Equal(MakeSourceMapLine(0, 0, line, 0), splitMapping[pc])
+		}
+	}
+}
+
+func TestVLQ(t *testing.T) {
+	partitiontest.PartitionTest(t)
+	a := require.New(t)
+
+	a.Equal("AAAA", MakeSourceMapLine(0, 0, 0, 0))
+	a.Equal("AACA", MakeSourceMapLine(0, 0, 1, 0))
+	a.Equal("AAEA", MakeSourceMapLine(0, 0, 2, 0))
+	a.Equal("AAgBA", MakeSourceMapLine(0, 0, 16, 0))
+	a.Equal("AAggBA", MakeSourceMapLine(0, 0, 512, 0))
+	a.Equal("ADggBD", MakeSourceMapLine(0, -1, 512, -1))
+}