kernhell 0.1.0__py3-none-any.whl

kernhell/core/orchestrator.py

@@ -0,0 +1,245 @@
+"""Healing orchestrator — coordinates the full self-healing pipeline.
+
+Pipeline Flow:
+  1. Scan test file for selector failures.
+  2. Prune live DOM snapshot.
+  3. Query Semantic Vector Cache (zero latency, zero LLM cost).
+  4. On Cache Miss:
+     a. AI Failure Diagnosis (RENAME vs MISSING vs STRUCTURAL).
+     b. Anti-Hallucination Guardrail: Skip genuine MISSING bugs.
+     c. AI Resilient Selector Generation (with DOM presence check).
+  5. Surgical AST/CST Patching (preserves comments, indentation, formatting).
+  6. Test Verification (re-runs test to confirm fix; reverts on failure).
+  7. Store verified fix in Semantic Memory for future instant reuse.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Optional
+
+import structlog
+
+from kernhell.analyzer.analyzer import FailureAnalyzer
+from kernhell.analyzer.healer import SelectorHealer
+from kernhell.cache.cache_manager import CacheManager
+from kernhell.core.config import KernHellConfig, load_config
+from kernhell.core.exceptions import (
+    HealerError,
+    LowConfidenceError,
+    NoFailuresDetectedError,
+    ScannerError,
+)
+from kernhell.core.models import (
+    Diagnosis,
+    FailureContext,
+    FailureType,
+    HealingReport,
+    HealingResult,
+    PrunedDOM,
+    SelectorFix,
+)
+from kernhell.patcher.patcher import SurgicalPatcher
+from kernhell.patcher.verifier import TestVerifier
+from kernhell.pruner.dom_pruner import prune_dom
+from kernhell.scanner.runner import ScannerRunner
+
+logger = structlog.get_logger()
+
+
+class HealingOrchestrator:
+    """Coordinates failure scanning, context capture, DOM pruning, and healing."""
+
+    def __init__(self, config: Optional[KernHellConfig] = None) -> None:
+        self.config = config or load_config()
+        self.scanner = ScannerRunner(self.config)
+        self.cache = CacheManager(self.config)
+        self.analyzer = FailureAnalyzer(self.config)
+        self.healer = SelectorHealer(self.config)
+        self.patcher = SurgicalPatcher()
+        self.verifier = TestVerifier(self.config)
+
+    def scan(self, test_file: Path) -> list[tuple[FailureContext, Optional[PrunedDOM]]]:
+        """Scan a test file for failures and capture pruned DOMs without modifying files."""
+        logger.info("orchestrator.scan.start", test_file=str(test_file))
+        failures = self.scanner.run(test_file)
+
+        results: list[tuple[FailureContext, Optional[PrunedDOM]]] = []
+        for failure in failures:
+            pruned: Optional[PrunedDOM] = None
+            if failure.live_dom:
+                pruned = prune_dom(failure.live_dom)
+            results.append((failure, pruned))
+
+        logger.info("orchestrator.scan.complete", failures_count=len(results))
+        return results
+
+    def heal(self, test_file: Path, dry_run: Optional[bool] = None) -> HealingReport:
+        """Run the autonomous self-healing pipeline for a test file."""
+        start_time = time.perf_counter()
+        is_dry_run = self.config.healing.dry_run if dry_run is None else dry_run
+
+        logger.info(
+            "orchestrator.heal.start",
+            test_file=str(test_file),
+            dry_run=is_dry_run,
+        )
+
+        report = HealingReport(test_file=test_file)
+
+        try:
+            scan_results = self.scan(test_file)
+        except NoFailuresDetectedError as exc:
+            logger.info("orchestrator.no_failures", message=str(exc))
+            report.duration_ms = int((time.perf_counter() - start_time) * 1000)
+            return report
+        except ScannerError as exc:
+            logger.error("orchestrator.scan_failed", error=str(exc))
+            raise
+
+        # Limit heals per file to prevent runaway modification
+        max_heals = self.config.healing.max_heals_per_file
+        if len(scan_results) > max_heals:
+            logger.warning(
+                "orchestrator.exceeded_max_heals",
+                failures=len(scan_results),
+                max_allowed=max_heals,
+            )
+
+        for failure, pruned in scan_results[:max_heals]:
+            result = self._heal_single_failure(
+                test_file=test_file,
+                failure=failure,
+                pruned_dom=pruned,
+                dry_run=is_dry_run,
+            )
+            report.results.append(result)
+
+        report.duration_ms = int((time.perf_counter() - start_time) * 1000)
+        logger.info(
+            "orchestrator.heal.complete",
+            test_file=str(test_file),
+            total=report.total_failures,
+            healed=report.healed_count,
+            skipped=report.skipped_count,
+            from_cache=report.cache_hits,
+            duration_ms=report.duration_ms,
+        )
+        return report
+
+    def _heal_single_failure(
+        self,
+        test_file: Path,
+        failure: FailureContext,
+        pruned_dom: Optional[PrunedDOM],
+        dry_run: bool,
+    ) -> HealingResult:
+        """Execute the healing decision tree for a single broken selector."""
+        # 1. Check Semantic Vector Cache
+        cached_fix, score = self.cache.lookup(
+            broken_selector=failure.broken_selector,
+            context=failure.surrounding_code,
+            page_url=failure.page_url,
+        )
+
+        if cached_fix is not None:
+            logger.info(
+                "orchestrator.cache_hit_applying",
+                selector=failure.broken_selector,
+                score=score,
+            )
+            if not dry_run:
+                self.patcher.patch_test_file(
+                    test_file=test_file,
+                    fix=cached_fix,
+                    line_number=failure.line_number,
+                )
+                self.verifier.verify(test_file, cached_fix)
+            else:
+                cached_fix.verified = True
+
+            return HealingResult(
+                failure=failure,
+                pruned_dom=pruned_dom,
+                fix=cached_fix,
+                from_cache=True,
+            )
+
+        # 2. AI Failure Diagnosis
+        try:
+            diagnosis = self.analyzer.diagnose(failure, pruned_dom)
+        except Exception as exc:
+            logger.error("orchestrator.diagnosis_failed", error=str(exc))
+            return HealingResult(
+                failure=failure,
+                pruned_dom=pruned_dom,
+                skipped=True,
+                skip_reason=f"Diagnosis failed: {exc}",
+            )
+
+        # 3. Anti-Hallucination Guardrail: Never heal genuine MISSING bugs
+        if diagnosis.failure_type == FailureType.MISSING:
+            logger.info(
+                "orchestrator.skip_missing",
+                selector=failure.broken_selector,
+                explanation=diagnosis.explanation,
+            )
+            return HealingResult(
+                failure=failure,
+                pruned_dom=pruned_dom,
+                diagnosis=diagnosis,
+                skipped=True,
+                skip_reason=f"Potential real bug: element is genuinely MISSING ({diagnosis.explanation})",
+            )
+
+        # 4. Generate Resilient Replacement Selector
+        try:
+            fix = self.healer.suggest_fix(failure, diagnosis, pruned_dom)
+        except LowConfidenceError as exc:
+            logger.warning("orchestrator.low_confidence", error=str(exc))
+            return HealingResult(
+                failure=failure,
+                pruned_dom=pruned_dom,
+                diagnosis=diagnosis,
+                skipped=True,
+                skip_reason=str(exc),
+            )
+        except HealerError as exc:
+            logger.warning("orchestrator.healer_error", error=str(exc))
+            return HealingResult(
+                failure=failure,
+                pruned_dom=pruned_dom,
+                diagnosis=diagnosis,
+                skipped=True,
+                skip_reason=str(exc),
+            )
+
+        # 5. Surgical AST/CST Patching & Verification
+        if not dry_run:
+            self.patcher.patch_test_file(
+                test_file=test_file,
+                fix=fix,
+                line_number=failure.line_number,
+            )
+            verified = self.verifier.verify(test_file, fix)
+            if verified:
+                # 6. Store in Semantic Memory
+                self.cache.store(
+                    broken_selector=failure.broken_selector,
+                    fix=fix,
+                    context=failure.surrounding_code,
+                    page_url=failure.page_url,
+                    test_file=str(test_file),
+                )
+        else:
+            # In dry-run mode, simulate successful verification preview
+            fix.verified = True
+
+        return HealingResult(
+            failure=failure,
+            pruned_dom=pruned_dom,
+            diagnosis=diagnosis,
+            fix=fix,
+            from_cache=False,
+        )

kernhell/patcher/patcher.py

@@ -0,0 +1,215 @@
+"""AST / Concrete Syntax Tree Surgical Code Patcher.
+
+Uses `libcst` to surgically replace broken selectors in test files.
+Unlike Python's standard `ast` module, `libcst` preserves:
+  - All original indentation, spaces, and blank lines
+  - All inline and block comments (# ...)
+  - All docstrings and quote styles (' vs ")
+  - All unrelated code and imports
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+
+import structlog
+
+from kernhell.core.exceptions import PatcherError, SelectorNotFoundInASTError
+from kernhell.core.models import SelectorFix
+from kernhell.utils.file_utils import backup_file, read_file, write_file
+
+logger = structlog.get_logger()
+
+
+class SurgicalPatcher:
+    """Surgically edits test files using Concrete Syntax Tree parsing."""
+
+    def __init__(self) -> None:
+        pass
+
+    def patch_test_file(
+        self,
+        test_file: Path,
+        fix: SelectorFix,
+        line_number: Optional[int] = None,
+        create_backup: bool = True,
+    ) -> str:
+        """Surgically replace the broken selector in the test file.
+
+        Parameters
+        ----------
+        test_file : Path
+            Path to the test file on disk.
+        fix : SelectorFix
+            The proposed fix containing old_selector and new_selector.
+        line_number : Optional[int]
+            The line number where failure occurred (for disambiguation).
+        create_backup : bool
+            Whether to write a .kernhell.bak file before mutating.
+
+        Returns
+        -------
+        str
+            The patched source code.
+        """
+        resolved = test_file.resolve()
+        source_code = read_file(resolved)
+
+        logger.info(
+            "patcher.start",
+            file=str(resolved),
+            old=fix.old_selector,
+            new=fix.new_selector,
+            line=line_number,
+        )
+
+        if create_backup:
+            backup_file(resolved)
+
+        patched_code = self.apply_patch(
+            source_code=source_code,
+            old_selector=fix.old_selector,
+            new_selector=fix.new_selector,
+            target_line=line_number,
+        )
+
+        write_file(resolved, patched_code)
+        logger.info("patcher.complete", file=str(resolved))
+        return patched_code
+
+    def apply_patch(
+        self,
+        source_code: str,
+        old_selector: str,
+        new_selector: str,
+        target_line: Optional[int] = None,
+    ) -> str:
+        """Apply CST surgical replacement to source code string.
+
+        Tries `libcst` first. If `libcst` is unavailable or parsing fails,
+        falls back to a high-precision line-scoped surgical string replacement.
+        """
+        try:
+            import libcst as cst
+
+            return self._cst_transform(
+                source_code=source_code,
+                old_selector=old_selector,
+                new_selector=new_selector,
+                target_line=target_line,
+            )
+        except ImportError:
+            logger.warning("patcher.libcst_not_available.using_surgical_regex")
+            return self._surgical_line_transform(
+                source_code=source_code,
+                old_selector=old_selector,
+                new_selector=new_selector,
+                target_line=target_line,
+            )
+        except Exception as exc:
+            logger.warning("patcher.cst_failed.falling_back_to_surgical_regex", error=str(exc))
+            return self._surgical_line_transform(
+                source_code=source_code,
+                old_selector=old_selector,
+                new_selector=new_selector,
+                target_line=target_line,
+            )
+
+    def _cst_transform(
+        self,
+        source_code: str,
+        old_selector: str,
+        new_selector: str,
+        target_line: Optional[int] = None,
+    ) -> str:
+        """CST Transformer implementation."""
+        import libcst as cst
+
+        module = cst.parse_module(source_code)
+
+        # Clean selector text (strip quotes if raw string)
+        raw_old = old_selector.strip("'\"")
+
+        class SelectorStringReplacer(cst.CSTTransformer):
+            def __init__(self) -> None:
+                self.replaced_count = 0
+
+            def leave_SimpleString(
+                self,
+                original_node: cst.SimpleString,
+                updated_node: cst.SimpleString,
+            ) -> cst.SimpleString:
+                # Value includes surrounding quotes, e.g. '"#buy-now"'
+                val = original_node.evaluated_value
+                if val == raw_old:
+                    quote = original_node.value[0]
+                    # Format replacement preserving quote style
+                    new_val = f"{quote}{new_selector.strip('\'"')}{quote}"
+                    self.replaced_count += 1
+                    return updated_node.with_changes(value=new_val)
+                return updated_node
+
+        replacer = SelectorStringReplacer()
+        transformed = module.visit(replacer)
+
+        if replacer.replaced_count == 0:
+            # If literal string wasn't found in quotes, try surgical line transform
+            return self._surgical_line_transform(
+                source_code=source_code,
+                old_selector=old_selector,
+                new_selector=new_selector,
+                target_line=target_line,
+            )
+
+        return transformed.code
+
+    def _surgical_line_transform(
+        self,
+        source_code: str,
+        old_selector: str,
+        new_selector: str,
+        target_line: Optional[int] = None,
+    ) -> str:
+        """High-precision line-scoped replacement.
+
+        Targets only the specific line (or lines near it) where the failure occurred.
+        Preserves indentation, comments, and spacing.
+        """
+        raw_old = old_selector.strip("'\"")
+        raw_new = new_selector.strip("'\"")
+
+        lines = source_code.splitlines(keepends=True)
+        replaced = False
+
+        if target_line is not None and 1 <= target_line <= len(lines):
+            # Try target line first
+            idx = target_line - 1
+            if raw_old in lines[idx]:
+                lines[idx] = lines[idx].replace(raw_old, raw_new)
+                replaced = True
+            else:
+                # Search window of ±5 lines around target_line
+                start = max(0, idx - 5)
+                end = min(len(lines), idx + 6)
+                for i in range(start, end):
+                    if raw_old in lines[i]:
+                        lines[i] = lines[i].replace(raw_old, raw_new)
+                        replaced = True
+                        break
+
+        # Fallback: replace first occurrence across whole file
+        if not replaced:
+            for i, line in enumerate(lines):
+                if raw_old in line:
+                    lines[i] = line.replace(raw_old, raw_new)
+                    replaced = True
+                    break
+
+        if not replaced:
+            raise SelectorNotFoundInASTError(
+                f"Broken selector '{old_selector}' could not be located in test file."
+            )
+
+        return "".join(lines)

kernhell/patcher/verifier.py

@@ -0,0 +1,82 @@
+"""Test Verifier — re-runs tests to confirm that patches actually heal the test.
+
+If verification succeeds: marks fix as verified and cleans up backups.
+If verification fails: reverts the test file from backup to prevent corruption.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import structlog
+
+from kernhell.core.config import KernHellConfig
+from kernhell.core.exceptions import NoFailuresDetectedError, VerificationFailedError
+from kernhell.core.models import SelectorFix
+from kernhell.scanner.runner import ScannerRunner
+from kernhell.utils.file_utils import restore_from_backup
+
+logger = structlog.get_logger()
+
+
+class TestVerifier:
+    """Verifies that an applied patch successfully allows the test to pass."""
+
+    __test__ = False
+
+    def __init__(self, config: KernHellConfig) -> None:
+        self.config = config
+        self.scanner = ScannerRunner(config)
+
+    def verify(
+        self,
+        test_file: Path,
+        fix: SelectorFix,
+        revert_on_failure: bool = True,
+    ) -> bool:
+        """Re-run the test to verify whether the fix resolved the failure.
+
+        Parameters
+        ----------
+        test_file : Path
+            Path to the patched test file.
+        fix : SelectorFix
+            The fix that was applied.
+        revert_on_failure : bool
+            Whether to automatically restore the file from backup on failure.
+
+        Returns
+        -------
+        bool
+            True if verification passed (all tests clean).
+        """
+        logger.info(
+            "verifier.start",
+            file=str(test_file),
+            new_selector=fix.new_selector,
+        )
+
+        try:
+            # Re-running the test. If NoFailuresDetectedError is raised, it PASSED!
+            self.scanner.run(test_file)
+
+            # If scanner.run returned a list of failures without raising NoFailuresDetectedError,
+            # then there are still failures remaining.
+            logger.warning("verifier.still_failing", file=str(test_file))
+            if revert_on_failure:
+                restore_from_backup(test_file)
+            fix.verified = False
+            return False
+
+        except NoFailuresDetectedError:
+            # The test passed cleanly! Fix verified.
+            logger.info("verifier.passed", file=str(test_file))
+            fix.verified = True
+            return True
+
+        except Exception as exc:
+            logger.warning("verifier.exception", file=str(test_file), error=str(exc))
+            if revert_on_failure:
+                restore_from_backup(test_file)
+            fix.verified = False
+            return False

kernhell/pruner/__init__.py

@@ -0,0 +1 @@
+"""Pruner package — DOM noise removal."""