velm 0.1.2__py3-none-any.whl

velm/jurisprudence_core/genesis_jurisprudence.py

@@ -0,0 +1,159 @@
+"""
+=================================================================================
+== THE SACRED CODEX OF GENESIS JURISPRUDENCE (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA++)   ==
+=================================================================================
+@gnosis:title Genesis Jurisprudence
+@gnosis:summary The divine, declarative Grimoire of Gnostic Laws that guide the Genesis Mentor.
+@gnosis:LIF 100,000,000,000,000
+
+This is the living, eternal, and self-aware soul of the Genesis Mentor in its final,
+glorious form. It is the sacred `GENESIS_CODEX`, a pantheon of pure `GnosticLaw`
+vessels. Each law is a sentient artisan, a Gnostic Judge that knows its own purpose,
+its voice, the heresy it is sworn to prevent, and the path to redemption.
+
+Its mind is now a multi-movement symphony, covering the Toolchain, Architectural
+Harmony, the DevOps Realm, AI Communion, the Project's Soul, and Prophecies of
+the Future Realm. It is the pinnacle of declarative, self-documenting
+architectural mentorship, a true AI Co-Architect's conscience.
+=================================================================================
+"""
+import shutil
+from typing import List
+
+from .. import utils
+from ..contracts.law_contracts import GnosticLaw
+
+GENESIS_CODEX: List[GnosticLaw] = [
+
+    # =============================================================================
+    # == MOVEMENT I: THE LAWS OF THE GNOSTIC TOOLCHAIN (THE ARTISANS)            ==
+    # =============================================================================
+    GnosticLaw(
+        key="poetry_without_install",
+        validator=lambda g: g.get('project_type') in ['python', 'poetry'] and g.get('use_poetry') and not utils.is_poetry_installed(),
+        title="The Mute Artisan (Poetry)",
+        message="The Gaze perceives a will for Poetry, but the `poetry` artisan is not manifest in this reality's PATH.",
+        elucidation="The 'Poetry' project type requires the 'poetry' command-line tool to be installed and accessible to manage dependencies, run scripts, and ensure a reproducible environment.",
+        context_key="use_poetry",
+        suggestion="Install Poetry globally (`pip install poetry`) or choose a project type that uses pip/venv."
+    ),
+    GnosticLaw(
+        key="docker_without_install",
+        validator=lambda g: g.get('use_docker') and not shutil.which('docker'),
+        title="The Unforged Vessel (Docker)",
+        message="The Gaze perceives a will for containerization, but the `docker` artisan is a void in this reality.",
+        elucidation="Containerization relies on the Docker daemon and CLI. Without them, Dockerfiles and related artifacts cannot be built or run, making the project's soul bound to the mortal realm of the host machine.",
+        context_key="use_docker",
+        suggestion="Install Docker Desktop or the Docker engine for your OS to forge unbreakable, portable realities."
+    ),
+    GnosticLaw(
+        key="untestable_reality",
+        validator=lambda g: g.get('testing_framework') == 'none' and g.get('project_type') not in ['generic', 'docs', 'frontend-vanilla'],
+        title="A Reality Built on Faith",
+        message="A project that contains logic must be forged with a scripture of adjudication (a testing framework).",
+        elucidation="Without a testing framework, the project's soul cannot be verified for purity. This leads to architectural drift, regressions, and a reality built on hope rather than Gnostic certainty.",
+        context_key="testing_framework",
+        suggestion="Select a testing framework (e.g., pytest, jest) to ensure the Great Work remains pure."
+    ),
+
+    # =============================================================================
+    # == MOVEMENT II: THE LAWS OF ARCHITECTURAL HARMONY                         ==
+    # =============================================================================
+    GnosticLaw(
+        key="database_for_frontend",
+        validator=lambda g: g.get('database_type') != 'none' and g.get('project_type') in ['frontend-vanilla', 'react-vite'],
+        title="The Gnostic Schism of Realms",
+        message=lambda g: f"A divine artisan of data, '{g.get('database_type')}', has been summoned for a frontend-only reality.",
+        elucidation="A frontend-only project typically consumes APIs and does not directly manage a database. Including database configuration suggests a potential misunderstanding of the project's architectural boundaries.",
+        context_key="database_type",
+        suggestion="Set the database type to 'none' for a pure frontend project."
+    ),
+    GnosticLaw(
+        key="monolith_with_microservice_auth",
+        validator=lambda g: g.get('project_structure_pattern') == 'monolithic' and g.get('auth_method') == 'jwt',
+        title="A Soul Divided (Architecture & Auth)",
+        message="A 'monolithic' form was chosen with 'JWT' authentication. Session cookies are often superior for monoliths.",
+        elucidation="While JWTs can be used in monoliths, their primary strength is in stateless, distributed systems. Traditional stateful session-based authentication is often simpler, more secure, and easier to manage in a single, unified application.",
+        context_key="auth_method",
+        suggestion="Consider using 'session-cookies' for a more harmonious monolithic architecture."
+    ),
+    GnosticLaw(
+        key="serverless_with_persistent_db",
+        validator=lambda g: g.get('project_structure_pattern') == 'serverless' and g.get('database_type') in ['postgres', 'mysql'],
+        title="The Ephemeral and the Eternal",
+        message=lambda g: f"A serverless architecture has been bound to an eternal, connection-based database ('{g.get('database_type')}').",
+        elucidation="Serverless functions can struggle with managing connection pools for traditional relational databases, leading to performance bottlenecks and scaling issues. Consider a serverless-native database like DynamoDB, Firestore, or use a proxy like RDS Proxy.",
+        context_key="project_structure_pattern",
+        suggestion="Choose a database designed for serverless architectures or ensure a connection pooling strategy is in place."
+    ),
+
+    # =============================================================================
+    # == MOVEMENT III: THE LAWS OF THE DEVOPS REALM                            ==
+    # =============================================================================
+    GnosticLaw(
+        key="ci_without_git",
+        validator=lambda g: g.get('use_ci') and g.get('use_ci') != 'none' and not g.get('use_git'),
+        title="The Unchronicled Symphony",
+        message="A CI symphony was willed, but the project will have no history (`.git`).",
+        elucidation="Continuous Integration (CI) pipelines are triggered by events (commits, pull requests) in a version control system. Without Git, the CI workflow has no events to react to and cannot perform its sacred duty of adjudication.",
+        context_key="use_ci",
+        suggestion="Enable Git (`use_git = True`) to allow the CI symphony to be conducted."
+    ),
+    GnosticLaw(
+        key="observability_without_docker",
+        validator=lambda g: g.get('observability_setup') and not g.get('use_docker'),
+        title="The Unseen Soul",
+        message="The Gaze of Observability was willed, but the reality will not be containerized.",
+        elucidation="While observability can be achieved on a host machine, containerized environments (via Docker Compose) provide a standardized, isolated, and reproducible way to run monitoring stacks like Prometheus and Grafana alongside the application.",
+        context_key="observability_setup",
+        suggestion="Enable Docker (`use_docker = True`) to forge a complete, self-aware, and observable reality."
+    ),
+
+    # =============================================================================
+    # == MOVEMENT IV: THE LAWS OF THE CO-ARCHITECT'S COMMUNION                   ==
+    # =============================================================================
+    GnosticLaw(
+        key="ai_consent_without_goals",
+        validator=lambda g: g.get('ai_code_generation_consent') and not g.get('project_goals'),
+        title="The Mute Oracle",
+        message="Consent granted for the AI Co-Architect, but no `project_goals` were proclaimed.",
+        elucidation="The AI Co-Architect's Gaze is most profound when it understands the ultimate destiny of the project. Proclaiming the project goals allows it to make more intelligent, context-aware prophecies and abstractions.",
+        context_key="ai_code_generation_consent",
+        suggestion="Proclaim the `project_goals` to empower the AI Co-Architect."
+    ),
+
+    # =============================================================================
+    # == MOVEMENT V: THE LAWS OF THE PROJECT'S SOUL                              ==
+    # =============================================================================
+    GnosticLaw(
+        key="casing_heresy_in_name",
+        validator=lambda g: g.get('project_name') and (g.get('project_name') != utils.to_slug_case(g.get('project_name'))),
+        title="A Profane Form (Project Name)",
+        message=lambda g: f"Project name '{g.get('project_name')}' contains profane characters or casing.",
+        elucidation="Project names should be in 'kebab-case' (e.g., 'my-awesome-api') for universal compatibility with package managers, domain names, and container registries. This avoids a multitude of downstream heresies.",
+        context_key="project_name",
+        suggestion=lambda g: f"Consider renaming to '{utils.to_slug_case(g.get('project_name', ''))}'."
+    ),
+    GnosticLaw(
+        key="vague_project_name",
+        validator=lambda g: g.get('project_name') and g.get('project_name').lower() in ['test', 'app', 'project', 'new-project'],
+        title="The Nameless Soul",
+        message=lambda g: f"The name '{g.get('project_name')}' is generic and lacks a unique Gnostic identity.",
+        elucidation="A unique and descriptive name is the first act of bestowing a soul upon a new reality. Generic names can lead to confusion and a lack of clear architectural intent.",
+        context_key="project_name",
+        suggestion="Choose a more specific and meaningful name for your project."
+    ),
+
+    # =============================================================================
+    # == MOVEMENT VI: THE LAWS OF THE FUTURE REALM (PROPHECIES)                  ==
+    # =============================================================================
+    GnosticLaw(
+        key="prophecy_of_the_polyglot_cosmos",
+        validator=lambda g: g.get('frontend_framework') not in ['none', 'vanilla-js'] and g.get('project_type') in ['python', 'go', 'rust'],
+        title="Prophecy: The Birth of a Polyglot Cosmos",
+        message="Binding a compiled backend to a JS frontend creates a complex Polyglot Cosmos.",
+        elucidation="Managing a project with distinct frontend and backend languages introduces complexities in the build process, deployment, and developer experience. This is a powerful but advanced architectural choice.",
+        context_key="frontend_framework",
+        suggestion="Consider a full-stack framework (like Next.js or Django+HTMX) or ensure a robust monorepo and API contract strategy is planned."
+    ),
+]

