Stirling-PDF/.taskfiles/engine.yml

version: '3'

vars:
  # File selections as git pathspecs: git does the include/exclude matching, so
  # there is no grep/xargs and it behaves identically on every platform.
  PY_FILES: >-
    'scripts/**/*.py'
    'src/**/*.py'
    ':(exclude)**/tool_io.py'
    ':(exclude)**/tool_models.py'

tasks:
  install:
    desc: "Install engine runtime and development dependencies"
    run: once
    cmds:
      - uv python install 3.13.8
      - uv sync --locked --group engine --group engine-dev
    sources:
      - uv.lock
      - pyproject.toml
    status:
      - test -d .venv

  lock:
    desc: "Update the engine lockfile from project metadata"
    cmds:
      - uv lock

  lock:upgrade:
    desc: "Upgrade allowed engine dependencies and update the lockfile"
    cmds:
      - uv lock --upgrade

  lock:check:
    desc: "Check whether the engine lockfile is current"
    cmds:
      - uv lock --check

  update:
    desc: "Upgrade engine dependencies and synchronize the environment"
    cmds:
      - task: lock:upgrade
      - uv sync --locked --group engine --group engine-dev

  update:all:
    desc: "Upgrade all Python dependency groups and synchronize the environment"
    cmds:
      - task: lock:upgrade
      - uv sync --locked --all-groups

  prepare:
    desc: "Set up engine .env from template"
    deps: [install]
    cmds:
      - uv run --locked --group engine --group engine-dev scripts/setup_env.py
    sources:
      - scripts/setup_env.py
    generates:
      - .env.local

  run:
    desc: "Run engine server"
    deps: [prepare]
    ignore_error: true
    dir: src
    vars:
      PORT: '{{.PORT | default "5001"}}'
    env:
      PYTHONUNBUFFERED: "1"
    cmds:
      - uv run --locked --group engine uvicorn stirling.api.app:app --host 0.0.0.0 --port {{.PORT}} --workers "${STIRLING_ENGINE_WORKERS:-4}"

  dev:
    desc: "Start engine dev server with hot reload"
    deps: [prepare]
    ignore_error: true
    dir: src
    vars:
      PORT: '{{.PORT | default "5001"}}'
    env:
      PYTHONUNBUFFERED: "1"
    cmds:
      - uv run --locked --group engine --group engine-dev uvicorn stirling.api.app:app --host 0.0.0.0 --port {{.PORT}} --reload

  lint:
    desc: "Run linting"
    deps: [install]
    cmds:
      - uv run --locked --group pre-commit ruff check $(git ls-files {{.PY_FILES}})

  lint:fix:
    desc: "Auto-fix lint issues"
    deps: [install]
    cmds:
      - uv run --locked --group pre-commit ruff check $(git ls-files {{.PY_FILES}}) --fix

  format:
    desc: "Auto-fix code formatting"
    deps: [install]
    cmds:
      - uv run --locked --group pre-commit ruff format $(git ls-files {{.PY_FILES}})

  format:check:
    desc: "Check code formatting"
    deps: [install]
    cmds:
      - uv run --locked --group pre-commit ruff format $(git ls-files {{.PY_FILES}}) --diff

  typecheck:
    desc: "Run type checking"
    deps: [install]
    cmds:
      - uv run --locked --group engine --group engine-dev pyright $(git ls-files {{.PY_FILES}}) --warnings

  test:
    desc: "Run tests"
    deps: [prepare]
    cmds:
      - uv run --locked --group engine --group engine-dev pytest tests

  test:coverage:
    desc: "Run tests with coverage reporting"
    deps: [prepare]
    cmds:
      - >-
        uv run --locked --group engine --group engine-dev pytest tests
        --cov=src/stirling
        --cov-fail-under=20
        --cov-report=term-missing
        --cov-report=xml:coverage/coverage.xml
        --cov-report=html:coverage/html
        --cov-report=json:coverage/coverage.json
      - uv run python scripts/check_coverage.py coverage/coverage.json --minimum 20

  fix:
    desc: "Auto-fix lint + format"
    cmds:
      - task: format  # Can auto-fix some things that `lint:fix` can't like line length violations
      - task: lint:fix
      - task: format  # Ensure that after lint fixing that the code is still formatted correctly

  check:
    desc: "Full engine quality gate"
    cmds:
      - task: typecheck
      - task: lint
      - task: format:check
      - task: test

  tool-models:
    desc: "Generate tool_models.py from Java OpenAPI spec (SwaggerDoc.json)"
    deps: [install, ":backend:swagger"]
    cmds:
      - uv run --locked --group engine --group engine-dev python scripts/generate_tool_models.py --spec ../SwaggerDoc.json --output src/stirling/models/tool_models.py --io-output src/stirling/models/tool_io.py
    sources:
      - ../SwaggerDoc.json
      - scripts/generate_tool_models.py
    generates:
      - src/stirling/models/tool_models.py
      - src/stirling/models/tool_io.py

  tool-models:check:
    desc: "Fail if the committed tool models are out of date"
    deps: [install, ":backend:swagger"]
    cmds:
      - uv run --locked --group engine --group engine-dev python scripts/generate_tool_models.py --spec ../SwaggerDoc.json --output src/stirling/models/tool_models.py --io-output src/stirling/models/tool_io.py --check

  clean:
    desc: "Clean build artifacts"
    cmds:
      - task: '{{if eq .OS "Windows_NT"}}clean-windows{{else}}clean-unix{{end}}'

  clean-unix:
    internal: true
    desc: "Clean build artifacts"
    cmds:
      - rm -rf .venv data logs output

  # On Windows, use PowerShell as bash failed to delete some dependencies
  clean-windows:
    internal: true
    desc: "Clean build artifacts"
    ignore_error: true
    cmds:
      - powershell rm -Recurse -Force -ErrorAction SilentlyContinue .venv
      - powershell rm -Recurse -Force -ErrorAction SilentlyContinue data
      - powershell rm -Recurse -Force -ErrorAction SilentlyContinue logs
      - powershell rm -Recurse -Force -ErrorAction SilentlyContinue output