fix(ci): attach the uncapped-pool opt-out marker to the call it exempts

[LeSingh1]

Stacking note: this touches ci/tools/check_mempool_hygiene.py, the same file as #2538. The two changes are in different functions (_is_capped/_dict_is_capped there, _opted_out here) and different regions of the test file, so they merge cleanly in either order. Reviewable and mergeable independently.

Problem

_opted_out accepts the opt-out marker anywhere on the line above the offending call:

def _opted_out(lines: list[str], node: ast.AST) -> bool:
    """True if the call, or the line above it, carries the opt-out marker."""
    start = max(node.lineno - 2, 0)  # -1 for 0-based, -1 more for a preceding comment
    end = getattr(node, "end_lineno", node.lineno)
    return any(OPT_OUT_MARKER in line for line in lines[start:end])

Nothing requires that preceding line to be a comment, or to have anything to do with the call. So a trailing marker that annotates one statement also exempts the statement on the next line:

with pytest.raises(RuntimeError):
    DeviceMemoryResource(dev, DeviceMemoryResourceOptions(ipc_enabled=True))  # uncapped-pool-ok: raises first
DeviceMemoryResource(dev, DeviceMemoryResourceOptions())   # <- silently exempt

This is the shape a reviewer is least likely to catch: both lines look correctly annotated, and the second one reserves the full address-space window that this check exists to prevent.

The marker text merely appearing in an unrelated string has the same effect:

msg = "see uncapped-pool-ok in AGENTS.md"
DeviceMemoryResource(dev, DeviceMemoryResourceOptions())   # <- silently exempt

Both verified against violations_in() on main: [] in each case, while the identical call with no marker anywhere is correctly reported.

Fix

Bind the marker to the call's own statement. _iter_calls walks the tree carrying the chain of ast.stmt ancestors, and a marker counts when it is:

• inside the call's statement — from the statement's first line through the end of the call, so continuation lines of a multi-line construction count;
• on the header line of a compound statement containing the call (with, def, for, ...), so a marker on a block header still annotates the calls in that block;
• on a dedicated comment line immediately above the statement.

A marker anywhere else no longer counts.

Every documented placement keeps working, including the pytest.raises form from cuda_core/tests/AGENTS.md. Anchoring on the statement rather than the call also fixes a false positive the old window had — a marker on the first line of a multi-line construction never reached the inner options call:

mr = DeviceMemoryResource(  # uncapped-pool-ok: reason
    dev,
    DeviceMemoryResourceOptions(),   # <- reported anyway on main
)

Also documented the placement rule in cuda_core/tests/AGENTS.md, which is what contributors read.

Effect on the tree

None: no opt-out in cuda_core/tests relied on the loose behavior. The existing test_the_live_test_suite_is_clean (which runs main([]) over the real tree) still passes.

Tests

Two parametrized tests appended to ci/tools/tests/test_check_mempool_hygiene.py:

• test_marker_that_does_not_annotate_the_call_does_not_suppress_it — trailing marker on the previous statement, marker inside an unrelated string, comment detached by a blank line.
• test_marker_attached_to_the_call_still_suppresses_it — comment above, indented comment above, inline on the call, continuation line of the same call, first line of a multi-line statement, containing with header, containing def header.

Verification

Executed in full (pure AST analysis, no GPU):

# with the fix
66 passed

# with ci/tools/check_mempool_hygiene.py restored from upstream/main
FAILED ...does_not_suppress_it[trailing-marker-on-previous-statement]
FAILED ...does_not_suppress_it[marker-inside-an-unrelated-string]
FAILED ...still_suppresses_it[first-line-of-a-multiline-statement]
3 failed, 63 passed

(The third is the false positive described above — it fails on main for the opposite reason.)

ruff check / ruff format --check clean on both changed Python files; python -m py_compile clean. Verified index-safely (cp aside, git show upstream/main:<path> >, run, restore) — no staged reverts.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.