packwerk 2.2.0 → 2.2.1

data/lib/packwerk/node_helpers.rb

@@ -0,0 +1,335 @@
+# typed: true
+# frozen_string_literal: true
+
+require "parser"
+require "parser/ast/node"
+
+module Packwerk
+  # Convenience methods for working with Parser::AST::Node nodes.
+  module NodeHelpers
+    class TypeError < ArgumentError; end
+
+    class << self
+      extend T::Sig
+
+      sig { params(class_or_module_node: AST::Node).returns(String) }
+      def class_or_module_name(class_or_module_node)
+        case type_of(class_or_module_node)
+        when CLASS, MODULE
+          # (class (const nil :Foo) (const nil :Bar) (nil))
+          #   "class Foo < Bar; end"
+          # (module (const nil :Foo) (nil))
+          #   "module Foo; end"
+          identifier = class_or_module_node.children[0]
+          constant_name(identifier)
+        else
+          raise TypeError
+        end
+      end
+
+      sig { params(constant_node: AST::Node).returns(String) }
+      def constant_name(constant_node)
+        case type_of(constant_node)
+        when CONSTANT_ROOT_NAMESPACE
+          ""
+        when CONSTANT, CONSTANT_ASSIGNMENT, SELF
+          # (const nil :Foo)
+          #   "Foo"
+          # (const (cbase) :Foo)
+          #   "::Foo"
+          # (const (lvar :a) :Foo)
+          #   "a::Foo"
+          # (casgn nil :Foo (int 1))
+          #   "Foo = 1"
+          # (casgn (cbase) :Foo (int 1))
+          #   "::Foo = 1"
+          # (casgn (lvar :a) :Foo (int 1))
+          #   "a::Foo = 1"
+          # (casgn (self) :Foo (int 1))
+          #   "self::Foo = 1"
+          namespace, name = constant_node.children
+
+          if namespace
+            [constant_name(namespace), name].join("::")
+          else
+            name.to_s
+          end
+        else
+          raise TypeError
+        end
+      end
+
+      sig { params(node: AST::Node).returns(T.untyped) }
+      def each_child(node)
+        if block_given?
+          node.children.each do |child|
+            yield child if child.is_a?(Parser::AST::Node)
+          end
+        else
+          enum_for(:each_child, node)
+        end
+      end
+
+      sig { params(starting_node: AST::Node, ancestors: T::Array[AST::Node]).returns(T::Array[String]) }
+      def enclosing_namespace_path(starting_node, ancestors:)
+        ancestors.select { |n| [CLASS, MODULE].include?(type_of(n)) }
+          .each_with_object([]) do |node, namespace|
+          # when evaluating `class Child < Parent`, the const node for `Parent` is a child of the class
+          # node, so it'll be an ancestor, but `Parent` is not evaluated in the namespace of `Child`, so
+          # we need to skip it here
+          next if type_of(node) == CLASS && parent_class(node) == starting_node
+
+          namespace.prepend(class_or_module_name(node))
+        end
+      end
+
+      sig { params(string_or_symbol_node: AST::Node).returns(T.any(String, Symbol)) }
+      def literal_value(string_or_symbol_node)
+        case type_of(string_or_symbol_node)
+        when STRING, SYMBOL
+          # (str "foo")
+          #   "'foo'"
+          # (sym :foo)
+          #   ":foo"
+          string_or_symbol_node.children[0]
+        else
+          raise TypeError
+        end
+      end
+
+      sig { params(node: Parser::AST::Node).returns(Node::Location) }
+      def location(node)
+        location = node.location
+        Node::Location.new(location.line, location.column)
+      end
+
+      sig { params(node: AST::Node).returns(T::Boolean) }
+      def constant?(node)
+        type_of(node) == CONSTANT
+      end
+
+      sig { params(node: AST::Node).returns(T::Boolean) }
+      def constant_assignment?(node)
+        type_of(node) == CONSTANT_ASSIGNMENT
+      end
+
+      sig { params(node: AST::Node).returns(T::Boolean) }
+      def class?(node)
+        type_of(node) == CLASS
+      end
+
+      sig { params(node: AST::Node).returns(T::Boolean) }
+      def method_call?(node)
+        type_of(node) == METHOD_CALL
+      end
+
+      sig { params(node: AST::Node).returns(T::Boolean) }
+      def hash?(node)
+        type_of(node) == HASH
+      end
+
+      sig { params(node: AST::Node).returns(T::Boolean) }
+      def string?(node)
+        type_of(node) == STRING
+      end
+
+      sig { params(node: AST::Node).returns(T::Boolean) }
+      def symbol?(node)
+        type_of(node) == SYMBOL
+      end
+
+      sig { params(method_call_node: AST::Node).returns(T::Array[AST::Node]) }
+      def method_arguments(method_call_node)
+        raise TypeError unless method_call?(method_call_node)
+
+        # (send (lvar :foo) :bar (int 1))
+        #   "foo.bar(1)"
+        method_call_node.children.slice(2..-1)
+      end
+
+      sig { params(method_call_node: AST::Node).returns(Symbol) }
+      def method_name(method_call_node)
+        raise TypeError unless method_call?(method_call_node)
+
+        # (send (lvar :foo) :bar (int 1))
+        #   "foo.bar(1)"
+        method_call_node.children[1]
+      end
+
+      sig { params(node: AST::Node).returns(T.nilable(String)) }
+      def module_name_from_definition(node)
+        case type_of(node)
+        when CLASS, MODULE
+          # "class My::Class; end"
+          # "module My::Module; end"
+          class_or_module_name(node)
+        when CONSTANT_ASSIGNMENT
+          # "My::Class = ..."
+          # "My::Module = ..."
+          rvalue = node.children.last
+
+          case type_of(rvalue)
+          when METHOD_CALL
+            # "Class.new"
+            # "Module.new"
+            constant_name(node) if module_creation?(rvalue)
+          when BLOCK
+            # "Class.new do end"
+            # "Module.new do end"
+            constant_name(node) if module_creation?(method_call_node(rvalue))
+          end
+        end
+      end
+
+      sig { params(node: Parser::AST::Node).returns(T.nilable(Node::Location)) }
+      def name_location(node)
+        location = node.location
+
+        if location.respond_to?(:name)
+          name = location.name
+          Node::Location.new(name.line, name.column)
+        end
+      end
+
+      sig { params(class_node: AST::Node).returns(T.nilable(AST::Node)) }
+      def parent_class(class_node)
+        raise TypeError unless type_of(class_node) == CLASS
+
+        # (class (const nil :Foo) (const nil :Bar) (nil))
+        #   "class Foo < Bar; end"
+        class_node.children[1]
+      end
+
+      sig { params(ancestors: T::Array[AST::Node]).returns(String) }
+      def parent_module_name(ancestors:)
+        definitions = ancestors
+          .select { |n| [CLASS, MODULE, CONSTANT_ASSIGNMENT, BLOCK].include?(type_of(n)) }
+
+        names = definitions.map do |definition|
+          name_part_from_definition(definition)
+        end.compact
+
+        names.empty? ? "Object" : names.reverse.join("::")
+      end
+
+      sig { params(hash_node: AST::Node, key: Symbol).returns(T.untyped) }
+      def value_from_hash(hash_node, key)
+        raise TypeError unless hash?(hash_node)
+
+        pair = hash_pairs(hash_node).detect { |pair_node| literal_value(hash_pair_key(pair_node)) == key }
+        hash_pair_value(pair) if pair
+      end
+
+      private
+
+      BLOCK = :block
+      CLASS = :class
+      CONSTANT = :const
+      CONSTANT_ASSIGNMENT = :casgn
+      CONSTANT_ROOT_NAMESPACE = :cbase
+      HASH = :hash
+      HASH_PAIR = :pair
+      METHOD_CALL = :send
+      MODULE = :module
+      SELF = :self
+      STRING = :str
+      SYMBOL = :sym
+
+      private_constant(
+        :BLOCK, :CLASS, :CONSTANT, :CONSTANT_ASSIGNMENT, :CONSTANT_ROOT_NAMESPACE, :HASH, :HASH_PAIR, :METHOD_CALL,
+        :MODULE, :SELF, :STRING, :SYMBOL,
+      )
+
+      sig { params(node: AST::Node).returns(Symbol) }
+      def type_of(node)
+        node.type
+      end
+
+      sig { params(hash_pair_node: AST::Node).returns(T.untyped) }
+      def hash_pair_key(hash_pair_node)
+        raise TypeError unless type_of(hash_pair_node) == HASH_PAIR
+
+        # (pair (int 1) (int 2))
+        #   "1 => 2"
+        # (pair (sym :answer) (int 42))
+        #   "answer: 42"
+        hash_pair_node.children[0]
+      end
+
+      sig { params(hash_pair_node: AST::Node).returns(T.untyped) }
+      def hash_pair_value(hash_pair_node)
+        raise TypeError unless type_of(hash_pair_node) == HASH_PAIR
+
+        # (pair (int 1) (int 2))
+        #   "1 => 2"
+        # (pair (sym :answer) (int 42))
+        #   "answer: 42"
+        hash_pair_node.children[1]
+      end
+
+      sig { params(hash_node: AST::Node).returns(T::Array[AST::Node]) }
+      def hash_pairs(hash_node)
+        raise TypeError unless hash?(hash_node)
+
+        # (hash (pair (int 1) (int 2)) (pair (int 3) (int 4)))
+        #   "{1 => 2, 3 => 4}"
+        hash_node.children.select { |n| type_of(n) == HASH_PAIR }
+      end
+
+      sig { params(block_node: AST::Node).returns(AST::Node) }
+      def method_call_node(block_node)
+        raise TypeError unless type_of(block_node) == BLOCK
+
+        # (block (send (lvar :foo) :bar) (args) (int 42))
+        #   "foo.bar do 42 end"
+        block_node.children[0]
+      end
+
+      sig { params(node: AST::Node).returns(T::Boolean) }
+      def module_creation?(node)
+        # "Class.new"
+        # "Module.new"
+        method_call?(node) &&
+          dynamic_class_creation?(receiver(node)) &&
+          method_name(node) == :new
+      end
+
+      sig { params(node: T.nilable(AST::Node)).returns(T::Boolean) }
+      def dynamic_class_creation?(node)
+        !!node &&
+          constant?(node) &&
+          ["Class", "Module"].include?(constant_name(node))
+      end
+
+      sig { params(node: AST::Node).returns(T.nilable(String)) }
+      def name_from_block_definition(node)
+        if method_name(method_call_node(node)) == :class_eval
+          receiver = receiver(node)
+          constant_name(receiver) if receiver && constant?(receiver)
+        end
+      end
+
+      sig { params(node: AST::Node).returns(T.nilable(String)) }
+      def name_part_from_definition(node)
+        case type_of(node)
+        when CLASS, MODULE, CONSTANT_ASSIGNMENT
+          module_name_from_definition(node)
+        when BLOCK
+          name_from_block_definition(node)
+        end
+      end
+
+      sig { params(method_call_or_block_node: AST::Node).returns(T.nilable(AST::Node)) }
+      def receiver(method_call_or_block_node)
+        case type_of(method_call_or_block_node)
+        when METHOD_CALL
+          method_call_or_block_node.children[0]
+        when BLOCK
+          receiver(method_call_node(method_call_or_block_node))
+        else
+          raise TypeError
+        end
+      end
+    end
+  end
+end

