archspec 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5ac200fd85432184c5043ce7540e45cb3bcc0013a37ecd77d07c34aca51bfd8
-  data.tar.gz: 5d3e6b1558c796c6784505b9637b5fa58fb0da9d7b85fd30e71b7a26689da471
+  metadata.gz: 3b50ec4f86cfdf9e4f95b1cf4a28c4dec212d711781675dedd6648f13aed7c1f
+  data.tar.gz: 9303aefb00b161004cc515b0d1b2ad03b3e60f396ef34b9dc86be4e7a1825650
 SHA512:
-  metadata.gz: 71b4a46c3423cd47b0317559aea01038431b29f0fa8cbd1f72a403cf5e4a3bb64bf7649412752110d7a49e5e59abbc387dd3e3ec1251a11a1f7219d6fdd05877
-  data.tar.gz: 28f23d54d05d3d16663a5c728aa55846b45f240913cdada2954672059d9193e895c7e651434351bef50f30731ad08e8b5660680e17d97b294846745f769e7f75
+  metadata.gz: 56bd81e5ee880404a80c7f29d498c58903bd8d087c5e8deb80af060d6d169c3b40e471eb09758500d6522516d83090b435b45ab243f780978539840b9548681e
+  data.tar.gz: a3dc2d41b6b97edd3ddacb8c84632c0b8ae81471c9132ec02ddbf66ce68d8dd916d068aeb366a8bed99f996ed6f81cda8a3a48b502459b0d25afc525d81df95d

data/README.md

@@ -1,11 +1,12 @@
 # ArchSpec
 
-Architecture linter for Ruby and Rails.
+Static analysis for your architecture. A linter for Ruby and Rails boundaries.
 
 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.
+change in CI, whether a person or a coding agent wrote it. It is plain static
+analysis: it reads Ruby source with Prism, never boots the app, and no AI is
+involved in checking your code.
 
 It maps conventional Rails files to constants and checks the structural rules
 you write down: components, layers, constant references, inheritance, mixins,
@@ -164,7 +165,18 @@ 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.
+facts ArchSpec found:
+
+```text
+app/models/user.rb
+
+  defined constants: User
+  components:
+    models: matched file pattern app/models/**/*.rb
+  outgoing facts:
+    1:14 │ inherits from ApplicationRecord
+     2:3 │ references UsersController
+```
 
 ## Checking AI-Written Code
 
@@ -182,10 +194,16 @@ Passing paths still analyzes the project so dependencies resolve, but reports on
 If it fails, read the evidence before changing the spec:
 
 ```text
-[dependencies.forbid] app/models/user.rb:2:3
-  models must not depend on controllers
-  evidence: User references_constant UsersController
-  confidence: high
+[error] models must not depend on controllers [dependencies.forbid]
+
+app/models/user.rb:2:3
+
+    1 │ class User < ApplicationRecord
+  → 2 │   UsersController
+      │   ^~~~~~~~~~~~~~~
+    3 │ end
+
+  note: User references UsersController
 ```
 
 Most failures should be fixed in the generated code. Update the spec only when

data/lib/archspec/analyzer.rb

@@ -81,7 +81,9 @@ module ArchSpec
             when 'next-line'
               suppressions << Suppression.new(rule, line + 1, line + 1, reason)
             else
-              active[rule] << [line + 1, reason]
+              # The block form covers its own line too, so a trailing
+              # `# archspec:disable RULE` works like RuboCop's.
+              active[rule] << [line, reason]
             end
           elsif (match = text.match(ENABLE_PATTERN))
             rule = normalize_rule(match[1])
@@ -141,43 +143,49 @@ module ArchSpec
         attr_accessor: %i[reader writer]
       }.freeze
 
-      def visit(graph, path, node, current_constant: nil, namespace: [], visibility: :public, default_scope: :instance)
+      def visit(graph, path, node, current_constant: nil, namespace: [], nesting: [], visibility: :public,
+                default_scope: :instance)
         return unless node
 
         case node
         when Prism::ProgramNode, Prism::StatementsNode
