lutaml-graphviz 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2f8d38e9554f3ba105ab977a65c8fae46fa9bc9a75b66548dcd0cfa9bc8ee96d
+  data.tar.gz: 6734497fb339f562370efd5415af737ea9cf5bf8a5748efbbea36061f723eb32
+SHA512:
+  metadata.gz: 6f382d5798769a1a90a5b70c71db72f278d1f9750a1227ae4084e9e435f64bfd53a1b701d8bab464d504e6a7bbfa20f416aeb167eba7f390dc0ae052baad6721
+  data.tar.gz: 63f8b3eeb80e2262110ed15a18a5b15a2dce97060519c8727a2657149b5db83c852f417a05ba5b6af0335e3080ae8bf413fd3a09eb140543fb5624a0ddc2e50e

data/lib/lutaml/graphviz/formatter/graphviz/document_formatter.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Formatter
+    class Graphviz < Base
+      module DocumentFormatter
+        def format_document(node)
+          @fontname = node.fontname || DEFAULT_CLASS_FONT
+          @node["fontname"] = "#{@fontname}-bold"
+
+          hide_members, hide_other_classes = extract_fidelity_options(node)
+          classes = format_all_classes(node, hide_members)
+          associations = build_associations(node, hide_other_classes)
+
+          build_digraph(classes, associations)
+        end
+
+        def extract_fidelity_options(node)
+          if node.fidelity
+            [node.fidelity.hideMembers, node.fidelity.hideOtherClasses]
+          else
+            [nil, nil]
+          end
+        end
+
+        def format_all_classes(node, hide_members)
+          node.all_classes.map do |class_node|
+            graph_node_name = generate_graph_name(class_node.name)
+            <<~HEREDOC
+              #{graph_node_name} [
+                shape="plain"
+                fontname="#{@fontname || DEFAULT_CLASS_FONT}"
+                label=<#{format_class(class_node, hide_members)}>]
+            HEREDOC
+          end.join("\n")
+        end
+
+        def build_associations(node, hide_other_classes)
+          associations = collect_all_associations(node)
+          associations = sort_by_document_grouping(node.groups, associations) if node.groups
+          classes_names = node.classes.map(&:name)
+          format_filtered_associations(associations, classes_names, hide_other_classes)
+        end
+
+        def collect_all_associations(node)
+          class_level = node.classifiable_classes
+          Set.new
+          all = class_level.filter_map(&:associations).flatten + node.associations
+          all.uniq { |a| association_key(a) }
+        end
+
+        def format_filtered_associations(associations, classes_names, hide_other_classes)
+          associations.filter_map do |assoc_node|
+            next if hide_other_classes && !classes_names.include?(assoc_node.member_end)
+
+            format_relationship(assoc_node)
+          end.join("\n")
+        end
+
+        def build_digraph(classes, associations)
+          indented_classes = indent_lines(classes)
+          indented_assocs = indent_lines(associations)
+
+          <<~HEREDOC
+            digraph G {
+              graph [#{@graph}]
+              edge [#{@edge}]
+              node [#{@node}]
+
+            #{indented_classes}
+
+            #{indented_assocs}
+            }
+          HEREDOC
+        end
+
+        def indent_lines(text)
+          text.lines.map { |line| "  #{line}" }.join.chomp
+        end
+
+        private
+
+        def association_key(assoc)
+          [assoc.owner_end.to_s, assoc.member_end.to_s, assoc.name.to_s]
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/graphviz/formatter/graphviz/html_builder.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Formatter
+    class Graphviz < Base
+      module HtmlBuilder
+        EMPTY_MEMBER_TABLE = <<~HEREDOC.chomp
+          <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0">
+            <TR><TD ALIGN="LEFT"></TD></TR>
+          </TABLE>
+        HEREDOC
+
+        def escape_html_chars(text)
+          text
+            .gsub("&", "&amp;")
+            .gsub("<", "&#60;")
+            .gsub(">", "&#62;")
+            .gsub("[", "&#91;")
+            .gsub("]", "&#93;")
+        end
+
+        def format_member_rows(members, hide_members, &formatter)
+          return EMPTY_MEMBER_TABLE if hide_members || !members&.any?
+
+          formatter ||= method(:dispatch_format)
+          field_rows = members.map do |member|
+            %(<TR><TD ALIGN="LEFT">#{formatter.call(member)}</TD></TR>)
+          end
+          build_member_table(field_rows)
+        end
+
+        def format_enum_member(member)
+          enum_literal?(member) ? format_enum_literal(member) : dispatch_format(member)
+        end
+
+        def enum_literal?(node)
+          node.is_a?(Lml::TopElementAttribute) &&
+            node.type.nil? && node.cardinality.nil?
+        end
+
+        def build_member_table(field_rows)
+          indented = field_rows.map { |row| (" " * 10) + row }.join("\n")
+          <<~HEREDOC.chomp
+            <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0">
+              #{indented}
+            </TABLE>
+          HEREDOC
+                    .concat("\n")
+                    .concat(" " * 6)
+        end
+
+        def build_name_table(name_parts)
+          <<~HEREDOC
+            <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0">
+              #{name_parts.map { |n| %(<TR><TD ALIGN="CENTER">#{n}</TD></TR>) }.join("\n")}
+            </TABLE>
+          HEREDOC
+        end
+
+        def build_table_body(name_html, field_table, method_table)
+          [name_html, field_table, method_table].compact.filter_map do |type|
+            <<~TEXT
+              <TR>
+                <TD>#{type}</TD>
+              </TR>
+            TEXT
+          end.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/graphviz/formatter/graphviz/node_formatter.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Formatter
+    class Graphviz < Base
+      module NodeFormatter
+        ACCESS_SYMBOLS = {
+          "public" => "+",
+          "protected" => "#",
+          "private" => "-",
+          "package" => "~"
+        }.freeze
+
+        def format_attribute(node)
+          symbol = ACCESS_SYMBOLS[node.visibility]
+          result = "#{symbol}#{node.name}"
+          if node.type
+            stereotype = node.stereotype.empty? ? "" : node.stereotype.map { |s| "«#{s}»" }.join
+            result += " : #{stereotype}#{node.type}"
+          end
+          result += format_cardinality_bounds(node.cardinality) if node.cardinality
+          result = escape_html_chars(result)
+          result = "<U>#{result}</U>" if node.static
+          result
+        end
+
+        def format_cardinality_bounds(cardinality)
+          min = cardinality.min || "*"
+          max = cardinality.max || "*"
+          "[#{min}..#{max}]"
+        end
+
+        def format_operation(node)
+          symbol = ACCESS_SYMBOLS[node.visibility]
+          params = format_operation_params(node.owned_parameter)
+          result = "#{symbol} #{node.name}(#{params})"
+          result << " : #{node.return_type}" if node.return_type
+          result = escape_html_chars(result)
+          result = "<U>#{result}</U>" if node.is_static
+          result = "<I>#{result}</I>" if node.is_abstract
+          result
+        end
+
+        def format_operation_params(params)
+          return "" unless params&.any?
+
+          params.map do |param|
+            param.type ? "#{param.name} : #{param.type}" : param.name.to_s
+          end.join(", ")
+        end
+
+        # Kind labels rendered above the name: guillemet stereotypes first,
+        # then the entity-kind label (enums/data types/primitives carry no
+        # user stereotypes of their own in the grammar).
+        KIND_LABELS = {
+          enums: "enumeration",
+          data_types: "dataType",
+          primitives: "primitive"
+        }.freeze
+
+        def format_class(node, hide_members = nil)
+          name = ["<B>#{escape_html_chars(node.name)}</B>"]
+          node.stereotype.each do |stereotype|
+            name.unshift("«#{escape_html_chars(stereotype)}»")
+          end
+          if (kind = KIND_LABELS[node.class.entity_type])
+            name.unshift("«#{kind}»")
+          end
+          name_html = build_name_table(name)
+
+          member_formatter = node.is_a?(Lml::Enum) ? method(:format_enum_member) : nil
+          field_table = format_member_rows(node.attributes, hide_members, &member_formatter)
+          method_table = format_member_rows(node.operations, hide_members) if node.operations&.any?
+          table_body = build_table_body(name_html, field_table, method_table)
+
+          <<~HEREDOC.chomp
+            <TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="10">
+              #{table_body}
+            </TABLE>
+          HEREDOC
+        end
+
+        def format_enum_literal(node)
+          "<I>#{escape_html_chars(node.name.to_s)}</I>"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/graphviz/formatter/graphviz/relationship_formatter.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Formatter
+    class Graphviz < Base
+      module RelationshipFormatter
+        ARROW_TYPES = {
+          "composition" => "diamond",
+          "aggregation" => "odiamond",
+          "direct" => "vee"
+        }.freeze
+
+        DASHED_TYPES = %w[dependency realizes].freeze
+
+        DIRECTION_LABELS = {
+          "target" => "%s ▶",
+          "source" => "◀ %s"
+        }.freeze
+
+        def format_relationship(node)
+          graph_parent_name = generate_graph_name(node.owner_end)
+          graph_node_name = generate_graph_name(node.member_end)
+          attributes = build_edge_attributes(node)
+          graph_attributes = " [#{attributes}]" unless attributes.empty?
+
+          "#{graph_parent_name} -> #{graph_node_name}#{graph_attributes}"
+        end
+
+        def build_edge_attributes(node)
+          attrs = Attributes.new
+
+          apply_edge_style(attrs, node)
+          apply_edge_direction(attrs, node)
+          apply_edge_labels(attrs, node)
+          apply_arrow_types(attrs, node)
+          maybe_swap_labels(attrs)
+
+          attrs
+        end
+
+        def format_label(name, cardinality = nil)
+          res = "+#{name}"
+          return res if cardinality.nil? || cardinality.min.nil? || cardinality.max.nil?
+
+          "#{res} #{cardinality.min}..#{cardinality.max}"
+        end
+
+        private
+
+        def sort_by_document_grouping(groups, associations)
+          result = []
+          seen = Set.new
+
+          groups.each do |group|
+            group.values.each do |group_name| # rubocop:disable Style/HashEachMethods
+              matches = associations.select { |a| a.owner_end == group_name }
+              matches.each { |a| add_unseen(a, result, seen) }
+            end
+          end
+          associations.each { |a| add_unseen(a, result, seen) }
+          result
+        end
+
+        def add_unseen(association, result, seen)
+          return if seen.include?(association)
+
+          result.push(association)
+          seen.add(association)
+        end
+
+        def apply_edge_style(attrs, node)
+          attrs["style"] = "dashed" if DASHED_TYPES.include?(node.member_end_type)
+        end
+
+        def apply_edge_direction(attrs, node)
+          attrs["dir"] = if node.owner_end_type && node.member_end_type
+                           "both"
+                         elsif node.owner_end_type
+                           "back"
+                         else
+                           "direct"
+                         end
+        end
+
+        def apply_edge_labels(attrs, node)
+          apply_verb_label(attrs, node)
+          apply_direction_label(attrs, node)
+          apply_endpoint_labels(attrs, node)
+        end
+
+        def apply_verb_label(attrs, node)
+          attrs["label"] = node.action.verb if node&.action&.verb
+        end
+
+        def apply_direction_label(attrs, node)
+          return unless node&.action&.direction
+
+          template = DIRECTION_LABELS[node.action.direction]
+          attrs["label"] = template % attrs["label"] if template
+        end
+
+        def apply_endpoint_labels(attrs, node)
+          if node.owner_end_attribute_name
+            attrs["headlabel"] = format_label(
+              node.owner_end_attribute_name, node.owner_end_cardinality
+            )
+          end
+
+          return unless node.member_end_attribute_name
+
+          attrs["taillabel"] = format_label(
+            node.member_end_attribute_name, node.member_end_cardinality
+          )
+        end
+
+        def apply_arrow_types(attrs, node)
+          attrs["arrowtail"] = ARROW_TYPES.fetch(node.owner_end_type, "onormal")
+          attrs["arrowhead"] = ARROW_TYPES.fetch(node.member_end_type, "onormal")
+        end
+
+        def maybe_swap_labels(attrs)
+          return unless attrs["dir"] == "back" && attrs["arrowtail"] != "vee"
+
+          attrs["arrowhead"], attrs["arrowtail"] = [attrs["arrowtail"], attrs["arrowhead"]]
+          attrs["headlabel"], attrs["taillabel"] = [attrs["taillabel"], attrs["headlabel"]]
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/graphviz/formatter/graphviz.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "open3"
+require "set"
+
+module Lutaml
+  module Formatter
+    class Graphviz < Base
+      autoload :HtmlBuilder, "lutaml/graphviz/formatter/graphviz/html_builder"
+      autoload :NodeFormatter, "lutaml/graphviz/formatter/graphviz/node_formatter"
+      autoload :RelationshipFormatter, "lutaml/graphviz/formatter/graphviz/relationship_formatter"
+      autoload :DocumentFormatter, "lutaml/graphviz/formatter/graphviz/document_formatter"
+
+      include HtmlBuilder
+      include NodeFormatter
+      include RelationshipFormatter
+      include DocumentFormatter
+
+      class Attributes < Hash
+        def to_s
+          to_a
+            .reject { |(_k, val)| val.nil? }
+            .map { |(a, b)| "#{a}=#{b.inspect}" }
+            .join(" ")
+        end
+      end
+
+      DEFAULT_CLASS_FONT = "Helvetica"
+
+      VALID_TYPES = %i[
+        dot xdot ps pdf svg svgz fig png gif jpg jpeg json imap cmapx
+      ].freeze
+
+      def initialize(attributes = {})
+        super
+        setup_default_attributes
+        @type = :dot
+      end
+
+      attr_reader :graph, :edge, :node
+
+      def type=(value)
+        super
+        @type = :dot unless VALID_TYPES.include?(@type)
+      end
+
+      def format(node)
+        dot = super.lines.map(&:rstrip).join("\n")
+        generate_from_dot(dot)
+      end
+
+      def setup_default_attributes
+        @graph = build_graph_attrs
+        @edge = build_edge_attrs
+        @node = build_node_attrs
+      end
+
+      def build_graph_attrs
+        Attributes.new.tap do |g|
+          g["splines"] = "ortho"
+          g["pad"] = "0.5"
+          g["ranksep"] = "1.2"
+          g["nodesep"] = "1.2"
+          g["rankdir"] = "BT"
+        end
+      end
+
+      def build_edge_attrs
+        Attributes.new.tap { |e| e["color"] = "gray50" }
+      end
+
+      def build_node_attrs
+        Attributes.new.tap { |n| n["shape"] = "box" }
+      end
+
+      private :setup_default_attributes, :build_graph_attrs,
+              :build_edge_attrs, :build_node_attrs
+
+      protected
+
+      def generate_from_dot(input)
+        Lutaml::Layout::GraphVizEngine.new(input: input).render(@type)
+      end
+
+      def generate_graph_name(name)
+        name.gsub(/[^0-9a-zA-Z]/i, "")
+      end
+    end
+  end
+end

data/lib/lutaml/graphviz/layout/graph_viz_engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "ruby-graphviz"
+require "open3"
+
+module Lutaml
+  module Layout
+    class GraphVizEngine < Engine
+      def render(type)
+        Open3.popen3("dot", "-T#{type}") do |stdin, stdout, _stderr, _wait|
+          stdout.binmode
+          stdin.puts(input)
+          stdin.close
+          stdout.read
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/graphviz/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Graphviz
+    VERSION = "0.1.0"
+  end
+end

data/lib/lutaml/graphviz.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "lutaml/lml"
+require_relative "graphviz/version"
+
+module Lutaml
+  # Graphviz diagram rendering for LutaML models. The renderers register
+  # themselves against the model-driven formatter registry owned by
+  # lutaml (Lutaml::Formatter.all / .find_by_name), so requiring this file
+  # is all a consumer does to make the `graphviz` formatter available.
+  # ruby-graphviz and the `dot` toolchain live in this gem only.
+  module Graphviz
+    class Error < Lutaml::Error; end
+  end
+
+  module Formatter
+    autoload :Graphviz, "lutaml/graphviz/formatter/graphviz"
+  end
+
+  module Layout
+    autoload :GraphVizEngine, "lutaml/graphviz/layout/graph_viz_engine"
+  end
+end
+
+# Force the autoload so the formatter registers in Lutaml::Formatter.all
+# as soon as the gem is required.
+Lutaml::Formatter::Graphviz

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: lutaml-graphviz
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ribose Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lutaml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby-graphviz
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Renders LutaML (LML) documents as Graphviz diagrams. Owns the ruby-graphviz
+  dependency so the lutaml core gemspecs never carry an optional render toolchain.
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/lutaml/graphviz.rb
+- lib/lutaml/graphviz/formatter/graphviz.rb
+- lib/lutaml/graphviz/formatter/graphviz/document_formatter.rb
+- lib/lutaml/graphviz/formatter/graphviz/html_builder.rb
+- lib/lutaml/graphviz/formatter/graphviz/node_formatter.rb
+- lib/lutaml/graphviz/formatter/graphviz/relationship_formatter.rb
+- lib/lutaml/graphviz/layout/graph_viz_engine.rb
+- lib/lutaml/graphviz/version.rb
+homepage: https://github.com/lutaml/lutaml-graphviz
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/lutaml/lutaml-graphviz
+  source_code_uri: https://github.com/lutaml/lutaml-graphviz
+  changelog_uri: https://github.com/lutaml/lutaml-graphviz/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: Graphviz diagram rendering for LutaML models
+test_files: []