archspec 0.4.0 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25ea714cd768976e860df4f0dbaa9ff477e381096f95b98787a0a645fc0cd776
-  data.tar.gz: 527621e2bb18514433cf26ede594f2cafa2699d0d95e2d3fa4d9e8b9e4aac354
+  metadata.gz: 24d73489bf5bdd8a56deffac28bbcd11aab271db3281afcce4e0aa21c93de28b
+  data.tar.gz: 9c6303777aededa6ce4f7780943a5a7257b33cbef978e50369296d1a4d0b0a8f
 SHA512:
-  metadata.gz: f9c83e97692a44bbf72391593e695bc4c8a7859d148508f4cb8cf490a55e51a8de98d0df8ab0d37bf8bf13fcdb3e4707f9325850a39b9a33ea678a0d0aa7f3b2
-  data.tar.gz: ec19d8b85144cee92cd7bd2c968d848aef39feccdda87b56849dab7ac706543fec8041bee524ab0c5532193b423442f6ef3eec00d6d52f6301ec3e960b5cf1b8
+  metadata.gz: 1c69995b8ce63a81ed15be9233a4f6199deb5faa710a0853613150d464229b653a4d7e122b032ba417e6048b7cf1285ee6a9272ff0217071b8cd727ed02add63
+  data.tar.gz: 8de9a4380f15a1c8f197980207ba20939bfac7a9a7a61e9e297eb57b517c491eb9017ab91c22057b3d88536c609bac385a6fddc311cb76b8915b66c64c5dc9dc

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:
@@ -160,7 +164,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
 
@@ -178,10 +193,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

@@ -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
@@ -115,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])
@@ -175,36 +143,49 @@ 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: [], 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,
+                                                   nesting: nesting, 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,
+                                       nesting: nesting, 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,
+                                        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
@@ -217,41 +198,100 @@ 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(graph, path, node.body, current_constant: constant.name, namespace: 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(graph, path, node.body, current_constant: constant.name, namespace: 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
+      # 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:, 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, nesting: nesting, default_scope: :class)
+        else
+          visit_children(graph, path, node, current_constant: nil, namespace: namespace,
+                                            nesting: nesting, visibility: visibility, default_scope: :class)
+        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, nesting:, default_scope: :instance)
+        return unless body
+
+        unless body.is_a?(Prism::StatementsNode)
+          return visit(graph, path, body, current_constant: constant.name, namespace: namespace, nesting: nesting,
+                                          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, nesting)
+          else
+            visit(graph, path, statement, current_constant: constant.name, namespace: namespace,
+                                          nesting: nesting, visibility: visibility, default_scope: default_scope)
+          end
+        end
       end
 
-      def visit_def(graph, path, node, current_constant:, namespace:)
-        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)
-          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
 
@@ -266,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 visit_call(graph, path, node, current_constant:, namespace:)
+      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:, nesting:, 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,
+                                                   nesting: nesting, visibility: visibility,
+                                                   default_scope: default_scope)
         end
 
         message = node.message.to_sym
@@ -298,7 +349,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|
@@ -313,7 +364,8 @@ module ArchSpec
               from_path: path,
               from_constant: current_constant,
               to: constant_name,
-              location: location
+              location: location,
+              lexical_nesting: nesting
             )
           end
         end
@@ -338,10 +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
 
@@ -350,13 +403,69 @@ 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:)
+      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)
+          visit(graph, path, child, current_constant: current_constant, namespace: namespace,
+                                    nesting: nesting, 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, nesting)
+        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,
+                                   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,
+                                   nesting: nesting, visibility: current, default_scope: default_scope)
+          current
+        elsif arguments.empty? && forced_scope.nil?
+          visit(graph, path, node, current_constant: constant.name, namespace: namespace,
+                                   nesting: nesting, visibility: visibility, default_scope: default_scope)
+          visibility
+        else
+          visit(graph, path, node, current_constant: constant.name, namespace: namespace,
+                                   nesting: nesting, visibility: forced_scope.nil? ? visibility : current,
+                                   default_scope: default_scope)
+          current
         end
       end
 
@@ -376,36 +485,51 @@ 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
+        return if message == :delegate && truthy_keyword_argument?(node, :prefix)
 
-        names = symbol_arguments(node)
-        return if message == :delegate && keyword_argument?(node, :prefix)
-
+        names = generated_method_names(constant, node, message)
+        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
+
+        superclass = constant.superclass.to_s.sub(/\A::/, '')
+        return names if 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)
+      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
@@ -423,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
 
@@ -431,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
@@ -443,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