dsl/

lib.rs

//! Symbiont DSL Parser Library
//!
//! This library provides parsing capabilities for the Symbiont DSL using Tree-sitter.

use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::time::Duration;
use tree_sitter::{Language, Node, Parser, Tree};

/// Canonical file extension for Symbiont agent definitions.
pub const SYMBI_EXTENSION: &str = "symbi";

/// Legacy file extension for Symbiont agent definitions. Continues to be
/// recognized indefinitely for backward compatibility; new files should
/// use `SYMBI_EXTENSION`.
pub const LEGACY_DSL_EXTENSION: &str = "dsl";

/// Returns true if the given path has a Symbiont agent definition extension
/// (either canonical `.symbi` or legacy `.dsl`).
pub fn is_symbi_file(path: &Path) -> bool {
    path.extension()
        .and_then(|ext| ext.to_str())
        .is_some_and(|ext| ext == SYMBI_EXTENSION || ext == LEGACY_DSL_EXTENSION)
}

/// Strip a recognized Symbiont agent extension (`.symbi` or `.dsl`) from a
/// filename, returning the stem. Returns `None` if the name has neither
/// extension.
pub fn strip_symbi_extension(name: &str) -> Option<&str> {
    name.strip_suffix(".symbi")
        .or_else(|| name.strip_suffix(".dsl"))
}

/// Maximum AST traversal depth. The Symbi DSL produces shallow trees in
/// practice (top-level block → attribute list → value); 256 gives generous
/// headroom for future extensions while still bounding stack usage for any
/// hand-crafted adversarial input. Exceeding this depth aborts the traversal
/// and emits a `tracing::warn!`.
const MAX_AST_DEPTH: usize = 256;

/// Sandbox tier enumeration representing different isolation levels
/// This mirrors the SandboxTier enum in the runtime crate to avoid circular dependencies
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum SandboxTier {
    /// Docker container sandbox
    Docker,
    /// gVisor sandbox for enhanced security
    GVisor,
    /// Firecracker microVM sandbox
    Firecracker,
    /// E2B.dev cloud sandbox
    E2B,
}

impl std::fmt::Display for SandboxTier {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            SandboxTier::Docker => write!(f, "docker"),
            SandboxTier::GVisor => write!(f, "gvisor"),
            SandboxTier::Firecracker => write!(f, "firecracker"),
            SandboxTier::E2B => write!(f, "e2b"),
        }
    }
}

// External function to get the language definition from the tree-sitter grammar
// This is generated by the tree-sitter build process and must be linked at compile time
extern "C" {
    fn tree_sitter_symbiont() -> Language;
}

/// Parse Symbiont DSL code and return the syntax tree
///
/// # Safety
///
/// This function uses an `unsafe` block to call the FFI function `tree_sitter_symbiont()`.
/// This is safe because:
///
/// 1. **Function Origin**: The `tree_sitter_symbiont()` function is generated by the
///    tree-sitter build process (build.rs) and follows the tree-sitter C ABI contract.
///
/// 2. **Invariants**: The tree-sitter library guarantees that language functions:
///    - Return a valid, immutable `Language` struct
///    - Are thread-safe and can be called multiple times
///    - Do not perform any unsafe memory operations
///    - Do not modify global state
///
/// 3. **Build Verification**: The language grammar is validated at build time by
///    tree-sitter's build system. Invalid grammars will fail to compile.
///
/// 4. **FFI Contract**: The tree-sitter `Language` type is an opaque handle that is
///    managed entirely by the tree-sitter library, ensuring memory safety.
///
/// # Panics
///
/// This function will panic if:
/// - The tree-sitter grammar was not properly linked at build time
/// - The language is incompatible with the tree-sitter runtime version
///
/// These are build-time errors that should be caught during development.
pub fn parse_dsl(source_code: &str) -> Result<Tree, Box<dyn std::error::Error>> {
    // SAFETY: See function documentation above. The tree_sitter_symbiont() function
    // is generated by tree-sitter's build system and follows all necessary safety
    // invariants for FFI calls. The returned Language is an opaque handle that is
    // fully managed by the tree-sitter library.
    let language = unsafe { tree_sitter_symbiont() };

    let mut parser = Parser::new();
    parser.set_language(language)?;

    let tree = parser
        .parse(source_code, None)
        .ok_or("Failed to parse DSL code")?;

    Ok(tree)
}

/// Print the AST in a readable format
pub fn print_ast(node: Node, source: &str, depth: usize) {
    let indent = "  ".repeat(depth);
    let node_text = if node.child_count() == 0 {
        let start = node.start_byte();
        let end = node.end_byte();
        format!(" \"{}\"", &source[start..end].replace('\n', "\\n"))
    } else {
        String::new()
    };

    println!(
        "{}{}: {}{}",
        indent,
        node.kind(),
        node_text,
        if node.is_error() { " [ERROR]" } else { "" }
    );

    for i in 0..node.child_count() {
        if let Some(child) = node.child(i) {
            print_ast(child, source, depth + 1);
        }
    }
}

/// WithBlock attribute structure
#[derive(Debug, Clone, PartialEq)]
pub struct WithAttribute {
    pub name: String,
    pub value: String,
}

/// WithBlock structure containing sandbox configuration
#[derive(Debug, Clone, PartialEq)]
pub struct WithBlock {
    pub attributes: Vec<WithAttribute>,
    pub sandbox_tier: Option<SandboxTier>,
    pub timeout: Option<u64>,
}

impl WithBlock {
    pub fn new() -> Self {
        Self {
            attributes: Vec::new(),
            sandbox_tier: None,
            timeout: None,
        }
    }

