archunit 0.0.1 → 1.0.0

data/lib/archunit/extraction/resolve_load_paths.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative '../error/user_error'
+require_relative 'discover_gemspec_load_paths'
+
+module ArchUnit
+  module Extraction
+    # Builds the deterministic feature search path used for static Ruby import resolution.
+    module LoadPaths
+      module_function
+
+      def resolve(project_root, explicit_paths: [], source_files: nil)
+        root = canonical_root(project_root)
+        defaults = [root.join('lib'), root].select(&:directory?)
+        explicit = resolve_explicit_paths(root, explicit_paths)
+        discovered = GemspecLoadPaths.resolve(root, source_files:)
+
+        deduplicate(defaults + explicit + discovered)
+      end
+
+      def canonical_root(value)
+        path = value.respond_to?(:to_path) ? value.to_path : value
+        unless path.is_a?(String) && !path.empty?
+          raise UserError, 'project_root must be a non-empty path'
+        end
+
+        root = Pathname.new(path).expand_path
+        raise UserError, 'project_root must be an existing directory' unless root.directory?
+
+        root.realpath
+      end
+      private_class_method :canonical_root
+
+      def resolve_explicit_paths(root, paths)
+        validate_explicit_paths(paths)
+        paths.map { |value| resolve_explicit_path(root, value) }
+      end
+      private_class_method :resolve_explicit_paths
+
+      def resolve_explicit_path(root, value)
+        candidate = Pathname.new(value.tr('\\', '/'))
+        candidate = root.join(candidate) unless candidate.absolute?
+        candidate = candidate.expand_path
+        validate_explicit_path(candidate, root, value)
+        candidate.realpath
+      end
+      private_class_method :resolve_explicit_path
+
+      def validate_explicit_path(candidate, root, value)
+        unless candidate.directory?
+          raise UserError, "load path must be an existing directory: #{value}"
+        end
+
+        canonical = candidate.realpath
+        return if within_project?(canonical, root)
+
+        raise UserError, "load path must stay inside the project root: #{value}"
+      end
+      private_class_method :validate_explicit_path
+
+      def validate_explicit_paths(paths)
+        valid = paths.is_a?(Array) && paths.all? do |path|
+          path.is_a?(String) && !path.empty?
+        end
+        return if valid
+
+        raise UserError, 'load_paths must be an Array of non-empty paths'
+      end
+      private_class_method :validate_explicit_paths
+
+      def within_project?(path, root)
+        path.relative_path_from(root).each_filename.first != '..'
+      rescue ArgumentError
+        false
+      end
+      private_class_method :within_project?
+
+      def deduplicate(paths)
+        paths.each_with_object([]) do |path, result|
+          value = normalized(path).freeze
+          result << value unless result.include?(value)
+        end.freeze
+      end
+      private_class_method :deduplicate
+
+      def normalized(path)
+        path.to_s.tr('\\', '/')
+      end
+      private_class_method :normalized
+    end
+  end
+end

data/lib/archunit/extraction/resolved_import.rb

@@ -4,11 +4,14 @@ require_relative '../common/extraction/import_kind'
 
 module ArchUnit
   module Extraction
-    ResolvedImport = Data.define(:module_name, :import_kind, :line_number, :resolved_path) do
-      def initialize(module_name:, import_kind:, line_number:, resolved_path: nil)
+    ResolvedImport = Data.define(:module_name, :import_kind, :line_number, :resolved_path,
+                                 :end_line) do
+      def initialize(module_name:, import_kind:, line_number:, resolved_path: nil,
+                     end_line: line_number)
         validate_module_name(module_name)
         validate_import_kind(import_kind)
         validate_line_number(line_number)
+        validate_line_number(end_line)
         validate_resolved_path(resolved_path)
 
         module_name = module_name.dup.freeze

