core-runtime 0.1.1__py3-none-any.whl

shared/infrastructure/storage/integrity_service.py

@@ -0,0 +1,108 @@
+# src/shared/infrastructure/storage/integrity_service.py
+
+"""
+Integrity Service - Phase 2 Hardening.
+Provides deterministic checksum verification for the codebase.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+
+from shared.logger import getLogger
+from shared.models.validation_result import ValidationResult
+
+
+logger = getLogger(__name__)
+
+
+# ID: 3e5c78c1-db6a-4ff8-8cdd-0f284b0acd80
+class IntegrityService:
+    """
+    Manages codebase fingerprints to ensure deterministic state.
+    """
+
+    def __init__(self, repo_root: Path):
+        self.repo_root = repo_root
+        self.integrity_dir = repo_root / "var" / "integrity"
+        self.integrity_dir.mkdir(parents=True, exist_ok=True)
+
+    # ID: ef8581d2-86f8-47f5-b1b8-27fb72b95b80
+    def create_baseline(self, label: str = "default") -> Path:
+        """
+        Scans src/ and creates a signed baseline of all file hashes.
+        """
+        logger.info("Creating integrity baseline: %s", label)
+
+        manifest = {
+            "metadata": {
+                "label": label,
+                "timestamp": datetime.now(UTC).isoformat(),
+                "repo_root": str(self.repo_root),
+            },
+            "files": self._hash_codebase(),
+        }
+
+        output_path = self.integrity_dir / f"baseline_{label}.json"
+        output_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+
+        logger.info("✅ Baseline saved to %s", output_path)
+        return output_path
+
+    # ID: 2cfcf898-5206-4247-bc6a-24042c430284
+    def verify_integrity(self, label: str = "default") -> ValidationResult:
+        """
+        Compares current codebase against a saved baseline.
+        """
+        baseline_path = self.integrity_dir / f"baseline_{label}.json"
+        if not baseline_path.exists():
+            return ValidationResult(ok=False, errors=[f"Baseline '{label}' not found."])
+
+        baseline = json.loads(baseline_path.read_text(encoding="utf-8"))
+        current_state = self._hash_codebase()
+
+        errors = []
+        # Check for modified or deleted files
+        for path, expected_hash in baseline["files"].items():
+            if path not in current_state:
+                errors.append(f"DELETED: {path}")
+            elif current_state[path] != expected_hash:
+                errors.append(f"MODIFIED: {path}")
+
+        # Check for new files
+        for path in current_state:
+            if path not in baseline["files"]:
+                errors.append(f"NEW FILE: {path}")
+
+        is_ok = len(errors) == 0
+        return ValidationResult(
+            ok=is_ok,
+            errors=errors,
+            metadata={"checked_at": datetime.now(UTC).isoformat()},
+        )
+
+    def _hash_codebase(self) -> dict[str, str]:
+        """Calculates SHA256 for every file in src/."""
+        hashes = {}
+        src_path = self.repo_root / "src"
+
+        for file_path in src_path.rglob("*.py"):
+            if "__pycache__" in str(file_path):
+                continue
+
+            rel_path = str(file_path.relative_to(self.repo_root))
+            hashes[rel_path] = self._generate_file_hash(file_path)
+
+        return hashes
+
+    @staticmethod
+    def _generate_file_hash(path: Path) -> str:
+        """Helper to generate a stable file hash."""
+        sha256_hash = hashlib.sha256()
+        with open(path, "rb") as f:
+            for byte_block in iter(lambda: f.read(4096), b""):
+                sha256_hash.update(byte_block)
+        return sha256_hash.hexdigest()

shared/infrastructure/validation/black_formatter.py

@@ -0,0 +1,41 @@
+# src/shared/infrastructure/validation/black_formatter.py
+
+"""
+Formats Python code using the Black formatter with robust error handling for syntax and formatting issues.
+"""
+
+from __future__ import annotations
+
+import black
+
+
+# --- MODIFICATION: The function now returns only the formatted code on success ---
+# --- and raises a specific exception on failure, simplifying its contract. ---
+# ID: 044478bd-8231-48ff-af43-6bc3c022d69c
+def format_code_with_black(code: str) -> str:
+    """Formats the given Python code using Black, raising `black.InvalidInput` for syntax errors or `Exception` for other formatting issues."""
+    """
+    Attempts to format the given Python code using Black.
+
+    Args:
+        code: The Python source code to format.
+
+    Returns:
+        The formatted code as a string.
+
+    Raises:
+        black.InvalidInput: If the code contains a syntax error that Black cannot handle.
+        Exception: For other unexpected Black formatting errors.
+    """
+    try:
+        mode = black.FileMode()
+        formatted_code = black.format_str(code, mode=mode)
+        return formatted_code
+    except black.InvalidInput as e:
+        # Re-raise with a clear message for the pipeline to catch.
+        raise black.InvalidInput(
+            f"Black could not format the code due to a syntax error: {e}"
+        )
+    except Exception as e:
+        # Catch any other unexpected errors from Black.
+        raise Exception(f"An unexpected error occurred during Black formatting: {e}")

shared/infrastructure/validation/quality.py

@@ -0,0 +1,46 @@
+# src/shared/infrastructure/validation/quality.py
+
+"""
+Code quality validation checks for maintainability and clarity.
+
+This module provides quality-focused validation checks such as detecting
+FUTURE comments and other code clarity issues that don't affect functionality
+but impact maintainability.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+Violation = dict[str, Any]
+
+
+# ID: 0c6502f3-6d97-41e8-a618-6ae63a489e8b
+class QualityChecker:
+    """Handles code quality and clarity validation checks."""
+
+    # ID: 972208ef-200e-4836-851d-f82f24e3b779
+    def check_for_todo_comments(self, code: str) -> list[Violation]:
+        """Scans source code for FUTURE/PENDING comments and returns them as violations.
+
+        Args:
+            code: The source code to scan for FUTURE comments
+
+        Returns:
+            List of violations for each FUTURE/PENDING comment found
+        """
+        violations: list[Violation] = []
+        for i, line in enumerate(code.splitlines(), 1):
+            if "#" in line:
+                comment = line.split("#", 1)[1]
+                if "FUTURE" in comment or "PENDING" in comment:
+                    violations.append(
+                        {
+                            "rule": "clarity.no_todo_comments",
+                            "message": f"Unresolved '{comment.strip()}' on line {i}",
+                            "line": i,
+                            "severity": "warning",
+                        }
+                    )
+        return violations

