Feature/v0.0.4 phase3 node queries

[dev-parkins]

Phase 3: Node Query Functions

Summary

Implements all 4 node query functions for FerrisScript, enabling scene tree navigation and node access. This completes Phase 3 of v0.0.4, adding essential capabilities for game development with Godot.

Status: ✅ Complete and Ready for Review
Branch: feature/v0.0.4-phase3-node-queries
Implementation Time: ~6 hours (under 2-3 day estimate)
Test Coverage: 416 tests passing (396 existing + 17 new + 3 other)

---

What's New

Four Node Query Built-ins

1. get_node(path: String) -> Node

Get a node by path (absolute or relative):

let player = get_node("Player");
let ui = get_node("/root/Main/UI");
let sibling = get_node("../OtherNode");

Error Codes: E601-E604 (wrong args, empty path, not found, no callback)

2. get_parent() -> Node

Get the parent of the current node:

let parent = get_parent();
let grandparent = get_parent().get_parent();

Error Codes: E605-E606 (wrong args, no parent)

3. has_node(path: String) -> bool

Check if a node exists before accessing:

if has_node("Player") {
    let player = get_node("Player");
}

Error Codes: E607-E609 (wrong args, empty path, no callback)
Note: Never errors on missing node, always returns bool

4. find_child(name: String) -> Node

Recursively search for a child by name:

let health_bar = find_child("HealthBar");
let weapon = find_child("CurrentWeapon");

Error Codes: E610-E613 (wrong args, empty name, not found, no callback)

---

Implementation Details

Architecture

Pattern: Special-cased built-ins with callbacks (consistent with emit_signal from Phase 1)

FerrisScript Code
    ↓
Runtime (call_builtin)
    ↓
Callback mechanism
    ↓
Thread-local storage (CURRENT_NODE_INSTANCE_ID)
    ↓
Godot Node API (try_get_node_as, get_parent, has_node, find_child)

New Types and Infrastructure

Value::Node variant (runtime/src/lib.rs:78):

pub enum Value {
    // ... existing variants
    Node(NodeHandle),
}

NodeHandle struct (runtime/src/lib.rs:127-169):

pub struct NodeHandle {
    pub(crate) node_id: String,
}

NodeQueryType enum (runtime/src/lib.rs:204-216):

pub enum NodeQueryType {
    GetNode,
    GetParent,
    HasNode,
    FindChild,
}

Callback signature:

type NodeQueryCallback = fn(NodeQueryType, Option<String>) -> Result<Value, String>;

Thread-Local Storage Pattern

Setup (godot_bind/src/lib.rs:14):

thread_local! {
    static CURRENT_NODE_INSTANCE_ID: RefCell<Option<InstanceId>> = const { RefCell::new(None) };
}

Registration (before script execution):

CURRENT_NODE_INSTANCE_ID.with(|id| *id.borrow_mut() = Some(instance_id));
env.set_node_query_callback(Some(node_query_callback_tls));

Cleanup (after script execution):

CURRENT_NODE_INSTANCE_ID.with(|id| *id.borrow_mut() = None);

Error Handling

12 new error codes (E601-E613):

Code	Function	Description
E601	get_node	Wrong argument count
E602	get_node	Empty path
E603	get_node	Node not found
E604	get_node	No callback set
E605	get_parent	Wrong argument count
E606	get_parent	No parent node
E607	has_node	Wrong argument count
E608	has_node	Empty path
E609	has_node	No callback set
E610	find_child	Wrong argument count
E611	find_child	Empty name
E612	find_child	Child not found
E613	find_child	No callback set

---

Testing

Test Coverage

• 17 new tests (11 type checker + 6 runtime)
• 416 total tests passing (396 existing + 17 new + 3 other)
• Zero clippy warnings
• Build time: 2-4 seconds
• Test time: 0.5 seconds

Type Checker Tests (11)

Valid usage (4 tests):

• get_node with string path
• get_parent with no args
• has_node with string path
• find_child with string name

Wrong argument count (4 tests):

