archunit 0.0.1 → 1.0.0

data/lib/archunit/extraction/extract_graph.rb

@@ -4,9 +4,12 @@ require 'pathname'
 require_relative '../common/extraction/edge'
 require_relative '../common/extraction/graph'
 require_relative '../common/fluentapi/check_options'
+require_relative '../common/logging/inspection'
 require_relative 'enumerate_source_files'
 require_relative 'extract_dependencies'
+require_relative 'extraction_profile'
 require_relative 'locate_project'
+require_relative 'resolve_load_paths'
 
 module ArchUnit
   # Assembles the normalized dependency graph for a Ruby project.
@@ -17,16 +20,19 @@ module ArchUnit
     module_function
 
     def extract_graph(
-      locator = nil, exclude_patterns: nil, options: nil, working_directory: Dir.pwd
+      locator = nil, exclude_patterns: nil, options: nil, working_directory: Dir.pwd,
+      profile: nil
     )
+      ExtractionProfile.validate(profile)
       options = Common::FluentApi::CheckOptions.resolve(options)
-      root = Pathname.new(locate_project(locator, working_directory:))
-      patterns = resolve_exclude_patterns(exclude_patterns)
-      cache_key = graph_cache_key(root, exclude_patterns: patterns, options:)
+      ExtractionProfile.measure(profile, :total) do
+        root = ExtractionProfile.measure(profile, :project_discovery) do
+          Pathname.new(locate_project(locator, working_directory:))
+        end
+        patterns = resolve_project_exclude_patterns(root, exclude_patterns)
+        key = graph_cache_key(root, exclude_patterns: patterns, options:)
 
-      GRAPH_CACHE_MUTEX.synchronize do
-        graph_cache.delete(cache_key) if options.clear_cache?
-        graph_cache[cache_key] ||= extract_graph_uncached(root, patterns)
+        Common::Logging::Inspection.graph(fetch_graph(root, patterns, options, key, profile), root:)
       end
     end
 
@@ -35,14 +41,51 @@ module ArchUnit
       nil
     end
 
-    def extract_graph_uncached(root, exclude_patterns)
-      source_files = enumerate_source_files(root, exclude_patterns:)
-      edges = self_edges(source_files) + extract_dependencies_from(root, source_files)
+    def fetch_graph(root, patterns, options, cache_key, profile)
+      GRAPH_CACHE_MUTEX.synchronize do
+        graph_cache.delete(cache_key) if options.clear_cache?
+        cached = graph_cache[cache_key]
+        if cached
+          profile&.record_cache_hit
+          return cached
+        end
+
+        graph_cache[cache_key] = extract_graph_uncached(root, patterns, options, profile)
+      end
+    end
+    private_class_method :fetch_graph
 
-      Common::Extraction::Graph.new(merge_parallel_edges(edges))
+    def extract_graph_uncached(root, exclude_patterns, options, profile)
+      source_files = ExtractionProfile.measure(profile, :source_enumeration) do
+        enumerate_source_files_with_patterns(root, exclude_patterns)
+      end
+      profile&.increment(:source_files, source_files.length)
+      load_paths = ExtractionProfile.measure(profile, :load_path_discovery) do
+        LoadPaths.resolve(root, explicit_paths: options.load_paths, source_files:)
+      end
+      edges = extraction_edges(root, source_files, load_paths, options, profile)
+      graph_from_edges(edges, profile)
     end
     private_class_method :extract_graph_uncached
 
+    def extraction_edges(root, source_files, load_paths, options, profile)
+      edges = self_edges(source_files) + extract_dependencies_from(
+        root, source_files, load_paths:, profile:, options:
+      )
+      profile&.increment(:raw_edges, edges.length)
+      edges
+    end
+    private_class_method :extraction_edges
+
+    def graph_from_edges(edges, profile)
+      merged = ExtractionProfile.measure(profile, :edge_merge) do
+        merge_parallel_edges(edges)
+      end
+      profile&.increment(:merged_edges, merged.length)
+      Common::Extraction::Graph.new(merged)
+    end
+    private_class_method :graph_from_edges
+
     def graph_cache_key(project_root, exclude_patterns:, options:)
       [
         project_root.to_s.tr('\\', '/').freeze,
@@ -80,7 +123,8 @@ module ArchUnit
           source: first.source,
           target: first.target,
           external: first.external,
-          import_kinds: parallel_edges.flat_map(&:import_kinds)
+          import_kinds: parallel_edges.flat_map(&:import_kinds),
+          evidence: parallel_edges.flat_map(&:evidence)
         )
       end
     end

data/lib/archunit/extraction/extract_imports.rb

