codexa 0.4.0__py3-none-any.whl

semantic_code_intelligence/plugins/examples/code_quality.py

@@ -0,0 +1,73 @@
+"""Sample CodexA plugin — custom code validator.
+
+Demonstrates the CUSTOM_VALIDATION hook to add project-specific
+code quality checks. This example flags common issues like TODO
+comments and print statements in production code.
+
+Usage:
+    1. Copy this file to `.codexa/plugins/`
+    2. Custom validations will run during `codexa review`
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from semantic_code_intelligence.plugins import PluginBase, PluginHook, PluginMetadata
+
+
+class CodeQualityPlugin(PluginBase):
+    """Custom code quality validator."""
+
+    def metadata(self) -> PluginMetadata:
+        return PluginMetadata(
+            name="code-quality",
+            version="0.1.0",
+            description="Custom code quality validation rules",
+            author="CodexA Team",
+            hooks=[PluginHook.CUSTOM_VALIDATION],
+        )
+
+    def on_hook(self, hook: PluginHook, data: dict[str, Any]) -> dict[str, Any]:
+        """Run custom validation rules.
+
+        CUSTOM_VALIDATION data contract:
+            - code: str — source code to validate
+            - issues: list — existing issues (append to this)
+        """
+        if hook != PluginHook.CUSTOM_VALIDATION:
+            return data
+
+        code = data.get("code", "")
+        issues = data.get("issues", [])
+
+        # Flag TODO/FIXME/HACK comments
+        for i, line in enumerate(code.splitlines(), 1):
+            for tag in ("TODO", "FIXME", "HACK", "XXX"):
+                if tag in line:
+                    issues.append({
+                        "line": i,
+                        "description": f"{tag} comment found",
+                        "severity": "info",
+                        "source": "code-quality",
+                    })
+
+        # Flag bare print() statements (suggests using logging)
+        for i, line in enumerate(code.splitlines(), 1):
+            stripped = line.strip()
+            if stripped.startswith("print(") and not stripped.startswith("print(f\"DEBUG"):
+                issues.append({
+                    "line": i,
+                    "description": "Consider using logging instead of print()",
+                    "severity": "warning",
+                    "source": "code-quality",
+                })
+
+        data["issues"] = issues
+        return data
+
+
+def create_plugin() -> CodeQualityPlugin:
+    """Factory function for plugin discovery."""
+    return CodeQualityPlugin()

semantic_code_intelligence/plugins/examples/search_annotator.py

@@ -0,0 +1,56 @@
+"""Sample CodexA plugin — search result annotator.
+
+This example plugin demonstrates how to build a CodexA plugin that
+hooks into the search pipeline. It adds a timestamp and custom tag
+to every search result passing through.
+
+Usage:
+    1. Copy this file to `.codexa/plugins/`
+    2. Results from `codexa search` will include the annotation
+
+This serves as a starting point for building your own plugins.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from semantic_code_intelligence.plugins import PluginBase, PluginHook, PluginMetadata
+
+
+class SearchAnnotatorPlugin(PluginBase):
+    """Annotates search results with custom metadata."""
+
+    def metadata(self) -> PluginMetadata:
+        return PluginMetadata(
+            name="search-annotator",
+            version="0.1.0",
+            description="Annotates search results with custom metadata",
+            author="CodexA Team",
+            hooks=[PluginHook.POST_SEARCH],
+        )
+
+    def activate(self, context: dict[str, Any]) -> None:
+        """Store activation time for annotation."""
+        self._activated_at = time.time()
+
+    def on_hook(self, hook: PluginHook, data: dict[str, Any]) -> dict[str, Any]:
+        """Add annotation to search results.
+
+        POST_SEARCH data contract:
+            - results: list of search result dicts
+            - query: the original search query
+        """
+        if hook == PluginHook.POST_SEARCH:
+            results = data.get("results", [])
+            for result in results:
+                result["annotated_by"] = "search-annotator"
+                result["annotated_at"] = time.time()
+            data["annotation_count"] = len(results)
+        return data
+
+
+def create_plugin() -> SearchAnnotatorPlugin:
+    """Factory function for plugin discovery."""
+    return SearchAnnotatorPlugin()

semantic_code_intelligence/scalability/__init__.py

