codegen

type RenderOptions struct {
	// TemplateName is the named template invoked from the parsed Templates set.
	TemplateName string
	// Templates is a parsed *template.Template containing TemplateName plus
	// any templates it references (e.g. via {{template "header" .}}).
	Templates *template.Template
	// Data is bound to the template's "." context.
	Data any
	// Filename is the absolute path of the file being rendered. goimports
	// uses it to resolve module-local imports. Empty filenames disable
	// path-aware import resolution.
	Filename string
}

type VerifyResult struct {
	// Drifted lists the relative paths whose disk content differs from the
	// freshly-generated content (per `git status --porcelain`). Empty when
	// the worktree is clean after running the generator.
	Drifted []string
	// DiffSummary is the truncated `git diff` output for the drifted files,
	// suitable for printing to CI logs. Empty when Drifted is empty.
	DiffSummary string
}

type WriteAction string

type WriteOptions struct {
	// Path is the absolute target file path.
	Path string
	// Content is the bytes to compare against / write to the target.
	Content []byte
	// RepoRoot gates Path through fspath.IsWithinRoot to reject path
	// traversal. Must be non-empty (the output of pathsafe.ResolveRoot);
	// Write returns an error immediately if RepoRoot is empty.
	RepoRoot string
	// DryRun suppresses the filesystem mutation and returns ActionWouldWrite
	// (or ActionUnchanged when content matches).
	DryRun bool
	// Verify suppresses the filesystem mutation and returns ActionDrifted
	// (or ActionUnchanged) by comparing Content with the on-disk file.
	// DryRun and Verify are mutually exclusive at the CLI layer; combining
	// them here is harmless — Verify dominates (no write either way).
	Verify bool
	// Headerless opts out of the "existing file must carry the gocell
	// generated header" guard. Reserved exclusively for artifacts that
	// cannot carry a Go-style line comment (e.g. JSON schema files).
	// When true, Write will overwrite any existing file without checking
	// for the generated header; the within-root and Action state-machine
	// invariants are unaffected.
	//
	// Caller allowlist: only tools/codegen/sharedschema may set this field.
	// Enforced by archtest SHARED-SCHEMA-MIRROR-FUNNEL-01 A2.
	Headerless bool
}

type WriteResult struct {
	Action WriteAction
	Path   string
}