interlinked-mapper 0.1.0__py3-none-any.whl

interlinked/commander/repl.py

@@ -0,0 +1,50 @@
+"""Interactive REPL for controlling the visualization."""
+
+from __future__ import annotations
+
+import code
+import sys
+from pathlib import Path
+
+from interlinked.analyzer.graph import CodeGraph
+from interlinked.commander.query import QueryEngine
+
+
+class InterlinkedREPL:
+    """Drops into an interactive Python REPL with the QueryEngine as `view`."""
+
+    def __init__(self, graph: CodeGraph) -> None:
+        self.graph = graph
+        self.view = QueryEngine(graph)
+
+    def start(self) -> None:
+        """Launch the interactive REPL."""
+        banner = (
+            "\n"
+            "╔══════════════════════════════════════════════════╗\n"
+            "║           INTERLINKED — Topology Explorer        ║\n"
+            "╚══════════════════════════════════════════════════╝\n"
+            "\n"
+            "  Available objects:\n"
+            "    view    — QueryEngine (main control interface)\n"
+            "    graph   — CodeGraph (raw graph access)\n"
+            "\n"
+            "  Quick start:\n"
+            "    view.stats()                          # summary\n"
+            "    view.zoom('module')                   # zoom level\n"
+            "    view.focus('my_module')               # focus on node\n"
+            "    view.query('dead functions')          # find dead code\n"
+            "    view.trace_variable('config')         # trace a var\n"
+            "    view.nl('show me uncalled functions') # natural language\n"
+            "\n"
+            "  Type help(view) for full API documentation.\n"
+        )
+
+        local_ns = {
+            "view": self.view,
+            "graph": self.graph,
+            "QueryEngine": QueryEngine,
+            "CodeGraph": CodeGraph,
+        }
+
+        code.interact(banner=banner, local=local_ns, exitmsg="Goodbye.")

interlinked/mcp_server.py

