github-security-report 0.16.0__tar.gz → 0.18.0__tar.gz

{github_security_report-0.16.0 → github_security_report-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github-security-report
-Version: 0.16.0
+Version: 0.18.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
@@ -36,7 +36,7 @@ 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: ruff==0.16.9; 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'
@@ -345,6 +345,8 @@ 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,
     "order": { "style": "auto" }
   },
@@ -407,7 +409,8 @@ organisation, as `--top-n` does.
 
 The per-org `exclude` list removes repositories from analysis entirely; they are
 reported as **excluded** (distinct from "not enabled"), so an intentional
-exclusion is visible rather than silently dropped.
+exclusion is visible rather than silently dropped. Entries match repository
+names case-insensitively, as GitHub does.
 
 Every category reports those exclusions beneath its counts, so an
 organisation-wide list repeats under each one. `report.excluded_display`
@@ -836,6 +839,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**,
@@ -1519,8 +1554,30 @@ uvx github-security-report remediate \
 # Limit to specific categories (repeatable).
 uvx github-security-report remediate --org lfreleng-actions \
   --category codeql --category private_vulnerability_reporting --apply
+
+# Limit to specific repositories, for any category (comma-separated and/or
+# repeatable; `name` in any configured org, or `owner/name`).
+uvx github-security-report remediate --org lfreleng-actions \
+  --repos dependamerge,python-nss-ng --apply
 ```
 
+`--repos` narrows the run itself, not just its output. Everything done per
+repository (the feature probes, the batched prefetch, the CodeQL history walk
+and every write) covers only the named repositories, so a targeted run skips
+the bulk of a full one. The organisation-wide alert sweeps are the exception:
+each is a single org-bulk request, so its cost follows the organisation's open
+alert backlog rather than its repository count. It combines with
+`--category`. Every name is checked against every configured organisation
+before anything is written: a name that matches no repository (almost always
+a typo), or one that matches only repositories the configuration excludes
+(the `exclude` list, archived, fork, template or test), stops the run with
+exit code 2 and says which. A bare name excluded in one organisation but in
+scope in another runs against the in-scope one only; naming a repository never
+brings an excluded one back. A `--repos` value that names nothing also stops
+the run, rather than falling back to every repository. The run then collects
+exactly the repositories that check validated, without listing the
+organisation again, and prints `Limited to:` beneath its heading.
+
 The remediable categories are the simple on/off features with a documented
 enablement endpoint:
 
@@ -1537,6 +1594,59 @@ Qualitative findings (Scorecard, zizmor, open Dependabot alerts, cooldown,
 release freshness/mutability) are reported but not auto-remediated. Remediation
 is organisation-scoped (`--scope org`, the default and only supported scope).
 
+### Cleaning up stale CodeQL configurations
+
+One category is **destructive**, so it runs only when named. The no-argument
+run never includes it:
+
+```bash
+# Preview: which configurations would go, and which are refused and why.
+uvx github-security-report remediate --org lfreleng-actions \
+  --category codeql_stale_configurations
+
+# Apply.
+uvx github-security-report remediate --org lfreleng-actions \
+  --category codeql_stale_configurations --apply
+```
+
+It acts on the rows of **CodeQL: Stale Configurations**, according to their
+cause:
+
+<!-- markdownlint-disable MD013 -->
+
+| Cause | Action |
+| ----- | ------ |
+| Default setup disabled; workflow removed; superseded by default setup; language removed from default setup | **Delete** the configuration: it can never upload again |
+| Workflow disabled after inactivity | **Re-enable** the workflow, restoring the scan |
+| Analyses failing, default setup changing state or not uploading, uploaded outside GitHub Actions, workflow disabled by hand, active but not uploading, or state unreadable | Reported only; needs a person |
+
+<!-- markdownlint-enable MD013 -->
+
+Deleting removes a configuration's analyses, which clears GitHub's *"Code
+Scanning results may be out of date"* warning but also removes its alert
+history. A deletion is therefore **refused**, in a dry run as in an apply,
+when:
+
+- no current configuration scans its language: the stale results are then
+  the only record of it, so add scanning for the language first (the refusal
+  names it, and **CodeQL: Language Coverage** lists the gap);
+- it would help close an open alert. This is judged across **every deletion
+  planned in the repository**, not one at a time: an alert held by two stale
+  configurations would close if both went, so both are refused, although
+  neither holds it alone. An alert also reported by a live configuration
+  blocks nothing;
+- the repository's open alerts cannot be read.
+
+Refusals are listed beside the work done and do not fail the run. Deletion is
+paced at one request a second across the whole run, as GitHub asks of
+mutating requests, and is resumable: an interrupted run's next pass picks up
+the remaining analyses. GitHub answers requests it will not authorise with
+`404`, so a deletion's `404` counts as already done only once the analysis
+also reads back as gone; a token that may not delete fails instead of
+reporting a cleanup that never happened. The token needs the classic `repo`
+scope. See [ADR-0005](docs/adr/0005-codeql-configuration-cleanup.md) for the
+reasoning.
+
 ## Bulk Remediation Scripts
 
 The standalone scripts below predate the `remediate` subcommand and remain for

{github_security_report-0.16.0 → github_security_report-0.18.0}/README.md

@@ -301,6 +301,8 @@ 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,
     "order": { "style": "auto" }
   },
@@ -363,7 +365,8 @@ organisation, as `--top-n` does.
 
 The per-org `exclude` list removes repositories from analysis entirely; they are
 reported as **excluded** (distinct from "not enabled"), so an intentional
-exclusion is visible rather than silently dropped.
+exclusion is visible rather than silently dropped. Entries match repository
+names case-insensitively, as GitHub does.
 
 Every category reports those exclusions beneath its counts, so an
 organisation-wide list repeats under each one. `report.excluded_display`
@@ -792,6 +795,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**,
@@ -1475,8 +1510,30 @@ uvx github-security-report remediate \
 # Limit to specific categories (repeatable).
 uvx github-security-report remediate --org lfreleng-actions \
   --category codeql --category private_vulnerability_reporting --apply
+
+# Limit to specific repositories, for any category (comma-separated and/or
+# repeatable; `name` in any configured org, or `owner/name`).
+uvx github-security-report remediate --org lfreleng-actions \
+  --repos dependamerge,python-nss-ng --apply
 ```
 
