archspec 1.0.1 → 1.1.0.rc2

data/lib/archspec/rules/naming_rules.rb

@@ -74,31 +74,22 @@ module ArchSpec
 
       # Forbids any selected method from existing. Rule id +naming.forbidden+.
       class Forbidden
-        def initialize(because: nil)
-          @because = because
-        end
-
         def id
           'naming.forbidden'
         end
 
         def diagnostics(selected, rule, _graph)
           selected.map do |definition, _match|
+            evidence = "#{definition.owner} defines #{definition.scope} method #{definition.name} " \
+                       "(#{rule.selector.describe})"
             Diagnostic.new(
               rule: id,
-              message: message_for(definition),
+              message: "#{definition.owner} must not define ##{definition.name}",
               location: definition.location,
-              evidence: "#{definition.owner} defines #{definition.scope} method #{definition.name} (#{rule.selector.describe})"
+              evidence: evidence
             )
           end
         end
-
-        private
-
-        def message_for(definition)
-          base = "#{definition.owner} must not define ##{definition.name}"
-          @because ? "#{base}: #{@because}" : base
-        end
       end
 
       # Requires each selected method to have a sibling named by a template, in
@@ -106,7 +97,7 @@ module ArchSpec
       # interpolates the selector's named captures, as in
       # <tt>requires("without_%{base}")</tt>. Rule id +naming.requires+.
       class Requires
-        def initialize(template, on: nil, scope: :instance, because: nil)
+        def initialize(template, on: nil, scope: :instance)
           unless NamingRule::VALID_SCOPES.include?(scope)
             raise Error, "requires scope: must be :instance or :class, got #{scope.inspect}"
           end
@@ -115,7 +106,6 @@ module ArchSpec
           @template = template
           @on = on
           @target_scope = scope
-          @because = because
         end
 
         def id
@@ -163,8 +153,7 @@ module ArchSpec
             else
               "a matching ##{sibling}"
             end
-          base = "#{definition.owner}##{definition.name} requires #{clause}"
-          @because ? "#{base}: #{@because}" : base
+          "#{definition.owner}##{definition.name} requires #{clause}"
         end
       end
 
@@ -190,17 +179,17 @@ module ArchSpec
         end
 
         def forbidden(except: [], because: nil)
-          add(Forbidden.new(because: because), except)
+          add(Forbidden.new, except, because)
         end
 
         def requires(template, on: nil, scope: :instance, except: [], because: nil)
           validate_template!(template)
-          add(Requires.new(template, on: component_name(on), scope: scope, because: because), except)
+          add(Requires.new(template, on: component_name(on), scope: scope), except, because)
         end
 
         private
 
-        def add(constraint, except)
+        def add(constraint, except, because)
           rule = NamingRule.new(
             source: @component.name,
             selector: @selector,
@@ -208,7 +197,7 @@ module ArchSpec
             scope: @scope,
             except: except
           )
-          @component.definition.add_rule(rule)
+          @component.definition.add_rule(Rules.with_reason(rule, because))
           @component
         end
 
@@ -224,7 +213,7 @@ module ArchSpec
         end
 
         def validate_template!(template)
-          return unless template.is_a?(String)
+          return unless template.is_a?(String) && template.include?('%')
 
           captures = @selector.regex.names.to_h { |name| [name.to_sym, name] }
           template % captures

data/lib/archspec/rules/protocol_rules.rb

@@ -8,13 +8,13 @@ module ArchSpec
       attr_reader :source, :method_names, :receiver
 
       def initialize(source, methods, receiver: :any)
-        unless %i[any none].include?(receiver)
-          raise Error, "cannot_call receiver: must be :any or :none, got #{receiver.inspect}"
+        unless %i[any none].include?(receiver) || receiver.is_a?(String)
+          raise Error, "cannot_call receiver: must be :any, :none or a constant name, got #{receiver.inspect}"
         end
 
         @source = source.to_sym
         @method_names = Array(methods).flatten.map(&:to_sym)
-        @receiver = receiver
+        @receiver = receiver.is_a?(String) ? receiver.sub(/\A::/, '') : receiver
       end
 
       def merge_key
@@ -33,22 +33,42 @@ module ArchSpec
       def evaluate(graph)
         graph.edges.filter_map do |edge|
           next unless edge.type == :calls_named_method
-          next unless method_names.include?(edge.to.to_sym)
+          forbidden = forbidden_name(edge)
+          next unless forbidden
           next if receiver == :none && edge.receiver != :none
