archunit 0.0.1

data/lib/archunit/common/projection/edge_projections.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'mapped_edge'
+
+module ArchUnit
+  module Common
+    # Reusable edge-to-label mapping functions for shared graph projections.
+    module Projection
+      module_function
+
+      # Maps every non-self edge without changing its labels.
+      def per_edge
+        lambda do |edge|
+          next if edge.source == edge.target
+
+          map_identity(edge)
+        end
+      end
+
+      # Maps non-self edges whose targets are part of the extracted project.
+      def per_internal_edge
+        lambda do |edge|
+          next if edge.external || edge.source == edge.target
+
+          map_identity(edge)
+        end
+      end
+
+      # Maps non-self edges whose targets are outside the extracted project.
+      def per_external_edge
+        lambda do |edge|
+          next unless edge.external
+          next if edge.source == edge.target
+
+          map_identity(edge)
+        end
+      end
+
+      # Maps an edge without filtering, including source-file self-edges.
+      def identity
+        ->(edge) { map_identity(edge) }
+      end
+
+      def map_identity(edge)
+        MappedEdge.new(source_label: edge.source, target_label: edge.target)
+      end
+      private_class_method :map_identity
+    end
+  end
+end

data/lib/archunit/common/projection/mapped_edge.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Common
+    module Projection
+      # The labels produced when a raw dependency edge is mapped into a domain view.
+      MappedEdge = Data.define(:source_label, :target_label) do
+        def initialize(source_label:, target_label:)
+          source_label = immutable_label(source_label, :source_label)
+          target_label = immutable_label(target_label, :target_label)
+          super
+        end
+
+        private
+
+        def immutable_label(value, attribute)
+          unless value.is_a?(String) && !value.empty?
+            raise ArgumentError, "#{attribute} must be a non-empty String"
+          end
+
+          value.dup.freeze
+        end
+      end
+    end
+  end
+end

data/lib/archunit/common/projection/project_cycles.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative 'cycles/johnson_cycles'
+require_relative 'edge_projections'
+require_relative 'project_edges'
+require_relative 'projected_edge'
+
+module ArchUnit
+  module Common
+    # Cycle projection over immutable, evidence-retaining projected edges.
+    module Projection
+      module_function
+
+      def project_internal_cycles(graph)
+        project_cycles(project_edges(graph, per_internal_edge))
+      end
+
+      def project_cycles(edges)
+        projected_edges = normalize_projected_edges(edges)
+        label_ids = label_ids_for(projected_edges)
+        edges_by_ids = index_edges(projected_edges, label_ids)
+        paths = Cycles::JohnsonCycles.call(adjacency_for(edges_by_ids))
+        cycles_from_paths(paths, edges_by_ids)
+      end
+
+      def cycles_from_paths(paths, edges_by_ids)
+        paths.map do |path|
+          path.each_index.map do |index|
+            source = path.fetch(index)
+            target = path.fetch((index + 1) % path.length)
+            edges_by_ids.fetch([source, target])
+          end.freeze
+        end.freeze
+      end
+
+      def normalize_projected_edges(edges)
+        unless edges.respond_to?(:each)
+          raise ArgumentError, 'edges must be an enumerable of ProjectedEdge values'
+        end
+
+        groups = {}
+        edges.each { |edge| add_to_projection_groups(groups, edge) }
+        projected_edges_from(groups)
+      end
+      private_class_method :normalize_projected_edges
+
+      def add_to_projection_groups(groups, edge)
+        unless edge.is_a?(ProjectedEdge)
+          raise ArgumentError, 'edges must contain only ProjectedEdge values'
+        end
+        return if edge.source_label == edge.target_label
+
+        key = [edge.source_label, edge.target_label]
+        (groups[key] ||= []).concat(edge.cumulated_edges)
+      end
+      private_class_method :add_to_projection_groups
+
+      def projected_edges_from(groups)
+        groups.map do |(source_label, target_label), raw_edges|
+          ProjectedEdge.new(
+            source_label:, target_label:, cumulated_edges: raw_edges.uniq
+          )
+        end.freeze
+      end
+      private_class_method :projected_edges_from
+
+      def label_ids_for(edges)
+        labels = edges.flat_map { |edge| [edge.source_label, edge.target_label] }.uniq
+        labels.each_with_index.to_h.freeze
+      end
+      private_class_method :label_ids_for
+
+      def index_edges(edges, label_ids)
+        edges.to_h do |edge|
+          key = [label_ids.fetch(edge.source_label), label_ids.fetch(edge.target_label)]
+          [key, edge]
+        end.freeze
+      end
+      private_class_method :index_edges
+
+      def adjacency_for(edges_by_ids)
+        adjacency = Hash.new { |hash, vertex| hash[vertex] = [] }
+        edges_by_ids.each_key do |source, target|
+          adjacency[source] << target
+          adjacency[target] ||= []
+        end
+        adjacency.transform_values { |targets| targets.uniq.freeze }.freeze
+      end
+      private_class_method :adjacency_for
+    end
+  end
+end

