packwerk 3.2.3 → 3.3.0

data/lib/packwerk/package_todo.rb

@@ -5,28 +5,21 @@ require "yaml"
 
 module Packwerk
   class PackageTodo
-    extend T::Sig
-
-    PackageName = T.type_alias { String }
-    ConstantName = T.type_alias { String }
-    FilePath = T.type_alias { String }
-    Entry = T.type_alias { T::Hash[ConstantName, T::Hash[ConstantName, T::Array[FilePath]]] }
-    Entries = T.type_alias do
-      T::Hash[PackageName, Entry]
-    end
+    #: type package_name = String
+    #: type constant_name = String
+    #: type file_path = String
+    #: type entry = Hash[constant_name, Hash[constant_name, Array[file_path]]]
+    #: type entries = Hash[package_name, entry]
 
-    sig { params(package: Packwerk::Package, path: String).void }
+    #: (Packwerk::Package package, String path) -> void
     def initialize(package, path)
       @package = package
       @path = path
-      @new_entries = T.let({}, Entries)
-      @old_entries = T.let(nil, T.nilable(Entries))
+      @new_entries = {} #: entries
+      @old_entries = nil #: entries?
     end
 
-    sig do
-      params(reference: Packwerk::Reference, violation_type: String)
-        .returns(T::Boolean)
-    end
+    #: (Packwerk::Reference reference, violation_type: String) -> bool
     def listed?(reference, violation_type:)
       violated_constants_found = old_entries.dig(reference.constant.package.name, reference.constant.name)
       return false unless violated_constants_found
@@ -37,9 +30,7 @@ module Packwerk
       violated_constants_found.fetch("violations", []).include?(violation_type)
     end
 
-    sig do
-      params(reference: Packwerk::Reference, violation_type: String).returns(T::Boolean)
-    end
+    #: (Packwerk::Reference reference, String violation_type) -> bool
     def add_entries(reference, violation_type)
       package_violations = new_entries.fetch(reference.constant.package.name, {})
       entries_for_constant = package_violations[reference.constant.name] ||= {}
@@ -54,7 +45,7 @@ module Packwerk
       listed?(reference, violation_type: violation_type)
     end
 
-    sig { params(for_files: T::Set[String]).returns(T::Boolean) }
+    #: (Set[String] for_files) -> bool
     def stale_violations?(for_files)
       prepare_entries_for_dump
 
@@ -71,7 +62,7 @@ module Packwerk
       end
     end
 
-    sig { void }
+    #: -> void
     def dump
       if new_entries.empty?
         delete_if_exists
@@ -93,24 +84,24 @@ module Packwerk
       end
     end
 
-    sig { void }
+    #: -> void
     def delete_if_exists
       File.delete(@path) if File.exist?(@path)
     end
 
     private
 
-    sig { returns(Entries) }
+    #: entries
     attr_reader(:new_entries)
 
-    sig { params(package: String).returns(T::Array[String]) }
+    #: (String package) -> Array[String]
     def deleted_files_for(package)
       old_files = old_entries.fetch(package, {}).values.flat_map { |violation| violation.fetch("files") }
       new_files = new_entries.fetch(package, {}).values.flat_map { |violation| violation.fetch("files") }
       old_files - new_files
     end
 
-    sig { params(package: String, violations: Entry).returns(T::Boolean) }
+    #: (String package, violations: entry) -> bool
     def stale_violation_for_package?(package, violations:)
       violations.any? do |constant_name, entries_for_constant|
         new_entries_violation_types = new_entries.dig(package, constant_name, "violations")
@@ -129,10 +120,10 @@ module Packwerk
       end
     end
 
-    sig { params(package_violations: Entry, files: T::Set[String]).returns(Entry) }
+    #: (entry package_violations, files: Set[String]) -> entry
     def package_violations_for(package_violations, files:)
       {}.tap do |package_violations_for_files|
