tasks.py

import os
import re
import shutil
import sys
import tempfile
from enum import Enum
from pathlib import Path
from typing import Dict, Optional

import invoke
from invoke import task

from developer.git.commit_validator import (
    validate_commits_locally_or_ci,
)
from strictdoc.core.environment import (
    BINARY_HTML_STATIC_DIR,
    BINARY_HTML_TEMPLATES_DIR,
    HTML_STATIC_DIRS,
    HTML_TEMPLATE_DIRS,
)
from strictdoc.core.project_config import ProjectConfigDefault
from tools.server_check import free_strictdoc_port

# Specifying encoding because Windows crashes otherwise when running Invoke
# tasks below:
# UnicodeEncodeError: 'charmap' codec can't encode character '\ufffd'
# in position 16: character maps to <undefined>
# People say, it might also be possible to export PYTHONIOENCODING=utf8 but this
# seems to work.
# FIXME: If you are a Windows user and expert, please advise on how to do this
# properly.
sys.stdout = open(1, "w", encoding="utf-8", closefd=False, buffering=1)

STRICTDOC_TMP_DIR = os.path.join(tempfile.gettempdir(), "strictdoc_tmp_dir")
TEST_REPORTS_DIR = "build/test_reports"

# Redirect all __pycache__ output (from Invoke itself and every subprocess it
# spawns: pytest, mypy, plain python invocations, etc.) into a single folder,
# instead of littering __pycache__ directories across the source tree.
os.environ["PYTHONPYCACHEPREFIX"] = os.path.abspath("build/pycache")


def get_pyinstaller_html_template_data_options() -> str:
    return "\n".join(
        f'--add-data "{template_dir}{os.pathsep}{BINARY_HTML_TEMPLATES_DIR}"'
        for template_dir in HTML_TEMPLATE_DIRS
    )


def get_pyinstaller_html_static_data_options() -> str:
    return "\n".join(
        f'--add-data "{static_dir}{os.pathsep}{BINARY_HTML_STATIC_DIR}"'
        for static_dir in HTML_STATIC_DIRS
    )


def get_nuitka_html_template_data_options() -> str:
    return "\n".join(
        f'--include-data-dir="{template_dir}={BINARY_HTML_TEMPLATES_DIR}"'
        for template_dir in HTML_TEMPLATE_DIRS
    )


def get_nuitka_html_static_data_options() -> str:
    return "\n".join(
        f'--include-data-dir="{static_dir}={BINARY_HTML_STATIC_DIR}"'
        for static_dir in HTML_STATIC_DIRS
    )


# To prevent all tasks from building to the same virtual environment.
# Each value is a uv dependency group name declared in pyproject.toml's
# [dependency-groups].
class UvEnvironment(str, Enum):
    DEVELOPMENT = "development"
    CHECK = "check"
    DOCUMENTATION = "documentation"
    RELEASE = "release"
    RELEASE_LOCAL = "release-local"
    PYINSTALLER = "pyinstaller"


def run_invoke(
    context,
    cmd,
    environment: Optional[dict] = None,
    pty: bool = False,
    warn: bool = False,
) -> invoke.runners.Result:
    def one_line_command(string):
        return re.sub("\\s+", " ", string).strip()

    return context.run(
        one_line_command(cmd),
        env=environment,
        hide=False,
        warn=warn,
        pty=pty,
        echo=True,
    )


def uv_venv_dir(environment_type: UvEnvironment) -> str:
    # Each flavor gets its own venv so, e.g., pyinstaller/twine deps never
    # mix with playwright/pytest deps.
    return os.path.abspath(f"build/uv/{environment_type.value}")


def uv_venv_bin_dir(environment_type: UvEnvironment) -> str:
    return os.path.join(
        uv_venv_dir(environment_type), "Scripts" if os.name == "nt" else "bin"
    )


def uv_venv_python(environment_type: UvEnvironment) -> str:
    # An absolute path, unlike a bare "python"/"python3" on PATH: a uv/venv
    # on Windows only ships python.exe (no python3.exe), and PATH-based
    # lookup for a nested subprocess (e.g. tests/integration/expect_exit.py
    # spawning STRICTDOC_EXEC itself) has been observed to resolve to the
    # system Python instead of the venv's, even though the venv's bin/
    # directory is first on PATH for directly-spawned commands.
    #
    # Forward slashes even on Windows: this value gets embedded in a lit
    # RUN: line, which on Windows CI runs through Git Bash. A backslash
    # path there is parsed as shell escapes (\a, \s, ... silently dropped),
    # mangling the path; Windows itself accepts forward slashes fine.
    python_name = "python.exe" if os.name == "nt" else "python"
    path = os.path.join(uv_venv_bin_dir(environment_type), python_name)
    return path.replace(os.sep, "/")


