justfile

#!/usr/bin/env -S just --working-directory . --justfile
# Load project-specific properties from the `.env` file

set dotenv-load := true

# Whether coverage should be measured when running tests. Use `create-coverage-report` to create a report from the collected data.

coverage := env("COVERAGE_REPORT", "false")

# The output directory for documentation artifacts

output_dir := "output"

# Lists all available recipes.
default:
    just --list

# Adds pre-commit and pre-push git hooks
[private]
add-hooks:
    #!/usr/bin/env bash
    set -euo pipefail

    echo just run-pre-commit-hook > .git/hooks/pre-commit
    chmod +x .git/hooks/pre-commit

    echo just run-pre-push-hook > .git/hooks/pre-push
    chmod +x .git/hooks/pre-push

    cat > .git/hooks/prepare-commit-msg <<'EOL'
    #!/bin/sh

    COMMIT_MSG_FILE=$1
    COMMIT_SOURCE=$2

    SOB=$(git var GIT_COMMITTER_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')
    git interpret-trailers --in-place --trailer "$SOB" "$COMMIT_MSG_FILE"
    if test -z "$COMMIT_SOURCE"; then
        /usr/bin/perl -i.bak -pe 'print "\n" if !$first_line++' "$COMMIT_MSG_FILE"
    fi
    EOL
    chmod +x .git/hooks/prepare-commit-msg

# Updates the local cargo index and displays which crates would be updated
[private]
dry-update:
    cargo update --dry-run --verbose

# Ensures that one or more required commands are installed
[private]
ensure-command +command:
    #!/usr/bin/env bash
    set -euo pipefail

    read -r -a commands <<< "{{ command }}"

    for cmd in "${commands[@]}"; do
        if ! command -v "$cmd" > /dev/null 2>&1 ; then
            printf "Couldn't find required executable '%s'\n" "$cmd" >&2
            exit 1
        fi
    done

# Retrieves the configured target directory for cargo.
[private]
get-cargo-target-directory:
    just ensure-command cargo jq
    cargo metadata --format-version 1 | jq -r  .target_directory

# Gets names of all workspace members
[private]
get-workspace-members:
    cargo metadata --format-version=1 |jq -r '.workspace_members[] | capture("/(?<name>[a-z-]+)#.*").name'

# Gets metadata version of a workspace member
[private]
get-workspace-member-version package:
    #!/usr/bin/env bash
    set -euo pipefail

    readonly version="$(cargo metadata --format-version=1 |jq -r --arg pkg {{ package }} '.workspace_members[] | capture("/(?<name>[a-z-]+)#(?<version>[0-9.]+)") | select(.name == $pkg).version')"

    if [[ -z "$version" ]]; then
        printf "No version found for package %s\n" {{ package }} >&2
        exit 1
    fi

    printf "$version\n"

# Installs a `set` of ALPM packages.
[private]
install-alpm-package-set set:
    #!/usr/bin/env bash
    set -euo pipefail

    readonly set="{{ set }}"

    # Sets of basic default packages for various targets.
    #
    # Overrides take place in the switch case, when adding packages to the (initially empty) `packages` array.
    readonly build_book=(
        cargo-depgraph
        graphviz
        mdbook
        mdbook-mermaid
    )
    readonly check_commits=(
        git
        cocogitto
        codespell
        committed
        ripgrep
    )
    readonly check_dependencies=(cargo-deny)
    readonly check_licenses=(
        git
        reuse
    )
    readonly check_links=(lychee)
    readonly check_rust=(
        clang
        python
    )
    readonly check_shell=(
        ripgrep
        shellcheck
        tangler
    )
    readonly check_spelling=(codespell)
    readonly check_unused=(cargo-machete)
    readonly dev=(
        biome
        cargo-insta
        git-cliff
        miniserve
        release-plz
        voa-verifiers-arch
        watchexec
    )
    readonly docs=(
        clang
        jq
        python
        uv
    )
    readonly format=(
        biome
        cargo-sort-derives
        clang
        mado
        taplo
        uv
    )
    readonly lint_website=(
         biome
         pnpm
         zola
    )
    readonly manpages=(
        clang
        lowdown
        rust-script
    )
    readonly pkgbuild=(alpm-pkgbuild-bridge)
    readonly publish=(
        clang
        jq
        maturin
        uv
        zig
    )
    readonly python_dev=(
         maturin
         uv
         zig
    )
    readonly rust_dev=(rustup)
    readonly test=(
        cargo-nextest
        clang
        meson
    )
    readonly test_containerized=(podman)
    readonly test_coverage=(
        cargo-llvm-cov
        cargo-nextest
        clang
        jq
        maturin
        meson
        python
        uv
    )
    readonly test_readmes=(
        clang
        diffutils
        jq
        meson
        rust-script
        tangler
    )

    # Start with an empty set of packages and add to it in the below switch-case.
    packages=()

    case "$set" in
        all)
            packages+=(
                "${build_book[@]}"
                "${check_commits[@]}"
                "${check_spelling[@]}"
                "${check_shell[@]}"
                "${check_rust[@]}"
                "${check_unused[@]}"
                "${check_dependencies[@]}"
                "${check_licenses[@]}"
                "${check_links[@]}"
                "${dev[@]}"
                "${docs[@]}"
                "${format[@]}"
                "${lint_website[@]}"
                "${manpages[@]}"
                "${pkgbuild[@]}"
                "${python_dev[@]}"
                "${rust_dev[@]}"
                "${test[@]}"
                "${test_containerized[@]}"
                "${test_coverage[@]}"
                "${test_readmes[@]}"
            )
            ;;
        book)
            packages+=(
                "${build_book[@]}"
                "${docs[@]}"
                "${lint_website[@]}"
            )
            ;;
        commits)
            packages+=("${check_commits[@]}")
            ;;
        containerized)
            packages+=(
                "${test_coverage[@]}"
                "${test_containerized[@]}"
            )
            ;;
        coverage)
            packages+=("${test_coverage[@]}")
            ;;
        docs)
            packages+=("${docs[@]}")
            ;;
        dependencies)
            packages+=("${check_dependencies[@]}")
            ;;
        formatting)
            packages+=("${format[@]}")
            ;;
        licenses)
            packages+=("${check_licenses[@]}")
            ;;
        lint-website)
            packages+=("${lint_website[@]}")
            ;;
        links)
            packages+=("${check_links[@]}")
            ;;
        manpages)
            packages+=("${manpages[@]}")
            ;;
        publish)
            packages+=("${publish[@]}")
            ;;
        python-dev)
            packages+=(
                "${pkgbuild[@]}"
                "${python_dev[@]}"
                "${rust_dev[@]}"
            )
            ;;
        readmes)
            packages+=("${test_readmes[@]}")
            ;;
        rust)
            packages+=("${check_rust[@]}")
            ;;
        rust-dev)
            packages+=(
                "${pkgbuild[@]}"
                "${rust_dev[@]}"
            )
            ;;
        shell)
            packages+=("${check_shell[@]}")
            ;;
        spelling)
            packages+=("${check_spelling[@]}")
            ;;
        test)
            packages+=("${test[@]}")
            ;;
        unused)
            packages+=("${check_unused[@]}")
            ;;
        *)
            printf 'Invalid package set %s' "$set" >&2
            exit 1
    esac

    just ensure-command pacman run0

    # Deduplicate using an associative array
    declare -A unique_packages
    for package in "${packages[@]}"; do
        if [[ ! "${unique_packages[$package]+_}" ]]; then
            unique_packages["$package"]=1
        fi
    done

    # Use run0 when not root
    command=()
    if (( "$(id -u)" > 0 )); then
        command+=(run0)
    fi
    command+=(
        pacman -Su --needed --noconfirm
    )

    "${command[@]}" "${!unique_packages[@]}"

