# easement
Architecture quality gate for polyglot codebases.
Declare the components of your system and which of them may depend on which. `easement` extracts the real dependencies from the code, builds the graph and fails the build when the code drifts from the declared architecture.
> **easement** — a legal right to cross someone else's land. In `easement`, every allowed dependency between components is an explicit easement; everything else is trespassing.
## Install
`easement` runs a SCIP indexer for each indexed language it finds, so install those too, see [Indexers](#indexers).
```sh
brew install mokevnin/tap/easement
```
Homebrew works on macOS and Linux. Other options:
- the install script for macOS and Linux, which checks the archive against the checksums of the release and installs to `/usr/local/bin`:
```sh
curl -fsSL https://raw.githubusercontent.com/mokevnin/easement/main/install.sh | sh
```
Pass `-b <dir>` to install elsewhere and `-v <version>` to pin a release: `... | sh -s -- -b ~/.local/bin -v 0.1.0`;
- `.deb` and `.rpm` packages for amd64 and arm64 on each [GitHub release](https://github.com/mokevnin/easement/releases): `sudo apt install ./easement_<version>-1_amd64.deb` or `sudo dnf install ./easement-<version>-1.x86_64.rpm`;
- `cargo install easement`;
- prebuilt binaries for macOS, Linux and Windows, with a PowerShell installer for Windows, on each release.
## Status
Early. Go, TypeScript/JavaScript, Python and Rust are resolved by [SCIP](https://scip-code.org/) indexers, so they need the [indexers](#indexers) installed; Java, C#, Kotlin, PHP and Swift are read with tree-sitter until their indexers are wired in.
## Usage
```sh
easement init # write a starting easement.yml from the code as it is
easement check # exit 0: passed, 1: violations, 2: error
easement check --format json # machine-readable report; also sarif, github, junit
easement check --diff origin/main # only imports added in this change
easement check --watch # check again on every change
easement check --component web # report only on the files of one component (repeatable)
easement check --scope src/api # report only on files under a path (repeatable)
easement baseline # legalize current violations
easement explain src/app/a.ts # which component a file is in and what it may do
easement graph # the components as a Mermaid diagram (--format dot)
easement suggest # what the real graph says about the config
easement schema # the JSON Schema of easement.yml
easement completions zsh # shell completions: bash, zsh, fish, powershell, elvish
```
The text report is coloured on a terminal. `--color auto|always|never` overrides that, and `auto` honours `NO_COLOR` and `CLICOLOR_FORCE`; the structured formats are never coloured. To install completions for zsh, write the script to a directory on your `fpath`: `easement completions zsh > ~/.zfunc/_easement`.
`easement suggest` reads the real graph against the config and lists the `may_depend_on` entries no import uses, the imports that nothing allows, and the components whose instances never import each other and so could be `isolated`.
`easement init` finds the components in the layout of the project (the subdirectories of `internal/`, `src/`, `app/`, … or the top-level directories) and allows every dependency it finds between them. The first `easement check` passes; remove the dependencies that should not exist, and add `because:` reasons.
`easement.yml` lives in the project root; all paths are relative to it.
```yaml
version: 1
components:
handler: { in: internal/handlers }
service: { in: "internal/services/**" }
repository: { in: "internal/domain/*/repository" }
model: { in: internal/models }
common: [model]
rules:
handler: { may_depend_on: [service] }
service:
may_depend_on: [repository]
because: services never talk HTTP
exclude: ["**/*_test.go"]
```
- **components**: an `in` pattern (a glob or a list of globs) names a module, whether it is a directory or a file: `src/app/cli` covers the `cli/` directory with everything below it and a file `cli.py`. `*` stays within one directory, `**` crosses directories. When several components match a file, the one with the higher `priority` wins (default 0), then the longest pattern, so a single file can be carved out of a larger component. `except` lists patterns a component gives up: its files matching them belong to the next component that matches, if any.
- **rules**: an allow-list. A component may depend on itself, on `common` components and on what `may_depend_on` lists — nothing else. `because` is printed with every violation of the rule, so the reader (or an agent) learns where the code should go instead.
- Files outside every component are not checked, unless `strict: true` turns them into `orphan` violations. External modules are checked only where a rule says so, see [External modules](#external-modules).
- **exclude**: globs to skip, for the whole project. `.gitignore` is honoured and `node_modules` is always skipped. Excluded files are not checked at all. To hold tests to rules of their own, see [Tests](#tests).
```text
$ easement check
internal/handlers/books.go:6: handler -> repository is not allowed (imports example.com/shop/internal/repository) [dependency]
easement failed: 1 violation(s), 0 stale, 0 legalized; 5 files, 6 internal deps
```
## Rules
Every violation carries a rule id, used in the JSON report, the baseline and suppressions.
| Rule | Fails when |
|---|---|
| `dependency` | a component imports one that its `may_depend_on` does not list |
| `privacy` | a component imports a path of another component outside that component's `public` API |
| `cycle` | components covered by `no_cycles` depend on each other in a cycle |
| `external` | a component uses an external module its rule does not allow |
| `metric` | a component exceeds `max_fan_out` or `max_instability` |
| `orphan` | with `strict: true`, a checked file belongs to no component |
| `isolation` | an instance of an `isolated` component imports another instance |
| `required` | a directory of a component lacks an import, a file or a directive its rule requires |
| `file` | a component holds a file its `forbid_file` rule forbids |
| `symbol` | a component uses a name its `forbid_symbol` rule forbids, or one outside the `public_symbols` of another component |
| `suppression-reason` | an inline suppression has no reason |
| `unused-suppression` | an inline suppression matches no violation, or names a rule that cannot be suppressed (`dependency`, `privacy`, `external`, `isolation` and `symbol` can be) |
### Public API
```yaml
components:
billing:
in: src/billing
public: [src/billing/index, src/billing/api]
because: billing internals change without notice
```
Other components may import only the public paths (`src/billing/index.ts`, anything under `src/billing/api`); code inside `billing` reaches its own internals freely. A component without `public` is open.
### Instances of one component
```yaml
components:
pages:
in: "src/pages/*"
isolated: true
because: pages ship as separate bundles
```
Each directory that `src/pages/*` matches is an instance, and instances of an `isolated` component must not import each other: `src/pages/contacts` cannot import `src/pages/segments`. A file `contacts.tsx` and a directory `contacts/` are the same instance. Every `in` pattern of an isolated component needs a `*` to tell the instances apart, and no `**`. Violations are the `isolation` rule and can be suppressed inline; `because` of the component is printed with them.
### Who may import a component
```yaml
components:
ee:
in: internal/ee
allow_importers: [wiring]
because: ee is licensed separately
```
Only the listed components (and `ee` itself) may import `ee`, even when `common` or `layers` would let everyone in. This is the other side of `may_depend_on`: write it where the rule is about the one being imported. The violation reads `pages -> ee: ee may be imported only from wiring`.
### Layers and forbidden dependencies
```yaml
layers: [handler, service, repository] # top to bottom
rules:
handler:
must_not_depend_on: [repository]
because: handlers go through services
```
A layer may depend on every layer below it and never on one above. `must_not_depend_on` wins over everything that would allow the dependency: `may_depend_on`, `common` and `layers`. Its violations read `handler -> repository is forbidden`.
An item of `must_not_depend_on` and `forbid_external` can carry a reason of its own, which is printed instead of the `because` of the rule:
```yaml
rules:
core:
must_not_depend_on:
- { name: ee, because: core never knows enterprise code }
forbid_external:
- { name: moment, because: "moment is deprecated, use date-fns" }
- lodash
because: core stays dependency-free # printed for lodash
```
`may_depend_on`, `may_use_external`, `must_depend_on`, `must_use_external`, `requires_file`, `forbid_file`, `requires_directive` and `forbid_symbol` take the same items. For the allow-lists the reason says why the dependency is allowed and is shown by `easement explain`.
Quote a reason that contains a comma or a colon.
### External modules
```yaml
rules:
domain:
forbid_external: [moment, "@acme/*", net/http]
ui:
may_use_external: [react, lodash]
```
`forbid_external` lists modules the component must not use. `may_use_external` is an allow-list: everything else is a violation; without it any external module is fine. A pattern covers submodules, split at `/`, `.`, `::` and `\`: `lodash` covers `lodash/fp`, `@mantine/core` covers `@mantine/core/styles.css`, `java.util` covers `java.util.List`, `serde` covers `serde::Deserialize`. The standard library counts as external in Go, Python, Java and Rust, so an allow-list has to name it. The reason of the matching item is printed with a violation, else the `because` of the rule.
### Required imports and files
```yaml
rules:
resources:
must_depend_on: [shared]
must_use_external:
- { name: goverter, because: mappers are generated with goverter }
requires_file: [README.md]
```
The other side of `may_depend_on`: what a component must do rather than may. Every directory that holds checked files of the component is a unit, and some file in the unit has to import each listed component and external module (a pattern covers submodules, as in `forbid_external`) and the directory has to contain each listed file name or glob (`*_test.go` demands a test). A unit that falls short is one `required` violation per missing item, reported at the first file of the directory. With `src/api/*/resources` as the component, each `resources` directory is checked on its own. The rule cannot be suppressed inline; use the baseline for old debt.
### Files and directives
```yaml
rules:
ui:
forbid_file:
- { name: "*.css", because: styles live in the design system }
resources:
requires_directive:
- { name: "goverter:converter", because: mappers are generated }
```
`forbid_file` fails on every file of the component whose name or path matches a glob (`file` violation, one per file). `requires_directive` is for dependencies that are written as comments rather than imports (`// goverter:converter`, `//go:generate`, `//go:embed`): some file in every directory of the component has to match each regular expression, like `requires_file` does for names. A directory that does not is one `required` violation per missing expression.
### Symbols
```yaml
components:
db:
in: internal/db
public_symbols: [Scoped, Tx]
because: handlers get a scoped client, never the raw one
rules:
handler:
forbid_symbol:
- { name: "db.Client", because: use db.Scoped so every query is tenant-bound }
```
`forbid_symbol` names what a component must not use, as `package.Name` or `import/path.Name`. `public_symbols` is the other side: other components may use only these names from the component's packages (`only Scoped and Tx`). Both are `symbol` violations at the line of the use and can be suppressed inline.
The indexer resolves every name to its definition, so `db.Client` is matched by what it is, not by how it is spelled: an import alias or a local variable that shadows the package name makes no difference, and a method call on a value of that type (`c.Query()`) counts as a use of `Client`. For Go the qualifier is the import path or its package name; for TypeScript it is the npm package (`lodash.debounce`) or the file without extension (`src/db/client.Client`). Symbol rules are read for the indexed languages (Go and TypeScript); in the others they say nothing.
### Tests
```yaml
tests: auto
rules:
tests:
may_depend_on: [testhelper, service]
because: tests reach the database only through testhelper
```
`tests: auto` puts the test files of every language into a component named `tests` (`*_test.go`, `*.test.*` and `*.spec.*` for TypeScript and JavaScript, `test_*.py` and `*_test.py`, `*Test.java`, `*Tests.java`, `*Test.kt`, `*Test.cs`, `*Tests.cs`, `*Test.php`, `*Tests.swift`, `__tests__/`). It beats every other component for those files. Without a `tests` rule tests may import anything, which is the same as not checking them; with one, `may_depend_on` is their allow-list. Name the component `tests` yourself and `tests: auto` refuses to run.
### Coupling limits
```yaml
rules:
core:
max_fan_out: 4 # components it depends on
max_instability: 0.7 # out / (in + out), 0 is stable and 1 is unstable
```
Both count dependencies between components, so `common` components are counted too. A violation names the limit and the components behind it.
### Strict mode
`strict: true` fails on every checked file that belongs to no component, so a new directory cannot slip past the gate unnoticed. `unowned` lists the files and directories that are allowed to belong to none:
```yaml
strict: true
unowned: [ent, cmd, tools]
```
Unlike `exclude`, files in `unowned` are still read, so components can depend on them. `exclude` hides files from the check altogether.
### Cycles
```yaml
no_cycles: true # or a list: [billing, orders, catalog]
```
A group of components that all reach each other is reported once, with the shortest cycle to break:
```text
src/billing/charge.ts:1: component dependency cycle among 3 components: billing, catalog, orders (shortest: billing -> orders -> billing) [cycle]
```
In diff mode a cycle is reported when any import inside it was added by the change.
### Suppressions
An exception for one import, in a comment of any language, always with a reason after `--`:
```ts
// easement:disable-next-line dependency -- legacy admin export, remove with #123
import { exportAll } from "../admin/export";
import { client } from "../billing/generated"; // easement:disable-line privacy -- generated client
```
A suppression without a reason does not suppress and fails as `suppression-reason`. One that no longer matches a violation fails as `unused-suppression`, so exceptions do not outlive the code they excused. Prefer the baseline for old debt; suppressions are for deliberate, reviewed exceptions.
## Reporting on a part of the project
`--component <name>` and `--scope <path>` narrow the report to the files of a component or the files under a path; given together, a file has to satisfy both. The whole project is still read, because cycles, limits and every edge need all of it, so the run is not faster, but the violations, the baseline's stale entries and the counters (`1358 files, 4183 deps` becomes the numbers of the part) are those of the part. With `--watch` the cache makes the reruns fast.
## Monorepos
All paths are relative to the directory of `easement.yml`, so a package of a monorepo gets its own config and `easement check -c packages/api/easement.yml`. Packages share rules with `extends`:
```yaml
# packages/api/easement.yml
extends: ../../easement.base.yml # a path or a list of paths, relative to this file
components:
api: { in: src }
```
`components` and `rules` merge by name, and a definition in the extending file replaces the one it extends as a whole; `common` and `exclude` are joined; any other key is replaced. Patterns in the extended file stay relative to the config being loaded.
## In CI
`--format` picks the report: `text` (default), `json`, `sarif` (GitHub Code Scanning), `github` (annotations on the changed files) and `junit` (a failed test case per violation).
The repository is a GitHub Action:
```yaml
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: mokevnin/easement@main
with:
diff: origin/main # optional: judge only what the pull request adds
```
Inputs: `version`, `config`, `working-directory`, `diff` and `format` (`github` by default). With SARIF:
```yaml
- run: easement check --format sarif > easement.sarif
- uses: github/codeql-action/upload-sarif@v3
with: { sarif_file: easement.sarif }
```
For git hooks we recommend [mise](https://mise.jdx.dev) to install `easement` and [hk](https://hk.jdx.dev) to run it:
```toml
# mise.toml
[tools]
"github:mokevnin/easement" = "latest"
hk = "latest"
```
```pkl
// hk.pkl
hooks {
["pre-push"] {
steps {
["easement"] { check = "easement check" }
}
}
}
```
Run it on `pre-push` rather than `pre-commit`: the check reads the whole project.
`easement schema` prints the JSON Schema of `easement.yml`; `easement init` adds it to the file for editors that read a `yaml-language-server` comment. `easement check --watch` runs again after every change and re-reads only the files that changed; the cache lives in memory, so every run of the command starts cold.
## Baseline: adopting on an existing project
`easement baseline` writes current violations to `easement.baseline.yml` (path configurable with `baseline:`). After that the gate is a ratchet:
- violations in the baseline are legalized;
- any new violation fails;
- a baseline entry that no longer occurs also fails, so fixed debt has to be removed from the file with `easement baseline`. The baseline can only shrink.
Entries are keyed by rule, file, target and components, not by line, so unrelated edits do not invalidate them. A cycle is keyed by its components.
## Diff mode: judging a pull request
`easement check --diff <base>` reports only violations whose import line was added or changed since the merge-base with `<base>`, including uncommitted and untracked files. Old violations elsewhere do not fail the change, so the gate can be turned on without a baseline. In CI fetch the base branch (`actions/checkout` with `fetch-depth: 0`).
The report ends with the new dependencies between components that the change brings: `app -> ui` is listed when every import behind that edge is on a changed line, so a reviewer sees the change to the graph and not only the violations. `--format github` adds it as a notice and `--format json` as `stats.new_dependencies`.
The baseline still applies, and stale entries are still reported. A rule change in `easement.yml` does not touch the importing lines, so it shows up only in a full `easement check`; run both on pull requests if the config changes often.
## Languages
| Language | Extracts | Resolves |
|---|---|---|
| Go | everything `scip-go` resolves | per `go.mod`, as the Go toolchain does |
| TypeScript / JavaScript | everything `scip-typescript` resolves: `import`, `export … from`, `import()`, `typeof import()`, `require()` in JavaScript files | the TypeScript compiler's own rules: `tsconfig` `paths`, package `exports`, workspaces, `.js` → `.ts` |
| Python | everything `scip-python` resolves | the interpreter's rules, as `pyright` sees them: absolute and relative imports, packages, the installed environment |
| Java | `import`, `import static`, `import ….*` | classes indexed by their `package` declaration, so any source layout and multi-module builds work without configuration |
| Rust | everything `rust-analyzer scip` resolves | the crate graph from `cargo metadata`: `crate::`, `self::`, `super::`, workspace members, `mod x;` |
| C# | `using`, `using static`, `using Alias =`, `global using` | namespaces indexed by their `namespace` declarations: a namespace is the directory of the first file that declares it, a type is `Type.cs` next to it |
| Kotlin | `import`, `import … as`, `import ….*` | top-level declarations indexed by the `package` of their file, like Java; a file may hold several classes |
| PHP | `use`, `use function`, `use const`, group `use`, `require`/`include` of a literal | PSR-4 maps of every `composer.json`; a function or constant points at the directory of its namespace |
| Swift | `import` | modules in the SwiftPM layout: `Sources/<Module>` next to a `Package.swift` |
Go, TypeScript, Python and Rust come from a SCIP index, which is exact but has its own limits: only files that a `tsconfig.json` includes are indexed, and easement says how many source files no index covered (`N files not covered by an indexer`); `require()` in a `.ts` file is invisible unless `@types/node` is installed (JavaScript files are fine); a violation names the target file (`imports src/db/d.ts`) rather than the specifier as written; `vi.mock('./x')` and similar string arguments are not imports to the compiler, so they are not seen. Imports computed at run time are not reported for these languages. In Python third-party modules have to be installed in the environment the indexer sees, or their imports are not seen (there is no check for that yet, unlike `node_modules`), and a module reference is matched to its file by the end of its dotted name, so an import that two modules could satisfy is skipped. In Rust the dependency of a line is the deepest module it names, `std`, `core` and `alloc` all count as `std`, and `rust-analyzer` must be installed (`rustup component add rust-analyzer`). `scip-python` 0.6.8 crashes on Windows (`new RegExp(path.sep, 'g')` in its own code), so on Windows easement stops with an error when there are Python files; add them to `exclude` to check the rest, until the indexer is fixed.
Known limits of the languages that tree-sitter reads: references by fully qualified name without an import (Java, C#, Kotlin, PHP) are not seen. Imports whose target is computed at run time (`Class.forName(name)`) cannot be checked; the report counts them (`N dynamic imports not analysed`) and `--format json` lists them in `stats.dynamic`. A C# namespace that spans several components resolves to the first of its directories, so keep a namespace in one component. Swift modules declared with a custom `path:` in `Package.swift` are not found.
Adding a language to the indexed set means naming its indexer and the marker file it runs in (`src/indexer.rs`) and mapping its symbols to module names (`src/scip.rs`). A language that has no indexer can still be read with a tree-sitter adapter (`src/lang/mod.rs`): extract imports from a file, resolve a specifier to a project path or an external module. Rules, baseline and reports are language-agnostic.
### Indexers
| Language | Indexer | Needs |
|---|---|---|
| Go | [`scip-go`](https://github.com/scip-code/scip-go) | a `go.mod`; the Go toolchain and the module dependencies |
| TypeScript, JavaScript | [`scip-typescript`](https://github.com/sourcegraph/scip-typescript) | a `tsconfig.json` (with `allowJs` for JavaScript); `npm install` (or pnpm, yarn) done |
| Python | [`scip-python`](https://github.com/sourcegraph/scip-python) | Python and Node; the dependencies installed in the environment; **not Windows** (see below) |
| Rust | `rust-analyzer scip` | a `Cargo.toml` (the outermost one holds the workspace); `rustup component add rust-analyzer` |
```sh
mise use -g go:github.com/scip-code/scip-go/cmd/scip-go npm:@sourcegraph/scip-typescript npm:@sourcegraph/scip-python
```
`easement check` finds the `go.mod`, `tsconfig.json` and `Cargo.toml` files (Python projects: `pyproject.toml`, `setup.py`, `setup.cfg`, `requirements.txt`, or else the project root), runs the indexer in each of those directories and reads the result. A missing indexer, a failed run (add a directory that is not part of the project to `exclude`), or a `package.json` with dependencies but no `node_modules` is an error (exit code 2), never a quiet gap; source files that no `go.mod`, `tsconfig.json` or `Cargo.toml` covers are counted in the report as `files not covered by an indexer`: without installed packages the indexer cannot see third-party modules, so `forbid_external` would silently pass.
Languages whose dependencies are not visible from imports (Ruby, Elixir) are out of scope.
## How it works
1. Walk the project. For Go and TypeScript run the SCIP indexer and read the index; for the other languages parse each file with tree-sitter and collect imports.
2. Turn every reference to a module into a dependency on a file inside the project, or on an external module.
3. Map both ends to components and check each edge against the rules.
4. Compare violations with the baseline and report.
## Comparison with other tools
Most architecture checkers are tied to one language. `easement` is not a replacement for them where they go deeper; it is for projects that want one model across several languages.
| Tool | Languages | Level of analysis | Rules are written as |
| --- | --- | --- | --- |
| `easement` | Go, TypeScript/JavaScript, Python, Java, Rust, C#, Kotlin, PHP, Swift | imports between files and packages | one YAML file |
| [ArchUnit](https://www.archunit.org/) | Java (and other JVM languages through bytecode) | classes, methods, annotations, inheritance | JUnit tests in code |
| [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) | JavaScript, TypeScript | imports between modules | JS or JSON config |
| [import-linter](https://github.com/seddonym/import-linter) | Python | imports between modules | INI or TOML contracts |
| [Deptrac](https://github.com/deptrac/deptrac) | PHP | classes, collected into layers | YAML |
| [arch-go](https://github.com/arch-go/arch-go) | Go | packages, functions, naming | YAML |
| [depguard](https://github.com/OpenPeeDeeP/depguard) | Go | import allow and deny lists | `golangci-lint` config |
Where `easement` differs:
- **One config, one baseline, one report.** A repository with a Go backend and a TypeScript frontend gets the same component model, the same suppressions and the same CI output (`sarif`, `github`, `junit`) for both.
- **The compiler's view, through SCIP.** Go, TypeScript, Python and Rust are resolved by their SCIP indexers, so aliases, `tsconfig` paths and re-exports are what the compiler sees; for the other languages files are read with tree-sitter and nothing has to build. The price of the indexers is that dependencies have to be installed, which ArchUnit, working on compiled classes, also asks for.
- **Adoption and review features built in.** A baseline for existing violations, `--diff` to judge only what a pull request adds, `--scope` for a part of the project, and `extends` for shared policy in a monorepo.
- **One static binary.** No runtime to install in CI.
Where the others are stronger:
- **Depth.** `easement` sees imports and, for Go, the names used through them, but it does not resolve types. Rules about classes, methods, annotations, naming or call chains (ArchUnit, arch-go) are out of its reach.
- **Resolution.** A tool built for one ecosystem knows its build system better than a general adapter does: dependency-cruiser and its TypeScript options, import-linter and Python packaging, ArchUnit and the classpath.
- **Maturity.** The tools above have years of use behind them. `easement` is early.
Using both is reasonable: keep a language-specific tool for the deep rules of one codebase and let `easement` hold the boundaries between components and languages.
## Inspired by
`easement` builds on ideas from these tools, each of which covers one language or ecosystem:
- [ArchUnit](https://www.archunit.org/): architecture rules as tests for Java.
- [dependency-cruiser](https://github.com/sverweij/dependency-cruiser): dependency rules for JavaScript and TypeScript.
- [import-linter](https://github.com/seddonym/import-linter): import contracts between Python modules.
- [Deptrac](https://github.com/deptrac/deptrac): layers and allowed dependencies for PHP.
- [arch-go](https://github.com/arch-go/arch-go): architecture checks for Go.
- [depguard](https://github.com/OpenPeeDeeP/depguard): import allow and deny lists for Go.
`easement` puts one component model, one config and one baseline over all of them.
## Development
Tools are pinned in `mise.toml`: `mise install`, `mise run setup` for the git hooks, then `mise run check` (every lint, the same set CI runs) and `cargo test`. Commits follow Conventional Commits; releases are cut by merging the release-please pull request.
## License
MIT