github-security-report 0.20.0__tar.gz → 0.21.0__tar.gz

{github_security_report-0.20.0 → github_security_report-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github-security-report
-Version: 0.20.0
+Version: 0.21.0
 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
@@ -1850,24 +1850,25 @@ Repo mode leaves nothing behind.
 
 ### Progress and run summary
 
-On an interactive terminal an org-mode run keeps one live line at the bottom
-of the screen while it collects: the organisation, the phase it is in, the
-repository count where the phase works per repository, the REST and GraphQL
-request counts with how many are in flight, and the elapsed time. A second
-line appears while GitHub has the run paused for a rate limit, and while the
+On an interactive terminal an org-mode run keeps three live lines at the
+bottom of the screen while it collects, one kind of information each: where
+the run is (the organisation and the phase it is in), its API traffic (the
+REST and GraphQL request counts with how many are in flight, and external
+requests once there are any), and its progress (the elapsed time, the
+repository count where the phase works per repository, and a countdown while
+GitHub has the run paused for a rate limit). A fourth line appears while the
 workflow-run store is being built for the first time, since that one-off
-dominates a cold run. Warnings logged in the meantime are held and replayed,
-in order, once the line comes down.
-
-<!-- markdownlint-disable MD013 -->
+dominates a cold run. Each line stays one line: on a terminal too narrow for
+it, it is cut short with an ellipsis rather than wrapped, and the elapsed
+time, leading its line, is the last thing to go. Warnings logged in the
+meantime are held and replayed, in order, once the display comes down.
 
 ```text
-⠧ lfreleng-actions · probing repositories · 41/120 repos · REST 812 (9 in flight) · GraphQL 24 · 38.2 s
-⏳ rate limited by GitHub (core); resuming in 42 s
+⠧ lfreleng-actions · probing repositories
+  REST 812 (9 in flight) · GraphQL 24
+  38.2 s · 41/120 repos · ⏳ rate limited by GitHub (core); resuming in 42 s
 ```
 
-<!-- markdownlint-enable MD013 -->
-
 Before each organisation's report, a dim three-line summary says what the
 run cost and what the store holds, so a slow run explains itself without
 `--verbose`:
@@ -1890,9 +1891,9 @@ reads `in memory (not cached)` and, since its store is empty every time, is
 never a first run. The summary is for the terminal only: nothing of it
 reaches the Markdown, HTML, JSON or Slack output.
 
-The live line is off under `--no-progress`, when `CI` is set, when stdout is
-not a terminal, and with `--verbose`, whose log lines would fight it for the
-screen. The summary prints in every case. The same figures reach the log at
+The live display is off under `--no-progress`, when `CI` is set, when stdout
+is not a terminal, and with `--verbose`, whose log lines would fight it for
+the screen. The summary prints in every case. The same figures reach the log at
 `INFO` under `--verbose`.
 
 ### GitHub Enterprise Server

{github_security_report-0.20.0 → github_security_report-0.21.0}/README.md

@@ -1806,24 +1806,25 @@ Repo mode leaves nothing behind.
 
 ### Progress and run summary
 
-On an interactive terminal an org-mode run keeps one live line at the bottom
-of the screen while it collects: the organisation, the phase it is in, the
-repository count where the phase works per repository, the REST and GraphQL
-request counts with how many are in flight, and the elapsed time. A second
-line appears while GitHub has the run paused for a rate limit, and while the
+On an interactive terminal an org-mode run keeps three live lines at the
+bottom of the screen while it collects, one kind of information each: where
+the run is (the organisation and the phase it is in), its API traffic (the
+REST and GraphQL request counts with how many are in flight, and external
+requests once there are any), and its progress (the elapsed time, the
+repository count where the phase works per repository, and a countdown while
+GitHub has the run paused for a rate limit). A fourth line appears while the
 workflow-run store is being built for the first time, since that one-off
-dominates a cold run. Warnings logged in the meantime are held and replayed,
-in order, once the line comes down.
-
-<!-- markdownlint-disable MD013 -->
+dominates a cold run. Each line stays one line: on a terminal too narrow for
+it, it is cut short with an ellipsis rather than wrapped, and the elapsed
+time, leading its line, is the last thing to go. Warnings logged in the
+meantime are held and replayed, in order, once the display comes down.
 
 ```text
-⠧ lfreleng-actions · probing repositories · 41/120 repos · REST 812 (9 in flight) · GraphQL 24 · 38.2 s
-⏳ rate limited by GitHub (core); resuming in 42 s
+⠧ lfreleng-actions · probing repositories
+  REST 812 (9 in flight) · GraphQL 24
+  38.2 s · 41/120 repos · ⏳ rate limited by GitHub (core); resuming in 42 s
 ```
 
-<!-- markdownlint-enable MD013 -->
-
 Before each organisation's report, a dim three-line summary says what the
 run cost and what the store holds, so a slow run explains itself without
 `--verbose`:
@@ -1846,9 +1847,9 @@ reads `in memory (not cached)` and, since its store is empty every time, is
 never a first run. The summary is for the terminal only: nothing of it
 reaches the Markdown, HTML, JSON or Slack output.
 
-The live line is off under `--no-progress`, when `CI` is set, when stdout is
-not a terminal, and with `--verbose`, whose log lines would fight it for the
-screen. The summary prints in every case. The same figures reach the log at
+The live display is off under `--no-progress`, when `CI` is set, when stdout
+is not a terminal, and with `--verbose`, whose log lines would fight it for
+the screen. The summary prints in every case. The same figures reach the log at
 `INFO` under `--verbose`.
 
 ### GitHub Enterprise Server

{github_security_report-0.20.0 → github_security_report-0.21.0}/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.20.0'
-__version_tuple__ = version_tuple = (0, 20, 0)
+__version__ = version = '0.21.0'
+__version_tuple__ = version_tuple = (0, 21, 0)
 
 __commit_id__ = commit_id = None

{github_security_report-0.20.0 → github_security_report-0.21.0}/src/github_security_report/cli/progress.py

@@ -6,14 +6,20 @@
 :class:`~github_security_report.client.events.ProgressSink` the transport
 reports requests to and the
 :class:`~github_security_report.collect.context.CollectProgress` the
-collectors name their phases through, and renders what it hears as one Rich
-``Live`` line per organisation: a spinner, the phase, the repository count
-where the phase is per-repository, the REST and GraphQL request counts with
-how many are in flight, and the clock. A second line appears only while
-something exceptional lasts: a rate-limit backoff, or a first-time build of
-the workflow-run store.
-
-While the line is on screen, WARNINGs bound for the terminal are held and
+collectors name their phases through, and renders what it hears as a Rich
+``Live`` display of three lines per organisation, one category each so none
+is cut short on an 80-column terminal:
+
+1. where the run is: a spinner, the organisation and the phase;
+2. API traffic: the REST and GraphQL request counts with how many are in
+   flight, and the external count once one has been made;
+3. progress: the clock, the repository count where the phase is
+   per-repository, and a rate-limit backoff's countdown while it lasts.
+
+A fourth line appears only while the workflow-run store is built for the
+first time, a notice too long to share the third.
+
+While the display is on screen, WARNINGs bound for the terminal are held and
 replayed once it stops, so a transport warning cannot tear through it and the
 operator still reads every one, in order, in a single block before the run
 summary. Off (a :class:`NullTracker`) in CI, when stdout is not a terminal,
@@ -167,7 +173,7 @@ class _LogHold:
 
 
 class RunTracker:
-    """One organisation's live progress line (see the module docstring)."""
+    """One organisation's live progress display (see the module docstring)."""
 
     def __init__(
         self, console: Console, *, clock: Callable[[], float] = time.monotonic
@@ -193,7 +199,7 @@ class RunTracker:
 
     # -- lifecycle ----------------------------------------------------------
     def start(self, org: str) -> None:
-        """Reset the counters for ``org`` and put the line on screen."""
+        """Reset the counters for ``org`` and put the display on screen."""
         self._org = org
         self._started = self._clock()
         self._stopped = None
@@ -221,7 +227,7 @@ class RunTracker:
         self._live = live
 
     def stop(self) -> None:
-        """Freeze the line, take the display down and replay held warnings.
+        """Freeze the display, take it down and replay held warnings.
 
         Best effort: callers run this from ``finally``, so a display that
         fails to draw its last frame must neither replace the error the run
@@ -294,56 +300,70 @@ class RunTracker:
     def _clock_text(self) -> str:
         return f"{self._elapsed():.1f} s"
 
-    def _body(self) -> str:
-        """The line without its clock: what the renderer may truncate."""
-        parts = [self._org, self._phase if self._stopped is None else "done"]
-        if self._repos_total is not None:
-            parts.append(f"{self._repos_done}/{self._repos_total} repos")
-        parts.append(self._count("REST", "rest"))
-        parts.append(self._count("GraphQL", "graphql"))
+    def _where(self) -> str:
+        """The first line's text: the organisation and the phase."""
+        phase = self._phase if self._stopped is None else "done"
+        return f"{self._org} · {phase}"
+
+    def _traffic(self) -> str:
+        """The second line: the request counts by kind."""
+        parts = [self._count("REST", "rest"), self._count("GraphQL", "graphql")]
         if self._requests.get("external"):
             parts.append(self._count("external", "external"))
         return " · ".join(parts)
 
-    def line(self) -> str:
-        """The progress line as plain text: what the spinner follows."""
-        return f"{self._body()} · {self._clock_text()}"
+    def _backoff(self) -> str | None:
+        """The rate-limit countdown, while a backoff is in progress."""
+        if not self._backoffs:
+            return None
+        wait = max(0.0, self._resume_at - self._clock())
+        where = f" ({self._limited_resource})" if self._limited_resource else ""
+        return f"⏳ rate limited by GitHub{where}; resuming in {wait:.0f} s"
+
+    def _progress(self) -> str:
+        """The third line, clock first so truncation takes it last."""
+        parts = [self._clock_text()]
+        if self._repos_total is not None:
+            parts.append(f"{self._repos_done}/{self._repos_total} repos")
+        backoff = self._backoff()
+        if backoff is not None:
+            parts.append(backoff)
+        return " · ".join(parts)
 
-    def exceptional(self) -> tuple[str, str] | None:
-        """The second line, as ``(marker, text)``, while something warrants it."""
-        if self._backoffs:
-            wait = max(0.0, self._resume_at - self._clock())
-            where = f" ({self._limited_resource})" if self._limited_resource else ""
-            return "⏳", f"rate limited by GitHub{where}; resuming in {wait:.0f} s"
+    def lines(self) -> list[str]:
+        """The display as plain text, one string per row, without the spinner."""
+        rows = [self._where(), self._traffic(), self._progress()]
         if self._notice:
-            return "📦", self._notice
-        return None
+            rows.append(f"📦 {self._notice}")
+        return rows
 
     @staticmethod
     def _cell(text: str, style: str = "") -> Text:
         return Text(text, style=style, no_wrap=True, overflow="ellipsis")
 
     def render(self) -> RenderableType:
-        """The one or two physical lines, however narrow the terminal.
-
-        Each row is one line: the text in the middle column truncates with an
-        ellipsis rather than wrapping, since a wrapped line is as unreadable
-        as a torn one. The clock has a column of its own so it is the last
-        thing to go, not the first: it is what tells a stalled run from a
-        slow one once the counts are cut off.
+        """Three or four physical lines, however narrow the terminal.
+
+        Each row is one line: its text truncates with an ellipsis rather than
+        wrapping, since a wrapped line is as unreadable as a torn one. The
+        clock leads the third row so it is the last thing on it to go: it is
+        what tells a stalled run from a slow one. The rows after the first
+        leave the spinner's column empty, so their text aligns under the
+        first row's.
         """
         grid = Table.grid(padding=(0, 1))
         grid.add_column(no_wrap=True)
         grid.add_column()
-        grid.add_column(no_wrap=True)
         marker: RenderableType = (
             self._spinner if self._stopped is None else Text("✓", style="green")
         )
-        grid.add_row(marker, self._cell(self._body()), f"· {self._clock_text()}")
-        second = self.exceptional()
-        if second is not None:
-            second_marker, text = second
-            grid.add_row(Text(second_marker), self._cell(text, "yellow"), "")
+        where, traffic, progress, *notice = self.lines()
+        grid.add_row(marker, self._cell(where))
+        grid.add_row("", self._cell(traffic))
+        style = "yellow" if self._backoffs else ""
+        grid.add_row("", self._cell(progress, style))
+        for text in notice:
+            grid.add_row("", self._cell(text, "yellow"))
         return grid
 
 

{github_security_report-0.20.0 → github_security_report-0.21.0}/src/github_security_report/cli/serialise.py

@@ -40,6 +40,8 @@ def _table_to_dict(section: TableSection) -> dict:
         "fail_count": section.fail_count,
         "unknown_count": section.unknown_count,
         "not_applicable_count": section.not_applicable_count,
+        # One string per note; a note with a detail line carries it after a
+        # newline (the malware coverage note's headline and detail).
         "notes": list(section.notes),
         "description": section.resolved_description(),
         # Aggregate rows beneath the totals, over every row (report.json is the

{github_security_report-0.20.0 → github_security_report-0.21.0}/src/github_security_report/malware.py

@@ -26,9 +26,11 @@ _COLUMNS = ("Repository", "Package", "Ecosystem", "Manifest", "Severity", "Age")
 # Severity and Age sort on numbers (the severity rung, the days), so a
 # configured sort on either defaults to worst or oldest first.
 _NUMERIC_COLUMNS = frozenset({4, 5})
+# A headline and its detail, split by a newline: each surface sets the detail
+# on a line of its own under the headline (see the summary renderers).
 COVERAGE_NOTE = (
-    "GitHub's API does not expose whether malware alerts are enabled; "
-    "a repository without findings may have the feature off."
+    "Malware alert enablement/status NOT currently available through APIs\n"
+    "Repositories without findings may have the feature off so coverage unknown"
 )
 
 

{github_security_report-0.20.0 → github_security_report-0.21.0}/src/github_security_report/render/html.py

@@ -139,6 +139,8 @@ def _summary_context(
                 "kind": line.kind,
                 "emoji": SUMMARY_EMOJI[line.kind],
                 "text": line.text,
+                # A multi-line note: the template breaks between the parts.
+                "parts": line.text.split("\n"),
                 "label": line.names_label,
                 "names": names,
                 "names_hidden": hidden,

{github_security_report-0.20.0 → github_security_report-0.21.0}/src/github_security_report/render/markdown.py

@@ -185,7 +185,9 @@ def _summary_lines(
     """
     out: list[str] = []
     for line in lines:
-        out.append(f"{SUMMARY_EMOJI[line.kind]} {line.text}")
+        # A multi-line note keeps its detail on a line of its own.
+        text = line.text.replace("\n", "<br>\n")
+        out.append(f"{SUMMARY_EMOJI[line.kind]} {text}")
         out.append("")
     for line in lines:
         if not line.listed:

{github_security_report-0.20.0 → github_security_report-0.21.0}/src/github_security_report/render/terminal.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 from collections.abc import Callable, Sequence
 from pathlib import Path
 
+from rich.cells import cell_len
 from rich.console import Console
 from rich.markup import escape
 from rich.table import Table
@@ -140,7 +141,11 @@ def _render_summary(
     """
     for line in lines:
         style = _SUMMARY_STYLE[line.kind]
-        console.print(f"  [{style}]{SUMMARY_EMOJI[line.kind]} {line.text}[/{style}]")
+        emoji = SUMMARY_EMOJI[line.kind]
+        # A multi-line note's detail aligns under its headline's text.
+        indent = " " * (2 + cell_len(emoji) + 1)
+        text = line.text.replace("\n", f"\n{indent}")
+        console.print(f"  [{style}]{emoji} {text}[/{style}]")
     for line in lines:
         if line.listed:
             style = _SUMMARY_STYLE[line.kind]

{github_security_report-0.20.0 → github_security_report-0.21.0}/src/github_security_report/templates/report.html.j2

@@ -56,7 +56,7 @@
 {%- macro render_summary(summary) -%}
   {% if summary %}
   <ul class="summary">
-    {% for line in summary %}<li class="kind-{{ line.kind }}"><span aria-hidden="true">{{ line.emoji }}</span> {{ line.text }}</li>{% endfor %}
+    {% for line in summary %}<li class="kind-{{ line.kind }}"><span aria-hidden="true">{{ line.emoji }}</span> {% for part in line.parts %}{% if not loop.first %}<br>{% endif %}{{ part }}{% endfor %}</li>{% endfor %}
     {% for line in summary %}{% if line.label and line.names %}<li class="names"><strong>{{ line.label }}:</strong> {% for r in line.names %}{% if r.url %}<a href="{{ r.url }}">{{ r.name }}</a>{% else %}{{ r.name }}{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}{% if line.names_hidden %} … (+{{ line.names_hidden }} more){% endif %}</li>{% endif %}{% endfor %}
   </ul>
   {% endif %}