ast

Documentation

Overview

Package ast implements AST-based code injection for lin v2.

The injector locates insertion points purely from Go AST structure (interface names, struct receivers, top-level functions) — there are no comment markers or anchor regions involved.

Design source: lin/docs/features/05-registration-strategy.md.

Index

• func AddInterfaceMethod(file string, p InterfacePayload) error
• func AddProtoImport(file string, p ProtoPayload) error
• func AppendRegistration(file string, p RegisterPayload) error
• func BackupFile(rootDir, relPath, ts string) (string, error)
• func CleanupBackup(rootDir, ts string) error
• func NewTimestamp() string
• func ParseFile(path string) (*dst.File, error)
• func ParseFileWithDecorator(src []byte) (*dst.File, *decorator.Decorator, error)
• func RestoreFromBackup(backupPath, originalPath string) error
• func WriteFile(path string, f *dst.File) error
• type InjectPlan
• type InjectSpec
• type Injector
  • func NewInjector(rootDir string) *Injector
  • func (inj *Injector) Inject(plan InjectPlan) error
  • func (inj *Injector) Restore() error
• type InterfacePayload
• type MutatorKind
• type ProtoPayload
• type RegisterPayload

Functions

func AddInterfaceMethod

func AddInterfaceMethod(file string, p InterfacePayload) error

AddInterfaceMethod injects a method into a Go interface and adds a corresponding receiver method, with proper import. Idempotent.

All insertion points are computed from AST structure:

• Interface method → appended to *dst.InterfaceType.Methods.List of InterfaceName.
• Receiver method → appended to f.Decls (top-level decls).
• Import → prepended to the first import GenDecl, or a new one if absent.

func AddProtoImport

func AddProtoImport(file string, p ProtoPayload) error

AddProtoImport inserts an import statement into a .proto file. Idempotent: skips if the import already exists.

func AppendRegistration

func AppendRegistration(file string, p RegisterPayload) error

AppendRegistration appends a call statement to the Body of FunctionName. Idempotent: if the same statement is already present in the Body, returns nil.

func BackupFile

func BackupFile(rootDir, relPath, ts string) (string, error)

BackupFile copies src (relative to rootDir) into the user-level backup cache: <projectBackupBase>/<ts>/<rel>. Returns the backup path.

func CleanupBackup

func CleanupBackup(rootDir, ts string) error

CleanupBackup removes the backup directory for a given timestamp. Also prunes oldest backups keeping only the 3 most recent.

func NewTimestamp

func NewTimestamp() string

NewTimestamp returns a timestamp string suitable for backup directory names.

func ParseFile

func ParseFile(path string) (*dst.File, error)

ParseFile parses a Go source file into a dst.File.

func ParseFileWithDecorator

func ParseFileWithDecorator(src []byte) (*dst.File, *decorator.Decorator, error)

ParseFileWithDecorator parses a Go file using the dst decorator (exported for testing).

func RestoreFromBackup

func RestoreFromBackup(backupPath, originalPath string) error

RestoreFromBackup copies backupPath back to originalPath.

func WriteFile

func WriteFile(path string, f *dst.File) error

WriteFile serialises a dst.File back to the given path.

Types

type InjectPlan

type InjectPlan struct {
	Specs []InjectSpec
}

InjectPlan groups all injection specs for one operation.

type InjectSpec

type InjectSpec struct {
	File    string
	Mutator MutatorKind
	Payload any
}

InjectSpec describes a single AST injection.

type Injector

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

Injector orchestrates backup, mutation, and rollback of central files.

func NewInjector

func NewInjector(rootDir string) *Injector

NewInjector creates an Injector for the given project root.

func (*Injector) Inject

func (inj *Injector) Inject(plan InjectPlan) error

Inject executes all InjectSpecs in plan.Specs.

Algorithm:

1. Backup all target files.
2. Execute each mutator in order.
3. On any failure, restore all backed-up files and return a wrapped error.
4. On success, clean up the backup directory.

func (*Injector) Restore

func (inj *Injector) Restore() error

Restore restores all backed-up files to their original paths.

type InterfacePayload

type InterfacePayload struct {
	// InterfaceName is the name of the interface type (e.g. "IBiz").
	InterfaceName string
	// StructName is the receiver type (e.g. "biz").
	StructName string

	// Method is the method name to add (e.g. "PostV1").
	Method string
	// ReturnType is the return type string (e.g. "postv1.PostBiz").
	ReturnType string

	// ImportAlias and ImportPath form the import to add (optional).
	ImportAlias string
	ImportPath  string

	// ImplBody is the function body expression (e.g. "return postv1.New(b.store)").
	// When empty, an empty body is emitted.
	ImplBody string
}

InterfacePayload carries parameters for AddInterfaceMethod.

Insertion locations are derived purely from Go AST structure (interface name, receiver struct name) — no anchor comments are required.

type MutatorKind

type MutatorKind string

MutatorKind identifies the AST mutator type.

const (
	MutatorKindInterface MutatorKind = "interface"
	MutatorKindProto     MutatorKind = "proto"
	MutatorKindRegister  MutatorKind = "register"
)

type ProtoPayload

type ProtoPayload struct {
	// File is the path to the .proto file to modify (overwritten by the caller).
	File string
	// Import is the import string to add (e.g. "post.proto").
	Import string
}

ProtoPayload carries parameters for AddProtoImport.

Insertion is purely structural: the target import is placed inside the existing import block (sorted-aware), or directly after the package/option header lines when no imports exist yet. No anchor comments are used.

type RegisterPayload

type RegisterPayload struct {
	// FunctionName is the top-level function whose body will receive the
	// new statement (e.g. "RegisterAll").
	FunctionName string
	// Statement is the call expression to append, written as a Go expression
	// such as "RegisterErrors(PostErrors()...)".
	Statement string
}

RegisterPayload carries parameters for AppendRegistration.

The insertion target is the Body of the top-level function FunctionName. No anchor comments are required.