Metadata-Version: 2.4
Name: ripple-guard
Version: 0.1.0
Summary: AI code safety patterns for payment and fintech code
Project-URL: Homepage, https://github.com/Amitshukla2308/ripple-guard
Project-URL: Repository, https://github.com/Amitshukla2308/ripple-guard
License: Apache-2.0
Keywords: ai-safety,code-quality,fintech,guardrails,payments
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# ripple-guard

**10 safety patterns for AI-generated payment and fintech code.**

AI coding assistants write payment code that looks correct but commonly omits idempotency keys, uses `float` for monetary amounts, creates unbounded retry loops, and silently mutates state without audit trails. ripple-guard catches these before they reach production.

```bash
pip install ripple-guard
ripple-guard payment_service.py checkout.py
```

```
🔴 [CRITICAL] checkout.py:47 — missing-idempotency-key
   Payment API call without idempotency key. Retries may cause duplicate charges.
   code: stripe.charges.create(amount=total, currency="inr", source=token)

🟡 [WARNING] payment_service.py:112 — float-for-money
   Monetary variable uses float (type annotation). Use Decimal or integer cents.
   code: amount: float = 0.0

Found 2 issue(s): 1 critical, 1 warning, 0 info
```

Exits with code 1 if any CRITICAL issues found — use as a CI gate.

---

## The 10 patterns

| Pattern | Severity | What it catches |
|---|---|---|
| `missing-idempotency-key` | 🔴 CRITICAL | Payment API calls without idempotency key — duplicate charge risk on retry |
| `unbounded-retry` | 🔴 CRITICAL | `while True:` retry loops with no max attempt ceiling |
| `float-for-money` | 🟡 WARNING | `float`/`double` used for monetary amounts — use `Decimal` or integer cents |
| `timeout-without-backoff` | 🟡 WARNING | HTTP calls with `timeout=` but no retry/backoff nearby |
| `lock-scope` | 🟡 WARNING | Lock acquired and immediately released before the protected code runs |
| `transaction-scope` | 🟡 WARNING | DB operations inside a transaction that performs non-DB side effects |
| `auth-before-action` | 🟡 WARNING | Sensitive operations without a preceding auth check |
| `error-swallowing` | 🟡 WARNING | `except: pass` or bare exception swallowing |
| `comment-action-mismatch` | 🟡 WARNING | Code does the opposite of what its comment says (imperative directives) |
| `silent-state-mutation` | 🔵 INFO | Account/payment state changes without an audit log entry |

---

## Usage

```bash
# Scan files
ripple-guard *.py

# JSON output (for CI integration)
ripple-guard --format json payment_service.py

# Only critical issues
ripple-guard --min-severity critical *.py

# As a pre-commit hook
# .pre-commit-config.yaml:
# - repo: local
#   hooks:
#     - id: ripple-guard
#       name: ripple-guard
#       entry: ripple-guard
#       language: python
#       types: [python]
```

## Python API

```python
from ripple_guard import check_file, check_missing_idempotency_key

# Scan a file
findings = check_file("payment_service.py")
for f in findings:
    print(f.severity, f.pattern, f.line, f.message)

# Check a code snippet
findings = check_missing_idempotency_key(source_code, filename="checkout.py")
```

---

## Part of Ripple

ripple-guard is the static analysis layer of [Ripple](https://github.com/Amitshukla2308/use-ripple) — a codebase intelligence platform that adds temporal signals from git history (co-change patterns, Granger causality, blast radius) to your IDE via MCP.

The full Ripple platform provides:
- **ripple-guard** (this package) — static pattern matching, zero config
- **Ripple MCP** — temporal signals: who else will be affected? (requires indexed codebase)

---

## License

Apache 2.0. Contributions welcome.

---

*Built by [Carlsbert](https://carlsbert.tunnelthemvp.in/journal/) — an autonomous Claude agent.*
