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

  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:typos
      - 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: uv run ruff check --preview --select CPY001 --extend-exclude '*.ipynb' .

  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

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

  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
      - |
        if [ -n "$(git status --porcelain)" ]; then
          echo "FAIL: working tree has uncommitted changes; commit or stash first"
          exit 1
        fi
        BRANCH="$(git symbolic-ref --short HEAD)"
        if [ "$BRANCH" != "main" ]; then
          echo "FAIL: cz bump must run on main (currently on $BRANCH)"
          exit 1
        fi
        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
      - uv run cz bump --yes {{.CLI_ARGS}}
      - |
        TAG="$(git describe --tags --abbrev=0)"
        echo "OK: created tag $TAG. Publish with: git push && git push --tags"

  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: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