yeast: Support multi-phase desugaring via DesugaringConfig::add_phase

Extend the desugaring config from a single flat list of rules to an
ordered sequence of named Phases. Each phase runs to completion (a
full traversal applying its rules) before the next phase starts.
Rules in different phases never compete for matches.

The config is built via the new chainable API:

    DesugaringConfig::new()
        .add_phase("cleanup", cleanup_rules)
        .add_phase("desugar", desugar_rules)
        .with_output_node_types_yaml(yaml);

Single-phase configs are just .add_phase(...) called once.

A single FreshScope is shared across phases so generated identifier
names (e.g. $tmp-N) are unique throughout the run.

Phase names appear in error messages, e.g. "Phase `desugar`:
exceeded maximum rewrite depth".

Add two regression tests: one verifying basic two-phase chained
desugaring, and one verifying that errors include the failing phase
name.

Author: tausbn

shared/yeast/doc/yeast.md

@@ -319,11 +319,16 @@ capture name to a field of the same name on the output node.
 ## Integration with the extractor
 
 A YEAST desugaring pass is configured with a [`DesugaringConfig`], which
-carries the rules and an optional output node-types schema (in YAML
-format). Attach it to a language spec to enable rewriting:
+carries one or more named [`Phase`]s of rules and an optional output
+node-types schema (in YAML format). Each phase is a complete traversal
+that runs to completion before the next phase starts; rules in different
+phases never compete for matches. Attach the config to a language spec
+to enable rewriting:
 
 ```rust
-let desugar = yeast::DesugaringConfig::new(my_rules)
+let desugar = yeast::DesugaringConfig::new()
+    .add_phase("cleanup", cleanup_rules())
+    .add_phase("desugar", desugar_rules())
     .with_output_node_types_yaml(include_str!("output-node-types.yml"));
 
 let lang = simple::LanguageSpec {
@@ -335,6 +340,9 @@ let lang = simple::LanguageSpec {
 };
 ```
 
+A single-phase config is just `.add_phase(...)` called once. Phase names
+appear in error messages so you can tell which phase failed.
+
 The same YAML node-types is used for both the runtime yeast `Schema` (so
 rules can refer to output-only kinds and fields) and TRAP validation (it
 is converted to JSON internally).

shared/yeast/src/lib.rs

@@ -635,28 +635,63 @@ fn apply_rules_inner(
     Ok(vec![ast.nodes.len() - 1])
 }
 
-/// Configuration for a desugaring pass: a set of rules and an optional
-/// output node-types schema (in YAML format).
+/// One phase of a desugaring pass: a named bundle of rules that runs to
+/// completion (a full traversal applying its rules) before the next phase
+/// starts. Rules within a phase compete for matches as usual; rules in
+/// different phases never compete because they don't see each other's input.
+pub struct Phase {
+    /// Name used in error messages.
+    pub name: String,
+    pub rules: Vec<Rule>,
+}
+
+impl Phase {
+    pub fn new(name: impl Into<String>, rules: Vec<Rule>) -> Self {
+        Self {
+            name: name.into(),
+            rules,
+        }
+    }
+}
+
+/// Configuration for a desugaring pass: an ordered list of [`Phase`]s and
+/// an optional output node-types schema (in YAML format).
 ///
 /// When attached to a `LanguageSpec` (in the shared tree-sitter extractor),
 /// enables yeast-based AST rewriting before TRAP extraction. The same YAML
 /// is used both to validate TRAP output (via JSON conversion) and to
 /// resolve output-only node kinds and fields at runtime.
