archspec 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 583efdae4f510098da5807cb0d7f509892851f5f26766e705dd6354c1e6b1748
-  data.tar.gz: 5523396837663f507b4b474bcc1fd2a803f59f60910047b1dc9e910b1b46fde5
+  metadata.gz: b5ac200fd85432184c5043ce7540e45cb3bcc0013a37ecd77d07c34aca51bfd8
+  data.tar.gz: 5d3e6b1558c796c6784505b9637b5fa58fb0da9d7b85fd30e71b7a26689da471
 SHA512:
-  metadata.gz: 4761e204b83d63afcaa16c823aa47ba6c39653990d30c30dadd94e0698ffc0dc8566cb0740125c9948c630ab983183b5907828691a55d36a66f314df5f35ea8b
-  data.tar.gz: d5e8219c53e25cf060e78d74f8e23c75d7fc6204451ee1faf4a7f1ecac8caf53ce02b27d13bb194ca83810d7874e720385ec9daa31508d6840f9bb068c00ba88
+  metadata.gz: 71b4a46c3423cd47b0317559aea01038431b29f0fa8cbd1f72a403cf5e4a3bb64bf7649412752110d7a49e5e59abbc387dd3e3ec1251a11a1f7219d6fdd05877
+  data.tar.gz: 28f23d54d05d3d16663a5c728aa55846b45f240913cdada2954672059d9193e895c7e651434351bef50f30731ad08e8b5660680e17d97b294846745f769e7f75

data/README.md

@@ -67,7 +67,7 @@ Keep a hexagonal core away from adapters:
 architecture :hexagonal
 ```
 
-Check a modular monolith:
+Check a modular monolith, and make packs go through a public API:
 
 ```ruby
 architecture :modular_monolith,
@@ -79,6 +79,9 @@ architecture :modular_monolith,
   allow: {
     billing: %i[shared],
     catalog: %i[shared]
+  },
+  public: {
+    billing: "packs/billing/app/public/**/*.rb"
   }
 ```
 
@@ -89,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
@@ -106,16 +109,22 @@ architecture :cqrs,
 
 ## What It Checks
 
-- **Dependencies:** allowed and forbidden references between components
+- **Dependencies:** allowed and forbidden references between components, in both directions
+- **Privacy:** other components must go through a component's public API
+- **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:
@@ -150,7 +159,7 @@ bundle exec archspec check
 bundle exec archspec init
 bundle exec archspec check
 bundle exec archspec check --format json
-bundle exec archspec check --update-baseline
+bundle exec archspec check --update-todo
 bundle exec archspec explain app/models/user.rb
 ```
 
@@ -161,12 +170,15 @@ facts ArchSpec found.
 
 Generated code should pass the same architecture checks as hand-written code.
 
-After an AI-assisted change:
+After an AI-assisted change, check the whole project, or just the files that changed:
 
 ```sh
 bundle exec archspec check
+bundle exec archspec check app/models/user.rb app/services
 ```
 
+Passing paths still analyzes the project so dependencies resolve, but reports only violations in those paths. This keeps the loop tight after each edit.
+
 If it fails, read the evidence before changing the spec:
 
 ```text
@@ -179,16 +191,17 @@ If it fails, read the evidence before changing the spec:
 Most failures should be fixed in the generated code. Update the spec only when
 the architecture decision itself has changed.
 
-## Baselines and Suppressions
+## Todo and Suppressions
 
-Use a baseline when adopting ArchSpec in an existing app:
+Use a todo file when adopting ArchSpec in an existing app. It records the current
+violations so they stop failing the build, leaving a list to burn down:
 
 ```ruby
-baseline ".archspec_todo.yml"
+todo "archspec_todo.yml"
 ```
 
 ```sh
-bundle exec archspec check --update-baseline
+bundle exec archspec check --update-todo
 ```
 
 Use local suppressions for deliberate exceptions:
@@ -210,6 +223,12 @@ This repository checks its own architecture:
 bundle exec rake architecture
 ```
 
