feat(contributor-scan): 1.1 regions from entry points, 1.2 the repository driver

Pair scoring could rely on a labelled function; a contributor cannot supply one
-- which code is risky is the question they are asking. Regions now come from
entry points, with a file-level fallback that says it is one, and each carries
only the families its shape and language admit. Ranking uses what
EntryPointRecord already decided (access_level, trust_boundary) rather than a
second opinion computed from the same evidence.

A family is offered only where its arbiter could answer: access_control needs a
handler, so a library file with no entry point is not asked about obligations it
has no siblings to be inconsistent with.

The driver makes the two costs that were free at pair scale explicit. ONE CPG
per repository, reused across regions -- a build is 5-30s on a forty-line
excerpt and per-region builds would make this unusable. And a budget that is a
TOTAL for the run rather than the enumerator's per-region cap of eight, spent
highest-rank-first, with whatever it does not reach counted into
regions_unjudged. A tool that silently analyses a tenth of a repository and
reports a clean result is worse than one that says what it skipped.

Two flaws the tests caught, both mine and both about ownership: the budget
counted calls by reading a client's own usage log, so it silently never tripped
for a client that keeps none -- the driver now counts its own spend through a
wrapper; and the driver trusted its caller to have sorted, when the order the
budget is spent in belongs to whoever holds the budget.

The third was worse and only surfaced because a test failed for the right
reason: the driver passed candidates=() and never enumerated, so a repository
scan would have reported only what the arbiters establish unaided and never
populated the suspicion band -- which supplied 15 of 26 findings in the pair
measurement. It enumerates now.

Sibling audit (Req 8.5) done before writing: family routing lives in exactly one
production place, pipeline._arbitrate, dispatching on spec type. regions_for
returns family names and the driver resolves specs, so that stays true.

750 passing, mypy clean over 96 files, gates byte-identical, zero orphans.

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

tests/test_model_regions.py

@@ -0,0 +1,118 @@
+"""contributor-scan task 1.1: regions come from the code, not from a label (Req 2).
+
+A contributor cannot tell the tool which function is interesting -- that is the whole question they are
+asking. Pair scoring could rely on a labelled function; a repository scan cannot. Regions therefore come from
+entry points, with a file-level fallback that says so, and each region carries only the families its shape and
+language actually admit.
+"""
+
+from __future__ import annotations
+
+
+def _entry(path="api/users.py", function="update_password", access="public", boundary="network"):  # type: ignore[no-untyped-def]
+    from openultrasast.mapping import EntryPointRecord
+
+    return EntryPointRecord(
+        path=path,
+        line=10,
+        end_line=40,
+        function_name=function,
+        name=function,
+        kind="route",
+        access_level=access,
+        trust_boundary=boundary,
+        access_evidence=[],
+        conditions=[],
+        provenance="decorator",
+        rationale="",
+    )
+
+
+def _target(path="api/users.py", language="python"):  # type: ignore[no-untyped-def]
+    from openultrasast.preprocess import FileTarget
+
+    return FileTarget(
+        path=path,
+        absolute_path=f"/repo/{path}",
+        language=language,
+        loc=100,
+        tags=[],
+        has_fuzz_entry_point=False,
+        static_hints=[],
+        reachability_hints=[],
+    )
+
+
+def test_an_entry_point_becomes_a_region() -> None:
+    from openultrasast.model.regions import regions_for
+
+    regions = regions_for([_entry()], [_target()])
+    assert len(regions) == 1
+    assert regions[0].path == "api/users.py" and regions[0].function == "update_password"
+    assert regions[0].source == "entry_point"
+
+
+def test_a_file_with_no_entry_point_still_gets_a_region_that_says_so() -> None:
+    """Req 2.2: a fallback is fine; a fallback that pretends to be an entry point is not."""
+    from openultrasast.model.regions import regions_for
+
+    regions = regions_for([], [_target(path="lib/util.py")])
+    assert len(regions) == 1
+    assert regions[0].function is None
+    assert regions[0].source == "file_fallback"
+
+
+def test_regions_carry_only_families_their_language_has_specs_for() -> None:
+    """Req 2.3. Asking every family of every region is the unbounded version of this."""
+    from openultrasast.model.regions import regions_for
+
+    python = regions_for([_entry()], [_target()])[0]
+    assert "injection" in python.families
+    # C has no dominance or config facts; a C region must not claim them.
+    c_region = regions_for([], [_target(path="src/x.c", language="c")])[0]
+    assert "access_control" not in c_region.families
+    assert "config_secrets" not in c_region.families
+
+
+def test_an_absence_family_is_only_offered_where_there_is_a_handler() -> None:
+    """An obligation needs a reachable operation. A library file with no entry point has no handler to
+    be inconsistent about, so offering access_control there is asking a question the arbiter cannot answer."""
+    from openultrasast.model.regions import regions_for
+
+    handler = regions_for([_entry()], [_target()])[0]
+    library = regions_for([], [_target(path="lib/util.py")])[0]
+    assert "access_control" in handler.families
+    assert "access_control" not in library.families
+
+
+def test_public_entry_points_outrank_internal_ones() -> None:
+    """Ranking uses what EntryPointRecord already carries rather than inventing a signal."""
+    from openultrasast.model.regions import regions_for
+
+    entries = [_entry(path="a.py", function="internal", access="local-only"), _entry(path="b.py", function="exposed", access="public")]
+    targets = [_target(path="a.py"), _target(path="b.py")]
+    ranked = regions_for(entries, targets)
+    assert [r.function for r in ranked] == ["exposed", "internal"], "highest risk first"
+    assert ranked[0].rank > ranked[1].rank
+
+
+def test_the_order_is_total_so_two_runs_agree() -> None:
+    from openultrasast.model.regions import regions_for
+
+    entries = [_entry(path=f"{c}.py", function=f"h{i}") for i, c in enumerate("abc")]
+    targets = [_target(path=f"{c}.py") for c in "abc"]
+    assert regions_for(entries, targets) == regions_for(entries, targets)
+
+
+def test_a_file_with_an_entry_point_is_not_also_a_fallback_region() -> None:
+    """Otherwise every handler is scanned twice and the budget is spent on duplicates."""
+    from openultrasast.model.regions import regions_for
+
+    regions = regions_for([_entry()], [_target()])
+    assert len(regions) == 1
+
+
+def test_an_unsupported_language_yields_no_region() -> None:
+    from openultrasast.model.regions import regions_for
+
+    assert regions_for([], [_target(path="x.rb", language="ruby")]) == ()

