myproject

#!/usr/bin/env -S mycmd project run
# -*- mode: shell-script; sh-shell: bash; sh-basic-offset: 4; sh-indentation: 4; coding: utf-8 -*-
# shellcheck shell=bash

set -o nounset -o errexit -o errtrace -o pipefail

project.load_task_library "shell"
project.load_task_library "git"

# shellcheck disable=SC2154
readonly BIN_DIR="${MYPROJECT_BASE_DIR}/bin"
readonly SUPPORT_DIR="${MYPROJECT_BASE_DIR}/support"
readonly TESTING_BASE="${MYPROJECT_BASE_DIR}/testing"
readonly TEST_FILES_BASE="${TESTING_BASE}/tests"
readonly TEST_USER_BASE="${TESTING_BASE}/user-base"
readonly SYSTEM_BASE="${MYPROJECT_BASE_DIR}/mycmd"
readonly VENDOR_DIR="${MYPROJECT_BASE_DIR}/vendor"
readonly TEST_VENDOR_DIR="${TESTING_BASE}/vendor"
readonly VENDOR_WORKING_DIR="${MYPROJECT_BASE_DIR}/vendor/.working"
readonly TMP_WORKING_DIR="${MYPROJECT_BASE_DIR}/tmp"
readonly DOCS_DIR="${MYPROJECT_BASE_DIR}/docs"

if [[ ! -d "${TMP_WORKING_DIR}" ]]; then
    mkdir -p "${TMP_WORKING_DIR}" || true
fi

WORKTREES_PARENT_DIR="$(cd "$(dirname "${MYPROJECT_BASE_DIR}")" &>/dev/null && pwd -P)"
readonly WORKTREES_PARENT_DIR

mycmd.trace "Set the following variables:"
mycmd.trace "- BIN_DIR: ${BIN_DIR}"
mycmd.trace "- SUPPORT_DIR: ${SUPPORT_DIR}"
mycmd.trace "- TESTING_BASE: ${TESTING_BASE}"
mycmd.trace "- TEST_FILES_BASE: ${TEST_FILES_BASE}"
mycmd.trace "- TEST_USER_BASE: ${TEST_USER_BASE}"
mycmd.trace "- SYSTEM_BASE: ${SYSTEM_BASE}"
mycmd.trace "- VENDOR_DIR: ${VENDOR_DIR}"
mycmd.trace "- TEST_VENDOR_DIR: ${TEST_VENDOR_DIR}"
mycmd.trace "- VENDOR_WORKING_DIR: ${VENDOR_WORKING_DIR}"
mycmd.trace "- TMP_WORKING_DIR: ${TMP_WORKING_DIR}"
mycmd.trace "- DOCS_DIR: ${DOCS_DIR}"
mycmd.trace "- WORKTREES_PARENT_DIR: ${WORKTREES_PARENT_DIR}"

#----------------------------------------
# Project File Sets
# All Files
project.register_fileset ALL_FILES
project.find_files_for_fileset ALL_FILES "${BIN_DIR}" "${SYSTEM_BASE}" "${TEST_FILES_BASE}" "${TEST_USER_BASE}" -type f
# shellcheck disable=SC2154
project.add_files_to_fileset ALL_FILES "${MYPROJECT_PROJECT_FILE}"
project.register_task_with_fileset list-all-files \
    project.list-files \
    ALL_FILES

# Implementation Files Only
project.register_fileset IMPLEMENTATION_FILES
project.find_files_for_fileset IMPLEMENTATION_FILES "${BIN_DIR}" "${SYSTEM_BASE}" -type f
project.register_task_with_fileset list-implementation-files \
    project.list-files \
    IMPLEMENTATION_FILES

# Test Files Only
project.register_fileset TEST_FILES
project.find_files_for_fileset TEST_FILES "${TEST_FILES_BASE}" -type f -name '*-test'
project.register_task_with_fileset list-test-files \
    project.list-files \
    TEST_FILES

# MyCmd Lib and Support Libraries Only
project.register_fileset MYCMD_LIB_FILES
project.find_files_for_fileset MYCMD_LIB_FILES "${SYSTEM_BASE}" -maxdepth 1 -name "*-lib"
project.register_task_with_fileset list-mycmd-lib-files \
    project.list-files \
    MYCMD_LIB_FILES

#----------------------------------------
# Vendored Code Management
function _update_vendored_file_for_vendor_base_dir() {
    local -r source_path="${VENDOR_WORKING_DIR}/${1}"
    local -r vendor_dir="${2}"
    local -r dest_path="${vendor_dir}/${3}"
    local -r dest_dir=$(dirname "${dest_path}")

    if [[ ! -e "${source_path}" ]]; then
        mycmd.log "Source file '${source_path}' not found."
        return 1
    fi

    if [[ ! -e "${dest_dir}" ]]; then
        mkdir -p "${dest_dir}"
    fi

    if [[ -e "${dest_path}" ]]; then
        if diff -q "${source_path}" "${dest_path}"; then
            mycmd.log "Vendored file '${dest_path}' is up to date."
            return 0
        fi
    fi

    mycmd.log "Updating vendor destination '${dest_path}'."
    cp -a "${source_path}" "${dest_path}"
}

