Support bit and bit[n] subroutine return values, including return measure q

[TheGupta2012]

Closes #387

Problem

bit x = f(); crashed with AttributeError: 'NoneType' object has no attribute 'value' — validate_return_statement read return_type.size.value unconditionally, and bit carries no size. bit[n] returns did not crash but emitted an unresolved f() call, since a bit declaration survives unrolling while the subroutine definition does not. return measure q; failed earlier still: _visit_measurement never applied the function qubit transform, so any measurement on a formal argument raised "Missing register declaration for 'q'".

Approach

• The declared return width is evaluated by the caller and passed into validate_return_statement. A cast failure is re-raised as Return type mismatch for subroutine 'f'. Expected bit[2] but got float, naming both types.
• A bit-returning call is replaced by the expression standing in for its return value: a BitstringLiteral when the register is statically known, a reference when it is not. The substitution is applied to a copy of the declaration/assignment, so the source AST keeps its call and the module can be unrolled again (depth() re-unrolls a copy).
• _visit_measurement now rewrites its qubit operand innermost scope outwards, exactly as _visit_reset already does. This removes the # TODO: handle in-function measurements.

Temp-bit decision for return measure q;

A measurement has no compile-time value, so the return expression cannot fold to a literal. A temporary bit register is synthesised at the call site (__<fn>_return_<n>, sized from the declared return type) and the measurement targets it; the caller's variable is then initialised from that register:

bit[1] __f_return_0;
__f_return_0[0] = measure q[0];
bit[1] x = __f_return_0;

Reasoning: the emitted program stays valid OpenQASM — a measurement needs a classical target, and folding a runtime value into the caller's variable would emit a stale "0". Each call gets its own numbered register, so repeated calls do not collide.

Assign-then-return (bit c; c = measure q; return c;) needs no temp — the local bit c; already reaches the caller's output, so the identifier is returned by reference. A nested subroutine forwards whichever expression the inner call produced.

Tests

tests/qasm3/subroutines/test_subroutine_returns.py (new module; test_subroutines.py is near the 1000-line pylint cap): -> bit, -> bit[n], return measure q, a multi-qubit return measure q, assign-then-return, assignment to an already-declared caller variable, nested forwarding of both a measured and a literal bit return, repeated calls getting distinct temp registers, unrolling the same module twice, and declared/returned type mismatches (including return measure q; from a void subroutine).

Checks

pytest 842 passed / 3 skipped (baseline 828 / 3). pylint 10.00/10, isort, black, mypy clean; tox -e docs builds.

Stacked on #404 (feature-385-391-bit-repr-negative-indices); rebases onto main once #404 merges.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 57fbc5ef-8db7-4df8-aa9c-e309f0a22969

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[argus-eye]

Argus review

Auto-review is off for this repo. Tick the box below to run a review on this PR.

• Trigger Argus review

Estimated cost

• Files changed: 5
• Diff lines (±): 689
• Historical avg: ~243.6k tokens · ~$0.95 · across last 10 review(s)

Tip: you can also comment @argus-eye review at any time.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!