    /// Parse sandbox tier from string value, validating against known tiers
    pub fn parse_sandbox_tier(value: &str) -> Result<SandboxTier, String> {
        // Remove quotes if present
        let cleaned_value = value.trim_matches('"');
        match cleaned_value.to_lowercase().as_str() {
            "docker" => Ok(SandboxTier::Docker),
            "gvisor" => Ok(SandboxTier::GVisor),
            "firecracker" => Ok(SandboxTier::Firecracker),
            "e2b" => Ok(SandboxTier::E2B),
            _ => Err(format!(
                "Invalid sandbox tier: {}. Valid options are: docker, gvisor, firecracker, e2b",
                value
            )),
        }
    }
}

impl Default for WithBlock {
    fn default() -> Self {
        Self::new()
    }
}

/// Extract metadata from parsed AST
pub fn extract_metadata(tree: &Tree, source: &str) -> HashMap<String, String> {
    let mut metadata = HashMap::new();
    let root_node = tree.root_node();

    // Walk through the tree to find metadata blocks
    let _cursor = root_node.walk();

    fn traverse_for_metadata(
        node: Node,
        source: &str,
        metadata: &mut HashMap<String, String>,
        depth: usize,
    ) {
        if depth > MAX_AST_DEPTH {
            tracing::warn!(
                "DSL metadata traversal aborted: depth {} exceeds MAX_AST_DEPTH {}",
                depth,
                MAX_AST_DEPTH
            );
            return;
        }
        if node.kind() == "metadata_block" {
            // Extract metadata key-value pairs
            for i in 0..node.child_count() {
                if let Some(child) = node.child(i) {
                    if child.kind() == "metadata_pair" {
                        if let (Some(key_node), Some(value_node)) = (child.child(0), child.child(2))
                        {
                            let key =
                                source[key_node.start_byte()..key_node.end_byte()].to_string();
                            let value =
                                source[value_node.start_byte()..value_node.end_byte()].to_string();
                            metadata.insert(key, value);
                        }
                    }
                }
            }
        }

        // Recursively traverse children
        for i in 0..node.child_count() {
            if let Some(child) = node.child(i) {
                traverse_for_metadata(child, source, metadata, depth + 1);
            }
        }
    }

    traverse_for_metadata(root_node, source, &mut metadata, 0);
    metadata
}

/// Extract with blocks from parsed AST
pub fn extract_with_blocks(tree: &Tree, source: &str) -> Result<Vec<WithBlock>, String> {
    let mut with_blocks = Vec::new();
    let root_node = tree.root_node();

    fn traverse_for_with_blocks(
        node: Node,
        source: &str,
        with_blocks: &mut Vec<WithBlock>,
        depth: usize,
    ) -> Result<(), String> {
        if depth > MAX_AST_DEPTH {
            return Err(format!(
                "DSL AST traversal depth exceeded MAX_AST_DEPTH ({})",
                MAX_AST_DEPTH
            ));
        }
        if node.kind() == "with_block" {
            let mut with_block = WithBlock::new();

            // Extract with attributes
            for i in 0..node.child_count() {
                if let Some(child) = node.child(i) {
                    if child.kind() == "with_attribute" {
                        if let (Some(name_node), Some(value_node)) =
                            (child.child(0), child.child(2))
                        {
                            let name =
                                source[name_node.start_byte()..name_node.end_byte()].to_string();
                            let value =
                                source[value_node.start_byte()..value_node.end_byte()].to_string();

                            let attribute = WithAttribute {
                                name: name.clone(),
                                value: value.clone(),
                            };
                            with_block.attributes.push(attribute);

                            // Parse specific attributes
                            match name.as_str() {
                                "sandbox" => match WithBlock::parse_sandbox_tier(&value) {
                                    Ok(tier) => with_block.sandbox_tier = Some(tier),
                                    Err(e) => return Err(e),
                                },
                                "timeout" => {
                                    let timeout_str = value.trim_matches('"');
                                    // Normalize DSL time suffixes to humantime units
                                    let normalized = if let Some(n) =
                                        timeout_str.strip_suffix(".seconds")
                                    {
                                        format!("{}s", n.trim())
                                    } else if let Some(n) = timeout_str.strip_suffix(".minutes") {
                                        format!("{}m", n.trim())
                                    } else if let Some(n) = timeout_str.strip_suffix(".hours") {
                                        format!("{}h", n.trim())
                                    } else {
                                        timeout_str.to_string()
                                    };

                                    // Try humantime first, fall back to bare number as seconds
                                    if let Ok(duration) = humantime::parse_duration(&normalized) {
                                        with_block.timeout = Some(duration.as_secs());
                                    } else if let Ok(seconds) = normalized.parse::<u64>() {
                                        with_block.timeout = Some(seconds);
                                    } else {
                                        return Err(format!("Invalid timeout value: {}", value));
                                    }
                                }
                                _ => {} // Other attributes are stored but not specially parsed
                            }
                        }
                    }
                }
            }

            with_blocks.push(with_block);
        }

        // Recursively traverse children
        for i in 0..node.child_count() {
            if let Some(child) = node.child(i) {
                traverse_for_with_blocks(child, source, with_blocks, depth + 1)?;
            }
        }

        Ok(())
    }

    traverse_for_with_blocks(root_node, source, &mut with_blocks, 0)?;
    Ok(with_blocks)
}

