visualize_packwerk 0.1.3 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 358f7f6ce6490e9a49b9a898af9d877181c1ecffd99068dea9cbaa5267f1a552
-  data.tar.gz: 4ff54f1b92868804ce3a49bba54f54668ccc1510b446873fc7dbb3da7d9d4cfe
+  metadata.gz: 4684e489b9b59adcca847e4c3261f98d487210b07c3573e9c147f94fd0044424
+  data.tar.gz: 9f3e57d74e418e25e7732822193e1b7d3fd06048c46d6d1a9da7d97a60c62a7d
 SHA512:
-  metadata.gz: 4933f49f8868128aaecd6b6696d79cc677d8185bea9b18e3f2f7bdbafec85dfd9d055ebe8c196aad7008b52a92f5fcad53d69af5535ffad152b6c8188ebbb8bb
-  data.tar.gz: 5f72a6c8a97623326a94e4fca096b5a836c9208e801a5f70f720d515115f074a41d35f7b4ccc801f02bb44d01e95e338826d3ce2ee39f50808ce3d8006a6709a
+  metadata.gz: 51eaec81b7b964cba8e6bca64c2e1b80298f650d6fcf7fdd1c0817e016f9661a437ab86f068d9a041a903d1c83b8d31212343419a807ebefd117ed5c4dfa6832
+  data.tar.gz: e8eb48b12eb1841bd0543f660c29dd8644cf3cfd9cedf31fcab81b51f76e8353d87bfd522197b07ad6e0622cfbfaaa4649d49eee8a6b6d242f719e2510bd4e46

data/README.md

@@ -1,8 +1,19 @@
 # visualize_packwerk
 
-This gem contains rake tasks to help visualize relationships between packwerk packs.
+This gem helps visualize relationships between packwerk packs.
 
-# Usage
+![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
@@ -12,7 +23,7 @@ selected_packs = Packs.all.select{ |p| ['Team 1', 'Team 2'].include?(CodeOwnersh
 VisualizePackwerk.package_graph!(selected_packs)
 ```
 
-# Building a team graph for specific teams
+## Building a team graph for specific teams
 ```ruby
 # Select the teams you want to include
 selected_teams = CodeTeams.all
@@ -20,8 +31,5 @@ selected_teams = CodeTeams.all.select{ |t| ['Team 1', 'Team 2'].include?(t.name)
 VisualizePackwerk.team_graph!(selected_teams)
 ```
 
-## bin/packs
-For simpler use, use `bin/packs` in `use_packwerk` (https://github.com/rubyatscale/use_packwerk)
-
 # Want to change something or add a feature?
 Submit a PR or post an issue!

data/lib/visualize_packwerk/package_graph.rb

@@ -16,7 +16,7 @@ module VisualizePackwerk
     sig { params(package_nodes: T::Set[PackageNode]).void }
     def initialize(package_nodes:)
       @package_nodes = package_nodes
-      @index_by_name = T.let({}, T::Hash[String, PackageNode])
+      @index_by_name = T.let({}, T::Hash[String, T.nilable(PackageNode)])
     end
 
     sig { returns(PackageGraph) }
@@ -46,9 +46,9 @@ module VisualizePackwerk
       PackageGraph.new(package_nodes: package_nodes)
     end
 
-    sig { params(name: String).returns(PackageNode) }
+    sig { params(name: String).returns(T.nilable(PackageNode)) }
     def package_by_name(name)
-      @index_by_name[name] ||= T.must(package_nodes.find { |node| node.name == name })
+      @index_by_name[name] ||= package_nodes.find { |node| node.name == name }
     end
   end
 end

data/lib/visualize_packwerk/package_relationships.rb

@@ -45,7 +45,15 @@ module VisualizePackwerk
       # https://graphviz.org/docs/layouts/
       default_layout = :dot
       # other_layout = :sfdp
-      graphviz_graph = GraphViz.new(:G, type: :digraph, dpi: 100, layout: default_layout)
+      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])
@@ -56,36 +64,32 @@ module VisualizePackwerk
         graphviz_nodes[node.name] = add_node(node, graphviz_graph)
       end
 
-      max_edge_width = 10
-
       # Draw all edges
       nodes_to_draw.each do |node|
         node.dependencies.each do |to_node|
           next unless node_names.include?(to_node)
 
-          graphviz_graph.add_edges(
-            graphviz_nodes[node.name],
-            graphviz_nodes[to_node],
-            { color: 'darkgreen' }
+          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)
 
-          edge_width = [
-            [(violation_count / 5).to_i, 1].max, # rubocop:disable Lint/NumberConversion
-            max_edge_width,
-          ].min
-
-          graphviz_graph.add_edges(
-            graphviz_nodes[node.name],
-            graphviz_nodes[to_node_name],
-            { color: 'red', penwidth: edge_width }
+          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)
@@ -106,6 +110,60 @@ module VisualizePackwerk
 
       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

data/lib/visualize_packwerk/team_graph.rb

@@ -26,7 +26,9 @@ module VisualizePackwerk
         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_team = package_graph.package_by_name(pack_name).team_name
+            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!
@@ -36,7 +38,9 @@ module VisualizePackwerk
 
         dependencies = Set.new
         package_nodes_for_team.map(&:dependencies).reduce(Set.new, :+).each do |dependency|
-          dependencies << package_graph.package_by_name(dependency).team_name
+          other_pack = package_graph.package_by_name(dependency)
+          next if other_pack.nil?
+          dependencies << other_pack.team_name
         end
 
         team_nodes << TeamNode.new(

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: visualize_packwerk
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.1
 platform: ruby
 authors:
 - Gusto Engineers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-09 00:00:00.000000000 Z
+date: 2023-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
@@ -160,6 +160,7 @@ files:
 - README.md
 - lib/visualize_packwerk.rb
 - lib/visualize_packwerk/graph_interface.rb
+- lib/visualize_packwerk/legend.png
 - lib/visualize_packwerk/node_interface.rb
 - lib/visualize_packwerk/package_graph.rb
 - lib/visualize_packwerk/package_node.rb