archspec 1.1.0.rc2 → 1.2.0

data/lib/archspec/concern_semantics.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  # Normalizes the explicit ActiveSupport::Concern DSL after semantic indexing.
+  # Callback bodies retain lexical constant references, but their mixins and
+  # methods are installed on the consumer. No application code is executed.
+  # Source ownership is normalized here; established effects are emitted through
+  # Facts::Builder, using the same application path as external producers.
+  class ConcernSemantics
+    ModuleBody = Data.define(:name, :path, :body)
+    Callback = Data.define(:kind, :methods, :mixins, :calls)
+    MIXINS = { includes: :include, prepends: :prepend, extends: :extend }.freeze
+
+    def initialize
+      @modules = []
+      @callbacks = Hash.new { |hash, key| hash[key] = [] }
+      @dependencies = Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def record_module(name, path, body)
+      @modules << ModuleBody.new(name, path, body) if body.is_a?(Prism::StatementsNode)
+    end
+
+    def apply(graph)
+      @graph = graph
+      @mixin_edges = graph.edges.select { |edge| MIXINS.key?(edge.type) }
+                          .group_by { |edge| [edge.from_constant, edge.from_path] }
+      @concerns = @modules.select { |mod| extends_concern?(mod) }.map(&:name).to_set
+      return if @concerns.empty?
+
+      @facts = Facts::Builder.new(graph, producer: 'active_support_concern')
+      normalize_blocks
+      defer_dependencies
+      rebuild_mixins
+      install_consumers
+      @concerns.each do |name|
+        source = graph.constants_named("#{name}::ClassMethods").first
+        @facts.expose_methods(source: source, owner: graph.constants_named(name).first, scope: :class) if source
+      end
+      @facts.apply
+    end
+
+    private
+
+    attr_reader :graph
+
+    def extends_concern?(mod)
+      mod.body.body.any? do |node|
+        next false unless node.is_a?(Prism::CallNode) && node.name == :extend
+        next false unless node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)
+
+        span = SourceLocation.from_prism(mod.path, node.location)
+        @mixin_edges.fetch([mod.name, mod.path], []).any? do |edge|
+          edge.type == :extends && edge.from_constant == mod.name && within?(span, edge.location) &&
+            graph.resolve_edge_constant(edge) == 'ActiveSupport::Concern'
+        end
+      end
+    end
+
+    def install_consumers
+      events = graph.edges.select { |edge| MIXINS.key?(edge.type) }.group_by { |edge| [edge.from_constant, edge.from_path] }
+      events.each do |(name, path), edges|
+        next if @concerns.include?(name)
+        next unless edges.any? do |edge|
+          edge.type != :extends && @concerns.include?(graph.resolve_edge_constant(edge))
+        end
+
+        consumer = graph.constants_named(name).find { |node| node.path == path }
+        next unless consumer
+
+        consumer.mixins.each_value(&:clear)
+        visited = Set.new
+        edges.sort_by { |edge| [edge.location.line, edge.location.column] }.each do |edge|
+          target = graph.resolve_edge_constant(edge)
+          kind = MIXINS.fetch(edge.type)
+          if kind != :extend && @concerns.include?(target)
+            install_concern(consumer, target, kind, edge, visited)
+          else
+            add_mixin(consumer, kind, target, edge)
+          end
+        end
+      end
+    end
+
+    # Each block only touches edges that its concern owns, so the edges are
+    # indexed by owner once. Removed edges are compacted at the end, which
+    # keeps the surviving edges in their original order.
+    def normalize_blocks
+      @concern_edges = Hash.new { |hash, key| hash[key] = [] }
+      graph.edges.each_with_index do |edge, index|
+        @concern_edges[edge.from_constant] << index if @concerns.include?(edge.from_constant)
+      end
+      @removed_edges = Set.new
+
+      @modules.each do |mod|
+        next unless @concerns.include?(mod.name)
+
+        mod.body.body.each do |node|
+          next unless node.is_a?(Prism::CallNode) && (node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode))
+          next unless %i[class_methods included prepended].include?(node.name)
+          next unless node.arguments.nil? && node.block.is_a?(Prism::BlockNode)
+          next if graph.constants_named(mod.name).any? { |constant| constant.class_methods.include?(node.name) }
+
+          location = SourceLocation.from_prism(mod.path, node.block.location)
+          if node.name == :class_methods
+            normalize_class_methods(mod, location)
+          else
+            defer_callback(mod, node, location)
+          end
+        end
+      end
+      graph.edges.replace(graph.edges.reject.with_index { |_, index| @removed_edges.include?(index) })
+    end
+
+    def owned_edges(name)
+      @concern_edges[name].filter_map do |index|
+        edge = graph.edges[index]
+        [index, edge] if edge.from_constant == name && !@removed_edges.include?(index)
+      end
+    end
+
+    def normalize_class_methods(mod, location)
+      name = "#{mod.name}::ClassMethods"
+      target = graph.add_constant(name: name, kind: :module, path: mod.path,
+                                 location: location, nesting: [mod.name])
+      extract_methods(mod, location).each { |method| @facts.method_definition(owner: target, definition: method) }
+      owned_edges(mod.name).each do |index, edge|
+        next unless within?(location, edge.location)
+
+        graph.edges[index] = edge.with(from_constant: name,
+                                       resolved_receiver: edge.resolved_receiver == mod.name ? name : edge.resolved_receiver)
+      end
+    end
+
+    def defer_callback(mod, node, location)
+      methods = extract_methods(mod, location)
+      owned = owned_edges(mod.name)
+      mixins = owned.filter_map do |index, edge|
+        next unless MIXINS.key?(edge.type) && within?(location, edge.location)
+
+        @removed_edges.add(index)
+        edge
+      end
+      statements = node.block.body.is_a?(Prism::StatementsNode) ? node.block.body.body : []
+      direct = statements.select do |statement|
+        statement.is_a?(Prism::DefNode) ||
+          (statement.is_a?(Prism::CallNode) && statement.block.nil? &&
+           (statement.receiver.nil? || statement.receiver.is_a?(Prism::SelfNode)))
+      end
+                         .map { |statement| SourceLocation.from_prism(mod.path, statement.location) }
+      certain_methods = methods.select { |method| direct.any? { |span| within?(span, method.location) } }
+      certain_mixins = mixins.select { |edge| direct.any? { |span| within?(span, edge.location) } }
+      calls = owned.filter_map do |_, edge|
+        edge if edge.type == :calls_named_method && edge.receiver == :none &&
+                (direct.include?(edge.location) || certain_methods.any? { |method| within?(method.location, edge.location) })
+      end
+      @callbacks[mod.name] << Callback.new(node.name, certain_methods, certain_mixins, calls)
+      return if methods == certain_methods && mixins == certain_mixins
+
+      graph.conditional_callbacks << ConditionalCallback.new(mod.name, mod.path, node.name, location,
+        (mixins - certain_mixins).map do |edge|
+          ConditionalMixin.new(MIXINS.fetch(edge.type), graph.resolve_edge_constant(edge), edge.location)
+        end,
+        methods - certain_methods)
+      source = graph.constants_named(mod.name).find { |constant| constant.path == mod.path }
+      @facts.gap(source: source, message: "conditional #{node.name} callback", location: location)
+    end
+
+    def extract_methods(mod, location)
+      graph.constants_named(mod.name).flat_map do |constant|
+        selected = constant.method_definitions.select { |method| within?(location, method.location) }
+        constant.method_definitions.reject! { |method| selected.include?(method) }
+        constant.instance_methods.replace(constant.method_definitions.select { |method| method.scope == :instance }.map(&:name))
+        constant.class_methods.replace(constant.method_definitions.select { |method| method.scope == :class }.map(&:name))
+        selected
+      end
+    end
+
+    def defer_dependencies
+      graph.edges.reject! do |edge|
+        next false unless @concerns.include?(edge.from_constant) && %i[includes prepends].include?(edge.type)
+        next false unless @concerns.include?(graph.resolve_edge_constant(edge))
+
+        @dependencies[edge.from_constant] << edge
+        true
+      end
+    end
+
+    def rebuild_mixins
+      affected = @concerns | @concerns.map { |name| "#{name}::ClassMethods" }.to_set
+      mixins = graph.edges.select { |edge| MIXINS.key?(edge.type) }
+                    .group_by { |edge| [edge.from_constant, edge.from_path] }
+      graph.constants.each do |constant|
+        next unless affected.include?(constant.name)
+
+        constant.mixins.each_value(&:clear)
+        mixins.fetch([constant.name, constant.path], []).each do |edge|
+          constant.add_mixin(MIXINS.fetch(edge.type), "::#{graph.resolve_edge_constant(edge)}")
+        end
+      end
+    end
+
+    def install_concern(consumer, name, kind, origin, visited)
+      return if visited.include?([consumer.name, name])
+
+      visited.add([consumer.name, name])
+      @dependencies[name].each do |dependency|
+        target = graph.resolve_edge_constant(dependency)
+        install_concern(consumer, target, kind, dependency, visited)
+      end
+      add_mixin(consumer, kind, name, origin)
+      class_methods = "#{name}::ClassMethods"
+      unless graph.constants_named(class_methods).empty?
+        add_mixin(consumer, kind == :prepend ? :singleton_prepend : :extend, class_methods, origin)
+      end
+      callback_kind = kind == :prepend ? :prepended : :included
+      @callbacks[name].select { |callback| callback.kind == callback_kind }.each do |callback|
+        callback.mixins.each do |edge|
+          target = graph.resolve_edge_constant(edge)
+          mixin_kind = MIXINS.fetch(edge.type)
+          if @concerns.include?(target) && mixin_kind != :extend
+            install_concern(consumer, target, mixin_kind, edge, visited)
+          else
+            add_mixin(consumer, mixin_kind, target, edge)
+          end
+        end
+        callback.methods.each do |method|
+          @facts.method_definition(owner: consumer, definition: method, installation: origin.location)
+        end
+        callback.calls.each do |edge|
+          method = callback.methods.find { |definition| within?(definition.location, edge.location) }
+          @facts.bind_receiver(edge: edge, receiver: consumer.name, scope: method ? method.scope : :class)
+        end
+      end
+    end
+
+    def add_mixin(consumer, kind, target, origin)
+      @facts.mixin(owner: consumer, kind: kind, target: target, location: origin.location)
+    end
+
+    def within?(outer, inner)
+      outer.path == inner.path &&
+        ([outer.line, outer.column] <=> [inner.line, inner.column]) <= 0 &&
+        ([outer.end_line, outer.end_column] <=> [inner.end_line, inner.end_column]) >= 0
+    end
+  end
+end

