Go Quality & Tooling Guide (GoDoctor) #

GoDoctor is a high-level Go developer workflow orchestrator that coordinates standard Go toolchain binaries and static analysis utilities—providing guarded code edits, automated build and lint pipelines, mutation testing, and SQLite test analytics both as a command-line interface (CLI) and as a Model Context Protocol (MCP) server.

1. Go Coding & Architectural Standards #

Google Go Style & Idiomatic Practices #

• Standard Toolchain Enforcement: All code must be strictly formatted with gofmt, organized with goimports, checked with go vet, and linted with golangci-lint.
• Naming Conventions:
  • Avoid repeating package names in exported types or functions (no stuttering). Use user.Service instead of user.UserService, http.Server instead of http.HttpServer, and config.Load instead of config.LoadConfig.
  • Use camelCase for unexported identifiers and PascalCase for exported identifiers. Acronyms must remain uniform in case (e.g., JSONURL, dbID, xmlHTTP).
• Error Handling:
  • Return errors as the last return value.
  • Wrap errors with contextual information using fmt.Errorf("action description: %w", err).
  • Do not panic in libraries or standard business logic; return explicit errors.

Package Architecture & Layout #

• Flat Package Structure: Prefer flat package layouts over deep enterprise layered modeling (such as adapters/, ports/, entities/, controllers/, repositories/, services/, usecases/). Keep code flat in the root or logically grouped by feature/domain.
• Private vs. Public API: Use internal/ for private packages that should not be imported by external modules. Do not create a pkg/ directory unless developing a cloud-native project in the Kubernetes ecosystem.
• Test Fixtures & Golden Files: Store test fixtures, golden files, mock datasets, and external test inputs in testdata/ directories. The Go toolchain ignores testdata/ folders during normal package compilation.
• Avoid Monolithic Files: Split package logic into clear, focused files named after their primary responsibility (e.g., server.go, handler.go, config.go, types.go).
• Prohibition of Generic Catch-All Packages: NEVER create generic util, shared, common, or helpers packages. These act as catch-all dumping grounds that destroy dependency boundaries. Place functionality in specific, domain-named packages or close to its site of use.

API Design & HTTP Architecture #

• Interface Segregation: Keep interfaces small and consumer-defined (accept interfaces, return structs). Do not create premature interfaces with single implementations. Expose concrete types from producer packages.
• HTTP Service Design: Follow modern Go HTTP service design patterns:
  • Constructor-based dependency injection (e.g., NewServer(cfg, logger)).
  • Group HTTP routes and handlers on a single server struct.
  • Write explicit HTTP middleware for cross-cutting concerns (logging, authentication, tracing).

2. Tool Selection Matrix #

Test Runner Tiers (smart_test / godoctor call test) #

• level: "fast": Sub-second inner loop test execution. Runs go test -v directly; skips coverage profiling and testquery.db synchronization. Ideal for rapid iterative development.
• level: "basic" (default): Standard testing tier. Runs unit tests with statement coverage profiling (go tool cover -func) and auto-indexes execution metrics into .godoctor/testquery.db via testquery.
• level: "benchmark": Runs Go benchmark suites (go test -bench=<pattern> -benchmem -run=NONE) and formats throughput and memory allocations as a Markdown table.
• level: "complete": Comprehensive quality gate. Runs basic unit tests, coverage profiling, and testquery.db indexing, followed by multi-worker selene mutation testing across packages. Ideal for pre-commit, CI verification, and release audits.

3. Core Principles & Safeguards #

• Zero-Fallback Policy: External binaries (golangci-lint, modernize, deadcode, selene, testquery) must be pre-installed in $PATH or defined in .godoctor.yaml. Dynamic go run compilation fallbacks are banned to eliminate 1.5s–4.5s latency delays and ensure reproducible execution.
• Tool Version Tracking: GoDoctor actively verifies installed tool versions against recommended baselines, reporting non-blocking upgrade recommendations and providing godoctor check.
• Absolute Paths Required: All directory (dir) and file (filename) parameters must be absolute paths (e.g. /path/to/project).
• Atomic Edit Transactions & Compiler Gate: edit / smart_edit matches target blocks using whitespace-insensitive Levenshtein similarity, formats via goimports, and writes to a temporary file before atomic rename. Edits are verified via go vet ./... across the workspace and automatically rolled back (with identifier spelling suggestions) if errors are introduced.
• Concurrency & Resource Management: Heavy operations like level: "complete" (Selene mutation testing) utilize all CPU cores; avoid spawning concurrent test/build tasks while complete runs are in flight to prevent CPU exhaustion and SQLite WAL contention.
• Configuration-Driven: Subsystems read settings from .godoctor.yaml following a strict 3-tier precedence hierarchy: $$\text{Per-Call Payload (JSON)} \succ \text{Config File } (\texttt{.godoctor.yaml}) \succ \text{Built-in Defaults}$$

