packs 0.0.5 → 0.0.22

data/lib/packs/user_event_logger.rb

@@ -0,0 +1,199 @@
+# typed: strict
+
+module Packs
+  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-todo` 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-todo` 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-todo` 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 update-todo` 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-todo` 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_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. `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
+      else
+        <<~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
+    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_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_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
+    end
+
+    sig { returns(String) }
+    def documentation_link
+      'https://github.com/rubyatscale/use_packs#readme'
+    end
+  end
+end

data/lib/packs.rb

@@ -1,80 +1,260 @@
 # typed: strict
 
-require 'yaml'
-require 'pathname'
-require 'sorbet-runtime'
-require 'packs/pack'
+# Ruby internal requires
+require 'fileutils'
+
+# External gem requires
+require 'colorized_string'
+
+# Internal gem requires
+require 'packs-specification'
+require 'parse_packwerk'
+require 'code_teams'
+require 'code_ownership'
+require 'rubocop-packs'
+
+# Private implementation requires
 require 'packs/private'
+require 'packs/per_file_processor_interface'
+require 'packs/rubocop_post_processor'
+require 'packs/code_ownership_post_processor'
+require 'packs/logging'
+require 'packs/configuration'
+require 'packs/cli'
 
 module Packs
-  PACKAGE_FILE = T.let('package.yml'.freeze, String)
+  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
 
-  class << self
-    extend T::Sig
+  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 { returns(T::Array[Pack]) }
-    def all
-      packs_by_name.values
+  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 = Packs.config.user_event_logger.before_move_to_pack(pack_name)
+      Logging.print_bold_green(intro)
     end
 
-    sig { params(name: String).returns(T.nilable(Pack)) }
-    def find(name)
-      packs_by_name[name]
+    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 = Packs.config.user_event_logger.after_move_to_pack(pack_name)
+      Logging.print_bold_green(next_steps)
     end
+  end
 
-    sig { params(file_path: T.any(Pathname, String)).returns(T.nilable(Pack)) }
-    def for_file(file_path)
-      path_string = file_path.to_s
-      @for_file = T.let(@for_file, T.nilable(T::Hash[String, T.nilable(Pack)]))
-      @for_file ||= {}
-      @for_file[path_string] ||= all.find { |package| path_string.start_with?("#{package.name}/") || path_string == package.name }
+  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 = Packs.config.user_event_logger.before_make_public
+      Logging.print_bold_green(intro)
     end
 
-    sig { void }
-    def bust_cache!
-      @packs_by_name = nil
-      @config = nil
-      @for_file = nil
+    Private.make_public!(
+      paths_relative_to_root: paths_relative_to_root,
+      per_file_processors: per_file_processors
+    )
+
+    Logging.section('Next steps') do
+      next_steps = Packs.config.user_event_logger.after_make_public
+      Logging.print_bold_green(next_steps)
     end
+  end
 
-    sig { returns(Private::Configuration) }
-    def config
-      @config = T.let(@config, T.nilable(Private::Configuration))
-      @config ||= Private::Configuration.fetch
+  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 = Packs.config.user_event_logger.before_add_dependency(pack_name)
+      Logging.print_bold_green(intro)
     end
 
-    sig { params(blk: T.proc.params(arg0: Private::Configuration).void).void }
-    def configure(&blk)
-      # If packs.yml is being used, then ignore direct configuration.
-      # This is only a stop-gap to permit Stimpack users to more easily migrate
-      # to packs.yml
-      return if Private::Configuration::CONFIGURATION_PATHNAME.exist?
+    Private.add_dependency!(
+      pack_name: pack_name,
+      dependency_name: dependency_name
+    )
 
-      yield(config)
+    Logging.section('Next steps') do
+      next_steps = Packs.config.user_event_logger.after_add_dependency(pack_name)
+      Logging.print_bold_green(next_steps)
     end
+  end
 
-    private
+  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 = Packs.config.user_event_logger.before_move_to_parent(pack_name)
+      Logging.print_bold_green(intro)
+    end
 
-    sig { returns(T::Hash[String, Pack]) }
-    def packs_by_name
-      @packs_by_name = T.let(@packs_by_name, T.nilable(T::Hash[String, Pack]))
-      @packs_by_name ||= begin
-        all_packs = package_glob_patterns.map do |path|
-          Pack.from(path)
-        end
+    Private.move_to_parent!(
+      pack_name: pack_name,
+      parent_name: parent_name,
+      per_file_processors: per_file_processors
+    )
 
-        # We want to match more specific paths first so for_file works correctly.
-        sorted_packages = all_packs.sort_by { |package| -package.name.length }
-        sorted_packages.to_h { |p| [p.name, p] }
-      end
+    Logging.section('Next steps') do
+      next_steps = Packs.config.user_event_logger.after_move_to_parent(pack_name)
+
+      Logging.print_bold_green(next_steps)
     end
+  end
 
-    sig { returns(T::Array[Pathname]) }
-    def package_glob_patterns
-      absolute_root = Private.root
-      config.pack_paths.flat_map do |pack_path|
-        Pathname.glob(absolute_root.join(pack_path).join(PACKAGE_FILE))
-      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!
+    Specification.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_package_todo_yml_files!
+    Private.lint_package_todo_yml_files!
+  end
+
+  sig { params(packs: T::Array[Packs::Pack]).void }
+  def self.lint_package_yml_files!(packs)
+    Private.lint_package_yml_files!(packs)
+  end
 end