data/lib/archunit/extraction/validate_extraction_paths.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative '../error/user_error'
+
+module ArchUnit
+  module Extraction
+    # Validates public extractor paths before the trusted internal pipeline runs.
+    module ExtractionPaths
+      module_function
+
+      def source_file(value)
+        path = extraction_path(value, 'source_file')
+        raise UserError, 'source_file must be an existing file' unless path.file?
+
+        path
+      end
+
+      def project_root(value)
+        path = extraction_path(value, 'project_root')
+        raise UserError, 'project_root must be an existing directory' unless path.directory?
+
+        path.realpath
+      end
+
+      def extraction_path(value, attribute)
+        value = value.to_path if value.respond_to?(:to_path)
+        unless value.is_a?(String) && !value.empty?
+          raise UserError, "#{attribute} must be a non-empty path"
+        end
+
+        Pathname.new(value).expand_path
+      end
+      private_class_method :extraction_path
+    end
+  end
+end

data/lib/archunit/files/extraction/extract_file_info.rb

@@ -63,16 +63,25 @@ module ArchUnit
 
       def source_path_within(root, identifier)
         path = root.join(identifier).cleanpath
-        relative = path.relative_path_from(root).to_s.tr('\\', '/')
-        if relative == '..' || relative.start_with?('../')
-          raise TechnicalError, 'source file must be inside the project root'
-        end
+        ensure_inside_root(root, path)
         raise TechnicalError, "source file does not exist: #{identifier}" unless path.file?
 
-        path
+        resolved = path.realpath
+        ensure_inside_root(root, resolved)
+        resolved
       end
       private_class_method :source_path_within
 
+      def ensure_inside_root(root, path)
+        relative = path.relative_path_from(root).to_s.tr('\\', '/')
+        return unless relative == '..' || relative.start_with?('../')
+
+        raise TechnicalError, 'source file must be inside the project root'
+      rescue ArgumentError
+        raise TechnicalError, 'source file must be inside the project root'
+      end
+      private_class_method :ensure_inside_root
+
       def directory_of(identifier)
         return '' unless identifier.include?('/')
 

data/lib/archunit/files/extraction/file_info.rb

@@ -8,7 +8,7 @@ module ArchUnit
       FileInfo = Data.define(
         :path, :name, :extension, :directory, :content, :lines_of_code
       ) do
-        # rubocop:disable Metrics/ParameterLists -- FileInfo has six required public fields.
+        # rubocop:disable-next Metrics/ParameterLists -- FileInfo has six required public fields.
         def initialize(path:, name:, extension:, directory:, content:, lines_of_code:)
           path = immutable_string(path, :path, allow_empty: false, normalize_path: true)
           name = immutable_string(name, :name, allow_empty: false)
@@ -20,7 +20,6 @@ module ArchUnit
           lines_of_code = non_negative_integer(lines_of_code)
           super
         end
-        # rubocop:enable Metrics/ParameterLists
 
         private
 

data/lib/archunit/files/fluentapi/depend_on_external_module_condition.rb

@@ -34,6 +34,8 @@ module ArchUnit
           is_negated
         end
 
+        # Adds another external module pattern using OR semantics.
+        # @return [DependOnExternalModuleCondition]
         def matching(module_name, except: nil)
           filter = Common::RegexFactory.path_matcher(module_name, except:)
           self.class.new(builder, module_filters: [*module_filters, filter])

data/lib/archunit/files/fluentapi/depend_on_external_module_condition_builder.rb

@@ -26,6 +26,8 @@ module ArchUnit
           is_negated
         end
 
+        # Selects an allowed or forbidden external module name.
+        # @return [DependOnExternalModuleCondition]
         def matching(module_name, except: nil)
           filter = Common::RegexFactory.path_matcher(module_name, except:)
           DependOnExternalModuleCondition.new(self, module_filters: [filter])

data/lib/archunit/files/fluentapi/depend_on_file_condition.rb

@@ -34,14 +34,20 @@ module ArchUnit
           is_negated
         end
 
+        # Adds another allowed or forbidden basename using OR semantics.
+        # @return [DependOnFileCondition]
         def with_name(pattern, except: nil)
           with_filter(Common::RegexFactory.filename_matcher(pattern, except:))
         end
 
+        # Adds another allowed or forbidden folder using OR semantics.
+        # @return [DependOnFileCondition]
         def in_folder(pattern, except: nil)
           with_filter(Common::RegexFactory.folder_matcher(pattern, except:))
         end
 
