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/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(),
     )