Skip to content

repo_progress_report.md

Latest commit

 

History

History
224 lines (185 loc) · 15.7 KB

repo_progress_report.md

File metadata and controls

224 lines (185 loc) · 15.7 KB
Raw

📊 Repository Progress Report: AI-Powered Repository Risk Intelligence Platform

Project Goal

An enterprise-grade platform for analyzing GitHub repositories to detect technical debt, risk hotspots, and unstable files using code metrics and (eventually) ML. Targeted at Engineering Managers, CTOs, DevOps Leads, and Developers.

🏗️ Architecture Overview

The system is designed as a modular, microservices-ready architecture with 6 subsystems:

Subsystem Technology Status
API Gateway FastAPI (Python 3.11) 🟡 Scaffolded (no routes)
Analysis Engine (Worker) RQ + GitPython + Radon/Bandit 🟢 Core implemented
Database Layer PostgreSQL (async via asyncpg) 🟢 Models & engine done
Risk Scoring Engine Rule-based weighted scoring 🟢 Implemented
Frontend Client Next.js 14 + Tailwind CSS 🔴 Not started
ML Service Scikit-Learn / XGBoost 🔴 Not started
Insights Engine (LLM) AI-generated summaries 🔴 Not started

✅ What Has Been Implemented

1. Infrastructure & DevOps

  • Docker Compose — Full orchestration with 4 services:
    • db (PostgreSQL 15)
    • redis (Redis 7)
    • backend (FastAPI via Uvicorn)
    • worker (RQ background processor)
  • Dockerfile — Python 3.11-slim, Poetry-based dependency management, includes git for repo cloning
  • Poetry pyproject.toml — All dependencies declared (FastAPI, SQLModel, asyncpg, Redis, RQ, GitPython, PyDriller, Radon, Bandit, etc.)

2. Configuration (app/core/config.py)

  • Pydantic-based Settings class with:
    • DATABASE_URL (PostgresDsn)
    • REDIS_URL (RedisDsn)
    • JWT security settings (SECRET_KEY, ALGORITHM, token expiry)
    • GitHub OAuth placeholders (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET)
    • Worker queue configuration (high, default, low)

3. Database Layer (app/db/)

  • Async engine via sqlalchemy.ext.asyncio + asyncpg
  • Auto table creation on app startup (init_db())
  • Async session factory (get_session())
  • 7 SQLModel tables fully defined:
Model Key Fields Relationships
User github_id, username, email, avatar_url ↔ Organizations (M2M)
Organization name, slug, created_by_user_id → Repositories, ↔ Users
OrganizationMember org_id, user_id, role (admin/member) Join table
Repository org_id, name, html_url, clone_url, health_score, risk_status → AnalysisJobs, → Files
AnalysisJob repo_id, status, mode, progress_pct, error_log → Repository
File repo_id, file_path, language, is_active → FileMetrics
FileMetric file_id, complexity, loc, churn, ownership_score → File
  • Enums: JobStatus (queued/running/completed/failed), AnalysisMode (standard/performance), OrgRole (admin/member), RiskStatus (low/medium/high/critical)

4. Pluggable Analyzer Framework (app/services/analyzer/)

  • LanguageAnalyzer ABC — Abstract base class with:
    • language_name property
    • file_extensions property
    • analyze(file_path, content) method
    • can_handle(file_path) convenience method
  • UniversalMetrics — Language-agnostic metrics applied to ALL files:
    • Lines of Code (LOC)
    • Empty line count
    • File size in bytes
  • PythonAnalyzer — Language-specific analyzer for .py files using:
    • Radon — Cyclomatic Complexity, Raw Metrics (LOC, SLOC), Halstead Metrics (volume, difficulty, effort)
    • Bandit — imported but not yet wired into analysis
  • AnalyzerManager — Registry pattern that:
    • Runs universal metrics on every file
    • Dispatches to language-specific analyzer when available
    • Falls back to "Unknown" language detection

5. Analysis Orchestrator (app/services/analysis_orchestrator.py)

The main job execution pipeline:

  1. Retrieves AnalysisJob from DB (using sync engine)
  2. Marks job as RUNNING
  3. Clones the repo (full or shallow based on mode)
  4. Walks the repository file tree (skipping .git)
  5. For each file:
    • Reads content (UTF-8, ignoring errors for binary files)
    • Runs AnalyzerManager.analyze_file() for metrics
    • Persists File and FileMetric records
    • Calculates per-file risk score
  6. Computes overall repo health score
  7. Classifies repo risk status
  8. Marks job as COMPLETED (or FAILED on exception)

6. Repository Service (app/services/repo_service.py)

  • Clones Git repos to /tmp/repos/ with path sanitization
  • Supports shallow cloning (depth 5000 for performance mode)
  • Re-clones fresh on each analysis (cleanup existing)
  • get_commit_count() utility method

7. Risk Scoring Service (app/services/risk_scoring.py)

  • Weighted formula: Risk = (0.4 × Complexity) + (0.3 × Churn) + (0.1 × LOC) + (0.2 × Bus Factor)
  • Normalization: Complexity capped at 20, LOC at 500, Churn at 100
  • Classification: LOW (<30), MEDIUM (30-60), HIGH (60-80), CRITICAL (≥80)
  • Repo Health: 100 - average_risk across all files

