archunit 0.0.1

data/lib/archunit/layers/fluentapi/layered_architecture_values.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Layers
+    module FluentApi
+      # Validation and defensive copying for immutable layer policy builders.
+      module LayeredArchitectureValues
+        private
+
+        def validated_layer_name(value)
+          return value.dup.freeze if value.is_a?(String) && !value.strip.empty?
+
+          raise ArgumentError, 'layer name must be a non-empty String'
+        end
+
+        def immutable_project_locator(locator)
+          return if locator.nil?
+
+          locator = locator.to_path if locator.respond_to?(:to_path)
+          return locator.dup.freeze if locator.is_a?(String) && !locator.empty?
+
+          raise ArgumentError, 'project_locator must be a non-empty path or nil'
+        end
+
+        def immutable_layer_definitions(values)
+          definitions = Array(values).dup
+          unless definitions.all?(Assertion::LayerDefinition)
+            raise ArgumentError, 'layer_definitions must contain only LayerDefinition values'
+          end
+          unless definitions.map(&:name).uniq.length == definitions.length
+            raise ArgumentError, 'layer names must be unique'
+          end
+
+          definitions.freeze
+        end
+
+        def immutable_dependency_map(value)
+          raise ArgumentError, 'dependency policies must be Hash values' unless value.is_a?(Hash)
+
+          value.to_h do |source, targets|
+            immutable_source = validated_layer_name(source)
+            immutable_targets = Array(targets).map do |name|
+              validated_layer_name(name)
+            end.freeze
+            [immutable_source, immutable_targets]
+          end.freeze
+        end
+      end
+    end
+  end
+end

data/lib/archunit/layers/fluentapi/layers.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'layered_architecture'
+
+# Public ArchUnitRuby entry points for named layer policies.
+module ArchUnit
+  module Layers
+    # Sentence-like entry points and builders for layer architecture rules.
+    module FluentApi
+      module_function
+
+      def project_layers(project_locator = nil)
+        LayeredArchitecture.new(project_locator:)
+      end
+
+      class << self
+        alias layers project_layers
+      end
+    end
+  end
+
+  def self.project_layers(project_locator = nil)
+    Layers::FluentApi.project_layers(project_locator)
+  end
+
+  class << self
+    alias layers project_layers
+  end
+end

data/lib/archunit/metrics/assertion/custom_metric.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative '../../common/assertion/violation'
+require_relative '../calculation/metric'
+require_relative '../extraction/metric_info'
+
+module ArchUnit
+  module Metrics
+    # Pure assertions and structured custom metric violation data.
+    module Assertion
+      # A class whose calculated custom value did not satisfy the user's predicate.
+      class CustomMetricViolation < Common::Assertion::Violation
+        attr_reader :class_info, :metric_name, :description, :value
+
+        def initialize(class_info:, metric_name:, description:, value:)
+          @class_info = class_info_value(class_info)
+          @metric_name = immutable_string(metric_name, :metric_name)
+          @description = immutable_string(description, :description)
+          @value = numeric_value(value)
+          super()
+        end
+
+        private
+
+        def class_info_value(value)
+          return value if value.is_a?(Extraction::ClassInfo)
+
+          raise ArgumentError, 'class_info must be a ClassInfo value'
+        end
+
+        def immutable_string(value, attribute)
+          return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError, "#{attribute} must be a non-empty String"
+        end
+
+        def numeric_value(value)
+          return value if value.is_a?(Numeric)
+
+          raise ArgumentError, 'value must be Numeric'
+        end
+      end
+
+      module_function
+
+      def gather_custom_metric_violations(class_infos, metric, predicate)
+        validate_custom_metric_arguments(class_infos, metric, predicate)
+        class_infos.filter_map do |class_info|
+          value = metric.calculate(class_info)
+          next if predicate.call(value, class_info)
+
+          CustomMetricViolation.new(
+            class_info:, metric_name: metric.name,
+            description: metric.description, value:
+          )
+        end
+      end
+
+      def validate_custom_metric_arguments(class_infos, metric, predicate)
+        unless class_infos.is_a?(Array) && class_infos.all?(Extraction::ClassInfo)
+          raise ArgumentError, 'class_infos must be an Array of ClassInfo values'
+        end
+        unless metric.is_a?(Calculation::Metric) && metric.name.is_a?(String) && metric.description
+          raise ArgumentError, 'metric must be a described custom Metric'
+        end
+        return if predicate.respond_to?(:call)
+
+        raise ArgumentError, 'predicate must respond to call'
+      end
+      private_class_method :validate_custom_metric_arguments
+    end
+  end
+end

