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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github-security-report
-Version: 0.15.0
+Version: 0.16.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,8 +36,8 @@ 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.5; extra == 'dev'
-Requires-Dist: syrupy==6.0.0; 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
@@ -101,6 +101,33 @@ if you want to probe everything regardless.
 Further sections report **configuration posture** and **freshness** as plain
 tables (org mode):
 
+- **CodeQL scan health** — two tables beneath **CodeQL: Results/Findings** (the
+  CodeQL alerts table), whose "Clean" says nothing about whether CodeQL is
+  still running:
+  - **Stale Configurations** lists every CodeQL configuration whose last scan
+    trails the default branch's newest commit by more than
+    `codeql_stale_days` (default 30) — the condition GitHub's tool status page
+    flags as *"Code Scanning results may be out of date"*. Each row names the
+    setup type (**Default**, GitHub-managed; or **Advanced**, a workflow in the
+    repository), the language, the last *successful* scan, and the cause:
+    analyses failing (a run that errors still uploads, but its results do not
+    count as a scan), default setup switched off, a workflow removed or
+    disabled, or an advanced workflow
+    **superseded** by default setup (GitHub rejects advanced CodeQL uploads
+    while default setup is on). An *orphaned* configuration will never scan
+    again; delete it from the tool status page once the live setup covers its
+    language.
+  - **Language Coverage** lists repositories where GitHub detects a
+    CodeQL-supported language that no current configuration scans — typically
+    an advanced workflow whose language matrix omits one the repository
+    contains, such as `actions` for its own workflows. On default setup GitHub
+    reports only the languages it is set to scan, so a detected language
+    deliberately left out of default setup is not visible to this check.
+
+  Both consider only repositories where CodeQL has run at least once; the rest
+  already appear in the Results/Findings not-enabled list. Finding a stale
+  configuration means reading each repository's whole CodeQL analysis history,
+  since GitHub cannot filter it by configuration.
 - **Dependabot** — three tables: repositories with vulnerability **alerts not
   enabled**, repositories with **security updates not enabled**, and ecosystems
   with no update `cooldown` configured (mandatory; any value passes).
@@ -118,6 +145,20 @@ tables (org mode):
   exposes no org-wide or GraphQL equivalent) and, like every other category,
   always collected; hide it with the `private_vulnerability_reporting` render
   toggle.
+- **Auto-merge** — repositories where the **Allow auto-merge** setting is off,
+  so a pull request cannot be queued to merge itself once its requirements are
+  met. The setting only offers the option: an auto-merging pull request still
+  waits for the required checks, reviews and branch protections the repository
+  already enforces, so enabling it relaxes nothing. What it removes is the
+  interval between a change becoming mergeable and somebody noticing — the
+  window a reviewed dependency update sits in while the vulnerability it fixes
+  stays unpatched. Read from the batched GraphQL prefetch, so it costs no extra
+  request; hide it with the `auto_merge` render toggle.
+
+The four enablement categories count the repositories with and without the
+feature (plus any whose state could not be read), and by default name whichever
+known list is shorter — see
+[Enabled or disabled repository lists](#enabled-or-disabled-repository-lists).
 
 ## Operating modes
 
@@ -182,6 +223,7 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Secret scanning alerts | Open secret-scanning alerts, across every GitHub pattern category |
 | Issues | Open issues and their labels (GitHub Issues table) |
 | Administration | Dependabot enablement + security-updates status, and effective branch rules |
+| Actions | Workflow state behind a stale CodeQL configuration |
 
 **Organization permissions:**
 
@@ -302,6 +344,7 @@ environment-variable name, never embedded.
     "include_test": false,
     "repo_min_age_days": 28,
     "release_max_age_days": 60,
+    "codeql_stale_days": 30,
     "graph_batch": 10,
     "order": { "style": "auto" }
   },
@@ -326,6 +369,17 @@ individual output. Set a value to `0` to remove the limit entirely and show
 every offender. Each can also be set at the CLI with `--top-n`,
 `--top-n-report`, `--top-n-cli`, and `--top-n-slack`.
 