data/lib/archunit/common/projection/project_edges.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative '../extraction/edge'
+require_relative 'mapped_edge'
+require_relative 'projected_edge'
+
+module ArchUnit
+  module Common
+    # Pure functions and immutable values for relabeling dependency graphs.
+    module Projection
+      module_function
+
+      # Applies a callable Edge -> MappedEdge/nil hook and cumulates equal labels.
+      def project_edges(graph, mapper = nil, &block)
+        map_function = resolve_map_function(mapper, block)
+        projection_groups(graph, map_function).map do |(source_label, target_label), edges|
+          ProjectedEdge.new(source_label:, target_label:, cumulated_edges: edges)
+        end.freeze
+      end
+
+      def projection_groups(graph, map_function)
+        groups = {}
+
+        each_edge(graph) do |edge|
+          mapped = map_function.call(edge)
+          next if mapped.nil?
+
+          validate_mapped_edge(mapped)
+          key = [mapped.source_label, mapped.target_label]
+          (groups[key] ||= []) << edge
+        end
+        groups
+      end
+      private_class_method :projection_groups
+
+      def resolve_map_function(mapper, block)
+        raise ArgumentError, 'provide a mapper or a block, not both' if mapper && block
+
+        map_function = mapper || block
+        return map_function if map_function.respond_to?(:call)
+
+        raise ArgumentError, 'mapper must be callable'
+      end
+      private_class_method :resolve_map_function
+
+      def each_edge(graph)
+        unless graph.respond_to?(:each)
+          raise ArgumentError, 'graph must be an enumerable of Edge values'
+        end
+
+        graph.each do |edge|
+          unless edge.is_a?(Extraction::Edge)
+            raise ArgumentError, 'graph must contain only Edge values'
+          end
+
+          yield edge
+        end
+      end
+      private_class_method :each_edge
+
+      def validate_mapped_edge(value)
+        return if value.is_a?(MappedEdge)
+
+        raise ArgumentError, 'mapper must return a MappedEdge or nil'
+      end
+      private_class_method :validate_mapped_edge
+    end
+  end
+end

