Documentation
¶
Overview ¶
Package capability recognizes what a pipeline job does from the facts the CLI already parsed (the job's image, the include that defined it, its report artifacts, its script lines) and from the wrapper scripts it calls in the checkout. A capability is a name a user declares, or the CLI's built-in list does (builtin.yaml), with glob recognizers over seven subjects (spec 4.2, 4.3); the platform's dependencies graph lists the result as the `capability` resource kind ("which projects run secret detection").
Index ¶
- Constants
- func BuiltinYAML() []byte
- func Validate(decls []Declaration) error
- type Compiled
- type CompiledField
- type CompiledPattern
- type CompiledRecognizer
- type Declaration
- func Builtin() []Declaration
- func DecodeJSON(data []byte) ([]Declaration, error)
- func DecodeYAML(data []byte) ([]Declaration, error)
- func Effective(user []Declaration) []Declaration
- func FromFile(raw interface{}, l *logrus.Entry) []Declaration
- func PruneEmptyRecognizers(decls []Declaration, dropped func(capability string, index int)) []Declaration
- type Match
Constants ¶
const ( EvidenceImages = "images" EvidenceGitlabIncludeTemplate = "gitlab_include_template" EvidenceGitlabIncludeComponent = "gitlab_include_component" EvidenceGitlabIncludeProject = "gitlab_include_project" EvidenceGitlabReportTypes = "gitlab_report_types" EvidenceCommands = "commands" EvidenceWrapperScript = "wrapper_script" )
The evidence a match rests on: the name of the recognizer field that matched (spec 4.4), listed in the precedence order a recognizer's fields are tried in (spec 4.3).
Variables ¶
This section is empty.
Functions ¶
func BuiltinYAML ¶
func BuiltinYAML() []byte
BuiltinYAML returns the embedded builtin.yaml bytes, copied so a caller can never alter the list the CLI runs: what `plumber capabilities defaults` prints verbatim (spec 4.2).
func Validate ¶
func Validate(decls []Declaration) error
Validate re-exports capdecl.Validate: the bounds of spec 4.2 (list count, name grammar, uniqueness, recognizer count, at least one pattern, tool bytes, per-field pattern count, per-pattern bytes), returning one error naming the first violation. It never checks glob syntax: that is Compile's business (it skips and warns).
Types ¶
type Compiled ¶
type Compiled struct {
Name string
Recognizers []CompiledRecognizer
}
Compiled is one declaration ready for matching: its name and its recognizers, compiled.
func Compile ¶
func Compile(decls []Declaration, warn func(string)) []Compiled
Compile compiles decls' patterns to capdecl.Glob, keeping the source text of each. A pattern that does not compile as a plain glob is skipped and, when warn is not nil, reported once through warn naming the capability, the recognizer's tool (or its declared order when the recognizer named no tool), the field and the pattern (spec 4.3: "a pattern that does not compile is refused at PUT and, from .plumber.yaml, skipped with one warning line"). wrapper_script is not a declared field: its patterns are the recognizer's compiled commands, since spec 4.3 matches a wrapper script's lines against the recognizer's commands, not against a field of its own.
type CompiledField ¶
type CompiledField struct {
Name string
Patterns []CompiledPattern
}
CompiledField is one evidence field of a compiled recognizer: its name (the bill's evidence vocabulary, spec 4.4) and its patterns. A pattern that failed to compile as a glob is never here: Compile already skipped it and warned once.
type CompiledPattern ¶
CompiledPattern is one glob pattern, compiled, with its source text kept: the tool fallback needs it (spec 4.3, "the recognizer's tool when declared, else the pattern that matched") and so does a later warning that names the pattern. The matcher is capdecl.Glob, bounded by len(subject) * len(pattern) whatever the pattern.
type CompiledRecognizer ¶
type CompiledRecognizer struct {
Tool string
Fields [7]CompiledField
}
CompiledRecognizer is one compiled recognizer: the declared tool (empty when the recognizer did not name one, in which case the matched pattern names the tool on the edge, spec 4.3) and its seven evidence fields, in the precedence order a matcher tries them in (spec 4.3): images, gitlab_include_template, gitlab_include_component, gitlab_include_project, gitlab_report_types, commands, wrapper_script.
type Declaration ¶
type Declaration = capdecl.Declaration
Declaration re-exports capdecl.Declaration: the type a user capability, or the CLI's own built-in one, is written in (spec 4.2). It is declared here as a type alias, not a new type, so capability.Declaration and capdecl.Declaration stay interchangeable. The schema lives in the leaf package capdecl because capability imports gitlab (for the wrapper-script read of recognize.go) and gitlab imports configuration: a schema here could never be named by configuration. configuration keeps the .plumber.yaml key raw (PlumberConfig.Capabilities) and the provider decodes it through DecodeYAML below.
The declaration's Recognizer type is not re-exported: code in this package that names it explicitly (rather than through a Declaration's Recognizers field) spells it out as capdecl.Recognizer, and the compiled form a matcher reads is CompiledRecognizer.
func Builtin ¶
func Builtin() []Declaration
Builtin returns the CLI's built-in capability list, decoded once and deep-copied on every call so a caller mutating the result never affects another caller or a later call (spec 4.2). It panics if the embedded builtin.yaml fails to decode: that can only happen if a change to builtin.yaml breaks its own schema, a build-time bug this test suite catches before it ships.
func DecodeJSON ¶
func DecodeJSON(data []byte) ([]Declaration, error)
DecodeJSON re-exports capdecl.DecodeJSON: a tolerant decode of a bare JSON array of declarations (the org setting, served through /context), ignoring an unknown key so a field a newer platform serves never drops the fields the CLI knows (spec 4.6).
func DecodeYAML ¶
func DecodeYAML(data []byte) ([]Declaration, error)
DecodeYAML re-exports capdecl.DecodeYAML: a strict decode of a `capabilities:` YAML document (.plumber.yaml, the CLI's built-in list), refusing an unknown key by name.
func Effective ¶
func Effective(user []Declaration) []Declaration
Effective returns the effective capability list a run uses: the user list first, in its own order, then every built-in capability whose name the user list does not declare (spec 4.2). A user declaration that names a built-in replaces it whole: there is no merge of recognizers inside one name, so a user can narrow a built-in like secret_detection to their own tool alone. A nil or empty user list yields Builtin() unchanged.
func FromFile ¶
func FromFile(raw interface{}, l *logrus.Entry) []Declaration
FromFile decodes a .plumber.yaml `capabilities:` key the strict way (DecodeYAML) and checks its bounds (Validate): the one step the provider (CapabilitiesOf) and `config view` both run on the file's raw value, so the two can never read the key differently (spec 4.2, 4.6). raw is the PlumberConfig.Capabilities field exactly as the YAML loader left it. Nil raw (no capabilities key in the file) is nil, no warning. A decode or validation failure logs the one-line warning both callers show through l, naming the error, and returns nil so the caller falls back to the built-in list alone.
func PruneEmptyRecognizers ¶
func PruneEmptyRecognizers(decls []Declaration, dropped func(capability string, index int)) []Declaration
PruneEmptyRecognizers re-exports capdecl.PruneEmptyRecognizers: for the served list, after DecodeJSON and before Validate, it drops every recognizer with no pattern in the fields this CLI knows (one that only carried a field of a newer platform), reporting each through dropped; a capability left with none keeps its name (spec 4.2 and 4.6).
type Match ¶
type Match struct {
Kind string `json:"kind"`
Job string `json:"job"`
Tool string `json:"tool"`
Evidence string `json:"evidence"`
}
Match is one recognized capability of one job: the capability's name, the job, the tool (the recognizer's declared tool, else the pattern that matched) and the evidence (the name of the field that matched).
func Recognize ¶
func Recognize(pipe *ir.NormalizedPipeline, repoRoot string, decls []Compiled) []Match
Recognize returns one Match per (job, capability) over pipe (spec 4.3), sorted by job then kind. Hidden jobs (a dot-prefixed name) are skipped. For each capability, its recognizers are tried in list order, each recognizer's fields in their precedence order (images, gitlab_include_template, gitlab_include_component, gitlab_include_project, gitlab_report_types, commands, wrapper_script) and each field's patterns in order against the field's subjects; the first hit names the tool (the recognizer's, else the pattern's text) and the evidence (the field's name). repoRoot is the checkout root wrapper scripts are read under; the caller passes it only when the checkout is the analyzed project at its ref, and an empty root turns the wrapper_script subject off. A nil pipeline or an empty list yields nil.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
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).
|
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). |