archspec 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25ea714cd768976e860df4f0dbaa9ff477e381096f95b98787a0a645fc0cd776
-  data.tar.gz: 527621e2bb18514433cf26ede594f2cafa2699d0d95e2d3fa4d9e8b9e4aac354
+  metadata.gz: b5ac200fd85432184c5043ce7540e45cb3bcc0013a37ecd77d07c34aca51bfd8
+  data.tar.gz: 5d3e6b1558c796c6784505b9637b5fa58fb0da9d7b85fd30e71b7a26689da471
 SHA512:
-  metadata.gz: f9c83e97692a44bbf72391593e695bc4c8a7859d148508f4cb8cf490a55e51a8de98d0df8ab0d37bf8bf13fcdb3e4707f9325850a39b9a33ea678a0d0aa7f3b2
-  data.tar.gz: ec19d8b85144cee92cd7bd2c968d848aef39feccdda87b56849dab7ac706543fec8041bee524ab0c5532193b423442f6ef3eec00d6d52f6301ec3e960b5cf1b8
+  metadata.gz: 71b4a46c3423cd47b0317559aea01038431b29f0fa8cbd1f72a403cf5e4a3bb64bf7649412752110d7a49e5e59abbc387dd3e3ec1251a11a1f7219d6fdd05877
+  data.tar.gz: 28f23d54d05d3d16663a5c728aa55846b45f240913cdada2954672059d9193e895c7e651434351bef50f30731ad08e8b5660680e17d97b294846745f769e7f75

data/README.md

@@ -92,7 +92,7 @@ component :controllers, in: "app/controllers/**/*.rb"
 component :models, in: "app/models/**/*.rb"
 component :services, in: "app/services/**/*.rb"
 
-controllers.can_use :models, :services
+controllers.can_only_use :models, :services
 models.cannot_use :controllers
 services.cannot_call :render, :redirect_to, :params, :session
 services.cannot_instantiate_and_invoke
@@ -114,13 +114,17 @@ architecture :cqrs,
 - **Concerns:** a concern must not depend on the classes that include it
 - **Layers:** dependency direction and cycles
 - **Rails:** controller APIs kept out of models and services
-- **Architectures:** Rails, vanilla Rails, layered, hexagonal, clean, modular monolith, CQRS, and event-driven bundles
+- **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
+- **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
-- **Zeitwerk names:** conventional file names defining the expected constants
 - **Empty components:** directories that must stay empty, like `app/services` in vanilla Rails
 - **Suppressions:** narrow local exceptions with a reason
 
+## Checking Zeitwerk Names
+
+ArchSpec does not check Zeitwerk constant names. Zeitwerk does that itself. Add `Zeitwerk::Loader.eager_load_all` (or your loader's `eager_load`) to your test suite or CI. It raises on any file that does not define the constant its path implies, using your real inflector and ignores.
+
 ## Installation
 
 Add ArchSpec to your Gemfile:

data/lib/archspec/analyzer.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'prism'
-require 'pathname'
 
 module ArchSpec
   module Analyzer
@@ -15,7 +14,6 @@ module ArchSpec
         result = Prism.parse_file(path)
         graph.add_file(
           path: path,
-          expected_constant: expected_constant_for(path, root, definition.inflections),
           parse_errors: parse_errors_for(path, result.errors),
           suppressions: suppressions_for(result.comments)
         )
@@ -49,38 +47,6 @@ module ArchSpec
       end.select { |path| File.file?(path) }.map { |path| File.expand_path(path) }.to_set
     end
 
-    def expected_constant_for(path, root, inflections = {})
-      relative = Pathname(path).relative_path_from(Pathname(root)).to_s
-      stem =
-        case relative
-        when %r{\Aapp/[^/]+/concerns/(.+)\.rb\z}
-          Regexp.last_match(1)
-        when %r{\Aapp/[^/]+/(.+)\.rb\z}
-          Regexp.last_match(1)
-        when %r{\Alib/(.+)\.rb\z}
-          Regexp.last_match(1)
-        when %r{\A(?:packs|engines)/[^/]+/app/[^/]+/concerns/(.+)\.rb\z}
-          Regexp.last_match(1)
-        when %r{\A(?:packs|engines)/[^/]+/app/[^/]+/(.+)\.rb\z}
-          Regexp.last_match(1)
-        else
-          return nil
-        end
-
-      camelize_path(stem, inflections)
-    end
-
-    # Rails-style acronyms: inflections apply to whole path segments first,
-    # then to each snake_case word (inflect "api" => "API" fixes both api.rb
-    # and api_client.rb).
-    def camelize_path(path, inflections = {})
-      path.split('/').map do |part|
-        inflections[part] || part.split('_').map do |word|
-          inflections[word] || (word[0] ? word[0].upcase + word[1..] : word)
-        end.join
-      end.join('::')
-    end
-
     def suppressions_for(comments)
       SuppressionParser.parse(comments)
     end
@@ -175,24 +141,31 @@ module ArchSpec
         attr_accessor: %i[reader writer]
       }.freeze
 
