IncludeCPP 3.8.9__py3-none-any.whl → 4.0.2__py3-none-any.whl

includecpp/core/cssl/cssl_runtime.py

@@ -68,11 +68,11 @@ class CSSLRuntimeError(Exception):
         # Build detailed error message
         error_parts = []
 
-        # Main error message
+        # Main error message (no "Error:" prefix - CLI handles that)
         if line:
-            error_parts.append(f"Error at line {line}: {message}")
+            error_parts.append(f"Line {line}: {message}")
         else:
-            error_parts.append(f"Error: {message}")
+            error_parts.append(message)
 
         # Add context if available
         if context:
@@ -99,6 +99,89 @@ ERROR_HINTS = {
 }
 
 
+def _find_similar_names(name: str, candidates: list, max_distance: int = 2) -> list:
+    """Find similar names for 'did you mean' suggestions using Levenshtein distance."""
+    if not candidates:
+        return []
+
+    def levenshtein(s1: str, s2: str) -> int:
+        if len(s1) < len(s2):
+            s1, s2 = s2, s1
+        if len(s2) == 0:
+            return len(s1)
+        prev_row = range(len(s2) + 1)
+        for i, c1 in enumerate(s1):
+            curr_row = [i + 1]
+            for j, c2 in enumerate(s2):
+                insertions = prev_row[j + 1] + 1
+                deletions = curr_row[j] + 1
+                substitutions = prev_row[j] + (c1.lower() != c2.lower())
+                curr_row.append(min(insertions, deletions, substitutions))
+            prev_row = curr_row
+        return prev_row[-1]
+
+    similar = []
+    name_lower = name.lower()
+    for candidate in candidates:
+        if candidate.startswith('_'):
+            continue
+        dist = levenshtein(name, candidate)
+        # Also check case-insensitive exact match
+        if name_lower == candidate.lower() and name != candidate:
+            similar.insert(0, candidate)  # Exact case mismatch goes first
+        elif dist <= max_distance:
+            similar.append(candidate)
+
+    return similar[:3]  # Return top 3 suggestions
+
+
+def _get_available_classes(scope: 'Scope', global_scope: 'Scope', promoted_globals: dict) -> list:
+    """Get list of all available class names."""
+    classes = []
+    # Check current scope chain
+    current = scope
+    while current:
+        for name, val in current.variables.items():
+            if isinstance(val, CSSLClass) and name not in classes:
+                classes.append(name)
+        current = current.parent
+    # Check global scope
+    for name, val in global_scope.variables.items():
+        if isinstance(val, CSSLClass) and name not in classes:
+            classes.append(name)
+    # Check promoted globals
+    for name, val in promoted_globals.items():
+        if isinstance(val, CSSLClass) and name not in classes:
+            classes.append(name)
+    return classes
+
+
+def _get_available_functions(scope: 'Scope', global_scope: 'Scope', builtins) -> list:
+    """Get list of all available function names."""
+    functions = []
+    # Check current scope chain
+    current = scope
+    while current:
+        for name, val in current.variables.items():
+            if callable(val) or (isinstance(val, ASTNode) and val.type == 'function'):
+                if name not in functions:
+                    functions.append(name)
+        current = current.parent
+    # Check global scope
+    for name, val in global_scope.variables.items():
+        if callable(val) or (isinstance(val, ASTNode) and val.type == 'function'):
+            if name not in functions:
+                functions.append(name)
+    # Check builtins
+    if builtins:
+        for name in dir(builtins):
+            if name.startswith('builtin_'):
+                func_name = name[8:]  # Remove 'builtin_' prefix
+                if func_name not in functions:
+                    functions.append(func_name)
+    return functions
+
+
 class CSSLBreak(Exception):
     """Break statement"""
     pass
@@ -280,11 +363,11 @@ class CSSLRuntime:
         """Format a detailed error with source context"""
         error_parts = []
 
-        # Main error header
+        # Main error header (no "Error:" prefix - CLI handles that)
         if line and line > 0:
-            error_parts.append(f"Error at line {line} in {self._current_file}:")
+            error_parts.append(f"Line {line} in {self._current_file}:")
         else:
-            error_parts.append(f"Error in {self._current_file}:")
+            error_parts.append(f"In {self._current_file}:")
 
         # Extract message without existing line info
         clean_msg = message
@@ -716,9 +799,12 @@ class CSSLRuntime:
         Parses class members and methods, creating a CSSLClass object
         that can be instantiated with 'new'.
         Supports inheritance via 'extends' keyword and method overwriting via 'overwrites'.
+
+        Classes are local by default. Use 'global class' or 'class @Name' for global classes.
         """
         class_info = node.value
         class_name = class_info.get('name')
+        is_global = class_info.get('is_global', False)
         extends_class_name = class_info.get('extends')
         extends_is_python = class_info.get('extends_is_python', False)
         overwrites_class_name = class_info.get('overwrites')
@@ -745,7 +831,22 @@ class CSSLRuntime:
                     parent_class = self.global_scope.get(extends_class_name)
 
             if parent_class is None:
-                raise ValueError(f"Cannot extend unknown class '{extends_class_name}'")
+                # Build detailed error for extends
+                available_classes = _get_available_classes(self.scope, self.global_scope, self._promoted_globals)
+                similar = _find_similar_names(extends_class_name, available_classes)
+
+                if similar:
+                    hint = f"Did you mean: {', '.join(similar)}?"
+                elif extends_is_python:
+                    hint = f"Python object '${extends_class_name}' not found. Use share() to share Python objects first."
+                else:
+                    hint = f"Define class '{extends_class_name}' before this class, or use 'extends $PyObject' for Python objects"
+
+                raise self._format_error(
+                    node.line,
+                    f"Cannot extend unknown class '{extends_class_name}'",
+                    hint
+                )
 
             # Auto-wrap Python objects for inheritance
             from .cssl_builtins import CSSLizedPythonObject
@@ -803,9 +904,11 @@ class CSSLRuntime:
         class_def.class_params = class_params  # Class-level constructor parameters
         class_def.extends_args = extends_args  # Arguments to pass to parent constructor
 
-        # Register class in scope
+        # Register class in scope (local by default, global if marked)
         self.scope.set(class_name, class_def)
-        self.global_scope.set(class_name, class_def)
+        if is_global:
+            self.global_scope.set(class_name, class_def)
+            self._promoted_globals[class_name] = class_def
 
         # Handle class overwrites - replace methods in target class
         if overwrites_class_name:
@@ -888,24 +991,43 @@ class CSSLRuntime:
         """Execute function definition - registers it and handles extends/overwrites.
 
         Syntax:
