repolens-cli 0.1.0__py3-none-any.whl

repolens/__init__.py

@@ -0,0 +1 @@
+"""RepoLens — AI-native codebase intelligence."""

repolens/ai_client.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from openai import OpenAI
+
+from .models import RepoAnalysis
+
+
+_PROVIDER_DEFAULTS: dict[str, dict] = {
+    "openai": {
+        "base_url": "https://api.openai.com/v1",
+        "model": "gpt-4o",
+        "key_env": "OPENAI_API_KEY",
+    },
+    "gemini": {
+        "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
+        "model": "gemini-2.5-flash",
+        "key_env": "GEMINI_API_KEY",
+    },
+    "groq": {
+        "base_url": "https://api.groq.com/openai/v1",
+        "model": "llama-3.3-70b-versatile",
+        "key_env": "GROQ_API_KEY",
+    },
+    "ollama": {
+        "base_url": "http://localhost:11434/v1",
+        "model": "llama3.2",
+        "key_env": None,  # no key needed
+    },
+    "anthropic": {
+        "base_url": "https://api.anthropic.com/v1",
+        "model": "claude-sonnet-4-6",
+        "key_env": "ANTHROPIC_API_KEY",
+    },
+}
+
+_client: Optional[OpenAI] = None
+_model: str = ""
+
+
+def is_configured() -> bool:
+    for p, cfg in _PROVIDER_DEFAULTS.items():
+        key_env = cfg.get("key_env")
+        if key_env and os.environ.get(key_env):
+            return True
+    if os.environ.get("REPOLENS_AI_PROVIDER") == "ollama":
+        return True
+    if os.environ.get("REPOLENS_AI_BASE_URL"):
+        return True
+    if os.environ.get("REPOLENS_AI_API_KEY"):
+        return True
+    return False
+
+
+def _get_client() -> tuple[OpenAI, str]:
+    global _client, _model
+    if _client is not None:
+        return _client, _model
+
+    provider = os.environ.get("REPOLENS_AI_PROVIDER", "").lower()
+    if not provider:
+        # auto-detect from available keys
+        for p, cfg in _PROVIDER_DEFAULTS.items():
+            key_env = cfg.get("key_env")
+            if key_env and os.environ.get(key_env):
+                provider = p
+                break
+        if not provider:
+            if os.environ.get("REPOLENS_AI_API_KEY") and os.environ.get("REPOLENS_AI_BASE_URL"):
+                provider = "custom"
+            elif os.environ.get("REPOLENS_AI_BASE_URL"):
+                provider = "ollama"  # no-auth local provider
+            else:
+                raise RuntimeError(
+                    "No AI provider configured.\n"
+                    "Set REPOLENS_AI_PROVIDER and a matching API key, e.g.:\n"
+                    "  REPOLENS_AI_PROVIDER=gemini  GEMINI_API_KEY=...\n"
+                    "  REPOLENS_AI_PROVIDER=groq    GROQ_API_KEY=...\n"
+                    "  REPOLENS_AI_PROVIDER=ollama  (no key needed)\n"
+                    "  REPOLENS_AI_PROVIDER=openai  OPENAI_API_KEY=...\n"
+                    "See .env.example for full reference."
+                )
+
+    cfg = _PROVIDER_DEFAULTS.get(provider, {})
+    base_url = os.environ.get("REPOLENS_AI_BASE_URL") or cfg.get("base_url", "")
+    model = os.environ.get("REPOLENS_AI_MODEL") or cfg.get("model", "gpt-4o")
+
+    # Resolve API key
+    api_key = os.environ.get("REPOLENS_AI_API_KEY")
+    if not api_key:
+        key_env = cfg.get("key_env")
+        if key_env:
+            api_key = os.environ.get(key_env)
+    if not api_key:
+        api_key = "ollama"  # openai SDK requires a non-empty string; local providers ignore it
+
+    _client = OpenAI(api_key=api_key, base_url=base_url or None)
+    _model = model
+    return _client, _model
+
+
+def _build_repo_context(analysis: RepoAnalysis) -> str:
+    lines: list[str] = []
+    lines.append(f"# Repository: {analysis.root}")
+    lines.append(f"Files analysed: {len(analysis.file_analyses)}")
+    lines.append("")
+
+    lines.append("## File Tree")
+    for f in analysis.files[:100]:
+        in_deg = analysis.stats.in_degree.get(f.path, 0)
+        badge = f" [{in_deg}←]" if in_deg > 0 else ""
+        lines.append(f"  {f.path} ({f.language}){badge}")
+    if len(analysis.files) > 100:
+        lines.append(f"  … and {len(analysis.files) - 100} more")
+    lines.append("")
+
+    lines.append("## Import Graph (file → local deps)")
+    for path, deps in list(analysis.stats.import_edges.items())[:50]:
+        if deps:
+            lines.append(f"  {path} → {', '.join(deps)}")
+    lines.append("")
+
+    if analysis.stats.circular_deps:
+        lines.append("## ⚠ Circular Dependencies")
+        for cycle in analysis.stats.circular_deps:
+            lines.append("  " + " → ".join(cycle) + " → " + cycle[0])
+        lines.append("")
+
+    lines.append("## Entry Points")
+    for ep in analysis.stats.entry_points[:20]:
+        lines.append(f"  {ep}")
+    lines.append("")
+
+    lines.append("## Most-Imported Files")
+    for path, count in analysis.stats.hub_files[:10]:
+        if count > 0:
+            lines.append(f"  {path} ({count} importers)")
+    lines.append("")
+
+    lines.append("## Functions per File (sample)")
+    items = sorted(
+        analysis.file_analyses.items(),
+        key=lambda x: len(x[1].functions),
+        reverse=True,
+    )[:20]
+    for path, fa in items:
+        if fa.functions:
+            names = ", ".join(f.name for f in fa.functions[:10])
+            lines.append(f"  {path}: {names}")
+
+    return "\n".join(lines)
+
+
+_SYSTEM_PROMPT = (
+    "You are RepoLens, an AI assistant that helps developers understand codebases. "
+    "You have a structured summary of a code repository: file tree, import dependency "
+    "graph, circular dependency alerts, entry points, and function listings. "
+    "Answer concisely, reference actual file names, and trace call chains step by step "
+    "when asked. If unsure, say so."
+)
+
+
+def ask(
+    analysis: RepoAnalysis,
+    question: str,
+    history: list[dict] | None = None,
+) -> str:
+    """Send *question* to the model, including prior *history* for multi-turn chat.
+
+    history: list of {"role": "user"|"assistant", "content": str} pairs
+             from previous turns (oldest first, excluding repo context).
+    """
+    client, model = _get_client()
+    context = _build_repo_context(analysis)
+
+    # First user turn carries the repo context; subsequent turns are plain text.
+    if history:
+        first_user = history[0]["content"]
+        if not first_user.startswith("<repo_context>"):
+            history[0] = {
+                "role": "user",
+                "content": f"<repo_context>\n{context}\n</repo_context>\n\n{first_user}",
+            }
+        messages = [{"role": "system", "content": _SYSTEM_PROMPT}] + history + [
+            {"role": "user", "content": question}
+        ]
+    else:
+        messages = [
+            {"role": "system", "content": _SYSTEM_PROMPT},
+            {
+                "role": "user",
+                "content": f"<repo_context>\n{context}\n</repo_context>\n\nQuestion: {question}",
+            },
+        ]
+
+    response = client.chat.completions.create(
+        model=model,
+        max_tokens=1024,
+        messages=messages,
+    )
+    return response.choices[0].message.content or ""
+
+
+def generate_onboarding(analysis: RepoAnalysis) -> str:
+    client, model = _get_client()
+    context = _build_repo_context(analysis)
+    response = client.chat.completions.create(
+        model=model,
+        max_tokens=2048,
+        messages=[
+            {"role": "system", "content": _SYSTEM_PROMPT},
+            {
+                "role": "user",
+                "content": (
+                    f"<repo_context>\n{context}\n</repo_context>\n\n"
+                    "Generate a new developer onboarding guide. Include:\n"
+                    "1. What this codebase does (1-2 sentences)\n"
+                    "2. Key abstractions to understand first\n"
+                    "3. Entry points — where to start reading\n"
+                    "4. Most important files and what each does\n"
+                    "5. Architectural patterns worth knowing\n"
+                    "6. Circular dependencies or tech debt to be aware of\n\n"
+                    "Be specific; reference actual file names."
+                ),
+            },
+        ],
+    )
+    return response.choices[0].message.content or ""