function _update_vendored_file() {
    _update_vendored_file_for_vendor_base_dir "${1}" "${VENDOR_DIR}" "${2}"
}

function _update_vendored_test_file() {
    _update_vendored_file_for_vendor_base_dir "${1}" "${TEST_VENDOR_DIR}" "${2}"
}

function update-ansi() {
    # https://github.com/fidian/ansi
    if [[ ! -e "${VENDOR_WORKING_DIR}/ansi" ]]; then
        mkdir -p "${VENDOR_WORKING_DIR}" 2>/dev/null || true
        cd "${VENDOR_WORKING_DIR}"
        mycmd.output "Cloning ansi git repository."
        git clone --quiet git@github.com:fidian/ansi.git
    fi

    cd "${VENDOR_WORKING_DIR}/ansi"
    mycmd.output "Pulling latest ansi changes from git."
    git pull --rebase --quiet

    _update_vendored_file "ansi/ansi" "ansi"
}
project.register_task update-ansi

function update-bashup-events() {
    # https://github.com/bashup/events/tree/bash44
    if [[ ! -e "${VENDOR_WORKING_DIR}/bashup.events" ]]; then
        mkdir -p "${VENDOR_WORKING_DIR}" 2>/dev/null || true
        cd "${VENDOR_WORKING_DIR}"
        mycmd.output "Cloning bashup.events git repository."
        git clone --quiet -b bash44 git@github.com:bashup/events.git bashup.events
    fi

    cd "${VENDOR_WORKING_DIR}/bashup.events"
    mycmd.output "Pulling latest bashup.events changes from git."
    git pull --rebase --quiet

    _update_vendored_file "bashup.events/bashup.events" "bashup.events"
}
project.register_task update-bashup-events

function update-shunit2() {
    # https://github.com/kward/shunit2/tree/master
    if [[ ! -e "${VENDOR_WORKING_DIR}/shunit2" ]]; then
        mkdir -p "${VENDOR_WORKING_DIR}" 2>/dev/null || true
        cd "${VENDOR_WORKING_DIR}"
        mycmd.output "Cloning shunit2 git repository."
        git clone --quiet git@github.com:kward/shunit2.git shunit2
    fi

    cd "${VENDOR_WORKING_DIR}/shunit2"
    mycmd.output "Pulling latest shunit2 changes from git."
    git pull --rebase --quiet

    _update_vendored_test_file "shunit2/shunit2" "shunit2"
    _update_vendored_test_file "shunit2/shunit2_test_helpers" "shunit2_test_helpers"
}
project.register_task update-shunit2

#----------------------------------------
# Code Metrics
mycmd.defer_at_startup mycmd.init_bin sed
function list-mycmd-lib-functions() {
    local -n fileset="${1}"

    grep -E '^[[:space:]]*function' "${fileset[@]}" \
        | mycmd.bin_execute sed -n 's/.*function \(.*\)() {/\1/p' \
        | sort -u
}
project.register_task_with_fileset list-mycmd-lib-functions \
    list-mycmd-lib-functions \
    MYCMD_LIB_FILES

mycmd.defer_at_startup mycmd.init_bin sed
mycmd.defer_at_startup mycmd.init_bin grep
function list-mycmd-lib-functions-with-source-file() {
    local -n fileset="${1}"

    mycmd.bin_execute grep -H -E '^[[:space:]]*function' "${fileset[@]}" \
        | mycmd.bin_execute sed -r -n 's/^([^:]+):.*function (.*)\(\) \{/\1,\2/p' \
        | sort -u
}
project.register_task_with_fileset list-mycmd-lib-functions-with-source-file list-mycmd-lib-functions-with-source-file MYCMD_LIB_FILES

function generate-shell-function-index() {
    if ! mycmd.init_bin_no_exit index-shell-functions; then
        mycmd.log "Neccessary tool 'index-shell-functions' not found."
        return 1
    fi

    local -n fileset="${1}"

    # TODO: Handle subdirectories
    local src_file
    for src_file in "${fileset[@]}"; do
        # shellcheck disable=SC2155
        local dest_file="${TMP_WORKING_DIR}/$(basename "${src_file}").csv"
        project.verbose "Generating index for ${src_file} to ${dest_file}"
        mycmd.bin_execute index-shell-functions "${src_file}" "${dest_file}"
    done
}
project.register_task_with_fileset index-mycmd-lib \
    generate-shell-function-index \
    MYCMD_LIB_FILES

