suspenders 20230113.0 → 20250317.0

data/lib/generators/suspenders/factories_generator.rb

@@ -0,0 +1,64 @@
+module Suspenders
+  module Generators
+    class FactoriesGenerator < Rails::Generators::Base
+      include Suspenders::Generators::Helpers
+
+      source_root File.expand_path("../../templates/factories", __FILE__)
+      desc <<~MARKDOWN
+        Uses [FactoryBot][] as an alternative to [Fixtures][] to help you define
+        dummy and test data for your test suite. The `create`, `build`, and
+        `build_stubbed` class methods are directly available to all tests.
+
+        Place FactoryBot definitions in `spec/factories.rb`, at least until it
+        grows unwieldy. This helps reduce confusion around circular dependencies and
+        makes it easy to jump between definitions.
+
+        [FactoryBot]: https://github.com/thoughtbot/factory_bot
+        [Fixtures]: https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures
+      MARKDOWN
+
+      def add_factory_bot
+        gem_group :development, :test do
+          gem "factory_bot_rails"
+        end
+
+        Bundler.with_unbundled_env { run "bundle install" }
+      end
+
+      def set_up_factory_bot
+        if default_test_helper_present?
+          insert_into_file Rails.root.join("test/test_helper.rb"), after: "class TestCase" do
+            "\n    include FactoryBot::Syntax::Methods"
+          end
+        elsif rspec_test_helper_present?
+          copy_file "factory_bot_rspec.rb", "spec/support/factory_bot.rb"
+          insert_into_file Rails.root.join("spec/rails_helper.rb") do
+            %(Dir[Rails.root.join("spec/support/**/*.rb")].sort.each { |file| require file })
+          end
+        end
+      end
+
+      def generate_empty_factories_file
+        if default_test_suite?
+          copy_file "factories.rb", "test/factories.rb"
+        elsif rspec_test_suite?
+          copy_file "factories.rb", "spec/factories.rb"
+        end
+      end
+
+      def remove_fixture_definitions
+        if default_test_helper_present?
+          comment_lines "test/test_helper.rb", /fixtures :all/
+        end
+      end
+
+      def create_linting_test
+        if default_test_suite?
+          copy_file "factories_test.rb", "test/factory_bots/factories_test.rb"
+        elsif rspec_test_suite?
+          copy_file "factories_spec.rb", "spec/factory_bots/factories_spec.rb"
+        end
+      end
+    end
+  end
+end

data/lib/generators/suspenders/inline_svg_generator.rb

@@ -0,0 +1,24 @@
+module Suspenders
+  module Generators
+    class InlineSvgGenerator < Rails::Generators::Base
+      include Suspenders::Generators::APIAppUnsupported
+      source_root File.expand_path("../../templates/inline_svg", __FILE__)
+      desc <<~MARKDOWN
+        Uses [inline_svg][] for embedding SVG documents into views.
+
+        Configuration can be found at `config/initializers/inline_svg.rb`
+
+        [inline_svg]: https://github.com/jamesmartin/inline_svg
+      MARKDOWN
+
+      def add_inline_svg_gem
+        gem "inline_svg"
+        Bundler.with_unbundled_env { run "bundle install" }
+      end
+
+      def configure_inline_svg
+        copy_file "inline_svg.rb", "config/initializers/inline_svg.rb"
+      end
+    end
+  end
+end

data/lib/generators/suspenders/install/web_generator.rb

