query_packwerk 0.1.0

data/lib/query_packwerk/file_cache.rb

@@ -0,0 +1,160 @@
+# typed: strict
+# frozen_string_literal: true
+
+module QueryPackwerk
+  # Manages caching of file contents, AST nodes, and code analysis results.
+  # Provides efficient access to parsed Ruby code, constant references, and
+  # source abstractions for performance optimization during violation analysis.
+  # Supports both standard and anonymized views of source code patterns.
+  class FileCache
+    extend T::Sig
+
+    RUBY_FILE = T.let(/\.(rb|rake)\z/, Regexp)
+
+    sig { void }
+    def initialize
+      # { file_name => AST }
+      @file_ast_cache = T.let({}, T::Hash[String, RuboCop::AST::Node])
+      @file_cache = T.let({}, T::Hash[String, String])
+
+      # { [file_name, const_name] => [AST const nodes] }
+      @file_const_cache = T.let({}, T::Hash[T::Array[String], T::Array[RuboCop::AST::Node]])
+
+      # { [file_name, const_name] => [AST const nodes with full receiver chains] }
+      @full_source_cache = T.let({}, T::Hash[T::Array[String], T::Array[RuboCop::AST::Node]])
+
+      # { [file_name, const_name] => [anonymized sources] }
+      @anonymized_source_cache = T.let({}, T::Hash[T::Array[String], T::Array[String]])
+
+      @anonymized_args_cache = T.let({}, T::Hash[String, String])
+
+      @is_active_record_cache = T.let({}, T::Hash[String, String])
+      @is_constant_cache = T.let({}, T::Hash[String, String])
+    end
+
+    sig { params(file_names: String, headers: T::Boolean).void }
+    def load!(*file_names, headers: true)
+      file_count = file_names.size
+
+      warn "Prepopulating AST cache with #{file_count} files: " if headers
+
+      file_names.each do |f|
+        get_file_ast(f)
+        $stderr.print '.'
+      end
+
+      warn '', 'AST cache loaded' if headers
+    end
+
+    sig { params(cache_name: Symbol, key: T.untyped, value: T.untyped).returns(T.untyped) }
+    def set(cache_name, key:, value:)
+      case cache_name
+      when :is_active_record
+        return @is_active_record_cache[key] if @is_active_record_cache.key?(key)
+
+        @is_active_record_cache[key] = value
+      when :is_constant
+        return @is_constant_cache[key] if @is_constant_cache.key?(key)
+
+        @is_constant_cache[key] = value
+      end
+    end
+
+    sig { params(file_name: String).returns(RuboCop::AST::Node) }
+    def get_file_ast(file_name)
+      @file_ast_cache[file_name] ||= ast_from(get_file(file_name))
+    end
+
+    sig { params(file_name: String).returns(String) }
+    def get_file(file_name)
+      @file_cache[file_name] ||= if RUBY_FILE.match?(file_name) && File.exist?(file_name)
+                                   File.read(file_name)
+                                 else
+                                   'x'
+                                 end
+    end
+
+    # Get all occurrencs of the violation's constant in a file
+    sig { params(file_name: String, class_name: String).returns(T::Array[RuboCop::AST::Node]) }
+    def get_all_const_occurrences(file_name:, class_name:)
+      const_key = [file_name, class_name]
+
+      return T.must(@file_const_cache[const_key]) if @file_const_cache.key?(const_key)
+
+      absolute_const_node = ast_from(class_name)
+      relative_const_node = ast_from(class_name.delete_prefix('::'))
+
+      @file_const_cache[const_key] = get_file_ast(file_name).each_descendant.select do |node|
+        next false unless node.const_type?
+
+        node == absolute_const_node || node == relative_const_node
+      end
+    end
+
+    # Gets the full unanonymized source of how a constant is called
+    sig { params(file_name: String, class_name: String).returns(T::Array[RuboCop::AST::Node]) }
+    def get_full_sources(file_name:, class_name:)
+      const_key = [file_name, class_name]
+
+      return T.must(@full_source_cache[const_key]) if @full_source_cache.key?(const_key)
+
+      @full_source_cache[const_key] = get_all_const_occurrences(
+        file_name: file_name,
+        class_name: class_name
+      ).map do |node|
+        get_full_receiver_chain(node)
+      end
+    end
+
+    # Cleans up and anonymizes a source
+    sig { params(source: String).returns(String) }
+    def anonymize_arguments(source)
+      @anonymized_args_cache[source] ||= RuleRewriter
+                                         .rewrite(source)
+                                         .delete("\n").squeeze(' ').delete_prefix('::')
+    end
+
+    # Get the full receiver chains on a constant, and anonymize their arguments
+    sig { params(file_name: String, class_name: String).returns(T::Array[String]) }
+    def get_full_anonymous_sources(file_name:, class_name:)
+      const_key = [file_name, class_name]
+
+      return T.must(@anonymized_source_cache[const_key]) if @anonymized_source_cache.key?(const_key)
+
+      @anonymized_source_cache[const_key] = get_full_sources(
+        file_name: file_name,
+        class_name: class_name
+      ).map do |node|
+        get_full_receiver_chain(node)
+          .source
+          .then { |s| anonymize_arguments(s) }
+      end
+    end
+
+    private
+
+    # Turns a string into a Ruby AST
+    sig { params(string: String).returns(RuboCop::AST::Node) }
+    def ast_from(string)
+      RuboCop::ProcessedSource.new(string, RUBY_VERSION.to_f).ast
+    end
+
+    # We can find a constant, but by going up its parents we can find out the full call chain
+    # by checking if each parent is a receiver of the child, giving us method calls and
+    # arguments on a constant as well as where it occurred.
+    sig { params(node: RuboCop::AST::Node).returns(RuboCop::AST::Node) }
+    def get_full_receiver_chain(node)
+      return node unless node.const_type?
+
+      current_node = T.let(node, RuboCop::AST::Node)
+
+      while (parent_node = current_node.parent)
+        break unless parent_node.receiver == current_node
+
+        current_node = parent_node
+      end
+
+      current_node
+    end
+  end
+end

