packwerk 2.3.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94a6e793dd2c071a7bfb9a739fb6aaf2e07b0d2183bf743afb38da5e3847f0e2
-  data.tar.gz: dd779094dad5572746476d25d63e26f29819cf0b57519f73a4f693610cfd238e
+  metadata.gz: 9af43a5e2d624ca5d6b38bfa3c9e65d1d12b1b9cc148a153563ebd55d3b6c82a
+  data.tar.gz: 6dee0dac16640632fb272c72ebe024a36c6a85ba23748b2ab5886279cccd863c
 SHA512:
-  metadata.gz: 9ff4d2a2aa7b6cb34e59362321ea3fb22826d10430addeef1b6143408d1a1b510ff8915105f2e74e9173334dfcfbd0a76610ea00242a2720c6feb9c75b53556f
-  data.tar.gz: 7ed4cbe3376821d54a5a58e2bc25ac3baf1f03a84928e027c0e1e1f39d52a14df4e18cc8d9ecfa50de3756507f46c0e9687d04464d3ec149037a7fdecb8eed0e
+  metadata.gz: 197f933a60a46aba470ee66a2c04bbabcf1ff3c3386665551dbb7b8241b9357d73e7576de7edd7c322249b8d45cfc0b282616e0f9a5a665d4560964632a66806
+  data.tar.gz: ec903a206f47df277d6187afc5c17a9cfa1591446afb249f2ba62171f7c56ba8687ce403041db451eb8ea0dba842feb26cc7c32e9ff600b93e60e49eafb4584f

data/.github/workflows/ci.yml

@@ -1,6 +1,6 @@
 name: CI
 
-on: [push]
+on: [push, pull_request]
 
 jobs:
   tests:
@@ -12,13 +12,10 @@ jobs:
           - gemfiles/Gemfile-rails-6-0
           - gemfiles/Gemfile-rails-6-1
         ruby:
-          - 2.6
           - 2.7
           - 3.0
           - 3.1
-        exclude:
-          - ruby: 2.6
-            gemfile: Gemfile
+          - 3.2
     env:
       BUNDLE_GEMFILE: ${{ matrix.gemfile }}
     name: "Tests: Ruby ${{ matrix.ruby }} ${{ matrix.gemfile }}"

data/.ruby-version

@@ -1 +1 @@
-3.0.0
+3.2.1

data/Gemfile

@@ -8,7 +8,6 @@ gemspec
 # Specify the same dependency sources as the application Gemfile
 
 gem("spring")
-gem("rails")
 gem("constant_resolver", require: false)
 gem("rubocop-performance", require: false)
 gem("rubocop-sorbet", require: false)

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    packwerk (2.3.0)
-      activesupport (>= 5.2)
+    packwerk (3.0.1)
+      activesupport (>= 6.0)
       ast
       better_html
       bundler
