coderag-ai 0.3.0__py3-none-any.whl

coderag/__init__.py

@@ -0,0 +1,12 @@
+"""CodeRAG: token-efficient, structure-aware Code Intelligence + RAG."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    # Distribution name is `coderag-ai`; the import name is `coderag`.
+    __version__ = _version("coderag-ai")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

coderag/analyzers/base.py

@@ -0,0 +1,36 @@
+"""Static-analysis adapter interface (Phase 10).
+
+A ``StaticAnalyzer`` turns tool output into normalized ``Finding``s. Adapters run
+the tool as a subprocess (never importing/linking it), so licensing stays clean
+(see docs/licenses.md re: pylint GPL). Future adapters: SonarQube, mypy, Ruff,
+Bandit.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class Finding:
+    file_path: str          # repository-relative
+    line: int
+    code: str               # rule id, e.g. "F401", "W0611"
+    message: str
+    tool: str
+
+    def describe(self) -> str:
+        return f"[{self.tool}:{self.code}] {self.file_path}:{self.line} — {self.message}"
+
+
+class StaticAnalyzer(ABC):
+    name: str
+
+    @abstractmethod
+    def available(self) -> bool:
+        """Whether the underlying tool is installed/runnable."""
+
+    @abstractmethod
+    def analyze(self, root: str, paths: list[str] | None = None) -> list[Finding]:
+        """Run the analyzer over ``root`` (optionally limited to ``paths``)."""

coderag/analyzers/flake8_adapter.py

@@ -0,0 +1,43 @@
+"""Flake8 adapter (runs flake8 as a subprocess)."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+from coderag.analyzers.base import Finding, StaticAnalyzer
+
+_FMT = "%(path)s\t%(row)d\t%(code)s\t%(text)s"
+
+
+class Flake8Analyzer(StaticAnalyzer):
+    name = "flake8"
+
+    def available(self) -> bool:
+        try:
+            subprocess.run(
+                [sys.executable, "-m", "flake8", "--version"],
+                capture_output=True, check=True,
+            )
+            return True
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return False
+
+    def analyze(self, root: str, paths: list[str] | None = None) -> list[Finding]:
+        targets = paths or ["."]
+        result = subprocess.run(
+            [sys.executable, "-m", "flake8", f"--format={_FMT}", *targets],
+            cwd=root, capture_output=True, text=True,
+        )
+        findings: list[Finding] = []
+        for line in result.stdout.splitlines():
+            parts = line.split("\t")
+            if len(parts) != 4:
+                continue
+            path, row, code, text = parts
+            path = path.lstrip("./").replace("\\", "/")
+            findings.append(
+                Finding(file_path=path, line=int(row), code=code, message=text,
+                        tool=self.name)
+            )
+        return findings

coderag/analyzers/pylint_adapter.py

@@ -0,0 +1,50 @@
+"""Pylint adapter (runs pylint as a subprocess; its JSON output is consumed).
+
+Pylint is GPL-2.0 but is invoked only as an external tool — CodeRAG neither
+imports nor links it (docs/licenses.md).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+
+from coderag.analyzers.base import Finding, StaticAnalyzer
+
+
+class PylintAnalyzer(StaticAnalyzer):
+    name = "pylint"
+
+    def available(self) -> bool:
+        try:
+            subprocess.run(
+                [sys.executable, "-m", "pylint", "--version"],
+                capture_output=True, check=True,
+            )
+            return True
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return False
+
+    def analyze(self, root: str, paths: list[str] | None = None) -> list[Finding]:
+        targets = paths or ["."]
+        result = subprocess.run(
+            [sys.executable, "-m", "pylint", "--output-format=json", "--score=n", *targets],
+            cwd=root, capture_output=True, text=True,
+        )
+        try:
+            items = json.loads(result.stdout or "[]")
+        except json.JSONDecodeError:
+            return []
+        findings: list[Finding] = []
+        for it in items:
+            findings.append(
+                Finding(
+                    file_path=str(it.get("path", "")).replace("\\", "/"),
+                    line=int(it.get("line", 1)),
+                    code=it.get("message-id", it.get("symbol", "")),
+                    message=it.get("message", ""),
+                    tool=self.name,
+                )
+            )
+        return findings

coderag/analyzers/workflow.py

