contextl 1.0.1 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextl",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "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
 # ---------------------------------------------------------------------------