/// A parsed schedule definition from DSL `schedule` blocks.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ScheduleDefinition {
    /// Name identifier for this schedule.
    pub name: String,
    /// Cron expression (mutually exclusive with `at`).
    pub cron: Option<String>,
    /// One-shot datetime (mutually exclusive with `cron`).
    pub at: Option<String>,
    /// IANA timezone (e.g. "America/New_York"). Defaults to "UTC".
    pub timezone: String,
    /// Name of the agent to run on this schedule.
    pub agent: Option<String>,
    /// Policy name to apply to scheduled runs.
    pub policy: Option<String>,
    /// Audit level: "none", "errors_only", or "all_operations".
    pub audit: Option<String>,
    /// If true, job runs once then disables.
    pub one_shot: bool,
    /// Optional delivery target (e.g. "slack://channel").
    pub deliver: Option<String>,
}

impl ScheduleDefinition {
    fn new(name: String) -> Self {
        Self {
            name,
            cron: None,
            at: None,
            timezone: "UTC".to_string(),
            agent: None,
            policy: None,
            audit: None,
            one_shot: false,
            deliver: None,
        }
    }
}

/// Extract schedule definitions from parsed AST.
///
/// Looks for `schedule <name> { key: value, ... }` blocks and returns
/// structured `ScheduleDefinition` values. Validates that either `cron`
/// or `at` is present (but not both).
pub fn extract_schedule_definitions(
    tree: &Tree,
    source: &str,
) -> Result<Vec<ScheduleDefinition>, String> {
    let mut schedules = Vec::new();
    let root_node = tree.root_node();

    fn traverse_for_schedules(
        node: Node,
        source: &str,
        schedules: &mut Vec<ScheduleDefinition>,
        depth: usize,
    ) -> Result<(), String> {
        if depth > MAX_AST_DEPTH {
            return Err(format!(
                "DSL AST traversal depth exceeded MAX_AST_DEPTH ({})",
                MAX_AST_DEPTH
            ));
        }
        if node.kind() == "schedule_definition" {
            // Child 0 = "schedule" keyword, Child 1 = identifier, then "{", properties, "}"
            let name_node = node
                .child(1)
                .ok_or_else(|| "schedule_definition missing name".to_string())?;
            let name = source[name_node.start_byte()..name_node.end_byte()].to_string();
            let mut sched = ScheduleDefinition::new(name);

            for i in 0..node.child_count() {
                if let Some(child) = node.child(i) {
                    if child.kind() == "schedule_property" {
                        // Child 0 = key identifier, child 1 = ":", child 2 = value
                        if let (Some(key_node), Some(val_node)) = (child.child(0), child.child(2)) {
                            let key =
                                source[key_node.start_byte()..key_node.end_byte()].to_string();
                            let raw_value =
                                source[val_node.start_byte()..val_node.end_byte()].to_string();
                            // Strip surrounding quotes if present.
                            let value = raw_value.trim_matches('"').to_string();

                            match key.as_str() {
                                "cron" => sched.cron = Some(value),
                                "at" => sched.at = Some(value),
                                "timezone" => sched.timezone = value,
                                "agent" => sched.agent = Some(value),
                                "policy" => sched.policy = Some(value),
                                "audit" => sched.audit = Some(value),
                                "one_shot" => sched.one_shot = value == "true",
                                "deliver" => sched.deliver = Some(value),
                                _ => {
                                    // Unknown properties are silently ignored for forward compat.
                                }
                            }
                        }
                    }
                }
            }

            // Validate: must have cron or at, not both.
            match (&sched.cron, &sched.at) {
                (None, None) => {
                    return Err(format!(
                        "schedule '{}': must specify either 'cron' or 'at'",
                        sched.name
                    ));
                }
                (Some(_), Some(_)) => {
                    return Err(format!(
                        "schedule '{}': cannot specify both 'cron' and 'at'",
                        sched.name
                    ));
                }
                _ => {}
            }

            schedules.push(sched);
        }

        // Recurse into children.
        for i in 0..node.child_count() {
            if let Some(child) = node.child(i) {
                traverse_for_schedules(child, source, schedules, depth + 1)?;
            }
        }

        Ok(())
    }

    traverse_for_schedules(root_node, source, &mut schedules, 0)?;
    Ok(schedules)
}

/// Memory store backend type.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum MemoryStoreType {
    /// Markdown-file-based memory store.
    Markdown,
}

/// Search configuration for a memory store.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MemorySearchConfig {
    /// Weight for vector/semantic similarity (0.0–1.0).
    pub vector_weight: f64,
    /// Weight for keyword/BM25 matching (0.0–1.0).
    pub keyword_weight: f64,
}

impl Default for MemorySearchConfig {
    fn default() -> Self {
        Self {
            vector_weight: 0.7,
            keyword_weight: 0.3,
        }
    }
}

/// A parsed memory definition from DSL `memory` blocks.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MemoryDefinition {
    /// Name identifier for this memory store.
    pub name: String,
    /// Backend store type.
    pub store: MemoryStoreType,
    /// Filesystem path for the memory store.
    pub path: PathBuf,
    /// How long to retain memory entries.
    pub retention: Duration,
    /// Optional search configuration.
    pub search: Option<MemorySearchConfig>,
}

impl MemoryDefinition {
    fn new(name: String) -> Self {
        Self {
            name,
            store: MemoryStoreType::Markdown,
            path: PathBuf::from("data/agents"),
            retention: Duration::from_secs(90 * 86400),
            search: None,
        }
    }
}