-          visit_children(graph, path, node, current_constant: current_constant, namespace: namespace,
+          visit_children(graph, path, node, current_constant: current_constant, namespace: namespace, nesting: nesting,
                                             visibility: visibility, default_scope: default_scope)
         when Prism::ClassNode
-          visit_class(graph, path, node, current_constant: current_constant, namespace: namespace)
+          visit_class(graph, path, node, current_constant: current_constant, namespace: namespace, nesting: nesting)
         when Prism::ModuleNode
-          visit_module(graph, path, node, current_constant: current_constant, namespace: namespace)
+          visit_module(graph, path, node, current_constant: current_constant, namespace: namespace, nesting: nesting)
         when Prism::SingletonClassNode
           visit_singleton_class(graph, path, node, current_constant: current_constant, namespace: namespace,
-                                                   visibility: visibility, default_scope: default_scope)
+                                                   nesting: nesting, visibility: visibility,
+                                                   default_scope: default_scope)
         when Prism::DefNode
           visit_def(graph, path, node, current_constant: current_constant, namespace: namespace,
-                                       visibility: visibility, default_scope: default_scope)
+                                       nesting: nesting, visibility: visibility, default_scope: default_scope)
         when Prism::CallNode
           visit_call(graph, path, node, current_constant: current_constant, namespace: namespace,
-                                        visibility: visibility, default_scope: default_scope)
+                                        nesting: nesting, visibility: visibility, default_scope: default_scope)
         when Prism::ConstantPathNode, Prism::ConstantReadNode
-          add_constant_reference(graph, path, node, current_constant)
+          add_constant_reference(graph, path, node, current_constant, nesting)
         else
-          visit_children(graph, path, node, current_constant: current_constant, namespace: namespace,
+          visit_children(graph, path, node, current_constant: current_constant, namespace: namespace, nesting: nesting,
                                             visibility: visibility, default_scope: default_scope)
         end
       end
 
       private
 
-      def visit_class(graph, path, node, current_constant:, namespace:)
+      def visit_class(graph, path, node, current_constant:, namespace:, nesting:)
         name = qualified_constant_name(node.constant_path, namespace)
+        return visit_children(graph, path, node, current_constant: current_constant, namespace: namespace,
+                                                 nesting: nesting) unless name
+
         constant = graph.add_constant(
           name: name,
           kind: :class,
           path: path,
-          location: SourceLocation.from_prism(path, node.location)
+          location: SourceLocation.from_prism(path, node.location),
+          nesting: nesting
         )
 
         if node.superclass
@@ -190,31 +198,38 @@ module ArchSpec
               from_path: path,
               from_constant: constant.name,
               to: superclass,
-              location: SourceLocation.from_prism(path, node.superclass.location)
+              location: SourceLocation.from_prism(path, node.superclass.location),
+              lexical_nesting: nesting
             )
           else
             # Dynamic superclass (Struct.new, DelegateClass(...)): no
             # inherits_from edge, but constants inside still count as
             # references, and ancestry stays marked unresolved.
             constant.superclass = node.superclass.slice
-            visit(graph, path, node.superclass, current_constant: constant.name,
-                                                namespace: constant.name.split('::'))
+            visit(graph, path, node.superclass, current_constant: constant.name, namespace: namespace,
+                                                nesting: nesting)
           end
         end
 
-        visit_constant_body(graph, path, constant, node.body, constant.name.split('::'))
+        visit_constant_body(graph, path, constant, node.body, constant.name.split('::'),
+                            nesting: [constant.name] + nesting)
       end
 
-      def visit_module(graph, path, node, current_constant:, namespace:)
+      def visit_module(graph, path, node, current_constant:, namespace:, nesting:)
         name = qualified_constant_name(node.constant_path, namespace)
+        return visit_children(graph, path, node, current_constant: current_constant, namespace: namespace,
+                                                 nesting: nesting) unless name
+
         constant = graph.add_constant(
           name: name,
           kind: :module,
           path: path,
-          location: SourceLocation.from_prism(path, node.location)
+          location: SourceLocation.from_prism(path, node.location),
+          nesting: nesting
         )
 
-        visit_constant_body(graph, path, constant, node.body, constant.name.split('::'))
+        visit_constant_body(graph, path, constant, node.body, constant.name.split('::'),
+                            nesting: [constant.name] + nesting)
       end
 
       # A +class << self+ (or +class << SomeConstant+) block defines methods on a
@@ -222,15 +237,15 @@ module ArchSpec
       # applies to them. Walk the body with +default_scope: :class+ against the
       # target constant. An unknown target (+class << variable+) still has its
       # body visited for edges, but no methods are attributed.
