Create examples directory with usage scripts

[BekahHW]

Description

RepoReady would benefit from an examples/ directory containing practical usage scripts and demonstrations. This will help new users understand how to use the CLI effectively and provide ready-to-run examples for different scenarios.

Current State

• ❌ No examples directory exists
• ❌ No sample usage scripts
• ❌ Limited practical demonstrations
• ✅ Good documentation in README.md
• ✅ Intro and examples commands exist in CLI
• ✅ Test script exists (test-org-community-files.js)

Acceptance Criteria

Directory Structure

• Create examples/ directory in repository root
• Organize examples by use case or complexity
• Include README.md in examples directory
• Ensure all examples are executable and well-documented

Example Scripts to Create

Basic Usage Examples

• evaluate-popular-repos.js - Evaluate well-known repositories
• batch-evaluate.js - Evaluate multiple repositories
• create-repo-interactive.js - Interactive repository creation
• evaluate-with-token.js - Using GitHub tokens properly

Advanced Examples

• compare-repositories.js - Compare scores of multiple repos
• export-results.js - Export evaluation results to JSON/CSV
• check-org-repos.js - Evaluate all repos in an organization
• automated-evaluation.js - Scheduled evaluation script

Integration Examples

• github-actions-example.yml - Use RepoReady in CI/CD
• pre-commit-hook.js - Evaluate repo before commits
• slack-integration.js - Send results to Slack
• dashboard-data.js - Generate data for dashboards

Implementation Suggestions

Directory Structure

examples/
├── README.md
├── basic/
│   ├── evaluate-popular-repos.js
│   ├── create-repo-interactive.js
│   └── evaluate-with-token.js
├── advanced/
│   ├── batch-evaluate.js
│   ├── compare-repositories.js
│   └── export-results.js
├── integrations/
│   ├── github-actions-example.yml
│   ├── pre-commit-hook.js
│   └── slack-integration.js
└── data/
    ├── sample-repos.json
    └── expected-results.json

Example: Basic Repository Evaluation

#!/usr/bin/env node
// examples/basic/evaluate-popular-repos.js

/**
 * Example: Evaluate Popular Open Source Repositories
 * 
 * This script demonstrates how to use RepoReady to evaluate
 * several well-known open source repositories and compare their scores.
 */

const { exec } = require('child_process');
const util = require('util');
const execPromise = util.promisify(exec);

const popularRepos = [
  'facebook/react',
  'microsoft/vscode',
  'nodejs/node',
  'tensorflow/tensorflow',
  'vuejs/vue'
];

async function evaluateRepos() {
  console.log('🚀 Evaluating Popular Open Source Repositories\n');
  console.log('This may take a moment due to API rate limits...\n');
  
  for (const repo of popularRepos) {
    try {
      console.log(`📊 Evaluating ${repo}...`);
      
      // Use the built RepoReady CLI
      const { stdout } = await execPromise(`node ../dist/index.js evaluate ${repo}`);
      
      console.log(stdout);
      console.log('─'.repeat(50));
      
      // Small delay to respect rate limits
      await new Promise(resolve => setTimeout(resolve, 1000));
      
    } catch (error) {
      console.error(`❌ Error evaluating ${repo}:`, error.message);
    }
  }
}

// Run if called directly
if (require.main === module) {
  evaluateRepos()
    .then(() => console.log('✅ Evaluation complete!'))
    .catch(console.error);
}

module.exports = { evaluateRepos, popularRepos };

Example: Batch Evaluation with Results Export

// examples/advanced/batch-evaluate.js

/**
 * Example: Batch Repository Evaluation with Export
 * 
 * Evaluates multiple repositories and exports results to JSON
 */

const fs = require('fs').promises;
const path = require('path');
const { GitHubService } = require('../../dist/utils/github');
const { RepositoryEvaluator } = require('../../dist/evaluator');

class BatchEvaluator {
  constructor(githubToken) {
    this.githubService = new GitHubService(githubToken);
    this.evaluator = new RepositoryEvaluator();
    this.results = [];
  }

  async evaluateRepository(owner, repo) {
    try {
      console.log(`📊 Evaluating ${owner}/${repo}...`);
      
      const repoInfo = await this.githubService.getRepositoryInfo(owner, repo);
      const score = await this.evaluator.evaluate(repoInfo);
      
      const result = {
        repository: `${owner}/${repo}`,
        timestamp: new Date().toISOString(),
        score: score.percentage,
        rating: score.rating,
        totalScore: score.totalScore,
        maxScore: score.maxScore,
        recommendations: score.recommendations.length
      };
      
      this.results.push(result);
      console.log(`   Score: ${score.percentage.toFixed(1)}% (${score.rating})`);
      
      return result;
    } catch (error) {
      console.error(`❌ Error evaluating ${owner}/${repo}:`, error.message);
      return null;
    }
  }

