use_packs 0.0.1

data/lib/use_packs/user_event_logger.rb

@@ -0,0 +1,259 @@
+# typed: strict
+
+module UsePacks
+  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/packs 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) Expose public API in #{pack_name}/app/public. Try `bin/packs make_public #{pack_name}/path/to/file.rb`
+
+        4) 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) Touch base with each team who owns files involved in this move
+
+        3) Expose public API in #{pack_name}/app/public. Try `bin/packs make_public #{pack_name}/path/to/file.rb`
+
+        4) 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) Work to migrate clients of private API to your new public API
+
+        3) 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 packwerk.
+
+        Want to find how your private API is being used today?
+        Try running: `bin/packs list_top_privacy_violations #{pack_name}`
+
+        Want to move something into this folder?
+        Try running: `bin/packs 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_packs 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/packs 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/packs 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/packs 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/packs 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_packs#readme'
+    end
+  end
+end

data/lib/use_packs.rb

@@ -0,0 +1,298 @@
+# typed: strict
+
+# Ruby internal requires
+require 'fileutils'
+
+# External gem requires
+require 'colorized_string'
+
+# Internal gem requires
+require 'parse_packwerk'
+require 'code_teams'
+require 'code_ownership'
+require 'rubocop-packs'
+
+# Private implementation requires
+require 'use_packs/private'
+require 'use_packs/per_file_processor_interface'
+require 'use_packs/rubocop_post_processor'
+require 'use_packs/code_ownership_post_processor'
+require 'use_packs/logging'
+require 'use_packs/configuration'
+require 'use_packs/cli'
+
+module UsePacks
+  extend T::Sig
+
+  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),
+      team: T.nilable(CodeTeams::Team)
+    ).void
+  end
+  def self.create_pack!(
+    pack_name:,
+    enforce_privacy: true,
+    enforce_dependencies: nil,
+    team: nil
+  )
+    Private.create_pack!(
+      pack_name: pack_name,
+      enforce_privacy: enforce_privacy,
+      enforce_dependencies: enforce_dependencies,
+      team: team
+    )
+  end
+
+  sig do
+    params(
+      pack_name: String,
+      paths_relative_to_root: T::Array[String],
+      per_file_processors: T::Array[PerFileProcessorInterface]
+    ).void
+  end
+  def self.move_to_pack!(
+    pack_name:,
+    paths_relative_to_root: [],
+    per_file_processors: []
+  )
+    Logging.section('👋 Hi!') do
+      intro = UsePacks.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
+    )
+
+    Logging.section('Next steps') do
+      next_steps = UsePacks.config.user_event_logger.after_move_to_pack(pack_name)
+      Logging.print_bold_green(next_steps)
+    end
+  end
+
+  sig do
+    params(
+      paths_relative_to_root: T::Array[String],
+      per_file_processors: T::Array[PerFileProcessorInterface]
+    ).void
+  end
+  def self.make_public!(
+    paths_relative_to_root: [],
+    per_file_processors: []
+  )
+    Logging.section('Making files public') do
+      intro = UsePacks.config.user_event_logger.before_make_public
+      Logging.print_bold_green(intro)
+    end
+
+    Private.make_public!(
+      paths_relative_to_root: paths_relative_to_root,
+      per_file_processors: per_file_processors
+    )
+
+    Logging.section('Next steps') do
+      next_steps = UsePacks.config.user_event_logger.after_make_public
+      Logging.print_bold_green(next_steps)
+    end
+  end
+
+  sig do
+    params(
+      pack_name: String,
+      dependency_name: String
+    ).void
+  end
+  def self.add_dependency!(
+    pack_name:,
+    dependency_name:
+  )
+    Logging.section('Adding a dependency') do
+      intro = UsePacks.config.user_event_logger.before_add_dependency(pack_name)
+      Logging.print_bold_green(intro)
+    end
+
+    Private.add_dependency!(
+      pack_name: pack_name,
+      dependency_name: dependency_name
+    )
+
+    Logging.section('Next steps') do
+      next_steps = UsePacks.config.user_event_logger.after_add_dependency(pack_name)
+      Logging.print_bold_green(next_steps)
+    end
+  end
+
+  sig do
+    params(
+      pack_name: String,
+      parent_name: String,
+      per_file_processors: T::Array[PerFileProcessorInterface]
+    ).void
+  end
+  def self.move_to_parent!(
+    pack_name:,
+    parent_name:,
+    per_file_processors: []
+  )
+    Logging.section('👋 Hi!') do
+      intro = UsePacks.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
+    )
+
+    Logging.section('Next steps') do
+      next_steps = UsePacks.config.user_event_logger.after_move_to_parent(pack_name)
+
+      Logging.print_bold_green(next_steps)
+    end
+  end
+
+  sig do
+    params(
+      pack_name: T.nilable(String),
+      limit: Integer
+    ).void
+  end
+  def self.list_top_privacy_violations(
+    pack_name:,
+    limit:
+  )
+    Private::PackRelationshipAnalyzer.list_top_privacy_violations(
+      pack_name,
+      limit
+    )
+  end
+
+  sig do
+    params(
+      pack_name: T.nilable(String),
+      limit: Integer
+    ).void
+  end
+  def self.list_top_dependency_violations(
+    pack_name:,
+    limit:
+  )
+    Private::PackRelationshipAnalyzer.list_top_dependency_violations(
+      pack_name,
+      limit
+    )
+  end
+
+  sig do
+    params(
+      file: String,
+      find: 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
+    )
+  end
+
+  sig { void }
+  def self.bust_cache!
+    Private.bust_cache!
+  end
+
+  #
+  # execute_command is like `run` except it does not `exit`
+  #
+  sig { params(argv: T.untyped, formatter: T.nilable(Packwerk::OffensesFormatter)).void }
+  def self.execute(argv, formatter = nil)
+    Private::PackwerkWrapper.with_safe_exit_if_no_files_found do
+      Private::PackwerkWrapper.packwerk_cli(formatter).execute_command(argv)
+    end
+  end
+
+  sig { params(files: T::Array[String]).returns(T::Array[Packwerk::ReferenceOffense]) }
+  def self.get_offenses_for_files(files)
+    formatter = Private::PackwerkWrapper::OffensesAggregatorFormatter.new
+    Private::PackwerkWrapper.packwerk_cli_execute_safely(['check', *files], formatter)
+    formatter.aggregated_offenses.compact
+  end
+
+  sig { params(files: T::Array[String]).returns(T::Array[Packwerk::ReferenceOffense]) }
+  def self.get_offenses_for_files_by_package(files)
+    packages = Private::PackwerkWrapper.package_names_for_files(files)
+    argv = ['check', '--packages', packages.join(',')]
+    formatter = Private::PackwerkWrapper::OffensesAggregatorFormatter.new
+    Private::PackwerkWrapper.packwerk_cli_execute_safely(argv, formatter)
+    formatter.aggregated_offenses.compact
+  end
+
+  sig { void }
+  def self.lint_deprecated_references_yml_files!
+    contents_before = Private.get_deprecated_references_contents
+    UsePacks.execute(['update-deprecations'])
+    contents_after = Private.get_deprecated_references_contents
+    diff = Private.diff_deprecated_references_yml(contents_before, contents_after)
+
+    if diff == ''
+      # No diff generated by `update-deprecations`
+      exit 0
+    else
+      output = <<~OUTPUT
+        All `deprecated_references.yml` files must be up-to-date and that no diff is generated when running `bin/packwerk update-deprecations`.
+        This helps ensure a high quality signal in other engineers' PRs when inspecting new violations by ensuring there are no unrelated changes.
+
+        There are three main reasons there may be a diff:
+        1) Most likely, you may have stale violations, meaning there are old violations that no longer apply.
+        2) You may have some sort of auto-formatter set up somewhere (e.g. something that reformats YML files) that is, for example, changing double quotes to single quotes. Ensure this is turned off for these auto-generated files.
+        3) You may have edited these files manually. It's recommended to use the `bin/packwerk update-deprecations` command to make changes to `deprecated_references.yml` files.
+
+        In all cases, you can run `bin/packwerk update-deprecations` to update these files.
+
+        Here is the diff generated after running `update-deprecations`:
+        ```
+        #{diff}
+        ```
+
+      OUTPUT
+
+      puts output
+      UsePacks.config.on_deprecated_references_lint_failure.call(output)
+
+      exit 1
+    end
+  end
+
+  sig { params(packs: T::Array[ParsePackwerk::Package]).void }
+  def self.lint_package_yml_files!(packs)
+    packs.each do |p|
+      new_package = ParsePackwerk::Package.new(
+        name: p.name,
+        enforce_privacy: p.enforce_privacy,
+        enforce_dependencies: p.enforce_dependencies,
+        dependencies: p.dependencies.uniq.sort,
+        metadata: p.metadata
+      )
+      ParsePackwerk.write_package_yml!(new_package)
+    end
+  end
+end