github-security-report 0.11.0__tar.gz → 0.11.2__tar.gz

{github_security_report-0.11.0 → github_security_report-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github-security-report
-Version: 0.11.0
+Version: 0.11.2
 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
@@ -393,6 +393,19 @@ config asked for an uncapped one. `0` means "no limit" at every level. In a
 shared Slack channel the most generous value any contributing org configured for
 that category wins, matching the visibility rule above.
 
+On Slack, `0` is best-effort rather than absolute. Slack imposes hard structural
+limits on a message — 50 blocks per post, 3,000 characters per text object (a
+section body or a context note) and 150 for a header — and rejects the **whole**
+post if any is breached, so an uncapped table would cost the entire digest rather
+than merely overflowing. The digest therefore sizes itself to fit: repository
+name lists are trimmed first, then table rows, and whatever is left out is
+reported by the usual `… and N more` tally so the numbers on screen stay honest.
+Counts are never dropped, only names and rows. The other three surfaces have no
+Slack-style ceiling, but they still apply their own row limits — only the
+`report.json` artifact is unconditionally complete. The digest links to the
+GitHub Pages report whenever `pages_url` is set and short enough to render as a
+link.
+
 ### Per-category row ordering
 
 Each table ships a sensible default ordering — largest backlog first, stalest

{github_security_report-0.11.0 → github_security_report-0.11.2}/README.md

@@ -349,6 +349,19 @@ config asked for an uncapped one. `0` means "no limit" at every level. In a
 shared Slack channel the most generous value any contributing org configured for
 that category wins, matching the visibility rule above.
 
+On Slack, `0` is best-effort rather than absolute. Slack imposes hard structural
+limits on a message — 50 blocks per post, 3,000 characters per text object (a
+section body or a context note) and 150 for a header — and rejects the **whole**
+post if any is breached, so an uncapped table would cost the entire digest rather
+than merely overflowing. The digest therefore sizes itself to fit: repository
+name lists are trimmed first, then table rows, and whatever is left out is
+reported by the usual `… and N more` tally so the numbers on screen stay honest.
+Counts are never dropped, only names and rows. The other three surfaces have no
+Slack-style ceiling, but they still apply their own row limits — only the
+`report.json` artifact is unconditionally complete. The digest links to the
+GitHub Pages report whenever `pages_url` is set and short enough to render as a
+link.
+
 ### Per-category row ordering
 
 Each table ships a sensible default ordering — largest backlog first, stalest

{github_security_report-0.11.0 → github_security_report-0.11.2}/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.11.0'
-__version_tuple__ = version_tuple = (0, 11, 0)
+__version__ = version = '0.11.2'
+__version_tuple__ = version_tuple = (0, 11, 2)
 
 __commit_id__ = commit_id = None

{github_security_report-0.11.0 → github_security_report-0.11.2}/src/github_security_report/client/reads.py

@@ -19,12 +19,45 @@ from github_security_report.client.queries import (
     _DEPENDABOT_ENABLED_QUERY,
     _REPO_GRAPH_FRAGMENT,
 )
-from github_security_report.client.transport import Transport
+from github_security_report.client.transport import NetworkError, Transport
 from github_security_report.models import Repo, RepoGraphData
 
 log = logging.getLogger(__name__)
 
 
+def _aliases_with_errors(errors: object, alias_count: int) -> set[str]:
+    """Alias keys implicated by a batched query's ``errors`` array.
+
+    GitHub reports a *field-level* failure with HTTP 200: the alias is still a
+    populated dictionary, the field that failed is null, and an ``errors``
+    entry carries its path (e.g. ``["r3", "latestRelease"]``). Parsing such a
+    node would convert a read failure into a confident negative -- a nulled
+    ``latestRelease`` is indistinguishable from "never released" -- so the
+    whole alias is treated as unreadable rather than partially trusted.
+
+    The alias is failed wholesale rather than per field: a finer-grained flag
+    per field would have to be threaded through every table to be honest
+    about which half of a row is trustworthy, whereas one unknown repository
+    is already a state every table renders correctly.
+
+    An error whose path names no alias cannot be attributed, so it implicates
+    every alias in the batch: with no way to tell which repositories it
+    touched, treating any of them as successfully read would be a guess.
+    """
+    all_aliases = {f"r{i}" for i in range(alias_count)}
+    if not isinstance(errors, list):
+        return set()
+    affected: set[str] = set()
+    for entry in errors:
+        path = entry.get("path") if isinstance(entry, dict) else None
+        head = path[0] if isinstance(path, list) and path else None
+        if isinstance(head, str) and head in all_aliases:
+            affected.add(head)
+        else:
+            return all_aliases
+    return affected
+
+
 class ReadClient(Transport):
     """The reporting reads: sweeps, per-repo probes and batched prefetch."""
 
@@ -334,12 +367,21 @@ class ReadClient(Transport):
     ) -> dict[str, RepoGraphData]:
         """Prefetch per-repo data for many repositories in one GraphQL query.
 
-        Returns a ``RepoGraphData`` per requested name. Repositories that cannot
-        be read (a ``null`` alias) or a wholly failed query degrade to default
-        ``RepoGraphData``, so they drop out of the dependent tables rather than
-        being mislabelled. An empty ``names`` issues no request.
+        Returns a ``RepoGraphData`` per requested name. This data is
+        load-bearing for whole report sections (releases/tags, Dependabot
+        enablement, open issues), and its defaults are indistinguishable from
+        confident negatives ("never released"), so a wholly failed query --
+        a non-200 response that survived the shared retry/backoff policy, or
+        a 200 carrying no ``data`` object -- raises :class:`NetworkError` to
+        abort the run rather than fabricating results. A repository that
+        cannot be fully read -- a ``null`` alias, or a populated alias whose
+        ``errors`` entry shows a field failed to resolve -- degrades to
+        ``RepoGraphData(unreadable=True)`` so downstream tables report it as
+        unknown. An empty ``names`` issues no request.
         """