data/lib/archspec/definition.rb

@@ -21,18 +21,43 @@ module ArchSpec
       'vendor/**/*'
     ].freeze
 
-    attr_accessor :name, :root_path, :todo_path, :base_dir
-    attr_reader :source_patterns, :ignore_patterns, :component_specs, :rules
+    attr_accessor :name, :root_path, :todo_path, :facts_path, :base_dir
+    attr_reader :source_patterns, :ignore_patterns, :user_ignore_patterns, :component_specs, :rules
 
     def initialize(name = nil)
       @name = name
       @root_path = '.'
       @todo_path = nil
+      @facts_path = nil
       @base_dir = nil
       @source_patterns = []
       @ignore_patterns = DEFAULT_IGNORE_PATTERNS.dup
+      @user_ignore_patterns = []
       @component_specs = {}
       @rules = []
+      @producers = {}
+      @auto_producers = []
+    end
+
+    # Producer names mapped to the file that registers them, or nil for a
+    # built-in producer. Declaring facts without producers selects Rails.
+    def producers
+      @producers.empty? ? { 'rails' => nil } : @producers
+    end
+
+    # Producers named by +reflect+, whose documents a check requires.
+    def declared_producers
+      @producers.keys
+    end
+
+    # Producers whose facts a check refreshes on its own when they are
+    # missing or stale.
+    attr_reader :auto_producers
+
+    def add_producer(name, require: nil, auto: false)
+      @producers[name.to_s] = require&.to_s
+      @auto_producers |= [name.to_s] if auto
+      @facts_path ||= 'archspec_facts'
     end
 
     def add_source_patterns(patterns)
