archunit 0.0.1

data/lib/archunit/slices/projection/slice_projection.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative '../../common/extraction/edge'
+require_relative '../../common/pattern_matching'
+require_relative '../../common/projection/mapped_edge'
+
+module ArchUnit
+  module Slices
+    # Projections from file dependencies into architectural slices.
+    module Projection
+      # Immutable callable mapper that also exposes the selected internal slice names.
+      class SliceProjection
+        def initialize(&labeler)
+          raise ArgumentError, 'a slice labeler block is required' unless labeler
+
+          @labeler = labeler.freeze
+          freeze
+        end
+
+        def call(edge)
+          validate_edge(edge)
+          return if edge.source == edge.target
+
+          source_label = label_for(edge.source)
+          return unless source_label
+
+          target_label = edge.external ? edge.target : label_for(edge.target)
+          return unless target_label
+          return if !edge.external && source_label == target_label
+
+          Common::Projection::MappedEdge.new(source_label:, target_label:)
+        end
+
+        def slice_labels(graph)
+          labels = []
+          each_edge(graph) do |edge|
+            labels << label_for(edge.source)
+            labels << label_for(edge.target) unless edge.external
+          end
+          labels.compact.uniq.sort.freeze
+        end
+
+        def label_for(path)
+          unless path.is_a?(String) && !path.empty?
+            raise ArgumentError, 'path must be a non-empty String'
+          end
+
+          label = @labeler.call(Common::PatternMatching.normalize_path(path))
+          return if label.nil?
+          return label.dup.freeze if label.is_a?(String) && !label.empty?
+
+          raise TypeError, 'slice labelers must return a non-empty String or nil'
+        end
+
+        private
+
+        def each_edge(graph)
+          unless graph.respond_to?(:each)
+            raise ArgumentError, 'graph must be an enumerable of Edge values'
+          end
+
+          graph.each do |edge|
+            validate_edge(edge)
+            yield edge
+          end
+        end
+
+        def validate_edge(value)
+          return if value.is_a?(Common::Extraction::Edge)
+
+          raise ArgumentError, 'graph must contain only Edge values'
+        end
+      end
+    end
+  end
+end

data/lib/archunit/slices/projection/slicing_projections.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative 'slice_projection'
+require_relative '../../common/pattern_matching'
+require_relative '../../common/regex_factory'
+
+module ArchUnit
+  module Slices
+    # Projections from file dependencies into architectural slices.
+    module Projection
+      CAPTURE = '(**)'
+
+      module_function
+
+      def identity
+        SliceProjection.new { |path| path }
+      end
+
+      def slice_by_pattern(pattern, except: nil)
+        regexp = slice_pattern_regexp(pattern)
+        slice_by_regex(regexp, except:)
+      end
+
+      def slice_by_regex(regexp, except: nil)
+        regexp = immutable_regexp(regexp)
+        selector = Common::RegexFactory.path_matcher('**', except:)
+        SliceProjection.new do |path|
+          next unless Common::PatternMatching.matches_pattern?(path, selector)
+
+          match = regexp.match(path)
+          match && non_empty_capture(match[1])
+        end
+      end
+
+      def slice_by_file_suffix(labeling)
+        labels = immutable_suffix_labels(labeling)
+        SliceProjection.new do |path|
+          filename = path.split('/').last
+          extension = File.extname(filename)
+          stem = extension.empty? ? filename : filename.delete_suffix(extension)
+          labels.find { |suffix, _label| stem.end_with?(suffix) }&.last
+        end
+      end
+
+      def slice_pattern_regexp(pattern)
+        validate_slice_pattern(pattern)
+
+        escaped = Regexp.escape(pattern.tr('\\', '/'))
+        source = escaped.sub(Regexp.escape(CAPTURE), '([^/]+)')
+                        .gsub('\\*\\*', '.*')
+                        .gsub('\\*', '[^/]*')
+        Regexp.new(source).freeze
+      end
+      private_class_method :slice_pattern_regexp
+
+      def validate_slice_pattern(value)
+        unless value.is_a?(String) && !value.empty?
+          raise ArgumentError, 'pattern must be a non-empty String'
+        end
+        return if value.scan(CAPTURE).length == 1
+
+        raise ArgumentError, "pattern must contain exactly one #{CAPTURE} slice capture"
+      end
+      private_class_method :validate_slice_pattern
+
+      def immutable_regexp(value)
+        return Regexp.new(value.source, value.options).freeze if value.is_a?(Regexp)
+
+        raise ArgumentError, 'regexp must be a Regexp with a slice capture group'
+      end
+      private_class_method :immutable_regexp
+
+      def non_empty_capture(value)
+        value if value.is_a?(String) && !value.empty?
+      end
+      private_class_method :non_empty_capture
+
+      def immutable_suffix_labels(value)
+        unless value.is_a?(Hash) && !value.empty?
+          raise ArgumentError, 'labeling must be a non-empty Hash of suffixes to slice names'
+        end
+
+        labels = value.map do |suffix, label|
+          [non_empty_string(suffix, :suffix), non_empty_string(label, :slice_name)]
+        end
+        labels.sort_by { |suffix, _label| -suffix.length }.freeze
+      end
+      private_class_method :immutable_suffix_labels
+
+      def non_empty_string(value, attribute)
+        return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+        raise ArgumentError, "#{attribute} must be a non-empty String"
+      end
+      private_class_method :non_empty_string
+    end
+  end
+end

