git-sage 0.1.0__tar.gz

git_sage-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,162 @@
+# 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/git_sage/__init__.py

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

git_sage-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-0.1.0/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