github-security-report 0.22.0__tar.gz → 0.23.0__tar.gz

{github_security_report-0.22.0 → github_security_report-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github-security-report
-Version: 0.22.0
+Version: 0.23.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
@@ -200,7 +200,8 @@ tables (org mode):
   enabled count out of the applicable count per language, such as
   `python 30/32 · go 5/5 · javascript-typescript 10/12`. See
   [ADR-0006](docs/adr/0006-github-code-quality.md); hide it with the
-  `code_quality` render toggle.
+  `code_quality` render toggle, or leave fixture repositories out of it alone
+  with its `exclude` patterns (see [Per-category exclusions](#per-category-exclusions)).
 - **Workflow Failures** — repositories whose GitHub Actions workflows failed
   in the window, ranked by failed runs. The motivating case is the bulk
   Dependabot merge whose integration tests need credentials, so they run
@@ -532,10 +533,11 @@ governs that line on every surface:
 
 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.
+category reads `All Clean` once no Excluded line qualifies it. Every category
+reports the organisation's own list unless it excludes repositories of its own
+(see [Per-category exclusions](#per-category-exclusions)), so with
+`conditional-hide` the line survives only beneath such a category. 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
@@ -686,6 +688,40 @@ 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 exclusions
+
+A category can leave repositories out that every other category still reports,
+with `report.categories.<key>.exclude`: a list of regular expressions searched
+against the repository name, case-insensitively, so `^test-` drops every
+repository whose name starts with `test-` and `^fixture$` drops exactly
+`fixture`. The motivating case is Code Quality, which is billed per committer:
+an organisation that reports its test repositories (`include_test`) still has
+no reason to pay for scanning them, and wants the section to list only the
+repositories worth switching on:
+
+```json
+{
+  "report": {
+    "include_test": true,
+    "categories": {
+      "code_quality": { "exclude": ["^test-"] }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+An excluded repository is neither a row nor a count in that category, and
+`remediate --category code_quality` never writes to it. It is not dropped
+silently: the category's **Excluded** footer line names it alongside the
+organisation's own `exclude` list, and `report.json` carries the category's full
+list under `category_excluded`. Under `excluded_display: conditional-hide` that
+footer line is exactly the one that stays. An organisation's own `exclude` list
+replaces the inherited one rather than adding to it, as every other
+`categories` key does; a pattern that does not compile is a configuration
+error. `exclude` applies to `code_quality` only; setting it on any other
+category is a configuration error, since no other table yet applies it.
+
 ### Per-category row ordering
 
 Each table ships a sensible default ordering — largest backlog first, stalest

{github_security_report-0.22.0 → github_security_report-0.23.0}/README.md

@@ -156,7 +156,8 @@ tables (org mode):
   enabled count out of the applicable count per language, such as
   `python 30/32 · go 5/5 · javascript-typescript 10/12`. See
   [ADR-0006](docs/adr/0006-github-code-quality.md); hide it with the
-  `code_quality` render toggle.
+  `code_quality` render toggle, or leave fixture repositories out of it alone
+  with its `exclude` patterns (see [Per-category exclusions](#per-category-exclusions)).
 - **Workflow Failures** — repositories whose GitHub Actions workflows failed
   in the window, ranked by failed runs. The motivating case is the bulk
   Dependabot merge whose integration tests need credentials, so they run
@@ -488,10 +489,11 @@ governs that line on every surface:
 
 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.
+category reads `All Clean` once no Excluded line qualifies it. Every category
+reports the organisation's own list unless it excludes repositories of its own
+(see [Per-category exclusions](#per-category-exclusions)), so with
+`conditional-hide` the line survives only beneath such a category. 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
@@ -642,6 +644,40 @@ 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 exclusions
+
+A category can leave repositories out that every other category still reports,
+with `report.categories.<key>.exclude`: a list of regular expressions searched
+against the repository name, case-insensitively, so `^test-` drops every
+repository whose name starts with `test-` and `^fixture$` drops exactly
+`fixture`. The motivating case is Code Quality, which is billed per committer:
+an organisation that reports its test repositories (`include_test`) still has
+no reason to pay for scanning them, and wants the section to list only the
+repositories worth switching on:
+
+```json
+{
+  "report": {
+    "include_test": true,
+    "categories": {
+      "code_quality": { "exclude": ["^test-"] }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+An excluded repository is neither a row nor a count in that category, and
+`remediate --category code_quality` never writes to it. It is not dropped
+silently: the category's **Excluded** footer line names it alongside the
+organisation's own `exclude` list, and `report.json` carries the category's full
+list under `category_excluded`. Under `excluded_display: conditional-hide` that
+footer line is exactly the one that stays. An organisation's own `exclude` list
+replaces the inherited one rather than adding to it, as every other
+`categories` key does; a pattern that does not compile is a configuration
+error. `exclude` applies to `code_quality` only; setting it on any other
+category is a configuration error, since no other table yet applies it.
+
 ### Per-category row ordering
 
 Each table ships a sensible default ordering — largest backlog first, stalest

{github_security_report-0.22.0 → github_security_report-0.23.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.22.0'
-__version_tuple__ = version_tuple = (0, 22, 0)
+__version__ = version = '0.23.0'
+__version_tuple__ = version_tuple = (0, 23, 0)
 
 __commit_id__ = commit_id = None

{github_security_report-0.22.0 → github_security_report-0.23.0}/src/github_security_report/categories/__init__.py

@@ -24,6 +24,7 @@ from github_security_report.categories.signals import SIGNAL_CATEGORIES
 from github_security_report.categories.tables import TABLE_CATEGORIES
 
 __all__ = [
+    "EXCLUDABLE_CATEGORIES",
     "NESTED_CATEGORIES",
     "REPO_LIST_CATEGORIES",
     "CategoryKey",
@@ -76,6 +77,15 @@ REPO_LIST_CATEGORIES: frozenset[CategoryKey] = frozenset(
 )
 
 
+# Categories that take an ``exclude`` list of their own, dropping repositories
+# from that one category while every other still reports them. A repository
+# excluded this way is counted on the category's Excluded footer line, so the
+# omission stays visible, and remediation never writes it. Only the categories
+# whose builders apply the list are named: the schema refuses it anywhere else,
+# where it would validate and then do nothing.
+EXCLUDABLE_CATEGORIES: frozenset[CategoryKey] = frozenset({CategoryKey.CODE_QUALITY})
+
+
 def orderable_categories() -> tuple[CategoryMeta, ...]:
     """Categories an ordering list may name, in registry order.
 

{github_security_report-0.22.0 → github_security_report-0.23.0}/src/github_security_report/cli/serialise.py

@@ -83,6 +83,15 @@ def _org_to_dict(org: OrgReport, hidden: Collection[CategoryKey] = ()) -> dict:
         "partial": org.partial,
         # Repositories explicitly excluded from analysis (per-org exclude list).
         "excluded": [r.full_name for r in org.excluded_repos],
+        # Categories excluding repositories of their own (a category's
+        # `exclude` patterns), each with its full list: the organisation's
+        # exclusions above plus the category's. Absent categories report the
+        # organisation's list alone.
+        "category_excluded": {
+            key.value: [r.full_name for r in repos]
+            for key, repos in org.category_excluded.items()
+            if key not in suppressed
+        },
         # Every category below, in the order the rendered surfaces drew it.
         # The keyed structure that follows is stable regardless, but a consumer
         # building its own view can reproduce the published layout instead of

{github_security_report-0.22.0 → github_security_report-0.23.0}/src/github_security_report/collect/extras.py

@@ -20,6 +20,7 @@ import asyncio
 import logging
 
 from github_security_report import codeql, layout, malware, posture
+from github_security_report.categories import CategoryKey
 from github_security_report.code_quality import CodeQualitySetup, applicable_languages
 from github_security_report.collect.codeql import collect_codeql_facts
 from github_security_report.collect.context import (
@@ -45,7 +46,7 @@ from github_security_report.pulls import (
     build_assigned_pull_requests_table,
     build_pull_requests_table,
 )
-from github_security_report.report import OrgReport
+from github_security_report.report import OrgReport, TableSection
 
 log = logging.getLogger(__name__)
 
@@ -122,6 +123,31 @@ async def _posture_for_repo(repo: Repo, ctx: OrgCollectContext) -> RepoPosture:
     )
 
 
+def _build_code_quality(
+    report: OrgReport, postures: list[RepoPosture], report_cfg: ReportConfig
+) -> tuple[TableSection, dict[str, tuple[str, ...]]]:
+    """The Code Quality table and its remediation plan, less the excluded.
+
+    A repository the category's own ``exclude`` patterns match is dropped
+    before the table is built, so it is neither a row nor a count nor a
+    remediation target, and is recorded as excluded for this category alone:
+    its footer then lists it alongside the organisation's own exclusions,
+    while every other category still reports the repository.
+    """
+    kept: list[RepoPosture] = []
+    dropped: list[Repo] = []
+    for p in postures:
+        if report_cfg.category_excludes(CategoryKey.CODE_QUALITY, p.repo.name):
+            dropped.append(p.repo)
+        else:
+            kept.append(p)
+    if dropped:
+        report.category_excluded[CategoryKey.CODE_QUALITY] = sorted(
+            (*report.excluded_repos, *dropped), key=lambda r: r.name
+        )
+    return posture.build_code_quality_table(kept), posture.code_quality_writes(kept)
+
+
 async def _attach_author_tables(
     report: OrgReport,
     in_scope: list[Repo],
@@ -251,8 +277,9 @@ async def attach_extra_tables(
         sweep_readable=ctx.sweep_status.get("dependabot") == 200,
         generated_at=report.generated_at,
     )
-    report.code_quality = posture.build_code_quality_table(postures)
-    report.code_quality_writes = posture.code_quality_writes(postures)
+    report.code_quality, report.code_quality_writes = _build_code_quality(
+        report, postures, report_cfg
+    )
     report.codeql_tables = codeql.build_codeql_tables(
         codeql_facts, stale_days=report_cfg.codeql_stale_days
     )

{github_security_report-0.22.0 → github_security_report-0.23.0}/src/github_security_report/config/blocks.py

@@ -11,6 +11,7 @@ with a usable error. Those parsers live here; the top-level loader in
 
 from __future__ import annotations
 
+import re
 from collections.abc import Mapping
 from dataclasses import replace
 from types import MappingProxyType
@@ -227,6 +228,27 @@ def _require_reachable_warning(
         )
 
 
+def _exclude_patterns_from(key: str, raw: list[str]) -> tuple[re.Pattern[str], ...]:
+    """Compile a category's ``exclude`` list, naming the pattern that fails.
+
+    Compiled once here rather than on every repository, and rejected at load
+    time rather than mid-run: a pattern that does not compile would otherwise
+    surface only after the whole organisation had been read. An oversized
+    repeat count raises ``OverflowError`` and deep nesting ``RecursionError``
+    rather than ``re.error``, so those are caught too.
+    """
+    patterns: list[re.Pattern[str]] = []
+    for text in raw:
+        try:
+            patterns.append(re.compile(text, re.IGNORECASE))
+        except (re.error, OverflowError, RecursionError) as exc:
+            raise ConfigError(
+                f"report.categories.{key}.exclude pattern {text!r} is not a "
+                f"valid regular expression: {exc}"
+            ) from exc
+    return tuple(patterns)
+
+
 def _categories_from(
     data: dict, base: Mapping[str, CategoryToggle]
 ) -> Mapping[str, CategoryToggle]:
@@ -267,5 +289,10 @@ def _categories_from(
             repo_list=(
                 RepoList(raw["repo_list"]) if "repo_list" in raw else current.repo_list
             ),
+            exclude=(
+                _exclude_patterns_from(key, raw["exclude"])
+                if "exclude" in raw
+                else current.exclude
+            ),
         )
     return MappingProxyType(merged)

{github_security_report-0.22.0 → github_security_report-0.23.0}/src/github_security_report/config/models.py

@@ -10,6 +10,7 @@ defaults they fall back to. Construction from raw JSON lives in
 from __future__ import annotations
 
 import datetime as dt
+import re
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 from types import MappingProxyType
@@ -94,7 +95,10 @@ class CategoryToggle:
     ordering of a generic table with a list of column names; ``None`` keeps the
     ordering the table's builder chose. ``repo_list`` overrides which side of a
     boolean feature category is named (see :class:`RepoList`); ``None`` falls
-    back to the report-wide ``repo_list``.
+    back to the report-wide ``repo_list``. ``exclude`` drops the repositories
+    whose name matches any of its regular expressions from this one category
+    (see :data:`~github_security_report.categories.EXCLUDABLE_CATEGORIES`);
+    they are reported on its Excluded footer line rather than dropped silently.
     """
 
     enabled: bool = True
@@ -103,6 +107,7 @@ class CategoryToggle:
     top_n: int | None = None
     sort: tuple[str, ...] | None = None
     repo_list: RepoList | None = None
+    exclude: tuple[re.Pattern[str], ...] = ()
 
     def shows_on(self, output: str) -> bool:
         """Whether this category renders on ``output`` (cli/slack/markdown/html)."""
@@ -404,6 +409,17 @@ class ReportConfig:
             return toggle.repo_list
         return self.repo_list
 
+    def category_excludes(self, key: CategoryKey, name: str) -> bool:
+        """Whether category ``key`` drops repository ``name`` by its own list.
+
+        Patterns are searched rather than fully matched, so ``^test-`` reads
+        as the prefix it looks like, and compiled case-insensitively, since
+        GitHub repository names are. False for an unconfigured category: only
+        the organisation's ``exclude`` list removes a repository everywhere.
+        """
+        toggle = self.categories.get(key.value)
+        return toggle is not None and any(p.search(name) for p in toggle.exclude)
+
 
 @dataclass(frozen=True)
 class OrgConfig:

{github_security_report-0.22.0 → github_security_report-0.23.0}/src/github_security_report/config/schema.py

@@ -9,6 +9,7 @@ weekdays), the error raised on invalid input, and ``CONFIG_SCHEMA`` itself.
 from __future__ import annotations
 
 from github_security_report.categories import (
+    EXCLUDABLE_CATEGORIES,
     REPO_LIST_CATEGORIES,
     CategoryMeta,
     all_categories,
@@ -81,8 +82,9 @@ def _category_schema(meta: CategoryMeta) -> dict:
     """The schema for one category's block under ``report.categories``.
 
     ``repo_list`` is offered only to the boolean feature categories, the only
-    ones with an enabled list to name: anywhere else it would validate and then
-    do nothing, so it is left out and the schema rejects it by name.
+    ones with an enabled list to name, and ``exclude`` only to the categories
+    whose builders apply it: anywhere else either would validate and then do
+    nothing, so it is left out and the schema rejects it by name.
     """
     properties: dict = {
         "enabled": {"type": "boolean"},
@@ -110,6 +112,15 @@ def _category_schema(meta: CategoryMeta) -> dict:
     }
     if meta.key in REPO_LIST_CATEGORIES:
         properties["repo_list"] = {"enum": REPO_LIST_VALUES}
+    if meta.key in EXCLUDABLE_CATEGORIES:
+        # Regular expressions searched against the repository name, case-
+        # insensitively; a match drops the repository from this category only
+        # and lists it on the category's Excluded footer line. The loader
+        # rejects a pattern that does not compile, which JSON Schema cannot.
+        properties["exclude"] = {
+            "type": "array",
+            "items": {"type": "string", "minLength": 1},
+        }
     return {"type": "object", "additionalProperties": False, "properties": properties}
 
 

{github_security_report-0.22.0 → github_security_report-0.23.0}/src/github_security_report/report/aggregate.py

@@ -59,11 +59,11 @@ class OrgReport:
     # organisation's baseline: every category reports it unless
     # ``category_excluded`` gives that category a list of its own.
     excluded_repos: list[Repo] = field(default_factory=list)
-    # Exclusions for a category that differ from the organisation baseline.
-    # Absent keys inherit ``excluded_repos``, which today is every category: no
-    # builder yet excludes repositories per category. It is the seam a
-    # category-specific exclusion attaches to, and what the conditional-hide
-    # footer setting compares against the baseline.
+    # Exclusions for a category that differ from the organisation baseline:
+    # the baseline plus the repositories the category's own ``exclude``
+    # patterns dropped (see ``categories.EXCLUDABLE_CATEGORIES``). Absent keys
+    # inherit ``excluded_repos``. This is what the conditional-hide footer
+    # setting compares against the baseline.
     category_excluded: dict[CategoryKey, list[Repo]] = field(default_factory=dict)
     # Extra Dependabot posture tables rendered as sub-sections beneath the
     # Dependabot signal heading (alerts not enabled, security updates not