archunit 0.0.1

data/lib/archunit/testing/result_factory.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative '../common/assertion/violation'
+require_relative 'color_utils'
+require_relative 'test_result'
+require_relative 'violation_factory'
+
+module ArchUnit
+  # Violation presentation and test-framework integration.
+  module Testing
+    # Shapes a violation collection into one framework-neutral test result.
+    class ResultFactory
+      class << self
+        def from_violations(violations, color: nil, expected_to_pass: true)
+          validate_violations(violations)
+          validate_expected_to_pass(expected_to_pass)
+          color = resolve_color(color)
+          return empty_result(color, expected_to_pass) if violations.empty?
+
+          failing_result(violations, color, expected_to_pass)
+        end
+
+        private
+
+        def passing_result(color)
+          message = ColorUtils.green('No architecture violations found.', enabled: color)
+          TestResult.new(passed: true, message:)
+        end
+
+        def empty_result(color, expected_to_pass)
+          return passing_result(color) if expected_to_pass
+
+          message = 'Expected architecture violations, but none were found.'
+          message = ColorUtils.bold(ColorUtils.red(message, enabled: color), enabled: color)
+          TestResult.new(passed: false, message:)
+        end
+
+        def failing_result(violations, color, expected_to_pass)
+          test_violations = violations.map do |violation|
+            ViolationFactory.from_violation(violation)
+          end
+          TestResult.new(
+            passed: !expected_to_pass,
+            message: failure_message(test_violations, color)
+          )
+        end
+
+        def failure_message(test_violations, color)
+          lines = [failure_title(test_violations.length, color), '']
+
+          test_violations.each_with_index do |violation, index|
+            append_violation(lines, violation, index, color)
+          end
+          lines.join("\n").rstrip
+        end
+
+        def failure_title(count, color)
+          noun = count == 1 ? 'violation' : 'violations'
+          title = "Found #{count} architecture #{noun}:"
+          ColorUtils.bold(ColorUtils.red(title, enabled: color), enabled: color)
+        end
+
+        def append_violation(lines, violation, index, color)
+          heading = "  #{index + 1}. #{violation.message}"
+          lines << ColorUtils.yellow(heading, enabled: color)
+          lines << "     #{violation.details}"
+          lines << ''
+        end
+
+        def validate_violations(values)
+          return if values.is_a?(Array) && values.all?(Common::Assertion::Violation)
+
+          raise ArgumentError, 'violations must be an Array of Violation values'
+        end
+
+        def validate_expected_to_pass(value)
+          return if [true, false].include?(value)
+
+          raise ArgumentError, 'expected_to_pass must be true or false'
+        end
+
+        def resolve_color(value)
+          return ColorUtils.supported? if value.nil?
+          return value if [true, false].include?(value)
+
+          raise ArgumentError, 'color must be true, false, or nil'
+        end
+      end
+
+      private_class_method :new
+    end
+  end
+end

data/lib/archunit/testing/rspec_adapter.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Testing
+    # RSpec's matcher protocol, delegating all evaluation and prose to shared testing code.
+    class RSpecPassMatcher
+      def initialize(options = nil)
+        @options = options
+      end
+
+      def matches?(rule)
+        matches_expectation?(rule, expected_to_pass: true)
+      end
+
+      # RSpec's matcher protocol fixes this method name.
+      # rubocop:disable Naming/PredicatePrefix
+      def does_not_match?(rule)
+        matches_expectation?(rule, expected_to_pass: false)
+      end
+      # rubocop:enable Naming/PredicatePrefix
+
+      def failure_message
+        result.message
+      end
+      alias failure_message_when_negated failure_message
+
+      private
+
+      attr_reader :options, :result
+
+      def matches_expectation?(rule, expected_to_pass:)
+        @result = ArchUnit::Testing.result_for(rule, options, expected_to_pass:)
+        result.passed?
+      end
+    end
+
+    # Methods mixed into RSpec's matcher namespace when the framework is present.
+    module RSpecMatchers
+      def pass(options = nil)
+        RSpecPassMatcher.new(options)
+      end
+    end
+
+    # Installs the native `expect(rule).to pass` matcher when RSpec is already loaded.
+    module RSpecAdapter
+      module_function
+
+      def install!
+        return unless rspec_available?
+        return if installed?
+
+        ::RSpec::Matchers.include(RSpecMatchers)
+        @installed = true
+        nil
+      end
+
+      def installed?
+        @installed == true
+      end
+
+      def rspec_available?
+        return false unless defined?(::RSpec)
+
+        require 'rspec/matchers' unless defined?(::RSpec::Matchers)
+        defined?(::RSpec::Matchers)
+      rescue LoadError
+        false
+      end
+      private_class_method :rspec_available?
+    end
+  end
+end
+
+ArchUnit::Testing::RSpecAdapter.install!

