2.4 KiB
| id | ticket | title | created | tags | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| LSN-0018 | pbs-learn-to-discussion-lessons-migration | PBS AST and Parser Contract Legacy Import | 2026-03-27 |
|
Context
Legacy import from docs/compiler/pbs/learn/01. AST and Parser Contract.md.
This lesson preserves the durable parser-facing contract that remained after the PBS workflow prune. It records what later phases are allowed to assume about AST structure without freezing one parser implementation strategy.
Key Decisions
Obligations-first AST contract
What: PBS standardizes observable AST obligations rather than one mandatory in-memory representation.
Why: Downstream phases need deterministic structure and attribution, but the repository does not want to lock parser architecture or implementation language.
Trade-offs: The contract is flexible for implementation, but it requires strong conformance discipline around spans, node families, and rejection behavior.
Recovery must preserve structural honesty
What: Parser recovery is allowed only when the recovered AST remains structurally coherent and attribution-safe.
Why: Recovery exists to keep diagnostics useful, not to hide invalid syntax behind permissive fake trees.
Trade-offs: This makes parser implementations slightly stricter, but it prevents later phases from operating on misleading AST shapes.
Patterns and Algorithms
- Treat AST as a structural boundary, not a semantic one.
- Preserve declaration identity instead of collapsing overloads or rewriting source-observable parse outcomes.
- Make precedence and associativity visible in AST shape, because they are part of the user-observable contract.
- Require stable source attribution on every node that diagnostics or lowering may consume.
- Keep diagnostic identity locale-agnostic; wording is not the conformance key.
Pitfalls
- Rewriting AST after parse in a way that changes observable parse meaning.
- Allowing recovery to downgrade a required rejection into an accepted semantic shape.
- Emitting nodes without enough attribution for diagnostics or lowering.
- Treating localized message strings as conformance identity.
Takeaways
- PBS AST is standardized by obligations, not by one exact object model.
- Parser recovery is acceptable only when it stays structurally honest.
- Attribution and deterministic rejection are first-class parser contracts, not secondary details.