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.

# 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

pip install ripple-git

Then in any Python project:

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, add Ripple to your .pre-commit-config.yaml:

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

Then install:

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

# 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