QueryPackwerk

QueryPackwerk is a Ruby gem for querying and analyzing Packwerk violations in Ruby applications. It provides a friendly API for exploring package.yml and package_todo.yml files, making it easier to manage module boundaries and dependencies in your codebase.

Installation

This gem provides a CLI interface that can be used independently from your application.

gem install query_packwerk

You can also make it available in a specific application by adding it to your Gemfile:

bundle add query_packwerk --group=development

Usage

Console Interface

The easiest way to use QueryPackwerk is through its interactive console. This will use the local directory Packwerk context and provide you with all QueryPackwerk methods.

query_packwerk console

The CLI includes a welcome message with a list of commands. You can access it any time with welcome:

query_packwerk:001:0> welcome

Find packages to work with:

# Get a packagequery_packwerk:001:0> package("pack_name")# Get all packagesquery_packwerk:001:0> Packages.all# Find a packagequery_packwerk:001:0> Packages.where(name: /service/)

Explore violations:

# Get all violations for a packquery_packwerk:001:0> violations_for("pack_name")# Get where violations occurredquery_packwerk:001:0> violation_sources_for("pack_name")# Get how often violations occurredquery_packwerk:001:0> violation_counts_for("pack_name")# Get the 'shape' of violationsquery_packwerk:001:0> anonymous_violation_sources_for("pack_name")# Get how often each shape occursquery_packwerk:001:0> anonymous_violation_counts_for("pack_name")# Get who consumes this packquery_packwerk:001:0> consumers("pack_name")# Get all violationsquery_packwerk:001:0> Violations.all

If you change any of the package.yml or package_todo.yml files, you can reload the running console:

# Reset the cachequery_packwerk:001:0> reload!

Ruby API

QueryPackwerk can also be used programmatically from Ruby:

require'query_packwerk'# Get all violations for a packviolations=QueryPackwerk.violations_for("my_pack")# Get which files are consuming your pack and how many violations each hasconsumers=QueryPackwerk.consumers("my_pack")# Get a count of all violation typescounts=QueryPackwerk.violation_counts_for("my_pack")

Examples

Analyze which parts of your codebase are most dependent on a package:

# Find the top 5 consumers of your packageQueryPackwerk.consumers("my_pack").sort_by{ |_,count| -count}.first(5)

Find the most common violation patterns:

# Get anonymized violation patterns with a threshold of at least 3 occurrencesQueryPackwerk.anonymous_violation_counts_for("my_pack",threshold: 3)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, push a PR with the label for the version you want, like 'major', 'minor' or 'patch'. When the PR is merged, the version will be automatically released to RubyGems.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/rubyatscale/query_packwerk.

License

The gem is available as open source under the terms of the MIT License.