shotgun-sh 0.2.29.dev2__py3-none-any.whl → 0.6.1.dev1__py3-none-any.whl

shotgun/codebase/benchmarks/exporters.py

@@ -0,0 +1,119 @@
+"""Metrics exporters for saving benchmark results to files.
+
+This module provides the MetricsExporter class for exporting benchmark
+results to various file formats.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from shotgun.codebase.benchmarks.formatters import (
+    JsonFormatter,
+    MarkdownFormatter,
+    MetricsDisplayOptions,
+)
+from shotgun.logging_config import get_logger
+
+if TYPE_CHECKING:
+    from shotgun.codebase.benchmarks.models import BenchmarkResults
+
+logger = get_logger(__name__)
+
+
+class MetricsExporter:
+    """Export benchmark metrics to files."""
+
+    def __init__(self) -> None:
+        """Initialize metrics exporter."""
+        self._format_map = {
+            ".json": self._export_json,
+            ".md": self._export_markdown,
+            ".markdown": self._export_markdown,
+        }
+
+    def export(
+        self,
+        results: BenchmarkResults,
+        filepath: Path | str,
+        format: str | None = None,
+        options: MetricsDisplayOptions | None = None,
+    ) -> None:
+        """Export benchmark results to file.
+
+        The format is auto-detected from the file extension if not specified.
+
+        Args:
+            results: Benchmark results to export
+            filepath: Path to export file
+            format: Optional format override ("json", "markdown")
+            options: Display options for controlling what to include
+
+        Raises:
+            ValueError: If format cannot be determined or is unsupported
+            OSError: If file cannot be written
+        """
+        filepath = Path(filepath)
+        options = options or MetricsDisplayOptions()
+
+        # Determine format
+        if format:
+            format_lower = format.lower()
+            if format_lower == "json":
+                export_func = self._export_json
+            elif format_lower in ("markdown", "md"):
+                export_func = self._export_markdown
+            else:
+                raise ValueError(f"Unknown export format: {format}")
+        else:
+            # Auto-detect from extension
+            suffix = filepath.suffix.lower()
+            if suffix not in self._format_map:
+                raise ValueError(
+                    f"Cannot determine format from extension '{suffix}'. "
+                    f"Supported extensions: {', '.join(self._format_map.keys())}. "
+                    f"Or specify format explicitly."
+                )
+            export_func = self._format_map[suffix]
+
+        # Ensure parent directory exists
+        filepath.parent.mkdir(parents=True, exist_ok=True)
+
+        # Export
+        export_func(results, filepath, options)
+        logger.info(f"Exported benchmark results to {filepath}")
+
+    def _export_json(
+        self,
+        results: BenchmarkResults,
+        filepath: Path,
+        options: MetricsDisplayOptions,
+    ) -> None:
+        """Export results to JSON file.
+
+        Args:
+            results: Benchmark results
+            filepath: Output path
+            options: Display options
+        """
+        formatter = JsonFormatter()
+        content = formatter.format_results(results, options)
+        filepath.write_text(content)
+
+    def _export_markdown(
+        self,
+        results: BenchmarkResults,
+        filepath: Path,
+        options: MetricsDisplayOptions,
+    ) -> None:
+        """Export results to Markdown file.
+
+        Args:
+            results: Benchmark results
+            filepath: Output path
+            options: Display options
+        """
+        formatter = MarkdownFormatter()
+        content = formatter.format_results(results, options)
+        filepath.write_text(content)

shotgun/codebase/benchmarks/formatters/__init__.py

@@ -0,0 +1,49 @@
+"""Result formatters for benchmark output.
+
+This package provides formatters for displaying benchmark results in various
+formats: JSON and Markdown.
+"""
+
+from shotgun.codebase.benchmarks.formatters.base import ResultFormatter
+from shotgun.codebase.benchmarks.formatters.json_formatter import JsonFormatter
+from shotgun.codebase.benchmarks.formatters.markdown import MarkdownFormatter
+
+# Re-export MetricsDisplayOptions from models for convenience
+from shotgun.codebase.benchmarks.models import MetricsDisplayOptions
+
+__all__ = [
+    "JsonFormatter",
+    "MarkdownFormatter",
+    "MetricsDisplayOptions",
+    "ResultFormatter",
+    "get_formatter",
+]
+
+
+def get_formatter(
+    output_format: str,
+) -> JsonFormatter | MarkdownFormatter:
+    """Get appropriate formatter for output format.
+
+    Args:
+        output_format: Format name - "json" or "markdown"
+
+    Returns:
+        Formatter instance
+
+    Raises:
+        ValueError: If output format is unknown
+    """
+    formatters: dict[str, type[JsonFormatter | MarkdownFormatter]] = {
+        "json": JsonFormatter,
+        "markdown": MarkdownFormatter,
+    }
+
+    format_lower = output_format.lower()
+    if format_lower not in formatters:
+        raise ValueError(
+            f"Unknown output format: {output_format}. "
+            f"Valid formats: {', '.join(formatters.keys())}"
+        )
+
+    return formatters[format_lower]()

shotgun/codebase/benchmarks/formatters/base.py

@@ -0,0 +1,34 @@
+"""Base classes and protocols for formatters.
+
+This module provides the Protocol interface that all formatters implement.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from shotgun.codebase.benchmarks.models import (
+        BenchmarkResults,
+        MetricsDisplayOptions,
+    )
+
+
+class ResultFormatter(Protocol):
+    """Protocol for formatting benchmark results."""
+
+    def format_results(
+        self,
+        results: BenchmarkResults,
+        options: MetricsDisplayOptions,
+    ) -> str:
+        """Format benchmark results for display.
+
+        Args:
+            results: Benchmark results to format
+            options: Display options
+
+        Returns:
+            Formatted string ready for output
+        """
+        ...

