packs-specification 0.0.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 71b2b5bb84c327f15708d53b5a3da1739fb14e298efa58801409f79d5b17459d
+  data.tar.gz: 124bdf2eaa370451d0ab1d7fc86a1217f6b9bef4d7eedc2eb63f23a67d45f06f
+SHA512:
+  metadata.gz: ae8c0af2ba916b8615cfc8c843c2894dac61969f65f97d5683e66a5db0df65e3c80b7731cd8388dc05fcd49ecef7e51577dba26f67e049803f8794d7cf13503c
+  data.tar.gz: f251bacc060817d2247523a1e373545aac4ced7917a34b8da5ea0ce97be6b62af1615a04002ff35a136507f807f7c9312c6d1ab7a304136bcb5b5b02f7f0bb86

data/README.md

@@ -0,0 +1,25 @@
+# packs-specification
+
+Welcome to `packs-specification`! `packs` are a simple ruby specification for an extensible packaging system to help modularize Ruby applications.
+
+A `pack` (short for `package`) is a folder of Ruby code with a `package.yml` at the root that is intended to represent a well-modularized domain, and the rest of the [rubyatscale](https://github.com/rubyatscale) ecosystem is intended to help make the boundaries between a pack and any other more clear.
+
+# Configuration
+By default, this library will look for `packs` in the folder `packs/*/package.yml` (as well as nested packs at `packs/*/*/package.yml`). To change where `packs` are located, create a `packs.yml` file:
+```
+pack_paths:
+  - "{packs,utilities,deprecated}/*" # packs with multiple roots!
+  - "{packs,utilities,deprecated}/*/*" # nested packs!
+  - gems/* # gems can be packs too!
+```
+
+Here are some example integrations with `packs`:
+- [`packs-rails`](https://github.com/rubyatscale/packs-rails) can be used to integrate `packs` into your `rails` application
+- [`rubocop-packs`](https://github.com/rubyatscale/rubocop-packs) contains cops to improve boundaries around `packs` 
+- [`packwerk`](https://github.com/Shopify/packwerk) and [`packwerk-extensions`](https://github.com/rubyatscale/packwerk-extensions) help you describe and constrain your package graph in terms of dependencies between packs and pack public API
+- [`code_ownership`](https://github.com/rubyatscale/code_ownership) gives your application the capability to determine the owner of a pack
+- [`use_packs`](https://github.com/rubyatscale/use_packs) gives a CLI, `bin/packs`, that makes it easy to create new packs, move files between packs, and more.
+- [`pack_stats`](https://github.com/rubyatscale/pack_stats) makes it easy to send metrics about pack adoption and modularization to your favorite metrics provider, such as DataDog (which has built-in support).
+
+# How is a pack different from a gem?
+A ruby [`gem`](https://guides.rubygems.org/what-is-a-gem/) is the Ruby community solution for packaging and distributing Ruby code. A gem is a great place to start new projects, and a great end state for code that's been extracted from an existing codebase. `packs` are intended to help gradually modularize an application that has some conceptual boundaries, but is not yet ready to be factored into gems.

data/lib/packs/pack.rb

@@ -0,0 +1,48 @@
+# typed: strict
+
+module Packs
+  class Pack < T::Struct
+    extend T::Sig
+
+    const :name, String
+    const :path, Pathname
+    const :relative_path, Pathname
+    const :raw_hash, T::Hash[T.untyped, T.untyped]
+
+    sig { params(package_yml_absolute_path: Pathname).returns(Pack) }
+    def self.from(package_yml_absolute_path)
+      package_loaded_yml = YAML.load_file(package_yml_absolute_path)
+      path = package_yml_absolute_path.dirname
+      relative_path = path.relative_path_from(Private.root)
+      package_name = relative_path.cleanpath.to_s
+
+      Pack.new(
+        name: package_name,
+        path: path,
+        relative_path: relative_path,
+        raw_hash: package_loaded_yml || {}
+      )
+    end
+
+    sig { params(relative: T::Boolean).returns(Pathname) }
+    def yml(relative: true)
+      path_to_use = relative ? relative_path : path
+      path_to_use.join(PACKAGE_FILE).cleanpath
+    end
+
+    sig { returns(String) }
+    def last_name
+      relative_path.basename.to_s
+    end
+
+    sig { returns(T::Boolean) }
+    def is_gem?
+      @is_gem ||= T.let(relative_path.glob('*.gemspec').any?, T.nilable(T::Boolean))
+    end
+
+    sig { returns(T::Hash[T.untyped, T.untyped]) }
+    def metadata
+      raw_hash['metadata'] || {}
+    end
+  end
+end

data/lib/packs/private/configuration.rb

@@ -0,0 +1,36 @@
+# typed: strict
+
+module Packs
+  module Private
+    class Configuration < T::Struct
+      extend T::Sig
+      CONFIGURATION_PATHNAME = T.let(Pathname.new('packs.yml'), Pathname)
+
+      DEFAULT_PACK_PATHS = T.let([
+                                   'packs/*',
+                                   'packs/*/*'
+                                 ], T::Array[String])
+
+      prop :pack_paths, T::Array[String]
+
+      sig { returns(Configuration) }
+      def self.fetch
+        config_hash = CONFIGURATION_PATHNAME.exist? ? YAML.load_file(CONFIGURATION_PATHNAME) : {}
+
+        new(
+          pack_paths: pack_paths(config_hash)
+        )
+      end
+
+      sig { params(config_hash: T::Hash[T.untyped, T.untyped]).returns(T::Array[String]) }
+      def self.pack_paths(config_hash)
+        specified_pack_paths = config_hash['pack_paths']
+        if specified_pack_paths.nil?
+          DEFAULT_PACK_PATHS.dup
+        else
+          Array(specified_pack_paths)
+        end
+      end
+    end
+  end
+end

data/lib/packs/private.rb

@@ -0,0 +1,16 @@
+# typed: strict
+
+require 'packs/private/configuration'
+
+module Packs
+  module Private
+    extend T::Sig
+
+    sig { returns(Pathname) }
+    def self.root
+      Pathname.pwd
+    end
+  end
+
+  private_constant :Private
+end

data/lib/packs/rspec/fixture_helper.rb

@@ -0,0 +1,33 @@
+# typed: strict
+# frozen_string_literal: true
+
+module FixtureHelper
+  extend T::Sig
+
+  sig { params(path: String, content: String).returns(String) }
+  def write_file(path, content = '')
+    pathname = Pathname.pwd.join(path)
+    FileUtils.mkdir_p(pathname.dirname)
+    pathname.write(content)
+    path
+  end
+
+  sig do
+    params(
+      pack_name: String,
+      config: T::Hash[T.untyped, T.untyped]
+    ).void
+  end
+  def write_pack(
+    pack_name,
+    config = {}
+  )
+    path = Pathname.pwd.join(pack_name).join('package.yml')
+    write_file(path.to_s, YAML.dump(config))
+  end
+
+  sig { params(path: String).void }
+  def delete_app_file(path)
+    File.delete(path)
+  end
+end

data/lib/packs/rspec/support.rb

@@ -0,0 +1,21 @@
+require_relative 'fixture_helper'
+
+RSpec.configure do |config|
+  config.include FixtureHelper
+
+  config.before do
+    # We bust_cache always because each test may write its own packs
+    Packs.bust_cache!
+  end
+
+  # Eventually, we could make this opt-in via metadata so someone can use this support without affecting all their tests.
+  config.around do |example|
+    prefix = [File.basename($0), Process.pid].join('-') # rubocop:disable Style/SpecialGlobalVars
+    tmpdir = Dir.mktmpdir(prefix)
+    Dir.chdir(tmpdir) do
+      example.run
+    end
+  ensure
+    FileUtils.rm_rf(tmpdir)
+  end
+end

data/lib/packs.rb

@@ -0,0 +1,80 @@
+# typed: strict
+
+require 'yaml'
+require 'pathname'
+require 'sorbet-runtime'
+require 'packs/pack'
+require 'packs/private'
+
+module Packs
+  PACKAGE_FILE = T.let('package.yml'.freeze, String)
+
+  class << self
+    extend T::Sig
+
+    sig { returns(T::Array[Pack]) }
+    def all
+      packs_by_name.values
+    end
+
+    sig { params(name: String).returns(T.nilable(Pack)) }
+    def find(name)
+      packs_by_name[name]
+    end
+
+    sig { params(file_path: T.any(Pathname, String)).returns(T.nilable(Pack)) }
+    def for_file(file_path)
+      path_string = file_path.to_s
+      @for_file = T.let(@for_file, T.nilable(T::Hash[String, T.nilable(Pack)]))
+      @for_file ||= {}
+      @for_file[path_string] ||= all.find { |package| path_string.start_with?("#{package.name}/") || path_string == package.name }
+    end
+
+    sig { void }
+    def bust_cache!
+      @packs_by_name = nil
+      @config = nil
+      @for_file = nil
+    end
+
+    sig { returns(Private::Configuration) }
+    def config
+      @config = T.let(@config, T.nilable(Private::Configuration))
+      @config ||= Private::Configuration.fetch
+    end
+
+    sig { params(blk: T.proc.params(arg0: Private::Configuration).void).void }
+    def configure(&blk)
+      # If packs.yml is being used, then ignore direct configuration.
+      # This is only a stop-gap to permit Stimpack users to more easily migrate
+      # to packs.yml
+      return if Private::Configuration::CONFIGURATION_PATHNAME.exist?
+
+      yield(config)
+    end
+
+    private
+
+    sig { returns(T::Hash[String, Pack]) }
+    def packs_by_name
+      @packs_by_name = T.let(@packs_by_name, T.nilable(T::Hash[String, Pack]))
+      @packs_by_name ||= begin
+        all_packs = package_glob_patterns.map do |path|
+          Pack.from(path)
+        end
+
+        # We want to match more specific paths first so for_file works correctly.
+        sorted_packages = all_packs.sort_by { |package| -package.name.length }
+        sorted_packages.to_h { |p| [p.name, p] }
+      end
+    end
+
+    sig { returns(T::Array[Pathname]) }
+    def package_glob_patterns
+      absolute_root = Private.root
+      config.pack_paths.flat_map do |pack_path|
+        Pathname.glob(absolute_root.join(pack_path).join(PACKAGE_FILE))
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: packs-specification
+version: !ruby/object:Gem::Version
+  version: 0.0.7
+platform: ruby
+authors:
+- Gusto Engineers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-08-09 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: rubocop
+  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: 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'
+description: The specification for packs in the `rubyatscale` ecosystem.
+email:
+- dev@gusto.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/packs.rb
+- lib/packs/pack.rb
+- lib/packs/private.rb
+- lib/packs/private/configuration.rb
+- lib/packs/rspec/fixture_helper.rb
+- lib/packs/rspec/support.rb
+homepage: https://github.com/rubyatscale/packs-specification
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rubyatscale/packs-specification
+  source_code_uri: https://github.com/rubyatscale/packs-specification
+  changelog_uri: https://github.com/rubyatscale/packs-specification/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.1.6
+signing_key: 
+specification_version: 4
+summary: The specification for packs in the `rubyatscale` ecosystem.
+test_files: []