archunit 0.0.1

data/lib/archunit/files/assertion/depend_on_external_modules.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative '../../common/assertion/violation'
+require_relative '../../common/filter'
+require_relative '../../common/pattern_matching'
+require_relative '../../common/projection/projected_edge'
+
+module ArchUnit
+  module Files
+    # Pure assertions over dependencies from project files to external modules.
+    module Assertion
+      # Data describing an external module dependency that disagrees with a rule.
+      class ExternalModuleDependencyViolation < Common::Assertion::Violation
+        attr_reader :dependency, :is_negated
+
+        def initialize(dependency:, is_negated: false)
+          @dependency = projected_edge(dependency)
+          @is_negated = boolean_value(is_negated)
+          super()
+        end
+
+        def negated?
+          is_negated
+        end
+
+        def ==(other)
+          other.is_a?(self.class) &&
+            dependency == other.dependency &&
+            is_negated == other.is_negated
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, dependency, is_negated].hash
+        end
+
+        private
+
+        def projected_edge(value)
+          return value if value.is_a?(Common::Projection::ProjectedEdge)
+
+          raise ArgumentError, 'dependency must be a ProjectedEdge'
+        end
+
+        def boolean_value(value)
+          return value if [true, false].include?(value)
+
+          raise ArgumentError, 'is_negated must be true or false'
+        end
+      end
+
+      module_function
+
+      def gather_external_module_dependency_violations(
+        edges, subject_filters, module_filters, is_negated:
+      )
+        validate_external_dependency_arguments(
+          edges, subject_filters, module_filters, is_negated
+        )
+
+        edges.filter_map do |edge|
+          external_dependency_violation(
+            edge, subject_filters, module_filters, is_negated
+          )
+        end
+      end
+
+      def external_dependency_violation(edge, subject_filters, module_filters, is_negated)
+        return unless Common::PatternMatching.matches_all_patterns?(
+          edge.source_label, subject_filters
+        )
+
+        target_matches = Common::PatternMatching.matches_any_pattern?(
+          edge.target_label, module_filters
+        )
+        return unless is_negated ? target_matches : !target_matches
+
+        ExternalModuleDependencyViolation.new(dependency: edge, is_negated:)
+      end
+      private_class_method :external_dependency_violation
+
+      def validate_external_dependency_arguments(
+        edges, subject_filters, module_filters, is_negated
+      )
+        validate_external_projected_edges(edges)
+        validate_external_filters(subject_filters, :subject_filters, allow_empty: true)
+        validate_external_filters(module_filters, :module_filters, allow_empty: false)
+        return if [true, false].include?(is_negated)
+
+        raise ArgumentError, 'is_negated must be true or false'
+      end
+      private_class_method :validate_external_dependency_arguments
+
+      def validate_external_projected_edges(values)
+        return if values.is_a?(Array) && values.all?(Common::Projection::ProjectedEdge)
+
+        raise ArgumentError, 'edges must be an Array of ProjectedEdge values'
+      end
+      private_class_method :validate_external_projected_edges
+
+      def validate_external_filters(values, name, allow_empty:)
+        valid = values.is_a?(Array) && values.all?(Common::Filter)
+        valid &&= !values.empty? unless allow_empty
+        return if valid
+
+        requirement = if allow_empty
+                        'an Array of Filter values'
+                      else
+                        'a non-empty Array of Filter values'
+                      end
+        raise ArgumentError, "#{name} must be #{requirement}"
+      end
+      private_class_method :validate_external_filters
+    end
+  end
+end

