archunit 0.0.1 → 1.0.0

data/lib/archunit/extraction/conservative_local_flow.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Extraction
+    # Keeps local-string inference inside straight-line code and lexical scopes.
+    module ConservativeLocalFlow
+      def visit_def_node(node)
+        @local_strings.isolated_scope { super }
+      end
+
+      def visit_class_node(node)
+        @local_strings.isolated_scope { super }
+      end
+
+      def visit_module_node(node)
+        @local_strings.isolated_scope { super }
+      end
+
+      def visit_singleton_class_node(node)
+        @local_strings.isolated_scope { super }
+      end
+
+      def visit_block_node(node)
+        @local_strings.isolated_scope { super }
+        @local_strings.capture_scopes
+      end
+
+      def visit_lambda_node(node)
+        @local_strings.isolated_scope { super }
+        @local_strings.capture_scopes
+      end
+
+      def visit_local_variable_operator_write_node(node)
+        super
+        @local_strings.assign(node.name, nil)
+      end
+
+      def visit_local_variable_or_write_node(node)
+        super
+        @local_strings.assign(node.name, nil)
+      end
+
+      def visit_local_variable_and_write_node(node)
+        super
+        @local_strings.assign(node.name, nil)
+      end
+
+      def visit_multi_write_node(node)
+        super
+        @local_strings.invalidate_all
+      end
+
+      def visit_post_execution_node(node)
+        @local_strings.uncertain_flow { super }
+        @local_strings.capture_scopes
+      end
+
+      def visit_match_write_node(node)
+        super
+        @local_strings.invalidate_all
+      end
+
+      def visit_instance_variable_write_node(node)
+        super
+        @local_strings.invalidate_escaped(node.value)
+      end
+
+      def visit_global_variable_write_node(node)
+        super
+        @local_strings.invalidate_escaped(node.value)
+      end
+
+      def visit_class_variable_write_node(node)
+        super
+        @local_strings.invalidate_escaped(node.value)
+      end
+
+      def visit_constant_write_node(node)
+        super
+        @local_strings.invalidate_escaped(node.value)
+      end
+
+      def visit_constant_path_write_node(node)
+        super
+        @local_strings.invalidate_escaped(node.value)
+      end
+
+      # These constructs require control-flow analysis beyond the supported straight-line subset.
+      %i[
+        begin defined pre_execution if unless and or case case_match while until for
+        rescue rescue_modifier
+      ].each do |kind|
+        define_method("visit_#{kind}_node") do |node|
+          @local_strings.uncertain_flow { super(node) }
+        end
+      end
+    end
+    private_constant :ConservativeLocalFlow
+  end
+end

