archtest

type AssertOptions ¶

type AssertOptions struct {
	// Check is how the rule is run, and reaches Checkable.Check unchanged: whether an empty selection is
	// allowed, where the progress log goes, which build tags the project is analyzed under. The zero value
	// is what rule.Check(nil) would have done.
	Check fluentapi.CheckOptions
	// Message is how a rule that does not hold is reported: the palette the report is painted in, and how
	// many violations it lists. The zero value is plain text and every violation, which is the right default
	// for output that is read from a CI log as often as from a terminal.
	Message MessageOptions
}

AssertOptions is the one options bag the assert helpers take: how the rule is run, and how the failure is written. AssertAllPass takes the same bag for a whole suite of rules, which is why nothing in it is about one rule in particular.

AssertPasses spans both halves of the pipeline's tail — it checks and then it reports — so it needs the knobs of both, and it holds the two existing bags rather than re-declaring their fields. A flat bag with `AllowEmptyTests` and `MaxViolations` side by side would read more briefly and would be a second place where every knob the library ever grows has to be added, in step, forever.

It is a struct with a nil-means-defaults contract, like the two bags inside it, and every default is a zero value — a quiet, strict check reported as plain text with every violation listed — so a nil bag, the zero bag and an explicitly empty one all describe the same assertion. That is why the ordinary call is AssertPasses(t, rule, nil). Read a nil bag through WithDefaults rather than reaching for a field.

func (o *AssertOptions) WithDefaults() AssertOptions

type Color ¶

type Color uint8

Color is a terminal color the report paints one part of a message in: the offender, the rule it broke, the count at the top.

It is a closed set of names rather than an escape sequence a caller hands in. Report policy is this layer's, so a report that is assembled in one place can be changed in one place — and a caller able to pass an arbitrary escape sequence could put a cursor move, or a clear-screen, into somebody's test output.

ColorNone is the zero value and paints nothing, so the zero Palette is a plain-text report and color is opted into rather than out of. That is worth more than it looks: test output is read at least as often from a CI log, where an escape sequence is noise, as from a terminal.

const (
	// ColorNone paints nothing at all: Paint hands the text back exactly as it came in. It is the zero
	// value, and what every field of the zero Palette is.
	ColorNone Color = iota
	// ColorRed is the failure color: the count at the top of a failing report, and what an offender was
	// found to actually do.
	ColorRed
	// ColorGreen is the pass color: the one line a report of a rule that holds consists of.
	ColorGreen
	// ColorYellow is the requirement color: the rule an offender broke, in the words it was written in.
	ColorYellow
	// ColorBlue is for a palette of a caller's own; the default palette does not use it.
	ColorBlue
	// ColorMagenta is for a palette of a caller's own; the default palette does not use it.
	ColorMagenta
	// ColorCyan is the subject color: the file, or the cycle, a reader has to go and look at.
	ColorCyan
	// ColorGray is the hint color: the sentence that explains a failure rather than reporting it.
	ColorGray
)

func (c Color) Paint(text string) string

func (c Color) String() string

func (c Color) Valid() bool

type MessageOptions ¶

type MessageOptions struct {
	// Palette is which color each part of a message is painted in. The zero Palette paints nothing, so
	// the default is plain text: an escape sequence in a CI log is noise, and the caller who wants color
	// is the one who knows whether a terminal is there. DefaultPalette is the palette to ask for.
	Palette Palette
	// MaxViolations is how many violations a report lists before it says how many it left out. Zero, and
	// anything below it, means every violation.
	//
	// A rule that a repository has never been held to can report hundreds of files, and a test failure
	// that scrolls a terminal is one nobody reads the top of. The cut is never silent — the report says
	// how many were left out and which knob did it — because a truncated list that looks complete is
	// worse than a long one.
	MaxViolations int
}

MessageOptions is the one options bag this layer takes: everything about how a report is written, as opposed to what it reports.

It is a struct with a nil-means-defaults contract, like fluentapi.CheckOptions, and every default is a zero value — a plain-text report that lists every violation — so a nil bag, the zero bag and an explicitly empty one all describe the same report. Read a nil bag through WithDefaults rather than reaching for a field.

