@voodocs/cli 0.1.0

package/lib/darkarts/core/loader.py

@@ -0,0 +1,231 @@
+"""
+Plugin loader for discovering and loading plugins.
+"""
+
+import importlib
+import importlib.util
+import os
+import sys
+from pathlib import Path
+from typing import List, Optional
+from .plugin import DarkArtsPlugin, PluginError
+from .registry import PluginRegistry
+
+
+class PluginLoader:
+    """Load plugins from various sources."""
+    
+    def __init__(self, registry: PluginRegistry):
+        """
+        Initialize the loader.
+        
+        Args:
+            registry: The plugin registry to register loaded plugins
+        """
+        self.registry = registry
+    
+    def load_from_module(self, module_path: str, class_name: Optional[str] = None) -> DarkArtsPlugin:
+        """
+        Load plugin from Python module.
+        
+        Args:
+            module_path: Python module path (e.g., 'darkarts.plugins.math')
+            class_name: Optional class name (if not provided, looks for DarkArtsPlugin subclass)
+            
+        Returns:
+            The loaded plugin instance
+            
+        Raises:
+            PluginError: If loading fails
+        """
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError as e:
+            raise PluginError(f"Failed to import module '{module_path}': {e}")
+        
+        if class_name:
+            if not hasattr(module, class_name):
+                raise PluginError(f"Module '{module_path}' has no class '{class_name}'")
+            plugin_class = getattr(module, class_name)
+        else:
+            # Find DarkArtsPlugin subclass
+            plugin_class = None
+            for attr_name in dir(module):
+                attr = getattr(module, attr_name)
+                if (isinstance(attr, type) and 
+                    issubclass(attr, DarkArtsPlugin) and 
+                    attr is not DarkArtsPlugin):
+                    plugin_class = attr
+                    break
+            
+            if not plugin_class:
+                raise PluginError(f"No DarkArtsPlugin subclass found in '{module_path}'")
+        
+        try:
+            plugin = plugin_class()
+        except Exception as e:
+            raise PluginError(f"Failed to instantiate plugin: {e}")
+        
+        return plugin
+    
+    def load_from_file(self, file_path: str, class_name: Optional[str] = None) -> DarkArtsPlugin:
+        """
+        Load plugin from Python file.
+        
+        Args:
+            file_path: Path to Python file
+            class_name: Optional class name
+            
+        Returns:
+            The loaded plugin instance
+            
+        Raises:
+            PluginError: If loading fails
+        """
+        file_path = Path(file_path).resolve()
+        
+        if not file_path.exists():
+            raise PluginError(f"File not found: {file_path}")
+        
+        if not file_path.suffix == '.py':
+            raise PluginError(f"File must be a Python file: {file_path}")
+        
+        # Load module from file
+        module_name = file_path.stem
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+        
+        if not spec or not spec.loader:
+            raise PluginError(f"Failed to load spec from file: {file_path}")
+        
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        
+        try:
+            spec.loader.exec_module(module)
+        except Exception as e:
+            raise PluginError(f"Failed to execute module: {e}")
+        
+        # Find and instantiate plugin class
+        if class_name:
+            if not hasattr(module, class_name):
+                raise PluginError(f"Module has no class '{class_name}'")
+            plugin_class = getattr(module, class_name)
+        else:
+            plugin_class = None
+            for attr_name in dir(module):
+                attr = getattr(module, attr_name)
+                if (isinstance(attr, type) and 
+                    issubclass(attr, DarkArtsPlugin) and 
+                    attr is not DarkArtsPlugin):
+                    plugin_class = attr
+                    break
+            
+            if not plugin_class:
+                raise PluginError(f"No DarkArtsPlugin subclass found in file")
+        
+        try:
+            plugin = plugin_class()
+        except Exception as e:
+            raise PluginError(f"Failed to instantiate plugin: {e}")
+        
+        return plugin
+    
+    def load_from_directory(self, directory: str) -> List[DarkArtsPlugin]:
+        """
+        Load all plugins from a directory.
+        
+        Args:
+            directory: Path to directory containing plugin files
+            
+        Returns:
+            List of loaded plugins
+        """
+        directory = Path(directory).resolve()
+        
+        if not directory.exists():
+            raise PluginError(f"Directory not found: {directory}")
+        
+        if not directory.is_dir():
+            raise PluginError(f"Not a directory: {directory}")
+        
+        plugins = []
+        
+        for file_path in directory.glob("*.py"):
+            if file_path.name.startswith("_"):
+                continue  # Skip __init__.py and private files
+            
+            try:
+                plugin = self.load_from_file(str(file_path))
+                plugins.append(plugin)
+            except PluginError as e:
+                print(f"Warning: Failed to load plugin from {file_path}: {e}")
+                continue
+        
+        return plugins
+    
+    def load_builtin_plugins(self) -> List[DarkArtsPlugin]:
+        """
+        Load built-in plugins.
+        
+        Returns:
+            List of loaded built-in plugins
+        """
+        plugins = []
+        
+        # Try to load math plugin
+        try:
+            plugin = self.load_from_module("darkarts.plugins.math", "MathPlugin")
+            plugins.append(plugin)
+        except PluginError:
+            pass  # Math plugin not yet implemented
+        
+        # Try to load voodocs plugin
+        try:
+            plugin = self.load_from_module("darkarts.plugins.voodocs", "VooDocsPlugin")
+            plugins.append(plugin)
+        except PluginError:
+            pass  # VooDocs plugin not yet implemented
+        
+        return plugins
+    
+    def load_and_register(self, source: str, source_type: str = "module") -> DarkArtsPlugin:
+        """
+        Load a plugin and register it.
+        
+        Args:
+            source: Module path, file path, or directory path
+            source_type: Type of source ('module', 'file', or 'directory')
+            
+        Returns:
+            The loaded plugin (or list of plugins for directory)
+            
+        Raises:
+            PluginError: If loading or registration fails
+        """
+        if source_type == "module":
+            plugin = self.load_from_module(source)
+            self.registry.register(plugin)
+            return plugin
+        elif source_type == "file":
+            plugin = self.load_from_file(source)
+            self.registry.register(plugin)
+            return plugin
+        elif source_type == "directory":
+            plugins = self.load_from_directory(source)
+            for plugin in plugins:
+                self.registry.register(plugin)
+            return plugins
+        else:
+            raise PluginError(f"Unknown source type: {source_type}")
+    
+    def load_and_register_builtin(self) -> List[DarkArtsPlugin]:
+        """
+        Load and register all built-in plugins.
+        
+        Returns:
+            List of loaded plugins
+        """
+        plugins = self.load_builtin_plugins()
+        for plugin in plugins:
+            self.registry.register(plugin)
+        return plugins