8. Background Worker (app/workers/entrypoint.py)

  • RQ worker listening on high, default, low queues
  • Connects to Redis via configured URL

9. FastAPI App (app/main.py)

  • Lifespan-based startup (auto-creates tables)
  • Two endpoints:
    • GET / — Welcome message
    • GET /health — Health check
  • OpenAPI docs at /api/v1/openapi.json

10. Scripts (scripts/)

  • seed_and_trigger.py — Seeds DB with test User → Org → Repo (psf/requests) → AnalysisJob
  • process_job.py — CLI to manually run a specific job by ID
  • test_pipeline_standalone.py — End-to-end test that creates a local git repo, runs analysis, and verifies results (using SQLite)

🔴 What Has NOT Been Implemented

API Layer

  • No API routes exist — The app/api/ directory has only an empty init.py
  • No endpoints for: creating repos, triggering analysis, fetching results, user auth
  • No Pydantic request/response schemas (schemas/ directory is missing entirely)

Authentication & Security

  • GitHub OAuth config is placeholder only (no OAuth flow, no JWT issuance)
  • No auth middleware or dependency injection

Frontend

  • No frontend exists — The planned Next.js app has not been started
  • No dashboard, charts, or visualization

ML / Prediction

  • No ML pipeline, training scripts, or model inference
  • Scikit-Learn / XGBoost are not in dependencies

AI Insights (LLM)

  • No natural language risk explanations or refactoring suggestions

Advanced Analysis

  • Churn calculation is placeholder (always 0) — Git history analysis via PyDriller is not wired
  • Bus Factor / Ownership not implemented (ownership_score always 0.0)
  • Bandit security scanning is imported but never called
  • Entropy mentioned but not implemented
  • No commit-level tracking (the commits table mentioned in architecture is missing from models)
  • No contributors table
  • No risk_snapshots table (fields exist on FileMetric but seem misplaced)

Testing

  • No proper test suite (pytest is a dev dependency but no tests directory)
  • The standalone test script uses SQLite and has hardcoded paths

CI/CD

  • No GitHub Actions workflows
  • No .github/ directory

⚠️ Known Issues / Technical Debt

  1. FileMetric model has extra fields — repo_id, date, total_risk_score, high_risk_file_count appear to be leftover from a RiskSnapshot model that was merged into FileMetric by mistake
  2. PythonAnalyzer import path — Uses from .base import LanguageAnalyzer but base.py is in the parent analyzer/ directory, not in languages/
  3. Sync/Async mismatch — The main app uses async engine but the worker creates its own sync engine by string-replacing +asyncpg from the URL
  4. No Alembic migrations — Tables are auto-created; no migration history
  5. datetime.utcnow() is used throughout (deprecated in Python 3.12+)

📈 Progress by Architecture Phase

Phase Scope Status
MVP (Weeks 1-4) Auth, Import Repos, Basic Metrics, Simple Dashboard ~30% done (metrics engine only)
Advanced (Weeks 5-8) Risk Scoring, Trends, Charts, Export ~15% done (scoring formula only)
Elite (Weeks 9-12) ML Prediction, AI Insights, CI/CD Integration 0%

📁 File Tree Summary

codebase analyser/
├── docker-compose.yml          ← 4-service orchestration
├── README.md                   ← Quick start guide
├── docs/
│   └── ARCHITECTURE.md         ← Detailed system design doc
├── scripts/
│   ├── seed_and_trigger.py     ← DB seeding + job creation
│   ├── process_job.py          ← Manual job runner
│   └── test_pipeline_standalone.py  ← E2E test
└── backend/
    ├── Dockerfile              ← Python 3.11 + Poetry
    ├── pyproject.toml           ← Dependencies
    └── app/
        ├── main.py             ← FastAPI app (2 endpoints)
        ├── core/
        │   └── config.py       ← Pydantic settings
        ├── db/
        │   ├── engine.py       ← Async DB engine + session
        │   └── models.py       ← 7 SQLModel tables
        ├── services/
        │   ├── analysis_orchestrator.py  ← Main job pipeline
        │   ├── repo_service.py          ← Git clone logic
        │   ├── risk_scoring.py          ← Weighted risk formula
        │   └── analyzer/
        │       ├── base.py              ← LanguageAnalyzer ABC
        │       ├── universal.py         ← LOC, file size
        │       ├── manager.py           ← Analyzer registry
        │       └── languages/
        │           └── python.py        ← Radon complexity
        ├── workers/
        │   └── entrypoint.py   ← RQ worker
        └── api/
            └── __init__.py     ← Empty (no routes)

Important

Bottom line: The project has a solid architectural foundation — database models, a pluggable analyzer framework, risk scoring logic, Docker orchestration, and a working analysis pipeline. However, it's missing the API routes, frontend, authentication, git history analysis (churn/bus factor), ML pipeline, and AI insights that would make it a usable product. Roughly 25-30% of the planned MVP is complete.