explorer

# GitHub Projects Explorer

Discover and analyze trending open-source projects on GitHub, with support for multi-dimensional search and filtering.

## Features

- 🏷️ **Multi-Tag Filtering** - Support for one or more project topics/tags
- ⭐ **Star Count Filtering** - Filter by a minimum number of stars
- 📅 **Time Range** - Filter projects created within the last N days
- 🔤 **Programming Language** - Filter by specific programming language
- 📊 **Smart Sorting** - Sort by Stars, Forks, or Updated Time

## Prerequisites

### Optional: Configure GitHub Token

The GitHub API has rate limits (60 requests/hour unauthenticated, 5000 requests/hour authenticated).

```bash
# Get a Token: https://github.com/settings/tokens
export GITHUB_TOKEN="your_github_token"
```

To add it permanently to `~/.zshrc`:
```bash
echo 'export GITHUB_TOKEN="your-token"' >> ~/.zshrc
source ~/.zshrc
```

## Usage

### Basic Search

**Search by Topic:**
```bash
python3 scripts/github_projects.py --topic python
```

**Multiple Topics (AND relation):**
```bash
python3 scripts/github_projects.py --topic python --topic machine-learning
```

### Filter by Star Count

```bash
# Find Python projects with Stars > 1000
python3 scripts/github_projects.py --topic python --stars 1000

# Find AI projects with Stars > 10000
python3 scripts/github_projects.py --topic ai --stars 10000
```

### Filter by Time (Last N Days)

```bash
# Python projects created in the last 30 days
python3 scripts/github_projects.py --topic python --days 30

# High-star AI projects created in the last 7 days
python3 scripts/github_projects.py --topic ai --stars 100 --days 7
```

### Filter by Programming Language

```bash
# Rust projects
python3 scripts/github_projects.py --lang rust --stars 1000

# Go projects
python3 scripts/github_projects.py --lang go --stars 500 --days 30

# TypeScript projects
python3 scripts/github_projects.py --lang typescript --topic react --stars 500
```

### Comprehensive Examples

```bash
# AI Projects: Last 30 days, Python, Stars > 500
python3 scripts/github_projects.py \
  --topic ai --topic python \
  --stars 500 \
  --days 30

# Rust Tools: High stars, Last 90 days
python3 scripts/github_projects.py \
  --topic rust \
  --stars 5000 \
  --days 90 \
  --limit 50

# Frontend Frameworks: JavaScript, Stars > 1000
python3 scripts/github_projects.py \
  --topic frontend \
  --lang javascript \
  --stars 1000 \
  --sort updated
```

## Output Format

Example Output:
```
🔥 Found 30 trending projects:

1. 🌟 facebook/react
   📝 A declarative, efficient, and flexible JavaScript library...
   🔗 https://github.com/facebook/react
   📊 Stars: 220,000 | Forks: 45,000 | Language: JavaScript
   🏷️  Tags: react, frontend, javascript
   📅 Created: 2013-05-24 | Updated: 2024-02-03

2. ⭐ microsoft/vscode
   📝 Visual Studio Code
   🔗 https://github.com/microsoft/vscode
   📊 Stars: 150,000 | Forks: 30,000 | Language: TypeScript
   ...
```

## Command Arguments

| Argument | Short | Description | Example |
|----------|-------|-------------|---------|
| `--topic` | `-t` | Project topic/tag (can be used multiple times) | `-t python -t ai` |
| `--stars` | `-s` | Minimum number of stars | `--stars 1000` |
| `--days` | `-d` | Created within the last N days | `--days 30` |
| `--lang` | `-l` | Programming language | `--lang rust` |
| `--limit` | - | Number of results to return (default: 30) | `--limit 50` |
| `--sort` | - | Sorting method | `--sort stars` |

### Sorting Options

- `stars` - By star count (default, descending)
- `forks` - By fork count
- `updated` - By recent update time
- `created` - By creation time

## Recommended Trending Tags

| Domain | Recommended Tags |
|--------|------------------|
| AI/ML | `ai`, `machine-learning`, `deep-learning`, `nlp`, `computer-vision` |
| Frontend | `frontend`, `react`, `vue`, `angular`, `javascript`, `typescript` |
| Backend | `backend`, `api`, `microservices`, `nodejs`, `python` |
| Mobile Dev | `mobile`, `ios`, `android`, `flutter`, `react-native` |
| DevOps | `devops`, `docker`, `kubernetes`, `ci-cd`, `terraform` |
| Data | `database`, `big-data`, `analytics`, `sql`, `nosql` |
| Security | `security`, `cybersecurity`, `penetration-testing` |
| Tools | `cli`, `tools`, `productivity`, `automation` |

## FAQ

**Error: API rate limit exceeded**
→ Set GITHUB_TOKEN to increase limits:
```bash
export GITHUB_TOKEN="your-token"
```

**No results returned**
→ Try loosening your search criteria:
- Lower the `--stars` threshold
- Increase the `--days` count
- Reduce the number of `--topic` tags

**Inaccurate search results**
→ Use more specific tags:
- Use `machine-learning` instead of `ml`
- Use `natural-language-processing` instead of `nlp`

## Use Cases

### Scenario 1: Track Emerging Tech
```bash
# Trending AI projects from the last 30 days
python3 scripts/github_projects.py --topic ai --stars 100 --days 30 --limit 50
```

### Scenario 2: Learn from Top Projects
```bash
# High-star Python projects
python3 scripts/github_projects.py --topic python --stars 10000 --limit 20
```

### Scenario 3: Discover New Tools
```bash
# Developer tools from the last 7 days
python3 scripts/github_projects.py --topic developer-tools --topic cli --days 7 --stars 50
```

### Scenario 4: Tech Research
```bash
# Compare web frameworks across different languages
python3 scripts/github_projects.py --topic web-framework --lang rust --stars 1000
python3 scripts/github_projects.py --topic web-framework --lang go --stars 1000
```

## References

- GitHub Search API: [references/github_api.md](references/github_api.md)
- Official GitHub Docs: https://docs.github.com/en/rest/search