Release 0.4.3: interactive-editing perf (19% median, 26% p95)

[siy]

Summary

Performance release focused on interactive editing. Measured on the IncrementalBenchmark editing-session suite over a 1,900-line Java fixture:

Metric	0.4.2	0.4.3	Change
Median	13.3 ms	10.8 ms	-19%
p95	30.1 ms	22.4 ms	-26%
p99	56.4 ms	53.3 ms	-5%
% under 16ms (frame budget)	83%	91.5%	+8.5pp

Breaking change

• SourceSpan now stores int triples instead of two SourceLocation refs. Component accessors are now startLine()/startColumn()/startOffset()/endLine()/endColumn()/endOffset(). The legacy start() / end() methods remain (lazy SourceLocation materialization). Factory SourceSpan.sourceSpan(SourceLocation, SourceLocation) is preserved. Pattern-matching code that destructures SourceSpan(SourceLocation, SourceLocation) must migrate to either case SourceSpan span + accessors or case SourceSpan(int, int, int, int, int, int). Drove the p95 win.

Internals

• NodeIndex.build pre-sizes the IdentityHashMap from a descendant-count pass (eliminates resize churn — was 22.8% of bench allocations). (Commit fcff78f)
• New IncrementalSessionBench in peglib-incremental/src/jmh/java: realistic 1,000-edit interactive sessions, Regimes A (cursor-pinned) and B (cursor-moved-to-edit). Per-class median/p95/p99/max + frame-budget hit rate + top-10 outlier diagnostics. JVM tuning recommendations in peglib-incremental/README.md (-Xms2g -Xmx2g -XX:MaxGCPauseMillis=20 reduces p99 by 33%). (Commits 716a113, 77c7c70)

Notes for downstream

• Regenerate generated parsers to pick up the gen-time SourceSpan emission update.
• Architectural rework planned for 0.5.0 (see docs/incremental/ARCHITECTURE-0.5.0.md when published).

Test plan

• mvn install — BUILD SUCCESS (jbct format check passes after chore: jbct:format pass on SourceSpan)
• mvn test — 897 tests passing across 5 modules (699 + 100 + 66 + 5 + 27), 0 failures, 0 errors, 0 skipped
• CI build green

Summary by CodeRabbit

• BREAKING CHANGES

  • SourceSpan internal structure refactored to use primitive integers; migration guidance provided in release notes.

• New Features

  • Added benchmarking utilities for performance measurement of incremental parsing.

• Performance

  • Achieved significant performance improvements for interactive editing workloads (median and p95 latency reductions).

• Documentation

  • Updated release notes and dependency documentation for version 0.4.3.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR releases version 0.4.3, replacing SourceSpan's internal representation from two SourceLocation references to six primitive integers (startLine, startColumn, startOffset, endLine, endColumn, endOffset), with new convenience accessors. All dependent code paths across tests, incremental parser internals, playground, and diagnostics are updated to use the simplified accessor API. A new IncrementalSessionBench benchmarking tool is added.

Changes

SourceSpan Data Structure & Accessor Migration

Layer / File(s)	Summary
Data Shape peglib-core/src/main/java/org/pragmatica/peg/tree/SourceSpan.java	Record signature changed from SourceSpan(SourceLocation start, SourceLocation end) to six-int constructor; lazy SourceLocation materialization preserved via start() and end() accessors; new startOffset(), endOffset(), startLine(), endLine(), startColumn(), endColumn() accessors added; length(), extract(), merge() refactored to operate on integer fields; toString() updated.
CST Code Generation peglib-core/src/main/java/org/pragmatica/peg/generator/ParserGenerator.java	New public SourceSpan type defined in generated CST; diagnostic rendering logic updated to use startLine(), endLine(), startColumn() accessors instead of start().line() / end().line() patterns; label-line calculations, underline rendering, and range sorting refactored for the new API; generated CST construction paths updated.
Incremental Parser Internals peglib-incremental/src/main/java/org/pragmatica/peg/incremental/internal/CstHash.java, NodeIndex.java, TreeSplicer.java, TriviaRedistribution.java	All span-offset accesses replaced from start().offset() / end().offset() to startOffset() / endOffset(); range containment checks, ancestor rebuilding, trivia shifting, and boundary validations updated; NodeIndex.build() enhanced with pre-computed descendant counts for initial capacity; TriviaRedistribution rewrite paths updated for offset-based positioning.
Test & Example Integration peglib-core/src/test/java/org/pragmatica/peg/TriviaTest.java, ErrorRecoveryExample.java, ChoiceDispatchAnalyzerTest.java	Trivia span tests updated to call startOffset() / endOffset() instead of start().offset() / end().offset(); error-recovery example refactored to use new line/column/offset accessors; test SPAN initialization changed to use factory method SourceSpan.sourceSpan(...).
Playground & Diagnostic Output peglib-playground/src/main/java/org/pragmatica/peg/playground/ParseTracer.java, internal/JsonEncoder.java	ParseTracer updated to use startOffset() accessor; JsonEncoder enriched to emit position fields ("start", "end", "line", "column") for nodes, trivia, and diagnostics via the new SourceSpan accessors.
Release Coordination CHANGELOG.md, README.md, pom.xml (all modules), peglib-incremental/src/jmh/java/org/pragmatica/peg/incremental/bench/IncrementalSessionBench.java	Version bumped to 0.4.3 across all module POMs; CHANGELOG documents breaking change and performance metrics; README updated with new version; new IncrementalSessionBench JMH benchmark tool added with deterministic edit-plan generation, two-regime measurement (cursor-moved vs. cursor-fixed), and detailed statistics reporting for interactive-editing workloads.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• siy/java-peglib#23: Modifies peglib-incremental benchmarks and internal classes (TriviaRedistribution, NodeIndex, CstHash) that are refactored here for the new span accessor API.
• siy/java-peglib#25: Changes NodeIndex and span-related logic in the incremental module; shares the same CST/span access pattern migration.
• siy/java-peglib#28: Modifies SourceSpan factory methods and span-accessor call sites across CST generation and incremental parser paths, directly preceding this refactoring.

Poem

A SourceSpan's spring step, from two refs to six ints so bright, 🐰
Where start().offset() once nested deep in sight,
Now startOffset() bounds—cleaner, faster might!
The incremental parser hops through the night. ✨
Performance blooms where efficient spans alight. 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 18.52% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 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 primary change: a performance release (0.4.3) with specific quantified improvements (19% median, 26% p95) for interactive editing, which aligns with the breaking change to SourceSpan and internal optimizations documented throughout the changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ 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 release-0.4.3

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ast-grep (0.42.1)

peglib-core/src/main/java/org/pragmatica/peg/generator/ParserGenerator.java

---

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