packwerk 1.3.0 → 2.0.0

data/lib/packwerk/constant_name_inspector.rb

@@ -4,7 +4,7 @@
 require "ast"
 
 module Packwerk
-  # An interface describing some object that can extract a constant name from an AST node
+  # An interface describing an object that can extract a constant name from an AST node.
   module ConstantNameInspector
     extend T::Sig
     extend T::Helpers

data/lib/packwerk/deprecated_references.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 require "yaml"
@@ -7,11 +7,15 @@ module Packwerk
   class DeprecatedReferences
     extend T::Sig
 
+    ENTRIES_TYPE = T.type_alias do
+      T::Hash[String, T.untyped]
+    end
+
     sig { params(package: Packwerk::Package, filepath: String).void }
     def initialize(package, filepath)
       @package = package
       @filepath = filepath
-      @new_entries = {}
+      @new_entries = T.let({}, ENTRIES_TYPE)
     end
 
     sig do
@@ -53,7 +57,7 @@ module Packwerk
           if entries_for_file["violations"].all? { |type| new_entries_violation_types.include?(type) }
             stale_violations =
               entries_for_file["files"] - Array(@new_entries.dig(package, constant_name, "files"))
-            stale_violations.present?
+            stale_violations.any?
           else
             return true
           end
@@ -73,7 +77,7 @@ module Packwerk
           #
           # You can regenerate this file using the following command:
           #
-          # packwerk update-deprecations #{@package.name}
+          # bin/packwerk update-deprecations #{@package.name}
         MESSAGE
         File.open(@filepath, "w") do |f|
           f.write(message)
@@ -84,7 +88,7 @@ module Packwerk
 
     private
 
-    sig { returns(Hash) }
+    sig { returns(ENTRIES_TYPE) }
     def prepare_entries_for_dump
       @new_entries.each do |package_name, package_violations|
         package_violations.each do |_, entries_for_file|
@@ -97,13 +101,21 @@ module Packwerk
       @new_entries = @new_entries.sort.to_h
     end
 
-    sig { returns(Hash) }
+    sig { returns(ENTRIES_TYPE) }
     def deprecated_references
+      @deprecated_references ||= T.let(@deprecated_references, T.nilable(ENTRIES_TYPE))
       @deprecated_references ||= if File.exist?(@filepath)
-        YAML.load_file(@filepath) || {}
+        load_yaml(@filepath)
       else
         {}
       end
     end
+
+    sig { params(filepath: String).returns(ENTRIES_TYPE) }
+    def load_yaml(filepath)
+      YAML.load_file(filepath) || {}
+    rescue Psych::Exception
+      {}
+    end
   end
 end

data/lib/packwerk/file_processor.rb

@@ -1,10 +1,12 @@
-# typed: false
+# typed: true
 # frozen_string_literal: true
 
 require "ast/node"
 
 module Packwerk
   class FileProcessor
+    extend T::Sig
+
     class UnknownFileTypeResult < Offense
       def initialize(file:)
         super(file: file, message: "unknown file type")
@@ -16,24 +18,47 @@ module Packwerk
       @parser_factory = parser_factory || Packwerk::Parsers::Factory.instance
     end
 
+    sig do
+      params(file_path: String).returns(
+        T::Array[
+          T.any(
+            Packwerk::Reference,
+            Packwerk::Offense,
+          )
+        ]
+      )
+    end
     def call(file_path)
-      parser = @parser_factory.for_path(file_path)
-      return [UnknownFileTypeResult.new(file: file_path)] if parser.nil?
+      return [UnknownFileTypeResult.new(file: file_path)] if parser_for(file_path).nil?
 
-      node = File.open(file_path, "r", external_encoding: Encoding::UTF_8) do |file|
-        parser.call(io: file, file_path: file_path)
-      rescue Parsers::ParseError => e
-        return [e.result]
-      end
+      node = parse_into_ast(file_path)
+      return [] unless node
+
+      references_from_ast(node, file_path)
+    rescue Parsers::ParseError => e
+      [e.result]
+    end
+
+    private
 
-      result = []
-      if node
-        node_processor = @node_processor_factory.for(filename: file_path, node: node)
-        node_visitor = Packwerk::NodeVisitor.new(node_processor: node_processor)
+    def references_from_ast(node, file_path)
+      references = []
 
-        node_visitor.visit(node, ancestors: [], result: result)
+      node_processor = @node_processor_factory.for(filename: file_path, node: node)
+      node_visitor = Packwerk::NodeVisitor.new(node_processor: node_processor)
+      node_visitor.visit(node, ancestors: [], result: references)
+
+      references
+    end
+
+    def parse_into_ast(file_path)
+      File.open(file_path, "r", nil, external_encoding: Encoding::UTF_8) do |file|
+        parser_for(file_path).call(io: file, file_path: file_path)
       end
