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/graph/rendering/html_document.rb ADDED Viewed

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+module ArchUnit
+  module GraphReporting
+    module Rendering
+      # Static offline document shell used by the HTML graph renderer.
+      module HtmlDocument
+        TEMPLATE = <<~HTML
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+            <meta charset="UTF-8" />
+            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+            <title>%<title>s</title>
+            <style>
+              :root { color-scheme: light; font-family: Inter, Arial, sans-serif; }
+              body { margin: 0; color: #172033; background: #f5f7fb; }
+              header { padding: 28px 36px; color: white; background: #13294b; }
+              header h1 { margin: 0 0 6px; font-size: 28px; }
+              header p { margin: 0; color: #d7e3f4; }
+              main { max-width: 1180px; margin: 0 auto; padding: 28px 36px 48px; }
+              h2 { margin-top: 32px; font-size: 20px; }
+              .summary { display: grid; grid-template-columns: repeat(4, 1fr); gap: 12px; }
+              .metric { padding: 16px; border: 1px solid #d8deea; border-radius: 8px; background: white; }
+              .metric strong { display: block; font-size: 26px; color: #13294b; }
+              table { width: 100%%; border-collapse: collapse; background: white; }
+              th, td { padding: 9px 11px; border: 1px solid #d8deea; text-align: left; }
+              th { background: #eaf0f8; }
+              code, pre { font-family: Consolas, "SFMono-Regular", monospace; }
+              pre { overflow: auto; padding: 16px; color: #e7edf7; background: #101827; border-radius: 8px; }
+              details { margin: 12px 0; }
+              summary { cursor: pointer; font-weight: 700; }
+              .empty { padding: 16px; border: 1px solid #d8deea; background: white; }
+              @media (max-width: 760px) { .summary { grid-template-columns: repeat(2, 1fr); } }
+            </style>
+          </head>
+          <body>
+            <header><h1>%<title>s</h1><p>Generated by ArchUnitRuby graph reporting</p></header>
+            <main>%<body>s</main>
+          </body>
+          </html>
+        HTML
+      end
+    end
+  end
+end

data/lib/archunit/graph/rendering/html_renderer.rb ADDED Viewed

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+require_relative 'd2_renderer'
+require_relative 'dot_renderer'
+require_relative 'escaping'
+require_relative 'html_document'
+require_relative 'json_renderer'
+require_relative 'mermaid_renderer'
+require_relative 'rendering_support'
+module ArchUnit
+  module GraphReporting
+    module Rendering
+      # Renders a complete offline HTML report with no external resources.
+      module HtmlRenderer
+        module_function
+        def render(snapshot)
+          snapshot = RenderingSupport.validate_snapshot(snapshot)
+          title = Escaping.html(snapshot.title)
+          format(HtmlDocument::TEMPLATE, title:, body: report_body(snapshot))
+        end
+        def report_body(snapshot)
+          [
+            summary_section(snapshot), node_section(snapshot), dependency_section(snapshot),
+            source_section(snapshot)
+          ].join("\n")
+        end
+        private_class_method :report_body
+        def summary_section(snapshot)
+          summary = snapshot.summary
+          <<~HTML
+            <section class="summary" aria-label="Graph summary">
+              #{metric(summary.node_count, 'Nodes')}
+              #{metric(summary.edge_count, 'Aggregated edges')}
+              #{metric(summary.raw_edge_count, 'Raw edges')}
+              #{metric(summary.external_edge_count, 'External edges')}
+            </section>
+          HTML
+        end
+        private_class_method :summary_section
+        def metric(value, label)
+          "<div class=\"metric\"><strong>#{value}</strong>#{Escaping.html(label)}</div>"
+        end
+        private_class_method :metric
+        def node_section(snapshot)
+          items = snapshot.nodes.map do |node|
+            "<li><code>#{Escaping.html(node.label)}</code></li>"
+          end.join
+          "<section><h2>Nodes</h2><ul>#{items}</ul></section>"
+        end
+        private_class_method :node_section
+        def dependency_section(snapshot)
+          return empty_dependency_section if snapshot.edges.empty?
+          rows = snapshot.edges.map { |edge| dependency_row(edge) }.join
+          <<~HTML
+            <section><h2>Dependencies</h2><table>
+              <thead><tr><th>Source</th><th>Target</th><th>Count</th><th>External</th><th>Import kinds</th></tr></thead>
+              <tbody>#{rows}</tbody>
+            </table></section>
+          HTML
+        end
+        private_class_method :dependency_section
+        def dependency_row(edge)
+          values = [
+            edge.source, edge.target, edge.count,
+            edge.external ? 'yes' : 'no', edge.import_kinds.join(', ')
+          ]
+          "<tr>#{values.map { |value| "<td>#{Escaping.html(value)}</td>" }.join}</tr>"
+        end
+        private_class_method :dependency_row
+        def empty_dependency_section
+          '<section><h2>Dependencies</h2><div class="empty">' \
+            'No dependency edges matched this graph query.</div></section>'
+        end
+        private_class_method :empty_dependency_section
+        def source_section(snapshot)
+          sources = {
+            'Mermaid' => MermaidRenderer.render(snapshot),
+            'DOT' => DotRenderer.render(snapshot),
+            'D2' => D2Renderer.render(snapshot),
+            'JSON snapshot' => JsonRenderer.render(snapshot)
+          }
+          details = sources.map do |name, source|
+            "<details><summary>#{name}</summary><pre>#{Escaping.html(source)}</pre></details>"
+          end.join
+          "<section><h2>Portable sources</h2>#{details}</section>"
+        end
+        private_class_method :source_section
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+require 'json'
+require_relative 'rendering_support'
+module ArchUnit
+  module GraphReporting
+    module Rendering
+      # Renders the complete graph snapshot as stable, formatted JSON.
+      module JsonRenderer
+        module_function
+        def render(snapshot)
+          snapshot = RenderingSupport.validate_snapshot(snapshot)
+          JSON.pretty_generate(snapshot_hash(snapshot))
+        end
+        def snapshot_hash(snapshot)
+          {
+            title: snapshot.title,
+            nodes: snapshot.nodes.map { |node| { id: node.id, label: node.label } },
+            edges: snapshot.edges.map { |edge| edge_hash(edge) },
+            summary: snapshot.summary.to_h
+          }
+        end
+        private_class_method :snapshot_hash
+        def edge_hash(edge)
+          {
+            source: edge.source, target: edge.target, count: edge.count,
+            external: edge.external, import_kinds: edge.import_kinds
+          }
+        end
+        private_class_method :edge_hash
+      end
+    end
+  end
+end

data/lib/archunit/graph/rendering/mermaid_renderer.rb ADDED Viewed

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+require_relative 'escaping'
+require_relative 'rendering_support'
+module ArchUnit
+  module GraphReporting
+    module Rendering
+      # Renders a Mermaid flowchart from a report snapshot.
+      module MermaidRenderer
+        module_function
+        def render(snapshot)
+          snapshot = RenderingSupport.validate_snapshot(snapshot)
+          ids = RenderingSupport.node_ids(snapshot)
+          lines = ["%% #{Escaping.single_line(snapshot.title)}", 'flowchart LR']
+          snapshot.nodes.each do |node|
+            lines << "  #{node.id}[\"#{Escaping.mermaid_label(node.label)}\"]"
+          end
+          snapshot.edges.each { |edge| lines << edge_line(edge, ids) }
+          lines.join("\n")
+        end
+        def edge_line(edge, ids)
+          arrow = edge.external ? '-.->' : '-->'
+          label = edge.count > 1 ? "|#{edge.count}|" : ''
+          "  #{ids.fetch(edge.source)} #{arrow}#{label} #{ids.fetch(edge.target)}"
+        end
+        private_class_method :edge_line
+      end
+    end
+  end
+end

data/lib/archunit/graph/rendering/rendering_support.rb ADDED Viewed

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+require_relative '../projection/graph_report_snapshot'
+module ArchUnit
+  module GraphReporting
+    module Rendering
+      # Shared validation for renderers that accept only completed snapshots.
+      module RenderingSupport
+        module_function
+        def validate_snapshot(value)
+          return value if value.is_a?(Projection::GraphReportSnapshot)
+          raise ArgumentError, 'snapshot must be a GraphReportSnapshot'
+        end
+        def node_ids(snapshot)
+          snapshot.nodes.to_h { |node| [node.label, node.id] }
+        end
+      end
+    end
+  end
+end

data/lib/archunit/layers/assertion/layer_definition.rb ADDED Viewed

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+require_relative '../../common/filter'
+require_relative '../../common/pattern_matching'
+module ArchUnit
+  module Layers
+    # Pure assertions over dependencies between named architectural layers.
+    module Assertion
+      # Immutable association between a layer name and its file selectors.
+      class LayerDefinition
+        attr_reader :name, :filters
+        def initialize(name:, filters:)
+          @name = layer_name(name)
+          @filters = filter_values(filters)
+          freeze
+        end
+        def matches?(file_path)
+          Common::PatternMatching.matches_any_pattern?(file_path, filters)
+        end
+        def with_filter(filter)
+          self.class.new(name:, filters: [*filters, filter])
+        end
+        def ==(other)
+          other.is_a?(self.class) && name == other.name && filters == other.filters
+        end
+        alias eql? ==
+        def hash
+          [self.class, name, filters].hash
+        end
+        private
+        def layer_name(value)
+          return value.dup.freeze if value.is_a?(String) && !value.strip.empty?
+          raise ArgumentError, 'name must be a non-empty String'
+        end
+        def filter_values(values)
+          filters = Array(values).dup
+          unless !filters.empty? && filters.all?(Common::Filter)
+            raise ArgumentError, 'filters must contain at least one Filter'
+          end
+          filters.freeze
+        end
+      end
+    end
+  end
+end

data/lib/archunit/layers/assertion/layer_dependencies.rb ADDED Viewed

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+require_relative '../../common/projection/projected_edge'
+require_relative 'layer_definition'
+require_relative 'layer_dependency_violation'
+module ArchUnit
+  module Layers
+    # Pure assertions over dependencies between named architectural layers.
+    module Assertion
+      module_function
+      def gather_layer_dependency_violations(
+        edges, layers, allowed_dependencies, forbidden_dependencies
+      )
+        validate_arguments(edges, layers, allowed_dependencies, forbidden_dependencies)
+        edges.filter_map do |edge|
+          dependency_violation(edge, layers, allowed_dependencies, forbidden_dependencies)
+        end
+      end
+      def dependency_violation(edge, layers, allowed_dependencies, forbidden_dependencies)
+        source_layer = find_layer(edge.source_label, layers)
+        target_layer = find_layer(edge.target_label, layers)
+        return unless source_layer && target_layer
+        return if source_layer.name == target_layer.name
+        rule = violated_rule(
+          source_layer.name, target_layer.name, allowed_dependencies, forbidden_dependencies
+        )
+        return unless rule
+        build_violation(edge, source_layer, target_layer, rule)
+      end
+      private_class_method :dependency_violation
+      def build_violation(edge, source_layer, target_layer, rule)
+        LayerDependencyViolation.new(
+          dependency: edge, source_layer: source_layer.name, target_layer: target_layer.name, rule:
+        )
+      end
+      private_class_method :build_violation
+      def violated_rule(source, target, allowed_dependencies, forbidden_dependencies)
+        forbidden_targets = forbidden_dependencies.fetch(source, [])
+        return :may_not_depend_on_layers if forbidden_targets.include?(target)
+        return unless allowed_dependencies.key?(source)
+        return if allowed_dependencies.fetch(source).include?(target)
+        :may_only_depend_on_layers
+      end
+      private_class_method :violated_rule
+      def find_layer(file_path, layers)
+        layers.find { |layer| layer.matches?(file_path) }
+      end
+      private_class_method :find_layer
+      def validate_arguments(edges, layers, allowed_dependencies, forbidden_dependencies)
+        unless edges.is_a?(Array) && edges.all?(Common::Projection::ProjectedEdge)
+          raise ArgumentError, 'edges must be an Array of ProjectedEdge values'
+        end
+        unless layers.is_a?(Array) && layers.all?(LayerDefinition)
+          raise ArgumentError, 'layers must be an Array of LayerDefinition values'
+        end
+        validate_dependency_map(allowed_dependencies, :allowed_dependencies)
+        validate_dependency_map(forbidden_dependencies, :forbidden_dependencies)
+      end
+      private_class_method :validate_arguments
+      def validate_dependency_map(value, attribute)
+        valid = value.is_a?(Hash) && value.all? do |source, targets|
+          valid_layer_name?(source) && targets.is_a?(Array) && targets.all? do |target|
+            valid_layer_name?(target)
+          end
+        end
+        return if valid
+        raise ArgumentError, "#{attribute} must map layer names to Arrays of layer names"
+      end
+      private_class_method :validate_dependency_map
+      def valid_layer_name?(value)
+        value.is_a?(String) && !value.strip.empty?
+      end
+      private_class_method :valid_layer_name?
+    end
+  end
+end

data/lib/archunit/layers/assertion/layer_dependency_violation.rb ADDED Viewed

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+require_relative '../../common/assertion/violation'
+require_relative '../../common/projection/projected_edge'
+module ArchUnit
+  module Layers
+    # Pure assertions over dependencies between named architectural layers.
+    module Assertion
+      # Data describing one cross-layer edge rejected by a layer policy.
+      class LayerDependencyViolation < Common::Assertion::Violation
+        RULES = %i[may_only_depend_on_layers may_not_depend_on_layers].freeze
+        attr_reader :dependency, :source_layer, :target_layer, :rule
+        def initialize(dependency:, source_layer:, target_layer:, rule:)
+          @dependency = projected_edge(dependency)
+          @source_layer = layer_name(source_layer, :source_layer)
+          @target_layer = layer_name(target_layer, :target_layer)
+          @rule = rule_value(rule)
+          super()
+        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_layer, target_layer, rule]
+        end
+        def projected_edge(value)
+          return value if value.is_a?(Common::Projection::ProjectedEdge)
+          raise ArgumentError, 'dependency must be a ProjectedEdge'
+        end
+        def layer_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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+require_relative '../../common/regex_factory'
+module ArchUnit
+  module Layers
+    module FluentApi
+      # Immutable stage defining which files belong to one named layer.
+      class LayerDefinitionBuilder
+        attr_reader :architecture, :layer_name
+        def initialize(architecture, layer_name)
+          @architecture = architecture_value(architecture)
+          @layer_name = layer_name_value(layer_name)
+          freeze
+        end
+        def defined_by(pattern, except: nil)
+          add_filter(Common::RegexFactory.path_matcher(pattern, except:))
+        end
+        def defined_by_folder(pattern, except: nil)
+          add_filter(Common::RegexFactory.folder_matcher(pattern, except:))
+        end
+        private
+        def add_filter(filter)
+          architecture.__send__(:with_layer_filter, layer_name, filter)
+        end
+        def architecture_value(value)
+          return value if value.is_a?(LayeredArchitecture)
+          raise ArgumentError, 'architecture must be a LayeredArchitecture'
+        end
+        def layer_name_value(value)
+          return value.dup.freeze if value.is_a?(String) && !value.strip.empty?
+          raise ArgumentError, 'layer_name must be a non-empty String'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+module ArchUnit
+  module Layers
+    module FluentApi
+      # Immutable stage adding an allowlist or blocklist policy for one layer.
+      class LayerDependencyRuleBuilder
+        attr_reader :architecture, :layer_name
+        def initialize(architecture, layer_name)
+          @architecture = architecture_value(architecture)
+          @layer_name = layer_name_value(layer_name)
+          freeze
+        end
+        def may_only_depend_on_layers(*layer_names)
+          architecture.__send__(:with_allowed_dependencies, layer_name, layer_names)
+        end
+        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'
+          end
+          architecture.__send__(:with_forbidden_dependencies, layer_name, layer_names)
+        end
+        private
+        def architecture_value(value)
+          return value if value.is_a?(LayeredArchitecture)
+          raise ArgumentError, 'architecture must be a LayeredArchitecture'
+        end
+        def layer_name_value(value)
+          return value.dup.freeze if value.is_a?(String) && !value.strip.empty?
+          raise ArgumentError, 'layer_name must be a non-empty String'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+require_relative '../../common/assertion/empty_test_violation'
+require_relative '../../common/fluentapi/checkable'
+require_relative '../../common/projection/edge_projections'
+require_relative '../../common/projection/project_edges'
+require_relative '../../common/projection/project_to_nodes'
+require_relative '../../extraction/extract_graph'
+require_relative '../assertion/layer_definition'
+require_relative '../assertion/layer_dependencies'
+require_relative 'layer_definition_builder'
+require_relative 'layer_dependency_rule_builder'
+require_relative 'layered_architecture_values'
+module ArchUnit
+  module Layers
+    module FluentApi
+      # Immutable, executable named-layer dependency policy.
+      class LayeredArchitecture
+        include Common::FluentApi::Checkable
+        include LayeredArchitectureValues
+        attr_reader :project_locator, :layer_definitions,
+                    :allowed_dependencies, :forbidden_dependencies
+        def initialize(
+          project_locator: nil, layer_definitions: [],
+          allowed_dependencies: {}, forbidden_dependencies: {}
+        )
+          @project_locator = immutable_project_locator(project_locator)
+          @layer_definitions = immutable_layer_definitions(layer_definitions)
+          @allowed_dependencies = immutable_dependency_map(allowed_dependencies)
+          @forbidden_dependencies = immutable_dependency_map(forbidden_dependencies)
+          freeze
+        end
+        def layer(name)
+          LayerDefinitionBuilder.new(self, validated_layer_name(name))
+        end
+        def where_layer(name)
+          name = validated_layer_name(name)
+          ensure_defined_layer!(name)
+          LayerDependencyRuleBuilder.new(self, name)
+        end
+        private
+        def with_layer_filter(name, filter)
+          definition = layer_definition(name)
+          updated = if definition
+                      replace_definition(definition, definition.with_filter(filter))
+                    else
+                      [*layer_definitions, Assertion::LayerDefinition.new(name:, filters: [filter])]
+                    end
+          copy(layer_definitions: updated)
+        end
+        def with_allowed_dependencies(source, targets)
+          targets = validated_target_layers(targets)
+          copy(allowed_dependencies: allowed_dependencies.merge(source => targets))
+        end
+        def with_forbidden_dependencies(source, targets)
+          targets = validated_target_layers(targets)
+          combined = [*forbidden_dependencies.fetch(source, []), *targets].uniq
+          copy(forbidden_dependencies: forbidden_dependencies.merge(source => combined))
+        end
+        def perform_check(options)
+          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)
+          empty_policy_violations(nodes, options) +
+            Assertion.gather_layer_dependency_violations(
+              edges, layer_definitions, allowed_dependencies, forbidden_dependencies
+            )
+        end
+        def empty_policy_violations(nodes, options)
+          return [] if options.allow_empty_tests?
+          policy_source_names.filter_map do |name|
+            definition = layer_definition(name)
+            next if nodes.any? { |node| definition.matches?(node.label) }
+            Common::Assertion::EmptyTestViolation.new(filters: definition.filters)
+          end
+        end
+        def policy_source_names
+          [*allowed_dependencies.keys, *forbidden_dependencies.keys].uniq
+        end
+        def copy(overrides = {})
+          self.class.new(
+            project_locator: overrides.fetch(:project_locator, project_locator),
+            layer_definitions: overrides.fetch(:layer_definitions, layer_definitions),
+            allowed_dependencies: overrides.fetch(:allowed_dependencies, allowed_dependencies),
+            forbidden_dependencies: overrides.fetch(:forbidden_dependencies, forbidden_dependencies)
+          )
+        end
+        def replace_definition(old_definition, new_definition)
+          layer_definitions.map do |definition|
+            definition.equal?(old_definition) ? new_definition : definition
+          end
+        end
+        def layer_definition(name)
+          layer_definitions.find { |definition| definition.name == name }
+        end
+        def ensure_defined_layer!(name)
+          return if layer_definition(name)
+          raise ArgumentError, "layer '#{name}' must be defined before it can have a policy"
+        end
+        def validated_target_layers(values)
+          names = Array(values).map { |value| validated_layer_name(value) }.uniq
+          undefined = names.reject { |name| layer_definition(name) }
+          unless undefined.empty?
+            raise ArgumentError, "undefined target layer: #{undefined.join(', ')}"
+          end
+          names
+        end
+      end
+    end
+  end
+end