Parser: Add track_locations option to skip source-location objects

[joelhawksley]

Summary

Splits the track_locations parse option out of #1872 into its own PR, as requested.

Herb.parse builds a Location (two Positions) — and a Range — for every AST node and token. Callers that never read source locations (e.g. rendering a template with validation disabled) pay to materialize objects they immediately discard; Location/Range/Position account for roughly half of the parse's Ruby allocations.

This adds an additive track_locations: option to Herb.parse (default true, fully backward compatible). When false, the node/token builders leave location and range as nil. The flag is applied under the GVL immediately before Ruby AST materialization, so it cannot race with the native parse.

It also makes Herb::AST::Helpers#inline_ruby_comment? safe when locations are not tracked. That helper detected a single-line inline # comment by comparing node.location.start.line to node.location.end.line, which raises once track_locations: false leaves the location nil. It runs on the compiler's happy path (Compiler#visit_erb_content_node), so without this fix any template containing an inline Ruby comment fails to compile when locations are off. It now falls back to an equivalent newline check on the node content, keeping compiled output byte-identical whether or not locations are tracked.

Metrics

Measured by running ActionView::Precompiler against GitHub.com's views directory (Ruby 4.0.5 + PRISM), comparing track_locations on (current default) vs. off:

End-to-end ActionView::Precompiler (6,302 templates):

	compile time (median)	allocations
locations tracked (default)	21.53s	39.3M
track_locations: false	20.91s	32.5M
delta	~3% faster	~17% fewer

The end-to-end wall-clock delta is modest because Herb parsing is only a fraction of total precompile work (render-call scanning, file I/O, and ActionView's compile! machinery dominate); the allocation reduction is the headline.

Isolated Herb::Engine compile of the same corpus (8,578 .html.erb files, validation disabled):

	compile time (median)	allocations
locations tracked (default)	11.43s	38.3M
track_locations: false	10.40s	29.7M
delta	9.0% faster	22.5% fewer

Compiled Herb::Engine#src output was verified byte-for-byte identical across all corpus templates with locations on vs. off (0 mismatches, 0 skips).

Notes

• The only public API change is the additive track_locations: option on Herb.parse.
• Generated files (ext/herb/nodes.c, ext/herb/error_helpers.c) are not touched by this PR; the location builders they call already honor the flag.
• Split out of Engine: Reduce template compilation overhead #1872 per the request to land track_locations as its own PR.

[joelhawksley]

@marcoroth updated and marked ready for review! I'm purposefully going to do the perf PRs one at a time ❤️

[marcoroth]

Thanks for splitting this out @joelhawksley!

I pushed a few commits to your branch to make sure track_locations is treated as a parser option across all language bindings.

I changed the node and token builders take a parser_options_T instead of a track_locations. This should make it easier for future options without having to touch the signatures again.

The make this more visible, I updated the pretty print functions to render the locations as (location: ∅).

Also, added the option to the playground and the CLI via the --no-track-locations flag.

And finally, in TypeScript, parse(source, { track_locations: false }) now returns a branded result that the Printer and Rewriter reject at compile time.

Please let me know if this still yields the results you were seeing in your benchmarks!

Thank you! 🙏🏼

[joelhawksley]

Re-ran the benchmark on the current PR head (3c3b6b57)

I rebuilt the extension from the latest state of this branch (now including the parser_options_T threading and the Locationless brand) and re-ran a parse benchmark against a real corpus of github/github ERB templates.

Setup

• Corpus: 7,169 .erb files from github/github (app/views/** + packages/**), 15.1 MB; 7,165 parse with zero errors and are used for the comparison (so both modes do identical work).
• Call mirrors the ReActionView engine path: Herb.parse(src, track_whitespace: true), toggling only track_locations.
• Ruby 4.0.5, herb 0.10.3 (this branch). Median of 7 rounds for wall-clock; allocations measured via GC.stat(:total_allocated_objects) (deterministic).

Results

Config	Wall-clock (median)	Allocations
track_locations: true (default)	3.94 s	15,816,110
track_locations: false	3.34 s	7,826,904
Delta	~14% faster (13.8–15.2% across runs)	50.5% fewer (−7,989,206 objects)

The allocation reduction is exactly reproducible run-to-run (50.5% fewer Ruby objects across the 7,165 templates); wall-clock lands at ~14% faster. This lines up with the original hypothesis that Location/Range/Position materialization is roughly half of the parse's Ruby-object allocations — skipping it when the caller never reads source locations is a clean, backward-compatible win.

---

Disclosure: this comment and the benchmark run were produced by Claude Opus 4.8 (GitHub Copilot), acting on behalf of @joelhawksley.

[marcoroth]

Sweet, thanks for the confirmation, @joelhawksley, merging! 🙏🏼