archspec 0.4.0 → 1.0.0.rc1

data/lib/archspec/model.rb

@@ -7,7 +7,7 @@ require_relative 'value_object'
 
 module ArchSpec
   ParseError = ValueObject.define(:message, :location)
-  MethodDefinition = ValueObject.define(:owner, :name, :scope, :location)
+  MethodDefinition = ValueObject.define(:owner, :name, :scope, :location, :visibility)
 
   Suppression = ValueObject.define(:rule, :start_line, :end_line, :reason) do
     def matches?(diagnostic)
@@ -18,26 +18,27 @@ module ArchSpec
   end
 
   class SourceFile
-    attr_reader :path, :relative_path, :expected_constant, :parse_errors, :suppressions
+    attr_reader :path, :relative_path, :parse_errors, :suppressions
 
-    def initialize(root:, path:, expected_constant:, parse_errors:, suppressions:)
+    def initialize(root:, path:, parse_errors:, suppressions:)
       @path = path
       @relative_path = Pathname(path).relative_path_from(Pathname(root)).to_s
-      @expected_constant = expected_constant
       @parse_errors = parse_errors
       @suppressions = suppressions
     end
   end
 
   class ConstantNode
-    attr_reader :name, :kind, :path, :location, :instance_methods, :class_methods, :method_definitions, :mixins
+    attr_reader :name, :kind, :path, :location, :instance_methods, :class_methods, :method_definitions, :mixins,
+                :nesting
     attr_accessor :superclass
 
-    def initialize(name:, kind:, path:, location:)
+    def initialize(name:, kind:, path:, location:, nesting: [])
       @name = name
       @kind = kind
       @path = path
       @location = location
+      @nesting = Array(nesting).dup.freeze
       @instance_methods = Set.new
       @class_methods = Set.new
       @method_definitions = []
@@ -56,22 +57,58 @@ module ArchSpec
       kind == :module
     end
 
-    def add_instance_method(name, location:)
+    def add_instance_method(name, location:, visibility: :public)
       instance_methods.add(name.to_sym)
-      method_definitions << MethodDefinition.new(self.name, name.to_sym, :instance, location)
+      method_definitions << MethodDefinition.new(self.name, name.to_sym, :instance, location, visibility)
     end
 
-    def add_class_method(name, location:)
+    def add_class_method(name, location:, visibility: :public)
       class_methods.add(name.to_sym)
-      method_definitions << MethodDefinition.new(self.name, name.to_sym, :class, location)
+      method_definitions << MethodDefinition.new(self.name, name.to_sym, :class, location, visibility)
     end
 
     def add_mixin(kind, name)
       mixins.fetch(kind).add(name)
     end
+
+    # Rewrites the visibility of already-recorded definitions, for the
+    # <tt>private :foo, :bar</tt> form that names methods defined earlier.
+    def set_visibility(name, scope, visibility)
+      name = name.to_sym
+      method_definitions.map! do |definition|
+        definition.name == name && definition.scope == scope ? definition.with(visibility: visibility) : definition
+      end
+    end
   end
 
-  Edge = ValueObject.define(:type, :from_path, :from_constant, :to, :location, :confidence, :receiver)
+  Edge = ValueObject.define(
+    :type,
+    :from_path,
+    :from_constant,
+    :to,
+    :location,
+    :confidence,
+    :receiver,
+    :lexical_nesting
+  ) do
+    VERBS = {
+      references_constant: 'references',
+      inherits_from: 'inherits from',
+      includes: 'includes',
+      prepends: 'prepends',
+      extends: 'extends',
+      calls_named_method: 'calls',
+      instantiates_and_invokes: 'instantiates and invokes',
+      requires: 'requires',
+      requires_relative: 'requires',
+      dynamic_feature: 'uses dynamic feature'
+    }.freeze
+
+    # The edge type as prose, for diagnostics and explain output.
+    def verb
+      VERBS.fetch(type, type.to_s.tr('_', ' '))
+    end
+  end
 
   class Component
     attr_reader :name, :files, :constants, :file_reasons, :constant_reasons