data/lib/archunit/slices/uml/export_diagram.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative '../../common/projection/projected_edge'
+
+module ArchUnit
+  module Slices
+    # Parsing and rendering of the supported PlantUML component-diagram subset.
+    module Uml
+      # Stable PlantUML generation and UTF-8 file export for projected slice graphs.
+      module PlantUmlRenderer
+        module_function
+
+        def render(edges, components: [])
+          validate_edges(edges)
+          components = component_names(edges, components)
+          lines = ['@startuml']
+          lines.concat(components.map { |name| "  component [#{plant_uml_name(name)}]" })
+          lines.concat(sorted_edges(edges).map do |edge|
+            "  [#{plant_uml_name(edge.source_label)}] --> " \
+              "[#{plant_uml_name(edge.target_label)}]"
+          end)
+          "#{lines.append('@enduml').join("\n")}\n"
+        end
+
+        def export(edges, output_path, components: [])
+          path = normalized_path(output_path)
+          FileUtils.mkdir_p(File.dirname(path)) unless File.dirname(path) == '.'
+          File.binwrite(path, render(edges, components:).encode(Encoding::UTF_8))
+          nil
+        end
+
+        def component_names(edges, values)
+          edge_names = edges.flat_map { |edge| [edge.source_label, edge.target_label] }
+          names = [*Array(values), *edge_names]
+          names.map { |name| plant_uml_name(name) }.uniq.sort.freeze
+        end
+        private_class_method :component_names
+
+        def sorted_edges(edges)
+          edges.sort_by { |edge| [edge.source_label, edge.target_label] }
+        end
+        private_class_method :sorted_edges
+
+        def validate_edges(value)
+          return if value.is_a?(Array) && value.all?(Common::Projection::ProjectedEdge)
+
+          raise ArgumentError, 'edges must be an Array of ProjectedEdge values'
+        end
+        private_class_method :validate_edges
+
+        def plant_uml_name(value)
+          valid = value.is_a?(String) && !value.strip.empty? && !value.match?(/[\]\r\n]/)
+          return value.strip if valid
+
+          raise ArgumentError, 'PlantUML component names must be non-empty and cannot contain ]'
+        end
+        private_class_method :plant_uml_name
+
+        def normalized_path(value)
+          value = value.to_path if value.respond_to?(:to_path)
+          return value if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError, 'output_path must be a non-empty path'
+        end
+        private_class_method :normalized_path
+      end
+    end
+  end
+end

data/lib/archunit/slices/uml/parse_diagram.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'plant_uml_diagram'
+
+module ArchUnit
+  module Slices
+    # Parsing and rendering of the supported PlantUML component-diagram subset.
+    module Uml
+      # Line-based parser for PlantUML component declarations and directed arrows.
+      module PlantUmlParser
+        COMPONENT = /\Acomponent\s+\[([^\]]+)\]/i
+        DEPENDENCY = /\A\[([^\]]+)\]\s*-{1,2}>\s*\[([^\]]+)\]/
+
+        module_function
+
+        def parse(text)
+          unless text.is_a?(String) && !text.strip.empty?
+            raise ArgumentError, 'diagram text must be a non-empty String'
+          end
+
+          components = []
+          dependencies = []
+          text.each_line do |line|
+            parse_line(line, components, dependencies)
+          end
+          PlantUmlDiagram.new(components:, dependencies:)
+        end
+
+        def parse_line(line, components, dependencies)
+          line = uncommented(line)
+          return if line.empty? || line.start_with?('@')
+
+          if (match = COMPONENT.match(line))
+            components << match[1]
+          elsif (match = DEPENDENCY.match(line))
+            dependency = PlantUmlDependency.new(source: match[1], target: match[2])
+            dependencies << dependency
+            components.push(dependency.source, dependency.target)
+          end
+        end
+        private_class_method :parse_line
+
+        def uncommented(line)
+          stripped = line.strip
+          return '' if stripped.start_with?("'", '//')
+
+          stripped.split("'", 2).first.to_s.strip
+        end
+        private_class_method :uncommented
+      end
+    end
+  end
+end

