archspec 1.0.1 → 1.1.0.rc2

data/lib/archspec/architectures.rb

@@ -296,9 +296,10 @@ module ArchSpec
         Rules::NamingRule.new(
           source: nil,
           selector: Rules::Naming::NameSelector.new(regex),
-          constraint: Rules::Naming::Forbidden.new(because: reason),
+          constraint: Rules::Naming::Forbidden.new,
           scope: scope
-        )
+        ),
+        because: reason
       )
     end
 
@@ -314,11 +315,14 @@ module ArchSpec
 
     def define_component(dsl, name, selector)
       if selector.is_a?(Hash)
+        selector = selector.to_h.transform_keys(&:to_sym)
         dsl.component(
           name,
           in: selector[:in] || selector[:files],
+          except: selector[:except],
           namespace: selector[:namespace],
-          constants: selector[:constants]
+          constants: selector[:constants],
+          descendants_of: selector[:descendants_of]
         )
       else
         dsl.component(name, in: selector)

data/lib/archspec/component_spec.rb

@@ -5,19 +5,23 @@ module ArchSpec
   # explicit constant name. Created by ArchSpec::DSL::Context#component. The
   # analyzer uses it to assign files and constants to the component.
   class ComponentSpec
-    attr_reader :name, :file_patterns, :namespaces, :constants
+    attr_reader :name, :file_patterns, :exclude_patterns, :namespaces, :constants, :ancestor_names
 
-    def initialize(name, files: [], namespace: nil, constants: nil)
+    def initialize(name, files: [], except: [], namespace: nil, constants: nil, descendants_of: nil)
       @name = name.to_sym
       @file_patterns = Array(files).compact.map(&:to_s)
+      @exclude_patterns = Array(except).compact.map(&:to_s)
       @namespaces = Array(namespace).compact.map { |value| normalize_constant(value) }
       @constants = Array(constants).compact.map { |value| normalize_constant(value) }
+      @ancestor_names = Array(descendants_of).compact.map { |value| normalize_constant(value) }
     end
 
     def merge!(other)
       @file_patterns |= other.file_patterns
+      @exclude_patterns |= other.exclude_patterns
       @namespaces |= other.namespaces
       @constants |= other.constants
+      @ancestor_names |= other.ancestor_names
       self
     end
 
@@ -30,6 +34,13 @@ module ArchSpec
         end
     end
 
+    def matching_ancestor(name, graph)
+      return if ancestor_names.empty?
+
+      ancestors = graph.ancestor_names(name).first
+      ancestor_names.find { |ancestor| ancestors.include?(ancestor) }
+    end
+
     private
 
     def normalize_constant(value)

data/lib/archspec/diagnostic.rb

@@ -8,14 +8,28 @@ module ArchSpec
   # these. Its #fingerprint is the stable id used to match todo entries and
   # suppress specific findings.
   class Diagnostic
-    attr_reader :rule, :message, :location, :evidence, :confidence
+    attr_reader :rule, :message, :location, :evidence, :confidence, :reason
 
-    def initialize(rule:, message:, location:, evidence:, confidence: :high)
+    def initialize(rule:, message:, location:, evidence:, confidence: :high, reason: nil)
       @rule = rule
       @message = message
       @location = location
       @evidence = evidence
       @confidence = confidence
+      @reason = reason
+    end
+
+    def with_reason(reason)
+      return self unless reason
+
+      self.class.new(
+        rule: rule,
+        message: message,
+        location: location,
+        evidence: evidence,
+        confidence: confidence,
+        reason: reason
+      )
     end
 
     # Line numbers stay out of the fingerprint so todo entries survive edits
@@ -29,7 +43,7 @@ module ArchSpec
     end
 
     def to_h(root:)