data/lib/query_packwerk/package.rb

@@ -0,0 +1,129 @@
+# typed: strict
+# frozen_string_literal: true
+
+module QueryPackwerk
+  # Represents a Packwerk package with enhanced querying capabilities.
+  # Wraps around ParsePackwerk::Package to provide additional methods
+  # for accessing package properties, dependencies, violations, and consumer information.
+  class Package
+    extend T::Sig
+
+    sig { returns(ParsePackwerk::Package) }
+    attr_reader :original_package
+
+    sig { params(original_package: ParsePackwerk::Package).void }
+    def initialize(original_package:)
+      @original_package = original_package
+    end
+
+    sig { returns(String) }
+    def name
+      @original_package.name
+    end
+
+    sig { returns(T::Boolean) }
+    def enforce_dependencies
+      !!@original_package.enforce_dependencies
+    end
+
+    sig { returns(T::Boolean) }
+    def enforce_privacy
+      !!@original_package.enforce_privacy
+    end
+
+    sig { returns(ParsePackwerk::MetadataYmlType) }
+    def metadata
+      @original_package.metadata
+    end
+
+    sig { returns(T::Hash[String, T.untyped]) }
+    def config
+      @original_package.config
+    end
+
+    sig { returns(QueryPackwerk::Packages) }
+    def dependencies
+      Packages.where(name: @original_package.dependencies)
+    end
+
+    sig { returns(T::Array[String]) }
+    def dependency_names
+      @original_package.dependencies
+    end
+
+    sig { returns(String) }
+    def owner
+      config['owner'] || Packages::UNOWNED
+    end
+
+    sig { returns(Pathname) }
+    def directory
+      Pathname.new(name).cleanpath
+    end
+
+    # Returns violations where this package is the consumer (i.e., this package
+    # has dependencies on other packages). These are the "todos" in the package_todo.yml
+    # file for this package.
+    sig { returns(QueryPackwerk::Violations) }
+    def todos
+      QueryPackwerk::Violations.where(consuming_pack: name)
+    end
+    alias outgoing_violations todos
+
+    # Returns violations where this package is the producer (i.e., other packages
+    # depend on this package). These are violations where other packages are
+    # accessing code from this package.
+    sig { returns(QueryPackwerk::Violations) }
+    def violations
+      QueryPackwerk::Violations.where(producing_pack: name)
+    end
+    alias incoming_violations violations
+
+    # Returns all packages that consume (depend on) this package
+    sig { returns(QueryPackwerk::Packages) }
+    def consumers
+      Packages.where(name: consumer_names)
+    end
+
+    # Returns the names of all packages that consume (depend on) this package
+    sig { returns(T::Array[String]) }
+    def consumer_names
+      violations.consumers.keys
+    end
+
+    # Returns a count of how often each consumer package accesses this package
+    sig { returns(T::Hash[String, Integer]) }
+    def consumer_counts
+      violations.consumers
+    end
+
+    sig { returns(String) }
+    def parent_name
+      directory.dirname.to_s
+    end
+
+    sig do
+      params(
+        keys: T.nilable(T::Array[Symbol])
+      ).returns(T::Hash[Symbol, T.untyped])
+    end
+    def deconstruct_keys(keys)
+      all_values = {
+        name: name,
+        owner: owner,
+        owned: owner != Packages::UNOWNED,
+        dependencies: dependency_names,
+
+        # Used for future implementations of NestedPacks
+        parent_name: parent_name
+      }
+
+      keys.nil? ? all_values : all_values.slice(*T.unsafe(keys))
+    end
+
+    sig { returns(String) }
+    def inspect
+      "#<#{self.class.name} #{name}>"
+    end
+  end
+end

