velm 0.1.2__py3-none-any.whl

velm/artisans/hover/perception.py

@@ -0,0 +1,236 @@
+# Path: scaffold/artisans/hover/perception.py
+# ------------------------------------------
+# LIF: INFINITY | ROLE: OMNISCIENT_STATE_ENGINE | RANK: SOVEREIGN
+# auth_code: Ω_PERCEPTION_TOTALITY_V9007_MAESTRO_ASCENDED
+
+import re
+from dataclasses import dataclass, field
+from typing import List, Optional, Set, Dict, Any, Tuple
+
+# --- THE GEOMETRIC CONSTANTS ---
+INDENT_SIZE = 4
+SIGIL_COMMENT = '#'
+SIGIL_JINJA_OPEN = '{{'
+SIGIL_JINJA_CLOSE = '}}'
+SIGIL_SOUL_OPS = {'::', '<<', '->', '+=', '-=', '~=', '^='}
+SIGIL_HEADERS = {'$$', 'let', 'def', 'const'}
+
+# [ASCENSION 2]: THE MAESTRO LIFECYCLE REGISTRY
+MAESTRO_EDICTS = {'post-run', 'pre-run', 'on-undo', 'on-heresy', 'weave', 'trait', 'use', 'contract'}
+
+
+@dataclass(frozen=True)
+class AuraContext:
+    """
+    =============================================================================
+    == THE VESSEL OF AURA (V-Ω-COGNITIVE-STATE-FINALIS)                        ==
+    =============================================================================
+    An immutable record of the logical spacetime surrounding a coordinate.
+    """
+    context_type: str  # 'form', 'will', 'logic', 'metadata', 'soul', 'void', 'polyglot'
+    parent_block: Optional[str] = None
+    ancestry: List[str] = field(default_factory=list)
+    depth: int = 0
+
+    # Flags of Essence
+    is_inside_jinja: bool = False
+    is_inside_string: bool = False
+    is_inside_comment: bool = False
+    is_inside_header: bool = False
+    is_inside_soul: bool = False
+    is_inside_vow: bool = False
+
+    # [ASCENSION 2]: Lifecycle Markers
+    maestro_edict: Optional[str] = None  # 'post-run', 'on-undo', etc.
+
+    active_language: str = "scaffold"
+    local_scope_vars: Set[str] = field(default_factory=set)
+    line_idx: int = 0
+    char_idx: int = 0
+
+
+class BlockAuraPerceiver:
+    """
+    =============================================================================
+    == THE AURA SEER (V-Ω-RECURSIVE-CONTEXT-ENGINE-ULTIMA)                     ==
+    =============================================================================
+    LIF: 10,000,000,000,000 | ROLE: OMNISCIENT_PERCEIVER
+    """
+
+    RE_BLOCK_START = re.compile(r'^\s*(@if|@for|@macro|@try|@task|%%|py:|rs:|go:|js:|sh:)\b')
+    RE_MAESTRO_FULL = re.compile(r'^\s*%%\s+([\w\-]+)')
+    RE_LOOP_VAR = re.compile(r'@for\s+([a-zA-Z_]\w*)\s+in')
+
+    @staticmethod
+    def scan(content: str, line_idx: int, char_idx: int = 0) -> AuraContext:
+        lines = content.splitlines()
+        if not lines or line_idx < 0 or line_idx >= len(lines):
+            return AuraContext(context_type='void')
+
+        raw_line = lines[line_idx]
+        stripped = raw_line.strip()
+
+        # =========================================================================
+        # == MOVEMENT I: COMMENT ABSOLUTISM (THE CURE)                           ==
+        # =========================================================================
+        # We perform a character-by-character scan to find the TRUE comment horizon.
+
+        in_string_char: Optional[str] = None
+        in_comment: bool = False
+        comment_start_idx = -1
+        jinja_depth = 0
+
+        cursor_in_string = False
+        cursor_in_comment = False
+        cursor_in_jinja = False
+
+        soul_op_idx = -1
+        vow_op_idx = -1
+
+        for i, char in enumerate(raw_line):
+            # 1. State Capture at Cursor
+            if i == char_idx:
+                cursor_in_string = (in_string_char is not None)
+                cursor_in_comment = in_comment
+                cursor_in_jinja = (jinja_depth > 0)
+
+            # 2. Comment Absolutism Gating
+            if in_comment: continue
+
+            # 3. String Physics
+            if in_string_char:
+                if char == in_string_char and (i == 0 or raw_line[i - 1] != '\\'):
+                    in_string_char = None
+            else:
+                if char in ('"', "'"):
+                    # Check for Triple Quotes
+                    if i + 2 < len(raw_line) and raw_line[i:i + 3] in ('"""', "'''"):
+                        # Simplified for line-perception, treat as standard string start
+                        in_string_char = char
+                    else:
+                        in_string_char = char
+
+                # 4. The Comment Horizon [ASCENSION 1]
+                elif char == SIGIL_COMMENT:
+                    in_comment = True
+                    comment_start_idx = i
+                    if char_idx >= i: cursor_in_comment = True
+
+                # 5. Jinja & Operators
+                elif char == '{' and i + 1 < len(raw_line) and raw_line[i + 1] == '{':
+                    jinja_depth += 1
+                elif char == '}' and i + 1 < len(raw_line) and raw_line[i + 1] == '}':
+                    jinja_depth = max(0, jinja_depth - 1)
+
+                if i + 1 < len(raw_line):
+                    chunk = raw_line[i:i + 2]
+                    if chunk in SIGIL_SOUL_OPS:
+                        if soul_op_idx == -1: soul_op_idx = i
+                    if chunk == '??':
+                        if vow_op_idx == -1: vow_op_idx = i
+
+        # Handle EOL Cursor
+        if char_idx >= len(raw_line):
+            cursor_in_comment = in_comment
+            cursor_in_string = (in_string_char is not None)
+
+        # [THE CURE]: If cursor is in comment, we RETURN IMMEDIATELY.
+        if cursor_in_comment:
+            is_pragma = raw_line[comment_start_idx:].strip().startswith('# @')
+            return AuraContext(
+                context_type='metadata_pragma' if is_pragma else 'metadata',
+                is_inside_comment=True,
+                line_idx=line_idx,
+                char_idx=char_idx
+            )
+
+        # =========================================================================
+        # == MOVEMENT II: CONTEXT TRIAGE                                         ==
+        # =========================================================================
+        is_inside_soul = (soul_op_idx != -1 and char_idx > soul_op_idx)
+        is_inside_vow = (vow_op_idx != -1 and char_idx > vow_op_idx)
+
+        context_type = 'form'
+        maestro_edict = None
+
+        # 1. MAESTRO AWARENESS [ASCENSION 2]
+        maestro_match = BlockAuraPerceiver.RE_MAESTRO_FULL.match(raw_line)
+        if maestro_match:
+            context_type = 'will'
+            maestro_edict = maestro_match.group(1) if maestro_match.group(1) in MAESTRO_EDICTS else None
+
+        elif is_inside_soul:
+            context_type = 'soul'
+        elif is_inside_vow or stripped.startswith(('>>', '!!')):
+            context_type = 'will'
+        elif stripped.startswith('@'):
+            context_type = 'logic'
+
+        is_definition = any(stripped.startswith(s) for s in SIGIL_HEADERS)
+
+        # =========================================================================
+        # == MOVEMENT III: ANCESTRAL DNA THREADING                               ==
+        # =========================================================================
+        raw_indent = len(raw_line) - len(raw_line.lstrip())
+        current_depth = raw_indent // INDENT_SIZE
+
+        parent_block = None
+        ancestry = []
+        active_language = "scaffold"
+        local_vars = set()
+
+        scan_indent = raw_indent
+        for i in range(line_idx - 1, -1, -1):
+            line = lines[i]
+            s_line = line.strip()
+            if not s_line or s_line.startswith(SIGIL_COMMENT): continue
+
+            l_indent = len(line) - len(s_line)
+
+            if l_indent < scan_indent:
+                scan_indent = l_indent
+
+                # Detect Maestro Parent
+                m_parent = BlockAuraPerceiver.RE_MAESTRO_FULL.match(s_line)
+                if m_parent:
+                    edict_name = m_parent.group(1)
+                    ancestry.insert(0, f"%% {edict_name}")
+                    if not parent_block: parent_block = f"%% {edict_name}"
+                    if not maestro_edict: maestro_edict = edict_name
+                    context_type = 'will'
+
+                # Detect Logic Parent
+                match = BlockAuraPerceiver.RE_BLOCK_START.match(s_line)
+                if match:
+                    b_type = match.group(1)
+                    ancestry.insert(0, b_type)
+                    if not parent_block: parent_block = b_type
+                    if b_type == "@for":
+                        lm = BlockAuraPerceiver.RE_LOOP_VAR.search(s_line)
+                        if lm: local_vars.add(lm.group(1))
+                    if b_type.endswith(':'): active_language = b_type.rstrip(':')
+
+                if any(m in s_line for m in ('>>', '??', '%% symphony')):
+                    if context_type == 'form': context_type = 'will'
+
+                if l_indent == 0: break
+
+        return AuraContext(
+            context_type=context_type,
+            parent_block=parent_block,
+            ancestry=ancestry,
+            depth=current_depth,
+            is_inside_jinja=cursor_in_jinja,
+            is_inside_string=cursor_in_string,
+            is_inside_comment=False,
+            is_inside_header=is_definition,
+            is_inside_soul=is_inside_soul,
+            is_inside_vow=is_inside_vow,
+            maestro_edict=maestro_edict,  # [WIRED]
+            active_language=active_language,
+            local_scope_vars=local_vars,
+            line_idx=line_idx,
+            char_idx=char_idx
+        )
+
+# === SCRIPTURE SEALED: THE MAESTRO IS MANIFEST ===