repolens/analyzer.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+from typing import Optional
+
+from .models import FileAnalysis, FileNode, FunctionNode
+
+
+# ── Python ────────────────────────────────────────────────────────────────────
+
+def _py_resolve(module: str, level: int, current_file: str, all_paths: set[str]) -> Optional[str]:
+    """Resolve a Python import to a repo-relative file path."""
+    parts = module.split(".") if module else []
+
+    if level > 0:
+        base = Path(current_file).parent
+        for _ in range(level - 1):
+            base = base.parent
+        candidate_parts = list(base.parts) + parts
+    else:
+        candidate_parts = parts
+
+    as_path = "/".join(candidate_parts)
+    for candidate in (f"{as_path}.py", f"{as_path}/__init__.py"):
+        if candidate in all_paths:
+            return candidate
+    return None
+
+
+def _call_name(node: ast.expr) -> Optional[str]:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        obj = _call_name(node.value)
+        return f"{obj}.{node.attr}" if obj else node.attr
+    return None
+
+
+def _analyze_python(file_node: FileNode, all_paths: set[str]) -> FileAnalysis:
+    fa = FileAnalysis(path=file_node.path, language="python")
+    if not file_node.content:
+        return fa
+    try:
+        tree = ast.parse(file_node.content, filename=file_node.path)
+    except SyntaxError:
+        return fa
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                fa.raw_imports.append(alias.name)
+                r = _py_resolve(alias.name, 0, file_node.path, all_paths)
+                if r:
+                    fa.resolved_imports.append(r)
+
+        elif isinstance(node, ast.ImportFrom):
+            module = node.module or ""
+            level = node.level
+            fa.raw_imports.append(("." * level) + module)
+            r = _py_resolve(module, level, file_node.path, all_paths)
+            if r:
+                fa.resolved_imports.append(r)
+
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            calls: list[str] = []
+            for child in ast.walk(node):
+                if child is node:
+                    continue
+                if isinstance(child, ast.Call):
+                    name = _call_name(child.func)
+                    if name:
+                        calls.append(name)
+            raw_doc = ast.get_docstring(node, clean=True)
+            # Trim to first paragraph so long docstrings don't flood the TUI
+            docstring = raw_doc.split("\n\n")[0].strip() if raw_doc else None
+            fa.functions.append(
+                FunctionNode(
+                    name=node.name,
+                    file_path=file_node.path,
+                    line_start=node.lineno,
+                    line_end=node.end_lineno or node.lineno,
+                    calls=calls,
+                    docstring=docstring,
+                )
+            )
+
+        elif isinstance(node, ast.ClassDef):
+            fa.classes.append(node.name)
+
+    return fa
+
+
+# ── JavaScript / TypeScript ───────────────────────────────────────────────────
+
+_JS_IMPORT_RE = re.compile(
+    r"""(?:
+        import\s+(?:[^'"]*?\s+from\s+)?['"]([^'"]+)['"]
+      | (?:require|import)\s*\(\s*['"]([^'"]+)['"]\s*\)
+      | export\s+[^'"]*?\s+from\s+['"]([^'"]+)['"]
+    )""",
+    re.VERBOSE | re.MULTILINE,
+)
+
+_JS_FUNC_RE = re.compile(
+    r"""(?:
+        (?:export\s+(?:default\s+)?)?(?:async\s+)?function\s+(\w+)\s*\(
+      | (?:export\s+)?const\s+(\w+)\s*=\s*(?:async\s*)?\(
+      | (?:export\s+)?const\s+(\w+)\s*=\s*(?:async\s+)?function
+    )""",
+    re.VERBOSE | re.MULTILINE,
+)
+
+# Matches /** ... */ JSDoc block immediately before a function
+_JSDOC_RE = re.compile(r'/\*\*(.*?)\*/', re.DOTALL)
+
+
+def _js_resolve(import_path: str, current_file: str, all_paths: set[str]) -> Optional[str]:
+    if not import_path.startswith("."):
+        return None
+    base = Path(current_file).parent
+    candidate = (base / import_path).as_posix()
+    for ext in ("", ".js", ".jsx", ".ts", ".tsx", "/index.js", "/index.ts", "/index.tsx"):
+        p = candidate + ext
+        if p in all_paths:
+            return p
+    return None
+
+
+def _analyze_js(file_node: FileNode, all_paths: set[str]) -> FileAnalysis:
+    fa = FileAnalysis(path=file_node.path, language=file_node.language)
+    if not file_node.content:
+        return fa
+    content = file_node.content
+
+    for m in _JS_IMPORT_RE.finditer(content):
+        raw = m.group(1) or m.group(2) or m.group(3)
+        if not raw:
+            continue
+        fa.raw_imports.append(raw)
+        r = _js_resolve(raw, file_node.path, all_paths)
+        if r:
+            fa.resolved_imports.append(r)
+
+    for m in _JS_FUNC_RE.finditer(content):
+        name = m.group(1) or m.group(2) or m.group(3)
+        if not name:
+            continue
+        line = content[: m.start()].count("\n") + 1
+        # Look for a JSDoc comment ending just before this function
+        preceding = content[: m.start()].rstrip()
+        jsdoc_match = _JSDOC_RE.search(preceding)
+        docstring: Optional[str] = None
+        if jsdoc_match and preceding.endswith("*/"):
+            raw = jsdoc_match.group(1)
+            # Strip leading " * " from each line and @param/@returns tags
+            lines = [re.sub(r'^\s*\*\s?', '', l) for l in raw.splitlines()]
+            desc_lines = [l for l in lines if l.strip() and not l.strip().startswith("@")]
+            if desc_lines:
+                docstring = " ".join(desc_lines).strip()
+        fa.functions.append(
+            FunctionNode(
+                name=name,
+                file_path=file_node.path,
+                line_start=line,
+                line_end=line,
+                docstring=docstring,
+            )
+        )
+    return fa
+
+
+# ── Go ────────────────────────────────────────────────────────────────────────
+
+_GO_IMPORT_BLOCK_RE = re.compile(r'import\s*\(([^)]+)\)', re.DOTALL)
+_GO_IMPORT_SINGLE_RE = re.compile(r'^import\s+"([^"]+)"', re.MULTILINE)
+_GO_FUNC_RE = re.compile(r'^func\s+(?:\([^)]+\)\s+)?(\w+)\s*\(', re.MULTILINE)
+
+
+def _analyze_go(file_node: FileNode, _all_paths: set[str]) -> FileAnalysis:
+    fa = FileAnalysis(path=file_node.path, language="go")
+    if not file_node.content:
+        return fa
+    content = file_node.content
+    for block in _GO_IMPORT_BLOCK_RE.findall(content):
+        for imp in re.findall(r'"([^"]+)"', block):
+            fa.raw_imports.append(imp)
+    for m in _GO_IMPORT_SINGLE_RE.finditer(content):
+        fa.raw_imports.append(m.group(1))
+    for m in _GO_FUNC_RE.finditer(content):
+        line = content[: m.start()].count("\n") + 1
+        fa.functions.append(
+            FunctionNode(name=m.group(1), file_path=file_node.path, line_start=line, line_end=line)
+        )
+    return fa
+
+
+# ── Rust ──────────────────────────────────────────────────────────────────────
+
+_RUST_USE_RE = re.compile(r'^use\s+([\w::{},\s*]+);', re.MULTILINE)
+_RUST_FN_RE = re.compile(r'^(?:pub\s+)?(?:async\s+)?fn\s+(\w+)\s*[\(<]', re.MULTILINE)
+
+
+def _analyze_rust(file_node: FileNode, _all_paths: set[str]) -> FileAnalysis:
+    fa = FileAnalysis(path=file_node.path, language="rust")
+    if not file_node.content:
+        return fa
+    content = file_node.content
+    for m in _RUST_USE_RE.finditer(content):
+        fa.raw_imports.append(m.group(1).strip())
+    for m in _RUST_FN_RE.finditer(content):
+        line = content[: m.start()].count("\n") + 1
+        fa.functions.append(
+            FunctionNode(name=m.group(1), file_path=file_node.path, line_start=line, line_end=line)
+        )
+    return fa
+
+
+# ── Dispatcher ────────────────────────────────────────────────────────────────
+
+def analyze_file(file_node: FileNode, all_paths: set[str]) -> FileAnalysis:
+    dispatch = {
+        "python": _analyze_python,
+        "javascript": _analyze_js,
+        "typescript": _analyze_js,
+        "go": _analyze_go,
+        "rust": _analyze_rust,
+    }
+    fn = dispatch.get(file_node.language)
+    if fn:
+        return fn(file_node, all_paths)
+    return FileAnalysis(path=file_node.path, language=file_node.language)
+
+
+def analyze_all(files: list[FileNode]) -> dict[str, FileAnalysis]:
+    all_paths = {f.path for f in files}
+    return {
+        f.path: analyze_file(f, all_paths)
+        for f in files
+        if f.content is not None
+    }