data/lib/query_packwerk/packages.rb

@@ -0,0 +1,78 @@
+# typed: strict
+# frozen_string_literal: true
+
+module QueryPackwerk
+  # A collection class for managing and querying sets of Packwerk packages.
+  # Provides methods for retrieving, filtering, and analyzing packages within
+  # the application. Implements Enumerable and QueryInterface for flexible
+  # data manipulation and consistent query patterns.
+  class Packages
+    extend T::Sig
+    extend T::Generic
+
+    Elem = type_member { { fixed: QueryPackwerk::Package } }
+
+    UNOWNED = T.let('Unowned', String)
+
+    include Enumerable
+    include QueryInterface
+
+    sig { override.returns(T::Array[QueryPackwerk::Package]) }
+    attr_reader :original_collection
+
+    class << self
+      extend T::Sig
+
+      # Get all packages wrapped in our interfaces
+      sig { returns(QueryPackwerk::Packages) }
+      def all
+        @all ||= T.let(
+          begin
+            packages = ParsePackwerk.all.map { |p| QueryPackwerk::Package.new(original_package: p) }
+            QueryPackwerk::Packages.new(packages)
+          end,
+          T.nilable(QueryPackwerk::Packages)
+        )
+      end
+
+      sig do
+        params(
+          query_params: T.untyped, # Array, or anything responding to `===`, which can't be typed
+          query_fn: T.nilable(T.proc.params(arg0: T.untyped).returns(T::Boolean))
+        ).returns(QueryPackwerk::Packages)
+      end
+      def where(**query_params, &query_fn)
+        QueryPackwerk::Packages.new(super)
+      end
+
+      sig { void }
+      def reload!
+        @all = nil
+      end
+    end
+
+    sig { params(original_collection: T::Array[QueryPackwerk::Package]).void }
+    def initialize(original_collection)
+      @original_collection = original_collection
+    end
+
+    # You can query for packages rather than violations to get a broader view, and
+    # the violations returned from this will be related to all packs in this class rather than just
+    # one.
+    sig { returns(QueryPackwerk::Violations) }
+    def violations
+      QueryPackwerk::Violations.new(
+        @original_collection.flat_map { |pack| pack.violations.original_collection }
+      )
+    end
+
+    sig { returns(String) }
+    def inspect
+      [
+        "#<#{self.class.name} [",
+        to_a.map(&:inspect).join("\n"),
+        ']>'
+      ].join("\n")
+    end
+  end
+end