-        package_violations_for_files = T.cast(package_violations_for_files, Entry)
+        package_violations_for_files = package_violations_for_files #: as entry
 
         package_violations.each do |constant_name, entries_for_constant|
           entries_for_files = files & entries_for_constant.fetch("files")
@@ -146,7 +137,7 @@ module Packwerk
       end
     end
 
-    sig { returns(Entries) }
+    #: -> entries
     def prepare_entries_for_dump
       new_entries.each do |package_name, package_violations|
         package_violations.each do |_, entries_for_constant|
@@ -159,12 +150,12 @@ module Packwerk
       @new_entries = new_entries.sort.to_h
     end
 
-    sig { returns(Entries) }
+    #: -> entries
     def old_entries
       @old_entries ||= load_yaml_file(@path)
     end
 
-    sig { params(path: String).returns(Entries) }
+    #: (String path) -> entries
     def load_yaml_file(path)
       File.exist?(path) && YAML.load_file(path) || {}
     rescue Psych::Exception

data/lib/packwerk/parse_run.rb

@@ -5,32 +5,15 @@ require "parallel"
 
 module Packwerk
   class ParseRun
-    extend T::Sig
+    #: type process_file_proc = ^(String path) -> Array[Offense]
 
-    ProcessFileProc = T.type_alias do
-      T.proc.params(path: String).returns(T::Array[Offense])
-    end
-
-    sig do
-      params(
-        relative_file_set: FilesForProcessing::RelativeFileSet,
-        parallel: T::Boolean,
-      ).void
-    end
+    #: (relative_file_set: FilesForProcessing::relative_file_set, parallel: bool) -> void
     def initialize(relative_file_set:, parallel:)
       @relative_file_set = relative_file_set
       @parallel = parallel
     end
 
-    sig do
-      params(
-        run_context: RunContext,
-        on_interrupt: T.nilable(T.proc.void),
-        block: T.nilable(T.proc.params(
-          offenses: T::Array[Packwerk::Offense],
-        ).void)
-      ).returns(T::Array[Offense])
-    end
+    #: (RunContext run_context, ?on_interrupt: (^-> void)?) ?{ (Array[Packwerk::Offense] offenses) -> void } -> Array[Offense]
     def find_offenses(run_context, on_interrupt: nil, &block)
       process_file_proc = process_file_proc(run_context, &block)
 
@@ -45,32 +28,22 @@ module Packwerk
 
     private
 
-    sig do
-      params(
-        run_context: RunContext,
-        block: T.nilable(T.proc.params(offenses: T::Array[Offense]).void)
-      ).returns(ProcessFileProc)
-    end
+    #: (RunContext run_context) ?{ (Array[Offense] offenses) -> void } -> process_file_proc
     def process_file_proc(run_context, &block)
       if block
-        T.let(proc do |relative_file|
+        proc do |relative_file|
           run_context.process_file(relative_file: relative_file).tap(&block)
-        end, ProcessFileProc)
+        end #: process_file_proc
       else
-        T.let(proc do |relative_file|
+        proc do |relative_file|
           run_context.process_file(relative_file: relative_file)
-        end, ProcessFileProc)
+        end #: process_file_proc
       end
     end
 
-    sig do
-      params(
-        on_interrupt: T.nilable(T.proc.void),
-        block: ProcessFileProc
-      ).returns(T::Array[Offense])
-    end
+    #: (?on_interrupt: (^-> void)?) { (?) -> untyped } -> Array[Offense]
     def serial_find_offenses(on_interrupt: nil, &block)
-      all_offenses = T.let([], T::Array[Offense])
+      all_offenses = [] #: Array[Offense]
       begin
         @relative_file_set.each do |relative_file|
           offenses = yield(relative_file)

data/lib/packwerk/parsed_constant_definitions.rb

@@ -6,13 +6,9 @@ require "ast/node"
 module Packwerk
   # A collection of constant definitions parsed from an Abstract Syntax Tree (AST).
   class ParsedConstantDefinitions
-    extend T::Sig
-
     class << self
-      extend T::Sig
-
       # What fully qualified constants can this constant refer to in this context?
