🧠 Core AI Analysis Modules

The intelligence at the heart of gh.gg is powered by a suite of AI analysis modules, primarily utilizing Google Gemini AI. These modules, located in the src/lib/ai/ directory, are responsible for processing raw GitHub data and transforming it into actionable insights, visualizations, and comprehensive documentation. They directly implement the AI Processing described in the Architecture Overview.

Each module is designed for a specific analytical task, taking structured inputs and generating structured outputs along with detailed markdown reports and token usage statistics.

🤖 AI Modules Overview

`ai-slop.ts`

Purpose: To detect and report on "code slop" – low-quality code patterns often found in AI-generated or poorly written human code.
Type of Analysis: Identifies repetitive code, unnecessary complexity, valueless boilerplate, bad abstractions, useless tests, and loose TypeScript types.
Key Inputs: A list of repository files (with path and content), and the repoName.
Key Outputs: AISlopData (structured metrics, overall score, AI-generated percentage, detected patterns) and usage (token count).
Gemini Usage: Generates a detailed report and assigns scores based on code analysis, identifying specific slop patterns and suggesting fixes.

`battle-analysis.ts`

Purpose: To act as an AI judge for developer arena battles, comparing two developers' profiles and determining a winner based on specified criteria.
Type of Analysis: Comparative assessment of two DeveloperProfile objects across various criteria (e.g., code quality, innovation, architecture). It also calculates ELO rating changes.
Key Inputs: challengerProfile, opponentProfile, their respective usernames, and an array of criteria for the battle.
Key Outputs: BattleAnalysisResult (winner, reason, score breakdown, highlights, recommendations) and usage.
Gemini Usage: Evaluates the strengths and weaknesses of each developer's profile against the battle criteria, assigning scores and providing a narrative judgment.

`commit-analysis.ts`

Purpose: To provide an in-depth AI-powered review of individual Git commits.
Type of Analysis: Assesses commit message quality, code changes, AI generation likelihood, and adherence to best practices.
Key Inputs: commitMessage, commitSha, author details, changedFiles (including patch content), repoName, and branch.
Key Outputs: CommitAnalysisResult (overall score, slop ranking, breakdown for message/code quality/AI likelihood/best practices, and actionable fixes), a formatted markdown report, and usage.
Gemini Usage: Examines commit metadata and diffs to generate a comprehensive quality report, including a "slop ranking" and suggestions for improvement.

`developer-profile.ts`

Purpose: To create a comprehensive AI-powered profile for a GitHub developer.
Type of Analysis: Synthesizes information from multiple public repositories to assess skills, development style, and identify top projects. It can optionally generate repository scorecards as part of the process.
Key Inputs: username, RepoSummary for their repositories, optional repoFiles for deeper code analysis, and userId for linking generated scorecards.
Key Outputs: DeveloperProfile (summary, skill assessment, tech stack, development style, top repositories, suggestions) and usage.
Gemini Usage: Acts as a "Senior Engineering Manager" to compile a professional profile, using repository metadata and potentially detailed code analysis (scorecard.ts module output) to provide scored insights and improvement suggestions. It also handles finding and storing developer emails from commit history.

`diagram.ts`

Purpose: To generate various types of Mermaid diagrams directly from codebase files.
Type of Analysis: Interprets code structure, dependencies, and logic to visualize it as a flowchart, sequence diagram, class diagram, state diagram, pie chart, or Gantt chart.
Key Inputs: A list of files (with path and content), repoName, diagramType, options (e.g., layout), and optional previousResult/lastError for retry attempts.
Key Outputs: diagramCode (Mermaid syntax) and usage.
Gemini Usage: Acts as an "expert software architect and diagram creator," converting natural language understanding of the codebase into valid Mermaid markdown. It is capable of iteratively fixing diagram syntax based on previous errors.

`documentation.ts`

Purpose: To generate comprehensive, professional wiki documentation for an entire codebase.
Type of Analysis: Extracts high-level overviews, installation guides, architectural patterns, component details, API references, best practices, troubleshooting, examples, and contribution guidelines. It can handle large repositories via chunking.
Key Inputs: repoName, repoDescription, primaryLanguage, a list of files with content, packageJson, and readme content. Supports useChunking and tokensPerChunk for scaling.
Key Outputs: DocumentationResult (structured JSON for all wiki sections), a full markdown string, and usage.
Gemini Usage: Acts as an "expert technical writer and software architect," processing the codebase (potentially in chunks) to synthesize a complete and coherent documentation set, adhering to a predefined structure.

`issue-analysis.ts`

Purpose: To provide intelligent triage and analysis for GitHub issues.
Type of Analysis: Evaluates issue clarity, actionability, completeness, likelihood of being AI-generated, and duplication risk.
Key Inputs: issueTitle, issueBody, issueNumber, author details, labels, repoName, and optional repoDescription.
Key Outputs: IssueAnalysisResult (overall score, slop ranking, breakdown for clarity/actionability/completeness/AI likelihood/duplicate risk, suggested labels, priority, and improvements), a formatted markdown report, and usage.
Gemini Usage: Functions as an "expert issue triager," providing a critical assessment of the issue's quality, suggesting labels, and offering ways to improve it for better developer experience.

`pr-analysis.ts`

Purpose: To perform automated AI-powered code reviews for pull requests.
Type of Analysis: Assesses code quality, security, performance, and maintainability of code changes in a pull request.
Key Inputs: prTitle, prDescription, changedFiles (including patch content), repoName, baseBranch, and headBranch.
Key Outputs: PRAnalysisResult (overall score, summary, breakdown for code quality/security/performance/maintainability, and key recommendations), a formatted markdown comment, and usage.
Gemini Usage: Operates as an "expert code reviewer," scrutinizing the diffs and PR metadata to identify potential issues and suggest actionable improvements across various quality dimensions.

`scorecard.ts`

Purpose: To generate a comprehensive, scorecard-style analysis of a GitHub repository.
Type of Analysis: Evaluates the overall health, quality, and potential business impact of a codebase across various metrics.
Key Inputs: A list of files (with path and content) and the repoName.
Key Outputs: ScorecardData (structured metrics, overall score), a formatted markdown report focusing on business impact, and usage.
Gemini Usage: Functions as an "expert codebase analyst," providing a high-level overview of the repository's status, breaking down quality into key metrics, and translating technical findings into business-relevant insights.

`wiki-generator-streaming.ts`

Purpose: An enhanced version of the wiki-generator.ts module, designed to handle large repositories by processing files in chunks and providing real-time progress updates.
Type of Analysis: Similar to documentation.ts, it plans and generates comprehensive wiki documentation, but with an added layer of robust, scalable processing for massive codebases.
Key Inputs: Same as wiki-generator.ts, plus an onProgress callback for streaming updates.
Key Outputs: A stream of ProgressUpdate objects, culminating in WikiGeneratorResult (generated pages, detailed usage including cache tokens).
Gemini Usage: Utilizes Gemini's content caching mechanism (genAI.caches) to store the entire codebase context for efficient multi-stage generation. It performs chunk-by-chunk analysis and a final stitching phase, and incorporates retry logic with exponential backoff to manage API rate limits.

These AI modules form the "intelligence layer" of gh.gg, leveraging Google Gemini's advanced natural language understanding and generation capabilities to provide unprecedented insights and automation for GitHub repositories.