archunit 0.0.1 → 1.0.0

data/lib/archunit/common/extraction/dependency_evidence.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'import_kind'
+
+module ArchUnit
+  module Common
+    module Extraction
+      # Source-level support for a file dependency, without implying runtime execution.
+      DependencyEvidence = Data.define(
+        :source, :kind, :name, :line_number, :end_line, :target_line_number
+      ) do
+        # Keywords mirror this immutable source span.
+        def initialize( # rubocop:disable Metrics/ParameterLists
+          source:, kind:, name:, line_number:, end_line: line_number, target_line_number: nil
+        )
+          validate_identity(source, kind, name)
+          validate_lines(line_number, end_line, target_line_number)
+          source = source.tr('\\', '/').freeze
+          name = name.dup.freeze
+          super
+        end
+
+        private
+
+        def validate_identity(source, kind, name)
+          return if source.is_a?(String) && name.is_a?(String) && ImportKind.valid?(kind)
+
+          raise ArgumentError, 'evidence requires a source, name, and valid dependency kind'
+        end
+
+        def validate_lines(first, last, target)
+          valid = positive_line?(first) && positive_line?(last) && last >= first
+          return if valid && (target.nil? || positive_line?(target))
+
+          raise ArgumentError, 'evidence requires valid source line numbers'
+        end
+
+        def positive_line?(value)
+          value.is_a?(Integer) && value.positive?
+        end
+      end
+    end
+  end
+end

data/lib/archunit/common/extraction/edge.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
 require_relative 'import_kind'
+require_relative 'dependency_evidence'
 
 module ArchUnit
   module Common
     module Extraction
-      Edge = Data.define(:source, :target, :external, :import_kinds) do
-        def initialize(source:, target:, external:, import_kinds: [])
+      Edge = Data.define(:source, :target, :external, :import_kinds, :evidence) do
+        def initialize(source:, target:, external:, import_kinds: [], evidence: [])
           source = immutable_identifier(source, :source)
           target = immutable_identifier(target, :target)
           validate_external(external)
           import_kinds = immutable_import_kinds(import_kinds)
+          evidence = Array(evidence).uniq.freeze
+          unless evidence.all?(DependencyEvidence)
+            raise ArgumentError, 'evidence must contain DependencyEvidence values'
+          end
 
           super
         end

data/lib/archunit/common/extraction/import_kind.rb

@@ -9,8 +9,9 @@ module ArchUnit
         REQUIRE_RELATIVE = :require_relative
         AUTOLOAD = :autoload
         LOAD = :load
+        CONSTANT_REFERENCE = :constant_reference
 
-        ALL = [REQUIRE, REQUIRE_RELATIVE, AUTOLOAD, LOAD].freeze
+        ALL = [REQUIRE, REQUIRE_RELATIVE, AUTOLOAD, LOAD, CONSTANT_REFERENCE].freeze
 
         def self.valid?(value)
           ALL.include?(value)

data/lib/archunit/common/extraction/parse_diagnostic.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Common
+    module Extraction
+      # Immutable parser failure location; line and column are both one-based.
+      ParseDiagnostic = Data.define(:path, :line, :column, :message) do
+        def initialize(path:, line:, column:, message:)
+          unless [path, message].all? { |value| value.is_a?(String) && !value.empty? }
+            raise ArgumentError, 'parse diagnostic requires a non-empty path and message'
+          end
+          unless [line, column].all? { |value| value.is_a?(Integer) && value.positive? }
+            raise ArgumentError, 'parse diagnostic coordinates must be positive integers'
+          end
+
+          path = path.tr('\\', '/').freeze
+          message = message.dup.freeze
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -6,7 +6,12 @@ module ArchUnit
   module Common
     module FluentApi
       # Immutable options shared by every terminal rule check.
-      CheckOptions = Data.define(:allow_empty_tests, :logging, :clear_cache) do
+      CheckOptions = Data.define(
+        :allow_empty_tests, :logging, :clear_cache, :load_paths, :dependency_analysis
+      ) do
+        # Normalizes nil or an existing options value for terminal execution.
+        # @param value [CheckOptions, nil]
+        # @return [CheckOptions]
         def self.resolve(value)
           return new if value.nil?
           return value if value.is_a?(self)
