hakorune/docs/guides/scopebox.md

ScopeBox and MIR Scope Hints (Dev/CI option)

Overview
- ScopeBox is an optional, compile-time-only wrapper that makes lexical scopes explicit in the AST for diagnostics and macro visibility. It is a no-op for execution: MIR lowering treats ScopeBox like a normal block and semantics are unchanged.

How to enable
- Inject ScopeBox wrappers during core normalization by setting:
  - `NYASH_SCOPEBOX_ENABLE=1`
- Injection points:
  - If.then / If.else bodies
  - Loop.body
  - Bare blocks are represented by `Program { statements }` and already get ScopeEnter/ScopeLeave hints.

MIR Scope Hints (unified env)
- Configure hint output with a single env using a pipe-style syntax:
  - `NYASH_MIR_HINTS="<target>|<filters>..."`
- Targets:
  - `trace` or `stderr`: print human-friendly hints to stderr
  - `jsonl=<path>` or a file path: append one JSON object per line
- Filters:
  - `all` (default), `scope`, `join`, `loop`, `phi`
- Examples:
  - `NYASH_MIR_HINTS="trace|all"`
  - `NYASH_MIR_HINTS="jsonl=tmp/hints.jsonl|scope|join"`
  - `NYASH_MIR_HINTS="tmp/hints.jsonl|loop"`
- Back-compat:
  - `NYASH_MIR_TRACE_HINTS=1` is still accepted (equivalent to `trace|all`).

Zero-cost policy
- ScopeBox is removed implicitly during MIR lowering (treated as a block). ScopeEnter/ScopeLeave hints are observational only. Execution and IR are unchanged.
pyvm: split op handlers into ops_core/ops_box/ops_ctrl; add ops_flow + intrinsic; delegate vm.py without behavior change net-plugin: modularize constants (consts.rs) and sockets (sockets.rs); remove legacy commented socket code; fix unused imports mir: move instruction unit tests to tests/mir_instruction_unit.rs (file lean-up); no semantic changes runner/pyvm: ensure using pre-strip; misc docs updates Build: cargo build ok; legacy cfg warnings remain as before 2025-09-21 08:53:00 +09:00			`ScopeBox and MIR Scope Hints (Dev/CI option)`
scopebox: add design guide; scaffold no-op scope/defer macro; add MIR hint plan to CURRENT_TASK 2025-09-20 00:59:50 +09:00
pyvm: split op handlers into ops_core/ops_box/ops_ctrl; add ops_flow + intrinsic; delegate vm.py without behavior change net-plugin: modularize constants (consts.rs) and sockets (sockets.rs); remove legacy commented socket code; fix unused imports mir: move instruction unit tests to tests/mir_instruction_unit.rs (file lean-up); no semantic changes runner/pyvm: ensure using pre-strip; misc docs updates Build: cargo build ok; legacy cfg warnings remain as before 2025-09-21 08:53:00 +09:00			`Overview`
			`- ScopeBox is an optional, compile-time-only wrapper that makes lexical scopes explicit in the AST for diagnostics and macro visibility. It is a no-op for execution: MIR lowering treats ScopeBox like a normal block and semantics are unchanged.`
scopebox: add design guide; scaffold no-op scope/defer macro; add MIR hint plan to CURRENT_TASK 2025-09-20 00:59:50 +09:00
pyvm: split op handlers into ops_core/ops_box/ops_ctrl; add ops_flow + intrinsic; delegate vm.py without behavior change net-plugin: modularize constants (consts.rs) and sockets (sockets.rs); remove legacy commented socket code; fix unused imports mir: move instruction unit tests to tests/mir_instruction_unit.rs (file lean-up); no semantic changes runner/pyvm: ensure using pre-strip; misc docs updates Build: cargo build ok; legacy cfg warnings remain as before 2025-09-21 08:53:00 +09:00			`How to enable`
			`- Inject ScopeBox wrappers during core normalization by setting:`
			- `NYASH_SCOPEBOX_ENABLE=1`
			`- Injection points:`
			`- If.then / If.else bodies`
			`- Loop.body`
			- Bare blocks are represented by `Program { statements }` and already get ScopeEnter/ScopeLeave hints.
scopebox: add design guide; scaffold no-op scope/defer macro; add MIR hint plan to CURRENT_TASK 2025-09-20 00:59:50 +09:00
pyvm: split op handlers into ops_core/ops_box/ops_ctrl; add ops_flow + intrinsic; delegate vm.py without behavior change net-plugin: modularize constants (consts.rs) and sockets (sockets.rs); remove legacy commented socket code; fix unused imports mir: move instruction unit tests to tests/mir_instruction_unit.rs (file lean-up); no semantic changes runner/pyvm: ensure using pre-strip; misc docs updates Build: cargo build ok; legacy cfg warnings remain as before 2025-09-21 08:53:00 +09:00			`MIR Scope Hints (unified env)`
			`- Configure hint output with a single env using a pipe-style syntax:`
			- `NYASH_MIR_HINTS="<target>\|<filters>..."`
			`- Targets:`
			- `trace` or `stderr`: print human-friendly hints to stderr
			- `jsonl=<path>` or a file path: append one JSON object per line
			`- Filters:`
			- `all` (default), `scope`, `join`, `loop`, `phi`
			`- Examples:`
			- `NYASH_MIR_HINTS="trace\|all"`
			- `NYASH_MIR_HINTS="jsonl=tmp/hints.jsonl\|scope\|join"`
			- `NYASH_MIR_HINTS="tmp/hints.jsonl\|loop"`
			`- Back-compat:`
			- `NYASH_MIR_TRACE_HINTS=1` is still accepted (equivalent to `trace\|all`).
scopebox: add design guide; scaffold no-op scope/defer macro; add MIR hint plan to CURRENT_TASK 2025-09-20 00:59:50 +09:00
pyvm: split op handlers into ops_core/ops_box/ops_ctrl; add ops_flow + intrinsic; delegate vm.py without behavior change net-plugin: modularize constants (consts.rs) and sockets (sockets.rs); remove legacy commented socket code; fix unused imports mir: move instruction unit tests to tests/mir_instruction_unit.rs (file lean-up); no semantic changes runner/pyvm: ensure using pre-strip; misc docs updates Build: cargo build ok; legacy cfg warnings remain as before 2025-09-21 08:53:00 +09:00			`Zero-cost policy`
			`- ScopeBox is removed implicitly during MIR lowering (treated as a block). ScopeEnter/ScopeLeave hints are observational only. Execution and IR are unchanged.`
scopebox: add design guide; scaffold no-op scope/defer macro; add MIR hint plan to CURRENT_TASK 2025-09-20 00:59:50 +09:00