archunit 0.0.1 → 1.0.0

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

@@ -9,6 +9,8 @@ module ArchUnit
     module FluentApi
       module_function
 
+      # Starts an immutable named-layer policy.
+      # @return [LayeredArchitecture]
       def project_layers(project_locator = nil)
         LayeredArchitecture.new(project_locator:)
       end
@@ -19,6 +21,9 @@ module ArchUnit
     end
   end
 
+  # Starts an immutable named-layer policy.
+  # @param project_locator [String, Pathname, nil] project directory, Gemfile, or gemspec
+  # @return [Layers::FluentApi::LayeredArchitecture]
   def self.project_layers(project_locator = nil)
     Layers::FluentApi.project_layers(project_locator)
   end

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

@@ -30,7 +30,7 @@ module ArchUnit
       end
       private_class_method :build_distance_infos
 
-      # rubocop:disable Metrics/AbcSize -- Both directional indexes are built in one graph pass.
+      # rubocop:disable-next 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] = [] }
@@ -43,7 +43,6 @@ module ArchUnit
         end
         [outgoing, incoming]
       end
-      # rubocop:enable Metrics/AbcSize
       private_class_method :coupling_indexes
     end
   end

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

@@ -3,6 +3,7 @@
 require 'pathname'
 require 'prism'
 require_relative '../../error/technical_error'
+require_relative '../../error/source_parse_error'
 require_relative '../../extraction/enumerate_source_files'
 require_relative '../../extraction/locate_project'
 require_relative 'metric_info'
@@ -26,15 +27,15 @@ module ArchUnit
         path = source_path(source_file)
         identifier = (relative_path || path.basename.to_s).to_s.tr('\\', '/')
         source = path.read
-        build_file_info(identifier, source)
+        result = SourceParseError.validate!(Prism.parse(source, filepath: path.to_s), path:)
+        build_file_info(identifier, source, result)
       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)
+      def build_file_info(identifier, source, parse_result)
         visitor = SourceMetricsVisitor.new(identifier)
-        visitor.visit(parse_result.value) if parse_result.success?
+        visitor.visit(parse_result.value)
         FileInfo.new(
           path: identifier, lines_of_code: lines_of_code(source), **visitor_counts(visitor)
         )
@@ -54,7 +55,7 @@ module ArchUnit
       end
       private_class_method :visitor_counts
 
-      # rubocop:disable Metrics/MethodLength -- The state tracks Ruby's =begin/=end comments.
+      # rubocop:disable-next 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|
@@ -70,7 +71,6 @@ module ArchUnit
           end
         end
       end
-      # rubocop:enable Metrics/MethodLength
       private_class_method :lines_of_code
 
       def source_path(value)

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

@@ -70,7 +70,7 @@ module ArchUnit
       end
 
       # Static information about one Ruby class declaration.
-      # rubocop:disable Lint/DataDefineOverride -- `methods` is the established metric vocabulary.
+      # rubocop:disable-next Lint/DataDefineOverride -- `methods` is the established metric vocabulary.
       ClassInfo = Data.define(:name, :file_path, :methods, :fields) do
         include ValueValidation
 
@@ -86,7 +86,6 @@ module ArchUnit
           "#{file_path}:#{name}"
         end
       end
-      # rubocop:enable Lint/DataDefineOverride
 
       # Static counts and class declarations extracted from one Ruby source file.
       FileInfo = Data.define(
@@ -102,7 +101,7 @@ module ArchUnit
       ) do
         include ValueValidation
 