data/lib/archunit/common/projection/project_to_nodes.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative '../extraction/edge'
+require_relative 'projected_node'
+require_relative 'project_edges'
+
+module ArchUnit
+  module Common
+    # Pure functions and immutable values for relabeling dependency graphs.
+    module Projection
+      module_function
+
+      def project_to_nodes(graph, include_externals: false)
+        validate_include_externals(include_externals)
+        labels, incoming, outgoing = collect_node_edges(graph, include_externals)
+
+        labels.keys.sort.map do |label|
+          ProjectedNode.new(label:, incoming: incoming[label], outgoing: outgoing[label])
+        end.freeze
+      end
+
+      def collect_node_edges(graph, include_externals)
+        incoming = Hash.new { |hash, label| hash[label] = [] }
+        outgoing = Hash.new { |hash, label| hash[label] = [] }
+        labels = {}
+
+        each_edge(graph) do |edge|
+          collect_node_edge(edge, labels, incoming, outgoing, include_externals)
+        end
+        [labels, incoming, outgoing]
+      end
+      private_class_method :collect_node_edges
+
+      def collect_node_edge(edge, labels, incoming, outgoing, include_externals)
+        labels[edge.source] = true
+        return if self_edge?(edge)
+
+        outgoing[edge.source] << edge
+        return if edge.external && !include_externals
+
+        labels[edge.target] = true
+        incoming[edge.target] << edge
+      end
+      private_class_method :collect_node_edge
+
+      def self_edge?(edge)
+        edge.source == edge.target
+      end
+      private_class_method :self_edge?
+
+      def validate_include_externals(value)
+        return if [true, false].include?(value)
+
+        raise ArgumentError, 'include_externals must be true or false'
+      end
+      private_class_method :validate_include_externals
+    end
+  end
+end

data/lib/archunit/common/projection/projected_edge.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../extraction/edge'
+require_relative 'mapped_edge'
+
+module ArchUnit
+  module Common
+    module Projection
+      # A labeled dependency that retains every raw edge collapsed into it.
+      ProjectedEdge = Data.define(:source_label, :target_label, :cumulated_edges) do
+        def initialize(source_label:, target_label:, cumulated_edges:)
+          mapped = MappedEdge.new(source_label:, target_label:)
+          cumulated_edges = immutable_edges(cumulated_edges)
+
+          super(
+            source_label: mapped.source_label,
+            target_label: mapped.target_label,
+            cumulated_edges:
+          )
+        end
+
+        private
+
+        def immutable_edges(values)
+          edges = Array(values).dup
+          unless edges.any? && edges.all?(Extraction::Edge)
+            raise ArgumentError, 'cumulated_edges must contain at least one Edge'
+          end
+
+          edges.freeze
+        end
+      end
+    end
+  end
+end

data/lib/archunit/common/projection/projected_node.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative '../extraction/edge'
+
+module ArchUnit
+  module Common
+    module Projection
+      # A graph node with its incoming and outgoing raw dependency edges.
+      ProjectedNode = Data.define(:label, :incoming, :outgoing) do
+        def initialize(label:, incoming: [], outgoing: [])
+          label = immutable_label(label)
+          incoming = immutable_edges(incoming, :incoming)
+          outgoing = immutable_edges(outgoing, :outgoing)
+          super
+        end
+
+        private
+
+        def immutable_label(value)
+          return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError, 'label must be a non-empty String'
+        end
+
+        def immutable_edges(values, attribute)
+          edges = Array(values).dup
+          unless edges.all?(Extraction::Edge)
+            raise ArgumentError, "#{attribute} must contain only Edge values"
+          end
+
+          edges.freeze
+        end
+      end
+    end
+  end
+end