velm/artisans/ignore/artisan.py

@@ -0,0 +1,70 @@
+# Path: scaffold/artisans/ignore/artisan.py
+# -----------------------------------------
+
+import requests
+from pathlib import Path
+from typing import List, Set
+
+from ...core.artisan import BaseArtisan
+from ...interfaces.base import ScaffoldResult, Artifact
+from ...interfaces.requests import IgnoreRequest
+from ...help_registry import register_artisan
+from ...utils import atomic_write
+
+
+@register_artisan("ignore")
+class IgnoreArtisan(BaseArtisan[IgnoreRequest]):
+    """
+    =============================================================================
+    == THE GATEKEEPER OF AVERSION (V-Ω-GITIGNORE-IO)                           ==
+    =============================================================================
+    LIF: 10,000,000,000
+
+    Fetches and merges .gitignore templates from the gitignore.io API.
+    """
+
+    API_URL = "https://www.toptal.com/developers/gitignore/api"
+
+    def execute(self, request: IgnoreRequest) -> ScaffoldResult:
+        targets = [t.lower() for t in request.templates]
+        self.logger.info(f"Communing with the Gatekeeper for: [cyan]{', '.join(targets)}[/cyan]")
+
+        # 1. The Celestial Request
+        try:
+            api_query = ",".join(targets)
+            response = requests.get(f"{self.API_URL}/{api_query}", timeout=10)
+            response.raise_for_status()
+            content = response.text
+        except Exception as e:
+            return self.failure(f"Celestial Communion Failed: {e}")
+
+        # 2. The Gnostic Header
+        header = (
+            f"# Generated by Scaffold God-Engine\n"
+            f"# Templates: {', '.join(targets)}\n"
+            f"# -----------------------------------------------------------------------------\n"
+        )
+        final_content = header + content
+
+        # 3. The Inscription
+        target_path = self.project_root / ".gitignore"
+
+        if request.append and target_path.exists():
+            original = target_path.read_text(encoding='utf-8')
+            # Deduplication Check (Naive)
+            if f"# Templates: {', '.join(targets)}" in original:
+                return self.success("These rules are already inscribed.")
+
+            final_content = original + "\n\n" + final_content
+            action = "appended"
+        else:
+            if target_path.exists():
+                self.guarded_execution([target_path], request, context="ignore_overwrite")
+            action = "created"
+
+        atomic_write(target_path, final_content, self.logger, self.project_root)
+
+        return self.success(
+            f".gitignore {action} with rules for {', '.join(targets)}.",
+            artifacts=[Artifact(path=target_path, type="file", action="modified")]
+        )