+`report.codeql_stale_days` (default `30`, minimum `1`) is the CodeQL
+stale-configuration threshold: a configuration is stale once its last scan
+trails the default branch's newest commit by more than that many days. It is
+measured against the branch head rather than the clock, so a repository nobody
+has pushed to is not flagged just for being quiet. GitHub does not publish the
+threshold behind its own "may be out of date" warning; across the
+`lfreleng-actions` estate healthy configurations trailed their head by at most
+five days and abandoned ones by more than eighty, so the default sits well
+clear of both. The same threshold decides which configurations count as current
+for Language Coverage.
+
 The Releases / Tagging section has two independent freshness levers:
 
 - `report.repo_min_age_days` (default `28`, `0` = include all) is a grace
@@ -355,6 +409,23 @@ 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.
 
+Every category reports those exclusions beneath its counts, so an
+organisation-wide list repeats under each one. `report.excluded_display`
+governs that line on every surface:
+
+| Value | Excluded line |
+| ----- | ------------- |
+| `always-show` (default) | Shown under every category |
+| `always-hide` | Never shown |
+| `conditional-hide` | Shown only for a category whose exclusions differ from the organisation's `exclude` list, and then in full |
+
+Hiding the line changes nothing else: every count is unaffected, and the report
+header's repository count already leaves excluded repositories out. So a clean
+category reads `All Clean` once no Excluded line qualifies it. Today every
+category reports the organisation's own list, so `conditional-hide` currently
+hides the same lines `always-hide` does. It differs once a category excludes
+repositories of its own. The `report.json` artifact always lists the exclusions.
+
 Archived and test repositories are excluded from analysis by default. Opt them
 back in with `report.include_archived` / `report.include_test` in the config, or
 for a single run with `--include-archived` / `--include-test`.
@@ -384,16 +455,17 @@ both true.
 
 The example above hides Zizmor on every surface, and keeps Releases / Tagging
 out of the terminal and Slack while still publishing it to the Markdown and HTML
-Pages output. The valid category keys are: `codeql`, `scorecard`, `zizmor`,
-`aislop`, `dependabot_alerts`, `secret_scanning`, `dependabot_alerts_enabled`,
-`dependabot_updates_enabled`, `dependabot_cooldown`, `releases`,
-`mutable_releases`, `private_vulnerability_reporting`, `github_issues`. Like the
-other `report`
-settings, `categories` can be set
-globally and overridden per organisation (overrides merge key-by-key, so
-flipping one output leaves the rest untouched). The machine-readable
-`report.json` artifact always contains the complete dataset, regardless of these
-toggles.
+Pages output. The valid category keys are: `codeql`,
+`codeql_stale_configurations`, `codeql_language_coverage`, `scorecard`,
+`zizmor`, `aislop`, `dependabot_alerts`, `secret_scanning`,
+`dependabot_alerts_enabled`, `dependabot_updates_enabled`,
+`dependabot_cooldown`, `releases`, `mutable_releases`,
+`private_vulnerability_reporting`, `auto_merge`, `github_issues`,
+`pull_requests`, `pull_requests_assigned`. Like the other `report` settings,
+`categories` can be set globally and overridden per organisation (overrides
+merge key-by-key, so flipping one output leaves the rest untouched). The
+machine-readable `report.json` artifact always contains the complete dataset,
+regardless of these toggles.
 
 When several organisations share one Slack channel they render into a single
 combined digest, so the per-org Slack toggles are unioned for that channel: a
@@ -454,6 +526,52 @@ Slack-style ceiling, but they still apply their own row limits — only the
 GitHub Pages report whenever `pages_url` is set and short enough to render as a
 link.
 
