kernhell 0.1.0__py3-none-any.whl

kernhell/cli/ui.py

@@ -0,0 +1,176 @@
+"""Rich console UI helpers for KernHell CLI output.
+
+Provides reusable display components for the terminal:
+  - Branded banner with version
+  - Failure context panels
+  - Healing result tables
+  - Progress spinners
+  - Diff display for patched selectors
+"""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich.syntax import Syntax
+from rich import box
+
+from kernhell import __version__
+from kernhell.core.models import FailureContext, HealingReport, PrunedDOM
+
+console = Console(stderr=True)
+
+
+# ---------------------------------------------------------------------------
+# Banner
+# ---------------------------------------------------------------------------
+
+_BANNER = r"""
+ ██╗  ██╗███████╗██████╗ ███╗   ██╗██╗  ██╗███████╗██╗     ██╗
+ ██║ ██╔╝██╔════╝██╔══██╗████╗  ██║██║  ██║██╔════╝██║     ██║
+ █████╔╝ █████╗  ██████╔╝██╔██╗ ██║███████║█████╗  ██║     ██║
+ ██╔═██╗ ██╔══╝  ██╔══██╗██║╚██╗██║██╔══██║██╔══╝  ██║     ██║
+ ██║  ██╗███████╗██║  ██║██║ ╚████║██║  ██║███████╗███████╗███████╗
+ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝
+"""
+
+
+def print_banner() -> None:
+    """Display the KernHell ASCII banner with version."""
+    banner_text = Text(_BANNER, style="bold red")
+    tagline = Text(
+        "  The Heart of Your System Where Innovation Meets Precision",
+        style="italic bright_black",
+    )
+    version = Text(f"  v{__version__}", style="dim")
+
+    console.print(banner_text, highlight=False)
+    console.print(tagline)
+    console.print(version)
+    console.print()
+
+
+# ---------------------------------------------------------------------------
+# Failure Display
+# ---------------------------------------------------------------------------
+
+
+def print_failure_context(ctx: FailureContext, index: int = 1) -> None:
+    """Display a single failure context as a Rich panel."""
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column("Key", style="bold cyan", width=16)
+    table.add_column("Value")
+
+    table.add_row("Selector", Text(ctx.broken_selector, style="bold red"))
+    table.add_row("Type", ctx.selector_type.value)
+    table.add_row("Error", ctx.error_type.value)
+    table.add_row("Line", str(ctx.line_number) if ctx.line_number else "unknown")
+    table.add_row("File", str(ctx.test_file.name))
+
+    if ctx.page_url:
+        table.add_row("URL", ctx.page_url)
+
+    panel = Panel(
+        table,
+        title=f"[bold red]💀 Failure #{index}[/bold red]",
+        border_style="red",
+        box=box.ROUNDED,
+    )
+    console.print(panel)
+
+    # Show surrounding code if available
+    if ctx.surrounding_code:
+        syntax = Syntax(
+            ctx.surrounding_code,
+            "python",
+            theme="monokai",
+            line_numbers=False,
+            word_wrap=True,
+        )
+        console.print(
+            Panel(syntax, title="[dim]Surrounding Code[/dim]", border_style="dim")
+        )
+
+
+def print_pruning_stats(pruned: PrunedDOM) -> None:
+    """Display DOM pruning statistics."""
+    console.print(
+        f"  🔪 DOM Pruned: "
+        f"[dim]{pruned.original_size:,}[/dim] → "
+        f"[bold green]{pruned.pruned_size:,}[/bold green] bytes "
+        f"([bold green]-{pruned.reduction_pct}%[/bold green])"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Scan Summary
+# ---------------------------------------------------------------------------
+
+
+def print_scan_summary(failures: list[FailureContext]) -> None:
+    """Display a summary table of all detected failures."""
+    if not failures:
+        console.print(
+            Panel(
+                "[bold green]✅ All tests passed — nothing to heal![/bold green]",
+                border_style="green",
+            )
+        )
+        return
+
+    table = Table(
+        title="🔍 Detected Selector Failures",
+        box=box.SIMPLE_HEAVY,
+        show_lines=True,
+    )
+    table.add_column("#", style="dim", width=4)
+    table.add_column("Selector", style="bold red")
+    table.add_column("Type", style="cyan")
+    table.add_column("Line", style="yellow", justify="right")
+    table.add_column("Error", style="dim")
+
+    for i, f in enumerate(failures, 1):
+        table.add_row(
+            str(i),
+            f.broken_selector,
+            f.selector_type.value,
+            str(f.line_number) if f.line_number else "?",
+            f.error_type.value,
+        )
+
+    console.print(table)
+    console.print(
+        f"\n  [bold]{len(failures)}[/bold] broken selector(s) found.\n"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Healing Report (stub — expanded in Weekend 2)
+# ---------------------------------------------------------------------------
+
+
+def print_healing_report(report: HealingReport) -> None:
+    """Display the final healing report."""
+    table = Table(
+        title="🔥 KernHell Healing Report",
+        box=box.DOUBLE_EDGE,
+    )
+    table.add_column("Metric", style="bold")
+    table.add_column("Value", justify="right")
+
+    table.add_row("Total Failures", str(report.total_failures))
+    table.add_row("Healed", f"[bold green]{report.healed_count}[/bold green]")
+    table.add_row("Skipped", f"[yellow]{report.skipped_count}[/yellow]")
+    table.add_row("From Cache", str(report.cache_hits))
+    table.add_row("LLM Calls", str(report.llm_calls))
+    table.add_row("Duration", f"{report.duration_ms}ms")
+    table.add_row(
+        "Status",
+        "[bold green]✅ PASSED[/bold green]"
+        if report.verification_passed
+        else "[bold red]❌ FAILED[/bold red]",
+    )
+
+    console.print(table)

kernhell/core/__init__.py

@@ -0,0 +1 @@
+"""Core package — models, config, orchestration, and exceptions."""

kernhell/core/config.py

@@ -0,0 +1,219 @@
+"""KernHell configuration management.
+
+Loads settings from (in priority order):
+  1. Environment variables  (KERNHELL_LLM__PROVIDER, etc.)
+  2. .kernhellrc.toml in the current directory
+  3. ~/.kernhellrc.toml in the user's home directory
+  4. Built-in defaults
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import-untyped]
+
+
+# ---------------------------------------------------------------------------
+# Config Sub-Sections
+# ---------------------------------------------------------------------------
+
+
+class LLMConfig(BaseModel):
+    """LLM provider settings."""
+
+    provider: str = "gemini"
+    model: str = "gemini-1.5-flash"
+    api_key: Optional[str] = None
+    temperature: float = 0.1
+    max_tokens: int = 2048
+
+    def get_resolved_api_key(self) -> Optional[str]:
+        """Resolve API key from explicit config or standard provider environment variables."""
+        if self.api_key:
+            return self.api_key
+
+        import os
+
+        prov = self.provider.lower()
+        if prov == "gemini":
+            return os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY")
+        elif prov == "groq":
+            return os.environ.get("GROQ_API_KEY")
+        elif prov == "openai":
+            return os.environ.get("OPENAI_API_KEY")
+        elif prov == "anthropic":
+            return os.environ.get("ANTHROPIC_API_KEY")
+        return None
+
+    def get_litellm_model_name(self) -> str:
+        """Format the model name appropriately for litellm."""
+        prov = self.provider.lower()
+        model = self.model.strip()
+        if prov == "openai":
+            return model
+        elif prov == "gemini":
+            return model if model.startswith("gemini/") else f"gemini/{model}"
+        return model if model.startswith(f"{prov}/") else f"{prov}/{model}"
+
+
+class HealingConfig(BaseModel):
+    """Healing behavior settings."""
+
+    confidence_threshold: float = 0.85
+    max_heals_per_file: int = 5
+    dry_run: bool = False
+    auto_commit: bool = False
+
+
+class CacheConfig(BaseModel):
+    """Semantic vector cache settings."""
+
+    enabled: bool = True
+    similarity_threshold: float = 0.92
+    cache_dir: str = "~/.kernhell/cache"
+    embedding_model: str = "all-MiniLM-L6-v2"
+
+
+class ScannerConfig(BaseModel):
+    """Playwright scanner settings."""
+
+    timeout_ms: int = 5000
+    capture_screenshot: bool = True
+    browser: str = "chromium"
+    headless: bool = True
+
+
+class LoggingConfig(BaseModel):
+    """Logging settings."""
+
+    level: str = "INFO"
+    json_output: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Root Config
+# ---------------------------------------------------------------------------
+
+
+class KernHellConfig(BaseSettings):
+    """Root configuration for KernHell.
+
+    Merges TOML file settings with environment variable overrides.
+    Env vars use the prefix ``KERNHELL_`` with double-underscore nesting
+    (e.g. ``KERNHELL_LLM__PROVIDER=openai``).
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="KERNHELL_",
+        env_nested_delimiter="__",
+        case_sensitive=False,
+    )
+
+    llm: LLMConfig = Field(default_factory=LLMConfig)
+    healing: HealingConfig = Field(default_factory=HealingConfig)
+    cache: CacheConfig = Field(default_factory=CacheConfig)
+    scanner: ScannerConfig = Field(default_factory=ScannerConfig)
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
+
+
+# ---------------------------------------------------------------------------
+# Config Loading
+# ---------------------------------------------------------------------------
+
+_CONFIG_FILENAMES = [".kernhellrc.toml", "kernhell.toml"]
+
+
+def _find_config_file() -> Optional[Path]:
+    """Search current dir, then home dir for a config file."""
+    for directory in [Path.cwd(), Path.home()]:
+        for name in _CONFIG_FILENAMES:
+            candidate = directory / name
+            if candidate.is_file():
+                return candidate
+    return None
+
+
+def _extract_env_overrides() -> dict:
+    """Extract and nest environment variables starting with KERNHELL_."""
+    import os
+
+    overrides: dict = {}
+    prefix = "KERNHELL_"
+    for key, value in os.environ.items():
+        if key.upper().startswith(prefix):
+            remainder = key[len(prefix):].lower()
+            parts = remainder.split("__")
+            d = overrides
+            for p in parts[:-1]:
+                d = d.setdefault(p, {})
+            d[parts[-1]] = value
+    return overrides
+
+
+def _deep_merge(base: dict, overlay: dict) -> dict:
+    """Recursively merge overlay dict on top of base dict."""
+    merged = dict(base)
+    for k, v in overlay.items():
+        if k in merged and isinstance(merged[k], dict) and isinstance(v, dict):
+            merged[k] = _deep_merge(merged[k], v)
+        else:
+            merged[k] = v
+    return merged
+
+
+def _load_env_file() -> None:
+    """Load key-value pairs from .env file into os.environ if present."""
+    import os
+
+    for env_file in [Path.cwd() / ".env", Path.home() / ".kernhell" / ".env"]:
+        if env_file.is_file():
+            try:
+                for line in env_file.read_text(encoding="utf-8").splitlines():
+                    line = line.strip()
+                    if line and not line.startswith("#") and "=" in line:
+                        k, v = line.split("=", 1)
+                        k = k.strip()
+                        v = v.strip().strip("'\"")
+                        if k and k not in os.environ:
+                            os.environ[k] = v
+            except Exception:
+                pass
+
+
+def load_config(config_path: Optional[Path] = None) -> KernHellConfig:
+    """Load and return the merged KernHell configuration.
+
+    Parameters
+    ----------
+    config_path:
+        Explicit path to a TOML config file.  When *None*, the function
+        searches the current directory and then ``$HOME`` for
+        ``.kernhellrc.toml``.
+
+    Returns
+    -------
+    KernHellConfig
+        Fully resolved configuration with TOML → env-var priority.
+    """
+    _load_env_file()
+    file_settings: dict = {}
+
+    path = config_path or _find_config_file()
+    if path and path.is_file():
+        with open(path, "rb") as f:
+            file_settings = tomllib.load(f)
+
+    # Environment variables have highest priority over file settings
+    env_overrides = _extract_env_overrides()
+    merged_settings = _deep_merge(file_settings, env_overrides)
+
+    return KernHellConfig(**merged_settings)

kernhell/core/exceptions.py

@@ -0,0 +1,104 @@
+"""KernHell custom exception hierarchy.
+
+Every module raises typed exceptions so the Orchestrator can decide
+whether to retry, skip, or abort cleanly.
+"""
+
+from __future__ import annotations
+
+
+class KernHellError(Exception):
+    """Base exception for all KernHell errors."""
+
+
+# ---------------------------------------------------------------------------
+# Scanner Errors
+# ---------------------------------------------------------------------------
+
+
+class ScannerError(KernHellError):
+    """Raised when the Scanner fails to execute or parse a test run."""
+
+
+class PlaywrightNotInstalledError(ScannerError):
+    """Playwright or its browsers are not installed."""
+
+
+class TestFileNotFoundError(ScannerError):
+    """The specified test file does not exist."""
+
+
+class NoFailuresDetectedError(ScannerError):
+    """The test run completed without any selector failures — nothing to heal."""
+
+
+# ---------------------------------------------------------------------------
+# Pruner Errors
+# ---------------------------------------------------------------------------
+
+
+class PrunerError(KernHellError):
+    """Raised when DOM pruning fails (e.g. malformed HTML)."""
+
+
+# ---------------------------------------------------------------------------
+# Analyzer / Healer Errors
+# ---------------------------------------------------------------------------
+
+
+class AnalyzerError(KernHellError):
+    """Raised when the LLM analysis step fails."""
+
+
+class HealerError(KernHellError):
+    """Raised when the LLM cannot produce a valid selector fix."""
+
+
+class LLMConnectionError(AnalyzerError):
+    """Cannot reach the configured LLM provider."""
+
+
+class LowConfidenceError(HealerError):
+    """The proposed fix has a confidence score below the threshold."""
+
+    def __init__(self, confidence: float, threshold: float) -> None:
+        self.confidence = confidence
+        self.threshold = threshold
+        super().__init__(
+            f"Confidence {confidence:.2f} is below threshold {threshold:.2f}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Patcher Errors
+# ---------------------------------------------------------------------------
+
+
+class PatcherError(KernHellError):
+    """Raised when AST patching fails."""
+
+
+class SelectorNotFoundInASTError(PatcherError):
+    """The broken selector string was not found in the test file's AST."""
+
+
+class VerificationFailedError(PatcherError):
+    """The patched test still fails after applying the fix."""
+
+
+# ---------------------------------------------------------------------------
+# Cache Errors
+# ---------------------------------------------------------------------------
+
+
+class CacheError(KernHellError):
+    """Raised when the semantic cache encounters an error."""
+
+
+# ---------------------------------------------------------------------------
+# Config Errors
+# ---------------------------------------------------------------------------
+
+
+class ConfigError(KernHellError):
+    """Raised when configuration is invalid or missing."""

kernhell/core/models.py

@@ -0,0 +1,174 @@
+"""Core data models for the KernHell healing pipeline.
+
+Every module communicates through these typed Pydantic models.
+This enforces clean boundaries and makes serialization/validation automatic.
+"""
+
+from __future__ import annotations
+
+import enum
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+
+class SelectorType(str, enum.Enum):
+    """Classification of the Playwright selector strategy that was used."""
+
+    CSS = "css"
+    XPATH = "xpath"
+    TEXT = "text"
+    ROLE = "role"
+    TEST_ID = "test_id"
+    LABEL = "label"
+    PLACEHOLDER = "placeholder"
+    UNKNOWN = "unknown"
+
+
+class ErrorType(str, enum.Enum):
+    """Category of Playwright failure."""
+
+    TIMEOUT = "timeout"
+    NOT_FOUND = "not_found"
+    STRICT_MODE = "strict_mode"
+    NAVIGATION = "navigation"
+    OTHER = "other"
+
+
+class FailureType(str, enum.Enum):
+    """Diagnosis of *why* the selector failed."""
+
+    RENAME = "rename"          # Element exists, selector changed
+    MISSING = "missing"        # Element genuinely absent (real bug)
+    STRUCTURAL = "structural"  # DOM structure significantly changed
+    UNKNOWN = "unknown"
+
+
+class SelectorStrategy(str, enum.Enum):
+    """Strategy the healer used to find the replacement selector."""
+
+    ROLE_MATCH = "role_match"
+    TEXT_MATCH = "text_match"
+    ARIA_MATCH = "aria_match"
+    TEST_ID_MATCH = "test_id_match"
+    DATA_ATTR = "data_attr"
+    CSS_FALLBACK = "css_fallback"
+
+
+# ---------------------------------------------------------------------------
+# Pipeline Data Models
+# ---------------------------------------------------------------------------
+
+
+class FailureContext(BaseModel):
+    """Everything captured at the moment a Playwright selector fails.
+
+    Produced by the Scanner, consumed by the Pruner and Analyzer.
+    """
+
+    test_file: Path
+    line_number: int
+    broken_selector: str
+    selector_type: SelectorType = SelectorType.UNKNOWN
+    error_message: str
+    error_type: ErrorType = ErrorType.TIMEOUT
+    live_dom: str = ""
+    page_url: str = ""
+    screenshot_path: Optional[Path] = None
+    surrounding_code: str = ""
+
+    # Metadata
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class PrunedDOM(BaseModel):
+    """The DOM after noise removal by the DOMPruner.
+
+    Carries both the pruned HTML and reduction stats for reporting.
+    """
+
+    html: str
+    original_size: int
+    pruned_size: int
+
+    @property
+    def reduction_pct(self) -> float:
+        """Percentage of bytes removed by pruning."""
+        if self.original_size == 0:
+            return 0.0
+        return round((1 - self.pruned_size / self.original_size) * 100, 1)
+
+
+class Diagnosis(BaseModel):
+    """LLM classification of the failure — produced by the Analyzer.
+
+    RENAME → safe to heal.  MISSING → potential real bug, skip.
+    """
+
+    failure_type: FailureType
+    explanation: str
+    confidence: float = Field(ge=0.0, le=1.0)
+
+
+class SelectorFix(BaseModel):
+    """A proposed replacement selector — produced by the Healer."""
+
+    old_selector: str
+    new_selector: str
+    strategy: SelectorStrategy = SelectorStrategy.CSS_FALLBACK
+    confidence: float = Field(ge=0.0, le=1.0)
+    reasoning: str = ""
+
+    # Populated after Verifier confirms the fix works
+    verified: bool = False
+
+
+class HealingResult(BaseModel):
+    """Outcome of healing a single broken selector."""
+
+    failure: FailureContext
+    pruned_dom: Optional[PrunedDOM] = None
+    diagnosis: Optional[Diagnosis] = None
+    fix: Optional[SelectorFix] = None
+    from_cache: bool = False
+    skipped: bool = False
+    skip_reason: str = ""
+
+
+class HealingReport(BaseModel):
+    """Aggregate report for a full healing run (one or more test files)."""
+
+    test_file: Path
+    results: list[HealingResult] = []
+    duration_ms: int = 0
+
+    @property
+    def total_failures(self) -> int:
+        return len(self.results)
+
+    @property
+    def healed_count(self) -> int:
+        return sum(1 for r in self.results if r.fix and r.fix.verified)
+
+    @property
+    def skipped_count(self) -> int:
+        return sum(1 for r in self.results if r.skipped)
+
+    @property
+    def cache_hits(self) -> int:
+        return sum(1 for r in self.results if r.from_cache)
+
+    @property
+    def llm_calls(self) -> int:
+        return sum(1 for r in self.results if not r.from_cache and r.fix is not None)
+
+    @property
+    def verification_passed(self) -> bool:
+        return all(r.fix.verified for r in self.results if r.fix is not None)