LibXMLBehaviorTreeParser.cpp

Go to the documentation of this file.

#include "Parsers/LibXMLBehaviorTreeParser.h"
#include "Core/BehaviorTree.h"
#include "Core/BehaviorTreeValidator.h"
#include "Core/BlackboardEntry.h"
#include "Core/Node.h"
#include "Utils/Logger.h"
#include <algorithm>
#include <fstream>
#include <mutex>
 
namespace EmberCore {
 
// Static initialization
std::once_flag LibXMLBehaviorTreeParser::libxml2_init_flag_;
bool LibXMLBehaviorTreeParser::global_libxml2_initialized_ = false;
std::mutex LibXMLBehaviorTreeParser::destruction_mutex_;
 
LibXMLBehaviorTreeParser::LibXMLBehaviorTreeParser()
    : config_(ParserConfig::CreateDefault()), progress_callback_(nullptr), project_parsing_mode_(false),
      max_threads_(std::thread::hardware_concurrency()), thread_safe_(true), libxml2_initialized_(false) {
    InitializeLibXML2();
}
 
LibXMLBehaviorTreeParser::LibXMLBehaviorTreeParser(const ParserConfig &config)
    : config_(config), progress_callback_(nullptr), project_parsing_mode_(false),
      max_threads_(std::thread::hardware_concurrency()), thread_safe_(true), libxml2_initialized_(false) {
    InitializeLibXML2();
}
 
LibXMLBehaviorTreeParser::~LibXMLBehaviorTreeParser() {
    // Serialize destruction to prevent libxml2 race conditions
    // This mutex ensures only one parser destructor runs at a time
    std::lock_guard<std::mutex> lock(destruction_mutex_);
 
    // Clear internal state that may reference libxml2 memory
    parsed_trees_.clear();
    parsed_blackboards_.clear();
    expanded_subtree_cache_.clear();
    expansion_stack_.clear();
 
    // Don't call xmlCleanupParser() here - it's a global resource
    // libxml2 cleanup should only happen at application shutdown
}
 
// Simple error suppression handler (thread-safe)
static void SuppressLibXMLErrors(void *ctx, const char *msg, ...) {
    // Suppress all libxml2 error output to avoid thread-safety issues
    // Errors will be captured via structured error callbacks per-document
}
 
void LibXMLBehaviorTreeParser::InitializeLibXML2() {
    std::call_once(libxml2_init_flag_, [this]() {
        // Initialize libxml2 with threading support
        // NOTE: In tests, this is also called in main() before threads for extra safety
        xmlInitParser();
        LIBXML_TEST_VERSION
 
        // Enable threading support
        xmlInitThreads();
        thread_safe_ = true;
        LOG_INFO("LibXMLParser", "libxml2 threading support enabled");
 
        // Suppress default libxml2 error output (errors will be captured per-document)
        // This avoids thread-safety issues with global error handlers
        xmlSetGenericErrorFunc(nullptr, SuppressLibXMLErrors);
 
        global_libxml2_initialized_ = true;
        libxml2_initialized_ = true;
    });
}
 
std::shared_ptr<BehaviorTree> LibXMLBehaviorTreeParser::ParseFromFile(const EmberCore::String &filepath) {
    ClearErrors();
    parsed_trees_.clear();
    parsed_blackboards_.clear();
    current_file_path_ = filepath;
 
    // Report progress: Starting
    if (!ReportProgress("Opening XML file...", 0, 5)) {
        return nullptr; // User cancelled
    }
 
    // Check if file exists
    std::ifstream file(filepath);
    if (!file.good()) {
        AddError(ParseError::FILE_NOT_FOUND, EmberCore::String("File not found: ") + filepath);
        ReportProgress("ERROR: File not found", 0, 5);
        return nullptr;
    }
 
    // Get file size for logging
    file.seekg(0, std::ios::end);
    std::streampos fileSize = file.tellg();
    file.seekg(0, std::ios::beg);
 
    EmberCore::String sizeStr;
    if (fileSize < 1024) {
        sizeStr = std::to_string(fileSize) + " bytes";
    } else if (fileSize < 1024 * 1024) {
        sizeStr = std::to_string(static_cast<double>(fileSize) / 1024.0) + " KB";
    } else {
        sizeStr = std::to_string(static_cast<double>(fileSize) / (1024.0 * 1024.0)) + " MB";
    }
    ReportProgress("File size: " + sizeStr + "", 0, 5);
 
    // Report progress: Loading XML
    if (!ReportProgress("Loading XML document...", 1, 5)) {
        return nullptr; // User cancelled
    }
 
    // Load XML document with libxml2
    xmlDocPtr doc = xmlParseFile(filepath.c_str());
    if (!doc) {
        AddError(ParseError::XML_SYNTAX_ERROR, EmberCore::String("Failed to parse XML file: ") + filepath);
        ReportProgress("ERROR: XML syntax error", 1, 5);
        return nullptr;
    }
 
    ReportProgress("XML document loaded successfully", 1, 5);
    LOG_INFO("LibXMLParser", EmberCore::String("Loading: ") + filepath);
 
    // Report progress: Parsing trees
    if (!ReportProgress("Parsing behavior trees...", 2, 5)) {
        xmlFreeDoc(doc);
        return nullptr; // User cancelled
    }
 
    // Parse the document
    bool success = ParseXMLDocument(doc, filepath);
    xmlFreeDoc(doc);
 
    if (!success) {
        ReportProgress("ERROR: Failed to parse document structure", 2, 5);
        return nullptr;
    }
 
    // Report progress: Finalizing
    if (!ReportProgress("Finalizing...", 4, 5)) {
        return nullptr; // User cancelled
    }
 
    ReportProgress("Parsed " + std::to_string(parsed_trees_.size()) + " tree(s) successfully", 4, 5);
 
    // Return the main tree if specified
    if (!main_tree_name_.empty() && parsed_trees_.count(main_tree_name_)) {
        auto main_tree = parsed_trees_[main_tree_name_];
 
        // Validate the tree structure using unified validator
        if (!ReportProgress("Validating tree structure...", 4, 5)) {
            return nullptr; // User cancelled
        }
 
        BehaviorTreeValidator validator(config_);
        auto validation_result = validator.Validate(main_tree.get());
 
        // Report validation errors (these block loading)
        if (validation_result.HasErrors()) {
            LOG_ERROR("LibXMLParser",
                      "Tree validation failed with " + std::to_string(validation_result.ErrorCount()) + " error(s):");
 
            for (const auto &issue : validation_result.issues) {
                if (issue.severity == BehaviorTreeValidator::Severity::ERROR) {
                    AddError(ParseError::INVALID_TREE_STRUCTURE, issue.message);
                    LOG_ERROR("LibXMLParser", "  [" + issue.node_path + "] " + issue.message);
                }
            }
 
            ReportProgress("ERROR: Tree validation failed", 4, 5);
            return nullptr; // Errors block loading
        }
 
        // Report validation warnings (these don't block loading)
        if (validation_result.HasWarnings()) {
            LOG_WARNING("LibXMLParser",
                        "Tree has " + std::to_string(validation_result.WarningCount()) + " warning(s):");
 
            for (const auto &issue : validation_result.issues) {
                if (issue.severity == BehaviorTreeValidator::Severity::WARNING) {
                    LOG_WARNING("LibXMLParser", "  [" + issue.node_path + "] " + issue.message);
                }
            }
        }
 
        ReportProgress("Tree validation passed", 4, 5);
        return main_tree;
    }
 
    // Return the first tree if no main tree specified
    if (!parsed_trees_.empty()) {
        auto first_tree = parsed_trees_.begin()->second;
 
        // Validate the tree structure
        BehaviorTreeValidator validator(config_);
        auto validation_result = validator.Validate(first_tree.get());
 
        if (validation_result.HasErrors()) {
            for (const auto &issue : validation_result.issues) {
                if (issue.severity == BehaviorTreeValidator::Severity::ERROR) {
                    AddError(ParseError::INVALID_TREE_STRUCTURE, issue.message);
                }
            }
            return nullptr; // Errors block loading
        }
 
        return first_tree;
    }
 
    AddError(ParseError::MISSING_BEHAVIOR_TREE, "No behavior trees found in XML file");
    return nullptr;
}
 
std::shared_ptr<BehaviorTree> LibXMLBehaviorTreeParser::ParseFromString(const EmberCore::String &xml_content) {
    ClearErrors();
    parsed_trees_.clear();
    parsed_blackboards_.clear();
    current_file_path_ = "<string>";
 
    // Load XML from string with libxml2
    xmlDocPtr doc = xmlParseMemory(xml_content.c_str(), xml_content.length());
    if (!doc) {
        AddError(ParseError::XML_SYNTAX_ERROR, "Failed to parse XML content");
        return nullptr;
    }
 
    // Parse the document
    if (!ParseXMLDocument(doc)) {
        xmlFreeDoc(doc);
        return nullptr;
    }
 
    xmlFreeDoc(doc);
 
    // Return the main tree if specified
    if (!main_tree_name_.empty() && parsed_trees_.count(main_tree_name_)) {
        auto main_tree = parsed_trees_[main_tree_name_];
 
        // Validate the tree structure
        BehaviorTreeValidator validator(config_);
        auto validation_result = validator.Validate(main_tree.get());
 
        if (validation_result.HasErrors()) {
            for (const auto &issue : validation_result.issues) {
                if (issue.severity == BehaviorTreeValidator::Severity::ERROR) {
                    AddError(ParseError::INVALID_TREE_STRUCTURE, issue.message);
                }
            }
            return nullptr; // Errors block loading
        }
 
        return main_tree;
    }
 
    // Return the first tree if no main tree specified
    if (!parsed_trees_.empty()) {
        auto first_tree = parsed_trees_.begin()->second;
 
        // Validate the tree structure
        BehaviorTreeValidator validator(config_);
        auto validation_result = validator.Validate(first_tree.get());
 
        if (validation_result.HasErrors()) {
            for (const auto &issue : validation_result.issues) {
                if (issue.severity == BehaviorTreeValidator::Severity::ERROR) {
                    AddError(ParseError::INVALID_TREE_STRUCTURE, issue.message);
                }
            }
            return nullptr; // Errors block loading
        }
 
        return first_tree;
    }
 
    AddError(ParseError::MISSING_BEHAVIOR_TREE, "No behavior trees found in XML content");
    return nullptr;
}
 
std::vector<LibXMLBehaviorTreeParser::ParseResult>
LibXMLBehaviorTreeParser::ParseMultipleFiles(const std::vector<EmberCore::String> &filepaths) {
 
    std::vector<ParseResult> results;
    results.reserve(filepaths.size());
 
    for (const auto &filepath : filepaths) {
        ParseResult result;
        result.file_path = filepath;
 
        try {
            result.tree = ParseFromFile(filepath);
            result.success = (result.tree != nullptr);
            if (!result.success) {
                std::lock_guard<std::mutex> lock(errors_mutex_);
                result.errors = errors_;
            }
        } catch (const std::exception &e) {
            result.success = false;
            result.errors.push_back(
                ParseError(ParseError::THREAD_ERROR, "Exception parsing " + filepath + ": " + std::string(e.what())));
        }
 
        results.push_back(result);
    }
 
    return results;
}
 
// ============================================================================
// Project Parsing Methods
// ============================================================================
 
int LibXMLBehaviorTreeParser::ProjectParseResult::GetImplementedTreeCount() const {
    int count = 0;
    for (const auto &pair : tree_statuses) {
        if (pair.second.is_implemented) {
            count++;
        }
    }
    return count;
}
 
int LibXMLBehaviorTreeParser::ProjectParseResult::GetTotalTreeCount() const {
    return static_cast<int>(tree_statuses.size());
}
 
LibXMLBehaviorTreeParser::ProjectParseResult LibXMLBehaviorTreeParser::ParseProject(BehaviorTreeProject *project) {
    if (!project) {
        ProjectParseResult result;
        result.errors.push_back(ParseError(ParseError::INVALID_VALUE, "Project is null"));
        return result;
    }
 
    // Get absolute paths for all resources
    std::vector<EmberCore::String> filepaths;
    for (const auto &resource : project->GetResources()) {
        filepaths.push_back(project->ResolveResourcePath(resource));
    }
 
    // Parse all files with shared registry
    ProjectParseResult result = ParseFilesWithSharedRegistry(filepaths);
 
    // Update project with tree implementation statuses
    if (result.success) {
        project->SetTreeImplementationStatus(result.tree_statuses);
    }
 
    return result;
}
 
LibXMLBehaviorTreeParser::ProjectParseResult
LibXMLBehaviorTreeParser::ParseFilesWithSharedRegistry(const std::vector<EmberCore::String> &filepaths) {
 
    ProjectParseResult result;
    result.success = true;
 
    // Clear existing state
    ClearErrors();
    parsed_trees_.clear();
    parsed_blackboards_.clear();
    tree_implementation_statuses_.clear();
    unimplemented_references_.clear();
    project_parsing_mode_ = true; // Enable project parsing mode
 
    int total_files = static_cast<int>(filepaths.size());
    int current_file = 0;
 
    ReportProgress("Starting project parsing...", 0, total_files + 2);
 
    std::vector<EmberCore::String> main_tree_candidates;
 
    // First pass: Parse all files to collect all trees
    for (const auto &filepath : filepaths) {
        current_file++;
        current_file_path_ = filepath;
 
        ReportProgress("Parsing file " + std::to_string(current_file) + "/" + std::to_string(total_files) + ": " +
                           filepath,
                       current_file, total_files + 2);
 
        // Check if file exists
        std::ifstream file(filepath);
        if (!file.good()) {
            // Create FileParseInfo even for failed files
            FileParseInfo failedInfo;
            failedInfo.filepath = filepath;
            failedInfo.parsed_successfully = false;
            failedInfo.errors.push_back("File not found: " + filepath);
            result.file_infos.push_back(failedInfo);
 
            result.errors.push_back(
                ParseError(ParseError::FILE_NOT_FOUND, EmberCore::String("File not found: ") + filepath, filepath));
            result.success = false;
            continue;
        }
        file.close();
 
        // Parse the XML file
        xmlDocPtr doc = xmlParseFile(filepath.c_str());
        if (!doc) {
            // Create FileParseInfo even for failed files
            FileParseInfo failedInfo;
            failedInfo.filepath = filepath;
            failedInfo.parsed_successfully = false;
            failedInfo.errors.push_back("Failed to parse XML file - syntax error");
            result.file_infos.push_back(failedInfo);
 
            result.errors.push_back(ParseError(ParseError::XML_SYNTAX_ERROR,
                                               EmberCore::String("Failed to parse XML file: ") + filepath, filepath));
            result.success = false;
            continue;
        }
 
        // Parse document but don't expand subtrees yet
        // (we'll do that after all files are parsed)
        xmlNodePtr root = xmlDocGetRootElement(doc);
        if (!root) {
            // Create FileParseInfo even for failed files
            FileParseInfo failedInfo;
            failedInfo.filepath = filepath;
            failedInfo.parsed_successfully = false;
            failedInfo.errors.push_back("XML document has no root element");
            result.file_infos.push_back(failedInfo);
 
            xmlFreeDoc(doc);
            result.errors.push_back(
                ParseError(ParseError::MISSING_ROOT_ELEMENT, "XML document has no root element", filepath));
            result.success = false;
            continue;
        }
 
        // Get configured element names
        const auto &doc_config = config_.GetDocumentConfig();
        const auto &tree_config = config_.GetTreeConfig();
 
        // Validate root element
        EmberCore::String root_name = GetNodeName(root);
        bool root_valid = false;
        if (doc_config.case_sensitive) {
            root_valid = (root_name == doc_config.root_element);
        } else {
            auto to_lower = [](String str) {
                std::transform(str.begin(), str.end(), str.begin(), ::tolower);
                return str;
            };
            root_valid = (to_lower(root_name) == to_lower(doc_config.root_element));
        }
 
        if (!root_valid) {
            // Create FileParseInfo even for failed files
            FileParseInfo failedInfo;
            failedInfo.filepath = filepath;
            failedInfo.parsed_successfully = false;
            failedInfo.errors.push_back("Expected '" + doc_config.root_element + "' element, found '" + root_name +
                                        "'");
            result.file_infos.push_back(failedInfo);
 
            xmlFreeDoc(doc);
            result.errors.push_back(ParseError(ParseError::MISSING_ROOT_ELEMENT,
                                               EmberCore::String("Expected '") + doc_config.root_element +
                                                   "' element, found '" + root_name + "'",
                                               filepath));
            result.success = false;
            continue;
        }
 
        // Collect main_tree_to_execute candidate from this file
        {
            EmberCore::String main_tree = GetNodeAttribute(root, doc_config.main_tree_attribute);
            if (!main_tree.empty()) {
                main_tree_candidates.push_back(main_tree);
            }
        }
 
        // Create file info for detailed validation
        FileParseInfo fileInfo;
        fileInfo.filepath = filepath;
        fileInfo.parsed_successfully = true;
 
        std::set<String> file_tree_ids;
        std::set<String> file_bb_ids;
        std::set<String> subtree_refs_set;
        std::set<String> bb_includes_set;
        std::map<String, std::vector<String>> per_bb_includes;
 
        // Parse all BehaviorTree and Blackboard nodes in this file
        for (xmlNodePtr child = root->children; child; child = child->next) {
            if (child->type == XML_ELEMENT_NODE) {
                EmberCore::String name = GetNodeName(child);
 
                if (name == tree_config.behavior_tree_element) {
                    // Parse BehaviorTree
                    fileInfo.has_behavior_trees = true;
                    fileInfo.tree_count++;
 
                    EmberCore::String tree_id = GetNodeAttribute(child, tree_config.tree_id_attribute);
                    if (tree_id.empty()) {
                        fileInfo.errors.push_back("BehaviorTree element missing required 'ID' attribute");
                    } else {
                        fileInfo.tree_ids.push_back(tree_id);
 
                        // Check for duplicate tree IDs within this file
                        if (file_tree_ids.count(tree_id) > 0) {
                            fileInfo.warnings.push_back("Duplicate tree ID within file: " + tree_id);
                        }
                        file_tree_ids.insert(tree_id);
 
                        auto tree = ParseBehaviorTree(child);
                        if (tree) {
                            parsed_trees_[tree_id] = tree;
 
                            // Track implementation status
                            TreeImplementationStatus status(tree_id);
                            status.is_implemented = tree->HasRootNode() && tree->GetNodeCount() > 0;
                            status.has_root_node = tree->HasRootNode();
                            status.defined_in_file = filepath;
                            tree_implementation_statuses_[tree_id] = status;
 
                            // Collect SubTree references
                            if (tree->HasRootNode()) {
                                CollectSubTreeReferences(tree->GetRootNode(), subtree_refs_set);
                            }
 
                            LOG_INFO("LibXMLParser", "Parsed tree '" + tree_id + "' from " + filepath);
                        }
                    }
                } else if (name == "Blackboard") {
                    // Parse Blackboard
                    fileInfo.has_blackboards = true;
                    fileInfo.blackboard_count++;
 
                    EmberCore::String bb_id = GetNodeAttribute(child, "ID");
                    if (bb_id.empty()) {
                        fileInfo.errors.push_back("Blackboard element missing required 'ID' attribute");
                    } else {
                        fileInfo.blackboard_ids.push_back(bb_id);
 
                        // Check for duplicate blackboard IDs within this file
                        if (file_bb_ids.count(bb_id) > 0) {
                            fileInfo.warnings.push_back("Duplicate blackboard ID within file: " + bb_id);
                        }
                        file_bb_ids.insert(bb_id);
 
                        // Parse includes attribute
                        EmberCore::String includes = GetNodeAttribute(child, "includes");
                        if (!includes.empty()) {
                            // Validate format {ID1 ID2 ...}
                            if (includes.front() != '{' || includes.back() != '}') {
                                fileInfo.warnings.push_back(
                                    "Blackboard '" + bb_id +
                                    "' has malformed includes syntax (should be {ID1 ID2 ...})");
                            } else {
                                // Parse includes
                                String includes_content = includes.substr(1, includes.size() - 2);
                                std::istringstream iss(includes_content);
                                String token;
                                std::vector<String> bb_inc_list;
                                while (iss >> token) {
                                    if (!token.empty()) {
                                        bb_includes_set.insert(token);
                                        fileInfo.blackboard_includes.push_back(token);
                                        bb_inc_list.push_back(token);
                                    }
                                }
                                if (!bb_inc_list.empty()) {
                                    per_bb_includes[bb_id] = std::move(bb_inc_list);
                                }
                            }
                        }
 
                        // Validate entries
                        std::set<String> seen_keys;
                        for (xmlNodePtr entryNode = child->children; entryNode; entryNode = entryNode->next) {
                            if (entryNode->type != XML_ELEMENT_NODE)
                                continue;
                            if (GetNodeName(entryNode) != "Entry")
                                continue;
 
                            String key = GetNodeAttribute(entryNode, "key");
                            String type = GetNodeAttribute(entryNode, "type");
 
                            if (key.empty()) {
                                fileInfo.errors.push_back("Blackboard '" + bb_id +
                                                          "' has Entry missing required 'key' attribute");
                                continue;
                            }
                            if (type.empty()) {
                                fileInfo.errors.push_back("Blackboard '" + bb_id + "' entry '" + key +
                                                          "' missing required 'type' attribute");
                                continue;
                            }
 
                            // Check for duplicate keys
                            if (seen_keys.count(key) > 0) {
                                fileInfo.warnings.push_back("Blackboard '" + bb_id +
                                                            "' has duplicate entry key: " + key);
                            }
                            seen_keys.insert(key);
 
                            // Validate type (using existing validation list)
                            static const std::set<String> validTypes = {"bool",
                                                                        "int",
                                                                        "int8",
                                                                        "float",
                                                                        "string",
                                                                        "Currency",
                                                                        "uint8_t",
                                                                        "uint32_t",
                                                                        "size_t",
                                                                        "auto",
                                                                        "vec(int)",
                                                                        "vec(int8)",
                                                                        "vec(uint8_t)",
                                                                        "vec(uint32_t)",
                                                                        "vec(float)",
                                                                        "vec(string)",
                                                                        "vec(Currency)",
                                                                        "vec(vec(uint8_t))",
                                                                        "vec(vec(uint32_t))",
                                                                        "vec(pair(float))",
                                                                        "pair(float)",
                                                                        "pair(int)",
                                                                        "pair(string)",
                                                                        "map(string, string)",
                                                                        "map(string,string)",
                                                                        "map(string, int)",
                                                                        "map(string,int)",
                                                                        "set(string)",
                                                                        "set(int)",
                                                                        "set(uint32_t)",
                                                                        "set",
                                                                        "Results",
                                                                        "ReelFigs",
                                                                        "GameSounds"};
 
                            bool isValidType = validTypes.count(type) > 0;
                            bool isCustomType = !type.empty() && std::isupper(type[0]) &&
                                                type.find('(') == String::npos && type.find(')') == String::npos;
 
                            if (!isValidType && !isCustomType) {
                                fileInfo.warnings.push_back("Blackboard '" + bb_id + "' entry '" + key +
                                                            "' has unsupported type: " + type);
                            }
                        }
 
                        // Actually parse the blackboard
                        auto blackboard = ParseBlackboard(child);
                        if (blackboard) {
                            parsed_blackboards_[bb_id] = std::move(blackboard);
                            LOG_INFO("LibXMLParser", "Parsed blackboard '" + bb_id + "' from " + filepath);
                        }
                    }
                }
            }
        }
 
        // Store subtree refs in file info
        fileInfo.subtree_refs.assign(subtree_refs_set.begin(), subtree_refs_set.end());
 
        for (auto &kv : per_bb_includes) {
            result.blackboard_includes_map[kv.first] = std::move(kv.second);
        }
 
        // Check if file has neither trees nor blackboards
        if (!fileInfo.has_behavior_trees && !fileInfo.has_blackboards) {
            fileInfo.warnings.push_back("No BehaviorTree or Blackboard elements found in file");
        }
 
        // Add file info to result
        result.file_infos.push_back(fileInfo);
 
        xmlFreeDoc(doc);
    }
 
    // Select the main tree: among valid candidates, pick the one with the most subtree references
    // (the project's main execution tree typically orchestrates the most subtrees)
    {
        EmberCore::String best_candidate;
        size_t best_ref_count = 0;
 
        auto countRefs = [](Node *root) -> size_t {
            if (!root)
                return 0;
            std::set<EmberCore::String> refs;
            std::vector<Node *> stack = {root};
            while (!stack.empty()) {
                Node *n = stack.back();
                stack.pop_back();
                EmberCore::String ref = n->GetAttribute("__subtree_ref__", "");
                if (!ref.empty())
                    refs.insert(ref);
                for (size_t i = 0; i < n->GetChildCount(); ++i)
                    stack.push_back(n->GetChild(i));
            }
            return refs.size();
        };
 
        for (const auto &candidate : main_tree_candidates) {
            auto it = parsed_trees_.find(candidate);
            if (it == parsed_trees_.end() || !it->second || !it->second->HasRootNode())
                continue;
            size_t refCount = countRefs(it->second->GetRootNode());
            if (best_candidate.empty() || refCount > best_ref_count) {
                best_candidate = candidate;
                best_ref_count = refCount;
            }
        }
 
        if (!best_candidate.empty()) {
            result.main_tree_name = best_candidate;
        } else if (!main_tree_candidates.empty()) {
            result.main_tree_name = main_tree_candidates.front();
        }
    }
 
    // Note: Even if some files failed to parse, we continue with validation
    // for the files that did parse successfully. result.success will remain
    // false to indicate errors occurred, but we still do cross-file validation.
 
    // Copy any errors from failed parsing
    if (!result.success) {
        std::lock_guard<std::mutex> lock(errors_mutex_);
        for (const auto &err : errors_) {
            result.errors.push_back(err);
        }
    }
 
    // Second pass: Collect all SubTree references and identify unimplemented trees
    ReportProgress("Collecting SubTree references...", total_files + 1, total_files + 2);
 
    std::set<EmberCore::String> all_references;
    for (const auto &tree_pair : parsed_trees_) {
        if (tree_pair.second && tree_pair.second->HasRootNode()) {
            CollectSubTreeReferences(tree_pair.second->GetRootNode(), all_references);
        }
    }
 
    // Collect all implemented tree IDs
    std::set<String> implemented_tree_ids;
    for (const auto &tree_pair : parsed_trees_) {
        implemented_tree_ids.insert(tree_pair.first);
    }
 
    // Track references in implementation status and add per-file warnings
    for (const auto &ref : all_references) {
        if (tree_implementation_statuses_.find(ref) == tree_implementation_statuses_.end()) {
            // This is a referenced but not implemented tree
            TreeImplementationStatus status(ref);
            status.is_implemented = false;
            status.has_root_node = false;
            tree_implementation_statuses_[ref] = status;
            unimplemented_references_.insert(ref);
            result.unimplemented_references.push_back(ref);
            result.warnings.push_back("Tree '" + ref + "' is referenced but not implemented");
            LOG_WARNING("LibXMLParser", "Tree '" + ref + "' is referenced but not implemented");
 
            // Add warning to each file that references this unimplemented tree
            for (auto &fileInfo : result.file_infos) {
                for (const auto &subtree_ref : fileInfo.subtree_refs) {
                    if (subtree_ref == ref) {
                        fileInfo.warnings.push_back("References unimplemented tree: " + ref);
                        break;
                    }
                }
            }
        }
    }
 
    // Third pass: Expand all SubTree placeholders (with project mode)
    ReportProgress("Expanding SubTree references...", total_files + 2, total_files + 2);
    ExpandAllSubTreePlaceholdersForProject();
 
    // Cross-file validation: detect duplicates and unresolved references
    ReportProgress("Validating cross-file references...", total_files + 2, total_files + 2);
 
    // Collect all tree IDs and detect duplicates
    std::map<String, std::vector<String>> tree_id_to_files;
    for (const auto &fileInfo : result.file_infos) {
        for (const auto &tree_id : fileInfo.tree_ids) {
            tree_id_to_files[tree_id].push_back(fileInfo.filepath);
        }
    }
    for (const auto &pair : tree_id_to_files) {
        if (pair.second.size() > 1) {
            result.duplicate_tree_ids.push_back(pair.first);
            result.warnings.push_back("Duplicate tree ID found across files: " + pair.first);
        }
    }
 
    // Collect all blackboard IDs and detect duplicates
    std::map<String, std::vector<String>> bb_id_to_files;
    std::set<String> all_blackboard_ids;
    for (const auto &fileInfo : result.file_infos) {
        for (const auto &bb_id : fileInfo.blackboard_ids) {
            bb_id_to_files[bb_id].push_back(fileInfo.filepath);
            all_blackboard_ids.insert(bb_id);
        }
    }
    for (const auto &pair : bb_id_to_files) {
        if (pair.second.size() > 1) {
            result.duplicate_blackboard_ids.push_back(pair.first);
            result.warnings.push_back("Duplicate blackboard ID found across files: " + pair.first);
        }
    }
 
    // Detect unresolved blackboard includes
    std::set<String> unresolved_includes;
    for (const auto &fileInfo : result.file_infos) {
        for (const auto &include : fileInfo.blackboard_includes) {
            if (all_blackboard_ids.count(include) == 0) {
                unresolved_includes.insert(include);
            }
        }
    }
    result.unresolved_blackboard_includes.assign(unresolved_includes.begin(), unresolved_includes.end());
    for (const auto &include : unresolved_includes) {
        result.warnings.push_back("Unresolved blackboard include: " + include);
    }
 
    // Copy circular references detected during expansion
    result.circular_references.assign(circular_references_.begin(), circular_references_.end());
 
    // Copy results
    result.parsed_trees = parsed_trees_;
 
    // Convert unique_ptr blackboards to shared_ptr
    for (auto &pair : parsed_blackboards_) {
        if (pair.second) {
            // Move ownership from unique_ptr to shared_ptr
            result.parsed_blackboards[pair.first] = std::shared_ptr<Blackboard>(std::move(pair.second));
        }
    }
 
    result.tree_statuses = tree_implementation_statuses_;
 
    // Copy any additional errors
    {
        std::lock_guard<std::mutex> lock(errors_mutex_);
        for (const auto &err : errors_) {
            result.errors.push_back(err);
        }
    }
 
    result.success = result.errors.empty();
    project_parsing_mode_ = false;
 
    ReportProgress("Project parsing complete: " + std::to_string(result.GetImplementedTreeCount()) + " implemented, " +
                       std::to_string(result.unimplemented_references.size()) + " unimplemented",
                   total_files + 2, total_files + 2);
 
    return result;
}
 
void LibXMLBehaviorTreeParser::CollectSubTreeReferences(Node *node, std::set<EmberCore::String> &references) {
    if (!node)
        return;
 
    // Check if this is a SubTree placeholder
    EmberCore::String subtree_ref = node->GetAttribute("__subtree_ref__", "");
    if (!subtree_ref.empty()) {
        references.insert(subtree_ref);
 
        // Track which files reference this tree
        if (tree_implementation_statuses_.find(subtree_ref) != tree_implementation_statuses_.end()) {
            auto &status = tree_implementation_statuses_[subtree_ref];
            if (std::find(status.referenced_in_files.begin(), status.referenced_in_files.end(), current_file_path_) ==
                status.referenced_in_files.end()) {
                status.referenced_in_files.push_back(current_file_path_);
            }
        }
    }
 
    // Recursively check children
    for (size_t i = 0; i < node->GetChildCount(); ++i) {
        CollectSubTreeReferences(node->GetChild(i), references);
    }
}
 
void LibXMLBehaviorTreeParser::ExpandAllSubTreePlaceholdersForProject() {
    // Clear cache before expansion
    expanded_subtree_cache_.clear();
    expansion_stack_.clear();
    circular_references_.clear();
 
    for (auto &tree_pair : parsed_trees_) {
        auto &tree = tree_pair.second;
        if (tree && tree->HasRootNode()) {
            // Add the tree ID to the expansion stack before expanding
            expansion_stack_.insert(tree_pair.first);
            ExpandSubTreePlaceholderForProject(tree->GetRootNode());
            expansion_stack_.erase(tree_pair.first);
        }
    }
}
 
bool LibXMLBehaviorTreeParser::ExpandSubTreePlaceholderForProject(Node *node) {
    if (!node)
        return false;
 
    bool expanded_any = false;
 
    // Check if this node is a SubTree placeholder
    EmberCore::String subtree_ref = node->GetAttribute("__subtree_ref__", "");
    if (!subtree_ref.empty()) {
        // This is a SubTree placeholder node
 
        if (parsed_trees_.find(subtree_ref) != parsed_trees_.end()) {
            auto referenced_tree = parsed_trees_[subtree_ref];
            if (referenced_tree && referenced_tree->HasRootNode()) {
                Node *referenced_root = referenced_tree->GetRootNode();
 
                // Check for circular reference
                bool is_expanding = (expansion_stack_.find(subtree_ref) != expansion_stack_.end());
                bool already_expanded = (expanded_subtree_cache_.find(subtree_ref) != expanded_subtree_cache_.end());
 
                if (is_expanding) {
                    // Track the circular reference - build a message showing the cycle
                    String cycle_msg = "Circular reference: ";
                    bool first = true;
                    for (const auto &tree_in_stack : expansion_stack_) {
                        if (!first)
                            cycle_msg += " -> ";
                        cycle_msg += tree_in_stack;
                        first = false;
                    }
                    cycle_msg += " -> " + subtree_ref;
 
                    circular_references_.insert(cycle_msg);
                    AddError(ParseError::INVALID_TREE_STRUCTURE, "Circular SubTree reference detected: " + cycle_msg);
                    LOG_ERROR("LibXMLParser", "Circular SubTree reference detected: " + cycle_msg);
                    return false;
                }
 
                if (!already_expanded) {
                    expansion_stack_.insert(subtree_ref);
                    ExpandSubTreePlaceholderForProject(referenced_root);
                    expanded_subtree_cache_.insert(subtree_ref);
                    expansion_stack_.erase(subtree_ref);
                }
 
                // Copy properties from referenced tree
                node->SetName(referenced_root->GetName());
                node->SetType(referenced_root->GetType());
                node->RemoveAttribute("__is_placeholder__");
 
                for (const auto &attr_pair : referenced_root->GetAllAttributes()) {
                    node->SetAttribute(attr_pair.first, attr_pair.second);
                }
 
                for (size_t i = 0; i < referenced_root->GetChildCount(); ++i) {
                    Node *child = referenced_root->GetChild(i);
                    if (child) {
                        node->AddChild(child->DeepCopy());
                    }
                }
 
                expanded_any = true;
            } else {
                // Referenced tree exists but is empty - mark as unimplemented
                node->RemoveAttribute("__is_placeholder__");
                node->SetAttribute("__unimplemented__", "true");
                node->SetName("SubTree: " + subtree_ref + " [EMPTY]");
                LOG_WARNING("LibXMLParser", "SubTree '" + subtree_ref + "' is empty (no root node)");
            }
        } else {
            // Tree not found - in project mode, don't error, just mark as unimplemented
            // Remove the placeholder marker and mark as unimplemented instead
            node->RemoveAttribute("__is_placeholder__");
            node->SetAttribute("__unimplemented__", "true");
            node->SetName("SubTree: " + subtree_ref + " [NOT IMPLEMENTED]");
            LOG_WARNING("LibXMLParser", "SubTree '" + subtree_ref + "' not found (unimplemented reference)");
        }
    } else {
        // Not a subtree placeholder, recursively expand children
        for (size_t i = 0; i < node->GetChildCount(); ++i) {
            if (ExpandSubTreePlaceholderForProject(node->GetChild(i))) {
                expanded_any = true;
            }
        }
    }
 
    return expanded_any;
}
 
bool LibXMLBehaviorTreeParser::IsTreeImplemented(const EmberCore::String &tree_id) const {
    auto it = tree_implementation_statuses_.find(tree_id);
    if (it != tree_implementation_statuses_.end()) {
        return it->second.is_implemented;
    }
    return false;
}
 
std::vector<EmberCore::String> LibXMLBehaviorTreeParser::GetUnimplementedReferences() const {
    std::vector<EmberCore::String> result;
    for (const auto &ref : unimplemented_references_) {
        result.push_back(ref);
    }
    return result;
}
 
// ============================================================================
// Core Parsing Methods
// ============================================================================
 
bool LibXMLBehaviorTreeParser::ParseXMLDocument(xmlDocPtr doc, const EmberCore::String &source_path) {
    xmlNodePtr root = xmlDocGetRootElement(doc);
    if (!root) {
        AddError(ParseError::MISSING_ROOT_ELEMENT, "XML document has no root element");
        return false;
    }
 
    // Use configured root element name
    const auto &doc_config = config_.GetDocumentConfig();
    EmberCore::String root_name = GetNodeName(root);
 
    if (doc_config.case_sensitive) {
        if (root_name != doc_config.root_element) {
            AddError(ParseError::MISSING_ROOT_ELEMENT, EmberCore::String("Expected '") + doc_config.root_element +
                                                           "' element, found '" + root_name + "'");
            return false;
        }
    } else {
        // Case-insensitive comparison
        auto to_lower = [](String str) {
            std::transform(str.begin(), str.end(), str.begin(), ::tolower);
            return str;
        };
        if (to_lower(root_name) != to_lower(doc_config.root_element)) {
            AddError(ParseError::MISSING_ROOT_ELEMENT, EmberCore::String("Expected '") + doc_config.root_element +
                                                           "' element, found '" + root_name + "'");
            return false;
        }
    }
 
    // Get main tree to execute using configured attribute name
    main_tree_name_ = GetNodeAttribute(root, doc_config.main_tree_attribute);
    if (!main_tree_name_.empty()) {
        ReportProgress(EmberCore::String("Main tree: ") + main_tree_name_, 2, 5);
    }
 
    // Report progress: Parsing structure
    ReportProgress("Parsing tree structure...", 2, 5);
 
    // Get configured element names
    const auto &tree_config = config_.GetTreeConfig();
    const auto &blackboard_config = config_.GetBlackboardConfig();
 
    // Count total elements first for better progress reporting
    int totalElements = 0;
    for (xmlNodePtr child = root->children; child; child = child->next) {
        if (child->type == XML_ELEMENT_NODE) {
            EmberCore::String name = GetNodeName(child);
            if (name == tree_config.behavior_tree_element || name == blackboard_config.blackboard_element) {
                totalElements++;
            }
        }
    }
    ReportProgress("Found " + std::to_string(totalElements) + " element(s) to parse", 2, 5);
 
    // Parse all BehaviorTree nodes
    int treeCount = 0;
    int blackboardCount = 0;
    for (xmlNodePtr child = root->children; child; child = child->next) {
        if (child->type == XML_ELEMENT_NODE) {
            EmberCore::String name = GetNodeName(child);
            if (name == tree_config.behavior_tree_element) {
                auto tree = ParseBehaviorTree(child);
                if (tree) {
                    EmberCore::String tree_id = GetNodeAttribute(child, tree_config.tree_id_attribute);
                    if (!tree_id.empty()) {
                        parsed_trees_[tree_id] = tree;
                        treeCount++;
                        // Report progress for each tree parsed
                        EmberCore::String progressMsg = "Parsed tree " + std::to_string(treeCount) + "/" +
                                                        std::to_string(totalElements) + ": " + tree_id;
                        ReportProgress(progressMsg, 2, 5);
 
                        // Log node count
                        if (tree->HasRootNode()) {
                            size_t nodeCount = tree->GetNodeCount();
                            ReportProgress("   " + std::to_string(nodeCount) + " node(s) in tree", 2, 5);
                        }
                    } else {
                        AddError(ParseError::MISSING_ATTRIBUTE,
                                 tree_config.behavior_tree_element + " missing " + tree_config.tree_id_attribute +
                                     " attribute",
                                 child);
                        ReportProgress("   WARNING: Tree missing ID attribute", 2, 5);
                    }
                }
            } else if (name == blackboard_config.blackboard_element) {
                auto blackboard = ParseBlackboard(child);
                if (blackboard) {
                    EmberCore::String blackboard_id = blackboard->GetId();
                    parsed_blackboards_[blackboard_id] = std::move(blackboard);
                    blackboardCount++;
                    ReportProgress(EmberCore::String("Parsed blackboard: ") + blackboard_id, 2, 5);
                }
            } else if (!doc_config.allow_unknown_elements) {
                LOG_WARNING("LibXMLParser", "Unknown element '" + name + "' in root (ignored)");
            }
        }
    }
 
    LOG_INFO("LibXMLParser", "Parsed " + std::to_string(parsed_trees_.size()) + " trees and " +
                                 std::to_string(parsed_blackboards_.size()) + " blackboards");
 
    ReportProgress("Parsed " + std::to_string(treeCount) + " tree(s) and " + std::to_string(blackboardCount) +
                       " blackboard(s)",
                   2, 5);
 
    // Report progress: Expanding subtrees
    ReportProgress("Expanding subtrees...", 3, 5);
 
    // Expand all SubTree placeholders now that all trees have been parsed
    ExpandAllSubTreePlaceholders();
    ReportProgress("Subtree expansion complete", 3, 5);
 
    // Assign blackboards to all parsed trees after parsing is complete
    for (const auto &blackboard_pair : parsed_blackboards_) {
        const auto &blackboard = blackboard_pair.second;
        for (auto &tree_pair : parsed_trees_) {
            tree_pair.second->AddBlackboard(blackboard->Clone());
        }
    }
 
    // Check for errors
    if (HasErrors()) {
        LOG_ERROR("LibXMLParser", "Parsing failed with " + std::to_string(errors_.size()) + " error(s):");
        for (size_t i = 0; i < errors_.size(); ++i) {
            LOG_ERROR("LibXMLParser", "  " + std::to_string(i + 1) + ": " + errors_[i].message);
        }
        return false;
    }
 
    LOG_INFO("LibXMLParser", "Parsing completed successfully");
    return true;
}
 
// Helper methods for libxml2 integration
EmberCore::String LibXMLBehaviorTreeParser::GetNodeName(xmlNodePtr node) {
    if (!node || !node->name)
        return "";
    return std::string(reinterpret_cast<const char *>(node->name));
}
 
EmberCore::String LibXMLBehaviorTreeParser::GetNodeAttribute(xmlNodePtr node, const EmberCore::String &attr_name) {
    if (!node)
        return "";
 
    xmlChar *value = xmlGetProp(node, reinterpret_cast<const xmlChar *>(attr_name.c_str()));
    if (!value)
        return "";
 
    EmberCore::String result = std::string(reinterpret_cast<const char *>(value));
    xmlFree(value);
    return result;
}
 
// Thread-safe error handling
bool LibXMLBehaviorTreeParser::HasErrors() const {
    std::lock_guard<std::mutex> lock(errors_mutex_);
    return !errors_.empty();
}
 
const std::vector<LibXMLBehaviorTreeParser::ParseError> &LibXMLBehaviorTreeParser::GetErrors() const {
    std::lock_guard<std::mutex> lock(errors_mutex_);
    return errors_;
}
 
void LibXMLBehaviorTreeParser::ClearErrors() {
    std::lock_guard<std::mutex> lock(errors_mutex_);
    errors_.clear();
}
 
void LibXMLBehaviorTreeParser::AddError(ParseError::Type type, const EmberCore::String &message, xmlNodePtr node,
                                        const EmberCore::String &context) {
    std::lock_guard<std::mutex> lock(errors_mutex_);
    ParseError error(type, message, current_file_path_);
 
    if (node) {
        error.line_number = node->line;
        error.column_number = 0; // libxml2 doesn't provide column info in older versions
        error.node_path = GetNodePath(node);
    }
 
    if (!context.empty()) {
        error.context = context;
        error.message += " (Context: " + context + ")";
    }
 
    errors_.push_back(error);
    LOG_ERROR("LibXMLParser", "Parse error: " + message + "");
}
 
EmberCore::String LibXMLBehaviorTreeParser::GetNodePath(xmlNodePtr node) {
    if (!node)
        return "";
 
    EmberCore::String path;
    xmlNodePtr current = node;
 
    while (current && current->parent) {
        EmberCore::String node_name = GetNodeName(current);
        EmberCore::String id = GetNodeAttribute(current, "ID");
        EmberCore::String name = GetNodeAttribute(current, "name");
 
        if (!id.empty()) {
            node_name += "[ID=" + id + "]";
        } else if (!name.empty()) {
            node_name += "[name=" + name + "]";
        }
 
        if (path.empty()) {
            path = node_name;
        } else {
            path = node_name + "/" + path;
        }
 
        current = current->parent;
    }
 
    return path;
}
 
bool LibXMLBehaviorTreeParser::ReportProgress(const EmberCore::String &message, int current, int total) {
    if (progress_callback_) {
        return progress_callback_->OnProgress(message, current, total);
    }
    // If no callback, always continue
    return true;
}
 
std::shared_ptr<BehaviorTree> LibXMLBehaviorTreeParser::ParseBehaviorTree(xmlNodePtr tree_node) {
    const auto &tree_config = config_.GetTreeConfig();
 
    if (!ValidateRequiredAttribute(tree_node, tree_config.tree_id_attribute)) {
        return nullptr;
    }
 
    EmberCore::String tree_id = GetNodeAttribute(tree_node, tree_config.tree_id_attribute);
    auto behavior_tree = std::make_shared<BehaviorTree>();
 
    // Set the tree name from the ID attribute (important for serialization round-trips)
    behavior_tree->SetName(tree_id);
 
    // Capture document-level comments
    CaptureComments(tree_node, behavior_tree.get());
 
    // Parse the root node of this behavior tree
    xmlNodePtr child = tree_node->children;
    std::unique_ptr<Node> root_node = nullptr;
 
    while (child) {
        if (child->type == XML_ELEMENT_NODE) {
            auto node = ParseNode(child);
            if (node) {
                if (!root_node) {
                    root_node = std::move(node);
                } else {
                    AddError(ParseError::INVALID_VALUE,
                             tree_config.behavior_tree_element + " can only have one root node", child);
                    return nullptr;
                }
            }
        }
        child = child->next;
    }
 
    if (!root_node && tree_config.require_root_node) {
        AddError(ParseError::MISSING_ROOT_ELEMENT,
                 EmberCore::String(tree_config.behavior_tree_element) + " '" + tree_id + "' has no root node");
        return nullptr;
    }
 
    if (root_node) {
        // Create a visual wrapper node for the BehaviorTree itself
        auto wrapper_node = std::make_unique<Node>(tree_id, Node::Type::BehaviorTree);
 
        // Copy any BehaviorTree-level attributes to the wrapper node
        xmlAttrPtr attr = tree_node->properties;
        while (attr) {
            EmberCore::String attr_name = reinterpret_cast<const char *>(attr->name);
            EmberCore::String attr_value = GetNodeAttribute(tree_node, attr_name);
            wrapper_node->SetAttribute(attr_name, attr_value);
            attr = attr->next; // CRITICAL: Advance to next attribute
        }
 
        // Add the actual root node (Sequence, Selector, etc.) as a child
        wrapper_node->AddChild(std::move(root_node));
 
        // Set the wrapper as the BehaviorTree's root
        behavior_tree->SetRootNode(std::move(wrapper_node));
    }
    return behavior_tree;
}
 
std::unique_ptr<Node> LibXMLBehaviorTreeParser::ParseNode(xmlNodePtr xml_node) {
    if (!xml_node || xml_node->type != XML_ELEMENT_NODE) {
        return nullptr;
    }
 
    const auto &node_config = config_.GetNodeConfig();
    const auto &tree_config = config_.GetTreeConfig();
 
    EmberCore::String element_name = GetNodeName(xml_node);
    std::unique_ptr<Node> node = nullptr;
 
    // Element name indicates the category (Control, Action, Decorator, Condition)
    // The specific behavior is specified in the ID attribute
    if (element_name == node_config.control_element) {
        node = ParseControlNode(xml_node);
    } else if (element_name == node_config.action_element) {
        node = ParseActionNode(xml_node);
    } else if (element_name == node_config.condition_element) {
        node = ParseConditionNode(xml_node);
    } else if (element_name == node_config.decorator_element) {
        node = ParseDecoratorNode(xml_node);
    } else if (element_name == tree_config.subtree_element) {
        node = ParseSubTreeNode(xml_node);
    } else if (element_name == node_config.generic_node_element) {
        // Generic node - try to infer type
        node = ParseActionNode(xml_node); // Default to action
    } else {
        // Unknown node type - handle according to config
        const auto &classification_config = config_.GetClassificationConfig();
        switch (classification_config.unknown_behavior) {
        case ParserConfig::UnknownTypeBehavior::ERROR:
            AddError(ParseError::UNKNOWN_NODE_TYPE, "Unknown node element: " + element_name, xml_node);
            return nullptr;
        case ParserConfig::UnknownTypeBehavior::WARNING:
            LOG_WARNING("LibXMLParser", "Unknown node element: " + element_name + " (skipped)");
            return nullptr;
        case ParserConfig::UnknownTypeBehavior::GENERIC_NODE:
            LOG_WARNING("LibXMLParser", "Unknown node element: " + element_name + " (creating generic action node)");
            node = ParseActionNode(xml_node);
            break;
        }
    }
 
    if (node) {
        // For SubTree nodes, attributes and children are handled differently
        // (they are copied from the referenced tree)
        if (element_name != tree_config.subtree_element) {
            SetNodeAttributes(node.get(), xml_node);
            ParseChildNodes(node.get(), xml_node);
        }
    }
 
    return node;
}
 
std::unique_ptr<Node> LibXMLBehaviorTreeParser::ParseControlNode(xmlNodePtr xml_node) {
    const auto &node_config = config_.GetNodeConfig();
 
    if (!ValidateRequiredAttribute(xml_node, node_config.node_id_attribute)) {
        return nullptr;
    }
 
    EmberCore::String control_type = GetNodeAttribute(xml_node, node_config.node_id_attribute);
 
    // Validate this is actually a control type
    if (!config_.IsControlType(control_type)) {
        const auto &classification_config = config_.GetClassificationConfig();
        if (classification_config.unknown_behavior == ParserConfig::UnknownTypeBehavior::ERROR) {
            AddError(ParseError::UNKNOWN_NODE_TYPE, "Unknown control node type: " + control_type, xml_node);
            return nullptr;
        }
        LOG_WARNING("LibXMLParser", "Unknown control type '" + control_type + "', creating generic control node");
    }
 
    auto node = std::make_unique<Node>(control_type, Node::Type::Control);
    LOG_TRACE("LibXMLParser", "Created control node: " + control_type);
 
    return node;
}
 
std::unique_ptr<Node> LibXMLBehaviorTreeParser::ParseActionNode(xmlNodePtr xml_node) {
    const auto &node_config = config_.GetNodeConfig();
 
    if (!ValidateRequiredAttribute(xml_node, node_config.node_id_attribute)) {
        return nullptr;
    }
 
    EmberCore::String action_type = GetNodeAttribute(xml_node, node_config.node_id_attribute);
 
    // Check if it's a known action type (if list is defined)
    if (!config_.IsActionType(action_type)) {
        const auto &classification_config = config_.GetClassificationConfig();
        if (!classification_config.action_types.empty() &&
            classification_config.unknown_behavior == ParserConfig::UnknownTypeBehavior::ERROR) {
            AddError(ParseError::UNKNOWN_NODE_TYPE, "Unknown action type: " + action_type, xml_node);
            return nullptr;
        }
        LOG_TRACE("LibXMLParser", "Unknown action type '" + action_type + "', creating generic Action node");
    }
 
    auto node = std::make_unique<Node>(action_type, Node::Type::Action);
    LOG_TRACE("LibXMLParser", "Created action node: " + action_type);
 
    return node;
}
 
std::unique_ptr<Node> LibXMLBehaviorTreeParser::ParseConditionNode(xmlNodePtr xml_node) {
    const auto &node_config = config_.GetNodeConfig();
 
    if (!ValidateRequiredAttribute(xml_node, node_config.node_id_attribute)) {
        return nullptr;
    }
 
    EmberCore::String condition_type = GetNodeAttribute(xml_node, node_config.node_id_attribute);
 
    // Check if it's a known condition type (if list is defined)
    if (!config_.IsConditionType(condition_type)) {
        const auto &classification_config = config_.GetClassificationConfig();
        if (!classification_config.condition_types.empty() &&
            classification_config.unknown_behavior == ParserConfig::UnknownTypeBehavior::ERROR) {
            AddError(ParseError::UNKNOWN_NODE_TYPE, "Unknown condition type: " + condition_type, xml_node);
            return nullptr;
        }
        LOG_TRACE("LibXMLParser", "Unknown condition type '" + condition_type + "', creating generic Condition node");
    }
 
    auto node = std::make_unique<Node>(condition_type, Node::Type::Condition);
    LOG_TRACE("LibXMLParser", "Created condition node: " + condition_type);
 
    return node;
}
 
std::unique_ptr<Node> LibXMLBehaviorTreeParser::ParseDecoratorNode(xmlNodePtr xml_node) {
    const auto &node_config = config_.GetNodeConfig();
 
    if (!ValidateRequiredAttribute(xml_node, node_config.node_id_attribute)) {
        return nullptr;
    }
 
    EmberCore::String decorator_type = GetNodeAttribute(xml_node, node_config.node_id_attribute);
 
    // Validate this is actually a decorator type
    if (!config_.IsDecoratorType(decorator_type)) {
        const auto &classification_config = config_.GetClassificationConfig();
        if (classification_config.unknown_behavior == ParserConfig::UnknownTypeBehavior::ERROR) {
            AddError(ParseError::UNKNOWN_NODE_TYPE, "Unknown decorator type: " + decorator_type, xml_node);
            return nullptr;
        }
        LOG_WARNING("LibXMLParser", "Unknown decorator type '" + decorator_type + "', creating generic decorator node");
    }
 
    auto node = std::make_unique<Node>(decorator_type, Node::Type::Decorator);
    LOG_TRACE("LibXMLParser", "Created decorator node: " + decorator_type);
 
    return node;
}
 
std::unique_ptr<Node> LibXMLBehaviorTreeParser::ParseSubTreeNode(xmlNodePtr xml_node) {
    const auto &tree_config = config_.GetTreeConfig();
 
    if (!ValidateRequiredAttribute(xml_node, tree_config.subtree_reference_attribute)) {
        return nullptr;
    }
 
    EmberCore::String subtree_id = GetNodeAttribute(xml_node, tree_config.subtree_reference_attribute);
 
    // Create a placeholder node that will be expanded later (two-pass system)
    // This allows forward references where SubTree A references Tree B that appears later in XML
    // Use BehaviorTree type for SubTree placeholders (they reference other behavior trees)
    auto placeholder = std::make_unique<Node>("SubTree[" + subtree_id + "]", Node::Type::BehaviorTree);
    placeholder->SetAttribute("__subtree_ref__", subtree_id);
    placeholder->SetAttribute("__is_placeholder__", "true");
 
    LOG_TRACE("LibXMLParser",
              "Created SubTree placeholder for '" + subtree_id + "' (will expand after all trees parsed)");
 
    // TODO: Handle SubTree parameters and variable substitution
    // For now, we just store the reference and expand later
 
    return placeholder;
}
 
std::unique_ptr<Blackboard> LibXMLBehaviorTreeParser::ParseBlackboard(xmlNodePtr blackboard_node) {
    const auto &blackboard_config = config_.GetBlackboardConfig();
 
    if (!ValidateRequiredAttribute(blackboard_node, blackboard_config.blackboard_id_attribute)) {
        return nullptr;
    }
 
    EmberCore::String blackboard_id = GetNodeAttribute(blackboard_node, blackboard_config.blackboard_id_attribute);
    auto blackboard = std::make_unique<Blackboard>(blackboard_id);
 
    // Check for parent attribute (inheritance)
    EmberCore::String parent_id = GetNodeAttribute(blackboard_node, blackboard_config.parent_attribute);
    if (!parent_id.empty()) {
        blackboard->SetParentId(parent_id);
        LOG_TRACE("LibXMLParser", "Blackboard '" + blackboard_id + "' inherits from '" + parent_id + "'");
    }
 
    // Parse all Entry children
    xmlNodePtr child = blackboard_node->children;
    while (child) {
        if (child->type == XML_ELEMENT_NODE && GetNodeName(child) == blackboard_config.entry_element) {
            auto entry = ParseBlackboardEntry(child);
            if (entry) {
                blackboard->AddEntry(std::move(entry));
            }
        }
        child = child->next;
    }
 
    LOG_TRACE("LibXMLParser", "Parsed blackboard '" + blackboard_id + "' with " +
                                  std::to_string(blackboard->GetEntryCount()) + " entries");
 
    return blackboard;
}
 
std::unique_ptr<BlackboardEntry> LibXMLBehaviorTreeParser::ParseBlackboardEntry(xmlNodePtr entry_node) {
    const auto &blackboard_config = config_.GetBlackboardConfig();
 
    if (!ValidateRequiredAttribute(entry_node, blackboard_config.entry_key_attribute) ||
        !ValidateRequiredAttribute(entry_node, blackboard_config.entry_type_attribute)) {
        return nullptr;
    }
 
    EmberCore::String key = GetNodeAttribute(entry_node, blackboard_config.entry_key_attribute);
    EmberCore::String type_str = GetNodeAttribute(entry_node, blackboard_config.entry_type_attribute);
    EmberCore::String value = GetNodeAttribute(entry_node, blackboard_config.entry_value_attribute);
 
    BlackboardEntry::DataType data_type = BlackboardEntry::ParseDataType(type_str);
    if (data_type == BlackboardEntry::DataType::UNKNOWN) {
        if (!blackboard_config.allow_undefined_keys) {
            AddError(ParseError::INVALID_VALUE, "Unknown blackboard entry type: " + type_str, entry_node);
            return nullptr;
        }
        LOG_WARNING("LibXMLParser", "Unknown blackboard type '" + type_str + "', using AUTO");
        data_type = BlackboardEntry::DataType::AUTO;
    }
 
    auto entry = std::make_unique<BlackboardEntry>(key, data_type, value);
 
    if (!entry->IsValidValue()) {
        // For empty values on collection/complex types, just warn and continue
        // This is common for types like 'set', 'auto', etc. that may be initialized later
        LOG_WARNING("LibXMLParser", "Empty or invalid value '" + value + "' for type '" + type_str + "' (key: " + key +
                                        ") - will use default");
        // Don't fail parsing for this - it's not critical
    }
 
    LOG_TRACE("LibXMLParser",
              "Parsed blackboard entry: " + key + " (" + type_str + ") = " + (value.empty() ? "<empty>" : value));
 
    return entry;
}
 
void LibXMLBehaviorTreeParser::SetNodeAttributes(Node *node, xmlNodePtr xml_node) {
    const auto &node_config = config_.GetNodeConfig();
 
    // Set basic attributes using configured attribute names
    EmberCore::String name = GetNodeAttribute(xml_node, node_config.node_name_attribute);
    if (!name.empty()) {
        node->SetName(name);
    }
 
    EmberCore::String id = GetNodeAttribute(xml_node, node_config.node_id_attribute);
    if (!id.empty() && name.empty()) {
        node->SetName(id); // Use ID as name if no explicit name specified
    }
 
    // Explicitly store the ID attribute so it can be serialized back
    if (!id.empty()) {
        node->SetAttribute(node_config.node_id_attribute, id);
    }
 
    // Parse and store all custom attributes (if allowed)
    if (node_config.allow_custom_attributes) {
        xmlAttrPtr attr = xml_node->properties;
        while (attr) {
            EmberCore::String attr_name = std::string(reinterpret_cast<const char *>(attr->name));
            EmberCore::String attr_value = std::string(reinterpret_cast<const char *>(attr->children->content));
 
            // Store all attributes except the name attribute (already handled above)
            // ID attribute is handled explicitly above but we allow it to be stored again to avoid issues
            if (attr_name != node_config.node_name_attribute) {
                node->SetAttribute(attr_name, attr_value);
                LOG_TRACE("LibXMLParser", "Stored node attribute: " + attr_name + " = " + attr_value);
            }
 
            attr = attr->next;
        }
    }
}
 
void LibXMLBehaviorTreeParser::ParseChildNodes(Node *parent, xmlNodePtr xml_parent) {
    xmlNodePtr child = xml_parent->children;
    size_t children_added = 0;
 
    while (child) {
        if (child->type == XML_ELEMENT_NODE) {
            auto child_node = ParseNode(child);
            if (child_node) {
                // Now we have unique_ptr, so we can move it directly
                parent->AddChild(std::move(child_node));
                children_added++;
                LOG_TRACE("LibXMLParser", "Added child node to " + parent->GetName());
            } else {
                LOG_TRACE("LibXMLParser", "Skipped child node for " + parent->GetName());
            }
        }
        child = child->next;
    }
 
    // Log if a parent ended up with no children (this might indicate SubTree skipping)
    if (children_added == 0 && xml_parent->children) {
        LOG_WARNING("LibXMLParser",
                    "Node '" + parent->GetName() +
                        "' ended up with no children after parsing (likely due to skipped SubTree nodes)");
    }
}
 
void LibXMLBehaviorTreeParser::ExpandAllSubTreePlaceholders() {
    // Clear cache before expansion
    expanded_subtree_cache_.clear();
    expansion_stack_.clear(); // Clear the stack tracking for circular reference detection
 
    for (auto &tree_pair : parsed_trees_) {
        auto &tree = tree_pair.second;
        if (tree && tree->HasRootNode()) {
            ExpandSubTreePlaceholder(tree->GetRootNode());
        }
    }
}
 
bool LibXMLBehaviorTreeParser::ExpandSubTreePlaceholder(Node *node) {
    if (!node)
        return false;
 
    bool expanded_any = false;
 
    // Check if this node is a SubTree placeholder
    EmberCore::String subtree_ref = node->GetAttribute("__subtree_ref__", "");
    if (!subtree_ref.empty()) {
        // This is a SubTree placeholder node - expand it
 
        if (parsed_trees_.find(subtree_ref) != parsed_trees_.end()) {
            auto referenced_tree = parsed_trees_[subtree_ref];
            if (referenced_tree && referenced_tree->HasRootNode()) {
                Node *referenced_root = referenced_tree->GetRootNode();
 
                // Check if this subtree is currently being expanded (circular reference)
                // OR if it has already been fully expanded (cache hit)
                bool is_expanding = (expansion_stack_.find(subtree_ref) != expansion_stack_.end());
                bool already_expanded = (expanded_subtree_cache_.find(subtree_ref) != expanded_subtree_cache_.end());
 
                if (is_expanding) {
                    // We're in a circular reference - abort
                    AddError(ParseError::INVALID_TREE_STRUCTURE, "Circular SubTree reference detected: " + subtree_ref);
                    LOG_ERROR("LibXMLParser", "Circular SubTree reference detected: " + subtree_ref);
                    return false;
                }
 
                if (!already_expanded) {
                    // First time expanding this subtree - mark as being expanded
                    expansion_stack_.insert(subtree_ref);
 
                    // Recursively expand the referenced tree's root and its children
                    ExpandSubTreePlaceholder(referenced_root);
 
                    // Mark as fully expanded in cache
                    expanded_subtree_cache_.insert(subtree_ref);
 
                    // Remove from expansion stack - this subtree is now safe to reference
                    expansion_stack_.erase(subtree_ref);
                }
 
                // Copy properties and children from the (now fully expanded) referenced_root
                node->SetName(referenced_root->GetName());
                node->SetType(referenced_root->GetType());
                node->RemoveAttribute("__is_placeholder__");
 
                // Copy attributes from referenced tree
                for (const auto &attr_pair : referenced_root->GetAllAttributes()) {
                    node->SetAttribute(attr_pair.first, attr_pair.second);
                }
 
                // Deep copy children (which are already fully expanded)
                for (size_t i = 0; i < referenced_root->GetChildCount(); ++i) {
                    Node *child = referenced_root->GetChild(i);
                    if (child) {
                        node->AddChild(child->DeepCopy());
                    }
                }
 
                // Since we deep copied from an already-expanded tree,
                // we DON'T need to expand the copied children again
 
                expanded_any = true;
            } else {
                // Referenced tree exists but is empty - mark as unimplemented
                node->RemoveAttribute("__is_placeholder__");
                node->SetAttribute("__unimplemented__", "true");
                node->SetName("SubTree: " + subtree_ref + " [EMPTY]");
                LOG_WARNING("LibXMLParser", "SubTree '" + subtree_ref + "' is empty (no root node)");
            }
        } else {
            // SubTree not found - mark as unimplemented instead of leaving as placeholder
            // This allows the tree to be used even with missing subtree references
            node->RemoveAttribute("__is_placeholder__");
            node->SetAttribute("__unimplemented__", "true");
            node->SetName("SubTree: " + subtree_ref + " [NOT IMPLEMENTED]");
            LOG_WARNING("LibXMLParser", "SubTree '" + subtree_ref + "' not found (unimplemented reference)");
        }
    } else {
        // Not a subtree placeholder, just recursively expand children
        for (size_t i = 0; i < node->GetChildCount(); ++i) {
            if (ExpandSubTreePlaceholder(node->GetChild(i))) {
                expanded_any = true;
            }
        }
    }
 
    return expanded_any;
}
 
bool LibXMLBehaviorTreeParser::ValidateRequiredAttribute(xmlNodePtr node, const EmberCore::String &attr_name) {
    if (!node) {
        AddError(ParseError::MISSING_ATTRIBUTE, "Node is null when validating attribute '" + attr_name + "'");
        return false;
    }
 
    EmberCore::String value = GetNodeAttribute(node, attr_name);
    if (value.empty()) {
        AddError(ParseError::MISSING_ATTRIBUTE, "Required attribute '" + attr_name + "' is missing", node);
        return false;
    }
 
    return true;
}
 
void LibXMLBehaviorTreeParser::CaptureComments(xmlNodePtr parent, BehaviorTree *tree, Node *node) {
    if (!parent || !tree) {
        return;
    }
 
    auto &xml_metadata = tree->GetXMLMetadata();
 
    // Iterate through all children to find comments
    for (xmlNodePtr child = parent->children; child; child = child->next) {
        if (child->type == XML_COMMENT_NODE) {
            // Extract comment text
            xmlChar *content = xmlNodeGetContent(child);
            if (content) {
                EmberCore::String comment_text = reinterpret_cast<const char *>(content);
                xmlFree(content);
 
                // Determine if this comment is before or after a node
                bool before_node = true;
                xmlNodePtr next_element = child->next;
                while (next_element && next_element->type != XML_ELEMENT_NODE) {
                    next_element = next_element->next;
                }
 
                if (!next_element) {
                    before_node = false; // Comment after last element
                }
 
                if (node) {
                    // Associate comment with specific node
                    XMLMetadata::Comment comment;
                    comment.text = comment_text;
                    comment.before_node = before_node;
                    xml_metadata.node_comments[node->GetId()].push_back(comment);
                } else {
                    // Document-level comment
                    if (before_node) {
                        xml_metadata.header_comments.push_back(comment_text);
                    } else {
                        xml_metadata.footer_comments.push_back(comment_text);
                    }
                }
            }
        }
    }
}
 
} // namespace EmberCore