packwerk 1.2.0 → 1.4.0

data/lib/packwerk/cli.rb

@@ -1,7 +1,10 @@
 # typed: true
 # frozen_string_literal: true
 
+require "optparse"
+
 module Packwerk
+  # A command-line interface to Packwerk.
   class Cli
     extend T::Sig
 
@@ -10,6 +13,7 @@ module Packwerk
         configuration: T.nilable(Configuration),
         out: T.any(StringIO, IO),
         err_out: T.any(StringIO, IO),
+        environment: String,
         style: Packwerk::OutputStyle,
         offenses_formatter: T.nilable(Packwerk::OffensesFormatter)
       ).void
@@ -18,11 +22,13 @@ module Packwerk
       configuration: nil,
       out: $stdout,
       err_out: $stderr,
+      environment: "test",
       style: OutputStyles::Plain.new,
       offenses_formatter: nil
     )
       @out = out
       @err_out = err_out
+      @environment = environment
       @style = style
       @configuration = configuration || Configuration.from_path
       @progress_formatter = Formatters::ProgressFormatter.new(@out, style: style)
@@ -77,28 +83,12 @@ module Packwerk
     def init
       @out.puts("📦 Initializing Packwerk...")
 
-      application_validation = Packwerk::Generators::ApplicationValidation.generate(
-        for_rails_app: rails_app?,
-        root: @configuration.root_path,
-        out: @out
-      )
-
-      if application_validation
-        if rails_app?
-          # To run in the same space as the Rails process,
-          # in order to fetch load paths for the configuration generator
-          exec("bin/packwerk", "generate_configs")
-        else
-          generate_configurations = generate_configs
-        end
-      end
-
-      application_validation && generate_configurations
+      generate_configs
     end
 
     def generate_configs
       configuration_file = Packwerk::Generators::ConfigurationFile.generate(
-        load_paths: Packwerk::ApplicationLoadPaths.extract_relevant_paths,
+        load_paths: Packwerk::ApplicationLoadPaths.extract_relevant_paths(@configuration.root_path, @environment),
         root: @configuration.root_path,
         out: @out
       )
@@ -110,7 +100,7 @@ module Packwerk
       result = if success
         <<~EOS
 
-          🎉 Packwerk is ready to be used. You can start defining packages and run `packwerk check`.
+          🎉 Packwerk is ready to be used. You can start defining packages and run `bin/packwerk check`.
           For more information on how to use Packwerk, see: https://github.com/Shopify/packwerk/blob/main/USAGE.md
         EOS
       else
@@ -136,22 +126,23 @@ module Packwerk
       result.status
     end
 
-    def fetch_files_to_process(paths)
-      files = FilesForProcessing.fetch(paths: paths, configuration: @configuration)
+    def fetch_files_to_process(paths, ignore_nested_packages)
+      files = FilesForProcessing.fetch(
+        paths: paths,
+        ignore_nested_packages: ignore_nested_packages,
+        configuration: @configuration
+      )
       abort("No files found or given. "\
         "Specify files or check the include and exclude glob in the config file.") if files.empty?
       files
     end
 
     def validate(_paths)
-      warn("`packwerk validate` should be run within the application. "\
-        "Generate the bin script using `packwerk init` and"\
-        " use `bin/packwerk validate` instead.") unless defined?(::Rails)
-
       @progress_formatter.started_validation do
         checker = Packwerk::ApplicationValidator.new(
           config_file_path: @configuration.config_path,
-          configuration: @configuration
+          configuration: @configuration,
+          environment: @environment,
         )
         result = checker.check_all
 
@@ -171,18 +162,24 @@ module Packwerk
       end
     end
 
-    sig { returns(T::Boolean) }
-    def rails_app?
-      if File.exist?("config/application.rb") && File.exist?("bin/rails")
-        File.foreach("Gemfile").any? { |line| line.match?(/['"]rails['"]/) }
+    def parse_run(params)
+      paths = T.let([], T::Array[String])
+      ignore_nested_packages = nil
+
+      if params.any? { |p| p.include?("--packages") }
+        OptionParser.new do |parser|
+          parser.on("--packages=PACKAGESLIST", Array, "package names, comma separated") do |p|
+            paths = p
+          end
+        end.parse!(params)
+        ignore_nested_packages = true
       else
-        false
+        paths = params
+        ignore_nested_packages = false
       end
-    end
 
-    def parse_run(paths)
       ParseRun.new(
-        files: fetch_files_to_process(paths),
+        files: fetch_files_to_process(paths, ignore_nested_packages),
         configuration: @configuration,
         progress_formatter: @progress_formatter,
         offenses_formatter: @offenses_formatter

data/lib/packwerk/configuration.rb

@@ -45,7 +45,7 @@ module Packwerk
       @root_path = File.expand_path(root)
       @package_paths = configs["package_paths"] || "**/"
       @custom_associations = configs["custom_associations"] || []
-      @load_paths = configs["load_paths"] || []
+      @load_paths = (configs["load_paths"] || []).uniq
       @inflections_file = File.expand_path(configs["inflections_file"] || "config/inflections.yml", @root_path)
       @parallel = configs.key?("parallel") ? configs["parallel"] : true
 

data/lib/packwerk/const_node_inspector.rb

@@ -15,6 +15,9 @@ module Packwerk
     def constant_name_from_node(node, ancestors:)
       return nil unless Node.constant?(node)
       parent = ancestors.first
+
+      # Only process the root `const` node for namespaced constant references. For example, in the
+      # reference `Spam::Eggs::Thing`, we only process the const node associated with `Spam`.
       return nil unless root_constant?(parent)
 
       if parent && constant_in_module_or_class_definition?(node, parent: parent)
@@ -30,8 +33,6 @@ module Packwerk
 
     private
 
-    # Only process the root `const` node for namespaced constant references. For example, in the
-    # reference `Spam::Eggs::Thing`, we only process the const node associated with `Spam`.
     sig { params(parent: T.nilable(AST::Node)).returns(T::Boolean) }
     def root_constant?(parent)
       !(parent && Node.constant?(parent))

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:
           #
-          # bundle exec 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

@@ -15,7 +15,7 @@ module Packwerk
 
       sig { override.params(offenses: T::Array[T.nilable(Offense)]).returns(String) }
       def show_offenses(offenses)
-        return "No offenses detected 🎉" if offenses.empty?
+        return "No offenses detected" if offenses.empty?
 
         <<~EOS
           #{offenses_list(offenses)}
@@ -23,6 +23,15 @@ module Packwerk
         EOS
       end
 
+      sig { override.params(offense_collection: Packwerk::OffenseCollection).returns(String) }
+      def show_stale_violations(offense_collection)
+        if offense_collection.stale_violations?
+          "There were stale violations found, please run `packwerk update-deprecations`"
+        else
+          "No stale violations detected"
+        end
+      end
+
       private
 
       sig { params(offenses: T::Array[T.nilable(Offense)]).returns(String) }

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/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/inflector.rb

@@ -4,6 +4,7 @@
 require "active_support/inflector"
 
 module Packwerk
+  # A custom inflector used, among other things, to map between constant names and file names.
   class Inflector
     class << self
       extend T::Sig

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/offenses_formatter.rb

@@ -11,5 +11,9 @@ module Packwerk
     sig { abstract.params(offenses: T::Array[T.nilable(Offense)]).returns(String) }
     def show_offenses(offenses)
     end
+
+    sig { abstract.params(offense_collection: Packwerk::OffenseCollection).returns(String) }
+    def show_stale_violations(offense_collection)
+    end
   end
 end

data/lib/packwerk/package.rb

@@ -1,45 +1,69 @@
-# 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 ||= File.join(@name, user_defined_public_path || "app/public/")
+      @public_path = T.let(@public_path, T.nilable(String))
+      @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?("/")
@@ -47,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