Documentation
¶
Overview ¶
Package formats decodes task definitions from YAML, JSON and TOML into the taskrun data model, and converts legacy Kite task maps.
The package performs no execution: it never starts a process, never calls a handler and never evaluates a dynamic variable command. Decoding records the source name, base directory and field path of every error, and a definition is only returned after the whole document validates.
Discovery of task files is always explicit: the caller supplies the start directory, the file names and the extension order. Nothing is read from parent directories or the network by default.
Index ¶
- Constants
- Variables
- func Discover(opts DiscoverOptions) ([]string, error)
- func DiscoverAndLoad(opts DiscoverOptions, override bool) (taskrun.Definition, error)
- func LegacyMap(scripts map[string]any, baseDir string) (taskrun.Definition, error)
- func Load(ext string, reader io.Reader, source, baseDir string) (taskrun.Definition, error)
- func LoadFile(path string) (taskrun.Definition, error)
- func LoadFiles(paths []string, override bool) (taskrun.Definition, error)
- func Merge(defs []taskrun.Definition, override bool) (taskrun.Definition, error)
- func SplitCommandLine(line string) (string, []string, error)
- type DiscoverMode
- type DiscoverOptions
- type LegacyOptions
- type LegacyResult
- type LegacyScriptFile
Constants ¶
const ( FormatJSON = "json" FormatYAML = "yaml" FormatTOML = "toml" )
Format names accepted by Load.
Variables ¶
var DefaultExtensions = []string{".yaml", ".yml", ".json", ".toml"}
DefaultExtensions is the extension order used when Extensions is empty.
Functions ¶
func Discover ¶
func Discover(opts DiscoverOptions) ([]string, error)
Discover returns the task files selected by the options. Files are returned in load order: a single nearest file, or root to nearest for ancestors.
func DiscoverAndLoad ¶
func DiscoverAndLoad(opts DiscoverOptions, override bool) (taskrun.Definition, error)
DiscoverAndLoad discovers files and merges them in load order.
func Load ¶
Load decodes one document. baseDir must be an absolute directory: relative script paths resolve against it and the value is recorded as the source base directory.
func LoadFile ¶
func LoadFile(path string) (taskrun.Definition, error)
LoadFile decodes a file, using its extension to select the format. The directory of path becomes the absolute source base directory.
func LoadFiles ¶
func LoadFiles(paths []string, override bool) (taskrun.Definition, error)
LoadFiles decodes and merges several sources in order. Task name conflicts are an error unless override is true, in which case the later definition replaces the whole task. Variables and environment defaults are always overridden by key.
func Merge ¶
func Merge(defs []taskrun.Definition, override bool) (taskrun.Definition, error)
Merge combines decoded definitions in input order.
func SplitCommandLine ¶
SplitCommandLine splits a legacy command line into a program and its arguments using shell style quoting. The library never splits an exec argument itself; this helper exists for the Kite compatibility layer, which maps legacy "program arg arg" strings onto structured argv.
Types ¶
type DiscoverMode ¶
type DiscoverMode string
DiscoverMode selects how far discovery walks.
const ( // Nearest stops at the first directory level that has a match. It is the // default when Mode is empty. Nearest DiscoverMode = "nearest" // Ancestors collects at most one file per level, from the root down to the // start directory, so closer files override earlier ones when merged. Ancestors DiscoverMode = "ancestors" )
type DiscoverOptions ¶
type DiscoverOptions struct {
Mode DiscoverMode
// Names are file base names without extension, for example ".kite.task".
Names []string
// Extensions is the preferred extension order, for example [".yaml",".json"].
Extensions []string
// StartDir is the absolute directory the search starts at.
StartDir string
// StopDir stops the walk when it reaches this absolute directory.
StopDir string
// MaxDepth limits how many levels are inspected. Zero means no limit beyond
// the stop directory or the filesystem root.
MaxDepth int
}
DiscoverOptions configures explicit discovery. There is no implicit search: Names and StartDir are required and nothing outside the described levels is read.
type LegacyOptions ¶
type LegacyOptions struct {
// Scripts is the legacy task map, including an optional "__settings" entry.
Scripts map[string]any
// Settings is an already extracted "__settings" map. It is merged over the
// one found inside Scripts.
Settings map[string]any
// BaseDir is the absolute directory of the source configuration.
BaseDir string
// DefaultShell is the legacy runner TypeShell value, for example "sh".
DefaultShell string
// RuntimeVars lists the names the Kite adapter injects at run time
// (ctx.Vars keys, gvs, paths, kite, time, workdir, dirname and so on).
// Only these names are rewritten from legacy $name/${name} into the
// namespaced ${vars.name} form; anything else is left untouched.
RuntimeVars []string
// EnvNames lists environment variable names that the legacy renderer
// substituted through its ParseEnv option. A bare $NAME reference to one of
// them becomes ${env.NAME}. Variable names take precedence, matching the
// legacy lookup order.
EnvNames []string
// Files are script files discovered from ScriptDirs.
Files map[string]LegacyScriptFile
}
LegacyOptions configures the conversion of a historical Kite task map. The converter is the only place that understands Kite private syntax: command aliases, extensions, plugins and system command fallback stay in Kite.
type LegacyResult ¶
type LegacyResult struct {
Definition taskrun.Definition
Warnings []string
}
LegacyResult carries the converted definition and the conversion warnings. A warning records behavior that the new model does not own, such as command aliases or plugin support, so the Kite adapter can report it instead of silently dropping semantics.
func LegacyDefinition ¶
func LegacyDefinition(opts LegacyOptions) (LegacyResult, error)
LegacyDefinition converts legacy Kite task definitions into the current model.
type LegacyScriptFile ¶
type LegacyScriptFile struct {
// Path is the file path, absolute or relative to BaseDir.
Path string
// Ext is the file extension including the dot, for example ".go".
Ext string
// Bin is the interpreter from ExtToBinMap; it may contain arguments. When
// empty the extension without the dot is used, matching the legacy
// BinName default.
Bin string
}
LegacyScriptFile describes a script file discovered by the caller.
Source Files