data/lib/archunit/extraction/constant_index.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative '../common/extraction/edge'
+require_relative 'constant_visitor'
+
+module ArchUnit
+  module Extraction
+    # Bounded project definition index. Unknown/ambiguous names never invent file targets.
+    class ConstantIndex
+      Location = Data.define(:source, :line_number)
+      MAX_NAMESPACE_PASSES = 8
+
+      def initialize(analyses, profile: nil)
+        @analyses = analyses
+        @profile = profile
+        @visitors = stabilized_visitors
+        @definitions = definition_locations
+        @namespaces = namespace_names(@visitors)
+        @inherited_namespaces = @visitors.values.flat_map(&:inherited_namespaces).to_set
+      end
+
+      def edges
+        @visitors.flat_map do |source, visitor|
+          visitor.references.filter_map { |reference| resolve_edge(source, reference) }
+        end
+      end
+
+      private
+
+      def stabilized_visitors
+        visitors = collect
+        MAX_NAMESPACE_PASSES.times do
+          names = namespace_names(visitors)
+          visitors = collect(namespace_names: names)
+          return visitors if namespace_names(visitors) == names
+        end
+        unresolved_count = visitors.values.sum { |visitor| visitor.references.length }
+        @profile&.increment(:unresolved_constant_references, unresolved_count)
+        {}
+      end
+
+      def collect(namespace_names: nil)
+        @analyses.to_h do |source, result|
+          visitor = ConstantVisitor.new(namespace_names:)
+          visitor.visit(result.value)
+          [source, visitor]
+        end
+      end
+
+      def namespace_names(visitors)
+        visitors.values.flat_map(&:definitions).each_with_object(Set.new) do |definition, names|
+          parts = definition.name.split('::')
+          parts.length.times { |index| names << parts.take(index + 1).join('::') }
+        end
+      end
+
+      def definition_locations
+        map = Hash.new { |hash, key| hash[key] = [] }
+        @visitors.each do |source, visitor|
+          visitor.definitions.each do |definition|
+            map[definition.name] << Location.new(source:, line_number: definition.line_number)
+          end
+        end
+        map
+      end
+
+      def resolve_edge(source, reference)
+        name = resolve_name(reference)
+        locations = name ? @definitions.fetch(name, []) : []
+        return unresolved(:unresolved_constant_references) if locations.empty?
+        return unresolved(:ambiguous_constant_references) if locations.map(&:source).uniq.length > 1
+
+        location = locations.first
+        return if source == location.source
+
+        evidence_edge(source, reference, location)
+      end
+
+      def resolve_name(reference)
+        name = reference.name
+        return name.delete_prefix('::') if name.start_with?('::')
+
+        head = name.split('::').first
+        owner = reference.nesting.find { |scope| @namespaces.include?("#{scope}::#{head}") }
+        return "#{owner}::#{name}" if owner
+        return if @inherited_namespaces.include?(reference.inherited_scope)
+
+        name
+      end
+
+      def unresolved(counter)
+        @profile&.increment(counter)
+        nil
+      end
+
+      def evidence_edge(source, reference, location)
+        kind = Common::Extraction::ImportKind::CONSTANT_REFERENCE
+        evidence = Common::Extraction::DependencyEvidence.new(
+          source:, kind:, name: reference.name, line_number: reference.line_number,
+          end_line: reference.end_line, target_line_number: location.line_number
+        )
+        Common::Extraction::Edge.new(
+          source:, target: location.source, external: false,
+          import_kinds: [kind], evidence: [evidence]
+        )
+      end
+    end
+    private_constant :ConstantIndex
+  end
+end

data/lib/archunit/extraction/constant_visitor.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module ArchUnit
+  module Extraction
+    # Collects declarations and uses with Ruby's lexical (not textual path) nesting.
+    class ConstantVisitor < Prism::Visitor
+      Definition = Data.define(:name, :line_number)
+      Reference = Data.define(:name, :nesting, :inherited_scope, :line_number, :end_line)
+
+      attr_reader :definitions, :references, :inherited_namespaces
+
+      def initialize(namespace_names: nil)
+        super()
+        @namespace_names = namespace_names
+        @definitions = []
+        @references = []
+        @nesting = []
+        @inherited_namespaces = []
+      end
+
+      def visit_class_node(node)
+        visit(node.superclass)
+        visit_namespace(node, inherited: !node.superclass.nil?)
+      end
+
+      def visit_module_node(node)
+        visit_namespace(node, inherited: false)
+      end
+
+      def visit_constant_write_node(node)
+        define_constant(qualify(node.name.to_s), node)
+        visit(node.value)
+      end
+
+      def visit_constant_path_write_node(node)
+        name = static_name(node.target)
+        define_constant(declaration_name(name), node) if name
+        visit(node.value)
+      end
+
+      # ||= introduces a possible declaration, like a conditional ordinary assignment.
+      # This records ownership, not whether the branch executes or what value it stores.
+      alias visit_constant_or_write_node visit_constant_write_node
+      alias visit_constant_path_or_write_node visit_constant_path_write_node
+
+      def visit_constant_read_node(node)
+        record_reference(node.name.to_s, node)
+      end
+
+      def visit_constant_path_node(node)
+        name = static_name(node)
+        name ? record_reference(name, node) : super
+      end
+
+      def visit_call_node(node)
+        if %i[include prepend extend const_set remove_const autoload].include?(node.name) &&
+           !@nesting.empty?
+          @inherited_namespaces << @nesting.first
+        end
+        super
+      end
+
+      def visit_singleton_class_node(node)
+        visit(node.expression)
+        previous = @dynamic_scope
+        @dynamic_scope = true
+        visit(node.body)
+      ensure
+        @dynamic_scope = previous
+      end
+
+      private
+
+      def visit_namespace(node, inherited:)
+        name = static_name(node.constant_path)
+        return unless name
+
+        full_name = declaration_name(name)
+        define_constant(full_name, node.constant_path)
+        @inherited_namespaces << full_name if inherited
+        previous = @nesting
+        @nesting = [full_name, *previous]
+        visit(node.body)
+      ensure
+        @nesting = previous if previous
+      end
+
+      def declaration_name(name)
+        return name.delete_prefix('::') if name.start_with?('::') || @nesting.empty?
+        return qualify(name) unless name.include?('::')
+
+        head = name.split('::').first
+        owner = @nesting.find { |scope| @namespace_names&.include?("#{scope}::#{head}") }
+        owner ? "#{owner}::#{name}" : name
+      end
+
+      def qualify(name)
+        @nesting.empty? ? name : "#{@nesting.first}::#{name}"
+      end
+
+      def define_constant(name, node)
+        return if @dynamic_scope
+
+        @definitions << Definition.new(name:, line_number: node.location.start_line)
+      end
+
+      def record_reference(name, node)
+        return if @dynamic_scope && !name.start_with?('::')
+
+        @references << Reference.new(
+          name:, nesting: @nesting.dup.freeze, inherited_scope: @nesting.first,
+          line_number: node.location.start_line, end_line: node.location.end_line
+        )
+      end
+
+      def static_name(node)
+        return node.name.to_s if node.is_a?(Prism::ConstantReadNode)
+        return unless node.is_a?(Prism::ConstantPathNode)
+        return "::#{node.name}" if node.parent.nil?
+
+        parent = static_name(node.parent)
+        "#{parent}::#{node.name}" if parent
+      end
+    end
+    private_constant :ConstantVisitor
+  end
+end