+        # Adds another allowed or forbidden path using OR semantics.
+        # @return [DependOnFileCondition]
         def in_path(pattern, except: nil)
           with_filter(Common::RegexFactory.path_matcher(pattern, except:))
         end

data/lib/archunit/files/fluentapi/depend_on_file_condition_builder.rb

@@ -26,14 +26,20 @@ module ArchUnit
           is_negated
         end
 
+        # Selects dependency targets by basename.
+        # @return [DependOnFileCondition]
         def with_name(pattern, except: nil)
           condition(Common::RegexFactory.filename_matcher(pattern, except:))
         end
 
+        # Selects dependency targets by containing folder.
+        # @return [DependOnFileCondition]
         def in_folder(pattern, except: nil)
           condition(Common::RegexFactory.folder_matcher(pattern, except:))
         end
 
+        # Selects dependency targets by complete path.
+        # @return [DependOnFileCondition]
         def in_path(pattern, except: nil)
           condition(Common::RegexFactory.path_matcher(pattern, except:))
         end

data/lib/archunit/files/fluentapi/file_condition_builder.rb

@@ -16,26 +16,38 @@ module ArchUnit
           freeze
         end
 
+        # Selects files by basename.
+        # @return [FileConditionBuilder]
         def with_name(pattern, except: nil)
           with_filter(Common::RegexFactory.filename_matcher(pattern, except:))
         end
 
+        # Selects files by project-relative containing folder.
+        # @return [FileConditionBuilder]
         def in_folder(pattern, except: nil)
           with_filter(Common::RegexFactory.folder_matcher(pattern, except:))
         end
 
+        # Selects files by complete project-relative path.
+        # @return [FileConditionBuilder]
         def in_path(pattern, except: nil)
           with_filter(Common::RegexFactory.path_matcher(pattern, except:))
         end
 
+        # Selects one exact project-relative file.
+        # @return [FileConditionBuilder]
         def in_file(file_path, except: nil)
           with_filter(Common::RegexFactory.exact_file_matcher(file_path, except:))
         end
 
+        # Enters the positive rule mood.
+        # @return [PositiveMatchPatternFileConditionBuilder]
         def should
           PositiveMatchPatternFileConditionBuilder.new(self)
         end
 
+        # Enters the negated rule mood.
+        # @return [NegatedMatchPatternFileConditionBuilder]
         def should_not
           NegatedMatchPatternFileConditionBuilder.new(self)
         end

data/lib/archunit/files/fluentapi/file_rule_support.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../../common/pattern_matching'
+require_relative '../../common/logging/inspection'
 require_relative '../../common/projection/project_to_nodes'
 
 module ArchUnit
@@ -12,12 +13,18 @@ module ArchUnit
 
         def selected_nodes(graph, filters)
           nodes = Common::Projection.project_to_nodes(graph)
-          return nodes if filters.empty?
+          selected = filters.empty? ? nodes : matching_nodes(nodes, filters)
+          Common::Logging::Inspection.selection(
+            'selected file', selected, &:label
+          )
+        end
 
+        def matching_nodes(nodes, filters)
           nodes.select do |node|
             Common::PatternMatching.matches_all_patterns?(node.label, filters)
           end
         end
+        private_class_method :matching_nodes
       end
     end
   end

data/lib/archunit/files/fluentapi/files.rb

@@ -11,6 +11,9 @@ module ArchUnit
     module FluentApi
       module_function
 
+      # Starts an immutable file-rule sentence.
+      # @param project_locator [String, Pathname, nil] project directory, Gemfile, or gemspec
+      # @return [FileConditionBuilder]
       def project_files(project_locator = nil)
         FileConditionBuilder.new(project_locator:)
       end
@@ -21,6 +24,9 @@ module ArchUnit
     end
   end
 
+  # Starts an immutable file-rule sentence.
+  # @param project_locator [String, Pathname, nil] project directory, Gemfile, or gemspec
+  # @return [Files::FluentApi::FileConditionBuilder]
   def self.project_files(project_locator = nil)
     Files::FluentApi.project_files(project_locator)
   end

