esys-gitlog 0.2.0__tar.gz → 0.3.0__tar.gz

{esys_gitlog-0.2.0/src/esys_gitlog.egg-info → esys_gitlog-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: esys-gitlog
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python implementation of git elog
 Author: Project maintainers
 License-Expression: MIT
@@ -55,9 +55,51 @@ and named profiles follow root SADR-0009 / SADR-0010 and contract CADR-0012.
 elog --preferences path.json   # preference overlay
 elog --profile acme            # built-in or profiles/acme.json
 elog --config path/profile.json  # one-off profile file
-elog preferences detect        # probe jira/gh/glab/git remote; write missing user keys
+elog preferences detect        # probe jira-cli/acli + git remote; write missing user keys
+elog preferences detect --json --no-write   # machine-readable candidates (extension setup)
+elog preferences set-link jira-id 'https://host/browse/{id}'
+elog preferences clear-link jira-id
+elog preferences set-tool jira 'C:\tools\jira.exe'   # optional absolute path
+elog preferences set-tool acli /usr/local/bin/acli
 ```
 
+Jira browse bases come from local **jira-cli** config and/or **Atlassian acli**
+(`acli jira config get site`), never from per-commit HTTP (SADR-0010). Detection
+only fills unset user keys unless you use `set-link`. Absolute paths live under
+`detection.jiraExecutable` / `detection.acliExecutable` when the tools are not
+on `PATH`.
+
+### Live Jira fixture (SCRUM)
+
+The free site [libesys.atlassian.net](https://libesys.atlassian.net/browse/SCRUM-1)
+uses project key **`SCRUM`** only (do not invent other project keys).
+
+1. Configure acli or jira-cli against that site (optional absolute paths via
+   `elog preferences set-tool`).
+2. Seed once (creates 10 new issues, writes the pin — not part of every CI run):
+
+```bash
+python scripts/seed_jira_live_fixture.py --project SCRUM --count 10
+```
+
+3. Commit `tests/integration/jira_live.pin.json`.
+4. Materialize a durable Git repo for the VS Code extension / manual checks:
+
+```bash
+python scripts/materialize_jira_live_repo.py
+```
+
+   Output: `tests/integration/jira_live_repo/` (gitignored except a placeholder
+   README). Open that folder, store the browse template, refresh the commit browser.
+5. Run the live test locally or enable GitLab variable `ESYS_GITLOG_JIRA_LIVE=1`
+   for job `test:jira-live`:
+
+```bash
+ESYS_GITLOG_JIRA_LIVE=1 pytest -m jira_live -o addopts= --no-cov
+```
+
+Default `pytest` excludes `@pytest.mark.jira_live` so coverage stays offline.
+
 ## Standalone binary (optional)
 
 The primary install remains the wheel + `git-elog` / `elog` console scripts. For a

{esys_gitlog-0.2.0 → esys_gitlog-0.3.0}/README.md

@@ -33,9 +33,51 @@ and named profiles follow root SADR-0009 / SADR-0010 and contract CADR-0012.
 elog --preferences path.json   # preference overlay
 elog --profile acme            # built-in or profiles/acme.json
 elog --config path/profile.json  # one-off profile file
-elog preferences detect        # probe jira/gh/glab/git remote; write missing user keys
+elog preferences detect        # probe jira-cli/acli + git remote; write missing user keys
+elog preferences detect --json --no-write   # machine-readable candidates (extension setup)
+elog preferences set-link jira-id 'https://host/browse/{id}'
+elog preferences clear-link jira-id
+elog preferences set-tool jira 'C:\tools\jira.exe'   # optional absolute path
+elog preferences set-tool acli /usr/local/bin/acli
 ```
 
+Jira browse bases come from local **jira-cli** config and/or **Atlassian acli**
+(`acli jira config get site`), never from per-commit HTTP (SADR-0010). Detection
+only fills unset user keys unless you use `set-link`. Absolute paths live under
+`detection.jiraExecutable` / `detection.acliExecutable` when the tools are not
+on `PATH`.
+
+### Live Jira fixture (SCRUM)
+
+The free site [libesys.atlassian.net](https://libesys.atlassian.net/browse/SCRUM-1)
+uses project key **`SCRUM`** only (do not invent other project keys).
+
+1. Configure acli or jira-cli against that site (optional absolute paths via
+   `elog preferences set-tool`).
+2. Seed once (creates 10 new issues, writes the pin — not part of every CI run):
+
+```bash
+python scripts/seed_jira_live_fixture.py --project SCRUM --count 10
+```
+
+3. Commit `tests/integration/jira_live.pin.json`.
+4. Materialize a durable Git repo for the VS Code extension / manual checks:
+
+```bash
+python scripts/materialize_jira_live_repo.py
+```
+
+   Output: `tests/integration/jira_live_repo/` (gitignored except a placeholder
+   README). Open that folder, store the browse template, refresh the commit browser.
+5. Run the live test locally or enable GitLab variable `ESYS_GITLOG_JIRA_LIVE=1`
+   for job `test:jira-live`:
+
+```bash
+ESYS_GITLOG_JIRA_LIVE=1 pytest -m jira_live -o addopts= --no-cov
+```
+
+Default `pytest` excludes `@pytest.mark.jira_live` so coverage stays offline.
+
 ## Standalone binary (optional)
 
 The primary install remains the wheel + `git-elog` / `elog` console scripts. For a

{esys_gitlog-0.2.0 → esys_gitlog-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "esys-gitlog"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python implementation of git elog"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -41,7 +41,12 @@ where = ["src"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = [".", "src"]
+markers = [
+  "jira_live: live Jira fixture (ESYS_GITLOG_JIRA_LIVE=1 + seeded pin)",
+]
 addopts = [
+  "-m",
+  "not jira_live",
   "--cov=esys_gitlog",
   "--cov-report=term-missing",
   "--cov-fail-under=95.01",

{esys_gitlog-0.2.0 → esys_gitlog-0.3.0}/src/esys_gitlog/__init__.py

@@ -1,3 +1,3 @@
 """esys_gitlog — installable package."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{esys_gitlog-0.2.0 → esys_gitlog-0.3.0}/src/esys_gitlog/cli.py

@@ -11,13 +11,17 @@ from typer.core import TyperGroup
 
 from esys_gitlog import app as application
 from esys_gitlog.config import DisplayMode, QaMode
-from esys_gitlog.detection import detect_links, dump_detection_debug
+from esys_gitlog.detection import detect_report, dump_detection_debug
 from esys_gitlog.git_adapter import GitError, filter_git_log_args
 from esys_gitlog.preferences import (
+    LinkPreferences,
+    clear_user_ref_link,
     fill_link_gaps,
     load_layered_preferences,
     merge_missing_links_into_user_file,
     preferences_to_object,
+    set_user_detection_executables,
+    set_user_ref_link,
 )
 from esys_gitlog.tool_paths import user_preferences_path
 
@@ -299,13 +303,40 @@ def preferences_detect(
         "--debug",
         help="Print which vendor CLIs are on PATH.",
     ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Print a machine-readable detection report (candidates, sources, tools).",
+    ),
+    probe_auth: bool = typer.Option(
+        False,
+        "--probe-auth",
+        help="Optionally probe jira-cli/acli auth (setup only; may touch the network).",
+    ),
 ) -> None:
-    """Probe local Jira/GitHub/GitLab CLIs and git remote; optionally persist."""
+    """Probe local Jira (jira-cli/acli), GitHub/GitLab CLIs and git remote; optionally persist."""
     cwd = Path.cwd()
     prefs = load_layered_preferences(cwd)
-    discovered = detect_links(cwd, detection=prefs.detection)
-    if show_debug:
-        typer.echo(dump_detection_debug())
+    report = detect_report(
+        cwd,
+        detection=prefs.detection,
+        probe_auth=probe_auth,
+    )
+    discovered = LinkPreferences(
+        ref_links=dict(report.get("refLinks") or {}),
+        commit_link=report.get("commitLink"),
+    )
+    if show_debug and not as_json:
+        typer.echo(dump_detection_debug(prefs.detection))
+    if as_json:
+        if write:
+            path = user_preferences_path()
+            merge_missing_links_into_user_file(discovered=discovered, user_path=path)
+            report["wrote"] = str(path)
+        else:
+            report["wrote"] = None
+        typer.echo(json.dumps(report, indent=2))
+        return
     merged = fill_link_gaps(prefs, discovered)
     typer.echo(json.dumps(preferences_to_object(merged), indent=2))
     if write:
@@ -314,9 +345,68 @@ def preferences_detect(
         typer.echo(f"wrote missing keys to {path}", err=True)
 
 
+@preferences_app.command("set-link")
+def preferences_set_link(
+    family: str = typer.Argument(help="Identifier family, e.g. jira-id"),
+    template: str = typer.Argument(
+        help="URL template with {id}, e.g. https://host/browse/{id}",
+    ),
+) -> None:
+    """Create or overwrite a user-layer ref link template (explicit settings edit)."""
+    path = user_preferences_path()
+    set_user_ref_link(family, template, user_path=path)
+    typer.echo(json.dumps({"family": family, "template": template, "path": str(path)}, indent=2))
+
+
+@preferences_app.command("clear-link")
+def preferences_clear_link(
+    family: str = typer.Argument(help="Identifier family, e.g. jira-id"),
+) -> None:
+    """Remove a user-layer ref link template."""
+    path = user_preferences_path()
+    clear_user_ref_link(family, user_path=path)
+    typer.echo(json.dumps({"family": family, "cleared": True, "path": str(path)}, indent=2))
+
+
+@preferences_app.command("set-tool")
+def preferences_set_tool(
+    tool: str = typer.Argument(help="Tool name: jira or acli"),
+    executable: str = typer.Argument(help="Absolute path to the executable"),
+) -> None:
+    """Store an absolute path for jira-cli or acli (when not on PATH)."""
+    name = tool.strip().lower()
+    path = user_preferences_path()
+    if name in ("jira", "jira-cli"):
+        set_user_detection_executables(jira_executable=executable, user_path=path)
+    elif name == "acli":
+        set_user_detection_executables(acli_executable=executable, user_path=path)
+    else:
+        typer.echo("tool must be 'jira' or 'acli'", err=True)
+        raise typer.Exit(code=2)
+    typer.echo(json.dumps({"tool": name, "executable": executable, "path": str(path)}, indent=2))
+
+
+@preferences_app.command("clear-tool")
+def preferences_clear_tool(
+    tool: str = typer.Argument(help="Tool name: jira or acli"),
+) -> None:
+    """Remove a configured jira-cli or acli path (fall back to PATH)."""
+    name = tool.strip().lower()
+    path = user_preferences_path()
+    if name in ("jira", "jira-cli"):
+        set_user_detection_executables(clear_jira=True, user_path=path)
+    elif name == "acli":
+        set_user_detection_executables(clear_acli=True, user_path=path)
+    else:
+        typer.echo("tool must be 'jira' or 'acli'", err=True)
+        raise typer.Exit(code=2)
+    typer.echo(json.dumps({"tool": name, "cleared": True, "path": str(path)}, indent=2))
+
+
 def main() -> None:
     """Console script entry point."""
-    invoked = Path(sys.argv[0]).name
+    # Normalize Windows separators so ``Path.name`` works when run under POSIX.
+    invoked = Path(sys.argv[0].replace("\\", "/")).name
     if invoked.lower().endswith(".exe"):
         invoked = invoked[:-4]
     prog_name = invoked or "git-elog"

esys_gitlog-0.3.0/src/esys_gitlog/detection.py

@@ -0,0 +1,377 @@
+"""Optional local CLI / git-remote link-base detection (SADR-0010).
+
+Jira browse bases may come from ankitpokhrel/jira-cli and/or Atlassian acli.
+Discovery prefers local config files, then non-network CLI config gets. Optional
+auth probes are setup-only and never run per commit refresh.
+
+Configured absolute paths (``detection.jiraExecutable`` /
+``detection.acliExecutable``) win over PATH lookup.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from esys_gitlog.links import detect_commit_link_from_remote, read_origin_url
+from esys_gitlog.preferences import DetectionSettings, LinkPreferences
+
+_JIRA_SERVER = re.compile(r"""(?mx)^\s*(?:server|endpoint|url)\s*[:=]\s*["']?(https?://[^\s"']+)""")
+
+
+@dataclass(frozen=True)
+class JiraDetectResult:
+    """Outcome of local Jira browse-base detection."""
+
+    template: str | None
+    source: str | None
+    auth_ok: bool | None = None
+    auth_source: str | None = None
+
+
+@dataclass(frozen=True)
+class ResolvedToolPaths:
+    """Resolved absolute executables (or None when unavailable)."""
+
+    jira: str | None = None
+    acli: str | None = None
+    jira_configured: str | None = None
+    acli_configured: str | None = None
+
+
+def resolve_executable(name: str, configured: str | None = None) -> str | None:
+    """Prefer an absolute configured path when it exists; else ``PATH`` lookup."""
+    if configured:
+        candidate = Path(configured)
+        if candidate.is_file():
+            return str(candidate.resolve())
+        # Windows often omits ``.exe`` in settings.
+        for suffix in ("", ".exe", ".cmd", ".bat"):
+            alt = Path(str(candidate) + suffix) if suffix else candidate
+            if alt.is_file():
+                return str(alt.resolve())
+    return shutil.which(name)
+
+
+def resolve_tool_paths(detection: DetectionSettings | None = None) -> ResolvedToolPaths:
+    settings = detection or DetectionSettings()
+    return ResolvedToolPaths(
+        jira=resolve_executable("jira", settings.jira_executable),
+        acli=resolve_executable("acli", settings.acli_executable),
+        jira_configured=settings.jira_executable,
+        acli_configured=settings.acli_executable,
+    )
+
+
+def _run_text(
+    argv: list[str],
+    *,
+    timeout: float = 5.0,
+    executable: str | None = None,
+) -> str | None:
+    exe = executable or shutil.which(argv[0])
+    if not exe:
+        return None
+    try:
+        completed = subprocess.run(
+            [exe, *argv[1:]],
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=timeout,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if completed.returncode != 0:
+        return None
+    text = (completed.stdout or "").strip()
+    return text or None
+
+
+def _browse_template(base: str) -> str:
+    return base.rstrip("/") + "/browse/{id}"
+
+
+def _http_base(value: str) -> str | None:
+    text = value.strip().strip("\"'")
+    if not text.startswith("http"):
+        return None
+    # acli may print a bare site host URL; strip trailing paths that are not browse.
+    return text.rstrip("/")
+
+
+def jira_config_candidates() -> list[Path]:
+    """Known ankitpokhrel/jira-cli config paths (local, no network)."""
+    home = Path.home()
+    return [
+        home / ".config" / ".jira" / ".config.yml",
+        home / ".jira" / ".config.yml",
+        home / ".config" / "jira" / "config.yml",
+    ]
+
+
+# Back-compat alias used by tests.
+_jira_config_candidates = jira_config_candidates
+
+
+def _jira_from_config_files() -> tuple[str | None, str | None]:
+    for candidate in jira_config_candidates():
+        if not candidate.is_file():
+            continue
+        try:
+            text = candidate.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        match = _JIRA_SERVER.search(text)
+        if match:
+            base = _http_base(match.group(1))
+            if base:
+                return _browse_template(base), f"jira-cli-config:{candidate}"
+    return None, None
+
+
+def _jira_from_jira_cli(tools: ResolvedToolPaths) -> tuple[str | None, str | None]:
+    value = _run_text(
+        ["jira", "config", "get", "server"],
+        executable=tools.jira,
+    )
+    if value:
+        base = _http_base(value)
+        if base:
+            return _browse_template(base), "jira-cli:config-get-server"
+    return None, None
+
+
+def _jira_from_acli(tools: ResolvedToolPaths) -> tuple[str | None, str | None]:
+    value = _run_text(
+        ["acli", "jira", "config", "get", "site"],
+        executable=tools.acli,
+    )
+    if value:
+        base = _http_base(value)
+        if base:
+            return _browse_template(base), "acli:config-get-site"
+    return None, None
+
+
+def probe_jira_auth(
+    detection: DetectionSettings | None = None,
+) -> tuple[bool | None, str | None]:
+    """Best-effort auth check (setup only). Does not invent browse URLs.
+
+    Tries jira-cli ``me`` then acli identity-style commands. ``None`` means
+    neither CLI is available or no conclusive result.
+    """
+    tools = resolve_tool_paths(detection)
+    tried = False
+    if tools.jira:
+        tried = True
+        text = _run_text(
+            ["jira", "me", "--plain"],
+            timeout=8.0,
+            executable=tools.jira,
+        )
+        if text:
+            return True, "jira-cli:me"
+        return False, "jira-cli:me"
+    if tools.acli:
+        tried = True
+        for argv in (
+            ["acli", "jira", "auth", "status"],
+            ["acli", "jira", "me"],
+        ):
+            text = _run_text(argv, timeout=8.0, executable=tools.acli)
+            if text:
+                return True, f"acli:{argv[-1]}"
+        return False, "acli"
+    return (False, None) if tried else (None, None)
+
+
+def detect_jira_ref_link_detailed(
+    *,
+    probe_auth: bool = False,
+    detection: DetectionSettings | None = None,
+) -> JiraDetectResult:
+    """Detect a ``jira-id`` browse template; optionally probe CLI auth."""
+    tools = resolve_tool_paths(detection)
+    finders = (
+        _jira_from_config_files,
+        lambda: _jira_from_jira_cli(tools),
+        lambda: _jira_from_acli(tools),
+    )
+    for finder in finders:
+        template, source = finder()
+        if template:
+            auth_ok: bool | None = None
+            auth_source: str | None = None
+            if probe_auth:
+                auth_ok, auth_source = probe_jira_auth(detection)
+            return JiraDetectResult(
+                template=template,
+                source=source,
+                auth_ok=auth_ok,
+                auth_source=auth_source,
+            )
+    auth_ok = None
+    auth_source = None
+    if probe_auth:
+        auth_ok, auth_source = probe_jira_auth(detection)
+    return JiraDetectResult(
+        template=None,
+        source=None,
+        auth_ok=auth_ok,
+        auth_source=auth_source,
+    )
+
+
+def detect_jira_ref_link(
+    *,
+    detection: DetectionSettings | None = None,
+) -> str | None:
+    """Return a ``jira-id`` browse template from local jira CLI config if possible."""
+    return detect_jira_ref_link_detailed(probe_auth=False, detection=detection).template
+
+
+def detect_github_commit_link(*, cwd: Path | None = None) -> str | None:
+    """Prefer ``gh`` host config; fall back to origin remote when appropriate."""
+    host = _run_text(["gh", "config", "get", "host"])
+    if host and "github" in host:
+        # Repo-specific commit URL still needs remote path; leave to git remote.
+        return None
+    # ``gh repo view --json url`` needs network; skip.
+    _ = cwd
+    return None
+
+
+def detect_gitlab_commit_link() -> str | None:
+    host = _run_text(["glab", "config", "get", "host"])
+    if host and host.startswith("http"):
+        # Project path still needs git remote; host alone is not a commit template.
+        return None
+    return None
+
+
+def detect_links(
+    cwd: Path,
+    *,
+    detection: DetectionSettings | None = None,
+    git_executable: str = "git",
+) -> LinkPreferences:
+    """Discover link templates for unset preference gaps (best-effort, local)."""
+    settings = detection or DetectionSettings()
+    cli_on, git_on, _persist = settings.resolved()
+    ref_links: dict[str, str] = {}
+    commit_link: str | None = None
+
+    if cli_on:
+        jira = detect_jira_ref_link(detection=settings)
+        if jira:
+            ref_links["jira-id"] = jira
+        # gh/glab currently contribute via git remote for commit URLs.
+        detect_github_commit_link(cwd=cwd)
+        detect_gitlab_commit_link()
+
+    if git_on:
+        remote = read_origin_url(cwd, git_executable=git_executable)
+        if remote:
+            commit_link = detect_commit_link_from_remote(remote)
+
+    return LinkPreferences(ref_links=ref_links, commit_link=commit_link)
+
+
+def detect_report(
+    cwd: Path,
+    *,
+    detection: DetectionSettings | None = None,
+    git_executable: str = "git",
+    probe_auth: bool = False,
+) -> dict[str, Any]:
+    """Machine-readable detection summary for CLI / extension (no write)."""
+    settings = detection or DetectionSettings()
+    cli_on, git_on, _persist = settings.resolved()
+    tools = resolve_tool_paths(settings)
+    jira = (
+        detect_jira_ref_link_detailed(probe_auth=probe_auth, detection=settings)
+        if cli_on
+        else JiraDetectResult(None, None)
+    )
+    commit_link: str | None = None
+    commit_source: str | None = None
+    if git_on:
+        remote = read_origin_url(cwd, git_executable=git_executable)
+        if remote:
+            commit_link = detect_commit_link_from_remote(remote)
+            if commit_link:
+                commit_source = "git-remote:origin"
+
+    ref_links: dict[str, str] = {}
+    sources: dict[str, str] = {}
+    if jira.template:
+        ref_links["jira-id"] = jira.template
+        if jira.source:
+            sources["jira-id"] = jira.source
+    if commit_link:
+        sources["commitLink"] = commit_source or "git-remote:origin"
+
+    return {
+        "refLinks": ref_links,
+        "commitLink": commit_link,
+        "sources": sources,
+        "auth": {
+            "ok": jira.auth_ok,
+            "source": jira.auth_source,
+            "probed": probe_auth,
+        },
+        "tools": {
+            "jiraOnPath": bool(shutil.which("jira")),
+            "acliOnPath": bool(shutil.which("acli")),
+            "jiraResolved": tools.jira,
+            "acliResolved": tools.acli,
+            "jiraConfigured": tools.jira_configured,
+            "acliConfigured": tools.acli_configured,
+            "ghOnPath": bool(shutil.which("gh")),
+            "glabOnPath": bool(shutil.which("glab")),
+        },
+        "jiraConfigCandidates": [str(p) for p in jira_config_candidates()],
+    }
+
+
+def read_gh_host_file() -> str | None:
+    """Test helper: parse ``gh`` hosts.yml for a github.com entry."""
+    path = Path.home() / ".config" / "gh" / "hosts.yml"
+    if not path.is_file():
+        return None
+    try:
+        # Avoid requiring PyYAML; look for github.com entry.
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    if "github.com:" in text or "github.com" in text:
+        return "https://github.com"
+    return None
+
+
+def dump_detection_debug(
+    detection: DetectionSettings | None = None,
+) -> str:
+    """Return a short JSON summary of what would be detected (for CLI)."""
+    tools = resolve_tool_paths(detection)
+    return json.dumps(
+        {
+            "jiraConfigCandidates": [str(p) for p in jira_config_candidates()],
+            "ghOnPath": bool(shutil.which("gh")),
+            "glabOnPath": bool(shutil.which("glab")),
+            "jiraOnPath": bool(shutil.which("jira")),
+            "acliOnPath": bool(shutil.which("acli")),
+            "jiraResolved": tools.jira,
+            "acliResolved": tools.acli,
+            "jiraConfigured": tools.jira_configured,
+            "acliConfigured": tools.acli_configured,
+        },
+        indent=2,
+    )

{esys_gitlog-0.2.0 → esys_gitlog-0.3.0}/src/esys_gitlog/identifiers.py

@@ -10,7 +10,12 @@ _JIRA_KEY = re.compile(r"^[A-Za-z][A-Za-z0-9_]*-\d+$")
 # Subject-edge reference tokens (CADR-0005): bare id or optional square brackets.
 # Prefix may use a trailing colon instead of whitespace.
 _SUBJECT_PREFIX_REF = re.compile(r"^(?:\[)?(?P<token>[A-Za-z][A-Za-z0-9_]*-\d+)(?:\])?(?::|\s+)\s*")
-_SUBJECT_SUFFIX_REF = re.compile(r"(?:\s+|\[)(?P<token>[A-Za-z][A-Za-z0-9_]*-\d+)\]?\s*$")
+# Suffix: prefer ``[KEY-123]`` (optional space before '['), else bare `` KEY-123``.
+# Separate group names — Python ``re`` does not allow the same name in both arms.
+_SUBJECT_SUFFIX_REF = re.compile(
+    r"(?:\s*\[(?P<bracket>[A-Za-z][A-Za-z0-9_]*-\d+)\]"
+    r"|\s+(?P<bare>[A-Za-z][A-Za-z0-9_]*-\d+))\s*$"
+)
 
 # Shapes from references.md that any-id accepts beyond the Jira key.
 _ANY_EXTRA = (
@@ -61,6 +66,11 @@ def match_subject_suffix_ref(subject_line: str) -> re.Match[str] | None:
     return _SUBJECT_SUFFIX_REF.search(subject_line)
 
 
+def subject_suffix_token(match: re.Match[str]) -> str:
+    """Return the captured suffix id from a ``match_subject_suffix_ref`` match."""
+    return match.group("bracket") or match.group("bare") or ""
+
+
 def strip_subject_edge_refs(
     subject_line: str,
     *,