mycmd.defer_at_startup mycmd.init_bin grep
function catalog-mycmd-lib-function-call-tree() {
    local -n fileset="${1}"
    local -a functions

    readarray -t functions < <(project.execute_tasks list-mycmd-lib-functions || true)

    local fn
    local fn_pattern
    local match_line
    local file
    local line_number
    local -a data=()

    project.output_only_if_not_quiet "Cataloging function from mycmd-lib across all implementation files."

    for fn in "${functions[@]}"; do
        project.verbose "Searching for function '${fn}'."
        fn_pattern="${fn/./\\.}"

        while read -r match_line; do
            file="$(echo "${match_line}" | cut -d: -f1)"
            line_number="$(echo "${match_line}" | cut -d: -f2)"
            data+=("${fn},${file},${line_number}")
        done < <(mycmd.bin_execute grep -P -n "(?<!function )[[:<:]]${fn_pattern}[[:>:]]" "${fileset[@]}" \
            | mycmd.bin_execute grep -P -v "^[^:]+:[[:digit:]]+:.*#.*[[:<:]]${fn_pattern}[[:>:]].*" || true)
    done

    local -r output_file="${TMP_WORKING_DIR}/fn-callers.csv"

    echo "function,file,line" >"${output_file}"

    (
        local line
        for line in "${data[@]}"; do
            echo "${line}"
        done
    ) | sort -t, -k1,2 >>"${output_file}"

    project.output_only_if_not_quiet "Wrote results to ${output_file}."
}
project.register_task_with_fileset catalog-mycmd-lib-function-call-tree \
    catalog-mycmd-lib-function-call-tree \
    MYCMD_LIB_FILES

mycmd.defer_at_startup mycmd.init_bin grep
function catalog-mycmd-lib-function-callers() {
    local -n implementation_fileset="${1}"
    local -a functions

    readarray -t functions < <(project.execute_tasks list-mycmd-lib-functions || true)

    local fn
    local fn_pattern
    local count
    local -a data=()

    project.output_only_if_not_quiet "Cataloging function from mycmd-lib across all implementation files."

    for fn in "${functions[@]}"; do
        local impl_file
        for impl_file in "${implementation_fileset[@]}"; do
            project.verbose "Searching for function '${fn}' in file '${impl_file}'."

            fn_pattern="${fn/./\\.}"
            count="$(mycmd.bin_execute grep -P "(?<!function )[[:<:]]${fn_pattern}[[:>:]]" "${impl_file}" \
                | mycmd.bin_execute grep -P -c -v ".*#.*[[:<:]]${fn_pattern}[[:>:]].*" || true)"
            data+=("${fn},${impl_file},${count}")
        done
    done

    local -r output_file="${TMP_WORKING_DIR}/fn-call-counts.csv"

    echo "function,file,count" >"${output_file}"

    (
        local line
        for line in "${data[@]}"; do
            echo "${line}"
        done
    ) | sort -t, -k3 -nr >>"${output_file}"

    project.output_only_if_not_quiet "Wrote results to ${output_file}."
}
project.register_task_with_fileset catalog-mycmd-lib-function-callers \
    catalog-mycmd-lib-function-callers \
    IMPLEMENTATION_FILES

function count_source_lines() {
    local -n fileset="${1}"

    project.output_only_if_not_quiet "Counting source lines in fileset '${!fileset}'."
    wc -l "${fileset[@]}" | sort -nr
}
project.register_task_with_fileset count-all-source-lines \
    count_source_lines \
    ALL_FILES
project.register_task_with_fileset count-implementation-source-lines \
    count_source_lines \
    IMPLEMENTATION_FILES
project.register_task_with_fileset count-test-source-lines \
    count_source_lines \
    TEST_FILES
project.register_task_with_fileset count-mycmd-lib-source-lines \
    count_source_lines \
    MYCMD_LIB_FILES

#----------------------------------------
# Test execution
# shellcheck disable=SC2034
function summarize_test_results() {
    local -n results_ref="${1}"

    local -A result_table=()
    local test_file
    local result

    for test_file in "${!results_ref[@]}"; do
        result="${results_ref["${test_file}"]}"

        if ((result == 0)); then
            # Green Check: https://www.compart.com/en/unicode/U+2705
            result_table["${test_file}"]="\u2705"
        else
            # Red X: https://www.compart.com/en/unicode/U+274C
            result_table["${test_file}"]="\u274c"
        fi
    done

    mycmd.print_table result_table \
        "Testing Summary:" \
        "Test File" "Result"
}