data/lib/archunit/files/fluentapi/match_pattern_file_condition_builder.rb

@@ -31,26 +31,40 @@ module ArchUnit
           @negated
         end
 
+        # Requires selected files to match a basename pattern.
+        # @return [MatchPatternFileCondition]
         def have_name(pattern, except: nil)
           matching(Common::RegexFactory.filename_matcher(pattern, except:))
         end
 
+        # Requires selected files to match a containing-folder pattern.
+        # @return [MatchPatternFileCondition]
         def be_in_folder(pattern, except: nil)
           matching(Common::RegexFactory.folder_matcher(pattern, except:))
         end
 
+        # Requires selected files to match a complete-path pattern.
+        # @return [MatchPatternFileCondition]
         def be_in_path(pattern, except: nil)
           matching(Common::RegexFactory.path_matcher(pattern, except:))
         end
 
+        # Starts the object stage for internal file dependencies.
+        # @return [DependOnFileConditionBuilder]
         def depend_on_files
           DependOnFileConditionBuilder.new(self)
         end
 
+        # Starts the object stage for standard-library and gem imports.
+        # @return [DependOnExternalModuleConditionBuilder]
         def depend_on_external_modules
           DependOnExternalModuleConditionBuilder.new(self)
         end
 
+        # Applies a custom predicate to each selected FileInfo.
+        # @param condition [#call] predicate receiving one FileInfo
+        # @param message [String] explanation used for violations
+        # @return [CustomFileCondition]
         def adhere_to(condition, message)
           CustomFileCondition.new(self, condition:, message:)
         end

data/lib/archunit/files/fluentapi/positive_match_pattern_file_condition_builder.rb

@@ -12,6 +12,8 @@ module ArchUnit
           super(scope, negated: false)
         end
 
+        # Requires the selected internal dependency graph to be cycle-free.
+        # @return [CycleFreeFileCondition]
         def have_no_cycles
           CycleFreeFileCondition.new(self)
         end

data/lib/archunit/graph/fluentapi/graph.rb

@@ -9,6 +9,8 @@ module ArchUnit
     module FluentApi
       module_function
 
+      # Starts an immutable dependency-graph report.
+      # @return [ProjectGraphBuilder]
       def project_graph(project_locator = nil)
         ProjectGraphBuilder.new(project_locator:)
       end
@@ -19,6 +21,9 @@ module ArchUnit
     end
   end
 
+  # Starts an immutable dependency-graph report.
+  # @param project_locator [String, Pathname, nil] project directory, Gemfile, or gemspec
+  # @return [GraphReporting::FluentApi::ProjectGraphBuilder]
   def self.project_graph(project_locator = nil)
     GraphReporting::FluentApi.project_graph(project_locator)
   end

data/lib/archunit/graph/fluentapi/project_graph_builder.rb

@@ -10,6 +10,30 @@ module ArchUnit
   module GraphReporting
     module FluentApi
       # Immutable query builder for dependency graph snapshots and reports.
+      # @!method to_dot
+      #   @return [String] the current graph report as Graphviz DOT
+      # @!method to_mermaid
+      #   @return [String] the current graph report as Mermaid
+      # @!method to_d2
+      #   @return [String] the current graph report as D2
+      # @!method to_csv
+      #   @return [String] the current graph report as CSV
+      # @!method to_json
+      #   @return [String] the current graph report as JSON
+      # @!method to_html
+      #   @return [String] the current graph report as self-contained HTML
+      # @!method export_as_dot(output_path)
+      #   @return [nil] writes Graphviz DOT to output_path
+      # @!method export_as_mermaid(output_path)
+      #   @return [nil] writes Mermaid to output_path
+      # @!method export_as_d2(output_path)
+      #   @return [nil] writes D2 to output_path
+      # @!method export_as_csv(output_path)
+      #   @return [nil] writes CSV to output_path
+      # @!method export_as_json(output_path)
+      #   @return [nil] writes JSON to output_path
+      # @!method export_as_html(output_path)
+      #   @return [nil] writes self-contained HTML to output_path
       class ProjectGraphBuilder
         attr_reader :project_locator, :options, :check_options
 
