diff --git a/.github/workflows/repository-overseer.yml b/.github/workflows/repository-overseer.yml new file mode 100644 index 0000000..ce69ab3 --- /dev/null +++ b/.github/workflows/repository-overseer.yml @@ -0,0 +1,292 @@ +name: Repository Overseer + +on: + # Run on schedule + schedule: + - cron: '0 0 * * 0' # Weekly on Sunday at midnight + + # Allow manual trigger + workflow_dispatch: + inputs: + analysis_type: + description: 'Type of analysis to run' + required: false + default: 'full' + type: choice + options: + - full + - code + - docs + - deps + - cicd + - issues + - automation + - monitor + + # Run on push to main branches + push: + branches: + - main + - master + paths: + - '**.py' + - 'requirements.txt' + - 'package.json' + - '.github/workflows/**' + + # Run on pull requests + pull_request: + types: [opened, synchronize, reopened] + +jobs: + overseer-analysis: + name: Run Repository Overseer + runs-on: ubuntu-latest + permissions: + contents: write + issues: write + pull-requests: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better analysis + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + cache: 'pip' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + + - name: Run Repository Overseer + id: overseer + run: | + if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then + ANALYSIS_TYPE="${{ github.event.inputs.analysis_type }}" + else + ANALYSIS_TYPE="full" + fi + + if [[ "$ANALYSIS_TYPE" == "full" ]]; then + python run_overseer.py --verbose --output overseer-results.json + else + python run_overseer.py --only "$ANALYSIS_TYPE" --verbose --output overseer-results.json + fi + continue-on-error: true + + - name: Upload analysis results + uses: actions/upload-artifact@v4 + if: always() + with: + name: overseer-results + path: overseer-results.json + retention-days: 30 + + - name: Generate analysis summary + if: always() + run: | + python -c " + import json + import os + + with open('overseer-results.json') as f: + data = json.load(f) + + summary = [] + summary.append('# ๐Ÿ” Repository Overseer Analysis') + summary.append('') + summary.append(f'**Timestamp:** {data.get(\"timestamp\", \"N/A\")}') + summary.append('') + + analyses = data.get('analyses', {}) + + # Code Analysis + code = analyses.get('code', {}) + if code: + summary.append('## ๐Ÿ“Š Code Quality') + summary.append(f'- **Quality Score:** {code.get(\"code_quality_score\", code.get(\"quality_score\", 0))}/100') + summary.append(f'- **Refactoring Opportunities:** {len(code.get(\"refactoring_opportunities\", []))}') + summary.append(f'- **Architectural Improvements:** {len(code.get(\"architectural_improvements\", []))}') + summary.append(f'- **Performance Issues:** {len(code.get(\"performance_optimizations\", []))}') + summary.append('') + + # Dependencies + deps = analyses.get('dependencies', {}) + if deps: + vuln_count = len(deps.get('vulnerable_packages', [])) + outdated_count = len(deps.get('outdated_packages', [])) + + summary.append('## ๐Ÿ“ฆ Dependencies') + if vuln_count > 0: + summary.append(f'- โš ๏ธ **Vulnerable Packages:** {vuln_count}') + else: + summary.append('- โœ… **No vulnerable packages found**') + summary.append(f'- **Outdated Packages:** {outdated_count}') + summary.append(f'- **Upgrade Recommendations:** {len(deps.get(\"upgrade_recommendations\", []))}') + summary.append('') + + # CI/CD + cicd = analyses.get('cicd', {}) + if cicd: + summary.append('## โš™๏ธ CI/CD') + summary.append(f'- **Workflow Optimizations:** {len(cicd.get(\"workflow_optimizations\", []))}') + summary.append(f'- **Test Improvements:** {len(cicd.get(\"test_improvements\", []))}') + summary.append(f'- **Linting Suggestions:** {len(cicd.get(\"linting_suggestions\", []))}') + summary.append('') + + # Recommendations + recs = data.get('recommendations', []) + if recs: + summary.append('## ๐Ÿ’ก Top Recommendations') + critical = [r for r in recs if r.get('priority') == 'critical'] + high = [r for r in recs if r.get('priority') == 'high'] + + if critical: + summary.append('### ๐Ÿ”ด Critical') + for rec in critical[:3]: + summary.append(f'- {rec.get(\"message\", \"\")}') + + if high: + summary.append('### ๐ŸŸก High Priority') + for rec in high[:5]: + summary.append(f'- {rec.get(\"message\", \"\")}') + summary.append('') + + summary.append('---') + summary.append('๐Ÿ“ Full results available in the workflow artifacts') + + # Write to step summary + with open(os.environ['GITHUB_STEP_SUMMARY'], 'w') as f: + f.write('\n'.join(summary)) + " + + - name: Create issue for critical findings + if: always() + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const results = JSON.parse(fs.readFileSync('overseer-results.json', 'utf8')); + + const recommendations = results.recommendations || []; + const critical = recommendations.filter(r => r.priority === 'critical'); + const high = recommendations.filter(r => r.priority === 'high'); + + if (critical.length > 0 || high.length > 0) { + const deps = results.analyses?.dependencies || {}; + const vulnerabilities = deps.vulnerable_packages || []; + + let body = '## ๐Ÿ” Repository Overseer - Critical Findings\n\n'; + body += `**Analysis Date:** ${results.timestamp}\n\n`; + + if (critical.length > 0) { + body += '### ๐Ÿ”ด Critical Issues\n\n'; + critical.forEach(rec => { + body += `- **[${rec.category}]** ${rec.message}\n`; + }); + body += '\n'; + } + + if (vulnerabilities.length > 0) { + body += '### โš ๏ธ Security Vulnerabilities\n\n'; + vulnerabilities.slice(0, 5).forEach(vuln => { + body += `- **${vuln.package}** (${vuln.current_version}): ${vuln.vulnerability}\n`; + if (vuln.fixed_in) { + body += ` - Fix: Upgrade to ${vuln.fixed_in}\n`; + } + }); + if (vulnerabilities.length > 5) { + body += `\n_...and ${vulnerabilities.length - 5} more vulnerabilities_\n`; + } + body += '\n'; + } + + if (high.length > 0) { + body += '### ๐ŸŸก High Priority Issues\n\n'; + high.slice(0, 10).forEach(rec => { + body += `- **[${rec.category}]** ${rec.message}\n`; + }); + if (high.length > 10) { + body += `\n_...and ${high.length - 10} more high priority issues_\n`; + } + body += '\n'; + } + + body += '\n---\n'; + body += 'Full analysis results are available in the [workflow artifacts]'; + body += `(${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}).\n`; + + // Check if an issue already exists + const issues = await github.rest.issues.listForRepo({ + owner: context.repo.owner, + repo: context.repo.repo, + labels: 'overseer-findings', + state: 'open' + }); + + if (issues.data.length > 0) { + // Update existing issue + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: issues.data[0].number, + body: `## ๐Ÿ”„ Updated Findings\n\n${body}` + }); + } else { + // Create new issue + await github.rest.issues.create({ + owner: context.repo.owner, + repo: context.repo.repo, + title: '๐Ÿ” Repository Overseer - Critical Findings', + body: body, + labels: ['overseer-findings', 'automated'] + }); + } + } + + dependency-security-scan: + name: Security Vulnerability Scan + runs-on: ubuntu-latest + permissions: + contents: read + security-events: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install safety pip-audit + + - name: Run safety check + continue-on-error: true + run: | + safety check --json --output safety-report.json || true + + - name: Run pip-audit + continue-on-error: true + run: | + pip-audit --format json --output pip-audit-report.json || true + + - name: Upload security reports + uses: actions/upload-artifact@v4 + if: always() + with: + name: security-reports + path: | + safety-report.json + pip-audit-report.json + retention-days: 30 diff --git a/.gitignore b/.gitignore index 134cfb8..1c95f3d 100644 --- a/.gitignore +++ b/.gitignore @@ -210,3 +210,4 @@ __marimo__/ overseer-results.json README_ENHANCED.md CONTRIBUTING_ENHANCED.md +coverage.json diff --git a/CONTRIBUTING_GENERATED.md b/CONTRIBUTING_GENERATED.md new file mode 100644 index 0000000..b29a8cb --- /dev/null +++ b/CONTRIBUTING_GENERATED.md @@ -0,0 +1,48 @@ +# Contributing Guide + +Thank you for your interest in contributing to ! + +## Getting Started + +1. Fork the repository +2. Clone your fork +3. Create a new branch for your feature +4. Make your changes +5. Run tests +6. Submit a pull request + +## Development Setup + +See the [User Guide](USER_GUIDE.md) for setup instructions. + +## Code Style + +### Python + +- Follow PEP 8 style guide +- Use type hints where appropriate +- Write docstrings for all public functions and classes +- Maximum line length: 100 characters + +## Testing + +All new features must include tests. + +Run tests with: + +```bash +pytest +``` + +## Pull Request Process + +1. Update documentation as needed +2. Add tests for new functionality +3. Ensure all tests pass +4. Update CHANGELOG.md +5. Request review from maintainers + +## Code of Conduct + +Please be respectful and constructive in all interactions. + diff --git a/HEALTH_DASHBOARD.md b/HEALTH_DASHBOARD.md new file mode 100644 index 0000000..47fe6f8 --- /dev/null +++ b/HEALTH_DASHBOARD.md @@ -0,0 +1,67 @@ +# ๐Ÿ“Š Repository Health Dashboard + +*Last updated: 2026-02-17T10:59:28.359584* + +--- + +## Overall Health + +### ๐Ÿ”ด Score: 45/100 + +``` +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 45% +``` + +**Status:** Poor - Immediate action required + +--- + +## ๐Ÿ’ป Code Quality + +- **Quality Score:** 0/100 +- **Refactoring Opportunities:** 1249 +- **Architectural Improvements:** 91 +- **Performance Issues:** 83 + +## ๐Ÿ“ฆ Dependencies + +- โœ… **Vulnerable Packages:** 0 +- **Outdated Packages:** 0 +- **Upgrade Recommendations:** 0 + +## โš™๏ธ CI/CD + +- **Workflow Optimizations:** 14 +- **Test Improvements:** 1 +- **Linting Suggestions:** 1 + +## ๐Ÿ“š Documentation + +- **README:** โœ… +- **Contributing Guide:** โœ… +- **API Documentation:** โœ… + +## ๐Ÿท๏ธ Issue Management + +- **Issues Processed:** 0 +- **Labels Applied:** 0 +- **Priorities Assigned:** 0 + +## ๐Ÿ“ˆ Monitoring + +- **Total Recommendations:** 4 +- **High Priority:** 3 +- **Medium Priority:** 1 +- **Low Priority:** 0 + +--- + +## ๐Ÿ’ก Top Recommendations + +### ๐ŸŸก High Priority + +- **[code_quality]** Found 1249 refactoring opportunities. Consider addressing high-priority items. + +--- + +*Generated by Repository Overseer* diff --git a/OVERSEER_COMPLETE_SUMMARY.md b/OVERSEER_COMPLETE_SUMMARY.md new file mode 100644 index 0000000..7e4c1a5 --- /dev/null +++ b/OVERSEER_COMPLETE_SUMMARY.md @@ -0,0 +1,317 @@ +# Repository Overseer - Complete Implementation Summary + +## Overview + +This repository now includes a fully functional **Advanced Full-Stack Repository Overseer** system that automatically manages and improves repositories across seven key dimensions. + +## โœ… Implemented Features + +### 1. Deep Code Analysis ๐Ÿ” + +**Module:** `overseer/code_analyzer.py` + +The code analyzer performs comprehensive AST-based analysis to detect: + +- **Refactoring Opportunities** + - Long functions (>50 lines) + - Code duplication (5+ line blocks) + - Complex conditionals (>3 boolean operations) + - Magic numbers that should be constants + +- **Architectural Issues** + - God classes (>20 methods) + - Missing docstrings + - SOLID principle violations + +- **Performance Problems** + - List comprehension opportunities + - Inefficient string concatenation in loops + - Algorithm complexity issues + +**Quality Score:** Calculated based on detected issues (0-100 scale) + +### 2. Smart Documentation Generation ๐Ÿ“š + +**Module:** `overseer/doc_generator.py` + +Automatically generates: + +- Enhanced README.md with comprehensive project information +- CONTRIBUTING.md guidelines +- API documentation from docstrings +- Architecture documentation +- User guides + +**Tools:** +- `scripts/generate_comprehensive_docs.py` - Standalone doc generator +- Generates: API Reference, User Guide, Architecture docs, Contributing guide + +### 3. Intelligent Dependency Management ๐Ÿ“ฆ + +**Module:** `overseer/dependency_manager.py` + +Features: +- Scans Python (requirements.txt) and JavaScript (package.json) dependencies +- Detects outdated packages +- Identifies known vulnerabilities +- Suggests secure upgrades with version recommendations +- Multi-ecosystem support + +**Integration:** +- GitHub Actions workflow includes safety and pip-audit scanning +- Automated security reports + +### 4. CI/CD Workflow Optimization โš™๏ธ + +**Module:** `overseer/cicd_optimizer.py` + +Analyzes and optimizes: +- Existing GitHub Actions workflows +- Caching strategies +- Matrix testing configurations +- Job performance +- Missing workflows (test, lint, deploy) + +**Suggestions:** +- Workflow parallelization +- Dependency caching +- Build optimization +- Test splitting + +### 5. Automated Issue Triaging ๐Ÿท๏ธ + +**Module:** `overseer/issue_triager.py` + +Capabilities: +- Pattern-based label assignment +- Intelligent priority detection +- Security issue identification +- Duplicate detection +- Auto-categorization (bug, enhancement, documentation, security, performance, testing) + +**Configuration:** Define custom label patterns in `overseer-config.json` + +### 6. Automation Script Generation ๐Ÿค– + +**Module:** `overseer/automation_engine.py` + +**Tool:** `scripts/generate_automation_scripts.py` + +Generated scripts (in `scripts/automation/`): +- `format-python.sh` - Python code formatting (black + isort) +- `format-javascript.sh` - JS/TS formatting (prettier) +- `create-release.sh` - Automated versioning and release creation +- `setup-dev-env.sh` - Development environment setup +- `run-tests.sh` - Test execution with coverage +- `lint-code.sh` - Multi-language linting + +All scripts are: +- Cross-platform compatible +- Well-documented +- Executable and ready to use + +### 7. Real-time Repository Monitoring ๐Ÿ“Š + +**Module:** `overseer/monitor.py` + +**Tool:** `scripts/generate_health_dashboard.py` + +Monitors: +- Code quality metrics +- Performance trends +- Security posture +- Collaboration health +- Test coverage +- Build times + +**Dashboard Features:** +- Overall health score (0-100) +- Visual progress bars +- Priority-based recommendations +- Metric breakdowns +- Trend analysis + +## ๐Ÿš€ GitHub Actions Integration + +**Workflow:** `.github/workflows/repository-overseer.yml` + +### Triggers +- Weekly schedule (Sunday at midnight) +- Push to main/master branches +- Pull request events +- Manual workflow dispatch + +### Capabilities +- Runs full overseer analysis +- Uploads results as artifacts +- Generates workflow summaries +- Creates GitHub issues for critical findings +- Integrates with security scanning (safety, pip-audit) +- Updates existing issues with new findings + +### Workflow Features +- Configurable analysis types (full, code, deps, cicd, issues, automation, monitor) +- Artifact retention (30 days) +- Automatic issue creation for vulnerabilities +- Summary generation for PR reviews + +## ๐Ÿ“‹ Configuration + +**File:** `overseer-config.json` + +Comprehensive configuration for: +- Code analysis thresholds +- Documentation generation +- Dependency management +- CI/CD optimization +- Issue triaging patterns +- Automation preferences +- Monitoring metrics +- Notification settings +- Path exclusions + +## ๐ŸŽฏ Usage Examples + +### Run Full Analysis +```bash +python run_overseer.py +``` + +### Run Specific Analysis +```bash +python run_overseer.py --only code +python run_overseer.py --only deps +python run_overseer.py --only cicd +``` + +### Custom Configuration +```bash +python run_overseer.py --config custom-config.json +``` + +### Generate Documentation +```bash +python scripts/generate_comprehensive_docs.py +``` + +### Generate Automation Scripts +```bash +python scripts/generate_automation_scripts.py +``` + +### Generate Health Dashboard +```bash +python scripts/generate_health_dashboard.py +``` + +## ๐Ÿ“Š Current Repository Health + +Based on the latest analysis: + +- **Overall Health Score:** 45/100 (Needs Improvement) +- **Code Quality Score:** 0/100 +- **Refactoring Opportunities:** 1,249 +- **Architectural Improvements:** 91 +- **Performance Issues:** 83 +- **Vulnerable Dependencies:** 0 โœ… +- **CI/CD Optimizations:** 14 +- **Documentation:** Complete โœ… + +## ๐Ÿ”ง Key Implementation Files + +### Core Modules +- `overseer/orchestrator.py` - Main orchestration engine +- `overseer/code_analyzer.py` - AST-based code analysis +- `overseer/doc_generator.py` - Documentation generation +- `overseer/dependency_manager.py` - Dependency scanning +- `overseer/cicd_optimizer.py` - Workflow optimization +- `overseer/issue_triager.py` - Issue management +- `overseer/automation_engine.py` - Script generation +- `overseer/monitor.py` - Repository monitoring + +### CLI & Tools +- `run_overseer.py` - Main CLI interface +- `scripts/generate_automation_scripts.py` - Automation script generator +- `scripts/generate_comprehensive_docs.py` - Documentation generator +- `scripts/generate_health_dashboard.py` - Health dashboard generator + +### Configuration & Workflows +- `overseer-config.json` - Configuration file +- `.github/workflows/repository-overseer.yml` - Automated execution workflow + +### Generated Outputs +- `overseer-results.json` - Analysis results +- `HEALTH_DASHBOARD.md` - Visual health metrics +- `README_ENHANCED.md` - Enhanced README +- `CONTRIBUTING_ENHANCED.md` - Enhanced contributing guide +- `docs/api/*.md` - API documentation +- `scripts/automation/*.sh` - Automation scripts + +## ๐ŸŽ‰ Benefits + +1. **Automated Quality Assurance** + - Continuous code quality monitoring + - Automated refactoring suggestions + - Performance optimization identification + +2. **Security First** + - Vulnerability scanning + - Dependency security checks + - Automated security issue creation + +3. **Documentation Always Up-to-Date** + - Auto-generated from code + - Framework-aware content + - Comprehensive guides + +4. **Optimized Development Workflow** + - CI/CD optimization suggestions + - Automation script generation + - Efficient issue management + +5. **Real-time Insights** + - Health dashboard + - Trend monitoring + - Actionable recommendations + +## ๐Ÿ”„ Integration with Existing Workflows + +The overseer integrates seamlessly with: +- Existing GitHub Actions workflows +- Pre-commit hooks +- Code review processes +- Issue management +- Release processes + +## ๐Ÿ“ˆ Future Enhancements + +Potential additions: +- [ ] HTML dashboard with interactive charts +- [ ] Auto-PR creation for fixes +- [ ] Webhook support for real-time monitoring +- [ ] Email/Slack notifications +- [ ] ML-based pattern recognition +- [ ] Custom rule engine +- [ ] Multi-repository support +- [ ] Integration with other CI/CD platforms + +## ๐Ÿค Contributing + +The overseer is fully open-source and extensible. Contributions welcome: +- Add new analyzers +- Improve detection algorithms +- Add support for new languages +- Enhance documentation generation +- Create new automation scripts + +## ๐Ÿ“ License + +MIT License - Same as the main repository + +--- + +**Status:** โœ… Fully Implemented and Operational + +**Last Updated:** 2026-02-17 + +**Documentation Version:** 1.0.0 diff --git a/README.md b/README.md index 73ec962..9d7d855 100644 --- a/README.md +++ b/README.md @@ -225,6 +225,71 @@ REPOSITORY OVERSEER ANALYSIS COMPLETE ============================================================ ``` +### Configuration + +The overseer can be configured using `overseer-config.json`: + +```json +{ + "code_analysis": { + "enabled": true, + "complexity_threshold": 10, + "max_function_length": 50 + }, + "dependency_management": { + "enabled": true, + "check_vulnerabilities": true, + "auto_suggest_upgrades": true + }, + "cicd": { + "enabled": true, + "optimize_workflows": true + } +} +``` + +### Automated Execution with GitHub Actions + +The overseer can run automatically on schedule or on specific events: + +```yaml +# .github/workflows/repository-overseer.yml +on: + schedule: + - cron: '0 0 * * 0' # Weekly + push: + branches: [main] + workflow_dispatch: +``` + +The workflow will: +- ๐Ÿ“Š Analyze code quality and suggest improvements +- ๐Ÿ”’ Scan dependencies for vulnerabilities +- โšก Optimize CI/CD workflows +- ๐Ÿ“ Generate documentation +- ๐Ÿท๏ธ Auto-triage issues +- ๐Ÿค– Create automation scripts +- ๐Ÿ“ˆ Monitor repository health + +Results are uploaded as artifacts and critical findings create GitHub issues automatically. + +### Advanced Usage + +**Run specific analysis:** +```bash +python run_overseer.py --only deps --verbose +``` + +**Use custom config:** +```bash +python run_overseer.py --config my-config.json +``` + +**Analyze external repository:** +```bash +python run_overseer.py --repo /path/to/project +``` + ## Chain-of-Thought Prompt Templates This repository includes comprehensive CoT templates for advanced AI reasoning: diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md new file mode 100644 index 0000000..8dd179b --- /dev/null +++ b/docs/API_REFERENCE.md @@ -0,0 +1,1596 @@ +# API Reference +*Generated on 2026-02-17* + +## Module: `overseer` + +### Class: `CICDOptimizer` + +CI/CD workflow optimizer that analyzes and improves +automated pipelines. + +#### Methods + +##### `analyze()` + +Analyze CI/CD workflows and suggest improvements. + +Returns: + Dictionary containing optimization recommendations + +### Function: `analyze(self)` + +Analyze CI/CD workflows and suggest improvements. + +Returns: + Dictionary containing optimization recommendations + +### Class: `DocumentationGenerator` + +Intelligent documentation generator that creates README, CONTRIBUTING, +and API documentation from code analysis. + +#### Methods + +##### `generate()` + +Generate all documentation + +##### `generate_readme()` + +Generate or enhance README.md file. + +Returns: + Path to generated README + +##### `generate_contributing()` + +Generate CONTRIBUTING.md file. + +Returns: + Path to generated CONTRIBUTING.md + +##### `generate_api_docs()` + +Generate API documentation from code. + +Returns: + List of paths to generated documentation files + +### Function: `generate(self)` + +Generate all documentation + +### Function: `generate_readme(self)` + +Generate or enhance README.md file. + +Returns: + Path to generated README + +### Function: `generate_contributing(self)` + +Generate CONTRIBUTING.md file. + +Returns: + Path to generated CONTRIBUTING.md + +### Function: `generate_api_docs(self)` + +Generate API documentation from code. + +Returns: + List of paths to generated documentation files + +### Class: `RepositoryMonitor` + +Real-time repository monitor that provides continuous recommendations +for improvements across quality, performance, security, and collaboration. + +#### Methods + +##### `analyze()` + +Analyze repository health and provide recommendations. + +Returns: + Dictionary containing monitoring results + +### Function: `analyze(self)` + +Analyze repository health and provide recommendations. + +Returns: + Dictionary containing monitoring results + +### Class: `CodeAnalyzer` + +Advanced code analyzer for detecting refactoring opportunities, +architectural issues, and performance problems. + +#### Methods + +##### `analyze()` + +Run comprehensive code analysis. + +Returns: + Dictionary containing analysis results + +### Function: `analyze(self)` + +Run comprehensive code analysis. + +Returns: + Dictionary containing analysis results + +### Class: `RepositoryOverseer` + +Advanced full-stack repository overseer that manages and improves repositories. + +Features: +- Deep code analysis and refactoring recommendations +- Automated documentation generation +- Smart dependency management +- CI/CD workflow optimization +- Intelligent issue triaging +- Automation script generation +- Real-time monitoring and recommendations + +#### Methods + +##### `analyze_code()` + +Conduct deep code analysis. + +Returns: + Dictionary containing analysis results + +##### `generate_documentation()` + +Auto-generate and enhance documentation. + +Returns: + Dictionary containing generated documentation info + +##### `manage_dependencies()` + +Smart dependency management and security scanning. + +Returns: + Dictionary containing dependency analysis and recommendations + +##### `optimize_cicd()` + +Design and refine CI/CD workflows. + +Returns: + Dictionary containing CI/CD optimization recommendations + +##### `triage_issues()` + +Automate issue triaging, labeling, and prioritization. + +Returns: + Dictionary containing issue triage results + +##### `generate_automation_scripts()` + +Suggest intelligent automation scripts for repetitive tasks. + +Returns: + Dictionary containing generated automation scripts + +##### `monitor_repository()` + +Monitor repository activity and provide real-time recommendations. + +Returns: + Dictionary containing monitoring results and recommendations + +##### `run_full_analysis()` + +Execute all repository oversight tasks. + +Returns: + Complete analysis results + +##### `save_results(output_path)` + +Save analysis results to file. + +Args: + output_path: Path to save results (default: repo_root/overseer-results.json) + +### Function: `analyze_code(self)` + +Conduct deep code analysis. + +Returns: + Dictionary containing analysis results + +### Function: `generate_documentation(self)` + +Auto-generate and enhance documentation. + +Returns: + Dictionary containing generated documentation info + +### Function: `manage_dependencies(self)` + +Smart dependency management and security scanning. + +Returns: + Dictionary containing dependency analysis and recommendations + +### Function: `optimize_cicd(self)` + +Design and refine CI/CD workflows. + +Returns: + Dictionary containing CI/CD optimization recommendations + +### Function: `triage_issues(self)` + +Automate issue triaging, labeling, and prioritization. + +Returns: + Dictionary containing issue triage results + +### Function: `generate_automation_scripts(self)` + +Suggest intelligent automation scripts for repetitive tasks. + +Returns: + Dictionary containing generated automation scripts + +### Function: `monitor_repository(self)` + +Monitor repository activity and provide real-time recommendations. + +Returns: + Dictionary containing monitoring results and recommendations + +### Function: `run_full_analysis(self)` + +Execute all repository oversight tasks. + +Returns: + Complete analysis results + +### Function: `save_results(self, output_path)` + +Save analysis results to file. + +Args: + output_path: Path to save results (default: repo_root/overseer-results.json) + +### Class: `IssueTriager` + +Intelligent issue triager that automatically labels and prioritizes +issues based on patterns and content analysis. + +#### Methods + +##### `process()` + +Process and triage issues. + +Returns: + Dictionary containing triage results + +##### `analyze_issue_content(title, body)` + +Analyze issue content to suggest labels and priority. + +Args: + title: Issue title + body: Issue body + +Returns: + Dictionary with suggested labels and priority + +### Function: `process(self)` + +Process and triage issues. + +Returns: + Dictionary containing triage results + +### Function: `analyze_issue_content(self, title, body)` + +Analyze issue content to suggest labels and priority. + +Args: + title: Issue title + body: Issue body + +Returns: + Dictionary with suggested labels and priority + +### Class: `AutomationEngine` + +Intelligent automation script generator for common development tasks. + +#### Methods + +##### `generate()` + +Generate automation scripts. + +Returns: + Dictionary containing generated script information + +### Function: `generate(self)` + +Generate automation scripts. + +Returns: + Dictionary containing generated script information + +### Class: `DependencyManager` + +Intelligent dependency manager that detects outdated packages, +vulnerabilities, and suggests secure upgrades. + +#### Methods + +##### `analyze()` + +Analyze dependencies for issues and recommendations. + +Returns: + Dictionary containing dependency analysis + +### Function: `analyze(self)` + +Analyze dependencies for issues and recommendations. + +Returns: + Dictionary containing dependency analysis + +## Module: `tests` + +### Class: `TestErrorHandler` + +Test suite for ErrorHandler class. + +#### Methods + +##### `setup_method()` + +Set up test fixtures. + +##### `test_initialization()` + +Test ErrorHandler initialization. + +##### `test_handle_error_basic()` + +Test basic error handling. + +##### `test_handle_error_with_severity()` + +Test error handling with severity levels. + +##### `test_handle_error_with_category()` + +Test error handling with categories. + +##### `test_custom_error_types()` + +Test custom error types. + +##### `test_error_recovery()` + +Test error recovery mechanisms. + +##### `test_severity_levels(severity)` + +Test all severity levels. + +##### `test_error_categories(category)` + +Test all error categories. + +##### `test_error_logging()` + +Test error logging functionality. + +##### `test_multiple_errors()` + +Test handling multiple errors. + +##### `test_error_with_context()` + +Test error handling with additional context. + +### Class: `TestErrorSeverity` + +Test suite for ErrorSeverity enum. + +#### Methods + +##### `test_severity_values()` + +Test that all severity levels are defined. + +### Class: `TestErrorCategory` + +Test suite for ErrorCategory enum. + +#### Methods + +##### `test_category_values()` + +Test that all error categories are defined. + +### Class: `TestCustomErrors` + +Test suite for custom error classes. + +#### Methods + +##### `test_agent_error()` + +Test AgentError exception. + +##### `test_retryable_error()` + +Test RetryableError exception. + +##### `test_configuration_error()` + +Test ConfigurationError exception. + +##### `test_validation_error()` + +Test CustomValidationError exception. + +### Class: `TestErrorIntegration` + +Integration tests for error handling. + +#### Methods + +##### `setup_method()` + +Set up test fixtures. + +##### `test_full_error_workflow()` + +Test complete error handling workflow. + +##### `test_nested_error_handling()` + +Test handling of nested errors. + +##### `test_concurrent_error_handling()` + +Test handling multiple concurrent errors. + +### Function: `setup_method(self)` + +Set up test fixtures. + +### Function: `test_initialization(self)` + +Test ErrorHandler initialization. + +### Function: `test_handle_error_basic(self)` + +Test basic error handling. + +### Function: `test_handle_error_with_severity(self)` + +Test error handling with severity levels. + +### Function: `test_handle_error_with_category(self)` + +Test error handling with categories. + +### Function: `test_custom_error_types(self)` + +Test custom error types. + +### Function: `test_error_recovery(self)` + +Test error recovery mechanisms. + +### Function: `test_severity_levels(self, severity)` + +Test all severity levels. + +### Function: `test_error_categories(self, category)` + +Test all error categories. + +### Function: `test_error_logging(self)` + +Test error logging functionality. + +### Function: `test_multiple_errors(self)` + +Test handling multiple errors. + +### Function: `test_error_with_context(self)` + +Test error handling with additional context. + +### Function: `test_severity_values(self)` + +Test that all severity levels are defined. + +### Function: `test_category_values(self)` + +Test that all error categories are defined. + +### Function: `test_agent_error(self)` + +Test AgentError exception. + +### Function: `test_retryable_error(self)` + +Test RetryableError exception. + +### Function: `test_configuration_error(self)` + +Test ConfigurationError exception. + +### Function: `test_validation_error(self)` + +Test CustomValidationError exception. + +### Function: `setup_method(self)` + +Set up test fixtures. + +### Function: `test_full_error_workflow(self)` + +Test complete error handling workflow. + +### Function: `test_nested_error_handling(self)` + +Test handling of nested errors. + +### Function: `test_concurrent_error_handling(self)` + +Test handling multiple concurrent errors. + +### Class: `ErrorSeverity` + +### Class: `ErrorCategory` + +### Class: `AgentError` + +### Class: `RetryableError` + +### Class: `ConfigurationError` + +### Class: `CustomValidationError` + +### Class: `ErrorHandler` + +#### Methods + +##### `handle_error(error, severity, category)` + +### Function: `handle_error(self, error, severity, category)` + +### Function: `test_import()` + +Test that the module can be imported. + +### Function: `test_config_generation()` + +Test that the configuration can be generated. + +### Function: `test_pygithub_available()` + +Test that PyGithub is available. + +### Function: `main()` + +Run all tests. + +### Class: `TestConfigurationUtils` + +Test suite for configuration utilities. + +#### Methods + +##### `test_load_config_valid()` + +Test loading valid configuration. + +##### `test_load_config_missing_file()` + +Test loading non-existent configuration. + +##### `test_load_config_invalid_json()` + +Test loading invalid JSON configuration. + +### Class: `TestFileOperations` + +Test suite for file operation utilities. + +#### Methods + +##### `test_read_file_exists()` + +Test reading existing file. + +##### `test_read_file_not_exists()` + +Test reading non-existent file. + +##### `test_write_file_success()` + +Test writing to file. + +##### `test_write_file_readonly_directory()` + +Test writing to read-only directory. + +### Class: `TestJSONOperations` + +Test suite for JSON operation utilities. + +#### Methods + +##### `test_save_json_valid_data()` + +Test saving valid JSON data. + +##### `test_save_json_complex_data()` + +Test saving complex JSON data. + +##### `test_load_json_valid()` + +Test loading valid JSON. + +### Class: `TestValidationUtils` + +Test suite for validation utilities. + +#### Methods + +##### `test_validate_input_valid()` + +Test validating valid input. + +##### `test_validate_input_invalid()` + +Test validating invalid input. + +##### `test_validate_input_empty()` + +Test validating empty input. + +### Class: `TestPathUtils` + +Test suite for path utilities. + +#### Methods + +##### `test_resolve_path()` + +Test path resolution. + +##### `test_get_project_root()` + +Test getting project root. + +##### `test_ensure_directory()` + +Test ensuring directory exists. + +### Class: `TestErrorHandlingInUtils` + +Test error handling in utility functions. + +#### Methods + +##### `test_graceful_failure_file_operations()` + +Test graceful failure in file operations. + +##### `test_graceful_failure_json_operations()` + +Test graceful failure in JSON operations. + +##### `test_retry_mechanism()` + +Test retry mechanism if implemented. + +### Class: `TestUtilityHelpers` + +Test suite for utility helper functions. + +#### Methods + +##### `test_sanitize_input()` + +Test input sanitization. + +##### `test_format_output()` + +Test output formatting. + +##### `test_parse_arguments()` + +Test argument parsing. + +### Class: `TestIntegrationUtils` + +Integration tests for utility functions. + +#### Methods + +##### `test_full_workflow()` + +Test complete utility workflow. + +##### `test_error_recovery()` + +Test error recovery in utility functions. + +### Function: `test_load_config_valid(self)` + +Test loading valid configuration. + +### Function: `test_load_config_missing_file(self)` + +Test loading non-existent configuration. + +### Function: `test_load_config_invalid_json(self)` + +Test loading invalid JSON configuration. + +### Function: `test_read_file_exists(self)` + +Test reading existing file. + +### Function: `test_read_file_not_exists(self)` + +Test reading non-existent file. + +### Function: `test_write_file_success(self)` + +Test writing to file. + +### Function: `test_write_file_readonly_directory(self)` + +Test writing to read-only directory. + +### Function: `test_save_json_valid_data(self)` + +Test saving valid JSON data. + +### Function: `test_save_json_complex_data(self)` + +Test saving complex JSON data. + +### Function: `test_load_json_valid(self)` + +Test loading valid JSON. + +### Function: `test_validate_input_valid(self)` + +Test validating valid input. + +### Function: `test_validate_input_invalid(self)` + +Test validating invalid input. + +### Function: `test_validate_input_empty(self)` + +Test validating empty input. + +### Function: `test_resolve_path(self)` + +Test path resolution. + +### Function: `test_get_project_root(self)` + +Test getting project root. + +### Function: `test_ensure_directory(self)` + +Test ensuring directory exists. + +### Function: `test_graceful_failure_file_operations(self)` + +Test graceful failure in file operations. + +### Function: `test_graceful_failure_json_operations(self)` + +Test graceful failure in JSON operations. + +### Function: `test_retry_mechanism(self)` + +Test retry mechanism if implemented. + +### Function: `test_sanitize_input(self)` + +Test input sanitization. + +### Function: `test_format_output(self)` + +Test output formatting. + +### Function: `test_parse_arguments(self)` + +Test argument parsing. + +### Function: `test_full_workflow(self)` + +Test complete utility workflow. + +### Function: `test_error_recovery(self)` + +Test error recovery in utility functions. + +### Class: `MockUtils` + +#### Methods + +##### `load_config(path)` + +##### `save_json(data, path)` + +##### `read_file(path)` + +##### `write_file(path, content)` + +##### `validate_input(data)` + +### Function: `load_config(path)` + +### Function: `save_json(data, path)` + +### Function: `read_file(path)` + +### Function: `write_file(path, content)` + +### Function: `validate_input(data)` + +### Function: `failing_function()` + +### Function: `temp_directory()` + +Provide a temporary directory for tests. + +### Function: `temp_file()` + +Provide a temporary file for tests. + +### Function: `sample_config()` + +Provide sample configuration for tests. + +### Function: `mock_github_api()` + +Provide a mock GitHub API client. + +### Function: `sample_json_file(temp_directory)` + +Create a sample JSON file for testing. + +### Function: `mock_logger()` + +Provide a mock logger for tests. + +### Function: `error_scenarios()` + +Provide common error scenarios for testing. + +### Function: `reset_environment()` + +Reset environment variables after each test. + +### Function: `mock_error_handler()` + +Provide a mock error handler. + +### Function: `sample_data_sets()` + +Provide sample data sets for testing. + +### Function: `mock_file_system(temp_directory)` + +Create a mock file system structure. + +### Function: `performance_metrics()` + +Provide performance metrics tracking. + +### Function: `pytest_configure(config)` + +Configure pytest. + +### Function: `pytest_collection_modifyitems(config, items)` + +Modify test collection. + +### Function: `capture_logs()` + +Capture log messages during tests. + +### Function: `retry_config()` + +Provide retry configuration for tests. + +### Function: `security_test_data()` + +Provide security test data. + +### Function: `load_test_config()` + +Provide load testing configuration. + +### Function: `log_capture(message)` + +### Class: `TestRepositoryOverseer` + +Test the main RepositoryOverseer class + +#### Methods + +##### `setUp()` + +Set up test fixtures + +##### `tearDown()` + +Clean up test fixtures + +##### `test_initialization()` + +Test overseer initialization + +##### `test_default_config()` + +Test default configuration loading + +##### `test_analyze_code()` + +Test code analysis + +##### `test_run_full_analysis()` + +Test running full analysis + +##### `test_save_results()` + +Test saving results to file + +### Class: `TestCodeAnalyzer` + +Test the CodeAnalyzer module + +#### Methods + +##### `setUp()` + +Set up test fixtures + +##### `tearDown()` + +Clean up test fixtures + +##### `test_initialization()` + +Test analyzer initialization + +##### `test_find_python_files()` + +Test finding Python files + +##### `test_detect_long_functions()` + +Test detection of long functions + +##### `test_detect_god_classes()` + +Test detection of god classes + +##### `test_quality_score_calculation()` + +Test quality score calculation + +### Class: `TestDocumentationGenerator` + +Test the DocumentationGenerator module + +#### Methods + +##### `setUp()` + +Set up test fixtures + +##### `tearDown()` + +Clean up test fixtures + +##### `test_initialization()` + +Test generator initialization + +##### `test_detect_repository_info()` + +Test repository info detection + +##### `test_generate_readme()` + +Test README generation + +##### `test_generate_contributing()` + +Test CONTRIBUTING.md generation + +### Class: `TestDependencyManager` + +Test the DependencyManager module + +#### Methods + +##### `setUp()` + +Set up test fixtures + +##### `tearDown()` + +Clean up test fixtures + +##### `test_initialization()` + +Test manager initialization + +##### `test_parse_requirements()` + +Test parsing requirements.txt + +##### `test_analyze_dependencies()` + +Test dependency analysis + +### Class: `TestCICDOptimizer` + +Test the CICDOptimizer module + +#### Methods + +##### `setUp()` + +Set up test fixtures + +##### `tearDown()` + +Clean up test fixtures + +##### `test_initialization()` + +Test optimizer initialization + +##### `test_analyze_workflows()` + +Test workflow analysis + +##### `test_check_for_caching()` + +Test cache detection + +### Class: `TestIssueTriager` + +Test the IssueTriager module + +#### Methods + +##### `setUp()` + +Set up test fixtures + +##### `tearDown()` + +Clean up test fixtures + +##### `test_initialization()` + +Test triager initialization + +##### `test_analyze_issue_content()` + +Test issue content analysis + +##### `test_security_issue_detection()` + +Test security issue detection + +### Class: `TestAutomationEngine` + +Test the AutomationEngine module + +#### Methods + +##### `setUp()` + +Set up test fixtures + +##### `tearDown()` + +Clean up test fixtures + +##### `test_initialization()` + +Test engine initialization + +##### `test_generate_scripts()` + +Test script generation + +### Class: `TestRepositoryMonitor` + +Test the RepositoryMonitor module + +#### Methods + +##### `setUp()` + +Set up test fixtures + +##### `tearDown()` + +Clean up test fixtures + +##### `test_initialization()` + +Test monitor initialization + +##### `test_analyze()` + +Test repository analysis + +##### `test_generate_recommendations()` + +Test recommendation generation + +### Function: `setUp(self)` + +Set up test fixtures + +### Function: `tearDown(self)` + +Clean up test fixtures + +### Function: `test_initialization(self)` + +Test overseer initialization + +### Function: `test_default_config(self)` + +Test default configuration loading + +### Function: `test_analyze_code(self)` + +Test code analysis + +### Function: `test_run_full_analysis(self)` + +Test running full analysis + +### Function: `test_save_results(self)` + +Test saving results to file + +### Function: `setUp(self)` + +Set up test fixtures + +### Function: `tearDown(self)` + +Clean up test fixtures + +### Function: `test_initialization(self)` + +Test analyzer initialization + +### Function: `test_find_python_files(self)` + +Test finding Python files + +### Function: `test_detect_long_functions(self)` + +Test detection of long functions + +### Function: `test_detect_god_classes(self)` + +Test detection of god classes + +### Function: `test_quality_score_calculation(self)` + +Test quality score calculation + +### Function: `setUp(self)` + +Set up test fixtures + +### Function: `tearDown(self)` + +Clean up test fixtures + +### Function: `test_initialization(self)` + +Test generator initialization + +### Function: `test_detect_repository_info(self)` + +Test repository info detection + +### Function: `test_generate_readme(self)` + +Test README generation + +### Function: `test_generate_contributing(self)` + +Test CONTRIBUTING.md generation + +### Function: `setUp(self)` + +Set up test fixtures + +### Function: `tearDown(self)` + +Clean up test fixtures + +### Function: `test_initialization(self)` + +Test manager initialization + +### Function: `test_parse_requirements(self)` + +Test parsing requirements.txt + +### Function: `test_analyze_dependencies(self)` + +Test dependency analysis + +### Function: `setUp(self)` + +Set up test fixtures + +### Function: `tearDown(self)` + +Clean up test fixtures + +### Function: `test_initialization(self)` + +Test optimizer initialization + +### Function: `test_analyze_workflows(self)` + +Test workflow analysis + +### Function: `test_check_for_caching(self)` + +Test cache detection + +### Function: `setUp(self)` + +Set up test fixtures + +### Function: `tearDown(self)` + +Clean up test fixtures + +### Function: `test_initialization(self)` + +Test triager initialization + +### Function: `test_analyze_issue_content(self)` + +Test issue content analysis + +### Function: `test_security_issue_detection(self)` + +Test security issue detection + +### Function: `setUp(self)` + +Set up test fixtures + +### Function: `tearDown(self)` + +Clean up test fixtures + +### Function: `test_initialization(self)` + +Test engine initialization + +### Function: `test_generate_scripts(self)` + +Test script generation + +### Function: `setUp(self)` + +Set up test fixtures + +### Function: `tearDown(self)` + +Clean up test fixtures + +### Function: `test_initialization(self)` + +Test monitor initialization + +### Function: `test_analyze(self)` + +Test repository analysis + +### Function: `test_generate_recommendations(self)` + +Test recommendation generation + +### Class: `TestAIAgent` + +Test suite for AI Agent main functionality. + +#### Methods + +##### `setup_method()` + +Set up test fixtures. + +##### `test_agent_initialization(mock_getenv)` + +Test agent initialization with configuration. + +##### `test_agent_handles_missing_config()` + +Test agent gracefully handles missing configuration. + +##### `test_agent_validates_inputs()` + +Test input validation in agent. + +##### `test_agent_logging(mock_print)` + +Test agent logging functionality. + +##### `test_agent_error_recovery()` + +Test agent error recovery mechanisms. + +##### `test_agent_retry_mechanism(retry_count)` + +Test retry mechanism with different counts. + +##### `test_agent_handles_api_errors()` + +Test handling of API errors. + +##### `test_agent_timeout_handling()` + +Test timeout handling in agent. + +##### `test_agent_concurrent_operations()` + +Test agent handling concurrent operations. + +##### `test_agent_resource_cleanup()` + +Test proper resource cleanup. + +### Class: `TestAgentWorkflow` + +Test suite for agent workflow operations. + +#### Methods + +##### `test_workflow_initialization()` + +Test workflow initialization. + +##### `test_workflow_execution()` + +Test workflow execution. + +##### `test_workflow_error_handling()` + +Test error handling in workflow. + +##### `test_workflow_rollback()` + +Test workflow rollback mechanism. + +##### `test_workflow_checkpointing()` + +Test workflow checkpointing. + +### Class: `TestAgentIntegration` + +Integration tests for agent operations. + +#### Methods + +##### `test_full_agent_lifecycle()` + +Test complete agent lifecycle. + +##### `test_agent_with_file_operations(mock_file, mock_json)` + +Test agent with file operations. + +##### `test_agent_state_management()` + +Test agent state management. + +##### `test_agent_performance_metrics()` + +Test collection of performance metrics. + +### Class: `TestAgentSecurity` + +Test suite for agent security features. + +#### Methods + +##### `test_secure_credential_handling()` + +Test secure handling of credentials. + +##### `test_input_sanitization()` + +Test input sanitization. + +##### `test_rate_limiting()` + +Test rate limiting functionality. + +##### `test_secure_communication()` + +Test secure communication protocols. + +### Class: `TestAgentRobustness` + +Test suite for agent robustness features. + +#### Methods + +##### `test_graceful_degradation()` + +Test graceful degradation. + +##### `test_circuit_breaker()` + +Test circuit breaker pattern. + +##### `test_health_checks()` + +Test health check functionality. + +##### `test_monitoring_alerts()` + +Test monitoring and alerting. + +##### `test_load_handling(load_level)` + +Test handling different load levels. + +### Function: `setup_method(self)` + +Set up test fixtures. + +### Function: `test_agent_initialization(self, mock_getenv)` + +Test agent initialization with configuration. + +### Function: `test_agent_handles_missing_config(self)` + +Test agent gracefully handles missing configuration. + +### Function: `test_agent_validates_inputs(self)` + +Test input validation in agent. + +### Function: `test_agent_logging(self, mock_print)` + +Test agent logging functionality. + +### Function: `test_agent_error_recovery(self)` + +Test agent error recovery mechanisms. + +### Function: `test_agent_retry_mechanism(self, retry_count)` + +Test retry mechanism with different counts. + +### Function: `test_agent_handles_api_errors(self)` + +Test handling of API errors. + +### Function: `test_agent_timeout_handling(self)` + +Test timeout handling in agent. + +### Function: `test_agent_concurrent_operations(self)` + +Test agent handling concurrent operations. + +### Function: `test_agent_resource_cleanup(self)` + +Test proper resource cleanup. + +### Function: `test_workflow_initialization(self)` + +Test workflow initialization. + +### Function: `test_workflow_execution(self)` + +Test workflow execution. + +### Function: `test_workflow_error_handling(self)` + +Test error handling in workflow. + +### Function: `test_workflow_rollback(self)` + +Test workflow rollback mechanism. + +### Function: `test_workflow_checkpointing(self)` + +Test workflow checkpointing. + +### Function: `test_full_agent_lifecycle(self)` + +Test complete agent lifecycle. + +### Function: `test_agent_with_file_operations(self, mock_file, mock_json)` + +Test agent with file operations. + +### Function: `test_agent_state_management(self)` + +Test agent state management. + +### Function: `test_agent_performance_metrics(self)` + +Test collection of performance metrics. + +### Function: `test_secure_credential_handling(self)` + +Test secure handling of credentials. + +### Function: `test_input_sanitization(self)` + +Test input sanitization. + +### Function: `test_rate_limiting(self)` + +Test rate limiting functionality. + +### Function: `test_secure_communication(self)` + +Test secure communication protocols. + +### Function: `test_graceful_degradation(self)` + +Test graceful degradation. + +### Function: `test_circuit_breaker(self)` + +Test circuit breaker pattern. + +### Function: `test_health_checks(self)` + +Test health check functionality. + +### Function: `test_monitoring_alerts(self)` + +Test monitoring and alerting. + +### Function: `test_load_handling(self, load_level)` + +Test handling different load levels. + diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md new file mode 100644 index 0000000..d34bcf7 --- /dev/null +++ b/docs/USER_GUIDE.md @@ -0,0 +1,46 @@ +# User Guide + +*For * + +## Installation + +### Python Setup + +```bash +# Clone the repository +git clone +cd + +# Create virtual environment +python -m venv .venv +source .venv/bin/activate # On Windows: .venv\Scripts\activate + +# Install dependencies +pip install -r requirements.txt +``` + +## Usage + +### Available Scripts + +- `generate_automation_scripts.py`: Description needed +- `setup-dev.sh`: Description needed + +## Testing + +Run tests with: + +```bash +pytest +``` + +## Development + +### Code Style + +This project follows standard coding conventions. + +### Continuous Integration + +This project uses GitHub Actions for CI/CD. + diff --git a/docs/api/scripts_generate_automation_scripts.md b/docs/api/scripts_generate_automation_scripts.md new file mode 100644 index 0000000..8589b07 --- /dev/null +++ b/docs/api/scripts_generate_automation_scripts.md @@ -0,0 +1,19 @@ +# generate_automation_scripts + +Automation Scripts Generator + +Generates intelligent automation scripts for common repository tasks. + +## Function: generate_scripts + +Generate all automation scripts. + +Args: + output_dir: Directory to save scripts (default: scripts/automation) + +Returns: + List of generated script paths + +## Function: main + +Main entry point diff --git a/docs/api/scripts_generate_comprehensive_docs.md b/docs/api/scripts_generate_comprehensive_docs.md new file mode 100644 index 0000000..404b8df --- /dev/null +++ b/docs/api/scripts_generate_comprehensive_docs.md @@ -0,0 +1,13 @@ +# generate_comprehensive_docs + +Comprehensive Documentation Generator + +Generates detailed, professional documentation for repositories. + +## Class: ComprehensiveDocGenerator + +Generate comprehensive documentation from code analysis + +## Function: main + +Main entry point diff --git a/docs/api/scripts_generate_health_dashboard.md b/docs/api/scripts_generate_health_dashboard.md new file mode 100644 index 0000000..c2dcee5 --- /dev/null +++ b/docs/api/scripts_generate_health_dashboard.md @@ -0,0 +1,13 @@ +# generate_health_dashboard + +Repository Health Dashboard + +Generates a visual dashboard showing repository health metrics. + +## Class: HealthDashboard + +Generate repository health dashboard + +## Function: main + +Main entry point diff --git a/overseer-config.json b/overseer-config.json new file mode 100644 index 0000000..ddd3d5a --- /dev/null +++ b/overseer-config.json @@ -0,0 +1,115 @@ +{ + "code_analysis": { + "enabled": true, + "detect_refactoring": true, + "detect_architecture": true, + "detect_performance": true, + "complexity_threshold": 10, + "min_test_coverage": 80, + "max_function_length": 50, + "max_class_length": 300, + "detect_code_smells": true, + "frameworks": ["python", "javascript", "typescript"] + }, + "documentation": { + "enabled": true, + "auto_generate_readme": true, + "auto_generate_contributing": true, + "generate_api_docs": true, + "generate_changelog": true, + "update_existing": true, + "include_badges": true, + "include_examples": true + }, + "dependency_management": { + "enabled": true, + "check_vulnerabilities": true, + "auto_suggest_upgrades": true, + "scan_frequency": "daily", + "ecosystems": ["pip", "npm", "yarn"], + "severity_threshold": "medium", + "auto_fix_vulnerabilities": false, + "create_prs": false + }, + "cicd": { + "enabled": true, + "optimize_workflows": true, + "suggest_tests": true, + "suggest_linting": true, + "suggest_deployment": true, + "suggest_caching": true, + "suggest_matrix_testing": true, + "detect_slow_jobs": true, + "max_job_duration": 600 + }, + "issue_triaging": { + "enabled": true, + "auto_label": true, + "auto_prioritize": true, + "pattern_detection": true, + "detect_duplicates": true, + "suggest_assignments": true, + "labels": { + "bug": ["bug", "error", "exception", "crash"], + "enhancement": ["feature", "enhancement", "improvement"], + "documentation": ["docs", "documentation", "readme"], + "security": ["security", "vulnerability", "cve"], + "performance": ["performance", "slow", "optimization"], + "testing": ["test", "testing", "coverage"] + } + }, + "automation": { + "enabled": true, + "code_formatting": true, + "release_tagging": true, + "environment_setup": true, + "generate_hooks": true, + "generate_scripts": true, + "platforms": ["linux", "macos", "windows"] + }, + "monitoring": { + "enabled": true, + "continuous": true, + "alert_on_issues": true, + "performance_tracking": true, + "track_metrics": [ + "code_quality", + "test_coverage", + "build_time", + "dependencies", + "security_score" + ], + "alert_thresholds": { + "quality_score": 70, + "test_coverage": 80, + "vulnerabilities": 0, + "build_time_increase": 20 + } + }, + "notifications": { + "enabled": true, + "channels": ["github_issues", "github_discussions"], + "critical_only": false, + "digest_frequency": "weekly" + }, + "exclusions": { + "paths": [ + ".git", + ".github/agents", + "__pycache__", + "*.pyc", + "node_modules", + ".venv", + "venv", + "dist", + "build", + ".tox", + "*.egg-info" + ], + "files": [ + "*.min.js", + "*.bundle.js", + "*.map" + ] + } +} diff --git a/scripts/automation/README.md b/scripts/automation/README.md new file mode 100644 index 0000000..f1c4bea --- /dev/null +++ b/scripts/automation/README.md @@ -0,0 +1,54 @@ +# Automation Scripts + +Auto-generated scripts for common repository tasks. + +## Available Scripts + +### format-python.sh + +Format Python code with black and isort + +```bash +./format-python.sh +``` + +### format-javascript.sh + +Format JavaScript/TypeScript code with prettier + +```bash +./format-javascript.sh +``` + +### create-release.sh + +Create a new release with automatic versioning + +```bash +./create-release.sh +``` + +### setup-dev-env.sh + +Setup development environment + +```bash +./setup-dev-env.sh +``` + +### run-tests.sh + +Run all tests with coverage + +```bash +./run-tests.sh +``` + +### lint-code.sh + +Run linters on codebase + +```bash +./lint-code.sh +``` + diff --git a/scripts/automation/create-release.sh b/scripts/automation/create-release.sh new file mode 100755 index 0000000..c091475 --- /dev/null +++ b/scripts/automation/create-release.sh @@ -0,0 +1,77 @@ +#!/bin/bash +# Auto-generated release tagger +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +echo -e "${GREEN}๐Ÿš€ Release Creation Script${NC}" +echo "" + +# Get current version from git tags +CURRENT_VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0") +echo "Current version: $CURRENT_VERSION" + +# Parse version numbers +VERSION=${CURRENT_VERSION#v} +IFS='.' read -ra VERSION_PARTS <<< "$VERSION" +MAJOR=${VERSION_PARTS[0]} +MINOR=${VERSION_PARTS[1]} +PATCH=${VERSION_PARTS[2]} + +# Ask for version bump type +echo "" +echo "Select version bump type:" +echo "1) Patch (v$MAJOR.$MINOR.$((PATCH+1)))" +echo "2) Minor (v$MAJOR.$((MINOR+1)).0)" +echo "3) Major (v$((MAJOR+1)).0.0)" +echo "4) Custom" +read -p "Enter choice [1-4]: " choice + +case $choice in + 1) + NEW_VERSION="v$MAJOR.$MINOR.$((PATCH+1))" + ;; + 2) + NEW_VERSION="v$MAJOR.$((MINOR+1)).0" + ;; + 3) + NEW_VERSION="v$((MAJOR+1)).0.0" + ;; + 4) + read -p "Enter custom version (e.g., v1.2.3): " NEW_VERSION + ;; + *) + echo -e "${RED}Invalid choice${NC}" + exit 1 + ;; +esac + +echo "" +echo -e "${YELLOW}Creating release: $NEW_VERSION${NC}" + +# Get commit messages since last tag +echo "" +echo "Recent changes:" +git log $CURRENT_VERSION..HEAD --oneline --decorate + +# Confirm +echo "" +read -p "Proceed with release $NEW_VERSION? [y/N]: " confirm +if [[ ! $confirm =~ ^[Yy]$ ]]; then + echo "Release cancelled" + exit 0 +fi + +# Create tag +git tag -a "$NEW_VERSION" -m "Release $NEW_VERSION" + +# Push tag +git push origin "$NEW_VERSION" + +echo "" +echo -e "${GREEN}โœ… Release $NEW_VERSION created successfully!${NC}" +echo "View release: https://github.com/$(git remote get-url origin | sed 's/.*github.com[:/]\(.*\)\.git/\1/')/releases/tag/$NEW_VERSION" diff --git a/scripts/automation/format-javascript.sh b/scripts/automation/format-javascript.sh new file mode 100755 index 0000000..6304e3f --- /dev/null +++ b/scripts/automation/format-javascript.sh @@ -0,0 +1,18 @@ +#!/bin/bash +# Auto-generated JavaScript code formatter +set -e + +echo "๐ŸŽจ Formatting JavaScript/TypeScript code..." + +# Check if prettier is installed +if ! command -v prettier &> /dev/null; then + echo "Installing prettier..." + npm install -g prettier +fi + +# Format with prettier +echo "Running prettier..." +prettier --write "**/*.{js,jsx,ts,tsx,json,css,scss,md}" \ + --ignore-path .gitignore + +echo "โœ… JavaScript code formatting complete!" diff --git a/scripts/automation/format-python.sh b/scripts/automation/format-python.sh new file mode 100755 index 0000000..bbe3529 --- /dev/null +++ b/scripts/automation/format-python.sh @@ -0,0 +1,27 @@ +#!/bin/bash +# Auto-generated Python code formatter +set -e + +echo "๐ŸŽจ Formatting Python code..." + +# Check if black is installed +if ! command -v black &> /dev/null; then + echo "Installing black..." + pip install black +fi + +# Check if isort is installed +if ! command -v isort &> /dev/null; then + echo "Installing isort..." + pip install isort +fi + +# Format with black +echo "Running black..." +black . --line-length 100 --exclude '/(\.git|\.venv|venv|__pycache__|\.tox|dist|build)/' + +# Sort imports with isort +echo "Running isort..." +isort . --profile black --skip-gitignore + +echo "โœ… Python code formatting complete!" diff --git a/scripts/automation/lint-code.sh b/scripts/automation/lint-code.sh new file mode 100755 index 0000000..ccc0ada --- /dev/null +++ b/scripts/automation/lint-code.sh @@ -0,0 +1,54 @@ +#!/bin/bash +# Auto-generated code linter +set -e + +echo "๐Ÿ” Running linters..." + +EXIT_CODE=0 + +# Python linting +if ls *.py 2>/dev/null || [ -d "scripts" ] || [ -d "src" ]; then + echo "Linting Python code..." + + # flake8 + if command -v flake8 &> /dev/null; then + echo "Running flake8..." + flake8 . --max-line-length=100 --exclude=.git,__pycache__,.venv,venv || EXIT_CODE=1 + fi + + # pylint + if command -v pylint &> /dev/null; then + echo "Running pylint..." + find . -name "*.py" -not -path "./.venv/*" -not -path "./venv/*" | xargs pylint || EXIT_CODE=1 + fi + + # mypy + if command -v mypy &> /dev/null; then + echo "Running mypy..." + mypy . --ignore-missing-imports || EXIT_CODE=1 + fi +fi + +# JavaScript linting +if [ -f "package.json" ]; then + if command -v npm &> /dev/null; then + if grep -q "eslint" package.json; then + echo "Running ESLint..." + npm run lint || EXIT_CODE=1 + fi + fi +fi + +# Security linting +if command -v bandit &> /dev/null; then + echo "Running security scan with bandit..." + bandit -r . -x ./.venv,./venv,./tests || EXIT_CODE=1 +fi + +if [ $EXIT_CODE -eq 0 ]; then + echo "โœ… All linting checks passed!" +else + echo "โŒ Some linting checks failed" +fi + +exit $EXIT_CODE diff --git a/scripts/automation/run-tests.sh b/scripts/automation/run-tests.sh new file mode 100755 index 0000000..9758193 --- /dev/null +++ b/scripts/automation/run-tests.sh @@ -0,0 +1,37 @@ +#!/bin/bash +# Auto-generated test runner +set -e + +echo "๐Ÿงช Running tests..." + +# Check if pytest is installed +if ! python -m pytest --version &> /dev/null; then + echo "Installing pytest..." + pip install pytest pytest-cov pytest-xdist +fi + +# Run tests with coverage +echo "Running pytest with coverage..." +python -m pytest \ + --verbose \ + --cov=. \ + --cov-report=html \ + --cov-report=term \ + --cov-report=xml \ + -n auto \ + tests/ + +# Check coverage threshold +COVERAGE=$(coverage report | grep TOTAL | awk '{print $4}' | sed 's/%//') +THRESHOLD=80 + +echo "" +if (( $(echo "$COVERAGE < $THRESHOLD" | bc -l) )); then + echo "โš ๏ธ Coverage ($COVERAGE%) is below threshold ($THRESHOLD%)" + exit 1 +else + echo "โœ… Coverage ($COVERAGE%) meets threshold ($THRESHOLD%)" +fi + +echo "" +echo "Coverage report: htmlcov/index.html" diff --git a/scripts/automation/setup-dev-env.sh b/scripts/automation/setup-dev-env.sh new file mode 100755 index 0000000..9da674b --- /dev/null +++ b/scripts/automation/setup-dev-env.sh @@ -0,0 +1,69 @@ +#!/bin/bash +# Auto-generated development environment setup +set -e + +echo "๐Ÿ› ๏ธ Setting up development environment..." + +# Detect OS +OS="unknown" +if [[ "$OSTYPE" == "linux-gnu"* ]]; then + OS="linux" +elif [[ "$OSTYPE" == "darwin"* ]]; then + OS="macos" +elif [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "cygwin" ]]; then + OS="windows" +fi + +echo "Detected OS: $OS" + +# Check Python +if ! command -v python3 &> /dev/null; then + echo "โŒ Python 3 not found. Please install Python 3.8+" + exit 1 +fi + +echo "โœ… Python $(python3 --version) found" + +# Create virtual environment +if [ ! -d ".venv" ]; then + echo "Creating virtual environment..." + python3 -m venv .venv +fi + +# Activate virtual environment +echo "Activating virtual environment..." +source .venv/bin/activate 2>/dev/null || source .venv/Scripts/activate 2>/dev/null + +# Upgrade pip +echo "Upgrading pip..." +pip install --upgrade pip + +# Install dependencies +if [ -f "requirements.txt" ]; then + echo "Installing Python dependencies..." + pip install -r requirements.txt +fi + +# Install pre-commit hooks if available +if [ -f ".pre-commit-config.yaml" ]; then + echo "Installing pre-commit hooks..." + pip install pre-commit + pre-commit install +fi + +# Check for Node.js dependencies +if [ -f "package.json" ]; then + if command -v npm &> /dev/null; then + echo "Installing Node.js dependencies..." + npm install + else + echo "โš ๏ธ package.json found but npm not installed" + fi +fi + +echo "" +echo "โœ… Development environment setup complete!" +echo "" +echo "To activate the environment:" +echo " source .venv/bin/activate # Linux/macOS" +echo " .venv\Scripts\activate # Windows" diff --git a/scripts/generate_automation_scripts.py b/scripts/generate_automation_scripts.py new file mode 100755 index 0000000..359f83f --- /dev/null +++ b/scripts/generate_automation_scripts.py @@ -0,0 +1,399 @@ +#!/usr/bin/env python3 +""" +Automation Scripts Generator + +Generates intelligent automation scripts for common repository tasks. +""" + +import os +import sys +from pathlib import Path +from typing import Dict, List + +# Script templates +SCRIPTS = { + 'format_python': { + 'name': 'format-python.sh', + 'description': 'Format Python code with black and isort', + 'content': '''#!/bin/bash +# Auto-generated Python code formatter +set -e + +echo "๐ŸŽจ Formatting Python code..." + +# Check if black is installed +if ! command -v black &> /dev/null; then + echo "Installing black..." + pip install black +fi + +# Check if isort is installed +if ! command -v isort &> /dev/null; then + echo "Installing isort..." + pip install isort +fi + +# Format with black +echo "Running black..." +black . --line-length 100 --exclude '/(\.git|\.venv|venv|__pycache__|\.tox|dist|build)/' + +# Sort imports with isort +echo "Running isort..." +isort . --profile black --skip-gitignore + +echo "โœ… Python code formatting complete!" +''' + }, + 'format_javascript': { + 'name': 'format-javascript.sh', + 'description': 'Format JavaScript/TypeScript code with prettier', + 'content': '''#!/bin/bash +# Auto-generated JavaScript code formatter +set -e + +echo "๐ŸŽจ Formatting JavaScript/TypeScript code..." + +# Check if prettier is installed +if ! command -v prettier &> /dev/null; then + echo "Installing prettier..." + npm install -g prettier +fi + +# Format with prettier +echo "Running prettier..." +prettier --write "**/*.{js,jsx,ts,tsx,json,css,scss,md}" \\ + --ignore-path .gitignore + +echo "โœ… JavaScript code formatting complete!" +''' + }, + 'release_tag': { + 'name': 'create-release.sh', + 'description': 'Create a new release with automatic versioning', + 'content': '''#!/bin/bash +# Auto-generated release tagger +set -e + +# Colors for output +RED='\\033[0;31m' +GREEN='\\033[0;32m' +YELLOW='\\033[1;33m' +NC='\\033[0m' # No Color + +echo -e "${GREEN}๐Ÿš€ Release Creation Script${NC}" +echo "" + +# Get current version from git tags +CURRENT_VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0") +echo "Current version: $CURRENT_VERSION" + +# Parse version numbers +VERSION=${CURRENT_VERSION#v} +IFS='.' read -ra VERSION_PARTS <<< "$VERSION" +MAJOR=${VERSION_PARTS[0]} +MINOR=${VERSION_PARTS[1]} +PATCH=${VERSION_PARTS[2]} + +# Ask for version bump type +echo "" +echo "Select version bump type:" +echo "1) Patch (v$MAJOR.$MINOR.$((PATCH+1)))" +echo "2) Minor (v$MAJOR.$((MINOR+1)).0)" +echo "3) Major (v$((MAJOR+1)).0.0)" +echo "4) Custom" +read -p "Enter choice [1-4]: " choice + +case $choice in + 1) + NEW_VERSION="v$MAJOR.$MINOR.$((PATCH+1))" + ;; + 2) + NEW_VERSION="v$MAJOR.$((MINOR+1)).0" + ;; + 3) + NEW_VERSION="v$((MAJOR+1)).0.0" + ;; + 4) + read -p "Enter custom version (e.g., v1.2.3): " NEW_VERSION + ;; + *) + echo -e "${RED}Invalid choice${NC}" + exit 1 + ;; +esac + +echo "" +echo -e "${YELLOW}Creating release: $NEW_VERSION${NC}" + +# Get commit messages since last tag +echo "" +echo "Recent changes:" +git log $CURRENT_VERSION..HEAD --oneline --decorate + +# Confirm +echo "" +read -p "Proceed with release $NEW_VERSION? [y/N]: " confirm +if [[ ! $confirm =~ ^[Yy]$ ]]; then + echo "Release cancelled" + exit 0 +fi + +# Create tag +git tag -a "$NEW_VERSION" -m "Release $NEW_VERSION" + +# Push tag +git push origin "$NEW_VERSION" + +echo "" +echo -e "${GREEN}โœ… Release $NEW_VERSION created successfully!${NC}" +echo "View release: https://github.com/$(git remote get-url origin | sed 's/.*github.com[:/]\\(.*\\)\\.git/\\1/')/releases/tag/$NEW_VERSION" +''' + }, + 'setup_dev_env': { + 'name': 'setup-dev-env.sh', + 'description': 'Setup development environment', + 'content': '''#!/bin/bash +# Auto-generated development environment setup +set -e + +echo "๐Ÿ› ๏ธ Setting up development environment..." + +# Detect OS +OS="unknown" +if [[ "$OSTYPE" == "linux-gnu"* ]]; then + OS="linux" +elif [[ "$OSTYPE" == "darwin"* ]]; then + OS="macos" +elif [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "cygwin" ]]; then + OS="windows" +fi + +echo "Detected OS: $OS" + +# Check Python +if ! command -v python3 &> /dev/null; then + echo "โŒ Python 3 not found. Please install Python 3.8+" + exit 1 +fi + +echo "โœ… Python $(python3 --version) found" + +# Create virtual environment +if [ ! -d ".venv" ]; then + echo "Creating virtual environment..." + python3 -m venv .venv +fi + +# Activate virtual environment +echo "Activating virtual environment..." +source .venv/bin/activate 2>/dev/null || source .venv/Scripts/activate 2>/dev/null + +# Upgrade pip +echo "Upgrading pip..." +pip install --upgrade pip + +# Install dependencies +if [ -f "requirements.txt" ]; then + echo "Installing Python dependencies..." + pip install -r requirements.txt +fi + +# Install pre-commit hooks if available +if [ -f ".pre-commit-config.yaml" ]; then + echo "Installing pre-commit hooks..." + pip install pre-commit + pre-commit install +fi + +# Check for Node.js dependencies +if [ -f "package.json" ]; then + if command -v npm &> /dev/null; then + echo "Installing Node.js dependencies..." + npm install + else + echo "โš ๏ธ package.json found but npm not installed" + fi +fi + +echo "" +echo "โœ… Development environment setup complete!" +echo "" +echo "To activate the environment:" +echo " source .venv/bin/activate # Linux/macOS" +echo " .venv\\Scripts\\activate # Windows" +''' + }, + 'run_tests': { + 'name': 'run-tests.sh', + 'description': 'Run all tests with coverage', + 'content': '''#!/bin/bash +# Auto-generated test runner +set -e + +echo "๐Ÿงช Running tests..." + +# Check if pytest is installed +if ! python -m pytest --version &> /dev/null; then + echo "Installing pytest..." + pip install pytest pytest-cov pytest-xdist +fi + +# Run tests with coverage +echo "Running pytest with coverage..." +python -m pytest \\ + --verbose \\ + --cov=. \\ + --cov-report=html \\ + --cov-report=term \\ + --cov-report=xml \\ + -n auto \\ + tests/ + +# Check coverage threshold +COVERAGE=$(coverage report | grep TOTAL | awk '{print $4}' | sed 's/%//') +THRESHOLD=80 + +echo "" +if (( $(echo "$COVERAGE < $THRESHOLD" | bc -l) )); then + echo "โš ๏ธ Coverage ($COVERAGE%) is below threshold ($THRESHOLD%)" + exit 1 +else + echo "โœ… Coverage ($COVERAGE%) meets threshold ($THRESHOLD%)" +fi + +echo "" +echo "Coverage report: htmlcov/index.html" +''' + }, + 'lint_code': { + 'name': 'lint-code.sh', + 'description': 'Run linters on codebase', + 'content': '''#!/bin/bash +# Auto-generated code linter +set -e + +echo "๐Ÿ” Running linters..." + +EXIT_CODE=0 + +# Python linting +if ls *.py 2>/dev/null || [ -d "scripts" ] || [ -d "src" ]; then + echo "Linting Python code..." + + # flake8 + if command -v flake8 &> /dev/null; then + echo "Running flake8..." + flake8 . --max-line-length=100 --exclude=.git,__pycache__,.venv,venv || EXIT_CODE=1 + fi + + # pylint + if command -v pylint &> /dev/null; then + echo "Running pylint..." + find . -name "*.py" -not -path "./.venv/*" -not -path "./venv/*" | xargs pylint || EXIT_CODE=1 + fi + + # mypy + if command -v mypy &> /dev/null; then + echo "Running mypy..." + mypy . --ignore-missing-imports || EXIT_CODE=1 + fi +fi + +# JavaScript linting +if [ -f "package.json" ]; then + if command -v npm &> /dev/null; then + if grep -q "eslint" package.json; then + echo "Running ESLint..." + npm run lint || EXIT_CODE=1 + fi + fi +fi + +# Security linting +if command -v bandit &> /dev/null; then + echo "Running security scan with bandit..." + bandit -r . -x ./.venv,./venv,./tests || EXIT_CODE=1 +fi + +if [ $EXIT_CODE -eq 0 ]; then + echo "โœ… All linting checks passed!" +else + echo "โŒ Some linting checks failed" +fi + +exit $EXIT_CODE +''' + } +} + + +def generate_scripts(output_dir: Path = None) -> List[Path]: + """ + Generate all automation scripts. + + Args: + output_dir: Directory to save scripts (default: scripts/automation) + + Returns: + List of generated script paths + """ + if output_dir is None: + output_dir = Path('scripts') / 'automation' + + output_dir.mkdir(parents=True, exist_ok=True) + generated = [] + + print(f"๐Ÿ“ Generating automation scripts in {output_dir}...") + print() + + for script_id, script_data in SCRIPTS.items(): + script_path = output_dir / script_data['name'] + + # Write script + with open(script_path, 'w') as f: + f.write(script_data['content']) + + # Make executable + script_path.chmod(0o755) + + generated.append(script_path) + print(f"โœ… Generated: {script_data['name']}") + print(f" Description: {script_data['description']}") + + print() + print(f"๐ŸŽ‰ Generated {len(generated)} automation scripts!") + + # Create README + readme_path = output_dir / 'README.md' + with open(readme_path, 'w') as f: + f.write("# Automation Scripts\n\n") + f.write("Auto-generated scripts for common repository tasks.\n\n") + f.write("## Available Scripts\n\n") + + for script_id, script_data in SCRIPTS.items(): + f.write(f"### {script_data['name']}\n\n") + f.write(f"{script_data['description']}\n\n") + f.write(f"```bash\n") + f.write(f"./{script_data['name']}\n") + f.write(f"```\n\n") + + print(f"๐Ÿ“ Generated: {readme_path}") + + return generated + + +def main(): + """Main entry point""" + output_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else None + generated = generate_scripts(output_dir) + + print() + print("๐Ÿ’ก Usage:") + print(" Make scripts executable: chmod +x scripts/automation/*.sh") + print(" Run a script: ./scripts/automation/format-python.sh") + + return 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/scripts/generate_comprehensive_docs.py b/scripts/generate_comprehensive_docs.py new file mode 100644 index 0000000..7ef0af8 --- /dev/null +++ b/scripts/generate_comprehensive_docs.py @@ -0,0 +1,338 @@ +#!/usr/bin/env python3 +""" +Comprehensive Documentation Generator + +Generates detailed, professional documentation for repositories. +""" + +import os +import ast +import json +from pathlib import Path +from typing import Dict, List, Optional +from datetime import datetime + + +class ComprehensiveDocGenerator: + """Generate comprehensive documentation from code analysis""" + + def __init__(self, repo_path: Path): + self.repo_path = Path(repo_path) + self.project_info = self._analyze_project() + + def _analyze_project(self) -> Dict: + """Analyze project structure and metadata""" + info = { + 'name': self.repo_path.name, + 'has_python': (self.repo_path / 'requirements.txt').exists() or + (self.repo_path / 'setup.py').exists() or + (self.repo_path / 'pyproject.toml').exists(), + 'has_javascript': (self.repo_path / 'package.json').exists(), + 'has_docker': (self.repo_path / 'Dockerfile').exists(), + 'has_tests': (self.repo_path / 'tests').exists() or + (self.repo_path / 'test').exists(), + 'has_ci': (self.repo_path / '.github' / 'workflows').exists(), + 'modules': self._find_modules(), + 'scripts': self._find_scripts() + } + return info + + def _find_modules(self) -> List[str]: + """Find Python modules in the project""" + modules = [] + for item in self.repo_path.iterdir(): + if item.is_dir() and (item / '__init__.py').exists(): + modules.append(item.name) + return modules + + def _find_scripts(self) -> List[str]: + """Find executable scripts""" + scripts = [] + scripts_dir = self.repo_path / 'scripts' + if scripts_dir.exists(): + for item in scripts_dir.iterdir(): + if item.is_file() and os.access(item, os.X_OK): + scripts.append(item.name) + return scripts + + def generate_api_reference(self) -> str: + """Generate API reference documentation""" + content = [] + content.append("# API Reference\n") + content.append(f"*Generated on {datetime.now().strftime('%Y-%m-%d')}*\n\n") + + # Document modules + for module in self.project_info['modules']: + module_path = self.repo_path / module + content.append(f"## Module: `{module}`\n\n") + + # Find Python files in module + for py_file in module_path.rglob('*.py'): + if py_file.name == '__init__.py': + continue + + try: + with open(py_file) as f: + tree = ast.parse(f.read()) + + # Document classes + for node in ast.walk(tree): + if isinstance(node, ast.ClassDef): + content.append(f"### Class: `{node.name}`\n\n") + docstring = ast.get_docstring(node) + if docstring: + content.append(f"{docstring}\n\n") + + # Document methods + methods = [n for n in node.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))] + if methods: + content.append("#### Methods\n\n") + for method in methods: + if method.name.startswith('_'): + continue # Skip private methods + + args = [a.arg for a in method.args.args if a.arg != 'self'] + content.append(f"##### `{method.name}({', '.join(args)})`\n\n") + + method_doc = ast.get_docstring(method) + if method_doc: + content.append(f"{method_doc}\n\n") + + # Document module-level functions + elif isinstance(node, ast.FunctionDef): + if not node.name.startswith('_'): + args = [a.arg for a in node.args.args] + content.append(f"### Function: `{node.name}({', '.join(args)})`\n\n") + + func_doc = ast.get_docstring(node) + if func_doc: + content.append(f"{func_doc}\n\n") + + except Exception as e: + print(f"Warning: Could not parse {py_file}: {e}") + + return ''.join(content) + + def generate_user_guide(self) -> str: + """Generate user guide""" + content = [] + content.append("# User Guide\n\n") + content.append(f"*For {self.project_info['name']}*\n\n") + + # Installation + content.append("## Installation\n\n") + + if self.project_info['has_python']: + content.append("### Python Setup\n\n") + content.append("```bash\n") + content.append("# Clone the repository\n") + content.append(f"git clone \n") + content.append(f"cd {self.project_info['name']}\n\n") + content.append("# Create virtual environment\n") + content.append("python -m venv .venv\n") + content.append("source .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n\n") + content.append("# Install dependencies\n") + content.append("pip install -r requirements.txt\n") + content.append("```\n\n") + + if self.project_info['has_javascript']: + content.append("### JavaScript Setup\n\n") + content.append("```bash\n") + content.append("# Install dependencies\n") + content.append("npm install\n") + content.append("```\n\n") + + # Usage + content.append("## Usage\n\n") + + # Scripts + if self.project_info['scripts']: + content.append("### Available Scripts\n\n") + for script in self.project_info['scripts']: + content.append(f"- `{script}`: Description needed\n") + content.append("\n") + + # Testing + if self.project_info['has_tests']: + content.append("## Testing\n\n") + content.append("Run tests with:\n\n") + content.append("```bash\n") + if self.project_info['has_python']: + content.append("pytest\n") + content.append("```\n\n") + + # Development + content.append("## Development\n\n") + content.append("### Code Style\n\n") + content.append("This project follows standard coding conventions.\n\n") + + if self.project_info['has_ci']: + content.append("### Continuous Integration\n\n") + content.append("This project uses GitHub Actions for CI/CD.\n\n") + + return ''.join(content) + + def generate_architecture_doc(self) -> str: + """Generate architecture documentation""" + content = [] + content.append("# Architecture\n\n") + content.append(f"*System architecture for {self.project_info['name']}*\n\n") + + content.append("## Overview\n\n") + content.append("This document describes the high-level architecture of the system.\n\n") + + # Components + content.append("## Components\n\n") + + for module in self.project_info['modules']: + content.append(f"### {module.title()}\n\n") + + # Try to get module docstring + init_file = self.repo_path / module / '__init__.py' + if init_file.exists(): + try: + with open(init_file) as f: + tree = ast.parse(f.read()) + docstring = ast.get_docstring(tree) + if docstring: + content.append(f"{docstring}\n\n") + except: + pass + + # Data Flow + content.append("## Data Flow\n\n") + content.append("Describe how data flows through the system.\n\n") + + # Dependencies + content.append("## External Dependencies\n\n") + + if self.project_info['has_python'] and (self.repo_path / 'requirements.txt').exists(): + content.append("### Python Dependencies\n\n") + content.append("See `requirements.txt` for the full list.\n\n") + + if self.project_info['has_javascript'] and (self.repo_path / 'package.json').exists(): + content.append("### JavaScript Dependencies\n\n") + content.append("See `package.json` for the full list.\n\n") + + return ''.join(content) + + def generate_contributing_guide(self) -> str: + """Generate contributing guide""" + content = [] + content.append("# Contributing Guide\n\n") + content.append(f"Thank you for your interest in contributing to {self.project_info['name']}!\n\n") + + content.append("## Getting Started\n\n") + content.append("1. Fork the repository\n") + content.append("2. Clone your fork\n") + content.append("3. Create a new branch for your feature\n") + content.append("4. Make your changes\n") + content.append("5. Run tests\n") + content.append("6. Submit a pull request\n\n") + + content.append("## Development Setup\n\n") + content.append("See the [User Guide](USER_GUIDE.md) for setup instructions.\n\n") + + content.append("## Code Style\n\n") + + if self.project_info['has_python']: + content.append("### Python\n\n") + content.append("- Follow PEP 8 style guide\n") + content.append("- Use type hints where appropriate\n") + content.append("- Write docstrings for all public functions and classes\n") + content.append("- Maximum line length: 100 characters\n\n") + + if self.project_info['has_javascript']: + content.append("### JavaScript\n\n") + content.append("- Follow ESLint configuration\n") + content.append("- Use modern ES6+ syntax\n") + content.append("- Write JSDoc comments for functions\n\n") + + content.append("## Testing\n\n") + content.append("All new features must include tests.\n\n") + + if self.project_info['has_tests']: + content.append("Run tests with:\n\n") + content.append("```bash\n") + if self.project_info['has_python']: + content.append("pytest\n") + content.append("```\n\n") + + content.append("## Pull Request Process\n\n") + content.append("1. Update documentation as needed\n") + content.append("2. Add tests for new functionality\n") + content.append("3. Ensure all tests pass\n") + content.append("4. Update CHANGELOG.md\n") + content.append("5. Request review from maintainers\n\n") + + content.append("## Code of Conduct\n\n") + content.append("Please be respectful and constructive in all interactions.\n\n") + + return ''.join(content) + + def generate_all_docs(self, output_dir: Path = None) -> Dict[str, Path]: + """Generate all documentation""" + if output_dir is None: + output_dir = self.repo_path / 'docs' + + output_dir = Path(output_dir) + output_dir.mkdir(parents=True, exist_ok=True) + + generated = {} + + # API Reference + api_ref = self.generate_api_reference() + api_path = output_dir / 'API_REFERENCE.md' + with open(api_path, 'w') as f: + f.write(api_ref) + generated['api_reference'] = api_path + print(f"โœ… Generated: {api_path}") + + # User Guide + user_guide = self.generate_user_guide() + guide_path = output_dir / 'USER_GUIDE.md' + with open(guide_path, 'w') as f: + f.write(user_guide) + generated['user_guide'] = guide_path + print(f"โœ… Generated: {guide_path}") + + # Architecture + arch = self.generate_architecture_doc() + arch_path = output_dir / 'ARCHITECTURE.md' + with open(arch_path, 'w') as f: + f.write(arch) + generated['architecture'] = arch_path + print(f"โœ… Generated: {arch_path}") + + # Contributing + contrib = self.generate_contributing_guide() + contrib_path = self.repo_path / 'CONTRIBUTING_GENERATED.md' + with open(contrib_path, 'w') as f: + f.write(contrib) + generated['contributing'] = contrib_path + print(f"โœ… Generated: {contrib_path}") + + return generated + + +def main(): + """Main entry point""" + import sys + + repo_path = Path(sys.argv[1]) if len(sys.argv) > 1 else Path('.') + + print(f"๐Ÿ“š Generating comprehensive documentation for: {repo_path}") + print() + + generator = ComprehensiveDocGenerator(repo_path) + generated = generator.generate_all_docs() + + print() + print(f"๐ŸŽ‰ Generated {len(generated)} documentation files!") + + return 0 + + +if __name__ == '__main__': + import sys + sys.exit(main()) diff --git a/scripts/generate_health_dashboard.py b/scripts/generate_health_dashboard.py new file mode 100644 index 0000000..b3cca77 --- /dev/null +++ b/scripts/generate_health_dashboard.py @@ -0,0 +1,282 @@ +#!/usr/bin/env python3 +""" +Repository Health Dashboard + +Generates a visual dashboard showing repository health metrics. +""" + +import json +import os +from pathlib import Path +from datetime import datetime +from typing import Dict, List, Any + + +class HealthDashboard: + """Generate repository health dashboard""" + + def __init__(self, results_file: Path = None): + if results_file is None: + results_file = Path('overseer-results.json') + + self.results_file = Path(results_file) + self.results = self._load_results() + + def _load_results(self) -> Dict: + """Load overseer results""" + if not self.results_file.exists(): + return {} + + with open(self.results_file) as f: + return json.load(f) + + def _get_health_score(self) -> int: + """Calculate overall health score (0-100)""" + score = 100 + + analyses = self.results.get('analyses', {}) + + # Code quality (40% weight) + code = analyses.get('code', {}) + quality_score = code.get('code_quality_score', code.get('quality_score', 100)) + score -= (100 - quality_score) * 0.4 + + # Dependencies (30% weight) + deps = analyses.get('dependencies', {}) + vuln_count = len(deps.get('vulnerable_packages', [])) + score -= min(vuln_count * 10, 30) # Cap at 30 points + + # CI/CD (15% weight) + cicd = analyses.get('cicd', {}) + cicd_issues = len(cicd.get('workflow_optimizations', [])) + score -= min(cicd_issues * 2, 15) # Cap at 15 points + + # Documentation (15% weight) + docs = analyses.get('documentation', {}) + if not docs.get('readme_updated', True): + score -= 10 + if not docs.get('contributing_generated', True): + score -= 5 + + return max(0, int(score)) + + def _get_status_emoji(self, score: int) -> str: + """Get emoji for score""" + if score >= 90: + return "๐ŸŸข" + elif score >= 70: + return "๐ŸŸก" + elif score >= 50: + return "๐ŸŸ " + else: + return "๐Ÿ”ด" + + def _get_priority_counts(self) -> Dict[str, int]: + """Get counts of issues by priority""" + counts = {'critical': 0, 'high': 0, 'medium': 0, 'low': 0} + + recs = self.results.get('recommendations', []) + for rec in recs: + priority = rec.get('priority', 'low') + counts[priority] = counts.get(priority, 0) + 1 + + return counts + + def generate_markdown_dashboard(self) -> str: + """Generate markdown dashboard""" + content = [] + + # Header + content.append("# ๐Ÿ“Š Repository Health Dashboard\n\n") + timestamp = self.results.get('timestamp', datetime.now().isoformat()) + content.append(f"*Last updated: {timestamp}*\n\n") + content.append("---\n\n") + + # Overall Health Score + health_score = self._get_health_score() + status_emoji = self._get_status_emoji(health_score) + + content.append("## Overall Health\n\n") + content.append(f"### {status_emoji} Score: {health_score}/100\n\n") + + # Progress bar + filled = int(health_score / 5) + empty = 20 - filled + progress_bar = "โ–ˆ" * filled + "โ–‘" * empty + content.append(f"```\n{progress_bar} {health_score}%\n```\n\n") + + # Status interpretation + if health_score >= 90: + content.append("**Status:** Excellent - Repository is in great shape!\n\n") + elif health_score >= 70: + content.append("**Status:** Good - Minor improvements recommended\n\n") + elif health_score >= 50: + content.append("**Status:** Fair - Some issues need attention\n\n") + else: + content.append("**Status:** Poor - Immediate action required\n\n") + + content.append("---\n\n") + + # Metrics + analyses = self.results.get('analyses', {}) + + # Code Quality + code = analyses.get('code', {}) + if code: + content.append("## ๐Ÿ’ป Code Quality\n\n") + + quality_score = code.get('code_quality_score', code.get('quality_score', 0)) + refactoring = len(code.get('refactoring_opportunities', [])) + architecture = len(code.get('architectural_improvements', [])) + performance = len(code.get('performance_optimizations', [])) + + content.append(f"- **Quality Score:** {quality_score}/100\n") + content.append(f"- **Refactoring Opportunities:** {refactoring}\n") + content.append(f"- **Architectural Improvements:** {architecture}\n") + content.append(f"- **Performance Issues:** {performance}\n\n") + + # Dependencies + deps = analyses.get('dependencies', {}) + if deps: + content.append("## ๐Ÿ“ฆ Dependencies\n\n") + + vulnerable = len(deps.get('vulnerable_packages', [])) + outdated = len(deps.get('outdated_packages', [])) + recommendations = len(deps.get('upgrade_recommendations', [])) + + if vulnerable > 0: + content.append(f"- โš ๏ธ **Vulnerable Packages:** {vulnerable} (CRITICAL)\n") + else: + content.append("- โœ… **Vulnerable Packages:** 0\n") + + content.append(f"- **Outdated Packages:** {outdated}\n") + content.append(f"- **Upgrade Recommendations:** {recommendations}\n\n") + + # CI/CD + cicd = analyses.get('cicd', {}) + if cicd: + content.append("## โš™๏ธ CI/CD\n\n") + + optimizations = len(cicd.get('workflow_optimizations', [])) + test_improvements = len(cicd.get('test_improvements', [])) + linting = len(cicd.get('linting_suggestions', [])) + + content.append(f"- **Workflow Optimizations:** {optimizations}\n") + content.append(f"- **Test Improvements:** {test_improvements}\n") + content.append(f"- **Linting Suggestions:** {linting}\n\n") + + # Documentation + docs = analyses.get('documentation', {}) + if docs: + content.append("## ๐Ÿ“š Documentation\n\n") + + readme = "โœ…" if docs.get('readme_updated', False) else "โŒ" + contrib = "โœ…" if docs.get('contributing_generated', False) else "โŒ" + api_docs = "โœ…" if docs.get('api_docs_generated', False) else "โŒ" + + content.append(f"- **README:** {readme}\n") + content.append(f"- **Contributing Guide:** {contrib}\n") + content.append(f"- **API Documentation:** {api_docs}\n\n") + + # Issue Triage + issues = analyses.get('issue_triage', {}) + if issues: + content.append("## ๐Ÿท๏ธ Issue Management\n\n") + + processed = issues.get('issues_processed', 0) + labeled = issues.get('labels_applied', 0) + prioritized = issues.get('priorities_assigned', 0) + + content.append(f"- **Issues Processed:** {processed}\n") + content.append(f"- **Labels Applied:** {labeled}\n") + content.append(f"- **Priorities Assigned:** {prioritized}\n\n") + + # Monitoring + monitoring = analyses.get('monitoring', {}) + if monitoring: + content.append("## ๐Ÿ“ˆ Monitoring\n\n") + + recs = monitoring.get('recommendations', []) + content.append(f"- **Total Recommendations:** {len(recs)}\n") + + # Count by priority + priority_counts = {'high': 0, 'medium': 0, 'low': 0} + for rec in recs: + priority = rec.get('priority', 'low') + priority_counts[priority] = priority_counts.get(priority, 0) + 1 + + content.append(f"- **High Priority:** {priority_counts['high']}\n") + content.append(f"- **Medium Priority:** {priority_counts['medium']}\n") + content.append(f"- **Low Priority:** {priority_counts['low']}\n\n") + + # Top Recommendations + recs = self.results.get('recommendations', []) + if recs: + content.append("---\n\n") + content.append("## ๐Ÿ’ก Top Recommendations\n\n") + + # Group by priority + critical = [r for r in recs if r.get('priority') == 'critical'] + high = [r for r in recs if r.get('priority') == 'high'] + + if critical: + content.append("### ๐Ÿ”ด Critical\n\n") + for rec in critical[:5]: + content.append(f"- **[{rec.get('category', 'general')}]** {rec.get('message', '')}\n") + content.append("\n") + + if high: + content.append("### ๐ŸŸก High Priority\n\n") + for rec in high[:5]: + content.append(f"- **[{rec.get('category', 'general')}]** {rec.get('message', '')}\n") + content.append("\n") + + # Footer + content.append("---\n\n") + content.append("*Generated by Repository Overseer*\n") + + return ''.join(content) + + def generate_html_dashboard(self) -> str: + """Generate HTML dashboard (future enhancement)""" + # TODO: Implement HTML dashboard with charts + pass + + def save_dashboard(self, output_file: Path = None): + """Save dashboard to file""" + if output_file is None: + output_file = Path('HEALTH_DASHBOARD.md') + + markdown = self.generate_markdown_dashboard() + + with open(output_file, 'w') as f: + f.write(markdown) + + print(f"โœ… Dashboard saved to: {output_file}") + return output_file + + +def main(): + """Main entry point""" + import sys + + results_file = Path(sys.argv[1]) if len(sys.argv) > 1 else None + + print("๐Ÿ“Š Generating Repository Health Dashboard...") + print() + + dashboard = HealthDashboard(results_file) + output = dashboard.save_dashboard() + + # Print to console + print() + print("=" * 60) + print(dashboard.generate_markdown_dashboard()) + print("=" * 60) + + return 0 + + +if __name__ == '__main__': + import sys + sys.exit(main())