packwerk-extensions 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39d34d165ec6218799d3416a91249917b0d5b64272af7a8ba60c66e3473876c5
-  data.tar.gz: 040f5a83a6fef23e26efef5149fce578329c5db46b9d8f3ebe0d380e56250683
+  metadata.gz: 24439a703540da854784770755e1343825565c3803e5f445d2e201a2641b830c
+  data.tar.gz: 2abc2d11f203b5c4f779cffcd9b918950f196e8077f38ffd6607c48984e8142f
 SHA512:
-  metadata.gz: e6f3ac7caadd78432c6b5a45f593c63445e23bbc30784528b13c505175e4358f0efb0de65eeca41b6a049431d24855834d191b2a1b10892dda56016eb777e937
-  data.tar.gz: 7d4fbd68b612ce1cb185e574fca289bf8266133cda8f47a47d95a14adf098c5fa2805d6cdf15ba4c47287b5afcc4674328b7308e255c713cffc24b43c457cd8b
+  metadata.gz: 1174851513f542ffb1cffc27adab3f7cb7a8b0daa018476d57ce06547521727ee88c0c722b504d1ff81e2fe154b5a15073d99a7d05ce99f2057c98788e9484f5
+  data.tar.gz: db04d45d6cb81beb4b198fafee35246cb5aa53ef53d74ef4d399860339c0b8a95c8098fa32ef529e7ba5dc872d74715d2da030c45c57e1fbe237b1aae4d8643d

data/README.md

@@ -6,7 +6,7 @@ Currently, it ships the following checkers to help improve the boundaries betwee
 - 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.
 - 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.
+- A `layer` (formerly `architecture`) checker that allows packages to specify their "layer" and requires that each layer only communicate with layers below it.
 
 ## Installation
 
@@ -26,7 +26,7 @@ require:
   - packwerk/privacy/checker
   - packwerk/visibility/checker
   - packwerk/folder_visibility/checker
-  - packwerk/architecture/checker
+  - packwerk/layer/checker
 ```
 
 ## Privacy Checker
@@ -34,14 +34,18 @@ The privacy checker extension was originally extracted from [packwerk](https://g
 
 A package's privacy boundary is violated when there is a reference to the package's private constants from a source outside the package.
 
-To enforce privacy for your package, set `enforce_privacy` to `true` on your pack:
+To enforce privacy for your package, set `enforce_privacy` to `true` or `strict` on your pack:
 
 ```yaml
 # components/merchandising/package.yml
 enforce_privacy: true
 ```
 
-Setting `enforce_privacy` to true will make all references to private constants in your package a violation.
+Setting `enforce_privacy` to `true` will make all references to private constants in your package a violation.
+
+Setting `enforce_privacy` to `strict` will forbid all references to private constants in your package. **This includes violations that have been added to other packages' `package_todo.yml` files.** 
+
+Note: You will need to remove all existing privacy violations before setting `enforce_privacy` to `strict`.
 
 ### Using public folders
 You may enforce privacy either way mentioned above and still expose a public API for your package by placing constants in the public folder, which by default is `app/public`. The constants in the public folder will be made available for use by the rest of the application.
@@ -64,7 +68,7 @@ public_path: my/custom/path/
 > 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
@@ -73,7 +77,7 @@ public_path: my/custom/path/
 
 
 
-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`.
+You may make individual files public within a private package by usage of a comment within the first 5 lines of the `.rb` file containing `pack_public: true`.
 
 Example:
 