data/lib/archunit/files/assertion/depend_on_files.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative '../../common/assertion/violation'
+require_relative '../../common/filter'
+require_relative '../../common/pattern_matching'
+require_relative '../../common/projection/projected_edge'
+
+module ArchUnit
+  module Files
+    # Pure assertions over dependencies between project files.
+    module Assertion
+      # Data describing an internal file dependency that disagrees with a rule.
+      class FileDependencyViolation < Common::Assertion::Violation
+        attr_reader :dependency, :is_negated
+
+        def initialize(dependency:, is_negated: false)
+          @dependency = projected_edge(dependency)
+          @is_negated = boolean_value(is_negated)
+          super()
+        end
+
+        def negated?
+          is_negated
+        end
+
+        def ==(other)
+          other.is_a?(self.class) &&
+            dependency == other.dependency &&
+            is_negated == other.is_negated
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, dependency, is_negated].hash
+        end
+
+        private
+
+        def projected_edge(value)
+          return value if value.is_a?(Common::Projection::ProjectedEdge)
+
+          raise ArgumentError, 'dependency must be a ProjectedEdge'
+        end
+
+        def boolean_value(value)
+          return value if [true, false].include?(value)
+
+          raise ArgumentError, 'is_negated must be true or false'
+        end
+      end
+
+      module_function
+
+      def gather_file_dependency_violations(
+        edges, subject_filters, object_filters, is_negated:
+      )
+        validate_dependency_arguments(edges, subject_filters, object_filters, is_negated)
+
+        edges.filter_map do |edge|
+          dependency_violation(edge, subject_filters, object_filters, is_negated)
+        end
+      end
+
+      def dependency_violation(edge, subject_filters, object_filters, is_negated)
+        return unless Common::PatternMatching.matches_all_patterns?(
+          edge.source_label, subject_filters
+        )
+
+        target_matches = Common::PatternMatching.matches_all_patterns?(
+          edge.target_label, object_filters
+        )
+        return unless is_negated ? target_matches : !target_matches
+
+        FileDependencyViolation.new(dependency: edge, is_negated:)
+      end
+      private_class_method :dependency_violation
+
+      def validate_dependency_arguments(edges, subject_filters, object_filters, is_negated)
+        validate_projected_edges(edges)
+        validate_filters(subject_filters, :subject_filters, allow_empty: true)
+        validate_filters(object_filters, :object_filters, allow_empty: false)
+        return if [true, false].include?(is_negated)
+
+        raise ArgumentError, 'is_negated must be true or false'
+      end
+      private_class_method :validate_dependency_arguments
+
+      def validate_projected_edges(values)
+        return if values.is_a?(Array) && values.all?(Common::Projection::ProjectedEdge)
+
+        raise ArgumentError, 'edges must be an Array of ProjectedEdge values'
+      end
+      private_class_method :validate_projected_edges
+
+      def validate_filters(values, name, allow_empty:)
+        valid = values.is_a?(Array) && values.all?(Common::Filter)
+        valid &&= !values.empty? unless allow_empty
+        return if valid
+
+        requirement = if allow_empty
+                        'an Array of Filter values'
+                      else
+                        'a non-empty Array of Filter values'
+                      end
+        raise ArgumentError, "#{name} must be #{requirement}"
+      end
+      private_class_method :validate_filters
+    end
+  end
+end

