feat(reports): say what was looked for, and what cannot be decided

contributor-scan 2.16, implementing the approved Req 5.6. `c/memory`
scored zero true positives across 89k lines of C and three distinct
classes of false one, for a structural reason: it models string CALLS and
libpng overflows through arithmetic.

The task allowed retiring the family. Kept, scoped and stated instead --
`strcpy` misuse is real in plenty of C and the family earns its place for
that. Retiring it would have removed the disclosure along with the
coverage, leaving a C scan silent for a reason nobody could read.

**Its own description was the quiet-failure risk.** It claimed "bounds,
lifetime, arithmetic", which is exactly what it does not decide. It now
names the APIs it models, and a new `limits` field in families.toml says
what it cannot: an overflow expressed as an index, a pointer offset, or a
memcpy whose size is computed -- which is how most real C overflows are
written, and how every one of libpng's is.

A limit recorded in a fact table nobody reads is no better than silence, so
the report renders it. **What was analysed** lists every family offered to
a region whether or not it found anything, because a family that ran and
reported nothing is the case a reader is most likely to misread, and it
states plainly that silence means no fact table covered the code rather
than that the code is safe.

The counts are derived from the fact tables the arbiter actually used, so
they cannot drift from what the engine looked for; only the limit sentence
is authored, because "cannot decide an overflow expressed as an index" is a
statement about an abstraction and no table can produce it.

A C scan that finds nothing now says:

  | c | `memory` | 121 | 9 |
  **`memory` (c)** — Models CALLS, not arithmetic...

Gates byte-identical.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01T7XD7x5KonMdmGRkp63EQG

src/openultrasast/cli.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import argparse
 import json
 import tempfile
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, replace
 from pathlib import Path
 from time import perf_counter
@@ -538,6 +538,10 @@ def _run_scan(path: Path, config_path: Path, mode: str, fail_on: str) -> ScanOut
             wrote_verdicts = True
             plan = record_completed(plan, Stage.REGRESS)
     worth_fixing_payload = _worth_fixing_payload(verdict_records) if wrote_verdicts else None