-            define func() { ... }
-            define func : extends otherFunc() { ... }  - Inherit local vars
-            define func : overwrites otherFunc() { ... }  - Replace otherFunc
+            define func() { ... }                           - Local function
+            global define func() { ... }                    - Global function
+            define @func() { ... }                          - Global function (alternative)
+            define func : extends otherFunc() { ... }       - Inherit local vars
+            define func : overwrites otherFunc() { ... }    - Replace otherFunc
         """
         func_info = node.value
         func_name = func_info.get('name')
+        is_global = func_info.get('is_global', False)
         extends_func = func_info.get('extends')
         extends_is_python = func_info.get('extends_is_python', False)
         overwrites_func = func_info.get('overwrites')
         overwrites_is_python = func_info.get('overwrites_is_python', False)
 
+        # Get append/overwrite reference info (&Class::method syntax)
+        append_mode = func_info.get('append_mode', False)
+        append_ref_class = func_info.get('append_ref_class')
+        append_ref_member = func_info.get('append_ref_member')
+
         # Store function extends info for runtime use
         if extends_func:
             node.value['_extends_resolved'] = self._resolve_function_target(
                 extends_func, extends_is_python
             )
 
-        # Handle overwrites - replace the target function
+        # Handle &Class::method syntax
+        # Without ++ = full replacement
+        # With ++ = append (run original first, then new code)
+        if append_ref_class:
+            if append_mode:
+                # Append mode: wrap original to run original + new
+                self._append_to_target(append_ref_class, append_ref_member, node)
+            else:
+                # Full replacement
+                self._overwrite_target(append_ref_class, append_ref_member, node)
+
+        # Handle overwrites keyword - replace the target function
         if overwrites_func:
             target = self._resolve_function_target(overwrites_func, overwrites_is_python)
             if target is not None:
@@ -922,8 +1044,11 @@ class CSSLRuntime:
                     self.scope.set(overwrites_func, node)
                     self.global_scope.set(overwrites_func, node)
 
-        # Register the function
+        # Register the function (local by default, global if marked)
         self.scope.set(func_name, node)
+        if is_global:
+            self.global_scope.set(func_name, node)
+            self._promoted_globals[func_name] = node
         return None
 
     def _resolve_function_target(self, name: str, is_python: bool) -> Any:
@@ -945,6 +1070,142 @@ class CSSLRuntime:
             return self._call_function(func_node, list(args), kwargs)
         return wrapper
 
+    def _overwrite_target(self, ref_class: str, ref_member: str, replacement_node: ASTNode):
+        """Overwrite a class method or function with the replacement.
+
+        Handles:
+        - &ClassName::method - Overwrite method in CSSL class
+        - &$PyObject.method - Overwrite method in Python shared object
+        - &functionName - Overwrite standalone function
+        """
+        from ..cssl_bridge import _live_objects, SharedObjectProxy
+
+        # Handle Python shared objects
+        if ref_class.startswith('$'):
+            var_name = ref_class[1:]
+            ref_obj = _live_objects.get(var_name)
+            if ref_obj is None:
+                ref_obj = self.scope.get(var_name) or self.global_scope.get(var_name)
+
+            if ref_obj is None:
+                return
+
+            # Unwrap SharedObjectProxy
+            if isinstance(ref_obj, SharedObjectProxy):
+                ref_obj = ref_obj._obj
+
+            # Overwrite Python object method
+            if ref_member and hasattr(ref_obj, ref_member):
+                wrapper = self._create_python_wrapper(replacement_node)
+                try:
+                    setattr(ref_obj, ref_member, wrapper)
+                except (AttributeError, TypeError):
+                    pass  # Can't overwrite (immutable or builtin)
+            return
+
+        # Handle CSSL class method overwrite
+        target_class = self.scope.get(ref_class) or self.global_scope.get(ref_class)
+        if target_class is None:
+            # Maybe it's a standalone function reference (no ::member)
+            if ref_member is None:
+                # &functionName - overwrite the function
+                self.scope.set(ref_class, replacement_node)
+                self.global_scope.set(ref_class, replacement_node)
+            return
+
+        if isinstance(target_class, CSSLClass) and ref_member:
+            # Overwrite method in the class
+            if hasattr(target_class, 'methods') and isinstance(target_class.methods, dict):
+                target_class.methods[ref_member] = replacement_node
+            # Also check members list
+            if hasattr(target_class, 'members'):
+                for i, member in enumerate(target_class.members):
+                    if member.type in ('function', 'FUNCTION') and member.value.get('name') == ref_member:
+                        target_class.members[i] = replacement_node
+                        break
+
+    def _append_to_target(self, ref_class: str, ref_member: str, append_node: ASTNode):
+        """Append new code to an existing class method or function.
+
+        Creates a wrapper that runs original first, then the appended code.
+        Handles:
+        - &ClassName::method ++ - Append to method in CSSL class
+        - &$PyObject.method ++ - Append to method in Python shared object
+        - &functionName ++ - Append to standalone function
+        """
+        from ..cssl_bridge import _live_objects, SharedObjectProxy
+
+        # Handle Python shared objects
+        if ref_class.startswith('$'):
+            var_name = ref_class[1:]
+            ref_obj = _live_objects.get(var_name)
+            if ref_obj is None:
+                ref_obj = self.scope.get(var_name) or self.global_scope.get(var_name)
+
+            if ref_obj is None:
+                return
+
+            if isinstance(ref_obj, SharedObjectProxy):
+                ref_obj = ref_obj._obj
+
+            # Create wrapper that calls original + new
+            if ref_member and hasattr(ref_obj, ref_member):
+                original_method = getattr(ref_obj, ref_member)
+                runtime = self
+                def appended_wrapper(*args, **kwargs):
+                    # Run original first
+                    result = None
+                    if callable(original_method):
+                        try:
+                            result = original_method(*args, **kwargs)
+                        except:
+                            pass
+                    # Then run appended code
+                    return runtime._call_function(append_node, list(args), kwargs)
+                try:
+                    setattr(ref_obj, ref_member, appended_wrapper)
+                except (AttributeError, TypeError):
+                    pass
+            return
+
+        # Handle CSSL class method append
+        target_class = self.scope.get(ref_class) or self.global_scope.get(ref_class)
+        if target_class is None:
+            # Standalone function append
+            if ref_member is None:
+                original_func = self.scope.get(ref_class) or self.global_scope.get(ref_class)
+                if original_func:
+                    # Store original in append_node so it can run first
+                    append_node.value['_original_func'] = original_func
+                self.scope.set(ref_class, append_node)
+                self.global_scope.set(ref_class, append_node)
+            return
+
+        if isinstance(target_class, CSSLClass) and ref_member:
+            # Find original method
+            original_method = None
+            if hasattr(target_class, 'methods') and isinstance(target_class.methods, dict):
+                original_method = target_class.methods.get(ref_member)
+
+            if original_method is None and hasattr(target_class, 'members'):
+                for member in target_class.members:
+                    if member.type in ('function', 'FUNCTION') and member.value.get('name') == ref_member:
+                        original_method = member
+                        break
+
+            # Store original in append_node for runtime execution
+            if original_method:
+                append_node.value['_original_method'] = original_method
+
+            # Replace with append_node (which will call original first via _call_function)
+            if hasattr(target_class, 'methods') and isinstance(target_class.methods, dict):
+                target_class.methods[ref_member] = append_node
+            if hasattr(target_class, 'members'):
+                for i, member in enumerate(target_class.members):
+                    if member.type in ('function', 'FUNCTION') and member.value.get('name') == ref_member:
+                        target_class.members[i] = append_node
+                        break
+
     def _exec_typed_declaration(self, node: ASTNode) -> Any:
         """Execute typed variable declaration: type<T> varName = value;
 
