packwerk 1.3.2 → 1.4.0

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

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

@@ -0,0 +1,58 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module ReferenceChecking
+    module Checkers
+      # Checks whether a given reference references a private constant of another package.
+      class PrivacyChecker
+        extend T::Sig
+        include Checker
+
+        sig { override.returns(Packwerk::ViolationType) }
+        def violation_type
+          ViolationType::Privacy
+        end
+
+        sig do
+          override
+            .params(reference: Packwerk::Reference)
+            .returns(T::Boolean)
+        end
+        def invalid_reference?(reference)
+          return false if reference.constant.public?
+
+          privacy_option = reference.constant.package.enforce_privacy
+          return false if enforcement_disabled?(privacy_option)
+
+          return false unless privacy_option == true ||
+            explicitly_private_constant?(reference.constant, explicitly_private_constants: privacy_option)
+
+          true
+        end
+
+        private
+
+        sig do
+          params(
+            constant: ConstantDiscovery::ConstantContext,
+            explicitly_private_constants: T::Array[String]
+          ).returns(T::Boolean)
+        end
+        def explicitly_private_constant?(constant, explicitly_private_constants:)
+          explicitly_private_constants.include?(constant.name) ||
+            # nested constants
+            explicitly_private_constants.any? { |epc| constant.name.start_with?(epc + "::") }
+        end
+
+        sig do
+          params(privacy_option: T.nilable(T.any(T::Boolean, T::Array[String])))
+            .returns(T::Boolean)
+        end
+        def enforcement_disabled?(privacy_option)
+          [false, nil].include?(privacy_option)
+        end
+      end
+    end
+  end
+end

data/lib/packwerk/reference_checking/reference_checker.rb

@@ -0,0 +1,33 @@
+# typed: true
+# frozen_string_literal: true
+
+module Packwerk
+  module ReferenceChecking
+    class ReferenceChecker
+      extend T::Sig
+
+      def initialize(checkers)
+        @checkers = checkers
+      end
+
+      sig do
+        params(
+          reference: T.any(Packwerk::Reference, Packwerk::Offense)
+        ).returns(T::Array[Packwerk::Offense])
+      end
+      def call(reference)
+        return [reference] if reference.is_a?(Packwerk::Offense)
+
+        @checkers.each_with_object([]) do |checker, violations|
+          next unless checker.invalid_reference?(reference)
+          offense = Packwerk::ReferenceOffense.new(
+            location: reference.source_location,
+            reference: reference,
+            violation_type: checker.violation_type
+          )
+          violations << offense
+        end
+      end
+    end
+  end
+end

data/lib/packwerk/reference_extractor.rb

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
-  # extracts a possible constant reference from a given AST node
+  # Extracts a possible constant reference from a given AST node.
   class ReferenceExtractor
     extend T::Sig
 
@@ -59,7 +59,7 @@ module Packwerk
 
       return if source_package == constant.package
 
-      Reference.new(source_package, relative_path, constant)
+      Reference.new(source_package, relative_path, constant, Node.location(node))
     end
 
     def local_reference?(constant_name, name_location, namespace_path)

data/lib/packwerk/reference_offense.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
+  # An offense related to a {Packwerk::Reference}.
   class ReferenceOffense < Offense
     extend T::Sig
     extend T::Helpers

data/lib/packwerk/run_context.rb

@@ -4,6 +4,7 @@
 require "constant_resolver"
 
 module Packwerk
+  # Holds the context of a Packwerk run across multiple files.
   class RunContext
     extend T::Sig
 
@@ -17,8 +18,8 @@ module Packwerk
     )
 
     DEFAULT_CHECKERS = [
-      ::Packwerk::DependencyChecker,
-      ::Packwerk::PrivacyChecker,
+      ::Packwerk::ReferenceChecking::Checkers::DependencyChecker,
+      ::Packwerk::ReferenceChecking::Checkers::PrivacyChecker,
     ]
 
     class << self