-      def visit(graph, path, node, current_constant: nil, namespace: [])
+      def visit(graph, path, node, current_constant: nil, namespace: [], 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,
+                                            visibility: visibility, default_scope: default_scope)
         when Prism::ClassNode
           visit_class(graph, path, node, current_constant: current_constant, namespace: namespace)
         when Prism::ModuleNode
           visit_module(graph, path, node, current_constant: current_constant, namespace: namespace)
+        when Prism::SingletonClassNode
+          visit_singleton_class(graph, path, node, current_constant: current_constant, namespace: namespace,
+                                                   visibility: visibility, default_scope: default_scope)
         when Prism::DefNode
-          visit_def(graph, path, node, current_constant: current_constant, namespace: namespace)
+          visit_def(graph, path, node, current_constant: current_constant, namespace: namespace,
+                                       visibility: visibility, default_scope: default_scope)
         when Prism::CallNode
-          visit_call(graph, path, node, current_constant: current_constant, namespace: namespace)
+          visit_call(graph, path, node, current_constant: current_constant, namespace: namespace,
+                                        visibility: visibility, default_scope: default_scope)
         when Prism::ConstantPathNode, Prism::ConstantReadNode
           add_constant_reference(graph, path, node, current_constant)
         else
-          visit_children(graph, path, node, current_constant: current_constant, namespace: namespace)
+          visit_children(graph, path, node, current_constant: current_constant, namespace: namespace,
+                                            visibility: visibility, default_scope: default_scope)
         end
       end
 
@@ -229,7 +202,7 @@ module ArchSpec
           end
         end
 
-        visit(graph, path, node.body, current_constant: constant.name, namespace: constant.name.split('::'))
+        visit_constant_body(graph, path, constant, node.body, constant.name.split('::'))
       end
 
       def visit_module(graph, path, node, current_constant:, namespace:)
@@ -241,17 +214,67 @@ module ArchSpec
           location: SourceLocation.from_prism(path, node.location)
         )
 
-        visit(graph, path, node.body, current_constant: constant.name, namespace: constant.name.split('::'))
+        visit_constant_body(graph, path, constant, node.body, constant.name.split('::'))
+      end
+
+      # A +class << self+ (or +class << SomeConstant+) block defines methods on a
+      # constant's singleton, so they are class methods, and +private+ inside it
+      # 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:)
+        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)
+        else
+          visit_children(graph, path, node, current_constant: current_constant, namespace: namespace,
+                                            visibility: visibility, default_scope: default_scope)
+        end
+      end
+
+      def singleton_target(expression, current_constant)
+        return current_constant if expression.is_a?(Prism::SelfNode)
+
+        constant_reference_name(expression) if constant_node?(expression)
+      end
+
+      # Walks a class or module body in source order, tracking method visibility
+      # so +private+/+protected+ and their inline and symbol-list forms mark the
+      # methods they cover. +default_scope+ is +:class+ inside a singleton class,
+      # 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)
+        return unless body
+
+        unless body.is_a?(Prism::StatementsNode)
+          return visit(graph, path, body, current_constant: constant.name, namespace: namespace,
+                                          default_scope: default_scope)
+        end
+
+        visibility = :public
+        body.body.each do |statement|
+          if (modifier = visibility_modifier(statement))
+            visibility = apply_visibility_modifier(graph, path, constant, statement, namespace, visibility, modifier,
+                                                   default_scope)
+          else
+            visit(graph, path, statement, current_constant: constant.name, namespace: namespace,
+                                          visibility: visibility, default_scope: default_scope)
+          end
+        end
       end
 
