archunit 0.0.1

data/lib/archunit/extraction/extract_graph.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative '../common/extraction/edge'
+require_relative '../common/extraction/graph'
+require_relative '../common/fluentapi/check_options'
+require_relative 'enumerate_source_files'
+require_relative 'extract_dependencies'
+require_relative 'locate_project'
+
+module ArchUnit
+  # Assembles the normalized dependency graph for a Ruby project.
+  module Extraction
+    GRAPH_CACHE_MUTEX = Mutex.new
+    GRAPH_INDEPENDENT_CHECK_OPTIONS = %i[allow_empty_tests logging clear_cache].freeze
+
+    module_function
+
+    def extract_graph(
+      locator = nil, exclude_patterns: nil, options: nil, working_directory: Dir.pwd
+    )
+      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:)
+
+      GRAPH_CACHE_MUTEX.synchronize do
+        graph_cache.delete(cache_key) if options.clear_cache?
+        graph_cache[cache_key] ||= extract_graph_uncached(root, patterns)
+      end
+    end
+
+    def clear_graph_cache
+      GRAPH_CACHE_MUTEX.synchronize { graph_cache.clear }
+      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)
+
+      Common::Extraction::Graph.new(merge_parallel_edges(edges))
+    end
+    private_class_method :extract_graph_uncached
+
+    def graph_cache_key(project_root, exclude_patterns:, options:)
+      [
+        project_root.to_s.tr('\\', '/').freeze,
+        exclude_patterns.sort.freeze,
+        graph_analysis_toggles(options)
+      ].freeze
+    end
+    private_class_method :graph_cache_key
+
+    def graph_analysis_toggles(options)
+      options.class.members.filter_map do |member|
+        next if GRAPH_INDEPENDENT_CHECK_OPTIONS.include?(member)
+
+        [member, options.public_send(member)].freeze
+      end.freeze
+    end
+    private_class_method :graph_analysis_toggles
+
+    def graph_cache
+      @graph_cache ||= {}
+    end
+    private_class_method :graph_cache
+
+    def self_edges(source_files)
+      source_files.map do |source|
+        Common::Extraction::Edge.new(source: source, target: source, external: false)
+      end
+    end
+    private_class_method :self_edges
+
+    def merge_parallel_edges(edges)
+      edges.group_by { |edge| [edge.source, edge.target] }.values.map do |parallel_edges|
+        first = parallel_edges.first
+        Common::Extraction::Edge.new(
+          source: first.source,
+          target: first.target,
+          external: first.external,
+          import_kinds: parallel_edges.flat_map(&:import_kinds)
+        )
+      end
+    end
+    private_class_method :merge_parallel_edges
+  end
+end

data/lib/archunit/extraction/extract_imports.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'prism'
+require_relative '../error/technical_error'
+require_relative '../error/user_error'
+require_relative 'resolve_import'
+require_relative 'resolved_import'
+
+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
+    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?
+
+      visitor = ImportVisitor.new
+      visitor.visit(parse_result.value)
+      reject_ignored_imports(visitor.imports, parse_result.comments)
+    end
+    private_class_method :parsed_imports
+
+    def reject_ignored_imports(imports, comments)
+      directives = ignore_directives(comments)
+      imports.reject do |module_name, _import_kind, start_line, end_line|
+        directives.any? do |line, trailing, modules|
+          directive_applies?(line, trailing, start_line, end_line) &&
+            (modules.empty? || modules.any? { |name| ignored_module?(module_name, name) })
+        end
+      end
+    end
+    private_class_method :reject_ignored_imports
+
+    def ignore_directives(comments)
+      comments.filter_map do |comment|
+        match = IGNORE_DIRECTIVE.match(comment.location.slice)
+        next unless match
+
+        [comment.location.start_line, comment.trailing?, directive_modules(match[:modules])]
+      end
+    end
+    private_class_method :ignore_directives
+
+    def directive_applies?(line, trailing, start_line, end_line)
+      return line.between?(start_line, end_line) if trailing
+
+      start_line == line + 1
+    end
+    private_class_method :directive_applies?
+
+    def directive_modules(value)
+      return [] if value.nil?
+
+      value.split(/[\s,]+/).reject(&:empty?)
+    end
+    private_class_method :directive_modules
+
+    def ignored_module?(module_name, scoped_name)
+      module_name == scoped_name || module_name.start_with?("#{scoped_name}/")
+    end
+    private_class_method :ignored_module?
+
+    def resolved_import(located_import, source_path, root)
+      module_name, import_kind, line_number, = 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
+    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/locate_project.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative '../error/technical_error'
+require_relative '../error/user_error'
+
+module ArchUnit
+  # Ruby-specific project discovery and source extraction.
+  module Extraction
+    module_function
+
+    def locate_project(locator = nil, working_directory: Dir.pwd)
+      working_root = existing_directory(working_directory, :working_directory)
+      root = project_root(locator, working_root)
+      normalize_path(root.realpath)
+    rescue UserError, TechnicalError
+      raise
+    rescue SystemCallError => e
+      raise TechnicalError, "could not locate project: #{e.message}"
+    end
+
+    def project_root(locator, working_root)
+      return detected_project_root(working_root) || working_root if locator.nil?
+
+      explicit_project_root(locator, working_root)
+    end
+    private_class_method :project_root
+
+    def explicit_project_root(locator, working_root)
+      path = pathname(locator, :locator)
+      path = working_root.join(path) unless path.absolute?
+
+      return path.realpath if path.directory?
+      return path.dirname.realpath if path.file? && project_marker_file?(path)
+
+      raise UserError, 'project locator must be a directory, Gemfile, or .gemspec file'
+    end
+    private_class_method :explicit_project_root
+
+    def detected_project_root(working_root)
+      working_root.ascend.find { |directory| project_marker?(directory) }
+    end
+    private_class_method :detected_project_root
+
+    def project_marker?(directory)
+      directory.join('Gemfile').file? || directory.children.any? do |entry|
+        entry.file? && entry.extname == '.gemspec'
+      end
+    end
+    private_class_method :project_marker?
+
+    def project_marker_file?(path)
+      path.basename.to_s == 'Gemfile' || path.extname == '.gemspec'
+    end
+    private_class_method :project_marker_file?
+
+    def existing_directory(value, attribute)
+      path = pathname(value, attribute).expand_path
+      raise UserError, "#{attribute} must be an existing directory" unless path.directory?
+
+      path.realpath
+    end
+    private_class_method :existing_directory
+
+    def pathname(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)
+    end
+    private_class_method :pathname
+
+    def normalize_path(path)
+      path.to_s.tr('\\', '/')
+    end
+    private_class_method :normalize_path
+  end
+end

data/lib/archunit/extraction/resolve_import.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative '../common/extraction/import_kind'
+
+module ArchUnit
+  # Resolves Ruby dependency names using Ruby's own feature resolver.
+  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)
+      resolved = if import_kind == Common::Extraction::ImportKind::LOAD
+                   resolve_load(module_name, roots, import_kind)
+                 else
+                   resolve_feature(module_name, roots, import_kind)
+                 end
+
+      resolved&.tr('\\', '/')&.freeze
+    end
+
+    def import_search_roots(source_file, project_root, import_kind)
+      if import_kind == Common::Extraction::ImportKind::REQUIRE_RELATIVE
+        [File.dirname(File.expand_path(source_file))]
+      else
+        root = File.expand_path(project_root)
+        [File.join(root, 'lib'), root]
+      end
+    end
+    private_class_method :import_search_roots
+
+    def resolve_feature(module_name, roots, import_kind)
+      feature_candidates(module_name, roots).each do |candidate|
+        resolution = $LOAD_PATH.resolve_feature_path(candidate)
+        return resolution.last if resolution
+      end
+
+      return if import_kind == Common::Extraction::ImportKind::REQUIRE_RELATIVE
+
+      $LOAD_PATH.resolve_feature_path(module_name)&.last
+    end
+    private_class_method :resolve_feature
+
+    def resolve_load(module_name, roots, import_kind)
+      load_candidates(module_name, roots).find { |candidate| File.file?(candidate) } ||
+        resolve_load_from_global_path(module_name, import_kind)
+    end
+    private_class_method :resolve_load
+
+    def resolve_load_from_global_path(module_name, import_kind)
+      return if import_kind == Common::Extraction::ImportKind::REQUIRE_RELATIVE
+      return if Pathname.new(module_name).absolute?
+
+      $LOAD_PATH.lazy
+                .map { |directory| File.expand_path(module_name, directory) }
+                .find { |candidate| File.file?(candidate) }
+    end
+    private_class_method :resolve_load_from_global_path
+
+    def feature_candidates(module_name, roots)
+      path = Pathname.new(module_name)
+      return [path.expand_path.to_s] if path.absolute?
+
+      roots.map { |root| File.expand_path(module_name, root) }.uniq
+    end
+    private_class_method :feature_candidates
+
+    def load_candidates(module_name, roots)
+      path = Pathname.new(module_name)
+      return [path.expand_path.to_s] if path.absolute?
+
+      roots.map { |root| File.expand_path(module_name, root) }.uniq
+    end
+    private_class_method :load_candidates
+  end
+end

data/lib/archunit/extraction/resolved_import.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative '../common/extraction/import_kind'
+
+module ArchUnit
+  module Extraction
+    ResolvedImport = Data.define(:module_name, :import_kind, :line_number, :resolved_path) do
+      def initialize(module_name:, import_kind:, line_number:, resolved_path: nil)
+        validate_module_name(module_name)
+        validate_import_kind(import_kind)
+        validate_line_number(line_number)
+        validate_resolved_path(resolved_path)
+
+        module_name = module_name.dup.freeze
+        resolved_path = resolved_path&.tr('\\', '/')&.freeze
+        super
+      end
+
+      private
+
+      def validate_module_name(value)
+        return if value.is_a?(String) && !value.empty?
+
+        raise ArgumentError, 'module_name must be a non-empty String'
+      end
+
+      def validate_import_kind(value)
+        return if Common::Extraction::ImportKind.valid?(value)
+
+        raise ArgumentError, "unknown import kind: #{value.inspect}"
+      end
+
+      def validate_line_number(value)
+        return if value.is_a?(Integer) && value.positive?
+
+        raise ArgumentError, 'line_number must be a positive Integer'
+      end
+
+      def validate_resolved_path(value)
+        return if value.nil? || (value.is_a?(String) && !value.empty?)
+
+        raise ArgumentError, 'resolved_path must be nil or a non-empty String'
+      end
+    end
+  end
+end

data/lib/archunit/files/assertion/custom_file_condition.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative '../../common/assertion/violation'
+require_relative '../extraction/file_info'
+
+module ArchUnit
+  module Files
+    # Pure assertions over user-defined source-file predicates.
+    module Assertion
+      # Data describing a file that disagrees with a custom predicate.
+      class CustomFileViolation < Common::Assertion::Violation
+        attr_reader :file_info, :message, :is_negated
+
+        def initialize(file_info:, message:, is_negated: false)
+          @file_info = file_info_value(file_info)
+          @message = message_value(message)
+          @is_negated = boolean_value(is_negated)
+          super()
+        end
+
+        def negated?
+          is_negated
+        end
+
+        def ==(other)
+          other.is_a?(self.class) &&
+            file_info == other.file_info &&
+            message == other.message &&
+            is_negated == other.is_negated
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, file_info, message, is_negated].hash
+        end
+
+        private
+
+        def file_info_value(value)
+          return value if value.is_a?(Files::Extraction::FileInfo)
+
+          raise ArgumentError, 'file_info must be a FileInfo'
+        end
+
+        def message_value(value)
+          return value.dup.freeze if value.is_a?(String) && !value.strip.empty?
+
+          raise ArgumentError, 'message must be a non-empty String'
+        end
+
+        def boolean_value(value)
+          return value if [true, false].include?(value)
+
+          raise ArgumentError, 'is_negated must be true or false'
+        end
+      end
+
+      module_function
+
+      def gather_custom_file_violations(file_infos, condition, message, is_negated:)
+        validate_custom_arguments(file_infos, condition, message, is_negated)
+
+        file_infos.filter_map do |file_info|
+          result = condition.call(file_info)
+          unless [true, false].include?(result)
+            raise ArgumentError, 'condition must return true or false'
+          end
+          next unless is_negated ? result : !result
+
+          CustomFileViolation.new(file_info:, message:, is_negated:)
+        end
+      end
+
+      def validate_custom_arguments(file_infos, condition, message, is_negated)
+        unless file_infos.is_a?(Array) && file_infos.all?(Files::Extraction::FileInfo)
+          raise ArgumentError, 'file_infos must be an Array of FileInfo values'
+        end
+        raise ArgumentError, 'condition must be callable' unless condition.respond_to?(:call)
+        unless message.is_a?(String) && !message.strip.empty?
+          raise ArgumentError, 'message must be a non-empty String'
+        end
+        return if [true, false].include?(is_negated)
+
+        raise ArgumentError, 'is_negated must be true or false'
+      end
+      private_class_method :validate_custom_arguments
+    end
+  end
+end

data/lib/archunit/files/assertion/cycle_free.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative '../../common/assertion/violation'
+require_relative '../../common/projection/projected_edge'
+
+module ArchUnit
+  module Files
+    # Pure file-rule assertion functions and violation values.
+    module Assertion
+      # Data describing one closed circular dependency path.
+      class CycleViolation < Common::Assertion::Violation
+        attr_reader :cycle, :path
+
+        def initialize(cycle:)
+          @cycle = immutable_cycle(cycle)
+          @path = [cycle.first.source_label, *cycle.map(&:target_label)].freeze
+          super()
+        end
+
+        def ==(other)
+          other.is_a?(self.class) && cycle == other.cycle
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, cycle].hash
+        end
+
+        private
+
+        def immutable_cycle(values)
+          unless values.is_a?(Array) && !values.empty? && values.all?(Common::Projection::ProjectedEdge)
+            raise ArgumentError, 'cycle must be a non-empty Array of ProjectedEdge values'
+          end
+          unless closed_cycle?(values)
+            raise ArgumentError, 'cycle edges must form a contiguous closed path'
+          end
+
+          values.dup.freeze
+        end
+
+        def closed_cycle?(edges)
+          edges.each_cons(2).all? do |current, following|
+            current.target_label == following.source_label
+          end && edges.last.target_label == edges.first.source_label
+        end
+      end
+
+      module_function
+
+      def gather_cycle_violations(cycles)
+        raise ArgumentError, 'cycles must be an Array' unless cycles.is_a?(Array)
+
+        cycles.map { |cycle| CycleViolation.new(cycle:) }
+      end
+    end
+  end
+end