/// Extract memory definitions from parsed AST.
///
/// Looks for `memory <name> { key value, ... }` blocks and returns
/// structured `MemoryDefinition` values.
pub fn extract_memory_definitions(
    tree: &Tree,
    source: &str,
) -> Result<Vec<MemoryDefinition>, String> {
    let mut memories = Vec::new();
    let root_node = tree.root_node();

    fn traverse_for_memories(
        node: Node,
        source: &str,
        memories: &mut Vec<MemoryDefinition>,
        depth: usize,
    ) -> Result<(), String> {
        if depth > MAX_AST_DEPTH {
            return Err(format!(
                "DSL AST traversal depth exceeded MAX_AST_DEPTH ({})",
                MAX_AST_DEPTH
            ));
        }
        if node.kind() == "memory_definition" {
            // Child 0 = "memory" keyword, Child 1 = identifier, then "{", properties, "}"
            let name_node = node
                .child(1)
                .ok_or_else(|| "memory_definition missing name".to_string())?;
            let name = source[name_node.start_byte()..name_node.end_byte()].to_string();
            let mut mem = MemoryDefinition::new(name);

            for i in 0..node.child_count() {
                if let Some(child) = node.child(i) {
                    match child.kind() {
                        "memory_property" => {
                            // memory_property: identifier value (space-separated, NO colon)
                            // child(0) = key, child(1) = value
                            if let (Some(key_node), Some(val_node)) =
                                (child.child(0), child.child(1))
                            {
                                let key =
                                    source[key_node.start_byte()..key_node.end_byte()].to_string();
                                let raw_value =
                                    source[val_node.start_byte()..val_node.end_byte()].to_string();
                                let value = raw_value.trim_matches('"').to_string();

                                match key.as_str() {
                                    "store" => match value.to_lowercase().as_str() {
                                        "markdown" => mem.store = MemoryStoreType::Markdown,
                                        _ => {
                                            return Err(format!(
                                                "memory '{}': unknown store type '{}'",
                                                mem.name, value
                                            ));
                                        }
                                    },
                                    "path" => mem.path = PathBuf::from(value),
                                    "retention" => {
                                        mem.retention =
                                            humantime::parse_duration(&value).map_err(|e| {
                                                format!(
                                                    "memory '{}': invalid retention '{}': {}",
                                                    mem.name, value, e
                                                )
                                            })?;
                                    }
                                    _ => {
                                        // Unknown properties are silently ignored for forward compat.
                                    }
                                }
                            }
                        }
                        "memory_search_block" => {
                            // memory_search_block: 'search' '{' repeat(memory_search_property) '}'
                            let mut search = MemorySearchConfig::default();
                            for j in 0..child.child_count() {
                                if let Some(prop_node) = child.child(j) {
                                    if prop_node.kind() == "memory_search_property" {
                                        // memory_search_property: identifier value (space-separated)
                                        // child(0) = key, child(1) = value
                                        if let (Some(key_node), Some(val_node)) =
                                            (prop_node.child(0), prop_node.child(1))
                                        {
                                            let key = source
                                                [key_node.start_byte()..key_node.end_byte()]
                                                .to_string();
                                            let raw_value = source
                                                [val_node.start_byte()..val_node.end_byte()]
                                                .to_string();

                                            match key.as_str() {
                                                "vector_weight" => {
                                                    search.vector_weight = raw_value
                                                        .parse::<f64>()
                                                        .map_err(|e| {
                                                            format!(
                                                                "memory: invalid vector_weight '{}': {}",
                                                                raw_value, e
                                                            )
                                                        })?;
                                                }
                                                "keyword_weight" => {
                                                    search.keyword_weight = raw_value
                                                        .parse::<f64>()
                                                        .map_err(|e| {
                                                            format!(
                                                                "memory: invalid keyword_weight '{}': {}",
                                                                raw_value, e
                                                            )
                                                        })?;
                                                }
                                                _ => {
                                                    // Unknown search properties ignored.
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                            mem.search = Some(search);
                        }
                        _ => {}
                    }
                }
            }

            memories.push(mem);
        }

        // Recurse into children.
        for i in 0..node.child_count() {
            if let Some(child) = node.child(i) {
                traverse_for_memories(child, source, memories, depth + 1)?;
            }
        }

        Ok(())
    }

    traverse_for_memories(root_node, source, &mut memories, 0)?;
    Ok(memories)
}

/// Webhook provider type.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum WebhookProvider {
    /// GitHub webhook provider.
    GitHub,
    /// Stripe webhook provider.
    Stripe,
    /// Slack webhook provider.
    Slack,
    /// Custom/unknown webhook provider.
    Custom,
}

impl std::str::FromStr for WebhookProvider {
    type Err = std::convert::Infallible;

    /// Parse a provider name case-insensitively. Unknown providers become `Custom`.
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Ok(match s.to_lowercase().as_str() {
            "github" => WebhookProvider::GitHub,
            "stripe" => WebhookProvider::Stripe,
            "slack" => WebhookProvider::Slack,
            _ => WebhookProvider::Custom,
        })
    }
}

impl WebhookProvider {
    /// Parse a provider name case-insensitively. Unknown providers become `Custom`.
    pub fn parse(s: &str) -> Self {
        s.parse().unwrap()
    }
}

/// Filter configuration for a webhook.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct WebhookFilter {
    /// JSON path expression to match against the webhook payload.
    pub json_path: String,
    /// Exact match value.
    pub equals: Option<String>,
    /// Substring match value.
    pub contains: Option<String>,
}

/// A parsed webhook definition from DSL `webhook` blocks.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct WebhookDefinition {
    /// Name identifier for this webhook.
    pub name: String,
    /// URL path to receive webhooks on.
    pub path: String,
    /// Webhook provider type.
    pub provider: WebhookProvider,
    /// Secret for webhook signature verification.
    pub secret: String,
    /// Name of the agent to invoke on webhook receipt.
    pub agent: Option<String>,
    /// Optional filter to apply to incoming webhook payloads.
    pub filter: Option<WebhookFilter>,
}

impl WebhookDefinition {
    fn new(name: String) -> Self {
        Self {
            name,
            path: String::new(),
            provider: WebhookProvider::Custom,
            secret: String::new(),
            agent: None,
            filter: None,
        }
    }
}

/// Extract webhook definitions from parsed AST.
///
/// Looks for `webhook <name> { key value, ... }` blocks and returns
/// structured `WebhookDefinition` values. Validates that `path` is present.
pub fn extract_webhook_definitions(
    tree: &Tree,
    source: &str,
) -> Result<Vec<WebhookDefinition>, String> {
    let mut webhooks = Vec::new();
    let root_node = tree.root_node();

    /// Apply a key-value pair to the webhook definition.
    fn apply_webhook_property(
        key: &str,
        value: &str,
        webhook: &mut WebhookDefinition,
        has_path: &mut bool,
    ) {
        match key {
            "path" => {
                webhook.path = value.to_string();
                *has_path = true;
            }
            "provider" => {
                webhook.provider = WebhookProvider::parse(value);
            }
            "secret" => webhook.secret = value.to_string(),
            "agent" => webhook.agent = Some(value.to_string()),
            _ => {
                // Unknown properties are silently ignored for forward compat.
            }
        }
    }

    /// Extract key-value pairs from a node, handling both webhook_property nodes
    /// and ERROR nodes that contain identifier pairs (for unquoted values).
    fn extract_webhook_props_from_node(
        node: Node,
        source: &str,
        webhook: &mut WebhookDefinition,
        has_path: &mut bool,
    ) {
        match node.kind() {
            "webhook_property" => {
                // webhook_property: identifier value (space-separated, NO colon)
                // child(0) = key, child(1) = value
                if let (Some(key_node), Some(val_node)) = (node.child(0), node.child(1)) {
                    let key = source[key_node.start_byte()..key_node.end_byte()].to_string();
                    let raw_value = source[val_node.start_byte()..val_node.end_byte()].to_string();
                    let value = raw_value.trim_matches('"').to_string();
                    apply_webhook_property(&key, &value, webhook, has_path);
                }
            }
            "ERROR" => {
                // When tree-sitter encounters an unquoted identifier as a value
                // (e.g. `provider github`), it wraps the pair in an ERROR node
                // with two identifier children. We also recurse to find any
                // webhook_property nodes nested inside the ERROR node.
                let mut i = 0;
                while i < node.child_count() {
                    if let Some(child) = node.child(i) {
                        if child.kind() == "identifier" {
                            // Check if next sibling is also an identifier (unquoted value pair)
                            if let Some(next) = node.child(i + 1) {
                                if next.kind() == "identifier" {
                                    let key =
                                        source[child.start_byte()..child.end_byte()].to_string();
                                    let value =
                                        source[next.start_byte()..next.end_byte()].to_string();
                                    apply_webhook_property(&key, &value, webhook, has_path);
                                    i += 2;
                                    continue;
                                }
                            }
                        } else if child.kind() == "webhook_property" {
                            // Nested webhook_property inside ERROR node
                            extract_webhook_props_from_node(child, source, webhook, has_path);
                        }
                    }
                    i += 1;
                }
            }
            _ => {}
        }
    }

    fn traverse_for_webhooks(
        node: Node,
        source: &str,
        webhooks: &mut Vec<WebhookDefinition>,
        depth: usize,
    ) -> Result<(), String> {
        if depth > MAX_AST_DEPTH {
            return Err(format!(
                "DSL AST traversal depth exceeded MAX_AST_DEPTH ({})",
                MAX_AST_DEPTH
            ));
        }
        if node.kind() == "webhook_definition" {
            // Child 0 = "webhook" keyword, Child 1 = identifier, then "{", properties, "}"
            let name_node = node
                .child(1)
                .ok_or_else(|| "webhook_definition missing name".to_string())?;
            let name = source[name_node.start_byte()..name_node.end_byte()].to_string();
            let mut webhook = WebhookDefinition::new(name);
            let mut has_path = false;

            for i in 0..node.child_count() {
                if let Some(child) = node.child(i) {
                    if child.kind() == "webhook_filter_block" {
                        // webhook_filter_block: 'filter' '{' repeat(webhook_filter_property) '}'
                        let mut json_path = String::new();
                        let mut equals = None;
                        let mut contains = None;

                        for j in 0..child.child_count() {
                            if let Some(prop_node) = child.child(j) {
                                if prop_node.kind() == "webhook_filter_property" {
                                    // webhook_filter_property: identifier value (space-separated)
                                    // child(0) = key, child(1) = value
                                    if let (Some(key_node), Some(val_node)) =
                                        (prop_node.child(0), prop_node.child(1))
                                    {
                                        let key = source
                                            [key_node.start_byte()..key_node.end_byte()]
                                            .to_string();
                                        let raw_value = source
                                            [val_node.start_byte()..val_node.end_byte()]
                                            .to_string();
                                        let value = raw_value.trim_matches('"').to_string();

                                        match key.as_str() {
                                            "json_path" => json_path = value,
                                            "equals" => equals = Some(value),
                                            "contains" => contains = Some(value),
                                            _ => {
                                                // Unknown filter properties ignored.
                                            }
                                        }
                                    }
                                }
                            }
                        }

                        webhook.filter = Some(WebhookFilter {
                            json_path,
                            equals,
                            contains,
                        });
                    } else {
                        extract_webhook_props_from_node(child, source, &mut webhook, &mut has_path);
                    }
                }
            }

            // Validate: path is required.
            if !has_path {
                return Err(format!("webhook '{}': must specify 'path'", webhook.name));
            }

            webhooks.push(webhook);
        }

        // Recurse into children.
        for i in 0..node.child_count() {
            if let Some(child) = node.child(i) {
                traverse_for_webhooks(child, source, webhooks, depth + 1)?;
            }
        }

        Ok(())
    }

    traverse_for_webhooks(root_node, source, &mut webhooks, 0)?;
    Ok(webhooks)
}

/// A parsed channel definition from DSL `channel` blocks.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ChannelDefinition {
    pub name: String,
    pub platform: Option<String>,
    pub workspace: Option<String>,
    pub channels: Vec<String>,
    pub default_agent: Option<String>,
    pub dlp_profile: Option<String>,
    pub audit_level: Option<String>,
    pub default_deny: bool,
    pub policy_rules: Vec<ChannelPolicyRule>,
    pub data_classification: Vec<DataClassificationEntry>,
}

impl ChannelDefinition {
    fn new(name: String) -> Self {
        Self {
            name,
            platform: None,
            workspace: None,
            channels: Vec::new(),
            default_agent: None,
            dlp_profile: None,
            audit_level: None,
            default_deny: false,
            policy_rules: Vec::new(),
            data_classification: Vec::new(),
        }
    }
}

/// A policy rule within a channel definition.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ChannelPolicyRule {
    /// Action kind: "allow", "deny", "require", or "audit".
    pub action: String,
    /// Raw expression text (e.g. `invoke("compliance_check")`).
    pub expression: String,
}

