refactor(gnovm): rename precompiler to transpiler, move to own package (#1681)

Part 1 of several _transpiler_ refactors I intend to perform.

This PR tackles one of the first pet peeves I have about the
`precompile` tool, which is that the name is not intuitive to what it
does.

Transpile is a name that not everyone likes. Ultimately, converting one
source code to another is also an act of "compilation"; in fact, the
TypeScript tool that converts it into JavaScript is called the
"TypeScript Compiler". The distinction between transpiler and compiler
is blurry; but I think it is useful to call what we have as a
_transpiler_ to outline that it is doing a "source-to-source"
translation, which I don't think a name like `compile` or `precompile`
could.

Additionally, this PR moves the source files for the transpiler into its
own package, gnovm/pkg/transpiler.

One question is to whether the "constants" of the precompiler, like
`GnoRealmPkgsPrefixBefore`, should deserve their own package or not.

Author: thehowl

.github/workflows/examples.yml

@@ -32,7 +32,7 @@ jobs:
         with:
           go-version: ${{ matrix.goversion }}
       - run: go install -v ./gnovm/cmd/gno
-      - run: go run ./gnovm/cmd/gno precompile --verbose --gobuild ./examples
+      - run: go run ./gnovm/cmd/gno transpile --verbose --gobuild ./examples
   test:
     strategy:
       fail-fast: false

PLAN.md

@@ -16,7 +16,7 @@ the Discord server.
 ### Gnolang
 
 * Get basic Go tests working _COMPLETE_
-* Implement minimal toolsuite (precompile, gnodev)
+* Implement minimal toolsuite (transpile, gnodev)
 * Tweak/enforce gas limitations
 * Implement flat-as-struct supported
 * Implement ownership/realm logic; phase 1: no cycles

docs/getting-started/local-setup.md

@@ -28,7 +28,7 @@ git clone https://github.com/gnolang/gno.git
 ## 2. Installing the `gno` development toolkit
 
 Next, we are going to build and install the `gno` development toolkit.
-`gno` provides ample functionality to the user, among which is running, precompiling, testing and building `.gno` files.
+`gno` provides ample functionality to the user, among which is running, transpiling, testing and building `.gno` files.
 
 To install the toolkit, navigate to the `gnovm` folder from the repository root, and run the `build` make directive:
 

docs/gno-tooling/cli/gno.md

@@ -19,7 +19,7 @@ gno {SUB_COMMAND}
 | Name         | Description                                |
 | ------------ | ------------------------------------------ |
 | `test`       | Tests a gno package.                       |
-| `precompile` | Precompiles a `.gno` file to a `.go` file. |
+| `transpile`  | Transpiles a `.gno` file to a `.go` file. |
 | `repl`       | Starts a GnoVM REPL.                       |
 
 ### `test`
@@ -32,9 +32,9 @@ gno {SUB_COMMAND}
 | `root-dir`   | String        | Clones location of github.com/gnolang/gno (gno tries to guess it). |
 | `run`        | String        | Test name filtering pattern.                                       |
 | `timeout`    | time.Duration | The maximum execution time in ns.                                  |
-| `precompile` | Boolean       | Precompiles a `.gno` file to a `.go` file before testing.          |
+| `transpile`  | Boolean       | Transpiles a `.gno` file to a `.go` file before testing.          |
 
-### `precompile`
+### `transpile`
 
 #### **Options**
 

docs/reference/go-gno-compatibility.md

@@ -303,7 +303,7 @@ Legend:
 | + go mod init     | gno mod init     | same behavior                                                         |
 | + go mod download | gno mod download | same behavior                                                         |
 | + go mod tidy     | gno mod tidy     | same behavior                                                         |
-|                   | gno precompile   |                                                                       |
+|                   | gno transpile    |                                                                       |
 | go work           |                  |                                                                       |
 |                   | gno repl         |                                                                       |
 | go run            | gno run          |                                                                       |

examples/Makefile

@@ -9,13 +9,13 @@ help:
 	@echo "Available make commands:"
 	@cat Makefile | grep '^[a-z][^:]*:' | cut -d: -f1 | sort | sed 's/^/  /'
 
-.PHONY: precompile
-precompile:
-	go run ../gnovm/cmd/gno precompile --verbose .
+.PHONY: transpile
+transpile:
+	go run ../gnovm/cmd/gno transpile --verbose .
 
 .PHONY: build
-build: precompile
-	go run ../gnovm/cmd/gno build --verbose .
+build:
+	go run ../gnovm/cmd/gno transpile --verbose --gobuild .
 
 .PHONY: test
 test:

gno.land/pkg/gnoclient/client_txs.go

@@ -2,7 +2,7 @@ package gnoclient
 
 import (
 	"github.com/gnolang/gno/gno.land/pkg/sdk/vm"
-	gno "github.com/gnolang/gno/gnovm/pkg/gnolang"
+	"github.com/gnolang/gno/gnovm/pkg/transpiler"
 	"github.com/gnolang/gno/tm2/pkg/amino"
 	ctypes "github.com/gnolang/gno/tm2/pkg/bft/rpc/core/types"
 	"github.com/gnolang/gno/tm2/pkg/crypto"
@@ -138,8 +138,8 @@ func (c *Client) Run(cfg BaseTxCfg, msgs ...MsgRun) (*ctypes.ResultBroadcastTxCo
 
 		caller := c.Signer.Info().GetAddress()
 
-		// Precompile and validate Gno syntax
-		if err = gno.PrecompileAndCheckMempkg(msg.Package); err != nil {
+		// Transpile and validate Gno syntax
+		if err = transpiler.TranspileAndCheckMempkg(msg.Package); err != nil {
 			return nil, err
 		}
 

gno.land/pkg/keyscli/addpkg.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/gnolang/gno/gno.land/pkg/sdk/vm"
 	gno "github.com/gnolang/gno/gnovm/pkg/gnolang"
+	"github.com/gnolang/gno/gnovm/pkg/transpiler"
 	"github.com/gnolang/gno/tm2/pkg/amino"
 	"github.com/gnolang/gno/tm2/pkg/commands"
 	"github.com/gnolang/gno/tm2/pkg/crypto/keys"
@@ -101,8 +102,8 @@ func execMakeAddPkg(cfg *MakeAddPkgCfg, args []string, io commands.IO) error {
 		panic(fmt.Sprintf("found an empty package %q", cfg.PkgPath))
 	}
 
-	// precompile and validate syntax
-	err = gno.PrecompileAndCheckMempkg(memPkg)
+	// transpile and validate syntax
+	err = transpiler.TranspileAndCheckMempkg(memPkg)
 	if err != nil {
 		panic(err)
 	}

gno.land/pkg/keyscli/run.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/gnolang/gno/gno.land/pkg/sdk/vm"
 	gno "github.com/gnolang/gno/gnovm/pkg/gnolang"
+	"github.com/gnolang/gno/gnovm/pkg/transpiler"
 	"github.com/gnolang/gno/tm2/pkg/amino"
 	"github.com/gnolang/gno/tm2/pkg/commands"
 	"github.com/gnolang/gno/tm2/pkg/crypto/keys"
@@ -108,8 +109,8 @@ func execMakeRun(cfg *MakeRunCfg, args []string, cmdio commands.IO) error {
 	if memPkg.IsEmpty() {
 		panic(fmt.Sprintf("found an empty package %q", memPkg.Path))
 	}
-	// precompile and validate syntax
-	err = gno.PrecompileAndCheckMempkg(memPkg)
+	// transpile and validate syntax
+	err = transpiler.TranspileAndCheckMempkg(memPkg)
 	if err != nil {
 		panic(err)
 	}

gnovm/cmd/gno/README.md

@@ -10,7 +10,7 @@
 
 * `gno run` - run a Gno file
 * `gno build` - build a gno package
-* `gno precompile` - precompile .gno to .go
+* `gno transpile` - transpile .gno to .go
 * `gno test` - test a gno package
 * `gno mod` - manages dependencies
 * `gno repl` start a GnoVM REPL

gnovm/cmd/gno/lint_test.go

@@ -31,7 +31,7 @@ func TestLintApp(t *testing.T) {
 		// TODO: is gno source valid?
 		// TODO: are dependencies valid?
 		// TODO: is gno source using unsafe/discouraged features?
-		// TODO: consider making `gno precompile; go lint *gen.go`
+		// TODO: consider making `gno transpile; go lint *gen.go`
 		// TODO: check for imports of native libs from non _test.gno files
 	}
 	testMainCaseRun(t, tc)

gnovm/cmd/gno/main.go

@@ -28,7 +28,7 @@ func newGnocliCmd(io commands.IO) *commands.Command {
 		newTestCmd(io),
 		newLintCmd(io),
 		newRunCmd(io),
-		newPrecompileCmd(io),
+		newTranspileCmd(io),
 		newCleanCmd(io),
 		newReplCmd(),
 		newDocCmd(io),

gnovm/cmd/gno/test.go

@@ -20,6 +20,7 @@ import (
 	"github.com/gnolang/gno/gnovm/pkg/gnoenv"
 	gno "github.com/gnolang/gno/gnovm/pkg/gnolang"
 	"github.com/gnolang/gno/gnovm/pkg/gnomod"
+	"github.com/gnolang/gno/gnovm/pkg/transpiler"
 	"github.com/gnolang/gno/gnovm/tests"
 	"github.com/gnolang/gno/tm2/pkg/commands"
 	"github.com/gnolang/gno/tm2/pkg/errors"
@@ -33,7 +34,7 @@ type testCfg struct {
 	rootDir             string
 	run                 string
 	timeout             time.Duration
-	precompile          bool // TODO: precompile should be the default, but it needs to automatically precompile dependencies in memory.
+	transpile           bool // TODO: transpile should be the default, but it needs to automatically transpile dependencies in memory.
 	updateGoldenTests   bool
 	printRuntimeMetrics bool
 	withNativeFallback  bool
@@ -110,10 +111,10 @@ func (c *testCfg) RegisterFlags(fs *flag.FlagSet) {
 	)
 
 	fs.BoolVar(
-		&c.precompile,
-		"precompile",
+		&c.transpile,
+		"transpile",
 		false,
-		"precompile gno to go before testing",
+		"transpile gno to go before testing",
 	)
 
 	fs.BoolVar(
@@ -166,15 +167,15 @@ func execTest(cfg *testCfg, args []string, io commands.IO) error {
 
 	verbose := cfg.verbose
 
-	tempdirRoot, err := os.MkdirTemp("", "gno-precompile")
+	tempdirRoot, err := os.MkdirTemp("", "gno-transpile")
 	if err != nil {
 		log.Fatal(err)
 	}
 	defer os.RemoveAll(tempdirRoot)
 
 	// go.mod
 	modPath := filepath.Join(tempdirRoot, "go.mod")
-	err = makeTestGoMod(modPath, gno.ImportPrefix, "1.21")
+	err = makeTestGoMod(modPath, transpiler.ImportPrefix, "1.21")
 	if err != nil {
 		return fmt.Errorf("write .mod file: %w", err)
 	}
@@ -208,14 +209,14 @@ func execTest(cfg *testCfg, args []string, io commands.IO) error {
 	buildErrCount := 0
 	testErrCount := 0
 	for _, pkg := range subPkgs {
-		if cfg.precompile {
+		if cfg.transpile {
 			if verbose {
 				io.ErrPrintfln("=== PREC  %s", pkg.Dir)
 			}
-			precompileOpts := newPrecompileOptions(&precompileCfg{
+			transpileOpts := newTranspileOptions(&transpileCfg{
 				output: tempdirRoot,
 			})
-			err := precompilePkg(importPath(pkg.Dir), precompileOpts)
+			err := transpilePkg(importPath(pkg.Dir), transpileOpts)
 			if err != nil {
 				io.ErrPrintln(err)
 				io.ErrPrintln("FAIL")
@@ -233,7 +234,7 @@ func execTest(cfg *testCfg, args []string, io commands.IO) error {
 			if err != nil {
 				return errors.New("cannot resolve build dir")
 			}
-			err = goBuildFileOrPkg(tempDir, defaultPrecompileCfg)
+			err = goBuildFileOrPkg(tempDir, defaultTranspileCfg)
 			if err != nil {
 				io.ErrPrintln(err)
 				io.ErrPrintln("FAIL")
@@ -317,7 +318,7 @@ func gnoTestPkg(
 			gnoPkgPath = pkgPathFromRootDir(pkgPath, rootDir)
 			if gnoPkgPath == "" {
 				// unable to read pkgPath from gno.mod, generate a random realm path
-				gnoPkgPath = gno.GnoRealmPkgsPrefixBefore + random.RandStr(8)
+				gnoPkgPath = transpiler.GnoRealmPkgsPrefixBefore + random.RandStr(8)
 			}
 		}
 		memPkg := gno.ReadMemPackage(pkgPath, gnoPkgPath)

gnovm/cmd/gno/testdata/gno_precompile/01_no_args.txtar

@@ -5,7 +5,7 @@ gno test .
 ! stdout .+
 stderr '\?       \. 	\[no test files\]'
 
-! gno test --precompile .
+! gno test --transpile .
 
 ! stdout .+
 stderr 'expected ''package'', found ''EOF'''

gnovm/cmd/gno/testdata/gno_precompile/02_empty_dir.txtar

@@ -5,7 +5,7 @@
 ! stdout .+
 stderr 'expected ''package'', found ''EOF'''
 
-! gno test --precompile .
+! gno test --transpile .
 
 ! stdout .+
 stderr 'expected ''package'', found ''EOF'''

gnovm/cmd/gno/testdata/gno_test/empty_gno1.txtar

@@ -5,7 +5,7 @@
 ! stdout .+
 stderr 'expected ''package'', found ''EOF'''
 
-! gno test --precompile .
+! gno test --transpile .
 
 ! stdout .+
 stderr 'expected ''package'', found ''EOF'''

gnovm/cmd/gno/testdata/gno_test/empty_gno2.txtar

@@ -6,7 +6,7 @@ stdout 'Machine.RunMain\(\) panic: beep boop'
 stderr '=== RUN   file/failing_filetest.gno'
 stderr 'panic: fail on failing_filetest.gno: got unexpected error: beep boop'
 
-! gno test -verbose --precompile .
+! gno test -verbose --transpile .
 
 stdout 'Machine.RunMain\(\) panic: beep boop'
 stderr '=== PREC  \.'

gnovm/cmd/gno/testdata/gno_test/empty_gno3.txtar

@@ -7,7 +7,7 @@ stderr '=== RUN   TestAlwaysFailing'
 stderr '--- FAIL: TestAlwaysFailing'
 stderr 'FAIL: 0 build errors, 1 test errors'
 
-! gno test -verbose --precompile .
+! gno test -verbose --transpile .
 
 ! stdout .+
 stderr '=== RUN   TestAlwaysFailing'

gnovm/cmd/gno/testdata/gno_test/failing_filetest.txtar

@@ -0,0 +1,6 @@
+# Run gno transpile without args
+
+! gno transpile
+
+! stdout .+
+stderr 'USAGE'

gnovm/cmd/gno/testdata/gno_test/failing_test.txtar

@@ -0,0 +1,6 @@
+# Run gno transpile on an empty dir
+
+gno transpile .
+
+! stdout .+
+! stderr .+

gnovm/cmd/gno/testdata/gno_transpile/01_no_args.txtar

@@ -1,12 +1,12 @@
-# Run gno precompile with gno files with parse errors
+# Run gno transpile with gno files with parse errors
 
-! gno precompile .
+! gno transpile .
 
 ! stdout .+
 stderr '^main.gno:3:1: expected declaration, found invalid$'
 stderr '^main.gno:7:2: expected declaration, found wrong$'
 stderr '^sub/sub.gno:3:1: expected declaration, found invalid$'
-stderr '^3 precompile error\(s\)$'
+stderr '^3 transpile error\(s\)$'
 
 # no *.gen.go files are created
 ! exec test -f main.gno.gen.go

gnovm/cmd/gno/testdata/gno_transpile/02_empty_dir.txtar

@@ -1,6 +1,6 @@
-# Run gno precompile with valid gno files
+# Run gno transpile with valid gno files
 
-gno precompile .
+gno transpile .
 
 ! stdout .+
 ! stderr .+

gnovm/cmd/gno/testdata/gno_precompile/03_gno_files_parse_error.txtar gnovm/cmd/gno/testdata/gno_transpile/03_gno_files_parse_error.txtar

@@ -1,8 +1,8 @@
-# Run gno precompile with -skip-fmt flag
+# Run gno transpile with -skip-fmt flag
 # NOTE(tb): this flag doesn't actually prevent the code format, because
-# `gnolang.Precompile()` calls `format.Node()`.
+# `gnolang.Transpile()` calls `format.Node()`.
 
-gno precompile -skip-fmt .
+gno transpile -skip-fmt .
 
 ! stdout .+
 ! stderr .+

gnovm/cmd/gno/testdata/gno_precompile/04_valid_gno_files.txtar gnovm/cmd/gno/testdata/gno_transpile/04_valid_gno_files.txtar

@@ -1,6 +1,6 @@
-# Run gno precompile with -gobuild flag
+# Run gno transpile with -gobuild flag
 
-gno precompile -gobuild .
+gno transpile -gobuild .
 
 ! stdout .+
 ! stderr .+

gnovm/cmd/gno/testdata/gno_precompile/05_skip_fmt_flag.txtar gnovm/cmd/gno/testdata/gno_transpile/05_skip_fmt_flag.txtar

@@ -1,11 +1,11 @@
-# Run gno precompile with -gobuild flag
+# Run gno transpile with -gobuild flag
 
-! gno precompile -gobuild .
+! gno transpile -gobuild .
 
 ! stdout .+
 stderr '^main.gno:4:6: x declared and not used$'
 stderr '^main.gno:5:6: y declared and not used$'
-stderr '^2 precompile error\(s\)$'
+stderr '^2 transpile error\(s\)$'
 
 cmp main.gno.gen.go main.gno.gen.go.golden
 cmp sub/sub.gno.gen.go sub/sub.gno.gen.go.golden

gnovm/cmd/gno/testdata/gno_precompile/06_build_flag.txtar gnovm/cmd/gno/testdata/gno_transpile/06_build_flag.txtar

@@ -1,6 +1,6 @@
-# Run gno precompile with -gobuild flag on file with parse error
+# Run gno transpile with -gobuild flag on file with parse error
 
-! gno precompile -gobuild .
+! gno transpile -gobuild .
 
 ! stdout .+
 stderr '^main.gno:3:1: expected declaration, found invalid$'