data/lib/archunit/testing/slice_violation_formatter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'test_violation'
+
+module ArchUnit
+  module Testing
+    # Human-readable presentation for slice architecture violations.
+    module SliceViolationFormatter
+      private
+
+      def slice_dependency(violation)
+        relationship = if violation.rule == :contain_dependency
+                         'depends on forbidden slice'
+                       else
+                         'has a dependency not allowed by the diagram on'
+                       end
+        TestViolation.new(
+          message: 'Slice dependency violation',
+          details: "Slice '#{violation.source_slice}' #{relationship} " \
+                   "'#{violation.target_slice}'."
+        )
+      end
+    end
+  end
+end

data/lib/archunit/testing/test_result.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  # Violation presentation and test-framework integration.
+  module Testing
+    # Immutable framework-neutral pass flag and formatted message.
+    TestResult = Data.define(:passed, :message) do
+      def initialize(passed:, message:)
+        raise ArgumentError, 'passed must be true or false' unless [true, false].include?(passed)
+        unless message.is_a?(String) && !message.empty?
+          raise ArgumentError, 'message must be a non-empty String'
+        end
+
+        super(passed:, message: message.dup.freeze)
+      end
+
+      def passed?
+        passed
+      end
+
+      def failed?
+        !passed
+      end
+    end
+  end
+end

data/lib/archunit/testing/test_violation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  # Violation presentation and test-framework integration.
+  module Testing
+    # Immutable human-readable representation of one structured violation.
+    TestViolation = Data.define(:message, :details) do
+      def initialize(message:, details:)
+        message = non_empty_string(message, :message)
+        details = non_empty_string(details, :details)
+        super
+      end
+
+      private
+
+      def non_empty_string(value, attribute)
+        return value.dup.freeze if value.is_a?(String) && !value.strip.empty?
+
+        raise ArgumentError, "#{attribute} must be a non-empty String"
+      end
+    end
+  end
+end

data/lib/archunit/testing/violation_factory.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative '../common/assertion/empty_test_violation'
+require_relative '../common/assertion/violation'
+require_relative '../files/assertion/custom_file_condition'
+require_relative '../files/assertion/cycle_free'
+require_relative '../files/assertion/depend_on_external_modules'
+require_relative '../files/assertion/depend_on_files'
+require_relative '../files/assertion/matching_files'
+require_relative '../layers/assertion/layer_dependency_violation'
+require_relative '../metrics/assertion/custom_metric'
+require_relative '../metrics/assertion/metric_predicate'
+require_relative '../metrics/assertion/metric_threshold'
+require_relative '../metrics/assertion/metric_zone'
+require_relative '../slices/assertion/slice_dependency_violation'
+require_relative 'layer_violation_formatter'
+require_relative 'metric_violation_formatter'
+require_relative 'slice_violation_formatter'
+require_relative 'test_violation'
+
+module ArchUnit
+  # Violation presentation and test-framework integration.
+  module Testing
+    # The sole mapping from structured violation data to human-readable prose.
+    class ViolationFactory
+      extend LayerViolationFormatter
+      extend MetricViolationFormatter
+      extend SliceViolationFormatter
+
+      FORMATTERS = {
+        Common::Assertion::EmptyTestViolation => :empty_test,
+        Files::Assertion::FilePatternViolation => :file_pattern,
+        Files::Assertion::FileDependencyViolation => :file_dependency,
+        Files::Assertion::ExternalModuleDependencyViolation => :external_module_dependency,
+        Files::Assertion::CycleViolation => :cycle,
+        Files::Assertion::CustomFileViolation => :custom_file,
+        Layers::Assertion::LayerDependencyViolation => :layer_dependency,
+        Slices::Assertion::SliceDependencyViolation => :slice_dependency
+      }.merge(MetricViolationFormatter::FORMATTERS).freeze
+
+      class << self
+        def from_violation(violation)
+          unless violation.is_a?(Common::Assertion::Violation)
+            raise ArgumentError, 'violation must be a Violation'
+          end
+
+          formatter = FORMATTERS.find { |type, _method| violation.is_a?(type) }&.last
+          formatter ? send(formatter, violation) : generic(violation)
+        end
+
+        private
+
+        def empty_test(violation)
+          selectors = violation.filters.map { |filter| describe_filter(filter) }
+          details = if selectors.empty?
+                      'The unfiltered rule scope contained no files.'
+                    else
+                      "No files matched: #{selectors.join(' AND ')}."
+                    end
+          TestViolation.new(message: 'No files matched the rule scope', details:)
+        end
+
+        def file_pattern(violation)
+          relationship = violation.negated? ? 'matches forbidden' : 'does not match required'
+          TestViolation.new(
+            message: 'File pattern violation',
+            details: "File '#{violation.projected_node.label}' #{relationship} " \
+                     "#{describe_filter(violation.check_filter)}."
+          )
+        end
+
+        def file_dependency(violation)
+          edge = violation.dependency
+          relationship = if violation.negated?
+                           'depends on forbidden file'
+                         else
+                           'depends on file outside the allowed target set'
+                         end
+          TestViolation.new(
+            message: 'File dependency violation',
+            details: "File '#{edge.source_label}' #{relationship} '#{edge.target_label}'."
+          )
+        end
+
+        def external_module_dependency(violation)
+          edge = violation.dependency
+          relationship = if violation.negated?
+                           'depends on forbidden external module'
+                         else
+                           'depends on external module outside the allowlist'
+                         end
+          TestViolation.new(
+            message: 'External module dependency violation',
+            details: "File '#{edge.source_label}' #{relationship} '#{edge.target_label}'."
+          )
+        end
+
+        def cycle(violation)
+          TestViolation.new(
+            message: 'Circular dependency detected',
+            details: "Cycle: #{violation.path.join(' -> ')}."
+          )
+        end
+
+        def custom_file(violation)
+          relationship = if violation.negated?
+                           'matched the forbidden predicate'
+                         else
+                           'failed the predicate'
+                         end
+          TestViolation.new(
+            message: violation.message,
+            details: "File '#{violation.file_info.path}' #{relationship}."
+          )
+        end
+
+        def generic(violation)
+          TestViolation.new(
+            message: 'Architecture violation',
+            details: "Unformatted violation type: #{violation.class.name}."
+          )
+        end
+
+        def describe_filter(filter)
+          target = {
+            filename: 'filename',
+            path_without_filename: 'folder',
+            path: 'path',
+            classname: 'class name'
+          }.fetch(filter.target)
+          "#{target} pattern /#{filter.regexp.source}/ (#{filter.matching})"
+        end
+      end
+
+      private_class_method :new
+    end
+  end
+end