@@ -20,51 +44,71 @@ module ArchUnit
           freeze
         end
 
+        # Includes standard-library and gem imports in the report.
+        # @return [ProjectGraphBuilder]
         def include_external_dependencies
           with_options(options.with(include_external_dependencies: true))
         end
 
+        # Includes the self-edges that represent dependency-free source files.
+        # @return [ProjectGraphBuilder]
         def include_self_dependencies
           with_options(options.with(include_self_dependencies: true))
         end
 
+        # Keeps matching nodes and neighbors within depth hops.
+        # @return [ProjectGraphBuilder]
         def focus_on(pattern, depth = 1, except: nil)
           filter = Common::RegexFactory.path_matcher(pattern, except:)
           with_options(options.with(focus: filter, focus_depth: depth))
         end
 
+        # Keeps nodes reachable from matching starting nodes.
+        # @return [ProjectGraphBuilder]
         def reachable_from(pattern, except: nil)
           filter = Common::RegexFactory.path_matcher(pattern, except:)
           with_options(options.with(reachable_from: filter))
         end
 
+        # Keeps matching nodes and everything that depends on them.
+        # @return [ProjectGraphBuilder]
         def dependents_of(pattern, except: nil)
           filter = Common::RegexFactory.path_matcher(pattern, except:)
           with_options(options.with(dependents_of: filter))
         end
 
+        # Groups file nodes by the requested project-relative folder depth.
+        # @return [ProjectGraphBuilder]
         def collapse_to_folder_depth(depth)
           with_options(options.with(collapse: Projection::FolderDepthCollapse.new(depth:)))
         end
 
+        # Groups node names through a regular-expression replacement.
+        # @return [ProjectGraphBuilder]
         def collapse_by_pattern(pattern, replacement = '\\1')
           collapse = Projection::PatternCollapse.from(pattern, replacement)
           with_options(options.with(collapse:))
         end
 
+        # Sets the report title.
+        # @return [ProjectGraphBuilder]
         def titled(title)
           with_options(options.with(title:))
         end
 
+        # Attaches extraction-related CheckOptions to this report.
+        # @return [ProjectGraphBuilder]
         def with_check_options(value)
           self.class.new(project_locator:, options:, check_options: value)
         end
 
+        # @return [GraphReportSnapshot] the immutable queried graph
         def snapshot
           graph = ArchUnit::Extraction.extract_graph(project_locator, options: check_options)
           Projection::SnapshotFactory.create(graph, options)
         end
 
+        # @return [GraphReportSummary] counts for the current snapshot
         def summary
           snapshot.summary
         end

data/lib/archunit/graph/projection/aggregate_edges.rb

@@ -12,7 +12,7 @@ module ArchUnit
 
         def aggregate(edges, collapse:, include_self_dependencies:)
           groups = Hash.new do |hash, key|
-            hash[key] = { count: 0, external: false, import_kinds: [] }
+            hash[key] = { count: 0, external: false, import_kinds: [], evidence: [] }
           end
 
           edges.each do |edge|
@@ -30,6 +30,7 @@ module ArchUnit
           group[:count] += 1
           group[:external] ||= edge.external
           group[:import_kinds] |= edge.import_kinds
+          group[:evidence] |= edge.evidence
         end
         private_class_method :accumulate
 
@@ -37,7 +38,8 @@ module ArchUnit
           groups.sort_by { |(source, target), _group| [source, target] }.map do |key, group|
             GraphReportEdge.new(
               source: key.first, target: key.last, count: group[:count],
-              external: group[:external], import_kinds: group[:import_kinds]
+              external: group[:external], import_kinds: group[:import_kinds],
+              evidence: group[:evidence]
             )
           end.freeze
         end

data/lib/archunit/graph/projection/graph_query_options.rb

@@ -21,7 +21,7 @@ module ArchUnit
         end
 
         # The options bag deliberately mirrors the eight independent fluent modifiers.