-      sig { params(constant_name: String, namespace_path: T::Array[T.nilable(String)]).returns(T::Array[String]) }
+      #: (String constant_name, namespace_path: Array[String?]) -> Array[String]
       def reference_qualifications(constant_name, namespace_path:)
         return [constant_name] if constant_name.start_with?("::")
 
@@ -26,20 +22,14 @@ module Packwerk
       end
     end
 
-    sig { params(root_node: T.nilable(AST::Node)).void }
+    #: (root_node: AST::Node?) -> void
     def initialize(root_node:)
-      @local_definitions = T.let({}, T::Hash[String, T.nilable(Node::Location)])
+      @local_definitions = {} #: Hash[String, Node::Location?]
 
       collect_local_definitions_from_root(root_node) if root_node
     end
 
-    sig do
-      params(
-        constant_name: String,
-        location: T.nilable(Node::Location),
-        namespace_path: T::Array[String],
-      ).returns(T::Boolean)
-    end
+    #: (String constant_name, ?location: Node::Location?, ?namespace_path: Array[String]) -> bool
     def local_reference?(constant_name, location: nil, namespace_path: [])
       qualifications = self.class.reference_qualifications(constant_name, namespace_path: namespace_path)
 
@@ -51,14 +41,16 @@ module Packwerk
 
     private
 
-    sig { params(node: AST::Node, current_namespace_path: T::Array[T.nilable(String)]).void }
+    #: (AST::Node node, ?Array[String?] current_namespace_path) -> void
     def collect_local_definitions_from_root(node, current_namespace_path = [])
       if NodeHelpers.constant_assignment?(node)
         add_definition(NodeHelpers.constant_name(node), current_namespace_path, NodeHelpers.name_location(node))
       elsif NodeHelpers.module_name_from_definition(node)
         # handle compact constant nesting (e.g. "module Sales::Order")
-        tempnode = T.let(node, T.nilable(AST::Node))
-        while (tempnode = NodeHelpers.each_child(T.must(tempnode)).find { |node| NodeHelpers.constant?(node) })
+        tempnode = node #: AST::Node?
+        while (tempnode = NodeHelpers.each_child(
+            tempnode #: as !nil
+          ).find { |node| NodeHelpers.constant?(node) })
           add_definition(NodeHelpers.constant_name(tempnode), current_namespace_path,
             NodeHelpers.name_location(tempnode))
         end
@@ -69,13 +61,7 @@ module Packwerk
       NodeHelpers.each_child(node) { |child| collect_local_definitions_from_root(child, current_namespace_path) }
     end
 
-    sig do
-      params(
-        constant_name: String,
-        current_namespace_path: T::Array[T.nilable(String)],
-        location: T.nilable(Node::Location),
-      ).void
-    end
+    #: (String constant_name, Array[String?] current_namespace_path, Node::Location? location) -> void
     def add_definition(constant_name, current_namespace_path, location)
       resolved_constant = [""].concat(current_namespace_path).push(constant_name).join("::")
 

data/lib/packwerk/parsers/erb.rb

@@ -9,24 +9,23 @@ require "parser/source/buffer"
 module Packwerk
   module Parsers
     class Erb
-      extend T::Sig
-
       include ParserInterface
 
-      sig { params(parser_class: T.untyped, ruby_parser: Ruby).void }
+      #: (?parser_class: untyped, ?ruby_parser: Ruby) -> void
       def initialize(parser_class: BetterHtml::Parser, ruby_parser: Ruby.new)
-        @parser_class = T.let(parser_class, T.class_of(BetterHtml::Parser))
+        @parser_class = parser_class #: singleton(BetterHtml::Parser)
         @ruby_parser = ruby_parser
       end
 
-      sig { override.params(io: T.any(IO, StringIO), file_path: String).returns(T.untyped) }
+      # @override
+      #: (io: (IO | StringIO), ?file_path: String) -> untyped
       def call(io:, file_path: "<unknown>")
         buffer = Parser::Source::Buffer.new(file_path)
         buffer.source = io.read
         parse_buffer(buffer, file_path: file_path)
       end
 
