quantum-framework 0.18.0__py3-none-any.whl

quantum/core/features/logging/src/__init__.py

@@ -0,0 +1,12 @@
+"""
+Logging feature for Quantum Language
+
+Provides structured logging with multiple severity levels,
+conditional output, and external service integration.
+"""
+
+from .ast_node import LogNode
+from .parser import parse_log
+from .runtime import LoggingService
+
+__all__ = ['LogNode', 'parse_log', 'LoggingService']

quantum/core/features/logging/src/ast_node.py

@@ -0,0 +1,111 @@
+"""
+AST Node for q:log - Structured Logging
+"""
+
+from typing import Optional
+from quantum.core.ast_nodes import QuantumNode
+
+
+class LogNode(QuantumNode):
+    """
+    Represents a <q:log> - Structured logging statement
+
+    Example:
+        <q:log level="info" message="User {userName} logged in" context="{user}" />
+        <q:log level="error" message="API failed" when="{!api_result.success}" />
+    """
+
+    VALID_LEVELS = ['trace', 'debug', 'info', 'warning', 'error', 'critical']
+
+    # Spellings people actually write, mapped to the level they mean. `warn`
+    # is what Python's own logging, JavaScript's console and most log
+    # libraries call it, and two examples in this repository use it — one of
+    # them the only q:websocket example there is, which therefore did not
+    # parse. Rejecting a word the whole industry uses is not strictness, it
+    # is a papercut.
+    LEVEL_ALIASES = {
+        'warn': 'warning',
+        'fatal': 'critical',
+        'err': 'error',
+        'verbose': 'trace',
+    }
+
+    def __init__(
+        self,
+        level: str,
+        message: str,
+        context: Optional[str] = None,
+        when: Optional[str] = None,
+        provider: Optional[str] = None,
+        async_mode: bool = True,
+        correlation_id: Optional[str] = None
+    ):
+        """
+        Initialize a LogNode
+
+        Args:
+            level: Log severity level (trace, debug, info, warning, error, critical)
+            message: Log message with databinding support
+            context: Optional structured data (JSON expression)
+            when: Optional conditional expression
+            provider: Optional output destination (Phase 2)
+            async_mode: Async logging mode (Phase 2)
+            correlation_id: Optional request tracking ID (Phase 2)
+        """
+        # Validate level
+        if not level:
+            raise ValueError("Log requires 'level' attribute")
+
+        level = self.LEVEL_ALIASES.get(str(level).strip().lower(), level)
+
+        if level not in self.VALID_LEVELS:
+            raise ValueError(
+                f"Invalid log level '{level}'. Must be one of: {', '.join(self.VALID_LEVELS)}"
+            )
+
+        # Validate message
+        if message is None:
+            raise ValueError("Log requires 'message' attribute")
+
+        self.level = level
+        self.message = message
+        self.context = context
+        self.when = when
+        self.provider = provider
+        self.async_mode = async_mode
+        self.correlation_id = correlation_id
+
+    def __repr__(self):
+        attrs = [f"level={self.level!r}", f"message={self.message!r}"]
+        if self.context:
+            attrs.append(f"context={self.context!r}")
+        if self.when:
+            attrs.append(f"when={self.when!r}")
+        return f"LogNode({', '.join(attrs)})"
+
+    def to_dict(self):
+        """Convert node to dictionary for debugging/serialization"""
+        return {
+            "type": "log",
+            "level": self.level,
+            "message": self.message[:50] + "..." if self.message and len(self.message) > 50 else self.message,
+            "context": self.context,
+            "when": self.when,
+            "provider": self.provider,
+            "async": self.async_mode,
+            "correlation_id": self.correlation_id
+        }
+
+    def validate(self):
+        """Validate the node and return list of errors"""
+        errors = []
+
+        if not self.level:
+            errors.append("Log requires 'level' attribute")
+        elif self.level not in self.VALID_LEVELS:
+            errors.append(f"Invalid log level '{self.level}'. Must be one of: {', '.join(self.VALID_LEVELS)}")
+
+        if not self.message:
+            errors.append("Log requires 'message' attribute")
+
+        return errors