@@ -80,6 +117,7 @@ module ArchSpec
       @name = name.to_sym
       @files = Set.new
       @constants = Set.new
+      @constant_occurrences = Set.new
       @file_reasons = Hash.new { |hash, key| hash[key] = Set.new }
       @constant_reasons = Hash.new { |hash, key| hash[key] = Set.new }
     end
@@ -89,10 +127,17 @@ module ArchSpec
       file_reasons[path].add(reason) if reason
     end
 
-    def add_constant(name, reason: nil)
+    def add_constant(name, path:, reason: nil)
       constants.add(name)
+      @constant_occurrences.add([name, path])
       constant_reasons[name].add(reason) if reason
     end
+
+    def includes_constant?(name, path: nil)
+      return constants.include?(name) unless path
+
+      @constant_occurrences.include?([name, path])
+    end
   end
 
   class Graph
@@ -117,29 +162,30 @@ module ArchSpec
       @components = {}
     end
 
-    def add_file(path:, expected_constant:, parse_errors:, suppressions: [])
+    def add_file(path:, parse_errors:, suppressions: [])
       files[path] = SourceFile.new(
         root: root,
         path: path,
-        expected_constant: expected_constant,
         parse_errors: parse_errors,
         suppressions: suppressions
       )
     end
 
-    def add_constant(name:, kind:, path:, location:)
+    def add_constant(name:, kind:, path:, location:, nesting: [])
       normalized = normalize_constant(name)
       existing = @constants_by_name[normalized].find { |constant| constant.path == path && constant.kind == kind }
       return existing if existing
 
-      constant = ConstantNode.new(name: normalized, kind: kind, path: path, location: location)
+      constant = ConstantNode.new(name: normalized, kind: kind, path: path, location: location, nesting: nesting)
       constants << constant
       @constants_by_name[normalized] << constant
       constant
     end
 
-    def add_edge(type:, from_path:, from_constant:, to:, location:, confidence: :high, receiver: nil)
-      edges << Edge.new(type, from_path, from_constant, normalize_constant(to), location, confidence, receiver)
+    def add_edge(type:, from_path:, from_constant:, to:, location:, confidence: :high, receiver: nil,
+                 lexical_nesting: nil)
+      nesting = lexical_nesting&.map { |name| normalize_constant(name) }&.freeze
+      edges << Edge.new(type, from_path, from_constant, to.to_s, location, confidence, receiver, nesting)
     end
 
     def constants_named(name)
@@ -154,7 +200,13 @@ module ArchSpec
       component = components[name.to_sym]
       return [] unless component
 
-      component.constants.flat_map { |constant_name| constants_named(constant_name) }.flat_map(&:method_definitions)
+      constants_for_component(name).flat_map(&:method_definitions)
+    end
+
+    # Every method definition in the graph, across all constants. Used by
+    # project-wide naming rules that are not scoped to one component.
+    def method_definitions
+      constants.flat_map(&:method_definitions)
     end
 
     def assign_components(component_specs)
@@ -162,18 +214,22 @@ module ArchSpec
 
       component_specs.each do |spec|
         component = Component.new(spec.name)
+        files_matched_by_pattern = Set.new
 
         spec.file_patterns.each do |pattern|
-          each_matching_file(pattern) { |path| component.add_file(path, reason: "matched file pattern #{pattern}") }
+          each_matching_file(pattern) do |path|
+            files_matched_by_pattern.add(path)
+            component.add_file(path, reason: "matched file pattern #{pattern}")
+          end
         end
 
         constants.each do |constant|
-          matched_file = component.files.include?(constant.path)
+          matched_file = files_matched_by_pattern.include?(constant.path)
           matched_constant = spec.matches_constant?(constant.name)
           next unless matched_file || matched_constant
 
           component.add_file(constant.path, reason: "defines #{constant.name}") if matched_constant