-      def visit_singleton_class(graph, path, node, current_constant:, namespace:, visibility:, default_scope:)
+      def visit_singleton_class(graph, path, node, current_constant:, namespace:, nesting:, visibility:, default_scope:)
         target = singleton_target(node.expression, current_constant)
         constant = target && graph.constants_named(target).find { |candidate| candidate.path == path }
 
         if constant
-          visit_constant_body(graph, path, constant, node.body, namespace, default_scope: :class)
+          visit_constant_body(graph, path, constant, node.body, namespace, nesting: nesting, default_scope: :class)
         else
-          visit_children(graph, path, node, current_constant: current_constant, namespace: namespace,
-                                            visibility: visibility, default_scope: default_scope)
+          visit_children(graph, path, node, current_constant: nil, namespace: namespace,
+                                            nesting: nesting, visibility: visibility, default_scope: :class)
         end
       end
 
@@ -246,11 +261,11 @@ module ArchSpec
       # so bare +def+s there are class methods. Every statement is still handed to
       # +visit+, so all other facts (calls, references, mixins) are recorded
       # exactly as before.
-      def visit_constant_body(graph, path, constant, body, namespace, default_scope: :instance)
+      def visit_constant_body(graph, path, constant, body, namespace, nesting:, default_scope: :instance)
         return unless body
 
         unless body.is_a?(Prism::StatementsNode)
-          return visit(graph, path, body, current_constant: constant.name, namespace: namespace,
+          return visit(graph, path, body, current_constant: constant.name, namespace: namespace, nesting: nesting,
                                           default_scope: default_scope)
         end
 
@@ -258,16 +273,18 @@ module ArchSpec
         body.body.each do |statement|
           if (modifier = visibility_modifier(statement))
             visibility = apply_visibility_modifier(graph, path, constant, statement, namespace, visibility, modifier,
-                                                   default_scope)
+                                                   default_scope, nesting)
           else
             visit(graph, path, statement, current_constant: constant.name, namespace: namespace,
-                                          visibility: visibility, default_scope: default_scope)
+                                          nesting: nesting, visibility: visibility, default_scope: default_scope)
           end
         end
       end
 
-      def visit_def(graph, path, node, current_constant:, namespace:, visibility: :public, default_scope: :instance)
-        if current_constant && (constant = graph.constants_named(current_constant).find do |candidate|
+      def visit_def(graph, path, node, current_constant:, namespace:, nesting:, visibility: :public,
+                    default_scope: :instance)
+        owner = method_definition_owner(graph, node, current_constant, nesting)
+        if owner && (constant = graph.constants_named(owner).find do |candidate|
           candidate.path == path
         end)
           location = SourceLocation.from_prism(path, node.location)
@@ -289,13 +306,24 @@ module ArchSpec
           )
         end
 
-        visit_children(graph, path, node, current_constant: current_constant, namespace: namespace)
+        visit_children(graph, path, node, current_constant: current_constant, namespace: namespace, nesting: nesting)
+      end
+
+      def method_definition_owner(graph, node, current_constant, nesting)
+        return current_constant unless node.receiver
+        return current_constant if node.receiver.is_a?(Prism::SelfNode)
+        return unless constant_node?(node.receiver)
+
+        name = constant_reference_name(node.receiver)
+        graph.resolve_constant_reference(name, current_constant, lexical_nesting: nesting) if name
       end
 
-      def visit_call(graph, path, node, current_constant:, namespace:, visibility: :public, default_scope: :instance)
+      def visit_call(graph, path, node, current_constant:, namespace:, nesting:, visibility: :public,
+                     default_scope: :instance)
         unless node.message
           return visit_children(graph, path, node, current_constant: current_constant, namespace: namespace,
-                                                   visibility: visibility, default_scope: default_scope)
+                                                   nesting: nesting, visibility: visibility,
+                                                   default_scope: default_scope)
         end
 
         message = node.message.to_sym
@@ -336,7 +364,8 @@ module ArchSpec
               from_path: path,
               from_constant: current_constant,
               to: constant_name,
-              location: location
+              location: location,
+              lexical_nesting: nesting
             )
           end
         end
@@ -361,11 +390,11 @@ module ArchSpec
           )
         end
 