# Checks if a string matches a workspace member exactly
[private]
is-workspace-member package:
    #!/usr/bin/env bash
    set -euo pipefail

    mapfile -t workspace_members < <(just get-workspace-members 2>/dev/null)

    for name in "${workspace_members[@]}"; do
        if [[ "$name" == {{ package }} ]]; then
            exit 0
        fi
    done
    exit 1

# Runs checks and tests before creating a commit.
[private]
run-pre-commit-hook: check docs test-docs
    just test --features cli

# Runs checks before pushing commits to remote repository.
[private]
run-pre-push-hook: check-commits

# Builds the documentation book using mdbook and stages all necessary rustdocs alongside
[group('build')]
build-book:
    #!/usr/bin/env bash
    set -euo pipefail

    just ensure-command cargo jq mdbook mdbook-mermaid cargo-depgraph dot

    # Build the local dependency graph.
    cargo depgraph --workspace-only | dot -Tpng > resources/docs/src/api-docs/dependency_graph.png

    target_dir="$(just get-cargo-target-directory)"
    readonly output_dir="{{ output_dir }}"
    readonly rustdoc_dir="$output_dir/docs/rustdoc/"
    mapfile -t workspace_members < <(just get-workspace-members 2>/dev/null)

    just docs
    mdbook-mermaid install resources/docs/
    mdbook build resources/docs/

    # move rust docs to their own namespaced dir
    mkdir -p "$rustdoc_dir"
    for name in "${workspace_members[@]}"; do
        cp -r "$target_dir/doc/${name//-/_}" "$rustdoc_dir"
    done

    # move python docs
    cp -r "$target_dir/pdoc/" "$output_dir/docs/pdoc"

    cp -r "$target_dir/doc/"{search.*,src,static.files,trait.impl,type.impl} "$rustdoc_dir"
    cp -r "$target_dir/doc/"*.{js,html} "$rustdoc_dir"

    if [[ ! -f "alpm-lint-website/themes/linkita/theme.toml" ]]; then
        echo "The alpm-lint-website linkita submodule does not exist"
        echo "Did you clone the submodule? Check the contribution guidelines."
        exit 1
    fi

    just --justfile alpm-lint-website/justfile build
    cp -r alpm-lint-website/public "$output_dir/docs/lints"

