Metadata-Version: 2.4
Name: suphm
Version: 0.3.3
Summary: Supply chain health metrics: a CLI for analysing OSS package health, maintainer burnout, and supply-chain risk
Project-URL: Homepage, https://github.com/SemClone/suphm
Project-URL: Documentation, https://github.com/SemClone/suphm#readme
Project-URL: Repository, https://github.com/SemClone/suphm
Author-email: oscarvalenzuelab <oscar.valenzuela.b@gmail.com>, SEMCL <info@semcl.one>
License-Expression: AGPL-3.0-or-later
License-File: AUTHORS.md
License-File: LICENSE
Keywords: metrics,purl,sbom,security,supply-chain
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: anyio>=4.0
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: osslili>=0.1.0
Requires-Dist: packageurl-python>=0.15.0
Requires-Dist: purl2src>=0.1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Description-Content-Type: text/markdown

# suphm — Supply Chain Health Metrics

[![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://opensource.org/licenses/AGPL-3.0)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://img.shields.io/pypi/v/suphm.svg)](https://pypi.org/project/suphm/)

A command-line tool that scores OSS package health, maintainer sustainability, and supply-chain risk across npm, PyPI, Cargo, Maven, Go, and direct GitHub repositories. Pulls metrics from registry APIs, GitHub, and the source repository itself; outputs structured JSON for downstream consumption.

## Features

- **Multi-Ecosystem Support**: Analyze packages from npm, PyPI, Cargo, Maven, and Go
- **Health Scoring**: Comprehensive package health assessment (0-100 score)
- **Burnout Detection**: Identify maintainer sustainability risks
- **CHAOSS Metrics**: Bus factor, pony factor, elephant factor analysis
- **Company Affiliation Enrichment**: Automatic contributor company detection via GitHub API (when token provided)
- **Tarball Inspection**: License detection (via osslili), copyright extraction, binary-file detection by extension and magic bytes, hardened against zip-slip and decompression bombs
- **GitHub Integration**: Stars, forks, issues, PRs, and release metrics
- **Flexible Output**: JSON reports for integration with other tools

### How It Works

suphm runs a comprehensive 7-step analysis pipeline:

1. **Discovery** - Fetch package metadata from deps.dev, ecosyste.ms, and package registries
2. **Clone** - Download the source repository for deep analysis
3. **Git Metrics** - Calculate CHAOSS metrics (bus factor, contributors, companies)
4. **GitHub API** - Gather community health indicators (stars, forks, issues, PRs)
5. **Tarball Scan** - Analyze package contents for licenses, copyrights, and binary files
6. **Health Score** - Compute overall package health across multiple dimensions
7. **Burnout Score** - Assess maintainer sustainability and stress indicators

## Installation

### Requirements

- Python 3.10+
- The `git` command-line binary on `PATH` (used to clone source repositories
  for git-history analysis)
- Optional: a GitHub personal access token (`GITHUB_TOKEN` or `SUPHM_GITHUB_TOKEN`)
  to lift the unauthenticated 60 req/hr cap to 5 000 req/hr.

### From PyPI

```bash
pip install suphm
```

### From source

```bash
git clone https://github.com/SemClone/suphm.git
cd suphm
pip install -e ".[dev]"
```

## Quick Start

```bash
# Analyze a package
suphm analyze pkg:npm/express

# Save results to file
suphm analyze pkg:pypi/requests --output report.json

# Analyze different ecosystems
suphm analyze pkg:cargo/serde
suphm analyze pkg:maven/org.opensearch/opensearch
suphm analyze pkg:go/github.com/hashicorp/terraform

# Discovery only (no deep analysis)
suphm discover pkg:npm/lodash
```

## Usage

### CLI Commands

```bash
# Full package analysis
suphm analyze pkg:npm/express --output analysis.json

# Metadata discovery only
suphm discover pkg:pypi/requests

# View cache information
suphm cache info

# Clear cache
suphm cache clear --all

# Check version
suphm --version
```

### Supported Package URL (PURL) Formats

```bash
# npm packages
pkg:npm/express
pkg:npm/@babel/core@7.24.0

# PyPI packages
pkg:pypi/requests
pkg:pypi/requests@2.31.0

# Cargo (Rust) packages
pkg:cargo/serde
pkg:cargo/tokio@1.32.0

# Maven packages
pkg:maven/org.opensearch/opensearch
pkg:maven/org.apache.commons/commons-lang3@3.12.0

# Go modules
pkg:go/github.com/hashicorp/terraform

# GitHub repositories
pkg:github/expressjs/express
```

### Output Format

The tool outputs JSON reports with the following metrics:

**Health Score (0-100)**
- Commit activity and release frequency
- Contributor diversity (bus factor, pony factor)
- Issue/PR responsiveness
- License compliance
- Branch protection and security

**Burnout Score (0-100)**
- Issue backlog pressure
- Response time gaps
- Triage overhead
- Workload concentration
- Activity decline trends

**Additional Metrics**
- CHAOSS metrics (bus/pony/elephant factors)
- GitHub community health (stars, forks, issues, PRs)
- License information
- Binary file detection (by extension and magic bytes)

## Using as a Python Library

suphm can also be used as a library in your Python applications:

```python
from pathlib import Path
from suphm.metrics.git import GitMetricsAnalyzer

# Analyze a git repository
analyzer = GitMetricsAnalyzer(Path("/path/to/repo"))
result = analyzer.analyze()

# Access metrics for different time windows
metrics_90d = result.time_windows["90_days"]
print(f"Commits (90d): {metrics_90d.total_commits}")
print(f"Bus factor: {metrics_90d.bus_factor}")
print(f"License: {result.license_changes.current_license}")
```

## Configuration

### GitHub Token (Recommended)

Set up a GitHub token for higher rate limits:

```bash
export GITHUB_TOKEN=ghp_your_token_here
```

### Cache Configuration

```bash
# Via environment variable
export SUPHM_CACHE_DIR=/custom/path

# Or in ~/.suphm/config.yaml
cache:
  directory: /custom/path
```

## Documentation

- [Getting Started](https://github.com/SemClone/suphm/blob/main/docs/getting-started.md)
- [Command Reference](https://github.com/SemClone/suphm/blob/main/docs/commands.md)
- [Python Library API](https://github.com/SemClone/suphm/blob/main/docs/API_REFERENCE.md)
- [Health Score Calculation](https://github.com/SemClone/suphm/blob/main/docs/HEALTH_SCORE_CALCULATION.md)
- [API Integrations](https://github.com/SemClone/suphm/blob/main/docs/api-integrations.md)
- [GitHub Token Setup](https://github.com/SemClone/suphm/blob/main/docs/github-token-setup.md)
- [SerpAPI Setup](https://github.com/SemClone/suphm/blob/main/docs/serpapi-setup.md)

## Support

- [GitHub Issues](https://github.com/SemClone/suphm/issues) — bug reports and feature requests

## License

GNU Affero General Public License v3.0. See the LICENSE file in the source repository for the full text.

---

*Part of the [SEMCL.ONE](https://semcl.one) ecosystem for comprehensive OSS compliance and code analysis.*
