packwerk-extensions 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4dbf14484c64b3fe953df421fad052d504988b6ea4f7b325baf53baa4e869b4b
-  data.tar.gz: b34ab360d4b87eb2a30f5f32e6057fc3088674768cdefb3d787b80dfa52931e1
+  metadata.gz: 558107be67a748dfb9a175b9d90be2acc373913f36a66c5bccbb3401e80cd85f
+  data.tar.gz: fb98b8c64bb3043d267aab3d966d404934a5a530020dc18e3e599a13153fe121
 SHA512:
-  metadata.gz: 2b1b7b4f9665f2bd39cec93f5ccd4a650f8b2f89b217cc2141a7e66cd1b43591f1b948c7bc9ebaf5f7297df5f058a8a197cec32217e2d751adfe73f5197700e7
-  data.tar.gz: fb813bb156391ed80b5fb7a6bb3886b48e1ba5204db4f64c1b88d82cf4e5a6a654384cf3de632db6839d76bca730c8a04de34535673b81cb8702ff321756f2e0
+  metadata.gz: e6beb350fd3089406f7a0ec0409b79f261136b89ffe0ede267215893ca7abb9f5613a7aaf44248f1c0b53560a0596a78739568f85bd2a081edf4b3d0f69fe0d0
+  data.tar.gz: 706bc3779b3af6ce3d6780ba9106a8bb4fc84cd81ddd93c7809b62f2663de1baf4c906f961abc6a4982c8815142478d839054b27c504639e1eb5dc88e0b267e3

data/README.md

@@ -2,40 +2,29 @@
 
 `packwerk-extensions` is a home for checker extensions for packwerk.
 
-#### Enforcing privacy boundary
+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.
 