# Build local documentation
[group('build')]
docs:
    #!/usr/bin/env bash
    set -euo pipefail

    RUSTDOCFLAGS='-D warnings' cargo doc --document-private-items --no-deps

    target_dir="$(just get-cargo-target-directory)"
    uv run --directory python-alpm pdoc -d google -o "$target_dir/pdoc/" alpm

# Render `manpages`, `shell_completions` or `specifications` (`kind`) of a given package (`pkg`).
[group('build')]
generate kind pkg:
    #!/usr/bin/bash

    set -Eeuo pipefail

    readonly output_dir="{{ output_dir }}"
    readonly pkg="{{ pkg }}"
    readonly kind="{{ kind }}"
    mkdir --parents "$output_dir"


    script="$(mktemp --suffix=.ers)"
    readonly script="$script"

    # remove temporary script file on exit
    cleanup() (
      if [[ -n "${script:-}" ]]; then
        rm -f "$script"
      fi
    )

    trap cleanup EXIT

    case "$kind" in
        manpages|shell_completions)
            modules=()
            case "$pkg" in
                alpm-db)
                    modules+=("::desc" "::files")
                    ;;
                alpm-repo-db)
                    modules+=("::desc" "::files")
                    ;;
                *)
                    modules+=("")
                    ;;
            esac

            for module in "${modules[@]}"; do
                sed "s/PKG/$pkg/;s#PATH#$PWD/$pkg#g;s/KIND/$kind/g;s/MODULE/$module/g" > "$script" < .rust-script/allgen.ers
                chmod +x "$script"
                "$script" "$output_dir/$kind"
            done
            ;;
        specifications)
            output_kind=manpages
            mkdir -p "$output_dir/$output_kind/"
            for file in "$PWD/$pkg/resources/specification/"*.md; do
                file_name="$(basename "$file")"
                output_file="${file_name/.md}"
                section="${output_file/*.}"
                lowdown -s -t man -M section="$section" -o "$output_dir/$output_kind/$output_file" "$file"
            done
            ;;
        *)
            printf 'Only "manpages", "shell_completions" or "specifications" are supported targets.\n'
            exit 1
    esac

# Generates shell completions
[group('build')]
generate-completions:
    just generate shell_completions alpm-buildinfo
    just generate shell_completions alpm-db
    just generate shell_completions alpm-lint
    just generate shell_completions alpm-mtree
    just generate shell_completions alpm-pkginfo
    just generate shell_completions alpm-repo-db
    just generate shell_completions alpm-srcinfo

# Generates all manpages and specifications
[group('build')]
generate-manpages-and-specs:
    just generate manpages alpm-buildinfo
    just generate manpages alpm-db
    just generate manpages alpm-lint
    just generate manpages alpm-mtree
    just generate manpages alpm-pkginfo
    just generate manpages alpm-srcinfo
    just generate specifications alpm-buildinfo
    just generate specifications alpm-db
    just generate specifications alpm-mtree
    just generate specifications alpm-package
    just generate specifications alpm-pkginfo
    just generate specifications alpm-repo
    just generate specifications alpm-repo-db
    just generate specifications alpm-srcinfo
    just generate specifications alpm-state-repo
    just generate specifications alpm-types

[doc('Builds the Python alpm package for a given platform (`platform`).
Supported platforms are `all` (prepares sdist and wheels for x86_64, aarch64 and riscv64),
`sdist` (only source distribution), `current` (builds wheel for current platform) or any valid `--target` value for maturin')]
[group('build')]
[working-directory('python-alpm')]
build-python platform="current":
    #!/usr/bin/env bash
    set -euo pipefail

    readonly platform="{{ platform }}"

    just ensure-command maturin zig

    case "$platform" in
        "all")
            # We use zig cc to create manylinux compatible wheels
            # this skips the need for running this in a manylinux container
            just ensure-command rustup
            rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu riscv64gc-unknown-linux-gnu
            maturin sdist -o dist
            maturin build --release --zig --target=x86_64-unknown-linux-gnu -o dist
            maturin build --release --zig --target=aarch64-unknown-linux-gnu -o dist
            maturin build --release --zig --target=riscv64gc-unknown-linux-gnu -o dist
            ;;
        "sdist")
            maturin sdist -o dist
            ;;
        "current")
            maturin build --release --zig -o dist
            ;;
        *)
            just ensure-command rustup
            rustup target add "$platform"
            maturin build --release --zig --target="$platform" -o dist
    esac

