config

Documentation

Overview

Package config reads per-project rule settings.

The format is deliberately small: which rules to run, and at what severity. Anything more expressive invites configuration that encodes a policy nobody remembers agreeing to.

Inline `# quaddoc: disable=QD001 reason` comments suppress a rule for one unit. The reason is mandatory, and a disable without one is itself reported, because a suppression whose justification has been lost is indistinguishable from a bug someone gave up on.

Index

• Constants
• func ApplySuppressions(findings []rules.Finding, byUnit map[string][]Suppression) []rules.Finding
• type Config
  • func Load(start string) (*Config, error)
  • func (c *Config) RuleConfig() rules.Config
• type Suppression
  • func ParseSuppressions(unit, text string) []Suppression
  • func (s Suppression) Covers(ruleID string) bool

Constants

const FileName = ".quaddoc.toml"

FileName is the per-project configuration file.

Functions

func ApplySuppressions

func ApplySuppressions(findings []rules.Finding, byUnit map[string][]Suppression) []rules.Finding

ApplySuppressions removes findings covered by a directive, and reports directives that gave no reason.

The reason is mandatory because the cost of a suppression is paid later, by whoever finds it and cannot tell whether it is still justified.

Types

type Config

type Config struct {
	// Disabled lists rule IDs to skip entirely.
	Disabled map[string]bool
	// Severity maps a rule ID to the severity to report it at.
	Severity map[string]rules.Severity
	// Path is where the configuration was read from, empty if none was found.
	Path string
}

Config is a project's rule settings.

func Load

func Load(start string) (*Config, error)

Load reads configuration for a project, searching the directory and its parents so that a repository-wide file applies to units in subdirectories.

func (*Config) RuleConfig

func (c *Config) RuleConfig() rules.Config

RuleConfig converts to the engine's configuration.

type Suppression

type Suppression struct {
	// Rules are the rule IDs suppressed, empty for all of them.
	Rules []string
	// Reason is why. Mandatory.
	Reason string
	// Line is where the directive appeared.
	Line int
	// Unit is the file it appeared in.
	Unit string
}

Suppression is an inline `# quaddoc: disable=...` directive.

func ParseSuppressions

func ParseSuppressions(unit, text string) []Suppression

ParseSuppressions finds inline directives in a unit file's text.

A directive applies to the whole file rather than to the following line. Line-scoped suppression sounds tidier but breaks the moment someone reformats the file, and a suppression that silently stops applying is worse than one with a slightly broad scope.

func (Suppression) Covers

func (s Suppression) Covers(ruleID string) bool

Covers reports whether a suppression applies to a finding.