@@ -40,7 +65,9 @@ module ArchSpec
     end
 
     def add_ignore_patterns(patterns)
-      @ignore_patterns |= Array(patterns).flatten.compact.map(&:to_s)
+      patterns = Array(patterns).flatten.compact.map(&:to_s)
+      @user_ignore_patterns |= patterns
+      @ignore_patterns |= patterns
     end
 
     def add_component(spec)
@@ -70,5 +97,17 @@ module ArchSpec
       patterns = source_patterns.empty? ? DEFAULT_SOURCE_PATTERNS.dup : source_patterns.dup
       patterns | component_specs.values.flat_map(&:file_patterns)
     end
+
+    # Whether a component file pattern explicitly reaches into a directory that
+    # only a default ignore excludes: its literal leading directories, before
+    # any glob character, sit inside that ignore. +vendor/engines/*/**/*.rb+
+    # does; a broad +**/*.rb+ does not. Ignores the user declared always win.
+    def claims_default_ignored?(pattern)
+      directory = pattern.sub(%r{\A\./}, '')[/\A[^*?\[{]*/].sub(%r{[^/]*\z}, '')
+
+      (DEFAULT_IGNORE_PATTERNS - user_ignore_patterns).any? do |ignore|
+        File.fnmatch?(ignore, "#{directory}_", File::FNM_PATHNAME | File::FNM_DOTMATCH)
+      end
+    end
   end
 end

data/lib/archspec/dsl.rb

@@ -50,7 +50,10 @@ module ArchSpec
       end
 
       # Adds glob patterns for files to skip. Combines with the built-in
-      # ignores for +.git+, +tmp+, +vendor+, and +node_modules+.
+      # ignores for +.git+, +.bundle+, +tmp+, +vendor+, and +node_modules+.
+      # A built-in ignore steps aside for a component pattern whose literal
+      # leading directories sit inside it, such as
+      # <tt>vendor/engines/*/**/*.rb</tt>; patterns declared here always win.
       def ignore(*patterns)
         add_ignore_patterns(patterns)
       end
@@ -61,11 +64,36 @@ module ArchSpec
       #
       #   todo "archspec_todo.yml"
       #
-      # Write or refresh it with <tt>archspec check --update-todo</tt>.
+      # Write or refresh it with <tt>archspec check --update-todo</tt>; flag
+      # entries that no longer match with <tt>archspec check --check-todo</tt>.
       def todo(path = 'archspec_todo.yml')
         self.todo_path = path.to_s
       end
 
+      # Loads the facts that <tt>archspec reflect</tt> captured from this
+      # directory. Checks only read these files; they never boot the app.
+      def facts(path = 'archspec_facts')
+        self.facts_path = path.to_s
+      end
+
+      # Chooses the producers <tt>archspec reflect</tt> runs, and turns on
+      # facts in +archspec_facts+ unless #facts names another directory.
+      # Without it, a facts directory is filled by the built-in +:rails+
+      # producer. Load your own producer from a gem or a project file:
+      #
+      #   reflect :rails
+      #   reflect :widgets, require: "widgets/archspec"
+      #   reflect :billing, require: "./lib/archspec/billing_facts"
+      #
+      # With <tt>auto: true</tt>, +check+ and +explain+ run the producer
+      # themselves when its facts are missing or stale, which boots the app.
+      # Leave it off where checks must not boot anything, such as CI.
+      def reflect(*names, require: nil, auto: false)
+        raise Error, 'reflect needs at least one producer name' if names.empty?
+
+        names.flatten.each { |name| add_producer(name, require: require, auto: auto) }
+      end
+
       # Yields each subdirectory matching a glob, so you can declare one
       # component per engine or pack without hardcoding their names. Paths
       # resolve against the +Archspec.rb+ directory, not the working directory,

data/lib/archspec/evaluator.rb

@@ -5,7 +5,11 @@ module ArchSpec
     extend self
 
     def evaluate(definition, graph, todo: Todo.empty)
-      diagnostics = parser_diagnostics(graph) + definition.rules.flat_map { |rule| rule.evaluate(graph) }
+      unsuppressed(definition, graph).reject { |diagnostic| todo.include?(diagnostic) }
+    end
+
+    def unsuppressed(definition, graph)
+      diagnostics = parser_diagnostics(graph) + graph.fact_diagnostics + definition.rules.flat_map { |rule| rule.evaluate(graph) }
 
       # Deduplicate before rejecting. One statement can raise several diagnostics
       # that differ only in evidence, because `include Foo` is both an includes
@@ -15,7 +19,7 @@ module ArchSpec
       diagnostics
         .sort_by { |d| [d.location.path, d.location.line, d.rule, d.message, d.evidence] }
         .uniq { |d| [d.rule, d.message, d.location.path, d.location.line] }
-        .reject { |diagnostic| graph.suppressed?(diagnostic) || todo.include?(diagnostic) }
+        .reject { |diagnostic| graph.suppressed?(diagnostic) }
     end
 
     private

data/lib/archspec/facts/application.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  module Facts
+    Reference = Data.define(:source, :target, :location)
+    Method = Data.define(:owner, :definition, :mode, :installation)
+    Mixin = Data.define(:owner, :target, :kind, :location)
+    Receiver = Data.define(:source, :name, :location, :receiver, :scope)
+    Exposure = Data.define(:source, :owner, :scope)
+    Gap = Data.define(:source, :message, :location)
+    Resolve = Data.define(:source, :message, :location)
+    # One document's facts. The producer is recorded on imported edges; facts
+    # applied in memory by a static pass have none.
+    Operations = Data.define(*LIST_KEYS.map(&:to_sym), :producer)
+
+    # Applies validated semantic facts, independently of how they were found.
+    # Source normalization happens before this boundary; facts establish the
+    # resulting relationships, APIs, and execution contexts.
+    module Application
+      extend self
+
+      MIXIN_TYPES = { include: :includes, prepend: :prepends, extend: :extends,
+                      singleton_prepend: :extends }.freeze
+
+      def apply(graph, batches)
+        validate(graph, batches)
+        dependencies = dependency_index(graph, batches)
+        batches.each do |batch|
+          producer = batch.producer
+          batch.references.each do |fact|
+            add_dependency(graph, dependencies, :references_constant, fact.source, fact.target, fact.location, producer)
+          end
+          batch.methods.each { |fact| install_method(fact) }
+          batch.mixins.each do |fact|
+            fact.owner.add_mixin(fact.kind, "::#{fact.target}")
+            add_dependency(graph, dependencies, MIXIN_TYPES.fetch(fact.kind), fact.owner, fact.target, fact.location,
+              producer, match_location: false)
+          end
+          batch.exposures.each do |fact|
+            graph.expose_instance_methods(fact.source.name, as_owner: exposure_owner_name(fact.owner), scope: fact.scope)
+          end
+          batch.gaps.each do |fact|
+            graph.add_edge(type: :dynamic_feature, from_path: fact.source.path, from_constant: fact.source.name,
+              to: fact.message, location: fact.location, confidence: :unknown_due_to_dynamic_feature,
+              producer: producer)
+          end
+        end
+        resolve_gaps(graph, batches.flat_map(&:resolves))
+        graph.clear_method_caches
+        bind_receivers(graph, batches.flat_map(&:receivers))
+        graph
+      end
+
+      def validate(graph, batches)
+        validate_exposures(graph, batches.flat_map(&:exposures))
+      end
+
+      private
+
+      def validate_exposures(graph, facts)
+        facts.group_by { |fact| fact.source.name }.each do |source, entries|
+          projections = entries.map { |fact| [exposure_owner_name(fact.owner), fact.scope] }
+          existing = graph.method_exposure(source)
+          projections << existing if existing
+          raise Error, "conflicting method exposure facts for #{source}" if projections.uniq.size > 1
+        end
+      end
+
+      def exposure_owner_name(owner)
+        owner.respond_to?(:name) ? owner.name : owner
+      end
+
+      # Existing dependency edges, keyed with and without their location, so
+      # each fact checks for a duplicate without scanning the whole graph.
+      def dependency_index(graph, batches)
+        sources = batches.flat_map { |batch| batch.references.map(&:source) + batch.mixins.map(&:owner) }
+                         .to_set(&:name)
+        return Set.new if sources.empty?
+
+        types = MIXIN_TYPES.values.to_set << :references_constant
+        graph.edges.each_with_object(Set.new) do |edge, index|
+          next unless sources.include?(edge.from_constant) && types.include?(edge.type)
+
+          key = [edge.type, edge.from_constant, edge.from_path, graph.resolve_edge_constant(edge)]
+          index << key << (key + [edge.location])
+        end
+      end
+
+      def add_dependency(graph, index, type, source, target, location, producer, match_location: true)
+        key = [type, source.name, source.path, target]
+        return unless index.add?(match_location ? key + [location] : key)
+
+        index << key << (key + [location])
+        graph.add_edge(type: type, from_path: source.path, from_constant: source.name,
+          to: target, resolved_to: target, location: location, producer: producer)
+      end
+
+      # A producer that observed what a static gap left open settles it, so
+      # the gap no longer counts against the analysis.
+      def resolve_gaps(graph, facts)
+        return if facts.empty?
+
+        resolved = facts.group_by { |fact| [fact.source.name, fact.source.path, fact.location] }
+        graph.edges.reject! do |edge|
+          edge.type == :dynamic_feature &&
+            resolved.fetch([edge.from_constant, edge.from_path, edge.location], []).any? do |fact|
+              fact.message.nil? || edge.to == fact.message
+            end
+        end
+      end
+
+      def install_method(fact)
+        owner = fact.owner
+        definition = fact.definition
+        existing = owner.method_definitions.select do |method|
+          method.name == definition.name && method.scope == definition.scope
+        end
+        return if fact.mode == :if_missing && existing.any?
+
+        if fact.mode == :define
+          return if existing.any? do |method|
+            method.location.path == owner.path && fact.installation.path == owner.path &&
+              ([method.location.line, method.location.column] <=>
+               [fact.installation.line, fact.installation.column]).positive?
+          end
+
+          owner.method_definitions.reject! { |method| existing.include?(method) }
+        end
+        return if owner.method_definitions.include?(definition)
+
+        owner.method_definitions << definition
+        (definition.scope == :class ? owner.class_methods : owner.instance_methods).add(definition.name)
+      end
+
+      def bind_receivers(graph, facts)
+        return if facts.empty?
+
+        groups = facts.group_by { |fact| [fact.source.name, fact.source.path, fact.name, fact.location] }
+        sources = facts.to_set { |fact| fact.source.name }
+        seen = Set.new
+        edges = graph.edges.flat_map do |edge|
+          next edge unless sources.include?(edge.from_constant) && edge.type == :calls_named_method && edge.receiver == :none
+
+          key = [edge.from_constant, edge.from_path, edge.to, edge.location]
+          bindings = groups[key]
+          next edge unless bindings
+
+          bindings.filter_map do |fact|
+            next unless seen.add?([key, fact.receiver, fact.scope])
+
+            edge.with(resolved_receiver: fact.receiver, receiver_scope: fact.scope,
+              resolved_method: graph.resolve_method_alias(fact.receiver, edge.to, fact.scope))
+          end
+        end
+        graph.edges.replace(edges)
+      end
+    end
+  end
+end