+`--repos` narrows the run itself, not just its output. Everything done per
+repository (the feature probes, the batched prefetch, the CodeQL history walk
+and every write) covers only the named repositories, so a targeted run skips
+the bulk of a full one. The organisation-wide alert sweeps are the exception:
+each is a single org-bulk request, so its cost follows the organisation's open
+alert backlog rather than its repository count. It combines with
+`--category`. Every name is checked against every configured organisation
+before anything is written: a name that matches no repository (almost always
+a typo), or one that matches only repositories the configuration excludes
+(the `exclude` list, archived, fork, template or test), stops the run with
+exit code 2 and says which. A bare name excluded in one organisation but in
+scope in another runs against the in-scope one only; naming a repository never
+brings an excluded one back. A `--repos` value that names nothing also stops
+the run, rather than falling back to every repository. The run then collects
+exactly the repositories that check validated, without listing the
+organisation again, and prints `Limited to:` beneath its heading.
+
 The remediable categories are the simple on/off features with a documented
 enablement endpoint:
 
@@ -1493,6 +1550,59 @@ Qualitative findings (Scorecard, zizmor, open Dependabot alerts, cooldown,
 release freshness/mutability) are reported but not auto-remediated. Remediation
 is organisation-scoped (`--scope org`, the default and only supported scope).
 