shared/infrastructure/validation/ruff_linter.py

@@ -0,0 +1,104 @@
+# src/shared/infrastructure/validation/ruff_linter.py
+
+"""
+Provides a utility to fix and lint Python code using Ruff's JSON output format.
+Runs Ruff lint checks on generated Python code before it's staged.
+Returns a success flag and an optional linting message.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+Violation = dict[str, Any]
+
+
+# ID: 4c86e6d0-20f6-4773-8030-b31d1d109871
+def fix_and_lint_code_with_ruff(
+    code: str, repo_root: Path, display_filename: str = "<code>"
+) -> tuple[str, list[Violation]]:
+    """
+    Fix and lint the provided Python code using Ruff's JSON output format.
+
+    Args:
+        code (str): Source code to fix and lint.
+        repo_root (Path): Repository root; temp dir resolves under repo_root/var/tmp/
+            per CLAUDE.md /tmp/ prohibition.
+        display_filename (str): Optional display name for readable error messages.
+
+    Returns:
+        A tuple containing:
+        - The potentially fixed code as a string.
+        - A list of structured violation dictionaries for any remaining issues.
+    """
+    violations: list[Violation] = []
+
+    # Use a temporary directory to avoid any explicit filesystem deletions (no os.remove).
+    with tempfile.TemporaryDirectory(
+        prefix="core_ruff_", dir=str(repo_root / "var" / "tmp")
+    ) as tmp_dir:
+        tmp_path = Path(tmp_dir) / "snippet.py"
+        tmp_path.write_text(code, encoding="utf-8")
+
+        try:
+            # Apply fixes (do not fail build on lint errors).
+            subprocess.run(
+                ["ruff", "check", str(tmp_path), "--fix", "--exit-zero", "--quiet"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+            fixed_code = tmp_path.read_text(encoding="utf-8")
+
+            # Collect structured violations (JSON output).
+            result = subprocess.run(
+                ["ruff", "check", str(tmp_path), "--format", "json", "--exit-zero"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+            if result.stdout:
+                ruff_violations = json.loads(result.stdout)
+                for v in ruff_violations:
+                    violations.append(
+                        {
+                            "rule": v.get("code", "RUFF-UNKNOWN"),
+                            "message": v.get("message", "Unknown Ruff error"),
+                            "line": v.get("location", {}).get("row", 0),
+                            "severity": "warning",
+                            "file": display_filename,
+                        }
+                    )
+
+            return (fixed_code, violations)
+
+        except FileNotFoundError:
+            logger.error(
+                "Ruff is not installed or not in your PATH. Please install it."
+            )
+            tool_missing_violation: Violation = {
+                "rule": "tooling.missing",
+                "message": "Ruff is not installed or not in your PATH.",
+                "line": 0,
+                "severity": "error",
+                "file": display_filename,
+            }
+            return (code, [tool_missing_violation])
+
+        except json.JSONDecodeError:
+            logger.error("Failed to parse Ruff's JSON output.")
+            return (code, [])
+
+        except Exception as e:
+            logger.error("An unexpected error occurred during Ruff execution: %s", e)
+            return (code, [])

shared/infrastructure/validation/syntax_checker.py

@@ -0,0 +1,45 @@
+# src/shared/infrastructure/validation/syntax_checker.py
+
+"""
+Handles Python syntax validation for code before it's staged for write/commit operations.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import Any
+
+
+Violation = dict[str, Any]
+# --- END OF FIX ---
+
+
+# ID: c1e335fb-1ee0-4e76-b6bd-9ed7a7494f14
+def check_syntax(file_path: str, code: str) -> list[Violation]:
+    """Checks the given Python code for syntax errors and returns a list of violations, if any."""
+    """
+    Checks whether the given code has valid Python syntax.
+
+    Args:
+        file_path (str): File name (used to detect .py files).
+        code (str): Source code string.
+
+    Returns:
+        A list of violation dictionaries. An empty list means the syntax is valid.
+    """
+    if not file_path.endswith(".py"):
+        return []
+
+    try:
+        ast.parse(code)
+        return []
+    except SyntaxError as e:
+        error_line = e.text.strip() if e.text else "<source unavailable>"
+        return [
+            {
+                "rule": "E999",  # Ruff's code for syntax errors
+                "message": f"Invalid Python syntax: {e.msg} near '{error_line}'",
+                "line": e.lineno,
+                "severity": "error",
+            }
+        ]