-        visit_children(graph, path, node, current_constant: current_constant, namespace: namespace,
+        visit_children(graph, path, node, current_constant: current_constant, namespace: namespace, nesting: nesting,
                                           visibility: visibility, default_scope: default_scope)
       end
 
-      def add_constant_reference(graph, path, node, current_constant)
+      def add_constant_reference(graph, path, node, current_constant, nesting)
         name = constant_reference_name(node)
         return unless name
 
@@ -374,14 +403,16 @@ module ArchSpec
           from_path: path,
           from_constant: current_constant,
           to: name,
-          location: SourceLocation.from_prism(path, node.location)
+          location: SourceLocation.from_prism(path, node.location),
+          lexical_nesting: nesting
         )
       end
 
-      def visit_children(graph, path, node, current_constant:, namespace:, visibility: :public, default_scope: :instance)
+      def visit_children(graph, path, node, current_constant:, namespace:, nesting:, visibility: :public,
+                         default_scope: :instance)
         node.child_nodes.compact.each do |child|
           visit(graph, path, child, current_constant: current_constant, namespace: namespace,
-                                    visibility: visibility, default_scope: default_scope)
+                                    nesting: nesting, visibility: visibility, default_scope: default_scope)
         end
       end
 
@@ -410,7 +441,7 @@ module ArchSpec
       # statements that follow it. A bare +private+ changes that default; the
       # inline (+private def foo+) and symbol-list (+private :foo+) forms mark
       # only the methods they name and leave the default unchanged.
-      def apply_visibility_modifier(graph, path, constant, node, namespace, current, spec, default_scope)
+      def apply_visibility_modifier(graph, path, constant, node, namespace, current, spec, default_scope, nesting)
         visibility, forced_scope = spec
         scope = forced_scope || default_scope
         arguments = node.arguments&.arguments || []
@@ -419,20 +450,21 @@ module ArchSpec
 
         if definitions.any?
           visit(graph, path, node, current_constant: constant.name, namespace: namespace,
-                                   visibility: visibility, default_scope: default_scope)
+                                   nesting: nesting, visibility: visibility, default_scope: default_scope)
           current
         elsif names.any?
           names.each { |name| constant.set_visibility(name.unescaped.to_sym, scope, visibility) }
           visit(graph, path, node, current_constant: constant.name, namespace: namespace,
-                                   visibility: current, default_scope: default_scope)
+                                   nesting: nesting, visibility: current, default_scope: default_scope)
           current
-        elsif forced_scope.nil?
+        elsif arguments.empty? && forced_scope.nil?
           visit(graph, path, node, current_constant: constant.name, namespace: namespace,
-                                   visibility: visibility, default_scope: default_scope)
+                                   nesting: nesting, visibility: visibility, default_scope: default_scope)
           visibility
         else
           visit(graph, path, node, current_constant: constant.name, namespace: namespace,
-                                   visibility: current, default_scope: default_scope)
+                                   nesting: nesting, visibility: forced_scope.nil? ? visibility : current,
+                                   default_scope: default_scope)
           current
         end
       end
@@ -461,10 +493,9 @@ module ArchSpec
 
         constant = graph.constants_named(current_constant).find { |candidate| candidate.path == path }
         return unless constant
+        return if message == :delegate && truthy_keyword_argument?(node, :prefix)
 
         names = generated_method_names(constant, node, message)
-        return if message == :delegate && keyword_argument?(node, :prefix)
-
         adder = default_scope == :class ? :add_class_method : :add_instance_method
         names.each do |name|
           kinds = message == :attribute ? %i[reader writer] : ATTR_MESSAGES.fetch(message, %i[reader])
@@ -479,7 +510,9 @@ module ArchSpec
       def generated_method_names(constant, node, message)
         names = symbol_arguments(node)
         return names unless message == :attribute
-        return names if constant.superclass == 'ActiveSupport::CurrentAttributes'
+
+        superclass = constant.superclass.to_s.sub(/\A::/, '')
+        return names if superclass == 'ActiveSupport::CurrentAttributes'
 
         names.first(1)
       end
@@ -490,11 +523,13 @@ module ArchSpec
         end || []
       end
 
-      def keyword_argument?(node, name)
+      def truthy_keyword_argument?(node, name)
         node.arguments&.arguments&.any? do |argument|
           argument.is_a?(Prism::KeywordHashNode) && argument.elements.any? do |element|
             element.is_a?(Prism::AssocNode) && element.key.is_a?(Prism::SymbolNode) &&
-              element.key.unescaped.to_sym == name
+              element.key.unescaped.to_sym == name &&
+              !element.value.is_a?(Prism::FalseNode) &&
+              !element.value.is_a?(Prism::NilNode)
           end
         end
       end
