Add CLI support for query AST output

Author: zharinov

AGENTS.md

@@ -22,6 +22,25 @@
 - Basic grammar: tree expressions `(type)`, alternation `[a b]`, wildcards `_`, captures `@name` with types `::T`, fields `field:`, quantifiers `*+?` (and non-greedy), anonymous nodes `"literal"`, supertypes `(a/b)`, special nodes `(ERROR)`, sequences `{...}`, named definitions `Name = expr`, tagged alternations `[A: ... B: ...]`
 - Parser accepts UpperIdent in capture/field positions for resilience (validation catches casing errors)
 
+## Error Pipeline
+
+Errors flow through staged analysis:
+- `Parse`: Syntax structure errors (lexer/parser)
+- `Resolve`: Name resolution errors (undefined references, duplicate definitions)
+- `Escape`: Recursive pattern detection errors
+
+Errors are collected, not fail-fast. Use `Query::errors_in_stage()` for filtering, `Query::render_errors_grouped()` for CLI output.
+
+## CLI
+
+Debug flags for introspection (composable, multiple can be enabled):
+- `--query-cst`: Concrete syntax tree (all tokens)
+- `--query-ast`: Abstract syntax tree (semantic structure, concise)
+- `--query-refs`: Name resolution references
+- Future: `--query-types`, `--source-ast`, `--result`
+
+Designed for LLM-friendly debugging. Errors render at the end, grouped by stage.
+
 ## SyntaxKind naming convention
 
 Short, punchy names for CST node kinds:
@@ -47,7 +66,6 @@ An expression (`Expr`) is one of: `Tree | Alt | Seq | Quantifier | Capture`
 ## What's NOT yet implemented
 
 - Semantic validation (Phase 5): field value constraints, alternation style mixing, casing rules
-- AST layer: typed wrappers over `SyntaxNode` (like `struct Node(SyntaxNode)`)
 
 ## Intentionally deferred (post-MVP)
 
@@ -72,6 +90,21 @@ An expression (`Expr`) is one of: `Tree | Alt | Seq | Quantifier | Capture`
 - **Arrays**: Quantifiers `?`, `*`, `+` determine the cardinality (optional, list, non-empty list).
 - **Fields**: Captures `@name` create fields within the current scope.
 
+## AST Layer
+
+Typed wrappers over CST (`SyntaxNode`) in `ql/ast.rs`:
+- `Root`, `Def`, `Tree`, `Ref`, `Lit`, `Alt`, `Branch`, `Seq`, `Capture`, `Type`, `Quantifier`, `Field`, `NegatedField`, `Wildcard`, `Anchor`
+- `Expr` enum for any expression node
+- `format_ast()` for concise semantic tree output (vs CST which includes all tokens)
+- Tests using AST should use `snapshot_ast()` for cleaner output
+
+## AST Casting Convention
+
+- Use `Option<T>` for casting methods, not `TryFrom`/`TryInto`
+- `None` is not always an error—parsing resilience requires flexible conversion
+- Validation is a separate layer from casting; don't embed error logic in cast methods
+- Consistent with rnix-parser, rowan ecosystem patterns
+
 ## General rules
 
 - When the changes are made, propose an update to AGENTS.md file if it provides valuable context for future LLM agent calls

crates/plotnik-cli/src/main.rs

@@ -12,6 +12,7 @@ use std::path::PathBuf;
 │ Output          │ Needs Query │ Needs Source │
 ├─────────────────┼─────────────┼──────────────┤
 │ --query-cst     │      ✓      │              │
+│ --query-ast     │      ✓      │              │
 │ --query-refs    │      ✓      │              │
 │ --query-types   │      ✓      │              │
 │ --source-ast    │             │      ✓       │