velm/artisans/indexer/__init__.py

@@ -0,0 +1,3 @@
+# Path: artisans/indexer/__init__.py
+from .artisan import IndexerArtisan
+__all__ = ["IndexerArtisan"]

velm/artisans/indexer/artisan.py

@@ -0,0 +1,50 @@
+# Path: artisans/indexer/artisan.py
+# ---------------------------------
+
+import time
+from ...core.artisan import BaseArtisan
+from ...interfaces.base import ScaffoldResult
+from ...interfaces.requests import IndexRequest
+from .core.engine import IndexingEngine
+from .languages.factory import LanguageFactory
+
+
+class IndexerArtisan(BaseArtisan[IndexRequest]):
+    """
+    =============================================================================
+    == THE INDEXER ARTISAN (V-Ω-POLYGLOT-SWARM-V2)                             ==
+    =============================================================================
+    LIF: 10,000,000,000 | ROLE: KNOWLEDGE_INGESTOR
+    """
+
+    def execute(self, request: IndexRequest) -> ScaffoldResult:
+        start_time = time.monotonic()
+
+        # 1. Acquire Targets
+        if not self.engine.cortex:
+            return self.failure("Cortex not manifest.")
+
+        memory = self.engine.cortex.perceive()
+
+        # Filter for unindexed files that we support
+        files_to_index = [
+            f for f in memory.inventory
+            if (request.force or not self.engine.cortex.is_indexed(f))
+               and LanguageFactory.get_parser(f) is not None
+        ]
+
+        if not files_to_index:
+            return self.success("Index Up-to-Date.")
+
+        self.logger.info(f"Igniting Polyglot Swarm: {len(files_to_index)} scriptures identified.")
+
+        # 2. Ignite Swarm
+        engine = IndexingEngine(self.engine.cortex)
+        stats = engine.run_swarm(files_to_index)
+
+        stats.duration_ms = (time.monotonic() - start_time) * 1000
+
+        return self.success(
+            f"Indexing Complete. {stats.total_symbols} symbols found.",
+            data=stats.__dict__
+        )

