graphwerk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5d3fb33710355e47f3bbfaa7c9f78e01547cad92a379d0d449e9f9e4b9f2be5a
+  data.tar.gz: 16c12353022a3b87bc1aae310fddbb176b0d4718ac7a85a33b17672d3ed1edab
+SHA512:
+  metadata.gz: ca38ee1799a0c4bb6fc08ed41836c6773d80c2ffbb86333baedbcd390ac390866a9d4bb416282a06dba7d8e3520ac33d5089c6aa6814159479995c74c4fb12b1
+  data.tar.gz: ca18e12ca29229fd82aaa316bd24bf40053fac581e3c25be1a71649c58498ecab3b131087183d54aa125f7348e03916c2352d71712fd2d374073eb616628983e

data/.github/workflows/rspec.yml

@@ -0,0 +1,23 @@
+name: RSpec Test Suite
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout branch
+      uses: actions/checkout@v1
+    - name: Set up Ruby
+      uses: actions/setup-ruby@v1
+      with:
+        ruby-version: 2.6.6
+    - name: Install latest bundler
+      run: |
+        command -v bundler || gem install bundler
+    - name: Install gems
+      run: bundle install --jobs $(nproc) --retry 3
+    - name: Typecheck with Sorbet
+      run: bundle exec srb tc . --ignore=/vendor
+    - name: Run RSpec test suite
+      run: bundle exec rspec spec

data/.gitignore

