use_packwerk 0.50.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f4f9377346178fe79c699c9493993c0fb270170dcb200e1e443df752b6d7d32c
+  data.tar.gz: e9bf3060d53092534f2193fe93d68188cf750b2bbb824d60dc2c6ec6205c51f5
+SHA512:
+  metadata.gz: 0a4ef1cc30ac3db3613a1cb5d294a9bdd5afa2bdf1c70cbfb47db4b592c98d01130d5a3722ac3ebad206c0d36a906016148304cbe84f6fa193186bd4d734a213
+  data.tar.gz: 0430dfe13a6d016ea79b499ad0c28a53fdfa02dbd211c3777a32aae6f8b96b7bc6694c4e03d84add447505080a6d428faac4fffa6d3d861049ba09ed5edc6113

data/README.md

@@ -0,0 +1,62 @@
+# UsePackwerk
+
+UsePackwerk is a gem that helps in creating and maintaining packs. It exists to help perform some basic operations needed for pack setup and configuration. It provides a basic ruby file packager utility for [`packwerk`](https://github.com/Shopify/packwerk/). It assumes you are using [`stimpack`](https://github.com/rubyatscale/stimpack) to organize your packages.
+
+## Usage
+### General Help
+`bin/use_packwerk --help`
+
+### Pack Creation
+`bin/create_pack -n packs/your_pack_name_here`
+
+### Moving files to packs
+`bin/move_to_pack -n packs/your_pack_name_here -f path/to/file.rb,path/to/directory`
+This is used for moving files into a pack (the pack must already exist).
+Note this works for moving files to packs from the monolith or from other packs
+
+Make sure there are no spaces between the comma-separated list of paths of directories.
+
+### Moving a file to public API
+`bin/make_public -f path/to/file.rb,path/to/directory`
+This moves a file or directory to public API (that is -- the `app/public` folder).
+
+Make sure there are no spaces between the comma-separated list of paths of directories.
+
+### Listing top privacy violations
+`bin/list_top_privacy_violations -n packs/my_pack`
+Want to create interfaces? Not sure how your pack's code is being used?
+
+You can use this command to list the top privacy violations.
+
+If no pack name is passed in, this will list out violations across all packs.
+
+### Listing top dependency violations
+`bin/list_top_dependency_violations -n packs/my_pack`
+Want to see who is depending on you? Not sure how your pack's code is being used in an unstated way
+
+You can use this command to list the top dependency violations.
+
+If no pack name is passed in, this will list out violations across all packs.
+
+### Adding a dependency
+`bin/add_pack_dependency -n packs/my_pack -d packs/dependency_pack_name`
+
+This can be used to quickly modify a `package.yml` file and add a dependency. It also cleans up the list of dependencies to sort the list and remove redundant entries.
+
+## Discussions, Issues, Questions, and More
+To keep things organized, here are some recommended homes:
+
+### Issues:
+https://github.com/Gusto/use_packwerk/issues
+
+### Questions:
+https://github.com/Gusto/use_packwerk/discussions/categories/q-a
+
+### General discussions:
+https://github.com/Gusto/use_packwerk/discussions/categories/general
+
+### Ideas, new features, requests for change:
+https://github.com/Gusto/use_packwerk/discussions/categories/ideas
+
+### Showcasing your work:
+https://github.com/Gusto/use_packwerk/discussions/categories/show-and-tell

data/bin/use_packwerk

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# typed: strict
+
+require_relative '../lib/use_packwerk'
+UsePackwerk::CLI.start(ARGV)

data/lib/use_packwerk/cli.rb

@@ -0,0 +1,71 @@
+# typed: strict
+
+require 'thor'
+
+module UsePackwerk
+  class CLI < Thor
+    extend T::Sig
+
+    desc "create packs/your_pack", "Create pack with name packs/your_pack"
+    sig { params(pack_name: String).void }
+    def create(pack_name)
+      UsePackwerk.create_pack!(pack_name: pack_name)
+    end
+
+    desc "add_dependency packs/from_pack packs/to_pack", "Add packs/to_pack to packs/from_pack/package.yml list of dependencies"
+    long_desc <<~LONG_DESC
+      Use this to add a dependency between packs.
+
+      When you use bin/use_packwerk add_dependency packs/from_pack packs/to_pack, this command will
+      modify packs/from_pack/package.yml's list of dependencies and add packs/to_pack.
+
+      This command will also sort the list and make it unique.
+    LONG_DESC
+    sig { params(from_pack: String, to_pack: String).void }
+    def add_dependency(from_pack, to_pack)
+      UsePackwerk.add_dependency!(
+        pack_name: from_pack,
+        dependency_name: to_pack
+      )
+    end
+
+    desc "list_top_dependency_violations packs/your_pack", "List the top dependency violations of packs/your_pack"
+    option :limit, type: :numeric, default: 10, aliases: :l, banner: 'Specify the limit of constants to analyze'
+    sig { params(pack_name: String).void }
+    def list_top_dependency_violations(pack_name)
+      UsePackwerk.list_top_dependency_violations(
+        pack_name: pack_name,
+        limit: options[:limit]
+      )
+    end
+
+    desc "list_top_privacy_violations packs/your_pack", "List the top privacy violations of packs/your_pack"
+    option :limit, type: :numeric, default: 10, aliases: :l, banner: 'Specify the limit of constants to analyze'
+    sig { params(pack_name: String).void }
+    def list_top_privacy_violations(pack_name)
+      UsePackwerk.list_top_privacy_violations(
+        pack_name: pack_name,
+        limit: options[:limit]
+      )
+    end
+
+    desc "make_public path/to/file.rb path/to/directory", "Pass in a space-separated list of file or directory paths to make public"
+    sig { params(paths: String).void }
+    def make_public(*paths)
+      UsePackwerk.make_public!(
+        paths_relative_to_root: paths,
+        per_file_processors: [UsePackwerk::RubocopPostProcessor.new, UsePackwerk::CodeOwnershipPostProcessor.new],
+      )
+    end
+
+    desc "move packs/destination_pack path/to/file.rb path/to/directory", "Pass in a destination pack and a space-separated list of file or directory paths to move to the destination pack"
+    sig { params(pack_name: String, paths: String).void }
+    def move(pack_name, *paths)
+      UsePackwerk.move_to_pack!(
+        pack_name: pack_name,
+        paths_relative_to_root: paths,
+        per_file_processors: [UsePackwerk::RubocopPostProcessor.new, UsePackwerk::CodeOwnershipPostProcessor.new],
+      )
+    end
+  end
+end

data/lib/use_packwerk/code_ownership_post_processor.rb

@@ -0,0 +1,58 @@
+# typed: strict
+
+module UsePackwerk
+  class CodeOwnershipPostProcessor
+    include PerFileProcessorInterface
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @teams = T.let([], T::Array[String])
+      @did_move_files = T.let(false, T::Boolean)
+    end
+
+    sig { override.params(file_move_operation: Private::FileMoveOperation).void }
+    def before_move_file!(file_move_operation)
+      relative_path_to_origin = file_move_operation.origin_pathname
+      relative_path_to_destination = file_move_operation.destination_pathname
+
+      code_owners_allow_list_file = Pathname.new('config/code_ownership.yml')
+
+      if code_owners_allow_list_file.exist?
+        UsePackwerk.replace_in_file(
+          file: code_owners_allow_list_file.to_s,
+          find: relative_path_to_origin,
+          replace_with: relative_path_to_destination,
+        )
+      end
+
+      team = CodeOwnership.for_file(relative_path_to_origin.to_s)
+
+      if team
+        @teams << team.name
+      else
+        @teams << 'Unknown'
+      end
+
+      if !CodeOwnership.for_package(file_move_operation.destination_pack).nil?
+        CodeOwnership.remove_file_annotation!(relative_path_to_origin.to_s)
+        @did_move_files = true
+      end
+    end
+
+    sig { void }
+    def print_final_message!
+      if @teams.any?
+        Logging.section('Code Ownership') do
+          Logging.print('This section contains info about the current ownership distribution of the moved files.')
+          @teams.group_by { |team| team }.sort_by { |team, instances| -instances.count }.each do |team, instances|
+            Logging.print "  #{team} - #{instances.count} files"
+          end
+          if @did_move_files
+            Logging.print "Since the destination package has package-based ownership, file-annotations were removed from moved files."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/use_packwerk/configuration.rb

@@ -0,0 +1,49 @@
+# typed: strict
+
+module UsePackwerk
+  class Configuration
+    extend T::Sig
+
+    sig { params(enforce_dependencies: T::Boolean).void }
+    attr_writer :enforce_dependencies
+
+    sig { params(documentation_link: String).void }
+    attr_writer :documentation_link
+
+    sig { void }
+    def initialize
+      @enforce_dependencies = T.let(@enforce_dependencies, T.nilable(T::Boolean))
+      @documentation_link = T.let(documentation_link, T.nilable(String) )
+    end
+
+    sig { returns(T::Boolean) }
+    def enforce_dependencies
+      if !@enforce_dependencies.nil?
+        @enforce_dependencies
+      else
+        true
+      end
+    end
+
+    # Configure a link to show up for users who are looking for more info
+    sig { returns(String) }
+    def documentation_link
+      "https://go/packwerk"
+    end
+  end
+
+  class << self
+    extend T::Sig
+
+    sig { returns(Configuration) }
+    def config
+      @config = T.let(@config, T.nilable(Configuration))
+      @config ||= Configuration.new
+    end
+
+    sig { params(blk: T.proc.params(arg0: Configuration).void).void }
+    def configure(&blk) # rubocop:disable Lint/UnusedMethodArgument
+      yield(config)
+    end
+  end
+end

data/lib/use_packwerk/logging.rb

@@ -0,0 +1,33 @@
+# typed: strict
+
+require 'colorized_string'
+
+module UsePackwerk
+  module Logging
+    extend T::Sig
+
+    sig { params(title: String, block: T.proc.void).void }
+    def self.section(title, &block)
+      print_divider
+      puts ColorizedString.new("#{title}").green.bold
+      puts "\n"
+      yield
+    end
+
+    sig { params(text: String).void }
+    def self.print_bold_green(text)
+      puts ColorizedString.new(text).green.bold
+    end
+
+    sig { params(text: String).void }
+    def self.print(text)
+      puts text
+    end
+
+    sig { void }
+    def self.print_divider
+      puts '=' * 100
+    end
+  end
+end
+

data/lib/use_packwerk/per_file_processor_interface.rb

@@ -0,0 +1,19 @@
+# typed: strict
+
+module UsePackwerk
+  module PerFileProcessorInterface
+    extend T::Sig
+    extend T::Helpers
+
+    abstract!
+
+    sig { abstract.params(file_move_operation: Private::FileMoveOperation).void }
+    def before_move_file!(file_move_operation)
+    end
+
+    sig { void }
+    def print_final_message!
+      nil
+    end
+  end
+end

data/lib/use_packwerk/private/file_move_operation.rb

@@ -0,0 +1,77 @@
+# typed: strict
+
+module UsePackwerk
+  module Private
+    class FileMoveOperation < T::Struct
+      extend T::Sig
+
+      const :origin_pathname, Pathname
+      const :destination_pathname, Pathname
+      const :destination_pack, ParsePackwerk::Package
+
+      sig { params(origin_pathname: Pathname, new_package_root: Pathname).returns(Pathname) }
+      def self.destination_pathname_for_package_move(origin_pathname, new_package_root)
+        parts = origin_pathname.to_s.split('/')
+        toplevel_directory = parts[0]
+
+        case toplevel_directory.to_s
+        # This allows us to move files from monolith to packs
+        when 'app', 'spec', 'lib'
+          new_package_root.join(origin_pathname).cleanpath
+        # This allows us to move files from packs to packs
+        when *PERMITTED_PACK_LOCATIONS # parts looks like ['packs', 'organisms', 'app', 'services', 'bird_like', 'eagle.rb']
+          new_package_root.join(T.must(parts[2..]).join('/')).cleanpath
+        else
+          raise StandardError.new("Don't know how to find destination path for #{origin_pathname.inspect}")
+        end
+      end
+
+      sig { params(origin_pathname: Pathname).returns(Pathname) }
+      def self.destination_pathname_for_new_public_api(origin_pathname)
+        parts = origin_pathname.to_s.split('/')
+        toplevel_directory = Pathname.new(parts[0])
+
+        case toplevel_directory.to_s
+        # This allows us to make API in the monolith public
+        when 'app', 'spec'
+          toplevel_directory.join('public').join(T.must(parts[2..]).join('/')).cleanpath
+        # This allows us to make API in existing packs public
+        when *PERMITTED_PACK_LOCATIONS # parts looks like ['packs', 'organisms', 'app', 'services', 'bird_like', 'eagle.rb']
+          pack_name = Pathname.new(parts[1])
+          toplevel_directory.join(pack_name).join('app/public').join(T.must(parts[4..]).join('/')).cleanpath
+        else
+          raise StandardError.new("Don't know how to find destination path for #{origin_pathname.inspect}")
+        end
+      end
+
+      sig { returns(FileMoveOperation) }
+      def spec_file_move_operation
+        # This could probably be implemented by some "strategy pattern" where different extension types are handled by different helpers
+        # Such a thing could also include, for example, when moving a controller, moving its ERB view too.
+        if origin_pathname.extname == '.rake'
+          new_origin_pathname = origin_pathname.sub('/lib/', '/spec/lib/').sub(/^lib\//, 'spec/lib/').sub('.rake', '_spec.rb')
+          new_destination_pathname = destination_pathname.sub('/lib/', '/spec/lib/').sub(/^lib\//, 'spec/lib/').sub('.rake', '_spec.rb')
+        else
+          new_origin_pathname = origin_pathname.sub('/app/', '/spec/').sub(/^app\//, 'spec/').sub('.rb', '_spec.rb')
+          new_destination_pathname = destination_pathname.sub('/app/', '/spec/').sub(/^app\//, 'spec/').sub('.rb', '_spec.rb')
+        end
+        FileMoveOperation.new(
+          origin_pathname: new_origin_pathname,
+          destination_pathname: new_destination_pathname,
+          destination_pack: destination_pack,
+        )
+      end
+
+      private
+
+      sig { params(path: Pathname).returns(FileMoveOperation) }
+      def relative_to(path)
+        FileMoveOperation.new(
+          origin_pathname: origin_pathname.relative_path_from(path),
+          destination_pathname: destination_pathname.relative_path_from(path),
+          destination_pack: destination_pack,
+        )
+      end
+    end
+  end
+end

data/lib/use_packwerk/private/pack_relationship_analyzer.rb

@@ -0,0 +1,219 @@
+# typed: strict
+
+module UsePackwerk
+  module Private
+    module PackRelationshipAnalyzer
+      extend T::Sig
+
+      sig do
+        params(
+          pack_name: T.nilable(String),
+          limit: Integer,
+        ).void
+      end
+      def self.list_top_privacy_violations(pack_name, limit)
+        all_packages = ParsePackwerk.all
+        if !pack_name.nil?
+          pack_name = Private.clean_pack_name(pack_name)
+          package = all_packages.find { |package| package.name == pack_name }
+          if package.nil?
+            raise StandardError.new("Can not find package with name #{pack_name}. Make sure the argument is of the form `packs/my_pack/`")
+          end
+
+          pack_specific_content = <<~PACK_CONTENT
+            You are listing top #{limit} privacy violations for #{pack_name}. See #{UsePackwerk.config.documentation_link} for other utilities!
+            Pass in a limit to display more or less, e.g. `bin/list_top_privacy_violations -n #{pack_name} -l 1000`
+
+            This script is intended to help you find which of YOUR pack's private classes, constants, or modules other packs are using the most.
+            Anything not in #{pack_name}/app/public is considered private API.
+          PACK_CONTENT
+
+          to_package_names = [pack_name]
+        else
+          pack_specific_content = <<~PACK_CONTENT
+            You are listing top #{limit} privacy violations for all packs. See #{UsePackwerk.config.documentation_link} for other utilities!
+            Pass in a limit to display more or less, e.g. `bin/list_top_privacy_violations -n #{pack_name} -l 1000`
+
+            This script is intended to help you find which of YOUR pack's private classes, constants, or modules other packs are using the most.
+            Anything not in pack_name/app/public is considered private API.
+          PACK_CONTENT
+
+          to_package_names = all_packages.map(&:name)
+        end
+
+        violations_by_count = {}
+        total_pack_violation_count = 0
+
+        Logging.section('👋 Hi there') do
+          intro = <<~INTRO
+            #{pack_specific_content}
+
+            When using this script, ask yourself some questions like:
+            - What do I want to support?
+            - What do I *not* want to support?
+            - What is considered simply an implementation detail, and what is essential to the behavior of my pack?
+            - What is a simple, minimialistic API for clients to engage with the behavior of your pack?
+            - How do I ensure my public API is not coupled to specific client's use cases?
+
+            Looking at privacy violations can help guide the development of your public API, but it is just the beginning!
+
+            The script will output in the following format:
+
+            SomeConstant # This is the name of a class, constant, or module defined in your pack, outside of app/public
+              - Total Count: 5 # This is the total number of uses of this outside your pack
+              - By package: # This is a breakdown of the use of this constant by other packages
+                # This is the number of files in this pack that this constant is used.
+                # Check `packs/other_pack_a/deprecated_references.yml` under the '#{pack_name}'.'SomeConstant' key to see where this constant is used
+                - packs/other_pack_a: 3
+                - packs/other_pack_b: 2
+            SomeClass # This is the second most violated class, constant, or module defined in your pack
+              - Total Count: 2
+              - By package:
+                - packs/other_pack_a: 1
+                - packs/other_pack_b: 1
+
+            Lastly, remember you can use `bin/make_public -f #{pack_name}/path/to/file.rb` to make your class, constant, or module public API.
+          INTRO
+          Logging.print_bold_green(intro)
+        end
+
+        # TODO: This is a copy of the implementation below. We may want to refactor out this implementation detail before making changes that apply to both.
+        all_packages.each do |client_package|
+          PackageProtections::ProtectedPackage.from(client_package).violations.select(&:privacy?).each do |violation|
+            next unless to_package_names.include?(violation.to_package_name)
+            if pack_name.nil?
+              violated_symbol = "#{violation.class_name} (#{violation.to_package_name})"
+            else
+              violated_symbol = "#{violation.class_name}"
+            end
+            violations_by_count[violated_symbol] ||= {}
+            violations_by_count[violated_symbol][:total_count] ||= 0
+            violations_by_count[violated_symbol][:by_package] ||= {}
+            violations_by_count[violated_symbol][:by_package][client_package.name] ||= 0
+            violations_by_count[violated_symbol][:total_count] += violation.files.count
+            violations_by_count[violated_symbol][:by_package][client_package.name] += violation.files.count
+            total_pack_violation_count += violation.files.count
+          end
+        end
+
+        Logging.print("Total Count: #{total_pack_violation_count}")
+
+        sorted_violations = violations_by_count.sort_by { |violated_symbol, count_info| [-count_info[:total_count], violated_symbol] }
+        sorted_violations.first(limit).each do |violated_symbol, count_info|
+          percentage_of_total = (count_info[:total_count] * 100.0 / total_pack_violation_count).round(2)
+          Logging.print(violated_symbol)
+          Logging.print("  - Total Count: #{count_info[:total_count]} (#{percentage_of_total}% of total)")
+
+          Logging.print("  - By package:")
+          count_info[:by_package].sort_by{ |client_package_name, count| [-count, client_package_name] }.each do |client_package_name, count|
+            Logging.print("    - #{client_package_name}: #{count}")
+          end
+        end
+      end
+
+      sig do
+        params(
+          pack_name: T.nilable(String),
+          limit: Integer
+        ).void
+      end
+      def self.list_top_dependency_violations(pack_name, limit)
+        all_packages = ParsePackwerk.all
+
+        if !pack_name.nil?
+          pack_name = Private.clean_pack_name(pack_name)
+          package = all_packages.find { |package| package.name == pack_name }
+          if package.nil?
+            raise StandardError.new("Can not find package with name #{pack_name}. Make sure the argument is of the form `packs/my_pack/`")
+          end
+
+          pack_specific_content = <<~PACK_CONTENT
+            You are listing top #{limit} dependency violations for #{pack_name}. See #{UsePackwerk.config.documentation_link} for other utilities!
+            Pass in a limit to display more or less, e.g. `bin/list_top_dependency_violations -n #{pack_name} -l 1000`
+
+            This script is intended to help you find which of YOUR pack's private classes, constants, or modules other packs are using the most.
+            Anything not in #{pack_name}/app/public is considered private API.
+          PACK_CONTENT
+
+          to_package_names = [pack_name]
+        else
+          pack_specific_content = <<~PACK_CONTENT
+            You are listing top #{limit} dependency violations for all packs. See #{UsePackwerk.config.documentation_link} for other utilities!
+            Pass in a limit to display more or less, e.g. `bin/list_top_dependency_violations -n #{pack_name} -l 1000`
+
+            This script is intended to help you find which of YOUR pack's private classes, constants, or modules other packs are using the most.
+            Anything not in pack_name/app/public is considered private API.
+          PACK_CONTENT
+
+          to_package_names = all_packages.map(&:name)
+        end
+
+        violations_by_count = {}
+        total_pack_violation_count = 0
+
+        Logging.section('👋 Hi there') do
+          intro = <<~INTRO
+            #{pack_specific_content}
+
+            When using this script, ask yourself some questions like:
+            - What do I want to support?
+            - What do I *not* want to support?
+            - Which direction should a dependency go?
+            - What packs should depend on you, and what packs should not depend on you?
+            - Would it be simpler if other packs only depended on interfaces to your pack rather than implementation?
+
+            Looking at dependency violations can help guide the development of your public API, but it is just the beginning!
+
+            The script will output in the following format:
+
+            SomeConstant # This is the name of a class, constant, or module defined in your pack, outside of app/public
+              - Total Count: 5 # This is the total number of unstated uses of this outside your pack
+              - By package: # This is a breakdown of the use of this constant by other packages
+                # This is the number of files in this pack that this constant is used.
+                # Check `packs/other_pack_a/deprecated_references.yml` under the '#{pack_name}'.'SomeConstant' key to see where this constant is used
+                - packs/other_pack_a: 3
+                - packs/other_pack_b: 2
+            SomeClass # This is the second most violated class, constant, or module defined in your pack
+              - Total Count: 2
+              - By package:
+                - packs/other_pack_a: 1
+                - packs/other_pack_b: 1
+          INTRO
+          Logging.print_bold_green(intro)
+        end
+
+        # TODO: This is a copy of the implementation above. We may want to refactor out this implementation detail before making changes that apply to both.
+        all_packages.each do |client_package|
+          PackageProtections::ProtectedPackage.from(client_package).violations.select(&:dependency?).each do |violation|
+            next unless to_package_names.include?(violation.to_package_name)
+            if pack_name.nil?
+              violated_symbol = "#{violation.class_name} (#{violation.to_package_name})"
+            else
+              violated_symbol = "#{violation.class_name}"
+            end
+            violations_by_count[violated_symbol] ||= {}
+            violations_by_count[violated_symbol][:total_count] ||= 0
+            violations_by_count[violated_symbol][:by_package] ||= {}
+            violations_by_count[violated_symbol][:by_package][client_package.name] ||= 0
+            violations_by_count[violated_symbol][:total_count] += violation.files.count
+            violations_by_count[violated_symbol][:by_package][client_package.name] += violation.files.count
+            total_pack_violation_count += violation.files.count
+          end
+        end
+
+        Logging.print("Total Count: #{total_pack_violation_count}")
+
+        sorted_violations = violations_by_count.sort_by { |violated_symbol, count_info| [-count_info[:total_count], violated_symbol] }
+        sorted_violations.first(limit).each do |violated_symbol, count_info|
+          percentage_of_total = (count_info[:total_count] * 100.0 / total_pack_violation_count).round(2)
+          Logging.print(violated_symbol)
+          Logging.print("  - Total Count: #{count_info[:total_count]} (#{percentage_of_total}% of total)")
+          Logging.print("  - By package:")
+          count_info[:by_package].sort_by{ |client_package_name, count| [-count, client_package_name] }.each do |client_package_name, count|
+            Logging.print("    - #{client_package_name}: #{count}")
+          end
+        end
+      end
+    end
+  end
+end