seafoam 0.2

data/lib/seafoam/config.rb

@@ -0,0 +1,34 @@
+module Seafoam
+  # Finds and loads configuration.
+  class Config
+    def initialize
+      @dot_dir = find_dot_dir
+    end
+
+    # Load the configuration.
+    def load_config
+      config_file = File.expand_path('config', @dot_dir)
+      if File.exist?(config_file)
+        puts "loading config #{config_file}" if $DEBUG
+        load config_file
+      end
+    end
+
+    private
+
+    # Walk up the directory chain from the current directory to root, looking
+    # for .seafoam.
+    def find_dot_dir
+      dir = Dir.getwd
+      loop do
+        dot_dir = File.expand_path('.seafoam', dir)
+        return dot_dir if Dir.exist?(dot_dir)
+
+        new_dir = File.expand_path('..', dir)
+        break if new_dir == dir
+
+        dir = new_dir
+      end
+    end
+  end
+end

data/lib/seafoam/graph.rb

@@ -0,0 +1,91 @@
+module Seafoam
+  # A graph, with properties, nodes, and edges. We don't encapsulate the graph
+  # too much - be careful.
+  class Graph
+    attr_reader :props, :nodes, :edges
+
+    def initialize(props = nil)
+      @props = props || {}
+      @nodes = {}
+      @edges = []
+    end
+
+    # Create a node.
+    def create_node(id, props = nil)
+      props ||= {}
+      node = Node.new(id, props)
+      @nodes[id] = node
+      node
+    end
+
+    # Create an edge between two nodes.
+    def create_edge(from, to, props = nil)
+      props ||= {}
+      edge = Edge.new(from, to, props)
+      @edges.push edge
+      from.outputs.push edge
+      to.inputs.push edge
+      edge
+    end
+  end
+
+  # A node, with properties, input edges, and output edges.
+  class Node
+    attr_reader :id, :inputs, :outputs, :props
+
+    def initialize(id, props = nil)
+      props ||= {}
+      @id = id
+      @inputs = []
+      @outputs = []
+      @props = props
+    end
+
+    # All edges - input and output.
+    def edges
+      inputs + outputs
+    end
+
+    # All adjacent nodes - from input and output edges.
+    def adjacent
+      (inputs.map(&:from) + outputs.map(&:to)).uniq
+    end
+
+    # id (label)
+    def id_and_label
+      if props[:label]
+        "#{id} (#{props[:label]})"
+      else
+        id.to_s
+      end
+    end
+
+    # Inspect.
+    def inspect
+      "<Node #{id}>"
+    end
+  end
+
+  # A directed edge, with a node it's from and a node it's going to, and
+  # properties.
+  class Edge
+    attr_reader :from, :to, :props
+
+    def initialize(from, to, props = nil)
+      props ||= {}
+      @from = from
+      @to = to
+      @props = props
+    end
+
+    # Both nodes - from and to.
+    def nodes
+      [@from, @to]
+    end
+
+    # Inspect.
+    def inspect
+      "<Edge #{from.id} -> #{to.id}>"
+    end
+  end
+end

data/lib/seafoam/graphviz_writer.rb

