archunit 0.0.1

data/lib/archunit/common/fluentapi/check_options.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative '../logging/logging_options'
+
+module ArchUnit
+  module Common
+    module FluentApi
+      # Immutable options shared by every terminal rule check.
+      CheckOptions = Data.define(:allow_empty_tests, :logging, :clear_cache) do
+        def self.resolve(value)
+          return new if value.nil?
+          return value if value.is_a?(self)
+
+          raise ArgumentError, 'options must be a CheckOptions value or nil'
+        end
+
+        def initialize(allow_empty_tests: false, logging: nil, clear_cache: false)
+          validate_boolean(allow_empty_tests, :allow_empty_tests)
+          validate_logging(logging)
+          validate_boolean(clear_cache, :clear_cache)
+          super
+        end
+
+        def allow_empty_tests?
+          allow_empty_tests
+        end
+
+        def clear_cache?
+          clear_cache
+        end
+
+        private
+
+        def validate_boolean(value, attribute)
+          return if [true, false].include?(value)
+
+          raise ArgumentError, "#{attribute} must be true or false"
+        end
+
+        def validate_logging(value)
+          return if value.nil? || value.is_a?(Logging::LoggingOptions)
+
+          raise ArgumentError, 'logging must be a LoggingOptions value or nil'
+        end
+      end
+    end
+  end
+end

data/lib/archunit/common/fluentapi/checkable.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../assertion/violation'
+require_relative '../assertion/empty_test_violation'
+require_relative '../logging/check_logger'
+require_relative 'check_options'
+
+module ArchUnit
+  module Common
+    module FluentApi
+      # The shared execution contract implemented by every terminal rule.
+      module Checkable
+        def check(options = nil)
+          resolved_options = CheckOptions.resolve(options)
+          logger = Logging::CheckLogger.new(resolved_options.logging)
+          check_name = self.class.name || self.class.to_s
+          logger.start_check(check_name)
+          execute_check(resolved_options, logger, check_name)
+        ensure
+          logger&.close
+        end
+
+        private
+
+        def perform_check(_options)
+          raise NotImplementedError, "#{self.class} must implement #perform_check"
+        end
+
+        def execute_check(options, logger, check_name)
+          logger.log_progress("executing #{check_name}")
+          violations = validate_violations(perform_check(options))
+          log_violations(logger, violations)
+          logger.end_check(check_name, violation_count: violations.length)
+          violations
+        rescue StandardError, NotImplementedError => e
+          logger.end_check(check_name, error: e)
+          raise
+        end
+
+        def log_violations(logger, violations)
+          violations.each do |violation|
+            logger.log_violation(violation)
+            next unless violation.respond_to?(:metric_name) && violation.respond_to?(:value)
+
+            subject = violation.identifier if violation.respond_to?(:identifier)
+            logger.log_metric(name: violation.metric_name, value: violation.value, subject:)
+          end
+        end
+
+        def empty_test_violation(selected_items, filters:, negated:, options:)
+          unless selected_items.respond_to?(:empty?)
+            raise ArgumentError, 'selected_items must respond to empty?'
+          end
+          unless options.is_a?(CheckOptions)
+            raise ArgumentError, 'options must be a CheckOptions value'
+          end
+          return if !selected_items.empty? || options.allow_empty_tests?
+
+          [Assertion::EmptyTestViolation.new(filters:, is_negated: negated)]
+        end
+
+        def validate_violations(violations)
+          return violations if violations.is_a?(Array) && violations.all?(Assertion::Violation)
+
+          raise TypeError, 'check must return an Array of Violation values'
+        end
+      end
+    end
+  end
+end

