contextl 1.0.1 → 1.1.1

package/README.md

@@ -1,23 +1,26 @@
 # 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.
+**Architecture intelligence for AI coding agents.**
+
+Stop letting your AI agent read your entire codebase to make one small change. `contextl` finds the exact files that matter — using graph theory, not guesswork.
 
 ```
-"fix the upload error" → [FileUploader.tsx, lib/upload.ts, UploadSection.tsx]
+"fix the broken checkout flow"
+        ↓
+components/Checkout.tsx      [high confidence]
+lib/api.ts                   [high confidence]
+types/index.ts                [medium confidence]
 ```
 
-Instead of feeding your entire repo to an AI, `contextl` reduces 5 000 files down to the 5 most relevant ones in milliseconds.
+No LLM. No embeddings. No API keys. No vector database. Pure dependency graph + text scoring — runs entirely on your machine, your code never leaves your laptop.
 
 ---
 
-## Quick start
-
-**Requires Python 3.9+** on your PATH. Everything else (`networkx`, `mcp`) is installed automatically on first run.
+## Install (60 seconds)
 
-### 1 — Add to your IDE's MCP config
+**Requires Python 3.9+** on your PATH. Everything else (`networkx`, `mcp`) installs automatically on first run.
 
-Paste this JSON into your IDE's MCP config file (paths listed below):
+Add this to your IDE's MCP config file:
 
 ```json
 {
@@ -30,103 +33,79 @@ Paste this JSON into your IDE's MCP config file (paths listed below):
 }
 ```
 
-#### Config file locations
+**Where to find your config file:**
 
-| IDE | Config file |
+| IDE | Config path |
 |-----|-------------|
-| **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 |
+| Antigravity | `~/.gemini/config/mcp_config.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Claude Code | `~/.claude.json` |
+| VS Code | `.vscode/mcp.json` |
 
-### 2 — Use it
+Restart your IDE. Done — no cloning, no Python setup beyond having it installed.
 
-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
-```
+## What it gives your agent
 
----
+Three tools, automatically available once connected:
 
-## Tools exposed
+### `query_repo`
+*"Find the files relevant to this change."*
 
-### `query_repo(repo_path, query, top_n?)`
+Ranks every file in your repo against a natural-language query using filename matching, content matching, and graph proximity. Returns confidence-scored results with plain-English reasoning.
 
-Ranks the most relevant files for a change request.
+### `analyze_impact`
+*"If I change this file, what breaks?"*
 
-**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`)
+Walks the dependency graph upstream from any file to find every direct and transitive dependent. Flags likely test files so your agent knows what to re-run. Essential before touching shared files like `types/`, `utils/`, or config.
 
-**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`
+*"What files exist here?"*
 
-### `scan_repo(repo_path)`
+Lists every source file `contextl` can see — useful for the agent to orient itself before doing anything else.
 
-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 the ranking works
+
+1. **Keyword match** — does the filename contain query terms?
+2. **Content match** — does the file's source code mention the terms?
+3. **Graph proximity** — files connected to high-scoring files get a relevance boost
+4. **Centrality (PageRank)** — heavily-connected files rank higher when scores tie
 
 ---
 
-## How it works
+## Supported languages
 
-The engine runs **entirely locally** — no network calls, no AI APIs, no data leaves your machine.
+TypeScript, TSX, JavaScript, JSX — built for Next.js and React codebases first.
 
-Scoring uses four signals:
+Python, Go, and Rust support are on the roadmap.
 
