parse_packwerk 0.10.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 00ce04288d8a8c4f46571bd181e8a3781d325116cd58e8078cdf142e9f74ffce
+  data.tar.gz: 23c1e53eab84fc472d116bf025c6ddb499f509da25246f47ffbdb857ec922f3f
+SHA512:
+  metadata.gz: f24bf1e21e1800e35aa9c4fcdbf1c5e71efafd421d1ce7829461e620c30728a23dd78e099f91bd359fa69e0bca9cef71fabea4cc139598520520942afbcf9006
+  data.tar.gz: 6bd309198e121db0066178ec0fcddbef4b0187110a600bc716fe72d1ebbedab713767b25700d679bd219cafabd93ce6c0896cc0cf9cfa51c279c205105c30003

data/README.md

@@ -0,0 +1,33 @@
+# ParsePackwerk
+This gem is meant to give a way to parse the various YML files that come with [`packwerk`](https://github.com/Shopify/packwerk).
+
+# Usage
+```ruby
+# Get all packages
+# Note that currently, this does not respect configuration in `packwerk.yml`
+packages = ParsePackwerk.all
+
+# Get a single package with a given ame
+package = ParsePackwerk.find('packs/my_pack')
+
+# Get a structured `deprecated_references.yml` object a single package
+deprecated_references = ParsePackwerk::DeprecatedReferences.for(package)
+
+# Count violations of a particular type for a package
+deprecated_references.violations.count(&:privacy?)
+deprecated_references.violations.count(&:dependency?)
+
+# Get the number of files a particular constant is violated in
+deprecated_references.violations.select { |v| v.class_name == 'SomeConstant' }.sum { |v| v.files.count }
+```
+
+# Why does this gem exist?
+We generally recommend folks depend on `packwerk` rather than `parse_packwerk`. This gem is mostly a private implementation for other parts of the Big Rails modularization toolchain.
+
+This gem exists for this toolchain for these reasons:
+
+(A) `packwerk` is lacking public APIs for the behavior we want. It's close with `PackageSet`, but we need to also be able to parse violations.
+(B) Certain critical, production runtime code-paths need to use this, and we want a simple, low-dependency, infrequently changing dependency for our production environment. One example of production usage is that `package.yml` files can store team ownership information, which is used when an error happens in production to route it to the right team.
+(C) `packwerk` has heavy duty dependencies like rails and lots of others, and it adds a degree of maintenance cost and complexity that isn’t necessary when all we want to do is read YML files
+
+Long-term, it might make sense for these reasons to extract out some of the parsing from `packwerk` into a separate gem similar to this so that we can leverage the ecosystem of tools associated with the idea of a “pack” in ways that are simple and safe for both development and production environments.

data/lib/parse_packwerk/configuration.rb

@@ -0,0 +1,52 @@
+# typed: strict
+
+module ParsePackwerk
+  class Configuration < T::Struct
+    extend T::Sig
+
+    const :exclude, T::Array[String]
+    const :package_paths, T::Array[String]
+
+    sig { returns(Configuration) }
+    def self.fetch
+      packwerk_yml_filename = Pathname.new(PACKWERK_YML_NAME)
+      if !File.exist?(packwerk_yml_filename)
+        raw_packwerk_config = {}
+      else
+        # when the YML file is empty or only contains comment, it gets parsed
+        # as the boolean `false` for some reason. this handles that case
+        raw_packwerk_config = YAML.load_file(packwerk_yml_filename) || {}
+      end
+
+      Configuration.new(
+        exclude: excludes(raw_packwerk_config),
+        package_paths: package_paths(raw_packwerk_config),
+      )
+    end
+
+    sig { params(config_hash: T::Hash[T.untyped, T.untyped]).returns(T::Array[String]) }
+    def self.excludes(config_hash)
+      specified_exclude = config_hash['exclude']
+      excludes = if specified_exclude.nil?
+        DEFAULT_EXCLUDE_GLOBS.dup
+      else
+        Array(specified_exclude)
+      end
+
+      excludes.push Bundler.bundle_path.join("**").to_s
+    end
+
+    sig { params(config_hash: T::Hash[T.untyped, T.untyped]).returns(T::Array[String]) }
+    def self.package_paths(config_hash)
+      specified_package_paths = config_hash['package_paths']
+      package_paths = if specified_package_paths.nil?
+        DEFAULT_PACKAGE_PATHS.dup
+      else
+        Array(specified_package_paths)
+      end
+
+      # We add the root package path always
+      package_paths.push '.'
+    end
+  end
+end

data/lib/parse_packwerk/constants.rb

@@ -0,0 +1,21 @@
+# typed: strict
+
+module ParsePackwerk
+  ROOT_PACKAGE_NAME = T.let('.'.freeze, String)
+  PACKAGE_YML_NAME = T.let('package.yml'.freeze, String)
+  PACKWERK_YML_NAME = T.let('packwerk.yml'.freeze, String)
+  DEPRECATED_REFERENCES_YML_NAME = T.let('deprecated_references.yml'.freeze, String)
+  ENFORCE_DEPENDENCIES = T.let('enforce_dependencies'.freeze, String)
+  ENFORCE_PRIVACY = T.let('enforce_privacy'.freeze, String)
+  METADATA = T.let('metadata'.freeze, String)
+  DEPENDENCIES = T.let('dependencies'.freeze, String)
+
+  # Since this metadata is unstructured YAML, it could be any type. We leave it to clients of `ParsePackwerk::Package`
+  # to add types based on their known usage of metadata.
+  MetadataYmlType = T.type_alias do
+    T::Hash[T.untyped, T.untyped]
+  end
+
+  DEFAULT_EXCLUDE_GLOBS = T.let(["{bin,node_modules,script,tmp,vendor}/**/*"], T::Array[String])
+  DEFAULT_PACKAGE_PATHS = T.let(['**/'], T::Array[String])
+end

data/lib/parse_packwerk/deprecated_references.rb

@@ -0,0 +1,50 @@
+# typed: strict
+
+module ParsePackwerk
+  class DeprecatedReferences < T::Struct
+    extend T::Sig
+
+    const :pathname, Pathname
+    const :violations, T::Array[Violation]
+
+    sig { params(package: Package).returns(DeprecatedReferences) }
+    def self.for(package)
+      deprecated_references_yml_pathname = package.directory.join(DEPRECATED_REFERENCES_YML_NAME)
+      DeprecatedReferences.from(deprecated_references_yml_pathname)
+    end
+
+    sig { params(pathname: Pathname).returns(DeprecatedReferences) }
+    def self.from(pathname)
+      if !pathname.exist?
+        new(
+          pathname: pathname.cleanpath,
+          violations: []
+        )
+      else
+        deprecated_references_loaded_yml = YAML.load_file(pathname)
+
+        all_violations = []
+        deprecated_references_loaded_yml&.each_key do |to_package_name|
+          deprecated_references_per_package = deprecated_references_loaded_yml[to_package_name]
+          deprecated_references_per_package.each_key do |class_name|
+            symbol_usage = deprecated_references_per_package[class_name]
+            files = symbol_usage['files']
+            violations = symbol_usage['violations']
+            if violations.include? 'dependency'
+              all_violations << Violation.new(type: 'dependency', to_package_name: to_package_name, class_name: class_name, files: files)
+            end
+
+            if violations.include? 'privacy'
+              all_violations << Violation.new(type: 'privacy', to_package_name: to_package_name, class_name: class_name, files: files)
+            end
+          end
+        end
+
+        new(
+          pathname: pathname.cleanpath,
+          violations: all_violations
+        )
+      end
+    end
+  end
+end

data/lib/parse_packwerk/package.rb

@@ -0,0 +1,47 @@
+# typed: strict
+
+module ParsePackwerk
+  class Package < T::Struct
+    extend T::Sig
+
+    const :name, String
+    const :enforce_dependencies, T::Boolean
+    const :enforce_privacy, T::Boolean
+    const :metadata, MetadataYmlType
+    const :dependencies, T::Array[String]
+
+    sig { params(pathname: Pathname).returns(Package) }
+    def self.from(pathname)
+      package_loaded_yml = YAML.load_file(pathname)
+      package_name = pathname.dirname.cleanpath.to_s
+
+      new(
+        name: package_name,
+        enforce_dependencies: package_loaded_yml[ENFORCE_DEPENDENCIES] ? true : false,
+        enforce_privacy: package_loaded_yml[ENFORCE_PRIVACY] ? true : false,
+        metadata: package_loaded_yml[METADATA] || {},
+        dependencies: package_loaded_yml[DEPENDENCIES] || []
+      )
+    end
+
+    sig { returns(Pathname) }
+    def yml
+      Pathname.new(name).join(PACKAGE_YML_NAME).cleanpath
+    end
+
+    sig { returns(Pathname) }
+    def directory
+      Pathname.new(name).cleanpath
+    end
+
+    sig { returns(T::Boolean) }
+    def enforces_dependencies?
+      enforce_dependencies
+    end
+
+    sig { returns(T::Boolean) }
+    def enforces_privacy?
+      enforce_privacy
+    end
+  end
+end

data/lib/parse_packwerk/package_set.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "pathname"
+require 'bundler'
+
+module ParsePackwerk
+  class PackageSet
+    extend T::Sig
+
+    sig { params(package_pathspec: T::Array[String], exclude_pathspec: T::Array[String]).returns(T::Array[Package]) }
+    def self.from(package_pathspec:, exclude_pathspec:)
+      package_glob_patterns = package_pathspec.map do |pathspec|
+        File.join(pathspec, PACKAGE_YML_NAME)
+      end
+
+      # The T.unsafe is because the upstream RBI is wrong for Pathname.glob
+      package_paths = T.unsafe(Pathname).glob(package_glob_patterns)
+        .map(&:cleanpath)
+        .reject { |path| exclude_path?(exclude_pathspec, path) }
+
+      package_paths.uniq.map do |path|
+        Package.from(path)
+      end
+    end
+
+    sig { params(globs: T::Array[String], path: Pathname).returns(T::Boolean) }
+    def self.exclude_path?(globs, path)
+      globs.any? do |glob|
+        path.fnmatch(glob, File::FNM_EXTGLOB)
+      end
+    end
+
+    private_class_method :exclude_path?
+  end
+end

data/lib/parse_packwerk/violation.rb

@@ -0,0 +1,22 @@
+# typed: strict
+
+module ParsePackwerk
+  class Violation < T::Struct
+    extend T::Sig
+
+    const :type, String
+    const :to_package_name, String
+    const :class_name, String
+    const :files, T::Array[String]
+
+    sig { returns(T::Boolean) }
+    def dependency?
+      type == 'dependency'
+    end
+
+    sig { returns(T::Boolean) }
+    def privacy?
+      type == 'privacy'
+    end
+  end
+end

data/lib/parse_packwerk.rb

@@ -0,0 +1,90 @@
+# typed: strict
+
+require 'sorbet-runtime'
+require 'yaml'
+require 'pathname'
+require 'parse_packwerk/constants'
+require 'parse_packwerk/violation'
+require 'parse_packwerk/deprecated_references'
+require 'parse_packwerk/package'
+require 'parse_packwerk/configuration'
+require 'parse_packwerk/package_set'
+
+module ParsePackwerk
+  class MissingConfiguration < StandardError
+    extend T::Sig
+
+    sig { params(packwerk_file_name: Pathname).void }
+    def initialize(packwerk_file_name)
+      super("We could not find a configuration file at #{packwerk_file_name}")
+    end
+  end
+
+  extend T::Sig
+
+  sig do
+    returns(T::Array[Package])
+  end
+  def self.all
+    PackageSet.from(package_pathspec: yml.package_paths, exclude_pathspec: yml.exclude)
+  end
+
+  sig { params(name: String).returns(T.nilable(Package)) }
+  def self.find(name)
+    packages_by_name[name]
+  end
+
+  sig { returns(ParsePackwerk::Configuration) }
+  def self.yml
+    Configuration.fetch
+  end
+
+  sig { params(package: ParsePackwerk::Package).void }
+  def self.write_package_yml!(package)
+    FileUtils.mkdir_p(package.directory)
+    File.open(package.yml, 'w') do |file|
+      # We do not use `YAML.dump` or `contents.to_yaml` because it seems like packwerk writes a variation of the default YAML spec.
+      # If you'd like to see the difference, change this to `package_yaml = YAML.dump(contents)` to and run tests to see the difference.
+      package_yml = <<~PACKAGEYML
+        enforce_dependencies: #{package.enforces_dependencies?}
+        enforce_privacy: #{package.enforces_privacy?}
+      PACKAGEYML
+
+      if package.dependencies.any?
+        dependencies = <<~STATEDDEPS
+          dependencies:
+          #{package.dependencies.map { |dep| "  - #{dep}" }.join("\n")}
+        STATEDDEPS
+
+        package_yml += dependencies
+      end
+
+      if package.metadata.keys.any?
+        raw_yaml = YAML.dump(package.metadata)
+        stylized_yaml = raw_yaml.gsub("---\n", '')
+        indented_yaml = stylized_yaml.split("\n").map { |line| "  #{line}" }.join("\n")
+
+        metadata = <<~METADATA
+          metadata:
+          #{indented_yaml}
+        METADATA
+
+        package_yml += metadata
+      end
+
+      file.write(package_yml)
+    end
+  end
+
+  # We memoize packages_by_name for fast lookup.
+  # Since Graph is an immutable value object, we can create indexes and general caching mechanisms safely.
+  sig { returns(T::Hash[String, Package]) }
+  def self.packages_by_name
+    @packages_by_name = T.let(@packages_by_name, T.nilable(T::Hash[String, Package]))
+    @packages_by_name ||= begin
+      all.map{|p| [p.name, p]}.to_h
+    end
+  end
+
+  private_class_method :packages_by_name
+end

data/sorbet/config

@@ -0,0 +1,3 @@
+--dir
+.
+--ignore=/vendor/bundle

data/sorbet/rbi/gems/hashdiff@1.0.1.rbi

@@ -0,0 +1,82 @@
+# DO NOT EDIT MANUALLY
+# This is an autogenerated file for types exported from the `hashdiff` gem.
+# Please instead update this file by running `bin/tapioca sync`.
+
+# typed: true
+
+module Hashdiff
+  class << self
+    def best_diff(obj1, obj2, options = T.unsafe(nil), &block); end
+    def comparable?(obj1, obj2, strict = T.unsafe(nil)); end
+    def compare_values(obj1, obj2, options = T.unsafe(nil)); end
+    def count_diff(diffs); end
+    def count_nodes(obj); end
+    def custom_compare(method, key, obj1, obj2); end
+    def decode_property_path(path, delimiter = T.unsafe(nil)); end
+    def diff(obj1, obj2, options = T.unsafe(nil), &block); end
+    def diff_array_lcs(arraya, arrayb, options = T.unsafe(nil)); end
+    def lcs(arraya, arrayb, options = T.unsafe(nil)); end
+    def node(hash, parts); end
+    def patch!(obj, changes, options = T.unsafe(nil)); end
+    def prefix_append_array_index(prefix, array_index, opts); end
+    def prefix_append_key(prefix, key, opts); end
+    def similar?(obja, objb, options = T.unsafe(nil)); end
+    def unpatch!(obj, changes, options = T.unsafe(nil)); end
+
+    private
+
+    def any_hash_or_array?(obja, objb); end
+  end
+end
+
+class Hashdiff::CompareHashes
+  class << self
+    def call(obj1, obj2, opts = T.unsafe(nil)); end
+  end
+end
+
+class Hashdiff::LcsCompareArrays
+  class << self
+    def call(obj1, obj2, opts = T.unsafe(nil)); end
+  end
+end
+
+class Hashdiff::LinearCompareArray
+  def initialize(old_array, new_array, options); end
+
+  def call; end
+
+  private
+
+  def additions; end
+  def append_addition(item, index); end
+  def append_addititions_before_match(match_index); end
+  def append_deletion(item, index); end
+  def append_deletions_before_match(match_index); end
+  def append_differences(difference); end
+  def changes; end
+  def compare_at_index; end
+  def deletions; end
+  def differences; end
+  def expected_additions; end
+  def expected_additions=(_arg0); end
+  def extra_items_in_new_array?; end
+  def extra_items_in_old_array?; end
+  def index_of_match_after_additions; end
+  def index_of_match_after_deletions; end
+  def item_difference(old_item, new_item, item_index); end
+  def iterated_through_both_arrays?; end
+  def new_array; end
+  def new_index; end
+  def new_index=(_arg0); end
+  def old_array; end
+  def old_index; end
+  def old_index=(_arg0); end
+  def options; end
+
+  class << self
+    def call(old_array, new_array, options = T.unsafe(nil)); end
+  end
+end
+
+Hashdiff::VERSION = T.let(T.unsafe(nil), String)

data/sorbet/rbi/gems/rspec@3.10.0.rbi

@@ -0,0 +1,34 @@
+# DO NOT EDIT MANUALLY
+# This is an autogenerated file for types exported from the `rspec` gem.
+# Please instead update this file by running `bin/tapioca sync`.
+
+# typed: true
+
+module RSpec
+  class << self
+    def clear_examples; end
+    def configuration; end
+    def configuration=(_arg0); end
+    def configure; end
+    def const_missing(name); end
+    def context(*args, &example_group_block); end
+    def current_example; end
+    def current_example=(example); end
+    def describe(*args, &example_group_block); end
+    def example_group(*args, &example_group_block); end
+    def fcontext(*args, &example_group_block); end
+    def fdescribe(*args, &example_group_block); end
+    def reset; end
+    def shared_context(name, *args, &block); end
+    def shared_examples(name, *args, &block); end
+    def shared_examples_for(name, *args, &block); end
+    def world; end
+    def world=(_arg0); end
+    def xcontext(*args, &example_group_block); end
+    def xdescribe(*args, &example_group_block); end
+  end
+end
+
+RSpec::MODULES_TO_AUTOLOAD = T.let(T.unsafe(nil), Hash)
+module RSpec::Version; end
+RSpec::Version::STRING = T.let(T.unsafe(nil), String)

data/sorbet/rbi/gems/rspec_override.rbi

@@ -0,0 +1,4 @@
+module RSpec
+  module Matchers
+  end
+end

metadata

@@ -0,0 +1,171 @@
+--- !ruby/object:Gem::Specification
+name: parse_packwerk
+version: !ruby/object:Gem::Version
+  version: 0.10.0
+platform: ruby
+authors:
+- Gusto Engineers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.16
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.16
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tapioca
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hashdiff
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A low-dependency gem for parsing and writing packwerk YML files
+email:
+- dev@gusto.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/parse_packwerk.rb
+- lib/parse_packwerk/configuration.rb
+- lib/parse_packwerk/constants.rb
+- lib/parse_packwerk/deprecated_references.rb
+- lib/parse_packwerk/package.rb
+- lib/parse_packwerk/package_set.rb
+- lib/parse_packwerk/violation.rb
+- sorbet/config
+- sorbet/rbi/gems/hashdiff@1.0.1.rbi
+- sorbet/rbi/gems/rspec@3.10.0.rbi
+- sorbet/rbi/gems/rspec_override.rbi
+homepage: https://github.com/bigrails/parse_packwerk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bigrails/parse_packwerk
+  source_code_uri: https://github.com/bigrails/parse_packwerk
+  changelog_uri: https://github.com/bigrails/parse_packwerk/releases
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key: 
+specification_version: 4
+summary: A low-dependency gem for parsing and writing packwerk YML files
+test_files: []