GitHub Developer Toolkit

An open-source system that helps developers improve, analyze, and showcase their GitHub presence.

Overview

The GitHub Developer Toolkit analyzes a developer's GitHub profile and turns it into explainable metrics, dimension scores, findings, and actionable recommendations. A core design principle is the strict separation between raw GitHub data (the immutable source of truth) and derived analysis (everything computed from it). See docs/architecture.md.

Requirements

• Python 3.11+
• uv (Python package manager)
• Make (optional, for the quality gates)
• A GitHub Personal Access Token with read access to the data the analyzer fetches

Setup

git clone https://github.com/Joe-Huber/github-developer-toolkit.git
cd github-developer-toolkit

# install the package and dev dependencies
uv sync

# configure the GitHub token
cp .env.example .env
# then edit .env and set GHDTK_GITHUB_TOKEN

# install the pre-commit hooks
uv run pre-commit install

Configuration loads from environment variables (GHDTK_*), a .env file, or a ghdtk.toml config file, with documented precedence: env vars > .env > ghdtk.toml > defaults. See .env.example for every available variable.

Usage

# CLI entry point
uv run ghdtk --version
uv run ghdtk config          # inspect the resolved configuration

The profile-analysis commands are built out in later milestones; the data models, configuration, and module boundaries are in place now.

Quality gates

Every change must pass all gates:

make check       # lint + format-check + typecheck + test

Individual gates:

make lint        # ruff check
make format      # ruff format (auto-fix)
make format-check
make typecheck   # mypy (strict)
make test        # pytest
make coverage    # pytest with coverage report

The pre-commit hooks run the same checks automatically on every commit.

Project structure

src/ghdtk/
├── api/              # GitHub API client
├── models/
│   ├── raw/          # immutable snapshots of GitHub payloads
│   └── derived/      # metrics, scores, findings, recommendations, report
├── collectors/       # fetch API data → raw snapshots
├── analyzers/        # raw snapshots → metrics & findings
├── scoring/          # metrics → dimension scores
├── recommendations/  # findings → recommendations
├── report/           # analysis → report DTO
├── config/           # configuration (file + env + defaults)
└── cli/              # command-line interface

Contributing

PRs are welcome. Before opening one, make sure make check passes and the pre-commit hooks are green. See docs/architecture.md for the design principles every contribution should follow.

License

MIT