def run_invoke_with_uv(
    context,
    environment_type: UvEnvironment,
    command: str,
    environment: Optional[Dict] = None,
    pty: bool = False,
) -> invoke.runners.Result:
    assert isinstance(environment_type, UvEnvironment)
    assert isinstance(command, str)

    venv_dir = uv_venv_dir(environment_type)

    # VIRTUAL_ENV: keeps it in sync with UV_PROJECT_ENVIRONMENT so uv does
    # not warn about the two disagreeing whenever this runs from inside an
    # already-activated venv (e.g. a developer's own .venv, or Nix's
    # devShell).
    # --inexact: tasks like release_local pip-install the just-built
    # strictdoc artifact into this same venv outside of uv's tracking; a
    # plain `uv sync` would remove it again on the next call.
    run_invoke(
        context,
        f"""
            uv sync --frozen --inexact --no-install-project
                --group {environment_type.value}
        """,
        environment={
            "UV_PROJECT_ENVIRONMENT": venv_dir,
            "VIRTUAL_ENV": venv_dir,
            **(environment or {}),
        },
    )

    return run_invoke(
        context,
        command,
        environment={
            "PATH": f"{uv_venv_bin_dir(environment_type)}{os.pathsep}{os.environ['PATH']}",
            "VIRTUAL_ENV": venv_dir,
            **(environment or {}),
        },
        pty=pty,
    )


@task(default=True)
def list_tasks(context):
    clean_command = """
        invoke --list
    """
    run_invoke(context, clean_command)


@task
def clean(context):
    # https://unix.stackexchange.com/a/689930/77389
    clean_command = r"""
        rm -rf output/ &&
        find tests/ -type d \( -name output -o -name Output \) -exec rm -rf {} +
    """
    run_invoke(context, clean_command)


@task(aliases=["s"])
def server(context, input_path=".", config=None, port=None):
    assert os.path.isdir(input_path), input_path
    if config is not None:
        assert os.path.isfile(config), config
    config_argument = f"--config {config}" if config is not None else ""
    port_argument = f"--port {port}" if port is not None else ""

    try:
        should_continue = free_strictdoc_port(
            port
            if port is not None
            else ProjectConfigDefault.DEFAULT_SERVER_PORT
        )
    except OSError as error:
        print(error, file=sys.stderr)  # noqa: T201
        return

    if not should_continue:
        return

    run_invoke_with_uv(
        context,
        UvEnvironment.DEVELOPMENT,
        f"""
            python -m strictdoc.cli.main
                --debug
                --development
                server {input_path} {config_argument}
                    --host 127.0.0.1
                    {port_argument}
                    --reload
                    --watch
        """,
        pty=True,
    )


@task(aliases=["scs"])
def screencast_server(context, focus=None, edit=False):
    """
    Manual dev server for tests/screencast scenarios: starts StrictDoc on a
    scenario's project (the shared demo fixture by default, or another
    scenario's project via --focus), for inspecting it in the browser.

    By default this serves a disposable copy, rebuilt fresh every time, so
    nothing done through the UI persists. Pass --edit to serve the real,
    persistent files instead (the shared fixture itself, or a generated
    project reused across restarts) when intentionally editing them.
    """

    focus_argument = f"--focus {focus}" if focus is not None else ""
    edit_argument = "--edit" if edit else ""

    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        f"python tests/screencast/run_server.py {focus_argument} {edit_argument}",
    )


@task(aliases=["d"])
def docs(context):
    run_invoke_with_uv(
        context,
        UvEnvironment.DOCUMENTATION,
        """
            python -m strictdoc.cli.main
                export .
                    --formats=html,html2pdf
                    --output-dir output/strictdoc_website
                    --project-title "StrictDoc"
        """,
    )


@task(clean, aliases=["tus"])
def test_unit_server(context, focus=None):
    focus_argument = f"-k {focus}" if focus is not None else ""

    Path(TEST_REPORTS_DIR).mkdir(parents=True, exist_ok=True)

    cwd = os.getcwd()

    path_to_coverage_file = f"{cwd}/build/coverage/unit_server/.coverage"

    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        f"""
            coverage run
            --rcfile=.coveragerc.unit_server
            --data-file={path_to_coverage_file}
            -m pytest
            tests/unit_server/
                {focus_argument}
                --junit-xml={TEST_REPORTS_DIR}/tests_unit_server.pytest.junit.xml
                -o junit_suite_name="StrictDoc Web Server Unit Tests"
                -o cache_dir=build/pytest_cache/unit_server
        """,
    )


