packwerk 1.3.1 → 2.1.0

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

@@ -12,12 +12,12 @@
 # Patterns to find package configuration files
 # package_paths: "**/"
 
-# List of application load paths
-<%= @load_paths_comment -%>
-<%= @load_paths_formatted %>
 # List of custom associations, if any
 # custom_associations:
 # - "cache_belongs_to"
 
-# Location of inflections file
-# inflections_file: "config/inflections.yml"
+# 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/graph.rb

@@ -2,7 +2,9 @@
 # frozen_string_literal: true
 
 module Packwerk
+  # A general implementation of a graph data structure with the ability to check for - and list - cycles.
   class Graph
+    # @param [Array<Array>] edges The edges of the graph; An edge being represented as an Array of two nodes.
     def initialize(*edges)
       @edges = edges.uniq
       @cycles = Set.new

data/lib/packwerk/node.rb

@@ -5,6 +5,7 @@ require "parser"
 require "parser/ast/node"
 
 module Packwerk
+  # Convenience methods for working with Parser::AST::Node nodes.
   module Node
     class TypeError < ArgumentError; end
     Location = Struct.new(:line, :column)
@@ -263,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

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
+  # Processes a single node in an abstract syntax tree (AST) using the provided checkers.
   class NodeProcessor
     extend T::Sig
 
@@ -9,35 +10,22 @@ module Packwerk
       params(
         reference_extractor: ReferenceExtractor,
         filename: String,
-        checkers: T::Array[Checker]
       ).void
     end
-    def initialize(reference_extractor:, filename:, checkers:)
+    def initialize(reference_extractor:, filename:)
       @reference_extractor = reference_extractor
       @filename = filename
-      @checkers = checkers
     end
 
-    sig { params(node: Parser::AST::Node, ancestors: T::Array[Parser::AST::Node]).returns(T::Array[Offense]) }
-    def call(node, ancestors)
-      return [] unless Node.method_call?(node) || Node.constant?(node)
-      reference = @reference_extractor.reference_from_node(node, ancestors: ancestors, file_path: @filename)
-      check_reference(reference, node)
+    sig do
+      params(
+        node: Parser::AST::Node,
+        ancestors: T::Array[Parser::AST::Node]
+      ).returns(T.nilable(UnresolvedReference))
     end
-
-    private
-
-    def check_reference(reference, node)
-      return [] unless reference
-      @checkers.each_with_object([]) do |checker, violations|
-        next unless checker.invalid_reference?(reference)
-        offense = Packwerk::ReferenceOffense.new(
-          location: Node.location(node),
-          reference: reference,
-          violation_type: checker.violation_type
-        )
-        violations << offense
-      end
+    def call(node, ancestors)
+      return unless Node.method_call?(node) || Node.constant?(node)
+      @reference_extractor.reference_from_node(node, ancestors: ancestors, file_path: @filename)
     end
   end
 end

data/lib/packwerk/node_processor_factory.rb

@@ -8,14 +8,12 @@ module Packwerk
     const :root_path, String
     const :context_provider, Packwerk::ConstantDiscovery
     const :constant_name_inspectors, T::Array[ConstantNameInspector]
-    const :checkers, T::Array[Checker]
 
     sig { params(filename: String, node: AST::Node).returns(NodeProcessor) }
     def for(filename:, node:)
       ::Packwerk::NodeProcessor.new(
         reference_extractor: reference_extractor(node: node),
         filename: filename,
-        checkers: checkers,
       )
     end
 
@@ -24,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

@@ -1,14 +1,19 @@
-# typed: false
+# typed: true
 # frozen_string_literal: true
 
 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
 
     def visit(node, ancestors:, result:)
-      result.concat(@node_processor.call(node, ancestors))
+      reference = @node_processor.call(node, ancestors)
+      result << reference if reference
 
       child_ancestors = [node] + ancestors
       Node.each_child(node) do |child|

data/lib/packwerk/package.rb

@@ -1,37 +1,51 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 module Packwerk
+  # The basic unit of modularity for packwerk; a folder that has been declared to define a package.
+  # The package contains all constants defined in files in this folder and all subfolders that are not packages
+  # themselves.
   class Package
+    extend T::Sig
     include Comparable
 
     ROOT_PACKAGE_NAME = "."
 
-    attr_reader :name, :dependencies
+    sig { returns(String) }
+    attr_reader :name
+    sig { returns(T::Array[String]) }
+    attr_reader :dependencies
 
+    sig { params(name: String, config: T.nilable(T.any(T::Hash[T.untyped, T.untyped], FalseClass))).void }
     def initialize(name:, config:)
       @name = name
-      @config = config || {}
-      @dependencies = Array(@config["dependencies"]).freeze
+      @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]))) }
     def enforce_privacy
       @config["enforce_privacy"]
     end
 
