archunit 0.0.1

data/lib/archunit/metrics/extraction/distance_info.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'metric_info'
+
+module ArchUnit
+  module Metrics
+    module Extraction
+      # One source file enriched with project-level dependency coupling.
+      DistanceInfo = Data.define(
+        :file_info, :afferent_coupling, :efferent_coupling, :project_file_count
+      ) do
+        include ValueValidation
+
+        def initialize(
+          file_info:, afferent_coupling:, efferent_coupling:, project_file_count:
+        )
+          raise ArgumentError, 'file_info must be a FileInfo value' unless file_info.is_a?(FileInfo)
+
+          project_file_count = positive_integer(project_file_count, :project_file_count)
+          afferent_coupling = coupling_value(
+            afferent_coupling, :afferent_coupling, project_file_count
+          )
+          efferent_coupling = coupling_value(
+            efferent_coupling, :efferent_coupling, project_file_count
+          )
+          super
+        end
+
+        def identifier
+          file_info.identifier
+        end
+
+        def path
+          file_info.path
+        end
+
+        def type_count
+          file_info.type_count
+        end
+
+        def abstract_type_count
+          file_info.abstract_type_count
+        end
+
+        def lines_of_code
+          file_info.lines_of_code
+        end
+
+        private
+
+        def coupling_value(value, attribute, file_count)
+          value = non_negative_integer(value, attribute)
+          return value if value < file_count
+
+          raise ArgumentError, "#{attribute} cannot exceed the other project files"
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/extraction/extract_distance_info.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative '../../extraction/extract_graph'
+require_relative 'distance_info'
+require_relative 'extract_project_info'
+
+module ArchUnit
+  module Metrics
+    # Ruby-specific extraction enriched with dependency coupling.
+    module Extraction
+      module_function
+
+      # Enriches static file facts with distinct internal incoming/outgoing dependencies.
+      def extract_distance_infos(project_locator = nil, options: nil)
+        project = extract_project_info(project_locator)
+        graph = ArchUnit::Extraction.extract_graph(project.project_root, options:)
+        outgoing, incoming = coupling_indexes(graph, project.files.map(&:path))
+        build_distance_infos(project, outgoing, incoming)
+      end
+
+      def build_distance_infos(project, outgoing, incoming)
+        project.files.map do |file_info|
+          DistanceInfo.new(
+            file_info:,
+            afferent_coupling: incoming.fetch(file_info.path, []).length,
+            efferent_coupling: outgoing.fetch(file_info.path, []).length,
+            project_file_count: project.files.length
+          )
+        end.freeze
+      end
+      private_class_method :build_distance_infos
+
+      # rubocop:disable Metrics/AbcSize -- Both directional indexes are built in one graph pass.
+      def coupling_indexes(graph, file_paths)
+        outgoing = Hash.new { |hash, key| hash[key] = [] }
+        incoming = Hash.new { |hash, key| hash[key] = [] }
+        graph.each do |edge|
+          next if edge.external || edge.source == edge.target
+          next unless file_paths.include?(edge.source) && file_paths.include?(edge.target)
+
+          outgoing[edge.source] |= [edge.target]
+          incoming[edge.target] |= [edge.source]
+        end
+        [outgoing, incoming]
+      end
+      # rubocop:enable Metrics/AbcSize
+      private_class_method :coupling_indexes
+    end
+  end
+end

