Enable spring by default when executing packwerk init

README.md

@@ -47,7 +47,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
 

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)
 

USAGE.md

@@ -42,9 +42,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:
 
@@ -69,6 +72,12 @@ Packwerk reads from the `packwerk.yml` configuration file in the root directory.
 | custom_associations  | N/A                                       | list of custom associations, if any |
 | parallel             | true                                      | when true, fork code parsing out to subprocesses |
 
+## 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. 
+
 ### Using a custom ERB parser
 
 You can specify a custom ERB parser if needed. For example, if you're using `<%graphql>` tags from https://github.com/github/graphql-client in your ERBs, you can use a custom parser subclass to comment them out so that Packwerk can parse the rest of the file:
@@ -134,7 +143,7 @@ Any new inflectors should be added to `config/inflections.yml`.
 
 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:
 
@@ -237,7 +246,7 @@ You can also specify folders for a shorter run time:
 
 ![](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 +256,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)
 

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)

lib/packwerk/cli.rb

@@ -98,7 +98,7 @@ def generate_configs
       result = if success
         <<~EOS
 
-          🎉 Packwerk is ready to be used. You can start defining packages and run `packwerk check`.
+          🎉 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

lib/packwerk/deprecated_references.rb

@@ -77,7 +77,7 @@ def dump
           #
           # You can regenerate this file using the following command:
           #
-          # packwerk update-deprecations #{@package.name}
+          # bin/packwerk update-deprecations #{@package.name}
         MESSAGE
         File.open(@filepath, "w") do |f|
           f.write(message)

lib/packwerk/spring_command.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# typed: false
+
+require "spring/commands"
+
+module Packwerk
+  class SpringCommand
+    def env(*)
+      # Packwerk needs to run in a test environment, which has a set of autoload paths that are
+      # often a superset of the dev/prod paths (for example, test/support/helpers)
+      "test"
+    end
+
+    def exec_name
+      "packwerk"
+    end
+
+    def gem_name
+      "packwerk"
+    end
+
+    def call
+      load(Gem.bin_path(gem_name, exec_name))
+    end
+  end
+
+  Spring.register_command("packwerk", SpringCommand.new)
+end

test/unit/spring_command_test.rb

@@ -0,0 +1,20 @@
+# typed: ignore
+# frozen_string_literal: true
+
+require "test_helper"
+require "spring/commands"
+
+module Packwerk
+  class SpringCommandTest < Minitest::Test
+    test "registers command with Spring when loaded" do
+      require "packwerk/spring_command"
+
+      command = Spring.command("packwerk")
+
+      assert_not_nil(command, message: "packwerk command not registered with Spring")
+      assert_equal("packwerk", command.exec_name)
+      assert_equal("packwerk", command.gem_name)
+      assert_equal("test", command.env(nil))
+    end
+  end
+end