Introduction
Architecture Rules lets you write your repository’s architecture in one file, architecture.yaml,
and enforce it with an oxlint plugin and a CLI. Reach for it when you want import boundaries,
folder layouts and naming rules checked on every change instead of in code review.
What it enforces
Section titled “What it enforces”Each question below is answered by one family of rules, each with its own page.
| Question | Family |
|---|---|
| What may this folder import? | imports |
| Who may import it? | importedBy |
| Which importers may use this exported symbol? | exports |
| Which names may this file declare or call? | members |
| What may this file export? | surface |
| Which files may live in this folder? | structure |
| What may they be called? | structure |
| Which sibling files does this file require? | structure |
| Is there an import cycle? | graph |
| Does anything import this file? | graph |
| Can this layer reach that one, by any route? | graph |
The oxlint plugin and the CLI both check the first five. graph needs the whole repository, so
only the CLI checks it. To adopt rules on an
existing codebase, see adoption.
A manifest is a tree
Section titled “A manifest is a tree”The manifest reads like a directory listing. Everything about a folder is written at that folder, and its subfolders inherit it:
"@/modules/{module}/domain/": imports: reset: true external: [effect] allow: ["@/modules/{module}/domain/**"] children: "*.root.ts": { requires: ["{base}.root.test.ts"] }This says domain/ may import only itself and effect, and every *.root.ts needs a test beside it.
To see every rule that governs one file, run
architecture explain.
Two guarantees
Section titled “Two guarantees”- Rules match resolved files. An import is resolved through your
tsconfigpaths and workspace links before any rule sees it. An import that cannot be resolved is an error, not a skip. See resolution. - Every rule proves it can fire. Each rule is tested against a generated violation when it loads, and the plugin refuses to load if one no longer matches anything. See probes.