feat(opt-report): show local declaration locations

[proggeramlug]

Closes #7036\n\n## Summary\n- retain report-only LocalId -> source-span metadata through HIR lowering and local-cloning transforms\n- populate the existing opt-report byte_offset field for named locals without changing the JSON schema\n- render file:line:column plus source/caret snippets in text reports, including CJS wrapper line correction\n\n## Testing\n- cargo test -p perry-hir --lib\n- cargo test -p perry-transform --lib\n- cargo check -p perry-codegen --tests\n- cargo check -p perry\n\nNo version bump.

Summary by CodeRabbit

• New Features

  • Enhanced text optimization reports with file, line, and column locations.
  • Added source-line and caret snippets for named locals and optimization entries.
  • Improved source mapping for CommonJS-wrapped code.
  • Preserved declaration locations through lowering and code transformations.

• Bug Fixes

  • Retained accurate source locations for cloned and inlined locals.
  • Kept source metadata from affecting stable hashes or cache keys.

• Documentation

  • Updated optimization-report documentation to describe source locations, snippets, and hotness ratios.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 61c0f71b-7e9f-49c8-b15a-4c5399c27de3

📥 Commits

Reviewing files that changed from the base of the PR and between ac52a5c and b3f9cb1.

📒 Files selected for processing (66)

• changelog.d/7957-opt-report-source-locations.md
• crates/perry-codegen/src/codegen/clone_suffix_tests.rs
• crates/perry-codegen/src/codegen/declared_string_add_tests.rs
• crates/perry-codegen/src/codegen/emission_order_tests.rs
• crates/perry-codegen/src/codegen/entry/tests.rs
• crates/perry-codegen/src/codegen/mod.rs
• crates/perry-codegen/src/codegen/number_exactness_tests.rs
• crates/perry-codegen/src/codegen/opts.rs
• crates/perry-codegen/src/native_root_coverage/mod.rs
• crates/perry-codegen/src/opt_report/mod.rs
• crates/perry-codegen/src/opt_report/render.rs
• crates/perry-codegen/src/temp_root_coverage/mod.rs
• crates/perry-codegen/src/type_analysis/numeric/tests.rs
• crates/perry-codegen/src/type_analysis/strings/tests.rs
• crates/perry-codegen/tests/app_window_config_options.rs
• crates/perry-codegen/tests/argless_builtin_extra_args.rs
• crates/perry-codegen/tests/class_field_store_pointer_test.rs
• crates/perry-codegen/tests/class_keys_gc_root.rs
• crates/perry-codegen/tests/constructor_recursion.rs
• crates/perry-codegen/tests/i64_spec_ternary_recursion.rs
• crates/perry-codegen/tests/large_object_barriers.rs
• crates/perry-codegen/tests/loop_safepoint_purity.rs
• crates/perry-codegen/tests/macos_bundle_chdir_gate.rs
• crates/perry-codegen/tests/native_proof_buffer_views.rs
• crates/perry-codegen/tests/native_proof_regressions.rs
• crates/perry-codegen/tests/node_test_mock_property_presence.rs
• crates/perry-codegen/tests/perry_builtin_name_collision.rs
• crates/perry-codegen/tests/private_guard_declaring_class.rs
• crates/perry-codegen/tests/scalar_replaced_slot_roots.rs
• crates/perry-codegen/tests/shadow_slot_hygiene.rs
• crates/perry-codegen/tests/static_symbol_hygiene.rs
• crates/perry-codegen/tests/temp_root_operand_temporaries.rs
• crates/perry-codegen/tests/typed_feedback.rs
• crates/perry-codegen/tests/typed_shape_declared_at_allocation.rs
• crates/perry-codegen/tests/typed_shape_descriptor.rs
• crates/perry-codegen/tests/typed_shape_descriptors.rs
• crates/perry-hir/src/destructuring/pattern_binding.rs
• crates/perry-hir/src/destructuring/var_decl.rs
• crates/perry-hir/src/ir/mod.rs
• crates/perry-hir/src/ir/module.rs
• crates/perry-hir/src/lower/context.rs
• crates/perry-hir/src/lower/expr_function.rs
• crates/perry-hir/src/lower/expr_object.rs
• crates/perry-hir/src/lower/for_head.rs
• crates/perry-hir/src/lower/lower_module_fn.rs
• crates/perry-hir/src/lower/lowering_context.rs
• crates/perry-hir/src/lower/module_decl.rs
• crates/perry-hir/src/lower/module_decl/namespace.rs
• crates/perry-hir/src/lower/stmt.rs
• crates/perry-hir/src/lower/stmt_loops.rs
• crates/perry-hir/src/lower/tests.rs
• crates/perry-hir/src/lower_decl/body_stmt.rs
• crates/perry-hir/src/lower_decl/body_stmt/nested_fn_decl.rs
• crates/perry-hir/src/lower_decl/class_members.rs
• crates/perry-hir/src/lower_decl/fn_decl.rs
• crates/perry-hir/src/lower_decl/private_members.rs
• crates/perry-hir/src/stable_hash/module.rs
• crates/perry-hir/src/stable_hash/tests.rs
• crates/perry-transform/src/inline/mod.rs
• crates/perry-transform/src/inline/substitute.rs
• crates/perry-transform/src/lib.rs
• crates/perry-transform/src/source_spans.rs
• crates/perry-transform/src/unroll/mod.rs
• crates/perry/src/commands/compile/collect_modules.rs
• crates/perry/src/commands/compile/run_pipeline.rs
• crates/perry/src/commands/compile/types.rs