-      sig { params(buffer: Parser::Source::Buffer, file_path: String).returns(T.nilable(AST::Node)) }
+      #: (Parser::Source::Buffer buffer, file_path: String) -> AST::Node?
       def parse_buffer(buffer, file_path:)
         parser = @parser_class.new(buffer, template_language: :html)
         to_ruby_ast(parser.ast, file_path)
@@ -40,18 +39,15 @@ module Packwerk
 
       private
 
-      sig do
-        params(
-          erb_ast: T.all(::AST::Node, Object),
-          file_path: String
-        ).returns(T.nilable(::AST::Node))
-      end
+      #: ((::AST::Node & Object) erb_ast, String file_path) -> ::AST::Node?
       def to_ruby_ast(erb_ast, file_path)
         # Note that we're not using the source location (line/column) at the moment, but if we did
         # care about that, we'd need to tweak this to insert empty lines and spaces so that things
         # line up with the ERB file
-        code_pieces = T.must(code_nodes(erb_ast)).map do |node|
-          T.cast(node, ::AST::Node).children.first
+        nodes = code_nodes(erb_ast) #: as !nil
+        code_pieces = nodes.map do |node|
+          node #: as ::AST::Node
+            .children.first
         end
 
         @ruby_parser.call(
@@ -60,14 +56,7 @@ module Packwerk
         )
       end
 
-      sig do
-        params(
-          node: T.any(::AST::Node, String, NilClass),
-          block: T.nilable(T.proc.params(arg0: ::AST::Node).void),
-        ).returns(
-          T.any(T::Enumerator[::AST::Node], T::Array[String], NilClass)
-        )
-      end
+      #: ((::AST::Node | String)? node) ?{ (::AST::Node arg0) -> void } -> (Enumerator[::AST::Node] | Array[String])?
       def code_nodes(node, &block)
         return enum_for(:code_nodes, node) unless block
         return unless node.is_a?(::AST::Node)

data/lib/packwerk/parsers/factory.rb

@@ -6,7 +6,6 @@ require "singleton"
 module Packwerk
   module Parsers
     class Factory