@@ -0,0 +1,213 @@
+module Seafoam
+  # A writer from graphs to the Graphviz DOT format, including all the
+  # formatting.
+  class GraphvizWriter
+    def initialize(stream)
+      @stream = stream
+    end
+
+    # Write a graph.
+    def write_graph(graph, hidpi = false)
+      inline_attrs = {}
+      attrs = {}
+      attrs[:dpi] = 200 if hidpi
+      attrs[:bgcolor] = 'transparent'
+      @stream.puts 'digraph G {'
+      @stream.puts "  graph #{write_attrs(attrs)};"
+      write_nodes inline_attrs, graph
+      write_edges inline_attrs, graph
+      @stream.puts '}'
+    end
+
+    private
+
+    # Write node declarations.
+    def write_nodes(inline_attrs, graph)
+      graph.nodes.each_value do |node|
+        write_node inline_attrs, node
+      end
+    end
+
+    def write_node(inline_attrs, node)
+      # We're going to build up a hash of Graphviz drawing attributes.
+      attrs = {}
+
+      # The node is hidden, and it's not going to be inlined above any
+      # other node.
+      if node.props[:hidden] && !node.props[:inlined]
+        # If the node has any adjacent nodes that are not hidden, and are
+        # shaded, then we need to declare the node but make it invisible so
+        # the edge appears, pointing off into space, but the node does not.
+        if node.adjacent.any? { |a| !a.props[:hidden] && a.props[:spotlight] == 'shaded' }
+          attrs[:style] = 'invis'
+          attrs[:label] = ''
+          @stream.puts "  node#{node.id} #{write_attrs(attrs)};"
+        end
+      else
+        # This is a visible node.
+
+        # Give it a label.
+        if node.props[:label]
+          attrs[:label] = "#{node.id} #{node.props[:label]}"
+        else
+          # If we really still don't have a label, just use the ID.
+          attrs[:label] = node.id.to_s
+        end
+
+        # Basic attributes for a node.
+        attrs[:shape] = 'rectangle'
+        attrs[:fontname] = 'Arial'
+        attrs[:style] = 'filled'
+        attrs[:color] = 'black'
+
+        # Color depends on the kind of node.
+        back_color, fore_color = NODE_COLORS[node.props[:kind]]
+        attrs[:fillcolor] = back_color
+        attrs[:fontcolor] = fore_color
+
+        if node.props[:inlined]
+          # If the node is to be inlined then draw it smaller and a different
+          # shape.
+          attrs[:shape] = 'oval'
+          attrs[:fontsize] = '8'
+
+          # Just record these attributes for where it's used by other nodes
+          # so it can be drawn above them - don't actually declare a node.
+          inline_attrs[node.id] = attrs
+        else
+          attrs[:shape] = 'diamond' if node.props[:kind] == 'calc'
+
+          # If the node is shaded, convert the attributes to the shaded
+          # version.
+          attrs = shade(attrs) if node.props[:spotlight] == 'shaded'
+
+          # Declare the node.
+          @stream.puts "  node#{node.id} #{write_attrs(attrs)};"
+        end
+      end
+    end
+
+    # Write edge declarations.
+
+    def write_edges(inline_attrs, graph)
+      graph.edges.each do |edge|
+        # Skip the edge if it's from a node that is hidden and it doesn't point
+        # to a shaded node.
+        next if edge.from.props[:hidden] && edge.to.props[:spotlight] != 'shaded'
+
+        # Skip the edge if it's to a node that is hidden and it doesn't come
+        # from a shaded node.
+        next if edge.to.props[:hidden] && edge.from.props[:spotlight] != 'shaded'
+
+        write_edge inline_attrs, edge
+      end
+    end
+
+    def write_edge(inline_attrs, edge)
+      # We're going to build up a hash of Graphviz drawing attributes.
+      attrs = {}
+
+      label = edge.props[:label]
+      if edge.from.props[:out_annotation]
+        label = "#{label} #{edge.from.props[:out_annotation]}"
+      end
+      attrs[:label] = label
+
+      # Basic edge attributes.
+      attrs[:fontname] = 'arial'
+      color = EDGE_COLORS[edge.props[:kind]]
+      attrs[:color] = EDGE_COLORS[edge.props[:kind]]
+      attrs[:fontcolor] = color
+
+      # Properties depending on the kind of edge.
+      case edge.props[:kind]
+      when 'control'
+        attrs[:penwidth] = 2
+      when 'loop'
+        attrs[:penwidth] = 4
+      when 'info'
+        attrs[:style] = 'dashed'
+      end
+
+      # Reversed edges.
+      attrs[:dir] = 'back' if edge.props[:reverse]
+
+      # Convert attributes to shaded if any edges involved are shaded.
+      attrs = shade(attrs) if edge.nodes.any? { |n| n.props[:spotlight] == 'shaded' }
+
+      # Does this edge come from an inlined node?
+
+      if edge.from.props[:inlined]
+        # An inlined edge is drawn as a new version of the from-node and an
+        # edge from that new version directly to the to-node. With only one
+        # user it's a short edge and the from-node is show directly above the
+        # to-node.
+
+        if edge.to.props[:spotlight] == 'shaded'
+          # Draw inlined edges to shaded nodes as invisible.
+          node_attrs = { label: '', style: 'invis' }
+        else
+          # Get attributes from when we went through nodes earlier.
+          node_attrs = inline_attrs[edge.from.id]
+        end
+
+        # Inlined nodes skip the arrow for simplicity.
+        attrs[:arrowhead] = 'none'
+        attrs[:fontsize] = '8'
+
+        # Declare a new node just for this user.
+        @stream.puts "  inline#{edge.from.id}x#{edge.to.id} #{write_attrs(node_attrs)};"
+
+        # Declare the edge.
+        @stream.puts "  inline#{edge.from.id}x#{edge.to.id} -> node#{edge.to.id} #{write_attrs(attrs)};"
+      else
+        # Declare the edge.
+        @stream.puts "  node#{edge.from.id} -> node#{edge.to.id} #{write_attrs(attrs)};"
+      end
+    end
+
+    # Return attributes for a node or edge modified to 'shade' them in terms
+    # the spotlight functionality - so basically make them light grey.
+    def shade(attrs)
+      attrs = attrs.dup
+      attrs[:color] = ICE_STONE
+      attrs[:fontcolor] = ICE_STONE
+      attrs[:fillcolor] = DUST
+      attrs
+    end
+
+    # Write a hash of key-value attributes into the DOT format.
+    def write_attrs(attrs)
+      '[' + attrs.reject { |_k, v| v.nil? }.map { |k, v| "#{k}=#{quote(v)}" }.join(',') + ']'
+    end
+
+    # Quote and escape a string.
+    def quote(string)
+      string = string.to_s
+      string = string.gsub('\\', '\\\\')
+      string = string.gsub('"', '\\"')
+      "\"#{string}\""
+    end
+
+    # Color theme.
+
+    EDGE_COLORS = {
+      'info' => BIG_STONE,
+      'control' => AMARANTH,
+      'loop' => AMARANTH,
+      'data' => KEPPEL,
+      'other' => BLACK
+    }
+
+    NODE_COLORS = {
+      'info' => [DUST, BLACK],
+      'input' => [WHITE_ICE, BLACK],
+      'control' => [CARISSMA, BLACK],
+      'effect' => [AMARANTH, WHITE],
+      'virtual' => [BIG_STONE, WHITE],
+      'guard' => [ORANGE, BLACK],
+      'calc' => [KEPPEL, BLACK],
+      'other' => [DUST, BLACK]
+    }
+  end
+end