+          next if receiver.is_a?(String) && !receiver_matches?(graph, edge)
           next unless graph.source_components_for(edge).include?(source)
           next if own_method_call?(graph, edge)
 
           Diagnostic.new(
             rule: id,
-            message: "#{source} must not call ##{edge.to}",
+            message: "#{source} must not call ##{forbidden}",
             location: edge.location,
-            evidence: "#{graph.edge_source_name(edge)} calls #{edge.to}"
+            evidence: evidence_for(graph, edge)
           )
         end
       end
 
       private
 
+      def forbidden_name(edge)
+        return edge.to.to_sym if method_names.include?(edge.to.to_sym)
+        return edge.resolved_method if edge.resolved_method && method_names.include?(edge.resolved_method)
+      end
+
+      def receiver_matches?(graph, edge)
+        return false unless edge.resolved_receiver
+        return true if edge.resolved_receiver == receiver
+
+        graph.ancestor_names(edge.resolved_receiver, scope: edge.receiver_scope || :instance).first.include?(receiver)
+      end
+
+      def evidence_for(graph, edge)
+        evidence = "#{graph.edge_source_name(edge)} calls #{edge.to}"
+        evidence = "#{evidence} (alias of #{edge.resolved_method})" if edge.resolved_method
+        receiver.is_a?(String) ? "#{evidence} on #{edge.resolved_receiver}" : evidence
+      end
+
       # A receiverless call to a method the class itself defines (directly,
       # inherited, or via attr_*/attribute/delegate) is a call to its own API.
       def own_method_call?(graph, edge)
@@ -63,15 +83,23 @@ module ArchSpec
     # component that do not implement the method, counting inherited and
     # mixed-in methods.
     class MustImplementRule
-      attr_reader :source, :method_name
+      attr_reader :source, :method_name, :scope, :arity, :keywords
+
+      def initialize(source, method_name, scope: :instance, arity: nil, keywords: nil)
+        ProtocolEvidence.validate_scope!(scope, for_rule: 'must_implement')
+        if arity && (!arity.is_a?(Integer) || arity.negative?)
+          raise Error, "must_implement arity: must be a non-negative Integer, got #{arity.inspect}"
+        end
 
-      def initialize(source, method_name)
         @source = source.to_sym
         @method_name = method_name.to_sym
+        @scope = scope
+        @arity = arity
+        @keywords = Array(keywords).compact.map(&:to_sym).to_set
       end
 
       def merge_key
-        [self.class, source, method_name]
+        [self.class, source, method_name, scope, arity, keywords]
       end
 
       def id
@@ -80,15 +108,16 @@ module ArchSpec
 
       def evaluate(graph)
         constants_for(graph).filter_map do |constant|
-          methods, unresolved = graph.effective_instance_methods(constant.name)
-          next if methods.include?(method_name)
+          definitions, unresolved = graph.effective_method_definitions(constant.name, scope)
+          implementations = definitions.select { |definition| definition.name == method_name }
+          next if requirement_met?(implementations)
 
           Diagnostic.new(
             rule: id,
-            message: "#{constant.name} must implement ##{method_name}",
+            message: "#{constant.name} must implement #{method_label}#{requirement_clause}",
             location: constant.location,
-            evidence: ProtocolEvidence.for(constant, methods, unresolved),
-            confidence: unresolved.empty? ? :high : :medium
+            evidence: evidence_for(constant, definitions, implementations, unresolved),
+            confidence: unresolved.empty? && signature_known?(implementations) ? :high : :medium
           )
         end
       end
@@ -98,23 +127,73 @@ module ArchSpec
       def constants_for(graph)
         ProtocolEvidence.constants_for(graph, source)
       end
+
+      def requirement_met?(implementations)
+        return false if implementations.empty?
+        return true unless signature_required?
+
+        implementations.any? do |definition|
+          definition.signatures.any? do |signature|
+            (arity.nil? || signature.accepts_arity?(arity)) && signature.accepts_keywords?(keywords)
+          end
+        end
+      end
+
+      def signature_required?
+        !arity.nil? || keywords.any?
+      end
+
+      def signature_known?(implementations)
+        !signature_required? || implementations.any? { |definition| definition.signatures.any? }
+      end
+
+      def method_label
+        "#{scope == :class ? '.' : '#'}#{method_name}"
+      end
+
+      def requirement_clause
+        requirements = []
+        requirements << "#{arity} positional #{arity == 1 ? 'argument' : 'arguments'}" if arity
+        requirements << "keywords #{keywords.map { |name| "#{name}:" }.sort.join(', ')}" if keywords.any?
+        requirements.empty? ? '' : " accepting #{requirements.join(' and ')}"
+      end
+
+      def evidence_for(constant, definitions, implementations, unresolved)
+        if implementations.empty?
+          return ProtocolEvidence.for(constant, definitions.map(&:name).to_set, unresolved, scope: scope)
+        end
+
+        signatures = implementations.flat_map(&:signatures)
+        detail =
+          if signatures.empty?
+            'has no recorded signature'
+          else
+            "accepts #{signatures.map(&:describe).uniq.join(' or ')}"
+          end
+        evidence = "#{constant.name} #{method_label} #{detail}"
+        return evidence if unresolved.empty?
+
+        "#{evidence}; unresolved ancestors: #{unresolved.to_a.sort.join(', ')}"
+      end
     end
 
     # Backs ArchSpec::DSL::ComponentProxy#must_implement_one_of. Flags classes
     # that implement none of the named methods.
     class MustImplementOneOfRule
