release 0.3.0: multi-module reshape + parseRuleAt API

[siy]

Summary

Infrastructure-only minor-bump release. Two deliverables, both setting up 0.3.1+:

1. Multi-module Maven reshape. Root becomes peglib-parent (packaging=pom); current content moves to peglib-core/ sub-module. Shell modules peglib-incremental/ and peglib-formatter/ reserved for 0.3.1 and 0.3.3. Existing sibling modules peglib-maven-plugin and peglib-playground become proper reactor children.
2. parseRuleAt API. New Parser#parseRuleAt(Class<? extends RuleId>, String, int) → Result<PartialParse>. Implemented in interpreter and generator emission. Enables 0.3.1's incremental-reparse boundary algorithm per docs/incremental/SPEC.md §5.6.

Maven coordinate preserved

org.pragmatica-lite:peglib:0.3.0 still resolves to the same primary jar consumers got in 0.2.x — the artifact lives in a sub-directory, coordinate unchanged. Downstream pins need no updates.

Tests

Aggregate across all modules: 701 passing, 1 skipped, 0 failures.

• peglib-core: 663 → 674 (+11 ParseRuleAtTest)
• peglib-maven-plugin: 5 (unchanged)
• peglib-playground: 22 (unchanged)
• Corpus parity stays 22/22 across every parity suite
• GeneratorFlagInertnessTest 3/3

Breaking changes

None for consumers of org.pragmatica-lite:peglib. The new shell modules and parent pom are additive.

Test plan

• mvn install -DskipTests at root — reactor builds
• mvn test at root — 701/701 + 1 skipped
• jar tf ~/.m2/.../peglib-0.3.0.jar has all expected classes
• cd peglib-maven-plugin && mvn test — sibling plugin still works
• cd peglib-playground && mvn test — sibling playground still works

Summary by CodeRabbit

• New Features

  • Introduced parseRuleAt API enabling partial parsing at specific input offsets, returning a PartialParse record with the parsed CST node and endpoint offset.

• Documentation

  • Added comprehensive documentation for partial parsing feature and module layout.

• Project Structure

  • Reorganized Maven project into multi-module reactor (peglib-parent) with peglib-core as primary artifact and placeholder modules for incremental parsing and code formatting.
  • Version bumped to 0.3.0.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

The PR restructures the Maven project from a single-module JAR layout to a multi-module reactor (peglib-parent) hosting peglib-core as the primary artifact, plus placeholder modules for peglib-incremental and peglib-formatter. It introduces a new parseRuleAt API (Parser#parseRuleAt(Class<? extends RuleId>, String, int)) returning Result<PartialParse>, with implementations in PegEngine and ParserGenerator, comprehensive tests, and documentation.

Changes

Cohort / File(s)	Summary
Multi-Module Maven Restructuring pom.xml, peglib-core/pom.xml, peglib-incremental/pom.xml, peglib-formatter/pom.xml, peglib-maven-plugin/pom.xml, peglib-playground/pom.xml	Converted root from single-module peglib (0.2.9) to multi-module reactor peglib-parent (0.3.0) with submodules; moved modules into reactor via parent inheritance; established dependencyManagement and pluginManagement at parent level.
Partial Parse API Surface peglib-core/src/main/java/org/pragmatica/peg/parser/Parser.java, peglib-core/src/main/java/org/pragmatica/peg/parser/PartialParse.java	Added new interface method parseRuleAt(Class<? extends RuleId>, String, int) returning Result<PartialParse> to Parser; introduced new public record PartialParse(CstNode node, int endOffset).
Interpreter Implementation peglib-core/src/main/java/org/pragmatica/peg/parser/PegEngine.java	Implemented parseRuleAt with offset validation, rule name resolution (via zero-arg instantiation fallback), line/column computation from offset, and failure-to-ParseError conversion; added resolveRuleName and computeLocation helpers.
Generator Implementation peglib-core/src/main/java/org/pragmatica/peg/generator/ParserGenerator.java	Generated parseRuleAt method with rule dispatch table (ruleDispatch map), offset seeking (seekTo helper), rule invocation via supplier, and PartialParse wrapping on success; added error construction on failure.
Comprehensive Test Suite peglib-core/src/test/java/org/pragmatica/peg/parser/ParseRuleAtTest.java	Added test cases for interpreter success/failure, PartialParse record accessors, and generator parity via runtime Java compilation; validates cross-path consistency using reflection and runtime class loading.
Documentation & Changelog CHANGELOG.md, README.md, docs/GRAMMAR-DSL.md, docs/PARTIAL-PARSE.md	Updated version to 0.3.0, documented multi-module layout, introduced new PARTIAL-PARSE.md describing API contract/semantics and usage examples; updated cross-references.
Module Package Declarations peglib-incremental/src/main/java/org/pragmatica/peg/incremental/package-info.java, peglib-formatter/src/main/java/org/pragmatica/peg/formatter/package-info.java	Added reserved-package Javadoc for incremental and formatter modules referencing future specifications.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant InterpreterParser as Parser<br/>(Interpreter)
    participant PegEngine
    participant ParsingContext
    participant Rule as Grammar<br/>Rule
    
    Client->>InterpreterParser: parseRuleAt(ruleId, input, offset)
    InterpreterParser->>PegEngine: parseRuleAt(ruleId, input, offset)
    PegEngine->>PegEngine: resolveRuleName(ruleId)
    PegEngine->>PegEngine: computeLocation(offset)
    PegEngine->>ParsingContext: create & position at offset
    PegEngine->>Rule: parseRule(ruleId)
    Rule->>ParsingContext: consume input
    ParsingContext-->>Rule: CST node
    Rule-->>PegEngine: CstNode
    PegEngine->>PegEngine: wrap in PartialParse(node, endOffset)
    PegEngine-->>Client: Result<PartialParse>

Loading

sequenceDiagram
    participant Client
    participant GenParser as Generated<br/>Parser
    participant Dispatch as RuleId<br/>Dispatch
    participant ParseMethod as parse_rule()<br/>Method
    
    Client->>GenParser: parseRuleAt(ruleId, input, offset)
    GenParser->>GenParser: validate inputs
    GenParser->>Dispatch: lookup(ruleId)
    Dispatch-->>GenParser: supplier
    GenParser->>GenParser: seekTo(offset)
    GenParser->>ParseMethod: invoke via supplier
    ParseMethod->>ParseMethod: consume input
    ParseMethod-->>GenParser: CstNode
    GenParser->>GenParser: wrap in PartialParse(node, pos)
    GenParser-->>Client: Result<PartialParse>

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• release 0.2.3: interpreter phase-1 port (1.38x speedup) #14 — The retrieved PR's incremental SPEC design explicitly requires the parseRuleAt API for cursor-anchored incremental CST reparsing; this PR implements that foundational API.
• chore: release 0.2.1 #12 — Both PRs modify ParserGenerator.java for CST-related code generation; the main PR adds parseRuleAt dispatch/seek generation while the retrieved PR modified CST generation and whitespace/trivia handling.
• chore: release 0.1.9 #10 — Both PRs modify the same core parser implementation classes (ParserGenerator.java, PegEngine.java); this PR adds partial-parse logic to both.

Poem

🐰 A parser now leaps at any offset so fine,
From cursor to rule, the PartialParse divine!
With multi-modules and dispatch tables bright,
The reactor spins and the tests all pass right! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.27% 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 'release 0.3.0: multi-module reshape + parseRuleAt API' clearly and concisely summarizes the two main changes in the changeset: the multi-module Maven restructuring and the new parseRuleAt API addition, matching the stated PR objectives.
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.3.0

---

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