-      {
+      hash = {
         id: fingerprint(root: root),
         rule: rule,
         message: message,
@@ -41,6 +55,8 @@ module ArchSpec
         evidence: evidence,
         confidence: confidence.to_s
       }
+      hash[:reason] = reason if reason
+      hash
     end
   end
 end

data/lib/archspec/dsl.rb

@@ -89,17 +89,26 @@ module ArchSpec
       end
 
       # Declares a component: a named set of files, matched by glob, namespace,
-      # or explicit constant.
+      # explicit constant, or semantic ancestry.
       #
       #   component :services, in: "app/services/**/*.rb"
+      #   component :workflows, in: "app/models/**/*.rb", except: "app/models/legacy/**/*.rb"
       #   component :billing, namespace: "Billing"
       #   component :legacy, constants: %w[OldReport OldExport]
+      #   component :records, descendants_of: "ApplicationRecord"
       #
       # Returns an ArchSpec::DSL::ComponentProxy for attaching rules. The
       # component is also available by name later in the file.
-      def component(name, in: nil, namespace: nil, constants: nil)
+      def component(name, in: nil, except: nil, namespace: nil, constants: nil, descendants_of: nil)
         add_component(
-          ComponentSpec.new(name, files: binding.local_variable_get(:in), namespace: namespace, constants: constants)
+          ComponentSpec.new(
+            name,
+            files: binding.local_variable_get(:in),
+            except: except,
+            namespace: namespace,
+            constants: constants,
+            descendants_of: descendants_of
+          )
         )
         ComponentProxy.new(self, name)
       end
@@ -129,16 +138,16 @@ module ArchSpec
       #   no_cycles among: %i[billing catalog shared]
       #
       # Rule id: +dependencies.no_cycles+.
-      def no_cycles(among: nil)
+      def no_cycles(among: nil, because: nil)
         DSL.assert_known_components!(self, among, for_rule: 'no_cycles') if among
-        add_rule(Rules::NoCyclesRule.new(among: among))
+        add_rule(Rules.with_reason(Rules::NoCyclesRule.new(among: among), because))
       end
 
       # Adds a custom rule object. A rule responds to +id+ and
       # <tt>evaluate(graph)</tt>, returning ArchSpec::Diagnostic objects. Use
       # this to extend ArchSpec with project-specific checks.
-      def rule(rule)
-        add_rule(rule)
+      def rule(rule, because: nil)
+        add_rule(Rules.with_reason(rule, because))
       end
 
       def method_missing(name, ...)
@@ -172,9 +181,9 @@ module ArchSpec
       #   controllers.can_only_use :models, :services
       #
       # Rule id: +dependencies.allow+.
-      def can_only_use(*targets)
+      def can_only_use(*targets, because: nil)
         DSL.assert_known_components!(definition, targets, for_rule: "#{name}.can_only_use")
-        add_rule(Rules::AllowDependenciesRule.new(name, targets))
+        add_rule(Rules::AllowDependenciesRule.new(name, targets), because: because)
         self
       end
 
@@ -184,9 +193,9 @@ module ArchSpec
       #   models.cannot_use :controllers, :helpers
       #
       # Rule id: +dependencies.forbid+.
-      def cannot_use(*targets)
+      def cannot_use(*targets, because: nil)
         DSL.assert_known_components!(definition, targets, for_rule: "#{name}.cannot_use")
-        add_rule(Rules::ForbidDependenciesRule.new(name, targets))
+        add_rule(Rules::ForbidDependenciesRule.new(name, targets), because: because)
         self
       end
 
@@ -197,26 +206,27 @@ module ArchSpec
       #   shared_kernel.can_only_be_used_by :billing, :catalog
       #
       # Rule id: +dependencies.consumers+.
-      def can_only_be_used_by(*consumers)
+      def can_only_be_used_by(*consumers, because: nil)
         DSL.assert_known_components!(definition, consumers, for_rule: "#{name}.can_only_be_used_by")
-        add_rule(Rules::AllowedConsumersRule.new(name, consumers))
+        add_rule(Rules::AllowedConsumersRule.new(name, consumers), because: because)
         self
       end
 
       # Forbids calling the named methods. By default any receiver matches, so
       # this catches +record.update+ and +cache.update+ alike. Pass
-      # <tt>receiver: :none</tt> to match only bare, implicit-+self+ calls, which
-      # is how the Rails presets keep the controller API out of models.
+      # <tt>receiver: :none</tt> to match only bare, implicit-+self+ calls, or a
+      # constant name to match that semantic class receiver and its descendants.
       #
       #   queries.cannot_call :save, :update, :destroy
       #   services.cannot_call :render, :params, receiver: :none
+      #   models.cannot_call :find_by_sql, receiver: "ActiveRecord::Base"
       #
       # A bare call to a method the component defines, inherits, or generates
       # with +attr_*+, Rails +attribute+, or +delegate+ is treated as its own API
-      # and not flagged.
+      # and not flagged. Resolved method aliases are matched to their target.
       # Rule id: +methods.forbid+.
-      def cannot_call(*methods, receiver: :any)
-        add_rule(Rules::CannotCallRule.new(name, methods, receiver: receiver))
+      def cannot_call(*methods, receiver: :any, because: nil)
+        add_rule(Rules::CannotCallRule.new(name, methods, receiver: receiver), because: because)
         self
       end
 
@@ -227,8 +237,8 @@ module ArchSpec
       #   models.cannot_define :call
       #
       # Rule id: +methods.define_forbid+.
-      def cannot_define(*methods)
-        add_rule(Rules::CannotDefineMethodRule.new(name, methods))
+      def cannot_define(*methods, because: nil)
+        add_rule(Rules::CannotDefineMethodRule.new(name, methods), because: because)
         self
       end
 
@@ -237,8 +247,8 @@ module ArchSpec
       # toward plain methods over anonymous command objects.
       #
       # Rule id: +objects.instantiate_and_invoke_forbid+.
-      def cannot_instantiate_and_invoke
-        add_rule(Rules::CannotInstantiateAndInvokeRule.new(name))
+      def cannot_instantiate_and_invoke(because: nil)
+        add_rule(Rules::CannotInstantiateAndInvokeRule.new(name), because: because)
         self
       end
 
@@ -248,8 +258,8 @@ module ArchSpec
       #   models.cannot_reference_constants "ActionController", "ActionView"
       #
       # Rule id: +constants.forbid+.
-      def cannot_reference_constants(*constants)
-        add_rule(Rules::CannotReferenceConstantsRule.new(name, constants))
+      def cannot_reference_constants(*constants, because: nil)
+        add_rule(Rules::CannotReferenceConstantsRule.new(name, constants), because: because)
         self
       end
 
@@ -263,8 +273,11 @@ module ArchSpec
       # +constants+ matches exact names, +namespace+ matches a name and its
       # children. Code inside the component may still reach its own internals.
       # Rule id: +dependencies.privacy+.
-      def public_api(*patterns, constants: nil, namespace: nil)
-        add_rule(Rules::PublicApiRule.new(name, files: patterns, constants: constants, namespaces: namespace))
+      def public_api(*patterns, constants: nil, namespace: nil, because: nil)
+        add_rule(
+          Rules::PublicApiRule.new(name, files: patterns, constants: constants, namespaces: namespace),
+          because: because
+        )
         self
       end
 
@@ -276,8 +289,8 @@ module ArchSpec
       #   model_concerns.cannot_reference_includers
       #
       # Rule id: +concerns.independence+.
-      def cannot_reference_includers
-        add_rule(Rules::ConcernIndependenceRule.new(name))
+      def cannot_reference_includers(because: nil)
+        add_rule(Rules::ConcernIndependenceRule.new(name), because: because)
         self
       end
 
@@ -290,34 +303,48 @@ module ArchSpec
       #
       # Rule id: +components.empty+.
       def must_be_empty(because: nil)
-        add_rule(Rules::MustBeEmptyRule.new(name, because: because))
+        add_rule(Rules::MustBeEmptyRule.new(name), because: because)
         self
       end
 
       # Requires every class in the component to implement all the named
-      # instance methods. Methods inherited from resolvable superclasses or
-      # mixins count.
+      # methods. Instance methods are checked by default; pass
+      # <tt>scope: :class</tt> for the class side. Methods inherited from
+      # resolvable superclasses or mixins count. Optional +arity:+ and
+      # +keywords:+ constraints check whether each method accepts that call.
       #
       #   commands.must_implement :perform
+      #   commands.must_implement :call, arity: 1, keywords: :actor
+      #   jobs.must_implement :perform_later, scope: :class
       #
       # Rule id: +protocol.must_implement+.
-      def must_implement(*methods)
+      def must_implement(*methods, scope: :instance, arity: nil, keywords: nil, because: nil)
         raise Error, 'must_implement requires at least one method' if methods.flatten.compact.empty?
 
         methods.each do |method_name|
-          add_rule(Rules::MustImplementRule.new(name, method_name))
+          add_rule(
+            Rules::MustImplementRule.new(
+              name,
+              method_name,
+              scope: scope,
+              arity: arity,
+              keywords: keywords
+            ),
+            because: because
+          )
         end
         self
       end
 
       # Requires every class in the component to implement at least one of the
-      # named instance methods. Useful when a protocol allows either name.
+      # named methods. Useful when a protocol allows either name. Pass
+      # <tt>scope: :class</tt> to check the class side.
       #
       #   commands.must_implement_one_of :perform, :call
       #
       # Rule id: +protocol.must_implement_one_of+.
-      def must_implement_one_of(*methods)
-        add_rule(Rules::MustImplementOneOfRule.new(name, methods))
+      def must_implement_one_of(*methods, scope: :instance, because: nil)
+        add_rule(Rules::MustImplementOneOfRule.new(name, methods, scope: scope), because: because)
         self
       end
 
@@ -338,13 +365,17 @@ module ArchSpec
 
       private
 
-      def add_rule(rule)
+      def add_rule(rule, because: nil)
+        rule = Rules.with_reason(rule, because)
         if rule.respond_to?(:merge_key)
           existing = definition.rules.find do |candidate|
             candidate.respond_to?(:merge_key) && candidate.merge_key == rule.merge_key
           end
 
-          return existing.merge!(rule) if existing.respond_to?(:merge!)
+          if existing
+            Rules.with_reason(existing, rule.archspec_because) if rule.respond_to?(:archspec_because)
+            return existing.merge!(rule) if existing.respond_to?(:merge!)
+          end
           return existing if existing
         end
 

data/lib/archspec/formatters/explanation.rb

@@ -28,7 +28,11 @@ module ArchSpec
         print_parse_errors(output, style, file)
         print_component_reasons(output, style, graph.component_assignment_reasons_for_path(path))
         print_suppressions(output, style, file)
-        print_facts(output, style, graph.edges.select { |edge| edge.from_path == path })
+        print_facts(output, style, graph.edges.select { |edge| edge.from_path == path }, label: 'outgoing facts')
+        names = graph.constants_for_path(path).map(&:name).to_set
+        incoming = graph.dependency_edges.select { |edge| names.include?(graph.resolve_edge_constant(edge)) }
+        print_facts(output, style, incoming, label: 'incoming dependencies')
+        print_census(output, style, graph.analysis_census(path: path))
       end
 
       def explain_constant(output, style, graph, subject)
@@ -40,14 +44,29 @@ module ArchSpec
           output.puts style.bold(constant.name)
           output.puts
           output.puts "  #{style.note('kind:')} #{constant.kind}"
-          output.puts "  #{style.note('file:')} #{constant.location.relative_path(graph.root)}:#{constant.location.line}"
+          relative_location = "#{constant.location.relative_path(graph.root)}:#{constant.location.line}"
+          output.puts "  #{style.note('file:')} #{relative_location}"
           print_component_reasons(
             output, style,
             graph.component_assignment_reasons_for_constant(constant.name, path: constant.path)
           )
           output.puts "  #{style.note('superclass:')} #{constant.superclass || '(none)'}"
+          ancestors, unresolved = graph.ancestor_names(constant.name)
+          resolved_ancestors = ancestors.empty? ? '(none)' : ancestors.to_a.join(', ')
+          output.puts "  #{style.note('resolved ancestors:')} #{resolved_ancestors}"
+          unless unresolved.empty?
+            output.puts "  #{style.note('unresolved ancestors:')} #{unresolved.to_a.sort.join(', ')}"
+          end
           output.puts "  #{style.note('instance methods:')} #{constant.instance_methods.to_a.sort.join(', ')}"
           output.puts "  #{style.note('class methods:')} #{constant.class_methods.to_a.sort.join(', ')}"
+          print_facts(
+            output,
+            style,
+            graph.edges.select { |edge| edge.from_constant == constant.name && edge.from_path == constant.path },
+            label: 'outgoing facts'
+          )
+          print_facts(output, style, graph.incoming_dependency_edges(constant.name), label: 'incoming dependencies')
+          print_census(output, style, graph.analysis_census(path: constant.path))
         end
       end
 
@@ -85,13 +104,13 @@ module ArchSpec
         end
       end
 
-      def print_facts(output, style, facts)
+      def print_facts(output, style, facts, label:)
         if facts.empty?
-          output.puts "  #{style.note('outgoing facts:')} (none)"
+          output.puts "  #{style.note("#{label}:")} (none)"
           return
         end
 
-        output.puts "  #{style.note('outgoing facts:')}"
+        output.puts "  #{style.note("#{label}:")}"
         locations = facts.map { |edge| "#{edge.location.line}:#{edge.location.column}" }
         in_gutters(locations) do |gutter, index|
           edge = facts[index]
@@ -99,6 +118,15 @@ module ArchSpec
         end
       end
 
+      def print_census(output, style, census)
+        clauses = []
+        clauses << "#{census[:unresolved_constants]} unresolved constants" if census[:unresolved_constants].positive?
+        clauses << "#{census[:dynamic_features]} dynamic features" if census[:dynamic_features].positive?
+        clauses << "#{census[:unknown_receivers]} unknown receivers" if census[:unknown_receivers].positive?
+        census[:rubydex_diagnostics].each { |rule, count| clauses << "#{count} RubyDEX #{rule}" }
+        output.puts "  #{style.note('analysis gaps:')} #{clauses.empty? ? '(none)' : clauses.join(', ')}"
+      end
+
       # Yields each label right-justified to the widest one, with the frame
       # gutter bar appended, so columns line up like the check output.
       def in_gutters(labels)

data/lib/archspec/formatters/json.rb

@@ -12,6 +12,7 @@ module ArchSpec
           files: graph.files.size,
           constants: graph.constants.size,
           facts: graph.edges.size,
+          analysis: graph.analysis_census,
           violations: diagnostics.map { |diagnostic| diagnostic.to_h(root: graph.root) }
         )
       end