# Checks source code formatting
[group('check')]
check-formatting:
    just ensure-command biome cargo-sort-derives mado taplo uv

    just --unstable --fmt --check

    biome check --indent-style=space --expand=always renovate.json

    # We're using nightly to properly group imports, see rustfmt.toml
    cargo +nightly fmt -- --check

    taplo format --check

    # Checks for consistent sorting of rust derives
    cargo sort-derives --check

    mado check

    uv run --directory python-alpm ruff format --check

# Runs all check targets
[group('check')]
check: check-spelling check-formatting check-shell-code check-rust-code check-python-code check-unused-deps check-dependencies check-licenses check-links

# Checks commit messages for correctness
[group('check')]
check-commits:
    #!/usr/bin/env bash
    set -euo pipefail

    just ensure-command codespell cog committed rg

    readonly default_branch="${CI_DEFAULT_BRANCH:-main}"

    if ! git rev-parse --verify "origin/$default_branch" > /dev/null 2>&1; then
        printf "The default branch '%s' does not exist!\n" "$default_branch" >&2
        exit 1
    fi

    tmpdir="$(mktemp --dry-run --directory)"
    readonly check_tmpdir="$tmpdir"
    mkdir -p "$check_tmpdir"

    # remove temporary dir on exit
    cleanup() (
      if [[ -n "${check_tmpdir:-}" ]]; then
        rm -rf "${check_tmpdir}"
      fi
    )

    trap cleanup EXIT

    for commit in $(git rev-list "origin/${default_branch}.."); do
        printf "Checking commit %s\n" "$commit"

        commit_message="$(git show -s --format=%B "$commit")"
        codespell_config="$(mktemp --tmpdir="$check_tmpdir")"

        # either use the commit's .codespellrc or create one
        if git show "$commit:.codespellrc" > /dev/null 2>&1; then
            git show "$commit:.codespellrc" > "$codespell_config"
        else
            printf "[codespell]\nskip = .cargo,.git,target,.env,Cargo.lock\nignore-words-list = crate\n" > "$codespell_config"
        fi

        if ! rg -q "Signed-off-by: " <<< "$commit_message"; then
            printf "Commit %s ❌️\n" "$commit" >&2
            printf "The commit message lacks a \"Signed-off-by\" line.\n" >&2
            printf "%s\n" \
                "  Please use:" \
                "    git rebase --signoff main && git push --force-with-lease" \
                "  See https://developercertificate.org/ for more details." >&2
            exit 1
        elif ! codespell --config "$codespell_config" - <<< "$commit_message"; then
            printf "Commit %s ❌️\n" "$commit" >&2
            printf "The spelling of the commit message needs improvement.\n" >&2
            exit 1
        elif ! cog verify "$commit_message"; then
            printf "Commit %s ❌️\n" "$commit" >&2
            printf "%s\n" \
                "The commit message is not a conventional commit message:" \
                "$commit_message" \
                "See https://www.conventionalcommits.org/en/v1.0.0/ for more details." >&2
            exit 1
        elif ! committed "$commit"; then
            printf "Commit %s ❌️\n" "$commit" >&2
            printf "%s\n" \
                "The commit message does not meet the required standards:" \
                "$commit_message"
            exit 1
        else
            printf "Commit %s ✅️\n\n" "$commit"
        fi
    done

# Checks for issues with dependencies
[group('check')]
check-dependencies: dry-update
    cargo deny --all-features check

# Checks licensing status
[group('check')]
check-licenses:
    just ensure-command reuse
    reuse lint

# Check for stale links in documentation
[group('check')]
check-links:
    #!/usr/bin/env bash

    set -euo pipefail

    readonly output_dir="{{ output_dir }}"

    just ensure-command lychee
    # Only run lychee if the book has been built at least once.
    if [[ -d "${output_dir}/docs" ]]; then
        lychee .
    else
        printf 'Skipping link checking, as the book has not been built.\nRun `just build-book` to build the book.'
    fi

# Checks the Rust source code using cargo-clippy.
[group('check')]
check-rust-code:
    just ensure-command cargo cargo-clippy
    cargo clippy --all-features --all-targets --workspace -- -D warnings

# Checks the Python source code using ruff and mypy.
[group('check')]
check-python-code:
    uv run --directory python-alpm ruff check
    uv run --directory python-alpm mypy --strict .