@task(test_unit_server, aliases=["tusc"])
def test_unit_server_report(context):
    cwd = os.getcwd()

    path_to_coverage_file = f"{cwd}/build/coverage/unit_server/.coverage"

    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        f"""
            coverage html
                --rcfile=.coveragerc.unit_server
                --data-file={path_to_coverage_file}
        """,
    )


@task(aliases=["te"])
def test_end2end(
    context,
    *,
    focus=None,
    exit_first=False,
    parallelize=False,
    long_timeouts=False,
    headless=False,
    headed=False,
    shard=None,
    test_path=None,
    coverage: bool = False,
):
    """
    @relation(SDOC-SRS-46, scope=function)
    """

    environment = {}

    coverage_command_or_none = ""
    coverage_argument_or_none = ""

    if coverage:
        cwd = os.getcwd()
        coverage_file_dir = f"{cwd}/build/coverage/end2end/"
        coverage_file_dir2 = f"{cwd}/build/coverage/end2end_strictdoc/"
        coverage_file = os.path.join(coverage_file_dir, ".coverage")
        coverage_rc = os.path.join(cwd, ".coveragerc.end2end")
        shutil.rmtree(coverage_file_dir, ignore_errors=True)
        shutil.rmtree(coverage_file_dir2, ignore_errors=True)
        coverage_command_or_none = f"""
            coverage run
                --rcfile={coverage_rc}
                --data-file={coverage_file}
                -m
        """
        coverage_argument_or_none = "--strictdoc-coverage"

    long_timeouts_argument = (
        "--strictdoc-long-timeouts" if long_timeouts else ""
    )

    parallelize_argument = ""
    if parallelize:
        print(  # noqa: T201
            "warning: "
            "Running parallelized end-2-end tests is supported "
            "but is not stable."
        )
        parallelize_argument = "--numprocesses=2 --strictdoc-parallelize"

    assert shard is None or re.match(r"[1-9][0-9]*/[1-9][0-9]*", shard), (
        f"--shard argument has an incorrect format: {shard}."
    )
    shard_argument = f"--strictdoc-shard={shard}" if shard else ""

    focus_argument = f"-k {focus}" if focus is not None else ""
    exit_first_argument = "--exitfirst" if exit_first else ""
    headless_argument = "--headless2" if headless and not headed else "--gui"
    test_command = f"""
            {coverage_command_or_none}
            pytest
            --failed-first
            --capture=no
            --reuse-session
            {parallelize_argument}
            {shard_argument}
            {coverage_argument_or_none}
            {focus_argument}
            {exit_first_argument}
            {long_timeouts_argument}
            {headless_argument}
            --junit-xml={TEST_REPORTS_DIR}/tests_end2end.pytest.junit.xml
            -o junit_suite_name="StrictDoc End-to-End Tests"
            -o cache_dir=build/pytest_cache/end2end
            tests/end2end
    """
    if test_path:
        test_command = test_command.rstrip() + f"/{test_path}"

    Path(TEST_REPORTS_DIR).mkdir(parents=True, exist_ok=True)

    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        test_command,
        environment=environment,
    )


@task(aliases=["tsc"])
def test_screencast(context, *, focus=None, record_video=False):
    """
    Runs the tests/screencast scenarios: fast pass/fail checks by default,
    or (re)recording of the corresponding .webm videos with --record-video.
    """

    focus_argument = f"-k {focus}" if focus is not None else ""
    record_video_argument = "--strictdoc-record-video" if record_video else ""

    Path(TEST_REPORTS_DIR).mkdir(parents=True, exist_ok=True)

    test_command = f"""
        pytest
        --capture=no
        {focus_argument}
        {record_video_argument}
        --junit-xml={TEST_REPORTS_DIR}/tests_screencast.pytest.junit.xml
        -o junit_suite_name="StrictDoc Screencast Tests"
        -o cache_dir=build/pytest_screencast
        tests/screencast/scenarios
    """

    run_invoke_with_uv(context, UvEnvironment.CHECK, test_command)


@task(aliases=["scov"])
def screencast_optimize_video(context, focus=None):
    """
    Converts recorded tests/screencast/output/*.webm into muted,
    web-optimized .webm (VP9) and .mp4 (H.264) pairs under
    tests/screencast/output/web/, ready to hand off to the product website.

    Run `invoke test-screencast --record-video` first to produce the raw
    recordings this reads from.
    """

    focus_argument = f"--focus {focus}" if focus is not None else ""

    run_invoke(
        context, f"python tests/screencast/optimize_video.py {focus_argument}"
    )


