archspec 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bee3d8fe834714f4b7fb9837b8bafe96165dde21950884dff5772fc0e4a2793f
-  data.tar.gz: 0c45ca575799e4928169e931110226c1f23983a8ef1a183108759b2447a566a6
+  metadata.gz: 0001aded07b821733e37d7b2cf2adad037d06686ae1ff199510c9f42489027c7
+  data.tar.gz: 6c96d3209bbc9616a22664acabf1747117676b9e5e9f8ee7cbe473a40255fbef
 SHA512:
-  metadata.gz: d577e26b80aaea4dfe570644bcb6b072b329b4b104f11da16d6f724fbe11080035450b45d5a1f08f1809c2064794a671c037fc50aa27183e2bb06381a2c237a1
-  data.tar.gz: 7db12b7c471d72275a268a903f81e4184b03b4626539a7db01abf7d01cd6874b2d63575652c04dfe3f89165285a3557c85344c225e86728c0d6a57c99bd87e86
+  metadata.gz: 3558e6e242ba00826f4dd86b33113eebf0defda4990aa73e2dc34abed790661ccb005a91768edb0605112e85329510673d900dc9b0148339a01245844bfddcea
+  data.tar.gz: 9e1339b47c815d19be1fa994ceec99d7b113af0428dbe62d5221055b161d4668e8c9201cca76f907598d274a0302e4a2196c7fc391a6814e1904590b4766d5f3

data/README.md

@@ -1,13 +1,15 @@
 # ArchSpec
 
-Architecture checks for Ruby and Rails.
+Architecture linter for Ruby and Rails.
 
-Turn your application's architecture into executable checks.
+ArchSpec turns your application's architecture into executable checks. Declare
+your components, dependencies, and boundaries in one file, then check every
+change in CI, whether a person or a coding agent wrote it. It reads Ruby source
+with Prism and never boots the app.
 
-ArchSpec reads Ruby source with Prism, maps conventional Rails files to
-constants, and checks the structural rules you write down: components, layers,
-constant references, inheritance, mixins, named method calls, method protocols,
-cycles, and Rails boundaries.
+It maps conventional Rails files to constants and checks the structural rules
+you write down: components, layers, constant references, inheritance, mixins,
+named method calls, method protocols, cycles, and Rails boundaries.
 
 It does not try to infer the "true" design pattern of arbitrary Ruby code. You
 describe the architecture your team wants. ArchSpec checks whether the code still
@@ -17,9 +19,11 @@ matches it.
 
 Architecture usually lives in pull request comments, onboarding docs, and senior
 engineers' heads. That does not scale well, especially when code is moving fast.
+More of that code is now written by coding agents that do not know your
+conventions.
 
 ArchSpec gives you a small Ruby DSL for the rules that code review otherwise has
-to remember:
+to remember, and checks them on every change:
 
 - models do not reach into controllers
 - domain code does not depend on adapters
@@ -32,104 +36,80 @@ to remember:
 Start with conventional Rails boundaries:
 
 ```ruby
-# Archspec.rb
-ArchSpec.define "Application architecture" do
-  root "."
-  preset :rails_way
-end
+architecture :rails
 ```
 