velm/artisans/indexer/core/contracts.py

@@ -0,0 +1,14 @@
+# Path: artisans/indexer/core/contracts.py
+from dataclasses import dataclass
+from typing import List, Optional
+from pathlib import Path
+from ....core.cortex.contracts import SymbolKind
+
+
+@dataclass
+class IndexingStats:
+    total_files: int = 0
+    total_symbols: int = 0
+    duration_ms: float = 0.0
+    errors: int = 0
+

velm/artisans/indexer/core/engine.py

@@ -0,0 +1,51 @@
+# Path: artisans/indexer/core/engine.py
+# -------------------------------------
+
+import concurrent.futures
+from pathlib import Path
+from typing import List, Any
+from .contracts import IndexingStats
+from ..languages.factory import LanguageFactory
+
+
+class IndexingEngine:
+    """
+    =============================================================================
+    == THE SWARM ENGINE (V-Ω-PARALLEL-PROCESSOR)                               ==
+    =============================================================================
+    Manages the thread pool and dispatches files to their respective parsers.
+    """
+
+    def __init__(self, cortex):
+        self.cortex = cortex
+
+    def run_swarm(self, files: List[Path]) -> IndexingStats:
+        stats = IndexingStats(total_files=len(files))
+
+        # Max 8 workers to balance GIL vs IO
+        with concurrent.futures.ThreadPoolExecutor(max_workers=8) as executor:
+            future_to_path = {
+                executor.submit(self._process_file, f): f
+                for f in files
+            }
+
+            for future in concurrent.futures.as_completed(future_to_path):
+                path = future_to_path[future]
+                try:
+                    symbols = future.result()
+                    if symbols:
+                        self.cortex.memorize_symbols(path, symbols)
+                        stats.total_symbols += len(symbols)
+                except Exception:
+                    stats.errors += 1
+
+        return stats
+
+    def _process_file(self, path: Path):
+        try:
+            parser = LanguageFactory.get_parser(path)
+            if not parser: return []
+            content = path.read_text(encoding='utf-8', errors='ignore')
+            return parser.parse(content, path)
+        except Exception:
+            return []