@@ -1,109 +1,80 @@
 # frozen_string_literal: true
 
-require 'pathname'
 require 'prism'
 require_relative '../error/technical_error'
+require_relative '../error/source_parse_error'
 require_relative '../error/user_error'
-require_relative 'resolve_import'
+require_relative 'extraction_profile'
+require_relative 'import_resolver'
+require_relative 'import_visitor'
 require_relative 'resolved_import'
+require_relative 'validate_extraction_paths'
 
 module ArchUnit
   # Parses Ruby source without executing it and resolves literal imports.
   module Extraction
     IGNORE_DIRECTIVE = /\A#\s*archunit:\s*ignore(?:\s+(?<modules>.+?))?\s*\z/
 
-    # Collects supported dependency calls from a Prism syntax tree.
-    class ImportVisitor < Prism::Visitor
-      CALL_KINDS = {
-        require: Common::Extraction::ImportKind::REQUIRE,
-        require_relative: Common::Extraction::ImportKind::REQUIRE_RELATIVE,
-        autoload: Common::Extraction::ImportKind::AUTOLOAD,
-        load: Common::Extraction::ImportKind::LOAD
-      }.freeze
-
-      attr_reader :imports
-
-      def initialize
-        super
-        @imports = []
-      end
-
-      def visit_call_node(node)
-        record_import(node)
-        super
-      end
-
-      private
-
-      def record_import(node)
-        import_kind = CALL_KINDS[node.name]
-        return unless import_kind && supported_receiver?(node, import_kind)
-
-        arguments = node.arguments&.arguments || []
-        argument = import_argument(arguments, import_kind)
-        return unless argument.is_a?(Prism::StringNode)
-        return unless valid_module_name?(argument.unescaped)
-
-        @imports << located_import(argument, import_kind, node)
-      end
-
-      def located_import(argument, import_kind, node)
-        [argument.unescaped, import_kind, node.location.start_line, node.location.end_line]
-      end
-
-      def valid_module_name?(module_name)
-        !module_name.empty? && !module_name.include?("\0")
-      end
-
-      def supported_receiver?(node, import_kind)
-        return true if node.receiver.nil?
-        if import_kind == Common::Extraction::ImportKind::AUTOLOAD
-          return constant_receiver?(node.receiver)
-        end
-
-        node.receiver.respond_to?(:full_name) &&
-          node.receiver.full_name.delete_prefix('::') == 'Kernel'
-      end
-
-      def constant_receiver?(receiver)
-        receiver.is_a?(Prism::ConstantReadNode) || receiver.is_a?(Prism::ConstantPathNode)
-      end
-
-      def import_argument(arguments, import_kind)
-        if import_kind == Common::Extraction::ImportKind::AUTOLOAD
-          return unless arguments.length == 2
-
-          arguments[1]
-        else
-          return unless arguments.length == 1
-
-          arguments[0]
-        end
-      end
-    end
-    private_constant :ImportVisitor
-
     module_function
 
-    def extract_imports(source_file, project_root:)
-      source_path = import_source_path(source_file)
-      root = import_project_root(project_root)
-      parsed_imports(source_path).map do |located_import|
-        resolved_import(located_import, source_path, root)
-      end.freeze
+    def extract_imports(
+      source_file, project_root:, load_paths: nil, profile: nil, resolution_cache: nil
+    )
+      source_path = ExtractionPaths.source_file(source_file)
+      root = ExtractionPaths.project_root(project_root)
+      extract_imports_from(
+        source_path, project_root: root, load_paths:, profile:, resolution_cache:
+      )
     rescue UserError
       raise
     rescue SystemCallError => e
       raise TechnicalError, "could not parse Ruby source file: #{e.message}"
     end
 
-    def parsed_imports(source_path)
-      parse_result = Prism.parse_file(source_path.to_s)
-      return [] unless parse_result.success?
+    # Share the parsed AST with constant analysis.
+    def extract_imports_from( # rubocop:disable Metrics/ParameterLists
+      source_path, project_root:, load_paths: nil, profile: nil, resolution_cache: nil,
+      parse_result: nil
+    )
+      resolver = build_import_resolver(
+        source_path:, project_root:, load_paths:, profile:, cache: resolution_cache
+      )
+      parse_result ||= parse_source(source_path, profile)
+      resolve_imports(parsed_imports(parse_result, profile), resolver)
+    rescue SystemCallError => e
+      raise TechnicalError, "could not parse Ruby source file: #{e.message}"
+    end
+    private_class_method :extract_imports_from
+
+    def build_import_resolver(**)
+      ImportResolver.new(**)
+    end
+    private_class_method :build_import_resolver
+
+    def resolve_imports(imports, resolver)
+      imports.map { |import| resolved_import(import, resolver) }.freeze
+    end
+    private_class_method :resolve_imports
 