-        out = {name: RepoGraphData() for name in names}
+        # Seed every requested name as unreadable; only a successfully parsed
+        # alias replaces its entry, so nothing failed can masquerade as read.
+        out = {name: RepoGraphData(unreadable=True) for name in names}
         if not names:
             return out
         aliases = "\n".join(
@@ -360,17 +402,25 @@ class ReadClient(Transport):
             json={"query": query, "variables": variables},
         )
         if resp.status_code != 200:
+            status = resp.status_code
             await resp.aclose()  # unread body would leak a pooled connection
-            return out
+            raise NetworkError(
+                f"GraphQL prefetch for {org} failed with HTTP {status} after "
+                "exhausting retries; aborting because the release/tag, "
+                "Dependabot-enablement and open-issues data for "
+                f"{len(names)} repositories would otherwise be fabricated "
+                "from defaults (e.g. reported as never released)."
+            )
         body = resp.json()
-        data = body.get("data") or {}
+        data = body.get("data")
         await resp.aclose()  # release the connection once the body is read
         # GitHub answers a partially-refused query with HTTP 200: the readable
-        # aliases populated, the rest null, and an ``errors`` array explaining
-        # why. Silently dropping it hides exactly the case where a field was
-        # served as null because the token could not read it, so the paths are
-        # logged once per batch for diagnosis.
+        # aliases populated, the rest null or missing individual fields, and an
+        # ``errors`` array explaining why. The paths are both logged for
+        # diagnosis and used to fail the affected aliases, since a field nulled
+        # by a failed read is indistinguishable from a genuine absence.
         errors = body.get("errors")
+        errored_aliases = _aliases_with_errors(errors, len(names))
         if errors:
             log.warning(
                 "GraphQL prefetch for %s returned %d error(s); affected data is "
@@ -384,8 +434,32 @@ class ReadClient(Transport):
                     if isinstance(e, dict)
                 ),
             )
+        if not isinstance(data, dict):
+            # HTTP 200 with no data object at all: the whole batch failed
+            # (e.g. a timed-out or refused query). Same stakes as a non-200.
+            raise NetworkError(
+                f"GraphQL prefetch for {org} returned no data for any of "
+                f"{len(names)} repositories; aborting rather than reporting "
+                "fabricated defaults. "
+                f"errors={errors!r}"
+            )
         for i, name in enumerate(names):
-            node = data.get(f"r{i}")
+            alias = f"r{i}"
+            if alias in errored_aliases:
+                # A field of this alias failed to resolve, so its null fields
+                # cannot be told apart from genuine absences. Leave the
+                # pre-seeded unreadable default in place.
+                continue
+            node = data.get(alias)
             if isinstance(node, dict):
                 out[name] = _parse_repo_node(node)
+        unreadable = sorted(name for name, d in out.items() if d.unreadable)
+        if unreadable:
+            log.warning(
+                "GraphQL prefetch for %s could not read %d repositories "
+                "(reported as unknown): %s",
+                org,
+                len(unreadable),
+                ", ".join(unreadable),
+            )
         return out

{github_security_report-0.11.0 → github_security_report-0.11.2}/src/github_security_report/client/transport.py

@@ -35,15 +35,17 @@ _TransportT = TypeVar("_TransportT", bound="Transport")
 
 
 class NetworkError(RuntimeError):
-    """The GitHub API was unreachable after exhausting the retry budget.
+    """The GitHub API was unusable after exhausting the retry budget.
 
     Raised for transport-level failures (DNS, connection, TLS, or read
     timeout) against the GitHub API that persist across every retry within
-    ``API_MAX_TOTAL_WAIT_SECONDS``. The run aborts rather than rendering a
-    report from missing data: when the API itself cannot be reached, an empty
-    or "all clean / all unknown" report is actively misleading. Transport
-    failures against the third-party Scorecard endpoint do not raise this --
-    they degrade that one signal instead.
+    ``API_MAX_TOTAL_WAIT_SECONDS``, and by callers whose data is load-bearing
+    for the whole report (the batched GraphQL prefetch) when GitHub keeps
+    answering with server errors. The run aborts rather than rendering a
+    report from missing data: when the API itself cannot be relied on, an
+    empty or "all clean / all unknown" report is actively misleading.
+    Transport failures against the third-party Scorecard endpoint do not
+    raise this -- they degrade that one signal instead.
     """
 
 
@@ -163,8 +165,11 @@ class Transport:
         -- 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.
-        Rate-limit responses (403/429) back off on the same schedule and, once
-        exhausted, return the throttled response for per-signal degradation.
+        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.
         """
         http = client or self._client
         is_external = http is self._ext_client
@@ -216,10 +221,11 @@ class Transport:
                 waited += delay
                 attempt += 1
                 continue
-            if resp.status_code not in (403, 429):
+            if resp.status_code not in (403, 429) and resp.status_code < 500:
                 return resp