-      attr_reader :source, :method_names
+      attr_reader :source, :method_names, :scope
 
-      def initialize(source, method_names)
+      def initialize(source, method_names, scope: :instance)
+        ProtocolEvidence.validate_scope!(scope, for_rule: 'must_implement_one_of')
         @source = source.to_sym
         names = Array(method_names).flatten.compact
         raise Error, 'must_implement_one_of requires at least one method' if names.empty?
 
         @method_names = names.map(&:to_sym)
+        @scope = scope
       end
 
       def merge_key
-        [self.class, source]
+        [self.class, source, scope]
       end
 
       def merge!(other)
@@ -128,14 +207,21 @@ module ArchSpec
 
       def evaluate(graph)
         constants_for(graph).filter_map do |constant|
-          methods, unresolved = graph.effective_instance_methods(constant.name)
+          methods, unresolved =
+            if scope == :class
+              graph.effective_class_methods(constant.name)
+            else
+              graph.effective_instance_methods(constant.name)
+            end
           next if method_names.any? { |method_name| methods.include?(method_name) }
 
+          sigil = scope == :class ? '.' : '#'
+          choices = method_names.map { |name| "#{sigil}#{name}" }.join(', ')
           Diagnostic.new(
             rule: id,
-            message: "#{constant.name} must implement one of #{method_names.map { |name| "##{name}" }.join(', ')}",
+            message: "#{constant.name} must implement one of #{choices}",
             location: constant.location,
-            evidence: ProtocolEvidence.for(constant, methods, unresolved),
+            evidence: ProtocolEvidence.for(constant, methods, unresolved, scope: scope),
             confidence: unresolved.empty? ? :high : :medium
           )
         end
@@ -153,6 +239,14 @@ module ArchSpec
     module ProtocolEvidence
       module_function
 
+      VALID_SCOPES = %i[instance class].freeze
+
+      def validate_scope!(scope, for_rule:)
+        return if VALID_SCOPES.include?(scope)
+
+        raise Error, "#{for_rule} scope: must be :instance or :class, got #{scope.inspect}"
+      end
+
       def constants_for(graph, source)
         component = graph.components[source]
         return [] unless component
@@ -160,8 +254,9 @@ module ArchSpec
         graph.constants_for_component(source).select(&:class?).uniq(&:name)
       end
 
-      def for(constant, methods, unresolved)
-        evidence = "#{constant.name} methods: #{methods.empty? ? '(none)' : methods.to_a.sort.join(', ')}"
+      def for(constant, methods, unresolved, scope: :instance)
+        label = scope == :class ? 'class methods' : 'methods'
+        evidence = "#{constant.name} #{label}: #{methods.empty? ? '(none)' : methods.to_a.sort.join(', ')}"
         return evidence if unresolved.empty?
 
         "#{evidence}; unresolved ancestors: #{unresolved.to_a.sort.join(', ')}"

data/lib/archspec/rules/reasoned.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  module Rules
+    # Attaches a human reason to any rule without coupling that metadata to the
+    # rule's implementation or to diagnostic fingerprints.
+    module Reasoned
+      attr_reader :archspec_because
+
+      def archspec_because=(reason)
+        return unless reason
+
+        reason = reason.to_s.strip
+        raise Error, 'because: must not be empty' if reason.empty?
+        if archspec_because && archspec_because != reason
+          raise Error, "the same rule cannot have two reasons: #{archspec_because.inspect} and #{reason.inspect}"
+        end
+
+        @archspec_because = reason
+      end
+
+      def evaluate(graph)
+        super.map { |diagnostic| diagnostic.with_reason(archspec_because) }
+      end
+    end
+
+    module_function
+
+    def with_reason(rule, because)
+      return rule unless because
+
+      rule.extend(Reasoned) unless rule.is_a?(Reasoned)
+      rule.archspec_because = because
+      rule
+    end
+  end
+end

data/lib/archspec/source_location.rb

@@ -2,10 +2,8 @@
 
 require 'pathname'
 
-require_relative 'value_object'
-
 module ArchSpec
