Add scopeAt() — scope-aware stack frame resolution

[AlexVanderbist]

Summary

Adds SourceMapLookup::scopeAt() — resolves a generated position to the enclosing source-language scope, modeled after the ECMA-426 Scopes proposal. Today it's a heuristic polyfill that walks sourcesContent backward; when bundlers begin emitting the normative scopes field, the same API will be backed natively.

Also adds isIgnored() for the ignoreList field and converts Position / GeneratedPosition to class-level readonly.

Motivation

For Flare's stack-trace de-minification, lookup() gets the file+line back to source, but the frame's method name stays minified (u, r, j). The sourcemap's names table has the original identifiers (thirdLevelExplode, RenderCrashChild, etc.) but typically only attached to declaration tokens — not to the throw site itself. scopeAt() is the "which function am I inside?" primitive the lookup side was missing.

What it resolves

• function NAME, generator, const/let/var NAME = (arrow | async arrow | function | x => …)
• Class and object method shorthand including async, static, get/set, and #private
• Nested enclosure: Scope::$parent links outward (e.g. onClick → DeeplyNestedTrigger)
• Anonymous arrow callbacks (arr.map(() => { … })) — returns a Scope with name === null

Control-flow keywords (if/while/for/switch/catch) are filtered so they can't masquerade as method names. The per-line tokenizer skips braces inside strings, line/block comments, and template literal text; ${…} interpolation is treated as code.

Against the Flare React playground's six user frames — thirdLevelExplode, secondLevelCompute, DeeplyNestedTrigger.onClick, AsyncPromiseTrigger.onClick, ManualReportTrigger.onClick, RenderCrashChild — all six resolve to a named Scope, with the handlers correctly nested under their component.

API

$scope = $map->scopeAt(line: 42, column: 17);

$scope->name;                  // "onClick", or null for an anonymous function boundary
$scope->position->sourceLine;  // where the frame actually executed
$scope->parent?->name;         // lexically enclosing scope

Per-call $maxLinesBack argument overrides SourceMapLookup::DEFAULT_WALKBACK_LINES (60).

Performance

Benchmarked against small (82 KB), medium (549 KB), and large (6.2 MB) fixtures. On medium/large: ~35% overhead over lookup() with the walk-back cache warm. Cold per-call cost on the large fixture: ~6 µs. Cache key is (sourceFileIndex, sourceLine, maxLinesBack) — which is effectively free to hit because many generated columns share the same source line, so in typical stack-trace resolution workloads cache hit rate approaches 100%.

Full numbers at benchmarks/scope_at_cost.php (not wired into composer bench — run manually).

Deferred

• Native ScopesSourceMapLookup engine — will slot in behind the same API when bundlers emit the scopes field.
• ScopeKind enum, inlined-callsite chain via GeneratedRange.callsite, ScopeOrigin signal — add when the native engine lands.
• Multiline strings / block comments that span lines in the walk-back tokenizer — documented in WalkBack's class docblock.

Test plan

• 46 new tests (7 ignoreList feature, 25 WalkBack unit, 14 scopeAt feature) on top of the existing 111 — 157 total pass
• Regression test for control-flow keyword filter (if, while, for, switch, catch)
• Test that scopeAt falls back to the mapping's .name when no sourcesContent is available
• Test that anonymous arrow callbacks produce Scope(name: null) rather than null
• End-to-end test against the real Vite-produced fixture at tests/fixtures/scopes/frontend-errors.js.map (included; provenance documented in the fixture's README)
• Benchmark harness runs clean against all three fixtures