-            # Reachable but possibly rate limited: distinguish secondary/primary
-            # rate limiting from a genuine 403, then back off on the shared
+            # 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")
@@ -235,18 +241,35 @@ class Transport:
             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
+                not (rate_limited or server_error)
                 or attempt >= self._max_retries
                 or waited + delay > API_MAX_TOTAL_WAIT_SECONDS
             ):
+                # 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
-            log.warning("rate limited on %s; backing off %.0fs", url, delay)
+            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)
             # 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()

{github_security_report-0.11.0 → github_security_report-0.11.2}/src/github_security_report/collect/context.py

@@ -60,13 +60,13 @@ class OrgCollectContext:
     probe_scorecard: bool
 
     def graph_for(self, name: str) -> RepoGraphData:
-        """Prefetched GraphQL data for a repository, or empty defaults.
+        """Prefetched GraphQL data for a repository, or unreadable defaults.
 
-        A repository missing from the prefetch (an unreadable alias, or a wholly
-        failed batch) degrades to defaults so it drops out of the dependent
-        tables instead of being mislabelled.
+        A repository missing from the prefetch entirely is marked
+        ``unreadable`` so the dependent tables report it as unknown instead of
+        mislabelling it with confident negatives (e.g. "never released").
         """
-        return self.graph.get(name, RepoGraphData())
+        return self.graph.get(name, RepoGraphData(unreadable=True))
 
     def ruleset_signals(self, name: str) -> set[str]:
         """Signals an org ruleset enforces for a repository (possibly none)."""

{github_security_report-0.11.0 → github_security_report-0.11.2}/src/github_security_report/collect/extras.py

@@ -55,6 +55,7 @@ async def _posture_for_repo(repo: Repo, ctx: OrgCollectContext) -> RepoPosture:
     )
     return RepoPosture(
         repo=repo,
+        graph_unreadable=graph.unreadable,
         dependabot_alerts=graph.dependabot_alerts_enabled,
         security_updates=security_updates,
         private_vulnerability_reporting=pvr,

{github_security_report-0.11.0 → github_security_report-0.11.2}/src/github_security_report/models.py

@@ -171,9 +171,16 @@ class RepoGraphData:
     ``open_issues``, and should present its own totals as covering the window
     rather than the whole backlog. The window is ordered oldest-first, so the
     oldest issue -- the one the age check reports -- is always present even when
-    the window truncates.
+    window truncates.
     """
 
+    # True when this repository's data could not be read at all (a ``null``
+    # GraphQL alias, or the repository missing from the prefetch entirely).
+    # Downstream tables must report such repositories as unknown: the other
+    # defaults below are indistinguishable from "feature absent" readings
+    # (e.g. ``latest_release_at is None`` also means "never released"), so
+    # without this flag a failed read silently renders as false negatives.
+    unreadable: bool = False
     dependabot_alerts_enabled: bool | None = None
     latest_tag_at: dt.datetime | None = None
     # Publish time of the "Latest" release, for release/tag staleness.

{github_security_report-0.11.0 → github_security_report-0.11.2}/src/github_security_report/posture.py

@@ -45,6 +45,11 @@ class RepoPosture:
     """Per-repository configuration/freshness facts for the extra sections."""
 
     repo: Repo
+    # True when the batched GraphQL prefetch could not read this repository at
+    # all: the release/tag and dependabot.yml facts below are then unknown, not
+    # absent, and the tables must count the repository as unknown rather than
+    # render confident negatives such as "never released".
+    graph_unreadable: bool = False
     # Dependabot repo-level feature flags (None = indeterminate).
     dependabot_alerts: bool | None = None
     security_updates: bool | None = None
@@ -217,12 +222,16 @@ def build_cooldown_table(postures: list[RepoPosture]) -> TableSection:
     with_cooldown = sum(
         1 for p in postures if p.has_dependabot_config and not p.cooldown_missing
     )
+    # An unreadable prefetch means the dependabot.yml itself is unknown, not
+    # absent -- count it as unknown rather than silently dropping the repo.
+    indeterminate = sum(1 for p in postures if p.graph_unreadable)
     return TableSection(
         category=category_meta(CategoryKey.DEPENDABOT_COOLDOWN),
         columns=("Repository", "Ecosystems without cooldown"),
         rows=rows,
         pass_count=with_cooldown,
         fail_count=missing,
+        unknown_count=indeterminate,
     )
 
 
