Metadata-Version: 2.4
Name: github-developer-activity
Version: 0.0.3
Summary: Report GitHub activity for a user in an organization.
Author: Kaizten Analytics
License-Expression: LicenseRef-Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# GitHub Developer Activity

`github-developer-activity.py` reports activity for a GitHub user in an organization
by using the authenticated GitHub CLI (`gh`). It keeps a local JSON cache so
repeated runs do not need to rediscover every repository and issue from scratch.

## Requirements

- Python 3.10 or newer
- GitHub CLI (`gh`)
- An authenticated GitHub CLI session:

```bash
gh auth login
```

## Usage

```bash
./github-developer-activity.py --organization ORGANIZATION --username USERNAME
./github-developer-activity.py --organization ORGANIZATION --username USERNAME --days 30
./github-developer-activity.py --organization ORGANIZATION --username USERNAME --since 2026-01-01
./github-developer-activity.py --organization ORGANIZATION --username USERNAME --cache-dir ~/tmp/activity-cache
./github-developer-activity.py --organization ORGANIZATION --username USERNAME --no-print-report
./github-developer-activity.py --organization ORGANIZATION --username USERNAME --only-issues
./github-developer-activity.py --organization ORGANIZATION --username USERNAME --max-gh-calls 100
./github-developer-activity.py --organization ORGANIZATION --username USERNAME --cache-ttl-hours 24 --resume
./github-developer-activity.py --organization ORGANIZATION --username USERNAME --repo ORG/REPO --repo-prefix ORG/service-
./github-developer-activity.py --organization ORGANIZATION --username USERNAME --format json --export-csv ./activity-csv
./github-developer-activity.py report-list --organization ORGANIZATION --username USERNAME
./github-developer-activity.py report-view --organization ORGANIZATION --username USERNAME REPORT_ID
./github-developer-activity.py report-delete --organization ORGANIZATION --username USERNAME REPORT_ID [REPORT_ID ...]
./github-developer-activity.py report-diff --organization ORGANIZATION --username USERNAME OLD_REPORT_ID NEW_REPORT_ID
./github-developer-activity.py --clean-cache
./github-developer-activity.py --clean-org ORGANIZATION
./github-developer-activity.py --clean-user ORGANIZATION USERNAME
```

The output contains:

- a `status: complete|uncompleted` line after the GitHub user
- period beginning and ending timestamps
- repositories the requested user can access, with repository role
- repositories where the user has authored commits and has write, maintain, or admin access
- number of cached/discovered commits in the selected period
- the user's last commit in each repository
- per-repository issue summary for repositories where the user has write, maintain, or admin access
- the first and last repository issue numbers, URLs, creation dates, and elapsed times
- the first open repository issue number, URL, creation date, and elapsed time
- repository open and closed issue counts
- open and closed issue counts assigned to the requested username
- a repository/user assigned issue summary table
- assigned issue counts and percentages for every assignee in discovered repositories
- assigned issue counts created in the selected period and closed in the selected period
- assigned issues in those repositories
- all users assigned to each issue
- the latest issue comment text, truncated to 20 characters
- the username that wrote the latest issue comment
- the latest issue comment URL
- the time since the user's latest issue comment, shown as days, hours, and minutes
- a priority issue table for open assigned issues with the oldest or missing user comments

Closed issues in the assigned issues table show `-` for comment URL and time
since latest comment.

If neither `--days` nor `--since` is provided, commit counts use all cached and
discovered commit data.

Elapsed commit and comment times are displayed as `Nd Nh Nm`.

Assigned issues are sorted by repository, state (`open` before `closed`), time
since the user's latest comment, and issue number.

Assigned issue summary percentages use the number of issues assigned to any user
in that repository as the denominator. Period counts use issue creation dates,
and period closed counts use issue close dates.

Each normal activity run prints the report and saves the same output under the
organization/user cache. Use `--no-print-report` to save the report without
printing the report body; these runs print progress messages to stderr while
they execute. Normal runs print the complete saved report path to stderr after
the report is generated. Each saved report also stores a JSON sidecar used for
diffs and automation. At most 10 reports are kept per organization/user. Use
`report-list` to see saved report IDs, `report-view` to print one saved report,
`report-delete` to remove one or more saved reports, and `report-diff` to compare
assigned issue changes between two reports saved by this version of the tool.

If a GitHub CLI error stops a refresh, the run prints a warning, marks the
report as `status: uncompleted`, and still generates the report from the local
cache and any partial refresh data already collected.

## Refresh controls

Use `--max-gh-calls N` to stop refresh work before the run makes more than `N`
GitHub CLI calls. The report is still saved as `status: uncompleted`.

Use `--cache-ttl-hours N` to skip refresh steps that were completed less than
`N` hours ago. Use `--resume` to prioritize steps that failed or were skipped in
the previous run.

Use `--only-issues` to focus on repository issue lists and assigned issues. Use
`--skip-commits`, `--skip-comments`, or `--skip-issue-summary` for finer control.
When rate-limit preflight shows a very low remaining quota, the script
automatically prioritizes issue lists and skips lower-priority searches.

Use repeatable `--repo OWNER/NAME` and `--repo-prefix PREFIX` filters to limit
refresh work and report output to matching repositories.

Use `--format json` to print structured report data. Use `--export-csv DIR` to
write one CSV file per report section while still saving the normal report.

## Cache

By default, cache files are stored under:

```text
~/.github-developer-activity/ORGANIZATION/USERNAME/
  repositories.json
  issues.json
  metadata.json
  reports/
    REPORT_ID.md
    REPORT_ID.json
```

Each run refreshes data in this order:

1. Check repositories in the organization that the requested user can access.
2. Fetch repository issue lists for discovered repositories.
3. Check assigned issues in already discovered repositories for the requested username.
4. Check comments for newly discovered assigned issues.
5. Check comments for issues already saved locally.
6. Search for authored commits and newly discovered repositories.
7. Check assigned issues in newly discovered repositories.
8. Refresh issue summary counts for discovered repositories.

Comment details are not requested for closed issues. Closed issues keep any comment details already present in the local cache.

GitHub search APIs can return at most 1000 results for a query. When that limit is reached, the script prints a warning and the cache may not contain the full historical commit set.

Use cache cleaning options to remove stale local data:

```bash
./github-developer-activity.py --clean-cache
./github-developer-activity.py --clean-org ORGANIZATION
./github-developer-activity.py --clean-user ORGANIZATION USERNAME
```

Report IDs use UTC timestamps, for example `20260912T153045Z`.
