packwerk-extensions 0.0.8 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 661762b44e28e84ff3b70007bc039b6f767ddf638524f5a069a832e1f0d2fb34
-  data.tar.gz: a229b9432f95c10b211a411fee200e48721ff8d3c6b3fd1b745f8211cf58038a
+  metadata.gz: 1fb13125668a6ba704b97b2a91ffd7af5daf052b32732c7cea8a0f5c7da6bc75
+  data.tar.gz: a82b52e56c9a7b03bcc7b1963105feb3c99225f85a3159e8793dc9d0cf19285a
 SHA512:
-  metadata.gz: 32e5084af7d8e7cba4b743d0be13d29c1ea05b0c6e00ab7d0b9a38a229545093cf21f9e18da883987e487588f5bb7a47cc8728912332c9f295a42b03432bafc3
-  data.tar.gz: 01ff189cc3e645da3eeab3176351ebc0d23d274a9d20269f32733cdb2771169f365857bc946a66e5982c447887f81817fee047b82709e34115f18abaa53a0479
+  metadata.gz: 6a7bfa59d26c83525e1b87f0ba0d8270ff1043c42f85189668d8ec5047c534a2e249c082c6fb600ef3d3b1c8fba3351db59425ab07bd8ab372b4956aef6750f9
+  data.tar.gz: 9d2e225bf812bb133726667754d969e4bb2ff5c4a4ede918faf2cb9178349946f7041bc9a60b163c8a100e02d5cdacf31289ada63475af040a1432e2c3d9bcdf

data/README.md

@@ -1,12 +1,34 @@
 # packwerk-extensions
 