@task(aliases=["tu"])
def test_unit(context, coverage=False, focus=None, path=None, output=False):
    """
    @relation(SDOC-SRS-44, scope=function)
    """

    Path(TEST_REPORTS_DIR).mkdir(parents=True, exist_ok=True)

    focus_argument = f"-k {focus}" if focus is not None else ""
    output_argument = "--capture=no" if output else ""

    cwd = os.getcwd()

    if path is None:
        path = "tests/unit"
    else:
        assert "tests/unit" in path, path

    path_to_coverage_file = f"{cwd}/build/coverage/unit/.coverage"

    pytest_command = (
        """
        coverage run
            --rcfile=.coveragerc.unit
            --data-file={path_to_coverage_file}
            -m pytest
    """
        if coverage
        else "pytest"
    )

    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        f"""
            {pytest_command}
            {focus_argument}
            {output_argument}
            --junit-xml={TEST_REPORTS_DIR}/tests_unit.pytest.junit.xml
            -o cache_dir=build/pytest_cache/unit
            -o junit_suite_name="StrictDoc Unit Tests"
            -p no:seleniumbase
            {path}
        """,
    )
    if coverage and not focus and path == "tests/unit":
        run_invoke_with_uv(
            context,
            UvEnvironment.CHECK,
            f"""
                coverage report
                    --sort=cover
                    --rcfile=.coveragerc.unit
                    --data-file={path_to_coverage_file}
            """,
        )


@task(test_unit, aliases=["tuc"])
def test_unit_report(context):
    cwd = os.getcwd()

    path_to_coverage_file = f"{cwd}/build/coverage/unit/.coverage"

    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        f"""
            coverage html
                --rcfile=.coveragerc.unit
                --data-file={path_to_coverage_file}
        """,
    )


@task(clean, aliases=["ti"])
def test_integration(
    context,
    *,
    focus=None,
    debug=False,
    no_parallelization=False,
    fail_first=False,
    coverage=False,
    strictdoc=None,
    html2pdf=False,
    shard=None,
    environment=UvEnvironment.CHECK,
):
    """
    @relation(SDOC-SRS-45, scope=function)
    """

    cwd = os.getcwd()

    if strictdoc is None:
        strictdoc_exec = f"{uv_venv_python(environment)} -m strictdoc.cli.main"
    else:
        strictdoc_exec = strictdoc

    coverage_path_argument = ""
    if coverage:
        path_to_coverage_rc = f"{cwd}/.coveragerc.integration"
        strictdoc_exec = (
            f"coverage run --rcfile={path_to_coverage_rc} -m strictdoc.cli.main"
        )
        if html2pdf:
            path_to_coverage_dir = f"{cwd}/build/coverage/integration_html2pdf/"
        else:
            path_to_coverage_dir = f"{cwd}/build/coverage/integration/"
        path_to_coverage = os.path.join(path_to_coverage_dir, ".coverage")
        shutil.rmtree(path_to_coverage_dir, ignore_errors=True)
        coverage_path_argument = (
            f'--param COVERAGE_FILE="{path_to_coverage}" '
            f'--param COVERAGE_PROCESS_START="{path_to_coverage_rc}"'
        )

    debug_opts = "-vv --show-all" if debug else ""
    focus_or_none = f"--filter {focus}" if focus else ""
    fail_first_argument = "--max-failures 1" if fail_first else ""
    junit_xml_report_argument = (
        "--xunit-xml-output build/test_reports/tests_integration_html2pdf.lit.junit.xml"
        if html2pdf
        else "--xunit-xml-output build/test_reports/tests_integration.lit.junit.xml"
    )

    # Allow partitioning of integration and html2pdf tests
    partition_opts = ""
    if shard is not None:
        match = re.match(r"([1-9][0-9]*)/([1-9][0-9]*)", shard)
        assert match, f"--shard argument has an incorrect format: {shard}."
        run_shard = int(match.group(1))
        num_shards = int(match.group(2))
        partition_opts = f"--num-shards={num_shards} --run-shard={run_shard}"

    # HTML2PDF tests are running Chrome Driver which does not seem to be
    # parallelizable, or at least not in the way StrictDoc uses it.
    # If HTML2PDF option is provided, do not parallelize and only run the
    # HTML2PDF-specific tests.
    # HTML2PDF tests can be safely partitioned.
    chromedriver_param = ""
    if not html2pdf:
        parallelize_opts = "" if not no_parallelization else "--threads 1"
        html2pdf_param = ""
        test_folder = f"{cwd}/tests/integration"
        test_output_dir = "build/tests_integration"
    else:
        parallelize_opts = "--threads 1"
        html2pdf_param = "--param TEST_HTML2PDF=1"
        chromedriver_path = os.environ.get("CHROMEWEBDRIVER")
        if chromedriver_path is not None:
            # NOTE: isfile() check does not work on GitHub Actions / Linux,
            #       the exists() check works.
            assert os.path.exists(chromedriver_path), chromedriver_path
            chromedriver_param = f"--param CHROMEDRIVER={os.path.join(chromedriver_path, 'chromedriver')}"
            if os.name == "nt":
                # On Windows, its chromdriver.exe
                chromedriver_param = chromedriver_param + ".exe"
        test_folder = f"{cwd}/tests/integration/features/html2pdf"
        test_output_dir = "build/tests_integration_html2pdf"

    # The command sometimes exits with 1 even if the files are deleted.
    # warn=True ensures that the execution continues.
    run_invoke(
        context,
        f"""
        rm -rf {test_output_dir}
        """,
        warn=True,
    )

    run_invoke(
        context,
        f"""
        rm -rf {STRICTDOC_TMP_DIR}
        """,
    )

    Path(STRICTDOC_TMP_DIR).mkdir(exist_ok=True)
    Path(TEST_REPORTS_DIR).mkdir(parents=True, exist_ok=True)

    itest_command = f"""
        lit
        --param STRICTDOC_EXEC="{strictdoc_exec}"
        --param STRICTDOC_TMP_DIR="{STRICTDOC_TMP_DIR}"
        --param TEST_OUTPUT_DIR="{test_output_dir}"
        --timeout 180
        --order smart
        {junit_xml_report_argument}
        {coverage_path_argument}
        {html2pdf_param}
        {chromedriver_param}
        -v
        {debug_opts}
        {focus_or_none}
        {fail_first_argument}
        {parallelize_opts}
        {partition_opts}
        {test_folder}
    """

    run_invoke_with_uv(
        context,
        environment,
        itest_command,
        environment={"STRICTDOC_CACHE_DIR": "Output/_cache"},
    )


