config

Documentation

Overview

Package config loads declscope's YAML configuration.

A config file is optional. When present it is named .declscope.yaml (or .yml) and is looked up from the directory of the package being analyzed upwards, so that a subtree can relax the rules without the rest of the module following suit.

defaults:
  unexported: private

rules:
  naming:
    qualify: ondemand    # always | never | ondemand (only once a package has two namespaces)
    vocabulary:          # per-namespace words that carry the namespace
      mouse: [wheel]
  allowBoundary: false  # stop checking reach, leaving only the naming rule
  allowSurplus: false   # keep //declscope:package with no visible outside use

rules.naming.qualify reads an internal.Mode; rules.naming.exported is true/false; rules.naming.vocabulary maps a namespace to the extra words that satisfy the naming rule for it. rules.allowBoundary and rules.allowSurplus are true/false and default to false.

Unknown keys are an error, and the message names the key and the keys the section does take.

Index

• Variables
• func DefaultBaseline(dir, root string) (string, bool)
• func Find(dir string) string
• func FindBaseline(dir string) string
• func FindChain(dir string) []string
• func Resolve(dir, explicit string) (internal.Options, string, error)
• func ResolveForBaseline(dir, explicit string) (opts internal.Options, configPath, named string, err error)
• type File
  • func Load(path string) (*File, error)
  • func (f *File) Apply(opts *internal.Options) error
  • func (f *File) BaselinePath() string
  • func (f *File) FilterBase() string

Variables

var BaselineNames = []string{".declscope-baseline.yaml", ".declscope-baseline.yml"}

BaselineNames are the default baseline file names, discovered the same way as the config file when none is configured explicitly.

var Names = []string{".declscope.yaml", ".declscope.yml"}

Names are tried in order in each directory.

Functions

func DefaultBaseline

func DefaultBaseline(dir, root string) (string, bool)

DefaultBaseline returns where the entries of a package in dir belong when no config file names a baseline: the nearest existing default-named file between the package and root, which is what the analyzer will consult, else a new file in root, the directory the regeneration was run from.

The search walks the same path as FindBaseline but stops at root. A default-named file above root holds entries for packages the run never saw, and rewriting it wholesale would drop them; a new file in root shadows it for exactly the packages under root instead.

It reports false when root is not on the path at all — the package lies outside root, or a module boundary intervenes — because a file written in root would never be found from dir, and a baseline whose presence is not enough is worse than none. An existing file found on the way is committed to only once the walk has confirmed root is below it: for a package outside root, the nearest file is above root, and rewriting it has the same cost as rewriting one above root for a package inside.

func Find

func Find(dir string) string

Find walks up from dir looking for a config file and returns its path, or "" when there is none. The search stops at a module root, so a stray config file somewhere above the module cannot silently change its rules.

func FindBaseline

func FindBaseline(dir string) string

FindBaseline walks up from dir looking for a default-named baseline file. Its presence is what enables suppression, so the name is fixed and the search stops at the module root, exactly like the config lookup.

func FindChain

func FindChain(dir string) []string

FindChain walks up from dir and returns every config file it passes, outermost first. The nearest file is last, so applying the slice in order leaves the nearest one's stated keys on top.

The search stops at a module root, exactly as Find does. Config files do compose, so a file above the module would reach into it, which is the one thing the module boundary is there to prevent.

func Resolve

func Resolve(dir, explicit string) (internal.Options, string, error)

Resolve produces the options for analyzing a package directory: built-in defaults, with the nearest config file layered on top, and the baseline loaded — the one the config names, else the nearest default-named file found by FindBaseline. explicit overrides the config lookup. It returns the config path that was used, or "" when there was none.

func ResolveForBaseline

func ResolveForBaseline(dir, explicit string) (opts internal.Options, configPath, named string, err error)

ResolveForBaseline produces the options for regenerating the baseline of a package directory: the same rules as Resolve, but no baseline is looked up or loaded, so the options record the current state from scratch. Loading it would let a baseline that fails to parse block its own regeneration, which is the one remedy the documentation offers for it.

The third result is the baseline the config file names, resolved against the config file, or "" when it names none. Where a package's entries belong in that case is the caller's decision — see DefaultBaseline.

Types

type File

type File struct {
	Defaults defaultsSection `yaml:"defaults"`
	Rules    rulesSection    `yaml:"rules"`

	// Filter narrows and subtracts. only alone keeps nothing outside it, omit
	// alone takes files out of everything, and both together narrow first.
	Filter filterSection `yaml:"filter"`

	// Baseline is a path relative to this config file.
	Baseline string `yaml:"baseline"`
	// contains filtered or unexported fields
}

File is the on-disk configuration. Every field is optional, and no setting has a zero value that means anything, so a field left empty is skipped by Apply: omitting a key keeps the built-in default rather than silently disabling a rule.

func Load

func Load(path string) (*File, error)

Load reads and parses a config file.

func (*File) Apply

func (f *File) Apply(opts *internal.Options) error

Apply layers the file's settings onto opts.

func (*File) BaselinePath

func (f *File) BaselinePath() string

BaselinePath resolves the configured baseline against the config file's own directory, so that a config can be moved without rewriting the path.

func (*File) FilterBase

func (f *File) FilterBase() string

FilterBase is the directory the filter patterns are relative to: the one holding this config file, the way BaselinePath resolves the baseline. A path written in a file means a path from that file, and every other path key here already works that way.

Resolving here rather than at match time is what lets the pattern itself be anchored: ** regains its meaning, since a pattern no longer matches at every depth by construction.

Empty when the file did not come from disk.