Taskfile.yaml

version: "3"

set: [errexit, nounset, pipefail]
silent: true

vars:
  TYPOS_VERSION: '{{.TYPOS_VERSION | default "1.45.1"}}'

tasks:
  default:
    cmd: task --list --sort alphanumeric

  run:
    desc: "Run a command inside the project environment (usage: task run -- python ...)"
    cmd: uv run {{.CLI_ARGS}}

  setup:
    desc: Create or reuse the local Python environment and install repo tooling
    cmds:
      - uv venv --allow-existing --python 3.13.3
      - uv sync --all-groups --extra notebooks
      - uv run python -m ipykernel install --sys-prefix --name joint-client-python --display-name "Python (joint-client-python)"
      - uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
      - task: install:ripgrep
      - task: install:typos
      - cmd: |
          if [ -f .env ]; then
            echo ".env already exists; leaving it untouched"
          else
            cp .env.sample .env
            echo "Created .env from .env.sample"
          fi
      - cmd: 'echo "Activate virtual environment with: . .venv/bin/activate"'

  lint:
    desc: Run Ruff lint checks
    cmd: uv run ruff check .

  license-check:
    desc: Verify every Python source file has the required copyright/SPDX header
    cmd: docker run --rm -v "$PWD:/src" --workdir /src apache/skywalking-eyes:0.8.0 -c .licenserc.yaml header check

  format:
    desc: Run Ruff formatter (rewrites files in place)
    cmd: uv run ruff format .

  typecheck:
    desc: Run ty static type checks
    cmd: uv run ty check --output-format concise --error-on-warning

  test:
    desc: Run the unit test suite
    cmd: uv run pytest -n auto

  coverage:
    desc: Run tests with coverage enforcement
    cmd: uv run pytest -n auto --cov=jointfm_client --cov-report=term-missing --cov-fail-under=90

  build:
    desc: Build and validate the source distribution and wheel
    cmds:
      - uv build
      - uv run python scripts/validate_distribution.py

  check:
    desc: Run static code quality checks (read-only; no file modifications)
    cmds:
      - task: typos
      - task: lint
      - uv run ruff format --check .
      - task: typecheck

  release:require-tag:
    desc: Fail fast if Commitizen has no base tag to bump from
    cmd: |
      EXPECTED="v$(uv run cz version --project)"
      if git rev-parse -q --verify "refs/tags/$EXPECTED" >/dev/null; then
        echo "OK: base tag $EXPECTED found"
        exit 0
      fi
      echo "FAIL: base tag $EXPECTED does not exist."
      echo "Commitizen needs an annotated tag matching the current pyproject version"
      echo "to compute the next bump. Seed it once with:"
      echo
      echo "  git tag -a $EXPECTED -m 'Seed initial release tag for Commitizen'"
      echo "  git push --tags"
      echo
      echo "Then rerun this task."
      exit 1

  release:dry:
    desc: Preview the next SemVer bump (no commit, no tag, no file changes)
    cmds:
      - task: release:require-tag
      - |
        uv run cz bump --dry-run --yes {{.CLI_ARGS}}
        echo "OK: dry-run succeeded (no files modified)"

  release:check:
    desc: Verify the working tree is ready to cut a release
    cmds:
      - task: release:require-tag
      - |
        echo "[1/3] checking working tree is clean..."
        if [ -n "$(git status --porcelain)" ]; then
          echo "FAIL: working tree has uncommitted changes; commit or stash first"
          exit 1
        fi
        echo "[2/3] checking current branch is main..."
        BRANCH="$(git symbolic-ref --short HEAD)"
        if [ "$BRANCH" != "main" ]; then
          echo "FAIL: cz bump must run on main (currently on $BRANCH)"
          exit 1
        fi
        echo "[3/3] fetching origin/main and checking alignment..."
        git fetch --quiet origin main
        if [ "$(git rev-parse HEAD)" != "$(git rev-parse origin/main)" ]; then
          echo "FAIL: local main is not aligned with origin/main; pull/push first"
          exit 1
        fi
        echo "OK: release pre-flight passed"

  release:
    desc: Cut a SemVer release with Commitizen (writes CHANGELOG, bumps versions, tags)
    cmds:
      - task: release:check
      - |
        PREV="$(uv run cz version --project)"
        echo "bumping version with Commitizen (writing files, tagging)..."
        uv run cz bump --yes {{.CLI_ARGS}}
        NEXT="$(uv run cz version --project)"
        echo
        echo "OK: released v$PREV -> v$NEXT"
        echo "  bumped version in: pyproject.toml, src/jointfm_client/__init__.py, README.md"
        echo "  updated: CHANGELOG.md, uv.lock"
        echo "  created tag: v$NEXT"
        echo "  publish with: task release:publish"

  release:publish:
    desc: Push the release commit and its tag to origin (triggers the PyPI publish workflow)
    cmds:
      - task: release:require-tag
      - |
        TAG="v$(uv run cz version --project)"
        echo "[1/5] checking working tree is clean..."
        if [ -n "$(git status --porcelain)" ]; then
          echo "FAIL: working tree has uncommitted changes; commit them first"
          exit 1
        fi
        echo "[2/5] checking current branch is main..."
        BRANCH="$(git symbolic-ref --short HEAD)"
        if [ "$BRANCH" != "main" ]; then
          echo "FAIL: releases are published from main (currently on $BRANCH)"
          exit 1
        fi
        echo "[3/5] checking $TAG points at HEAD..."
        if [ "$(git rev-parse "$TAG^{commit}")" != "$(git rev-parse HEAD)" ]; then
          echo "FAIL: $TAG does not point at HEAD."
          echo "The wheel published from this tag must match the commit on main."
          echo "This usually means the release PR was squashed or rebased instead"
          echo "of merged, so the tagged commit is no longer part of main."
          exit 1
        fi
        echo "[4/5] checking $TAG is not already published..."
        git fetch --quiet origin main
        if [ -n "$(git ls-remote --tags origin "refs/tags/$TAG")" ]; then
          echo "FAIL: origin already has $TAG; PyPI does not allow reusing a version."
          echo "Cut a new release instead of republishing this one."
          exit 1
        fi
        echo "[5/5] commits to be pushed to origin/main:"
        git --no-pager log --oneline origin/main..HEAD
        echo
        if [ -t 0 ]; then
          printf 'Push main and %s to origin? This publishes %s to PyPI. [y/N] ' "$TAG" "$TAG"
          read -r CONFIRMATION
          case "$CONFIRMATION" in
            y|Y|yes|YES) ;;
            *)
              echo "OK: aborted, nothing was pushed"
              exit 1
              ;;
          esac
        fi
        git push origin main
        git push origin "refs/tags/$TAG"
        echo
        echo "OK: pushed main and $TAG to origin"
        echo "  the Publish to PyPI workflow now builds and uploads $TAG"

  typos:
    desc: Run the spelling checker
    cmds:
      - task: install:typos
      - typos --config typos.toml --force-exclude --sort .

  pre-commit:
    desc: Run pre-commit hooks on all files
    cmd: |
      set +e
      uv run pre-commit run --all-files
      PRE_COMMIT_STATUS=$?
      MSG_STATUS=0
      if [ -s .git/COMMIT_EDITMSG ]; then
        uv run pre-commit run --hook-stage commit-msg --commit-msg-filename .git/COMMIT_EDITMSG
        MSG_STATUS=$?
      fi
      if [ "$PRE_COMMIT_STATUS" -ne 0 ] || [ "$MSG_STATUS" -ne 0 ]; then
        exit 1
      fi

  install:ripgrep:
    desc: Install ripgrep using the available system package manager
    cmds:
      - |
        if command -v rg >/dev/null 2>&1; then
          exit 0
        fi
        if command -v apt >/dev/null 2>&1; then
          sudo apt update && sudo apt install -y ripgrep
        elif command -v dnf >/dev/null 2>&1; then
          rpm -q spal-release >/dev/null 2>&1 || sudo dnf install -y spal-release
          sudo dnf install -y ripgrep
        elif command -v yum >/dev/null 2>&1; then
          sudo yum install -y ripgrep
        elif command -v pacman >/dev/null 2>&1; then
          sudo pacman -Sy --noconfirm ripgrep
        elif command -v brew >/dev/null 2>&1; then
          brew install ripgrep
        else
          echo "No supported package manager found for automatic ripgrep installation."
          echo "Install ripgrep manually, then rerun: task setup"
          exit 1
        fi

  install:typos:
    desc: Install typos using Homebrew when available, otherwise download a release binary with curl
    cmds:
      - |
        LOCAL_TYPOS="$HOME/.local/bin/typos"
        if command -v typos >/dev/null 2>&1; then
          echo "typos already installed: $(command -v typos)"
          exit 0
        fi
        if [ -x "$LOCAL_TYPOS" ]; then
          echo "typos already installed: $LOCAL_TYPOS"
          exit 0
        fi
        if command -v brew >/dev/null 2>&1; then
          if brew list typos-cli >/dev/null 2>&1 || brew install typos-cli; then
            if command -v typos >/dev/null 2>&1; then
              echo "Installed typos via Homebrew: $(command -v typos)"
              exit 0
            fi
          fi
        fi
        if ! command -v curl >/dev/null 2>&1; then
          echo "curl is required to download typos automatically."
          echo "Install curl or typos manually, then rerun: task setup"
          exit 1
        fi
        if ! command -v tar >/dev/null 2>&1; then
          echo "tar is required to unpack the typos release archive."
          echo "Install tar or typos manually, then rerun: task setup"
          exit 1
        fi
        if ! command -v install >/dev/null 2>&1; then
          echo "install is required to place the typos binary."
          echo "Install coreutils or typos manually, then rerun: task setup"
          exit 1
        fi
        VERSION="{{.TYPOS_VERSION}}"
        ARCH="$(uname -m)"
        case "$ARCH" in
          x86_64|amd64)
            ARCH="x86_64"
            ;;
          arm64|aarch64)
            ARCH="aarch64"
            ;;
          *)
            echo "Unsupported typos architecture: $ARCH"
            exit 1
            ;;
        esac
        OS_NAME="$(uname -s)"
        case "$OS_NAME" in
          Darwin)
            TARGET="$ARCH-apple-darwin"
            ARCHIVE_EXT="tar.gz"
            ;;
          Linux)
            TARGET="$ARCH-unknown-linux-musl"
            ARCHIVE_EXT="tar.gz"
            ;;
          *)
            echo "Unsupported typos operating system: $OS_NAME"
            echo "This setup supports Ubuntu, AWS Linux, and macOS only."
            exit 1
            ;;
        esac
        ARCHIVE_NAME="typos-v${VERSION}-${TARGET}.${ARCHIVE_EXT}"
        DOWNLOAD_URL="https://github.com/crate-ci/typos/releases/download/v${VERSION}/${ARCHIVE_NAME}"
        INSTALL_DIR="$HOME/.local/bin"
        TMP_DIR="$(mktemp -d)"
        trap 'rm -rf "$TMP_DIR"' EXIT
        curl -fsSL "$DOWNLOAD_URL" -o "$TMP_DIR/$ARCHIVE_NAME"
        mkdir -p "$INSTALL_DIR"
        tar -xzf "$TMP_DIR/$ARCHIVE_NAME" -C "$TMP_DIR"
        install "$TMP_DIR/typos" "$INSTALL_DIR/typos"
        echo "Installed typos to $INSTALL_DIR/typos"
        case ":$PATH:" in
          *":$INSTALL_DIR:"*)
            ;;
          *)
            echo "Add $INSTALL_DIR to PATH if you want to invoke typos directly in new shells."
            ;;
        esac