+    sig { returns(T::Boolean) }
     def enforce_dependencies?
       @config["enforce_dependencies"] == true
     end
 
+    sig { params(package: Package).returns(T::Boolean) }
     def dependency?(package)
       @dependencies.include?(package.name)
     end
 
+    sig { params(path: String).returns(T::Boolean) }
     def package_path?(path)
       return true if root?
       path.start_with?(@name)
     end
 
+    sig { returns(String) }
     def public_path
       @public_path ||= begin
         unprefixed_public_path = user_defined_public_path || "app/public/"
@@ -44,10 +58,12 @@ module Packwerk
       end
     end
 
+    sig { params(path: String).returns(T::Boolean) }
     def public_path?(path)
       path.start_with?(public_path)
     end
 
+    sig { returns(T.nilable(String)) }
     def user_defined_public_path
       return unless @config["public_path"]
       return @config["public_path"] if @config["public_path"].end_with?("/")
@@ -55,23 +71,28 @@ module Packwerk
       @config["public_path"] + "/"
     end
 
+    sig { params(other: T.untyped).returns(T.nilable(Integer)) }
     def <=>(other)
       return nil unless other.is_a?(self.class)
       name <=> other.name
     end
 
+    sig { params(other: T.untyped).returns(T::Boolean) }
     def eql?(other)
       self == other
     end
 
+    sig { returns(Integer) }
     def hash
       name.hash
     end
 
+    sig { returns(String) }
     def to_s
       name
     end
 
+    sig { returns(T::Boolean) }
     def root?
       @name == ROOT_PACKAGE_NAME
     end

data/lib/packwerk/package_set.rb

@@ -1,15 +1,25 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 require "pathname"
 
 module Packwerk
+  PathSpec = T.type_alias { T.any(String, T::Array[String]) }
+
+  # A set of {Packwerk::Package}s as well as methods to parse packages from the filesystem.
   class PackageSet
+    extend T::Sig
+    extend T::Generic
     include Enumerable
 
+    Elem = type_member(fixed: Package)
+
     PACKAGE_CONFIG_FILENAME = "package.yml"
 
     class << self
+      extend T::Sig
+
+      sig { params(root_path: String, package_pathspec: T.nilable(PathSpec)).returns(PackageSet) }
       def load_all_from(root_path, package_pathspec: nil)
         package_paths = package_paths(root_path, package_pathspec || "**")
 
@@ -23,8 +33,17 @@ module Packwerk
         new(packages)
       end
 
-      def package_paths(root_path, package_pathspec)
-        bundle_path_match = Bundler.bundle_path.join("**").to_s
+      sig do
+        params(
+          root_path: String,
+          package_pathspec: PathSpec,
+          exclude_pathspec: T.nilable(PathSpec)
+        ).returns(T::Array[Pathname])
+      end
+      def package_paths(root_path, package_pathspec, exclude_pathspec = [])
+        exclude_pathspec = Array(exclude_pathspec).dup
+          .push(Bundler.bundle_path.join("**").to_s)
+          .map { |glob| File.expand_path(glob) }
 
         glob_patterns = Array(package_pathspec).map do |pathspec|
           File.join(root_path, pathspec, PACKAGE_CONFIG_FILENAME)
@@ -32,34 +51,51 @@ module Packwerk
 
         Dir.glob(glob_patterns)
           .map { |path| Pathname.new(path).cleanpath }
-          .reject { |path| path.realpath.fnmatch(bundle_path_match) }
+          .reject { |path| exclude_path?(exclude_pathspec, path) }
       end
 
       private
 
+      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
+
+      sig { params(globs: T::Array[String], path: Pathname).returns(T::Boolean) }
+      def exclude_path?(globs, path)
+        globs.any? do |glob|
+          path.realpath.fnmatch(glob, File::FNM_EXTGLOB)
+        end
+      end
     end
 
+    sig { returns(T::Hash[String, Package]) }
+    attr_reader :packages
+
+    sig { params(packages: T::Array[Package]).void }
     def initialize(packages)
       # We want to match more specific paths first
       sorted_packages = packages.sort_by { |package| -package.name.length }
-      @packages = sorted_packages.each_with_object({}) { |package, hash| hash[package.name] = package }
+      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) }
     def each(&blk)
-      @packages.values.each(&blk)
+      packages.values.each(&blk)
     end
 
+    sig { params(name: String).returns(T.nilable(Package)) }
     def fetch(name)
-      @packages[name]
+      packages[name]
     end
 
+    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

@@ -4,6 +4,7 @@
 require "ast/node"
 
 module Packwerk