@@ -50,9 +51,12 @@ module Packwerk
       @checker_classes = checker_classes
     end
 
-    sig { params(file: String).returns(T::Array[T.nilable(::Packwerk::Offense)]) }
+    sig { params(file: String).returns(T::Array[Packwerk::Offense]) }
     def process_file(file:)
-      file_processor.call(file)
+      references = file_processor.call(file)
+
+      reference_checker = ReferenceChecking::ReferenceChecker.new(checkers)
+      references.flat_map { |reference| reference_checker.call(reference) }
     end
 
     private
@@ -66,7 +70,6 @@ module Packwerk
     def node_processor_factory
       NodeProcessorFactory.new(
         context_provider: context_provider,
-        checkers: checkers,
         root_path: root_path,
         constant_name_inspectors: constant_name_inspectors
       )
@@ -94,7 +97,7 @@ module Packwerk
       ::Packwerk::PackageSet.load_all_from(root_path, package_pathspec: package_paths)
     end
 
-    sig { returns(T::Array[Checker]) }
+    sig { returns(T::Array[ReferenceChecking::Checkers::Checker]) }
     def checkers
       checker_classes.map(&:new)
     end

data/lib/packwerk/sanity_checker.rb

@@ -1,4 +1,4 @@
-# typed: false
+# typed: strict
 # frozen_string_literal: true
 
 module Packwerk

data/lib/packwerk/spring_command.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# typed: false
+
+require "spring/commands"
+
+module Packwerk
+  class SpringCommand
+    def env(*)
+      # Packwerk needs to run in a test environment, which has a set of autoload paths that are
+      # often a superset of the dev/prod paths (for example, test/support/helpers)
+      "test"
+    end
+
+    def exec_name
+      "packwerk"
+    end
+
+    def gem_name
+      "packwerk"
+    end
+
+    def call
+      load(Gem.bin_path(gem_name, exec_name))
+    end
+  end
+
+  Spring.register_command("packwerk", SpringCommand.new)
+end

data/lib/packwerk/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Packwerk
-  VERSION = "1.3.2"
+  VERSION = "1.4.0"
 end

data/lib/packwerk/violation_type.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 module Packwerk

data/lib/packwerk.rb

@@ -12,13 +12,11 @@ module Packwerk
   autoload :ApplicationValidator
   autoload :AssociationInspector
   autoload :OffenseCollection
-  autoload :Checker
   autoload :Cli
   autoload :Configuration
   autoload :ConstantDiscovery
   autoload :ConstantNameInspector
   autoload :ConstNodeInspector
-  autoload :DependencyChecker
   autoload :DeprecatedReferences
   autoload :FileProcessor
   autoload :FilesForProcessing
@@ -36,7 +34,6 @@ module Packwerk
   autoload :ParsedConstantDefinitions
   autoload :Parsers
   autoload :ParseRun
-  autoload :PrivacyChecker
   autoload :Reference
   autoload :ReferenceExtractor
   autoload :ReferenceOffense
@@ -77,4 +74,18 @@ module Packwerk
     autoload :InflectionsFile
     autoload :RootPackage
   end
+
+  module ReferenceChecking
+    extend ActiveSupport::Autoload
+
+    autoload :ReferenceChecker
+
+    module Checkers
+      extend ActiveSupport::Autoload
+
+      autoload :Checker
+      autoload :DependencyChecker
+      autoload :PrivacyChecker
+    end
+  end
 end

data/packwerk.gemspec

@@ -44,11 +44,13 @@ Gem::Specification.new do |spec|
   spec.add_dependency("constant_resolver")
   spec.add_dependency("parallel")
   spec.add_dependency("sorbet-runtime")
+  spec.add_dependency("bundler")
 
-  spec.add_development_dependency("bundler")
   spec.add_development_dependency("rake")
   spec.add_development_dependency("sorbet")
   spec.add_development_dependency("m")
