packwerk 3.0.0 → 3.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11206a06e6ac99c1fb8ef4cdefbe334133317d0599fce6480d4dfe10f694c747
-  data.tar.gz: 606778530b8a872d331e5f331b9c6e14cb37ff6e0a5e13247bb0aebe1ca9e0cc
+  metadata.gz: 9172cfed0b1190af4ece801d73138cdaba7cd9aaad8fdb90537b2d6a03d597bb
+  data.tar.gz: 946267b723dff18a00a2948d4f9d5c8766018ae815b50fa542ba450bdc29c718
 SHA512:
-  metadata.gz: 66166a9c683483fda99341adc79c807c40f8190c349c8650b8646810e06d11f9b4728e2e938ef0abf640967d0764d78b66e956aba3bdaef830c4a15253711542
-  data.tar.gz: c1cce5df16246f1561cd0954abca4685e21adcaf52d3f6d164acd776f9466a0ad276a65b9a2f5cc9e358b058fcdc2cef265c2b3948043f9f3e35b1d4798ec5e9
+  metadata.gz: a7ec7b0f03a55f713b24d9aec7e6cadfb7138087685ee698f7a35c64209638168d91ee7de44a174543271b4252173007d64a16b0bd5f00348dd0554a76c34bb1
+  data.tar.gz: ccc7785fcef8f061923c72f122dbf7f7c9ebab1e7c4cc9d2e6c2a8a643ac0da8f7594c17c2823b2bcc7845dd255d886a6b85eabe0ce68176a8b1ff57097c7278

data/README.md

@@ -58,10 +58,12 @@ Read [USAGE.md](USAGE.md) for usage once Packwerk is installed on your project.
 Various third parties have built tooling on top of packwerk. Here's a selection of some that might prove useful:
 
 - https://github.com/bellroy/graphwerk draws a graph of your package dependencies
-- https://github.com/Gusto/packwerk-vscode integrates packwerk into Visual Studio Code so you can see violations right in your editor
-- https://github.com/Gusto/stimpack sets up Rails autoloading, as well as `rspec` and `FactoryBot` integration, for packages arranged in a flat list. Stimpack is quite convenient, but for autoloading we recommend to use `Rails::Engine`s instead.
+- https://github.com/rubyatscale/packwerk-vscode integrates packwerk into Visual Studio Code so you can see violations right in your editor
+- https://github.com/vinted/packwerk-intellij integrates packwerk into RubyMine so you can see violations right in your editor
+- https://github.com/rubyatscale/packs-rails sets up Rails autoloading, as well as `rspec` and `FactoryBot` integration, for packages arranged in a flat list. packs-rails is quite convenient, but for autoloading we recommend to use `Rails::Engine`s instead.
 - https://github.com/rubyatscale/danger-packwerk integrates packwerk with [danger.systems](https://danger.systems) to provide packwerk feedback as Github inline PR comments
 - https://github.com/rubyatscale/packwerk-extensions contains extensions for packwerk, including a checker for packwerk that allows you to enforce public API boundaries. This was originally extracted from `packwerk` itself.
+- https://github.com/alexevanczuk/packs is a Rust implementation of packwerk that has experimental support for non-Rails, non-Zeitwerk applications.
 
 ## Development
 

data/exe/packwerk

@@ -1,7 +1,10 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "packwerk/disable_sorbet"
+unless defined?(Spring)
+  require "packwerk/disable_sorbet"
+end
+
 require "packwerk"
 
 # Needs to be run in test environment in order to have test helper paths available in the autoload paths

data/lib/packwerk/application_validator.rb

@@ -11,6 +11,9 @@ module Packwerk
   class ApplicationValidator
     include Validator
     extend T::Sig
+    extend ActiveSupport::Autoload
+
+    autoload :Helpers
 
     sig { params(package_set: PackageSet, configuration: Configuration).returns(Validator::Result) }
     def check_all(package_set, configuration)

data/lib/packwerk/association_inspector.rb

@@ -19,19 +19,27 @@ module Packwerk
       CustomAssociations
     )
 
-    sig { params(inflector: T.class_of(ActiveSupport::Inflector), custom_associations: CustomAssociations).void }
-    def initialize(inflector:, custom_associations: Set.new)
+    sig do
+      params(
+        inflector: T.class_of(ActiveSupport::Inflector),
+        custom_associations: CustomAssociations,
+        excluded_files: T::Set[String]
+      ).void
+    end
+    def initialize(inflector:, custom_associations: Set.new, excluded_files: Set.new)
       @inflector = inflector
       @associations = T.let(RAILS_ASSOCIATIONS + custom_associations, CustomAssociations)
+      @excluded_files = T.let(excluded_files, T::Set[String])
     end
 
     sig do
       override
-        .params(node: AST::Node, ancestors: T::Array[AST::Node])
+        .params(node: AST::Node, ancestors: T::Array[AST::Node], relative_file: String)
         .returns(T.nilable(String))
     end
-    def constant_name_from_node(node, ancestors:)
+    def constant_name_from_node(node, ancestors:, relative_file:)
       return unless NodeHelpers.method_call?(node)
+      return if excluded?(relative_file)
       return unless association?(node)
 
       arguments = NodeHelpers.method_arguments(node)
@@ -48,6 +56,11 @@ module Packwerk
 
     private
 
+    sig { params(relative_file: String).returns(T::Boolean) }
+    def excluded?(relative_file)
+      @excluded_files.include?(relative_file)
+    end
+
     sig { params(node: AST::Node).returns(T::Boolean) }
     def association?(node)
       method_name = NodeHelpers.method_name(node)

data/lib/packwerk/checker.rb

@@ -11,16 +11,15 @@ module Packwerk
     class << self
       extend T::Sig
 
-      sig { params(base: Class).void }
+      sig { params(base: T::Class[T.anything]).void }
       def included(base)
-        @checkers ||= T.let(@checkers, T.nilable(T::Array[Class]))
-        @checkers ||= []
-        @checkers << base
+        checkers << base
       end
 
       sig { returns(T::Array[Checker]) }
       def all
-        T.unsafe(@checkers).map(&:new)
+        load_defaults
+        T.cast(checkers.map(&:new), T::Array[Checker])
       end
 
       sig { params(violation_type: String).returns(Checker) }
@@ -30,6 +29,16 @@ module Packwerk
 
       private
 
