[Pastalikek65]

Closes #342

Implements opt-in fault-tolerant parsing via a new RecoverTo(types...) build option.

What it does

When parsing fails, the parser scans forward from the error position for the first token that could begin one of the registered productions, skips the malformed region, and resumes parsing from that synchronization point. The partial AST up to the failure is retained (per participle's existing best-effort behavior).

type Statements struct {
    Stmts []*Stmt `@@*`
}

parser := participle.MustBuild[Statements](
    participle.RecoverTo(&Stmt{}),
)

Input like call one broken call two parses to [call:one, call:two] — broken is skipped.

Design

• Start-set analysis (recovery.go): computes, per registered production, the token predicates that can begin it. Handles literal (incl. type constraints and case-insensitivity), reference, strct, disjunction, sequence (with nullability propagation through nullable heads), capture, group and union. Opaque nodes (custom, parseable, negation, lookaheadGroup) contribute nothing.
• Forward scan (maybeRecover): scans via a speculative branch (Next() skips elided tokens), never crosses structural literals (tokens appearing verbatim in the grammar that aren't sync points — e.g. closing delimiters), and guarantees termination via:
  1. the failed token is always consumed, and
  2. a lastRecovery cursor guard prevents re-recovering at the same position.
• Hooks (nodes.go): only inside repetition loops (group */+), on both the error path and the zero-match path. This keeps the change surgical and avoids the O(n²) blow-up a strct-level hook produced during development.
• Validation: RecoverTo on a type not in the grammar is a build error.

Testing

11 unit tests covering: skip-malformed, resume-after-brace (nested blocks, } not crossed), no-sync-token falls back to original error, no-option no-op, multiple malformed, UseLookahead interaction, case-insensitive literals, unknown-type build error, unions, @@+ (one-or-more), and struct-level sync on a recursive grammar.

Fuzzed 45s / ~300k executions with no hang, panic or explosion (a fuzzer found two non-termination cases during development that the lastRecovery guard + structural-literal rules resolved).

Open question for maintainer

RecoverTo is deliberately sync-only (productions are not re-parsed into the AST after recovery); re-parsing recovered nodes would be a natural follow-up but adds complexity. Happy to extend if desired.

[alecthomas]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d7b93b45de

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Honor case-insensitivity for structural literals

When a delimiter's token type is configured with CaseInsensitive, this exact-value lookup does not use the literal parser's case-insensitive matching. For example, with grammar delimiter "END", lowercase input end is not recognized as structural, so recovery can scan past the enclosing block to a later synchronization token, attach that statement to the wrong block, and eventually fail at EOF expecting END. Structural literals should be matched using the same case and token-type semantics as literal.Parse.

Useful? React with 👍 / 👎.