data/lib/packwerk/node_processor.rb

@@ -9,12 +9,12 @@ module Packwerk
     sig do
       params(
         reference_extractor: ReferenceExtractor,
-        absolute_file: String,
+        relative_file: String,
       ).void
     end
-    def initialize(reference_extractor:, absolute_file:)
+    def initialize(reference_extractor:, relative_file:)
       @reference_extractor = reference_extractor
-      @absolute_file = absolute_file
+      @relative_file = relative_file
     end
 
     sig do
@@ -24,8 +24,9 @@ module Packwerk
       ).returns(T.nilable(UnresolvedReference))
     end
     def call(node, ancestors)
-      return unless Node.method_call?(node) || Node.constant?(node)
-      @reference_extractor.reference_from_node(node, ancestors: ancestors, absolute_file: @absolute_file)
+      return unless NodeHelpers.method_call?(node) || NodeHelpers.constant?(node)
+
+      @reference_extractor.reference_from_node(node, ancestors: ancestors, relative_file: @relative_file)
     end
   end
 end

data/lib/packwerk/node_processor_factory.rb

@@ -9,11 +9,11 @@ module Packwerk
     const :context_provider, Packwerk::ConstantDiscovery
     const :constant_name_inspectors, T::Array[ConstantNameInspector]
 
