graphlens-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{graphlens_cli-0.4.0 → graphlens_cli-0.5.0}/PKG-INFO

@@ -1,17 +1,20 @@
 Metadata-Version: 2.3
 Name: graphlens-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Command-line interface for graphlens code analysis
 Requires-Dist: graphlens
 Requires-Dist: typer[all]>=0.15
 Requires-Dist: graphlens-python ; extra == 'all'
 Requires-Dist: graphlens-typescript ; extra == 'all'
 Requires-Dist: neo4j ; extra == 'all'
+Requires-Dist: mcp>=1.2 ; extra == 'all'
+Requires-Dist: mcp>=1.2 ; extra == 'mcp'
 Requires-Dist: neo4j ; extra == 'neo4j'
 Requires-Dist: graphlens-python ; extra == 'python'
 Requires-Dist: graphlens-typescript ; extra == 'typescript'
 Requires-Python: >=3.13
 Provides-Extra: all
+Provides-Extra: mcp
 Provides-Extra: neo4j
 Provides-Extra: python
 Provides-Extra: typescript

{graphlens_cli-0.4.0 → graphlens_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphlens-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "Command-line interface for graphlens code analysis"
 requires-python = ">=3.13"
 dependencies = [
@@ -12,7 +12,8 @@ dependencies = [
 python = ["graphlens-python"]
 typescript = ["graphlens-typescript"]
 neo4j = ["neo4j"]
-all = ["graphlens-python", "graphlens-typescript", "neo4j"]
+mcp = ["mcp>=1.2"]
+all = ["graphlens-python", "graphlens-typescript", "neo4j", "mcp>=1.2"]
 
 [project.scripts]
 graphlens = "graphlens_cli:app"

{graphlens_cli-0.4.0 → graphlens_cli-0.5.0}/src/graphlens_cli/__init__.py

@@ -1,7 +1,9 @@
 """graphlens-cli — command-line interface for graphlens code analysis."""
 
 import graphlens_cli._analyze
+import graphlens_cli._mcp
 import graphlens_cli._neo4j
+import graphlens_cli._query
 import graphlens_cli._visualize  # noqa: F401  — registers visualize command
 from graphlens_cli._app import app
 

{graphlens_cli-0.4.0 → graphlens_cli-0.5.0}/src/graphlens_cli/_analyze.py

@@ -1,4 +1,4 @@
-"""graphlens analyze — print graph statistics."""
+"""graphlens analyze — print graph statistics or serialize to JSON."""
 
 from __future__ import annotations
 
@@ -7,40 +7,14 @@ from pathlib import Path
 from typing import Annotated
 
 import typer
-from graphlens import NodeKind, RelationKind
+from graphlens import RESOLVER_STATUS_KEY, GraphLens, NodeKind, RelationKind
 
 from graphlens_cli._app import app, resolve_langs, run_analysis
 
 
-@app.command()
-def analyze(
-    root: Annotated[
-        Path,
-        typer.Argument(
-            help="Project root to analyse",
-            exists=True,
-            file_okay=False,
-            resolve_path=True,
-        ),
-    ],
-    lang: Annotated[
-        str,
-        typer.Option(
-            help=(
-                "Adapter(s) to use: auto | python | typescript"
-                " | python,typescript"
-            ),
-            show_default=True,
-        ),
-    ] = "auto",
-) -> None:
-    """Print node and relation statistics for a project."""
-    langs = resolve_langs(lang, root)
-    typer.echo(f"Analysing {root}  [lang={', '.join(langs)}]\n")
-
-    graph, elapsed = run_analysis(root, langs)
+def _print_stats(graph: GraphLens, elapsed: float) -> None:
+    """Print node/relation/external/caller statistics for *graph*."""
     nodes = graph.nodes
-
     typer.echo(
         f"{len(nodes)} nodes  ·  "
         f"{len(graph.relations)} relations  ·  "
@@ -78,3 +52,76 @@ def analyze(
             n = nodes.get(nid)
             name = n.qualified_name if n else nid
             typer.echo(f"  {count:>4}  {name}")
+
+
+@app.command()
+def analyze(
+    root: Annotated[
+        Path,
+        typer.Argument(
+            help="Project root to analyse",
+            exists=True,
+            file_okay=False,
+            resolve_path=True,
+        ),
+    ],
+    lang: Annotated[
+        str,
+        typer.Option(
+            help=(
+                "Adapter(s) to use: auto | python | typescript"
+                " | python,typescript"
+            ),
+            show_default=True,
+        ),
+    ] = "auto",
+    output_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            "-f",
+            help="Output format: text (stats) or json (serialized graph)",
+        ),
+    ] = "text",
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Write the serialized graph (JSON) to this path",
+            dir_okay=False,
+            writable=True,
+        ),
+    ] = None,
+    strict: Annotated[
+        bool,
+        typer.Option(
+            "--strict",
+            help="Exit non-zero if the resolver status is not 'ok'",
+        ),
+    ] = False,
+) -> None:
+    """Analyse a project: print stats, or serialize the graph to JSON."""
+    quiet = output_format == "json" and output is None
+    langs = resolve_langs(lang, root)
+    if not quiet:
+        typer.echo(f"Analysing {root}  [lang={', '.join(langs)}]\n")
+
+    graph, elapsed = run_analysis(root, langs, verbose=not quiet)
+
+    if output is not None:
+        output.write_text(graph.to_json(indent=2), encoding="utf-8")
+        typer.echo(
+            f"Wrote graph JSON to {output}  "
+            f"({len(graph.nodes)} nodes, {len(graph.relations)} relations)"
+        )
+    elif output_format == "json":
+        typer.echo(graph.to_json(indent=2))
+    else:
+        _print_stats(graph, elapsed)
+
+    status = str(graph.metadata.get(RESOLVER_STATUS_KEY, "ok"))
+    if not quiet and status != "ok":
+        typer.echo(f"\nresolver status: {status}", err=True)
+    if strict and status != "ok":
+        raise typer.Exit(code=1)

{graphlens_cli-0.4.0 → graphlens_cli-0.5.0}/src/graphlens_cli/_app.py

@@ -6,7 +6,12 @@ import time
 from typing import TYPE_CHECKING
 
 import typer
-from graphlens import GraphLens, adapter_registry
+from graphlens import (
+    RESOLVER_STATUS_KEY,
+    GraphLens,
+    ResolverStatus,
+    adapter_registry,
+)
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -76,6 +81,14 @@ def load_adapter(lang: str) -> LanguageAdapter:
         from graphlens_typescript import TypescriptAdapter
 
         return TypescriptAdapter()
+    if lang == "go":
+        from graphlens_go import GoAdapter
+
+        return GoAdapter()
+    if lang == "rust":
+        from graphlens_rust import RustAdapter
+
+        return RustAdapter()
 
     msg = f"Unknown or unavailable adapter: {lang!r}"
     raise typer.BadParameter(msg)
@@ -98,16 +111,29 @@ def run_analysis(
 ) -> tuple[GraphLens, float]:
     """Analyse *root* with each adapter; return merged graph and elapsed."""
     combined = GraphLens()
+    statuses: list[ResolverStatus] = []
     t0 = time.monotonic()
     for lang in langs:
         if verbose:
             typer.echo(f"  [{lang}] analysing {root} …")
         adapter = load_adapter(lang)
         g = adapter.analyze(root)
+        raw_status = g.metadata.get(RESOLVER_STATUS_KEY)
+        status = (
+            ResolverStatus.OK
+            if raw_status is None
+            else ResolverStatus.from_value(
+                raw_status, default=ResolverStatus.DEGRADED
+            )
+        )
+        statuses.append(status)
         if verbose:
             typer.echo(
                 f"  [{lang}] {len(g.nodes)} nodes,"
                 f" {len(g.relations)} relations"
             )
         merge_graph(combined, g)
+    combined.metadata[RESOLVER_STATUS_KEY] = ResolverStatus.combine(
+        statuses
+    ).value
     return combined, time.monotonic() - t0

graphlens_cli-0.5.0/src/graphlens_cli/_mcp.py

@@ -0,0 +1,234 @@
+"""
+graphlens mcp — serve the graph query API to agents over MCP (TCK-7).
+
+The query logic lives in plain functions that operate on a ``GraphLens``
+so it is fully testable without the optional ``mcp`` dependency.  The
+``mcp`` package is imported lazily inside :func:`_build_server`, and the
+``mcp`` subcommand prints a friendly hint if it is not installed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from graphlens import RESOLVER_STATUS_KEY, GraphLens, NodeKind, RelationKind
+
+from graphlens_cli._app import app
+
+if TYPE_CHECKING:
+    from graphlens import Node
+
+
+def load_graph(path: Path) -> GraphLens:
+    """Load a graph from a JSON file produced by ``analyze --output``."""
+    return GraphLens.from_json(path.read_text(encoding="utf-8"))
+
+
+def _node_dict(node: Node) -> dict[str, object]:
+    return {
+        "id": node.id,
+        "kind": node.kind.value,
+        "qualified_name": node.qualified_name,
+        "name": node.name,
+        "file_path": node.file_path,
+    }
+
+
+def _resolve_ids(graph: GraphLens, node: str) -> list[str]:
+    """Resolve *node* (an id or a qualified/short name) to node ids."""
+    if node in graph.nodes:
+        return [node]
+    return [n.id for n in graph.nodes_by_name(node)]
+
+
+def graph_stats(graph: GraphLens) -> dict[str, object]:
+    """Return node/relation counts and the resolver status."""
+    nodes_by_kind: dict[str, int] = {}
+    for node in graph.nodes.values():
+        nodes_by_kind[node.kind.value] = (
+            nodes_by_kind.get(node.kind.value, 0) + 1
+        )
+    rels_by_kind: dict[str, int] = {}
+    for rel in graph.relations:
+        rels_by_kind[rel.kind.value] = rels_by_kind.get(rel.kind.value, 0) + 1
+    return {
+        "nodes": len(graph.nodes),
+        "relations": len(graph.relations),
+        "nodes_by_kind": nodes_by_kind,
+        "relations_by_kind": rels_by_kind,
+        "resolver_status": graph.metadata.get(RESOLVER_STATUS_KEY),
+    }
+
+
+def find_nodes(graph: GraphLens, name: str) -> list[dict[str, object]]:
+    """Return nodes whose short or qualified name matches *name*."""
+    return [_node_dict(n) for n in graph.nodes_by_name(name)]
+
+
+def _gather(
+    graph: GraphLens, node: str, op: str, depth: int
+) -> list[dict[str, object]]:
+    seen: dict[str, Node] = {}
+    for nid in _resolve_ids(graph, node):
+        if op == "callers":
+            results = graph.callers(nid)
+        elif op == "callees":
+            results = graph.callees(nid)
+        elif op == "references":
+            results = graph.references_to(nid)
+        else:  # neighbors
+            results = graph.neighbors(nid, depth=depth)
+        for n in results:
+            seen[n.id] = n
+    return [_node_dict(n) for n in seen.values()]
+
+
+def callers(graph: GraphLens, node: str) -> list[dict[str, object]]:
+    """Return functions/methods that call *node*."""
+    return _gather(graph, node, "callers", 1)
+
+
+def callees(graph: GraphLens, node: str) -> list[dict[str, object]]:
+    """Return functions/methods that *node* calls."""
+    return _gather(graph, node, "callees", 1)
+
+
+def references(graph: GraphLens, node: str) -> list[dict[str, object]]:
+    """Return nodes that reference *node*."""
+    return _gather(graph, node, "references", 1)
+
+
+def neighbors(
+    graph: GraphLens, node: str, depth: int = 1
+) -> list[dict[str, object]]:
+    """Return nodes within *depth* hops of *node*."""
+    return _gather(graph, node, "neighbors", depth)
+
+
+def communicates_with(graph: GraphLens) -> list[dict[str, object]]:
+    """Return cross-language ``COMMUNICATES_WITH`` edges (consumer→server)."""
+    edges: list[dict[str, object]] = []
+    for rel in graph.relations:
+        if rel.kind is not RelationKind.COMMUNICATES_WITH:
+            continue
+        source = graph.nodes.get(rel.source_id)
+        target = graph.nodes.get(rel.target_id)
+        if source is None or target is None:
+            continue  # pragma: no cover - dangling edge
+        edges.append(
+            {
+                "consumer": source.qualified_name,
+                "provider": target.qualified_name,
+                "mechanism": rel.metadata.get("mechanism"),
+                "key": rel.metadata.get("boundary_key"),
+                "confidence": rel.metadata.get("confidence"),
+            }
+        )
+    return edges
+
+
+def boundaries(graph: GraphLens) -> list[dict[str, object]]:
+    """Return all cross-language boundary contracts in the graph."""
+    return [
+        {
+            "mechanism": n.metadata.get("mechanism"),
+            "key": n.metadata.get("key"),
+            "exposed_by": [
+                graph.nodes[r.source_id].qualified_name
+                for r in graph.incoming(n.id, RelationKind.EXPOSES)
+                if r.source_id in graph.nodes
+            ],
+            "consumed_by": [
+                graph.nodes[r.source_id].qualified_name
+                for r in graph.incoming(n.id, RelationKind.CONSUMES)
+                if r.source_id in graph.nodes
+            ],
+        }
+        for n in graph.nodes_by_kind(NodeKind.BOUNDARY)
+    ]
+
+
+def _build_server(graph: GraphLens):  # noqa: ANN202  # pragma: no cover
+    """Build a FastMCP server exposing the query tools (needs ``mcp``)."""
+    from mcp.server.fastmcp import (  # ty: ignore[unresolved-import]
+        FastMCP,
+    )
+
+    server = FastMCP("graphlens")
+
+    # Typed wrappers (not lambdas) so FastMCP derives correct input schemas
+    # — e.g. ``depth`` is advertised as an int, ``node``/``name`` as strings.
+    @server.tool(name="stats")
+    def stats_tool() -> dict[str, object]:
+        """Return node/relation counts and the resolver status."""
+        return graph_stats(graph)
+
+    @server.tool(name="find")
+    def find_tool(name: str) -> list[dict[str, object]]:
+        """Find nodes whose short or qualified name matches ``name``."""
+        return find_nodes(graph, name)
+
+    @server.tool(name="callers")
+    def callers_tool(node: str) -> list[dict[str, object]]:
+        """Return functions/methods that call ``node`` (id or name)."""
+        return callers(graph, node)
+
+    @server.tool(name="callees")
+    def callees_tool(node: str) -> list[dict[str, object]]:
+        """Return functions/methods that ``node`` (id or name) calls."""
+        return callees(graph, node)
+
+    @server.tool(name="references")
+    def references_tool(node: str) -> list[dict[str, object]]:
+        """Return nodes that reference ``node`` (id or name)."""
+        return references(graph, node)
+
+    @server.tool(name="neighbors")
+    def neighbors_tool(node: str, depth: int = 1) -> list[dict[str, object]]:
+        """Return nodes within ``depth`` hops of ``node`` (id or name)."""
+        return neighbors(graph, node, depth)
+
+    @server.tool(name="communicates_with")
+    def communicates_with_tool() -> list[dict[str, object]]:
+        """Return cross-language ``COMMUNICATES_WITH`` edges."""
+        return communicates_with(graph)
+
+    @server.tool(name="boundaries")
+    def boundaries_tool() -> list[dict[str, object]]:
+        """Return all cross-language boundary contracts in the graph."""
+        return boundaries(graph)
+
+    return server
+
+
+def serve(graph_path: Path) -> None:  # pragma: no cover - stdio server loop
+    """Load the graph and run the MCP server over stdio."""
+    _build_server(load_graph(graph_path)).run()
+
+
+@app.command("mcp")
+def mcp_command(
+    graph_path: Annotated[
+        Path,
+        typer.Option(
+            "--graph",
+            "-g",
+            help="Path to a graph JSON file (from `analyze --output`)",
+            exists=True,
+            dir_okay=False,
+        ),
+    ],
+) -> None:
+    """Serve the graph query API to agents over MCP (stdio)."""
+    try:
+        import mcp  # noqa: F401  # ty: ignore[unresolved-import]
+    except ImportError as exc:
+        typer.echo(
+            "MCP support requires the 'mcp' package. Install it with:\n"
+            "  pip install 'graphlens-cli[mcp]'",
+            err=True,
+        )
+        raise typer.Exit(code=1) from exc
+    serve(graph_path)  # pragma: no cover - requires mcp

graphlens_cli-0.5.0/src/graphlens_cli/_query.py

@@ -0,0 +1,83 @@
+"""graphlens query — query a previously serialized graph JSON."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from graphlens import GraphLens
+
+from graphlens_cli._app import app
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from graphlens import Node
+
+_OPERATIONS = ("callers", "callees", "references", "neighbors")
+
+
+def _resolve_ids(graph: GraphLens, node: str) -> list[str]:
+    """Resolve *node* (an id or a qualified/short name) to node ids."""
+    if node in graph.nodes:
+        return [node]
+    return [n.id for n in graph.nodes_by_name(node)]
+
+
+@app.command()
+def query(
+    node: Annotated[
+        str,
+        typer.Argument(help="Node id, qualified name, or short name"),
+    ],
+    graph_path: Annotated[
+        Path,
+        typer.Option(
+            "--graph",
+            "-g",
+            help="Path to a graph JSON file (from `analyze --output`)",
+            exists=True,
+            dir_okay=False,
+        ),
+    ],
+    operation: Annotated[
+        str,
+        typer.Option(
+            "--op",
+            help="callers | callees | references | neighbors",
+        ),
+    ] = "callers",
+    depth: Annotated[
+        int,
+        typer.Option(help="Hop depth for the 'neighbors' operation"),
+    ] = 1,
+) -> None:
+    """Query a saved graph for relationships of a node."""
+    if operation not in _OPERATIONS:
+        msg = f"operation must be one of {', '.join(_OPERATIONS)}"
+        raise typer.BadParameter(msg)
+
+    graph = GraphLens.from_json(graph_path.read_text(encoding="utf-8"))
+    ids = _resolve_ids(graph, node)
+    if not ids:
+        typer.echo(f"No node matching {node!r}", err=True)
+        raise typer.Exit(code=1)
+
+    ops: dict[str, Callable[[str], list[Node]]] = {
+        "callers": graph.callers,
+        "callees": graph.callees,
+        "references": graph.references_to,
+    }
+    for nid in ids:
+        src = graph.nodes[nid]
+        results = (
+            graph.neighbors(nid, depth=depth)
+            if operation == "neighbors"
+            else ops[operation](nid)
+        )
+        typer.echo(f"{operation} of {src.qualified_name} ({src.kind.value}):")
+        for r in results:
+            typer.echo(f"  {r.kind.value:<16} {r.qualified_name}")
+        if not results:
+            typer.echo("  (none)")