This feature hub defines the normative contract for **grammar and parser contract** and links newcomer-oriented reference articles.

## Implementation anchors
- `compiler/crates/beskid_analysis/src/beskid.pest` defines the grammar tokens and precedence.
- `compiler/crates/beskid_analysis/src/syntax/` builds syntax items from parser output.
- `compiler/crates/beskid_analysis/src/syntax/items/parse_helpers.rs` contains shared parse helpers used by item parsers.

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-COMP-FRONT-0004` … `D-COMP-FRONT-0006`); use the reader **ADRs** tab for expandable detail.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Grammar and parser contract - Contracts and edge cases](./articles/contracts-and-edge-cases/)
- [Grammar and parser contract - Design model](./articles/design-model/)
- [Grammar and parser contract - Examples](./articles/examples/)
- [Grammar and parser contract - FAQ and troubleshooting](./articles/faq-and-troubleshooting/)
- [Grammar and parser contract - Flow and algorithm](./articles/flow-and-algorithm/)
- [Grammar and parser contract - Verification and traceability](./articles/verification-and-traceability/)
<!-- /spec:generate:article-index -->

## Context

Sibling articles under this feature previously restated requirements in inconsistent forms.

## 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/grammar-and-parser-contract/index.mdx`
- `article bundle under the same feature directory.`

## 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.pest`
- `compiler/crates/beskid_analysis/src/syntax/`
- `compiler/crates/beskid_analysis/src/syntax/items/parse_helpers.rs`

## Context

This feature hub defines the normative contract for **grammar and parser contract** and links newcomer-oriented reference articles.

## Decision

The reference compiler **must** implement Grammar and parser contract as documented in this feature hub and its article bundle.

## Consequences

Changes require hub/ADR updates and verification anchor extensions.

## Verification anchors

- `compiler/crates/beskid_analysis/src/beskid.pest`
- `compiler/crates/beskid_analysis/src/syntax/`
- `compiler/crates/beskid_analysis/src/syntax/items/parse_helpers.rs`

This article documents **contracts and edge cases** for **grammar and parser contract** in the reference compiler.

## What this covers
For newcomers, this page explains where the contract shows up in day-to-day compiler work and which code paths are most useful first reads.

## Anchored code paths
- `compiler/crates/beskid_analysis/src/beskid.pest` defines the grammar tokens and precedence.
- `compiler/crates/beskid_analysis/src/syntax/` builds syntax items from parser output.
- `compiler/crates/beskid_analysis/src/syntax/items/parse_helpers.rs` contains shared parse helpers used by item parsers.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.

This article documents **design model** for **grammar and parser contract** in the reference compiler.

## Anchored code paths

- `compiler/crates/beskid_analysis/src/beskid.pest` defines grammar tokens and precedence.
- `compiler/crates/beskid_analysis/src/syntax/` builds syntax items from parser output.
- `compiler/crates/beskid_analysis/src/syntax/items/parse_helpers.rs` contains shared parse helpers.

## Metaprogramming grammar (removed)

The reference compiler **must not** define a language-level `meta` item grammar. Compiler mods use ordinary Beskid source plus SDK contracts (`Collector`, `Generator`, `Analyzer`, `Rewriter`).

Legacy `MetaDefinition` productions **must be removed** from `beskid.pest` and AST/HIR surfaces.

## `extend type` production (v0.2 target)

The grammar **must** define **`extend type`** as the normative type-extension syntax (see **[extend type](/platform-spec/language-meta/program-structure/extend-type/)**). Generators emit `extend type` blocks as typed AST contributions.

Implementation **must** pair pest rules with item parsers under `compiler/crates/beskid_analysis/src/syntax/items/` and snapshot tests under `compiler/crates/beskid_tests`.

## Language macro productions (v0.2 target)

The grammar **must** define:

| Production | Role |
| --- | --- |
| **`MacroDefinition`** | `Visibility?` `macro` `Identifier` `(` `MacroParameterList` `)` `Block` — module **`InnerItem`**. |
| **`MacroParameter`** | `MacroFragmentKind` `Identifier` (closed kind keywords). |
| **`MacroInvocation`** | `Identifier` `!` optional `(` `MacroArgumentList` `)` optional braced `Block` — **expression** position. |
| **`MacroMetavariableExpr`** | `$` `Identifier` — legal only inside **`MacroDefinition`** bodies. |

See **[Language macros](/platform-spec/language-meta/metaprogramming/macros/)**. Expansion is host-driven in **`macro.expand`**; the parser only materializes definitions and invocation sites.

## Practical notes

- Treat diagnostics and tests as part of the contract, not optional implementation details.
- When grammar changes, update this article and conformance tests in the same change.

This article documents **examples** for **grammar and parser contract** in the reference compiler.

## What this covers
For newcomers, this page explains where the contract shows up in day-to-day compiler work and which code paths are most useful first reads.

## Anchored code paths
- `compiler/crates/beskid_analysis/src/beskid.pest` defines the grammar tokens and precedence.
- `compiler/crates/beskid_analysis/src/syntax/` builds syntax items from parser output.
- `compiler/crates/beskid_analysis/src/syntax/items/parse_helpers.rs` contains shared parse helpers used by item parsers.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.

This article documents **faq and troubleshooting** for **grammar and parser contract** in the reference compiler.

## What this covers
For newcomers, this page explains where the contract shows up in day-to-day compiler work and which code paths are most useful first reads.

## Anchored code paths
- `compiler/crates/beskid_analysis/src/beskid.pest` defines the grammar tokens and precedence.
- `compiler/crates/beskid_analysis/src/syntax/` builds syntax items from parser output.
- `compiler/crates/beskid_analysis/src/syntax/items/parse_helpers.rs` contains shared parse helpers used by item parsers.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.

This article documents **flow and algorithm** for **grammar and parser contract** in the reference compiler.

## What this covers
For newcomers, this page explains where the contract shows up in day-to-day compiler work and which code paths are most useful first reads.

## Anchored code paths
- `compiler/crates/beskid_analysis/src/beskid.pest` defines the grammar tokens and precedence.
- `compiler/crates/beskid_analysis/src/syntax/` builds syntax items from parser output.
- `compiler/crates/beskid_analysis/src/syntax/items/parse_helpers.rs` contains shared parse helpers used by item parsers.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.

This article documents **verification and traceability** for **grammar and parser contract** in the reference compiler.

## What this covers
For newcomers, this page explains where the contract shows up in day-to-day compiler work and which code paths are most useful first reads.

## Anchored code paths
- `compiler/crates/beskid_analysis/src/beskid.pest` defines the grammar tokens and precedence.
- `compiler/crates/beskid_analysis/src/syntax/` builds syntax items from parser output.
- `compiler/crates/beskid_analysis/src/syntax/items/parse_helpers.rs` contains shared parse helpers used by item parsers.

## Grammar evidence

Verification **must** include:

- Removal of legacy `MetaDefinition` from `beskid.pest` and AST/HIR surfaces.
- Parser snapshot tests for **`extend type`** syntax.
- Formatter and LSP smoke tests when `extend type` affects structure-sensitive tooling.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.