git-sage 0.1.0__py3-none-any.whl

git_sage/__init__.py

@@ -0,0 +1,3 @@
+"""git-sage: local AI code review for your git workflow."""
+
+__version__ = "0.1.0"

git_sage/cli.py

@@ -0,0 +1,222 @@
+"""
+cli.py
+------
+Click-based CLI entrypoint for git-sage.
+
+Commands
+--------
+  git-sage review          Run a review of staged changes (interactive)
+  git-sage review --hook   Run a review triggered by the pre-push hook
+  git-sage install         Install the pre-push hook in the current repo
+  git-sage uninstall       Remove the pre-push hook
+  git-sage status          Show tool version, hook status, and Ollama availability
+  git-sage models          List locally available Ollama models
+"""
+
+import sys
+import click
+
+from git_sage import __version__
+from git_sage import diff as diff_mod
+from git_sage import hook as hook_mod
+from git_sage import ollama as ollama_mod
+from git_sage import output
+from git_sage.prompt import build_messages
+from git_sage.parser import parse, Verdict
+
+
+# ---------------------------------------------------------------------------
+# Root group
+# ---------------------------------------------------------------------------
+
+@click.group()
+@click.version_option(__version__, prog_name="git-sage")
+def main() -> None:
+    """git-sage — local AI code review for your git workflow."""
+
+
+# ---------------------------------------------------------------------------
+# review
+# ---------------------------------------------------------------------------
+
+@main.command()
+@click.option(
+    "--model", "-m",
+    default=ollama_mod.DEFAULT_MODEL,
+    show_default=True,
+    help="Ollama model to use for review.",
+)
+@click.option(
+    "--host",
+    default=ollama_mod.DEFAULT_HOST,
+    show_default=True,
+    help="Ollama server URL.",
+)
+@click.option(
+    "--context", "-c",
+    default=None,
+    help='Optional note about this change, e.g. "Adds OAuth login".',
+)
+@click.option(
+    "--hook",
+    is_flag=True,
+    hidden=True,
+    help="Internal flag: invoked from the pre-push hook.",
+)
+@click.option(
+    "--diff-mode",
+    type=click.Choice(["staged", "head", "branch"]),
+    default="staged",
+    show_default=True,
+    help="Which diff to review.",
+)
+@click.option(
+    "--base",
+    default="main",
+    show_default=True,
+    help="Base branch for --diff-mode=branch.",
+)
+@click.option(
+    "--force", "-f",
+    is_flag=True,
+    help="Do not abort the push even if the verdict is REVISE (hook mode only).",
+)
+def review(model, host, context, hook, diff_mode, base, force) -> None:
+    """Review staged (or recent) changes with a local AI model."""
+
+    # 1. Check Ollama is running
+    if not ollama_mod.is_available(host):
+        output.print_error(
+            f"Ollama is not running at {host}.\n"
+            "  Start it with:  ollama serve\n"
+            f"  Then pull a model:  ollama pull {ollama_mod.DEFAULT_MODEL}"
+        )
+        sys.exit(1)
+
+    # 2. Extract the diff
+    try:
+        if diff_mode == "staged":
+            diff = diff_mod.get_staged_diff()
+        elif diff_mode == "head":
+            diff = diff_mod.get_head_diff()
+        else:
+            diff = diff_mod.get_branch_diff(base)
+    except RuntimeError as exc:
+        output.print_error(str(exc))
+        sys.exit(1)
+
+    if not diff.raw.strip():
+        output.print_warning("No changes found to review.")
+        sys.exit(0)
+
+    output.print_diff_stats(diff)
+
+    # 3. Build prompt and call Ollama
+    messages = build_messages(diff, context)
+
+    try:
+        with output.thinking_spinner(f"Reviewing with {model}…"):
+            raw_response = ollama_mod.chat(messages, model=model, host=host)
+    except ollama_mod.OllamaError as exc:
+        output.print_error(f"Ollama error: {exc}")
+        sys.exit(1)
+
+    # 4. Parse and render
+    result = parse(raw_response)
+    output.print_review(result)
+
+    # 5. Hook mode: non-zero exit aborts the push
+    if hook and result.verdict == Verdict.REVISE and not force:
+        click.echo(
+            "  Push aborted by git-sage. Fix the issues above, or run:\n"
+            "    git push --no-verify   to bypass the hook.\n"
+        )
+        sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# install
+# ---------------------------------------------------------------------------
+
+@main.command()
+def install() -> None:
+    """Install the git-sage pre-push hook in the current repository."""
+    try:
+        hook_path = hook_mod.install()
+        output.print_success(f"Hook installed at {hook_path}")
+        click.echo("  git-sage will now review your changes before every push.\n")
+    except RuntimeError as exc:
+        output.print_error(str(exc))
+        sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# uninstall
+# ---------------------------------------------------------------------------
+
+@main.command()
+def uninstall() -> None:
+    """Remove the git-sage pre-push hook from the current repository."""
+    try:
+        removed = hook_mod.uninstall()
+        if removed:
+            output.print_success("Hook removed.")
+        else:
+            output.print_warning("No git-sage hook found in this repository.")
+    except RuntimeError as exc:
+        output.print_error(str(exc))
+        sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# status
+# ---------------------------------------------------------------------------
+
+@main.command()
+@click.option("--host", default=ollama_mod.DEFAULT_HOST, show_default=True)
+def status(host) -> None:
+    """Show the current status of git-sage, the hook, and Ollama."""
+    click.echo(f"\n  git-sage  v{__version__}\n")
+
+    # Ollama
+    if ollama_mod.is_available(host):
+        click.echo(f"  [✓]  Ollama running at {host}")
+        models = ollama_mod.list_models(host)
+        if models:
+            click.echo(f"       Models: {', '.join(models)}")
+    else:
+        click.echo(f"  [✗]  Ollama not reachable at {host}")
+        click.echo( "       Start with:  ollama serve")
+
+    # Hook
+    if hook_mod.is_installed():
+        click.echo("  [✓]  pre-push hook installed")
+    else:
+        click.echo("  [ ]  pre-push hook not installed")
+        click.echo("       Run:  git-sage install")
+
+    click.echo()
+
+
+# ---------------------------------------------------------------------------
+# models
+# ---------------------------------------------------------------------------
+
+@main.command()
+@click.option("--host", default=ollama_mod.DEFAULT_HOST, show_default=True)
+def models(host) -> None:
+    """List locally available Ollama models."""
+    if not ollama_mod.is_available(host):
+        output.print_error(f"Ollama is not running at {host}.")
+        sys.exit(1)
+
+    model_list = ollama_mod.list_models(host)
+    if not model_list:
+        click.echo("\n  No models found. Pull one with:\n")
+        click.echo(f"    ollama pull {ollama_mod.DEFAULT_MODEL}\n")
+    else:
+        click.echo(f"\n  Available models ({len(model_list)}):\n")
+        for m in model_list:
+            marker = "  ●" if m.startswith("qwen2.5-coder") else "  ○"
+            click.echo(f"{marker}  {m}")
+        click.echo()