-Go vanilla, 37signals style — rich models, no service objects:
+Go vanilla, 37signals style, with rich models and no service objects:
 
 ```ruby
-ArchSpec.define "Application architecture" do
-  root "."
-  preset :vanilla_rails
-end
+architecture :vanilla_rails
 ```
 
 Add layers when the app has a clear direction of dependencies:
 
 ```ruby
-ArchSpec.define "Application architecture" do
-  root "."
-  architecture :layered, layers: {
-    interface: "app/controllers/**/*.rb",
-    application: "app/services/**/*.rb",
-    domain: "app/models/**/*.rb"
-  }
-end
+architecture :layered
+```
+
+Override the default directories when the app uses different names:
+
+```ruby
+architecture :layered, layers: {
+  interface: "app/controllers/**/*.rb",
+  application: "app/services/**/*.rb",
+  domain: "app/models/**/*.rb"
+}
 ```
 
 Keep a hexagonal core away from adapters:
 
 ```ruby
-ArchSpec.define "Application architecture" do
-  root "."
-
-  architecture :hexagonal,
-    application: %w[app/services/**/*.rb app/use_cases/**/*.rb],
-    domain: "app/domain/**/*.rb",
-    ports: "app/ports/**/*.rb",
-    adapters: %w[app/adapters/**/*.rb app/integrations/**/*.rb]
-end
+architecture :hexagonal
 ```
 
 Check a modular monolith:
 
 ```ruby
-ArchSpec.define "Application architecture" do
-  root "."
-
-  architecture :modular_monolith,
-    components: {
-      billing: "packs/billing/**/*.rb",
-      catalog: "packs/catalog/**/*.rb",
-      shared: "packs/shared/**/*.rb"
-    },
-    allow: {
-      billing: %i[shared],
-      catalog: %i[shared]
-    }
-end
+architecture :modular_monolith,
+  components: {
+    billing: "packs/billing/**/*.rb",
+    catalog: "packs/catalog/**/*.rb",
+    shared: "packs/shared/**/*.rb"
+  },
+  allow: {
+    billing: %i[shared],
+    catalog: %i[shared]
+  }
 ```
 
 Write local rules in plain Ruby:
 
 ```ruby
-ArchSpec.define "Application architecture" do
-  root "."
-
-  component :controllers, in: "app/controllers/**/*.rb"
-  component :models, in: "app/models/**/*.rb"
-  component :services, in: "app/services/**/*.rb"
+component :controllers, in: "app/controllers/**/*.rb"
+component :models, in: "app/models/**/*.rb"
+component :services, in: "app/services/**/*.rb"
 
-  controllers.can_use :models, :services
-  models.cannot_use :controllers
-  services.cannot_call :render, :redirect_to, :params, :session
-  services.cannot_instantiate_and_invoke
-end
+controllers.can_use :models, :services
+models.cannot_use :controllers
+services.cannot_call :render, :redirect_to, :params, :session
+services.cannot_instantiate_and_invoke
 ```
 
 Check command/query separation:
 
 ```ruby
-ArchSpec.define "Application architecture" do
-  root "."
-
-  architecture :cqrs,
-    commands: "app/commands/**/*.rb",
-    queries: "app/queries/**/*.rb",
-    read_models: "app/read_models/**/*.rb"
-end
+architecture :cqrs,
+  commands: "app/commands/**/*.rb",
+  queries: "app/queries/**/*.rb",
+  read_models: "app/read_models/**/*.rb"
 ```
 
 ## What It Checks
 
 - **Dependencies:** allowed and forbidden references between components
 - **Layers:** dependency direction and cycles
-- **Rails MVC:** controller APIs kept out of models and services
-- **Architectures:** Rails MVC, layered, hexagonal, clean, modular monolith, CQRS, and event-driven bundles
+- **Rails:** controller APIs kept out of models and services
+- **Architectures:** Rails, vanilla Rails, layered, hexagonal, clean, modular monolith, CQRS, and event-driven bundles
 - **Protocols:** required methods such as `resolve`, `perform`, or project-specific interfaces
 - **Objects:** rules against one-shot `Something.new(...).whatever` command objects
 - **Zeitwerk names:** conventional file names defining the expected constants

data/lib/archspec/analyzer.rb

@@ -351,16 +351,10 @@ module ArchSpec
 
       def instantiates_and_invokes(node)
         receiver = node.receiver
-        return unless receiver.is_a?(Prism::CallNode)
-        return unless receiver.message == 'new'
+        return unless receiver.is_a?(Prism::CallNode) && receiver.message&.to_sym == :new
 
-        "#{new_receiver_name(receiver)}##{node.message}"
-      end
-
-      def new_receiver_name(node)
-        return constant_reference_name(node.receiver) if constant_node?(node.receiver)
-
-        node.receiver&.slice || '(unknown)'
+        name = constant_node?(receiver.receiver) ? constant_reference_name(receiver.receiver) : receiver.receiver&.slice
+        "#{name}##{node.message}"
       end
 
       def qualified_constant_name(node, namespace)

data/lib/archspec/architectures.rb

@@ -45,6 +45,15 @@ module ArchSpec
       subscribers: 'app/subscribers/**/*.rb'
     }.freeze
 