# Checks shell code using shellcheck.
[group('check')]
check-shell-code:
    just check-shell-readme alpm-buildinfo
    just check-shell-readme alpm-mtree
    just check-shell-readme alpm-pkginfo
    just check-shell-readme alpm-srcinfo

    just check-shell-recipe 'test-readme alpm-buildinfo'
    just check-shell-recipe 'test-readme alpm-pkginfo'
    just check-shell-recipe 'test-readme alpm-srcinfo'
    just check-shell-recipe 'test-readme alpm-db'
    just check-shell-recipe build-book
    just check-shell-recipe check-commits
    just check-shell-recipe check-unused-deps
    just check-shell-recipe ci-publish
    just check-shell-recipe containerized-integration-tests
    just check-shell-recipe 'generate shell_completions alpm-buildinfo'
    just check-shell-recipe 'install-alpm-package-set all'
    just check-shell-recipe 'is-workspace-member alpm-buildinfo'
    just check-shell-recipe 'prepare-release alpm-buildinfo'
    just check-shell-recipe 'release alpm-buildinfo'
    just check-shell-recipe 'release python-alpm'
    just check-shell-recipe flaky
    just check-shell-recipe test
    just check-shell-recipe test-docs
    just check-shell-recipe test-python
    just check-shell-recipe docs
    just check-shell-recipe 'ensure-command test'
    just check-shell-recipe virtualized-integration-tests
    just check-shell-recipe build-python

    just check-shell-script alpm-srcinfo/tests/generate_srcinfo.bash
    just check-shell-script .cargo/runner.sh

# Checks the script examples of a project's README using shellcheck.
[group('check')]
check-shell-readme project:
    just ensure-command shellcheck tangler
    tangler bash < {{ project }}/README.md | shellcheck --shell bash -

# Checks justfile recipe relying on shell semantics using shellcheck.
[group('check')]
check-shell-recipe recipe:
    just ensure-command rg shellcheck
    just -vv -n {{ recipe }} 2>&1 | rg -v '===> Running recipe' | shellcheck -

# Checks a shell script using shellcheck.
[group('check')]
check-shell-script file:
    just ensure-command shellcheck
    shellcheck --shell bash {{ file }}

# Checks common spelling mistakes
[group('check')]
check-spelling:
    just ensure-command codespell
    codespell

# Checks for unused dependencies
[group('check')]
check-unused-deps:
    #!/usr/bin/env bash
    set -euo pipefail

    just ensure-command cargo-machete

    for name in $(just get-workspace-members); do
        cargo machete "$name"
    done

# Adds needed git configuration for the local repository
[group('dev')]
configure-git:
    # Enforce gpg signed keys for this repository
    git config commit.gpgsign true

    just add-hooks

# Installs all tools required for development
[group('dev')]
dev-install: install-pacman-dev-packages install-rust-dev-tools

# Installs all binaries of the workspace
[group('dev')]
install-workspace-binaries:
    #!/usr/bin/env bash
    set -euo pipefail

    mapfile -t workspace_members < <(just get-workspace-members 2>/dev/null)

    # Workspace members without a binary
    ignored_members=(
        alpm-common
        alpm-compress
        alpm-db
        alpm-lint-config
        alpm-package
        alpm-parsers
        alpm-pkgbuild
        alpm-state-repo
        alpm-repo
        alpm-repo-db
        alpm-types
        python-alpm
    )

    for name in "${workspace_members[@]}"; do
        # Make sure we don't try to install any of the ignored binaries.
        skip=false
        for ignored in "${ignored_members[@]}"; do
            if [[ "$name" == "$ignored" ]]; then
                skip=true
                break
            fi
        done

        if [ "$skip" = true ]; then
            continue
        fi

        echo "Installing $name"
        cargo install --locked --path "$name" --features cli
    done

# Fixes common issues. Files need to be git add'ed
[group('dev')]
fix:
    #!/usr/bin/env bash
    set -euo pipefail

    just ensure-command biome cargo codespell git uv

    if ! git diff-files --quiet ; then
        echo "Working tree has changes. Please stage them: git add ."
        exit 1
    fi

    codespell --write-changes
    just --unstable --fmt
    biome format --write --indent-style=space --expand=always renovate.json
    cargo clippy --fix --allow-staged

    # fmt must be last as clippy's changes may break formatting
    cargo +nightly fmt

    uv run --directory python-alpm ruff format
    uv run --directory python-alpm ruff check --fix

# Installs development packages using pacman
[group('dev')]
install-pacman-dev-packages:
    just install-alpm-package-set all

