chore: reorganize gnovm/cmd/gno (#3587)

- Increase Go-Gno compatibility. - Sort alphabetically commands. - Move Gno-specific commands under `gno tool <command>`. - Improve `ShortHelp`. - Use `embedmd` in `gnovm/cmd/gno`'s README as an example of how we should use it more frequently. --------- Signed-off-by: moul <[email protected]>
gnolang · Jan 24, 2025 · f67f186 · f67f186
1 parent 98c4353
commit f67f186
Show file tree

Hide file tree

Showing 42 changed files with 181 additions and 117 deletions.
diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml
@@ -29,7 +29,7 @@ jobs:
         with:
           go-version: ${{ matrix.goversion }}
       - run: go install -v ./gnovm/cmd/gno
-      - run: go run ./gnovm/cmd/gno transpile -v --gobuild ./examples
+      - run: go run ./gnovm/cmd/gno tool transpile -v --gobuild ./examples
   test:
     strategy:
       fail-fast: false

diff --git a/.gitignore b/.gitignore
@@ -34,3 +34,6 @@ coverage.out
 *.swp
 *.swo
 *.bak
+
+.tmp/
+wal/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -198,7 +198,7 @@ Additionally, it's not possible to use `gofumpt` for code formatting with
 
 (flycheck-define-checker gno-lint
   "A GNO syntax checker using the gno lint tool."
-  :command ("gno" "lint" source-original)
+  :command ("gno" "tool" "lint" source-original)
   :error-patterns (;; ./file.gno:32: error message (code=1)
                    (error line-start (file-name) ":" line ": " (message) " (code=" (id (one-or-more digit)) ")." line-end))
   ;; Ensure the file is saved, to work around

diff --git a/docs/reference/go-gno-compatibility.md b/docs/reference/go-gno-compatibility.md
@@ -297,31 +297,31 @@ Legend:
 
 ## Tooling (`gno` binary)
 
-| go command        | gno command               | comment                                                               |
-|-------------------|---------------------------|-----------------------------------------------------------------------|
-| go bug            | gno bug                   | same behavior                                                         |
-| go build          | gno transpile -gobuild    | same intention, limited compatibility                                 |
-| go clean          | gno clean                 | same intention, limited compatibility                                 |
-| go doc            | gno doc                   | limited compatibility; see https://github.com/gnolang/gno/issues/522  |
-| go env            | gno env                   |                                                                       |
-| go fix            |                           |                                                                       |
-| go fmt            | gno fmt                   | gofmt (& similar tools, like gofumpt) works on gno code.              |
-| go generate       |                           |                                                                       |
-| go get            |                           | see `gno mod download`.                                               |
-| go help           | gno $cmd --help           | ie. `gno doc --help`                                                  |
-| go install        |                           |                                                                       |
-| go list           |                           |                                                                       |
-| go mod            | gno mod                   |                                                                       |
-| + go mod init     | gno mod init              | same behavior                                                         |
-| + go mod download | gno mod download          | same behavior                                                         |
-| + go mod tidy     | gno mod tidy              | same behavior                                                         |
-| + go mod why      | gno mod why               | same intention                                                        |
-|                   | gno transpile             |                                                                       |
-| go work           |                           |                                                                       |
-|                   | gno repl                  |                                                                       |
-| go run            | gno run                   |                                                                       |
-| go test           | gno test                  | limited compatibility                                                 |
-| go tool           |                           |                                                                       |
-| go version        |                           |                                                                       |
-| go vet            |                           |                                                                       |
-| golint            | gno lint                  | same intention                                                        |
+| go command        | gno command                  | comment                                                               |
+|-------------------|------------------------------|-----------------------------------------------------------------------|
+| go bug            | gno bug                      | same behavior                                                         |
+| go build          | gno tool transpile -gobuild  | same intention, limited compatibility                                 |
+| go clean          | gno clean                    | same intention, limited compatibility                                 |
+| go doc            | gno doc                      | limited compatibility; see https://github.com/gnolang/gno/issues/522  |
+| go env            | gno env                      |                                                                       |
+| go fix            |                              |                                                                       |
+| go fmt            | gno fmt                      | gofmt (& similar tools, like gofumpt) works on gno code.              |
+| go generate       |                              |                                                                       |
+| go get            |                              | see `gno mod download`.                                               |
+| go help           | gno $cmd --help              | ie. `gno doc --help`                                                  |
+| go install        |                              |                                                                       |
+| go list           |                              |                                                                       |
+| go mod            | gno mod                      |                                                                       |
+| + go mod init     | gno mod init                 | same behavior                                                         |
+| + go mod download | gno mod download             | same behavior                                                         |
+| + go mod tidy     | gno mod tidy                 | same behavior                                                         |
+| + go mod why      | gno mod why                  | same intention                                                        |
+|                   | gno tool transpile           |                                                                       |
+| go work           |                              |                                                                       |
+|                   | gno tool repl                |                                                                       |
+| go run            | gno run                      |                                                                       |
+| go test           | gno test                     | limited compatibility                                                 |
+| go tool           |                              |                                                                       |
+| go version        |                              |                                                                       |
+| go vet            |                              |                                                                       |
+| golint            | gno tool lint                | same intention                                                        |
diff --git a/examples/Makefile b/examples/Makefile
@@ -33,19 +33,19 @@ OFFICIAL_PACKAGES += ./gno.land/r/gov
 # Dev tools
 .PHONY: transpile
 transpile:
-	go run ../gnovm/cmd/gno transpile -v .
+	go run ../gnovm/cmd/gno tool transpile -v .
 
 .PHONY: build
 build:
-	go run ../gnovm/cmd/gno transpile -v --gobuild .
+	go run ../gnovm/cmd/gno tool transpile -v --gobuild .
 
 .PHONY: test
 test:
 	go run ../gnovm/cmd/gno test -v ./...
 
 .PHONY: lint
 lint:
-	go run ../gnovm/cmd/gno lint -v $(OFFICIAL_PACKAGES)
+	go run ../gnovm/cmd/gno tool lint -v $(OFFICIAL_PACKAGES)
 
 .PHONY: test.sync
 test.sync:

diff --git a/gnovm/Makefile b/gnovm/Makefile
@@ -54,8 +54,8 @@ lint:
 
 .PHONY: fmt
 fmt:
-	go run ./cmd/gno fmt $(GNOFMT_FLAGS) ./stdlibs/... ./tests/stdlibs/...
 	$(rundep) mvdan.cc/gofumpt $(GOFMT_FLAGS) .
+	go run ./cmd/gno fmt $(GNOFMT_FLAGS) ./stdlibs/... ./tests/stdlibs/...
 
 .PHONY: imports
 imports:
@@ -125,7 +125,13 @@ _test.filetest:;
 # TODO: move _dev.stringer to go:generate instructions, simplify generate
 #       to just go generate.
 .PHONY: generate
-generate: _dev.stringer _dev.generate
+generate: _dev.stringer _dev.generate _dev.docs
+
+.PHONY: _dev.docs
+_dev.docs:
+	mkdir -p .tmp
+	(go run ./cmd/gno -h 2>&1 || true) | grep -v "exit status 1" > .tmp/gno-help.txt
+	$(rundep) github.com/campoy/embedmd -w `find . -name "*.md"`
 
 stringer_cmd=$(rundep) golang.org/x/tools/cmd/stringer
 .PHONY: _dev.stringer

diff --git a/gnovm/cmd/gno/README.md b/gnovm/cmd/gno/README.md
@@ -6,13 +6,25 @@
 
 `gno <command> [arguments]`
 
-## Commands
+## Usage
 
-* `gno run` - run a Gno file
-* `gno transpile` - transpile .gno to .go
-* `gno test` - test a gno package
-* `gno mod` - manages dependencies
-* `gno repl` start a GnoVM REPL
+[embedmd]:#(../../.tmp/gno-help.txt)
+```txt
+USAGE
+  gno <command> [arguments]
+
+SUBCOMMANDS
+  bug    start a bug report
+  clean  remove generated and cached data
+  doc    show documentation for package or symbol
+  env    print gno environment information
+  fmt    gnofmt (reformat) package sources
+  mod    module maintenance
+  run    run gno packages
+  test   test packages
+  tool   run specified gno tool
+
+```
 
 ## Install
 

diff --git a/gnovm/cmd/gno/bug.go b/gnovm/cmd/gno/bug.go
@@ -61,7 +61,7 @@ func newBugCmd(io commands.IO) *commands.Command {
 		commands.Metadata{
 			Name:       "bug",
 			ShortUsage: "bug",
-			ShortHelp:  "Start a bug report",
+			ShortHelp:  "start a bug report",
 			LongHelp: `opens https://github.com/gnolang/gno/issues in a browser. 
 
 The new issue body is prefilled for you with the following information:

diff --git a/gnovm/cmd/gno/clean.go b/gnovm/cmd/gno/clean.go
@@ -26,7 +26,7 @@ func newCleanCmd(io commands.IO) *commands.Command {
 		commands.Metadata{
 			Name:       "clean",
 			ShortUsage: "clean [flags]",
-			ShortHelp:  "removes generated files and cached data",
+			ShortHelp:  "remove generated and cached data",
 		},
 		cfg,
 		func(ctx context.Context, args []string) error {

diff --git a/gnovm/cmd/gno/doc.go b/gnovm/cmd/gno/doc.go
@@ -29,7 +29,8 @@ func newDocCmd(io commands.IO) *commands.Command {
 		commands.Metadata{
 			Name:       "doc",
 			ShortUsage: "doc [flags] <pkgsym>",
-			ShortHelp:  "get documentation for the specified package or symbol (type, function, method, or variable/constant)",
+			ShortHelp:  "show documentation for package or symbol",
+			LongHelp:   "get documentation for the specified package or symbol (type, function, method, or variable/constant)",
 		},
 		c,
 		func(_ context.Context, args []string) error {

diff --git a/gnovm/cmd/gno/env.go b/gnovm/cmd/gno/env.go
@@ -18,7 +18,7 @@ func newEnvCmd(io commands.IO) *commands.Command {
 		commands.Metadata{
 			Name:       "env",
 			ShortUsage: "env [flags] <pkgsym>",
-			ShortHelp:  "`env` prints Gno environment information",
+			ShortHelp:  "print gno environment information",
 		},
 		c,
 		func(_ context.Context, args []string) error {

diff --git a/gnovm/cmd/gno/fmt.go b/gnovm/cmd/gno/fmt.go
@@ -35,7 +35,7 @@ func newFmtCmd(io commands.IO) *commands.Command {
 		commands.Metadata{
 			Name:       "fmt",
 			ShortUsage: "gno fmt [flags] [path ...]",
-			ShortHelp:  "Run gno file formatter.",
+			ShortHelp:  "gnofmt (reformat) package sources",
 			LongHelp:   "The `gno fmt` tool processes, formats, and cleans up `gno` source files.",
 		},
 		cfg,

diff --git a/gnovm/cmd/gno/main.go b/gnovm/cmd/gno/main.go
@@ -16,33 +16,32 @@ func main() {
 func newGnocliCmd(io commands.IO) *commands.Command {
 	cmd := commands.NewCommand(
 		commands.Metadata{
-			ShortUsage: "<subcommand> [flags] [<arg>...]",
-			LongHelp:   "Runs the gno development toolkit",
+			ShortUsage: "gno <command> [arguments]",
 		},
 		commands.NewEmptyConfig(),
 		commands.HelpExec,
 	)
 
 	cmd.AddSubCommands(
-		newModCmd(io),
-		newTestCmd(io),
-		newLintCmd(io),
-		newRunCmd(io),
-		newTranspileCmd(io),
+		newBugCmd(io),
+		// build
 		newCleanCmd(io),
-		newReplCmd(),
 		newDocCmd(io),
 		newEnvCmd(io),
-		newBugCmd(io),
+		// fix
 		newFmtCmd(io),
-		// graph
-		// vendor -- download deps from the chain in vendor/
-		// list -- list packages
-		// render -- call render()?
-		// publish/release
 		// generate
-		// "vm" -- starts an in-memory chain that can be interacted with?
+		// get
+		// install
+		// list -- list packages
+		newModCmd(io),
+		// work
+		newRunCmd(io),
+		// telemetry
+		newTestCmd(io),
+		newToolCmd(io),
 		// version -- show cmd/gno, golang versions
+		// vet
 	)
 
 	return cmd

diff --git a/gnovm/cmd/gno/mod.go b/gnovm/cmd/gno/mod.go
@@ -25,16 +25,20 @@ func newModCmd(io commands.IO) *commands.Command {
 		commands.Metadata{
 			Name:       "mod",
 			ShortUsage: "mod <command>",
-			ShortHelp:  "manage gno.mod",
+			ShortHelp:  "module maintenance",
 		},
 		commands.NewEmptyConfig(),
 		commands.HelpExec,
 	)
 
 	cmd.AddSubCommands(
 		newModDownloadCmd(io),
+		// edit
+		// graph
 		newModInitCmd(),
 		newModTidy(io),
+		// vendor
+		// verify
 		newModWhy(io),
 	)
 

diff --git a/gnovm/cmd/gno/run.go b/gnovm/cmd/gno/run.go
@@ -32,7 +32,7 @@ func newRunCmd(io commands.IO) *commands.Command {
 		commands.Metadata{
 			Name:       "run",
 			ShortUsage: "run [flags] <file> [<file>...]",
-			ShortHelp:  "runs the specified gno files",
+			ShortHelp:  "run gno packages",
 		},
 		cfg,
 		func(_ context.Context, args []string) error {

diff --git a/gnovm/cmd/gno/test.go b/gnovm/cmd/gno/test.go
@@ -35,7 +35,7 @@ func newTestCmd(io commands.IO) *commands.Command {
 		commands.Metadata{
 			Name:       "test",
 			ShortUsage: "test [flags] <package> [<package>...]",
-			ShortHelp:  "runs the tests for the specified packages",
+			ShortHelp:  "test packages",
 			LongHelp: `Runs the tests for the specified packages.
 
 'gno test' recompiles each package along with any files with names matching the

diff --git a/gnovm/cmd/gno/testdata/lint/bad_import.txtar b/gnovm/cmd/gno/testdata/lint/bad_import.txtar
@@ -1,6 +1,6 @@
-# testing gno lint command: bad import error
+# testing gno tool lint command: bad import error
 
-! gno lint ./bad_file.gno
+! gno tool lint ./bad_file.gno
 
 cmp stdout stdout.golden
 cmp stderr stderr.golden

diff --git a/gnovm/cmd/gno/testdata/lint/file_error.txtar b/gnovm/cmd/gno/testdata/lint/file_error.txtar
@@ -1,6 +1,6 @@
-# gno lint: test file error
+# gno tool lint: test file error
 
-! gno lint ./i_have_error_test.gno
+! gno tool lint ./i_have_error_test.gno
 
 cmp stdout stdout.golden
 cmp stderr stderr.golden

diff --git a/gnovm/cmd/gno/testdata/lint/no_error.txtar b/gnovm/cmd/gno/testdata/lint/no_error.txtar
@@ -1,6 +1,6 @@
-# testing simple gno lint command with any error
+# testing simple gno tool lint command with any error
 
-gno lint ./good_file.gno
+gno tool lint ./good_file.gno
 
 cmp stdout stdout.golden
 cmp stdout stderr.golden

diff --git a/gnovm/cmd/gno/testdata/lint/no_gnomod.txtar b/gnovm/cmd/gno/testdata/lint/no_gnomod.txtar
@@ -1,6 +1,6 @@
-# gno lint: no gnomod
+# gno tool lint: no gnomod
 
-! gno lint .
+! gno tool lint .
 
 cmp stdout stdout.golden
 cmp stderr stderr.golden

diff --git a/gnovm/cmd/gno/testdata/lint/not_declared.txtar b/gnovm/cmd/gno/testdata/lint/not_declared.txtar
@@ -1,6 +1,6 @@
-# testing gno lint command: not declared error
+# testing gno tool lint command: not declared error
 
-! gno lint ./bad_file.gno
+! gno tool lint ./bad_file.gno
 
 cmp stdout stdout.golden
 cmp stderr stderr.golden

diff --git a/gnovm/cmd/gno/testdata/transpile/gobuild_flag_build_error.txtar b/gnovm/cmd/gno/testdata/transpile/gobuild_flag_build_error.txtar
@@ -1,7 +1,7 @@
-# Run gno transpile with -gobuild flag
+# Run gno tool transpile with -gobuild flag
 # The error messages changed sometime in go1.23, so this avoids errors
 
-! gno transpile -gobuild .
+! gno tool transpile -gobuild .
 
 ! stdout .+
 stderr '^main.gno:4:6: .*declared and not used'

diff --git a/gnovm/cmd/gno/testdata/transpile/gobuild_flag_parse_error.txtar b/gnovm/cmd/gno/testdata/transpile/gobuild_flag_parse_error.txtar
@@ -1,6 +1,6 @@
-# Run gno transpile with -gobuild flag on file with parse error
+# Run gno tool transpile with -gobuild flag on file with parse error
 
-! gno transpile -gobuild .
+! gno tool transpile -gobuild .
 
 ! stdout .+
 stderr '^main.gno:3:1: expected declaration, found invalid$'

diff --git a/gnovm/cmd/gno/testdata/transpile/invalid_import.txtar b/gnovm/cmd/gno/testdata/transpile/invalid_import.txtar
@@ -1,6 +1,6 @@
-# Run gno transpile with gno files with an invalid import path
+# Run gno tool transpile with gno files with an invalid import path
 
-! gno transpile .
+! gno tool transpile .
 
 ! stdout .+
 stderr '^main.gno:5:2: import "xxx" does not exist$'

diff --git a/gnovm/cmd/gno/testdata/transpile/no_args.txtar b/gnovm/cmd/gno/testdata/transpile/no_args.txtar
@@ -1,6 +1,6 @@
-# Run gno transpile without args
+# Run gno tool transpile without args
 
-! gno transpile
+! gno tool transpile
 
 ! stdout .+
 stderr 'USAGE'
diff --git a/gnovm/cmd/gno/testdata/transpile/parse_error.txtar b/gnovm/cmd/gno/testdata/transpile/parse_error.txtar
@@ -1,6 +1,6 @@
-# Run gno transpile with gno files with parse errors
+# Run gno tool transpile with gno files with parse errors
 
-! gno transpile .
+! gno tool transpile .
 
 ! stdout .+
 stderr '^main.gno:3:1: expected declaration, found invalid$'

diff --git a/gnovm/cmd/gno/testdata/transpile/valid_empty_dir.txtar b/gnovm/cmd/gno/testdata/transpile/valid_empty_dir.txtar
@@ -1,6 +1,6 @@
-# Run gno transpile on an empty dir
+# Run gno tool transpile on an empty dir
 
-gno transpile .
+gno tool transpile .
 
 ! stdout .+
 ! stderr .+
-Original file line number
+Diff line change
@@ Expand Up / @@ -34,3 +34,6 @@ coverage.out @@
     *.swp
     *.swo
     *.bak
+    .tmp/
+    wal/