More clarification and documentation

Author: martinemde

lib/query_packwerk.rb

@@ -31,41 +31,45 @@ def package(name)
     Packages.where(name: name).first
   end
 
-  # All violations for a pack
+  # Get all violations where other packages access code from this package
+  # (i.e., this package is the producer, others are consumers)
   sig { params(pack_name: String).returns(QueryPackwerk::Violations) }
   def violations_for(pack_name)
     QueryPackwerk::Violations.where(producing_pack: full_name(pack_name))
   end
 
+  # Get all todos where this package accesses code from other packages
+  # (i.e., this package is the consumer, others are producers)
+  sig { params(pack_name: String).returns(QueryPackwerk::Violations) }
   def todos_for(pack_name)
-    package(pack_name).todos
+    QueryPackwerk::Violations.where(consuming_pack: full_name(pack_name))
   end
 
-  # Where the violations occurred
+  # Get where the violations occurred (where other packages access this package)
   sig { params(pack_name: String).returns(T::Hash[String, T::Array[String]]) }
   def violation_sources_for(pack_name)
     violations_for(pack_name).sources_with_locations
   end
 
-  # How often the violations occurred
+  # Get how often the violations occurred
   sig { params(pack_name: String, threshold: Integer).returns(T::Hash[String, T::Hash[String, Integer]]) }
   def violation_counts_for(pack_name, threshold: 0)
     violations_for(pack_name).source_counts(threshold: threshold)
   end
 
-  # The "shape" of all of the occurring violations
+  # Get the 'shape' of all violations (how other packages access this package)
   sig { params(pack_name: String).returns(T::Hash[String, T::Array[String]]) }
   def anonymous_violation_sources_for(pack_name)
     violations_for(pack_name).anonymous_sources
   end
 
-  # How often each of those shapes occurs
+  # Get how often each 'shape' of violation occurs (counts of how other packages access this package)
   sig { params(pack_name: String, threshold: Integer).returns(T::Hash[String, T::Hash[String, Integer]]) }
   def anonymous_violation_counts_for(pack_name, threshold: 0)
     violations_for(pack_name).anonymous_source_counts(threshold: threshold)
   end
 
-  # Who consumes this pack?
+  # Get which packages consume code from this package (who depends on this package)
   sig { params(pack_name: String, threshold: Integer).returns(T::Hash[String, Integer]) }
   def consumers(pack_name, threshold: 0)
     violations_for(pack_name).consumers(threshold: threshold)

lib/query_packwerk/console.rb

@@ -56,15 +56,21 @@ def inspect
         puts 'QueryPackwerk Console'
         puts '====================='
         puts 'Available commands:'
-        puts '  violations_for(pack_name)                  - Get all violations for a pack'
-        puts '  violation_sources_for(pack_name)           - Get where violations occurred'
-        puts '  violation_counts_for(pack_name)            - Get how often violations occurred'
-        puts "  anonymous_violation_sources_for(pack_name) - Get the 'shape' of violations"
-        puts '  anonymous_violation_counts_for(pack_name)  - Get how often each shape occurs'
-        puts '  consumers(pack_name)                       - Get who consumes this pack'
         puts '  package(pack_name)                         - Get a package by name'
         puts '  Packages.all                               - Get all packages'
-        puts '  Violations.all                             - Get all violations'
+        puts ''
+        puts 'Package Consumption (how others use this package):'
+        puts '  violations_for(pack_name)                  - Get all violations where others access this package'
+        puts '  violation_sources_for(pack_name)           - Get where others access this package'
+        puts '  violation_counts_for(pack_name)            - Get how often others access this package'
+        puts "  anonymous_violation_sources_for(pack_name) - Get the 'shape' of how others access this package"
+        puts '  anonymous_violation_counts_for(pack_name)  - Get how often each access pattern occurs'
+        puts '  consumers(pack_name)                       - Get which packages consume this package'
+        puts ''
+        puts 'Package Dependencies (how this package uses others):'
+        puts '  todos_for(pack_name)                       - Get all todos where this package accesses others'
+        puts ''
+        puts 'Violations.all                               - Get all violations'
         puts ''
 
         catch(:IRB_EXIT) do

lib/query_packwerk/package.rb

@@ -61,31 +61,40 @@ 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 dependency_violations todos
+    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 consumer_violations violations
+    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
-      consumer_violations.consumers.keys
+      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
-      consumer_violations.consumers
+      violations.consumers
     end
 
     sig { returns(String) }

lib/query_packwerk/violations.rb

@@ -219,6 +219,13 @@ def consumers(threshold: 0)
       threshold_filter_sort(tallies, threshold:)
     end
 
+    # Find which packs produce these violations
+    sig { params(threshold: Integer).returns(T::Hash[String, Integer]) }
+    def producers(threshold: 0)
+      tallies = @original_collection.map { |v| v.producing_pack.name }.tally
+      threshold_filter_sort(tallies, threshold:)
+    end
+
     # Filter for violations which include one of the provided file globs
     sig { params(file_globs: T.any(String, Regexp)).returns(QueryPackwerk::Violations) }
     def including_files(*file_globs)

spec/query_packwerk/package_spec.rb

@@ -63,10 +63,10 @@
     end
   end
 
-  describe '#dependency_violations' do
+  describe '#outgoing_violations' do
     it 'is an alias for #todos' do
       # Both methods should return equivalent objects but might not be equal with `==`
-      expect(package.todos.to_a).to match_array(package.dependency_violations.to_a)
+      expect(package.todos.to_a).to match_array(package.outgoing_violations.to_a)
     end
   end
 
@@ -77,10 +77,10 @@
     end
   end
 
-  describe '#consumer_violations' do
+  describe '#incoming_violations' do
     it 'is an alias for #violations' do
       # Both methods should return equivalent objects but might not be equal with `==`
-      expect(package.consumer_violations.to_a).to match_array(package.violations.to_a)
+      expect(package.incoming_violations.to_a).to match_array(package.violations.to_a)
     end
   end