packwerk 1.3.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bd7c65bd8c7e2c9448f0c0ab3dffc69291c0a379d7da46b7deb7a70e87b805f
-  data.tar.gz: ddfeb4e7d17a5deba8ab1319897adefe77462d64f088e3ae8ddfbfa0ecefa1d0
+  metadata.gz: 5d150d89ede62e601246e2ff0290ecda4aab883a7c8b8be02feb86760ad26b72
+  data.tar.gz: 33b088b3387b8fdfe694967f20529fb8795dec8572dc9e036cb4979402f19c5b
 SHA512:
-  metadata.gz: 784b0938aae086fc90d362542b3b372fa235790f40983be1172c3563be4c82f13052642638447496043c94e68e72dcdb8adc344ee8336130e2130b92afb9bccc
-  data.tar.gz: e464eb8f88b8827cace5a7c38a4cf653d686bd19327e1b1123a6828d075be8919f9a73cbca57413a8ed859225525d9b64e57406b9d4b25ebac3f5b3c91703b03
+  metadata.gz: 102154447670b85dc4e0825dcdf1ec11cd0fd291ffc1c7230b98da2208b0a39c38d2c8726a33226aeea68082e16a24917db7ad3380c871b9b02b0d76c8ac69fc
+  data.tar.gz: 666e3745e9167028e5d3901d74400848c87c1b8a64a7487d3e4bfe13916e2902990633db7c448057b8106fd4b6b5c5de08c697c88151a305c92d34259266448f

data/Gemfile.lock

@@ -87,10 +87,11 @@ GIT
 PATH
   remote: .
   specs:
-    packwerk (1.3.2)
+    packwerk (1.4.0)
       activesupport (>= 5.2)
       ast
       better_html
+      bundler
       constant_resolver
       parallel
       parser
@@ -135,16 +136,16 @@ GEM
     marcel (1.0.0)
     method_source (1.0.0)
     mini_mime (1.0.3)
-    mini_portile2 (2.5.1)
+    mini_portile2 (2.6.1)
     minitest (5.14.4)
     minitest-focus (1.2.1)
       minitest (>= 4, < 6)
     mocha (1.12.0)
     nio4r (2.5.7)
-    nokogiri (1.11.5)
-      mini_portile2 (~> 2.5.0)
+    nokogiri (1.12.5)
+      mini_portile2 (~> 2.6.1)
       racc (~> 1.4)
-    nokogiri (1.11.5-x86_64-darwin)
+    nokogiri (1.12.5-x86_64-darwin)
       racc (~> 1.4)
     parallel (1.20.1)
     parlour (6.0.0)
