diffrag 0.2.3__py3-none-any.whl

diffrag/cli/main.py

@@ -0,0 +1,440 @@
+"""Entry-point for the ``diffrag`` CLI."""
+
+import asyncio
+import dataclasses
+import importlib.resources
+import json
+import logging
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.table import Table
+
+from ..ai.openai_compat import OpenAICompatClient
+from ..config.settings import Settings, default_db_path, user_config_path
+from ..diff.git import GitRepository
+from ..exceptions import AICodeReviewerError
+from ..indexing.indexer import RepoIndexer
+from ..review.reviewer import CodeReviewer
+
+console = Console()
+err_console = Console(stderr=True, style="bold red")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_settings(config: str | None) -> Settings:
+    """Load settings using a three-tier lookup (first match wins).
+
+    1. ``--config <path>`` — explicit CLI flag
+    2. ``.diffrag.toml`` in the current working directory
+    3. :func:`~diffrag.config.settings.user_config_path` — OS user config dir
+    4. Built-in defaults
+
+    Args:
+        config: Optional path to a ``.toml`` configuration file.
+
+    Returns:
+        Resolved :class:`~diffrag.config.Settings` instance.
+    """
+    if config:
+        return Settings.from_toml(Path(config))
+    project = Path(".diffrag.toml")
+    if project.exists():
+        return Settings.from_toml(project)
+    user = user_config_path()
+    if user.exists():
+        return Settings.from_toml(user)
+    return Settings.from_defaults()
+
+
+def _build_reviewer(
+    settings: Settings,
+    repo_path: Path,
+    verbosity: str = "standard",
+) -> tuple[CodeReviewer, GitRepository | None]:
+    """Instantiate the :class:`CodeReviewer` from *settings*.
+
+    Args:
+        settings: Resolved settings object.
+        repo_path: Canonical path of the repository being reviewed.
+            Used to derive the per-repository database location.
+        verbosity: Detail level for generated reviews.
+
+    Returns:
+        A tuple of ``(CodeReviewer, None)``; repository is opened separately.
+    """
+    ai_client = OpenAICompatClient(
+        base_url=settings.ai.base_url,
+        model=settings.ai.model,
+        api_key=settings.ai.api_key,
+        timeout=settings.ai.timeout,
+    )
+    embed_client = OpenAICompatClient(
+        base_url=settings.embedding.base_url,
+        model=settings.embedding.model,
+        api_key=settings.embedding.api_key,
+        timeout=settings.embedding.timeout,
+    )
+    indexer = RepoIndexer(
+        db_path=default_db_path(repo_path),
+        embedding_client=embed_client,
+        chunk_size=settings.indexing.chunk_size,
+        chunk_overlap=settings.indexing.chunk_overlap,
+        excluded_patterns=settings.indexing.excluded_patterns,
+        max_file_size=settings.indexing.max_file_size,
+    )
+    reviewer = CodeReviewer(
+        ai_client=ai_client,
+        indexer=indexer,
+        similarity_top_k=settings.review.similarity_top_k,
+        max_prompt_tokens=settings.review.max_prompt_tokens,
+        verbosity=verbosity,
+    )
+    return reviewer, None
+
+
+# ---------------------------------------------------------------------------
+# CLI group
+# ---------------------------------------------------------------------------
+
+
+@click.group()
+@click.option("--verbose", "-v", is_flag=True, help="Enable debug logging.")
+def cli(verbose: bool) -> None:
+    """AI-powered git diff analysis and code review with RAG context.
+
+    Run ``diffrag COMMAND --help`` for details on each command.
+    """
+    level = logging.DEBUG if verbose else logging.WARNING
+    logging.basicConfig(level=level, format="%(levelname)s %(name)s: %(message)s")
+
+
+# ---------------------------------------------------------------------------
+# review command
+# ---------------------------------------------------------------------------
+
+
+@cli.command()
+@click.option(
+    "--repo",
+    "-r",
+    "repo_path",
+    default=".",
+    show_default=True,
+    type=click.Path(exists=True, file_okay=False),
+    help="Path to the git repository.",
+)
+@click.option("--base", "-b", default=None, help="Base branch/ref (default from config or 'main').")
+@click.option("--head", "-H", default="HEAD", show_default=True, help="Head branch/ref to review.")
+@click.option(
+    "--config",
+    "-c",
+    default=None,
+    type=click.Path(exists=True),
+    help="Path to a .toml config file.",
+)
+@click.option(
+    "--verbosity",
+    "-V",
+    default=None,
+    type=click.Choice(["brief", "standard", "detailed"]),
+    help="Review detail level (overrides config default).",
+)
+def review(
+    repo_path: str,
+    base: str | None,
+    head: str,
+    config: str | None,
+    verbosity: str | None,
+) -> None:
+    """Generate an AI code review for changes between two git refs.
+
+    The repository index is built automatically on the first run and reused on
+    subsequent runs as long as HEAD has not changed.  A fresh commit triggers a
+    rebuild; switching branches also triggers a rebuild.
+
+    Examples:
+
+    \b
+        diffrag review --base main
+        diffrag review --base main --head feature/my-feature
+        diffrag review --repo /path/to/repo --base v1.0.0 --head HEAD
+    """
+    settings = _load_settings(config)
+    effective_base = base or settings.review.base_branch
+    effective_verbosity = verbosity or settings.review.verbosity
+    resolved_repo = Path(repo_path).resolve()
+    reviewer, _ = _build_reviewer(settings, repo_path=resolved_repo, verbosity=effective_verbosity)
+    repo = GitRepository(Path(repo_path))
+
+    async def _run() -> None:
+        with console.status("Preparing...", spinner="dots") as status:
+
+            def on_progress(msg: str) -> None:
+                status.update(f"[bold cyan]{msg}[/bold cyan]")
+                if not msg.endswith("..."):
+                    console.print(f"[green]✓[/green] {msg}")
+
+            result = await reviewer.review(
+                repo,
+                effective_base,
+                head,
+                on_progress=on_progress,
+            )
+
+        if result.summary == "No changes detected between the two refs.":
+            console.print(Panel("[yellow]No changes detected.[/yellow]", title="Review"))
+            return
+
+        n_files = len(result.file_reviews)
+        console.print(
+            Panel(
+                f"[bold]{effective_base}[/bold] → [bold cyan]{head}[/bold cyan]"
+                f"  [dim]{n_files} file review(s)[/dim]",
+                title="[bold blue]AI Code Review[/bold blue]",
+            )
+        )
+
+        if len(result.file_reviews) > 1:
+            for fr in result.file_reviews:
+                console.rule(f"[cyan]{fr.identifier}[/cyan]")
+                console.print(Markdown(fr.content))
+
+            console.rule("[bold]Consolidated Review[/bold]")
+
+        console.print(Markdown(result.summary))
+        console.print(
+            f"\n[dim]Tokens — prompt: {result.total_prompt_tokens}  "
+            f"completion: {result.total_completion_tokens}[/dim]"
+        )
+
+    try:
+        asyncio.run(_run())
+    except AICodeReviewerError as exc:
+        err_console.print(f"Error: {exc}")
+        sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# ask command
+# ---------------------------------------------------------------------------
+
+
+@cli.command()
+@click.option(
+    "--repo",
+    "-r",
+    "repo_path",
+    default=".",
+    show_default=True,
+    type=click.Path(exists=True, file_okay=False),
+    help="Path to the git repository.",
+)
+@click.option("--base", "-b", default=None, help="Base branch/ref.")
+@click.option("--head", "-H", default="HEAD", show_default=True, help="Head branch/ref.")
+@click.option(
+    "--config",
+    "-c",
+    default=None,
+    type=click.Path(exists=True),
+    help="Path to a .toml config file.",
+)
+@click.option(
+    "--verbosity",
+    "-V",
+    default=None,
+    type=click.Choice(["brief", "standard", "detailed"]),
+    help="Answer detail level (overrides config default).",
+)
+def ask(
+    repo_path: str,
+    base: str | None,
+    head: str,
+    config: str | None,
+    verbosity: str | None,
+) -> None:
+    """Interactively ask questions about the diff and codebase.
+
+    Launches a REPL where each question is answered using RAG context
+    from the indexed repository plus the current diff.  Type ``exit`` or
+    press Ctrl-D to quit.
+
+    Example:
+
+    \b
+        diffrag ask --base main
+    """
+    settings = _load_settings(config)
+    effective_base = base or settings.review.base_branch
+    effective_verbosity = verbosity or settings.review.verbosity
+    resolved_repo = Path(repo_path).resolve()
+    reviewer, _ = _build_reviewer(settings, repo_path=resolved_repo, verbosity=effective_verbosity)
+    repo = GitRepository(Path(repo_path))
+    diff_result = repo.get_diff(effective_base, head)
+
+    console.print(
+        Panel(
+            f"Asking about [bold]{effective_base}[/bold] → [bold cyan]{head}[/bold cyan]\n"
+            "[dim]Type your question and press Enter. Type 'exit' or Ctrl-D to quit.[/dim]",
+            title="[bold green]Interactive Q&A[/bold green]",
+        )
+    )
+
+    history: list[tuple[str, str]] = []
+    while True:
+        try:
+            question = console.input("\n[bold cyan]>[/bold cyan] ").strip()
+        except (EOFError, KeyboardInterrupt):
+            console.print("\n[dim]Bye.[/dim]")
+            break
+
+        if question.lower() in ("exit", "quit", "q"):
+            break
+        if not question:
+            continue
+
+        async def _answer(q: str = question, hist: list[tuple[str, str]] = history) -> str:
+            with console.status("[bold green]Thinking…[/]", spinner="dots"):
+                return await reviewer.ask(q, diff_result, history=hist)
+
+        try:
+            answer = asyncio.run(_answer())
+            console.print(Markdown(answer))
+            history.append((question, answer))
+        except AICodeReviewerError as exc:
+            err_console.print(f"Error: {exc}")
+
+
+# ---------------------------------------------------------------------------
+# create-config command
+# ---------------------------------------------------------------------------
+
+_EXAMPLE_CONFIG = importlib.resources.files("diffrag").joinpath("data/config.example.toml")
+
+
+@cli.command("create-config")
+@click.option(
+    "--out",
+    "-o",
+    default=None,
+    type=click.Path(dir_okay=False),
+    help="Destination path (default: user-level config returned by config-path).",
+)
+@click.option("--force", "-f", is_flag=True, help="Overwrite if the file already exists.")
+def create_config(out: str | None, force: bool) -> None:
+    """Create a config file pre-populated with all available settings.
+
+    By default the file is written to the user-level config directory so it
+    applies to every repository on this machine.  Pass ``--out`` to write a
+    project-level ``.diffrag.toml`` instead.
+
+    \b
+        diffrag create-config                      # global user config
+        diffrag create-config --out .diffrag.toml # project override
+        diffrag create-config --force              # overwrite existing
+    """
+    dest = Path(out) if out else user_config_path()
+
+    if dest.exists() and not force:
+        err_console.print(
+            f"[bold]{dest}[/bold] already exists. Use [bold]--force[/bold] to overwrite."
+        )
+        sys.exit(1)
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(_EXAMPLE_CONFIG.read_text(encoding="utf-8"), encoding="utf-8")
+    console.print(f"[green]✓[/green] Config written to [bold]{dest}[/bold]")
+
+
+# ---------------------------------------------------------------------------
+# db-path command
+# ---------------------------------------------------------------------------
+
+
+@cli.command("db-path")
+@click.option(
+    "--repo",
+    "-r",
+    "repo_path",
+    default=".",
+    show_default=True,
+    type=click.Path(exists=True, file_okay=False),
+    help="Path to the git repository.",
+)
+def db_path_cmd(repo_path: str) -> None:
+    """Print the database path for a repository.
+
+    The index for each repository is stored in a unique subdirectory of the
+    OS user cache directory, derived from the repository's canonical path.
+    The directory may not exist yet (it is created on first run).
+
+    \b
+        diffrag db-path
+        diffrag db-path --repo /path/to/repo
+    """
+    console.print(str(default_db_path(Path(repo_path).resolve())))
+
+
+# ---------------------------------------------------------------------------
+# config-path command
+# ---------------------------------------------------------------------------
+
+
+@cli.command("config-path")
+def config_path_cmd() -> None:
+    """Print the path to the user-level config file."""
+    console.print(str(user_config_path()))
+
+
+# ---------------------------------------------------------------------------
+# show-config command
+# ---------------------------------------------------------------------------
+
+
+@cli.command("show-config")
+@click.option(
+    "--config",
+    "-c",
+    default=None,
+    type=click.Path(exists=True),
+    help="Path to a .toml config file.",
+)
+def show_config(config: str | None) -> None:
+    """Display the effective configuration as JSON.
+
+    Useful for verifying which settings are active, including defaults.
+    """
+    settings = _load_settings(config)
+
+    def _serialise(obj: object) -> object:
+        if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+            return {f.name: _serialise(getattr(obj, f.name)) for f in dataclasses.fields(obj)}
+        if isinstance(obj, Path):
+            return str(obj)
+        if isinstance(obj, list):
+            return [_serialise(v) for v in obj]
+        return obj
+
+    table = Table(title="Effective Configuration", show_header=True)
+    table.add_column("Section", style="cyan")
+    table.add_column("Key", style="white")
+    table.add_column("Value", style="green")
+
+    raw = _serialise(settings)
+    assert isinstance(raw, dict)
+    for section, values in raw.items():
+        if isinstance(values, dict):
+            for key, value in values.items():
+                table.add_row(str(section), str(key), json.dumps(value))
+        else:
+            table.add_row("", str(section), json.dumps(values))
+
+    console.print(table)

