Archaven

Put your Rust module dependency rules in tests.

Archaven scans Rust source files, finds dependencies between module paths, checks them against your rules, and returns printable violations. Use it when a project has boundaries that should stay true over time: domain code should not import infrastructure, HTTP handlers should not reach straight into the database, or one business module should not depend on another module's internals.

Start with one rule:

use archaven::{Access, Archaven, Rule};

#[test]
fn domain_does_not_depend_on_infrastructure() {
    let violations = Archaven::new()
        .rule(
            Rule::new()
                .named("domain purity")
                .deny(
                    Access::from("app::**::domain::**")
                        .to("app::**::infrastructure::**")
                        .because("domain code must not depend on infrastructure"),
                ),
        )
        .check("./src")
        .unwrap();

    violations.assert_empty();
}

That test fails when Archaven finds a dependency like:

app::orders::domain::order -> app::orders::infrastructure::database

What Archaven Checks

Archaven works with Rust module paths such as:

app::sales::orders::domain::order
app::sales::orders::infrastructure::adapter::billing_client
app::billing::invoices::application::command::issue_invoice

For each dependency found in the source tree, Archaven asks:

source path -> target path

Then every configured Rule decides whether that dependency is allowed. A rule can describe boundaries between scopes, dependencies inside one scope, or a global source-to-target policy.

Installation

Add Archaven as a dev dependency:

[dev-dependencies]
archaven = "1.0.0"

Simple Examples

Ban one direction globally:

Rule::new()
    .named("domain purity")
    .deny(
        Access::from("app::**::domain::**")
            .to("app::**::infrastructure::**")
            .because("domain code must not depend on infrastructure"),
    )

Keep handlers out of persistence details:

Rule::new()
    .named("handlers use application services")
    .deny(
        Access::from("app::**::http::**")
            .to("app::**::database::**")
            .because("HTTP handlers should go through application services"),
    )

Allow only a narrow dependency shape inside each feature:

Rule::within("app::*")
    .named("feature internals")
    .deny_all()
    .allow(Access::from("http::**").to("application::**"))
    .allow(Access::from("application::**").to("domain::**"))
    .allow(Access::from("infrastructure::**").to("application::**"))
    .allow(Access::from("infrastructure::**").to("domain::**"))
    .because("feature dependencies should point through application and domain code")

Keep selected directories limited to Rust module root files:

Rule::directories("app::*")
    .named("module roots")
    .allow_only_module_roots()

These examples are intentionally plain. Archaven does not require you to adopt a specific architecture style; it checks source-to-target module path policies that fit your codebase.

Similar Tools

Archaven follows the same general idea as ArchUnit in the Java ecosystem: architecture rules should be executable tests, not comments in a diagram. ArchUnit works over Java classes, packages, and bytecode-level concepts. Archaven keeps the same testing habit, but applies it to Rust source files and Rust module paths.

It is also close in spirit to Deptrac in the PHP ecosystem. Deptrac groups code into layers and checks which layers may depend on which other layers. Archaven does not use a separate YAML layer model; rules are written directly in Rust tests with Rule, Access, and module path patterns.

The goal is intentionally small: make dependency boundaries visible in normal Rust test suites and CI.

More Boundary Examples

Keep one feature from reaching into another feature's internals:

Rule::between("app::*")
    .named("feature boundaries")
    .deny_all()
    .allow(
        Access::from("**")
            .to("api::**")
            .because("features expose only their public API modules"),
    )

Keep plugin code from depending on the application shell:

Rule::new()
    .named("plugins stay independent")
    .deny(
        Access::from("plugins::**")
            .to("app::shell::**")
            .because("plugins should not depend on application shell internals"),
    )

Keep tests and support code from leaking into production modules:

Rule::new()
    .named("production does not use test support")
    .deny(
        Access::from("app::**")
            .to("test_support::**")
            .because("test helpers must stay out of production code"),
    )

Protect a shared kernel from depending on product-specific modules:

Rule::new()
    .named("shared kernel is product-neutral")
    .deny(
        Access::from("app::shared::**")
            .to_any(["app::billing::**", "app::sales::**"])
            .because("shared code should not depend on product-specific modules"),
    )

Example Project

The repository includes a small runnable example in examples/basic_architecture_test.rs. It scans the sample source tree under examples/sample_app/src and demonstrates the simple rules from this README.

Run it with:

cargo test --example basic_architecture_test

The example is deliberately small. It is meant to show how an architecture test looks in a normal Rust project before you move on to larger modular-monolith rules.

Who This Is For

