hexastack-tools 0.2.0__py3-none-any.whl

hexastack_tools/__init__.py

@@ -0,0 +1,3 @@
+"""Developer tooling, code scanning analysis, and CI automation suite for Hexastack."""
+
+__all__: list[str] = []

hexastack_tools/adapters/github/__init__.py

@@ -0,0 +1,11 @@
+"""GitHub adapter package exports."""
+
+from hexastack_tools.adapters.github.client import (
+    GitHubHttpAdapter,
+    get_github_token,
+)
+
+__all__ = [
+    "get_github_token",
+    "GitHubHttpAdapter",
+]

hexastack_tools/adapters/github/client.py

@@ -0,0 +1,398 @@
+"""Concrete adapter implementing GitHubApiPort using httpx and GitHub REST / GraphQL APIs."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from typing import Any
+
+import httpx
+
+from hexastack_tools.domain.github import (
+    CheckRunFinding,
+    PrSummary,
+    ReviewComment,
+    ReviewThread,
+    SecurityAlert,
+)
+from hexastack_tools.ports.github import GitHubApiPort
+
+
+def get_github_token() -> str | None:
+    """Retrieve GitHub token from environment or gh CLI."""
+    token = os.getenv("GITHUB_TOKEN") or os.getenv("GH_TOKEN")
+    if token:
+        return token.strip()
+
+    if shutil.which("gh"):
+        try:
+            res = subprocess.run(
+                ["gh", "auth", "token"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if res.returncode == 0 and res.stdout.strip():
+                return res.stdout.strip()
+        except (subprocess.SubprocessError, OSError):
+            return None
+
+    return None
+
+
+class GitHubHttpAdapter(GitHubApiPort):
+    """Adapter executing synchronous HTTP requests to GitHub REST and GraphQL APIs."""
+
+    def __init__(
+        self,
+        token: str | None = None,
+        owner: str = "TheTrueSCU",
+        repo: str = "hexastack",
+    ) -> None:
+        """Initialize GitHub HTTP client adapter.
+
+        Args:
+            token: Optional GitHub bearer token.
+            owner: Repository owner / organization.
+            repo: Repository name.
+        """
+        self.owner = owner
+        self.repo = repo
+        self.token = token or get_github_token()
+        headers = {
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        self._client = httpx.Client(
+            base_url="https://api.github.com",
+            headers=headers,
+            timeout=30.0,
+        )
+
+    def close(self) -> None:
+        """Close underlying httpx client."""
+        self._client.close()
+
+    def __enter__(self) -> GitHubHttpAdapter:
+        """Context manager enter."""
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Context manager exit."""
+        self.close()
+
+    def get_pr_summary(self, pr_number: int) -> PrSummary:
+        """Fetch full aggregate summary for a pull request."""
+        resp = self._client.get(f"/repos/{self.owner}/{self.repo}/pulls/{pr_number}")
+        resp.raise_for_status()
+        data = resp.json()
+
+        head_ref = data.get("head", {}).get("ref", "")
+        head_sha = data.get("head", {}).get("sha", "")
+
+        check_runs = self.get_check_runs(head_sha or head_ref)
+        review_threads = self.get_review_threads(pr_number)
+        alerts = self.get_code_scanning_alerts(ref=f"refs/pull/{pr_number}/merge")
+
+        # Fetch issue comments
+        comments_resp = self._client.get(
+            f"/repos/{self.owner}/{self.repo}/issues/{pr_number}/comments"
+        )
+        general_comments: list[ReviewComment] = []
+        if comments_resp.status_code == 200:
+            for c in comments_resp.json():
+                general_comments.append(
+                    ReviewComment(
+                        id=c.get("id", 0),
+                        author=c.get("user", {}).get("login", "unknown"),
+                        body=c.get("body", ""),
+                        created_at=c.get("created_at", ""),
+                        url=c.get("html_url", ""),
+                        is_review_comment=False,
+                    )
+                )
+
+        # Fetch inline review comments (including CodeQL and code reviews)
+        pull_comments_resp = self._client.get(
+            f"/repos/{self.owner}/{self.repo}/pulls/{pr_number}/comments"
+        )
+        if pull_comments_resp.status_code == 200:
+            for c in pull_comments_resp.json():
+                general_comments.append(
+                    ReviewComment(
+                        id=c.get("id", 0),
+                        author=c.get("user", {}).get("login", "unknown"),
+                        body=c.get("body", ""),
+                        created_at=c.get("created_at", ""),
+                        path=c.get("path"),
+                        line=c.get("line") or c.get("original_line"),
+                        url=c.get("html_url", ""),
+                        diff_hunk=c.get("diff_hunk"),
+                        is_review_comment=True,
+                    )
+                )
+
+        return PrSummary(
+            number=pr_number,
+            title=data.get("title", ""),
+            author=data.get("user", {}).get("login", "unknown"),
+            state=data.get("state", "open"),
+            mergeable=str(data.get("mergeable_state") or "unknown"),
+            is_draft=bool(data.get("draft", False)),
+            head_ref=head_ref,
+            base_ref=data.get("base", {}).get("ref", "main"),
+            html_url=data.get("html_url", ""),
+            check_runs=tuple(check_runs),
+            review_threads=tuple(review_threads),
+            security_alerts=tuple(alerts),
+            general_comments=tuple(general_comments),
+        )
+
+    def get_check_runs(self, ref: str) -> list[CheckRunFinding]:
+        """Fetch check runs and commit statuses for a ref."""
+        resp = self._client.get(
+            f"/repos/{self.owner}/{self.repo}/commits/{ref}/check-runs"
+        )
+        if resp.status_code != 200:
+            return []
+
+        runs = resp.json().get("check_runs", [])
+        findings: list[CheckRunFinding] = []
+        for r in runs:
+            findings.append(
+                CheckRunFinding(
+                    name=r.get("name", "unknown"),
+                    status=r.get("status", "unknown"),
+                    conclusion=r.get("conclusion") or "in_progress",
+                    details_url=r.get("html_url") or r.get("details_url", ""),
+                    workflow_name=r.get("workflow_name"),
+                    started_at=r.get("started_at"),
+                    completed_at=r.get("completed_at"),
+                )
+            )
+        return findings
+
+    def get_review_threads(self, pr_number: int) -> list[ReviewThread]:
+        """Fetch review discussion threads and conversation resolution state via GraphQL."""
+        query = """
+        query($owner: String!, $repo: String!, $pr: Int!) {
+          repository(owner: $owner, name: $repo) {
+            pullRequest(number: $pr) {
+              reviewThreads(first: 50) {
+                nodes {
+                  id
+                  isResolved
+                  resolvedBy { login }
+                  comments(first: 20) {
+                    nodes {
+                      id
+                      body
+                      author { login }
+                      path
+                      line
+                      createdAt
+                      url
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        """
+        payload = {
+            "query": query,
+            "variables": {"owner": self.owner, "repo": self.repo, "pr": pr_number},
+        }
+        resp = self._client.post("/graphql", json=payload)
+        if resp.status_code != 200:
+            return []
+
+        data = resp.json()
+        threads_nodes = (
+            data.get("data", {})
+            .get("repository", {})
+            .get("pullRequest", {})
+            .get("reviewThreads", {})
+            .get("nodes", [])
+        )
+        results: list[ReviewThread] = []
+        for t in threads_nodes:
+            thread_id = t.get("id", "")
+            is_resolved = bool(t.get("isResolved", False))
+            resolved_by = (
+                t.get("resolvedBy", {}).get("login") if t.get("resolvedBy") else None
+            )
+
+            comments_list: list[ReviewComment] = []
+            for c in t.get("comments", {}).get("nodes", []):
+                comments_list.append(
+                    ReviewComment(
+                        id=c.get("id", ""),
+                        author=c.get("author", {}).get("login", "unknown"),
+                        body=c.get("body", ""),
+                        created_at=c.get("createdAt", ""),
+                        path=c.get("path"),
+                        line=c.get("line"),
+                        url=c.get("url"),
+                    )
+                )
+
+            results.append(
+                ReviewThread(
+                    id=thread_id,
+                    is_resolved=is_resolved,
+                    resolved_by=resolved_by,
+                    comments=tuple(comments_list),
+                )
+            )
+        return results
+
+    def get_code_scanning_alerts(
+        self,
+        ref: str | None = None,
+        state: str = "open",
+    ) -> list[SecurityAlert]:
+        """Fetch CodeQL code scanning alerts."""
+        params: dict[str, str] = {"per_page": "100"}
+        if state != "all":
+            params["state"] = state
+        if ref:
+            params["ref"] = ref
+
+        resp = self._client.get(
+            f"/repos/{self.owner}/{self.repo}/code-scanning/alerts",
+            params=params,
+        )
+        if resp.status_code != 200:
+            return []
+
+        raw_alerts = resp.json()
+        if not isinstance(raw_alerts, list):
+            return []
+
+        results: list[SecurityAlert] = []
+        for a in raw_alerts:
+            rule = a.get("rule", {})
+            inst = a.get("most_recent_instance", {})
+            loc = inst.get("location", {})
+            results.append(
+                SecurityAlert(
+                    number=a.get("number", 0),
+                    rule_id=rule.get("id", "unknown"),
+                    rule_description=rule.get("description", ""),
+                    severity=rule.get("severity", "unknown"),
+                    security_severity_level=rule.get("security_severity_level"),
+                    state=a.get("state", "open"),
+                    path=loc.get("path", "-"),
+                    start_line=loc.get("start_line"),
+                    end_line=loc.get("end_line"),
+                    message=inst.get("message", {}).get("text", ""),
+                    help_markdown=rule.get("help"),
+                )
+            )
+        return results
+
+    def get_single_alert(self, alert_number: int) -> SecurityAlert:
+        """Fetch full metadata for a single security alert."""
+        resp = self._client.get(
+            f"/repos/{self.owner}/{self.repo}/code-scanning/alerts/{alert_number}"
+        )
+        resp.raise_for_status()
+        a = resp.json()
+
+        rule = a.get("rule", {})
+        inst = a.get("most_recent_instance", {})
+        loc = inst.get("location", {})
+        return SecurityAlert(
+            number=a.get("number", alert_number),
+            rule_id=rule.get("id", "unknown"),
+            rule_description=rule.get("description", ""),
+            severity=rule.get("severity", "unknown"),
+            security_severity_level=rule.get("security_severity_level"),
+            state=a.get("state", "open"),
+            path=loc.get("path", "-"),
+            start_line=loc.get("start_line"),
+            end_line=loc.get("end_line"),
+            message=inst.get("message", {}).get("text", ""),
+            help_markdown=rule.get("help"),
+        )
+
+    def get_failed_run_logs(self, run_id: int | str) -> str | None:
+        """Fetch failed log output for a workflow run using gh CLI or REST API."""
+        if shutil.which("gh"):
+            try:
+                res = subprocess.run(
+                    ["gh", "run", "view", str(run_id), "--log-failed"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+                if res.returncode == 0 and res.stdout.strip():
+                    return res.stdout.strip()
+            except (subprocess.SubprocessError, OSError):
+                # Ignore subprocess failure when retrieving failed run logs via gh CLI
+                pass
+
+        return None
+
+    def get_workflow_runs(
+        self,
+        branch: str | None = None,
+        limit: int = 5,
+    ) -> list[dict[str, Any]]:
+        """Fetch recent workflow runs for a branch."""
+        if shutil.which("gh"):
+            cmd = [
+                "gh",
+                "run",
+                "list",
+                "--json",
+                "databaseId,name,conclusion,headSha,event,status,displayTitle,url",
+                "--limit",
+                str(limit),
+            ]
+            if branch:
+                cmd.extend(["--branch", branch])
+            try:
+                res = subprocess.run(cmd, capture_output=True, text=True, check=False)
+                if res.returncode == 0 and res.stdout.strip():
+                    import json
+
+                    return json.loads(res.stdout.strip())
+            except (subprocess.SubprocessError, OSError, json.JSONDecodeError):
+                # Fall back to GitHub REST API if local gh CLI execution fails
+                pass
+
+        params: dict[str, Any] = {"per_page": limit}
+        if branch:
+            params["branch"] = branch
+        resp = self._client.get(
+            f"/repos/{self.owner}/{self.repo}/actions/runs", params=params
+        )
+        if resp.status_code != 200:
+            return []
+        data = resp.json().get("workflow_runs", [])
+        return [
+            {
+                "databaseId": r.get("id"),
+                "name": r.get("name"),
+                "conclusion": r.get("conclusion") or "",
+                "headSha": r.get("head_sha", ""),
+                "event": r.get("event", ""),
+                "status": r.get("status", ""),
+                "displayTitle": r.get("display_title", ""),
+                "url": r.get("html_url", ""),
+            }
+            for r in data
+        ]
+
+
+__all__ = [
+    "get_github_token",
+    "GitHubHttpAdapter",
+]

hexastack_tools/adapters/presenters/__init__.py

@@ -0,0 +1,37 @@
+"""Presenters package export for hexastack_tools."""
+
+from hexastack_tools.adapters.presenters.checks import (
+    build_checks_table,
+    present_checks,
+    render_checks_json,
+    render_checks_plain,
+)
+from hexastack_tools.adapters.presenters.common import resolve_output_format
+from hexastack_tools.adapters.presenters.pr import (
+    present_pr_summary,
+    render_pr_summary_json,
+    render_pr_summary_plain,
+    render_pr_summary_rich,
+)
+from hexastack_tools.adapters.presenters.security import (
+    build_security_comments_table,
+    present_security_comments,
+    render_security_comments_json,
+    render_security_comments_plain,
+)
+
+__all__ = [
+    "build_checks_table",
+    "build_security_comments_table",
+    "present_checks",
+    "present_pr_summary",
+    "present_security_comments",
+    "render_checks_json",
+    "render_checks_plain",
+    "render_pr_summary_json",
+    "render_pr_summary_plain",
+    "render_pr_summary_rich",
+    "render_security_comments_json",
+    "render_security_comments_plain",
+    "resolve_output_format",
+]

hexastack_tools/adapters/presenters/checks.py

@@ -0,0 +1,106 @@
+"""Checks Presenter supporting Rich ANSI tables, structured JSON, and plain TSV."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from rich.console import Console
+from rich.table import Table
+
+from hexastack_tools.adapters.presenters.common import resolve_output_format
+from hexastack_tools.domain.github import CheckRunFinding, OutputFormat
+
+console = Console()
+
+
+def _render_check_conclusion(conclusion: str) -> str:
+    """Format conclusion with color styling."""
+    conc = conclusion.lower()
+    if conc == "success":
+        return "[bold green]✓ SUCCESS[/bold green]"
+    if conc == "failure":
+        return "[bold red]✗ FAILURE[/bold red]"
+    if conc == "skipped":
+        return "[dim]– SKIPPED[/dim]"
+    if conc == "neutral":
+        return "[dim cyan]○ NEUTRAL[/dim cyan]"
+    return f"[bold yellow]⏳ {conc.upper()}[/bold yellow]"
+
+
+def build_checks_table(checks: list[CheckRunFinding], ref: str) -> Table:
+    """Construct Rich table for CI check runs."""
+    table = Table(
+        title=f"[bold cyan]GitHub CI / Check Runs for '{ref}' ({len(checks)} checks)[/bold cyan]",
+        show_header=True,
+        header_style="bold magenta",
+    )
+    table.add_column("Workflow", style="dim", width=22)
+    table.add_column("Job / Check Name", style="bold")
+    table.add_column("Status", width=12)
+    table.add_column("Conclusion", width=16)
+    table.add_column("Details URL", style="blue")
+
+    for c in checks:
+        table.add_row(
+            c.workflow_name or "CI",
+            c.name,
+            c.status,
+            _render_check_conclusion(c.conclusion),
+            c.details_url,
+        )
+    return table
+
+
+def render_checks_json(checks: list[CheckRunFinding], ref: str) -> str:
+    """Serialize check runs to JSON."""
+    data = {
+        "ref": ref,
+        "total_checks": len(checks),
+        "checks": [
+            {
+                "name": c.name,
+                "workflow": c.workflow_name,
+                "status": c.status,
+                "conclusion": c.conclusion,
+                "details_url": c.details_url,
+            }
+            for c in checks
+        ],
+    }
+    return json.dumps(data, indent=2)
+
+
+def render_checks_plain(checks: list[CheckRunFinding], ref: str) -> str:
+    """Serialize check runs to plain TSV lines."""
+    lines = [f"REF\t{ref}\t{len(checks)}"]
+    for c in checks:
+        lines.append(
+            f"CHECK\t{c.workflow_name or 'CI'}\t{c.name}\t{c.status}\t{c.conclusion}\t{c.details_url}"
+        )
+    return "\n".join(lines)
+
+
+def present_checks(
+    checks: list[CheckRunFinding],
+    ref: str,
+    output_format: OutputFormat = OutputFormat.AUTO,
+) -> None:
+    """Unified entrypoint to present CI check runs in rich, json, plain, or auto-detected format."""
+    resolved_format = resolve_output_format(output_format)
+    if resolved_format == OutputFormat.JSON:
+        sys.stdout.write(render_checks_json(checks, ref) + "\n")
+        sys.stdout.flush()
+    elif resolved_format == OutputFormat.PLAIN:
+        sys.stdout.write(render_checks_plain(checks, ref) + "\n")
+        sys.stdout.flush()
+    else:
+        console.print(build_checks_table(checks, ref))
+
+
+__all__ = [
+    "build_checks_table",
+    "present_checks",
+    "render_checks_json",
+    "render_checks_plain",
+]

hexastack_tools/adapters/presenters/common.py

@@ -0,0 +1,26 @@
+"""Common presentation utilities and pipe-detection for hexastack_tools."""
+
+from __future__ import annotations
+
+import sys
+
+from hexastack_tools.domain.github import OutputFormat
+
+
+def resolve_output_format(output_format: OutputFormat) -> OutputFormat:
+    """Resolve auto output format: automatically selects PLAIN if stdout is piped (not a TTY).
+
+    Args:
+        output_format: Requested output format mode (AUTO, RICH, JSON, PLAIN).
+
+    Returns:
+        Resolved concrete OutputFormat (RICH, JSON, or PLAIN).
+    """
+    if output_format == OutputFormat.AUTO:
+        return OutputFormat.PLAIN if not sys.stdout.isatty() else OutputFormat.RICH
+    return output_format
+
+
+__all__ = [
+    "resolve_output_format",
+]