@@ -0,0 +1,85 @@
+module Suspenders
+  module Generators
+    module Install
+      class WebGenerator < Rails::Generators::Base
+        include Suspenders::Generators::APIAppUnsupported
+        include Suspenders::Generators::DatabaseUnsupported
+        include Suspenders::Generators::NodeNotInstalled
+        include Suspenders::Generators::NodeVersionUnsupported
+
+        source_root File.expand_path("../../../templates/install/web", __FILE__)
+        desc <<~MARKDOWN
+          Invokes all necessary generators for new Rails applications generated with Suspenders.
+
+          This generatator is intended to be invoked as part of an [application template][].
+
+          #### Use the latest suspenders release:
+
+          ```
+          rails new <app_name> \\
+          --skip-rubocop \\
+          --skip-test \\
+          -d=postgresql \\
+          -m=https://raw.githubusercontent.com/thoughtbot/suspenders/main/lib/install/web.rb
+          ```
+
+          #### OR use the current (possibly unreleased) `main` branch of suspenders:
+
+          ```
+          rails new app_name \\
+          --suspenders-main \\
+          --skip-rubocop \\
+          --skip-test \\
+          -d=postgresql \\
+          -m=https://raw.githubusercontent.com/thoughtbot/suspenders/main/lib/install/web.rb
+          ```
+
+          [application template]: https://guides.rubyonrails.org/rails_application_templates.html
+        MARKDOWN
+
+        def invoke_generators
+          # This needs to go first, since it configures `.node-version`
+          generate "suspenders:prerequisites"
+
+          generate "suspenders:accessibility"
+          generate "suspenders:advisories"
+          generate "suspenders:email"
+          generate "suspenders:factories"
+          generate "suspenders:inline_svg"
+          generate "suspenders:lint"
+          generate "suspenders:rake"
+          generate "suspenders:setup"
+          generate "suspenders:tasks"
+          generate "suspenders:testing"
+          generate "suspenders:views"
+
+          # suspenders:jobs needs to be invoked before suspenders:styles, since
+          # suspenders:styles generator creates Procfile.dev
+          generate "suspenders:styles"
+          generate "suspenders:jobs"
+
+          # Needs to run after other generators, since some touch the
+          # configuration files.
+          generate "suspenders:environments:test"
+          generate "suspenders:environments:development"
+          generate "suspenders:environments:production"
+
+          # Needs to be run last since it depends on lint, testing, and
+          # advisories
+          generate "suspenders:ci"
+        end
+
+        def cleanup
+          rake "suspenders:cleanup:organize_gemfile"
+          rake "suspenders:cleanup:generate_readme"
+          copy_file "CONTRIBUTING.md", "CONTRIBUTING.md"
+        end
+
+        def lint
+          run "yarn run fix:prettier"
+          run "bundle exec rake standard:fix_unsafely"
+        end
+      end
+    end
+  end
+end

data/lib/generators/suspenders/jobs_generator.rb

@@ -0,0 +1,34 @@
+module Suspenders
+  module Generators
+    class JobsGenerator < Rails::Generators::Base
+      desc <<~MARKDOWN
+        Uses [Sidekiq][] for [background job][] processing.
+
+        Configures the `test` environment to use the [inline][] adapter.
+
+        [Sidekiq]: https://github.com/sidekiq/sidekiq
+        [background job]: https://guides.rubyonrails.org/active_job_basics.html
+        [inline]: https://api.rubyonrails.org/classes/ActiveJob/QueueAdapters/InlineAdapter.html
+      MARKDOWN
+
+      def add_sidekiq_gem
+        gem "sidekiq"
+        Bundler.with_unbundled_env { run "bundle install" }
+      end
+
+      def configure_active_job
+        environment "config.active_job.queue_adapter = :sidekiq"
+        environment "config.active_job.queue_adapter = :inline", env: "test"
+      end
+
+      def configure_procfile
+        if Rails.root.join("Procfile.dev").exist?
+          append_to_file "Procfile.dev", "worker: bundle exec sidekiq"
+        else
+          say "Add default Procfile.dev"
+          create_file "Procfile.dev", "worker: bundle exec sidekiq"
+        end
+      end
+    end
+  end
+end

data/lib/generators/suspenders/lint_generator.rb