-      result
+    end
+
+    def parser_for(file_path)
+      @parser_factory.for_path(file_path)
     end
   end
 end

data/lib/packwerk/files_for_processing.rb

@@ -4,14 +4,15 @@
 module Packwerk
   class FilesForProcessing
     class << self
-      def fetch(paths:, configuration:)
-        new(paths, configuration).files
+      def fetch(paths:, configuration:, ignore_nested_packages: false)
+        new(paths, configuration, ignore_nested_packages).files
       end
     end
 
-    def initialize(paths, configuration)
+    def initialize(paths, configuration, ignore_nested_packages)
       @paths = paths
       @configuration = configuration
+      @ignore_nested_packages = ignore_nested_packages
     end
 
     def files
@@ -43,11 +44,21 @@ module Packwerk
         File.expand_path(glob, @configuration.root_path)
       end
 
-      Dir.glob([File.join(path, "**", "*")]).select do |file_path|
+      files = Dir.glob([File.join(path, "**", "*")]).select do |file_path|
         absolute_includes.any? do |pattern|
           File.fnmatch?(pattern, file_path, File::FNM_EXTGLOB)
         end
       end
+
+      if @ignore_nested_packages
+        nested_packages_paths = Dir.glob(File.join(path, "*", "**", "package.yml"))
+        nested_packages_globs = nested_packages_paths.map { |npp| npp.gsub("package.yml", "**/*") }
+        nested_packages_globs.each do |glob|
+          files -= Dir.glob(glob)
+        end
+      end
+
+      files
     end
 
     def configured_included_files

data/lib/packwerk/formatters/offenses_formatter.rb

@@ -44,7 +44,7 @@ module Packwerk
 
       sig { params(offenses: T::Array[T.nilable(Offense)]).returns(String) }
       def offenses_summary(offenses)
-        offenses_string = Inflector.default.pluralize("offense", offenses.length)
+        offenses_string = "offense".pluralize(offenses.length)
         "#{offenses.length} #{offenses_string} detected"
       end
     end

data/lib/packwerk/formatters/progress_formatter.rb

@@ -16,7 +16,7 @@ module Packwerk
 
       def started(target_files)
         files_size = target_files.size
-        files_string = Inflector.default.pluralize("file", files_size)
+        files_string = "file".pluralize(files_size)
         @out.puts("📦 Packwerk is inspecting #{files_size} #{files_string}")
       end
 

data/lib/packwerk/generators/configuration_file.rb

@@ -11,18 +11,15 @@ module Packwerk
       CONFIGURATION_TEMPLATE_FILE_PATH = "templates/packwerk.yml.erb"
 
       class << self
-        def generate(load_paths:, root:, out:)
-          new(load_paths: load_paths, root: root, out: out).generate
+        def generate(root:, out:)
+          new(root: root, out: out).generate
         end
       end
 
-      sig { params(load_paths: T::Array[String], root: String, out: T.any(StringIO, IO)).void }
-      def initialize(load_paths:, root:, out: $stdout)
-        @load_paths = load_paths
+      sig { params(root: String, out: T.any(StringIO, IO)).void }
+      def initialize(root:, out: $stdout)
         @root = root
         @out = out
-
-        set_template_variables
       end
 
       sig { returns(T::Boolean) }
@@ -43,18 +40,6 @@ module Packwerk
 
       private
 
-      def set_template_variables
-        @load_paths_formatted = if @load_paths.empty?
-          "# load_paths:\n# - 'app/models'\n"
-        else
-          @load_paths.map { |path| "- #{path}\n" }.join
-        end
-
-        @load_paths_comment = unless @load_paths.empty?
-          "# These load paths were auto generated by Packwerk.\nload_paths:\n"
-        end
-      end
-
       def render
         ERB.new(template, trim_mode: "-").result(binding)
       end

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

@@ -1,5 +1,5 @@
 # This file represents the root package of the application
-# Please validate the configuration using `bin/packwerk validate` (for Rails applications) or running the auto generated
+# Please validate the configuration using `packwerk validate` (for Rails applications) or running the auto generated
 # test case (for non-Rails projects). You can then use `packwerk check` to check your code.
 
 # Turn on dependency checks for this package

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

@@ -12,12 +12,6 @@
 # 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"

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 AST nodes.
   module Node
     class TypeError < ArgumentError; end
     Location = Struct.new(:line, :column)

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(Packwerk::Reference))
     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
 

data/lib/packwerk/node_visitor.rb

@@ -1,14 +1,16 @@
-# 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
     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,38 +1,52 @@
-# 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])
     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 = T.let(@public_path, T.nilable(String))
       @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,50 @@ 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])
     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) }
+      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 = {}

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