git-repo-analyzer-test 1.0.0

package/README.md

@@ -0,0 +1,179 @@
+# Git Repository Analyzer
+
+A comprehensive Node.js tool for analyzing GitHub repositories across four critical dimensions: **Code Quality**, **Vulnerabilities**, **Code Review Practices**, and **Performance**.
+
+## Features
+
+- **📈 Code Quality Analysis**: Evaluate repository health through stars, forks, issues, documentation, and activity metrics
+- **🔒 Security & Vulnerability Assessment**: Identify potential security risks and recommend safeguards
+- **👥 Code Review & Collaboration Metrics**: Analyze pull request patterns, review velocity, and team collaboration
+- **⚡ Performance & Release Analysis**: Track release frequency, development velocity, and code frequency patterns
+- **📊 Comprehensive Reports**: Generate detailed reports with actionable recommendations
+- **🔄 Batch Analysis**: Analyze multiple repositories in one operation
+
+## Installation
+
+1. Clone or download the repository
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. (Optional) Configure GitHub token for authenticated requests:
+```bash
+npm run analyze -- config
+```
+
+Create a `.env` file in the root directory:
+```
+GITHUB_TOKEN=your_github_personal_access_token
+```
+
+## Usage
+
+### Analyze a Single Repository
+
+```bash
+npm run analyze -- analyze owner/repo-name
+```
+
+**Example:**
+```bash
+npm run analyze -- analyze facebook/react
+```
+
+### Save Report to File
+
+```bash
+npm run analyze -- analyze owner/repo-name --output ./reports/report.json
+```
+
+### Analyze Multiple Repositories
+
+Create a file `repos.txt` with one repository per line:
+```
+facebook/react
+torvalds/linux
+kubernetes/kubernetes
+nodejs/node
+```
+
+Then run:
+```bash
+npm run analyze -- batch repos.txt --output-dir ./reports
+```
+
+### View Configuration
+
+```bash
+npm run analyze -- config
+```
+
+## Report Sections
+
+### 1. Code Quality
+- Stars, forks, watchers
+- Open issues count
+- Primary language and languages used
+- Days since last update
+- Documentation presence
+- Topics and tags
+
+### 2. Security & Vulnerability
+- Risk level assessment (Critical, High, Medium, Low)
+- Risk factors identification
+- Security feature status
+- Maintenance status
+- Actionable recommendations
+
+### 3. Code Review & Collaboration
+- Pull request metrics (total, open, merged, closure rate)
+- Average review time
+- Contributor count
+- Commit patterns and unique authors
+- Review velocity analysis
+
+### 4. Performance & Release
+- Release frequency and patterns
+- Development velocity trends
+- Code activity analysis
+- Weekly additions and deletions
+- Release cadence recommendations
+
+## Environment Variables
+
+- `GITHUB_TOKEN`: Personal access token for authenticated API requests (increases rate limit from 60 to 5000 requests/hour)
+
+## API Rate Limits
+
+- **Without token**: 60 requests per hour (IP-based)
+- **With token**: 5000 requests per hour (user-based)
+
+## Project Structure
+
+```
+src/
+├── index.js              # Main entry point
+├── cli.js                # Command-line interface
+├── github/
+│  └── client.js         # GitHub API client
+├── analyzers/
+│  ├── quality.js        # Code quality analyzer
+│  ├── vulnerability.js  # Security analyzer
+│  ├── codeReview.js     # Code review analyzer
+│  └── performance.js    # Performance analyzer
+└── report/
+   └── generator.js      # Report generation
+```
+
+## Example Output
+
+```
+📊 GitHub Repository Analysis Report
+Repository: facebook/react
+Generated: 2/10/2026, 10:30:45 AM
+
+🎯 Overall Score: 92/100
+[████████████████████░░░░░░]
+
+📈 Code Quality Analysis
+Quality Score: 95/100
+┌────────────────────┬─────────┐
+│ Metric             │ Value   │
+├────────────────────┼─────────┤
+│ Stars              │ 215000  │
+│ Forks              │ 44000   │
+│ Open Issues        │ 1200    │
+└────────────────────┴─────────┘
+
+[Additional sections for security, code review, and performance...]
+```
+
+## Technologies Used
+
+- **axios**: HTTP client for API requests
+- **commander**: CLI framework
+- **chalk**: Terminal colors
+- **table**: Formatted table output
+- **dotenv**: Environment variable management
+
+## Error Handling
+
+The analyzer handles various error scenarios:
+- Invalid repository format
+- Network errors
+- API rate limit exceeded
+- Repository not found
+- Insufficient permissions
+
+## Contributing
+
+Feel free to submit issues and enhancement requests!
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Support
+
+For issues, questions, or suggestions, please open an issue in the repository.

package/USAGE.md

@@ -0,0 +1,189 @@
+# Usage Guide
+
+## Quick Start
+
+### 1. Install Dependencies
+```bash
+npm install
+```
+
+### 2. Configure GitHub Token (Optional but Recommended)
+Edit `.env` file and add your GitHub personal access token:
+```
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+Get a token from: https://github.com/settings/tokens
+
+### 3. Analyze a Repository
+
+**Single Repository:**
+```bash
+npm run analyze -- analyze facebook/react
+```
+
+**Save Report as JSON:**
+```bash
+npm run analyze -- analyze nodejs/node --output ./reports/node-report.json
+```
+
+## Command Reference
+
+### Analyze Command
+```
+npm run analyze -- analyze <owner/repo> [options]
+
+Options:
+  -o, --output <path>  Save report to JSON file
+```
+
+### Batch Command
+```
+npm run analyze -- batch <file> [options]
+
+Options:
+  -o, --output-dir <path>  Save reports to directory
+
+File format: One repository per line
+facebook/react
+nodejs/node
+kubernetes/kubernetes
+```
+
+### Config Command
+```
+npm run analyze -- config
+```
+Shows GitHub token configuration instructions.
+
+## Report Components
+
+### Code Quality Score (0-100)
+Evaluates:
+- Repository popularity (stars, forks, watchers)
+- Issue management
+- Documentation availability
+- Activity level
+- Language diversity
+
+### Vulnerability Risk Level
+- **Low**: Repository appears secure
+- **Medium**: Some security concerns
+- **High**: Significant security risks
+- **Critical**: Severe vulnerabilities
+
+Risk factors include:
+- Maintenance status
+- Security features enabled
+- Open issues count
+- Documentation coverage
+- Repository archival status
+
+### Code Review Collaboration Score (0-100)
+Metrics:
+- Pull request volume and closure rate
+- Average review time
+- Team collaboration level
+- Commit patterns
+- Contributor count
+
+### Performance Score (0-100)
+Evaluates:
+- Release frequency and patterns
+- Development velocity trends
+- Code activity over time
+- Repository maturity
+- Network metrics
+
+## API Rate Limits
+
+- **Without Token**: 60 requests/hour (IP-based)
+- **With Token**: 5000 requests/hour (user-based)
+
+## Typical Analysis Time
+
+- Single repository: 3-5 seconds
+- Batch of 10 repositories: 30-50 seconds
+
+## Example Reports
+
+### Report Structure (JSON)
+```json
+{
+  "timestamp": "2026-02-10T18:34:25.000Z",
+  "repository": "vuejs/vue",
+  "summary": {
+    "overallScore": 86,
+    "qualityScore": 94,
+    "securityScore": 50,
+    "collaborationScore": 100,
+    "performanceScore": 100,
+    "healthStatus": "Excellent"
+  },
+  "detailed": {
+    "quality": { ... },
+    "vulnerability": { ... },
+    "codeReview": { ... },
+    "performance": { ... }
+  }
+}
+```
+
+## Troubleshooting
+
+### "Cannot find module" errors
+- Ensure all dependencies are installed: `npm install`
+- Check file paths are correct (imports should use `../`)
+
+### API rate limit exceeded
+- Add GitHub token to `.env` file
+- Reduces rate limit from 60 to 5000 requests/hour
+
+### "Repository not found" error
+- Verify the repository exists and is public
+- Check the format is correct: `owner/repo-name`
+
+### No data for code frequency
+- Some statistics may not be available for certain repositories
+- This is normal and won't affect the analysis
+
+## Advanced Usage
+
+### Programmatic Use
+```javascript
+import { analyzeRepository } from './src/index.js';
+
+const { report, analysis } = await analyzeRepository('owner', 'repo');
+console.log(report.summary);
+```
+
+### Custom Report Export
+Extend `ReportGenerator` to add custom formats:
+```javascript
+static generateCSVReport(analysis) {
+  // Custom CSV export logic
+}
+```
+
+## Best Practices
+
+1. **Use GitHub Token**: Enables 80x higher API rate limits
+2. **Batch Analysis**: Analyze multiple repos at once to save time
+3. **Export Reports**: Save JSON reports for archival or comparison
+4. **Regular Audits**: Periodically re-analyze repositories to track changes
+5. **Review Recommendations**: Pay attention to generated recommendations for improvements
+
+## Support
+
+For issues or questions:
+1. Check this guide first
+2. Review the README.md for detailed documentation
+3. Check GitHub issues in your repository
+4. Verify your GitHub token has necessary permissions
+
+## Next Steps
+
+- Analyze your own repositories
+- Set up batch analysis for multiple projects
+- Export reports for team review
+- Compare reports over time to track improvements

package/bin/cli.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+import dotenv from 'dotenv';
+import chalk from 'chalk';
+import path from 'path';
+import fs from 'fs';
+import axios from 'axios';
+import { AnalyzerEngine } from '../src/core/analyzerEngine.js';
+import generator from "../src/report/generator.js";
+
+// Load env
+dotenv.config();
+
+// ⚠️ DO NOT log full key
+console.log("KEY:", process.env.OPENAI_API_KEY?.slice(0, 8));
+
+// ⚠️ DEV ONLY (remove in prod)
+process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+
+// -----------------------------
+// Parse arguments
+// -----------------------------
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+    console.log(chalk.yellow('Usage: analyze <owner/repo> [--output report.json]'));
+    process.exit(1);
+}
+
+const repoInput = args[0];
+const outputIndex = args.indexOf('--output');
+const outputPath = outputIndex !== -1 ? args[outputIndex + 1] : null;
+
+// -----------------------------
+// Parse repo
+// -----------------------------
+function parseRepo(repo) {
+    if (repo.startsWith('http')) {
+        const parts = repo
+            .replace('https://github.com/', '')
+            .replace('.git', '')
+            .split('/');
+        return { owner: parts[0], repo: parts[1] };
+    }
+    const [owner, repoName] = repo.split('/');
+    return { owner, repo: repoName };
+}
+
+const { owner, repo } = parseRepo(repoInput);
+
+if (!owner || !repo) {
+    console.error(chalk.red('❌ Invalid repository format. Use owner/repo'));
+    process.exit(1);
+}
+
+// -----------------------------
+// Run Analysis
+// -----------------------------
+(async () => {
+    try {
+        console.log(chalk.cyan(`\n🔍 Analyzing: ${owner}/${repo}\n`));
+
+        const analyzer = new AnalyzerEngine();
+        const analysis = await analyzer.runFullAnalysis(owner, repo);
+
+        // Pretty JSON output (no [Object])
+        console.log(chalk.gray("\n📊 Analysis Result:\n"));
+        console.log(JSON.stringify(analysis, null, 2));
+
+        // -----------------------------
+        // Generate TEXT report
+        // -----------------------------
+        const textReport = generator.generateReport(`${owner}/${repo}`, analysis);
+
+        console.log(chalk.green("\n📝 Text Report:\n"));
+        console.log(textReport);
+
+        // -----------------------------
+        // Generate PDF via API
+        // -----------------------------
+        const serverUrl = "http://localhost:9000";
+
+        console.log(chalk.cyan("\n📄 Generating PDF report...\n"));
+
+        const response = await axios.post(
+            `${serverUrl}/api/export-pdf`,
+            {
+                repository: `${owner}/${repo}`,
+                analysis: analysis,
+                report: {
+                    summary: analysis.summary || {}
+                }
+            },
+            {
+                responseType: "stream",
+            }
+        );
+
+        // Ensure reports folder exists
+        const reportsDir = path.join(process.cwd(), "reports");
+        if (!fs.existsSync(reportsDir)) {
+            fs.mkdirSync(reportsDir);
+        }
+
+        const fileName = `${owner}-${repo}-${Date.now()}.pdf`;
+        const filePath = path.join(reportsDir, fileName);
+
+        const writer = fs.createWriteStream(filePath);
+
+        response.data.pipe(writer);
+
+        await new Promise((resolve, reject) => {
+            writer.on("finish", resolve);
+            writer.on("error", reject);
+        });
+
+        console.log(chalk.green("\n✅ PDF Report Generated!\n"));
+        console.log(chalk.blue(`📁 Local Path: ${filePath}`));
+        console.log(chalk.blue(`🌐 Download URL: http://localhost:9000/reports/${fileName}\n`));
+
+        // -----------------------------
+        // Save JSON if --output used
+        // -----------------------------
+        if (outputPath) {
+            const fullPath = path.resolve(outputPath);
+            fs.writeFileSync(fullPath, JSON.stringify(analysis, null, 2), 'utf-8');
+
+            console.log(chalk.green(`\n✅ JSON Report saved to: ${fullPath}\n`));
+        }
+
+    } catch (error) {
+        console.error(chalk.red(`❌ Error: ${error.message}`));
+        process.exit(1);
+    }
+})();