@@ -92,6 +93,10 @@ struct OutputArgs {
     #[arg(long)]
     query_cst: bool,
 
+    /// Show parsed query AST (abstract syntax tree, semantic structure)
+    #[arg(long)]
+    query_ast: bool,
+
     /// Show name resolution (definitions and references)
     #[arg(long)]
     query_refs: bool,
@@ -125,8 +130,15 @@ fn main() {
     let has_source = cli.source.source_text.is_some() || cli.source.source_file.is_some();
 
     // Validate output dependencies
-    if (cli.output.query_cst || cli.output.query_refs || cli.output.query_types) && !has_query {
-        eprintln!("error: --query-cst, --query-refs, and --query-types require --query-text or --query-file");
+    if (cli.output.query_cst
+        || cli.output.query_ast
+        || cli.output.query_refs
+        || cli.output.query_types)
+        && !has_query
+    {
+        eprintln!(
+            "error: --query-cst, --query-ast, --query-refs, and --query-types require --query-text or --query-file"
+        );
         std::process::exit(1);
     }
 
@@ -150,6 +162,7 @@ fn main() {
         || (has_query
             && has_source
             && !cli.output.query_cst
+            && !cli.output.query_ast
             && !cli.output.query_refs
             && !cli.output.query_types
             && !cli.output.source_ast
@@ -177,6 +190,13 @@ fn main() {
         }
     }
 
+    if cli.output.query_ast {
+        println!("=== QUERY AST ===");
+        if let Some(ref q) = query {
+            print!("{}", q.format_ast());
+        }
+    }
+
     if cli.output.query_refs {
         println!("=== QUERY REFS ===");
         if let Some(ref q) = query {
@@ -223,16 +243,16 @@ fn load_query(args: &QueryArgs) -> String {
     if let Some(ref path) = args.query_file {
         if path.as_os_str() == "-" {
             let mut buf = String::new();
-            io::stdin().read_to_string(&mut buf).expect("failed to read stdin");
+            io::stdin()
+                .read_to_string(&mut buf)
+                .expect("failed to read stdin");
             return buf;
         }
         return fs::read_to_string(path).expect("failed to read query file");
     }
     unreachable!()
 }
 
-
-
 fn print_help(topic: Option<&str>) {
     match topic {
         None => {
@@ -255,4 +275,4 @@ fn print_help(topic: Option<&str>) {
             std::process::exit(1);
         }
     }
-}
+}

crates/plotnik-lib/src/lib.rs

@@ -17,7 +17,7 @@
 
 pub mod ql;
 
-use ql::ast::Root;
+use ql::ast::{Root, format_ast};
 use ql::parser::{self, ErrorStage, Parse, SyntaxError};
 use ql::resolve::SymbolTable;
 use ql::syntax_kind::SyntaxNode;
@@ -151,6 +151,11 @@ impl<'a> Query<'a> {
         out
     }
 
+    /// Format AST structure (semantic tree without syntactic tokens).
+    pub fn format_ast(&self) -> String {
+        format_ast(&self.root())
+    }
+
     /// Format symbol references (without errors).
     pub fn format_refs(&self) -> String {
         let mut out = String::new();
@@ -183,6 +188,17 @@ impl<'a> Query<'a> {
         out
     }
 
+    /// Snapshot of AST structure (with errors).
+    pub fn snapshot_ast(&self) -> String {
+        let mut out = self.format_ast();
+        if !self.errors.is_empty() {
+            out.push_str("---\n");
+            out.push_str(&self.render_errors());
+            out.push('\n');
+        }
+        out
+    }
+
     /// Snapshot of CST structure (with trivia, with errors).
     pub fn snapshot_cst_raw(&self) -> String {
         let mut out = self.format_cst_raw();

crates/plotnik-lib/src/ql/ast.rs

@@ -4,6 +4,7 @@
 //! Cast is infallible for correct `SyntaxKind` - validation happens elsewhere.
 
 use crate::ql::syntax_kind::{SyntaxKind, SyntaxNode, SyntaxToken};
+use std::fmt::Write;
 
 macro_rules! ast_node {
     ($name:ident, $kind:ident) => {
@@ -252,3 +253,139 @@ impl Lit {
             .find(|t| t.kind() == SyntaxKind::StringLit)
     }
 }
+
+pub fn format_ast(root: &Root) -> String {
+    let mut out = String::new();
+    format_root(root, &mut out);
+    out
+}
+
+fn format_root(root: &Root, out: &mut String) {
+    out.push_str("Root\n");
+    for def in root.defs() {
+        format_def(&def, 1, out);
+    }
+    for expr in root.exprs() {
+        format_expr(&expr, 1, out);
+    }
+}
+
+fn format_def(def: &Def, indent: usize, out: &mut String) {
+    let prefix = "  ".repeat(indent);
+    let name = def.name().map(|t| t.text().to_string());
+    match name {
+        Some(n) => {
+            let _ = writeln!(out, "{}Def {}", prefix, n);
+        }
+        None => {
+            let _ = writeln!(out, "{}Def", prefix);
+        }
+    }
+    if let Some(body) = def.body() {
+        format_expr(&body, indent + 1, out);
+    }
+}
+
+fn format_expr(expr: &Expr, indent: usize, out: &mut String) {
+    let prefix = "  ".repeat(indent);
+    match expr {
+        Expr::Tree(t) => {
+            let node_type = t.node_type().map(|tok| tok.text().to_string());
+            match node_type {
+                Some(ty) => {
+                    let _ = writeln!(out, "{}Tree {}", prefix, ty);
+                }
+                None => {
+                    let _ = writeln!(out, "{}Tree", prefix);
+                }
+            }
+            for child in t.children() {
+                format_expr(&child, indent + 1, out);
+            }
+        }
+        Expr::Ref(r) => {
+            let name = r.name().map(|t| t.text().to_string()).unwrap_or_default();
+            let _ = writeln!(out, "{}Ref {}", prefix, name);
+        }
+        Expr::Lit(l) => {
+            let value = l.value().map(|t| t.text().to_string()).unwrap_or_default();
+            let _ = writeln!(out, "{}Lit {}", prefix, value);
+        }
+        Expr::Alt(a) => {
+            let _ = writeln!(out, "{}Alt", prefix);
+            for branch in a.branches() {
+                format_branch(&branch, indent + 1, out);
+            }
+            for expr in a.exprs() {
+                format_expr(&expr, indent + 1, out);
+            }
+        }
+        Expr::Seq(s) => {
+            let _ = writeln!(out, "{}Seq", prefix);
+            for child in s.children() {
+                format_expr(&child, indent + 1, out);
+            }
+        }
+        Expr::Capture(c) => {
+            let name = c.name().map(|t| t.text().to_string()).unwrap_or_default();
+            let type_ann = c
+                .type_annotation()
+                .and_then(|t| t.name())
+                .map(|t| t.text().to_string());
+            match type_ann {
+                Some(ty) => {
+                    let _ = writeln!(out, "{}Capture @{} :: {}", prefix, name, ty);
+                }
+                None => {
+                    let _ = writeln!(out, "{}Capture @{}", prefix, name);
+                }
+            }
+            if let Some(inner) = c.inner() {
+                format_expr(&inner, indent + 1, out);
+            }
+        }
+        Expr::Quantifier(q) => {
+            let op = q
+                .operator()
+                .map(|t| t.text().to_string())
+                .unwrap_or_default();
+            let _ = writeln!(out, "{}Quantifier {}", prefix, op);
+            if let Some(inner) = q.inner() {
+                format_expr(&inner, indent + 1, out);
+            }
+        }
+        Expr::Field(f) => {
+            let name = f.name().map(|t| t.text().to_string()).unwrap_or_default();
+            let _ = writeln!(out, "{}Field {}:", prefix, name);
+            if let Some(value) = f.value() {
+                format_expr(&value, indent + 1, out);
+            }
+        }
+        Expr::NegatedField(f) => {
+            let name = f.name().map(|t| t.text().to_string()).unwrap_or_default();
+            let _ = writeln!(out, "{}NegatedField !{}", prefix, name);
+        }
+        Expr::Wildcard(_) => {
+            let _ = writeln!(out, "{}Wildcard", prefix);
+        }
+        Expr::Anchor(_) => {
+            let _ = writeln!(out, "{}Anchor", prefix);
+        }
+    }
+}
+
+fn format_branch(branch: &Branch, indent: usize, out: &mut String) {
+    let prefix = "  ".repeat(indent);
+    let label = branch.label().map(|t| t.text().to_string());
+    match label {
+        Some(l) => {
+            let _ = writeln!(out, "{}Branch {}:", prefix, l);
+        }
+        None => {
+            let _ = writeln!(out, "{}Branch", prefix);
+        }
+    }
+    if let Some(body) = branch.body() {
+        format_expr(&body, indent + 1, out);
+    }
+}