-        # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists -- Independent count facts.
+        # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists -- Independent count facts.
         def initialize(
           path:,
           lines_of_code:,
@@ -131,7 +130,6 @@ module ArchUnit
 
           super
         end
-        # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
 
         def identifier
           path

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

@@ -7,7 +7,7 @@ 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.
+      # rubocop:disable-next 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
@@ -82,7 +82,7 @@ module ArchUnit
           @singleton_class_depth -= 1
         end
 
-        # rubocop:disable Metrics/MethodLength -- The ensure keeps nested visitor state balanced.
+        # rubocop:disable-next Metrics/MethodLength -- The ensure keeps nested visitor state balanced.
         def visit_def_node(node)
           active_class = active_class_accumulator
           unless active_class
@@ -97,7 +97,6 @@ module ArchUnit
         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|
@@ -271,7 +270,6 @@ module ArchUnit
           end
         end
       end
-      # rubocop:enable Metrics/ClassLength
       private_constant :SourceMetricsVisitor
     end
   end

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

@@ -21,6 +21,8 @@ module ArchUnit
           super(scope:, metric:)
         end
 
+        # Creates a custom-metric rule retaining the configured description.
+        # @return [CustomMetricCondition]
         def should_satisfy(predicate)
           CustomMetricCondition.new(selection: self, predicate:)
         end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../../common/fluentapi/checkable'
+require_relative 'logged_metric'
 require_relative '../assertion/custom_metric'
 
 module ArchUnit
@@ -32,7 +33,9 @@ module ArchUnit
           )
           return empty_test if empty_test
 
-          Assertion.gather_custom_metric_violations(classes, selection.metric, predicate)
+          Assertion.gather_custom_metric_violations(
+            classes, LoggedMetric.wrap(selection.metric), predicate
+          )
         end
       end
     end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative '../../common/logging/inspection'
+
+module ArchUnit
+  module Metrics
+    module FluentApi
+      # Observes the existing calculation once, including values that pass the rule.
+      module LoggedMetric
+        def self.wrap(metric)
+          logger = Common::Logging::Inspection.logger
+          return metric unless logger&.debug?
+
+          metric.with(calculation: lambda do |subject|
+            value = metric.calculate(subject)
+            logger.log_metric(name: metric.name, value:, subject: subject.identifier)
+            value
+          end)
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../../common/fluentapi/checkable'
+require_relative 'logged_metric'
 require_relative '../assertion/metric_predicate'
 
 module ArchUnit
@@ -34,7 +35,9 @@ module ArchUnit
           )
           return empty_test if empty_test
 
-          Assertion.gather_metric_predicate_violations(subjects, selection.metric, predicate)
+          Assertion.gather_metric_predicate_violations(
+            subjects, LoggedMetric.wrap(selection.metric), predicate
+          )
         end
       end
     end

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

@@ -8,6 +8,8 @@ module ArchUnit
     module FluentApi
       # Shared HTML export terminal for one family of scoped metrics.
       module MetricReportBuilder
+        # Writes an offline HTML report for all metrics in this family.
+        # @return [nil]
         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)

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

@@ -9,6 +9,16 @@ module ArchUnit
   module Metrics
     module FluentApi
       # Lazy selection of one metric over a metrics scope.
