Taskfile.yml

version: '3'

##
# IMPORTANT: All tasks listed in this file should be executed from the root folder.
# - https://taskfile.dev/usage/#task-directory
#
# NOTE: Examples of multiline strings in YAML.
# - https://yaml-multiline.info/
#
# NOTE: Use `[ "${IN_DOCKER_CONTAINER}" == "true" ] && echo true || echo false` to debug ``[ "${IN_DOCKER_CONTAINER}" == "true" ]`.
#
# NOTE: Forwarding CLI arguments to commands ({{.CLI_ARGS}}).
# - https://taskfile.dev/usage/#forwarding-cli-arguments-to-commands
#
# NOTE: All tasks are sorted alphabetically.
#
# NOTE: `open` tasks only navigate/open apps. They are NOT running any other commands.
#
# TODO: Global preconditions are imitated using YAML anchors. Replace anchors once native support added.
# - https://github.com/go-task/task/issues/294
#
# NOTE: Use the following snippet to test what exactly anchors are generating from irb.
#   yaml = ["yaml", "awesome_print"].each(&method(:require)).then { File.read("Taskfile.yml") }.then { |text| YAML.load(text, aliases: true) }.tap { |yaml| ap yaml }
#
# NOTE: Prefer to utilize task vars when possible since it allows to pass CLI_ARGS with no hacks.
#   # Okish
#   - APPRAISAL=rails_7.1 task rspec
#
#   # Better, since CLI_ARGS now works out of the box.
#   - task: rspec
#     vars:
#       APPRAISAL: rails_7.1
##