+  # https://github.com/ruby/psych/pull/487
+  spec.add_development_dependency("psych", "~> 3")
 
   # For Ruby parsing
   spec.add_dependency("ast")

data/service.yml

@@ -1,3 +1 @@
 classification: library
-slack_channels:
-- core-stewardship

data/sorbet/rbi/gems/psych@3.3.2.rbi

@@ -0,0 +1,24 @@
+# typed: true
+
+# DO NOT EDIT MANUALLY
+# This is an autogenerated file for types exported from the `psych` gem.
+# Please instead update this file by running `bin/tapioca gem psych`.
+
+::RUBY19 = T.let(T.unsafe(nil), TrueClass)
+
+class Object < ::BasicObject
+  include ::ActiveSupport::ToJsonWithActiveSupportEncoder
+  include ::Kernel
+  include ::JSON::Ext::Generator::GeneratorMethods::Object
+  include ::ActiveSupport::Tryable
+  include ::Minitest::Expectations
+  include ::Mocha::ParameterMatchers::InstanceMethods
+  include ::Mocha::Inspect::ObjectMethods
+  include ::Mocha::ObjectMethods
+
+  def to_yaml(options = T.unsafe(nil)); end
+
+  class << self
+    def yaml_tag(url); end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: packwerk
 version: !ruby/object:Gem::Version
-  version: 1.3.2
+  version: 1.4.0
 platform: ruby
 authors:
 - Shopify Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-09-01 00:00:00.000000000 Z
+date: 2021-11-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -73,7 +73,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -122,6 +122,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: psych
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: ast
   requirement: !ruby/object:Gem::Requirement
@@ -206,13 +220,11 @@ files:
 - lib/packwerk/application_load_paths.rb
 - lib/packwerk/application_validator.rb
 - lib/packwerk/association_inspector.rb
-- lib/packwerk/checker.rb
 - lib/packwerk/cli.rb
 - lib/packwerk/configuration.rb
 - lib/packwerk/const_node_inspector.rb
 - lib/packwerk/constant_discovery.rb
 - lib/packwerk/constant_name_inspector.rb
-- lib/packwerk/dependency_checker.rb
 - lib/packwerk/deprecated_references.rb
 - lib/packwerk/file_processor.rb
 - lib/packwerk/files_for_processing.rb
@@ -246,13 +258,17 @@ files:
 - lib/packwerk/parsers/erb.rb
 - lib/packwerk/parsers/factory.rb
 - lib/packwerk/parsers/ruby.rb
-- lib/packwerk/privacy_checker.rb
 - lib/packwerk/reference.rb
+- lib/packwerk/reference_checking/checkers/checker.rb
+- lib/packwerk/reference_checking/checkers/dependency_checker.rb
+- lib/packwerk/reference_checking/checkers/privacy_checker.rb
+- lib/packwerk/reference_checking/reference_checker.rb
 - lib/packwerk/reference_extractor.rb
 - lib/packwerk/reference_offense.rb
 - lib/packwerk/result.rb
 - lib/packwerk/run_context.rb
 - lib/packwerk/sanity_checker.rb
+- lib/packwerk/spring_command.rb
 - lib/packwerk/version.rb
 - lib/packwerk/violation_type.rb
 - library.yml
@@ -301,6 +317,7 @@ files:
 - sorbet/rbi/gems/parlour@6.0.0.rbi
 - sorbet/rbi/gems/parser@3.0.0.0.rbi
 - sorbet/rbi/gems/pry@0.14.0.rbi
+- sorbet/rbi/gems/psych@3.3.2.rbi
 - sorbet/rbi/gems/racc@1.5.2.rbi
 - sorbet/rbi/gems/rack-test@1.1.0.rbi
 - sorbet/rbi/gems/rack@2.2.3.rbi

data/lib/packwerk/checker.rb

@@ -1,17 +0,0 @@
-# typed: true
-# frozen_string_literal: true
-
-module Packwerk
-  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