archspec 1.0.1 → 1.1.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07a83d8f3402826cb160272cea2739a3ad9542bc7d35fd6590544c39fcf7c597
-  data.tar.gz: 5d087f15b56575032c262a7f7e097270b4bad4bb09acd066003bfbbc338900eb
+  metadata.gz: 3d1149a18e2ffb69c03d15e95ca539d3c42c1fda406376069313b9e07365a1b1
+  data.tar.gz: 290b05eb65ad246ebd1d81a025abe013a3150d5afc7e0bb6cb834dae3f64a429
 SHA512:
-  metadata.gz: c1ee035facb38cb68d9bde3b469f6fdd0e98bf434437254c3f9123cb7eb4ca9cfb2206ce0e4ad01fd25179054cc91e0c821de729026a08e69bb2cfb99092c084
-  data.tar.gz: de5d78b6d8e71e26d2a9cc67e6ad0854f532b876bd7e885536e867ddf27d5fb1a324b3bdb79e63f4d880c0194de036e94c2ae77d10219bedd19f6d84008e0d6b
+  metadata.gz: 2e02c22290a4616b60edb2a5fd97ba991237e6da3b2fe495a5fde7802ac520fa432c821a9eb895c98333ce1acb170aff476ffa016c1de924199a9b47463d3994
+  data.tar.gz: 99d07ea4daff657b1823a81beff200f2139a3646c1ef7ad1bb3f041f13a9a03d7bd39a8b5b4b0176bda00ca13506043a691a1c93f65f54eed33a17c129e0f6af

data/README.md

@@ -4,7 +4,7 @@
 
 <strong>Executable architecture specifications for Ruby and Rails</strong>
 
-<p>Declare your components and boundaries in one <code>Archspec.rb</code>, and every change gets checked in CI, whether a person or a coding agent wrote it. No AI involved, just Prism.</p>
+<p>Declare your components and boundaries in one <code>Archspec.rb</code>, and every change gets checked in CI, whether a person or a coding agent wrote it. No AI involved, just static analysis.</p>
 
 Battle tested in [<picture><source media="(prefers-color-scheme: dark)" srcset="https://rubyllm.com/assets/images/logotype_dark.svg"><img src="https://rubyllm.com/assets/images/logotype.svg" alt="RubyLLM" height="30" align="absmiddle"></picture>](https://rubyllm.com) and at [<picture><source media="(prefers-color-scheme: dark)" srcset="https://chatwithwork.com/logotype-dark.svg"><img src="https://chatwithwork.com/logotype.svg" alt="Chat with Work" height="30" align="absmiddle"></picture>](https://chatwithwork.com)
 
@@ -18,7 +18,7 @@ Battle tested in [<picture><source media="(prefers-color-scheme: dark)" srcset="
 
 ---
 
-ArchSpec turns your architecture into executable checks: components, layers, constant references, inheritance, mixins, named method calls, method protocols, naming conventions, cycles, and Rails boundaries. It is plain static analysis: it reads Ruby source with Prism, never boots the app, and no AI is involved in checking your code. The full Discourse app, 1,899 files, checks in 2.5 seconds.
+ArchSpec turns your architecture into executable checks: components, layers, constant references, inheritance, mixins, named method calls, method protocols, naming conventions, cycles, and Rails boundaries. It is plain static analysis: Rubydex builds the semantic index, Prism supplies a small syntax overlay, the app never boots, and no AI is involved in checking your code.
 
 ## Why ArchSpec?
 
@@ -100,10 +100,13 @@ Write local rules in plain Ruby:
 component :controllers, in: "app/controllers/**/*.rb"
 component :models, in: "app/models/**/*.rb"
 component :services, in: "app/services/**/*.rb"
+component :records, descendants_of: "ApplicationRecord"
 
 controllers.can_only_use :models, :services
 models.cannot_use :controllers
-services.cannot_call :render, :redirect_to, :params, :session
+services.cannot_call :render, :redirect_to, :params, :session,
+  because: "services do not own the HTTP response"
+models.cannot_call :find_by_sql, receiver: "ActiveRecord::Base"
 services.cannot_instantiate_and_invoke
 ```
 
@@ -124,7 +127,7 @@ architecture :cqrs,
 - **Layers:** dependency direction and cycles
 - **Rails:** controller APIs kept out of models and services
 - **Architectures:** Rails, vanilla Rails, layered, hexagonal, clean, modular monolith, CQRS, event-driven, and Ruby conventions bundles
-- **Protocols:** required methods such as `resolve`, `perform`, or project-specific interfaces
+- **Protocols:** instance/class APIs and callable signatures such as `call(amount, actor:)`
 - **Naming:** conventions on a component's public API, such as banning `get_`/`set_` or pairing `with_x` with `without_x`
 - **Objects:** rules against one-shot `Something.new(...).whatever` command objects
 - **Empty components:** directories that must stay empty, like `app/services` in vanilla Rails
@@ -136,6 +139,8 @@ ArchSpec does not check Zeitwerk constant names. Zeitwerk does that itself. Add
 
 ## Installation
 
+ArchSpec requires Ruby 3.2 or newer.
+
 Add ArchSpec to your Gemfile:
 
 ```ruby
@@ -172,8 +177,9 @@ bundle exec archspec check --update-todo
 bundle exec archspec explain app/models/user.rb
 ```
 
-`explain` shows why a file or constant belongs to a component and which outgoing
-facts ArchSpec found:
+`explain` shows why a file or constant belongs to a component, its resolved
+ancestry, outgoing facts, incoming dependencies, and anything the analysis
+could not prove:
 
 ```text
 app/models/user.rb