# repo-stats

> A maintainer dashboard for any public GitHub repository. Stars, forks,
> recent issues, recent PRs, release cadence, and top contributors —
> straight from the terminal.

`repo-stats` is a thin CLI on top of the GitHub REST API. It exists
because every OSS maintainer eventually wants a one-shot snapshot of
"how is this project doing right now?" without opening seven browser
tabs.

## Install

```bash
npm install -g repo-stats
```

Set `GITHUB_TOKEN` (or `GH_TOKEN`) to lift the API rate limit from
60 req/h (anonymous) to 5,000 req/h (authenticated).

## Usage

```
repo-stats owner/repo
repo-stats https://github.com/owner/repo
repo-stats git@github.com:owner/repo.git
```

### Flags

| Flag                       | Description                                                    |
| -------------------------- | -------------------------------------------------------------- |
| `--json`                   | Emit a JSON blob instead of a table.                           |
| `--md`                     | Emit a Markdown summary (handy for status updates).            |
| `--open-only`              | Only count open issues and PRs.                                |
| `--no-color`               | Disable ANSI color output.                                     |
| `--limit-issues <n>`       | Maximum issues to fetch (default 30).                          |
| `--limit-pulls <n>`        | Maximum PRs to fetch (default 20).                             |
| `--limit-releases <n>`     | Maximum releases to fetch (default 10).                        |
| `--limit-contributors <n>` | Maximum contributors to fetch (default 20).                    |

## Programmatic API

```ts
import { parseRepoUrl, fetchRepoStats, buildSummary, renderTable } from 'repo-stats';

const repo = parseRepoUrl('vercel/next.js');
const fetched = await fetchRepoStats(repo);
const summary = buildSummary(fetched);
console.log(renderTable(summary));
```

All public types — `RepoStats`, `IssueSummary`, `PullSummary`,
`ReleaseSummary`, `ContributorSummary`, `RepoSummary` — are exported
from the package root.

## What the output shows

The table mode groups information into five sections:

- **Repository** — stars, forks, watchers, primary language, license,
  size, default branch, creation and last-push dates, topics.
- **Issues** — open/closed counts, 7-day and 30-day activity windows,
  the top five issue labels, and the five most recently updated issues.
- **Pull Requests** — open/merged/closed counts, 7-day and 30-day
  throughput, average files per PR, and the five most recently updated
  PRs.
- **Releases** — total count, latest release, average release cadence
  in days, and the five most recent releases.
- **Contributors** — total count plus the top five by contribution
  count.

The `--json` flag returns the raw, normalized payload so you can
pipe it into `jq` or your own scripts.

The `--md` flag produces a single Markdown block suitable for dropping
into a status update, weekly digest, or a `#projects` channel post.

## License

MIT — see [LICENSE](./LICENSE).