Documentation
¶
Overview ¶
Package mode implements run, lint, and format over the shared pipeline, differing only in network use and what (if anything) is written.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AnnotateChange ¶
AnnotateChange is one comment line annotate would write: At is the 0-based line index it acts on, Line the comment text. Existing distinguishes the two shapes - a fresh insertion above a recognized line (Existing false), or a rewrite of an existing directive comment at At into its canonical minimal form (Existing true, only under --force).
type AnnotateFile ¶
type AnnotateFile struct {
Path string
Changes []AnnotateChange
Sidecar *AnnotateSidecar
Skips []AnnotateSkip
Written bool
WriteErr error
}
AnnotateFile is the annotate outcome for one file: the comment lines it would add or rewrite (for a commentable file), or the sidecar it would generate (for a comment-less strict-JSON target), and whether they were written. The two are mutually exclusive - a file either hosts inline comments or it does not.
type AnnotateSidecar ¶
type AnnotateSidecar struct {
Path string
Content string
Entries []SidecarEntryChange
}
AnnotateSidecar is the sidecar annotate would write beside a comment-less target: its path, the full canonical YAML to write, and one entry-change per fresh or rewritten entry (for counts and reporting). Content is the exact bytes `--write` lays down - a fresh document, or the existing one with new entries appended.
type AnnotateSkip ¶
type AnnotateSkip struct {
Line int // 0-based target line; -1 when the reason belongs to the file
Reason string
Sidecar string
}
AnnotateSkip records a recognized annotation candidate that annotate left alone, with the reason it failed an opt-out or offline safety gate. Skips are diagnostics only; they never affect Added/Updated counts.
type AnnotateSummary ¶
type AnnotateSummary struct {
Files []AnnotateFile
Scanned int // total files examined during the walk
}
AnnotateSummary is the annotate outcome over all roots, in file order.
func Annotate ¶
func Annotate( ctx context.Context, roots []string, write bool, force bool, configs *config.Resolver, reporter progress.Reporter, parallelism int, opts ...pipeline.Option, ) (AnnotateSummary, error)
Annotate scans every text file under roots and, for each line that clover can already track but is not yet annotated, proposes a `clover: provider=auto` comment above it - the inverse of the auto-detection that resolves such a marker. It is the onboarding command: it leans on the same dispatch routes match.Infer uses, so a line only earns an annotation that is guaranteed to re-resolve. By default it never touches an existing annotation; with force it also rewrites a recognized line's directive into its canonical minimal form, collapsing keys inference supplies while preserving every rule key. With write off it reports what it would do and writes nothing; otherwise it rewrites each changed file atomically.
func (AnnotateSummary) Added ¶
func (s AnnotateSummary) Added() int
Added reports how many fresh annotations annotate would insert.
func (AnnotateSummary) OK ¶
func (s AnnotateSummary) OK() bool
OK reports whether every recognized line is already annotated canonically - nothing to add or rewrite.
func (AnnotateSummary) Total ¶
func (s AnnotateSummary) Total() int
Total reports the total number of comment lines annotate would add or rewrite.
func (AnnotateSummary) Updated ¶
func (s AnnotateSummary) Updated() int
Updated reports how many existing annotations annotate would rewrite (--force).
type FormatChange ¶
FormatChange is a directive comment line format would rewrite: its 0-based line index, the before and after text, and any unknown keys --prune removed.
type FormatError ¶
FormatError is a directive format left untouched because it carries an unknown key, reported (and exited on) rather than silently reformatted. --prune turns these into changes instead.
type FormatFile ¶
type FormatFile struct {
Path string
Changes []FormatChange
Errors []FormatError
Sidecar bool
Content string
Written bool
WriteErr error
}
FormatFile is the format outcome for one file: the comment lines it would canonicalize, any rejected for an unknown key, and whether they were written. For a sidecar, Sidecar is set and Content carries the whole re-emitted document (the file is rewritten as a unit, not line by line).
type FormatSummary ¶
type FormatSummary struct {
Files []FormatFile
}
FormatSummary is the format outcome over all roots, in file order.
func Format ¶
func Format( ctx context.Context, roots []string, dry bool, cliPrune *bool, configs *config.Resolver, parallelism int, opts ...pipeline.Option, ) (FormatSummary, error)
Format canonicalizes every directive comment under roots - reordering keys into their canonical sequence and normalizing quoting - without resolving or touching the version. It only ever rewrites the comment, never the target line, and is idempotent. With dry set it reports what would change and writes nothing, the read-only path shared by --check and --dry-run; otherwise it rewrites each changed file atomically.
func (FormatSummary) Changed ¶
func (s FormatSummary) Changed() int
Changed reports the total number of directive comments format would rewrite.
func (FormatSummary) Errored ¶
func (s FormatSummary) Errored() int
Errored reports the total number of directives format rejected for an unknown key (always zero under --prune, which removes them instead).
func (FormatSummary) OK ¶
func (s FormatSummary) OK() bool
OK reports whether every directive is already canonical and carries no unknown key - the signal a format --check gate, and an unknown-key rejection, exit on.
type Outcome ¶
type Outcome struct {
pipeline.FileResult
Written bool
WriteErr error
}
Outcome pairs a file's resolution results with what the mode did to it on disk: whether it was rewritten, and any error from that write. A mode that writes nothing (lint) leaves Written false and WriteErr nil.
type SidecarEntryChange ¶
SidecarEntryChange is one sidecar entry annotate would add or, under --force, rewrite: the 0-based target line in the target file it governs, and whether it replaces an existing entry rather than introducing a new one.
type Summary ¶
type Summary struct {
Outcomes []Outcome
Elapsed time.Duration // wall-clock time the run took, for the summary line
}
Summary is everything a mode produced over its roots, in file order, ready for the reporter to render.
func Lint ¶
Lint validates every marker under roots offline - no network, no writes - and reports each one's problems. It is the CI gate: a clean summary proves every directive will resolve, an errored or skipped marker proves it will not.
func Run ¶
func Run( ctx context.Context, roots []string, dryRun bool, parallelism int, opts ...pipeline.Option, ) (Summary, error)
Run resolves every marker under roots against its provider and rewrites each changed target line in place, atomically and preserving file mode. With dryRun set it resolves and renders but writes nothing, so the summary shows what would change. The pipeline options forward scan and resolution settings (workers, clock, ignore files).
func (Summary) Disabled ¶
Disabled reports the number of markers a disabled= directive intentionally disabled. They are inert by design, so they never count toward lint failure.
Source Files