packwerk 2.3.0 → 3.0.1

data/lib/packwerk/formatters/progress_formatter.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 require "benchmark"
@@ -14,37 +14,56 @@ module Packwerk
         @style = style
       end
 
-      def started(target_files)
-        files_size = target_files.size
-        files_string = "file".pluralize(files_size)
-        @out.puts("📦 Packwerk is inspecting #{files_size} #{files_string}")
-      end
-
+      sig { params(block: T.proc.void).void }
       def started_validation(&block)
-        @out.puts("📦 Packwerk is running validation...")
+        start_validation
 
         execution_time = Benchmark.realtime(&block)
         finished(execution_time)
+      end
 
-        @out.puts("✅ Packages are valid. Use `packwerk check` to run static checks.")
+      sig { params(target_files: FilesForProcessing::RelativeFileSet, block: T.proc.void).void }
+      def started_inspection(target_files, &block)
+        start_inspection(target_files)
+
+        execution_time = Benchmark.realtime(&block)
+        finished(execution_time)
       end
 
+      sig { void }
       def mark_as_inspected
         @out.print(".")
       end
 
+      sig { void }
       def mark_as_failed
         @out.print("#{@style.error}E#{@style.reset}")
       end
 
+      sig { void }
+      def interrupted
+        @out.puts
+        @out.puts("Manually interrupted. Violations caught so far are listed below:")
+      end
+
+      private
+
+      sig { params(execution_time: Float).void }
       def finished(execution_time)
         @out.puts
         @out.puts("📦 Finished in #{execution_time.round(2)} seconds")
       end
 
-      def interrupted
-        @out.puts
-        @out.puts("Manually interrupted. Violations caught so far are listed below:")
+      sig { void }
+      def start_validation
+        @out.puts("📦 Packwerk is running validation...")
+      end
+
+      sig { params(target_files: FilesForProcessing::RelativeFileSet).void }
+      def start_inspection(target_files)
+        files_size = target_files.size
+        files_string = "file".pluralize(files_size)
+        @out.puts("📦 Packwerk is inspecting #{files_size} #{files_string}")
       end
     end
   end

data/lib/packwerk/generators/configuration_file.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 require "erb"
@@ -11,6 +11,9 @@ module Packwerk
       CONFIGURATION_TEMPLATE_FILE_PATH = "templates/packwerk.yml.erb"
 
       class << self
+        extend T::Sig
+
+        sig { params(root: String, out: T.any(IO, StringIO)).returns(T::Boolean) }
         def generate(root:, out:)
           new(root: root, out: out).generate
         end
@@ -25,7 +28,7 @@ module Packwerk
       sig { returns(T::Boolean) }
       def generate
         @out.puts("📦 Generating Packwerk configuration file...")
-        default_config_path = File.join(@root, ::Packwerk::Configuration::DEFAULT_CONFIG_PATH)
+        default_config_path = File.join(@root, Configuration::DEFAULT_CONFIG_PATH)
 
         if File.exist?(default_config_path)
           @out.puts("⚠️  Packwerk configuration file already exists.")
@@ -40,10 +43,12 @@ module Packwerk
 
       private
 
+      sig { returns(String) }
       def render
         ERB.new(template, trim_mode: "-").result(binding)
       end
 
+      sig { returns(String) }
       def template
         template_file_path = File.join(__dir__, CONFIGURATION_TEMPLATE_FILE_PATH)
         File.read(template_file_path)

data/lib/packwerk/generators/root_package.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 module Packwerk
@@ -7,11 +7,15 @@ module Packwerk
       extend T::Sig
 
       class << self
+        extend T::Sig
+
+        sig { params(root: String, out: T.any(IO, StringIO)).returns(T::Boolean) }
         def generate(root:, out:)
           new(root: root, out: out).generate
         end
       end
 
+      sig { params(root: String, out: T.any(IO, StringIO)).void }
       def initialize(root:, out: $stdout)
         @root = root
         @out = out

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

@@ -5,16 +5,6 @@
 # Turn on dependency checks for this package
 enforce_dependencies: true
 