git_sage/diff.py

@@ -0,0 +1,76 @@
+"""
+diff.py
+-------
+Extracts diffs from git using subprocess.
+
+Supports two modes:
+  - staged:  changes added with `git add` (used during pre-push / manual review)
+  - head:    diff of the last commit vs its parent (useful for post-commit review)
+"""
+
+import subprocess
+from dataclasses import dataclass
+
+
+@dataclass
+class DiffResult:
+    raw: str           # full unified diff text
+    file_count: int    # number of changed files
+    additions: int     # total lines added
+    deletions: int     # total lines removed
+    files: list[str]   # list of changed file paths
+
+
+def get_staged_diff() -> DiffResult:
+    """Return the diff of all staged changes (git diff --cached)."""
+    return _run_diff(["git", "diff", "--cached"])
+
+
+def get_head_diff() -> DiffResult:
+    """Return the diff of the last commit vs its parent (git diff HEAD~1 HEAD)."""
+    return _run_diff(["git", "diff", "HEAD~1", "HEAD"])
+
+
+def get_branch_diff(base: str = "main") -> DiffResult:
+    """Return the diff of the current branch vs a base branch."""
+    return _run_diff(["git", "diff", f"{base}...HEAD"])
+
+
+def _run_diff(cmd: list[str]) -> DiffResult:
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"git diff failed:\n{result.stderr.strip()}"
+        )
+
+    raw = result.stdout
+
+    if not raw.strip():
+        return DiffResult(raw="", file_count=0, additions=0, deletions=0, files=[])
+
+    additions = sum(1 for line in raw.splitlines() if line.startswith("+") and not line.startswith("+++"))
+    deletions = sum(1 for line in raw.splitlines() if line.startswith("-") and not line.startswith("---"))
+    files = _extract_files(raw)
+
+    return DiffResult(
+        raw=raw,
+        file_count=len(files),
+        additions=additions,
+        deletions=deletions,
+        files=files,
+    )
+
+
+def _extract_files(diff_text: str) -> list[str]:
+    files = []
+    for line in diff_text.splitlines():
+        if line.startswith("+++ b/"):
+            path = line.removeprefix("+++ b/")
+            if path not in files:
+                files.append(path)
+    return files