+## Privacy Checker
 The privacy checker extension was originally extracted from [packwerk](https://github.com/Shopify/packwerk).
 
 A package's privacy boundary is violated when there is a reference to the package's private constants from a source outside the package.
 
-There are two ways you can enforce privacy for your package:
-
-1. Enforce privacy for all external sources
+To enforce privacy for your package, set `enforce_privacy` to `true` on your pack:
 
 ```yaml
 # components/merchandising/package.yml
-enforce_privacy: true  # will make everything private that is not in
-                        # the components/merchandising/app/public folder
+enforce_privacy: true
 ```
 
 Setting `enforce_privacy` to true will make all references to private constants in your package a violation.
 
-2. Enforce privacy for specific constants
-
-```yaml
-# components/merchandising/package.yml
-enforce_privacy:
-  - "::Merchandising::Product"
-  - "::SomeNamespace"  # enforces privacy for the namespace and
-                       # everything nested in it
-```
-
-It will be a privacy violation when a file outside of the `components/merchandising` package tries to reference `Merchandising::Product`.
-
-##### Using public folders
+### 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.
 
-##### Defining your own public folder
+### Defining your own public folder
 
 You may prefer to override the default public folder, you can do so on a per-package basis by defining a `public_path`.
 
@@ -48,8 +37,6 @@ public_path: my/custom/path/
 ### 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`.
 
-See: [USAGE.md - Enforcing privacy boundary](USAGE.md#Enforcing-privacy-boundary)
-
 #### Interpreting Privacy violation
 
 > /Users/JaneDoe/src/github.com/sample-project/user/app/controllers/labels_controller.rb:170:30
@@ -60,7 +47,38 @@ See: [USAGE.md - Enforcing privacy boundary](USAGE.md#Enforcing-privacy-boundary
 
 There has been a privacy violation of the package `billing` in the package `user`, through the use of the constant `Billing::CarrierInvoiceTransaction` in the file `user/app/controllers/labels_controller.rb`.
 
-##### Suggestions
+#### Suggestions
 You may be accessing the implementation of a piece of functionality that is supposed to be accessed through a public interface on the package. Try to use the public interface instead. A package’s public interface should be defined in its `app/public` folder and documented.
 
 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.
+
+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.
+
+```yaml
+# components/merchandising/package.yml
+enforce_visibility: true
+visible_to:
+  - components/other_package
+```
+
+## Architecture Checker
+The architecture 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:
+```
+architecture_layers:
+  - package
+  - utility
+```
+
+Then, turn on the checker in your package:
+```yaml
+# components/merchandising/package.yml
+enforce_architecture: true
+layer: utility
+```
+
+Now this pack can only depend on other utility packages.

data/lib/packwerk/architecture/checker.rb

@@ -0,0 +1,96 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'packwerk/architecture/layers'
+
+module Packwerk
+  module Architecture
+    # 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:
+    #   - orchestrator
+    #   - business_domain
+    #   - platform
+    #   - utility
+    #   - specification
+    #
+    # Then a package can configure:
+    # enforce_architecture: true | false | strict
+    # layer: utility
+    #
+    # This is intended to provide:
+    # A) Direction for which dependency violations to tackle
+    # B) What dependencies should or should not exist
+    # C) A potential sequencing for modularizing a system (starting with lower layers first).
+    #
+    class Checker
+      extend T::Sig
+      include Packwerk::Checker
+
+      VIOLATION_TYPE = T.let('architecture', 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)
+        constant_package = Package.from(reference.constant.package, layers)
+        referencing_package = Package.from(reference.package, layers)
+        !referencing_package.can_depend_on?(constant_package, layers: layers)
+      end
+
+      sig do
+        override
+          .params(listed_offense: Packwerk::ReferenceOffense)
+          .returns(T::Boolean)
+      end
+      def strict_mode_violation?(listed_offense)
+        constant_package = listed_offense.reference.package
+        constant_package.config['enforce_architecture'] == 'strict'
+      end
+
+      sig do
+        override
+          .params(reference: Packwerk::Reference)
+          .returns(String)
+      end
+      def message(reference)
+        constant_package = Package.from(reference.constant.package, layers)
+        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.
+
+          #{standard_help_message(reference)}
+        MESSAGE
+
+        message.chomp
+      end
+
+      # TODO: Extract this out into a common helper, can call it StandardViolationHelpMessage.new(...) and implements .to_s
+      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
+
+      sig { returns(Layers) }
+      def layers
+        @layers ||= T.let(Layers.new, T.nilable(Packwerk::Architecture::Layers))
+      end
+    end
+  end
+end

data/lib/packwerk/architecture/layers.rb

@@ -0,0 +1,38 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module Architecture
+    class Layers
+      extend T::Sig
+
+      sig { void }
+      def initialize
+        @names = T.let(@names, T.nilable(T::Set[String]))
+        @names_list = T.let(@names_list, T.nilable(T::Array[String]))
+      end
+
+      sig { params(layer: String).returns(Integer) }
+      def index_of(layer)
+        index = names_list.reverse.find_index(layer)
+        if index.nil?
+          raise "Layer #{layer} not find, please run `bin/packwerk validate`"
+        end
+
+        index
+      end
+
+      sig { returns(T::Set[String]) }
+      def names
+        @names ||= Set.new(names_list)
+      end
+
+      private
+
+      sig { returns(T::Array[String]) }
+      def names_list
+        @names_list ||= YAML.load_file('packwerk.yml')['architecture_layers'] || []
+      end
+    end
+  end
+end

data/lib/packwerk/architecture/package.rb

@@ -0,0 +1,54 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module Architecture
+    class Package < T::Struct
+      extend T::Sig
+
+      const :layer, T.nilable(String)
+      const :enforcement_setting, T.nilable(T.any(T::Boolean, String, T::Array[String]))
+      const :config, T::Hash[T.untyped, T.untyped]
+
+      sig { returns(T::Boolean) }
+      def enforces?
+        enforcement_setting == true || enforcement_setting == 'strict'
+      end
+
+      sig { params(other_package: Package, layers: Layers).returns(T::Boolean) }
+      def can_depend_on?(other_package, layers:)
+        return true if !enforces?
+
+        flow_sensitive_layer = layer
+        flow_sensitive_other_layer = other_package.layer
+        return true if flow_sensitive_layer.nil?
+        return true if flow_sensitive_other_layer.nil?
+
+        layers.index_of(flow_sensitive_layer) >= layers.index_of(flow_sensitive_other_layer)
+      end
+
+      class << self
+        extend T::Sig
+
+        sig { params(package: ::Packwerk::Package, layers: Layers).returns(Package) }
+        def from(package, layers)
+          config = package.config
+
+          # This allows the layer to be inferred based on the package root
+          package_root = package.name.split('/').first
+          if package_root && layers.names.include?(package_root)
+            layer = package_root
+          else
+            layer = config['layer']
+          end
+
+          Package.new(
+            layer: layer,
+            enforcement_setting: config['enforce_architecture'],
+            config: config
+          )
+        end
+      end
+    end
+  end
+end

data/lib/packwerk/architecture/validator.rb

@@ -0,0 +1,112 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Packwerk
+  module Architecture
+    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_set.each do |package|
+          config = package.config
+          f = Pathname.new(package.name).join('package.yml').to_s
+          next if !config
+
+          result = check_enforce_architecture_setting(f, config['enforce_architecture'])
+          results << result
+          next if !result.ok?
+
+          result = check_layer_setting(config, f, config['layer'])
+          results << result
+          next if !result.ok?
+
+          package = Package.from(package, layers)
+          results += check_dependencies_setting(package_set, package, f)
+        end
+
+        merge_results(results, separator: "\n---\n")
+      end
+
+      sig { returns(Layers) }
+      def layers
+        @layers ||= T.let(Layers.new, T.nilable(Packwerk::Architecture::Layers))
+      end
+
+      sig { override.returns(T::Array[String]) }
+      def permitted_keys
+        %w[enforce_architecture layer]
+      end
+
+      sig do
+        params(package_set: PackageSet, package: Package, config_file_path: String).returns(T::Array[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?
+
+          other_package = Package.from(other_packwerk_package, layers)
+          next if package.can_depend_on?(other_package, layers: layers)
+
+          results << 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."
+          )
+        end
+
+        results
+      end
+
+      sig do
+        params(config: T::Hash[T.untyped, T.untyped], config_file_path: String, layer: T.untyped).returns(Result)
+      end
+      def check_layer_setting(config, config_file_path, layer)
+        enforce_architecture = config['enforce_architecture']
+        enforce_architecture_enabled = !(enforce_architecture.nil? || enforce_architecture == false)
+        valid_layer = layer.nil? || layers.names.include?(layer)
+
+        if layer.nil? && enforce_architecture_enabled
+          Result.new(
+            ok: false,
+            error_value: "Invalid 'layer' option in #{config_file_path.inspect}: #{layer.inspect}. `layer` must be set if `enforce_architecture` 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}"
+          )
+        end
+      end
+
+      sig do
+        params(config_file_path: String, setting: T.untyped).returns(Result)
+      end
+      def check_enforce_architecture_setting(config_file_path, 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
+          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`"
+          )
+        else
+          Result.new(
+            ok: false,
+            error_value: "Invalid 'enforce_architecture' option in #{config_file_path.inspect}: #{setting.inspect}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/packwerk-extensions.rb

@@ -12,6 +12,10 @@ 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
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: packwerk-extensions
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.7
 platform: ruby
 authors:
 - Gusto Engineers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-12-19 00:00:00.000000000 Z
+date: 2022-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: packwerk
@@ -173,6 +173,10 @@ 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/privacy/checker.rb
 - lib/packwerk/privacy/package.rb
 - lib/packwerk/privacy/validator.rb