From 0db122e1f2aa043a9d02dda892191e434bd653a5 Mon Sep 17 00:00:00 2001 From: Niessen Date: Tue, 18 Aug 2026 06:44:41 +0200 Subject: [PATCH 1/3] docs: align README with ArchUnitTS --- README.md | 98 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 70 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 82b1d75..b350ab3 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,22 @@ -# ArchUnitRuby +# ArchUnitRuby - Architecture Testing -Architecture testing for Ruby. Part of **ArchUnitEverything**: one recognizable testing library -for each programming language. +
-[![CI](https://github.com/LukasNiessen/ArchUnitRuby/actions/workflows/ci.yml/badge.svg)](https://github.com/LukasNiessen/ArchUnitRuby/actions/workflows/ci.yml) -[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-e4493f)](https://lukasniessen.github.io/ArchUnitRuby/) -[![Gem version](https://img.shields.io/gem/v/archunit.svg)](https://rubygems.org/gems/archunit) -[![Gem downloads](https://img.shields.io/gem/dt/archunit.svg)](https://clickgems.clickhouse.com/dashboard/archunit) -[![Ruby 3.3+](https://img.shields.io/badge/Ruby-3.3%2B-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -[![GitHub stars](https://img.shields.io/github/stars/LukasNiessen/ArchUnitRuby.svg)](https://github.com/LukasNiessen/ArchUnitRuby) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Build & tests](https://img.shields.io/github/actions/workflow/status/LukasNiessen/ArchUnitRuby/ci.yml?branch=main&label=build%20%26%20tests)](https://github.com/LukasNiessen/ArchUnitRuby/actions/workflows/ci.yml) [![GitHub stars](https://img.shields.io/github/stars/LukasNiessen/ArchUnitRuby.svg)](https://github.com/LukasNiessen/ArchUnitRuby)
+[![Gem version](https://img.shields.io/gem/v/archunit.svg)](https://rubygems.org/gems/archunit) [![Gem downloads](https://img.shields.io/gem/dt/archunit.svg)](https://clickgems.clickhouse.com/dashboard/archunit) [![Ruby 3.3+](https://img.shields.io/badge/Ruby-3.3%2B-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/) + +
+ +Enforce architecture rules in Ruby projects. Check dependency directions, detect circular +dependencies, enforce naming and location conventions, measure code quality, and generate +architecture reports as ordinary Ruby tests. + +ArchUnitRuby is part of **ArchUnitEverything**: one recognizable architecture-testing library for +each programming language. + +_Inspired by the amazing ArchUnit library, but not affiliated with ArchUnit._ + +[Setup](#-setup) · [Use Cases](#-use-cases) · [Features](#-features) · [Documentation](https://lukasniessen.github.io/ArchUnitRuby/) · [Sponsor](https://github.com/sponsors/LukasNiessen) · [Contributing](#-contributing) ArchUnitRuby turns a Ruby codebase into a dependency graph and lets you test that graph with rules that read like English: @@ -28,13 +35,13 @@ is tested on Ruby 3.3, 3.4, and 4.0 on Linux and Ruby 4.0 on Windows. Version 0. Siblings: [ArchUnitTS](https://github.com/LukasNiessen/ArchUnitTS) and [ArchUnitPython](https://github.com/LukasNiessen/ArchUnitPython). -## Documentation - The [documentation site](https://lukasniessen.github.io/ArchUnitRuby/) combines this guide with a searchable, source-generated API reference for every public module, class, and method. The same site is rebuilt in CI and deployed from `main`, so the published reference follows the repository. -## Install +## ⚡ 5 min Quickstart + +### Installation ArchUnitRuby requires Ruby 3.3 or newer. Add it to your test dependencies: @@ -62,7 +69,7 @@ current raw count and ClickGems provides the historical breakdown. RSpec and Minitest integrations are optional; ArchUnitRuby does not install either test framework for you. -## Your first rule +### Add tests Create `spec/architecture_spec.rb`: @@ -85,6 +92,21 @@ Run it like any other specification: bundle exec rspec spec/architecture_spec.rb ``` +### CI Integration + +Architecture specifications run with the rest of the test suite, so no dedicated CI integration +is required: + +```yaml +# GitHub Actions +- name: Run architecture tests + run: bundle exec rspec spec/architecture_spec.rb +``` + +## 🚐 Setup + +### Project Location + The project locator is optional. With no argument, ArchUnitRuby searches from the current directory for a `Gemfile` or gemspec. Pass a directory or either marker file when analyzing another project: @@ -93,7 +115,7 @@ ArchUnit.project_files('/workspace/my_app') ArchUnit.project_files('/workspace/my_app/Gemfile') ``` -## The fluent grammar +### Fluent Grammar Every rule is built left to right from the same small grammar: @@ -128,7 +150,9 @@ when an empty result is genuinely valid: rule.check(ArchUnit::CheckOptions.new(allow_empty_tests: true)) ``` -## Files +## 🐣 Features + +### File Rules File rules cover cycles, naming, location, internal dependencies, external modules, and custom source predicates: @@ -156,7 +180,7 @@ rule = ArchUnit.project_files.in_folder('app/services/**') ) ``` -## Layers +### Layer Dependencies Named layers express an allowlist or blocklist over groups of files: @@ -176,7 +200,7 @@ Dependencies within one layer are always allowed. Edges with an unassigned endpo Calling `may_only_depend_on_layers` without targets seals a layer; `may_not_depend_on_layers` requires at least one forbidden target. -## Slices and PlantUML +### Architecture Slices and PlantUML Slices group files by one captured path segment and preserve every concrete dependency as evidence: @@ -202,7 +226,7 @@ expect(rule).to pass The supported subset recognizes components, directed dependencies, comments, and `@startuml` / `@enduml`. Use `to_plantuml` or `export_as_plantuml(path)` to generate a diagram from the real graph. -## Dependency graph reports +### Dependency Graph Reports Graph reporting builds one immutable snapshot and renders it consistently as DOT, Mermaid, D2, CSV, JSON, or self-contained HTML: @@ -222,7 +246,7 @@ Queries include `focus_on`, `reachable_from`, and `dependents_of`. Collapse by f regular-expression replacement. Every format has an in-memory `to_` and an `export_as_(path)` terminal. -## Metrics +### Code Metrics Metric scopes select files and Ruby classes before measurement or assertion: @@ -253,7 +277,7 @@ services.count.export_as_html('reports/service-counts') The threshold vocabulary is intentionally limited to `should_be_below`, `should_be_above`, `should_be`, `should_be_below_or_equal`, `should_be_above_or_equal`, and `should_satisfy`. -## Pattern exclusions +### Pattern Exclusions Every selector accepts `except:` in the same call. A plain pattern or array uses the parent selector's context, including filenames for path and folder selectors: @@ -275,7 +299,9 @@ scope = ArchUnit.metrics.in_path( ) ``` -## Results and test frameworks +## 🐹 Use Cases + +### Results and Test Frameworks `check` returns an array of structured violations. Architecture disagreement is data, not an exception: @@ -296,7 +322,7 @@ ArchUnit.assert_passes(rule) # Framework-neutral `ArchUnit.format_violations` and `ResultFactory` provide stable human-readable output. All violations retain the concrete dependency, file, layer, slice, or metric evidence that caused them. -## Per-check logging +## 📝 Debug Logging & Configuration Logging is off by default and belongs to one check; there is no process-global configuration: @@ -314,7 +340,9 @@ Levels are `debug`, `info`, `warn`, and `error`. The fixed events cover check st violations, and metric evidence. `io:` defaults to `$stderr`, accepts any writable stream, and may be `nil`. File output creates missing directories and writes timestamped `archunit-*.log` files. -## What ArchUnitRuby extracts +## 🕵️ Technical Deep Dive + +### What ArchUnitRuby Extracts ArchUnitRuby uses Prism and statically recognizes: @@ -358,7 +386,7 @@ Load-path choices affect graph caching. Equivalent normalized choices reuse a ca different set builds a separate graph. Use `clear_cache: true` after changing files or gemspec layout within one process. -## Executable examples +## 🐲 Example Repository The [ArchUnitRuby RAG test repository](https://github.com/TristanKruse/ArchUnitRuby-TestRepo-RAG) is a small layered retrieval-augmented-generation application with two deliberate architecture @@ -369,7 +397,7 @@ ArchUnitRuby also dogfoods itself in `spec/architecture_spec.rb`: `common` is is modules cannot depend on one another, implementation files cannot depend on the public surface, and the complete library graph must remain cycle-free. -## Development +## 🦊 Contributing ```bash git clone https://github.com/LukasNiessen/ArchUnitRuby.git @@ -399,13 +427,27 @@ for corpus controls, JSON output, and CI limits. The implementation conventions and intended dependency directions live in [`AGENTS.md`](AGENTS.md). -## Current limitations +## 📅 Plans and Current Limitations - Ruby constants are not modeled as a separate graph. Files are the primary dependency vocabulary. - Dynamic `require`, `autoload`, and `load` arguments cannot be resolved statically. - PlantUML support is a deliberately small component-diagram subset, not a complete UML parser. - The API is still pre-release and may change before the first stable gem version. -## License +## 💟 Community + +Questions and feature ideas are welcome in [GitHub Issues](https://github.com/LukasNiessen/ArchUnitRuby/issues). + +### Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=LukasNiessen/ArchUnitRuby&type=Date)](https://star-history.com/#LukasNiessen/ArchUnitRuby&Date) + +## 📄 License [MIT](LICENSE) + +
+ +[Go back to the top](#top) + +
From 64266f28bb274bdbb0459987ccb066697f2ea25e Mon Sep 17 00:00:00 2001 From: Niessen Date: Tue, 18 Aug 2026 07:27:44 +0200 Subject: [PATCH 2/3] docs: remove version badge and family label --- README.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/README.md b/README.md index b350ab3..d3f5180 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Build & tests](https://img.shields.io/github/actions/workflow/status/LukasNiessen/ArchUnitRuby/ci.yml?branch=main&label=build%20%26%20tests)](https://github.com/LukasNiessen/ArchUnitRuby/actions/workflows/ci.yml) [![GitHub stars](https://img.shields.io/github/stars/LukasNiessen/ArchUnitRuby.svg)](https://github.com/LukasNiessen/ArchUnitRuby)
-[![Gem version](https://img.shields.io/gem/v/archunit.svg)](https://rubygems.org/gems/archunit) [![Gem downloads](https://img.shields.io/gem/dt/archunit.svg)](https://clickgems.clickhouse.com/dashboard/archunit) [![Ruby 3.3+](https://img.shields.io/badge/Ruby-3.3%2B-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/) +[![Gem downloads](https://img.shields.io/gem/dt/archunit.svg)](https://clickgems.clickhouse.com/dashboard/archunit) [![Ruby 3.3+](https://img.shields.io/badge/Ruby-3.3%2B-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
@@ -11,9 +11,6 @@ Enforce architecture rules in Ruby projects. Check dependency directions, detect dependencies, enforce naming and location conventions, measure code quality, and generate architecture reports as ordinary Ruby tests. -ArchUnitRuby is part of **ArchUnitEverything**: one recognizable architecture-testing library for -each programming language. - _Inspired by the amazing ArchUnit library, but not affiliated with ArchUnit._ [Setup](#-setup) · [Use Cases](#-use-cases) · [Features](#-features) · [Documentation](https://lukasniessen.github.io/ArchUnitRuby/) · [Sponsor](https://github.com/sponsors/LukasNiessen) · [Contributing](#-contributing) From f5afe7f07360a95339959098a02267c266d6d8f6 Mon Sep 17 00:00:00 2001 From: Niessen Date: Tue, 18 Aug 2026 08:07:45 +0200 Subject: [PATCH 3/3] docs: credit project maintainers --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index d3f5180..a7a220e 100644 --- a/README.md +++ b/README.md @@ -433,6 +433,15 @@ The implementation conventions and intended dependency directions live in [`AGEN ## 💟 Community +### Maintainers + +- **[Tristan Kruse](https://github.com/TristanKruse)** — Tech Lead & Maintainer +- **[Lukas Niessen](https://github.com/LukasNiessen)** — Maintainer + +### Contributors + +See everyone who has contributed on the [GitHub contributors page](https://github.com/LukasNiessen/ArchUnitRuby/graphs/contributors). + Questions and feature ideas are welcome in [GitHub Issues](https://github.com/LukasNiessen/ArchUnitRuby/issues). ### Star History