devx/src/devx/ci/post_merge.py

#!/usr/bin/env python3
"""Update Vikunja task after a merge to master.

Usage:
  VIKUNJA_TOKEN=<token> python3 -m devx.ci.post_merge <commit_msg> [--commit-sha <sha>]
"""

import re
import subprocess  # nosec B404

import click
from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]

from devx.api_clients import VikunjaClient
from devx.ci._shared import extract_task_id as _extract_task_id
from devx.config import DEFAULT_PER_PAGE, TASK_PREFIX, VIKUNJA_API_URL, VIKUNJA_PROJECT_ID
from devx.exceptions import APIError
from devx.i18n import _
from devx.tokens import get_vikunja_token

load_dotenv()


def _get_git_commit_message() -> str:
    """Get the full commit message of the latest commit."""
    result = subprocess.run(  # nosec B603 B607
        ["git", "log", "-1", "--pretty=%B"],
        capture_output=True,
        text=True,
        check=False,
    )
    if result.returncode != 0:
        raise click.ClickException(f"git log failed: {result.stderr.strip()}")
    return result.stdout.strip()


def _get_git_commit_sha() -> str:
    """Get the SHA of the latest commit."""
    result = subprocess.run(  # nosec B603 B607
        ["git", "rev-parse", "HEAD"],
        capture_output=True,
        text=True,
        check=False,
    )
    if result.returncode != 0:
        raise click.ClickException(f"git rev-parse failed: {result.stderr.strip()}")
    return result.stdout.strip()


def extract_task_id(commit_msg: str) -> str:
    """Extract task identifier from the first line of commit message (delegates to shared utility)."""
    first_line = commit_msg.split("\n")[0]
    return _extract_task_id(first_line)


def extract_conventional_msg(commit_msg: str) -> str:
    """Strip the DEVX-N prefix from the commit subject.

    Handles both formats:
    - ``DEVX-N: <message>`` (legacy, colon-separated)
    - ``DEVX-N <message>`` (current, space-separated)
    """
    first_line = commit_msg.split("\n")[0]
    return re.sub(rf"^{TASK_PREFIX}-\d+[:\s]\s*", "", first_line)


def resolve_task_id(client: VikunjaClient, task_id: str) -> int:
    """Resolve DEVX-N identifier to Vikunja numeric task ID.

    Paginates through the project's tasks to handle projects with more
    than 50 tasks.  Raises ClickException if the task is not found.
    """
    page = 1
    while True:
        tasks = client.list_project_tasks(VIKUNJA_PROJECT_ID, page=page, per_page=DEFAULT_PER_PAGE)
        if not tasks:
            break
        matches = [t for t in tasks if t.get("identifier") == task_id]
        if matches:
            return int(matches[0]["id"])
        if len(tasks) < DEFAULT_PER_PAGE:
            break
        page += 1
    raise click.ClickException(
        _(
            "Could not find Vikunja task {task_id} in project {project_id}. "
            "Every PR must have a corresponding Vikunja task.",
            task_id=task_id,
            project_id=VIKUNJA_PROJECT_ID,
        )
    )


def build_comment(task_id: str, conv_msg: str, commit_sha: str) -> str:
    """Build HTML comment body for Vikunja."""
    return f"<p><strong>{task_id}</strong>: {conv_msg}</p><p>Commit: <code>{commit_sha}</code></p>"


@click.command()
@click.argument("commit_msg", required=False)
@click.option("--commit-sha", default="", help="Commit SHA")
@click.option("--from-git", is_flag=True, default=False, help="Read commit message and SHA from git.")
@click.option(
    "--git-sha",
    default="",
    help="Read commit message from a specific git SHA (avoids race condition with parallel jobs).",
)
def main(commit_msg: str | None, commit_sha: str, from_git: bool, git_sha: str) -> None:
    if git_sha:
        # Read commit message from a specific SHA — this avoids the race
        # condition where a parallel job (e.g., release) pushes a new commit
        # to master before this job reads HEAD.
        result = subprocess.run(  # nosec B603 B607
            ["git", "log", "-1", "--pretty=%B", git_sha],
            capture_output=True,
            text=True,
            check=False,
        )
        if result.returncode != 0:
            raise click.ClickException(f"git log failed for SHA {git_sha}: {result.stderr.strip()}")
        commit_msg = result.stdout.strip()
        if not commit_sha:
            commit_sha = git_sha
    elif from_git:
        commit_msg = _get_git_commit_message()
        if not commit_sha:
            commit_sha = _get_git_commit_sha()
    if not commit_msg:
        raise click.ClickException("commit_msg argument is required (or use --from-git or --git-sha)")
    try:
        token = get_vikunja_token()
    except click.ClickException:
        raise click.ClickException(_("ERROR: VIKUNJA_TOKEN is not set.")) from None

    task_id = extract_task_id(commit_msg)
    if not task_id:
        first_line = commit_msg.split("\n")[0]
        # Skip gracefully for infrastructure commits that don't follow
        # the DEVX-N convention: release commits, reverts, bot commits, etc.
        infra_patterns = [
            r"^release: v\d+\.\d+\.\d+",  # release commits
            r"^revert: ",  # git revert commits
            r"^Merge ",  # merge commits
            r"^\[skip ci\]",  # skip-ci commits
        ]
        for pattern in infra_patterns:
            if re.match(pattern, first_line):
                click.echo(
                    _(
                        "Infrastructure commit (no DEVX-N task ID), skipping Vikunja update: {msg}",
                        msg=first_line,
                    )
                )
                return
        # Non-infrastructure commits without DEVX-N prefix — this is a
        # convention violation. Fail the post-merge job so the issue is visible.
        raise click.ClickException(
            _(
                "No task ID ({prefix}-N) found in commit message: {msg}. "
                "Every non-infrastructure commit must have a task ID.",
                prefix=TASK_PREFIX,
                msg=first_line,
            )
        )

    client = VikunjaClient(VIKUNJA_API_URL, token)
    vikunja_task_id = resolve_task_id(client, task_id)
    conv_msg = extract_conventional_msg(commit_msg)
    sha = commit_sha or "unknown"
    html = build_comment(task_id, conv_msg, sha)

    try:
        client.post_comment(vikunja_task_id, html)
        client.update_task(vikunja_task_id, done=True)
    except APIError as e:
        # Vikunja API failures must be visible — the task was not updated
        # and needs manual intervention. Failing the CI job makes this visible.
        raise click.ClickException(
            _(
                "Vikunja API error (HTTP {status}): {message}. "
                "Task {task_id} was NOT updated. "
                "The merge succeeded but the Vikunja task needs manual update.",
                status=e.status,
                message=e.message,
                task_id=task_id,
            )
        ) from e

    click.echo(
        _(
            "Nice! Vikunja task {task_id} (ID {vikunja_id}) updated and marked done.",
            task_id=task_id,
            vikunja_id=vikunja_task_id,
        )
    )


if __name__ == "__main__":  # pragma: no cover
    main()