data/lib/archunit/testing.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'testing/color_utils'
+require_relative 'testing/test_violation'
+require_relative 'testing/test_result'
+require_relative 'testing/violation_factory'
+require_relative 'testing/result_factory'
+require_relative 'testing/assertion_failure'
+require_relative 'testing/assert_passes'
+
+# Public violation formatting entry points.
+module ArchUnit
+  # Violation presentation and test-framework integration.
+  module Testing
+    module_function
+
+    def format_violations(violations, color: nil)
+      ResultFactory.from_violations(violations, color:).message
+    end
+
+    def result_for(rule, options = nil, expected_to_pass: true)
+      unless rule.is_a?(Common::FluentApi::Checkable)
+        raise ArgumentError, 'rule must implement Checkable'
+      end
+
+      violations = rule.check(options)
+      return ResultFactory.from_violations(violations) if expected_to_pass
+
+      ResultFactory.from_violations(violations, expected_to_pass: false)
+    end
+  end
+
+  def self.format_violations(violations, color: nil)
+    Testing.format_violations(violations, color:)
+  end
+end
+
+require_relative 'testing/rspec_adapter'
+require_relative 'testing/minitest_adapter'

data/lib/archunit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  VERSION = '0.0.1'
+end

data/lib/archunit.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative 'archunit/version'
+require_relative 'archunit/error/technical_error'
+require_relative 'archunit/error/user_error'
+require_relative 'archunit/common/pattern'
+require_relative 'archunit/common/filter'
+require_relative 'archunit/common/pattern_matching'
+require_relative 'archunit/common/regex_factory'
+require_relative 'archunit/common/logging/logging_options'
+require_relative 'archunit/common/logging/check_logger'
+require_relative 'archunit/common/assertion/violation'
+require_relative 'archunit/common/assertion/empty_test_violation'
+require_relative 'archunit/common/fluentapi/check_options'
+require_relative 'archunit/common/fluentapi/checkable'
+require_relative 'archunit/common/extraction/import_kind'
+require_relative 'archunit/common/extraction/edge'
+require_relative 'archunit/common/extraction/graph'
+require_relative 'archunit/common/projection/mapped_edge'
+require_relative 'archunit/common/projection/projected_edge'
+require_relative 'archunit/common/projection/projected_node'
+require_relative 'archunit/common/projection/edge_projections'
+require_relative 'archunit/common/projection/project_edges'
+require_relative 'archunit/common/projection/project_to_nodes'
+require_relative 'archunit/common/projection/project_cycles'
+require_relative 'archunit/extraction/locate_project'
+require_relative 'archunit/extraction/enumerate_source_files'
+require_relative 'archunit/extraction/resolved_import'
+require_relative 'archunit/extraction/resolve_import'
+require_relative 'archunit/extraction/extract_imports'
+require_relative 'archunit/extraction/extract_dependencies'
+require_relative 'archunit/extraction/extract_graph'
+require_relative 'archunit/files/fluentapi/files'
+require_relative 'archunit/layers/fluentapi/layers'
+require_relative 'archunit/slices/fluentapi/slices'
+require_relative 'archunit/graph/fluentapi/graph'
+require_relative 'archunit/metrics/fluentapi/metrics'
+require_relative 'archunit/testing'
+
+# Public ArchUnitRuby API and shared data types.
+module ArchUnit
+  Filter = Common::Filter
+  PatternMatching = Common::PatternMatching
+  RegexFactory = Common::RegexFactory
+  LoggingOptions = Common::Logging::LoggingOptions
+  CheckLogger = Common::Logging::CheckLogger
+  Violation = Common::Assertion::Violation
+  EmptyTestViolation = Common::Assertion::EmptyTestViolation
+  CheckOptions = Common::FluentApi::CheckOptions
+  Checkable = Common::FluentApi::Checkable
+  ImportKind = Common::Extraction::ImportKind
+  Edge = Common::Extraction::Edge
+  Graph = Common::Extraction::Graph
+  MappedEdge = Common::Projection::MappedEdge
+  ProjectedEdge = Common::Projection::ProjectedEdge
+  ProjectedNode = Common::Projection::ProjectedNode
+  CycleViolation = Files::Assertion::CycleViolation
+  FilePatternViolation = Files::Assertion::FilePatternViolation
+  FileDependencyViolation = Files::Assertion::FileDependencyViolation
+  ExternalModuleDependencyViolation = Files::Assertion::ExternalModuleDependencyViolation
+  FileInfo = Files::Extraction::FileInfo
+  CustomFileViolation = Files::Assertion::CustomFileViolation
+  LayerDefinition = Layers::Assertion::LayerDefinition
+  LayerDependencyViolation = Layers::Assertion::LayerDependencyViolation
+  SliceProjection = Slices::Projection::SliceProjection
+  SliceProjections = Slices::Projection
+  SliceDependencyViolation = Slices::Assertion::SliceDependencyViolation
+  DiagramAdherenceOptions = Slices::Assertion::DiagramAdherenceOptions
+  PlantUmlDependency = Slices::Uml::PlantUmlDependency
+  PlantUmlDiagram = Slices::Uml::PlantUmlDiagram
+  PlantUmlParser = Slices::Uml::PlantUmlParser
+  PlantUmlRenderer = Slices::Uml::PlantUmlRenderer
+  FolderDepthCollapse = GraphReporting::Projection::FolderDepthCollapse
+  PatternCollapse = GraphReporting::Projection::PatternCollapse
+  GraphQueryOptions = GraphReporting::Projection::GraphQueryOptions
+  GraphReportNode = GraphReporting::Projection::GraphReportNode
+  GraphReportEdge = GraphReporting::Projection::GraphReportEdge
+  GraphReportSummary = GraphReporting::Projection::GraphReportSummary
+  GraphReportSnapshot = GraphReporting::Projection::GraphReportSnapshot
+  GraphSnapshotFactory = GraphReporting::Projection::SnapshotFactory
+  GraphRenderer = GraphReporting::Rendering::GraphRenderer
+  MetricMethodInfo = Metrics::Extraction::MethodInfo
+  MetricFieldInfo = Metrics::Extraction::FieldInfo
+  ClassInfo = Metrics::Extraction::ClassInfo
+  MetricFileInfo = Metrics::Extraction::FileInfo
+  MetricProjectInfo = Metrics::Extraction::ProjectInfo
+  DistanceInfo = Metrics::Extraction::DistanceInfo
+  Metric = Metrics::Calculation::Metric
+  CountMetrics = Metrics::Calculation::Count
+  LCOMMetrics = Metrics::Calculation::LCOM
+  DistanceMetrics = Metrics::Calculation::Distance
+  MetricMeasurement = Metrics::FluentApi::MetricMeasurement
+  MetricsExportOptions = Metrics::Reporting::MetricsExportOptions
+  MetricsExporter = Metrics::Reporting::MetricsExporter
+  MetricExtraction = Metrics::Extraction
+  MetricZoneViolation = Metrics::Assertion::MetricZoneViolation
+  MetricThresholdViolation = Metrics::Assertion::MetricThresholdViolation
+  MetricPredicateViolation = Metrics::Assertion::MetricPredicateViolation
+  CustomMetricViolation = Metrics::Assertion::CustomMetricViolation
+  TestViolation = Testing::TestViolation
+  TestResult = Testing::TestResult
+  ColorUtils = Testing::ColorUtils
+  ViolationFactory = Testing::ViolationFactory
+  ResultFactory = Testing::ResultFactory
+  AssertionFailure = Testing::AssertionFailure
+
+  def self.clear_graph_cache
+    Extraction.clear_graph_cache
+  end
+end