Documentation
¶
Overview ¶
Package pipeline orchestrates the phases (discover -> parse -> validate -> prepare -> execute -> report) and defines the Executor, Mode, and Reporter seams.
Index ¶
- Variables
- func Scan(ctx context.Context, roots []string, opts ...Option) ([]scan.File, int, error)
- type FileResult
- type Marker
- type Option
- func WithConfig(r *config.Resolver) Option
- func WithDeep(deep *bool) Option
- func WithDowngrade(allow *bool) Option
- func WithForce(force *bool) Option
- func WithIgnoreFiles(names ...string) Option
- func WithMaxSize(n int64) Option
- func WithNoIgnore(on bool) Option
- func WithNow(t time.Time) Option
- func WithPrerelease(allow *bool) Option
- func WithReporter(r progress.Reporter) Option
- func WithRequireDirective(on bool) Option
- func WithScanLabel(label string) Option
- func WithTagFilter(filter tag.Filter) Option
- func WithTruncationSink(sink func(provider.Truncation)) Option
- func WithVerify(on *bool) Option
- func WithVersion(current string) Option
- func WithWorkers(n int) Option
- type Result
Constants ¶
This section is empty.
Variables ¶
var ErrNoCandidate = errors.New("no candidate satisfies the rule")
ErrNoCandidate reports that no discovered version satisfied the marker's rule (constraint, include/exclude, prerelease). The edge checks for it to suggest a deep lookup, since a shallow lookup may have paged past a matching version.
Functions ¶
func Scan ¶
Scan walks roots offline - honouring ignore files, never resolving - and returns the files that carry a directive, alongside the total number of files examined. It is the front half Run and Validate build on, exposed for format and annotate, which rewrite directive comments without ever binding markers or touching the network.
Types ¶
type FileResult ¶
FileResult groups a scanned file's original lines with the results of every marker it carries, in line order. Lines is the content as read; Rewritten applies the changed results to produce the new content.
func Run ¶
Run scans roots for directives, resolves every marker it finds against its provider (or the marker it follows), and renders the resolved version onto each target line. It is the read-and-resolve keystone: it performs the file and network I/O but writes nothing - applying or reporting the results is the caller's choice. Results are grouped by file in path order, markers in line order, so the output is deterministic.
func Validate ¶
Validate is the offline counterpart of Run: it scans, binds, and checks every marker - that its provider and keys are valid, its target line carries an unambiguous version, its rule compiles, and its follow edges resolve - without any network or writes. It is the engine behind lint, surfacing each marker's own problem rather than cascading one failure into the next.
func (FileResult) Rewritten ¶
func (f FileResult) Rewritten() []string
Rewritten returns the file's lines with every changed result spliced onto its target line. The original slice is left untouched.
type Marker ¶
type Marker struct {
File string
Line int // 0-based index of the directive's comment line
Target int // 0-based index of the line it rewrites
Directive directive.Directive
Provider string // provider name; follow for a follower
ID string // namespaced producer id, or ""
From string // namespaced follow source, or ""
Value string // value kind a follower projects
Select string // old/new snapshot a follower reads
Tags []string // labels for --tags filtering, in source order
Sidecar bool // the directive came from a YAML sidecar
}
Marker is a directive bound to the line it governs, classified as a producer (resolves from an upstream provider) or a follower (reuses another marker's result), with id and from namespaced to the file's repository so the same id in different repositories does not clash.
func Markers ¶
Markers binds every directive found in file to its target line, classifies it, and namespaces its id and from by the file's repository root.
func (Marker) IsFollower ¶
IsFollower reports whether the marker reuses another marker's result rather than resolving from an upstream provider.
type Option ¶
type Option func(*settings)
Option configures Run.
func WithConfig ¶
WithConfig sets the per-root config resolver. Each scanned file's repository root supplies its own paths.exclude, required-version gate, and selection toggle defaults (verify/prerelease/downgrade/deep); a CLI override still wins over every root. Without it the scan applies no project config.
func WithDeep ¶
WithDeep overrides the per-root run.deep default for every marker: a deep lookup follows pagination to exhaustion instead of reading only the first (newest) page - more accurate, at the cost of more requests that may be slow or hit rate limits. A non-nil value forces it on or off run-wide; nil leaves each root's run.deep (and a verify-implied deep) in force. The default is shallow.
func WithDowngrade ¶
WithDowngrade overrides the per-directive downgrade rule for every marker: a non-nil allow forces downgrades on or off run-wide, while nil leaves each directive's own setting in force.
func WithForce ¶
WithForce overrides the per-root run.force default for every marker. When in force, a followed digest (sha256 or commit) is re-pinned even if the version it follows is unchanged, so a re-published artifact's new digest is adopted. nil leaves each root's run.force in force; the default holds an unchanged version's digest, so a pin never moves on its own.
func WithIgnoreFiles ¶
WithIgnoreFiles sets the ignore-file names honoured during the walk (default: .gitignore).
func WithMaxSize ¶
WithMaxSize sets the largest file the scan will read.
func WithNoIgnore ¶
WithNoIgnore disables ignore-file pruning (.gitignore) so otherwise-ignored files are scanned. VCS directories stay excluded.
func WithNow ¶
WithNow injects the reference time cooldown measures against, keeping a run deterministic. Unset, the current time is used.
func WithPrerelease ¶
WithPrerelease overrides the per-directive prerelease rule for every marker: a non-nil allow forces prereleases on or off run-wide, while nil leaves each directive's own setting in force.
func WithReporter ¶
WithReporter sets the progress reporter that observes markers as they resolve. The default discards everything; the CLI supplies a live display.
func WithRequireDirective ¶
WithRequireDirective sets whether the scan keeps only files that already carry a clover: directive (the default, for run/lint/format) or returns every text file (for annotate, which proposes directives where none exist).
func WithScanLabel ¶
WithScanLabel sets the message shown on the transient scan-progress line - the live "Scanning ..." spinner that precedes resolution. Each command supplies its own phrasing; the default is generic.
func WithTagFilter ¶
WithTagFilter restricts the run to markers the filter matches. The zero filter matches every marker; a non-empty one drops markers whose tags do not satisfy it, including untagged markers.
func WithTruncationSink ¶
func WithTruncationSink(sink func(provider.Truncation)) Option
WithTruncationSink sets a callback invoked with a truncated resource (its label and upstream page) when a shallow lookup stopped with more results available, so the caller can suggest a deep lookup. It may be called concurrently.
func WithVerify ¶
WithVerify overrides the per-directive verify rule for every marker: a non-nil value forces the deep tag-on-branch check on or off run-wide, while nil leaves each directive's own verify/verify-branch setting in force.
func WithVersion ¶
WithVersion sets the running clover version the per-root required-version gate checks each repository against. Unset (or an unparseable dev build), the gate is inert.
func WithWorkers ¶
WithWorkers sets how many files the scan walk and markers resolve concurrently (library default: NumCPU; the CLI passes its -P flag, default 10).
type Result ¶
type Result struct {
Marker Marker
Current string // the version token currently on the target line
Resolved string // the value the marker resolved to upstream, or via follow
Written string // the value rendered onto the line; what the report shows as `to`
NewLine string // the target line after rendering, == original when unchanged
Changed bool // whether rendering altered the target line
Skipped bool // the marker's dependency failed, was missing, or cycled
Disabled bool // the directive set disabled=...; the marker is intentionally inert (never a lint failure)
Reason string // why the marker was skipped, or the disabled= reason it was disabled with
Err error // why resolution failed
Verify error // a secure pin failed verification (non-fatal: the marker still resolved)
Moved string // the upstream commit a held pin's tag moved to; empty when unmoved
// Truncated reports that a shallow lookup against a recency-ordered provider
// stopped with more pages available. Paired with an ErrNoCandidate failure it
// drives the gated --deep hint; it stays false for a lexically ordered
// provider, whose truncation feeds the run-wide blanket hint instead.
Truncated bool
// ResolvedURL is the upstream web page for the resolved candidate (e.g. a
// GitHub release/tag page), when the provider supplies one. The report
// hyperlinks the reported version to it; empty when unavailable.
ResolvedURL string
// CurrentURL is the upstream web page for the version currently on the line,
// with its ref inferred from the resolved ref's format. The report
// hyperlinks the from value to it; empty when unavailable.
CurrentURL string
}
Result is the outcome of resolving one marker: the version it found in the file, the value it resolved to, and the rewritten target line. Exactly one of a clean resolution, Skipped, Disabled, or Err holds. A skipped, disabled, or errored marker leaves Resolved empty and NewLine equal to the original line.
Source Files