data/lib/archunit/slices/uml/plant_uml_dependency.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Slices
+    # Parsing and rendering of the supported PlantUML component-diagram subset.
+    module Uml
+      # One allowed directed component dependency from a PlantUML diagram.
+      PlantUmlDependency = Data.define(:source, :target) do
+        def initialize(source:, target:)
+          source = component_name(source, :source)
+          target = component_name(target, :target)
+          super
+        end
+
+        private
+
+        def component_name(value, attribute)
+          return value.strip.freeze if value.is_a?(String) && !value.strip.empty?
+
+          raise ArgumentError, "#{attribute} must be a non-empty component name"
+        end
+      end
+    end
+  end
+end

data/lib/archunit/slices/uml/plant_uml_diagram.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'plant_uml_dependency'
+
+module ArchUnit
+  module Slices
+    # Parsing and rendering of the supported PlantUML component-diagram subset.
+    module Uml
+      # Immutable component names and allowed directed dependencies parsed from PlantUML.
+      PlantUmlDiagram = Data.define(:components, :dependencies) do
+        def initialize(components: [], dependencies: [])
+          dependencies = immutable_dependencies(dependencies)
+          components = immutable_components(components, dependencies)
+          super
+        end
+
+        def allows?(source, target)
+          dependencies.include?(PlantUmlDependency.new(source:, target:))
+        end
+
+        private
+
+        def immutable_dependencies(values)
+          dependencies = Array(values).dup
+          unless dependencies.all?(PlantUmlDependency)
+            raise ArgumentError, 'dependencies must contain only PlantUmlDependency values'
+          end
+
+          dependencies.uniq.freeze
+        end
+
+        def immutable_components(values, dependencies)
+          dependency_names = dependencies.flat_map { |item| [item.source, item.target] }
+          components = [*Array(values), *dependency_names]
+          unless components.all? { |name| name.is_a?(String) && !name.strip.empty? }
+            raise ArgumentError, 'components must contain only non-empty Strings'
+          end
+
+          components.map { |name| name.strip.freeze }.uniq.freeze
+        end
+      end
+    end
+  end
+end

data/lib/archunit/testing/assert_passes.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../common/fluentapi/checkable'
+require_relative 'assertion_failure'
+require_relative 'result_factory'
+
+# Public framework-neutral architecture assertion entry point.
+module ArchUnit
+  # Violation presentation and test-framework integration.
+  module Testing
+    module_function
+
+    def assert_passes(rule, options = nil)
+      result = result_for(rule, options)
+      return if result.passed?
+
+      raise AssertionFailure, result
+    end
+  end
+
+  def self.assert_passes(rule, options = nil)
+    Testing.assert_passes(rule, options)
+  end
+end

data/lib/archunit/testing/assertion_failure.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'test_result'
+
+module ArchUnit
+  # Violation presentation and test-framework integration.
+  module Testing
+    # Framework-neutral assertion failure used by the documented fallback helper.
+    class AssertionFailure < StandardError
+      attr_reader :result
+
+      def initialize(result)
+        unless result.is_a?(TestResult) && result.failed?
+          raise ArgumentError, 'result must be a failed TestResult'
+        end
+
+        @result = result
+        super(result.message)
+      end
+    end
+  end
+end

data/lib/archunit/testing/color_utils.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  # Violation presentation and test-framework integration.
+  module Testing
+    # ANSI colour helpers that degrade to plain text outside capable terminals.
+    class ColorUtils
+      RESET = "\e[0m"
+
+      class << self
+        def supported?(output: $stdout, environment: ENV)
+          return false unless environment['NO_COLOR'].to_s.empty?
+          return false if environment['TERM'] == 'dumb'
+
+          output.respond_to?(:tty?) && output.tty?
+        end
+
+        def red(text, enabled: supported?)
+          wrap('31', text, enabled:)
+        end
+
+        def green(text, enabled: supported?)
+          wrap('32', text, enabled:)
+        end
+
+        def yellow(text, enabled: supported?)
+          wrap('33', text, enabled:)
+        end
+
+        def blue(text, enabled: supported?)
+          wrap('34', text, enabled:)
+        end
+
+        def magenta(text, enabled: supported?)
+          wrap('35', text, enabled:)
+        end
+
+        def cyan(text, enabled: supported?)
+          wrap('36', text, enabled:)
+        end
+
+        def bold(text, enabled: supported?)
+          wrap('1', text, enabled:)
+        end
+
+        def dim(text, enabled: supported?)
+          wrap('2', text, enabled:)
+        end
+
+        private
+
+        def wrap(code, text, enabled:)
+          raise ArgumentError, 'text must be a String' unless text.is_a?(String)
+          unless [true, false].include?(enabled)
+            raise ArgumentError, 'enabled must be true or false'
+          end
+          return text unless enabled
+
+          "\e[#{code}m#{text}#{RESET}"
+        end
+      end
+
+      private_class_method :new
+    end
+  end
+end

