yeast: Add AST for rewrite rules

shared/yeast-macros/Cargo.toml

@@ -9,4 +9,4 @@ proc-macro = true
 [dependencies]
 proc-macro2 = "1.0"
 quote = "1.0"
-syn = "3.0"
+syn = { version = "3.0", features = ["full"] }

shared/yeast-macros/src/ast.rs

@@ -0,0 +1,134 @@
+use proc_macro2::{Ident, Literal};
+
+/// A complete rewrite rule such as `(input) where guard => (output)`.
+pub(crate) struct Rule {
+    /// Input pattern before `where` or `=>`.
+    pub(crate) pattern: Pattern,
+    /// Optional Rust guard expression after `where`.
+    pub(crate) guard: Option<syn::Expr>,
+    /// Template or annotated Rust replacement after `=>`.
+    pub(crate) replacement: Replacement,
+}
+
+pub(crate) enum Replacement {
+    /// One or more output templates such as `(call ...) {extra_nodes}`.
+    Templates(Vec<Template>),
+    /// Annotated Rust body such as `expr? { ... }`.
+    Rust {
+        /// Retained in the rule AST for validation and analysis; runtime
+        /// lowering only needs the Rust body.
+        #[allow(dead_code)]
+        annotation: ReturnAnnotation,
+        body: syn::Block,
+    },
+}
+
+#[allow(dead_code)]
+pub(crate) struct ReturnAnnotation {
+    /// Declared output kind before the Rust body.
+    pub(crate) kind: Ident,
+    /// Declared output cardinality (`kind`, `kind?`, or `kind*`).
+    pub(crate) cardinality: Cardinality,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct Cardinality {
+    pub(crate) multiple: bool,
+    pub(crate) required: bool,
+}
+
+impl Cardinality {
+    pub(crate) const SINGLE: Self = Self {
+        multiple: false,
+        required: true,
+    };
+    pub(crate) const OPTIONAL: Self = Self {
+        multiple: false,
+        required: false,
+    };
+    pub(crate) const ZERO_OR_MORE: Self = Self {
+        multiple: true,
+        required: false,
+    };
+    pub(crate) const ONE_OR_MORE: Self = Self {
+        multiple: true,
+        required: true,
+    };
+}
+
+/// An input pattern such as `(call method: (identifier) @name)`.
+pub(crate) enum Pattern {
+    /// `_` or `(_)`, distinguished by whether unnamed nodes may match.
+    Any { match_unnamed: bool },
+    /// A named node and the pattern matched against each field.
+    Node {
+        kind: String,
+        fields: Vec<(String, Pattern)>,
+    },
+    /// An unnamed token pattern such as `"+"`.
+    Unnamed(String),
+    /// A captured pattern such as `(identifier) @name` or `_ @@raw`.
+    Capture {
+        /// Capture identifier after `@` or `@@`.
+        name: Ident,
+        /// Whether `@@` keeps the captured input node untranslated.
+        raw: bool,
+        pattern: Box<Pattern>,
+        cardinality: Cardinality,
+    },
+    /// An ordered sequence of patterns within a field.
+    Sequence(Vec<Pattern>),
+    /// A repeated or optional pattern.
+    Repeated {
+        pattern: Box<Pattern>,
+        cardinality: Cardinality,
+    },
+}
+
+impl Pattern {
+    pub(crate) fn matches_single_node(&self) -> bool {
+        match self {
+            Pattern::Any { .. } | Pattern::Node { .. } | Pattern::Unnamed(_) => true,
+            Pattern::Capture { cardinality, .. } => *cardinality == Cardinality::SINGLE,
+            Pattern::Sequence(_) | Pattern::Repeated { .. } => false,
+        }
+    }
+}
+
+pub(crate) enum Template {
+    /// A parenthesized node template such as `(call method: {name})`.
+    Node(Node),
+    /// An embedded Rust block such as `{args}`.
+    Splice(syn::Block),
+}
+
+pub(crate) struct Node {
+    /// The node kind at the start of the template, such as `call` in `(call)`.
+    pub(crate) kind: Ident,
+    /// Optional leaf content such as `"foo"` or `#{name}` in
+    /// `(identifier "foo")` or `(identifier #{name})`.
+    pub(crate) content: Option<Content>,
+    /// Named fields such as `method: {name}` in `(call method: {name})`.
+    pub(crate) fields: Vec<Field>,
+}
+
+pub(crate) enum Content {
+    /// Static leaf content such as `"foo"` in `(identifier "foo")`.
+    Static(Literal),
+    /// Computed leaf content such as `#{name}` in `(identifier #{name})`.
+    Computed(syn::Block),
+}
+
+pub(crate) enum Field {
+    /// A named field such as `argument: {args}` or
+    /// `label: (identifier #{name})?`.
+    Named {
+        /// The field name before `:`, such as `argument`.
+        name: Ident,
+        /// The node or Rust splice after `:`, such as `(identifier "x")` or
+        /// `{args}`.
+        value: Template,
+        /// Whether the field value has a trailing `?`.
+        optional: bool,
+    },
+}

shared/yeast-macros/src/lib.rs

@@ -1,9 +1,13 @@
 use proc_macro::TokenStream;
 use proc_macro2::TokenStream as TokenStream2;
 
+mod ast;
+mod lower;
 mod parse;
+mod rule_parse;
+mod template_parse;
 
-/// Proc macro for constructing a `QueryNode` from a tree-sitter-inspired pattern.
+/// Proc macro for constructing a tree-sitter-inspired `yeast::query::QueryNode`.
 ///
 /// # Syntax
 ///
@@ -19,11 +23,24 @@ mod parse;
 /// (pattern) @capture           - capture the matched node
 /// "literal" @capture           - capture an unnamed token
 /// _ @capture                   - capture any node
-/// (pattern)* @capture          - capture each repeated match
-/// (pattern)?                   - zero or one
+/// (kind)* @capture             - capture each repeated named-node match
+/// "literal"* @capture          - capture each repeated unnamed-token match
+/// (kind)?                      - zero or one named node
 /// ```
 ///
 /// Named fields and bare child patterns may be intermixed in any order.
+///
+/// A parenthesized query whose first element is a node kind is always parsed as
+/// that node pattern. Otherwise, two or more sibling patterns form a sequence.
+/// A sequence may be repeated, but cannot itself be captured because it does
+/// not represent one node:
+///
+/// ```text
+/// ((identifier) @items (integer) @items)*  // valid: explicit node captures
+/// ((identifier) (integer))* @items         // invalid: sequence capture
+/// ("+" ",")*                               // valid: repeated token sequence
+/// (_ ",")*                                 // valid: repeated wildcard/token sequence
+/// ```
 #[proc_macro]
 pub fn query(input: TokenStream) -> TokenStream {
     let input2: TokenStream2 = input.into();