🤖 AI Code Reviewer

Production-grade Python code analysis combining AST static analysis with Google Gemini LLM reasoning.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│          Web Dashboard (HTML / CSS / JS)             │
│  • CodeMirror syntax-highlighted editor             │
│  • GitHub repo/file URL input                       │
│  • Animated score gauge + severity-filtered cards   │
│  • Line-level highlights in editor                  │
└────────────────────┬────────────────────────────────┘
                     │ POST /api/analyze
┌────────────────────▼────────────────────────────────┐
│                FastAPI Backend                       │
│  ┌─────────────────────┬───────────────────────────┐│
│  │  AST Analyser       │   Gemini LLM Analyser     ││
│  │  (ast_analyzer.py)  │   (llm_analyzer.py)       ││
│  │                     │                           ││
│  │  • Unused variables │   • Code quality review   ││
│  │  • Long functions   │   • Security analysis     ││
│  │  • Deep nesting     │   • Improvement snippets  ││
│  │  • Naming issues    │   • Architecture advice   ││
│  │  • Missing docs     │                           ││
│  │  • Bare except      │                           ││
│  │  • Mutable defaults │                           ││
│  │  • Too many args    │                           ││
│  └─────────────────────┴───────────────────────────┘│
│  ┌──────────────────────────────────────────────────┐│
│  │  GitHub Fetcher (github_fetcher.py)              ││
│  │  Supports: repo URLs, blob URLs, raw file URLs   ││
│  └──────────────────────────────────────────────────┘│
│  ┌──────────────────────────────────────────────────┐│
│  │  Scorer & Aggregator (scorer.py)                 ││
│  │  Deduplication + severity-weighted 0–100 score  ││
│  └──────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘

---

📁 Project Structure

Code_reviewer_and_analyser/
├── backend/
│   ├── main.py                  # FastAPI app + static file serving
│   ├── config.py                # Pydantic settings (.env reader)
│   ├── core/
│   │   ├── ast_analyzer.py      # 8 AST-based static detectors
│   │   ├── llm_analyzer.py      # Gemini LLM analysis engine
│   │   ├── github_fetcher.py    # GitHub repo/file fetcher
│   │   └── scorer.py            # Issue dedup + quality scoring
│   ├── models/
│   │   └── schemas.py           # Pydantic request/response models
│   └── routers/
│       └── analyze.py           # POST /api/analyze endpoint
├── frontend/
│   ├── index.html               # Dashboard SPA
│   ├── style.css                # Dark glassmorphism theme
│   └── app.js                   # Dashboard logic
├── .env.example                 # Environment variable template
├── requirements.txt
└── README.md

---

🚀 Quick Start

1. Clone & Install

git clone <your-repo-url>
cd Code_reviewer_and_analyser

# Create virtual environment
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

pip install -r requirements.txt

2. Configure Environment

cp .env.example .env

Edit .env:

GEMINI_API_KEY=your_gemini_api_key_here

Get a free Gemini API key at aistudio.google.com

3. Run

uvicorn backend.main:app --reload --port 8000

Open http://localhost:8000 in your browser.

---

📡 API Reference

POST /api/analyze

Analyse Python code or a GitHub repository.

Request Body

{
  "code": "def foo():\n    x = 1\n    return 2",
  "filename": "example.py",
  "enable_llm": true
}

Or with a GitHub URL:

{
  "github_url": "https://github.com/owner/repo",
  "enable_llm": true
}

Field	Type	Required	Description
code	string	One of code/github_url	Raw Python source code
github_url	string	One of code/github_url	GitHub repo, blob, or raw URL
filename	string	No	Display filename (default: code.py)
enable_llm	boolean	No	Run Gemini LLM analysis (default: true)

Response

