packwerk 2.2.2 → 3.0.0

data/lib/packwerk/configuration.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 require "pathname"
@@ -6,7 +6,12 @@ require "yaml"
 
 module Packwerk
   class Configuration
+    extend T::Sig
+
     class << self
+      extend T::Sig
+
+      sig { params(path: String).returns(Configuration) }
       def from_path(path = Dir.pwd)
         raise ArgumentError, "#{File.expand_path(path)} does not exist" unless File.exist?(path)
 
@@ -21,6 +26,7 @@ module Packwerk
 
       private
 
+      sig { params(path: String).returns(Configuration) }
       def from_packwerk_config(path)
         new(
           YAML.load_file(path) || {},
@@ -30,63 +36,78 @@ module Packwerk
     end
 
     DEFAULT_CONFIG_PATH = "packwerk.yml"
-    DEFAULT_INCLUDE_GLOBS = ["**/*.{rb,rake,erb}"]
-    DEFAULT_EXCLUDE_GLOBS = ["{bin,node_modules,script,tmp,vendor}/**/*"]
+    DEFAULT_INCLUDE_GLOBS = T.let(["**/*.{rb,rake,erb}"], T::Array[String])
+    DEFAULT_EXCLUDE_GLOBS = T.let(["{bin,node_modules,script,tmp,vendor}/**/*"], T::Array[String])
 
-    attr_reader(
-      :include, :exclude, :root_path, :package_paths, :custom_associations, :config_path, :cache_directory
-    )
+    sig { returns(T::Array[String]) }
+    attr_reader(:include)
 
-    def initialize(configs = {}, config_path: nil)
-      @include = configs["include"] || DEFAULT_INCLUDE_GLOBS
-      @exclude = configs["exclude"] || DEFAULT_EXCLUDE_GLOBS
-      root = config_path ? File.dirname(config_path) : "."
-      @root_path = File.expand_path(root)
-      @package_paths = configs["package_paths"] || "**/"
-      @custom_associations = configs["custom_associations"] || []
-      @parallel = configs.key?("parallel") ? configs["parallel"] : true
-      @cache_enabled = configs.key?("cache") ? configs["cache"] : false
-      @cache_directory = Pathname.new(configs["cache_directory"] || "tmp/cache/packwerk")
-      @config_path = config_path
+    sig { returns(T::Array[String]) }
+    attr_reader(:exclude)
 
-      if configs["load_paths"]
-        warning = <<~WARNING
-          DEPRECATION WARNING: The 'load_paths' key in `packwerk.yml` is deprecated.
-          This value is no longer cached, and you can remove the key from `packwerk.yml`.
-        WARNING
+    sig { returns(String) }
+    attr_reader(:root_path)
 
-        warn(warning)
-      end
+    sig { returns(T.any(String, T::Array[String])) }
+    attr_reader(:package_paths)
 
-      if configs["inflections_file"]
-        warning = <<~WARNING
-          DEPRECATION WARNING: The 'inflections_file' key in `packwerk.yml` is deprecated.
-          This value is no longer cached, and you can remove the key from `packwerk.yml`.
-          You can also delete #{configs["inflections_file"]}.
-        WARNING
+    sig { returns(T::Array[Symbol]) }
+    attr_reader(:custom_associations)
 
-        warn(warning)
-      end
+    sig { returns(T.nilable(String)) }
+    attr_reader(:config_path)
+
+    sig { returns(Pathname) }
+    attr_reader(:cache_directory)
 
-      inflection_file = File.expand_path(configs["inflections_file"] || "config/inflections.yml", @root_path)
-      if Pathname.new(inflection_file).exist?
-        warning = <<~WARNING
-          DEPRECATION WARNING: Inflections YMLs in packwerk are now deprecated.
-          This value is no longer cached, and you can now delete #{inflection_file}
-        WARNING
+    sig do
+      params(
+        configs: T::Hash[String, T.untyped],
+        config_path: T.nilable(String),
+      ).void
+    end
+    def initialize(configs = {}, config_path: nil)
+      @include = T.let(configs["include"] || DEFAULT_INCLUDE_GLOBS, T::Array[String])
+      @exclude = T.let(configs["exclude"] || DEFAULT_EXCLUDE_GLOBS, T::Array[String])
+      root = config_path ? File.dirname(config_path) : "."
+      @root_path = T.let(File.expand_path(root), String)
+      @package_paths = T.let(configs["package_paths"] || "**/", T.any(String, T::Array[String]))
+      @custom_associations = T.let(configs["custom_associations"] || [], T::Array[Symbol])
+      @parallel = T.let(configs.key?("parallel") ? configs["parallel"] : true, T::Boolean)
+      @cache_enabled = T.let(configs.key?("cache") ? configs["cache"] : false, T::Boolean)
+      @cache_directory = T.let(Pathname.new(configs["cache_directory"] || "tmp/cache/packwerk"), Pathname)
+      @config_path = config_path
 
-        warn(warning)
+      @offenses_formatter_identifier = T.let(
+        configs["offenses_formatter"] || Formatters::DefaultOffensesFormatter::IDENTIFIER, String
+      )
+
+      if configs.key?("require")
+        configs["require"].each do |require_directive|
+          ExtensionLoader.load(require_directive, @root_path)
+        end
       end
     end
 
+    sig { returns(T::Hash[String, Module]) }
     def load_paths
-      @load_paths ||= ApplicationLoadPaths.extract_relevant_paths(@root_path, "test")
+      @load_paths ||= T.let(
+        RailsLoadPaths.for(@root_path, environment: "test"),
+        T.nilable(T::Hash[String, Module]),
+      )
     end
 
+    sig { returns(T::Boolean) }
     def parallel?
       @parallel
     end
 
+    sig { returns(OffensesFormatter) }
+    def offenses_formatter
+      OffensesFormatter.find(@offenses_formatter_identifier)
+    end
+
+    sig { returns(T::Boolean) }
     def cache_enabled?
       @cache_enabled
     end

data/lib/packwerk/const_node_inspector.rb

@@ -52,4 +52,6 @@ module Packwerk
       "::" + NodeHelpers.parent_module_name(ancestors: ancestors)
     end
   end
+
+  private_constant :ConstNodeInspector
 end

data/lib/packwerk/constant_context.rb

@@ -0,0 +1,8 @@
+# typed: true
+# frozen_string_literal: true
+
+module Packwerk
+  extend T::Sig
+
+  ConstantContext = Struct.new(:name, :location, :package)
+end

data/lib/packwerk/constant_discovery.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 require "constant_resolver"
@@ -17,8 +17,6 @@ module Packwerk
   class ConstantDiscovery
     extend T::Sig
 
-    ConstantContext = Struct.new(:name, :location, :package, :public?)
-
     # @param constant_resolver [ConstantResolver]
     # @param packages [Packwerk::PackageSet]
     sig do
@@ -50,12 +48,12 @@ module Packwerk
     # @param const_name [String] The unresolved constant's name.
     # @param current_namespace_path [Array<String>] (optional) The namespace of the context in which the constant is
     #   used, e.g. ["Apps", "Models"] for `Apps::Models`. Defaults to [] which means top level.
-    # @return [Packwerk::ConstantDiscovery::ConstantContext]
+    # @return [ConstantContext]
     sig do
       params(
         const_name: String,
         current_namespace_path: T.nilable(T::Array[String]),
-      ).returns(T.nilable(ConstantDiscovery::ConstantContext))
+      ).returns(T.nilable(ConstantContext))
     end
     def context_for(const_name, current_namespace_path: [])
       begin
