config

Documentation

Overview

Package config loads and validates Clover's optional YAML configuration. Two layers share one shape and one embedded JSON schema: a user config under the XDG config dir, and a per-project .clover.yaml that overlays it. The schema is also published for editor tooling.

Settings are grouped by the command they configure (run/lint/fmt), with a global block for cross-command defaults like output detail; per-command keys override the global one, and an explicit CLI flag overrides both.

Index

• func CommonExcludes() []string
• func DefaultExcludes() []string
• func Starter(requiredVersion string, excludes []string) []byte
• type Annotate
• type Config
  • func Load(dir, path string) (*Config, error)
  • func LoadUser() (*Config, error)
  • func Merge(user, project *Config) *Config
  • func (c *Config) AnnotateCheck() *bool
  • func (c *Config) AnnotateWrite() *bool
  • func (c *Config) Cache() *bool
  • func (c *Config) CheckVersion(current string) error
  • func (c *Config) Cooldown() time.Duration
  • func (c *Config) CooldownFor(m Marker) time.Duration
  • func (c *Config) Deep() *bool
  • func (c *Config) DeepFor(m Marker) *bool
  • func (c *Config) Downgrade() *bool
  • func (c *Config) DowngradeFor(m Marker) *bool
  • func (c *Config) ExcludeGlobs() []string
  • func (c *Config) Force() *bool
  • func (c *Config) ForceFor(m Marker) *bool
  • func (c *Config) LintOutput(cli *output.Mode) output.Mode
  • func (c *Config) Prerelease() *bool
  • func (c *Config) PrereleaseFor(m Marker) *bool
  • func (c *Config) Prune() *bool
  • func (c *Config) RunOutput(cli *output.Mode) output.Mode
  • func (c *Config) Verify() *bool
  • func (c *Config) VerifyFor(m Marker) *bool
• type Format
• type Global
• type Lint
• type Marker
• type Paths
• type Resolver
  • func NewResolver(user *Config, explicit string, noConfig bool) *Resolver
  • func (r *Resolver) Err() error
  • func (r *Resolver) ForDir(dir string) (*Config, error)
  • func (r *Resolver) Primary() *Config
  • func (r *Resolver) PrimaryForPaths(paths []string) (*Config, error)
  • func (r *Resolver) Root(dir string) string
• type Rule
• type Run

Functions

func CommonExcludes

func CommonExcludes() []string

CommonExcludes returns the exclude globs the init wizard offers, as a fresh copy.

func DefaultExcludes

func DefaultExcludes() []string

DefaultExcludes returns the exclude globs preselected by the init wizard, as a fresh copy.

func Starter

func Starter(requiredVersion string, excludes []string) []byte

Starter renders a commented starter .clover.yaml. A non-empty requiredVersion becomes an active required-version constraint; an empty one is shown as a commented example, documenting the field without imposing a gate. Likewise a non-empty excludes becomes an active paths.exclude block; an empty one is shown commented, so the output never carries a null array. The output carries a yaml-language-server modeline so editors validate it against the published schema, and round-trips cleanly through Load.

Types

type Annotate

type Annotate struct {
	Check *bool `yaml:"check"`
	Write *bool `yaml:"write"`
}

Annotate holds defaults for `clover annotate`.

type Config

type Config struct {
	Annotate        Annotate `yaml:"annotate"`
	Format          Format   `yaml:"fmt"`
	Global          Global   `yaml:"global"`
	Lint            Lint     `yaml:"lint"`
	Paths           Paths    `yaml:"paths"`
	RequiredVersion *string  `yaml:"required-version"`
	Run             Run      `yaml:"run"`
}

Config is a parsed .clover.yaml. Pointer fields are tri-state: nil means the key was absent (so a lower-precedence layer or built-in default applies), distinct from an explicit false/zero that overrides it.

func Load

func Load(dir, path string) (*Config, error)

Load reads the project config from path, or - when path is empty - the first of .clover.yaml/.clover.yml found in dir, validating it against the embedded schema. It returns nil with no error when no file is found and none was requested, so an absent config is simply no config.

func LoadUser

func LoadUser() (*Config, error)

LoadUser reads the user config from <config-dir>/clover/config.yaml (or .yml), where <config-dir> is $XDG_CONFIG_HOME or its per-OS default (e.g. ~/.config). Like Load it returns nil with no error when no file is present. Its settings form the base that a project config overlays via Merge.

