codegen

Documentation

Overview

Package codegen uses astkit and the Go compiler to analyze Go source and generate new code from it. It bootstraps itself on astkit — using AST manipulation to produce code, and the compiler to validate it.

Index

• func CompilePackageProtos(pkg *GeneratedPackage) (map[string]*ProtoCompileResult, error)
• func FormatGeneratedFile(src string) (string, error)
• func GenerateMessageDecls(messages []StructInfo) []ast.Decl
• func GeneratePackageProto(pkgName, goPackage string, bundles []*ServiceBundle, types []StructInfo) string
• func GenerateProto(pkg, goPackage string, iface InterfaceInfo, types []StructInfo) string
• type BootstrapResult
  • func Bootstrap(module, src string) (*BootstrapResult, error)
  • func BootstrapDir(module, dir string) (*BootstrapResult, error)
• type FieldInfo
• type FullBootstrapResult
  • func FullBootstrap(module, src string) (*FullBootstrapResult, error)
• type FuncInfo
• type GeneratedPackage
  • func WritePackage(module, pkgName string, info *PackageInfo, bundles []*ServiceBundle, ...) (*GeneratedPackage, error)
• type InterfaceInfo
• type PackageInfo
  • func AnalyzeFile(f *ast.File, fset *token.FileSet) *PackageInfo
  • func AnalyzeSource(src string) (*PackageInfo, error)
• type ProtoCompileResult
• type ProtoCompiler
  • func NewProtoCompiler() (*ProtoCompiler, error)
  • func (pc *ProtoCompiler) Compile(protoFile, goPackage, outDir string) (*ProtoCompileResult, error)
  • func (pc *ProtoCompiler) CompileBundle(bundle *ServiceBundle) (*ProtoCompileResult, error)
  • func (pc *ProtoCompiler) CompileProtoString(protoContent, goPackage string) (*ProtoCompileResult, error)
• type RoundTripReport
• type ServiceBundle
  • func OnboardDir(pkgName, dir string) ([]*ServiceBundle, error)
  • func OnboardFile(pkgName string, f *ast.File, fset *token.FileSet) ([]*ServiceBundle, error)
  • func OnboardInterface(pkgName string, iface InterfaceInfo, types []StructInfo) (*ServiceBundle, error)
  • func OnboardSource(pkgName, src string) ([]*ServiceBundle, error)
• type StructInfo
• type TransformResult
  • func TransformInterface(iface InterfaceInfo, existingTypes []StructInfo) *TransformResult

Functions

func CompilePackageProtos

func CompilePackageProtos(pkg *GeneratedPackage) (map[string]*ProtoCompileResult, error)

CompilePackageProtos compiles all .proto files in a GeneratedPackage. Returns a map of proto filename → ProtoCompileResult.

func FormatGeneratedFile

func FormatGeneratedFile(src string) (string, error)

FormatGeneratedFile runs gofmt on a generated file string.

func GenerateMessageDecls

func GenerateMessageDecls(messages []StructInfo) []ast.Decl

GenerateMessageDecls produces ast declarations for the generated message structs.

func GeneratePackageProto

func GeneratePackageProto(pkgName, goPackage string, bundles []*ServiceBundle, types []StructInfo) string

GeneratePackageProto generates a single .proto file containing all services and all message types from a set of service bundles. This produces one proto file per package, avoiding message name conflicts across services.

func GenerateProto

func GenerateProto(pkg, goPackage string, iface InterfaceInfo, types []StructInfo) string

GenerateProto generates a .proto service definition from analyzed Go types. It maps Go structs to proto messages and interface methods to RPCs. The goPackage parameter sets the go_package option in the proto file.

Types

type BootstrapResult

type BootstrapResult struct {
	// Package is the generated package.
	Package *GeneratedPackage

	// CompileOK is true if the generated code compiled successfully.
	CompileOK bool

	// CompileError is set if compilation failed.
	CompileError error

	// RoundTrip is the re-analysis of the generated code — verifying
	// that codegen can read its own output.
	RoundTrip *PackageInfo

	// RoundTripOK is true if re-analysis found the expected structure.
	RoundTripOK bool

	// RoundTripReport has detailed pass/fail info for each check.
	RoundTripReport *RoundTripReport
}