@@ -14,21 +19,40 @@ module ArchUnit
           raise ArgumentError, 'options must be a CheckOptions value or nil'
         end
 
-        def initialize(allow_empty_tests: false, logging: nil, clear_cache: false)
+        # @param allow_empty_tests [Boolean] permit a selector that finds no subjects
+        # @param logging [LoggingOptions, nil] per-check logging configuration
+        # @param clear_cache [Boolean] rebuild the dependency graph for this check
+        # @param load_paths [Array<String, Pathname>] additional project-contained source roots
+        # @param dependency_analysis [Symbol] :imports or opt-in :imports_and_constants
+        def initialize(
+          allow_empty_tests: false, logging: nil, clear_cache: false, load_paths: [],
+          dependency_analysis: :imports
+        )
           validate_boolean(allow_empty_tests, :allow_empty_tests)
           validate_logging(logging)
           validate_boolean(clear_cache, :clear_cache)
+          load_paths = immutable_load_paths(load_paths)
+          unless %i[imports imports_and_constants].include?(dependency_analysis)
+            raise ArgumentError, 'dependency_analysis must be :imports or :imports_and_constants'
+          end
+
           super
         end
 
+        # @return [Boolean] whether an empty subject selection is allowed
         def allow_empty_tests?
           allow_empty_tests
         end
 
+        # @return [Boolean] whether this check rebuilds the cached graph
         def clear_cache?
           clear_cache
         end
 
+        def constant_references?
+          dependency_analysis == :imports_and_constants
+        end
+
         private
 
         def validate_boolean(value, attribute)
@@ -42,6 +66,23 @@ module ArchUnit
 
           raise ArgumentError, 'logging must be a LoggingOptions value or nil'
         end
+
+        def immutable_load_paths(value)
+          unless value.is_a?(Array)
+            raise ArgumentError, 'load_paths must be an Array of non-empty paths'
+          end
+
+          value.map { |path| immutable_load_path(path) }.uniq.freeze
+        end
+
+        def immutable_load_path(value)
+          value = value.to_path if value.respond_to?(:to_path)
+          unless value.is_a?(String) && !value.empty?
+            raise ArgumentError, 'load_paths must be an Array of non-empty paths'
+          end
+
+          value.tr('\\', '/').delete_suffix('/').freeze
+        end
       end
     end
   end

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

@@ -3,6 +3,7 @@
 require_relative '../assertion/violation'
 require_relative '../assertion/empty_test_violation'
 require_relative '../logging/check_logger'
+require_relative '../logging/inspection'
 require_relative 'check_options'
 
 module ArchUnit
@@ -10,6 +11,27 @@ module ArchUnit
     module FluentApi
       # The shared execution contract implemented by every terminal rule.
       module Checkable
+        # Optional normalized explanation, kept separate from violation values.
+        # @return [String, nil]
+        attr_reader :rationale
+
+        # Explains why this completed rule exists, without changing the original.
+        # Append this after all selectors and modifiers.
+        # @param reason [String] a non-blank human-readable explanation
+        # @return [Checkable] a distinct frozen rule of the same type
+        def because(reason)
+          unless reason.is_a?(String) && !reason.strip.empty?
+            raise ArgumentError, 'reason must be a non-empty String'
+          end
+
+          copy = dup
+          copy.instance_variable_set(:@rationale, reason.strip.freeze)
+          copy.freeze
+        end
+
+        # Executes the rule and returns every architecture disagreement as structured data.
+        # @param options [CheckOptions, nil]
+        # @return [Array<ArchUnit::Violation>]
         def check(options = nil)
           resolved_options = CheckOptions.resolve(options)
           logger = Logging::CheckLogger.new(resolved_options.logging)
@@ -28,7 +50,9 @@ module ArchUnit
 
         def execute_check(options, logger, check_name)
           logger.log_progress("executing #{check_name}")
-          violations = validate_violations(perform_check(options))
+          violations = Logging::Inspection.with(logger) do
+            validate_violations(perform_check(options))
+          end
           log_violations(logger, violations)
           logger.end_check(check_name, violation_count: violations.length)
           violations

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

@@ -53,6 +53,14 @@ module ArchUnit
           write(:debug, "log metric: #{metric}=#{value}#{context}")
         end
 