  async evaluateBatch(repositories) {
    for (const repo of repositories) {
      const [owner, name] = repo.split('/');
      await this.evaluateRepository(owner, name);
      
      // Respect rate limits
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }

  async exportResults(filename = 'evaluation-results.json') {
    const outputPath = path.join(__dirname, '..', 'data', filename);
    await fs.writeFile(outputPath, JSON.stringify(this.results, null, 2));
    console.log(`📄 Results exported to ${outputPath}`);
  }

  generateSummary() {
    if (this.results.length === 0) return;
    
    const avgScore = this.results.reduce((sum, r) => sum + r.score, 0) / this.results.length;
    const ratingCounts = this.results.reduce((counts, r) => {
      counts[r.rating] = (counts[r.rating] || 0) + 1;
      return counts;
    }, {});
    
    console.log('\n📈 Batch Evaluation Summary');
    console.log(`   Repositories evaluated: ${this.results.length}`);
    console.log(`   Average score: ${avgScore.toFixed(1)}%`);
    console.log(`   Rating distribution:`, ratingCounts);
  }
}

// Example usage
const exampleRepos = [
  'OpenSource-Communities/RepoReady',
  'facebook/react',
  'microsoft/typescript'
];

async function main() {
  const token = process.env.GITHUB_TOKEN;
  if (!token) {
    console.error('Please set GITHUB_TOKEN environment variable');
    process.exit(1);
  }
  
  const batchEvaluator = new BatchEvaluator(token);
  
  await batchEvaluator.evaluateBatch(exampleRepos);
  batchEvaluator.generateSummary();
  await batchEvaluator.exportResults();
}

if (require.main === module) {
  main().catch(console.error);
}

Example: GitHub Actions Integration

# examples/integrations/github-actions-example.yml

# Example GitHub Actions workflow using RepoReady
name: Repository Health Check

on:
  schedule:
    # Run weekly on Sundays at 6 AM UTC
    - cron: '0 6 * * 0'
  workflow_dispatch: # Allow manual triggering

jobs:
  evaluate-repos:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'
        
    - name: Install RepoReady
      run: npm install -g repoready
      
    - name: Evaluate repository
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        echo "## Repository Health Report" >> $GITHUB_STEP_SUMMARY
        rr evaluate ${{ github.repository }} >> $GITHUB_STEP_SUMMARY
        
    - name: Evaluate competitor repositories
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        echo "## Competitor Analysis" >> $GITHUB_STEP_SUMMARY
        rr evaluate microsoft/vscode >> $GITHUB_STEP_SUMMARY
        rr evaluate facebook/react >> $GITHUB_STEP_SUMMARY

Files to Create

Main Examples README

# Examples Directory

This directory contains practical examples of using RepoReady in various scenarios.

## Getting Started

1. Build RepoReady: `npm run build`
2. Set GitHub token: `export GITHUB_TOKEN=your_token_here`
3. Run examples: `node examples/basic/evaluate-popular-repos.js`

## Directory Structure

- `basic/` - Simple usage examples for beginners
- `advanced/` - Complex scenarios and batch operations
- `integrations/` - Integration with other tools and services
- `data/` - Sample data files and expected results

## Requirements

- Node.js 16+
- Built RepoReady (`npm run build`)
- GitHub token (for API access)

## Examples Overview

### Basic Examples
- **evaluate-popular-repos.js** - Evaluate famous repositories
- **create-repo-interactive.js** - Interactive repository creation
- **evaluate-with-token.js** - Token usage best practices

### Advanced Examples
- **batch-evaluate.js** - Evaluate multiple repos with export
- **compare-repositories.js** - Side-by-side repository comparison
- **check-org-repos.js** - Evaluate entire organizations

### Integration Examples
- **github-actions-example.yml** - CI/CD integration
- **pre-commit-hook.js** - Git hook integration
- **slack-integration.js** - Notifications integration

Benefits

• 📚 Provides practical learning materials
• 🚀 Helps users get started quickly
• 💡 Demonstrates advanced use cases
• 🔧 Shows integration possibilities
• 📊 Includes real-world scenarios
• 🎯 Reduces support burden with self-service examples

Integration with Documentation

• Link examples from main README.md
• Reference examples in CLI help text
• Include in getting started guides
• Use in tutorials and blog posts

Estimated Effort

Medium - Requires creating multiple working examples and documentation.

---

Perfect for contributors who want to help users succeed with RepoReady! 📚