use_packs 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 88d0834366bd3d1591029828eab623a5781f0ed44a3b8c0b35ab92f131236377
+  data.tar.gz: 8f3dd5181a41f8bd3ff2441fc58c73bac8ec712137a5967b7447d62b9014d653
+SHA512:
+  metadata.gz: 3cb7be9b2014cc3c065d700e19472821acda6b9a41fe73cdf695e52d2d96ee1552aabaf2e123c8f4d4b21c1b469cb26073e8eaa650874d6ded5fbdb63c3a401e
+  data.tar.gz: 6a6a15f8f010a10988eae52796bbbf55326c7a814bc1d0ec3a550edd860cc038fb7eb917860e7629cae1d6b2462901296b5bb163857b3cf955a7c93b6d9ffe21

data/README.md

@@ -0,0 +1,71 @@
+# UsePacks
+
+UsePacks 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/packs --help` or just `bin/packs` to enter interactive mode.
+
+### Pack Creation
+`bin/packs create packs/your_pack_name_here`
+
+### Moving files to packs
+`bin/packs move packs/your_pack_name_here 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/packs make_public 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/packs list_top_privacy_violations 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/packs list_top_dependency_violations 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/packs add_dependency packs/my_pack 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.
+
+### Setting up Spring
+
+[Spring](https://github.com/rails/spring) is a preloader for Rails. Although `use_packs` itself does not use `Rails`, this can help speed up running commands like `bin/packs` by caching the bundle.
+Firstly, spring needs to know about the `bin/packs` command when spring is loading. To do that, add `require 'use_packs/spring_command'` to `config/spring.rb` in your application.
+Secondly, to enable Spring, first run `bin/spring binstub packs` which will "springify" the generated binstub.
+
+### Releasing
+Releases happen automatically through github actions once a version update is committed to `main`.
+
+## Discussions, Issues, Questions, and More
+To keep things organized, here are some recommended homes:
+
+### Issues:
+https://github.com/Gusto/use_packs/issues
+
+### Questions:
+https://github.com/Gusto/use_packs/discussions/categories/q-a
+
+### General discussions:
+https://github.com/Gusto/use_packs/discussions/categories/general
+
+### Ideas, new features, requests for change:
+https://github.com/Gusto/use_packs/discussions/categories/ideas
+
+### Showcasing your work:
+https://github.com/Gusto/use_packs/discussions/categories/show-and-tell

data/bin/packs

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# typed: strict
+
+require_relative '../lib/use_packs'
+
+if ARGV.empty?
+  UsePacks.start_interactive_mode!
+else
+  UsePacks::CLI.start(ARGV)
+end

data/bin/rubocop

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rubocop', 'rubocop')

data/bin/tapioca

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'tapioca' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('tapioca', 'tapioca')

data/lib/use_packs/cli.rb

@@ -0,0 +1,127 @@
+# typed: strict
+
+require 'thor'
+
+module UsePacks
+  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)
+      UsePacks.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/packs 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)
+      UsePacks.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)
+      UsePacks.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)
+      UsePacks.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)
+      UsePacks.make_public!(
+        paths_relative_to_root: paths,
+        per_file_processors: [UsePacks::RubocopPostProcessor.new, UsePacks::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)
+      UsePacks.move_to_pack!(
+        pack_name: pack_name,
+        paths_relative_to_root: paths,
+        per_file_processors: [UsePacks::RubocopPostProcessor.new, UsePacks::CodeOwnershipPostProcessor.new]
+      )
+    end
+
+    desc 'move_to_parent packs/parent_pack packs/child_pack', 'Pass in a parent pack and another pack to be made as a child to the parent pack!'
+    sig { params(parent_name: String, pack_name: String).void }
+    def move_to_parent(parent_name, pack_name)
+      UsePacks.move_to_parent!(
+        parent_name: parent_name,
+        pack_name: pack_name,
+        per_file_processors: [UsePacks::RubocopPostProcessor.new, UsePacks::CodeOwnershipPostProcessor.new]
+      )
+    end
+
+    desc 'lint_deprecated_references_yml_files', 'Ensures `deprecated_references.yml` files are up to date'
+    sig { void }
+    def lint_deprecated_references_yml_files
+      UsePacks.lint_deprecated_references_yml_files!
+    end
+
+    desc 'lint_package_yml_files [ packs/my_pack packs/my_other_pack ]', 'Lint `package.yml` files'
+    sig { params(pack_names: String).void }
+    def lint_package_yml_files(*pack_names)
+      UsePacks.lint_package_yml_files!(parse_pack_names(pack_names))
+    end
+
+    desc 'validate', 'Run bin/packwerk validate (detects cycles)'
+    sig { void }
+    def validate
+      system('bin/packwerk validate')
+    end
+
+    desc 'check [ packs/my_pack ]', 'Run bin/packwerk check'
+    sig { params(paths: String).void }
+    def check(*paths)
+      system("bin/packwerk check #{paths.join(' ')}")
+    end
+
+    desc 'update [ packs/my_pack ]', 'Run bin/packwerk update-deprecations'
+    sig { params(paths: String).void }
+    def update(*paths)
+      system("bin/packwerk update-deprecations #{paths.join(' ')}")
+    end
+
+    desc 'regenerate_rubocop_todo [ packs/my_pack packs/my_other_pack ]', "Regenerate packs/*/#{RuboCop::Packs::PACK_LEVEL_RUBOCOP_TODO_YML} for one or more packs"
+    sig { params(pack_names: String).void }
+    def regenerate_rubocop_todo(*pack_names)
+      RuboCop::Packs.regenerate_todo(packs: parse_pack_names(pack_names))
+    end
+
+    private
+
+    # This is used by thor to know that these private methods are not intended to be CLI commands
+    no_commands do
+      sig { params(pack_names: T::Array[String]).returns(T::Array[ParsePackwerk::Package]) }
+      def parse_pack_names(pack_names)
+        pack_names.empty? ? ParsePackwerk.all : pack_names.map { |p| ParsePackwerk.find(p.gsub(%r{/$}, '')) }.compact
+      end
+    end
+  end
+end

data/lib/use_packs/code_ownership_post_processor.rb

@@ -0,0 +1,58 @@
+# typed: strict
+
+module UsePacks
+  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?
+        UsePacks.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 { params(file_move_operations: T::Array[Private::FileMoveOperation]).void }
+    def after_move_files!(file_move_operations)
+      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_packs/configuration.rb

@@ -0,0 +1,61 @@
+# typed: strict
+
+require 'use_packs/user_event_logger'
+require 'use_packs/default_user_event_logger'
+
+module UsePacks
+  class Configuration
+    extend T::Sig
+
+    sig { params(enforce_dependencies: T::Boolean).void }
+    attr_writer :enforce_dependencies
+
+    sig { returns(UserEventLogger) }
+    attr_accessor :user_event_logger
+
+    OnDeprecatedReferencesLintFailure = T.type_alias do
+      T.proc.params(output: String).void
+    end
+
+    sig { returns(OnDeprecatedReferencesLintFailure) }
+    attr_accessor :on_deprecated_references_lint_failure
+
+    sig { void }
+    def initialize
+      @enforce_dependencies = T.let(default_enforce_dependencies, T::Boolean)
+      @user_event_logger = T.let(DefaultUserEventLogger.new, UserEventLogger)
+      @on_deprecated_references_lint_failure = T.let(->(output) {}, OnDeprecatedReferencesLintFailure)
+    end
+
+    sig { returns(T::Boolean) }
+    def enforce_dependencies
+      @enforce_dependencies
+    end
+
+    sig { void }
+    def bust_cache!
+      @enforce_dependencies = default_enforce_dependencies
+    end
+
+    sig { returns(T::Boolean) }
+    def default_enforce_dependencies
+      true
+    end
+  end
+
+  class << self
+    extend T::Sig
+
+    sig { returns(Configuration) }
+    def config
+      Private.load_client_configuration
+      @config = T.let(@config, T.nilable(Configuration))
+      @config ||= Configuration.new
+    end
+
+    sig { params(blk: T.proc.params(arg0: Configuration).void).void }
+    def configure(&blk)
+      yield(config)
+    end
+  end
+end

data/lib/use_packs/default_user_event_logger.rb

@@ -0,0 +1,7 @@
+# typed: strict
+
+module UsePacks
+  class DefaultUserEventLogger
+    include UserEventLogger
+  end
+end

data/lib/use_packs/logging.rb

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

data/lib/use_packs/per_file_processor_interface.rb

@@ -0,0 +1,18 @@
+# typed: strict
+
+module UsePacks
+  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 { params(file_move_operations: T::Array[Private::FileMoveOperation]).void }
+    def after_move_files!(file_move_operations)
+      nil
+    end
+  end
+end

data/lib/use_packs/private/file_move_operation.rb

@@ -0,0 +1,80 @@
+# typed: strict
+
+module UsePacks
+  module Private
+    class FileMoveOperation < T::Struct
+      extend T::Sig
+
+      const :origin_pathname, Pathname
+      const :destination_pathname, Pathname
+      const :destination_pack, ParsePackwerk::Package
+
+      sig { returns(ParsePackwerk::Package) }
+      def origin_pack
+        ParsePackwerk.package_from_path(origin_pathname)
+      end
+
+      sig { params(origin_pathname: Pathname, new_package_root: Pathname).returns(Pathname) }
+      def self.destination_pathname_for_package_move(origin_pathname, new_package_root)
+        origin_pack = ParsePackwerk.package_from_path(origin_pathname)
+
+        if origin_pack.name == ParsePackwerk::ROOT_PACKAGE_NAME
+          new_package_root.join(origin_pathname).cleanpath
+        else
+          Pathname.new(origin_pathname.to_s.gsub(origin_pack.name, new_package_root.to_s)).cleanpath
+        end
+      end
+
+      sig { params(origin_pathname: Pathname).returns(Pathname) }
+      def self.destination_pathname_for_new_public_api(origin_pathname)
+        origin_pack = ParsePackwerk.package_from_path(origin_pathname)
+        if origin_pack.name == ParsePackwerk::ROOT_PACKAGE_NAME
+          filepath_without_pack_name = origin_pathname.to_s
+        else
+          filepath_without_pack_name = origin_pathname.to_s.gsub("#{origin_pack.name}/", '')
+        end
+
+        # We join the pack name with the rest of the path...
+        path_parts = filepath_without_pack_name.split('/')
+        Pathname.new(origin_pack.name).join(
+          # ... keeping the "app" or "spec"
+          T.must(path_parts[0]),
+          # ... substituting "controllers," "services," etc. with "public"
+          'public',
+          # ... then the rest is the same
+          T.must(path_parts[2..]).join('/')
+          # and we take the cleanpath so `./app/...` becomes `app/...`
+        ).cleanpath
+      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(%r{^lib/}, 'spec/lib/').sub('.rake', '_spec.rb')
+          new_destination_pathname = destination_pathname.sub('/lib/', '/spec/lib/').sub(%r{^lib/}, 'spec/lib/').sub('.rake', '_spec.rb')
+        else
+          new_origin_pathname = origin_pathname.sub('/app/', '/spec/').sub(%r{^app/}, 'spec/').sub('.rb', '_spec.rb')
+          new_destination_pathname = destination_pathname.sub('/app/', '/spec/').sub(%r{^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_packs/private/interactive_cli/pack_selector.rb

@@ -0,0 +1,34 @@
+# typed: strict
+
+module UsePacks
+  module Private
+    module InteractiveCli
+      class PackSelector
+        extend T::Sig
+
+        sig { params(prompt: TTY::Prompt, question_text: String).returns(ParsePackwerk::Package) }
+        def self.single_pack_select(prompt, question_text: 'Please select a pack')
+          packs = ParsePackwerk.all.to_h { |t| [t.name, t] }
+          prompt.select(
+            question_text,
+            packs,
+            filter: true,
+            per_page: 10,
+            show_help: :always
+          )
+        end
+
+        sig { params(prompt: TTY::Prompt, question_text: String).returns(T::Array[ParsePackwerk::Package]) }
+        def self.single_or_all_pack_multi_select(prompt, question_text: 'Please select one or more packs')
+          prompt.multi_select(
+            question_text,
+            ParsePackwerk.all.to_h { |t| [t.name, t] },
+            filter: true,
+            per_page: 10,
+            show_help: :always
+          )
+        end
+      end
+    end
+  end
+end

data/lib/use_packs/private/interactive_cli/team_selector.rb

@@ -0,0 +1,35 @@
+# typed: strict
+
+module UsePacks
+  module Private
+    module InteractiveCli
+      class TeamSelector
+        extend T::Sig
+
+        sig { params(prompt: TTY::Prompt, question_text: String).returns(CodeTeams::Team) }
+        def self.single_select(prompt, question_text: 'Please select a team owner')
+          teams = CodeTeams.all.sort_by(&:name).to_h { |t| [t.name, t] }
+          prompt.select(
+            question_text,
+            teams,
+            filter: true,
+            per_page: 10,
+            show_help: :always
+          )
+        end
+
+        sig { params(prompt: TTY::Prompt, question_text: String).returns(T::Array[CodeTeams::Team]) }
+        def self.multi_select(prompt, question_text: 'Please select team owners')
+          teams = CodeTeams.all.to_h { |t| [t.name, t] }
+          prompt.multi_select(
+            question_text,
+            teams,
+            filter: true,
+            per_page: 10,
+            show_help: :always
+          )
+        end
+      end
+    end
+  end
+end

data/lib/use_packs/private/interactive_cli/use_cases/add_dependency.rb

@@ -0,0 +1,30 @@
+# typed: strict
+
+module UsePacks
+  module Private
+    module InteractiveCli
+      module UseCases
+        class AddDependency
+          extend T::Sig
+          extend T::Helpers
+          include Interface
+
+          sig { override.params(prompt: TTY::Prompt).void }
+          def perform!(prompt)
+            dependent_pack = PackSelector.single_pack_select(prompt, question_text: 'Please select the pack you are adding a dependency to.')
+            dependency_pack = PackSelector.single_pack_select(prompt, question_text: "Please select the pack that #{dependent_pack.name} should depend on.")
+            UsePacks.add_dependency!(
+              pack_name: dependent_pack.name,
+              dependency_name: dependency_pack.name
+            )
+          end
+
+          sig { override.returns(String) }
+          def user_facing_name
+            'Add a dependency'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/use_packs/private/interactive_cli/use_cases/check.rb

@@ -0,0 +1,25 @@
+# typed: strict
+
+module UsePacks
+  module Private
+    module InteractiveCli
+      module UseCases
+        class Check
+          extend T::Sig
+          extend T::Helpers
+          include Interface
+
+          sig { override.returns(String) }
+          def user_facing_name
+            'Run bin/packwerk check'
+          end
+
+          sig { override.params(prompt: TTY::Prompt).void }
+          def perform!(prompt)
+            system('bin/packwerk check')
+          end
+        end
+      end
+    end
+  end
+end