Taskfile.yml

# Task runner for Manifest V3 for Chromium browsers
# =================================================
# As of Aug. 2022 Firefox is not supported.
#
# This task runner requires Task to be installed.
# https://taskfile.dev/#/installation
#
version: "3"

silent: true

vars:
  REQDOCS: "task requires the installation of mkdocs: https://www.mkdocs.org/user-guide/installation"
  REQPNPM: "task requires the installation of pnpm: https://pnpm.io/installation"
  REQSHX: "task requires the installation of shelljs/shx: https://github.com/shelljs/shx"
  REQWEXT: "task requires the installation of Web-ext: https://github.com/mozilla/web-ext"
  REQMAT: "task requires the installation of Material for MkDocs: https://squidfunk.github.io/mkdocs-material"

tasks:
  default:
    desc: List the available tasks.
    cmds:
     - task --list

  # install and uninstall packages and libraries
  inst-packages:
    desc: Installs both the dependencies and dev-dependencies contained in the package.json.
    aliases: [i]
    preconditions:
      - sh: pnpm -v
        msg: "{{.REQPNPM}}"
    cmds:
      - cmd: pnpm install
      - task: packages-copy

  inst-docs:
    desc: Install required Python packages for documentation (mkdocs, mkdocs-material).
    aliases: [id]
    cmds:
      - cmd: pip install mkdocs mkdocs-material

  inst-puppeteer:
    desc: Download the required Chrome browser for Puppeteer.
    aliases: [ip]
    cmds:
      - cmd: pnpm exec puppeteer browsers install chrome

  rm-puppeteer:
    desc: Remove the downloaded Chrome browser for Puppeteer.
    aliases: [rp]
    cmds:
      - cmd: rm -rf ~/.cache/puppeteer

  # linting commands
  lints:
    desc: Run both regular linting and security linting.
    aliases: [ll]
    ignore_error: true
    cmds:
      - task: lint
      - task: lint-security

  lint:
    desc: Lint the JavaScript files in the `ext` directory.
    aliases: [l]
    ignore_error: true
    cmds:
      - cmd: echo 'Running ESLint on extension scripts...'
      # node and dependencies
      - cmd: pnpm exec eslint ext/scripts/sw/*.js --stats
      - cmd: pnpm exec eslint ext/scripts/*.js --stats

  lint-security:
    desc: Run security linting with ESLint security plugins.
    aliases: [ls]
    ignore_error: true
    cmds:
      - cmd: echo 'Running security linting on extension scripts...'
      - cmd: cd ext && node test/autogen-lint-security.mjs

  lint-coverage:
    desc: Generate code coverage summary report.
    aliases: [lc]
    cmds:
      - cmd: echo 'Generating code coverage summary...'
      - cmd: cd ext && node test/autogen-coverage.mjs

  lint-benchmark:
    desc: Run performance benchmarks.
    aliases: [lb]
    cmds:
      - cmd: echo 'Running performance benchmarks...'
      - cmd: cd ext && node test/autogen-benchmark.mjs 2>/dev/null # hide library errors

  lint-benchmark-expanded:
    desc: Run expanded performance benchmarks.
    aliases: [lbe]
    cmds:
      - cmd: echo 'Running expanded performance benchmarks...'
      - cmd: cd ext && node test/autogen-benchmark-1.mjs

  lint-benchmark-error:
    desc: Run error handling benchmarks.
    aliases: [lme]
    cmds:
      - cmd: echo 'Running error handling benchmarks...'
      - cmd: cd ext && node test/autogen-benchmark-2.mjs 2>/dev/null

  lint-metrics:
    desc: Track and compare metrics over time.
    aliases: [lm]
    cmds:
      - cmd: echo 'Tracking metrics...'
      - cmd: cd ext && node test/autogen-metric.mjs 2>/dev/null

  # user commands that are displayed with `task --list`
  build:
    desc: Creates the submission package for Chrome.
    summary: |
      Creates a package that is intended for submission to the Chrome Web Store
      and Microsoft Edge Add-ons.

      Packaged file will be located in /web-ext-artifacts
    cmds:
      - task: build-chrome

  build-chrome:
    # edit web-ext-chrome.mjs to hide files and directories
    preconditions:
      - sh: pnpm -v
        msg: "{{.REQPNPM}}"
      - sh: pnpm exec web-ext --version
        msg: "{{.REQWEXT}}"
    cmds:
      - task: packages-copy
      - cmd: pnpm exec web-ext --config ext/.web-ext-chrome.mjs --source-dir ./ext build
        ignore_error: true

  checks:
    desc: Check, run and print the versions of the task commands and dependencies.
    ignore_error: true
    cmds:
      # node and dependencies
      - cmd: echo '• Checking Node.js'
      - cmd: pnpm exec shx echo -n "Node.js "
      - cmd: node --version
      - cmd: echo '• Checking pnpm and web-ext'
      - cmd: pnpm exec shx echo -n "pnpm version "
      - cmd: pnpm --version
      - cmd: pnpm exec shx --version
      - cmd: pnpm exec shx echo -n "Web-ext v"
      - cmd: pnpm exec web-ext --version
      # python and dependencies
      - cmd: echo '• Checking Python and the dependencies'
      - cmd: python --version
      - cmd: mkdocs --version
      - cmd: pip --version
      - cmd: pip show mkdocs-material --quiet
      # system tools
      - cmd: echo '• Checking Git and Task'
      - cmd: git --version
      - cmd: task --version

  # packages for the web extension and builds
  packages-copy:
    desc: Copies the dependencies from `node_modules` over to the `ext` directory.
    aliases: [pc]
    preconditions:
      - sh: pnpm -v
        msg: "{{.REQPNPM}}"
      - sh: pnpm exec shx --version
        msg: "{{.REQSHX}}"
    # use shx for Windows compatibility
    cmds:
      - cmd: pnpm exec shx cp -f "node_modules/bulma/css/bulma.min.css" "ext/css/bulma.min.css"
      - cmd: pnpm exec shx cp -f "node_modules/qunit/qunit/qunit.css" "ext/test/qunit.css"
      - cmd: pnpm exec shx cp -f "node_modules/qunit/qunit/qunit.js" "ext/test/qunit.js"
      - cmd: pnpm exec shx cp -f "node_modules/linkifyjs/dist/linkify.js" "ext/js/linkify.js"
      - cmd: pnpm exec shx cp -f "node_modules/linkify-plugin-ip/dist/linkify-plugin-ip.js" "ext/js/linkify-plugin-ip.js"
      - cmd: pnpm exec shx cp -f "node_modules/linkify-element/dist/linkify-element.js" "ext/js/linkify-element.js"
      - cmd: pnpm exec shx cp -f "node_modules/dompurify/dist/purify.js" "ext/js/purify.js"

  packages-latest:
    desc: Interactively update to the latest dependencies and copy them to the `ext` directory.
    aliases: [pl]
    preconditions:
      - sh: pnpm -v
        msg: "{{.REQPNPM}}"
      - sh: pnpm exec shx --version
        msg: "{{.REQSHX}}"
    cmds:
      - cmd: pnpm update --interactive --latest
      - cmd: pnpm exec shx echo ""
      - task: packages-copy

  packages-update:
    desc: Updates all dependencies to the latest version and copies them to the `ext` directory.
    aliases: [pu]
    preconditions:
      - sh: pnpm -v
        msg: "{{.REQPNPM}}"
      - sh: pnpm exec shx --version
        msg: "{{.REQSHX}}"
    cmds:
      - cmd: pnpm update
      - cmd: pnpm exec shx echo ""
      - task: packages-copy

  # unit tests
  test:
    desc: Run QUnit tests.
    aliases: [t]
    cmds:
      - cmd: node ext/test/qunit-terminal.mjs
  test-old:
    desc: Run QUnit tests in a real Chrome WebExtension context using Puppeteer.
    aliases: [to]
    cmds:
      - cmd: node ext/test/qunit-puppeteer.mjs

  test-cli:
    desc: Run QUnit tests in headless Chrome using Puppeteer, it will return failed tests.
    aliases: [tc]
    cmds:
      - cmd: node ext/test/qunit-headless.mjs

  test-webextension:
    desc: Run RetroTxt WebExtension with proper file:/// URL handling.
    aliases: [ext]
    cmds:
      - cmd: echo 'Testing RetroTxt WebExtension with file:/// URLs...'
      - cmd: cd ext && node test/autogen-webextension.mjs
      - cmd: echo 'WebExtension test completed. Check browser for results.'

  # documentation
  docs-build:
    desc:  Build the current documentation in use on https://docs.retrotxt.com.
    aliases: [doc]
    preconditions:
      - sh: pip show mkdocs-material
        msg: "{{.REQMAT}}"
      - sh: pnpm -v
        msg: "{{.REQPNPM}}"
      - sh: pnpm mkdocs -V
        msg: "{{.REQDOCS}}"
    cmds:
      - cmd: pnpm mkdocs build

  docs-serve:
    desc:  Run an internal server to view the documentation in `docs`.
    aliases: [docs]
    preconditions:
      # - sh: pip show mkdocs-material
      #   msg: "{{.REQMAT}}"
      - sh: pnpm -v
        msg: "{{.REQPNPM}}"
      - sh: pnpm mkdocs -V
        msg: "{{.REQDOCS}}"
    cmds:
      - cmd: pnpm mkdocs serve
        ignore_error: true # ignore Ctrl-C exit interrupts