@task
def coverage_combine(context):
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            coverage combine
                --data-file build/coverage/.coverage.combined
                --keep
                build/coverage/end2end_strictdoc/.coverage.*
                build/coverage/integration/.coverage.*
                build/coverage/integration_html2pdf/.coverage.*
                build/coverage/unit/.coverage
                build/coverage/unit_server/.coverage
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            coverage html
                --rcfile .coveragerc.combined
                --data-file build/coverage/.coverage.combined
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            coverage json
                --rcfile .coveragerc.combined
                --data-file build/coverage/.coverage.combined
                --pretty-print
                -o build/coverage/coverage.combined.json
        """,
    )


@task
def lint_ruff_format(context):
    """
    @relation(SDOC-SRS-42, scope=function)
    """

    result: invoke.runners.Result = run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            ruff
                format
                --cache-dir build/ruff_cache
                *.py
                developer/
                docs/
                strictdoc/
                tools/ecss
                tests/unit/
                tests/unit_server/
                tests/integration/*.py
                tests/end2end/
        """,
    )
    # Ruff always exits with 0, so we handle the output.
    if "reformatted" in result.stdout:
        print("invoke: ruff format found issues")  # noqa: T201
        result.exited = 1
        raise invoke.exceptions.UnexpectedExit(result)


@task(aliases=["lr"])
def lint_ruff(context):
    """
    @relation(SDOC-SRS-42, scope=function)
    """

    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            ruff check . --fix --exit-non-zero-on-fix --cache-dir build/ruff_cache
        """,
    )


@task(aliases=["lm"])
def lint_mypy(context):
    """
    @relation(SDOC-SRS-41, SDOC-SRS-43, scope=function)
    """

    # These checks do not seem to be useful:
    # - import
    # --disallow-any-expr
    # --disallow-any-explicit
    # --disallow-any-unimported  # noqa: ERA001
    # --disallow-any-decorated
    # - type-abstract. It is ignored on purpose because of assert_cast()
    #   implementation. See https://stackoverflow.com/a/74073453/598057.
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            mypy docs/
                 strictdoc/
                 tests/unit/strictdoc/backend/sdoc_source_code/test_marker_lexer.py

                --show-error-codes
                --disable-error-code=import
                --disable-error-code=type-abstract
                --cache-dir=build/mypy_cache
                --extra-checks

                --strict
                --strict-optional
                --strict-equality

                --check-untyped-defs
                --disallow-any-generics
                --disallow-incomplete-defs
                --disallow-subclassing-any
                --disallow-untyped-calls
                --disallow-untyped-decorators
                --disallow-untyped-defs
                --no-implicit-optional
                --warn-no-return
                --warn-redundant-casts
                --warn-return-any
                --warn-unreachable
                --warn-unused-ignores

                --python-version=3.10
        """,
    )