shotgun/codebase/benchmarks/formatters/json_formatter.py

@@ -0,0 +1,106 @@
+"""JSON formatter for benchmark results.
+
+This module provides the JsonFormatter class for displaying benchmark results
+as JSON.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from shotgun.codebase.benchmarks.models import (
+        BenchmarkResults,
+        MetricsDisplayOptions,
+    )
+
+
+class JsonFormatter:
+    """Format benchmark results as JSON."""
+
+    def format_results(
+        self,
+        results: BenchmarkResults,
+        options: MetricsDisplayOptions,
+    ) -> str:
+        """Format benchmark results as JSON.
+
+        Args:
+            results: Benchmark results to format
+            options: Display options
+
+        Returns:
+            JSON string
+        """
+        data = {
+            "codebase_name": results.codebase_name,
+            "codebase_path": results.codebase_path,
+            "config": {
+                "mode": results.config.mode,
+                "worker_count": results.config.worker_count,
+                "iterations": results.config.iterations,
+                "warmup_iterations": results.config.warmup_iterations,
+            },
+            "statistics": {
+                "avg_duration_seconds": results.avg_duration_seconds,
+                "min_duration_seconds": results.min_duration_seconds,
+                "max_duration_seconds": results.max_duration_seconds,
+                "std_dev_seconds": results.std_dev_seconds,
+                "avg_throughput": results.avg_throughput,
+                "avg_memory_mb": results.avg_memory_mb,
+                "speedup_factor": results.speedup_factor,
+                "efficiency": results.efficiency,
+            },
+            "runs": [],
+        }
+
+        # Add run data
+        for run in results.measured_runs:
+            run_data: dict[str, object] = {
+                "run_id": run.run_id,
+                "duration_seconds": run.metrics.total_duration_seconds,
+                "total_files": run.metrics.total_files,
+                "total_nodes": run.metrics.total_nodes,
+                "total_relationships": run.metrics.total_relationships,
+                "throughput": run.metrics.avg_throughput,
+                "peak_memory_mb": run.metrics.peak_memory_mb,
+            }
+
+            # Add phase metrics
+            if options.show_phase_metrics:
+                phase_data: dict[str, dict[str, object]] = {}
+                for name, phase in run.metrics.phase_metrics.items():
+                    phase_data[name] = {
+                        "duration_seconds": phase.duration_seconds,
+                        "items_processed": phase.items_processed,
+                        "throughput": phase.throughput,
+                        "memory_mb": phase.memory_mb,
+                    }
+                run_data["phase_metrics"] = phase_data
+
+            # Add file metrics
+            if options.show_file_metrics and run.metrics.file_metrics:
+                file_metrics_list = run.metrics.file_metrics
+                if options.top_n_files:
+                    file_metrics_list = sorted(
+                        file_metrics_list,
+                        key=lambda f: f.parse_time_ms,
+                        reverse=True,
+                    )[: options.top_n_files]
+
+                run_data["file_metrics"] = [
+                    {
+                        "file_path": f.file_path,
+                        "language": f.language,
+                        "file_size_bytes": f.file_size_bytes,
+                        "parse_time_ms": f.parse_time_ms,
+                        "definitions_extracted": f.definitions_extracted,
+                    }
+                    for f in file_metrics_list
+                ]
+
+            runs_list: list[dict[str, object]] = data["runs"]  # type: ignore[assignment]
+            runs_list.append(run_data)
+
+        return json.dumps(data, indent=2)

shotgun/codebase/benchmarks/formatters/markdown.py

@@ -0,0 +1,136 @@
+"""Markdown formatter for benchmark results.
+
+This module provides the MarkdownFormatter class for displaying benchmark results
+as GitHub-compatible markdown.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from shotgun.codebase.benchmarks.models import (
+        BenchmarkResults,
+        MetricsDisplayOptions,
+    )
+
+
+class MarkdownFormatter:
+    """Format benchmark results as GitHub-compatible markdown."""
+
+    def format_results(
+        self,
+        results: BenchmarkResults,
+        options: MetricsDisplayOptions,
+    ) -> str:
+        """Format benchmark results as markdown.
+
+        Args:
+            results: Benchmark results to format
+            options: Display options
+
+        Returns:
+            Markdown string
+        """
+        lines = []
+
+        # Header
+        lines.append(f"# Indexing Benchmark: {results.codebase_name}")
+        lines.append("")
+        lines.append(f"**Path:** `{results.codebase_path}`")
+
+        mode = results.config.mode.capitalize()
+        worker_info = ""
+        if results.config.mode == "parallel":
+            worker_count = results.config.worker_count or "auto"
+            worker_info = f" ({worker_count} workers)"
+        lines.append(f"**Mode:** {mode}{worker_info}")
+        lines.append(
+            f"**Iterations:** {results.config.iterations} ({results.config.warmup_iterations} warmup)"
+        )
+        lines.append("")
+
+        # Summary statistics
+        lines.append("## Summary")
+        lines.append("")
+        lines.append("| Metric | Value |")
+        lines.append("|--------|-------|")
+
+        if results.config.iterations > 1:
+            lines.append(f"| Duration (avg) | {results.avg_duration_seconds:.2f}s |")
+            lines.append(f"| Duration (min) | {results.min_duration_seconds:.2f}s |")
+            lines.append(f"| Duration (max) | {results.max_duration_seconds:.2f}s |")
+            lines.append(f"| Duration (std dev) | {results.std_dev_seconds:.2f}s |")
+        else:
+            lines.append(f"| Duration | {results.avg_duration_seconds:.2f}s |")
+
+        lines.append(f"| Throughput | {results.avg_throughput:.1f} files/s |")
+        lines.append(f"| Peak Memory | {results.avg_memory_mb:.1f} MB |")
+
+        metrics = results.get_last_metrics()
+        if metrics:
+            lines.append(f"| Files Processed | {metrics.total_files:,} |")
+            lines.append(f"| Nodes Created | {metrics.total_nodes:,} |")
+            lines.append(f"| Relationships | {metrics.total_relationships:,} |")
+
+        if results.efficiency:
+            lines.append(
+                f"| Parallelism Efficiency | {results.efficiency * 100:.0f}% |"
+            )
+        if results.speedup_factor:
+            lines.append(f"| Speedup | {results.speedup_factor:.2f}x |")
+
+        lines.append("")
+
+        # Phase breakdown
+        if metrics and options.show_phase_metrics and not options.show_summary_only:
+            lines.append("## Phase Breakdown")
+            lines.append("")
+            lines.append("| Phase | Duration | Items | Throughput | Memory |")
+            lines.append("|-------|----------|-------|------------|--------|")
+
+            for name, phase in metrics.phase_metrics.items():
+                lines.append(
+                    f"| {name} | {phase.duration_seconds:.2f}s | "
+                    f"{phase.items_processed} | {phase.throughput:.1f}/s | "
+                    f"{phase.memory_mb:.1f} MB |"
+                )
+
+            lines.append("")
+
+        # File metrics
+        if (
+            metrics
+            and options.show_file_metrics
+            and metrics.file_metrics
+            and not options.show_summary_only
+        ):
+            file_metrics = sorted(
+                metrics.file_metrics,
+                key=lambda f: f.parse_time_ms,
+                reverse=True,
+            )
+            if options.top_n_files:
+                file_metrics = file_metrics[: options.top_n_files]
+
+            if file_metrics:
+                title = "File Metrics"
+                if options.top_n_files:
+                    title = f"Top {len(file_metrics)} Slowest Files"
+
+                lines.append(f"## {title}")
+                lines.append("")
+                lines.append("| File | Language | Size | Duration | Definitions |")
+                lines.append("|------|----------|------|----------|-------------|")
+
+                for f in file_metrics:
+                    size_kb = f.file_size_bytes / 1024
+                    lines.append(
+                        f"| `{f.file_path}` | {f.language} | "
+                        f"{size_kb:.1f} KB | {f.parse_time_ms:.1f}ms | "
+                        f"{f.definitions_extracted} |"
+                    )
+
+                lines.append("")
+
+        return "\n".join(lines)

