How Guarding Turns Architecture Docs into Automated Multi‑Language Tests

Overview

Guarding is an open‑source architecture‑guard tool written in Rust. It supports Java, JavaScript, Rust, Go and other languages, runs on Windows, macOS and Linux, and provides a DSL for defining architectural rules.

DSL for Rules

Rules are expressed with a concise DSL. Example snippets:

package(".")::file.len should < 200;
package(".")::file.len should > 50;
class("java.util.Map") only accessed(["com.phodal.pepper.refactor.staticclass"]);
class(implementation "BaseParser")::len = 2;
class(implementation "BaseParser")::name should not contains "Lexer";

Installation and Execution

Install via Cargo: cargo install guarding Or clone the repository:

https://github.com/inherd/guarding

Run the tool with the guarding command.

Architecture

Guarding consists of three components:

Rule parser that reads the DSL.

Multi‑language source parser built on Tree‑sitter; queries are written as S‑expressions.

Rule executor that applies parsed rules to the abstract syntax tree.

Processing flow is illustrated below:

Multi‑language Source Parsing

Tree‑sitter was selected after evaluating Antlr, Ctags and LSP because of its performance and broad language coverage (Rust, JavaScript, Python, Ruby, Haskell, etc.). Tree‑sitter produces a concrete syntax tree that can be queried with S‑expressions.

Example C++ class and its Tree‑sitter node representation:

class MyClass {
  public:
    int myNum;
    string myString;
};

translation_unit [0,0]-[6,0]
class_specifier [0,0]-[4,1]
name: type_identifier [0,0]-[13]
body: field_declaration_list [0,14]-[4,1]
access_specifier [1,2]-[1,9]

Corresponding query in S‑expression:

(class_specifier name: ((type_identifier) @class-name))

Grammar Design

Guarding uses the pest parser generator. A fragment of the grammar:

normal_rule = { rule_level ~ ("(" ~ scope ~ ")")? ~ (use_symbol ~ expression)? ~ should? ~ only? ~ operator ~ assert ~ ";"? }
rule_level = { "package" | "class" | "struct" | "function" | "file" }

Documentation and examples are located in the docs and examples directories of the repository.

Typical Usage Scenarios

Local pre‑commit checks via Git hooks.

Integration in CI pipelines for continuous architectural validation.

Future support for real‑time analysis through IDE/editor plugins.

Contribution

Contributions are welcome at:

https://github.com/inherd/guarding