data/lib/archunit/metrics/assertion/metric_predicate.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative '../../common/assertion/violation'
+require_relative '../calculation/metric'
+require_relative '../calculation/numeric_value'
+
+module ArchUnit
+  module Metrics
+    # Pure arbitrary metric predicates and structured violation data.
+    module Assertion
+      # One built-in metric value that did not satisfy a user predicate.
+      class MetricPredicateViolation < Common::Assertion::Violation
+        attr_reader :subject, :metric_name, :value
+
+        def initialize(subject:, metric_name:, value:)
+          unless subject.respond_to?(:identifier)
+            raise ArgumentError, 'subject must expose an identifier'
+          end
+
+          @subject = subject
+          @metric_name = immutable_metric_name(metric_name)
+          @value = Calculation::NumericValue.validate(value)
+          super()
+        end
+
+        def identifier
+          subject.identifier
+        end
+
+        private
+
+        def immutable_metric_name(value)
+          return value if value.is_a?(Symbol)
+          return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError, 'metric_name must be a Symbol or non-empty String'
+        end
+      end
+
+      module_function
+
+      def gather_metric_predicate_violations(subjects, metric, predicate)
+        validate_predicate_assertion(subjects, metric, predicate)
+        subjects.filter_map do |subject|
+          value = metric.calculate(subject)
+          next if predicate.call(value, subject)
+
+          MetricPredicateViolation.new(subject:, metric_name: metric.name, value:)
+        end
+      end
+
+      def validate_predicate_assertion(subjects, metric, predicate)
+        raise ArgumentError, 'metric must be a Metric' unless metric.is_a?(Calculation::Metric)
+
+        unless subjects.is_a?(Array) && subjects.all?(metric.subject_type)
+          type_name = metric.subject_type.name.split('::').last
+          raise ArgumentError, "subjects must be an Array of #{type_name} values"
+        end
+        return if predicate.respond_to?(:call)
+
+        raise ArgumentError, 'predicate must respond to call'
+      end
+      private_class_method :validate_predicate_assertion
+    end
+  end
+end

data/lib/archunit/metrics/assertion/metric_threshold.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative '../../common/assertion/violation'
+require_relative '../calculation/metric'
+require_relative '../calculation/numeric_value'
+
+module ArchUnit
+  module Metrics
+    # Pure metric threshold assertions and structured violation data.
+    module Assertion
+      # One metric value that did not meet its numeric threshold.
+      class MetricThresholdViolation < Common::Assertion::Violation
+        COMPARISONS = %i[below above equal below_or_equal above_or_equal].freeze
+
+        attr_reader :subject, :metric_name, :value, :threshold, :comparison
+
+        def initialize(subject:, metric_name:, value:, threshold:, comparison:)
+          @subject = validated_subject(subject)
+          @metric_name = immutable_metric_name(metric_name)
+          @value = Calculation::NumericValue.validate(value)
+          @threshold = Calculation::NumericValue.validate(threshold, attribute: 'threshold')
+          @comparison = validated_comparison(comparison)
+          super()
+        end
+
+        def identifier
+          subject.identifier
+        end
+
+        private
+
+        def validated_subject(value)
+          return value if value.respond_to?(:identifier)
+
+          raise ArgumentError, 'subject must expose an identifier'
+        end
+
+        def validated_comparison(value)
+          return value if COMPARISONS.include?(value)
+
+          raise ArgumentError, "unknown metric comparison: #{value.inspect}"
+        end
+
+        def immutable_metric_name(value)
+          return value if value.is_a?(Symbol)
+          return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError, 'metric_name must be a Symbol or non-empty String'
+        end
+      end
+
+      module_function
+
+      def gather_metric_threshold_violations(subjects, metric, comparison, threshold)
+        validate_metric_assertion(subjects, metric)
+        threshold = validate_threshold(comparison, threshold)
+
+        subjects.filter_map do |subject|
+          value = metric.calculate(subject)
+          next if threshold_satisfied?(value, comparison, threshold)
+
+          MetricThresholdViolation.new(
+            subject:, metric_name: metric.name, value:, threshold:, comparison:
+          )
+        end
+      end
+
+      def validate_threshold(comparison, threshold)
+        unless MetricThresholdViolation::COMPARISONS.include?(comparison)
+          raise ArgumentError, "unknown metric comparison: #{comparison.inspect}"
+        end
+
+        Calculation::NumericValue.validate(threshold, attribute: 'threshold')
+      end
+      private_class_method :validate_threshold
+
+      def threshold_satisfied?(value, comparison, threshold)
+        case comparison
+        when :below then value < threshold
+        when :above then value > threshold
+        when :equal then value == threshold
+        when :below_or_equal then value <= threshold
+        when :above_or_equal then value >= threshold
+        end
+      end
+      private_class_method :threshold_satisfied?
+
+      def validate_metric_assertion(subjects, metric)
+        raise ArgumentError, 'metric must be a Metric' unless metric.is_a?(Calculation::Metric)
+
+        return if subjects.is_a?(Array) && subjects.all?(metric.subject_type)
+
+        type_name = metric.subject_type.name.split('::').last
+        raise ArgumentError, "subjects must be an Array of #{type_name} values"
+      end
+      private_class_method :validate_metric_assertion
+    end
+  end
+end