BootstrapResult is the output of the full bootstrap pipeline.

func Bootstrap

func Bootstrap(module, src string) (*BootstrapResult, error)

Bootstrap runs the full bootstrap pipeline:

1. Analyze source code
2. Transform interfaces → gRPC form
3. Generate a complete Go package (server, main, proto, go.mod)
4. Compile the generated .proto with protoc
5. go mod tidy + go build the whole thing
6. Re-analyze the generated code with codegen (round-trip)
7. Verify the round-trip preserves structure

func BootstrapDir

func BootstrapDir(module, dir string) (*BootstrapResult, error)

BootstrapDir runs the full bootstrap pipeline on an existing directory.

type FieldInfo

type FieldInfo struct {
	Name     string
	TypeExpr ast.Expr
	TypeStr  string
}

FieldInfo describes a field or parameter.

type FullBootstrapResult

type FullBootstrapResult struct {
	*BootstrapResult

	// ProtoResults holds the proto compilation result per service.
	ProtoResults map[string]*ProtoCompileResult

	// ProtoCompileOK is true if all protos compiled successfully.
	ProtoCompileOK bool
}

FullBootstrapResult extends BootstrapResult with proto compilation output. In the unified pipeline, proto compilation is part of Bootstrap itself, so this type provides backward-compatible access to the same result.

func FullBootstrap

func FullBootstrap(module, src string) (*FullBootstrapResult, error)

FullBootstrap runs the complete pipeline: analyze → onboard → write package → protoc → go mod tidy → go build. This is the unified entry point that produces a complete, runnable gRPC service.

type FuncInfo

type FuncInfo struct {
	Name       string
	RecvType   string // empty for functions
	Params     []FieldInfo
	Results    []FieldInfo
	HasContext bool // first param is context.Context
	HasError   bool // last result is error
}

FuncInfo describes a function or method.

type GeneratedPackage

type GeneratedPackage struct {
	// Module is the Go module path (e.g. "example.com/myservice").
	Module string

	// PkgName is the Go package name.
	PkgName string

	// Files maps filename → content for every generated file.
	Files map[string]string

	// Bundles are the service bundles that were generated.
	Bundles []*ServiceBundle

	// SourceInfo is the analyzed info from the input source.
	SourceInfo *PackageInfo
}

GeneratedPackage is a complete, self-contained Go package produced by the bootstrap pipeline. Every file compiles together as a unit.

func WritePackage

func WritePackage(module, pkgName string, info *PackageInfo, bundles []*ServiceBundle, outDir string) (*GeneratedPackage, error)

WritePackage generates a complete, compilable gRPC service package. The output layout:

pb/<pkg>.proto                    — unified proto definition
<service>_server.go (package main) — server impl using pb types
main.go                           — gRPC server wiring
go.mod                            — module with grpc/protobuf deps

Proto compilation (protoc) and Go compilation happen in FullBootstrap.

type InterfaceInfo

type InterfaceInfo struct {
	Name    string
	Methods []FuncInfo
}

InterfaceInfo describes an interface type.

type PackageInfo

type PackageInfo struct {
	Name       string
	Structs    []StructInfo
	Interfaces []InterfaceInfo
	Functions  []FuncInfo
}

PackageInfo holds analyzed information about a Go package.

func AnalyzeFile

func AnalyzeFile(f *ast.File, fset *token.FileSet) *PackageInfo

AnalyzeFile extracts type and function info from a parsed file.

func AnalyzeSource

func AnalyzeSource(src string) (*PackageInfo, error)

AnalyzeSource parses Go source code and extracts type/function info.

type ProtoCompileResult

type ProtoCompileResult struct {
	// ProtoFile is the input .proto file path.
	ProtoFile string

	// GoFiles are the generated Go files (message types + gRPC stubs).
	GoFiles map[string]string

	// CompileOK is true if protoc succeeded.
	CompileOK bool

	// Error is set if compilation failed.
	Error error
}

