packwerk 1.3.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bd8ccbf44a3bfe1eb5a0afb97fce3740ae641d1f8e938ad8bc8351d4ff8f74b
-  data.tar.gz: 697369e81f54c8130844d4de6bcee75c328eeda1de8b24e04736acd5bbe1ed2a
+  metadata.gz: 66332315c1155336fbe79f8aeb6e44a0893d4100a1d4b6b5f08c81574c940fe0
+  data.tar.gz: 88da350ce07daaf7556d23edbc318a19ca33b74af71ee624d547a8a8598bc16b
 SHA512:
-  metadata.gz: ac77bcba32e7e15a2c61aae6b90d76ef2dcae8c3d408a9e5b9746ea268c14a7421aabf082ac63148a1d53fb74b7ab3780c8145e50a9868a67472ad09294718e6
-  data.tar.gz: 3c1819b3cf5417add105c1755856033dbc5339ed093450c45f241dd9aeb4828000fa67633f2a402f43634ea61af29d0f23d1244ea9049811714aab10f23fdd59
+  metadata.gz: b54eeeac5e68285e03c32916d72f2afdc291d9d6d4993de0d2875d7dbb4a9cdf8cde7ca2677107f35288a20a20c1f8fc2f9ddcc330c9a7fe0dfaf8e245c07b3c
+  data.tar.gz: d8597878958e00a069cb5e51c609e04da9526b3c1933c4824399e4bad1173d718703c88ec582411a9c73fb5c88899707b04ebdb7b296a22b70e25598e11b57d6

data/CHANGELOG.md

@@ -0,0 +1 @@
+See https://github.com/Shopify/packwerk/releases.

data/Gemfile.lock

@@ -87,11 +87,13 @@ GIT
 PATH
   remote: .
   specs:
-    packwerk (1.3.1)
+    packwerk (2.1.0)
       activesupport (>= 5.2)
       ast
       better_html
+      bundler
       constant_resolver
+      digest
       parallel
       parser
       sorbet-runtime
@@ -117,6 +119,7 @@ GEM
     concurrent-ruby (1.1.8)
     constant_resolver (0.1.5)
     crass (1.0.6)
+    digest (3.1.0)
     erubi (1.10.0)
     globalid (0.4.2)
       activesupport (>= 4.2.0)
@@ -135,16 +138,14 @@ GEM
     marcel (1.0.0)
     method_source (1.0.0)
     mini_mime (1.0.3)
-    mini_portile2 (2.5.1)
+    mini_portile2 (2.6.1)
     minitest (5.14.4)
     minitest-focus (1.2.1)
       minitest (>= 4, < 6)
     mocha (1.12.0)
     nio4r (2.5.7)
-    nokogiri (1.11.5)
-      mini_portile2 (~> 2.5.0)
-      racc (~> 1.4)
-    nokogiri (1.11.5-x86_64-darwin)
+    nokogiri (1.12.5)
+      mini_portile2 (~> 2.6.1)
       racc (~> 1.4)
     parallel (1.20.1)
     parlour (6.0.0)
