doc

type Example struct {
	// Reported is the shape the rule reports a finding for.
	Reported []string
	// Accepted is the shape that satisfies the rule.
	Accepted []string
}

type Linter struct {
	// ID is the identifier used in .pkglint.yaml and in diagnostics.
	ID string
	// Summary is the one-line description shown when listing linters.
	Summary string
	// Description explains what the linter inspects, one paragraph per element.
	Description []string
	// Rules documents every rule the linter runs, in execution order.
	Rules []Rule
	// Notes hold caveats printed after the rule list.
	Notes []string
}

type Options struct {
	// Linter is the linter to document. Empty lists every linter instead.
	Linter string
	// Rule narrows the output to a single rule of Linter.
	Rule string
}

type Rule struct {
	// ID is the identifier used under the linter's rules key in .pkglint.yaml.
	ID string
	// Summary is the one-line description shown in the linter's rule list.
	Summary string
	// Description explains why the rule exists, one paragraph per element.
	Description []string
	// Reports lists the conditions under which the rule emits a finding.
	Reports []string
	// Example shows the rule in practice. Every rule carries one.
	Example Example
	// Fix tells the user how to satisfy the rule.
	Fix string
	// Tunable reports whether the rule carries its own severity. Rules that are
	// not tunable encode hard contracts and always run at the linter severity.
	Tunable bool
	// Impact is the built-in severity of a rule whose level is fixed in the rule
	// body rather than read from settings. It applies to the rules of a linter that
	// carries no settings at all, where there is no linter severity to inherit and
	// the rules do not all report at the same level. Leave it unset for a rule that
	// follows its linter.
	Impact *lint.Level
	// Notes hold caveats printed after the rule body.
	Notes []string
}