shotgun/codebase/benchmarks/models.py

@@ -0,0 +1,129 @@
+"""Pydantic models for benchmark system.
+
+This module contains all data models used by the benchmark system.
+"""
+
+from __future__ import annotations
+
+import statistics
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+from shotgun.codebase.core.metrics_types import IndexingMetrics
+
+
+class BenchmarkMode(StrEnum):
+    """Execution mode for benchmarks."""
+
+    PARALLEL = "parallel"
+    SEQUENTIAL = "sequential"
+
+
+class OutputFormat(StrEnum):
+    """Output format for benchmark results."""
+
+    JSON = "json"
+    MARKDOWN = "markdown"
+
+
+class BenchmarkConfig(BaseModel):
+    """Configuration for benchmark execution."""
+
+    mode: BenchmarkMode = BenchmarkMode.PARALLEL
+    worker_count: int | None = None
+    iterations: int = 1
+    warmup_iterations: int = 0
+    collect_file_metrics: bool = True
+    collect_worker_metrics: bool = True
+
+
+class BenchmarkRun(BaseModel):
+    """Results from a single benchmark run."""
+
+    run_id: int
+    is_warmup: bool
+    metrics: IndexingMetrics
+
+
+class BenchmarkResults(BaseModel):
+    """Complete results from benchmark execution."""
+
+    codebase_name: str
+    codebase_path: str
+    config: BenchmarkConfig
+    warmup_runs: list[BenchmarkRun] = Field(default_factory=list)
+    measured_runs: list[BenchmarkRun] = Field(default_factory=list)
+
+    # Aggregate statistics (calculated after runs)
+    avg_duration_seconds: float = 0.0
+    min_duration_seconds: float = 0.0
+    max_duration_seconds: float = 0.0
+    std_dev_seconds: float = 0.0
+    avg_throughput: float = 0.0
+    avg_memory_mb: float = 0.0
+
+    # Comparison data
+    baseline_duration: float | None = None
+    speedup_factor: float | None = None
+    efficiency: float | None = None
+
+    def add_run(self, run: BenchmarkRun) -> None:
+        """Add a benchmark run to results.
+
+        Args:
+            run: Benchmark run to add
+        """
+        if run.is_warmup:
+            self.warmup_runs.append(run)
+        else:
+            self.measured_runs.append(run)
+
+    def calculate_statistics(self) -> None:
+        """Calculate aggregate statistics from measured runs."""
+        if not self.measured_runs:
+            return
+
+        durations = [r.metrics.total_duration_seconds for r in self.measured_runs]
+        throughputs = [r.metrics.avg_throughput for r in self.measured_runs]
+        memories = [r.metrics.peak_memory_mb for r in self.measured_runs]
+
+        self.avg_duration_seconds = statistics.mean(durations)
+        self.min_duration_seconds = min(durations)
+        self.max_duration_seconds = max(durations)
+        self.std_dev_seconds = (
+            statistics.stdev(durations) if len(durations) > 1 else 0.0
+        )
+        self.avg_throughput = statistics.mean(throughputs)
+        self.avg_memory_mb = statistics.mean(memories)
+
+        # Calculate efficiency if parallel mode with known worker count
+        if (
+            self.config.mode == BenchmarkMode.PARALLEL
+            and self.config.worker_count
+            and self.baseline_duration
+        ):
+            speedup = self.baseline_duration / self.avg_duration_seconds
+            self.speedup_factor = speedup
+            self.efficiency = speedup / self.config.worker_count
+
+    def get_last_metrics(self) -> IndexingMetrics | None:
+        """Get metrics from the last measured run.
+
+        Returns:
+            IndexingMetrics from last run, or None if no runs
+        """
+        if self.measured_runs:
+            return self.measured_runs[-1].metrics
+        return None
+
+
+class MetricsDisplayOptions(BaseModel):
+    """Options for controlling metrics display."""
+
+    show_phase_metrics: bool = True
+    show_worker_metrics: bool = False
+    show_file_metrics: bool = False
+    show_summary_only: bool = False
+    top_n_files: int | None = None
+    min_file_duration_ms: float | None = None

