contextl 1.0.1

package/python/mcp_server.py

@@ -0,0 +1,201 @@
+"""
+Repository Intelligence Engine — Universal MCP Server
+
+Exposes the engine as an MCP (Model Context Protocol) server over stdio.
+Works with any MCP-compatible IDE: Cursor, Windsurf, Claude Code, VS Code, etc.
+
+The IDE launches this script automatically when it needs it.
+No manual server to keep running.
+
+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
+"""
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+import mcp.types as types
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+# Make sure the engine modules are importable from the same directory
+sys.path.insert(0, str(Path(__file__).parent))
+
+from scanner import scan_repo
+from import_parser import parse_imports
+from graph_builder import build_graph
+from query_engine import query as engine_query
+from main import _confidence, _reasoning
+
+
+# ---------------------------------------------------------------------------
+# Server setup
+# ---------------------------------------------------------------------------
+server = Server("repo-intelligence")
+
+
+# ---------------------------------------------------------------------------
+# Tool definitions
+# ---------------------------------------------------------------------------
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="query_repo",
+            description=(
+                "Find the most relevant files in a code repository for a given "
+                "change request or natural-language query. "
+                "Returns a ranked list of files with relevance scores, confidence "
+                "levels, matched terms, and a one-line reasoning string. "
+                "Use this before editing code to identify exactly which files need "
+                "to change — avoids reading irrelevant files."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "repo_path": {
+                        "type": "string",
+                        "description": "Absolute or relative path to the repository root.",
+                    },
+                    "query": {
+                        "type": "string",
+                        "description": (
+                            "Natural-language description of the change you want to make. "
+                            "Examples: 'fix the upload error handler', "
+                            "'change the login page logo', 'add dark mode to footer'."
+                        ),
+                    },
+                    "top_n": {
+                        "type": "integer",
+                        "description": "Maximum number of files to return (default: 5, max: 20).",
+                        "default": 5,
+                        "minimum": 1,
+                        "maximum": 20,
+                    },
+                },
+                "required": ["repo_path", "query"],
+            },
+        ),
+        types.Tool(
+            name="scan_repo",
+            description=(
+                "Scan a repository and list all source files the engine can see. "
+                "Useful for understanding the repository structure before querying. "
+                "Returns file paths, extensions, and sizes."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "repo_path": {
+                        "type": "string",
+                        "description": "Absolute or relative path to the repository root.",
+                    },
+                },
+                "required": ["repo_path"],
+            },
+        ),
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Tool handlers
+# ---------------------------------------------------------------------------
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
+
+    if name == "query_repo":
+        return await _handle_query(arguments)
+
+    if name == "scan_repo":
+        return await _handle_scan(arguments)
+
+    return [types.TextContent(
+        type="text",
+        text=json.dumps({"error": f"Unknown tool: {name}"}),
+    )]
+
+
+async def _handle_query(args: dict) -> list[types.TextContent]:
+    repo_path = args.get("repo_path", "")
+    query_str = args.get("query", "")
+    top_n = min(int(args.get("top_n", 5)), 20)
+
+    # Run the engine (synchronous — wrap in thread to stay async-safe)
+    loop = asyncio.get_event_loop()
+    try:
+        result = await loop.run_in_executor(None, _run_query, repo_path, query_str, top_n)
+    except Exception as e:
+        result = {"error": str(e), "query": query_str, "repo": repo_path, "results": []}
+
+    return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+
+
+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)
+    ranked = engine_query(query_str, repo_graph, top_n=top_n)
+
+    return {
+        "query": query_str,
+        "repo": scan.root,
+        "total_files_scanned": scan.total_files,
+        "results": [
+            {
+                "rank": i + 1,
+                "path": r.path,
+                "score": round(r.total_score, 4),
+                "confidence": _confidence(r.total_score),
+                "matched_terms": sorted(r.matched_terms),
+                "reasoning": _reasoning(r, repo_graph),
+            }
+            for i, r in enumerate(ranked)
+        ],
+    }
+
+
+async def _handle_scan(args: dict) -> list[types.TextContent]:
+    repo_path = args.get("repo_path", "")
+
+    loop = asyncio.get_event_loop()
+    try:
+        result = await loop.run_in_executor(None, _run_scan, repo_path)
+    except Exception as e:
+        result = {"error": str(e), "repo": repo_path}
+
+    return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+
+
+def _run_scan(repo_path: str) -> dict:
+    scan = scan_repo(repo_path)
+    return {
+        "repo": scan.root,
+        "total_files": scan.total_files,
+        "files": [
+            {"path": f.path, "extension": f.extension, "size_bytes": f.size_bytes}
+            for f in scan.files
+        ],
+    }
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+async def main():
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options(),
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/python/query_engine.py

