suspenders 20230113.0 → 20240516.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 606737b8d87f3fe7ccfae7c15d214df27de810600e1cb77873025d1af0f17f3d
-  data.tar.gz: 10ab96b1b4eb893b86cb9ddd40146fdb49c99d51fe03aecf579148ca7a6cbf46
+  metadata.gz: 8c2709f640163cac9a711d3fbc428db7771bf0082f8052f0e37cf1b60357fcbf
+  data.tar.gz: 8a2d49d93399ead80a3ef658124bd3657fb68bc923b3091bc42f390c22b9abf4
 SHA512:
-  metadata.gz: 8d8f0be9c9c48c24cbd459575552dba6f3a93ad669472235e3e2a00bbe26c7cd114a798a527b8b0faeb226aaeb91bad8a98930502e82cf4e2995c90f40070d02
-  data.tar.gz: '08f52691df274a0187571d59020ca241a564ce442ac5b60427eb7a93087563fc3bb73b1719042ec957d38ed84071d0c06260a2cd18c2ca0124a7cbfd57e05ad1'
+  metadata.gz: ad3ba6902b12457e407ac81beade17ec912918d64a0e58eb7874c8214f861deead37497e06214fbae8effc30e7dfff02b4c0006a23a7b6bf0a03f4977538a18b
+  data.tar.gz: f3e992788aa0424a1b198ae611a9bed2542d80c12b321946a02fdf17fc05126f6f9b7a86fccbe2470aba77a72bc02612603fcfa072fba621b458e5c3d9981afe

data/README.md

@@ -1,225 +1,132 @@
 # Suspenders
 