-      def visit_def(graph, path, node, current_constant:, namespace:)
+      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|
           candidate.path == path
         end)
-          if node.receiver
-            constant.add_class_method(node.name, location: SourceLocation.from_prism(path, node.location))
+          location = SourceLocation.from_prism(path, node.location)
+          if node.receiver || default_scope == :class
+            constant.add_class_method(node.name, location: location, visibility: visibility)
           else
-            constant.add_instance_method(node.name, location: SourceLocation.from_prism(path, node.location))
+            constant.add_instance_method(node.name, location: location, visibility: visibility)
           end
         end
 
@@ -269,10 +292,10 @@ module ArchSpec
         visit_children(graph, path, node, current_constant: current_constant, namespace: namespace)
       end
 
-      def visit_call(graph, path, node, current_constant:, namespace:)
+      def visit_call(graph, path, node, current_constant:, namespace:, visibility: :public, default_scope: :instance)
         unless node.message
-          return visit_children(graph, path, node, current_constant: current_constant,
-                                                   namespace: namespace)
+          return visit_children(graph, path, node, current_constant: current_constant, namespace: namespace,
+                                                   visibility: visibility, default_scope: default_scope)
         end
 
         message = node.message.to_sym
@@ -298,7 +321,7 @@ module ArchSpec
           )
         end
 
-        record_generated_methods(graph, path, node, message, current_constant, location)
+        record_generated_methods(graph, path, node, message, current_constant, location, visibility, default_scope)
 
         if (edge_type = MIXIN_MESSAGES[message])
           constant_arguments(node).each do |constant_name|
@@ -338,7 +361,8 @@ 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,
+                                          visibility: visibility, default_scope: default_scope)
       end
 
       def add_constant_reference(graph, path, node, current_constant)
@@ -354,9 +378,62 @@ module ArchSpec
         )
       end
 
-      def visit_children(graph, path, node, current_constant:, namespace:)
+      def visit_children(graph, path, node, current_constant:, namespace:, visibility: :public, default_scope: :instance)
         node.child_nodes.compact.each do |child|
-          visit(graph, path, child, current_constant: current_constant, namespace: namespace)
+          visit(graph, path, child, current_constant: current_constant, namespace: namespace,
+                                    visibility: visibility, default_scope: default_scope)
+        end
+      end
+
+      # Maps a visibility call to [visibility, forced_scope]. A nil forced_scope
+      # means the call follows the context (instance methods in a class body,
+      # class methods inside +class << self+); +*_class_method+ always targets
+      # class methods.
+      VISIBILITY_MODIFIERS = {
+        private: [:private, nil],
+        protected: [:protected, nil],
+        public: [:public, nil],
+        private_class_method: [:private, :class],
+        public_class_method: [:public, :class]
+      }.freeze
+
+      # The [visibility, forced_scope] a bare visibility call sets, or nil when
+      # the node is not one. Only receiverless calls count, so +obj.private+ is
+      # ignored.
+      def visibility_modifier(node)
+        return unless node.is_a?(Prism::CallNode) && node.receiver.nil?
+
+        VISIBILITY_MODIFIERS[node.message&.to_sym]
+      end
+
+      # Applies a visibility call and returns the default visibility for the
+      # 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)
+        visibility, forced_scope = spec
+        scope = forced_scope || default_scope
+        arguments = node.arguments&.arguments || []
+        definitions = arguments.select { |argument| argument.is_a?(Prism::DefNode) }
+        names = arguments.select { |argument| argument.is_a?(Prism::SymbolNode) || argument.is_a?(Prism::StringNode) }
+
+        if definitions.any?
+          visit(graph, path, node, current_constant: constant.name, namespace: namespace,
+                                   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)
+          current
+        elsif forced_scope.nil?
+          visit(graph, path, node, current_constant: constant.name, namespace: namespace,
+                                   visibility: visibility, default_scope: default_scope)
+          visibility
+        else
+          visit(graph, path, node, current_constant: constant.name, namespace: namespace,
+                                   visibility: current, default_scope: default_scope)
+          current
         end
       end
 