+      # @!method should_be_below(threshold)
+      #   @return [MetricThresholdCondition]
+      # @!method should_be_above(threshold)
+      #   @return [MetricThresholdCondition]
+      # @!method should_be(threshold)
+      #   @return [MetricThresholdCondition]
+      # @!method should_be_below_or_equal(threshold)
+      #   @return [MetricThresholdCondition]
+      # @!method should_be_above_or_equal(threshold)
+      #   @return [MetricThresholdCondition]
       class MetricSelection
         THRESHOLD_METHODS = {
           should_be_below: :below,
@@ -29,8 +39,12 @@ module ArchUnit
           freeze
         end
 
-        def measure
-          scope.__send__(:subjects_for, metric.subject_type).map do |subject|
+        # Evaluates this metric for every selected subject.
+        # @param options [CheckOptions, nil] dependency-analysis options for coupling metrics
+        # @return [Array<MetricMeasurement>]
+        def measure(options = nil)
+          options = Common::FluentApi::CheckOptions.resolve(options)
+          scope.__send__(:subjects_for, metric.subject_type, options:).map do |subject|
             MetricMeasurement.new(
               subject:,
               metric_name: metric.name,
@@ -45,6 +59,8 @@ module ArchUnit
           end
         end
 
+        # Creates a rule from a custom predicate over value and subject.
+        # @return [MetricPredicateCondition]
         def should_satisfy(predicate)
           MetricPredicateCondition.new(selection: self, predicate:)
         end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../../common/fluentapi/checkable'
+require_relative 'logged_metric'
 require_relative '../assertion/metric_threshold'
 
 module ArchUnit
@@ -38,7 +39,7 @@ module ArchUnit
           return empty_test if empty_test
 
           Assertion.gather_metric_threshold_violations(
-            subjects, selection.metric, comparison, threshold
+            subjects, LoggedMetric.wrap(selection.metric), comparison, threshold
           )
         end
       end

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

@@ -9,12 +9,17 @@ module ArchUnit
     module FluentApi
       module_function
 
+      # Starts an immutable source-metrics scope.
+      # @return [MetricsBuilder]
       def metrics(project_locator = nil)
         MetricsBuilder.new(project_locator:)
       end
     end
   end
 
+  # Starts an immutable source-metrics scope.
+  # @param project_locator [String, Pathname, nil] project directory, Gemfile, or gemspec
+  # @return [Metrics::FluentApi::MetricsBuilder]
   def self.metrics(project_locator = nil)
     Metrics::FluentApi.metrics(project_locator)
   end

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

@@ -23,41 +23,56 @@ module ArchUnit
           freeze
         end
 
+        # Selects metric source files by basename.
+        # @return [MetricsBuilder]
         def with_name(pattern, except: nil)
           with_filter(Common::RegexFactory.filename_matcher(pattern, except:))
         end
 
+        # Selects metric source files by containing folder.
+        # @return [MetricsBuilder]
         def in_folder(pattern, except: nil)
           with_filter(Common::RegexFactory.folder_matcher(pattern, except:))
         end
 
+        # Selects metric source files by complete path.
+        # @return [MetricsBuilder]
         def in_path(pattern, except: nil)
           with_filter(Common::RegexFactory.path_matcher(pattern, except:))
         end
 
+        # Selects classes within the selected source files.
+        # @return [MetricsBuilder]
         def for_classes_matching(pattern, except: nil)
           with_filter(Common::RegexFactory.classname_matcher(pattern, except:))
         end
 
+        # @return [CountMetricsBuilder] count metric vocabulary
         def count
           CountMetricsBuilder.new(self)
         end
 
+        # @return [LCOMMetricsBuilder] cohesion metric vocabulary
         def lcom
           LCOMMetricsBuilder.new(self)
         end
 
+        # @return [DistanceMetricsBuilder] dependency-distance metric vocabulary
         def distance
           DistanceMetricsBuilder.new(self)
         end
 
+        # Defines a custom numeric calculation over ClassInfo.
+        # @return [CustomMetricBuilder]
         def custom_metric(name, description, calculation)
           CustomMetricBuilder.new(scope: self, name:, description:, calculation:)
         end
 
+        # @return [MetricProjectInfo] extracted files and classes in this scope
         def analyze
           project = Extraction.extract_project_info(project_locator)
           selected_files = project.files.filter_map { |file| selected_file_info(file) }
+          Common::Logging::Inspection.selection('metric file', selected_files, &:path)
           Extraction::ProjectInfo.new(project_root: project.project_root, files: selected_files)
         end
 

data/lib/archunit/slices/fluentapi/diagram_slice_condition.rb

@@ -39,6 +39,7 @@ module ArchUnit
 
           diagram = Uml::PlantUmlParser.parse(diagram_source.read)
           edges = Common::Projection.project_edges(graph, projection)
+          Common::Logging::Inspection.projection(edges)
           Assertion.gather_diagram_adherence_violations(edges, diagram, options)
         end
 

data/lib/archunit/slices/fluentapi/forbidden_slice_dependency_condition.rb

@@ -41,6 +41,7 @@ module ArchUnit
           return empty_test if empty_test
 
           edges = Common::Projection.project_edges(graph, projection)
+          Common::Logging::Inspection.projection(edges)
           Assertion.gather_forbidden_slice_dependency_violations(
             edges, source_slice, target_slice
           )

data/lib/archunit/slices/fluentapi/negative_slice_condition_builder.rb

@@ -18,6 +18,8 @@ module ArchUnit
           freeze
         end
 
+        # Forbids a directed dependency between two named slices.
+        # @return [ForbiddenSliceDependencyCondition]
         def contain_dependency(source_slice, target_slice)
           ForbiddenSliceDependencyCondition.new(scope, source_slice:, target_slice:)
         end

data/lib/archunit/slices/fluentapi/positive_slice_condition_builder.rb

@@ -24,18 +24,26 @@ module ArchUnit
           freeze
         end
 
+        # Ignores slices that are absent from the diagram and have no dependency edge.
+        # @return [PositiveSliceConditionBuilder]
         def ignoring_orphan_slices
           copy(options.with(ignore_orphan_slices: true))
         end
 
+        # Ignores dependencies to external modules during diagram comparison.
+        # @return [PositiveSliceConditionBuilder]
         def ignoring_external_slices
           copy(options.with(ignore_external_slices: true))
         end
 
+        # Requires the slice graph to match inline PlantUML.
+        # @return [DiagramSliceCondition]
         def adhere_to_diagram(text)
           DiagramSliceCondition.new(scope, DiagramSource.inline(text), options:)
         end
 
+        # Requires the slice graph to match a PlantUML file.
+        # @return [DiagramSliceCondition]
         def adhere_to_diagram_in_file(path)
           DiagramSliceCondition.new(scope, DiagramSource.file(path), options:)
         end

data/lib/archunit/slices/fluentapi/slice_scope_builder.rb

@@ -22,28 +22,40 @@ module ArchUnit
           freeze
         end
 
+        # Captures slice names with the `(**)` segment in a glob pattern.
+        # @return [SliceScopeBuilder]
         def defined_by(pattern, except: nil)
           copy(projection: Projection.slice_by_pattern(pattern, except:))
         end
 
+        # Captures slice names with the first group in a regular expression.
+        # @return [SliceScopeBuilder]
         def defined_by_regex(regexp, except: nil)
           copy(projection: Projection.slice_by_regex(regexp, except:))
         end
 
+        # Enters the negated slice-rule mood.
+        # @return [NegativeSliceConditionBuilder]
         def should_not
           NegativeSliceConditionBuilder.new(self)
         end
 
+        # Enters the positive slice-rule mood.
+        # @return [PositiveSliceConditionBuilder]
         def should
           PositiveSliceConditionBuilder.new(self)
         end
 
+        # Renders the real slice graph as PlantUML.
+        # @return [String]
         def to_plantuml(options = nil)
           graph = extract_graph(options)
           edges = Common::Projection.project_edges(graph, projection)
           Uml::PlantUmlRenderer.render(edges, components: projection.slice_labels(graph))
         end
 
+        # Writes the real slice graph as PlantUML.
+        # @return [nil]
         def export_as_plantuml(output_path, options = nil)
           graph = extract_graph(options)
           edges = Common::Projection.project_edges(graph, projection)

data/lib/archunit/slices/fluentapi/slices.rb

@@ -9,6 +9,8 @@ module ArchUnit
     module FluentApi
       module_function
 
+      # Starts an immutable slice-rule sentence.
+      # @return [SliceScopeBuilder]
       def project_slices(project_locator = nil)
         SliceScopeBuilder.new(project_locator:)
       end
@@ -19,6 +21,9 @@ module ArchUnit
     end
   end
 
+  # Starts an immutable slice-rule sentence.
+  # @param project_locator [String, Pathname, nil] project directory, Gemfile, or gemspec
+  # @return [Slices::FluentApi::SliceScopeBuilder]
   def self.project_slices(project_locator = nil)
     Slices::FluentApi.project_slices(project_locator)
   end

data/lib/archunit/testing/assert_passes.rb

@@ -10,6 +10,8 @@ module ArchUnit
   module Testing
     module_function
 
+    # Raises AssertionFailure when a rule returns violations.
+    # @return [nil]
     def assert_passes(rule, options = nil)
       result = result_for(rule, options)
       return if result.passed?
@@ -18,6 +20,8 @@ module ArchUnit
     end
   end
 
+  # Raises AssertionFailure when a rule returns violations.
+  # @return [nil]
   def self.assert_passes(rule, options = nil)
     Testing.assert_passes(rule, options)
   end

data/lib/archunit/testing/result_factory.rb

@@ -11,17 +11,29 @@ module ArchUnit
     # Shapes a violation collection into one framework-neutral test result.
     class ResultFactory
       class << self
-        def from_violations(violations, color: nil, expected_to_pass: true)
+        def from_violations(violations, color: nil, expected_to_pass: true, rationale: nil)
           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)
+          result = if violations.empty?
+                     empty_result(color, expected_to_pass)
+                   else
+                     failing_result(violations, color, expected_to_pass)
+                   end
+          explain_result(result, rationale)
         end
 
         private
 
+        def explain_result(result, rationale)
+          unless rationale.nil? || (rationale.is_a?(String) && !rationale.strip.empty?)
+            raise ArgumentError, 'rationale must be a non-empty String or nil'
+          end
+          return result unless rationale && result.failed?
+
+          TestResult.new(passed: false, message: "#{result.message}\n\nBecause: #{rationale.strip}")
+        end
+
         def passing_result(color)
           message = ColorUtils.green('No architecture violations found.', enabled: color)
           TestResult.new(passed: true, message:)

data/lib/archunit/testing/rspec_adapter.rb

@@ -13,11 +13,10 @@ module ArchUnit
       end
 
       # RSpec's matcher protocol fixes this method name.
-      # rubocop:disable Naming/PredicatePrefix
+      # rubocop:disable-next Naming/PredicatePrefix
       def does_not_match?(rule)
         matches_expectation?(rule, expected_to_pass: false)
       end
-      # rubocop:enable Naming/PredicatePrefix
 
       def failure_message
         result.message

data/lib/archunit/testing.rb

@@ -14,22 +14,26 @@ module ArchUnit
   module Testing
     module_function
 
+    # Formats structured violations for a terminal or test failure.
+    # @return [String]
     def format_violations(violations, color: nil)
       ResultFactory.from_violations(violations, color:).message
     end
 
+    # Converts a rule check into a framework-neutral TestResult.
+    # @return [TestResult]
     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)