@@ -0,0 +1,94 @@
+module Suspenders
+  module Generators
+    class LintGenerator < Rails::Generators::Base
+      include Suspenders::Generators::Helpers
+
+      source_root File.expand_path("../../templates/lint", __FILE__)
+      desc <<~MARKDOWN
+        - Uses [@thoughtbot/eslint-config][] for JavaScript linting.
+        - Uses [@thoughtbot/stylelint-config][] for CSS linting.
+        - Uses [prettier][] for additional linting.
+        - Uses [better_html][], [erb_lint][], and [erblint-github][] for ERB linting.
+        - Uses [standard][] for Ruby linting.
+
+        **Available Commands**
+
+        - Run `yarn lint` to lint front-end code.
+        - Run `yarn fix:prettier` to automatically fix prettier violations.
+        - Run `bin/rails standard` to lint ERB and Ruby code.
+        - Run `bundle exec standardrb --fix` to fix standard violations.
+
+        [@thoughtbot/eslint-config]: https://github.com/thoughtbot/eslint-config
+        [@thoughtbot/stylelint-config]: https://github.com/thoughtbot/stylelint-config
+        [prettier]: https://prettier.io
+        [better_html]: https://github.com/Shopify/better-html
+        [erb_lint]: https://github.com/Shopify/erb-lint
+        [erblint-github]: https://github.com/github/erblint-github
+        [standard]: https://github.com/standardrb/standard
+      MARKDOWN
+
+      def check_package_json
+        unless File.exist? Rails.root.join("package.json")
+          copy_file "package.json", "package.json"
+        end
+      end
+
+      # TODO: Remove eslint version pin once the follownig is solved
+      # https://github.com/thoughtbot/eslint-config/issues/10
+      def install_dependencies
+        run "yarn add stylelint eslint@^8.9.0 @thoughtbot/stylelint-config @thoughtbot/eslint-config npm-run-all prettier --dev"
+      end
+
+      def install_gems
+        gem_group :development, :test do
+          gem "better_html", require: false
+          gem "erb_lint", require: false
+          gem "erblint-github", require: false
+          gem "standard"
+        end
+        Bundler.with_unbundled_env { run "bundle install" }
+      end
+
+      def configure_stylelint
+        copy_file "stylelintrc.json", ".stylelintrc.json"
+      end
+
+      def configure_eslint
+        copy_file "eslintrc.json", ".eslintrc.json"
+      end
+
+      def configure_prettier
+        copy_file "prettierrc", ".prettierrc"
+        copy_file "prettierignore", ".prettierignore"
+      end
+
+      def configure_erb_lint
+        copy_file "erb-lint.yml", ".erb-lint.yml"
+        copy_file "config_better_html.yml", "config/better_html.yml"
+        copy_file "config_initializers_better_html.rb", "config/initializers/better_html.rb"
+        copy_file "erblint.rake", "lib/tasks/erblint.rake"
+        template "rubocop.yml.tt", ".rubocop.yml"
+      end
+
+      def update_package_json
+        content = File.read package_json
+        json = JSON.parse content
+        json["scripts"] ||= {}
+
+        json["scripts"]["lint"] = "run-p lint:eslint lint:stylelint lint:prettier"
+        json["scripts"]["lint:eslint"] = "eslint --max-warnings=0 --no-error-on-unmatched-pattern 'app/javascript/**/*.js'"
+        json["scripts"]["lint:stylelint"] = "stylelint 'app/assets/stylesheets/**/*.css'"
+        json["scripts"]["lint:prettier"] = "prettier --check '**/*' --ignore-unknown"
+        json["scripts"]["fix:prettier"] = "prettier --write '**/*' --ignore-unknown"
+
+        File.write package_json, JSON.pretty_generate(json)
+      end
+
+      private
+
+      def package_json
+        Rails.root.join("package.json")
+      end
+    end
+  end
+end

data/lib/generators/suspenders/prerequisites_generator.rb

@@ -0,0 +1,19 @@
+module Suspenders
+  module Generators
+    class PrerequisitesGenerator < Rails::Generators::Base
+      include Suspenders::Generators::Helpers
+      include Suspenders::Generators::NodeNotInstalled
+      include Suspenders::Generators::NodeVersionUnsupported
+
+      source_root File.expand_path("../../templates/prerequisites", __FILE__)
+
+      desc <<~MARKDOWN
+        Creates `.node-version` file set to the current LTS version.
+      MARKDOWN
+
+      def set_node_version
+        template "node-version", ".node-version"
+      end
+    end
+  end
+end

data/lib/generators/suspenders/rake_generator.rb

@@ -0,0 +1,25 @@
+module Suspenders
+  module Generators
+    class RakeGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../templates/rake", __FILE__)
+      desc <<~MARKDOWN
+        Adds default Raketask wich is a wrapper for `suspenders:rake`.
+
+        This will do the following:
+
+          - Run the test suite.
+          - Run a Ruby and ERB linter.
+          - Scan the Ruby codebase for any dependency vulnerabilities.
+      MARKDOWN
+
+      def configure_default_rake_task
+        append_to_file "Rakefile", <<~RUBY
+
+          if Rails.env.local?
+            task default: "suspenders:rake"
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/generators/suspenders/setup_generator.rb

@@ -0,0 +1,14 @@
+module Suspenders
+  module Generators
+    class SetupGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../templates/setup", __FILE__)
+      desc <<~MARKDOWN
+        Run `bin/setup` to install dependencies and seed development data.
+      MARKDOWN
+
+      def replace_bin_setup
+        copy_file "bin_setup.rb", "bin/setup", force: true
+      end
+    end
+  end
+end

data/lib/generators/suspenders/styles_generator.rb

