codegen

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 8, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package codegen provides YAML-driven code generation primitives for GoFastr.

Typical CLI-style usage discovers or loads a Config, registers built-in generators and extension commands on a Registry, runs generation into a FileSet, then writes files with WriteFiles. Embedders can register in-process generators and extensions directly and may skip command extension registration entirely.

Index

Constants

View Source 
const ManifestName = ".codegen-manifest.json"

ManifestName is the generated-file ownership manifest written under output roots.

View Source 
const ProtocolVersion = 1

ProtocolVersion is the current external extension protocol version.

Variables

This section is empty.

Functions

func CleanEnabled 

func CleanEnabled(cfg CodegenConfig) bool

CleanEnabled reports whether clean mode is enabled, defaulting to true.

func EnsureNoSymlinkLeaf 

func EnsureNoSymlinkLeaf(path string) error

EnsureNoSymlinkLeaf rejects path when the final component is an existing symlink.

func EnsureNoSymlinkPath 

func EnsureNoSymlinkPath(path string) error

EnsureNoSymlinkPath rejects a path whose existing components include symlinks.

func HasCodegenSection 

func HasCodegenSection(path string) (bool, error)

HasCodegenSection reports whether path has a top-level codegen key.

func LoadSource 

func LoadSource(projectDir string, source SourceConfig) (any, error)

LoadSource loads the source configured for a generator.

func SafeOutputRoot 

func SafeOutputRoot(root string) (string, error)

SafeOutputRoot validates a root that may be cleaned.

func SafeRelativePath 

func SafeRelativePath(path string) (string, error)

SafeRelativePath validates a generated path.

func WriteFiles 

func WriteFiles(files *FileSet, opts WriteOptions) error

WriteFiles writes generated files and records a manifest for future cleans.

Types

type CodegenConfig 

type CodegenConfig struct {
	Output     string            `json:"output"`
	Clean      *bool             `json:"clean,omitempty"`
	Generators []GeneratorConfig `json:"generators,omitempty"`
	Extensions []ExtensionConfig `json:"extensions,omitempty"`
}

CodegenConfig configures one generator run.

type Config 

type Config struct {
	Version int           `json:"version"`
	Codegen CodegenConfig `json:"codegen"`
}

Config is the top-level YAML code generation configuration.

func DecodeConfig 

func DecodeConfig(node *coreyaml.Node) (Config, error)

DecodeConfig decodes a parsed YAML node into Config.

func LoadConfig 

func LoadConfig(path string) (Config, error)

LoadConfig reads and validates a YAML codegen configuration file.

type Context 

type Context struct {
	ProjectDir  string
	Config      Config
	Metadata    map[string]any
	Inputs      map[string]any
	Files       *FileSet
	Diagnostics []Diagnostic
}

Context is the shared generation context passed to generators/extensions.

type Diagnostic 

type Diagnostic struct {
	Severity string `json:"severity"`
	Message  string `json:"message"`
}

Diagnostic is a machine-readable message produced during generation.

type Discovery 

type Discovery struct {
	Path       string
	ProjectDir string
	Config     Config
	Found      bool
}

Discovery is the result of looking for a codegen configuration file.

func DiscoverConfig 

func DiscoverConfig(projectDir string) (Discovery, error)

DiscoverConfig finds the project codegen config. Dedicated codegen config files win; gofastr.yml is only considered when it has a codegen section.

type Extension 

type Extension interface {
	Name() string
	RunPhase(ctx context.Context, phase string, genCtx *Context, gen GeneratorConfig, ext ExtensionConfig) (ExtensionResponse, error)
}

Extension participates in code generation through named phases.

func NewCommandExtension 

func NewCommandExtension(name string, command []string, stderrWriter io.Writer) Extension

NewCommandExtension creates an Extension backed by an external command.

type ExtensionConfig 

type ExtensionConfig struct {
	Name    string         `json:"name"`
	Command []string       `json:"command,omitempty"`
	Config  map[string]any `json:"config,omitempty"`
}

ExtensionConfig describes an extension process or in-process extension.