-# Turn on privacy checks for this package
-# enforcing privacy is often not useful for the root package, because it would require defining a public interface
-# for something that should only be a thin wrapper in the first place.
-# We recommend enabling this for any new packages you create to aid with encapsulation.
-enforce_privacy: false
-
-# By default the public path will be app/public/, however this may not suit all applications' architecture so
-# this allows you to modify what your package's public path is.
-# public_path: app/public/
-
 # A list of this package's dependencies
 # Note that packages in this list require their own `package.yml` file
 # dependencies:

data/lib/packwerk/graph.rb

@@ -4,8 +4,14 @@
 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)
+    extend T::Sig
+    sig do
+      params(
+        # The edges of the graph; An edge being represented as an Array of two nodes.
+        edges: T::Array[T::Array[T.any(String, Integer, NilClass)]]
+      ).void
+    end
+    def initialize(edges)
       @edges = edges.uniq
       @cycles = Set.new
       process
@@ -73,4 +79,6 @@ module Packwerk
       @cycles << cycle
     end
   end
+
+  private_constant :Graph
 end

data/lib/packwerk/node.rb

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
-  class Node
+  module Node
     Location = Struct.new(:line, :column)
   end
 end

data/lib/packwerk/node_helpers.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 require "parser"
@@ -59,11 +59,16 @@ module Packwerk
         end
       end
 
-      sig { params(node: AST::Node).returns(T.untyped) }
-      def each_child(node)
-        if block_given?
+      sig do
+        params(
+          node: AST::Node,
+          block: T.nilable(T.proc.params(arg0: Parser::AST::Node).void),
+        ).returns(T::Enumerable[AST::Node])
+      end
+      def each_child(node, &block)
+        if block
           node.children.each do |child|
-            yield child if child.is_a?(Parser::AST::Node)
+            yield(child) if child.is_a?(Parser::AST::Node)
           end
         else
           enum_for(:each_child, node)
@@ -181,9 +186,9 @@ module Packwerk
         end
       end
 
-      sig { params(node: Parser::AST::Node).returns(T.nilable(Node::Location)) }
+      sig { params(node: AST::Node).returns(T.nilable(Node::Location)) }
       def name_location(node)
-        location = node.location
+        location = T.cast(node, Parser::AST::Node).location
 
         if location.respond_to?(:name)
           name = location.name
@@ -332,4 +337,6 @@ module Packwerk
       end
     end
   end
+
+  private_constant :NodeHelpers
 end

data/lib/packwerk/node_processor.rb

@@ -29,4 +29,6 @@ module Packwerk
       @reference_extractor.reference_from_node(node, ancestors: ancestors, relative_file: @relative_file)
     end
   end
+
+  private_constant :NodeProcessor
 end

data/lib/packwerk/node_processor_factory.rb

@@ -6,12 +6,12 @@ module Packwerk
     extend T::Sig
 
     const :root_path, String
-    const :context_provider, Packwerk::ConstantDiscovery
+    const :context_provider, ConstantDiscovery
     const :constant_name_inspectors, T::Array[ConstantNameInspector]
 
     sig { params(relative_file: String, node: AST::Node).returns(NodeProcessor) }
     def for(relative_file:, node:)