data/lib/archunit/common/logging/check_logger.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'time'
+require_relative 'logging_options'
+
+module ArchUnit
+  module Common
+    module Logging
+      # A logger owned by one check invocation; no configuration or output state is global.
+      class CheckLogger
+        LEVEL_PRIORITIES = { debug: 0, info: 1, warn: 2, error: 3 }.freeze
+
+        attr_reader :log_path
+
+        def initialize(options = nil, clock: -> { Time.now.utc })
+          validate_options(options)
+          raise ArgumentError, 'clock must respond to call' unless clock.respond_to?(:call)
+
+          @options = options
+          @clock = clock
+          @file = nil
+          @log_path = nil
+          @mutex = Mutex.new
+        end
+
+        def start_check(check_name)
+          write(:info, "start check: #{label(check_name, 'check_name')}")
+        end
+
+        def end_check(check_name, violation_count: nil, error: nil)
+          name = label(check_name, 'check_name')
+          if error
+            write(:error, "end check: #{name} failed with #{error.class}: #{error.message}")
+          else
+            write(:info, "end check: #{name} (#{Integer(violation_count)} violations)")
+          end
+        end
+
+        def log_progress(message)
+          write(:info, "log progress: #{label(message, 'message')}")
+        end
+
+        def log_violation(violation)
+          raise ArgumentError, 'violation is required' if violation.nil?
+
+          write(:warn, "log violation: #{violation_description(violation)}")
+        end
+
+        def log_metric(name:, value:, subject: nil)
+          metric = label(name, 'name')
+          context = subject.nil? ? '' : " [#{subject}]"
+          write(:debug, "log metric: #{metric}=#{value}#{context}")
+        end
+
+        def close
+          @mutex.synchronize do
+            @file&.close
+            @file = nil
+          end
+          nil
+        end
+
+        private
+
+        def validate_options(value)
+          return if value.nil? || value.is_a?(LoggingOptions)
+
+          raise ArgumentError, 'options must be a LoggingOptions value or nil'
+        end
+
+        def write(level, message)
+          return if @options.nil? || !enabled?(level)
+
+          timestamp = current_time
+          line = "[#{timestamp.iso8601(6)}] [#{level.to_s.upcase}] #{message}\n"
+          @mutex.synchronize do
+            @options.io&.write(line)
+            output_file(timestamp)&.write(line)
+          end
+          nil
+        end
+
+        def enabled?(level)
+          LEVEL_PRIORITIES.fetch(level) >= LEVEL_PRIORITIES.fetch(@options.level)
+        end
+
+        def current_time
+          value = @clock.call
+          raise ArgumentError, 'clock must return a Time' unless value.is_a?(Time)
+
+          value.utc
+        end
+
+        def output_file(timestamp)
+          return unless @options.file_output?
+          return @file if @file
+
+          FileUtils.mkdir_p(@options.output_directory)
+          @log_path = File.join(
+            @options.output_directory,
+            "archunit-#{timestamp.strftime('%Y-%m-%d_%H-%M-%S-%6N')}.log"
+          ).freeze
+          @file = File.open(@log_path, @options.append ? 'ab' : 'wb')
+        end
+
+        def label(value, attribute)
+          text = value.to_s
+          return text unless text.empty?
+
+          raise ArgumentError, "#{attribute} must not be empty"
+        end
+
+        def violation_description(violation)
+          description = violation.class.name.to_s
+          description = violation.class.to_s if description.empty?
+          return description unless violation.respond_to?(:identifier)
+
+          "#{description} [#{violation.identifier}]"
+        end
+      end
+    end
+  end
+end

data/lib/archunit/common/logging/logging_options.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Common
+    module Logging
+      LOG_LEVELS = %i[debug info warn error].freeze
+      private_constant :LOG_LEVELS
+
+      # Immutable, per-check logging configuration. A nil CheckOptions#logging disables logging.
+      LoggingOptions = Data.define(:level, :io, :output_directory, :append) do
+        def initialize(level: :info, io: $stderr, output_directory: nil, append: false)
+          level = normalize_level(level)
+          validate_io(io)
+          output_directory = normalize_output_directory(output_directory)
+          validate_append(append)
+          super
+        end
+
+        def file_output?
+          !output_directory.nil?
+        end
+
+        private
+
+        def normalize_level(value)
+          normalized = value.respond_to?(:to_sym) ? value.to_sym : value
+          return normalized if LOG_LEVELS.include?(normalized)
+
+          raise ArgumentError, "level must be one of: #{LOG_LEVELS.join(', ')}"
+        end
+
+        def validate_io(value)
+          return if value.nil? || value.respond_to?(:write)
+
+          raise ArgumentError, 'io must respond to write or be nil'
+        end
+
+        def normalize_output_directory(value)
+          return if value.nil?
+
+          path = value.respond_to?(:to_path) ? value.to_path : value
+          unless path.is_a?(String) && !path.empty?
+            raise ArgumentError, 'output_directory must be a non-empty path or nil'
+          end
+
+          File.expand_path(path).freeze
+        end
+
+        def validate_append(value)
+          return if [true, false].include?(value)
+
+          raise ArgumentError, 'append must be true or false'
+        end
+      end
+    end
+  end
+end