• Each function tested with incorrect arg count
• Validates error message format

Wrong argument type (3 tests):

• get_node with i32 instead of string
• has_node with i32 instead of string
• find_child with i32 instead of string
• Note: Tests updated for type coercion behavior

Runtime Tests (6)

Mock callback tests:

• get_node: Success and "not found" error
• get_parent: Success and "no parent" error
• has_node: Returns true/false correctly
• find_child: Success and "not found" error

---

Example Scripts

Created 4 comprehensive examples in examples/:

1. node_query_basic.ferris - Basic get_node and get_parent usage
2. node_query_validation.ferris - has_node for safe access patterns
3. node_query_search.ferris - find_child recursive searching
4. node_query_error_handling.ferris - Error handling best practices

---

Documentation

Updated Files

• ✅ docs/planning/v0.0.4/PHASE_3_NODE_QUERIES.md - Complete implementation plan (530+ lines)
• ✅ docs/planning/v0.0.4/README.md - Phase 3 marked complete
• ✅ CHANGELOG.md - Phase 3 entry added
• ✅ 4 example scripts created

Planning Document

See PHASE_3_NODE_QUERIES.md for:

• Complete implementation phases (3.1-3.7)
• Acceptance criteria (all met ✅)
• Architecture details
• Known limitations
• Timeline (estimated vs actual)
• Final statistics

---

Changes by File

crates/runtime/src/lib.rs (+180 lines)

• Value::Node variant (line 78)
• NodeHandle struct (lines 127-169)
• NodeQueryType enum (lines 204-216)
• NodeQueryCallback type (line 203)
• Env.node_query_callback field (line 274)
• Env.set_node_query_callback() (lines 323-325)
• call_builtin() special handling (lines 430-489):
  • get_node validation and callback invocation
  • get_parent validation and callback invocation
  • has_node validation and callback invocation (returns bool)
  • find_child validation and callback invocation
• 6 runtime tests (lines 2866-3019)

crates/godot_bind/src/lib.rs (+70 lines)

• CURRENT_NODE_INSTANCE_ID thread-local (line 14)
• node_query_callback_tls() function (lines 48-107):
  • GetNode: node.try_get_node_as::<Node2D>(path)
  • GetParent: node.get_parent()
  • HasNode: node.has_node(path) → bool
  • FindChild: node.find_child(name)
• Callback setup (lines 432-434)
• Cleanup (lines 455-457)
• value_to_variant() update (line 126): Node → nil
• godot_print_builtin() update (line 137): Debug print for Node

crates/compiler/src/type_checker.rs (+30 lines + 11 tests)

• get_node registration (lines 152-158): (string) -> Node
• get_parent registration (lines 160-165): () -> Node
• has_node registration (lines 167-172): (string) -> bool
• find_child registration (lines 174-179): (string) -> Node
• 11 type checker tests (lines 2704-2848)

examples/ (+4 files)

• node_query_basic.ferris - Basic usage
• node_query_validation.ferris - Safe patterns with has_node
• node_query_search.ferris - Recursive find_child
• node_query_error_handling.ferris - Best practices

---

Known Limitations

Node Reference Limitations

Current: Nodes cannot be stored in variables or passed as arguments

// NOT SUPPORTED:
let my_node = get_node("Player");
some_function(my_node); // Can't pass nodes

Reason: FerrisScript's type system doesn't support reference types yet

Workaround: Store paths as strings, query when needed

let player_path = "Player";
if has_node(player_path) {
    let player = get_node(player_path);
}

Node Invalidation

Issue: Nodes may become invalid if freed in Godot

Current Behavior: No validity checking implemented

Future Solution (deferred to v0.0.5 or later):

• Weak reference pattern using ObjectID
• is_valid() checks before operations
• Graceful error handling for freed nodes

Recommendation: Validate with has_node() before accessing nodes that may be freed

Array Support

Deferred: get_children() -> Array<Node> requires array support

Planned: v0.0.6 or later when arrays are implemented

---

Breaking Changes

None - This is additive functionality only.

---

Migration Guide

