feat: add examples directory with usage scripts

examples/README.md

@@ -0,0 +1,56 @@
+# 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
+- **export-results.js** - Export evaluation results to JSON/CSV
+- **check-org-repos.js** - Evaluate all repos in an organization
+
+### 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

examples/advanced/batch-evaluate.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// 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 { exec } = require('child_process');
+const util = require('util');
+
+const execPromise = util.promisify(exec);
+
+class BatchEvaluator {
+  constructor(githubToken) {
+    this.githubToken = githubToken;
+    this.results = [];
+  }
+
+  async evaluateRepository(owner, repo) {
+    try {
+      console.log(`📊 Evaluating ${owner}/${repo}...`);
+
+      const command = this.githubToken 
+        ? `node ../../dist/index.js evaluate ${owner}/${repo} --token ${this.githubToken}`
+        : `node ../../dist/index.js evaluate ${owner}/${repo}`;
+
+      const { stdout } = await execPromise(command);
+
+      // Parse the output to extract score information
+      const scoreMatch = stdout.match(/Score: (\d+)%/);
+      const ratingMatch = stdout.match(/Rating: (\w+)/);
+
+      const result = {
+        repository: `${owner}/${repo}`,
+        timestamp: new Date().toISOString(),
+        score: scoreMatch ? parseInt(scoreMatch[1]) : 0,
+        rating: ratingMatch ? ratingMatch[1] : 'Unknown',
+        rawOutput: stdout
+      };
+
+      this.results.push(result);
+      console.log(`   Score: ${result.score}% (${result.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);
+}
+
+module.exports = { BatchEvaluator };

examples/advanced/check-org-repos.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// examples/advanced/check-org-repos.js
+
+/**
+ * Example: Check Organization Repositories
+ * 
+ * This script demonstrates how to evaluate all repositories
+ * in a GitHub organization for contributor readiness.
+ */
+
+const { exec } = require('child_process');
+const util = require('util');
+const fs = require('fs').promises;
+const path = require('path');
+
+const execPromise = util.promisify(exec);
+
+class OrganizationEvaluator {
+  constructor(githubToken) {
+    this.githubToken = githubToken;
+    this.results = [];
+  }
+
+  async getOrganizationRepos(orgName) {
+    try {
+      console.log(`🔍 Fetching repositories for organization: ${orgName}`);
+
+      // Use GitHub API to get organization repositories
+      const command = `curl -H "Authorization: token ${this.githubToken}" "https://api.github.com/orgs/${orgName}/repos?per_page=100"`;
+      const { stdout } = await execPromise(command);
+
+      const repos = JSON.parse(stdout);
+      return repos.map(repo => `${repo.owner.login}/${repo.name}`);
+    } catch (error) {
+      console.error(`❌ Error fetching organization repos:`, error.message);
+      return [];
+    }
+  }
+
+  async evaluateRepository(owner, repo) {
+    try {
+      console.log(`📊 Evaluating ${owner}/${repo}...`);
+
+      const command = this.githubToken 
+        ? `node ../../dist/index.js evaluate ${owner}/${repo} --token ${this.githubToken}`
+        : `node ../../dist/index.js evaluate ${owner}/${repo}`;
+
+      const { stdout } = await execPromise(command);
+
+      // Parse the output to extract score information
+      const scoreMatch = stdout.match(/Score: (\d+)%/);
+      const ratingMatch = stdout.match(/Rating: (\w+)/);
+
+      const result = {
+        repository: `${owner}/${repo}`,
+        score: scoreMatch ? parseInt(scoreMatch[1]) : 0,
+        rating: ratingMatch ? ratingMatch[1] : 'Unknown',
+        timestamp: new Date().toISOString()
+      };
+
+      this.results.push(result);
+      console.log(`   Score: ${result.score}% (${result.rating})`);
+
+      return result;
+    } catch (error) {
+      console.error(`❌ Error evaluating ${owner}/${repo}:`, error.message);
+      return null;
+    }
+  }
+
+  async evaluateOrganization(orgName) {
+    console.log(`🏢 Evaluating Organization: ${orgName}\n`);
+
+    const repositories = await this.getOrganizationRepos(orgName);
+
+    if (repositories.length === 0) {
+      console.log('No repositories found for this organization');
+      return;
+    }
+
+    console.log(`Found ${repositories.length} repositories to evaluate\n`);
+
+    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));
+    }
+
+    this.generateOrganizationReport(orgName);
+    await this.exportOrganizationResults(orgName);
+  }
+
+  generateOrganizationReport(orgName) {
+    if (this.results.length === 0) return;
+
+    console.log(`\n📊 Organization Report: ${orgName}`);
+    console.log('='.repeat(60));
+
+    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;
+    }, {});
+
+    // Sort by score
+    const sortedResults = this.results.sort((a, b) => b.score - a.score);
+
+    console.log(`Total Repositories: ${this.results.length}`);
+    console.log(`Average Score: ${avgScore.toFixed(1)}%`);
+    console.log(`Rating Distribution:`, ratingCounts);
+
+    console.log('\nTop Performing Repositories:');
+    sortedResults.slice(0, 5).forEach((result, index) => {
+      console.log(`  ${index + 1}. ${result.repository} - ${result.score}% (${result.rating})`);
+    });
+
+    console.log('\nRepositories Needing Attention:');
+    sortedResults.slice(-5).reverse().forEach((result, index) => {
+      console.log(`  ${index + 1}. ${result.repository} - ${result.score}% (${result.rating})`);
+    });
+  }
+
+  async exportOrganizationResults(orgName) {
+    const outputPath = path.join(__dirname, '..', 'data', `${orgName}-evaluation.json`);
+    await fs.writeFile(outputPath, JSON.stringify(this.results, null, 2));
+    console.log(`\n📄 Organization results exported to ${outputPath}`);
+  }
+}
+
+// Example usage
+async function main() {
+  const orgName = process.argv[2];
+  const token = process.env.GITHUB_TOKEN;
+
+  if (!orgName) {
+    console.error('Please provide organization name: node check-org-repos.js <org-name>');
+    process.exit(1);
+  }
+
+  if (!token) {
+    console.error('Please set GITHUB_TOKEN environment variable');
+    process.exit(1);
+  }
+
+  const evaluator = new OrganizationEvaluator(token);
+  await evaluator.evaluateOrganization(orgName);
+}
+
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+module.exports = { OrganizationEvaluator };