@@ -512,7 +547,11 @@ module ArchSpec
         return unless receiver.is_a?(Prism::CallNode) && receiver.message&.to_sym == :new
 
         receiver_node = receiver.receiver
-        name = (constant_reference_name(receiver_node) if constant_node?(receiver_node)) || receiver_node&.slice
+        return unless constant_node?(receiver_node)
+
+        name = constant_reference_name(receiver_node)
+        return unless name
+
         "#{name}##{node.message}"
       end
 
@@ -520,7 +559,9 @@ module ArchSpec
       # Admin::Users::RolesController, so compact paths join the namespace too.
       def qualified_constant_name(node, namespace)
         raw = constant_reference_name(node)
-        absolute = node.respond_to?(:full_name_parts) && node.full_name_parts.first == :""
+        return unless raw
+
+        absolute = node.is_a?(Prism::ConstantPathNode) && node.parent.nil?
 
         if absolute || namespace.empty?
           raw
@@ -532,8 +573,11 @@ module ArchSpec
       # nil when the path has dynamic parts (self.class::FOO): there is no
       # static name to check against.
       def constant_reference_name(node)
-        node.full_name.to_s.sub(/\A::/, '')
-      rescue Prism::ConstantPathNode::DynamicPartsInConstantPathError
+        return unless constant_node?(node)
+
+        node.full_name.to_s
+      rescue Prism::ConstantPathNode::DynamicPartsInConstantPathError,
+             Prism::ConstantPathNode::MissingNodesInConstantPathError
         nil
       end
 

data/lib/archspec/architectures.rb

@@ -11,35 +11,33 @@ module ArchSpec
   # Every preset accepts overrides for its directories, so you can keep the
   # shape while pointing at your own paths. The presets are:
   #
-  # - +:rails+ (aliases +:rails_mvc+, +:rails_way+): conventional MVC that keeps
-  #   controller APIs out of models and services. Options +components:+,
-  #   +controller_api:+, +share_helpers:+.
+  # - +:rails+: conventional MVC that keeps controller APIs out of models and
+  #   services. Options +components:+, +controller_api:+, +share_helpers:+.
   # - +:rails_strict+: +:rails+ plus a cycle check and a concern independence
   #   check. Adds option +concerns:+.
   # - +:vanilla_rails+: +:rails+ plus empty-directory rules for the 37signals
   #   style (forbidding +app/services+, +app/forms+, +app/policies+, and more)
   #   and the concern independence check. Options +components:+, +empty:+,
   #   +controller_api:+, +share_helpers:+, +concerns:+.
-  # - +:layered+ (alias +:rails_layered+): ordered layers that may only depend
-  #   inward, with a cycle check. Option +layers:+ (order matters).
-  # - +:hexagonal+ (alias +:rails_hexagonal+): ports and adapters, keeping the
-  #   domain away from adapters. Options +application:+, +domain:+, +ports:+,
-  #   +adapters:+.
-  # - +:clean+ (alias +:rails_clean+): clean architecture layers. Options
-  #   +frameworks:+, +interface_adapters:+, +use_cases:+, +entities:+.
-  # - +:modular_monolith+ (alias +:bounded_contexts+): named packages with
-  #   per-package allowlists and optional public APIs. Options +components:+
-  #   (required), +allow:+, +public:+.
-  # - +:cqrs+ (alias +:rails_cqrs+): separates commands from queries and keeps
-  #   writes out of queries. Options +commands:+, +queries:+, +read_models:+,
-  #   +mutating_methods:+.
-  # - +:event_driven+ (alias +:rails_event_driven+): events, publishers, and
-  #   subscribers. Options +events:+, +publishers:+, +subscribers:+.
+  # - +:layered+: ordered layers that may only depend inward, with a cycle
+  #   check. Option +layers:+ (order matters).
+  # - +:hexagonal+: ports and adapters, keeping the domain away from adapters.
+  #   Options +application:+, +domain:+, +ports:+, +adapters:+.
+  # - +:clean+: clean architecture layers. Options +frameworks:+,
+  #   +interface_adapters:+, +use_cases:+, +entities:+.
+  # - +:modular_monolith+: named packages with per-package allowlists and
+  #   optional public APIs. Options +components:+ (required), +allow:+,
+  #   +public:+.
+  # - +:cqrs+: separates commands from queries and keeps writes out of queries.
+  #   Options +commands:+, +queries:+, +read_models:+, +mutating_methods:+.
+  # - +:event_driven+: events, publishers, and subscribers. Options +events:+,
+  #   +publishers:+, +subscribers:+.
   # - +:ruby_conventions+: generic Ruby naming idioms (no +get_+/+set_+, no +is_+
   #   prefix), applied project-wide. Adds no components, so it composes with any
   #   other architecture. No options.
   #