package/docs/SONARCLOUD_ANALYSIS_COVERED.md

@@ -0,0 +1,144 @@
+# Points Covered in SonarCloud Analysis
+
+This document lists what the Repository Analyzer includes when it runs a SonarCloud-based code quality analysis.
+
+---
+
+## Short summary (at a glance)
+
+| Area | What’s covered |
+|------|----------------|
+| **Quality gate** | Status (OK / ERROR / NONE) + conditions list |
+| **Metrics** | LOC, bugs, vulnerabilities, code smells, coverage, duplication, complexity, security hotspots, ratings |
+| **Issues** | List with severity, file, line, message; breakdown by type and severity |
+| **Score** | 0–10 score + A+ to F rating from bugs, vulns, smells, gate, coverage |
+| **Recommendations** | Auto-generated from metrics (gate, bugs, vulns, smells, coverage, duplication) |
+| **UI** | KPI cards, 3 charts, metric tiles, conditions, issues table, recommendations, SonarCloud link |
+
+**APIs used (free plan):** Quality gate status, measures/component, issues/search.  
+**Optional:** Clone + SonarScanner for first-time or always-fresh scan.
+
+---
+
+## 1. Quality Gate
+
+- **Status:** OK, ERROR, or NONE (from SonarCloud `api/qualitygates/project_status`).
+- **Conditions:** Each condition shows:
+  - Metric key
+  - Status (OK / ERROR)
+  - Operator and value
+  - Error threshold (when applicable)
+- **UI:** Quality Gate KPI card (green = OK, red = ERROR, grey = NONE/unknown) and a conditions list when available.
+
+---
+
+## 2. Core Metrics (Free-Tier)
+
+| Metric | Description |
+|--------|-------------|
+| **ncloc** | Non-comment lines of code |
+| **bugs** | Number of bugs |
+| **vulnerabilities** | Number of vulnerabilities |
+| **code_smells** | Number of code smells |
+| **coverage** | Test coverage (%) |
+| **duplicated_lines_density** | Duplicated lines (%) |
+
+---
+
+## 3. Extended Metrics (When Available)
+
+| Metric | Description |
+|--------|-------------|
+| **security_hotspots** | Security hotspots count |
+| **security_hotspots_reviewed** | Hotspots reviewed (%) |
+| **sqale_rating** | Maintainability rating (A–E) |
+| **reliability_rating** | Reliability rating (A–E) |
+| **security_rating** | Security rating (A–E) |
+| **quality_gate_status** | Quality gate status from measures |
+| **complexity** | Cyclomatic complexity |
+| **cognitive_complexity** | Cognitive complexity |
+| **duplicated_blocks** | Duplicated blocks |
+| **lines** | Total lines |
+
+---
+
+## 4. Issues
+
+- **Source:** SonarCloud `api/issues/search`.
+- **Per issue:** Key, type, severity, message, component (file), line, rule, effort.
+- **Severities:** BLOCKER, CRITICAL, MAJOR, MINOR, INFO.
+- **UI:** Issues table (e.g. top 50–100), and “Issues by severity” pie chart; total issue count in KPI and in “Issues breakdown” chart (bugs, vulnerabilities, code smells, hotspots).
+
+---
+
+## 5. Quality Score & Rating
+
+- **Score:** 0–10, computed from:
+  - Bugs (deduction)
+  - Vulnerabilities (deduction)
+  - Code smells (capped deduction)
+  - Quality gate ERROR (deduction)
+  - Reliability and security ratings (A=best, E=worst)
+  - Coverage ≥ 80% (small bonus)
+- **Rating:** A+, A, B+, B, C+, C, F (from score).
+- **UI:** “Quality Score” KPI card (e.g. X/10 and rating).
+
+---
+
+## 6. Overall Summary
+
+- **Status:** Passed / Failed / Unknown (from quality gate).
+- **Metrics summary:** Bugs, vulnerabilities, code smells, coverage, duplication, ncloc (for display in the report/UI).
+
+---
+
+## 7. Recommendations
+
+Generated from the analysis (not from SonarCloud API):
+
+- **Quality gate failed** → Fix failing quality gate conditions.
+- **Bugs > 0** → Address reported bugs.
+- **Vulnerabilities > 0** → Remediate vulnerabilities.
+- **Code smells > 50** → Reduce code smells for maintainability.
+- **Coverage < 80%** → Increase test coverage toward 80%+.
+- **Duplication > 5%** → Reduce duplicated lines.
+
+Each recommendation has priority (HIGH / MEDIUM / LOW), category, and action text.
+
+---
+
+## 8. Dashboard / UI Elements
+
+- **KPI cards:** Quality Score, Quality Gate, Lines of Code, Total Issues.
+- **Charts:**
+  - Issues breakdown (bugs, vulnerabilities, code smells, security hotspots).
+  - Coverage & duplication (%).
+  - Issues by severity (BLOCKER, CRITICAL, MAJOR, MINOR, INFO).
+- **Metric tiles:** Lines of code, bugs, vulnerabilities, code smells, security hotspots, duplication, coverage, complexity.
+- **Quality gate conditions** list.
+- **Issues table** (key, rule, severity, file, line, message).
+- **Recommendations** list.
+- **Link** to view project on SonarCloud.
+
+---
+
+## 9. APIs Used (SonarCloud Free Plan)
+
+- `GET api/qualitygates/project_status` — Quality gate status and conditions.
+- `GET api/measures/component` — Metric values (free-tier and extended keys).
+- `GET api/issues/search` — Issues list (optional, page size e.g. 100).
+
+Project key is derived from `SONAR_ORGANIZATION` and the repo (e.g. `org_repo`). Branches tried: `master`, `main`, then no branch.
+
+---
+
+## 10. Optional: First-Time Scan
+
+- If the project is not on SonarCloud (or no metrics yet), the app can:
+  - Clone the repo and run SonarScanner (when `SONAR_RUN_SCANNER_IF_MISSING=true`).
+  - Or run a fresh scan on each analysis (when `SONAR_ALWAYS_RUN_SCAN=true`).
+- After a scan, the analyzer waits for metrics (configurable wait and polling) and then shows the same points above.
+
+---
+
+*This list reflects what is implemented in the Repository Analyzer’s SonarCloud integration (analyzer, client, and UI).*