Documentation
¶
Overview ¶
Package lint checks a spec repository against the rules in PROCESS.md. Every rule is a function returning findings; nothing here prints or exits.
Index ¶
- Variables
- type BranchFile
- type Context
- type Finding
- func L01(ctx Context) []Finding
- func L02(ctx Context) []Finding
- func L03(ctx Context) []Finding
- func L04(ctx Context) []Finding
- func L05(ctx Context) []Finding
- func L06(ctx Context) []Finding
- func L07(ctx Context) []Finding
- func L08(ctx Context) []Finding
- func L09(ctx Context) []Finding
- func L10(ctx Context) []Finding
- func L11(ctx Context) []Finding
- func L12(ctx Context) []Finding
- func L13(ctx Context) []Finding
- func L14(ctx Context) []Finding
- func L15(ctx Context) []Finding
- func L16(ctx Context) []Finding
- func L17(ctx Context) []Finding
- func L18(ctx Context) []Finding
- func Run(ctx Context) []Finding
- type Rule
- type Severity
Constants ¶
This section is empty.
Variables ¶
var Rules = []Rule{ {"L01", L01}, {"L02", L02}, {"L03", L03}, {"L04", L04}, {"L05", L05}, {"L06", L06}, {"L07", L07}, {"L08", L08}, {"L09", L09}, {"L10", L10}, {"L11", L11}, {"L12", L12}, {"L13", L13}, {"L14", L14}, {"L15", L15}, {"L16", L16}, {"L17", L17}, {"L18", L18}, }
Rules is every rule, in code order.
Functions ¶
This section is empty.
Types ¶
type BranchFile ¶
BranchFile is a document as it stands on the branch. Err records a failure to read it, which must not be mistaken for the document being new: one means the repository is unreadable, the other that the document is editable.
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context is everything a rule needs.
Its fields are unexported and NewContext is the only way to fill them. That is deliberate: the branch snapshot is what Frozen reads, and a Context built as a literal without it reported every document as editable, which made the same document an error from one command and a warning from another. A rule stating "use the constructor" in a comment was not enough, so the compiler states it instead.
func NewContext ¶
NewContext builds a Context with the branch snapshot populated. Any caller whose rules depend on whether a document is frozen must use this rather than building a Context literal: Branch is what Frozen reads, and a Context without it reports every document as editable.
func (Context) Frozen ¶
Frozen reports whether a document has already reached the branch in a terminal status, and so can no longer be edited. A rule never reports an error against a frozen document, because L11 forbids the fix.
func (Context) Git ¶
func (c Context) Git() git.Repository
Git is the repository's git, or nil when there is not one.
type Finding ¶
type Finding struct {
// Path is relative to root.
Path string
// Line is 1-based, or 0 when the finding has no single line.
Line int
Severity Severity
Message string
Rule string
}
Finding is one rule's complaint about one place.
func L02 ¶
L02 checks that the identifier matches the type and filename, and that the filename has the required shape.
func L04 ¶
L04 checks that every reference resolves to an existing document of a type the field permits.
func L05 ¶
L05 checks updates and obsoletes: same type, accepted, not the document itself, and not both at once.
func L08 ¶
L08 checks that the required sections are present, correctly titled and in the required relative order, and that Rejection rationale is present exactly when the document is rejected.
func L09 ¶
L09 checks that an accepted document leaves no open questions. Keyed on the section being present rather than on the document type, so it still holds if an ADR carries one as an extra section.
func L11 ¶
L11 checks that a frozen document is unchanged. A document is frozen once it has reached the branch in a terminal status; until then the working tree may differ freely, which is what makes the freezing commit legal.
func L12 ¶
L12 checks that a spec page includes nothing that is effectively obsolete. Obsolescence claimed by a document that is not accepted has no effect, so a page is stale only once the replacement has actually been decided.
func L13 ¶
L13 checks that a ref has been verified recently enough. A ref_stale_days of zero disables the rule.
func L14 ¶
L14 checks that no required section was left empty. It does not apply to withdrawn documents, whose sections are empty by the nature of abandonment, and it exempts the two sections that are legitimately empty: Open questions, which L09 requires to be empty before acceptance, and Changelog, which stays empty for a document never edited while proposed.
func L15 ¶
L15 checks the glossary: unique terms, in ascending case-insensitive order, one paragraph each.
func L17 ¶
L17 checks that every relative link resolves to a file, and to a heading when it carries an anchor.
Source Files