package/lib/darkarts/core/plugin.py

@@ -0,0 +1,215 @@
+"""
+Core plugin system for DarkArts.
+
+This module defines the base classes and interfaces for the DarkArts plugin system.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+from enum import Enum
+
+
+class PluginCapability(Enum):
+    """Standard plugin capabilities."""
+    PARSE = "parse"
+    ANALYZE = "analyze"
+    EXECUTE = "execute"
+    EXPLAIN = "explain"
+    LEARN = "learn"
+    MULTI_STEP = "multi_step"
+
+
+@dataclass
+class PluginMetadata:
+    """Metadata about a plugin."""
+    name: str
+    version: str
+    description: str
+    author: str
+    dependencies: List[str] = field(default_factory=list)
+    capabilities: List[str] = field(default_factory=list)
+    
+    def has_capability(self, capability: str) -> bool:
+        """Check if plugin has a specific capability."""
+        return capability in self.capabilities
+
+
+@dataclass
+class PluginInput:
+    """Input to a plugin."""
+    content: str
+    context: Dict[str, Any] = field(default_factory=dict)
+    options: Dict[str, Any] = field(default_factory=dict)
+    
+    def get_option(self, key: str, default: Any = None) -> Any:
+        """Get an option value with default."""
+        return self.options.get(key, default)
+
+
+@dataclass
+class PluginOutput:
+    """Output from a plugin."""
+    success: bool
+    result: Any
+    explanation: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    error: Optional[str] = None
+    steps: List[Dict[str, Any]] = field(default_factory=list)
+    
+    def add_step(self, name: str, description: str, result: Any = None):
+        """Add an execution step."""
+        self.steps.append({
+            "name": name,
+            "description": description,
+            "result": result,
+        })
+    
+    def add_metadata(self, key: str, value: Any):
+        """Add metadata."""
+        self.metadata[key] = value
+
+
+class DarkArtsPlugin(ABC):
+    """Base class for all DarkArts plugins."""
+    
+    def __init__(self):
+        """Initialize the plugin."""
+        self._learning_enabled = True
+    
+    @property
+    @abstractmethod
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata."""
+        pass
+    
+    @abstractmethod
+    def parse(self, input: PluginInput) -> Any:
+        """
+        Parse domain-specific input into internal representation.
+        
+        Args:
+            input: The input to parse
+            
+        Returns:
+            Parsed representation (domain-specific)
+            
+        Raises:
+            ParseError: If parsing fails
+        """
+        pass
+    
+    @abstractmethod
+    def analyze(self, parsed: Any) -> Dict[str, Any]:
+        """
+        Analyze the parsed input for complexity, requirements, etc.
+        
+        Args:
+            parsed: The parsed representation
+            
+        Returns:
+            Analysis results as a dictionary
+        """
+        pass
+    
+    @abstractmethod
+    def execute(self, parsed: Any, analysis: Dict[str, Any]) -> PluginOutput:
+        """
+        Execute the main processing logic.
+        
+        Args:
+            parsed: The parsed representation
+            analysis: Analysis results from analyze()
+            
+        Returns:
+            Plugin output with results
+        """
+        pass
+    
+    def explain(self, output: PluginOutput, level: str = "student") -> str:
+        """
+        Generate natural language explanation (optional override).
+        
+        Args:
+            output: The plugin output to explain
+            level: Explanation level (student, teacher, expert)
+            
+        Returns:
+            Natural language explanation
+        """
+        if output.explanation:
+            return output.explanation
+        
+        if not output.success:
+            return f"Execution failed: {output.error}"
+        
+        return f"Result: {output.result}"
+    
+    def learn(self, input: PluginInput, output: PluginOutput) -> None:
+        """
+        Learn from this execution (optional override).
+        
+        Args:
+            input: The input that was processed
+            output: The output that was generated
+        """
+        pass
+    
+    def enable_learning(self, enabled: bool = True):
+        """Enable or disable learning for this plugin."""
+        self._learning_enabled = enabled
+    
+    def is_learning_enabled(self) -> bool:
+        """Check if learning is enabled."""
+        return self._learning_enabled
+    
+    def validate_input(self, input: PluginInput) -> bool:
+        """
+        Validate input before processing (optional override).
+        
+        Args:
+            input: The input to validate
+            
+        Returns:
+            True if valid, False otherwise
+        """
+        return bool(input.content and input.content.strip())
+    
+    def preprocess(self, input: PluginInput) -> PluginInput:
+        """
+        Preprocess input before parsing (optional override).
+        
+        Args:
+            input: The input to preprocess
+            
+        Returns:
+            Preprocessed input
+        """
+        return input
+    
+    def postprocess(self, output: PluginOutput) -> PluginOutput:
+        """
+        Postprocess output before returning (optional override).
+        
+        Args:
+            output: The output to postprocess
+            
+        Returns:
+            Postprocessed output
+        """
+        return output
+
+
+class ParseError(Exception):
+    """Exception raised when parsing fails."""
+    pass
+
+
+class ExecutionError(Exception):
+    """Exception raised when execution fails."""
+    pass
+
+
+class PluginError(Exception):
+    """Base exception for plugin-related errors."""
+    pass