{
  "files": [
    {
      "filename": "example.py",
      "line_count": 8,
      "score": 62,
      "issues": [
        {
          "type": "code_smell",
          "severity": "medium",
          "source": "static",
          "line": 2,
          "line_end": null,
          "symbol": "x",
          "message": "Variable 'x' is assigned but never used.",
          "suggestion": "Remove the assignment or prefix with '_' to indicate intentional non-use.",
          "refactored_snippet": null
        }
      ]
    }
  ],
  "total_issues": 3,
  "overall_score": 62,
  "llm_summary": "The code has several issues including an unused variable...",
  "static_issue_count": 2,
  "llm_issue_count": 1
}

GET /health

{ "status": "ok", "service": "ai-code-reviewer" }

---

🔍 Static Analysis Detectors

Detector	Severity	What it catches
Unused Variables	Medium	Variables assigned but never read
Long Functions	High	Functions > 50 lines
Deep Nesting	High	Control-flow depth > 3 levels
Naming Issues	Low–Medium	Non-snake_case functions/vars, single-char names, non-PascalCase classes
Missing Docstrings	Low	Public functions/classes without docstrings
Bare Except	High	except: without exception type
Mutable Defaults	High	List/dict/set as default argument
Too Many Args	Medium	Functions with > 7 parameters

---

🤖 LLM Analysis (Gemini)

The Gemini gemini-2.0-flash model is prompted with a structured JSON schema request to detect:

• Logic errors and bug risks
• Security vulnerabilities
• Performance bottlenecks
• Architecture and design issues
• Code maintainability problems

Each LLM issue includes a refactored_snippet with corrected code where applicable.

---

🧮 Scoring System

Quality score is computed as:

score = max(0, 100 - Σ penalty(issue))

Severity	Penalty
Critical	−20
High	−10
Medium	−5
Low	−2
Info	0

Near-duplicate issues (same line, >60% message word overlap) across static and LLM sources are deduplicated.

---

🧪 Sample curl Request

curl -X POST http://localhost:8000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "code": "def badFunction(a,b,c,d,e,f,g,h):\n    x = 1\n    try:\n        pass\n    except:\n        pass",
    "filename": "test.py",
    "enable_llm": false
  }'

---

📊 Sample Output

{
  "files": [{
    "filename": "test.py",
    "line_count": 6,
    "score": 53,
    "issues": [
      {
        "type": "maintainability",
        "severity": "medium",
        "source": "static",
        "line": 1,
        "symbol": "badFunction",
        "message": "Function 'badFunction' has 8 parameters (limit: 7).",
        "suggestion": "Consider grouping related parameters into a dataclass or config object.",
        "refactored_snippet": null
      },
      {
        "type": "code_smell",
        "severity": "medium",
        "source": "static",
        "line": 2,
        "symbol": "x",
        "message": "Variable 'x' is assigned but never used.",
        "suggestion": "Remove the assignment or prefix with '_'.",
        "refactored_snippet": null
      },
      {
        "type": "bug_risk",
        "severity": "high",
        "source": "static",
        "line": 4,
        "message": "Bare 'except:' clause catches all exceptions.",
        "suggestion": "Catch specific exceptions: 'except Exception as e:'",
        "refactored_snippet": "except Exception as e:\n    logger.error('Error: %s', e)\n    raise"
      }
    ]
  }],
  "total_issues": 3,
  "overall_score": 53,
  "llm_summary": null,
  "static_issue_count": 3,
  "llm_issue_count": 0
}

---

⚙️ Configuration

Variable	Default	Description
GEMINI_API_KEY	—	Google Gemini API key (required for LLM)
GITHUB_TOKEN	—	GitHub PAT (optional, increases rate limits)
APP_HOST	0.0.0.0	Server bind host
APP_PORT	8000	Server bind port
MAX_FILE_SIZE_KB	512	Max file size to analyse
MAX_GITHUB_FILES	20	Max .py files to fetch from a repo

---

🛡️ Security Notes

• CORS is set to * for development. Restrict in production.
• GitHub token is never exposed to the frontend.
• Code analysis runs in an isolated process thread (no code execution).

---

📄 License

MIT