-[![Build Status](https://github.com/thoughtbot/suspenders/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/thoughtbot/suspenders/actions)
-[![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)
-
-Suspenders is the base Rails application used at
-[thoughtbot](https://thoughtbot.com/).
-
-  ![Suspenders boy](http://media.tumblr.com/1TEAMALpseh5xzf0Jt6bcwSMo1_400.png)
-
-## Installation
-
-First install the suspenders gem:
-
-    gem install suspenders
-
-Then run:
-
-    suspenders projectname
-
-This will create a Rails app in `projectname` using the latest version of Rails.
-
-### Associated services
-
-* Enable [Circle CI](https://circleci.com/) Continuous Integration
-* Enable [GitHub auto deploys to Heroku staging and review
-    apps](https://dashboard.heroku.com/apps/app-name-staging/deploy/github).
-
-## Gemfile
-
-To see the latest and greatest gems, look at Suspenders'
-[Gemfile](templates/Gemfile.erb), which will be appended to the default
-generated projectname/Gemfile.
-
-It includes application gems like:
-
-* [Sidekiq](https://github.com/mperham/sidekiq) for background
-  processing
-* [High Voltage](https://github.com/thoughtbot/high_voltage) for static pages
-* [Honeybadger](https://www.honeybadger.io/?affiliate=A43uwl) for exception notification
-* [Oj](http://www.ohler.com/oj/)
-* [Postgres](https://github.com/ged/ruby-pg) for access to the Postgres database
-* [Rack Canonical Host](https://github.com/tylerhunt/rack-canonical-host) to
-  ensure all requests are served from the same domain
-* [Rack Timeout](https://github.com/heroku/rack-timeout) to abort requests that are
-  taking too long
-* [Recipient Interceptor](https://github.com/croaky/recipient_interceptor) to
-  avoid accidentally sending emails to real people from staging
-* [Simple Form](https://github.com/plataformatec/simple_form) for form markup
-  and style
-* [Skylight](https://www.skylight.io/) for monitoring performance
-* [Title](https://github.com/calebthompson/title) for storing titles in
-  translations
-
-And development gems like:
-
-* [Dotenv](https://github.com/bkeepers/dotenv) for loading environment variables
-* [Pry Rails](https://github.com/rweng/pry-rails) for interactively exploring
-  objects
-* [ByeBug](https://github.com/deivid-rodriguez/byebug) for interactively
-  debugging behavior
-* [Bullet](https://github.com/flyerhzm/bullet) for help to kill N+1 queries and
-  unused eager loading
-* [Bundler Audit](https://github.com/rubysec/bundler-audit) for scanning the
-  Gemfile for insecure dependencies based on published CVEs
-* [Web Console](https://github.com/rails/web-console) for better debugging via
-  in-browser IRB consoles.
+[![CI](https://github.com/thoughtbot/suspenders/actions/workflows/main.yml/badge.svg)](https://github.com/thoughtbot/suspenders/actions/workflows/main.yml)
 
-And testing gems like:
+Suspenders is a [Rails Engine][] containing generators for configuring Rails
+applications with these [features][].
 
-* [Capybara](https://github.com/jnicklas/capybara) and
-  [Google Chromedriver]
-  integration testing
-* [capybara_accessibility_audit](https://github.com/thoughtbot/capybara_accessibility_audit) and
-  [capybara_accessible_selectors](https://github.com/citizensadvice/capybara_accessible_selectors)
-* [Factory Bot](https://github.com/thoughtbot/factory_bot) for test data
-* [Formulaic](https://github.com/thoughtbot/formulaic) for integration testing
-  HTML forms
-* [RSpec](https://github.com/rspec/rspec) for unit testing
-* [RSpec Mocks](https://github.com/rspec/rspec-mocks) for stubbing and spying
-* [Shoulda Matchers](https://github.com/thoughtbot/shoulda-matchers) for common
-  RSpec matchers
-* [Timecop](https://github.com/travisjeffery/timecop) for testing time
+It is used by thoughtbot to get a jump start on a new or existing app. Use
+Suspenders if you're in a rush to build something amazing; don't use it if you
+like missing deadlines.
 
-## Other goodies
+[Rails Engine]: https://guides.rubyonrails.org/engines.html
+[features]: ./FEATURES.md
 
-Suspenders also comes with:
+![Suspenders boy](https://media.tumblr.com/1TEAMALpseh5xzf0Jt6bcwSMo1_400.png)
 
-* The [`./bin/setup`][setup] convention for new developer setup
-* The `./bin/deploy` convention for deploying to Heroku
-* Rails' flashes set up and in application layout
-* A few nice time formats set up for localization
-* `Rack::Deflater` to [compress responses with Gzip][compress]
-* A [low database connection pool limit][pool]
-* [Safe binstubs][binstub]
-* [t() and l() in specs without prefixing with I18n][i18n]
-* An automatically-created `SECRET_KEY_BASE` environment variable in all
-  environments
-* Configuration for [CircleCI][circle] Continuous Integration (tests)
-* Configuration for [Hound][hound] Continuous Integration (style)
-* Configuration for [stylelint][stylelint]
-* The analytics adapter [Segment][segment] (and therefore config for Google
-  Analytics, Intercom, Facebook Ads, Twitter Ads, etc.)
-* [PostCSS Autoprefixer][autoprefixer] for CSS vendor prefixes
-* [PostCSS Normalize][normalize] for resetting browser styles
+## Requirements
 
-[setup]: https://robots.thoughtbot.com/bin-setup
-[compress]: https://robots.thoughtbot.com/content-compression-with-rack-deflater
-[pool]: https://devcenter.heroku.com/articles/concurrency-and-database-connections
-[binstub]: https://github.com/thoughtbot/suspenders/pull/282
-[i18n]: https://github.com/thoughtbot/suspenders/pull/304
-[circle]: https://circleci.com/docs
-[hound]: https://houndci.com
-[stylelint]: https://stylelint.io/
-[segment]: https://segment.com
-[autoprefixer]: https://github.com/postcss/autoprefixer
-[normalize]: https://github.com/csstools/postcss-normalize
+- Rails `~> 7.0`
+- Ruby `>= 3.1`
+- Node `>= 20.0.0`
 
-## Heroku
+## Usage
 
-Read the documentation on [deploying to Heroku][heroku deploy]
+Suspenders can be used to create a new Rails application, or to enhance an
+existing Rails application.
 
-You can optionally create Heroku staging and production apps:
+### With New Rails Applications
 
-    suspenders app --heroku true
+This approach uses an [application template][] to generate a new Rails
+application with Suspenders.
 
-This:
+We skip the [default test framework][] in favor of [RSpec][], and [prefer
+PostgreSQL][] as our database.
 
-* Creates a staging and production Heroku app
-* Sets them as `staging` and `production` Git remotes
-* Configures staging with `HONEYBADGER_ENV` environment variable set
-  to `staging`
-* Creates a [Heroku Pipeline] for review apps
-* Schedules automated backups for 10AM UTC for both `staging` and `production`
+```
+rails new app_name \
+ --skip-test \
+ -d=postgresql \
+ -m=https://raw.githubusercontent.com/thoughtbot/suspenders/main/lib/install/web.rb
+```
 
-[Heroku Pipeline]: https://devcenter.heroku.com/articles/pipelines
-[heroku deploy]: https://github.com/thoughtbot/suspenders/blob/master/docs/heroku_deploy.md
+Then run `bin/setup` within the newly generated application.
 
-You can optionally specify alternate Heroku flags:
+Alternatively, if you're using our [dotfiles][], then you can just run `rails new
+app_name`, or create your own [railsrc][] file with the following configuration:
 
-    suspenders app \
-      --heroku true \
-      --heroku-flags "--region eu --addons sendgrid,ssl"
+```
+--skip-test
+--database=postgresql
+-m=https://raw.githubusercontent.com/thoughtbot/suspenders/main/lib/install/web.rb
+```
 
-See all possible Heroku flags:
+[application template]: https://guides.rubyonrails.org/rails_application_templates.html
+[default test framework]: https://guides.rubyonrails.org/testing.html
+[RSpec]: http://rspec.info
+[prefer PostgreSQL]: https://github.com/thoughtbot/dotfiles/pull/728
+[dotfiles]: https://github.com/thoughtbot/dotfiles
+[railsrc]: https://github.com/rails/rails/blob/7f7f9df8641e35a076fe26bd097f6a1b22cb4e2d/railties/lib/rails/generators/rails/app/USAGE#L5C1-L7
 
-    heroku help create
+### With Existing Rails Applications
 
-## Git
+Suspenders can be used on an existing Rails application by adding it to the
+`:development` and `:test` group.
 
-This will initialize a new git repository for your Rails app. You can
-bypass this with the `--skip-git` option:
+```ruby
+group :development, :test do
+  gem "suspenders"
+end
+```
 
-    suspenders app --skip-git true
+Once installed, you can invoke the web installation generator, which will
+invoke all generators.
 
-## GitHub
+```
+bin/rails g suspenders:install:web
+```
 
-You can optionally create a GitHub repository for the suspended Rails app. It
-requires that you have [Hub](https://github.com/github/hub) on your system:
+Or, you can invoke generators individually. To see a list of available
+generators run:
 
-    brew install hub # macOS, for other systems see https://github.com/github/hub#installation
-    suspenders app --github organization/project
+```
+bin/rails g | grep suspenders
+```
 
-This has the same effect as running:
+To learn more about a generator, run:
 
-    hub create organization/project
+```
+bin/rails g suspenders:[generator_name] --help
+```
 
-## Dependencies
+### Available Tasks
 
-Suspenders requires the latest version of Ruby.
+Suspenders ships with several custom Rake tasks.
 
-Some gems included in Suspenders have native extensions. You should have GCC
-installed on your machine before generating an app with Suspenders.
-
-Use [OS X GCC Installer](https://github.com/kennethreitz/osx-gcc-installer/) for
-Snow Leopard (OS X 10.6).
-
-Use [Command Line Tools for Xcode](https://developer.apple.com/downloads/index.action)
-for Lion (OS X 10.7) or Mountain Lion (OS X 10.8).
-
-We use [Google Chromedriver] for full-stack JavaScript integration testing. It
-requires Google Chrome or Chromium.
-
-[Google Chromedriver]: https://sites.google.com/a/chromium.org/chromedriver/home
-
-PostgreSQL needs to be installed and running for the `db:create` rake task.
-
-Redis needs to be installed and running for Sidekiq
-
-## Issues
-
-If you have problems, please create a
-[GitHub Issue](https://github.com/thoughtbot/suspenders/issues).
+```
+bin/rails suspenders:rake
+bin/rails suspenders:db:migrate
+bin/rails suspenders:cleanup:organize_gemfile
+```
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md).
-
+See the [CONTRIBUTING] document.
 Thank you, [contributors]!
 
+[CONTRIBUTING]: CONTRIBUTING.md
 [contributors]: https://github.com/thoughtbot/suspenders/graphs/contributors
 
 ## License
 
-Suspenders is Copyright © 2008-2017 thoughtbot.
-It is free software,
-and may be redistributed under the terms specified in the [LICENSE] file.
+Suspenders is Copyright (c) thoughtbot, inc.
+It is free software, and may be redistributed
+under the terms specified in the [LICENSE] file.
+
+[LICENSE]: /LICENSE
 
-[LICENSE]: LICENSE
+## About
 
-## About thoughtbot
+Suspenders is maintained by [thoughtbot].
 
-[![thoughtbot][thoughtbot-logo]][thoughtbot]
+![thoughtbot](https://thoughtbot.com/brand_assets/93:44.svg)
 
 Suspenders is maintained and funded by thoughtbot, inc.
 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
 
 We love open source software!
-See [our other projects][community].
-We are [available for hire][hire].
+See [our other projects][community]
+or [hire us][hire] to help build your product.
 
-[thoughtbot]: https://thoughtbot.com?utm_source=github
-[thoughtbot-logo]: https://thoughtbot.com/brand_assets/93:44.svg
 [community]: https://thoughtbot.com/community?utm_source=github
-[hire]: https://thoughtbot.com?utm_source=github
+[hire]: https://thoughtbot.com/hire-us?utm_source=github

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+require "minitest/test_task"
+require "standard/rake"
+
+Minitest::TestTask.create(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.warning = false
+  t.test_globs = ["test/**/*_test.rb"]
+end
+
+task default: %i[test standard]

data/lib/generators/suspenders/accessibility_generator.rb

@@ -0,0 +1,24 @@
+module Suspenders
+  module Generators
+    class AccessibilityGenerator < Rails::Generators::Base
+      include Suspenders::Generators::APIAppUnsupported
+
+      desc <<~MARKDOWN
+        Uses [capybara_accessibility_audit][] and
+        [capybara_accessible_selectors][] to encourage and enforce accessibility best
+        practices.
+
+        [capybara_accessibility_audit]: https://github.com/thoughtbot/capybara_accessibility_audit
+        [capybara_accessible_selectors]: https://github.com/citizensadvice/capybara_accessible_selectors
+      MARKDOWN
+
+      def add_capybara_gems
+        gem_group :test do
+          gem "capybara_accessibility_audit", github: "thoughtbot/capybara_accessibility_audit"
+          gem "capybara_accessible_selectors", github: "citizensadvice/capybara_accessible_selectors"
+        end
+        Bundler.with_unbundled_env { run "bundle install" }
+      end
+    end
+  end
+end

data/lib/generators/suspenders/advisories_generator.rb

@@ -0,0 +1,32 @@
+module Suspenders
+  module Generators
+    class AdvisoriesGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../templates/advisories", __FILE__)
+      desc <<~MARKDOWN
+        Uses [bundler-audit][] to update the local security database and show
+        any relevant issues with the app's dependencies via a Rake task.
+
+        [bundler-audit]: https://github.com/rubysec/bundler-audit
+      MARKDOWN
+
+      def add_bundler_audit
+        gem_group :development, :test do
+          gem "bundler-audit", ">= 0.7.0", require: false
+        end
+        Bundler.with_unbundled_env { run "bundle install" }
+      end
+
+      def modify_rakefile
+        content = <<~RUBY
+
+          if Rails.env.local?
+            require "bundler/audit/task"
+            Bundler::Audit::Task.new
+          end
+        RUBY
+
+        insert_into_file "Rakefile", content, after: /require_relative "config\/application"\n/
+      end
+    end
+  end
+end

data/lib/generators/suspenders/ci_generator.rb

@@ -0,0 +1,57 @@
+module Suspenders
+  module Generators
+    class CiGenerator < Rails::Generators::Base
+      include Suspenders::Generators::DatabaseUnsupported
+      include Suspenders::Generators::Helpers
+
+      source_root File.expand_path("../../templates/ci", __FILE__)
+      desc <<~MARKDOWN
+        Uses [GitHub Actions][] for CI, and [Dependabot][] for dependency updates.
+
+        [GitHub Actions]: https://docs.github.com/en/actions
+        [Dependabot]: https://docs.github.com/en/code-security/dependabot/working-with-dependabot
+      MARKDOWN
+
+      def ci_files
+        empty_directory ".github/workflows"
+        template "ci.yml", ".github/workflows/ci.yaml"
+        template "dependabot.yml", ".github/dependabot.yaml"
+      end
+
+      private
+
+      def scan_ruby?
+        has_gem? "bundler-audit"
+      end
+
+      def scan_js?
+        File.exist?("bin/importmap") && using_node?
+      end
+
+      def lint?
+        using_node? && has_gem?("standard") && has_yarn_script?("lint")
+      end
+
+      def using_node?
+        File.exist? "package.json"
+      end
+
+      def has_gem?(name)
+        Bundler.rubygems.find_name(name).any?
+      end
+
+      def using_rspec?
+        File.exist? "spec"
+      end
+
+      def has_yarn_script?(name)
+        return false if !using_node?
+
+        content = File.read("package.json")
+        json = JSON.parse(content)
+
+        json.dig("scripts", name)
+      end
+    end
+  end
+end

data/lib/generators/suspenders/email_generator.rb

@@ -0,0 +1,56 @@
+module Suspenders
+  module Generators
+    class EmailGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../templates/email", __FILE__)
+      desc <<~MARKDOWN
+        [Intercept][] emails in non-production environments by setting `INTERCEPTOR_ADDRESSES`.
+
+        ```sh
+        INTERCEPTOR_ADDRESSES="user_1@example.com,user_2@example.com" bin/rails s
+        ```
+
+        Configuration can be found at `config/initializers/email_interceptor.rb`.
+
+        Interceptor can be found at `app/mailers/email_interceptor.rb`.
+
+        [Intercept]: https://guides.rubyonrails.org/action_mailer_basics.html#intercepting-emails
+      MARKDOWN
+
+      def create_email_interceptor
+        copy_file "email_interceptor.rb", "app/mailers/email_interceptor.rb"
+      end
+
+      def create_email_interceptor_initializer
+        initializer "email_interceptor.rb", <<~RUBY
+          Rails.application.configure do
+            if ENV["INTERCEPTOR_ADDRESSES"].present?
+              config.action_mailer.interceptors = %w[EmailInterceptor]
+            end
+          end
+        RUBY
+      end
+
+      def configure_email_interceptor
+        environment do
+          %(
+            config.to_prepare do
+              EmailInterceptor.config.interceptor_addresses = ENV.fetch("INTERCEPTOR_ADDRESSES", "").split(",")
+            end
+          )
+        end
+      end
+
+      # TODO: Remove once https://github.com/rails/rails/pull/51191 is in latest
+      # Rails release
+      def configure_development_environment
+        environment %(config.action_mailer.default_url_options = { host: "localhost", port: 3000 }), env: "development"
+      end
+
+      # TODO: Remove once https://github.com/rails/rails/pull/51191 is in latest
+      # Rails release
+      def configure_test_environment
+        environment %(config.action_mailer.default_url_options = { host: "www.example.com" }), env: "test"
+      end
+    end
+  end
+end

data/lib/generators/suspenders/environments/development_generator.rb

@@ -0,0 +1,50 @@
+module Suspenders
+  module Generators
+    module Environments
+      class DevelopmentGenerator < Rails::Generators::Base
+        desc <<~MARKDOWN
+          - Enables [raise_on_missing_translations][].
+          - Enables [annotate_rendered_view_with_filenames][].
+          - Enables [i18n_customize_full_message][].
+          - Enables [query_log_tags_enabled][].
+
+          [raise_on_missing_translations]: https://guides.rubyonrails.org/configuring.html#config-i18n-raise-on-missing-translations
+          [annotate_rendered_view_with_filenames]: https://guides.rubyonrails.org/configuring.html#config-action-view-annotate-rendered-view-with-filenames
+          [i18n_customize_full_message]: https://guides.rubyonrails.org/configuring.html#config-active-model-i18n-customize-full-message
+          [query_log_tags_enabled]: https://guides.rubyonrails.org/configuring.html#config-active-record-query-log-tags-enabled
+        MARKDOWN
+
+        def raise_on_missing_translations
+          if development_config.match?(/^\s#\s*config\.i18n\.raise_on_missing_translations/)
+            uncomment_lines "config/environments/development.rb", "config.i18n.raise_on_missing_translations = true"
+          else
+            environment %(config.i18n.raise_on_missing_translations = true), env: "development"
+          end
+        end
+
+        def annotate_render_view_with_filename
+          if development_config.match?(/^\s#\s*config\.action_view\.annotate_render_view_with_filename/)
+            uncomment_lines "config/environments/development.rb",
+              "config.action_view.annotate_rendered_view_with_filenames = true"
+          else
+            environment %(config.action_view.annotate_rendered_view_with_filenames = true), env: "development"
+          end
+        end
+
+        def enable_i18n_customize_full_message
+          environment %(config.active_model.i18n_customize_full_message = true), env: "development"
+        end
+
+        def enable_query_log_tags_enabled
+          environment %(config.active_record.query_log_tags_enabled = true), env: "development"
+        end
+
+        private
+
+        def development_config
+          File.read(Rails.root.join("config/environments/development.rb"))
+        end
+      end
+    end
+  end
+end

data/lib/generators/suspenders/environments/production_generator.rb

@@ -0,0 +1,27 @@
+module Suspenders
+  module Generators
+    module Environments
+      class ProductionGenerator < Rails::Generators::Base
+        desc <<~MARKDOWN
+          - Enables [require_master_key][].
+
+          [require_master_key]: https://guides.rubyonrails.org/configuring.html#config-require-master-key
+        MARKDOWN
+
+        def require_master_key
+          if production_config.match?(/^\s*#\s*config\.require_master_key\s*=\s*true/)
+            uncomment_lines "config/environments/production.rb", /config\.require_master_key\s*=\s*true/
+          else
+            environment %(config.require_master_key = true), env: "production"
+          end
+        end
+
+        private
+
+        def production_config
+          File.read(Rails.root.join("config/environments/production.rb"))
+        end
+      end
+    end
+  end
+end

data/lib/generators/suspenders/environments/test_generator.rb

@@ -0,0 +1,39 @@
+module Suspenders
+  module Generators
+    module Environments
+      class TestGenerator < Rails::Generators::Base
+        desc <<~MARKDOWN
+          - Enables [raise_on_missing_translations][].
+          - Disables [action_dispatch.show_exceptions][].
+
+          [raise_on_missing_translations]: https://guides.rubyonrails.org/configuring.html#config-i18n-raise-on-missing-translations
+          [action_dispatch.show_exceptions]: https://edgeguides.rubyonrails.org/configuring.html#config-action-dispatch-show-exceptions
+        MARKDOWN
+
+        def raise_on_missing_translations
+          if test_config.match?(/^\s*#\s*config\.i18n\.raise_on_missing_translations\s*=\s*true/)
+            uncomment_lines "config/environments/test.rb", /config\.i18n\.raise_on_missing_translations\s*=\s*true/
+          else
+            environment %(config.i18n.raise_on_missing_translations = true), env: "test"
+          end
+        end
+
+        def disable_action_dispatch_show_exceptions
+          if test_config.match?(/^\s*config\.action_dispatch\.show_exceptions\s*=\s*:rescuable/)
+            gsub_file "config/environments/test.rb", /^\s*config\.action_dispatch\.show_exceptions\s*=\s*:rescuable/,
+              "config.action_dispatch.show_exceptions = :none"
+            gsub_file "config/environments/test.rb", /^\s*#\s*Raise exceptions instead of rendering exception templates/i, ""
+          else
+            environment %(config.action_dispatch.show_exceptions = :none), env: "test"
+          end
+        end
+
+        private
+
+        def test_config
+          File.read(Rails.root.join("config/environments/test.rb"))
+        end
+      end
+    end
+  end
+end