data/lib/archunit/common/pattern.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Common
+    # Compiles user-facing glob strings into the regular expressions used by the kernel.
+    module Pattern
+      module_function
+
+      def compile(pattern)
+        case pattern
+        when String
+          compile_glob(pattern.tr('\\', '/'))
+        when Regexp
+          pattern.dup.freeze
+        else
+          raise ArgumentError, 'pattern must be a String glob or Regexp'
+        end
+      end
+
+      def valid?(pattern)
+        pattern.is_a?(String) || pattern.is_a?(Regexp)
+      end
+
+      def compile_glob(glob)
+        characters = glob.chars
+        source = +'\\A'
+        index = 0
+
+        while index < characters.length
+          fragment, index = compile_fragment(characters, index)
+          source << fragment
+        end
+
+        Regexp.new("#{source}\\z").freeze
+      end
+      private_class_method :compile_glob
+
+      def compile_fragment(characters, index)
+        case characters[index]
+        when '*'
+          compile_star(characters, index)
+        when '?'
+          ['[^/]', index + 1]
+        when '['
+          compile_character_class(characters, index)
+        else
+          [Regexp.escape(characters[index]), index + 1]
+        end
+      end
+      private_class_method :compile_fragment
+
+      def compile_star(characters, index)
+        return ['[^/]*', index + 1] unless characters[index + 1] == '*'
+
+        index += 2
+        index += 1 while characters[index] == '*'
+        return ['.*', index] unless characters[index] == '/'
+
+        ['(?:.*/)?', index + 1]
+      end
+      private_class_method :compile_star
+
+      def compile_character_class(characters, index)
+        closing_index = character_class_closing_index(characters, index)
+        return ['\\[', index + 1] if closing_index.nil? || closing_index == index + 1
+
+        content = characters[(index + 1)...closing_index]
+        return ['\\[', index + 1] if content == ['!']
+
+        [character_class_fragment(content), closing_index + 1]
+      end
+      private_class_method :compile_character_class
+
+      def character_class_closing_index(characters, index)
+        closing_offset = characters[(index + 1)..].index(']')
+        closing_offset && (index + closing_offset + 1)
+      end
+      private_class_method :character_class_closing_index
+
+      def character_class_fragment(content)
+        content = content.dup
+        negated = content.first == '!'
+        content.shift if negated
+
+        escaped_content = content.map { |character| escape_class_character(character) }.join
+        prefix = negated ? '^' : ''
+        "(?=[^/])[#{prefix}#{escaped_content}]"
+      end
+      private_class_method :character_class_fragment
+
+      def escape_class_character(character)
+        return "\\#{character}" if ['\\', '[', ']', '&', '^'].include?(character)
+
+        character
+      end
+      private_class_method :escape_class_character
+    end
+  end
+end

data/lib/archunit/common/pattern_matching.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative 'filter'
+
+module ArchUnit
+  module Common
+    # Generic matching operations. The Filter selects which part of a candidate is tested.
+    module PatternMatching
+      module_function
+
+      def matches_pattern?(file_path, filter, class_name: nil)
+        validate_arguments(file_path, filter, class_name)
+        target = target_string(file_path, filter.target, class_name)
+        matches = regexp_matches?(filter, target)
+
+        matches && filter.exclusions.none? do |exclusion|
+          matches_pattern?(file_path, exclusion, class_name:)
+        end
+      end
+
+      def matches_all_patterns?(file_path, filters, class_name: nil)
+        filters.all? { |filter| matches_pattern?(file_path, filter, class_name:) }
+      end
+
+      def matches_any_pattern?(file_path, filters, class_name: nil)
+        filters.any? { |filter| matches_pattern?(file_path, filter, class_name:) }
+      end
+
+      def normalize_path(path)
+        path.tr('\\', '/')
+      end
+
+      def extract_filename(path)
+        normalize_path(path).split('/').last.to_s
+      end
+
+      def path_without_filename(path)
+        parts = normalize_path(path).split('/')
+        parts.pop
+        parts.join('/')
+      end
+
+      def validate_arguments(file_path, filter, class_name)
+        raise ArgumentError, 'file_path must be a String' unless file_path.is_a?(String)
+        raise ArgumentError, 'filter must be a Filter' unless filter.is_a?(Filter)
+        return if class_name.nil? || class_name.is_a?(String)
+
+        raise ArgumentError, 'class_name must be a String'
+      end
+      private_class_method :validate_arguments
+
+      def target_string(file_path, target, class_name)
+        case target
+        when :filename
+          extract_filename(file_path)
+        when :path
+          normalize_path(file_path)
+        when :path_without_filename
+          path_without_filename(file_path)
+        when :classname
+          class_name || raise(ArgumentError, 'class_name is required for a classname filter')
+        end
+      end
+      private_class_method :target_string
+
+      def regexp_matches?(filter, target)
+        match = filter.regexp.match(target)
+        return false unless match
+        return true if filter.matching == :partial
+
+        match.begin(0).zero? && match.end(0) == target.length
+      end
+      private_class_method :regexp_matches?
+    end
+  end
+end

