use_packwerk 0.55.0 → 0.57.0

data/lib/use_packwerk/user_event_logger.rb

@@ -0,0 +1,265 @@
+# typed: strict
+
+module UsePackwerk
+  module UserEventLogger
+    extend T::Sig
+    extend T::Helpers
+
+    abstract!
+
+    sig { params(pack_name: String).returns(String) }
+    def before_create_pack(pack_name)
+      <<~MSG
+        You are creating a pack, which is great. Check out #{documentation_link} for more info!
+      MSG
+    end
+
+    sig { params(pack_name: String).returns(String) }
+    def after_create_pack(pack_name)
+      <<~MSG
+        Your next steps might be:
+
+        1) Move files into your pack with `bin/use_packwerk move #{pack_name} path/to/file.rb`
+
+        2) Run `bin/packwerk update-deprecations` to update the violations. Make sure to run `spring stop` if you've added new load paths (new top-level directories) in your pack.
+
+        3) Update TODO lists for rubocop implemented protections. See #{documentation_link} for more info
+
+        4) Expose public API in #{pack_name}/app/public. Try `bin/use_packwerk make_public #{pack_name}/path/to/file.rb`
+
+        5) Update your readme at #{pack_name}/README.md
+      MSG
+    end
+
+    sig { params(pack_name: String).returns(String) }
+    def before_move_to_pack(pack_name)
+      <<~MSG
+        You are moving a file to a pack, which is great. Check out #{documentation_link} for more info!
+      MSG
+    end
+
+    sig { params(pack_name: String).returns(String) }
+    def after_move_to_pack(pack_name)
+      <<~MSG
+        Your next steps might be:
+
+        1) Run `bin/packwerk update-deprecations` to update the violations. Make sure to run `spring stop` if you've added new load paths (new top-level directories) in your pack.
+
+        2) Update TODO lists for rubocop implemented protections. See #{documentation_link} for more info
+
+        3) Touch base with each team who owns files involved in this move
+
+        4) Expose public API in #{pack_name}/app/public. Try `bin/use_packwerk make_public #{pack_name}/path/to/file.rb`
+
+        5) Update your readme at #{pack_name}/README.md
+      MSG
+    end
+
+    sig { returns(String) }
+    def before_make_public
+      <<~MSG
+        You are moving some files into public API. See #{documentation_link} for other utilities!
+      MSG
+    end
+
+    sig { returns(String) }
+    def after_make_public
+      <<~MSG
+        Your next steps might be:
+
+        1) Run `bin/packwerk update-deprecations` to update the violations. Make sure to run `spring stop` if you've added new load paths (new top-level directories) in your pack.
+
+        2) Update TODO lists for rubocop implemented protections. See #{documentation_link} for more info
+
+        3) Work to migrate clients of private API to your new public API
+
+        4) Update your README at packs/your_package_name/README.md
+      MSG
+    end
+
+    sig { params(pack_name: String).returns(String) }
+    def before_add_dependency(pack_name)
+      <<~MSG
+        You are adding a dependency. See #{documentation_link} for other utilities!
+      MSG
+    end
+
+    sig { params(pack_name: String).returns(String) }
+    def after_add_dependency(pack_name)
+      <<~MSG
+        Your next steps might be:
+
+        1) Run `bin/packwerk validate` to ensure you haven't introduced a cyclic dependency
+
+        2) Run `bin/packwerk update-deprecations` to update the violations.
+      MSG
+    end
+
+    sig { params(pack_name: String).returns(String) }
+    def before_move_to_parent(pack_name)
+      <<~MSG
+        You are moving one pack to be a child of a different pack. Check out #{documentation_link} for more info!
+      MSG
+    end
+
+    sig { params(pack_name: String).returns(String) }
+    def after_move_to_parent(pack_name)
+      <<~MSG
+        Your next steps might be:
+
+        1) Delete the old pack when things look good: `rm -rf #{pack_name}`
+
+        2) Run `bin/packwerk update-deprecations` to update the violations. Make sure to run `spring stop` first.
+      MSG
+    end
+
+    sig { params(pack_name: String).returns(String) }
+    def on_create_public_directory_todo(pack_name)
+      <<~MSG
+        This directory holds your public API!
+
+        Any classes, constants, or modules that you want other packs to use and you intend to support should go in here.
+        Anything that is considered private should go in other folders.
+
+        If another pack uses classes, constants, or modules that are not in your public folder, it will be considered a "privacy violation" by packwerk.
+        You can prevent other packs from using private API by using package_protections.
+
+        Want to find how your private API is being used today?
+        Try running: `bin/use_packwerk list_top_privacy_violations #{pack_name}`
+
+        Want to move something into this folder?
+        Try running: `bin/use_packwerk make_public #{pack_name}/path/to/file.rb`
+
+        One more thing -- feel free to delete this file and replace it with a README.md describing your package in the main package directory.
+
+        See #{documentation_link} for more info!
+      MSG
+    end
+
+    sig { params(pack_name: String).returns(String) }
+    def on_create_readme_todo(pack_name)
+      <<~MSG
+        Welcome to `#{pack_name}`!
+
+        If you're the author, please consider replacing this file with a README.md, which may contain:
+        - What your pack is and does
+        - How you expect people to use your pack
+        - Example usage of your pack's public API (which lives in `#{pack_name}/app/public`)
+        - Limitations, risks, and important considerations of usage
+        - How to get in touch with eng and other stakeholders for questions or issues pertaining to this pack (note: it is recommended to add ownership in `#{pack_name}/package.yml` under the `owner` metadata key)
+        - What SLAs/SLOs (service level agreements/objectives), if any, your package provides
+        - When in doubt, keep it simple
+        - Anything else you may want to include!
+
+        README.md files are under version control and should change as your public API changes.#{' '}
+
+        See #{documentation_link} for more info!
+      MSG
+    end
+
+    sig { params(pack_name: T.nilable(String), limit: Integer).returns(String) }
+    def before_list_top_dependency_violations(pack_name, limit)
+      if pack_name.nil?
+        pack_specific_content = <<~PACK_CONTENT
+          You are listing top #{limit} dependency violations for all packs. See #{documentation_link} for other utilities!
+          Pass in a limit to display more or less, e.g. `use_packwerk list_top_dependency_violations #{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
+      else
+        pack_specific_content = <<~PACK_CONTENT
+          You are listing top #{limit} dependency violations for #{pack_name}. See #{documentation_link} for other utilities!
+          Pass in a limit to display more or less, e.g. `bin/use_packwerk list_top_dependency_violations #{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
+      end
+
+      <<~MSG
+        #{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
+      MSG
+    end
+
+    sig { params(pack_name: T.nilable(String), limit: Integer).returns(String) }
+    def before_list_top_privacy_violations(pack_name, limit)
+      if pack_name.nil?
+        pack_specific_content = <<~PACK_CONTENT
+          You are listing top #{limit} privacy violations for all packs. See #{documentation_link} for other utilities!
+          Pass in a limit to display more or less, e.g. `bin/use_packwerk list_top_privacy_violations #{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
+      else
+        pack_specific_content = <<~PACK_CONTENT
+          You are listing top #{limit} privacy violations for #{pack_name}. See #{documentation_link} for other utilities!
+          Pass in a limit to display more or less, e.g. `bin/use_packwerk list_top_privacy_violations #{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
+      end
+
+      <<~MSG
+        #{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/use_packwerk make_public #{pack_name}/path/to/file.rb` to make your class, constant, or module public API.
+      MSG
+    end
+
+    sig { returns(String) }
+    def documentation_link
+      'https://github.com/rubyatscale/use_packwerk#readme'
+    end
+  end
+end

