scan

Documentation

Overview

Package scan walks the requested paths and discovers the files that contain a clover: directive. A single walker feeds a pool of workers that read and scan files concurrently; only files with a directive keep their content, for the later rewrite. Binary and oversized files are skipped, as are VCS and ignored directories. Discovery only - atomic rewrites belong to the apply phase (x/os.AtomicWrite).

Index

• func IsSidecar(path string) bool
• type File
  • func Scan(ctx context.Context, roots []string, opts ...Option) ([]File, int, error)
• type IgnoreFunc
• type LineError
• type Located
• type Option
  • func WithIgnore(fn IgnoreFunc) Option
  • func WithMaxSize(n int64) Option
  • func WithProgress(fn ProgressFunc) Option
  • func WithRequireDirective(on bool) Option
  • func WithWorkers(n int) Option
• type ProgressFunc

Functions

func IsSidecar

func IsSidecar(path string) bool

IsSidecar reports whether path names a sidecar file. format and annotate use it to skip the diagnostics File a broken sidecar produces - a sidecar is never an inline-directive target to reformat or annotate.

Types

type File

type File struct {
	Path  string
	Lines []string
	Found []Located
	// Ignored holds the line indices a clover:ignore control suppresses (the
	// next-line target, or the lines inside an ignore-start/ignore-end block).
	// It lets annotate honour the same opt-out the directive scan does; it is nil
	// when the file has no such control.
	Ignored set.Set[int]
	Errors  []LineError
}

File is a scanned file that carries at least one directive. Lines is the file's content, split on newlines and retained so the apply phase can rewrite in place.

func Scan

func Scan(ctx context.Context, roots []string, opts ...Option) ([]File, int, error)

Scan walks roots and returns the files carrying a clover: directive, sorted by path for deterministic output, along with the total number of files examined. A single walker produces paths that a pool of workers reads and scans concurrently.

type IgnoreFunc

type IgnoreFunc func(path string, isDir bool) bool

IgnoreFunc reports whether the walk should skip path. isDir distinguishes a directory (skipped wholesale) from a file. It is the seam a gitignore matcher plugs into via WithIgnore.

type LineError

type LineError struct {
	Line    int
	Err     error
	Sidecar bool
	Skip    bool
}

LineError is a malformed directive: the keyword was present but parsing failed. The pipeline surfaces it as an errored marker result. Sidecar marks a structural sidecar problem (a dangling target, an unresolvable locator, double-governance) so lint fails on it while run downgrades it to a skip-with-warning - a broken sidecar should not sink an otherwise-good run. Skip marks a soft skip rather than a hard error - a sidecar entry suppressed by a clover:ignore on its target line - surfaced as a skipped result (its Err carries the reason), so the opt-out is visible without reading as a failure.

type Located

type Located struct {
	Line      int // index into File.Lines of the directive's comment line, or the target line for a sidecar
	Directive directive.Directive
	Sidecar   bool // the directive came from a YAML sidecar; Line is the resolved target
}

Located is a directive found on a line of a file. An inline directive's Line is its comment line (it rewrites the line below); a sidecar directive's Line is the target line itself, already resolved by its locator, so Sidecar marks which binding the pipeline applies.

type Option

type Option func(*config)

Option configures Scan.

func WithIgnore

func WithIgnore(fn IgnoreFunc) Option

WithIgnore supplies the predicate that skips ignored files and directories - the seam a gitignore matcher plugs into. It is consulted in addition to the always-skipped VCS directories.

func WithMaxSize

func WithMaxSize(n int64) Option

WithMaxSize sets the largest file scan will read.

func WithProgress

func WithProgress(fn ProgressFunc) Option

WithProgress supplies a callback invoked once per file as the walk proceeds, carrying the running count of files examined. It is the seam the CLI's live scan-progress line plugs into; the callback must be goroutine-safe.

func WithRequireDirective

func WithRequireDirective(on bool) Option

WithRequireDirective controls whether a file must already carry a clover: directive to be returned. The default (true) is what run, lint, and format want: only annotated files are of interest, and the keyword prefilter skips the rest cheaply. annotate sets it false to inspect every text file, proposing directives for lines that carry none - so a keyword-less file is returned with an empty Found rather than discarded.

func WithWorkers

func WithWorkers(n int) Option

WithWorkers sets the number of files scanned concurrently (default: NumCPU).

type ProgressFunc

type ProgressFunc func(scanned int)

ProgressFunc reports the running count of files examined so far. It is called once per file from the scan worker pool, so an implementation must be goroutine-safe; it is the seam a live progress display plugs into.