packwerk 2.3.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94a6e793dd2c071a7bfb9a739fb6aaf2e07b0d2183bf743afb38da5e3847f0e2
-  data.tar.gz: dd779094dad5572746476d25d63e26f29819cf0b57519f73a4f693610cfd238e
+  metadata.gz: 11206a06e6ac99c1fb8ef4cdefbe334133317d0599fce6480d4dfe10f694c747
+  data.tar.gz: 606778530b8a872d331e5f331b9c6e14cb37ff6e0a5e13247bb0aebe1ca9e0cc
 SHA512:
-  metadata.gz: 9ff4d2a2aa7b6cb34e59362321ea3fb22826d10430addeef1b6143408d1a1b510ff8915105f2e74e9173334dfcfbd0a76610ea00242a2720c6feb9c75b53556f
-  data.tar.gz: 7ed4cbe3376821d54a5a58e2bc25ac3baf1f03a84928e027c0e1e1f39d52a14df4e18cc8d9ecfa50de3756507f46c0e9687d04464d3ec149037a7fdecb8eed0e
+  metadata.gz: 66166a9c683483fda99341adc79c807c40f8190c349c8650b8646810e06d11f9b4728e2e938ef0abf640967d0764d78b66e956aba3bdaef830c4a15253711542
+  data.tar.gz: c1cce5df16246f1561cd0954abca4685e21adcaf52d3f6d164acd776f9466a0ad276a65b9a2f5cc9e358b058fcdc2cef265c2b3948043f9f3e35b1d4798ec5e9

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.0)
+      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.7

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/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)
 
@@ -22,26 +20,6 @@ _Note: You cannot specify folders or packages for `bin/packwerk validate` becaus
 
 ![](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/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. See [`packwerk-extensions`](https://github.com/rubyatscale/packwerk-extensions) to incorporate privacy checks into your use of `packwerk`.
 
 #### 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,6 +195,7 @@ 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?
@@ -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.
@@ -275,3 +239,129 @@ Above is an example of a constant violation entry in `package_todo.yml`.
 * `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.
+
+# 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, such as the privacy checker listed below.
+
+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
+```
+
+#### Privacy Checker
+
+[`packwerk-extensions`](https://github.com/rubyatscale/packwerk-extensions) (originally extracted from `packwerk`) can be used to help define and enforce public API boundaries of a package. See the README.md for more details. To use this, add it to your `Gemfile` and then require it via `packwerk.yml`:
+```yml
+require:
+  - packwerk-extensions
+```
+
+### 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,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+require "packwerk/disable_sorbet"
 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)