visualize_packwerk 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e70be5b42437ab3ffacbbff1a3ec57c1116b8bc5fd1e4fc91163631414a35dae
+  data.tar.gz: 7cc7f753055f8f655d0787f3452f3b600eef10182689d637ac2a49eaf96706ff
+SHA512:
+  metadata.gz: fe981d2228c1b9039020e5b715cb578b3c5a5a8f6bbade61513151d1a770d06eb327463563b96468e00e0359e7aa6fcadf991d10f03ddec1e923396266c008c0
+  data.tar.gz: 8de59866b806300164ccd476d9e481b7aba1ff328d746c246aec49fe3d65c353511dc2db8713807787b1e991c6fcf8040281fee7ff03766c821111950373b1c2

data/README.md

@@ -0,0 +1,32 @@
+# visualize_packwerk
+
+This pack contains rake tasks to help visualize relationships between packwerk packs.
+
+# Usage
+## Building a package graph for a selection of packages (owned by 5 teams max)
+```
+bin/rails visualize_packwerk:package_relationships['packs/pack1','packs/pack2']
+```
+
+# Building a package graph for specific teams (5 teams max)
+```
+bin/rails visualize_packwerk:package_relationships_for_teams['Team1','Team2']
+```
+
+# Building a package graph for all packages (this is slow and produces a huge file)
+```
+bin/rails visualize_packwerk:package_relationships
+```
+
+# Building a TEAM graph for specific teams
+```
+bin/rails visualize_packwerk:team_relationships['Team1','Team2']
+```
+
+# Building a TEAM graph for all teams (this is slow and produces a huge file)
+```
+bin/rails visualize_packwerk:team_relationships
+```
+
+# Want to change something or add a feature?
+Submit a PR or post an issue!

data/lib/visualize_packwerk/graph_interface.rb

@@ -0,0 +1,17 @@
+# typed: strict
+
+module VisualizePackwerk
+  # 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_packwerk/node_interface.rb

@@ -0,0 +1,29 @@
+# typed: strict
+
+module VisualizePackwerk
+  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_packwerk/package_graph.rb

@@ -0,0 +1,48 @@
+# typed: strict
+
+module VisualizePackwerk
+  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, PackageNode])
+    end
+
+    sig { returns(PackageGraph) }
+    def self.construct
+      package_nodes = Set.new
+      ParsePackwerk.all.each do |p|
+        # We could consider ignoring the root!
+        # We would also need to ignore it when parsing PackageNodes.
+        # next if p.name == ParsePackwerk::ROOT_PACKAGE_NAME
+        owner = CodeOwnership.for_package(p)
+        violations_by_package = PackageProtections::ProtectedPackage.from(p).violations.group_by(&:to_package_name).transform_values(&:count)
+
+        package_nodes << PackageNode.new(
+          name: p.name,
+          team_name: owner&.name || 'Unknown',
+          violations_by_package: violations_by_package,
+          dependencies: Set.new(p.dependencies)
+        )
+      end
+
+      PackageGraph.new(package_nodes: package_nodes)
+    end
+
+    sig { params(name: String).returns(PackageNode) }
+    def package_by_name(name)
+      @index_by_name[name] ||= T.must(package_nodes.find { |node| node.name == name })
+    end
+  end
+end

data/lib/visualize_packwerk/package_node.rb

@@ -0,0 +1,28 @@
+# typed: strict
+
+module VisualizePackwerk
+  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_packwerk/package_relationships.rb