velm/artisans/indexer/languages/base.py

@@ -0,0 +1,33 @@
+# Path: artisans/indexer/languages/base.py
+import re
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import List, Pattern
+from ....core.cortex.contracts import SymbolEntry, SymbolKind
+
+
+class BaseLanguageParser(ABC):
+    """
+    The Immutable Contract for Language Parsing.
+    """
+
+    @abstractmethod
+    def parse(self, content: str, path: Path) -> List[SymbolEntry]:
+        pass
+
+    def _extract(self, pattern: Pattern, content: str, path: Path, kind: SymbolKind) -> List[SymbolEntry]:
+        """High-speed regex extraction helper."""
+        results = []
+        for match in pattern.finditer(content):
+            name = match.group(1)
+            # O(N) line counting is acceptable for indexing speed vs AST overhead
+            line_num = content.count('\n', 0, match.start())
+
+            results.append(SymbolEntry(
+                name=name,
+                path=path,
+                kind=kind,
+                line=line_num,
+                column=match.start() - content.rfind('\n', 0, match.start()) - 1
+            ))
+        return results

velm/artisans/indexer/languages/factory.py

@@ -0,0 +1,25 @@
+# Path: artisans/indexer/languages/factory.py
+from typing import Optional, Dict
+from pathlib import Path
+from .base import BaseLanguageParser
+from .python import PythonParser
+from .javascript import JavaScriptParser
+from .go import GoParser
+from .rust import RustParser
+from .java import JavaParser
+from .ruby import RubyParser
+
+class LanguageFactory:
+    _REGISTRY: Dict[str, BaseLanguageParser] = {
+        '.py': PythonParser(),
+        '.js': JavaScriptParser(), '.jsx': JavaScriptParser(),
+        '.ts': JavaScriptParser(), '.tsx': JavaScriptParser(),
+        '.go': GoParser(),
+        '.rs': RustParser(),
+        '.java': JavaParser(),
+        '.rb': RubyParser()
+    }
+
+    @staticmethod
+    def get_parser(path: Path) -> Optional[BaseLanguageParser]:
+        return LanguageFactory._REGISTRY.get(path.suffix.lower())

velm/artisans/indexer/languages/go.py

@@ -0,0 +1,13 @@
+import re
+from .base import BaseLanguageParser
+from ....core.cortex.contracts import SymbolKind
+
+class GoParser(BaseLanguageParser):
+    RE_FUNC = re.compile(r'^func\s+([a-zA-Z0-9_]+)\(', re.MULTILINE)
+    RE_TYPE = re.compile(r'^type\s+([a-zA-Z0-9_]+)\s+(?:struct|interface)', re.MULTILINE)
+
+    def parse(self, content, path):
+        return (
+            self._extract(self.RE_FUNC, content, path, SymbolKind.FUNCTION) +
+            self._extract(self.RE_TYPE, content, path, SymbolKind.CLASS)
+        )

velm/artisans/indexer/languages/java.py

@@ -0,0 +1,13 @@
+import re
+from .base import BaseLanguageParser
+from ....core.cortex.contracts import SymbolKind
+
+class JavaParser(BaseLanguageParser):
+    RE_CLASS = re.compile(r'\bclass\s+([a-zA-Z0-9_]+)', re.MULTILINE)
+    RE_INTERFACE = re.compile(r'\binterface\s+([a-zA-Z0-9_]+)', re.MULTILINE)
+
+    def parse(self, content, path):
+        return (
+            self._extract(self.RE_CLASS, content, path, SymbolKind.CLASS) +
+            self._extract(self.RE_INTERFACE, content, path, SymbolKind.INTERFACE)
+        )

velm/artisans/indexer/languages/javascript.py