@@ -0,0 +1,252 @@
+"""
+Repository Intelligence Engine
+Step 4: Query Engine
+
+Accepts a natural-language query and ranks files by relevance using:
+
+  1. Keyword match score  — does the filename / path contain query terms?
+  2. Content match score  — do the file's contents mention query terms?
+  3. Graph neighbor bonus — if a high-scoring file is nearby in the graph,
+                            its neighbors get a proximity boost
+  4. Centrality weight    — more connected files rank slightly higher when
+                            scores are otherwise equal
+
+No LLM. No embeddings. Pure text + graph.
+"""
+
+import re
+from dataclasses import dataclass, field
+
+from scanner import scan_repo
+from import_parser import parse_imports
+from graph_builder import build_graph, RepoGraph
+
+
+# ---------------------------------------------------------------------------
+# Stop words — stripped from queries before matching
+# ---------------------------------------------------------------------------
+STOP_WORDS = {
+    "a", "an", "the", "in", "on", "at", "to", "for", "of", "and",
+    "or", "is", "it", "this", "that", "with", "from", "how", "what",
+    "where", "when", "which", "who", "make", "change", "update", "fix",
+    "add", "remove", "edit", "modify", "the", "my", "our", "i", "we",
+}
+
+
+@dataclass
+class RankedFile:
+    """A file with its relevance score and scoring breakdown."""
+    path: str
+    total_score: float
+    keyword_score: float   # path/filename match
+    content_score: float   # file content match
+    neighbor_bonus: float  # proximity to other high-scoring files
+    centrality: float      # PageRank weight
+    matched_terms: list[str] = field(default_factory=list)
+
+    def explain(self) -> str:
+        terms = ", ".join(self.matched_terms) if self.matched_terms else "none"
+        return (
+            f"  {self.path}\n"
+            f"    score={self.total_score:.4f}  "
+            f"keyword={self.keyword_score:.3f}  "
+            f"content={self.content_score:.3f}  "
+            f"neighbor={self.neighbor_bonus:.3f}  "
+            f"centrality={self.centrality:.4f}\n"
+            f"    matched terms: {terms}"
+        )
+
+
+def _tokenize(text: str) -> list[str]:
+    """Lowercase, split on non-alphanumeric, remove stop words."""
+    tokens = re.findall(r"[a-z0-9]+", text.lower())
+    return [t for t in tokens if t not in STOP_WORDS and len(t) > 1]
+
+
+def _path_tokens(path: str) -> list[str]:
+    """Extract meaningful tokens from a file path."""
+    # Split on slashes, dots, camelCase, kebab-case, underscores
+    parts = re.split(r"[/\\.]", path)
+    tokens = []
+    for part in parts:
+        # Split camelCase: LoginHeader → login, header
+        sub = re.sub(r"([A-Z])", r" \1", part).lower()
+        tokens.extend(re.findall(r"[a-z0-9]+", sub))
+    return [t for t in tokens if t not in STOP_WORDS and len(t) > 1]
+
+
+def _keyword_score(query_terms: list[str], file_path: str) -> tuple[float, list[str]]:
+    """
+    Score how well query terms match the file path / name.
+    Filename matches score higher than directory matches.
+    """
+    path_toks = _path_tokens(file_path)
+    filename_toks = _path_tokens(file_path.split("/")[-1])
+
+    matched = []
+    score = 0.0
+
+    for term in query_terms:
+        if term in filename_toks:
+            score += 1.0   # Strong signal: term in filename
+            matched.append(term)
+        elif term in path_toks:
+            score += 0.4   # Weaker signal: term in directory path
+            if term not in matched:
+                matched.append(term)
+
+    # Normalize by number of query terms
+    if query_terms:
+        score = score / len(query_terms)
+
+    return score, matched
+
+
+def _content_score(query_terms: list[str], file_path: str) -> tuple[float, list[str]]:
+    """
+    Score how often query terms appear in the file's source code.
+    Uses term frequency, capped to avoid huge files dominating.
+    """
+    try:
+        content = open(file_path, encoding="utf-8").read().lower()
+    except Exception:
+        return 0.0, []
+
+    content_tokens = set(re.findall(r"[a-z0-9]+", content))
+    matched = [t for t in query_terms if t in content_tokens]
+
+    if not query_terms:
+        return 0.0, []
+
+    score = len(matched) / len(query_terms)
+    return score, matched
+
+
+def _apply_neighbor_bonus(
+    scores: dict[str, float],
+    repo_graph: RepoGraph,
+    boost: float = 0.15,
+    depth: int = 1,
+) -> dict[str, float]:
+    """
+    Files neighbouring high-scoring files get a proximity boost.
+    Runs one pass: find top scorers, boost their graph neighbors.
+    """
+    if not scores:
+        return scores
+
+    max_score = max(scores.values()) or 1.0
+    boosted = dict(scores)
+
+    for path, score in scores.items():
+        # Only propagate from files with meaningful scores
+        if score < 0.1:
+            continue
+
+        neighbors = repo_graph.get_neighbors(path, depth=depth)
+        for neighbor in neighbors:
+            if neighbor in boosted:
+                # Boost proportional to how strong the source signal is
+                boosted[neighbor] += boost * (score / max_score)
+
+    return boosted
+
+
+def query(
+    q: str,
+    repo_graph: RepoGraph,
+    top_n: int = 10,
+) -> list[RankedFile]:
+    """
+    Rank all files in the repository by relevance to a natural-language query.
+
+    Args:
+        q:          Natural-language query string.
+        repo_graph: Built graph from build_graph().
+        top_n:      Maximum number of results to return.
+
+    Returns:
+        List of RankedFile sorted by total_score descending.
+    """
+    query_terms = _tokenize(q)
+
+    if not query_terms:
+        return []
+
+    # --- Pass 1: keyword + content scores per file ---
+    keyword_scores: dict[str, float] = {}
+    content_scores: dict[str, float] = {}
+    matched_terms: dict[str, list[str]] = {}
+
+    for path, node in repo_graph.nodes.items():
+        kscore, kterms = _keyword_score(query_terms, path)
+        cscore, cterms = _content_score(query_terms, node.path if hasattr(node, "absolute_path") else
+                                        str(__import__("pathlib").Path(repo_graph.root) / path))
+
+        keyword_scores[path] = kscore
+        content_scores[path] = cscore
+        matched_terms[path] = list(set(kterms + cterms))
+
+    # --- Pass 2: combine into base score ---
+    base_scores: dict[str, float] = {}
+    for path in repo_graph.nodes:
+        base_scores[path] = (
+            keyword_scores.get(path, 0.0) * 0.5 +
+            content_scores.get(path, 0.0) * 0.5
+        )
+
+    # --- Pass 3: neighbor bonus ---
+    boosted_scores = _apply_neighbor_bonus(base_scores, repo_graph)
+
+    # --- Pass 4: centrality tiebreaker ---
+    results = []
+    for path, node in repo_graph.nodes.items():
+        neighbor_bonus = boosted_scores[path] - base_scores[path]
+        total = boosted_scores[path] + node.centrality * 0.05
+
+        results.append(RankedFile(
+            path=path,
+            total_score=total,
+            keyword_score=keyword_scores.get(path, 0.0),
+            content_score=content_scores.get(path, 0.0),
+            neighbor_bonus=neighbor_bonus,
+            centrality=node.centrality,
+            matched_terms=matched_terms.get(path, []),
+        ))
+
+    # Sort by total score descending
+    results.sort(key=lambda r: r.total_score, reverse=True)
+
+    # Return only files with non-zero score, up to top_n
+    return [r for r in results if r.total_score > 0.01][:top_n]
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 3:
+        print("Usage: python query_engine.py <repo_path> '<query>'")
+        print("Example: python query_engine.py ../Lazy-Footers 'change the download button'")
+        sys.exit(1)
+
+    target = sys.argv[1]
+    user_query = sys.argv[2]
+
+    print(f"Query: '{user_query}'")
+    print(f"Repo:  {target}")
+    print()
+
+    scan = scan_repo(target)
+    parse = parse_imports(scan)
+    repo_graph = build_graph(scan, parse)
+
+    ranked = query(user_query, repo_graph)
+
+    if not ranked:
+        print("No relevant files found.")
+    else:
+        print(f"Top {len(ranked)} relevant files:\n")
+        for i, result in enumerate(ranked, 1):
+            print(f"{i}.")
+            print(result.explain())
+            print()