@@ -1243,12 +1504,15 @@ class CSSLRuntime:
                         if not self._running:
                             break
                         self._execute_node(child)
-                    # Copy all local vars to new scope
-                    for name, value in temp_scope._vars.items():
-                        new_scope.set(name, value)
+                except CSSLReturn:
+                    # Parent returned - that's fine, we just want the local vars
+                    pass
                 except:
                     pass
                 finally:
+                    # ALWAYS copy local vars (even if parent returned)
+                    for name, value in temp_scope.variables.items():
+                        new_scope.set(name, value)
                     self.scope = old_scope
 
         # Bind parameters - handle both positional and named arguments
@@ -1307,7 +1571,80 @@ class CSSLRuntime:
                     break
                 self._execute_node(child)
         except CSSLReturn as ret:
-            return ret.value
+            return_value = ret.value
+
+            # Check exclude_type: *[type] - must NOT return excluded type
+            exclude_type = func_info.get('exclude_type')
+            if exclude_type and isinstance(exclude_type, str):
+                type_map = {
+                    'string': str, 'int': int, 'float': float, 'bool': bool,
+                    'null': type(None), 'none': type(None),
+                    'list': list, 'array': list, 'dict': dict, 'json': dict,
+                }
+                excluded_py_type = type_map.get(exclude_type.lower())
+                # For shuffled returns (tuples), check each element
+                if isinstance(return_value, tuple):
+                    for val in return_value:
+                        if excluded_py_type and isinstance(val, excluded_py_type):
+                            raise CSSLRuntimeError(f"Type exclusion: function must NOT return '{exclude_type}' values")
+                elif excluded_py_type and isinstance(return_value, excluded_py_type):
+                    raise CSSLRuntimeError(f"Type exclusion: function must NOT return '{exclude_type}'")
+
+            # Enforce return type for typed functions (like C++)
+            # Typed functions MUST return the declared type
+            # Exception: 'meta' modifier allows any return type
+            enforce_return_type = func_info.get('enforce_return_type', False)
+            return_type = func_info.get('return_type')
+
+            if enforce_return_type and return_type and return_type != 'void':
+                # Type mapping from CSSL types to Python types
+                type_validate_map = {
+                    'string': str, 'int': int, 'float': (int, float), 'bool': bool,
+                    'list': list, 'array': list, 'dict': dict, 'json': dict,
+                    'dynamic': object,  # Any type
+                    'void': type(None),
+                }
+
+                # Generic container types - accept lists/tuples
+                container_types = {
+                    'vector', 'stack', 'datastruct', 'dataspace',
+                    'shuffled', 'iterator', 'combo', 'openquote', 'map'
+                }
+
+                if return_type in container_types:
+                    # Container types accept list, tuple, dict depending on type
+                    if return_type == 'map':
+                        expected = dict
+                    elif return_type == 'shuffled':
+                        expected = (list, tuple)
+                    else:
+                        expected = (list, tuple, object)
+
+                    if not isinstance(return_value, expected):
+                        func_name = func_info.get('name', 'unknown')
+                        actual_type = type(return_value).__name__
+                        raise CSSLRuntimeError(
+                            f"Type error in '{func_name}': declared return type '{return_type}' "
+                            f"but returned '{actual_type}'. Typed functions must return declared type."
+                        )
+                elif return_type in type_validate_map:
+                    expected = type_validate_map[return_type]
+                    if expected != object and return_value is not None:
+                        if not isinstance(return_value, expected):
+                            func_name = func_info.get('name', 'unknown')
+                            actual_type = type(return_value).__name__
+                            raise CSSLRuntimeError(
+                                f"Type error in '{func_name}': declared return type '{return_type}' "
+                                f"but returned '{actual_type}'. Typed functions must return declared type."
+                            )
+
+            # Check non_null: function must return a value (not None)
+            non_null = func_info.get('non_null', False)
+            if non_null and return_value is None:
+                func_name = func_info.get('name', 'unknown')
+                raise CSSLRuntimeError(f"Non-null function '{func_name}' returned null/None")
+
+            return return_value
         except Exception as e:
             # If undefined modifier, suppress all errors
             if is_undefined:
@@ -2715,7 +3052,21 @@ class CSSLRuntime:
             scoped_val = self.global_scope.get(f'${name}')
             if scoped_val is not None:
                 return scoped_val
-            raise CSSLRuntimeError(f"Shared object '${name}' not found. Use share() to share objects.")
+            # List available shared objects for helpful error
+            available_shared = list(_live_objects.keys())
+            similar = _find_similar_names(name, available_shared)
+            if similar:
+                hint = f"Did you mean: ${', $'.join(similar)}?"
+            elif available_shared:
+                hint = f"Available shared objects: ${', $'.join(available_shared[:5])}"
+            else:
+                hint = "Use share(name, object) from Python to share objects first."
+
+            raise self._format_error(
+                node.line if hasattr(node, 'line') else 0,
+                f"Shared object '${name}' not found",
+                hint
+            )
 
         if node.type == 'captured_ref':
             # %<name> captured reference - use value captured at infusion registration time
@@ -2742,7 +3093,13 @@ class CSSLRuntime:
                 value = self._original_functions.get(name)
             if value is not None:
                 return value
-            raise CSSLRuntimeError(f"Captured reference '%{name}' not found.")
+            # Build helpful error for captured reference
+            hint = f"Variable '{name}' must exist when the infusion is registered. Check that '%{name}' is defined before the <<== operator."
+            raise self._format_error(
+                node.line if hasattr(node, 'line') else 0,
+                f"Captured reference '%{name}' not found",
+                hint
+            )
 
         if node.type == 'instance_ref':
             # instance<"name"> - get shared instance by name