-| 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`.
+## Why this exists
+
+AI coding agents are increasingly good at writing code. They're still bad at knowing *where* to look. On a 5,000-file repo, an agent might read 100+ files just to change a logo. `contextl` exists to fix that — and to eventually give agents a real model of your codebase's architecture, not just a file list.
 
 ---
 
-## Requirements
+## Also available for Python
+
+```bash
+pip install contextl-mcp
+```
 
-| Requirement | Version |
-|-------------|---------|
-| Node.js | ≥ 18 |
-| Python | ≥ 3.9 |
-| `networkx` | auto-installed |
-| `mcp` | auto-installed |
+Same engine, same tools — installable via PyPI for Python-first workflows.
 
 ---
 
+## Links
+
+- [GitHub](https://github.com/DS0710-coder/contextl)
+- [PyPI package](https://pypi.org/project/contextl-mcp)
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextl",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "contextl — finds the most relevant files in your codebase for any change request. MCP server for AI coding agents.",
   "keywords": [
     "mcp",

package/python/impact_analysis.py

@@ -0,0 +1,196 @@
+"""
+Repository Intelligence Engine
+Step 6: Change Impact Analysis
+
+Answers: "If I modify this file, what else is affected?"
+
+Walks the dependency graph upstream (predecessors) from a given file to find
+every file that directly or transitively depends on it. Also flags likely
+test files so the impact report highlights what needs re-testing.
+
+Pure graph traversal — no LLM, no embeddings. Uses the same RepoGraph
+built in graph_builder.py.
+"""
+
+from dataclasses import dataclass, field
+
+from scanner import scan_repo
+from import_parser import parse_imports
+from graph_builder import build_graph, RepoGraph
+
+
+# Heuristics for detecting test files by path/name
+TEST_MARKERS = ("test", "spec", "__tests__", "__mocks__")
+
+
+@dataclass
+class ImpactedFile:
+    """A single file affected by a change, with its distance from the source."""
+    path: str
+    distance: int          # 1 = directly imports the changed file, 2 = imports something that does, etc.
+    is_test_file: bool
+    via: str                # the immediate file that pulled this one in (for tracing the chain)
+
+
+@dataclass
+class ImpactReport:
+    """Full result of an impact analysis for one target file."""
+    target: str
+    directly_affected: list[ImpactedFile] = field(default_factory=list)
+    transitively_affected: list[ImpactedFile] = field(default_factory=list)
+    test_files: list[str] = field(default_factory=list)
+    total_affected: int = 0
+
+    def summary(self) -> str:
+        lines = [
+            f"Impact analysis for: {self.target}",
+            f"Total affected files: {self.total_affected}",
+            "",
+        ]
+
+        if self.directly_affected:
+            lines.append("Directly affected (import this file):")
+            for f in self.directly_affected:
+                marker = "  [test]" if f.is_test_file else ""
+                lines.append(f"  {f.path}{marker}")
+            lines.append("")
+
+        if self.transitively_affected:
+            lines.append("Transitively affected (depend on a direct dependent):")
+            for f in self.transitively_affected:
+                marker = "  [test]" if f.is_test_file else ""
+                lines.append(f"  {f.path}  (via {f.via}, distance {f.distance}){marker}")
+            lines.append("")
+
+        if self.test_files:
+            lines.append("Suggested tests to run:")
+            for t in self.test_files:
+                lines.append(f"  {t}")
+        else:
+            lines.append("No test files found in the impact radius.")
+
+        return "\n".join(lines)
+
+    def to_tree_string(self) -> str:
+        """Render as an ASCII dependency tree, similar to `tree` output."""
+        lines = [self.target]
+        direct = self.directly_affected
+        for i, f in enumerate(direct):
+            is_last_direct = (i == len(direct) - 1)
+            connector = "└──" if is_last_direct else "├──"
+            marker = " [test]" if f.is_test_file else ""
+            lines.append(f"{connector} {f.path}{marker}")
+
+            # Find transitive files that came via this direct file
+            children = [t for t in self.transitively_affected if t.via == f.path]
+            for j, child in enumerate(children):
+                is_last_child = (j == len(children) - 1)
+                prefix = "    " if is_last_direct else "│   "
+                child_connector = "└──" if is_last_child else "├──"
+                child_marker = " [test]" if child.is_test_file else ""
+                lines.append(f"{prefix}{child_connector} {child.path}{child_marker}")
+
+        return "\n".join(lines)
+
+
+def _is_test_file(path: str) -> bool:
+    lowered = path.lower()
+    return any(marker in lowered for marker in TEST_MARKERS)
+
+
+def analyze_impact(
+    target_file: str,
+    repo_graph: RepoGraph,
+    max_depth: int = 5,
+) -> ImpactReport:
+    """
+    Find every file affected by a change to target_file.
+
+    Args:
+        target_file: Relative path of the file being changed (must exist in repo_graph.nodes).
+        repo_graph:  Built graph from build_graph().
+        max_depth:   Maximum number of hops to traverse upstream (default 5).
+
+    Returns:
+        ImpactReport listing direct and transitive dependents.
+
+    Raises:
+        ValueError: If target_file is not found in the graph.
+    """
+    if target_file not in repo_graph.nodes:
+        raise ValueError(
+            f"File not found in repository graph: {target_file}. "
+            f"Make sure the path is relative to the repo root."
+        )
+
+    report = ImpactReport(target=target_file)
+
+    visited: set[str] = {target_file}
+    direct_dependents = repo_graph.get_dependents(target_file)
+
+    # --- Distance 1: direct dependents ---
+    frontier: list[tuple[str, str]] = []  # (path, via)
+    for dep in direct_dependents:
+        if dep in visited:
+            continue
+        visited.add(dep)
+        is_test = _is_test_file(dep)
+        report.directly_affected.append(
+            ImpactedFile(path=dep, distance=1, is_test_file=is_test, via=target_file)
+        )
+        if is_test:
+            report.test_files.append(dep)
+        frontier.append((dep, dep))
+
+    # --- Distance 2+: transitive dependents (BFS upstream) ---
+    distance = 2
+    while frontier and distance <= max_depth:
+        next_frontier: list[tuple[str, str]] = []
+
+        for current_path, origin_direct_file in frontier:
+            for dep in repo_graph.get_dependents(current_path):
+                if dep in visited:
+                    continue
+                visited.add(dep)
+                is_test = _is_test_file(dep)
+                report.transitively_affected.append(
+                    ImpactedFile(
+                        path=dep,
+                        distance=distance,
+                        is_test_file=is_test,
+                        via=origin_direct_file,  # trace back to the original direct dependent
+                    )
+                )
+                if is_test:
+                    report.test_files.append(dep)
+                next_frontier.append((dep, origin_direct_file))
+
+        frontier = next_frontier
+        distance += 1
+
+    report.total_affected = len(report.directly_affected) + len(report.transitively_affected)
+
+    return report
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 3:
+        print("Usage: python impact_analysis.py <repo_path> <target_file>")
+        print("Example: python impact_analysis.py ../sample_repo types/files.ts")
+        sys.exit(1)
+
+    repo_path = sys.argv[1]
+    target = sys.argv[2]
+
+    scan = scan_repo(repo_path)
+    parse = parse_imports(scan)
+    repo_graph = build_graph(scan, parse)
+
+    report = analyze_impact(target, repo_graph)
+
+    print(report.summary())
+    print()
+    print("Dependency tree:")
+    print(report.to_tree_string())

package/python/mcp_server.py

@@ -11,8 +11,9 @@ 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
+    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
 """
 
 import asyncio
@@ -32,6 +33,7 @@ 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
+from impact_analysis import analyze_impact
 
 
 # ---------------------------------------------------------------------------
@@ -100,6 +102,42 @@ async def list_tools() -> list[types.Tool]:
                 "required": ["repo_path"],
             },
         ),
+        types.Tool(
+            name="analyze_impact",
+            description=(
+                "Find every file affected by changing a specific file. "
+                "Walks the dependency graph upstream to find direct and transitive "
+                "dependents — files that import the target file, and files that import "
+                "those files. Flags likely test files so you know what to re-test. "
+                "Use this BEFORE modifying a shared file (types, utils, config) to "
+                "understand the blast radius of the change."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "repo_path": {
+                        "type": "string",
+                        "description": "Absolute or relative path to the repository root.",
+                    },
+                    "target_file": {
+                        "type": "string",
+                        "description": (
+                            "Path of the file being changed, relative to repo_path. "
+                            "Example: 'src/types/index.ts' or 'lib/api.ts'. "
+                            "Use scan_repo first if unsure of the exact path."
+                        ),
+                    },
+                    "max_depth": {
+                        "type": "integer",
+                        "description": "Maximum hops to traverse upstream (default: 5).",
+                        "default": 5,
+                        "minimum": 1,
+                        "maximum": 10,
+                    },
+                },
+                "required": ["repo_path", "target_file"],
+            },
+        ),
     ]
 
 
@@ -115,6 +153,9 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
     if name == "scan_repo":
         return await _handle_scan(arguments)
 
+    if name == "analyze_impact":
+        return await _handle_impact(arguments)
+
     return [types.TextContent(
         type="text",
         text=json.dumps({"error": f"Unknown tool: {name}"}),
@@ -185,6 +226,48 @@ def _run_scan(repo_path: str) -> dict:
     }
 
 
+async def _handle_impact(args: dict) -> list[types.TextContent]:
+    repo_path = args.get("repo_path", "")
+    target_file = args.get("target_file", "")
+    max_depth = min(int(args.get("max_depth", 5)), 10)
+
+    loop = asyncio.get_event_loop()
+    try:
+        result = await loop.run_in_executor(None, _run_impact, repo_path, target_file, max_depth)
+    except Exception as e:
+        result = {"error": str(e), "repo": repo_path, "target_file": target_file}
+
+    return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+
+
+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)
+    report = analyze_impact(target_file, repo_graph, max_depth=max_depth)
+
+    return {
+        "target_file": report.target,
+        "total_affected": report.total_affected,
+        "directly_affected": [
+            {"path": f.path, "is_test_file": f.is_test_file}
+            for f in report.directly_affected
+        ],
+        "transitively_affected": [
+            {
+                "path": f.path,
+                "distance": f.distance,
+                "via": f.via,
+                "is_test_file": f.is_test_file,
+            }
+            for f in report.transitively_affected
+        ],
+        "suggested_tests": report.test_files,
+        "dependency_tree": report.to_tree_string(),
+    }
+
+
 # ---------------------------------------------------------------------------
 # Entry point
 # ---------------------------------------------------------------------------