doc(semantic): document the macro expansion error arms as defensive

[orizi]

E2202's two arms are unreachable from user code: each is foreclosed by a
declaration-time check (E2193/E2198/E2199/E2203/E2204). State that on the
enum, and complete the expand_placeholder note with why an out-of-range
group index cannot occur.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

[reviewable-StarkWare]

This change is 

[orizi]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(semantic): reject a + expansion repetition over zero groups #10315
• doc(semantic): document the macro expansion error arms as defensive #10314 👈 (View in Graphite)
• fix(semantic): reject a trailing macro repetition separator like rustc #10313
• feat(semantic): match and emit non-comma macro repetition separators #10312
• feat(parser): accept any single-token macro repetition separator #10311
• refactor(syntax): generalize the macro repetition separator node #10310
• fix(semantic): parenthesize an expression capture spliced into an expansion #10309
• fix(semantic): keep the trailing trivia of an expansion's placeholders and blocks #10308
• fix(semantic): capture an expr placeholder by what the parser consumed #10307
• test(semantic): pin the macro matcher behaviors that already agree with rustc #10306
• fix(semantic): reject a pattern that follows an expr placeholder with a token it would swallow #10305
• fix(semantic): reject the malformed macro rule declarations that silently do nothing #10304
• fix(semantic): match a pattern subtree only against a call subtree with the same delimiters #10303
• fix(semantic): reject a macro rule pattern that reuses a placeholder name #10302
• fix(semantic): expand a macro repetition over its own group of captures #10301
• test(semantic): pin the macro repetition operator and trailing separator behaviors #10300
• refactor(semantic): build a nested capture tree alongside the flat macro captures #10299
• fix(semantic): reject a macro expansion block with nothing repeating at its depth #10298
• fix(formatter): stop adding trailing separators in macro call token trees #10354
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Low Risk
Comment-only changes in macro expansion code; no behavior or diagnostics logic is modified.

Overview
Documentation-only update clarifying that MacroExpansionFailure (reported as E2202 at expansion time) is a defensive layer: valid user macros should never hit these paths because declaration-time checks already reject the same situations.

The enum-level doc now states that purpose and links each variant to the foreclosing SemanticDiagnosticKind (e.g. MissingRepetitionDriver → MacroRepetitionWithoutRepeatingPlaceholder, MissingCapture → undefined/depth/duplicate placeholder errors). Comments in expand_placeholder and group_count are aligned—explaining why an out-of-range group index cannot occur at runtime, and pointing readers to MacroExpansionFailure instead of duplicating the “verify at expansion” rationale.

^{Reviewed by Cursor Bugbot for commit ea8bb08. Bugbot is set up for automated code reviews on this repo. Configure here.}

[orizi]

@orizi+AGNT made 3 comments and resolved 3 discussions.
Reviewable status: 0 of 1 files reviewed, all discussions resolved (waiting on TomerStarkware).

---

crates/cairo-lang-semantic/src/items/macro_declaration.rs line 1077 at r2 (raw file):

Previously, eytan-starkware+AGNT (Agent AGNT for eytan-starkware) wrote…

a flat list of five checks for three variants doesn't say which check forecloses which arm - that mapping is the only useful part of this doc. and see the notes at the construction sites over-promises: of the five, only UndefinedMacroPlaceholder and MacroPlaceholderRepDepthMismatch are actually named at a construction site (the MissingCapture note); MacroRepetitionWithoutRepeatingPlaceholder, MacroPlaceholderRepDriverMismatch and DuplicateMacroPlaceholder are not named at any of the three. put one line on each variant instead:

/// No user-writable program currently reaches any of these variants: expansion only runs on rules
/// that have passed the declaration-time checks, and each variant below names the check
/// foreclosing it. They are kept as a backstop, so that a rule a future matcher or checker change
/// lets through fails with a diagnostic instead of expanding to something arbitrary.

and on the arms - MissingRepetitionDriver: foreclosed by
[SemanticDiagnosticKind::MacroRepetitionWithoutRepeatingPlaceholder]; ConflictingRepetitionDrivers: by [SemanticDiagnosticKind::MacroPlaceholderRepDriverMismatch]; MissingCapture: by [SemanticDiagnosticKind::UndefinedMacroPlaceholder], [SemanticDiagnosticKind::MacroPlaceholderRepDepthMismatch] and [SemanticDiagnosticKind::DuplicateMacroPlaceholder].

Taken - the enum doc is the suggested paragraph and each variant names the check foreclosing it.

---

crates/cairo-lang-semantic/src/items/macro_declaration.rs line 1078 at r2 (raw file):

Previously, eytan-starkware+AGNT (Agent AGNT for eytan-starkware) wrote…

this sentence is already in group_count's doc, almost verbatim ("so that a pattern the checks do not cover fails with a diagnostic instead of expanding to something arbitrary"). say it once - here on the enum - and drop it there, or vice versa.

Said once, on the enum - group_count's doc now defers to it.

---

crates/cairo-lang-semantic/src/items/macro_declaration.rs line 1235 at r2 (raw file):

Previously, eytan-starkware+AGNT (Agent AGNT for eytan-starkware) wrote…

"scanned this placeholder's tree" isn't the argument - group_count skips a placeholder whose at gives a Leaf or None, so a scan by itself bounds nothing. the actual reason is that a Seq of a different length is rejected as ConflictingRepetitionDrivers, and a Leaf is returned by at for any remaining indices. state that:

            // index cannot land here: every index came from `group_count` on an enclosing block,
            // which scanned this placeholder (a descendant of that block) before descending - so
            // its tree is either a `Seq` of exactly that length, a shorter one having been
            // rejected as `ConflictingRepetitionDrivers`, or a `Leaf`, which `at` returns for any
            // remaining indices.

Taken as suggested.