@@ -2831,6 +3188,58 @@ class CSSLRuntime:
         if node.type == 'unary':
             return self._eval_unary(node)
 
+        if node.type == 'non_null_assert':
+            # *$var, *@module, *identifier - assert value is not null/None
+            operand = node.value.get('operand')
+            value = self._evaluate(operand)
+            if value is None:
+                # Get name of the operand for better error message
+                operand_name = "unknown"
+                if isinstance(operand, ASTNode):
+                    if operand.type == 'identifier':
+                        operand_name = operand.value
+                    elif operand.type == 'shared_ref':
+                        operand_name = f"${operand.value}"
+                    elif operand.type == 'module_ref':
+                        operand_name = f"@{operand.value}"
+                    elif operand.type == 'global_ref':
+                        operand_name = f"r@{operand.value}"
+                raise self._format_error(
+                    node.line if hasattr(node, 'line') else 0,
+                    f"Non-null assertion failed: '{operand_name}' is null/None",
+                    f"The value accessed via '*{operand_name}' must not be null. Check that it is defined and initialized."
+                )
+            return value
+
+        if node.type == 'type_exclude_assert':
+            # *[type]expr - assert value is NOT of excluded type
+            exclude_type = node.value.get('exclude_type')
+            operand = node.value.get('operand')
+            value = self._evaluate(operand)
+
+            # Map CSSL types to Python types
+            type_map = {
+                'string': str,
+                'int': int,
+                'float': float,
+                'bool': bool,
+                'null': type(None),
+                'none': type(None),
+                'list': list,
+                'array': list,
+                'dict': dict,
+                'json': dict,
+            }
+
+            excluded_py_type = type_map.get(exclude_type.lower() if isinstance(exclude_type, str) else exclude_type)
+            if excluded_py_type and isinstance(value, excluded_py_type):
+                raise self._format_error(
+                    node.line if hasattr(node, 'line') else 0,
+                    f"Type exclusion assertion failed: value is of excluded type '{exclude_type}'",
+                    f"The expression was marked *[{exclude_type}] meaning it must NOT return {exclude_type}, but it did."
+                )
+            return value
+
         if node.type == 'call':
             return self._eval_call(node)
 
@@ -3108,12 +3517,33 @@ class CSSLRuntime:
             return self._call_function(callee, args, kwargs)
 
         callee_name = callee_node.value if isinstance(callee_node, ASTNode) and hasattr(callee_node, 'value') else str(callee_node)
-        raise CSSLRuntimeError(
-            f"Cannot call '{callee_name}' - it is not a function",
-            node.line,
-            context=f"Type: {type(callee).__name__}",
-            hint=ERROR_HINTS['undefined_function']
-        )
+
+        # Build detailed error with suggestions
+        available_funcs = _get_available_functions(self.scope, self.global_scope, self.builtins)
+        similar = _find_similar_names(callee_name, available_funcs)
+
+        if callee is None:
+            # Function not found at all
+            if similar:
+                hint = f"Did you mean: {', '.join(similar)}?"
+            else:
+                hint = f"Function '{callee_name}' is not defined. Define it with: define {callee_name}() {{ }}"
+            raise self._format_error(
+                node.line,
+                f"Function '{callee_name}' not found",
+                hint
+            )
+        else:
+            # Found something but it's not callable
+            if similar:
+                hint = f"'{callee_name}' is a {type(callee).__name__}, not a function. Did you mean: {', '.join(similar)}?"
+            else:
+                hint = f"'{callee_name}' is a {type(callee).__name__}. Functions must be defined with 'define' keyword."
+            raise self._format_error(
+                node.line,
+                f"Cannot call '{callee_name}' - it is not a function",
+                hint
+            )
 
     def _eval_typed_call(self, node: ASTNode) -> Any:
         """Evaluate typed function call like OpenFind<string>(0) or OpenFind<dynamic, "name">"""
