gogh: Instructions file for Codex

gogh — LLM usage context

Reference for an LLM that needs to write or modify Go code that uses the gogh library to generate Go source. Module: github.com/sirkon/gogh · Go 1.26+ · Root package is gogh (all public API lives there).

What gogh is

gogh is a Go source rendering library. You build Go files programmatically by writing formatted lines through a renderer; gogh takes care of the parts that are tedious and error-prone in hand-written generators:

• collecting and emitting the import block,
• resolving package qualifier names and alias collisions automatically,
• running gofmt (or fancyfmt) on the result,
• writing the files into the correct location inside the current Go module.

Use it when writing go generate tools, protoc plugins, schema-to-Go generators, etc. The model is "write lines that look like Go, with $placeholders for imported-package qualifiers and positional args".

Mental model (read this first)

1. Module[T] — one generation session, tied to the Go module on disk (discovered via go env / go mod edit). You create it once with gogh.New(...). Render() at the end flushes all files to disk. Must run inside a module directory; shells out to the go toolchain and uses a boltDB cache for package-name lookups. That cache is self-invalidating: versioned deps are keyed by (package path, declared version) from go.mod so a bump invalidates exactly the affected entry; replaced/workspaced/local packages are read straight from disk (cheap, always fresh, never bolt-cached); stdlib/undeclared-transitive are cached by package path. A per-module in-memory cache ensures each name is resolved at most once per Module.
2. Package[T] — a Go package within the module. Get one from the module (Root, Current, Package, PackageName). Each package produces one or more file renderers.
3. GoRenderer[T] — the writing surface for one Go file. You write lines into it; it owns that file's imports and rendering context.
4. RawRenderer — like GoRenderer but for plain-text files (no package header, no imports). Same line API.
5. Importer / Imports — import management. Add(pkgpath).Ref("name") registers an import and binds its qualifier into the rendering context so $name expands to the (possibly aliased) package name.
6. Rendering context / scope — a hierarchical map of named values per renderer. Populated by Ref, Let, Uniq, UniqBind, and the function helpers (Returns sets ReturnZeroValues). Exposed in format strings as $name; positional args are $0, $1, …