packs

A 100% Rust implementation of packwerk, a gradual modularization platform for Ruby.

Goals:

To be a drop-in replacement for packwerk on most projects

• Currently can serve as a drop-in replacement on Gusto's extra-large Rails monolith
• This is a work in progress! Please see Verification for instructions on how to verify the output of packs is the same as packwerk.

To be 20x faster than packwerk on most projects

• Currently ~10-20x as fast as the ruby implementation. See BENCHMARKS.md.
• Your mileage may vary!
• Other performance improvements are coming soon!

Support non-Rails, non-zeitwerk apps

• Currently supports non-Rails apps through an experimental implementation
• Uses the same public API as packwerk, but has different behavior.
• See EXPERIMENTAL_PARSER_USAGE.md for more info

Usage and Documentation

Once installed and added to your $PATH, just call packs to see the CLI help message and documentation. (Note: if you're using use_packs AND chruby, you'll need to instead call pks everywhere you'd normally call packs.)

Welcome! Please see https://github.com/alexevanczuk/packs for more information!

Usage: packs [OPTIONS] <COMMAND>

Commands:
  greet                          Just saying hi
  check                          Look for violations in the codebase
  update                         Update package_todo.yml files with the current violations
  validate                       Look for validation errors in the codebase
  delete-cache                   `rm -rf` on your cache directory, default `tmp/cache/packwerk`
  list-packs                     List packs based on configuration in packwerk.yml (for debugging purposes)
  list-included-files            List analyzed files based on configuration in packwerk.yml (for debugging purposes)
  list-definitions               List the constants that packs sees and where it sees them (for debugging purposes)
  list-unnecessary-dependencies  List dependencies that when removed produce no violations.
  help                           Print this message or the help of the given subcommand(s)

Options:
      --project-root <PROJECT_ROOT>  Path for the root of the project [default: .]
  -d, --debug                        Run with performance debug mode
  -e, --experimental-parser          Run with the experimental parser, which gets constant definitions directly from the AST
      --no-cache                     Run without the cache (good for CI, testing)
  -h, --help                         Print help
  -V, --version                      Print version

Installation

See INSTALLATION.md

Using with VSCode Extension

packwerk has a VSCode Extension: https://github.com/rubyatscale/packwerk-vscode/tree/main Using the extension with packs is straightforward and results in a much more responsive experience.

Directions:

• Follow INSTALLATION.md instructions to install packs
• Follow the configuration directions to configure the extension to use packs instead of the ruby gem by setting the executable to packs check

Verification

As packs is still a work-in-progress, it's possible it will not produce the same results as the ruby implementation (see Not Yet Supported). If so, please file an issue – I'd love to try to support your use case!

Instructions:

• Follow the directions above to install packs
• Run packs delete-cache
• Run packs update
• Confirm the output of git diff is empty
• Please file an issue if it's not!

New to Rust?

Me too! This is my first Rust project, so I'd love to have feedback, advice, and contributions!

Rust is a low-level language with high-level abstractions, a rich type system, with a focus on memory safety through innovative compile-time checks on memory usage.

If you're new to Rust, don't be intimidated! https://www.rust-lang.org has tons of great learning resources.

If you'd like to contribute but don't know where to start, please reach out! I'd love to help you get started.

Not yet supported

• custom inflections
• custom load paths
• zeitwerk default namespaces
• extensible plugin system
• stale violation detection
• strict mode on checkers

Benchmarks

See BENCHMARKS.md

Kudos

• Current and Ex-Shopifolks (@exterm, @wildmaples) for open-sourcing packwerk
• Gusties, and the Ruby/Rails Modularity Slack Server, for continued feedback and support
• @mzruya for the initial implementation and Rust inspiration