-    sig { params(absolute_file: String, node: AST::Node).returns(NodeProcessor) }
-    def for(absolute_file:, node:)
+    sig { params(relative_file: String, node: AST::Node).returns(NodeProcessor) }
+    def for(relative_file:, node:)
       ::Packwerk::NodeProcessor.new(
         reference_extractor: reference_extractor(node: node),
-        absolute_file: absolute_file,
+        relative_file: relative_file,
       )
     end
 

data/lib/packwerk/node_visitor.rb

@@ -16,7 +16,7 @@ module Packwerk
       result << reference if reference
 
       child_ancestors = [node] + ancestors
-      Node.each_child(node) do |child|
+      NodeHelpers.each_child(node) do |child|
         visit(child, ancestors: child_ancestors, result: result)
       end
     end

data/lib/packwerk/offense_collection.rb

@@ -31,6 +31,7 @@ module Packwerk
     end
     def listed?(offense)
       return false unless offense.is_a?(ReferenceOffense)
+
       reference = offense.reference
       deprecated_references_for(reference.source_package).listed?(reference, violation_type: offense.violation_type)
     end
@@ -49,9 +50,11 @@ module Packwerk
       end
     end
 
-    sig { returns(T::Boolean) }
-    def stale_violations?
-      @deprecated_references.values.any?(&:stale_violations?)
+    sig { params(for_files: T::Set[String]).returns(T::Boolean) }
+    def stale_violations?(for_files)
+      @deprecated_references.values.any? do |deprecated_references|
+        deprecated_references.stale_violations?(for_files)
+      end
     end
 
     sig { void }