@@ -0,0 +1,22 @@
+/Gemfile.lock
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/vendor
+/node_modules
+
+# rspec failure tracking
+.rspec_status
+
+/shell.nix
+/tags
+
+*.log
+.DS_Store
+
+.ruby-gemset

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+2.6.6

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+1.0.0
+
+* Initial release

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in graphwerk.gemspec
+gemspec
+
+group :development, :test do
+  gem 'guard-livereload', require: false
+  gem 'guard-rspec'
+  gem 'pry-byebug'
+  gem 'rb-fsevent', require: false
+  gem 'rb-readline'
+  gem 'rspec'
+  gem 'shoulda-matchers', require: false
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Samuel Giles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,49 @@
+![graphwerk-logo](https://user-images.githubusercontent.com/2643026/95463568-cfaada80-0970-11eb-8305-aea01a0d77a9.png)
+
+# Graphwerk [![Gem Version](https://badge.fury.io/rb/graphwerk.svg)](https://badge.fury.io/rb/graphwerk) ![CI Badge](https://github.com/tricycle/graphwerk/workflows/RSpec%20Test%20Suite/badge.svg)
+
+Graphwerk is a small Ruby gem that can generate a diagram of dependencies between packages within an application that's using Packwerk to enforce boundaries.
+
+The gem builds on top of [Packwerk](https://github.com/Shopify/packwerk) and [Graphviz](https://github.com/glejeune/Ruby-Graphviz).
+
+Here's an example application package dependency diagram:
+
+![example](https://user-images.githubusercontent.com/2643026/95458900-c159c000-096a-11eb-86b7-b5ef7c1e936d.png)
+
+## Install
+
+Add this line to your application's Gemfile and run `bundle install`:
+
+`gem 'graphwerk'`
+
+## Usage
+
+For Rails applications a Railtie automatically loads a rake task that makes it easy to generate a diagram for your root package and its dependencies. The diagram will be placed at the root of your application as `packwerk.png`.
+
+```bash
+bundle exec rake graphwerk:update
+```
+
+More advance usage is possible by passing a `Packwerk::PackageSet` directly to `Graphwerk::Builders::Graph` and calling `#build` returning a `Graphviz` instance:
+
+```ruby
+graph = Graphwerk::Builders::Graph.new(
+   Packwerk::PackageSet.load_all_from(".")
+).build
+graph.output(svg: 'packwerk.svg')
+```
+
+All Graphviz layouts are supported and options for the graph, nodes and edges can be set via an optional `options` argument:
+
+```ruby
+graph = Graphwerk::Builders::Graph.new(
+   Packwerk::PackageSet.load_all_from("."),
+   options: {
+     layout: Graphwerk::Layout::Twopi,
+     graph: { overlap: true },
+     node: { fillcolor: '#000000' },
+     edges: { len: '3.0' }
+    }
+).build
+graph.output(svg: 'packwerk.svg')
+```

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'graphwerk'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/graphwerk.gemspec

@@ -0,0 +1,36 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'graphwerk/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'graphwerk'
+  spec.version       = Graphwerk::VERSION
+  spec.authors       = ['Samuel Giles']
+  spec.email         = ['samuel.giles@bellroy.com']
+
+  spec.summary       = "Visualise dependencies between your application and it's Packwerk packages using Graphviz."
+  spec.homepage      = 'https://github.com/tricycle/graphwerk'
+  spec.license       = 'MIT'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(spec|sorbet)/}) && !f.match(%r{^spec/support/factories/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport'
+  spec.add_dependency 'packwerk'
+  spec.add_dependency 'ruby-graphviz'
+  spec.add_dependency 'sorbet-runtime'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'rake', '>= 12.3.3'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'sorbet'
+  spec.add_development_dependency 'rspec-sorbet'
+end

data/lib/graphwerk.rb

@@ -0,0 +1,21 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require 'packwerk'
+require 'ruby-graphviz'
+require 'active_support/core_ext/hash/deep_merge'
+require 'graphwerk/version'
+require 'graphwerk/constants'
+require 'graphwerk/layout'
+require 'graphwerk/presenters/package'
+require 'graphwerk/builders/graph'
+require 'graphwerk/railtie' if defined?(Rails)
+
+module Graphwerk
+  def self.for_application(**args)
+    Graphwerk::Builders::Graph.new(
+      Packwerk::PackageSet.load_all_from(".")
+    ).build.output(args)
+  end
+end

data/lib/graphwerk/builders/graph.rb

@@ -0,0 +1,112 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Graphwerk
+  module Builders
+    class Graph
+      extend T::Sig
+
+      OptionsShape = T.type_alias {
+        {
+          layout: Graphwerk::Layout,
+          application: T::Hash[Symbol, Object],
+          graph: T::Hash[Symbol, Object],
+          node: T::Hash[Symbol, Object],
+          edge: T::Hash[Symbol, Object]
+        }
+      }
+
+      DEFAULT_OPTIONS = T.let({
+        layout: Graphwerk::Layout::Fdp,
+        application: {
+          style: 'filled',
+          fillcolor: '#333333',
+          fontcolor: 'white'
+        },
+        graph: {
+          root: Constants::ROOT_PACKAGE_NAME,
+          overlap: false,
+          splines: true
+        },
+        node: {
+          shape: 'box',
+          style: 'rounded, filled',
+          fontcolor: 'white',
+          fillcolor: '#EF673E',
+          color: '#EF673E',
+          fontname: 'Lato'
+        },
+        edge: {
+          len: '0.4'
+        }
+      }, OptionsShape)
+
+      sig { params(package_set: Packwerk::PackageSet, options: T::Hash[Symbol, Object]).void }
+      def initialize(package_set, options: {})
+        @package_set = package_set
+        @options = T.let(DEFAULT_OPTIONS.deep_merge(options), OptionsShape)
+        @graph = T.let(build_empty_graph, GraphViz)
+        @nodes = T.let(build_empty_nodes, T::Hash[String, GraphViz::Node])
+      end
+
+      sig { returns(GraphViz) }
+      def build
+        setup_graph
+        add_packages_to_graph
+        add_package_dependencies_to_graph
+        @graph
+      end
+
+      private
+
+      sig { returns(GraphViz) }
+      def build_empty_graph
+        GraphViz.new(:strict, type: :digraph, use: @options[:layout].serialize)
+      end
+
+      sig { returns(T::Hash[String, GraphViz::Node]) }
+      def build_empty_nodes
+        {
+          application: @graph.add_nodes(
+            Constants::ROOT_PACKAGE_NAME,
+            **@options[:application]
+          )
+        }
+      end
+
+      sig { void }
+      def setup_graph
+        @graph = build_empty_graph
+        @nodes = build_empty_nodes
+        @options[:graph].each_pair { |k,v| @graph.graph[k] =v }
+        @options[:node].each_pair { |k,v| @graph.node[k] =v }
+        @options[:edge].each_pair { |k,v| @graph.edge[k] =v }
+      end
+
+      sig { void }
+      def add_package_dependencies_to_graph
+        packages.each { |package| draw_dependencies(package) }
+      end
+
+      sig { void }
+      def add_packages_to_graph
+        packages.each do |package|
+          @nodes[package.name] = @graph.add_nodes(package.name, color: package.color)
+        end
+      end
+
+      sig { params(package: Presenters::Package).void }
+      def draw_dependencies(package)
+        package.dependencies.each do |dependency|
+          @graph.add_edges(@nodes[package.name], @nodes[dependency], color: package.color)
+        end
+      end
+
+      sig { returns(T::Array[Presenters::Package]) }
+      def packages
+        @packages = T.let(@packages, T.nilable(T::Array[Presenters::Package]))
+        @packages ||= @package_set.map { |package| Presenters::Package.new(package) }
+      end
+    end
+  end
+end

data/lib/graphwerk/constants.rb

@@ -0,0 +1,8 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Graphwerk
+  module Constants
+    ROOT_PACKAGE_NAME = 'Application'
+  end
+end

data/lib/graphwerk/layout.rb

@@ -0,0 +1,15 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Graphwerk
+  class Layout < T::Enum
+    enums do
+      Dot = new
+      Neato = new
+      Fdp = new
+      Sfdp = new
+      Twopi = new
+      Circo = new
+    end
+  end
+end

data/lib/graphwerk/presenters/package.rb

@@ -0,0 +1,56 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Graphwerk
+  module Presenters
+    class Package
+      extend T::Sig
+
+      sig { params(package: Packwerk::Package).void }
+      def initialize(package)
+        @package = package
+      end
+
+      WITHOUT_ROOT_FOLDER = T.let(
+        ->(package_name) { package_name.split('/', 2).last },
+        T.proc.params(package_name: String).returns(String)
+      )
+
+      sig { returns(String) }
+      def name
+        return WITHOUT_ROOT_FOLDER.call(@package.name) unless root?
+
+        Constants::ROOT_PACKAGE_NAME
+      end
+
+      sig { returns(T::Array[String]) }
+      def dependencies
+        @package.dependencies.map { |dependency| WITHOUT_ROOT_FOLDER.call(dependency) }
+      end
+
+      ROOT_COLOR = 'black'
+      COMPONENT_COLOR = 'azure4'
+
+      sig { returns(String) }
+      def color
+        return ROOT_COLOR if root?
+
+        COMPONENT_COLOR
+      end
+
+      private
+
+      ROOT_PACKAGE = '.'
+
+      sig { returns(T::Boolean) }
+      def root?
+        @package.name == ROOT_PACKAGE
+      end
+
+      private_constant :ROOT_PACKAGE,
+                       :ROOT_COLOR,
+                       :COMPONENT_COLOR,
+                       :WITHOUT_ROOT_FOLDER
+    end
+  end
+end

data/lib/graphwerk/railtie.rb

@@ -0,0 +1,10 @@
+# typed: false
+# frozen_string_literal: true
+
+module Graphwerk
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load 'graphwerk/tasks/rails.rake'
+    end
+  end
+end

data/lib/graphwerk/tasks/rails.rake

@@ -0,0 +1,9 @@
+# typed: false
+# frozen_string_literal: true
+
+namespace :graphwerk do
+  desc 'Produce an updated packwerk.png architecture diagram using Graphwerk'
+  task update: :environment do
+    Graphwerk.for_application(png: Rails.root.join('packwerk.png'))
+  end
+end

data/lib/graphwerk/version.rb

@@ -0,0 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Graphwerk
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,204 @@
+--- !ruby/object:Gem::Specification
+name: graphwerk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Samuel Giles
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2020-10-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  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: 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: 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: 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: bundler
+  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: pry
+  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: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 12.3.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 12.3.3
+- !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: rspec-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'
+description:
+email:
+- samuel.giles@bellroy.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/rspec.yml"
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- graphwerk.gemspec
+- lib/graphwerk.rb
+- lib/graphwerk/builders/graph.rb
+- lib/graphwerk/constants.rb
+- lib/graphwerk/layout.rb
+- lib/graphwerk/presenters/package.rb
+- lib/graphwerk/railtie.rb
+- lib/graphwerk/tasks/rails.rake
+- lib/graphwerk/version.rb
+homepage: https://github.com/tricycle/graphwerk
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key:
+specification_version: 4
+summary: Visualise dependencies between your application and it's Packwerk packages
+  using Graphviz.
+test_files: []