-          component.add_constant(constant.name,
+          component.add_constant(constant.name, path: constant.path,
                                  reason: matched_file ? 'defined in matched file' : 'matched namespace/constant selector')
         end
 
@@ -187,14 +243,31 @@ module ArchSpec
       end
     end
 
-    def component_names_for_constant(name)
+    def component_names_for_constant(name, path: nil)
       normalized = normalize_constant(name)
 
       components.values.each_with_object(Set.new) do |component, names|
-        names.add(component.name) if component.constants.include?(normalized)
+        names.add(component.name) if component.includes_constant?(normalized, path: path)
       end
     end
 
+    # The edge's source as prose: its constant when known, otherwise the
+    # root-relative path of the file. Diagnostics use this so evidence never
+    # embeds an absolute path, which would make todo fingerprints
+    # machine-specific.
+    def edge_source_name(edge)
+      edge.from_constant || files[edge.from_path]&.relative_path || edge.from_path
+    end
+
+    # Components that own the source of an edge. Constant and namespace
+    # selectors stay precise when a file also defines unrelated constants;
+    # top-level edges fall back to the file assignment.
+    def source_components_for(edge)
+      return component_names_for_path(edge.from_path) unless edge.from_constant
+
+      component_names_for_constant(edge.from_constant, path: edge.from_path)
+    end
+
     def dependency_edges
       edges.select { |edge| DEPENDENCY_EDGE_TYPES.include?(edge.type) }
     end
@@ -202,31 +275,30 @@ module ArchSpec
     def target_components_for(edge)
       return Set.new unless DEPENDENCY_EDGE_TYPES.include?(edge.type)
 
-      resolved = resolve_constant_reference(edge.to, edge.from_constant)
+      resolved = resolve_edge_constant(edge)
       constants_named(resolved).each_with_object(Set.new) do |constant, names|
-        names.merge(component_names_for_path(constant.path))
-        names.merge(component_names_for_constant(constant.name))
+        names.merge(component_names_for_constant(resolved, path: constant.path))
       end
     end
 
-    def resolve_constant_reference(name, from_constant)
+    def resolve_constant_reference(name, from_constant = nil, lexical_nesting: nil)
+      absolute = name.to_s.start_with?('::')
       normalized = normalize_constant(name)
-      candidates = []
-
-      if from_constant
-        namespace = normalize_constant(from_constant).split('::')
-        namespace.pop
-
-        until namespace.empty?
-          candidates << "#{namespace.join('::')}::#{normalized}"
-          namespace.pop
-        end
-      end
+      return normalized if absolute
 
+      scopes = lexical_nesting || inferred_nesting(from_constant)
+      candidates = scopes.map { |scope| "#{normalize_constant(scope)}::#{normalized}" }
       candidates << normalized
       candidates.find { |candidate| constants_named(candidate).any? } || normalized
     end
 
+    # Resolves an edge with the lexical nesting captured where the reference
+    # appeared. This matters for compact class declarations and superclass
+    # expressions, where inferring scope from the finished class name is wrong.
+    def resolve_edge_constant(edge)
+      resolve_constant_reference(edge.to, edge.from_constant, lexical_nesting: edge.lexical_nesting)
+    end
+
     # Instance methods a constant responds to, walking resolvable superclasses
     # and include/prepend mixins. Returns [methods, unresolved ancestor names];
     # a non-empty second element means the answer is incomplete.
@@ -246,11 +318,21 @@ module ArchSpec
       nodes.each do |node|
         methods.merge(node.instance_methods)
 
-        ancestors = node.mixins[:include].to_a + node.mixins[:prepend].to_a
-        ancestors << node.superclass if node.superclass
+        mixins = node.mixins[:include].to_a + node.mixins[:prepend].to_a
+
+        mixins.each do |ancestor|
+          resolved_name = resolve_constant_reference(
+            ancestor,
+            node.name,
+            lexical_nesting: [node.name] + node.nesting
+          )
+          ancestor_methods, ancestor_unresolved = effective_instance_methods(resolved_name, visited)
+          methods.merge(ancestor_methods)
+          unresolved.merge(ancestor_unresolved)
+        end
 
-        ancestors.each do |ancestor|
-          resolved_name = resolve_constant_reference(ancestor, node.name)
+        if node.superclass
+          resolved_name = resolve_constant_reference(node.superclass, node.name, lexical_nesting: node.nesting)
           ancestor_methods, ancestor_unresolved = effective_instance_methods(resolved_name, visited)
           methods.merge(ancestor_methods)
           unresolved.merge(ancestor_unresolved)
@@ -265,7 +347,7 @@ module ArchSpec
       pairs = Set.new
 
       dependency_edges.each do |edge|
-        source_components = component_names_for_path(edge.from_path)
+        source_components = source_components_for(edge)
         source_components &= allowed_sources unless allowed_sources.empty?
         next if source_components.empty?
 
@@ -287,16 +369,23 @@ module ArchSpec
       end
     end
 
-    def component_assignment_reasons_for_constant(name)
+    def component_assignment_reasons_for_constant(name, path: nil)
       normalized = normalize_constant(name)
 
       components.values.each_with_object({}) do |component, reasons|
-        next unless component.constants.include?(normalized)
+        next unless component.includes_constant?(normalized, path: path)
 
         reasons[component.name] = component.constant_reasons[normalized].to_a.sort
       end
     end
 
+    def constants_for_component(name)
+      component = components[name.to_sym]
+      return [] unless component
+
+      constants.select { |constant| component.includes_constant?(constant.name, path: constant.path) }
+    end
+
     def suppressed?(diagnostic)
       files[diagnostic.location.path]&.suppressions&.any? { |suppression| suppression.matches?(diagnostic) }
     end
@@ -314,5 +403,12 @@ module ArchSpec
     def normalize_constant(value)
       value.to_s.sub(/\A::/, '')
     end
+
+    def inferred_nesting(from_constant)
+      return [] unless from_constant
+
+      parts = normalize_constant(from_constant).split('::')
+      parts.length.downto(1).map { |length| parts.first(length).join('::') }
+    end
   end
 end

data/lib/archspec/rules/component_rules.rb

@@ -30,7 +30,7 @@ module ArchSpec
           Diagnostic.new(
             rule: id,
             message: because ? "#{source} must stay empty: #{because}" : "#{source} must stay empty",
-            location: SourceLocation.new(path, 1, 1),
+            location: SourceLocation.point(path, 1, 1),
             evidence: "#{relative} belongs to #{source}"
           )
         end

data/lib/archspec/rules/concern_rules.rb

@@ -34,7 +34,7 @@ module ArchSpec
           consumers = includers[edge.from_constant]
           next if consumers.empty?
 
-          target = graph.resolve_constant_reference(edge.to, edge.from_constant)
+          target = graph.resolve_edge_constant(edge)
           includer = consumers.find { |name| target == name || target.start_with?("#{name}::") }
           next unless includer
 
@@ -42,7 +42,7 @@ module ArchSpec
             rule: id,
             message: "#{edge.from_constant} must not reference its includer #{includer}",
             location: edge.location,
-            evidence: "#{edge.from_constant} #{edge.type} #{target}"
+            evidence: "#{edge.from_constant} #{edge.verb} #{target}"
           )
         end
       end
