Operations & Edge Cases
This page documents how the analyzer behaves under real GitHub API constraints and imperfect repository conditions.
API Call Budget
Each repository analysis requires approximately five to six GitHub API calls:
-
GET /repos/{owner}/{repo} -
GET /repos/{owner}/{repo}/contributors?per_page=1 -
GET /repos/{owner}/{repo}/commits?since=…&per_page=1 -
GET /repos/{owner}/{repo}/languages -
GET /repos/{owner}/{repo}/git/trees/{branch}?recursive=1 GET /repos/{owner}/{repo}/contents/package.jsonwhen needed for JavaScript repositories
Rate Limit Strategy
| Tier | Mechanism | Responsibility |
|---|---|---|
| 1 | Octokit throttling | Retries once with backoff when rate-limited |
| 2 | Proactive budget check | Stops early when remaining quota is too low |
| 3 | UI rate-limit indicator | Shows remaining requests and reset timing |
| Mode | Limit | Approximate repos per hour |
|---|---|---|
| No token | 60 requests per hour | About 10 |
| With token | 5000 requests per hour | About 830 |
Cache Behavior
The cache is an in-memory Map with a 10-minute TTL keyed by normalized owner/repo values.
- Good fit for repeated analysis in a single process
- Resets on server restart or serverless cold start
- Kept intentionally simple to avoid introducing storage dependencies
Edge Cases
| Scenario | Behavior |
|---|---|
| Private repository | Returns a per-repo access denied error while other repos continue |
| Missing repository | Returns a repository not found error |
| Empty repository | Metrics default near zero and the result trends Beginner |
| Huge repo over 100k files | Git Tree truncation leads to file count estimation |
| Invalid URL | Rejected by client validation and server sanitization |
| Non-GitHub URL | Rejected before analysis proceeds |
| No recent commits | Activity still uses the other four metrics |
| Rate limit exhausted | Returns 429 with reset time |
| Network timeout | Client request times out and surfaces a user-facing error |
| Partial sub-fetch failure | Failed sub-metrics default safely so one issue does not drop the whole batch |
Large Repository Handling
When the tree API reports truncated: true, the file count is estimated as:
This is deliberately conservative. The score is still usable, but it should be understood as an approximation.
Failure Isolation
The analyzer is designed so one bad repository should not poison the entire batch. That is why per-repository failures are returned alongside successful analyses rather than aborting the whole request.