data/lib/archunit/metrics/extraction/extract_project_info.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'prism'
+require_relative '../../error/technical_error'
+require_relative '../../extraction/enumerate_source_files'
+require_relative '../../extraction/locate_project'
+require_relative 'metric_info'
+require_relative 'source_metrics_visitor'
+
+module ArchUnit
+  module Metrics
+    # Ruby source extraction for numeric code metrics.
+    module Extraction
+      module_function
+
+      def extract_project_info(project_locator = nil, exclude_patterns: nil)
+        root = Pathname.new(ArchUnit::Extraction.locate_project(project_locator))
+        files = ArchUnit::Extraction.enumerate_source_files(root, exclude_patterns:).map do |path|
+          extract_file_info(root.join(path), relative_path: path)
+        end
+        ProjectInfo.new(project_root: root.to_s, files:)
+      end
+
+      def extract_file_info(source_file, relative_path: nil)
+        path = source_path(source_file)
+        identifier = (relative_path || path.basename.to_s).to_s.tr('\\', '/')
+        source = path.read
+        build_file_info(identifier, source)
+      rescue SystemCallError => e
+        raise TechnicalError, "could not extract Ruby source metrics: #{e.message}"
+      end
+
+      def build_file_info(identifier, source)
+        parse_result = Prism.parse(source)
+        visitor = SourceMetricsVisitor.new(identifier)
+        visitor.visit(parse_result.value) if parse_result.success?
+        FileInfo.new(
+          path: identifier, lines_of_code: lines_of_code(source), **visitor_counts(visitor)
+        )
+      end
+      private_class_method :build_file_info
+
+      def visitor_counts(visitor)
+        {
+          statement_count: visitor.statement_count,
+          import_count: visitor.import_count,
+          class_count: visitor.class_count,
+          function_count: visitor.function_count,
+          class_infos: visitor.class_infos,
+          type_count: visitor.type_count,
+          abstract_type_count: visitor.abstract_type_count
+        }
+      end
+      private_class_method :visitor_counts
+
+      # rubocop:disable Metrics/MethodLength -- The state tracks Ruby's =begin/=end comments.
+      def lines_of_code(source)
+        in_block_comment = false
+        source.each_line.count do |line|
+          stripped = line.strip
+          if stripped == '=begin'
+            in_block_comment = true
+            false
+          elsif stripped == '=end' && in_block_comment
+            in_block_comment = false
+            false
+          else
+            !in_block_comment && !stripped.empty? && !stripped.start_with?('#')
+          end
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+      private_class_method :lines_of_code
+
+      def source_path(value)
+        value = value.to_path if value.respond_to?(:to_path)
+        unless value.is_a?(String) && !value.empty?
+          raise ArgumentError, 'source_file must be a non-empty path'
+        end
+
+        path = Pathname.new(value).expand_path
+        raise ArgumentError, 'source_file must be an existing file' unless path.file?
+
+        path
+      end
+      private_class_method :source_path
+    end
+  end
+end