data/lib/archspec/formatters/text.rb

@@ -28,6 +28,7 @@ module ArchSpec
         if diagnostics.empty?
           output.puts "ArchSpec passed: #{graph.files.size} files, #{graph.constants.size} constants, " \
                       "#{graph.edges.size} facts checked."
+          print_census(output, graph)
           return
         end
 
@@ -40,13 +41,15 @@ module ArchSpec
 
         label = diagnostics.size == 1 ? 'architecture violation' : 'architecture violations'
         output.puts style.bold("#{diagnostics.size} #{label} found.")
+        print_census(output, graph)
       end
 
       def print_diagnostic(output, style, graph, diagnostic, sources)
         location = diagnostic.location
         relative = location.relative_path(graph.root)
 
-        output.puts "#{style.severity('[error]')} #{style.bold(diagnostic.message)} #{style.faint("[#{diagnostic.rule}]")}"
+        header = "#{style.severity('[error]')} #{style.bold(diagnostic.message)} #{style.faint("[#{diagnostic.rule}]")}"
+        output.puts header
         output.puts
         output.puts "#{relative}:#{location.line}:#{location.column}"
         print_frame(output, style, location, sources[location.path])
@@ -55,6 +58,7 @@ module ArchSpec
           output.puts
           output.puts "  #{style.note('note:')} #{note}"
         end
+        output.puts "  #{style.note('reason:')} #{diagnostic.reason}" if diagnostic.reason
         output.puts
       end
 
@@ -107,6 +111,20 @@ module ArchSpec
       rescue SystemCallError
         []
       end
+
+      def print_census(output, graph)
+        census = graph.analysis_census
+        clauses = []
+        if census[:unresolved_constants].positive?
+          clauses << "#{census[:unresolved_constants]} unresolved constant references"
+        end
+        clauses << "#{census[:dynamic_features]} dynamic features" if census[:dynamic_features].positive?
+        clauses << "#{census[:unknown_receivers]} calls with unknown receivers" if census[:unknown_receivers].positive?
+        census[:rubydex_diagnostics].each do |rule, count|
+          clauses << "#{count} RubyDEX #{rule} #{count == 1 ? 'diagnostic' : 'diagnostics'}"
+        end
+        output.puts "Analysis gaps: #{clauses.join(', ')}." unless clauses.empty?
+      end
     end
   end
 end