rolemodel-rails 0.26.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '009bb14699c3ecc612283b81294506fdacc64e881d386d597c6b3e5302d708dd'
+  data.tar.gz: 436e21097154c27592f5f9c89557050ae64ecd6be9c4f6ee767a1aa5d5b37ce9
+SHA512:
+  metadata.gz: 83ec891bfb8720a836cd4145b2395c5db5b79e11ad2711da22be127d70da963b4cb254217aa530e279b20b68a3f47e148aea0da2643815ce3dbd753f9d0c0272
+  data.tar.gz: be94ed5589774d6f39f26741c01353d28bbcd650b21fb5e05aa94ed763b353a9caeff94eb9639d57cd0039cfe1dd75f719fb593b9d99905e25eaecc8fd8b7e8b

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Mark Kraemer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,161 @@
+# RoleModel Rails
+
+Executable Best Practices for Rails apps, based on RoleModel's best approaches
+
+Attempts to solve the pain of:
+
+* Setup of a new Rails app is harder than it needs to be
+  * We've tried application templates, but only useful onetime
+* Our BestPractice learns don't often get ported into other projects as it isn't straightforward to do so
+* There is an emerging pattern of libraries using generators (e.g. webpacker) to migrate a setup between library versions
+
+## Precondition
+
+The rolemodel-rails gem expects to be added to an existing Rails project. Typically those are started with:
+
+```shell
+rails new <app-name> --javascript=webpack --database=postgresql --skip-test
+```
+
+The Devise generator requires your database to exist before running.
+
+```shell
+rails db:create
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+group :development do
+  gem 'rolemodel-rails', github: 'RoleModel/rolemodel_rails'
+end
+```
+
+And then execute:
+
+    $ bundle
+
+## Usage
+
+Run all generators (useful on a new app)
+
+```shell
+bin/rails g rolemodel:all
+```
+
+Or run a single generator
+
+```shell
+bin/rails g rolemodel:webpack
+```
+
+Or run a category subset
+
+```shell
+bin/rails g rolemodel:testing:all
+```
+
+You can see complete list of available generators (including those under the RoleModel namespace) by running
+
+```shell
+bin/rails g
+```
+
+## Generators
+
+* [Github](./lib/generators/rolemodel/github)
+* [Semaphore](./lib/generators/rolemodel/semaphore)
+* [Heroku](./lib/generators/rolemodel/heroku)
+* [Readme](./lib/generators/rolemodel/readme)
+* [Webpack](./lib/generators/rolemodel/webpack)
+* [React](./lib/generators/rolemodel/react)
+* [Slim](./lib/generators/rolemodel/slim)
+* [Optics](./lib/generators/rolemodel/optics)
+  * [Base](./lib/generators/rolemodel/optics/base)
+  * [Icons](./lib/generators/rolemodel/optics/icons)
+* [Testing](./lib/generators/rolemodel/testing)
+  * [RSpec](./lib/generators/rolemodel/testing/rspec)
+  * [Jasmine Playwright](./lib/generators/rolemodel/testing/jasmine_playwright)
+  * [ViTest](./lib/generators/rolemodel/testing/vitest)
+  * [Factory Bot](./lib/generators/rolemodel/testing/factory_bot)
+  * [Test Prof](./lib/generators/rolemodel/testing/test_prof)
+  * [Parallel Test](./lib/generators/rolemodel/testing/parallel_tests)
+* [SimpleForm](./lib/generators/rolemodel/simple_form)
+* [SoftDestroyable](./lib/generators/rolemodel/soft_destroyable)
+* [SaaS](./lib/generators/rolemodel/saas)
+  * [Devise](./lib/generators/rolemodel/saas/devise)
+* [Mailers](./lib/generators/rolemodel/mailers)
+* [Linters](./lib/generators/rolemodel/linters)
+  * [Rubocop](./lib/generators/rolemodel/linters/rubocop)
+  * [ESLint](./lib/generators/rolemodel/linters/eslint)
+* [UI Components](./lib/generators/rolemodel/ui_components)
+  * [Flash](./lib/generators/rolemodel/ui_components/flash)
+  * [Modals](./lib/generators/rolemodel/ui_components/modals)
+  * [Navbar](./lib/generators/rolemodel/ui_components/navbar)
+* [Source Map](./lib/generators/rolemodel/source_map)
+* [Kaminari](./lib/generators/rolemodel/kaminari)
+* [GoodJob](./lib/generators/rolemodel/good_job)
+* [Editors](./lib/generators/rolemodel/editors)
+* [Tailored Select](./lib/generators/rolemodel/tailored_select)
+* [Lograge](./lib/generators/rolemodel/lograge)
+
+## Development
+
+Install the versions of Node and Ruby specified in `.node-version` and `.ruby-version` on your machine. https://asdf-vm.com/ is a great tool for managing language versions. Then run `npm install -g yarn`.
+
+## Adding new Generators
+
+Run `bin/new_generator` passing the **name** you want to use and a **description**.  Consult the list of existing [Generators](#generators) in case your new generator belongs in one of the existing groups (folders).
+
+e.g.
+
+```shell
+bin/new_generator testing/fantasitic_specs 'A Fantastic Testing Framework'
+```
+
+We use the embeded Rails apps (`example_rails*`) to test generators against. They reference the rolemodel-rails gem by local path,
+so you can navigate into one of them and run your generator for immediate feedback while developing.
+
+> [!IMPORTANT]
+> Before submitting a PR, run `bin/bump_version` to ensure the Gem builds successfully & that everything continues to stay in sync & up-to-date.<br /><br />
+> For very small changes & bug fixes, prefer `bin/bump_version --patch`.
+
+## Testing
+
+Generator specs should be added to the [spec](./spec) directory.
+
+Setup & Teardown of the test-dummy app is handled for you.  All you need to do is run the provided helper method:
+
+e.g.
+
+```ruby
+RSpec.describe Rolemodel::MyGenerator, type: :generator do
+  before { run_generator_against_test_app }
+end
+```
+
+You may also provide command line arguments to the helper method as an array:
+
+e.g.
+
+```ruby
+RSpec.describe Rolemodel::Testing::JasminePlaywrightGenerator, type: :generator do
+  before { run_generator_against_test_app(['--github-package-token=123']) }
+end
+```
+
+Additional information about testing generators and the available assertions & matchers can be found at the following resources.
+
+* [Rails Guide](https://guides.rubyonrails.org/generators.html#testing-generators)
+* [API Documentation](https://api.rubyonrails.org/classes/Rails/Generators/Testing/Assertions.html)
+* [Generator Spec Gem](https://github.com/stevehodgkiss/generator_spec)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/RoleModel/rolemodel_rails.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/generators/rolemodel/README.md

@@ -0,0 +1,29 @@
+# RoleModel Generator
+
+[USAGE](./USAGE)
+
+## What you get
+
+* [Github](./github)
+* [GoodJob](./good_job)
+* [Heroku](./heroku)
+* [Linters](./linters)
+* [Mailers](./mailers)
+* [Modals](./modals)
+* [Optics](./optics)
+* [README](./readme)
+* [SaaS](./saas)
+* [Semaphore](./semaphore)
+* [SimpleForm](./simple_form)
+* [Slim](./slim)
+* [SoftDestroyable](./soft_destroyable)
+* [Source Map](./source_map)
+* [Testing](./testing)
+* [Webpack](./webpack)
+
+## Helpful documentation
+
+* [Rails Custom Generators](https://guides.rubyonrails.org/generators.html)
+* [Generator Action Methods](https://api.rubyonrails.org/classes/Rails/Generators/Actions.html)
+* [Thor Action Methods](https://www.rubydoc.info/github/erikhuda/thor/master/Thor/Actions)
+Thor action methods can be used just like Rails generator action methods

data/lib/generators/rolemodel/USAGE

@@ -0,0 +1,5 @@
+Description:
+    runs all the generators
+
+Example:
+    rails generate rolemodel:all

data/lib/generators/rolemodel/all_generator.rb

@@ -0,0 +1,29 @@
+module Rolemodel
+  class AllGenerator < BaseGenerator
+    source_root File.expand_path('templates', __dir__)
+
+    def run_all_the_generators
+      generate 'rolemodel:github'
+      generate 'rolemodel:semaphore'
+      generate 'rolemodel:heroku'
+      generate 'rolemodel:readme'
+      generate 'rolemodel:webpack'
+      generate 'rolemodel:react'
+      generate 'rolemodel:slim'
+      generate 'rolemodel:optics:all'
+      generate 'rolemodel:testing:all'
+      generate 'rolemodel:simple_form'
+      generate 'rolemodel:soft_destroyable'
+      generate 'rolemodel:saas:all'
+      generate 'rolemodel:mailers'
+      generate 'rolemodel:linters:all'
+      generate 'rolemodel:ui_components:all'
+      generate 'rolemodel:source_map'
+      generate 'rolemodel:good_job'
+      generate 'rolemodel:kaminari'
+      generate 'rolemodel:editors'
+      # generate 'rolemodel:tailored_select' # Not production ready
+      generate 'rolemodel:lograge'
+    end
+  end
+end

data/lib/generators/rolemodel/base_generator.rb

@@ -0,0 +1,14 @@
+require 'rails/generators/base'
+require 'rails/generators/bundle_helper'
+require_relative 'replace_content_helper'
+
+class Rolemodel::BaseGenerator < Rails::Generators::Base
+  include Rails::Generators::BundleHelper,
+          Rolemodel::ReplaceContentHelper
+
+  private
+  # based on https://github.com/rails/rails/blob/main/railties/lib/rails/generators/app_base.rb#L713
+  def run_bundle
+    bundle_command("install --quiet", "BUNDLE_IGNORE_MESSAGES" => "1")
+  end
+end

data/lib/generators/rolemodel/editors/README.md

@@ -0,0 +1,9 @@
+# Editor Config Generator
+
+## What you get
+
+Creates a default [`.editorconfig`](https://editorconfig.org/) file for your project.
+
+Also ensures that a VSCode `extensions.json` config file exists in the project and adds
+the [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)
+extension to it.

data/lib/generators/rolemodel/editors/USAGE

@@ -0,0 +1,9 @@
+Description:
+    generates EditorConfig and recommends VSCode extensions
+
+Example:
+    rails generate rolemodel:editors
+
+    This will create:
+        .editorconfig
+        .vscode/extensions.json

data/lib/generators/rolemodel/editors/editors_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'vscode_helpers'
+
+module Rolemodel
+  # Add standard editorconfig and any extensions to enable it
+  class EditorsGenerator < BaseGenerator
+    include Rolemodel::VSCodeHelpers
+
+    # This is bringing in the root from this gem, so we only modify
+    # one copy of .editorconfig for both this repo and any consumers.
+    source_root File.expand_path('../../../../', __dir__)
+
+    def add_editorconfig
+      # Bring over the .editorconfig file for whitespace, etc.
+      copy_file '.editorconfig'
+
+      # Configuration for VSCode to recommend the EditorConfig extension.
+      ensure_extensions_config
+
+      # Presumably in the future, we might add ESLint, Rubocop, etc.
+      # extensions. We might eventually also split this out, if there are
+      # extensions for RubyMine or other editors, but in theory, we might
+      # want to bring over config files for any RM-supported editors.
+      inject_into_file '.vscode/extensions.json', after: '"recommendations": [' do
+        "\n    \"EditorConfig.EditorConfig\","
+      end
+    end
+  end
+end

data/lib/generators/rolemodel/editors/vscode_helpers.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Rolemodel
+  module VSCodeHelpers
+    private
+
+    # Create an extensions file for VSCode and provide an empty
+    # recommendations array if it doesn't exist.
+    def ensure_extensions_config
+      return if File.exist?('.vscode/extensions.json')
+
+      create_file('.vscode/extensions.json') do |file|
+        <<~JSON
+          {
+            "recommendations": [
+            ]
+          }
+        JSON
+      end
+    end
+  end
+end

data/lib/generators/rolemodel/github/README.md

@@ -0,0 +1,23 @@
+# Github Generator
+
+## Prerequisites
+You will need the parallel_tests generator to run the CI tests.
+
+## What you get
+
+### ci.yml
+A sensible default `ci.yml` to get you started with Github Actions. This will run linters, model tests, and system tests.
+
+Along with the `ci.yml`, your `database.yml` will be modified to be able to be run in GHA.
+
+### Pull Request Template
+
+When you open a Pull Request in Github it will use the Markdown file as a [template](./templates/pull_request_template.md) for the content of the PR.
+
+Helpful for reminding collaborators to add specific details to the PR.
+
+### Copilot Instructions
+
+Installed into `.github/instructions`, these are context-specific instructions for Copilot to help it give more accurate
+and relevant results. These are a good starting point but they should be tweaked for your project's frameworks and
+standards.

data/lib/generators/rolemodel/github/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Sets up our standard Github configuration
+
+Example:
+    rails generate rolemodel:github
+
+    This will create:
+        .github/pull_request_template.md
+        .github/workflows/ci.yml

data/lib/generators/rolemodel/github/github_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Rolemodel
+  class GithubGenerator < BaseGenerator
+    # Source root is the project-level .github directory
+    # This allows us to use the same templates for both the generated app and this gem
+    source_root File.expand_path('.github')
+
+    def install_pull_request_template
+      template 'pull_request_template.md', '.github/pull_request_template.md'
+    end
+
+    def remove_rolemodel_rails_version_check
+      gsub_file '.github/pull_request_template.md',
+                "* [ ] Run `bin/bump_version` or `bin/bump_version --patch`\n",
+                ''
+    end
+
+    def install_copilot_instructions
+      copy_file 'instructions/css.instructions.md', '.github/instructions/css.instructions.md'
+      copy_file 'instructions/js.instructions.md', '.github/instructions/js.instructions.md'
+      copy_file 'instructions/project.instructions.md', '.github/instructions/project.instructions.md'
+      copy_file 'instructions/ruby.instructions.md', '.github/instructions/ruby.instructions.md'
+      copy_file 'instructions/slim.instructions.md', '.github/instructions/slim.instructions.md'
+    end
+
+    def install_ci_yml
+      copy_file 'templates/ci.yml', '.github/workflows/ci.yml'
+    end
+
+    def update_database_yml_for_ci
+      insert_into_file 'config/database.yml', after: /database: .*_test.*\n/ do
+        optimize_indentation <<~YML, 2
+          <% if ENV.has_key?("POSTGRES_USER") %>
+          username: <%= ENV.fetch("POSTGRES_USER") %>
+          password: <%= ENV.fetch("POSTGRES_PASSWORD") { nil } %>
+          host: localhost
+          <% end %>
+        YML
+      end
+    end
+  end
+end

data/lib/generators/rolemodel/good_job/README.md

@@ -0,0 +1,13 @@
+# GoodJob Background Job Generator
+
+```
+rails g rolemodel:good_job
+```
+
+## Depends On
+
+- nothing
+
+## What you get
+
+Pulls in [GoodJob](https://github.com/bensheldon/good_job)

data/lib/generators/rolemodel/good_job/USAGE

@@ -0,0 +1,5 @@
+Description:
+  Sets up our standard GoodJob configuration
+
+Example:
+  rails generate rolemodel:good_job

data/lib/generators/rolemodel/good_job/good_job_generator.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Rolemodel
+  class GoodJobGenerator < BaseGenerator
+    source_root File.expand_path('templates', __dir__)
+
+    def install_good_job
+      say 'Install GoodJob'
+
+      bundle_command 'add good_job'
+      run_bundle
+
+      generate 'good_job:install'
+    end
+
+    def configure_good_job
+      say 'Add GoodJob configuration'
+
+      inject_into_file 'config/application.rb', after: "class Application < Rails::Application\n" do
+        optimize_indentation <<~'RUBY', 4
+          # Add GoodJob ActiveJob queue adapter
+          config.active_job.queue_adapter = :good_job
+
+        RUBY
+      end
+
+      gsub_file 'config/environments/production.rb', 'config.active_job.queue_adapter', '# config.active_job.queue_adapter'
+    end
+
+    def configure_good_job_routes
+      say 'Add GoodJob routes'
+
+      route_text = <<~RUBY
+        # Example but update per the authorization strategy of app
+        namespace :admin do
+          # authenticate :user, ->(user) { user.admin? } do
+            mount GoodJob::Engine => 'good_job'
+          # end
+        end
+      RUBY
+      route route_text
+    end
+
+    def configure_procfile
+      say 'Add GoodJob to Procfile'
+
+      if File.exist?(Rails.root.join('Procfile'))
+        append_to_file 'Procfile', <<~COMMAND
+          worker: bundle exec good_job start
+        COMMAND
+      end
+
+      append_to_file 'Procfile.dev', <<~COMMAND
+        worker: bundle exec good_job start
+      COMMAND
+    end
+
+    def copy_initializers
+      say 'Add GoodJob initializers'
+
+      copy_file 'config/initializers/active_job.rb'
+      copy_file 'config/initializers/good_job.rb'
+    end
+
+    def finishing_notes
+      say <<~NOTES
+        *** Reminder to update Honeybadger gem to version 5.7.0 or later to get correct GoodJob error notifications in Honeybadger
+
+        *** Reminder to also update your job classes to include appropriate concurrency controls (enqueue_limit/perform_limit with keys)
+      NOTES
+    end
+  end
+end

data/lib/generators/rolemodel/good_job/templates/config/initializers/active_job.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# *** NOTE ABOUT ORDERING OF discard_on/retry_on
+# https://api.rubyonrails.org/v7.1.3.2/classes/ActiveJob/Exceptions/ClassMethods.html#method-i-retry_on
+# 'retry_on' and 'discard_on' handlers are searched from bottom to top, and up the class hierarchy.
+# The handler of the first class for which exception.is_a?(klass) holds true is the one invoked, if any.
+
+# Add retry at ActiveJob::Base level to ensure all jobs retry 25 times by default regardless
+# of where the job originates from
+# Note: Rails 6 should use :exponentially_longer
+ActiveJob::Base.retry_on StandardError, wait: :polynomially_longer, attempts: 25
+
+# Automatically retry jobs that encountered a deadlock
+ActiveJob::Base.retry_on ActiveRecord::Deadlocked
+
+ActiveJob::Base.discard_on ActiveJob::DeserializationError
+ActiveJob::Base.discard_on ActiveRecord::RecordNotFound

data/lib/generators/rolemodel/good_job/templates/config/initializers/good_job.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# NOTE: queues - Configuring queues is an important part of prioritization. GoodJob uses
+# multiple ways to override. 12factor override used here with fallback to a common queue
+# override example/pattern for Heroku apps using pdf generation limiting to serial
+# processing to constrain resource [memory] limitations
+
+# NOTE: execution_mode - development defaults to async but has known to hang in certain
+# [unidentified] situations so use external which gives devs more control on running too
+
+Rails.application.configure do
+  config.good_job = {
+    smaller_number_is_higher_priority: true, # new default in V4 and for all of ActiveJob
+    queues: ENV.fetch('GOOD_JOB_QUEUES', 'pdf:1;-pdf'), # see note above
+    execution_mode: Rails.env.test? ? :inline : :external # see note above
+    # enable_cron: true,
+    # cron: {
+    #   <cron_label>: {
+    #     cron: 'every friday at 12pm EST',
+    #     class: '<class_name>'
+    #   }
+    # }
+  }
+end

data/lib/generators/rolemodel/heroku/README.md

@@ -0,0 +1,8 @@
+# Heroku Generator
+
+## What you get
+
+* Procfile configured for a server process and a release command to run migrations
+* Basic app.json preconfigured with a script to initialize the database and common environment variables, addons, and buildpacks
+
+This is the basic config needed to deploy to Heroku.

data/lib/generators/rolemodel/heroku/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Sets up our standard Heroku deployment configuration
+
+Example:
+    rails generate rolemodel:heroku
+
+    This will create:
+        app.json
+        Procfile

data/lib/generators/rolemodel/heroku/heroku_generator.rb

@@ -0,0 +1,52 @@
+module Rolemodel
+  class HerokuGenerator < BaseGenerator
+    source_root File.expand_path('templates', __dir__)
+
+    def install_app_json
+      say 'Install app.json file', :green
+
+      @project_name = Rails.application.class.try(:parent_name) || Rails.application.class.module_parent_name
+      template 'app.json'
+    end
+
+    def install_procfile
+      say 'Install Procfile', :green
+
+      template 'Procfile'
+    end
+
+    def force_ssl
+      say 'Require SSL for production environment.', :green
+
+      uncomment_lines('config/environments/production.rb', 'config.force_ssl = true')
+    end
+
+    def enable_log_level_configurability
+      say 'Enable log-level adjustment via "LOG_LEVEL" environment variable', :green
+
+      gsub_file(
+        'config/environments/production.rb',
+        'config.log_level = ENV.fetch("RAILS_LOG_LEVEL", "info")',
+        "config.log_level = ENV.fetch('LOG_LEVEL', 'INFO')"
+      )
+      gsub_file('config/environments/production.rb', 'config.log_level = :info', "config.log_level = ENV.fetch('LOG_LEVEL', 'INFO')")
+    end
+
+    def create_assets_rake_tasks # rubocop:disable Metrics/MethodLength
+      say 'Enhancing assets:precompile task to remove node_modules directory during production build.', :green
+      rakefile('assets.rake', <<~RAKE)
+        # All runtime asset dependencies should be bundled by Webpack during asset precompilation.
+        # Therefore, the node_modules directory can be removed after assets are compiled to significantly reduce slug size.
+        # In rare cases, you may have a runtime dependency into node_modules directly. If this is the case and you are unable
+        # to bundle the dependency, delete this file and the node_modules directory will be included in your production slug.
+
+        Rake::Task['assets:precompile'].enhance do
+          if Rails.env.production?
+            puts '----> Removing node_modules directory to reduce slug size.'
+            FileUtils.rm_rf(Rails.root.join('node_modules'))
+          end
+        end
+      RAKE
+    end
+  end
+end

data/lib/generators/rolemodel/heroku/templates/Procfile

@@ -0,0 +1,2 @@
+web: bundle exec puma -C config/puma.rb
+release: bin/rails db:migrate