+        def debug?
+          !@options.nil? && enabled?(:debug)
+        end
+
+        def debug
+          write(:debug, "inspect: #{yield}") if debug?
+        end
+
         def close
           @mutex.synchronize do
             @file&.close

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Common
+    module Logging
+      # Internal inspection context, scoped to one check and isolated by Ruby fiber.
+      module Inspection
+        module_function
+
+        def with(logger)
+          previous = Thread.current[:archunit_inspection_logger]
+          Thread.current[:archunit_inspection_logger] = logger
+          yield
+        ensure
+          Thread.current[:archunit_inspection_logger] = previous
+        end
+
+        def logger
+          Thread.current[:archunit_inspection_logger]
+        end
+
+        def debug(&)
+          logger&.debug(&)
+        end
+
+        def graph(graph, root:)
+          debug do
+            logger.debug { "project root: #{root.to_s.inspect}" }
+            graph.each { |edge| logger.debug { describe_edge(edge) } }
+            "graph edges: #{graph.size}"
+          end
+          graph
+        end
+
+        def selection(label, items)
+          debug do
+            items.each { |item| logger.debug { "#{label}: #{yield(item).inspect}" } }
+            "#{label} count: #{items.length}"
+          end
+          items
+        end
+
+        def projection(edges)
+          selection('projected dependency', edges) do |edge|
+            "#{edge.source_label} -> #{edge.target_label} (#{edge.cumulated_edges.length} edges)"
+          end
+        end
+
+        def describe_edge(edge)
+          return "discovered file: #{edge.source.inspect}" if edge.source == edge.target
+
+          "dependency: #{edge.source.inspect} -> #{edge.target.inspect} " \
+            "(external=#{edge.external}, kinds=#{edge.import_kinds.inspect})"
+        end
+        private_class_method :describe_edge
+      end
+    end
+  end
+end

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

@@ -8,6 +8,10 @@ module ArchUnit
 
       # Immutable, per-check logging configuration. A nil CheckOptions#logging disables logging.
       LoggingOptions = Data.define(:level, :io, :output_directory, :append) do
+        # @param level [Symbol, String] one of debug, info, warn, or error
+        # @param io [#write, nil] stream sink, or nil to disable stream output
+        # @param output_directory [String, Pathname, nil] optional directory for timestamped logs
+        # @param append [Boolean] append to an existing selected log file when possible
         def initialize(level: :info, io: $stderr, output_directory: nil, append: false)
           level = normalize_level(level)
           validate_io(io)
@@ -16,6 +20,7 @@ module ArchUnit
           super
         end
 
+        # @return [Boolean] whether file logging is configured
         def file_output?
           !output_directory.nil?
         end

data/lib/archunit/common/pattern.rb

@@ -37,18 +37,28 @@ module ArchUnit
 
       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]
+        when '*' then compile_star(characters, index)
+        when '/' then compile_slash(characters, index)
+        when '?' then ['[^/]', index + 1]
+        when '[' then compile_character_class(characters, index)
+        else [Regexp.escape(characters[index]), index + 1]
         end
       end
       private_class_method :compile_fragment
 
+      def compile_slash(characters, index)
+        globstar_index = index + 1
+        globstar = characters[globstar_index] == '*' && characters[globstar_index + 1] == '*'
+        return ['/', globstar_index] unless globstar
+
+        tail_index = globstar_index + 2
+        tail_index += 1 while characters[tail_index] == '*'
+        return ['/', globstar_index] unless tail_index == characters.length
+
+        ['(?:/.*)?', tail_index]
+      end
+      private_class_method :compile_slash
+
       def compile_star(characters, index)
         return ['[^/]*', index + 1] unless characters[index + 1] == '*'
 

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

@@ -8,6 +8,9 @@ module ArchUnit
       module Cycles
         # Enumerates every elementary directed cycle once using Johnson's algorithm.
         class JohnsonCycles
+          Frame = Struct.new(:vertex, :neighbours, :index, :found_cycle)
+          private_constant :Frame
+
           def self.call(adjacency)
             new(adjacency).call
           end
@@ -55,36 +58,49 @@ module ArchUnit
           end
 
           def circuit(vertex)
+            frames = [enter_vertex(vertex)]
+            until frames.empty?
+              frame = frames.last
+              if frame.index < frame.neighbours.length
+                explore_neighbour(frame, frames)
+              else
+                finish_vertex(frames)
+              end
+            end
+          end
+
+          def enter_vertex(vertex)
             @stack << vertex
             @blocked.add(vertex)
