"""Structured issue/branch ownership evidence (#440).

Author branches must follow ``(fix|feat|docs|chore)/issue-<n>-<desc>``. Duplicate-work
and lock-recovery gates use this parser instead of broad substring matching on
``issue-<n>`` so unrelated branch names cannot false-positive.
"""

from __future__ import annotations

import re

ISSUE_BRANCH_RE = re.compile(
    r"^(?P<prefix>fix|feat|docs|chore)/issue-(?P<num>\d+)(?:-|$)"
)


def parse_issue_branch(branch_name: str) -> int | None:
    """Return the issue number encoded in a canonical author branch, else None."""
    match = ISSUE_BRANCH_RE.match((branch_name or "").strip())
    if not match:
        return None
    return int(match.group("num"))


def branch_belongs_to_issue(branch_name: str, issue_number: int) -> bool:
    """True when ``branch_name`` is a canonical branch for ``issue_number``."""
    parsed = parse_issue_branch(branch_name)
    return parsed is not None and parsed == issue_number