@@ -71,8 +69,9 @@ module Packwerk
         constant.name,
         constant.location,
         package,
-        package.public_path?(constant.location),
       )
     end
   end
+
+  private_constant :ConstantDiscovery
 end

data/lib/packwerk/constant_name_inspector.rb

@@ -18,4 +18,6 @@ module Packwerk
     end
     def constant_name_from_node(node, ancestors:); end
   end
+
+  private_constant :ConstantNameInspector
 end

data/lib/packwerk/disable_sorbet.rb

@@ -0,0 +1,41 @@
+# typed: true
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+begin
+  T::Configuration.default_checked_level = :never
+
+  T.singleton_class.prepend(
+    Module.new do
+      def cast(value, type, checked: true)
+        value
+      end
+
+      def let(value, type, checked: true)
+        value
+      end
+
+      def must(arg)
+        arg
+      end
+
+      def absurd(value)
+        value
+      end
+
+      def bind(value, type, checked: true)
+        value
+      end
+    end
+  )
+rescue RuntimeError => error
+  # From https://github.com/sorbet/sorbet/blob/dcf1b069cfb0d6624c027e45e59f4c6ca33de970/gems/sorbet-runtime/lib/types/private/runtime_levels.rb#L54
+  # Sorbet has already evaluated a method call somewhere, so we can't disable it.
+  # In this case, we want to log a warning so Packwerk can still be used (but will be slower).
+  if /Set the default checked level earlier./.match?(error.message)
+    warn("Packwerk couldn't disable Sorbet. Please ensure it isn't being used before Packwerk is loaded.")
+  else
+    raise error
+  end
+end

