Metadata-Version: 2.4
Name: hermes-repo-audit
Version: 0.1.0
Summary: GitHub repo launch-readiness auditor — signals your repo is missing for public discoverability.
Project-URL: Homepage, https://github.com/roli-lpci/repo-audit
Project-URL: Repository, https://github.com/roli-lpci/repo-audit
Project-URL: Issues, https://github.com/roli-lpci/repo-audit/issues
Author: roli-lpci
License: Apache-2.0
License-File: LICENSE
Keywords: audit,cli,devtools,discoverability,github,launch,open-source,repo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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 :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: ddgs>=7.0
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: responses; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# repo-audit: GitHub repo launch-readiness checker

[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
[![CI](https://github.com/roli-lpci/repo-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/roli-lpci/repo-audit/actions)

Your repo works locally. Now what? Most repos stay invisible not because the code is bad, but because no topics are set, no PyPI page exists, the README is three lines, and nobody has ever posted it anywhere.

`repo-audit` measures that gap in under 30 seconds and gives you a ranked to-do list you can act on immediately.

- "My repo has 0 stars and I don't know where to start."
- "I pushed a tool but it doesn't show up in GitHub search."
- "I want a quick audit before sharing a repo publicly."
- "I need to know what's missing before submitting to an awesome-* list."
- "I want to verify my launch checklist is actually done."

## Install

```bash
pip install repo-audit
```

Requires Python 3.10+. No GitHub token needed.

## Quick Start

```bash
repo-audit github.com/psf/black
```

## Exact Outcome

```text
repo-audit: github.com/psf/black
  Score: 91/100  Grade: A  (12.3s)

  PASS  README Quality         100/100
  PASS  Repo Metadata          100/100
  PASS  Social Proof           100/100
  PASS  Release Cadence        100/100
  PASS  Docs & Agent Files      90/100
  PASS  Distribution (PyPI/npm) 100/100
  PASS  Web Discoverability    100/100
  FAIL  Topical Citations       40/100
  WARN  Launch Channels         75/100

Top actions:
  [Topical Citations] Post 'Show HN: black — ...' at news.ycombinator.com.
  [Launch Channels] Submit a PR to the relevant awesome-* list.
```

## Other Flags

```bash
# JSON output for scripting or CI
repo-audit github.com/psf/black --json

# Verbose: show per-signal findings and source URLs
repo-audit github.com/psf/black --verbose
```

## Signal Categories

| Signal | Weight | What it checks |
|---|---|---|
| README Quality | 15% | length, quickstart, badges, license mention |
| Repo Metadata | 12% | description, topics, homepage |
| Social Proof | 10% | stars, forks, commit recency |
| Release Cadence | 8% | GitHub releases and tags |
| Docs & Agent Files | 10% | AGENTS.md, llms.txt, CONTRIBUTING, CHANGELOG |
| Distribution | 15% | PyPI or npm presence |
| Web Discoverability | 12% | DDG: does repo appear in top search results? |
| Topical Citations | 10% | DDG: HN, Reddit, arXiv site: queries |
| Launch Channels | 8% | awesome-* lists, DEV.to articles |

## When To Use It

- Before sharing a repo publicly (Show HN, blog post, tweet)
- Before submitting to an awesome-* list
- As a lightweight pre-launch CI check
- When auditing an existing repo to find quick wins

## When Not To Use It

- To audit private repos (GitHub public API only, by design)
- To check code quality (use a linter for that)
- When you need proof of correctness, not a discoverability signal

## Provenance Gate

Every signal in the output cites the GitHub API URL or search result URL it was derived from. No fabricated scores. When a signal can't be found (e.g. a private repo), the tool returns an honest null and cites the empty source URL.

## Python API

```python
from repo_audit.audit import run_audit
from repo_audit.formatter import format_text

report = run_audit("github.com/psf/black")
print(report.overall_score)   # int 0-100
print(report.grade)           # "A" | "B" | "C" | "D" | "F"
print(report.top_actions)     # list[str] ranked action items
```

## License

Apache-2.0