+  # A collection of constant definitions parsed from an Abstract Syntax Tree (AST).
   class ParsedConstantDefinitions
     def initialize(root_node:)
       @local_definitions = {}
@@ -24,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
@@ -52,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.rb

@@ -2,5 +2,6 @@
 # frozen_string_literal: true
 
 module Packwerk
-  Reference = Struct.new(:source_package, :relative_path, :constant)
+  # A reference from a file in one package to a constant that may be defined in a different package.
+  Reference = Struct.new(:source_package, :relative_path, :constant, :source_location)
 end

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

@@ -0,0 +1,21 @@
+# typed: true
+# frozen_string_literal: true
+
+module Packwerk
+  module ReferenceChecking
+    module Checkers
+      module Checker
+        extend T::Sig
+        extend T::Helpers
+
+        interface!
+
+        sig { returns(ViolationType).abstract }
+        def violation_type; end
+
+        sig { params(reference: Reference).returns(T::Boolean).abstract }
+        def invalid_reference?(reference); end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module ReferenceChecking
+    module Checkers
+      # Checks whether a given reference conforms to the configured graph of dependencies.
+      class DependencyChecker
+        extend T::Sig
+        include Checker
+
+        sig { override.returns(ViolationType) }
+        def violation_type
+          ViolationType::Dependency
+        end
+
+        sig do
+          override
+            .params(reference: Packwerk::Reference)
+            .returns(T::Boolean)
+        end
+        def invalid_reference?(reference)
+          return false unless reference.source_package
+          return false unless reference.source_package.enforce_dependencies?
+          return false if reference.source_package.dependency?(reference.constant.package)
+          true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module ReferenceChecking
+    module Checkers
+      # Checks whether a given reference references a private constant of another package.
+      class PrivacyChecker
+        extend T::Sig
+        include Checker
+
+        sig { override.returns(Packwerk::ViolationType) }
+        def violation_type
+          ViolationType::Privacy
+        end
+
+        sig do
+          override
+            .params(reference: Packwerk::Reference)
+            .returns(T::Boolean)
+        end
+        def invalid_reference?(reference)
+          return false if reference.constant.public?
+
+          privacy_option = reference.constant.package.enforce_privacy
+          return false if enforcement_disabled?(privacy_option)
+
+          return false unless privacy_option == true ||
+            explicitly_private_constant?(reference.constant, explicitly_private_constants: privacy_option)
+
+          true
+        end
+
+        private
+
+        sig do
+          params(
+            constant: ConstantDiscovery::ConstantContext,
+            explicitly_private_constants: T::Array[String]
+          ).returns(T::Boolean)
+        end
+        def explicitly_private_constant?(constant, explicitly_private_constants:)
+          explicitly_private_constants.include?(constant.name) ||
+            # nested constants
+            explicitly_private_constants.any? { |epc| constant.name.start_with?(epc + "::") }
+        end
+
+        sig do
+          params(privacy_option: T.nilable(T.any(T::Boolean, T::Array[String])))
+            .returns(T::Boolean)
+        end
+        def enforcement_disabled?(privacy_option)
+          [false, nil].include?(privacy_option)
+        end
+      end
+    end
+  end
+end

data/lib/packwerk/reference_checking/reference_checker.rb

@@ -0,0 +1,33 @@
+# typed: true
+# frozen_string_literal: true
+
+module Packwerk
+  module ReferenceChecking
+    class ReferenceChecker
+      extend T::Sig
+
+      def initialize(checkers)
+        @checkers = checkers
+      end
+
+      sig do
+        params(
+          reference: T.any(Packwerk::Reference, Packwerk::Offense)
+        ).returns(T::Array[Packwerk::Offense])
+      end
+      def call(reference)
+        return [reference] if reference.is_a?(Packwerk::Offense)
+
+        @checkers.each_with_object([]) do |checker, violations|
+          next unless checker.invalid_reference?(reference)
+          offense = Packwerk::ReferenceOffense.new(
+            location: reference.source_location,
+            reference: reference,
+            violation_type: checker.violation_type
+          )
+          violations << offense
+        end
+      end
+    end
+  end
+end

data/lib/packwerk/reference_extractor.rb

@@ -2,64 +2,111 @@
 # frozen_string_literal: true
 
 module Packwerk
-  # extracts a possible constant reference from a given AST node
+  # Extracts a possible constant reference from a given AST node.
   class ReferenceExtractor
     extend T::Sig
 
     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)
+      UnresolvedReference.new(
+        constant_name,
+        namespace_path,
+        relative_path,
+        location
+      )
     end
 
     def local_reference?(constant_name, name_location, namespace_path)

data/lib/packwerk/reference_offense.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
+  # An offense related to a {Packwerk::Reference}.
   class ReferenceOffense < Offense
     extend T::Sig
     extend T::Helpers