Add InstructionMetadata::stack_effect_jump for branch stack effects#7585

youknowone

Summary by CodeRabbit

Bug Fixes
- More accurate stack-depth calculation for branching and targeted control-flow, fixing incorrect depth estimates for some paths.
- Corrected branch-aware stack-effect behavior so stack-effect queries reflect taken vs fallthrough paths.
Refactor
- Simplified propagation of stack depths to target blocks for clearer, more consistent control-flow analysis.
New Features
- Branch-aware stack-effect query supports explicit, taken, and unknown jump semantics.

CPython's compile.c provides stack_effect(opcode, oparg, jump) where the jump parameter selects between fallthrough and branch effects. The existing stack_effect() only returns the fallthrough effect. Add stack_effect_jump() that returns the branch effect. Most instructions have identical fallthrough/branch effects; ForIter and Send are the exceptions (ForIter: fallthrough=+1, branch=-1; Send: fallthrough=0, branch=-1).

coderabbitai

📝 Walkthrough

Walkthrough

Simplifies stack-depth propagation in codegen to use a new branch-aware stack-effect API. Adds stack_effect_jump to instruction metadata and pseudo-instructions, and updates the stdlib stack_effect helper to accept an optional jump argument and choose branch/fallthrough or max effect accordingly.

Changes

Cohort / File(s)	Summary
Codegen IR `crates/codegen/src/ir.rs`	Removed special-casing for `SETUP_*` pseudo-ops and SEND adjustment when computing target depths; always compute `jump_effect` via new API and push `target_depth` unconditionally.
Instruction metadata `crates/compiler-core/src/bytecode/instruction.rs`	Added `InstructionMetadata::stack_effect_jump(&self, oparg: u32) -> i32` with default to `stack_effect`; implemented dispatch for `AnyInstruction`; `PseudoInstruction` overrides `stack_effect_jump` for `SETUP_FINALLY`, `SETUP_WITH`, and `SETUP_CLEANUP`.
Stdlib opcode helper `crates/stdlib/src/_opcode.rs`	`stack_effect` now accepts an optional `jump: Option<bool>`: `Some(true)` uses branch effect, `Some(false)` uses fallthrough, `None` returns max of both; conversion of `jump` uses `try_to_bool`.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

"I hopped through ops and depths unknown,
Pushed handler depths where once was shown,
A jump-aware wiggle in my bytecode song,
Stack effects balanced, hopping along 🐇"

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding a new `stack_effect_jump` method to `InstructionMetadata` for computing branch-taken stack effects, which is the core feature across all modified files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

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

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

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@crates/compiler-core/src/bytecode/instruction.rs`:
- Around line 1716-1724: Implement branch-sensitive stack effects by overriding
stack_effect_jump for the opcodes ForIter and Send: in the Instruction trait's
stack_effect_jump implementation, match on self (or the instruction variant) and
return -1 for ForIter and -1 for Send (regardless of oparg), otherwise fall back
to calling self.stack_effect(oparg); this ensures branch edges use the correct
values used by max_stackdepth and the exposed stack_effect(jump=True). Also
update the unit test expectation in test__opcode.py to assert
stack_effect(FOR_ITER, 0, jump=True) == -1 instead of 1.

In `@crates/stdlib/src/_opcode.rs`:
- Around line 209-213: The match on the Option jump currently treats None as the
taken-branch only; change handling so None returns the maximum of both paths:
compute both opcode.stack_effect(oparg) and opcode.stack_effect_jump(oparg) and
use the larger value when jump is None, while keeping Some(false) ->
opcode.stack_effect(oparg) and Some(true) -> opcode.stack_effect_jump(oparg);
update the match using the existing jump variable and the opcode.stack_effect /
opcode.stack_effect_jump calls to locate the change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 9633aeda-1e39-410c-879f-d780a6209f1d

📥 Commits

Reviewing files that changed from the base of the PR and between 27aed85 and 89191b8.

📒 Files selected for processing (3)

crates/codegen/src/ir.rs
crates/compiler-core/src/bytecode/instruction.rs
crates/stdlib/src/_opcode.rs

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@crates/stdlib/src/_opcode.rs`:
- Around line 189-200: The current parsing of args.jump uses try_to_bool which
accepts truthy/falsy objects; instead, in the stack_effect implementation ensure
args.jump only accepts identity True, False or None: when handling args.jump
(the variable jump / match arm using vm.is_none and v), check explicitly for
None, then check identity for True and False (use the VM/context identity checks
available) and return Some(true) or Some(false) accordingly; for any other
object return vm.new_value_error("stack_effect: jump must be False, True or
None") so non-boolean truthy/falsy values raise ValueError.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 3af32856-1019-4537-8c7c-fe5ef48c7f15

📥 Commits

Reviewing files that changed from the base of the PR and between 14bf7c5 and f401e37.

📒 Files selected for processing (1)

crates/stdlib/src/_opcode.rs

youknowone marked this pull request as ready for review April 13, 2026 05:26

coderabbitai Bot reviewed Apr 13, 2026

View reviewed changes

apply review

f401e37

youknowone force-pushed the stack-effect-jump branch from 14bf7c5 to f401e37 Compare April 13, 2026 07:46

coderabbitai Bot reviewed Apr 13, 2026

View reviewed changes

ShaharNaveh reviewed Apr 13, 2026

View reviewed changes

youknowone deleted the stack-effect-jump branch April 13, 2026 08:25

coderabbitai Bot mentioned this pull request Apr 17, 2026

Align bytecode codegen structure with CPython 3.14 #7588

Merged

coderabbitai Bot mentioned this pull request May 1, 2026

AnyInstruction helpers + doc imrovments #7757

Merged

coderabbitai Bot mentioned this pull request May 10, 2026

Add has_* methods to opcode enums #7818

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add InstructionMetadata::stack_effect_jump for branch stack effects#7585