shared/infrastructure/validation/test_runner.py

@@ -0,0 +1,167 @@
+# src/shared/infrastructure/validation/test_runner.py
+
+"""
+Executes pytest and captures results as Constitutional Evidence.
+
+- Implemented 'suppress_logging' parameter to control logging verbosity (workflow.dead_code_check).
+- Maintains strict traceability by persisting to DB regardless of verbosity.
+- Aligns with the 'Headless' policy (LOG-001).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from datetime import UTC, datetime
+from typing import Any
+
+from shared.action_types import ActionImpact, ActionResult
+from shared.config import settings
+from shared.infrastructure.database.session_manager import get_session
+from shared.infrastructure.storage.file_handler import FileHandler
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+# ID: 0a702b47-f04b-4afe-8e35-20e9cad19aa3
+async def run_tests(suppress_logging: bool = True) -> ActionResult:
+    """
+    Executes pytest asynchronously and returns a canonical ActionResult.
+
+    Args:
+        suppress_logging: If False, logs start/stop events to the system logger.
+    """
+    start_time = time.perf_counter()
+
+    if not suppress_logging:
+        logger.info("🧪 Initiating system test suite...")
+
+    repo_root = settings.REPO_PATH
+    tests_path = repo_root / "tests"
+
+    timeout = settings.model_extra.get("TEST_RUNNER_TIMEOUT", 300)
+
+    try:
+        process = await asyncio.create_subprocess_exec(
+            "pytest",
+            str(tests_path),
+            "--tb=short",
+            "-q",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=repo_root,
+        )
+
+        try:
+            stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                process.communicate(), timeout=timeout
+            )
+            stdout = stdout_bytes.decode().strip()
+            stderr = stderr_bytes.decode().strip()
+            exit_code = process.returncode
+        except TimeoutError:
+            process.kill()
+            stdout = ""
+            stderr = f"Test run timed out after {timeout}s."
+            exit_code = -1
+
+    except Exception as e:
+        stdout = ""
+        stderr = str(e)
+        exit_code = -1
+
+    duration = time.perf_counter() - start_time
+    ok = exit_code == 0
+    summary = (
+        _summarize(stdout) if ok else (stderr.split("\n")[0] or "Execution failed")
+    )
+
+    # 1. Construct the Result Payload
+    result_data = {
+        "exit_code": exit_code,
+        "stdout": stdout,
+        "stderr": stderr,
+        "summary": summary,
+        "error": summary if not ok else None,
+        "timestamp": datetime.now(UTC).isoformat(),
+    }
+
+    # 2. Build the Canonical ActionResult
+    action_result = ActionResult(
+        action_id="test.execute",
+        ok=ok,
+        data=result_data,
+        duration_sec=duration,
+        impact=ActionImpact.READ_ONLY,
+        suggestions=["Run 'pytest --lf' to retry failed tests."] if not ok else [],
+    )
+
+    # 3. Persist Evidence (Always happens, even if suppress_logging is True)
+    _log_test_result_to_file(result_data)
+    _store_failure_artifact(result_data)
+    await _persist_result_to_db(action_result)
+
+    if not suppress_logging:
+        logger.info("🏁 Test run complete: %s (%.2fs)", summary, duration)
+
+    return action_result
+
+
+def _summarize(output: str) -> str:
+    """Parses pytest output to find the final summary line."""
+    if not output:
+        return "No output captured."
+    lines = output.strip().splitlines()
+    for line in reversed(lines):
+        if any(word in line for word in ["passed", "failed", "error", "skipped"]):
+            return line.strip()
+    return "No test summary found."
+
+
+async def _persist_result_to_db(result: ActionResult) -> None:
+    """Writes the result to the core.action_results table."""
+    from shared.models.action_result import ActionResult as ActionResultModel
+
+    try:
+        async with get_session() as session:
+            db_entry = ActionResultModel(
+                action_type="test_execution",
+                ok=result.ok,
+                error_message=result.data.get("stderr") if not result.ok else None,
+                action_metadata={
+                    "summary": result.data.get("summary"),
+                    "exit_code": result.data.get("exit_code"),
+                    "timestamp": result.data.get("timestamp"),
+                },
+                agent_id="test_runner_infra",
+                duration_ms=int(result.duration_sec * 1000),
+            )
+            session.add(db_entry)
+            await session.commit()
+    except Exception as e:
+        logger.warning("Failed to persist test result to DB: %s", e)
+
+
+def _log_test_result_to_file(data: dict[str, Any]) -> None:
+    try:
+        fh = FileHandler(str(settings.REPO_PATH))
+        rel_log_path = "var/logs/tests.jsonl"
+        new_line = json.dumps(data, ensure_ascii=False) + "\n"
+        fh.write_runtime_text(rel_log_path, new_line)
+    except Exception as e:
+        logger.debug("Test file logging skipped: %s", e)
+
+
+def _store_failure_artifact(data: dict[str, Any]) -> None:
+    try:
+        fh = FileHandler(str(settings.REPO_PATH))
+        failure_rel = "var/reports/test_failures.json"
+        if data.get("exit_code") != 0:
+            fh.write_runtime_json(failure_rel, data)
+        else:
+            fh.remove_file(failure_rel)
+    except Exception as e:
+        logger.debug("Test failure artifact update skipped: %s", e)

shared/infrastructure/validation/yaml_validator.py

@@ -0,0 +1,45 @@
+# src/shared/infrastructure/validation/yaml_validator.py
+
+"""
+YAML validation pipeline.
+
+This module provides validation functionality specifically for YAML files,
+checking for syntax errors and structural issues.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+
+Violation = dict[str, Any]
+
+
+# ID: f3bbf4e9-71b5-4dad-8ad8-ee93b90dd8c0
+def validate_yaml_code(code: str) -> tuple[str, list[Violation]]:
+    """Validation pipeline for YAML code.
+
+    This function validates YAML syntax and structure, returning any violations
+    found during the validation process.
+
+    Args:
+        code: The YAML code to validate
+
+    Returns:
+        A tuple containing the original code and list of violations
+    """
+    violations = []
+    try:
+        yaml.safe_load(code)
+    except yaml.YAMLError as e:
+        violations.append(
+            {
+                "rule": "syntax.yaml",
+                "message": f"Invalid YAML format: {e}",
+                "line": e.problem_mark.line + 1 if e.problem_mark else 0,
+                "severity": "error",
+            }
+        )
+    return code, violations