-      visitor = ImportVisitor.new
-      visitor.visit(parse_result.value)
-      reject_ignored_imports(visitor.imports, parse_result.comments)
+    def parse_source(source_path, profile)
+      source = ExtractionProfile.measure(profile, :file_read) { File.binread(source_path) }
+      result = ExtractionProfile.measure(profile, :prism_parse) do
+        Prism.parse(source, filepath: source_path.to_s)
+      end
+      profile&.increment(:malformed_files) unless result.success?
+      SourceParseError.validate!(result, path: source_path)
+    rescue SystemCallError => e
+      raise TechnicalError, "could not parse Ruby source file: #{e.message}"
+    end
+    private_class_method :parse_source
+
+    def parsed_imports(parse_result, profile)
+      ExtractionProfile.measure(profile, :import_extraction) do
+        visitor = ImportVisitor.new
+        visitor.visit(parse_result.value)
+        profile&.increment(:unresolved_imports, visitor.unresolved_imports)
+        reject_ignored_imports(visitor.imports, parse_result.comments)
+      end
     end
     private_class_method :parsed_imports
 
@@ -147,51 +118,16 @@ module ArchUnit
     end
     private_class_method :ignored_module?
 
-    def resolved_import(located_import, source_path, root)
-      module_name, import_kind, line_number, = located_import
+    def resolved_import(located_import, resolver)
+      module_name, import_kind, line_number, end_line = located_import
       ResolvedImport.new(
         module_name: module_name,
         import_kind: import_kind,
         line_number: line_number,
-        resolved_path: resolve_import_for(module_name, import_kind, source_path, root)
+        end_line: end_line,
+        resolved_path: resolver.resolve(module_name, import_kind)
       )
     end
     private_class_method :resolved_import
-
-    def resolve_import_for(module_name, import_kind, source_path, root)
-      resolve_import(
-        module_name,
-        source_file: source_path,
-        project_root: root,
-        import_kind: import_kind
-      )
-    end
-    private_class_method :resolve_import_for
-
-    def import_source_path(value)
-      path = extraction_path(value, 'source_file')
-      raise UserError, 'source_file must be an existing file' unless path.file?
-
-      path
-    end
-    private_class_method :import_source_path
-
-    def import_project_root(value)
-      path = extraction_path(value, 'project_root')
-      raise UserError, 'project_root must be an existing directory' unless path.directory?
-
-      path.realpath
-    end
-    private_class_method :import_project_root
-
-    def extraction_path(value, attribute)
-      value = value.to_path if value.respond_to?(:to_path)
-      unless value.is_a?(String) && !value.empty?
-        raise UserError, "#{attribute} must be a non-empty path"
-      end
-
-      Pathname.new(value).expand_path
-    end
-    private_class_method :extraction_path
   end
 end

data/lib/archunit/extraction/extraction_profile.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Extraction
+    # Mutable per-run timing and counter collector for cold/warm extraction benchmarks.
+    class ExtractionProfile
+      STAGES = %i[
+        total
+        project_discovery
+        source_enumeration
+        load_path_discovery
+        file_read
+        prism_parse
+        import_extraction
+        constant_indexing
+        target_resolution
+        target_index
+        edge_classification
+        edge_merge
+      ].freeze
+      COUNTERS = %i[
+        source_files
+        malformed_files
+        imports
+        unresolved_imports
+        unresolved_constant_references
+        ambiguous_constant_references
+        resolution_cache_hits
+        resolution_cache_misses
+        raw_edges
+        merged_edges
+      ].freeze
+
+      attr_reader :stage_seconds, :counters
+
+      def self.measure(profile, stage, &operation)
+        return operation.call unless profile
+
+        profile.measure(stage, &operation)
+      end
+
+      def self.validate(value)
+        return if value.nil? || value.is_a?(self)
+
+        raise ArgumentError, 'profile must be an ExtractionProfile value or nil'
+      end
+
+      def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        raise ArgumentError, 'clock must respond to call' unless clock.respond_to?(:call)
+
+        @clock = clock
+        @stage_seconds = STAGES.to_h { |stage| [stage, 0.0] }
+        @counters = COUNTERS.to_h { |counter| [counter, 0] }
+        @cache_hit = false
+      end
+
+      def measure(stage)
+        validate_stage(stage)
+        started_at = @clock.call
+        yield
+      ensure
+        @stage_seconds[stage] += @clock.call - started_at if started_at
+      end
+
+      def increment(counter, amount = 1)
+        validate_counter(counter)
+        unless amount.is_a?(Integer) && !amount.negative?
+          raise ArgumentError, 'counter amount must be a non-negative Integer'
+        end
+
+        @counters[counter] += amount
+      end
+
+      def record_cache_hit
+        @cache_hit = true
+      end
+
+      def cache_hit?
+        @cache_hit
+      end
+
+      def to_h
+        {
+          cache_hit: cache_hit?,
+          stage_seconds: stage_seconds.transform_values { |value| value.round(6) },
+          counters: counters.dup
+        }
+      end
+
+      private
+
+      def validate_stage(stage)
+        return if STAGES.include?(stage)
+
+        raise ArgumentError, "unknown extraction stage: #{stage.inspect}"
+      end
+
+      def validate_counter(counter)
+        return if COUNTERS.include?(counter)
+
+        raise ArgumentError, "unknown extraction counter: #{counter.inspect}"
+      end
+    end
+  end
+end

