Metadata-Version: 2.4
Name: pipulse
Version: 0.1.0
Summary: Python Dependency Health Analyzer
Author-email: Prabanjan R <prabanjanyadhav@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Prabanjan R
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/prabanjan-ux/pipulse
Project-URL: Issues, https://github.com/prabanjan-ux/pipulse/issues
Keywords: python,dependency,security,audit,vulnerability,github
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=10.0.0
Requires-Dist: packaging>=23.0
Dynamic: license-file

# 🔍 PiPulse

**Python Dependency Health Analyzer** — scan your `requirements.txt` and get a full health report on every package: vulnerabilities, version status, GitHub activity, and an overall health score.

```bash
pipulse scan requirements.txt
```

---

## Features

- **Vulnerability scanning** via the [OSV](https://osv.dev) database
- **Version check** — see which packages are outdated, up-to-date, or ahead
- **GitHub activity** — ACTIVE / STALE / ABANDONED based on last commit
- **Health score** — 0–100 score per package and an overall project score
- **Three output formats** — rich terminal table, HTML report, JSON report
- Handles **unpinned packages** gracefully

---

## Installation

```bash
pip install pipulse
```

Requires Python 3.9+

---

## Usage

### Terminal output

```bash
pipulse scan requirements.txt
```

### Generate HTML report

```bash
pipulse scan requirements.txt --html
# saves to report.html

pipulse scan requirements.txt --html my_report.html
# saves to custom filename
```

### Generate JSON report

```bash
pipulse scan requirements.txt --json
# saves to report.json

pipulse scan requirements.txt --json audit.json
```

### Both at once

```bash
pipulse scan requirements.txt --html --json
```

---

## Example Output

```
                           PiPulse Report
┌──────────┬─────────┬────────┬────────────┬───────┬───────┬──────────┬────────┐
│ Package  │ Current │ Latest │ Status     │ Vulns │ Stars │ Activity │ Health │
├──────────┼─────────┼────────┼────────────┼───────┼───────┼──────────┼────────┤
│ requests │ 2.28.0  │ 2.31.0 │ Outdated   │ 2     │ 51k   │ ACTIVE   │ 70     │
│ flask    │ 3.0.0   │ 3.0.0  │ Up-to-Date │ 0     │ 67k   │ ACTIVE   │ 100    │
│ pyjwt    │ 1.7.1   │ 2.8.0  │ Outdated   │ 3     │ 5k    │ ACTIVE   │ 55     │
└──────────┴─────────┴────────┴────────────┴───────┴───────┴──────────┴────────┘

Project PiPulse Score: 75/100
```

---

## Health Score

Each package gets a score from 0 to 100 based on:

| Factor | Impact |
|---|---|
| Each vulnerability found | −5 |
| Package is outdated | −15 |
| Repository is stale (90–365 days) | −10 |
| Repository is abandoned (365+ days) | −30 |
| 10k+ GitHub stars | +5 |
| 50k+ GitHub stars | +10 |

The **project score** is the average across all scanned packages.

---

## Requirements File Format

Standard `requirements.txt` format is supported:

```
requests==2.31.0
flask>=3.0.0
packaging
```

Unpinned packages (no version specified) are flagged and skipped for vulnerability checks.

---

## Limitations

- GitHub data uses the unauthenticated API (60 requests/hour). For large `requirements.txt` files, GitHub info may return `N/A` due to rate limiting.
- Vulnerability data is sourced from OSV — coverage varies by package.

---

## License

MIT © [Prabanjan R](https://github.com/prabanjan-ux)