-            found_cycle = explore_neighbours(vertex)
-            found_cycle ? unblock(vertex) : record_blockers(vertex)
-            @stack.pop
-            found_cycle
+            Frame.new(vertex, component_neighbours(vertex), 0, false)
           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
+          def explore_neighbour(frame, frames)
+            neighbour = frame.neighbours.fetch(frame.index)
+            frame.index += 1
+            if neighbour == @start
+              @cycles << @stack.dup
+              frame.found_cycle = true
+            elsif !@blocked.include?(neighbour)
+              frames << enter_vertex(neighbour)
             end
-            found_cycle
           end
 
-          def record_cycle?(neighbour)
-            return false unless neighbour == @start
-
-            @cycles << @stack.dup
-            true
+          def finish_vertex(frames)
+            frame = frames.pop
+            frame.found_cycle ? unblock(frame.vertex) : record_blockers(frame.vertex)
+            @stack.pop
+            frames.last.found_cycle ||= frame.found_cycle unless frames.empty?
           end
 
           def unblock(vertex)
-            return unless @blocked.delete?(vertex)
+            pending = [vertex]
+            until pending.empty?
+              candidate = pending.pop
+              next unless @blocked.delete?(candidate)
 
-            dependants = @blocked_by.delete(vertex) || []
-            dependants.each { |dependant| unblock(dependant) }
+              pending.concat((@blocked_by.delete(candidate) || []).to_a)
+            end
           end
 
           def record_blockers(vertex)

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

@@ -6,6 +6,9 @@ module ArchUnit
       module Cycles
         # Finds strongly connected components in a directed adjacency map.
         class TarjanScc
+          Frame = Struct.new(:vertex, :neighbours, :index)
+          private_constant :Frame
+
           def self.call(adjacency, vertices: adjacency.keys)
             new(adjacency, vertices).call
           end
@@ -30,13 +33,20 @@ module ArchUnit
           private
 
           def visit(vertex)
-            index_vertex(vertex)
-
-            neighbours(vertex).each do |neighbour|
-              inspect_neighbour(vertex, neighbour)
+            frames = [enter_vertex(vertex)]
+            until frames.empty?
+              frame = frames.last
+              if frame.index < frame.neighbours.length
+                inspect_neighbour(frame, frames)
+              else
+                finish_vertex(frames)
+              end
             end
+          end
 
-            extract_component(vertex) if @lowlinks.fetch(vertex) == @indices.fetch(vertex)
+          def enter_vertex(vertex)
+            index_vertex(vertex)
+            Frame.new(vertex, neighbours(vertex), 0)
           end
 
           def index_vertex(vertex)
@@ -47,16 +57,26 @@ module ArchUnit
             @on_stack.add(vertex)
           end
 
-          def inspect_neighbour(vertex, neighbour)
+          def inspect_neighbour(frame, frames)
+            neighbour = frame.neighbours.fetch(frame.index)
+            frame.index += 1
             unless @indices.key?(neighbour)
-              visit(neighbour)
-              @lowlinks[vertex] = [@lowlinks.fetch(vertex), @lowlinks.fetch(neighbour)].min
+              frames << enter_vertex(neighbour)
               return
             end
-
             return unless @on_stack.include?(neighbour)
 
-            @lowlinks[vertex] = [@lowlinks.fetch(vertex), @indices.fetch(neighbour)].min
+            update_lowlink(frame.vertex, @indices.fetch(neighbour))
+          end
+
+          def finish_vertex(frames)
+            vertex = frames.pop.vertex
+            extract_component(vertex) if @lowlinks.fetch(vertex) == @indices.fetch(vertex)
+            update_lowlink(frames.last.vertex, @lowlinks.fetch(vertex)) unless frames.empty?
+          end
+
+          def update_lowlink(vertex, index)
+            @lowlinks[vertex] = [@lowlinks.fetch(vertex), index].min
           end
 
           def extract_component(root)