4. Environment Diagnostics (godoctor check) #

Inspect installed external tools, versions, and health status:

# Formatted ASCII diagnostic table
godoctor check

# Machine-readable JSON output
godoctor check --json

5. Centralized Configuration (.godoctor.yaml) #

Initialize a configuration file in your repository:

godoctor init

Key configuration sections in .godoctor.yaml:

version: "1"

# CLI & Runtime Settings
cli:
  default_output: "text"
  color: true

# Server Execution Settings
server:
  write_timeout: "5m"
  allowed_origins:
    - "http://localhost"
    - "http://localhost:*"
    - "http://127.0.0.1"
    - "http://127.0.0.1:*"

# External Tools & Version Management
tools:
  golangci_lint:
    recommended_version: "v2.12.2"
    pkg: "github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2"
  modernize:
    recommended_version: "latest"
    pkg: "golang.org/x/tools/go/analysis/passes/modernize/cmd/modernize@latest"
  deadcode:
    recommended_version: "latest"
    pkg: "golang.org/x/tools/cmd/deadcode@latest"
  selene:
    recommended_version: "latest"
    pkg: "github.com/danicat/selene/cmd/selene@latest"
    workers: 0 # 0 defaults to runtime.GOMAXPROCS
    testquery_compat: true
  testquery:
    recommended_version: "latest"
    pkg: "github.com/danicat/testquery@latest"
    db_path: ".godoctor/testquery.db"

# Subsystem Flags & Behavior
features:
  autofix: true
  deadcode_check: true
  testquery_sync: true
  version_check_hints: true
  auto_rollback: true

6. Installation & Surface Management #

Installing GoDoctor CLI #

go install github.com/danicat/godoctor/cmd/godoctor@latest

Managing Surfaces (godoctor install & uninstall) #

Configure MCP server registration in mcp_config.json and unpack agent skills:

# Configure MCP and skills globally (default: ~/.gemini/config)
godoctor install

# Configure in workspace scope (.agents/)
godoctor install -w

# Modular configuration
godoctor install --mcp        # MCP server registration only
godoctor install --skills     # Skills unpacking only

# Clean removal
godoctor uninstall
godoctor uninstall -w

7. Direct CLI Invocation Examples (godoctor call) #

1. edit (Guarded Fuzzy Edits with goimports & Compiler Rollback) #

godoctor call edit '{"filename": "/absolute/path/to/main.go", "old_content": "fmt.Println(\"old\")", "new_content": "fmt.Println(\"new\")"}'

2. build (Build, Test, and Lint Pipeline) #

# Standard workspace build and test
godoctor call build '{"dir": "/absolute/path/to/project"}'

# Build with specific output binary target
godoctor call build '{"dir": "/absolute/path/to/project", "packages": "./cmd/godoctor", "output": "bin/godoctor"}'

3. test (Multi-Tier Test Runner) #

# Available levels: fast, basic, benchmark, complete
godoctor call test '{"dir": "/absolute/path/to/project", "level": "basic"}'

4. docs (Package & Symbol Documentation via go/doc) #

godoctor call docs '{"import_path": "net/http", "symbol_name": "Client"}'

5. selene (Mutation Testing) #

godoctor call selene '{"dir": "/absolute/path/to/project"}'

6. tq (SQL Test & Coverage Analytics) #

godoctor call tq '{"dir": "/absolute/path/to/project", "query": "SELECT package, test, elapsed FROM all_tests WHERE action = '\''fail'\''"}'

8. Detailed References #

For specialized workflows, refer to the companion references:

• TestQuery SQL Analytics & Schema: references/testquery.md — Comprehensive database schema (all_tests, all_coverage, test_coverage, all_code), SQLite query recipes, and statement coverage metrics.
• Selene Mutation Testing Guide: references/selene.md — AST mutation operators, mutant statuses (KILLED, SURVIVED, UNCOVERED), targeted mode execution, and surviving mutant remediation strategies.