Metadata-Version: 2.4
Name: repopulse-cli
Version: 0.3.1
Summary: A CLI tool that analyzes GitHub repository health and generates quality reports.
Author: Ali Assiri
License-Expression: MIT
Project-URL: Homepage, https://github.com/3ssiri/RepoPulse
Project-URL: Repository, https://github.com/3ssiri/RepoPulse
Project-URL: Issues, https://github.com/3ssiri/RepoPulse/issues
Project-URL: Changelog, https://github.com/3ssiri/RepoPulse/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/3ssiri/RepoPulse/blob/main/USAGE.md
Keywords: github,cli,repository-health,oss,code-quality,maintainer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.26.8
Requires-Dist: requests>=2.34.2
Requires-Dist: rich>=15.0.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: PyYAML>=6.0.3
Provides-Extra: dev
Requires-Dist: pytest>=9.1.1; extra == "dev"
Requires-Dist: ruff>=0.16.0; extra == "dev"
Requires-Dist: mypy>=2.3.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.12.20260518; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Dynamic: license-file

# RepoPulse

[![CI](https://github.com/3ssiri/RepoPulse/actions/workflows/ci.yml/badge.svg)](https://github.com/3ssiri/RepoPulse/actions/workflows/ci.yml)
[![CodeQL](https://github.com/3ssiri/RepoPulse/actions/workflows/codeql.yml/badge.svg)](https://github.com/3ssiri/RepoPulse/actions/workflows/codeql.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

RepoPulse is a Python CLI tool that scans GitHub repositories and produces a practical health report with a score out of 100, clear warnings, and actionable recommendations.

It is built for developers who want a quick repository quality review from the terminal, and for maintainers who want a small tool they can later run in CI.

## Quick Links

- [Arabic README](README.ar.md)
- [Spanish README](README.es-ES.md)
- [Installation Guide](INSTALLATION.md)
- [Usage Guide](USAGE.md)
- [Requirements](REQUIREMENTS.md)
- [Supported Checks](docs/checks.md)
- [JSON report contract](docs/json-schema.md)
- [Architecture](ARCHITECTURE.md)
- [Contributing](CONTRIBUTING.md)
- [Security Policy](SECURITY.md)
- [Roadmap](docs/roadmap.md)
- [License](LICENSE)
- [Changelog](CHANGELOG.md)
- [Publishing guide](docs/PUBLISHING.md)
- [Releases](https://github.com/3ssiri/RepoPulse/releases)

## Why RepoPulse Matters

Open source maintainers repeat the same repository hygiene checks across projects: README quality, licensing, CI, tests, stale activity, sensitive file names, and basic security posture. RepoPulse turns those checks into a quick, repeatable report that can run locally or in automation.

The project is early-stage, but it is designed around practical maintainer workflows: fast triage, clear recommendations, CI thresholds, and machine-readable output for future automation.

## Features

- Scan public GitHub repositories by URL.
- Scan a local directory offline (`repopulse scan .`) without the GitHub API.
- Emit GitHub-issue-ready recommendations with `--format issues`.
- Scan private repositories with `--token` or `GITHUB_TOKEN`.
- Fetch repository metadata and recursive file tree through the GitHub API (remote scans).
- Score repository health out of 100.
- Render a Rich terminal report.
- Export Markdown reports.
- Print or write JSON reports.
- Produce compact summaries for automation.
- Fail CI jobs with `--fail-under`.
- Compare two scans (`repopulse compare`) with score/check deltas and `--fail-on-regression`.
- Drop-in GitHub Actions example for CI health gates ([examples/github-action-repopulse.yml](examples/github-action-repopulse.yml)).
- Customize check weights and default thresholds with `.repopulse.yml` (optional named profiles: `strict`, `library`, `docs`, `release`).
- Detect common sensitive file names without printing secret contents.
- Add advisory dependency and security baseline recommendations.

## Tech Stack

RepoPulse is built with:

| Technology | Purpose |
|---|---|
| Python 3.11+ | Core runtime. |
| Typer | CLI commands and options. |
| Requests | GitHub API calls. |
| Rich | Terminal tables and formatted output. |
| Pydantic | Typed report and check models. |
| python-dotenv | Optional `GITHUB_TOKEN` loading. |
| Pytest | Test suite. |
| Ruff | Linting in CI. |

## Installation

From PyPI — install name is `repopulse-cli` (not the unrelated PyPI package `repopulse`). CLI remains `repopulse`:

```bash
pip install repopulse-cli
repopulse --help
```

Or clone and install from source:

```bash
git clone https://github.com/3ssiri/RepoPulse.git
cd RepoPulse
pip install -e .
```

For development:

```bash
pip install -e ".[dev]"
```

See [INSTALLATION.md](INSTALLATION.md) for full setup notes.

## Basic Usage

```bash
repopulse scan .
repopulse scan https://github.com/username/repository
repopulse scan https://github.com/username/repository --export report.md
repopulse scan https://github.com/username/repository --format json --output report.json
repopulse scan https://github.com/username/repository --fail-under 75
repopulse scan https://github.com/username/repository --config .repopulse.yml
repopulse scan https://github.com/username/private-repo --token YOUR_GITHUB_TOKEN
repopulse compare ./checkout-main ./checkout-pr --fail-on-regression
```

You can also set a token in the environment:

```bash
GITHUB_TOKEN=YOUR_GITHUB_TOKEN repopulse scan https://github.com/username/private-repo
```

See [USAGE.md](USAGE.md) for all options and examples.

## OSS Maintainer Use Cases

- Run repository health checks before releases.
- Add a `--fail-under` threshold to CI for project quality gates (see [examples/github-action-repopulse.yml](examples/github-action-repopulse.yml) and [USAGE.md](USAGE.md#using-repopulse-in-github-actions)).
- Export Markdown reports for issue triage or maintainer handoff.
- Export JSON for dashboards, bots, or future AI-assisted review workflows.
- Audit public or private repositories without printing secret contents.

## Example Output

```text
RepoPulse Health Report for psf/requests
Score: 91 / 100 - Excellent

Checks
README Quality      PASS   16/20
License             PASS   10/10
.gitignore          PASS   10/10
Tests               WARN   12/15
GitHub Actions      PASS   15/15
```

## Scoring System

| Check | Points |
|---|---:|
| README Quality | 20 |
| License | 10 |
| .gitignore | 10 |
| Tests | 15 |
| GitHub Actions | 15 |
| Recent Activity | 10 |
| Sensitive Files | 10 |
| Project Structure | 5 |
| Package Scripts | 5 |

Grades:

| Score | Grade |
|---|---|
| 90-100 | Excellent |
| 75-89 | Good |
| 60-74 | Fair |
| 40-59 | Weak |
| 0-39 | Critical |

Dependency and security baseline checks are advisory in `v0.1.0`; they add recommendations without changing the 100-point score.

## Configuration

RepoPulse automatically reads `.repopulse.yml` from the current directory when present. You can also pass a file explicitly:

```bash
repopulse scan https://github.com/username/repository --config examples/repopulse.yml
```

Configuration supports default CI thresholds, disabled checks, and custom weights:

```yaml
fail_under: 85
disabled_checks:
  - activity
weights:
  readme: 25
  tests: 20
  github_actions: 20
```

See [examples/repopulse.yml](examples/repopulse.yml) for a complete example.

## Supported Checks

- README completeness.
- License presence.
- `.gitignore` presence and common patterns.
- Test folders, test files, and package test commands.
- GitHub Actions workflows for CI, tests, linting, and builds.
- Recent activity based on `pushed_at`.
- Sensitive file names such as `.env`, `credentials.json`, and private keys.
- Project structure and root clutter.
- Package scripts or Python project configuration.
- Dependency hygiene through lockfiles and Dependabot.
- Security baseline through `SECURITY.md`, Dependabot, and CodeQL.

Full details are in [docs/checks.md](docs/checks.md).

## Requirements

- Python 3.11 or newer.
- Network access to `api.github.com`.
- GitHub token for private repositories or higher API rate limits.

See [REQUIREMENTS.md](REQUIREMENTS.md) for runtime and development requirements.

## Contributing

Contributions are welcome. Keep checks independent, return `CheckResult`, and add focused tests for new behavior.

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, and contribution workflow.

## License

RepoPulse is released under the MIT License. See [LICENSE](LICENSE).