data/lib/archunit/testing/layer_violation_formatter.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Testing
+    # Human-readable presentation for structured layer violations.
+    module LayerViolationFormatter
+      private
+
+      def layer_dependency(violation)
+        edge = violation.dependency
+        TestViolation.new(
+          message: 'Layer dependency violation',
+          details: "Layer '#{violation.source_layer}' #{layer_relationship(violation)} " \
+                   "'#{violation.target_layer}' via '#{edge.source_label}' -> " \
+                   "'#{edge.target_label}'."
+        )
+      end
+
+      def layer_relationship(violation)
+        return 'depends on forbidden layer' if violation.rule == :may_not_depend_on_layers
+
+        'depends on layer outside its allowlist'
+      end
+    end
+  end
+end

data/lib/archunit/testing/metric_violation_formatter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Testing
+    # Formatting helpers for structured metric violations.
+    module MetricViolationFormatter
+      FORMATTERS = {
+        Metrics::Assertion::CustomMetricViolation => :custom_metric,
+        Metrics::Assertion::MetricPredicateViolation => :metric_predicate,
+        Metrics::Assertion::MetricThresholdViolation => :metric_threshold,
+        Metrics::Assertion::MetricZoneViolation => :metric_zone
+      }.freeze
+
+      private
+
+      def custom_metric(violation)
+        TestViolation.new(
+          message: 'Custom metric violation',
+          details: "Class '#{violation.class_info.name}' in '#{violation.class_info.file_path}' " \
+                   "has #{violation.metric_name}=#{violation.value.inspect}; " \
+                   "#{violation.description}."
+        )
+      end
+
+      def metric_zone(violation)
+        zone = violation.zone == :pain ? 'pain' : 'uselessness'
+        TestViolation.new(
+          message: 'Metric zone violation',
+          details: "File '#{violation.distance_info.path}' is in the zone of #{zone} " \
+                   "(abstractness=#{format('%.2f', violation.abstractness)}, " \
+                   "instability=#{format('%.2f', violation.instability)})."
+        )
+      end
+
+      def metric_threshold(violation)
+        expectation = {
+          below: 'below', above: 'above', equal: 'equal to',
+          below_or_equal: 'below or equal to', above_or_equal: 'above or equal to'
+        }.fetch(violation.comparison)
+        TestViolation.new(
+          message: 'Metric threshold violation',
+          details: "Metric subject '#{violation.identifier}' has " \
+                   "#{violation.metric_name}=#{violation.value.inspect}; " \
+                   "expected #{expectation} #{violation.threshold.inspect}."
+        )
+      end
+
+      def metric_predicate(violation)
+        TestViolation.new(
+          message: 'Metric predicate violation',
+          details: "Metric subject '#{violation.identifier}' has " \
+                   "#{violation.metric_name}=#{violation.value.inspect}; " \
+                   'the should_satisfy predicate returned false.'
+        )
+      end
+    end
+  end
+end

data/lib/archunit/testing/minitest_adapter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Testing
+    # Native Minitest assertion methods mixed in only when Minitest is already loaded.
+    module MinitestAssertions
+      def assert_passes(rule, options = nil)
+        result = ArchUnit::Testing.result_for(rule, options)
+        assert(result.passed?, result.message)
+      end
+    end
+
+    # Silently installs the helper without making Minitest a runtime dependency.
+    module MinitestAdapter
+      module_function
+
+      def install!
+        return unless defined?(::Minitest::Assertions)
+        return if installed?
+
+        ::Minitest::Assertions.include(MinitestAssertions)
+        nil
+      end
+
+      def installed?
+        defined?(::Minitest::Assertions) &&
+          ::Minitest::Assertions.include?(MinitestAssertions)
+      end
+    end
+  end
+end
+
+ArchUnit::Testing::MinitestAdapter.install!