data/lib/archunit/extraction/discover_gemspec_load_paths.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'find'
+require 'pathname'
+require_relative 'enumerate_source_files'
+
+module ArchUnit
+  module Extraction
+    # Discovers gem-adjacent lib directories without evaluating gemspecs.
+    module GemspecLoadPaths
+      module_function
+
+      def resolve(root, source_files: nil)
+        paths = if source_files
+                  discover_from_sources(root, source_files)
+                else
+                  discover_with_walk(root)
+                end
+        paths.uniq.sort_by { |path| normalized(path) }
+      end
+
+      def discover_from_sources(root, source_files)
+        roots = source_files.flat_map { |source| source_lib_roots(root, source) }.uniq
+        roots.flat_map do |gem_root|
+          gemspecs_in(gem_root).filter_map { |entry| gemspec_lib_path(entry, root) }
+        end
+      end
+      private_class_method :discover_from_sources
+
+      def source_lib_roots(root, source)
+        segments = source.split('/')
+        segments.each_index.filter_map do |index|
+          next unless segments[index] == 'lib'
+
+          index.zero? ? root : root.join(*segments.take(index))
+        end
+      end
+      private_class_method :source_lib_roots
+
+      def gemspecs_in(directory)
+        directory.children.select do |entry|
+          entry.file? && entry.extname == '.gemspec'
+        end
+      end
+      private_class_method :gemspecs_in
+
+      def discover_with_walk(root)
+        paths = []
+        Find.find(root.to_s) do |entry|
+          next if directory_entry?(entry, root)
+
+          lib = gemspec_lib_path(Pathname.new(entry), root)
+          paths << lib if lib
+        end
+        paths
+      end
+      private_class_method :discover_with_walk
+
+      def directory_entry?(entry, root)
+        return false unless File.directory?(entry)
+
+        Find.prune if entry != root.to_s && excluded_directory?(entry)
+        true
+      end
+      private_class_method :directory_entry?
+
+      def gemspec_lib_path(entry, root)
+        return unless entry.extname == '.gemspec'
+
+        lib = entry.dirname.join('lib')
+        return unless lib.directory?
+
+        canonical = lib.realpath
+        canonical if within_project?(canonical, root)
+      end
+      private_class_method :gemspec_lib_path
+
+      def excluded_directory?(path)
+        Extraction::DEFAULT_EXCLUDED_DIRECTORIES.include?(File.basename(path))
+      end
+      private_class_method :excluded_directory?
+
+      def within_project?(path, root)
+        path.relative_path_from(root).each_filename.first != '..'
+      rescue ArgumentError
+        false
+      end
+      private_class_method :within_project?
+
+      def normalized(path)
+        path.to_s.tr('\\', '/')
+      end
+      private_class_method :normalized
+    end
+  end
+end

