feat(gnodoc): generate docs from contract codebase

gnodoc/.gitignore

@@ -0,0 +1 @@
+gnodoc

gnodoc/README.md

@@ -0,0 +1,114 @@
+# GnoDoc
+
+GnoDoc is a local documentation generator for Go and Gno packages that reads source code directly and emits Markdown. Unlike `gno doc`, it does not require deployment on-chain, so it can document packages before release. The goal is to provide pkg.go.dev-like structure and readability while staying lightweight and deterministic.
+
+When you run GnoDoc, it resolves the input package path in a predictable order. A directory path is used as-is, a module-relative path is resolved against a module root, and a Go import path is resolved via `go list` when needed. The module root is detected by walking upward from the package directory until a `gnomod.toml` is found; if `--module-root` is provided, that directory is used instead. The `module` field in `gnomod.toml` is used to build the final import path shown in the rendered Markdown.
+
+File discovery is intentionally simple. GnoDoc looks for `.go` and `.gno` files and optionally includes test files when `--include-tests` is set. File exclusion uses filename glob patterns, and parsing continues in best-effort mode when `--ignore-parse-errors` is enabled. The AST is built with comment parsing enabled and normalized into a DocPackage model that preserves symbol relationships (types, methods, functions, constants, variables), source locations, and structured tags such as Examples and Deprecated blocks.
+
+Markdown rendering follows a consistent section order: Overview, Index, Constants, Variables, Functions, Types, Examples, and Notes. The Index contains exported symbols and stable anchors, while constants and variables are grouped using their original declaration style. Function sections show signatures, description text, and a Returns block that summarizes named return values and concrete return expressions extracted from the function body. Types include fields, methods, and constructors, and examples are emitted as fenced code blocks with output where available. Source links are optionally rendered from file and line information using `--source-link-base`.
+
+## CLI Flags
+
+### Output
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--out=DIR` | current directory | Output directory for generated Markdown. |
+| `--output-file=NAME` | `README.md` | Output filename for the default command. |
+| `--filename=NAME` | `README.md` | Output filename for `export`. |
+| `--format=md` | `md` | Output format for `export` (Markdown only). |
+
+### Parsing and Filtering
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--include-tests` | false | Include `_test.go` / `_test.gno` files. |
+| `--ignore-parse-errors` | false | Continue parsing if some files fail. |
+| `--exclude=PATTERN` | (none) | Exclude files by filename glob (comma-separated). |
+| `--exported-only` | true | Only render exported symbols. |
+| `--all` | false | Include unexported symbols. |
+
+### Paths and Links
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--module-root=DIR` | (auto) | Override module root detection. |
+| `--source-link-base=URL` | (none) | Base URL for source links. |
+
+## Usage Examples
+
+Generate documentation for a local package directory:
+```bash
+gnodoc /path/to/package
+```
+
+Generate documentation using module-relative path:
+```bash
+gnodoc --module-root /path/to/module contract/p/gnoswap/int256
+```
+
+Export Markdown to a custom file and directory:
+```bash
+gnodoc export --out docs --filename governance.md contract/r/gnoswap/gov/governance
+```
+
+Include tests and tolerate parse errors:
+```bash
+gnodoc --include-tests --ignore-parse-errors /path/to/package
+```
+
+List packages under a directory:
+```bash
+gnodoc list /path/to/module
+```
+
+## Markdown Output Example (Simplified)
+~~~plain
+# pkgname
+
+`import "module/path/pkgname"`
+
+Package overview text.
+
+## Index
+- [TypeA](#typea)
+- [FuncX](#funcx)
+
+## Constants
+```go
+const (
+	MAX = 1
+)
+```
+
+## Functions
+### FuncX
+```go
+func FuncX(arg int) (result int, err error)
+```
+Description...
+
+#### Returns
+- named: result, err
+- return: result, nil
+
+## Types
+### TypeA
+```go
+type TypeA struct
+```
+Description...
+
+#### Methods
+##### MethodY
+```go
+func (t *TypeA) MethodY() error
+```
+
+#### Returns
+- return: nil
+~~~
+
+## Supported Features
+GnoDoc currently supports Go and Gno parsing, module detection via `gnomod.toml`, export filtering, stable anchors, example extraction from test files, source links, and return expression tracking.
+
+## Current Limitations
+GnoDoc does not render HTML, does not evaluate build tags or platform-specific files, and only supports filename-based exclude patterns. Return analysis is intentionally shallow and does not perform full control-flow or dataflow analysis. Example code formatting is best-effort and may preserve indentation from the source.

gnodoc/cmd/exitcode.go

@@ -0,0 +1,30 @@
+package cmd
+
+// ExitCode represents CLI exit codes.
+type ExitCode int
+
+const (
+	// ExitSuccess indicates successful execution.
+	ExitSuccess ExitCode = 0
+
+	// ExitError indicates a fatal error (input error, module detection failure, render failure).
+	ExitError ExitCode = 1
+
+	// ExitPartialError indicates partial file parsing failure.
+	// Used when --ignore-parse-errors is set but some files failed.
+	ExitPartialError ExitCode = 2
+)
+
+// String returns the string representation of the exit code.
+func (c ExitCode) String() string {
+	switch c {
+	case ExitSuccess:
+		return "success"
+	case ExitError:
+		return "error"
+	case ExitPartialError:
+		return "partial error"
+	default:
+		return "unknown"
+	}
+}

gnodoc/cmd/exitcode_test.go

@@ -0,0 +1,37 @@
+package cmd
+
+import "testing"
+
+func TestExitCode_Values(t *testing.T) {
+	// Exit codes as per spec
+	if ExitSuccess != 0 {
+		t.Errorf("ExitSuccess should be 0, got %d", ExitSuccess)
+	}
+	if ExitError != 1 {
+		t.Errorf("ExitError should be 1, got %d", ExitError)
+	}
+	if ExitPartialError != 2 {
+		t.Errorf("ExitPartialError should be 2, got %d", ExitPartialError)
+	}
+}
+
+func TestExitCode_String(t *testing.T) {
+	tests := []struct {
+		code     ExitCode
+		expected string
+	}{
+		{ExitSuccess, "success"},
+		{ExitError, "error"},
+		{ExitPartialError, "partial error"},
+		{ExitCode(99), "unknown"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.expected, func(t *testing.T) {
+			got := tt.code.String()
+			if got != tt.expected {
+				t.Errorf("String() = %q, want %q", got, tt.expected)
+			}
+		})
+	}
+}

gnodoc/cmd/options.go

@@ -0,0 +1,76 @@
+package cmd
+
+// GlobalOptions contains common options for all commands.
+type GlobalOptions struct {
+	// IncludeTests includes test files (*_test.go, *_test.gno).
+	IncludeTests bool
+
+	// IgnoreParseErrors continues parsing even if some files fail.
+	IgnoreParseErrors bool
+
+	// ExportedOnly includes only exported symbols.
+	ExportedOnly bool
+
+	// SourceLinkBase is the base URL for source links.
+	SourceLinkBase string
+
+	// ModuleRoot specifies the module root directory.
+	ModuleRoot string
+
+	// Exclude patterns for files/directories.
+	Exclude []string
+
+	// OutputFile is the output filename.
+	OutputFile string
+}
+
+// DefaultGlobalOptions returns the default global options.
+func DefaultGlobalOptions() *GlobalOptions {
+	return &GlobalOptions{
+		IncludeTests:      false,
+		IgnoreParseErrors: false,
+		ExportedOnly:      true,
+		OutputFile:        "README.md",
+	}
+}
+
+// ExportOptions contains options for the export command.
+type ExportOptions struct {
+	GlobalOptions
+
+	// Format is the output format (md).
+	Format string
+
+	// OutputDir is the output directory.
+	OutputDir string
+
+	// Filename is the output filename.
+	Filename string
+}
+
+// DefaultExportOptions returns the default export options.
+func DefaultExportOptions() *ExportOptions {
+	return &ExportOptions{
+		GlobalOptions: *DefaultGlobalOptions(),
+		Format:        "md",
+		OutputDir:     ".",
+		Filename:      "README.md",
+	}
+}
+
+// ListOptions contains options for the list command.
+type ListOptions struct {
+	// IncludeTests includes test packages.
+	IncludeTests bool
+
+	// Exclude patterns for packages.
+	Exclude []string
+}
+
+// DefaultListOptions returns the default list options.
+func DefaultListOptions() *ListOptions {
+	return &ListOptions{
+		IncludeTests: false,
+		Exclude:      nil,
+	}
+}

gnodoc/cmd/options_test.go

@@ -0,0 +1,45 @@
+package cmd
+
+import "testing"
+
+func TestGlobalOptions_Default(t *testing.T) {
+	opts := DefaultGlobalOptions()
+
+	if opts.IncludeTests {
+		t.Error("IncludeTests should be false by default")
+	}
+	if opts.IgnoreParseErrors {
+		t.Error("IgnoreParseErrors should be false by default")
+	}
+	if !opts.ExportedOnly {
+		t.Error("ExportedOnly should be true by default")
+	}
+	if opts.OutputFile != "README.md" {
+		t.Errorf("OutputFile should be 'README.md', got %q", opts.OutputFile)
+	}
+}
+
+func TestExportOptions_Default(t *testing.T) {
+	opts := DefaultExportOptions()
+
+	if opts.Format != "md" {
+		t.Errorf("Format should be 'md', got %q", opts.Format)
+	}
+	if opts.OutputDir != "." {
+		t.Errorf("OutputDir should be '.', got %q", opts.OutputDir)
+	}
+	if opts.Filename != "README.md" {
+		t.Errorf("Filename should be 'README.md', got %q", opts.Filename)
+	}
+}
+
+func TestListOptions_Default(t *testing.T) {
+	opts := DefaultListOptions()
+
+	if opts.IncludeTests {
+		t.Error("IncludeTests should be false by default")
+	}
+	if len(opts.Exclude) != 0 {
+		t.Error("Exclude should be empty by default")
+	}
+}