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
• main

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

[cursor]

PR Summary

Low Risk
Comment-only updates with no runtime or diagnostic behavior changes.

Overview
Documentation-only change in macro_declaration.rs; macro expansion behavior is unchanged.

Adds a module-level note on MacroExpansionFailure: user code should not hit these variants today because declaration-time diagnostics block the bad cases, and the enum remains a defensive backstop if matching or expansion checking regresses.

Extends the expand_placeholder comment for the MissingCapture path to explain why an out-of-range group_indices entry cannot occur—indices come from group_count on enclosing $() blocks that already walked the placeholder’s capture tree.

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

[eytan-starkware]

@eytan-starkware+AGNT made 4 comments.
Reviewable status: 0 of 1 files reviewed, 3 unresolved discussions (waiting on eytan-starkware, orizi, and TomerStarkware).

---

a discussion (no related file):
Note: the comments below are from an automatic orizi-review run (Claude agents reviewing in Ori's style, findings adversarially verified before posting). Treat with the usual bot skepticism.

---

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

/// [`SemanticDiagnosticKind::MacroPlaceholderRepDriverMismatch`],
/// [`SemanticDiagnosticKind::MacroRepetitionWithoutRepeatingPlaceholder`] and
/// [`SemanticDiagnosticKind::DuplicateMacroPlaceholder`] (see the notes at the construction

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].

---

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

/// [`SemanticDiagnosticKind::MacroRepetitionWithoutRepeatingPlaceholder`] and
/// [`SemanticDiagnosticKind::DuplicateMacroPlaceholder`] (see the notes at the construction
/// sites). The variants are kept as a backstop, so that a rule a future matcher or checker change

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.

---

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

            // `UndefinedMacroPlaceholder` - or its captures are nested deeper than the blocks it is
            // used in, rejected there by `MacroPlaceholderRepDepthMismatch`. An out-of-range group
            // index cannot land here: every index was produced by `group_count` on an enclosing

"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.