@@ -56,7 +56,7 @@ module ArchSpec
         graph.edges.each do |edge|
           next unless MIXIN_TYPES.include?(edge.type) && edge.from_constant
 
-          mod = graph.resolve_constant_reference(edge.to, edge.from_constant)
+          mod = graph.resolve_edge_constant(edge)
           map[mod].add(edge.from_constant) unless mod == edge.from_constant
         end
 

data/lib/archspec/rules/cycle_rule.rb

@@ -2,7 +2,7 @@
 
 module ArchSpec
   module Rules
-    # Backs ArchSpec::DSL::Context#no_cycles!. Flags dependency cycles between
+    # Backs ArchSpec::DSL::Context#no_cycles. Flags dependency cycles between
     # components, reporting each cycle once in a canonical order.
     class NoCyclesRule
       attr_reader :components
@@ -17,7 +17,7 @@ module ArchSpec
 
       def evaluate(graph)
         cycles(graph).map do |cycle|
-          location = first_location_for_cycle(graph, cycle) || SourceLocation.new(graph.root, 1, 1)
+          location = first_location_for_cycle(graph, cycle) || SourceLocation.point(graph.root, 1, 1)
           Diagnostic.new(
             rule: id,
             message: "component dependency cycle: #{cycle.join(' -> ')}",
@@ -74,7 +74,7 @@ module ArchSpec
       def first_location_for_cycle(graph, cycle)
         source, target = cycle
         graph.dependency_edges.find do |edge|
-          graph.component_names_for_path(edge.from_path).include?(source) &&
+          graph.source_components_for(edge).include?(source) &&
             graph.target_components_for(edge).include?(target)
         end&.location
       end

data/lib/archspec/rules/dependency_rules.rb

@@ -29,19 +29,11 @@ module ArchSpec
       private
 
       def relevant_edges(graph)
-        graph.dependency_edges.select { |edge| graph.component_names_for_path(edge.from_path).include?(source) }
-      end
-
-      def target_components(graph, edge)
-        graph.target_components_for(edge)
-      end
-
-      def edge_target(edge)
-        edge.to
+        graph.dependency_edges.select { |edge| graph.source_components_for(edge).include?(source) }
       end
     end
 
-    # Backs ArchSpec::DSL::ComponentProxy#can_use. Flags references from the
+    # Backs ArchSpec::DSL::ComponentProxy#can_only_use. Flags references from the
     # source to any component outside its allowlist.
     class AllowDependenciesRule < DependencyRule
       def id
@@ -50,14 +42,14 @@ module ArchSpec
 
       def evaluate(graph)
         relevant_edges(graph).flat_map do |edge|
-          target_components(graph, edge).filter_map do |target|
+          graph.target_components_for(edge).filter_map do |target|
             next if target == source || targets.include?(target)
 
             Diagnostic.new(
               rule: id,
               message: "#{source} may not depend on #{target}",
               location: edge.location,
-              evidence: "#{edge.from_constant || edge.from_path} #{edge.type} #{edge_target(edge)}"
+              evidence: "#{graph.edge_source_name(edge)} #{edge.verb} #{edge.to}"
             )
           end
         end
@@ -73,14 +65,14 @@ module ArchSpec
 
       def evaluate(graph)
         relevant_edges(graph).flat_map do |edge|
-          forbidden = target_components(graph, edge) & targets
+          forbidden = graph.target_components_for(edge) & targets
 
           forbidden.map do |target|
             Diagnostic.new(
               rule: id,
               message: "#{source} must not depend on #{target}",
               location: edge.location,
-              evidence: "#{edge.from_constant || edge.from_path} #{edge.type} #{edge_target(edge)}"
+              evidence: "#{graph.edge_source_name(edge)} #{edge.verb} #{edge.to}"
             )
           end
         end
@@ -115,7 +107,7 @@ module ArchSpec
         graph.dependency_edges.flat_map do |edge|
           next [] unless graph.target_components_for(edge).include?(source)
 
-          offenders = graph.component_names_for_path(edge.from_path).reject do |component|
+          offenders = graph.source_components_for(edge).reject do |component|
             component == source || consumers.include?(component)
           end
 
@@ -124,7 +116,7 @@ module ArchSpec
               rule: id,
               message: message_for(offender),
               location: edge.location,
-              evidence: "#{edge.from_constant || edge.from_path} #{edge.type} #{edge.to}"
+              evidence: "#{graph.edge_source_name(edge)} #{edge.verb} #{edge.to}"
             )
           end
         end
@@ -164,16 +156,16 @@ module ArchSpec
 
       def evaluate(graph)
         graph.dependency_edges.filter_map do |edge|
-          next unless graph.component_names_for_path(edge.from_path).include?(source)
+          next unless graph.source_components_for(edge).include?(source)
 
-          referenced = graph.resolve_constant_reference(edge.to, edge.from_constant)
+          referenced = graph.resolve_edge_constant(edge)
           next unless constants.any? { |constant| referenced == constant || referenced.start_with?("#{constant}::") }
 
           Diagnostic.new(
             rule: id,
             message: "#{source} must not reference #{referenced}",
             location: edge.location,
-            evidence: "#{edge.from_constant || edge.from_path} #{edge.type} #{edge.to}"
+            evidence: "#{graph.edge_source_name(edge)} #{edge.verb} #{edge.to}"
           )
         end
       end