packwerk-extensions 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4dbf14484c64b3fe953df421fad052d504988b6ea4f7b325baf53baa4e869b4b
-  data.tar.gz: b34ab360d4b87eb2a30f5f32e6057fc3088674768cdefb3d787b80dfa52931e1
+  metadata.gz: 3f20892b9d7d67a2164c7c632ac760c66859cacd2fa7af97c71a220a1d317893
+  data.tar.gz: a9a7f631ed8e6398a48e91fddc83fcff0e1d923aa16b75231e0a3296c5c4aa4a
 SHA512:
-  metadata.gz: 2b1b7b4f9665f2bd39cec93f5ccd4a650f8b2f89b217cc2141a7e66cd1b43591f1b948c7bc9ebaf5f7297df5f058a8a197cec32217e2d751adfe73f5197700e7
-  data.tar.gz: fb813bb156391ed80b5fb7a6bb3886b48e1ba5204db4f64c1b88d82cf4e5a6a654384cf3de632db6839d76bca730c8a04de34535673b81cb8702ff321756f2e0
+  metadata.gz: f66866b77e2727898fa951a05f716f8b959444553082f9c8999144013ee74d90820ee802a994b11887c3132799b47cbcc74a60cc6434a6172617ebb916748216
+  data.tar.gz: b6deec3d175813666076ce5797d29cc62df65ec233c552114cdf3492c92dd74791b53412201a8b3e56758fdb4bb9a6c7bed804225c99c192d92f9566a60a4a85

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)
+        referencing_package = Package.from(reference.package)
+        !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)
+        referencing_package = Package.from(reference.package)
+
+        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,30 @@
+# 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::Array[String]))
+      end
+
+      sig { params(layer: String).returns(Integer) }
+      def index_of(layer)
+        index = names.reverse.find_index(layer)
+        if index.nil?
+          raise "Layer #{layer} not find, please run `bin/packwerk validate`"
+        end
+
+        index
+      end
+
+      sig { returns(T::Array[String]) }
+      def names
+        @names ||= YAML.load_file('packwerk.yml')['architecture_layers'] || []
+      end
+    end
+  end
+end

data/lib/packwerk/architecture/package.rb

@@ -0,0 +1,49 @@
+# 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).returns(Package) }
+        def from(package)
+          from_config(package.config)
+        end
+
+        sig { params(config: T::Hash[T.untyped, T.untyped]).returns(Package) }
+        def from_config(config)
+          Package.new(
+            layer: config['layer'],
+            enforcement_setting: config['enforce_architecture'],
+            config: config
+          )
+        end
+      end
+    end
+  end
+end

data/lib/packwerk/architecture/validator.rb

@@ -0,0 +1,111 @@
+# 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_manifests(configuration).each do |f|
+          config = YAML.load_file(File.join(f))
+          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_config(config)
+          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)
+          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.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.6
 platform: ruby
 authors:
 - Gusto Engineers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-12-19 00:00:00.000000000 Z
+date: 2022-12-21 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