@@ -157,6 +158,7 @@ GEM
     pry (0.14.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
+    psych (3.3.2)
     racc (1.5.2)
     rack (2.2.3)
     rack-test (1.1.0)
@@ -189,7 +191,7 @@ GEM
     rubocop-sorbet (0.6.1)
       rubocop
     ruby-progressbar (1.11.0)
-    smart_properties (1.15.0)
+    smart_properties (1.16.3)
     sorbet (0.5.6360)
       sorbet-static (= 0.5.6360)
     sorbet-runtime (0.5.6360)
@@ -233,16 +235,17 @@ GEM
 
 PLATFORMS
   ruby
+  x86_64-darwin
   x86_64-darwin-20
 
 DEPENDENCIES
-  bundler
   byebug
   constant_resolver
   m
   minitest-focus
   mocha
   packwerk!
+  psych (~> 3)
   rails!
   rake
   rubocop-performance
@@ -254,4 +257,4 @@ DEPENDENCIES
   tapioca
 
 BUNDLED WITH
-   2.2.15
+   2.3.4

data/README.md

@@ -35,8 +35,6 @@ Watch a [1-minute video demo](https://www.youtube.com/watch?v=NwqlyBAxVpQ&featur
 gem 'packwerk'
 ```
 
-_Note: Packwerk has to be grouped in production environment within the Gemfile if your Rails app has custom inflections._
-
 2. Install the gem
 
 Execute:
@@ -47,7 +45,8 @@ Or install it yourself as:
 
     $ gem install packwerk
 
-3. Run `packwerk init` to generate the configuration files
+2. Run `bundle binstub packwerk` to generate the binstub
+3. Run `bin/packwerk init` to generate the configuration files
 
 ## Usage
 
@@ -57,6 +56,13 @@ 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
+
+You can use these third party tools to enhance your packwerk experience:
+
+- 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
+
 ## 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/TROUBLESHOOT.md

@@ -14,11 +14,11 @@ Packwerk can give feedback via continuous integration (CI) if you have it set up
 
 You can specify folders or packages in Packwerk commands for a shorter run time:
 
-     packwerk check components/your_package
+     bin/packwerk check components/your_package
 
-     packwerk update-deprecations components/your_package
+     bin/packwerk update-deprecations components/your_package
 
-_Note: You cannot specify folders or packages for `packwerk validate` because the command runs for the entire application._
+_Note: You cannot specify folders or packages for `bin/packwerk validate` because the command runs for the entire application._
 
 ![](static/packwerk_check_violation.gif)
 

data/UPGRADING.md

@@ -0,0 +1,54 @@
+# Upgrading from 1.x to 2.0
+
+With Packwerk 2.0, we made a few changes to simplify the setup. Updating will require removing some previously necessary files and configuration.
+
+## Gem group
+
+Because packwerk is no longer involved in specifying the application's inflections, it doesn't have to live in the `production` group in your `Gemfile` anymore. We recommend moving it to the `development` group.
+
+## Removing application config caches
+
+### Load paths
+We no longer require the `load_paths` key in `packwerk.yml`. You can simply delete the load_paths key as it will not be read anymore. Instead, Packwerk will ask Rails for load paths. If you're using spring, make sure to properly set up spring (see [USAGE.md](USAGE.md#setting-up-spring)) to keep packwerk fast.
+
+### Inflections
+We no longer require a custom `inflections.yml` file. Instead, you'll want to revert BACK to using the `inflections.rb` initializer as you would have done prior to adopting packwerk. To do this, you'll want to convert back to using the plain [ActiveSupport Inflections API](https://api.rubyonrails.org/classes/ActiveSupport/Inflector/Inflections.html).
+
+
+Given the following example `inflections.yml`, here is an example `inflections.rb` that would follow. Tip: if you're using git, you can run `git log config/inflections.yml`, find the first commit that introduced `inflections.yml`, find the COMMIT_SHA, and then run `git show COMMIT_SHA` to see what your inflections file looked like before (note that you may have changed `inflections.yml` since then, though).
+
+`config/inflections.yml`
+```yml
+# List your inflections in this file instead of `inflections.rb`
+# See steps to set up custom inflections:
+# https://github.com/Shopify/packwerk/blob/main/USAGE.md#Inflections
+
+acronym:
+ - 'HTML'
+ - 'API'
+
+singular:
+ - ['oxen', 'oxen']
+
+irregular:
+ - ['person', 'people']
+
+uncountable:
+ - 'fish'
+ - 'sheep'
+```
+
+`config/initializers/inflections.rb`
+```ruby
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  inflect.acronym('HTML')
+  inflect.acronym('API')
+
+  inflect.singular('oxen', 'oxen')
+
+  inflect.irregular('person', 'people')
+
+  inflect.uncountable('fish')
+  inflect.uncountable('sheep')
+ end
+```

data/USAGE.md

@@ -6,8 +6,9 @@
 * [What is a package?](#what-is-a-package)
   * [Package principles](#package-principles)
 * [Getting started](#getting-started)
-* [Setting up the configuration file](#setting-up-the-configuration-file)
-  * [Inflections](#inflections)
+  * [Setting up Spring](#setting-up-spring)
+* [Configuring Packwerk](#configuring-packwerk)
+  * [Using a custom ERB parser](#using-a-custom-erb-parser)
 * [Validating the package system](#validating-the-package-system)
 * [Defining packages](#defining-packages)
   * [Package metadata](#package-metadata)
@@ -42,9 +43,12 @@ The [package principles](https://en.wikipedia.org/wiki/Package_principles) page
 
 ## Getting started
 
-After including Packwerk in the Gemfile, you can generate the necessary files to get Packwerk running by executing:
+After including Packwerk in the Gemfile, you will first want to generate a binstub:
+You can do this by running `bundle binstub packwerk`, which will generate a [binstub](https://bundler.io/man/bundle-binstubs.1.html#DESCRIPTION) at `bin/packwerk`.
 
-    packwerk init
+Then, you can generate the necessary files to get Packwerk running by executing:
+
+    bin/packwerk init
 
 Here is a list of files generated:
 
@@ -52,11 +56,17 @@ Here is a list of files generated:
 |-----------------------------|--------------|------------|
 | Packwerk configuration      | packwerk.yml | See [Setting up the configuration file](#Setting-up-the-configuration-file) |
 | Root package                | package.yml  | A package for the root folder |
-| Custom inflections          | config/inflections.yml | A custom inflections file is only required if you have custom inflections in `inflections.rb`, see [Inflections](#Inflections) |
 
 After that, you may begin creating packages for your application. See [Defining packages](#Defining-packages)
 
-## Setting up the configuration file
+### Setting up Spring
+
+[Spring](https://github.com/rails/spring) is a preloader for Rails. Because `packwerk` loads `Rails`, it can be sped up dramatically by enabling spring.  Packwerk supports the usage of Spring.
+Firstly, spring needs to know about the packwerk spring command when spring is loading. To do that, add `require 'packwerk/spring_command'` to `config/spring.rb` in your application.
+Secondly, to enable Spring, first run `bin/spring binstub packwerk` which will "springify" the generated binstub.
+
+
+## Configuring Packwerk
 
 Packwerk reads from the `packwerk.yml` configuration file in the root directory. Packwerk will run with the default configuration if any of these settings are not specified.
 
@@ -65,9 +75,10 @@ Packwerk reads from the `packwerk.yml` configuration file in the root directory.
 | include              | **/*.{rb,rake,erb}                        | list of patterns for folder paths to include |
 | exclude              | {bin,node_modules,script,tmp,vendor}/**/* | list of patterns for folder paths to exclude |
 | package_paths        | **/                                       | a single pattern or a list of patterns to find package configuration files, see: [Defining packages](#Defining-packages) |
-| load_paths           | All application autoload paths            | list of load paths |
 | 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
 
@@ -91,50 +102,16 @@ end
 Packwerk::Parsers::Factory.instance.erb_parser_class = CustomParser
 ```
 
-### Inflections
-
-Packwerk requires custom inflections to be defined in `inflections.yml` instead of the traditional `inflections.rb`. This is because Packwerk accounts for custom inflections, such as acronyms, when resolving constants. Additionally, Packwerk interprets Active Record associations as references to constants. For example, `has_many :birds` is a reference to the `Bird` constant.
-
-In order to make your custom inflections compatible with Active Support and Packwerk, you must create a `config/inflections.yml` file and point `ActiveSupport::Inflector` to that file.
-
-In `inflections.rb`, add:
-
-```rb
-require "packwerk/inflections/custom"
-
-ActiveSupport::Inflector.inflections do |inflect|
-  # please add all custom inflections in the file below.
-  Packwerk::Inflections::Custom.new(
-    Rails.root.join("config", "inflections.yml")
-  ).apply_to(inflect)
-end
-```
-
-_Note: Packwerk has to be grouped in production environment within the Gemfile if you have custom inflections._
+## 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`.
 
-Next, move your existing custom inflections into `config/inflections.yml`:
-
-```yaml
-acronym:
-  - 'GraphQL'
-  - 'MRuby'
-  - 'TOS'
-irregular:
-  - ['analysis', 'analyses']
-  - ['reserve', 'reserves']
-uncountable:
-  - 'payment_details'
-singular:
-  - [!ruby/regexp /status$/, 'status']
-```
-
-Any new inflectors should be added to `config/inflections.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.
 
-We recommend setting up the package system validation for your Rails application in a CI step (or through a test suite for Ruby projects) separate from `packwerk check`.
+We recommend setting up the package system validation for your Rails application in a CI step (or through a test suite for Ruby projects) separate from `bin/packwerk check`.
 
 Use the following command to validate the application:
 
@@ -231,13 +208,17 @@ After enforcing the boundary checks for a package, you may execute:
 
 Packwerk will check the entire codebase for any new or stale violations.
 
-You can also specify folders or packages for a shorter run time:
+You can also specify folders for a shorter run time. When checking against folders all subfolders will be analyzed, irrespective of nested package boundaries.
 
     packwerk check components/your_package
 
+You can also specify packages for a shorter run time. When checking against packages any packages nested underneath the specified packages will not be checked. This can be helpful to test packages like the root package, which can have many nested packages.
+
+    packwerk check --packages=components/your_package,components/your_other_package
+
 ![](static/packwerk_check.gif)
 
-In order to keep the package system valid at each version of the application, we recommend running `packwerk check` in your CI pipeline.
+In order to keep the package system valid at each version of the application, we recommend running `bin/packwerk check` in your CI pipeline.
 
 See: [TROUBLESHOOT.md - Sample violations](TROUBLESHOOT.md#Sample-violations)
 
@@ -247,17 +228,17 @@ For existing codebases, packages are likely to have existing boundary violations
 
 If so, you will want to stop the bleeding and prevent more violations from occuring. The existing violations in the codebase can be recorded in a [deprecated references list](#Understanding_the_list_of_deprecated_references) by executing:
 
-    packwerk update-deprecations
+    bin/packwerk update-deprecations
 
-Similar to `packwerk check`, you may also run `packwerk update-deprecations` on folders or packages:
+Similar to `bin/packwerk check`, you may also run `bin/packwerk update-deprecations` on folders or packages:
 
-    packwerk update-deprecations components/your_package
+    bin/packwerk update-deprecations components/your_package
 
 ![](static/packwerk_update.gif)
 
 _Note: Changing dependencies or enabling dependencies will not require a full update of the codebase, only the package that changed. On the other hand, changing or enabling privacy will require a full update of the codebase._
 
-`packwerk update-deprecations` should only be run to record existing violations and to remove deprecated references that have been worked off. Running `packwerk update-deprecations` to resolve a violation should be the very last resort.
+`bin/packwerk update-deprecations` should only be run to record existing violations and to remove deprecated references that have been worked off. Running `bin/packwerk update-deprecations` to resolve a violation should be the very last resort.
 
 See: [TROUBLESHOOT.md - Troubleshooting violations](TROUBLESHOOT.md#Troubleshooting_violations)
 

data/exe/packwerk

@@ -3,4 +3,10 @@
 
 require "packwerk"
 
-Packwerk::Cli.new(style: Packwerk::OutputStyles::Coloured.new).run(ARGV.dup)
+# Needs to be run in test environment in order to have test helper paths available in the autoload paths
+ENV["RAILS_ENV"] = "test"
+
+# Command line arguments needs to be duplicated because spring modifies it
+packwerk_argv = ARGV.dup
+cli = Packwerk::Cli.new(style: Packwerk::OutputStyles::Coloured.new)
+cli.run(packwerk_argv)

data/lib/packwerk/application_load_paths.rb

@@ -4,6 +4,7 @@
 require "bundler"
 
 module Packwerk
+  # Extracts the load paths from the analyzed application so that we can map constant names to paths.
   module ApplicationLoadPaths
     class << self
       extend T::Sig

data/lib/packwerk/application_validator.rb

@@ -1,30 +1,27 @@
 # typed: true
 # frozen_string_literal: true
 
-require "active_support/inflector/inflections"
 require "constant_resolver"
 require "pathname"
 require "yaml"
 
 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
     def initialize(config_file_path:, configuration:, environment:)
       @config_file_path = config_file_path
       @configuration = configuration
       @environment = environment
-
-      @application_load_paths = ApplicationLoadPaths.extract_relevant_paths(configuration.root_path, environment)
     end
 
     Result = Struct.new(:ok?, :error_value)
 
     def check_all
       results = [
-        check_autoload_path_cache,
         check_package_manifests_for_privacy,
         check_package_manifest_syntax,
         check_application_structure,
-        check_inflection_file,
         check_acyclic_graph,
         check_package_manifest_paths,
         check_valid_package_dependencies,
@@ -34,21 +31,6 @@ module Packwerk
       merge_results(results)
     end
 
-    def check_autoload_path_cache
-      expected = @application_load_paths
-      actual = @configuration.load_paths
-      if expected.sort == actual.sort
-        Result.new(true)
-      else
-        Result.new(
-          false,
-          "Load path cache in #{@config_file_path} incorrect!\n"\
-          "Paths missing from file:\n#{format_yaml_strings(expected - actual)}\n"\
-          "Extraneous load paths in file:\n#{format_yaml_strings(actual - expected)}"
-        )
-      end
-    end
-
     def check_package_manifests_for_privacy
       privacy_settings = package_manifests_settings_for("enforce_privacy")
 
@@ -57,13 +39,13 @@ module Packwerk
         load_paths: @configuration.load_paths
       )
 
-      results = []
+      results = T.let([], T::Array[Packwerk::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] }
 
@@ -140,39 +122,6 @@ module Packwerk
       end
     end
 
-    def check_inflection_file
-      inflections_file = @configuration.inflections_file
-
-      application_inflections = ActiveSupport::Inflector.inflections
-      packwerk_inflections = Packwerk::Inflector.from_file(inflections_file).inflections
-
-      results = %i(plurals singulars uncountables humans acronyms).map do |type|
-        expected = application_inflections.public_send(type).to_set
-        actual = packwerk_inflections.public_send(type).to_set
-
-        if expected == actual
-          Result.new(true)
-        else
-          missing_msg = unless (expected - actual).empty?
-            "Expected #{type} to be specified in file: #{expected - actual}"
-          end
-          extraneous_msg = unless (actual - expected).empty?
-            "Extraneous #{type} was specified in file: #{actual - expected}"
-          end
-          Result.new(
-            false,
-            [missing_msg, extraneous_msg].join("\n")
-          )
-        end
-      end
-
-      merge_results(
-        results,
-        separator: "\n",
-        errors_headline: "Inflections specified in #{inflections_file} don't line up with application!\n"
-      )
-    end
-
     def check_acyclic_graph
       edges = package_set.flat_map do |package|
         package.dependencies.map { |dependency| [package, package_set.fetch(dependency)] }
@@ -296,7 +245,7 @@ module Packwerk
     end
 
     def package_manifests(glob_pattern = package_glob)
-      PackageSet.package_paths(@configuration.root_path, glob_pattern)
+      PackageSet.package_paths(@configuration.root_path, glob_pattern, @configuration.exclude)
         .map { |f| File.realpath(f) }
     end
 
@@ -316,9 +265,18 @@ module Packwerk
       !File.file?(package_path)
     end
 
-    def assert_constants_can_be_loaded(constants)
-      constants.each(&:constantize)
-      nil
+    def assert_constants_can_be_loaded(constants, config_file_path)
+      constants.map do |constant|
+        if !constant.start_with?("::")
+          Result.new(
+            false,
+            "'#{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(true)
+        end
+      end
     end
 
     def private_constant_unresolvable(name, config_file_path)

data/lib/packwerk/association_inspector.rb

@@ -19,7 +19,7 @@ module Packwerk
       CustomAssociations
     )
 
-    sig { params(inflector: Inflector, custom_associations: CustomAssociations).void }
+    sig { params(inflector: T.class_of(ActiveSupport::Inflector), custom_associations: CustomAssociations).void }
     def initialize(inflector:, custom_associations: Set.new)
       @inflector = inflector
       @associations = T.let(RAILS_ASSOCIATIONS + custom_associations, CustomAssociations)