packwerk-extensions 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15205fb6e29f594b5bfea27a6c2ef0488fa1ec2b2d6ae5265bfa906f7bac49a9
-  data.tar.gz: 6e795da44e384491a129e496a8541284317d0c523db59d431731119529535bbb
+  metadata.gz: 077e4a805c3061339f9c18e26d1768bbe3c3966e9e4c958b078ba1bcd0292c07
+  data.tar.gz: c292cb8cb900a9746d20e426a94ca89fc2a55cea542662812cb14f450466ae55
 SHA512:
-  metadata.gz: da2182b6b67511413dc606f943303130a955ba87f92e6798543a995eb94dc5577b1f1951decbb23751ce4c08535b361fc91778ebc6cea357d62f3860d4081e94
-  data.tar.gz: ee4701f2cc1ecf037823ffa7abe0cce8fa8d5bb2c61dcf587b85ab4331611968f7dfad84439a141479341c38f5a8a326e4b76c1b3040fa3672429c483a39a52c
+  metadata.gz: 601a651716181f5da48a302a7dd3b9a5eb3d46fa81a13ebd7138602aef8c11576344d724a2907b7bb950161ba11f0bb2a68207a9338de4b4e780c569320e8900
+  data.tar.gz: 288a0af58508deebdc3904a4a716ff933c837f4ca1cf840ece8ef8f4509936dfc6839fa7737e0f6d5805a007a00803dcafde59054a8e4089a11228a1d4b2486e

data/README.md

@@ -5,7 +5,8 @@
 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.
+- A `folder_visibility` checker that allows packages to their sibling packs and parent pack (to be used in an application that uses folder packs)
+- An `architecture` checker that allows packages to specify their "layer" and requires that each layer only communicate with layers below it.
 
 ## Installation
 
@@ -24,6 +25,7 @@ Alternatively, you can require individual checkers:
 require:
   - packwerk/privacy/checker
   - packwerk/visibility/checker
+  - packwerk/folder_visibility/checker
   - packwerk/architecture/checker
 ```
 
@@ -87,6 +89,30 @@ visible_to:
   - components/other_package
 ```
 
+## Folder-Visibility Checker
+The folder visibility checker can be used to allow a package to be private to their sibling packs and parent packs and will create todos if used by any other package.
+
+To enforce visibility for your package, set `enforce_folder_visibility` to `true` on your pack.
+
+```yaml
+# components/merchandising/package.yml
+enforce_folder_visibility: true
+```
+
+Here is an example of paths and whether their use of `packs/b/packs/e` is OK or not, assuming that protects itself via `enforce_folder_visibility`
+
+```
+.                         OK (parent of parent)
+packs/a                   VIOLATION
+packs/b                   OK (parent)
+packs/b/packs/d           OK (sibling)
+packs/b/packs/e           ENFORCE_NESTED_VISIBILITY: TRUE
+packs/b/packs/e/packs/f   VIOLATION
+packs/b/packs/e/packs/g   VIOLATION
+packs/b/packs/h           OK (sibling)
+packs/c                   VIOLATION
+```
+
 ## Architecture Checker
 The architecture checker can be used to enforce constraints on what can depend on what.
 
