release 0.2.3: interpreter phase-1 port (1.38x speedup)

[siy]

Summary

Ports the six phase-1 optimizations from the 0.2.2 generator rework to the interpreter (PegEngine). Measured 1.38× speedup on the 1,900-LOC FactoryClassGenerator.java.txt fixture (pre-port: 355 ± 7 ms/op → post-port: 258 ± 6 ms/op, JMH avgT, JDK 25).

1.38× is below the ≥1.5× plan target. Documented honestly in CHANGELOG: the interpreter's per-invocation expression-switch dispatch dominates per-call cost; phase-1's allocation-elision wins translate less dramatically than they do for the generator's rule-specialized output. Phase-2 optimizations (choiceDispatch, markResetChildren, inlineLocations, selectivePackrat) remain generator-only and are documented as structurally non-portable to the interpreter.

What changed

• New shared package org.pragmatica.peg.grammar.analysis hosts FirstCharAnalysis and ExpressionShape. Both ParserGenerator and PegEngine consume it — single source of truth for first-char derivation from a %whitespace rule.
• PegEngine applies all six phase-1 optimizations unconditionally (no configuration surface). Rationale per plan §0.2.3: interpreter is a single runtime class, no code-size trade-off to gate.
• §6.5 error-message unification to bracketed label ("[...]" / "[^...]") now applies to the interpreter too; no existing tests asserted on the old "character class" string, so zero test fallout.
• GeneratorFlagInertnessTest remains 3/3 green — generator emission is byte-identical.

Tests

• 565 → 587 passing, 1 skipped (pre-existing RoundTripTest, addressed in 0.2.4).
• New Phase1InterpreterParityTest (22/22) with a dedicated interpreter baseline at src/test/resources/perf-corpus-interpreter-baseline/.
• JMH interpreter variant added to Java25ParseBenchmark; raw results at docs/bench-results/java25-parse-interpreter.json.

Test plan

• mvn test — 587/587 + 1 skipped
• mvn install — peglib-0.2.3.jar published locally
• Corpus parity: 22/22 on Phase1InterpreterParityTest
• Generator emission byte-identical (GeneratorFlagInertnessTest 3/3)
• JMH measurement committed

Summary by CodeRabbit

Release Notes v0.2.3

• New Features

  • Interpreter performance optimizations with fast-path execution and unified message caching.
  • New interpreter benchmark variant for comparative performance analysis.

• Documentation

  • Added specification for the new incremental parsing module (experimental, 0.2.x cadence).
  • Enhanced project documentation with command-line interface reference and setup instructions.

• Tests

  • Added interpreter parity verification tests with committed baseline snapshots for correctness validation.

• Chores

  • Updated project version to 0.2.3.
  • Updated Git ignore rules.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Version 0.2.3 release introducing interpreter optimizations and parity testing infrastructure. Extracts shared grammar analysis utilities for whitespace first-character derivation and expression shape inspection. Optimizes the PegEngine interpreter with six phase-1 performance enhancements including first-char caching, literal fast-paths, bulk-advance position updates, and unified failure message labels. Adds interpreter benchmark variant and phase-1 parity testing with CST baseline hashing.

Changes

Cohort / File(s)	Summary
Version & Configuration pom.xml, README.md, .gitignore	Incremented peglib artifact version from 0.2.2 to 0.2.3; added .ndx/ directory to ignore rules.
Documentation CHANGELOG.md, CLAUDE.md, docs/incremental/SPEC.md, docs/bench-results/java25-parse-interpreter.json	Added 0.2.3 release notes detailing interpreter optimizations, analysis utilities, and parity testing. Documented ndx CLI reference and recall-palace commands. Introduced incremental reparsing specification with cursor-anchored CST design and v1/v2/v3 staging. Added JMH benchmark results JSON for interpreter variant.
Shared Grammar Analysis src/main/java/org/pragmatica/peg/grammar/analysis/ExpressionShape.java, src/main/java/org/pragmatica/peg/grammar/analysis/FirstCharAnalysis.java	Extracted expression-shape and first-character analysis into reusable public utilities. ExpressionShape pattern-matches to extract inner expressions from wrappers. FirstCharAnalysis recursively derives possible starting character sets for grammar expressions with cycle detection and character-class enumeration supporting escape sequences and case-insensitive expansion.
Generator Refactoring src/main/java/org/pragmatica/peg/generator/ParserGenerator.java	Delegated extractInnerExpression and whitespace first-char calculation to shared analysis utilities; removed 121 lines of local logic.
Interpreter Optimizations src/main/java/org/pragmatica/peg/parser/PegEngine.java, src/main/java/org/pragmatica/peg/parser/ParsingContext.java	Added bulkAdvanceNoNewline(int) for O(1) position/column updates; precomputed whitespace first-char caching in PegEngine; refactored terminal parsing paths to reuse computed end locations and employ bulk-advance; unified failure labels for literals and char-classes with per-engine caching.
Benchmark Infrastructure src/jmh/java/org/pragmatica/peg/bench/Java25ParseBenchmark.java	Added interpreter variant to JMH benchmark; constructs reusable interpreter-based parser via PegParser.fromGrammarWithoutActions(...) during setup.
Test Infrastructure src/test/java/org/pragmatica/peg/perf/Phase1InterpreterParityTest.java, src/test/java/org/pragmatica/peg/perf/InterpreterBaselineGenerator.java	Introduced phase-1 interpreter parity test that asserts parsed CST hashes match committed baselines. Added baseline generator utility to produce .hash files from corpus parsing.
Interpreter Baselines src/test/resources/perf-corpus-interpreter-baseline/**/*.hash	Added 31 hash baseline files for format-examples, flow-format-examples, and large corpus files to enable parity testing against interpreter CST output.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• PR #13: Introduces generator performance optimizations for whitespace handling and first-character analysis; this PR extends those patterns to the interpreter while extracting shared analysis utilities both can use.
• PR #11: Modifies ParserGenerator whitespace-related helper methods; this PR consolidates similar logic into shared utilities and refactors the generator to delegate to them.
• PR #12: Modifies parser generator and core parsing components to align interpreter behavior with generator; this PR completes interpreter parity with phase-1 optimizations and testing infrastructure.

Poem

🐰 Hops of joy through PEG-lib's new delight,
First-chars cached, interpreter shines bright!
Shared analysis, bulk advances swift,
Parity baselines guide this gift—
0.2.3, where speeds and truth align! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 48.72% 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 and concisely summarizes the main change: porting phase-1 interpreter optimizations and achieving a measured 1.38x speedup for version 0.2.3 release.
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.2.3

---

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