ProtoCompileResult holds the output of compiling a .proto file.

type ProtoCompiler

type ProtoCompiler struct {
	// ProtocBin is the path to the protoc binary.
	ProtocBin string

	// GenGoBin is the path to protoc-gen-go.
	GenGoBin string

	// GenGoGRPCBin is the path to protoc-gen-go-grpc.
	GenGoGRPCBin string
}

ProtoCompiler compiles .proto files into Go code using protoc.

func NewProtoCompiler

func NewProtoCompiler() (*ProtoCompiler, error)

NewProtoCompiler locates protoc and its Go plugins on PATH.

func (*ProtoCompiler) Compile

func (pc *ProtoCompiler) Compile(protoFile, goPackage, outDir string) (*ProtoCompileResult, error)

Compile runs protoc on a .proto file and produces Go message and gRPC files. The goPackage parameter sets the Go package path for the generated code. Output files are written to outDir.

func (*ProtoCompiler) CompileBundle

func (pc *ProtoCompiler) CompileBundle(bundle *ServiceBundle) (*ProtoCompileResult, error)

CompileBundle compiles the proto from a ServiceBundle and returns the generated Go files.

func (*ProtoCompiler) CompileProtoString

func (pc *ProtoCompiler) CompileProtoString(protoContent, goPackage string) (*ProtoCompileResult, error)

CompileProtoString compiles proto content from a string (writes to a temp file first). Returns the generated Go files.

type RoundTripReport

type RoundTripReport struct {
	OK       bool
	Failures []string
}

RoundTripReport describes what passed and what failed during round-trip verification. It replaces the old bool-only check with structured feedback.

type ServiceBundle

type ServiceBundle struct {
	// Name is the service name (from the interface).
	Name string

	// Proto is the .proto file content.
	Proto string

	// Messages are generated request/response structs.
	Messages []StructInfo

	// NormalizedInterface is the gRPC-compatible version of the interface.
	NormalizedInterface InterfaceInfo
}

ServiceBundle is the complete output of auto-onboarding a Go interface. It contains everything needed to expose a Go interface as a gRPC service.

func OnboardDir

func OnboardDir(pkgName, dir string) ([]*ServiceBundle, error)

OnboardDir analyzes all Go files in a directory and onboards every interface it finds. It merges struct types across files so that request/response types defined anywhere in the package are recognized.

func OnboardFile

func OnboardFile(pkgName string, f *ast.File, fset *token.FileSet) ([]*ServiceBundle, error)

OnboardFile onboards all interfaces from a parsed Go file.

func OnboardInterface

func OnboardInterface(pkgName string, iface InterfaceInfo, types []StructInfo) (*ServiceBundle, error)

OnboardInterface takes a Go interface and generates a service bundle: proto definition, generated message types, and normalized interface.

func OnboardSource

func OnboardSource(pkgName, src string) ([]*ServiceBundle, error)

OnboardSource parses Go source code and onboards all interfaces found in it.

type StructInfo

type StructInfo struct {
	Name    string
	Fields  []FieldInfo
	Methods []FuncInfo
}

StructInfo describes a struct type and its methods.

type TransformResult

type TransformResult struct {
	// Interface is the normalized interface with gRPC-compatible signatures.
	Interface InterfaceInfo
	// Messages are the generated request/response structs.
	Messages []StructInfo
	// Original is the unmodified interface for reference.
	Original InterfaceInfo
}

TransformResult holds the output of transforming an interface into gRPC-compatible form: request/response wrapper structs and a normalized interface where every method takes (ctx, *Request) and returns (*Response, error).

func TransformInterface

func TransformInterface(iface InterfaceInfo, existingTypes []StructInfo) *TransformResult

TransformInterface takes an arbitrary Go interface and normalizes it for gRPC: each method gets a request struct (wrapping its params) and a response struct (wrapping its non-error results). Methods that already follow the convention (single struct param, single struct result) are left alone.