@@ -3179,26 +3609,53 @@ class CSSLRuntime:
         )
 
     def _eval_new(self, node: ASTNode) -> CSSLInstance:
-        """Evaluate 'new ClassName(args)' expression.
+        """Evaluate 'new ClassName(args)' or 'new @ClassName(args)' expression.
 
         Creates a new instance of a CSSL class and calls its constructor.
         Supports multiple constructors (constr keyword), class parameters,
         and automatic parent constructor calling.
+
+        With '@' prefix (new @ClassName), looks only in global scope.
         """
         class_name = node.value.get('class')
+        is_global_ref = node.value.get('is_global_ref', False)
         args = [self._evaluate(arg) for arg in node.value.get('args', [])]
         kwargs = {k: self._evaluate(v) for k, v in node.value.get('kwargs', {}).items()}
 
         # Get class definition from scope
-        class_def = self.scope.get(class_name)
-        if class_def is None:
-            class_def = self.global_scope.get(class_name)
+        if is_global_ref:
+            # With @ prefix, only look in global scope
+            class_def = self._promoted_globals.get(class_name)
+            if class_def is None:
+                class_def = self.global_scope.get(class_name)
+        else:
+            # Normal lookup: local scope first, then global
+            class_def = self.scope.get(class_name)
+            if class_def is None:
+                class_def = self.global_scope.get(class_name)
 
         if class_def is None:
-            raise CSSLRuntimeError(
-                f"Class '{class_name}' not found",
+            # Build detailed error with suggestions
+            source_line = self._get_source_line(node.line)
+            available_classes = _get_available_classes(self.scope, self.global_scope, self._promoted_globals)
+            similar = _find_similar_names(class_name, available_classes)
+
+            # Check if class exists in global scope (user forgot @)
+            global_class = self._promoted_globals.get(class_name) or self.global_scope.get(class_name)
+            if global_class and isinstance(global_class, CSSLClass) and not is_global_ref:
+                hint = f"Class '{class_name}' exists in global scope. Use: new @{class_name}()"
+            elif similar:
+                hint = f"Did you mean: {', '.join(similar)}?"
+            elif available_classes:
+                hint = f"Available classes: {', '.join(available_classes[:5])}"
+            else:
+                hint = "Define the class before instantiation, or use 'global class' / 'class @Name' for global classes"
+
+            context = f"in expression: {source_line.strip()}" if source_line else None
+            raise self._format_error(
                 node.line,
-                hint="Make sure the class is defined before instantiation"
+                f"Class '{class_name}' not found",
+                hint
             )
 
         if not isinstance(class_def, CSSLClass):
@@ -3326,12 +3783,34 @@ class CSSLRuntime:
 
         # Resolve the class/instance reference
         if ref_class.startswith('$'):
-            # Dynamic instance reference: &$instanceVar::member
+            # Dynamic instance reference: &$instanceVar::member or &$PyObject.method
             var_name = ref_class[1:]
-            ref_obj = self.scope.get(var_name) or self.global_scope.get(var_name)
+
+            # First check in _live_objects for Python shared objects
+            from ..cssl_bridge import _live_objects, SharedObjectProxy
+            ref_obj = _live_objects.get(var_name)
+            if ref_obj is None:
+                ref_obj = self.scope.get(var_name) or self.global_scope.get(var_name)
+
             if ref_obj is None:
                 return  # Instance not found, skip silently
 
+            # Handle Python shared objects
+            if isinstance(ref_obj, SharedObjectProxy):
+                ref_obj = ref_obj._obj
+
+            # If it's a Python object (not CSSL), call the method directly
+            if not isinstance(ref_obj, (CSSLInstance, CSSLClass)):
+                if ref_member and hasattr(ref_obj, ref_member):
+                    method = getattr(ref_obj, ref_member)
+                    if callable(method):
+                        try:
+                            method(*args, **kwargs)
+                        except TypeError:
+                            # Try without args
+                            method()
+                return
+
             if isinstance(ref_obj, CSSLInstance):
                 # Get the class definition from the instance
                 target_class = ref_obj.class_def
@@ -3490,9 +3969,24 @@ class CSSLRuntime:
                 return lambda *args, **kwargs: python_method(*args, **kwargs)
             return lambda *args, **kwargs: self._call_method(instance, method_node, list(args), kwargs)
 
-        raise CSSLRuntimeError(
-            f"'{instance._class.name}' has no member or method '{member}'",
-            node.line if hasattr(node, 'line') else 0
+        # Build helpful error with available members
+        class_name = instance._class.name
+        available_members = list(instance._members.keys()) if hasattr(instance, '_members') else []
+        available_methods = list(instance._methods.keys()) if hasattr(instance, '_methods') else []
+        all_available = available_members + available_methods
+        similar = _find_similar_names(member, all_available)
+
+        if similar:
+            hint = f"Did you mean: {', '.join(similar)}?"
+        elif all_available:
+            hint = f"Available: {', '.join(all_available[:5])}"
+        else:
+            hint = f"Class '{class_name}' has no accessible members. Check class definition."
+
+        raise self._format_error(
+            node.line if hasattr(node, 'line') else 0,
+            f"'{class_name}' has no member or method '{member}'",
+            hint
         )
 
     def _call_method(self, instance: CSSLInstance, method_node: ASTNode, args: list, kwargs: dict = None) -> Any:
@@ -3536,9 +4030,19 @@ class CSSLRuntime:
         self.scope = new_scope
         self._current_instance = instance
 
+        original_return = None
         try:
+            # Handle append mode via _append_to_target (stored original)
+            original_method = func_info.get('_original_method')
+            if original_method:
+                # Execute original method first - capture return for fallback
+                try:
+                    original_return = self._call_method(instance, original_method, args, kwargs)
+                except CSSLReturn as ret:
+                    original_return = ret.value
+
             # Handle append mode (++) - execute referenced parent method first
-            if append_mode and append_ref_class:
+            elif append_mode and append_ref_class:
                 self._execute_append_reference(
                     instance, append_ref_class, append_ref_member,
                     args, kwargs, {}, is_constructor=False
@@ -3559,7 +4063,8 @@ class CSSLRuntime:
             self.scope = old_scope
             self._current_instance = old_instance
 
-        return None
+        # If no return in appended code, use original's return
+        return original_return
 
     def _eval_member_access(self, node: ASTNode) -> Any:
         """Evaluate member access"""
@@ -3587,7 +4092,25 @@ class CSSLRuntime:
                     python_method = method_node[1]
                     return lambda *args, **kwargs: python_method(*args, **kwargs)
                 return lambda *args, **kwargs: self._call_method(obj, method_node, list(args), kwargs)
-            raise CSSLRuntimeError(f"'{obj._class.name}' has no member or method '{member}'")
+            # Build helpful error with available members
+            class_name = obj._class.name
+            available_members = list(obj._members.keys()) if hasattr(obj, '_members') else []
+            available_methods = list(obj._methods.keys()) if hasattr(obj, '_methods') else []
+            all_available = available_members + available_methods
+            similar = _find_similar_names(member, all_available)
+
+            if similar:
+                hint = f"Did you mean: {', '.join(similar)}?"
+            elif all_available:
+                hint = f"Available: {', '.join(all_available[:5])}"
+            else:
+                hint = f"Class '{class_name}' has no accessible members."
+
+            raise self._format_error(
+                node.line,
+                f"'{class_name}' has no member or method '{member}'",
+                hint
+            )
 
         # === STRING METHODS ===
         if isinstance(obj, str):