packwerk-extensions 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15205fb6e29f594b5bfea27a6c2ef0488fa1ec2b2d6ae5265bfa906f7bac49a9
-  data.tar.gz: 6e795da44e384491a129e496a8541284317d0c523db59d431731119529535bbb
+  metadata.gz: 39d34d165ec6218799d3416a91249917b0d5b64272af7a8ba60c66e3473876c5
+  data.tar.gz: 040f5a83a6fef23e26efef5149fce578329c5db46b9d8f3ebe0d380e56250683
 SHA512:
-  metadata.gz: da2182b6b67511413dc606f943303130a955ba87f92e6798543a995eb94dc5577b1f1951decbb23751ce4c08535b361fc91778ebc6cea357d62f3860d4081e94
-  data.tar.gz: ee4701f2cc1ecf037823ffa7abe0cce8fa8d5bb2c61dcf587b85ab4331611968f7dfad84439a141479341c38f5a8a326e4b76c1b3040fa3672429c483a39a52c
+  metadata.gz: e6f3ac7caadd78432c6b5a45f593c63445e23bbc30784528b13c505175e4358f0efb0de65eeca41b6a049431d24855834d191b2a1b10892dda56016eb777e937
+  data.tar.gz: 7d4fbd68b612ce1cb185e574fca289bf8266133cda8f47a47d95a14adf098c5fa2805d6cdf15ba4c47287b5afcc4674328b7308e255c713cffc24b43c457cd8b

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
 ```
 
@@ -54,9 +56,86 @@ Example:
 public_path: my/custom/path/
 ```
 
