Prototype: scripts/star_radar.py -- GraphQL cross-repo collector

[djdarcy]

Prototype: scripts/star_radar.py -- GraphQL cross-repo collector

Parent: Cross-repo engagement radar epic
Milestone: v0.5.0 (prototype can start earlier as a script)

Goal

Build a standalone prototype script that demonstrates the core value: "which of my repos got new stars since I last checked?"

Specification

Input: User's GitHub identity (via gh auth status)

Process:

1. Call gh api graphql to fetch all repos (personal + org) with star/fork/issue counts
2. Handle pagination (cursor-based, >100 repos)
3. Store snapshot as ~/.ghtraf/portfolio/snapshots/YYYY-MM-DD.json
4. Compare against previous snapshot
5. Output delta report

Output (stdout):

Star changes since 2026-03-20:
  +2  DazzleTools/Windows-No-Internet-Secured-BUGFIX  (142 -> 144)
  +1  djdarcy/github-traffic-tracker  (12 -> 13)
  --- 47 repos unchanged ---

Fork changes since 2026-03-20:
  +1  DazzleML/comfyui-triton-and-sageattention-installer  (23 -> 24)

GraphQL query sketch:

{
  viewer {
    repositories(first: 100, ownerAffiliations: [OWNER]) {
      pageInfo { hasNextPage endCursor }
      nodes {
        nameWithOwner
        stargazerCount
        forkCount
        issues(states: OPEN) { totalCount }
        pullRequests(states: OPEN) { totalCount }
      }
    }
    organizations(first: 20) {
      nodes {
        repositories(first: 100) {
          pageInfo { hasNextPage endCursor }
          nodes {
            nameWithOwner
            stargazerCount
            forkCount
            issues(states: OPEN) { totalCount }
            pullRequests(states: OPEN) { totalCount }
          }
        }
      }
    }
  }
}

Key decisions

• Use subprocess to call gh api graphql (matches ghtraf's existing gh.py pattern)
• Store snapshots as JSON (same pattern as state.json)
• No external dependencies -- stdlib + gh CLI only
• Script should work standalone (python scripts/star_radar.py) and as a module

Graduation criteria

This script becomes ghtraf portfolio collect when:

1. It reliably collects data across all repos/orgs
2. The snapshot/delta pattern is proven
3. Output format is settled
4. ghtraf's v0.4.0 milestone is complete

Analysis

See 2026-03-21__17-57-11__dev-workflow-process_cross-repo-analytics-extend-vs-separate.md

[djdarcy]

Update: POC prototype built and validated

The POC script tests/one-offs/star_radar_poc.py has been built and tested against live data. Key findings:

What it does

• Fetches all repos (personal + 10 orgs) via GraphQL -- 92 repos in ~15 seconds
• Shows star events grouped by day with who starred + stargazers page link
• Supports --days N, --date YYYY-MM-DD, --all, --snapshot, --compare, --summary, --json
• Saves snapshots to ~/.ghtraf/portfolio/snapshots/YYYY-MM-DD.json

Coverage validation

• All 10 orgs confirmed individually queried (not relying on viewer affiliation limit)
• Forks included (14 found), flagged with isFork for optional filtering
• 92 repos total = 37 personal (OWNER) + 55 across orgs
• Per-org query approach is more thorough than a single all-affiliations query (avoids 100-repo cap)

Sample output (2026-03-22, 7-day window)

2026-03-21  (1 star)
==================================================
  +1  DazzleML/comfyui-triton-and-sageattention-installer
       by: DARKAILAB
       https://github.com/.../stargazers

2026-03-20  (2 stars)
==================================================
  +2  DazzleML/comfyui-triton-and-sageattention-installer
       by: a-i6, jerryYuX
       https://github.com/.../stargazers

What's not yet covered

• Collaborator repos on other users' personal accounts (rare edge case)
• GraphQL rate-limit handling (not needed at 92 repos, but will matter at scale)
• Fork/issue/PR delta display in star event view (tracked in snapshot, not yet surfaced per-day)

Graduation path

This script validates the core concept for #69. It graduates to ghtraf portfolio collect per #73 once the v0.4.0 milestone clears.