data/lib/archunit/common/regex_factory.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative 'filter'
+require_relative 'pattern'
+
+module ArchUnit
+  module Common
+    # The single construction point for user patterns and their matching targets.
+    class RegexFactory
+      TARGETED_EXCLUSIONS = {
+        in_path: :path,
+        in_folder: :path_without_filename,
+        with_name: :filename,
+        for_classes_matching: :classname
+      }.freeze
+      DEFAULT_EXCLUSION_TARGETS = {
+        filename: %i[filename],
+        path: %i[path filename],
+        path_without_filename: %i[path path_without_filename filename],
+        classname: %i[classname]
+      }.freeze
+
+      class << self
+        def filename_matcher(pattern, except: nil)
+          create_matcher(pattern, :filename, except:)
+        end
+
+        def folder_matcher(pattern, except: nil)
+          create_matcher(pattern, :path_without_filename, except:)
+        end
+
+        def path_matcher(pattern, except: nil)
+          create_matcher(pattern, :path, except:)
+        end
+
+        def classname_matcher(pattern, except: nil)
+          create_matcher(pattern, :classname, except:)
+        end
+
+        def exact_file_matcher(file_path, except: nil)
+          unless file_path.is_a?(String) && !file_path.empty?
+            raise ArgumentError, 'file_path must be a non-empty String'
+          end
+
+          normalized_path = file_path.tr('\\', '/')
+          regexp = Regexp.new("\\A#{Regexp.escape(normalized_path)}\\z")
+          exclusions = create_exclusion_filters(:path, except)
+          Filter.new(regexp:, target: :path, matching: :exact, exclusions:)
+        end
+
+        private
+
+        def create_matcher(pattern, target, except:)
+          exclusions = create_exclusion_filters(target, except)
+          Filter.new(regexp: Pattern.compile(pattern), target:, exclusions:)
+        end
+
+        def create_exclusion_filters(parent_target, exclusion)
+          return [] if exclusion.nil?
+          return targeted_exclusion_filters(exclusion) if exclusion.is_a?(Hash)
+
+          exclusion_patterns(exclusion).flat_map do |pattern|
+            DEFAULT_EXCLUSION_TARGETS.fetch(parent_target).map do |target|
+              simple_filter(pattern, target)
+            end
+          end
+        end
+
+        def targeted_exclusion_filters(exclusion)
+          unknown = exclusion.keys - TARGETED_EXCLUSIONS.keys
+          unless unknown.empty?
+            raise ArgumentError, "unknown targeted exclusion: #{unknown.first.inspect}"
+          end
+
+          exclusion.flat_map do |name, patterns|
+            exclusion_patterns(patterns).map do |pattern|
+              simple_filter(pattern, TARGETED_EXCLUSIONS.fetch(name))
+            end
+          end
+        end
+
+        def exclusion_patterns(value)
+          values = value.is_a?(Array) ? value : [value]
+          values.each { |pattern| Pattern.compile(pattern) }
+          values
+        end
+
+        def simple_filter(pattern, target)
+          Filter.new(regexp: Pattern.compile(pattern), target:)
+        end
+      end
+
+      private_class_method :new
+    end
+  end
+end

data/lib/archunit/error/technical_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  # Raised when the library or its execution environment cannot complete an operation.
+  class TechnicalError < StandardError; end
+end

data/lib/archunit/error/user_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  # Raised when a caller uses the ArchUnit API incorrectly.
+  class UserError < StandardError; end
+end

