archunit 0.0.1

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative '../../common/fluentapi/checkable'
+require_relative '../../common/projection/edge_projections'
+require_relative '../../common/projection/project_edges'
+require_relative '../../common/regex_factory'
+require_relative '../../extraction/extract_graph'
+require_relative '../assertion/depend_on_files'
+require_relative 'file_rule_support'
+
+module ArchUnit
+  module Files
+    module FluentApi
+      # Executable internal file-dependency rule with chainable object selectors.
+      class DependOnFileCondition
+        include Common::FluentApi::Checkable
+
+        attr_reader :builder, :project_locator, :subject_filters, :object_filters, :is_negated
+
+        def initialize(builder, object_filters:)
+          unless builder.is_a?(DependOnFileConditionBuilder)
+            raise ArgumentError, 'builder must be a DependOnFileConditionBuilder'
+          end
+
+          @builder = builder
+          @project_locator = builder.project_locator
+          @subject_filters = builder.subject_filters
+          @object_filters = immutable_object_filters(object_filters)
+          @is_negated = builder.negated?
+          freeze
+        end
+
+        def negated?
+          is_negated
+        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
+
+        private
+
+        def immutable_object_filters(values)
+          filters = Array(values).dup
+          unless !filters.empty? && filters.all?(Common::Filter)
+            raise ArgumentError, 'object_filters must contain at least one Filter'
+          end
+
+          filters.freeze
+        end
+
+        def with_filter(filter)
+          self.class.new(builder, object_filters: [*object_filters, filter])
+        end
+
+        def perform_check(options)
+          graph = ArchUnit::Extraction.extract_graph(project_locator, options:)
+          nodes = FileRuleSupport.selected_nodes(graph, subject_filters)
+          empty_test = empty_test_violation(
+            nodes, filters: subject_filters, negated: is_negated, options:
+          )
+          return empty_test if empty_test
+
+          edges = Common::Projection.project_edges(graph, Common::Projection.per_internal_edge)
+          Assertion.gather_file_dependency_violations(
+            edges, subject_filters, object_filters, is_negated:
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative '../../common/regex_factory'
+require_relative 'depend_on_file_condition'
+
+module ArchUnit
+  module Files
+    module FluentApi
+      # Immutable object stage selecting internal dependency targets.
+      class DependOnFileConditionBuilder
+        attr_reader :mood, :project_locator, :subject_filters, :is_negated
+
+        def initialize(mood)
+          unless mood.is_a?(MatchPatternFileConditionBuilder)
+            raise ArgumentError, 'mood must be a file condition builder'
+          end
+
+          @mood = mood
+          @project_locator = mood.project_locator
+          @subject_filters = mood.filters
+          @is_negated = mood.negated?
+          freeze
+        end
+
+        def negated?
+          is_negated
+        end
+
+        def with_name(pattern, except: nil)
+          condition(Common::RegexFactory.filename_matcher(pattern, except:))
+        end
+
+        def in_folder(pattern, except: nil)
+          condition(Common::RegexFactory.folder_matcher(pattern, except:))
+        end
+
+        def in_path(pattern, except: nil)
+          condition(Common::RegexFactory.path_matcher(pattern, except:))
+        end
+
+        private
+
+        def condition(filter)
+          DependOnFileCondition.new(self, object_filters: [filter])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative '../../common/filter'
+require_relative '../../common/regex_factory'
+
+module ArchUnit
+  module Files
+    module FluentApi
+      # Immutable scope builder selecting the files to which a rule will apply.
+      class FileConditionBuilder
+        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 in_file(file_path, except: nil)
+          with_filter(Common::RegexFactory.exact_file_matcher(file_path, except:))
+        end
+
+        def should
+          PositiveMatchPatternFileConditionBuilder.new(self)
+        end
+
+        def should_not
+          NegatedMatchPatternFileConditionBuilder.new(self)
+        end
+
+        private
+
+        def with_filter(filter)
+          self.class.new(project_locator:, filters: [*filters, filter])
+        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/files/fluentapi/file_rule_support.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../../common/pattern_matching'
+require_relative '../../common/projection/project_to_nodes'
+
+module ArchUnit
+  module Files
+    module FluentApi
+      # Shared file selection for executable rule terminals.
+      module FileRuleSupport
+        module_function
+
+        def selected_nodes(graph, filters)
+          nodes = Common::Projection.project_to_nodes(graph)
+          return nodes if filters.empty?
+
+          nodes.select do |node|
+            Common::PatternMatching.matches_all_patterns?(node.label, filters)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'file_condition_builder'
+require_relative 'positive_match_pattern_file_condition_builder'
+require_relative 'negated_match_pattern_file_condition_builder'
+
+# Public ArchUnitRuby entry points for file rules.
+module ArchUnit
+  module Files
+    # Sentence-like entry points and builders for file architecture rules.
+    module FluentApi
+      module_function
+
+      def project_files(project_locator = nil)
+        FileConditionBuilder.new(project_locator:)
+      end
+
+      class << self
+        alias files project_files
+      end
+    end
+  end
+
+  def self.project_files(project_locator = nil)
+    Files::FluentApi.project_files(project_locator)
+  end
+
+  class << self
+    alias files project_files
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative '../../common/filter'
+require_relative '../../common/fluentapi/checkable'
+require_relative '../../extraction/extract_graph'
+require_relative '../assertion/matching_files'
+require_relative 'file_rule_support'
+
+module ArchUnit
+  module Files
+    module FluentApi
+      # Executable file name or location predicate for either mood.
+      class MatchPatternFileCondition
+        include Common::FluentApi::Checkable
+
+        attr_reader :project_locator, :filters, :check_filter, :is_negated
+
+        def initialize(mood, check_filter:)
+          validate_mood(mood)
+          validate_check_filter(check_filter)
+          @project_locator = mood.project_locator
+          @filters = mood.filters
+          @check_filter = check_filter
+          @is_negated = mood.negated?
+          freeze
+        end
+
+        def negated?
+          is_negated
+        end
+
+        private
+
+        def validate_mood(value)
+          return if value.is_a?(MatchPatternFileConditionBuilder)
+
+          raise ArgumentError, 'mood must be a file condition builder'
+        end
+
+        def validate_check_filter(value)
+          return if value.is_a?(Common::Filter)
+
+          raise ArgumentError, 'check_filter must be a Filter'
+        end
+
+        def perform_check(options)
+          graph = ArchUnit::Extraction.extract_graph(project_locator, options:)
+          nodes = FileRuleSupport.selected_nodes(graph, filters)
+          empty_test = empty_test_violation(
+            nodes, filters:, negated: is_negated, options:
+          )
+          return empty_test if empty_test
+
+          Assertion.gather_matching_file_violations(nodes, check_filter, is_negated:)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative '../../common/regex_factory'
+require_relative 'custom_file_condition'
+require_relative 'depend_on_external_module_condition_builder'
+require_relative 'depend_on_file_condition_builder'
+require_relative 'match_pattern_file_condition'
+
+module ArchUnit
+  module Files
+    module FluentApi
+      # Shared immutable state for positive and negated file predicate builders.
+      class MatchPatternFileConditionBuilder
+        attr_reader :project_locator, :filters
+
+        def initialize(scope, negated:)
+          unless scope.is_a?(FileConditionBuilder)
+            raise ArgumentError, 'scope must be a FileConditionBuilder'
+          end
+          unless [true, false].include?(negated)
+            raise ArgumentError, 'negated must be true or false'
+          end
+
+          @project_locator = scope.project_locator
+          @filters = scope.filters
+          @negated = negated
+          freeze
+        end
+
+        def negated?
+          @negated
+        end
+
+        def have_name(pattern, except: nil)
+          matching(Common::RegexFactory.filename_matcher(pattern, except:))
+        end
+
+        def be_in_folder(pattern, except: nil)
+          matching(Common::RegexFactory.folder_matcher(pattern, except:))
+        end
+
+        def be_in_path(pattern, except: nil)
+          matching(Common::RegexFactory.path_matcher(pattern, except:))
+        end
+
+        def depend_on_files
+          DependOnFileConditionBuilder.new(self)
+        end
+
+        def depend_on_external_modules
+          DependOnExternalModuleConditionBuilder.new(self)
+        end
+
+        def adhere_to(condition, message)
+          CustomFileCondition.new(self, condition:, message:)
+        end
+
+        private
+
+        def matching(check_filter)
+          MatchPatternFileCondition.new(self, check_filter:)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'match_pattern_file_condition_builder'
+
+module ArchUnit
+  module Files
+    module FluentApi
+      # The `should_not` mood for file predicates.
+      class NegatedMatchPatternFileConditionBuilder < MatchPatternFileConditionBuilder
+        def initialize(scope)
+          super(scope, negated: true)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'match_pattern_file_condition_builder'
+require_relative 'cycle_free_file_condition'
+
+module ArchUnit
+  module Files
+    module FluentApi
+      # The `should` mood for file predicates.
+      class PositiveMatchPatternFileConditionBuilder < MatchPatternFileConditionBuilder
+        def initialize(scope)
+          super(scope, negated: false)
+        end
+
+        def have_no_cycles
+          CycleFreeFileCondition.new(self)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'project_graph_builder'
+
+# Public ArchUnitRuby entry points for dependency graph reports.
+module ArchUnit
+  module GraphReporting
+    # Sentence-like entry points and builders for graph reporting.
+    module FluentApi
+      module_function
+
+      def project_graph(project_locator = nil)
+        ProjectGraphBuilder.new(project_locator:)
+      end
+
+      class << self
+        alias dependency_graph project_graph
+      end
+    end
+  end
+
+  def self.project_graph(project_locator = nil)
+    GraphReporting::FluentApi.project_graph(project_locator)
+  end
+
+  class << self
+    alias dependency_graph project_graph
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative '../../common/fluentapi/check_options'
+require_relative '../../common/regex_factory'
+require_relative '../../extraction/extract_graph'
+require_relative '../projection/create_snapshot'
+require_relative '../rendering/graph_renderer'
+
+module ArchUnit
+  module GraphReporting
+    module FluentApi
+      # Immutable query builder for dependency graph snapshots and reports.
+      class ProjectGraphBuilder
+        attr_reader :project_locator, :options, :check_options
+
+        def initialize(project_locator: nil, options: nil, check_options: nil)
+          @project_locator = immutable_project_locator(project_locator)
+          @options = Projection::GraphQueryOptions.resolve(options)
+          @check_options = immutable_check_options(check_options)
+          freeze
+        end
+
+        def include_external_dependencies
+          with_options(options.with(include_external_dependencies: true))
+        end
+
+        def include_self_dependencies
+          with_options(options.with(include_self_dependencies: true))
+        end
+
+        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
+
+        def reachable_from(pattern, except: nil)
+          filter = Common::RegexFactory.path_matcher(pattern, except:)
+          with_options(options.with(reachable_from: filter))
+        end
+
+        def dependents_of(pattern, except: nil)
+          filter = Common::RegexFactory.path_matcher(pattern, except:)
+          with_options(options.with(dependents_of: filter))
+        end
+
+        def collapse_to_folder_depth(depth)
+          with_options(options.with(collapse: Projection::FolderDepthCollapse.new(depth:)))
+        end
+
+        def collapse_by_pattern(pattern, replacement = '\\1')
+          collapse = Projection::PatternCollapse.from(pattern, replacement)
+          with_options(options.with(collapse:))
+        end
+
+        def titled(title)
+          with_options(options.with(title:))
+        end
+
+        def with_check_options(value)
+          self.class.new(project_locator:, options:, check_options: value)
+        end
+
+        def snapshot
+          graph = ArchUnit::Extraction.extract_graph(project_locator, options: check_options)
+          Projection::SnapshotFactory.create(graph, options)
+        end
+
+        def summary
+          snapshot.summary
+        end
+
+        Rendering::GraphRenderer::RENDERERS.each_key do |format|
+          define_method("to_#{format}") do
+            Rendering::GraphRenderer.render(snapshot, format)
+          end
+
+          define_method("export_as_#{format}") do |output_path|
+            Rendering::GraphRenderer.export(snapshot, format, output_path)
+          end
+        end
+
+        private
+
+        def with_options(new_options)
+          self.class.new(project_locator:, options: new_options, check_options:)
+        end
+
+        def immutable_project_locator(locator)
+          return if locator.nil?
+
+          locator = locator.to_path if locator.respond_to?(:to_path)
+          return locator.dup.freeze if locator.is_a?(String) && !locator.empty?
+
+          raise ArgumentError, 'project_locator must be a non-empty path or nil'
+        end
+
+        def immutable_check_options(value)
+          return if value.nil?
+          return value if value.is_a?(Common::FluentApi::CheckOptions)
+
+          raise ArgumentError, 'check_options must be a CheckOptions value or nil'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'collapse_node'
+require_relative 'graph_report_edge'
+
+module ArchUnit
+  module GraphReporting
+    module Projection
+      # Aggregates selected raw edges after applying one node-collapse strategy.
+      module AggregateEdges
+        module_function
+
+        def aggregate(edges, collapse:, include_self_dependencies:)
+          groups = Hash.new do |hash, key|
+            hash[key] = { count: 0, external: false, import_kinds: [] }
+          end
+
+          edges.each do |edge|
+            source = CollapseNode.collapse(edge.source, collapse)
+            target = CollapseNode.collapse(edge.target, collapse)
+            next if !include_self_dependencies && source == target
+
+            accumulate(groups[[source, target]], edge)
+          end
+
+          build_edges(groups)
+        end
+
+        def accumulate(group, edge)
+          group[:count] += 1
+          group[:external] ||= edge.external
+          group[:import_kinds] |= edge.import_kinds
+        end
+        private_class_method :accumulate
+
+        def build_edges(groups)
+          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]
+            )
+          end.freeze
+        end
+        private_class_method :build_edges
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'folder_depth_collapse'
+require_relative 'pattern_collapse'
+
+module ArchUnit
+  module GraphReporting
+    module Projection
+      # Pure node-label collapsing shared by snapshot nodes and edges.
+      module CollapseNode
+        module_function
+
+        def collapse(node, strategy)
+          return node if strategy.nil?
+          return node.gsub(strategy.regexp, strategy.replacement) if strategy.is_a?(PatternCollapse)
+
+          collapse_to_folder(node, strategy.depth)
+        end
+
+        def collapse_to_folder(node, depth)
+          parts = node.split('/').reject(&:empty?)
+          return node if parts.length <= 1
+
+          folders = parts[0...-1]
+          return node if folders.empty?
+
+          folders.first(depth).join('/')
+        end
+        private_class_method :collapse_to_folder
+      end
+    end
+  end
+end