doctor

Documentation

Overview

Package doctor turns the architecture rules into static analysis.

Without it, "mandatory architecture" is documentation nobody reads. The rules here are the ones the type system cannot reach: the compiler guarantees that a repository needs a Grant, but it cannot tell you that the policy was never opened, that a controller talks to the database, or that a tenant came from the request.

It reads the AST and never runs the code, so it works on a project that does not compile -- which is exactly when someone needs to be told what is wrong.

The tree it reads

The project layout is conventional, directory by directory, so a file is placed by the app/ subtree it sits in rather than by a module directory: app/Policies/InvoicePolicy.go is the Policies of Invoice, and app/Repositories/InvoiceRepository.go is the Repositories of the same entity. The rules reason about the ENTITY, which is the thing a policy protects -- the directory is only how the entity is spelled on disk.

Index

• type Finding
  • func Run(dir string, profile Profile) ([]Finding, error)
  • func (f Finding) String() string
• type Profile
  • func ParseProfile(s string) (Profile, error)
• type Severity
  • func (s Severity) String() string

Types

type Finding

type Finding struct {
	Rule     string
	Severity Severity
	File     string
	Line     int
	Message  string
	// Why explains the consequence, not the rule. A finding that only says what
	// is forbidden gets suppressed; one that says what breaks gets fixed.
	Why string
}

Finding is one problem, at one place.

func Run

func Run(dir string, profile Profile) ([]Finding, error)

Run analyzes the project rooted at dir against one profile.

Every rule runs on both profiles except the three that only make sense on Performance, so asking for a profile adds checks and never removes any.

Findings come back sorted by file and line, so the output is stable and a diff between two runs means something.

func (Finding) String

func (f Finding) String() string

type Profile

type Profile string

Profile is the deployment profile a project is checked against.

The two labels are the ones arandu.mod.toml already spells in its profiles list, so a project asks for the check in the same word it declares support in.

const (
	// Conventional is the SQL profile, and what Run checks when nothing else is
	// asked for.
	Conventional Profile = "conventional"
	// Performance is the wide-column profile. It stores one aggregate per
	// partition, which is why a statement reaching two tables and a transaction
	// spanning two aggregates are findings here and correct code elsewhere.
	Performance Profile = "performance"
)

The two profiles. There is no third, and no "auto": a profile that is guessed from the code is a profile nobody can put in a pipeline.

func ParseProfile

func ParseProfile(s string) (Profile, error)

ParseProfile reads what was passed to the profile flag.

An unknown value is an error rather than a fallback to Conventional: a typo that silently checks less than was asked for is the failure this returns an error to prevent.

type Severity

type Severity int

Severity says whether a finding blocks CI.

const (
	// Warning is reported and does not fail, unless --strict.
	Warning Severity = iota
	// Error fails, always.
	Error
)

The two levels. There is no "info": a check that does not change what anyone does is noise that trains people to ignore the output.

func (Severity) String

func (s Severity) String() string