RubyGems - archunit - Versions diffs - 0.0.1 - Mend

archunit 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (149) hide show

data/lib/archunit/metrics/reporting/metrics_exporter.rb ADDED Viewed

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+require 'cgi/escape'
+require 'fileutils'
+require 'time'
+require_relative 'metrics_export_options'
+module ArchUnit
+  module Metrics
+    # Self-contained metrics report rendering and export.
+    module Reporting
+      # Renders caller-supplied metric data as a complete offline HTML document.
+      module MetricsExporter
+        DEFAULT_CSS = <<~CSS
+          :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
+          body { max-width: 960px; margin: 0 auto; padding: 2rem; }
+          h1 { margin-bottom: .25rem; }
+          .timestamp { color: #666; margin-top: 0; }
+          table { border-collapse: collapse; margin-top: 1.5rem; width: 100%; }
+          th, td { border: 1px solid #bbb; padding: .6rem .8rem; text-align: left; }
+          th { background: rgba(127, 127, 127, .14); }
+          tr:nth-child(even) { background: rgba(127, 127, 127, .07); }
+          footer { color: #666; font-size: .85rem; margin-top: 2rem; }
+        CSS
+        module_function
+        def export_as_html(data, options = nil)
+          raise ArgumentError, 'data must be a Hash' unless data.is_a?(Hash)
+          options = MetricsExportOptions.resolve(options)
+          html = render(data, options).freeze
+          write(options.output_path, html) if options.output_path
+          html
+        end
+        def render(data, options)
+          title = escape(options.title)
+          <<~HTML
+            <!DOCTYPE html>
+            <html lang="en">
+            #{document_head(title, options)}
+            #{document_body(title, data, options)}
+            </html>
+          HTML
+        end
+        private_class_method :render
+        def document_head(title, options)
+          <<~HTML.chomp
+            <head>
+              <meta charset="utf-8">
+              <meta name="viewport" content="width=device-width, initial-scale=1">
+              <title>#{title}</title>
+              <style>#{safe_css(options.custom_css || DEFAULT_CSS)}</style>
+            </head>
+          HTML
+        end
+        private_class_method :document_head
+        def document_body(title, data, options)
+          <<~HTML.chomp
+            <body>
+              <main>
+                <h1>#{title}</h1>
+                #{timestamp(options)}
+                #{metric_table(data)}
+              </main>
+              <footer>Generated by ArchUnitRuby</footer>
+            </body>
+          HTML
+        end
+        private_class_method :document_body
+        def metric_table(data)
+          <<~HTML.chomp
+            <table>
+              <thead><tr><th>Metric</th><th>Value</th></tr></thead>
+              <tbody>#{rows(data)}</tbody>
+            </table>
+          HTML
+        end
+        private_class_method :metric_table
+        def rows(data)
+          return '<tr><td colspan="2">No metric data.</td></tr>' if data.empty?
+          data.map do |name, value|
+            "<tr><td>#{escape(name)}</td><td>#{escape(value)}</td></tr>"
+          end.join
+        end
+        private_class_method :rows
+        def timestamp(options)
+          return '' unless options.include_timestamp
+          value = Time.now.utc.iso8601
+          %(<p class="timestamp">Generated: #{escape(value)}</p>)
+        end
+        private_class_method :timestamp
+        def write(output_path, html)
+          path = html_path(output_path)
+          directory = File.dirname(path)
+          FileUtils.mkdir_p(directory) unless directory == '.'
+          File.binwrite(path, html.encode(Encoding::UTF_8))
+          nil
+        end
+        private_class_method :write
+        def html_path(path)
+          return path if File.extname(path).casecmp?('.html')
+          "#{path}.html"
+        end
+        private_class_method :html_path
+        def escape(value)
+          CGI.escapeHTML(value.to_s)
+        end
+        private_class_method :escape
+        def safe_css(value)
+          value.gsub(%r{</style}i, '<\\/style')
+        end
+        private_class_method :safe_css
+      end
+    end
+  end
+end

data/lib/archunit/slices/assertion/adhere_to_diagram.rb ADDED Viewed

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+require_relative '../../common/projection/projected_edge'
+require_relative '../uml/plant_uml_diagram'
+require_relative 'diagram_adherence_options'
+require_relative 'slice_dependency_violation'
+module ArchUnit
+  module Slices
+    # Pure assertions over projected slice dependencies.
+    module Assertion
+      module_function
+      def gather_diagram_adherence_violations(edges, diagram, options = nil)
+        validate_diagram_arguments(edges, diagram, options)
+        options ||= DiagramAdherenceOptions.new
+        edges.filter_map do |edge|
+          next if ignored_diagram_edge?(edge, diagram, options)
+          next if diagram.allows?(edge.source_label, edge.target_label)
+          SliceDependencyViolation.new(
+            dependency: edge, source_slice: edge.source_label,
+            target_slice: edge.target_label, rule: :adhere_to_diagram, is_negated: false
+          )
+        end
+      end
+      def ignored_diagram_edge?(edge, diagram, options)
+        return true if options.ignore_external_slices? && external_dependency?(edge)
+        return false unless options.ignore_orphan_slices?
+        !diagram.components.include?(edge.source_label) ||
+          !diagram.components.include?(edge.target_label)
+      end
+      private_class_method :ignored_diagram_edge?
+      def external_dependency?(edge)
+        edge.cumulated_edges.any?(&:external)
+      end
+      private_class_method :external_dependency?
+      def validate_diagram_arguments(edges, diagram, options)
+        unless edges.is_a?(Array) && edges.all?(Common::Projection::ProjectedEdge)
+          raise ArgumentError, 'edges must be an Array of ProjectedEdge values'
+        end
+        unless diagram.is_a?(Uml::PlantUmlDiagram)
+          raise ArgumentError, 'diagram must be a PlantUmlDiagram'
+        end
+        return if options.nil? || options.is_a?(DiagramAdherenceOptions)
+        raise ArgumentError, 'options must be DiagramAdherenceOptions or nil'
+      end
+      private_class_method :validate_diagram_arguments
+    end
+  end
+end

data/lib/archunit/slices/assertion/contain_dependency.rb ADDED Viewed

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+require_relative '../../common/projection/projected_edge'
+require_relative 'slice_dependency_violation'
+module ArchUnit
+  module Slices
+    # Pure assertions over projected slice dependencies.
+    module Assertion
+      module_function
+      def gather_forbidden_slice_dependency_violations(edges, source_slice, target_slice)
+        validate_edges(edges)
+        source_slice = validated_slice_name(source_slice, :source_slice)
+        target_slice = validated_slice_name(target_slice, :target_slice)
+        edges.filter_map do |edge|
+          next unless edge.source_label == source_slice && edge.target_label == target_slice
+          SliceDependencyViolation.new(
+            dependency: edge, source_slice:, target_slice:,
+            rule: :contain_dependency, is_negated: true
+          )
+        end
+      end
+      def validate_edges(value)
+        return if value.is_a?(Array) && value.all?(Common::Projection::ProjectedEdge)
+        raise ArgumentError, 'edges must be an Array of ProjectedEdge values'
+      end
+      private_class_method :validate_edges
+      def validated_slice_name(value, attribute)
+        return value if value.is_a?(String) && !value.strip.empty?
+        raise ArgumentError, "#{attribute} must be a non-empty String"
+      end
+      private_class_method :validated_slice_name
+    end
+  end
+end

data/lib/archunit/slices/assertion/diagram_adherence_options.rb ADDED Viewed

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+module ArchUnit
+  module Slices
+    # Pure assertions over projected slice dependencies.
+    module Assertion
+      # Immutable modifiers controlling diagram coherence checks.
+      DiagramAdherenceOptions = Data.define(:ignore_orphan_slices, :ignore_external_slices) do
+        def initialize(ignore_orphan_slices: false, ignore_external_slices: false)
+          validate_boolean(ignore_orphan_slices, :ignore_orphan_slices)
+          validate_boolean(ignore_external_slices, :ignore_external_slices)
+          super
+        end
+        def with(**overrides)
+          self.class.new(**to_h, **overrides)
+        end
+        def ignore_orphan_slices?
+          ignore_orphan_slices
+        end
+        def ignore_external_slices?
+          ignore_external_slices
+        end
+        private
+        def validate_boolean(value, attribute)
+          return if [true, false].include?(value)
+          raise ArgumentError, "#{attribute} must be true or false"
+        end
+      end
+    end
+  end
+end

data/lib/archunit/slices/assertion/slice_dependency_violation.rb ADDED Viewed

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+require_relative '../../common/assertion/violation'
+require_relative '../../common/projection/projected_edge'
+module ArchUnit
+  module Slices
+    # Pure assertions over projected slice dependencies.
+    module Assertion
+      # Structured evidence for a dependency rejected by a slice rule.
+      class SliceDependencyViolation < Common::Assertion::Violation
+        RULES = %i[contain_dependency adhere_to_diagram].freeze
+        attr_reader :dependency, :source_slice, :target_slice, :rule, :is_negated
+        def initialize(dependency:, source_slice:, target_slice:, rule:, is_negated:)
+          @dependency = projected_edge(dependency)
+          @source_slice = slice_name(source_slice, :source_slice)
+          @target_slice = slice_name(target_slice, :target_slice)
+          @rule = rule_value(rule)
+          @is_negated = boolean(is_negated, :is_negated)
+          super()
+        end
+        def negated?
+          is_negated
+        end
+        def ==(other)
+          other.is_a?(self.class) && values == other.send(:values)
+        end
+        alias eql? ==
+        def hash
+          [self.class, *values].hash
+        end
+        private
+        def values
+          [dependency, source_slice, target_slice, rule, is_negated]
+        end
+        def projected_edge(value)
+          return value if value.is_a?(Common::Projection::ProjectedEdge)
+          raise ArgumentError, 'dependency must be a ProjectedEdge'
+        end
+        def slice_name(value, attribute)
+          return value.dup.freeze if value.is_a?(String) && !value.strip.empty?
+          raise ArgumentError, "#{attribute} must be a non-empty String"
+        end
+        def rule_value(value)
+          return value if RULES.include?(value)
+          raise ArgumentError, "rule must be one of: #{RULES.join(', ')}"
+        end
+        def boolean(value, attribute)
+          return value if [true, false].include?(value)
+          raise ArgumentError, "#{attribute} must be true or false"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+require_relative '../../common/fluentapi/checkable'
+require_relative '../../common/projection/project_edges'
+require_relative '../../extraction/extract_graph'
+require_relative '../assertion/adhere_to_diagram'
+require_relative '../uml/parse_diagram'
+module ArchUnit
+  module Slices
+    module FluentApi
+      # Executable `slices should adhere to diagram` rule.
+      class DiagramSliceCondition
+        include Common::FluentApi::Checkable
+        attr_reader :scope, :project_locator, :projection, :diagram_source, :options
+        def initialize(scope, diagram_source, options:)
+          @scope = scope_value(scope)
+          @project_locator = scope.project_locator
+          @projection = scope.projection
+          @diagram_source = diagram_source_value(diagram_source)
+          @options = options_value(options)
+          freeze
+        end
+        def negated?
+          false
+        end
+        private
+        def perform_check(check_options)
+          graph = ArchUnit::Extraction.extract_graph(project_locator, options: check_options)
+          empty_test = empty_test_violation(
+            projection.slice_labels(graph), filters: [], negated: false, options: check_options
+          )
+          return empty_test if empty_test
+          diagram = Uml::PlantUmlParser.parse(diagram_source.read)
+          edges = Common::Projection.project_edges(graph, projection)
+          Assertion.gather_diagram_adherence_violations(edges, diagram, options)
+        end
+        def scope_value(value)
+          return value if value.is_a?(SliceScopeBuilder)
+          raise ArgumentError, 'scope must be a SliceScopeBuilder'
+        end
+        def diagram_source_value(value)
+          return value if value.is_a?(DiagramSource)
+          raise ArgumentError, 'diagram_source must be a DiagramSource'
+        end
+        def options_value(value)
+          return value if value.is_a?(Assertion::DiagramAdherenceOptions)
+          raise ArgumentError, 'options must be DiagramAdherenceOptions'
+        end
+      end
+    end
+  end
+end

data/lib/archunit/slices/fluentapi/diagram_source.rb ADDED Viewed

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+module ArchUnit
+  module Slices
+    module FluentApi
+      DIAGRAM_SOURCE_KINDS = %i[inline file].freeze
+      # Immutable inline or file-backed PlantUML source, read only by a terminal check.
+      DiagramSource = Data.define(:kind, :value) do
+        def self.inline(text)
+          new(kind: :inline, value: text)
+        end
+        def self.file(path)
+          path = path.to_path if path.respond_to?(:to_path)
+          new(kind: :file, value: path)
+        end
+        def initialize(kind:, value:)
+          unless DIAGRAM_SOURCE_KINDS.include?(kind)
+            raise ArgumentError, "kind must be one of: #{DIAGRAM_SOURCE_KINDS.join(', ')}"
+          end
+          unless value.is_a?(String) && !value.empty?
+            raise ArgumentError, 'diagram source value must be a non-empty String'
+          end
+          super(kind:, value: value.dup.freeze)
+        end
+        def read
+          kind == :inline ? value : File.read(value, encoding: Encoding::UTF_8)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+require_relative '../../common/fluentapi/checkable'
+require_relative '../../common/projection/project_edges'
+require_relative '../../extraction/extract_graph'
+require_relative '../assertion/contain_dependency'
+module ArchUnit
+  module Slices
+    module FluentApi
+      # Executable `slices should not contain dependency` rule.
+      class ForbiddenSliceDependencyCondition
+        include Common::FluentApi::Checkable
+        attr_reader :scope, :project_locator, :projection, :source_slice, :target_slice
+        def initialize(scope, source_slice:, target_slice:)
+          unless scope.is_a?(SliceScopeBuilder)
+            raise ArgumentError, 'scope must be a SliceScopeBuilder'
+          end
+          @scope = scope
+          @project_locator = scope.project_locator
+          @projection = scope.projection
+          @source_slice = immutable_slice_name(source_slice, :source_slice)
+          @target_slice = immutable_slice_name(target_slice, :target_slice)
+          freeze
+        end
+        def negated?
+          true
+        end
+        private
+        def perform_check(options)
+          graph = ArchUnit::Extraction.extract_graph(project_locator, options:)
+          empty_test = empty_test_violation(
+            projection.slice_labels(graph), filters: [], negated: true, options:
+          )
+          return empty_test if empty_test
+          edges = Common::Projection.project_edges(graph, projection)
+          Assertion.gather_forbidden_slice_dependency_violations(
+            edges, source_slice, target_slice
+          )
+        end
+        def immutable_slice_name(value, attribute)
+          return value.dup.freeze if value.is_a?(String) && !value.strip.empty?
+          raise ArgumentError, "#{attribute} must be a non-empty String"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+require_relative 'forbidden_slice_dependency_condition'
+module ArchUnit
+  module Slices
+    module FluentApi
+      # Immutable negated mood for forbidden slice dependencies.
+      class NegativeSliceConditionBuilder
+        attr_reader :scope
+        def initialize(scope)
+          unless scope.is_a?(SliceScopeBuilder)
+            raise ArgumentError, 'scope must be a SliceScopeBuilder'
+          end
+          @scope = scope
+          freeze
+        end
+        def contain_dependency(source_slice, target_slice)
+          ForbiddenSliceDependencyCondition.new(scope, source_slice:, target_slice:)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+require_relative '../assertion/diagram_adherence_options'
+require_relative 'diagram_slice_condition'
+require_relative 'diagram_source'
+module ArchUnit
+  module Slices
+    module FluentApi
+      # Immutable positive mood and optional modifiers for diagram adherence.
+      class PositiveSliceConditionBuilder
+        attr_reader :scope, :options
+        def initialize(scope, options: Assertion::DiagramAdherenceOptions.new)
+          unless scope.is_a?(SliceScopeBuilder)
+            raise ArgumentError, 'scope must be a SliceScopeBuilder'
+          end
+          unless options.is_a?(Assertion::DiagramAdherenceOptions)
+            raise ArgumentError, 'options must be DiagramAdherenceOptions'
+          end
+          @scope = scope
+          @options = options
+          freeze
+        end
+        def ignoring_orphan_slices
+          copy(options.with(ignore_orphan_slices: true))
+        end
+        def ignoring_external_slices
+          copy(options.with(ignore_external_slices: true))
+        end
+        def adhere_to_diagram(text)
+          DiagramSliceCondition.new(scope, DiagramSource.inline(text), options:)
+        end
+        def adhere_to_diagram_in_file(path)
+          DiagramSliceCondition.new(scope, DiagramSource.file(path), options:)
+        end
+        private
+        def copy(new_options)
+          self.class.new(scope, options: new_options)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+require_relative '../projection/slicing_projections'
+require_relative 'negative_slice_condition_builder'
+require_relative 'positive_slice_condition_builder'
+require_relative '../uml/export_diagram'
+require_relative '../../common/fluentapi/check_options'
+require_relative '../../common/projection/project_edges'
+require_relative '../../extraction/extract_graph'
+module ArchUnit
+  module Slices
+    # Sentence-like builders for slice architecture rules.
+    module FluentApi
+      # Immutable scope describing how project files become named slices.
+      class SliceScopeBuilder
+        attr_reader :project_locator, :projection
+        def initialize(project_locator: nil, projection: Projection.identity)
+          @project_locator = immutable_project_locator(project_locator)
+          @projection = projection_value(projection)
+          freeze
+        end
+        def defined_by(pattern, except: nil)
+          copy(projection: Projection.slice_by_pattern(pattern, except:))
+        end
+        def defined_by_regex(regexp, except: nil)
+          copy(projection: Projection.slice_by_regex(regexp, except:))
+        end
+        def should_not
+          NegativeSliceConditionBuilder.new(self)
+        end
+        def should
+          PositiveSliceConditionBuilder.new(self)
+        end
+        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
+        def export_as_plantuml(output_path, options = nil)
+          graph = extract_graph(options)
+          edges = Common::Projection.project_edges(graph, projection)
+          Uml::PlantUmlRenderer.export(
+            edges, output_path, components: projection.slice_labels(graph)
+          )
+        end
+        private
+        def copy(projection: self.projection)
+          self.class.new(project_locator:, projection:)
+        end
+        def extract_graph(options)
+          options = Common::FluentApi::CheckOptions.resolve(options)
+          ArchUnit::Extraction.extract_graph(project_locator, 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 projection_value(value)
+          return value if value.is_a?(Projection::SliceProjection)
+          raise ArgumentError, 'projection must be a SliceProjection'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+require_relative 'slice_scope_builder'
+# Public ArchUnitRuby entry points for slice architecture rules.
+module ArchUnit
+  module Slices
+    # Sentence-like entry points and builders for slice architecture rules.
+    module FluentApi
+      module_function
+      def project_slices(project_locator = nil)
+        SliceScopeBuilder.new(project_locator:)
+      end
+      class << self
+        alias slices project_slices
+      end
+    end
+  end
+  def self.project_slices(project_locator = nil)
+    Slices::FluentApi.project_slices(project_locator)
+  end
+  class << self
+    alias slices project_slices
+  end
+end