Archaven is most useful once a Rust codebase has boundaries that people can name: features, bounded contexts, application/domain/infrastructure folders, plugins, adapters, or shared modules. It is a good fit for teams that already review module dependencies by convention and want those conventions to run in CI.

It is probably too much for tiny crates with only a few modules. In that case, regular Rust visibility, module organization, and code review may be enough.

Core Concepts

Archaven

Archaven is the checker. Add one or more rules, call check, and assert that the returned Violations collection is empty.

let violations = Archaven::new()
    .rule(/* rule */)
    .check("./src")
    .unwrap();

violations.assert_empty();

check returns Result<Violations, ArchavenError>:

• Err(...) means scanning, parsing, or rule compilation failed.
• Ok(violations) means analysis completed and the returned list contains all architectural violations.

Rule::between

Rule::between(pattern) checks dependencies between different instances matched by the same scope pattern.

Rule::between("app::*")

With paths like app::sales::... and app::billing::..., this checks cross-context dependencies from sales to billing and from billing to sales. Dependencies inside app::sales are ignored by this rule.

Example:

Rule::between("app::*")
    .named("bounded contexts")
    .deny_all()
    .allow(
        Access::from("*::infrastructure::adapter::**")
            .to_any([
                "*::application::command::**",
                "*::application::query::**",
            ]),
    )

The from and to patterns are relative to the matched source and target scopes. For a dependency from app::sales to app::billing, the rule above allows:

app::sales::*::infrastructure::adapter::**
    ->
app::billing::*::application::command::**
app::billing::*::application::query::**

Rule::within

Rule::within(pattern) checks dependencies inside the same matched scope.

Rule::within("app::*::*")

With a scope like app::sales::orders, this checks dependencies from one path under orders to another path under orders. Dependencies from orders to invoices are ignored by this rule.

Example:

Rule::within("app::*::*")
    .named("module internals")
    .deny_all()
    .allow(Access::from("application::**").to("domain::**"))
    .allow(Access::from("infrastructure::**").to("application::**"))
    .allow(Access::from("infrastructure::**").to("domain::**"))
    .allow(Access::from("ui::**").to("application::**"))

If a file assembles a module and should not be evaluated by that rule, ignore it with a file glob:

Rule::within("app::*::*")
    .named("module internals")
    .deny_all()
    .ignore_files(["**/mod.rs"])
    .allow(Access::from("application::**").to("domain::**"))

ignore_files is per-rule. Dependencies discovered in matching source files are skipped for that rule before deny, deny_all, and allow are evaluated.

Use ignore_module_roots when both Rust module root styles should be skipped:

Rule::within("app::*::*")
    .named("module internals")
    .deny_all()
    .ignore_module_roots()
    .allow(Access::from("application::**").to("domain::**"))

Module root files are mod.rs, lib.rs, and files named after a child directory, such as application.rs when an application/ directory exists.

Rule::directories

Rule::directories(pattern) checks the physical Rust files directly inside directories whose module path matches the pattern.

Rule::directories("app::*")
    .named("module roots")
    .allow_only_module_roots()

Directory rules intentionally support one or more * segments and do not support **. The full pattern chooses the directory level to check, so the last * is the checked level. For example, app::* checks directories such as app::orders and app::billing, while app::*::* checks directories such as app::sales::orders.

allow_only_module_roots allows only these .rs files in each matching directory:

• mod.rs
• lib.rs
• <child-directory>.rs

For example, this layout is allowed:

src/app/orders/
  mod.rs
  application.rs
  domain.rs
  application/
    command.rs
  domain/
    order.rs

but src/app/orders/helper.rs is reported unless an orders/helper/ directory also exists.

Multiple Rules

Rules are independent and can be combined in one checker:

let violations = Archaven::new()
    .rule(
        Rule::directories("app::*")
            .named("module roots")
            .allow_only_module_roots(),
    )
    .rule(
        Rule::between("app::*")
            .named("bounded contexts")
            .deny_all()
            .allow(
                Access::from("*::infrastructure::adapter::**")
                    .to_any([
                        "*::application::command::**",
                        "*::application::query::**",
                    ]),
            ),
    )
    .rule(
        Rule::within("app::*::*")
            .named("module internals")
            .deny_all()
            .ignore_module_roots()
            .allow(Access::from("application::**").to("domain::**"))
            .allow(Access::from("infrastructure::**").to("application::**"))
            .allow(Access::from("infrastructure::**").to("domain::**"))
            .allow(Access::from("ui::**").to("application::**")),
    )
    .check("./src")?;

violations.assert_empty();

This can model layered, hexagonal, vertical-slice, plugin, or custom dependency styles without adding architecture-specific types to the public API.