package/lib/darkarts/core/registry.py

@@ -0,0 +1,146 @@
+"""
+Plugin registry for managing and discovering plugins.
+"""
+
+from typing import Dict, List, Optional
+from .plugin import DarkArtsPlugin, PluginMetadata, PluginError
+
+
+class PluginRegistry:
+    """Registry for managing plugins."""
+    
+    def __init__(self):
+        """Initialize the registry."""
+        self._plugins: Dict[str, DarkArtsPlugin] = {}
+        self._metadata: Dict[str, PluginMetadata] = {}
+    
+    def register(self, plugin: DarkArtsPlugin) -> None:
+        """
+        Register a plugin.
+        
+        Args:
+            plugin: The plugin to register
+            
+        Raises:
+            PluginError: If plugin with same name already registered
+        """
+        metadata = plugin.metadata
+        
+        if metadata.name in self._plugins:
+            raise PluginError(f"Plugin '{metadata.name}' is already registered")
+        
+        # Check dependencies
+        for dep in metadata.dependencies:
+            if dep not in self._plugins:
+                raise PluginError(
+                    f"Plugin '{metadata.name}' depends on '{dep}' which is not registered"
+                )
+        
+        self._plugins[metadata.name] = plugin
+        self._metadata[metadata.name] = metadata
+    
+    def unregister(self, name: str) -> None:
+        """
+        Unregister a plugin.
+        
+        Args:
+            name: Name of the plugin to unregister
+        """
+        if name in self._plugins:
+            del self._plugins[name]
+            del self._metadata[name]
+    
+    def get(self, name: str) -> Optional[DarkArtsPlugin]:
+        """
+        Get a plugin by name.
+        
+        Args:
+            name: Name of the plugin
+            
+        Returns:
+            The plugin, or None if not found
+        """
+        return self._plugins.get(name)
+    
+    def get_metadata(self, name: str) -> Optional[PluginMetadata]:
+        """
+        Get plugin metadata by name.
+        
+        Args:
+            name: Name of the plugin
+            
+        Returns:
+            The plugin metadata, or None if not found
+        """
+        return self._metadata.get(name)
+    
+    def list(self) -> List[PluginMetadata]:
+        """
+        List all registered plugins.
+        
+        Returns:
+            List of plugin metadata
+        """
+        return list(self._metadata.values())
+    
+    def list_names(self) -> List[str]:
+        """
+        List all registered plugin names.
+        
+        Returns:
+            List of plugin names
+        """
+        return list(self._plugins.keys())
+    
+    def has_plugin(self, name: str) -> bool:
+        """
+        Check if a plugin is registered.
+        
+        Args:
+            name: Name of the plugin
+            
+        Returns:
+            True if registered, False otherwise
+        """
+        return name in self._plugins
+    
+    def has_capability(self, capability: str) -> List[str]:
+        """
+        Find plugins with a specific capability.
+        
+        Args:
+            capability: The capability to search for
+            
+        Returns:
+            List of plugin names with that capability
+        """
+        return [
+            name for name, meta in self._metadata.items()
+            if capability in meta.capabilities
+        ]
+    
+    def clear(self) -> None:
+        """Clear all registered plugins."""
+        self._plugins.clear()
+        self._metadata.clear()
+    
+    def __len__(self) -> int:
+        """Return number of registered plugins."""
+        return len(self._plugins)
+    
+    def __contains__(self, name: str) -> bool:
+        """Check if plugin is registered."""
+        return name in self._plugins
+    
+    def __iter__(self):
+        """Iterate over plugin names."""
+        return iter(self._plugins.keys())
+
+
+# Global registry instance
+_global_registry = PluginRegistry()
+
+
+def get_global_registry() -> PluginRegistry:
+    """Get the global plugin registry."""
+    return _global_registry

