query_packwerk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 69878aa37cf34d0896f727625f444787cf166db630cf8334109eccbd61cc40a9
+  data.tar.gz: ba722634ea12a50ea7473bb976567af174a40e14c5ba9aa0b12d782c8e92b49e
+SHA512:
+  metadata.gz: ad07eb416e3993dbbe823dd2305afbb86fc52c0e0ec652482a58f0058f60330bc5a16ecb969f9356bcc13eb52a669e58ea094eaf4c9486097fbc7862fd8b671b
+  data.tar.gz: 42115b541cc33e22658978aec000c83ce3d8db9385bcd7671e111c0629537be3dda33bcce9909a5b88d9e9c21a15ecce4af74d948aa2ea96d64583cefbd5c7b2

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,90 @@
+plugins:
+  - rubocop-sorbet
+  - rubocop-performance
+
+AllCops:
+  TargetRubyVersion: 3.1
+  SuggestExtensions: false
+  NewCops: enable
+  Exclude:
+    - bin/**/*
+    - vendor/**/*
+
+Sorbet/StrictSigil:
+  Enabled: false
+
+Layout/ExtraSpacing:
+  Enabled: true
+  Exclude:
+    - danger-packwerk.gemspec
+
+Layout/SpaceAroundOperators:
+  Enabled: true
+  Exclude:
+    - danger-packwerk.gemspec
+
+Sorbet/ValidSigil:
+  Enabled: true
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/SignalException:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Sorbet/FalseSigil:
+  Enabled: false
+
+Lint/UnusedMethodArgument:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Style/SuperArguments:
+  Enabled: false
+
+Style/ArgumentsForwarding:
+  Enabled: false
+
+Style/BlockForwarding:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1 @@
+See https://github.com/rubyatscale/query_packwerk/releases

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,131 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at rubyatscale@gusto.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Gusto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,108 @@
+# 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
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add query_packwerk
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install query_packwerk
+```
+
+## Usage
+
+### Console Interface
+
+The easiest way to use QueryPackwerk is through its interactive console:
+
+```bash
+query_packwerk console
+```
+
+This will load the Packwerk context from your current directory and provide you with an interactive Ruby console with QueryPackwerk methods available.
+
+Available commands in the console:
+
+```ruby
+# Get all violations for a pack
+violations_for("pack_name")
+
+# Get where violations occurred
+violation_sources_for("pack_name")
+
+# Get how often violations occurred
+violation_counts_for("pack_name")
+
+# Get the 'shape' of violations
+anonymous_violation_sources_for("pack_name")
+
+# Get how often each shape occurs
+anonymous_violation_counts_for("pack_name")
+
+# Get who consumes this pack
+consumers("pack_name")
+
+# Get all packages
+Packages.all
+
+# Get all violations
+Violations.all
+
+# Reset the cache
+reload!
+```
+
+### Ruby API
+
+You can also use QueryPackwerk programmatically in your Ruby code:
+
+```ruby
+require 'query_packwerk'
+
+# Get all violations for a pack
+violations = QueryPackwerk.violations_for("my_pack")
+
+# Get which files are consuming your pack and how many violations each has
+consumers = QueryPackwerk.consumers("my_pack")
+
+# Get a count of all violation types
+counts = QueryPackwerk.violation_counts_for("my_pack")
+```
+
+## Examples
+
+Analyze which parts of your codebase are most dependent on a package:
+
+```ruby
+# Find the top 5 consumers of your package
+QueryPackwerk.consumers("my_pack").sort_by { |_, count| -count }.first(5)
+```
+
+Find the most common violation patterns:
+
+```ruby
+# Get anonymized violation patterns with a threshold of at least 3 occurrences
+QueryPackwerk.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, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/martinemde/query_packwerk.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/exe/query_packwerk

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'query_packwerk'
+require 'query_packwerk/cli'
+
+QueryPackwerk::CLI.start

data/lib/query_packwerk/cli.rb