quantum/core/features/logging/src/parser.py

@@ -0,0 +1,50 @@
+"""
+Parser for q:log - Structured Logging
+"""
+
+import xml.etree.ElementTree as ET
+from typing import Optional
+from .ast_node import LogNode
+
+
+def parse_log(log_element: ET.Element) -> LogNode:
+    """
+    Parse a <q:log> element into a LogNode
+
+    Args:
+        log_element: The XML element representing the log statement
+
+    Returns:
+        LogNode instance
+
+    Raises:
+        ValueError: If required attributes are missing or invalid
+    """
+    # Get required attributes
+    level = log_element.get('level')
+    message = log_element.get('message')
+
+    # Get optional attributes
+    context = log_element.get('context')
+    when = log_element.get('when')
+    provider = log_element.get('provider')
+    async_mode_str = log_element.get('async', 'true')
+    correlation_id = log_element.get('correlation_id')
+
+    # Parse async mode
+    async_mode = async_mode_str.lower() == 'true' if async_mode_str else True
+
+    # Validate no child elements (q:log should be self-closing)
+    if len(log_element) > 0:
+        raise ValueError("Log tag must be self-closing")
+
+    # Create and return LogNode (validation happens in __init__)
+    return LogNode(
+        level=level,
+        message=message,
+        context=context,
+        when=when,
+        provider=provider,
+        async_mode=async_mode,
+        correlation_id=correlation_id
+    )

quantum/core/features/logging/src/runtime.py