diffrag/config/__init__.py

@@ -0,0 +1,21 @@
+"""Configuration loading and data models."""
+
+from .settings import (
+    AISettings,
+    EmbeddingSettings,
+    IndexingSettings,
+    ReviewSettings,
+    Settings,
+    default_db_path,
+    user_config_path,
+)
+
+__all__ = [
+    "AISettings",
+    "EmbeddingSettings",
+    "IndexingSettings",
+    "ReviewSettings",
+    "Settings",
+    "default_db_path",
+    "user_config_path",
+]

diffrag/config/settings.py

@@ -0,0 +1,190 @@
+"""Settings loaded from a TOML configuration file."""
+
+import hashlib
+import logging
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import platformdirs
+
+from ..exceptions import ConfigurationError
+
+log = logging.getLogger(__name__)
+
+
+def user_config_path() -> Path:
+    """Return the OS-appropriate user-level config file path.
+
+    - Linux / macOS: ``~/.config/diffrag/config.toml``
+    - Windows:       ``%APPDATA%\\diffrag\\config.toml``
+
+    The file may not exist yet; call this to find where to create it.
+    """
+    return Path(platformdirs.user_config_dir("diffrag")) / "config.toml"
+
+
+def default_db_path(repo_path: Path) -> Path:
+    """Return the cache-directory DB path for *repo_path*.
+
+    Each repository maps to a unique subdirectory inside the OS user cache dir,
+    named after the first 12 hex characters of the SHA-256 hash of the repo's
+    canonical absolute path.
+
+    - Linux / macOS: ``~/.cache/diffrag/<hash>/``
+    - Windows:       ``%LOCALAPPDATA%\\diffrag\\Cache\\<hash>\\``
+    """
+    digest = hashlib.sha256(str(repo_path.resolve()).encode()).hexdigest()[:12]
+    return Path(platformdirs.user_cache_dir("diffrag")) / digest
+
+
+_DEFAULT_EXCLUDED_PATTERNS = [
+    ".git",
+    ".venv",
+    "__pycache__",
+    "node_modules",
+    ".idea",
+    ".mypy_cache",
+    ".ruff_cache",
+    "dist",
+    "build",
+]
+
+
+@dataclass
+class AISettings:
+    """Settings for the language model used to generate reviews.
+
+    Attributes:
+        base_url: Base URL of the OpenAI-compatible or Ollama endpoint.
+        model: Model identifier to use for completion requests.
+        api_key: Bearer token sent in the Authorization header (empty = none).
+        timeout: HTTP request timeout in seconds.
+    """
+
+    base_url: str = "http://localhost:11434"
+    model: str = "llama3.2"
+    api_key: str = ""
+    timeout: float = 120.0
+
+
+@dataclass
+class EmbeddingSettings:
+    """Settings for the embedding model used to build the vector index.
+
+    Attributes:
+        base_url: Base URL of the OpenAI-compatible or Ollama endpoint.
+        model: Model identifier to use for embedding requests.
+        api_key: Bearer token sent in the Authorization header (empty = none).
+        timeout: HTTP request timeout in seconds.
+    """
+
+    base_url: str = "http://localhost:11434"
+    model: str = "nomic-embed-text"
+    api_key: str = ""
+    timeout: float = 60.0
+
+
+@dataclass
+class IndexingSettings:
+    """Settings that control how the repository is indexed.
+
+    The database location is always determined automatically by
+    :func:`default_db_path` and cannot be configured.
+
+    Attributes:
+        chunk_size: Maximum number of characters per text chunk.
+        chunk_overlap: Number of characters to overlap between consecutive chunks.
+        excluded_patterns: Additional directory or file name segments to skip,
+            applied on top of any patterns found in the repository's ``.gitignore``.
+            ``.git`` is always excluded regardless of this setting.
+        max_file_size: Files larger than this (bytes) are skipped.
+    """
+
+    chunk_size: int = 1024
+    chunk_overlap: int = 128
+    excluded_patterns: list[str] = field(default_factory=lambda: list(_DEFAULT_EXCLUDED_PATTERNS))
+    max_file_size: int = 1_000_000
+
+
+@dataclass
+class ReviewSettings:
+    """Settings that control the review behaviour.
+
+    Attributes:
+        base_branch: Default branch to diff against when none is specified.
+        similarity_top_k: Number of RAG context chunks retrieved per diff chunk.
+        max_prompt_tokens: Approximate token budget per diff chunk before splitting.
+        verbosity: Detail level of generated reviews. One of ``"brief"``,
+            ``"standard"`` (default), or ``"detailed"``.
+    """
+
+    base_branch: str = "main"
+    similarity_top_k: int = 5
+    max_prompt_tokens: int = 6000
+    verbosity: str = "standard"
+
+    def __post_init__(self) -> None:
+        if self.verbosity not in ("brief", "standard", "detailed"):
+            raise ConfigurationError(
+                f"Invalid verbosity {self.verbosity!r}. Choose 'brief', 'standard', or 'detailed'."
+            )
+
+
+@dataclass
+class Settings:
+    """Root settings object aggregating all configuration sections.
+
+    Attributes:
+        ai: Language model settings.
+        embedding: Embedding model settings.
+        indexing: Vector index settings.
+        review: Review behaviour settings.
+    """
+
+    ai: AISettings = field(default_factory=AISettings)
+    embedding: EmbeddingSettings = field(default_factory=EmbeddingSettings)
+    indexing: IndexingSettings = field(default_factory=IndexingSettings)
+    review: ReviewSettings = field(default_factory=ReviewSettings)
+
+    @classmethod
+    def from_toml(cls, path: Path) -> "Settings":
+        """Load settings from a TOML file.
+
+        Args:
+            path: Path to the ``.toml`` configuration file.
+
+        Returns:
+            A fully populated ``Settings`` instance.
+
+        Raises:
+            ConfigurationError: If the file cannot be read or contains invalid keys.
+        """
+        try:
+            with path.open("rb") as fh:
+                data = tomllib.load(fh)
+        except OSError as exc:
+            raise ConfigurationError(f"Cannot read config file {path}: {exc}") from exc
+        except tomllib.TOMLDecodeError as exc:
+            raise ConfigurationError(f"Invalid TOML in {path}: {exc}") from exc
+
+        log.debug("Loaded configuration from %s", path)
+
+        try:
+            return cls(
+                ai=AISettings(**data.get("ai", {})),
+                embedding=EmbeddingSettings(**data.get("embedding", {})),
+                indexing=IndexingSettings(**data.get("indexing", {})),
+                review=ReviewSettings(**data.get("review", {})),
+            )
+        except TypeError as exc:
+            raise ConfigurationError(f"Unexpected key in config {path}: {exc}") from exc
+
+    @classmethod
+    def from_defaults(cls) -> "Settings":
+        """Return a ``Settings`` instance with all default values.
+
+        Returns:
+            A ``Settings`` instance populated with default values.
+        """
+        return cls()

