packwerk 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a473db2c54adea132ca7e61a51072b570d7e37b7d63c021259eef3cc7625177b
-  data.tar.gz: 1b8486e61969621fac562d2fb6ebe47dcf6f71fcd13f6d18524337a3ed831ac2
+  metadata.gz: 66332315c1155336fbe79f8aeb6e44a0893d4100a1d4b6b5f08c81574c940fe0
+  data.tar.gz: 88da350ce07daaf7556d23edbc318a19ca33b74af71ee624d547a8a8598bc16b
 SHA512:
-  metadata.gz: 8c05f0ce6e8b398a87e98453c721d00707628918ce8455600c1cb00fb2cb9c68efc6bea373323e889d36fc3658ff45db3508b0e6386b876da58ca50cdb53ab9f
-  data.tar.gz: 51586b68f489ff1f32df06338d05a64cab753da56c11575b3c5c8fa55019e9a8527e0a20c54c8695e1432307227d26c10f01b0d6c610e41c55d84296be000bd8
+  metadata.gz: b54eeeac5e68285e03c32916d72f2afdc291d9d6d4993de0d2875d7dbb4a9cdf8cde7ca2677107f35288a20a20c1f8fc2f9ddcc330c9a7fe0dfaf8e245c07b3c
+  data.tar.gz: d8597878958e00a069cb5e51c609e04da9526b3c1933c4824399e4bad1173d718703c88ec582411a9c73fb5c88899707b04ebdb7b296a22b70e25598e11b57d6

data/Gemfile.lock

@@ -87,12 +87,13 @@ GIT
 PATH
   remote: .
   specs:
-    packwerk (2.0.0)
+    packwerk (2.1.0)
       activesupport (>= 5.2)
       ast
       better_html
       bundler
       constant_resolver
+      digest
       parallel
       parser
       sorbet-runtime
@@ -118,6 +119,7 @@ GEM
     concurrent-ruby (1.1.8)
     constant_resolver (0.1.5)
     crass (1.0.6)
+    digest (3.1.0)
     erubi (1.10.0)
     globalid (0.4.2)
       activesupport (>= 4.2.0)
@@ -145,8 +147,6 @@ GEM
     nokogiri (1.12.5)
       mini_portile2 (~> 2.6.1)
       racc (~> 1.4)
-    nokogiri (1.12.5-x86_64-darwin)
-      racc (~> 1.4)
     parallel (1.20.1)
     parlour (6.0.0)
       commander (~> 4.5)
@@ -257,4 +257,4 @@ DEPENDENCIES
   tapioca
 
 BUNDLED WITH
-   2.2.22
+   2.3.4

data/README.md

