bullet_train 1.0.41 → 1.0.46

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87bfe6b6ae9a8c873f110f0360c436e333cb68f0d6f0bb14fd4a458f4747aa29
-  data.tar.gz: 3b76e560de7117ae70b7af138937a3cdb96396fab8d660313335ca374f6fb35a
+  metadata.gz: 9e6c930c4e6fad0f50e6869cdfcceec0b40ac27e4eef3dc04facde80918c9276
+  data.tar.gz: bf9576a58a7c27ac23b46fbacbf93b16a4ac03bae5abc573ffc468e6dce11dc5
 SHA512:
-  metadata.gz: 41a7e50329932973e67dab25af3c0182bc6365ca57b4e8f859a4f691a9e202b0d248383960154a7aa84a0476d013204a1a802bd36b76a9936a3118897b00c1ae
-  data.tar.gz: 62cf5ad94c650779f7639f5a3eaf71d9a5b5f0885822c3ea5d9c5769532a7ebc358e86fbf866ccdd99a855feb512dc52c55d4931a1f87106c96e4f93dcf53244
+  metadata.gz: 9b6f9ce718307c62a69e49faf9948ba43b1fad9269c49b8562683c9deff3f7c00595d5d0216e2d01bf8b0a25a619164d8e48ca37570b0cbace136ec23fa9b7e3
+  data.tar.gz: 534d607fb41150372dcaea0af84b8aa8fa5897c1af3bf6bab4019cfbb06bf565819a543896dd131b081c39c7081b89144159f42e0118278a304ffd21bd745760

data/app/helpers/account/locale_helper.rb

@@ -46,7 +46,7 @@ module Account::LocaleHelper
           begin
             super(key + "💣", options.except(:default))
           rescue I18n::MissingTranslationData => exception
-            full_key = exception.message.rpartition(" ").last.gsub("💣", "")
+            full_key = exception.message.rpartition(" ").last.delete("💣")
           end
         end
       end
@@ -75,7 +75,7 @@ module Account::LocaleHelper
       end
     end
 
-    return result
+    result
   end
 
   # like 't', but if the key isn't found, it returns nil.

data/app/models/invitation.rb

@@ -1,5 +1,5 @@
 class Invitation < ApplicationRecord
-  include Invitations::Core
+  include Invitations::Base
   # 🚅 add concerns above.
 
   # 🚅 add belongs_to associations above.

data/app/models/membership.rb

@@ -1,5 +1,5 @@
 class Membership < ApplicationRecord
-  include Memberships::Core
+  include Memberships::Base
   # 🚅 add concerns above.
 
   # 🚅 add belongs_to associations above.

data/app/models/team.rb

@@ -1,6 +1,6 @@
 class Team < ApplicationRecord
-  include Teams::Core
-  include Webhooks::Outgoing::TeamSupport
+  include Teams::Base
+  # include Webhooks::Outgoing::TeamSupport
   # 🚅 add concerns above.
 
   # 🚅 add belongs_to associations above.

data/app/models/user.rb

@@ -1,5 +1,5 @@
 class User < ApplicationRecord
-  include Users::Core
+  include Users::Base
   # 🚅 add concerns above.
 
   # 🚅 add belongs_to associations above.

data/docs/indirection.md

@@ -1,3 +1,63 @@
-# Overriding Framework Defaults
+# Dealing with Indirection
 