@@ -0,0 +1,205 @@
+"""Scalability utilities — batch processing, memory management, performance.
+
+Provides:
+- BatchProcessor: processes items in configurable batches
+- MemoryAwareEmbedder: generates embeddings with memory-safe batching
+- ParallelScanner: concurrent file scanning
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, TypeVar
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from semantic_code_intelligence.utils.logging import get_logger
+
+logger = get_logger("scalability")
+
+T = TypeVar("T")
+R = TypeVar("R")
+
+
+# ---------------------------------------------------------------------------
+# Batch Processor
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BatchStats:
+    """Statistics for a batch processing run."""
+
+    total_items: int = 0
+    batches_processed: int = 0
+    items_succeeded: int = 0
+    items_failed: int = 0
+    elapsed_seconds: float = 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "total_items": self.total_items,
+            "batches_processed": self.batches_processed,
+            "items_succeeded": self.items_succeeded,
+            "items_failed": self.items_failed,
+            "elapsed_seconds": round(self.elapsed_seconds, 3),
+            "items_per_second": round(
+                self.items_succeeded / self.elapsed_seconds, 2
+            ) if self.elapsed_seconds > 0 else 0,
+        }
+
+
+class BatchProcessor:
+    """Process items in configurable batches with progress tracking.
+
+    Useful for chunking/embedding large sets of files without loading
+    everything into memory at once.
+    """
+
+    def __init__(self, batch_size: int = 64) -> None:
+        self._batch_size = max(1, batch_size)
+
+    @property
+    def batch_size(self) -> int:
+        return self._batch_size
+
+    def process(
+        self,
+        items: list[T],
+        processor: Callable[[list[T]], list[R]],
+        on_batch: Callable[[int, int], None] | None = None,
+    ) -> tuple[list[R], BatchStats]:
+        """Process items in batches.
+
+        Args:
+            items: Items to process.
+            processor: Function that processes a batch of items.
+            on_batch: Optional callback(batch_num, total_batches).
+
+        Returns:
+            Tuple of (all_results, stats).
+        """
+        stats = BatchStats(total_items=len(items))
+        all_results: list[R] = []
+        start = time.time()
+
+        total_batches = (len(items) + self._batch_size - 1) // self._batch_size
+
+        for batch_idx in range(total_batches):
+            offset = batch_idx * self._batch_size
+            batch = items[offset : offset + self._batch_size]
+
+            if on_batch:
+                on_batch(batch_idx + 1, total_batches)
+
+            try:
+                results = processor(batch)
+                all_results.extend(results)
+                stats.items_succeeded += len(batch)
+            except Exception:
+                logger.exception("Batch %d/%d failed", batch_idx + 1, total_batches)
+                stats.items_failed += len(batch)
+
+            stats.batches_processed += 1
+
+        stats.elapsed_seconds = time.time() - start
+        return all_results, stats
+
+
+# ---------------------------------------------------------------------------
+# Memory-aware Embedding Generator
+# ---------------------------------------------------------------------------
+
+class MemoryAwareEmbedder:
+    """Generates embeddings in memory-safe batches.
+
+    Wraps the base generator to handle large numbers of texts without
+    exhausting GPU/CPU memory.
+    """
+
+    def __init__(
+        self,
+        model_name: str = "all-MiniLM-L6-v2",
+        batch_size: int = 64,
+    ) -> None:
+        self._model_name = model_name
+        self._batch_size = batch_size
+        self._processor = BatchProcessor(batch_size)
+
+    def generate(
+        self,
+        texts: list[str],
+        show_progress: bool = False,
+    ) -> Any:
+        """Generate embeddings in batches, concatenating results.
+
+        Returns:
+            numpy ndarray of shape (len(texts), dimension).
+        """
+        import numpy as np
+
+        from semantic_code_intelligence.embeddings.generator import generate_embeddings
+
+        def _embed_batch(batch: list[str]) -> list[Any]:
+            emb = generate_embeddings(batch, model_name=self._model_name)
+            return [emb]  # Return as single item to be concatenated
+
+        def _on_batch(current: int, total: int) -> None:
+            if show_progress:
+                logger.info("Embedding batch %d/%d", current, total)
+
+        raw_results, stats = self._processor.process(
+            texts, _embed_batch, on_batch=_on_batch if show_progress else None
+        )
+
+        if not raw_results:
+            return np.empty((0, 0))
+
+        return np.vstack(raw_results)
+
+
+# ---------------------------------------------------------------------------
+# Parallel File Scanner
+# ---------------------------------------------------------------------------
+
+class ParallelScanner:
+    """Scan and process files using thread-based parallelism.
+
+    Useful for I/O-bound operations like reading/hashing multiple files.
+    """
+
+    def __init__(self, max_workers: int = 4) -> None:
+        self._max_workers = max(1, max_workers)
+
+    def scan_and_process(
+        self,
+        file_paths: list[Path],
+        processor: Callable[[Path], R],
+    ) -> tuple[list[R], list[str]]:
+        """Process files in parallel.
+
+        Args:
+            file_paths: Files to process.
+            processor: Function to apply to each file.
+
+        Returns:
+            Tuple of (results, error_messages).
+        """
+        results: list[R] = []
+        errors: list[str] = []
+
+        with ThreadPoolExecutor(max_workers=self._max_workers) as executor:
+            future_to_path = {
+                executor.submit(processor, fp): fp for fp in file_paths
+            }
+
+            for future in as_completed(future_to_path):
+                fp = future_to_path[future]
+                try:
+                    result = future.result()
+                    results.append(result)
+                except Exception as e:
+                    errors.append(f"{fp}: {e}")
+                    logger.debug("Failed to process %s: %s", fp, e)
+
+        return results, errors

semantic_code_intelligence/search/formatter.py

@@ -0,0 +1,123 @@
+"""Search result formatter — renders search results for CLI and JSON output."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.table import Table
+from rich.text import Text
+
+from semantic_code_intelligence.services.search_service import SearchResult
+from semantic_code_intelligence.utils.logging import console
+
+
+def format_results_json(query: str, results: list[SearchResult], top_k: int) -> str:
+    """Format search results as a JSON string for AI integration.
+
+    Args:
+        query: The search query.
+        results: List of SearchResult objects.
+        top_k: Number of results requested.
+
+    Returns:
+        Pretty-printed JSON string.
+    """
+    output: dict[str, Any] = {
+        "query": query,
+        "top_k": top_k,
+        "result_count": len(results),
+        "results": [r.to_dict() for r in results],
+    }
+    return json.dumps(output, indent=2, ensure_ascii=False)
+
+
+def format_results_jsonl(results: list[SearchResult]) -> str:
+    """Format search results as JSONL (one JSON object per line).
+
+    Each line is a self-contained JSON object suitable for piping into
+    ``jq``, ``fzf``, or streaming ingestion.
+    """
+    lines: list[str] = []
+    for r in results:
+        lines.append(json.dumps(r.to_dict(), ensure_ascii=False))
+    return "\n".join(lines)
+
+
+def format_results_rich(
+    query: str,
+    results: list[SearchResult],
+    *,
+    line_numbers: bool = False,
+    context_lines: int = 0,
+) -> None:
+    """Print search results as rich formatted output to the console.
+
+    Args:
+        query: The search query.
+        results: List of SearchResult objects.
+        line_numbers: If True, prefix code lines with line numbers (grep -n).
+        context_lines: Number of extra context lines to display around content.
+    """
+    if not results:
+        console.print(f"\n[yellow]No results found for:[/yellow] \"{query}\"\n")
+        return
+
+    console.print(f"\n[bold cyan]Search results for:[/bold cyan] \"{query}\"")
+    console.print(f"[dim]Found {len(results)} results[/dim]\n")
+
+    for i, result in enumerate(results, 1):
+        # Optionally expand context lines from the file on disk
+        content = result.content
+        start = result.start_line
+        if context_lines > 0:
+            content, start = _expand_context(result, context_lines)
+
+        # Header with file path, lines, and score
+        header = (
+            f"[bold]{result.file_path}[/bold] "
+            f"[dim]L{start}-L{result.end_line + context_lines}[/dim] "
+            f"[green]score: {result.score:.4f}[/green]"
+        )
+
+        # Code snippet with syntax highlighting
+        try:
+            syntax: str | Syntax = Syntax(
+                content.rstrip(),
+                result.language if result.language != "unknown" else "text",
+                line_numbers=True if line_numbers else True,
+                start_line=start,
+                theme="monokai",
+            )
+        except Exception:
+            syntax = content.rstrip()
+
+        panel = Panel(
+            syntax,
+            title=f"[bold]#{i}[/bold]  {header}",
+            title_align="left",
+            border_style="cyan",
+            padding=(0, 1),
+        )
+        console.print(panel)
+
+
+def _expand_context(result: SearchResult, ctx: int) -> tuple[str, int]:
+    """Read extra context lines from the original file on disk."""
+    from pathlib import Path
+
+    fp = Path(result.file_path)
+    if not fp.is_file():
+        return result.content, result.start_line
+    try:
+        lines = fp.read_text(encoding="utf-8", errors="replace").splitlines(keepends=True)
+    except OSError:
+        return result.content, result.start_line
+
+    new_start = max(1, result.start_line - ctx)
+    new_end = min(len(lines), result.end_line + ctx)
+    expanded = "".join(lines[new_start - 1 : new_end])
+    return expanded, new_start