data/lib/packwerk/offenses_formatter.rb

@@ -12,8 +12,8 @@ module Packwerk
     def show_offenses(offenses)
     end
 
-    sig { abstract.params(offense_collection: Packwerk::OffenseCollection).returns(String) }
-    def show_stale_violations(offense_collection)
+    sig { abstract.params(offense_collection: Packwerk::OffenseCollection, for_files: T::Set[String]).returns(String) }
+    def show_stale_violations(offense_collection, for_files)
     end
   end
 end

data/lib/packwerk/package.rb

@@ -13,6 +13,7 @@ module Packwerk
 
     sig { returns(String) }
     attr_reader :name
+
     sig { returns(T::Array[String]) }
     attr_reader :dependencies
 
@@ -42,6 +43,7 @@ module Packwerk
     sig { params(path: String).returns(T::Boolean) }
     def package_path?(path)
       return true if root?
+
       path.start_with?(@name)
     end
 
@@ -74,6 +76,7 @@ module Packwerk
     sig { params(other: T.untyped).returns(T.nilable(Integer)) }
     def <=>(other)
       return nil unless other.is_a?(self.class)
+
       name <=> other.name
     end
 

data/lib/packwerk/package_set.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "pathname"
+require "bundler"
 
 module Packwerk
   PathSpec = T.type_alias { T.any(String, T::Array[String]) }
@@ -59,6 +60,7 @@ module Packwerk
       sig { params(packages: T::Array[Package]).void }
       def create_root_package_if_none_in(packages)
         return if packages.any?(&:root?)
+
         packages << Package.new(name: Package::ROOT_PACKAGE_NAME, config: nil)
       end
 

data/lib/packwerk/parse_run.rb