data/lib/archunit/metrics/extraction/metric_info.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Metrics
+    # Immutable Ruby source facts used by metric calculations.
+    module Extraction
+      # Shared constructor validation for the immutable extraction values.
+      module ValueValidation
+        private
+
+        def immutable_string(value, attribute, normalize_path: false)
+          valid = value.is_a?(String) && !value.empty?
+          raise ArgumentError, "#{attribute} must be a non-empty String" unless valid
+
+          value = value.tr('\\', '/') if normalize_path
+          value.dup.freeze
+        end
+
+        def immutable_names(values, attribute)
+          names = Array(values).map do |value|
+            immutable_string(value, attribute)
+          end
+          names.uniq.sort.freeze
+        end
+
+        def immutable_values(values, type, attribute)
+          result = Array(values).dup
+          unless result.all?(type)
+            type_name = type.name.split('::').last
+            raise ArgumentError, "#{attribute} must contain only #{type_name} values"
+          end
+
+          result.freeze
+        end
+
+        def non_negative_integer(value, attribute)
+          return value if value.is_a?(Integer) && value >= 0
+
+          raise ArgumentError, "#{attribute} must be a non-negative Integer"
+        end
+
+        def positive_integer(value, attribute)
+          return value if value.is_a?(Integer) && value.positive?
+
+          raise ArgumentError, "#{attribute} must be a positive Integer"
+        end
+      end
+      private_constant :ValueValidation
+
+      # One method and the instance fields it reads or writes.
+      MethodInfo = Data.define(:name, :accessed_fields) do
+        include ValueValidation
+
+        def initialize(name:, accessed_fields: [])
+          name = immutable_string(name, :name)
+          accessed_fields = immutable_names(accessed_fields, :accessed_fields)
+          super
+        end
+      end
+
+      # One instance field and the methods that read or write it.
+      FieldInfo = Data.define(:name, :accessed_by) do
+        include ValueValidation
+
+        def initialize(name:, accessed_by: [])
+          name = immutable_string(name, :name)
+          accessed_by = immutable_names(accessed_by, :accessed_by)
+          super
+        end
+      end
+
+      # Static information about one Ruby class declaration.
+      # rubocop:disable Lint/DataDefineOverride -- `methods` is the established metric vocabulary.
+      ClassInfo = Data.define(:name, :file_path, :methods, :fields) do
+        include ValueValidation
+
+        def initialize(name:, file_path:, methods: [], fields: [])
+          name = immutable_string(name, :name)
+          file_path = immutable_string(file_path, :file_path, normalize_path: true)
+          methods = immutable_values(methods, MethodInfo, :methods)
+          fields = immutable_values(fields, FieldInfo, :fields)
+          super
+        end
+
+        def identifier
+          "#{file_path}:#{name}"
+        end
+      end
+      # rubocop:enable Lint/DataDefineOverride
+
+      # Static counts and class declarations extracted from one Ruby source file.
+      FileInfo = Data.define(
+        :path,
+        :lines_of_code,
+        :statement_count,
+        :import_count,
+        :class_count,
+        :function_count,
+        :class_infos,
+        :type_count,
+        :abstract_type_count
+      ) do
+        include ValueValidation
+
+        # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists -- Independent count facts.
+        def initialize(
+          path:,
+          lines_of_code:,
+          statement_count:,
+          import_count:,
+          class_count:,
+          function_count:,
+          class_infos: [],
+          type_count: nil,
+          abstract_type_count: 0
+        )
+          path = immutable_string(path, :path, normalize_path: true)
+          lines_of_code = non_negative_integer(lines_of_code, :lines_of_code)
+          statement_count = non_negative_integer(statement_count, :statement_count)
+          import_count = non_negative_integer(import_count, :import_count)
+          class_count = non_negative_integer(class_count, :class_count)
+          function_count = non_negative_integer(function_count, :function_count)
+          class_infos = immutable_values(class_infos, ClassInfo, :class_infos)
+          type_count = non_negative_integer(type_count || class_count, :type_count)
+          abstract_type_count = non_negative_integer(
+            abstract_type_count, :abstract_type_count
+          )
+          if abstract_type_count > type_count
+            raise ArgumentError, 'abstract_type_count cannot exceed type_count'
+          end
+
+          super
+        end
+        # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
+
+        def identifier
+          path
+        end
+      end
+
+      # Complete immutable metric input for one located Ruby project.
+      ProjectInfo = Data.define(:project_root, :files) do
+        include ValueValidation
+
+        def initialize(project_root:, files: [])
+          project_root = immutable_string(
+            project_root, :project_root, normalize_path: true
+          )
+          files = immutable_values(files, FileInfo, :files)
+          super
+        end
+
+        def classes
+          files.flat_map(&:class_infos).freeze
+        end
+      end
+    end
+  end
+end