type ExtensionRequest 

type ExtensionRequest struct {
	ProtocolVersion int             `json:"protocol_version"`
	Phase           string          `json:"phase"`
	ProjectDir      string          `json:"project_dir"`
	Generator       GeneratorConfig `json:"generator"`
	Extension       ExtensionConfig `json:"extension"`
	Source          any             `json:"source,omitempty"`
	Metadata        map[string]any  `json:"metadata,omitempty"`
	Files           []GeneratedFile `json:"files,omitempty"`
}

ExtensionRequest is the JSON payload sent to external command extensions.

type ExtensionResponse 

type ExtensionResponse struct {
	ProtocolVersion int             `json:"protocol_version,omitempty"`
	Diagnostics     []Diagnostic    `json:"diagnostics,omitempty"`
	Files           []GeneratedFile `json:"files,omitempty"`
	Deletes         []string        `json:"deletes,omitempty"`
}

ExtensionResponse is the JSON payload returned by extensions.

type FileSet 

type FileSet struct {
	// contains filtered or unexported fields
}

FileSet stores pending generated files and rejects silent collisions.

func NewFileSet 

func NewFileSet() *FileSet

NewFileSet creates an empty pending generated-file collection.

func (*FileSet) Add 

func (fs *FileSet) Add(file GeneratedFile) error

Add inserts one pending generated file and rejects path/content collisions.

func (*FileSet) All 

func (fs *FileSet) All() []GeneratedFile

All returns pending files in stable path order.

func (*FileSet) Delete 

func (fs *FileSet) Delete(path string) error

Delete removes a pending generated file by relative path.

func (*FileSet) DeleteOwned 

func (fs *FileSet) DeleteOwned(path, owner string) error

DeleteOwned removes a pending generated file only if it is owned by owner.

type GeneratedFile 

type GeneratedFile struct {
	Path    string `json:"path"`
	Content string `json:"content"`
	Owner   string `json:"owner,omitempty"`
}

GeneratedFile is a pending file produced by a generator or extension.

type Generator 

type Generator interface {
	Name() string
	Generate(ctx context.Context, genCtx *Context, cfg GeneratorConfig) ([]GeneratedFile, error)
}

Generator emits files for one configured generator entry.

type GeneratorConfig 

type GeneratorConfig struct {
	ID        string         `json:"id,omitempty"`
	Name      string         `json:"name"`
	Extension string         `json:"extension,omitempty"`
	Source    SourceConfig   `json:"source,omitempty"`
	Output    string         `json:"output,omitempty"`
	Config    map[string]any `json:"config,omitempty"`
}

GeneratorConfig configures one generator invocation.

type JSONDocument 

type JSONDocument struct {
	Path string `json:"path"`
	Data any    `json:"data"`
}

JSONDocument is one JSON file loaded by a json_dir source.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds available in-process generators and extensions.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates an empty generator/extension registry.

func (*Registry) RegisterCommandExtensions 

func (r *Registry) RegisterCommandExtensions(cfg CodegenConfig, stderrWriter io.Writer) error

RegisterCommandExtensions registers command-backed extensions from config.

func (*Registry) RegisterExtension 

func (r *Registry) RegisterExtension(ext Extension) error

RegisterExtension adds one in-process extension by name.

func (*Registry) RegisterGenerator 

func (r *Registry) RegisterGenerator(gen Generator) error

RegisterGenerator adds one in-process generator by name.

func (*Registry) Run 

func (r *Registry) Run(ctx context.Context, projectDir string, cfg Config) (*Context, error)

Run executes every configured generator and extension into one FileSet.

type SourceConfig 

type SourceConfig struct {
	Type   string         `json:"type,omitempty"`
	Path   string         `json:"path,omitempty"`
	Config map[string]any `json:"config,omitempty"`
}

SourceConfig describes structured input consumed by a generator.

type WriteOptions 

type WriteOptions struct {
	OutputRoot   string
	Clean        bool
	SkipManifest bool
}

WriteOptions controls writing a FileSet to disk.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.