+### Enabled or disabled repository lists
+
+The four boolean feature categories — `dependabot_alerts_enabled`,
+`dependabot_updates_enabled`, `private_vulnerability_reporting` and `auto_merge`
+— sort each repository into one of three buckets: enabled, not enabled, or
+**unknown** when the feature's state could not be read. The unknown bucket is
+counted but never named, and never treated as either side, so the enabled and
+not-enabled counts need not sum to the repositories analysed. Beneath the counts,
+one of the two known sides is named; `report.repo_list` chooses which, on every
+surface:
+
+| Value | Names |
+| ----- | ----- |
+| `auto` (default) | Whichever list is shorter |
+| `enabled` | The repositories with the feature on |
+| `disabled` | The repositories with the feature off |
+
+`auto` keeps a footer short whichever way an organisation leans: a feature
+nearly every repository has lists its few holdouts, and one almost none have
+lists its few adopters. Two cases resolve towards the actionable side: a tie
+names the repositories without the feature, and so does a category where
+*nothing* is enabled, since naming an empty list would print nothing where a
+reader wants the repositories to fix. Both sides are always counted, whichever is
+named.
+
+A category can override the global value:
+
+```json
+{
+  "report": {
+    "repo_list": "auto",
+    "categories": {
+      "dependabot_alerts_enabled": { "repo_list": "disabled" }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+Here Dependabot alerts always name the repositories to fix, and the other three
+feature categories name whichever side is shorter. `repo_list` applies only to
+those four categories; setting it on any other is a configuration error, since a
+table with qualitative columns has no enabled list to name. These categories
+render as a name list rather than a one-column table on every surface. The
+`report.json` artifact is unaffected.
+
 ### Per-category row ordering
 
 Each table ships a sensible default ordering — largest backlog first, stalest
@@ -1413,6 +1531,7 @@ enablement endpoint:
 | `dependabot_alerts_enabled` | Dependabot vulnerability alerts |
 | `dependabot_updates_enabled` | Dependabot security updates (plus alerts) |
 | `private_vulnerability_reporting` | Private vulnerability reporting |
+| `auto_merge` | The repository's "Allow auto-merge" setting |
 
 Qualitative findings (Scorecard, zizmor, open Dependabot alerts, cooldown,
 release freshness/mutability) are reported but not auto-remediated. Remediation

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

@@ -57,6 +57,33 @@ if you want to probe everything regardless.
 Further sections report **configuration posture** and **freshness** as plain
 tables (org mode):
 
+- **CodeQL scan health** — two tables beneath **CodeQL: Results/Findings** (the
+  CodeQL alerts table), whose "Clean" says nothing about whether CodeQL is
+  still running:
+  - **Stale Configurations** lists every CodeQL configuration whose last scan
+    trails the default branch's newest commit by more than
+    `codeql_stale_days` (default 30) — the condition GitHub's tool status page
+    flags as *"Code Scanning results may be out of date"*. Each row names the
+    setup type (**Default**, GitHub-managed; or **Advanced**, a workflow in the
+    repository), the language, the last *successful* scan, and the cause:
+    analyses failing (a run that errors still uploads, but its results do not
+    count as a scan), default setup switched off, a workflow removed or
+    disabled, or an advanced workflow
+    **superseded** by default setup (GitHub rejects advanced CodeQL uploads
+    while default setup is on). An *orphaned* configuration will never scan
+    again; delete it from the tool status page once the live setup covers its
+    language.
+  - **Language Coverage** lists repositories where GitHub detects a
+    CodeQL-supported language that no current configuration scans — typically
+    an advanced workflow whose language matrix omits one the repository
+    contains, such as `actions` for its own workflows. On default setup GitHub
+    reports only the languages it is set to scan, so a detected language
+    deliberately left out of default setup is not visible to this check.
+
+  Both consider only repositories where CodeQL has run at least once; the rest
+  already appear in the Results/Findings not-enabled list. Finding a stale
+  configuration means reading each repository's whole CodeQL analysis history,
+  since GitHub cannot filter it by configuration.
 - **Dependabot** — three tables: repositories with vulnerability **alerts not
   enabled**, repositories with **security updates not enabled**, and ecosystems
   with no update `cooldown` configured (mandatory; any value passes).
@@ -74,6 +101,20 @@ tables (org mode):
   exposes no org-wide or GraphQL equivalent) and, like every other category,
   always collected; hide it with the `private_vulnerability_reporting` render
   toggle.
+- **Auto-merge** — repositories where the **Allow auto-merge** setting is off,
+  so a pull request cannot be queued to merge itself once its requirements are
+  met. The setting only offers the option: an auto-merging pull request still
+  waits for the required checks, reviews and branch protections the repository
+  already enforces, so enabling it relaxes nothing. What it removes is the
+  interval between a change becoming mergeable and somebody noticing — the
+  window a reviewed dependency update sits in while the vulnerability it fixes
+  stays unpatched. Read from the batched GraphQL prefetch, so it costs no extra
+  request; hide it with the `auto_merge` render toggle.
+
+The four enablement categories count the repositories with and without the
+feature (plus any whose state could not be read), and by default name whichever
+known list is shorter — see
+[Enabled or disabled repository lists](#enabled-or-disabled-repository-lists).
 
 ## Operating modes
 
@@ -138,6 +179,7 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Secret scanning alerts | Open secret-scanning alerts, across every GitHub pattern category |
 | Issues | Open issues and their labels (GitHub Issues table) |
 | Administration | Dependabot enablement + security-updates status, and effective branch rules |
+| Actions | Workflow state behind a stale CodeQL configuration |
 
 **Organization permissions:**
 
@@ -258,6 +300,7 @@ environment-variable name, never embedded.
     "include_test": false,
     "repo_min_age_days": 28,
     "release_max_age_days": 60,
+    "codeql_stale_days": 30,
     "graph_batch": 10,
     "order": { "style": "auto" }
   },
@@ -282,6 +325,17 @@ individual output. Set a value to `0` to remove the limit entirely and show
 every offender. Each can also be set at the CLI with `--top-n`,
 `--top-n-report`, `--top-n-cli`, and `--top-n-slack`.
 
+`report.codeql_stale_days` (default `30`, minimum `1`) is the CodeQL
+stale-configuration threshold: a configuration is stale once its last scan
+trails the default branch's newest commit by more than that many days. It is
+measured against the branch head rather than the clock, so a repository nobody
+has pushed to is not flagged just for being quiet. GitHub does not publish the
+threshold behind its own "may be out of date" warning; across the
+`lfreleng-actions` estate healthy configurations trailed their head by at most
+five days and abandoned ones by more than eighty, so the default sits well
+clear of both. The same threshold decides which configurations count as current
+for Language Coverage.
+
 The Releases / Tagging section has two independent freshness levers:
 
 - `report.repo_min_age_days` (default `28`, `0` = include all) is a grace
@@ -311,6 +365,23 @@ 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.
 
+Every category reports those exclusions beneath its counts, so an
+organisation-wide list repeats under each one. `report.excluded_display`
+governs that line on every surface:
+
+| Value | Excluded line |
+| ----- | ------------- |
+| `always-show` (default) | Shown under every category |
+| `always-hide` | Never shown |
+| `conditional-hide` | Shown only for a category whose exclusions differ from the organisation's `exclude` list, and then in full |
+
+Hiding the line changes nothing else: every count is unaffected, and the report
+header's repository count already leaves excluded repositories out. So a clean
+category reads `All Clean` once no Excluded line qualifies it. Today every
+category reports the organisation's own list, so `conditional-hide` currently
+hides the same lines `always-hide` does. It differs once a category excludes
+repositories of its own. The `report.json` artifact always lists the exclusions.
+
 Archived and test repositories are excluded from analysis by default. Opt them
 back in with `report.include_archived` / `report.include_test` in the config, or
 for a single run with `--include-archived` / `--include-test`.
@@ -340,16 +411,17 @@ both true.
 
 The example above hides Zizmor on every surface, and keeps Releases / Tagging
 out of the terminal and Slack while still publishing it to the Markdown and HTML
-Pages output. The valid category keys are: `codeql`, `scorecard`, `zizmor`,
-`aislop`, `dependabot_alerts`, `secret_scanning`, `dependabot_alerts_enabled`,
-`dependabot_updates_enabled`, `dependabot_cooldown`, `releases`,
-`mutable_releases`, `private_vulnerability_reporting`, `github_issues`. Like the
-other `report`
-settings, `categories` can be set
-globally and overridden per organisation (overrides merge key-by-key, so
-flipping one output leaves the rest untouched). The machine-readable
-`report.json` artifact always contains the complete dataset, regardless of these
-toggles.
+Pages output. The valid category keys are: `codeql`,
+`codeql_stale_configurations`, `codeql_language_coverage`, `scorecard`,
+`zizmor`, `aislop`, `dependabot_alerts`, `secret_scanning`,
+`dependabot_alerts_enabled`, `dependabot_updates_enabled`,
+`dependabot_cooldown`, `releases`, `mutable_releases`,
+`private_vulnerability_reporting`, `auto_merge`, `github_issues`,
+`pull_requests`, `pull_requests_assigned`. Like the other `report` settings,
+`categories` can be set globally and overridden per organisation (overrides
+merge key-by-key, so flipping one output leaves the rest untouched). The
+machine-readable `report.json` artifact always contains the complete dataset,
+regardless of these toggles.
 
 When several organisations share one Slack channel they render into a single
 combined digest, so the per-org Slack toggles are unioned for that channel: a
@@ -410,6 +482,52 @@ Slack-style ceiling, but they still apply their own row limits — only the
 GitHub Pages report whenever `pages_url` is set and short enough to render as a
 link.
 
+### Enabled or disabled repository lists
+
+The four boolean feature categories — `dependabot_alerts_enabled`,
+`dependabot_updates_enabled`, `private_vulnerability_reporting` and `auto_merge`
+— sort each repository into one of three buckets: enabled, not enabled, or
+**unknown** when the feature's state could not be read. The unknown bucket is
+counted but never named, and never treated as either side, so the enabled and
+not-enabled counts need not sum to the repositories analysed. Beneath the counts,
+one of the two known sides is named; `report.repo_list` chooses which, on every
+surface:
+
+| Value | Names |
+| ----- | ----- |
+| `auto` (default) | Whichever list is shorter |
+| `enabled` | The repositories with the feature on |
+| `disabled` | The repositories with the feature off |
+
+`auto` keeps a footer short whichever way an organisation leans: a feature
+nearly every repository has lists its few holdouts, and one almost none have
+lists its few adopters. Two cases resolve towards the actionable side: a tie
+names the repositories without the feature, and so does a category where
+*nothing* is enabled, since naming an empty list would print nothing where a
+reader wants the repositories to fix. Both sides are always counted, whichever is
+named.
+
+A category can override the global value:
+
+```json
+{
+  "report": {
+    "repo_list": "auto",
+    "categories": {
+      "dependabot_alerts_enabled": { "repo_list": "disabled" }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+Here Dependabot alerts always name the repositories to fix, and the other three
+feature categories name whichever side is shorter. `repo_list` applies only to
+those four categories; setting it on any other is a configuration error, since a
+table with qualitative columns has no enabled list to name. These categories
+render as a name list rather than a one-column table on every surface. The
+`report.json` artifact is unaffected.
+
 ### Per-category row ordering
 
 Each table ships a sensible default ordering — largest backlog first, stalest
@@ -1369,6 +1487,7 @@ enablement endpoint:
 | `dependabot_alerts_enabled` | Dependabot vulnerability alerts |
 | `dependabot_updates_enabled` | Dependabot security updates (plus alerts) |
 | `private_vulnerability_reporting` | Private vulnerability reporting |
+| `auto_merge` | The repository's "Allow auto-merge" setting |
 
 Qualitative findings (Scorecard, zizmor, open Dependabot alerts, cooldown,
 release freshness/mutability) are reported but not auto-remediated. Remediation

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

@@ -63,9 +63,9 @@ dev = [
   "pytest-asyncio==1.4.0",
   "pytest-cov==7.1.0",
   "respx==0.23.1",
-  "syrupy==6.0.0",
+  "syrupy==6.1.1",
   "mypy==2.3.1",
-  "ruff==0.16.5",
+  "ruff==0.16.8",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]
@@ -95,9 +95,9 @@ dev = [
   "pytest-asyncio==1.4.0",
   "pytest-cov==7.1.0",
   "respx==0.23.1",
-  "syrupy==6.0.0",
+  "syrupy==6.1.1",
   "mypy==2.3.1",
-  "ruff==0.16.5",
+  "ruff==0.16.8",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]

{github_security_report-0.15.0 → github_security_report-0.16.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.15.0'
-__version_tuple__ = version_tuple = (0, 15, 0)
+__version__ = version = '0.16.0'
+__version_tuple__ = version_tuple = (0, 16, 0)
 
 __commit_id__ = commit_id = None

github_security_report-0.16.0/src/github_security_report/categories/__init__.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Report category metadata.
+
+A single, render-surface-agnostic registry describing every reporting category
+the tool produces. Each category carries its display title, the pass/fail
+vocabulary used in the standardised summary footer, a documentation URL, and a
+default human description. Renderers read this registry instead of hard-coding
+per-category headings, labels and explanatory text, so a wording change here
+flows to the terminal, Slack, Markdown and HTML surfaces at once.
+
+The registry deliberately holds no behaviour and imports nothing from the rest
+of the package except the leaf ``severity`` and ``secret_patterns`` modules
+(which themselves import nothing from the package), so both the domain models
+and the renderers can depend on it without a cycle. It is split by kind --
+the ranked signals in :mod:`.signals`, the tables in :mod:`.tables` -- and
+merged here, so callers see one registry in render order.
+"""
+
+from __future__ import annotations
+
+from github_security_report.categories.keys import CategoryKey, CategoryMeta
+from github_security_report.categories.signals import SIGNAL_CATEGORIES
+from github_security_report.categories.tables import TABLE_CATEGORIES
+
+__all__ = [
+    "NESTED_CATEGORIES",
+    "REPO_LIST_CATEGORIES",
+    "CategoryKey",
+    "CategoryMeta",
+    "all_categories",
+    "category_meta",
+    "orderable_categories",
+]
+
+_CATEGORIES: dict[CategoryKey, CategoryMeta] = {**SIGNAL_CATEGORIES, **TABLE_CATEGORIES}
+
+
+def category_meta(key: CategoryKey) -> CategoryMeta:
+    """The :class:`CategoryMeta` for ``key`` (registry lookup)."""
+    return _CATEGORIES[key]
+
+
+# Categories rendered as sub-tables beneath another category rather than as
+# sections of their own. The three Dependabot posture tables qualify their
+# parent signal -- "Alerts Enabled" means nothing adrift from "Dependabot:
+# Security Alerts" -- so they travel with it and cannot be positioned
+# independently, and the two CodeQL scan-health tables likewise qualify the
+# CodeQL signal, whose "Clean" means nothing if the scans behind it stopped.
+# Named here rather than in the layout module so the config schema can refuse to
+# accept one in an ordering list, which would otherwise be a setting that
+# validates and then does nothing.
+NESTED_CATEGORIES: frozenset[CategoryKey] = frozenset(
+    {
+        CategoryKey.CODEQL_STALE_CONFIGURATIONS,
+        CategoryKey.CODEQL_LANGUAGE_COVERAGE,
+        CategoryKey.DEPENDABOT_ALERTS_ENABLED,
+        CategoryKey.DEPENDABOT_UPDATES_ENABLED,
+        CategoryKey.DEPENDABOT_COOLDOWN,
+    }
+)
+
+# The boolean feature categories: every repository is either enabled or not, and
+# nothing else is known about it, so both sides are plain repository lists and
+# either can be the one worth naming. These render their names inline rather
+# than as a one-column table, and are the only categories the ``repo_list``
+# setting applies to -- the schema refuses it anywhere else, since a table with
+# qualitative columns has no "enabled" list to swap in.
+REPO_LIST_CATEGORIES: frozenset[CategoryKey] = frozenset(
+    {
+        CategoryKey.DEPENDABOT_ALERTS_ENABLED,
+        CategoryKey.DEPENDABOT_UPDATES_ENABLED,
+        CategoryKey.PRIVATE_VULNERABILITY_REPORTING,
+        CategoryKey.AUTO_MERGE,
+    }
+)
+
+
+def orderable_categories() -> tuple[CategoryMeta, ...]:
+    """Categories an ordering list may name, in registry order.
+
+    Every category except the nested ones, which have no position of their own
+    to configure.
+    """
+    return tuple(
+        meta for meta in _CATEGORIES.values() if meta.key not in NESTED_CATEGORIES
+    )
+
+
+def all_categories() -> tuple[CategoryMeta, ...]:
+    """Every category's metadata, in registry (render) order."""
+    return tuple(_CATEGORIES.values())

github_security_report-0.16.0/src/github_security_report/categories/keys.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""The category identifier and the shape of its metadata.
+
+Leaf types shared by the registry halves in :mod:`.signals` and :mod:`.tables`.
+``CategoryKey`` values are the stable identifiers used by the per-category
+configuration toggles, so treat them as part of the config contract: rename
+with care.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from github_security_report.severity import Severity
+
+
+class CategoryKey(str, Enum):
+    """Stable identifier for one reporting category (also the config key)."""
+
+    CODEQL = "codeql"
+    CODEQL_STALE_CONFIGURATIONS = "codeql_stale_configurations"
+    CODEQL_LANGUAGE_COVERAGE = "codeql_language_coverage"
+    SCORECARD = "scorecard"
+    ZIZMOR = "zizmor"
+    AISLOP = "aislop"
+    DEPENDABOT_ALERTS = "dependabot_alerts"
+    SECRET_SCANNING = "secret_scanning"
+    DEPENDABOT_ALERTS_ENABLED = "dependabot_alerts_enabled"
+    DEPENDABOT_UPDATES_ENABLED = "dependabot_updates_enabled"
+    DEPENDABOT_COOLDOWN = "dependabot_cooldown"
+    RELEASES = "releases"
+    MUTABLE_RELEASES = "mutable_releases"
+    PRIVATE_VULNERABILITY_REPORTING = "private_vulnerability_reporting"
+    AUTO_MERGE = "auto_merge"
+    GITHUB_ISSUES = "github_issues"
+    PULL_REQUESTS = "pull_requests"
+    PULL_REQUESTS_ASSIGNED = "pull_requests_assigned"
+
+
+@dataclass(frozen=True)
+class CategoryMeta:
+    """Display and documentation metadata for one reporting category.
+
+    ``pass_label`` names the healthy state (e.g. ``"Clean"``, ``"Immutable"``)
+    and is what the summary footer reports as ``All <pass_label>`` when nothing
+    needs attention. That collapse wants an adjectival label; a category whose
+    counted wording is a noun phrase ("12 No open issues") sets
+    ``pass_all_label`` to the word that reads correctly after "All" instead.
+    ``fail_label`` names the actionable state for categories
+    with a binary pass/fail axis (enablement, cooldown, mutability, release
+    freshness); it is ``None`` for the severity-ranked signals, whose offenders
+    are enumerated in the table itself rather than as a single failure count.
+    ``description`` is the default explanatory text shown beneath the table on
+    the Markdown and HTML surfaces; a builder may override it at runtime when
+    the wording depends on configuration (e.g. the release-age thresholds).
+    """
+
+    key: CategoryKey
+    title: str
+    pass_label: str
+    fail_label: str | None
+    url: str
+    description: str = ""
+    # Alternative pass wording for the collapsed "All <label>" footer line,
+    # when the counted wording would not read grammatically after "All".
+    pass_all_label: str | None = None
+    # The lowest finding severity that counts as a failure for this category.
+    # A repository fails (appears as an offender) only when it carries a finding
+    # at or above this rung; findings below it fold into the clean count. The
+    # global default is MEDIUM, so Low and Informational findings pass; a
+    # category may lower it (Zizmor uses INFORMATIONAL, so every finding
+    # counts). Meaningful only for the severity-ranked signals; binary
+    # categories ignore it. Overridable per category via the JSON config.
+    fail_severity: Severity = Severity.MEDIUM