@@ -0,0 +1,84 @@
+module Suspenders
+  module Generators
+    class StylesGenerator < Rails::Generators::Base
+      include Suspenders::Generators::APIAppUnsupported
+
+      source_root File.expand_path("../../templates/styles", __FILE__)
+      desc <<~MARKDOWN
+        - Uses [PostCSS][] via [cssbundling-rails][].
+        - Uses [modern-normalize][] to normalize browsers' default style.
+
+        Configuration can be found at `postcss.config.js`.
+
+        Adds the following stylesheet structure.
+
+        ```
+        app/assets/stylesheets/base.css
+        app/assets/stylesheets/components.css
+        app/assets/stylesheets/utilities.css
+        ```
+
+        Adds `app/assets/static` so that [postcss-url][] has a directory to copy
+        assets to.
+
+        [PostCSS]: https://postcss.org
+        [cssbundling-rails]: https://github.com/rails/cssbundling-rails
+        [modern-normalize]: https://github.com/sindresorhus/modern-normalize
+        [postcss-url]: https://github.com/postcss/postcss-url
+      MARKDOWN
+
+      def add_cssbundling_rails_gem
+        gem "cssbundling-rails"
+
+        Bundler.with_unbundled_env { run "bundle install" }
+        run "bin/rails css:install:postcss"
+      end
+
+      def build_directory_structure
+        create_file "app/assets/stylesheets/base.css"
+        append_to_file "app/assets/stylesheets/base.css", "/* Base Styles */"
+
+        create_file "app/assets/stylesheets/components.css"
+        append_to_file "app/assets/stylesheets/components.css", "/* Component Styles */"
+
+        create_file "app/assets/stylesheets/utilities.css"
+        append_to_file "app/assets/stylesheets/utilities.css", "/* Utility Styles */"
+      end
+
+      def configure_application_stylesheet
+        run "yarn add modern-normalize"
+
+        append_to_file "app/assets/stylesheets/application.postcss.css" do
+          <<~TEXT
+            @import "modern-normalize";
+            @import "base.css";
+            @import "components.css";
+            @import "utilities.css";
+          TEXT
+        end
+      end
+
+      def install_postcss_url
+        run "yarn add postcss-url"
+      end
+
+      def configures_postcss
+        begin
+          File.delete(postcss_config)
+        rescue Errno::ENOENT
+        end
+
+        empty_directory "app/assets/static"
+        create_file "app/assets/static/.gitkeep"
+
+        copy_file "postcss.config.js", "postcss.config.js"
+      end
+
+      private
+
+      def postcss_config
+        Rails.root.join("postcss.config.js")
+      end
+    end
+  end
+end

data/lib/generators/suspenders/tasks_generator.rb

@@ -0,0 +1,20 @@
+module Suspenders
+  module Generators
+    class TasksGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../templates/tasks", __FILE__)
+      desc <<~MARKDOWN
+        Creates `lib/tasks/dev.rake` which contains the following tasks:
+
+        `bin/rails dev:prime` which loads sample data for local development.
+      MARKDOWN
+
+      def create_dev_rake
+        if Bundler.rubygems.find_name("factory_bot").any?
+          copy_file "dev.rake", "lib/tasks/dev.rake"
+        else
+          say "This generator requires Factory Bot"
+        end
+      end
+    end
+  end
+end

data/lib/generators/suspenders/testing_generator.rb

