From c3d7f71da330a8bfdb778bc0dafdfbce793f8ab6 Mon Sep 17 00:00:00 2001 From: ArchUnitDev loop Date: Sun, 16 Aug 2026 11:08:33 +0000 Subject: [PATCH 1/2] README someone can actually start from Closes #41 Implemented by the ArchUnitDev loop. --- NOTES.md | 102 +++++ README.md | 523 ++++++++++++++++++++++- archtest/assert_all_pass.go | 4 +- archtest/assert_passes.go | 4 +- archunit.go | 6 +- readme_test.go | 813 ++++++++++++++++++++++++++++++++++++ 6 files changed, 1442 insertions(+), 10 deletions(-) create mode 100644 readme_test.go diff --git a/NOTES.md b/NOTES.md index fc3dc64..7fa91c3 100644 --- a/NOTES.md +++ b/NOTES.md @@ -2638,3 +2638,105 @@ Deviations from the issue text, `AGENTS.md` or sibling convention. One line each - WHY: the second layer policy in `TestTheSuiteHelperRunsOneSubtestPerRuleUnderTheNameItWasGiven` still has no `WhereLayer("metrics")` clause of its own, which is the metrics host's own omission and not the merge's. It is left as it was found: a merge that quietly adds a rule neither side wrote is a merge nobody can review. + +## Issue #41 — README someone can actually start from + +- WHY: `readme_test.go` exists because the trap the issue names — a sibling port's README documenting a slice API + that does not exist — is not a mistake somebody made while typing. It is what any hand-checked document becomes + after a few months of a moving API, and this repository already decided how to answer that: `ci_test.go` holds a + non-Go artifact to a spec as text rather than trusting that somebody re-reads it. So every Go name the README + uses is looked up in this module's own syntax tree, every `go` block in it is parsed, and the sentences that say + a thing is *absent* are checked against the absence. Six tests, one parse of the tree, no new dependency. +- WHY: the guard reads the library with `go/parser` and not with `reflect`. Reflection cannot see a package-level + function, a method nobody calls or a struct field's name, and those are most of what a README says: `Files`, + `ShouldBeBelowOrEqual`, `CheckOptions.AllowEmptyTests`. Parsing sees all three, and it sees the packages behind + the surface too, which is what lets the `LCOM*` sentence name functions that are deliberately not re-exported. +- WHY: nothing in the guard type-checks the examples, and that is a decision rather than a gap. An example is + written for the reader's project — `internal/api`, `docs/architecture.puml`, a predicate over their own files — + so making one compile means inventing a project around it, and then the document is being checked against a + fixture instead of against the library. What can be checked exactly is checked exactly: `archunit.X` against + archunit.go's exports, and every method of a chain rooted at `archunit` against the methods this module + declares. Every snippet was compiled once while it was written, in a scratch `package archunit_test` file that + `go vet` accepted and that was then deleted; the permanent guard is the parse. +- WHY: a chain's methods are checked against *every* exported method in the module rather than against the + receiver each one is really on. Following `ProjectFiles(nil).InFolder(…).ShouldNot().DependOnFiles()` through + its four builder types by hand is type-checking, badly. The looser check still catches the whole class of + mistake a README makes — a renamed verb, a predicate that moved to the other mood, a terminal that never + existed — because such a name exists nowhere in the tree. +- WHY: `namesOfTheReadersProject` is one entry long, `Handler`, and it is a list rather than a pattern. The + match-target table has to walk one identifier through five selectors, and the declared type of + `internal/api/handler.go` is `Handler` — a name from the reader's code that this module correctly does not have. + Anything added to that list is a name nothing checks any more, so it is worth the friction of being explicit. +- WHY: the graph section spells out all six `ExportAs*` names where the first draft said "`ExportAsDot` and its + five siblings". Both sentences are true, but only one of them can be checked, and only one of them answers the + question a reader actually has — *is Mermaid in there?* — without making them go and read the source. Same + reason the metrics section now names `ShouldNotBeInZoneOfUselessness` beside `ShouldNotBeInZoneOfPain`: the + document says the zone checks are two, so it has to say which two. +- WHY: the two counting sentences AGENTS.md warns about are kept, not avoided. "Nine modifiers" and "Thirteen + terminals" are what makes the report family readable as a closed set instead of a sample, and + `TestTheReadmeCountsTheGraphFamilyCorrectly` recomputes both off `graph/fluentapi` — a modifier hands back a + `GraphBuilder`, a terminal hands back a report or an `error`, `Except` is neither because an exclusion qualifies + the modifier in front of it. A tenth modifier fails that test in the commit that adds it, which is the only + form in which a counted sentence is safe to write. +- WHY: every row of "What is not implemented yet" was checked against the tree rather than remembered, and each + one has a test in `TestTheReadmeIsHonestAboutWhatIsMissing` that fails when somebody implements the thing: no + tag on any commit; the eight LCOM measures are plain functions in `metrics/calculation` with no fluent verb; the + slices family is the only one of the five with no `Except` (four spellings in files, five in metrics, three in + layers, the plain verb in graph); `SliceByFileSuffix` and `Identity` are `MapFunction` values with no slicing + verb; `ImportKind` appears nowhere in archunit.go, so `CheckOptions.IgnoredImportKinds` still needs an import of + `common/extraction`; diagrams are parsed in one format and rendered in seven. A section listing what is missing + is the section most certain to go stale in the happiest possible way, and a stale one tells a reader not to look + for a verb that is sitting right there. +- WHY: the empty-test guard has **two shapes and the README now says both**, which the first draft got wrong by + writing "every terminal reports an `EmptyTestViolation`". A terminal that returns violations does; a report + terminal has no violation list to put one in and so fails with `ErrEmptySnapshot`, `ErrEmptyReport` or + `ErrNothingToDraw`, exactly as those three sentinels' own comments say — and `Measure` reports emptiness + neither way, because it judges nothing. `AllowEmptyTests` opts out of all of them. The graph section gained + the same clause, since a query describing nothing is refused there too and the section never said so. +- WHY: "every modifier narrows it" is gone from the graph section, and from `archunit.go`'s `ProjectGraph` doc, + which said the same thing one clause differently. Two of the nine modifiers widen the default report — + `IncludingExternalDependencies` adds the code outside the project, `IncludingSelfDependencies` adds a node's + dependency on itself — and `Titled`/`WithCheckOptions` narrow nothing. The doc comment is the second copy of + one false sentence, so fixing only the README would have left the next copy to be made from the wrong one. +- WHY: the `fmt.Stringer` sentence is about "every stage of a chain that can describe itself", not every + builder. `LayerPolicyBuilder` — what `WhereLayer` returns — is the one exported stage with no `String`, and it + is named as the exception rather than given a method: a clause that has named a layer and not yet said + anything about it has no sentence of its own, and the policy it will join renders the whole thing anyway. + `readme_test.go`'s own comment about why `String` is exempt from the graph list was reworded to match. +- WHY: the failure block shows the rendering the library actually produces — `path without filename matches + "internal/api/**"`, and the object pattern quoted as the user typed it, `"internal/db/**"` — because that + block is the one section a reader compares their own terminal against. A selector renders as the part of an + identifier it was matched against and never as the verb that spelled it, which is issue #16's decision, so + the section now says that in one clause instead of showing a heading the library cannot print. The same slip + sat in `archtest/assert_passes.go` and `archtest/assert_all_pass.go`, where this copy came from, and both are + fixed so the next copy is right; the second was also missing `depend on files` from the violation line. +- WHY: the prose guard reads a pointer and a qualifier through instead of discarding them, which is what made + it a guard at all: the names that appear *only* in the prose are mostly written `archunit.KindEmptyTest`, + `*ProjectLocator` or `CheckOptions.IgnoredImportKinds`, and matching bare words alone left every one of them + checked by nothing. `archunit.X` is now held to archunit.go's exports rather than to the module, because that + spelling promises a user reaches it without importing anything else. A qualifier that does not read as an + exported identifier ends the word — `AGENTS.md`, `go.mod`, `t.Error` are not names of this library — and the + three the document writes with a foreign qualifier (`fmt.Stringer`, `extraction.ImportKindSet`, + `internal/api.Handler`) are a short explicit list beside `namesOfTheReadersProject`, for the same reason that + list is explicit. Verified by mutation: `archunit.KindEmptyTestX`, `CheckOptions.IgnoredImportKindsX` and + `*ProjectLocatorX` each fail now and each passed before. +- WHY: the closed-set test checks **exact membership** against the set of names the README actually names — + its prose identifiers plus its examples' selections — instead of `strings.Contains`. A substring search + cannot fail for a prefix, so `ShouldBe`, `ShouldBeAbove` and `ShouldBeBelow` were each satisfied by a longer + verb and three of the six threshold predicates were pinned by nothing. It also recomputes the two counts the + document states off `method.receiver`, which was collected and never read: six `Should*` on `MetricBuilder` + against "Threshold predicates are exactly six", two on `MetricsDistanceBuilder` against "the two zone + checks", so a verb added or deleted there fails in the commit that does it, the way + `TestTheReadmeCountsTheGraphFamilyCorrectly` already makes nine and thirteen do. Verified by mutation both + ways: deleting `ShouldBe` from the README fails, and a seventh threshold verb fails twice over. +- WHY: `metrics/extraction` is named beside `common/extraction` in "The map". The first draft said + `common/extraction` is the only part that knows Go, and the metrics module's own extractor imports `go/ast`, + `go/parser` and `go/token` and says in its package comment that it opens files and parses Go. The honest + statement is the one `AGENTS.md` makes about the stage rather than the package: SOURCE-and-EXTRACT is where + Go stops, and nothing downstream of either extractor knows what an import or a statement is. +- WHY: the install section's "the only direct dependency is `golang.org/x/tools`" is a sentence somebody chooses + this library on, so it is read out of `go.mod` — every requirement not marked `// indirect` has to be named in + the README. The first draft said "no third-party dependency beyond `golang.org/x/tools`", which quietly reads as + *nothing else gets into your module graph* while `golang.org/x/mod` and `golang.org/x/sync` come along + indirectly. The module path and the Go version are read out of `go.mod` for the same reason, one line lower down: + an install instruction naming a path this module does not have stops a reader at the first thing they type. diff --git a/README.md b/README.md index 94f26d0..5bc7696 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,524 @@ [![CI](https://github.com/LukasNiessen/ArchUnitGo/actions/workflows/ci.yml/badge.svg)](https://github.com/LukasNiessen/ArchUnitGo/actions/workflows/ci.yml) -Architecture testing for Go. Part of **ArchUnitEverything** — one architecture-testing library per language. - -> Early development. Nothing to install yet. +Architecture rules as ordinary Go unit tests. Write the sentence your team already says out loud — +*the api does not touch the database* — as a value, and let `go test` tell you where the code +disagrees. +ArchUnitGo is the Go member of **ArchUnitEverything**, one architecture-testing library per language. Siblings: [ArchUnitTS](https://github.com/LukasNiessen/ArchUnitTS) · -[ArchUnitPython](https://github.com/LukasNiessen/ArchUnitPython) +[ArchUnitPython](https://github.com/LukasNiessen/ArchUnitPython). + +- [Install](#install) +- [Your first rule](#your-first-rule) +- [What a failure looks like](#what-a-failure-looks-like) +- [The grammar](#the-grammar) +- [Patterns and identifiers](#patterns-and-identifiers) +- [One example per family](#one-example-per-family) + - [Files](#files) · [Layers](#layers) · [Slices](#slices) · [Metrics](#metrics) · [Dependency graph](#dependency-graph) +- [A whole suite](#a-whole-suite) +- [Without a test framework](#without-a-test-framework) +- [Check options](#check-options) +- [Keeping one import out of the graph](#keeping-one-import-out-of-the-graph) +- [When a rule selects nothing](#when-a-rule-selects-nothing) +- [What is not implemented yet](#what-is-not-implemented-yet) +- [The map](#the-map) + +## Install + +```sh +go get github.com/LukasNiessen/ArchUnitGo +``` + +Go 1.26 or newer. The only direct dependency is `golang.org/x/tools`, which is how the extractor talks +to the Go toolchain. There is no tagged release yet, so `go get` resolves to a pseudo-version of +`main` and the API may still move. + +The package is `archunit` while the last element of the module path is `ArchUnitGo`, so give the +import the name it has: + +```go +import archunit "github.com/LukasNiessen/ArchUnitGo" +``` + +## Your first rule + +```go +package architecture_test + +import ( + "testing" + + archunit "github.com/LukasNiessen/ArchUnitGo" +) + +func TestTheApiDoesNotTouchTheDatabase(t *testing.T) { + rule := archunit.ProjectFiles(nil). + InFolder("internal/api/**"). + ShouldNot(). + DependOnFiles(). + InFolder("internal/db/**") + + archunit.AssertPasses(t, rule, nil) +} +``` + +That is the whole setup. There is nothing to register, nothing to configure and no fixture to build: + +- **A rule is a value.** Building one does no work; only the terminal — `AssertPasses` here, or + `Check` — reads the project. Half-built rules can be stored in a variable and branched from. +- **`nil` means the defaults, everywhere.** The `*ProjectLocator` an entry point takes is `nil` for + *the project this test is in*, found by walking up to the nearest `go.mod`. The `*AssertOptions` and + `*CheckOptions` a terminal takes are `nil` for the defaults. +- **A failing rule is not an error.** `Check` returns `([]Violation, error)`; the violations are the + rule's result and the error is the library or the environment failing. `AssertPasses` turns the + first into `t.Error` and the second into a message saying the check could not be run at all. + +## What a failure looks like + +One `t.Error`, carrying the rule as it was written and then the violations, numbered from one: + +``` +project files, path without filename matches "internal/api/**", should not, depend on files, path without filename matches "internal/db/**" +1 violation: + 1. internal/api/handler.go: should not, depend on files, path without filename matches "internal/db/**"; it depends on internal/db/conn.go +``` + +The rule's own sentence is the first line, so a test that asserts several rules says which one broke +before it says what broke it. A selector renders as the part of an identifier it matches rather than as the +verb that spelled it — `InFolder` reads back as *path without filename matches* — because that is what a +reader has to compare their glob against. Violations carry data rather than prose — the offending file, the +requirement as a compiled pattern, what was found instead — and all phrasing happens in one place, so +`AssertOptions.Message` is where colour (`archunit.DefaultPalette()`) and a violation limit live. + +## The grammar + +Every rule is an English sentence, read left to right, and every family spells the same stages: + +| Stage | How many | Example | +|---|---|---| +| **Entry** | exactly 1 | `ProjectFiles(nil)`, `Layers(nil)`, `ProjectSlices(nil)`, `Metrics(nil)`, `ProjectGraph(nil)` | +| **Scope** | 0..n, chainable, AND | `InFolder("internal/api/**")`, `WithName("*_handler.go")` | +| **Exclusion** | 0..n, after any selector | `Except("**/generated")`, `ExceptWithName("*_gen.go")` | +| **Mood** | exactly 1 | `Should()`, `ShouldNot()` | +| **Predicate** | exactly 1 | `HaveNoCycles()`, `DependOnFiles()`, `AdhereTo(f, "…")` | +| **Object** | 1..n, chainable, AND | `InFolder("internal/db/**")` after `DependOnFiles()` | +| **Terminal** | exactly 1 | `Check(nil)`, `Measure(nil)`, `Snapshot()`, `ExportAsHTML(path)` | + +The vocabulary is fixed, and deliberately small: + +- **Mood is exactly two words**, `Should` and `ShouldNot`. No synonyms, ever. The two builders are one + assertion with a flag, so every predicate that has a meaningful negation is on both. +- **Predicates are bare infinitives**, so that mood plus predicate reads as English: `HaveNoCycles`, + `HaveName`, `BeInFolder`, `BeInPath`, `AdhereTo`, `DependOnFiles`, `DependOnExternalModules`, + `ContainDependency`, `AdhereToDiagram`, `MayOnlyDependOnLayers`, `MayNotDependOnLayers`. +- **Threshold predicates are exactly six**, metrics only, and each spells its own mood: `ShouldBeBelow`, + `ShouldBeAbove`, `ShouldBe`, `ShouldBeBelowOrEqual`, `ShouldBeAboveOrEqual`, `ShouldSatisfy`. +- **Modifiers are present participles**, chainable, order-independent and always optional: + `IncludingExternalDependencies`, `FocusOn`, `ReachableFrom`, `DependentsOf`, `CollapseToFolderDepth`, + `CollapseByPattern`, `Titled`, `WithCheckOptions`, `IgnoringOrphanSlices`, `IgnoringExternalSlices`. +- **`Except` qualifies the selector in front of it** and nothing else, it is repeatable, and its + patterns are read against the same part of an identifier as that selector unless a targeted form — + `ExceptWithName`, `ExceptInFolder`, `ExceptInPath`, `ExceptClassesMatching` — names a target of its + own. That is what keeps *everything under `app/`, but not the generated folder* one clause instead + of an inverted rule about the generated folder. +- **Builders are immutable**, so a scope is worth typing once: + + ```go + api := archunit.ProjectFiles(nil).InFolder("internal/api/**") + noDb := api.ShouldNot().DependOnFiles().InFolder("internal/db/**") + small := api.Should().AdhereTo(under400Lines, "be at most 400 lines long") + ``` + +## Patterns and identifiers + +A file is identified by its path relative to the project root, always with forward slashes: +`internal/api/handler.go`. A declared type — `classes`, in the family's vocabulary — is +`internal/api.Handler`. + +Patterns are globs, and globs are sugar for regex: every one of them compiles to an anchored regular +expression in one place, so nothing downstream ever sees a glob. + +| Glob | Means | +|---|---| +| `*` | any run of characters inside one segment, never crossing `/` | +| `**` | any run of characters, crossing `/`; `a/**` matches `a` itself as well as `a/b/c` | +| `?` | exactly one character, never `/` | +| `[a-z]`, `[!abc]` | one character from a class, or not from it | +| `(**)`, `(*)` | in a slicing only: the part of the identifier to cut a slice name out of | + +Everything else is literal, matching is case-sensitive, and there is no escape character — separators +are normalised, so `internal\api\**` and `internal/api/**` are the same glob on every platform. + +Which part of the identifier a pattern is matched against is the selector's business, and the +violation message names it: + +| Verb | Matches against | `internal/api/handler.go` | +|---|---|---| +| `WithName` | the filename | `handler.go` | +| `InFolder` | everything but the filename | `internal/api` | +| `InPath` | the whole identifier | `internal/api/handler.go` | +| `InFile` | the whole identifier, as a literal | — | +| `ForClassesMatching` | the declared name alone | `Handler` | + +`DefinedByRegex` and `SliceByRegex` take Go's own `regexp` syntax instead, for the patterns a glob +cannot spell. + +## One example per family + +### Files + +The file-level family: what depends on what, how files are named and where they live. + +```go +// A boundary, with one documented door in it. +rule := archunit.ProjectFiles(nil). + InFolder("internal/api/**"). + Except("**/generated"). + ShouldNot(). + DependOnFiles(). + InFolder("internal/db/**"). + ExceptInFolder("internal/db/dto/**") + +// No file depends on another in a circle. `HaveNoCycles` is offered on the positive mood alone. +cycles := archunit.ProjectFiles(nil).Should().HaveNoCycles() + +// Naming and placement. +naming := archunit.ProjectFiles(nil).InFolder("internal/api/**").Should().HaveName("*_handler.go") + +// Third-party policy: the object verb `Matching` is repeatable and combined with OR, which is the one +// chain in this library that widens rather than narrows. +external := archunit.ProjectFiles(nil). + InFolder("internal/domain/**"). + ShouldNot(). + DependOnExternalModules(). + Matching("*.*/**") + +// The escape hatch: your own predicate over one file, and the words to report it by. +custom := archunit.ProjectFiles(nil). + InFolder("internal/**"). + Should(). + AdhereTo(func(file archunit.FileInfo) bool { + return file.NonBlankLineCount <= 400 + }, "be at most 400 lines long") +``` + +`FileInfo` carries `Path`, `Name`, `Extension`, `Directory`, `Source` and `NonBlankLineCount`, so a +predicate can ask about the text of a file as well as its place. + +### Layers + +A named-layer policy: declare who exists, then say what each layer may depend on. The whole policy is +one rule. + +```go +rule := archunit.ProjectLayers(nil). + Layer("api").DefinedByFolder("internal/api/**"). + Layer("domain").DefinedByFolder("internal/domain/**"). + Layer("db").DefinedByFolder("internal/db/**"). + WhereLayer("api").MayOnlyDependOnLayers("domain", "db"). + WhereLayer("domain").MayOnlyDependOnLayers() +``` + +There is no mood stage here: `MayOnlyDependOnLayers` is the allowlist and `MayNotDependOnLayers` the +blocklist, so a mood before them would read as *should not, may not*. Dependencies inside a layer are +always allowed, a dependency with an end in no declared layer is ignored, and +`MayOnlyDependOnLayers()` with nothing named is the sealed layer. Every layer has to be declared +before the first clause. A violation is one per pair of layers rather than one per import, carrying +the concrete file dependencies that connect them. + +### Slices + +A slice is a name cut out of an identifier by the capture in the slicing pattern. Nothing is declared: +`internal/(**)/**` says that this project's slices are its folders under `internal`, so +`internal/api/handler.go` is in the slice `api` and a file the pattern does not match is in no slice +at all. + +```go +rule := archunit.ProjectSlices(nil). + DefinedBy("internal/(**)/**"). + ShouldNot(). + ContainDependency("api", "db") +``` + +The other rule a slicing can be asked for is the whole architecture at once, against the PlantUML +component diagram somebody drew of it: + +```go +rule := archunit.ProjectSlices(nil). + DefinedBy("internal/(**)/**"). + Should(). + AdhereToDiagramInFile("docs/architecture.puml"). + IgnoringOrphanSlices() +``` + +...and the reverse, which draws the diagram out of the project as it is: + +```go +err := archunit.ProjectSlices(nil). + DefinedBy("internal/(**)/**"). + ExportAsPlantUML("docs/architecture.puml", nil) +``` + +`ProjectSlices` has no shorter alias, unlike `Files` and `Layers`: `slices` is the name of a standard +library package, and a chain starting with it would read as one. + +### Metrics + +The numbers a project's code adds up to, and what they have to be. + +```go +// Eight counting metrics: LinesOfCode, Statements, Imports, Functions, Classes, Interfaces, +// MethodCount, FieldCount. +rule := archunit.Metrics(nil). + InFolder("internal/**"). + Count(). + LinesOfCode(). + ShouldBeBelow(400) + +// Five distance metrics about a package: Abstractness, Instability, DistanceFromMainSequence, +// NormalizedDistance, CouplingFactor — plus the two zone checks, ShouldNotBeInZoneOfPain and +// ShouldNotBeInZoneOfUselessness, where the corner and the mood are one verb. +zone := archunit.Metrics(nil).Distance().ShouldNotBeInZoneOfPain() +useless := archunit.Metrics(nil).InFolder("internal/**").Distance().ShouldNotBeInZoneOfUselessness() + +// The numbers themselves, without a threshold: one Measurement per file, class or folder. +measurements, err := archunit.Metrics(nil).InFolder("internal/api/**").Count().LinesOfCode().Measure(nil) + +// A metric of your own, judged by a comparison of your own. +surface := archunit.Metrics(nil). + ForClassesMatching("*Service"). + CustomMetric("public surface", "how many methods and fields a type exposes", + func(class archunit.MetricsClassInfo) float64 { + return float64(class.MethodCount + class.FieldCount) + }). + ShouldSatisfy(func(measurement archunit.Measurement, class archunit.MetricsClassInfo) bool { + return measurement.Value <= 20 || class.Interface + }, "expose at most 20 methods and fields unless it is an interface") + +// Either group also closes without naming a metric, and then the chain is a report rather than a rule: +// every number of the group over the one scope, as one self-contained HTML page. +err = archunit.Metrics(nil).InFolder("internal/**").Count().ExportAsHTML("build/metrics.html", nil) +``` + +`Metrics` is the family's only spelling of its entry point. Its four scope verbs — `WithName`, +`InFolder`, `InPath`, `ForClassesMatching` — are chainable and combined with AND, three describing +files and the last describing declared types; an exclusion is about the same population as the verb it +qualifies. `NewMetricsExporter` writes the same page from measurements you have already taken and +grouped your own way. + +### Dependency graph + +Not every chain is a rule. `ProjectGraph` describes a report, so it has no mood, no predicate and no +violations — its terminals hand back the diagram. + +```go +snapshot, err := archunit.ProjectGraph(nil). + FocusOn("internal/api/**", 1). + CollapseToFolderDepth(2). + Titled("what the api layer touches"). + Snapshot() + +fmt.Println(snapshot.Summary()) // 12 nodes, 18 edges, 143 dependencies + +err = archunit.DependencyGraph(nil). + CollapseToFolderDepth(2). + Titled("the modules of this project"). + ExportAsHTML("build/architecture.html") +``` + +Nine modifiers, all optional and order-independent: `IncludingExternalDependencies`, +`IncludingSelfDependencies`, `FocusOn`, `ReachableFrom`, `DependentsOf`, `CollapseToFolderDepth`, +`CollapseByPattern`, `Titled`, `WithCheckOptions`. The default report is one node per file of the +project's own code, and each modifier either narrows what the diagram draws, widens it — +`IncludingExternalDependencies` adds the code outside the project and `IncludingSelfDependencies` adds a +node's dependency on itself — or says how it is labeled. A query that describes nothing is refused rather +than drawn: every terminal here fails with `ErrEmptySnapshot` unless `AllowEmptyTests` says an empty report +was meant. + +Thirteen terminals: `Snapshot()` for the report as data, `ToDot`, `ToMermaid`, `ToD2`, `ToCSV`, +`ToJSON` and `ToHTML` for it as a string, and `ExportAsDot`, `ExportAsMermaid`, `ExportAsD2`, +`ExportAsCSV`, `ExportAsJSON` and `ExportAsHTML` for it as a file. A snapshot renders the same bytes +for the same project every time, so a diagram committed beside the code is reviewable in a pull +request. + +## A whole suite + +More than one rule is a map and one call, each rule in its own named subtest: + +```go +func TestTheArchitectureHolds(t *testing.T) { + archunit.AssertAllPass(t, map[string]archunit.Checkable{ + "the api does not touch the database": archunit.ProjectFiles(nil). + InFolder("internal/api/**"). + ShouldNot(). + DependOnFiles(). + InFolder("internal/db/**"), + "no file depends on another in a circle": archunit.ProjectFiles(nil).Should().HaveNoCycles(), + }, nil) +} +``` + +A rule that does not hold fails the subtest its author named it after, and the rules around it are +asserted all the same. The subtests run in the sorted order of their names, so +`go test -run 'TestTheArchitectureHolds/no_file_depends_on_another_in_a_circle'` selects one. A suite +with no rules in it is a failure rather than a pass, for the same reason a rule that selected no file +is. + +`archunit.Checkable` is the seam the whole library hangs from — every terminal implements it, and +`Check(*CheckOptions) ([]Violation, error)` is all of it — so a helper that loops over a list of rules +never has to know which family they came from. + +## Without a test framework + +`Check` is the universal terminal, and the report layer is separate from it: + +```go +violations, err := rule.Check(nil) +if err != nil { + return err +} +if result := archunit.NewResultFactory(nil).Result(violations); !result.Passed { + fmt.Println(result.Message) +} +``` + +`Violation`'s whole contract is `Kind()`, so a caller can group and count without asserting on a +concrete type — `archunit.KindFileDependency`, `archunit.KindEmptyTest` and the ten others — or type +switch on `archunit.FileDependencyViolation` and its siblings for the data itself. +`NewViolationFactory` phrases one violation at a time, for a report of your own shape. + +## Check options + +One options bag, and `nil` is always the defaults. Every default is a zero value, so a check is quiet, +strict about empty selections, free to reuse a cached graph, and looks at the production code under +the host platform's build constraints. + +```go +violations, err := rule.Check(&archunit.CheckOptions{ + AllowEmptyTests: false, // a rule that selected nothing is a violation; see below + IncludeTestFiles: true, // hold _test.go files to the same rules + BuildTags: []string{"linux"}, // the constraints to analyze under + IgnoreScopes: []string{"layers"}, + ClearCache: true, + Logging: &archunit.LogOptions{Writer: os.Stderr, Level: archunit.LogLevelDebug}, +}) +``` + +`AssertOptions` is the two bags each half already has — `Check` for how the rule is run, `Message` for +how a failure is written — so `archunit.AssertPasses(t, rule, &archunit.AssertOptions{...})` needs no +vocabulary of its own. + +Extraction is the expensive half of a check and every rule in a suite asks about the same project, so +the graph is memoised per process. `ClearCache`, or `archunit.ClearGraphCache()`, is for source that +changed underneath the library — a test that writes a fixture project, generated code produced between +two checks. + +Logging is off by default and there is no way to turn it on globally: the destination is injected per +check, so one test can assert on a log while the rest of the suite runs beside it. `LogOptions` also +holds the file a CI job archives, and the four levels are `LogLevelDebug`, `LogLevelInfo` (the +default), `LogLevelWarn` and `LogLevelError`. A technical failure is still the error `Check` returns; +a log line is never how this library reports something. + +## Keeping one import out of the graph + +Some imports are not dependencies. The directive is written the way Go writes a machine-readable +comment, so `gofmt` leaves it where you put it: + +```go +import ( + "database/sql" + + _ "github.com/lib/pq" //archunit:ignore +) +``` + +A bare directive is honoured by every rule. A scoped one — `//archunit:ignore layers` — is honoured +only by a check that names that scope in `CheckOptions.IgnoreScopes`, and counts as an ordinary +dependency everywhere else. The directive belongs to the one import it is written on, either trailing +it or on a comment-only line directly above it. + +## When a rule selects nothing + +**Zero matches is a violation, not a pass.** A selector matching no file is almost always a stale glob or a +renamed folder, and such a rule is green forever — so the guard is wired into every terminal, in whichever of +its two shapes that terminal has room for: + +- **A terminal that returns violations reports an `EmptyTestViolation`**, which is `Check` in every family. +- **A report terminal fails with an error**, because a report has no violation list to put a violation in: + `ErrEmptySnapshot` for the graph family's `Snapshot` and every `To*` and `ExportAs*` built on it, + `ErrEmptyReport` for the metrics family's `ExportAsHTML`, and `ErrNothingToDraw` for the slices family's + `ToPlantUML` and `ExportAsPlantUML`. + +`CheckOptions.AllowEmptyTests` opts out of both. The one terminal that reports emptiness neither way is +`Measure`, deliberately: it judges nothing, so whether an empty selection is a failure is not a question it +can ask — its result is the numbers themselves, and no subject is no numbers. + +To see what a selector actually resolves to, ask the scope stage rather than the rule: + +```go +files, err := archunit.ProjectFiles(nil).InFolder("internal/api/**").SelectFiles(nil) +membership, err := archunit.ProjectLayers(nil).Layer("api").DefinedByFolder("internal/api/**").SelectLayerFiles(nil) +slices, err := archunit.ProjectSlices(nil).DefinedBy("internal/(**)/**").SelectSliceFiles(nil) +``` + +Every stage of a chain that can describe itself is a `fmt.Stringer`, and prints the sentence it has become +so far — including the first thing it rejected, so a pattern that will not compile says so when the chain is +printed as well as when it is checked. The one stage that cannot is `LayerPolicyBuilder`, the clause caught +between `WhereLayer` and its predicate: it has named a layer and not yet said anything about it, so there is +no sentence of its own for it to print. + +## What is not implemented yet + +Documented from the source, so this list is what is actually missing today: + +- **No tagged release.** `go get` resolves to a pseudo-version of `main`, and names may still change. +- **Files are the node vocabulary.** There are no package-level selectors, and no rule about a + declared type's own dependencies. The metrics family reaches beyond files — its distance metrics are + about a folder and `ForClassesMatching` selects declared types — but a rule of the files family is + always about files. +- **The LCOM family has no fluent verb.** The eight measures live in `metrics/calculation` as plain + functions — `LCOM96a`, `LCOM96b`, `LCOM1`…`LCOM5`, `LCOMStar` — and are not on the public surface. + Until a `cohesion` group lands, the way to hold code to one is `CustomMetric` with your own function. +- **The slices family has no `Except`.** The other four have it: four spellings in the files family, + five in metrics, three in layers, and the plain verb in the graph module. +- **Two of the exported slicings have no `DefinedBy` verb.** `SliceByFileSuffix` and `Identity` are + `MapFunction` values a caller can hold, but the fluent slicing verbs are `DefinedBy` and + `DefinedByRegex` alone. +- **The import kinds are not on the public surface.** `CheckOptions.IgnoredImportKinds` takes an + `extraction.ImportKindSet`, so dropping blank imports before extraction means importing + `common/extraction` directly. +- **Diagrams are read in one format and written in seven.** `AdhereToDiagram` parses PlantUML + component diagrams; the graph module renders DOT, Mermaid, D2, CSV, JSON and HTML, and the slices + module renders PlantUML, but nothing reads any of the other six back. +- **Everything is synchronous** and analysis is single-project: a rule is about one module, found by + walking up to the nearest `go.mod`. + +## The map + +The whole product is the fluent API; everything else is its implementation. The pipeline is +`SOURCE -> EXTRACT -> PROJECT -> ASSERT -> REPORT`, and the SOURCE-and-EXTRACT stage is the only part that +knows Go — `common/extraction` for the dependency graph, and `metrics/extraction` for what is inside one +file. Nothing downstream of either knows what an import or a statement is. + +``` +common/ the kernel — extraction, projection, assertion, matching, logging +files/ file-level dependency and naming rules +layers/ named-layer policy +slices/ component and diagram rules +metrics/ numeric code-quality rules +graph/ dependency-graph reports +archtest/ violation formatting and test-framework glue +archunit.go the public surface — re-exports, nothing else +``` + +Every domain module has the same internal shape — `fluentapi/` is the only public part, with +`assertion/`, `projection/`, `extraction/` and `calculation/` behind it — so reading one module +teaches you how to navigate all of them. + +[AGENTS.md](AGENTS.md) is the authority on the architecture, the naming and the shape of the API, for +this library and for every other ArchUnit port. It is what to read before changing anything here. + +This repository enforces its own architecture on itself: +[architecture_test.go](architecture_test.go) is the four dependency rules of `AGENTS.md` written as a +suite through this public surface, and it is the library's best worked example. diff --git a/archtest/assert_all_pass.go b/archtest/assert_all_pass.go index acafe95..95683a0 100644 --- a/archtest/assert_all_pass.go +++ b/archtest/assert_all_pass.go @@ -62,9 +62,9 @@ type TestingRunner interface { // // --- FAIL: TestTheArchitectureHolds (0.62s) // --- FAIL: TestTheArchitectureHolds/the_api_does_not_touch_the_database (0.59s) -// project files, in folder "internal/api/**", should not, depend on files, in folder "internal/db/**" +// project files, path without filename matches "internal/api/**", should not, depend on files, path without filename matches "internal/db/**" // 1 violation: -// 1. internal/api/handler.go: should not, path without filename matches "internal/db"; it depends on internal/db/conn.go +// 1. internal/api/handler.go: should not, depend on files, path without filename matches "internal/db/**"; it depends on internal/db/conn.go // // The suite is a map from the name to the rule, and its rules are asserted in the sorted order of their // names. A map is what keeps a name and the rule it belongs to together at the call site, and what makes two diff --git a/archtest/assert_passes.go b/archtest/assert_passes.go index 2eabe03..67533d6 100644 --- a/archtest/assert_passes.go +++ b/archtest/assert_passes.go @@ -63,9 +63,9 @@ type helper interface { // that did not. A rule that does not hold is one t.Error, carrying the rule as the user wrote it and then // the whole report — the count, and the violations numbered from one: // -// project files, in folder "internal/api/**", should not, depend on files, in folder "internal/db/**" +// project files, path without filename matches "internal/api/**", should not, depend on files, path without filename matches "internal/db/**" // 1 violation: -// 1. internal/api/handler.go: should not, depend on files, path without filename matches "internal/db"; it depends on internal/db/conn.go +// 1. internal/api/handler.go: should not, depend on files, path without filename matches "internal/db/**"; it depends on internal/db/conn.go // // The rule's own sentence is the first line because a test that asserts several rules, or asserts one in a // loop, otherwise reports a list of files with nothing saying which sentence they broke. It is left out when diff --git a/archunit.go b/archunit.go index 9113523..fa27102 100644 --- a/archunit.go +++ b/archunit.go @@ -744,8 +744,10 @@ func Metrics(locator *ProjectLocator) MetricsBuilder { // // The nine modifiers are all optional, chainable and order-independent — `including external dependencies`, // `including self dependencies`, `focus on`, `reachable from`, `dependents of`, `collapse to folder depth`, -// `collapse by pattern`, `titled` and `with check options` — and each of them narrows what the diagram draws -// or says how it is labeled. The default report is one node per file of the project's own code. +// `collapse by pattern`, `titled` and `with check options` — and each of them narrows what the diagram draws, +// adds the code outside the project or a node's dependency on itself, or says how it is labeled. The default +// report is one node per file of the project's own code, so the two `including` verbs are the two that widen +// it. // // The four that take a pattern each take `except`, which qualifies the one the chain wrote most recently: it is // how a diagram leaves out the generated packages, and how `collapse by pattern "third party" "**"` keeps one diff --git a/readme_test.go b/readme_test.go new file mode 100644 index 0000000..c414009 --- /dev/null +++ b/readme_test.go @@ -0,0 +1,813 @@ +package archunit_test + +import ( + "go/ast" + "go/parser" + "go/token" + "go/types" + "os" + "path/filepath" + "regexp" + "slices" + "strconv" + "strings" + "testing" +) + +// This file is README.md held to the source it describes, by the same argument ci_test.go makes about +// the workflow: a document nobody can fail is a document that goes stale in the commit that changes +// the code. Issue #41 names the failure mode it exists to prevent — a sibling port's README documents +// a slice API that does not exist — and that is not a mistake somebody made while writing it. It is +// what a hand-checked document becomes after a few months of a moving API. +// +// So every Go identifier README.md names is looked up in this module's own syntax tree, every example +// in it is parsed, and the sentences that say a thing is *absent* are checked against the absence. The +// library is read with go/parser rather than reflection, because reflection cannot see a package-level +// function, a method nobody called or a struct field's name, and those are most of what a README says. +// +// Nothing here type-checks the examples. A snippet is written for a reader's project — `internal/api`, +// `docs/architecture.puml`, a predicate over the reader's own files — so the names it uses from this +// library are what can be verified, and they are verified exactly: `archunit.X` against the public +// surface, and every method of a chain rooted at `archunit` against the methods this module declares. + +const ( + // readmeFile is the document under test. + readmeFile = "README.md" + // surfaceFile is the public surface, and the only file a README example may name a symbol from + // directly. AGENTS.md: it re-exports and does nothing else. + surfaceFile = "archunit.go" + // moduleFile is where the install instruction's module path and Go version have to agree with. + moduleFile = "go.mod" + // surfacePackage is the name a README example imports the public surface under. The package is + // `archunit` while the last element of the module path is `ArchUnitGo`, so every example gives the + // import that name and every chain in one starts with this identifier. + surfacePackage = "archunit" +) + +// TestTheReadmeExamplesAreValidGo parses every ```go block of the README. An example that does not +// parse is worse than no example: a reader copies it, the compiler complains about the document rather +// than about their code, and they have no way to tell which of the two is wrong. +// +// A block is accepted as a whole file, as a file with the package clause left off — which is how the +// import example showing the ignore directive is written — or as the body of a function, which is how +// every rule in the document is written. Nothing here says which of the three a block has to be, +// because that is the author's business and all three read correctly on the page. +func TestTheReadmeExamplesAreValidGo(t *testing.T) { + for number, block := range goBlocksOfTheReadme(t) { + if _, err := parseExample(block); err != nil { + t.Errorf("the %s Go example in %s does not parse: %v\n%s", ordinal(number+1), readmeFile, err, block) + } + } +} + +// TestTheReadmeNamesOnlySymbolsThePublicSurfaceHas is the guard against the failure issue #41 names: +// a document describing an API the library does not have. +// +// Every `archunit.X` in an example has to be an exported name of archunit.go, and every method of a +// chain that starts there has to be a method this module declares. That covers the whole of what an +// example can get wrong about this library — a renamed verb, a predicate that moved to the other mood, +// a terminal that never existed — and it costs a parse of the tree the reader is being pointed at. +func TestTheReadmeNamesOnlySymbolsThePublicSurfaceHas(t *testing.T) { + declared := declarationsOfThisModule(t) + + for number, block := range goBlocksOfTheReadme(t) { + example, err := parseExample(block) + if err != nil { + continue // TestTheReadmeExamplesAreValidGo reports this one. + } + + for _, selection := range selectionsRootedAtTheSurface(example) { + if selection.onThePackage && !declared.surface[selection.name] { + t.Errorf("the %s Go example in %s uses %s.%s, which %s does not export", + ordinal(number+1), readmeFile, surfacePackage, selection.name, surfaceFile) + } + if !selection.onThePackage && !declared.methods[selection.name] { + t.Errorf("the %s Go example in %s calls .%s() on a chain from %s, and this module declares no such method", + ordinal(number+1), readmeFile, selection.name, surfacePackage) + } + } + for _, field := range fieldNamesOfTheLiterals(example) { + if !declared.names[field] { + t.Errorf("the %s Go example in %s fills in the field %s, which this module declares nowhere", + ordinal(number+1), readmeFile, field) + } + } + } +} + +// TestTheReadmeNamesOnlyIdentifiersThisModuleDeclares is the same guard over the prose, where most of +// a README's names actually are: the grammar table, the verb lists, the fields of an options bag. +// +// Every `Backticked` word that looks like an exported Go identifier has to be something this module +// declares — a function, a type, a constant, a method or a struct field — and a word the document wrote as +// `archunit.X` has to be on the public surface, because that spelling is a promise that a user reaches it +// without importing anything else. A pointer is the type it points at and a qualifier is stepped over, so +// `*CheckOptions` is checked as `CheckOptions` and `CheckOptions.IgnoredImportKinds` as the field. The one +// thing exempted is a segment of the module path, because `ArchUnitGo` is the repository's name and not an +// identifier. +// +// Prose is otherwise checked against the whole module and not against the public surface, because the +// document legitimately names things behind it: the eight LCOM functions it says have no fluent verb yet are +// exactly such names, and a test that demanded they be re-exported would be asking for the opposite of +// what that sentence says. +func TestTheReadmeNamesOnlyIdentifiersThisModuleDeclares(t *testing.T) { + declared := declarationsOfThisModule(t) + exempt := append(strings.Split(modulePathOfThisRepository(t), "/"), namesOfTheReadersProject...) + + for _, named := range identifiersTheReadmeProseNames(t) { + if slices.Contains(exempt, named.name) { + continue + } + switch { + case named.onTheSurface && !declared.surface[named.name]: + t.Errorf("%s names `%s`, and %s exports nothing by that name", readmeFile, named.spelled, surfaceFile) + case !named.onTheSurface && !declared.names[named.name]: + t.Errorf("%s names `%s` as an identifier of this library, and this module declares nothing by that name", + readmeFile, named.spelled) + } + } +} + +// TestTheReadmeInstallsThisModuleTheWayGoModDescribesIt pins the three facts of the install section +// that live in go.mod: the path a user types, the Go version they need, and every dependency they take +// on with it. +// +// The last of those is the one worth a test. "The only direct dependency is golang.org/x/tools" is a +// sentence a reader chooses this library on, and it stops being true in a commit that has nothing to do +// with the README. +func TestTheReadmeInstallsThisModuleTheWayGoModDescribesIt(t *testing.T) { + readme := readTheReadme(t) + module := readTheModuleFile(t) + + for _, required := range []string{ + "go get " + modulePathOfThisRepository(t), + "Go " + valueOfTheModuleDirective(t, "go") + " or newer", + } { + if !strings.Contains(readme, required) { + t.Errorf("%s does not say %q, which is what %s says", readmeFile, required, moduleFile) + } + } + + for _, dependency := range directRequirementsOfThisRepository(t) { + if !strings.Contains(readme, dependency) { + t.Errorf("%s takes a direct dependency on %s and %s does not mention it: the install section says which "+ + "dependencies come with this library", moduleFile, dependency, readmeFile) + } + } + if strings.Contains(module, "// indirect") && !strings.Contains(readme, "direct dependency") { + t.Errorf("%s does not distinguish direct from indirect dependencies, and %s has both", readmeFile, moduleFile) + } +} + +// TestTheReadmeNamesEveryVerbOfTheClosedSetsItDescribes is the completeness half, for the two families +// whose surface the README states as a closed set rather than as an example. +// +// The metrics family's `Should` verbs are the six threshold predicates and the two zone checks, and the +// README says in as many words that there is no seventh threshold predicate — so a verb added there +// makes that sentence false. The graph family is thirteen terminals and nine modifiers in one type, +// with no mood and no predicate to pass through, so its whole surface is a list a reader picks from and +// a name missing from the document is a name they cannot find at all. +// +// Membership is exact rather than a substring search, and the two counts the sentences state are recomputed +// off the receivers, for the reason TestTheReadmeCountsTheGraphFamilyCorrectly recomputes nine and thirteen: +// `strings.Contains(readme, "ShouldBe")` is satisfied by a document that only names `ShouldBeBelow`, and a +// sentence saying there are six of something is pinned by nothing until somebody counts them. +// +// `String` is exempt from the graph list: the README says once, of every stage of a chain that can describe +// itself, that it is a fmt.Stringer, and repeating it per family would be noise. +func TestTheReadmeNamesEveryVerbOfTheClosedSetsItDescribes(t *testing.T) { + readme := readTheReadme(t) + declared := declarationsOfThisModule(t) + named := namesTheReadmeNames(t) + + for _, verb := range declared.methodsOf("metrics/fluentapi") { + if !strings.HasPrefix(verb.name, "Should") { + continue + } + if !named[verb.name] { + t.Errorf("metrics/fluentapi declares the predicate %s and %s does not name it: the README says the "+ + "threshold verbs are a closed set of six, so a seventh has to change that sentence", verb.name, readmeFile) + } + } + + for _, verb := range declared.methodsOf("graph/fluentapi") { + if verb.name == "String" { + continue + } + if !named[verb.name] { + t.Errorf("graph/fluentapi declares %s and %s does not name it: the report family is one type, so its "+ + "whole surface is the list a reader picks from", verb.name, readmeFile) + } + } + + for _, counted := range []struct { + sentence string + receiver string + spelled int + }{ + {sentence: "Threshold predicates are exactly six", receiver: "MetricBuilder", spelled: 6}, + {sentence: "the two zone checks", receiver: "MetricsDistanceBuilder", spelled: 2}, + } { + var found []string + for _, verb := range declared.methodsOf("metrics/fluentapi") { + if verb.receiver == counted.receiver && strings.HasPrefix(verb.name, "Should") { + found = append(found, verb.name) + } + } + if !strings.Contains(readme, counted.sentence) { + t.Errorf("%s no longer says %q, so nothing here checks the number it states", readmeFile, counted.sentence) + } + if len(found) != counted.spelled { + t.Errorf("%s says %q and %s has %d of them: %v", + readmeFile, counted.sentence, counted.receiver, len(found), found) + } + } +} + +// TestTheReadmeCountsTheGraphFamilyCorrectly is the sentence AGENTS.md warns about most — prose that +// counts or bounds a surface — held to the count. +// +// The README says the report family is nine modifiers and thirteen terminals. Both numbers are read off +// the type here rather than trusted: a modifier is a method that hands back another builder, a terminal +// is one that hands back a report or an error, and `Except` is neither because an exclusion qualifies +// the modifier in front of it. +func TestTheReadmeCountsTheGraphFamilyCorrectly(t *testing.T) { + readme := readTheReadme(t) + var modifiers, terminals []string + + for _, method := range declarationsOfThisModule(t).methodsOf("graph/fluentapi") { + switch { + case strings.HasPrefix(method.name, "Except"): + case method.results() == "GraphBuilder": + modifiers = append(modifiers, method.name) + case strings.HasSuffix(method.results(), "error"): + terminals = append(terminals, method.name) + } + } + + for _, counted := range []struct { + sentence string + found []string + spelled int + }{ + {sentence: "Nine modifiers", found: modifiers, spelled: 9}, + {sentence: "Thirteen terminals", found: terminals, spelled: 13}, + } { + if !strings.Contains(readme, counted.sentence) { + t.Errorf("%s no longer says %q, so nothing here checks the number it states", readmeFile, counted.sentence) + } + if len(counted.found) != counted.spelled { + t.Errorf("%s says %q and graph/fluentapi has %d of them: %v", + readmeFile, counted.sentence, len(counted.found), counted.found) + } + } +} + +// TestTheReadmeIsHonestAboutWhatIsMissing checks the section a README normally has no way of being +// wrong about safely: the list of what is not implemented yet. +// +// A sentence saying a thing is absent goes stale in the happiest possible way — somebody implements the +// thing — and then the document is telling a reader not to look for a verb that is right there. Each +// row below is one claim of that section, and it fails the day the claim stops being true. +func TestTheReadmeIsHonestAboutWhatIsMissing(t *testing.T) { + declared := declarationsOfThisModule(t) + fluentFamilies := []string{ + "files/fluentapi", "layers/fluentapi", "slices/fluentapi", "metrics/fluentapi", "graph/fluentapi", + } + + for _, family := range fluentFamilies { + for _, verb := range declared.methodsOf(family) { + switch { + case strings.HasPrefix(verb.name, "LCOM"), strings.Contains(verb.name, "Cohesion"): + t.Errorf("%s declares the verb %s, and %s says the LCOM family has no fluent verb yet", + family, verb.name, readmeFile) + case strings.Contains(verb.name, "Package"): + t.Errorf("%s declares the verb %s, and %s says there are no package-level selectors yet", + family, verb.name, readmeFile) + case strings.Contains(verb.name, "FileSuffix"): + t.Errorf("%s declares the verb %s, and %s says SliceByFileSuffix has no `defined by` verb yet", + family, verb.name, readmeFile) + case family == "slices/fluentapi" && strings.HasPrefix(verb.name, "Except"): + t.Errorf("slices/fluentapi declares %s, and %s says the slices family is the one without `Except`", + verb.name, readmeFile) + } + } + } + + for name := range declared.surface { + if strings.Contains(name, "ImportKind") { + t.Errorf("%s exports %s, and %s says the import kinds are not on the public surface yet", + surfaceFile, name, readmeFile) + } + } +} + +// method is one exported method this module declares, as the tests above need it: its name, the type it +// is on, and what it hands back. +type method struct { + name string + receiver string + returns []string +} + +// results renders what the method hands back as one comma-separated string, so that a test asking +// whether a graph verb is a modifier or a terminal reads as the question it is: `GraphBuilder` is a +// modifier, anything ending in `error` is a terminal. +func (m method) results() string { + return strings.Join(m.returns, ", ") +} + +// declarations is this module's own syntax tree as the tests need to interrogate it: what the public +// surface exports, every exported method name, every exported name of any kind, and the exported +// methods of one package. +type declarations struct { + // surface is the exported top-level names of archunit.go — the only names an example may write + // after `archunit.`. + surface map[string]bool + // methods is every exported method name in the module, whatever it is on. A chain in an example is + // checked against this rather than against a receiver, because following a fluent chain's types by + // hand would be type-checking it, and that is what the compiler is for. + methods map[string]bool + // names is every exported name this module declares: functions, types, constants, variables, + // methods, interface methods and struct fields. It is what the prose is held to. + names map[string]bool + // byPackage is the exported methods of each package, keyed by its slash-separated directory. + byPackage map[string][]method +} + +// methodsOf are the exported methods this package declares, in the order they were read. +func (d declarations) methodsOf(pkg string) []method { + return d.byPackage[pkg] +} + +// declarationsOfThisModule reads every non-test Go file of the repository and collects what it declares. +// It is one parse of the tree per test that needs it, which costs a few milliseconds and buys a document +// that cannot name something the library does not have. +func declarationsOfThisModule(t *testing.T) declarations { + t.Helper() + + declared := declarations{ + surface: map[string]bool{}, + methods: map[string]bool{}, + names: map[string]bool{}, + byPackage: map[string][]method{}, + } + + for _, path := range goFilesOfThisRepository(t) { + file, err := parser.ParseFile(token.NewFileSet(), path, nil, parser.SkipObjectResolution) + if err != nil { + t.Fatalf("parsing %s failed: %v", path, err) + } + pkg := filepath.ToSlash(filepath.Dir(path)) + for _, declaration := range file.Decls { + declared.collect(pkg, path, declaration) + } + } + if len(declared.surface) == 0 { + t.Fatalf("%s declares no exported name at all, so nothing below is checking anything", surfaceFile) + } + return declared +} + +// collect files one top-level declaration under every name the tests look it up by. +func (d declarations) collect(pkg, path string, declaration ast.Decl) { + switch typed := declaration.(type) { + case *ast.FuncDecl: + if !typed.Name.IsExported() { + return + } + d.names[typed.Name.Name] = true + if typed.Recv == nil { + if path == surfaceFile { + d.surface[typed.Name.Name] = true + } + return + } + d.methods[typed.Name.Name] = true + d.byPackage[pkg] = append(d.byPackage[pkg], method{ + name: typed.Name.Name, + receiver: strings.TrimPrefix(types.ExprString(typed.Recv.List[0].Type), "*"), + returns: resultTypes(typed.Type), + }) + case *ast.GenDecl: + for _, spec := range typed.Specs { + d.collectSpec(path, spec) + } + } +} + +// collectSpec files a type, constant or variable, and the exported members of a struct or an interface. +// The members are here because most of what a README says about an options bag is its field names. +func (d declarations) collectSpec(path string, spec ast.Spec) { + switch typed := spec.(type) { + case *ast.TypeSpec: + d.declare(path, typed.Name) + switch underlying := typed.Type.(type) { + case *ast.StructType: + d.collectFields(underlying.Fields) + case *ast.InterfaceType: + d.collectFields(underlying.Methods) + } + case *ast.ValueSpec: + for _, name := range typed.Names { + d.declare(path, name) + } + } +} + +// collectFields files the exported members of a struct or an interface. An embedded field has no name +// of its own, so it is skipped: whatever it names is declared where its type is. +func (d declarations) collectFields(fields *ast.FieldList) { + if fields == nil { + return + } + for _, field := range fields.List { + for _, name := range field.Names { + if name.IsExported() { + d.names[name.Name] = true + } + } + } +} + +// declare files one exported name, and the public surface's own names twice. +func (d declarations) declare(path string, name *ast.Ident) { + if !name.IsExported() { + return + } + d.names[name.Name] = true + if path == surfaceFile { + d.surface[name.Name] = true + } +} + +// resultTypes are the types a function hands back, as they are written. +func resultTypes(signature *ast.FuncType) []string { + if signature.Results == nil { + return nil + } + var results []string + for _, result := range signature.Results.List { + results = append(results, types.ExprString(result.Type)) + } + return results +} + +// goFilesOfThisRepository are every Go file of the module except the tests, which are not what a README +// describes. +func goFilesOfThisRepository(t *testing.T) []string { + t.Helper() + + var paths []string + err := filepath.WalkDir(".", func(path string, entry os.DirEntry, err error) error { + if err != nil { + return err + } + if entry.IsDir() { + if entry.Name() == ".git" || entry.Name() == "testdata" { + return filepath.SkipDir + } + return nil + } + if strings.HasSuffix(path, ".go") && !strings.HasSuffix(path, "_test.go") { + paths = append(paths, path) + } + return nil + }) + if err != nil { + t.Fatalf("walking this repository failed: %v", err) + } + if len(paths) == 0 { + t.Fatal("this repository holds no Go file outside its tests") + } + return paths +} + +// selection is one thing a README example reads off the public surface: a name after `archunit.`, or a +// method of a chain that starts there. +type selection struct { + name string + onThePackage bool +} + +// selectionsRootedAtTheSurface are every name an example reads off this library, and nothing else. +// +// A selector expression is followed back to what it is rooted at — through calls, indexes and the +// selectors before it — and it counts only when that root is the identifier the public surface is +// imported under. That is what keeps `fmt.Println(snapshot.Summary())` out of the result while +// `archunit.ProjectFiles(nil).InFolder("x")` is fully in it: an example is checked against this library +// and never against the standard one. +func selectionsRootedAtTheSurface(example *ast.File) []selection { + var found []selection + + ast.Inspect(example, func(node ast.Node) bool { + selector, isSelector := node.(*ast.SelectorExpr) + if !isSelector { + return true + } + root, isIdentifier := chainRoot(selector.X).(*ast.Ident) + if !isIdentifier || root.Name != surfacePackage { + return true + } + qualifier, onThePackage := selector.X.(*ast.Ident) + found = append(found, selection{ + name: selector.Sel.Name, + onThePackage: onThePackage && qualifier.Name == surfacePackage, + }) + return true + }) + return found +} + +// chainRoot is what an expression is ultimately read off: the identifier at the far left of a fluent +// chain, once every call, selector, index and pair of parentheses in front of it has been stepped over. +func chainRoot(expression ast.Expr) ast.Expr { + for { + switch node := expression.(type) { + case *ast.SelectorExpr: + expression = node.X + case *ast.CallExpr: + expression = node.Fun + case *ast.IndexExpr: + expression = node.X + case *ast.ParenExpr: + expression = node.X + default: + return expression + } + } +} + +// fieldNamesOfTheLiterals are the fields an example fills in on a composite literal — the knobs of an +// options bag, which is where a README is as likely to name something stale as in a chain. +func fieldNamesOfTheLiterals(example *ast.File) []string { + var found []string + + ast.Inspect(example, func(node ast.Node) bool { + literal, isLiteral := node.(*ast.CompositeLit) + if !isLiteral { + return true + } + for _, element := range literal.Elts { + pair, isPair := element.(*ast.KeyValueExpr) + if !isPair { + continue + } + if key, isIdentifier := pair.Key.(*ast.Ident); isIdentifier && key.IsExported() { + found = append(found, key.Name) + } + } + return true + }) + return found +} + +// namesOfTheReadersProject are the backticked capitalised words of the README that name something in the +// project a reader is holding this library against, not something in the library. `Handler` is the +// declared type the match-target table walks `internal/api/handler.go` through, and a document that +// could not name one would have to explain `ForClassesMatching` without an example of a class. +// +// The list is deliberately short. Anything on it is a name nothing checks, which is the cost of writing +// an example, so a new entry is a decision rather than a way around a failing test. +var namesOfTheReadersProject = []string{"Handler"} + +// namesTheReadmeQualifiesWithSomethingElse are the backticked words of the README that read as a Go name +// qualified by something this module is not: an interface of the standard library, a package behind the +// public surface written as a user would have to import it, and a declared type of the reader's own project. +// +// They are exempt for the same reason namesOfTheReadersProject is, and the list is short for the same +// reason: each entry is a name nothing checks. +var namesTheReadmeQualifiesWithSomethingElse = []string{ + "fmt.Stringer", "extraction.ImportKindSet", "internal/api.Handler", +} + +// identifierInProse is a backticked word in the README that reads as an exported Go identifier: one +// word, starting with a capital. A pattern, a shell command, a path and a lowercase keyword all fail it, +// which is the point — those are not names this module can be asked about. +var identifierInProse = regexp.MustCompile(`^[A-Z][A-Za-z0-9]*$`) + +// proseName is one backticked word of the README that reads as a Go name, and where it has to be looked up. +type proseName struct { + // spelled is the word as the document wrote it, qualifier and pointer included, so that a failure + // quotes the reader what they would search the document for. + spelled string + // name is the identifier itself: the word with a leading `*` and any qualifier taken off. + name string + // onTheSurface says the document wrote the name as `archunit.X`, which is a promise that archunit.go + // exports it and not merely that this module declares it somewhere. + onTheSurface bool +} + +// identifiersTheReadmeProseNames are the identifiers the document names outside its code blocks: every +// `Backticked` word that reads as an exported Go name, with a trailing `()` taken off so that `Kind()` +// is checked as the method it is. +// +// A pointer and a qualifier are read through rather than discarded, because the names that appear *only* in +// the prose are mostly written one of those two ways — `archunit.KindEmptyTest`, `*ProjectLocator`, +// `CheckOptions.IgnoredImportKinds` — and a guard that dropped every shape but the bare word would be +// checking nothing about exactly the names no example mentions. A qualifier this module cannot be asked +// about ends the word instead: `AGENTS.md`, `go.mod` and `t.Error` are not names of this library, and are +// told apart by the qualifier reading as an exported identifier and the member after it doing so too. +// +// The code blocks are cut out first because they are checked properly, against the syntax tree, by the +// two tests above. +func identifiersTheReadmeProseNames(t *testing.T) []proseName { + t.Helper() + + var found []proseName + for _, quoted := range regexp.MustCompile("`([^`\n]+)`").FindAllStringSubmatch(proseOfTheReadme(t), -1) { + spelled := strings.TrimSuffix(quoted[1], "()") + if slices.Contains(namesTheReadmeQualifiesWithSomethingElse, spelled) { + continue + } + qualifier, name, qualified := strings.Cut(strings.TrimPrefix(spelled, "*"), ".") + if !qualified { + qualifier, name = "", qualifier + } + if !identifierInProse.MatchString(name) { + continue + } + if qualified && qualifier != surfacePackage && !identifierInProse.MatchString(qualifier) { + continue + } + found = append(found, proseName{spelled: spelled, name: name, onTheSurface: qualifier == surfacePackage}) + } + if len(found) == 0 { + t.Fatalf("%s names no identifier of this library outside its code blocks", readmeFile) + } + return found +} + +// namesTheReadmeNames is every name the document states as a name, as a set: the identifiers of its prose +// and the selections of its examples. +// +// It is what a completeness check has to be written against rather than a substring search over the +// document, because a substring search cannot fail for a prefix — a README that names `ShouldBeBelow` and +// nothing else satisfies `strings.Contains(readme, "ShouldBe")`, so three of the six threshold verbs would +// be pinned by nothing. +func namesTheReadmeNames(t *testing.T) map[string]bool { + t.Helper() + + named := map[string]bool{} + for _, name := range identifiersTheReadmeProseNames(t) { + named[name.name] = true + } + for _, block := range goBlocksOfTheReadme(t) { + example, err := parseExample(block) + if err != nil { + continue // TestTheReadmeExamplesAreValidGo reports this one. + } + for _, selection := range selectionsRootedAtTheSurface(example) { + named[selection.name] = true + } + } + return named +} + +// proseOfTheReadme is the document with its fenced code blocks removed. +func proseOfTheReadme(t *testing.T) string { + t.Helper() + + var prose []string + fenced := false + for line := range strings.Lines(readTheReadme(t)) { + if strings.HasPrefix(strings.TrimSpace(line), "```") { + fenced = !fenced + continue + } + if !fenced { + prose = append(prose, line) + } + } + return strings.Join(prose, "") +} + +// goBlocksOfTheReadme are the document's ```go blocks, in the order they appear. A block fenced as +// anything else — the shell command, the failure message a rule prints, the layout table — is not Go +// and is not read as Go. +func goBlocksOfTheReadme(t *testing.T) []string { + t.Helper() + + var blocks []string + var current []string + fenced := false + for line := range strings.Lines(readTheReadme(t)) { + switch trimmed := strings.TrimSpace(line); { + case fenced && strings.HasPrefix(trimmed, "```"): + blocks = append(blocks, strings.Join(current, "")) + current, fenced = nil, false + case fenced: + current = append(current, line) + case strings.HasPrefix(trimmed, "```go"): + fenced = true + } + } + if fenced { + t.Fatalf("%s has a code fence that is never closed", readmeFile) + } + if len(blocks) == 0 { + t.Fatalf("%s holds no Go example at all", readmeFile) + } + return blocks +} + +// parseExample parses one README block the three ways a block is legitimately written: a whole file, a +// file with the package clause left off, or the body of a function. The first spelling that parses wins, +// and the error reported when none of them does is the one from reading it as a function body, because +// that is what nearly every example in the document is. +func parseExample(block string) (*ast.File, error) { + if strings.HasPrefix(block, "package ") { + return parser.ParseFile(token.NewFileSet(), "example.go", block, parser.SkipObjectResolution) + } + if file, err := parser.ParseFile( + token.NewFileSet(), "example.go", "package example\n"+block, parser.SkipObjectResolution, + ); err == nil { + return file, nil + } + return parser.ParseFile( + token.NewFileSet(), "example.go", + "package example\nfunc example() {\n"+block+"\n}\n", parser.SkipObjectResolution, + ) +} + +// readTheReadme returns the document's contents, failing the test if the one document a user starts from +// is not there. +func readTheReadme(t *testing.T) string { + t.Helper() + + content, err := os.ReadFile(readmeFile) + if err != nil { + t.Fatalf("reading %s failed: %v", readmeFile, err) + } + return string(content) +} + +// readTheModuleFile returns go.mod's contents. +func readTheModuleFile(t *testing.T) string { + t.Helper() + + content, err := os.ReadFile(moduleFile) + if err != nil { + t.Fatalf("reading %s failed: %v", moduleFile, err) + } + return string(content) +} + +// modulePathOfThisRepository is what a user types after `go get`, read off go.mod rather than spelled +// here: an install instruction naming a path this module does not have is the one mistake in a README +// that stops a reader at the first line. +func modulePathOfThisRepository(t *testing.T) string { + t.Helper() + + return valueOfTheModuleDirective(t, "module") +} + +// valueOfTheModuleDirective is the single-argument directive go.mod states under this keyword — +// `module` and `go` are the two the README quotes. +func valueOfTheModuleDirective(t *testing.T, keyword string) string { + t.Helper() + + for line := range strings.Lines(readTheModuleFile(t)) { + if value, stated := strings.CutPrefix(strings.TrimSpace(line), keyword+" "); stated { + return strings.TrimSpace(value) + } + } + t.Fatalf("%s states no %s directive", moduleFile, keyword) + return "" +} + +// directRequirementsOfThisRepository are the modules this one requires itself, as opposed to the ones +// its own dependencies pulled in. They are what the install section promises a reader they are taking on. +func directRequirementsOfThisRepository(t *testing.T) []string { + t.Helper() + + var required []string + for line := range strings.Lines(readTheModuleFile(t)) { + trimmed := strings.TrimSpace(line) + if trimmed == "" || strings.Contains(trimmed, "// indirect") || !strings.Contains(trimmed, ".") { + continue + } + if path, version, versioned := strings.Cut(trimmed, " v"); versioned && version != "" { + required = append(required, strings.TrimPrefix(path, "require ")) + } + } + if len(required) == 0 { + t.Fatalf("%s requires no module directly, and the install section says which dependencies come along", + moduleFile) + } + return required +} + +// ordinal names a code block the way the test's own message needs it, so a failure says which example of +// the document it is about rather than printing a line number nobody can find in a rendered README. +func ordinal(number int) string { + names := []string{ + "first", "second", "third", "fourth", "fifth", "sixth", "seventh", "eighth", "ninth", "tenth", + "eleventh", "twelfth", "thirteenth", "fourteenth", "fifteenth", "sixteenth", "seventeenth", + "eighteenth", "nineteenth", "twentieth", + } + if number >= 1 && number <= len(names) { + return names[number-1] + } + return "#" + strconv.Itoa(number) +} From 836b963c4e61c37f88db95d02aa1b0217e535804 Mon Sep 17 00:00:00 2001 From: ArchUnitDev loop Date: Sun, 16 Aug 2026 12:30:38 +0000 Subject: [PATCH 2/2] Documentation site on GitHub Pages Closes #42 Implemented by the ArchUnitDev loop. --- .github/workflows/pages.yml | 78 ++++ NOTES.md | 67 +++ README.md | 6 + ci_test.go | 7 +- docs/_config.yml | 47 ++ docs/_layouts/default.html | 60 +++ docs/assets/docs.css | 342 ++++++++++++++ docs/files.md | 172 +++++++ docs/grammar.md | 160 +++++++ docs/graph.md | 139 ++++++ docs/index.md | 106 +++++ docs/internals.md | 137 ++++++ docs/layers.md | 121 +++++ docs/metrics.md | 182 ++++++++ docs/patterns.md | 96 ++++ docs/running.md | 203 ++++++++ docs/slices.md | 152 ++++++ docs_test.go | 895 ++++++++++++++++++++++++++++++++++++ readme_test.go | 139 +++--- 19 files changed, 3050 insertions(+), 59 deletions(-) create mode 100644 .github/workflows/pages.yml create mode 100644 docs/_config.yml create mode 100644 docs/_layouts/default.html create mode 100644 docs/assets/docs.css create mode 100644 docs/files.md create mode 100644 docs/grammar.md create mode 100644 docs/graph.md create mode 100644 docs/index.md create mode 100644 docs/internals.md create mode 100644 docs/layers.md create mode 100644 docs/metrics.md create mode 100644 docs/patterns.md create mode 100644 docs/running.md create mode 100644 docs/slices.md create mode 100644 docs_test.go diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..7bcfd9e --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,78 @@ +# The documentation site, built from docs/ and published to GitHub Pages. +# +# The site is Markdown and nothing else: GitHub's own Jekyll turns docs/ into HTML, docs/_layouts holds +# the one layout it is poured into, and docs/assets/docs.css is the whole of the styling. There is no +# generator to install, no lockfile to refresh and no step that could produce a different site on a +# different day — which matters because this repository's only direct dependency is golang.org/x/tools +# and a docs toolchain would have been the second one. +# +# What is *not* here is the check. A page that names a verb this library does not have, an example that +# does not parse, a link to a page nobody wrote — those are caught by docs_test.go on every push to every +# branch, along with the rest of `go test ./...`, because they are wrong before they are published rather +# than after. This workflow only builds and publishes; the CI gate is ci.yml. +# +# `main` alone is the trigger, unlike ci.yml, which watches every branch: publishing is not a check, and a +# branch's half-written page is not what the site should show. + +name: Docs + +on: + push: + branches: [main] + workflow_dispatch: + +# One deployment at a time, and never cancelled: a half-published site is worse than a stale one, so a +# push that lands while a deploy is running waits for it instead of replacing it mid-upload. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + name: Build the site + runs-on: ubuntu-latest + timeout-minutes: 10 + # Reading is all the build does — the repository for the pages, and the repository's Pages settings for + # the baseurl, which `configure-pages` asks the API for and gets a 403 without. Naming any permission + # here sets every other one to `none`, so the read of the settings has to be spelled as well as the read + # of the source. The token that can publish is the deploy job's, below. + permissions: + contents: read + pages: read + steps: + - uses: actions/checkout@v7 + # What baseurl the site is served under is Pages' answer, not this file's: the site is + # https://lukasniessen.github.io/ArchUnitGo/, so every asset and every internal link has to be + # written relative to a prefix docs/_config.yml states and this step confirms. + - uses: actions/configure-pages@v6 + # The site source is docs/ and not the repository root, so README.md is not a page of it. The two + # documents have different jobs — the README is what a reader skims before deciding, the site is what + # they read while writing rules — and docs/index.md links to the README for the parts that are only + # said once, such as what is not implemented yet. + - uses: actions/jekyll-build-pages@v1 + with: + source: ./docs + destination: ./_site + - uses: actions/upload-pages-artifact@v5 + with: + path: ./_site + + deploy: + name: Publish to GitHub Pages + runs-on: ubuntu-latest + timeout-minutes: 10 + needs: build + # `pages: write` publishes and `id-token: write` is what the deployment authenticates with. They are on + # this job alone: the build reads the repository and never needs either. + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + # Belt and braces on top of the `main`-only trigger, because the manual one has no branch filter: a + # workflow_dispatch from a branch builds the site and stops, and only main is ever published. + if: github.ref == 'refs/heads/main' + steps: + - id: deployment + uses: actions/deploy-pages@v5 diff --git a/NOTES.md b/NOTES.md index 7fa91c3..56916b7 100644 --- a/NOTES.md +++ b/NOTES.md @@ -2740,3 +2740,70 @@ Deviations from the issue text, `AGENTS.md` or sibling convention. One line each *nothing else gets into your module graph* while `golang.org/x/mod` and `golang.org/x/sync` come along indirectly. The module path and the Go version are read out of `go.mod` for the same reason, one line lower down: an install instruction naming a path this module does not have stops a reader at the first thing they type. + +## Issue #42 — Documentation site on GitHub Pages + +- WHY: the site is Markdown poured into one layout by GitHub's own Jekyll, with no generator, no theme gem + and no lockfile. "Same information architecture as the siblings" is a narrative guide beside a generated + API reference, and for a Go port the generated half already exists: `pkg.go.dev` renders every doc comment + of the public surface. A second reference generated into this repository would be a second thing to go + stale and the module's second toolchain, after `golang.org/x/tools` — which is a sentence the README and + `docs/index.md` both promise a reader. So the site holds the guide and links the reference, and says in as + many words that it does. +- WHY: the check for the site is `docs_test.go`, run by `go test ./...` on every push to every branch, and + `.github/workflows/pages.yml` only builds and publishes. A page that names a verb this library does not + have is wrong before it is published rather than after, and a publish workflow watching `main` alone would + be a gate that runs after the merge. The test asserts that separation: the pages workflow runs no command + of `gateOfThisRepository`. +- WHY: the navigation is generated in the layout from every page's `nav_order` front matter, and no page + filename appears in `_config.yml` or in `_layouts/default.html`. A hardcoded chapter list is the one part + of a docs folder that can silently disagree with what is in it; `docs_test.go` holds every page to stating + a layout, a title, a description and a contiguous unique `nav_order`, holds the front-matter title to the + page's own first heading, and holds the layout to naming no page. +- WHY: pages link to each other by filename — `[the files family](files.md)` — plus the + `jekyll-relative-links` plugin, so every link works while reading the source on GitHub as well as on the + built site. A raw HTML `` is left unrewritten by that plugin and 404s once published, which is the + one kind of broken link nobody notices, so raw HTML links are a test failure. Internal links, including + their `#fragment`s, are resolved against the pages and their headings. +- WHY: the completeness guard is per family: every exported method of `/fluentapi` has to be named + on `docs/.md`, exact match against the names the page states rather than `strings.Contains`. The + three self-describing methods — `String`, `Mood`, `Selectors` — are exempt because `docs/grammar.md` + documents them once for every family that has them, and the same test holds that page to naming them, so + the exemption cannot quietly become three verbs no page documents. They are not on every stage: `String` + is on all but `LayerPolicyBuilder`, `Mood` only on the files and slices mood stages — the layers and + metrics families carry the mood in the predicate and the graph family has none — and `Selectors` only on + the files and metrics scope stages, which are the two that hand their compiled filters back. The exemption + is by name, so a family that declares none of the three is unaffected by it. Every count the pages state + is recomputed off the syntax tree the way `readme_test.go` recomputes nine and thirteen. +- WHY: the build job's permissions are `contents: read` **and** `pages: read`, not `contents: read` alone. + Naming one permission sets every unnamed one to `none`, and `actions/configure-pages` asks the API for the + repository's Pages settings to work out the baseurl — with no read of them it gets a 403 and nothing is + ever built. The write half stays on the deploy job. +- WHY: the deploy job's condition is `github.ref == 'refs/heads/main'` rather than the sibling's + `github.event_name == 'push'` — the trigger already restricts pushes to `main`, and the branch test is + what also covers a `workflow_dispatch` from a branch, which has no branch filter of its own. +- WHY: five helpers of `readme_test.go` now take the document as a parameter (`readDocument`, `proseOf`, + `goBlocksOf`, `identifiersNamedInTheProseOf`, `namesTheDocumentNames`) so that `docs_test.go` holds ten + pages to the same syntax tree through the same code. Two emptiness assertions moved out of the helpers + into the README's own tests, because they are true of that document and not of every one: `docs/internals.md` + has fenced blocks and no Go example in it at all. The two exemption lists are shared unchanged — a name + that is fine in the README is fine on the site — and their comments now say "this repository's documents". +- WHY: `ci_test.go`'s comment on `ciWorkflow` said this repository has one workflow. Adding a second made + that prose false in the same diff, so it now names `pages.yml`, says which of the two gates a change, and + keeps the reason the tests below are about `ci.yml` alone. +- WHY: `TestTheDocsSiteCountsTheSurfacesItStatesAsClosedSets` recomputed only sets of *methods*, which left + three of the site's closed sets pinned by nothing, because what states them is package-level. So: the four + exported projections of `docs/patterns.md` (`exportedProjections` — the `SliceBy` family plus `Identity`, + which has no shared prefix and so is looked up by name, and looked up rather than assumed so that + un-exporting it goes red too); the five `Project` names of `docs/grammar.md`'s entry-point table, which is + the four entry points and the `*ProjectLocator` each takes; and one exclusion count per family, held to + *four in the files family, five in metrics, three in layers*. The last is over the **distinct** `Except` + names of a family rather than its methods, because `files/fluentapi` declares the same four on its scope + stage and again on its dependency clause, while the page is counting the vocabulary a reader learns. + `verbsOf` still drops every `Except` — an exclusion is not a verb picked from a list — so `exclusionsOf` + is a second reading of the same tree rather than a change to that one. +- WHY: the two dashes in `docs/grammar.md`'s `Also spelled` column are checked against the absence of + `archunit.Slices` and `archunit.Graph`, in the style of `TestTheReadmeIsHonestAboutWhatIsMissing`. An alias + somebody adds is one more package-level function: it makes that column, *the two families without a second + spelling*, `docs/slices.md`'s *no shorter alias* and `docs/metrics.md`'s *no second spelling* all false at + once, and no count of the surface and no lookup of what a page names can fail for a name that is not there. diff --git a/README.md b/README.md index 5bc7696..8304c33 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,12 @@ ArchUnitGo is the Go member of **ArchUnitEverything**, one architecture-testing Siblings: [ArchUnitTS](https://github.com/LukasNiessen/ArchUnitTS) · [ArchUnitPython](https://github.com/LukasNiessen/ArchUnitPython). +**Documentation site:** — the same material as this file with +a page per family, built from [docs/](docs). The API reference is +[pkg.go.dev](https://pkg.go.dev/github.com/LukasNiessen/ArchUnitGo), generated from the doc comments in the +source. This file stays the short version, and it is the one place that states +[what is not implemented yet](#what-is-not-implemented-yet). + - [Install](#install) - [Your first rule](#your-first-rule) - [What a failure looks like](#what-a-failure-looks-like) diff --git a/ci_test.go b/ci_test.go index e2d5066..d92c0ed 100644 --- a/ci_test.go +++ b/ci_test.go @@ -19,8 +19,11 @@ import ( // first, so that nothing below says anything about how the file is indented or where it wraps; what // they pin is that each command of the gate is in there, spelled the way a maintainer types it. -// ciWorkflow is the one workflow of this repository. A second one would be a check somewhere the tests -// below say nothing about, which is why the path is spelled here once. +// ciWorkflow is the workflow that holds every check of this repository. It is not the only workflow — +// .github/workflows/pages.yml publishes the documentation site, and docs_test.go is what holds that one to +// what it is supposed to do — but it is the only one that gates a change, which is why the tests below are +// about this path alone. A third workflow running a check none of them names would be a check nothing here +// says anything about. const ciWorkflow = ".github/workflows/ci.yml" // gateOfThisRepository is every check a change has to pass, as the command that runs it. It is the list diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..b39ba5f --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,47 @@ +# The documentation site's configuration. GitHub's own Jekyll is the whole toolchain: every page under +# docs/ is Markdown with front matter, _layouts/default.html is what they are poured into, and +# assets/docs.css is the styling. Nothing is installed, generated or vendored. +# +# .github/workflows/pages.yml builds this folder and publishes it; docs_test.go holds it to the library. + +title: ArchUnitGo +description: Architecture rules as ordinary Go unit tests. +lang: en + +# Where the site is served from. GitHub Pages puts a project site under the repository's name, so every +# internal link and every asset is written through Jekyll's `relative_url` and never as an absolute path +# — a link to /assets/docs.css would resolve above this site and 404. +url: https://lukasniessen.github.io +baseurl: /ArchUnitGo + +# The two places this site sends a reader who wants more than prose: the code, and the API reference the Go +# toolchain generates from its doc comments. There is no generated reference in this site on purpose — +# pkg.go.dev is where a Go reader looks for one, and a second copy of it would be a second thing to go stale. +repository_url: https://github.com/LukasNiessen/ArchUnitGo +api_reference_url: https://pkg.go.dev/github.com/LukasNiessen/ArchUnitGo + +# The sibling ports, named here rather than in each page's prose: someone who knows one of them should be +# able to read this site without a map. +siblings: + - name: ArchUnitTS + url: https://github.com/LukasNiessen/ArchUnitTS + - name: ArchUnitPython + url: https://github.com/LukasNiessen/ArchUnitPython + +markdown: kramdown +highlighter: rouge +kramdown: + input: GFM + syntax_highlighter: rouge + hard_wrap: false + +# Pages link to each other by filename — `[the files family](files.md)` — so that every link works while +# reading the source on GitHub as well as on the built site. This plugin is what rewrites those links to +# the pages' URLs; without it the site's links would 404 while the repository's still worked, which is the +# one kind of broken link nobody notices. +plugins: + - jekyll-relative-links + +relative_links: + enabled: true + collections: false diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html new file mode 100644 index 0000000..8e3bc46 --- /dev/null +++ b/docs/_layouts/default.html @@ -0,0 +1,60 @@ + + + + + + {% if page.url == '/' %}{{ site.title }} — {{ site.description }}{% else %}{{ page.title }} · {{ site.title }}{% endif %} + + + + + + + + + +
+ {%- comment -%} + The navigation is every page that gives itself a nav_order, sorted by it. No page is named here: + a page added to docs/ appears in the navigation because it has front matter, and docs_test.go is + what holds every page to having it. A hardcoded list would be the one part of this site that + could silently disagree with what is in the folder. + {%- endcomment -%} + {%- assign chapters = site.pages | where_exp: 'chapter', 'chapter.nav_order' | sort: 'nav_order' -%} + + +
+ {{ content }} +
+
+ + + + diff --git a/docs/assets/docs.css b/docs/assets/docs.css new file mode 100644 index 0000000..70f8e6b --- /dev/null +++ b/docs/assets/docs.css @@ -0,0 +1,342 @@ +/* + * The whole of this site's styling. One stylesheet, no framework, no build step: the site is Markdown + * poured into _layouts/default.html, and this is what makes it readable. + * + * Both color schemes are declared as custom properties and switched by prefers-color-scheme, so the page a + * reader gets is the one their system asked for and neither scheme is an afterthought. + */ + +:root { + color-scheme: light dark; + + --page: #ffffff; + --sunken: #f4f6f8; + --ink: #1c2024; + --ink-soft: #4b5563; + --rule: #dfe3e8; + --accent: #006c85; + --accent-soft: #e3f1f5; + --code-ink: #22303a; + + --measure: 46rem; + --sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; + --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace; +} + +@media (prefers-color-scheme: dark) { + :root { + --page: #11161a; + --sunken: #1a2127; + --ink: #e7ecf0; + --ink-soft: #a8b3bd; + --rule: #2b343c; + --accent: #67cde3; + --accent-soft: #17313a; + --code-ink: #dbe4ea; + } +} + +* { + box-sizing: border-box; +} + +body { + margin: 0; + background: var(--page); + color: var(--ink); + font-family: var(--sans); + font-size: 1rem; + line-height: 1.65; + -webkit-text-size-adjust: 100%; +} + +a { + color: var(--accent); + text-decoration-thickness: 1px; + text-underline-offset: 2px; +} + +a:hover { + text-decoration-thickness: 2px; +} + +:focus-visible { + outline: 2px solid var(--accent); + outline-offset: 2px; +} + +.skip { + position: absolute; + left: -9999px; +} + +.skip:focus { + left: 1rem; + top: 1rem; + z-index: 2; + padding: 0.5rem 0.75rem; + background: var(--page); + border: 1px solid var(--rule); + border-radius: 6px; +} + +/* ---- the banner ---- */ + +.banner { + border-bottom: 1px solid var(--rule); + background: var(--sunken); +} + +.banner-inner { + max-width: 72rem; + margin: 0 auto; + padding: 1.5rem 1.25rem 1.25rem; +} + +.wordmark { + font-size: 1.4rem; + font-weight: 650; + letter-spacing: -0.01em; + color: var(--ink); + text-decoration: none; +} + +.tagline { + margin: 0.15rem 0 0.6rem; + color: var(--ink-soft); +} + +.elsewhere { + display: flex; + flex-wrap: wrap; + gap: 0.4rem 1rem; + margin: 0; + font-size: 0.9rem; +} + +/* ---- the two columns ---- */ + +.page { + max-width: 72rem; + margin: 0 auto; + padding: 0 1.25rem 3rem; + display: grid; + grid-template-columns: 1fr; + gap: 0 2.5rem; +} + +@media (min-width: 60rem) { + .page { + grid-template-columns: 14rem minmax(0, 1fr); + } + + .chapters { + position: sticky; + top: 0; + align-self: start; + max-height: 100vh; + overflow-y: auto; + padding-top: 2rem; + } +} + +.chapters ol { + list-style: none; + margin: 1.5rem 0 0; + padding: 0; + font-size: 0.94rem; +} + +.chapters li { + margin: 0; + border-left: 2px solid var(--rule); +} + +.chapters a { + display: block; + padding: 0.35rem 0.75rem; + color: var(--ink-soft); + text-decoration: none; +} + +.chapters a:hover { + color: var(--accent); +} + +.chapters a[aria-current='page'] { + color: var(--accent); + font-weight: 600; + background: var(--accent-soft); +} + +/* ---- the prose ---- */ + +.prose { + max-width: var(--measure); + padding-top: 1.5rem; +} + +.prose h1, +.prose h2, +.prose h3 { + line-height: 1.25; + letter-spacing: -0.01em; +} + +.prose h1 { + font-size: 2rem; + margin: 0.75rem 0 1rem; +} + +.prose h2 { + font-size: 1.4rem; + margin: 2.5rem 0 0.75rem; + padding-top: 0.75rem; + border-top: 1px solid var(--rule); +} + +.prose h3 { + font-size: 1.1rem; + margin: 1.75rem 0 0.5rem; +} + +.prose blockquote { + margin: 1.25rem 0; + padding: 0.1rem 1rem; + border-left: 3px solid var(--accent); + color: var(--ink-soft); +} + +.prose table { + width: 100%; + margin: 1.25rem 0; + border-collapse: collapse; + font-size: 0.94rem; +} + +.prose th, +.prose td { + padding: 0.45rem 0.6rem; + border-bottom: 1px solid var(--rule); + text-align: left; + vertical-align: top; +} + +.prose th { + font-size: 0.82rem; + text-transform: uppercase; + letter-spacing: 0.04em; + color: var(--ink-soft); +} + +.prose code { + font-family: var(--mono); + font-size: 0.88em; + padding: 0.1em 0.3em; + border-radius: 4px; + background: var(--sunken); + color: var(--code-ink); +} + +.prose pre { + margin: 1.25rem 0; + padding: 0.9rem 1rem; + overflow-x: auto; + background: var(--sunken); + border: 1px solid var(--rule); + border-radius: 8px; + line-height: 1.5; +} + +.prose pre code { + padding: 0; + background: none; + font-size: 0.86rem; +} + +.prose hr { + margin: 2.5rem 0; + border: 0; + border-top: 1px solid var(--rule); +} + +.prose li { + margin: 0.35rem 0; +} + +/* ---- Rouge, the highlighter GitHub Pages ships with ---- */ + +.highlight .c, +.highlight .c1, +.highlight .cm, +.highlight .cs { + color: var(--ink-soft); + font-style: italic; +} + +.highlight .k, +.highlight .kd, +.highlight .kn, +.highlight .kp, +.highlight .kr, +.highlight .kt { + color: var(--accent); +} + +.highlight .s, +.highlight .s1, +.highlight .s2, +.highlight .sb, +.highlight .se { + color: #a4432b; +} + +.highlight .nf, +.highlight .nx { + font-weight: 600; +} + +.highlight .m, +.highlight .mi, +.highlight .mf { + color: #7a4bab; +} + +@media (prefers-color-scheme: dark) { + .highlight .s, + .highlight .s1, + .highlight .s2, + .highlight .sb, + .highlight .se { + color: #e8a58c; + } + + .highlight .m, + .highlight .mi, + .highlight .mf { + color: #c9a6ee; + } +} + +/* ---- the colophon ---- */ + +.colophon { + border-top: 1px solid var(--rule); + background: var(--sunken); + color: var(--ink-soft); + font-size: 0.9rem; +} + +.colophon p { + max-width: 72rem; + margin: 0 auto; + padding: 0.6rem 1.25rem; +} + +.colophon p:first-child { + padding-top: 1.25rem; +} + +.colophon p:last-child { + padding-bottom: 1.5rem; +} diff --git a/docs/files.md b/docs/files.md new file mode 100644 index 0000000..f8b9b14 --- /dev/null +++ b/docs/files.md @@ -0,0 +1,172 @@ +--- +layout: default +title: The files family +nav_order: 4 +description: File-level rules in ArchUnitGo — what depends on what, what depends on which third-party module, cycles, naming, placement and your own predicate. +--- + +# The files family + +The file is this library's primary node: a rule of this family selects files and then says something about +what they depend on, how they are named or where they live. It is the family to reach for first, and the one +the other four are variations on. + +```go +rule := archunit.ProjectFiles(nil). + InFolder("internal/api/**"). + ShouldNot(). + DependOnFiles(). + InFolder("internal/db/**") +``` + +`archunit.ProjectFiles` is the entry point, `archunit.Files` is the same one under a shorter name, and both +take an optional `*ProjectLocator`. + +## Scope + +The scope verbs are chainable and combined with AND, so each one narrows what the rule is about. Every one of +them takes an exclusion. + +| Verb | Selects the files whose | +|---|---| +| `WithName` | filename matches the pattern | +| `InFolder` | folder — the identifier without the filename — matches the pattern | +| `InPath` | whole identifier matches the pattern | +| `InFile` | identifier *is* this string, taken literally | + +| Exclusion | Reads its patterns against | +|---|---| +| `Except` | whatever the selector in front of it reads | +| `ExceptWithName` | the filename | +| `ExceptInFolder` | the folder | +| `ExceptInPath` | the whole identifier | + +To see what a scope resolves to before you judge it, ask the scope rather than the rule. `SelectFiles` hands +back the identifiers, sorted: + +```go +files, err := archunit.ProjectFiles(nil). + InFolder("internal/api/**"). + ExceptWithName("*_gen.go"). + SelectFiles(nil) +``` + +## The predicates + +`Should` and `ShouldNot` open the mood stage, and these are the predicates behind them: + +| Predicate | Says that a selected file | Moods | Reports | +|---|---|---|---| +| `DependOnFiles` | depends on the files the object names | both | `FileDependencyViolation` | +| `DependOnExternalModules` | depends on the third-party modules the object names | both | `FileExternalDependencyViolation` | +| `HaveNoCycles` | is in no dependency circle | `Should` only | `FileCycleViolation` | +| `HaveName` | is named as the pattern says | both | `FileNamingViolation` | +| `BeInFolder` | sits where the pattern says | both | `FileNamingViolation` | +| `BeInPath` | has the identifier the pattern says | both | `FileNamingViolation` | +| `AdhereTo` | satisfies a function you wrote | both | `FileAdherenceViolation` | + +Every one of them ends in `Check`, and each violation carries the offending file, the requirement as a +compiled pattern and what was found instead — never a sentence. [Running a rule](running.md) is where the +prose gets built. + +## A boundary between two folders + +`DependOnFiles` opens an object stage: the files the rule is about depending on. Its verbs are the scope's +three pattern verbs, chainable and combined with AND, and each takes the same four exclusions: + +```go +rule := archunit.ProjectFiles(nil). + InFolder("internal/api/**"). + Except("**/generated"). + ShouldNot(). + DependOnFiles(). + InFolder("internal/db/**"). + ExceptInFolder("internal/db/dto/**") +``` + +That reads as *the api does not touch the database, except for its data-transfer types* — a boundary with one +documented door in it. In the positive mood the same chain is a requirement: every selected file has to +depend on at least one file the object matches, which is how *every handler uses the service layer* is +written. + +| Object verb | Matches against | +|---|---| +| `WithName` | the filename of the file depended on | +| `InFolder` | its folder | +| `InPath` | its whole identifier | + +## Third-party modules + +`DependOnExternalModules` is the same shape for the code outside your project, and its one object verb is +`Matching`, which is read against the import path: + +```go +rule := archunit.ProjectFiles(nil). + InFolder("internal/domain/**"). + ShouldNot(). + DependOnExternalModules(). + Matching("*.*/**"). + Except("gopkg.in/yaml*/**") +``` + +`Matching` is repeatable and **combined with OR** — the one chain in this library that widens rather than +narrows, because *any of these modules* is what a third-party policy means. `*.*/**` is the glob for +*anything with a dot in its first segment*, which is every module path that is not a standard library +package. + +## Cycles + +```go +rule := archunit.ProjectFiles(nil).InFolder("internal/**").Should().HaveNoCycles() +``` + +One `FileCycleViolation` per cycle, each carrying a `Circuit` — the chain of dependencies that leaves a file, +comes back to it and touches nothing twice on the way, printable as `a.go -> b.go -> a.go`. The predicate is +offered on the positive mood alone: the negation would ask a project to contain a circle somewhere, which is +not a rule anybody means. + +## Naming and placement + +```go +naming := archunit.ProjectFiles(nil).InFolder("internal/api/**").Should().HaveName("*_handler.go") +placement := archunit.ProjectFiles(nil).WithName("*_test.go").ShouldNot().BeInFolder("internal/db/**") +``` + +`HaveName` reads the filename, `BeInFolder` the folder and `BeInPath` the whole identifier — the predicate +forms of the three scope verbs, matching against exactly the same parts. + +## Your own predicate + +`AdhereTo` is the escape hatch: a question about one file, answered yes or no, and the words to report it by. +`Should` requires every selected file to answer yes; `ShouldNot` forbids any of them from doing so. + +```go +rule := archunit.ProjectFiles(nil). + InFolder("internal/**"). + Should(). + AdhereTo(func(file archunit.FileInfo) bool { + return file.NonBlankLineCount <= 400 + }, "be at most 400 lines long") +``` + +The function is a `FilePredicate` and the value it is handed is a `FileInfo`, so it can ask about the text of +a file as well as its place: + +| Field | Is | +|---|---| +| `Path` | the file's identifier | +| `Name` | its name without the extension | +| `Extension` | that extension | +| `Directory` | its folder | +| `Source` | its whole source text | +| `NonBlankLineCount` | how many of its lines carry something | + +The second argument is the requirement in your own words, and it is what the failure message says the file +should have done — so write it as the predicate's own sentence, *be at most 400 lines long*, and the report +reads as one. + +## Next + +The other four families are the same grammar over a different node: [layers](layers.md) name their sets of +files up front, [slices](slices.md) cut them out of identifiers, [metrics](metrics.md) count rather than +judge, and the [dependency graph](graph.md) draws instead of judging at all. diff --git a/docs/grammar.md b/docs/grammar.md new file mode 100644 index 0000000..735dc51 --- /dev/null +++ b/docs/grammar.md @@ -0,0 +1,160 @@ +--- +layout: default +title: The grammar +nav_order: 2 +description: The stages every ArchUnitGo rule is built from — entry, scope, mood, predicate, object, terminal — and the fixed vocabulary each of them is spelled with. +--- + +# The grammar + +Every rule is an English sentence, read left to right: + +``` +ENTRY SCOPE MOOD PREDICATE OBJECT TERMINAL +project files in folder should not depend on in folder check + "**/api/**" files "**/db/**" +``` + +> *project files, in folder `**/api/**`, should not depend on files in folder `**/db/**`.* + +Learn the stages once and you can read a rule from any of the five families, because they all spell the +same ones. The vocabulary is deliberately small and it has no synonyms: one comparison, one spelling. + +## The stages + +| Stage | How many | Spelled | +|---|---|---| +| **Entry** | exactly 1 | `ProjectFiles`, `ProjectLayers`, `ProjectSlices`, `Metrics`, `ProjectGraph` | +| **Scope** | 0..n, chainable, AND | `WithName`, `InFolder`, `InPath`, `InFile`, `ForClassesMatching` | +| **Exclusion** | 0..n, after any selector that has one | `Except`, `ExceptWithName`, `ExceptInFolder`, `ExceptInPath`, `ExceptClassesMatching` | +| **Mood** | exactly 1 | `Should`, `ShouldNot` | +| **Predicate** | exactly 1 | `HaveNoCycles`, `HaveName`, `BeInFolder`, `BeInPath`, `AdhereTo`, `DependOnFiles`, `DependOnExternalModules`, `ContainDependency`, `AdhereToDiagram`, `MayOnlyDependOnLayers`, `MayNotDependOnLayers` | +| **Object** | 1..n, chainable | `InFolder` after `DependOnFiles`, `Matching` after `DependOnExternalModules` | +| **Modifier** | 0..n, order-independent | `IgnoringOrphanSlices`, `FocusOn`, `CollapseToFolderDepth`, `Titled`, `WithCheckOptions` | +| **Terminal** | exactly 1 | `Check`, `Measure`, `Snapshot`, `ToDot`, `ExportAsHTML` | + +Each family fills the stages in with its own vocabulary, and its own page says which: +[files](files.md), [layers](layers.md), [slices](slices.md), [metrics](metrics.md), +[dependency graph](graph.md). + +## Entry points + +An entry point is a noun phrase, and it takes an optional `*ProjectLocator` — `nil` for the project the +test itself is in, found by walking up to the nearest `go.mod`. It is never a required argument. + +| Entry point | Family | Also spelled | +|---|---|---| +| `archunit.ProjectFiles` | files | `archunit.Files` | +| `archunit.ProjectLayers` | layers | `archunit.Layers` | +| `archunit.ProjectSlices` | slices | — | +| `archunit.Metrics` | metrics | — | +| `archunit.ProjectGraph` | dependency-graph reports | `archunit.DependencyGraph` | + +The two families without a second spelling have a reason for it. `slices` alone is the name of a standard +library package, so a chain starting with it would read as one; `metrics` is what the metrics family calls +its entry point in every port. + +## Mood + +**Mood is exactly two words**, `Should` and `ShouldNot`. There are no synonyms, ever — not *must*, not *may*, +not *is not*. + +The two are one assertion with a flag rather than two code paths, which is why every predicate that has a +meaningful negation is on both moods, and why a predicate whose negation would report nothing is on one: +`HaveNoCycles` is offered on `Should` alone, because *should have cycles* is not a rule anybody means. + +Two families spell the mood inside the predicate instead of before it, and neither has a mood stage: + +- The layers family: `MayOnlyDependOnLayers` is the allowlist and `MayNotDependOnLayers` the blocklist, so + a mood in front of them would read as *should not, may not depend on layers*. +- The metrics family: each of the six threshold predicates carries its own — `ShouldBeBelow`, + `ShouldBeAbove`, `ShouldBe`, `ShouldBeBelowOrEqual`, `ShouldBeAboveOrEqual`, `ShouldSatisfy` — as do the + two zone checks, `ShouldNotBeInZoneOfPain` and `ShouldNotBeInZoneOfUselessness`. + +The [dependency-graph family](graph.md) has no mood because it has no predicate: it describes a report +rather than a rule. + +## Exclusions + +`Except` qualifies the selector in front of it and nothing else. It is repeatable, and its patterns are read +against the same part of an identifier as the selector it follows — unless a targeted form names a part of +its own: + +```go +rule := archunit.ProjectFiles(nil). + InFolder("app/**"). + Except("**/generated"). + ExceptWithName("*_gen.go"). + ShouldNot(). + DependOnFiles(). + InFolder("internal/db/**"). + ExceptInFolder("internal/db/dto/**") +``` + +That is what keeps *everything under `app/`, but not the generated folder* one clause, instead of an +inverted rule about the generated folder. `Except` with no selector in front of it is a user error rather +than a rule about everything, and each family offers exactly the targeted forms its own selectors name — +four in the files family, five in metrics, three in layers, and the plain verb in the graph module, where +every pattern is matched against the whole identifier already. The slices family is the one without it: it +has no exclusion at all, so a slicing is narrowed by the pattern that defines it and nothing else. + +## Terminals + +`Check(*CheckOptions) ([]Violation, error)` is the universal terminal: every rule in every family ends in +it, and it is the whole of `archunit.Checkable`, the seam the library hangs from. A helper that loops over a +list of rules never has to know which family they came from. + +```go +violations, err := rule.Check(nil) +``` + +The other terminals hand back something other than a judgement, and a chain that ends in one is a report +rather than a rule: `Measure` for the numbers a metric read, `Snapshot` for a graph report as data, `ToDot` +and its siblings for it as a string, `ExportAsHTML` and its siblings for it as a file. The scope stage has a +terminal of its own too — `SelectFiles`, `SelectLayerFiles`, `SelectSliceFiles` — which answers *what does +this selector actually match?* without judging anything. + +## Builders are values + +Every stage is immutable and returns a new instance, so a scope is worth typing once and a half-built rule +is worth storing: + +```go +api := archunit.ProjectFiles(nil).InFolder("internal/api/**") + +noDatabase := api.ShouldNot().DependOnFiles().InFolder("internal/db/**") +small := api.Should().AdhereTo(func(file archunit.FileInfo) bool { + return file.NonBlankLineCount <= 400 +}, "be at most 400 lines long") +``` + +Nothing was read from disk by any line of that. Both rules are values, and either can be stored in a struct +field, returned from a helper or put in a map of the suite's rules — see [running a rule](running.md). + +## Asking a chain what it says + +Three methods let a chain describe itself, and this page is where they are documented once, which is why the +family pages do not repeat them. Each is on the stages that have something to answer with: + +| Method | On | Hands back | +|---|---|---| +| `String` | every stage but `LayerPolicyBuilder` | the sentence the chain has become so far | +| `Mood` | the mood stage of the two families that have one, files and slices | `archunit.Should` or `archunit.ShouldNot` | +| `Selectors` | the scope stage of the two families whose scope compiles filters, files and metrics | the compiled patterns the scope selects with | + +`String` is what a failure message quotes the rule as, and it includes the first thing the chain rejected — +so a pattern that will not compile says so when the chain is printed as well as when it is checked. +`LayerPolicyBuilder` is the one stage without it, the clause caught between `WhereLayer` and its predicate: +it has named a layer and not yet said anything about it, so it has no sentence of its own. + +The other two are on the stages that exist to answer them. Only the files and slices families have a mood +stage — the layers and metrics families spell the mood inside the predicate and the graph family has none — +and of the scope stages only the files and metrics ones hand their compiled filters back, so a layers, +slices or graph chain has no `Selectors`. + +## Adding a verb + +The acceptance test for a new verb is not the implementation, it is the name: **read the whole chain aloud, +and if it is not a sentence an architect who does not write Go would understand, the name is wrong.** +[AGENTS.md](https://github.com/LukasNiessen/ArchUnitGo/blob/main/AGENTS.md) is where that rule and the rest +of the conventions live, and [how it works](internals.md) is the short version of where the code goes. diff --git a/docs/graph.md b/docs/graph.md new file mode 100644 index 0000000..57bd3d9 --- /dev/null +++ b/docs/graph.md @@ -0,0 +1,139 @@ +--- +layout: default +title: Dependency-graph reports +nav_order: 8 +description: The dependency graph of a Go project as data or as a diagram — nine modifiers, thirteen terminals, six formats, and no rule at all. +--- + +# Dependency-graph reports + +This family judges nothing. It describes a report — what to draw, how far, under what labels — and then hands +it back as data or as a document: + +```go +snapshot, err := archunit.ProjectGraph(nil). + FocusOn("internal/api/**", 1). + CollapseToFolderDepth(2). + Titled("what the api layer touches"). + Snapshot() +``` + +`archunit.ProjectGraph` is the entry point and `archunit.DependencyGraph` the other name the family gives it. +There is no mood, no predicate and no violation type here, and that is the grammar rather than an omission: a +report is not a rule, so there is nothing for it to disagree with. + +The default report is one node per file of the project's own code, with one arrow per dependency between two +of them. + +## The nine modifiers + +Every one is optional, chainable and order-independent. + +| Modifier | Does | +|---|---| +| `IncludingExternalDependencies` | adds the code outside the project — the standard library and the modules it depends on | +| `IncludingSelfDependencies` | keeps a node's dependency on itself, which is dropped by default | +| `FocusOn` | narrows to the files a pattern names plus their neighborhood, that many hops out in **both** directions | +| `ReachableFrom` | narrows to those files and everything they depend on, transitively | +| `DependentsOf` | narrows to those files and everything that depends on them, transitively | +| `CollapseToFolderDepth` | draws each folder at that depth as one node | +| `CollapseByPattern` | draws every node a pattern names as one node under a label you choose | +| `Titled` | says what the report is called | +| `WithCheckOptions` | says how the project is read — test files, ignored import kinds, where it is | + +`IncludingExternalDependencies` and `IncludingSelfDependencies` are the two verbs that widen the report; the +three that narrow it are three different questions. `FocusOn` is *what is around this code*, and depth 0 is the named files alone. `ReachableFrom` +follows the arrows forwards with no bound — *what does this pull in*, which is what a binary actually reaches. +`DependentsOf` follows them backwards — *who would notice if this changed*, which is the answer worth having +before deleting a folder. + +```go +snapshot, err := archunit.ProjectGraph(nil). + DependentsOf("internal/db/**"). + Titled("who would notice if the database changed"). + Snapshot() +``` + +Patterns here are matched against the whole identifier, so `internal/api/**` is that folder and everything +below it. They match identifiers and never the labels a collapse draws, which is what keeps focusing and +collapsing in one chain order-independent: the neighbors of the *files* named, drawn as folders. + +The four modifiers that take a pattern each take `Except`, which qualifies the one the chain wrote most +recently — the one word in this family that is not order-independent, because an exclusion belongs to the +clause it was typed in: + +```go +snapshot, err := archunit.ProjectGraph(nil). + IncludingExternalDependencies(). + FocusOn("app/**", 1). + Except("**/generated/**"). + CollapseByPattern("api", "internal/api/**"). + CollapseByPattern("third party", "**"). + Snapshot() +``` + +`CollapseByPattern` is the modifier for a diagram whose boxes are the architecture rather than the directory +tree: two folders that are one component, every dependency module as a single *third party* node, a legacy +corner as one box nobody wants to look inside. The label is asked for rather than derived, because a box has to +be called something and `internal/{api,web}/**` is not a name anybody wants to read — and giving those groups +the same names as [a layer policy's](layers.md) layers is what makes a report and a rule describe one +architecture. Groups are asked before `CollapseToFolderDepth`, so the two compose. + +## The thirteen terminals + +`Snapshot` hands the report back as data, and the other twelve hand it back as a document — six formats, each +as a string or as a file: + +| Format | As a string | As a file | +|---|---|---| +| Graphviz | `ToDot` | `ExportAsDot` | +| Mermaid | `ToMermaid` | `ExportAsMermaid` | +| D2 | `ToD2` | `ExportAsD2` | +| Comma-separated values | `ToCSV` | `ExportAsCSV` | +| JSON | `ToJSON` | `ExportAsJSON` | +| A self-contained web page | `ToHTML` | `ExportAsHTML` | + +```go +err := archunit.ProjectGraph(nil). + CollapseToFolderDepth(2). + Titled("the modules of this project"). + ExportAsHTML("build/architecture.html") +``` + +Every one of the twelve is `Snapshot` followed by one rendering function, which is why a new format is one +function this chain does not have to know about, and a modifier added here is understood by every format the +day it lands. A query that described a report with no node in it is `ErrEmptySnapshot` rather than an empty +diagram, for the same reason zero matches is a violation everywhere else. + +Note that the terminals of this family take no options bag — the six exporters take the path they write to +and nothing else, and the other seven take no argument at all. The check options are a modifier here, +`WithCheckOptions`, because a report has no `Check` to pass them to. + +## Reading a snapshot + +A `GraphSnapshot` is immutable and ordered: nodes by label, dependencies by source and then target. + +| Method | Hands back | +|---|---| +| `Nodes` | the `GraphNode` values that survived the query | +| `Edges` | the `GraphEdge` values drawn between them | +| `Summary` | the `GraphSummary`: the counts | +| `Title` | what the report is called | +| `Empty` | whether it holds no node at all | + +A `GraphNode` has a `Label` — a file identifier, an import path, or the group a collapse merged it into — and +`IsExternal`, which says whether it is somebody else's code. A `GraphEdge` has its `SourceLabel` and +`TargetLabel`, an `IsSelfDependency` flag, an `IsExternal` flag, the import kinds behind it, and a `Count`: +how many of the project's raw dependencies this one arrow stands for. That count is what makes a collapsed +diagram honest — forty files merged onto two folders is one arrow, and an arrow that does not say *312 +dependencies* invites the reader to think the two folders are barely coupled. + +A `GraphSummary` is a snapshot in numbers, and every field is one a caller legitimately wants alone: +`Nodes`, `Edges`, `Dependencies` — the raw dependencies behind those edges, which does not shrink when a +collapse merges arrows — `ExternalNodes` and `ExternalEdges`. A test asserting that this project depends on +nothing outside it reads one of them. + +## Next + +The graph is extracted once per project and memoised, because a suite asks about one project many times — +which is why [running a rule](running.md) has a word to say about `archunit.ClearGraphCache`. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..7c4a3a4 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,106 @@ +--- +layout: default +title: ArchUnitGo +nav_order: 1 +description: Architecture rules as ordinary Go unit tests — install it, write your first rule, read what a failure looks like. +--- + +# ArchUnitGo + +Write the sentence your team already says out loud — *the api does not touch the database* — as a value, +and let `go test` tell you where the code disagrees. + +```go +func TestTheApiDoesNotTouchTheDatabase(t *testing.T) { + rule := archunit.ProjectFiles(nil). + InFolder("internal/api/**"). + ShouldNot(). + DependOnFiles(). + InFolder("internal/db/**") + + archunit.AssertPasses(t, rule, nil) +} +``` + +That is the whole setup: no fixture, no registration, no configuration file. A rule is a value, `nil` means +the defaults everywhere, and the only thing that reads your project is the terminal at the end of the chain. + +## Install + +```sh +go get github.com/LukasNiessen/ArchUnitGo +``` + +Go 1.26 or newer. The only direct dependency is `golang.org/x/tools`, which is how the extractor talks to +the Go toolchain. There is no tagged release yet, so `go get` resolves to a pseudo-version of `main` and the +API may still move. + +The package is `archunit` while the last element of the module path is `ArchUnitGo`, so give the import the +name it has: + +```go +import archunit "github.com/LukasNiessen/ArchUnitGo" +``` + +## Your first rule + +An architecture rule is a normal test in a normal package. Put it wherever your other tests live: + +```go +package architecture_test + +import ( + "testing" + + archunit "github.com/LukasNiessen/ArchUnitGo" +) + +func TestNoFileDependsOnAnotherInACircle(t *testing.T) { + archunit.AssertPasses(t, archunit.ProjectFiles(nil).Should().HaveNoCycles(), nil) +} +``` + +Three things are worth knowing before you write the second one: + +- **A rule is a value.** Building one does no work. Only the terminal — `AssertPasses` here, or `Check` — + reads the project, so a half-built rule can be stored in a variable and branched from. +- **`nil` means the defaults, everywhere.** The `*ProjectLocator` an entry point takes is `nil` for *the + project this test is in*, found by walking up to the nearest `go.mod`. The `*AssertOptions` and + `*CheckOptions` a terminal takes are `nil` for the defaults. +- **A failing rule is not an error.** `Check` returns `([]Violation, error)`: the violations are the rule's + result and the error is the library or the environment failing. `AssertPasses` turns the first into + `t.Error` and the second into a message saying the check could not be run at all. + +## What a failure looks like + +One `t.Error`, carrying the rule as it was written and then the violations, numbered from one: + +``` +project files, path without filename matches "internal/api/**", should not, depend on files, path without filename matches "internal/db/**" +1 violation: + 1. internal/api/handler.go: should not, depend on files, path without filename matches "internal/db/**"; it depends on internal/db/conn.go +``` + +The rule's own sentence comes first, so a test asserting several rules says which one broke before it says +what broke it. A selector renders as the part of an identifier it was matched against rather than as the verb +that spelled it — `InFolder` reads back as *path without filename matches* — because that is what you have to +compare your glob against. See [patterns and identifiers](patterns.md) for what those parts are. + +## Where to go next + +- [The grammar](grammar.md) — the stages every rule is built from, in every family. +- [Patterns and identifiers](patterns.md) — what a glob means and what it is matched against. +- [The files family](files.md) — what depends on what, how files are named, where they live. +- [The layers family](layers.md) — a named-layer policy as one rule. +- [The slices family](slices.md) — components cut out of identifiers, and diagrams. +- [The metrics family](metrics.md) — the numbers a project adds up to, and what they have to be. +- [Dependency-graph reports](graph.md) — the diagram rather than the rule. +- [Running a rule](running.md) — check options, logging, colors, suites, no test framework at all. +- [How it works](internals.md) — the pipeline, the layout, and where to change something. + +Two things this site deliberately does not hold. The **API reference** is +[pkg.go.dev](https://pkg.go.dev/github.com/LukasNiessen/ArchUnitGo), generated from the doc comments in the +source, because that is where a Go reader looks for one and a second copy would be a second thing to go +stale. The list of **what is not implemented yet** is in the +[README](https://github.com/LukasNiessen/ArchUnitGo#what-is-not-implemented-yet), which is the one place it +is stated and tested. diff --git a/docs/internals.md b/docs/internals.md new file mode 100644 index 0000000..5c4f2b8 --- /dev/null +++ b/docs/internals.md @@ -0,0 +1,137 @@ +--- +layout: default +title: How it works +nav_order: 10 +description: The pipeline behind an ArchUnitGo rule, the repository layout, the four dependency rules the library holds itself to, and where a new verb goes. +--- + +# How it works + +The whole product is the fluent API; everything else is its implementation. This page is the short version of +what is behind it — enough to read the source, find the file a behaviour lives in, or add a verb. + +## The pipeline + +``` +SOURCE -> EXTRACT -> PROJECT -> ASSERT -> REPORT +``` + +| Stage | Does | Knows Go? | +|---|---|---| +| **Source** | finds the user's project, from a locator or by walking up to the nearest `go.mod` | only in how the root is found | +| **Extract** | walks and parses the source, resolves every import to a target, emits the edges | **yes, entirely** | +| **Project** | relabels those edges into what the rule is about — files, slices, layers, components — and drops the rest | no | +| **Assert** | walks the projected structure and emits one violation per disagreement | no | +| **Report** | turns violations into a test failure, a message or a rendered diagram | only the test-framework glue | + +The consequence worth internalising is that **almost all the Go-specific work is in Extract**. Everything +downstream of it is arithmetic over labelled edges, which is why the projections and the assertions can be +tested against a hand-built graph with no project on disk at all — and why a rule behaves the same on Windows +and on Linux. + +It is also why this library is recognisably the same product as its siblings: the four stages, the vocabulary +and the fluent grammar are the shared design, and only Extract is written per language. + +## The layout + +``` +common/ the kernel — everything shared + extraction/ the dependency-graph extractor <- one of the two packages that know Go + projection/ reshaping the graph, plus cycles + assertion/ the violation vocabulary + fluentapi/ Checkable, CheckOptions + archerror/ the technical and user error types + matching/ globs, regular expressions, match targets + logging/ the log a check writes +files/ file-level dependency and naming rules +layers/ named-layer policy +slices/ component and diagram rules +metrics/ numeric code-quality rules <- metrics/extraction is the other one +graph/ dependency-graph reports +archtest/ violation formatting and test-framework glue +archunit.go the public surface — re-exports, nothing else +``` + +`common/extraction` and `metrics/extraction` are those two: the first walks the imports of the whole project, +the second reads what is inside one file, and nothing downstream of either knows what an import or a +statement is. + +Every domain module has the same internal shape, which is the single most useful thing to know about this +repository: reading one module teaches you how to navigate all of them. + +``` +files/ + fluentapi/ the builder chain the user types <- the only public part + assertion/ pure: structure -> violations + projection/ module-specific reshaping (optional) + extraction/ module-specific gathering (optional) + calculation/ pure formulas (optional) +``` + +`assertion`, `projection` and `calculation` are pure: no filesystem, no clock, no globals. That is what makes +the interesting half of the library testable without a project to point it at. + +## The four dependency rules + +The library's own architecture is four rules, and they are the rules it enforces on itself: + +1. `common` depends on nothing but the standard library and the Go analysis toolchain. +2. Domain modules depend on `common`. **They must not depend on each other.** +3. The testing layer depends on `common` and on the domain modules' violation types. Nothing else. +4. The public surface depends on everything, and nothing depends on it. + +Rule 2 is the one that decays first — one module reaching into another for *just one helper* — which is why +they are written down as a suite through this library's own public API in +[architecture_test.go](https://github.com/LukasNiessen/ArchUnitGo/blob/main/architecture_test.go). That file is +also the best worked example this repository has: it is a real policy over a real codebase, and it fails when +somebody breaks it. + +## Two invariants of the data model + +- **Identifiers are project-relative and forward-slashed, everywhere.** Every pattern, every violation and + every label is that spelling, which is why the same rule holds on every platform. +- **Every file gets a self-edge.** That is how a file with no dependencies at all still appears as a node. + Projections filter self-edges out by default, and the node projection is the one that depends on them. + +## Adding a verb + +In order, each step landing in a predictable place: + +1. **Write the sentence first** and read it aloud. If it is not something an architect who does not write Go + would understand, the verb is wrong — that is the acceptance test, before any code. +2. **Pick the module.** A new node vocabulary is a new module; anything else belongs in an existing one. +3. **Define the violation type** in `/assertion`. Data only, never a sentence. +4. **Write the gather function** beside it. Pure, and handling both moods through the mood flag rather than in + two code paths. +5. **Add a projection** in `/projection`, or reuse one from `common`. +6. **Add the fluent stages** in `/fluentapi` — the predicate on both mood builders, and the terminal + implementing `Checkable`. +7. **Wire the empty-test guard** into that terminal. +8. **Teach the violation factory** how to phrase it, in the testing layer. +9. **Test at both levels**: the pure parts against a fixture graph, and one integration test through the + public API. + +If a step has no obvious home, the rule is probably in the wrong module. + +[AGENTS.md](https://github.com/LukasNiessen/ArchUnitGo/blob/main/AGENTS.md) is the authority on all of this — +the architecture, the naming, the grammar and the error taxonomy — for this library and for every other +ArchUnit port. It is what to read before changing anything. + +## Why the documents are tested + +Prose goes stale in the commit that changes the code, so the documents of this repository are held to the +source by tests like everything else: + +- `README.md` is parsed, and every Go identifier it names is looked up in this module's own syntax tree. +- These pages are held to the same guard, plus their own: each family page has to name every verb its module + exports, and every link between pages has to resolve. +- The workflow files are held to the checks they are supposed to run, as text. + +A document nobody can fail is a document that goes stale, and a documentation site is the easiest place in a +repository for that to happen quietly. + +## The API reference + +There is deliberately no reference section on this site. Every exported name of this library carries its own +doc comment, and [pkg.go.dev](https://pkg.go.dev/github.com/LukasNiessen/ArchUnitGo) renders them — which is +where a Go reader looks, and one copy fewer to go stale. diff --git a/docs/layers.md b/docs/layers.md new file mode 100644 index 0000000..22416df --- /dev/null +++ b/docs/layers.md @@ -0,0 +1,121 @@ +--- +layout: default +title: The layers family +nav_order: 5 +description: A named-layer policy in ArchUnitGo — declaring the layers once, then saying what each of them may and may not depend on. +--- + +# The layers family + +An N-layer policy written as file-level rules is N² pairwise rules, and a report about two folder globs reads +worse than a report about `api` and `db`. This family is the same vocabulary with the sets of files named up +front: + +```go +rule := archunit.ProjectLayers(nil). + Layer("api").DefinedByFolder("internal/api/**"). + Layer("domain").DefinedByFolder("internal/domain/**"). + Layer("db").DefinedByFolder("internal/db/**"). + WhereLayer("api").MayOnlyDependOnLayers("domain", "db"). + WhereLayer("db").MayNotDependOnLayers("api") +``` + +`archunit.ProjectLayers` is the entry point and `archunit.Layers` the shorter spelling of it. The chain says +nothing a pile of file-level rules could not — it exists because that pile is miserable to write and worse to +read. + +## The two halves + +A chain has a declaration half and a policy half, and both are chainable: + +| Half | Opened by | Closed by | +|---|---|---| +| Who exists | `Layer(name)` | `DefinedByFolder` or `DefinedBy` | +| What they may do | `WhereLayer(name)` | `MayOnlyDependOnLayers` or `MayNotDependOnLayers` | + +`DefinedByFolder` matches the folder of a file, which is what a layer usually is. `DefinedBy` matches the +whole identifier, which is what a layer whose members are *named* rather than placed needs — +`Layer("persistence").DefinedBy("internal/**/*_repository.go")` is a layer scattered across the tree. + +The policy half is where a chain becomes checkable. A chain that declares three layers and no clause is not +yet a rule about anything, so it has no `Check`: `WhereLayer` is what turns the declaration into one, and +every clause hands back something that takes another `WhereLayer` — so a whole policy is one value. + +## The two clauses + +```go +rule := archunit.ProjectLayers(nil). + Layer("api").DefinedByFolder("internal/api/**"). + Layer("domain").DefinedByFolder("internal/domain/**"). + WhereLayer("api").MayOnlyDependOnLayers("domain"). + WhereLayer("domain").MayOnlyDependOnLayers() +``` + +`MayOnlyDependOnLayers` is the allowlist: this layer may depend on the layers it names and on no other +declared layer. `MayNotDependOnLayers` is the blocklist: whatever else it does, not these. Named with nothing +at all, the allowlist is the **sealed layer** — *domain may only depend on layers, full stop* — which is how +the innermost ring of a hexagonal architecture is spelled. + +There is no mood stage here, because the two clauses carry their own polarity: `should not, may not depend on +layers` is not a sentence anybody would type. The mood is still what makes them one piece of logic rather than +two, and [the grammar](grammar.md#mood) is where that is spelled out. + +## The three semantic rules + +A policy is easy to misread, so its semantics are exactly three rules and no more: + +1. **Dependencies inside a layer are always allowed.** A layer is a set of files that belong together; a + policy is about the arrows between the sets. +2. **A dependency with an end in no declared layer is ignored.** Declaring three layers of a project with + thirty folders is a rule about those three, not a ban on the other twenty-seven — and a file excluded from + a layer by `Except` is in no layer, so it is ignored the same way. +3. **A blocklist clause is asked before an allowlist one.** When both name the same pair, the blocklist wins, + so a general allowlist can be written once and a single forbidden pair carved out of it. + +## Exclusions + +`Except` and its two targeted forms qualify the declaration in front of them, so a layer with a hole in it is +still one declaration: + +```go +policy := archunit.ProjectLayers(nil). + Layer("api").DefinedByFolder("internal/api/**").Except("**/generated"). + Layer("db").DefinedByFolder("internal/db/**").ExceptInPath("**/*_mock.go"). + WhereLayer("db").MayNotDependOnLayers("api") +``` + +| Exclusion | Reads its patterns against | +|---|---| +| `Except` | whatever the declaration in front of it reads — the folder after `DefinedByFolder`, the identifier after `DefinedBy` | +| `ExceptInFolder` | the folder | +| `ExceptInPath` | the whole identifier | + +A file taken out of a layer this way is not moved to another one: it is in none, and every dependency it is an +end of is ignored by rule 2. + +## What a violation says + +`Check` reports `LayerDependencyViolation` values, **one per pair of layers** rather than one per import: the +two layers, the layers the broken clause named, and the concrete file dependencies behind the pair. A policy +broken by two hundred imports between the same two layers is one violation with two hundred dependencies in +it, because *api depends on db* is one fact about the architecture. + +## Asking what a layer holds + +`SelectLayerFiles` resolves the declarations and hands back the files of each layer by name, which is the +first thing to reach for when a policy passes and you doubt it: + +```go +files, err := archunit.ProjectLayers(nil). + Layer("api").DefinedByFolder("internal/api/**"). + Layer("db").DefinedByFolder("internal/db/**"). + SelectLayerFiles(nil) +``` + +A layer no file matched is an empty entry, and it is a violation when the policy is checked rather than a +quiet pass — see [running a rule](running.md). + +## Next + +[Slices](slices.md) are the family for the components a project has *without* declaring them: the names are +cut out of the identifiers rather than written down. diff --git a/docs/metrics.md b/docs/metrics.md new file mode 100644 index 0000000..17e5f23 --- /dev/null +++ b/docs/metrics.md @@ -0,0 +1,182 @@ +--- +layout: default +title: The metrics family +nav_order: 7 +description: The numbers a Go project adds up to — counts, Martin's package metrics, thresholds, the two zones, a metric of your own, and the HTML report. +--- + +# The metrics family + +This family counts rather than judging what depends on what. A rule says where it looks, which number it is +about, and what that number has to be: + +```go +rule := archunit.Metrics(nil). + InFolder("internal/api/**"). + Count(). + LinesOfCode(). + ShouldBeBelow(400) +``` + +`archunit.Metrics` is the entry point, and it has no second spelling: `metrics` is what the family calls itself +in every port. A rule of this family ends in `Check` like every other rule in the library. + +Left without a predicate, the same chain is a measurement rather than a rule — `Measure` hands back one +`Measurement` per subject, carrying the metric's own name, the subject it was read off and the value: + +```go +measurements, err := archunit.Metrics(nil).InFolder("internal/api/**").Count().LinesOfCode().Measure(nil) +``` + +## Scope + +Four scope verbs, chainable and combined with AND. Three of them describe files and `ForClassesMatching` +describes declared types, which is the one thing about this family's scope worth remembering: an exclusion is +about the same population as the verb it qualifies. + +| Verb | Selects by | Excluded by | +|---|---|---| +| `WithName` | the filename | `ExceptWithName` | +| `InFolder` | the folder | `ExceptInFolder` | +| `InPath` | the whole identifier | `ExceptInPath` | +| `ForClassesMatching` | the declared type's own name | `ExceptClassesMatching` | + +`Except` is the plain form, read against the same part as the selector in front of it. + +## Which number + +The group a scope is followed by decides what there is to ask for, so a rule says which *kind* of number it +means before it says which number — `count, method count` reads as one phrase. + +**`Count`** is the eight numbers this library takes of a project as it is written. Six are about a file and two +about a class: + +| Verb | Counts | Per | +|---|---|---| +| `LinesOfCode` | the lines that carry something | file | +| `Statements` | the statements | file | +| `Imports` | the imports | file | +| `Functions` | the functions declared at package level | file | +| `Classes` | the declared types | file | +| `Interfaces` | the declared types that are interfaces | file | +| `MethodCount` | the methods a type has | class | +| `FieldCount` | the fields a type declares | class | + +**`Distance`** is Robert C. Martin's package metrics and the coupling factor beside them, each about a +component — a folder of the project, with the types it declares and the packages it depends on: + +| Verb | Is | +|---|---| +| `Abstractness` | how much of the component is interfaces | +| `Instability` | how much of its coupling points outward | +| `DistanceFromMainSequence` | how far it sits from the line where the two balance | +| `NormalizedDistance` | the same distance on a nought-to-one scale | +| `CouplingFactor` | how much of the coupling it could have with the other selected components it has | + +The eight LCOM formulas are calculated and tested and have no fluent verb yet, which the README's +[what is not implemented yet](https://github.com/LukasNiessen/ArchUnitGo#what-is-not-implemented-yet) states as +the one place it is stated. + +## The six thresholds + +**There are exactly six threshold predicates, and each spells its own mood**, which is why this family has no +mood stage. Five hold every number a rule measured to a figure: + +| Predicate | Holds a measured value to | +|---|---| +| `ShouldBeBelow` | less than the figure | +| `ShouldBeAbove` | more than the figure | +| `ShouldBe` | exactly the figure | +| `ShouldBeBelowOrEqual` | at most the figure | +| `ShouldBeAboveOrEqual` | at least the figure | + +There is no seventh. *Should equal*, *should be at most* and every other synonym of one of the five is +deliberately absent, because two spellings of one comparison mean every reader of a suite has to learn which +of them the author picked. A broken threshold is a `MetricsThresholdViolation`, one per subject, carrying the +subject, the number and the comparison it failed. + +The sixth is `ShouldSatisfy`, for the comparisons no threshold expresses — a question the user writes, and the +words to report it by: + +```go +rule := archunit.Metrics(nil). + ForClassesMatching("*Service"). + Count(). + MethodCount(). + ShouldSatisfy(func(measurement archunit.Measurement, class archunit.MetricsClassInfo) bool { + return measurement.Value <= 20 || class.Interface + }, "have at most 20 methods unless it is an interface") +``` + +The function is a `MetricsSatisfaction` and it is handed both halves of what the library knows: the +`Measurement`, so a predicate can exempt one subject or read the figure, and the `MetricsClassInfo` the number +was read off — the zero value for a metric that is not about a class, since a file's lines of code and a +package's abstractness have no class to be about. It reports a `MetricsSatisfactionViolation`, and the +requirement you wrote is the sentence it says. + +## The two zones + +`Abstractness` and `Instability` are the two axes of a plane, and two of its corners are places a package +should not be. Both checks are on the `Distance` group itself, because each is about both axes at once: + +```go +rule := archunit.Metrics(nil).InFolder("internal/**").Distance().ShouldNotBeInZoneOfPain() +``` + +| Check | Forbids the corner where a package is | +|---|---| +| `ShouldNotBeInZoneOfPain` | concrete and depended upon — rigid, and offering no interface to depend on instead | +| `ShouldNotBeInZoneOfUselessness` | abstract and depended on by nothing — an abstraction nobody uses | + +Each corner is a quarter-circle rather than the point itself, so a package that is *nearly* all concrete and +*nearly* all depended upon is reported too. Both exist in the negative mood alone: the positive would demand +that every selected package be badly designed. A failure is a `MetricsZoneViolation`, carrying the component, +the zone and the two coordinates that put it there. + +## A metric of your own + +`CustomMetric` is the family's escape hatch, and the reason it does not have to be exhaustive: a name, the +words saying what the number means, and your own function for reading it off one class. + +```go +rule := archunit.Metrics(nil). + ForClassesMatching("*Service"). + CustomMetric("public surface", "how many methods and fields a type exposes", + func(class archunit.MetricsClassInfo) float64 { + return float64(class.MethodCount + class.FieldCount) + }). + ShouldBeBelow(20) +``` + +The function is a `MetricsClassMeasure` and it is handed an `archunit.MetricsClassInfo`: the class's name, its +identifier, the file it was declared in, whether it is an interface, how many fields and methods it has, and — +through `MetricsFieldInfo` and `MetricsMethodInfo` — which of its fields each of its methods reaches. +Everything after the verb is unchanged, because a custom metric is a metric and not a second kind of rule. + +## The numbers as a page + +Either group also closes without naming a metric at all, and then the chain is a report rather than a rule. +`ExportAsHTML` measures every number of the group over the one scope and writes them as one self-contained +page — the form to reach for when the numbers are for a person rather than for a threshold: + +```go +err := archunit.Metrics(nil).InFolder("internal/**").Count().ExportAsHTML("build/metrics.html", nil) +``` + +For measurements you have already taken and grouped your own way, `archunit.NewMetricsExporter` is the same +page under your own title, timestamp and stylesheet: + +```go +exporter := archunit.NewMetricsExporter(&archunit.MetricsReportOptions{Title: "the numbers of this project"}) +err := exporter.ExportAsHTML(archunit.MetricsReportData{"lines of code": measurements}, "build/metrics.html") +``` + +`MetricsReportData` is a map from a heading to the measurements under it, and `MetricsReportOptions` is the +page's own `Title`, `Timestamp` and `Style`. The timestamp is a field rather than a clock the library reads: a +page that stamped itself would render different bytes on every run, so a report committed beside the code would +show up in every diff. A scope that selected nothing to measure is `ErrEmptyReport`. + +## Next + +[Dependency-graph reports](graph.md) are the other half of *reporting rather than judging*: the project's own +files, drawn. diff --git a/docs/patterns.md b/docs/patterns.md new file mode 100644 index 0000000..b3030f3 --- /dev/null +++ b/docs/patterns.md @@ -0,0 +1,96 @@ +--- +layout: default +title: Patterns and identifiers +nav_order: 3 +description: What a glob means in ArchUnitGo, what each selector matches it against, and how a file or a declared type is identified. +--- + +# Patterns and identifiers + +Every rule selects code by matching a pattern against an identifier. Two things are worth getting right +before you write a glob: what the identifier looks like, and which part of it the verb you chose reads. + +## Identifiers + +A file is identified by its path relative to the project root, always with forward slashes: +`internal/api/handler.go`. A declared type — a *class*, in the family's vocabulary — is that path's package +followed by the type's own name: `internal/api.Handler`. + +Identifiers are normalised, so `internal\api\handler.go` on Windows and `internal/api/handler.go` on Linux +are the same identifier and one pattern matches both. They are project-relative throughout: no rule ever +sees the absolute path of your checkout, and a pattern that starts with one matches nothing. + +## Globs + +Patterns are globs, and globs are sugar: every one of them compiles to an anchored regular expression in one +place, so nothing downstream of the fluent API ever sees a glob. + +| Glob | Means | +|---|---| +| `*` | any run of characters inside one segment, never crossing `/` | +| `**` | any run of characters, crossing `/`; `a/**` matches `a` itself as well as `a/b/c` | +| `?` | exactly one character, never `/` | +| `[a-z]`, `[!abc]` | one character from a class, or not from it | +| `(**)`, `(*)` | in a slicing only: the part of the identifier to cut a slice name out of | + +Everything else is literal. Matching is case-sensitive, patterns are anchored at both ends — `api/**` does +not match `internal/api/handler.go`, and `**/api/**` does — and there is no escape character, because +separators are normalised and the one character you would want to escape is not special anywhere. + +## What each verb matches against + +Which part of the identifier a pattern is read against is the selector's business, and a violation message +names that part rather than the verb, because the part is what you have to compare your glob to. + +| Verb | Matches against | For `internal/api/handler.go` | +|---|---|---| +| `WithName` | the filename | `handler.go` | +| `InFolder` | everything but the filename | `internal/api` | +| `InPath` | the whole identifier | `internal/api/handler.go` | +| `InFile` | the whole identifier, taken literally | — | +| `ForClassesMatching` | the declared type's own name | `Handler` | + +`InFile` is the one that is not a pattern: the identifier is taken literally, so a file whose name contains +`*`, `[` or `.` needs no defensive spelling. Chaining it twice selects nothing, because scope verbs are +combined with AND and no file is two files. + +## When a glob is not enough + +`DefinedByRegex` and `SliceByRegex` take Go's own `regexp` syntax instead, for the patterns a glob cannot +spell — the fluent verb, and the projection behind it a caller can hold. Every other verb, `DefinedBy` +included, reads a glob: + +```go +byRegex := archunit.ProjectSlices(nil).DefinedByRegex(`internal/([^/]+)/.*`) +byGlob := archunit.ProjectSlices(nil).DefinedBy("internal/(**)/**") // the glob spelling of the same slicing +``` + +Those two describe the same slicing — the second is the first written in the sugar. A regular expression is +anchored at both ends as well, and it has to hold exactly one capturing group when it is a slicing, because +the capture is where the slice's name comes from. + +The layers family has the general form under a name of its own: `DefinedBy` matches the whole identifier of +a file, so a layer whose members are named rather than placed — `internal/**/*_repository.go` — is spelled +with it, and `DefinedByFolder` is the folder-shaped case said out loud. + +## The projections behind the slicing verbs + +A slicing is a `MapFunction`: the thing that relabels one dependency of the graph as a dependency between two +slices, or drops it. The fluent verbs build one for you, and four of them are exported for a caller who wants +to hold one: + +| Function | Slices a project by | +|---|---| +| `archunit.SliceByPattern` | the capture in a glob — the projection behind `DefinedBy` | +| `archunit.SliceByRegex` | the capture in a regular expression — the projection behind `DefinedByRegex` | +| `archunit.SliceByFileSuffix` | the last `_`-separated word of a filename, so `order_handler.go` is in the slice `handler` | +| `archunit.Identity` | nothing at all: every dependency under the identifiers it already carries | + +`SliceByPattern` and `SliceByRegex` return an error for a pattern that will not compile, or one that does not +capture exactly one name. `SliceByFileSuffix` takes no argument, so it has nothing to get wrong. + +## A pattern that matches nothing + +**Zero matches is a violation, not a pass.** A selector matching no file is almost always a stale glob or a +renamed folder, and a rule about nothing is green forever — so every terminal refuses one. That guard, and +the way to ask a selector what it actually resolved to, are on [running a rule](running.md). diff --git a/docs/running.md b/docs/running.md new file mode 100644 index 0000000..e91cceb --- /dev/null +++ b/docs/running.md @@ -0,0 +1,203 @@ +--- +layout: default +title: Running a rule +nav_order: 9 +description: How a rule becomes a test — the assert helpers, check options, violations, colors, logging, the ignore directive and the empty-selection guard. +--- + +# Running a rule + +A rule is a value and nothing happens until a terminal runs it. `Check` is the terminal every rule in every +family ends in, and everything on this page is about what happens around it. + +## As a test + +```go +func TestTheApiDoesNotTouchTheDatabase(t *testing.T) { + rule := archunit.ProjectFiles(nil). + InFolder("internal/api/**"). + ShouldNot(). + DependOnFiles(). + InFolder("internal/db/**") + + archunit.AssertPasses(t, rule, nil) +} +``` + +A rule that holds reports nothing. One that does not is a single `t.Error` carrying the rule as it was written +and then the violations, numbered from one. + +`AssertPasses` needs `Error` and nothing else, which is what `TestingT` says: `*testing.T` satisfies it, and so +does any other framework's handle. There is no registration and no configuration anywhere in this library. + +More than one rule is a map and one call: + +```go +func TestTheArchitectureHolds(t *testing.T) { + archunit.AssertAllPass(t, map[string]archunit.Checkable{ + "the api does not touch the database": archunit.ProjectFiles(nil). + InFolder("internal/api/**"). + ShouldNot(). + DependOnFiles(). + InFolder("internal/db/**"), + "no file depends on another in a circle": archunit.ProjectFiles(nil).Should().HaveNoCycles(), + }, nil) +} +``` + +Each rule is asserted in its own subtest named after the sentence you wrote, so a rule that does not hold fails +that subtest and the rules around it are asserted all the same. The subtests run in the sorted order of their +names, which makes the output the same on every run and lets `go test -run` select one of them. A suite with no +rules in it is a failure rather than a pass, for the same reason a rule that selected no file is. + +`AssertAllPass` takes `TestingRunner` — `Error`, `Helper` and `Run` — so only `*testing.T` satisfies it. A +framework whose handle has no subtests still has `AssertPasses`. + +## Without a test framework + +The report layer is separate from the check, so nothing about this library needs `testing`: + +```go +violations, err := rule.Check(nil) +if err != nil { + return err +} +if result := archunit.NewResultFactory(nil).Result(violations); !result.Passed { + fmt.Println(result.Message) +} +``` + +`Result` is the whole of what an adapter reads: `Passed`, and the `Message` to print. It never ends in a +newline, because the caller's own `t.Error`, log line or diff decides how the last line ends. +`archunit.NewViolationFactory` phrases one violation at a time, for a report of your own shape. + +**A failing rule is not an error.** `Check` returns `([]Violation, error)`: the violations are the rule's +result, and the error is the library or the environment failing — a pattern that will not compile, a project +that will not load, a file that cannot be written. A rule that holds is an empty violation list and a `nil` +error. + +## What a violation is + +A `Violation` carries the thing that disagreed rather than a sentence about it. Its whole contract is `Kind`, +which returns a `ViolationKind` spelled the same way in every ArchUnit port, so a caller can group and count +without asserting on a concrete type: + +```go +counted := map[archunit.ViolationKind]int{} +for _, violation := range violations { + counted[violation.Kind()]++ +} +``` + +The kinds are `archunit.KindEmptyTest`, `archunit.KindFileCycle`, `archunit.KindFileNaming`, +`archunit.KindFileDependency`, `archunit.KindFileExternalDependency`, `archunit.KindFileAdherence`, +`archunit.KindLayerDependency`, `archunit.KindMetricsZone`, `archunit.KindMetricsThreshold`, +`archunit.KindMetricsSatisfaction`, `archunit.KindSliceDependency` and `archunit.KindSliceDiagram`. For the +data itself, type switch on the concrete type — `archunit.FileDependencyViolation` and its siblings, each +listed on its own family's page. + +## Check options + +One options bag, and `nil` is always the defaults. Every default is a zero value, so a check is quiet, strict +about empty selections, free to reuse a cached graph, and looks at the production code under the host +platform's build constraints. + +```go +violations, err := rule.Check(&archunit.CheckOptions{ + AllowEmptyTests: false, // a rule that selected nothing is a violation; see below + IncludeTestFiles: true, // hold _test.go files to the same rules + BuildTags: []string{"linux"}, // the constraints to analyze under + IgnoreScopes: []string{"layers"}, + ClearCache: true, + Logging: &archunit.LogOptions{Writer: os.Stderr, Level: archunit.LogLevelDebug}, +}) +``` + +`AssertOptions` is the two bags each half already has — `Check` for how the rule is run and `Message` for how a +failure is written — so the assert helpers need no vocabulary of their own: + +```go +archunit.AssertPasses(t, rule, &archunit.AssertOptions{ + Check: archunit.CheckOptions{IncludeTestFiles: true}, + Message: archunit.MessageOptions{Palette: archunit.DefaultPalette(), MaxViolations: 10}, +}) +``` + +`MessageOptions` is the report's own two knobs. `Palette` is which color each part of a message is painted in, +and the zero palette paints nothing — plain text is the default because 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. +`archunit.DefaultPalette` is the palette to ask for; `Color` is a closed set — `archunit.ColorRed`, +`archunit.ColorGreen`, `archunit.ColorYellow`, `archunit.ColorBlue`, `archunit.ColorMagenta`, +`archunit.ColorCyan`, `archunit.ColorGray` and `archunit.ColorNone` — so nothing but the library ever writes an +escape sequence. `MaxViolations` is how many violations a report lists before it says how many it left out, and +the cut is never silent: a truncated list that looks complete is worse than a long one. + +## The cache + +Extraction is the expensive half of a check and every rule in a suite asks about the same project, so the +dependency graph is memoised per process. `ClearCache` on the options bag, or `archunit.ClearGraphCache`, is +for source that changed underneath the library — a test that writes a fixture project, generated code produced +between two checks. + +## Logging + +Logging is off by default and there is no way to turn it on globally: the destination is injected per check, a +`nil` `*LogOptions` logs nothing, and a bag with neither a writer nor a file in it logs nothing either. That is +what lets one test assert on a log while the rest of the suite runs beside it. `LogOptions` also holds the file +a CI job archives, and the four levels are `LogLevelDebug`, `LogLevelInfo` — the default — `LogLevelWarn` and +`LogLevelError`. A technical failure is still the error `Check` returns; a log line is never how this library +reports something. + +`Logger` is the open log itself, for a caller assembling something of its own. Every rule this library offers +logs through one already. + +## Keeping one import out of the graph + +Some imports are not dependencies. The directive is written the way Go writes a machine-readable comment, so +`gofmt` leaves it where you put it: + +```go +import ( + "database/sql" + + _ "github.com/lib/pq" //archunit:ignore +) +``` + +A bare directive is honoured by every rule. A scoped one — `//archunit:ignore layers` — is honoured only by a +check that names that scope in `CheckOptions.IgnoreScopes`, and counts as an ordinary dependency everywhere +else. The directive belongs to the one import it is written on, either trailing it or on a comment-only line +directly above it, so a directive above the whole import block belongs to nothing. + +For the blank imports that register a driver, `CheckOptions.IgnoredImportKinds` drops a whole flavor of import +before any edge is emitted — an import kind set, which lives behind the surface in `common/extraction`. + +## When a rule selects nothing + +**Zero matches is a violation, not a pass.** A selector matching no file is almost always a stale glob or a +renamed folder, and such a rule is green forever — so the guard is wired into every terminal, in whichever of +its two shapes that terminal has room for: + +- **A terminal that returns violations reports an `EmptyTestViolation`**, which is `Check` in every family. +- **A report terminal fails with an error**, because a report has no violation list to put a violation in: + `ErrEmptySnapshot` for the graph family, `ErrEmptyReport` for the metrics family's `ExportAsHTML`, and + `ErrNothingToDraw` for the slices family's `ToPlantUML` and `ExportAsPlantUML`. + +`CheckOptions.AllowEmptyTests` opts out of both. The terminals that report emptiness in neither shape are +`Measure` and the scope terminals `SelectFiles`, `SelectLayerFiles` and `SelectSliceFiles`, deliberately: they +judge nothing, so whether an empty selection is a failure is not a question they can ask. `Measure` hands back +the numbers themselves, and no subject is no numbers; a scope terminal hands back what a selector resolved to, +which is the answer a reader wants most in the case where it resolved to nothing. + +To see what a selector actually resolves to, ask the scope stage rather than the rule: + +```go +files, err := archunit.ProjectFiles(nil).InFolder("internal/api/**").SelectFiles(nil) +membership, err := archunit.ProjectLayers(nil).Layer("api").DefinedByFolder("internal/api/**").SelectLayerFiles(nil) +sliced, err := archunit.ProjectSlices(nil).DefinedBy("internal/(**)/**").SelectSliceFiles(nil) +``` + +## Next + +[How it works](internals.md) is where the pipeline behind all of this is laid out, and where to change +something. diff --git a/docs/slices.md b/docs/slices.md new file mode 100644 index 0000000..834ca92 --- /dev/null +++ b/docs/slices.md @@ -0,0 +1,152 @@ +--- +layout: default +title: The slices family +nav_order: 6 +description: Slices in ArchUnitGo — components cut out of file identifiers, one rule per pair, and the whole architecture checked against a component diagram. +--- + +# The slices family + +A slice is a name cut out of a file's identifier. Nothing declares the slices of a project: the capture in the +slicing pattern does, so a slicing is a way of talking about a codebase rather than a list of its parts. + +```go +rule := archunit.ProjectSlices(nil). + DefinedBy("internal/(**)/**"). + ShouldNot(). + ContainDependency("api", "db") +``` + +`internal/(**)/**` says *the slices of this project are its folders under internal*, so +`internal/api/handler.go` is in the slice `api` and a file the pattern does not match is in no slice at all. +That is the difference from [a layer policy](layers.md), where every layer is named before any file is read — +and the reason the two families exist side by side. + +`archunit.ProjectSlices` is the entry point. It has no shorter alias, because `slices` alone is a standard +library package and a chain starting with it would read as one. + +## The slicing + +The scope of this family is **exactly one verb**, not the usual chain of them: + +| Verb | Reads its pattern as | +|---|---| +| `DefinedBy` | a glob, whose one capture — `(**)` or `(*)` — names the slice | +| `DefinedByRegex` | Go's own regular expression syntax, whose one capturing group names the slice | + +`internal/(**)/**` and `internal/([^/]+)/.*` are the same slicing said twice. Both need exactly one capture, +because a slice with two names is not a name; see [patterns and identifiers](patterns.md) for the rest of the +syntax. + +A second slicing is a user error rather than a narrower rule — two slicings would be two vocabularies for the +same project — so a chain that spells one twice reports `ErrSlicedTwice`, and a chain that spells none reports +`ErrNoSlicing`. + +## One pair of slices + +`ContainDependency` takes the two slices as they come out of the capture, in either mood: + +```go +slicing := archunit.ProjectSlices(nil).DefinedBy("internal/(**)/**") + +noDatabase := slicing.ShouldNot().ContainDependency("api", "db") +viaDomain := slicing.Should().ContainDependency("api", "domain") +``` + +Both rules are values over one stored slicing, which is what makes a suite of them cheap to write. `Check` +reports `SliceDependencyViolation` values, carrying the two slices and the concrete file dependencies behind +the pair, because *api depends on db* is one fact however many imports made it true. + +## The whole architecture at once + +Forty pairwise rules nobody keeps up to date are better written as the drawing everybody already has. +`AdhereToDiagram` takes the diagram as text and `AdhereToDiagramInFile` reads it from a file beside the code: + +```go +rule := archunit.ProjectSlices(nil). + DefinedBy("internal/(**)/**"). + Should(). + AdhereToDiagramInFile("docs/architecture.puml") +``` + +```go +rule := archunit.ProjectSlices(nil). + DefinedBy("internal/(**)/**"). + Should(). + AdhereToDiagram(` + @startuml + ' the architecture we agreed on + component [api] + component [domain] + component [db] + [api] --> [domain] + [api] --> [db] + @enduml + `) +``` + +The predicate is on the positive mood alone: *should not adhere to the diagram* is not a rule anybody means. + +The dialect is the component-diagram subset of PlantUML and no more of it — component declarations, arrows, +comments, and the frame. `component [api]`, `component api` and `[api]` each declare a component; `[api] --> +[db]` and `[api] -> [db]` each draw a dependency, and a `: label` after an arrow is read and dropped. A line +outside that grammar is refused with its number and its text rather than skipped, because a diagram whose +arrows are quietly half-read is worse than no diagram: it becomes rules nobody wrote. A styling directive a +drawing needs for its looks can be commented out with `'` for this library's benefit. A text with no component +in it at all is `ErrEmptyDiagram`. + +A project and a drawing can disagree in three ways, and one check reports every one of them it finds: + +| `SliceDiagramFinding` | Says | +|---|---| +| `FindingUndrawnDependency` | the project has a dependency between two slices that the diagram does not draw | +| `FindingUndeclaredSlice` | the project has a slice the diagram does not declare | +| `FindingAbsentComponent` | the diagram declares a component the project has no slice for | + +They are one violation type, `SliceDiagramViolation`, under one kind: a reader checking a project against a +drawing wants one list of the ways the two do not match. Only the first carries the file dependencies, because +the other two report that something is not there at all. + +Two modifiers switch off one finding each, and they are chainable in either order: + +| Modifier | Leaves out | +|---|---| +| `IgnoringOrphanSlices` | the slices no dependency reaches, which an architect drawing the architecture rather than the folder tree may reasonably not draw | +| `IgnoringExternalSlices` | the components this project has no slice for, which is what a drawing of a whole system full of sibling modules is made of | + +Neither touches the dependencies, and a slice that is an end of an arrow and missing from the drawing is a +hole in it whatever the modifiers say. + +## Drawing the project as it is + +The reverse of the rule is a terminal on the slicing itself — a drawing states what a project *is*, and no +rule about it has been written yet: + +```go +diagram, err := archunit.ProjectSlices(nil).DefinedBy("internal/(**)/**").ToPlantUML(nil) +``` + +```go +err := archunit.ProjectSlices(nil). + DefinedBy("internal/(**)/**"). + ExportAsPlantUML("docs/architecture.puml", nil) +``` + +`ToPlantUML` hands back the document as a string and `ExportAsPlantUML` writes it to a file, in exactly the +dialect `AdhereToDiagram` reads. So the way to start using this family on a codebase nobody has drawn yet is +to export the diagram, read it, delete the arrows that should not be there, and check the rest in as the +architecture. A slicing that found no slice at all is `ErrNothingToDraw` rather than an empty frame. + +## Asking what a slice holds + +`SelectSliceFiles` resolves the slicing and hands back the files of each slice by name, which is how a rule +about a slice that does not exist — a typo, a renamed folder — is found in one line: + +```go +files, err := archunit.ProjectSlices(nil).DefinedBy("internal/(**)/**").SelectSliceFiles(nil) +``` + +## Next + +[Metrics](metrics.md) is the family that counts instead of judging what depends on what, and +[dependency-graph reports](graph.md) is the one that draws the project's files rather than its components. diff --git a/docs_test.go b/docs_test.go new file mode 100644 index 0000000..1758ac1 --- /dev/null +++ b/docs_test.go @@ -0,0 +1,895 @@ +package archunit_test + +import ( + "os" + "regexp" + "slices" + "strconv" + "strings" + "testing" +) + +// This file is the documentation site under docs/ held to the library it documents, by the same argument +// readme_test.go makes about README.md: a document nobody can fail is a document that goes stale in the +// commit that changes the code. A site is the easiest place in a repository for that to happen quietly, +// because it is ten pages nobody reads in a diff and it renders just as nicely when it is wrong. +// +// So every page is read the same way the README is — its examples parsed, its `archunit.X` names looked up +// on the public surface, every backticked word of its prose looked up in this module's own syntax tree — +// through the helpers in readme_test.go rather than through a second copy of them. What is new here is what +// only a site can get wrong: a page with no front matter is a page the navigation cannot show, a link to a +// page nobody wrote is a 404, and a family page missing a verb is a verb a reader cannot find at all. +// +// The completeness half is the reason the site is worth having a test for rather than a proofread. Nine +// pages of prose beside a moving fluent API is exactly the situation issue #41 names, and the check that +// scales is not "did somebody remember to document this" — it is "every exported verb of files/fluentapi +// appears on docs/files.md, or this build is red". + +const ( + // docsFolder is the site: every Markdown file directly in it is a page, and the two folders beside + // them are the layout and the stylesheet. The paths below are written with forward slashes because + // that is what a Markdown link between two pages says as well as a path os.ReadFile takes anywhere. + docsFolder = "docs" + // docsLandingPage is the page a reader arrives at, and the one that links to all the others. + docsLandingPage = "docs/index.md" + // docsGrammarPage is where the vocabulary shared by every family is documented once, which is what + // lets the family pages leave the three self-describing methods out — and where the entry points and + // each family's exclusion verbs are stated as counted sets nobody else's page repeats. + docsGrammarPage = "docs/grammar.md" + // docsPatternsPage is the glob syntax, and with it the projections behind the slicing verbs: a table of + // the ones a caller can hold, stated as a count of what the surface exports. + docsPatternsPage = "docs/patterns.md" + // docsMetricsPage and docsGraphPage state almost the whole of their surface as a count, the way the + // README does — and a sentence saying there are six of something is pinned by nothing until somebody + // counts them. + docsMetricsPage = "docs/metrics.md" + docsGraphPage = "docs/graph.md" + // docsRunningPage and docsSlicesPage state a surface as the names themselves: the violation kinds, the + // colors, the log levels, the ways a project and a diagram of it disagree. A list of twelve is complete + // until a thirteenth constant is exported, and stale from that commit on. + docsRunningPage = "docs/running.md" + docsSlicesPage = "docs/slices.md" + // docsConfigFile, docsLayoutFile and docsStylesheet are the whole of the site's machinery. There is + // no generator, no lockfile and no build step: GitHub's own Jekyll pours the pages into the layout. + docsConfigFile = "docs/_config.yml" + docsLayoutFile = "docs/_layouts/default.html" + docsStylesheet = "docs/assets/docs.css" + // pagesWorkflow publishes the site and checks nothing, which is what the last test below is about. + pagesWorkflow = ".github/workflows/pages.yml" +) + +// TestTheDocsSiteExamplesAreValidGo parses every ```go block of every page, for the reason the README's +// examples are parsed: a reader copies one, the compiler complains about the document rather than about +// their code, and they have no way to tell which of the two is wrong. +func TestTheDocsSiteExamplesAreValidGo(t *testing.T) { + examples := 0 + + for _, documented := range pagesOfTheDocsSite(t) { + for number, block := range goBlocksOf(t, documented.path) { + examples++ + if _, err := parseExample(block); err != nil { + t.Errorf("the %s Go example in %s does not parse: %v\n%s", + ordinal(number+1), documented.path, err, block) + } + } + } + if examples == 0 { + t.Errorf("%s holds no Go example at all, so nothing here is checking anything about this library", + docsFolder) + } +} + +// TestTheDocsSiteNamesOnlySymbolsThePublicSurfaceHas is the guard against a site describing an API the +// library does not have: every `archunit.X` in an example is an exported name of archunit.go, every method +// of a chain that starts there is a method this module declares, and every field an example fills in on an +// options bag is a field that exists. +func TestTheDocsSiteNamesOnlySymbolsThePublicSurfaceHas(t *testing.T) { + declared := declarationsOfThisModule(t) + + for _, documented := range pagesOfTheDocsSite(t) { + for number, block := range goBlocksOf(t, documented.path) { + example, err := parseExample(block) + if err != nil { + continue // TestTheDocsSiteExamplesAreValidGo reports this one. + } + + for _, used := range selectionsRootedAtTheSurface(example) { + if used.onThePackage && !declared.surface[used.name] { + t.Errorf("the %s Go example in %s uses %s.%s, which %s does not export", + ordinal(number+1), documented.path, surfacePackage, used.name, surfaceFile) + } + if !used.onThePackage && !declared.methods[used.name] { + t.Errorf("the %s Go example in %s calls .%s() on a chain from %s, and this module declares "+ + "no such method", ordinal(number+1), documented.path, used.name, surfacePackage) + } + } + for _, field := range fieldNamesOfTheLiterals(example) { + if !declared.names[field] { + t.Errorf("the %s Go example in %s fills in the field %s, which this module declares nowhere", + ordinal(number+1), documented.path, field) + } + } + } + } +} + +// TestTheDocsSiteNamesOnlyIdentifiersThisModuleDeclares is the same guard over the prose, where most of a +// documentation page's names are: the tables of verbs, the fields of a struct a predicate is handed, the +// sentinel errors a terminal returns. +// +// It is the same check as the README's, against the same two short exemption lists, because the two +// documents describe one library and a name that is fine in one is fine in the other. +func TestTheDocsSiteNamesOnlyIdentifiersThisModuleDeclares(t *testing.T) { + declared := declarationsOfThisModule(t) + exempt := append(strings.Split(modulePathOfThisRepository(t), "/"), namesOfTheReadersProject...) + + for _, documented := range pagesOfTheDocsSite(t) { + inTheProse := identifiersNamedInTheProseOf(t, documented.path) + if len(inTheProse) == 0 { + t.Errorf("%s names no identifier of this library outside its code blocks: a page of this site that "+ + "is only prose is a page nothing checks", documented.path) + } + + for _, named := range inTheProse { + if slices.Contains(exempt, named.name) { + continue + } + switch { + case named.onTheSurface && !declared.surface[named.name]: + t.Errorf("%s names `%s`, and %s exports nothing by that name", + documented.path, named.spelled, surfaceFile) + case !named.onTheSurface && !declared.names[named.name]: + t.Errorf("%s names `%s` as an identifier of this library, and this module declares nothing by "+ + "that name", documented.path, named.spelled) + } + } + } +} + +// TestEveryPageOfTheDocsSiteSaysWhereItBelongs pins the front matter, which is the only thing holding the +// site together: the layout builds its navigation out of every page that gives itself a nav_order, so a +// page without one is a page nobody can reach, and two pages with the same one are ordered by whatever +// Jekyll happened to sort them by. +// +// The orders are 1..N with no gap and no repeat, and the title in the front matter is the page's own first +// heading — otherwise the navigation and the page disagree about what the page is called. +func TestEveryPageOfTheDocsSiteSaysWhereItBelongs(t *testing.T) { + pages := pagesOfTheDocsSite(t) + atPosition := map[int]string{} + + for _, documented := range pages { + if layout := documented.frontMatter["layout"]; layout != "default" { + t.Errorf("%s states the layout %q: every page of this site is poured into %s, which is where its "+ + "navigation and its stylesheet come from", documented.path, layout, docsLayoutFile) + } + for _, key := range []string{"title", "description"} { + if documented.frontMatter[key] == "" { + t.Errorf("%s states no %s in its front matter: the navigation is built from the title and the "+ + "description is what a search result and a link preview show", documented.path, key) + } + } + if documented.heading != documented.frontMatter["title"] { + t.Errorf("%s is called %q in its front matter and %q in its own first heading: the navigation and "+ + "the page would disagree about the name of the page", + documented.path, documented.frontMatter["title"], documented.heading) + } + + order, stated := navOrderOf(documented) + switch { + case !stated: + t.Errorf("%s states no nav_order: %s builds the navigation from that key alone, so a page without "+ + "one is published and linked from nowhere", documented.path, docsLayoutFile) + case atPosition[order] != "": + t.Errorf("%s and %s both state nav_order %d, so the navigation puts them in whichever order they "+ + "happened to be sorted in", atPosition[order], documented.path, order) + default: + atPosition[order] = documented.path + } + } + + for position := 1; position <= len(pages); position++ { + if atPosition[position] == "" { + t.Errorf("%s holds %d pages and none of them states nav_order %d: the orders are 1..%d, so a gap "+ + "means a page gave itself an order the site has no room for", + docsFolder, len(pages), position, len(pages)) + } + } + if atPosition[1] != docsLandingPage { + t.Errorf("%s is the first chapter of the navigation and %s is the page a reader arrives at", + atPosition[1], docsLandingPage) + } +} + +// TestEveryLinkOfTheDocsSiteResolves is the check a rendered site cannot do for itself. These pages link to +// each other by filename — `[the files family](files.md)` — so that every link works while reading the +// source on GitHub as well as on the built site, where jekyll-relative-links rewrites them. The cost of +// that spelling is that a link to a page nobody wrote looks exactly like a link to one that exists. +// +// A fragment is resolved too, against the target page's own headings, because a renamed heading is the way +// a link between two pages half-breaks: it lands on the page and then somewhere arbitrary on it. +func TestEveryLinkOfTheDocsSiteResolves(t *testing.T) { + for _, documented := range pagesOfTheDocsSite(t) { + targets := linkTargetsOf(t, documented.path) + if len(targets) == 0 { + t.Errorf("%s links to nothing at all, not even to the page after it: this site is read in order", + documented.path) + } + + for _, target := range targets { + if strings.HasPrefix(target, "#") || strings.HasPrefix(target, "mailto:") { + continue // an anchor inside this page, or an address; neither is a file of this site. + } + if strings.HasPrefix(target, "http") { + if !strings.HasPrefix(target, "https://") { + t.Errorf("%s links to %s over plain http", documented.path, target) + } + continue // somebody else's server, which nothing in this repository can hold to existing. + } + + file, fragment, _ := strings.Cut(target, "#") + if !strings.HasSuffix(file, ".md") { + t.Errorf("%s links to %s, and an internal link of this site is a page's filename: that is what "+ + "works in the repository as well as on the built site", documented.path, target) + continue + } + if _, err := os.Stat(docsFolder + "/" + file); err != nil { + t.Errorf("%s links to %s, and %s holds no such page", documented.path, target, docsFolder) + continue + } + if fragment == "" { + continue + } + if !slices.ContainsFunc(headingsOf(t, docsFolder+"/"+file), func(heading string) bool { + return anchorOf(heading) == fragment + }) { + t.Errorf("%s links to %s, and %s has no heading that lands on #%s", + documented.path, target, file, fragment) + } + } + } +} + +// TestTheDocsSiteLinksInMarkdownRatherThanInHtml is the one rule about how a page is written, and it is +// here because breaking it produces a site whose links work in the repository and 404 once published — +// the one kind of broken link nobody notices. +// +// jekyll-relative-links rewrites Markdown links only. A raw is left exactly as it was +// written, and a page served at /ArchUnitGo/files/ then points at /ArchUnitGo/files/files.md. +func TestTheDocsSiteLinksInMarkdownRatherThanInHtml(t *testing.T) { + for _, documented := range pagesOfTheDocsSite(t) { + content := readDocument(t, documented.path) + for _, raw := range []string{"href=", " 0 { + return headings[0] + } + return "" +} + +// headingsOf are a page's headings, in order, with their `#`s taken off. They are read out of the prose so +// that a comment in an example is not a heading. +func headingsOf(t *testing.T, document string) []string { + t.Helper() + + var headings []string + for line := range strings.Lines(proseOf(t, document)) { + if text, isHeading := strings.CutPrefix(strings.TrimSpace(line), "#"); isHeading { + headings = append(headings, strings.TrimSpace(strings.TrimLeft(text, "#"))) + } + } + return headings +} + +// anchorOf is the fragment a heading can be linked at: its text lowercased, with every run of anything +// else turned into one hyphen. `## Mood` is reached as `grammar.md#mood`, which is what a link between two +// pages of this site points at. +func anchorOf(heading string) string { + return strings.Trim(notInAnAnchor.ReplaceAllString(strings.ToLower(heading), "-"), "-") +} + +// linkTargetsOf is every target a page links to, in the order they appear: what stands in the parentheses +// of each Markdown link. The whole document is read rather than only its prose, because a link inside an +// example would be just as broken. +func linkTargetsOf(t *testing.T, document string) []string { + t.Helper() + + var targets []string + for _, link := range markdownLink.FindAllStringSubmatch(readDocument(t, document), -1) { + targets = append(targets, strings.TrimSpace(link[1])) + } + return targets +} + +// valueOfTheSiteSetting is a top-level setting of the site's configuration. Only a top-level key matches, +// because the value of an indented one belongs to the key above it and is not the site's own answer to +// anything. +func valueOfTheSiteSetting(t *testing.T, key string) string { + t.Helper() + + for line := range strings.Lines(readDocument(t, docsConfigFile)) { + if value, stated := strings.CutPrefix(line, key+":"); stated { + return strings.TrimSpace(value) + } + } + t.Fatalf("%s states no %s", docsConfigFile, key) + return "" +} + +// verbsOf are the exported methods of one stage of one fluent package that hand back one particular thing, +// which is how every count these pages state is counted: a modifier hands back its own builder, a metric +// verb hands back the stage that can be resolved, a threshold hands back a condition. +// +// An exclusion is never one of them. `Except` qualifies the verb in front of it, so it is part of a clause +// rather than a verb a reader picks from a list. +func verbsOf(declared declarations, pkg, receiver, returns string) []string { + var found []string + for _, method := range declared.methodsOf(pkg) { + if method.receiver != receiver || strings.HasPrefix(method.name, "Except") { + continue + } + if method.results() == returns { + found = append(found, method.name) + } + } + return found +} + +// exclusionsOf are the exclusion verbs one family offers, as the distinct names of them: `Except` and +// whichever targeted forms the family's own selectors name. +// +// Distinct, because a family declares each of them on every selector that has one — files/fluentapi spells +// the same four on its scope stage and again on its dependency clause — while a page saying a family offers +// four of them is counting the vocabulary a reader has to learn, which is the name and not the receiver. +func exclusionsOf(declared declarations, pkg string) []string { + var found []string + for _, method := range declared.methodsOf(pkg) { + if strings.HasPrefix(method.name, "Except") && !slices.Contains(found, method.name) { + found = append(found, method.name) + } + } + slices.Sort(found) // A failure naming them in declaration order would name them differently per receiver. + return found +} + +// exportedProjections are the `MapFunction` factories the public surface hands a caller who wants to hold +// the slicing a fluent verb builds: the `SliceBy` family and `Identity`, which is the one of them not named +// after a slicing because it is the absence of one. +// +// `Identity` is looked up by name rather than by a prefix because it is a whole name, and it is looked up +// rather than assumed so that the count goes red if it stops being exported as well as when a fifth +// projection joins it. +func exportedProjections(declared declarations) []string { + found := membersOfTheSurfacePrefixed(declared, "SliceBy") + if declared.surface["Identity"] { + found = append(found, "Identity") + } + return found +} + +// membersOfTheSurfacePrefixed are the public surface's members of one closed set, found by the prefix every +// member of it shares: `Kind` is the violation kinds, `Color` the colors a report is painted in. It is how a +// page that states such a set as a list is held to the list rather than to its own count. +// +// The name equal to the prefix is not one of them. That is the type the members are of — `Color`, `LogLevel` — +// which a page names as the set itself and not as a member of it. +func membersOfTheSurfacePrefixed(declared declarations, prefix string) []string { + var found []string + for name := range declared.surface { + if name != prefix && strings.HasPrefix(name, prefix) { + found = append(found, name) + } + } + slices.Sort(found) // The surface is a map, and a failure naming them in a different order every run is noise. + return found +} + +// terminalsOf are the methods of one stage that hand something back and can fail — which is what a +// terminal is, in every family: the one stage that reads the project. +func terminalsOf(declared declarations, pkg, receiver string) []string { + var found []string + for _, method := range declared.methodsOf(pkg) { + if method.receiver == receiver && strings.HasSuffix(method.results(), "error") { + found = append(found, method.name) + } + } + return found +} + +// methodsEveryFamilyShares are the three methods that let a chain describe itself rather than judge +// anything. They are not on every stage of every family — `String` is on all but LayerPolicyBuilder, `Mood` +// on the mood stage the files and slices families have, `Selectors` on the files and metrics scope stages — +// which is why the exemption is by name: wherever a family declares one, docs/grammar.md is where it is +// documented, for all five at once. That is why a family page is not asked to name them, and why the test +// that exempts them also holds that page to naming them. +func methodsEveryFamilyShares() []string { + return []string{"String", "Mood", "Selectors"} +} + +// markdownLink is a Markdown link, and the group is what it points at. Only this spelling is looked for: +// a raw HTML link is a finding of its own, because the built site does not rewrite one. +var markdownLink = regexp.MustCompile(`\[[^\]]*\]\(([^)]+)\)`) + +// notInAnAnchor is every run of characters a heading's fragment turns into a hyphen. +var notInAnAnchor = regexp.MustCompile(`[^a-z0-9]+`) diff --git a/readme_test.go b/readme_test.go index c414009..57fbefe 100644 --- a/readme_test.go +++ b/readme_test.go @@ -53,7 +53,12 @@ const ( // every rule in the document is written. Nothing here says which of the three a block has to be, // because that is the author's business and all three read correctly on the page. func TestTheReadmeExamplesAreValidGo(t *testing.T) { - for number, block := range goBlocksOfTheReadme(t) { + blocks := goBlocksOf(t, readmeFile) + if len(blocks) == 0 { + t.Fatalf("%s holds no Go example at all", readmeFile) + } + + for number, block := range blocks { if _, err := parseExample(block); err != nil { t.Errorf("the %s Go example in %s does not parse: %v\n%s", ordinal(number+1), readmeFile, err, block) } @@ -70,7 +75,7 @@ func TestTheReadmeExamplesAreValidGo(t *testing.T) { func TestTheReadmeNamesOnlySymbolsThePublicSurfaceHas(t *testing.T) { declared := declarationsOfThisModule(t) - for number, block := range goBlocksOfTheReadme(t) { + for number, block := range goBlocksOf(t, readmeFile) { example, err := parseExample(block) if err != nil { continue // TestTheReadmeExamplesAreValidGo reports this one. @@ -114,7 +119,12 @@ func TestTheReadmeNamesOnlyIdentifiersThisModuleDeclares(t *testing.T) { declared := declarationsOfThisModule(t) exempt := append(strings.Split(modulePathOfThisRepository(t), "/"), namesOfTheReadersProject...) - for _, named := range identifiersTheReadmeProseNames(t) { + inTheProse := identifiersNamedInTheProseOf(t, readmeFile) + if len(inTheProse) == 0 { + t.Fatalf("%s names no identifier of this library outside its code blocks", readmeFile) + } + + for _, named := range inTheProse { if slices.Contains(exempt, named.name) { continue } @@ -136,7 +146,7 @@ func TestTheReadmeNamesOnlyIdentifiersThisModuleDeclares(t *testing.T) { // sentence a reader chooses this library on, and it stops being true in a commit that has nothing to do // with the README. func TestTheReadmeInstallsThisModuleTheWayGoModDescribesIt(t *testing.T) { - readme := readTheReadme(t) + readme := readDocument(t, readmeFile) module := readTheModuleFile(t) for _, required := range []string{ @@ -176,9 +186,9 @@ func TestTheReadmeInstallsThisModuleTheWayGoModDescribesIt(t *testing.T) { // `String` is exempt from the graph list: the README says once, of every stage of a chain that can describe // itself, that it is a fmt.Stringer, and repeating it per family would be noise. func TestTheReadmeNamesEveryVerbOfTheClosedSetsItDescribes(t *testing.T) { - readme := readTheReadme(t) + readme := readDocument(t, readmeFile) declared := declarationsOfThisModule(t) - named := namesTheReadmeNames(t) + named := namesTheDocumentNames(t, readmeFile) for _, verb := range declared.methodsOf("metrics/fluentapi") { if !strings.HasPrefix(verb.name, "Should") { @@ -232,7 +242,7 @@ func TestTheReadmeNamesEveryVerbOfTheClosedSetsItDescribes(t *testing.T) { // is one that hands back a report or an error, and `Except` is neither because an exclusion qualifies // the modifier in front of it. func TestTheReadmeCountsTheGraphFamilyCorrectly(t *testing.T) { - readme := readTheReadme(t) + readme := readDocument(t, readmeFile) var modifiers, terminals []string for _, method := range declarationsOfThisModule(t).methodsOf("graph/fluentapi") { @@ -333,6 +343,10 @@ type declarations struct { names map[string]bool // byPackage is the exported methods of each package, keyed by its slash-separated directory. byPackage map[string][]method + // fieldsByType is the exported fields of each struct type, keyed by its package's directory and its own + // name — `graph/projection.Summary`. A document that says *every field* of one type is what this is for, + // because the flat set of names above cannot say which type a field belongs to. + fieldsByType map[string][]string } // methodsOf are the exported methods this package declares, in the order they were read. @@ -340,6 +354,11 @@ func (d declarations) methodsOf(pkg string) []method { return d.byPackage[pkg] } +// fieldsOf are the exported fields this struct type declares, in the order they were read. +func (d declarations) fieldsOf(pkg, name string) []string { + return d.fieldsByType[pkg+"."+name] +} + // declarationsOfThisModule reads every non-test Go file of the repository and collects what it declares. // It is one parse of the tree per test that needs it, which costs a few milliseconds and buys a document // that cannot name something the library does not have. @@ -347,10 +366,11 @@ func declarationsOfThisModule(t *testing.T) declarations { t.Helper() declared := declarations{ - surface: map[string]bool{}, - methods: map[string]bool{}, - names: map[string]bool{}, - byPackage: map[string][]method{}, + surface: map[string]bool{}, + methods: map[string]bool{}, + names: map[string]bool{}, + byPackage: map[string][]method{}, + fieldsByType: map[string][]string{}, } for _, path := range goFilesOfThisRepository(t) { @@ -391,20 +411,22 @@ func (d declarations) collect(pkg, path string, declaration ast.Decl) { }) case *ast.GenDecl: for _, spec := range typed.Specs { - d.collectSpec(path, spec) + d.collectSpec(pkg, path, spec) } } } // collectSpec files a type, constant or variable, and the exported members of a struct or an interface. -// The members are here because most of what a README says about an options bag is its field names. -func (d declarations) collectSpec(path string, spec ast.Spec) { +// The members are here because most of what a README says about an options bag is its field names, and a +// struct's are filed under the type they belong to as well, because a page that says *every field* of one +// type has to be held to that type's fields rather than to every field the module declares. +func (d declarations) collectSpec(pkg, path string, spec ast.Spec) { switch typed := spec.(type) { case *ast.TypeSpec: d.declare(path, typed.Name) switch underlying := typed.Type.(type) { case *ast.StructType: - d.collectFields(underlying.Fields) + d.fieldsByType[pkg+"."+typed.Name.Name] = d.collectFields(underlying.Fields) case *ast.InterfaceType: d.collectFields(underlying.Methods) } @@ -415,19 +437,23 @@ func (d declarations) collectSpec(path string, spec ast.Spec) { } } -// collectFields files the exported members of a struct or an interface. An embedded field has no name -// of its own, so it is skipped: whatever it names is declared where its type is. -func (d declarations) collectFields(fields *ast.FieldList) { +// collectFields files the exported members of a struct or an interface, and hands them back so that a +// struct's can also be filed under the type they belong to. An embedded field has no name of its own, so it +// is skipped: whatever it names is declared where its type is. +func (d declarations) collectFields(fields *ast.FieldList) []string { if fields == nil { - return + return nil } + var exported []string for _, field := range fields.List { for _, name := range field.Names { if name.IsExported() { d.names[name.Name] = true + exported = append(exported, name.Name) } } } + return exported } // declare files one exported name, and the public surface's own names twice. @@ -562,31 +588,32 @@ func fieldNamesOfTheLiterals(example *ast.File) []string { return found } -// namesOfTheReadersProject are the backticked capitalised words of the README that name something in the -// project a reader is holding this library against, not something in the library. `Handler` is the -// declared type the match-target table walks `internal/api/handler.go` through, and a document that -// could not name one would have to explain `ForClassesMatching` without an example of a class. +// namesOfTheReadersProject are the backticked capitalised words of this repository's documents that name +// something in the project a reader is holding this library against, not something in the library. +// `Handler` is the declared type the match-target table walks `internal/api/handler.go` through, and a +// document that could not name one would have to explain `ForClassesMatching` without an example of a class. // // The list is deliberately short. Anything on it is a name nothing checks, which is the cost of writing // an example, so a new entry is a decision rather than a way around a failing test. var namesOfTheReadersProject = []string{"Handler"} -// namesTheReadmeQualifiesWithSomethingElse are the backticked words of the README that read as a Go name -// qualified by something this module is not: an interface of the standard library, a package behind the -// public surface written as a user would have to import it, and a declared type of the reader's own project. +// namesTheDocumentsQualifyWithSomethingElse are the backticked words of this repository's documents that +// read as a Go name qualified by something this module is not: an interface of the standard library, a +// package behind the public surface written as a user would have to import it, and a declared type of the +// reader's own project. // // They are exempt for the same reason namesOfTheReadersProject is, and the list is short for the same // reason: each entry is a name nothing checks. -var namesTheReadmeQualifiesWithSomethingElse = []string{ +var namesTheDocumentsQualifyWithSomethingElse = []string{ "fmt.Stringer", "extraction.ImportKindSet", "internal/api.Handler", } -// identifierInProse is a backticked word in the README that reads as an exported Go identifier: one +// identifierInProse is a backticked word in a document that reads as an exported Go identifier: one // word, starting with a capital. A pattern, a shell command, a path and a lowercase keyword all fail it, // which is the point — those are not names this module can be asked about. var identifierInProse = regexp.MustCompile(`^[A-Z][A-Za-z0-9]*$`) -// proseName is one backticked word of the README that reads as a Go name, and where it has to be looked up. +// proseName is one backticked word of a document that reads as a Go name, and where it has to be looked up. type proseName struct { // spelled is the word as the document wrote it, qualifier and pointer included, so that a failure // quotes the reader what they would search the document for. @@ -598,7 +625,7 @@ type proseName struct { onTheSurface bool } -// identifiersTheReadmeProseNames are the identifiers the document names outside its code blocks: every +// identifiersNamedInTheProseOf are the identifiers a document names outside its code blocks: every // `Backticked` word that reads as an exported Go name, with a trailing `()` taken off so that `Kind()` // is checked as the method it is. // @@ -611,13 +638,13 @@ type proseName struct { // // The code blocks are cut out first because they are checked properly, against the syntax tree, by the // two tests above. -func identifiersTheReadmeProseNames(t *testing.T) []proseName { +func identifiersNamedInTheProseOf(t *testing.T, document string) []proseName { t.Helper() var found []proseName - for _, quoted := range regexp.MustCompile("`([^`\n]+)`").FindAllStringSubmatch(proseOfTheReadme(t), -1) { + for _, quoted := range regexp.MustCompile("`([^`\n]+)`").FindAllStringSubmatch(proseOf(t, document), -1) { spelled := strings.TrimSuffix(quoted[1], "()") - if slices.Contains(namesTheReadmeQualifiesWithSomethingElse, spelled) { + if slices.Contains(namesTheDocumentsQualifyWithSomethingElse, spelled) { continue } qualifier, name, qualified := strings.Cut(strings.TrimPrefix(spelled, "*"), ".") @@ -632,27 +659,24 @@ func identifiersTheReadmeProseNames(t *testing.T) []proseName { } found = append(found, proseName{spelled: spelled, name: name, onTheSurface: qualifier == surfacePackage}) } - if len(found) == 0 { - t.Fatalf("%s names no identifier of this library outside its code blocks", readmeFile) - } return found } -// namesTheReadmeNames is every name the document states as a name, as a set: the identifiers of its prose +// namesTheDocumentNames is every name a document states as a name, as a set: the identifiers of its prose // and the selections of its examples. // // It is what a completeness check has to be written against rather than a substring search over the // document, because a substring search cannot fail for a prefix — a README that names `ShouldBeBelow` and // nothing else satisfies `strings.Contains(readme, "ShouldBe")`, so three of the six threshold verbs would // be pinned by nothing. -func namesTheReadmeNames(t *testing.T) map[string]bool { +func namesTheDocumentNames(t *testing.T, document string) map[string]bool { t.Helper() named := map[string]bool{} - for _, name := range identifiersTheReadmeProseNames(t) { + for _, name := range identifiersNamedInTheProseOf(t, document) { named[name.name] = true } - for _, block := range goBlocksOfTheReadme(t) { + for _, block := range goBlocksOf(t, document) { example, err := parseExample(block) if err != nil { continue // TestTheReadmeExamplesAreValidGo reports this one. @@ -664,13 +688,13 @@ func namesTheReadmeNames(t *testing.T) map[string]bool { return named } -// proseOfTheReadme is the document with its fenced code blocks removed. -func proseOfTheReadme(t *testing.T) string { +// proseOf is a document with its fenced code blocks removed. +func proseOf(t *testing.T, document string) string { t.Helper() var prose []string fenced := false - for line := range strings.Lines(readTheReadme(t)) { + for line := range strings.Lines(readDocument(t, document)) { if strings.HasPrefix(strings.TrimSpace(line), "```") { fenced = !fenced continue @@ -682,16 +706,15 @@ func proseOfTheReadme(t *testing.T) string { return strings.Join(prose, "") } -// goBlocksOfTheReadme are the document's ```go blocks, in the order they appear. A block fenced as -// anything else — the shell command, the failure message a rule prints, the layout table — is not Go -// and is not read as Go. -func goBlocksOfTheReadme(t *testing.T) []string { +// goBlocksOf are a document's ```go blocks, in the order they appear. A block fenced as anything else — +// the shell command, the failure message a rule prints, the layout table — is not Go and is not read as Go. +func goBlocksOf(t *testing.T, document string) []string { t.Helper() var blocks []string var current []string fenced := false - for line := range strings.Lines(readTheReadme(t)) { + for line := range strings.Lines(readDocument(t, document)) { switch trimmed := strings.TrimSpace(line); { case fenced && strings.HasPrefix(trimmed, "```"): blocks = append(blocks, strings.Join(current, "")) @@ -703,10 +726,7 @@ func goBlocksOfTheReadme(t *testing.T) []string { } } if fenced { - t.Fatalf("%s has a code fence that is never closed", readmeFile) - } - if len(blocks) == 0 { - t.Fatalf("%s holds no Go example at all", readmeFile) + t.Fatalf("%s has a code fence that is never closed", document) } return blocks } @@ -730,14 +750,19 @@ func parseExample(block string) (*ast.File, error) { ) } -// readTheReadme returns the document's contents, failing the test if the one document a user starts from -// is not there. -func readTheReadme(t *testing.T) string { +// readDocument returns a document's contents as text, failing the test if a document this repository is +// supposed to hold is not there. +// +// It takes the path because README.md is not the only tested document any more: docs_test.go holds the pages +// of the documentation site to the same syntax tree through the same helpers, and reads the site's +// configuration, its layout and the workflow that publishes it with this too. A second reader of a file +// would be a second thing to keep in step. +func readDocument(t *testing.T, document string) string { t.Helper() - content, err := os.ReadFile(readmeFile) + content, err := os.ReadFile(document) if err != nil { - t.Fatalf("reading %s failed: %v", readmeFile, err) + t.Fatalf("reading %s failed: %v", document, err) } return string(content) }