data/lib/archunit/metrics/assertion/metric_zone.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative '../../common/assertion/violation'
+require_relative '../calculation/distance'
+require_relative '../extraction/metric_info'
+
+module ArchUnit
+  module Metrics
+    # Pure assertions and structured metric violation data.
+    module Assertion
+      # A file whose abstractness/instability point falls in a discouraged zone.
+      class MetricZoneViolation < Common::Assertion::Violation
+        ZONES = %i[pain uselessness].freeze
+
+        attr_reader :distance_info, :zone
+
+        def initialize(distance_info:, zone:)
+          unless distance_info.is_a?(Extraction::DistanceInfo)
+            raise ArgumentError, 'distance_info must be a DistanceInfo value'
+          end
+          unless ZONES.include?(zone)
+            raise ArgumentError, "unknown architectural zone: #{zone.inspect}"
+          end
+
+          @distance_info = distance_info
+          @zone = zone
+          super()
+        end
+
+        def abstractness
+          Calculation::Distance.abstractness.calculate(distance_info)
+        end
+
+        def instability
+          Calculation::Distance.instability.calculate(distance_info)
+        end
+      end
+
+      module_function
+
+      def gather_metric_zone_violations(distance_infos, zone)
+        unless distance_infos.is_a?(Array) && distance_infos.all?(Extraction::DistanceInfo)
+          raise ArgumentError, 'distance_infos must be an Array of DistanceInfo values'
+        end
+        unless MetricZoneViolation::ZONES.include?(zone)
+          raise ArgumentError, "unknown architectural zone: #{zone.inspect}"
+        end
+
+        distance_infos.filter_map do |distance_info|
+          next unless Calculation::Distance.in_zone?(distance_info, zone)
+
+          MetricZoneViolation.new(distance_info:, zone:)
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/calculation/count.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative '../extraction/metric_info'
+require_relative 'metric'
+
+module ArchUnit
+  module Metrics
+    module Calculation
+      # Pure count metrics over extracted Ruby class and file information.
+      module Count
+        CLASS_METRICS = {
+          method_count: ->(class_info) { class_info.methods.length },
+          field_count: ->(class_info) { class_info.fields.length }
+        }.freeze
+        FILE_METRICS = {
+          lines_of_code: :lines_of_code.to_proc,
+          statements: :statement_count.to_proc,
+          imports: :import_count.to_proc,
+          classes: :class_count.to_proc,
+          functions: :function_count.to_proc
+        }.freeze
+
+        CLASS_METRICS.each do |name, calculation|
+          define_singleton_method(name) do
+            Metric.new(
+              name:,
+              subject_type: Metrics::Extraction::ClassInfo,
+              calculation:
+            )
+          end
+        end
+
+        FILE_METRICS.each do |name, calculation|
+          define_singleton_method(name) do
+            Metric.new(
+              name:,
+              subject_type: Metrics::Extraction::FileInfo,
+              calculation:
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/calculation/distance.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative '../extraction/metric_info'
+require_relative 'metric'
+
+module ArchUnit
+  module Metrics
+    module Calculation
+      # Robert C. Martin's abstractness, instability, distance, and zone calculations.
+      module Distance
+        PAIN_LIMIT = 0.3
+        USELESSNESS_LIMIT = 0.7
+        SIZE_NORMALIZATION_LINES = 100.0
+        MAXIMUM_SIZE_DISCOUNT = 0.5
+
+        CALCULATIONS = {
+          abstractness: ->(info) { abstractness_value(info) },
+          instability: ->(info) { instability_value(info) },
+          distance_from_main_sequence: ->(info) { distance_value(info) },
+          coupling_factor: ->(info) { coupling_factor_value(info) },
+          normalized_distance: ->(info) { normalized_distance_value(info) }
+        }.freeze
+
+        CALCULATIONS.each do |name, calculation|
+          define_singleton_method(name) do
+            Metric.new(
+              name:, subject_type: Metrics::Extraction::DistanceInfo, calculation:
+            )
+          end
+        end
+
+        module_function
+
+        def in_zone?(distance_info, zone)
+          abstractness = abstractness_value(distance_info)
+          instability = instability_value(distance_info)
+          case zone
+          when :pain
+            abstractness < PAIN_LIMIT && instability < PAIN_LIMIT
+          when :uselessness
+            abstractness > USELESSNESS_LIMIT && instability > USELESSNESS_LIMIT
+          else
+            raise ArgumentError, "unknown architectural zone: #{zone.inspect}"
+          end
+        end
+
+        def abstractness_value(info)
+          return 0.0 if info.type_count.zero?
+
+          info.abstract_type_count.fdiv(info.type_count)
+        end
+        private_class_method :abstractness_value
+
+        def instability_value(info)
+          total = info.afferent_coupling + info.efferent_coupling
+          return 0.0 if total.zero?
+
+          info.efferent_coupling.fdiv(total)
+        end
+        private_class_method :instability_value
+
+        def distance_value(info)
+          (abstractness_value(info) + instability_value(info) - 1.0).abs
+        end
+        private_class_method :distance_value
+
+        def coupling_factor_value(info)
+          possible = 2 * (info.project_file_count - 1)
+          return 0.0 if possible.zero?
+
+          (info.afferent_coupling + info.efferent_coupling).fdiv(possible)
+        end
+        private_class_method :coupling_factor_value
+
+        def normalized_distance_value(info)
+          size_ratio = [info.lines_of_code.fdiv(SIZE_NORMALIZATION_LINES), 1.0].min
+          discount = size_ratio * MAXIMUM_SIZE_DISCOUNT
+          distance_value(info) * (1.0 - discount)
+        end
+        private_class_method :normalized_distance_value
+      end
+    end
+  end
+end

data/lib/archunit/metrics/calculation/lcom.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative '../extraction/metric_info'
+require_relative 'metric'
+
+module ArchUnit
+  module Metrics
+    module Calculation
+      # Pure lack-of-cohesion calculations over extracted method/field relationships.
+      module LCOM
+        CALCULATIONS = {
+          lcom96a: ->(class_info) { normalized_method_field_distance(class_info) },
+          lcom96b: ->(class_info) { method_field_density_complement(class_info) },
+          lcom1: ->(class_info) { pair_difference(class_info) },
+          lcom2: ->(class_info) { method_field_density_complement(class_info) },
+          lcom3: ->(class_info) { normalized_method_field_distance(class_info) },
+          lcom4: ->(class_info) { connected_components(class_info) },
+          lcom5: ->(class_info) { normalized_method_field_distance(class_info) },
+          lcom_star: ->(class_info) { normalized_method_field_distance(class_info) }
+        }.freeze
+
+        CALCULATIONS.each do |name, calculation|
+          define_singleton_method(name) do
+            Metric.new(
+              name:,
+              subject_type: Metrics::Extraction::ClassInfo,
+              calculation:
+            )
+          end
+        end
+
+        module_function
+
+        def normalized_method_field_distance(class_info)
+          method_count = class_info.methods.length
+          field_count = class_info.fields.length
+          return 0.0 if method_count <= 1 || field_count.zero?
+
+          average_accesses = field_access_count(class_info).fdiv(field_count)
+          (method_count - average_accesses).fdiv(method_count - 1)
+        end
+        private_class_method :normalized_method_field_distance
+
+        def method_field_density_complement(class_info)
+          method_count = class_info.methods.length
+          field_count = class_info.fields.length
+          return 0.0 if method_count <= 1 || field_count.zero?
+
+          1.0 - field_access_count(class_info).fdiv(method_count * field_count)
+        end
+        private_class_method :method_field_density_complement
+
+        def field_access_count(class_info)
+          class_info.fields.sum { |field| field.accessed_by.length }
+        end
+        private_class_method :field_access_count
+
+        def pair_difference(class_info)
+          sharing, non_sharing = method_pairs(class_info).partition do |left, right|
+            fields_overlap?(left, right)
+          end
+          [non_sharing.length - sharing.length, 0].max
+        end
+        private_class_method :pair_difference
+
+        def method_pairs(class_info)
+          class_info.methods.combination(2).to_a
+        end
+        private_class_method :method_pairs
+
+        def fields_overlap?(left, right)
+          left.accessed_fields.intersect?(right.accessed_fields)
+        end
+        private_class_method :fields_overlap?
+
+        def connected_components(class_info)
+          methods = class_info.methods
+          return 0 if methods.empty?
+
+          remaining = methods.dup
+          components = 0
+          until remaining.empty?
+            components += 1
+            remove_component(remaining)
+          end
+          components
+        end
+        private_class_method :connected_components
+
+        def remove_component(remaining)
+          pending = [remaining.first]
+          until pending.empty?
+            method = pending.pop
+            next unless remaining.delete(method)
+
+            pending.concat(remaining.select { |candidate| fields_overlap?(method, candidate) })
+          end
+        end
+        private_class_method :remove_component
+      end
+    end
+  end
+end

data/lib/archunit/metrics/calculation/metric.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'numeric_value'
+
+module ArchUnit
+  module Metrics
+    module Calculation
+      # Immutable named calculation over one extracted subject type.
+      Metric = Data.define(:name, :subject_type, :calculation, :description) do
+        def initialize(name:, subject_type:, calculation:, description: nil)
+          name = immutable_name(name)
+          raise ArgumentError, 'subject_type must be a Class' unless subject_type.is_a?(Class)
+          unless calculation.respond_to?(:call)
+            raise ArgumentError, 'calculation must respond to call'
+          end
+
+          calculation = calculation.dup.freeze
+          description = immutable_description(description)
+          super
+        end
+
+        def calculate(subject)
+          unless subject.is_a?(subject_type)
+            raise ArgumentError, "subject must be a #{subject_type.name.split('::').last}"
+          end
+
+          NumericValue.validate(
+            calculation.call(subject),
+            attribute: 'metric calculations',
+            error_class: TypeError
+          )
+        end
+
+        private
+
+        def immutable_name(value)
+          return value if value.is_a?(Symbol)
+          return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError, 'name must be a Symbol or non-empty String'
+        end
+
+        def immutable_description(value)
+          return if value.nil?
+          return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError, 'description must be a non-empty String or nil'
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/calculation/numeric_value.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Metrics
+    module Calculation
+      # Validation shared by metric calculations, thresholds, and measurements.
+      module NumericValue
+        module_function
+
+        def validate(value, attribute: 'value', error_class: ArgumentError)
+          return value if finite_real_number?(value)
+
+          raise error_class, "#{attribute} must be a finite real Numeric value"
+        end
+
+        def finite_real_number?(value)
+          return false unless value.is_a?(Numeric) && value.real?
+          return value.finite? if value.respond_to?(:finite?)
+
+          true
+        end
+      end
+    end
+  end
+end