@@ -376,25 +453,37 @@ module ArchSpec
         end || []
       end
 
-      # attr_* and unprefixed delegate calls define instance methods; without
-      # them, a class calling its own reader looks like a foreign call.
-      def record_generated_methods(graph, path, node, message, current_constant, location)
+      # attr_*, Rails attribute, and unprefixed delegate calls define methods;
+      # without them, a class calling its own reader looks like a foreign call.
+      def record_generated_methods(graph, path, node, message, current_constant, location, visibility, default_scope)
         return unless current_constant && node.receiver.nil?
-        return unless ATTR_MESSAGES.key?(message) || message == :delegate
+        return unless ATTR_MESSAGES.key?(message) || %i[attribute delegate].include?(message)
 
         constant = graph.constants_named(current_constant).find { |candidate| candidate.path == path }
         return unless constant
 
-        names = symbol_arguments(node)
+        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 = ATTR_MESSAGES.fetch(message, %i[reader])
-          constant.add_instance_method(name, location: location) if kinds.include?(:reader)
-          constant.add_instance_method(:"#{name}=", location: location) if kinds.include?(:writer)
+          kinds = message == :attribute ? %i[reader writer] : ATTR_MESSAGES.fetch(message, %i[reader])
+          constant.public_send(adder, name, location: location, visibility: visibility) if kinds.include?(:reader)
+          constant.public_send(adder, :"#{name}=", location: location, visibility: visibility) if kinds.include?(:writer)
         end
       end
 
+      # Active Record and Active Model take one attribute name followed by an
+      # optional type, which may itself be a symbol. CurrentAttributes instead
+      # accepts any number of names, so retain every literal name there.
+      def generated_method_names(constant, node, message)
+        names = symbol_arguments(node)
+        return names unless message == :attribute
+        return names if constant.superclass == 'ActiveSupport::CurrentAttributes'
+
+        names.first(1)
+      end
+
       def symbol_arguments(node)
         node.arguments&.arguments&.filter_map do |argument|
           argument.unescaped.to_sym if argument.is_a?(Prism::SymbolNode) || argument.is_a?(Prism::StringNode)

data/lib/archspec/architectures.rb

@@ -11,30 +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. Keeps
-  #   controller APIs out of models and services. Options: +components:+,
+  # - +:rails+ (aliases +:rails_mvc+, +:rails_way+): conventional MVC that keeps
+  #   controller APIs out of models and services. Options +components:+,
   #   +controller_api:+, +share_helpers:+.
-  # +:rails_strict+:: +:rails+ plus Zeitwerk name checks, a cycle check, and a
-  #   concern independence check. Options add +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:+,
+  # - +: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:+,
+  # - +: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:
+  # - +: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:+
+  # - +: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:+,
+  # - +: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:+.
+  # - +:event_driven+ (alias +:rails_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.
   module Architectures
@@ -149,6 +152,8 @@ module ArchSpec
         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
@@ -159,7 +164,7 @@ module ArchSpec
       define_components(dsl, components)
 
       forbidden = share_helpers ? %i[controllers] : %i[controllers helpers]
-      proxy_for(dsl, :controllers).can_use(*components.keys & %i[models services helpers mailers jobs])
+      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)
 
@@ -172,8 +177,7 @@ module ArchSpec
     def rails_strict(dsl, components:, controller_api: CONTROLLER_METHODS, share_helpers: false, concerns: DEFAULT_CONCERNS)
       components = normalize_map(components)
       rails_mvc(dsl, components: components, controller_api: controller_api, share_helpers: share_helpers)
-      dsl.verify_zeitwerk_names!
-      dsl.no_cycles!(among: components.keys)
+      dsl.no_cycles(among: components.keys)
       independent_concerns(dsl, concerns)
     end
 
@@ -195,10 +199,10 @@ module ArchSpec
 
       names.each_with_index do |name, index|
         allowed = names[(index + 1)..] || []
