169 lines
4.6 KiB
Markdown
169 lines
4.6 KiB
Markdown
# Compare Two Codebases
|
|
|
|
Systematic workflow for comparing repositories to identify similarities, differences, and unique features.
|
|
|
|
## When to Use
|
|
|
|
- "Are repo-a and repo-b providing the same functionality?"
|
|
- "What's different between these two implementations?"
|
|
- "Which repo has more features?"
|
|
- "Can I replace library X with library Y?"
|
|
|
|
## 4-Step Comparison Workflow
|
|
|
|
### Step 1: Fetch directory structures
|
|
|
|
```bash
|
|
gh api repos/OWNER-A/REPO-A/contents/PATH > repo1.json
|
|
gh api repos/OWNER-B/REPO-B/contents/PATH > repo2.json
|
|
```
|
|
|
|
If comparing a monorepo package, specify the path (e.g., `packages/explorerkit-idls`).
|
|
|
|
### Step 2: Compare file lists
|
|
|
|
```bash
|
|
jq -r '.[].name' repo1.json > repo1-files.txt
|
|
jq -r '.[].name' repo2.json > repo2-files.txt
|
|
diff repo1-files.txt repo2-files.txt
|
|
```
|
|
|
|
This shows:
|
|
- Files unique to repo1 (prefixed with `<`)
|
|
- Files unique to repo2 (prefixed with `>`)
|
|
- Common files (no prefix)
|
|
|
|
### Step 3: Fetch key files for comparison
|
|
|
|
Compare the most important files:
|
|
|
|
#### Package dependencies
|
|
|
|
```bash
|
|
gh api repos/OWNER-A/REPO-A/contents/package.json | jq -r '.content' | base64 -d > repo1-pkg.json
|
|
gh api repos/OWNER-B/REPO-B/contents/package.json | jq -r '.content' | base64 -d > repo2-pkg.json
|
|
```
|
|
|
|
Then compare dependencies:
|
|
|
|
```bash
|
|
jq '.dependencies' repo1-pkg.json
|
|
jq '.dependencies' repo2-pkg.json
|
|
```
|
|
|
|
#### Main entry points
|
|
|
|
```bash
|
|
gh api repos/OWNER-A/REPO-A/contents/src/index.ts | jq -r '.content' | base64 -d > repo1-index.ts
|
|
gh api repos/OWNER-B/REPO-B/contents/src/index.ts | jq -r '.content' | base64 -d > repo2-index.ts
|
|
```
|
|
|
|
### Step 4: Analyze differences
|
|
|
|
Compare the fetched files to identify:
|
|
|
|
**API Surface**
|
|
- What functions/classes are exported?
|
|
- Are the APIs similar or completely different?
|
|
- Which repo has more comprehensive exports?
|
|
|
|
**Dependencies**
|
|
- Shared dependencies (same approach)
|
|
- Different dependencies (different implementation)
|
|
- Dependency versions (maintenance status)
|
|
|
|
**Unique Features**
|
|
- Features only in repo1
|
|
- Features only in repo2
|
|
- Similar features with different implementations
|
|
|
|
## Example: Compare Solana IDL Libraries
|
|
|
|
```bash
|
|
# Repo 1: solana-fm/explorer-kit (monorepo package)
|
|
gh api repos/solana-fm/explorer-kit/contents/packages/explorerkit-idls > repo1.json
|
|
|
|
# Repo 2: tenequm/solana-idls (standalone)
|
|
gh api repos/tenequm/solana-idls/contents/ > repo2.json
|
|
|
|
# Compare file structures
|
|
jq -r '.[].name' repo1.json > repo1-files.txt
|
|
jq -r '.[].name' repo2.json > repo2-files.txt
|
|
diff repo1-files.txt repo2-files.txt
|
|
|
|
# Fetch package.json from both
|
|
gh api repos/solana-fm/explorer-kit/contents/packages/explorerkit-idls/package.json | jq -r '.content' | base64 -d > repo1-pkg.json
|
|
gh api repos/tenequm/solana-idls/contents/package.json | jq -r '.content' | base64 -d > repo2-pkg.json
|
|
|
|
# Compare dependencies
|
|
echo "=== Repo 1 Dependencies ==="
|
|
jq '.dependencies' repo1-pkg.json
|
|
echo "=== Repo 2 Dependencies ==="
|
|
jq '.dependencies' repo2-pkg.json
|
|
|
|
# Fetch main entry points
|
|
gh api repos/solana-fm/explorer-kit/contents/packages/explorerkit-idls/src/index.ts | jq -r '.content' | base64 -d > repo1-index.ts
|
|
gh api repos/tenequm/solana-idls/contents/src/index.ts | jq -r '.content' | base64 -d > repo2-index.ts
|
|
|
|
# Compare exports
|
|
echo "=== Repo 1 Exports ==="
|
|
grep -E "^export" repo1-index.ts
|
|
echo "=== Repo 2 Exports ==="
|
|
grep -E "^export" repo2-index.ts
|
|
```
|
|
|
|
## Analysis Framework
|
|
|
|
After fetching files, analyze systematically:
|
|
|
|
### 1. Purpose & Scope
|
|
- What problem does each repo solve?
|
|
- Same problem or different use cases?
|
|
|
|
### 2. API Design
|
|
- Are the APIs compatible?
|
|
- Which is more user-friendly?
|
|
- Breaking changes if switching?
|
|
|
|
### 3. Dependencies
|
|
- Shared ecosystem (similar approach)
|
|
- Different dependencies (different implementation)
|
|
- Heavy vs lightweight
|
|
|
|
### 4. Maintenance
|
|
- Last commit dates
|
|
- Release frequency
|
|
- Issue/PR activity
|
|
|
|
### 5. Features
|
|
- Core features both have
|
|
- Unique to repo1
|
|
- Unique to repo2
|
|
|
|
## Tips
|
|
|
|
**Compare READMEs first**
|
|
|
|
```bash
|
|
gh api repos/OWNER-A/REPO-A/contents/README.md | jq -r '.content' | base64 -d > repo1-readme.md
|
|
gh api repos/OWNER-B/REPO-B/contents/README.md | jq -r '.content' | base64 -d > repo2-readme.md
|
|
```
|
|
|
|
This gives you a high-level understanding before diving into code.
|
|
|
|
**Check for common file patterns**
|
|
|
|
- `package.json` - Dependencies and metadata
|
|
- `tsconfig.json` - TypeScript configuration
|
|
- `src/index.ts` - Main entry point
|
|
- `README.md` - Documentation and examples
|
|
- `CHANGELOG.md` - Version history
|
|
|
|
**Use git tree for overview**
|
|
|
|
```bash
|
|
gh api repos/OWNER/REPO/git/trees/main?recursive=1 | jq '.tree[] | select(.type == "blob") | .path' | grep -E "\.(ts|js|json)$"
|
|
```
|
|
|
|
Gets all TypeScript/JavaScript/JSON files quickly.
|