@@ -0,0 +1,158 @@
+# typed: strict
+
+module VisualizePackwerk
+  class PackageRelationships
+    extend T::Sig
+
+    OUTPUT_FILENAME = T.let('packwerk.png'.freeze, String)
+
+    sig { void }
+    def initialize
+      @colors_by_team = T.let({}, T::Hash[String, String])
+      @remaining_colors = T.let(
+        [
+          # Found using https://htmlcolorcodes.com/color-picker/
+          '#77EE77', # green
+          '#DFEE77', # yellow
+          '#77EEE6', # teal
+          '#EEC077', # orange
+          '#EE77BF', # pink
+          '#EE6F6F', # red
+          '#ED6EDE', # magenta
+          '#8E8CFE', # blue
+          '#EEA877', # red-orange
+        ], T::Array[String]
+      )
+    end
+
+    sig { params(teams: T::Array[CodeTeams::Team]).void }
+    def create_package_graph_for_teams!(teams)
+      packages = ParsePackwerk.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)
+      highlighted_node_names = teams.map(&:name)
+
+      draw_graph!(team_graph, highlighted_node_names, show_all_nodes: show_all_teams)
+    end
+
+    sig { params(packages: T::Array[ParsePackwerk::Package], show_all_packs: T::Boolean).void }
+    def create_package_graph!(packages, show_all_packs: false)
+      graph = PackageGraph.construct
+      highlighted_node_names = packages.map(&:name)
+      draw_graph!(graph, highlighted_node_names, show_all_nodes: show_all_packs)
+    end
+
+    sig { params(packages: T::Array[ParsePackwerk::Package], show_all_nodes: T::Boolean).void }
+    def create_graph!(packages, show_all_nodes: false)
+      graph = PackageGraph.construct
+      highlighted_node_names = packages.map(&:name)
+      draw_graph!(graph, highlighted_node_names, show_all_nodes: show_all_nodes)
+    end
+
+    sig { params(graph: GraphInterface, highlighted_node_names: T::Array[String], show_all_nodes: T::Boolean).void }
+    def draw_graph!(graph, highlighted_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)
+
+      # Create graph nodes
+      graphviz_nodes = T.let({}, T::Hash[String, GraphViz::Node])
+
+      nodes_to_draw = graph.nodes
+
+      nodes_to_draw.each do |node|
+        next unless highlighted_node_names.any? { |highlighted_node_name| node.depends_on?(highlighted_node_name) } || highlighted_node_names.include?(node.name)
+
+        highlight_node = highlighted_node_names.include?(node.name) && !show_all_nodes
+        graphviz_nodes[node.name] = add_node(node, graphviz_graph, highlight_node)
+      end
+
+      max_edge_width = 10
+
+      # Draw all edges
+      nodes_to_draw.each do |node|
+        node.dependencies.each do |to_node|
+          next unless highlighted_node_names.include?(to_node)
+
+          graphviz_graph.add_edges(
+            graphviz_nodes[node.name],
+            graphviz_nodes[to_node],
+            { color: 'darkgreen' }
+          )
+        end
+
+        node.violations_by_node_name.each do |to_node_name, violation_count|
+          next unless highlighted_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 }
+          )
+        end
+      end
+
+      # Save graph to filesystem
+      puts "Outputting to: #{OUTPUT_FILENAME}"
+      graphviz_graph.output(png: OUTPUT_FILENAME)
+      puts 'Finished!'
+    end
+
+    sig { params(node: NodeInterface, graph: GraphViz, highlight_node: T::Boolean).returns(GraphViz::Node) }
+    def add_node(node, graph, highlight_node)
+      default_node_options = {
+        fontsize: 26.0,
+        fontcolor: 'white',
+        fillcolor: 'black',
+        color: 'black',
+        height: 1.0,
+        style: 'filled, rounded',
+        shape: 'box',
+      }
+
+      node_options = if highlight_node
+        default_node_options.merge(
+          fillcolor: highlight_by_group(node),
+          color: highlight_by_group(node),
+          fontcolor: 'black'
+        )
+      else
+        default_node_options
+      end
+
+      graph.add_nodes(node.name, **node_options)
+    end
+
+    sig { params(node: NodeInterface).returns(String) }
+    def highlight_by_group(node)
+      highlighted_package_color = @colors_by_team[node.group_name]
+      if !highlighted_package_color
+        highlighted_package_color = @remaining_colors.first
+        raise 'Can only color nodes a max of 5 unique colors for now' if highlighted_package_color.nil?
+
+        @remaining_colors.delete(highlighted_package_color)
+        @colors_by_team[node.group_name] = highlighted_package_color
+      end
+
+      highlighted_package_color
+    end
+  end
+
+  private_constant :PackageRelationships
+end

data/lib/visualize_packwerk/railtie.rb

@@ -0,0 +1,15 @@
+# typed: ignore
+
+require 'visualize_packwerk'
+require 'rails'
+
+module VisualizePackwerk
+  class Railtie < Rails::Railtie
+    railtie_name :visualize_packwerk
+
+    rake_tasks do
+      path = File.expand_path(__dir__)
+      Dir.glob("#{path}/tasks/visualize_packwerk.rake").each { |f| load f }
+    end
+  end
+end

data/lib/visualize_packwerk/tasks/visualize_packwerk.rake