func (o *MessageOptions) WithDefaults() MessageOptions

type Palette ¶

type Palette struct {
	// Failure paints the count at the top of a failing report — `3 violations:`.
	Failure Color
	// Pass paints the one line a report of a rule that holds consists of.
	Pass Color
	// Subject paints the thing that disagreed with the rule: the offending file, or the files a cycle
	// runs through. It is what a reader has to go and open, so it is the piece worth finding first.
	Subject Color
	// Requirement paints the rule the subject broke, in the words it was written in: the mood, the
	// predicate and the patterns the user typed.
	Requirement Color
	// Finding paints what was found instead of the rule holding — the files an import reached, the
	// absence of one — which is the offense itself under the negated mood.
	Finding Color
	// Hint paints a sentence that explains a failure rather than reporting it: the note that an empty
	// rule is a violation, the note that a list was cut short. A reader who already knows can skip it,
	// which is why it is the quietest color in the default palette.
	Hint Color
}

Palette is which color each part of a report is painted in: one field per role a piece of a message plays, rather than one per violation kind.

Roles rather than kinds is the whole design. Every message this layer builds is the same sentence — this subject broke this requirement, and here is what was found instead — so a reader who has learned that the cyan word is the file to go and look at has learned it for every rule family the library ever grows, and a rule family that lands later needs no color of its own.

The zero Palette paints nothing, because every field of it is ColorNone: a report is plain text unless a caller asks for DefaultPalette, or fills in the roles it cares about. A nil *MessageOptions therefore means plain text, which is the right default for a CI log.

func DefaultPalette() Palette

type Result ¶

type Result struct {
	// Passed is whether the rule holds: true exactly when there were no violations. It is derived from
	// the list rather than tracked beside it, which is why nothing in the library returns a boolean
	// alongside a []Violation.
	Passed bool
	// Message is the report: one line naming how many violations there are and then one numbered line
	// per violation, or the pass message. It is complete and ready to print — already colored if the
	// options asked for that — and it never ends in a newline, because the caller's own t.Error, log line
	// or diff already decides how the last line ends.
	Message string
}

Result is a whole rule's outcome as a test framework needs it: whether the rule holds, and the one message to print when it does not.

It is the shape of every ArchUnit port's report — a pass flag plus a message — and the seam an adapter works against. An adapter reads these two fields and prints; it never assembles a message of its own, because then the library would phrase failures in as many ways as it has adapters.

The violations themselves are deliberately not here. A caller who wants the data rather than the prose already has it: Check returned it, and this layer is what turns it into words.

type ResultFactory ¶

type ResultFactory struct {
	// contains filtered or unexported fields
}

ResultFactory shapes the violations a rule reported into a Result: the collection of constructors an adapter to a test framework goes through.

It is where numbering, ordering and the count at the top are decided, and it phrases each violation through a ViolationFactory rather than knowing any violation type itself. That split is the reason a new rule family costs this layer one case in one type switch and nothing else.

It is immutable and cheap: the options and the violation factory built from them. Build one per report, or keep one for a suite.

func NewResultFactory(options *MessageOptions) ResultFactory

func (f ResultFactory) Result(violations []kernel.Violation) Result

2 violations:
  1. common/matching/filter.go: should, filename matches "regex_factory.go"; it does not
  2. common/matching/match_target.go: should, filename matches "regex_factory.go"; it does not

type TestingRunner ¶

type TestingRunner interface {
	TestingT
	// Helper marks the calling frame as a helper, so that a failure is filed against the user's own
	// AssertAllPass line rather than against a line of this file — both the one failure this helper reports
	// itself, a suite with no rules in it, and the ones its subtests report through AssertPasses.
	Helper()
	// Run runs f as a named subtest and reports whether it passed. The signature is the stdlib's, so that
	// *testing.T satisfies this interface without an adapter. The boolean is deliberately not read: a rule
	// that does not hold has already reported itself, and the rules after it are asserted either way, the
	// same way AssertPasses reports through Error rather than a fatal call.
	Run(name string, f func(t *testing.T)) bool
}