function get-test-log-file() {
    local description
    description="$(date '+%Y-%m-%d-%H%M%S')"
    readonly description

    local -r test_log_file="${TMP_WORKING_DIR}/test-output-${description}.log"

    echo "${test_log_file}"
}

function execute-test() {
    local -r test_log_file="${1}"
    shift
    local -r test_file="${1}"
    shift

    if [[ ! -e "${test_file}" ]]; then
        mycmd.log "Test file not found: ${test_file}"
        return 1
    fi

    local result=0
    mycmd.log "Executing test file: ${test_file}"
    echo "Executing test file: ${test_file}" >>"${test_log_file}"

    /usr/bin/env -u MYCMD_SEARCH_PATH \
        MYCMD_TRACE=1 \
        MYCMD_DEBUG=1 \
        MYCMD_LOG_FILE="${test_log_file}" \
        MYCMD_SYSTEM_BASE_DIR="${SYSTEM_BASE}" \
        MYCMD_USER_BASE_DIR="${TEST_USER_BASE}" \
        MYCMD_VENDOR_DIR="${VENDOR_DIR}" \
        PATH="${BIN_DIR}:${PATH}" \
        "${test_file}" "${@}" || result=$?

    mycmd.log "Result of ${test_file}: ${result}"
    echo "Result of ${test_file}: ${result}" >>"${test_log_file}"
    return "${result}"
}