+      ResultFactory.from_violations(violations, expected_to_pass:, rationale: rule.rationale)
     end
   end
 
+  # Formats structured violations for a terminal or test failure.
+  # @return [String]
   def self.format_violations(violations, color: nil)
     Testing.format_violations(violations, color:)
   end

data/lib/archunit/version.rb

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

data/lib/archunit.rb

@@ -2,6 +2,7 @@
 
 require_relative 'archunit/version'
 require_relative 'archunit/error/technical_error'
+require_relative 'archunit/error/source_parse_error'
 require_relative 'archunit/error/user_error'
 require_relative 'archunit/common/pattern'
 require_relative 'archunit/common/filter'
@@ -25,8 +26,11 @@ 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/resolve_load_paths'
+require_relative 'archunit/extraction/extraction_profile'
 require_relative 'archunit/extraction/resolved_import'
 require_relative 'archunit/extraction/resolve_import'
+require_relative 'archunit/extraction/import_resolver'
 require_relative 'archunit/extraction/extract_imports'
 require_relative 'archunit/extraction/extract_dependencies'
 require_relative 'archunit/extraction/extract_graph'
@@ -50,6 +54,8 @@ module ArchUnit
   Checkable = Common::FluentApi::Checkable
   ImportKind = Common::Extraction::ImportKind
   Edge = Common::Extraction::Edge
+  DependencyEvidence = Common::Extraction::DependencyEvidence
+  ParseDiagnostic = Common::Extraction::ParseDiagnostic
   Graph = Common::Extraction::Graph
   MappedEdge = Common::Projection::MappedEdge
   ProjectedEdge = Common::Projection::ProjectedEdge
@@ -104,6 +110,9 @@ module ArchUnit
   ResultFactory = Testing::ResultFactory
   AssertionFailure = Testing::AssertionFailure
 
+  # Clears every cached dependency graph in the current process.
+  # Use this after changing analyzed source files between checks.
+  # @return [nil]
   def self.clear_graph_cache
     Extraction.clear_graph_cache
   end