contextl 1.0.1

package/README.md

@@ -0,0 +1,132 @@
+# contextl
+
+> **Context-selection engine for AI coding assistants.**  
+> Finds the most relevant files in your codebase for a natural-language change request — no LLM, no embeddings, no vector database. Pure graph + text scoring.
+
+```
+"fix the upload error" → [FileUploader.tsx, lib/upload.ts, UploadSection.tsx]
+```
+
+Instead of feeding your entire repo to an AI, `contextl` reduces 5 000 files down to the 5 most relevant ones in milliseconds.
+
+---
+
+## Quick start
+
+**Requires Python 3.9+** on your PATH. Everything else (`networkx`, `mcp`) is installed automatically on first run.
+
+### 1 — Add to your IDE's MCP config
+
+Paste this JSON into your IDE's MCP config file (paths listed below):
+
+```json
+{
+  "mcpServers": {
+    "contextl": {
+      "command": "npx",
+      "args": ["-y", "contextl"]
+    }
+  }
+}
+```
+
+#### Config file locations
+
+| IDE | Config file |
+|-----|-------------|
+| **Antigravity** | `~/.gemini/antigravity/mcp/` (MCP server directory) |
+| **Cursor** | `~/.cursor/mcp.json` |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
+| **Claude Code** | `~/.claude.json` (or run `claude mcp add`) |
+| **VS Code** | `.vscode/mcp.json` in your workspace root |
+
+### 2 — Use it
+
+Just talk to your IDE's AI normally:
+
+```
+You:  "fix the file upload error handler"
+IDE:  calls query_repo → gets [FileUploader.tsx, lib/upload.ts, …]
+IDE:  reads only those 5 files instead of the whole repo
+```
+
+---
+
+## Tools exposed
+
+### `query_repo(repo_path, query, top_n?)`
+
+Ranks the most relevant files for a change request.
+
+**Parameters:**
+- `repo_path` — absolute path to the repository root
+- `query` — natural-language description of the change (e.g. `"change the download button color"`)
+- `top_n` — max results to return (default `5`, max `20`)
+
+**Returns:**
+```json
+{
+  "query": "change the download button",
+  "repo": "/path/to/repo",
+  "total_files_scanned": 142,
+  "results": [
+    {
+      "rank": 1,
+      "path": "components/DownloadButton.tsx",
+      "score": 0.9800,
+      "confidence": "high",
+      "matched_terms": ["button", "download"],
+      "reasoning": "Filename strongly matches query terms; file contents heavily reference query terms."
+    }
+  ]
+}
+```
+
+### `scan_repo(repo_path)`
+
+Lists all source files the engine can see in a repository. Useful for verifying coverage before querying.
+
+**Returns:**
+```json
+{
+  "repo": "/path/to/repo",
+  "total_files": 142,
+  "files": [
+    { "path": "components/Button.tsx", "extension": ".tsx", "size_bytes": 1024 }
+  ]
+}
+```
+
+---
+
+## How it works
+
+The engine runs **entirely locally** — no network calls, no AI APIs, no data leaves your machine.
+
+Scoring uses four signals:
+
+| Signal | Weight | Description |
+|--------|--------|-------------|
+| Keyword match | 0.5 | Query terms in the file path / name |
+| Content match | 0.5 | Query terms inside the file source |
+| Neighbor bonus | +0.15 | Files near high-scoring files in the import graph |
+| PageRank | 0.05 | Tiebreaker: more connected files rank slightly higher |
+
+Supports **Next.js / React / TypeScript** repos (`.ts`, `.tsx`, `.js`, `.jsx`). Automatically detects `@/` path aliases from `tsconfig.json`.
+
+---
+
+## Requirements
+
+| Requirement | Version |
+|-------------|---------|
+| Node.js | ≥ 18 |
+| Python | ≥ 3.9 |
+| `networkx` | auto-installed |
+| `mcp` | auto-installed |
+
+---
+
+## License
+
+MIT

package/bin/contextl.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * contextl — npm entry point
+ *
+ * Locates a suitable Python 3.9+ interpreter, ensures `networkx` and `mcp`
+ * are importable (installs them via pip if missing), then spawns mcp_server.py
+ * with stdio inherited so any MCP-compatible IDE can talk to it directly.
+ *
+ * No npm runtime dependencies — only Node.js built-ins.
+ */
+
+"use strict";
+
+const { execSync, spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+/** Directory containing the bundled Python engine files. */
+const PYTHON_DIR = path.resolve(__dirname, "..", "python");
+
+/** The MCP server entry point. */
+const MCP_SERVER = path.join(PYTHON_DIR, "mcp_server.py");
+
+// ---------------------------------------------------------------------------
+// Python discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * Try to find a Python 3.9+ interpreter.
+ * Tries the candidates in order; returns the first one that works.
+ * Throws if none is found.
+ */
+function findPython() {
+  const candidates = ["python3", "python", "python3.13", "python3.12", "python3.11", "python3.10", "python3.9"];
+
+  for (const cmd of candidates) {
+    try {
+      const raw = execSync(
+        `${cmd} -c "import sys; print(sys.version_info.major, sys.version_info.minor)"`,
+        { stdio: ["pipe", "pipe", "pipe"], timeout: 5000 }
+      ).toString().trim();
+
+      const [major, minor] = raw.split(" ").map(Number);
+      if (major === 3 && minor >= 9) {
+        return cmd;
+      }
+    } catch {
+      // Not found or wrong version — try next candidate
+    }
+  }
+
+  throw new Error(
+    "Python 3.9+ is required but was not found.\n" +
+    "Install it from https://www.python.org/downloads/ and make sure it is on your PATH."
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Dependency check & auto-install
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a Python package is importable.
+ * Returns true if it can be imported, false otherwise.
+ */
+function isPyPackageAvailable(python, packageName) {
+  try {
+    execSync(`${python} -c "import ${packageName}"`, {
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 10000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install a pip package quietly.
+ * Throws on failure.
+ */
+function pipInstall(python, packageName) {
+  process.stderr.write(`[contextl] Installing ${packageName}…\n`);
+  try {
+    execSync(`${python} -m pip install --quiet ${packageName}`, {
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 120_000,
+    });
+    process.stderr.write(`[contextl] ${packageName} installed.\n`);
+  } catch (err) {
+    throw new Error(
+      `Failed to install ${packageName} via pip.\n` +
+      `Run manually: pip install ${packageName}\n\n` +
+      String(err)
+    );
+  }
+}
+
+/**
+ * Ensure all required Python packages are available, installing if needed.
+ */
+function ensureDeps(python) {
+  const required = [
+    { importName: "networkx", pipName: "networkx" },
+    { importName: "mcp",      pipName: "mcp" },
+  ];
+
+  for (const { importName, pipName } of required) {
+    if (!isPyPackageAvailable(python, importName)) {
+      pipInstall(python, pipName);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Launch MCP server
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn mcp_server.py and forward signals so the parent IDE can cleanly
+ * shut it down.
+ */
+function launchServer(python) {
+  if (!fs.existsSync(MCP_SERVER)) {
+    throw new Error(`mcp_server.py not found at: ${MCP_SERVER}`);
+  }
+
+  const child = spawn(python, [MCP_SERVER], {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      PYTHONPATH: PYTHON_DIR,
+      PYTHONUNBUFFERED: "1",
+    },
+  });
+
+  // Forward termination signals to the child so it can shut down cleanly
+  for (const sig of ["SIGINT", "SIGTERM"]) {
+    process.on(sig, () => {
+      if (!child.killed) child.kill(sig);
+    });
+  }
+
+  child.on("exit", (code, signal) => {
+    process.exit(signal ? 1 : (code ?? 0));
+  });
+
+  child.on("error", (err) => {
+    process.stderr.write(`[contextl] Failed to start mcp_server.py: ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  let python;
+
+  try {
+    python = findPython();
+  } catch (err) {
+    process.stderr.write(`[contextl] ${err.message}\n`);
+    process.exit(1);
+  }
+
+  try {
+    ensureDeps(python);
+  } catch (err) {
+    process.stderr.write(`[contextl] Dependency error: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  launchServer(python);
+}
+
+main();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "contextl",
+  "version": "1.0.1",
+  "description": "contextl — finds the most relevant files in your codebase for any change request. MCP server for AI coding agents.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "code-search",
+    "context",
+    "cursor",
+    "windsurf",
+    "claude",
+    "vscode",
+    "typescript",
+    "nextjs",
+    "repository"
+  ],
+  "homepage": "https://github.com/dev7shah/prune#readme",
+  "bugs": {
+    "url": "https://github.com/dev7shah/prune/issues"
+  },
+  "license": "MIT",
+  "author": "dev7shah",
+  "bin": {
+    "contextl": "bin/contextl.js"
+  },
+  "files": [
+    "bin/",
+    "python/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prepublishOnly": "node -e \"require('fs').rmSync('python/__pycache__', { recursive: true, force: true })\"",
+    "test": "node bin/contextl.js --help 2>&1 || true"
+  }
+}

package/python/graph_builder.py

@@ -0,0 +1,171 @@
+"""
+Repository Intelligence Engine
+Step 3: Graph Builder
+
+Takes the import relationships from the parser and builds a directed graph
+where nodes are files and edges are import dependencies.
+
+Adds useful metadata to each node:
+  - in_degree:  how many files import this file (how "shared" it is)
+  - out_degree: how many files this file imports (how many deps it has)
+  - centrality: PageRank score (overall importance in the graph)
+
+Also computes connected clusters so we can understand which files
+belong to the same logical feature.
+"""
+
+import networkx as nx
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from scanner import scan_repo
+from import_parser import parse_imports, ParseResult
+
+
+@dataclass
+class FileNode:
+    """A file in the repository graph with computed metrics."""
+    path: str
+    extension: str
+    size_bytes: int
+
+    # Graph metrics (computed after graph is built)
+    in_degree: int = 0        # files that import this
+    out_degree: int = 0       # files this imports
+    centrality: float = 0.0   # PageRank score
+
+
+@dataclass
+class RepoGraph:
+    """
+    The complete dependency graph of the repository.
+    Wraps a NetworkX DiGraph with helper methods.
+    """
+    graph: nx.DiGraph
+    nodes: dict[str, FileNode]   # path → FileNode
+    root: str
+
+    def get_dependents(self, file_path: str) -> list[str]:
+        """Files that directly import this file (who uses me?)."""
+        return list(self.graph.predecessors(file_path))
+
+    def get_dependencies(self, file_path: str) -> list[str]:
+        """Files this file directly imports (what do I use?)."""
+        return list(self.graph.successors(file_path))
+
+    def get_neighbors(self, file_path: str, depth: int = 1) -> set[str]:
+        """
+        All files within `depth` hops of file_path (both directions).
+        depth=1 → direct imports + direct importers
+        depth=2 → their imports/importers too
+        """
+        neighbors = set()
+        frontier = {file_path}
+
+        for _ in range(depth):
+            next_frontier = set()
+            for node in frontier:
+                next_frontier.update(self.graph.predecessors(node))
+                next_frontier.update(self.graph.successors(node))
+            new_nodes = next_frontier - neighbors - {file_path}
+            neighbors.update(new_nodes)
+            frontier = new_nodes
+
+        return neighbors
+
+    def most_central_files(self, top_n: int = 5) -> list[FileNode]:
+        """Return the top N files by PageRank centrality."""
+        sorted_nodes = sorted(
+            self.nodes.values(),
+            key=lambda n: n.centrality,
+            reverse=True,
+        )
+        return sorted_nodes[:top_n]
+
+    def summary(self) -> str:
+        lines = [
+            f"Repository: {self.root}",
+            f"Nodes (files):        {self.graph.number_of_nodes()}",
+            f"Edges (imports):      {self.graph.number_of_edges()}",
+            f"Connected components: {nx.number_weakly_connected_components(self.graph)}",
+            "",
+            "Most central files (PageRank):",
+        ]
+        for node in self.most_central_files():
+            lines.append(
+                f"  {node.centrality:.4f}  {node.path}"
+                f"  (imported by {node.in_degree}, imports {node.out_degree})"
+            )
+        return "\n".join(lines)
+
+    def print_adjacency(self) -> None:
+        """Print a human-readable view of the full graph."""
+        print("Full dependency graph:")
+        for node_path in sorted(self.graph.nodes):
+            deps = self.get_dependencies(node_path)
+            used_by = self.get_dependents(node_path)
+            print(f"\n  {node_path}")
+            if deps:
+                for d in deps:
+                    print(f"    imports  → {d}")
+            if used_by:
+                for u in used_by:
+                    print(f"    used by  ← {u}")
+
+
+def build_graph(scan_result, parse_result: ParseResult) -> RepoGraph:
+    """
+    Build a directed dependency graph from scan + parse results.
+
+    Args:
+        scan_result:  Output from scan_repo()
+        parse_result: Output from parse_imports()
+
+    Returns:
+        RepoGraph with computed metrics on every node.
+    """
+    G = nx.DiGraph()
+
+    # Add all scanned files as nodes
+    file_nodes: dict[str, FileNode] = {}
+    for f in scan_result.files:
+        node = FileNode(
+            path=f.path,
+            extension=f.extension,
+            size_bytes=f.size_bytes,
+        )
+        file_nodes[f.path] = node
+        G.add_node(f.path, **vars(node))
+
+    # Add edges from import relationships
+    for rel in parse_result.relationships:
+        if rel.source in G and rel.target in G:
+            G.add_edge(rel.source, rel.target, raw_import=rel.raw_import)
+
+    # Compute PageRank (importance score)
+    try:
+        pagerank = nx.pagerank(G, alpha=0.85)
+    except nx.PowerIterationFailedConvergence:
+        pagerank = {n: 1.0 / len(G.nodes) for n in G.nodes}
+
+    # Attach metrics to each node
+    for path, node in file_nodes.items():
+        node.in_degree = G.in_degree(path)
+        node.out_degree = G.out_degree(path)
+        node.centrality = pagerank.get(path, 0.0)
+
+    return RepoGraph(graph=G, nodes=file_nodes, root=scan_result.root)
+
+
+if __name__ == "__main__":
+    import sys
+
+    target = sys.argv[1] if len(sys.argv) > 1 else "."
+
+    scan = scan_repo(target)
+    parse = parse_imports(scan)
+    repo_graph = build_graph(scan, parse)
+
+    print(repo_graph.summary())
+    print()
+    repo_graph.print_adjacency()