@@ -0,0 +1,19 @@
+# typed: strict
+
+require 'thor'
+
+module QueryPackwerk
+  # CLI for loading the QueryPackwerk console
+  class CLI < Thor
+    extend T::Sig
+
+    default_command :console
+
+    desc 'console',
+         'Query packwerk in the current directory via console'
+    sig { params(directory: String).void }
+    def console(directory = Dir.pwd)
+      QueryPackwerk::Console.start(directory)
+    end
+  end
+end

data/lib/query_packwerk/console.rb

@@ -0,0 +1,65 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'irb'
+require 'irb/completion'
+
+module QueryPackwerk
+  # Console for QueryPackwerk
+  class Console
+    extend T::Sig
+
+    sig { params(directory: String).void }
+    def self.start(directory = Dir.pwd)
+      puts "Loading packwerk context in #{directory}..."
+
+      Dir.chdir(directory) do
+        # Start IRB with current context
+        # https://github.com/cucumber/aruba/blob/main/lib/aruba/console.rb
+        ARGV.clear
+
+        require 'irb'
+        IRB.setup nil
+
+        IRB.conf[:IRB_NAME] = 'query_packwerk'
+
+        IRB.conf[:PROMPT] = {}
+        IRB.conf[:PROMPT][:QUERY_PACKWERK] = {
+          PROMPT_I: '%N:%03n:%i> ',
+          PROMPT_S: '%N:%03n:%i%l ',
+          PROMPT_C: '%N:%03n:%i* ',
+          RETURN: "# => %s\n"
+        }
+        IRB.conf[:PROMPT_MODE] = :QUERY_PACKWERK
+
+        IRB.conf[:RC] = false
+
+        require 'irb/completion'
+        IRB.conf[:READLINE] = true
+        IRB.conf[:SAVE_HISTORY] = 1000
+        IRB.conf[:HISTORY_FILE] = "#{directory}/.query_packwerk_history"
+
+        context = Class.new do
+          include QueryPackwerk
+          include QueryPackwerk::ConsoleHelpers
+          extend T::Sig
+        end
+
+        context_instance = context.new
+        irb = IRB::Irb.new(IRB::WorkSpace.new(context_instance))
+        IRB.conf[:MAIN_CONTEXT] = irb.context
+
+        context_instance.welcome
+
+        trap('SIGINT') do
+          irb.signal_handle
+        end
+
+        catch(:IRB_EXIT) do
+          irb.eval_input
+        end
+        Kernel.exit
+      end
+    end
+  end
+end

data/lib/query_packwerk/console_helpers.rb