@@ -105,3 +131,19 @@ layer: utility
 ```
 
 Now this pack can only depend on other utility packages.
+
+
+## Contributing
+
+Got another checker you would like to add? Add it to this repo!
+
+Please ensure these commands pass for you locally:
+
+```
+bundle
+srb tc
+bin/rubocop
+bin/rake test
+```
+
+Then, submit a PR!

data/lib/packwerk/folder_visibility/checker.rb

@@ -0,0 +1,93 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'packwerk/folder_visibility/package'
+require 'packwerk/folder_visibility/validator'
+
+module Packwerk
+  module FolderVisibility
+    class Checker
+      extend T::Sig
+      include Packwerk::Checker
+
+      VIOLATION_TYPE = T.let('folder_visibility', String)
+
+      sig { override.returns(String) }
+      def violation_type
+        VIOLATION_TYPE
+      end
+
+      sig do
+        override
+          .params(reference: Packwerk::Reference)
+          .returns(T::Boolean)
+      end
+      def invalid_reference?(reference)
+        referencing_package = reference.package
+        referenced_package = reference.constant.package
+
+        return false if enforcement_disabled?(Package.from(referenced_package).enforce_folder_visibility)
+
+        # the root pack is parent folder of all packs, so we short-circuit this here
+        referencing_package_is_root_pack = referencing_package.name == '.'
+        return false if referencing_package_is_root_pack
+
+        packages_are_sibling_folders = Pathname.new(referenced_package.name).dirname == Pathname.new(referencing_package.name).dirname
+        return false if packages_are_sibling_folders
+
+        referencing_package_is_parent_folder = Pathname.new(referenced_package.name).to_s.start_with?(referencing_package.name)
+        return false if referencing_package_is_parent_folder
+
+        true
+      end
+
+      sig do
+        override
+          .params(listed_offense: Packwerk::ReferenceOffense)
+          .returns(T::Boolean)
+      end
+      def strict_mode_violation?(listed_offense)
+        publishing_package = listed_offense.reference.constant.package
+        publishing_package.config['enforce_folder_visibility'] == 'strict'
+      end
+
+      sig do
+        override
+          .params(reference: Packwerk::Reference)
+          .returns(String)
+      end
+      def message(reference)
+        source_desc = "'#{reference.package}'"
+
+        message = <<~MESSAGE
+          Folder Visibility violation: '#{reference.constant.name}' belongs to '#{reference.constant.package}', which is not visible to #{source_desc} as it is not a sibling pack or parent pack.
+          Is there a different package to use instead, or should '#{reference.constant.package}' also be visible to #{source_desc}?
+
+          #{standard_help_message(reference)}
+        MESSAGE
+
+        message.chomp
+      end
+
+      private
+
+      sig do
+        params(visibility_option: T.nilable(T.any(T::Boolean, String)))
+          .returns(T::Boolean)
+      end
+      def enforcement_disabled?(visibility_option)
+        [false, nil].include?(visibility_option)
+      end
+
+      sig { params(reference: Reference).returns(String) }
+      def standard_help_message(reference)
+        standard_message = <<~MESSAGE.chomp
+          Inference details: this is a reference to #{reference.constant.name} which seems to be defined in #{reference.constant.location}.
+          To receive help interpreting or resolving this error message, see: https://github.com/Shopify/packwerk/blob/main/TROUBLESHOOT.md#Troubleshooting-violations
+        MESSAGE
+
+        standard_message.chomp
+      end
+    end
+  end
+end

data/lib/packwerk/folder_visibility/package.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module FolderVisibility
+    class Package < T::Struct
+      extend T::Sig
+
+      const :enforce_folder_visibility, T.nilable(T.any(T::Boolean, String))
+
+      class << self
+        extend T::Sig
+
+        sig { params(package: ::Packwerk::Package).returns(Package) }
+        def from(package)
+          Package.new(
+            enforce_folder_visibility: package.config['enforce_folder_visibility']
+          )
+        end
+      end
+    end
+  end
+end

data/lib/packwerk/folder_visibility/validator.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module FolderVisibility
+    class Validator
+      extend T::Sig
+      include Packwerk::Validator
+
+      Result = Packwerk::Validator::Result
+
+      sig { override.params(package_set: PackageSet, configuration: Configuration).returns(Result) }
+      def call(package_set, configuration)
+        results = T.let([], T::Array[Result])
+
+        package_manifests_settings_for(configuration, 'enforce_folder_visibility').each do |config, setting|
+          next if setting.nil?
+
+          next if [TrueClass, FalseClass].include?(setting.class) || setting == 'strict'
+
+          results << Result.new(
+            ok: false,
+            error_value: "\tInvalid 'enforce_folder_visibility' option: #{setting.inspect} in #{config.inspect}"
+          )
+        end
+
+        merge_results(results, separator: "\n---\n")
+      end
+
+      sig { override.returns(T::Array[String]) }
+      def permitted_keys
+        %w[enforce_folder_visibility]
+      end
+    end
+  end
+end

data/lib/packwerk-extensions.rb

@@ -6,6 +6,7 @@ require 'packwerk'
 
 require 'packwerk/privacy/checker'
 require 'packwerk/visibility/checker'
+require 'packwerk/folder_visibility/checker'
 require 'packwerk/architecture/checker'
 
 module Packwerk

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: packwerk-extensions
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Gusto Engineers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-09 00:00:00.000000000 Z
+date: 2023-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: packwerk
@@ -191,6 +191,9 @@ files:
 - lib/packwerk/architecture/layers.rb
 - lib/packwerk/architecture/package.rb
 - lib/packwerk/architecture/validator.rb
+- lib/packwerk/folder_visibility/checker.rb
+- lib/packwerk/folder_visibility/package.rb
+- lib/packwerk/folder_visibility/validator.rb
 - lib/packwerk/privacy/checker.rb
 - lib/packwerk/privacy/package.rb
 - lib/packwerk/privacy/validator.rb