@@ -157,6 +158,7 @@ GEM
     pry (0.14.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
+    psych (3.3.2)
     racc (1.5.2)
     rack (2.2.3)
     rack-test (1.1.0)
@@ -189,7 +191,7 @@ GEM
     rubocop-sorbet (0.6.1)
       rubocop
     ruby-progressbar (1.11.0)
-    smart_properties (1.15.0)
+    smart_properties (1.16.3)
     sorbet (0.5.6360)
       sorbet-static (= 0.5.6360)
     sorbet-runtime (0.5.6360)
@@ -237,13 +239,13 @@ PLATFORMS
   x86_64-darwin-20
 
 DEPENDENCIES
-  bundler
   byebug
   constant_resolver
   m
   minitest-focus
   mocha
   packwerk!
+  psych (~> 3)
   rails!
   rake
   rubocop-performance

data/README.md

@@ -47,7 +47,8 @@ Or install it yourself as:
 
     $ gem install packwerk
 
-3. Run `packwerk init` to generate the configuration files
+2. Run `bundle binstub packwerk` to generate the binstub
+3. Run `bin/packwerk init` to generate the configuration files
 
 ## Usage
 

data/TROUBLESHOOT.md

@@ -14,11 +14,11 @@ Packwerk can give feedback via continuous integration (CI) if you have it set up
 
 You can specify folders or packages in Packwerk commands for a shorter run time:
 
-     packwerk check components/your_package
+     bin/packwerk check components/your_package
 
-     packwerk update-deprecations components/your_package
+     bin/packwerk update-deprecations components/your_package
 
-_Note: You cannot specify folders or packages for `packwerk validate` because the command runs for the entire application._
+_Note: You cannot specify folders or packages for `bin/packwerk validate` because the command runs for the entire application._
 
 ![](static/packwerk_check_violation.gif)
 

data/USAGE.md

@@ -6,7 +6,9 @@
 * [What is a package?](#what-is-a-package)
   * [Package principles](#package-principles)
 * [Getting started](#getting-started)
-* [Setting up the configuration file](#setting-up-the-configuration-file)
+  * [Setting up Spring](#setting-up-spring)
+* [Configuring Packwerk](#configuring-packwerk)
+  * [Using a custom ERB parser](#using-a-custom-erb-parser)
   * [Inflections](#inflections)
 * [Validating the package system](#validating-the-package-system)
 * [Defining packages](#defining-packages)
@@ -42,9 +44,12 @@ The [package principles](https://en.wikipedia.org/wiki/Package_principles) page
 
 ## Getting started
 
-After including Packwerk in the Gemfile, you can generate the necessary files to get Packwerk running by executing:
+After including Packwerk in the Gemfile, you will first want to generate a binstub:
+You can do this by running `bundle binstub packwerk`, which will generate a [binstub](https://bundler.io/man/bundle-binstubs.1.html#DESCRIPTION) at `bin/packwerk`.
 
-    packwerk init
+Then, you can generate the necessary files to get Packwerk running by executing:
+
+    bin/packwerk init
 
 Here is a list of files generated:
 
@@ -56,7 +61,14 @@ Here is a list of files generated:
 
 After that, you may begin creating packages for your application. See [Defining packages](#Defining-packages)
 
-## Setting up the configuration file
+### Setting up Spring
+
+[Spring](https://github.com/rails/spring) is a preloader for Rails. Because `packwerk` loads `Rails`, it can be sped up dramatically by enabling spring.  Packwerk supports the usage of Spring.
+Firstly, spring needs to know about the packwerk spring command when spring is loading. To do that, add `require 'packwerk/spring_command'` to `config/spring.rb` in your application.
+Secondly, to enable Spring, first run `bin/spring binstub packwerk` which will "springify" the generated binstub.
+
+
+## Configuring Packwerk
 
 Packwerk reads from the `packwerk.yml` configuration file in the root directory. Packwerk will run with the default configuration if any of these settings are not specified.
 
@@ -134,7 +146,7 @@ Any new inflectors should be added to `config/inflections.yml`.
 
 There are some criteria that an application must meet in order to have a valid package system. These criteria include having a valid autoload path cache, package definition files, and application folder structure. The dependency graph within the package system also has to be acyclic.
 
-We recommend setting up the package system validation for your Rails application in a CI step (or through a test suite for Ruby projects) separate from `packwerk check`.
+We recommend setting up the package system validation for your Rails application in a CI step (or through a test suite for Ruby projects) separate from `bin/packwerk check`.
 
 Use the following command to validate the application:
 
@@ -231,13 +243,17 @@ After enforcing the boundary checks for a package, you may execute:
 
 Packwerk will check the entire codebase for any new or stale violations.
 
-You can also specify folders for a shorter run time:
+You can also specify folders for a shorter run time. When checking against folders all subfolders will be analyzed, irrespective of nested package boundaries.
 
     packwerk check components/your_package
 
+You can also specify packages for a shorter run time. When checking against packages any packages nested underneath the specified packages will not be checked. This can be helpful to test packages like the root package, which can have many nested packages.
+
+    packwerk check --packages=components/your_package,components/your_other_package
+
 ![](static/packwerk_check.gif)
 
-In order to keep the package system valid at each version of the application, we recommend running `packwerk check` in your CI pipeline.
+In order to keep the package system valid at each version of the application, we recommend running `bin/packwerk check` in your CI pipeline.
 
 See: [TROUBLESHOOT.md - Sample violations](TROUBLESHOOT.md#Sample-violations)
 
@@ -247,17 +263,17 @@ For existing codebases, packages are likely to have existing boundary violations
 
 If so, you will want to stop the bleeding and prevent more violations from occuring. The existing violations in the codebase can be recorded in a [deprecated references list](#Understanding_the_list_of_deprecated_references) by executing:
 
-    packwerk update-deprecations
+    bin/packwerk update-deprecations
 
-Similar to `packwerk check`, you may also run `packwerk update-deprecations` on folders or packages:
+Similar to `bin/packwerk check`, you may also run `bin/packwerk update-deprecations` on folders or packages:
 
-    packwerk update-deprecations components/your_package
+    bin/packwerk update-deprecations components/your_package
 
 ![](static/packwerk_update.gif)
 
 _Note: Changing dependencies or enabling dependencies will not require a full update of the codebase, only the package that changed. On the other hand, changing or enabling privacy will require a full update of the codebase._
 
-`packwerk update-deprecations` should only be run to record existing violations and to remove deprecated references that have been worked off. Running `packwerk update-deprecations` to resolve a violation should be the very last resort.
+`bin/packwerk update-deprecations` should only be run to record existing violations and to remove deprecated references that have been worked off. Running `bin/packwerk update-deprecations` to resolve a violation should be the very last resort.
 
 See: [TROUBLESHOOT.md - Troubleshooting violations](TROUBLESHOOT.md#Troubleshooting_violations)
 

data/exe/packwerk

@@ -3,4 +3,10 @@
 
 require "packwerk"
 
-Packwerk::Cli.new(style: Packwerk::OutputStyles::Coloured.new).run(ARGV.dup)
+# Needs to be run in test environment in order to have test helper paths available in the autoload paths
+ENV["RAILS_ENV"] = "test"
+
+# Command line arguments needs to be duplicated because spring modifies it
+packwerk_argv = ARGV.dup
+cli = Packwerk::Cli.new(style: Packwerk::OutputStyles::Coloured.new)
+cli.run(packwerk_argv)

data/lib/packwerk/application_load_paths.rb

@@ -4,6 +4,7 @@
 require "bundler"
 
 module Packwerk
+  # Extracts the load paths from the analyzed application so that we can map constant names to paths.
   module ApplicationLoadPaths
     class << self
       extend T::Sig

data/lib/packwerk/application_validator.rb

@@ -7,6 +7,8 @@ require "pathname"
 require "yaml"
 
 module Packwerk
+  # Checks the structure of the application and its packwerk configuration to make sure we can run a check and deliver
+  # correct results.
   class ApplicationValidator
     def initialize(config_file_path:, configuration:, environment:)
       @config_file_path = config_file_path
@@ -296,7 +298,7 @@ module Packwerk
     end
 
     def package_manifests(glob_pattern = package_glob)
-      PackageSet.package_paths(@configuration.root_path, glob_pattern)
+      PackageSet.package_paths(@configuration.root_path, glob_pattern, @configuration.exclude)
         .map { |f| File.realpath(f) }
     end
 

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
 
@@ -97,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
@@ -123,8 +126,12 @@ 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
@@ -155,9 +162,24 @@ module Packwerk
       end
     end
 
-    def parse_run(paths)
+    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
+        paths = params
+        ignore_nested_packages = false
+      end
+
       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/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
@@ -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,8 +101,9 @@ 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)
         load_yaml(@filepath)
       else
@@ -106,7 +111,7 @@ module Packwerk
       end
     end
 
-    sig { params(filepath: String).returns(Hash) }
+    sig { params(filepath: String).returns(ENTRIES_TYPE) }
     def load_yaml(filepath)
       YAML.load_file(filepath) || {}
     rescue Psych::Exception

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/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|