archunit 0.0.1

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative '../../common/extraction/graph'
+require_relative 'aggregate_edges'
+require_relative 'collapse_node'
+require_relative 'graph_query_options'
+require_relative 'graph_report_snapshot'
+require_relative 'node_selection'
+
+module ArchUnit
+  module GraphReporting
+    module Projection
+      DEFAULT_TITLE = 'ArchUnitRuby Dependency Graph'
+
+      # Builds the one immutable representation consumed by every graph renderer.
+      class SnapshotFactory
+        class << self
+          def create(graph, options = nil)
+            validate_graph(graph)
+            options = GraphQueryOptions.resolve(options)
+            query_edges = external_query_edges(graph, options)
+            selected_nodes = NodeSelection.select(query_edges, options)
+            raw_edges = selected_edges(query_edges, selected_nodes, options)
+            report_edges = aggregate_edges(raw_edges, options)
+            report_nodes = build_nodes(selected_nodes, report_edges, options.collapse)
+
+            build_snapshot(options, report_nodes, report_edges, raw_edges)
+          end
+
+          private
+
+          def validate_graph(value)
+            return if value.is_a?(Common::Extraction::Graph)
+
+            raise ArgumentError, 'graph must be a Graph value'
+          end
+
+          def external_query_edges(graph, options)
+            return graph.to_a if options.include_external_dependencies
+
+            graph.reject(&:external)
+          end
+
+          def selected_edges(edges, selected_nodes, options)
+            edges.select do |edge|
+              (options.include_self_dependencies || edge.source != edge.target) &&
+                selected_nodes.include?(edge.source) && selected_nodes.include?(edge.target)
+            end
+          end
+
+          def aggregate_edges(raw_edges, options)
+            AggregateEdges.aggregate(
+              raw_edges,
+              collapse: options.collapse,
+              include_self_dependencies: options.include_self_dependencies
+            )
+          end
+
+          def build_nodes(selected_nodes, report_edges, collapse)
+            labels = selected_nodes.map { |node| CollapseNode.collapse(node, collapse) }
+            labels.concat(report_edges.flat_map { |edge| [edge.source, edge.target] })
+            labels.uniq.sort.each_with_index.map do |label, index|
+              GraphReportNode.new(id: "n#{index}", label:)
+            end.freeze
+          end
+
+          def build_snapshot(options, nodes, edges, raw_edges)
+            GraphReportSnapshot.new(
+              title: options.title || DEFAULT_TITLE,
+              nodes:, edges:,
+              summary: GraphReportSummary.new(
+                node_count: nodes.length, edge_count: edges.length,
+                raw_edge_count: raw_edges.length,
+                external_edge_count: raw_edges.count(&:external)
+              )
+            )
+          end
+        end
+
+        private_class_method :new
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module GraphReporting
+    module Projection
+      # Collapse file nodes to their folder path at a fixed depth.
+      FolderDepthCollapse = Data.define(:depth) do
+        def initialize(depth:)
+          unless depth.is_a?(Integer) && depth.positive?
+            raise ArgumentError, 'depth must be a positive Integer'
+          end
+
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative '../../common/filter'
+require_relative 'folder_depth_collapse'
+require_relative 'pattern_collapse'
+
+module ArchUnit
+  module GraphReporting
+    module Projection
+      # Immutable selection, collapsing, and presentation options for a graph snapshot.
+      GraphQueryOptions = Data.define(
+        :include_external_dependencies, :include_self_dependencies,
+        :focus, :focus_depth, :reachable_from, :dependents_of,
+        :collapse, :title
+      ) do
+        def self.resolve(value)
+          return new if value.nil?
+          return value if value.is_a?(self)
+
+          raise ArgumentError, 'options must be a GraphQueryOptions value or nil'
+        end
+
+        # The options bag deliberately mirrors the eight independent fluent modifiers.
+        # rubocop:disable Metrics/ParameterLists
+        def initialize(
+          include_external_dependencies: false, include_self_dependencies: false,
+          focus: nil, focus_depth: 1, reachable_from: nil, dependents_of: nil,
+          collapse: nil, title: nil
+        )
+          validate_boolean(include_external_dependencies, :include_external_dependencies)
+          validate_boolean(include_self_dependencies, :include_self_dependencies)
+          validate_filter(focus, :focus)
+          validate_focus_depth(focus_depth)
+          validate_filter(reachable_from, :reachable_from)
+          validate_filter(dependents_of, :dependents_of)
+          validate_collapse(collapse)
+          title = immutable_title(title)
+          super
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        def with(**overrides)
+          self.class.new(**to_h, **overrides)
+        end
+
+        private
+
+        def validate_boolean(value, attribute)
+          return if [true, false].include?(value)
+
+          raise ArgumentError, "#{attribute} must be true or false"
+        end
+
+        def validate_filter(value, attribute)
+          return if value.nil? || value.is_a?(Common::Filter)
+
+          raise ArgumentError, "#{attribute} must be a Filter or nil"
+        end
+
+        def validate_focus_depth(value)
+          return if value.is_a?(Integer) && !value.negative?
+
+          raise ArgumentError, 'focus_depth must be a non-negative Integer'
+        end
+
+        def validate_collapse(value)
+          return if value.nil? || value.is_a?(FolderDepthCollapse) || value.is_a?(PatternCollapse)
+
+          raise ArgumentError, 'collapse must be a graph collapse strategy or nil'
+        end
+
+        def immutable_title(value)
+          return if value.nil?
+          return value.dup.freeze if value.is_a?(String) && !value.strip.empty?
+
+          raise ArgumentError, 'title must be a non-empty String or nil'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative '../../common/extraction/import_kind'
+
+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: [])
+          source = immutable_string(source, :source)
+          target = immutable_string(target, :target)
+          validate_count(count)
+          validate_external(external)
+          import_kinds = immutable_import_kinds(import_kinds)
+          super
+        end
+
+        private
+
+        def immutable_string(value, attribute)
+          return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError, "#{attribute} must be a non-empty String"
+        end
+
+        def validate_count(value)
+          return if value.is_a?(Integer) && value.positive?
+
+          raise ArgumentError, 'count must be a positive Integer'
+        end
+
+        def validate_external(value)
+          return if [true, false].include?(value)
+
+          raise ArgumentError, 'external must be true or false'
+        end
+
+        def immutable_import_kinds(values)
+          kinds = Array(values).uniq.sort_by(&:to_s)
+          unless kinds.all? { |kind| Common::Extraction::ImportKind.valid?(kind) }
+            raise ArgumentError, 'import_kinds contains an unknown import kind'
+          end
+
+          kinds.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module GraphReporting
+    module Projection
+      # Stable node identity and display label in a graph report snapshot.
+      GraphReportNode = Data.define(:id, :label) do
+        def initialize(id:, label:)
+          super(id: immutable_string(id, :id), label: immutable_string(label, :label))
+        end
+
+        private
+
+        def immutable_string(value, attribute)
+          return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError, "#{attribute} must be a non-empty String"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'graph_report_edge'
+require_relative 'graph_report_node'
+require_relative 'graph_report_summary'
+
+module ArchUnit
+  module GraphReporting
+    module Projection
+      # Immutable graph after filtering, collapsing, aggregation, and counting.
+      GraphReportSnapshot = Data.define(:title, :nodes, :edges, :summary) do
+        def initialize(title:, nodes:, edges:, summary:)
+          title = immutable_title(title)
+          nodes = immutable_values(nodes, GraphReportNode, :nodes)
+          edges = immutable_values(edges, GraphReportEdge, :edges)
+          unless summary.is_a?(GraphReportSummary)
+            raise ArgumentError, 'summary must be a GraphReportSummary'
+          end
+
+          super
+        end
+
+        private
+
+        def immutable_title(value)
+          return value.dup.freeze if value.is_a?(String) && !value.strip.empty?
+
+          raise ArgumentError, 'title must be a non-empty String'
+        end
+
+        def immutable_values(values, type, attribute)
+          entries = Array(values).dup
+          unless entries.all?(type)
+            type_name = type.name.split('::').last
+            raise ArgumentError, "#{attribute} must contain only #{type_name} values"
+          end
+
+          entries.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module GraphReporting
+    module Projection
+      # Counts describing the selected and aggregated graph snapshot.
+      GraphReportSummary = Data.define(
+        :node_count, :edge_count, :raw_edge_count, :external_edge_count
+      ) do
+        def initialize(node_count:, edge_count:, raw_edge_count:, external_edge_count:)
+          values = { node_count:, edge_count:, raw_edge_count:, external_edge_count: }
+          invalid = values.find { |_name, value| !value.is_a?(Integer) || value.negative? }
+          raise ArgumentError, "#{invalid.first} must be a non-negative Integer" if invalid
+
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative '../../common/pattern_matching'
+
+module ArchUnit
+  module GraphReporting
+    module Projection
+      # Pure graph traversal for focus, reachability, and dependent queries.
+      module NodeSelection
+        module_function
+
+        def select(edges, options)
+          return all_nodes(edges) unless query?(options)
+
+          selected = Set.new
+          selected.merge(expand_focus(edges, options.focus, options.focus_depth)) if options.focus
+          selected.merge(walk(edges, options.reachable_from, :outgoing)) if options.reachable_from
+          selected.merge(walk(edges, options.dependents_of, :incoming)) if options.dependents_of
+          selected
+        end
+
+        def query?(options)
+          options.focus || options.reachable_from || options.dependents_of
+        end
+        private_class_method :query?
+
+        def all_nodes(edges)
+          edges.each_with_object(Set.new) do |edge, nodes|
+            nodes.add(edge.source).add(edge.target)
+          end
+        end
+        private_class_method :all_nodes
+
+        def expand_focus(edges, filter, depth)
+          selected = matching_nodes(edges, filter)
+          queue = selected.map { |node| [node, 0] }
+
+          until queue.empty?
+            current, current_depth = queue.shift
+            next if current_depth >= depth
+
+            add_neighbors(edges, current, current_depth, selected, queue)
+          end
+          selected
+        end
+        private_class_method :expand_focus
+
+        def add_neighbors(edges, current, current_depth, selected, queue)
+          neighbors_of(edges, current).each do |neighbor|
+            next if selected.include?(neighbor)
+
+            selected.add(neighbor)
+            queue << [neighbor, current_depth + 1]
+          end
+        end
+        private_class_method :add_neighbors
+
+        def walk(edges, filter, direction)
+          selected = matching_nodes(edges, filter)
+          queue = selected.to_a
+
+          until queue.empty?
+            current = queue.shift
+            add_next_nodes(edges, current, direction, selected, queue)
+          end
+          selected
+        end
+        private_class_method :walk
+
+        def add_next_nodes(edges, current, direction, selected, queue)
+          next_nodes(edges, current, direction).each do |node|
+            next if selected.include?(node)
+
+            selected.add(node)
+            queue << node
+          end
+        end
+        private_class_method :add_next_nodes
+
+        def matching_nodes(edges, filter)
+          all_nodes(edges).select do |node|
+            Common::PatternMatching.matches_pattern?(node, filter)
+          end.to_set
+        end
+        private_class_method :matching_nodes
+
+        def neighbors_of(edges, node)
+          edges.filter_map do |edge|
+            if edge.source == node && edge.target != node
+              edge.target
+            elsif edge.target == node && edge.source != node
+              edge.source
+            end
+          end.uniq
+        end
+        private_class_method :neighbors_of
+
+        def next_nodes(edges, node, direction)
+          edges.filter_map do |edge|
+            if direction == :outgoing && edge.source == node
+              edge.target
+            elsif direction == :incoming && edge.target == node
+              edge.source
+            end
+          end.uniq
+        end
+        private_class_method :next_nodes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ArchUnit
+  module GraphReporting
+    module Projection
+      # Collapse nodes by applying a regular-expression replacement.
+      PatternCollapse = Data.define(:regexp, :replacement) do
+        def initialize(regexp:, replacement: '\\1')
+          raise ArgumentError, 'regexp must be a Regexp' unless regexp.is_a?(Regexp)
+          raise ArgumentError, 'replacement must be a String' unless replacement.is_a?(String)
+
+          super(regexp: regexp.dup.freeze, replacement: replacement.dup.freeze)
+        end
+
+        def self.from(pattern, replacement = '\\1')
+          regexp = pattern.is_a?(String) ? Regexp.new(pattern) : pattern
+          new(regexp:, replacement:)
+        rescue RegexpError => e
+          raise ArgumentError, "invalid collapse pattern: #{e.message}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'csv'
+require_relative 'rendering_support'
+
+module ArchUnit
+  module GraphReporting
+    module Rendering
+      # Renders aggregated graph edges as standards-compliant CSV.
+      module CsvRenderer
+        HEADERS = %w[source target count external import_kinds].freeze
+
+        module_function
+
+        def render(snapshot)
+          snapshot = RenderingSupport.validate_snapshot(snapshot)
+          CSV.generate(row_sep: "\n") do |csv|
+            csv << HEADERS
+            snapshot.edges.each do |edge|
+              csv << [
+                edge.source, edge.target, edge.count, edge.external,
+                edge.import_kinds.join('|')
+              ]
+            end
+          end.rstrip
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'escaping'
+require_relative 'rendering_support'
+
+module ArchUnit
+  module GraphReporting
+    module Rendering
+      # Renders D2 diagram source from a report snapshot.
+      module D2Renderer
+        module_function
+
+        def render(snapshot)
+          snapshot = RenderingSupport.validate_snapshot(snapshot)
+          lines = ["# #{Escaping.single_line(snapshot.title)}"]
+          snapshot.nodes.each { |node| lines << Escaping.quoted(node.label) }
+          snapshot.edges.each { |edge| lines << edge_line(edge) }
+          lines.join("\n")
+        end
+
+        def edge_line(edge)
+          label = edge.count > 1 ? ": #{Escaping.quoted(edge.count.to_s)}" : ''
+          style = edge.external ? ' { style.stroke-dash: 4 }' : ''
+          "#{Escaping.quoted(edge.source)} -> #{Escaping.quoted(edge.target)}#{label}#{style}"
+        end
+        private_class_method :edge_line
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'escaping'
+require_relative 'rendering_support'
+
+module ArchUnit
+  module GraphReporting
+    module Rendering
+      # Renders a Graphviz DOT directed graph from a report snapshot.
+      module DotRenderer
+        module_function
+
+        def render(snapshot)
+          snapshot = RenderingSupport.validate_snapshot(snapshot)
+          lines = header(snapshot)
+          snapshot.nodes.each { |node| lines << "  #{Escaping.quoted(node.label)};" }
+          snapshot.edges.each { |edge| lines << edge_line(edge) }
+          lines << '}'
+          lines.join("\n")
+        end
+
+        def header(snapshot)
+          [
+            'digraph dependencies {',
+            '  rankdir=LR;',
+            "  label=#{Escaping.quoted(snapshot.title)};",
+            '  labelloc=t;'
+          ]
+        end
+        private_class_method :header
+
+        def edge_line(edge)
+          attributes = edge_attributes(edge)
+          suffix = attributes.empty? ? '' : " [#{attributes.join(', ')}]"
+          "  #{Escaping.quoted(edge.source)} -> #{Escaping.quoted(edge.target)}#{suffix};"
+        end
+        private_class_method :edge_line
+
+        def edge_attributes(edge)
+          attributes = []
+          attributes << "label=#{Escaping.quoted(edge.count.to_s)}" if edge.count > 1
+          attributes << 'style=dashed' if edge.external
+          return attributes if edge.import_kinds.empty?
+
+          attributes << "tooltip=#{Escaping.quoted(edge.import_kinds.join(', '))}"
+        end
+        private_class_method :edge_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'cgi/escape'
+
+module ArchUnit
+  module GraphReporting
+    module Rendering
+      # Format-specific escaping kept out of the renderers' graph logic.
+      module Escaping
+        module_function
+
+        def quoted(value)
+          escaped = value.gsub('\\', '\\\\').gsub('"', '\\"').gsub("\n", '\\n')
+          "\"#{escaped}\""
+        end
+
+        def mermaid_label(value)
+          CGI.escapeHTML(value).gsub("\n", '<br/>')
+        end
+
+        def html(value)
+          CGI.escapeHTML(value.to_s)
+        end
+
+        def single_line(value)
+          value.gsub(/[\r\n]+/, ' ')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module ArchUnit
+  module GraphReporting
+    module Rendering
+      # UTF-8 file export shared by every graph report format.
+      module ExportReport
+        module_function
+
+        def write(output_path, content)
+          path = normalized_path(output_path)
+          FileUtils.mkdir_p(File.dirname(path)) unless File.dirname(path) == '.'
+          File.binwrite(path, content.encode(Encoding::UTF_8))
+          nil
+        end
+
+        def normalized_path(value)
+          value = value.to_path if value.respond_to?(:to_path)
+          return value if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError, 'output_path must be a non-empty path'
+        end
+        private_class_method :normalized_path
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'csv_renderer'
+require_relative 'd2_renderer'
+require_relative 'dot_renderer'
+require_relative 'export_report'
+require_relative 'html_renderer'
+require_relative 'json_renderer'
+require_relative 'mermaid_renderer'
+
+module ArchUnit
+  module GraphReporting
+    module Rendering
+      # One dispatch point for every renderer consuming the shared snapshot.
+      class GraphRenderer
+        RENDERERS = {
+          dot: DotRenderer, mermaid: MermaidRenderer, d2: D2Renderer,
+          csv: CsvRenderer, json: JsonRenderer, html: HtmlRenderer
+        }.freeze
+
+        class << self
+          def render(snapshot, format)
+            renderer(format).render(snapshot)
+          end
+
+          def export(snapshot, format, output_path)
+            ExportReport.write(output_path, render(snapshot, format))
+          end
+
+          RENDERERS.each_key do |format|
+            define_method("to_#{format}") do |snapshot|
+              render(snapshot, format)
+            end
+
+            define_method("export_as_#{format}") do |snapshot, output_path|
+              export(snapshot, format, output_path)
+            end
+          end
+
+          private
+
+          def renderer(format)
+            key = format.respond_to?(:to_sym) ? format.to_sym : format
+            RENDERERS.fetch(key)
+          rescue KeyError
+            raise ArgumentError, "unknown graph report format: #{format.inspect}"
+          end
+        end
+
+        private_class_method :new
+      end
+    end
+  end
+end