api

type Api interface {
	// Obtain the list of available generator names by looking for generator-*.yaml files in sourceBaseDir
	FindGeneratorNames(ctx context.Context, sourceBaseDir string) ([]string, error)

	// Obtain a specific generator spec, read from "generator-<generatorName>.yaml" in sourceBaseDir
	ObtainGeneratorSpec(ctx context.Context, sourceBaseDir string, generatorName string) (*GeneratorSpec, error)

	// Write a fresh RenderSpec with defaults set from the GeneratorSpec for the given generator
	//
	// The name of the output file can be set in request.RenderSpecFile, but if left empty, it defaults to
	// "generated-<generatorName>.yaml".
	//
	// Warning: if the file exists, it is silently overwritten! The idea is that you keep both your
	// generators and the generator targets in source control, so you can then review the changes made.
	WriteRenderSpecWithDefaults(ctx context.Context, request *Request, generatorName string) *Response

	// Write a RenderSpec file with the provided parameter values
	//
	// The name of the output file can be set in request.RenderSpecFile, but if left empty, it defaults to
	// "generated-<generatorName>.yaml".
	//
	// Warning: if the file exists, it is silently overwritten! The idea is that you keep both your
	// generators and the generator targets in source control, so you can then review the changes made.
	WriteRenderSpecWithValues(ctx context.Context, request *Request, generatorName string, parameters map[string]interface{}) *Response

	// Render files from templates according to RenderSpec and the GeneratorSpec it references.
	//
	// First the RenderSpec is read from <request.TargetBaseDir>/<request.RenderSpecFile>".
	// This tells the generator everything it needs to read the GeneratorSpec and execute it.
	//
	// If you leave request.RenderSpecFile empty, it defaults to "generated-main.yaml"
	//
	// Warning: existing files are silently overwritten! The idea is that you keep both your
	// generators and the generator targets in source control, so you can then review the changes made.
	Render(ctx context.Context, request *Request) *Response
}

type FileResult struct {
	Success          bool
	RelativeFilePath string
	Errors           []error
}

type GeneratorSpec struct {
	// The list of templates to render (if their condition evaluates to true)
	Templates []TemplateSpec `yaml:"templates"`

	// The list of available variables
	Variables map[string]VariableSpec `yaml:"variables"`
}

type RenderSpec struct {
	// Name of the generator to use (determines yaml file to read for generator spec). The main one should be called
	// generator-main.yaml, and GeneratorName should be set to "main".
	GeneratorName string `yaml:"generator"`

	// Assign variable "key" value "value". All values are evaluated as templates until they no longer change,
	// so the value of one variable can refer to other variables, even if using their default values.
	Parameters map[string]interface{} `yaml:"parameters"`
}

type Request struct {
	// Directory where to find e.g. 'main.yaml' describing the generator. Required.
	SourceBaseDir string `yaml:"sourcedir"`

	// Directory where to find 'generator-main.yaml' specifying values and the generator to use. Required.
	TargetBaseDir string `yaml:"targetdir"`

	// yaml-file to read for RenderSpec, if not set, defaults to "generated-main.yaml".
	RenderSpecFile string `yaml:"renderspec"`
}

type Response struct {
	Success       bool
	RenderedFiles []FileResult
	Errors        []error
}

type TemplateSpec struct {
	RelativeSourcePath string        `yaml:"source"`
	RelativeTargetPath string        `yaml:"target"`
	Condition          string        `yaml:"condition"`
	WithItems          []interface{} `yaml:"with_items"`
	WithFiles          []string      `yaml:"with_files"`
	JustCopy           bool          `yaml:"just_copy"`
}

type VariableSpec struct {
	// Human readable description for the variable.
	Description string `yaml:"description"`

	// Regex validation pattern that the string representation (%v) of the value must match. No validation if left empty.
	ValidationPattern string `yaml:"pattern"`

	// Default value. If missing, the variable is considered required. Note that variables can have structured content.
	DefaultValue interface{} `yaml:"default"`
}