shotgun/codebase/core/__init__.py

@@ -5,6 +5,7 @@ from shotgun.codebase.core.code_retrieval import (
     retrieve_code_by_cypher,
     retrieve_code_by_qualified_name,
 )
+from shotgun.codebase.core.gitignore import GitignoreManager, load_gitignore_for_repo
 from shotgun.codebase.core.ingestor import (
     CodebaseIngestor,
     Ingestor,
@@ -29,6 +30,9 @@ __all__ = [
     "Ingestor",
     "SimpleGraphBuilder",
     "CodebaseGraphManager",
+    # Gitignore support
+    "GitignoreManager",
+    "load_gitignore_for_repo",
     # Language configuration
     "LanguageConfig",
     "LANGUAGE_CONFIGS",

shotgun/codebase/core/call_resolution.py

@@ -0,0 +1,91 @@
+"""Call resolution utilities for function/method call graph building.
+
+This module provides shared utilities for resolving function calls
+and calculating confidence scores for potential callee matches.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Mapping
+
+
+def calculate_callee_confidence(
+    caller_qn: str,
+    callee_qn: str,
+    module_qn: str,
+    object_name: str | None,
+    simple_name_lookup: Mapping[str, Collection[str]],
+) -> float:
+    """Calculate confidence score for a potential callee match.
+
+    Uses multiple heuristics to determine how likely a given callee
+    is the correct target of a function call:
+    1. Module locality - functions in the same module are most likely
+    2. Package locality - functions in the same package hierarchy
+    3. Object/class match for method calls
+    4. Standard library boost
+    5. Name uniqueness boost
+
+    Args:
+        caller_qn: Qualified name of the calling function
+        callee_qn: Qualified name of the potential callee
+        module_qn: Qualified name of the current module
+        object_name: Object name for method calls (e.g., 'obj' in obj.method())
+        simple_name_lookup: Mapping from simple names to qualified names
+            (supports both set[str] and list[str] values)
+
+    Returns:
+        Confidence score between 0.0 and 1.0
+    """
+    score = 0.0
+
+    # 1. Module locality - functions in the same module are most likely
+    if callee_qn.startswith(module_qn + "."):
+        score += 0.5
+
+        # Even higher if in the same class
+        caller_parts = caller_qn.split(".")
+        callee_parts = callee_qn.split(".")
+        if len(caller_parts) >= 3 and len(callee_parts) >= 3:
+            if caller_parts[:-1] == callee_parts[:-1]:  # Same class
+                score += 0.2
+
+    # 2. Package locality - functions in the same package hierarchy
+    elif "." in module_qn:
+        package = module_qn.rsplit(".", 1)[0]
+        if callee_qn.startswith(package + "."):
+            score += 0.3
+
+    # 3. Object/class match for method calls
+    if object_name:
+        # Check if callee is a method of a class matching the object name
+        callee_parts = callee_qn.split(".")
+        if len(callee_parts) >= 2:
+            # Simple heuristic: check if class name matches object name
+            # (In reality, we'd need type inference for accuracy)
+            class_name = callee_parts[-2]
+            if class_name.lower() == object_name.lower():
+                score += 0.3
+            elif object_name == "self" and callee_qn.startswith(
+                caller_qn.rsplit(".", 1)[0]
+            ):
+                # 'self' refers to the same class
+                score += 0.4
+
+    # 4. Standard library boost
+    # Give a small boost to standard library functions
+    if callee_qn.startswith(("builtins.", "typing.", "collections.")):
+        score += 0.1
+
+    # 5. Name uniqueness boost
+    # If function names are unique enough, boost confidence
+    callee_simple_name = callee_qn.split(".")[-1]
+    possible_matches = simple_name_lookup.get(callee_simple_name, [])
+    possible_count = len(possible_matches)
+    if possible_count == 1:
+        score += 0.2
+    elif possible_count <= 3:
+        score += 0.1
+
+    # Normalize to [0, 1]
+    return min(score, 1.0)