data/lib/archunit/extraction/enumerate_source_files.rb

@@ -4,9 +4,11 @@ require 'find'
 require 'pathname'
 require_relative '../error/technical_error'
 require_relative '../error/user_error'
+require_relative 'arch_ignore'
 
 module ArchUnit
   # Ruby-specific project discovery and source extraction.
+  # rubocop:disable-next Metrics/ModuleLength -- One source policy keeps graphs and metrics aligned.
   module Extraction
     DEFAULT_EXCLUDED_DIRECTORIES = %w[
       .bundle
@@ -30,22 +32,33 @@ module ArchUnit
 
     def enumerate_source_files(project_root, exclude_patterns: nil)
       root = source_root(project_root)
-      patterns = resolve_exclude_patterns(exclude_patterns)
+      patterns = resolve_project_exclude_patterns(root, exclude_patterns)
+      enumerate_source_files_with_patterns(root, patterns)
+    end
+
+    def enumerate_source_files_with_patterns(root, patterns)
       source_files_under(root, patterns).sort.freeze
     rescue UserError, TechnicalError
       raise
     rescue SystemCallError => e
       raise TechnicalError, "could not enumerate Ruby source files: #{e.message}"
     end
+    private_class_method :enumerate_source_files_with_patterns
+
+    def resolve_project_exclude_patterns(root, value)
+      configured = resolve_exclude_patterns(value)
+      resolve_exclude_patterns([*configured, *ArchIgnore.patterns(root)])
+    end
+    private_class_method :resolve_project_exclude_patterns
 
     def source_files_under(root, exclude_patterns)
       Find.find(root.to_s).filter_map do |entry|
-        if File.directory?(entry)
-          Find.prune if excluded_path?(entry, root, exclude_patterns)
-          next
-        end
+        stat = File.lstat(entry)
+        next if stat.symlink?
 
-        if ruby_source_file?(entry) && !excluded_path?(entry, root, exclude_patterns)
+        if stat.directory?
+          Find.prune if excluded_path?(entry, root, exclude_patterns)
+        elsif ruby_source_file?(entry, stat) && !excluded_path?(entry, root, exclude_patterns)
           relative_identifier(entry, root).freeze
         end
       end
@@ -85,8 +98,8 @@ module ArchUnit
     end
     private_class_method :normalize_exclude_pattern
 
-    def ruby_source_file?(entry)
-      File.file?(entry) && File.extname(entry) == '.rb'
+    def ruby_source_file?(entry, stat)
+      stat.file? && File.extname(entry) == '.rb'
     end
     private_class_method :ruby_source_file?
 
@@ -100,6 +113,8 @@ module ArchUnit
       raise UserError, 'project_root must be an existing directory' unless root.directory?
 
       root.realpath
+    rescue SystemCallError => e
+      raise TechnicalError, "could not enumerate Ruby source files: #{e.message}"
     end
     private_class_method :source_root
 

data/lib/archunit/extraction/extract_dependencies.rb

@@ -2,31 +2,91 @@
 
 require 'pathname'
 require_relative '../common/extraction/edge'
+require_relative '../common/fluentapi/check_options'
 require_relative 'enumerate_source_files'
 require_relative 'extract_imports'
+require_relative 'resolve_load_paths'
+require_relative 'constant_index'
 
 module ArchUnit
   # Turns statically resolvable Ruby imports into dependency edges.
   module Extraction
+    DependencyContext = Data.define(
+      :root, :targets, :load_paths, :profile, :cache, :include_evidence
+    )
+    private_constant :DependencyContext
+
     module_function
 
-    def extract_dependencies(project_root, exclude_patterns: nil)
+    def extract_dependencies(project_root, exclude_patterns: nil, options: nil)
+      options = Common::FluentApi::CheckOptions.resolve(options)
       source_files = enumerate_source_files(project_root, exclude_patterns:)
       root = Pathname.new(path_value(project_root)).expand_path.realpath
-      extract_dependencies_from(root, source_files)
+      load_paths = LoadPaths.resolve(
+        root, explicit_paths: options.load_paths, source_files:
+      )
+      extract_dependencies_from(root, source_files, load_paths:, options:)
     end
 
-    def extract_dependencies_from(root, source_files)
-      internal_targets = internal_target_index(root, source_files)
+    def extract_dependencies_from(root, source_files, load_paths:, options:, profile: nil)
+      context = DependencyContext.new(
+        root:, targets: profiled_target_index(root, source_files, profile), load_paths:,
+        profile:, cache: {}, include_evidence: options.constant_references?
+      )
 
-      source_files.flat_map do |source|
-        extract_imports(root.join(source), project_root: root).map do |import|
-          dependency_edge(source, import, internal_targets)
-        end
-      end.freeze
+      analyses = options.constant_references? ? parse_sources(root, source_files, profile) : {}
+      edges = source_files.flat_map do |source|
+        dependencies_for_source(source, context, analyses[source])
+      end
+      edges.concat(constant_edges(analyses, profile)) if options.constant_references?
+      edges.freeze
     end
     private_class_method :extract_dependencies_from
 
+    def profiled_target_index(root, source_files, profile)
+      ExtractionProfile.measure(profile, :target_index) do
+        internal_target_index(root, source_files)
+      end
+    end
+    private_class_method :profiled_target_index
+
+    def parse_sources(root, sources, profile)
+      sources.to_h { |source| [source, parse_source(root.join(source), profile)] }
+    end
+    private_class_method :parse_sources
+
+    def constant_edges(analyses, profile)
+      ExtractionProfile.measure(profile, :constant_indexing) do
+        ConstantIndex.new(analyses, profile:).edges
+      end
+    end
+    private_class_method :constant_edges
+
+    def dependencies_for_source(source, context, parse_result)
+      imports = extract_imports_from(
+        context.root.join(source),
+        project_root: context.root,
+        load_paths: context.load_paths,
+        profile: context.profile,
+        resolution_cache: context.cache,
+        parse_result:
+      )
+      context.profile&.increment(:imports, imports.length)
+      classify_imports(source, imports, context)
+    end
+    private_class_method :dependencies_for_source
+
+    def classify_imports(source, imports, context)
+      ExtractionProfile.measure(context.profile, :edge_classification) do
+        imports.map do |import|
+          dependency_edge(
+            source, import, context.targets, include_evidence: context.include_evidence
+          )
+        end
+      end
+    end
+    private_class_method :classify_imports
+
     def path_value(value)
       value.respond_to?(:to_path) ? value.to_path : value
     end
@@ -39,22 +99,30 @@ module ArchUnit
     end
     private_class_method :internal_target_index
 
-    def dependency_edge(source, import, internal_targets)
+    def dependency_edge(source, import, internal_targets, include_evidence:)
       target = import.resolved_path && internal_targets[canonical_path(import.resolved_path)]
 
       Common::Extraction::Edge.new(
         source: source,
         target: target || import.module_name,
         external: target.nil?,
-        import_kinds: [import.import_kind]
+        import_kinds: [import.import_kind],
+        evidence: include_evidence ? [import_evidence(source, import)] : []
       )
     end
     private_class_method :dependency_edge
 
+    def import_evidence(source, import)
+      Common::Extraction::DependencyEvidence.new(
+        source:, kind: import.import_kind, name: import.module_name,
+        line_number: import.line_number, end_line: import.end_line
+      )
+    end
+    private_class_method :import_evidence
+
     def canonical_path(path)
-      Pathname.new(path).realpath.to_s.tr('\\', '/')
-    rescue SystemCallError
-      Pathname.new(path).expand_path.to_s.tr('\\', '/')
+      normalized = Pathname.new(path).expand_path.cleanpath.to_s.tr('\\', '/')
+      File::FNM_SYSCASE.zero? ? normalized : normalized.downcase
     end
     private_class_method :canonical_path
   end