ctxgraph-code 0.1.2__tar.gz → 0.2.0__tar.gz

{ctxgraph_code-0.1.2 → ctxgraph_code-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxgraph-code
-Version: 0.1.2
+Version: 0.2.0
 Summary: Code knowledge graph for Claude Code. Build a relationship graph of your Python codebase and query it during coding sessions.
 Author: ctxgraph-code contributors
 License: MIT
@@ -165,13 +165,17 @@ Generates a focused context summary: relevant files, their symbols, and dependen
 ### `view`
 
 ```bash
-ctxgraph-code view
-ctxgraph-code view --output tree.txt
+ctxgraph-code view                 # generates interactive D3.js HTML and opens browser
+ctxgraph-code view --no-open       # generate HTML without opening browser
+ctxgraph-code view --tree          # show text tree instead (useful in terminal)
+ctxgraph-code view --output graph.html  # save to custom path
 ```
 
-Prints a hierarchical directory tree from the graph showing every file and its symbols (classes marked `[C]`, functions/methods marked `[M]`). Also lists import and call edges at the bottom.
+Opens an **interactive D3.js force-directed graph** in the browser. Drag nodes, zoom/pan, search by name, filter by type (File/Class/Function). Hover to highlight connected nodes and see summaries.
 
-Useful for a quick visual scan of the project structure without reading every file.
+The HTML is self-contained (loads D3.js from CDN) and saved to `.ctxgraph/graph.html`.
+
+Use `--tree` for a terminal-friendly text view of the directory hierarchy with symbols and edges.
 
 ### `info`
 
@@ -286,7 +290,7 @@ Built-in default exclusion patterns (always applied): `__pycache__`, `*.pyc`, `.
 | CLI commands | 9 (build, capsule, query, view, serve, info, init, ask, chat, history, skill) | 9 (init, build, query, deps, usedby, overview, symbols, context, setup, view, info) |
 | LLM integration | Built-in (Ollama, Claude, OpenAI, Azure) | None (delegates to Claude Code) |
 | Chat sessions | Yes | No |
-| Visualizer | D3.js HTML + SVG | Text tree (`view` command) |
+| Visualizer | D3.js HTML + SVG | D3.js HTML (`view` opens in browser, `--tree` for text) |
 | Skills system | Yes (customizable skill TOML files) | No |
 | MCP server | Yes | No |
 | Token savings | Yes (capsule DSL compression) | No |

{ctxgraph_code-0.1.2 → ctxgraph_code-0.2.0}/README.md

@@ -142,13 +142,17 @@ Generates a focused context summary: relevant files, their symbols, and dependen
 ### `view`
 
 ```bash
-ctxgraph-code view
-ctxgraph-code view --output tree.txt
+ctxgraph-code view                 # generates interactive D3.js HTML and opens browser
+ctxgraph-code view --no-open       # generate HTML without opening browser
+ctxgraph-code view --tree          # show text tree instead (useful in terminal)
+ctxgraph-code view --output graph.html  # save to custom path
 ```
 
-Prints a hierarchical directory tree from the graph showing every file and its symbols (classes marked `[C]`, functions/methods marked `[M]`). Also lists import and call edges at the bottom.
+Opens an **interactive D3.js force-directed graph** in the browser. Drag nodes, zoom/pan, search by name, filter by type (File/Class/Function). Hover to highlight connected nodes and see summaries.
 
-Useful for a quick visual scan of the project structure without reading every file.
+The HTML is self-contained (loads D3.js from CDN) and saved to `.ctxgraph/graph.html`.
+
+Use `--tree` for a terminal-friendly text view of the directory hierarchy with symbols and edges.
 
 ### `info`
 
@@ -263,7 +267,7 @@ Built-in default exclusion patterns (always applied): `__pycache__`, `*.pyc`, `.
 | CLI commands | 9 (build, capsule, query, view, serve, info, init, ask, chat, history, skill) | 9 (init, build, query, deps, usedby, overview, symbols, context, setup, view, info) |
 | LLM integration | Built-in (Ollama, Claude, OpenAI, Azure) | None (delegates to Claude Code) |
 | Chat sessions | Yes | No |
-| Visualizer | D3.js HTML + SVG | Text tree (`view` command) |
+| Visualizer | D3.js HTML + SVG | D3.js HTML (`view` opens in browser, `--tree` for text) |
 | Skills system | Yes (customizable skill TOML files) | No |
 | MCP server | Yes | No |
 | Token savings | Yes (capsule DSL compression) | No |

{ctxgraph_code-0.1.2 → ctxgraph_code-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ctxgraph-code"
-version = "0.1.2"
+version = "0.2.0"
 description = "Code knowledge graph for Claude Code. Build a relationship graph of your Python codebase and query it during coding sessions."
 readme = "README.md"
 license = {text = "MIT"}

{ctxgraph_code-0.1.2 → ctxgraph_code-0.2.0}/src/ctxgraph_code/analyzers/python/importer.py

@@ -4,90 +4,99 @@ import ast
 from pathlib import Path
 from typing import Optional
 
-from ctxgraph_code.graph.models import Edge, Graph, Node
-
-
-def analyze_imports(file_path: Path, root_path: Path) -> Graph:
-    graph = Graph()
+from ctxgraph_code.graph.models import Graph
+
+
+def analyze_imports(
+    file_path: Path,
+    root_path: Path,
+    *,
+    tree: Optional[ast.AST] = None,
+    path_index: Optional[set[str]] = None,
+) -> Graph:
+    # Result containers (not full Graph — caller merges)
+    nodes: list[dict] = []
+    edges: list[dict] = []
     rel_path = _relative_path(file_path, root_path)
     file_node_id = f"file:{rel_path}"
 
-    graph.add_node(
-        Node(
-            id=file_node_id,
-            type="file",
-            name=file_path.name,
-            path=rel_path,
-            summary=None,
-            importance=0.5,
-            size_bytes=file_path.stat().st_size,
-        )
-    )
-
-    try:
-        tree = ast.parse(file_path.read_text(encoding="utf-8", errors="replace"))
-    except SyntaxError:
-        return graph
+    nodes.append(dict(
+        id=file_node_id,
+        type="file",
+        name=file_path.name,
+        path=rel_path,
+        summary=None,
+        importance=0.5,
+        size_bytes=file_path.stat().st_size,
+    ))
+
+    if tree is None:
+        try:
+            tree = ast.parse(file_path.read_text(encoding="utf-8", errors="replace"))
+        except SyntaxError:
+            return Graph.from_batch(nodes, edges)
 
     for node in ast.walk(tree):
         if isinstance(node, ast.Import):
             for alias in node.names:
-                target = _resolve_import_target(alias.name, root_path)
+                target = _resolve_import_target(alias.name, root_path, path_index)
                 if target:
-                    _add_import_edge(graph, rel_path, file_node_id, target, alias.name)
+                    _add_import_edge(nodes, edges, rel_path, file_node_id, target, alias.name)
 
         elif isinstance(node, ast.ImportFrom):
             if node.module is None:
                 continue
             if node.level and node.level > 0:
                 target = _resolve_relative_import(
-                    node.module, node.level, rel_path, root_path
+                    node.module, node.level, rel_path, root_path, path_index
                 )
             else:
-                target = _resolve_import_target(node.module, root_path)
+                target = _resolve_import_target(node.module, root_path, path_index)
 
             if target:
                 for alias in node.names:
                     symbol_name = alias.asname or alias.name
                     edge_label = f"{node.module}.{alias.name}"
                     _add_import_edge(
-                        graph, rel_path, file_node_id, target, edge_label
+                        nodes, edges, rel_path, file_node_id, target, edge_label
                     )
 
-    return graph
+    return Graph.from_batch(nodes, edges)
 
 
 def _add_import_edge(
-    graph: Graph,
+    nodes: list[dict],
+    edges: list[dict],
     source_rel: str,
     source_id: str,
     target_rel: str,
     label: str,
 ):
     target_id = f"file:{target_rel}"
-    if target_id not in graph.nodes:
-        graph.add_node(
-            Node(
-                id=target_id,
-                type="file",
-                name=Path(target_rel).name,
-                path=target_rel,
-                summary=None,
-                importance=0.3,
-                size_bytes=0,
-            )
-        )
-    graph.add_edge(
-        Edge(
-            source_id=source_id,
-            target_id=target_id,
-            relation="imports",
-            weight=1.0,
-        )
-    )
-
-
-def _resolve_import_target(module_name: str, root_path: Path) -> Optional[str]:
+    # Check if target node already in our batch list
+    if not any(n["id"] == target_id for n in nodes):
+        nodes.append(dict(
+            id=target_id,
+            type="file",
+            name=Path(target_rel).name,
+            path=target_rel,
+            summary=None,
+            importance=0.3,
+            size_bytes=0,
+        ))
+    edges.append(dict(
+        source_id=source_id,
+        target_id=target_id,
+        relation="imports",
+        weight=1.0,
+    ))
+
+
+def _resolve_import_target(
+    module_name: str,
+    root_path: Path,
+    path_index: Optional[set[str]] = None,
+) -> Optional[str]:
     package_path = module_name.replace(".", "/")
     root_name = root_path.name
     extensions = [".py", ".pyw"]
@@ -100,16 +109,20 @@ def _resolve_import_target(module_name: str, root_path: Path) -> Optional[str]:
     for base in candidates:
         for ext in extensions:
             candidate = f"{base}{ext}"
-            if _exists_in_project(candidate, root_path):
+            if _exists_in_project(candidate, root_path, path_index):
                 return candidate
             init_candidate = f"{base}/__init__{ext}"
-            if _exists_in_project(init_candidate, root_path):
+            if _exists_in_project(init_candidate, root_path, path_index):
                 return init_candidate
     return None
 
 
 def _resolve_relative_import(
-    module_name: str, level: int, source_rel: str, root_path: Path
+    module_name: str,
+    level: int,
+    source_rel: str,
+    root_path: Path,
+    path_index: Optional[set[str]] = None,
 ) -> Optional[str]:
     parts = Path(source_rel).parts
     if level > len(parts):
@@ -120,15 +133,21 @@ def _resolve_relative_import(
     extensions = [".py", ".pyw"]
     for ext in extensions:
         candidate = f"{base}{ext}"
-        if _exists_in_project(candidate, root_path):
+        if _exists_in_project(candidate, root_path, path_index):
             return candidate
         init_candidate = f"{base}/__init__{ext}"
-        if _exists_in_project(init_candidate, root_path):
+        if _exists_in_project(init_candidate, root_path, path_index):
             return init_candidate
     return None
 
 
-def _exists_in_project(candidate_path: str, root_path: Path) -> bool:
+def _exists_in_project(
+    candidate_path: str,
+    root_path: Path,
+    path_index: Optional[set[str]] = None,
+) -> bool:
+    if path_index is not None:
+        return candidate_path in path_index
     full = root_path / candidate_path
     return full.exists()
 

{ctxgraph_code-0.1.2 → ctxgraph_code-0.2.0}/src/ctxgraph_code/analyzers/python/semantic.py

@@ -2,19 +2,27 @@ from __future__ import annotations
 
 import ast
 from pathlib import Path
+from typing import Optional
 
 from ctxgraph_code.graph.models import Node
 
 
-def enrich_node_summary(node: Node, file_path: Path) -> str:
+def enrich_node_summary(
+    node: Node,
+    file_path: Path,
+    *,
+    source: Optional[str] = None,
+    tree: Optional[ast.AST] = None,
+) -> str:
     if node.summary:
         return node.summary
 
-    try:
-        source = file_path.read_text(encoding="utf-8", errors="replace")
-        tree = ast.parse(source)
-    except (SyntaxError, FileNotFoundError):
-        return node.summary or ""
+    if tree is None:
+        try:
+            source = file_path.read_text(encoding="utf-8", errors="replace")
+            tree = ast.parse(source)
+        except (SyntaxError, FileNotFoundError):
+            return node.summary or ""
 
     if node.type == "file":
         return _summarize_file(tree, file_path)

ctxgraph_code-0.2.0/src/ctxgraph_code/analyzers/python/symbols.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Optional
+
+from ctxgraph_code.graph.models import Graph
+
+
+def analyze_symbols(
+    file_path: Path,
+    root_path: Path,
+    *,
+    source: Optional[str] = None,
+    tree: Optional[ast.AST] = None,
+) -> Graph:
+    rel_path = _relative_path(file_path, root_path)
+    file_node_id = f"file:{rel_path}"
+
+    if tree is None:
+        try:
+            source = file_path.read_text(encoding="utf-8", errors="replace")
+            tree = ast.parse(source)
+        except SyntaxError:
+            return Graph()
+
+    lines = source.split("\n") if source else []
+    nodes: list[dict] = []
+    edges: list[dict] = []
+
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.ClassDef):
+            _process_class(node, nodes, edges, file_node_id, rel_path, lines)
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            _process_function(node, nodes, edges, file_node_id, rel_path, lines)
+
+    _process_calls(tree, nodes, edges, rel_path)
+
+    return Graph.from_batch(nodes, edges)
+
+
+# ── helpers ─────────────────────────────────────────────────────────────────
+
+
+def _node_dict(**kw) -> dict:
+    return dict(kw)
+
+
+def _edge_dict(**kw) -> dict:
+    return dict(kw)
+
+
+def _process_class(
+    node: ast.ClassDef,
+    nodes: list[dict],
+    edges: list[dict],
+    file_node_id: str,
+    rel_path: str,
+    lines: list[str],
+):
+    class_id = f"class:{rel_path}::{node.name}"
+    summary = _extract_docstring(node)
+    bases = _get_base_names(node)
+
+    nodes.append(_node_dict(
+        id=class_id,
+        type="class",
+        name=node.name,
+        path=rel_path,
+        parent_id=file_node_id,
+        summary=summary,
+        importance=0.6,
+        lineno=node.lineno,
+    ))
+    edges.append(_edge_dict(
+        source_id=file_node_id,
+        target_id=class_id,
+        relation="defines",
+        weight=1.0,
+    ))
+
+    for base in bases:
+        edges.append(_edge_dict(
+            source_id=class_id,
+            target_id=base,
+            relation="extends",
+            weight=0.8,
+        ))
+
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            _process_method(child, nodes, edges, class_id, rel_path, lines)
+
+
+def _process_function(
+    node: (ast.FunctionDef | ast.AsyncFunctionDef),
+    nodes: list[dict],
+    edges: list[dict],
+    file_node_id: str,
+    rel_path: str,
+    lines: list[str],
+):
+    func_id = f"func:{rel_path}::{node.name}"
+    summary = _extract_docstring(node)
+
+    nodes.append(_node_dict(
+        id=func_id,
+        type="function",
+        name=node.name,
+        path=rel_path,
+        parent_id=file_node_id,
+        summary=summary,
+        importance=0.5,
+        lineno=node.lineno,
+    ))
+    edges.append(_edge_dict(
+        source_id=file_node_id,
+        target_id=func_id,
+        relation="defines",
+        weight=1.0,
+    ))
+
+
+def _process_method(
+    node: (ast.FunctionDef | ast.AsyncFunctionDef),
+    nodes: list[dict],
+    edges: list[dict],
+    class_id: str,
+    rel_path: str,
+    lines: list[str],
+):
+    method_id = f"func:{rel_path}::{node.name}"
+    summary = _extract_docstring(node)
+
+    nodes.append(_node_dict(
+        id=method_id,
+        type="function",
+        name=node.name,
+        path=rel_path,
+        parent_id=class_id,
+        summary=summary,
+        importance=0.5,
+        lineno=node.lineno,
+    ))
+    edges.append(_edge_dict(
+        source_id=class_id,
+        target_id=method_id,
+        relation="defines",
+        weight=1.0,
+    ))
+
+
+def _process_calls(tree: ast.AST, nodes: list[dict], edges: list[dict], rel_path: str):
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            func_name = _get_call_name(node.func)
+            if func_name:
+                caller_id = _find_enclosing_symbol(tree, node, rel_path)
+                if caller_id:
+                    callee_id = _find_target_node(func_name, nodes)
+                    if callee_id:
+                        edges.append(_edge_dict(
+                            source_id=caller_id,
+                            target_id=callee_id,
+                            relation="calls",
+                            weight=0.7,
+                        ))
+
+
+def _get_call_name(node: ast.AST) -> Optional[str]:
+    if isinstance(node, ast.Name):
+        return node.id
+    elif isinstance(node, ast.Attribute):
+        return node.attr
+    return None
+
+
+def _find_enclosing_symbol(
+    tree: ast.AST, target_node: ast.AST, rel_path: str
+) -> Optional[str]:
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if _contains_node(node, target_node):
+                return f"func:{rel_path}::{node.name}"
+        elif isinstance(node, ast.ClassDef):
+            for child in ast.iter_child_nodes(node):
+                if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    if _contains_node(child, target_node):
+                        return f"func:{rel_path}::{child.name}"
+    return None
+
+
+def _contains_node(container: ast.AST, target: ast.AST) -> bool:
+    for node in ast.walk(container):
+        if node is target:
+            return True
+    return False
+
+
+def _find_target_node(name: str, nodes: list[dict]) -> Optional[str]:
+    for nd in nodes:
+        if nd.get("type") in ("function", "class") and nd["name"] == name:
+            return nd["id"]
+    return None
+
+
+def _extract_docstring(node: ast.AST) -> Optional[str]:
+    if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+        doc = ast.get_docstring(node)
+        if doc:
+            return doc.split("\n\n")[0][:200]
+    return None
+
+
+def _get_base_names(node: ast.ClassDef) -> list[str]:
+    bases = []
+    for base in node.bases:
+        if isinstance(base, ast.Name):
+            bases.append(f"class:{base.id}")
+    return bases
+
+
+def _relative_path(file_path: Path, root_path: Path) -> str:
+    try:
+        return str(file_path.relative_to(root_path)).replace("\\", "/")
+    except ValueError:
+        return file_path.name