func Merge

func Merge(user, project *Config) *Config

Merge returns the effective config: the user config overlaid by the project one, field by field. The project layer always takes precedence - any field it sets wins, and only the fields it leaves unset fall back to user. Either argument may be nil. Configs are treated as immutable after load: the result is a fresh top-level value, but its pointer and slice leaves may alias an input's, so callers must not mutate them in place.

func (*Config) AnnotateCheck

func (c *Config) AnnotateCheck() *bool

AnnotateCheck returns the configured annotate.check default (nil = unset).

func (*Config) AnnotateWrite

func (c *Config) AnnotateWrite() *bool

AnnotateWrite returns the configured annotate.write default (nil = unset).

func (*Config) Cache

func (c *Config) Cache() *bool

Cache returns the configured run.cache setting (nil = unset). When false, cacheable responses are not persisted across runs.

func (*Config) CheckVersion

func (c *Config) CheckVersion(current string) error

CheckVersion verifies the running clover version satisfies required-version. An empty constraint, or a current version that does not parse (a dev build), passes - the gate never blocks an unversioned binary.

func (*Config) Cooldown

func (c *Config) Cooldown() time.Duration

Cooldown returns the configured run.cooldown default, zero when unset. It is the fill-in for directives carrying no cooldown of their own - a written cooldown is a deliberate per-line choice, so unlike the boolean defaults this one never overrides a directive. The value is validated at load, so parsing cannot fail here.

func (*Config) CooldownFor

func (c *Config) CooldownFor(m Marker) time.Duration

CooldownFor resolves the run.cooldown default for marker m: the first matching rule that sets cooldown wins, else run.cooldown, zero when neither applies. Like Config.Cooldown it only fills in for directives carrying no cooldown of their own. Values are validated at load, so parsing cannot fail here.

func (*Config) Deep

func (c *Config) Deep() *bool

Deep returns the configured run.deep default (nil = unset).

func (*Config) DeepFor

func (c *Config) DeepFor(m Marker) *bool

DeepFor resolves the run.deep default for marker m.

func (*Config) Downgrade

func (c *Config) Downgrade() *bool

Downgrade returns the configured run.downgrade default (nil = unset).

func (*Config) DowngradeFor

func (c *Config) DowngradeFor(m Marker) *bool

DowngradeFor resolves the run.downgrade default for marker m.

func (*Config) ExcludeGlobs

func (c *Config) ExcludeGlobs() []string

ExcludeGlobs returns the configured exclude globs, nil-safe so callers need not branch on a missing config.

func (*Config) Force

func (c *Config) Force() *bool

Force returns the configured run.force default (nil = unset). When true, a followed digest is re-pinned even if the version it follows is unchanged.

func (*Config) ForceFor

func (c *Config) ForceFor(m Marker) *bool

ForceFor resolves the run.force default for marker m.

func (*Config) LintOutput

func (c *Config) LintOutput(cli *output.Mode) output.Mode

LintOutput resolves the output detail for `clover lint`, with the same precedence as Config.RunOutput but keyed on lint.output.

func (*Config) Prerelease

func (c *Config) Prerelease() *bool

Prerelease returns the configured run.prerelease default (nil = unset).

func (*Config) PrereleaseFor

func (c *Config) PrereleaseFor(m Marker) *bool

PrereleaseFor resolves the run.prerelease default for marker m.

func (*Config) Prune

func (c *Config) Prune() *bool

Prune returns the configured fmt.prune default (nil = unset).

func (*Config) RunOutput

func (c *Config) RunOutput(cli *output.Mode) output.Mode

RunOutput resolves the output detail for `clover run`: the CLI value when set, then run.output, then global.output, then the built-in text default.

func (*Config) Verify

func (c *Config) Verify() *bool

Verify, Prerelease, Downgrade, and Deep return the configured run defaults as tri-state pointers (nil = unset), nil-safe on the config. A caller resolves the effective value as cmp.Or(cliFlag, cfg.Verify()): the CLI flag wins, then the config, then the per-marker directive that a nil leaves untouched.

func (*Config) VerifyFor

func (c *Config) VerifyFor(m Marker) *bool

VerifyFor resolves the run.verify default for marker m: the first matching rule that sets verify wins, else the run block's own value. Like every scoped accessor it is nil-safe on the config.

type Format

type Format struct {
	Prune *bool `yaml:"prune"`
}

