github-security-report 0.12.0__tar.gz → 0.12.1__tar.gz

{github_security_report-0.12.0 → github_security_report-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github-security-report
-Version: 0.12.0
+Version: 0.12.1
 Summary: Security and quality reporting across GitHub organisations
 Project-URL: Homepage, https://github.com/lfreleng-actions/github-security-report-action
 Project-URL: Repository, https://github.com/lfreleng-actions/github-security-report-action

{github_security_report-0.12.0 → github_security_report-0.12.1}/src/github_security_report/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.12.0'
-__version_tuple__ = version_tuple = (0, 12, 0)
+__version__ = version = '0.12.1'
+__version_tuple__ = version_tuple = (0, 12, 1)
 
 __commit_id__ = commit_id = None

{github_security_report-0.12.0 → github_security_report-0.12.1}/src/github_security_report/client/transport.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 import asyncio
 import logging
 import socket
+from dataclasses import dataclass
 from typing import TypeVar
 
 import httpx
@@ -102,6 +103,102 @@ class AuthError(NetworkError):
     """
 
 
+def _auth_error(method: str, url: str) -> AuthError:
+    """The :class:`AuthError` for credentials GitHub rejected on ``url``.
+
+    Built on the very first 401 rather than retried or degraded, for the
+    reasons :class:`AuthError` gives. The message names the remedy, because
+    the operator's next action is to check the token, not to retry.
+    """
+    return AuthError(
+        "Authentication error: GitHub rejected the credentials "
+        "(HTTP 401); aborting because every subsequent read would "
+        "fail the same way and the report would render as "
+        "'no data' or 'all clean' rather than as a failure.\n  "
+        f"endpoint={method} {url}\n  "
+        "Check that the token is set, has not expired, and has not "
+        "been revoked or rotated."
+    )
+
+
+async def _transport_failure_result(
+    exc: httpx.HTTPError,
+    method: str,
+    url: str,
+    *,
+    attempt: int,
+    is_external: bool,
+) -> httpx.Response:
+    """Resolve a transport failure that outlived the whole retry budget.
+
+    A third-party (Scorecard) endpoint degrades to an indeterminate 503 so one
+    flaky external API never aborts the GitHub report. The GitHub API instead
+    raises :class:`NetworkError`: a report built without live data is actively
+    misleading, so the run aborts, carrying a diagnostics line that names the
+    endpoint that could not be reached.
+    """
+    if is_external:
+        log.warning(
+            "external request to %s failed after %d attempt(s): "
+            "%s; signal degraded to unknown",
+            url,
+            attempt + 1,
+            exc,
+        )
+        return httpx.Response(503, request=httpx.Request(method, url))
+    diagnostics = await _endpoint_diagnostics(url)
+    raise NetworkError(
+        "Network error: the GitHub API is unreachable after "
+        f"{attempt + 1} attempt(s) within "
+        f"{API_MAX_TOTAL_WAIT_SECONDS:.0f}s; aborting because a "
+        "security report cannot be produced without live API "
+        "data.\n  "
+        f"endpoint={method} {url} {diagnostics} "
+        f"cause={exc!s}"
+    ) from exc
+
+
+class _RetryBudget:
+    """Attempts spent and seconds slept so far within one ``_request`` call.
+
+    Holds the state the retry loop carries across iterations, so deciding that
+    the budget has run out and spending it (sleep, then count the attempt) stay
+    together instead of being open-coded at every backoff site.
+    """
+
+    def __init__(self, max_retries: int) -> None:
+        self.attempt = 0
+        self.waited = 0.0
+        self._max_retries = max_retries
+
+    def exhausted(self, delay: float) -> bool:
+        """Whether sleeping ``delay`` would exceed the retry or wait budget."""
+        return (
+            self.attempt >= self._max_retries
+            or self.waited + delay > API_MAX_TOTAL_WAIT_SECONDS
+        )
+
+    async def sleep(self, delay: float) -> None:
+        """Back off for ``delay`` seconds and charge them to the budget."""
+        await asyncio.sleep(delay)
+        self.waited += delay
+        self.attempt += 1
+
+
+@dataclass(frozen=True)
+class _RetryPlan:
+    """How a reachable-but-degraded (403/429/5xx) response should be treated.
+
+    ``retriable`` is false for a genuine permission error, which is handed
+    straight back to the caller; ``server_error`` only selects the wording of
+    the retry warning.
+    """
+
+    retriable: bool
+    server_error: bool
+    delay: float
+
+
 class Transport:
     """Connection lifecycle plus the shared retry/backoff request primitives."""
 
@@ -175,25 +272,20 @@ class Transport:
 
         Retries follow the shared retry/backoff policy: exponential backoff,
         at most ``max_retries`` retries (the constructor argument, defaulting to
-        ``API_MAX_RETRIES``), and at most
-        ``API_MAX_TOTAL_WAIT_SECONDS`` of cumulative waiting. A transport
-        failure (DNS/TLS/connect or read timeout) to the GitHub API that
-        outlives the whole budget raises :class:`NetworkError` to abort the run
-        -- a report built without live data would be misleading. The same
-        failure against the third-party Scorecard endpoint instead degrades to
-        an indeterminate 503, so one flaky external API never aborts the report.
-        Server errors (5xx) and rate-limit responses (403/429) back off on the
-        same schedule and, once exhausted, return the response for the caller
-        to handle: per-signal probes degrade to unknown, while callers whose
-        data is load-bearing (the GraphQL prefetch) abort the run instead of
-        fabricating results. A 401 from the GitHub API is never degraded or
-        retried: it condemns every remaining read, so it raises
-        :class:`AuthError` immediately.
+        ``API_MAX_RETRIES``), and at most ``API_MAX_TOTAL_WAIT_SECONDS`` of
+        cumulative waiting -- the two ceilings :class:`_RetryBudget` tracks.
+        What happens once that budget is spent depends on the failure and lives
+        in the helpers below: :func:`_transport_failure_result` for an endpoint
+        that could not be reached at all, and :meth:`_plan_degraded_retry` for a
+        server error (5xx) or a rate limit (403/429), which ends by returning
+        the response for the caller to handle -- per-signal probes degrade to
+        unknown, while callers whose data is load-bearing (the GraphQL
+        prefetch) abort the run instead of fabricating results. A 401 from the
+        GitHub API is never degraded or retried; see :func:`_auth_error`.
         """
         http = client or self._client
         is_external = http is self._ext_client
-        attempt = 0
-        waited = 0.0
+        budget = _RetryBudget(self._max_retries)
         while True:
             try:
                 async with self._sem:
@@ -201,114 +293,103 @@ class Transport:
             except httpx.HTTPError as exc:
                 # Transport failure: the endpoint could not be reached at all
                 # (DNS, connection, TLS, or read timeout).
-                delay = self._backoff_delay(attempt)
-                exhausted = (
-                    attempt >= self._max_retries
-                    or waited + delay > API_MAX_TOTAL_WAIT_SECONDS
-                )
-                if exhausted:
-                    if is_external:
-                        # Third-party (Scorecard) endpoint: degrade this one
-                        # signal rather than aborting the whole GitHub report.
-                        log.warning(
-                            "external request to %s failed after %d attempt(s): "
-                            "%s; signal degraded to unknown",
-                            url,
-                            attempt + 1,
-                            exc,
-                        )
-                        return httpx.Response(503, request=httpx.Request(method, url))
-                    diagnostics = await _endpoint_diagnostics(url)
-                    raise NetworkError(
-                        "Network error: the GitHub API is unreachable after "
-                        f"{attempt + 1} attempt(s) within "
-                        f"{API_MAX_TOTAL_WAIT_SECONDS:.0f}s; aborting because a "
-                        "security report cannot be produced without live API "
-                        "data.\n  "
-                        f"endpoint={method} {url} {diagnostics} "
-                        f"cause={exc!s}"
-                    ) from exc
-                log.warning(
-                    "request to %s failed: %s; retrying in %.0fs (retry %d of %d)",
-                    url,
-                    exc,
-                    delay,
-                    attempt + 1,
-                    self._max_retries,
-                )
-                await asyncio.sleep(delay)
-                waited += delay
-                attempt += 1
+                delay = self._backoff_delay(budget.attempt)
+                if budget.exhausted(delay):
+                    return await _transport_failure_result(
+                        exc,
+                        method,
+                        url,
+                        attempt=budget.attempt,
+                        is_external=is_external,
+                    )
+                self._log_transport_retry(url, exc, delay, budget.attempt)
+                await budget.sleep(delay)
                 continue
             if resp.status_code == 401 and not is_external:
                 # Credentials rejected: fail fast on the very first request
                 # rather than letting a hundred more rejections accumulate into
                 # an empty, plausible-looking report.
                 await resp.aclose()  # unread body would leak a pooled connection
-                raise AuthError(
-                    "Authentication error: GitHub rejected the credentials "
-                    "(HTTP 401); aborting because every subsequent read would "
-                    "fail the same way and the report would render as "
-                    "'no data' or 'all clean' rather than as a failure.\n  "
-                    f"endpoint={method} {url}\n  "
-                    "Check that the token is set, has not expired, and has not "
-                    "been revoked or rotated."
-                )
+                raise _auth_error(method, url)
             if resp.status_code not in (403, 429) and resp.status_code < 500:
                 return resp
             # Reachable but degraded: a 5xx (GitHub infrastructure trouble) or
             # a possible rate limit. Distinguish secondary/primary rate
             # limiting from a genuine 403, then back off on the shared
             # schedule (honouring Retry-After) within the wait budget.
-            retry_after = resp.headers.get("retry-after")
-            remaining = resp.headers.get("x-ratelimit-remaining")
-            retry_after_secs = _parse_retry_after(retry_after)
-            # A 429 is by definition "Too Many Requests", so always back off on
-            # it even when GitHub (or an intermediary) omits Retry-After and the
-            # x-ratelimit-remaining header; falling through would return the 429
-            # un-retried. A 403 is a rate limit only when one of those headers
-            # says so (otherwise it is a genuine permission error); the mere
-            # *presence* of Retry-After counts, so a malformed/unparsable value
-            # still triggers a backoff (falling back to the exponential schedule
-            # below) rather than being mistaken for a permission error.
-            rate_limited = (
-                resp.status_code == 429 or retry_after is not None or remaining == "0"
-            )
-            # Any 5xx is retried: GitHub's infrastructure wobbles produce
-            # transient 500/502/503 responses that, if returned un-retried,
-            # would silently degrade (or falsify) whole report sections.
-            server_error = resp.status_code >= 500
-            delay = (
-                retry_after_secs
-                if retry_after_secs is not None
-                else self._backoff_delay(attempt)
-            )
-            if (
-                not (rate_limited or server_error)
-                or attempt >= self._max_retries
-                or waited + delay > API_MAX_TOTAL_WAIT_SECONDS
-            ):
+            plan = self._plan_degraded_retry(resp, budget.attempt)
+            if not plan.retriable or budget.exhausted(plan.delay):
                 # Retries exhausted (or a genuine 403): hand the response back
                 # so the caller can degrade its signal to unknown -- or, when
                 # its data is load-bearing, abort the run.
                 return resp
-            if server_error:
-                log.warning(
-                    "server error %d on %s; retrying in %.0fs (retry %d of %d)",
-                    resp.status_code,
-                    url,
-                    delay,
-                    attempt + 1,
-                    self._max_retries,
-                )
-            else:
-                log.warning("rate limited on %s; backing off %.0fs", url, delay)
+            self._log_degraded_retry(resp, url, plan, budget.attempt)
             # The discarded response must be closed; we are retrying and will
             # not read its body, so leaving it open would leak a pool connection.
             await resp.aclose()
-            await asyncio.sleep(delay)
-            waited += delay
-            attempt += 1
+            await budget.sleep(plan.delay)
+
+    def _plan_degraded_retry(self, resp: httpx.Response, attempt: int) -> _RetryPlan:
+        """Decide whether a 403/429/5xx response is retriable, and after how long.
+
+        A 429 is by definition "Too Many Requests", so always back off on it
+        even when GitHub (or an intermediary) omits Retry-After and the
+        x-ratelimit-remaining header; falling through would return the 429
+        un-retried. A 403 is a rate limit only when one of those headers
+        says so (otherwise it is a genuine permission error); the mere
+        *presence* of Retry-After counts, so a malformed/unparsable value
+        still triggers a backoff (falling back to the exponential schedule)
+        rather than being mistaken for a permission error.
+
+        Any 5xx is retried: GitHub's infrastructure wobbles produce transient
+        500/502/503 responses that, if returned un-retried, would silently
+        degrade (or falsify) whole report sections.
+        """
+        retry_after = resp.headers.get("retry-after")
+        remaining = resp.headers.get("x-ratelimit-remaining")
+        retry_after_secs = _parse_retry_after(retry_after)
+        rate_limited = (
+            resp.status_code == 429 or retry_after is not None or remaining == "0"
+        )
+        server_error = resp.status_code >= 500
+        return _RetryPlan(
+            retriable=rate_limited or server_error,
+            server_error=server_error,
+            delay=(
+                retry_after_secs
+                if retry_after_secs is not None
+                else self._backoff_delay(attempt)
+            ),
+        )
+
+    def _log_transport_retry(
+        self, url: str, exc: httpx.HTTPError, delay: float, attempt: int
+    ) -> None:
+        """Warn that an unreachable endpoint will be retried after ``delay``."""
+        log.warning(
+            "request to %s failed: %s; retrying in %.0fs (retry %d of %d)",
+            url,
+            exc,
+            delay,
+            attempt + 1,
+            self._max_retries,
+        )
+
+    def _log_degraded_retry(
+        self, resp: httpx.Response, url: str, plan: _RetryPlan, attempt: int
+    ) -> None:
+        """Warn that a degraded response will be retried after ``plan.delay``."""
+        if plan.server_error:
+            log.warning(
+                "server error %d on %s; retrying in %.0fs (retry %d of %d)",
+                resp.status_code,
+                url,
+                plan.delay,
+                attempt + 1,
+                self._max_retries,
+            )
+        else:
+            log.warning("rate limited on %s; backing off %.0fs", url, plan.delay)
 
     async def _get_list(self, url: str, **params: object) -> tuple[int, list[dict]]:
         """GET a paginated list, returning (status, items collected).

{github_security_report-0.12.0 → github_security_report-0.12.1}/src/github_security_report/ordering.py

@@ -362,6 +362,10 @@ def resolve_signal_terms(
             folded = _SIGNAL_ALIASES.get(folded, folded)
         column = columns.get(folded)
         if column is None:
+            # ``columns`` holds sort-column headings, never a finding value.
+            # CodeQL's py/clear-text-logging-sensitive-data fires only because
+            # ``_SECRET_SCANNING_COLUMNS`` matches its "secret" heuristic -- a
+            # feature name. Alert 68 is dismissed as a false positive.
             log.warning(
                 "ignoring unknown sort column %r for the %s table; available "
                 "columns are: %s",

github_security_report-0.12.1/src/github_security_report/pulls/__init__.py

@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Open pull requests per repository, split by author and by what blocks them.
+
+A reporting category outside the four-state per-signal model, and a sibling of
+:mod:`issues`: a plain table counting each repository's open pull requests
+across two independent groupings.
+
+**Who raised it.** ``Human`` and ``Auto`` partition the counted pull requests:
+``Auto`` is recognised automation (Dependabot, pre-commit.ci, Renovate and any
+other bot actor -- see :mod:`authors`), ``Human`` is everyone else. ``Ext``
+counts the human pull requests raised from outside the organisation, so it is a
+**subset of Human**, never a bot. Counting automation as external would be
+literally true by GitHub's association (``dependabot[bot]`` reports
+``CONTRIBUTOR`` or ``NONE``) and useless in practice: it would bury genuine
+outside contributions under routine dependency updates.
+
+**What is holding it up.** ``Conflict``, ``Fail`` and ``Draft`` are independent
+of the author split and of each other, so one pull request can be counted in
+several of them. They therefore do not sum to the total, and are not meant to.
+
+The same bounded-window caveat as the issues table applies: ``Total`` is exact
+at any size because it comes from ``totalCount``, while the breakdown columns
+only see the collected window, so they can sum to less than ``Total``. A row
+whose window truncated is marked, so a partial breakdown is visible as such.
+
+**Who is expected to move it.** Aggregate rows beneath the totals split the
+same pull requests by assignment. Only ``Unassigned`` is a property of the pull
+request itself; ``Mine`` and ``Others`` are read relative to the account the
+report authenticated as, and so are confined twice over -- to runs that
+authenticated as a person, and to the surface that person reads.
+
+The implementation is split across ``columns`` (the table's schema),
+``counting`` (placing each pull request in the column and assignment buckets),
+``presentation`` (cell wording, emphasis and the description's caveats) and
+``table`` (the builder and the two public entry points). This module re-exports
+the public surface, so importing from ``github_security_report.pulls`` is
+unchanged.
+"""
+
+from __future__ import annotations
+
+# Re-exported for their own sake rather than used here: each was resolvable on
+# the flat module this package replaces. The ``X as X`` form marks them as
+# deliberate re-exports rather than imports nothing uses.
+from collections.abc import Callable as Callable
+from collections.abc import Mapping as Mapping
+from collections.abc import Set as Set
+
+from github_security_report.authors import is_automation_author as is_automation_author
+from github_security_report.authors import is_external_author as is_external_author
+from github_security_report.categories import CategoryKey as CategoryKey
+from github_security_report.categories import category_meta as category_meta
+from github_security_report.models import PullRequestRef as PullRequestRef
+from github_security_report.models import Repo as Repo
+from github_security_report.models import RepoGraphData as RepoGraphData
+from github_security_report.pulls.columns import (
+    ALL_COLUMNS,
+    ASSIGNMENT_ROWS,
+    AUTOMATION_COLUMN,
+    BREAKDOWN_COLUMNS,
+    CONFLICT_COLUMN,
+    DRAFT_COLUMN,
+    EXTERNAL_COLUMN,
+    FAILING_COLUMN,
+    HUMAN_COLUMN,
+    MINE_ROW,
+    OTHERS_ROW,
+    PERSONAL_ASSIGNMENT_ROWS,
+    REPOSITORY_COLUMN,
+    TOTAL_COLUMN,
+    TRUNCATED_MARKER,
+    UNASSIGNED_ROW,
+)
+from github_security_report.pulls.counting import (
+    _blocked_count,
+    _is_automation,
+    _is_external,
+    assignment_counts,
+    assignment_rows,
+    count_pull_requests,
+    is_mine,
+)
+from github_security_report.pulls.presentation import (
+    _cell_levels,
+    _describe,
+    _total_cell,
+    automation_level,
+)
+from github_security_report.pulls.table import (
+    _build_table,
+    build_assigned_pull_requests_table,
+    build_pull_requests_table,
+)
+from github_security_report.report import (
+    CELL_BAD,
+    CELL_GOOD,
+    CELL_WARN,
+    TableRow,
+    TableSection,
+)
+
+# The flat module declared no ``__all__``, so ``import *`` exported exactly its
+# non-underscore top-level names. Splitting it into a package binds the four
+# submodules here too, which would silently widen that surface, so the former
+# surface is pinned explicitly. Private names stay importable by name, as
+# before; they were never part of the star export.
+__all__ = [
+    "ALL_COLUMNS",
+    "ASSIGNMENT_ROWS",
+    "AUTOMATION_COLUMN",
+    "BREAKDOWN_COLUMNS",
+    "CELL_BAD",
+    "CELL_GOOD",
+    "CELL_WARN",
+    "CONFLICT_COLUMN",
+    "Callable",
+    "CategoryKey",
+    "DRAFT_COLUMN",
+    "EXTERNAL_COLUMN",
+    "FAILING_COLUMN",
+    "HUMAN_COLUMN",
+    "MINE_ROW",
+    "Mapping",
+    "OTHERS_ROW",
+    "PERSONAL_ASSIGNMENT_ROWS",
+    "PullRequestRef",
+    "REPOSITORY_COLUMN",
+    "Repo",
+    "RepoGraphData",
+    "Set",
+    "TOTAL_COLUMN",
+    "TRUNCATED_MARKER",
+    "TableRow",
+    "TableSection",
+    "UNASSIGNED_ROW",
+    "annotations",
+    "assignment_counts",
+    "assignment_rows",
+    "automation_level",
+    "build_assigned_pull_requests_table",
+    "build_pull_requests_table",
+    "category_meta",
+    "count_pull_requests",
+    "is_automation_author",
+    "is_external_author",
+    "is_mine",
+]

github_security_report-0.12.1/src/github_security_report/pulls/columns.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""The pull-request table's schema: its columns and its aggregate rows.
+
+Names and order for everything the table draws, kept in one place because the
+counting, the cell emphasis and the table builder all key off them.
+"""
+
+from __future__ import annotations
+
+REPOSITORY_COLUMN = "Repository"
+HUMAN_COLUMN = "Human"
+AUTOMATION_COLUMN = "Auto"
+DRAFT_COLUMN = "Draft"
+EXTERNAL_COLUMN = "Ext"
+FAILING_COLUMN = "Fail"
+CONFLICT_COLUMN = "Conflict"
+TOTAL_COLUMN = "Total"
+
+# Counted columns in render order, framed by the repository and the total.
+# Ordered so related columns read together: the author split first, with Ext
+# beside Human because it qualifies it (Ext is a subset of Human, never of
+# Auto), then the blockers, worst first -- a conflict needs a human to rebase,
+# a failing check may only need a re-run, and a draft is not blocked at all.
+BREAKDOWN_COLUMNS = (
+    HUMAN_COLUMN,
+    EXTERNAL_COLUMN,
+    AUTOMATION_COLUMN,
+    CONFLICT_COLUMN,
+    FAILING_COLUMN,
+    DRAFT_COLUMN,
+)
+
+ALL_COLUMNS = (REPOSITORY_COLUMN, *BREAKDOWN_COLUMNS, TOTAL_COLUMN)
+
+# Aggregate rows drawn beneath the totals, splitting the same pull requests by
+# who is expected to move them. A partition, not another set of columns: every
+# collected pull request falls in exactly one, so the rows sum to the total.
+#
+# Only ``Unassigned`` is a fact about the pull request. ``Mine`` and ``Others``
+# are read relative to the account the report authenticated as, so they exist
+# only when that account is a person (see :func:`assignment_rows`) and are
+# rendered only on the surface that person reads (see
+# ``TableSection.personal_footer_labels``).
+UNASSIGNED_ROW = "Unassigned"
+OTHERS_ROW = "Others"
+MINE_ROW = "Mine"
+PERSONAL_ASSIGNMENT_ROWS = (OTHERS_ROW, MINE_ROW)
+ASSIGNMENT_ROWS = (UNASSIGNED_ROW, *PERSONAL_ASSIGNMENT_ROWS)
+
+# Marker appended to a repository's total when its open pull requests exceed the
+# collected window, so a partial breakdown is visible as such.
+TRUNCATED_MARKER = "+"