archunit 0.0.1

data/lib/archunit/metrics/fluentapi/custom_metric_builder.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative '../calculation/metric'
+require_relative '../extraction/metric_info'
+require_relative 'custom_metric_condition'
+require_relative 'metric_selection'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # A user-defined class calculation that can be measured or asserted.
+      class CustomMetricBuilder < MetricSelection
+        def initialize(scope:, name:, description:, calculation:)
+          unless name.is_a?(String) && !name.empty?
+            raise ArgumentError, 'custom metric name must be a non-empty String'
+          end
+
+          metric = Calculation::Metric.new(
+            name:, description:, subject_type: Extraction::ClassInfo, calculation:
+          )
+          super(scope:, metric:)
+        end
+
+        def should_satisfy(predicate)
+          CustomMetricCondition.new(selection: self, predicate:)
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/fluentapi/custom_metric_condition.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative '../../common/fluentapi/checkable'
+require_relative '../assertion/custom_metric'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # Executable custom class-metric predicate.
+      class CustomMetricCondition
+        include Common::FluentApi::Checkable
+
+        attr_reader :selection, :predicate
+
+        def initialize(selection:, predicate:)
+          unless selection.is_a?(CustomMetricBuilder)
+            raise ArgumentError, 'selection must be a CustomMetricBuilder'
+          end
+          raise ArgumentError, 'predicate must respond to call' unless predicate.respond_to?(:call)
+
+          @selection = selection
+          @predicate = predicate.dup.freeze
+          freeze
+        end
+
+        private
+
+        def perform_check(options)
+          classes = selection.scope.__send__(:subjects_for, Extraction::ClassInfo, options:)
+          empty_test = empty_test_violation(
+            classes, filters: selection.scope.filters, negated: false, options:
+          )
+          return empty_test if empty_test
+
+          Assertion.gather_custom_metric_violations(classes, selection.metric, predicate)
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/fluentapi/distance_metrics_builder.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative '../calculation/distance'
+require_relative 'metric_report_builder'
+require_relative 'metric_selection'
+require_relative 'zone_condition'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # Fluent distance metric names and architectural zone guards.
+      class DistanceMetricsBuilder
+        include MetricReportBuilder
+
+        attr_reader :scope
+
+        def initialize(scope)
+          raise ArgumentError, 'scope must be a MetricsBuilder' unless scope.is_a?(MetricsBuilder)
+
+          @scope = scope
+          freeze
+        end
+
+        Calculation::Distance::CALCULATIONS.each_key do |name|
+          define_method(name) do
+            MetricSelection.new(scope:, metric: Calculation::Distance.public_send(name))
+          end
+        end
+
+        def not_in_zone_of_pain
+          ZoneCondition.new(scope:, zone: :pain)
+        end
+
+        def not_in_zone_of_uselessness
+          ZoneCondition.new(scope:, zone: :uselessness)
+        end
+
+        private
+
+        def report_metrics
+          Calculation::Distance::CALCULATIONS.each_key.map do |name|
+            Calculation::Distance.public_send(name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/fluentapi/lcom_metrics_builder.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative '../calculation/lcom'
+require_relative 'metric_report_builder'
+require_relative 'metric_selection'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # Fluent LCOM metric names for one immutable metrics scope.
+      class LCOMMetricsBuilder
+        include MetricReportBuilder
+
+        attr_reader :scope
+
+        def initialize(scope)
+          raise ArgumentError, 'scope must be a MetricsBuilder' unless scope.is_a?(MetricsBuilder)
+
+          @scope = scope
+          freeze
+        end
+
+        Calculation::LCOM::CALCULATIONS.each_key do |name|
+          define_method(name) do
+            MetricSelection.new(scope:, metric: Calculation::LCOM.public_send(name))
+          end
+        end
+
+        private
+
+        def report_metrics
+          Calculation::LCOM::CALCULATIONS.each_key.map do |name|
+            Calculation::LCOM.public_send(name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/fluentapi/metric_measurement.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative '../calculation/numeric_value'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # One calculated metric value and the extracted subject it describes.
+      MetricMeasurement = Data.define(:subject, :metric_name, :value) do
+        def initialize(subject:, metric_name:, value:)
+          unless subject.respond_to?(:identifier)
+            raise ArgumentError, 'subject must expose an identifier'
+          end
+
+          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
+    end
+  end
+end

data/lib/archunit/metrics/fluentapi/metric_predicate_condition.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative '../../common/fluentapi/checkable'
+require_relative '../assertion/metric_predicate'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # Executable arbitrary predicate over one selected built-in metric.
+      class MetricPredicateCondition
+        include Common::FluentApi::Checkable
+
+        attr_reader :selection, :predicate
+
+        def initialize(selection:, predicate:)
+          unless selection.is_a?(MetricSelection)
+            raise ArgumentError, 'selection must be a MetricSelection'
+          end
+          raise ArgumentError, 'predicate must respond to call' unless predicate.respond_to?(:call)
+
+          @selection = selection
+          @predicate = predicate.dup.freeze
+          freeze
+        end
+
+        private
+
+        def perform_check(options)
+          subjects = selection.scope.__send__(
+            :subjects_for, selection.metric.subject_type, options:
+          )
+          empty_test = empty_test_violation(
+            subjects, filters: selection.scope.filters, negated: false, options:
+          )
+          return empty_test if empty_test
+
+          Assertion.gather_metric_predicate_violations(subjects, selection.metric, predicate)
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/fluentapi/metric_report_builder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative '../reporting/metrics_export_options'
+require_relative '../reporting/metrics_exporter'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # Shared HTML export terminal for one family of scoped metrics.
+      module MetricReportBuilder
+        def export_as_html(output_path, options = nil)
+          options = Reporting::MetricsExportOptions.resolve(options).with(output_path:)
+          Reporting::MetricsExporter.export_as_html(metric_report_data, options)
+          nil
+        end
+
+        private
+
+        def metric_report_data
+          report_metrics.group_by(&:subject_type).each_with_object({}) do |(type, metrics), data|
+            subjects = scope.__send__(:subjects_for, type)
+            metrics.each { |metric| add_metric_values(data, subjects, metric) }
+          end.freeze
+        end
+
+        def add_metric_values(data, subjects, metric)
+          subjects.each do |subject|
+            data["#{metric.name} [#{subject.identifier}]"] = metric.calculate(subject)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/fluentapi/metric_selection.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative '../calculation/metric'
+require_relative 'metric_measurement'
+require_relative 'metric_predicate_condition'
+require_relative 'metric_threshold_condition'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # Lazy selection of one metric over a metrics scope.
+      class MetricSelection
+        THRESHOLD_METHODS = {
+          should_be_below: :below,
+          should_be_above: :above,
+          should_be: :equal,
+          should_be_below_or_equal: :below_or_equal,
+          should_be_above_or_equal: :above_or_equal
+        }.freeze
+
+        attr_reader :scope, :metric
+
+        def initialize(scope:, metric:)
+          raise ArgumentError, 'scope must be a MetricsBuilder' unless scope.is_a?(MetricsBuilder)
+          raise ArgumentError, 'metric must be a Metric' unless metric.is_a?(Calculation::Metric)
+
+          @scope = scope
+          @metric = metric
+          freeze
+        end
+
+        def measure
+          scope.__send__(:subjects_for, metric.subject_type).map do |subject|
+            MetricMeasurement.new(
+              subject:,
+              metric_name: metric.name,
+              value: metric.calculate(subject)
+            )
+          end.freeze
+        end
+
+        THRESHOLD_METHODS.each do |method_name, comparison|
+          define_method(method_name) do |threshold|
+            MetricThresholdCondition.new(selection: self, comparison:, threshold:)
+          end
+        end
+
+        def should_satisfy(predicate)
+          MetricPredicateCondition.new(selection: self, predicate:)
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/fluentapi/metric_threshold_condition.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative '../../common/fluentapi/checkable'
+require_relative '../assertion/metric_threshold'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # Executable numeric threshold over one selected metric.
+      class MetricThresholdCondition
+        include Common::FluentApi::Checkable
+
+        attr_reader :selection, :comparison, :threshold
+
+        def initialize(selection:, comparison:, threshold:)
+          unless selection.is_a?(MetricSelection)
+            raise ArgumentError, 'selection must be a MetricSelection'
+          end
+          unless Assertion::MetricThresholdViolation::COMPARISONS.include?(comparison)
+            raise ArgumentError, "unknown metric comparison: #{comparison.inspect}"
+          end
+
+          @selection = selection
+          @comparison = comparison
+          @threshold = Calculation::NumericValue.validate(threshold, attribute: 'threshold')
+          freeze
+        end
+
+        private
+
+        def perform_check(options)
+          subjects = selection.scope.__send__(
+            :subjects_for, selection.metric.subject_type, options:
+          )
+          empty_test = empty_test_violation(
+            subjects, filters: selection.scope.filters, negated: false, options:
+          )
+          return empty_test if empty_test
+
+          Assertion.gather_metric_threshold_violations(
+            subjects, selection.metric, comparison, threshold
+          )
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/fluentapi/metrics.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'metrics_builder'
+
+# Public ArchUnitRuby API.
+module ArchUnit
+  module Metrics
+    # Public entry point for numeric Ruby source metrics.
+    module FluentApi
+      module_function
+
+      def metrics(project_locator = nil)
+        MetricsBuilder.new(project_locator:)
+      end
+    end
+  end
+
+  def self.metrics(project_locator = nil)
+    Metrics::FluentApi.metrics(project_locator)
+  end
+end

data/lib/archunit/metrics/fluentapi/metrics_builder.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative '../../common/filter'
+require_relative '../../common/pattern_matching'
+require_relative '../../common/regex_factory'
+require_relative '../extraction/extract_project_info'
+require_relative '../extraction/extract_distance_info'
+require_relative 'count_metrics_builder'
+require_relative 'custom_metric_builder'
+require_relative 'distance_metrics_builder'
+require_relative 'lcom_metrics_builder'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # Immutable scope builder for numeric metrics over Ruby source.
+      class MetricsBuilder
+        attr_reader :project_locator, :filters
+
+        def initialize(project_locator: nil, filters: [])
+          @project_locator = immutable_project_locator(project_locator)
+          @filters = immutable_filters(filters)
+          freeze
+        end
+
+        def with_name(pattern, except: nil)
+          with_filter(Common::RegexFactory.filename_matcher(pattern, except:))
+        end
+
+        def in_folder(pattern, except: nil)
+          with_filter(Common::RegexFactory.folder_matcher(pattern, except:))
+        end
+
+        def in_path(pattern, except: nil)
+          with_filter(Common::RegexFactory.path_matcher(pattern, except:))
+        end
+
+        def for_classes_matching(pattern, except: nil)
+          with_filter(Common::RegexFactory.classname_matcher(pattern, except:))
+        end
+
+        def count
+          CountMetricsBuilder.new(self)
+        end
+
+        def lcom
+          LCOMMetricsBuilder.new(self)
+        end
+
+        def distance
+          DistanceMetricsBuilder.new(self)
+        end
+
+        def custom_metric(name, description, calculation)
+          CustomMetricBuilder.new(scope: self, name:, description:, calculation:)
+        end
+
+        def analyze
+          project = Extraction.extract_project_info(project_locator)
+          selected_files = project.files.filter_map { |file| selected_file_info(file) }
+          Extraction::ProjectInfo.new(project_root: project.project_root, files: selected_files)
+        end
+
+        private
+
+        def with_filter(filter)
+          self.class.new(project_locator:, filters: [*filters, filter])
+        end
+
+        def subjects_for(subject_type, options: nil)
+          return distance_subjects(options:) if subject_type == Extraction::DistanceInfo
+
+          project = analyze
+          return project.files if subject_type == Extraction::FileInfo
+          return project.classes if subject_type == Extraction::ClassInfo
+
+          raise ArgumentError, "unsupported metric subject type: #{subject_type}"
+        end
+
+        def distance_subjects(options: nil)
+          Extraction.extract_distance_infos(project_locator, options:).select do |distance_info|
+            file_selected?(distance_info.file_info)
+          end
+        end
+
+        def file_selected?(file_info)
+          !selected_file_info(file_info).nil?
+        end
+
+        def selected_file_info(file_info)
+          path_filters, class_filters = partitioned_filters
+          matches_path = Common::PatternMatching.matches_all_patterns?(file_info.path, path_filters)
+          return unless matches_path
+          return file_info if class_filters.empty?
+
+          selected_classes = matching_classes(file_info, class_filters)
+          return if selected_classes.empty?
+
+          file_info.with(class_infos: selected_classes)
+        end
+
+        def matching_classes(file_info, class_filters)
+          file_info.class_infos.select do |class_info|
+            Common::PatternMatching.matches_all_patterns?(
+              file_info.path, class_filters, class_name: class_info.name
+            )
+          end
+        end
+
+        def partitioned_filters
+          filters.partition { |filter| filter.target != :classname }
+        end
+
+        def immutable_project_locator(locator)
+          return if locator.nil?
+
+          locator = locator.to_path if locator.respond_to?(:to_path)
+          unless locator.is_a?(String) && !locator.empty?
+            raise ArgumentError, 'project_locator must be a non-empty path or nil'
+          end
+
+          locator.dup.freeze
+        end
+
+        def immutable_filters(values)
+          filters = Array(values).dup
+          unless filters.all?(Common::Filter)
+            raise ArgumentError, 'filters must contain only Filter values'
+          end
+
+          filters.freeze
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/fluentapi/zone_condition.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative '../../common/fluentapi/checkable'
+require_relative '../assertion/metric_zone'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # Executable guard that rejects files in one architectural distance zone.
+      class ZoneCondition
+        include Common::FluentApi::Checkable
+
+        attr_reader :scope, :zone
+
+        def initialize(scope:, zone:)
+          raise ArgumentError, 'scope must be a MetricsBuilder' unless scope.is_a?(MetricsBuilder)
+          unless Assertion::MetricZoneViolation::ZONES.include?(zone)
+            raise ArgumentError, "unknown architectural zone: #{zone.inspect}"
+          end
+
+          @scope = scope
+          @zone = zone
+          freeze
+        end
+
+        private
+
+        def perform_check(options)
+          distance_infos = scope.__send__(:distance_subjects, options:)
+          empty_test = empty_test_violation(
+            distance_infos, filters: scope.filters, negated: false, options:
+          )
+          return empty_test if empty_test
+
+          Assertion.gather_metric_zone_violations(distance_infos, zone)
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/reporting/metrics_export_options.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Metrics
+    # Self-contained metrics report rendering and export.
+    module Reporting
+      # Immutable options for one metrics HTML report.
+      MetricsExportOptions = Data.define(
+        :output_path, :title, :include_timestamp, :custom_css
+      ) do
+        def self.resolve(value)
+          return new if value.nil?
+          return value if value.is_a?(self)
+
+          raise ArgumentError, 'options must be a MetricsExportOptions value or nil'
+        end
+
+        def initialize(
+          output_path: nil,
+          title: 'ArchUnitRuby Metrics Report',
+          include_timestamp: true,
+          custom_css: nil
+        )
+          output_path = optional_path(output_path)
+          title = immutable_string(title, :title)
+          unless [true, false].include?(include_timestamp)
+            raise ArgumentError, 'include_timestamp must be true or false'
+          end
+
+          custom_css = optional_string(custom_css, :custom_css)
+          super
+        end
+
+        private
+
+        def optional_path(value)
+          return if value.nil?
+
+          value = value.to_path if value.respond_to?(:to_path)
+          immutable_string(value, :output_path)
+        end
+
+        def optional_string(value, attribute)
+          return if value.nil?
+
+          immutable_string(value, attribute)
+        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
+      end
+    end
+  end
+end