@@ -0,0 +1,324 @@
+"""MCP Server for Interlinked — exposes the full view API as MCP tools.
+
+This allows Windsurf, Claude Desktop, or any MCP-compatible client to
+drive the Interlinked visualization directly.
+
+Usage:
+    interlinked mcp ./my_project                    # stdio transport
+    interlinked mcp ./my_project --port 8421        # SSE transport
+
+MCP config example (for .windsurf/mcp_config.json or claude_desktop_config.json):
+{
+  "mcpServers": {
+    "interlinked": {
+      "command": "/path/to/.venv/bin/interlinked",
+      "args": ["mcp", "/path/to/project"],
+      "env": {
+        "ANTHROPIC_API_KEY": "sk-ant-..."
+      }
+    }
+  }
+}
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from interlinked.analyzer.parser import parse_project
+from interlinked.analyzer.graph import CodeGraph
+from interlinked.analyzer.dead_code import detect_dead_code
+from interlinked.commander.query import QueryEngine
+
+
+def build_graph(project_path: str) -> tuple[CodeGraph, QueryEngine]:
+    """Parse a project and build the graph + query engine."""
+    nodes, edges = parse_project(project_path)
+    graph = CodeGraph()
+    graph.build_from(nodes, edges)
+    detect_dead_code(graph)
+
+    # Run similarity analysis if available
+    try:
+        from interlinked.analyzer.similarity import analyze_similarity
+        analyze_similarity(graph)
+    except Exception:
+        pass
+
+    engine = QueryEngine(graph)
+    return graph, engine
+
+
+def create_mcp_server(project_path: str) -> Server:
+    """Create an MCP server with all Interlinked tools."""
+    graph, engine = build_graph(project_path)
+
+    # Pick up API key from env if available
+    api_key = os.environ.get("ANTHROPIC_API_KEY", "")
+
+    server = Server("interlinked")
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        return [
+            Tool(
+                name="interlinked_stats",
+                description="Get summary statistics about the analyzed Python project: node counts, edge counts, dead code count.",
+                inputSchema={"type": "object", "properties": {}, "required": []},
+            ),
+            Tool(
+                name="interlinked_isolate",
+                description="Isolate a module, class, or function and show it plus everything that connects to it. This is the primary command for exploring a codebase. The target can be a partial name.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "target": {"type": "string", "description": "Name or partial name of the module/class/function to isolate"},
+                        "level": {"type": "string", "enum": ["module", "class", "function", "variable", "all"], "description": "Zoom level", "default": "function"},
+                        "depth": {"type": "integer", "description": "How many hops of connections to show", "default": 3},
+                        "edge_types": {"type": "array", "items": {"type": "string"}, "description": "Optional: only follow these edge types (calls, imports, inherits, reads, writes)"},
+                    },
+                    "required": ["target"],
+                },
+            ),
+            Tool(
+                name="interlinked_zoom",
+                description="Set the zoom level of the visualization: 'module' (high-level), 'class' (mid-level), or 'function' (detailed).",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "level": {"type": "string", "enum": ["module", "class", "function", "variable", "all"]},
+                    },
+                    "required": ["level"],
+                },
+            ),
+            Tool(
+                name="interlinked_focus",
+                description="Focus the visualization on a specific node and its neighborhood within N hops.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "node_id": {"type": "string", "description": "Qualified name of the node to focus on"},
+                        "depth": {"type": "integer", "description": "Number of hops to show", "default": 2},
+                    },
+                    "required": ["node_id"],
+                },
+            ),
+            Tool(
+                name="interlinked_query",
+                description="Run a structured query against the codebase graph. Supports: 'dead functions', 'callers of X', 'callees of X', 'modules', 'classes', 'functions', or any search term for fuzzy name matching.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "expression": {"type": "string", "description": "Query expression"},
+                    },
+                    "required": ["expression"],
+                },
+            ),
+            Tool(
+                name="interlinked_trace_variable",
+                description="Trace a variable's path through reads and writes across the codebase.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "variable": {"type": "string", "description": "Variable name to trace"},
+                        "origin": {"type": "string", "description": "Optional: qualified name of the origin scope"},
+                    },
+                    "required": ["variable"],
+                },
+            ),
+            Tool(
+                name="interlinked_propose_function",
+                description="Add a hypothetical function to the graph to visualize where it would connect. Shown in green to distinguish from real code.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string", "description": "Function name"},
+                        "module": {"type": "string", "description": "Module to place it in"},
+                        "calls": {"type": "array", "items": {"type": "string"}, "description": "Functions this would call"},
+                        "called_by": {"type": "array", "items": {"type": "string"}, "description": "Functions that would call this"},
+                    },
+                    "required": ["name", "module"],
+                },
+            ),
+            Tool(
+                name="interlinked_find_duplicates",
+                description="Find functions/methods with similar structure, signatures, or logic paths — potential duplicated functionality. Returns groups of similar symbols with similarity scores.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "threshold": {"type": "number", "description": "Similarity threshold 0.0-1.0 (default 0.6)", "default": 0.6},
+                        "scope": {"type": "string", "description": "Optional: limit search to symbols under this prefix"},
+                    },
+                    "required": [],
+                },
+            ),
+            Tool(
+                name="interlinked_similar_to",
+                description="Find functions/classes structurally similar to a given symbol. Useful for finding duplicated or redundant functionality.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "target": {"type": "string", "description": "Name or partial name of the symbol to compare against"},
+                        "threshold": {"type": "number", "description": "Similarity threshold 0.0-1.0", "default": 0.5},
+                    },
+                    "required": ["target"],
+                },
+            ),
+            Tool(
+                name="interlinked_get_context",
+                description="Get rich context about a symbol: source code, docstring, signature, comments, connections, and structural fingerprint. Useful for understanding what a function does before comparing.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "target": {"type": "string", "description": "Name or partial name of the symbol"},
+                    },
+                    "required": ["target"],
+                },
+            ),
+            Tool(
+                name="interlinked_command",
+                description="Execute a raw Python command against the view API. For advanced usage. The `view` object is the QueryEngine and `graph` is the CodeGraph.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "command": {"type": "string", "description": "Python expression to evaluate, e.g. view.isolate('analyzer')"},
+                    },
+                    "required": ["command"],
+                },
+            ),
+            Tool(
+                name="interlinked_switch_project",
+                description="Switch to analyzing a different Python project. Re-parses the new project and rebuilds the entire graph.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string", "description": "Absolute or relative path to the Python project root"},
+                    },
+                    "required": ["path"],
+                },
+            ),
+            Tool(
+                name="interlinked_reset",
+                description="Reset all filters, focus, and highlights back to the default full-graph view.",
+                inputSchema={"type": "object", "properties": {}, "required": []},
+            ),
+            Tool(
+                name="interlinked_set_api_key",
+                description="Set the Anthropic API key for the built-in chat pilot. This is stored in memory only, not written to disk.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "api_key": {"type": "string", "description": "Anthropic API key (sk-ant-...)"},
+                    },
+                    "required": ["api_key"],
+                },
+            ),
+        ]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+        nonlocal api_key
+
+        try:
+            result = _dispatch_tool(name, arguments, engine, graph, api_key)
+            if name == "interlinked_set_api_key":
+                api_key = arguments.get("api_key", "")
+                os.environ["ANTHROPIC_API_KEY"] = api_key
+                result = f"API key {'set' if api_key else 'cleared'}."
+            return [TextContent(type="text", text=str(result))]
+        except Exception as e:
+            return [TextContent(type="text", text=f"Error: {e}")]
+
+    return server
+
+
+def _dispatch_tool(
+    name: str, args: dict[str, Any],
+    engine: QueryEngine, graph: CodeGraph, api_key: str,
+) -> str:
+    """Route a tool call to the appropriate engine method."""
+
+    if name == "interlinked_stats":
+        stats = engine.stats()
+        return json.dumps(stats, indent=2)
+
+    elif name == "interlinked_isolate":
+        return engine.isolate(
+            target=args["target"],
+            level=args.get("level", "function"),
+            depth=args.get("depth", 3),
+            edge_types=args.get("edge_types"),
+        )
+
+    elif name == "interlinked_zoom":
+        return engine.zoom(args["level"])
+
+    elif name == "interlinked_focus":
+        return engine.focus(args["node_id"], depth=args.get("depth", 2))
+
+    elif name == "interlinked_query":
+        results = engine.query(args["expression"])
+        if len(results) > 20:
+            summary = f"Found {len(results)} results. Showing first 20:\n"
+            return summary + json.dumps(results[:20], indent=2)
+        return json.dumps(results, indent=2)
+
+    elif name == "interlinked_trace_variable":
+        return engine.trace_variable(args["variable"], args.get("origin"))
+
+    elif name == "interlinked_propose_function":
+        return engine.propose_function(
+            name=args["name"], module=args["module"],
+            calls=args.get("calls"), called_by=args.get("called_by"),
+        )
+
+    elif name == "interlinked_find_duplicates":
+        threshold = args.get("threshold", 0.6)
+        scope = args.get("scope")
+        return engine.find_duplicates(threshold=threshold, scope=scope)
+
+    elif name == "interlinked_similar_to":
+        return engine.similar_to(args["target"], threshold=args.get("threshold", 0.5))
+
+    elif name == "interlinked_get_context":
+        return engine.get_context(args["target"])
+
+    elif name == "interlinked_command":
+        cmd = args["command"]
+        local_ns: dict[str, Any] = {"view": engine, "graph": graph}
+        try:
+            result = eval(cmd, {"__builtins__": {}}, local_ns)
+        except SyntaxError:
+            exec(cmd, {"__builtins__": {}}, local_ns)
+            result = "OK"
+        if hasattr(result, "model_dump"):
+            return json.dumps(result.model_dump(), indent=2)
+        return str(result)
+
+    elif name == "interlinked_switch_project":
+        from interlinked.visualizer.server import _rebuild_graph
+        result = _rebuild_graph(args["path"], graph)
+        engine.reset_filter()
+        return json.dumps(result, indent=2)
+
+    elif name == "interlinked_reset":
+        return engine.reset_filter()
+
+    elif name == "interlinked_set_api_key":
+        return ""  # handled in call_tool
+
+    return f"Unknown tool: {name}"
+
+
+async def run_mcp_stdio(project_path: str) -> None:
+    """Run the MCP server over stdio."""
+    server = create_mcp_server(project_path)
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())

interlinked/models.py

@@ -0,0 +1,107 @@
+"""Shared data models for Interlinked."""
+
+from __future__ import annotations
+
+import enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SymbolType(str, enum.Enum):
+    MODULE = "module"
+    CLASS = "class"
+    FUNCTION = "function"
+    METHOD = "method"
+    VARIABLE = "variable"
+    PARAMETER = "parameter"
+
+
+class EdgeType(str, enum.Enum):
+    CALLS = "calls"
+    IMPORTS = "imports"
+    INHERITS = "inherits"
+    READS = "reads"
+    WRITES = "writes"
+    CONTAINS = "contains"  # module contains class, class contains method, etc.
+    PROPOSED = "proposed"
+    RETURNS = "returns"  # function returns value to caller
+
+
+class NodeData(BaseModel):
+    id: str
+    name: str
+    qualified_name: str
+    symbol_type: SymbolType
+    file_path: str | None = None
+    line_start: int | None = None
+    line_end: int | None = None
+    docstring: str | None = None
+    signature: str | None = None
+    is_dead: bool = False
+    is_proposed: bool = False
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class EdgeData(BaseModel):
+    source: str
+    target: str
+    edge_type: EdgeType
+    is_dead: bool = False
+    is_proposed: bool = False
+    line: int | None = None  # line where the reference occurs
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ColorScheme(BaseModel):
+    healthy: str = "#4a90d9"
+    dead_link: str = "#e74c3c"
+    proposed: str = "#2ecc71"
+    highlighted: str = "#f1c40f"
+    contains: str = "#95a5a6"
+    inherits: str = "#9b59b6"
+    imports: str = "#3498db"
+    calls: str = "#e67e22"
+    reads: str = "#1abc9c"
+    writes: str = "#e91e63"
+    module_bg: str = "#2c3e50"
+    class_bg: str = "#34495e"
+    function_bg: str = "#4a6fa5"
+    variable_bg: str = "#7f8c8d"
+
+
+class ViewContext(BaseModel):
+    """Natural language context for what the user is currently looking at."""
+    what: str = ""     # What is being shown
+    why: str = ""      # Why this view was chosen
+    where: str = ""    # Which part of the codebase (scope/modules/symbols)
+    source: str = ""   # Who set this context: "llm", "command", "trace", ""
+
+
+class ViewState(BaseModel):
+    """Current state of the visualization — what the user sees."""
+    zoom_level: str = "function"  # module, class, function
+    focus_node: str | None = None
+    focus_depth: int = 2
+    visible_node_ids: list[str] = Field(default_factory=list)
+    visible_edge_types: list[EdgeType] = Field(
+        default_factory=lambda: list(EdgeType)
+    )
+    highlighted_node_ids: list[str] = Field(default_factory=list)
+    highlighted_edge_ids: list[tuple[str, str]] = Field(default_factory=list)
+    # Trace roles: node_id -> "origin" | "mutator" | "passthrough" | "destination"
+    trace_node_roles: dict[str, str] = Field(default_factory=dict)
+    # Trace edge roles: "src|tgt" -> "write" | "read"
+    trace_edge_roles: dict[str, str] = Field(default_factory=dict)
+    colors: ColorScheme = Field(default_factory=ColorScheme)
+    show_dead: bool = True
+    show_proposed: bool = True
+    filter_expression: str | None = None
+    context: ViewContext = Field(default_factory=ViewContext)
+
+
+class GraphSnapshot(BaseModel):
+    """Serializable snapshot of the graph for the frontend."""
+    nodes: list[NodeData]
+    edges: list[EdgeData]
+    view: ViewState

interlinked/visualizer/__init__.py

@@ -0,0 +1 @@
+"""Visualizer — FastAPI server and web frontend."""

interlinked/visualizer/layouts.py

@@ -0,0 +1,181 @@
+"""Graph layout algorithms — compute node positions for the frontend.
+
+Uses a pure-Python force-directed layout so numpy is not required.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from typing import Any
+
+from interlinked.models import NodeData, EdgeData, SymbolType
+
+
+def _circular_layout(nodes: list[NodeData]) -> dict[str, tuple[float, float]]:
+    """Arrange nodes in a circle."""
+    n = len(nodes)
+    if n == 0:
+        return {}
+    pos: dict[str, tuple[float, float]] = {}
+    for i, node in enumerate(nodes):
+        angle = 2 * math.pi * i / n
+        pos[node.id] = (math.cos(angle), math.sin(angle))
+    return pos
+
+
+def compute_layout(
+    nodes: list[NodeData],
+    edges: list[EdgeData],
+    algorithm: str = "force",
+    width: float = 1200,
+    height: float = 800,
+) -> dict[str, dict[str, float]]:
+    """Compute x,y positions for each node.
+
+    Returns: {node_id: {"x": float, "y": float}}
+    """
+    if not nodes:
+        return {}
+
+    if algorithm == "hierarchical":
+        pos = _hierarchical_layout(nodes, edges)
+    elif algorithm == "circular":
+        pos = _circular_layout(nodes)
+    else:
+        pos = _force_layout(nodes, edges, iterations=80)
+
+    # Scale to canvas dimensions
+    result: dict[str, dict[str, float]] = {}
+    if pos:
+        xs = [p[0] for p in pos.values()]
+        ys = [p[1] for p in pos.values()]
+        min_x, max_x = min(xs), max(xs)
+        min_y, max_y = min(ys), max(ys)
+        range_x = max_x - min_x or 1
+        range_y = max_y - min_y or 1
+        margin = 80
+
+        for nid, (x, y) in pos.items():
+            result[nid] = {
+                "x": margin + ((x - min_x) / range_x) * (width - 2 * margin),
+                "y": margin + ((y - min_y) / range_y) * (height - 2 * margin),
+            }
+
+    return result
+
+
+def _force_layout(
+    nodes: list[NodeData],
+    edges: list[EdgeData],
+    iterations: int = 80,
+) -> dict[str, tuple[float, float]]:
+    """Pure-Python Fruchterman-Reingold force-directed layout."""
+    rng = random.Random(42)
+    node_ids = [n.id for n in nodes]
+    n = len(node_ids)
+    if n == 0:
+        return {}
+    if n == 1:
+        return {node_ids[0]: (0.0, 0.0)}
+
+    idx = {nid: i for i, nid in enumerate(node_ids)}
+    id_set = set(node_ids)
+
+    # Initial random positions
+    px = [rng.uniform(-1.0, 1.0) for _ in range(n)]
+    py = [rng.uniform(-1.0, 1.0) for _ in range(n)]
+
+    # Build adjacency
+    adj: list[list[int]] = [[] for _ in range(n)]
+    for e in edges:
+        if e.source in id_set and e.target in id_set:
+            si, ti = idx[e.source], idx[e.target]
+            adj[si].append(ti)
+            adj[ti].append(si)
+
+    area = 4.0 * n
+    k = math.sqrt(area / max(n, 1))
+    temp = 1.0
+
+    for iteration in range(iterations):
+        # Repulsive forces between all pairs
+        dx = [0.0] * n
+        dy = [0.0] * n
+
+        for i in range(n):
+            for j in range(i + 1, n):
+                ddx = px[i] - px[j]
+                ddy = py[i] - py[j]
+                dist = math.sqrt(ddx * ddx + ddy * ddy) or 0.001
+                force = (k * k) / dist
+                fx = (ddx / dist) * force
+                fy = (ddy / dist) * force
+                dx[i] += fx
+                dy[i] += fy
+                dx[j] -= fx
+                dy[j] -= fy
+
+        # Attractive forces along edges
+        for i in range(n):
+            for j in adj[i]:
+                if j <= i:
+                    continue
+                ddx = px[i] - px[j]
+                ddy = py[i] - py[j]
+                dist = math.sqrt(ddx * ddx + ddy * ddy) or 0.001
+                force = (dist * dist) / k
+                fx = (ddx / dist) * force
+                fy = (ddy / dist) * force
+                dx[i] -= fx
+                dy[i] -= fy
+                dx[j] += fx
+                dy[j] += fy
+
+        # Apply with temperature
+        for i in range(n):
+            disp = math.sqrt(dx[i] * dx[i] + dy[i] * dy[i]) or 0.001
+            scale = min(disp, temp) / disp
+            px[i] += dx[i] * scale
+            py[i] += dy[i] * scale
+
+        temp *= 0.95  # cooling
+
+    return {node_ids[i]: (px[i], py[i]) for i in range(n)}
+
+
+def _hierarchical_layout(
+    nodes: list[NodeData], edges: list[EdgeData]
+) -> dict[str, tuple[float, float]]:
+    """Simple hierarchical layout: modules at top, classes below, functions at bottom."""
+    layers: dict[SymbolType, list[str]] = {
+        SymbolType.MODULE: [],
+        SymbolType.CLASS: [],
+        SymbolType.FUNCTION: [],
+        SymbolType.METHOD: [],
+        SymbolType.VARIABLE: [],
+    }
+
+    for n in nodes:
+        layers[n.symbol_type].append(n.id)
+
+    pos: dict[str, tuple[float, float]] = {}
+    layer_order = [
+        SymbolType.MODULE,
+        SymbolType.CLASS,
+        SymbolType.FUNCTION,
+        SymbolType.METHOD,
+        SymbolType.VARIABLE,
+    ]
+
+    y = 0.0
+    for sym_type in layer_order:
+        ids = layers[sym_type]
+        if not ids:
+            continue
+        for i, nid in enumerate(ids):
+            x = (i + 1) / (len(ids) + 1)
+            pos[nid] = (x, y)
+        y += 1.0
+
+    return pos