-        # rubocop:disable Metrics/ParameterLists
+        # rubocop:disable-next Metrics/ParameterLists
         def initialize(
           include_external_dependencies: false, include_self_dependencies: false,
           focus: nil, focus_depth: 1, reachable_from: nil, dependents_of: nil,
@@ -37,7 +37,6 @@ module ArchUnit
           title = immutable_title(title)
           super
         end
-        # rubocop:enable Metrics/ParameterLists
 
         def with(**overrides)
           self.class.new(**to_h, **overrides)

data/lib/archunit/graph/projection/graph_report_edge.rb

@@ -1,18 +1,28 @@
 # frozen_string_literal: true
 
 require_relative '../../common/extraction/import_kind'
+require_relative '../../common/extraction/dependency_evidence'
 
 module ArchUnit
   module GraphReporting
     module Projection
       # Aggregated dependency evidence in a graph report snapshot.
-      GraphReportEdge = Data.define(:source, :target, :count, :external, :import_kinds) do
-        def initialize(source:, target:, count:, external:, import_kinds: [])
+      GraphReportEdge = Data.define(:source, :target, :count, :external, :import_kinds,
+                                    :evidence) do
+        # Keywords mirror this immutable report value.
+        def initialize( # rubocop:disable Metrics/ParameterLists
+          source:, target:, count:, external:, import_kinds: [], evidence: []
+        )
           source = immutable_string(source, :source)
           target = immutable_string(target, :target)
           validate_count(count)
           validate_external(external)
           import_kinds = immutable_import_kinds(import_kinds)
+          evidence = Array(evidence).uniq.freeze
+          unless evidence.all?(Common::Extraction::DependencyEvidence)
+            raise ArgumentError, 'evidence must contain DependencyEvidence values'
+          end
+
           super
         end
 

data/lib/archunit/graph/rendering/json_renderer.rb

@@ -26,10 +26,12 @@ module ArchUnit
         private_class_method :snapshot_hash
 
         def edge_hash(edge)
-          {
+          result = {
             source: edge.source, target: edge.target, count: edge.count,
             external: edge.external, import_kinds: edge.import_kinds
           }
+          result[:evidence] = edge.evidence.map(&:to_h) unless edge.evidence.empty?
+          result
         end
         private_class_method :edge_hash
       end

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

@@ -15,10 +15,14 @@ module ArchUnit
           freeze
         end
 
+        # Adds a full-path selector to this layer definition.
+        # @return [LayeredArchitecture]
         def defined_by(pattern, except: nil)
           add_filter(Common::RegexFactory.path_matcher(pattern, except:))
         end
 
+        # Adds a containing-folder selector to this layer definition.
+        # @return [LayeredArchitecture]
         def defined_by_folder(pattern, except: nil)
           add_filter(Common::RegexFactory.folder_matcher(pattern, except:))
         end

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

@@ -13,10 +13,14 @@ module ArchUnit
           freeze
         end
 
+        # Allows only the listed target layers; no targets seals the source layer.
+        # @return [LayeredArchitecture]
         def may_only_depend_on_layers(*layer_names)
           architecture.__send__(:with_allowed_dependencies, layer_name, layer_names)
         end
 
+        # Forbids dependencies on the listed target layers.
+        # @return [LayeredArchitecture]
         def may_not_depend_on_layers(*layer_names)
           if layer_names.empty?
             raise ArgumentError, 'may_not_depend_on_layers requires at least one layer name'

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

@@ -34,10 +34,14 @@ module ArchUnit
           freeze
         end
 
+        # Starts or extends the definition of a named layer.
+        # @return [LayerDefinitionBuilder]
         def layer(name)
           LayerDefinitionBuilder.new(self, validated_layer_name(name))
         end
 
+        # Selects a defined source layer for a dependency policy.
+        # @return [LayerDependencyRuleBuilder]
         def where_layer(name)
           name = validated_layer_name(name)
           ensure_defined_layer!(name)
@@ -71,6 +75,7 @@ module ArchUnit
           graph = ArchUnit::Extraction.extract_graph(project_locator, options:)
           nodes = Common::Projection.project_to_nodes(graph)
           edges = Common::Projection.project_edges(graph, Common::Projection.per_internal_edge)
+          Common::Logging::Inspection.projection(edges)
 
           empty_policy_violations(nodes, options) +
             Assertion.gather_layer_dependency_violations(