-        proxy_for(dsl, name).can_use(*allowed)
+        proxy_for(dsl, name).can_only_use(*allowed)
       end
 
-      dsl.no_cycles!(among: names)
+      dsl.no_cycles(among: names)
     end
 
     def hexagonal(dsl, application:, domain:, ports:, adapters:)
@@ -210,11 +214,11 @@ module ArchSpec
       )
       define_components(dsl, roles)
 
-      proxy_for(dsl, :application).can_use :domain, :ports
+      proxy_for(dsl, :application).can_only_use :domain, :ports
       proxy_for(dsl, :domain).cannot_use :adapters
       proxy_for(dsl, :ports).cannot_use :adapters
-      proxy_for(dsl, :adapters).can_use :application, :domain, :ports
-      dsl.no_cycles!(among: roles.keys)
+      proxy_for(dsl, :adapters).can_only_use :application, :domain, :ports
+      dsl.no_cycles(among: roles.keys)
     end
 
     def clean(dsl, frameworks:, interface_adapters:, use_cases:, entities:)
@@ -235,13 +239,13 @@ module ArchSpec
 
       components.each_key do |name|
         allowed = Array(allow[name] || allow[name.to_s])
-        proxy_for(dsl, name).can_use(*allowed)
+        proxy_for(dsl, name).can_only_use(*allowed)
 
         patterns = Array(public[name] || public[name.to_s])
         proxy_for(dsl, name).public_api(*patterns) if patterns.any?
       end
 
-      dsl.no_cycles!(among: components.keys)
+      dsl.no_cycles(among: components.keys)
     end
 
     def cqrs(dsl, commands:, queries:, read_models: nil, mutating_methods: MUTATING_METHODS)
@@ -252,7 +256,7 @@ module ArchSpec
       proxy_for(dsl, :commands).cannot_use :queries
       proxy_for(dsl, :queries).cannot_use :commands
       proxy_for(dsl, :queries).cannot_call(*mutating_methods)
-      dsl.no_cycles!(among: components.keys)
+      dsl.no_cycles(among: components.keys)
     end
 
     def event_driven(dsl, events:, publishers:, subscribers:)
@@ -260,13 +264,36 @@ module ArchSpec
       define_components(dsl, roles)
 
       proxy_for(dsl, :events).cannot_use :publishers, :subscribers
-      proxy_for(dsl, :publishers).can_use :events
-      proxy_for(dsl, :subscribers).can_use :events
-      dsl.no_cycles!(among: roles.keys)
+      proxy_for(dsl, :publishers).can_only_use :events
+      proxy_for(dsl, :subscribers).can_only_use :events
+      dsl.no_cycles(among: roles.keys)
+    end
+
+    # Applies the generic Ruby naming idioms project-wide: no +get_+/+set_+
+    # accessors and no +is_+ predicate prefix. Adds no components, so it composes
+    # with any other architecture. Project-specific conventions (the +with_x+ /
+    # +without_x+ pairing, the +supports_*?+ ban) stay opt-in through the
+    # +method_names.matching(...)+ primitives.
+    def ruby_conventions(dsl)
+      %i[instance class].each do |scope|
+        forbid_name(dsl, /\A(get|set)_/, 'use attr_ readers and writers or plain names, not get_/set_', scope: scope)
+        forbid_name(dsl, /\Ais_/, 'name predicates with a trailing ? and no is_ prefix (has_ is fine)', scope: scope)
+      end
     end
 
     private
 
+    def forbid_name(dsl, regex, reason, scope:)
+      dsl.rule(
+        Rules::NamingRule.new(
+          source: nil,
+          selector: Rules::Naming::NameSelector.new(regex),
+          constraint: Rules::Naming::Forbidden.new(because: reason),
+          scope: scope
+        )
+      )
+    end
+
     def with_defaults(defaults, options)
       defaults.merge(options)
     end
@@ -302,6 +329,8 @@ module ArchSpec
       return unless pattern
 
       dsl.component(:concerns, in: pattern).cannot_reference_includers
+      # Controllers carry an allowlist, so let them include concerns too.
+      proxy_for(dsl, :controllers).can_only_use(:concerns)
     end
   end
 end

data/lib/archspec/cli.rb