-      ::Packwerk::NodeProcessor.new(
+      NodeProcessor.new(
         reference_extractor: reference_extractor(node: node),
         relative_file: relative_file,
       )
@@ -19,13 +19,15 @@ module Packwerk
 
     private
 
-    sig { params(node: AST::Node).returns(::Packwerk::ReferenceExtractor) }
+    sig { params(node: AST::Node).returns(ReferenceExtractor) }
     def reference_extractor(node:)
-      ::Packwerk::ReferenceExtractor.new(
+      ReferenceExtractor.new(
         constant_name_inspectors: constant_name_inspectors,
         root_node: node,
         root_path: root_path,
       )
     end
   end
+
+  private_constant :NodeProcessorFactory
 end

data/lib/packwerk/node_visitor.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 module Packwerk
@@ -11,6 +11,13 @@ module Packwerk
       @node_processor = node_processor
     end
 
+    sig do
+      params(
+        node: Parser::AST::Node,
+        ancestors: T::Array[Parser::AST::Node],
+        result: T::Array[UnresolvedReference],
+      ).void
+    end
     def visit(node, ancestors:, result:)
       reference = @node_processor.call(node, ancestors)
       result << reference if reference
@@ -21,4 +28,6 @@ module Packwerk
       end
     end
   end
+
+  private_constant :NodeVisitor
 end

data/lib/packwerk/offense_collection.rb

@@ -18,6 +18,7 @@ module Packwerk
       @root_path = root_path
       @package_todo = T.let(package_todo, T::Hash[Packwerk::Package, Packwerk::PackageTodo])
       @new_violations = T.let([], T::Array[Packwerk::ReferenceOffense])
+      @strict_mode_violations = T.let([], T::Array[Packwerk::ReferenceOffense])
       @errors = T.let([], T::Array[Packwerk::Offense])
     end
 
@@ -27,6 +28,9 @@ module Packwerk
     sig { returns(T::Array[Packwerk::Offense]) }
     attr_reader :errors
 
+    sig { returns(T::Array[Packwerk::ReferenceOffense]) }
+    attr_reader :strict_mode_violations
+
     sig do
       params(offense: Packwerk::Offense)
         .returns(T::Boolean)
@@ -35,7 +39,7 @@ module Packwerk
       return false unless offense.is_a?(ReferenceOffense)
 
       reference = offense.reference
-      package_todo_for(reference.source_package).listed?(reference, violation_type: offense.violation_type)
+      package_todo_for(reference.package).listed?(reference, violation_type: offense.violation_type)
     end
 
     sig do
@@ -46,9 +50,11 @@ module Packwerk
         @errors << offense
         return
       end
-      package_todo = package_todo_for(offense.reference.source_package)
-      unless package_todo.add_entries(offense.reference, offense.violation_type)
+
+      if !already_listed?(offense)
         new_violations << offense
+      elsif strict_mode_violation?(offense)
+        strict_mode_violations << offense
       end
     end
 
@@ -70,12 +76,19 @@ module Packwerk
       errors + new_violations
     end
 
-    sig { void }
-    def dump_package_todo_files
-      @package_todo.each_value(&:dump)
+    private
+
+    sig { params(offense: ReferenceOffense).returns(T::Boolean) }
+    def already_listed?(offense)
+      package_todo_for(offense.reference.package).add_entries(offense.reference,
+        offense.violation_type)
     end
 
-    private
+    sig { params(offense: ReferenceOffense).returns(T::Boolean) }
+    def strict_mode_violation?(offense)
+      checker = Checker.find(offense.violation_type)
+      checker.strict_mode_violation?(offense)
+    end
 
     sig { params(package_set: Packwerk::PackageSet).void }
     def cleanup_extra_package_todo_files(package_set)
@@ -89,6 +102,11 @@ module Packwerk
       end
     end
 
+    sig { void }
+    def dump_package_todo_files
+      @package_todo.each_value(&:dump)
+    end
+
     sig { params(package: Packwerk::Package).returns(Packwerk::PackageTodo) }
     def package_todo_for(package)
       @package_todo[package] ||= Packwerk::PackageTodo.new(
@@ -99,17 +117,7 @@ module Packwerk
 
     sig { params(package: Packwerk::Package).returns(String) }
     def package_todo_file_for(package)
-      if Pathname.new(@root_path).join(package.name, "deprecated_references.yml").exist?
-        warning = <<~WARNING.squish
-          DEPRECATION WARNING: `deprecated_references.yml` files have been renamed to `package_todo.yml`.
-          Run `packwerk update-todo` to rename files automatically.
-        WARNING
-
-        warn(warning)
-        File.join(@root_path, package.name, "deprecated_references.yml")
-      else
-        File.join(@root_path, package.name, "package_todo.yml")
-      end
+      File.join(@root_path, package.name, "package_todo.yml")
     end
   end
 end

data/lib/packwerk/offenses_formatter.rb

@@ -6,14 +6,71 @@ module Packwerk
     extend T::Sig
     extend T::Helpers
 
-    interface!
+    abstract!
+
+    class DuplicateFormatterError < StandardError
+      extend T::Sig
+
+      sig { params(identifier: String).void }
+      def initialize(identifier)
+        super("Cannot have multiple identifiers with the same key (`#{identifier}`)")
+      end
+    end
+
+    class << self
+      extend T::Sig
+
+      sig { params(base: Class).void }
+      def included(base)
+        @offenses_formatters ||= T.let(@offenses_formatters, T.nilable(T::Array[Class]))
+        @offenses_formatters ||= []
+        @offenses_formatters << base
+      end
+
+      sig { returns(T::Array[OffensesFormatter]) }
+      def all
+        T.unsafe(@offenses_formatters).map(&:new)
+      end
+
+      sig { params(identifier: String).returns(OffensesFormatter) }
+      def find(identifier)
+        formatter_by_identifier(identifier)
+      end
+
+      private
+
+      sig { params(name: String).returns(OffensesFormatter) }
+      def formatter_by_identifier(name)
+        @formatter_by_identifier ||= T.let(nil, T.nilable(T::Hash[String, T.nilable(OffensesFormatter)]))
+        @formatter_by_identifier ||= begin
+          index = T.let({}, T::Hash[String, T.nilable(OffensesFormatter)])
+          OffensesFormatter.all.each do |formatter|
+            identifier = formatter.identifier
+            raise DuplicateFormatterError, identifier if index.key?(identifier)
+
+            index[identifier] = formatter
+          end
+          T.let(index, T.nilable(T::Hash[String, T.nilable(OffensesFormatter)]))
+        end
+
+        T.must(T.must(@formatter_by_identifier)[name])
+      end
+    end
 
     sig { abstract.params(offenses: T::Array[T.nilable(Offense)]).returns(String) }
     def show_offenses(offenses)
     end
 
-    sig { abstract.params(offense_collection: Packwerk::OffenseCollection, for_files: T::Set[String]).returns(String) }
+    sig { abstract.params(offense_collection: OffenseCollection, for_files: T::Set[String]).returns(String) }
     def show_stale_violations(offense_collection, for_files)
     end
+
+    sig { abstract.returns(String) }
+    def identifier
+    end
+
+    sig { abstract.params(strict_mode_violations: T::Array[ReferenceOffense]).returns(String) }
+    def show_strict_mode_violations(strict_mode_violations)
+    end
   end
 end

data/lib/packwerk/package.rb

@@ -17,22 +17,20 @@ module Packwerk
     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:)
+    sig { returns(T::Hash[T.untyped, T.untyped]) }
+    attr_reader :config
+
+    sig { params(name: String, config: T.nilable(T::Hash[String, T.untyped])).void }
+    def initialize(name:, config: nil)
       @name = name
-      @config = T.let(config || {}, T::Hash[T.untyped, T.untyped])
+      @config = T.let(config || {}, T::Hash[String, 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
+      [true, "strict"].include?(@config["enforce_dependencies"])
     end
 
     sig { params(package: Package).returns(T::Boolean) }
@@ -47,32 +45,6 @@ module Packwerk
       path.start_with?(@name)
     end
 
-    sig { returns(String) }
-    def public_path
-      @public_path ||= begin
-        unprefixed_public_path = user_defined_public_path || "app/public/"
-
-        if root?
-          unprefixed_public_path
-        else
-          File.join(@name, unprefixed_public_path)
-        end
-      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?("/")
-
-      @config["public_path"] + "/"
-    end
-
     sig { params(other: T.untyped).returns(T.nilable(Integer)) }
     def <=>(other)
       return nil unless other.is_a?(self.class)

data/lib/packwerk/package_set.rb

@@ -26,7 +26,7 @@ module Packwerk
 
         packages = package_paths.map do |path|
           root_relative = path.dirname.relative_path_from(root_path)
-          Package.new(name: root_relative.to_s, config: YAML.load_file(path))
+          Package.new(name: root_relative.to_s, config: YAML.load_file(path, fallback: nil))
         end
 
         create_root_package_if_none_in(packages)

data/lib/packwerk/package_todo.rb

@@ -20,7 +20,7 @@ module Packwerk
     end
 
     sig do
-      params(reference: Packwerk::Reference, violation_type: ViolationType)
+      params(reference: Packwerk::Reference, violation_type: String)
         .returns(T::Boolean)
     end
     def listed?(reference, violation_type:)
@@ -30,16 +30,18 @@ module Packwerk
       violated_constant_in_file = violated_constants_found.fetch("files", []).include?(reference.relative_path)
       return false unless violated_constant_in_file
 
-      violated_constants_found.fetch("violations", []).include?(violation_type.serialize)
+      violated_constants_found.fetch("violations", []).include?(violation_type)
     end
 
-    sig { params(reference: Packwerk::Reference, violation_type: Packwerk::ViolationType).returns(T::Boolean) }
+    sig do
+      params(reference: Packwerk::Reference, violation_type: String).returns(T::Boolean)
+    end
     def add_entries(reference, violation_type)
       package_violations = @new_entries.fetch(reference.constant.package.name, {})
       entries_for_constant = package_violations[reference.constant.name] ||= {}
 
       entries_for_constant["violations"] ||= []
-      entries_for_constant["violations"] << violation_type.serialize
+      entries_for_constant["violations"] << violation_type
 
       entries_for_constant["files"] ||= []
       entries_for_constant["files"] << reference.relative_path.to_s
@@ -64,11 +66,17 @@ module Packwerk
           }
         end
 
-        return true if package_violations_for_files.empty?
+        # We `next false` because if we cannot find existing violations for `for_files` within
+        # the `package_todo.yml` file, then there are no violations that
+        # can be considered stale.
+        next false if package_violations_for_files.empty?
 
         package_violations_for_files.any? do |constant_name, entries_for_constant|
           new_entries_violation_types = @new_entries.dig(package, constant_name, "violations")
-          return true if new_entries_violation_types.nil?
+          # If there are no NEW entries that match the old entries `for_files`,
+          # @new_entries is from the list of violations we get when we check this file.
+          # If this list is empty, we also must have stale violations.
+          next true if new_entries_violation_types.nil?
 
           if entries_for_constant["violations"].all? { |type| new_entries_violation_types.include?(type) }
             stale_violations =
@@ -83,23 +91,20 @@ module Packwerk
 
     sig { void }
     def dump
-      delete_old_deprecated_references
-
       if @new_entries.empty?
         delete_if_exists
       else
         prepare_entries_for_dump
         message = <<~MESSAGE
-          # This file contains a list of dependencies that are not part of the long term plan for #{@package.name}.
-          # We should generally work to reduce this list, but not at the expense of actually getting work done.
+          # This file contains a list of dependencies that are not part of the long term plan for the
+          # '#{@package.name}' package.
+          # We should generally work to reduce this list over time.
           #
           # You can regenerate this file using the following command:
           #
-          # bin/packwerk update-todo #{@package.name}
+          # bin/packwerk update-todo
         MESSAGE
-        package_todo_filepath = File.join(File.dirname(@filepath), "package_todo.yml")
-
-        File.open(package_todo_filepath, "w") do |f|
+        File.open(@filepath, "w") do |f|
           f.write(message)
           f.write(@new_entries.to_yaml)
         end
@@ -113,12 +118,6 @@ module Packwerk
 
     private
 
-    sig { void }
-    def delete_old_deprecated_references
-      deprecated_references_filepath = File.join(File.dirname(@filepath), "deprecated_references.yml")
-      File.delete(deprecated_references_filepath) if File.exist?(deprecated_references_filepath)
-    end
-
     sig { returns(EntriesType) }
     def prepare_entries_for_dump
       @new_entries.each do |package_name, package_violations|