shared/infrastructure/vector/__init__.py

@@ -0,0 +1,15 @@
+# src/shared/infrastructure/vector/__init__.py
+
+"""
+Unified Vector Indexing Infrastructure
+
+Provides the constitutional single source of truth for all vectorization
+operations across CORE.
+"""
+
+from __future__ import annotations
+
+from .vector_index_service import VectorIndexService
+
+
+__all__ = ["VectorIndexService"]

shared/infrastructure/vector/adapters/__init__.py

@@ -0,0 +1,20 @@
+# src/shared/infrastructure/vector/adapters/__init__.py
+
+"""
+Domain Adapters for Vector Indexing
+
+Adapters translate domain-specific data formats into VectorizableItems
+for the unified VectorIndexService.
+
+Available Adapters:
+- ConstitutionalAdapter: Policies and patterns (YAML)
+- ModuleAnchorAdapter: Architectural module context (coming in Step 3)
+- CapabilityAdapter: Knowledge graph symbols (coming in Step 4)
+"""
+
+from __future__ import annotations
+
+from .constitutional_adapter import ConstitutionalAdapter
+
+
+__all__ = ["ConstitutionalAdapter"]

shared/infrastructure/vector/adapters/constitutional/__init__.py

@@ -0,0 +1,26 @@
+# src/shared/infrastructure/vector/adapters/constitutional/__init__.py
+
+"""
+Constitutional vector adapter components.
+
+Components:
+- chunker: Semantic document chunking
+- doc_key_resolver: Canonical key computation
+- item_builder: VectorizableItem construction
+- utils: Shared utilities
+"""
+
+from __future__ import annotations
+
+from .chunker import chunk_document
+from .doc_key_resolver import compute_doc_key
+from .item_builder import data_to_items
+from .utils import safe_str
+
+
+__all__ = [
+    "chunk_document",
+    "compute_doc_key",
+    "data_to_items",
+    "safe_str",
+]