agex-cli 0.18.0__tar.gz → 0.20.0__tar.gz

{agex_cli-0.18.0 → agex_cli-0.20.0}/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-05-23
+
+### Changed
+
+- **Dropped the `typer` runtime dependency.** The CLI is now built on the
+  Python standard library's `argparse`, mirroring the sibling Culture repos
+  (`steward`, `devague`). This removes `typer`, `rich`, `shellingham`,
+  `annotated-doc`, `markdown-it-py`, `mdurl`, and `pygments` from the shipped
+  runtime closure (the wheel now depends only on `jinja2`, `pyyaml`,
+  `tomlkit`, and `portalocker`), shrinking the dependency-chain attack
+  surface. CLI behaviour is unchanged: every command, flag, exit code, and
+  stderr message is preserved, including the `agex explain agex`
+  unknown-command routing and the bare `--version` output.
+
+## [0.19.0] - 2026-05-23
+
+### Added
+
+- `agex pr read` (and `pr await`) now surface **Qodo code-review
+  findings** that Qodo posts inside collapsed `<details>` blocks of a
+  single top-level comment. A new `## Qodo review` section lists the
+  headline counts (🐞 Bugs / 📘 Rule violations / 📎 Requirement gaps)
+  and each finding's title + `file:line` + link, mirroring how inline
+  threads are shown. When counts are non-zero but no per-finding detail
+  could be parsed, the briefing flags it (`⚠️ N finding(s) in collapsed
+  Qodo review block — expand on GitHub`) so a bug is never silently
+  missed. Closes [#47](https://github.com/agentculture/agex-cli/issues/47).
+
+### Changed
+
+- Backend resolution accepts `claude` as an alias of `claude-code`, so
+  the AgentCulture-standard `culture.yaml` shape (`backend: claude`)
+  works with `agex pr` out of the box. When a `culture.yaml` backend is
+  genuinely unknown, the error now names the source, the offending agent
+  `suffix`, and the fix (e.g. `culture.yaml agent 'devague' has unknown
+  backend 'foo' / hint: expected one of claude (= claude-code), codex,
+  copilot, acp`). Closes [#46](https://github.com/agentculture/agex-cli/issues/46).
+
 ## [0.18.0] - 2026-05-12
 
 ### Added

{agex_cli-0.18.0 → agex_cli-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agex-cli
-Version: 0.18.0
+Version: 0.20.0
 Summary: Agent-operated developer-experience CLI — deterministic per-backend markdown briefings for autonomous agents.
 Project-URL: Homepage, https://culture.dev/agex/
 Project-URL: Repository, https://github.com/agentculture/agex-cli
@@ -13,7 +13,6 @@ Requires-Dist: jinja2>=3.1
 Requires-Dist: portalocker>=2.8
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: tomlkit>=0.12
-Requires-Dist: typer>=0.12
 Provides-Extra: dev
 Requires-Dist: bandit>=1.7; extra == 'dev'
 Requires-Dist: black>=24.0; extra == 'dev'

{agex_cli-0.18.0 → agex_cli-0.20.0}/pyproject.toml

@@ -1,13 +1,12 @@
 [project]
 name = "agex-cli"
-version = "0.18.0"
+version = "0.20.0"
 description = "Agent-operated developer-experience CLI — deterministic per-backend markdown briefings for autonomous agents."
 authors = [{name = "Ori Nachum"}]
 license = {text = "MIT"}
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
-    "typer>=0.12",
     "jinja2>=3.1",
     "pyyaml>=6.0",
     "tomlkit>=0.12",

agex_cli-0.20.0/src/agent_experience/cli.py

@@ -0,0 +1,443 @@
+"""agex CLI — stdlib argparse front end.
+
+No third-party CLI framework: this module routes `agex <command> [args]`
+through `argparse` only, mirroring the skeleton used by the sibling Culture
+repos (steward, devague). Business logic stays in `commands/<name>/scripts/`,
+which return ``(stdout, exit_code, stderr)`` tuples; this module just parses
+arguments and echoes those tuples. Adding a backend or command never touches
+the parsing core beyond a `register_*` call.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+from agent_experience import __version__
+from agent_experience.commands.doctor.scripts import doctor as doctor_script
+from agent_experience.commands.explain.scripts import explain as explain_script
+from agent_experience.commands.gamify.scripts import install as gamify_script
+from agent_experience.commands.hook.scripts import read as hook_read_script
+from agent_experience.commands.hook.scripts import write as hook_write_script
+from agent_experience.commands.learn.scripts import learn as learn_script
+from agent_experience.commands.overview.scripts import overview as overview_script
+from agent_experience.commands.pr.scripts import await_ as pr_await_script
+from agent_experience.commands.pr.scripts import delta as pr_delta_script
+from agent_experience.commands.pr.scripts import lint as pr_lint_script
+from agent_experience.commands.pr.scripts import open_ as pr_open_script
+from agent_experience.commands.pr.scripts import read as pr_read_script
+from agent_experience.commands.pr.scripts import reply as pr_reply_script
+from agent_experience.core.backend import parse_backend
+
+_GH_RERUN_HINT = "agex: rerun once network is reachable (gh failed)"
+_AGENT_HELP = "Backend: claude-code, codex, copilot, or acp."
+
+
+class _AgexArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser used everywhere via ``parser_class=``.
+
+    argparse's native ``error()`` already prints usage to stderr and exits
+    with code 2 — which matches agex's existing bad-argument behavior — so no
+    override is required. The subclass exists only so nested subparsers inherit
+    it and to give a single place for any future tweak.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Output helpers — preserve the exact newline behavior of the old typer.echo
+# calls. ``typer.echo(x, nl=False)`` wrote x verbatim; ``typer.echo(x)`` added
+# a newline; ``err=True`` selected stderr.
+# ---------------------------------------------------------------------------
+
+
+def _emit(stdout: str, stderr: str, *, stderr_newline: bool = True) -> None:
+    """Write a command's stdout/stderr the way the old CLI did."""
+    if stdout:
+        sys.stdout.write(stdout)
+    if stderr:
+        if stderr_newline:
+            print(stderr, file=sys.stderr)
+        else:
+            sys.stderr.write(stderr)
+
+
+def _parse_backend_or_report(agent: Optional[str]):
+    """Parse ``--agent`` into a Backend.
+
+    Returns ``(backend, None)`` on success, or ``(None, 2)`` after printing the
+    canonical ``agex: error: <msg>`` to stderr — letting the caller ``return``
+    the exit code without exception gymnastics.
+    """
+    try:
+        return parse_backend(agent), None
+    except ValueError as exc:
+        print(f"agex: error: {exc}", file=sys.stderr)
+        return None, 2
+
+
+# ---------------------------------------------------------------------------
+# Top-level command handlers
+# ---------------------------------------------------------------------------
+
+
+def _cmd_explain(args: argparse.Namespace) -> int:
+    stdout, exit_code, stderr = explain_script.run(args.topic)
+    _emit(stdout, stderr)
+    return exit_code
+
+
+def _cmd_doctor(args: argparse.Namespace) -> int:
+    stdout, exit_code, stderr = doctor_script.run(args.role)
+    _emit(stdout, stderr)
+    return exit_code
+
+
+def _cmd_learn(args: argparse.Namespace) -> int:
+    backend, err = _parse_backend_or_report(args.agent)
+    if err is not None:
+        return err
+    if args.topic is None:
+        stdout, exit_code, stderr = learn_script.run_menu(backend)
+    else:
+        stdout, exit_code, stderr = learn_script.run_topic(args.topic, backend)
+    _emit(stdout, stderr)
+    return exit_code
+
+
+def _cmd_gamify(args: argparse.Namespace) -> int:
+    backend, err = _parse_backend_or_report(args.agent)
+    if err is not None:
+        return err
+    if args.uninstall:
+        stdout, exit_code, stderr = gamify_script.uninstall(backend)
+    else:
+        stdout, exit_code, stderr = gamify_script.install(backend)
+    _emit(stdout, stderr)
+    return exit_code
+
+
+def _cmd_overview(args: argparse.Namespace) -> int:
+    backend, err = _parse_backend_or_report(args.agent)
+    if err is not None:
+        return err
+    stdout, exit_code, stderr = overview_script.run(backend)
+    _emit(stdout, stderr)
+    return exit_code
+
+
+# ---------------------------------------------------------------------------
+# hook subcommands
+# ---------------------------------------------------------------------------
+
+
+def _cmd_hook_write(args: argparse.Namespace) -> int:
+    _, exit_code, stderr = hook_write_script.run(args.event, args.args or [])
+    _emit("", stderr)
+    return exit_code
+
+
+def _cmd_hook_read(args: argparse.Namespace) -> int:
+    backend, err = _parse_backend_or_report(args.agent)
+    if err is not None:
+        return err
+    stdout, exit_code, stderr = hook_read_script.run(backend)
+    _emit(stdout, stderr)
+    return exit_code
+
+
+# ---------------------------------------------------------------------------
+# pr subcommands
+# ---------------------------------------------------------------------------
+
+
+def _cmd_pr_lint(args: argparse.Namespace) -> int:
+    try:
+        stdout, exit_code, stderr = pr_lint_script.run(
+            agent=args.agent, project_dir=Path.cwd(), exit_on_violation=args.exit_on_violation
+        )
+    except ValueError as exc:
+        print(f"agex: {exc}", file=sys.stderr)
+        return 2
+    _emit(stdout, stderr)
+    return exit_code
+
+
+def _cmd_pr_open(args: argparse.Namespace) -> int:
+    try:
+        stdout, exit_code, stderr = pr_open_script.run(
+            agent=args.agent,
+            project_dir=Path.cwd(),
+            title=args.title,
+            body_file=args.body_file,
+            draft=args.draft,
+            delayed_read=args.delayed_read,
+        )
+    except ValueError as exc:
+        print(f"agex: {exc}", file=sys.stderr)
+        return 2
+    except RuntimeError as exc:
+        print(str(exc), file=sys.stderr)
+        print("agex: rerun 'agex pr open ...' once network is reachable", file=sys.stderr)
+        return 1
+    _emit(stdout, stderr)
+    return exit_code
+
+
+def _cmd_pr_reply(args: argparse.Namespace) -> int:
+    try:
+        stdout, exit_code, stderr = pr_reply_script.run(
+            agent=args.agent, project_dir=Path.cwd(), pr=args.pr
+        )
+    except ValueError as exc:
+        print(f"agex: {exc}", file=sys.stderr)
+        return 2
+    except RuntimeError as exc:
+        print(str(exc), file=sys.stderr)
+        print(_GH_RERUN_HINT, file=sys.stderr)
+        return 1
+    _emit(stdout, stderr, stderr_newline=False)
+    return exit_code
+
+
+def _cmd_pr_read(args: argparse.Namespace) -> int:
+    try:
+        stdout, exit_code, stderr = pr_read_script.run(
+            agent=args.agent, project_dir=Path.cwd(), pr=args.pr, wait=args.wait
+        )
+    except ValueError as exc:
+        print(f"agex: {exc}", file=sys.stderr)
+        return 2
+    except RuntimeError as exc:
+        print(str(exc), file=sys.stderr)
+        print(_GH_RERUN_HINT, file=sys.stderr)
+        return 1
+    _emit(stdout, stderr)
+    return exit_code
+
+
+def _cmd_pr_await(args: argparse.Namespace) -> int:
+    try:
+        stdout, exit_code, stderr = pr_await_script.run(
+            agent=args.agent, project_dir=Path.cwd(), pr=args.pr, max_wait=args.max_wait
+        )
+    except ValueError as exc:
+        print(f"agex: {exc}", file=sys.stderr)
+        return 2
+    except RuntimeError as exc:
+        print(str(exc), file=sys.stderr)
+        print(_GH_RERUN_HINT, file=sys.stderr)
+        return 1
+    _emit(stdout, stderr)
+    return exit_code
+
+
+def _cmd_pr_delta(args: argparse.Namespace) -> int:
+    try:
+        stdout, exit_code, stderr = pr_delta_script.run(agent=args.agent, project_dir=Path.cwd())
+    except ValueError as exc:
+        print(f"agex: {exc}", file=sys.stderr)
+        return 2
+    except RuntimeError as exc:
+        print(str(exc), file=sys.stderr)
+        print(_GH_RERUN_HINT, file=sys.stderr)
+        return 1
+    _emit(stdout, stderr, stderr_newline=False)
+    return exit_code
+
+
+# ---------------------------------------------------------------------------
+# Parser construction
+# ---------------------------------------------------------------------------
+
+
+def _add_agent_option(parser: argparse.ArgumentParser, *, required: bool, help_text: str) -> None:
+    parser.add_argument("--agent", required=required, default=None, help=help_text)
+
+
+def _group_help(parser: argparse.ArgumentParser):
+    """Return a handler that prints a group's help to stderr and exits 2.
+
+    Mirrors Typer's ``no_args_is_help`` for ``agex hook`` / ``agex pr`` invoked
+    with no subcommand.
+    """
+
+    def _handle(_args: argparse.Namespace) -> int:
+        parser.print_help(sys.stderr)
+        return 2
+
+    return _handle
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _AgexArgumentParser(
+        prog="agex",
+        description="Agent-operated developer-experience CLI.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", parser_class=_AgexArgumentParser)
+
+    # explain
+    p_explain = sub.add_parser("explain", help="Describe a command or concept.")
+    p_explain.add_argument("topic", help="Topic to explain.")
+    p_explain.set_defaults(func=_cmd_explain)
+
+    # doctor
+    p_doctor = sub.add_parser("doctor", help="Diagnose the project's agex setup.")
+    p_doctor.add_argument(
+        "--role", default=None, help="Render a role-specific check section (e.g., pr-review)."
+    )
+    p_doctor.set_defaults(func=_cmd_doctor)
+
+    # learn
+    p_learn = sub.add_parser("learn", help="Teach a lesson topic (or show the menu).")
+    p_learn.add_argument("topic", nargs="?", default=None, help="Lesson topic (omit for menu).")
+    _add_agent_option(p_learn, required=True, help_text=_AGENT_HELP)
+    p_learn.set_defaults(func=_cmd_learn)
+
+    # gamify
+    p_gamify = sub.add_parser("gamify", help="Install (or uninstall) gamification.")
+    _add_agent_option(p_gamify, required=True, help_text=_AGENT_HELP)
+    p_gamify.add_argument("--uninstall", action="store_true", help="Reverse gamify.")
+    p_gamify.set_defaults(func=_cmd_gamify)
+
+    # overview
+    p_overview = sub.add_parser("overview", help="Render the per-backend overview briefing.")
+    _add_agent_option(p_overview, required=True, help_text=_AGENT_HELP)
+    p_overview.set_defaults(func=_cmd_overview)
+
+    _register_hook(sub)
+    _register_pr(sub)
+
+    return parser
+
+
+def _register_hook(sub: argparse._SubParsersAction) -> None:
+    hook_p = sub.add_parser("hook", help="Write and read agex tracking events.")
+    hook_sub = hook_p.add_subparsers(dest="hook_command", parser_class=_AgexArgumentParser)
+
+    p_write = hook_sub.add_parser("write", help="Append a tracking event.")
+    p_write.add_argument("event", help="Event name (e.g., post-tool-use).")
+    p_write.add_argument("args", nargs="*", help="Additional key=value pairs.")
+    p_write.set_defaults(func=_cmd_hook_write)
+
+    p_read = hook_sub.add_parser("read", help="Render tracked events for a backend.")
+    _add_agent_option(p_read, required=True, help_text=_AGENT_HELP)
+    p_read.set_defaults(func=_cmd_hook_read)
+
+    hook_p.set_defaults(func=_group_help(hook_p))
+
+
+def _register_pr(sub: argparse._SubParsersAction) -> None:
+    pr_p = sub.add_parser("pr", help="GitHub PR lifecycle commands.")
+    pr_sub = pr_p.add_subparsers(dest="pr_command", parser_class=_AgexArgumentParser)
+
+    p_lint = pr_sub.add_parser("lint", help="Lint the PR branch state.")
+    _add_agent_option(
+        p_lint,
+        required=False,
+        help_text="Backend (claude-code|codex|copilot|acp); falls back to culture.yaml.",
+    )
+    p_lint.add_argument(
+        "--exit-on-violation",
+        action="store_true",
+        help="Exit 1 when violations are found (CI mode).",
+    )
+    p_lint.set_defaults(func=_cmd_pr_lint)
+
+    p_open = pr_sub.add_parser("open", help="Open a PR.")
+    p_open.add_argument("--title", required=True)
+    p_open.add_argument("--body-file", type=Path, default=None)
+    p_open.add_argument("--draft", action="store_true", default=False)
+    _add_agent_option(p_open, required=False, help_text=_AGENT_HELP)
+    p_open.add_argument(
+        "--delayed-read",
+        action="store_true",
+        default=False,
+        help="After create, immediately run `pr read --wait 180`.",
+    )
+    p_open.set_defaults(func=_cmd_pr_open)
+
+    p_reply = pr_sub.add_parser("reply", help="Reply to PR review threads.")
+    p_reply.add_argument("pr", type=int)
+    _add_agent_option(p_reply, required=False, help_text=_AGENT_HELP)
+    p_reply.set_defaults(func=_cmd_pr_reply)
+
+    p_read = pr_sub.add_parser("read", help="Read PR review state.")
+    p_read.add_argument("pr", type=int, nargs="?", default=None)
+    p_read.add_argument(
+        "--wait", type=int, default=None, help="Poll for readiness up to SECS seconds."
+    )
+    _add_agent_option(p_read, required=False, help_text=_AGENT_HELP)
+    p_read.set_defaults(func=_cmd_pr_read)
+
+    p_await = pr_sub.add_parser(
+        "await",
+        help="Wake-me-when-triage-able combo verb.",
+        description=(
+            "Polls readiness, runs CI + Sonar gate, renders briefing. Exits "
+            "non-zero on quality-gate ERROR or unresolved review threads."
+        ),
+    )
+    p_await.add_argument("pr", type=int, nargs="?", default=None)
+    p_await.add_argument(
+        "--max-wait",
+        type=int,
+        default=1800,
+        help="Poll for readiness up to SECS seconds (default 1800).",
+    )
+    _add_agent_option(p_await, required=False, help_text=_AGENT_HELP)
+    p_await.set_defaults(func=_cmd_pr_await)
+
+    p_delta = pr_sub.add_parser("delta", help="Show the delta since the last PR read.")
+    _add_agent_option(p_delta, required=False, help_text=_AGENT_HELP)
+    p_delta.set_defaults(func=_cmd_pr_delta)
+
+    pr_p.set_defaults(func=_group_help(pr_p))
+
+
+# ---------------------------------------------------------------------------
+# Dispatch + entrypoint
+# ---------------------------------------------------------------------------
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    rc = args.func(args)
+    return rc if rc is not None else 0
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if getattr(args, "func", None) is None:
+        # No top-level command given — mirror Typer's no_args_is_help (exit 2).
+        parser.print_help(sys.stderr)
+        return 2
+    return _dispatch(args)
+
+
+# Keep in sync with the sub.add_parser registrations above.
+# If a new top-level command is added, extend this set so _main_entrypoint
+# stops routing it to the unknown-command fallback page.
+_KNOWN_COMMANDS = {"explain", "overview", "learn", "gamify", "hook", "doctor", "pr"}
+
+
+def _main_entrypoint() -> None:
+    """CLI entry point that routes unknown subcommands to ``agex explain agex``.
+
+    When the first positional argument is not a known command (and is not a
+    flag), print the ``agex explain agex`` page to stdout and the canonical
+    error message to stderr, then exit with code 2.  All other invocations —
+    known commands, ``--version``, ``--help``, zero-arg help — fall through to
+    the normal ``main()`` dispatch unchanged.
+    """
+    argv = sys.argv[1:]
+    if argv and not argv[0].startswith("-") and argv[0] not in _KNOWN_COMMANDS:
+        print(f"agex: error: unknown command '{argv[0]}'", file=sys.stderr)
+        stdout, _, _ = explain_script.run("agex")
+        sys.stdout.write(stdout)
+        sys.exit(2)
+    sys.exit(main())
+
+
+if __name__ == "__main__":
+    _main_entrypoint()

{agex_cli-0.18.0 → agex_cli-0.20.0}/src/agent_experience/commands/pr/assets/templates/pr_briefing.md.j2

@@ -42,6 +42,22 @@ _No comments yet._
 {% endfor %}
 {%- endif %}
 
+## Qodo review
+
+{% if not qodo -%}
+_No Qodo review found._
+{%- else -%}
+🐞 Bugs: **{{ qodo.counts.bugs }}** · 📘 Rule violations: **{{ qodo.counts.rule_violations }}** · 📎 Requirement gaps: **{{ qodo.counts.requirement_gaps }}**
+{% if qodo.findings -%}
+{% for f in qodo.findings -%}
+- {{ f.title or "(untitled finding)" }}{% if f.path %} — `{{ f.path }}{% if f.line %}:{{ f.line }}{% endif %}`{% endif %}{% if f.link %} ([link]({{ f.link }})){% endif %}
+{% endfor %}
+{%- endif %}
+{% if qodo.total > 0 and not qodo.findings -%}
+> ⚠️ {{ qodo.total }} finding(s) in collapsed Qodo review block — expand on GitHub{% if qodo.url %} {{ qodo.url }}{% endif %}
+{%- endif %}
+{%- endif %}
+
 ## Readiness
 
 {% if waiting_for -%}

agex_cli-0.20.0/src/agent_experience/commands/pr/scripts/_qodo.py

@@ -0,0 +1,147 @@
+"""Parse Qodo (``qodo-code-review[bot]``) "Code Review by Qodo" comments.
+
+Qodo posts its code review as a single top-level issue comment whose body is
+HTML containing collapsed ``<details>`` blocks — one per finding, each itself
+holding nested ``<details>`` for Description / Code / Evidence / Agent prompt.
+``agex pr read`` would otherwise render this comment truncated to 200 chars,
+hiding the findings (and any real bug) entirely.
+
+This module extracts the headline counts and, where possible, each finding's
+title + ``file:line`` + permalink so the briefing can surface them the way it
+surfaces inline review threads.  It is deliberately defensive: malformed or
+partial HTML yields whatever is parseable and the public ``parse`` never raises.
+
+Stdlib only (``re`` + ``html``) — the project ships no HTML-parsing dependency.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+from typing import Any
+
+_QODO_MARKER = "Code Review by Qodo"
+
+# Headline counts: <code>🐞 Bugs (3)</code>  <code>📘 Rule violations (1)</code>
+# <code>📎 Requirement gaps (0)</code>.  Emoji-agnostic; matches label + integer.
+_COUNT_RE = re.compile(
+    r"<code>[^<]*?(Bugs|Rule violations|Requirement gaps)\s*\((\d+)\)",
+    re.IGNORECASE,
+)
+
+_COUNT_KEYS = {
+    "bugs": "bugs",
+    "rule violations": "rule_violations",
+    "requirement gaps": "requirement_gaps",
+}
+
+# Each finding is introduced by a <summary> whose (tag-stripped) text starts
+# with an ordinal, e.g. "1. Orphan honesty rendered ...".  Nested Description /
+# Code / Evidence / Agent-prompt summaries do not start with a digit, so they
+# are not mistaken for findings — which sidesteps the nested-<details> problem.
+_SUMMARY_RE = re.compile(r"<summary\b[^>]*>(.*?)</summary>", re.IGNORECASE | re.DOTALL)
+_FINDING_TITLE_RE = re.compile(r"^\d+[.)]\s")
+
+# Qodo's "Code" location, a markdown link with a bracketed line range:
+#   [devague/render/spec_md.py[R44-49]](https://github.com/.../files#diff-…R44-R49)
+_CODE_LINK_RE = re.compile(
+    r"\[([^\[\]\n]+?)\[([RLrl]?\d+(?:-[RLrl]?\d+)?)\]\]\((https?://[^)\s]+)\)"
+)
+
+# Fallback: a bare GitHub blob permalink (used in the Evidence section):
+#   https://github.com/owner/repo/blob/<sha>/<path>#L42-L55  (trailing / tolerated)
+_PERMALINK_RE = re.compile(
+    r"https://github\.com/\S+?/blob/[0-9a-fA-F]+/"
+    r"(?P<path>[^#\s\"'<>)\]]+?)/?"
+    r"(?:#L(?P<start>\d+)(?:-L(?P<end>\d+))?)?(?=[\s\"'<>)\]]|$)"
+)
+
+_TAG_RE = re.compile(r"<[^>]+>")
+_WS_RE = re.compile(r"\s+")
+
+
+def _strip_tags(fragment: str) -> str:
+    text = _TAG_RE.sub(" ", fragment)
+    text = html.unescape(text)
+    return _WS_RE.sub(" ", text).strip()
+
+
+def _find_qodo_comment(comments: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """Return the "Code Review by Qodo" summary comment, or None."""
+    for c in comments:
+        if _QODO_MARKER in (c.get("body") or ""):
+            return c
+    return None
+
+
+def parse_counts(body: str) -> dict[str, int]:
+    counts = {"bugs": 0, "rule_violations": 0, "requirement_gaps": 0}
+    for label, n in _COUNT_RE.findall(body):
+        key = _COUNT_KEYS.get(label.lower())
+        if key:
+            counts[key] = int(n)
+    return counts
+
+
+def _extract_location(span: str) -> tuple[str | None, str | None, str | None]:
+    """Return (path, line, link) for the first location in a finding span."""
+    m = _CODE_LINK_RE.search(span)
+    if m:
+        path = m.group(1).strip()
+        line = re.sub(r"[RLrl]", "", m.group(2))
+        return path, line, m.group(3)
+    m = _PERMALINK_RE.search(span)
+    if m:
+        path = m.group("path").rstrip("/")
+        start, end = m.group("start"), m.group("end")
+        line = None
+        if start:
+            line = f"{start}-{end}" if end else start
+        return path, line, m.group(0)
+    return None, None, None
+
+
+def parse_findings(body: str) -> list[dict[str, Any]]:
+    summaries = list(_SUMMARY_RE.finditer(body))
+    title_idxs = [
+        i for i, m in enumerate(summaries) if _FINDING_TITLE_RE.match(_strip_tags(m.group(1)))
+    ]
+    findings: list[dict[str, Any]] = []
+    for n, idx in enumerate(title_idxs):
+        # Title = the summary text up to the first <code> status/type badge.
+        head = summaries[idx].group(1).split("<code>")[0]
+        title = _strip_tags(head)
+        span_start = summaries[idx].end()
+        span_end = summaries[title_idxs[n + 1]].start() if n + 1 < len(title_idxs) else len(body)
+        path, line, link = _extract_location(body[span_start:span_end])
+        if not title and not path:
+            continue
+        findings.append({"title": title, "path": path, "line": line, "link": link})
+    return findings
+
+
+def parse(comments: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """Return ``{counts, total, findings, url}`` for the Qodo summary comment,
+    or ``None`` *only* when no such comment is present.
+
+    Once a Qodo comment is found this always returns a dict (with safe
+    defaults), so a parsing hiccup degrades to "0 findings" / the collapsed
+    warning rather than the misleading ``_No Qodo review found._``.  ``counts``
+    and ``findings`` are parsed independently so a partial failure still
+    surfaces whatever was recoverable.  Never raises.
+    """
+    comment = _find_qodo_comment(comments)
+    if comment is None:
+        return None
+    body = comment.get("body") or ""
+    try:
+        counts = parse_counts(body)
+    except Exception:  # pragma: no cover - defensive
+        counts = {"bugs": 0, "rule_violations": 0, "requirement_gaps": 0}
+    try:
+        findings = parse_findings(body)
+    except Exception:  # pragma: no cover - defensive
+        findings = []
+    total = counts["bugs"] + counts["rule_violations"] + counts["requirement_gaps"]
+    url = comment.get("html_url") or next((f["link"] for f in findings if f.get("link")), None)
+    return {"counts": counts, "total": total, "findings": findings, "url": url}