@@ -283,6 +292,7 @@ def build_releases_table(
     excluded = frozenset(exclude)
     ranked: list[tuple[int, int, RepoPosture, int | None, int | None]] = []
     current_count = 0
+    unknown_count = 0
     for posture in postures:
         repo = posture.repo
         if is_release_excluded(
@@ -292,6 +302,12 @@ def build_releases_table(
             exclude=excluded,
         ):
             continue
+        if posture.graph_unreadable:
+            # The release/tag data could not be read for this repository, so
+            # its staleness is unknown -- never "never released/tagged", which
+            # is a confident negative the evidence does not support.
+            unknown_count += 1
+            continue
         release_age = _age_days(posture.latest_release_at, generated_at)
         tag_age = _age_days(posture.latest_tag_at, generated_at)
         if _release_is_current(release_age, tag_age, release_max_age_days):
@@ -340,6 +356,7 @@ def build_releases_table(
         rows=rows,
         pass_count=current_count,
         fail_count=len(rows),
+        unknown_count=unknown_count,
         description=age_note + stale_note + meta.description,
     )
 
@@ -361,6 +378,11 @@ def build_mutable_releases_table(postures: list[RepoPosture]) -> TableSection:
     clean_count = 0
     indeterminate_count = 0
     for posture in postures:
+        if posture.graph_unreadable:
+            # The release data could not be read at all: whether any release
+            # exists (let alone is immutable) is unknown.
+            indeterminate_count += 1
+            continue
         seen: set[str] = set()
         candidates: list[ReleaseRef] = []
         for ref in (posture.latest_release, posture.last_published_release):

{github_security_report-0.11.0 → github_security_report-0.11.2}/src/github_security_report/render/slack.py

@@ -8,6 +8,10 @@ offenders per signal, plus a prominent link to the full GitHub Pages report.
 Like the terminal, Slack is a brevity-first surface: it carries the
 standardised summary footer but omits the per-category explanatory description.
 Produces a ``chat.postMessage`` payload. See ``docs/BRIEF.md`` section 11.
+
+Slack validates the payload as a whole and rejects all of it if any structural
+limit is breached, so every block built here is sized by
+:mod:`~github_security_report.render.slack_limits` before it is emitted.
 """
 
 from __future__ import annotations
@@ -16,6 +20,16 @@ from collections.abc import Callable, Sequence
 
 from github_security_report.categories import CategoryKey
 from github_security_report.models import Repo, RepoSignal, SignalType
+from github_security_report.render.html import slugify
+from github_security_report.render.slack_limits import (
+    MAX_TEXT_CHARS,
+    context_block,
+    enforce_block_limit,
+    fallback_text,
+    fit_section_text,
+    header_block,
+    text_length,
+)
 from github_security_report.report import (
     ORG_SETUP_DOC_URL,
     SKIP_MESSAGE,
@@ -33,10 +47,6 @@ from github_security_report.report import (
     truncate,
 )
 
-# Slack rejects a chat.postMessage with more than 50 blocks, so a digest
-# spanning many orgs must be capped or the whole message fails to deliver.
-_SLACK_MAX_BLOCKS = 50
-
 # Summary kinds whose repository names are listed beneath the count line.
 _NAME_LIST_LABEL = {"disabled": "Disabled", "excluded": "Excluded"}
 
@@ -98,8 +108,17 @@ def _plain_total_row(
     return ["Total", *base, *info]
 
 
-def _fixed_table(section: SignalSection, top_n: int) -> str:
-    shown, hidden = truncate(section.offenders, top_n)
+def _fixed_table(section: SignalSection, shown_count: int) -> str:
+    """The fenced offender table showing the first ``shown_count`` rows.
+
+    Takes an absolute row count rather than a limit so the character budget in
+    :mod:`~github_security_report.render.slack_limits` can shed rows further
+    without a second truncation mechanism: the hidden tally is always derived
+    from the full offender list, so it stays honest no matter which cap did the
+    trimming.
+    """
+    shown = section.offenders[:shown_count]
+    hidden = len(section.offenders) - len(shown)
     informational = section_shows_informational(shown)
     cols = _plain_columns(section.signal, informational=informational)
     rows = [_plain_row(s, informational=informational) for s in shown]
@@ -127,28 +146,75 @@ def _fixed_table(section: SignalSection, top_n: int) -> str:
     return "\n".join(lines)
 
 
-def _summary_text(lines: Sequence[SummaryLine], *, top_n: int) -> str:
+def _summary_text(lines: Sequence[SummaryLine], *, names: int) -> str:
     """The standardised footer as Slack mrkdwn: count lines then name lists.
 
     One line per count (failures first), each prefixed with its shared glyph,
     followed by the disabled/excluded repository name lists. Brevity-first, so
     no per-category description is emitted.
+
+    ``names`` caps each name list at an absolute number of entries. It is
+    resolved by :func:`_name_cap` before it gets here, so ``0`` means "list no
+    names" -- not ``truncate``'s "no limit" -- and drops the enumerations
+    entirely. Nothing is lost by that: every name list has a count line above
+    it, and the count lines always survive.
     """
     out: list[str] = []
     for line in lines:
         out.append(f"{SUMMARY_EMOJI[line.kind]} {line.text}")
+    if names <= 0:
+        return "\n".join(out)
     for line in lines:
         label = _NAME_LIST_LABEL.get(line.kind)
         if not (label and line.names):
             continue
-        shown, hidden = truncate(line.names, top_n)
-        names = ", ".join(shown)
+        shown, hidden = truncate(line.names, names)
+        names_text = ", ".join(shown)
         if hidden:
-            names += f" … (+{hidden} more)"
-        out.append(f"{label}: {names}")
+            names_text += f" … (+{hidden} more)"
+        out.append(f"{label}: {names_text}")
     return "\n".join(out)
 
 
+def _name_breaks(lines: Sequence[SummaryLine]) -> tuple[int, ...]:
+    """Lengths of the rendered name lists, where the allowance stops being
+    monotonic.
+
+    A list completing mid-range drops its "… (+N more)" suffix, which can
+    shorten the block even as the allowance rises. Handing these to
+    :func:`fit_section_text` puts each transition on a search boundary.
+    """
+    return tuple(
+        sorted(
+            {
+                len(line.names)
+                for line in lines
+                if line.kind in _NAME_LIST_LABEL and line.names
+            }
+        )
+    )
+
+
+def _name_cap(lines: Sequence[SummaryLine], top_n: int) -> int:
+    """Resolve the configured limit into an absolute name-list allowance.
+
+    ``top_n`` carries the documented "``0`` means no limit" convention, which
+    the character budget cannot work with -- it needs to be able to ask for
+    *fewer* names, including none. Resolving "no limit" to the longest list
+    present makes every allowance an ordinary count.
+
+    The result is bounded by that longest list either way. ``top_n`` is
+    operator-supplied with no schema maximum, and an allowance beyond the names
+    that exist renders identically to one that stops at them -- so passing the
+    raw value through would only make the budget's search probe a wide range of
+    indistinguishable outcomes before it could move on to shedding rows.
+    """
+    longest = max((len(line.names) for line in lines), default=0)
+    if top_n > 0:
+        return min(top_n, longest)
+    return longest
+
+
 def _fixed_table_generic(columns: tuple[str, ...], rows: list[list[str]]) -> str:
     """Fixed-width text table for a generic posture/freshness table."""
     widths = [len(c) for c in columns]
@@ -174,30 +240,73 @@ def _table_block(
     (genuinely no data) is skipped, keeping the brevity-first digest tight. The
     explanatory description is omitted: Slack is a brevity-first surface.
     """
-    shown, hidden = truncate(section.rows, top_n)
-    summary = _summary_text(
-        build_summary(section.summary_counts(excluded)), top_n=top_n
-    )
-    if not shown and not summary:
+    lines = build_summary(section.summary_counts(excluded))
+    row_cap = len(truncate(section.rows, top_n)[0])
+    name_cap = _name_cap(lines, top_n)
+    if not row_cap and not _summary_text(lines, names=name_cap):
         return None
-    text = f"*{section.title}*"
-    if shown:
-        rows = [[row.repo.name, *row.cells] for row in shown]
-        totals = table_column_totals(section, shown)
-        if totals is not None:
-            rows.append(list(totals))
-        table = _fixed_table_generic(section.columns, rows)
-        if hidden:
-            table += f"\n… and {hidden} more"
-        text += f"\n```\n{table}\n```"
-    if summary:
-        text += f"\n{summary}"
+
+    def build(rows: int, names: int) -> str:
+        text = f"*{section.title}*"
+        if rows:
+            shown = section.rows[:rows]
+            cells = [[row.repo.name, *row.cells] for row in shown]
+            totals = table_column_totals(section, shown)
+            if totals is not None:
+                cells.append(list(totals))
+            table = _fixed_table_generic(section.columns, cells)
+            hidden = len(section.rows) - len(shown)
+            if hidden:
+                table += f"\n… and {hidden} more"
+            text += f"\n```\n{table}\n```"
+        summary = _summary_text(lines, names=names)
+        if summary:
+            text += f"\n{summary}"
+        return text
+
     return {
         "type": "section",
-        "text": {"type": "mrkdwn", "text": text},
+        "text": {
+            "type": "mrkdwn",
+            "text": fit_section_text(
+                build,
+                rows=row_cap,
+                names=name_cap,
+                name_breaks=_name_breaks(lines),
+            ),
+        },
     }
 
 
+def _signal_block(
+    section: SignalSection, top_n: int, *, excluded: Sequence[Repo]
+) -> dict:
+    """A Slack section block for one signal's offender table and footer."""
+    lines = build_summary(section.summary_counts(excluded))
+
+    def build(rows: int, names: int) -> str:
+        text = f"*{section.signal.heading}*"
+        if section.offenders:
+            text += f"\n```\n{_fixed_table(section, rows)}\n```"
+        summary = _summary_text(lines, names=names)
+        if summary:
+            text += f"\n{summary}"
+        elif not section.offenders:
+            # Only genuine absence of data (no rows and no countable state)
+            # warrants "no data"; an all-offender table has nothing to add.
+            text += "\nno data"
+        return text
+
+    row_cap = len(truncate(section.offenders, top_n)[0])
+    text = fit_section_text(
+        build,
+        rows=row_cap,
+        names=_name_cap(lines, top_n),
+        name_breaks=_name_breaks(lines),
+    )
+    return {"type": "section", "text": {"type": "mrkdwn", "text": text}}
+
+
 def render_org_blocks(
     org: OrgReport,
     *,
@@ -215,24 +324,13 @@ def render_org_blocks(
         # identically (both mean "no limit"), so normalise None to 0 here.
         return resolve(key) or 0
 
-    blocks: list[dict] = [
-        {
-            "type": "header",
-            "text": {"type": "plain_text", "text": f"🔐 Security report: {org.org}"},
-        }
-    ]
+    blocks: list[dict] = [header_block(f"🔐 Security report: {org.org}")]
     if org.partial:
         blocks.append(
-            {
-                "type": "context",
-                "elements": [
-                    {
-                        "type": "mrkdwn",
-                        "text": "⚠️ Incomplete: the repository listing could not "
-                        "be fully read; some repositories may be missing.",
-                    }
-                ],
-            }
+            context_block(
+                "⚠️ Incomplete: the repository listing could not "
+                "be fully read; some repositories may be missing."
+            )
         )
     excluded = org.excluded_repos
 
@@ -249,12 +347,11 @@ def render_org_blocks(
     for section in org.sections:
         key = section.signal.category_key
         if visible(key):
-            section_top_n = limit_for(key)
-            text = f"*{section.signal.heading}*"
             if section.skipped:
                 # Feature gating found no organisation support: one skip line
                 # linking the setup guide, instead of a table and footer.
-                text += (
+                text = (
+                    f"*{section.signal.heading}*"
                     f"\n{SUMMARY_EMOJI['excluded']} {SKIP_MESSAGE} — "
                     f"<{ORG_SETUP_DOC_URL}|setup guide>"
                 )
@@ -262,19 +359,7 @@ def render_org_blocks(
                     {"type": "section", "text": {"type": "mrkdwn", "text": text}}
                 )
                 continue
-            if section.offenders:
-                table = _fixed_table(section, section_top_n)
-                text += f"\n```\n{table}\n```"
-            summary = _summary_text(
-                build_summary(section.summary_counts(excluded)), top_n=section_top_n
-            )
-            if summary:
-                text += f"\n{summary}"
-            elif not section.offenders:
-                # Only genuine absence of data (no rows and no countable state)
-                # warrants "no data"; an all-offender table has nothing to add.
-                text += "\nno data"
-            blocks.append({"type": "section", "text": {"type": "mrkdwn", "text": text}})
+            blocks.append(_signal_block(section, limit_for(key), excluded=excluded))
         # Dependabot posture sub-tables follow the Dependabot signal block.
         if section.signal is SignalType.DEPENDABOT:
             for table_section in org.dependabot_tables:
@@ -284,38 +369,17 @@ def render_org_blocks(
     add_table(org.private_vulnerability_reporting)
     add_table(org.issues)
     if pages_url:
-        blocks.append(
-            {
-                "type": "context",
-                "elements": [
-                    {"type": "mrkdwn", "text": f"<{pages_url}|View the full report>"}
-                ],
-            }
-        )
+        # Link straight to this organisation's latest report page rather than
+        # the Pages index: the digest is per-org, so the index is a detour.
+        org_url = f"{pages_url.rstrip('/')}/{slugify(org.org)}/report.html"
+        link = f"<{org_url}|View the full report>"
+        # Omit the link rather than clamp it: a cut URL resolves elsewhere,
+        # which is a wrong answer rather than a missing one.
+        if text_length(link) <= MAX_TEXT_CHARS:
+            blocks.append(context_block(link))
     return blocks
 
 
-def _enforce_block_limit(blocks: list[dict], pages_url: str | None) -> list[dict]:
-    """Cap blocks at Slack's per-message limit, noting any truncation.
-
-    A digest covering many orgs can exceed 50 blocks, which makes Slack reject
-    the entire message (no digest delivered). Keep the first blocks and replace
-    the overflow with a single note pointing at the full report.
-    """
-    if len(blocks) <= _SLACK_MAX_BLOCKS:
-        return blocks
-    if pages_url:
-        note = (
-            f"… digest truncated to Slack's {_SLACK_MAX_BLOCKS}-block limit; "
-            f"<{pages_url}|view the full report>."
-        )
-    else:
-        note = f"… digest truncated to Slack's {_SLACK_MAX_BLOCKS}-block limit."
-    kept = blocks[: _SLACK_MAX_BLOCKS - 1]
-    kept.append({"type": "context", "elements": [{"type": "mrkdwn", "text": note}]})
-    return kept
-
-
 def render_payload(
     orgs: list[OrgReport],
     *,
@@ -333,10 +397,10 @@ def render_payload(
                 org, top_n=top_n, pages_url=pages_url, show=show, limit=limit
             )
         )
-    blocks = _enforce_block_limit(blocks, pages_url)
+    blocks = enforce_block_limit(blocks, pages_url)
     names = ", ".join(o.org for o in orgs)
     return {
         "channel": channel,
-        "text": f"🔐 Security report: {names}",
+        "text": fallback_text(f"🔐 Security report: {names}"),
         "blocks": blocks,
     }

github_security_report-0.11.2/src/github_security_report/render/slack_limits.py

@@ -0,0 +1,287 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Keeping a Slack payload inside Slack's hard structural limits.
+
+Slack validates a ``chat.postMessage`` payload as a whole: exceeding any one
+limit rejects the **entire** message, so a single oversized table costs the
+whole digest rather than degrading it. This module is the one place those
+limits are named and enforced:
+
+* the **50-block** per-message ceiling, which a digest spanning many
+  organisations crosses (see :func:`enforce_block_limit`);
+* the **3,000-character** ceiling on a text object, which an uncapped table
+  crosses long before it reaches 50 blocks (see :func:`fit_section_text`).
+  The same limit applies to a ``context`` element, whose text carries the
+  caller-supplied ``pages_url`` and so is *not* bounded by construction (see
+  :func:`context_block`);
+* the **150-character** ceiling on a ``header``, whose text carries a
+  configured organisation name (see :func:`header_block`);
+* the **40,000-character** ceiling on the top-level ``text`` fallback, which
+  concatenates every organisation name (see :func:`fallback_text`).
+
+Only one limit is left unguarded, and it is genuinely structural rather than
+data-dependent: a ``context`` block may hold 10 elements and every one built
+here holds exactly one. Everything an operator can influence -- configured
+organisation names, ``pages_url``, and any "no limit" row setting -- is
+measured rather than assumed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+# Slack rejects a chat.postMessage with more than 50 blocks, so a digest
+# spanning many orgs must be capped or the whole message fails to deliver.
+MAX_BLOCKS = 50
+
+# Slack's text object caps ``text`` at 3,000 characters wherever it appears --
+# section bodies and context elements alike -- and rejects the whole payload
+# with it. Reachable through any documented "no limit" setting (``top_n: 0`` at
+# report, surface or category level), which uncaps a table long before 50 blocks
+# are in play.
+MAX_TEXT_CHARS = 3000
+
+# A header block uses a plain_text object with its own, much tighter ceiling.
+MAX_HEADER_CHARS = 150
+
+# The top-level ``text`` fallback (notification preview) has a far larger one.
+MAX_FALLBACK_CHARS = 40000
+
+# Appended when even a row-less, name-less block will not fit: a guaranteed
+# last resort so an over-budget block can never leave this module.
+_CLAMP_NOTE = "\n… truncated"
+_FENCE = "```"
+
+
+def text_length(text: str) -> int:
+    """Length of ``text`` as Slack measures it, in UTF-16 code units.
+
+    Slack's limits are enforced by a JavaScript-facing API, where string length
+    counts UTF-16 code units, so an astral-plane emoji costs two. Python's
+    ``len`` counts code points and would under-count, letting a payload that
+    Slack rejects slip through. Counting UTF-16 is also the safe choice if
+    Slack in fact counts code points: it is never smaller, so it can only make
+    this module conservative, never permissive.
+
+    ``surrogatepass`` because operator-controlled strings can carry an unpaired
+    surrogate: :func:`json.loads` accepts ``\\ud800`` in a configured
+    organisation name, and POSIX argument decoding turns undecodable bytes into
+    lone surrogates. The strict encoder raises ``UnicodeEncodeError`` on those,
+    which would abort report generation outright -- a worse failure than the
+    oversized payload this module exists to prevent, and one introduced by the
+    measuring rather than by the data.
+    """
+    return len(text.encode("utf-16-le", "surrogatepass")) // 2
+
+
+def clamp(text: str, budget: int = MAX_TEXT_CHARS) -> str:
+    """Hard-cut ``text`` to ``budget``, closing any code fence left open.
+
+    The unconditional backstop beneath :func:`fit_section_text`: it makes the
+    limit an invariant of this module rather than something every caller has to
+    get right. Cutting mid-table would leave an unterminated code fence, which
+    Slack renders as the rest of the block swallowed into a code span, so an odd
+    fence count is balanced before the truncation note is appended.
+
+    A budget too small to hold that note degrades further rather than
+    overshooting -- a bare ellipsis, then nothing at all -- because a backstop
+    that quietly exceeds its own budget is worse than no backstop. Only an
+    explicit ``budget`` argument can reach those cases; every production caller
+    passes :data:`MAX_TEXT_CHARS`.
+    """
+    if text_length(text) <= budget:
+        return text
+    reserved = text_length(_CLAMP_NOTE) + text_length(f"\n{_FENCE}")
+    if budget < reserved:
+        return _ellipsize(text, budget)
+    room = budget - reserved
+    cut = text[:room]
+    # Re-measure rather than trusting the slice: ``room`` is a UTF-16 budget but
+    # the slice is by code point, so a surrogate pair can overshoot it.
+    while cut and text_length(cut) > room:
+        cut = cut[:-1]
+    if cut.count(_FENCE) % 2:
+        cut += f"\n{_FENCE}"
+    return cut + _CLAMP_NOTE
+
+
+def _largest_fitting(
+    render: Callable[[int], str],
+    count: int,
+    budget: int,
+    breaks: Sequence[int] = (),
+) -> int:
+    """Largest ``n <= count`` whose rendered text fits ``budget`` (or ``0``).
+
+    A binary search, which is valid only where rendered length is non-decreasing
+    in ``n``. ``breaks`` names the values where that fails, splitting the range
+    into windows that are individually monotonic; each is searched and the best
+    result wins. The answer is therefore exact without enumerating every
+    candidate -- a few binary searches rather than one linear scan.
+
+    **Rows need no breaks.** :func:`fit_section_text` searches them only after
+    the render at ``count`` has been measured and rejected, so every ``n``
+    probed leaves rows hidden and the single "… and N more" note is present
+    throughout. Each additional row adds at least a newline while that one note
+    can shrink by at most a digit, so length never falls. The step that would
+    shorten it -- the note vanishing once nothing is left over -- happens only
+    at ``count``, which the precondition excludes.
+
+    **Names do need them,** because that argument does not survive a second
+    list. Each name list carries its own note, and a list shorter than the
+    allowance completes *inside* the range: its ``… (+N more)`` suffix vanishes
+    while only one entry is added, so with short repository names the render
+    gets shorter as the allowance rises. Passing each list's length as a break
+    puts every such transition on a window boundary, where it cannot mislead the
+    search. Without them a rejected midpoint discards a fitting range above it
+    and hides names that would have fitted.
+    """
+    starts = sorted({0, *(b for b in breaks if 0 < b <= count)})
+    best = 0
+    for i, start in enumerate(starts):
+        end = starts[i + 1] - 1 if i + 1 < len(starts) else count
+        # Within a window length is non-decreasing, so if the smallest value
+        # does not fit then nothing above it in this window does either.
+        if text_length(render(start)) > budget:
+            continue
+        lo, hi = start, end
+        while lo < hi:
+            mid = (lo + hi + 1) // 2
+            if text_length(render(mid)) <= budget:
+                lo = mid
+            else:
+                hi = mid - 1
+        best = max(best, lo)
+    return best
+
+
+def fit_section_text(
+    render: Callable[[int, int], str],
+    *,
+    rows: int,
+    names: int,
+    name_breaks: Sequence[int] = (),
+    budget: int = MAX_TEXT_CHARS,
+) -> str:
+    """Fit a section block's text into ``budget`` by shedding content.
+
+    ``render(rows, names)`` must build the complete block text showing the first
+    ``rows`` table rows and the first ``names`` entries of each repository name
+    list, *including* the notes accounting for whatever it left out. Because
+    both are plain prefix counts, every reduction here flows back through the
+    same ``truncate``-shaped ``(shown, hidden)`` accounting the other surfaces
+    use, so the "… and N more" tallies stay honest instead of being tracked by a
+    second, parallel mechanism.
+
+    Content is shed in ascending order of value. Repository **name lists** go
+    first: they are pure enumeration, they are the part that grows without bound
+    on a large organisation, and dropping them costs nothing that matters --
+    their *counts* live on separate summary lines that always survive. **Table
+    rows** go next, and only as far as needed; they are ordered worst-first, so
+    a prefix is the most valuable part of the table.
+
+    Rows are shed rather than split across additional blocks. Blocks are a
+    scarce *global* resource -- 50 for the whole digest, shared by every
+    organisation -- so spending them on one oversized table would evict other
+    organisations from the message entirely, trading a partial table for total
+    data loss elsewhere. Slack is a brevity-first surface and the digest links
+    the full report whenever a usable URL is configured, so shedding rows and
+    saying so is the right degradation.
+
+    One probe decides which of the two is actually at fault. If the block still
+    will not fit with *no* names at all, then no name allowance can save it and
+    the rows are the problem, so the name search is skipped entirely rather than
+    rebuilding a large table across a range of allowances that cannot help.
+
+    ``name_breaks`` carries the length of each repository name list, marking
+    where the name allowance stops behaving monotonically; see
+    :func:`_largest_fitting`.
+    """
+    text = render(rows, names)
+    if text_length(text) <= budget:
+        return text
+    if text_length(render(rows, 0)) <= budget:
+        names = _largest_fitting(lambda n: render(rows, n), names, budget, name_breaks)
+        return render(rows, names)
+    rows = _largest_fitting(lambda n: render(n, 0), rows, budget)
+    return clamp(render(rows, 0), budget)
+
+
+def _ellipsize(text: str, budget: int) -> str:
+    """Cut plain text to ``budget``, marking the cut with an ellipsis.
+
+    For the header and fallback strings, where :func:`clamp`'s code-fence
+    handling and multi-line note would be out of place, and as :func:`clamp`'s
+    own fallback when the budget cannot hold that note. A budget with no room
+    even for the ellipsis yields the empty string: there is nothing truthful
+    left to say in zero characters.
+    """
+    if text_length(text) <= budget:
+        return text
+    if budget <= 0:
+        return ""
+    room = budget - 1
+    cut = text[:room]
+    # Re-measure: the budget is in UTF-16 units but the slice is by code point.
+    while cut and text_length(cut) > room:
+        cut = cut[:-1]
+    return f"{cut}…"
+
+
+def header_block(text: str) -> dict:
+    """A header block sized to Slack's plain_text ceiling.
+
+    The heading embeds a configured organisation name. GitHub caps its own
+    logins well below the limit, but the name reaching here comes from the
+    tool's configuration rather than from GitHub, so it is measured rather
+    than assumed.
+    """
+    return {
+        "type": "header",
+        "text": {"type": "plain_text", "text": _ellipsize(text, MAX_HEADER_CHARS)},
+    }
+
+
+def context_block(text: str) -> dict:
+    """A context block sized to Slack's text object ceiling.
+
+    Context elements carry the caller-supplied ``pages_url``, which nothing
+    validates for length, so the same 3,000-character limit applies here as to
+    a section body. Callers that build a link must check it fits *before*
+    passing it in and omit it otherwise: a clamped URL points somewhere other
+    than the report, which is a wrong answer rather than a missing one.
+    """
+    return {"type": "context", "elements": [{"type": "mrkdwn", "text": clamp(text)}]}
+
+
+def fallback_text(text: str) -> str:
+    """The top-level notification text, sized to Slack's ceiling.
+
+    It concatenates every organisation name in the digest, so it grows with the
+    configuration even though the limit is generous.
+    """
+    return _ellipsize(text, MAX_FALLBACK_CHARS)
+
+
+def enforce_block_limit(blocks: list[dict], pages_url: str | None) -> list[dict]:
+    """Cap blocks at Slack's per-message limit, noting any truncation.
+
+    A digest covering many orgs can exceed 50 blocks, which makes Slack reject
+    the entire message (no digest delivered). Keep the first blocks and replace
+    the overflow with a single note pointing at the full report.
+    """
+    if len(blocks) <= MAX_BLOCKS:
+        return blocks
+    note = f"… digest truncated to Slack's {MAX_BLOCKS}-block limit."
+    if pages_url:
+        linked = (
+            f"… digest truncated to Slack's {MAX_BLOCKS}-block limit; "
+            f"<{pages_url}|view the full report>."
+        )
+        # Prefer the linked note, but fall back to the bare one rather than
+        # clamping a URL into something that no longer resolves.
+        if text_length(linked) <= MAX_TEXT_CHARS:
+            note = linked
+    kept = blocks[: MAX_BLOCKS - 1]
+    kept.append(context_block(note))
+    return kept