data/lib/archunit/metrics/extraction/source_metrics_visitor.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require 'prism'
+require_relative 'metric_info'
+
+module ArchUnit
+  module Metrics
+    module Extraction
+      # Collects Ruby-specific count and class-cohesion facts from a Prism tree.
+      # rubocop:disable Metrics/ClassLength -- One visitor owns the state of a single AST walk.
+      class SourceMetricsVisitor < Prism::Visitor
+        IMPORT_METHODS = %i[autoload load require require_relative].freeze
+        ATTRIBUTE_METHODS = %i[attr_accessor attr_reader attr_writer].freeze
+        INSTANCE_VARIABLE_NODES = %i[
+          visit_instance_variable_and_write_node
+          visit_instance_variable_operator_write_node
+          visit_instance_variable_or_write_node
+          visit_instance_variable_read_node
+          visit_instance_variable_target_node
+          visit_instance_variable_write_node
+        ].freeze
+
+        attr_reader :class_infos, :statement_count, :import_count, :class_count, :function_count,
+                    :type_count, :abstract_type_count
+
+        def initialize(file_path)
+          super()
+          @file_path = file_path
+          @class_infos = []
+          reset_context
+          reset_counts
+        end
+
+        def reset_context
+          @class_stack = []
+          @method_stack = []
+          @namespace_stack = []
+          @singleton_class_depth = 0
+        end
+        private :reset_context
+
+        def reset_counts
+          @statement_count = 0
+          @import_count = 0
+          @class_count = 0
+          @function_count = 0
+          @type_count = 0
+          @abstract_type_count = 0
+        end
+        private :reset_counts
+
+        def visit_statements_node(node)
+          @statement_count += node.body.length
+          super
+        end
+
+        def visit_call_node(node)
+          @import_count += 1 if import_call?(node)
+          record_attribute_methods(node)
+          super
+        end
+
+        def visit_class_node(node)
+          @class_count += 1
+          @type_count += 1
+          @abstract_type_count += 1 if abstract_class?(node)
+          with_class(qualified_name(node.constant_path)) { super }
+        end
+
+        def visit_module_node(node)
+          if module_type?(node)
+            @type_count += 1
+            @abstract_type_count += 1
+          end
+          with_namespace(qualified_name(node.constant_path)) { super }
+        end
+
+        def visit_singleton_class_node(node)
+          @singleton_class_depth += 1
+          super
+        ensure
+          @singleton_class_depth -= 1
+        end
+
+        # rubocop:disable Metrics/MethodLength -- The ensure keeps nested visitor state balanced.
+        def visit_def_node(node)
+          active_class = active_class_accumulator
+          unless active_class
+            @function_count += 1 if current_namespace.nil?
+            return super
+          end
+
+          method_name = qualified_method_name(node)
+          method = active_class[:methods][method_name] ||= Set.new
+          @method_stack << [active_class, method]
+          super
+        ensure
+          @method_stack.pop if active_class
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        INSTANCE_VARIABLE_NODES.each do |visitor_method|
+          define_method(visitor_method) do |node|
+            record_field_access(node.name)
+            super(node)
+          end
+        end
+
+        private
+
+        def with_class(name)
+          accumulator = { name:, methods: Hash.new { |hash, key| hash[key] = Set.new } }
+          @class_stack << [name, accumulator]
+          @namespace_stack << name
+          yield
+          @class_infos << build_class_info(accumulator)
+        ensure
+          @namespace_stack.pop
+          @class_stack.pop
+        end
+
+        def with_namespace(name)
+          @namespace_stack << name
+          yield
+        ensure
+          @namespace_stack.pop
+        end
+
+        def current_namespace
+          @namespace_stack.last
+        end
+
+        def qualified_method_name(node)
+          return "self.#{node.name}" if node.receiver || @singleton_class_depth.positive?
+
+          node.name.to_s
+        end
+
+        def active_class_accumulator
+          namespace, accumulator = @class_stack.last
+          accumulator if namespace == current_namespace
+        end
+
+        def qualified_name(constant_path)
+          name = if constant_path.respond_to?(:full_name)
+                   constant_path.full_name
+                 else
+                   constant_path.location.slice
+                 end
+          name = name.delete_prefix('::')
+          return name if name.include?('::') || current_namespace.nil?
+
+          "#{current_namespace}::#{name}"
+        end
+
+        def import_call?(node)
+          return false unless IMPORT_METHODS.include?(node.name)
+          return false unless supported_import_receiver?(node)
+
+          arguments = node.arguments&.arguments || []
+          expected_count = node.name == :autoload ? 2 : 1
+          arguments.length == expected_count
+        end
+
+        def supported_import_receiver?(node)
+          return true if node.receiver.nil?
+          return constant_receiver?(node.receiver) if node.name == :autoload
+
+          node.receiver.respond_to?(:full_name) &&
+            node.receiver.full_name.delete_prefix('::') == 'Kernel'
+        end
+
+        def constant_receiver?(receiver)
+          receiver.is_a?(Prism::ConstantReadNode) || receiver.is_a?(Prism::ConstantPathNode)
+        end
+
+        def abstract_class?(node)
+          direct_statements(node).any? { |statement| abstract_method?(statement) }
+        end
+
+        def module_type?(node)
+          direct_statements(node).any? do |statement|
+            instance_method?(statement) || attribute_declaration?(statement)
+          end
+        end
+
+        def direct_statements(node)
+          body = node.body
+          body.is_a?(Prism::StatementsNode) ? body.body : []
+        end
+
+        def instance_method?(node)
+          node.is_a?(Prism::DefNode) && node.receiver.nil?
+        end
+
+        def attribute_declaration?(node)
+          node.is_a?(Prism::CallNode) && node.receiver.nil? &&
+            ATTRIBUTE_METHODS.include?(node.name)
+        end
+
+        def abstract_method?(node)
+          return false unless instance_method?(node)
+
+          body = node.body
+          statements = body.is_a?(Prism::StatementsNode) ? body.body : []
+          statements.one? && raises_not_implemented?(statements.first)
+        end
+
+        def raises_not_implemented?(node)
+          return false unless node.is_a?(Prism::CallNode)
+          return false unless %i[fail raise].include?(node.name) && node.receiver.nil?
+
+          error = node.arguments&.arguments&.first
+          error.respond_to?(:full_name) &&
+            error.full_name.delete_prefix('::') == 'NotImplementedError'
+        end
+
+        def record_attribute_methods(node)
+          accumulator = active_class_accumulator
+          return unless accumulator && @method_stack.empty?
+          return unless ATTRIBUTE_METHODS.include?(node.name)
+
+          attribute_names(node).each do |field_name|
+            add_attribute_reader(accumulator, field_name) unless node.name == :attr_writer
+            add_attribute_writer(accumulator, field_name) unless node.name == :attr_reader
+          end
+        end
+
+        def attribute_names(node)
+          (node.arguments&.arguments || []).filter_map do |argument|
+            supported = argument.is_a?(Prism::SymbolNode) ||
+                        argument.is_a?(Prism::StringNode)
+            argument.unescaped.to_s if supported
+          end
+        end
+
+        def add_attribute_reader(accumulator, field_name)
+          accumulator[:methods][field_name] << field_name
+        end
+
+        def add_attribute_writer(accumulator, field_name)
+          accumulator[:methods]["#{field_name}="] << field_name
+        end
+
+        def record_field_access(variable_name)
+          accumulator, method = @method_stack.last
+          return if accumulator.nil? || !accumulator.equal?(active_class_accumulator)
+
+          method << variable_name.to_s.delete_prefix('@')
+        end
+
+        def build_class_info(accumulator)
+          methods = build_method_infos(accumulator)
+          fields = build_field_infos(methods)
+          ClassInfo.new(name: accumulator[:name], file_path: @file_path, methods:, fields:)
+        end
+
+        def build_method_infos(accumulator)
+          accumulator[:methods].sort.map do |name, fields|
+            MethodInfo.new(name:, accessed_fields: fields.to_a)
+          end
+        end
+
+        def build_field_infos(methods)
+          field_accesses = Hash.new { |hash, key| hash[key] = [] }
+          methods.each do |method|
+            method.accessed_fields.each { |field| field_accesses[field] << method.name }
+          end
+          field_accesses.sort.map do |name, method_names|
+            FieldInfo.new(name:, accessed_by: method_names)
+          end
+        end
+      end
+      # rubocop:enable Metrics/ClassLength
+      private_constant :SourceMetricsVisitor
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative '../calculation/count'
+require_relative 'metric_report_builder'
+require_relative 'metric_selection'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # Fluent count-metric names for one immutable metrics scope.
+      class CountMetricsBuilder
+        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::Count::CLASS_METRICS.each_key do |name|
+          define_method(name) do
+            MetricSelection.new(scope:, metric: Calculation::Count.public_send(name))
+          end
+        end
+
+        Calculation::Count::FILE_METRICS.each_key do |name|
+          define_method(name) do
+            MetricSelection.new(scope:, metric: Calculation::Count.public_send(name))
+          end
+        end
+
+        private
+
+        def report_metrics
+          class_metrics = Calculation::Count::CLASS_METRICS.each_key.map do |name|
+            Calculation::Count.public_send(name)
+          end
+          file_metrics = Calculation::Count::FILE_METRICS.each_key.map do |name|
+            Calculation::Count.public_send(name)
+          end
+          class_metrics + file_metrics
+        end
+      end
+    end
+  end
+end