@@ -56,6 +56,13 @@ Read [USAGE.md](USAGE.md) for usage once Packwerk is installed on your project.
 
 "Packwerk" is pronounced [[ˈpakvɛʁk]](https://cdn.shopify.com/s/files/1/0258/7469/files/packwerk.mp3).
 
+## Ecosystem
+
+You can use these third party tools to enhance your packwerk experience:
+
+- https://github.com/bellroy/graphwerk draws a graph of your package dependencies
+- https://github.com/Gusto/packwerk-vscode integrates packwerk into Visual Studio Code so you can see violations right in your editor
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/USAGE.md

@@ -77,6 +77,8 @@ Packwerk reads from the `packwerk.yml` configuration file in the root directory.
 | package_paths        | **/                                       | a single pattern or a list of patterns to find package configuration files, see: [Defining packages](#Defining-packages) |
 | custom_associations  | N/A                                       | list of custom associations, if any |
 | parallel             | true                                      | when true, fork code parsing out to subprocesses |
+| cache                | false                                     | when true, caches the results of parsing files |
+| cache_directory      | tmp/cache/packwerk                        | the directory that will hold the packwerk cache |
 
 ### Using a custom ERB parser
 
@@ -100,6 +102,11 @@ end
 Packwerk::Parsers::Factory.instance.erb_parser_class = CustomParser
 ```
 
+## Using the cache
+Packwerk ships with an cache to help speed up file parsing. You can turn this on by setting `cache: true` in `packwerk.yml`.
+
+This will write to `tmp/cache/packwerk`.
+
 ## Validating the package system
 
 There are some criteria that an application must meet in order to have a valid package system. These criteria include having a valid autoload path cache, package definition files, and application folder structure. The dependency graph within the package system also has to be acyclic.

data/lib/packwerk/application_validator.rb

@@ -39,13 +39,13 @@ module Packwerk
         load_paths: @configuration.load_paths
       )
 
-      results = []
+      results = T.let([], T::Array[Packwerk::Result])
 
       privacy_settings.each do |config_file_path, setting|
         next unless setting.is_a?(Array)
         constants = setting
 
-        assert_constants_can_be_loaded(constants)
+        results += assert_constants_can_be_loaded(constants, config_file_path)
 
         constant_locations = constants.map { |c| [c, resolver.resolve(c)&.location] }
 
@@ -265,9 +265,18 @@ module Packwerk
       !File.file?(package_path)
     end
 
-    def assert_constants_can_be_loaded(constants)
-      constants.each(&:constantize)
-      nil
+    def assert_constants_can_be_loaded(constants, config_file_path)
+      constants.map do |constant|
+        if !constant.start_with?("::")
+          Result.new(
+            false,
+            "'#{constant}', listed in the 'enforce_privacy' option in #{config_file_path}, is invalid.\n"\
+            "Private constants need to be prefixed with the top-level namespace operator `::`."
+          )
+        else
+          constant.try(&:constantize) && Result.new(true)
+        end
+      end
     end
 
     def private_constant_unresolvable(name, config_file_path)

data/lib/packwerk/cache.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+# typed: strict
+
+require "digest"
+
+module Packwerk
+  class Cache
+    extend T::Sig
+
+    class CacheContents < T::Struct
+      extend T::Sig
+
+      const :file_contents_digest, String
+      const :unresolved_references, T::Array[UnresolvedReference]
+
+      sig { returns(String) }
+      def serialize
+        to_json
+      end
+
+      sig { params(serialized_cache_contents: String).returns(CacheContents) }
+      def self.deserialize(serialized_cache_contents)
+        cache_contents_json = JSON.parse(serialized_cache_contents)
+        unresolved_references = cache_contents_json["unresolved_references"].map do |json|
+          UnresolvedReference.new(
+            json["constant_name"],
+            json["namespace_path"],
+            json["relative_path"],
+            Node::Location.new(json["source_location"]["line"], json["source_location"]["column"],)
+          )
+        end
+
+        CacheContents.new(
+          file_contents_digest: cache_contents_json["file_contents_digest"],
+          unresolved_references: unresolved_references,
+        )
+      end
+    end
+
+    CACHE_SHAPE = T.type_alias do
+      T::Hash[
+        String,
+        CacheContents
+      ]
+    end
+
+    sig { params(enable_cache: T::Boolean, cache_directory: Pathname, config_path: String).void }
+    def initialize(enable_cache:, cache_directory:, config_path:)
+      @enable_cache = enable_cache
+      @cache = T.let({}, CACHE_SHAPE)
+      @files_by_digest = T.let({}, T::Hash[String, String])
+      @config_path = config_path
+      @cache_directory = cache_directory
+
+      if @enable_cache
+        create_cache_directory!
+        bust_cache_if_packwerk_yml_has_changed!
+        bust_cache_if_inflections_have_changed!
+      end
+    end
+
+    sig { void }
+    def bust_cache!
+      FileUtils.rm_rf(@cache_directory)
+    end
+
+    sig do
+      params(
+        file_path: String,
+        block: T.proc.returns(T::Array[UnresolvedReference])
+      ).returns(T::Array[UnresolvedReference])
+    end
+    def with_cache(file_path, &block)
+      return block.call unless @enable_cache
+
+      cache_location = @cache_directory.join(digest_for_string(file_path))
+
+      cache_contents = if cache_location.exist?
+        T.let(CacheContents.deserialize(cache_location.read),
+          CacheContents)
+      end
+
+      file_contents_digest = digest_for_file(file_path)
+
+      if !cache_contents.nil? && cache_contents.file_contents_digest == file_contents_digest
+        Debug.out("Cache hit for #{file_path}")
+
+        cache_contents.unresolved_references
+      else
+        Debug.out("Cache miss for #{file_path}")
+
+        unresolved_references = block.call
+
+        cache_contents = CacheContents.new(
+          file_contents_digest: file_contents_digest,
+          unresolved_references: unresolved_references,
+        )
+        cache_location.write(cache_contents.serialize)
+
+        unresolved_references
+      end
+    end
+
+    sig { params(file: String).returns(String) }
+    def digest_for_file(file)
+      digest_for_string(File.read(file))
+    end
+
+    sig { params(str: String).returns(String) }
+    def digest_for_string(str)
+      # MD5 appears to be the fastest
+      # https://gist.github.com/morimori/1330095
+      Digest::MD5.hexdigest(str)
+    end
+
+    sig { void }
+    def bust_cache_if_packwerk_yml_has_changed!
+      bust_cache_if_contents_have_changed(File.read(@config_path), :packwerk_yml)
+    end
+
+    sig { void }
+    def bust_cache_if_inflections_have_changed!
+      bust_cache_if_contents_have_changed(YAML.dump(ActiveSupport::Inflector.inflections), :inflections)
+    end
+
+    sig { params(contents: String, contents_key: Symbol).void }
+    def bust_cache_if_contents_have_changed(contents, contents_key)
+      current_digest = digest_for_string(contents)
+      cached_digest_path = @cache_directory.join(contents_key.to_s)
+
+      if !cached_digest_path.exist?
+        # In this case, we have nothing cached
+        # We save the current digest. This way the next time we compare current digest to cached digest,
+        # we can accurately determine if we should bust the cache
+        cached_digest_path.write(current_digest)
+
+        nil
+      elsif cached_digest_path.read == current_digest
+        Debug.out("#{contents_key} contents have NOT changed, preserving cache")
+      else
+        Debug.out("#{contents_key} contents have changed, busting cache")
+
+        bust_cache!
+        create_cache_directory!
+
+        cached_digest_path.write(current_digest)
+      end
+    end
+
+    sig { void }
+    def create_cache_directory!
+      FileUtils.mkdir_p(@cache_directory)
+    end
+  end
+
+  class Debug
+    extend T::Sig
+
+    sig { params(out: String).void }
+    def self.out(out)
+      if ENV["DEBUG_PACKWERK_CACHE"]
+        puts(out)
+      end
+    end
+  end
+
+  private_constant :Debug
+end

data/lib/packwerk/configuration.rb

@@ -34,10 +34,21 @@ module Packwerk
     DEFAULT_EXCLUDE_GLOBS = ["{bin,node_modules,script,tmp,vendor}/**/*"]
 
     attr_reader(
-      :include, :exclude, :root_path, :package_paths, :custom_associations, :config_path
+      :include, :exclude, :root_path, :package_paths, :custom_associations, :config_path, :cache_directory
     )
 
     def initialize(configs = {}, config_path: nil)
+      @include = configs["include"] || DEFAULT_INCLUDE_GLOBS
+      @exclude = configs["exclude"] || DEFAULT_EXCLUDE_GLOBS
+      root = config_path ? File.dirname(config_path) : "."
+      @root_path = File.expand_path(root)
+      @package_paths = configs["package_paths"] || "**/"
+      @custom_associations = configs["custom_associations"] || []
+      @parallel = configs.key?("parallel") ? configs["parallel"] : true
+      @cache_enabled = configs.key?("cache") ? configs["cache"] : false
+      @cache_directory = Pathname.new(configs["cache_directory"] || "tmp/cache/packwerk")
+      @config_path = config_path
+
       if configs["load_paths"]
         warning = <<~WARNING
           DEPRECATION WARNING: The 'load_paths' key in `packwerk.yml` is deprecated.
@@ -47,7 +58,6 @@ module Packwerk
         warn(warning)
       end
 
-      inflection_file = File.expand_path(configs["inflections_file"] || "config/inflections.yml", @root_path)
       if configs["inflections_file"]
         warning = <<~WARNING
           DEPRECATION WARNING: The 'inflections_file' key in `packwerk.yml` is deprecated.
@@ -58,6 +68,7 @@ module Packwerk
         warn(warning)
       end
 
+      inflection_file = File.expand_path(configs["inflections_file"] || "config/inflections.yml", @root_path)
       if Pathname.new(inflection_file).exist?
         warning = <<~WARNING
           DEPRECATION WARNING: Inflections YMLs in packwerk are now deprecated.
@@ -66,16 +77,6 @@ module Packwerk
 
         warn(warning)
       end
-
-      @include = configs["include"] || DEFAULT_INCLUDE_GLOBS
-      @exclude = configs["exclude"] || DEFAULT_EXCLUDE_GLOBS
-      root = config_path ? File.dirname(config_path) : "."
-      @root_path = File.expand_path(root)
-      @package_paths = configs["package_paths"] || "**/"
-      @custom_associations = configs["custom_associations"] || []
-      @parallel = configs.key?("parallel") ? configs["parallel"] : true
-
-      @config_path = config_path
     end
 
     def load_paths
@@ -85,5 +86,9 @@ module Packwerk
     def parallel?
       @parallel
     end
+
+    def cache_enabled?
+      @cache_enabled
+    end
   end
 end

data/lib/packwerk/constant_discovery.rb

@@ -4,7 +4,7 @@
 require "constant_resolver"
 
 module Packwerk
-  # Get information about (partially qualified) constants without loading the application code.
+  # Get information about unresolved constants without loading the application code.
   # Information gathered: Fully qualified name, path to file containing the definition, package,
   # and visibility (public/private to the package).
   #
@@ -35,9 +35,9 @@ module Packwerk
     end
 
     # Analyze a constant via its name.
-    # If the name is partially qualified, we need the current namespace path to correctly infer its full name
+    # If the constant is unresolved, we need the current namespace path to correctly infer its full name
     #
-    # @param const_name [String] The constant's name, fully or partially qualified.
+    # @param const_name [String] The unresolved constant's name.
     # @param current_namespace_path [Array<String>] (optional) The namespace of the context in which the constant is
     #   used, e.g. ["Apps", "Models"] for `Apps::Models`. Defaults to [] which means top level.
     # @return [Packwerk::ConstantDiscovery::ConstantContext]

data/lib/packwerk/deprecated_references.rb

@@ -16,6 +16,7 @@ module Packwerk
       @package = package
       @filepath = filepath
       @new_entries = T.let({}, ENTRIES_TYPE)
+      @deprecated_references = T.let(nil, T.nilable(ENTRIES_TYPE))
     end
 
     sig do
@@ -103,7 +104,6 @@ module Packwerk
 
     sig { returns(ENTRIES_TYPE) }
     def deprecated_references
-      @deprecated_references ||= T.let(@deprecated_references, T.nilable(ENTRIES_TYPE))
       @deprecated_references ||= if File.exist?(@filepath)
         load_yaml(@filepath)
       else

data/lib/packwerk/file_processor.rb

@@ -13,8 +13,16 @@ module Packwerk
       end
     end
 
-    def initialize(node_processor_factory:, parser_factory: nil)
+    sig do
+      params(
+        node_processor_factory: NodeProcessorFactory,
+        cache: Cache,
+        parser_factory: T.nilable(Parsers::Factory)
+      ).void
+    end
+    def initialize(node_processor_factory:, cache:, parser_factory: nil)
       @node_processor_factory = node_processor_factory
+      @cache = cache
       @parser_factory = parser_factory || Packwerk::Parsers::Factory.instance
     end
 
@@ -22,7 +30,7 @@ module Packwerk
       params(file_path: String).returns(
         T::Array[
           T.any(
-            Packwerk::Reference,
+            Packwerk::UnresolvedReference,
             Packwerk::Offense,
           )
         ]
@@ -31,16 +39,22 @@ module Packwerk
     def call(file_path)
       return [UnknownFileTypeResult.new(file: file_path)] if parser_for(file_path).nil?
 
-      node = parse_into_ast(file_path)
-      return [] unless node
+      @cache.with_cache(file_path) do
+        node = parse_into_ast(file_path)
+
+        return [] unless node
 
-      references_from_ast(node, file_path)
+        references_from_ast(node, file_path)
+      end
     rescue Parsers::ParseError => e
       [e.result]
     end
 
     private
 
+    sig do
+      params(node: Parser::AST::Node, file_path: String).returns(T::Array[UnresolvedReference])
+    end
     def references_from_ast(node, file_path)
       references = []
 

data/lib/packwerk/generators/templates/packwerk.yml.erb

@@ -15,3 +15,9 @@
 # List of custom associations, if any
 # custom_associations:
 # - "cache_belongs_to"
+
+# Whether or not you want the cache enabled (disabled by default)
+# cache: true
+
+# Where you want the cache to be stored (default below)
+# cache_directory: 'tmp/cache/packwerk'

data/lib/packwerk/node.rb

@@ -5,7 +5,7 @@ require "parser"
 require "parser/ast/node"
 
 module Packwerk
-  # Convenience methods for working with AST nodes.
+  # Convenience methods for working with Parser::AST::Node nodes.
   module Node
     class TypeError < ArgumentError; end
     Location = Struct.new(:line, :column)
@@ -264,6 +264,7 @@ module Packwerk
         # "Class.new"
         # "Module.new"
         method_call?(node) &&
+          receiver(node) &&
           constant?(receiver(node)) &&
           ["Class", "Module"].include?(constant_name(receiver(node))) &&
           method_name(node) == :new

data/lib/packwerk/node_processor.rb

@@ -21,7 +21,7 @@ module Packwerk
       params(
         node: Parser::AST::Node,
         ancestors: T::Array[Parser::AST::Node]
-      ).returns(T.nilable(Packwerk::Reference))
+      ).returns(T.nilable(UnresolvedReference))
     end
     def call(node, ancestors)
       return unless Node.method_call?(node) || Node.constant?(node)

data/lib/packwerk/node_processor_factory.rb

@@ -22,7 +22,6 @@ module Packwerk
     sig { params(node: AST::Node).returns(::Packwerk::ReferenceExtractor) }
     def reference_extractor(node:)
       ::Packwerk::ReferenceExtractor.new(
-        context_provider: context_provider,
         constant_name_inspectors: constant_name_inspectors,
         root_node: node,
         root_path: root_path,

data/lib/packwerk/node_visitor.rb

@@ -4,6 +4,9 @@
 module Packwerk
   # Visits all nodes of an AST, processing them using a given node processor.
   class NodeVisitor
+    extend T::Sig
+
+    sig { params(node_processor: NodeProcessor).void }
     def initialize(node_processor:)
       @node_processor = node_processor
     end

data/lib/packwerk/package.rb

@@ -21,6 +21,7 @@ module Packwerk
       @name = name
       @config = T.let(config || {}, T::Hash[T.untyped, T.untyped])
       @dependencies = T.let(Array(@config["dependencies"]).freeze, T::Array[String])
+      @public_path = T.let(nil, T.nilable(String))
     end
 
     sig { returns(T.nilable(T.any(T::Boolean, T::Array[String]))) }
@@ -46,7 +47,6 @@ module Packwerk
 
     sig { returns(String) }
     def public_path
-      @public_path = T.let(@public_path, T.nilable(String))
       @public_path ||= begin
         unprefixed_public_path = user_defined_public_path || "app/public/"
 

data/lib/packwerk/package_set.rb

@@ -79,6 +79,7 @@ module Packwerk
       sorted_packages = packages.sort_by { |package| -package.name.length }
       packages = sorted_packages.each_with_object({}) { |package, hash| hash[package.name] = package }
       @packages = T.let(packages, T::Hash[String, Package])
+      @package_from_path = T.let({}, T::Hash[String, T.nilable(Package)])
     end
 
     sig { override.params(blk: T.proc.params(arg0: Package).returns(T.untyped)).returns(T.untyped) }
@@ -94,7 +95,7 @@ module Packwerk
     sig { params(file_path: T.any(Pathname, String)).returns(T.nilable(Package)) }
     def package_from_path(file_path)
       path_string = file_path.to_s
-      packages.values.find { |package| package.package_path?(path_string) }
+      @package_from_path[path_string] ||= packages.values.find { |package| package.package_path?(path_string) }
     end
   end
 end

data/lib/packwerk/parsed_constant_definitions.rb

@@ -25,13 +25,13 @@ module Packwerk
     def self.reference_qualifications(constant_name, namespace_path:)
       return [constant_name] if constant_name.start_with?("::")
 
-      fully_qualified_constant_name = "::#{constant_name}"
+      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 + fully_qualified_constant_name }
+      possible_namespaces.map { |namespace| namespace + resolved_constant_name }
     end
 
     private
@@ -53,9 +53,9 @@ module Packwerk
     end
 
     def add_definition(constant_name, current_namespace_path, location)
-      fully_qualified_constant = [""].concat(current_namespace_path).push(constant_name).join("::")
+      resolved_constant = [""].concat(current_namespace_path).push(constant_name).join("::")
 
-      @local_definitions[fully_qualified_constant] = location
+      @local_definitions[resolved_constant] = location
     end
   end
 end

data/lib/packwerk/reference_extractor.rb

@@ -8,58 +8,105 @@ module Packwerk
 
     sig do
       params(
-        context_provider: Packwerk::ConstantDiscovery,
         constant_name_inspectors: T::Array[Packwerk::ConstantNameInspector],
         root_node: ::AST::Node,
         root_path: String,
       ).void
     end
     def initialize(
-      context_provider:,
       constant_name_inspectors:,
       root_node:,
       root_path:
     )
-      @context_provider = context_provider
       @constant_name_inspectors = constant_name_inspectors
       @root_path = root_path
       @local_constant_definitions = ParsedConstantDefinitions.new(root_node: root_node)
     end
 
+    sig do
+      params(
+        node: Parser::AST::Node,
+        ancestors: T::Array[Parser::AST::Node],
+        file_path: String
+      ).returns(T.nilable(UnresolvedReference))
+    end
     def reference_from_node(node, ancestors:, file_path:)
       constant_name = T.let(nil, T.nilable(String))
 
       @constant_name_inspectors.each do |inspector|
         constant_name = inspector.constant_name_from_node(node, ancestors: ancestors)
+
         break if constant_name
       end
 
       reference_from_constant(constant_name, node: node, ancestors: ancestors, file_path: file_path) if constant_name
     end
 
-    private
+    sig do
+      params(
+        unresolved_references_and_offenses: T::Array[T.any(UnresolvedReference, Offense)],
+        context_provider: ConstantDiscovery
+      ).returns(T::Array[T.any(Reference, Offense)])
+    end
+    def self.get_fully_qualified_references_and_offenses_from(unresolved_references_and_offenses, context_provider)
+      fully_qualified_references_and_offenses = T.let([], T::Array[T.any(Reference, Offense)])
 
-    def reference_from_constant(constant_name, node:, ancestors:, file_path:)
-      namespace_path = Node.enclosing_namespace_path(node, ancestors: ancestors)
-      return if local_reference?(constant_name, Node.name_location(node), namespace_path)
+      unresolved_references_and_offenses.each do |unresolved_references_or_offense|
+        if unresolved_references_or_offense.is_a?(Offense)
+          fully_qualified_references_and_offenses << unresolved_references_or_offense
+
+          next
+        end
+
+        unresolved_reference = unresolved_references_or_offense
+
+        constant =
+          context_provider.context_for(
+            unresolved_reference.constant_name,
+            current_namespace_path: unresolved_reference.namespace_path
+          )
+
+        next if constant&.package.nil?
 
-      constant =
-        @context_provider.context_for(
-          constant_name,
-          current_namespace_path: namespace_path
+        source_package = context_provider.package_from_path(unresolved_reference.relative_path)
+
+        next if source_package == constant.package
+
+        fully_qualified_references_and_offenses << Reference.new(
+          source_package,
+          unresolved_reference.relative_path,
+          constant,
+          unresolved_reference.source_location
         )
+      end
 
-      return if constant&.package.nil?
+      fully_qualified_references_and_offenses
+    end
 
-      relative_path =
-        Pathname.new(file_path)
-          .relative_path_from(@root_path).to_s
+    private
+
+    sig do
+      params(
+        constant_name: String,
+        node: Parser::AST::Node,
+        ancestors: T::Array[Parser::AST::Node],
+        file_path: String
+      ).returns(T.nilable(UnresolvedReference))
+    end
+    def reference_from_constant(constant_name, node:, ancestors:, file_path:)
+      namespace_path = Node.enclosing_namespace_path(node, ancestors: ancestors)
 
-      source_package = @context_provider.package_from_path(relative_path)
+      return if local_reference?(constant_name, Node.name_location(node), namespace_path)
 
-      return if source_package == constant.package
+      relative_path = Pathname.new(file_path).relative_path_from(@root_path).to_s
+      location = Node.location(node)
 
-      Reference.new(source_package, relative_path, constant, Node.location(node))
+      UnresolvedReference.new(
+        constant_name,
+        namespace_path,
+        relative_path,
+        location
+      )
     end
 
     def local_reference?(constant_name, name_location, namespace_path)

data/lib/packwerk/run_context.rb

@@ -25,12 +25,16 @@ module Packwerk
     class << self
       def from_configuration(configuration)
         inflector = ActiveSupport::Inflector
+
         new(
           root_path: configuration.root_path,
           load_paths: configuration.load_paths,
           package_paths: configuration.package_paths,
           inflector: inflector,
-          custom_associations: configuration.custom_associations
+          custom_associations: configuration.custom_associations,
+          cache_enabled: configuration.cache_enabled?,
+          cache_directory: configuration.cache_directory,
+          config_path: configuration.config_path,
         )
       end
     end
@@ -41,7 +45,10 @@ module Packwerk
       package_paths: nil,
       inflector: nil,
       custom_associations: [],
-      checker_classes: DEFAULT_CHECKERS
+      checker_classes: DEFAULT_CHECKERS,
+      cache_enabled: false,
+      cache_directory: nil,
+      config_path: nil
     )
       @root_path = root_path
       @load_paths = load_paths
@@ -49,21 +56,27 @@ module Packwerk
       @inflector = inflector
       @custom_associations = custom_associations
       @checker_classes = checker_classes
+      @cache_enabled = cache_enabled
+      @cache_directory = cache_directory
+      @config_path = config_path
     end
 
     sig { params(file: String).returns(T::Array[Packwerk::Offense]) }
     def process_file(file:)
-      references = file_processor.call(file)
-
+      unresolved_references_and_offenses = file_processor.call(file)
+      references_and_offenses = ReferenceExtractor.get_fully_qualified_references_and_offenses_from(
+        unresolved_references_and_offenses,
+        context_provider
+      )
       reference_checker = ReferenceChecking::ReferenceChecker.new(checkers)
-      references.flat_map { |reference| reference_checker.call(reference) }
+      references_and_offenses.flat_map { |reference| reference_checker.call(reference) }
     end
 
     private
 
     sig { returns(FileProcessor) }
     def file_processor
-      @file_processor ||= FileProcessor.new(node_processor_factory: node_processor_factory)
+      @file_processor ||= FileProcessor.new(node_processor_factory: node_processor_factory, cache: cache)
     end
 
     sig { returns(NodeProcessorFactory) }
@@ -77,7 +90,7 @@ module Packwerk
 
     sig { returns(ConstantDiscovery) }
     def context_provider
-      ::Packwerk::ConstantDiscovery.new(
+      @context_provider ||= ::Packwerk::ConstantDiscovery.new(
         constant_resolver: resolver,
         packages: package_set
       )
@@ -92,6 +105,11 @@ module Packwerk
       )
     end
 
+    sig { returns(Cache) }
+    def cache
+      @cache ||= Cache.new(enable_cache: @cache_enabled, cache_directory: @cache_directory, config_path: @config_path)
+    end
+
     sig { returns(PackageSet) }
     def package_set
       ::Packwerk::PackageSet.load_all_from(root_path, package_pathspec: package_paths)

data/lib/packwerk/unresolved_reference.rb

@@ -0,0 +1,10 @@
+# typed: true
+# frozen_string_literal: true
+
+module Packwerk
+  # An unresolved reference from a file in one package to a constant that may be defined in a different package.
+  # Unresolved means that we know how it's referred to in the file,
+  # and we have enough context on that reference to figure out the fully qualified reference such that we
+  # can produce a Reference in a separate pass. However, we have not yet resolved it to its fully qualified version.
+  UnresolvedReference = Struct.new(:constant_name, :namespace_path, :relative_path, :source_location)
+end

data/lib/packwerk/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Packwerk
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 end

data/lib/packwerk.rb

@@ -15,6 +15,7 @@ module Packwerk
   autoload :ApplicationValidator
   autoload :AssociationInspector
   autoload :OffenseCollection
+  autoload :Cache
   autoload :Cli
   autoload :Configuration
   autoload :ConstantDiscovery
@@ -36,6 +37,7 @@ module Packwerk
   autoload :ParsedConstantDefinitions
   autoload :Parsers
   autoload :ParseRun
+  autoload :UnresolvedReference
   autoload :Reference
   autoload :ReferenceExtractor
   autoload :ReferenceOffense

data/packwerk.gemspec

@@ -45,6 +45,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency("parallel")
   spec.add_dependency("sorbet-runtime")
   spec.add_dependency("bundler")
+  spec.add_dependency("digest")
 
   spec.add_development_dependency("rake")
   spec.add_development_dependency("sorbet")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: packwerk
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Shopify Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-12-08 00:00:00.000000000 Z
+date: 2022-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: digest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -222,6 +236,7 @@ files:
 - lib/packwerk/application_load_paths.rb
 - lib/packwerk/application_validator.rb
 - lib/packwerk/association_inspector.rb
+- lib/packwerk/cache.rb
 - lib/packwerk/cli.rb
 - lib/packwerk/configuration.rb
 - lib/packwerk/const_node_inspector.rb
@@ -266,6 +281,7 @@ files:
 - lib/packwerk/run_context.rb
 - lib/packwerk/sanity_checker.rb
 - lib/packwerk/spring_command.rb
+- lib/packwerk/unresolved_reference.rb
 - lib/packwerk/version.rb
 - lib/packwerk/violation_type.rb
 - library.yml