data/lib/archunit/files/assertion/matching_files.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative '../../common/assertion/violation'
+require_relative '../../common/filter'
+require_relative '../../common/pattern_matching'
+require_relative '../../common/projection/projected_node'
+
+module ArchUnit
+  module Files
+    # Pure file-pattern assertion functions and violation values.
+    module Assertion
+      # Data describing a selected file that disagrees with a pattern predicate.
+      class FilePatternViolation < Common::Assertion::Violation
+        attr_reader :check_filter, :projected_node, :is_negated
+
+        def initialize(check_filter:, projected_node:, is_negated: false)
+          @check_filter = filter_value(check_filter)
+          @projected_node = node_value(projected_node)
+          @is_negated = boolean_value(is_negated)
+          super()
+        end
+
+        def negated?
+          is_negated
+        end
+
+        def ==(other)
+          other.is_a?(self.class) &&
+            check_filter == other.check_filter &&
+            projected_node == other.projected_node &&
+            is_negated == other.is_negated
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, check_filter, projected_node, is_negated].hash
+        end
+
+        private
+
+        def filter_value(value)
+          return value if value.is_a?(Common::Filter)
+
+          raise ArgumentError, 'check_filter must be a Filter'
+        end
+
+        def node_value(value)
+          return value if value.is_a?(Common::Projection::ProjectedNode)
+
+          raise ArgumentError, 'projected_node must be a ProjectedNode'
+        end
+
+        def boolean_value(value)
+          return value if [true, false].include?(value)
+
+          raise ArgumentError, 'is_negated must be true or false'
+        end
+      end
+
+      module_function
+
+      def gather_matching_file_violations(nodes, check_filter, is_negated:)
+        validate_matching_arguments(nodes, check_filter, is_negated)
+
+        nodes.filter_map do |node|
+          matches = Common::PatternMatching.matches_pattern?(node.label, check_filter)
+          next unless is_negated ? matches : !matches
+
+          FilePatternViolation.new(check_filter:, projected_node: node, is_negated:)
+        end
+      end
+
+      def validate_matching_arguments(nodes, check_filter, is_negated)
+        unless nodes.is_a?(Array) && nodes.all?(Common::Projection::ProjectedNode)
+          raise ArgumentError, 'nodes must be an Array of ProjectedNode values'
+        end
+        unless check_filter.is_a?(Common::Filter)
+          raise ArgumentError, 'check_filter must be a Filter'
+        end
+        return if [true, false].include?(is_negated)
+
+        raise ArgumentError, 'is_negated must be true or false'
+      end
+      private_class_method :validate_matching_arguments
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative '../../error/technical_error'
+require_relative 'file_info'
+
+module ArchUnit
+  module Files
+    # Ruby-specific descriptive data extraction for file rules.
+    module Extraction
+      module_function
+
+      def extract_file_info(project_root, relative_path)
+        root = project_directory(project_root)
+        identifier = normalized_identifier(relative_path)
+        source_path = source_path_within(root, identifier)
+        build_file_info(identifier, read_source(source_path))
+      rescue TechnicalError
+        raise
+      rescue SystemCallError => e
+        raise TechnicalError, "could not extract file information: #{e.message}"
+      end
+
+      def read_source(path)
+        File.binread(path).force_encoding(Encoding::UTF_8).scrub
+      end
+      private_class_method :read_source
+
+      def build_file_info(identifier, content)
+        extension = File.extname(identifier)
+        FileInfo.new(
+          path: identifier,
+          name: File.basename(identifier, extension),
+          extension:,
+          directory: directory_of(identifier),
+          content:,
+          lines_of_code: content.lines.count { |line| !line.strip.empty? }
+        )
+      end
+      private_class_method :build_file_info
+
+      def project_directory(value)
+        value = value.to_path if value.respond_to?(:to_path)
+        unless value.is_a?(String) && !value.empty?
+          raise ArgumentError, 'project_root must be a non-empty path'
+        end
+
+        root = Pathname.new(value).expand_path
+        raise TechnicalError, 'project_root must be an existing directory' unless root.directory?
+
+        root.realpath
+      end
+      private_class_method :project_directory
+
+      def normalized_identifier(value)
+        unless value.is_a?(String) && !value.empty?
+          raise ArgumentError, 'relative_path must be a non-empty String'
+        end
+
+        value.tr('\\', '/').freeze
+      end
+      private_class_method :normalized_identifier
+
+      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
+        raise TechnicalError, "source file does not exist: #{identifier}" unless path.file?
+
+        path
+      end
+      private_class_method :source_path_within
+
+      def directory_of(identifier)
+        return '' unless identifier.include?('/')
+
+        File.dirname(identifier).tr('\\', '/').freeze
+      end
+      private_class_method :directory_of
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module Files
+    # Ruby-specific descriptive data extraction for file rules.
+    module Extraction
+      # Immutable source-file information exposed to custom predicates.
+      FileInfo = Data.define(
+        :path, :name, :extension, :directory, :content, :lines_of_code
+      ) do
+        # rubocop:disable 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)
+          extension = immutable_string(extension, :extension, allow_empty: true)
+          directory = immutable_string(
+            directory, :directory, allow_empty: true, normalize_path: true
+          )
+          content = immutable_string(content, :content, allow_empty: true)
+          lines_of_code = non_negative_integer(lines_of_code)
+          super
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        private
+
+        def immutable_string(value, attribute, allow_empty:, normalize_path: false)
+          valid = value.is_a?(String) && (allow_empty || !value.empty?)
+          unless valid
+            requirement = allow_empty ? 'a String' : 'a non-empty String'
+            raise ArgumentError, "#{attribute} must be #{requirement}"
+          end
+
+          value = value.tr('\\', '/') if normalize_path
+          value.dup.freeze
+        end
+
+        def non_negative_integer(value)
+          return value if value.is_a?(Integer) && value >= 0
+
+          raise ArgumentError, 'lines_of_code must be a non-negative Integer'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative '../../common/fluentapi/checkable'
+require_relative '../../extraction/extract_graph'
+require_relative '../../extraction/locate_project'
+require_relative '../assertion/custom_file_condition'
+require_relative '../extraction/extract_file_info'
+require_relative 'file_rule_support'
+
+module ArchUnit
+  module Files
+    module FluentApi
+      # Executable custom predicate evaluated against immutable FileInfo values.
+      class CustomFileCondition
+        include Common::FluentApi::Checkable
+
+        attr_reader :project_locator, :subject_filters, :condition, :message, :is_negated
+
+        def initialize(mood, condition:, message:)
+          validate_mood(mood)
+          @project_locator = mood.project_locator
+          @subject_filters = mood.filters
+          @condition = callable_value(condition)
+          @message = message_value(message)
+          @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 callable_value(value)
+          return value if value.respond_to?(:call)
+
+          raise ArgumentError, 'condition must be callable'
+        end
+
+        def message_value(value)
+          return value.dup.freeze if value.is_a?(String) && !value.strip.empty?
+
+          raise ArgumentError, 'message must be a non-empty String'
+        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
+
+          Assertion.gather_custom_file_violations(
+            extract_file_infos(nodes), condition, message, is_negated:
+          )
+        end
+
+        def extract_file_infos(nodes)
+          root = ArchUnit::Extraction.locate_project(project_locator)
+          nodes.map { |node| Files::Extraction.extract_file_info(root, node.label) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative '../../common/fluentapi/checkable'
+require_relative '../../common/projection/edge_projections'
+require_relative '../../common/projection/project_cycles'
+require_relative '../../common/projection/project_edges'
+require_relative '../../extraction/extract_graph'
+require_relative '../assertion/cycle_free'
+require_relative 'file_rule_support'
+
+module ArchUnit
+  module Files
+    module FluentApi
+      # Executable positive rule requiring the selected file graph to be acyclic.
+      class CycleFreeFileCondition
+        include Common::FluentApi::Checkable
+
+        attr_reader :project_locator, :filters
+
+        def initialize(mood)
+          unless mood.is_a?(PositiveMatchPatternFileConditionBuilder)
+            raise ArgumentError, 'mood must be a positive file condition builder'
+          end
+
+          @project_locator = mood.project_locator
+          @filters = mood.filters
+          freeze
+        end
+
+        private
+
+        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: false, options:
+          )
+          return empty_test if empty_test
+
+          cycles = cycles_within(graph, nodes)
+          Assertion.gather_cycle_violations(cycles)
+        end
+
+        def cycles_within(graph, nodes)
+          selected_labels = nodes.to_h { |node| [node.label, true] }
+          edges = Common::Projection.project_edges(graph, Common::Projection.per_internal_edge)
+                                    .select do |edge|
+            selected_labels[edge.source_label] && selected_labels[edge.target_label]
+          end
+          Common::Projection.project_cycles(edges)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# 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_external_modules'
+require_relative 'file_rule_support'
+
+module ArchUnit
+  module Files
+    module FluentApi
+      # Executable external-module rule with OR-combined module selectors.
+      class DependOnExternalModuleCondition
+        include Common::FluentApi::Checkable
+
+        attr_reader :builder, :project_locator, :subject_filters, :module_filters, :is_negated
+
+        def initialize(builder, module_filters:)
+          unless builder.is_a?(DependOnExternalModuleConditionBuilder)
+            raise ArgumentError, 'builder must be a DependOnExternalModuleConditionBuilder'
+          end
+
+          @builder = builder
+          @project_locator = builder.project_locator
+          @subject_filters = builder.subject_filters
+          @module_filters = immutable_module_filters(module_filters)
+          @is_negated = builder.negated?
+          freeze
+        end
+
+        def negated?
+          is_negated
+        end
+
+        def matching(module_name, except: nil)
+          filter = Common::RegexFactory.path_matcher(module_name, except:)
+          self.class.new(builder, module_filters: [*module_filters, filter])
+        end
+
+        private
+
+        def immutable_module_filters(values)
+          filters = Array(values).dup
+          unless !filters.empty? && filters.all?(Common::Filter)
+            raise ArgumentError, 'module_filters must contain at least one Filter'
+          end
+
+          filters.freeze
+        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_external_edge)
+          Assertion.gather_external_module_dependency_violations(
+            edges, subject_filters, module_filters, is_negated:
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative '../../common/regex_factory'
+require_relative 'depend_on_external_module_condition'
+
+module ArchUnit
+  module Files
+    module FluentApi
+      # Immutable object stage selecting external dependency names.
+      class DependOnExternalModuleConditionBuilder
+        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 matching(module_name, except: nil)
+          filter = Common::RegexFactory.path_matcher(module_name, except:)
+          DependOnExternalModuleCondition.new(self, module_filters: [filter])
+        end
+      end
+    end
+  end
+end