data/lib/seafoam/spotlight.rb

@@ -0,0 +1,28 @@
+module Seafoam
+  # Spotlight can *light* nodes, which makes them visible, their adjacent nodes
+  # visible by grey, and other nodes invisible. Multiple nodes can be *lit*.
+  class Spotlight
+    def initialize(graph)
+      @graph = graph
+    end
+
+    # Mark a node as lit by the spotlight.
+    def light(node)
+      # This node is lit.
+      node.props[:spotlight] = 'lit'
+
+      # Adjacent nodes are shaded, if they haven't be lit themselvs.
+      node.adjacent.each do |adjacent|
+        adjacent.props[:spotlight] ||= 'shaded'
+      end
+    end
+
+    # Go through all other nodes and make them hidden, having lit as many nodes
+    # as you want.
+    def shade
+      @graph.nodes.each_value do |node|
+        node.props[:hidden] = true unless node.props[:spotlight]
+      end
+    end
+  end
+end

data/lib/seafoam/version.rb

@@ -0,0 +1,5 @@
+module Seafoam
+  MAJOR_VERSION = 0
+  MINOR_VERSION = 2
+  VERSION = "#{MAJOR_VERSION}.#{MINOR_VERSION}"
+end

data/seafoam.gemspec

@@ -0,0 +1,20 @@
+require_relative 'lib/seafoam/version'
+
+Gem::Specification.new do |spec|
+  spec.name     = 'seafoam'
+  spec.version  = Seafoam::VERSION
+  spec.summary  = 'A tool for working with compiler graphs'
+  spec.authors  = ['Chris Seaton']
+  spec.homepage = 'https://github.com/Shopify/seafoam'
+  spec.license = 'MIT'
+
+  spec.files = `git ls-files`.split("\n")
+  spec.bindir = 'bin'
+  spec.executables = %w[seafoam bgv2json bgv2isabelle]
+
+  spec.required_ruby_version = '>= 2.5.8'
+
+  spec.add_development_dependency 'benchmark-ips', '~> 2.7'
+  spec.add_development_dependency 'rspec', '~> 3.8'
+  spec.add_development_dependency 'rubocop', '~> 0.74'
+end