data/lib/archunit/extraction/import_resolver.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative '../common/extraction/import_kind'
+require_relative 'extraction_profile'
+require_relative 'resolve_import'
+
+module ArchUnit
+  module Extraction
+    # Resolves one source file's imports and reuses context-independent feature lookups.
+    class ImportResolver
+      def initialize(source_path:, project_root:, load_paths:, profile: nil, cache: nil)
+        @source_path = source_path
+        @project_root = project_root
+        @load_paths = load_paths
+        @profile = profile
+        @cache = cache
+      end
+
+      def resolve(module_name, import_kind)
+        key = cache_key(module_name, import_kind)
+        return cached_resolution(key) if @cache&.key?(key)
+
+        @profile&.increment(:resolution_cache_misses) if @cache
+        resolution = uncached_resolution(module_name, import_kind)
+        @cache[key] = resolution if @cache
+        resolution
+      end
+
+      private
+
+      def cached_resolution(key)
+        @profile&.increment(:resolution_cache_hits)
+        @cache[key]
+      end
+
+      def uncached_resolution(module_name, import_kind)
+        ExtractionProfile.measure(@profile, :target_resolution) do
+          Extraction.resolve_import(
+            module_name,
+            source_file: @source_path,
+            project_root: @project_root,
+            import_kind:,
+            load_paths: @load_paths
+          )
+        end
+      end
+
+      def cache_key(module_name, import_kind)
+        source_context = if import_kind == Common::Extraction::ImportKind::REQUIRE_RELATIVE
+                           File.dirname(@source_path.to_s)
+                         end
+        [module_name, import_kind, source_context].freeze
+      end
+    end
+  end
+end

data/lib/archunit/extraction/import_visitor.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'prism'
+require_relative '../common/extraction/import_kind'
+require_relative 'conservative_local_flow'
+require_relative 'local_string_tracker'
+
+module ArchUnit
+  module Extraction
+    # Collects supported dependency calls from a Prism syntax tree.
+    class ImportVisitor < Prism::Visitor
+      include ConservativeLocalFlow
+
+      CALL_KINDS = {
+        require: Common::Extraction::ImportKind::REQUIRE,
+        require_relative: Common::Extraction::ImportKind::REQUIRE_RELATIVE,
+        autoload: Common::Extraction::ImportKind::AUTOLOAD,
+        load: Common::Extraction::ImportKind::LOAD
+      }.freeze
+
+      attr_reader :imports, :unresolved_imports
+
+      def initialize
+        super
+        @imports = []
+        @unresolved_imports = 0
+        @local_strings = LocalStringTracker.new
+      end
+
+      def visit_call_node(node)
+        import_call = supported_import_call?(node)
+        record_import(node) if import_call
+        super
+        invalidate_escaped_locals(node) unless import_call
+      end
+
+      def visit_local_variable_write_node(node)
+        super
+        @local_strings.assign(node.name, node.value)
+      end
+
+      private
+
+      def record_import(node)
+        import_kind = CALL_KINDS[node.name]
+        arguments = node.arguments&.arguments || []
+        argument = import_argument(arguments, import_kind)
+        module_name = @local_strings.resolve(argument)
+        unless valid_module_name?(module_name)
+          @unresolved_imports += 1
+          return
+        end
+
+        @imports << located_import(module_name, import_kind, node)
+      end
+
+      def located_import(module_name, import_kind, node)
+        [module_name, import_kind, node.location.start_line, node.location.end_line]
+      end
+
+      def valid_module_name?(module_name)
+        module_name.is_a?(String) && !module_name.empty? && !module_name.include?("\0")
+      end
+
+      def supported_import_call?(node)
+        import_kind = CALL_KINDS[node.name]
+        import_kind && supported_receiver?(node, import_kind) &&
+          !import_argument(node.arguments&.arguments || [], import_kind).nil?
+      end
+
+      def supported_receiver?(node, import_kind)
+        return true if node.receiver.nil?
+        if import_kind == Common::Extraction::ImportKind::AUTOLOAD
+          return constant_receiver?(node.receiver)
+        end
+
+        node.receiver.respond_to?(:full_name) &&
+          node.receiver.full_name.delete_prefix('::') == 'Kernel'
+      end
+
+      def constant_receiver?(receiver)
+        receiver.is_a?(Prism::ConstantReadNode) || receiver.is_a?(Prism::ConstantPathNode)
+      end
+
+      def import_argument(arguments, import_kind)
+        if import_kind == Common::Extraction::ImportKind::AUTOLOAD
+          return unless arguments.length == 2
+
+          arguments[1]
+        else
+          return unless arguments.length == 1
+
+          arguments[0]
+        end
+      end
+
+      def invalidate_escaped_locals(node)
+        @local_strings.invalidate_escaped(node)
+        @local_strings.capture_scopes if %i[eval binding local_variable_set].include?(node.name)
+      end
+    end
+    private_constant :ImportVisitor
+  end
+end