##
# Ensures that a task is executed for host OS.
#
from-host-os: &from-host-os
  sh: '[ "${IN_DOCKER_CONTAINER}" != "true" ]'
  msg: This task can be invoked only from the host operating system (https://www.ibm.com/cloud/learn/containerization)

##
# Ensures that a task is executed for macOS.
# - https://stackoverflow.com/a/17072017/12201472
#
from-mac-os: &from-mac-os
  sh: '[ "$(uname)" == "Darwin" ]'
  msg: This task uses macOS specific commands. Try to adjust it your OS and/or run it manually.

##
# Prepends `bundle exec` when no Appraisal is set.
# Prepends `APPRAISAL_NAME=name bin/appraisal` when an Appraisal is set.
#
BUNDLE_EXEC_PREFIX: &BUNDLE_EXEC_PREFIX
  sh: ruby -e 'puts (if "{{.APPRAISAL}}".empty? then "bundle exec" else "APPRAISAL_NAME={{.APPRAISAL}} bin/appraisal %s_%s_%s" % [RUBY_ENGINE, RUBY_ENGINE_VERSION[/\d+\.\d+/], "{{.APPRAISAL}}"] end)'

tasks:
  default:
    cmds:
      - task: test

  ##
  # NOTE: Usage examples.
  #   APPRAISAL=all task console
  #   APPRAISAL=dry task console
  #   APPRAISAL=rails_5.2 task console
  #   APPRAISAL=rails_6.0 task console
  #   APPRAISAL=rails_6.1 task console
  #   APPRAISAL=rails_7.0 task console
  #   APPRAISAL=rails_7.1 task console
  #   APPRAISAL=rails_7.2 task console
  #   task console
  #
  # NOTE: Setting `APPRAISAL` after `task console` does NOT work. Consider to open an issue.
  # NOTE: `task console` is also aliased as `task playground`.
  # NOTE: `BUNDLE_EXEC_PREFIX` must be kept in sync with `Appraisals` file.
  #
  console:
    cmds:
      - "{{.BUNDLE_EXEC_PREFIX}} rake console"
    vars:
      BUNDLE_EXEC_PREFIX: *BUNDLE_EXEC_PREFIX
    interactive: true

  coverage:lcov:merge:
    cmds:
      - npx --yes lcov-result-merger 'coverage/**/lcov.info' coverage/lcov.info

  coverage:open:
    cmds:
      - open coverage/index.html
    preconditions:
      - *from-host-os
      - *from-mac-os

  deps:
    cmds:
      - task: deps:install

  ##
  # NOTE: `task deps:install` is also aliased as `task install`.
  #
  deps:install:
    cmds:
      - cp Gemfile Gemfile.{{.RUBY_ENGINE}}_{{.RUBY_ENGINE_VERSION}}
      - bundle install
      - bin/appraisal install
    vars:
      RUBY_ENGINE:
        sh: ruby -e 'puts ["{{.RUBY_ENGINE}}", ENV["RUBY_ENGINE"], RUBY_ENGINE].map(&:to_s).reject(&:empty?).first'
      RUBY_ENGINE_VERSION:
        sh: ruby -e 'puts "{{.RUBY_ENGINE_VERSION}}".to_s[/\d+\.\d+/] || ENV["RUBY_ENGINE_VERSION"].to_s[/\d+\.\d+/] || RUBY_ENGINE_VERSION[/\d+\.\d+/]'

  ##
  # NOTE: Meaning of `2> /dev/null`.
  # - https://stackoverflow.com/a/10250395/12201472
  #
  # NOTE: Meaning of `|| true`.
  # - https://superuser.com/a/887349/1180656
  #
  deps:clean:
    cmds:
      - rm Gemfile.* 2> /dev/null || true
      - rm -rf gemfiles
      - touch gemfiles/.gitkeep
    prompt: This task removes Gemfile.* and gemfiles/**/*. Are you sure?

  ##
  # NOTE: Usage examples.
  #   task docker:bash RUBY_ENGINE=ruby RUBY_ENGINE_VERSION=2.7
  #   task docker:bash RUBY_ENGINE=ruby RUBY_ENGINE_VERSION=3.0
  #   task docker:bash RUBY_ENGINE=ruby RUBY_ENGINE_VERSION=3.1
  #   task docker:bash RUBY_ENGINE=ruby RUBY_ENGINE_VERSION=3.2
  #   task docker:bash RUBY_ENGINE=ruby RUBY_ENGINE_VERSION=3.3
  #   task docker:bash RUBY_ENGINE=jruby RUBY_ENGINE_VERSION=9.4
  #   task docker:bash RUBY_ENGINE=truffleruby RUBY_ENGINE_VERSION=22.3
  #
  # NOTE: JRuby 9.4 aims CRuby 3.1 compatibility.
  # - https://www.jruby.org/download
  #
  # NOTE: TruffleRuby 22.3 aims CRuby 3.1 compatibility.
  # - https://github.com/oracle/truffleruby/blob/master/doc/user/compatibility.md
  #
  # NOTE: Naming `RUBY_ENGINE` is inspired by `ruby_engine` gem.
  # - https://github.com/janlelis/ruby_engine
  #
  docker:bash:
    cmds:
      - docker run --rm -it -v $(pwd):/gem convenient_service:{{.RUBY_ENGINE}}_{{.RUBY_ENGINE_VERSION}} bash
    interactive: true
    preconditions:
      - *from-host-os
    requires:
      vars: [RUBY_ENGINE, RUBY_ENGINE_VERSION]

  ##
  # NOTE: Usage examples.
  #   RUBY_ENGINE=ruby RUBY_ENGINE_VERSION=2.7 task docker:build
  #   RUBY_ENGINE=ruby RUBY_ENGINE_VERSION=3.0 task docker:build
  #   RUBY_ENGINE=ruby RUBY_ENGINE_VERSION=3.1 task docker:build
  #   RUBY_ENGINE=ruby RUBY_ENGINE_VERSION=3.2 task docker:build
  #   RUBY_ENGINE=ruby RUBY_ENGINE_VERSION=3.3 task docker:build
  #   RUBY_ENGINE=jruby RUBY_ENGINE_VERSION=9.4 task docker:build
  #   RUBY_ENGINE=truffleruby RUBY_ENGINE_VERSION=22.3 task docker:build
  #
  # NOTE: JRuby 9.4 aims CRuby 3.1 compatibility.
  # - https://www.jruby.org/download
  #
  # NOTE: TruffleRuby 22.3 aims CRuby 3.1 compatibility.
  # - https://github.com/oracle/truffleruby/blob/master/doc/user/compatibility.md
  #
  # NOTE: Naming `RUBY_ENGINE` is inspired by `ruby_engine` gem.
  # - https://github.com/janlelis/ruby_engine
  #
  # NOTE: Meaning of `2> /dev/null`.
  # - https://stackoverflow.com/a/10250395/12201472
  #
  # NOTE: Meaning of `|| true`.
  # - https://superuser.com/a/887349/1180656
  #
  docker:build:
    cmds:
      - rm Gemfile.{{.RUBY_ENGINE}}_{{.RUBY_ENGINE_VERSION}} 2> /dev/null || true
      - rm Gemfile.{{.RUBY_ENGINE}}_{{.RUBY_ENGINE_VERSION}}.lock 2> /dev/null || true
      - cp Gemfile Gemfile.{{.RUBY_ENGINE}}_{{.RUBY_ENGINE_VERSION}}
      - docker build . -f docker/{{.RUBY_ENGINE}}_{{.RUBY_ENGINE_VERSION}}/Dockerfile -t convenient_service:{{.RUBY_ENGINE}}_{{.RUBY_ENGINE_VERSION}}
      ##
      # NOTE: Gemfiles created during the build time are NOT persisted. The following commands persist them by triggering `bundle install` in the run time.
      #
      - docker run --rm -it -v $(pwd):/gem convenient_service:{{.RUBY_ENGINE}}_{{.RUBY_ENGINE_VERSION}} bash -c "task deps:install"
    preconditions:
      - *from-host-os
    requires:
      vars: [RUBY_ENGINE, RUBY_ENGINE_VERSION]

  docker:build:all:
    cmds:
      - task: docker:build
        vars:
          RUBY_ENGINE: ruby
          RUBY_ENGINE_VERSION: 2.7
      - task: docker:build
        vars:
          RUBY_ENGINE: ruby
          RUBY_ENGINE_VERSION: 3.0
      - task: docker:build
        vars:
          RUBY_ENGINE: ruby
          RUBY_ENGINE_VERSION: 3.1
      - task: docker:build
        vars:
          RUBY_ENGINE: ruby
          RUBY_ENGINE_VERSION: 3.2
      - task: docker:build
        vars:
          RUBY_ENGINE: ruby
          RUBY_ENGINE_VERSION: 3.3
      - task: docker:build
        vars:
          RUBY_ENGINE: jruby
          RUBY_ENGINE_VERSION: 9.4
      - task: docker:build
        vars:
          RUBY_ENGINE: truffleruby
          RUBY_ENGINE_VERSION: 22.3
    preconditions:
      - *from-host-os

  ##
  # NOTE: Dev only command.
  # NOTE: macOS specific command.
  #
  docker:start:
    cmds:
      - open -a Docker
    preconditions:
      - *from-host-os
      - *from-mac-os

  ##
  # NOTE: `sdoc` (wrapper for `rdoc`) is replaced by `yard`, since you have a feeling like every time is a first time with `rdoc`.
  # - https://kapeli.com/cheat_sheets/Yard.docset/Contents/Resources/Documents/index
  # - https://rubydoc.info/gems/yard/file/README.md
  # - `yardoc --help`
  #
  # NOTE: `commonmarker` supports GitHub Flavored Markdown.
  # - https://github.com/gjtorikian/commonmarker
  # - https://github.github.com/gfm/
  # - https://github.com/github/markup#markups
  # - https://github.com/lsegal/yard/pull/1388
  #
  # TODO: Contribute. Forward `--parse-option LIBERAL_HTML_TAG` to commonmarker.
  #
  # NOTE: Options are specified in the `.yardopts` file.
  #
  # NOTE: Check `yard` own sources to find comprehensive usage examples.
  # - https://github.com/lsegal/yard
  #
  # NOTE: `.yardopts` docs.
  # - https://rubydoc.info/gems/yard/YARD/CLI/Yardoc
  #
  # NOTE: Examples of `.yardopts`.
  # - https://github.com/lsegal/yard/blob/main/.yardopts
  # - https://github.com/rspec/rspec-core/blob/main/.yardopts
  #
  # NOTE: `yard` intentionally does NOT support `:nodoc`. Internal API must be also documented for contributors.
  # - https://rubydoc.tenderapp.com/kb/getting-started-with-rubydocinfo/where-is-my-nodoc
  #
  # NOTE: `@internal` tag docs.
  # - https://github.com/lsegal/yard/issues/484#issuecomment-442596174
  #
  # NOTE: `@private` tag docs.
  # - https://rubydoc.tenderapp.com/kb/getting-started-with-rubydocinfo/where-is-my-nodoc
  #
  # NOTE: `.yardopts` does NOT support comments, that is why all notes are inside this Taskfile.
  # - https://github.com/lsegal/yard/blob/v0.9.36/lib/yard/core_ext/string.rb#L8
  #
  # TODO: Consider to utilize `yard-spec-plugin`.
  # - https://github.com/lsegal/yard-spec-plugin
  #
  docs:generate:
    cmds:
      ##
      # NOTE: yard supports plugins as gems only.
      # - https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#plugin-support
      #
      # NOTE: `RUBYLIB` is used to extend Ruby's `$LOAD_PATH`. This way yard treats `./yard` folder as a directory with custom gems.
      #
      - RUBYLIB=./yard bundle exec yardoc

  docs:generate:open:
    cmds:
      - task: docs:generate
      - open docs/api/index.html
    preconditions:
      - *from-host-os
      - *from-mac-os

  docs:lint:
    cmds:
      - task: yard_junk

  docs:missed:
    cmds:
      ##
      # NOTE: `RUBYLIB` is used to extend Ruby's `$LOAD_PATH`. This way yard treats `./yard` folder as a directory with custom gems.
      # NOTE: Options are taken from `.inch.yml`.
      #
      - RUBYLIB=./yard bundle exec inch

  ##
  # NOTE: `yard` server is running on `localhost:8808` be default.
  #
  docs:server:
    cmds:
      ##
      # NOTE: `RUBYLIB` is used to extend Ruby's `$LOAD_PATH`. This way yard treats `./yard` folder as a directory with custom gems.
      # NOTE: Options are specified in the `.yardopts` file.
      #
      # NOTE: `--reload` option docs.
      # - `yard server --help`.
      # - https://yardoc.org/index.html
      # - https://github.com/lsegal/yard/blob/main/lib/yard/cli/server.rb#L173
      # - https://groups.google.com/g/yardoc/c/PU-XJzsvL4Q
      #
      # NOTE: Use `--debug` option for verbose logging and debugging.
      #
      - RUBYLIB=./yard bundle exec yard server --reload
    preconditions:
      - *from-host-os

  ##
  # NOTE: `yard` server is running on `localhost:8808` be default.
  #
  docs:server:open:
    cmds:
      ##
      # NOTE: See https://ss64.com/mac/open.html for `open` options.
      #
      - open -na "Google Chrome" --args --new-window --incognito "http://localhost:8808"
      - task: docs:server
    preconditions:
      - *from-host-os
      - *from-mac-os

  ##
  # NOTE: Dev only command.
  #
  editor:open:
    cmds:
      - code .
    preconditions:
      - *from-host-os
      - *from-mac-os

  ##
  # NOTE: A trailing "/**" matches everything inside.
  # - https://git-scm.com/docs/gitignore
  #
  git:staged:minitest:
    cmds:
      - git diff --cached --name-only --diff-filter=d "test/**"
    preconditions:
      - *from-host-os

  ##
  # NOTE: A trailing "/**" matches everything inside.
  # - https://git-scm.com/docs/gitignore
  #
  git:staged:rspec:
    cmds:
      - git diff --cached --name-only --diff-filter=d "spec/**"
    preconditions:
      - *from-host-os

  ##
  # NOTE: Dev only command.
  # NOTE: macOS specific command.
  #
  github:open:
    cmds:
      - open -na "Google Chrome" --args --new-window --incognito "https://github.com/marian13/convenient_service"
    preconditions:
      - *from-host-os
      - *from-mac-os

  ##
  # NOTE: `task install` is also aliased as `task deps:install`.
  #
  install:
    cmds:
      - task: deps:install

  ##
  # NOTE: See `task console` for usage examples.
  #
  irb:
    cmds:
      - "{{.BUNDLE_EXEC_PREFIX}} rake irb"
    vars:
      BUNDLE_EXEC_PREFIX: *BUNDLE_EXEC_PREFIX
    interactive: true

  ##
  # NOTE: Usage examples.
  #   task lint
  #   AUTOCORRECT=true task lint
  #
  lint:
    cmds:
      - task: rubocop
      - task: docs:lint

  minitest:
    cmds:
      - bundle exec ruby minitest.rb {{.GIT_STAGED_MINITEST_FILES}} {{.CLI_ARGS}}
    vars:
      GIT_STAGED_MINITEST_FILES:
        sh: ruby -e 'puts `task git:staged:minitest --silent` if "{{.STAGED}}" == "true"'

  ##
  # - https://github.com/mbj/mutant/blob/main/docs/mutant-rspec.md#run-through-example
  #
  mutant:
    cmds:
      - bundle exec mutant run --include lib --require convenient_service --integration rspec -- 'ConvenientService*'

  ##
  # NOTE: Usage examples.
  #   APPRAISAL=all task playground
  #   APPRAISAL=dry task playground
  #   APPRAISAL=rails_5.2 task playground
  #   APPRAISAL=rails_6.0 task playground
  #   APPRAISAL=rails_6.1 task playground
  #   APPRAISAL=rails_7.0 task playground
  #   APPRAISAL=rails_7.1 task playground
  #   APPRAISAL=rails_7.2 task playground
  #   task playground
  #
  # NOTE: Setting `APPRAISAL` after `task playground` does NOT work. Consider to open an issue.
  # NOTE: `task playground` is also aliased as `task console`.
  # NOTE: `APPRAISAL_COMMAND` must be kept in sync with `Appraisals` file.
  #
  playground:
    cmds:
      - "{{.BUNDLE_EXEC_PREFIX}} rake console"
    vars:
      BUNDLE_EXEC_PREFIX: *BUNDLE_EXEC_PREFIX
    interactive: true

  ##
  # NOTE: See `task console` for usage examples.
  #
  pry:
    cmds:
      - "{{.BUNDLE_EXEC_PREFIX}} rake pry"
    vars:
      BUNDLE_EXEC_PREFIX: *BUNDLE_EXEC_PREFIX
    interactive: true

  release:
    cmds:
      - gem release

  ##
  # NOTE: Usage examples.
  #   task rspec
  #   APPRAISAL=all task rspec
  #   APPRAISAL=dry task rspec
  #   APPRAISAL=rails_5.2 task rspec
  #   APPRAISAL=rails_6.0 task rspec
  #   APPRAISAL=rails_6.1 task rspec
  #   APPRAISAL=rails_7.0 task rspec
  #   APPRAISAL=rails_7.1 task rspec
  #   APPRAISAL=rails_7.2 task rspec
  #
  # NOTE: It is also possible to run specs only for git staged files.
  #   STAGED=true APPRAISAL=rails_7.0 task rspec
  #
  # NOTE: git staged docs.
  # - https://githowto.com/staging_and_committing
  #
  # NOTE: Setting `APPRAISAL` after `task rspec` does NOT work. Consider to open an issue.
  # NOTE: `APPRAISAL_COMMAND` must be kept in sync with `Appraisals` file.
  #
  # NOTE: Ruby ternary operator can NOT be used since it contains colon that has special meaning in YAML. That is why `if/then/else/end` is used.
  #
  rspec:
    cmds:
      - "{{.BUNDLE_EXEC_PREFIX}} rspec --color --format progress {{.REQUIRE_SUFFIX}} {{.GIT_STAGED_RSPEC_FILES}} {{.CLI_ARGS}}"
    vars:
      REQUIRE_SUFFIX:
        sh: ruby -e 'puts case "{{.APPRAISAL}}" when /rails/ then "--require rails_helper" when /dry/ then "--require dry_helper" when /amazing_print/ then "--require amazing_print_helper" when /awesome_print/ then "--require awesome_print_helper" else "--require standard_helper" end'
      GIT_STAGED_RSPEC_FILES:
        sh: ruby -e 'puts `task git:staged:rspec --silent` if "{{.STAGED}}" == "true"'
      BUNDLE_EXEC_PREFIX: *BUNDLE_EXEC_PREFIX

  ##
  # NOTE: `task rspec APPRAISAL=rails_6.1` does NOT work.
  #
  rspec:all:
    cmds:
      - task: rspec
      - task: rspec
        vars:
          APPRAISAL: rails_7.1
      - task: rspec
        vars:
          APPRAISAL: dry
      - task: rspec
        vars:
          APPRAISAL: awesome_print
      - task: rspec
        vars:
          APPRAISAL: amazing_print
      - task: rspec
        vars:
          APPRAISAL: rails_7.2
      - task: rspec
        vars:
          APPRAISAL: rails_7.0
      - task: rspec
        vars:
          APPRAISAL: rails_6.1
      - task: rspec
        vars:
          APPRAISAL: rails_6.0
      - task: rspec
        vars:
          APPRAISAL: rails_5.2

  ##
  # NOTE: Usage examples.
  #   task rubocop
  #   AUTOCORRECT=true task rubocop
  #
  rubocop:
    cmds:
      - bundle exec rubocop --config .rubocop.yml {{.AUTOCORRECT_SUFFIX}} {{.CLI_ARGS}}
    vars:
      AUTOCORRECT_SUFFIX:
        sh: ruby -e 'puts "-A" if "{{.AUTOCORRECT}}" == "true"'

  test:
    cmds:
      - task: rspec:all
      - task: minitest

  ##
  # NOTE: Dev only command.
  #
  tmuxinator:start:
    cmds:
      - tmuxinator start convenient_service --project-config=.dev/.tmuxinator.yml
    preconditions:
      - *from-host-os

  ##
  # NOTE: Dev only command.
  #
  tmuxinator:stop:
    cmds:
      - tmuxinator stop convenient_service --project-config=.dev/.tmuxinator.yml
    preconditions:
      - *from-host-os

  yard_junk:
    cmds:
      - mkdir -p docs
      ##
      # NOTE: yard supports plugins as gems only.
      # - https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#plugin-support
      #
      # NOTE: `RUBYLIB` is used to extend Ruby's `$LOAD_PATH`. This way yard treats `./yard` folder as a directory with custom gems.
      #
      - RUBYLIB=./yard bundle exec yard-junk --text --html docs/junk-yard.html