yeast: Require type annotations on root-level Rust interpolations

In order to facilitate static type checking of rules (and to make it
easier for human readers as well), rust blocks at the root level (i.e.
rules of the form `... => { ... }`) must now have a type annotation in
front.

All other forms are unaffected: if the right hand side of a rule is a
tree, we can read the type of the root node directly. For interpolations
that happen inside of such a tree, we can recover the type by looking at
what field we're interpolating into, and consulting the output schema.

All existing uses have been updated to have the appropriate type
annotations, though these are of course not checked yet (and so could be
wrong).

Finally, this commit also removes the final catch-all rule `_ @node =>
{node}`. Because of the preceding rule that matches `(_) @node`, this
rule would only ever match unnamed nodes, and I think in practice it did
not match at all (at least not in our current set of tests).

To give it a proper type we would have to add some notion of an "any"
type, which I would like to avoid. If it _does_ turn out to be needed,
we can easily add it back (ideally with a test-case that shows why it's
still needed).

Author: tausbn

shared/yeast-macros/src/parse.rs

@@ -617,6 +617,76 @@ fn extract_captures_inner(
     }
 }
 
+/// A rule's return-type annotation, when the body is a Rust block. Written
+/// between `=>` and the block body using the schema's own vocabulary:
+///
+/// ```text
+///   => kind        { … }   // single node of that kind
+///   => kind?       { … }   // Option<KindId> (0 or 1)
+///   => kind*       { … }   // Vec<KindId>    (0+)
+/// ```
+///
+/// Template bodies (`=> (kind …)`) never carry an annotation — the
+/// output kind is the template root. The shorthand `=> kind` (no
+/// body) also carries no annotation. See `parse_rule_top` for dispatch.
+#[derive(Clone, Debug)]
+struct ReturnAnnotation {
+    kind: Ident,
+    multiplicity: AnnotationMultiplicity,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+enum AnnotationMultiplicity {
+    Single,
+    Optional,
+    Repeated,
+}
+
+/// Peek at the token stream to decide whether the transform following
+/// `=>` is a **new** annotation form (`kind [? | *] { … }`). If so,
+/// consume the annotation and return it, leaving the `{ … }` body in
+/// the stream for the caller to parse. Otherwise leave the stream
+/// untouched and return `None`.
+///
+/// The lookahead distinguishes:
+///   `kind {`   → annotation (single)
+///   `kind? {`  → annotation (optional)
+///   `kind* {`  → annotation (repeated)
+///   `kind`     → shorthand form (no `{` follows) — NOT an annotation
+///   anything else → template or bare block — NOT an annotation
+fn try_consume_return_annotation(tokens: &mut Tokens) -> Result<Option<ReturnAnnotation>> {
+    // Must start with an identifier (the kind name).
+    let mut lookahead = tokens.clone();
+    let Some(TokenTree::Ident(_)) = lookahead.next() else {
+        return Ok(None);
+    };
+    // Then optionally `?` or `*`, then a `{` group.
+    let after_suffix = match lookahead.peek() {
+        Some(TokenTree::Punct(p)) if p.as_char() == '?' || p.as_char() == '*' => {
+            lookahead.next();
+            lookahead.peek()
+        }
+        other => other,
+    };
+    if !matches!(after_suffix, Some(TokenTree::Group(g)) if g.delimiter() == Delimiter::Brace) {
+        return Ok(None);
+    }
+    // Commit: consume the ident + suffix from the real stream.
+    let kind = expect_ident(tokens, "expected output-kind name in annotation")?;
+    let multiplicity = match tokens.peek() {
+        Some(TokenTree::Punct(p)) if p.as_char() == '?' => {
+            tokens.next();
+            AnnotationMultiplicity::Optional
+        }
+        Some(TokenTree::Punct(p)) if p.as_char() == '*' => {
+            tokens.next();
+            AnnotationMultiplicity::Repeated
+        }
+        _ => AnnotationMultiplicity::Single,
+    };
+    Ok(Some(ReturnAnnotation { kind, multiplicity }))
+}
+
 /// Parse `rule!( query => transform )`.
 pub fn parse_rule_top(input: TokenStream) -> Result<TokenStream> {
     let mut tokens = input.into_iter().peekable();
@@ -688,8 +758,52 @@ pub fn parse_rule_top(input: TokenStream) -> Result<TokenStream> {
         })
         .collect();
 
-    // Parse transform: either shorthand `=> kind_name` or full `=> (template ...)`
-    let transform_body = if peek_is_field(&mut tokens) && {
+    // Parse transform: the token(s) after `=>` fall into one of three
+    // shapes, dispatched in order:
+    //
+    //   1. `kind [? | *] { rust_body }` — annotated Rust body (NEW).
+    //      Static-analysis-ready: the annotation declares the output
+    //      kind and multiplicity in the schema's own vocabulary.
+    //   2. `kind` alone — shorthand: emit `(kind field: {@cap})…` from
+    //      the query's captures.
+    //   3. anything else — full template form (`(kind …)` or bare
+    //      `{ … }` splice via `parse_direct_list`).
+    let annotation = try_consume_return_annotation(&mut tokens)?;
+
+    let transform_body = if let Some(annotation) = annotation {
+        // Annotation form: `=> kind [? | *] { rust_body }`.
+        let body_group = expect_group(&mut tokens, Delimiter::Brace)?;
+        if let Some(tok) = tokens.next() {
+            return Err(syn::Error::new_spanned(
+                tok,
+                "unexpected token after annotated rule body",
+            ));
+        }
+        let body = body_group.stream();
+        // The annotation is not yet consumed by codegen — it will drive
+        // typed handles once the schema-driven codegen lands. For now,
+        // emit a self-documenting reference to the annotated kind and
+        // preserve today's `Vec<yeast::Id>` closure return so behavior
+        // is unchanged.
+        let kind_str = annotation.kind.to_string();
+        let mult_str = match annotation.multiplicity {
+            AnnotationMultiplicity::Single => "single",
+            AnnotationMultiplicity::Optional => "optional",
+            AnnotationMultiplicity::Repeated => "repeated",
+        };
+        let _ = (kind_str, mult_str); // silence unused warnings until wired
+
+        // For now, adapt the user's typed return value to the framework's
+        // `Vec<yeast::Id>` closure result. This uses `IntoFieldIds`, which
+        // already accepts a bare `Id`, an iterable of ids, or `Option<Id>`
+        // — matching the three annotation multiplicities.
+        quote! {
+            let __value = { #body };
+            let mut __ids: Vec<yeast::Id> = Vec::new();
+            yeast::IntoFieldIds::extend_into(__value, &mut __ids);
+            __ids
+        }
+    } else if peek_is_field(&mut tokens) && {
         // Shorthand form: bare identifier = output node kind.
         // Auto-generate template from captures.
         let mut lookahead = tokens.clone();
@@ -749,6 +863,26 @@ pub fn parse_rule_top(input: TokenStream) -> Result<TokenStream> {
             vec![__id]
         }
     } else {
+        // Reject bare `{ ... }` transforms — they used to be accepted
+        // as either a Rust body producing a `Vec<Id>` or a template
+        // consisting of a single `{cap}` splice. Both patterns lost
+        // static-analysis information (no visible output kind), so we
+        // now require rules with block bodies to use the annotation
+        // form `=> kind [? | *] { ... }`. Templates must start with a
+        // parenthesized node (e.g. `(if_expr ...)`).
+        if let Some(TokenTree::Group(g)) = tokens.peek() {
+            if g.delimiter() == Delimiter::Brace {
+                let span = g.span();
+                return Err(syn::Error::new(
+                    span,
+                    "bare `{...}` rule bodies are no longer accepted; \
+                     use the annotation form `=> kind [? | *] { ... }` \
+                     (where the kind names the output node's schema kind, \
+                     optionally suffixed with `?` or `*` for multiplicity)",
+                ));
+            }
+        }
+
         // Full template form
         let transform_items = parse_direct_list(&mut tokens, &ctx_ident)?;
 
@@ -1026,10 +1160,7 @@ struct NamedString {
 }
 
 fn parse_named_string_arg(tokens: &mut Tokens, expected_name: &str) -> Result<NamedString> {
-    let name = expect_ident(
-        tokens,
-        &format!("expected `{expected_name}:` argument"),
-    )?;
+    let name = expect_ident(tokens, &format!("expected `{expected_name}:` argument"))?;
     if name != expected_name {
         return Err(syn::Error::new_spanned(
             name,

shared/yeast/doc/yeast.md

@@ -312,13 +312,15 @@ already conforms to the output schema.
 For rules that need the raw (input-schema) capture — typically to read
 its source text or to translate it explicitly with mutable context
 state between calls — use `@@name` instead. The body sees the original
-input-schema `Id`:
+input-schema `Id`. Because these rules always have a Rust block body,
+they use the annotation form (see [the `rule!` macro
+section](#the-rule-macro) for the full grammar):
 
 ```rust
 yeast::rule!(
     (assignment left: (_) @@raw_lhs right: (_) @rhs)
     =>
-    {
+    call {
         // raw_lhs is untranslated: read its original source text.
         let text = ctx.ast.source_text(raw_lhs);
         // rhs is already translated by the auto-translate prefix.
@@ -372,26 +374,79 @@ automatically: single captures bind as `Id`, repeated captures (after
 
 ## The `rule!` macro
 
-`rule!` combines a query and a transform into a single declaration:
+`rule!` combines a query and a transform into a single declaration.
+There are three transform forms, each suited to a different level of
+rule complexity:
 
 ```rust
-// Full template form
+// 1. Template form — a tree literal describing the output.
 yeast::rule!(
     (query_pattern field: (_) @capture)
     =>
     (output_template field: {capture})
 )
 
-// Shorthand form — captures become fields on the output node
+// 2. Shorthand form — captures become fields on a bare output kind.
 yeast::rule!(
     (query_pattern field: (_) @capture)
     => output_kind
 )
+
+// 3. Annotation form — a Rust block body preceded by the output kind.
+yeast::rule!(
+    (query_pattern child: (_)+ @@children)
+    =>
+    output_kind* {
+        // arbitrary Rust; must evaluate to a value compatible with the
+        // declared multiplicity (see below).
+        let mut result = Vec::new();
+        for child in children {
+            result.extend(ctx.translate(child)?);
+        }
+        result
+    }
+)
 ```
 
 The shorthand `=> kind` form auto-generates the template, mapping each
 capture name to a field of the same name on the output node.
 
+### Annotation form
+
+Rules that need imperative logic — mutating [`BuildCtx`] state per
+iteration, computing intermediate values, or looping over captures —
+use the annotation form. It has three shapes distinguished by a suffix
+on the output-kind identifier:
+
+| Syntax              | Body must evaluate to               | Meaning                        |
+|---------------------|-------------------------------------|--------------------------------|
+| `=> kind { ... }`   | a single node id of `kind`          | Emit exactly one node.         |
+| `=> kind? { ... }`  | an `Option` of a node id of `kind`  | Emit 0 or 1 nodes (`None`/`Some`). |
+| `=> kind* { ... }`  | an iterable of node ids of `kind`   | Emit 0+ nodes; flattens into the enclosing splice slot. |
+
+The suffix mirrors the `?` / `*` markers used elsewhere in the schema
+DSL (see [`ast_types.yml`](../../../unified/extractor/ast_types.yml)):
+bare identifier = required single, `?` = optional single, `*` =
+repeated.
+
+The annotation names the schema kind of the output, giving the macro
+enough information for future static analysis (e.g. computing the
+static output type of translated captures at their consumer sites).
+
+**Bare `=> { ... }` block bodies are rejected** — every Rust-block body
+must carry an annotation, so the output kind is always visible without
+having to inspect the block's expression.
+
+### Choosing between the forms
+
+Prefer the simplest form that fits:
+
+- If the whole transform is a tree literal, use the **template form**.
+- If the transform is a template whose root matches a query capture
+  1:1, use the **shorthand form**.
+- If the transform needs Rust logic (loops, `let` bindings, calls to
+  `ctx.translate`, etc.), use the **annotation form**.
+
 ## Integration with the extractor
 
 A YEAST desugaring pass is configured with a [`DesugaringConfig`], which