Metadata-Version: 2.4
Name: ripple-git
Version: 0.1.0
Summary: Semantic commit analysis for Python — catch what Git misses
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: gitpython>=3.1.0
Requires-Dist: networkx>=2.8.0
Requires-Dist: colorama>=0.4.6

# Ripple

**Semantic commit analysis for Python — catch what Git misses.**

Ripple sits at the commit moment and understands what your code change actually means. Not which lines changed — which functions, which dependencies, what breaks.

---

## The Problem

Git tracks text. It has no idea what your code does.

```python
# You delete this function
def generate_token(username):
    return "token_" + username

# Git commits it cleanly.
# Three other functions that call it will crash at runtime.
# Git never warned you.
```

Ripple catches this before the commit enters your repository.

---

## What Ripple Catches

- **Deleted functions** still called elsewhere — blocked before commit
- **Modified signatures** where callers pass wrong arguments
- **Cross-file dependencies** — catches what Git misses across modules  
- **Import aliases** — `from auth import logout as sign_out` tracked correctly
- **Class methods** — full class context in every report
- **Syntax errors** — unparseable files blocked immediately

---

## Install

```bash
pip install ripple-git
```

Then in any Python project:

```bash
cd your-project
ripple install
```

That's it. Every `git commit` now runs semantic analysis automatically.

---

## Pre-commit Framework Integration

If your project uses the [pre-commit framework](https://pre-commit.com), 
add Ripple to your `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: https://github.com/TheArcDev/ripple-git
    rev: v0.1.0
    hooks:
      - id: ripple
```

Then install:
```bash
pre-commit install
```

## What It Looks Like

```
Running Ripple semantic analysis...

=======================================================
 RIPPLE - SEMANTIC COMMIT ANALYSIS ENGINE
=======================================================

File: auth.py
----------------------------------------

 [🔴 CRITICAL] [DELETED] generate_token()
   → Had parameters: ['username']

 Real breakage detected:
 'generate_token' was deleted but is still called in 3 location(s)
     → auth.py line 2  (1 passed)
     → auth.py line 18 (1 passed)
     → app.py  line 14 (1 passed)

=======================================================
🔴 COMMIT BLOCKED
 Fix the issues above before committing
 Use --no-verify to override if intentional
=======================================================
```

---

## Commands

```bash
# Analyze staged changes without committing
ripple check

# Analyze working tree including unstaged changes  
ripple check --working

# Analyze only staged changes
ripple check --staged

# Smart commit — analyzes changes and suggests an accurate message
ripple commit

# Install hook into current repository
ripple install

# Remove hook from current repository
ripple uninstall
```

---

## Smart Commit Messages

Instead of `git commit -m "fixed stuff"`, Ripple reads what actually
changed and suggests an accurate message:

```
Suggested commit message:
----------------------------------------
add check_session(session_id) to auth
----------------------------------------

[U] Use suggested message
[W] Write your own message
[Q] Quit — don't commit
```

Messages are generated from real semantic data — not AI guessing.
Always accurate. Always specific.

---

## How It Works

Ripple uses three layers of analysis at every commit:

**1. Semantic layer** — AST parsing turns code into structured meaning.
Not which lines changed — which functions, parameters, and call
relationships changed.

**2. Graph layer** — dependency graph maps how every function connects
to every other function across your entire codebase. When something
changes, Ripple knows the full blast radius.

**3. Call site layer** — verifies whether callers of changed functions
are actually broken. Only blocks when real breakage exists — never
on clean refactors.

---

## Severity Levels

| Level | Meaning | Action |
|-------|---------|--------|
| 🔴 CRITICAL | Real breakage — will crash at runtime | Commit blocked |
| 🟠 WARN | Other functions depend on this change | Review before pushing |
| 🟢 INFO | Isolated change — no dependents affected | Commit proceeds |

---

## Requirements

- Python 3.8+
- Git

---

## Known Limitations

Ripple is a static analysis tool. It cannot detect:

- Dynamic calls via `getattr()` or `eval()`
- Runtime-only errors unrelated to function signatures
- Logic errors in function implementations

These are accepted limitations of static analysis. Ripple catches
the structural breakage that causes the most common and most painful
production failures.

---

## License

MIT