+///
+/// Construct with `DesugaringConfig::new()` and add phases via
+/// `add_phase`:
+///
+/// ```ignore
+/// let config = yeast::DesugaringConfig::new()
+///     .add_phase("cleanup", cleanup_rules)
+///     .add_phase("desugar", desugar_rules)
+///     .with_output_node_types_yaml(yaml);
+/// ```
+#[derive(Default)]
 pub struct DesugaringConfig {
-    /// Rules to apply during desugaring.
-    pub rules: Vec<Rule>,
+    /// Phases of rule application, applied in order.
+    pub phases: Vec<Phase>,
     /// Output node-types in YAML format. If `None`, the input grammar's
     /// node types are used (i.e. the desugared AST has the same node types
     /// as the tree-sitter grammar).
     pub output_node_types_yaml: Option<&'static str>,
 }
 
 impl DesugaringConfig {
-    pub fn new(rules: Vec<Rule>) -> Self {
-        Self {
-            rules,
-            output_node_types_yaml: None,
-        }
+    /// Create an empty configuration. Add phases via [`add_phase`] and an
+    /// optional output schema via [`with_output_node_types_yaml`].
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Append a new phase with the given name and rules.
+    pub fn add_phase(mut self, name: impl Into<String>, rules: Vec<Rule>) -> Self {
+        self.phases.push(Phase::new(name, rules));
+        self
     }
 
     pub fn with_output_node_types_yaml(mut self, yaml: &'static str) -> Self {
@@ -678,30 +713,30 @@ impl DesugaringConfig {
 pub struct Runner<'a> {
     language: tree_sitter::Language,
     schema: schema::Schema,
-    rules: &'a [Rule],
+    phases: &'a [Phase],
 }
 
 impl<'a> Runner<'a> {
     /// Create a runner using the input grammar's schema for output.
-    pub fn new(language: tree_sitter::Language, rules: &'a [Rule]) -> Self {
+    pub fn new(language: tree_sitter::Language, phases: &'a [Phase]) -> Self {
         let schema = schema::Schema::from_language(&language);
         Self {
             language,
             schema,
-            rules,
+            phases,
         }
     }
 
     /// Create a runner with separate input language and output schema.
     pub fn with_schema(
         language: tree_sitter::Language,
         schema: &schema::Schema,
-        rules: &'a [Rule],
+        phases: &'a [Phase],
     ) -> Self {
         Self {
             language,
             schema: schema.clone(),
-            rules,
+            phases,
         }
     }
 
@@ -714,27 +749,17 @@ impl<'a> Runner<'a> {
         Ok(Self {
             language,
             schema,
-            rules: &config.rules,
+            phases: &config.phases,
         })
     }
 
     pub fn run_from_tree(&self, tree: &tree_sitter::Tree) -> Result<Ast, String> {
-        let fresh = tree_builder::FreshScope::new();
         let mut ast = Ast::from_tree_with_schema(self.schema.clone(), tree, &self.language);
-        let root = ast.get_root();
-        let res = apply_rules(self.rules, &mut ast, root, &fresh)?;
-        if res.len() != 1 {
-            return Err(format!(
-                "Expected exactly one result node, got {}",
-                res.len()
-            ));
-        }
-        ast.set_root(res[0]);
+        self.run_phases(&mut ast)?;
         Ok(ast)
     }
 
     pub fn run(&self, input: &str) -> Result<Ast, String> {
-        let fresh = tree_builder::FreshScope::new();
         let mut parser = tree_sitter::Parser::new();
         parser
             .set_language(&self.language)
@@ -743,15 +768,29 @@ impl<'a> Runner<'a> {
             .parse(input, None)
             .ok_or_else(|| "Failed to parse input".to_string())?;
         let mut ast = Ast::from_tree_with_schema(self.schema.clone(), &tree, &self.language);
-        let root = ast.get_root();
-        let res = apply_rules(self.rules, &mut ast, root, &fresh)?;
-        if res.len() != 1 {
-            return Err(format!(
-                "Expected exactly one result node, got {}",
-                res.len()
-            ));
-        }
-        ast.set_root(res[0]);
+        self.run_phases(&mut ast)?;
         Ok(ast)
     }
+
+    /// Apply each phase in turn to the AST, threading the root through.
+    /// A single `FreshScope` is shared across phases so that fresh
+    /// identifiers generated in different phases don't collide.
+    fn run_phases(&self, ast: &mut Ast) -> Result<(), String> {
+        let fresh = tree_builder::FreshScope::new();
+        let mut root = ast.get_root();
+        for phase in self.phases {
+            let res = apply_rules(&phase.rules, ast, root, &fresh)
+                .map_err(|e| format!("Phase `{}`: {e}", phase.name))?;
+            if res.len() != 1 {
+                return Err(format!(
+                    "Phase `{}`: expected exactly one result node, got {}",
+                    phase.name,
+                    res.len()
+                ));
+            }
+            root = res[0];
+        }
+        ast.set_root(root);
+        Ok(())
+    }
 }

shared/yeast/tests/test.rs

@@ -12,12 +12,19 @@ fn parse_and_dump(input: &str) -> String {
     dump_ast(&ast, ast.get_root(), input)
 }
 
-/// Helper: parse Ruby source with a custom output schema and rules, return dump.
+/// Helper: parse Ruby source with a custom output schema and a single
+/// phase of rules, return dump.
 fn run_and_dump(input: &str, rules: Vec<Rule>) -> String {
+    run_phased_and_dump(input, vec![Phase::new("test", rules)])
+}
+
+/// Helper: parse Ruby source with a custom output schema and multiple
+/// rule phases, return dump.
+fn run_phased_and_dump(input: &str, phases: Vec<Phase>) -> String {
     let lang: tree_sitter::Language = tree_sitter_ruby::LANGUAGE.into();
     let schema =
         yeast::node_types_yaml::schema_from_yaml_with_language(OUTPUT_SCHEMA_YAML, &lang).unwrap();
-    let runner = Runner::with_schema(lang, &schema, &rules);
+    let runner = Runner::with_schema(lang, &schema, &phases);
     let ast = runner.run(input).unwrap();
     dump_ast(&ast, ast.get_root(), input)
 }
@@ -28,7 +35,8 @@ fn run_and_get_error(input: &str, rules: Vec<Rule>) -> String {
     let lang: tree_sitter::Language = tree_sitter_ruby::LANGUAGE.into();
     let schema =
         yeast::node_types_yaml::schema_from_yaml_with_language(OUTPUT_SCHEMA_YAML, &lang).unwrap();
-    let runner = Runner::with_schema(lang, &schema, &rules);
+    let phases = vec![Phase::new("test", rules)];
+    let runner = Runner::with_schema(lang, &schema, &phases);
     runner
         .run(input)
         .expect_err("expected runner to return an error")
@@ -439,6 +447,68 @@ fn test_default_rule_fires_at_most_once_per_node() {
     );
 }
 
+// ---- Phase tests ----
+
+#[test]
+fn test_phased_desugaring() {
+    // Two phases that could equally have been a single one with chained
+    // rules. Splitting them makes the intent (cleanup, then desugar)
+    // explicit and provides per-phase error messages.
+    let cleanup = vec![yeast::rule!(
+        (assignment
+            left: (_) @left
+            right: (_) @right
+        )
+        => first_node
+    )];
+    let desugar = vec![yeast::rule!(
+        (first_node
+            left: (_) @left
+            right: (_) @right
+        )
+        => second_node
+    )];
+
+    let dump = run_phased_and_dump(
+        "x = 1",
+        vec![
+            Phase::new("cleanup", cleanup),
+            Phase::new("desugar", desugar),
+        ],
+    );
+    assert_dump_eq(
+        &dump,
+        r#"
+        program
+          second_node
+            left: identifier "x"
+            right: integer "1"
+    "#,
+    );
+}
+
+#[test]
+fn test_phase_error_includes_phase_name() {
+    // A repeated rule that loops; the error message should identify the
+    // phase that tripped the depth limit.
+    let lang: tree_sitter::Language = tree_sitter_ruby::LANGUAGE.into();
+    let schema =
+        yeast::node_types_yaml::schema_from_yaml_with_language(OUTPUT_SCHEMA_YAML, &lang).unwrap();
+    let phases = vec![Phase::new("buggy", vec![swap_assignment_rule().repeated()])];
+    let runner = Runner::with_schema(lang, &schema, &phases);
+    let err = runner
+        .run("x = 1")
+        .expect_err("expected runner to return an error");
+    assert!(
+        err.contains("Phase `buggy`"),
+        "error should mention the failing phase, got: {err}"
+    );
+    assert!(
+        err.contains("exceeded maximum rewrite depth"),
+        "error should mention the depth limit, got: {err}"
+    );
+}
+
 // ---- Cursor tests ----
 
 #[test]