packwerk-extensions is a home for checker extensions for packwerk 3.
Currently, it ships the following checkers to help improve the boundaries between packages. These checkers are:
privacychecker that ensures other packages are using your package's public API
visibilitychecker that allows packages to be private except to an explicit group of other packages.
- An experimental
architecturechecker that allows packages to specify their "layer" and requires that each layer only communicate with layers below it.
packwerk-extensions to your
To register all checkers included in this gem, add the following to your
require: - packwerk-extensions
Alternatively, you can require individual checkers:
require: - packwerk/privacy/checker - packwerk/visibility/checker - packwerk/architecture/checker
The privacy checker extension was originally extracted from packwerk.
A package's privacy boundary is violated when there is a reference to the package's private constants from a source outside the package.
To enforce privacy for your package, set
true on your pack:
# components/merchandising/package.yml enforce_privacy: true
enforce_privacy to true will make all references to private constants in your package a violation.
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
Using specific private constants
Sometimes it is desirable to only enforce privacy on a subset of constants in a package. You can do so by defining a
private_constants list in your package.yml. Note that
enforce_privacy must be set to
'strict' for this to work.
Package Privacy violation
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.
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
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.
The visibility checker can be used to allow a package to be private implementation detail of other packages.
To enforce visibility for your package, set
true on your pack and specify
visible_to for other packages that can use your package.
# components/merchandising/package.yml enforce_visibility: true visible_to: - components/other_package
The architecture checker can be used to enforce constraints on what can depend on what.
To enforce architecture for your package, first define the
packwerk.yml, for example:
architecture_layers: - package - utility
Then, turn on the checker in your package:
# components/merchandising/package.yml enforce_architecture: true layer: utility
Now this pack can only depend on other utility packages.