ad-enforcement-tool

README

ADE

ADE (Architectural Decision Enforcement) is a command-line tool for enforcing architectural decisions. Rules are written in a small DSL and stored in .rule files. ADE either compiles each rule into an executable architecture test or verifies it directly against the codebase, delegating language-specific work to plugins.

ADE is part of the ADG ecosystem. The adg enforce command tree is powered by this module.

Quick start

go install github.com/phi42/ad-enforcement-tool/ade@latest
ade plugin install fscheck --repo github.com/phi42/ad-plugin-fscheck
ade validate -i my-adr.rule
ade verify   -i my-adr.rule -p fscheck

If you are using the ADG tool, replace ade with adg enforce throughout (e.g. adg enforce validate -i my-adr.rule).

A typical rule file:

adr "0001" "Use Clean Architecture"

component "Domain" = "MyApp.Domain"
component "Infra"  = "MyApp.Infrastructure"

code "domain_isolated" {
  Domain must not depend on Infra
  severity error
}

file "tests_exist" {
  path "tests/ArchTests/" must exist
  severity error
}

A syntax-highlighting extension for .rule files is available for VS Code; install ade.vsix from the latest release or see extras/vscode/.

For a step-by-step walkthrough (install, plugins, writing a rule, compiling, running in CI) see the user guide.

Plugins

Enforcement is delegated to plugins, separate executables that receive the parsed rule IR (rule.Spec protobuf) and either generate tests (compile mode) or perform checks directly (verify mode).

Plugin	Target	Description
ad-plugin-archgo	Go	Compiles code rules into arch-go tests.
ad-plugin-netarchtest	.NET / C#	Compiles code rules into NetArchTest + NUnit tests.
ad-plugin-archunit	Java	Compiles code rules into ArchUnit tests.
ad-plugin-fscheck	Any	Executes file rules directly against the filesystem.

To author your own plugin, copy one of the starter templates in extras/plugin-templates/ (Go, C#, or Java) and follow the plugin developer guide.

If you have developed a plugin that you'd like to share, feel free to open a PR adding it to the list above.

Import ADE as a go module

The cmd package exposes the full enforcement command tree as a single *cobra.Command. Other tools can register it directly:

import adecmd "github.com/phi42/ad-enforcement-tool/cmd"

rootCmd.AddCommand(adecmd.NewEnforceCommand())

This is how ad-guidance-tool integrates the enforcement commands under adg enforce. The protobuf types used for plugin communication are also exposed as a public Go package at rule, and the DSL reference is exposed by the dsl package.

Documentation

• docs/user-guide.md: end-to-end walkthrough; install, plugins, writing a rule, compile/verify, and running in CI.
• docs/cli-reference.md: every ade command, flag, and configuration key.
• dsl/dsl-reference.md: DSL reference; every keyword, every verb phrase.
• docs/plugin-developer-guide.md: plugin protocol, protobuf schema, and how to author your own plugin.
• docs/implementation.md: internal architecture and package layout for contributors.
• extras/ci-templates/: ready-to-use CI workflow templates.
• extras/vscode/: VS Code syntax-highlighting extension for .rule files.

Examples

• ad-guidance-tool: uses ad-plugin-fscheck and ad-plugin-archgo plugins to enforce architectural decisions in a Go monorepo.
• ad-casestudy: uses ad-plugin-fscheck and ad-plugin-netarchtest plugins to enforce architectural decisions in a .NET monorepo.
• OST Cloud Application Lab: Serverless Sample Application: uses ad-plugin-fscheck, ad-plugin-netarchtest and ad-plugin-archunit plugins to enforce architectural decisions in a serverless microservice application.

License

Licensed under the Apache License, Version 2.0.