function execute-single-file-tests() {
    local -r test_file="${1}"
    shift

    local test_log_file
    test_log_file="$(get-test-log-file)"
    readonly test_log_file

    if (($# > 0)); then
        # https://github.com/kward/shunit2?tab=readme-ov-file#-running-specific-tests-from-the-command-line
        # Prefix the arguments with --
        set -- "${test_log_file}" "${test_file}" -- "${@}"
    else
        set -- "${test_log_file}" "${test_file}"
    fi

    execute-test "${@}"
}
project.register_task execute-single-file-tests

function execute-all-tests() {
    local -n test_fileset="${1}"
    local test_file
    local -A results=()
    local result

    local test_log_file
    test_log_file="$(get-test-log-file)"
    readonly test_log_file

    local final_result=0

    for test_file in "${test_fileset[@]}"; do
        result=0

        execute-test "${test_log_file}" "${test_file}" || result=$?
        # shellcheck disable=SC2034
        results["${test_file}"]="${result}"

        if ((result != 0)); then
            final_result="${result}"
        fi
    done

    summarize_test_results results
    return "${final_result}"
}
project.register_task_with_fileset execute-all-tests \
    execute-all-tests \
    TEST_FILES

function get-last-test-log() {
    local -a test_log_files=("${TMP_WORKING_DIR}"/test-output-*.log)

    if ((${#test_log_files[@]} == 0)); then
        return 1
    fi

    local -a sorted_logs
    readarray -t sorted_logs < <(printf '%s\n' "${test_log_files[@]}" | sort -r || true)
    local -r last_test_log="${sorted_logs[0]}"
    echo "${last_test_log}"
}

function page-last-test-log() {
    local last_test_log
    if ! last_test_log="$(mycmd.nullglob_set_wrapper get-last-test-log)"; then
        mycmd.output "No test log files found."
        return 1
    fi
    readonly last_test_log

    less "${last_test_log}"
}
project.register_task page-last-test-log

function remove-test-logs() {
    rm -f "${TMP_WORKING_DIR}"/test-output-*.log 2>/dev/null || true
}
project.register_task remove-test-logs

#----------------------------------------
# Benchmarking
function execute-benchmark() {
    if ! mycmd.init_bin_no_exit hyperfine; then
        mycmd.log "Required tool 'hyperfine' not found."
        return 1
    fi

    local -r output_csv="${1}"
    local -r benchmark_command="${2}"

    local description
    if (($# > 2)); then
        description="${3}"
    else
        description="$(date '+%Y-%m-%d-%H%M%S')"
        project.verbose "Description not provided, using timestamp: '${description}'."
    fi
    readonly description

    local run_output_csv
    if ! run_output_csv="$(mktemp -q -t "benchmark-${description}-XXXXXX.csv")"; then
        mycmd.log "Error creating temporary file for benchmark output."
        return 1
    fi
    readonly run_output_csv

    /usr/bin/env MYCMD_SYSTEM_BASE_DIR="${SYSTEM_BASE}" \
        MYCMD_USER_BASE_DIR="${TEST_USER_BASE}" \
        MYCMD_VENDOR_DIR="${VENDOR_DIR}" \
        PATH="${BIN_DIR}:${PATH}" \
        hyperfine \
        --warmup 5 \
        --export-csv "${run_output_csv}" \
        -- "${benchmark_command}"

    if [[ ! -e "${output_csv}" ]]; then
        echo -n "description," >"${output_csv}"
        head -n 1 "${run_output_csv}" >>"${output_csv}"
    fi

    echo -n "${description}," >>"${output_csv}"
    tail -n 1 "${run_output_csv}" >>"${output_csv}"

    rm -f "${run_output_csv}"
}
project.register_task benchmark-help \
    execute-benchmark \
    "${TMP_WORKING_DIR}/project-help-benchmark.csv" \
    'mycmd project --help'
project.register_task benchmark-list-project-tasks \
    execute-benchmark \
    "${TMP_WORKING_DIR}/project-list-tasks-benchmark.csv" \
    'mycmd project list-tasks'
project.register_task benchmark-mycmd \
    execute-benchmark \
    "${TMP_WORKING_DIR}/mycmd-benchmark.csv" \
    "${BIN_DIR}/mycmd"

#----------------------------------------
# Code formatting
project.register_task_with_fileset format \
    project:shell.format \
    ALL_FILES

#----------------------------------------
# Code Lint
project.register_task_with_fileset lint \
    project:shell.lint \
    ALL_FILES

#----------------------------------------
# Processing Trace Logs

function remove-temporary-file() {
    local -r f="${1}"

    if [[ -e "${f}" ]]; then
        rm -f "${f}" || true
    fi
}

readonly GENERATE_PERF_FILE="${SUPPORT_DIR}/analysis/generate-perf-file.py"
function create-flamegraph-from-shell-trace() {
    if ! mycmd.init_bin_no_exit flamegraph.pl; then
        mycmd.log "Required tool 'flamegraph.pl' not found."
        return 1
    fi

    local -r shell_trace_log="${1}"
    local -r flamegraph_svg_file="${2}"

    local shell_perf_file
    if ! shell_perf_file="$(mktemp -q -t "shell-trace-XXXXXX.perf")"; then
        mycmd.log "Error creating temporary file for shell trace perf."
        return 1
    fi
    readonly shell_perf_file
    mycmd.defer_at_exit remove-temporary-file "${shell_perf_file}"

    if ! python "${GENERATE_PERF_FILE}" "${shell_trace_log}" "${shell_perf_file}"; then
        mycmd.log "Error converting trace log to a perf file."
        return 1
    fi

    if ! mycmd.bin_execute flamegraph.pl "${shell_perf_file}" >"${flamegraph_svg_file}"; then
        mycmd.log "Error generating flamegraph file"
        return 1
    fi
}
project.register_task create-flamegraph-from-shell-trace

readonly QUERY_CALL_HIERARCHY="${SUPPORT_DIR}/analysis/query-call-hierarchy.py"
function query-call-hierarchy() {
    local -r shell_trace_log="${1}"
    local -r target_function="${2}"

    python "${QUERY_CALL_HIERARCHY}" "${shell_trace_log}" "${target_function}"
}
project.register_task query-call-hierarchy

# Calling in Development Version
function mycmd-devel() {
    local -r trace_log_file="${TMP_WORKING_DIR}/shell-log-trace"

    if [[ -e "${trace_log_file}" ]]; then
        rm -rf "${trace_log_file}" || true
    fi

    /usr/bin/env MYCMD_SYSTEM_BASE_DIR="${SYSTEM_BASE}" \
        MYCMD_USER_BASE_DIR="${TEST_USER_BASE}" \
        PATH="${BIN_DIR}:${PATH}" \
        _MYCMD_EARLY_SHELL_TRACE=1 \
        _MYCMD_EARLY_TRACE_LOG_FILE="${trace_log_file}" \
        "${BIN_DIR}"/mycmd "${@}"
}
project.register_task mycmd-devel

function test-command-directly() {
    /usr/bin/env -u MYCMD_SEARCH_PATH \
        MYCMD_SYSTEM_BASE_DIR="${SYSTEM_BASE}" \
        MYCMD_USER_BASE_DIR="${TEST_USER_BASE}" \
        MYCMD_VENDOR_DIR="${VENDOR_DIR}" \
        PATH="${BIN_DIR}:${PATH}" \
        "${TEST_USER_BASE}/test-command" \
        "${@}"
}
project.register_task test-command-directly

#----------------------------------------
# Snapshot Management
function _get_tag_name_from_parts() {
    local -r tag_prefix="${1}"
    local -r sequence_number="${2}"

    local date_string
    if ! date_string="$(date '+%Y-%m-%d')"; then
        mycmd.log "Unexpected error getting the date string"
        return 1
    fi
    readonly date_string

    echo "${tag_prefix}-r${sequence_number}-${date_string}"
}

function _get_next_tag_name_from_previous() {
    local -r current_tag="${1}"
    local -r tag_prefix="${2}"

    local current_sequence="${current_tag##"${tag_prefix}"-r}"
    current_sequence="${current_sequence%%-*}"
    readonly current_sequence

    local -ir next_sequence=$((current_sequence + 1))
    _get_tag_name_from_parts "${tag_prefix}" "${next_sequence}"
}

# Local Snapshots
# - used for testing changes locally
# - tags are not pushed to github
# - tag names are of the form 'local-snapshot-r0-2024-01-27'
readonly LOCAL_SNAPSHOT_TAG_PREFIX="local-snapshot"

function get_next_local_snapshot_tag_name_from_previous() {
    _get_next_tag_name_from_previous "${1}" "${LOCAL_SNAPSHOT_TAG_PREFIX}"
}

function get_local_snapshot_tags() {
    local -r tags_array_ref_name="${1}"
    project:git.list_tags "${tags_array_ref_name}" "${LOCAL_SNAPSHOT_TAG_PREFIX}-*"
}

function list-local-snapshots() {
    local -a tags=()
    get_local_snapshot_tags tags

    if (("${#tags[@]}" == 0)); then
        mycmd.output "There are no local snapshots defined."
    fi

    local tag
    for tag in "${tags[@]}"; do
        mycmd.output "${tag}"
    done
}
project.register_task list-local-snapshots

function get_latest_local_snapshot_tag() {
    local -a existing_tags=()
    get_local_snapshot_tags existing_tags

    if (("${#existing_tags[@]}" == 0)); then
        return 1
    fi

    echo "${existing_tags[0]}"
}

function get_new_local_snapshot_tag_name() {
    local latest_local_snapshot_tag
    if ! latest_local_snapshot_tag="$(get_latest_local_snapshot_tag)"; then
        mycmd.trace "No local snapshot tags created"

        _get_tag_name_from_parts "${LOCAL_SNAPSHOT_TAG_PREFIX}" 0
        return 0
    fi
    readonly latest_local_snapshot_tag

    _get_next_tag_name_from_previous "${latest_local_snapshot_tag}" "${LOCAL_SNAPSHOT_TAG_PREFIX}"
}

function create_local_snapshot() {
    local commit
    if (($# == 0)); then
        commit="HEAD"
    else
        commit="${1}"
    fi
    readonly commit

    if project:git.commit_is_tagged_matching_pattern "${commit}" "${LOCAL_SNAPSHOT_TAG_PREFIX}-r.*"; then
        mycmd.log "Commit '${commit}' already has a snapshot defined."
        return 1
    fi

    local new_snapshot_tag_name
    if ! new_snapshot_tag_name="$(get_new_local_snapshot_tag_name)"; then
        mycmd.log "Error getting new snapshot tag name."
        return 1
    fi
    readonly new_snapshot_tag_name

    if ! project:git.create_lightweight_tag "${new_snapshot_tag_name}" "${commit}"; then
        mycmd.log "Error creating tag '${new_snapshot_tag_name}' at '${commit}'."
        return 1
    fi

    project.output_only_if_not_quiet "Created new local snapshot '${new_snapshot_tag_name}'."

    return 0
}
project.register_task create-local-snapshot \
    create_local_snapshot

# Development Snapshots
# - used for wider in-development testing
# - tags are pushed to github
# - tag names are of the form 'snapshot-r0-2024-01-27'
# - sequence numbers (r0 in this example) are independent of the local snapshot numbers
readonly DEVELOPMENT_SNAPSHOT_TAG_PREFIX='snapshot'

function get_next_development_snapshot_tag_name_from_previous() {
    _get_next_tag_name_from_previous "${1}" "${DEVELOPMENT_SNAPSHOT_TAG_PREFIX}"
}

function get_development_snapshot_tags() {
    local -r tags_array_ref_name="${1}"
    project:git.list_tags "${tags_array_ref_name}" "${DEVELOPMENT_SNAPSHOT_TAG_PREFIX}-*"
}

function list-development-snapshots() {
    local -a tags=()
    get_development_snapshot_tags tags

    if (("${#tags[@]}" == 0)); then
        mycmd.output "There are no development snapshots defined."
    fi

    local tag
    for tag in "${tags[@]}"; do
        mycmd.output "${tag}"
    done
}
project.register_task list-development-snapshots

function get_latest_development_snapshot_tag() {
    local -a existing_tags=()
    get_development_snapshot_tags existing_tags

    if (("${#existing_tags[@]}" == 0)); then
        return 1
    fi

    echo "${existing_tags[0]}"
}

function get_new_development_snapshot_tag_name() {
    local latest_development_snapshot_tag
    if ! latest_development_snapshot_tag="$(get_latest_development_snapshot_tag)"; then
        mycmd.trace "No development snapshot tags created"

        _get_tag_name_from_parts "${DEVELOPMENT_SNAPSHOT_TAG_PREFIX}" 0
        return 0
    fi
    readonly latest_development_snapshot_tag

    mycmd.output "Latest development tag: ${latest_development_snapshot_tag}"

    _get_next_tag_name_from_previous "${latest_development_snapshot_tag}" "${DEVELOPMENT_SNAPSHOT_TAG_PREFIX}"
}

function get_previous_snapshot_tag() {
    local current_tag="${1}"

    local -a all_tags=()
    if [[ "${current_tag}" = "${LOCAL_SNAPSHOT_TAG_PREFIX}"-* ]]; then
        get_local_snapshot_tags all_tags
    elif [[ "${current_tag}" = "${DEVELOPMENT_SNAPSHOT_TAG_PREFIX}"-* ]]; then
        get_development_snapshot_tags all_tags
    else
        mycmd.log "Unexpected tag format of current tag: '${current_tag}'."
    fi

    local -i index
    local -i tag_count="${#all_tags[@]}"
    local -i previous_tag_index

    for ((index = 0; index < tag_count; index++)); do
        if [[ "${current_tag}" = "${all_tags[${index}]}" ]]; then
            previous_tag_index=$((index + 1))

            if ((previous_tag_index == tag_count)); then
                mycmd.log "Current tag '${current_tag}' is the oldest tag"
                return 1
            fi

            echo "${all_tags[${previous_tag_index}]}"
            return 0
        fi
    done

    mycmd.log "Tag '${current_tag}' not found."
    return 1
}

function promote_local_snapshot_to_development() {
    if (($# == 0)); then
        mycmd.log "Missing snapshot to promote."
        return 1
    fi

    if ! mycmd.init_bin_no_exit gum; then
        mycmd.log "Required tool 'gum' not found."
        return 1
    fi

    local -r local_snapshot_tag="${1}"

    local new_development_snapshot_tag
    if ! new_development_snapshot_tag="$(get_new_development_snapshot_tag_name)"; then
        mycmd.log "Unexpected error getting new development snapshot tag name."
        return 1
    fi
    readonly new_development_snapshot_tag

    local -a tag_messages=()
    local summary_line
    if ! summary_line="$(mycmd.bin_execute gum input --placeholder "Summary of Snapshot")"; then
        mycmd.log "Error getting summary line."
        return 1
    fi
    tag_messages+=("${summary_line}")
    tag_messages+=("Created from local snapshot tag '${local_snapshot_tag}'.")

    if ! project:git.create_annotated_tag "${local_snapshot_tag}" "${new_development_snapshot_tag}" tag_messages; then
        mycmd.log "Error creating annotated tag"
        return 1
    fi

    if ! project:git.push_changes_with_annotated_tags; then
        mycmd.log "Error pushing changes"
        return 1
    fi

    project.output_only_if_not_quiet "Created and pushed new development snapshot '${new_development_snapshot_tag}'."
}
project.register_task promote-local-snapshot-to-development \
    promote_local_snapshot_to_development

function promote_latest_local_snapshot_tag_to_development() {
    local latest_local_snapshot
    if ! latest_local_snapshot="$(get_latest_local_snapshot_tag)"; then
        mycmd.log "No local snapshot tags defined yet."
        return 1
    fi
    readonly latest_local_snapshot

    promote_local_snapshot_to_development "${latest_local_snapshot}"
}
project.register_task promote-latest-local-snapshot-to-development \
    promote_latest_local_snapshot_tag_to_development

# ----------------------------------------
# Worktree management
readonly SNAPSHOT_WORKTREE="${WORKTREES_PARENT_DIR}/snapshot"
readonly SNAPSHOT_WORKTREE_LAST_USED_TAG_FILE="${WORKTREES_PARENT_DIR}/.last-used-snapshot-tag"
readonly SNAPSHOT_WORKTREE_CURRENT_TAG_FILE="${WORKTREES_PARENT_DIR}/.current-snapshot-tag"

function get_snapshot_worktree_current_tag() {
    if [[ -e "${SNAPSHOT_WORKTREE_CURRENT_TAG_FILE}" ]]; then
        cat "${SNAPSHOT_WORKTREE_CURRENT_TAG_FILE}"
        return 0
    else
        return 1
    fi
}

function update_snapshot_worktree_current_tag_file() {
    local -r tag="${1}"

    echo "${tag}" >"${SNAPSHOT_WORKTREE_CURRENT_TAG_FILE}"
}

function get_snapshot_worktree_last_used_tag() {
    if [[ -e "${SNAPSHOT_WORKTREE_LAST_USED_TAG_FILE}" ]]; then
        cat "${SNAPSHOT_WORKTREE_LAST_USED_TAG_FILE}"
        return 0
    else
        return 1
    fi
}

function update_snapshot_worktree_last_used_tag_file() {
    local -r tag="${1}"

    echo "${tag}" >"${SNAPSHOT_WORKTREE_LAST_USED_TAG_FILE}"
}

function update_snapshot_worktree_to_snapshot() {
    local -r tag="${1}"
    local do_force
    if (($# > 1)); then
        do_force="${2}"
    fi
    readonly do_force

    if [[ -d "${SNAPSHOT_WORKTREE}" ]]; then
        local current_worktree_tag
        if ! current_worktree_tag="$(get_snapshot_worktree_current_tag)"; then
            mycmd.log "Unexpected error reading current snapshot worktree current tag file."
            return 1
        fi
        readonly current_worktree_tag

        if [[ "${current_worktree_tag}" = "${tag}" ]]; then
            if [[ "${do_force}" = "true" ]]; then
                mycmd.trace "Snapshot worktree is already at '${tag}'."
            else
                mycmd.output "Snapshot worktree is already at '${tag}'."
                return 0
            fi
        fi

        update_snapshot_worktree_last_used_tag_file "${current_worktree_tag}"
        project:git.update_worktree_to_commitish "${SNAPSHOT_WORKTREE}" "${tag}"
        update_snapshot_worktree_current_tag_file "${tag}"
    else
        project:git.add_worktree_at_detached_commit "${SNAPSHOT_WORKTREE}" "${tag}"
        update_snapshot_worktree_current_tag_file "${tag}"
    fi
}
project.register_task update-snapshot-worktree-to-snapshot \
    update_snapshot_worktree_to_snapshot

function rollback_snapshot_worktree_to_last_used_snapshot() {
    local last_used_tag
    if ! last_used_tag="$(get_snapshot_worktree_last_used_tag)"; then
        mycmd.log "No last used tag file found at '${SNAPSHOT_WORKTREE_LAST_USED_TAG_FILE}'."
        return 1
    fi
    readonly last_used_tag

    update_snapshot_worktree_to_snapshot "${last_used_tag}"
}
project.register_task rollback-snapshot-worktree-to-last-used-snapshot \
    rollback_snapshot_worktree_to_last_used_snapshot

function rollback_snapshot_worktree_to_previous_snapshot_in_sequence() {
    local current_worktree_tag
    if ! current_worktree_tag="$(get_snapshot_worktree_current_tag)"; then
        mycmd.log "Error reading current snapshot worktree current tag file."
        return 1
    fi
    readonly current_worktree_tag

    local prior_snapshot_tag
    if ! prior_snapshot_tag="$(get_previous_snapshot_tag "${current_worktree_tag}")"; then
        return 1
    fi
    readonly prior_snapshot_tag

    update_snapshot_worktree_to_snapshot "${prior_snapshot_tag}"
}
project.register_task rollback-snapshot-worktree-to-previous-snapshot-in-sequence \
    rollback_snapshot_worktree_to_previous_snapshot_in_sequence

function update_snapshot_worktree_to_latest_local_snapshot() {
    local latest_local_snapshot
    if ! latest_local_snapshot="$(get_latest_local_snapshot_tag)"; then
        mycmd.log "No local snapshot tags defined yet."
        return 1
    fi
    readonly latest_local_snapshot

    update_snapshot_worktree_to_snapshot "${latest_local_snapshot}" "${@}"
}
project.register_task update-snapshot-worktree-to-latest-local-snapshot \
    update_snapshot_worktree_to_latest_local_snapshot

function update_snapshot_worktree_to_latest_development_snapshot() {
    project:git.fetch_tags

    local latest_development_snapshot
    if ! latest_development_snapshot="$(get_latest_development_snapshot_tag)"; then
        mycmd.log "No development snapshot tags defined yet."
        return 1
    fi
    readonly latest_development_snapshot

    update_snapshot_worktree_to_snapshot "${latest_development_snapshot}" "${@}"
}
project.register_task update-snapshot-worktree-to-latest-development-snapshot \
    update_snapshot_worktree_to_latest_development_snapshot

#----------------------------------------
# Repo Stats
function git-quick-stats() {
    if ! mycmd.init_bin_no_exit git-quick-stats; then
        mycmd.log "Required tool 'git-quick-stats' not found."
        return 1
    fi

    # shellcheck disable=SC2154
    /usr/bin/env PATH="${HOMEBREW_PREFIX}/opt/coreutils/libexec/gnubin:${PATH}" \
        git quick-stats "${@}"
}
project.register_task git-quick-stats

#----------------------------------------
# Run everything
mycmd.defer_at_startup mycmd.init_bin find
function clean-up() {
    mycmd.bin_execute find "${MYPROJECT_BASE_DIR}" -type f -name '.DS_Store' -delete
}
project.register_task clean-up

function all() {
    project.execute_tasks clean-up format lint execute-all-tests
}
project.register_task all
project.register_default_task all