Workspace.Checks.EnforceBoundaries (Workspace v0.2.0)

View Source

Enforces boundaries between projects.

Workspace provides a generic mechanism in order to express constraints on project dependencies using the defined tags. Using this check you can specify rules about what internal dependencies are allowed or forbidden.

Each configured check must specify the :tag for which it applies and either a set of tags that are allowed to depend on or a set of tags that are forbidden.

Common use cases

When you start paritioning your codebase into multiple well-defined cohesive packages, even for small projects, dozens of packages will be created. If all of them can depend on each other freely, the workspace will become umanageable and you will end up with a big ball of mud.

One of the main purposes of the workspace is to help you split your codebase into independent, cohesive and reusable packages. As a side effect you end up with a clean architecture.

The main purpose of this rule is to enforce the clean architecture and explicitly declare the allowed cross-workspace dependencies.

By properly tagging your projects by the architectural layer they belong to, you can apply rules of the form:

  • :shared libraries can only depend on :shared libraries
  • applications can only depend on the business logic layer
  • applications are not allowed to depend on data layer packages directly

Configuration

  • :tag - Required. Tag that source project must contain for the rule to be applicable

  • :allowed_tags - The source project is allowed to depend on projects that contain at least one of these tags. If not set all dependencies are allowed. The default value is [:*].

  • :forbidden_tags - The source project is forbidden to depend on projects that contain at least one of these tags. If not set all dependencies are allowed. The default value is [].

Example

You can enforce allowed dependencies for projects with specific tags. For example below we enforce that all projects tagged with {:scope, :shared} can only depend on internal projects with the {:scope, :shared} tag.

[
  module: Workspace.Checks.EnforceBoundaries,
  description: "shared projects can only depend on shared",
  opts: [
    tag: {:scope, :shared},
    allowed_tags: [{:scope, :shared}]
  ]
]

Additionally we can forbid specific dependencies, for example:

[
  module: Workspace.Checks.EnforceBoundaries,
  description: "public packages cannot depend on admin packages",
  opts: [
    tag: :public,
    forbidden_tags: [:admin]
  ]
]

By setting multiple boundaries rules you implicitly define your architecture and enforce proper dependencies, making the project more maintainable.

Combination with other checks

It is advised to combine this check with the Workspace.Checks.ValidateTags and Workspace.Checks.RequiredScopeTag checks in order to:

  • ensure that all project tags are valid
  • ensure that all projects are properly scope tagged across the dimensions you have decided to tag upon (scope, team, layer etc)
  • boundaries are enforced between the various projects