Documentation
¶
Overview ¶
Package capdecl holds the pipeline capability declaration schema: the types a user (or the CLI's own built-in list) writes a capability in, their strict decode from YAML and tolerant decode from JSON, the bounds that make a declared list safe to compile and to store, and the bounded glob matcher its patterns compile to (spec sections 4.2, 4.3 and 4.6 of the pipeline capabilities design, revised 2026-10-17, in the Plumber monorepo).
This package is a leaf: it imports nothing from this module. The capability package (which recognizes capabilities over a parsed pipeline and so imports gitlab, for the wrapper-script read) re-exports Declaration and these functions, and keeping the schema in a leaf leaves it importable from anywhere in the module without a cycle (capability -> gitlab -> configuration).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Validate ¶
func Validate(decls []Declaration) error
Validate checks decls against the bounds of spec 4.2, in the order of the spec's sentences: list count, name grammar, name uniqueness, recognizer count, at least one pattern per recognizer, tool bounds, per-field pattern count, per-pattern bounds. It returns one error naming the first violation, using the fixed sentences spec 4.6 gives the platform's own 422 body, so the same wording reaches a user from the file or from the setting. It never checks glob syntax: that is Compile's business (it skips and warns).
Types ¶
type Declaration ¶
type Declaration struct {
Name string `yaml:"name" json:"name"`
Recognizers []Recognizer `yaml:"recognizers" json:"recognizers"`
}
Declaration names one capability ("this job does X") and the recognizers that reveal it. The same shape is written in .plumber.yaml (YAML), the CLI's built-in list (YAML) and the org setting served through /context (JSON).
func DecodeJSON ¶
func DecodeJSON(data []byte) ([]Declaration, error)
DecodeJSON decodes a bare JSON array of declarations (the org setting, served through /context) into a declaration list, tolerantly: an unknown key is ignored. The platform refused unknown keys at PUT already, so one the CLI does not know comes from a platform newer than the CLI (a recognizer field added later): the CLI keeps the fields it knows rather than dropping the whole list (spec 4.6). The caller validates the result (Validate). The strict decode is DecodeYAML's, for the file a user types.
func DecodeYAML ¶
func DecodeYAML(data []byte) ([]Declaration, error)
DecodeYAML strictly decodes a `capabilities:` YAML document (.plumber.yaml, the CLI's built-in list) into a declaration list. An unknown key, at any level, is refused by name (yaml.UnmarshalStrict), so a typo never silently disables a recognizer (spec 4.2).
func PruneEmptyRecognizers ¶
func PruneEmptyRecognizers(decls []Declaration, dropped func(capability string, index int)) []Declaration
PruneEmptyRecognizers drops every recognizer that carries no pattern in the fields this CLI knows, calling dropped with the capability's name and the recognizer's index in the declared list for each one. It is for the served list only, after DecodeJSON and before Validate (spec 4.6): a recognizer the platform accepted with only a field of a platform newer than this CLI (a future github_actions) decodes here with zero patterns, and Validate would otherwise refuse the whole org list. A capability left with no recognizer keeps its name, which is the disable gesture (spec 4.2). The input is not modified.
type Glob ¶
type Glob struct {
// contains filtered or unexported fields
}
Glob is one compiled capability pattern (spec 4.3): `*` matches any run of characters, a `/` included; `?` exactly one character; `[...]` one character of a class with ranges (`[a-z]`), negated by a leading `!` or `^`, a `]` first in the class (after the negation) being a literal; `\x` the character x; every other character itself. Matching is case-sensitive and on the whole subject. A character is a rune: subject and pattern are read as UTF-8 throughout.
The matcher is the iterative wildcard algorithm with one remembered star (on a mismatch, resume one character further past the last star), with no recursion: a match costs at most len(subject) * len(pattern) steps whatever the pattern. A pattern is the user's and a subject any developer's script line, so a backtracking matcher (exponential on patterns such as `*b*a*a*`) would let a pattern and a line hang the run.
func CompileGlob ¶
CompileGlob compiles pattern, refusing an unclosed class (`[abc`, `[]`, `[!]`) and a trailing backslash. Inside a class a backslash is a literal: the class runs to the first `]` after its optional negation and optional leading `]`, exactly as ValidGlob scans it.
type Recognizer ¶
type Recognizer struct {
Tool string `yaml:"tool,omitempty" json:"tool,omitempty"`
Images []string `yaml:"images,omitempty" json:"images,omitempty"`
Commands []string `yaml:"commands,omitempty" json:"commands,omitempty"`
GitlabReportTypes []string `yaml:"gitlab_report_types,omitempty" json:"gitlab_report_types,omitempty"`
GitlabIncludeTemplate []string `yaml:"gitlab_include_template,omitempty" json:"gitlab_include_template,omitempty"`
GitlabIncludeComponent []string `yaml:"gitlab_include_component,omitempty" json:"gitlab_include_component,omitempty"`
GitlabIncludeProject []string `yaml:"gitlab_include_project,omitempty" json:"gitlab_include_project,omitempty"`
}
Recognizer is a set of pattern lists that reveal one tool. A field is provider-neutral (Images, Commands) or GitLab-prefixed (GitlabReportTypes, GitlabIncludeTemplate, GitlabIncludeComponent, GitlabIncludeProject); each is optional, but a recognizer carries at least one pattern across them (Validate checks this). Tool is optional; when absent the matched pattern names the tool on the edge (spec 4.3).
Source Files