Taskfile.yaml

# SPDX-FileCopyrightText: 2024 Roy Wright
#
# SPDX-License-Identifier: MIT

version: "3"

includes:
  # "fe" stands for "front end"
  fe: taskfiles/front-end.yaml
  hatch: taskfiles/hatch.yaml
  uv: taskfiles/uv.yaml
  poetry: taskfiles/poetry.yaml
  setuptools: taskfiles/setuptools.yaml
  variables: taskfiles/front-end-vars.yaml

tasks:
  default:
    cmds:
      - task --list

  make-env:
    desc: Create and update virtual environment
    cmds:
      - task fe:make-env
      - task fe:update-env

  update-env:
    desc: Update virtual environment
    cmds:
      - task fe:update-env

  init:
    desc: Initialize new project (only run once upon first creation of project).
    cmds:
      - git init .
      - git add docs LICENSES scripts src tests .gitignore
        .pre-commit-config.yaml DEV-README.md mkdocs.yml pyproject.toml
        README.md Taskfile.yaml taskfiles/hatch.yaml taskfiles/poetry.yaml
        taskfiles/uv.yaml taskfiles/uv-vars.yaml tox.ini
      # Realizing the template can mess up formatting of the files
      - pre-commit run blacken-docs --all-files >/dev/null || true
      - pre-commit run trailing-whitespace --all-files >/dev/null || true
      - pre-commit run prettier --all-files >/dev/null || true
      - pre-commit run ruff --all-files >/dev/null || true
      - git commit -m "Initial Framework."
      - pre-commit install
      - task: fe:make-env
      - task: fe:update-env
      - task: reuse-enable
    status:
      # do not run the init task if there is a .git/ directory
      - test -d .git

  reuse-enable:
    desc: Enable using SPDX reuse for enforcing copyright and license.
    cmds:
      - '{{.DEV_RUNNER}} toml set --toml-path pyproject.toml tool.taskfile.reuse
        "enabled"'
      - sed --in-place=.bak '/export SKIP=.*$/d' .git/hooks/pre-commit

  reuse-disable:
    desc: Disable using SPDX reuse for enforcing copyright and license.
    cmds:
      - '{{.DEV_RUNNER}} toml set --toml-path pyproject.toml tool.taskfile.reuse
        "disabled"'
      - sed --in-place=.bak '/export SKIP=.*$/d' .git/hooks/pre-commit
      - sed --in-place=.bak "/# start templated/a\export SKIP='reuse'"
        .git/hooks/pre-commit

  reuse-lint:
    desc:
      'Perform reuse checks if pyproject.toml: tools.taskfile.reuse is set to
      "enabled"'
    vars:
      AUTHOR:
        sh:
          "{{.DEV_RUNNER}} toml get --toml-path pyproject.toml
          project.authors[0].name"

      LICENSE:
        sh:
          '{{.DEV_RUNNER}} toml get --toml-path pyproject.toml
          project.license.file | grep -Po "([^/]+)(?=\.txt)"'

      REUSE_ENABLED:
        sh:
          "{{.DEV_RUNNER}} toml get --toml-path pyproject.toml
          tool.taskfile.reuse"

    cmds:
      - 'find . -name "requirements*.txt" -exec {{.DEV_RUNNER}} reuse annotate
        --copyright "{{.AUTHOR}}" --license "{{.LICENSE}}" --force-dot-license
        --skip-existing "{}" \; | grep "Successfully" || true'
      - "{{.DEV_RUNNER}} reuse lint"
    status:
      # if return is false, run the above commands
      - $( ! $( $(test "{{.REUSE_ENABLED}}" = "enabled") && [[ $(ls -1
        requirements*.txt **/requirements*.txt 2>/dev/null | wc -l) > 0 ]] ) )

  lint:
    desc: Perform static code analysis.
    cmds:
      - "{{.DEV_RUNNER}} ruff check --config pyproject.toml --fix src tests"
      - "{{.DEV_RUNNER}} scripts/run-mypy-all-python-versions.sh"
      - "{{.DEV_RUNNER}} fawltydeps --detailed || true"
      - task: reuse-lint
      - "{{.DEV_RUNNER}} pyupgrade --py311-plus"
      # Disallow improper capitalization
      - scripts/fail_on_regex_match.sh "PyBind|Numpy|Cmake|CCache|Github|PyTest"
      # lint shell scripts
      - 'git ls-files -z -- "*.sh" | xargs -0 {{.DEV_RUNNER}} shellcheck'

  format:
    desc: Check and reformat the code to a coding standard.
    cmds:
      - "{{.DEV_RUNNER}} ruff format --config pyproject.toml src tests"
      - 'git ls-files -z -- "*.md" "*.py" | xargs -0 --verbose {{.DEV_RUNNER}}
        blacken-docs'

  check-pyproject:
    desc:
      Check the consistency between poetry and hatch in the pyproject.toml file.
    cmds:
      # check that project and tool.poetry tables are in sync
      - "{{.DEV_RUNNER}} python3 -m check_pyproject --loglevel INFO"

  check-licenses:
    desc: Check that all dependency licenses are acceptable for this project.
    cmds:
      # check licenses
      - "{{.DEV_RUNNER}} liccheck -s pyproject.toml"
      - task: check-reuse

  check-reuse:
    desc: Check if project is REUSE compliant.
    vars:
      REUSE_ENABLED:
        sh:
          "{{.DEV_RUNNER}} toml get --toml-path pyproject.toml
          tool.taskfile.reuse"

    cmds:
      # add any missing copyrights
      - 'git diff --name-only --cached | xargs -I {} {{.DEV_RUNNER}} reuse
        annotate -c "$(git config --get user.name)" "{}"'
      # create software bill of materials
      - "{{.DEV_RUNNER}} reuse spdx -o reuse.spdx"
    status:
      - test "{{.REUSE_ENABLED}}" = "disabled"

  pre-commit:
    desc: Must pass before allowing version control commit.
    # called from the "pre-commit" hook and the "task build"
    cmds:
      - task: check-pyproject

  execute-pre-commit:
    # [private] internal task for running the pre-commit utility directly and conditionally skipping reuse hook
    vars:
      REUSE_ENABLED:
        sh:
          "{{.DEV_RUNNER}} toml get --toml-path pyproject.toml
          tool.taskfile.reuse"

      SKIP:
        sh:
          if test "{{.REUSE_ENABLED}}" = "disabled"; then echo "reuse"; else
          echo ""; fi
    cmds:
      - SKIP="{{.SKIP}}" pre-commit run --all-files || true

  build:
    desc: Build the project.
    cmds:
      - task fe:build

  make:
    desc: Make the project (format, lint, check, build, metrics, docs).
    summary: |
      Make the project

      Format the project, check for code quality, check for compliance,
      perform unit testing, build distributables, build documentation,
      and run the application to display its version.
    cmds:
      # show project's environment
      - task: fe:show-env
      # cleanup
      - rm -rf test-install
      # format the source code
      - task: format
      # check for programming errors/warnings
      - task: lint
      # check that code can be committed to vcs
      - task: execute-pre-commit
      # create dist packages
      - task: fe:build
      # install current build into dev virtual environment
      - task: fe:update-env
      # check licenses
      - task: check-licenses
      # run unit test and generate coverage reports
      - task: coverage
      # generate code metrics
      - task: metrics
      # build documentation
      - task: build-docs
      # actually run the built application, getting its version
      - task: version

  test:
    desc: Run the unit tests for the supported versions of python.
    cmds:
      # hatch supports matrix testing for multiple python coverage
      - task: fe:unit-test

  version:
    desc: Run the project, having it return its version.
    vars:
      APP_NAME:
        sh: "{{.DEV_RUNNER}} toml get --toml-path pyproject.toml project.name"
    cmds:
      - "{{.DEFAULT_RUNNER}} python3 -m {{.APP_NAME}} --version"

  pypi-version:
    desc:
      Get the current version of the given package(s) from pypi and output as
      PEP508 dependency specifier(s).
    summary: |
      Get the current version of the given package(s) from pypi and output as PEP508 dependency specifier(s).
      Example usage:
      ➤ task pypi_version -- httpx tomlkit
      task: [pypi_version] scripts/latest_pypi_version.sh httpx tomlkit
      httpx>=0.27.0
      tomlkit>=0.13.0

    cmds:
      - "scripts/latest_pypi_version.sh {{.CLI_ARGS}}"

  metrics:
    desc: Analyze the code.
    cmds:
      - bash -c "mkdir -p metrics"
      - "{{.METRICS_RUNNER}} radon cc --show-complexity --json --min=A
        --output-file=metrics/code-complexity.json src/"
      - "cat metrics/code-complexity.json | {{.METRICS_RUNNER}} python3
        scripts/metrics_cc_filter.py | head -n 20"
      - "{{.METRICS_RUNNER}} radon hal --json
        --output-file=metrics/halstead-metrics.json src/"
      - "{{.METRICS_RUNNER}} radon mi --json
        --output-file=metrics/maintainability-index.json src/"
      - "{{.METRICS_RUNNER}} radon raw --json
        --output-file=metrics/raw-metrics.json src/"

  coverage:
    desc: Run the unit tests with coverage.
    cmds:
      - "{{.DEV_RUNNER}} pytest --cov-report term-missing --cov-report
        json:metrics/coverage.json --cov-report html:metrics/coverage
        --cov=./src tests"

  docs:
    desc: Create the project documentation and open in the browser.
    cmds:
      - task: build-docs
      - task: serve-docs

  build-docs:
    desc: Build the documentation.
    cmds:
      - "{{.DOCS_RUNNER}} mkdocs --quiet build"

  serve-docs:
    desc: Start the documentation server and open browser at localhost:8000.
    cmds:
      - "{{.DOCS_RUNNER}} mkdocs serve --open"

  clean:
    desc: Remove virtual environments and generated files.
    cmds:
      - sh -c 'if command -v pre-commit >/dev/null 2>&1; then pre-commit clean
        || true; fi'
      - task: fe:env-prune
      - rm -rf .tox
      - rm -rf .nox
      - rm -rf .coverage
      - rm -rf build
      - rm -rf dist
      - rm -rf metrics
      - rm -rf site
      - rm -rf src/*.egg-info
      - rm -rf tests/__pycache__
      - rm -rf test-install
      - rm -rf .*_cache
      - rm -f requirements.txt
      - rm -f requirements.txt.license
      - rm -f requirements/requirements*.txt
      - rm -f requirements/requirements*.txt.license
      - rm -f poetry.lock
      - task: deactivate

  deactivate:
    # [private] if a virtual environment is active, deactivate it.
    cmds:
      - source .venv/bin/deactivate 2>/dev/null || true

  switch-to-uv:
    desc: Switch development to use uv.
    cmds:
      - task: clean
      - rm -f taskfiles/front-end.yaml taskfiles/front-end-vars.yaml
      - ln -s uv.yaml taskfiles/front-end.yaml
      - ln -s uv-vars.yaml taskfiles/front-end-vars.yaml
      - task: uv:make-env
      - task: uv:update-env
      - task: uv:show-env

  switch-to-hatch:
    desc: Switch development to use hatch.
    cmds:
      - "{{.DEV_RUNNER}} python3 scripts/swap_build_system.py hatch"
      - task: clean
      - rm -f taskfiles/front-end.yaml taskfiles/front-end-vars.yaml
      - ln -s hatch.yaml taskfiles/front-end.yaml
      - ln -s hatch-vars.yaml taskfiles/front-end-vars.yaml
      - task: hatch:make-env
      - task: hatch:update-env
      - task: hatch:show-env

  switch-to-poetry:
    desc: Switch development to use poetry.
    cmds:
      - "{{.DEV_RUNNER}} python3 scripts/swap_build_system.py poetry"
      - task: clean
      - rm -f taskfiles/front-end.yaml taskfiles/front-end-vars.yaml
      - ln -s poetry.yaml taskfiles/front-end.yaml
      - ln -s poetry-vars.yaml taskfiles/front-end-vars.yaml
      - task: poetry:make-env
      - task: poetry:update-env
      - task: poetry:show-env

  switch-to-setuptools:
    desc: Switch development to use setuptools.
    cmds:
      - "{{.DEV_RUNNER}} python3 scripts/swap_build_system.py setuptools"
      - rm -f taskfiles/front-end.yaml taskfiles/front-end-vars.yaml
      - ln -s setuptools.yaml taskfiles/front-end.yaml
      - ln -s setuptools-vars.yaml taskfiles/front-end-vars.yaml
      - task: clean
      - task: setuptools:make-env
      - task: setuptools:update-env
      - task: setuptools:show-env

  lockfiles-disable:
    desc:
      Disable backend to use requirements.txt files managed by pip-compile as
      lock files.
    cmds:
      - task fe:lockfiles-disable

  lockfiles-enable:
    desc:
      Enable backend to use requirements.txt files managed by pip-compile as
      lock files.
    cmds:
      - task fe:lockfiles-enable

  publish-test-pypi:
    desc: Publish to the test.pypi.org server.
    vars:
      APP_NAME:
        sh: "{{.DEV_RUNNER}} toml get --toml-path pyproject.toml project.name"
    cmds:
      - "{{.DEFAULT_RUNNER}} twine upload --repository testpypi dist/*"
      - rm -rf test-install
      - mkdir test-install
      - python3 -m venv test-install/.venv
      - test-install/.venv/bin/pip3 install -i https://test.pypi.org/simple/
        {{.APP_NAME}} --extra-index-url https://pypi.org/simple/
      - test-install/.venv/bin/{{.APP_NAME}} --version
      - echo "ok to delete test-install/"

  publish-pypi:
    desc: Publish to the pypi.org server.
    cmds:
      - "{{.DEFAULT_RUNNER}} twine upload --repository pypi dist/*"

  main-module:
    desc:
      "Run the __main__ module code, passing arguments to the module.  Example:
      task main -- --version"
    vars:
      APP_NAME:
        sh: "{{.DEV_RUNNER}} toml get --toml-path pyproject.toml project.name"
    cmds:
      - "{{.DEFAULT_RUNNER}} python3 -m {{.APP_NAME}} {{.CLI_ARGS}}"

  main:
    desc:
      "Run the application's script in the virtual environment's bin directory."
    vars:
      APP_NAME:
        sh: "{{.DEV_RUNNER}} toml get --toml-path pyproject.toml project.name"
    cmds:
      - "{{.DEFAULT_RUNNER}} {{.APP_NAME}} {{.CLI_ARGS}}"

  version-bumper:
    desc: "Manage the project's version with version-bumper"
    cmds:
      - "{{.DEFAULT_RUNNER}} version_bumper {{.CLI_ARGS}}"