-> TODO This section needs to be written.
+## The Problem with Indirection
+
+In software development, indirection is everywhere and takes many forms.
+
+For example, in vanilla Rails development, you introduce a type of indirection when you extract a button label out of a view file and use the `t` helper to render the string from a translation YAML file. In the future, when another developer goes to update the button label, they will first open the view, they'll see `t(".submit")` and then have to reason a little bit about which translation file they need to open up in order to update that label.
+
+Our goal in Bullet Train is to improve developer experience, not reduce it, so it was important that along with any instances of indirection we were introducing, we also included new tooling to ensure it was never a burden to developers. Thankfully, in practice we found that some of this new tooling improves even layers of indirection that have always been with us in Rails development.
+
+## Figuring Out Class Locations
+
+Most of Bullet Train's functionality is distributed via Ruby gems, not the starter template. As a result, the power of fuzzy searching in your IDE is more limited. For example, `app/controllers/account/users_controller.rb` includes its base functionality from a concern called `Account::Users::ControllerBase`. If you try to fuzzy search for it, you'll quickly find the module isn't included in your application repository. However, you can quickly figure out which Ruby gem is providing that concern and inspect it's source by running:
+
+```
+bin/resolve Account::Users::ControllerBase --open
+```
+
+If you need to modify behavior in these framework-provided classes or modules, see the documentation for [Overriding Framework Defaults](/docs/overriding.md).
+
+## Solving Indirection in Views
+
+### Resolving Partial Paths with `bin/resolve`
+
+Even in vanilla Rails development, when you're looking at a view file, the path you see passed to a `render` call isn't the actual file name of the partial that will be rendered. This is even more true in Bullet Train where certain partial paths are [magically served from theme gems](/docs/themes.md).
+
+`bin/resolve` makes it easy to figure out where where a partial is being served from:
+
+```
+$ bin/resolve shared/box
+```
+
+### Exposing Rendered Views with Xray
+
+> TODO Is this still true in Rails 7? Does it not do something like this by default now?
+
+If you're looking at a rendered view in the browser, it can be hard to know which file to open in order to make a change. To help, Bullet Train includes [Xray](https://github.com/brentd/xray-rails) by default, so you can right click on any element you see, select "Inspect Element", and you'll see comments in the HTML source telling you which file is powering a particular portion of the view, like this:
+
+```
+<!--XRAY START 90 /Users/andrewculver/.rbenv/versions/3.1.1/lib/ruby/gems/3.1.0/gems/bullet_train-themes-light-1.0.10/app/views/themes/light/workflow/_box.html.erb-->
+```
+
+Note that in the example above, the view in question isn't actually coming from the application repository. Instead, it's being included from the `bullet_train-themes-light` package. For instructions on how to customize it, see [Overriding the Framework](/docs/override).
+
+### Drilling Down on Translation Keys
+
+Even in vanilla Rails applications, extracting strings from view files into I18N translation YAML files introduces a layer of indirection. Bullet Train tries to improve the resulting DX with a couple tools that make it easier to figure out where a translation you see in your browser is coming from.
+
+#### Show Translation Keys in the Browser with `?show_locales=true`
+
+You can see the full translation key of any string on the page by adding `?show_locales=true` to the URL.
+
+#### Log Translation Keys to the Console with `?log_locales=true`
+
+You can also log all the translation key for anything being rendered to the console by adding `?log_locales=true` to the request URL. This can make it easier to copy and paste translation keys for strings that are rendered in non-selectable UI elements.
+
+#### Resolving Translation Keys with `bin/resolve`
+
+Once you have the full I18N translation key, you can use `bin/resolve` to figure out which package and file it's coming from. At that point, if you need to customize it, you can also use the `--eject` option to copy the  the framework for customization in your local application:
+
+```
+$ bin/resolve en.account.onboarding.user_details.edit.header --eject --open
+```

data/docs/overriding.md

@@ -1,53 +1,21 @@
-# Dealing with Indirection
+# Overriding Framework Defaults
 
-## The Problem with Indirection
+Most of Bullet Train's functionality is distributed via Ruby gems, not the starter template. We provide the `bin/resolve` tool to help developers figure out which Ruby gem packages are providing which classes, modules, views, and translations, and its usage is covered in the [Dealing With Indirection](/docs/indirection.md) section of the documentation.
 
-In software development, indirection is everywhere and takes many forms.
+However, sometimes you will need to do more than just understand where something is coming from and how it works in the framework. In some situations, you'll specifically want to change or override the default framework behavior. The primary workflow for doing this is much the same as the `bin/resolve` workflow for dealing with indirection in the first place, however, instead of just using `--open` to inspect the source of the framework-provided file, you can add `--eject` to have that file copied into the local repository. From there, it will act as a replacement for the framework-provided file, and you can modify the behavior as needed.
 
-For example, in vanilla Rails development, you introduce a type of indirection when you extract a button label out of a view file and use the `t` helper to render the string from a translation YAML file. In the future, when another developer goes to update the button label, they will first open the view, they'll see `t(".submit")` and then have to reason a little bit about which translation file they need to open up in order to update that label.
+## The Important Role of Active Support Concerns in Bullet Train Customization
 
-Our goal in Bullet Train is to improve developer experience, not reduce it, so it was important that along with any instances of indirection we were introducing, we also included new tooling to ensure it was never a burden to developers. Thankfully, in practice we found that some of this new tooling improves even layers of indirection that have always been with us in Rails development.
+When it comes to object-oriented classes, wholesale copying framework files into your local repository just to be able to modify their behavior or extend them would quickly be untenable, as your app would no longer see upstream updates that would otherwise be incorporated into your application via `bundle update`.
 