TestingRunner is the standard library's own test handle, as the suite helper needs it: the method that records a failure, the mark that says a frame is a helper, and Run — the subtest, which is how Go's testing package gives a result its shape.

It is deliberately the one interface in this layer that is not framework-agnostic. Run's argument is a func(*testing.T), so nothing but *testing.T satisfies it — not *testing.B, whose Run takes a *testing.B, and not a third-party handle unless it is built on the stdlib's. That is the trade the two assert helpers split between them: AssertPasses asks for the one method every framework has and works anywhere, and this one asks for the standard library so that it can hand back what only the standard library can do.

Helper() is required here rather than asked for at the call, which is how AssertPasses treats it. A handle with Run(string, func(*testing.T)) is the stdlib's handle, and the stdlib's handle has Helper — an optional interface for a method that cannot be missing would be a branch no test could reach.

type TestingT ¶

type TestingT interface {
	// Error records a failure and lets the test continue, which is Go's non-fatal assertion and what an
	// architecture rule wants: a suite that checks several rules should report all of them in one run, not
	// stop at the first. Its signature is the stdlib's, variadic and untyped, so that *testing.T satisfies
	// this interface without an adapter — AssertPasses always passes it exactly one string.
	Error(args ...any)
}

TestingT is the part of a test framework's handle AssertPasses needs: one method, the one that records a failure and lets the test carry on. TestingRunner is this interface plus what a suite of rules asks for on top, and nothing else in the library asks a framework for anything.

It is the smallest interface that can report anything, and that is the whole point of it. *testing.T and *testing.B satisfy it, so does stdlib testing.TB, and so does every third-party framework's handle that has ever called itself a drop-in for them — Ginkgo's GinkgoT(), a gocheck *check.C, a mock a user writes to test their own suite helper. There is nothing to register and nothing to configure: a framework works here by already having the method every framework has.

Helper() is deliberately not part of it. AssertPasses calls it when the handle has it, so a failure is reported against the user's own line, and a framework without it gets the report all the same rather than being locked out over a convenience.

type ViolationFactory ¶

type ViolationFactory struct {
	// contains filtered or unexported fields
}

ViolationFactory phrases one violation: the collection of constructors that turns the data a rule reported into the sentence a reader gets.

It knows the library's own violation types by sight, because a message is built from a violation's fields — the file, the compiled pattern, the mood, the dependencies actually found — and each family has its own. What it does not recognize is phrased from ViolationKind and whatever the violation can say about itself, so a rule family in a module written later, or a Checkable of a user's own, still reports something a human can read while step 8 of AGENTS.md's "Adding a new rule" is outstanding.

It is immutable and cheap: a palette and nothing else. Build one per report, or keep one for a suite.

func NewViolationFactory(options *MessageOptions) ViolationFactory

func (f ViolationFactory) Message(violation kernel.Violation) string

common/matching/filter.go: should, filename matches "regex_factory.go"; it does not
files/api/handler.go: should not, depend on files, path without filename matches "files/db"; it depends on files/db/conn.go
files/domain/order.go: should not, depend on external modules, path matches "*.*/**"; it depends on gorm.io/gorm
common/a.go: should, have no cycles; it depends on itself through common/a.go -> common/b.go -> common/a.go
layer "db": may not depend on layers "api"; it depends on api through db/conn.go -> api/handler.go
component "internal/db": should not, be in zone of pain; it is, at abstractness 0 and instability 0
internal/api/handler.go: should, be below 400; it is not, at lines of code 900
internal/api.Handler: should, satisfy "be at most 10 methods wide"; it does not, at method count 40
slice "api": should not, contain dependency "db"; it depends on db through api/handler.go -> db/conn.go
slice "api": should, adhere to diagram; it depends on db, which the diagram does not draw through api/a.go -> db/b.go
component "cache": should, adhere to diagram; the project has no slice for it
no files matched: path without filename matches "common/renamed"; an empty rule would hold forever, ...

func (f ViolationFactory) Messages(violations []kernel.Violation) []string