git_sage/hook.py

@@ -0,0 +1,128 @@
+"""
+hook.py
+-------
+Installs and removes the git pre-push hook that triggers git-sage automatically.
+
+The hook is a small shell script written to .git/hooks/pre-push. When git push
+is run, git executes this script first. If the script exits with a non-zero
+code, the push is aborted.
+
+This is intentionally simple — the hook just calls `git-sage review --hook`
+which handles all the logic in Python.
+"""
+
+import os
+import stat
+import subprocess
+from pathlib import Path
+
+
+HOOK_MARKER = "# git-sage managed hook"
+
+HOOK_SCRIPT = """\
+#!/usr/bin/env sh
+{marker}
+# This hook was installed by git-sage.
+# Run: git-sage uninstall   to remove it.
+
+git-sage review --hook
+""".format(marker=HOOK_MARKER)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def install(repo_root: Path | None = None) -> Path:
+    """
+    Write the pre-push hook to the git repo's hooks directory.
+
+    Parameters
+    ----------
+    repo_root:
+        Path to the git repository root. Auto-detected if not provided.
+
+    Returns
+    -------
+    Path to the installed hook file.
+
+    Raises
+    ------
+    RuntimeError if we're not inside a git repository.
+    """
+    hooks_dir = _get_hooks_dir(repo_root)
+    hook_path = hooks_dir / "pre-push"
+
+    if hook_path.exists():
+        existing = hook_path.read_text()
+        if HOOK_MARKER in existing:
+            # Already installed by us — overwrite silently (idempotent)
+            pass
+        else:
+            raise RuntimeError(
+                f"A pre-push hook already exists at {hook_path} and was not "
+                "created by git-sage. Remove it manually before installing."
+            )
+
+    hook_path.write_text(HOOK_SCRIPT)
+    # Make the hook executable (equivalent to chmod +x)
+    hook_path.chmod(hook_path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    return hook_path
+
+
+def uninstall(repo_root: Path | None = None) -> bool:
+    """
+    Remove the git-sage pre-push hook if it exists.
+
+    Returns True if removed, False if no hook was found.
+    """
+    hooks_dir = _get_hooks_dir(repo_root)
+    hook_path = hooks_dir / "pre-push"
+
+    if not hook_path.exists():
+        return False
+
+    existing = hook_path.read_text()
+    if HOOK_MARKER not in existing:
+        raise RuntimeError(
+            f"The hook at {hook_path} was not created by git-sage. "
+            "Remove it manually."
+        )
+
+    hook_path.unlink()
+    return True
+
+
+def is_installed(repo_root: Path | None = None) -> bool:
+    """Return True if the git-sage hook is currently installed."""
+    try:
+        hooks_dir = _get_hooks_dir(repo_root)
+        hook_path = hooks_dir / "pre-push"
+        return hook_path.exists() and HOOK_MARKER in hook_path.read_text()
+    except RuntimeError:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _get_hooks_dir(repo_root: Path | None) -> Path:
+    if repo_root is None:
+        repo_root = _find_repo_root()
+    hooks_dir = repo_root / ".git" / "hooks"
+    if not hooks_dir.exists():
+        raise RuntimeError(f"No .git/hooks directory found at {hooks_dir}")
+    return hooks_dir
+
+
+def _find_repo_root() -> Path:
+    result = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError("Not inside a git repository.")
+    return Path(result.stdout.strip())

git_sage/ollama.py

@@ -0,0 +1,123 @@
+"""
+ollama.py
+---------
+Thin HTTP client for the Ollama local inference server.
+
+Ollama exposes a REST API on http://localhost:11434 by default.
+We use httpx (sync) to keep the dependency footprint small.
+
+Reference: https://github.com/ollama/ollama/blob/main/docs/api.md
+"""
+
+import json
+from typing import Iterator
+
+import httpx
+
+DEFAULT_HOST = "http://localhost:11434"
+DEFAULT_MODEL = "qwen2.5-coder:7b"
+
+# How long to wait for the first token (seconds).
+# Code review of a large diff can take 20-30 s on CPU.
+TIMEOUT = 120
+
+
+class OllamaError(Exception):
+    """Raised when the Ollama server returns an error or is unreachable."""
+
+
+def is_available(host: str = DEFAULT_HOST) -> bool:
+    """Return True if the Ollama server is reachable."""
+    try:
+        r = httpx.get(f"{host}/api/tags", timeout=3)
+        return r.status_code == 200
+    except httpx.RequestError:
+        return False
+
+
+def list_models(host: str = DEFAULT_HOST) -> list[str]:
+    """Return the names of locally available models."""
+    try:
+        r = httpx.get(f"{host}/api/tags", timeout=5)
+        r.raise_for_status()
+        return [m["name"] for m in r.json().get("models", [])]
+    except httpx.RequestError as exc:
+        raise OllamaError(f"Cannot reach Ollama at {host}: {exc}") from exc
+
+
+def chat(
+    messages: list[dict],
+    model: str = DEFAULT_MODEL,
+    host: str = DEFAULT_HOST,
+    stream: bool = False,
+) -> str | Iterator[str]:
+    """
+    Send a chat request to Ollama.
+
+    Parameters
+    ----------
+    messages:
+        List of {"role": ..., "content": ...} dicts (OpenAI-compatible).
+    model:
+        Local model name, e.g. "qwen2.5-coder:7b".
+    host:
+        Ollama server base URL.
+    stream:
+        If True, yield text chunks as they arrive (for live output).
+        If False (default), return the complete response string.
+
+    Returns
+    -------
+    str (stream=False) or Iterator[str] (stream=True)
+    """
+    url = f"{host}/api/chat"
+    payload = {
+        "model": model,
+        "messages": messages,
+        "stream": stream,
+        "options": {
+            # Keep temperature low for deterministic code review
+            "temperature": 0.2,
+            "top_p": 0.9,
+        },
+    }
+
+    if stream:
+        return _stream_response(url, payload)
+    else:
+        return _blocking_response(url, payload)
+
+
+def _blocking_response(url: str, payload: dict) -> str:
+    try:
+        with httpx.Client(timeout=TIMEOUT) as client:
+            r = client.post(url, json=payload)
+            r.raise_for_status()
+            data = r.json()
+            return data["message"]["content"]
+    except httpx.HTTPStatusError as exc:
+        raise OllamaError(f"Ollama returned HTTP {exc.response.status_code}") from exc
+    except httpx.RequestError as exc:
+        raise OllamaError(f"Cannot reach Ollama: {exc}") from exc
+    except (KeyError, json.JSONDecodeError) as exc:
+        raise OllamaError(f"Unexpected response format: {exc}") from exc
+
+
+def _stream_response(url: str, payload: dict) -> Iterator[str]:
+    try:
+        with httpx.Client(timeout=TIMEOUT) as client:
+            with client.stream("POST", url, json=payload) as r:
+                r.raise_for_status()
+                for line in r.iter_lines():
+                    if not line:
+                        continue
+                    chunk = json.loads(line)
+                    token = chunk.get("message", {}).get("content", "")
+                    if token:
+                        yield token
+                    if chunk.get("done"):
+                        break
+    except httpx.HTTPStatusError as exc:
+        raise OllamaError(f"Ollama returned HTTP {exc.response.status_code}") from exc
+    except httpx.RequestError as exc:
+        raise OllamaError(f"Cannot reach Ollama: {exc}") from exc

git_sage/output.py

@@ -0,0 +1,130 @@
+"""
+output.py
+---------
+Terminal output renderer using the `rich` library.
+
+Rich gives us coloured panels, icons, and clean formatting with zero
+configuration — ideal for a CLI tool that developers will stare at
+every time they push code.
+"""
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich import box
+from rich.text import Text
+from rich.spinner import Spinner
+from rich.live import Live
+
+from git_sage.parser import ReviewResult, Verdict
+from git_sage.diff import DiffResult
+
+console = Console()
+
+
+# ---------------------------------------------------------------------------
+# Public render functions
+# ---------------------------------------------------------------------------
+
+def print_diff_stats(diff: DiffResult) -> None:
+    """Print a one-line summary of what's staged."""
+    stats = Text()
+    stats.append("  Staged: ", style="dim")
+    stats.append(f"{diff.file_count} file(s)", style="bold")
+    stats.append("  ", style="dim")
+    stats.append(f"+{diff.additions}", style="bold green")
+    stats.append(" / ", style="dim")
+    stats.append(f"-{diff.deletions}", style="bold red")
+    console.print(stats)
+
+
+def print_review(result: ReviewResult) -> None:
+    """Render the full review result to the terminal."""
+    _print_summary(result)
+    _print_issues(result)
+    _print_suggestions(result)
+    _print_verdict(result)
+
+
+def print_error(message: str) -> None:
+    console.print(f"\n[bold red]✗[/bold red]  {message}\n")
+
+
+def print_success(message: str) -> None:
+    console.print(f"\n[bold green]✓[/bold green]  {message}\n")
+
+
+def print_warning(message: str) -> None:
+    console.print(f"\n[bold yellow]⚠[/bold yellow]  {message}\n")
+
+
+def thinking_spinner(label: str = "Reviewing with local AI…") -> Live:
+    """
+    Returns a Rich Live context manager showing a spinner.
+
+    Usage:
+        with thinking_spinner():
+            result = ollama.chat(...)
+    """
+    spinner = Spinner("dots", text=f"[dim]{label}[/dim]")
+    return Live(spinner, console=console, refresh_per_second=10, transient=True)
+
+
+# ---------------------------------------------------------------------------
+# Private section renderers
+# ---------------------------------------------------------------------------
+
+def _print_summary(result: ReviewResult) -> None:
+    if not result.summary:
+        return
+    panel = Panel(
+        f"[dim]{result.summary}[/dim]",
+        title="[bold]Summary[/bold]",
+        border_style="bright_black",
+        padding=(0, 1),
+    )
+    console.print(panel)
+
+
+def _print_issues(result: ReviewResult) -> None:
+    if not result.issues:
+        console.print("\n[bold green]  No issues found.[/bold green]\n")
+        return
+
+    console.print(f"\n[bold red]  Issues[/bold red]  ({len(result.issues)} found)\n")
+    for i, issue in enumerate(result.issues, 1):
+        console.print(f"  [red]●[/red]  [dim]{i}.[/dim] {issue}")
+    console.print()
+
+
+def _print_suggestions(result: ReviewResult) -> None:
+    if not result.suggestions:
+        return
+
+    console.print(f"[bold yellow]  Suggestions[/bold yellow]  ({len(result.suggestions)})\n")
+    for i, sug in enumerate(result.suggestions, 1):
+        console.print(f"  [yellow]◆[/yellow]  [dim]{i}.[/dim] {sug}")
+    console.print()
+
+
+def _print_verdict(result: ReviewResult) -> None:
+    if result.verdict == Verdict.APPROVE:
+        panel = Panel(
+            "[bold green]  ✓  APPROVE[/bold green]\n[dim]  Ready to push.[/dim]",
+            border_style="green",
+            padding=(0, 1),
+        )
+    elif result.verdict == Verdict.REVISE:
+        panel = Panel(
+            "[bold red]  ✗  REVISE[/bold red]\n[dim]  Address the issues above before pushing.[/dim]",
+            border_style="red",
+            padding=(0, 1),
+        )
+    else:
+        panel = Panel(
+            "[bold yellow]  ?  UNKNOWN[/bold yellow]\n[dim]  The model didn't return a clear verdict.[/dim]",
+            border_style="yellow",
+            padding=(0, 1),
+        )
+    console.print(panel)
+    console.print()

git_sage/parser.py

@@ -0,0 +1,148 @@
+"""
+parser.py
+---------
+Parses the structured text output from the LLM into a ReviewResult dataclass.
+
+The system prompt (prompt.py) tells the model to respond with four labelled
+sections: SUMMARY, ISSUES, SUGGESTIONS, VERDICT. This parser extracts each
+section by scanning for those headings, making it tolerant of minor formatting
+variations in the model output.
+"""
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class Verdict(str, Enum):
+    APPROVE = "APPROVE"
+    REVISE  = "REVISE"
+    UNKNOWN = "UNKNOWN"  # fallback if the model didn't follow instructions
+
+
+@dataclass
+class ReviewResult:
+    summary:     str
+    issues:      list[str]
+    suggestions: list[str]
+    verdict:     Verdict
+    raw:         str        # full original LLM response (useful for debugging)
+
+    @property
+    def has_issues(self) -> bool:
+        return bool(self.issues)
+
+    @property
+    def is_approved(self) -> bool:
+        return self.verdict == Verdict.APPROVE
+
+
+# Section heading patterns (case-insensitive, allow trailing colon or whitespace)
+_HEADING = re.compile(
+    r"^(SUMMARY|ISSUES|SUGGESTIONS|VERDICT)\s*:?\s*$",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+# A numbered list item: "1. text" or "1) text"
+_LIST_ITEM = re.compile(r"^\s*\d+[.)]\s+(.+)$")
+
+
+def parse(raw: str) -> ReviewResult:
+    """
+    Parse the raw LLM response text into a ReviewResult.
+
+    Tolerates extra whitespace, minor heading variations, and models
+    that add a colon after the heading name.
+    """
+    sections = _split_sections(raw)
+
+    summary     = _extract_text(sections.get("summary", ""))
+    issues      = _extract_list(sections.get("issues", ""))
+    suggestions = _extract_list(sections.get("suggestions", ""))
+    verdict     = _extract_verdict(sections.get("verdict", ""))
+
+    return ReviewResult(
+        summary=summary,
+        issues=issues,
+        suggestions=suggestions,
+        verdict=verdict,
+        raw=raw,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _split_sections(text: str) -> dict[str, str]:
+    """
+    Split the response into a dict keyed by lowercase section name.
+
+    Example input:
+        SUMMARY
+        Adds OAuth login via GitHub.
+
+        ISSUES
+        1. Missing CSRF token validation.
+
+        ...
+    """
+    result: dict[str, str] = {}
+    current_key: str | None = None
+    current_lines: list[str] = []
+
+    for line in text.splitlines():
+        m = _HEADING.match(line.strip())
+        if m:
+            # Save previous section
+            if current_key is not None:
+                result[current_key] = "\n".join(current_lines).strip()
+            current_key = m.group(1).lower()
+            current_lines = []
+        else:
+            if current_key is not None:
+                current_lines.append(line)
+
+    # Save the last section
+    if current_key is not None:
+        result[current_key] = "\n".join(current_lines).strip()
+
+    return result
+
+
+def _extract_text(section: str) -> str:
+    """Return the section content as a single stripped string."""
+    return section.strip()
+
+
+def _extract_list(section: str) -> list[str]:
+    """
+    Extract numbered list items from a section.
+
+    Falls back to plain non-empty lines if no numbered items are found
+    (handles models that skip numbering).
+    """
+    items = []
+    for line in section.splitlines():
+        m = _LIST_ITEM.match(line)
+        if m:
+            items.append(m.group(1).strip())
+
+    if not items:
+        # Fallback: any non-empty line that isn't "None" / "None found."
+        items = [
+            line.strip()
+            for line in section.splitlines()
+            if line.strip() and not re.match(r"^none[. ]*(?:found)?\.?$", line.strip(), re.IGNORECASE)
+        ]
+
+    return items
+
+
+def _extract_verdict(section: str) -> Verdict:
+    text = section.strip().upper()
+    if "APPROVE" in text:
+        return Verdict.APPROVE
+    if "REVISE" in text:
+        return Verdict.REVISE
+    return Verdict.UNKNOWN

git_sage/prompt.py

@@ -0,0 +1,100 @@
+"""
+prompt.py
+---------
+Builds the system + user prompt that is sent to the local LLM.
+
+Keeping prompts in one place makes them easy to tweak, test, and
+document.
+"""
+
+from git_sage.diff import DiffResult
+
+# ---------------------------------------------------------------------------
+# System prompt
+# ---------------------------------------------------------------------------
+# Instruct the model to act as a senior code reviewer and return structured
+# output the parser can reliably split on.
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT = """\
+You are an expert code reviewer. Your job is to review the git diff provided \
+by the user and give concise, actionable feedback.
+
+Your response MUST follow this exact structure — do not deviate:
+
+SUMMARY
+<one or two sentences describing what this change does overall>
+
+ISSUES
+<a numbered list of concrete problems found; each item on its own line>
+<if no issues found, write: None found.>
+
+SUGGESTIONS
+<a numbered list of optional improvements; each item on its own line>
+<if no suggestions, write: None.>
+
+VERDICT
+<exactly one word: APPROVE or REVISE>
+
+Rules:
+- Be direct. No preamble or closing remarks outside the structure above.
+- Focus on correctness, security, and maintainability — not style.
+- NEVER flag issues in deleted lines (lines starting with `-`). Deleted code is \
+  being intentionally removed. Only review lines being added (lines starting with `+`).
+- Flag: hardcoded secrets or tokens, missing error handling, potential \
+  null/index errors, SQL injection risks, blocking calls in async code, \
+  N+1 query patterns, obvious logic bugs.
+- Do NOT flag: formatting, naming conventions, missing comments (unless \
+  a function is genuinely unclear), or subjective preferences.
+- Keep each issue and suggestion to one sentence.
+"""
+
+
+# ---------------------------------------------------------------------------
+# User message builder
+# ---------------------------------------------------------------------------
+
+def build_review_prompt(diff: DiffResult, context: str | None = None) -> str:
+    """
+    Construct the user-turn message from a DiffResult.
+
+    Parameters
+    ----------
+    diff:
+        The DiffResult from diff.py.
+    context:
+        Optional free-text context the developer can pass (e.g. "This adds
+        OAuth support for GitHub"). Helps the model give better feedback.
+    """
+    parts: list[str] = []
+
+    # Stats header — gives the model a quick orientation
+    parts.append(
+        f"Changed files ({diff.file_count}): {', '.join(diff.files)}\n"
+        f"Lines: +{diff.additions} / -{diff.deletions}"
+    )
+
+    # If this is a pure deletion diff, tell the model explicitly
+    if diff.additions == 0 and diff.deletions > 0:
+        parts.append(
+            "Note: This diff contains only deletions (files being removed). "
+            "Do not flag issues in deleted code — it is being intentionally removed. "
+            "If the change looks clean, approve it."
+        )
+
+    if context:
+        parts.append(f"Developer note: {context}")
+
+    parts.append("Diff:\n```diff\n" + diff.raw.strip() + "\n```")
+
+    return "\n\n".join(parts)
+
+
+def build_messages(diff: DiffResult, context: str | None = None) -> list[dict]:
+    """
+    Return the messages array ready to POST to the Ollama /api/chat endpoint.
+    """
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user",   "content": build_review_prompt(diff, context)},
+    ]

git_sage-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: git-sage
+Version: 0.1.0
+Summary: Local AI code reviewer for your git workflow. Powered by Ollama
+Author-email: Joel Adewole <joeladewole3@gmail.com>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Dynamic: license-file
+
+# git-sage
+
+> Local AI code review right before you push. No cloud. No subscriptions. No data leaving your machine.
+
+`git-sage` hooks into your git workflow and runs a code review using a locally hosted LLM via [Ollama](https://ollama.com). When you run `git push`, the tool intercepts it, sends your staged diff to the model, and either approves the push or asks you to revise, all on your machine, in seconds.
+```
+$ git push
+
+  Staged: 3 file(s)  +47 / -12
+
+  ╭─ Summary ───────────────────────────────────────────────────────────╮
+  │ Adds a /login endpoint with bcrypt password hashing.                │
+  ╰─────────────────────────────────────────────────────────────────────╯
+
+  Issues  (2 found)
+
+  ●  1. The SECRET_KEY is hardcoded as a string literal on line 14.
+  ●  2. There is no rate limiting on the /login route.
+
+  Suggestions  (1)
+
+  ◆  1. Load SECRET_KEY from os.getenv('SECRET_KEY') instead.
+
+  ╭─────────────────────────────────────────────────────────────────────╮
+  │  ✗  REVISE                                                          │
+  │  Address the issues above before pushing.                           │
+  ╰─────────────────────────────────────────────────────────────────────╯
+
+  Push aborted by git-sage. Fix the issues above, or run:
+    git push --no-verify   to bypass the hook.
+```
+
+📖 **[Full documentation →](https://wolz-codelife.github.io/git-sage/)**
+
+---
+
+## Why git-sage?
+
+Most AI code review tools sit at the pull request stage, by then your code has already reached a remote server. A hardcoded secret has already been pushed. A vulnerable dependency is already on a branch other developers may have pulled.
+
+`git-sage` moves the review to your local machine, before any code leaves it. If the model finds a problem, the push is aborted and you fix it right there in your editor.
+
+---
+
+## Requirements
+
+- Python 3.9+
+- [Ollama](https://ollama.com) installed and running
+- macOS, Linux, or Windows (WSL2)
+- ~5 GB disk space for the default model
+
+No GPU required. Runs on any modern laptop.
+
+---
+
+## Quick start
+
+**1. Install Ollama and pull the model**
+```bash
+brew install ollama      # macOS — see docs for Linux/Windows
+ollama serve
+ollama pull qwen2.5-coder:7b
+```
+
+**2. Install git-sage**
+```bash
+pip install git-sage
+```
+
+**3. Install the hook in your repo**
+```bash
+cd your-project
+git-sage install
+```
+
+**4. Push as normal**
+```bash
+git push   # review runs automatically
+```
+
+---
+
+## Commands
+
+| Command                                            | Description                               |
+|----------------------------------------------------|-------------------------------------------|
+| `git-sage review`                                  | Manually review staged changes            |
+| `git-sage review --model llama3.2`                 | Use a different local model               |
+| `git-sage review --context "Adds OAuth"`           | Provide context to the model              |
+| `git-sage review --diff-mode head`                 | Review the last commit instead            |
+| `git-sage review --diff-mode branch --base main`   | Review the whole branch                   |
+| `git-sage review --force`                          | Review but don't abort push on REVISE     |
+| `git-sage install`                                 | Install the pre-push hook                 |
+| `git-sage uninstall`                               | Remove the pre-push hook                  |
+| `git-sage status`                                  | Check Ollama availability and hook status |
+| `git-sage models`                                  | List locally available Ollama models      |
+
+---
+
+## How it works
+```
+git push
+  → .git/hooks/pre-push fires
+    → git-sage review --hook
+      → git diff --cached        (extract the staged diff)
+      → build prompt             (diff + system instructions)
+      → POST localhost:11434     (Ollama local API)
+      → parse response           (SUMMARY / ISSUES / SUGGESTIONS / VERDICT)
+      → render to terminal       (rich coloured output)
+      → exit 0 (APPROVE) or exit 1 (REVISE, aborts push)
+```
+
+For a full breakdown of the architecture and each module, see the **[Architecture docs](https://wolz-codelife.github.io/git-sage/docs/architecture)**.
+
+---
+
+## Bypassing the hook
+```bash
+git push --no-verify
+```
+
+---
+
+## Project structure
+```
+git_sage/
+  cli.py       CLI entrypoint (click)
+  diff.py      Git diff extraction
+  prompt.py    Prompt builder
+  ollama.py    Ollama HTTP client
+  parser.py    Response parser
+  output.py    Terminal renderer (rich)
+  hook.py      Git hook installer
+tests/
+  test_parser.py
+  test_diff.py
+  test_prompt.py
+docs/              Docusaurus documentation site
+CHANGELOG.md       Version history
+```
+
+---
+
+## Running tests
+```bash
+pip install pytest
+pytest tests/ -v
+```
+
+Tests are self-contained; no Ollama or git repo needed.
+
+---
+
+## Contributing
+
+Contributions are welcome. See the **[Contributing guide](https://wolz-codelife.github.io/git-sage/docs/contributing)** for how to get started, issue templates, and a PR template.
+
+---
+
+## License
+
+MIT

git_sage-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+git_sage/__init__.py,sha256=SxTQOGuVukUfD8aRF6O77e4S4IrtW6-sbykoHk6dh-U,82
+git_sage/cli.py,sha256=r9k93eEcij6S_T-h-n6GSKTUundwHHxw9IToZGREvRs,6987
+git_sage/diff.py,sha256=h422cfBQuxhZr78ciqKzgk-Js57Xcm8FSFpuW1snYhE,2169
+git_sage/hook.py,sha256=ITCUfJltbjgHzEu7lU-JgoIPSptZRFNPTjdtSJheN6k,3625
+git_sage/ollama.py,sha256=hFumyFt0_HMx3aQlkNRMSqnd402RHXZ4kL6KurSCNJM,3792
+git_sage/output.py,sha256=0t4OK5YBfjA6p55J5bY3RDDaKAYAQx1s4h79w051AW0,4063
+git_sage/parser.py,sha256=kytSHo84kASGEt-hfx9dnD3l3Vyw2zy3FDLkNZKxIsk,4092
+git_sage/prompt.py,sha256=hw22J0d7HiF6_vRHrcxEvLJ0Q96HJTAx0lZ-im6VwF4,3520
+git_sage-0.1.0.dist-info/licenses/LICENSE,sha256=R3DS5GnG8Q_xwj1NlBzoZKSUEUirux3V8AdUNiVUeww,1069
+git_sage-0.1.0.dist-info/METADATA,sha256=6JDS5jK9mgXQ21JtYdFFYlEVp-lIl-ApioxLlNCv4M8,6057
+git_sage-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+git_sage-0.1.0.dist-info/entry_points.txt,sha256=p7tOoGykDsSY5ZUU9RL9xuoswMoLJMEZd1SuZGgfunc,47
+git_sage-0.1.0.dist-info/top_level.txt,sha256=l1Tqzz51n6LwLqZkWgyNjWVTRWskcDC6t3D4fsE1zqs,9
+git_sage-0.1.0.dist-info/RECORD,,

git_sage-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

git_sage-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+git-sage = git_sage.cli:main

git_sage-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joel Adewole
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

git_sage-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+git_sage