-  SourceLocation = ValueObject.define(:path, :line, :column, :end_line, :end_column) do
+  SourceLocation = Data.define(:path, :line, :column, :end_line, :end_column) do
     def self.from_prism(path, location)
       new(path, location.start_line, location.start_column + 1, location.end_line, location.end_column + 1)
     end

data/lib/archspec/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ArchSpec
-  VERSION = '1.0.1'
+  VERSION = '1.1.0.rc2'
 end

data/lib/archspec.rb

@@ -2,7 +2,6 @@
 
 require_relative 'archspec/error'
 require_relative 'archspec/version'
-require_relative 'archspec/value_object'
 require_relative 'archspec/source_location'
 require_relative 'archspec/diagnostic'
 require_relative 'archspec/component_spec'
@@ -10,9 +9,11 @@ require_relative 'archspec/model'
 require_relative 'archspec/definition'
 require_relative 'archspec/todo'
 require_relative 'archspec/dsl'
+require_relative 'archspec/rubydex_index'
 require_relative 'archspec/analyzer'
 require_relative 'archspec/evaluator'
 require_relative 'archspec/architectures'
+require_relative 'archspec/rules/reasoned'
 require_relative 'archspec/rules/component_rules'
 require_relative 'archspec/rules/concern_rules'
 require_relative 'archspec/rules/dependency_rules'
@@ -30,7 +31,8 @@ require_relative 'archspec/cli'
 #
 # You describe components, dependencies, and boundaries in an +Archspec.rb+
 # file written in the ArchSpec::DSL, then run <tt>archspec check</tt> to verify
-# every change. ArchSpec reads Ruby source with Prism and never boots the app.
+# every change. ArchSpec indexes Ruby source with Rubydex, uses Prism for a
+# handful of syntax-specific facts, and never boots the app.
 #
 # The DSL is the public API. An +Archspec.rb+ file is evaluated directly:
 #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: archspec
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0.rc2
 platform: ruby
 authors:
 - Carmine Paolino
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-20 00:00:00.000000000 Z
+date: 2026-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubydex
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -73,8 +87,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '6.6'
 description: A static architecture linter for Ruby and Rails. Declare your components,
-  dependencies, and boundaries in one file, then check every change in CI. It reads
-  source with Prism and never boots the app.
+  dependencies, and boundaries in one file, then check every change in CI. It indexes
+  source with Rubydex and never boots the app.
 email:
 - carmine@paolino.me
 executables:
@@ -100,6 +114,7 @@ files:
 - lib/archspec/formatters/style.rb
 - lib/archspec/formatters/text.rb
 - lib/archspec/model.rb
+- lib/archspec/rubydex_index.rb
 - lib/archspec/rules/component_rules.rb
 - lib/archspec/rules/concern_rules.rb
 - lib/archspec/rules/cycle_rule.rb
@@ -107,9 +122,9 @@ files:
 - lib/archspec/rules/naming_rules.rb
 - lib/archspec/rules/privacy_rule.rb
 - lib/archspec/rules/protocol_rules.rb
+- lib/archspec/rules/reasoned.rb
 - lib/archspec/source_location.rb
 - lib/archspec/todo.rb
-- lib/archspec/value_object.rb
 - lib/archspec/version.rb
 homepage: https://archspecrb.dev
 licenses:
@@ -129,7 +144,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.3
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/archspec/value_object.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module ArchSpec
-  # A frozen value type with positional or keyword construction and #with,
-  # mirroring Ruby 3.2's Data.define. Deliberately hand-rolled: the gem
-  # supports Ruby 3.1, where Data does not exist. Do not replace this with
-  # Data until the required Ruby version reaches 3.2.
-  module ValueObject
-    def self.define(*members, &block)
-      klass = Struct.new(*members) do
-        members.each { |member| undef_method :"#{member}=" }
-
-        def initialize(*values, **keywords)
-          member_names = self.class.members
-
-          if keywords.any?
-            raise ArgumentError, 'expected positional arguments or keyword arguments, not both' unless values.empty?
-
-            unknown = keywords.keys - member_names
-            raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" if unknown.any?
-
-            missing = member_names - keywords.keys
-            raise ArgumentError, "missing keyword: #{missing.first.inspect}" if missing.any?
-
-            values = member_names.map { |member| keywords.fetch(member) }
-          elsif values.length != member_names.length
-            raise ArgumentError, "wrong number of arguments (given #{values.length}, expected #{member_names.length})"
-          end
-
-          super(*values)
-          freeze
-        end
-
-        def with(**changes)
-          unknown = changes.keys - self.class.members
-          raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" if unknown.any?
-
-          self.class.new(**to_h.merge(changes))
-        end
-      end
-
-      klass.class_eval(&block) if block
-      klass
-    end
-  end
-end