data/spec/seafoam/annotators/fallback_spec.rb

@@ -0,0 +1,69 @@
+require 'seafoam'
+
+require 'rspec'
+
+describe Seafoam::Annotators::FallbackAnnotator do
+  it 'always applies' do
+    expect(Seafoam::Annotators::FallbackAnnotator.applies?(Seafoam::Graph.new)).to be true
+  end
+
+  it 'adds a label annotation when there is a label property' do
+    graph = Seafoam::Graph.new
+    node = graph.create_node(0, 'label' => 'foo')
+    annotator = Seafoam::Annotators::FallbackAnnotator.new
+    annotator.annotate graph
+    expect(node.props[:label]).to eq 'foo'
+  end
+
+  it 'does not overwrite an existing label annotation' do
+    graph = Seafoam::Graph.new
+    node = graph.create_node(0, 'label' => 'foo', :label => 'bar')
+    annotator = Seafoam::Annotators::FallbackAnnotator.new
+    annotator.annotate graph
+    expect(node.props[:label]).to eq 'bar'
+  end
+
+  it 'adds nothing when there is no label property' do
+    graph = Seafoam::Graph.new
+    node = graph.create_node(0, 'xlabel' => 'foo')
+    annotator = Seafoam::Annotators::FallbackAnnotator.new
+    annotator.annotate graph
+    expect(node.props[:label]).to be nil
+  end
+
+  it 'sets node kind to other when there is no kind' do
+    graph = Seafoam::Graph.new
+    node = graph.create_node(0)
+    annotator = Seafoam::Annotators::FallbackAnnotator.new
+    annotator.annotate graph
+    expect(node.props[:kind]).to eq 'other'
+  end
+
+  it 'does not overwrite an existing node kind annotations' do
+    graph = Seafoam::Graph.new
+    node = graph.create_node(0, kind: 'control')
+    annotator = Seafoam::Annotators::FallbackAnnotator.new
+    annotator.annotate graph
+    expect(node.props[:kind]).to eq 'control'
+  end
+
+  it 'sets edge kind to other when there is no kind' do
+    graph = Seafoam::Graph.new
+    node_a = graph.create_node(0)
+    node_b = graph.create_node(1)
+    edge = graph.create_edge(node_a, node_b)
+    annotator = Seafoam::Annotators::FallbackAnnotator.new
+    annotator.annotate graph
+    expect(edge.props[:kind]).to eq 'other'
+  end
+
+  it 'does not overwrite an existing edge kind annotations' do
+    graph = Seafoam::Graph.new
+    node_a = graph.create_node(0)
+    node_b = graph.create_node(1)
+    edge = graph.create_edge(node_a, node_b, kind: 'control')
+    annotator = Seafoam::Annotators::FallbackAnnotator.new
+    annotator.annotate graph
+    expect(edge.props[:kind]).to eq 'control'
+  end
+end