@@ -14,14 +14,14 @@ module Packwerk
 
     sig do
       params(
-        absolute_file_set: FilesForProcessing::AbsoluteFileSet,
+        relative_file_set: FilesForProcessing::RelativeFileSet,
         configuration: Configuration,
         progress_formatter: Formatters::ProgressFormatter,
         offenses_formatter: OffensesFormatter,
       ).void
     end
     def initialize(
-      absolute_file_set:,
+      relative_file_set:,
       configuration:,
       progress_formatter: Formatters::ProgressFormatter.new(StringIO.new),
       offenses_formatter: Formatters::OffensesFormatter.new
@@ -29,15 +29,15 @@ module Packwerk
       @configuration = configuration
       @progress_formatter = progress_formatter
       @offenses_formatter = offenses_formatter
-      @absolute_file_set = absolute_file_set
+      @relative_file_set = relative_file_set
     end
 
     sig { returns(Result) }
     def detect_stale_violations
       offense_collection = find_offenses
 
-      result_status = !offense_collection.stale_violations?
-      message = @offenses_formatter.show_stale_violations(offense_collection)
+      result_status = !offense_collection.stale_violations?(@relative_file_set)
+      message = @offenses_formatter.show_stale_violations(offense_collection, @relative_file_set)
 
       Result.new(message: message, status: result_status)
     end
@@ -61,9 +61,11 @@ module Packwerk
 
       messages = [
         @offenses_formatter.show_offenses(offense_collection.outstanding_offenses),
-        @offenses_formatter.show_stale_violations(offense_collection),
+        @offenses_formatter.show_stale_violations(offense_collection, @relative_file_set),
       ]
-      result_status = offense_collection.outstanding_offenses.empty? && !offense_collection.stale_violations?
+
+      result_status = offense_collection.outstanding_offenses.empty? &&
+        !offense_collection.stale_violations?(@relative_file_set)
 
       Result.new(message: messages.join("\n") + "\n", status: result_status)
     end
@@ -73,13 +75,13 @@ module Packwerk
     sig { params(show_errors: T::Boolean).returns(OffenseCollection) }
     def find_offenses(show_errors: false)
       offense_collection = OffenseCollection.new(@configuration.root_path)
-      @progress_formatter.started(@absolute_file_set)
+      @progress_formatter.started(@relative_file_set)
 
       run_context = Packwerk::RunContext.from_configuration(@configuration)
       all_offenses = T.let([], T::Array[Offense])
 
-      process_file = T.let(-> (absolute_file) do
-        run_context.process_file(absolute_file: absolute_file).tap do |offenses|
+      process_file = T.let(->(relative_file) do
+        run_context.process_file(relative_file: relative_file).tap do |offenses|
           failed = show_errors && offenses.any? { |offense| !offense_collection.listed?(offense) }
           update_progress(failed: failed)
         end
@@ -87,7 +89,7 @@ module Packwerk
 
       execution_time = Benchmark.realtime do
         all_offenses = if @configuration.parallel?
-          Parallel.flat_map(@absolute_file_set, &process_file)
+          Parallel.flat_map(@relative_file_set, &process_file)
         else
           serial_find_offenses(&process_file)
         end
@@ -103,8 +105,8 @@ module Packwerk
     def serial_find_offenses(&block)
       all_offenses = T.let([], T::Array[Offense])
       begin
-        @absolute_file_set.each do |absolute_file|
-          offenses = block.call(absolute_file)
+        @relative_file_set.each do |relative_file|
+          offenses = yield(relative_file)
           all_offenses.concat(offenses)
         end
       rescue Interrupt

data/lib/packwerk/parsed_constant_definitions.rb

@@ -6,6 +6,21 @@ require "ast/node"
 module Packwerk
   # A collection of constant definitions parsed from an Abstract Syntax Tree (AST).
   class ParsedConstantDefinitions
+    class << self
+      # What fully qualified constants can this constant refer to in this context?
+      def reference_qualifications(constant_name, namespace_path:)
+        return [constant_name] if constant_name.start_with?("::")
+
+        resolved_constant_name = "::#{constant_name}"
+
+        possible_namespaces = namespace_path.each_with_object([""]) do |current, acc|
+          acc << "#{acc.last}::#{current}" if acc.last && current
+        end
+
+        possible_namespaces.map { |namespace| namespace + resolved_constant_name }
+      end
+    end
+
     def initialize(root_node:)
       @local_definitions = {}
 
@@ -21,35 +36,23 @@ module Packwerk
       end
     end
 
-    # What fully qualified constants can this constant refer to in this context?
-    def self.reference_qualifications(constant_name, namespace_path:)
-      return [constant_name] if constant_name.start_with?("::")
-
-      resolved_constant_name = "::#{constant_name}"
-
-      possible_namespaces = namespace_path.each_with_object([""]) do |current, acc|
-        acc << "#{acc.last}::#{current}" if acc.last && current
-      end
-
-      possible_namespaces.map { |namespace| namespace + resolved_constant_name }
-    end
-
     private
 
     def collect_local_definitions_from_root(node, current_namespace_path = [])
-      if Node.constant_assignment?(node)
-        add_definition(Node.constant_name(node), current_namespace_path, Node.name_location(node))
-      elsif Node.module_name_from_definition(node)
+      if NodeHelpers.constant_assignment?(node)
+        add_definition(NodeHelpers.constant_name(node), current_namespace_path, NodeHelpers.name_location(node))
+      elsif NodeHelpers.module_name_from_definition(node)
         # handle compact constant nesting (e.g. "module Sales::Order")
         tempnode = node
-        while (tempnode = Node.each_child(tempnode).find { |n| Node.constant?(n) })
-          add_definition(Node.constant_name(tempnode), current_namespace_path, Node.name_location(tempnode))
+        while (tempnode = NodeHelpers.each_child(tempnode).find { |n| NodeHelpers.constant?(n) })
+          add_definition(NodeHelpers.constant_name(tempnode), current_namespace_path,
+            NodeHelpers.name_location(tempnode))
         end
 
-        current_namespace_path += Node.class_or_module_name(node).split("::")
+        current_namespace_path += NodeHelpers.class_or_module_name(node).split("::")
       end
 
-      Node.each_child(node) { |child| collect_local_definitions_from_root(child, current_namespace_path) }
+      NodeHelpers.each_child(node) { |child| collect_local_definitions_from_root(child, current_namespace_path) }
     end
 
     def add_definition(constant_name, current_namespace_path, location)

data/lib/packwerk/parsers/erb.rb

@@ -49,8 +49,8 @@ module Packwerk
         )
       end
 
-      def code_nodes(node)
-        return enum_for(:code_nodes, node) unless block_given?
+      def code_nodes(node, &block)
+        return enum_for(:code_nodes, node) unless block
         return unless node.is_a?(::AST::Node)
 
         yield node if node.type == :code
@@ -62,7 +62,7 @@ module Packwerk
         end
 
         node.children.each do |child|
-          code_nodes(child) { |n| yield n }
+          code_nodes(child, &block)
         end
       end
     end

data/lib/packwerk/reference_checking/checkers/checker.rb

@@ -8,13 +8,26 @@ module Packwerk
         extend T::Sig
         extend T::Helpers
 
-        interface!
+        abstract!
 
-        sig { returns(ViolationType).abstract }
+        sig { abstract.returns(ViolationType) }
         def violation_type; end
 
-        sig { params(reference: Reference).returns(T::Boolean).abstract }
+        sig { abstract.params(reference: Reference).returns(T::Boolean) }
         def invalid_reference?(reference); end
+
+        sig { abstract.params(reference: Reference).returns(String) }
+        def message(reference); end
+
+        sig { params(reference: Reference).returns(String) }
+        def standard_help_message(reference)
+          standard_message = <<~EOS
+            Inference details: this is a reference to #{reference.constant.name} which seems to be defined in #{reference.constant.location}.
+            To receive help interpreting or resolving this error message, see: https://github.com/Shopify/packwerk/blob/main/TROUBLESHOOT.md#Troubleshooting-violations
+          EOS
+
+          standard_message.chomp
+        end
       end
     end
   end