No migration needed - Existing code continues to work unchanged.

For New Code

Use node queries in lifecycle callbacks:

fn _ready() {
    // Validate before accessing
    if has_node("Player") {
        let player = get_node("Player");
    }
}

fn _process(delta: f32) {
    // Navigate hierarchy
    let parent = get_parent();
    
    // Search for components
    let health_bar = find_child("HealthBar");
}

---

Performance Notes

Build Performance

• Compilation: 2-4 seconds (no change from baseline)
• Test execution: 0.5 seconds (17 new tests)
• Zero warnings: Clean clippy and rustc output

Runtime Performance

• Node queries: Direct Godot API calls (no overhead)
• Thread-local lookup: O(1) instance ID retrieval
• Callback mechanism: Single function pointer call

---

Implementation Efficiency

Time Savings

Original Estimate: 2-3 days (12-19 hours)
Actual Time: ~6 hours
Efficiency Gain: 50-68% time savings

Key Factor: Batching phases 3.2-3.5 (all 4 functions together)

• Eliminated context switching
• Reused infrastructure setup
• Parallel test development
• Saved 4-7 hours of overhead

Lessons Learned

1. Batching similar features dramatically improves efficiency
2. Thread-local storage provides clean separation for callbacks
3. Type coercion in type checker requires flexible test assertions
4. Mock callbacks enable thorough runtime testing without Godot

---

Checklist

Implementation

• Value::Node variant and NodeHandle struct
• NodeQueryType enum and callback type
• get_node() implementation
• get_parent() implementation
• has_node() implementation
• find_child() implementation
• Thread-local storage setup
• Godot API integration
• Error code definitions (E601-E613)

Testing

• Type checker tests (11 tests)
• Runtime tests (6 tests)
• All 416 tests passing
• Zero clippy warnings
• Build verification

Documentation

• PHASE_3_NODE_QUERIES.md planning document
• README.md updated
• CHANGELOG.md updated
• Example scripts created (4 files)
• PR description completed
• Error codes documented

Review Ready

• All tests passing
• Zero warnings
• Documentation complete
• Examples provided
• Known limitations documented
• Code review by maintainer
• Manual testing in Godot (optional)
• Merge to develop

---

Next Steps

1. Code Review - Review implementation and tests
2. Godot Testing (Optional) - Manual validation in test project
3. Merge - Merge to develop branch
4. Phase 4 - Begin Godot Types (Color, Rect2, Transform2D)

---

Related Links

• Planning Document: PHASE_3_NODE_QUERIES.md
• v0.0.4 Overview: docs/planning/v0.0.4/README.md
• Phase 1 (Signals): PR Phase 1 Signal Support #46
• Phase 2 (Callbacks): Branch feature/v0.0.4-phase1-prep
• Error Codes Reference: ERROR_CODES.md

---

Ready for Review ✅

[codecov]

Codecov Report

❌ Patch coverage is 46.48074% with 403 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
crates/test_harness/src/main.rs	0.00%	101 Missing ⚠️
crates/test_harness/src/test_runner.rs	0.00%	84 Missing ⚠️
crates/test_harness/src/scene_builder.rs	32.89%	51 Missing ⚠️
crates/godot_bind/src/lib.rs	0.00%	37 Missing ⚠️
crates/test_harness/src/godot_cli.rs	5.88%	32 Missing ⚠️
crates/test_harness/src/output_parser.rs	72.11%	29 Missing ⚠️
crates/test_harness/src/test_config.rs	0.00%	19 Missing ⚠️
crates/test_harness/src/metadata_parser.rs	81.25%	18 Missing ⚠️
crates/runtime/src/lib.rs	68.75%	15 Missing ⚠️
crates/test_harness/src/report_generator.rs	90.29%	13 Missing ⚠️
... and 1 more

📢 Thoughts on this report? Let us know!

[dev-parkins]

• Godot CLI Testing ✅
• node queries ✅
• enriched test annotations ✅
• assertions ✅
• entire godot harness ✅
• new research documents ✅
• additional coverage ✅