@@ -84,13 +88,13 @@ module Foo
   end
 end
 ```
-Now `Foo::Update` is considered public even though the `foo` package might be set to `enforce_private: (true || :strict)`.
+Now `Foo::Update` is considered public even though the `foo` package might be set to `enforce_privacy: (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.
+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 any way so it does not recognize `pack_public: 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
@@ -109,7 +113,7 @@ end => Layout/EmptyLineAfterMagicComment: Add an empty line after magic comments
 
 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.
+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 pack_public so there is risk at it being missed. It also is requiring extra empty lines in the group of magic comments.
 
 -----
 # pack_public: true
@@ -125,7 +129,7 @@ end => Ideal solution. No exceptions from rubocop and very low risk of the magic
 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,
+If you want to activate `'strict'` mode on your package but have a few privacy violations you know you will deal with later,
 you can set a list of patterns to exclude.
 
 ```yaml
@@ -155,7 +159,7 @@ You may be accessing the implementation of a piece of functionality that is supp
 The functionality you’re looking for may not be intended to be reused across packages at all. If there is no public interface for it but you have a good reason to use it from outside of its package, find the people responsible for the package and discuss a solution with them.
 
 ## Visibility Checker
-The visibility checker can be used to allow a package to be private implementation detail of other packages.
+The visibility checker can be used to allow a package to be a private implementation detail of other packages.
 
 To enforce visibility for your package, set `enforce_visibility` to `true` on your pack and specify `visible_to` for other packages that can use your package.
 
@@ -190,12 +194,12 @@ 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.
+## Layer Checker
+The layer checker can be used to enforce constraints on what can depend on what.
 
-To enforce architecture for your package, first define the `architecture_layers` in `packwerk.yml`, for example:
+To enforce layers for your package, first define the `layers` in `packwerk.yml`, for example:
 ```
-architecture_layers:
+layers:
   - package
   - utility
 ```
@@ -203,12 +207,33 @@ architecture_layers:
 Then, turn on the checker in your package:
 ```yaml
 # components/merchandising/package.yml
-enforce_architecture: true
+enforce_layers: true
 layer: utility
 ```
 
 Now this pack can only depend on other utility packages.
 
+### Deprecated Architecture Checker
+The "Layer Checker" was formerly named "Architecture Checker". The associated keys were:
+- packwerk.yml `architecture_layers`, which is now `layers`
+- package.yml `enforce_architecture`, which is now `enforce_layers`
+- package.yml `layer` is still a valid key
+- package_todo.yml - `architecture`, which is now `layer`
+
+```bash
+  # script to migrate code from deprecated "architecture" violations to "layer" violations
+  # sed and ripgrep required
+
+  # replace 'architecture_layers' with 'layers' in packwerk.yml
+  sed -i '' 's/architecture_layers/layers/g' ./packwerk.yml
+  
+  # replace 'enforce_architecture' with 'enforce_layers' in package.yml files
+  `rg -l 'enforce_architecture' -g 'package.yml' | xargs sed -i '' 's,enforce_architecture,enforce_layers,g'`
+
+  # replace '- architecture' with '- layer' in package_todo.yml files
+  `rg -l 'architecture' -g 'package_todo.yml' | xargs sed -i '' 's/- architecture/- layer/g'`
+```
+
 
 ## Contributing
 

data/lib/packwerk/{architecture → layer}/checker.rb

@@ -1,16 +1,17 @@
 # typed: strict
 # frozen_string_literal: true
 
-require 'packwerk/architecture/layers'
-require 'packwerk/architecture/package'
-require 'packwerk/architecture/validator'
+require 'packwerk/layer/config'
+require 'packwerk/layer/layers'
+require 'packwerk/layer/package'
+require 'packwerk/layer/validator'
 
 module Packwerk
-  module Architecture
+  module Layer
     # This enforces "layered architecture," which allows each class to be designated as one of N layers
     # configured by the client in `packwerk.yml`, for example:
     #
-    # architecture_layers:
+    # layers:
     #   - orchestrator
     #   - business_domain
     #   - platform
@@ -18,7 +19,7 @@ module Packwerk
     #   - specification
     #
     # Then a package can configure:
-    # enforce_architecture: true | false | strict
+    # enforce_layers: true | false | strict
     # layer: utility
     #
     # This is intended to provide:
@@ -30,11 +31,14 @@ module Packwerk
       extend T::Sig
       include Packwerk::Checker
 
-      VIOLATION_TYPE = T.let('architecture', String)
+      sig { void }
+      def initialize
+        @violation_type = T.let(@violation_type, T.nilable(String))
+      end
 
       sig { override.returns(String) }
       def violation_type
-        VIOLATION_TYPE
+        @violation_type ||= layer_config.violation_key
       end
 
       sig do
@@ -55,7 +59,7 @@ module Packwerk
       end
       def strict_mode_violation?(listed_offense)
         constant_package = listed_offense.reference.package
-        constant_package.config['enforce_architecture'] == 'strict'
+        constant_package.config[layer_config.enforce_key] == 'strict'
       end
 
       sig do
@@ -68,9 +72,10 @@ module Packwerk
         referencing_package = Package.from(reference.package, layers)
 
         message = <<~MESSAGE
-          Architecture layer violation: '#{reference.constant.name}' belongs to '#{reference.constant.package}', whose architecture layer type is "#{constant_package.layer}."
-          This constant cannot be referenced by '#{reference.package}', whose architecture layer type is "#{referencing_package.layer}."
-          Can we organize our code logic to respect the layers of these packs? See all layers in packwerk.yml.
+          Layer violation: '#{reference.constant.name}' belongs to '#{reference.constant.package}', whose layer type is "#{constant_package.layer}".
+          This constant cannot be referenced by '#{reference.package}', whose layer type is "#{referencing_package.layer}".
+          Packs in a lower layer may not access packs in a higher layer. See the `layers` in packwerk.yml. Current hierarchy:
+          - #{layers.names_list.join("\n- ")}
 
           #{standard_help_message(reference)}
         MESSAGE
@@ -91,7 +96,12 @@ module Packwerk
 
       sig { returns(Layers) }
       def layers
-        @layers ||= T.let(Layers.new, T.nilable(Packwerk::Architecture::Layers))
+        @layers ||= T.let(Layers.new, T.nilable(Packwerk::Layer::Layers))
+      end
+
+      sig { returns(Config) }
+      def layer_config
+        @layer_config ||= T.let(Config.new, T.nilable(Config))
       end
     end
   end

data/lib/packwerk/layer/config.rb

@@ -0,0 +1,46 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module Layer
+    class Config
+      extend T::Sig
+
+      ARCHITECTURE_VIOLATION_TYPE = T.let('architecture', String)
+      ARCHITECTURE_ENFORCE = T.let('enforce_architecture', String)
+      LAYER_VIOLATION_TYPE = T.let('layer', String)
+      LAYER_ENFORCE = T.let('enforce_layers', String)
+
+      sig { void }
+      def initialize
+        @layers_key_configured = T.let(@layers_key_configured, T.nilable(T::Boolean))
+        @layers_list = T.let(@layers_list, T.nilable(T::Array[String]))
+      end
+
+      sig { returns(T::Array[String]) }
+      def layers_list
+        @layers_list ||= YAML.load_file('packwerk.yml')[layers_key] || []
+      end
+
+      sig { returns(T::Boolean) }
+      def layers_key_configured?
+        @layers_key_configured ||= YAML.load_file('packwerk.yml')['architecture_layers'].nil?
+      end
+
+      sig { returns(String) }
+      def layers_key
+        layers_key_configured? ? 'layers' : 'architecture_layers'
+      end
+
+      sig { returns(String) }
+      def violation_key
+        layers_key_configured? ? LAYER_VIOLATION_TYPE : ARCHITECTURE_VIOLATION_TYPE
+      end
+
+      sig { returns(String) }
+      def enforce_key
+        layers_key_configured? ? LAYER_ENFORCE : ARCHITECTURE_ENFORCE
+      end
+    end
+  end
+end

data/lib/packwerk/{architecture → layer}/layers.rb

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
-  module Architecture
+  module Layer
     class Layers
       extend T::Sig
 
@@ -27,11 +27,9 @@ module Packwerk
         @names ||= Set.new(names_list)
       end
 
-      private
-
       sig { returns(T::Array[String]) }
       def names_list
-        @names_list ||= YAML.load_file('packwerk.yml')['architecture_layers'] || []
+        @names_list ||= Config.new.layers_list
       end
     end
   end

data/lib/packwerk/{architecture → layer}/package.rb

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
-  module Architecture
+  module Layer
     class Package < T::Struct
       extend T::Sig
 
@@ -46,7 +46,7 @@ module Packwerk
 
           Package.new(
             layer: layer,
-            enforcement_setting: config['enforce_architecture'],
+            enforcement_setting: config[Config.new.enforce_key],
             config: config
           )
         end

data/lib/packwerk/{architecture → layer}/validator.rb

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
-  module Architecture
+  module Layer
     class Validator
       extend T::Sig
       include Packwerk::Validator
@@ -16,19 +16,21 @@ module Packwerk
         package_set.each do |package|
           config = package.config
           f = Pathname.new(package.name).join('package.yml').to_s
+          package = Package.from(package, layers)
+
           next if !config
 
-          result = check_enforce_architecture_setting(f, config['enforce_architecture'])
+          result = check_enforce_key(package, f, config)
           results << result
           next if !result.ok?
 
-          package = Package.from(package, layers)
+          result = check_enforce_layers_setting(f, config[layer_config.enforce_key])
+          results << result
+          next if !result.ok?
 
           result = check_layer_setting(package, f)
           results << result
           next if !result.ok?
-
-          results += check_dependencies_setting(package_set, package, f)
         end
 
         merge_results(results, separator: "\n---\n")
@@ -36,33 +38,39 @@ module Packwerk
 
       sig { returns(Layers) }
       def layers
-        @layers ||= T.let(Layers.new, T.nilable(Packwerk::Architecture::Layers))
+        @layers ||= T.let(Layers.new, T.nilable(Packwerk::Layer::Layers))
+      end
+
+      sig { returns(Config) }
+      def layer_config
+        @layer_config ||= T.let(Config.new, T.nilable(Config))
       end
 
       sig { override.returns(T::Array[String]) }
       def permitted_keys
-        %w[enforce_architecture layer]
+        [layer_config.enforce_key, 'layer']
       end
 
       sig do
-        params(package_set: PackageSet, package: Package, config_file_path: String).returns(T::Array[Result])
+        params(package: Package, config_file_path: String, config: T::Hash[T.untyped, T.untyped]).returns(Result)
       end
-      def check_dependencies_setting(package_set, package, config_file_path)
-        results = T.let([], T::Array[Result])
-        package.config.fetch('dependencies', []).each do |dependency|
-          other_packwerk_package = package_set.fetch(dependency)
-          next if other_packwerk_package.nil?
+      def check_enforce_key(package, config_file_path, config)
+        enforce_layer_present = !config[Config::LAYER_ENFORCE].nil?
+        enforce_architecture_present = !config[Config::ARCHITECTURE_ENFORCE].nil?
 
-          other_package = Package.from(other_packwerk_package, layers)
-          next if package.can_depend_on?(other_package, layers: layers)
-
-          results << Result.new(
+        if layer_config.enforce_key == Config::LAYER_ENFORCE && enforce_architecture_present
+          Result.new(
+            ok: false,
+            error_value: "Unexpected `enforce_architecture` option in #{config_file_path.inspect}. Did you mean `enforce_layers`?"
+          )
+        elsif layer_config.enforce_key == Config::ARCHITECTURE_ENFORCE && enforce_layer_present
+          Result.new(
             ok: false,
-            error_value: "Invalid 'dependencies' in #{config_file_path.inspect}. '#{config_file_path}' has a layer type of '#{package.layer},' which cannot rely on '#{other_packwerk_package.name},' which has a layer type of '#{other_package.layer}.' `architecture_layers` can be found in packwerk.yml."
+            error_value: "Unexpected `enforce_layers` option in #{config_file_path.inspect}. Did you mean `enforce_architecture`?"
           )
+        else
+          Result.new(ok: true)
         end
-
-        results
       end
 
       sig do
@@ -75,14 +83,14 @@ module Packwerk
         if layer.nil? && package.enforces?
           Result.new(
             ok: false,
-            error_value: "Invalid 'layer' option in #{config_file_path.inspect}: #{package.layer.inspect}. `layer` must be set if `enforce_architecture` is on."
+            error_value: "Invalid 'layer' option in #{config_file_path.inspect}: #{package.layer.inspect}. `layer` must be set if `#{layer_config.enforce_key}` is on."
           )
         elsif valid_layer
           Result.new(ok: true)
         else
           Result.new(
             ok: false,
-            error_value: "Invalid 'layer' option in #{config_file_path.inspect}: #{layer.inspect}. Must be one of #{layers.names.to_a.inspect}"
+            error_value: "Invalid 'layer' option in #{config_file_path.inspect}: #{layer.inspect}. Must be one of #{layers.names_list.inspect}"
           )
         end
       end
@@ -90,19 +98,19 @@ module Packwerk
       sig do
         params(config_file_path: String, setting: T.untyped).returns(Result)
       end
-      def check_enforce_architecture_setting(config_file_path, setting)
+      def check_enforce_layers_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
           Result.new(
             ok: false,
-            error_value: "Invalid 'enforce_architecture' option in #{config_file_path.inspect}: #{setting.inspect}"
+            error_value: "Invalid '#{layer_config.enforce_key}' option in #{config_file_path.inspect}: #{setting.inspect}"
           )
         elsif activated_value && !layers_set
           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: "Cannot set '#{layer_config.enforce_key}' option in #{config_file_path.inspect} until `layers` have been specified in `packwerk.yml`"
           )
         else
           Result.new(ok: true)

data/lib/packwerk/visibility/validator.rb

@@ -14,7 +14,7 @@ module Packwerk
         visible_settings = package_manifests_settings_for(configuration, 'visible_to')
         results = T.let([], T::Array[Result])
 
-        all_package_names = package_set.map(&:name).to_set
+        all_package_names = package_set.to_set(&:name)
 
         package_manifests_settings_for(configuration, 'enforce_visibility').each do |config, setting|
           next if setting.nil?

data/lib/packwerk-extensions.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: packwerk-extensions
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.0
 platform: ruby
 authors:
 - Gusto Engineers
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-27 00:00:00.000000000 Z
+date: 2024-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: packwerk
@@ -187,13 +187,14 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/packwerk-extensions.rb
-- lib/packwerk/architecture/checker.rb
-- 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/layer/checker.rb
+- lib/packwerk/layer/config.rb
+- lib/packwerk/layer/layers.rb
+- lib/packwerk/layer/package.rb
+- lib/packwerk/layer/validator.rb
 - lib/packwerk/privacy/checker.rb
 - lib/packwerk/privacy/package.rb
 - lib/packwerk/privacy/validator.rb
@@ -208,7 +209,7 @@ metadata:
   source_code_uri: https://github.com/rubyatscale/packwerk-extensions
   changelog_uri: https://github.com/rubyatscale/packwerk-extensions/releases
   allowed_push_host: https://rubygems.org
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -216,15 +217,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.5.9
+signing_key:
 specification_version: 4
 summary: A collection of extensions for packwerk packages.
 test_files: []