data/lib/archunit/common/projection/cycles/johnson_cycles.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative 'tarjan_scc'
+
+module ArchUnit
+  module Common
+    module Projection
+      module Cycles
+        # Enumerates every elementary directed cycle once using Johnson's algorithm.
+        class JohnsonCycles
+          def self.call(adjacency)
+            new(adjacency).call
+          end
+
+          def initialize(adjacency)
+            @vertices = (adjacency.keys + adjacency.values.flatten).uniq.sort
+            @adjacency = @vertices.to_h do |vertex|
+              neighbours = adjacency.fetch(vertex, []).reject { |item| item == vertex }.uniq.sort
+              [vertex, neighbours]
+            end
+            @cycles = []
+          end
+
+          def call
+            lower_bound = @vertices.first
+
+            while lower_bound
+              component = next_component(lower_bound)
+              break unless component
+
+              start = component.min
+              prepare_search(component, start)
+              circuit(start)
+              lower_bound = @vertices.find { |vertex| vertex > start }
+            end
+
+            @cycles.map(&:freeze).freeze
+          end
+
+          private
+
+          def next_component(lower_bound)
+            remaining = @vertices.select { |vertex| vertex >= lower_bound }
+            TarjanScc.call(@adjacency, vertices: remaining)
+                     .select { |component| component.length > 1 }
+                     .min_by(&:min)
+          end
+
+          def prepare_search(component, start)
+            @component = component.to_set
+            @start = start
+            @stack = []
+            @blocked = Set.new
+            @blocked_by = Hash.new { |hash, vertex| hash[vertex] = Set.new }
+          end
+
+          def circuit(vertex)
+            @stack << vertex
+            @blocked.add(vertex)
+            found_cycle = explore_neighbours(vertex)
+            found_cycle ? unblock(vertex) : record_blockers(vertex)
+            @stack.pop
+            found_cycle
+          end
+
+          def explore_neighbours(vertex)
+            found_cycle = false
+            component_neighbours(vertex).each do |neighbour|
+              closes_cycle = record_cycle?(neighbour)
+              finds_cycle = !@blocked.include?(neighbour) && circuit(neighbour)
+              found_cycle = true if closes_cycle || finds_cycle
+            end
+            found_cycle
+          end
+
+          def record_cycle?(neighbour)
+            return false unless neighbour == @start
+
+            @cycles << @stack.dup
+            true
+          end
+
+          def unblock(vertex)
+            return unless @blocked.delete?(vertex)
+
+            dependants = @blocked_by.delete(vertex) || []
+            dependants.each { |dependant| unblock(dependant) }
+          end
+
+          def record_blockers(vertex)
+            component_neighbours(vertex).each do |neighbour|
+              @blocked_by[neighbour].add(vertex)
+            end
+          end
+
+          def component_neighbours(vertex)
+            @adjacency.fetch(vertex, []).select { |neighbour| @component.include?(neighbour) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/archunit/common/projection/cycles/tarjan_scc.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Common
+    module Projection
+      module Cycles
+        # Finds strongly connected components in a directed adjacency map.
+        class TarjanScc
+          def self.call(adjacency, vertices: adjacency.keys)
+            new(adjacency, vertices).call
+          end
+
+          def initialize(adjacency, vertices)
+            @adjacency = adjacency
+            @vertices = vertices.to_a
+            @allowed = @vertices.to_set
+            @next_index = 0
+            @indices = {}
+            @lowlinks = {}
+            @stack = []
+            @on_stack = Set.new
+            @components = []
+          end
+
+          def call
+            @vertices.each { |vertex| visit(vertex) unless @indices.key?(vertex) }
+            @components.map(&:freeze).freeze
+          end
+
+          private
+
+          def visit(vertex)
+            index_vertex(vertex)
+
+            neighbours(vertex).each do |neighbour|
+              inspect_neighbour(vertex, neighbour)
+            end
+
+            extract_component(vertex) if @lowlinks.fetch(vertex) == @indices.fetch(vertex)
+          end
+
+          def index_vertex(vertex)
+            @indices[vertex] = @next_index
+            @lowlinks[vertex] = @next_index
+            @next_index += 1
+            @stack << vertex
+            @on_stack.add(vertex)
+          end
+
+          def inspect_neighbour(vertex, neighbour)
+            unless @indices.key?(neighbour)
+              visit(neighbour)
+              @lowlinks[vertex] = [@lowlinks.fetch(vertex), @lowlinks.fetch(neighbour)].min
+              return
+            end
+
+            return unless @on_stack.include?(neighbour)
+
+            @lowlinks[vertex] = [@lowlinks.fetch(vertex), @indices.fetch(neighbour)].min
+          end
+
+          def extract_component(root)
+            component = []
+
+            loop do
+              vertex = @stack.pop
+              @on_stack.delete(vertex)
+              component << vertex
+              break if vertex == root
+            end
+
+            @components << component.sort
+          end
+
+          def neighbours(vertex)
+            @adjacency.fetch(vertex, []).select { |neighbour| @allowed.include?(neighbour) }
+          end
+        end
+      end
+    end
+  end
+end