Sibling articles under this feature previously restated requirements in inconsistent forms.
FAQ and troubleshooting
Platform spec article
FAQ and troubleshooting
Spec standingStandard
-
This feature hub owns normative MUST/SHOULD contract text for Parser and AST contracts.
Context
Decision
This feature hub owns normative MUST/SHOULD contract text. Sibling articles must not redefine hub requirements and should link here for authority.
Consequences
Contract changes start on the hub or in linked ADRs, then propagate to articles and implementation anchors.
Verification anchors
site/website/src/content/docs/platform-spec/compiler/front-end/parser-and-ast-contracts/index.mdxarticle bundle under the same feature directory.
-
Platform-spec text supersedes informal crate comments for Parser and AST contracts.
Context
Implementation crates accumulated informal notes that diverged from published contracts.
Decision
Normative platform-spec prose and ADRs under this feature supersede informal comments in implementation crates until explicitly migrated into spec text.
Consequences
Engineers file spec/ADR updates when behavior changes; crate comments are non-authoritative for conformance arguments.
Verification anchors
compiler/crates/beskid_analysis/src/beskid.pestcompiler/crates/beskid_analysis/src/parsingcompiler/crates/beskid_analysis/src/syntax/items
-
Multiple parser entrypoints caused span drift.
Context
Multiple parser entrypoints caused span drift.
Decision
beskid.pestandbeskid_analysis::parsingare the authoritative parse surface; AST contracts derive spans from this pipeline only.Consequences
Alternate parsers must not ship without an ADR and conformance fixtures.
Verification anchors
compiler/crates/beskid_analysis/src/beskid.pestcompiler/crates/beskid_analysis/src/parsing.
- Contracts and edge cases Non-negotiable parser contracts and common edge-case handling rules.
- Design model Mental model for how the front-end parser and syntax model are organized.
- Examples Concrete examples that show parser contracts in daily compiler work.
- FAQ and troubleshooting Common parser and syntax questions with practical debugging guidance.
- Flow and algorithm Step-by-step parse flow from source text to syntax structures.
- Verification and traceability How to verify parser behavior and trace docs back to source.
0 revisions (git unavailable at build; counts may be empty)
No commits recorded for this path.
Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).
Why does one syntax error produce many diagnostics?
Section titled “Why does one syntax error produce many diagnostics?”Look for missing parser recovery boundaries. A single malformed token can cascade if parsing keeps consuming nodes with shifted spans.
Where should I add a new language form first?
Section titled “Where should I add a new language form first?”Start in beskid.pest, then add syntax node mapping, then update resolver/analysis consumers. Skipping syntax mapping leads to unresolved or partially shaped nodes.
How do I know if a bug is parser or semantic?
Section titled “How do I know if a bug is parser or semantic?”If syntax nodes are malformed or missing fields, fix parser/syntax first. If nodes are correct but rule checks fail, continue in analysis/rules or resolver passes.