-  # See the guides at https://archspecrb.dev/architectures/ for each in depth.
+  # See the {architecture guides}[https://archspecrb.dev/architectures/] for
+  # each preset in depth.
   module Architectures
     extend self
 
@@ -106,84 +104,77 @@ module ArchSpec
       upsert upsert!
     ].freeze
 
+    # Every option each architecture accepts, with its default. The single
+    # source of truth for #apply: option validation checks these keys, and the
+    # architecture methods receive these values merged with the caller's.
+    DEFAULTS = {
+      rails: {
+        components: DEFAULT_RAILS_MVC,
+        controller_api: CONTROLLER_METHODS,
+        share_helpers: false
+      },
+      rails_strict: {
+        components: DEFAULT_RAILS_MVC,
+        controller_api: CONTROLLER_METHODS,
+        share_helpers: false,
+        concerns: DEFAULT_CONCERNS
+      },
+      vanilla_rails: {
+        components: DEFAULT_RAILS_MVC,
+        empty: VANILLA_RAILS_EMPTY,
+        controller_api: CONTROLLER_METHODS,
+        share_helpers: false,
+        concerns: DEFAULT_CONCERNS
+      },
+      layered: { layers: DEFAULT_LAYERED },
+      hexagonal: DEFAULT_HEXAGONAL,
+      clean: DEFAULT_CLEAN,
+      modular_monolith: { components: nil, allow: {}, public: {} },
+      cqrs: DEFAULT_CQRS.merge(mutating_methods: MUTATING_METHODS),
+      event_driven: DEFAULT_EVENT_DRIVEN,
+      ruby_conventions: {}
+    }.freeze
+
     # Applies the named preset to +dsl+, forwarding +options+ to it. Raises
     # ArchSpec::Error for an unknown name. Called by
     # ArchSpec::DSL::Context#architecture, so you rarely call it directly.
     def apply(name, dsl, **options)
-      case name.to_sym
-      when :rails, :rails_mvc, :rails_way
-        rails_mvc(
-          dsl,
-          components: options.fetch(:components, DEFAULT_RAILS_MVC),
-          controller_api: options.fetch(:controller_api, CONTROLLER_METHODS),
-          share_helpers: options.fetch(:share_helpers, false)
-        )
-      when :rails_strict
-        rails_strict(
-          dsl,
-          components: options.fetch(:components, DEFAULT_RAILS_MVC),
-          controller_api: options.fetch(:controller_api, CONTROLLER_METHODS),
-          share_helpers: options.fetch(:share_helpers, false),
-          concerns: options.fetch(:concerns, DEFAULT_CONCERNS)
-        )
-      when :vanilla_rails
-        vanilla_rails(
-          dsl,
-          components: options.fetch(:components, DEFAULT_RAILS_MVC),
-          empty: options.fetch(:empty, VANILLA_RAILS_EMPTY),
-          controller_api: options.fetch(:controller_api, CONTROLLER_METHODS),
-          share_helpers: options.fetch(:share_helpers, false),
-          concerns: options.fetch(:concerns, DEFAULT_CONCERNS)
-        )
-      when :layered, :rails_layered
-        layered(dsl, layers: options.fetch(:layers, DEFAULT_LAYERED))
-      when :hexagonal, :rails_hexagonal
-        hexagonal(dsl, **with_defaults(DEFAULT_HEXAGONAL, options))
-      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, {}),
-          public: options.fetch(:public, {})
-        )
-      when :cqrs, :rails_cqrs
-        cqrs(dsl, **with_defaults(DEFAULT_CQRS, options))
-      when :event_driven, :rails_event_driven
-        event_driven(dsl, **with_defaults(DEFAULT_EVENT_DRIVEN, options))
-      when :ruby_conventions
-        ruby_conventions(dsl)
-      else
-        raise Error, "Unknown ArchSpec architecture: #{name.inspect}"
-      end
+      name = architecture_name(name)
+      defaults = DEFAULTS[name]
+      raise Error, "unknown architecture: #{name.inspect}" unless defaults
+
+      validate_options!(name, defaults, options)
+      send(name, dsl, **defaults.merge(options))
     end
 