+It also runs against pinned checkouts of large real-world Rails apps to catch crashes and false positives before they ship:
+
+```sh
+bundle exec rake torture
+```
+
 ## License
 
 Released under the MIT License.

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),
           parse_errors: parse_errors_for(path, result.errors),
           suppressions: suppressions_for(result.comments)
         )
@@ -49,33 +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)
-      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)
-    end
-
-    def camelize_path(path)
-      path.split('/').map do |part|
-        part.split('_').map { |word| word[0] ? word[0].upcase + word[1..] : word }.join
-      end.join('::')
-    end
-
     def suppressions_for(comments)
       SuppressionParser.parse(comments)
     end
@@ -164,24 +135,37 @@ module ArchSpec
         extend: :extends
       }.freeze
 
-      def visit(graph, path, node, current_constant: nil, namespace: [])
+      ATTR_MESSAGES = {
+        attr_reader: %i[reader],
+        attr_writer: %i[writer],
+        attr_accessor: %i[reader writer]
+      }.freeze
+
+      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
 
@@ -197,18 +181,28 @@ module ArchSpec
         )
 
         if node.superclass
-          superclass = constant_reference_name(node.superclass)
-          constant.superclass = superclass
-          graph.add_edge(
-            type: :inherits_from,
-            from_path: path,
-            from_constant: constant.name,
-            to: superclass,
-            location: SourceLocation.from_prism(path, node.superclass.location)
-          )
+          superclass = constant_reference_name(node.superclass) if constant_node?(node.superclass)
+
+          if superclass
+            constant.superclass = superclass
+            graph.add_edge(
+              type: :inherits_from,
+              from_path: path,
+              from_constant: constant.name,
+              to: superclass,
+              location: SourceLocation.from_prism(path, node.superclass.location)
+            )
+          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('::'))
+          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:)
@@ -220,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
 
-      def visit_def(graph, path, node, current_constant:, namespace:)
+      # 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:, 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
 
@@ -248,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
@@ -277,6 +321,8 @@ module ArchSpec
           )
         end
 
+        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|
             if current_constant && (constant = graph.constants_named(current_constant).find do |candidate|
@@ -300,7 +346,8 @@ module ArchSpec
           from_path: path,
           from_constant: current_constant,
           to: message,
-          location: location
+          location: location,
+          receiver: receiver_kind(node)
         )
 
         if DYNAMIC_MESSAGES.include?(message)
@@ -314,22 +361,79 @@ 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)
+        name = constant_reference_name(node)
+        return unless name
+
         graph.add_edge(
           type: :references_constant,
           from_path: path,
           from_constant: current_constant,
-          to: constant_reference_name(node),
+          to: name,
           location: SourceLocation.from_prism(path, node.location)
         )
       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
 
@@ -349,27 +453,88 @@ module ArchSpec
         end || []
       end
 
+      # 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) || %i[attribute delegate].include?(message)
+
+        constant = graph.constants_named(current_constant).find { |candidate| candidate.path == path }
+        return unless constant
+
+        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])
+          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)
+        end || []
+      end
+
+      def 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
+          end
+        end
+      end
+
+      def receiver_kind(node)
+        receiver = node.receiver
+        return :none if receiver.nil? || receiver.is_a?(Prism::SelfNode)
+        return :constant if constant_node?(receiver)
+
+        :other
+      end
+
       def instantiates_and_invokes(node)
         receiver = node.receiver
         return unless receiver.is_a?(Prism::CallNode) && receiver.message&.to_sym == :new
 
-        name = constant_node?(receiver.receiver) ? constant_reference_name(receiver.receiver) : receiver.receiver&.slice
+        receiver_node = receiver.receiver
+        name = (constant_reference_name(receiver_node) if constant_node?(receiver_node)) || receiver_node&.slice
         "#{name}##{node.message}"
       end
 
+      # class Users::RolesController inside module Admin defines
+      # 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 == :""
 
-        if absolute || raw.include?('::') || namespace.empty?
+        if absolute || namespace.empty?
           raw
         else
           "#{namespace.join('::')}::#{raw}"
         end
       end
 
+      # 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
+        nil
       end
 
       def constant_node?(node)