# Installs all Rust tools required for development
[group('dev')]
install-rust-dev-tools:
    rustup default stable
    rustup component add clippy
    # Install nightly as we use it for formatting rules.
    rustup toolchain install nightly
    rustup component add --toolchain nightly rustfmt
    # llvm-tools-preview for code coverage
    rustup component add llvm-tools-preview

# Continuously run integration tests for a given number of rounds
[group('test')]
flaky test='just test-readme alpm-buildinfo' rounds='999999999999':
    #!/usr/bin/bash
    set -euo pipefail

    seq 1 {{ rounds }} | while read -r counter; do
      printf "Running flaky tests (%d/{{ rounds }})...\n" "$counter"
      sleep 1
      {{ test }}
      echo
    done

# Serves the documentation book using miniserve
[group('dev')]
serve-book: build-book
    just ensure-command miniserve
    miniserve --index=index.html {{ output_dir }}/docs

# Watches the documentation book contents and rebuilds on change using mdbook (useful for development)
[group('dev')]
watch-book:
    just ensure-command watchexec
    watchexec --exts md,toml,js --delay-run 5s -- just build-book

# Runs integration tests guarded by the `_containerized-integration-test` feature, located in modules named `containerized` (accepts `cargo nextest run` options via `options`).
[group('test')]
containerized-integration-tests *options:
    #!/usr/bin/env bash
    set -euo pipefail

    readonly coverage="{{ coverage }}"
    commands=(
        cargo
        cargo-nextest
        podman
    )
    read -r -a options <<< "{{ options }}"

    if [[ "$coverage" == "true" ]]; then
        commands+=(cargo-llvm-cov)
        just ensure-command "${commands[@]}"
        # Use the environment prepared by `cargo llvm-cov show-env`
        # shellcheck source=/dev/null
        source <(cargo llvm-cov show-env --export-prefix)
    else
        just ensure-command "${commands[@]}"
    fi

    cargo build --examples --bins
    cargo nextest run --features _containerized-integration-test,cli --filterset 'kind(test) and binary_id(/::containerized$/)' "${options[@]}"