tests/test_model_scan.py

@@ -0,0 +1,147 @@
+"""contributor-scan task 1.2: the repository driver (Req 3).
+
+Pair scoring built one CPG per pair and asked one region. A repository has thousands of regions, and the two
+things that were free at pair scale are the two that dominate here:
+
+* **CPG construction.** A build is 5-30s on a 40-line excerpt. Building one per region would make a
+  repository scan unusable, so the driver builds ONE and reuses it.
+* **Model calls.** The enumerator caps candidates at 8 per region, which says nothing about a scan with two
+  thousand regions. The budget is therefore a total for the run, spent on the highest-ranked regions first,
+  and whatever it does not reach is COUNTED rather than quietly dropped.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _region(path="a.py", function="run", families=("injection",), rank=1.0):  # type: ignore[no-untyped-def]
+    from openultrasast.model.regions import ScanRegion
+
+    return ScanRegion(path=path, function=function, language="python", families=families, rank=rank, source="entry_point")
+
+
+class _Backend:
+    """Counts builds, so the one-CPG-per-scan promise is testable rather than asserted."""
+
+    def __init__(self, fail: bool = False) -> None:
+        self.builds = 0
+        self._fail = fail
+
+    def available(self) -> bool:
+        return True
+
+    def build(self, root):  # type: ignore[no-untyped-def]
+        from openultrasast.cpg.backend import CpgResult
+
+        self.builds += 1
+        if self._fail:
+            return None
+        return CpgResult(cpg_path=Path("cpg.bin"), run=lambda q, p: [])
+
+
+def test_one_cpg_is_built_for_the_whole_repository() -> None:
+    from openultrasast.model.scan import scan_repository
+
+    backend = _Backend()
+    regions = tuple(_region(path=f"f{i}.py") for i in range(20))
+    scan_repository(Path("/repo"), regions, backend=backend, client=None, model="")
+    assert backend.builds == 1, "a build per region would make a repository scan unusable"
+
+
+def test_a_failed_build_yields_an_empty_result_not_an_exception() -> None:
+    from openultrasast.model.scan import scan_repository
+
+    result = scan_repository(Path("/repo"), (_region(),), backend=_Backend(fail=True), client=None, model="")
+    assert result.findings == ()
+    assert any("cpg_build_failed" in str(d) for d in result.degradations)
+
+
+def test_the_budget_is_a_total_for_the_run_and_the_remainder_is_counted(tmp_path) -> None:
+    """Req 3.2, 3.3: silently truncating is the failure this exists to prevent.
+
+    Real files on disk, because the driver enumerates candidates from them. A region pointing at a path that
+    does not exist yields no candidates, no model calls, and a budget that never trips -- which would make
+    this test pass for the wrong reason.
+    """
+    from openultrasast.model.scan import ScanBudget, scan_repository
+
+    class _Client:
+        def complete(self, **kw):  # type: ignore[no-untyped-def]
+            from openultrasast.tool_hunter import ChatResponse
+
+            return ChatResponse(content='{"vulnerable": true}')
+
+    source = "import os\n\n\ndef run(cmd):\n    os.system(cmd)\n"
+    for i in range(50):
+        (tmp_path / f"f{i}.py").write_text(source)
+    regions = tuple(_region(path=f"f{i}.py") for i in range(50))
+
+    result = scan_repository(
+        tmp_path,
+        regions,
+        backend=_Backend(),
+        client=_Client(),
+        model="m",
+        budget=ScanBudget(max_model_calls=5, max_regions=50),
+    )
+    assert result.model_calls > 0, "the driver must enumerate candidates and ask the judge about them"
+    assert result.regions_unjudged > 0
+    assert result.regions_scanned + result.regions_unjudged == 50
+    assert any("budget_exhausted" in str(d) for d in result.degradations)
+
+
+def test_the_budget_is_spent_on_the_highest_ranked_regions_first() -> None:
+    from openultrasast.model.scan import ScanBudget, scan_repository
+
+    seen: list[str] = []
+
+    class _Backend2(_Backend):
+        def build(self, root):  # type: ignore[no-untyped-def]
+            from openultrasast.cpg.backend import CpgResult
+
+            self.builds += 1
+            return CpgResult(cpg_path=Path("c.bin"), run=lambda q, p: (seen.append(str(p.get("function"))), [])[1])
+
+    regions = (_region(path="low.py", function="low", rank=0.1), _region(path="high.py", function="high", rank=1.0))
+    scan_repository(Path("/repo"), regions, backend=_Backend2(), client=None, model="", budget=ScanBudget(max_regions=1))
+    assert seen and seen[0] == "high", f"budget spent on the wrong region first: {seen}"
+
+
+def test_findings_are_ordered_by_rung_before_rank() -> None:
+    """Req 3.1: what the model established outranks what the LLM merely proposed."""
+    from openultrasast.model.ladder import Rung
+    from openultrasast.model.pipeline import ModelFinding
+    from openultrasast.model.scan import _ordered
+
+    findings = [
+        (ModelFinding(site="a", family="injection", rung=Rung.SUSPICION), 1.0),
+        (ModelFinding(site="b", family="injection", rung=Rung.ENTAILED), 0.1),
+        (ModelFinding(site="c", family="injection", rung=Rung.CORROBORATED), 0.5),
+    ]
+    assert [f.site for f in _ordered(findings)] == ["b", "c", "a"]
+
+
+def test_the_result_reports_what_the_model_arbitrated() -> None:
+    """Req 1.5: a user should see how much of the result the model established, not have to infer it."""
+    from openultrasast.model.scan import scan_repository
+
+    result = scan_repository(Path("/repo"), (_region(),), backend=_Backend(), client=None, model="")
+    assert set(result.by_rung) >= {"model_entailed", "model_corroborated", "suspicion"}
+    assert result.regions_scanned == 1
+
+
+def test_a_region_is_only_asked_about_families_it_carries() -> None:
+    from openultrasast.model.scan import scan_repository
+
+    asked: list[str] = []
+
+    class _B(_Backend):
+        def build(self, root):  # type: ignore[no-untyped-def]
+            from openultrasast.cpg.backend import CpgResult
+
+            self.builds += 1
+            return CpgResult(cpg_path=Path("c.bin"), run=lambda q, p: (asked.append(q), [])[1])
+
+    scan_repository(Path("/repo"), (_region(families=("injection",)),), backend=_B(), client=None, model="")
+    assert "dominance" not in asked and "config" not in asked