data/lib/archunit/error/source_parse_error.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'technical_error'
+require_relative '../common/extraction/parse_diagnostic'
+
+module ArchUnit
+  # An included source could not be analyzed; never an ordinary architecture violation.
+  class SourceParseError < TechnicalError
+    # @return [Array<Common::Extraction::ParseDiagnostic>] immutable source diagnostics
+    attr_reader :diagnostics
+
+    # @return [Prism::ParseResult] the complete result, or a technical failure
+    def self.validate!(result, path:)
+      return result if result.success?
+
+      diagnostics = result.errors.map do |error|
+        Common::Extraction::ParseDiagnostic.new(
+          path: path.to_s, line: error.location.start_line,
+          column: error.location.start_column + 1, message: error.message
+        )
+      end
+      raise SourceParseError, diagnostics
+    end
+
+    def initialize(diagnostics)
+      unless diagnostics.is_a?(Array) && !diagnostics.empty? &&
+             diagnostics.all?(Common::Extraction::ParseDiagnostic)
+        raise ArgumentError, 'source parse error requires non-empty parse diagnostics'
+      end
+
+      @diagnostics = diagnostics.dup.freeze
+      details = @diagnostics.map do |item|
+        "#{item.path}:#{item.line}:#{item.column}: #{item.message}"
+      end
+      super("Cannot analyze malformed Ruby source:\n#{details.join("\n")}")
+    end
+  end
+end

data/lib/archunit/extraction/arch_ignore.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative '../error/user_error'
+require_relative '../error/technical_error'
+
+module ArchUnit
+  module Extraction
+    # Reads bounded, repository-owned exclusions without evaluating project code.
+    # Only the project-root .archignore is read. Symlinks and negation are rejected.
+    module ArchIgnore
+      MAX_BYTES = 1024 * 1024
+
+      module_function
+
+      # @param root [Pathname] canonical project root
+      # @return [Array<String>] exclusion patterns using the source enumerator's glob syntax
+      def patterns(root)
+        path = root.join('.archignore')
+        stat = configuration_stat(path)
+        return [] unless stat
+
+        validate_configuration(stat)
+        parse(read_configuration(path))
+      rescue Errno::ELOOP
+        raise UserError, '.archignore must not be a symlink'
+      rescue SystemCallError, IOError => e
+        raise TechnicalError, "could not read .archignore: #{e.message}"
+      end
+
+      def configuration_stat(path)
+        path.lstat
+      rescue Errno::ENOENT
+        nil
+      end
+      private_class_method :configuration_stat
+
+      def validate_configuration(stat)
+        return if stat.file? && !stat.symlink?
+
+        raise UserError, '.archignore must be a regular file, not a symlink or directory'
+      end
+      private_class_method :validate_configuration
+
+      def read_configuration(path)
+        flags = File::RDONLY
+        # Windows defines NONBLOCK as 1, which is also WRONLY: do not use it there.
+        flags |= File::NOFOLLOW | File::NONBLOCK if File.const_defined?(:NOFOLLOW)
+        File.open(path, flags) do |file|
+          raise UserError, '.archignore must be a regular file' unless file.stat.file?
+
+          bounded_contents(file)
+        end
+      end
+      private_class_method :read_configuration
+
+      def bounded_contents(file)
+        contents = file.binmode.read(MAX_BYTES + 1) || String.new
+        raise UserError, '.archignore exceeds the 1 MiB size limit' if contents.bytesize > MAX_BYTES
+
+        contents
+      end
+      private_class_method :bounded_contents
+
+      def parse(contents)
+        contents.force_encoding(Encoding::UTF_8).scrub.delete_prefix("\uFEFF")
+                .each_line.filter_map do |line|
+          pattern = line.strip.tr('\\', '/')
+          next if pattern.empty? || pattern.start_with?('#')
+
+          if pattern.start_with?('!') || pattern.include?("\0")
+            raise UserError, '.archignore does not support negation (!) or NUL characters'
+          end
+
+          directory_pattern(pattern)
+        end
+      end
+      private_class_method :parse
+
+      def directory_pattern(pattern)
+        return pattern unless pattern.end_with?('/')
+
+        pattern = pattern.delete_suffix('/')
+        raise UserError, '.archignore cannot exclude the project root with /' if pattern.empty?
+
+        prefix = pattern.include?('/') ? '' : '**/'
+        "#{prefix}#{pattern}/**"
+      end
+      private_class_method :directory_pattern
+    end
+  end
+end