velm/jurisprudence_core/gnostic_type_system.py

@@ -0,0 +1,361 @@
+# Path: scaffold/jurisprudence_core/gnostic_type_system.py
+# --------------------------------------------------------
+
+import ast
+import re
+import uuid
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, List, Tuple, Optional
+
+
+def adjudicate_gnostic_purity(value: str, rule_string: str) -> Tuple[bool, Optional[str]]:
+    """
+    The one true, universal adjudicator. It receives a value and a scripture of laws
+    and returns a judgment of its purity.
+    """
+    if not rule_string:
+        return True, None
+
+    # This logic, which was once in jurisprudence.py, now lives here in its rightful home.
+    try:
+        # We use a simplified context for this validation rite.
+        # The 'validate' filter itself is what calls this.
+        gnostic_type = GnosticTypeParser.parse(rule_string)
+        gnostic_type.validate(value, "value", {})
+        return True, None
+    except ValueError as e:
+        return False, str(e)
+    except Exception as e:
+        return False, f"A meta-heresy occurred during adjudication: {e}"
+
+
+# --- THE BASE CONTRACT ---
+
+class GnosticType(ABC):
+    """
+    The Abstract Soul of a Type.
+    """
+
+    def __init__(self, constraints: Dict[str, Any] = None):
+        self.constraints = constraints or {}
+
+    @abstractmethod
+    def validate(self, value: Any, context: str, contract_registry: Dict[str, Any]) -> Any:
+        """
+        Adjudicates the value. Returns the cleaned value or raises ValueError.
+        'contract_registry' allows recursive lookup of other Contracts.
+        """
+        pass
+
+    def _check_constraints(self, value: Any, context: str):
+        """Universal constraint logic (min, max)."""
+        c = self.constraints
+        if 'min' in c:
+            if isinstance(value, (int, float)):
+                if value < c['min']: raise ValueError(f"{context} is too small (min {c['min']}).")
+            elif hasattr(value, '__len__'):
+                if len(value) < c['min']: raise ValueError(f"{context} is too short (min len {c['min']}).")
+
+        if 'max' in c:
+            if isinstance(value, (int, float)):
+                if value > c['max']: raise ValueError(f"{context} is too large (max {c['max']}).")
+            elif hasattr(value, '__len__'):
+                if len(value) > c['max']: raise ValueError(f"{context} is too long (max len {c['max']}).")
+
+
+# --- THE PRIMITIVES ---
+
+class AnyType(GnosticType):
+    def validate(self, value: Any, context: str, registry: Dict) -> Any:
+        return value
+
+
+class StringType(GnosticType):
+    def validate(self, value: Any, context: str, registry: Dict) -> str:
+        if not isinstance(value, str): raise ValueError(f"{context} must be a string.")
+        self._check_constraints(value, context)
+        if 'pattern' in self.constraints:
+            if not re.match(self.constraints['pattern'], value):
+                raise ValueError(f"{context} does not match pattern '{self.constraints['pattern']}'.")
+        return value
+
+
+class IntegerType(GnosticType):
+    def validate(self, value: Any, context: str, registry: Dict) -> int:
+        if isinstance(value, bool): raise ValueError(f"{context} must be an integer, not bool.")
+        if not isinstance(value, int): raise ValueError(f"{context} must be an integer.")
+        self._check_constraints(value, context)
+        return value
+
+
+class FloatType(GnosticType):
+    def validate(self, value: Any, context: str, registry: Dict) -> float:
+        if isinstance(value, bool): raise ValueError(f"{context} must be a float.")
+        if not isinstance(value, (float, int)): raise ValueError(f"{context} must be a number.")
+        self._check_constraints(value, context)
+        return float(value)
+
+
+class BoolType(GnosticType):
+    def validate(self, value: Any, context: str, registry: Dict) -> bool:
+        if not isinstance(value, bool): raise ValueError(f"{context} must be a boolean.")
+        return value
+
+
+# --- THE SEMANTIC TYPES ---
+
+class EmailType(StringType):
+    EMAIL_REGEX = re.compile(r'^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$')
+
+    def validate(self, value: Any, context: str, registry: Dict) -> str:
+        val = super().validate(value, context, registry)
+        if not self.EMAIL_REGEX.match(val): raise ValueError(f"{context} is not a valid email.")
+        return val
+
+
+class UUIDType(StringType):
+    def validate(self, value: Any, context: str, registry: Dict) -> str:
+        val = super().validate(value, context, registry)
+        try:
+            uuid.UUID(val)
+        except ValueError:
+            raise ValueError(f"{context} is not a valid UUID.")
+        return val
+
+
+class PathType(StringType):
+    def validate(self, value: Any, context: str, registry: Dict) -> str:
+        val = super().validate(value, context, registry)
+        p = Path(val)
+        if self.constraints.get('absolute') and not p.is_absolute():
+            raise ValueError(f"{context} must be an absolute path.")
+        return val
+
+
+class EnumType(GnosticType):
+    def validate(self, value: Any, context: str, registry: Dict) -> Any:
+        options = self.constraints.get('options', [])
+        if value not in options:
+            raise ValueError(f"{context} must be one of: {options}")
+        return value
+
+
+# --- THE HIGHER ORDER TYPES (THE SINGULARITY) ---
+
+class ListType(GnosticType):
+    def __init__(self, item_type: GnosticType, constraints: Dict = None):
+        super().__init__(constraints)
+        self.item_type = item_type
+
+    def validate(self, value: Any, context: str, registry: Dict) -> List[Any]:
+        if not isinstance(value, list): raise ValueError(f"{context} must be a list.")
+        self._check_constraints(value, context)
+        return [self.item_type.validate(item, f"{context}[{i}]", registry) for i, item in enumerate(value)]
+
+
+class DictType(GnosticType):
+    def __init__(self, key_type: GnosticType, value_type: GnosticType, constraints: Dict = None):
+        super().__init__(constraints)
+        self.key_type = key_type
+        self.value_type = value_type
+
+    def validate(self, value: Any, context: str, registry: Dict) -> Dict[Any, Any]:
+        if not isinstance(value, dict): raise ValueError(f"{context} must be a dict.")
+        self._check_constraints(value, context)
+        validated = {}
+        for k, v in value.items():
+            vk = self.key_type.validate(k, f"{context}.key({k})", registry)
+            vv = self.value_type.validate(v, f"{context}[{k}]", registry)
+            validated[vk] = vv
+        return validated
+
+
+class UnionType(GnosticType):
+    def __init__(self, types: List[GnosticType]):
+        super().__init__()
+        self.types = types
+
+    def validate(self, value: Any, context: str, registry: Dict) -> Any:
+        errors = []
+        for t in self.types:
+            try:
+                return t.validate(value, context, registry)
+            except ValueError as e:
+                errors.append(str(e))
+
+        raise ValueError(f"{context} failed Union check. Mismatches: {'; '.join(errors)}")
+
+
+class ContractRefType(GnosticType):
+    def __init__(self, contract_name: str):
+        super().__init__()
+        self.contract_name = contract_name
+
+    def validate(self, value: Any, context: str, registry: Dict) -> Any:
+        if self.contract_name not in registry:
+            raise ValueError(f"Contract '{self.contract_name}' is not defined.")
+
+        # Recursive Call to the Registry
+        contract = registry[self.contract_name]
+        # We rely on the Contract object's own validate method (defined below or externally)
+        # Since GnosticContract is in data_contracts, we do a manual validation here
+        # to avoid circular imports, or we move GnosticContract logic here.
+        # For purity, we assume value is a dict and validate fields.
+
+        if not isinstance(value, dict):
+            raise ValueError(f"{context} must be an object honoring '{self.contract_name}'.")
+
+        # Validate Fields
+        for field_name, field_def in contract.fields.items():
+            if field_name not in value:
+                if field_def.is_optional or field_def.default_value is not None:
+                    continue
+                raise ValueError(f"Missing required field '{field_name}' in {context} ({self.contract_name}).")
+
+            # The field_def.type_instance is a GnosticType!
+            field_def.gnostic_type.validate(value[field_name], f"{context}.{field_name}", registry)
+
+        return value
+
+
+class OptionalType(GnosticType):
+    def __init__(self, inner_type: GnosticType):
+        super().__init__()
+        self.inner_type = inner_type
+
+    def validate(self, value: Any, context: str, registry: Dict) -> Any:
+        if value is None: return None
+        return self.inner_type.validate(value, context, registry)
+
+
+# --- THE AST PARSER (THE BRAIN) ---
+
+class GnosticTypeParser:
+    """
+    Translates Python type strings ("List[str]", "int(min=1)") into GnosticType objects.
+    """
+
+    @classmethod
+    def parse(cls, type_str: str) -> GnosticType:
+        try:
+            # We use ast.parse in 'eval' mode to handle nested structures
+            node = ast.parse(type_str, mode='eval').body
+            return cls._visit(node)
+        except Exception as e:
+            # Fallback for simple strings that AST might dislike if they look like keywords?
+            # Actually AST handles most things well.
+            raise ValueError(f"Invalid type signature '{type_str}': {e}")
+
+    @classmethod
+    def _visit(cls, node) -> GnosticType:
+        # 1. Basic Types: "str", "int"
+        if isinstance(node, ast.Name):
+            return cls._resolve_primitive(node.id)
+
+        # 2. Constraints: "int(min=1)"
+        if isinstance(node, ast.Call):
+            base_type = cls._visit(node.func)
+            constraints = {}
+            for kw in node.keywords:
+                try:
+                    constraints[kw.arg] = ast.literal_eval(kw.value)
+                except:
+                    pass  # Logic for complex constraint values if needed
+
+            # Handle Enum positional args: enum("a", "b")
+            if isinstance(base_type, EnumType):
+                opts = []
+                for arg in node.args:
+                    try:
+                        opts.append(ast.literal_eval(arg))
+                    except:
+                        pass
+                constraints['options'] = opts
+
+            base_type.constraints = constraints
+            return base_type
+
+        # 3. Generics: "List[str]"
+        if isinstance(node, ast.Subscript):
+            base_id = node.value.id if isinstance(node.value, ast.Name) else ""
+
+            if base_id in ('List', 'list', 'Set', 'set'):
+                inner = cls._visit(node.slice)
+                return ListType(inner)
+
+            if base_id in ('Dict', 'dict'):
+                # Dicts in AST often come as Tuple in slice if multiple args?
+                # e.g. Dict[str, int] -> slice is Tuple
+                if isinstance(node.slice, ast.Tuple):
+                    key_t = cls._visit(node.slice.elts[0])
+                    val_t = cls._visit(node.slice.elts[1])
+                    return DictType(key_t, val_t)
+                else:
+                    # Fallback Dict[str, Any]
+                    return DictType(StringType(), AnyType())
+
+            if base_id == 'Optional':
+                inner = cls._visit(node.slice)
+                return OptionalType(inner)
+
+        # 4. Unions: "str | int"
+        if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
+            left = cls._visit(node.left)
+            right = cls._visit(node.right)
+            # Flatten unions if recursive
+            types = []
+            if isinstance(left, UnionType):
+                types.extend(left.types)
+            else:
+                types.append(left)
+
+            if isinstance(right, UnionType):
+                types.extend(right.types)
+            else:
+                types.append(right)
+
+            return UnionType(types)
+
+        # Fallback for Constants (None)
+        if isinstance(node, ast.Constant) and node.value is None:
+            return AnyType()  # NoneType
+
+        return AnyType()
+
+    @staticmethod
+    def _resolve_primitive(name: str) -> GnosticType:
+        n = name.lower()
+
+        # --- Standard Types ---
+        if n in ('str', 'string', 'text'): return StringType()
+        if n in ('int', 'integer'): return IntegerType()
+        if n in ('float', 'number'): return FloatType()
+        if n in ('bool', 'boolean'): return BoolType()
+        if n == 'uuid': return UUIDType()
+        if n == 'email': return EmailType()
+        if n == 'path': return PathType()
+        if n == 'enum': return EnumType()
+        if n == 'any': return AnyType()
+
+        # --- ★★★ THE LEGACY SHORTHANDS (THE FIX) ★★★ ---
+        # We map these legacy validator names to concrete StringTypes with patterns.
+
+        if n == 'var_path_safe':
+            # Alphanumeric, underscores, hyphens, dots. No spaces or slashes.
+            return StringType(constraints={'pattern': r'^[a-zA-Z0-9_.-]+$'})
+
+        if n == 'slug':
+            # Lowercase alphanumeric and hyphens.
+            return StringType(constraints={'pattern': r'^[a-z0-9-]+$'})
+
+        if n == 'snake':
+            # Lowercase alphanumeric and underscores.
+            return StringType(constraints={'pattern': r'^[a-z0-9_]+$'})
+
+        if n == 'pascal':
+            # PascalCase
+            return StringType(constraints={'pattern': r'^[A-Z][a-zA-Z0-9]*$'})
+
+        # --- Unknown -> Assume Contract Reference ---
+        return ContractRefType(name)

velm/jurisprudence_core/heresy_chronicles/__init__.py

@@ -0,0 +1,5 @@
+# Path: scaffold/jurisprudence_core/heresy_chronicles/__init__.py
+"""The sacred gateway to the Oracles of Interpretation."""
+from .heresy_chronicler import HeresyChronicler
+
+__all__ = ["HeresyChronicler"]