data/lib/archunit/extraction/enumerate_source_files.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'find'
+require 'pathname'
+require_relative '../error/technical_error'
+require_relative '../error/user_error'
+
+module ArchUnit
+  # Ruby-specific project discovery and source extraction.
+  module Extraction
+    DEFAULT_EXCLUDED_DIRECTORIES = %w[
+      .bundle
+      .cache
+      .git
+      .hg
+      .ruby-lsp
+      .svn
+      .yardoc
+      build
+      coverage
+      dist
+      log
+      node_modules
+      pkg
+      tmp
+      vendor
+    ].freeze
+
+    module_function
+
+    def enumerate_source_files(project_root, exclude_patterns: nil)
+      root = source_root(project_root)
+      patterns = resolve_exclude_patterns(exclude_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
+
+    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
+
+        if ruby_source_file?(entry) && !excluded_path?(entry, root, exclude_patterns)
+          relative_identifier(entry, root).freeze
+        end
+      end
+    end
+    private_class_method :source_files_under
+
+    def resolve_exclude_patterns(value)
+      patterns = value.nil? ? DEFAULT_EXCLUDED_DIRECTORIES : value
+      validate_exclude_patterns(patterns)
+
+      normalized = patterns.map { |pattern| normalize_exclude_pattern(pattern) }
+      raise_invalid_exclude_patterns if normalized.any?(&:empty?)
+
+      normalized.uniq.freeze
+    end
+    private_class_method :resolve_exclude_patterns
+
+    def validate_exclude_patterns(patterns)
+      return if patterns.is_a?(Array) && patterns.all? { |pattern| valid_exclude_pattern?(pattern) }
+
+      raise_invalid_exclude_patterns
+    end
+    private_class_method :validate_exclude_patterns
+
+    def raise_invalid_exclude_patterns
+      raise UserError, 'exclude_patterns must be an Array of non-empty Strings'
+    end
+    private_class_method :raise_invalid_exclude_patterns
+
+    def valid_exclude_pattern?(pattern)
+      pattern.is_a?(String) && !pattern.empty?
+    end
+    private_class_method :valid_exclude_pattern?
+
+    def normalize_exclude_pattern(pattern)
+      pattern.tr('\\', '/').delete_prefix('./').delete_suffix('/').freeze
+    end
+    private_class_method :normalize_exclude_pattern
+
+    def ruby_source_file?(entry)
+      File.file?(entry) && File.extname(entry) == '.rb'
+    end
+    private_class_method :ruby_source_file?
+
+    def source_root(value)
+      value = value.to_path if value.respond_to?(:to_path)
+      unless value.is_a?(String) && !value.empty?
+        raise UserError, 'project_root must be a non-empty path'
+      end
+
+      root = Pathname.new(value).expand_path
+      raise UserError, 'project_root must be an existing directory' unless root.directory?
+
+      root.realpath
+    end
+    private_class_method :source_root
+
+    def excluded_path?(entry, root, exclude_patterns)
+      return false if entry == root.to_s
+
+      relative = relative_identifier(entry, root)
+      exclude_patterns.any? do |pattern|
+        exclude_pattern_matches?(pattern, relative, File.basename(entry))
+      end
+    end
+    private_class_method :excluded_path?
+
+    def exclude_pattern_matches?(pattern, relative, basename)
+      flags = File::FNM_DOTMATCH | File::FNM_PATHNAME
+      anchored = pattern.start_with?('/')
+      candidate = pattern.delete_prefix('/')
+      target = anchored || candidate.include?('/') ? relative : basename
+
+      File.fnmatch?(candidate, target, flags)
+    end
+    private_class_method :exclude_pattern_matches?
+
+    def relative_identifier(entry, root)
+      Pathname.new(entry).relative_path_from(root).to_s.tr('\\', '/')
+    end
+    private_class_method :relative_identifier
+  end
+end

data/lib/archunit/extraction/extract_dependencies.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative '../common/extraction/edge'
+require_relative 'enumerate_source_files'
+require_relative 'extract_imports'
+
+module ArchUnit
+  # Turns statically resolvable Ruby imports into dependency edges.
+  module Extraction
+    module_function
+
+    def extract_dependencies(project_root, exclude_patterns: nil)
+      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)
+    end
+
+    def extract_dependencies_from(root, source_files)
+      internal_targets = internal_target_index(root, source_files)
+
+      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
+    end
+    private_class_method :extract_dependencies_from
+
+    def path_value(value)
+      value.respond_to?(:to_path) ? value.to_path : value
+    end
+    private_class_method :path_value
+
+    def internal_target_index(root, source_files)
+      source_files.to_h do |identifier|
+        [canonical_path(root.join(identifier)), identifier]
+      end
+    end
+    private_class_method :internal_target_index
+
+    def dependency_edge(source, import, internal_targets)
+      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]
+      )
+    end
+    private_class_method :dependency_edge
+
+    def canonical_path(path)
+      Pathname.new(path).realpath.to_s.tr('\\', '/')
+    rescue SystemCallError
+      Pathname.new(path).expand_path.to_s.tr('\\', '/')
+    end
+    private_class_method :canonical_path
+  end
+end