packs-specification 0.0.8 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fc4e79e4786eb16e964a3431d06fa071f48c7f4ae361c7d9747a50bd1634e76
-  data.tar.gz: 772de64f7ea2558241e0a3c234e3ce7660750fe37c49d09935c11260734bf282
+  metadata.gz: a95a4c598305baa6990d07093e98b49f55c3289c80d384e7beb558bcafde63ca
+  data.tar.gz: b6f2537d04165bee29925da1d29d9613da1b0219227ab397973efc65a1e64259
 SHA512:
-  metadata.gz: 29bf27fd2b72214370cb3513944f8b383bcc06aed7ff82fe92a1954aba1fd22111e6566d3c7158e43b8ca022723214e2e9176af3c7de72200b7cf8835e56c8fe
-  data.tar.gz: 48a3d36d1d9a587ca9c0ccf3fe984c5baf24cc3cc704e4f544deddc19a00661e6545d8361148aeaf3c1a68fe05f7fa3af4b3a75c3be3f4f815c90c0fb88f4dba
+  metadata.gz: 4cc9f93bad4fd2fe25d1d5ac32c4895d6dfcdf64de56b0f6aec31b29129a9a9f902e62f8c5820972efee538e0ecf6f45efd976f2b2bf8dcff577f2369c62d68f
+  data.tar.gz: 0cb00ea631d12ee411150657650da2864303e24c92ce3747471e9328a4018478d490db599f94e3b69e9b9727259e6b4fe5e2ca51e80e881c8e8ec3384b328e00

data/README.md

@@ -1,25 +1,26 @@
 # packs-specification
+This is a low-dependency gem that allows your production environment to query simple information about [`packs`](https://github.com/rubyatscale/packs).
 
-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.
+## Usage
+```ruby
 
-# 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!
-```
+require 'packs-specification'
 
-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).
+# Getting all packs
+# Example use: adding pack paths to a list of fixture paths
+# Returns a T::Array[Packs::Pack]
+Packs.all
 
-# 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.
+# Getting the pack for a specific file
+# Example use: Associating a file with an owner via a pack owner
+# Returns a T.nilable(Packs::Pack)
+Packs.for_file('/path/to/file.rb')
+Packs.for_file(Pathname.new('/path/to/file.rb')) # also works
+
+# Getting a pack with a specific name
+# Example use: Special casing certain behavior for a specific pack
+# Example use: Development tools that operate on user inputted pack names
+# Returns a T.nilable(Packs::Pack)
+Packs.find('packs/my_pack')
+```

data/lib/packs/pack.rb

@@ -13,7 +13,7 @@ module Packs
     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)
+      relative_path = path.relative_path_from(Specification.root)
       package_name = relative_path.cleanpath.to_s
 
       Pack.new(
@@ -36,7 +36,7 @@ module Packs
     end
 
     sig { returns(T::Boolean) }
-    def is_gem?
+    def is_gem? # rubocop:disable Naming/PredicateName
       @is_gem ||= T.let(relative_path.glob('*.gemspec').any?, T.nilable(T::Boolean))
     end
 

data/lib/packs/rspec/support.rb

@@ -5,17 +5,23 @@ RSpec.configure do |config|
 
   config.before do
     # We bust_cache always because each test may write its own packs
-    Packs.bust_cache!
+    Packs::Specification.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
+    if example.metadata[:skip_chdir_to_tmpdir]
       example.run
+    else
+      begin
+        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
-  ensure
-    FileUtils.rm_rf(tmpdir)
   end
 end

data/lib/packs/{private → specification}/configuration.rb

@@ -1,7 +1,7 @@
 # typed: strict
 
 module Packs
-  module Private
+  module Specification
     class Configuration < T::Struct
       extend T::Sig
       CONFIGURATION_PATHNAME = T.let(Pathname.new('packs.yml'), Pathname)

data/lib/packs/specification.rb

@@ -0,0 +1,73 @@
+# typed: strict
+
+require 'packs/specification/configuration'
+
+module Packs
+  module Specification
+    extend T::Sig
+
+    class << self
+      extend T::Sig
+
+      sig { returns(Pathname) }
+      def root
+        Pathname.pwd
+      end
+
+      sig { returns(Configuration) }
+      def config
+        @config = T.let(@config, T.nilable(Configuration))
+        @config ||= Configuration.fetch
+      end
+
+      sig { void }
+      def bust_cache!
+        @packs_by_name = nil
+        @for_file = nil
+        @config = nil
+      end
+
+      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
+
+      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 = Specification.root
+        Specification.config.pack_paths.flat_map do |pack_path|
+          Pathname.glob(absolute_root.join(pack_path).join(PACKAGE_FILE))
+        end
+      end
+    end
+  end
+end

data/lib/packs-specification.rb

@@ -4,8 +4,11 @@ require 'yaml'
 require 'pathname'
 require 'sorbet-runtime'
 require 'packs/pack'
-require 'packs/private'
+require 'packs/specification'
 
+# We let `packs-specification` define some API methods such as all, find, and for_file,
+# because this allows a production environment to require `packs-specification` only and get some simple functionality, without
+# needing to load all of `packs`.
 module Packs
   PACKAGE_FILE = T.let('package.yml'.freeze, String)
 
@@ -14,67 +17,17 @@ module Packs
 
     sig { returns(T::Array[Pack]) }
     def all
-      packs_by_name.values
+      Specification.all
     end
 
     sig { params(name: String).returns(T.nilable(Pack)) }
     def find(name)
-      packs_by_name[name]
+      Specification.find(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
+      Specification.for_file(file_path)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: packs-specification
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.10
 platform: ruby
 authors:
 - Gusto Engineers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-08-09 00:00:00.000000000 Z
+date: 2023-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
@@ -118,10 +118,10 @@ files:
 - README.md
 - lib/packs-specification.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
+- lib/packs/specification.rb
+- lib/packs/specification/configuration.rb
 homepage: https://github.com/rubyatscale/packs-specification
 licenses:
 - MIT

data/lib/packs/private.rb

@@ -1,16 +0,0 @@
-# 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