-## Solving Indirection in Views
-
-### Resolving Partial Paths with `bin/resolve`
-
-Even in vanilla Rails development, when you're looking at a view file, the path you see passed to a `render` call isn't the actual file name of the partial that will be rendered. This is even more true in Bullet Train where certain partial paths are [magically served from theme gems](/docs/themes.md).
-
-`bin/resolve` makes it easy to figure out where where a partial is being served from:
+For this reason, common points of extension like framework-provided models and controllers actually exist as a kind of "stub" in the local repository, but include their base functionality from framework-provided concerns, like so:
 
 ```
-$ bin/resolve shared/box
-```
-
-### Exposing Rendered Views with Xray
+class User < ApplicationRecord
+  include Users::Base
 
-> TODO Is this still true in Rails 7? Does it not do something like this by default now?
-
-If you're looking at a rendered view in the browser, it can be hard to know which file to open in order to make a change. To help, Bullet Train includes [Xray](https://github.com/brentd/xray-rails) by default, so you can right click on any element you see, select "Inspect Element", and you'll see comments in the HTML source telling you which file is powering a particular portion of the view, like this:
-
-```
-<!--XRAY START 90 /Users/andrewculver/.rbenv/versions/3.1.1/lib/ruby/gems/3.1.0/gems/bullet_train-themes-light-1.0.10/app/views/themes/light/workflow/_box.html.erb-->
+  # ...
+end
 ```
 
-Note that in the example above, the view in question isn't actually coming from the application repository. Instead, it's being included from the `bullet_train-themes-light` package. For instructions on how to customize it, see [Overriding the Framework](/docs/override).
-
-### Drilling Down on Translation Keys
-
-Even in vanilla Rails applications, extracting strings from view files into I18N translation YAML files introduces a layer of indirection. Bullet Train tries to improve the resulting DX with a couple tools that make it easier to figure out where a translation you see in your browser is coming from.
-
-#### Show Translation Keys in the Browser with `?show_locales=true`
-
-You can see the full translation key of any string on the page by adding `?show_locales=true` to the URL.
-
-#### Log Translation Keys to the Console with `?log_locales=true`
-
-You can also log all the translation key for anything being rendered to the console by adding `?log_locales=true` to the request URL. This can make it easier to copy and paste translation keys for strings that are rendered in non-selectable UI elements.
-
-#### Resolving Translation Keys with `bin/resolve`
-
-Once you have the full I18N translation key, you can use `bin/resolve` to figure out which package and file it's coming from. At that point, if you need to customize it, you can also use the `--eject` option to copy the  the framework for customization in your local application:
-
-```
-$ bin/resolve en.account.onboarding.user_details.edit.header --eject --open
-```
+In this case, for most customizations or extensions you would want to make, you don't need to eject `Users::Core` into your local repository. Instead, you can simply re-define methods from that concern in your local `User` model after the inclusion of the concern.

data/lib/bullet_train/resolver.rb

@@ -1,4 +1,4 @@
-require 'io/wait'
+require "io/wait"
 
 module BulletTrain
   class Resolver
@@ -13,28 +13,26 @@ module BulletTrain
       source_file = calculate_source_file_details
 
       if source_file[:absolute_path]
+        puts ""
         if source_file[:package_name].present?
-          puts ""
           puts "Absolute path:".green
           puts "  #{source_file[:absolute_path]}".green
           puts ""
           puts "Package name:".green
           puts "  #{source_file[:package_name]}".green
-          puts ""
         else
-          puts ""
           puts "Project path:".green
           puts "  #{source_file[:project_path]}".green
           puts ""
           puts "Note: If this file was previously ejected from a package, we can no longer see which package it came from. However, it should say at the top of the file where it was ejected from.".yellow
-          puts ""
         end
+        puts ""
 
         if interactive && !eject
           puts "\nWould you like to eject the file into the local project? (y/n)\n"
           input = $stdin.gets
           $stdin.getc while $stdin.ready?
-          if input.first.downcase == 'y'
+          if input.first.downcase == "y"
             eject = true
           end
         end
@@ -46,7 +44,7 @@ module BulletTrain
             else
               `mkdir -p #{source_file[:project_path].split("/")[0...-1].join("/")}`
               puts "Ejecting `#{source_file[:absolute_path]}` to `#{source_file[:project_path]}`".green
-              File.open("#{source_file[:project_path]}", "w+") do |file|
+              File.open((source_file[:project_path]).to_s, "w+") do |file|
                 case source_file[:project_path].split(".").last
                 when "rb", "yml"
                   file.puts "# Ejected from `#{source_file[:package_name]}`.\n\n"
@@ -69,13 +67,13 @@ module BulletTrain
           puts "\nWould you like to open `#{source_file[:absolute_path]}`? (y/n)\n"
           input = $stdin.gets
           $stdin.getc while $stdin.ready?
-          if input.first.downcase == 'y'
+          if input.first.downcase == "y"
             open = true
           end
         end
 
         if open
-          path = source_file[:package_name] ? source_file[:absolute_path] : "#{source_file[:project_path]}"
+          path = source_file[:package_name] ? source_file[:absolute_path] : (source_file[:project_path]).to_s
           puts "Opening `#{path}`.\n".green
           exec "open #{path}"
         end
@@ -121,25 +119,21 @@ module BulletTrain
     end
 
     def class_path
-      begin
-        @needle.constantize
-        return Object.const_source_location(@needle).first
-      rescue NameError => _
-        return false
-      end
+      @needle.constantize
+      Object.const_source_location(@needle).first
+    rescue NameError => _
+      false
     end
 
     def partial_path
-      begin
-        xray_path = ApplicationController.render(template: "bullet_train/partial_resolver", layout: nil, assigns: {needle: @needle}).lines[1].chomp
-        if xray_path.match(/<!--XRAY START \d+ (.*)-->/)
-          return $1
-        else
-          raise "It looks like Xray-rails isn't properly enabled?"
-        end
-      rescue ActionView::Template::Error => _
-        return nil
+      xray_path = ApplicationController.render(template: "bullet_train/partial_resolver", layout: nil, assigns: {needle: @needle}).lines[1].chomp
+      if xray_path =~ /<!--XRAY START \d+ (.*)-->/
+        $1
+      else
+        raise "It looks like Xray-rails isn't properly enabled?"
       end
+    rescue ActionView::Template::Error => _
+      nil
     end
 
     def file_path
@@ -149,7 +143,7 @@ module BulletTrain
 
     def locale_path
       # This is a complete list of translation files provided by this app or any linked Bullet Train packages.
-      (["#{Rails.root.to_s}/config/locales"] + `find ./tmp/gems/*`.lines.map(&:strip).map { |link| File.readlink(link) + "/config/locales" }).each do |locale_source|
+      (["#{Rails.root}/config/locales"] + `find ./tmp/gems/*`.lines.map(&:strip).map { |link| File.readlink(link) + "/config/locales" }).each do |locale_source|
         if File.exist?(locale_source)
           `find -L #{locale_source} | grep ".yml"`.lines.map(&:strip).each do |file_path|
             yaml = YAML.load_file(file_path, aliases: true)
@@ -161,7 +155,7 @@ module BulletTrain
         end
       end
 
-      return nil
+      nil
     end
   end
 end

data/lib/bullet_train/version.rb

@@ -1,3 +1,3 @@
 module BulletTrain
-  VERSION = "1.0.41"
+  VERSION = "1.0.46"
 end

data/lib/tasks/bullet_train_tasks.rake

@@ -1,13 +1,13 @@
-require 'io/wait'
+require "io/wait"
 
 namespace :bt do
   desc "Symlink registered gems in `./tmp/gems` so their views, etc. can be inspected by Tailwind CSS."
-  task :link => :environment do
-    if Dir.exists?("tmp/gems")
+  task link: :environment do
+    if Dir.exist?("tmp/gems")
       puts "Removing previously linked gems."
       `rm -f tmp/gems/*`
     else
-      if File.exists?("tmp/gems")
+      if File.exist?("tmp/gems")
         raise "A file named `tmp/gems` already exists? It has to be removed before we can create the required directory."
       end
 
@@ -43,7 +43,7 @@ namespace :bullet_train do
       $stdin.getc while $stdin.ready?
 
       # Extract absolute paths from XRAY comments.
-      if input.match(/<!--XRAY START \d+ (.*)-->/)
+      if input =~ /<!--XRAY START \d+ (.*)-->/
         input = $1
       end
 
@@ -53,7 +53,7 @@ namespace :bullet_train do
     if ARGV.first.present?
       BulletTrain::Resolver.new(ARGV.first).run(eject: ARGV.include?("--eject"), open: ARGV.include?("--open"), force: ARGV.include?("--force"), interactive: ARGV.include?("--interactive"))
     else
-      $stderr.puts "\n🚅 Usage: `bin/resolve [path, partial, or URL] (--eject) (--open)`\n".blue
+      warn "\n🚅 Usage: `bin/resolve [path, partial, or URL] (--eject) (--open)`\n".blue
     end
   end
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: bullet_train
 version: !ruby/object:Gem::Version
-  version: 1.0.41
+  version: 1.0.46
 platform: ruby
 authors:
 - Andrew Culver
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-03-25 00:00:00.000000000 Z
+date: 2022-04-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: standard
+  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