contextl 1.2.12 → 1.2.14

package/python/main.py

@@ -212,13 +212,20 @@ def build_parser() -> argparse.ArgumentParser:
     obsidian_parser.add_argument("repo_path", help="Path to the repository root")
     obsidian_parser.add_argument("output_dir", help="Absolute path to save the Obsidian markdown files")
 
+    # 5. Git Review
+    review_parser = subparsers.add_parser("review", help="Build AI-ready context from your git changes")
+    review_parser.add_argument("repo_path", help="Path to the repository root (must be a git repo)")
+    review_parser.add_argument("--staged", action="store_true", help="Only include staged changes")
+    review_parser.add_argument("--unstaged", action="store_true", help="Only include unstaged changes")
+    review_parser.add_argument("--json", action="store_true", help="Output clean JSON instead of human-readable text")
+
     return parser
 
 
 def main():
     # To maintain backward compatibility with old `contextl <repo> <query>`
     # we manually inject "search" if the first argument isn't a known command.
-    if len(sys.argv) >= 2 and sys.argv[1] not in ["search", "standalone", "impact", "obsidian", "-h", "--help"]:
+    if len(sys.argv) >= 2 and sys.argv[1] not in ["search", "standalone", "impact", "obsidian", "review", "-h", "--help"]:
         sys.argv.insert(1, "search")
 
     parser = build_parser()
@@ -276,6 +283,33 @@ def main():
         print(f"Obsidian Vault successfully generated at: {vault_path}")
         print("Open this folder in Obsidian to view your codebase graph!")
 
+    elif args.command == "review":
+        from git_review import _is_git_repo, get_changed_files, build_review_context, format_review_human, format_review_json
+
+        if not _is_git_repo(args.repo_path):
+            print(f"Error: '{args.repo_path}' is not a git repository.", file=sys.stderr)
+            sys.exit(1)
+
+        # Default: both staged + unstaged unless a flag is explicitly set
+        include_staged   = args.staged or (not args.staged and not args.unstaged)
+        include_unstaged = args.unstaged or (not args.staged and not args.unstaged)
+
+        staged, unstaged = get_changed_files(args.repo_path, include_staged, include_unstaged)
+
+        if not staged and not unstaged:
+            print("No changed files found. Make some edits and try again.")
+            sys.exit(0)
+
+        scan = scan_repo(args.repo_path)
+        parse = parse_imports(scan)
+        repo_graph = build_graph(scan, parse)
+        ctx = build_review_context(args.repo_path, staged, unstaged, repo_graph)
+
+        if args.json:
+            print(format_review_json(ctx))
+        else:
+            print(format_review_human(ctx))
+
 
 if __name__ == "__main__":
     main()

package/python/mcp_server.py

@@ -11,16 +11,27 @@ Usage (the IDE does this for you, but you can test manually):
     python mcp_server.py
 
 Tools exposed:
-    query_repo      — rank files by relevance to a natural-language query
-    scan_repo       — list all source files the engine can see in a repo
-    analyze_impact  — find every file affected by changing a target file
+    query_repo             — rank files by relevance to a natural-language query
+    scan_repo              — list all source files the engine can see in a repo
+    analyze_impact         — find every file affected by changing a target file
+    find_standalone_files  — find unimported files with in-degree 0
+    export_obsidian_vault  — export repo graph to an Obsidian markdown vault
+
+Performance:
+    A shared graph cache is maintained per repo path + file mtime fingerprint.
+    The 4-step build pipeline (scan → parse → graph → query) runs ONCE per
+    session and is reused by all tool calls. Subsequent calls on an unchanged
+    repo return from cache in <1ms.
 """
 
-import argparse
 import asyncio
 import json
+import os
 import sys
+import threading
+from dataclasses import dataclass
 from pathlib import Path
+from typing import Optional
 
 import mcp.types as types
 from mcp.server import Server
@@ -37,6 +48,78 @@ from main import _confidence, _reasoning
 from impact_analysis import analyze_impact
 from standalone import find_standalone_files
 from obsidian_export import export_obsidian_vault
+from git_review import _is_git_repo, get_changed_files, build_review_context, format_review_json
+from import_parser import extract_skeleton
+
+
+# ---------------------------------------------------------------------------
+# Shared graph cache — one pipeline build per repo per session
+# ---------------------------------------------------------------------------
+@dataclass
+class _CacheEntry:
+    repo_path: str          # resolved absolute path
+    mtime_hash: float       # max mtime across all source files at build time
+    scan: object            # ScanResult
+    repo_graph: object      # RepoGraph
+
+
+_cache_lock = threading.Lock()
+_cache: Optional[_CacheEntry] = None
+
+
+def _compute_mtime_hash(repo_path: str) -> float:
+    """Walk repo_path and return the maximum file modification time."""
+    max_mtime = 0.0
+    for dirpath, _, filenames in os.walk(repo_path):
+        # Skip hidden dirs and common noise dirs
+        dirpath_obj = Path(dirpath)
+        if any(part.startswith(".") or part in ("node_modules", "__pycache__", ".git", "dist", "build", "target")
+               for part in dirpath_obj.parts):
+            continue
+        for fname in filenames:
+            try:
+                mtime = os.path.getmtime(os.path.join(dirpath, fname))
+                if mtime > max_mtime:
+                    max_mtime = mtime
+            except OSError:
+                pass
+    return max_mtime
+
+
+def _get_graph(repo_path: str):
+    """
+    Return (scan, repo_graph) for the given repo_path.
+
+    On first call (or after any source file changes): runs the full
+    4-step pipeline and stores the result in the module-level cache.
+    On subsequent calls with unchanged files: returns instantly from cache.
+    """
+    global _cache
+
+    resolved = str(Path(repo_path).resolve())
+    mtime_hash = _compute_mtime_hash(resolved)
+
+    with _cache_lock:
+        if (_cache is not None
+                and _cache.repo_path == resolved
+                and _cache.mtime_hash == mtime_hash):
+            print("[contextl] graph cache hit", file=sys.stderr, flush=True)
+            return _cache.scan, _cache.repo_graph
+
+        # Cache miss — build the pipeline
+        print("[contextl] building graph...", file=sys.stderr, flush=True)
+        scan = scan_repo(resolved)
+        parse = parse_imports(scan)
+        repo_graph = build_graph(scan, parse)
+
+        _cache = _CacheEntry(
+            repo_path=resolved,
+            mtime_hash=mtime_hash,
+            scan=scan,
+            repo_graph=repo_graph,
+        )
+        print(f"[contextl] graph built: {scan.total_files} files", file=sys.stderr, flush=True)
+        return scan, repo_graph
 
 
 # ---------------------------------------------------------------------------
@@ -185,6 +268,60 @@ async def list_tools() -> list[types.Tool]:
                 "required": ["repo_path", "output_dir"],
             },
         ),
+        types.Tool(
+            name="review_changes",
+            description=(
+                "Git-aware context builder. Reads the current git diff (staged and/or "
+                "unstaged) to find what files you are editing, then automatically runs "
+                "impact analysis on each changed file to find every file that depends on "
+                "your changes. Returns a structured context bundle containing: the changed "
+                "files, their full blast radius (direct + transitive dependents), and a "
+                "list of test files that should be re-run. Use this at the START of any "
+                "code review or refactor session to instantly understand the full scope "
+                "of your changes before touching anything."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "repo_path": {
+                        "type": "string",
+                        "description": "Absolute or relative path to the git repository root.",
+                    },
+                    "staged": {
+                        "type": "boolean",
+                        "description": "Include staged changes (git diff --cached). Default true.",
+                        "default": True,
+                    },
+                    "unstaged": {
+                        "type": "boolean",
+                        "description": "Include unstaged working-tree changes (git diff). Default true.",
+                        "default": True,
+                    },
+                },
+                "required": ["repo_path"],
+            },
+        ),
+        types.Tool(
+            name="get_skeleton",
+            description=(
+                "Extract the structural skeleton (API surface) of a source file — all "
+                "class names, method signatures, function signatures, return types, and "
+                "docstrings — without any implementation bodies. "
+                "Use this when you need to understand a file's API without consuming its "
+                "full token count. A 5,000-line file becomes a ~100-line reference header. "
+                "Supports: Python, TypeScript, JavaScript, TSX, JSX, Java, Rust."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "file_path": {
+                        "type": "string",
+                        "description": "Absolute path to the source file to extract the skeleton from.",
+                    },
+                },
+                "required": ["file_path"],
+            },
+        ),
     ]
 
 
@@ -209,6 +346,12 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
     if name == "export_obsidian_vault":
         return await _handle_export_obsidian(arguments)
 
+    if name == "review_changes":
+        return await _handle_review_changes(arguments)
+
+    if name == "get_skeleton":
+        return await _handle_get_skeleton(arguments)
+
     return [types.TextContent(
         type="text",
         text=json.dumps({"error": f"Unknown tool: {name}"}),
@@ -231,10 +374,8 @@ async def _handle_query(args: dict) -> list[types.TextContent]:
 
 
 def _run_query(repo_path: str, query_str: str, top_n: int) -> dict:
-    """Synchronous pipeline — called from a thread executor."""
-    scan = scan_repo(repo_path)
-    parse = parse_imports(scan)
-    repo_graph = build_graph(scan, parse)
+    """Uses cached graph — pipeline runs only on first call or after file changes."""
+    scan, repo_graph = _get_graph(repo_path)
     ranked = engine_query(query_str, repo_graph, top_n=top_n)
 
     return {
@@ -268,7 +409,8 @@ async def _handle_scan(args: dict) -> list[types.TextContent]:
 
 
 def _run_scan(repo_path: str) -> dict:
-    scan = scan_repo(repo_path)
+    """Uses cached graph — pipeline runs only on first call or after file changes."""
+    scan, _ = _get_graph(repo_path)
     return {
         "repo": scan.root,
         "total_files": scan.total_files,
@@ -294,10 +436,8 @@ async def _handle_impact(args: dict) -> list[types.TextContent]:
 
 
 def _run_impact(repo_path: str, target_file: str, max_depth: int) -> dict:
-    """Synchronous pipeline — called from a thread executor."""
-    scan = scan_repo(repo_path)
-    parse = parse_imports(scan)
-    repo_graph = build_graph(scan, parse)
+    """Uses cached graph — pipeline runs only on first call or after file changes."""
+    scan, repo_graph = _get_graph(repo_path)
     report = analyze_impact(target_file, repo_graph, max_depth=max_depth)
 
     return {
@@ -334,10 +474,8 @@ async def _handle_standalone_files(args: dict) -> list[types.TextContent]:
 
 
 def _run_standalone_files(repo_path: str) -> dict:
-    """Synchronous pipeline — called from a thread executor."""
-    scan = scan_repo(repo_path)
-    parse = parse_imports(scan)
-    repo_graph = build_graph(scan, parse)
+    """Uses cached graph — pipeline runs only on first call or after file changes."""
+    scan, repo_graph = _get_graph(repo_path)
     standalone_files = find_standalone_files(repo_graph)
 
     return {
@@ -362,13 +500,10 @@ async def _handle_export_obsidian(args: dict) -> list[types.TextContent]:
 
 
 def _run_export_obsidian(repo_path: str, output_dir: str) -> dict:
-    """Synchronous pipeline — called from a thread executor."""
-    scan = scan_repo(repo_path)
-    parse = parse_imports(scan)
-    repo_graph = build_graph(scan, parse)
-    
+    """Uses cached graph — pipeline runs only on first call or after file changes."""
+    scan, repo_graph = _get_graph(repo_path)
     vault_path = export_obsidian_vault(repo_graph, output_dir)
-    
+
     return {
         "repo": scan.root,
         "vault_path": vault_path,
@@ -377,6 +512,57 @@ def _run_export_obsidian(repo_path: str, output_dir: str) -> dict:
     }
 
 
+async def _handle_review_changes(args: dict) -> list[types.TextContent]:
+    repo_path = args.get("repo_path", "")
+    include_staged   = bool(args.get("staged", True))
+    include_unstaged = bool(args.get("unstaged", True))
+
+    loop = asyncio.get_event_loop()
+    try:
+        result = await loop.run_in_executor(
+            None, _run_review_changes, repo_path, include_staged, include_unstaged
+        )
+    except Exception as e:
+        result = {"error": str(e), "repo": repo_path}
+
+    return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+
+
+def _run_review_changes(repo_path: str, include_staged: bool, include_unstaged: bool) -> dict:
+    """Uses cached graph — builds review context from current git diff."""
+    import json as _json
+
+    if not _is_git_repo(repo_path):
+        return {"error": f"'{repo_path}' is not a git repository."}
+
+    staged, unstaged = get_changed_files(repo_path, include_staged, include_unstaged)
+
+    if not staged and not unstaged:
+        return {
+            "repo": repo_path,
+            "message": "No changed files found.",
+            "changed_files": [],
+            "all_affected": [],
+            "suggested_tests": [],
+        }
+
+    _, repo_graph = _get_graph(repo_path)
+    ctx = build_review_context(repo_path, staged, unstaged, repo_graph)
+    return _json.loads(format_review_json(ctx))
+
+
+async def _handle_get_skeleton(args: dict) -> list[types.TextContent]:
+    file_path = args.get("file_path", "")
+
+    loop = asyncio.get_event_loop()
+    try:
+        result = await loop.run_in_executor(None, extract_skeleton, file_path)
+    except Exception as e:
+        result = {"error": str(e), "file": file_path}
+
+    return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+
+
 # ---------------------------------------------------------------------------
 # Entry point
 # ---------------------------------------------------------------------------