+### Cleaning up stale CodeQL configurations
+
+One category is **destructive**, so it runs only when named. The no-argument
+run never includes it:
+
+```bash
+# Preview: which configurations would go, and which are refused and why.
+uvx github-security-report remediate --org lfreleng-actions \
+  --category codeql_stale_configurations
+
+# Apply.
+uvx github-security-report remediate --org lfreleng-actions \
+  --category codeql_stale_configurations --apply
+```
+
+It acts on the rows of **CodeQL: Stale Configurations**, according to their
+cause:
+
+<!-- markdownlint-disable MD013 -->
+
+| Cause | Action |
+| ----- | ------ |
+| Default setup disabled; workflow removed; superseded by default setup; language removed from default setup | **Delete** the configuration: it can never upload again |
+| Workflow disabled after inactivity | **Re-enable** the workflow, restoring the scan |
+| Analyses failing, default setup changing state or not uploading, uploaded outside GitHub Actions, workflow disabled by hand, active but not uploading, or state unreadable | Reported only; needs a person |
+
+<!-- markdownlint-enable MD013 -->
+
+Deleting removes a configuration's analyses, which clears GitHub's *"Code
+Scanning results may be out of date"* warning but also removes its alert
+history. A deletion is therefore **refused**, in a dry run as in an apply,
+when:
+
+- no current configuration scans its language: the stale results are then
+  the only record of it, so add scanning for the language first (the refusal
+  names it, and **CodeQL: Language Coverage** lists the gap);
+- it would help close an open alert. This is judged across **every deletion
+  planned in the repository**, not one at a time: an alert held by two stale
+  configurations would close if both went, so both are refused, although
+  neither holds it alone. An alert also reported by a live configuration
+  blocks nothing;
+- the repository's open alerts cannot be read.
+
+Refusals are listed beside the work done and do not fail the run. Deletion is
+paced at one request a second across the whole run, as GitHub asks of
+mutating requests, and is resumable: an interrupted run's next pass picks up
+the remaining analyses. GitHub answers requests it will not authorise with
+`404`, so a deletion's `404` counts as already done only once the analysis
+also reads back as gone; a token that may not delete fails instead of
+reporting a cleanup that never happened. The token needs the classic `repo`
+scope. See [ADR-0005](docs/adr/0005-codeql-configuration-cleanup.md) for the
+reasoning.
+
 ## Bulk Remediation Scripts
 
 The standalone scripts below predate the `remediate` subcommand and remain for

{github_security_report-0.16.0 → github_security_report-0.18.0}/pyproject.toml

@@ -65,7 +65,7 @@ dev = [
   "respx==0.23.1",
   "syrupy==6.1.1",
   "mypy==2.3.1",
-  "ruff==0.16.8",
+  "ruff==0.16.9",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]
@@ -97,7 +97,7 @@ dev = [
   "respx==0.23.1",
   "syrupy==6.1.1",
   "mypy==2.3.1",
-  "ruff==0.16.8",
+  "ruff==0.16.9",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]

