GitHub Package Analyzer 🔍

A powerful tool to analyze GitHub repositories for package implementation and code quality using the GitHub API and OpenAI's GPT models. Evaluate your dependencies, verify implementations, and get AI-powered suggestions for improvement.

✨ Features

• 📦 Comprehensive Package Analysis

  • Scans package.json for declared dependencies
  • Verifies actual implementation in codebase
  • Custom pattern matching for different package types
  • Extensible package detection patterns

• 🤖 AI-Powered Code Analysis

  • Code quality evaluation using OpenAI GPT models
  • Implementation quality scoring
  • Best practices validation
  • Security assessment
  • Performance optimization suggestions

• 📊 Detailed Reporting

  • Overall repository health score
  • Package-by-package analysis
  • Implementation quality metrics
  • Actionable improvement suggestions
  • Letter grade assignments

• 🔄 Repository Tools

  • Full repository structure traversal
  • Intelligent file filtering
  • Multi-file code analysis
  • Dependency validation

📥 Installation

npm install github-package-analyzer

⚙️ Configuration

You'll need to provide authentication tokens:

const analyzer = new PackageAnalyzer({
    githubToken: process.env.GITHUB_TOKEN,  // GitHub Personal Access Token
    openaiKey: process.env.OPENAI_API_KEY   // OpenAI API Key
});

🚀 Usage

Basic Example

const PackageAnalyzer = require('github-package-analyzer');
const dotenv = require('dotenv');

dotenv.config();

async function main() {
    const analyzer = new PackageAnalyzer({
        githubToken: process.env.GITHUB_TOKEN,
        openaiKey: process.env.OPENAI_API_KEY
    });
    
    const result = await analyzer.analyze('owner', 'repo', ['react', 'express']);
    console.log(JSON.stringify(result, null, 2));
}

main().catch(console.error);

Extended Example with Custom Patterns

const PackageAnalyzer = require('github-package-analyzer');
const dotenv = require('dotenv');

dotenv.config();

async function analyzeFullStack() {
    // Define custom patterns for various frameworks and libraries
    const customPatterns = {
        'next': {
            filePatterns: ['.js', '.ts', '.jsx', '.tsx'],
            codePatterns: [
                'from "next"',
                'from "next/app"',
                'from "next/document"',
                'from "next/router"'
            ]
        },
        'prisma': {
            filePatterns: ['.ts', '.js'],
            codePatterns: [
                'from "@prisma/client"',
                'new PrismaClient',
                'prisma.$connect'
            ]
        },
        'tailwind': {
            filePatterns: ['.css', '.config.js'],
            codePatterns: [
                'tailwind.config',
                '@tailwind base',
                '@tailwind components',
                '@tailwind utilities'
            ]
        },
        'jest': {
            filePatterns: ['.test.js', '.spec.js', '.test.ts', '.spec.ts'],
            codePatterns: [
                'describe(',
                'test(',
                'it(',
                'expect(',
                'jest.mock'
            ]
        }
    };

    // Initialize analyzer with custom patterns
    const analyzer = new PackageAnalyzer({
        githubToken: process.env.GITHUB_TOKEN,
        openaiKey: process.env.OPENAI_API_KEY,
        patterns: customPatterns
    });

    try {
        // Analyze multiple aspects of a full-stack application
        const result = await analyzer.analyze(
            'owner',
            'repo',
            ['react', 'next', 'prisma', 'tailwind', 'jest']
        );

        // Generate detailed report
        console.log('Analysis Summary:');
        console.log('----------------');
        console.log(`Overall Grade: ${result.summary.grade}`);
        console.log(`Average Score: ${result.summary.averageScore}`);
        console.log('\nPackage Details:');
        
        result.details.dependencies.forEach(pkg => {
            console.log(`\n${pkg.package}:`);
            console.log(`  Installed: ${pkg.installed}`);
            console.log(`  Implemented: ${pkg.implementation}`);
            if (pkg.scores) {
                console.log(`  Code Quality: ${pkg.scores.codeQuality}`);
                console.log(`  Implementation Quality: ${pkg.scores.implementationQuality}`);
                console.log(`  Grade: ${pkg.grade}`);
            }
        });

        // Save detailed report to file
        const fs = require('fs');
        fs.writeFileSync(
            'analysis-report.json',
            JSON.stringify(result, null, 2)
        );

    } catch (error) {
        console.error('Analysis failed:', error);
    }
}

analyzeFullStack().catch(console.error);

📝 Analysis Features

The analyzer performs multiple levels of analysis:

1. Dependency Validation

• Checks package.json for required dependencies
• Validates both regular and dev dependencies
• Reports missing or outdated packages

2. Implementation Detection

• Scans codebase for actual package usage
• Supports multiple file extensions
• Custom pattern matching for different import styles

3. Code Quality Analysis

• Best practices adherence
• Error handling patterns
• Performance optimization opportunities
• Security vulnerability detection
• Code organization and structure

4. Implementation Quality

• Feature utilization assessment
• Integration pattern analysis
• Configuration validation
• Package-specific best practices
• Code efficiency metrics

📊 Output Format

The analyzer generates detailed reports in the following structure:

{
    "passed": true,
    "summary": {
        "totalScore": 85,
        "averageScore": 85,
        "grade": "B"
    },
    "details": {
        "dependencies": [],
        "implementation": [],
        "codeQuality": [],
        "suggestions": []
    }
}

🎯 Supported Packages

Built-in analysis patterns for:

• React
• Express

Add custom patterns by extending the configuration:

const customPatterns = {
    'packageName': {
        filePatterns: ['.ext1', '.ext2'],
        codePatterns: ['import pattern', 'require pattern']
    }
};

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. See our contributing guidelines for more details.

📄 License

MIT License - see LICENSE file for details.

👤 Author

Tom Tarpey

🔒 Security

⚠️ Important: Never commit API keys or tokens to version control. Use environment variables or secure configuration management for sensitive credentials.

📚 Documentation

For detailed API documentation and advanced usage examples, visit our documentation.