@@ -0,0 +1,17 @@
+import re
+from .base import BaseLanguageParser
+from ....core.cortex.contracts import SymbolKind
+
+class JavaScriptParser(BaseLanguageParser):
+    RE_CLASS = re.compile(r'class\s+([a-zA-Z0-9_]+)', re.MULTILINE)
+    RE_FUNC = re.compile(r'function\s+([a-zA-Z0-9_]+)', re.MULTILINE)
+    RE_CONST_FUNC = re.compile(r'(?:const|let|var)\s+([a-zA-Z0-9_]+)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[a-zA-Z0-9_]+)\s*=>', re.MULTILINE)
+    RE_INTERFACE = re.compile(r'interface\s+([a-zA-Z0-9_]+)', re.MULTILINE)
+
+    def parse(self, content, path):
+        return (
+            self._extract(self.RE_CLASS, content, path, SymbolKind.CLASS) +
+            self._extract(self.RE_FUNC, content, path, SymbolKind.FUNCTION) +
+            self._extract(self.RE_CONST_FUNC, content, path, SymbolKind.FUNCTION) +
+            self._extract(self.RE_INTERFACE, content, path, SymbolKind.INTERFACE)
+        )

velm/artisans/indexer/languages/python.py

@@ -0,0 +1,14 @@
+import re
+from .base import BaseLanguageParser
+from ....core.cortex.contracts import SymbolKind
+
+
+class PythonParser(BaseLanguageParser):
+    RE_CLASS = re.compile(r'^class\s+([a-zA-Z0-9_]+)', re.MULTILINE)
+    RE_FUNC = re.compile(r'^def\s+([a-zA-Z0-9_]+)', re.MULTILINE)
+
+    def parse(self, content, path):
+        return (
+                self._extract(self.RE_CLASS, content, path, SymbolKind.CLASS) +
+                self._extract(self.RE_FUNC, content, path, SymbolKind.FUNCTION)
+        )

velm/artisans/indexer/languages/ruby.py

@@ -0,0 +1,13 @@
+import re
+from .base import BaseLanguageParser
+from ....core.cortex.contracts import SymbolKind
+
+class RubyParser(BaseLanguageParser):
+    RE_CLASS = re.compile(r'^\s*class\s+([a-zA-Z0-9_]+)', re.MULTILINE)
+    RE_DEF = re.compile(r'^\s*def\s+([a-zA-Z0-9_]+)', re.MULTILINE)
+
+    def parse(self, content, path):
+        return (
+            self._extract(self.RE_CLASS, content, path, SymbolKind.CLASS) +
+            self._extract(self.RE_DEF, content, path, SymbolKind.FUNCTION)
+        )

velm/artisans/indexer/languages/rust.py

@@ -0,0 +1,15 @@
+import re
+from .base import BaseLanguageParser
+from ....core.cortex.contracts import SymbolKind
+
+class RustParser(BaseLanguageParser):
+    RE_FN = re.compile(r'\bfn\s+([a-zA-Z0-9_]+)', re.MULTILINE)
+    RE_STRUCT = re.compile(r'\bstruct\s+([a-zA-Z0-9_]+)', re.MULTILINE)
+    RE_TRAIT = re.compile(r'\btrait\s+([a-zA-Z0-9_]+)', re.MULTILINE)
+
+    def parse(self, content, path):
+        return (
+            self._extract(self.RE_FN, content, path, SymbolKind.FUNCTION) +
+            self._extract(self.RE_STRUCT, content, path, SymbolKind.CLASS) +
+            self._extract(self.RE_TRAIT, content, path, SymbolKind.INTERFACE)
+        )

velm/artisans/init/__init__.py

@@ -0,0 +1,12 @@
+# Path: scaffold/artisans/init/__init__.py
+# ----------------------------------------
+"""
+=================================================================================
+== THE SANCTUM OF INCEPTION (V-Ω-MODULAR-ASCENDED)                             ==
+=================================================================================
+This sanctum houses the God-Engine of Inception. It unifies the Manual Creator,
+the Genesis Bridge, and the Conductor into a single, sovereign artisan.
+"""
+from .artisan import InitArtisan
+
+__all__ = ["InitArtisan"]