plugin-scanner 2.0.5__tar.gz → 2.0.6__tar.gz

{plugin_scanner-2.0.5 → plugin_scanner-2.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.5
+Version: 2.0.6
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://github.com/hashgraph-online/ai-plugin-scanner
 Project-URL: Repository, https://github.com/hashgraph-online/ai-plugin-scanner
@@ -63,8 +63,7 @@ Description-Content-Type: text/markdown
 ## Guard Quickstart
 
 ```bash
-pipx run hol-guard start
-pipx run hol-guard install codex
+pipx run hol-guard bootstrap
 pipx run hol-guard run codex --dry-run
 pipx run hol-guard run codex
 pipx run hol-guard approvals
@@ -87,6 +86,8 @@ See [docs/guard/get-started.md](docs/guard/get-started.md) for the full local fl
 
 - `hol-guard start`
   Shows the next step for the harnesses Guard found.
+- `hol-guard bootstrap`
+  Detects the best local harness, starts the approval center, and installs Guard in front of it.
 - `hol-guard status`
   Shows what Guard is watching now.
 - `hol-guard install <harness>`
@@ -195,7 +196,13 @@ Scanner package:
 pip install plugin-scanner
 ```
 
-Cisco skill scanning support is included in the default `plugin-scanner` install (via `cisco-ai-skill-scanner`).
+Cisco-backed scanner analysis is optional:
+
+```bash
+pip install "plugin-scanner[cisco]"
+```
+
+The `cisco` extra installs the published `cisco-ai-skill-scanner` package from PyPI so the scanner remains publishable on PyPI and the optional Cisco analysis path works with standard package metadata.
 
 If you want both tools in one shell during local development:
 

{plugin_scanner-2.0.5 → plugin_scanner-2.0.6}/README.md

@@ -26,8 +26,7 @@
 ## Guard Quickstart
 
 ```bash
-pipx run hol-guard start
-pipx run hol-guard install codex
+pipx run hol-guard bootstrap
 pipx run hol-guard run codex --dry-run
 pipx run hol-guard run codex
 pipx run hol-guard approvals
@@ -50,6 +49,8 @@ See [docs/guard/get-started.md](docs/guard/get-started.md) for the full local fl
 
 - `hol-guard start`
   Shows the next step for the harnesses Guard found.
+- `hol-guard bootstrap`
+  Detects the best local harness, starts the approval center, and installs Guard in front of it.
 - `hol-guard status`
   Shows what Guard is watching now.
 - `hol-guard install <harness>`
@@ -158,7 +159,13 @@ Scanner package:
 pip install plugin-scanner
 ```
 
-Cisco skill scanning support is included in the default `plugin-scanner` install (via `cisco-ai-skill-scanner`).
+Cisco-backed scanner analysis is optional:
+
+```bash
+pip install "plugin-scanner[cisco]"
+```
+
+The `cisco` extra installs the published `cisco-ai-skill-scanner` package from PyPI so the scanner remains publishable on PyPI and the optional Cisco analysis path works with standard package metadata.
 
 If you want both tools in one shell during local development:
 

{plugin_scanner-2.0.5 → plugin_scanner-2.0.6}/docs/guard/get-started.md

@@ -10,10 +10,10 @@ Use it when you want to protect a harness before local MCP servers, skills, hook
 1. See what Guard found:
 
    ```bash
-   hol-guard start
+   hol-guard bootstrap
    ```
 
-2. Install Guard in front of the harness you use most:
+2. If you prefer the manual path, install Guard in front of the harness you use most:
 
    ```bash
    hol-guard install codex

{plugin_scanner-2.0.5 → plugin_scanner-2.0.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.5"
+version = "2.0.6"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.5 → plugin_scanner-2.0.6}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.5"
+version = "2.0.6"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.5 → plugin_scanner-2.0.6}/src/codex_plugin_scanner/action_runner.py

@@ -7,9 +7,19 @@ import json
 import os
 import sys
 from pathlib import Path
+from urllib.error import HTTPError, URLError
 
 from . import __version__
 from .cli import _build_plain_text, _build_verification_text, _scan_with_policy
+from .config import ConfigError, load_scanner_config
+from .github_reporting import (
+    build_scan_pr_comment_body,
+    build_verify_pr_comment_body,
+    load_pull_request_number,
+    resolve_pr_comment_config,
+    should_manage_pr_comment,
+    upsert_pr_comment,
+)
 from .models import GRADE_LABELS, max_severity
 from .quality_artifact import build_quality_artifact, write_quality_artifact
 from .reporting import build_json_payload, format_markdown, format_sarif, should_fail_for_severity
@@ -40,6 +50,15 @@ def _read_env(name: str, default: str = "") -> str:
     return os.environ.get(name, default)
 
 
+def _read_positive_int_env(name: str, *, default: int) -> int:
+    raw = _read_env(name, str(default)).strip()
+    try:
+        value = int(raw)
+    except ValueError:
+        return default
+    return value if value > 0 else default
+
+
 def _write_outputs(path: str, values: dict[str, str]) -> None:
     with Path(path).open("a", encoding="utf-8") as handle:
         for key, value in values.items():
@@ -52,6 +71,30 @@ def _write_step_summary(path: str, lines: tuple[str, ...]) -> None:
         handle.write("\n")
 
 
+def _resolve_pr_comment_settings(
+    *,
+    plugin_dir: str,
+    config_path: str,
+) -> tuple[str, str, int]:
+    config = None
+    try:
+        config = load_scanner_config(Path(plugin_dir).resolve(), config_path or None)
+    except ConfigError as error:
+        print(f"Warning: failed to load scanner config for PR comment settings: {error}", file=sys.stderr)
+    pr_comment = resolve_pr_comment_config(
+        default_mode=_read_env("PR_COMMENT", "auto"),
+        default_style=_read_env("PR_COMMENT_STYLE", "concise"),
+        default_max_findings=_read_positive_int_env(
+            "PR_COMMENT_MAX_FINDINGS",
+            default=5,
+        ),
+        configured_mode=config.github_pr_comment if config is not None else None,
+        configured_style=config.github_pr_comment_style if config is not None else None,
+        configured_max_findings=config.github_pr_comment_max_findings if config is not None else None,
+    )
+    return pr_comment.mode, pr_comment.style, pr_comment.max_findings
+
+
 def _build_scan_args(
     *,
     plugin_dir: str,
@@ -202,6 +245,14 @@ def main() -> int:
     github_sha = _read_env("GITHUB_SHA")
     github_run_id = _read_env("GITHUB_RUN_ID")
     github_api_url = _read_env("GITHUB_API_URL", "https://api.github.com")
+    github_token = _read_env("GITHUB_TOKEN")
+    github_event_name = _read_env("GITHUB_EVENT_NAME")
+    github_event_path = _read_env("GITHUB_EVENT_PATH")
+    pr_comment_mode, pr_comment_style, pr_comment_max_findings = _resolve_pr_comment_settings(
+        plugin_dir=plugin_dir,
+        config_path=config,
+    )
+    pull_request_number = load_pull_request_number(github_event_path) if github_event_path else None
 
     workflow_url = ""
     if github_repository and github_run_id:
@@ -235,8 +286,58 @@ def main() -> int:
     scan_scope = "plugin"
     local_plugin_count: int | None = None
     skipped_target_count: int | None = None
+    pr_comment_body = ""
 
     def finish(return_code: int) -> int:
+        output_values["report_path"] = report_path_value
+        output_values["registry_payload_path"] = registry_payload_path_value
+        if pr_comment_mode == "off":
+            output_values["pr_comment_status"] = "disabled"
+        elif should_manage_pr_comment(
+            mode=pr_comment_mode,
+            event_name=github_event_name,
+            pull_request_number=pull_request_number,
+        ):
+            if github_repository and github_token and pr_comment_body:
+                try:
+                    pr_comment_result = upsert_pr_comment(
+                        repository=github_repository,
+                        pull_request_number=pull_request_number if pull_request_number is not None else 0,
+                        token=github_token,
+                        api_base_url=github_api_url,
+                        body=pr_comment_body,
+                    )
+                    output_values["pr_comment_status"] = pr_comment_result.status
+                    output_values["pr_comment_id"] = pr_comment_result.comment_id
+                    output_values["pr_comment_url"] = pr_comment_result.comment_url
+                except (HTTPError, URLError, RuntimeError) as error:
+                    print(f"Warning: failed to update PR comment: {error}", file=sys.stderr)
+                    output_values["pr_comment_status"] = "failed"
+            else:
+                output_values["pr_comment_status"] = "skipped"
+        else:
+            output_values["pr_comment_status"] = "skipped"
+        step_summary_path = _read_env("GITHUB_STEP_SUMMARY")
+        if write_step_summary and step_summary_path:
+            _write_step_summary(
+                step_summary_path,
+                _build_step_summary_lines(
+                    mode=mode,
+                    score=output_values["score"],
+                    grade=output_values["grade"],
+                    grade_label=output_values["grade_label"],
+                    max_severity=output_values["max_severity"] or "none",
+                    findings_total=output_values["findings_total"],
+                    report_path=report_path_value,
+                    registry_payload_path=registry_payload_path_value,
+                    submission_issues=submission_issues,
+                    submission_eligible=submission_eligible,
+                    verify_pass=verify_pass_for_summary,
+                    scope=scan_scope,
+                    local_plugin_count=local_plugin_count,
+                    skipped_target_count=skipped_target_count,
+                ),
+            )
         output_values["action_exit_code"] = str(return_code)
         github_output = _read_env("GITHUB_OUTPUT")
         if github_output:
@@ -279,6 +380,13 @@ def main() -> int:
                 policy_pass=policy_eval.policy_pass,
                 raw_score=raw_result.score,
             )
+            pr_comment_body = build_scan_pr_comment_body(
+                result=result,
+                profile=resolved_profile,
+                policy_pass=policy_eval.policy_pass,
+                style=pr_comment_style,
+                max_findings_to_render=pr_comment_max_findings,
+            )
         elif mode == "lint":
             rendered = _render_lint_output(
                 result,
@@ -286,6 +394,13 @@ def main() -> int:
                 profile=resolved_profile,
                 policy_pass=policy_eval.policy_pass,
             )
+            pr_comment_body = build_scan_pr_comment_body(
+                result=result,
+                profile=resolved_profile,
+                policy_pass=policy_eval.policy_pass,
+                style=pr_comment_style,
+                max_findings_to_render=pr_comment_max_findings,
+            )
         else:
             if scan_scope != "plugin":
                 print(
@@ -431,6 +546,12 @@ def main() -> int:
         if scan_scope == "repository":
             local_plugin_count = len(verification.plugin_results)
             skipped_target_count = len(verification.skipped_targets)
+        verification_payload = build_verification_payload(verification)
+        pr_comment_body = build_verify_pr_comment_body(
+            verification_payload=verification_payload,
+            style=pr_comment_style,
+            max_findings_to_render=pr_comment_max_findings,
+        )
         rendered = _render_verify_output(verification, output_format=output_format)
         verify_pass_for_summary = verification.verify_pass
         if output_path:
@@ -447,31 +568,6 @@ def main() -> int:
         print(f"Unsupported mode: {mode}", file=sys.stderr)
         return finish(1)
 
-    output_values["report_path"] = report_path_value
-    output_values["registry_payload_path"] = registry_payload_path_value
-
-    step_summary_path = _read_env("GITHUB_STEP_SUMMARY")
-    if write_step_summary and step_summary_path:
-        _write_step_summary(
-            step_summary_path,
-            _build_step_summary_lines(
-                mode=mode,
-                score=output_values["score"],
-                grade=output_values["grade"],
-                grade_label=output_values["grade_label"],
-                max_severity=output_values["max_severity"] or "none",
-                findings_total=output_values["findings_total"],
-                report_path=report_path_value,
-                registry_payload_path=registry_payload_path_value,
-                submission_issues=submission_issues,
-                submission_eligible=submission_eligible,
-                verify_pass=verify_pass_for_summary,
-                scope=scan_scope,
-                local_plugin_count=local_plugin_count,
-                skipped_target_count=skipped_target_count,
-            ),
-        )
-
     if mode == "verify":
         return finish(return_code)
     return finish(0)

{plugin_scanner-2.0.5 → plugin_scanner-2.0.6}/src/codex_plugin_scanner/config.py

@@ -19,6 +19,9 @@ class ScannerConfig:
     baseline_file: str | None = None
     severity_overrides: dict[str, str] | None = None
     ignore_paths: tuple[str, ...] = ()
+    github_pr_comment: str | None = None
+    github_pr_comment_style: str | None = None
+    github_pr_comment_max_findings: int | None = None
 
 
 DEFAULT_CONFIG_FILES = (".plugin-scanner.toml", ".codex-plugin-scanner.toml")
@@ -45,8 +48,15 @@ def load_scanner_config(plugin_dir: Path, config_path: str | None = None) -> Sca
     except Exception as exc:  # pragma: no cover - parser-specific errors
         raise ConfigError(f"Failed to parse config '{candidate}': {exc}") from exc
 
-    scanner = payload.get("scanner", {})
-    rules = payload.get("rules", {})
+    scanner_value = payload.get("scanner", {})
+    scanner = scanner_value if isinstance(scanner_value, dict) else {}
+    rules_value = payload.get("rules", {})
+    rules = rules_value if isinstance(rules_value, dict) else {}
+    github_value = payload.get("github", {})
+    github = github_value if isinstance(github_value, dict) else {}
+    github_pr_comment_max_findings = github.get("pr_comment_max_findings")
+    if not isinstance(github_pr_comment_max_findings, int):
+        github_pr_comment_max_findings = None
 
     return ScannerConfig(
         profile=scanner.get("profile"),
@@ -55,6 +65,11 @@ def load_scanner_config(plugin_dir: Path, config_path: str | None = None) -> Sca
         baseline_file=scanner.get("baseline_file"),
         severity_overrides={str(k): str(v) for k, v in rules.get("severity_overrides", {}).items()},
         ignore_paths=tuple(str(path) for path in scanner.get("ignore_paths", [])),
+        github_pr_comment=github.get("pr_comment") if isinstance(github.get("pr_comment"), str) else None,
+        github_pr_comment_style=github.get("pr_comment_style")
+        if isinstance(github.get("pr_comment_style"), str)
+        else None,
+        github_pr_comment_max_findings=github_pr_comment_max_findings,
     )
 
 

plugin_scanner-2.0.6/src/codex_plugin_scanner/github_reporting.py

@@ -0,0 +1,326 @@
+"""GitHub pull request reporting helpers for repo-side Guard workflows."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import parse_qsl, quote, urlencode, urlsplit, urlunsplit
+from urllib.request import Request, urlopen
+
+from .models import GRADE_LABELS, Finding, ScanResult, max_severity
+
+REQUEST_TIMEOUT_SECONDS = 30
+PR_COMMENT_MARKER = "<!-- hol-guard-pr-comment -->"
+VALID_PR_COMMENT_MODES = frozenset({"auto", "always", "off"})
+VALID_PR_COMMENT_STYLES = frozenset({"concise", "detailed"})
+
+
+@dataclass(frozen=True, slots=True)
+class GitHubPrCommentConfig:
+    mode: str
+    style: str
+    max_findings: int
+
+
+@dataclass(frozen=True, slots=True)
+class GitHubPrCommentResult:
+    status: str
+    comment_id: str = ""
+    comment_url: str = ""
+
+
+def resolve_pr_comment_config(
+    *,
+    default_mode: str,
+    default_style: str,
+    default_max_findings: int,
+    configured_mode: str | None,
+    configured_style: str | None,
+    configured_max_findings: int | None,
+) -> GitHubPrCommentConfig:
+    mode = default_mode if default_mode in VALID_PR_COMMENT_MODES else "auto"
+    if default_mode == "auto" and configured_mode in VALID_PR_COMMENT_MODES:
+        mode = configured_mode
+    style = default_style if default_style in VALID_PR_COMMENT_STYLES else "concise"
+    if default_style == "concise" and configured_style in VALID_PR_COMMENT_STYLES:
+        style = configured_style
+    max_findings = default_max_findings if default_max_findings > 0 else 5
+    if default_max_findings == 5 and configured_max_findings is not None and configured_max_findings > 0:
+        max_findings = configured_max_findings
+    return GitHubPrCommentConfig(mode=mode, style=style, max_findings=max_findings)
+
+
+def load_pull_request_number(event_path: str) -> int | None:
+    try:
+        payload = json.loads(Path(event_path).read_text(encoding="utf-8"))
+    except OSError:
+        return None
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(payload, dict):
+        return None
+    pull_request = payload.get("pull_request")
+    if isinstance(pull_request, dict):
+        number = pull_request.get("number")
+        if isinstance(number, int):
+            return number
+    issue = payload.get("issue")
+    if isinstance(issue, dict) and isinstance(issue.get("pull_request"), dict):
+        number = issue.get("number")
+        if isinstance(number, int):
+            return number
+    return None
+
+
+def should_manage_pr_comment(
+    *,
+    mode: str,
+    event_name: str,
+    pull_request_number: int | None,
+) -> bool:
+    if mode == "off":
+        return False
+    if pull_request_number is None:
+        return False
+    if mode == "always":
+        return True
+    return event_name in {"pull_request", "pull_request_target"}
+
+
+def build_scan_pr_comment_body(
+    *,
+    result: ScanResult,
+    profile: str,
+    policy_pass: bool,
+    style: str,
+    max_findings_to_render: int,
+) -> str:
+    guard_status = "pass" if policy_pass else "blocked"
+    severity = max_severity(result.findings)
+    severity_label = severity.value if severity is not None else "none"
+    grade_label = GRADE_LABELS.get(result.grade, "Unknown")
+    lines = [
+        PR_COMMENT_MARKER,
+        "## Guard repo scan",
+        "",
+        f"- Verdict: `{guard_status}`",
+        f"- Score: `{result.score}/100` ({result.grade} - {grade_label})",
+        f"- Policy profile: `{profile}`",
+        f"- Max severity: `{severity_label}`",
+        f"- Findings: `{sum(result.severity_counts.values())}`",
+    ]
+    if result.scope == "repository":
+        lines.append(f"- Local plugin targets: `{len(result.plugin_results)}`")
+        lines.append(f"- Skipped marketplace entries: `{len(result.skipped_targets)}`")
+    if style == "detailed":
+        findings_to_render = tuple(result.findings[:max_findings_to_render])
+        lines.extend(_render_findings_section(findings_to_render, max_findings_to_render, len(result.findings)))
+    return "\n".join(lines)
+
+
+def build_verify_pr_comment_body(
+    *,
+    verification_payload: dict[str, object],
+    style: str,
+    max_findings_to_render: int,
+) -> str:
+    verify_pass = bool(verification_payload.get("verify_pass"))
+    status = "pass" if verify_pass else "blocked"
+    cases = verification_payload.get("cases", [])
+    case_items = cases if isinstance(cases, list) else []
+    lines = [
+        PR_COMMENT_MARKER,
+        "## Guard verification",
+        "",
+        f"- Verdict: `{status}`",
+        f"- Checks: `{len(case_items)}`",
+    ]
+    if style == "detailed":
+        for case in case_items[:max_findings_to_render]:
+            if not isinstance(case, dict):
+                continue
+            component = str(case.get("component") or "unknown")
+            name = str(case.get("name") or "unnamed")
+            message = str(case.get("message") or "")
+            icon = "✅" if bool(case.get("passed")) else "⚠️"
+            lines.append(f"- {icon} `{component}` {name}: {message}")
+    return "\n".join(lines)
+
+
+def upsert_pr_comment(
+    *,
+    repository: str,
+    pull_request_number: int,
+    token: str,
+    api_base_url: str,
+    body: str,
+) -> GitHubPrCommentResult:
+    comments_url = _repo_comments_url(
+        api_base_url=api_base_url,
+        repository=repository,
+        pull_request_number=pull_request_number,
+    )
+    comments = _list_pr_comments(comments_url, token)
+    existing_comment = _find_existing_pr_comment(comments)
+    if existing_comment is None:
+        created_comment = _request_json("POST", comments_url, token, {"body": body})
+        return _parse_comment_result(created_comment, status="created")
+    comment_id = existing_comment.get("id")
+    existing_body = existing_comment.get("body")
+    if isinstance(existing_body, str) and existing_body == body and isinstance(comment_id, int):
+        return _parse_comment_result(existing_comment, status="unchanged")
+    if not isinstance(comment_id, int):
+        raise RuntimeError("GitHub comment response is missing an id.")
+    updated_comment = _request_json(
+        "PATCH",
+        _repo_comment_url(api_base_url=api_base_url, repository=repository, comment_id=comment_id),
+        token,
+        {"body": body},
+    )
+    return _parse_comment_result(updated_comment, status="updated")
+
+
+def _list_pr_comments(
+    comments_url: str,
+    token: str,
+) -> list[dict[str, object]]:
+    comments: list[dict[str, object]] = []
+    next_url: str | None = _url_with_query_value(comments_url, "per_page", "100")
+    while next_url is not None:
+        payload, link_header = _request_json_with_headers("GET", next_url, token)
+        if not isinstance(payload, list):
+            raise RuntimeError("GitHub comment lookup returned an unexpected response.")
+        comments.extend(payload)
+        next_url = _next_link_url(link_header)
+    return comments
+
+
+def _render_findings_section(
+    findings: tuple[Finding, ...],
+    max_findings_to_render: int,
+    total_findings: int,
+) -> list[str]:
+    lines = ["", "### Top findings"]
+    if not findings:
+        lines.append("- No findings.")
+        return lines
+    for finding in findings:
+        location = ""
+        if finding.file_path is not None:
+            line_suffix = f":{finding.line_number}" if finding.line_number is not None else ""
+            location = f" in `{finding.file_path}{line_suffix}`"
+        lines.append(f"- `{finding.severity.value}` {finding.title}{location}")
+    if total_findings > max_findings_to_render:
+        lines.append(f"- …and {total_findings - max_findings_to_render} more.")
+    return lines
+
+
+def _request_json(
+    method: str,
+    url: str,
+    token: str,
+    payload: dict[str, object] | None = None,
+) -> dict[str, object] | list[dict[str, object]]:
+    data = None if payload is None else json.dumps(payload).encode("utf-8")
+    request = Request(url, data=data, method=method)
+    request.add_header("Accept", "application/vnd.github+json")
+    request.add_header("Authorization", f"Bearer {token}")
+    request.add_header("User-Agent", "hol-guard")
+    if data is not None:
+        request.add_header("Content-Type", "application/json")
+    with urlopen(request, timeout=REQUEST_TIMEOUT_SECONDS) as response:
+        return json.loads(response.read().decode("utf-8"))
+
+
+def _request_json_with_headers(
+    method: str,
+    url: str,
+    token: str,
+    payload: dict[str, object] | None = None,
+) -> tuple[dict[str, object] | list[dict[str, object]], str | None]:
+    data = None if payload is None else json.dumps(payload).encode("utf-8")
+    request = Request(url, data=data, method=method)
+    request.add_header("Accept", "application/vnd.github+json")
+    request.add_header("Authorization", f"Bearer {token}")
+    request.add_header("User-Agent", "hol-guard")
+    if data is not None:
+        request.add_header("Content-Type", "application/json")
+    with urlopen(request, timeout=REQUEST_TIMEOUT_SECONDS) as response:
+        return json.loads(response.read().decode("utf-8")), response.headers.get("Link")
+
+
+def _find_existing_pr_comment(
+    comments: list[dict[str, object]],
+) -> dict[str, object] | None:
+    for item in comments:
+        body = item.get("body")
+        if isinstance(body, str) and PR_COMMENT_MARKER in body:
+            return item
+    return None
+
+
+def _url_with_query_value(url: str, key: str, value: str) -> str:
+    parsed = urlsplit(url)
+    query_items = dict(parse_qsl(parsed.query, keep_blank_values=True))
+    query_items[key] = value
+    return urlunsplit(
+        (
+            parsed.scheme,
+            parsed.netloc,
+            parsed.path,
+            urlencode(query_items),
+            parsed.fragment,
+        )
+    )
+
+
+def _next_link_url(link_header: str | None) -> str | None:
+    if link_header is None or not link_header.strip():
+        return None
+    for item in link_header.split(","):
+        section = item.strip()
+        if 'rel="next"' not in section:
+            continue
+        if not section.startswith("<") or ">" not in section:
+            continue
+        return section[1 : section.index(">")]
+    return None
+
+
+def _repo_comments_url(
+    *,
+    api_base_url: str,
+    repository: str,
+    pull_request_number: int,
+) -> str:
+    owner, name = repository.split("/", 1)
+    encoded_repo = f"{quote(owner, safe='')}/{quote(name, safe='')}"
+    return f"{api_base_url.rstrip('/')}/repos/{encoded_repo}/issues/{pull_request_number}/comments"
+
+
+def _repo_comment_url(
+    *,
+    api_base_url: str,
+    repository: str,
+    comment_id: int,
+) -> str:
+    owner, name = repository.split("/", 1)
+    encoded_repo = f"{quote(owner, safe='')}/{quote(name, safe='')}"
+    return f"{api_base_url.rstrip('/')}/repos/{encoded_repo}/issues/comments/{comment_id}"
+
+
+def _parse_comment_result(
+    payload: dict[str, object] | list[dict[str, object]],
+    *,
+    status: str,
+) -> GitHubPrCommentResult:
+    if not isinstance(payload, dict):
+        raise RuntimeError("GitHub comment mutation returned an unexpected response.")
+    comment_id = payload.get("id")
+    comment_url = payload.get("html_url")
+    return GitHubPrCommentResult(
+        status=status,
+        comment_id=str(comment_id) if isinstance(comment_id, int) else "",
+        comment_url=comment_url if isinstance(comment_url, str) else "",
+    )