@@ -0,0 +1,107 @@
+"""Analyzer-driven fix workflow (Phase 10).
+
+Flow (spec §21): finding -> identify file/line -> identify enclosing symbol ->
+Code-RAG context -> (optional) LLM patch. Patch *application* and re-verification
+are intentionally left to the caller as an interface; the model is never allowed
+to loop unbounded — attempts are capped by ``MAX_FIX_ATTEMPTS``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from coderag.analyzers.base import Finding
+from coderag.context.package import ContextPackage
+from coderag.core.config import Settings, get_settings
+from coderag.db.models import Repository, Symbol
+
+
+def map_finding_to_symbol(session: Session, repository_id: int, finding: Finding):
+    """Return the smallest symbol whose line range encloses the finding's line."""
+    enclosing = session.scalars(
+        select(Symbol).where(
+            Symbol.repository_id == repository_id,
+            Symbol.file_path == finding.file_path,
+            Symbol.start_line <= finding.line,
+            Symbol.end_line >= finding.line,
+        )
+    ).all()
+    if enclosing:
+        # smallest span = most specific; prefer non-module
+        return min(
+            enclosing,
+            key=lambda s: (s.symbol_type == "module", s.end_line - s.start_line),
+        )
+    # fall back to the module symbol for that file
+    return session.scalar(
+        select(Symbol).where(
+            Symbol.repository_id == repository_id,
+            Symbol.file_path == finding.file_path,
+            Symbol.symbol_type == "module",
+        )
+    )
+
+
+@dataclass
+class FixContext:
+    finding: Finding
+    symbol_qualified_name: str | None
+    package: ContextPackage
+
+
+def build_fix_context(
+    session: Session, repo: Repository, finding: Finding,
+    settings: Settings | None = None,
+) -> FixContext:
+    from coderag.context.builder import ContextBuilder
+    from coderag.service import get_engine
+
+    settings = settings or get_settings()
+    symbol = map_finding_to_symbol(session, repo.id, finding)
+    query = symbol.qualified_name if symbol else finding.message
+    finding_text = (
+        finding.describe()
+        + "\n\nFix this finding WITHOUT changing existing behavior. "
+        + "Return a minimal patch and explain the change."
+    )
+    engine = get_engine(settings, semantic=True, graph=True)
+    outcome = engine.search(session, repo.id, query, top_n=None)
+    package = ContextBuilder(session, settings=settings).build(
+        query, outcome.candidates, repo,
+        changed_symbol_ids={symbol.id} if symbol else None,
+        finding=finding_text,
+    )
+    return FixContext(
+        finding=finding,
+        symbol_qualified_name=symbol.qualified_name if symbol else None,
+        package=package,
+    )
+
+
+def propose_fix(fix: FixContext, provider, max_output_tokens: int = 1024) -> str:
+    """Single LLM attempt to propose a patch for a finding (requires a provider)."""
+    from coderag.llm.base import LLMRequest
+
+    return provider.generate(
+        LLMRequest(prompt=fix.package.prompt_text, max_tokens=max_output_tokens)
+    ).text
+
+
+def run_fix_loop(fixes: list[FixContext], provider, settings: Settings | None = None):
+    """Bounded fix proposals — capped at MAX_FIX_ATTEMPTS to prevent infinite loops.
+
+    Application/re-verification of patches is the caller's responsibility (pass
+    verified patches back in); this MVP produces proposals only.
+    """
+    settings = settings or get_settings()
+    proposals = []
+    for fix in fixes[: settings.max_fix_attempts]:
+        proposals.append({
+            "finding": fix.finding.describe(),
+            "symbol": fix.symbol_qualified_name,
+            "patch": propose_fix(fix, provider, settings.llm_max_output_tokens),
+        })
+    return proposals

coderag/api/app.py

