TheArcDev/ripple-git

Semantic commit analysis for Python - catch what Git misses - TheArcDev/ripple-git

0 stars · 0 forks

README

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

Git commits it cleanly.

Three other functions that call it will crash at runtime.

Git never warned you.

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

Analyze working tree including unstaged changes

Analyze only staged changes

Smart commit — analyzes changes and suggests an accurate message

Install hook into current repository

Remove hook from current repository

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

source