+    # Req 5.6: what each family could see, for the report. Absent when the model layer did not run --
+    # and a scan with no model layer states no limits because it made no claims.
+    coverage_rows = model_payload.get("coverage") if isinstance(model_payload, dict) else None
+    coverage_for_report = coverage_rows if isinstance(coverage_rows, list) and coverage_rows else None
     runtime.run_stage(
         "report",
         lambda: write_markdown_report(
@@ -550,6 +554,7 @@ def _run_scan(path: Path, config_path: Path, mode: str, fail_on: str) -> ScanOut
             overlay=overlay_records if wrote_overlay else None,
             obligations=obligations_cited or None,
             obligations_summary=obligations_payload or None,
+            coverage=coverage_for_report,
         ),
     )
     runtime.run_stage(
@@ -872,7 +877,9 @@ def _model_skipped(reason: str) -> dict[str, object]:
     return {**_model_payload(None), "skipped": reason}
 
 
-def _model_payload(result: object, *, unjudged_paths: tuple[str, ...] = ()) -> dict[str, object]:
+def _model_payload(
+    result: object, *, unjudged_paths: tuple[str, ...] = (), coverage: Sequence[Mapping[str, object]] = ()
+) -> dict[str, object]:
     """What the scan records about the model layer.
 
     `unjudged_sample` names the regions the budget did not reach, lowest-ranked first. Counting them is the
@@ -892,6 +899,7 @@ def _model_payload(result: object, *, unjudged_paths: tuple[str, ...] = ()) -> d
         "query_seconds": getattr(result, "query_seconds", 0.0),
         "query_seconds_by_kind": dict(getattr(result, "query_seconds_by_kind", {}) or {}),
         "arbitrate_seconds": getattr(result, "arbitrate_seconds", 0.0),
+        "coverage": list(coverage),
     }
 
 
@@ -929,6 +937,12 @@ def _run_model_layer(
     if not regions:
         return [], _model_skipped("no_regions")
 
+    # Req 5.6: what each family could see, recorded whether or not it found anything. A family that ran
+    # and reported nothing is the case a reader is most likely to misread.
+    from .model.report import coverage_rows
+
+    coverage = coverage_rows(regions)
+
     resolved = resolve_chat_endpoint(config)
     client = resolved[0] if resolved else None
     if client is None:
@@ -952,7 +966,7 @@ def _run_model_layer(
     # The regions the budget did not reach, weakest first -- the evidence an exclusion list is built from.
     unjudged = tuple(region.path for region in regions[result.regions_scanned :][:10])
     findings = [_finding_from_model(item) for item in result.findings]
-    return findings, _model_payload(result, unjudged_paths=unjudged)
+    return findings, _model_payload(result, unjudged_paths=unjudged, coverage=coverage)
 
 
 def _finding_from_model(item: object) -> StaticFinding:

src/openultrasast/model/report.py

@@ -82,3 +82,59 @@ def render_findings(findings: Sequence[StaticFinding]) -> str:
 
 
 __all__ = ["SliceRow", "overfitting_gap", "render", "render_findings"]
+
+
+def coverage_rows(regions: Sequence[object]) -> list[dict[str, object]]:
+    """What each family actually modelled for the languages scanned, and what it cannot decide (Req 5.6).
+
+    Derived, not asserted: the count is the size of the fact table the arbiter used, so it cannot drift from
+    what the engine really looked for. The `limits` string is authored, reviewed and committed in
+    `families.toml`, because "cannot decide an overflow expressed as an index" is a statement about an
+    abstraction and no table can produce it.
+
+    Reported for every family that was OFFERED to a region, not only those that produced findings -- a family
+    that ran and found nothing is exactly the case a reader is most likely to misread, and the one Req 5.6
+    exists for.
+    """
+    from .specs import config_specs, dominance_specs, taint_specs
+    from .taxonomy import load_families
+
+    taxonomy = load_families()
+    limits = {family.id: family.limits for family in taxonomy.families}
+    described = {family.id: family.description for family in taxonomy.families}
+
+    offered: dict[tuple[str, str], int] = {}
+    for region in regions:
+        language = str(getattr(region, "language", ""))
+        for family in getattr(region, "families", ()):
+            offered.setdefault((language, str(family)), 0)
+            offered[(language, str(family))] += 1
+
+    rows: list[dict[str, object]] = []
+    for (language, family), region_count in sorted(offered.items()):
+        modelled = _modelled_count(language, family, taint_specs, dominance_specs, config_specs)
+        rows.append(
+            {
+                "language": language,
+                "family": family,
+                "regions": region_count,
+                "modelled": modelled,
+                "description": described.get(family, ""),
+                "limits": limits.get(family, ""),
+            }
+        )
+    return rows
+
+
+def _modelled_count(language: str, family: str, taint_specs, dominance_specs, config_specs) -> int:  # type: ignore[no-untyped-def]
+    """How many operations the arbiter for this family can even see in this language."""
+    spec = taint_specs(language=language).get(family)
+    if spec is not None:
+        return len(spec.sinks)
+    spec = dominance_specs(language=language).get(family)
+    if spec is not None:
+        return len(spec.operations)
+    spec = config_specs(language=language).get(family)
+    if spec is not None:
+        return len(spec.settings)
+    return 0

src/openultrasast/model/taxonomy.py

@@ -31,7 +31,7 @@ VERIFIER_KINDS = ("canary", "static", "none")
 Relation = Literal["same", "parent_child", "lateral", "fabricated"]
 DEFAULT_FAMILIES_PATH = Path(__file__).resolve().parents[1] / "ruleset" / "families.toml"
 
-_FAMILY_FIELDS = frozenset({"id", "description", "cwes", "mechanisms", "verifier", "parent"})
+_FAMILY_FIELDS = frozenset({"id", "description", "cwes", "mechanisms", "verifier", "parent", "limits"})
 _TOP_FIELDS = frozenset({"version", "family"})
 
 
@@ -47,6 +47,10 @@ class Family:
     mechanisms: frozenset[str]
     verifier: str  # VERIFIER_KINDS
     parent: str | None = None  # a family this one specializes; partial credit when one side is the other's parent
+    # What this family's abstraction CANNOT decide, in the words a reader needs. Empty means no limit has
+    # been stated, which is not the same as no limit existing -- and a family that has one and does not say
+    # so lets a silent scan read as a clean bill of health (Req 5.6).
+    limits: str = ""
 
 
 @dataclass(frozen=True)
@@ -153,6 +157,7 @@ def _family(source: Path, entry: dict[str, object]) -> Family:
         mechanisms=frozenset(mechanisms),
         verifier=verifier,
         parent=str(parent) if parent else None,
+        limits=str(entry.get("limits", "") or "").strip(),
     )
 
 

src/openultrasast/reports.py

@@ -22,6 +22,7 @@ def write_markdown_report(
     mechanisms: Mapping[str, Mapping[str, object]] | None = None,
     obligations: Mapping[str, Mapping[str, object]] | None = None,
     obligations_summary: Mapping[str, object] | None = None,
+    coverage: Sequence[Mapping[str, object]] | None = None,
 ) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     verification_by_id = _verification_by_id(verifications or [])
@@ -86,6 +87,8 @@ def write_markdown_report(
             cited_obligations[finding.finding_id] = info_o
             _append_obligation_lines(lines, info_o, (mechanisms or {}).get(str(info_o.get("known_fix") or "")))
         lines.extend(["", finding.rationale, ""])
+    if coverage:
+        _append_coverage(lines, coverage)
     if patterned:
         _append_pattern_matches(lines, patterned)
     if cited:
@@ -391,6 +394,36 @@ def _crowded_pattern_rules(findings: Sequence[StaticFinding]) -> list[StaticFind
     ]
 
 
+def _append_coverage(lines: list[str], coverage: Sequence[Mapping[str, object]]) -> None:
+    """What was looked for, and what could not be decided (Req 5.6).
+
+    A scan that reports nothing has established that nothing it MODELS was found. That is not the same as
+    finding nothing, and the difference is the whole reason this section exists: a silent report read as a
+    clean bill of health is worse than a noisy one, because the reader acts on it.
+    """
+    lines.extend(
+        [
+            "## What was analysed",
+            "",
+            "Each family below was offered to at least one region. **A family that reported nothing has "
+            "established only that nothing it models was found** — silence here means no fact table covered "
+            "the code, not that the code is safe.",
+            "",
+            "| language | family | regions | operations modelled |",
+            "| --- | --- | --- | --- |",
+        ]
+    )
+    for row in coverage:
+        lines.append(f"| {row.get('language')} | `{row.get('family')}` | {row.get('regions')} | {row.get('modelled')} |")
+    lines.append("")
+
+    stated = [row for row in coverage if str(row.get("limits") or "")]
+    if stated:
+        lines.extend(["### Stated limits", ""])
+        for row in stated:
+            lines.extend([f"**`{row.get('family')}` ({row.get('language')})** — {row.get('limits')}", ""])
+
+
 def _is_pattern_only(finding: StaticFinding) -> bool:
     """Is a text match the only thing behind this finding?
 

src/openultrasast/ruleset/families.toml

@@ -86,7 +86,8 @@ verifier = "none"
 
 [[family]]
 id = "memory"
-description = "Memory safety in C and C++: bounds, lifetime, arithmetic. Measured on the vendored slice, never gated; specialized systems own this class."
+description = "Misuse of unbounded string and format APIs in C and C++: a tainted value reaching gets, strcpy, strcat, sprintf or a non-literal format string."
+limits = """Models CALLS, not arithmetic. It cannot decide an overflow expressed as an index, a pointer offset, or a memcpy whose size is computed -- which is how most real C overflows are written, and how every one of libpng's is. A scan of C code that reports nothing from this family has established that no tainted value reached a modelled string API, and nothing at all about its buffer arithmetic."""
 cwes = [
     "CWE-119",
     "CWE-120",