@@ -0,0 +1,144 @@
+# typed: true
+
+module QueryPackwerk::ConsoleHelpers
+  extend T::Sig
+
+  sig { returns(String) }
+  def inspect
+    'query_packwerk console'
+  end
+
+  sig { returns(NilClass) } # returning nil is less ugly in the console.
+  def welcome
+    help_query_packwerk
+    puts
+    help_help
+  end
+
+  sig { params(type: T.nilable(T.any(String, Symbol))).returns(NilClass) }
+  def help(type = nil)
+    case type.to_s.downcase
+    when 'violation'
+      help_violation
+    when 'violations'
+      help_violations
+    when 'package'
+      help_package
+    when 'packages'
+      help_packages
+    when '', 'help'
+      help_help
+    else
+      puts "Unknown help topic: #{type}\n"
+      help_help
+    end
+  end
+
+  sig { returns(NilClass) }
+  def help_help
+    puts <<~HELP
+      Available help topics:
+        help            # This help
+        help_violation  # Help for QueryPackwerk::Violation
+        help_violations # Help for QueryPackwerk::Violations
+        help_package    # Help for QueryPackwerk::Package
+        help_packages   # Help for QueryPackwerk::Packages
+    HELP
+  end
+
+  sig { returns(NilClass) }
+  def help_violation
+    puts <<~HELP
+      QueryPackwerk::Violation (lib/query_packwerk/violation.rb)
+      ------------------------------------------------
+      .type                   # Returns the violation type ('privacy' or 'dependency')
+      .class_name             # Returns the violated constant name
+      .files                  # Returns array of files containing the violation
+      .producing_pack         # Returns the Package that owns the violated constant
+      .consuming_pack         # Returns the Package that violated the constant
+      .sources                # Returns array of AST nodes representing the violation occurrences
+      .sources_with_locations # Returns array of [file:line, source] pairs for each violation
+      .source_counts          # Returns hash of how often each violation source occurs
+      .anonymous_sources      # Returns array of violation sources with arguments anonymized
+      .anonymous_sources_with_locations # Returns array of [file:line, source] pairs for each violation with arguments anonymized
+      .count                  # Returns total number of violation occurrences
+    HELP
+  end
+
+  sig { returns(NilClass) }
+  def help_violations
+    puts <<~HELP
+      QueryPackwerk::Violations (lib/query_packwerk/violations.rb)
+      --------------------------------------------------
+      .where(conditions)      # Returns new Violations filtered by conditions
+      .raw_sources            # Returns hash of constant => AST nodes for all violations
+      .sources                # Returns hash of constant => source strings for all violations
+      .sources_with_locations # Returns hash of constant => [file:line, source] pairs
+      .source_counts          # Returns hash of constant => {source => count} with occurrence counts
+      .sources_with_contexts  # Returns hash of constant => [file:line, source] pairs for each violation with context
+      .anonymous_sources      # Returns hash of constant => anonymized sources
+      .anonymous_sources_with_locations # Returns array of [file:line, source] pairs for each violation with arguments anonymized
+      .consumers(threshold)   # Returns hash of consuming package names and violation counts
+      .producers(threshold)   # Returns hash of producing package names and violation counts
+      .including_files(globs) # Returns new Violations filtered to include specific files
+      .excluding_files(globs) # Returns new Violations filtered to exclude specific files
+    HELP
+  end
+
+  sig { returns(NilClass) }
+  def help_package
+    puts <<~HELP
+      QueryPackwerk::Package (lib/query_packwerk/package.rb)
+      ----------------------------------------------
+      .name                 # Returns the package name
+      .enforce_dependencies # Returns whether package enforces dependencies
+      .enforce_privacy      # Returns whether package enforces privacy
+      .metadata             # Returns the package metadata from package.yml
+      .config               # Returns the package configuration
+      .dependencies         # Returns Packages collection of dependencies
+      .dependency_names     # Returns array of dependency package names
+      .owner                # Returns the package owner or 'Unowned'
+      .directory            # Returns the package directory path
+      .todos                # Returns Violations where this package is the consumer
+      .violations           # Returns Violations where this package is the producer
+      .consumers            # Returns Packages that consume this package
+      .consumer_names       # Returns array of names of consuming packages
+      .consumer_counts      # Returns hash of consumer package names and counts
+    HELP
+  end
+
+  sig { returns(NilClass) }
+  def help_packages
+    puts <<~HELP
+      QueryPackwerk::Packages (lib/query_packwerk/packages.rb)
+      ------------------------------------------------
+      .all                  # Returns all packages in the application
+      .where(conditions)    # Returns new Packages filtered by conditions
+      .violations           # Returns Violations for all packages in collection
+    HELP
+  end
+
+  sig { returns(NilClass) }
+  def help_query_packwerk
+    puts <<~HELP
+      QueryPackwerk (lib/query_packwerk.rb)
+      ------------------------------
+      Available commands:
+        package(pack_name)                         # Get a package by name
+        Packages.all                               # Get all packages
+
+      Package Consumption (how others use this package):
+        violations_for(pack_name)                  # Get all violations where others access this package
+        violation_sources_for(pack_name)           # Get where others access this package
+        violation_counts_for(pack_name)            # Get how often others access this package
+        anonymous_violation_sources_for(pack_name) # Get the 'shape' of how others access this package
+        anonymous_violation_counts_for(pack_name)  # Get how often each access pattern occurs
+        consumers(pack_name)                       # Get which packages consume this package
+
+      Package Dependencies (how this package uses others):
+        todos_for(pack_name)                       # Get all todos where this package accesses others
+
+      Violations.all                               # Get all violations
+    HELP
+  end
+end