@@ -15,31 +15,6 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    actioncable (7.0.3.1)
-      actionpack (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
-      nio4r (~> 2.0)
-      websocket-driver (>= 0.6.1)
-    actionmailbox (7.0.3.1)
-      actionpack (= 7.0.3.1)
-      activejob (= 7.0.3.1)
-      activerecord (= 7.0.3.1)
-      activestorage (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
-      mail (>= 2.7.1)
-      net-imap
-      net-pop
-      net-smtp
-    actionmailer (7.0.3.1)
-      actionpack (= 7.0.3.1)
-      actionview (= 7.0.3.1)
-      activejob (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
-      mail (~> 2.5, >= 2.5.4)
-      net-imap
-      net-pop
-      net-smtp
-      rails-dom-testing (~> 2.0)
     actionpack (7.0.3.1)
       actionview (= 7.0.3.1)
       activesupport (= 7.0.3.1)
@@ -47,34 +22,12 @@ GEM
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.2.0)
-    actiontext (7.0.3.1)
-      actionpack (= 7.0.3.1)
-      activerecord (= 7.0.3.1)
-      activestorage (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
-      globalid (>= 0.6.0)
-      nokogiri (>= 1.8.5)
     actionview (7.0.3.1)
       activesupport (= 7.0.3.1)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activejob (7.0.3.1)
-      activesupport (= 7.0.3.1)
-      globalid (>= 0.3.6)
-    activemodel (7.0.3.1)
-      activesupport (= 7.0.3.1)
-    activerecord (7.0.3.1)
-      activemodel (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
-    activestorage (7.0.3.1)
-      actionpack (= 7.0.3.1)
-      activejob (= 7.0.3.1)
-      activerecord (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
-      marcel (~> 1.0)
-      mini_mime (>= 1.1.0)
     activesupport (7.0.3.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
@@ -95,10 +48,7 @@ GEM
     constant_resolver (0.2.0)
     crass (1.0.6)
     diff-lcs (1.5.0)
-    digest (3.1.0)
     erubi (1.11.0)
-    globalid (1.0.0)
-      activesupport (>= 5.0)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
     json (2.6.2)
@@ -109,37 +59,16 @@ GEM
     m (1.6.0)
       method_source (>= 0.6.7)
       rake (>= 0.9.2.2)
-    mail (2.7.1)
-      mini_mime (>= 0.1.1)
-    marcel (1.0.2)
     method_source (1.0.0)
-    mini_mime (1.1.2)
     mini_portile2 (2.8.0)
     minitest (5.16.2)
     minitest-focus (1.3.1)
       minitest (>= 4, < 6)
     mocha (1.14.0)
-    net-imap (0.2.3)
-      digest
-      net-protocol
-      strscan
-    net-pop (0.1.1)
-      digest
-      net-protocol
-      timeout
-    net-protocol (0.1.3)
-      timeout
-    net-smtp (0.3.1)
-      digest
-      net-protocol
-      timeout
     netrc (0.11.0)
-    nio4r (2.5.8)
     nokogiri (1.13.8)
       mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
-    nokogiri (1.13.8-x86_64-darwin)
-      racc (~> 1.4)
     parallel (1.22.1)
     parser (3.1.2.1)
       ast (~> 2.4.1)
@@ -151,20 +80,6 @@ GEM
     rack (2.2.4)
     rack-test (2.0.2)
       rack (>= 1.3)
-    rails (7.0.3.1)
-      actioncable (= 7.0.3.1)
-      actionmailbox (= 7.0.3.1)
-      actionmailer (= 7.0.3.1)
-      actionpack (= 7.0.3.1)
-      actiontext (= 7.0.3.1)
-      actionview (= 7.0.3.1)
-      activejob (= 7.0.3.1)
-      activemodel (= 7.0.3.1)
-      activerecord (= 7.0.3.1)
-      activestorage (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
-      bundler (>= 1.15.0)
-      railties (= 7.0.3.1)
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
@@ -232,7 +147,6 @@ GEM
       sorbet-runtime (>= 0.5.9204)
       thor (>= 0.19.2)
     spring (4.0.0)
-    strscan (3.0.4)
     syntax_tree (3.3.0)
       prettier_print
     tapioca (0.9.2)
@@ -246,7 +160,6 @@ GEM
       thor (>= 1.2.0)
       yard-sorbet
     thor (1.2.1)
-    timeout (0.3.0)
     tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.2.0)
@@ -254,15 +167,12 @@ GEM
       diff-lcs (~> 1.3)
       parser (>= 3.1.0)
     webrick (1.7.0)
-    websocket-driver (0.7.5)
-      websocket-extensions (>= 0.1.0)
-    websocket-extensions (0.1.5)
     yard (0.9.28)
       webrick (~> 1.7.0)
     yard-sorbet (0.6.1)
       sorbet-runtime (>= 0.5)
       yard (>= 0.9)
-    zeitwerk (2.6.6)
+    zeitwerk (2.6.4)
 
 PLATFORMS
   ruby
@@ -276,7 +186,7 @@ DEPENDENCIES
   minitest-focus
   mocha
   packwerk!
-  rails
+  railties
   rake
   rubocop-performance
   rubocop-shopify
@@ -288,4 +198,4 @@ DEPENDENCIES
   zeitwerk
 
 BUNDLED WITH
-   2.3.5
+   2.4.8

data/README.md

@@ -1,10 +1,5 @@
 # Packwerk [![Build Status](https://github.com/Shopify/packwerk/workflows/CI/badge.svg)](https://github.com/Shopify/packwerk/actions?query=workflow%3ACI)
 
-### ⚠️ 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.
 
@@ -15,14 +10,13 @@ Packwerk is a Ruby gem used to enforce boundaries and modularize Rails applicati
 Packwerk can be used to:
 * Combine groups of files into packages
 * Define package-level constant visibility (i.e. have publicly accessible constants)
-* Enforce privacy (inbound) and dependency (outbound) boundaries between packages
 * Help existing codebases to become more modular without obstructing development
 
 ## Prerequisites
 
 Packwerk needs [Zeitwerk](https://github.com/fxn/zeitwerk) enabled, which comes with Rails 6.
 
-Packwerk supports MRI versions 2.6 and above.
+Packwerk supports MRI versions 2.7 and above.
 
 ## Demo
 
@@ -67,6 +61,7 @@ Various third parties have built tooling on top of packwerk. Here's a selection
 - 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/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.
 
 ## Development
 

data/RESOLVING_VIOLATIONS.md

@@ -3,7 +3,7 @@
 Violations can be [recorded as a deprecation](#recording-violations) or (better!) [eliminated](#eliminating-violations).
 
 ## Recording Violations
-💡 New privacy and dependency violations are never hard-blocked. There are many very valid reasons to run `bin/packwerk update-todo`, adding new violations to `package_todo.yml` files. Even if you feel your reason might not be "valid," if your judgement says adding the violation and shipping your change will produce positive impact, trust your gut.
+💡 New dependency violations are never hard-blocked. There are many very valid reasons to run `bin/packwerk update-todo`, adding new violations to `package_todo.yml` files. Even if you feel your reason might not be "valid," if your judgement says adding the violation and shipping your change will produce positive impact, trust your gut.
 
 ### Emergency Fixes
 ❔ Is it a revert or is there a lot of urgency because you are fixing a production bug impacting customers?
@@ -31,7 +31,7 @@ Violations can be [recorded as a deprecation](#recording-violations) or (better!
 ➡️ Stay strong. Eliminate the violation. It is important to build a sustainable business that optimizes for the long-term. Look for advocates such as from mentors or within your team who can help you justify improving system design.
 
 ## Eliminating Violations
-💡 Dependency and privacy violations are Packwerk's signal that what we've stated about the desired system design (what
+💡 Dependency violations are Packwerk's signal that what we've stated about the desired system design (what
 packages exist and what lives in them, the dependencies in a package.yml, and the public interface in the package's public folder) doesn't match the reality of our system.
 If what we've stated about our system design doesn't feel right, then the violations won't make sense either! Make sure to think through system design before addressing a violation.
 
@@ -40,12 +40,7 @@ If what we've stated about our system design doesn't feel right, then the violat
 
 If not, find a better place for it to live.
 
-Otherwise, follow the guide for eliminating [Privacy Violations](#privacy-violations) or [Dependency Violations](#dependency-violations).
-
-### Privacy Violations
-💡  Packwerk thinks something is a privacy violation if you're referencing a constant, class, or module defined in the private implementation (i.e. not the public folder) of another package. We care about these because we want to make sure we only use parts of a package that have been exposed as public API.
-
-An explicit and implementation-hiding public API is a cornerstone of well-modularized code.
+Otherwise, follow the guide for eliminating [Dependency Violations](#dependency-violations).
 
 #### Use Existing Public Interface
 ❔ Does the package you're using expose public API in its public folder that supports your use case?

data/TROUBLESHOOT.md

@@ -2,8 +2,6 @@
 
 * [Troubleshooting violations](#Troubleshooting-violations)
   * [Feedback loop](#Feedback-loop)
-  * [Package Privacy violation](#Package-Privacy-violation)
-    * [Interpreting Privacy violation](#Interpreting-Privacy-violation)
   * [Package Dependency violation](#Package-Dependency-violation)
     * [Interpreting Dependency violation](#Interpreting-Dependency-violation)
 
@@ -16,32 +14,11 @@ You can specify folders or packages in Packwerk commands for a shorter run time:
 
      bin/packwerk check components/your_package
 
-     bin/packwerk update-todo components/your_package
-
-_Note: You cannot specify folders or packages for `bin/packwerk validate` because the command runs for the entire application._
+_Note: You cannot specify folders or packages for `bin/packwerk validate` and `bin/packwerk update-todo` because the 
+command runs for the entire application._
 
 ![](static/packwerk_check_violation.gif)
 
-### Package Privacy violation
-A constant that is private to its package has been referenced from outside of the package. Constants are declared private in their package’s `package.yml`.
-
-See: [USAGE.md - Enforcing privacy boundary](USAGE.md#Enforcing-privacy-boundary)
-
-#### Interpreting Privacy violation
-
-> /Users/JaneDoe/src/github.com/sample-project/user/app/controllers/labels_controller.rb:170:30
-> Privacy violation: '::Billing::CarrierInvoiceTransaction' is private to 'billing' but referenced from 'user'.
-> Is there a public entrypoint in 'billing/app/public/' that you can use instead?
->
-> Inference details: 'Billing::CarrierInvoiceTransaction' refers to ::Billing::CarrierInvoiceTransaction which seems to be defined in billing/app/models/billing/carrier_invoice_transaction.rb.
-
-There has been a privacy violation of the package `billing` in the package `user`, through the use of the constant `Billing::CarrierInvoiceTransaction` in the file `user/app/controllers/labels_controller.rb`.
-
-##### Suggestions
-You may be accessing the implementation of a piece of functionality that is supposed to be accessed through a public interface on the package. Try to use the public interface instead. A package’s public interface should be defined in its `app/public` folder and documented.
-
-The functionality you’re looking for may not be intended to be reused across packages at all. If there is no public interface for it but you have a good reason to use it from outside of its package, find the people responsible for the package and discuss a solution with them.
-
 ### Package Dependency violation
 A constant defined in a package A is referenced from a package B that doesn’t define a dependency on A. Packages define their dependencies in their `package.yml`.
 

data/UPGRADING.md

@@ -1,3 +1,15 @@
+# Upgrading from 2.x to 3.0
+
+In Packwerk 3.0, we've made two notable changes:
+
+## Renaming deprecated_references to package_todo
+
+The `update-deprecations` subcommand has been renamed to `update-todo`. Old `deprecated_references.yml` files will be automatically deleted and replaced with `package_todo.yml` files when you run `update-todo`. This behaviour has been in Packwerk [since 2.3.0](https://github.com/Shopify/packwerk/releases/tag/v2.3.0), and automatic deletion will be removed in the next release.
+
+### Removal of privacy checking
+
+Privacy checking via `enforce_privacy` has been removed. Developers are encouraged to focus on leveraging Packwerk for dependency checking. For those who still need privacy checks, please use [Gusto's extension gem](https://github.com/rubyatscale/packwerk-extensions).
+
 # 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.

data/USAGE.md

@@ -13,14 +13,15 @@
 * [Defining packages](#defining-packages)
   * [Package metadata](#package-metadata)
 * [Types of boundary checks](#types-of-boundary-checks)
-  * [Enforcing privacy boundary](#enforcing-privacy-boundary)
-    * [Using public folders](#using-public-folders)
   * [Enforcing dependency boundary](#enforcing-dependency-boundary)
+* [Using strict mode](#using-strict-mode)
 * [Checking for violations](#checking-for-violations)
 * [Resolving new violations](#resolving-new-violations)
   * [Understanding how to respond to new violations](#understanding-how-to-respond-to-new-violations)
 * [Recording existing violations](#recording-existing-violations)
   * [Understanding the package todo file](#understanding-the-package-todo-file)
+  * [Understanding the list of deprecated references](#understanding-the-list-of-deprecated-references)
+* [Loading extensions](#loading-extensions)
 
 ## What problem does Packwerk solve?
 
@@ -143,50 +144,10 @@ Example:
 
 ## Types of boundary checks
 
-Packwerk can perform two types of boundary checks: privacy and dependency.
-
-#### Enforcing privacy boundary
-
-A package's privacy boundary is violated when there is a reference to the package's private constants from a source outside the package.
-
-There are two ways you can enforce privacy for your package:
-
-1. Enforce privacy for all external sources
-
-```yaml
-# components/merchandising/package.yml
-enforce_privacy: true  # will make everything private that is not in
-                        # the components/merchandising/app/public folder
-```
-
-Setting `enforce_privacy` to true will make all references to private constants in your package a violation.
-
-2. Enforce privacy for specific constants
-
-```yaml
-# components/merchandising/package.yml
-enforce_privacy:
-  - "::Merchandising::Product"
-  - "::SomeNamespace"  # enforces privacy for the namespace and
-                       # everything nested in it
-```
-
-It will be a privacy violation when a file outside of the `components/merchandising` package tries to reference `Merchandising::Product`.
-
-##### Using public folders
-You may enforce privacy either way mentioned above and still expose a public API for your package by placing constants in the public folder, which by default is `app/public`. The constants in the public folder will be made available for use by the rest of the application.
-
-##### Defining your own public folder
-
-You may prefer to override the default public folder, you can do so on a per-package basis by defining a `public_path`.
-
-Example:
-
-```yaml
-public_path: my/custom/path/
-```
+Packwerk ships with dependency boundary checking only. Other checking support may be added by extension gems.
 
 #### Enforcing dependency boundary
+
 A package's dependency boundary is violated whenever it references a constant in some package that has not been declared as a dependency.
 
 Specify `enforce_dependencies: true` to start enforcing the dependencies of a package. The intentional dependencies of the package are specified as a list under a `dependencies:` key.
@@ -202,6 +163,15 @@ dependencies:
 
 It will be a dependency violation when `components/shop_identity` tries to reference a constant that is not within `components/platform` or itself.
 
+#### Using strict mode
+
+Once there are no more violations in a package, you can turn on `strict` mode, which will prevent new violations from being added to the package's `package_todo.yml`. To use this, simply change `enforce_dependencies: true` to `enforce_dependencies: strict` in your `package.yml`.
+
+Then, when you run `bin/packwerk check`, new violations will cause the following error to be displayed:
+```
+packs/referencing_package cannot have dependency violations on packs/defining_package because strict mode is enabled for dependency violations in packs/referencing_package/package.yml
+```
+
 ## Checking for violations
 
 After enforcing the boundary checks for a package, you may execute:
@@ -225,9 +195,10 @@ In order to keep the package system valid at each version of the application, we
 See: [TROUBLESHOOT.md - Sample violations](TROUBLESHOOT.md#Sample-violations)
 
 ## Resolving new violations
+
 ### Understanding how to respond to new violations
 
-When you have a new dependency or privacy violation, what do you do?
+When you have a new dependency violation, what do you do?
 
 See: [RESOLVING_VIOLATIONS.md](RESOLVING_VIOLATIONS.md)
 
@@ -239,19 +210,12 @@ If so, you will want to stop the bleeding and prevent more violations from occur
 
     bin/packwerk update-todo
 
-Similar to `bin/packwerk check`, you may also run `bin/packwerk update-todo` on folders or packages:
-
-    bin/packwerk update-todo 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._
-
 `bin/packwerk update-todo` should only be run to record existing violations and to remove violations that have been worked off. Running `bin/packwerk update-todo` to resolve a violation should be the very last resort.
 
 See: [TROUBLESHOOT.md - Troubleshooting violations](TROUBLESHOOT.md#Troubleshooting_violations)
 
-
 ### Understanding the package todo file
 
 The package TODO list is called `package_todo.yml` and can be found in the package folder. The list outlines the constant violations of the package, where the violation is located, and the file defining the violation.
@@ -271,7 +235,125 @@ Above is an example of a constant violation entry in `package_todo.yml`.
 
 * `components/merchant` - package where the constant violation is found
 * `::Checkouts::Core::CheckoutId` - violated constant in question
-* `dependency` - type of violation, either dependency or privacy
+* `dependency` - type of violation, typically dependency
 * `components/merchant/app/public/merchant/generate_order.rb` - path to the file containing the violated constant
 
-Violations exist within the package that makes a violating reference. This means privacy violations of your package can be found listed in `package_todo.yml` files in the packages with the reference to a private constant.
+Violations exist within the package that makes a violating reference.
+
+# Loading Extensions
+
+You can optionally specify ruby files that you'd like to be loaded with `packwerk` by specifying a `require` directive in `packwerk.yml`:
+```yml
+require:
+  - ./path/to/file.rb
+  - my_gem
+```
+
+`packwerk` will directly call `require` with these paths.
+You can prefix local files with a dot to define them relative to `packwerk.yml`, or you can use absolute paths.
+You can also reference the name of a gem.
+
+## Examples
+
+### Custom Offense Formatter
+
+While `packwerk` ships with its own offense formatter, you may specify a custom one in your configuration file via the `offenses_formatter:` key.  Your custom formatter will be used when `bin/packwerk check` is run.
+
+Firstly, you'll need to create an `OffensesFormatter` class that includes `Packwerk::OffensesFormatter`. You can use [`Packwerk::Formatters::OffensesFormatter`](lib/packwerk/formatters/offenses_formatter.rb) as a point of reference for this. Then, in the `require` directive described above, you'll want to tell `packwerk` about it:
+```ruby
+# ./path/to/file.rb
+class MyOffensesFormatter
+  include Packwerk::OffensesFormatter
+  # implement the `OffensesFormatter` interface
+
+  def identifier
+    'my_offenses_formatter'
+  end
+end
+```
+
+Then in `packwerk.yml`, you can set the `formatter` to the identifier for your class:
+```yml
+offenses_formatter: my_offenses_formatter
+```
+
+You can also pass in a formatter on the command line:
+```
+bin/packwerk check --offenses-formatter=my_offenses_formatter
+```
+
+### Custom Checkers
+
+Packwerk ships with a way to analyze dependencies and also supports custom checkers from extension gems.
+
+Custom checkers will allow references to constants to be analyzed in new ways, and for those invalid references to show up as violations in `package_todo.yml`.
+
+To create a custom checker, you'll first need to create a checker class that includes `Packwerk::Checker`. You can use [`Packwerk::ReferenceChecking::Checkers::DependencyChecker`](lib/packwerk/reference_checking/checkers/dependency_checker.rb) as a point of reference for this. Here is an example:
+
+```ruby
+# ./path/to/file.rb
+class MyChecker
+  include Packwerk::Checker
+  # implement the `Checker` interface
+
+  sig { override.returns(String) }
+  def violation_type
+    'my_custom_violation_type'
+  end
+
+  sig { override.params(listed_offense: ReferenceOffense).returns(T::Boolean) }
+  def strict_mode_violation?(listed_offense)
+    # This will allow "strict mode" to be supported in your checker
+    referencing_package = listed_offense.reference.package
+    referencing_package.config["enforce_custom"] == "strict"
+  end
+
+  sig { override.params(reference: Reference).returns(T::Boolean) }
+  def invalid_reference?(reference)
+    # your logic here
+  end
+
+  sig { override.params(reference: Reference).returns(String) }
+  def message(reference)
+    # your message here
+  end
+end
+```
+
+Then, in the `require` directive described above, you'll want to tell `packwerk` about it:
+
+```yml
+require:
+  - ./path/to/file.rb
+```
+
+### Custom Validators
+
+Similar to checkers, you can define your own validator to be executed when `bin/packwerk validate` is invoked. This can be used to support your custom checker (by specifying permitted keys) or to provide any other validations you want to impose on packages.
+
+To create a custom validator, you'll first need to create a validator class that includes `Packwerk::Validator`. You can use [`Packwerk::Validators::DependencyValidator`](lib/packwerk/validators/dependency_validator.rb) as a point of reference for this. Here is an example:
+
+```ruby
+# ./path/to/file.rb
+class MyValidator
+  include Packwerk::Validator
+  # implement the `Validator` interface
+
+  sig { override.returns(T::Array[String]) }
+  def permitted_keys
+    ['enforce_my_custom_checker']
+  end
+
+  sig { override.params(package_set: PackageSet, configuration: Configuration).returns(ApplicationValidator::Result) }
+  def call(package_set, configuration)
+    # your logic here
+  end
+end
+```
+
+Then, in the `require` directive described above, you'll want to tell `packwerk` about it:
+
+```yml
+require:
+  - ./path/to/file.rb
+```

data/dev.yml

@@ -3,7 +3,7 @@ name: packwerk
 type: ruby
 
 up:
-  - ruby: 3.0.0
+  - ruby: 3.2.1
   - bundler
 
 commands:

data/exe/packwerk

@@ -1,6 +1,10 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+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/gemfiles/Gemfile-rails-6-1

@@ -7,7 +7,7 @@ gemspec path: ".."
 # Specify the same dependency sources as the application Gemfile
 
 gem("spring")
-gem("rails", "~> 6.1.0")
+gem("rails", "~> 6.1")
 gem("constant_resolver", require: false)
 gem("sorbet-runtime", require: false)
 gem("rubocop-performance", require: false)