{github_security_report-0.16.0 → github_security_report-0.18.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.16.0'
-__version_tuple__ = version_tuple = (0, 16, 0)
+__version__ = version = '0.18.0'
+__version_tuple__ = version_tuple = (0, 18, 0)
 
 __commit_id__ = commit_id = None

{github_security_report-0.16.0 → github_security_report-0.18.0}/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.scope import RepoSelectionError, parse_repo_selection
 
 app = typer.Typer(
     name="github-security-report",
@@ -267,6 +268,7 @@ def report(
 # Derived from the remediator registry rather than restated, so adding a
 # remediable category cannot leave the help text naming the previous set.
 _REMEDIABLE_HELP = ", ".join(key.value for key in remediate_mod.REMEDIABLE)
+_EXPLICIT_HELP = ", ".join(key.value for key in remediate_mod.EXPLICIT_ONLY)
 
 
 @app.command()
@@ -288,7 +290,7 @@ def remediate(
     category: list[str] | None = typer.Option(
         None,
         "--category",
-        help=f"Remediable category to act on (repeatable; default: all). One of: {_REMEDIABLE_HELP}.",
+        help=f"Remediable category to act on (repeatable; default: all except the destructive {_EXPLICIT_HELP}, which run only when named). One of: {_REMEDIABLE_HELP}.",
     ),
     token_env: str | None = typer.Option(
         None,
@@ -300,14 +302,21 @@ def remediate(
         "--apply",
         help="Perform the writes. Without this flag remediate only previews (dry run).",
     ),
+    repos: list[str] | None = typer.Option(
+        None,
+        "--repos",
+        help="Limit every selected category to these repositories: comma-separated and/or repeatable, each 'name' (in any configured org) or 'owner/name'. Each org's repository list is checked first: a name matching nothing, a name matching only excluded repositories, or an incomplete list stops the run before any per-repository read or any write.",
+    ),
     no_color: bool = typer.Option(False, "--no-color", help="Disable coloured output."),
 ) -> None:
     """Enable security features on repositories that lack them.
 
     Runs the same collection the report uses, then switches on each selected
-    remediable feature wherever a repository has it confirmed off. Dry run by
-    default: pass --apply to make changes. Requires a write-capable token
-    (org admin), distinct from the read-only reporting PAT.
+    remediable feature wherever a repository has it confirmed off. Named
+    explicitly, codeql_stale_configurations also deletes orphaned CodeQL
+    configurations. Dry run by default: pass --apply to make changes. Requires
+    a write-capable token (org admin), distinct from the read-only reporting
+    PAT.
     """
     console = _console(no_color)
 
@@ -326,7 +335,22 @@ def remediate(
             markup=False,
         )
         raise typer.Exit(2)
-    categories = keys or list(remediate_mod.REMEDIABLE)
+    categories = keys or list(remediate_mod.DEFAULT_REMEDIABLE)
+
+    try:
+        selection = parse_repo_selection(repos or [])
+    except RepoSelectionError as exc:
+        # markup=False: the value is printed exactly as the user typed it.
+        console.print(f"--repos: {exc}", style="red", markup=False)
+        raise typer.Exit(2) from exc
+    if repos and not selection:
+        # An explicit narrowing must never widen to "every repository".
+        console.print(
+            "--repos: names no repository; omit it to act on every one",
+            style="red",
+            markup=False,
+        )
+        raise typer.Exit(2)
 
     cfg = _load_config(config_file, config_data, org, token_env, console=console)
     if cfg is None:
@@ -354,6 +378,7 @@ def remediate(
             token=token,
             categories=categories,
             apply=apply,
+            repos=selection,
         ),
     )
     raise typer.Exit(code)

{github_security_report-0.16.0 → github_security_report-0.18.0}/src/github_security_report/cli/modes.py

@@ -20,7 +20,7 @@ from typing import NoReturn
 import typer
 from rich.console import Console
 
-from github_security_report import collect, config, layout, runner
+from github_security_report import collect, config, layout, runner, scope
 from github_security_report import remediate as remediate_mod
 from github_security_report.categories import CategoryKey
 from github_security_report.cli import publish
@@ -36,7 +36,9 @@ from github_security_report.cli.outputs import (
     show,
 )
 from github_security_report.client import AuthError, GitHubClient, NetworkError
+from github_security_report.collect.protocols import ClientProtocol
 from github_security_report.config import Config, OrgConfig, ReportConfig
+from github_security_report.models import Repo
 from github_security_report.render import markdown as md_render
 from github_security_report.render import terminal as term_render
 from github_security_report.report import build_org_report
@@ -261,19 +263,35 @@ async def _run_remediate(
     token: str,
     categories: Sequence[CategoryKey],
     apply: bool,
+    repos: Sequence[scope.RepoRef] = (),
 ) -> int:
     """Collect each org's posture and enable (or preview enabling) features.
 
     A single write-capable token drives both the read (collection) and the
     writes for every configured org, so the per-org read ``token_env`` in the
-    config is intentionally bypassed. Returns 1 when any enable failed, else 0.
+    config is intentionally bypassed. ``repos``, when given, limits every
+    category to those repositories; the selection is checked against every
+    org before anything is read or written, and a name that matches nothing,
+    or only an excluded repository, stops the run. Returns 2 for a bad
+    selection, 1 when any write failed, else 0.
     """
     now = dt.datetime.now(dt.timezone.utc)
     failures = 0
     async with GitHubClient(token) as client:
-        for org_cfg in cfg.organizations:
+        selected = await _check_selection(client, cfg, repos, console=console)
+        if selected is None:
+            return 2
+        for index, org_cfg in enumerate(cfg.organizations):
+            if repos and index not in selected:
+                continue  # none of the named repositories live here
+            # The validated repositories themselves, so collection cannot
+            # silently lose one to a second, incomplete listing.
             report = await collect.collect_org(
-                client, org_cfg, org_cfg.report, generated_at=now
+                client,
+                org_cfg,
+                org_cfg.report,
+                generated_at=now,
+                selected=selected[index] if repos else None,
             )
             results = await remediate_mod.remediate_org(
                 client, report, categories=categories, apply=apply
@@ -286,6 +304,77 @@ async def _run_remediate(
                 console,
                 apply=apply,
                 top_n=org_cfg.report.cli_top_n,
+                # This entry's own validated repositories, not every selector:
+                # in a multi-org run each org names only what it collected.
+                limited_to=[r.name for r in selected[index]] if repos else [],
             )
             failures += sum(result.failures for result in results)
     return 1 if failures else 0
+
+
+async def _check_selection(
+    client: ClientProtocol,
+    cfg: Config,
+    repos: Sequence[scope.RepoRef],
+    *,
+    console: Console,
+) -> dict[int, tuple[Repo, ...]] | None:
+    """Each org entry's repositories a selection names, or None to stop.
+
+    Keyed by the entry's position in the configuration, holding only entries
+    with a match: a run collects exactly these, so an entry the selection
+    never touches is skipped. Keyed by position rather than name because the
+    configuration may list one organisation twice with different scoping;
+    each entry must act only on what its own configuration allows.
+
+    Every name must match a repository some configured org has in scope. A
+    name matching nothing is almost always a typo, and one matching only an
+    excluded repository (the exclude list, archived, fork, template, test)
+    must not bypass that exclusion, so both stop the run. So does any org
+    whose listing came back incomplete, since it may hide a repository a
+    selector names. Every problem is reported at once. An empty selection
+    returns an empty mapping, which callers read as "no selection".
+    """
+    if not repos:
+        return {}
+    usable: dict[scope.RepoRef, bool] = dict.fromkeys(repos, False)
+    excluded: dict[scope.RepoRef, list[str]] = {ref: [] for ref in repos}
+    touched: dict[int, tuple[Repo, ...]] = {}
+    problems: list[str] = []
+    for index, org_cfg in enumerate(cfg.organizations):
+        named = await collect.check_named_repos(client, org_cfg, org_cfg.report, repos)
+        if named.partial:
+            # A narrowed run must validate its whole target set, and an
+            # incomplete listing may hide a repository a selector names (a
+            # bare name can match in any org), so it cannot proceed on the
+            # matches it happened to see.
+            problems.append(
+                f"the repository listing for {org_cfg.name} was incomplete, so "
+                "the selection cannot be checked in full; try again"
+            )
+        for ref in repos:
+            if any(ref.matches(org_cfg.name, r.name) for r in named.in_scope):
+                usable[ref] = True
+            excluded[ref].extend(
+                f"{r.full_name} is excluded ({reason})"
+                for r, reason in named.excluded
+                if ref.matches(org_cfg.name, r.name)
+            )
+        if named.in_scope:
+            touched[index] = named.in_scope
+    # A bare name may be usable in one org and excluded in another: only a
+    # name with no usable match anywhere is a problem, so the run acts on the
+    # usable match and never on the excluded one.
+    for ref in repos:
+        if not usable[ref]:
+            problems.extend(excluded[ref])
+    unknown = [str(ref) for ref in repos if not usable[ref] and not excluded[ref]]
+    if unknown:
+        where = ", ".join(org_cfg.name for org_cfg in cfg.organizations)
+        problems.append(f"no repository named {', '.join(unknown)} in {where}")
+    if problems:
+        # markup=False: repository names come from the command line and the API.
+        for problem in problems:
+            console.print(f"--repos: {problem}", style="red", markup=False)
+        return None
+    return touched

{github_security_report-0.16.0 → github_security_report-0.18.0}/src/github_security_report/client/codeql_parsers.py

@@ -65,7 +65,9 @@ def latest_codeql_configurations(
     workflow that fails on every run read as current indefinitely. A
     configuration that has never once succeeded has no last scan at all
     (``None``), which makes it stale however recent its attempts. ``failing``
-    records whether the newest attempt errored.
+    records whether the newest attempt errored. Every analysis id in the
+    configuration is kept, newest first, which is the order GitHub requires
+    them deleted in.
     """
     grouped: dict[str, list[tuple[dt.datetime, Mapping[str, object]]]] = {}
     for analysis in analyses:
@@ -87,12 +89,19 @@ def _errored(analysis: Mapping[str, object]) -> bool:
     return isinstance(error, str) and bool(error.strip())
 
 
+def _analysis_id(analysis: Mapping[str, object]) -> int | None:
+    value = analysis.get("id")
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
 def _configuration(
     category: str, entries: list[tuple[dt.datetime, Mapping[str, object]]]
 ) -> CodeQLConfiguration:
     """One configuration from its analyses, newest first."""
     _newest_at, newest = entries[0]
     succeeded = [created for created, analysis in entries if not _errored(analysis)]
+    # Already newest first: the order GitHub requires them deleted in.
+    ids = [_analysis_id(analysis) for _created, analysis in entries]
     key = newest.get("analysis_key")
     return CodeQLConfiguration(
         category=category,
@@ -100,6 +109,7 @@ def _configuration(
         last_scan_at=succeeded[0] if succeeded else None,
         language=_analysis_language(newest),
         failing=_errored(newest),
+        analysis_ids=tuple(i for i in ids if i is not None),
     )
 
 

{github_security_report-0.16.0 → github_security_report-0.18.0}/src/github_security_report/client/reads.py

@@ -360,3 +360,51 @@ class ReadClient(OrgReadClient):
         readable = resp.status_code == 200
         await resp.aclose()  # only the status matters here
         return readable
+
+    async def codeql_alert_holders(
+        self, org: str, repo: str, branch: str
+    ) -> list[frozenset[str]] | None:
+        """Each open CodeQL alert's holding categories on ``branch``.
+
+        One entry per open alert: the categories of the configurations whose
+        instance of it is still open there. An instance already fixed holds
+        nothing open, so it is not counted. Deleting configurations closes every alert whose
+        holders they all belong to, so a cleanup judges its whole planned
+        deletion set against these, not one deletion at a time. ``None`` when
+        the alerts or any alert's instances could not be read in full: an
+        unknown answer must stop a deletion, never permit one.
+        """
+        base = f"{self._api_url}/repos/{org}/{repo}/code-scanning"
+        ref = f"refs/heads/{branch}"
+        # Filtered to the branch up front: only its alerts can be held open by
+        # a configuration on it, and each costs an instances read below.
+        status, alerts = await self._get_list(
+            f"{base}/alerts",
+            tool_name=CODE_SCANNING_TOOLS[SignalType.CODEQL],
+            state="open",
+            ref=ref,
+        )
+        if status != 200:
+            return None
+        holders: list[frozenset[str]] = []
+        for alert in alerts:
+            status, instances = await self._get_list(
+                f"{base}/alerts/{alert.get('number')}/instances", ref=ref
+            )
+            if status != 200:
+                return None
+            held_by: set[str] = set()
+            for instance in instances:
+                state = instance.get("state")
+                category = instance.get("category")
+                if state not in ("open", "fixed") or not isinstance(category, str):
+                    # An instance whose state or configuration is unknown could
+                    # be the one keeping the alert open; guessing would not
+                    # fail closed.
+                    return None
+                # Only an open instance holds the alert open: a configuration
+                # that has already fixed its instance keeps nothing alive.
+                if state == "open":
+                    held_by.add(category)
+            holders.append(frozenset(held_by))
+        return holders