+      sig { void }
+      def load_defaults
+        require("packwerk/reference_checking/checkers/dependency_checker")
+      end
+
+      sig { returns(T::Array[T::Class[T.anything]]) }
+      def checkers
+        @checkers ||= T.let([], T.nilable(T::Array[T::Class[T.anything]]))
+      end
+
       sig { params(name: String).returns(Checker) }
       def checker_by_violation_type(name)
         @checker_by_violation_type ||= T.let(Checker.all.to_h do |checker|
@@ -42,8 +51,8 @@ module Packwerk
     sig { abstract.returns(String) }
     def violation_type; end
 
-    sig { abstract.params(listed_offense: ReferenceOffense).returns(T::Boolean) }
-    def strict_mode_violation?(listed_offense); end
+    sig { abstract.params(offense: ReferenceOffense).returns(T::Boolean) }
+    def strict_mode_violation?(offense); end
 
     sig { abstract.params(reference: Reference).returns(T::Boolean) }
     def invalid_reference?(reference); end

data/lib/packwerk/cli.rb

@@ -1,8 +1,6 @@
 # typed: strict
 # frozen_string_literal: true
 
-require "optparse"
-
 module Packwerk
   # A command-line interface to Packwerk.
   class Cli
@@ -46,184 +44,23 @@ module Packwerk
 
     sig { params(args: T::Array[String]).returns(T::Boolean) }
     def execute_command(args)
-      subcommand = args.shift
-      case subcommand
-      when "init"
-        init
-      when "check"
-        output_result(parse_run(args).check)
-      when "update-todo", "update"
-        output_result(parse_run(args).update_todo)
-      when "validate"
-        validate(args)
-      when "version"
-        @out.puts(Packwerk::VERSION)
-        true
-      when nil, "help"
-        usage
-      else
-        @err_out.puts(
-          "'#{subcommand}' is not a packwerk command. See `packwerk help`."
-        )
-        false
-      end
-    end
-
-    private
-
-    sig { returns(T::Boolean) }
-    def init
-      @out.puts("📦 Initializing Packwerk...")
-
-      generate_configs
-    end
-
-    sig { returns(T::Boolean) }
-    def generate_configs
-      configuration_file = Generators::ConfigurationFile.generate(
-        root: @configuration.root_path,
-        out: @out
-      )
-
-      root_package = Generators::RootPackage.generate(root: @configuration.root_path, out: @out)
-
-      success = configuration_file && root_package
-
-      result = if success
-        <<~EOS
-
-          🎉 Packwerk is ready to be used. You can start defining packages and run `bin/packwerk check`.
-          For more information on how to use Packwerk, see: https://github.com/Shopify/packwerk/blob/main/USAGE.md
-        EOS
-      else
-        <<~EOS
-
-          ⚠️  Packwerk is not ready to be used.
-          Please check output and refer to https://github.com/Shopify/packwerk/blob/main/USAGE.md for more information.
-        EOS
-      end
-
-      @out.puts(result)
-      success
-    end
-
-    sig { returns(T::Boolean) }
-    def usage
-      @err_out.puts(<<~USAGE)
-        Usage: #{$PROGRAM_NAME} <subcommand>
-
-        Subcommands:
-          init - set up packwerk
-          check - run all checks
-          update-todo - update package_todo.yml files
-          validate - verify integrity of packwerk and package configuration
-          version - output packwerk version
-          help  - display help information about packwerk
-      USAGE
-      true
-    end
-
-    sig { params(result: Result).returns(T::Boolean) }
-    def output_result(result)
-      @out.puts
-      @out.puts(result.message)
-      result.status
-    end
-
-    sig do
-      params(
-        relative_file_paths: T::Array[String],
-        ignore_nested_packages: T::Boolean
-      ).returns(FilesForProcessing)
-    end
-    def fetch_files_to_process(relative_file_paths, ignore_nested_packages)
-      files_for_processing = FilesForProcessing.fetch(
-        relative_file_paths: relative_file_paths,
-        ignore_nested_packages: ignore_nested_packages,
-        configuration: @configuration
-      )
-      @out.puts(<<~MSG.squish) if files_for_processing.files.empty?
-        No files found or given.
-        Specify files or check the include and exclude glob in the config file.
-      MSG
-
-      files_for_processing
-    end
-
-    sig { params(_paths: T::Array[String]).returns(T::Boolean) }
-    def validate(_paths)
-      result = T.let(nil, T.nilable(Validator::Result))
-
-      @progress_formatter.started_validation do
-        result = validator.check_all(package_set, @configuration)
-
-        list_validation_errors(result)
-      end
-
-      T.must(result).ok?
-    end
-
-    sig { returns(ApplicationValidator) }
-    def validator
-      ApplicationValidator.new
-    end
-
-    sig { returns(PackageSet) }
-    def package_set
-      PackageSet.load_all_from(
-        @configuration.root_path,
-        package_pathspec: @configuration.package_paths
-      )
-    end
-
-    sig { params(result: Validator::Result).void }
-    def list_validation_errors(result)
-      @out.puts
-      if result.ok?
-        @out.puts("Validation successful 🎉")
+      command = args.shift || "help"
+      command_class = Commands.for(command)
+
+      if command_class
+        command_class.new(
+          args,
+          configuration: @configuration,
+          out: @out,
+          err_out: @err_out,
+          progress_formatter: @progress_formatter,
+          offenses_formatter: @offenses_formatter,
+        ).run
       else
-        @out.puts("Validation failed ❗")
-        @out.puts
-        @out.puts(result.error_value)
-      end
-    end
-
-    sig { params(args: T::Array[String]).returns(ParseRun) }
-    def parse_run(args)
-      relative_file_paths = T.let([], T::Array[String])
-      ignore_nested_packages = nil
-      formatter = @offenses_formatter
+        @err_out.puts("'#{command}' is not a packwerk command. See `packwerk help`.",)
 
-      if args.any? { |arg| arg.include?("--packages") }
-        OptionParser.new do |parser|
-          parser.on("--packages=PACKAGESLIST", Array, "package names, comma separated") do |p|
-            relative_file_paths = p
-          end
-        end.parse!(args)
-        ignore_nested_packages = true
-      else
-        relative_file_paths = args
-        ignore_nested_packages = false
-      end
-
-      if args.any? { |arg| arg.include?("--offenses-formatter") }
-        OptionParser.new do |parser|
-          parser.on("--offenses-formatter=FORMATTER", String,
-            "identifier of offenses formatter to use") do |formatter_identifier|
-            formatter = OffensesFormatter.find(formatter_identifier)
-          end
-        end.parse!(args)
+        false
       end
-
-      files_for_processing = fetch_files_to_process(relative_file_paths, ignore_nested_packages)
-
-      ParseRun.new(
-        relative_file_set: files_for_processing.files,
-        file_set_specified: files_for_processing.files_specified?,
-        configuration: @configuration,
-        progress_formatter: @progress_formatter,
-        offenses_formatter: formatter
-      )
     end
   end
 end

data/lib/packwerk/commands/base_command.rb

@@ -0,0 +1,69 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module Commands
+    class BaseCommand
+      extend T::Sig
+      extend T::Helpers
+      abstract!
+
+      @description = T.let("", String)
+
+      class << self
+        extend T::Sig
+
+        sig { params(description: T.nilable(String)).returns(String) }
+        def description(description = nil)
+          if description
+            @description = description
+          else
+            @description
+          end
+        end
+      end
+
+      sig do
+        params(
+          args: T::Array[String],
+          configuration: Configuration,
+          out: T.any(StringIO, IO),
+          err_out: T.any(StringIO, IO),
+          progress_formatter: Formatters::ProgressFormatter,
+          offenses_formatter: OffensesFormatter,
+        ).void
+      end
+      def initialize(args, configuration:, out:, err_out:, progress_formatter:, offenses_formatter:)
+        @args = args
+        @configuration = configuration
+        @out = out
+        @err_out = err_out
+        @progress_formatter = progress_formatter
+        @offenses_formatter = offenses_formatter
+      end
+
+      sig { abstract.returns(T::Boolean) }
+      def run; end
+
+      private
+
+      sig { returns(T::Array[String]) }
+      attr_reader :args
+
+      sig { returns(Configuration) }
+      attr_reader :configuration
+
+      sig { returns(T.any(StringIO, IO)) }
+      attr_reader :out
+
+      sig { returns(T.any(StringIO, IO)) }
+      attr_reader :err_out
+
+      sig { returns(Formatters::ProgressFormatter) }
+      attr_reader :progress_formatter
+
+      sig { returns(OffensesFormatter) }
+      attr_reader :offenses_formatter
+    end
+  end
+end

data/lib/packwerk/commands/check_command.rb

@@ -0,0 +1,62 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module Commands
+    class CheckCommand < BaseCommand
+      extend T::Sig
+      include UsesParseRun
+
+      description "run all checks"
+
+      sig { override.returns(T::Boolean) }
+      def run
+        if @files_for_processing.files.empty?
+          out.puts(<<~MSG.squish)
+            No files found or given.
+            Specify files or check the include and exclude glob in the config file.
+          MSG
+
+          true
+        end
+
+        all_offenses = T.let([], T::Array[Offense])
+        on_interrupt = T.let(-> { progress_formatter.interrupted }, T.proc.void)
+
+        progress_formatter.started_inspection(@files_for_processing.files) do
+          all_offenses = parse_run.find_offenses(run_context, on_interrupt: on_interrupt) do |offenses|
+            failed = offenses.any? { |offense| !offense_collection.listed?(offense) }
+            progress_formatter.increment_progress(failed)
+          end
+        end
+        offense_collection.add_offenses(all_offenses)
+
+        unlisted_strict_mode_violations = offense_collection.unlisted_strict_mode_violations
+
+        messages = [
+          offenses_formatter.show_offenses(offense_collection.outstanding_offenses),
+          offenses_formatter.show_stale_violations(offense_collection, @files_for_processing.files),
+          offenses_formatter.show_strict_mode_violations(unlisted_strict_mode_violations),
+        ]
+
+        out.puts(messages.select(&:present?).join("\n") + "\n")
+
+        offense_collection.outstanding_offenses.empty? &&
+          !offense_collection.stale_violations?(@files_for_processing.files) &&
+          unlisted_strict_mode_violations.empty?
+      end
+
+      private
+
+      sig { returns(RunContext) }
+      def run_context
+        @run_context ||= T.let(RunContext.from_configuration(configuration), T.nilable(RunContext))
+      end
+
+      sig { returns(OffenseCollection) }
+      def offense_collection
+        @offense_collection ||= T.let(OffenseCollection.new(configuration.root_path), T.nilable(OffenseCollection))
+      end
+    end
+  end
+end

data/lib/packwerk/commands/help_command.rb

@@ -0,0 +1,33 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module Commands
+    class HelpCommand < BaseCommand
+      extend T::Sig
+
+      description "display help information about packwerk"
+
+      sig { override.returns(T::Boolean) }
+      def run
+        err_out.puts(<<~USAGE)
+          Usage: #{$PROGRAM_NAME} <subcommand>
+
+          Subcommands:
+          #{command_help_lines}
+        USAGE
+
+        true
+      end
+
+      private
+
+      sig { returns(String) }
+      def command_help_lines
+        Commands.all.map do |command|
+          "  #{command.name} - #{command.description}"
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/packwerk/commands/init_command.rb

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module Commands
+    class InitCommand < BaseCommand
+      extend T::Sig
+
+      description "set up packwerk"
+
+      sig { override.returns(T::Boolean) }
+      def run
+        out.puts("📦 Initializing Packwerk...")
+
+        configuration_file = Generators::ConfigurationFile.generate(
+          root: configuration.root_path,
+          out: out
+        )
+
+        root_package = Generators::RootPackage.generate(root: configuration.root_path, out: out)
+
+        success = configuration_file && root_package
+
+        if success
+          out.puts(<<~EOS)
+
+            🎉 Packwerk is ready to be used. You can start defining packages and run `bin/packwerk check`.
+            For more information on how to use Packwerk, see: https://github.com/Shopify/packwerk/blob/main/USAGE.md
+          EOS
+        else
+          out.puts(<<~EOS)
+
+            ⚠️  Packwerk is not ready to be used.
+            Please check output and refer to https://github.com/Shopify/packwerk/blob/main/USAGE.md for more information.
+          EOS
+        end
+
+        success
+      end
+    end
+  end
+end

data/lib/packwerk/commands/lazy_loaded_entry.rb

@@ -0,0 +1,37 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module Commands
+    class LazyLoadedEntry
+      extend T::Sig
+
+      sig { returns(String) }
+      attr_reader :name
+
+      sig { params(name: String, aliases: T::Array[String]).void }
+      def initialize(name, aliases: [])
+        @name = name
+        @aliases = aliases
+      end
+
+      sig { returns(T.class_of(BaseCommand)) }
+      def command_class
+        classname = @name.sub(" ", "_").underscore.classify + "Command"
+        Commands.const_get(classname) # rubocop:disable Sorbet/ConstantsFromStrings
+      end
+
+      sig { returns(String) }
+      def description
+        command_class.description
+      end
+
+      sig { params(name_or_alias: String).returns(T::Boolean) }
+      def matches_command?(name_or_alias)
+        @name == name_or_alias || @aliases.include?(name_or_alias)
+      end
+    end
+
+    private_constant :LazyLoadedEntry
+  end
+end

data/lib/packwerk/commands/update_todo_command.rb

@@ -0,0 +1,60 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module Commands
+    class UpdateTodoCommand < BaseCommand
+      extend T::Sig
+      include UsesParseRun
+
+      description "update package_todo.yml files"
+
+      sig { override.returns(T::Boolean) }
+      def run
+        if @files_for_processing.files_specified?
+          out.puts(<<~MSG.squish)
+            ⚠️ update-todo must be called without any file arguments.
+          MSG
+
+          return false
+        end
+        if @files_for_processing.files.empty?
+          out.puts(<<~MSG.squish)
+            No files found or given.
+            Specify files or check the include and exclude glob in the config file.
+          MSG
+
+          return true
+        end
+
+        run_context = RunContext.from_configuration(configuration)
+        offenses = T.let([], T::Array[Offense])
+        progress_formatter.started_inspection(@files_for_processing.files) do
+          offenses = parse_run.find_offenses(run_context, on_interrupt: -> { progress_formatter.interrupted }) do
+            progress_formatter.increment_progress
+          end
+        end
+
+        offense_collection = OffenseCollection.new(configuration.root_path)
+        offense_collection.add_offenses(offenses)
+        offense_collection.persist_package_todo_files(run_context.package_set)
+
+        unlisted_strict_mode_violations = offense_collection.unlisted_strict_mode_violations
+
+        messages = [
+          offenses_formatter.show_offenses(offense_collection.errors + unlisted_strict_mode_violations),
+        ]
+
+        messages << if unlisted_strict_mode_violations.any?
+          "⚠️ `package_todo.yml` has been updated, but unlisted strict mode violations were not added."
+        else
+          "✅ `package_todo.yml` has been updated."
+        end
+
+        out.puts(messages.select(&:present?).join("\n") + "\n")
+
+        unlisted_strict_mode_violations.empty? && offense_collection.errors.empty?
+      end
+    end
+  end
+end