@@ -0,0 +1,190 @@
+"""
+Runtime service for q:log - Structured Logging
+"""
+
+import logging
+import json
+import os
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+
+class LoggingService:
+    """
+    Service to handle structured logging with multiple severity levels
+
+    Phase 1 Features:
+    - Console and file output
+    - JSON structured format
+    - Multiple log levels
+    - Conditional logging
+    - Context data
+
+    Phase 2 Features (TODO):
+    - Loguru integration
+    - External services (Sentry, Datadog)
+    - Async logging
+    - Log rotation
+    - Correlation IDs
+    """
+
+    # Map Quantum log levels to Python logging levels
+    LEVEL_MAP = {
+        'trace': logging.DEBUG - 5,  # Custom level below DEBUG
+        'debug': logging.DEBUG,
+        'info': logging.INFO,
+        'warning': logging.WARNING,
+        'error': logging.ERROR,
+        'critical': logging.CRITICAL
+    }
+
+    _instance: Optional['LoggingService'] = None
+    _initialized: bool = False
+
+    def __new__(cls):
+        """Singleton pattern to ensure one logger instance"""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        """Initialize the logging service"""
+        if not LoggingService._initialized:
+            self._setup_logging()
+            LoggingService._initialized = True
+
+    @classmethod
+    def configure_from_external(cls, logger):
+        """
+        Inject an externally configured logger so q:log tags reuse
+        the same handlers without duplication.
+
+        Called by logging_setup.setup_logging() after configuring
+        the 'quantum' root logger.
+        """
+        instance = cls.__new__(cls)
+        instance.logger = logger
+        cls._instance = instance
+        cls._initialized = True
+
+    def _setup_logging(self):
+        """Setup logging configuration"""
+        # Create logger
+        self.logger = logging.getLogger('quantum')
+        self.logger.setLevel(logging.DEBUG)  # Capture all levels
+
+        # Prevent duplicate handlers
+        if self.logger.handlers:
+            return
+
+        # Console handler - formatted output for development
+        console_handler = logging.StreamHandler()
+        console_handler.setLevel(logging.DEBUG)
+        console_formatter = logging.Formatter(
+            '%(asctime)s [%(levelname)s] %(message)s',
+            datefmt='%Y-%m-%d %H:%M:%S'
+        )
+        console_handler.setFormatter(console_formatter)
+        self.logger.addHandler(console_handler)
+
+        # File handler - JSON format for production (Phase 1: basic file logging)
+        # Phase 2 will add rotation with Loguru
+        log_dir = 'logs'
+        os.makedirs(log_dir, exist_ok=True)
+        log_file = os.path.join(log_dir, f'quantum_{datetime.now().strftime("%Y%m%d")}.log')
+
+        file_handler = logging.FileHandler(log_file, encoding='utf-8')
+        file_handler.setLevel(logging.DEBUG)
+        # For now, use same format. Phase 2 will use JSON formatter
+        file_handler.setFormatter(console_formatter)
+        self.logger.addHandler(file_handler)
+
+        # Custom TRACE level
+        logging.addLevelName(self.LEVEL_MAP['trace'], 'TRACE')
+
+    def log(
+        self,
+        level: str,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+        correlation_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Write a log entry
+
+        Args:
+            level: Log severity level
+            message: Log message (already resolved with databinding)
+            context: Optional structured context data
+            correlation_id: Optional request tracking ID
+
+        Returns:
+            Result dictionary with success status
+        """
+        try:
+            # Get Python logging level
+            py_level = self.LEVEL_MAP.get(level, logging.INFO)
+
+            # Build log entry
+            log_data = {
+                'timestamp': datetime.now().isoformat(),
+                'level': level,
+                'message': message
+            }
+
+            if context:
+                log_data['context'] = context
+
+            if correlation_id:
+                log_data['correlation_id'] = correlation_id
+
+            # Log to Python logger
+            # For Phase 1, just log the message. Phase 2 will log full JSON
+            extra_info = []
+            if context:
+                extra_info.append(f"context={json.dumps(context)}")
+            if correlation_id:
+                extra_info.append(f"correlation_id={correlation_id}")
+
+            full_message = message
+            if extra_info:
+                full_message = f"{message} | {' | '.join(extra_info)}"
+
+            self.logger.log(py_level, full_message)
+
+            return {
+                'success': True,
+                'timestamp': log_data['timestamp'],
+                'level': level,
+                'message': message,
+                'destination': 'file+console'
+            }
+
+        except Exception as e:
+            # Logging should never crash the application
+            # Silently capture errors and return failure
+            return {
+                'success': False,
+                'error': str(e)
+            }
+
+    def should_log(self, condition: Any) -> bool:
+        """
+        Evaluate if logging should occur based on 'when' condition
+
+        Args:
+            condition: Evaluated condition value
+
+        Returns:
+            True if should log, False otherwise
+        """
+        # If no condition, always log
+        if condition is None:
+            return True
+
+        # Evaluate boolean condition
+        if isinstance(condition, bool):
+            return condition
+
+        # Truthy evaluation for other types
+        return bool(condition)

quantum/core/features/loops/src/__init__.py

@@ -0,0 +1,8 @@
+"""
+Loops Feature (q:loop)
+"""
+
+from .ast_node import LoopNode
+
+__all__ = ['LoopNode']
+__version__ = '1.0.0'

quantum/core/features/loops/src/ast_node.py

@@ -0,0 +1,60 @@
+"""
+AST Node for Loops (q:loop)
+"""
+
+from typing import Dict, Any, List
+
+# Import base class
+import sys
+from pathlib import Path
+from quantum.core.ast_nodes import QuantumNode
+
+
+class LoopNode(QuantumNode):
+    """Represents a <q:loop> with various types"""
+
+    def __init__(self, loop_type: str, var_name: str):
+        self.loop_type = loop_type    # range, array, list, object, query, while
+        self.var_name = var_name      # variable name for current item
+        self.index_name = None        # optional index variable
+        self.items = None             # data source expression
+        self.condition = None         # for while loops
+        self.from_value = None        # for range loops
+        self.to_value = None          # for range loops
+        self.step_value = 1           # for range loops
+        self.delimiter = ","          # for list loops
+        self.body: List[QuantumNode] = []  # statements inside loop
+
+    def add_statement(self, statement: QuantumNode):
+        self.body.append(statement)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "type": "loop",
+            "loop_type": self.loop_type,
+            "var_name": self.var_name,
+            "index_name": self.index_name,
+            "from_value": self.from_value,
+            "to_value": self.to_value,
+            "step_value": self.step_value,
+            "body_statements": len(self.body)
+        }
+
+    def validate(self) -> List[str]:
+        errors = []
+        if not self.var_name:
+            errors.append("Loop variable name is required")
+
+        if self.loop_type == 'range':
+            if not self.from_value:
+                errors.append("Range loop requires 'from' attribute")
+            if not self.to_value:
+                errors.append("Range loop requires 'to' attribute")
+        elif self.loop_type in ['array', 'list', 'object']:
+            if not self.items:
+                errors.append(f"{self.loop_type.title()} loop requires 'items' attribute")
+
+        for statement in self.body:
+            errors.extend(statement.validate())
+
+        return errors

quantum/core/features/query/src/query_validators.py

@@ -0,0 +1,20 @@
+"""
+Quantum Query Validators — re-export of the canonical implementation.
+
+This module used to hold a full 290-line COPY of QueryValidator. Nothing
+imported it, so it quietly drifted out of step with the module the runtime
+actually uses (quantum/runtime/query_validators.py) — and by the time the
+audit looked, the two copies of a SECURITY validator disagreed with each
+other. A stale duplicate of a validator is worse than no duplicate: whoever
+reads this one believes they are reading what runs.
+
+It re-exports instead of copying, so the two cannot diverge again. Import
+from quantum.runtime.query_validators directly in new code.
+"""
+
+from quantum.runtime.query_validators import (  # noqa: F401
+    QueryValidationError,
+    QueryValidator,
+)
+
+__all__ = ["QueryValidationError", "QueryValidator"]

quantum/core/features/state_management/src/__init__.py

@@ -0,0 +1,11 @@
+"""
+State Management Feature (q:set)
+
+Enables declaration and manipulation of component state variables
+with type safety, validation, and scope management.
+"""
+
+from .ast_node import SetNode
+
+__all__ = ['SetNode']
+__version__ = '1.0.0'

quantum/core/features/state_management/src/ast_node.py

@@ -0,0 +1,121 @@
+"""
+AST Node for State Management (q:set)
+
+This module contains the SetNode class, which represents the <q:set> tag
+for state management in Quantum Language.
+"""
+
+from typing import Dict, Any, List, Optional
+
+# Import base class from parent AST nodes
+import sys
+from pathlib import Path
+from quantum.core.ast_nodes import QuantumNode
+
+
+class SetNode(QuantumNode):
+    """Represents a <q:set> - State Management"""
+
+    def __init__(self, name: str):
+        # Obrigatórios
+        self.name = name
+
+        # Tipo e valor
+        self.type = "string"
+        self.value = None
+        self.default = None
+
+        # Validação
+        self.required = False
+        self.nullable = True
+        self.validate_rule = None  # Renomeado de 'validate' para não conflitar com o método
+        self.pattern = None
+        self.mask = None
+        self.range = None
+        self.enum = None
+        self.unique = None
+        self.min = None
+        self.max = None
+        self.minlength = None
+        self.maxlength = None
+
+        # Comportamento
+        self.scope = "local"
+        self.operation = "assign"
+        self.step = 1
+
+        # Para operações em collections
+        self.index = None
+        self.key = None
+        self.source = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "type": "set",
+            "name": self.name,
+            "value_type": self.type,
+            "value": self.value,
+            "default": self.default,
+            "scope": self.scope,
+            "operation": self.operation,
+            "required": self.required,
+            "nullable": self.nullable,
+            "validation": {
+                "validate": self.validate_rule,
+                "pattern": self.pattern,
+                "mask": self.mask,
+                "range": self.range,
+                "enum": self.enum,
+                "unique": self.unique,
+                "min": self.min,
+                "max": self.max,
+                "minlength": self.minlength,
+                "maxlength": self.maxlength
+            }
+        }
+        return result
+
+    def validate(self) -> List[str]:
+        errors = []
+
+        if not self.name:
+            errors.append("Set variable name is required")
+
+        # Validar tipo
+        # 'integer' was missing here even though SetExecutor._convert_to_type()
+        # already handles it (target_type in ("integer", "number")), and other
+        # AST nodes like AgentToolParamNode accept it — this rejected any
+        # q:set/q:param using type="integer" (test-query-loop.q,
+        # test-query-params.q, and every qg: sprite param in game_engine_2d).
+        valid_types = ['string', 'number', 'integer', 'decimal', 'boolean', 'date', 'datetime',
+                      'array', 'object', 'json', 'binary', 'null']
+        if self.type not in valid_types:
+            errors.append(f"Invalid type: {self.type}. Must be one of {valid_types}")
+
+        # Validar operação
+        valid_operations = ['assign', 'increment', 'decrement', 'add', 'multiply',
+                           'append', 'prepend', 'remove', 'removeAt', 'clear', 'sort',
+                           'reverse', 'unique', 'merge', 'setProperty', 'deleteProperty',
+                           'clone', 'uppercase', 'lowercase', 'trim', 'format']
+        if self.operation not in valid_operations:
+            errors.append(f"Invalid operation: {self.operation}")
+
+        # Validar valor obrigatório para assign
+        if self.operation == "assign" and not self.value and not self.default and self.required:
+            errors.append("Set value or default is required when required=true")
+
+        # Validar enum
+        if self.enum and self.value:
+            enum_values = [v.strip() for v in self.enum.split(',')]
+            if self.value not in enum_values:
+                errors.append(f"Value '{self.value}' not in enum: {enum_values}")
+
+        # Validar minlength/maxlength
+        if self.type == "string" and self.value:
+            if self.minlength and len(str(self.value)) < int(self.minlength):
+                errors.append(f"Value length {len(str(self.value))} is less than minlength {self.minlength}")
+            if self.maxlength and len(str(self.value)) > int(self.maxlength):
+                errors.append(f"Value length {len(str(self.value))} exceeds maxlength {self.maxlength}")
+
+        return errors
+

quantum/core/features/terminal_engine/src/__init__.py

@@ -0,0 +1,21 @@
+"""
+Terminal Engine - AST nodes and parser for the qt: namespace.
+"""
+
+from .ast_nodes import (
+    ScreenNode, PanelNode, LayoutNode, TableNode, ColumnNode,
+    TerminalInputNode, ButtonNode, MenuNode, OptionNode,
+    TextNode_Terminal, ProgressNode, TreeNode, TabsNode, TabNode,
+    LogNode_Terminal, HeaderNode_Terminal, FooterNode, StatusNode,
+    KeybindingNode, TimerNode_Terminal, ServiceNode, CssNode,
+    OnEventNode_Terminal, RawCodeNode_Terminal,
+)
+
+__all__ = [
+    'ScreenNode', 'PanelNode', 'LayoutNode', 'TableNode', 'ColumnNode',
+    'TerminalInputNode', 'ButtonNode', 'MenuNode', 'OptionNode',
+    'TextNode_Terminal', 'ProgressNode', 'TreeNode', 'TabsNode', 'TabNode',
+    'LogNode_Terminal', 'HeaderNode_Terminal', 'FooterNode', 'StatusNode',
+    'KeybindingNode', 'TimerNode_Terminal', 'ServiceNode', 'CssNode',
+    'OnEventNode_Terminal', 'RawCodeNode_Terminal',
+]