@@ -107,7 +107,7 @@ module ArchSpec
 
       definition, root = load_definition(options[:config])
       graph = Analyzer.analyze(definition, root: root)
-      explain_subject(output, graph, subject)
+      Formatters::Explanation.print(output, graph: graph, subject: subject)
       0
     end
 
@@ -155,78 +155,6 @@ module ArchSpec
       end
     end
 
-    def explain_subject(output, graph, subject)
-      path = File.expand_path(subject, graph.root)
-
-      if graph.files.key?(path)
-        file = graph.files.fetch(path)
-        output.puts file.relative_path
-        output.puts "  expected constant: #{file.expected_constant || '(none)'}"
-        output.puts "  defined constants: #{graph.constants_for_path(path).map(&:name).join(', ')}"
-        output_parse_errors(output, file)
-        output_component_reasons(output, graph.component_assignment_reasons_for_path(path))
-        output_suppressions(output, file)
-        output.puts '  outgoing facts:'
-
-        graph.edges.select { |edge| edge.from_path == path }.each do |edge|
-          output.puts "    #{edge.type} #{edge.to} at #{edge.location.line}:#{edge.location.column}"
-        end
-      else
-        constants = graph.constants_named(subject)
-        raise Error, "No file or constant found for #{subject.inspect}" if constants.empty?
-
-        constants.each do |constant|
-          output.puts constant.name
-          output.puts "  kind: #{constant.kind}"
-          output.puts "  file: #{constant.location.relative_path(graph.root)}:#{constant.location.line}"
-          output_component_reasons(output, graph.component_assignment_reasons_for_constant(constant.name))
-          output.puts "  superclass: #{constant.superclass || '(none)'}"
-          output.puts "  instance methods: #{constant.instance_methods.to_a.sort.join(', ')}"
-          output.puts "  class methods: #{constant.class_methods.to_a.sort.join(', ')}"
-        end
-      end
-    end
-
-    def output_component_reasons(output, assignments)
-      if assignments.empty?
-        output.puts '  components: (none)'
-        return
-      end
-
-      output.puts '  components:'
-      assignments.sort_by { |name, _reasons| name.to_s }.each do |name, reasons|
-        output.puts "    #{name}: #{reasons.empty? ? '(no recorded reason)' : reasons.join('; ')}"
-      end
-    end
-
-    def output_suppressions(output, file)
-      return if file.suppressions.empty?
-
-      output.puts '  suppressions:'
-      file.suppressions.each do |suppression|
-        line_range =
-          if suppression.end_line == Float::INFINITY
-            "#{suppression.start_line}-EOF"
-          elsif suppression.start_line == suppression.end_line
-            suppression.start_line
-          else
-            "#{suppression.start_line}-#{suppression.end_line}"
-          end
-        rule = suppression.rule || '*'
-        reason = suppression.reason ? " -- #{suppression.reason}" : ''
-        output.puts "    #{rule} on line #{line_range}#{reason}"
-      end
-    end
-
-    def output_parse_errors(output, file)
-      return if file.parse_errors.empty?
-
-      output.puts '  parse errors:'
-      file.parse_errors.each do |parse_error|
-        output.puts "    #{parse_error.location.line}:#{parse_error.location.column} #{parse_error.message}"
-      end
-    end
-
     def usage
       <<~TEXT
         Usage:

data/lib/archspec/definition.rb

@@ -22,7 +22,7 @@ module ArchSpec
     ].freeze
 
     attr_accessor :name, :root_path, :todo_path, :base_dir
-    attr_reader :source_patterns, :ignore_patterns, :component_specs, :rules, :inflections
+    attr_reader :source_patterns, :ignore_patterns, :component_specs, :rules
 
     def initialize(name = nil)
       @name = name
@@ -33,11 +33,6 @@ module ArchSpec
       @ignore_patterns = DEFAULT_IGNORE_PATTERNS.dup
       @component_specs = {}
       @rules = []
-      @inflections = {}
-    end
-
-    def add_inflections(map)
-      @inflections.merge!(map.to_h.transform_keys(&:to_s).transform_values(&:to_s))
     end
 
     def add_source_patterns(patterns)