repolens/cli.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="repolens",
+        description="RepoLens — AI-native codebase intelligence",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Directory to analyse (default: current directory)",
+    )
+    parser.add_argument(
+        "--no-ai",
+        action="store_true",
+        help="Skip AI features",
+    )
+    parser.add_argument(
+        "--max-files",
+        type=int,
+        default=2000,
+        help="Max source files to scan (default: 2000)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output analysis as JSON instead of launching TUI",
+    )
+    args = parser.parse_args()
+
+    root = Path(args.path).resolve()
+    if not root.is_dir():
+        print(f"Error: {root} is not a directory.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"RepoLens  scanning {root} …")
+
+    try:
+        from dotenv import load_dotenv
+        load_dotenv()
+    except ImportError:
+        pass
+
+    from repolens.scanner import scan
+    from repolens.analyzer import analyze_all
+    from repolens.graph import build_graph
+    from repolens.models import RepoAnalysis
+
+    print("  Walking directory tree…")
+    files = scan(str(root), max_files=args.max_files)
+    print(f"  Found {len(files)} source files.")
+
+    print("  Analysing imports and functions…")
+    file_analyses = analyze_all(files)
+    print(f"  Analysed {len(file_analyses)} files.")
+
+    print("  Building dependency and call graphs…")
+    stats = build_graph(file_analyses)
+
+    analysis = RepoAnalysis(
+        root=str(root),
+        files=files,
+        file_analyses=file_analyses,
+        stats=stats,
+    )
+
+    n_cycles = len(stats.circular_deps)
+    print(f"  Done. {len(stats.functions)} functions  ·  {n_cycles} circular dep(s)")
+
+    if args.json:
+        _print_json(analysis)
+        return
+
+    print("  Launching TUI…\n")
+    from repolens.tui.app import RepoLensApp
+    app = RepoLensApp(analysis)
+    app.run()
+
+
+def _print_json(analysis: "RepoAnalysis") -> None:
+    import json
+
+    stats = analysis.stats
+    output = {
+        "root": analysis.root,
+        "total_files": len(analysis.files),
+        "files": [
+            {"path": f.path, "language": f.language, "size": f.size}
+            for f in analysis.files
+        ],
+        "import_graph": {k: v for k, v in stats.import_edges.items() if v},
+        "circular_deps": stats.circular_deps,
+        "hub_files": [{"path": p, "in_degree": d} for p, d in stats.hub_files],
+        "entry_points": stats.entry_points,
+        "functions": [
+            {
+                "id": fid,
+                "name": fn.name,
+                "file": fn.file_path,
+                "line": fn.line_start,
+                "calls": fn.calls,
+                "callers": fn.callers,
+            }
+            for fid, fn in stats.functions.items()
+        ],
+    }
+    print(json.dumps(output, indent=2))
+
+
+if __name__ == "__main__":
+    main()