package/python/scanner.py

@@ -0,0 +1,125 @@
+"""
+Repository Intelligence Engine
+Step 1: Repository Scanner
+
+Walks a repository and discovers all relevant source files.
+Filters by supported extensions for the MVP (Next.js / React / TypeScript).
+"""
+
+import os
+from pathlib import Path
+from dataclasses import dataclass, field
+
+
+SUPPORTED_EXTENSIONS = {".tsx", ".ts", ".jsx", ".js"}
+
+IGNORED_DIRS = {
+    "node_modules",
+    ".git",
+    ".next",
+    "dist",
+    "build",
+    ".cache",
+    "__pycache__",
+    ".turbo",
+    "coverage",
+}
+
+
+@dataclass
+class ScannedFile:
+    """Represents a single discovered file in the repository."""
+    path: str           # Relative path from repo root
+    absolute_path: str  # Full path on disk
+    extension: str      # File extension
+    size_bytes: int     # File size
+
+
+@dataclass
+class ScanResult:
+    """Result of scanning an entire repository."""
+    root: str
+    files: list[ScannedFile] = field(default_factory=list)
+
+    @property
+    def total_files(self) -> int:
+        return len(self.files)
+
+    def summary(self) -> str:
+        ext_counts: dict[str, int] = {}
+        for f in self.files:
+            ext_counts[f.extension] = ext_counts.get(f.extension, 0) + 1
+
+        lines = [
+            f"Repository: {self.root}",
+            f"Total files: {self.total_files}",
+            "",
+            "By extension:",
+        ]
+        for ext, count in sorted(ext_counts.items()):
+            lines.append(f"  {ext:8s}  {count} file{'s' if count != 1 else ''}")
+
+        return "\n".join(lines)
+
+
+def scan_repo(repo_path: str) -> ScanResult:
+    """
+    Walk the repository at repo_path and return a ScanResult
+    containing all discovered source files.
+
+    Args:
+        repo_path: Path to the repository root (absolute or relative).
+
+    Returns:
+        ScanResult with all discovered files.
+
+    Raises:
+        ValueError: If repo_path does not exist or is not a directory.
+    """
+    root = Path(repo_path).resolve()
+
+    if not root.exists():
+        raise ValueError(f"Path does not exist: {root}")
+    if not root.is_dir():
+        raise ValueError(f"Path is not a directory: {root}")
+
+    result = ScanResult(root=str(root))
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Prune ignored directories in-place so os.walk skips them
+        dirnames[:] = [d for d in dirnames if d not in IGNORED_DIRS]
+
+        for filename in filenames:
+            filepath = Path(dirpath) / filename
+            ext = filepath.suffix.lower()
+
+            if ext not in SUPPORTED_EXTENSIONS:
+                continue
+
+            relative = filepath.relative_to(root)
+            result.files.append(
+                ScannedFile(
+                    path=str(relative),
+                    absolute_path=str(filepath),
+                    extension=ext,
+                    size_bytes=filepath.stat().st_size,
+                )
+            )
+
+    # Sort by path for deterministic output
+    result.files.sort(key=lambda f: f.path)
+
+    return result
+
+
+if __name__ == "__main__":
+    import sys
+
+    target = sys.argv[1] if len(sys.argv) > 1 else "."
+    result = scan_repo(target)
+
+    print(result.summary())
+    print()
+    print("Discovered files:")
+    for f in result.files:
+        print(f"  {f.path}  ({f.size_bytes} bytes)")