/// A data classification entry within a channel definition.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DataClassificationEntry {
    /// Category label (e.g. "pii", "phi", "api_key").
    pub category: String,
    /// Action to take: "redact", "block", "allow".
    pub action: String,
}

/// Extract channel definitions from parsed AST.
///
/// Looks for `channel <name> { ... }` blocks and returns structured
/// `ChannelDefinition` values. Validates that `platform` is present.
pub fn extract_channel_definitions(
    tree: &Tree,
    source: &str,
) -> Result<Vec<ChannelDefinition>, String> {
    let mut channels = Vec::new();
    let root_node = tree.root_node();

    fn extract_array_strings(node: Node, source: &str) -> Vec<String> {
        let mut items = Vec::new();
        for i in 0..node.child_count() {
            if let Some(child) = node.child(i) {
                if child.kind() == "expression" || child.kind() == "string" {
                    // For expression nodes, look for the string child
                    let text = source[child.start_byte()..child.end_byte()].to_string();
                    items.push(text.trim_matches('"').to_string());
                } else if child.kind() != "[" && child.kind() != "]" && child.kind() != "," {
                    // Recurse into expression wrappers
                    let nested = extract_array_strings(child, source);
                    items.extend(nested);
                }
            }
        }
        items
    }

    fn traverse_for_channels(
        node: Node,
        source: &str,
        channels: &mut Vec<ChannelDefinition>,
        depth: usize,
    ) -> Result<(), String> {
        if depth > MAX_AST_DEPTH {
            return Err(format!(
                "DSL AST traversal depth exceeded MAX_AST_DEPTH ({})",
                MAX_AST_DEPTH
            ));
        }
        if node.kind() == "channel_definition" {
            let name_node = node
                .child(1)
                .ok_or_else(|| "channel_definition missing name".to_string())?;
            let name = source[name_node.start_byte()..name_node.end_byte()].to_string();
            let mut chan = ChannelDefinition::new(name);

            for i in 0..node.child_count() {
                if let Some(child) = node.child(i) {
                    match child.kind() {
                        "channel_property" => {
                            // Child 0 = key identifier, child 1 = ":", child 2 = value or array
                            if let (Some(key_node), Some(val_node)) =
                                (child.child(0), child.child(2))
                            {
                                let key =
                                    source[key_node.start_byte()..key_node.end_byte()].to_string();

                                if val_node.kind() == "array" {
                                    // Parse array elements
                                    let items = extract_array_strings(val_node, source);
                                    if key == "channels" {
                                        chan.channels = items;
                                    }
                                } else {
                                    let raw_value = source
                                        [val_node.start_byte()..val_node.end_byte()]
                                        .to_string();
                                    let value = raw_value.trim_matches('"').to_string();

                                    match key.as_str() {
                                        "platform" => chan.platform = Some(value),
                                        "workspace" => chan.workspace = Some(value),
                                        "default_agent" => chan.default_agent = Some(value),
                                        "dlp_profile" => chan.dlp_profile = Some(value),
                                        "audit_level" => chan.audit_level = Some(value),
                                        "default_deny" => chan.default_deny = value == "true",
                                        _ => {
                                            // Unknown properties ignored for forward compat.
                                        }
                                    }
                                }
                            }
                        }
                        "channel_policy_block" => {
                            // Extract nested policy rules
                            for j in 0..child.child_count() {
                                if let Some(rule_node) = child.child(j) {
                                    if rule_node.kind() == "policy_rule" {
                                        // Child 0 = action keyword, child 1 = ":", child 2 = expression
                                        if let (Some(action_node), Some(expr_node)) =
                                            (rule_node.child(0), rule_node.child(2))
                                        {
                                            let action = source
                                                [action_node.start_byte()..action_node.end_byte()]
                                                .to_string();
                                            let expression = source
                                                [expr_node.start_byte()..expr_node.end_byte()]
                                                .to_string();
                                            chan.policy_rules
                                                .push(ChannelPolicyRule { action, expression });
                                        }
                                    }
                                }
                            }
                        }
                        "channel_data_classification_block" => {
                            // Extract data classification rules
                            for j in 0..child.child_count() {
                                if let Some(rule_node) = child.child(j) {
                                    if rule_node.kind() == "data_classification_rule" {
                                        // Child 0 = category, child 1 = ":", child 2 = action
                                        if let (Some(cat_node), Some(act_node)) =
                                            (rule_node.child(0), rule_node.child(2))
                                        {
                                            let category = source
                                                [cat_node.start_byte()..cat_node.end_byte()]
                                                .to_string();
                                            let action = source
                                                [act_node.start_byte()..act_node.end_byte()]
                                                .to_string();
                                            chan.data_classification
                                                .push(DataClassificationEntry { category, action });
                                        }
                                    }
                                }
                            }
                        }
                        _ => {}
                    }
                }
            }

            // Validate: platform is required.
            if chan.platform.is_none() {
                return Err(format!("channel '{}': must specify 'platform'", chan.name));
            }

            channels.push(chan);
        }

        // Recurse into children.
        for i in 0..node.child_count() {
            if let Some(child) = node.child(i) {
                traverse_for_channels(child, source, channels, depth + 1)?;
            }
        }

        Ok(())
    }

    traverse_for_channels(root_node, source, &mut channels, 0)?;
    Ok(channels)
}