[doc('Creates code coverage report for all projects from all available sources.
When providing `with-docs` to the `mode` parameter, this also includes doc test coverage in the report (requires nightly).
The `metrics_name` parameter can be used to override the metrics name in the `coverage-metrics.txt` file used by GitLab.')]
[group('test')]
create-coverage-report mode="without-docs" metrics_name="Test-coverage":
    #!/usr/bin/env bash
    set -euo pipefail

    readonly metrics_name="{{ metrics_name }}"
    readonly mode="{{ mode }}"
    target_dir="$(just get-cargo-target-directory)"

    just ensure-command cargo-llvm-cov cargo-nextest jq

    mkdir --parents "$target_dir/llvm-cov/"

    # Options for cargo
    cargo_options=(+stable)

    # The chosen reporting style (defaults to without doctest coverage)
    reporting_style="without doctest coverage"

    # Options for creating cobertura coverage report with cargo-llvm-cov
    cargo_llvm_cov_cobertura_options=(
        --cobertura
        --output-path "$target_dir/llvm-cov/cobertura-coverage.xml"
    )

    # Options for creating coverage report summary with cargo-llvm-cov
    cargo_llvm_cov_summary_options=(
        --json
        --summary-only
    )

    if [[ "$mode" == "with-docs" ]]; then
        reporting_style="with doctest coverage"
        # The support for doctest coverage is a nightly feature
        cargo_options=(+nightly)
        cargo_llvm_cov_cobertura_options+=(--doctests)
        cargo_llvm_cov_summary_options+=(--doctests)
    fi

    printf "Creating report %s\n" "$reporting_style"

    # Use the environment prepared by `cargo llvm-cov show-env`
    # shellcheck source=/dev/null
    source <(cargo llvm-cov show-env --export-prefix)

    # Create cobertura coverage report
    cargo "${cargo_options[@]}" llvm-cov report "${cargo_llvm_cov_cobertura_options[@]}"

    printf "Calculating percentage...\n"

    # Get total coverage percentage from summary
    percentage="$(cargo "${cargo_options[@]}" llvm-cov report "${cargo_llvm_cov_summary_options[@]}" | jq '.data[0].totals.lines.percent')"

    # Trim percentage to 4 decimal places.
    percentage="$(LC_NUMERIC=C printf "%.4f\n" "$percentage")"

    # Writes to target/coverage-metrics.txt for Gitlab CI metric consumption.
    # https://docs.gitlab.com/ci/testing/metrics_reports/
    printf "%s %s\n" "$metrics_name" "$percentage" > "$target_dir/llvm-cov/coverage-metrics.txt"
    printf "Test-coverage: %s%%\n" "$percentage"

# Runs all unit tests. Options to `cargo nextest run` can be passed in using `options`.
[group('test')]
test *options:
    #!/usr/bin/env bash
    set -euo pipefail

    readonly coverage="{{ coverage }}"
    commands=(
        cargo
        cargo-nextest
    )
    read -r -a options <<< "{{ options }}"
    # If no options are provided, run all targets, locked, with cli checks.
    if (( ${#options[@]} == 0 )); then
        options+=(
            --locked
            --all
            --features cli
        )
    fi

    if [[ "$coverage" == "true" ]]; then
        commands+=(cargo-llvm-cov)
        just ensure-command "${commands[@]}"
        # Use the environment prepared by `cargo llvm-cov show-env`
        # shellcheck source=/dev/null
        source <(cargo llvm-cov show-env --export-prefix)
    else
        just ensure-command "${commands[@]}"
    fi

    cargo nextest run "${options[@]}"

# Runs all doc tests. Options to `cargo test` can be passed in using `options`.
[group('test')]
test-docs *options:
    #!/usr/bin/env bash
    set -euo pipefail

    readonly coverage="{{ coverage }}"
    toolchain="+stable"
    commands=(cargo)
    read -r -a options <<< "{{ options }}"

    if [[ "$coverage" == "true" ]]; then
        commands+=(cargo-llvm-cov)
        toolchain="+nightly"
        just ensure-command "${commands[@]}"
        # Use the environment prepared by `cargo llvm-cov show-env`
        # shellcheck source=/dev/null
        source <(cargo "$toolchain" llvm-cov show-env --export-prefix)
    else
        just ensure-command "${commands[@]}"
    fi

    cargo "$toolchain" test --locked --doc "${options[@]}"

# Runs per project end-to-end tests found in a project README.md
[group('test')]
test-readme project:
    #!/usr/bin/env bash
    set -euo pipefail

    CARGO_HOME="${CARGO_HOME:-$HOME/.cargo}"

    install_executables() {
        printf "Installing executables of %s...\n" "{{ project }}"
        cargo install --locked --path {{ project }} --features cli
    }

    install_executables

    PATH="$CARGO_HOME/bin:$PATH"
    printf "PATH=%s\n" "$PATH"

    cd {{ project }} && PATH="$PATH" tangler bash < README.md | bash -euo pipefail -

# Run end-to-end tests for README files of projects
[group('test')]
test-readmes:
    just test-readme alpm-buildinfo
    just test-readme alpm-pkginfo
    just test-readme alpm-srcinfo
    just test-readme alpm-soname
    just test-readme alpm-lint
    just test-readme alpm-db

# Run tests for Python bindings (accepts pytest `options`).
[group('test')]
[working-directory('python-alpm')]
test-python *options:
    #!/usr/bin/env bash
    set -euo pipefail

    readonly coverage="{{ coverage }}"
    commands=(
        uv
    )

    if [[ "$coverage" == "true" ]]; then
        commands+=(
            cargo-llvm-cov
            maturin
        )
        just ensure-command "${commands[@]}"
        # Use the environment prepared by `cargo llvm-cov show-env`
        # shellcheck source=/dev/null
        source <(cargo llvm-cov show-env --export-prefix)
        uv sync
        maturin develop
        # No reinstall arg as this would remove coverage instrumentation added by maturin
        uv run pytest {{ options }}
    else
        just ensure-command "${commands[@]}"
        uv run --reinstall-package python-alpm pytest {{ options }}
    fi

# Runs integration tests guarded by the `_virtualized-integration-test` feature (accepts `cargo nextest run` options via `options`).
[group('test')]
virtualized-integration-tests *options:
    #!/usr/bin/env bash
    set -euo pipefail

    readonly coverage="{{ coverage }}"
    commands=(cargo)
    read -r -a options <<< "{{ options }}"

    just ensure-command bash cargo cargo-nextest
    if [[ "$coverage" == "true" ]]; then
        commands+=(cargo-llvm-cov)
        just ensure-command "${commands[@]}"
        # Use the environment prepared by `cargo llvm-cov show-env`
        # shellcheck source=/dev/null
        source <(cargo llvm-cov show-env --export-prefix)
    else
        just ensure-command "${commands[@]}"
    fi

    cargo build --examples --bins
    cargo nextest run --features _virtualized-integration-test,cli --filterset 'kind(test) and binary_id(/::virtualized$/)' "${options[@]}"

# Publishes a crate in the workspace from GitLab CI in a pipeline for tags
[group('release')]
ci-publish:
    #!/usr/bin/env bash
    set -euo pipefail

    # auth tokens with publishing capabilities are expected to be set in GitLab project settings
    readonly cargo_token="${CARGO_REGISTRY_TOKEN:-}"
    readonly uv_token="${UV_PUBLISH_TOKEN:-}"

    # rely on predefined variable to retrieve git tag: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html
    readonly tag="${CI_COMMIT_TAG:-}"
    readonly crate="${tag//\/*/}"
    readonly version="${tag#*/}"

    just ensure-command cargo uv

    if [[ -z "$tag" ]]; then
        printf "There is no tag!\n" >&2
        exit 1
    fi
    if ! just is-workspace-member "$crate" &>/dev/null; then
        printf "The crate %s is not a workspace member of the project!\n" "$crate" >&2
        exit 1
    fi

    current_member_version="$(just get-workspace-member-version "$crate" 2>/dev/null)"
    readonly current_member_version="$current_member_version"
    if [[ "$version" != "$current_member_version" ]]; then
        printf "Current version in metadata of crate %s (%s) does not match the version from the tag (%s)!\n" "$crate" "$current_member_version" "$version"
        exit 1
    fi

    printf "Found tag %s (crate %s in version %s).\n" "$tag" "$crate" "$version"

    case "$crate" in
        "python-alpm")
            if [[ -z "$uv_token" ]]; then
                printf "There is no token for PyPI!\n" >&2
                exit 1
            fi

            just build-python all
            uv --directory "$crate" publish
          ;;
        *)
            if [[ -z "$cargo_token" ]]; then
                printf "There is no token for crates.io!\n" >&2
                exit 1
            fi

            cargo publish -p "$crate"
          ;;
    esac

# Prepares the release of a crate by updating dependencies, incrementing the crate version and creating a changelog entry (optionally, the version can be set explicitly)
[group('release')]
prepare-release package version="":
    #!/usr/bin/env bash
    set -euo pipefail

    readonly package_name="{{ package }}"
    if [[ -z "$package_name" ]]; then
        printf "No package name provided!\n"
        exit 1
    fi
    readonly package_version="{{ version }}"
    branch_name=""

    just ensure-command git release-plz

    # We use git-cliff directly for python-alpm as release-plz does version checks against crates.io
    # and we don't publish bindings to crates.io so it fails to determine the next version.
    # Additionally release-plz uses cargo-semver-checks to detect breaking changes,
    # but since our API is in Python, this would produce false positives.
    # git-cliff calculates version bumps solely based on commit messages.
    case "$package_name" in
        "python-alpm")
            just ensure-command git-cliff

            readonly cliff_common_options=(
                --workdir "$package_name"
            )
            readonly cliff_bump_options=(
                "${cliff_common_options[@]}"
                --bump
                --prepend "$package_name/CHANGELOG.md"
                --unreleased
            )
            git-cliff "${cliff_bump_options[@]}"
            bumped_version="$(git-cliff "${cliff_common_options[@]}" --bumped-version)"

            # git-cliff returns "package/version", but release-plz expects "package@version"
            release-plz set-version "${bumped_version%/*}@${bumped_version##*/}"
            ;;
        *)
            release-plz update --update-deps --package "$package_name"
            ;;
    esac

    # NOTE: When setting the version specifically, we are likely in a situation where `release-plz` did not detect a version change (e.g. when only changes to top-level files took place since last release).
    # In this case we are fine to potentially have no changes in the CHANGELOG.md or having to adjust it manually afterwards.
    if [[ -n "$package_version" ]]; then
        release-plz set-version "${package_name}@${package_version}"
    fi

    # make sure that the current version would be publishable, but ignore files not added to git
    cargo publish -p "$package_name" --dry-run --allow-dirty

    updated_package_version="$(just get-workspace-member-version "$package_name")"
    readonly updated_package_version="$updated_package_version"

    if [[ -n "$package_version" ]]; then
        branch_name="release/$package_name/$package_version"
    else
        branch_name="release/$package_name/$updated_package_version"
    fi
    git checkout -b "$branch_name"

    git add Cargo.* $package_name
    git commit --gpg-sign --signoff --message "chore: Upgrade $package_name crate to $updated_package_version"
    git push --set-upstream origin "$branch_name"

# Creates a release of a crate in the workspace by creating a tag and pushing it
[group('release')]
release package:
    #!/usr/bin/env bash
    set -euo pipefail

    package_version="$(just get-workspace-member-version {{ package }})"
    readonly package_version="$package_version"
    if [[ -z "$package_version" ]]; then
        exit 1
    fi
    readonly current_version="{{ package }}/$package_version"

    just ensure-command git

    if [[ -n "$(git tag -l "$current_version")" ]]; then
        printf "The tag %s exists already!\n" "$current_version" >&2
        exit 1
    fi

    printf "Creating tag %s...\n" "$current_version"
    git tag -s "$current_version" -m "$current_version"
    printf "Pushing tag %s...\n" "$current_version"
    git push origin refs/tags/"$current_version"