@task
def lint_format_js(context):
    # NOTE: Could not find the '--' equivalent for -w80.
    result: invoke.runners.Result = run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            js-beautify
                --indent-size=2
                --end-with-newline
                --replace
                -w100
                strictdoc/export/html/_static/autocompletable_field.js
                strictdoc/export/html/_static/copy_to_clipboard.js
                strictdoc/export/html/_static/deletable_field.js
                strictdoc/export/html/_static/draggable_list.js
                strictdoc/export/html/_static/editable_field.js
                strictdoc/export/html/_static/modal.js
                strictdoc/export/html/_static/movable_field.js
                strictdoc/export/html/_static/scroll_into_view.js
                strictdoc/export/html/_static/static_html_search.js
                strictdoc/export/html/_static/tabs.js
                strictdoc/features/project_index/assets/stable_uri_forwarder.js
        """,
    )
    # Ruff always exits with 0, so we handle the output.
    if "reformatted" in result.stdout:
        print("invoke: ruff format found issues")  # noqa: T201
        result.exited = 1
        raise invoke.exceptions.UnexpectedExit(result)


@task(aliases=["lc"])
def lint_commit(context):  # noqa: ARG001
    try:
        validate_commits_locally_or_ci()
    except ValueError as e:
        raise invoke.exceptions.Exit(message=str(e), code=1) from None


@task(aliases=["lf"])
def lint_fixit(context, fix=False, auto=False, path="strictdoc/"):
    if fix:
        auto_argument = "--automatic" if auto else ""
        run_invoke_with_uv(
            context,
            UvEnvironment.CHECK,
            f"""
                fixit fix {path} {auto_argument}
            """,
            pty=True,
        )
    else:
        run_invoke_with_uv(
            context,
            UvEnvironment.CHECK,
            f"""
                fixit lint --diff {path}
            """,
        )


@task(aliases=["l"])
def lint(context):
    lint_commit(context)
    lint_ruff_format(context)
    lint_ruff(context)
    lint_mypy(context)


@task(aliases=["t"])
def test(context, shard=None):
    test_unit(context)
    test_unit_server(context)
    test_integration(context, shard=shard)


@task(aliases=["ta"])
def test_all(context, coverage=False, headless=False):
    test_unit(context, coverage=coverage)
    test_unit_server(context)
    test_integration(context, coverage=coverage)
    test_integration(context, coverage=coverage, html2pdf=True)
    test_end2end(context, coverage=coverage, headless=headless)


@task(aliases=["c"])
def check(context):
    lint(context)
    test(context)


# https://github.com/github-changelog-generator/github-changelog-generator
# gem install github_changelog_generator
@task
def changelog(context, github_token):
    # The alpha release tags are excluded from the changelog.
    command = f"""
        github_changelog_generator
        --token {github_token}
        --user strictdoc-project
        --exclude-tags-regex ".*a\\d+"
        --project strictdoc
        """
    run_invoke(context, command)


@task
def check_dead_links(context):
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py docs/strictdoc_01_user_guide.sdoc
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py docs/strictdoc_02_feature_map.sdoc
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py docs/strictdoc_03_faq.sdoc
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py docs/strictdoc_04_release_notes.sdoc
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py docs/strictdoc_05_troubleshooting.sdoc
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py docs/strictdoc_10_contributing.sdoc
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py docs/strictdoc_11_developer_guide.sdoc
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py docs/strictdoc_24_development_plan.sdoc
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py docs/strictdoc_20_l1_system_requirements.sdoc
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py docs/strictdoc_21_l2_high_level_requirements.sdoc
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py docs/strictdoc_25_design.sdoc
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py CONTRIBUTING.md
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py NOTICE
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.CHECK,
        """
            python tools/link_health.py README.md
        """,
    )


@task
def release_local(context):
    run_invoke(
        context,
        """
            rm -rf build/
        """,
    )
    run_invoke(
        context,
        """
            pip uninstall strictdoc -y
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.RELEASE_LOCAL,
        """
            python -m build --outdir build/dist
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.RELEASE_LOCAL,
        """
            twine check build/dist/*
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.RELEASE_LOCAL,
        """
            pip install build/dist/*.tar.gz
        """,
    )
    test_integration(
        context, strictdoc="strictdoc", environment=UvEnvironment.RELEASE_LOCAL
    )


@task
def release(context, test_pypi=False, username=None, password=None):
    """
    A release can be made to PyPI or test package index (TestPyPI):
    https://pypi.org/project/strictdoc/
    https://test.pypi.org/project/strictdoc/
    """

    env_user = os.environ.get("TWINE_USERNAME")
    env_pass = os.environ.get("TWINE_PASSWORD")

    # The credentials come from one of three sources:
    # 1) --username and --password,
    # 2) TWINE_USERNAME and TWINE_PASSWORD (GitHub release workflow),
    # 3) the strictdoc_release or strictdoc_test section of ~/.pypirc.
    has_cli_credentials = bool(username or password)
    has_env_credentials = bool(env_user or env_pass)
    assert not (has_cli_credentials and has_env_credentials), (
        "Provide credentials either with --username/--password or with "
        "TWINE_USERNAME/TWINE_PASSWORD, not both."
    )
    if has_cli_credentials:
        assert username and password, (
            "Both --username and --password must be provided."
        )
    if has_env_credentials:
        assert env_user and env_pass, (
            "Both TWINE_USERNAME and TWINE_PASSWORD must be set."
        )
        assert env_user == "__token__", env_user

    repository_argument_or_none = ""
    if not has_cli_credentials and not has_env_credentials:
        repository_argument_or_none = (
            "--repository strictdoc_test"
            if test_pypi
            else "--repository strictdoc_release"
        )
    user_password = f"-u{username} -p{password}" if has_cli_credentials else ""

    run_invoke(
        context,
        """
            rm -rf build/dist/
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.RELEASE,
        """
            python -m build --outdir build/dist
        """,
    )
    run_invoke_with_uv(
        context,
        UvEnvironment.RELEASE,
        """
            twine check build/dist/*
        """,
    )
    # The token is in a core developer's .pypirc file.
    # https://test.pypi.org/manage/account/token/
    # https://packaging.python.org/en/latest/specifications/pypirc/#pypirc
    run_invoke_with_uv(
        context,
        UvEnvironment.RELEASE,
        f"""
            twine upload build/dist/strictdoc-*.tar.gz build/dist/strictdoc-*.whl
                {repository_argument_or_none}
                {user_password}
        """,
    )


@task
def release_pyinstaller(context):
    path_to_pyi_dist = "/tmp/strictdoc"
    html_template_data_options = get_pyinstaller_html_template_data_options()
    html_static_data_options = get_pyinstaller_html_static_data_options()

    # The --hidden-import strictdoc.server.app flag is needed because without
    # it, the following is produced:
    # ERROR: Error loading ASGI app. Could not import
    # module "strictdoc.server.app".
    # Solution found here: https://stackoverflow.com/a/71340437/598057
    # This behavior is not surprising because that's how the uvicorn loads the
    # application separately from the parent process.
    #
    # Compatibility modules can be imported by user-provided statistics
    # generators at runtime. PyInstaller cannot discover these imports
    # statically because the generators live outside of StrictDoc's package.
    #
    # --hidden-import strictdoc.api is needed for the same reason:
    # strictdoc.api is never imported anywhere inside StrictDoc's own
    # package (only by dynamically-loaded, external files such as a
    # project's own strictdoc_config.py, custom statistics generators, or
    # custom plugins), so PyInstaller's static analysis -- which walks
    # imports starting from strictdoc/cli/main.py -- never discovers it on
    # its own.
    command = f"""
        pyinstaller
            --clean
            --name strictdoc
            --noconfirm
            --additional-hooks-dir developer/pyinstaller_hooks
            --distpath {path_to_pyi_dist}
            --hidden-import strictdoc.api
            --hidden-import strictdoc.backend.rst.strictdoc_lexer
            --hidden-import strictdoc.core.statistics.metric
            --hidden-import strictdoc.export.html.generators.project_statistics
            --hidden-import strictdoc.export.html.generators.view_objects.project_statistics_view_object
            --hidden-import strictdoc.export.html.generators.view_objects.project_tree_stats
            --hidden-import strictdoc.server.app
            {html_template_data_options}
            {html_static_data_options}
            --add-data strictdoc/backend/rst/templates:templates/rst
            strictdoc/cli/main.py
    """

    run_invoke_with_uv(
        context,
        UvEnvironment.PYINSTALLER,
        """
    pyinstaller --version
    """,
    )

    run_invoke_with_uv(context, UvEnvironment.PYINSTALLER, command)


@task
def watch(context, sdocs_path="."):
    strictdoc_command = f"""
        python -m strictdoc.cli.main
            export
            {sdocs_path}
            --output-dir output/
    """

    run_invoke_with_uv(
        context,
        UvEnvironment.DEVELOPMENT,
        f"""
            {strictdoc_command}
        """,
    )

    paths_to_watch = "."
    run_invoke_with_uv(
        context,
        UvEnvironment.DEVELOPMENT,
        f"""
            watchmedo shell-command
            --patterns="*.py;*.sdoc;*.jinja;*.html;*.css;*.js"
            --recursive
            --ignore-pattern='output/;tests/integration'
            --command='{strictdoc_command}'
            --drop
            {paths_to_watch}
        """,
    )


@task
def run(context, command):
    run_invoke_with_uv(
        context,
        UvEnvironment.DEVELOPMENT,
        f"""
            {command}
        """,
    )


@task
def nuitka(context):
    html_template_data_options = get_nuitka_html_template_data_options()
    html_static_data_options = get_nuitka_html_static_data_options()

    run_invoke(
        context,
        f"""
        PYTHONPATH="{os.getcwd()}"
        python -m nuitka
            --static-libpython=no
            --standalone
            --include-module=textx
            --include-module=strictdoc.server.app
            --include-module=docutils
            --include-module=docutils.readers.standalone
            --include-module=docutils.parsers.rst
            {html_template_data_options}
            {html_static_data_options}
            --include-data-dir=strictdoc/backend/rst/templates=templates/rst
            --include-package-data=docutils
            strictdoc/cli/main.py
        """,
    )


# https://github.com/jrfonseca/gprof2dot
# pip install gprof2dot
@task()
def performance(context):
    command = """
        python -m cProfile -o output/profile.prof
            -m strictdoc.cli.main export . --no-parallelization &&
        gprof2dot -f pstats output/profile.prof | dot -Tpng -o output/output.png
    """
    run_invoke(context, command)


@task(performance)
def performance_snakeviz(context):
    command = """
        snakeviz output/profile.prof
    """
    run_invoke(context, command)


@task(aliases=["bd"])
def build_docker(
    context,
    image: str = "strictdoc:latest",
    no_cache: bool = False,
    source="pypi",
):
    no_cache_argument = "--no-cache" if no_cache else ""
    run_invoke(
        context,
        f"""
        docker build .
            --build-arg STRICTDOC_SOURCE={source}
            -t {image}
            {no_cache_argument}
        """,
    )


@task(aliases=["rd"])
def run_docker(
    context, image: str = "strictdoc:latest", command: Optional[str] = None
):
    command_argument = (
        f'/bin/bash -c "{command}"' if command is not None else ""
    )

    run_invoke(
        context,
        f"""
        docker run
            --name strictdoc
            --rm
            -it
            -e HOST_UID=$(id -u) -e HOST_GID=$(id -g)
            -v "$(pwd):/data"
            {image}
            {command_argument}
        """,
        pty=True,
    )


@task(aliases=["td"])
def test_docker(context, image: str = "strictdoc:latest"):
    run_invoke(
        context,
        """
        rm -rf output/ && mkdir -p output/ && chmod 777 output/
        """,
    )
    run_docker(
        context,
        image=image,
        command="strictdoc export --formats=html,html2pdf .",
    )

    def check_file_owner(filepath):
        import pwd  # noqa: PLC0415

        file_owner = pwd.getpwuid(os.stat(filepath).st_uid).pw_name
        current_user = os.environ.get("USER", "")
        return file_owner == current_user

    assert check_file_owner(
        "output/html2pdf/pdf/docs/strictdoc_01_user_guide.pdf"
    )


@task(aliases=["q"])
def qualification(context):
    test_all(context, coverage=True, headless=True)
    coverage_combine(context)


@task()
def drawio(context):
    if sys.platform == "darwin":
        path_to_drawio = "/Applications/draw.io.app/Contents/MacOS/draw.io"
    elif sys.platform.startswith("linux"):
        path_to_drawio = "drawio"
    else:
        raise NotImplementedError(
            "drawio task is supported only on macOS and Linux."
        )

    artifacts = [
        (
            "developer/drawio/Architecture.drawio",
            "docs/_assets/StrictDoc_Workspace-Architecture.drawio.png",
        ),
        (
            "developer/drawio/Backlog.drawio",
            "docs/_assets/StrictDoc_Workspace-Backlog.drawio.png",
        ),
        (
            "developer/drawio/Roadmap.drawio",
            "docs/_assets/StrictDoc_Workspace-Roadmap.drawio.png",
        ),
    ]

    for path_to_drawio_, path_to_png_ in artifacts:
        print(f"Copying: {path_to_drawio_} -> {path_to_png_}")  # noqa: T201

        # Basic safety for now to avoid writing wrong files.
        assert os.path.isfile(path_to_drawio_), path_to_drawio_
        assert os.path.isfile(path_to_png_), path_to_png_

        run_invoke(
            context,
            f"""
            {path_to_drawio}
                --export
                --format png
                -o {path_to_png_}
                --page-index 1
                {path_to_drawio_}
            """,
            pty=True,
        )