Format holds defaults for `clover fmt`.

type Global

type Global struct {
	Output *output.Mode `yaml:"output"`
}

Global holds cross-command defaults. A per-command block overrides these.

type Lint

type Lint struct {
	Output *output.Mode `yaml:"output"`
}

Lint holds defaults for `clover lint`.

type Marker

type Marker struct {
	Path     string
	Provider string
	Tags     []string
}

Marker describes one marker for scoped-rule matching: the file path relative to its repository root in slash form, the resolved provider name, and the directive's tags.

type Paths

type Paths struct {
	Exclude []string `yaml:"exclude"`
}

Paths controls which files clover scans.

type Resolver

type Resolver struct {
	// contains filtered or unexported fields
}

Resolver resolves the effective config governing a scanned path: the user config overlaid by the project .clover.yaml at the path's repository root (or, when the path is not in a repository, its own directory). Each root's config is loaded and merged once, then memoized, so a scan spanning many files across a handful of repositories does only a handful of reads. It also records the distinct roots it resolves, so a caller can tell a single-repository scan from a multi-repository one. Safe for concurrent use.

Two flags short-circuit discovery: an explicit --config governs every path, and --no-config yields nil for all of them.

func NewResolver

func NewResolver(user *Config, explicit string, noConfig bool) *Resolver

NewResolver builds a per-root config resolver. user is the loaded user (XDG) config and may be nil. explicit is the --config path: when non-empty it is loaded for every path and root discovery is skipped. noConfig, the --no-config flag, makes every lookup nil for a fully unconfigured run.

func (*Resolver) Err

func (r *Resolver) Err() error

Err returns the first project-config load error the resolver encountered while resolving paths, or nil. A malformed config is a hard error a caller surfaces after the scan, even when every file under the bad root was excluded or carried no directive.

func (*Resolver) ForDir

func (r *Resolver) ForDir(dir string) (*Config, error)

ForDir returns the effective config governing the directory dir: the project config at dir's repository root (or dir itself when not in a repository), overlaid on the user config and memoized per root. With --config the explicit file governs every directory; with --no-config it returns nil. A malformed project config surfaces its load error (memoized, so it is read once).

func (*Resolver) Primary

func (r *Resolver) Primary() *Config

Primary returns the config to resolve per-invocation settings (output detail, fmt.prune) from: the explicit --config when set; else the sole root's config when the scan resolved to exactly one repository, so a single-tree run still honours its project config; else the user config, so a multi-repository scan falls back to the user default. It is meaningful only after the scan has driven ForDir over the scanned tree.

func (*Resolver) PrimaryForPaths

func (r *Resolver) PrimaryForPaths(paths []string) (*Config, error)

PrimaryForPaths resolves the config for per-invocation settings that must be known before a scan starts. With one resolved root, that root's config wins; with multiple roots, the user config is the only unambiguous default.

func (*Resolver) Root

func (r *Resolver) Root(dir string) string

Root returns the directory whose project config governs dir: the repository root containing dir, or dir itself (absolute) when it is not in a repository. It is the cache key ForDir resolves under, exposed so a caller can group files by the root that governs them.

type Rule

type Rule struct {
	Paths     []string `yaml:"paths"`
	Providers []string `yaml:"providers"`
	Tags      []string `yaml:"tags"`

	Cooldown   *string `yaml:"cooldown"`
	Deep       *bool   `yaml:"deep"`
	Downgrade  *bool   `yaml:"downgrade"`
	Force      *bool   `yaml:"force"`
	Prerelease *bool   `yaml:"prerelease"`
	Verify     *bool   `yaml:"verify"`
}

Rule scopes run defaults to the markers its selectors match. At least one selector (paths, providers, tags) must be set. A setting left unset falls through to the next matching rule and then to the run block's own default, so orthogonal rules compose instead of shadowing each other.

type Run

type Run struct {
	Cache      *bool        `yaml:"cache"`
	Cooldown   *string      `yaml:"cooldown"`
	Deep       *bool        `yaml:"deep"`
	Downgrade  *bool        `yaml:"downgrade"`
	Force      *bool        `yaml:"force"`
	Output     *output.Mode `yaml:"output"`
	Prerelease *bool        `yaml:"prerelease"`
	Rules      []Rule       `yaml:"rules"`
	Verify     *bool        `yaml:"verify"`
}

Run holds defaults for `clover run`.