-    def rails_mvc(dsl, components:, controller_api: CONTROLLER_METHODS, share_helpers: false)
+    def rails(dsl, components:, controller_api:, share_helpers:)
       components = normalize_map(components)
+      missing = %i[controllers models] - components.keys
+      if missing.any?
+        raise Error, "the rails architectures need controllers and models components, missing: #{missing.join(', ')}"
+      end
+
       define_components(dsl, components)
 
-      forbidden = share_helpers ? %i[controllers] : %i[controllers helpers]
+      forbidden = (share_helpers ? %i[controllers] : %i[controllers helpers]) & components.keys
       proxy_for(dsl, :controllers).can_only_use(*components.keys & %i[models services helpers mailers jobs])
-      proxy_for(dsl, :models).cannot_use(*components.keys & forbidden)
-      proxy_for(dsl, :services).cannot_use(*components.keys & forbidden)
 
-      return if controller_api.empty?
-
-      proxy_for(dsl, :models).cannot_call(*controller_api, receiver: :none)
-      proxy_for(dsl, :services).cannot_call(*controller_api, receiver: :none)
+      (%i[models services] & components.keys).each do |name|
+        proxy = proxy_for(dsl, name)
+        proxy.cannot_use(*forbidden)
+        proxy.cannot_call(*controller_api, receiver: :none) unless controller_api.empty?
+      end
     end
 
-    def rails_strict(dsl, components:, controller_api: CONTROLLER_METHODS, share_helpers: false, concerns: DEFAULT_CONCERNS)
+    def rails_strict(dsl, components:, controller_api:, share_helpers:, concerns:)
       components = normalize_map(components)
-      rails_mvc(dsl, components: components, controller_api: controller_api, share_helpers: share_helpers)
+      rails(dsl, components: components, controller_api: controller_api, share_helpers: share_helpers)
       dsl.no_cycles(among: components.keys)
       independent_concerns(dsl, concerns)
     end
 
-    def vanilla_rails(dsl, components:, empty:, controller_api: CONTROLLER_METHODS, share_helpers: false,
-                      concerns: DEFAULT_CONCERNS)
-      rails_mvc(dsl, components: components, controller_api: controller_api, share_helpers: share_helpers)
+    def vanilla_rails(dsl, components:, empty:, controller_api:, share_helpers:, concerns:)
+      rails(dsl, components: components, controller_api: controller_api, share_helpers: share_helpers)
 
       empty.each do |name, (pattern, reason)|
         dsl.component(name, in: pattern).must_be_empty(because: reason)
@@ -234,6 +225,8 @@ module ArchSpec
     end
 
     def modular_monolith(dsl, components:, allow: {}, public: {})
+      raise Error, 'architecture :modular_monolith requires the components: option' unless components
+
       components = normalize_map(components)
       define_components(dsl, components)
 
@@ -248,7 +241,7 @@ module ArchSpec
       dsl.no_cycles(among: components.keys)
     end
 
-    def cqrs(dsl, commands:, queries:, read_models: nil, mutating_methods: MUTATING_METHODS)
+    def cqrs(dsl, commands:, queries:, read_models:, mutating_methods:)
       components = normalize_map(commands: commands, queries: queries)
       components[:read_models] = read_models if read_models
       define_components(dsl, components)
@@ -283,6 +276,21 @@ module ArchSpec
 
     private
 
+    def architecture_name(name)
+      name.to_sym
+    rescue NoMethodError
+      raise Error, "unknown architecture: #{name.inspect}"
+    end
+
+    def validate_options!(name, defaults, options)
+      unknown = options.keys - defaults.keys
+      return if unknown.empty?
+
+      label = unknown.length == 1 ? 'option' : 'options'
+      names = unknown.map { |option| "#{option}:" }.sort.join(', ')
+      raise Error, "unknown #{label} for architecture :#{name}: #{names}"
+    end
+
     def forbid_name(dsl, regex, reason, scope:)
       dsl.rule(
         Rules::NamingRule.new(
@@ -294,10 +302,6 @@ module ArchSpec
       )
     end
 
-    def with_defaults(defaults, options)
-      defaults.merge(options)
-    end
-
     def normalize_map(map)
       map.to_h.transform_keys(&:to_sym)
     end