package/lib/darkarts/exceptions.py

@@ -0,0 +1,51 @@
+"""
+VooDocs Custom Exceptions
+
+Provides specific exception types for better error handling and user feedback.
+"""
+
+
+class VooDocsError(Exception):
+    """Base exception for all VooDocs errors."""
+    pass
+
+
+class ParserError(VooDocsError):
+    """Raised when a parser encounters an error."""
+    pass
+
+
+class ParserNotBuiltError(ParserError):
+    """Raised when the TypeScript parser hasn't been built."""
+    
+    def __init__(self, parser_name="TypeScript"):
+        self.parser_name = parser_name
+        super().__init__(
+            f"{parser_name} parser not built. "
+            f"Run: cd lib/darkarts/parsers/typescript && npm install && npm run build"
+        )
+
+
+class AnnotationError(VooDocsError):
+    """Raised when annotation parsing fails."""
+    pass
+
+
+class InvalidAnnotationError(AnnotationError):
+    """Raised when an annotation has invalid syntax or structure."""
+    pass
+
+
+class GeneratorError(VooDocsError):
+    """Raised when a generator encounters an error."""
+    pass
+
+
+class ConfigurationError(VooDocsError):
+    """Raised when configuration is invalid or missing."""
+    pass
+
+
+class FileNotFoundError(VooDocsError):
+    """Raised when a required file is not found."""
+    pass

package/lib/darkarts/parsers/typescript/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * CLI wrapper for the TypeScript annotation parser
+ *
+ * Usage: darkarts-ts-parser <file_path>
+ * Output: JSON to stdout
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/lib/darkarts/parsers/typescript/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;GAKG"}