@@ -0,0 +1,113 @@
+module Suspenders
+  module Generators
+    class TestingGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../templates/testing", __FILE__)
+      desc <<~MARKDOWN
+        Uses [RSpec][] and [RSpec Rails][] in favor of the [default test suite][].
+
+        The test suite can be run with `bin/rails spec`.
+
+        Configuration can be found in the following files:
+
+        ```
+        spec/rails_helper.rb
+        spec/spec_helper.rb
+        spec/support/action_mailer.rb
+        spec/support/driver.rb
+        spec/support/i18n.rb
+        spec/support/shoulda_matchers.rb
+        ```
+
+        - Uses [action_dispatch-testing-integration-capybara][] to introduce Capybara assertions into Request specs.
+        - Uses [shoulda-matchers][] for simple one-liner tests for common Rails functionality.
+        - Uses [webmock][] for stubbing and setting expectations on HTTP requests in Ruby.
+
+        [RSpec]: http://rspec.info
+        [RSpec Rails]: https://github.com/rspec/rspec-rails
+        [default test suite]: https://guides.rubyonrails.org/testing.html
+        [action_dispatch-testing-integration-capybara]: https://github.com/thoughtbot/action_dispatch-testing-integration-capybara
+        [shoulda-matchers]: https://github.com/thoughtbot/shoulda-matchers
+        [webmock]: https://github.com/bblimke/webmock
+      MARKDOWN
+
+      def add_gems
+        gem_group :development, :test do
+          gem "rspec-rails", "~> 6.1.0"
+        end
+
+        gem_group :test do
+          gem "capybara"
+          gem "action_dispatch-testing-integration-capybara",
+            github: "thoughtbot/action_dispatch-testing-integration-capybara", tag: "v0.1.1",
+            require: "action_dispatch/testing/integration/capybara/rspec"
+          gem "selenium-webdriver"
+          gem "shoulda-matchers", "~> 6.0"
+          gem "webmock"
+        end
+
+        Bundler.with_unbundled_env { run "bundle install" }
+      end
+
+      def run_rspec_installation_script
+        rails_command "generate rspec:install"
+      end
+
+      def modify_rails_helper
+        insert_into_file "spec/rails_helper.rb",
+          "\s\sconfig.infer_base_class_for_anonymous_controllers = false\n",
+          after: "RSpec.configure do |config|\n"
+
+        uncomment_lines "spec/rails_helper.rb", /Rails\.root\.glob/
+      end
+
+      def modify_spec_helper
+        persistence_file_path = "\s\sconfig.example_status_persistence_file_path = \"tmp/rspec_examples.txt\"\n"
+        order = "\s\sconfig.order = :random\n\n"
+        webmock_config = <<~RUBY
+
+          WebMock.disable_net_connect!(
+            allow_localhost: true,
+            allow: [
+              /(chromedriver|storage).googleapis.com/,
+              "googlechromelabs.github.io"
+            ]
+          )
+        RUBY
+
+        insert_into_file "spec/spec_helper.rb",
+          persistence_file_path + order,
+          after: "RSpec.configure do |config|\n"
+
+        insert_into_file "spec/spec_helper.rb", "require \"webmock/rspec\"\n\n", before: "RSpec.configure do |config|"
+        insert_into_file "spec/spec_helper.rb", webmock_config
+      end
+
+      def create_system_spec_dir
+        empty_directory "spec/system"
+        create_file "spec/system/.gitkeep"
+      end
+
+      def configure_chromedriver
+        copy_file "driver.rb", "spec/support/driver.rb"
+      end
+
+      def configure_i18n_helper
+        copy_file "i18n.rb", "spec/support/i18n.rb"
+      end
+
+      def configure_shoulda_matchers
+        copy_file "shoulda_matchers.rb", "spec/support/shoulda_matchers.rb"
+      end
+
+      def configure_action_mailer_helpers
+        # https://guides.rubyonrails.org/testing.html#the-basic-test-case
+        #
+        # The ActionMailer::Base.deliveries array is only reset automatically in
+        # ActionMailer::TestCase and ActionDispatch::IntegrationTest tests. If
+        # you want to have a clean slate outside these test cases, you can reset
+        # it manually with: ActionMailer::Base.deliveries.clear
+        copy_file "action_mailer.rb", "spec/support/action_mailer.rb"
+      end
+    end
+  end
+end

data/lib/generators/suspenders/views_generator.rb

@@ -0,0 +1,38 @@
+module Suspenders
+  module Generators
+    class ViewsGenerator < Rails::Generators::Base
+      include Suspenders::Generators::APIAppUnsupported
+
+      source_root File.expand_path("../../templates/views", __FILE__)
+      desc <<~MARKDOWN
+        - A [partial][] for [flash messages][] is located in `app/views/application/_flashes.html.erb`.
+        - Sets [lang][] attribute on `<html>` element to `en` via `I18n.local`.
+        - Dynamically sets `<title>` via the [title][] gem.
+        - Disables Turbo's [Prefetch][] in an effort to reduce unnecessary network requests.
+
+        [partial]: https://guides.rubyonrails.org/layouts_and_rendering.html#using-partials
+        [flash messages]: https://guides.rubyonrails.org/action_controller_overview.html#the-flash
+        [lang]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang
+        [title]: https://github.com/calebhearth/title
+        [Prefetch]: https://turbo.hotwired.dev/handbook/drive#prefetching-links-on-hover
+      MARKDOWN
+
+      def install_gems
+        gem "title"
+
+        Bundler.with_unbundled_env { run "bundle install" }
+      end
+
+      def create_views
+        copy_file "flashes.html.erb", "app/views/application/_flashes.html.erb"
+      end
+
+      def update_application_layout
+        insert_into_file "app/views/layouts/application.html.erb", "    <%= render \"flashes\" -%>\n", after: "<body>\n"
+        gsub_file "app/views/layouts/application.html.erb", /<html>/, "<html lang=\"<%= I18n.locale %>\">"
+        gsub_file "app/views/layouts/application.html.erb", /<title>.*<\/title>/, "<title><%= title %></title>"
+        insert_into_file "app/views/layouts/application.html.erb", "    <meta name=\"turbo-prefetch\" content=\"false\">\n", after: "</title>"
+      end
+    end
+  end
+end