+### Defining public constants through sigil
+
+> [!WARNING]
+> This way of of defining the public API of a package should be considered WIP. It is not supported by all tooling in the RubyAtScale ecosystem, as @alexevanczuk pointed out in a [comment on the PR](https://github.com/rubyatscale/packwerk-extensions/pull/35#discussion_r1334331797):
+>
+> There are a couple of other places that will require changes related to this sigil. Namely, everything that is coupled to the public folder implementation of privacy.
+>
+> In the rubyatscale org:
+> 
+> * pack_stats, example https://github.com/rubyatscale/pack_stats/blob/main/lib/pack_stats/private/metrics/public_usage.rb. (IMO though we can just remove this metric – it has never been useful)
+> * Other places that mention public_path or app/public.
+>   * Org wide search for app/public link
+>   * Org wide search for public_path link
+>   * packs (the Rust port of packwerk – I could take this one over unless someone is interested in implementing whatever we come up with there
+
+
+
+You may make individual files public withhin a private package by usage of a comment within the first 5 lines of the `.rb` file containing `pack_public: true`.
+
+Example:
+
+```ruby
+# pack_public: true
+module Foo
+  class Update
+  end
+end
+```
+Now `Foo::Update` is considered public even though the `foo` package might be set to `enforce_private: (true || :strict)`.
+
+It's important to note that when combining `public_api: true` with the declaration of `private_constants`,
+`packwerk validate` will raise an exception if both are used for the same constant. This must be resolved by removing
+the sigil from the `.rb` file or removing the constant from the list of `private_constants`.
+
+If you are using rubocop, it may be configured in such a way that there must be an empty line after the magic keywords at the top of the file. Currently, this extension is not modifying rubocop in anyway so it does not recognize `public_pack: true` as a valid magic keyword option. That means placing it at the end of the magic keywords will throw a rubocop exception. However, you can place it first in the list to avoid an exception in rubocop.
+```
+-----
+# typed: ignore
+# frozen_string_literal: true
+# pack_public: true
+
+class Foo
+...
+end => Layout/EmptyLineAfterMagicComment: Add an empty line after magic comments.
+
+------
+# typed: ignore
+# frozen_string_literal: true
+
+# pack_public: true
+
+class Foo
+...
+end => Less than ideal. This won't raise an issue in rubocop, however, only the first 5 lines are scanned for the magic comment of public_pack so there is risk at it being missed. It also is requiring extra empty lines in the group of magic comments.
+
+-----
+# pack_public: true
+# typed: ignore
+# frozen_string_literal: true
+
+class Foo
+...
+end => Ideal solution. No exceptions from rubocop and very low risk of the magic comment being out of range since
+```
+
 ### 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.
 
+### Ignore strict mode for violation coming from specific path patterns
+If you want to activate `'strict'` mode on you package but have a few privacy violations you know you will deal with later,
+you can set a list of patterns to exclude.
+
+```yaml
+enforce_privacy: strict
+strict_privacy_ignored_patterns:
+- engines/another_engine/test/**/*
+```
+
+In this example, violations on constants of your engine referenced in those files `engines/another_engine/test/**/*` will not fail Packwerk checks.
+
 ### Package Privacy violation
 Packwerk thinks something is a privacy violation if you're referencing a constant, class, or module defined in the private implementation (i.e. not the public folder) of another package. We care about these because we want to make sure we only use parts of a package that have been exposed as public API.
 
@@ -87,6 +166,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 +208,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/privacy/checker.rb

@@ -12,6 +12,37 @@ module Packwerk
       include Packwerk::Checker
 
       VIOLATION_TYPE = T.let('privacy', String)
+      PUBLICIZED_SIGIL = T.let('pack_public: true', String)
+      PUBLICIZED_SIGIL_REGEX = T.let(/#.*pack_public:\s*true/, Regexp)
+      @publicized_locations = T.let({}, T::Hash[String, T::Boolean])
+
+      class << self
+        extend T::Sig
+
+        sig { returns(T::Hash[String, T::Boolean]) }
+        def publicized_locations
+          @publicized_locations
+        end
+
+        sig { params(location: String).returns(T::Boolean) }
+        def publicized_location?(location)
+          unless publicized_locations.key?(location)
+            publicized_locations[location] = check_for_publicized_sigil(location)
+          end
+
+          T.must(publicized_locations[location])
+        end
+
+        sig { params(location: String).returns(T::Boolean) }
+        def check_for_publicized_sigil(location)
+          content_contains_sigil?(File.readlines(location))
+        end
+
+        sig { params(lines: T::Array[String]).returns(T::Boolean) }
+        def content_contains_sigil?(lines)
+          T.must(lines[0..4]).any? { |l| l =~ PUBLICIZED_SIGIL_REGEX }
+        end
+      end
 
       sig { override.returns(String) }
       def violation_type
@@ -28,6 +59,7 @@ module Packwerk
         privacy_package = Package.from(constant_package)
 
         return false if privacy_package.public_path?(reference.constant.location)
+        return false if self.class.publicized_location?(reference.constant.location)
 
         privacy_option = privacy_package.enforce_privacy
         return false if enforcement_disabled?(privacy_option)
@@ -44,7 +76,14 @@ module Packwerk
       end
       def strict_mode_violation?(listed_offense)
         publishing_package = listed_offense.reference.constant.package
-        publishing_package.config['enforce_privacy'] == 'strict'
+
+        return false unless publishing_package.config['enforce_privacy'] == 'strict'
+        return false if exclude_from_strict?(
+          publishing_package.config['strict_privacy_ignored_patterns'] || [],
+          Pathname.new(listed_offense.reference.relative_path).cleanpath
+        )
+
+        true
       end
 
       sig do
@@ -98,6 +137,13 @@ module Packwerk
 
         standard_message.chomp
       end
+
+      sig { params(globs: T::Array[String], path: Pathname).returns(T::Boolean) }
+      def exclude_from_strict?(globs, path)
+        globs.any? do |glob|
+          path.fnmatch(glob, File::FNM_EXTGLOB)
+        end
+      end
     end
   end
 end

data/lib/packwerk/privacy/package.rb

@@ -11,6 +11,7 @@ module Packwerk
       const :enforce_privacy, T.nilable(T.any(T::Boolean, String))
       const :private_constants, T::Array[String]
       const :ignored_private_constants, T::Array[String]
+      const :strict_privacy_ignored_patterns, T::Array[String]
 
       sig { params(path: String).returns(T::Boolean) }
       def public_path?(path)
@@ -27,7 +28,8 @@ module Packwerk
             user_defined_public_path: user_defined_public_path(package),
             enforce_privacy: package.config['enforce_privacy'],
             private_constants: package.config['private_constants'] || [],
-            ignored_private_constants: package.config['ignored_private_constants'] || []
+            ignored_private_constants: package.config['ignored_private_constants'] || [],
+            strict_privacy_ignored_patterns: package.config['strict_privacy_ignored_patterns'] || []
           )
         end
 

data/lib/packwerk/privacy/validator.rb

@@ -31,7 +31,7 @@ module Packwerk
 
       sig { override.returns(T::Array[String]) }
       def permitted_keys
-        %w[public_path enforce_privacy private_constants ignored_private_constants]
+        %w[public_path enforce_privacy private_constants ignored_private_constants strict_privacy_ignored_patterns]
       end
 
       private
@@ -110,9 +110,8 @@ module Packwerk
       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)
+          check_for_publicized_constant(location, constant_package, name)
         else
           Result.new(
             ok: false,
@@ -122,6 +121,23 @@ module Packwerk
         end
       end
 
+      sig { params(location: String, constant_package: Packwerk::Package, name: T.untyped).returns(Result) }
+      def check_for_publicized_constant(location, constant_package, name)
+        if Packwerk::Privacy::Checker.publicized_location?(location)
+          sigil = Packwerk::Privacy::Checker::PUBLICIZED_SIGIL
+          Result.new(
+            ok: false,
+            error_value: "'#{name}' is an explicitly publicized constant declared in #{location} through usage of " \
+                         "'#{sigil}'. However, the package '#{constant_package}' is also declaring it as a private " \
+                         "constant. This conflict must be resolved. Either remove '#{sigil}' from #{location} or " \
+                         'remove this constant from the list of private constants in the config for ' \
+                         "'#{constant_package}'."
+          )
+        else
+          Result.new(ok: true)
+        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|

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.9
 platform: ruby
 authors:
 - Gusto Engineers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-09 00:00:00.000000000 Z
+date: 2023-10-27 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