data/lib/use_packwerk.rb

@@ -24,28 +24,36 @@ require 'use_packwerk/cli'
 module UsePackwerk
   extend T::Sig
 
-  PERMITTED_PACK_LOCATIONS = T.let([
-    'gems',
-    'components',
-    'packs',
-  ], T::Array[String])
+  PERMITTED_PACK_LOCATIONS = T.let(%w[
+                                     gems
+                                     components
+                                     packs
+                                   ], T::Array[String])
+
+  sig { void }
+  def self.start_interactive_mode!
+    Private::InteractiveCli.start!
+  end
 
   sig do
     params(
       pack_name: String,
       enforce_privacy: T::Boolean,
-      enforce_dependencies: T.nilable(T::Boolean)
+      enforce_dependencies: T.nilable(T::Boolean),
+      team: T.nilable(CodeTeams::Team)
     ).void
   end
   def self.create_pack!(
     pack_name:,
     enforce_privacy: true,
-    enforce_dependencies: nil
+    enforce_dependencies: nil,
+    team: nil
   )
     Private.create_pack!(
       pack_name: pack_name,
       enforce_privacy: enforce_privacy,
-      enforce_dependencies: enforce_dependencies, 
+      enforce_dependencies: enforce_dependencies,
+      team: team
     )
   end
 
@@ -53,7 +61,7 @@ module UsePackwerk
     params(
       pack_name: String,
       paths_relative_to_root: T::Array[String],
-      per_file_processors: T::Array[PerFileProcessorInterface],
+      per_file_processors: T::Array[PerFileProcessorInterface]
     ).void
   end
   def self.move_to_pack!(
@@ -62,36 +70,18 @@ module UsePackwerk
     per_file_processors: []
   )
     Logging.section('👋 Hi!') do
-      intro = <<~INTRO
-        You are moving a file to a pack, which is great. Check out #{UsePackwerk.config.documentation_link} for more info!
-
-        Please bring any questions or issues you have in your development process to #ruby-modularity or #product-infrastructure.
-        We'd be happy to try to help through pairing, accepting feedback, changing our process, changing our tools, and more.
-      INTRO
+      intro = UsePackwerk.config.user_event_logger.before_move_to_pack(pack_name)
       Logging.print_bold_green(intro)
     end
 
     Private.move_to_pack!(
       pack_name: pack_name,
       paths_relative_to_root: paths_relative_to_root,
-      per_file_processors: per_file_processors,
+      per_file_processors: per_file_processors
     )
 
     Logging.section('Next steps') do
-      next_steps = <<~NEXT_STEPS
-        Your next steps might be:
-
-        1) Run `bin/packwerk update-deprecations` to update the violations. Make sure to run `spring stop` if you've added new load paths (new top-level directories) in your pack.
-
-        2) Update TODO lists for rubocop implemented protections. See #{UsePackwerk.config.documentation_link} for more info
-
-        3) Touch base with each team who owns files involved in this move
-
-        4) Expose public API in #{pack_name}/app/public. Try `bin/use_packwerk make_public #{pack_name}/path/to/file.rb`
-
-        5) Update your readme at #{pack_name}/README.md
-      NEXT_STEPS
-
+      next_steps = UsePackwerk.config.user_event_logger.after_move_to_pack(pack_name)
       Logging.print_bold_green(next_steps)
     end
   end
@@ -99,7 +89,7 @@ module UsePackwerk
   sig do
     params(
       paths_relative_to_root: T::Array[String],
-      per_file_processors: T::Array[PerFileProcessorInterface],
+      per_file_processors: T::Array[PerFileProcessorInterface]
     ).void
   end
   def self.make_public!(
@@ -107,9 +97,7 @@ module UsePackwerk
     per_file_processors: []
   )
     Logging.section('Making files public') do
-      intro = <<~INTRO
-        You are moving some files into public API. See #{UsePackwerk.config.documentation_link} for other utilities!
-      INTRO
+      intro = UsePackwerk.config.user_event_logger.before_make_public
       Logging.print_bold_green(intro)
     end
 
@@ -117,20 +105,9 @@ module UsePackwerk
       paths_relative_to_root: paths_relative_to_root,
       per_file_processors: per_file_processors
     )
-  
-    Logging.section('Next steps') do
-      next_steps = <<~NEXT_STEPS
-        Your next steps might be:
-
-        1) Run `bin/packwerk update-deprecations` to update the violations. Make sure to run `spring stop` if you've added new load paths (new top-level directories) in your pack.
-
-        2) Update TODO lists for rubocop implemented protections. See #{UsePackwerk.config.documentation_link} for more info
-
-        3) Work to migrate clients of private API to your new public API
-
-        4) Update your README at packs/your_package_name/README.md
-      NEXT_STEPS
 
+    Logging.section('Next steps') do
+      next_steps = UsePackwerk.config.user_event_logger.after_make_public
       Logging.print_bold_green(next_steps)
     end
   end
@@ -146,9 +123,7 @@ module UsePackwerk
     dependency_name:
   )
     Logging.section('Adding a dependency') do
-      intro = <<~INTRO
-        You are adding a dependency. See #{UsePackwerk.config.documentation_link} for other utilities!
-      INTRO
+      intro = UsePackwerk.config.user_event_logger.before_add_dependency(pack_name)
       Logging.print_bold_green(intro)
     end
 
@@ -158,14 +133,7 @@ module UsePackwerk
     )
 
     Logging.section('Next steps') do
-      next_steps = <<~NEXT_STEPS
-        Your next steps might be:
-
-        1) Run `bin/packwerk validate` to ensure you haven't introduced a cyclic dependency
-
-        2) Run `bin/packwerk update-deprecations` to update the violations.
-      NEXT_STEPS
-
+      next_steps = UsePackwerk.config.user_event_logger.after_add_dependency(pack_name)
       Logging.print_bold_green(next_steps)
     end
   end
@@ -174,7 +142,7 @@ module UsePackwerk
     params(
       pack_name: String,
       parent_name: String,
-      per_file_processors: T::Array[PerFileProcessorInterface],
+      per_file_processors: T::Array[PerFileProcessorInterface]
     ).void
   end
   def self.move_to_parent!(
@@ -183,29 +151,18 @@ module UsePackwerk
     per_file_processors: []
   )
     Logging.section('👋 Hi!') do
-      intro = <<~INTRO
-        You are moving one pack to be a child of a different pack. Check out #{UsePackwerk.config.documentation_link} for more info!
-
-        Please bring any questions or issues you have in your development process to #ruby-modularity or #product-infrastructure.
-        We'd be happy to try to help through pairing, accepting feedback, changing our process, changing our tools, and more.
-      INTRO
+      intro = UsePackwerk.config.user_event_logger.before_move_to_parent(pack_name)
       Logging.print_bold_green(intro)
     end
 
     Private.move_to_parent!(
       pack_name: pack_name,
       parent_name: parent_name,
-      per_file_processors: per_file_processors,
+      per_file_processors: per_file_processors
     )
 
     Logging.section('Next steps') do
-      next_steps = <<~NEXT_STEPS
-        Your next steps might be:
-
-        1) Delete the old pack when things look good: `rm -rf #{pack_name}`
-
-        2) Run `bin/packwerk update-deprecations` to update the violations. Make sure to run `spring stop` first.
-      NEXT_STEPS
+      next_steps = UsePackwerk.config.user_event_logger.after_move_to_parent(pack_name)
 
       Logging.print_bold_green(next_steps)
     end
@@ -214,7 +171,7 @@ module UsePackwerk
   sig do
     params(
       pack_name: T.nilable(String),
-      limit: Integer,
+      limit: Integer
     ).void
   end
   def self.list_top_privacy_violations(
@@ -247,14 +204,19 @@ module UsePackwerk
     params(
       file: String,
       find: Pathname,
-      replace_with: Pathname,
+      replace_with: Pathname
     ).void
   end
   def self.replace_in_file(file:, find:, replace_with:)
     Private.replace_in_file(
       file: file,
       find: find,
-      replace_with: replace_with,
+      replace_with: replace_with
     )
   end
+
+  sig { void }
+  def self.bust_cache!
+    Private.bust_cache!
+  end
 end