Introducing a layering-checker plugin for Scala

Introducing a layering-checker plugin for Scala

A wartremover plugin that makes the Scala compiler enforce your layered architecture

When working in applications with a layered architecture, we define each layer’s responsibilities and constraints, usually enforced during code review. What if the compiler helped us instead?

This matters even more when coding with AI. An agent will happily take the shortest path to completion even if that violates the architecture, and it will keep doing it no matter how many times you point it out. A compiler error is feedback it can’t ignore, and unlike reviewer-gates, it costs seconds, not minutes.

A simple way to do this is to create an sbt module per layer (let me tell you, it’s annoying). Still, it can’t prevent a module from using its transitive dependencies. Imagine an app where A imports B and B imports C. Now A can use C too.

transitive-diagram

Bazel can enforce this, but you need a target per package, every dependency declared by hand, and strict deps enabled so a package can’t use what its dependencies import (also annoying).

The plugin

I published layering-warts, a wartremover plugin, and have used it for a few days in my expense-tracker Scala app. It has worked nicely so far.

Once you enable it, each sbt module declares its layers in a .wartremover-layering.conf at its base directory, like server/.wartremover-layering.conf. The wart uses the nearest file found in the compiled source’s directory or its parents (the same way git finds .git). A missing or invalid file is reported as a compiler error.

Here’s an example config:

# the packages this module owns, references to code outside them are not checked
roots = ["com.example", "controllers"]

# the longest matching package prefix decides the layer, so com.example.repositories.daos belongs to daos
layers = [
  { name = controllers,  packages = ["controllers"],                      calls = [actions, shared] }
  { name = actions,      packages = ["com.example.actions"],              calls = [repositories, shared] }
  { name = repositories, packages = ["com.example.repositories"],         calls = [daos, shared] }
  { name = daos,         packages = ["com.example.repositories.daos"],    calls = [daos, shared] }
  { name = shared,       packages = ["com.example.models"],               calls = [shared] }
]

# a class may reference a class of its own layer defined in the same file, defaults to true
allowSameFileSiblings = true

The config is cleaner as a diagram:

layering-diagram

With this config, a class in controllers can’t call repositories. Say I have this code:

package controllers

object HealthController {
  def f(r: com.example.repositories.UsersRepository): Unit = r.all().foreach(println)
}

Compilation now fails:

[error] -- Error: /expense-tracker/server/src/main/scala/controllers/HealthController.scala:18:66
[error] 18 |  def f(r: com.example.repositories.UsersRepository): Unit = r.all().foreach(println)
[error]    |                                                                ^^^^^
[error]    |[wartremover:Layering] HealthController in controllers must not call UsersRepository in repositories; controllers calls actions, shared.
[error] one error found

A layer can’t call its own classes either unless it lists itself in calls, so a controller can’t use another controller. Classes defined in the same file are the exception (allowSameFileSiblings).

For trying it, check out the repo latest docs.

It’s early, so feedback and issues are welcome.

Found a mistake or want to suggest an edit? View the source of this post on GitHub .