coverage --tests: rivet-marker attribution binds to the wrong fn (preceding helper instead of the following #[test])

[avrabe]

Friction

rivet 0.32.0, rivet coverage --tests on pulseengine/varve (commit with markers in crates/varve-core/src/*.rs and crates/varve/tests/cli.rs).

Markers written in the documented shape:

// rivet: verifies REQ-SCOPE-001
#[test]
fn resolution_and_listing_never_write_to_the_core() { ... }

are sometimes attributed to the wrong function in the coverage report. Observed attributions:

• REQ-SCOPE-001 → ambiguous_name_fails_closed_instead_of_choosing (the marker sits on the next test, resolution_and_listing_never_write_to_the_core)
• helper fns reported as tests: store (verifies), varve (verifies), fmt (verifies), load (verifies), find_pin (verifies) — these are non-test helpers/impl fns adjacent to marked tests

The requirement→marker count is right, so rivet verify still advances correctly, but the marker→test-name binding is unreliable — which matters for evidence auditing (an assessor reading the report is pointed at the wrong test, and a future verification-evidence-style check that trusts the binding would validate the wrong thing).

Guess: the scanner binds a marker to the nearest fn by proximity rather than to the first fn after the marker (skipping attributes like #[test]), so intervening helpers or preceding impl fns win.

Repro: pulseengine/varve @ feat/v0.1.0-resolution-core, rivet coverage --tests.

🤖 Filed mid-feature-loop per report-tool-friction.

[avrabe]

Triage from the scheduled routine (first pass on this issue; body has no prior comments).

The friction is well-scoped and the guess in the body — "the scanner binds a marker to the nearest fn by proximity rather than to the first fn after the marker, skipping attributes like #[test]" — reads as a diagnosis, not a hypothesis. That's the shape the AC can lock: marker binds to the first fn item (attribute-transparently) whose span starts after the marker comment, not the nearest one. Once pinned, the fix has one axis to move on.

There's no explicit ## Acceptance Criteria block on the body yet, so the routine can't autopick it. Sketch matching the kill-criterion shape (drop in / revise):

## Acceptance Criteria — `rivet coverage --tests` marker→fn binding

- [ ] Binding rule is source-order-forward and attribute-transparent: for a
      `// rivet: verifies REQ-XXX` marker comment, the target fn is the first
      `fn` item whose declaration span starts **after** the marker's end offset.
      Intervening `#[attr]`, `#[cfg(...)]`, `#[test]`, `doc-comment`, blank
      lines, and other attribute-shaped items are skipped without consuming
      the marker.
- [ ] Non-test items (impl-level helpers, `#[cfg(test)] mod` inner fns,
      `fn` items that are not annotated `#[test]` / `#[tokio::test]` /
      etc.) can never be marker targets — a marker whose next `fn` is a
      non-test raises a coverage-scanner diagnostic ("marker at path:line
      is not attached to a test") rather than silently binding to a helper.
- [ ] Golden-file test on a fixture crate under `rivet-cli/tests/fixtures/`
      that exactly reproduces the reported shapes: (a) marker followed by
      `#[test] fn following_test`, (b) marker followed by
      `#[cfg(test)] #[test] fn`, (c) marker followed by a plain `fn helper`
      then a `#[test] fn actual_test` — the marker resolves to the `#[test]`
      in every case; the helper `fn` case emits the "not a test" diagnostic.
- [ ] Regression fixture for the exact varve names reported
      (`ambiguous_name_fails_closed_...` and
      `resolution_and_listing_never_write_to_the_core`, plus the helper
      fns `store`, `varve`, `fmt`, `load`, `find_pin`): golden coverage
      output binds `REQ-SCOPE-001` to `resolution_and_listing_...`, and
      no helper appears as `<name> (verifies)`.
- [ ] The requirement→marker *count* (which the body notes is already
      right) is unchanged — this fix is binding-only, not count-affecting.
      `rivet verify`'s coverage numbers on a pre-fix fixture stay
      byte-identical after the fix; only the reported test names change.
- [ ] `cargo test -p rivet-cli --tests` and
      `cargo test -p rivet-core --tests` green;
      `cargo clippy --all-targets -- -D warnings` +
      `cargo fmt --all -- --check` clean; `rivet validate` PASS.
- [ ] Commit trailers: `Fixes: REQ-NNN` (file a new REQ for coverage-scanner
      binding correctness, or reuse the existing coverage-attribution REQ if
      one is already carrying this behaviour) + `Refs: #787`.
- [ ] **Explicitly out of scope (file separately if wanted):** binding
      markers to non-`fn` items (`impl` blocks, `mod` blocks); a future
      `verification-evidence`-style check that trusts the binding
      (independent slice, blocked until this lands so it doesn't validate
      the wrong thing); backporting the fix into a `rivet coverage
      --strict-binding` opt-in — flip on the always-correct binding
      directly, no dual mode.

One borderline call worth your input before AC is locked: doc-comment / non-marker comments between the marker and the fn — should they interrupt the binding (i.e. "marker directly precedes the fn, attributes/comments notwithstanding") or should any intervening comment terminate the binding (i.e. "marker only counts if nothing but attributes and whitespace separate it from the fn")? The body's repro cases don't disambiguate. The stricter form ("attributes + whitespace only") is safer for the assessor-audit case since it forbids the confusing "marker separated from its test by a paragraph of prose" shape from ever being valid; the looser form is more permissive to human-authored codebases that use section-header comments. Recommend the strict form unless there's a documented convention that says otherwise.

Process side-rail: https://pulseengine.eu/blog/ is up today (200 OK, unlike the long stretch of 503s across recent triage). The only workflow-relevant post is "Where the seams still show" (2026-07-12), which pins a maturity-classification lens (wired-in-CI / demonstrated-once / still-manual) — orthogonal to this issue's binding-correctness ask, but relevant if the fix is scoped to only go through the CI-gated path. Nothing on the blog speaks to per-issue AC shape, so the kill-criterion posture the routine uses across adjacent triage threads (#468 / #567 / #549 / #546) stands.

Not implemented this run.

---

Generated by Claude Code