Metadata-Version: 2.4
Name: finops-guard
Version: 0.1.0
Summary: Automated, Developer-First Local Cloud Cost Tracing & Linting
License: Proprietary End User License Agreement (EULA)
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# FinOps-Guard 💲🛡️

> **Automated, Developer-First Local Cloud Cost Tracing & Linting**

FinOps-Guard acts as a "linter" for cloud costs and efficiency, running locally on developers' machines or within CI/CD pipelines. It bridges the gap between infrastructure configuration (Terraform) and application code efficiency (Python/JS/TS) to predict cost anomalies before they hit production.

---

## 🚀 Key Features

- **Static Cost Estimation**: Parse Terraform configurations locally and map them against cached, offline pricing datasets (`pricing_db.json`) to show the monthly dollar impact right in the terminal. No cloud API access or terraform credentials required!
- **Code-to-Cloud Tracing**: Analyze application source code statically (using AST parsing for Python and token-based heuristics for JavaScript/TypeScript) to detect inefficient loops containing synchronous API calls or cloud SDK invocations.
- **FinOps Commit Hooks**: Interactively prompt developers during `git commit` if changes exceed a cost threshold (e.g. $100/mo), preventing accidental expensive configurations from reaching staging or production.

---

## 🗺️ High-Level Launch Architecture

To bridge developer tools with commercial platforms, FinOps-Guard operates on a hybrid model:
- **Free CLI / Hooks**: Runs locally or in CI pipelines.
- **SaaS / Self-Hosted Ingestion**: Aggregates reports for dashboard visibility, billing reconciliation, and license-based policy enforcement.

![High-Level Launch Architecture](launch_architecture.png)

---

## 📂 Project Structure

```text
finopsguard/
├── finops_guard/
│   ├── __init__.py
│   ├── cli.py             # CLI command orchestrator (lint, trace, hook)
│   ├── iac_parser.py      # Local HCL resource block and JSON plan parser
│   ├── cost_estimator.py  # Mapping resource metrics to pricing configurations
│   ├── code_tracer.py     # AST-based static analyzer for loop-bound API calls
│   ├── pre_commit.py      # Git hook integration logic
│   └── data/
│       └── pricing_db.json # Offline cache of AWS & GCP pricing rates
├── examples/
│   ├── terraform/         # Sample IaC configs with expensive DB/compute resources
│   └── app/               # Sample application script with synchronous loops
├── tests/                 # Comprehensive unit test suite
│   ├── test_iac_parser.py
│   ├── test_cost_estimator.py
│   └── test_code_tracer.py
├── pyproject.toml         # Packaging file (setuptools metadata)
└── ROADMAP.md             # Monetization strategies, extensions, and growth steps
```

---

## 💻 Installation

Install the package in editable mode locally:

```bash
pip install -e .
```

---

## 🛠️ Usage

### 1. Estimating Infrastructure Costs (Linting)

Run the static cost estimator on a Terraform directory or a single `.tf`/`plan.json` file:

```bash
finops-guard lint examples/terraform
```

*Output includes a detailed table of predicted monthly costs, service breakdowns, and annual projections.*

### 2. Tracing Application Code (Code-to-Cloud Tracing)

Scan codebases for costly synchronous network calls or cloud API calls nested in loops:

```bash
finops-guard trace examples/app
```

*Flags synchronous requests inside loop blocks with nesting details and code snippets.*

### 3. Setting Up pre-commit Hooks

Add FinOps-Guard directly to your git pre-commit workflow. You can run the hook check manually:

```bash
finops-guard hook examples/terraform --threshold 100 --strict
```

To configure it as a Git pre-commit hook automatically:
1. Create or edit `.git/hooks/pre-commit` in your git repository.
2. Add the following line:
   ```bash
   finops-guard hook . --threshold 100
   ```
3. Make the hook executable: `chmod +x .git/hooks/pre-commit`.

---

## 🧪 Testing

Run the automated test suite with Python's built-in `unittest` module:

```bash
python -m unittest discover -s tests
```