data/lib/query_packwerk/query_interface.rb

@@ -0,0 +1,268 @@
+# typed: strict
+# frozen_string_literal: true
+
+module QueryPackwerk
+  # A mixin module providing a flexible query interface for collections.
+  # Implements methods for filtering, comparing, and manipulating collection data
+  # with a consistent API pattern. Extends included classes with class methods
+  # for advanced querying capabilities and integrates with Enumerable for
+  # additional collection functionality.
+  module QueryInterface
+    include Kernel
+
+    extend T::Sig
+    extend T::Generic
+
+    Elem = type_member
+
+    include Enumerable
+
+    # Iterate over every member of the underlying original collection,
+    # also tie-in for Enumerable methods.
+    #
+    # Returns `T.untyped` because Sorbet complains on more accurate returns
+    # or void.
+    sig do
+      override.params(
+        block: T.nilable(T.proc.params(arg0: Elem).returns(T.untyped))
+      ).returns(
+        T.any(T::Enumerator[Elem], T::Array[Elem])
+      )
+    end
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      original_collection.each(&block)
+    end
+
+    # Should be overridden, the base of most of the queries.
+    #
+    # TODO: Consider refactoring to `abstract` interface
+    sig { overridable.returns(T::Array[T.untyped]) }
+    def original_collection
+      []
+    end
+
+    # `Enumerable` does not expose these methods.
+    sig { returns(Integer) }
+    def size
+      original_collection.size
+    end
+
+    alias length size
+    alias count size
+
+    # Extend the class with class extensions whenever this module is
+    # included so we get both singleton and instance methods we need for
+    # querying.
+    sig { params(klass: T::Class[T.anything]).void }
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      include Kernel
+      extend T::Sig
+
+      # *Notes on Sorbet:*
+      #
+      # Allows you to query against the underlying collection. As Sorbet does not
+      # allow for interface typing (i.e. `responds_to?`) we're using `T.untyped` instead.
+      #
+      # Since the implementing class will wrap the return value we also return `T.untyped` as
+      # Sorbet will imply this should be a `T::Array[inheriting_class]` rather than `InheritingClass`.
+      #
+      # *Notes on Interface:*
+      #
+      # This is based on a pattern-matching like interface using `===` and a few other assumptions
+      # about the underlying data structure. For singular values that means you can do this:
+      #
+      #     InheritingClass.where(name: /part_of_name/)
+      #
+      # ...as `===` works as a pattern inclusion for classes like `Regexp`, `Range`, class types, and
+      # more.
+      #
+      # There are a few unique cases presumed here as well when dealing with more complex queries:
+      #
+      # * If both the underlying value and query value are arrays we check for intersection
+      # * If the query value is an array we check if the underlying value "matches" and item in it
+      # * If the underlying value is an array we check if the query value matches any part of it
+      # * Otherwise we use `===` as a query
+      #
+      # These interfaces are meant to mimic ActiveRecord, but do take some liberties as we're working
+      # with Ruby objects rather than underlying database structures.
+      sig do
+        params(
+          query_params: T.untyped, # Array, or anything responding to `===`, which can't be typed
+          _query_fn: T.nilable(T.proc.params(arg0: T.untyped).returns(T::Boolean))
+        ).returns(T.untyped)
+      end
+      def where(**query_params, &_query_fn)
+        query_keys = query_params.keys
+        all_values = all
+
+        accepted_keys = all_values.first.deconstruct_keys(nil).keys
+        invalid_keys = query_keys - accepted_keys
+
+        raise ArgumentError, "The following keys are invalid for querying: #{invalid_keys.join(', ')}" if invalid_keys.any?
+
+        all_values.select do |value|
+          next yield(value) if block_given?
+
+          object_params = value.deconstruct_keys(query_keys)
+
+          query_params.all? do |param, query_matcher|
+            object_value = object_params[param]
+
+            case [query_matcher, object_value]
+            in [Array, Array]
+              intersects?(query_matcher, object_value)
+            in [Array, _]
+              any_compare?(query_matcher, object_value)
+            in [_, Array]
+              includes?(query_matcher, object_value)
+            else
+              case_equal?(query_matcher, object_value)
+            end
+          end
+        end
+      end
+      # Similar to the above `original_collection` we want to override this by defining
+      # where the InheritingClass can find all of its raw data.
+      #
+      # Sorbet does not recognize `included(klass)`/`klass.extend(ClassMethods)` when
+      # looking for `override` hooks. May be a bug in Sorbet.
+      sig do
+        returns(T.untyped)
+      end
+      def all
+        []
+      end
+
+      private
+
+      # Query Array to value Array is intersection, rather than strict equality or a literal pattern
+      # match. While we could do a `===` approximation of intersection that would make
+      # the code much more complicated.
+      sig { params(query_matcher: T::Array[T.untyped], object_value: T::Array[T.untyped]).returns(T::Boolean) }
+      def intersects?(query_matcher, object_value)
+        query_matcher.intersect?(object_value)
+      end
+
+      # Query Array to Any object value checks if any of the query matchers match that value
+      sig { params(query_matcher: T::Array[T.untyped], object_value: T.untyped).returns(T::Boolean) }
+      def any_compare?(query_matcher, object_value)
+        query_matcher.any? { |matcher| matcher === object_value } # rubocop:disable Style/CaseEquality
+      end
+
+      # Any other type of Query to Array is find if any value matches the condition
+      sig { params(query_matcher: T.untyped, object_value: T::Array[T.untyped]).returns(T::Boolean) }
+      def includes?(query_matcher, object_value)
+        object_value.any? { |v| query_matcher === v } # rubocop:disable Style/CaseEquality, Performance/RedundantEqualityComparisonBlock
+      end
+
+      # Otherwise we use `===` to decide if it's a match, and we use it explicitly as
+      # it's a very powerful query-like DSL and is in the language for a reason.
+      #
+      # We would use `===` for all cases, except that `Array` does not define it, nor
+      # should it as it could be defined in multiple different ways much the same as
+      # `String#each` could mean several things.
+      sig { params(query_matcher: T.untyped, object_value: T.untyped).returns(T::Boolean) }
+      def case_equal?(query_matcher, object_value)
+        query_matcher === object_value # rubocop:disable Style/CaseEquality
+      end
+    end
+
+    protected
+
+    sig do
+      params(
+        collection: T::Array[T.untyped],
+        threshold: Integer,
+        _blk: T.proc.params(arg0: T.untyped).returns(T::Array[T.untyped])
+      ).returns(T::Hash[String, T::Hash[String, Integer]])
+    end
+    def deep_merge_counts(collection, threshold: 0, &_blk)
+      nested_counts = collection.each_with_object(
+        Hash.new { |h, k| h[k] = Hash.new(0) }
+      ) do |violation, new_nested_counts|
+        key, values = yield(violation)
+
+        new_nested_counts[key].merge!(values) { |_k, a, b| a + b }
+      end
+
+      threshold_drop(nested_counts, threshold: threshold)
+    end
+
+    sig do
+      params(
+        collection: T::Array[T.untyped],
+        _blk: T.proc.params(arg0: T.untyped).returns(T::Array[T.untyped])
+      ).returns(T::Hash[String, T::Array[T.untyped]])
+    end
+    def deep_merge_groups(collection, &_blk)
+      groups = collection.each_with_object(
+        Hash.new { |h, k| h[k] = [] }
+      ) do |violation, new_groups|
+        key, values = yield(violation)
+        new_groups[key].concat(values)
+      end
+
+      if groups.values.first.is_a?(String)
+        groups.transform_values(&:sort)
+      else
+        groups
+      end
+    end
+
+    sig do
+      params(
+        collection: T::Array[T.untyped],
+        _blk: T.proc.params(arg0: T.untyped).returns(T::Array[T.untyped])
+      ).returns(T::Hash[String, T::Hash[String, T::Array[String]]])
+    end
+    def deep_merge_hash_groups(collection, &_blk)
+      initial_hash = Hash.new do |constants, const_name|
+        constants[const_name] = Hash.new do |sources, source|
+          sources[source] = []
+        end
+      end
+
+      merged_collection = collection.each_with_object(initial_hash) do |violation, new_groups|
+        constant_name, sources = yield(violation)
+        sources.each do |source, file_locations|
+          new_groups[constant_name][source].concat(file_locations)
+        end
+      end
+
+      merged_collection.transform_values do |sources_hash|
+        sources_hash
+          .transform_values(&:sort)
+          .sort_by { |_anonymous_source, file_list| -file_list.size }
+          .to_h
+      end
+    end
+
+    sig do
+      params(
+        hash: T::Hash[String, T::Hash[String, Integer]],
+        threshold: Integer
+      ).returns(T::Hash[String, T::Hash[String, Integer]])
+    end
+    def threshold_drop(hash, threshold: 0)
+      hash
+        .transform_values { |vs| threshold_filter_sort(vs, threshold: threshold) }
+        .reject { |_k, vs| vs.empty? }
+    end
+
+    sig { params(hash: T::Hash[String, Integer], threshold: Integer).returns(T::Hash[String, Integer]) }
+    def threshold_filter_sort(hash, threshold: 0)
+      hash
+        .select { |_k, v| v >= threshold }
+        .sort_by { |_k, v| -v }
+        .to_h
+    end
+
+    mixes_in_class_methods(ClassMethods)
+  end
+end

