mirror of
https://github.com/tiennm99/ghglance.git
synced 2026-10-11 03:13:20 +00:00
tiennm99
3fc8a59de6
The Marketplace rejects ghstats as an action name, so the repo, Go module, binary, and action share the name ghglance instead. The demo workflow keeps reading the existing GHSTATS_TOKEN repo secret.
3.2 KiB
3.2 KiB
ghglance — 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. ghglance 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) |
| ghglance | 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.