packs-rails 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cd98f383feaab97c239cf1281a65c3fe8c4ab9ca623d69f7138fc8bcc1729092
+  data.tar.gz: d8042586ae2abd53b01fced0e59069d770728272f853e722c27b4bf76e2a9efb
+SHA512:
+  metadata.gz: 9ac6362a82c7cdc78c22683176c3e3b319da85824f1c3013a60fd03816082af280fce9fb605da07431184f81916a982be6ee43f246b516bd195f29d00b811145
+  data.tar.gz: 8b0699e9bed0a6923bf74b70fa614551b0ec446dc3492ec9bdb6fdd5e1ad94b0a2bb5934f4bb806858a97e4017855555adff9c7c84234b748272c8716ec0d182

data/README.md

@@ -0,0 +1,137 @@
+# packs-rails
+
+`packs-rails` establishes and implements a set of conventions for splitting up large monoliths built on top of the [`packs`](https://github.com/rubyatscale/packs) standard. `packs-rails` makes it easy to use [`packwerk`](https://github.com/Shopify/packwerk) to modularize your rails app. With `packs-rails`, new packages' autoload paths are automatically added to Rails, so your code will immediately become usable and loadable without additional configuration.
+
+Here is an example application that uses `packs-rails`:
+```
+package.yml # root level pack
+app/ # Unpackaged code
+  models/
+  ...
+packs/
+  my_domain/
+    package.yml # See the packwerk docs for more info
+    deprecated_references.yml # See the packwerk docs for more info
+    app/
+      public/ # Recommended location for public API
+        my_domain.rb # creates the primary namespaces
+        my_domain/
+          my_subdomain.rb
+      services/ # Private services
+        my_domain/
+          some_private_class.rb
+      models/ # Private models
+        some_other_non_namespaced_private_model.rb # this works too
+        my_domain/
+          my_private_namespacd_model.rb
+      controllers/
+      views/
+    config/
+      initializers/ # Initializers can live in packs and load as expected
+    lib/
+      tasks/
+    spec/ # With packs-rails, specs for a pack live next to the pack
+      public/
+        my_domain_spec.rb
+        my_domain/
+          my_subdomain_spec.rb
+      services/
+        my_domain/
+          some_private_class_spec.rb
+      models/
+        some_other_non_namespaced_private_model_spec.rb
+        my_domain/
+          my_private_namespaced_model_spec.rb
+      factories/ # packs-rails will automatically load pack factories into FactoryBot
+        my_domain/
+          my_private_namespaced_model_factory.rb
+  my_other_domain/
+    ... # other packs have a similar structure
+  my_other_other_domain/
+    ...
+```
+
+## Usage
+
+Setting up `packs-rails` is straightforward. Simply by including `packs-rails` in your `Gemfile` in all environments, `packs-rails` will automatically hook into and configure Rails.
+
+From there, you can create a `./packs` folder and structure it using the conventions listed above.
+
+If you wish to use a different directory name, eg `components` instead of `packs`, you can customize this by configuring `packs.yml`. See [`packs`](https://github.com/rubyatscale/packs) for more information.
+
+### Splitting routes
+`packs-rails` allows you to split your application routes for every pack. You just have to create a file describing your routes and then `draw` them in your root `config/routes.rb` file.
+
+```ruby
+# packs/my_domain/config/routes/my_domain.rb
+resources :my_resource
+
+# config/routes.rb
+draw(:my_domain)
+```
+
+### Making your Package an Engine
+Add `engine: true` to your `package.yml` to make it an actual Rails engine ([read more about what this means here](https://guides.rubyonrails.org/engines.html)):
+```yml
+# packs/my_pack/package.yml
+enforce_dependencies: true
+enforce_privacy: true
+metadata:
+  engine: true
+```
+
+## Ecosystem and Integrations
+
+### RSpec Integration
+Simply add `--require packs/rails/rspec` to your `.rspec`.
+Or, if you'd like, pass it as an argument to `rspec`:
+
+```
+$ rspec --require packs/rails/rspec ...
+```
+
+Integration will allow you to run tests as such:
+```
+# Run all specs in your entire application (packs and all):
+rspec
+
+# Run just that one test:
+rspec spec/some/specific_spec.rb
+
+# Run all tests under the "foobar" pack and all the tests of its nested packs:
+rspec packs/foobar
+
+# Same as above but also adds the "binbaz" pack:
+rspec packs/foobar pack/binbaz
+
+# Run all test files inside the "packs/foobar/spec" directory:
+rspec packs/foobar/spec
+
+# Run all specs under the "packs/foobar/nested_pack" pack:
+rspec packs/foobar/nested_pack
+```
+
+#### parallel_tests
+
+`parallel_tests` has it its own spec discovery mechanism, so packs-rails's RSpec integration doesn't do anything when you use them together.
+To make them work, you'll need to explicitly specify the spec paths:
+
+```bash
+RAILS_ENV=test bundle exec parallel_test spec packs/**/spec -t rspec <other_options>
+```
+
+#### Knapsack (Pro)
+
+Similarly, Knapsack (and its Pro version) has its own spec discovery mechanism and the API will find and queue the relevant specs.
+To make it discover your pack tests as well, you'll need to configure the following variables:
+
+```yaml
+KNAPSACK_PRO_TEST_DIR: spec
+KNAPSACK_PRO_TEST_FILE_PATTERN: '{spec,packs}/**{,/*/**}/*_spec.rb'
+```
+
+Setting `KNAPSACK_PRO_TEST_FILE_PATTERN` will tell Knapsack where your specs are located, while setting `KNAPSACK_PRO_TEST_DIR` is necessary because otherwise an incorrect value is sent to rspec via the `--default-path` option.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rubyatscale/packs-rails.

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "packs-rails"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/tapioca

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'tapioca' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("tapioca", "tapioca")

data/lib/packs/rails/integrations/factory_bot.rb

@@ -0,0 +1,17 @@
+# typed: true
+
+module Packs
+  module Rails
+    module Integrations
+      class FactoryBot
+        def initialize(app)
+          return unless app.config.respond_to?(:factory_bot)
+
+          Packs.all.reject(&:is_gem?).each do |pack|
+            app.config.factory_bot.definition_file_paths << pack.relative_path.join("spec/factories").to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/packs/rails/integrations/rails.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+# typed: true
+
+require "active_support/inflections"
+
+module Packs
+  module Rails
+    module Integrations
+      class Rails
+        def initialize(app)
+          @app = app
+
+          Packs::Rails.config.paths.freeze
+
+          create_engines
+          inject_paths
+        end
+
+        def create_engines
+          Packs.all.reject(&:is_gem?).each do |pack|
+            next unless pack.metadata['engine']
+
+            create_engine(pack)
+          end
+        end
+
+        def inject_paths
+          Packs.all.reject(&:is_gem?).each do |pack|
+            Packs::Rails.config.paths.each do |path|
+              @app.paths[path] << pack.relative_path.join(path)
+            end
+          end
+        end
+
+        private
+
+        def create_namespace(name)
+          namespace = ActiveSupport::Inflector.camelize(name)
+          namespace.split("::").reduce(Object) do |base, mod|
+            if base.const_defined?(mod, false)
+              base.const_get(mod, false)
+            else
+              base.const_set(mod, Module.new)
+            end
+          end
+        end
+
+        def create_engine(pack)
+          name = pack.last_name
+          namespace = create_namespace(name)
+          stim = Stim.new(pack, namespace)
+          namespace.const_set("Engine", Class.new(::Rails::Engine)).include(stim)
+        end
+      end
+    end
+  end
+end

data/lib/packs/rails/integrations/rspec.rb

@@ -0,0 +1,60 @@
+# typed: true
+
+module Packs
+  module Rails
+    module Integrations
+      class RSpec
+        extend T::Sig
+
+        def initialize
+          # This is the list of directories RSpec was told to run.
+          to_run = ::RSpec.configuration.instance_variable_get(:@files_or_directories_to_run)
+          default_path = ::RSpec.configuration.default_path
+
+          if to_run == [default_path]
+            # This is the default case when you run `rspec`. We want to add all the pack's spec paths
+            # to the collection of directories to run.
+
+            pack_paths = Packs.all.map do |pack|
+              spec_path = pack.relative_path.join(default_path)
+              spec_path.to_s if spec_path.exist?
+            end
+
+            to_run.concat(pack_paths)
+          else
+            # This is when `rspec` is run with a list of directories or files. We scan this list to see
+            # if any of them matches a pack's directory. If it does, we concat the `default_path` to the
+            # end of it.
+            #
+            # packs/my_pack => packs/my_pack/spec
+            # 
+            # If it doesn't match a pack path, we leave it alone.
+
+            to_run.map! do |path|
+              if pack = Packs.find(path)
+                [
+                  pack,
+                  *nested_packs_for(pack)
+                ].map do |pack|
+                  spec_path = pack.relative_path.join(default_path)
+                  spec_path.to_s if spec_path.exist?
+                end
+              else
+                path
+              end
+            end
+          end
+
+          ::RSpec.configuration.files_or_directories_to_run = to_run.flatten.compact.uniq
+        end
+
+        sig { params(parent_pack: Packs::Pack).returns(T::Array[Packs::Pack]) }
+        def nested_packs_for(parent_pack)
+          Packs.all.select do |pack|
+            pack.name != parent_pack.name && pack.name.include?(parent_pack.name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/packs/rails/integrations.rb

@@ -0,0 +1,11 @@
+require "active_support"
+
+module Packs
+  module Rails
+    module Integrations
+      autoload :FactoryBot, "packs/rails/integrations/factory_bot"
+      autoload :Rails, "packs/rails/integrations/rails"
+      autoload :RSpec, "packs/rails/integrations/rspec"
+    end
+  end
+end

data/lib/packs/rails/railtie.rb

@@ -0,0 +1,16 @@
+require "rails/railtie"
+
+module Packs
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.before_configuration do |app|
+        Integrations::Rails.new(app)
+        Integrations::FactoryBot.new(app)
+
+        # This is not used within packs-rails. Rather, this allows OTHER tools to
+        # hook into packs-rails via ActiveSupport hooks.
+        ActiveSupport.run_load_hooks(:packs_rails, Packs)
+      end
+    end
+  end
+end

data/lib/packs/rails/rspec.rb

@@ -0,0 +1,3 @@
+require "packs-rails"
+
+Packs::Rails::Integrations::RSpec.new

data/lib/packs/rails/stim.rb

@@ -0,0 +1,42 @@
+# typed: true
+
+module Packs
+  module Rails
+    class Stim < Module
+      extend T::Sig
+
+      sig { params(pack: Packs::Pack, namespace: Module).void }
+      def initialize(pack, namespace)
+        @pack = pack
+        @namespace = namespace
+        super()
+      end
+
+      def included(engine)
+        engine.called_from = @pack.relative_path
+        engine.extend(ClassMethods)
+        engine.isolate_namespace(@namespace)
+
+        # Set all of these paths to nil because we want the Rails integration to take
+        # care of them. The purpose of this Engine is really just for the namespace
+        # isolation.
+        (Packs::Rails.config.paths +
+          # In addition to the paths we've delegated to the main app, we don't allow
+          # Engine Packs to have various capabilities.
+          %w(
+            config/environments
+            db/migrate
+          )
+        ).uniq.each do |path|
+          engine.paths[path] = nil
+        end
+      end
+
+      module ClassMethods
+        def find_root(_from)
+          T.unsafe(self).called_from
+        end
+      end
+    end
+  end
+end

data/lib/packs/rails/version.rb

@@ -0,0 +1,5 @@
+module Packs
+  module Rails
+    VERSION = "0.0.1".freeze
+  end
+end

data/lib/packs-rails.rb

@@ -0,0 +1,43 @@
+require 'packs'
+require "active_support"
+require "rails/application"
+require 'sorbet-runtime'
+
+module Packs
+  module Rails
+    extend ActiveSupport::Autoload
+
+    autoload :Integrations
+    autoload :Railtie
+    autoload :Stim
+
+    class Error < StandardError; end
+
+    class << self
+      attr_reader :config
+
+      def root
+        @root ||= ::Rails::Application.find_root(Dir.pwd)
+      end
+    end
+
+    @config = ActiveSupport::OrderedOptions.new
+    @config.paths = %w(
+      app
+      app/controllers
+      app/channels
+      app/helpers
+      app/models
+      app/mailers
+      app/views
+      lib
+      lib/tasks
+      config
+      config/locales
+      config/initializers
+      config/routes
+    )
+  end
+
+  require "packs/rails/railtie"
+end

metadata

@@ -0,0 +1,185 @@
+--- !ruby/object:Gem::Specification
+name: packs-rails
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ngan Pham
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2023-01-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  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: activesupport
+  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: packs
+  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: 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: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: debug
+  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'
+- !ruby/object:Gem::Dependency
+  name: rails
+  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: packs-rails establishes and implements a set of conventions for splitting
+  up large monoliths.
+email:
+- gusto-opensource-buildkite@gusto.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/console
+- bin/setup
+- bin/tapioca
+- lib/packs-rails.rb
+- lib/packs/rails/integrations.rb
+- lib/packs/rails/integrations/factory_bot.rb
+- lib/packs/rails/integrations/rails.rb
+- lib/packs/rails/integrations/rspec.rb
+- lib/packs/rails/railtie.rb
+- lib/packs/rails/rspec.rb
+- lib/packs/rails/stim.rb
+- lib/packs/rails/version.rb
+homepage: https://github.com/Gusto/packs-rails
+licenses: []
+metadata:
+  homepage_uri: https://github.com/Gusto/packs-rails
+  source_code_uri: https://github.com/Gusto/packs-rails
+  changelog_uri: https://github.com/Gusto/packs-rails/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+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: A Rails helper to package your code.
+test_files: []