data/lib/query_packwerk/rule_rewriter/anonymize_arguments_rule.rb

@@ -0,0 +1,31 @@
+# typed: false
+# frozen_string_literal: true
+
+module QueryPackwerk
+  class RuleRewriter
+    class AnonymizeArgumentsRule < BaseRule
+      extend T::Sig
+
+      # Arguments prefixed with a sigil like `*arg` and `&fn`
+      SIGIL_ARGS = T.let(%i[splat block_pass].freeze, T::Array[Symbol])
+
+      sig { override.params(node: RuboCop::AST::Node).void }
+      def on_send(node)
+        return unless node.arguments?
+
+        node.arguments.reject(&:hash_type?).each do |arg|
+          arg_node = if SIGIL_ARGS.include?(arg.type)
+                       arg.children.first
+                     else
+                       arg
+                     end
+
+          # Just in case we get strangely shaped nodes
+          next unless arg_node.respond_to?(:loc)
+
+          @rewriter.replace(arg_node.loc.expression, ANONYMIZED)
+        end
+      end
+    end
+  end
+end

data/lib/query_packwerk/rule_rewriter/anonymize_keyword_arguments_rule.rb

@@ -0,0 +1,30 @@
+# typed: false
+# frozen_string_literal: true
+
+module QueryPackwerk
+  class RuleRewriter
+    class AnonymizeKeywordArgumentsRule < BaseRule
+      extend T::Sig
+
+      sig { override.params(node: RuboCop::AST::Node).void }
+      def on_send(node)
+        return unless node.arguments?
+
+        node.arguments.select(&:hash_type?).each do |hash_node|
+          hash_node.children.each do |pair|
+            _keyword_node, value_node = if pair.kwsplat_type?
+                                          [nil, pair.children.first]
+                                        else
+                                          pair.children
+                                        end
+
+            # Just in case we get strangely shaped nodes
+            next unless value_node.respond_to?(:loc)
+
+            @rewriter.replace(value_node.loc.expression, ANONYMIZED)
+          end
+        end
+      end
+    end
+  end
+end