packwerk 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a473db2c54adea132ca7e61a51072b570d7e37b7d63c021259eef3cc7625177b
-  data.tar.gz: 1b8486e61969621fac562d2fb6ebe47dcf6f71fcd13f6d18524337a3ed831ac2
+  metadata.gz: dfc6290decd1cdaa95140a3d8495fb324c3c6d3cf01b4794e40068baff8eb663
+  data.tar.gz: cb01a5adb6f0118473a635b3d38416a4287207651262ee8a20b0f7833d8bfa37
 SHA512:
-  metadata.gz: 8c05f0ce6e8b398a87e98453c721d00707628918ce8455600c1cb00fb2cb9c68efc6bea373323e889d36fc3658ff45db3508b0e6386b876da58ca50cdb53ab9f
-  data.tar.gz: 51586b68f489ff1f32df06338d05a64cab753da56c11575b3c5c8fa55019e9a8527e0a20c54c8695e1432307227d26c10f01b0d6c610e41c55d84296be000bd8
+  metadata.gz: 85e01c90d7d35d169f773b4a9dd281b0cf563c5586d68e7592317d5747da81aba396b0330a9d77e776c01d098353fbc27c08d80f314ff6db88e5bf3117d06b41
+  data.tar.gz: 650a4a5852353ed999c54159c7951905c3984e1d21a17c99e51c94462733df2f20f55931b76ecab2590e179c41756da862df170263d7c6077e5976465e802fe9

data/Gemfile.lock

@@ -87,15 +87,16 @@ GIT
 PATH
   remote: .
   specs:
-    packwerk (2.0.0)
+    packwerk (2.2.0)
       activesupport (>= 5.2)
       ast
       better_html
       bundler
-      constant_resolver
+      constant_resolver (>= 0.2.0)
+      digest
       parallel
       parser
-      sorbet-runtime
+      sorbet-runtime (>= 0.5.9914)
 
 GEM
   remote: https://rubygems.org/
@@ -116,8 +117,9 @@ GEM
     commander (4.5.2)
       highline (~> 2.0.0)
     concurrent-ruby (1.1.8)
-    constant_resolver (0.1.5)
+    constant_resolver (0.2.0)
     crass (1.0.6)
+    digest (3.1.0)
     erubi (1.10.0)
     globalid (0.4.2)
       activesupport (>= 4.2.0)
@@ -136,16 +138,16 @@ GEM
     marcel (1.0.0)
     method_source (1.0.0)
     mini_mime (1.0.3)
-    mini_portile2 (2.6.1)
+    mini_portile2 (2.8.0)
     minitest (5.14.4)
     minitest-focus (1.2.1)
       minitest (>= 4, < 6)
     mocha (1.12.0)
     nio4r (2.5.7)
-    nokogiri (1.12.5)
-      mini_portile2 (~> 2.6.1)
+    nokogiri (1.13.4)
+      mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
-    nokogiri (1.12.5-x86_64-darwin)
+    nokogiri (1.13.4-x86_64-darwin)
       racc (~> 1.4)
     parallel (1.20.1)
     parlour (6.0.0)
@@ -159,7 +161,7 @@ GEM
       coderay (~> 1.1)
       method_source (~> 1.0)
     psych (3.3.2)
-    racc (1.5.2)
+    racc (1.6.0)
     rack (2.2.3)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
@@ -191,18 +193,19 @@ GEM
     rubocop-sorbet (0.6.1)
       rubocop
     ruby-progressbar (1.11.0)
-    smart_properties (1.16.3)
-    sorbet (0.5.6360)
-      sorbet-static (= 0.5.6360)
-    sorbet-runtime (0.5.6360)
-    sorbet-static (0.5.6360-universal-darwin-14)
-    sorbet-static (0.5.6360-universal-darwin-15)
-    sorbet-static (0.5.6360-universal-darwin-16)
-    sorbet-static (0.5.6360-universal-darwin-17)
-    sorbet-static (0.5.6360-universal-darwin-18)
-    sorbet-static (0.5.6360-universal-darwin-19)
-    sorbet-static (0.5.6360-universal-darwin-20)
-    sorbet-static (0.5.6360-x86_64-linux)
+    smart_properties (1.17.0)
+    sorbet (0.5.9914)
+      sorbet-static (= 0.5.9914)
+    sorbet-runtime (0.5.9914)
+    sorbet-static (0.5.9914-universal-darwin-14)
+    sorbet-static (0.5.9914-universal-darwin-15)
+    sorbet-static (0.5.9914-universal-darwin-16)
+    sorbet-static (0.5.9914-universal-darwin-17)
+    sorbet-static (0.5.9914-universal-darwin-18)
+    sorbet-static (0.5.9914-universal-darwin-19)
+    sorbet-static (0.5.9914-universal-darwin-20)
+    sorbet-static (0.5.9914-universal-darwin-21)
+    sorbet-static (0.5.9914-x86_64-linux)
     spoom (1.1.0)
       colorize
       sorbet (>= 0.5.6347)