+    VANILLA_RAILS_EMPTY = {
+      services: ['app/services/**/*.rb', 'behavior belongs on models, not service objects'],
+      forms: ['app/forms/**/*.rb', 'use strong parameters and model validations'],
+      policies: ['app/policies/**/*.rb', 'authorization is predicate methods on models'],
+      decorators: ['app/decorators/**/*.rb', 'use helpers and ERB partials'],
+      presenters: ['app/presenters/**/*.rb', 'presentation objects are POROs in app/models'],
+      view_components: ['app/components/**/*.rb', 'use helpers and ERB partials']
+    }.freeze
+
     CONTROLLER_METHODS = %i[render redirect_to params session cookies flash].freeze
     MUTATING_METHODS = %i[
       create create!
@@ -58,19 +67,27 @@ module ArchSpec
 
     def apply(name, dsl, **options)
       case name.to_sym
-      when :rails_mvc, :rails_way
+      when :rails, :rails_mvc, :rails_way
         rails_mvc(dsl, components: options.fetch(:components, DEFAULT_RAILS_MVC))
-      when :layered
+      when :rails_strict
+        rails_strict(dsl, components: options.fetch(:components, DEFAULT_RAILS_MVC))
+      when :vanilla_rails
+        vanilla_rails(
+          dsl,
+          components: options.fetch(:components, DEFAULT_RAILS_MVC),
+          empty: options.fetch(:empty, VANILLA_RAILS_EMPTY)
+        )
+      when :layered, :rails_layered
         layered(dsl, layers: options.fetch(:layers, DEFAULT_LAYERED))
-      when :hexagonal
+      when :hexagonal, :rails_hexagonal
         hexagonal(dsl, **with_defaults(DEFAULT_HEXAGONAL, options))
-      when :clean
+      when :clean, :rails_clean
         clean(dsl, **with_defaults(DEFAULT_CLEAN, options))
       when :modular_monolith, :bounded_contexts
         modular_monolith(dsl, components: options.fetch(:components), allow: options.fetch(:allow, {}))
-      when :cqrs
+      when :cqrs, :rails_cqrs
         cqrs(dsl, **with_defaults(DEFAULT_CQRS, options))
-      when :event_driven
+      when :event_driven, :rails_event_driven
         event_driven(dsl, **with_defaults(DEFAULT_EVENT_DRIVEN, options))
       else
         raise Error, "Unknown ArchSpec architecture: #{name.inspect}"
@@ -88,6 +105,21 @@ module ArchSpec
       proxy_for(dsl, :services).cannot_call(*CONTROLLER_METHODS)
     end
 
+    def rails_strict(dsl, components:)
+      components = normalize_map(components)
+      rails_mvc(dsl, components: components)
+      dsl.verify_zeitwerk_names!
+      dsl.no_cycles!(among: components.keys)
+    end
+
+    def vanilla_rails(dsl, components:, empty:)
+      rails_mvc(dsl, components: components)
+
+      empty.each do |name, (pattern, reason)|
+        dsl.component(name, in: pattern).must_be_empty(because: reason)
+      end
+    end
+
     def layered(dsl, layers:)
       ordered = normalize_map(layers)
       define_components(dsl, ordered)

data/lib/archspec/cli.rb

@@ -8,10 +8,7 @@ module ArchSpec
 
     CONFIG_FILE = 'Archspec.rb'
     TEMPLATE = <<~RUBY
-      ArchSpec.define "Application architecture" do
-        root "."
-        preset :rails_way
-      end
+      architecture :rails
     RUBY
 
     def run(argv, output: $stdout, error: $stderr)
@@ -107,9 +104,10 @@ module ArchSpec
 
       ArchSpec.last_definition = nil
       absolute_config = File.expand_path(config_path)
-      load absolute_config
-      definition = ArchSpec.last_definition
-      raise Error, "#{config_path} did not call ArchSpec.define." unless definition
+      definition = Definition.new
+      definition.extend(DSL::Context)
+      definition.instance_eval(File.read(absolute_config), absolute_config)
+      definition = ArchSpec.last_definition || definition
 
       [definition, definition.absolute_root(File.dirname(absolute_config))]
     end

data/lib/archspec/definition.rb

@@ -20,7 +20,7 @@ module ArchSpec
     attr_accessor :name, :root_path, :baseline_path
     attr_reader :source_patterns, :ignore_patterns, :component_specs, :rules
 
-    def initialize(name)
+    def initialize(name = nil)
       @name = name
       @root_path = '.'
       @baseline_path = nil

data/lib/archspec/dsl.rb

@@ -31,10 +31,6 @@ module ArchSpec
       alias layer component
       alias role component
 
-      def preset(name, **options)
-        Presets.apply(name, self, **options)
-      end
-
       def architecture(name, **options)
         Architectures.apply(name, self, **options)
       end

data/lib/archspec/model.rb

@@ -146,10 +146,10 @@ module ArchSpec
     end
 
     def method_definitions_for_component(name)
-      component = components.fetch(name.to_sym)
+      component = components[name.to_sym]
+      return [] unless component
+
       component.constants.flat_map { |constant_name| constants_named(constant_name) }.flat_map(&:method_definitions)
-    rescue KeyError
-      []
     end
 
     def assign_components(component_specs)

data/lib/archspec/presets.rb

@@ -5,73 +5,7 @@ module ArchSpec
     module_function
 
     def apply(name, dsl, **options)
-      case name.to_sym
-      when :rails_way, :rails_mvc
-        rails_way(dsl, **options)
-      when :rails_strict
-        rails_strict(dsl, **options)
-      when :vanilla_rails
-        vanilla_rails(dsl, **options)
-      when :rails_layered
-        rails_layered(dsl, **options)
-      when :rails_hexagonal
-        rails_hexagonal(dsl, **options)
-      when :rails_clean
-        rails_clean(dsl, **options)
-      when :rails_cqrs
-        rails_cqrs(dsl, **options)
-      when :rails_event_driven
-        rails_event_driven(dsl, **options)
-      else
-        raise Error, "Unknown ArchSpec preset: #{name.inspect}"
-      end
-    end
-
-    def rails_way(dsl, **options)
-      Architectures.apply(:rails_mvc, dsl, **options)
-    end
-
-    def rails_strict(dsl, **options)
-      rails_way(dsl, **options)
-      dsl.verify_zeitwerk_names!
-      dsl.no_cycles!(among: %i[controllers models helpers mailers jobs services])
-    end
-
-    VANILLA_RAILS_EMPTY = {
-      services: ['app/services/**/*.rb', 'behavior belongs on models, not service objects'],
-      forms: ['app/forms/**/*.rb', 'use strong parameters and model validations'],
-      policies: ['app/policies/**/*.rb', 'authorization is predicate methods on models'],
-      decorators: ['app/decorators/**/*.rb', 'use helpers and partials'],
-      presenters: ['app/presenters/**/*.rb', 'presentation objects are POROs in app/models'],
-      view_components: ['app/components/**/*.rb', 'use helpers and ERB partials']
-    }.freeze
-
-    def vanilla_rails(dsl, **options)
-      rails_way(dsl, **options)
-
-      VANILLA_RAILS_EMPTY.each do |name, (pattern, reason)|
-        dsl.component(name, in: pattern).must_be_empty(because: reason)
-      end
-    end
-
-    def rails_layered(dsl, **options)
-      Architectures.apply(:layered, dsl, **options)
-    end
-
-    def rails_hexagonal(dsl, **options)
-      Architectures.apply(:hexagonal, dsl, **options)
-    end
-
-    def rails_clean(dsl, **options)
-      Architectures.apply(:clean, dsl, **options)
-    end
-
-    def rails_cqrs(dsl, **options)
-      Architectures.apply(:cqrs, dsl, **options)
-    end
-
-    def rails_event_driven(dsl, **options)
-      Architectures.apply(:event_driven, dsl, **options)
+      Architectures.apply(name, dsl, **options)
     end
   end
 end

data/lib/archspec/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ArchSpec
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/archspec.rb

@@ -27,7 +27,7 @@ module ArchSpec
   class << self
     attr_accessor :last_definition
 
-    def define(name = 'Architecture', &block)
+    def define(name = nil, &block)
       definition = Definition.new(name)
       definition.extend(DSL::Context)
       definition.instance_eval(&block) if block

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: archspec
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Carmine Paolino
@@ -52,7 +52,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '13.0'
-description: Convention-aware architecture checks for Ruby and Rails codebases.
+description: A static architecture linter for Ruby and Rails. Declare your components,
+  dependencies, and boundaries in one file, then check every change in CI. It reads
+  source with Prism and never boots the app.
 email:
 - carmine@paolino.me
 executables:
@@ -112,5 +114,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Architecture fitness functions for Ruby and Rails.
+summary: Architecture linter for Ruby and Rails.
 test_files: []