mirror of
https://github.com/tiennm99/ghstats.git
synced 2026-08-31 06:27:58 +00:00
tiennm99andGitHub
9e435f631f
project-roadmap.md went from a 146-line phase-by-phase history to a 48-line focused view: what's planned, what's out of scope. Completed work is already in git log + GitHub Releases — the doc re-telling it was the thing most likely to rot and least likely to be read. project-overview-pdr.md: "Open questions" section dropped its stale bullet list and now just points at project-roadmap.md (single source of truth for planned work). code-standards.md: drop the ".claude/ directory" commit rule — that's a per-user workflow detail, not a project-level standard. Docs are for users of the CLI/Action and coworkers of this repo, nothing else.
3.2 KiB
3.2 KiB
ghstats — Product Development Requirements
One-liner
Single-binary Go CLI + GitHub Action that renders 15 themed SVG cards summarising a GitHub user's public (and optionally private) profile, for embedding in a profile README.
Users
- Primary: GitHub users maintaining a profile README who want auto-updating stat cards without a self-hosted service.
- Secondary: Tools integrating profile summaries (dashboards, portfolio sites).
Non-goals
- WakaTime-style editor telemetry.
- Cloning repos or running linguist locally (lowlighter/metrics territory). A future
-accurate-languagesmode may add per-commit REST classification; clone-mode is out of scope for v1. - Real-time / per-request API server. ghstats is a scheduled batch renderer.
Value proposition vs alternatives
| Tool | Language | Runs as | Solves per-commit attribution? |
|---|---|---|---|
| anuraghazra/github-readme-stats | JS | hosted service | No (byte-size only) |
| vn7n24fzkq/github-profile-summary-cards | TS | Action + hosted | No (primary-language-per-repo) |
| lowlighter/metrics (indepth) | JS | Action | Yes (clones + linguist-js) |
| ghstats | Go | Action + CLI | Partial (byte-weighted today; REST-per-commit planned) |
Distinguishing traits:
- Single binary: no Node, no Ruby, no Docker needed for CLI usage.
- Seed-list sampling: commit-history probes land on repos the user actually committed in (via
contributionsCollection.commitContributionsByRepository), not top-starred or owned-only. - All-time variants: for every time-bounded card (most-commit-language, productive-time, contributions), there's a lifetime counterpart.
- Accurate defaults: forks and private repos are on by default so cards reflect real activity;
-include-privatesilently no-ops if the token lacksreposcope, so the default is safe for public runs too.
Functional requirements
| # | Requirement |
|---|---|
| F1 | Render 15 cards per selected theme (see docs/system-architecture.md) |
| F2 | Support 65 themes ported from github-profile-summary-cards |
| F3 | Handle the full username→profile→cards flow in a single invocation |
| F4 | Package as GitHub Action with commit_changes auto-commit of output |
| F5 | Expose -include-forks / -include-private toggles |
| F6 | Apply byte-weighted commit-to-language attribution |
| F7 | Render smooth area charts for time-series (Catmull-Rom) |
| F8 | Support IANA timezones for productive-time (display UTC±N.NN) |
Non-functional requirements
| Axis | Target |
|---|---|
| Runtime (scheduled Action) | < 60 s for typical user |
| GraphQL calls per run | < 100 |
| REST calls per run | 0 (may grow with future modes) |
| Dependencies | stdlib only (no Go module deps required) |
| Binary size | < 15 MB stripped |
| SVG output correctness | XML-escaped, no script injection from user data |
Success metrics
- Cards render identically across
dracula,github,github_dark,nord_bright,tokyonight. - Test suite covers rendering, XML escaping, number formatting, language sort.
go vet ./...andgo test ./...clean on every commit.
Open questions
Planned follow-on work lives in project-roadmap.md.