data/lib/packwerk/extension_loader.rb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  # This class handles loading extensions to packwerk using the `require` directive
+  # in the `packwerk.yml` configuration.
+  module ExtensionLoader
+    class << self
+      extend T::Sig
+      sig { params(require_directive: String, config_dir_path: String).void }
+      def load(require_directive, config_dir_path)
+        # We want to transform the require directive to behave differently
+        # if it's a specific local file being required versus a gem
+        if require_directive.start_with?(".")
+          require File.join(config_dir_path, require_directive)
+        else
+          require require_directive
+        end
+      end
+    end
+  end
+
+  private_constant :ExtensionLoader
+end

data/lib/packwerk/file_processor.rb

@@ -64,7 +64,7 @@ module Packwerk
       references = []
 
       node_processor = @node_processor_factory.for(relative_file: relative_file, node: node)
-      node_visitor = Packwerk::NodeVisitor.new(node_processor: node_processor)
+      node_visitor = NodeVisitor.new(node_processor: node_processor)
       node_visitor.visit(node, ancestors: [], result: references)
 
       references
@@ -82,4 +82,6 @@ module Packwerk
       @parser_factory.for_path(file_path)
     end
   end
+
+  private_constant :FileProcessor
 end

data/lib/packwerk/files_for_processing.rb

@@ -15,10 +15,10 @@ module Packwerk
           relative_file_paths: T::Array[String],
           configuration: Configuration,
           ignore_nested_packages: T::Boolean
-        ).returns(RelativeFileSet)
+        ).returns(FilesForProcessing)
       end
       def fetch(relative_file_paths:, configuration:, ignore_nested_packages: false)
-        new(relative_file_paths, configuration, ignore_nested_packages).files
+        new(relative_file_paths, configuration, ignore_nested_packages)
       end
     end
 
@@ -33,37 +33,48 @@ module Packwerk
       @relative_file_paths = relative_file_paths
       @configuration = configuration
       @ignore_nested_packages = ignore_nested_packages
-      @custom_files = T.let(nil, T.nilable(RelativeFileSet))
+      @specified_files = T.let(nil, T.nilable(RelativeFileSet))
+      @files = T.let(nil, T.nilable(RelativeFileSet))
     end
 
     sig { returns(RelativeFileSet) }
     def files
-      include_files = if custom_files.empty?
+      @files ||= files_for_processing
+    end
+
+    sig { returns(T::Boolean) }
+    def files_specified?
+      specified_files.any?
+    end
+
+    private
+
+    sig { returns(RelativeFileSet) }
+    def files_for_processing
+      all_included_files = if specified_files.empty?
         configured_included_files
       else
-        configured_included_files & custom_files
+        configured_included_files & specified_files
       end
 
-      include_files - configured_excluded_files
+      all_included_files - configured_excluded_files
     end
 
-    private
-
     sig { returns(RelativeFileSet) }