/// A structured diagnostic emitted by error analysis
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DslDiagnostic {
    /// 1-based start line
    pub start_line: usize,
    /// 1-based start column
    pub start_col: usize,
    /// 1-based end line
    pub end_line: usize,
    /// 1-based end column
    pub end_col: usize,
    /// The source text of the erroneous node
    pub snippet: String,
    /// Nesting depth at which the error was found
    pub depth: usize,
}

impl std::fmt::Display for DslDiagnostic {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "ERROR at {}:{}-{}:{}: '{}'",
            self.start_line, self.start_col, self.end_line, self.end_col, self.snippet
        )
    }
}

/// Find errors in the AST and return them as structured diagnostics
pub fn find_errors(node: Node, source: &str, depth: usize) -> Vec<DslDiagnostic> {
    let mut diagnostics = Vec::new();
    collect_errors(node, source, depth, &mut diagnostics);
    diagnostics
}

fn collect_errors(node: Node, source: &str, depth: usize, diagnostics: &mut Vec<DslDiagnostic>) {
    if node.kind() == "ERROR" {
        let start = node.start_position();
        let end = node.end_position();
        let text = &source[node.start_byte()..node.end_byte()];
        diagnostics.push(DslDiagnostic {
            start_line: start.row + 1,
            start_col: start.column + 1,
            end_line: end.row + 1,
            end_col: end.column + 1,
            snippet: text.to_string(),
            depth,
        });
    }

    for i in 0..node.child_count() {
        if let Some(child) = node.child(i) {
            collect_errors(child, source, depth + 1, diagnostics);
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_extension_helpers() {
        assert!(is_symbi_file(Path::new("foo.symbi")));
        assert!(is_symbi_file(Path::new("foo.dsl")));
        assert!(is_symbi_file(Path::new("agents/bar.symbi")));
        assert!(!is_symbi_file(Path::new("foo.txt")));
        assert!(!is_symbi_file(Path::new("foo")));
        assert!(!is_symbi_file(Path::new("foo.SYMBI")));

        assert_eq!(strip_symbi_extension("agent.symbi"), Some("agent"));
        assert_eq!(strip_symbi_extension("agent.dsl"), Some("agent"));
        assert_eq!(strip_symbi_extension("agent"), None);
        assert_eq!(strip_symbi_extension("agent.txt"), None);
    }

    #[test]
    fn test_basic_parsing() {
        let simple_dsl = r#"
        agent TestAgent {
            capabilities: [test]
        }
        "#;

        let result = parse_dsl(simple_dsl);
        assert!(result.is_ok(), "Basic DSL parsing should succeed");
    }

    #[test]
    fn test_metadata_extraction() {
        let dsl_with_metadata = r#"
        metadata {
            version: "1.0",
            author: "Test"
        }
        "#;

        if let Ok(tree) = parse_dsl(dsl_with_metadata) {
            let metadata = extract_metadata(&tree, dsl_with_metadata);
            assert!(!metadata.is_empty(), "Should extract metadata");
        }
    }

    #[test]
    fn test_with_block_parsing() {
        let agent_with_sandbox = r#"
        agent code_runner(script: String) -> Output {
            with sandbox = "e2b", timeout = 60.seconds {
                return execute(script);
            }
        }
        "#;

        if let Ok(tree) = parse_dsl(agent_with_sandbox) {
            let with_blocks = extract_with_blocks(&tree, agent_with_sandbox).unwrap();
            assert_eq!(with_blocks.len(), 1, "Should extract one with block");

            let with_block = &with_blocks[0];
            assert_eq!(with_block.sandbox_tier, Some(SandboxTier::E2B));
            assert_eq!(with_block.timeout, Some(60));
        }
    }

    #[test]
    fn test_sandbox_tier_validation() {
        assert_eq!(
            WithBlock::parse_sandbox_tier("docker"),
            Ok(SandboxTier::Docker)
        );
        assert_eq!(
            WithBlock::parse_sandbox_tier("gvisor"),
            Ok(SandboxTier::GVisor)
        );
        assert_eq!(
            WithBlock::parse_sandbox_tier("firecracker"),
            Ok(SandboxTier::Firecracker)
        );
        assert_eq!(WithBlock::parse_sandbox_tier("e2b"), Ok(SandboxTier::E2B));

        // Test with quotes
        assert_eq!(
            WithBlock::parse_sandbox_tier("\"docker\""),
            Ok(SandboxTier::Docker)
        );

        // Test invalid tier
        assert!(WithBlock::parse_sandbox_tier("invalid").is_err());
    }

    #[test]
    fn test_schedule_definition_parsing() {
        let dsl = r#"
        schedule morning_report {
            cron: "0 7 * * 1-5",
            timezone: "America/New_York",
            agent: "compliance_reporter",
            policy: "hipaa_guard",
            audit: "all_operations"
        }
        "#;

        let tree = parse_dsl(dsl).expect("should parse");
        let schedules = extract_schedule_definitions(&tree, dsl).unwrap();
        assert_eq!(schedules.len(), 1);

        let s = &schedules[0];
        assert_eq!(s.name, "morning_report");
        assert_eq!(s.cron.as_deref(), Some("0 7 * * 1-5"));
        assert_eq!(s.timezone, "America/New_York");
        assert_eq!(s.agent.as_deref(), Some("compliance_reporter"));
        assert_eq!(s.policy.as_deref(), Some("hipaa_guard"));
        assert_eq!(s.audit.as_deref(), Some("all_operations"));
        assert!(!s.one_shot);
    }

    #[test]
    fn test_schedule_one_shot() {
        let dsl = r#"
        schedule quarterly_check {
            at: "2026-03-31T23:59:00",
            timezone: "UTC",
            agent: "sox_auditor",
            one_shot: true
        }
        "#;

        let tree = parse_dsl(dsl).expect("should parse");
        let schedules = extract_schedule_definitions(&tree, dsl).unwrap();
        assert_eq!(schedules.len(), 1);

        let s = &schedules[0];
        assert_eq!(s.name, "quarterly_check");
        assert!(s.cron.is_none());
        assert_eq!(s.at.as_deref(), Some("2026-03-31T23:59:00"));
        assert!(s.one_shot);
    }

    #[test]
    fn test_schedule_missing_cron_and_at() {
        let dsl = r#"
        schedule bad_schedule {
            timezone: "UTC",
            agent: "some_agent"
        }
        "#;

        let tree = parse_dsl(dsl).expect("should parse");
        let result = extract_schedule_definitions(&tree, dsl);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("must specify either"));
    }

    #[test]
    fn test_schedule_both_cron_and_at_rejected() {
        let dsl = r#"
        schedule conflicting {
            cron: "0 * * * *",
            at: "2026-01-01T00:00:00",
            agent: "some_agent"
        }
        "#;

        let tree = parse_dsl(dsl).expect("should parse");
        let result = extract_schedule_definitions(&tree, dsl);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("cannot specify both"));
    }

    #[test]
    fn test_schedule_with_delivery() {
        let dsl = r#"
        schedule alerter {
            cron: "*/30 * * * *",
            agent: "compliance_agent",
            deliver: "slack://compliance-alerts"
        }
        "#;

        let tree = parse_dsl(dsl).expect("should parse");
        let schedules = extract_schedule_definitions(&tree, dsl).unwrap();
        assert_eq!(schedules.len(), 1);
        assert_eq!(
            schedules[0].deliver.as_deref(),
            Some("slack://compliance-alerts")
        );
    }

    #[test]
    fn test_multiple_schedules() {
        let dsl = r#"
        schedule job_a {
            cron: "0 * * * *",
            agent: "agent_a"
        }
        schedule job_b {
            at: "2026-06-01T12:00:00",
            agent: "agent_b",
            one_shot: true
        }
        "#;

        let tree = parse_dsl(dsl).expect("should parse");
        let schedules = extract_schedule_definitions(&tree, dsl).unwrap();
        assert_eq!(schedules.len(), 2);
        assert_eq!(schedules[0].name, "job_a");
        assert_eq!(schedules[1].name, "job_b");
    }

    #[test]
    fn test_with_block_attributes() {
        let agent_with_multiple_attrs = r#"
        agent test_agent {
            with sandbox = "docker", timeout = 30.seconds {
                return success();
            }
        }
        "#;

        if let Ok(tree) = parse_dsl(agent_with_multiple_attrs) {
            let with_blocks = extract_with_blocks(&tree, agent_with_multiple_attrs).unwrap();
            assert_eq!(with_blocks.len(), 1);

            let with_block = &with_blocks[0];
            assert_eq!(with_block.attributes.len(), 2);
            assert_eq!(with_block.sandbox_tier, Some(SandboxTier::Docker));
            assert_eq!(with_block.timeout, Some(30));
        }
    }

    #[test]
    fn test_timeout_seconds_suffix() {
        let dsl = r#"
        agent runner(s: String) -> Output {
            with timeout = 45.seconds {
                return execute(s);
            }
        }
        "#;
        let tree = parse_dsl(dsl).unwrap();
        let blocks = extract_with_blocks(&tree, dsl).unwrap();
        assert_eq!(blocks.len(), 1);
        assert_eq!(blocks[0].timeout, Some(45));
    }

    #[test]
    fn test_timeout_minutes_suffix() {
        let dsl = r#"
        agent runner(s: String) -> Output {
            with timeout = 30.minutes {
                return execute(s);
            }
        }
        "#;
        let tree = parse_dsl(dsl).unwrap();
        let blocks = extract_with_blocks(&tree, dsl).unwrap();
        assert_eq!(blocks.len(), 1);
        assert_eq!(blocks[0].timeout, Some(30 * 60));
    }

    #[test]
    fn test_timeout_hours_suffix() {
        let dsl = r#"
        agent runner(s: String) -> Output {
            with timeout = 2.hours {
                return execute(s);
            }
        }
        "#;
        let tree = parse_dsl(dsl).unwrap();
        let blocks = extract_with_blocks(&tree, dsl).unwrap();
        assert_eq!(blocks.len(), 1);
        assert_eq!(blocks[0].timeout, Some(2 * 3600));
    }

    #[test]
    fn test_timeout_bare_number() {
        let dsl = r#"
        agent runner(s: String) -> Output {
            with timeout = 120 {
                return execute(s);
            }
        }
        "#;
        let tree = parse_dsl(dsl).unwrap();
        let blocks = extract_with_blocks(&tree, dsl).unwrap();
        assert_eq!(blocks.len(), 1);
        assert_eq!(blocks[0].timeout, Some(120));
    }
}