diffrag/data/config.example.toml

@@ -0,0 +1,53 @@
+# diffrag configuration
+#
+# Settings are loaded from the first file found:
+#   1. --config <path>          (explicit CLI flag)
+#   2. .diffrag.toml           (current working directory)
+#   3. user-level config        (run "diffrag config-path" to find this)
+#   4. Built-in defaults        (no file needed)
+#
+# All keys are optional — remove any section to use built-in defaults.
+
+[ai]
+# Base URL of the OpenAI-compatible endpoint (OpenWebUI, Ollama /v1, OpenAI, etc.)
+base_url = "http://localhost:11434"
+# Model identifier to use for review generation
+model = "llama3.2"
+# API key / bearer token (leave empty for unauthenticated local servers)
+api_key = ""
+# Per-read timeout in seconds (requests use streaming; this is the max time
+# between consecutive chunks, not the total generation time)
+timeout = 120.0
+
+[embedding]
+# Embedding endpoint — can differ from the completion endpoint
+base_url = "http://localhost:11434"
+model = "nomic-embed-text"
+api_key = ""
+timeout = 60.0
+
+[indexing]
+# The index is always stored in the OS user cache directory, keyed by repo.
+# Run "diffrag db-path" to see the exact path for the current repository.
+# Target chunk size in characters
+chunk_size = 1024
+# Overlap between consecutive chunks in characters
+chunk_overlap = 128
+# Patterns in the repository's .gitignore are excluded automatically.
+# The list below provides additional excludes on top of .gitignore.
+excluded_patterns = [
+    ".git", ".venv", "__pycache__", "node_modules",
+    ".idea", ".mypy_cache", ".ruff_cache", "dist", "build",
+]
+# Files larger than this (bytes) are not indexed
+max_file_size = 1000000
+
+[review]
+# Default branch to diff against when --base is not specified
+base_branch = "main"
+# Number of context chunks retrieved from the index per diff chunk
+similarity_top_k = 5
+# Approximate token budget per diff chunk before hunk-splitting kicks in
+max_prompt_tokens = 6000
+# Detail level of generated reviews: "brief" | "standard" | "detailed"
+verbosity = "standard"