---

📝 Walkthrough

Walkthrough

The PR records local declaration spans during HIR lowering, preserves them through inlining and loop unrolling, and uses them to populate optimization-report offsets. Text reports now show file, line, column, source snippets, and carets, including corrected CommonJS wrapper locations.

Changes

Source-span metadata and lowering

Layer / File(s)	Summary
HIR source-span contract crates/perry-hir/src/ir/*, crates/perry-hir/src/lower/*	Adds LocalSourceSpan and Module.local_source_spans. Lowering records spans for bindings, parameters, loops, destructuring, catches, exports, and methods.
HIR validation and hashing crates/perry-hir/src/lower/tests.rs, crates/perry-hir/src/stable_hash/*	Adds lowering coverage and confirms source metadata does not change stable hashes or cache keys.

Transform propagation

Layer / File(s)	Summary
Local-ID remapping crates/perry-transform/src/source_spans.rs, crates/perry-transform/src/inline/*	Tracks fresh local IDs, propagates spans through transitive remaps, and prevents repeated recording during recursive substitution.
Loop-unroll propagation crates/perry-transform/src/unroll/mod.rs	Carries local remaps through cloned loop bodies and assigns original spans to fresh locals. Tests cover unrolled locals.

Optimization reports

Layer / File(s)	Summary
Offset resolution and source registry crates/perry-codegen/src/opt_report/mod.rs, crates/perry-codegen/src/codegen/mod.rs	Shares local-span maps through report scopes, resolves declaration offsets, registers module sources, and clears test-session sources.
Text rendering crates/perry-codegen/src/opt_report/render.rs	Resolves offsets to file, line, and column values. It renders source lines and carets, with raw-offset fallback.
Fixture updates and regression tests crates/perry-codegen/src/codegen/*_tests.rs, crates/perry-codegen/src/*/tests.rs, crates/perry-codegen/tests/*	Initializes local_source_spans in module fixtures and tests offset resolution and rendered locations.

Compile integration

Layer / File(s)	Summary
Source mapping and CommonJS wiring crates/perry/src/commands/compile/*	Enables source mapping for text reports, uses wrapped CommonJS source, applies line-offset correction, and updates report documentation.
Release documentation changelog.d/7957-opt-report-source-locations.md	Documents local-span preservation and source-location output.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CompilePipeline
  participant Codegen
  participant HIR
  participant Transform
  participant OptReport
  participant TextRenderer
  CompilePipeline->>Codegen: provide module source and line offset
  Codegen->>HIR: lower bindings with source spans
  HIR->>Transform: pass local-span metadata
  Transform->>OptReport: provide remapped local spans
  Codegen->>OptReport: register module source
  OptReport->>TextRenderer: provide resolved offsets
  TextRenderer-->>CompilePipeline: render location, snippet, and caret

Loading

Possibly related PRs

• PerryTS/perry#7037: Introduces the optimization-report APIs extended by this PR.
• PerryTS/perry#7052: Also modifies loop-unrolling code and its regression tests.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/7036-opt-report-spans

---

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.}