-`packwerk-extensions` is a home for checker extensions for packwerk.
+`packwerk-extensions` is a home for checker extensions for [packwerk](https://github.com/Shopify/packwerk) 3.
+
+Note that packwerk has not yet released packwerk 3. If you'd like to use `packwerk-extensions`, you'll need to point your `Gemfile` at the `packwerk` `main` branch:
+```ruby
+gem 'packwerk', github: 'Shopify/packwerk', branch: 'main'
+```
 
 Currently, it ships the following checkers to help improve the boundaries between packages. These checkers are:
 - A `privacy` checker that ensures other packages are using your package's public API
 - A `visibility` checker that allows packages to be private except to an explicit group of other packages.
 - An experimental `architecture` checker that allows packages to specify their "layer" and requires that each layer only communicate with layers below it.
 
+## Installation
+
+To register all checkers included in this gem, add the following to your `packwerk.yml`:
+
+```yaml
+require: packwerk-extensions
+```
+
+Alternatively, you can require individual checkers:
+
+```yaml
+require:
+  - packwerk/privacy/checker
+  - packwerk/visibility/checker
+  - packwerk/architecture/checker
+```
+
 ## Privacy Checker
 The privacy checker extension was originally extracted from [packwerk](https://github.com/Shopify/packwerk).
 
@@ -34,6 +56,9 @@ Example:
 public_path: my/custom/path/
 ```
 
+### Using specific private constants
+Sometimes it is desirable to only enforce privacy on a subset of constants in a package. You can do so by defining a `private_constants` list in your package.yml. Note that `enforce_privacy` must be set to `true` or `'strict'` for this to work.
+
 ### Package Privacy violation
 A constant that is private to its package has been referenced from outside of the package. Constants are declared private in their package’s `package.yml`.
 

data/lib/packwerk/architecture/checker.rb

@@ -2,6 +2,8 @@
 # frozen_string_literal: true
 
 require 'packwerk/architecture/layers'
+require 'packwerk/architecture/package'
+require 'packwerk/architecture/validator'
 
 module Packwerk
   module Architecture

data/lib/packwerk/architecture/validator.rb

@@ -91,20 +91,21 @@ module Packwerk
         params(config_file_path: String, setting: T.untyped).returns(Result)
       end
       def check_enforce_architecture_setting(config_file_path, setting)
+        activated_value = [true, 'strict'].include?(setting)
         valid_value = [true, nil, false, 'strict'].include?(setting)
         layers_set = layers.names.any?
-        if valid_value && layers_set
-          Result.new(ok: true)
-        elsif valid_value
+        if !valid_value
           Result.new(
             ok: false,
-            error_value: "Cannot set 'enforce_architecture' option in #{config_file_path.inspect} until `architectural_layers` have been specified in `packwerk.yml`"
+            error_value: "Invalid 'enforce_architecture' option in #{config_file_path.inspect}: #{setting.inspect}"
           )
-        else
+        elsif activated_value && !layers_set
           Result.new(
             ok: false,
-            error_value: "Invalid 'enforce_architecture' option in #{config_file_path.inspect}: #{setting.inspect}"
+            error_value: "Cannot set 'enforce_architecture' option in #{config_file_path.inspect} until `architectural_layers` have been specified in `packwerk.yml`"
           )
+        else
+          Result.new(ok: true)
         end
       end
     end

data/lib/packwerk/privacy/checker.rb

@@ -1,6 +1,9 @@
 # typed: strict
 # frozen_string_literal: true
 
+require 'packwerk/privacy/package'
+require 'packwerk/privacy/validator'
+
 module Packwerk
   module Privacy
     # Checks whether a given reference references a private constant of another package.
@@ -27,7 +30,9 @@ module Packwerk
         return false if privacy_package.public_path?(reference.constant.location)
 
         privacy_option = privacy_package.enforce_privacy
-        !enforcement_disabled?(privacy_option)
+        return false if enforcement_disabled?(privacy_option)
+
+        explicitly_private_constant?(reference.constant, explicitly_private_constants: privacy_package.private_constants)
       end
 
       sig do
@@ -60,6 +65,20 @@ module Packwerk
 
       private
 
+      sig do
+        params(
+          constant: ConstantContext,
+          explicitly_private_constants: T::Array[String]
+        ).returns(T::Boolean)
+      end
+      def explicitly_private_constant?(constant, explicitly_private_constants:)
+        return true if explicitly_private_constants.empty?
+
+        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, String, T::Array[String])))
           .returns(T::Boolean)

data/lib/packwerk/privacy/package.rb

@@ -8,7 +8,8 @@ module Packwerk
 
       const :public_path, String
       const :user_defined_public_path, T.nilable(String)
-      const :enforce_privacy, T.nilable(T.any(T::Boolean, String, T::Array[String]))
+      const :enforce_privacy, T.nilable(T.any(T::Boolean, String))
+      const :private_constants, T::Array[String]
 
       sig { params(path: String).returns(T::Boolean) }
       def public_path?(path)
@@ -23,7 +24,8 @@ module Packwerk
           Package.new(
             public_path: public_path_for(package),
             user_defined_public_path: user_defined_public_path(package),
-            enforce_privacy: package.config['enforce_privacy']
+            enforce_privacy: package.config['enforce_privacy'],
+            private_constants: package.config['private_constants'] || []
           )
         end
 

data/lib/packwerk/privacy/validator.rb

@@ -19,6 +19,8 @@ module Packwerk
           results << check_enforce_privacy_setting(config_file_path, setting)
         end
 
+        results += verify_private_constants_setting(package_set, configuration)
+
         public_path_settings = package_manifests_settings_for(configuration, 'public_path')
         public_path_settings.each do |config_file_path, setting|
           results << check_public_path(config_file_path, setting)
@@ -29,11 +31,49 @@ module Packwerk
 
       sig { override.returns(T::Array[String]) }
       def permitted_keys
-        %w[public_path enforce_privacy]
+        %w[public_path enforce_privacy private_constants]
       end
 
       private
 
+      sig { params(package_set: PackageSet, configuration: Configuration).returns(T::Array[Result]) }
+      def verify_private_constants_setting(package_set, configuration)
+        private_constants_setting = package_manifests_settings_for(configuration, 'private_constants')
+        results = T.let([], T::Array[Result])
+        resolver = ConstantResolver.new(
+          root_path: configuration.root_path,
+          load_paths: configuration.load_paths
+        )
+
+        private_constants_setting.each do |config_file_path, setting|
+          next if setting.nil?
+
+          unless setting.is_a?(Array)
+            results << Result.new(
+              ok: false,
+              error_value: "Invalid 'private_constants' setting: #{setting.inspect}"
+            )
+            next
+          end
+
+          constants = setting
+
+          results += assert_constants_can_be_loaded(constants, config_file_path)
+
+          constant_locations = constants.map { |c| [c, resolver.resolve(c)&.location] }
+
+          constant_locations.each do |name, location|
+            results << if location
+                         check_private_constant_location(configuration, package_set, name, location, config_file_path)
+                       else
+                         private_constant_unresolvable(name, config_file_path)
+                       end
+          end
+        end
+
+        results
+      end
+
       sig do
         params(config_file_path: String, setting: T.untyped).returns(Result)
       end
@@ -52,7 +92,7 @@ module Packwerk
         params(config_file_path: String, setting: T.untyped).returns(Result)
       end
       def check_enforce_privacy_setting(config_file_path, setting)
-        if [TrueClass, FalseClass, Array, NilClass].include?(setting.class) || setting == 'strict'
+        if [TrueClass, FalseClass, NilClass].include?(setting.class) || setting == 'strict'
           Result.new(ok: true)
         else
           Result.new(
@@ -61,6 +101,55 @@ module Packwerk
           )
         end
       end
+
+      sig do
+        params(configuration: Configuration, package_set: PackageSet, name: T.untyped, location: T.untyped,
+               config_file_path: T.untyped).returns(Result)
+      end
+      def check_private_constant_location(configuration, package_set, name, location, config_file_path)
+        declared_package = package_set.package_from_path(relative_path(configuration, config_file_path))
+        constant_package = package_set.package_from_path(location)
+
+        if constant_package == declared_package
+          Result.new(ok: true)
+        else
+          Result.new(
+            ok: false,
+            error_value: "'#{name}' is declared as private in the '#{declared_package}' package but appears to be " \
+                         "defined\nin the '#{constant_package}' package. Packwerk resolved it to #{location}."
+          )
+        end
+      end
+
+      sig { params(constants: T.untyped, config_file_path: String).returns(T::Array[Result]) }
+      def assert_constants_can_be_loaded(constants, config_file_path)
+        constants.map do |constant|
+          if constant.start_with?('::')
+            constant.try(&:constantize) && Result.new(ok: true)
+          else
+            error_value = "'#{constant}', listed in the 'private_constants' option " \
+                          "in #{config_file_path}, is invalid.\nPrivate constants need to be " \
+                          'prefixed with the top-level namespace operator `::`.'
+            Result.new(
+              ok: false,
+              error_value: error_value
+            )
+          end
+        end
+      end
+
+      sig { params(name: T.untyped, config_file_path: T.untyped).returns(Result) }
+      def private_constant_unresolvable(name, config_file_path)
+        explicit_filepath = "#{(name.start_with?('::') ? name[2..] : name).underscore}.rb"
+
+        Result.new(
+          ok: false,
+          error_value: "'#{name}', listed in #{config_file_path}, could not be resolved.\n" \
+                       "This is probably because it is an autovivified namespace - a namespace module that doesn't have a\n" \
+                       "file explicitly defining it. Packwerk currently doesn't support declaring autovivified namespaces as\n" \
+                       "private. Add a #{explicit_filepath} file to explicitly define the constant."
+        )
+      end
     end
   end
 end

data/lib/packwerk/visibility/checker.rb

@@ -1,6 +1,9 @@
 # typed: strict
 # frozen_string_literal: true
 
+require 'packwerk/visibility/package'
+require 'packwerk/visibility/validator'
+
 module Packwerk
   module Visibility
     # Checks whether a given reference references a constant from a package that does not permit visibility

data/lib/packwerk-extensions.rb

@@ -5,16 +5,8 @@ require 'sorbet-runtime'
 require 'packwerk'
 
 require 'packwerk/privacy/checker'
-require 'packwerk/privacy/package'
-require 'packwerk/privacy/validator'
-
 require 'packwerk/visibility/checker'
-require 'packwerk/visibility/package'
-require 'packwerk/visibility/validator'
-
 require 'packwerk/architecture/checker'
-require 'packwerk/architecture/package'
-require 'packwerk/architecture/validator'
 
 module Packwerk
   module Extensions

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: packwerk-extensions
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.1.0
 platform: ruby
 authors:
 - Gusto Engineers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-12-29 00:00:00.000000000 Z
+date: 2023-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: packwerk
@@ -25,19 +25,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 2.2.1
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 6.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 6.0.0
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement