github-security-report 0.17.0__tar.gz → 0.18.1__tar.gz

github_security_report-0.17.0/README.md → github_security_report-0.18.1/PKG-INFO

@@ -1,3 +1,47 @@
+Metadata-Version: 2.5
+Name: github-security-report
+Version: 0.18.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
+Project-URL: Issues, https://github.com/lfreleng-actions/github-security-report-action/issues
+Author-email: The Linux Foundation <mwatkins@linuxfoundation.org>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: codeql,dependabot,github,github-actions,linux-foundation,reporting,scorecard,secret-scanning,security,zizmor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx[http2]==0.28.1
+Requires-Dist: jinja2==3.1.6
+Requires-Dist: jsonschema==4.26.0
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: rich==15.0.0
+Requires-Dist: typer==0.27.3
+Provides-Extra: dev
+Requires-Dist: mypy==2.4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
+Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Requires-Dist: respx==0.23.1; extra == 'dev'
+Requires-Dist: ruff==0.17.0; extra == 'dev'
+Requires-Dist: syrupy==6.1.1; extra == 'dev'
+Requires-Dist: types-jsonschema==4.26.0.20261006; extra == 'dev'
+Requires-Dist: types-pyyaml==6.0.12.20250915; extra == 'dev'
+Description-Content-Type: text/markdown
+
 <!--
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: 2026 The Linux Foundation
@@ -301,7 +345,10 @@ environment-variable name, never embedded.
     "repo_min_age_days": 28,
     "release_max_age_days": 60,
     "codeql_stale_days": 30,
+    "issue_age_warn_days": 30,
+    "issue_age_error_days": 60,
     "graph_batch": 10,
+    "concurrency": 9,
     "order": { "style": "auto" }
   },
   "organizations": [
@@ -793,6 +840,38 @@ with HTTP 200 and this one field null, so affected repositories are reported as
 `❓ Unknown` rather than counted as having no open issues — an unreadable backlog
 is never presented as a clean one.
 
+#### Issue colours and age thresholds
+
+On the terminal the counts are coloured so the table reads at a glance: `Bug`
+and `Untriaged` **red**, `Docs` **green**. As in the Pull Requests table, only
+**non-zero** counts are coloured, so the eye lands on the rows with something
+in them. The colours follow the column **name** (case-insensitively), so they
+apply to a custom `issue_labels` that keeps a `Bug` or `Docs` column and simply
+do not appear for one that renames them.
+
+`Oldest` is coloured against two age thresholds, in days:
+
+```json
+{
+  "report": {
+    "issue_age_warn_days": 30,
+    "issue_age_error_days": 60
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+- **Green** while the oldest open issue is at most `issue_age_warn_days`
+  (default `30`) old.
+- **Yellow** once it is older than `issue_age_warn_days`.
+- **Red** once it is older than `issue_age_error_days` (default `60`).
+
+An `unknown` age is never coloured. Either threshold may be set to `0` to
+switch that level off; with both off the column is left uncoloured.
+`issue_age_error_days` must be **strictly greater** than `issue_age_warn_days`
+(or `0`), otherwise the yellow level could never be reached, so it is rejected
+at load. Both are settable per organisation.
+
 ### Pull Requests
 
 The `pull_requests` category counts each repository's **open pull requests**,
@@ -1267,16 +1346,25 @@ size is bounded by *latency*, not by rate-limit cost: 25 repositories measured
 at ~9 s against `lfreleng-actions` and failed intermittently; 10 measured at
 ~3.5 s.
 
+Up to four of these queries run at once. Each takes a few seconds on GitHub's
+side, so a prefetch issued one query at a time left most of the client's
+concurrency idle; against `lfreleng-actions` it took about 50 s of a 100 s run.
+
 `report.graph_batch` (default `10`; minimum `1`) sets the starting batch size,
 globally or per organisation. It is a lever for a slow day rather than a hard
 limit: a batch that still fails on size after the transport's own retries is
-re-issued at **half** the size, and the smaller size is kept for the rest of
-that organisation's collection (each organisation in a multi-org run starts
-from its own configured size, since organisations differ in how much data a
-repository carries). Only a single-repository query GitHub still cannot
-answer, or a failure that a smaller query could not fix (a `403`, an
-exhausted rate limit, or a `500`/`503` outage rather than a `502`/`504`
-timeout), aborts the run with exit code `3`.
+re-issued at **half** the size, and every batch issued after that failure is
+seen uses the smaller size for the rest of that organisation's collection
+(each organisation in a multi-org run starts from its own configured size,
+since organisations differ in how much data a repository carries). The
+learned size only shrinks. Because queries overlap, the batches already in
+flight when the first failure arrives were issued at the old size, so on a
+slow day up to four oversized batches, rather than one, may fail before the
+smaller size takes effect; that bounded cost buys the overlap. Only a
+single-repository query GitHub still cannot answer, or a failure that a
+smaller query could not fix (a `403`, an exhausted rate limit, or a
+`500`/`503` outage rather than a `502`/`504` timeout), aborts the run with
+exit code `3`, and the queries still in flight are cancelled first.
 
 The value can be set three ways, in this order of precedence:
 
@@ -1301,6 +1389,65 @@ a larger value buys nothing except a longer first failure.
 > predating the flag will reject a set one with `No such option`, so set
 > `GSR_GRAPH_BATCH` only once the pinned release supports it.
 
+### Client concurrency
+
+Each organisation's run holds at most `report.concurrency` requests to the
+GitHub API open at once (default `9`; minimum `1`, maximum `32`), globally or
+per organisation. Reads from the external Scorecard API queue on a separate
+limit of four, so a slow third-party endpoint never holds a slot that a
+GitHub request is waiting for.
+
+The value can be set three ways, in this order of precedence:
+
+1. `--concurrency N` on the command line (the action's `concurrency` input).
+2. A **repository or organisation variable** passed to that input. The
+   bundled `reporting.yaml` passes `vars.GSR_CONCURRENCY`, so the value can be
+   adjusted from repository settings without a workflow edit or a release.
+3. `report.concurrency` in the configuration; otherwise the built-in `9`.
+
+`9` is a deliberate halfway point. GitHub documents its secondary rate limits
+as no more than 100 concurrent requests across REST and GraphQL, and no more
+than 900 points per minute for REST endpoints; this project has hit those
+limits before, so the default stays well clear of them. Measured against
+`lfreleng-actions` (143 repositories, about 1,400 requests; one run each in
+the same hour, so read ±10–15 % as GitHub latency noise), before the GraphQL
+prefetch ran concurrently:
+
+<!-- markdownlint-disable MD013 -->
+
+| Concurrency | Wall | Throughput | Mean time per request | Average slots busy | GitHub pushback |
+| ----------- | ---: | ---------: | --------------------: | -----------------: | --------------- |
+| 6 (former default) | 102.5 s | 13.7 req/s | 0.283 s | 3.9 / 6 | none |
+| 12 | 75.9 s | 18.5 req/s | 0.286 s | 5.3 / 12 | none |
+
+<!-- markdownlint-enable MD013 -->
+
+Raise it once a run shows no pushback; lower it if GitHub starts answering
+with secondary rate-limit `403`/`429` responses. To measure a change, run the
+CLI with `--verbose`: when each organisation's collection finishes it logs
+one line of what the run cost, for example
+
+<!-- markdownlint-disable MD013 -->
+
+```text
+GitHub API for lfreleng-actions: 1402 requests (0 retries), 822 core points, 64 graphql points, 41.3 MiB received, 102.5 s
+```
+
+<!-- markdownlint-enable MD013 -->
+
+The request count is every request the tool issued, including retries and
+attempts that never got an answer. The points come from GitHub's own
+`x-ratelimit-*` response headers rather than from counting: GitHub meters a
+token across more than one bucket per resource (alike requests seconds apart
+can carry different `x-ratelimit-reset` values with independent counters), so
+each bucket's spread between its lowest and highest reading is summed per
+resource. The lowest reading already includes that request's own cost, so the
+figure is short by the first request of each bucket — a measurement aid, not a
+bill. Nothing of this line reaches the rendered report or the step summary.
+
+> As with `graph_batch`, an empty input is not passed to the tool, so set
+> `GSR_CONCURRENCY` only once the pinned release supports `--concurrency`.
+
 ### Pass/fail severity cutoff
 
 The severity-ranked signals (CodeQL, Scorecard, Zizmor, aislop, Dependabot
@@ -1379,6 +1526,7 @@ and the Slack **bot token** is consumed by the workflow, not the CLI.
 | `force_notify` | No | `false` | Post to Slack regardless of `report_day` |
 | `hide` | No | `""` | Category keys to suppress on every output (space- or comma-separated). Overrides config, and is one-way: it cannot re-enable a disabled category |
 | `graph_batch` | No | `""` | Repositories per batched GraphQL prefetch query (minimum `1`; default: config, else `10`). Pass a repository or organisation variable such as `${{ vars.GSR_GRAPH_BATCH }}` to adjust it from settings. A batch that still fails is halved automatically, so this sets the starting size (see [GraphQL prefetch batch size](#graphql-prefetch-batch-size)) |
+| `concurrency` | No | `""` | Concurrent GitHub API requests per organisation (`1` to `32`; default: config, else `9`). Pass a repository or organisation variable such as `${{ vars.GSR_CONCURRENCY }}` to adjust it from settings (see [Client concurrency](#client-concurrency)) |
 | `tool_version` | No | `""` | Published PyPI version to install. Empty (the default) uses the Dependabot-managed pin in `.github/runtime-pin/requirements.txt`; set a specific version to override. Ignored on pull requests or when `use_local_source` is `true` (both run from source) |
 | `use_local_source` | No | `false` | Run from the checked-out source instead of PyPI (for testing unreleased code from any event) |
 

github_security_report-0.17.0/PKG-INFO → github_security_report-0.18.1/README.md

@@ -1,47 +1,3 @@
-Metadata-Version: 2.5
-Name: github-security-report
-Version: 0.17.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
-Project-URL: Issues, https://github.com/lfreleng-actions/github-security-report-action/issues
-Author-email: The Linux Foundation <mwatkins@linuxfoundation.org>
-License-Expression: Apache-2.0
-License-File: LICENSE
-Keywords: codeql,dependabot,github,github-actions,linux-foundation,reporting,scorecard,secret-scanning,security,zizmor
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Security
-Classifier: Topic :: Software Development :: Quality Assurance
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: httpx[http2]==0.28.1
-Requires-Dist: jinja2==3.1.6
-Requires-Dist: jsonschema==4.26.0
-Requires-Dist: pyyaml==6.0.3
-Requires-Dist: rich==15.0.0
-Requires-Dist: typer==0.27.2
-Provides-Extra: dev
-Requires-Dist: mypy==2.3.1; extra == 'dev'
-Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
-Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
-Requires-Dist: pytest==9.1.1; extra == 'dev'
-Requires-Dist: respx==0.23.1; extra == 'dev'
-Requires-Dist: ruff==0.16.8; extra == 'dev'
-Requires-Dist: syrupy==6.1.1; extra == 'dev'
-Requires-Dist: types-jsonschema==4.26.0.20260518; extra == 'dev'
-Requires-Dist: types-pyyaml==6.0.12.20250915; extra == 'dev'
-Description-Content-Type: text/markdown
-
 <!--
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: 2026 The Linux Foundation
@@ -345,7 +301,10 @@ environment-variable name, never embedded.
     "repo_min_age_days": 28,
     "release_max_age_days": 60,
     "codeql_stale_days": 30,
+    "issue_age_warn_days": 30,
+    "issue_age_error_days": 60,
     "graph_batch": 10,
+    "concurrency": 9,
     "order": { "style": "auto" }
   },
   "organizations": [
@@ -837,6 +796,38 @@ with HTTP 200 and this one field null, so affected repositories are reported as
 `❓ Unknown` rather than counted as having no open issues — an unreadable backlog
 is never presented as a clean one.
 
+#### Issue colours and age thresholds
+
+On the terminal the counts are coloured so the table reads at a glance: `Bug`
+and `Untriaged` **red**, `Docs` **green**. As in the Pull Requests table, only
+**non-zero** counts are coloured, so the eye lands on the rows with something
+in them. The colours follow the column **name** (case-insensitively), so they
+apply to a custom `issue_labels` that keeps a `Bug` or `Docs` column and simply
+do not appear for one that renames them.
+
+`Oldest` is coloured against two age thresholds, in days:
+
+```json
+{
+  "report": {
+    "issue_age_warn_days": 30,
+    "issue_age_error_days": 60
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+- **Green** while the oldest open issue is at most `issue_age_warn_days`
+  (default `30`) old.
+- **Yellow** once it is older than `issue_age_warn_days`.
+- **Red** once it is older than `issue_age_error_days` (default `60`).
+
+An `unknown` age is never coloured. Either threshold may be set to `0` to
+switch that level off; with both off the column is left uncoloured.
+`issue_age_error_days` must be **strictly greater** than `issue_age_warn_days`
+(or `0`), otherwise the yellow level could never be reached, so it is rejected
+at load. Both are settable per organisation.
+
 ### Pull Requests
 
 The `pull_requests` category counts each repository's **open pull requests**,
@@ -1311,16 +1302,25 @@ size is bounded by *latency*, not by rate-limit cost: 25 repositories measured
 at ~9 s against `lfreleng-actions` and failed intermittently; 10 measured at
 ~3.5 s.
 
+Up to four of these queries run at once. Each takes a few seconds on GitHub's
+side, so a prefetch issued one query at a time left most of the client's
+concurrency idle; against `lfreleng-actions` it took about 50 s of a 100 s run.
+
 `report.graph_batch` (default `10`; minimum `1`) sets the starting batch size,
 globally or per organisation. It is a lever for a slow day rather than a hard
 limit: a batch that still fails on size after the transport's own retries is
-re-issued at **half** the size, and the smaller size is kept for the rest of
-that organisation's collection (each organisation in a multi-org run starts
-from its own configured size, since organisations differ in how much data a
-repository carries). Only a single-repository query GitHub still cannot
-answer, or a failure that a smaller query could not fix (a `403`, an
-exhausted rate limit, or a `500`/`503` outage rather than a `502`/`504`
-timeout), aborts the run with exit code `3`.
+re-issued at **half** the size, and every batch issued after that failure is
+seen uses the smaller size for the rest of that organisation's collection
+(each organisation in a multi-org run starts from its own configured size,
+since organisations differ in how much data a repository carries). The
+learned size only shrinks. Because queries overlap, the batches already in
+flight when the first failure arrives were issued at the old size, so on a
+slow day up to four oversized batches, rather than one, may fail before the
+smaller size takes effect; that bounded cost buys the overlap. Only a
+single-repository query GitHub still cannot answer, or a failure that a
+smaller query could not fix (a `403`, an exhausted rate limit, or a
+`500`/`503` outage rather than a `502`/`504` timeout), aborts the run with
+exit code `3`, and the queries still in flight are cancelled first.
 
 The value can be set three ways, in this order of precedence:
 
@@ -1345,6 +1345,65 @@ a larger value buys nothing except a longer first failure.
 > predating the flag will reject a set one with `No such option`, so set
 > `GSR_GRAPH_BATCH` only once the pinned release supports it.
 
+### Client concurrency
+
+Each organisation's run holds at most `report.concurrency` requests to the
+GitHub API open at once (default `9`; minimum `1`, maximum `32`), globally or
+per organisation. Reads from the external Scorecard API queue on a separate
+limit of four, so a slow third-party endpoint never holds a slot that a
+GitHub request is waiting for.
+
+The value can be set three ways, in this order of precedence:
+
+1. `--concurrency N` on the command line (the action's `concurrency` input).
+2. A **repository or organisation variable** passed to that input. The
+   bundled `reporting.yaml` passes `vars.GSR_CONCURRENCY`, so the value can be
+   adjusted from repository settings without a workflow edit or a release.
+3. `report.concurrency` in the configuration; otherwise the built-in `9`.
+
+`9` is a deliberate halfway point. GitHub documents its secondary rate limits
+as no more than 100 concurrent requests across REST and GraphQL, and no more
+than 900 points per minute for REST endpoints; this project has hit those
+limits before, so the default stays well clear of them. Measured against
+`lfreleng-actions` (143 repositories, about 1,400 requests; one run each in
+the same hour, so read ±10–15 % as GitHub latency noise), before the GraphQL
+prefetch ran concurrently:
+
+<!-- markdownlint-disable MD013 -->
+
+| Concurrency | Wall | Throughput | Mean time per request | Average slots busy | GitHub pushback |
+| ----------- | ---: | ---------: | --------------------: | -----------------: | --------------- |
+| 6 (former default) | 102.5 s | 13.7 req/s | 0.283 s | 3.9 / 6 | none |
+| 12 | 75.9 s | 18.5 req/s | 0.286 s | 5.3 / 12 | none |
+
+<!-- markdownlint-enable MD013 -->
+
+Raise it once a run shows no pushback; lower it if GitHub starts answering
+with secondary rate-limit `403`/`429` responses. To measure a change, run the
+CLI with `--verbose`: when each organisation's collection finishes it logs
+one line of what the run cost, for example
+
+<!-- markdownlint-disable MD013 -->
+
+```text
+GitHub API for lfreleng-actions: 1402 requests (0 retries), 822 core points, 64 graphql points, 41.3 MiB received, 102.5 s
+```
+
+<!-- markdownlint-enable MD013 -->
+
+The request count is every request the tool issued, including retries and
+attempts that never got an answer. The points come from GitHub's own
+`x-ratelimit-*` response headers rather than from counting: GitHub meters a
+token across more than one bucket per resource (alike requests seconds apart
+can carry different `x-ratelimit-reset` values with independent counters), so
+each bucket's spread between its lowest and highest reading is summed per
+resource. The lowest reading already includes that request's own cost, so the
+figure is short by the first request of each bucket — a measurement aid, not a
+bill. Nothing of this line reaches the rendered report or the step summary.
+
+> As with `graph_batch`, an empty input is not passed to the tool, so set
+> `GSR_CONCURRENCY` only once the pinned release supports `--concurrency`.
+
 ### Pass/fail severity cutoff
 
 The severity-ranked signals (CodeQL, Scorecard, Zizmor, aislop, Dependabot
@@ -1423,6 +1482,7 @@ and the Slack **bot token** is consumed by the workflow, not the CLI.
 | `force_notify` | No | `false` | Post to Slack regardless of `report_day` |
 | `hide` | No | `""` | Category keys to suppress on every output (space- or comma-separated). Overrides config, and is one-way: it cannot re-enable a disabled category |
 | `graph_batch` | No | `""` | Repositories per batched GraphQL prefetch query (minimum `1`; default: config, else `10`). Pass a repository or organisation variable such as `${{ vars.GSR_GRAPH_BATCH }}` to adjust it from settings. A batch that still fails is halved automatically, so this sets the starting size (see [GraphQL prefetch batch size](#graphql-prefetch-batch-size)) |
+| `concurrency` | No | `""` | Concurrent GitHub API requests per organisation (`1` to `32`; default: config, else `9`). Pass a repository or organisation variable such as `${{ vars.GSR_CONCURRENCY }}` to adjust it from settings (see [Client concurrency](#client-concurrency)) |
 | `tool_version` | No | `""` | Published PyPI version to install. Empty (the default) uses the Dependabot-managed pin in `.github/runtime-pin/requirements.txt`; set a specific version to override. Ignored on pull requests or when `use_local_source` is `true` (both run from source) |
 | `use_local_source` | No | `false` | Run from the checked-out source instead of PyPI (for testing unreleased code from any event) |
 

{github_security_report-0.17.0 → github_security_report-0.18.1}/pyproject.toml

@@ -45,7 +45,7 @@ keywords = [
 ]
 dependencies = [
   "httpx[http2]==0.28.1",
-  "typer==0.27.2",
+  "typer==0.27.3",
   "rich==15.0.0",
   "jinja2==3.1.6",
   "jsonschema==4.26.0",
@@ -64,9 +64,9 @@ dev = [
   "pytest-cov==7.1.0",
   "respx==0.23.1",
   "syrupy==6.1.1",
-  "mypy==2.3.1",
-  "ruff==0.16.8",
-  "types-jsonschema==4.26.0.20260518",
+  "mypy==2.4.0",
+  "ruff==0.17.0",
+  "types-jsonschema==4.26.0.20261006",
   "types-PyYAML==6.0.12.20250915",
 ]
 
@@ -96,9 +96,9 @@ dev = [
   "pytest-cov==7.1.0",
   "respx==0.23.1",
   "syrupy==6.1.1",
-  "mypy==2.3.1",
-  "ruff==0.16.8",
-  "types-jsonschema==4.26.0.20260518",
+  "mypy==2.4.0",
+  "ruff==0.17.0",
+  "types-jsonschema==4.26.0.20261006",
   "types-PyYAML==6.0.12.20250915",
 ]
 

{github_security_report-0.17.0 → github_security_report-0.18.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.17.0'
-__version_tuple__ = version_tuple = (0, 17, 0)
+__version__ = version = '0.18.1'
+__version_tuple__ = version_tuple = (0, 18, 1)
 
 __commit_id__ = commit_id = None

{github_security_report-0.17.0 → github_security_report-0.18.1}/src/github_security_report/cli/app.py

@@ -27,6 +27,7 @@ from github_security_report.cli.modes import (
 )
 from github_security_report.cli.options import OrgRunOptions, ReportOverrides
 from github_security_report.cli.outputs import TopNLimits
+from github_security_report.config import CONCURRENCY_MAX
 from github_security_report.scope import RepoSelectionError, parse_repo_selection
 
 app = typer.Typer(
@@ -172,6 +173,11 @@ def report(
         "--graph-batch",
         help="Repositories per batched GraphQL prefetch query (minimum 1; default: config, else 10). GitHub bounds how long one query may run, so a batch that still fails is halved automatically; this sets the starting size.",
     ),
+    concurrency: int | None = typer.Option(
+        None,
+        "--concurrency",
+        help=f"Concurrent GitHub API requests per organisation (1-{CONCURRENCY_MAX}; default: config, else 9). Raise it to shorten a run, lower it if GitHub's secondary rate limits push back.",
+    ),
     no_color: bool = typer.Option(False, "--no-color", help="Disable coloured output."),
 ) -> None:
     """Generate a security and quality report."""
@@ -188,6 +194,9 @@ def report(
     boundary.check_non_negative(console, "--repo-min-age-days", repo_min_age_days)
     boundary.check_non_negative(console, "--release-max-age-days", release_max_age_days)
     boundary.check_positive(console, "--graph-batch", graph_batch)
+    boundary.check_positive(
+        console, "--concurrency", concurrency, maximum=CONCURRENCY_MAX
+    )
     hidden = boundary.resolve_hidden(console, hide)
 
     cfg = _load_config(config_file, config_data, org, token_env, console=console)
@@ -218,6 +227,7 @@ def report(
                 include_archived=True if include_archived else None,
                 include_test=True if include_test else None,
                 graph_batch=graph_batch,
+                concurrency=concurrency,
             ),
             hidden=hidden,
         )
@@ -245,6 +255,7 @@ def report(
                     ("--include-archived", include_archived),
                     ("--include-test", include_test),
                     ("--graph-batch", graph_batch is not None),
+                    ("--concurrency", concurrency is not None),
                 )
                 if supplied
             ],

{github_security_report-0.17.0 → github_security_report-0.18.1}/src/github_security_report/cli/boundary.py

@@ -41,16 +41,22 @@ def check_non_negative(console: Console, name: str, value: int | None) -> None:
         raise typer.Exit(2)
 
 
-def check_positive(console: Console, name: str, value: int | None) -> None:
+def check_positive(
+    console: Console, name: str, value: int | None, *, maximum: int | None = None
+) -> None:
     """Reject a zero or negative override where 0 has no meaning.
 
     For a batch size, unlike a row limit, there is no "unlimited" reading of
     0 -- a query carrying no repositories is not a query -- so the floor is 1,
-    matching the config schema's minimum for the same control.
+    matching the config schema's minimum for the same control. ``maximum``,
+    when given, mirrors the schema's ceiling for the same control.
     """
     if value is not None and value < 1:
         console.print(f"[red]{name} must be 1 or greater[/red]")
         raise typer.Exit(2)
+    if value is not None and maximum is not None and value > maximum:
+        console.print(f"[red]{name} must be {maximum} or less[/red]")
+        raise typer.Exit(2)
 
 
 def check_limits(console: Console, limits: Sequence[tuple[str, int | None]]) -> None:

{github_security_report-0.17.0 → github_security_report-0.18.1}/src/github_security_report/cli/modes.py

@@ -125,7 +125,16 @@ async def _collect_reports(
     now: dt.datetime,
     overrides: ReportOverrides,
 ) -> list[OrgPair] | None:
-    """Collect every configured org's report, or None if a token is missing."""
+    """Collect every configured org's report, or None if a token is missing.
+
+    Once each organisation's client closes, what its requests cost is logged
+    at INFO: visible with ``--verbose``, which is how a run is measured, and
+    silent otherwise. Nothing of it reaches the rendered report. It is logged
+    whether or not the collection finished: a run that aborts on a rate limit,
+    an outage or a rejected token is exactly the run whose request, retry and
+    timing figures are wanted, so the exit path logs them before the error
+    propagates.
+    """
     pairs: list[OrgPair] = []
     for org_cfg in cfg.organizations:
         token = config.resolve_token(org_cfg)
@@ -135,15 +144,21 @@ async def _collect_reports(
             )
             return None
         effective_cfg, report_cfg = overrides.apply(org_cfg)
-        async with GitHubClient(token) as client:
-            pairs.append(
-                (
-                    org_cfg,
-                    await collect.collect_org(
-                        client, effective_cfg, report_cfg, generated_at=now
-                    ),
+        client = GitHubClient(token, concurrency=report_cfg.concurrency)
+        try:
+            async with client:
+                pairs.append(
+                    (
+                        org_cfg,
+                        await collect.collect_org(
+                            client, effective_cfg, report_cfg, generated_at=now
+                        ),
+                    )
                 )
-            )
+        finally:
+            # After the context has closed the client, so the elapsed time
+            # covers the whole run; the error, if any, carries on from here.
+            log.info("GitHub API for %s: %s", org_cfg.name, client.stats.summary())
     return pairs
 
 
@@ -204,7 +219,7 @@ async def _run_repo(
     if not token:
         console.print(f"[red]No token in ${token_env}[/red]")
         return 2
-    async with GitHubClient(token) as client:
+    async with GitHubClient(token, concurrency=cfg.concurrency) as client:
         repo, signals = await collect.collect_repo(
             client, owner, repo_name, ruleset_workflows=cfg.ruleset_workflows
         )

{github_security_report-0.17.0 → github_security_report-0.18.1}/src/github_security_report/cli/options.py

@@ -35,9 +35,9 @@ class ReportOverrides:
     but not narrow it, so a flag can loosen what the configuration asked for
     without being able to tighten it behind the operator's back.
 
-    ``graph_batch`` is an operational lever rather than report policy: it
-    changes how the GraphQL prefetch is issued, never what the report says, so
-    it may move in either direction.
+    ``graph_batch`` and ``concurrency`` are operational levers rather than
+    report policy: they change how the requests are issued, never what the
+    report says, so they may move in either direction.
     """
 
     repo_min_age_days: int | None = None
@@ -47,14 +47,15 @@ class ReportOverrides:
     include_archived: bool | None = None
     include_test: bool | None = None
     graph_batch: int | None = None
+    concurrency: int | None = None
 
     def apply(self, org_cfg: OrgConfig) -> tuple[OrgConfig, ReportConfig]:
         """The org and report configs to collect with, overrides applied.
 
-        The two age thresholds, the three booleans and the batch size are
-        scalar policy, so applying one uniformly across every configured
-        organisation is what a reader of the flag expects, and matches how
-        ``--top-n`` already behaves.
+        The two age thresholds, the three booleans, the batch size and the
+        concurrency are scalars, so applying one uniformly across every
+        configured organisation is what a reader of the flag expects, and
+        matches how ``--top-n`` already behaves.
 
         ``releases_exclude`` is not scalar: it is a curated per-organisation
         list, and one flag replacing all of them loses data the config
@@ -70,6 +71,7 @@ class ReportOverrides:
             "include_archived",
             "include_test",
             "graph_batch",
+            "concurrency",
         ):
             value = getattr(self, name)
             if value is not None: