visualize_packs 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d1394594cbe0bf263a019593de9fd39ce2c191fb4c56d6be47fa0a52b2d20e6c
+  data.tar.gz: 7e81457c38334432d358d5e2b87e12330b1bc5ec90221a6d96626a71e9bf386f
+SHA512:
+  metadata.gz: f5f8114ea83f715bb3d8539788f69b433818c22428aee06d2c2e43e721059d64b3a01006eb5d0b1dcf7bed358178fbb7fa6f931a406cf566c6a04a5a7c41fd14
+  data.tar.gz: 98896ac828d1b2b3e6062b8f0acda397bfa7f1c219c6fadb5d7bbec5eb3697599c615334470207abe9579fe5463aaa11e1ac272a234fd1a7bc674b4c619c0c9d

data/README.md

@@ -0,0 +1,35 @@
+# visualize_packs
+
+This gem helps visualize relationships between packs.
+
+![Example of visualization](docs/example.png)
+
+# CLI Usage
+## bin/packs
+For simpler use, add `bin/packs` via `use_packs` (https://github.com/rubyatscale/use_packs)
+```
+bin/packs visualize # all packs
+bin/packs visualize packs/a packs/b # subset of packs
+bin/packs # enter interactive mode to select what packs to visualize
+```
+
+# Ruby API Usage
+## Building a package graph for a selection of packages
+```ruby
+# Select the packs you want to include
+selected_packs = Packs.all
+selected_packs = Packs.all.select{ |p| ['packs/my_pack_1', 'packs/my_pack_2'].include?(p.name) }
+selected_packs = Packs.all.select{ |p| ['Team 1', 'Team 2'].include?(CodeOwnership.for_package(p)&.name) }
+VisualizePacks.package_graph!(selected_packs)
+```
+
+## Building a team graph for specific teams
+```ruby
+# Select the teams you want to include
+selected_teams = CodeTeams.all
+selected_teams = CodeTeams.all.select{ |t| ['Team 1', 'Team 2'].include?(t.name) }
+VisualizePacks.team_graph!(selected_teams)
+```
+
+# Want to change something or add a feature?
+Submit a PR or post an issue!

data/lib/visualize_packs/graph_interface.rb

@@ -0,0 +1,17 @@
+# typed: strict
+
+module VisualizePacks
+  # This stores graphviz-independent views of our package graph.
+  # It should be optimized for fast lookup (leveraging internal indexes, which are stable due to the immutability of the package nodes)
+  # A `TeamGraph` should be able to consume this and basically just create a reduced version
+  # Lastly, each one should implement a common interface, and graphviz should use that interface and take in either types of graph via the interface
+  module GraphInterface
+    extend T::Sig
+    extend T::Helpers
+    interface!
+
+    sig { abstract.returns(T::Set[NodeInterface]) }
+    def nodes
+    end
+  end
+end

data/lib/visualize_packs/node_interface.rb

@@ -0,0 +1,29 @@
+# typed: strict
+
+module VisualizePacks
+  module NodeInterface
+    extend T::Sig
+    extend T::Helpers
+    interface!
+
+    sig { abstract.returns(String) }
+    def name
+    end
+
+    sig { abstract.returns(String) }
+    def group_name
+    end
+
+    sig { abstract.returns(T::Hash[String, Integer]) }
+    def violations_by_node_name
+    end
+
+    sig { abstract.returns(T::Array[String]) }
+    def dependencies
+    end
+
+    sig { abstract.params(node_name: String).returns(T::Boolean) }
+    def depends_on?(node_name)
+    end
+  end
+end

data/lib/visualize_packs/package_graph.rb

@@ -0,0 +1,54 @@
+# typed: strict
+
+module VisualizePacks
+  class PackageGraph
+    extend T::Sig
+    include GraphInterface
+
+    sig { returns(T::Set[PackageNode]) }
+    attr_reader :package_nodes
+
+    sig { override.returns(T::Set[NodeInterface]) }
+    def nodes
+      package_nodes
+    end
+
+    sig { params(package_nodes: T::Set[PackageNode]).void }
+    def initialize(package_nodes:)
+      @package_nodes = package_nodes
+      @index_by_name = T.let({}, T::Hash[String, T.nilable(PackageNode)])
+    end
+
+    sig { returns(PackageGraph) }
+    def self.construct
+      package_nodes = Set.new
+      Packs.all.each do |p|
+        owner = CodeOwnership.for_package(p)
+
+        # Here we need to load the package violations and dependencies,
+        # so we need to use ParsePackwerk to parse that information.
+        package_info = ParsePackwerk.find(p.name)
+        next unless package_info # This should not happen unless packs/parse_packwerk change implementation
+
+        violations = package_info.violations
+        violations_by_package = violations.group_by(&:to_package_name).transform_values(&:count)
+
+        dependencies = package_info.dependencies
+
+        package_nodes << PackageNode.new(
+          name: p.name,
+          team_name: owner&.name || 'Unknown',
+          violations_by_package: violations_by_package,
+          dependencies: Set.new(dependencies)
+        )
+      end
+
+      PackageGraph.new(package_nodes: package_nodes)
+    end
+
+    sig { params(name: String).returns(T.nilable(PackageNode)) }
+    def package_by_name(name)
+      @index_by_name[name] ||= package_nodes.find { |node| node.name == name }
+    end
+  end
+end

data/lib/visualize_packs/package_node.rb

@@ -0,0 +1,28 @@
+# typed: strict
+
+module VisualizePacks
+  class PackageNode < T::Struct
+    extend T::Sig
+    include NodeInterface
+
+    const :name, String
+    const :team_name, String
+    const :violations_by_package, T::Hash[String, Integer]
+    const :dependencies, T::Set[String]
+
+    sig { override.returns(T::Hash[String, Integer]) }
+    def violations_by_node_name
+      violations_by_package
+    end
+
+    sig { override.returns(String) }
+    def group_name
+      team_name
+    end
+
+    sig { override.params(node_name: String).returns(T::Boolean) }
+    def depends_on?(node_name)
+      dependencies.include?(node_name) || (violations_by_package[node_name] || 0) > 0
+    end
+  end
+end

data/lib/visualize_packs/package_relationships.rb

@@ -0,0 +1,170 @@
+# typed: strict
+
+module VisualizePacks
+  class PackageRelationships
+    extend T::Sig
+
+    OUTPUT_FILENAME = T.let('packwerk.png'.freeze, String)
+
+    sig { params(teams: T::Array[CodeTeams::Team]).void }
+    def create_package_graph_for_teams!(teams)
+      packages = Packs.all.select do |package|
+        teams.map(&:name).include?(CodeOwnership.for_package(package)&.name)
+      end
+
+      create_package_graph!(packages)
+    end
+
+    sig { params(teams: T::Array[CodeTeams::Team], show_all_teams: T::Boolean).void }
+    def create_team_graph!(teams, show_all_teams: false)
+      package_graph = PackageGraph.construct
+      team_graph = TeamGraph.from_package_graph(package_graph)
+      node_names = teams.map(&:name)
+
+      draw_graph!(team_graph, node_names, show_all_nodes: show_all_teams)
+    end
+
+    sig { params(packages: T::Array[Packs::Pack]).void }
+    def create_package_graph!(packages)
+      graph = PackageGraph.construct
+      node_names = packages.map(&:name)
+      draw_graph!(graph, node_names)
+    end
+
+    sig { params(packages: T::Array[Packs::Pack], show_all_nodes: T::Boolean).void }
+    def create_graph!(packages, show_all_nodes: false)
+      graph = PackageGraph.construct
+      node_names = packages.map(&:name)
+      draw_graph!(graph, node_names, show_all_nodes: show_all_nodes)
+    end
+
+    sig { params(graph: GraphInterface, node_names: T::Array[String], show_all_nodes: T::Boolean).void }
+    def draw_graph!(graph, node_names, show_all_nodes: false)
+      # SFDP looks better than dot in some cases, but less good in other cases.
+      # If your visualization looks bad, change the layout to other_layout!
+      # https://graphviz.org/docs/layouts/
+      default_layout = :dot
+      # other_layout = :sfdp
+      graphviz_graph = GraphViz.new(
+        :G,
+        type: :digraph,
+        dpi: 100,
+        layout: default_layout,
+        label: "Visualization of #{node_names.count} packs, generated using `bin/packs`",
+        fontsize: 24,
+        labelloc: "t",
+      )
+
+      # Create graph nodes
+      graphviz_nodes = T.let({}, T::Hash[String, GraphViz::Node])
+
+      nodes_to_draw = graph.nodes.select{|n| node_names.include?(n.name) }
+
+      nodes_to_draw.each do |node|
+        graphviz_nodes[node.name] = add_node(node, graphviz_graph)
+      end
+
+      # Draw all edges
+      nodes_to_draw.each do |node|
+        node.dependencies.each do |to_node|
+          next unless node_names.include?(to_node)
+
+          add_dependency(
+            graph: graphviz_graph,
+            node1: T.must(graphviz_nodes[node.name]),
+            node2: T.must(graphviz_nodes[to_node]),
+          )
+        end
+
+        node.violations_by_node_name.each do |to_node_name, violation_count|
+          next unless node_names.include?(to_node_name)
+
+          add_violation(
+            graph: graphviz_graph,
+            node1: T.must(graphviz_nodes[node.name]),
+            node2: T.must(graphviz_nodes[to_node_name]),
+            violation_count: violation_count
+          )
+        end
+      end
+
+      add_legend(graphviz_graph)
+
+      # Save graph to filesystem
+      puts "Outputting to: #{OUTPUT_FILENAME}"
+      graphviz_graph.output(png: OUTPUT_FILENAME)
+      puts 'Finished!'
+    end
+
+    sig { params(node: NodeInterface, graph: GraphViz).returns(GraphViz::Node) }
+    def add_node(node, graph)
+      node_options = {
+        fontsize: 26.0,
+        fontcolor: 'black',
+        fillcolor: 'white',
+        color: 'black',
+        height: 1.0,
+        style: 'filled, rounded',
+        shape: 'box',
+      }
+
+      graph.add_nodes(node.name, **node_options)
+    end
+
+    sig { params(graph: GraphViz).void }
+    def add_legend(graph)
+      legend = graph.add_graph("legend")
+
+      # This commented out code was used to generate an image that I edited by hand.
+      # I was unable to figure out how to:
+      # - put a box around the legend
+      # - layout the node pairs in vertical order
+      # - give it a title
+      # So I just generated this using graphviz and then pulled the image in.
+      # a_node = legend.add_nodes("packs/a")
+      # b_node = legend.add_nodes("packs/b")
+      # c_node = legend.add_nodes("packs/c")
+      # d_node = legend.add_nodes("packs/d")
+      # e_node = legend.add_nodes("packs/e")
+      # f_node = legend.add_nodes("packs/f")
+
+      # add_dependency(graph: legend, node1: a_node, node2: b_node, label: 'Dependency in package.yml')
+      # add_violation(graph: legend, node1: c_node, node2: d_node, violation_count: 1, label: 'Violations (few)')
+      # add_violation(graph: legend, node1: e_node, node2: f_node, violation_count: 30, label: 'Violations (many)')
+
+      image = legend.add_node("",
+        shape: "image",
+        image: Pathname.new(__dir__).join("./legend.png").to_s,
+      )
+    end
+
+    sig { params(graph: GraphViz, node1: GraphViz::Node, node2: GraphViz::Node, violation_count: Integer, label: T.nilable(String)).void }
+    def add_violation(graph:, node1:, node2:, violation_count:, label: nil)
+      max_edge_width = 10
+
+      edge_width = [
+        [(violation_count / 5).to_i, 1].max, # rubocop:disable Lint/NumberConversion
+        max_edge_width,
+      ].min
+
+      opts = { color: 'red', style: 'dashed', penwidth: edge_width }
+      if label
+        opts.merge!(label: label)
+      end
+
+      graph.add_edges(node1, node2, opts)
+    end
+
+    sig { params(graph: GraphViz, node1: GraphViz::Node, node2: GraphViz::Node, label: T.nilable(String)).void }
+    def add_dependency(graph:, node1:, node2:, label: nil)
+      opts = { color: 'darkgreen' }
+      if label
+        opts.merge!(label: label)
+      end
+
+      graph.add_edges(node1, node2, opts)
+    end
+  end
+
+  private_constant :PackageRelationships
+end

data/lib/visualize_packs/team_graph.rb

@@ -0,0 +1,56 @@
+# typed: strict
+
+module VisualizePacks
+  #
+  # A team graph reduces a PackageGraph by aggregating over packages owned by teams
+  #
+  class TeamGraph
+    extend T::Sig
+    include GraphInterface
+
+    sig { override.returns(T::Set[NodeInterface]) }
+    def nodes
+      @team_nodes
+    end
+
+    sig { params(team_nodes: T::Set[TeamNode]).void }
+    def initialize(team_nodes:)
+      @team_nodes = team_nodes
+    end
+
+    sig { params(package_graph: PackageGraph).returns(TeamGraph) }
+    def self.from_package_graph(package_graph)
+      team_nodes = T.let(Set.new, T::Set[TeamNode])
+      package_graph.package_nodes.group_by(&:team_name).each do |team, package_nodes_for_team|
+        violations_by_team = {}
+        package_nodes_for_team.map(&:violations_by_package).each do |new_violations_by_package|
+          new_violations_by_package.each do |pack_name, count|
+            # We first get the pack owner of the violated package
+            other_package = package_graph.package_by_name(pack_name)
+            next if other_package.nil?
+            other_team = other_package.team_name
+            violations_by_team[other_team] ||= 0
+            # Then we add the violations on that team together
+            # TODO: We may want to ignore this if team == other_team to avoid arrows pointing to self, but maybe not!
+            violations_by_team[other_team] += count
+          end
+        end
+
+        dependencies = Set.new
+        package_nodes_for_team.map(&:dependencies).reduce(Set.new, :+).each do |dependency|
+          other_pack = package_graph.package_by_name(dependency)
+          next if other_pack.nil?
+          dependencies << other_pack.team_name
+        end
+
+        team_nodes << TeamNode.new(
+          name: team,
+          violations_by_team: violations_by_team,
+          dependencies: dependencies
+        )
+      end
+
+      TeamGraph.new(team_nodes: team_nodes)
+    end
+  end
+end

data/lib/visualize_packs/team_node.rb

@@ -0,0 +1,27 @@
+# typed: strict
+
+module VisualizePacks
+  class TeamNode < T::Struct
+    extend T::Sig
+    include NodeInterface
+
+    const :name, String
+    const :violations_by_team, T::Hash[String, Integer]
+    const :dependencies, T::Set[String]
+
+    sig { override.returns(T::Hash[String, Integer]) }
+    def violations_by_node_name
+      violations_by_team
+    end
+
+    sig { override.returns(String) }
+    def group_name
+      name
+    end
+
+    sig { override.params(node_name: String).returns(T::Boolean) }
+    def depends_on?(node_name)
+      dependencies.include?(node_name) || (violations_by_node_name[node_name] || 0) > 0
+    end
+  end
+end

data/lib/visualize_packs.rb

@@ -0,0 +1,29 @@
+# typed: strict
+
+require 'packs-specification'
+require 'parse_packwerk'
+require 'code_ownership'
+require 'graphviz'
+require 'sorbet-runtime'
+
+require 'visualize_packs/node_interface'
+require 'visualize_packs/graph_interface'
+require 'visualize_packs/team_node'
+require 'visualize_packs/package_node'
+require 'visualize_packs/team_graph'
+require 'visualize_packs/package_graph'
+require 'visualize_packs/package_relationships'
+
+module VisualizePacks
+  extend T::Sig
+
+  sig { params(packages: T::Array[Packs::Pack]).void }
+  def self.package_graph!(packages)
+    PackageRelationships.new.create_package_graph!(packages)
+  end
+
+  sig { params(teams: T::Array[CodeTeams::Team]).void }
+  def self.team_graph!(teams)
+    PackageRelationships.new.create_team_graph!(teams)
+  end
+end

metadata

@@ -0,0 +1,197 @@
+--- !ruby/object:Gem::Specification
+name: visualize_packs
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Gusto Engineers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-08-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  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: packs
+  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: parse_packwerk
+  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: code_ownership
+  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: rake
+  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'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.16
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.16
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tapioca
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A gem to visualize connections in a Ruby app that uses packs
+email:
+- dev@gusto.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/visualize_packs.rb
+- lib/visualize_packs/graph_interface.rb
+- lib/visualize_packs/legend.png
+- lib/visualize_packs/node_interface.rb
+- lib/visualize_packs/package_graph.rb
+- lib/visualize_packs/package_node.rb
+- lib/visualize_packs/package_relationships.rb
+- lib/visualize_packs/team_graph.rb
+- lib/visualize_packs/team_node.rb
+homepage: https://github.com/rubyatscale/visualize_packs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rubyatscale/visualize_packs
+  source_code_uri: https://github.com/rubyatscale/visualize_packs
+  changelog_uri: https://github.com/rubyatscale/visualize_packs/releases
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: A gem to visualize connections in a Ruby app that uses packs
+test_files: []