@@ -0,0 +1,73 @@
+# typed: strict
+
+module VisualizePackwerk
+  class TaskLoader
+    include Rake::DSL
+    extend T::Sig
+
+    sig { void }
+    def create_tasks!
+      namespace(:visualize_packwerk) do
+        # This creates the array of symbols that are needed to declare an argument to a rake task
+        package_args = (1..100).map { |i| "package#{i}".to_sym }
+
+        desc('Graph packages')
+        task(:package_relationships, package_args => :environment) do |_task, args|
+          show_all_packs = args.to_hash.values.none?
+          packages = if show_all_packs
+            ParsePackwerk.all
+          else
+            args.to_hash.values.map do |pack_name|
+              found_package = ParsePackwerk.all.find { |p| p.name == pack_name }
+              if found_package.nil?
+                abort "Could not find pack with name: #{pack_name}"
+              end
+
+              found_package
+            end
+          end
+
+          PackageRelationships.new.create_package_graph!(packages, show_all_packs: show_all_packs)
+        end
+
+        # This creates the array of symbols that are needed to declare an argument to a rake task
+        team_args = (1..5).map { |i| "team#{i}".to_sym }
+
+        desc('Graph packages for teams')
+        task(:package_relationships_for_teams, team_args => :environment) do |_task, args|
+          teams = args.to_hash.values.map do |team_name|
+            team = CodeTeams.find(team_name)
+            if team.nil?
+              abort("Could not find team with name: #{team_name}. Check your config/teams/subdirectory/team.yml for correct team spelling, e.g. `Product Infrastructure`")
+            end
+
+            team
+          end
+
+          PackageRelationships.new.create_package_graph_for_teams!(teams)
+        end
+
+        desc('Graph team relationships')
+        task(:team_relationships, team_args => :environment) do |_task, args|
+          show_all_teams = args.to_hash.values.none?
+          teams = if show_all_teams
+            CodeTeams.all
+          else
+            args.to_hash.values.map do |team_name|
+              team = CodeTeams.find(team_name)
+              if team.nil?
+                abort("Could not find team with name: #{team_name}. Check your config/teams/subdirectory/team.yml for correct team spelling, e.g. `Product Infrastructure`")
+              end
+
+              team
+            end
+          end
+
+          PackageRelationships.new.create_team_graph!(teams, show_all_teams: show_all_teams)
+        end
+      end
+    end
+  end
+end
+
+VisualizePackwerk::TaskLoader.new.create_tasks!

data/lib/visualize_packwerk/team_graph.rb

@@ -0,0 +1,52 @@
+# typed: strict
+
+module VisualizePackwerk
+  #
+  # 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_team = package_graph.package_by_name(pack_name).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|
+          dependencies << package_graph.package_by_name(dependency).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_packwerk/team_node.rb

@@ -0,0 +1,27 @@
+# typed: strict
+
+module VisualizePackwerk
+  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_packwerk.rb

@@ -0,0 +1,17 @@
+# typed: strict
+
+module VisualizePackwerk
+  require 'visualize_packwerk/railtie' if defined?(Rails)
+  require 'parse_packwerk'
+  require 'code_ownership'
+  require 'package_protections'
+  require 'graphviz'
+
+  require 'visualize_packwerk/node_interface'
+  require 'visualize_packwerk/graph_interface'
+  require 'visualize_packwerk/team_node'
+  require 'visualize_packwerk/package_node'
+  require 'visualize_packwerk/team_graph'
+  require 'visualize_packwerk/package_graph'
+  require 'visualize_packwerk/package_relationships'
+end

data/sorbet/config

@@ -0,0 +1,2 @@
+--dir
+.

data/sorbet/rbi/gems/activesupport@7.0.3.1.rbi

@@ -0,0 +1,76 @@
+# typed: false
+
+# DO NOT EDIT MANUALLY
+# This is an autogenerated file for types exported from the `activesupport` gem.
+# Please instead update this file by running `bin/tapioca gem activesupport`.
+
+class FalseClass
+  include ::JSON::Ext::Generator::GeneratorMethods::FalseClass
+end
+
+class Float < ::Numeric
+  include ::JSON::Ext::Generator::GeneratorMethods::Float
+end
+
+class IO
+  include ::Enumerable
+  include ::File::Constants
+end
+
+class IO::ConsoleMode
+  def echo=(_arg0); end
+  def raw(*_arg0); end
+  def raw!(*_arg0); end
+
+  private
+
+  def initialize_copy(_arg0); end
+end
+
+class IO::EAGAINWaitReadable < ::Errno::EAGAIN
+  include ::IO::WaitReadable
+end
+
+class IO::EAGAINWaitWritable < ::Errno::EAGAIN
+  include ::IO::WaitWritable
+end
+
+class IO::EINPROGRESSWaitReadable < ::Errno::EINPROGRESS
+  include ::IO::WaitReadable
+end
+
+class IO::EINPROGRESSWaitWritable < ::Errno::EINPROGRESS
+  include ::IO::WaitWritable
+end
+
+IO::EWOULDBLOCKWaitReadable = IO::EAGAINWaitReadable
+IO::EWOULDBLOCKWaitWritable = IO::EAGAINWaitWritable
+
+class Integer < ::Numeric
+  include ::JSON::Ext::Generator::GeneratorMethods::Integer
+end
+
+class NameError < ::StandardError
+  include ::DidYouMean::Correctable
+end
+
+class NilClass
+  include ::JSON::Ext::Generator::GeneratorMethods::NilClass
+end
+
+class Numeric
+  include ::Comparable
+end
+
+class Symbol
+  include ::Comparable
+end
+
+class TrueClass
+  include ::JSON::Ext::Generator::GeneratorMethods::TrueClass
+end
+
+class URI::Generic
+  include ::URI::RFC2396_REGEXP
+  include ::URI
+end