-      extend T::Sig
       include Singleton
 
       RUBY_REGEX = %r{
@@ -20,29 +19,30 @@ module Packwerk
       ERB_REGEX = /\.erb\Z/
       private_constant :ERB_REGEX
 
-      sig { void }
+      #: -> void
       def initialize
-        @ruby_parser = T.let(nil, T.nilable(ParserInterface))
-        @erb_parser = T.let(nil, T.nilable(ParserInterface))
-        @erb_parser_class = T.let(nil, T.nilable(T::Class[T.anything]))
+        @ruby_parser = nil #: ParserInterface?
+        @erb_parser = nil #: ParserInterface?
+        @erb_parser_class = nil #: Class[top]?
       end
 
-      sig { params(path: String).returns(T.nilable(ParserInterface)) }
+      #: (String path) -> ParserInterface?
       def for_path(path)
         case path
         when RUBY_REGEX
           @ruby_parser ||= Ruby.new
         when ERB_REGEX
-          @erb_parser ||= T.unsafe(erb_parser_class).new
+          erb_parser_class_ = erb_parser_class #: as untyped
+          @erb_parser ||= erb_parser_class_.new
         end
       end
 
-      sig { returns(T::Class[T.anything]) }
+      #: -> Class[top]
       def erb_parser_class
         @erb_parser_class ||= Erb
       end
 
-      sig { params(klass: T.nilable(T::Class[T.anything])).void }
+      #: (Class[top]? klass) -> void
       def erb_parser_class=(klass)
         @erb_parser_class = klass
         @erb_parser = nil

data/lib/packwerk/parsers/parser_interface.rb

@@ -3,17 +3,12 @@
 
 module Packwerk
   module Parsers
+    # @requires_ancestor: Kernel
+    # @interface
     module ParserInterface
-      extend T::Helpers
-      extend T::Sig
-
-      requires_ancestor { Kernel }
-
-      interface!
-
-      sig { abstract.params(io: T.any(IO, StringIO), file_path: String).returns(T.untyped) }
-      def call(io:, file_path:)
-      end
+      # @abstract
+      #: (io: (IO | StringIO), file_path: String) -> untyped
+      def call(io:, file_path:) = raise NotImplementedError, "Abstract method called"
     end
   end
 end

data/lib/packwerk/parsers/ruby.rb

@@ -7,14 +7,10 @@ require "prism"
 module Packwerk
   module Parsers
     class Ruby
-      extend T::Sig
-
       include ParserInterface
 
       class RaiseExceptionsParser < Prism::Translation::Parser
-        extend T::Sig
-
-        sig { params(builder: T.untyped).void }
+        #: (untyped builder) -> void
         def initialize(builder)
           super(builder)
           super.diagnostics.all_errors_are_fatal = true
@@ -22,28 +18,27 @@ module Packwerk
 
         private
 
-        sig { params(error: Prism::ParseError).returns(T::Boolean) }
+        #: (Prism::ParseError error) -> bool
         def valid_error?(error)
           error.type != :invalid_yield
         end
       end
 
-      class TolerateInvalidUtf8Builder < Parser::Builders::Default
-        extend T::Sig
-
-        sig { params(token: T.untyped).returns(T.untyped) }
+      class TolerateInvalidUtf8Builder < Prism::Translation::Parser::Builder
+        #: (untyped token) -> untyped
         def string_value(token)
           value(token)
         end
       end
 
-      sig { params(parser_class: T.untyped).void }
+      #: (?parser_class: untyped) -> void
       def initialize(parser_class: RaiseExceptionsParser)
-        @builder = T.let(TolerateInvalidUtf8Builder.new, Object)
-        @parser_class = T.let(parser_class, T.class_of(RaiseExceptionsParser))
+        @builder = TolerateInvalidUtf8Builder.new #: Object
+        @parser_class = parser_class #: singleton(RaiseExceptionsParser)
       end
 
-      sig { override.params(io: T.any(IO, StringIO), file_path: String).returns(T.nilable(Parser::AST::Node)) }
+      # @override
+      #: (io: (IO | StringIO), ?file_path: String) -> Parser::AST::Node?
       def call(io:, file_path: "<unknown>")
         buffer = Parser::Source::Buffer.new(file_path)
         buffer.source = io.read

data/lib/packwerk/parsers.rb

@@ -11,12 +11,10 @@ module Packwerk
     class ParseResult < Offense; end
 
     class ParseError < StandardError
-      extend T::Sig
-
-      sig { returns(ParseResult) }
+      #: ParseResult
       attr_reader(:result)
 
-      sig { params(result: ParseResult).void }
+      #: (ParseResult result) -> void
       def initialize(result)
         super(result.message)
         @result = result

data/lib/packwerk/rails_load_paths.rb

@@ -9,9 +9,7 @@ module Packwerk
   # Extracts the load paths from the analyzed application so that we can map constant names to paths.
   module RailsLoadPaths
     class << self
-      extend T::Sig
-
-      sig { params(root: String, environment: String).returns(T::Hash[String, Module]) }
+      #: (String root, environment: String) -> Hash[String, Module[top]]
       def for(root, environment:)
         require_application(root, environment)
         all_paths = extract_application_autoload_paths
@@ -22,17 +20,14 @@ module Packwerk
 
       private
 
-      sig { returns(T::Hash[String, Module]) }
+      #: -> Hash[String, Module[top]]
       def extract_application_autoload_paths
         Rails.autoloaders.inject({}) do |h, loader|
           h.merge(loader.dirs(namespaces: true))
         end
       end
 
-      sig do
-        params(all_paths: T::Hash[String, Module], bundle_path: Pathname, rails_root: Pathname)
-          .returns(T::Hash[Pathname, Module])
-      end
+      #: (Hash[String, Module[top]] all_paths, ?bundle_path: Pathname, ?rails_root: Pathname) -> Hash[Pathname, Module[top]]
       def filter_relevant_paths(all_paths, bundle_path: Bundler.bundle_path, rails_root: Rails.root)
         bundle_path_match = bundle_path.join("**")
         rails_root_match = rails_root.join("**")
@@ -43,12 +38,12 @@ module Packwerk
           .reject { |path| path.fnmatch(bundle_path_match.to_s) } # reject paths from vendored gems
       end
 
-      sig { params(load_paths: T::Hash[Pathname, Module], rails_root: Pathname).returns(T::Hash[String, Module]) }
+      #: (Hash[Pathname, Module[top]] load_paths, ?rails_root: Pathname) -> Hash[String, Module[top]]
       def relative_path_strings(load_paths, rails_root: Rails.root)
         load_paths.transform_keys { |path| Pathname.new(path).relative_path_from(rails_root).to_s }
       end
 
-      sig { params(root: String, environment: String).void }
+      #: (String root, String environment) -> void
       def require_application(root, environment)
         environment_file = "#{root}/config/environment"
 
@@ -61,7 +56,7 @@ module Packwerk
         end
       end
 
-      sig { params(paths: T::Hash[T.untyped, Module]).void }
+      #: (Hash[untyped, Module[top]] paths) -> void
       def assert_load_paths_present(paths)
         if paths.empty?
           raise <<~EOS

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

@@ -6,21 +6,18 @@ module Packwerk
     module Checkers
       # Checks whether a given reference conforms to the configured graph of dependencies.
       class DependencyChecker
-        extend T::Sig
         include Checker
 
-        VIOLATION_TYPE = T.let("dependency", String)
+        VIOLATION_TYPE = "dependency" #: String
 
-        sig { override.returns(String) }
+        # @override
+        #: -> String
         def violation_type
           VIOLATION_TYPE
         end
 
-        sig do
-          override
-            .params(reference: Packwerk::Reference)
-            .returns(T::Boolean)
-        end
+        # @override
+        #: (Packwerk::Reference reference) -> bool
         def invalid_reference?(reference)
           return false unless reference.package.enforce_dependencies?
           return false if reference.package.dependency?(reference.constant.package)
@@ -28,11 +25,8 @@ module Packwerk
           true
         end
 
-        sig do
-          override
-            .params(reference: Packwerk::Reference)
-            .returns(String)
-        end
+        # @override
+        #: (Packwerk::Reference reference) -> String
         def message(reference)
           const_name = reference.constant.name
           const_package = reference.constant.package
@@ -46,7 +40,8 @@ module Packwerk
           EOS
         end
 
-        sig { override.params(offense: ReferenceOffense).returns(T::Boolean) }
+        # @override
+        #: (ReferenceOffense offense) -> bool
         def strict_mode_violation?(offense)
           referencing_package = offense.reference.package
           referencing_package.config["enforce_dependencies"] == "strict"
@@ -54,7 +49,7 @@ module Packwerk
 
         private
 
-        sig { params(reference: Reference).returns(String) }
+        #: (Reference reference) -> String
         def standard_help_message(reference)
           standard_message = <<~EOS
             Inference details: this is a reference to #{reference.constant.name} which seems to be defined in #{reference.constant.location}.

data/lib/packwerk/reference_checking/reference_checker.rb

@@ -4,18 +4,12 @@
 module Packwerk
   module ReferenceChecking
     class ReferenceChecker
-      extend T::Sig
-
-      sig { params(checkers: T::Array[Checker]).void }
+      #: (Array[Checker] checkers) -> void
       def initialize(checkers)
         @checkers = checkers
       end
 
-      sig do
-        params(
-          reference: Reference
-        ).returns(T::Array[Packwerk::Offense])
-      end
+      #: (Reference reference) -> Array[Packwerk::Offense]
       def call(reference)
         @checkers.each_with_object([]) do |checker, violations|
           next unless checker.invalid_reference?(reference)