data/lib/archunit/extraction/local_string_tracker.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module ArchUnit
+  module Extraction
+    # Conservatively tracks local variables whose current value is a literal String.
+    class LocalStringTracker
+      UNKNOWN = Object.new.freeze
+      private_constant :UNKNOWN
+
+      def initialize
+        @scopes = [{}]
+        @captured_scopes = [false]
+        @uncertain_depth = 0
+      end
+
+      def resolve(node)
+        return node.unescaped if node.is_a?(Prism::StringNode)
+        return UNKNOWN if @uncertain_depth.positive? || @captured_scopes.last
+        return scope.fetch(node.name, UNKNOWN) if node.is_a?(Prism::LocalVariableReadNode)
+
+        UNKNOWN
+      end
+
+      def assign(name, value)
+        invalidate_escaped(value) if value && !value.is_a?(Prism::StringNode)
+        scope[name] = resolve(value)
+      end
+
+      def invalidate_escaped(node)
+        local_reads(node).each { |name| scope[name] = UNKNOWN if scope.key?(name) }
+      end
+
+      def isolated_scope
+        @scopes << {}
+        @captured_scopes << false
+        yield
+      ensure
+        @scopes.pop
+        @captured_scopes.pop
+      end
+
+      def invalidate_all
+        @scopes.each { |values| values.transform_values! { UNKNOWN } }
+      end
+
+      def capture_scopes
+        @captured_scopes.map! { true }
+        invalidate_all
+      end
+
+      def uncertain_flow
+        invalidate_scope
+        @uncertain_depth += 1
+        yield
+      ensure
+        @uncertain_depth -= 1
+        invalidate_scope
+      end
+
+      private
+
+      def local_reads(node)
+        return [node.name] if node.is_a?(Prism::LocalVariableReadNode)
+
+        node.compact_child_nodes.flat_map { |child| local_reads(child) }.uniq
+      end
+
+      def invalidate_scope
+        scope.transform_values! { UNKNOWN }
+      end
+
+      def scope
+        @scopes.last
+      end
+    end
+    private_constant :LocalStringTracker
+  end
+end

data/lib/archunit/extraction/resolve_import.rb

@@ -8,8 +8,8 @@ module ArchUnit
   module Extraction
     module_function
 
-    def resolve_import(module_name, source_file:, project_root:, import_kind:)
-      roots = import_search_roots(source_file, project_root, import_kind)
+    def resolve_import(module_name, source_file:, project_root:, import_kind:, load_paths: nil)
+      roots = import_search_roots(source_file, project_root, import_kind, load_paths)
       resolved = if import_kind == Common::Extraction::ImportKind::LOAD
                    resolve_load(module_name, roots, import_kind)
                  else
@@ -19,9 +19,11 @@ module ArchUnit
       resolved&.tr('\\', '/')&.freeze
     end
 
-    def import_search_roots(source_file, project_root, import_kind)
+    def import_search_roots(source_file, project_root, import_kind, load_paths)
       if import_kind == Common::Extraction::ImportKind::REQUIRE_RELATIVE
         [File.dirname(File.expand_path(source_file))]
+      elsif load_paths
+        load_paths
       else
         root = File.expand_path(project_root)
         [File.join(root, 'lib'), root]