@@ -255,6 +258,7 @@ DEPENDENCIES
   sorbet-runtime
   spring
   tapioca
+  zeitwerk
 
 BUNDLED WITH
-   2.2.22
+   2.3.5

data/README.md

@@ -1,6 +1,9 @@
 # Packwerk [![Build Status](https://github.com/Shopify/packwerk/workflows/CI/badge.svg)](https://github.com/Shopify/packwerk/actions?query=workflow%3ACI)
 
-## NOTE: Packwerk is considered to be feature-complete for Shopify's uses. We are currently accepting bug fixes only, and it is not being actively developed. Please fork this project if you are interested in adding new features.
+### ⚠️ While Shopify is actively using `packwerk`, we consider it feature complete.
+We are keeping `packwerk` compatible with current versions of Ruby and Rails, but will accept feature requests only in rare cases. Please submit bug fixes though!
+
+---
 
 > "I know who you are and because of that I know what you do."
 > This knowledge is a dependency that raises the cost of change.
@@ -56,6 +59,15 @@ Read [USAGE.md](USAGE.md) for usage once Packwerk is installed on your project.
 
 "Packwerk" is pronounced [[ˈpakvɛʁk]](https://cdn.shopify.com/s/files/1/0258/7469/files/packwerk.mp3).
 
+## Ecosystem
+
+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/BigRails/danger-packwerk integrates packwerk with [danger.systems](https://danger.systems) to provide packwerk feedback as Github inline PR comments
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/USAGE.md

@@ -77,6 +77,8 @@ Packwerk reads from the `packwerk.yml` configuration file in the root directory.
 | package_paths        | **/                                       | a single pattern or a list of patterns to find package configuration files, see: [Defining packages](#Defining-packages) |
 | custom_associations  | N/A                                       | list of custom associations, if any |
 | parallel             | true                                      | when true, fork code parsing out to subprocesses |
+| cache                | false                                     | when true, caches the results of parsing files |
+| cache_directory      | tmp/cache/packwerk                        | the directory that will hold the packwerk cache |
 
 ### Using a custom ERB parser
 
@@ -100,6 +102,11 @@ end
 Packwerk::Parsers::Factory.instance.erb_parser_class = CustomParser
 ```
 
+## Using the cache
+Packwerk ships with an cache to help speed up file parsing. You can turn this on by setting `cache: true` in `packwerk.yml`.
+
+This will write to `tmp/cache/packwerk`.
+
 ## Validating the package system
 
 There are some criteria that an application must meet in order to have a valid package system. These criteria include having a valid autoload path cache, package definition files, and application folder structure. The dependency graph within the package system also has to be acyclic.

data/lib/packwerk/application_load_paths.rb

@@ -9,7 +9,7 @@ module Packwerk
     class << self
       extend T::Sig
 
-      sig { params(root: String, environment: String).returns(T::Array[String]) }
+      sig { params(root: String, environment: String).returns(T::Hash[String, Module]) }
       def extract_relevant_paths(root, environment)
         require_application(root, environment)
         all_paths = extract_application_autoload_paths
@@ -18,36 +18,30 @@ module Packwerk
         relative_path_strings(relevant_paths)
       end
 
-      sig { returns(T::Array[String]) }
+      sig { returns(T::Hash[String, Module]) }
       def extract_application_autoload_paths
-        Rails.application.railties
-          .select { |railtie| railtie.is_a?(Rails::Engine) }
-          .push(Rails.application)
-          .flat_map do |engine|
-            paths = (engine.config.autoload_paths + engine.config.eager_load_paths + engine.config.autoload_once_paths)
-            paths.map(&:to_s).uniq
-          end
+        Rails.autoloaders.inject({}) do |h, loader|
+          h.merge(loader.root_dirs)
+        end
       end
 
       sig do
-        params(all_paths: T::Array[String], bundle_path: Pathname, rails_root: Pathname)
-          .returns(T::Array[Pathname])
+        params(all_paths: T::Hash[String, Module], bundle_path: Pathname, rails_root: Pathname)
+          .returns(T::Hash[Pathname, Module])
       end
       def filter_relevant_paths(all_paths, bundle_path: Bundler.bundle_path, rails_root: Rails.root)
         bundle_path_match = bundle_path.join("**")
         rails_root_match = rails_root.join("**")
 
         all_paths
-          .map { |path| Pathname.new(path).expand_path }
+          .transform_keys { |path| Pathname.new(path).expand_path }
           .select { |path| path.fnmatch(rails_root_match.to_s) } # path needs to be in application directory
           .reject { |path| path.fnmatch(bundle_path_match.to_s) } # reject paths from vendored gems
       end
 
-      sig { params(paths: T::Array[Pathname], rails_root: Pathname).returns(T::Array[String]) }
-      def relative_path_strings(paths, rails_root: Rails.root)
-        paths
-          .map { |path| path.relative_path_from(rails_root).to_s }
-          .uniq
+      sig { params(load_paths: T::Hash[Pathname, Module], rails_root: Pathname).returns(T::Hash[String, Module]) }
+      def relative_path_strings(load_paths, rails_root: Rails.root)
+        load_paths.transform_keys { |path| Pathname.new(path).relative_path_from(rails_root).to_s }
       end
 
       private
@@ -65,7 +59,7 @@ module Packwerk
         end
       end
 
-      sig { params(paths: T::Array[T.untyped]).void }
+      sig { params(paths: T::Hash[T.untyped, Module]).void }
       def assert_load_paths_present(paths)
         if paths.empty?
           raise <<~EOS

data/lib/packwerk/application_validator.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 require "constant_resolver"
@@ -9,14 +9,36 @@ module Packwerk
   # Checks the structure of the application and its packwerk configuration to make sure we can run a check and deliver
   # correct results.
   class ApplicationValidator
+    extend T::Sig
+
+    sig do
+      params(
+        config_file_path: String,
+        configuration: Configuration,
+        environment: String
+      ).void
+    end
     def initialize(config_file_path:, configuration:, environment:)
       @config_file_path = config_file_path
       @configuration = configuration
       @environment = environment
+      @package_set = T.let(PackageSet.load_all_from(@configuration.root_path, package_pathspec: package_glob),
+        PackageSet)
     end
 
-    Result = Struct.new(:ok?, :error_value)
+    class Result < T::Struct
+      extend T::Sig
+
+      const :ok, T::Boolean
+      const :error_value, T.nilable(String)
+
+      sig { returns(T::Boolean) }
+      def ok?
+        ok
+      end
+    end
 
+    sig { returns(Result) }
     def check_all
       results = [
         check_package_manifests_for_privacy,
@@ -31,6 +53,7 @@ module Packwerk
       merge_results(results)
     end
 
+    sig { returns(Result) }
     def check_package_manifests_for_privacy
       privacy_settings = package_manifests_settings_for("enforce_privacy")
 
@@ -39,13 +62,13 @@ module Packwerk
         load_paths: @configuration.load_paths
       )
 
-      results = []
+      results = T.let([], T::Array[Result])
 
       privacy_settings.each do |config_file_path, setting|
         next unless setting.is_a?(Array)
         constants = setting
 
-        assert_constants_can_be_loaded(constants)
+        results += assert_constants_can_be_loaded(constants, config_file_path)
 
         constant_locations = constants.map { |c| [c, resolver.resolve(c)&.location] }
 
@@ -61,6 +84,7 @@ module Packwerk
       merge_results(results, separator: "\n---\n")
     end
 
+    sig { returns(Result) }
     def check_package_manifest_syntax
       errors = []
 
@@ -102,12 +126,13 @@ module Packwerk
       end
 
       if errors.empty?
-        Result.new(true)
+        Result.new(ok: true)
       else
-        Result.new(false, errors.join("\n---\n"))
+        Result.new(ok: false, error_value: errors.join("\n---\n"))
       end
     end
 
+    sig { returns(Result) }
     def check_application_structure
       resolver = ConstantResolver.new(
         root_path: @configuration.root_path.to_s,
@@ -116,26 +141,27 @@ module Packwerk
 
       begin
         resolver.file_map
-        Result.new(true)
+        Result.new(ok: true)
       rescue => e
-        Result.new(false, e.message)
+        Result.new(ok: false, error_value: e.message)
       end
     end
 
+    sig { returns(Result) }
     def check_acyclic_graph
-      edges = package_set.flat_map do |package|
-        package.dependencies.map { |dependency| [package, package_set.fetch(dependency)] }
+      edges = @package_set.flat_map do |package|
+        package.dependencies.map { |dependency| [package, @package_set.fetch(dependency)] }
       end
-      dependency_graph = Packwerk::Graph.new(*T.unsafe(edges))
+      dependency_graph = Graph.new(*T.unsafe(edges))
 
       cycle_strings = build_cycle_strings(dependency_graph.cycles)
 
       if dependency_graph.acyclic?
-        Result.new(true)
+        Result.new(ok: true)
       else
         Result.new(
-          false,
-          <<~EOS
+          ok: false,
+          error_value: <<~EOS
             Expected the package dependency graph to be acyclic, but it contains the following cycles:
 
             #{cycle_strings.join("\n")}
@@ -144,6 +170,7 @@ module Packwerk
       end
     end
 
+    sig { returns(Result) }
     def check_package_manifest_paths
       all_package_manifests = package_manifests("**/")
       package_paths_package_manifests = package_manifests(package_glob)
@@ -151,11 +178,11 @@ module Packwerk
       difference = all_package_manifests - package_paths_package_manifests
 
       if difference.empty?
-        Result.new(true)
+        Result.new(ok: true)
       else
         Result.new(
-          false,
-          <<~EOS
+          ok: false,
+          error_value: <<~EOS
             Expected package paths for all package.ymls to be specified, but paths were missing for the following manifests:
 
             #{relative_paths(difference).join("\n")}
@@ -164,6 +191,7 @@ module Packwerk
       end
     end
 
+    sig { returns(Result) }
     def check_valid_package_dependencies
       packages_dependencies = package_manifests_settings_for("dependencies")
         .delete_if { |_, deps| deps.nil? }
@@ -175,7 +203,7 @@ module Packwerk
         end
 
       if packages_with_invalid_dependencies.empty?
-        Result.new(true)
+        Result.new(ok: true)
       else
         error_locations = packages_with_invalid_dependencies.map do |package, invalid_dependencies|
           package ||= @configuration.root_path
@@ -189,8 +217,8 @@ module Packwerk
         end
 
         Result.new(
-          false,
-          <<~EOS
+          ok: false,
+          error_value: <<~EOS
             These dependencies do not point to valid packages:
 
             #{error_locations.join("\n")}
@@ -199,16 +227,17 @@ module Packwerk
       end
     end
 
+    sig { returns(Result) }
     def check_root_package_exists
       root_package_path = File.join(@configuration.root_path, "package.yml")
       all_packages_manifests = package_manifests(package_glob)
 
       if all_packages_manifests.include?(root_package_path)
-        Result.new(true)
+        Result.new(ok: true)
       else
         Result.new(
-          false,
-          <<~EOS
+          ok: false,
+          error_value: <<~EOS
             A root package does not exist. Create an empty `package.yml` at the root directory.
           EOS
         )
@@ -224,6 +253,7 @@ module Packwerk
     # to the string:
     #
     #   ["a -> b -> c -> a", "b -> c -> b"]
+    sig { params(cycles: T.untyped).returns(T::Array[String]) }
     def build_cycle_strings(cycles)
       cycles.map do |cycle|
         cycle_strings = cycle.map(&:to_s)
@@ -232,84 +262,102 @@ module Packwerk
       end
     end
 
+    sig { params(setting: T.untyped).returns(T.untyped) }
     def package_manifests_settings_for(setting)
       package_manifests.map { |f| [f, (YAML.load_file(File.join(f)) || {})[setting]] }
     end
 
+    sig { params(list: T.untyped).returns(T.untyped) }
     def format_yaml_strings(list)
       list.sort.map { |p| "- \"#{p}\"" }.join("\n")
     end
 
+    sig { returns(T.any(T::Array[String], String)) }
     def package_glob
       @configuration.package_paths || "**"
     end
 
+    sig { params(glob_pattern: T.any(T::Array[String], String)).returns(T::Array[String]) }
     def package_manifests(glob_pattern = package_glob)
       PackageSet.package_paths(@configuration.root_path, glob_pattern, @configuration.exclude)
         .map { |f| File.realpath(f) }
     end
 
+    sig { params(paths: T::Array[String]).returns(T::Array[Pathname]) }
     def relative_paths(paths)
       paths.map { |path| relative_path(path) }
     end
 
+    sig { params(path: String).returns(Pathname) }
     def relative_path(path)
       Pathname.new(path).relative_path_from(@configuration.root_path)
     end
 
+    sig { params(path: T.untyped).returns(T::Boolean) }
     def invalid_package_path?(path)
       # Packages at the root can be implicitly specified as "."
       return false if path == "."
 
-      package_path = File.join(@configuration.root_path, path, Packwerk::PackageSet::PACKAGE_CONFIG_FILENAME)
+      package_path = File.join(@configuration.root_path, path, PackageSet::PACKAGE_CONFIG_FILENAME)
       !File.file?(package_path)
     end
 
-    def assert_constants_can_be_loaded(constants)
-      constants.each(&:constantize)
-      nil
+    sig { params(constants: T.untyped, config_file_path: String).returns(T::Array[Result]) }
+    def assert_constants_can_be_loaded(constants, config_file_path)
+      constants.map do |constant|
+        if !constant.start_with?("::")
+          Result.new(
+            ok: false,
+            error_value: "'#{constant}', listed in the 'enforce_privacy' option in #{config_file_path}, is invalid.\n"\
+            "Private constants need to be prefixed with the top-level namespace operator `::`."
+          )
+        else
+          constant.try(&:constantize) && Result.new(ok: true)
+        end
+      end
     end
 
+    sig { params(name: T.untyped, config_file_path: T.untyped).returns(Result) }
     def private_constant_unresolvable(name, config_file_path)
       explicit_filepath = (name.start_with?("::") ? name[2..-1] : name).underscore + ".rb"
 
       Result.new(
-        false,
-        "'#{name}', listed in #{config_file_path}, could not be resolved.\n"\
+        ok: false,
+        error_value: "'#{name}', listed in #{config_file_path}, could not be resolved.\n"\
         "This is probably because it is an autovivified namespace - a namespace module that doesn't have a\n"\
         "file explicitly defining it. Packwerk currently doesn't support declaring autovivified namespaces as\n"\
         "private. Add a #{explicit_filepath} file to explicitly define the constant."
       )
     end
 
+    sig { params(name: T.untyped, location: T.untyped, config_file_path: T.untyped).returns(Result) }
     def check_private_constant_location(name, location, config_file_path)
-      declared_package = package_set.package_from_path(relative_path(config_file_path))
-      constant_package = package_set.package_from_path(location)
+      declared_package = @package_set.package_from_path(relative_path(config_file_path))
+      constant_package = @package_set.package_from_path(location)
 
       if constant_package == declared_package
-        Result.new(true)
+        Result.new(ok: true)
       else
         Result.new(
-          false,
-          "'#{name}' is declared as private in the '#{declared_package}' package but appears to be "\
+          ok: false,
+          error_value: "'#{name}' is declared as private in the '#{declared_package}' package but appears to be "\
           "defined\nin the '#{constant_package}' package. Packwerk resolved it to #{location}."
         )
       end
     end
 
-    def package_set
-      @package_set ||= Packwerk::PackageSet.load_all_from(@configuration.root_path, package_pathspec: package_glob)
+    sig do
+      params(results: T::Array[Result], separator: String, errors_headline: String).returns(Result)
     end
-
     def merge_results(results, separator: "\n===\n", errors_headline: "")
       results.reject!(&:ok?)
 
       if results.empty?
-        Result.new(true)
+        Result.new(ok: true)
       else
         Result.new(
-          false,
-          errors_headline + results.map(&:error_value).join(separator)
+          ok: false,
+          error_value: errors_headline + results.map(&:error_value).join(separator)
         )
       end
     end