-    def custom_files
-      @custom_files ||= Set.new(
+    def specified_files
+      @specified_files ||= Set.new(
         @relative_file_paths.map do |relative_file_path|
           if File.file?(relative_file_path)
             relative_file_path
           else
-            custom_included_files(relative_file_path)
+            specified_included_files(relative_file_path)
           end
         end
       ).flatten
     end
 
     sig { params(relative_file_path: String).returns(RelativeFileSet) }
-    def custom_included_files(relative_file_path)
+    def specified_included_files(relative_file_path)
       # Note, assuming include globs are always relative paths
       relative_includes = @configuration.include
       relative_files = Dir.glob([File.join(relative_file_path, "**", "*")]).select do |relative_path|
@@ -100,4 +111,6 @@ module Packwerk
       Set.new(relative_globs.flat_map { |glob| Dir[glob] })
     end
   end
+
+  private_constant :FilesForProcessing
 end

data/lib/packwerk/formatters/default_offenses_formatter.rb

@@ -0,0 +1,77 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module Formatters
+    class DefaultOffensesFormatter
+      include OffensesFormatter
+
+      IDENTIFIER = T.let("default", String)
+
+      extend T::Sig
+
+      sig { override.params(offenses: T::Array[T.nilable(Offense)]).returns(String) }
+      def show_offenses(offenses)
+        return "No offenses detected" if offenses.empty?
+
+        <<~EOS
+          #{offenses_list(offenses)}
+          #{offenses_summary(offenses)}
+        EOS
+      end
+
+      sig { override.params(offense_collection: OffenseCollection, fileset: T::Set[String]).returns(String) }
+      def show_stale_violations(offense_collection, fileset)
+        if offense_collection.stale_violations?(fileset)
+          "There were stale violations found, please run `packwerk update-todo`"
+        else
+          "No stale violations detected"
+        end
+      end
+
+      sig { override.returns(String) }
+      def identifier
+        IDENTIFIER
+      end
+
+      sig { override.params(strict_mode_violations: T::Array[ReferenceOffense]).returns(String) }
+      def show_strict_mode_violations(strict_mode_violations)
+        if strict_mode_violations.any?
+          strict_mode_violations.compact.map { |offense| format_strict_mode_violation(offense) }.join("\n")
+        else
+          ""
+        end
+      end
+
+      private
+
+      sig { returns(OutputStyle) }
+      def style
+        @style ||= T.let(Packwerk::OutputStyles::Coloured.new, T.nilable(Packwerk::OutputStyles::Coloured))
+      end
+
+      sig { params(offense: ReferenceOffense).returns(String) }
+      def format_strict_mode_violation(offense)
+        reference_package = offense.reference.package
+        defining_package = offense.reference.constant.package
+        "#{reference_package} cannot have #{offense.violation_type} violations on #{defining_package} "\
+          "because strict mode is enabled for #{offense.violation_type} violations in "\
+          "the enforcing package's package.yml"
+      end
+
+      sig { params(offenses: T::Array[T.nilable(Offense)]).returns(String) }
+      def offenses_list(offenses)
+        offenses
+          .compact
+          .map { |offense| offense.to_s(style) }
+          .join("\n")
+      end
+
+      sig { params(offenses: T::Array[T.nilable(Offense)]).returns(String) }
+      def offenses_summary(offenses)
+        offenses_string = "offense".pluralize(offenses.length)
+        "#{offenses.length} #{offenses_string} detected"
+      end
+    end
+  end
+end

data/lib/packwerk/formatters/progress_formatter.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 require "benchmark"
@@ -14,37 +14,56 @@ module Packwerk
         @style = style
       end
 
-      def started(target_files)
-        files_size = target_files.size
-        files_string = "file".pluralize(files_size)
-        @out.puts("📦 Packwerk is inspecting #{files_size} #{files_string}")
-      end
-
+      sig { params(block: T.proc.void).void }
       def started_validation(&block)
-        @out.puts("📦 Packwerk is running validation...")
+        start_validation
 
         execution_time = Benchmark.realtime(&block)
         finished(execution_time)
+      end
 
-        @out.puts("✅ Packages are valid. Use `packwerk check` to run static checks.")
+      sig { params(target_files: FilesForProcessing::RelativeFileSet, block: T.proc.void).void }
+      def started_inspection(target_files, &block)
+        start_inspection(target_files)
+
+        execution_time = Benchmark.realtime(&block)
+        finished(execution_time)
       end
 
+      sig { void }
       def mark_as_inspected
         @out.print(".")
       end
 
+      sig { void }
       def mark_as_failed
         @out.print("#{@style.error}E#{@style.reset}")
       end
 
+      sig { void }
+      def interrupted
+        @out.puts
+        @out.puts("Manually interrupted. Violations caught so far are listed below:")
+      end
+
+      private
+
+      sig { params(execution_time: Float).void }
       def finished(execution_time)
         @out.puts
         @out.puts("📦 Finished in #{execution_time.round(2)} seconds")
       end
 
-      def interrupted
-        @out.puts
-        @out.puts("Manually interrupted. Violations caught so far are listed below:")
+      sig { void }
+      def start_validation
+        @out.puts("📦 Packwerk is running validation...")
+      end
+
+      sig { params(target_files: FilesForProcessing::RelativeFileSet).void }
+      def start_inspection(target_files)
+        files_size = target_files.size
+        files_string = "file".pluralize(files_size)
+        @out.puts("📦 Packwerk is inspecting #{files_size} #{files_string}")
       end
     end
   end

data/lib/packwerk/generators/configuration_file.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 require "erb"
@@ -11,6 +11,9 @@ module Packwerk
       CONFIGURATION_TEMPLATE_FILE_PATH = "templates/packwerk.yml.erb"
 
       class << self
+        extend T::Sig
+
+        sig { params(root: String, out: T.any(IO, StringIO)).returns(T::Boolean) }
         def generate(root:, out:)
           new(root: root, out: out).generate
         end
@@ -25,7 +28,7 @@ module Packwerk
       sig { returns(T::Boolean) }
       def generate
         @out.puts("📦 Generating Packwerk configuration file...")
-        default_config_path = File.join(@root, ::Packwerk::Configuration::DEFAULT_CONFIG_PATH)
+        default_config_path = File.join(@root, Configuration::DEFAULT_CONFIG_PATH)
 
         if File.exist?(default_config_path)
           @out.puts("⚠️  Packwerk configuration file already exists.")
@@ -40,10 +43,12 @@ module Packwerk
 
       private
 
+      sig { returns(String) }
       def render
         ERB.new(template, trim_mode: "-").result(binding)
       end
 
+      sig { returns(String) }
       def template
         template_file_path = File.join(__dir__, CONFIGURATION_TEMPLATE_FILE_PATH)
         File.read(template_file_path)

data/lib/packwerk/generators/root_package.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 module Packwerk
@@ -7,11 +7,15 @@ module Packwerk
       extend T::Sig
 
       class << self
+        extend T::Sig
+
+        sig { params(root: String, out: T.any(IO, StringIO)).returns(T::Boolean) }
         def generate(root:, out:)
           new(root: root, out: out).generate
         end
       end
 
+      sig { params(root: String, out: T.any(IO, StringIO)).void }
       def initialize(root:, out: $stdout)
         @root = root
         @out = out

data/lib/packwerk/generators/templates/package.yml

@@ -5,16 +5,6 @@
 # Turn on dependency checks for this package
 enforce_dependencies: true
 
-# Turn on privacy checks for this package
-# enforcing privacy is often not useful for the root package, because it would require defining a public interface
-# for something that should only be a thin wrapper in the first place.
-# We recommend enabling this for any new packages you create to aid with encapsulation.
-enforce_privacy: false
-
-# By default the public path will be app/public/, however this may not suit all applications' architecture so
-# this allows you to modify what your package's public path is.
-# public_path: app/public/
-
 # A list of this package's dependencies
 # Note that packages in this list require their own `package.yml` file
 # dependencies:

data/lib/packwerk/graph.rb

@@ -4,8 +4,14 @@
 module Packwerk
   # A general implementation of a graph data structure with the ability to check for - and list - cycles.
   class Graph
-    # @param [Array<Array>] edges The edges of the graph; An edge being represented as an Array of two nodes.
-    def initialize(*edges)
+    extend T::Sig
+    sig do
+      params(
+        # The edges of the graph; An edge being represented as an Array of two nodes.
+        edges: T::Array[T::Array[T.any(String, Integer, NilClass)]]
+      ).void
+    end
+    def initialize(edges)
       @edges = edges.uniq
       @cycles = Set.new
       process
@@ -73,4 +79,6 @@ module Packwerk
       @cycles << cycle
     end
   end
+
+  private_constant :Graph
 end

data/lib/packwerk/node.rb

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
-  class Node
+  module Node
     Location = Struct.new(:line, :column)
   end
 end

data/lib/packwerk/node_helpers.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 require "parser"
@@ -59,11 +59,16 @@ module Packwerk
         end
       end
 
-      sig { params(node: AST::Node).returns(T.untyped) }
-      def each_child(node)
-        if block_given?
+      sig do
+        params(
+          node: AST::Node,
+          block: T.nilable(T.proc.params(arg0: Parser::AST::Node).void),
+        ).returns(T::Enumerable[AST::Node])
+      end
+      def each_child(node, &block)
+        if block
           node.children.each do |child|
-            yield child if child.is_a?(Parser::AST::Node)
+            yield(child) if child.is_a?(Parser::AST::Node)
           end
         else
           enum_for(:each_child, node)
@@ -181,9 +186,9 @@ module Packwerk
         end
       end
 
-      sig { params(node: Parser::AST::Node).returns(T.nilable(Node::Location)) }
+      sig { params(node: AST::Node).returns(T.nilable(Node::Location)) }
       def name_location(node)
-        location = node.location
+        location = T.cast(node, Parser::AST::Node).location
 
         if location.respond_to?(:name)
           name = location.name
@@ -332,4 +337,6 @@ module Packwerk
       end
     end
   end
+
+  private_constant :NodeHelpers
 end