@@ -0,0 +1,351 @@
+"""FastAPI application.
+
+Endpoints for repository registration/indexing, retrieval (`/search`,
+`/context` — no LLM needed), `/ask` (needs an LLM), symbol inspection, and
+metrics. Every repository-scoped request is authorized via
+``AuthorizationProvider`` and retrieval is always bound to a ``repository_id``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from fastapi import Depends, FastAPI, Header, HTTPException
+from fastapi.responses import HTMLResponse
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from coderag import __version__ as _coderag_version
+from coderag.api import schemas as s
+from coderag.db.models import (
+    IndexingRun,
+    LLMRequest,
+    QueryRecord,
+    Repository,
+    Symbol,
+    SymbolEmbedding,
+    SymbolRelationship,
+)
+from coderag.security.authz import get_authorization_provider
+from coderag.service import (
+    RepositoryNotFound,
+    resolve_repository,
+    run_ask,
+    run_context,
+    run_search,
+)
+
+app = FastAPI(title="CodeRAG", version=_coderag_version)
+
+
+def get_session() -> Iterator[Session]:
+    from coderag.db.base import get_session_factory
+
+    session = get_session_factory()()
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+
+
+def principal(x_user: str | None = Header(default=None)) -> str | None:
+    return x_user
+
+
+def _resolve_authorized(session: Session, name: str | None, who: str | None) -> Repository:
+    try:
+        repo = resolve_repository(session, name)
+    except RepositoryNotFound as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    if not get_authorization_provider().can_access(who, repo.id):
+        raise HTTPException(status_code=403, detail="not authorized for this repository")
+    return repo
+
+
+@app.get("/health")
+def health() -> dict:
+    return {"status": "ok"}
+
+
+@app.post("/repositories", response_model=s.RepositoryOut)
+def register_repository(
+    req: s.RegisterRepoRequest, session: Session = Depends(get_session)
+) -> s.RepositoryOut:
+    from coderag.indexing.indexer import get_or_create_repository
+
+    repo = get_or_create_repository(session, req.name, req.path, req.url)
+    session.flush()
+    return s.RepositoryOut(
+        id=repo.id, name=repo.name, local_path=repo.local_path,
+        default_branch=repo.default_branch, indexed_commit_sha=repo.indexed_commit_sha,
+    )
+
+
+@app.post("/repositories/{repo_id}/index", response_model=s.IndexStatusOut)
+def index_repository_endpoint(
+    repo_id: int, session: Session = Depends(get_session),
+    who: str | None = Depends(principal),
+) -> s.IndexStatusOut:
+    from coderag.indexing.indexer import Indexer
+
+    repo = session.get(Repository, repo_id)
+    if repo is None:
+        raise HTTPException(status_code=404, detail="repository not found")
+    if not get_authorization_provider().can_access(who, repo.id):
+        raise HTTPException(status_code=403, detail="not authorized")
+    run, stats = Indexer(session).full_index(repo)
+    return s.IndexStatusOut(
+        repository_id=repo.id, status=run.status, mode=run.mode,
+        files_indexed=stats.files_indexed, symbols_indexed=stats.symbols_indexed,
+        embeddings_created=stats.embeddings_created,
+        relationships=stats.relationships_created,
+        duration_seconds=stats.duration_seconds, to_commit=stats.commit_sha,
+    )
+
+
+@app.get("/repositories/{repo_id}/index/status", response_model=s.IndexStatusOut)
+def index_status(
+    repo_id: int, session: Session = Depends(get_session),
+) -> s.IndexStatusOut:
+    run = session.scalar(
+        select(IndexingRun).where(IndexingRun.repository_id == repo_id)
+        .order_by(IndexingRun.id.desc())
+    )
+    if run is None:
+        raise HTTPException(status_code=404, detail="no indexing run for repository")
+    return s.IndexStatusOut(
+        repository_id=repo_id, status=run.status, mode=run.mode,
+        files_indexed=run.files_indexed, symbols_indexed=run.symbols_indexed,
+        embeddings_created=run.embeddings_created, duration_seconds=run.duration_seconds,
+        to_commit=run.to_commit, error=run.error,
+    )
+
+
+@app.post("/search", response_model=s.SearchResponse)
+def search_endpoint(
+    req: s.SearchRequest, session: Session = Depends(get_session),
+    who: str | None = Depends(principal),
+) -> s.SearchResponse:
+    repo = _resolve_authorized(session, req.repository, who)
+    _repo, outcome = run_search(
+        session, req.query, repo.name, top_n=req.limit,
+        semantic=req.semantic, graph=req.graph, record=True,
+    )
+    return s.SearchResponse(
+        repository=repo.name, latency_ms=outcome.latency_ms,
+        candidates=[
+            s.CandidateOut(
+                symbol_id=c.symbol_id, qualified_name=c.qualified_name,
+                symbol_type=c.symbol_type, file_path=c.file_path,
+                start_line=c.start_line, end_line=c.end_line,
+                score=round(c.fused_score, 6), reasons=sorted(c.reasons),
+            )
+            for c in outcome.candidates
+        ],
+    )
+
+
+@app.post("/context", response_model=s.ContextResponse)
+def context_endpoint(
+    req: s.ContextRequest, session: Session = Depends(get_session),
+    who: str | None = Depends(principal),
+) -> s.ContextResponse:
+    repo = _resolve_authorized(session, req.repository, who)
+    _repo, package, _outcome = run_context(
+        session, req.query, repo.name, max_tokens=req.max_tokens, finding=req.finding,
+    )
+    return s.ContextResponse(
+        repository=repo.name,
+        entries=[
+            s.ContextEntryOut(
+                category=e.category, qualified_name=e.candidate.qualified_name,
+                file_path=e.candidate.file_path, start_line=e.candidate.start_line,
+                end_line=e.candidate.end_line, tokens=e.tokens,
+                reasons=sorted(e.candidate.reasons),
+            )
+            for e in package.entries
+        ],
+        accounting=s.AccountingOut(**package.accounting.as_dict()),
+        prompt=package.prompt_text if req.include_prompt else None,
+    )
+
+
+@app.post("/ask", response_model=s.AskResponse)
+def ask_endpoint(
+    req: s.AskRequest, session: Session = Depends(get_session),
+    who: str | None = Depends(principal),
+) -> s.AskResponse:
+    repo = _resolve_authorized(session, req.repository, who)
+    try:
+        _repo, package, response, _outcome = run_ask(
+            session, req.query, repo.name, max_tokens=req.max_tokens,
+            max_output_tokens=req.max_output_tokens,
+        )
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    u = response.usage
+    return s.AskResponse(
+        repository=repo.name, answer=response.text,
+        usage=s.UsageOut(
+            input_tokens=u.input_tokens, output_tokens=u.output_tokens,
+            cached_input_tokens=u.cached_input_tokens, model=u.model,
+            latency_ms=u.latency_ms,
+        ),
+        accounting=s.AccountingOut(**package.accounting.as_dict()),
+    )
+
+
+@app.get("/symbols/{symbol_id}", response_model=s.SymbolOut)
+def get_symbol(
+    symbol_id: int, session: Session = Depends(get_session),
+    who: str | None = Depends(principal),
+) -> s.SymbolOut:
+    sym = session.get(Symbol, symbol_id)
+    if sym is None:
+        raise HTTPException(status_code=404, detail="symbol not found")
+    if not get_authorization_provider().can_access(who, sym.repository_id):
+        raise HTTPException(status_code=403, detail="not authorized")
+    return s.SymbolOut(
+        id=sym.id, qualified_name=sym.qualified_name, symbol_name=sym.symbol_name,
+        symbol_type=sym.symbol_type, file_path=sym.file_path, start_line=sym.start_line,
+        end_line=sym.end_line, signature=sym.signature, docstring=sym.docstring,
+        token_count=sym.token_count, source_code=sym.source_code,
+    )
+
+
+@app.get("/symbols/{symbol_id}/relationships", response_model=list[s.RelationshipOut])
+def get_symbol_relationships(
+    symbol_id: int, session: Session = Depends(get_session),
+    who: str | None = Depends(principal),
+) -> list[s.RelationshipOut]:
+    sym = session.get(Symbol, symbol_id)
+    if sym is None:
+        raise HTTPException(status_code=404, detail="symbol not found")
+    if not get_authorization_provider().can_access(who, sym.repository_id):
+        raise HTTPException(status_code=403, detail="not authorized")
+    rels = session.scalars(
+        select(SymbolRelationship).where(
+            (SymbolRelationship.source_symbol_id == symbol_id)
+            | (SymbolRelationship.target_symbol_id == symbol_id)
+        )
+    ).all()
+    qual: dict[int, str] = {
+        row[0]: row[1]
+        for row in session.execute(
+            select(Symbol.id, Symbol.qualified_name).where(
+                Symbol.repository_id == sym.repository_id
+            )
+        ).all()
+    }
+    out = []
+    for r in rels:
+        outgoing = r.source_symbol_id == symbol_id
+        out.append(
+            s.RelationshipOut(
+                relationship_type=r.relationship_type, confidence=r.confidence,
+                target_symbol_id=r.target_symbol_id,
+                target_qualified_name=(
+                    qual.get(r.target_symbol_id) if r.target_symbol_id is not None else None
+                ),
+                target_name=r.target_name,
+                direction="outgoing" if outgoing else "incoming",
+            )
+        )
+    return out
+
+
+@app.get("/metrics", response_model=s.MetricsOut)
+def metrics(session: Session = Depends(get_session)) -> s.MetricsOut:
+    def count(model) -> int:
+        return session.scalar(select(func.count()).select_from(model)) or 0
+
+    avg_ctx = session.scalar(select(func.avg(QueryRecord.context_tokens))) or 0.0
+    avg_lat = session.scalar(select(func.avg(QueryRecord.retrieval_latency_ms))) or 0.0
+    in_tok = session.scalar(select(func.coalesce(func.sum(LLMRequest.input_tokens), 0))) or 0
+    out_tok = session.scalar(select(func.coalesce(func.sum(LLMRequest.output_tokens), 0))) or 0
+    cand_sum = session.scalar(
+        select(func.coalesce(func.sum(QueryRecord.candidate_tokens), 0))
+    ) or 0
+    ctx_sum = session.scalar(
+        select(func.coalesce(func.sum(QueryRecord.context_tokens), 0))
+    ) or 0
+    saved = int(cand_sum) - int(ctx_sum)
+    reduction = round(100.0 * saved / cand_sum, 1) if cand_sum else 0.0
+    base_sum = int(session.scalar(
+        select(func.coalesce(func.sum(QueryRecord.baseline_tokens), 0))
+    ) or 0)
+    # only queries that actually recorded a baseline contribute to this comparison
+    base_ctx = int(session.scalar(
+        select(func.coalesce(func.sum(QueryRecord.context_tokens), 0)).where(
+            QueryRecord.baseline_tokens > 0
+        )
+    ) or 0)
+    saved_vs_files = base_sum - base_ctx
+    reduction_vs_files = round(100.0 * saved_vs_files / base_sum, 1) if base_sum else 0.0
+    return s.MetricsOut(
+        repositories=count(Repository), symbols=count(Symbol),
+        embeddings=count(SymbolEmbedding), relationships=count(SymbolRelationship),
+        queries=count(QueryRecord), llm_requests=count(LLMRequest),
+        avg_context_tokens=round(float(avg_ctx), 1),
+        avg_retrieval_latency_ms=round(float(avg_lat), 2),
+        total_llm_input_tokens=int(in_tok), total_llm_output_tokens=int(out_tok),
+        total_candidate_tokens=int(cand_sum), total_context_tokens=int(ctx_sum),
+        total_tokens_saved=saved, avg_token_reduction_percent=reduction,
+        total_baseline_tokens=base_sum, total_saved_vs_files=saved_vs_files,
+        reduction_vs_files_percent=reduction_vs_files,
+    )
+
+
+@app.get("/queries", response_model=list[s.QueryRow])
+def recent_queries(
+    limit: int = 100, session: Session = Depends(get_session)
+) -> list[s.QueryRow]:
+    rows = session.execute(
+        select(QueryRecord, Repository.name)
+        .join(Repository, Repository.id == QueryRecord.repository_id)
+        .order_by(QueryRecord.id.desc())
+        .limit(limit)
+    ).all()
+    # sum LLM tokens per query in one pass
+    llm = {
+        qid: (int(itok), int(otok))
+        for qid, itok, otok in session.execute(
+            select(
+                LLMRequest.query_id,
+                func.coalesce(func.sum(LLMRequest.input_tokens), 0),
+                func.coalesce(func.sum(LLMRequest.output_tokens), 0),
+            ).group_by(LLMRequest.query_id)
+        ).all()
+    }
+    out: list[s.QueryRow] = []
+    for q, repo_name in rows:
+        saved = q.candidate_tokens - q.context_tokens
+        reduction = round(100.0 * saved / q.candidate_tokens, 1) if q.candidate_tokens else 0.0
+        li, lo = llm.get(q.id, (None, None))
+        out.append(s.QueryRow(
+            id=q.id, repository=repo_name, mode=q.mode, query=q.query_text,
+            candidates_found=q.candidates_found, candidates_selected=q.candidates_selected,
+            candidate_tokens=q.candidate_tokens, context_tokens=q.context_tokens,
+            tokens_saved=saved, reduction_percent=reduction,
+            baseline_tokens=q.baseline_tokens, baseline_files=q.baseline_files,
+            saved_vs_files=q.baseline_tokens - q.context_tokens if q.baseline_tokens else 0,
+            reduction_vs_files=(
+                round(100.0 * (q.baseline_tokens - q.context_tokens) / q.baseline_tokens, 1)
+                if q.baseline_tokens else 0.0
+            ),
+            retrieval_latency_ms=round(q.retrieval_latency_ms, 2),
+            llm_input_tokens=li, llm_output_tokens=lo,
+            created_at=q.created_at.isoformat() if q.created_at else "",
+        ))
+    return out
+
+
+@app.get("/dashboard", response_class=HTMLResponse, include_in_schema=False)
+def dashboard() -> str:
+    from coderag.api.dashboard import DASHBOARD_HTML
+
+    return DASHBOARD_HTML