Rule::new

Rule::new() checks absolute source and target patterns.

Rule::new()
    .named("domain purity")
    .deny(
        Access::from("app::**::domain::**")
            .to("app::**::infrastructure::**")
            .because("domain code must not depend on infrastructure"),
    )

Use this when a rule is not scoped by between or within.

Path Patterns

Archaven matches module paths by :: segments.

*  = exactly one segment
** = one or more segments

Examples:

app::*::anything       matches app::orders::anything
app::*::anything       does not match app::orders::nested::anything
app::**::anything      matches app::orders::nested::anything
app::**::anything      does not match app::anything
app::**                matches app::orders and app::orders::domain
app::**                does not match app

Patterns are intentionally segment-based. app::*::domain is different from app::**::domain, and ** never means "zero segments".

Larger Modular Monolith Example

The same primitives scale to a modular monolith. Start by describing the module paths that matter, then decide which source-to-target dependencies are allowed.

Given this source layout:

src/app/sales/orders/domain/order.rs
src/app/sales/orders/application/command/create_order.rs
src/app/sales/orders/infrastructure/adapter/billing_client.rs
src/app/sales/orders/ui/http_controller.rs
src/app/billing/invoices/application/command/issue_invoice.rs
src/app/billing/invoices/application/query/get_invoice.rs

Check cross-context communication:

use archaven::{Access, Archaven, Rule};

#[test]
fn bounded_contexts_are_isolated() {
    let violations = Archaven::new()
        .rule(
            Rule::between("app::*")
                .named("bounded contexts")
                .deny_all()
                .allow(
                    Access::from("*::infrastructure::adapter::**")
                        .to_any([
                            "*::application::command::**",
                            "*::application::query::**",
                        ])
                        .because("cross-context calls go through adapters and command/query APIs"),
                ),
        )
        .check("./src")
        .unwrap();

    assert!(violations.is_empty(), "{violations}");
}

Check dependencies inside each module:

use archaven::{Access, Archaven, Rule};

#[test]
fn module_internal_dependencies_are_valid() {
    let violations = Archaven::new()
        .rule(
            Rule::within("app::*::*")
                .named("module internals")
                .deny_all()
                .allow(Access::from("application::**").to("domain::**"))
                .allow(Access::from("infrastructure::**").to("application::**"))
                .allow(Access::from("infrastructure::**").to("domain::**"))
                .allow(Access::from("ui::**").to("application::**"))
                .because("dependencies inside a module must point inward"),
        )
        .check("./src")
        .unwrap();

    assert!(violations.is_empty(), "{violations}");
}

Violation Output

Violations implements Display, so it can be used directly in assertions:

assert!(violations.is_empty(), "{violations}");

For test assertions, assert_empty panics with the formatted violation list and reports the panic at the assertion call site:

violations.assert_empty();

You can also format violations yourself:

for violation in &violations {
    println!(
        "{}: {} -> {}",
        violation.location().file().display(),
        violation.source(),
        violation.target(),
    );
}

A violation contains:

• rule name
• reason
• source module path
• target module path for dependency violations
• file path
• line and column when available

How Scanning Works

Archaven derives source module paths from Rust file paths under the directory passed to check.

For example:

src/app/sales/orders/domain/order.rs

becomes:

app::sales::orders::domain::order

The scanner parses Rust files with syn and records dependencies from:

• use crate::...
• crate::...
• self::...
• super::...
• local root paths such as app::...

Use Rule::ignore_module_roots() when module root files intentionally wire internals that the rule should not evaluate. Use Rule::directories("app::*").allow_only_module_roots() when matching directories should contain only Rust module root files.

This keeps Archaven fast and usable from regular tests. It also means Archaven is a source-level checker, not a full Rust compiler front-end. Macro generated paths, complex re-exports, trait dispatch, and every possible aliasing pattern may require explicit paths in code or future scanner improvements.

Custom Rule Sets

The built-in Rule type is enough for many projects, but Archaven also exposes RuleSet for custom policies. Custom rules can inspect discovered dependencies and source directories through DependencyGraph.

use archaven::{ArchavenError, DependencyGraph, RuleSet, Violations};

struct MyRule;

impl RuleSet for MyRule {
    fn check(&self, graph: &DependencyGraph) -> Result<Violations, ArchavenError> {
        for dependency in graph.dependencies() {
            let _ = (dependency.source(), dependency.target());
        }

        for directory in graph.directories() {
            let _ = (
                directory.path(),
                directory.module(),
                directory.files(),
                directory.child_directories(),
            );
        }

        Ok(Violations::new())
    }
}

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

at your option.